Settle application commands and prefer native convenience aliases
This commit is contained in:
@@ -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
|
||||
|
||||
@@ -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;
|
||||
|
||||
Reference in New Issue
Block a user