19 KiB
CommandKit Adoption
Status: agreed target; implementation pending.
This roadmap consolidates the migration discussion. 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, configuration internals, and internal overview describe the implementation. The migration starts from these differences:
internal/appowns 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: 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
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.
- 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.
- 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.
- 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. - 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.
- 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: 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, configuration, operations, relevant internal/integration documentation, and maintained examples when implementation lands. Release notes summarize the impact and link to those canonical contracts. Select the release number under release policy 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.