455 lines
23 KiB
Markdown
455 lines
23 KiB
Markdown
# CommandKit migration notepad
|
|
|
|
Status: working discussion notes. Started 2026-11-19.
|
|
|
|
Narratio will become a CommandKit-native application. This notepad collects the
|
|
agreed direction, open questions, and subsequent decisions before they are
|
|
consolidated into a feature roadmap. It is not an implementation plan or a
|
|
description of current Narratio behavior.
|
|
|
|
## Agreed direction
|
|
|
|
### Full native cutover
|
|
|
|
Adopt CommandKit's public-facing conventions and recommendations to the fullest
|
|
extent. Backward compatibility with Narratio's existing CLI conventions is a
|
|
non-goal. Provide migration guidance in release documentation so operators can
|
|
update their commands and scripts.
|
|
|
|
Use native command declarations, typed inputs, routing, help, version,
|
|
reporting, and outcome handling. Adopt upstream parsing and presentation
|
|
semantics rather than building compatibility parsers, legacy output modes, or
|
|
status translations to reproduce the existing CLI.
|
|
|
|
Consequently, differences in repeated-flag handling, option placement, help,
|
|
version output, configuration comparison syntax, and exit classification are
|
|
migration topics to explain, not legacy behavior to preserve. Existing command
|
|
names and shortcuts may survive when they remain useful domain operations;
|
|
their historical existence alone does not require retaining them.
|
|
|
|
### Modules and ownership
|
|
|
|
Plan adoption of CommandKit core and its ConfigKit integration, `ckconfig`.
|
|
Use the standard inspection capabilities where they apply to Narratio's
|
|
configuration. Generated help and shell completion belong in the direction
|
|
for the cutover.
|
|
|
|
Narratio continues to own pipeline orchestration, configuration-domain
|
|
resolution, artifact selection, manifests, resume, publishing, restore, and
|
|
cleanup. CommandKit owns CLI mechanics and presentation through its public
|
|
APIs. Application-owned declarations and providers connect those boundaries.
|
|
|
|
Keep `ckprompt` and direct PromptKit engine ownership outside this migration.
|
|
Narratio delegates prompt execution to Scriptorium. Prompt-requirements
|
|
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, with spelling defined below.
|
|
|
|
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, with the view defined below.
|
|
|
|
### Configuration scopes and views
|
|
|
|
Expose four scopes corresponding to Narratio's configuration domains. Use `app`
|
|
as the native default scope.
|
|
|
|
| Scope | Effective configuration |
|
|
| --- | --- |
|
|
| `app` | Pipeline configuration, including campaign-dependent artifact expansion and generated publish rules |
|
|
| `campaign` | The selected campaign's settings |
|
|
| `session` | The selected session's settings, including applicable campaign defaults |
|
|
| `party` | The selected campaign's canonical party roster |
|
|
|
|
Use effective values for `show` and `diff`, native provenance for `sources` and
|
|
`explain`, and domain validation for `validate`. Inspection reflects imports,
|
|
overlays, inheritance, defaults, and applicable Narratio resolution. A separate
|
|
raw-versus-resolved mode is not part of the initial design.
|
|
|
|
`app` show/diff includes the concrete artifacts and publish rules execution
|
|
receives. Provenance must distinguish authored and derived values accurately;
|
|
a generated artifact must not appear to have been literally declared in a
|
|
source file. Use native evidence without inventing source origins.
|
|
|
|
Keep `config artifacts` as a focused catalog of definitions and dependencies
|
|
derived from the same effective pipeline. `session artifacts SESSION` reports
|
|
session-specific availability and publication state. Future input discovery can
|
|
extend the configuration catalog separately from this migration.
|
|
|
|
Acquire only the context needed for the selected scope. Party-driven pipeline
|
|
expansion requires the selected campaign and party; effective session settings
|
|
require the session and applicable campaign context. Campaign inspection does
|
|
not require a session. Scope discovery and help do not load configuration.
|
|
Report missing required context explicitly rather than presenting a partially
|
|
resolved view as complete.
|
|
|
|
Retain CommandKit's operation-specific `--scope all` behavior. Do not silently
|
|
omit a selected scope whose required context is missing.
|
|
|
|
Comparisons use independently resolved left and right selections through native
|
|
selectors and their `--against-*` counterparts. Permit comparisons across
|
|
overlays, configuration files, and campaigns; the existing same-campaign
|
|
restriction is not retained.
|
|
|
|
### Session acquisition and selectors
|
|
|
|
Inspection and execution use the same session-selection rules. Load an explicit
|
|
session file exactly when supplied; otherwise use normal local discovery, then
|
|
configured remote discovery when no local session exists and its identity is
|
|
known. Missing or invalid explicit files are errors. Invalid content, access
|
|
failures, and identity mismatches do not trigger fallback to another source.
|
|
|
|
Remote discovery prefers the authored session-root configuration and falls back
|
|
to the committed prepared snapshot only when the authored object is absent.
|
|
Configuration inspection permits these network reads without requiring a
|
|
separate remote opt-in. It creates no local runtime state: no workspace
|
|
initialization, restored files, execution locks, or manifest changes. Source
|
|
inspection identifies local, remote-authored, and committed-snapshot origins.
|
|
Forced-local or forced-remote selection is not part of the initial design.
|
|
|
|
| Selector | Meaning |
|
|
| --- | --- |
|
|
| `--config PATH` | Pipeline configuration root for every scope |
|
|
| `--overlay NAME` | Pipeline overlay |
|
|
| `--campaign ID` | Campaign identity |
|
|
| `--campaign-file PATH` | Explicit campaign configuration file |
|
|
| `--session ID` | Session identity on configuration inspection commands |
|
|
| `--session-file PATH` | Explicit session configuration file |
|
|
| `--secrets-dir PATH` | Credential-bootstrap directory selection |
|
|
|
|
Changing scope does not change the meaning of `--config`. Session-oriented
|
|
commands retain their positional session identity and can also select an
|
|
explicit source using `--session-file`.
|
|
|
|
Identity and file selectors are complementary: the file selects the source and
|
|
an accompanying ID asserts the intended identity. Check that assertion against
|
|
the effective configuration after native overrides and resolution; mismatches
|
|
fail clearly.
|
|
For inspection, the file can supply identity when no identity selector is
|
|
given; session-oriented commands retain their required positional identity.
|
|
Select the party through its campaign; an independent `--party-file` selector
|
|
is not part of this migration.
|
|
|
|
Comparisons expose `--against-campaign`, `--against-campaign-file`,
|
|
`--against-session`, and `--against-session-file` alongside CommandKit's native
|
|
right-side configuration selectors. Omitted right-side selectors use normal
|
|
defaults rather than inheriting left-side values.
|
|
|
|
### Configuration inspection capabilities
|
|
|
|
Enable the full applicable native inspection capabilities across the four
|
|
configuration scopes:
|
|
|
|
- path-selected show using JSON Pointer syntax;
|
|
- explanation and path discovery, including available history and provenance;
|
|
- detailed validation findings with native severity and code filters;
|
|
- detailed comparisons with before/after values and presence information; and
|
|
- native `diff --check`, including status `3` when differences exist.
|
|
|
|
These operations use the same configuration and evidence as ordinary
|
|
inspection. Filtering findings changes presentation, not validation success.
|
|
Expose available evidence for derived fields without manufacturing source
|
|
history.
|
|
|
|
### Native configuration overrides
|
|
|
|
Support invocation-local overrides for all four domains, with equivalent
|
|
configuration selections available to inspection, planning, and execution.
|
|
CommandKit supplies the `POINTER=JSON` flag grammar; ConfigKit applies its native
|
|
override mechanism. Do not introduce additional protected-field lists, custom
|
|
merge semantics, or a separate override acceptance policy.
|
|
|
|
Use these flag spellings:
|
|
|
|
| Flag | Target |
|
|
| --- | --- |
|
|
| `--set POINTER=JSON` | Selected inspection scope; `app` on execution commands |
|
|
| `--set-app POINTER=JSON` | App/pipeline configuration explicitly |
|
|
| `--set-campaign POINTER=JSON` | Campaign configuration explicitly |
|
|
| `--set-session POINTER=JSON` | Session configuration explicitly |
|
|
| `--set-party POINTER=JSON` | Party configuration explicitly |
|
|
|
|
Explicitly targeted flags also support overriding a configuration on which the
|
|
selected inspection view depends, such as inspecting expanded pipeline
|
|
artifacts with a party override. Comparisons use native `--against-set` and
|
|
the corresponding `--against-set-app`, `--against-set-campaign`,
|
|
`--against-set-session`, and `--against-set-party` flags for the right side.
|
|
Retain native aggregate-scope behavior rather than inventing scope prefixes
|
|
inside JSON Pointers.
|
|
|
|
Apply overrides after typed defaults and decoding, before application
|
|
resolution and semantic validation. Preserve native explicit empty, false,
|
|
zero, and null values, mapping merge and whole-sequence replacement, and
|
|
duplicate/overlapping-path rejection. Earlier parsing and decoding failures
|
|
remain errors. CommandKit's last-value convention for singleton flags does not
|
|
replace ConfigKit's conflict rules for override records.
|
|
|
|
Override paths address the configuration accepted by the loader. They do not
|
|
provide an independent patch mechanism over the final expanded artifact
|
|
catalog. Ordinary Narratio derivation and validation determine the effective
|
|
result, regardless of whether values came from files, inheritance, overlays,
|
|
or CLI overrides.
|
|
|
|
Overrides leave source configuration files unchanged. Normal run metadata and
|
|
prepared configuration may record the effective settings through established
|
|
secret-safe representations. Reuse decisions continue to depend on semantic
|
|
evidence: result-affecting changes can require regeneration, while the presence
|
|
of an override alone does not force execution.
|
|
|
|
### Identity assertions and credential overrides
|
|
|
|
Identity fields are not immutable or excluded from overrides. ConfigKit applies
|
|
their overrides normally. Narratio then checks the effective identity against
|
|
any explicitly asserted campaign/session identity so an operation targeting one
|
|
session cannot silently use another session's workspace, lock, manifest, or
|
|
remote destination. This is an ordinary domain consistency check, independent
|
|
of how the value was supplied.
|
|
|
|
When no identity is asserted, such as inspection of an explicit session file
|
|
without `--session`, the effective document can supply its overridden identity.
|
|
Session-oriented commands retain their required positional assertion.
|
|
|
|
Credential-related fields accept native overrides and use ConfigKit's ordinary
|
|
typed-secret handling and normal configuration validation. Safe inspection,
|
|
diagnostics, and persistence remain separate output responsibilities; they do
|
|
not justify additional restrictions on which fields may be overridden.
|
|
|
|
### Reports and machine-readable output
|
|
|
|
Use CommandKit's native reporting system throughout. Produce one structured
|
|
result per invocation where the command has a meaningful result, keeping
|
|
progress and diagnostics separate. Standard ckconfig commands retain their
|
|
native report shapes; Narratio defines report values for its domain operations.
|
|
|
|
| Command family | Report content |
|
|
| --- | --- |
|
|
| `run`, `regenerate-artifacts` | Campaign/session identity, selected stages, execution or reuse outcomes, generated artifacts, and completion status |
|
|
| `session plan` | Selected stages, planned execution/reuse decisions and reasons, artifact targets, and prerequisites |
|
|
| `session status` | Local stage state and available remote publication information |
|
|
| Artifact catalogs | Source identities, producers, dependencies, and session-specific availability/publication where applicable |
|
|
| `session validate` | Overall outcome and individual findings |
|
|
| `session restore`, `session clean` | Planned or completed actions, conflicts, and dry-run status |
|
|
| Session initialization and lock mutations | Concise confirmation identifying the affected session, destination, or lock |
|
|
|
|
Support native `--format text|yaml|json` conventions. Start with native automatic
|
|
presentation, including YAML for structured values. Add a custom text template
|
|
only when representative output demonstrates a substantial readability benefit.
|
|
The template presents the same report value rather than a separate information
|
|
model; recreating the existing handwritten text output is not a goal.
|
|
|
|
Long-running operations emit progress through the diagnostic channel and their
|
|
final report through the result channel, allowing JSON results to be captured
|
|
without progress mixed into the document. A streaming JSON event protocol is
|
|
deferred as a separate interface.
|
|
|
|
When execution stops after meaningful domain work, report what completed and
|
|
where work stopped alongside the failed command outcome. Preserve the success
|
|
of earlier durable work. Failures before meaningful domain work, such as invalid
|
|
arguments, need only the native error; do not manufacture an empty run report.
|
|
Report-delivery failure follows CommandKit's native handling and does not undo
|
|
completed pipeline work.
|
|
|
|
Define public report values separately from internal structs and durable
|
|
manifests. Expose information useful to operators and callers without making
|
|
the entire internal state or manifest schema the CLI contract. Document
|
|
application-owned report fields as a public interface. An additional schema
|
|
version mechanism is not part of the initial design; review native report
|
|
changes during dependency upgrades.
|
|
|
|
`--format` controls the command report, not the format of generated artifacts.
|
|
For example, session initialization still writes its YAML configuration when
|
|
the confirmation report uses JSON.
|
|
|
|
## Reviewed upstream baseline
|
|
|
|
The initial review covered these released modules:
|
|
|
|
| Module | Version | Relevant capability |
|
|
| --- | --- | --- |
|
|
| `go.maximumdirect.net/commandkit` | v0.7.0 | Typed commands and inputs, presence tracking, aliases, help/version, completion, reporting, and outcomes |
|
|
| `go.maximumdirect.net/ckconfig` | v0.9.0 | Configuration scopes, validation, safe display, sources, explanation, comparison, and optional overrides |
|
|
| `go.maximumdirect.net/ckprompt` | v0.10.0 | PromptKit inspection and request tooling; reviewed for context, outside adoption scope |
|
|
|
|
Core v0.7.0 and ckconfig v0.9.0 require Go 1.27.0; ckconfig selects ConfigKit
|
|
v1.2.1. Narratio already declares those Go and ConfigKit versions. CommandKit
|
|
identifies itself as alpha. Select exact released versions when preparing the
|
|
roadmap and revisit these references if that baseline changes.
|
|
|
|
Upstream references:
|
|
|
|
- [Consumer guide and module selection](https://forge.maximumdirect.net/base-layer/commandkit/src/commit/d330d7637f2e7507eca931a899397222c82bc892/docs/consumers/guide.md)
|
|
- [Core CLI conventions](https://forge.maximumdirect.net/base-layer/commandkit/src/commit/b57bfe176cff05a892e6cb07ebb5f350239e55d4/docs/cli.md)
|
|
- [ConfigKit integration public contracts](https://forge.maximumdirect.net/base-layer/commandkit/src/commit/9962368f0c1ea1f6ad010638e94621091105d745/integrations/ckconfig/contracts.go)
|
|
|
|
Narratio's existing [CLI reference](../cli.md) and
|
|
[configuration internals](../internal/configuration.md) provide the current
|
|
baseline. They remain current-behavior documents until the migration lands.
|
|
|
|
## Open decisions
|
|
|
|
### Diagnostics and invocation lifecycle
|
|
|
|
Classify existing messages into CommandKit's result, failure, warning,
|
|
information, progress, and debug categories. Use native visibility rules,
|
|
including their suppression behavior, and ensure failures communicate the
|
|
actionable context. Coordinate this with existing durable logs and stage
|
|
diagnostics so the CLI does not emit duplicate messages.
|
|
|
|
Define where configuration acquisition and secrets bootstrap occur so help,
|
|
version, completion, and invalid syntax do not unnecessarily initialize runtime
|
|
services. Narratio owns process startup, signal handling, cancellation, and
|
|
exit; decide how that lifecycle supplies CommandKit invocations while retaining
|
|
session locking and failure persistence.
|
|
|
|
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.
|
|
|
|
### 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.
|
|
|
|
Once the target command/report surface is settled, identify affected examples,
|
|
operator procedures, scripts, and downstream callers. Release guidance should
|
|
map old workflows to their native equivalents and explain parsing, output,
|
|
diagnostic, and exit-status changes. Select the release version under the
|
|
repository's release policy when the compatibility impact is concrete.
|
|
|
|
Record appropriate validation for domain behavior and CLI integration in the
|
|
eventual plan. Dependency attribution and canonical documentation updates belong
|
|
to the adoption work. No release version or publication action is selected here.
|
|
|
|
## Discussion and decision record
|
|
|
|
### 2026-11-19 — Initial direction
|
|
|
|
Accepted the direction of adopting core and ckconfig while keeping direct
|
|
PromptKit integration and Scriptorium requirements work separate. The initial
|
|
review identified command design, configuration views, reporting, and lifecycle
|
|
as the main discussion areas.
|
|
|
|
The user established full CommandKit-native cutover as the guiding decision:
|
|
adopt upstream public conventions and recommendations to the fullest extent,
|
|
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.
|
|
|
|
### 2026-11-19 — Configuration scopes and views agreed
|
|
|
|
Accepted `app`, `campaign`, `session`, and `party` scopes, with `app` as default.
|
|
Show/diff exposes effective values and source/explanation operations use native
|
|
provenance. Concrete artifacts remain visible in the effective pipeline and the
|
|
separate configuration catalog; session artifact inspection owns availability.
|
|
Accepted context-dependent acquisition, explicit missing-context errors, native
|
|
aggregate-scope behavior, and independently resolved comparisons across
|
|
campaigns. Session acquisition policy and selector spelling are next.
|
|
|
|
### 2026-11-19 — Session acquisition and selectors agreed
|
|
|
|
Accepted shared inspection/execution discovery with automatic remote fallback,
|
|
read-only acquisition without local runtime state, and explicit source
|
|
provenance. Accepted distinct identity/file selectors, identity assertions when
|
|
both are supplied, campaign-owned party selection, and independent right-side
|
|
comparison selectors. Optional configuration capabilities and overrides are
|
|
the next discussion topic.
|
|
|
|
### 2026-11-19 — Configuration capabilities and overrides agreed
|
|
|
|
Accepted full applicable inspection capabilities and native overrides across
|
|
all four configuration domains, with parity across inspection, planning, and
|
|
execution. Selected verb-first `--set-app`, `--set-campaign`, `--set-session`,
|
|
and `--set-party` spellings and corresponding `--against-set-*` comparison
|
|
flags, alongside native `--set` and `--against-set`.
|
|
|
|
Clarified that overrides have no Narratio-specific protected fields or custom
|
|
merge semantics. Identity assertions are checked against effective values after
|
|
native overrides and resolution; they do not make identity fields immutable.
|
|
Credential overrides use native typed-secret handling. Safe output and
|
|
persistence do not impose additional override restrictions.
|
|
|
|
### 2026-11-19 — Reporting agreed
|
|
|
|
Accepted native structured reporting with one meaningful result document per
|
|
invocation, separate diagnostics/progress, and native ckconfig report shapes.
|
|
Custom text templates require a demonstrated readability benefit. Domain
|
|
reports describe partial execution on failure without undoing durable work;
|
|
early failures need no empty report. Report models remain separate from
|
|
manifests and generated artifact formats, with documented public fields and no
|
|
additional schema version mechanism initially. Streaming JSON events remain
|
|
deferred. Diagnostics and invocation lifecycle are the next discussion topic.
|
|
|
|
### Continuing the discussion
|
|
|
|
For each topic, record the question, the agreed outcome, its rationale, and any
|
|
remaining dependency or follow-up. Date decisions and update the corresponding
|
|
open topic so settled issues are not repeatedly reopened. Distinguish proposals
|
|
from accepted decisions.
|
|
|
|
Once the relevant decisions are settled, consolidate the target behavior, scope,
|
|
compatibility impact, and acceptance criteria into the feature roadmap. Keep
|
|
implementation sequencing for the subsequent plan.
|