Settle application commands and prefer native convenience aliases
This commit is contained in:
@@ -1,9 +1,9 @@
|
|||||||
# CommandKit migration notepad
|
# CommandKit migration notepad
|
||||||
|
|
||||||
Status: discussion in progress. This is the working record for agreeing on
|
Status: design direction agreed; ready for feature-roadmap preparation. This
|
||||||
Scriptorium's CommandKit migration before preparing a feature roadmap. It
|
working record captures the decisions for Scriptorium's CommandKit migration.
|
||||||
captures direction, open decisions, and discussion notes; implementation scope
|
The remaining integration details below belong in the roadmap alongside
|
||||||
and sequencing will follow once the relevant decisions are settled.
|
implementation sequencing and validation.
|
||||||
|
|
||||||
## Product context
|
## 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
|
Legacy command names, flag spellings, parsing rules, report shapes, and exit
|
||||||
semantics do not constrain the new interface. Do not add compatibility wrappers,
|
semantics do not constrain the new interface. Do not add compatibility wrappers,
|
||||||
legacy aliases, or duplicate inspection implementations solely to preserve the
|
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
|
Provide migration guidance in release documentation so consumers can update
|
||||||
their invocations and output handling. Guidance replaces a compatibility layer;
|
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
|
previous summary projections, and explain the changed presentation in migration
|
||||||
guidance. Requirements discovery retains its distinct upstream content boundary.
|
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
|
## Upstream baseline
|
||||||
|
|
||||||
The initial review covered CommandKit **v0.7.0**, ckconfig **v0.9.0**, and
|
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,
|
[subprocess contract](../integrations/subprocess.md) describe the starting point,
|
||||||
not requirements to reproduce during migration.
|
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
|
### Outcomes and process lifecycle
|
||||||
verbosity decisions above are settled. The remaining work is to specify their
|
|
||||||
integration in the feature roadmap.
|
|
||||||
|
|
||||||
Map PromptKit's typed errors and reported outcomes into CommandKit conventions,
|
Map PromptKit's typed errors and reported outcomes into CommandKit conventions,
|
||||||
preserving its distinction between a completed content check reporting
|
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.
|
adapter mappings, not a new application validation policy.
|
||||||
|
|
||||||
Signal cancellation and the whole-operation deadline remain application
|
Signal cancellation and the whole-operation deadline remain application
|
||||||
responsibilities. Decide their mapping to the CommandKit invocation context
|
responsibilities. Specify their mapping to the CommandKit invocation context
|
||||||
and PromptKit operation timeout, separately from the standard per-attempt
|
and PromptKit operation timeout, including the application deadline flag and
|
||||||
timeout flag.
|
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
|
Specify ordinary path handling, overwriting, parent-directory behavior,
|
||||||
around the reusable ckprompt request flag groups. Use their standard names,
|
destination collisions, and delivery ordering for `--output` and `--report`.
|
||||||
value-presence behavior, and parsing semantics wherever applicable.
|
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
|
### Adoption and verification
|
||||||
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
|
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
|
## Preparing the roadmap
|
||||||
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
|
Fold the agreed decisions and remaining integration details into a feature
|
||||||
behavior, and any upstream gaps are settled, fold the decisions into a feature
|
roadmap. Preserve the selected upstream conventions and explicit non-goals.
|
||||||
roadmap. That roadmap will define implementation sequence, removal of replaced
|
Record any concrete new issue found during preparation without reopening settled
|
||||||
CLI code, appropriate validation, and migration documentation. This notepad does
|
product choices merely to preserve the old CLI. This notepad remains the
|
||||||
not prescribe implementation phases or treat the open proposals as commitments.
|
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-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
|
[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
|
Use the same application configuration and framework source selection as
|
||||||
execution, including `--config`, `--overlay`, and applicable application
|
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.
|
prompt/profile namespace flags supply the relevant discovery context.
|
||||||
Preserve upstream selection semantics, including the prompt's default profile
|
Preserve upstream selection semantics, including the prompt's default profile
|
||||||
when an explicit profile is omitted. Qualified IDs identify installed resources;
|
when an explicit profile is omitted. Qualified IDs identify installed resources;
|
||||||
|
|||||||
Reference in New Issue
Block a user