189 lines
9.5 KiB
Markdown
189 lines
9.5 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.
|
||
|
|
|
||
|
|
## 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
|
||
|
|
|
||
|
|
### 1. Domain command organization
|
||
|
|
|
||
|
|
Which commands and conveniences should the native CLI expose? Review `run`,
|
||
|
|
`run-stage`, `analyze`, `publish`, `regenerate-artifacts`, `clean`, and the
|
||
|
|
`session` family for operator usefulness. Decide how session IDs, stage bounds,
|
||
|
|
and artifact selections should be expressed using native typed inputs.
|
||
|
|
|
||
|
|
CommandKit aliases redirect command paths; they do not inject flags or
|
||
|
|
operands. Retained conveniences that select a stage or force a range therefore
|
||
|
|
need application-owned commands sharing domain execution logic. Decide which
|
||
|
|
are worth keeping on that basis, without a compatibility requirement.
|
||
|
|
|
||
|
|
### 2. Configuration scopes and views
|
||
|
|
|
||
|
|
Which named scopes should be available initially: one effective pipeline scope,
|
||
|
|
or also campaign, session, and party scopes? Define the selectors and acquisition
|
||
|
|
needed for each, including which inspections should work without a session or
|
||
|
|
remote access.
|
||
|
|
|
||
|
|
Narratio distinguishes the authored configuration from the resolved domain
|
||
|
|
view containing concrete artifact families and generated publish rules. Settle
|
||
|
|
what each standard inspection operation exposes, keeping safe effective values
|
||
|
|
and truthful native provenance available without confusing their meanings.
|
||
|
|
|
||
|
|
The initial proposal is to use the resolved, credential-safe domain view for
|
||
|
|
show and diff, native evidence for source/explanation operations, and an
|
||
|
|
application-specific artifact catalog. Decide the catalog's placement and how
|
||
|
|
campaign and party context participate in comparisons, including independent
|
||
|
|
left and right selectors.
|
||
|
|
|
||
|
|
### 3. 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.
|
||
|
|
|
||
|
|
### 4. 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.
|
||
|
|
|
||
|
|
### 5. 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.
|
||
|
|
|
||
|
|
### 6. 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.
|
||
|
|
|
||
|
|
### 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.
|