Files
scriptorium/docs/roadmap/commandkit-notepad.md

214 lines
12 KiB
Markdown
Raw Normal View History

# CommandKit migration notepad
Status: discussion in progress. This is the working record for agreeing on
Scriptorium's CommandKit migration before preparing a feature roadmap. It
captures direction, open decisions, and discussion notes; implementation scope
and sequencing will follow once the relevant decisions are settled.
## Product context
Scriptorium is a neutral executable interface over PromptKit. Its primary
consumers are applications that need to run stored prompts and consume their
output without importing PromptKit or building an internal prompting workflow.
The CLI and its subprocess contract are therefore central to this migration.
An installation may load many independently maintained collections. The
existing collection model remains the starting point: ConfigKit imports discover
`collection.yml` or `collection.yaml` entry points, each collection declares its
own namespace, and relative imports assemble its profiles and prompts. See the
[configuration contract](../config.md) and
[discovery example](../../examples/config.discovery.yml).
HTTP remains secondary to the CLI discussion. A broader HTTP design review is
planned before v1.0; adopting CommandKit does not itself settle that design.
## Agreed direction
### Full native cutover
Decision recorded 2026-11-19: become a CommandKit-native application, including
`ckconfig` and `ckprompt`, and adopt upstream public conventions and
recommendations as fully as possible.
Backward compatibility with existing CLI conventions is an explicit non-goal.
Legacy command names, flag spellings, parsing rules, report shapes, and exit
semantics do not constrain the new interface. Do not add compatibility wrappers,
legacy aliases, or duplicate inspection implementations solely to preserve the
old CLI. Upstream convenience aliases can be considered on their own merits.
Provide migration guidance in release documentation so consumers can update
their invocations and output handling. Guidance replaces a compatibility layer;
it does not require a transition period with both interfaces. The
[release policy](../policy/release.md#versioning-and-compatibility) governs
release version selection and documentation of breaking changes.
### Ownership and integration
Use CommandKit for command declarations, parsing, help, reporting, and outcomes;
use `ckconfig` and `ckprompt` for their standardized operator interfaces.
Scriptorium should retire the corresponding custom inspection machinery as
those interfaces take over.
PromptKit continues to own preparation and execution semantics. ConfigKit
continues to own configuration resolution. Scriptorium supplies application
configuration and source selection, generation and server commands, process
lifecycle, and application-specific artifact handling. CommandKit adoption
does not introduce workflow or conversation state.
Prefer shared upstream capabilities over new Scriptorium-specific equivalents.
If a required shared capability is missing, discuss an upstream request before
designing a local substitute. Application-specific behavior still belongs in
Scriptorium.
### Initial capability set
Decision recorded 2026-11-19: include configuration comparison, provider smoke
tests, and shell completion in the initial migration, alongside application and
PromptKit configuration scopes, resource inventories and inspection,
requirements discovery, and concrete request validation.
Use the existing upstream capabilities. Configuration comparison should cover
both application and PromptKit scopes, with independent selections for each
side. Provider smoke tests run when explicitly invoked; including them does not
make them startup checks or release prerequisites. Document provider usage and
the distinction between successful diagnostic execution and positive findings.
Shell completion should use upstream command, flag, static-value, and path
completion, with appropriate hints for application-owned inputs. Dynamic
completion of installed resource names is a separate possible enhancement.
Application-specific wiring remains to be designed, but inclusion of these
three capabilities is settled. Prepared-request preview and the future of
`render` remain a separate discussion below.
## Upstream baseline
The initial review covered CommandKit **v0.7.0**, ckconfig **v0.9.0**, and
ckprompt **v0.10.0**. These are a review baseline, not a final dependency choice
for implementation. The [upstream consumer guide][upstream-guide] describes
their composition and supported extension points.
| Component | Relevant capabilities |
| --- | --- |
| CommandKit | Typed flags and operands with explicit-value presence, generated help and version, shared reporting and outcomes, optional shell completion. |
| ckconfig | Configuration scopes; validation, effective values, sources, explanations, and comparisons; temporary overrides where supported by the loader. |
| ckprompt | Prompt, profile, backend, namespace, and collection inventories; resource inspection; requirements discovery; optional concrete request validation, prepared-request previews, and provider smoke tests. Reusable request flags also serve application-owned commands. |
Scriptorium currently uses PromptKit v0.23.3 and ConfigKit v1.2.1. The reviewed
ckprompt release declares PromptKit v0.23.2 and ConfigKit v1.2.1. Validate the
chosen dependency combination while retaining Scriptorium's adopted PromptKit
fixes; the older declared minimum is not a reason to downgrade.
The [upstream CLI reference][upstream-cli] owns the detailed conventions. The
[current Scriptorium CLI](../cli.md) and
[subprocess contract](../integrations/subprocess.md) describe the starting point,
not requirements to reproduce during migration.
## Open decisions
### 1 Generation output and process outcomes
The starting proposal is to keep generated artifact bytes easy to consume,
with execution metadata separately available. CommandKit supports both raw
output and structured reports; using it does not require wrapping generated
artifacts in a report envelope.
Decide the new generation interface: stdout versus explicit file output,
execution-report delivery, and how those choices interact with standard format
and verbosity controls. In particular, quiet mode suppresses CommandKit output
but does not cancel execution; application-owned file effects need an explicit
design. Ordinary diagnostics should follow upstream reporting conventions.
Adopt upstream usage and operational outcomes, then decide how to represent
generated-output validation failure as an application domain outcome. The
current use of exit 2 for that failure conflicts with CommandKit's usage and
invalid-configuration convention. Also settle output/report write failures and
how callers distinguish them from generation or validation failures.
Signal cancellation and the whole-operation deadline remain application
responsibilities. Decide their mapping to the CommandKit invocation context
and PromptKit operation timeout, separately from the standard per-attempt
timeout flag.
### 2 Prepared-request preview and the existing render command
Upstream `promptkit show prepared` overlaps Scriptorium's `render` command.
Prefer one preparation path and the native prepared report.
Decide whether the upstream command fully meets the product need, or whether an
application command still serves a distinct purpose such as artifact-oriented
file output. Retaining the old name or custom report solely for compatibility
is already ruled out. Review associated application defaults, including the
current render-format setting, when deciding the final interface.
### 3 Configuration selection and namespace experience
Use consistent application configuration and PromptKit source selection across
generation, inspection, requirements, and previews. Application-only
configuration inspection should not require constructing a PromptKit engine.
Decide how the standard `app` and `promptkit` configuration scopes are exposed,
how application selectors map into their loaders, and which temporary overrides
are supported. Configuration scope, resource namespace, and profile selection
are distinct concepts and should remain clear to operators.
For installations with many collections, decide whether to enable the optional
prompt, profile, and backend namespace selectors and how to present the native
namespace-filtered and all-namespace inventory views. Begin with upstream
behavior; identify any unmet collection-navigation need before adding local
conventions. Collection discovery itself does not need redesign for CommandKit.
### 4 Native reports and executable consumer needs
Adopt native inspection reports as the starting point. Standard prompt
inspection includes captured prompt messages, unlike the current Scriptorium
summary. Document that change and confirm how native inspection and preparation
reports meet operator needs without rebuilding custom projections.
Reconcile the proposed [Narratio requirements request](narratio-feature-request.md)
with native `promptkit requirements show`. Its central need remains valid:
discover input requirements before expensive upstream work and before input
files exist. Preserve the distinction between successful discovery and complete
discovery; a successful partial report does not establish all requirements.
The proposal's legacy syntax and prompt-version assumptions need revision. Its
illustrative versioned JSON envelope and structured-error request also need a
decision: native reports do not add that Scriptorium envelope, and `--format
json` does not automatically turn diagnostics into a JSON error protocol.
Determine which consumer requirements are essential and whether any genuine
gap belongs upstream. Avoid treating the existing proposal as a mandate for a
new compatibility facade.
Keep discovery distinct from concrete request validation: validation prepares a
real request and may read input artifacts and check relevant credentials;
discovery must work before those artifacts exist. Neither guarantees a future
generation will succeed.
### 5 Application commands and standard request flags
Decide the final generation command operands and application-specific flags
around the reusable ckprompt request flag groups. Use their standard names,
value-presence behavior, and parsing semantics wherever applicable.
Migration guidance will need to explain changes such as separate literal-text
and file-input flags, endpoint and timeout naming, and repeated mapping values.
In particular, upstream's optional `--input` alias denotes literal text, while
Scriptorium's existing flag denotes a file. Choose any upstream convenience
aliases deliberately and document the new meanings; preserving old meanings
is not a design requirement.
## Continuing the discussion
Record discussion notes under the relevant open decision. When a choice is
settled, move its conclusion and rationale into the agreed direction with its
decision date, and remove superseded alternatives. Add new questions when a
concrete product need emerges.
Once the command surface, consumer outputs and outcomes, loader and namespace
behavior, and any upstream gaps are settled, fold the decisions into a feature
roadmap. That roadmap will define implementation sequence, removal of replaced
CLI code, appropriate validation, and migration documentation. This notepad does
not prescribe implementation phases or treat the open proposals as commitments.
[upstream-guide]: https://forge.maximumdirect.net/base-layer/commandkit/src/commit/d330d7637f2e7507eca931a899397222c82bc892/docs/consumers/guide.md
[upstream-cli]: https://forge.maximumdirect.net/base-layer/commandkit/src/commit/d330d7637f2e7507eca931a899397222c82bc892/docs/cli.md