Record agreed CommandKit command organization
This commit is contained in:
@@ -45,6 +45,65 @@ inspection and early pipeline dependency checks remain separate feature work
|
|||||||
using an eventual Scriptorium external contract. CommandKit adoption can
|
using an eventual Scriptorium external contract. CommandKit adoption can
|
||||||
proceed independently.
|
proceed independently.
|
||||||
|
|
||||||
|
### Command organization
|
||||||
|
|
||||||
|
Use one general execution command, one regeneration convenience, and command
|
||||||
|
families for session operations and configuration:
|
||||||
|
|
||||||
|
```text
|
||||||
|
narratio
|
||||||
|
├── run SESSION
|
||||||
|
├── regenerate-artifacts SESSION
|
||||||
|
├── session
|
||||||
|
│ ├── init SESSION
|
||||||
|
│ ├── plan SESSION
|
||||||
|
│ ├── validate SESSION
|
||||||
|
│ ├── status SESSION
|
||||||
|
│ ├── restore SESSION
|
||||||
|
│ ├── clean [SESSION | --all]
|
||||||
|
│ ├── artifacts SESSION
|
||||||
|
│ └── locks
|
||||||
|
│ ├── list SESSION
|
||||||
|
│ ├── add SESSION SOURCE
|
||||||
|
│ └── remove SESSION SOURCE
|
||||||
|
├── config
|
||||||
|
│ ├── scopes
|
||||||
|
│ ├── validate
|
||||||
|
│ ├── show
|
||||||
|
│ ├── sources
|
||||||
|
│ ├── explain
|
||||||
|
│ ├── diff
|
||||||
|
│ └── artifacts
|
||||||
|
├── version
|
||||||
|
├── completion
|
||||||
|
└── help
|
||||||
|
```
|
||||||
|
|
||||||
|
`run SESSION` selects the full pipeline by default. `--from` and `--through`
|
||||||
|
select an inclusive contiguous range. Add `--stage` for one stage, mutually
|
||||||
|
exclusive with the range selectors; it selects the same stage as both endpoints.
|
||||||
|
`--force` independently requests forced execution. `session plan` accepts the
|
||||||
|
same execution-selection options, including stage/range, force, and artifacts.
|
||||||
|
|
||||||
|
Use positional session IDs on session-oriented commands and remove their
|
||||||
|
duplicate `--session-id` spelling. Campaign and configuration selection remain
|
||||||
|
flags. Configuration inspection selectors will be settled with scope design.
|
||||||
|
|
||||||
|
Remove `run-stage`, `analyze`, and `publish`. Single-stage execution uses
|
||||||
|
`run --stage`; forced regeneration adds `--force` explicitly. Move top-level
|
||||||
|
`clean` to `session clean`. Use the explicit `session locks list` operation so
|
||||||
|
the bare locks group displays native help.
|
||||||
|
|
||||||
|
Keep `regenerate-artifacts` as an application-owned command sharing execution
|
||||||
|
logic. Its useful domain intent is forced extraction through analysis without
|
||||||
|
publication. It regenerates the complete configured extraction bundle;
|
||||||
|
`--artifacts` selects analysis targets and their required prerequisites, not
|
||||||
|
extraction lanes. The command name makes regeneration explicit.
|
||||||
|
|
||||||
|
`config artifacts` remains a Narratio-specific catalog alongside the standard
|
||||||
|
ckconfig operations. Its final placement and view will be confirmed with the
|
||||||
|
configuration scope discussion.
|
||||||
|
|
||||||
## Reviewed upstream baseline
|
## Reviewed upstream baseline
|
||||||
|
|
||||||
The initial review covered these released modules:
|
The initial review covered these released modules:
|
||||||
@@ -72,19 +131,7 @@ baseline. They remain current-behavior documents until the migration lands.
|
|||||||
|
|
||||||
## Open decisions
|
## Open decisions
|
||||||
|
|
||||||
### 1. Domain command organization
|
### Configuration scopes and views
|
||||||
|
|
||||||
Which commands and conveniences should the native CLI expose? Review `run`,
|
|
||||||
`run-stage`, `analyze`, `publish`, `regenerate-artifacts`, `clean`, and the
|
|
||||||
`session` family for operator usefulness. Decide how session IDs, stage bounds,
|
|
||||||
and artifact selections should be expressed using native typed inputs.
|
|
||||||
|
|
||||||
CommandKit aliases redirect command paths; they do not inject flags or
|
|
||||||
operands. Retained conveniences that select a stage or force a range therefore
|
|
||||||
need application-owned commands sharing domain execution logic. Decide which
|
|
||||||
are worth keeping on that basis, without a compatibility requirement.
|
|
||||||
|
|
||||||
### 2. Configuration scopes and views
|
|
||||||
|
|
||||||
Which named scopes should be available initially: one effective pipeline scope,
|
Which named scopes should be available initially: one effective pipeline scope,
|
||||||
or also campaign, session, and party scopes? Define the selectors and acquisition
|
or also campaign, session, and party scopes? Define the selectors and acquisition
|
||||||
@@ -102,7 +149,7 @@ application-specific artifact catalog. Decide the catalog's placement and how
|
|||||||
campaign and party context participate in comparisons, including independent
|
campaign and party context participate in comparisons, including independent
|
||||||
left and right selectors.
|
left and right selectors.
|
||||||
|
|
||||||
### 3. Optional configuration capabilities
|
### Optional configuration capabilities
|
||||||
|
|
||||||
Determine the useful scope of path-selected show, path explanation, detailed
|
Determine the useful scope of path-selected show, path explanation, detailed
|
||||||
validation findings, comparison details/check mode, and temporary `--set`
|
validation findings, comparison details/check mode, and temporary `--set`
|
||||||
@@ -115,7 +162,7 @@ ability to parse an override does not establish Narratio's intended loading
|
|||||||
contract. Avoid an inspection result that purports to describe execution while
|
contract. Avoid an inspection result that purports to describe execution while
|
||||||
silently using different resolution rules.
|
silently using different resolution rules.
|
||||||
|
|
||||||
### 4. Reports and machine-readable output
|
### Reports and machine-readable output
|
||||||
|
|
||||||
Design useful report values for planning, status, artifact inventories,
|
Design useful report values for planning, status, artifact inventories,
|
||||||
validation, restore, cleanup, and execution summaries. Apply native text, YAML,
|
validation, restore, cleanup, and execution summaries. Apply native text, YAML,
|
||||||
@@ -128,7 +175,7 @@ results from diagnostic/progress messages. Decide what stability Narratio will
|
|||||||
promise for application-owned report fields; do not accidentally make durable
|
promise for application-owned report fields; do not accidentally make durable
|
||||||
manifest schemas the CLI response contract.
|
manifest schemas the CLI response contract.
|
||||||
|
|
||||||
### 5. Diagnostics and invocation lifecycle
|
### Diagnostics and invocation lifecycle
|
||||||
|
|
||||||
Classify existing messages into CommandKit's result, failure, warning,
|
Classify existing messages into CommandKit's result, failure, warning,
|
||||||
information, progress, and debug categories. Use native visibility rules,
|
information, progress, and debug categories. Use native visibility rules,
|
||||||
@@ -146,7 +193,7 @@ Completion can suggest commands, static values such as stage names, and
|
|||||||
filesystem paths. Decide which declarations receive those hints; dynamic
|
filesystem paths. Decide which declarations receive those hints; dynamic
|
||||||
campaign/artifact discovery would need a separately supported capability.
|
campaign/artifact discovery would need a separately supported capability.
|
||||||
|
|
||||||
### 6. Delivery and migration guidance
|
### Delivery and migration guidance
|
||||||
|
|
||||||
Choose implementation work units that lead to one complete native cutover.
|
Choose implementation work units that lead to one complete native cutover.
|
||||||
Intermediate development steps need not become a supported dual CLI.
|
Intermediate development steps need not become a supported dual CLI.
|
||||||
@@ -176,6 +223,15 @@ provide release migration guidance, and treat existing CLI compatibility as a
|
|||||||
non-goal. This settles the earlier question of whether to preserve legacy CLI
|
non-goal. This settles the earlier question of whether to preserve legacy CLI
|
||||||
conventions.
|
conventions.
|
||||||
|
|
||||||
|
### 2026-11-19 — Command organization agreed
|
||||||
|
|
||||||
|
Accepted the proposed command tree, `run --stage` selector, positional session
|
||||||
|
IDs, shared selection syntax for planning, explicit lock listing, and movement
|
||||||
|
of cleanup under `session`. Removed the separate single-stage and implicitly
|
||||||
|
forced analysis/publication commands from the target CLI. Retained
|
||||||
|
`regenerate-artifacts` because it expresses a useful multi-stage regeneration
|
||||||
|
workflow. Configuration scopes and views are the next discussion topic.
|
||||||
|
|
||||||
### Continuing the discussion
|
### Continuing the discussion
|
||||||
|
|
||||||
For each topic, record the question, the agreed outcome, its rationale, and any
|
For each topic, record the question, the agreed outcome, its rationale, and any
|
||||||
|
|||||||
Reference in New Issue
Block a user