Files
narratio/docs/roadmap/commandkit.md

20 KiB

CommandKit Adoption

Status: implemented; all stages in the implementation plan are complete.

This roadmap consolidates the migration discussion. It defines the intended end state and required work. The implementation plan defines the ordered implementation stages.

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/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: 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.

Emit Progress for stage transitions and useful finer-grained activity, including download starts/completions, individual speaker and artifact completions, and reuse of prior work. These events are available with --progress alone and use native streamed, unprefixed lines. Info supplies context: selected sources, destinations, configuration, and reasons for decisions. For example, downloading a speaker's audio is Progress; identifying the selected audio source is Info.

Keep the categories independent. --verbose enables informational messages and warnings without enabling progress; --progress enables progress without enabling informational messages or warnings. With both flags, stderr carries both categories while stdout retains the final report. Do not introduce a separate verbose-progress level or require both flags for finer-grained events.

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

The required changes span these areas.

  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 and finer-grained progress 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. Representative finer-grained progress events appear with --progress alone; informational context follows verbose mode, and combining the flags exposes both without changing stdout reports.
  • 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.

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. Release selection remains separate from implementation.