Consolidate the CommandKit adoption roadmap
This commit is contained in:
370
docs/roadmap/commandkit.md
Normal file
370
docs/roadmap/commandkit.md
Normal file
@@ -0,0 +1,370 @@
|
||||
# CommandKit Adoption
|
||||
|
||||
Status: agreed target; implementation pending.
|
||||
|
||||
This roadmap consolidates the [migration discussion](commandkit-notepad.md).
|
||||
It defines the intended end state and required work. Detailed implementation
|
||||
sequencing belongs in a subsequent plan.
|
||||
|
||||
## Objective And Scope
|
||||
|
||||
Make Narratio a CommandKit-native application, adopting upstream command,
|
||||
configuration-inspection, reporting, and invocation conventions. Deliver one
|
||||
complete cutover. Backward compatibility with the existing CLI is a non-goal;
|
||||
release documentation will explain the migration.
|
||||
|
||||
Adopt `go.maximumdirect.net/commandkit` v0.7.0 and
|
||||
`go.maximumdirect.net/ckconfig` v0.9.0 as the initial baseline. They fit Narratio's
|
||||
existing ConfigKit v1.2.1 and Go 1.27.0 minimum. Review relevant public contract
|
||||
changes before deliberately selecting later releases.
|
||||
|
||||
Preserve consequential pipeline behavior: canonical stage sequencing, semantic
|
||||
resume evidence, publication boundaries, restore safety, and cleanup rules.
|
||||
Changes needed for the agreed configuration ownership, CLI, reports, and
|
||||
cancellation behavior are in scope.
|
||||
|
||||
## Current Baseline
|
||||
|
||||
The [CLI reference](../cli.md), [configuration internals](../internal/configuration.md),
|
||||
and [internal overview](../internal/overview.md) describe the implementation.
|
||||
The migration starts from these differences:
|
||||
|
||||
- `internal/app` owns handwritten routing, flag parsing, help, output, and exit
|
||||
handling. CommandKit and ckconfig are not dependencies yet.
|
||||
- ConfigKit already loads configuration, but subsequent campaign/session
|
||||
composition and artifact-family expansion modify runtime configuration.
|
||||
Expansion adds concrete artifacts and publish rules to the pipeline object.
|
||||
- Show and diff use a safe final-domain projection frozen as a separate native
|
||||
result; provenance comes from retained authoring results. App inspection
|
||||
acquires campaign/party context for expansion, and comparisons require the
|
||||
same campaign.
|
||||
- Session selection and operations exist, but their CLI wiring needs the agreed
|
||||
identity/file distinction, native scopes, and explicit party-file selection.
|
||||
- The command dispatcher starts with `context.Background()`. The runner releases
|
||||
locks on failure, but stage failures return no run summary and bypass its
|
||||
successful finalization path. Signal propagation, partial reporting, and
|
||||
terminal persistence need coordinated changes.
|
||||
|
||||
Consumer probes against the selected upstream releases confirmed native scope
|
||||
inspection, app-only overrides, independent comparisons, and lazy acquisition.
|
||||
Two upstream limits are already accommodated: the generated `config` group
|
||||
cannot accept Narratio subcommands, and execution commands have no reusable
|
||||
override binding. The design uses a separate `artifacts` family and defers
|
||||
execution overrides. Neither limitation blocks adoption.
|
||||
|
||||
## Target Behavior
|
||||
|
||||
### Ownership And Configuration Handoff
|
||||
|
||||
Follow [ADR 0003](../adr/0003-assign-configuration-ownership.md): ConfigKit owns
|
||||
configuration through the completed handoff; Narratio consumes it without
|
||||
mutation and derives domain objects; CommandKit and ckconfig own CLI mechanics
|
||||
and native inspection.
|
||||
|
||||
Supply schemas, defaults, configuration validation, and genuine resolution
|
||||
rules through ConfigKit's supported lifecycle. Applicable campaign defaults for
|
||||
session configuration complete there. Native inspection uses the actual result,
|
||||
including its values, provenance, history, and validation evidence.
|
||||
|
||||
Derive party/player projections, concrete artifact catalogs, execution plans,
|
||||
and publication actions as separate domain products. Keep their validation in
|
||||
the appropriate domain operation. Do not put these products back into the
|
||||
configuration, manufacture inspection evidence for them, or move domain work
|
||||
into configuration callbacks merely to include it in `config show`.
|
||||
|
||||
Safe persisted configuration and domain records may continue serving preparation
|
||||
and resume. They do not replace the native inspection result. Resume remains
|
||||
based on result-affecting semantic evidence, not configuration provenance or a
|
||||
blanket effective-digest cache key.
|
||||
|
||||
### Command Organization
|
||||
|
||||
```text
|
||||
narratio
|
||||
├── run SESSION
|
||||
├── artifacts
|
||||
│ ├── list
|
||||
│ └── regenerate 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
|
||||
├── version
|
||||
├── completion
|
||||
└── help
|
||||
```
|
||||
|
||||
`run SESSION` selects the full pipeline by default. `--from` and `--through`
|
||||
select an inclusive contiguous range. `--stage` selects one stage and is mutually
|
||||
exclusive with range selectors. `--force` is independent. `session plan` accepts
|
||||
the same stage/range, force, and artifact selections.
|
||||
|
||||
`artifacts regenerate SESSION` forces extraction through analysis without
|
||||
publication, sharing execution logic with `run`. It regenerates the complete
|
||||
configured extraction bundle; `--artifacts` selects analysis targets and their
|
||||
prerequisites, not extraction lanes.
|
||||
|
||||
`artifacts list` reports configured definitions, producers, and dependencies,
|
||||
including family members derived from the selected pipeline, campaign, and
|
||||
party. `session artifacts SESSION` reports availability and publication state.
|
||||
Planning exposes derived execution and publication work. These are domain views,
|
||||
separate from native configuration inspection.
|
||||
|
||||
Remove `run-stage`, `analyze`, and `publish`; single-stage work uses
|
||||
`run --stage`, adding `--force` when requested. Move top-level `clean` to
|
||||
`session clean` and `regenerate-artifacts` to `artifacts regenerate`.
|
||||
Replace `config artifacts` with `artifacts list`. Use explicit `session locks list`.
|
||||
Bare command groups display native help. Do not retain compatibility aliases or
|
||||
duplicate `--session-id` flags for positional session arguments.
|
||||
|
||||
### Configuration Scopes And Selection
|
||||
|
||||
Expose four native ckconfig scopes, with `app` as the default:
|
||||
|
||||
| Scope | Configuration inspected |
|
||||
| --- | --- |
|
||||
| `app` | Resolved application/pipeline configuration |
|
||||
| `campaign` | Selected campaign settings |
|
||||
| `session` | Selected session settings, including applicable configuration defaults |
|
||||
| `party` | Party configuration selected explicitly or through the campaign default |
|
||||
|
||||
Enable applicable native show, path selection/discovery, sources, explanation
|
||||
and history, validation findings and filters, and detailed comparison. Filtering
|
||||
findings does not change validation success. Retain native per-operation
|
||||
`--scope all` behavior, reporting missing required context rather than silently
|
||||
omitting scopes. There is no additional raw/resolved view or Narratio-owned
|
||||
path/provenance reconciliation.
|
||||
|
||||
Acquire only the context required by the selected scope. App inspection does
|
||||
not acquire campaign/party context solely for artifact expansion. Campaign
|
||||
inspection does not require a session. Catalog and planning commands acquire
|
||||
the context needed for their domain work.
|
||||
|
||||
| Selector | Meaning |
|
||||
| --- | --- |
|
||||
| `--config PATH` | Pipeline configuration root, regardless of scope |
|
||||
| `--overlay NAME` | Pipeline overlay |
|
||||
| `--campaign ID` | Campaign identity |
|
||||
| `--campaign-file PATH` | Explicit campaign file |
|
||||
| `--session ID` | Session identity for configuration inspection |
|
||||
| `--session-file PATH` | Explicit session file |
|
||||
| `--party-file PATH` | Explicit party file in place of the campaign default |
|
||||
| `--secrets-dir PATH` | Credential-bootstrap directory |
|
||||
|
||||
Session-oriented domain commands use positional session identity and may also
|
||||
select `--session-file`. A file selects the source; an explicit identity asserts
|
||||
the intended effective identity after resolution. Inspection may obtain identity
|
||||
from the file when no identity is asserted. Mismatches fail clearly.
|
||||
|
||||
Resolve explicit CLI-relative paths from the invocation directory. An explicit
|
||||
party file supplies the roster consistently for inspection, players, artifact
|
||||
expansion, planning, and execution; missing or invalid explicit files fail
|
||||
without falling back to the campaign default. Native source evidence identifies
|
||||
the selected file and its imports.
|
||||
|
||||
Diff resolves both sides independently, permitting different files, overlays,
|
||||
and campaigns. Add `--against-campaign`, `--against-campaign-file`,
|
||||
`--against-session`, `--against-session-file`, and `--against-party-file` alongside
|
||||
native `--against-config` and `--against-overlay`. Omitted right-side selectors
|
||||
use normal defaults, including that side's campaign-default roster; they do not
|
||||
inherit left-side values.
|
||||
|
||||
### Session Acquisition
|
||||
|
||||
Share selection rules between inspection and execution: load an explicit file
|
||||
exactly; otherwise use normal local discovery, then remote discovery when no
|
||||
local session exists and identity is known. Invalid content, access failures,
|
||||
and identity mismatches do not trigger fallback. Remote discovery prefers the
|
||||
authored session-root configuration, using the committed prepared snapshot only
|
||||
when the authored object is absent.
|
||||
|
||||
Inspection may perform these network reads without a separate opt-in. It does
|
||||
not initialize a workspace, restore files, acquire execution locks, or change
|
||||
manifests. Source inspection distinguishes local, remote-authored, and committed
|
||||
snapshot origins. No forced-local or forced-remote selector is needed initially.
|
||||
|
||||
### Overrides
|
||||
|
||||
Enable native `--set POINTER=JSON` only for app inspection and `--against-set`
|
||||
for its comparison side. ConfigKit owns assignment acceptance, ordering, merge,
|
||||
conflict, path, and typed-secret semantics. Do not add protected-field lists,
|
||||
translate domain catalog paths, or promise that every displayed path is
|
||||
overridable. Normal configuration validation and secret-safe output still apply.
|
||||
|
||||
Campaign, session, and party use file selectors rather than field overrides.
|
||||
Native aggregate inspection rejects overrides because not every scope supports
|
||||
them; aggregate operations without overrides retain upstream behavior. Do not
|
||||
add scope-specific override flags or cross-scope dispatch.
|
||||
|
||||
Inspection overrides affect that invocation only. Defer field overrides on
|
||||
execution and planning until CommandKit supplies a reusable binding. Narratio
|
||||
will not build its own parser, binding, or equivalent machinery. Files and
|
||||
overlays select execution settings; this convenience is not an adoption
|
||||
dependency.
|
||||
|
||||
### Reports And Diagnostics
|
||||
|
||||
Use native reporting and ckconfig report shapes. Domain operations return one
|
||||
structured result where meaningful, with public report values separate from
|
||||
internal state and manifests:
|
||||
|
||||
| Operation | Useful report content |
|
||||
| --- | --- |
|
||||
| Run/regenerate | Identities, selected stages, execution/reuse, artifacts, completion |
|
||||
| Plan | Execution/reuse decisions and reasons, targets, prerequisites |
|
||||
| Status | Local stage state and available remote publication information |
|
||||
| Artifact inspection | Source identities, producers, dependencies; availability/publication for session views |
|
||||
| Session validation | Overall outcome and findings |
|
||||
| Restore/clean | Planned/completed actions, conflicts, dry-run status |
|
||||
| Initialization/lock mutations | Concise confirmation of the affected session, destination, or lock |
|
||||
|
||||
Use native automatic presentation, including YAML for structured values, and
|
||||
`--format text|yaml|json`. Add text templates only where representative output
|
||||
shows a substantial readability benefit, presenting the same report data.
|
||||
Document public report fields without adding a schema-version mechanism.
|
||||
Report format does not change generated artifact formats, including session YAML.
|
||||
|
||||
CommandKit owns console presentation: results on stdout, diagnostics/progress
|
||||
on stderr. Ordinary mode shows results and failures; warnings/information require
|
||||
verbose/debug; progress requires `--progress` or debug. Quiet suppresses successful
|
||||
results and progress while preserving failures. Material conditions also appear
|
||||
in the result, independent of diagnostic visibility.
|
||||
|
||||
Keep downstream streams in existing captured logs and provide concise console
|
||||
context and log locations without automatic replay. Quiet does not disable logs
|
||||
or persistence; debug does not automatically enable downstream debug artifacts.
|
||||
Visibility options do not change pipeline selection, execution, or retention.
|
||||
|
||||
Failures after meaningful work return partial results alongside the failed
|
||||
outcome, preserving earlier durable successes. Early input failures need no
|
||||
empty report. Native report-delivery failures do not undo completed work.
|
||||
|
||||
### Invocation Lifecycle
|
||||
|
||||
Parse and check input combinations before credential bootstrap. Load required
|
||||
configuration, derive domain context, then acquire execution resources. Finalize
|
||||
state and release resources before completing the invocation. Configuration-
|
||||
dependent checks occur after loading. Help, version, completion, and scope
|
||||
discovery do not bootstrap secrets, load configuration, contact storage, or
|
||||
initialize adapters.
|
||||
|
||||
The process boundary supplies a context canceled by Ctrl-C or termination.
|
||||
Propagate it to active operations and existing adapter shutdown paths; stop
|
||||
scheduling further work. Attempt appropriate terminal manifest persistence and
|
||||
lock release, preserve completed checkpoints, and report meaningful partial
|
||||
results. Retain persistence or shutdown errors alongside the original failure.
|
||||
Cancellation does not run the cleanup stage or delete resumable work. Abrupt
|
||||
process death does not guarantee finalization.
|
||||
|
||||
Use native outcomes: `0` success; `1` operational failure, cancellation, or output
|
||||
failure; `2` invalid invocation or identifiable configuration input; `3` changed
|
||||
`diff --check`. Use public error classification and retain underlying error
|
||||
identity, avoiding error-string matching and duplicate terminal failures.
|
||||
|
||||
Provide native completion for command paths, flags, static stage/scope choices,
|
||||
and applicable file/directory selectors.
|
||||
|
||||
## Required Work
|
||||
|
||||
These work areas describe scope, not mandatory buildable milestones.
|
||||
|
||||
1. **Replace the command boundary.** Add the selected dependencies and native
|
||||
application/command declarations. Wire typed inputs to domain operations,
|
||||
introduce the artifacts family and revised selectors, and remove superseded
|
||||
routing, parsers, help, output, and shortcuts. Retain shared bounded execution
|
||||
for run, planning, and regeneration where applicable.
|
||||
2. **Correct the configuration handoff.** Review post-load composition: move
|
||||
genuine configuration defaults/resolution into supported ConfigKit callbacks;
|
||||
derive catalogs, player projections, and publication actions separately.
|
||||
Adapt planning, stages, adapters, prepared records, and semantic evidence to
|
||||
consume those products without mutating completed configuration. Remove
|
||||
replacement inspection snapshots and their separate evidence path while
|
||||
retaining records needed for preparation and resume.
|
||||
3. **Integrate native scopes and acquisition.** Expose genuine results through
|
||||
`ckconfig.FromConfigKit`, register the four scopes and their selectors, and
|
||||
enable app-only inspection overrides. Share local/remote selection with
|
||||
execution, add party-file selection, and remove the same-campaign diff
|
||||
restriction. Keep each comparison side independent and acquisition lazy.
|
||||
4. **Integrate presentation and lifecycle.** Define domain report values, route
|
||||
diagnostics through CommandKit, and replace ad hoc status handling. Propagate
|
||||
signal cancellation and adapt runner failure/finalization paths to preserve
|
||||
partial results and attempt terminal persistence. Add native completion.
|
||||
5. **Complete integration and migration.** Update behavioral tests, remove
|
||||
obsolete CLI machinery and expectations, review dependency attribution, and
|
||||
update canonical documentation, examples, and affected scripts with the
|
||||
implementation. Prepare workflow-oriented release migration guidance.
|
||||
|
||||
## Verification And Completion
|
||||
|
||||
Use real CommandKit and ConfigKit with controlled external boundaries. Cover
|
||||
the integration risks without duplicating upstream parser/configuration tests:
|
||||
|
||||
- Native commands and selectors invoke the intended operation; stage/range,
|
||||
force, analysis-target selection, and complete-bundle regeneration retain
|
||||
their agreed meanings.
|
||||
- Native inspection uses genuine results and evidence. Catalog/plan derivation
|
||||
does not mutate them. Equivalent files and overlays have the same loading
|
||||
semantics across inspection, planning, and execution; inspection overrides
|
||||
remain invocation-local and unavailable on execution commands.
|
||||
- Required context, identity assertions, exact-file errors, local/remote
|
||||
fallback, and source labels behave consistently without inspection creating
|
||||
runtime state. Party selection reaches each consumer, and diff sides remain
|
||||
independent. App-only and aggregate override behavior follows ckconfig.
|
||||
- Structured results remain separate from diagnostics, retain meaningful partial
|
||||
work, and use native outcomes. Lazy commands avoid configuration/services;
|
||||
cancellation reaches active work, preserves checkpoints, and permits terminal
|
||||
persistence and lock release, including their failure reporting.
|
||||
- Existing consequential stage, resume, publication, restore, and cleanup
|
||||
behavior remains protected. Safe inspection, diagnostics, and persistence
|
||||
preserve the established secret-handling boundary.
|
||||
|
||||
Update or retire tests enforcing replaced CLI conventions while retaining useful
|
||||
domain coverage. Default verification remains offline and independent of live
|
||||
services, real credentials, and paid model calls. Run the repository's established
|
||||
final checks from [Development](../development.md#validation): tests, race-enabled
|
||||
tests, vet, and build, including documentation and maintained-example checks.
|
||||
|
||||
Carry out implementation as one end-to-end sprint. Intermediate commits may be
|
||||
incomplete, incoherent, or noncompiling; use focused checks where useful and
|
||||
report their state accurately. Do not add compatibility scaffolding to make each
|
||||
commit independently shippable. Completion requires the coherent, compilable,
|
||||
validated final application and its documentation.
|
||||
|
||||
## Migration And Deferred Work
|
||||
|
||||
Release guidance will include an old-to-new command table and explain identity
|
||||
versus file selectors, party-file selection, inspection-only overrides, native
|
||||
flag repetition/placement, inspection versus domain views, comparison defaults,
|
||||
structured output, diagnostic visibility, exit classifications, and cancellation.
|
||||
Update the [CLI](../cli.md), [configuration](../config.md),
|
||||
[operations](../operations.md), relevant internal/integration documentation,
|
||||
and [maintained examples](../../examples/README.md) when implementation lands.
|
||||
Release notes summarize the impact and link to those canonical contracts.
|
||||
Select the release number under [release policy](../policy/release.md) once the
|
||||
final compatibility impact is known; this roadmap does not authorize publication.
|
||||
|
||||
Execution/planning overrides await a reusable upstream binding. Dynamic
|
||||
campaign/artifact completion and streaming JSON events are deferred. Direct
|
||||
ckprompt/PromptKit ownership, downstream-tool adoption, workspace reorganization,
|
||||
and Scriptorium-backed input discovery and early dependency checks remain
|
||||
separate work. The catalog exposes Narratio's configured knowledge; this
|
||||
migration does not promise to discover prompt requirements or prove that every
|
||||
configured pipeline can complete.
|
||||
|
||||
No significant design decisions remain open. Implementation sequencing and
|
||||
release selection do not block preparation of the implementation plan.
|
||||
Reference in New Issue
Block a user