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

332 lines
18 KiB
Markdown
Raw Normal View History

# CommandKit migration notepad
Status: discussion record incorporated into the
[adoption roadmap](commandkit-adoption.md) and
[ADR 0006](../adr/0006-adopt-commandkit-native-operator-interfaces.md).
The roadmap owns implementation work; the ADR records the ownership decision.
## 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. Adopt upstream convenience aliases as described below.
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.
ConfigKit owns configuration policy through the fully resolved handoff,
including PromptKit configuration resolution. PromptKit owns prompting and
inspection semantics. Scriptorium interprets resolved values and uses upstream
APIs and results to satisfy user requests. CommandKit adoption does not introduce
workflow or conversation state. ADR 0006 records these boundaries.
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, concrete request validation, and prepared-request
preview.
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
capabilities is settled. The prepared-request preview decision is recorded 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 and available through the native result reporting choices below.
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.
### Native result reporting and separate report files
Decision revised 2026-11-19: use a main CommandKit `Report` containing PromptKit's
native `RunResult`, with a text template that emits only generated content.
Default/text output serves artifact consumers; standard JSON/YAML formats expose
the native result and its metadata. This composes existing upstream APIs;
ckprompt does not supply a general generation command or prescribe this template.
Include an optional `--report PATH` flag requiring an explicit file destination.
Omitting it creates no separate report file. When requested, pass the native
`RunResult` to CommandKit's renderer without an artifact-only text template.
Optional `--report-format text|yaml|json` selects the native rendering format.
When omitted, leave the format unset and let CommandKit choose; its current
structured-value default is YAML, and future upstream changes flow through.
There is no Scriptorium default or filename-based selection. Report rendering
is independent of the main result's `--format`, representation, and destination.
Failure to write a requested report is a delivery failure and must produce a
nonzero outcome and diagnostic.
Do not include a configured reporting directory or automatic report collection
in the initial migration. The caller selects the report path and manages its
lifecycle. A configured directory may be considered later if automatic
collection becomes useful; an explicit report path would take precedence.
Native result reports are available when PromptKit returns a result. Operational
failures produce a nonzero exit and native diagnostics. This follows PromptKit's
capabilities and is the intended boundary, not a gap for Scriptorium to address.
Do not synthesize replacement results or add an alternative failure-report
format to compensate for the absence of a native result.
### Output destinations and verbosity
Decision revised 2026-11-19: remove the previously selected `--output` flag.
The main result uses the native invocation reporter and stdout. Callers save it
through shell redirection or a subprocess stdout destination; diagnostics remain
on stderr. Do not retain the old `--out` flag.
`--format` selects the stdout representation independently of redirection:
default/text emits the raw artifact, while JSON/YAML emits the native result
with metadata. The filename does not select the format. `--report PATH` remains
an additional native result report, so callers can save the raw artifact and its
report to separate files by redirecting stdout and supplying `--report`.
Adopt CommandKit's upstream verbosity and `--quiet` semantics fully, including
mode selection, message visibility, rendering, and presentation failures. Do
not add Scriptorium-specific exceptions to normal command-output suppression.
Quiet mode does not cancel generation, and failure explanations remain visible
through the native diagnostic channel.
An explicit `--report` write remains an application-owned effect in quiet mode,
using the existing writer API. Quiet suppresses the main result even when stdout
is redirected; callers wanting that result omit quiet. No
selected-format accessor is needed, so the upstream proposal is no longer a
migration prerequisite. The [upstream reporting contract][upstream-cli] owns the
shared verbosity rules.
### Prepared-request preview
Decision recorded 2026-11-19: replace `render` entirely with the native
`promptkit show prepared PROMPT_ID` command, enabled through ckprompt's request
preparation integration. Remove `render` without a compatibility alias.
Use the native prepared-run report, standard request flags, diagnostics,
verbosity, and outcomes. Default and explicit text output use the upstream YAML
presentation; JSON remains available through `--format json`. Remove
`defaults.render_format` and any custom prepared-output formatting code left
unused by the migration.
Share application configuration selection, collection loading, and applicable
request construction with generation so previews describe the corresponding
execution request. PromptKit continues to own preparation semantics.
Use the native result stream for preview output; consumers can capture or
redirect stdout to save it, as with generation. File-output convenience does
not justify retaining a separate preview command. Update maintained examples
and release migration guidance to use `promptkit show prepared`.
### Configuration selection and namespaces
Decision recorded 2026-11-19: fully adopt native configuration and namespace
conventions. Expose the `app` and `promptkit` configuration scopes through
ckconfig. `app` inspects Scriptorium's application settings; `promptkit`
inspects the framework configuration assembled from the selected sources.
Collections do not become separate configuration scopes. Application-only
inspection must not require constructing a PromptKit engine.
`--config` consistently selects Scriptorium's application configuration,
including when inspecting the `promptkit` scope. That configuration selects
the framework sources and collection-discovery file. Adopt the standard
`--overlay` spelling and use consistent source-selection and loading rules
across generation, preview, inspection, requirements, and other applicable
commands. Keep the established ConfigKit collection-import model.
Enable the native prompt, profile, and backend namespace selectors on
applicable commands. They independently scope short caller-supplied resource
IDs; qualified IDs remain exact selections. Namespace selection does not
rewrite stored references or change collection discovery. Keep configuration
scope, resource namespace, and profile selection distinct.
Use native inventory filters, including namespace selection and
`--all-namespaces`, and retain upstream default listing behavior. Support
standard temporary configuration overrides where the upstream loader supports
them. The reviewed PromptKit configuration scope does not support those
overrides; do not add local override semantics to compensate.
Do not add configurable default namespaces in the initial migration. Use
qualified IDs and explicit namespace flags when selecting namespaced resources,
while retaining upstream behavior for unqualified IDs. Configurable defaults
can be considered later if a need arises.
### Native inspection reports and consumer requirements
Decision recorded 2026-11-19: adopt native inspection reports and the native
`promptkit requirements show` interface for Narratio's early dependency
discovery. Its consumer needs and acceptance scenarios are recorded in the
[aligned Narratio proposal](narratio-feature-request.md). This direction is
accepted; Scriptorium integration remains to be implemented.
Consume native report fields without a Scriptorium-specific schema-version
envelope. Use native nonzero outcomes and diagnostics for invocation failures;
JSON report selection does not require JSON errors. Neither a separately
versioned envelope nor programmatic invocation-failure categories blocks this
migration. A future concrete need for either belongs in an upstream discussion.
PromptKit owns requirement classification, discovery completeness, and structured
discovery issues. Completeness is distinct from satisfied bindings or execution
readiness; Narratio owns comparison against its planned inputs. Keep early
discovery separate from concrete request validation. Use current exact resource
identities and native input/variable metadata, without restoring obsolete prompt
versions or inventing input schemas or variable-default semantics.
Standard prompt inspection includes captured messages; prepared preview includes
rendered content. Adopt these native reports without rebuilding Scriptorium's
previous summary projections, and explain the changed presentation in migration
guidance. Requirements discovery retains its distinct upstream content boundary.
### Application commands and standard request flags
Decision recorded 2026-11-19: use `run PROMPT_ID` for generation, with the prompt
as a required positional operand and no duplicate prompt-selection flag. Keep
`serve` as the application command for the HTTP service. Both are CommandKit
commands owned by Scriptorium, outside the reserved `config` and `promptkit`
families. The CLI migration does not redesign the HTTP API.
Reuse ckprompt's applicable resource, input, and execution flag bindings.
Preserve native parsing, explicit-value presence, repeated mapping semantics,
and PromptKit's interpretation of request values. Keep application-specific
configuration/source selection, `--report`/`--report-format`, server options,
and the whole-operation deadline separate from framework request controls.
Enable upstream convenience aliases consistently on applicable commands,
including `run`. Prefer their shorter spellings in user-facing documentation,
examples, migration guidance, and subprocess integration examples wherever they
are applicable and unambiguous. For example, prefer `--profile`, `--input-file`,
`--input-text`, and `--var` over their `--llm-*` equivalents. Canonical upstream
spellings remain available with identical semantics; the preference does not
remove or rename them.
Aliases retain upstream meanings. In particular, `--input` supplies literal
text; file references use `--input-file`. Migration guidance must explain this
change along with endpoint and timeout naming and repeated mapping values.
Use the canonical spelling where a shorter alias would be ambiguous; do not
assign an upstream alias a different application-specific meaning.
## 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.
## Details for the feature roadmap
The product and interface direction is settled. The following details need
concrete implementation choices in the roadmap, but do not require another
architectural discussion before drafting it.
### Outcomes and process lifecycle
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. Specify their mapping to the CommandKit invocation context
and PromptKit operation timeout, including the application deadline flag and
units, separately from the standard per-attempt timeout flag.
### File delivery
The roadmap and implementation plan specify ordinary report-file handling and
delivery ordering relative to stdout. The caller owns redirected destinations;
Scriptorium does not infer them or check for collisions with the report path.
Partial delivery follows native outcomes and the agreed result-availability
boundary.
### Adoption and verification
Confirm the released dependency combination, complete the application-specific
flag and loader mappings, and sequence replacement and removal of CLI code.
Define appropriate verification for the selected behavior and update canonical
documentation, examples, and release migration guidance as implementation lands.
## Roadmap handoff
The [adoption roadmap](commandkit-adoption.md) incorporates these decisions and
integration details. Keep implementation status there; retain this notepad as
the discussion record.
[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