246 lines
13 KiB
Markdown
246 lines
13 KiB
Markdown
# 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.
|
|
|
|
### Generation and subprocess requirements
|
|
|
|
Decision recorded 2026-11-19: optimize the default generation response for the
|
|
majority of consumers, who want only the raw resulting artifact. Metadata is
|
|
optional. Consumers requesting it may receive it inline with the content or in
|
|
a separately saved report; either is acceptable, and both may be supported if
|
|
convenient. Supporting both delivery modes is not a requirement.
|
|
|
|
Prefer native CommandKit reporting and PromptKit result types before introducing
|
|
a Scriptorium-specific response format. A failure must produce a nonzero process
|
|
status and information explaining the failure. This does not require a new
|
|
structured error envelope: native diagnostics are an acceptable way to deliver
|
|
that information.
|
|
|
|
Scriptorium remains a neutral interface to PromptKit. Pass through the errors,
|
|
validation outcomes, and result information that PromptKit supplies rather than
|
|
adding independent judgments about generated content or redefining upstream
|
|
failure semantics. Adapting those outcomes to CommandKit and process exit codes
|
|
is application work; deciding what constitutes a PromptKit failure is not.
|
|
|
|
## 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 consumer requirements above are settled. The proposed native composition is
|
|
a CommandKit `Report` whose value is PromptKit's `RunResult`, with a text
|
|
template that emits only generated content. Default/text output would serve
|
|
artifact consumers; standard JSON/YAML formats would expose the native result
|
|
and its metadata. This uses CommandKit's existing reporting mechanism and
|
|
PromptKit's existing result shape; ckprompt does not supply a general generation
|
|
command or prescribe this composition. Confirm this choice and decide whether
|
|
separate report-file delivery adds enough value to include it as well.
|
|
|
|
PromptKit's `RunResult` includes content, validation, selected resources, usage,
|
|
and timing. Operational failures return no partial `RunResult`; observer events
|
|
separately expose terminal metadata, retry counts, and presence-aware usage.
|
|
Do not invent an empty or synthetic success result to represent a failure.
|
|
Use native failure diagnostics, and consider additional observation reporting
|
|
only if a concrete consumer need warrants it.
|
|
|
|
Settle explicit artifact-file output and its interaction with report selection
|
|
and standard verbosity controls. Quiet mode suppresses CommandKit output but
|
|
does not cancel execution; application-owned file effects need an explicit
|
|
design.
|
|
|
|
Map PromptKit's typed errors and reported outcomes into CommandKit conventions,
|
|
preserving its distinction between a completed content check reporting
|
|
`ValidationFailed` and an operational error. Select any necessary domain exit
|
|
code without reusing the current validation-failure exit 2, which conflicts with
|
|
CommandKit's usage convention. Also specify artifact/report delivery failures
|
|
using CommandKit's presentation-failure behavior where applicable. These are
|
|
adapter mappings, not a new application validation policy.
|
|
|
|
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
|