Settle application commands and prefer native convenience aliases

This commit is contained in:
2026-11-19 18:20:17 +00:00
parent 8078c6ecc7
commit 5f32a4f2ad
2 changed files with 58 additions and 34 deletions

View File

@@ -1,9 +1,9 @@
# 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.
Status: design direction agreed; ready for feature-roadmap preparation. This
working record captures the decisions for Scriptorium's CommandKit migration.
The remaining integration details below belong in the roadmap alongside
implementation sequencing and validation.
## Product context
@@ -34,7 +34,7 @@ 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.
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;
@@ -234,6 +234,34 @@ 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, `--output`, `--report`, 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
@@ -257,13 +285,13 @@ The [upstream CLI reference][upstream-cli] owns the detailed conventions. The
[subprocess contract](../integrations/subprocess.md) describe the starting point,
not requirements to reproduce during migration.
## Open decisions
## Details for the feature roadmap
### 1 Generation integration details
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.
The consumer requirements, native result reporting, output destinations, and
verbosity decisions above are settled. The remaining work is to specify their
integration in the feature roadmap.
### Outcomes and process lifecycle
Map PromptKit's typed errors and reported outcomes into CommandKit conventions,
preserving its distinction between a completed content check reporting
@@ -274,35 +302,31 @@ 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.
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.
### 2 Application commands and standard request flags
### File delivery
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.
Specify ordinary path handling, overwriting, parent-directory behavior,
destination collisions, and delivery ordering for `--output` and `--report`.
Describe partial delivery consistently with native outcome reporting and the
agreed upstream result-availability boundary.
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.
### Adoption and verification
## Continuing the discussion
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.
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.
## Preparing the roadmap
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.
Fold the agreed decisions and remaining integration details into a feature
roadmap. Preserve the selected upstream conventions and explicit non-goals.
Record any concrete new issue found during preparation without reopening settled
product choices merely to preserve the old CLI. This notepad remains the
discussion record until its decisions have been incorporated into that roadmap.
[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

View File

@@ -28,7 +28,7 @@ The [upstream CLI contract][requirements-cli] owns syntax and report details.
Use the same application configuration and framework source selection as
execution, including `--config`, `--overlay`, and applicable application
selectors. The native `--llm-profile`, `--llm-var`, `--llm-session-id`, and
selectors. The preferred native aliases `--profile`, `--var`, `--session-id`, and
prompt/profile namespace flags supply the relevant discovery context.
Preserve upstream selection semantics, including the prompt's default profile
when an explicit profile is omitted. Qualified IDs identify installed resources;