290 lines
14 KiB
Markdown
290 lines
14 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. Configuration inspection selector spelling remains to be settled.
|
|
|
|
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 policy and exact application
|
|
selector spellings remain open below.
|
|
|
|
## 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
|
|
|
|
### Session acquisition and selector spelling
|
|
|
|
Decide whether configuration inspection uses normal remote session discovery
|
|
when no local source exists, or requires an explicit remote selection. Define
|
|
the read-only boundary, including network reads and any local materialization.
|
|
|
|
Choose consistent flags for campaign/session identities versus explicit files
|
|
and their right-side comparison equivalents. Session-oriented commands retain
|
|
their agreed positional IDs; standard configuration commands use selectors
|
|
suited to the native ckconfig command structure.
|
|
|
|
### Optional configuration capabilities
|
|
|
|
Determine the useful scope of path-selected show, path explanation, detailed
|
|
validation findings, comparison details/check mode, and temporary `--set`
|
|
overrides. Prefer the native capabilities wherever the provider can faithfully
|
|
support them.
|
|
|
|
Overrides require a domain decision: which configurations accept them, and do
|
|
execution commands accept the same overrides as inspection? The integration's
|
|
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.
|
|
|
|
### Reports and machine-readable output
|
|
|
|
Design useful report values for planning, status, artifact inventories,
|
|
validation, restore, cleanup, and execution summaries. Apply native text, YAML,
|
|
and JSON presentation consistently. Decide where a text template improves
|
|
operator readability and where native structured presentation is sufficient.
|
|
|
|
CommandKit does not transform raw application output into structured reports.
|
|
Identify any output that genuinely needs raw bytes and distinguish final
|
|
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.
|
|
|
|
### 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.
|
|
|
|
### 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.
|