Record CommandKit migration direction and open decisions
This commit is contained in:
188
docs/roadmap/commandkit-notepad.md
Normal file
188
docs/roadmap/commandkit-notepad.md
Normal file
@@ -0,0 +1,188 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user