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
|
||||
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
|
||||
|
||||
The initial review covered these released modules:
|
||||
@@ -72,19 +131,7 @@ baseline. They remain current-behavior documents until the migration lands.
|
||||
|
||||
## Open decisions
|
||||
|
||||
### 1. Domain command organization
|
||||
|
||||
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
|
||||
### Configuration scopes and views
|
||||
|
||||
Which named scopes should be available initially: one effective pipeline scope,
|
||||
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
|
||||
left and right selectors.
|
||||
|
||||
### 3. Optional configuration capabilities
|
||||
### Optional configuration capabilities
|
||||
|
||||
Determine the useful scope of path-selected show, path explanation, detailed
|
||||
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
|
||||
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,
|
||||
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
|
||||
manifest schemas the CLI response contract.
|
||||
|
||||
### 5. Diagnostics and invocation lifecycle
|
||||
### Diagnostics and invocation lifecycle
|
||||
|
||||
Classify existing messages into CommandKit's result, failure, warning,
|
||||
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
|
||||
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.
|
||||
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
|
||||
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
|
||||
|
||||
For each topic, record the question, the agreed outcome, its rationale, and any
|
||||
|
||||
Reference in New Issue
Block a user