Plan the CommandKit adoption sprint
This commit is contained in:
555
docs/roadmap/implementation.md
Normal file
555
docs/roadmap/implementation.md
Normal file
@@ -0,0 +1,555 @@
|
||||
# CommandKit Adoption Implementation Plan
|
||||
|
||||
## Purpose And Execution
|
||||
|
||||
Implement the target in the [CommandKit adoption roadmap](commandkit-adoption.md).
|
||||
This plan owns the implementation steps and concrete adapter choices; the roadmap
|
||||
owns product intent and target behavior. The [migration notepad](commandkit-notepad.md)
|
||||
records the discussion. [ADR 0006](../adr/0006-adopt-commandkit-native-operator-interfaces.md),
|
||||
[ADR 0005](../adr/0005-configkit-boundary.md), and
|
||||
[ADR 0004](../adr/0004-definition-boundary.md) remain authoritative.
|
||||
|
||||
Audience: a Luna coding agent implementing one numbered stage per prompt, in
|
||||
order, as one end-to-end sprint. Intermediate stages may leave compilation or
|
||||
tests temporarily broken. Do not build compatibility dispatch, parallel CLI
|
||||
surfaces, feature toggles, or temporary abstractions to make intermediate stages
|
||||
shippable. The final assembled application is the completion boundary. Add the
|
||||
stage's relevant tests with its implementation; run focused checks when runnable
|
||||
and record deferred checks for Stage 9. Follow the agent policy for focused
|
||||
commits, accurately identifying incomplete validation.
|
||||
|
||||
Start with [development guidance](../development.md). Read the applicable
|
||||
[agent](../policy/agents.md), [architecture](../policy/architecture.md),
|
||||
[testing](../policy/testing.md), [documentation](../policy/documentation.md), and
|
||||
[OSS](../policy/oss.md) policies. Use the [release policy](../policy/release.md)
|
||||
for release-related documentation and build metadata. Preserve unrelated work.
|
||||
This plan does not authorize release publication, upstream repository changes,
|
||||
or rewriting accepted ADR decisions.
|
||||
|
||||
Planning baseline: `bcb1a76e345ef7f3720dcbce7c446beb0d9db23b`.
|
||||
The current application uses Go 1.27.0, ConfigKit v1.2.1, and PromptKit v0.23.3,
|
||||
with validation/build toolchain Go 1.27.4. Relevant starting components are
|
||||
`cmd/scriptorium`, `internal/adapter/cli`, `internal/config`, `internal/format`,
|
||||
`internal/report`, and the unchanged `internal/adapter/http`.
|
||||
|
||||
## Dependency Prerequisite And Selected Integration
|
||||
|
||||
The reviewed public APIs are documented at CommandKit revision
|
||||
`d330d7637f2e7507eca931a899397222c82bc892` in its
|
||||
[consumer guide][upstream-guide] and [CLI contract][upstream-cli]. The released
|
||||
baseline is:
|
||||
|
||||
| Module | Reviewed release | Release source commit |
|
||||
| --- | --- | --- |
|
||||
| `go.maximumdirect.net/commandkit` | v0.7.0 | `b57bfe176cff05a892e6cb07ebb5f350239e55d4` |
|
||||
| `go.maximumdirect.net/ckconfig` | v0.9.0 | `9962368f0c1ea1f6ad010638e94621091105d745` |
|
||||
| `go.maximumdirect.net/ckprompt` | v0.10.0 | `c9a56e1b15f2169881a91fca4e1f4a1c475e057a` |
|
||||
|
||||
There is one approved external prerequisite. CommandKit v0.7.0 has the public
|
||||
`RenderReport(writer, report, format)` API but does not expose the invocation's
|
||||
selected format. Its invocation reporter suppresses console writes in quiet
|
||||
mode. Consequently that release alone cannot implement the agreed formatted
|
||||
`--output` behavior, including quiet-mode file delivery, through the intended
|
||||
APIs. The user selected a **released upstream selected-format accessor** as the
|
||||
solution. Adopt that capability before implementing Stage 6. Its final exported
|
||||
name and release number are determined upstream, not invented here.
|
||||
|
||||
Keep ckconfig v0.9.0 and ckprompt v0.10.0 if they compose with the released core
|
||||
addition; adopt corresponding released integration updates only if needed for
|
||||
that capability. Preserve ConfigKit v1.2.1 and PromptKit v0.23.3 unless that
|
||||
necessary released combination requires a separately reviewed change. In
|
||||
particular, ckprompt's PromptKit v0.23.2 minimum is not a reason to downgrade.
|
||||
Do not opportunistically expand this sprint into another framework upgrade.
|
||||
|
||||
Stage 1 confirms the actual release and API. If unavailable, record the external
|
||||
dependency and leave the affected work incomplete pending its release. Do not
|
||||
silently reduce the output contract, parse reporting flags again, use reflection
|
||||
or private APIs, or commit a local module replacement. The upstream addition is
|
||||
not an unresolved product choice and is not work to implement in this repository.
|
||||
|
||||
## Settled Application Choices
|
||||
|
||||
### Command And Selection Mapping
|
||||
|
||||
Install the native `config` and `promptkit` families, plus application commands
|
||||
`run PROMPT_ID` and `serve`. Use `ckprompt.Declarations` to install native
|
||||
convenience aliases. Install equivalent command-scoped aliases for applicable
|
||||
reused bindings on `run`; do not add legacy command aliases or a duplicate prompt
|
||||
flag. Native help, version, completion, format, verbosity, and outcomes replace
|
||||
their old counterparts without a compatibility parser.
|
||||
|
||||
| Input | Application mapping |
|
||||
| --- | --- |
|
||||
| `--config` | Application main-source selection on every configuration-consuming command, including the `promptkit` scope and family. Preserve explicit presence, including an empty value. |
|
||||
| `--overlay` | Pass the supplied value to ConfigKit's `Options.Overlay`. At v1.2.1 this is a name, not a filesystem path: native empty/default selection and `overlays/NAME.yml` lookup apply. Do not add a second overlay interpreter or a fallback root. |
|
||||
| Repeated `--promptkit-source PATH` | Replace the complete `promptkit_sources` list during ConfigKit loading with the selected files/directories in occurrence order, as a native override. Retain the useful existing file/directory classification, without comma splitting. |
|
||||
| `--schema-dir` | Presence-aware override of application `schema_dir`. |
|
||||
| `--addr`, `--artifact-root`, `--max-request-bytes`, `--max-artifact-bytes`, `--max-response-bytes` | Presence-aware application `server` overrides; available on `serve` and application-scope configuration inspection. |
|
||||
| `config ... --set POINTER=JSON` | Ordered native override records for `app`; append after named application-selector overrides so native assignments are authoritative when both address the same value. Enable the feature only on `app`. |
|
||||
| `config diff --against-*` | Independent right-side selections and corresponding application-selector overrides, initialized independently rather than inherited from the left. |
|
||||
| `--run-timeout DURATION` on `run` | `time.ParseDuration`, then unchanged into `RunRequest.OperationTimeout`. Positive values add the native operation budget; zero and negative values add none under PromptKit v0.23.3. No second application timer or positivity restriction. |
|
||||
| Native `--llm-timeout-seconds` / `--timeout-seconds` | Integer per-attempt timeout through the ckprompt execution binding; no old duration conversion. |
|
||||
|
||||
Framework selectors (`promptkit-source`, `schema-dir`) apply to both config
|
||||
scopes and to the native PromptKit family. Server selectors apply to the `app`
|
||||
scope only. Provide each config selector with its matching `AgainstName`, such
|
||||
as `against-promptkit-source`, `against-schema-dir`, or `against-addr`.
|
||||
`run` accepts the framework selectors, request controls, and delivery controls;
|
||||
it does not need server-only flags. `serve` accepts framework and server
|
||||
selectors, not generation request controls. The configured `transient_retries`
|
||||
value remains an engine default; the native execution flag overrides a request.
|
||||
|
||||
ConfigKit remains responsible for loading and all precedence, resolution, and
|
||||
inspection semantics. The override ordering above selects library inputs; it
|
||||
does not authorize post-load merging. Keep cwd-relative application path values,
|
||||
the existing discovery locations, and source-relative PromptKit resources.
|
||||
|
||||
### Outcomes And Delivery
|
||||
|
||||
| Condition | Outcome |
|
||||
| --- | --- |
|
||||
| Completed run without `ValidationFailed` | Native success, status 0, subject to delivery. |
|
||||
| Completed run with `ValidationFailed` | `commandkit.Domain("validation_failed", 4)` with a useful explanation; deliver the returned artifact and native result. |
|
||||
| Syntax, declaration-input, or destination-combination errors | Native usage, status 2. |
|
||||
| Configuration load errors | Use `ckconfig.ClassifyConfigurationError` and native diagnostic evidence: usage 2 for classified invalid configuration, otherwise operational 1. |
|
||||
| Lookup, preparation, generation, capacity, operation-timeout, cancellation, or other operational errors | Operational 1 with safe explanation and preserved typed cause. Request failures are not completed content-validation failures. |
|
||||
| Native `config diff --check` differences | Native status 3, unchanged. |
|
||||
| Result or diagnostic presentation failure | Preserve CommandKit's finalization rules: success/usage become operational 1; a nonzero domain status remains nonzero and retains its classification. |
|
||||
| Explicit file delivery failure | Operational 1 for an otherwise successful run. Preserve an already nonzero domain status 4 while adding the delivery explanation/cause. Attempt remaining requested delivery. |
|
||||
|
||||
Use `errors.Is`/`errors.As`, not error-text matching. Apply cancellation and
|
||||
typed operation-timeout handling before configuration classification. Do not
|
||||
classify every `ErrInvalidConfig` wrapper as invalid user input without native
|
||||
evidence. Retain safe explanations for provider failures; causes are inspectable
|
||||
Go errors, not permission to print credential-bearing provider payloads.
|
||||
|
||||
Use one `commandkit.Report` with the actual `*promptkit.RunResult` as `Value`.
|
||||
Its reusable text template emits `Artifact.Body` as bytes represented as a string,
|
||||
with no added newline, header, escaping, or summary. Native JSON/YAML serialization
|
||||
remains upstream-owned, including byte representation and native metadata.
|
||||
|
||||
Without `--output`, submit the report through the invocation reporter. With
|
||||
`--output PATH`, render through `commandkit.RenderReport` to that file using
|
||||
the upstream selected-format accessor; do not also submit a console result.
|
||||
`--report PATH` additionally renders the same native result as JSON, regardless
|
||||
of main format or destination. Explicit files are application effects and are
|
||||
written even in quiet mode. No separate report is created when the flag is absent.
|
||||
|
||||
Use ordinary create/truncate file operations (mode 0644 for newly created files,
|
||||
subject to umask), preserve normal OS behavior for existing files, and handle
|
||||
render/write/close errors. Do not create parent directories. Explicit empty
|
||||
destination values are usage errors; `-` is an ordinary filename. Before
|
||||
generation, reject output/report paths known to identify the same file using
|
||||
cleaned absolute path equality and `os.SameFile` for existing destinations.
|
||||
This is a best-effort collision check, not a filesystem-race guarantee.
|
||||
|
||||
Once a result is available, attempt main delivery first, then the separate
|
||||
report, even if the first attempt fails. Do not precreate or truncate files
|
||||
before a result exists. No native result means no replacement report or output
|
||||
file; an existing destination can remain from a previous invocation. Delivery
|
||||
is nontransactional: written bytes remain after failure. No rollback, atomic
|
||||
replacement, symlink sandbox, or additional filesystem hardening is requested.
|
||||
|
||||
## Stage 1: Select Released Dependencies And Establish Command Composition
|
||||
|
||||
**Primary files:** `go.mod`, `go.sum`, `internal/adapter/cli` composition,
|
||||
`docs/oss/attribution.md`, and applicable `docs/oss/licenses/` texts.
|
||||
|
||||
1. Verify the released selected-format accessor prerequisite above and select
|
||||
the minimal compatible released module combination. Record the actual
|
||||
versions and complete source commits in this plan's implementation status
|
||||
and attribution entries as appropriate; use released modules, not sibling
|
||||
checkouts, workspaces, vendoring, or replacements.
|
||||
2. Add CommandKit, ckconfig, and ckprompt dependencies. Keep the existing Go
|
||||
minimum and validation toolchain unless the selected addition supplies a
|
||||
concrete contrary requirement; raise such an expansion rather than guessing.
|
||||
Verify selected PromptKit/ConfigKit versions and tidy the module metadata.
|
||||
3. Create the CLI composition entry point in `internal/adapter/cli`. Accept a
|
||||
context, application identity, argv, and output streams; let `App.Execute`
|
||||
own parsing and finalization and return its outcome/status to the entrypoint.
|
||||
Keep package/file choices straightforward rather than introducing a new
|
||||
framework or interface for each factory.
|
||||
4. Establish declarations for `run`, `serve`, the native configuration suite,
|
||||
native PromptKit suite, and `commandkit.Completion("scriptorium")`. Fill the
|
||||
application loaders and handlers in later stages. Native root/group/help
|
||||
behavior replaces the dispatch switch. Declaration construction, help,
|
||||
version, scope discovery, and static completion must not load application
|
||||
or framework configuration or invoke providers.
|
||||
5. Apply the OSS House Format to CommandKit, ckconfig, and ckprompt using their
|
||||
actual release commits and module-subdirectory notice paths. Inspect linked
|
||||
dependencies, including Cobra, pflag, and any applicable mousetrap use,
|
||||
rather than treating every module-graph tool as a runtime dependency.
|
||||
Reuse existing verbatim license texts and add missing applicable ones.
|
||||
Preserve current project licensing and notice navigation.
|
||||
|
||||
**Evidence:** selected module metadata has no replacements or unintended
|
||||
PromptKit downgrade; declaration construction is valid when wired; help/version
|
||||
can be exercised without a readable application configuration. Check notice
|
||||
paths against the selected commits. Final composed behavior is checked in Stage 9.
|
||||
|
||||
## Stage 2: Adapt Authoritative Application Loading And Shared Selectors
|
||||
|
||||
**Primary files:** `internal/config/{load,document,settings}.go`, their tests,
|
||||
and CLI application-loading/source-selector helpers.
|
||||
|
||||
1. Retain one `configkit.Load` boundary returning its actual
|
||||
`*configkit.Result[Document]`. Adapt selection into `LoadOptions` or its
|
||||
replacement: explicit config presence chooses `File`, omission chooses the
|
||||
existing ordered `SearchConfig`, imports remain enabled, and overlay and
|
||||
override records go directly into ConfigKit. Preserve wrapped error identity.
|
||||
Respect the invocation context at the application boundary without claiming
|
||||
ConfigKit's synchronous work can be forcibly interrupted.
|
||||
2. Replace `flag.FlagSet.Visit` and parser-owned override collection with typed
|
||||
CommandKit bindings retaining `Supplied.Set`. Convert only supplied
|
||||
application selectors into correctly labeled ConfigKit overrides, then append
|
||||
native `Selection.Overrides` as specified above. Keep source-list order and
|
||||
replacement. Use ordinary OS classification for explicitly supplied source
|
||||
paths; do not load framework definitions during application inspection.
|
||||
Preserve the existing nonnegative `int64` domain for HTTP byte limits,
|
||||
including zero as unlimited; do not narrow it to a platform `int` or add a cap.
|
||||
3. Keep schema, defaults, normalization, and domain validation inside the
|
||||
existing ConfigKit definition callbacks. Record normalization through native
|
||||
`configkit.Normalize`/resolution evidence. `Settings` remains a conversion
|
||||
of completed values, not another resolver or merger.
|
||||
4. Remove `Document.Defaults`, `DefaultsDocument`, `defaults.render_format`,
|
||||
`AppSettings.DefaultRenderFormat`, associated normalization/validation, and
|
||||
the resulting `internal/config` dependency on `internal/format`. Strict
|
||||
ConfigKit decoding handles the retired field; add no compatibility mapping.
|
||||
5. Retain shared engine construction from resolved settings: one ordered
|
||||
underlay per app selector, import-enabled file inputs, directory expansion
|
||||
through `promptkit.DirectoryInputs`, no implicit main, existing schema base
|
||||
and engine retry setting, and the default upstream bundle. Do not change
|
||||
collection traversal, peer composition, or whole-record replacement.
|
||||
6. Use fresh application input per comparison side and invocation-owned state
|
||||
under the native factory lifecycle; comparison may share that state without
|
||||
sharing either side's selected values. Start without an engine/config cache:
|
||||
separately reached loads are ordinary
|
||||
loads, not an immutable-snapshot contract. Server engine lifetime is handled
|
||||
separately in Stage 7. Small invocation state for acquisition diagnostics is
|
||||
acceptable and must not alter effective configuration.
|
||||
|
||||
**Evidence:** real ConfigKit-backed tests cover omitted versus explicit-empty
|
||||
config/overlay selection, a supplied zero or empty app override, native `--set`
|
||||
precedence, ordered source replacement, normalized values and their evidence,
|
||||
and removal of `render_format`. Reuse existing import/search/source tests;
|
||||
do not reproduce ConfigKit's exhaustive composition matrix.
|
||||
|
||||
## Stage 3: Install Native Configuration Scopes And Independent Comparison
|
||||
|
||||
**Primary files:** CLI configuration-suite composition and loaders; replace
|
||||
`internal/adapter/cli/config.go` and `framework_config.go` responsibilities.
|
||||
|
||||
1. Construct `ckconfig.Command(ckconfig.Suite[...])` with `app` from
|
||||
`ckconfig.FromConfigKit` and `promptkit` from `ckprompt.ConfigScope`.
|
||||
Enable native validate/show/sources/explain/diff and supported path/metadata
|
||||
modes. Keep native scope discovery and default scope selection.
|
||||
2. Mark only the application scope as supporting temporary overrides, passing
|
||||
those records through Stage 2. Retain the PromptKit scope's native disabled
|
||||
override feature, including native capability checks for all-scope requests.
|
||||
3. Install selectors with their scopes and independent `AgainstName` bindings
|
||||
from the mapping above. Use fresh `NewInput` results, not shared pointers.
|
||||
Each comparison loader must consume that side's `Selection` and input;
|
||||
do not cache the first engine into the second side. Delegate comparisons
|
||||
to the returned native adapters instead of assembling a synthetic document.
|
||||
4. Preserve native view metadata, findings, sources, path discovery, explanation,
|
||||
redaction, diff reports, and failure classification. No local source DTO,
|
||||
JSON Pointer interpretation, custom effective document, explanation-tree
|
||||
reconciliation, or replacement formatter is needed.
|
||||
5. Route application-load diagnostics for framework acquisitions through
|
||||
`ckconfig.AdaptDiagnostics` and `commandkit.Acquired` diagnostics/explanations,
|
||||
retaining the adapter's existing framework evidence. Small callback
|
||||
decoration may attach application acquisition messages; do not insert app
|
||||
findings into the PromptKit configuration view or merge their evidence trees.
|
||||
Retain diagnostics from each reached comparison side and label their context.
|
||||
Application-scope acquisition itself stays with `FromConfigKit`.
|
||||
|
||||
**Evidence:** app inspection works even with unreadable framework sources;
|
||||
framework inspection uses sources selected by `--config`/`--overlay`; native
|
||||
show and explain agree with the resolved callback values. Exercise native
|
||||
root/index/escaped-key paths and redaction through representative integration
|
||||
cases, independent left/right configs/overlays/selectors, and diff-check status 3.
|
||||
Verify app overrides are available and framework overrides are not emulated.
|
||||
|
||||
## Stage 4: Install Native PromptKit Resources, Requirements, And Preview
|
||||
|
||||
**Primary files:** CLI PromptKit-suite composition, engine-loading adapters,
|
||||
and behavior tests replacing custom definition/prepared inspection tests.
|
||||
|
||||
1. Compose `ckprompt.FromEngine`, `WithRequestValidation`,
|
||||
`WithRequestPreparation`, and `WithSmokeTesting`, using the common application
|
||||
selection and engine loading from Stage 2. Enable all twelve callbacks:
|
||||
five inventories, three named resource inspections, requirements discovery,
|
||||
concrete validation, preparation, and smoke testing.
|
||||
2. Enable `ckprompt.WithNamespaces` with empty application defaults and install
|
||||
`ckprompt.Declarations`. Let the adapters apply their native engine views;
|
||||
the common engine loader returns an unscoped engine. Retain inventory filters
|
||||
and default listing behavior rather than forcing all namespaces.
|
||||
3. Request builders should be nil where the seed already is the desired
|
||||
request. If application mapping needs a builder, start with the supplied
|
||||
seed and preserve its fields, explicit values, and namespace context; do not
|
||||
reread bindings or merge a different request after the builder returns.
|
||||
The configured retry default belongs in the engine, not a second request pass.
|
||||
4. Carry application acquisition diagnostics through the native callback return
|
||||
channels as in Stage 3, preserving framework messages and typed failures.
|
||||
Let CommandKit control presentation and verbosity; do not write directly to
|
||||
stderr from loaders or suppress native reports based on local interpretations.
|
||||
5. Expose native prompt messages, profile/backend inspection, and prepared-run
|
||||
reports as returned, including their content-bearing nature. No old summary
|
||||
projection or local schema-version envelope. Preview remains native
|
||||
`promptkit show prepared PROMPT_ID`, with native text/YAML/JSON behavior and
|
||||
stdout capture for file saving.
|
||||
6. Keep discovery distinct from preparation: requirements discovery does not
|
||||
need generated input artifacts, model credentials, schemas, provider calls,
|
||||
or a generation output path. Loading configuration and captured message
|
||||
resources is still expected. Concrete validation/preview keep their upstream
|
||||
preparation-time prerequisites. Do not reject partial discovery or convert
|
||||
unsuccessful/unsupported smoke findings into extra application failures.
|
||||
|
||||
**Evidence:** implement the nine linked
|
||||
[Narratio scenarios](narratio-feature-request.md#consumer-acceptance-scenarios)
|
||||
with a small set of real-library fixtures covering exact required names,
|
||||
undeclared references, optional/conditional inputs, variable presence including
|
||||
empty values, complete versus partial reports, profile/prompt identity, and
|
||||
selection failures. Check native inventories/namespace filters, one named report
|
||||
per resource kind, and preparation/validation without generation. Smoke-test
|
||||
wiring uses a controlled local provider or injected public LLM client, never real
|
||||
credentials or paid calls. Reuse fixture coverage rather than duplicating the
|
||||
upstream analysis or rendering suite.
|
||||
|
||||
## Stage 5: Implement Positional Generation, Request Mapping, And Outcomes
|
||||
|
||||
**Primary files:** the new application `run` declaration, request/outcome
|
||||
helpers in `internal/adapter/cli`, and run integration tests.
|
||||
|
||||
1. Declare exactly one required positional `PROMPT_ID` with CommandKit, using
|
||||
shared app config/overlay/framework-selector bindings. Reuse
|
||||
`ckprompt.NewResourceFlags` for profile and session selection,
|
||||
`NewPromptInputFlags` for variables/text/files, and `NewExecutionFlags` for
|
||||
all native execution controls. Do not install the reusable prompt flag:
|
||||
the operand supplies that ID. The native run request has no direct backend-ID
|
||||
override, so do not invent a backend flag or synthetic profile for `run`.
|
||||
2. Map the bound values directly into a native `RunRequest` (profile, session,
|
||||
inputs, vars, execution, retry count). Preserve pointers and explicit values
|
||||
rather than implementing local inheritance/clearing rules. Keep native
|
||||
assignment semantics: first `=` separates a mapping, commas are literal,
|
||||
and the last text/file occurrence for an input wins.
|
||||
3. Install the native short convenience spellings on `run` with
|
||||
`commandkit.FlagAliasFor`, matching the reused binding meanings. Cover
|
||||
profile/session, var, input-text/input-file, all execution controls, and
|
||||
`--input`/`--llm-input` as literal-text aliases. Do not retain `--out`,
|
||||
`--execution-report`, `--llm-base-url`, old `--timeout`, `--prompt-id`, or
|
||||
`--profile-id` merely for compatibility.
|
||||
4. For `run`, declare the three standard namespace flags and convenience aliases
|
||||
through ordinary typed CommandKit string flags. The reviewed reusable
|
||||
resource bindings do not export namespace bindings; use public
|
||||
`Engine.WithNamespaces(promptkit.Namespaces{...})`, which is the supported
|
||||
application-engine-view integration. Leave validation of namespace values
|
||||
and ID selection to PromptKit. No local qualification or rewriting of stored
|
||||
references, and no configurable default namespace.
|
||||
5. Pass the invocation context to `Engine.Run` and map `--run-timeout` unchanged
|
||||
to `OperationTimeout`. Keep generation single-dispatch at the adapter level;
|
||||
retries, repairs, backend admission, credentials, and preparation belong
|
||||
upstream. Do not call `ValidateRequest` first as a new execution prerequisite.
|
||||
6. Implement the outcome table above. A completed invalid result is still
|
||||
delivered and returns domain status 4. A resultless operational error has
|
||||
no synthesized result or alternative report shape. Treat an unexpected nil
|
||||
result without an error as an operational integration failure, not success.
|
||||
Preserve typed causes and safe terminal explanations.
|
||||
7. Build the native result report/text template and submit stdout results
|
||||
through the invocation reporter. Keep any retained generation summary as a
|
||||
native Info message, normally hidden at ordinary verbosity. Stage 6 adds
|
||||
explicit destinations without changing the result shape.
|
||||
|
||||
**Evidence:** real-engine/controlled-provider tests exercise the assembled
|
||||
positional command, preferred aliases, literal/file precedence, comma-containing
|
||||
values, numeric zero and reasoning empty values, service tier/extra parameters,
|
||||
qualified IDs and independent namespaces, raw byte output, native structured
|
||||
serialization, completed invalid content/status 4, and resultless operational
|
||||
failure/status 1. Include a small typed-error mapping table rather than parsing
|
||||
error prose. Use native config classification for representative load failures.
|
||||
|
||||
## Stage 6: Add Explicit Output And Native JSON Report Delivery
|
||||
|
||||
**Primary files:** CLI generation-delivery helpers and focused delivery tests.
|
||||
Requires the released upstream selected-format accessor confirmed in Stage 1.
|
||||
|
||||
1. Add `--output` and `--report` as presence-aware application file flags with
|
||||
path completion. Validate empty values and known destination collisions
|
||||
before executing the model. Do not create files during validation.
|
||||
2. Implement the settled delivery rules using the same report as Stage 5.
|
||||
Main stdout uses `Invocation.Reporter().Report`; main files use
|
||||
`RenderReport` and the upstream selected format; separate reports use
|
||||
`RenderReport(..., FormatJSON)`. The default selected format must continue
|
||||
to use the artifact-only text template. Extensions never select formats.
|
||||
3. Keep explicit file effects independent of console quiet selection. Do not
|
||||
temporarily change reporting mode, rerun `App.Execute`, capture stdout and
|
||||
parse it back, or replace native structured serialization to obtain files.
|
||||
Keep file rendering outside reporter render callbacks to avoid reentrancy.
|
||||
4. Attempt main delivery and then the requested report even when the first
|
||||
fails, retaining every relevant delivery error. Include useful failure
|
||||
explanations and preserve the selected nonzero domain outcome. Console
|
||||
presentation failures remain recorded by CommandKit finalization; explicit
|
||||
file errors need their own outcome handling because they bypass its reporter.
|
||||
5. Remove the CLI observer/report collector wiring and old report-file format.
|
||||
Leave `internal/report` and HTTP report attachment intact. Only a returned
|
||||
native run result is eligible for the new CLI report file.
|
||||
|
||||
**Evidence:** cover default/text raw bytes, JSON and YAML main files, JSON
|
||||
separate report equivalence to inline native JSON, no duplicate stdout,
|
||||
format/extension independence, and quiet with/without requested files. Test
|
||||
empty paths, same cleaned path, existing same-file aliases, replacement without
|
||||
parent creation, first-delivery failure followed by report attempt, report
|
||||
failure after successful main delivery, and an unchanged existing report on a
|
||||
resultless operational failure. Use temporary files and a small failing-writer
|
||||
seam for stdout/render failures. Confirm status 4 survives a delivery failure
|
||||
while its explanation identifies the failure. No exhaustive filesystem matrix.
|
||||
|
||||
## Stage 7: Wire Process Metadata, Cancellation, And Server Startup
|
||||
|
||||
**Primary files:** `cmd/scriptorium/main.go`, CLI `serve` declaration,
|
||||
`scripts/release.sh`, `.woodpecker/release.yml`, and lifecycle tests.
|
||||
|
||||
1. Build the CLI identity as `scriptorium`, with caller-supplied version and
|
||||
revision. Add entrypoint string variables defaulting to `dev` and empty
|
||||
revision for ordinary builds, suitable for `-X main.version=...` and
|
||||
`-X main.revision=...`. Supply the release version/source commit in the
|
||||
existing release script and hosted build flags. Keep Go 1.27.4, build targets,
|
||||
publication guards, and release-completion semantics unchanged.
|
||||
2. At the process entrypoint, create a signal-aware context for interrupt and
|
||||
SIGTERM, pass it into execution, clean it up before `os.Exit`, and return
|
||||
CommandKit's finalized status without translating it to the old CLI constants.
|
||||
Keep this separately testable without signaling the test runner itself.
|
||||
3. Implement `serve` as an application command consuming Stage 2's resolved
|
||||
server settings. Construct the existing restricted artifact reader and inject
|
||||
it into one PromptKit engine shared by that server's requests. Install the
|
||||
existing HTTP handler and limits; retain `ReadHeaderTimeout` and engine retry
|
||||
defaults. Do not construct engines per request or remove backend capacity
|
||||
coordination.
|
||||
4. Send startup information through native Info reporting and failures through
|
||||
native explanations/causes. Do not add raw stdout server banners. Integrate
|
||||
context cancellation with `http.Server.Close` so the listener and active
|
||||
connections are closed; treat the resulting `ErrServerClosed` as expected
|
||||
cancellation with a useful nonzero operational outcome. Retain operational
|
||||
failure for unrelated listen/serve errors. This adds no graceful-drain deadline
|
||||
or guarantee that context-ignoring work has finished.
|
||||
5. Leave HTTP routes, DTOs, status mappings, optional execution reports,
|
||||
restricted-reader policy, and concurrency contracts unchanged. Continue using
|
||||
the HTTP observer collector; native CLI result reporting does not replace it.
|
||||
|
||||
**Evidence:** test injected context cancellation reaching a real engine operation
|
||||
without a duplicate timer; distinguish native operation timeout from earlier
|
||||
parent cancellation. Include zero/negative operation budgets and independent
|
||||
per-attempt timeout mapping. Exercise actual `serve` startup with a loopback
|
||||
listener, representative HTTP request, and controlled shutdown using explicit
|
||||
readiness coordination. Reuse the HTTP reader/DTO/report/shared-capacity suite
|
||||
rather than duplicating it. Build a binary with test identity flags and check native
|
||||
version output. Test-local fallback deadlines prevent regressions from hanging.
|
||||
|
||||
## Stage 8: Retire Superseded Machinery And Update Canonical Documentation
|
||||
|
||||
**Primary files:** old CLI parser/dispatch/inspection files and tests,
|
||||
`internal/format`, documentation and maintained examples listed below.
|
||||
|
||||
1. Remove obsolete `flag` parsing, comma mapping, old dispatch/help/exit
|
||||
constants, legacy `render`/`inspect` commands, custom source DTOs and
|
||||
inspection writers, custom prepared/definition presentation, and unused
|
||||
CLI report helpers. Delete `internal/format` if it has no remaining consumers;
|
||||
preserve `internal/report` for HTTP. Keep the useful source-to-underlay wiring
|
||||
in its new CLI home, not a resurrected framework facade.
|
||||
2. Replace obsolete tests with selected native integration protection from
|
||||
Stages 2–7. Retain architectural import boundaries and HTTP regression tests.
|
||||
Do not make intentionally retired snapshots or aliases pass by retaining
|
||||
production compatibility code. Avoid testing CommandKit's complete parser
|
||||
or formatting matrix again in Scriptorium.
|
||||
3. Update canonical owners with implemented behavior:
|
||||
|
||||
| Owner | Required changes |
|
||||
| --- | --- |
|
||||
| `docs/cli.md` | New command tree, applicable flags/aliases, native selection/reporting, run destinations, file semantics, statuses, completion, explicit smoke tests. Link upstream for standard family details. |
|
||||
| `docs/config.md` | Removed render default; native overlay-name selection; application overrides and loader authority; app/framework scopes and native comparison. Preserve collection/source/default semantics. |
|
||||
| `docs/integrations/subprocess.md` | Artifact-first execution, native reports and result availability, content-bearing metadata reports, stream capture, partial delivery, cancellation, and caller responsibility. Link exact CLI syntax rather than duplicate it. |
|
||||
| `docs/operations.md` | Updated discovery/preview/execution workflow, explicit smoke-test effects, potentially sensitive reports, file retention, server process lifecycle, unchanged HTTP limits. |
|
||||
| `docs/internal/overview.md`, `adapters.md`, `sources.md` | Actual component inventory and data flow, native acquisition boundaries, CLI result versus retained HTTP observation report, selector/engine lifecycle. |
|
||||
| `docs/development.md`, `docs/policy/architecture.md`, `docs/policy/testing.md` | Accurate component/dependency/reading and test ownership descriptions; retain adopted constraints, policy provenance, and accepted ADR decisions. |
|
||||
| `README.md`, `docs/consumers/api.md`, `docs/consumers/upgrading-promptkit.md` | Current quickstart/navigation and any affected examples; distinguish framework-format migration from the new CLI migration. |
|
||||
|
||||
4. Add a focused CLI migration guide under `docs/consumers/`, linked from the
|
||||
CLI/consumer overview. Cover positional prompt selection; `render` and
|
||||
`inspect` replacements; file versus literal inputs; repeated mappings without
|
||||
comma splitting; `--overlay` names; endpoint and timeout spelling/units;
|
||||
output/report destinations, native formats, and result availability; quiet
|
||||
behavior; status changes; and content-bearing native inspection/reports.
|
||||
This prepares release migration information without selecting a version,
|
||||
editing published notes, tagging, pushing, or adding release gates. Eventual
|
||||
release notes must summarize the breaking change and link the guide under
|
||||
the existing release/OSS policies.
|
||||
5. Update maintained application configs to remove the retired render default.
|
||||
Update `examples/render-markdown-summary.sh`, `render-v0.9-features.sh`,
|
||||
README/config examples, and collection workflows to native prepared preview,
|
||||
inspection, positional IDs, and preferred aliases. Existing example script
|
||||
filenames may remain; they are not CLI compatibility commands. Retain both
|
||||
collection-entry spellings and the multi-definition discovery example.
|
||||
6. Keep historical release notes unchanged. Update roadmap/Narratio status only
|
||||
after their acceptance behavior is implemented and verified. Do not silently
|
||||
retire deferred HTTP redesign or dynamic-resource completion proposals.
|
||||
|
||||
**Evidence:** no production command routes to retired parsing/presentation;
|
||||
remaining imports justify every retained helper/package. Maintained YAML loads
|
||||
under the new schema, scripts run without provider access where intended, and
|
||||
current documentation links resolve. Migration examples match the built CLI.
|
||||
|
||||
## Stage 9: Verify The Complete Native Cutover
|
||||
|
||||
1. Finish any deferred stage checks against the complete application. Use real
|
||||
ConfigKit, PromptKit, and CommandKit with deterministic provider substitutes
|
||||
at the external boundary. Tests remain offline and independent of real keys.
|
||||
2. Run a representative end-to-end collection workflow using
|
||||
`examples/config.discovery.yml`: discover resources in support/review,
|
||||
show requirements before input artifacts exist, validate/preview once inputs
|
||||
exist, and run through a controlled provider with consistent selections.
|
||||
Include native app and framework configuration comparisons with independent
|
||||
sides. Reuse the stage tests to cover Narratio's scenarios, not a parallel
|
||||
test harness. Confirm both optional entry-file globs still work and a new
|
||||
checkout is seen on a later invocation, not a hot-reload promise.
|
||||
3. Verify reachable help/version, preferred/canonical aliases, completion
|
||||
generation for the upstream-supported shells, and controlled smoke testing.
|
||||
Help/version/scope discovery/static completion work without configuration or
|
||||
provider availability. Confirm retired commands/flags are absent or rejected
|
||||
except where a spelling now intentionally has its native meaning (`--input`).
|
||||
4. Review the output/outcome matrix across stdout, requested files, quiet,
|
||||
completed validation failure, operational failures, presentation errors,
|
||||
cancellation, and partial delivery. Verify reports are native values with
|
||||
no Scriptorium wrapper, and HTTP's distinct contract remains unchanged.
|
||||
5. Run the repository baseline on the selected toolchain:
|
||||
|
||||
```sh
|
||||
go test ./...
|
||||
go test -race ./...
|
||||
go vet ./...
|
||||
go build ./cmd/scriptorium
|
||||
```
|
||||
|
||||
Check `gofmt`, `git diff --check`, affected examples and Markdown links,
|
||||
`go mod tidy` cleanliness, and the selected module graph. Check linked
|
||||
runtime packages separately with `go list -deps ./cmd/scriptorium` when
|
||||
validating attribution. Build the existing Linux amd64/arm64 targets with
|
||||
the unchanged release build options plus the selected identity metadata;
|
||||
this is migration verification, not a new publication gate.
|
||||
6. Audit the final diff against the roadmap and ADRs. In particular, confirm
|
||||
no post-handoff effective-config rewriting, synthetic inspection evidence,
|
||||
legacy CLI compatibility layer, new HTTP restriction, arbitrary secret
|
||||
redaction, extra resource-readiness prerequisite, automatic provider probe,
|
||||
workflow state, snapshot guarantee, or transactional file-delivery claim
|
||||
was introduced. Upstream limits/semantics remain upstream-owned.
|
||||
7. Record completion and the actual dependency/API selections after successful
|
||||
verification. Commit the finished implementation units under the agent
|
||||
policy and report checks, commits, and any remaining work accurately. Do
|
||||
not mark the migration complete while the approved upstream accessor or
|
||||
required acceptance behavior is missing.
|
||||
|
||||
There are no unresolved product questions. The selected-format accessor is an
|
||||
approved external release prerequisite, with its exact API/version to be
|
||||
confirmed in Stage 1; it does not authorize a local workaround.
|
||||
|
||||
[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
|
||||
Reference in New Issue
Block a user