556 lines
38 KiB
Markdown
556 lines
38 KiB
Markdown
# 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
|