From df33e8aefc9c4ffdf8363e120fe641b2e2ca5a14 Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Fri, 6 Nov 2026 03:28:21 +0000 Subject: [PATCH] Plan reusable PromptKit CLI flag collections --- docs/roadmap/future.md | 4 ++- docs/roadmap/promptkit-v0.19.0.md | 47 ++++++++++++++++++++++++++----- 2 files changed, 43 insertions(+), 8 deletions(-) diff --git a/docs/roadmap/future.md b/docs/roadmap/future.md index b0a03da..baa660c 100644 --- a/docs/roadmap/future.md +++ b/docs/roadmap/future.md @@ -79,7 +79,9 @@ application loading and startup. The [PromptKit v0.19.0 roadmap](promptkit-v0.19.0.md#targeted-end-state) now owns concrete request preview, applicable request flags, namespace selection, -and the shared configuration inspection extensions. These are CLI features; +and the shared configuration inspection extensions. Its execution flags will be +public reusable `ckprompt` collections for standard and application-owned CLI +commands, composed through existing core bindings. These are CLI features; general-purpose helpers for application-internal PromptKit use are outside CommandKit's ownership boundary. diff --git a/docs/roadmap/promptkit-v0.19.0.md b/docs/roadmap/promptkit-v0.19.0.md index b2943e2..c692efe 100644 --- a/docs/roadmap/promptkit-v0.19.0.md +++ b/docs/roadmap/promptkit-v0.19.0.md @@ -154,12 +154,32 @@ snapshot a redacted configuration report or a transferable execution handle. Expose the upstream snapshot evidence without implying later execution uses that exact snapshot or will succeed. -Share CLI binding implementation where it reduces duplication between smoke, -validation, and preview. Preserve native explicit zero/empty values and -whole-map replacement semantics. Keep parsing in CommandKit and domain validity +Provide public, reusable typed execution-flag collections in `ckprompt`, defined +once and used by smoke, validation, preview, and application-owned commands. +The collections standardize flag names, help, parsing, completion hints, +supplied-value tracking, and binding into native PromptKit request fields. +Applications retain their own input structs, request construction, engine +acquisition, execution, and outcomes. Reusing CLI declarations is within +CommandKit's ownership boundary; it does not introduce runtime convenience APIs. + +Use the existing core `CommandSpec[I].Flags`, typed flag constructors, and +`Supplied[T]`. A generic collection factory can accept destination accessors +and return ordinary `[]commandkit.Flag[I]`. Direct binding is sufficient for +ordinary use; existing [CaptureFlags and FlagValues.ApplyTo](../../flag_values.go) +support deferred application or multiple destinations where needed. No core +change or new core collection abstraction is currently required. Exact exported +names and accessor signatures remain implementation design choices. + +Keep execution-target overrides and the request-level transient retry field +distinct even when one convenient collection includes both. Preserve omission +instead of imposing shared defaults: ordinary execution and smoke diagnostics +have different native retry defaults. Preserve native explicit zero/empty +values and whole-map replacement semantics. Support deliberate subsets for +actual command needs while retaining common flag names and meanings, using a +proportionate composition API. Keep parsing in CommandKit and domain validity in PromptKit. Existing application builders remain usable; resolve override precedence and the remaining request controls under OD-2 before documenting new -public behavior. These helpers serve standard CLI commands only. +public behavior. ### Namespace selection @@ -262,8 +282,10 @@ errors remain errors even if an override would replace the affected value. candidate note and affected canonical dependency/compatibility guidance. No core Go-minimum increase follows from this adoption. 3. **Implement request inspection and selection.** Add preview, applicable - override flags, provider-parameter input, and namespace selectors. Reuse the - standard suite's lifecycle and preserve existing application adapter seams. + override flags, provider-parameter input, and namespace selectors. Implement + public `ckprompt` execution-flag collections on existing core bindings and + reuse them in the standard commands. Reuse the standard suite's lifecycle + and preserve existing application adapter seams. 4. **Implement shared configuration inspection.** Add metadata discovery and explicitness, detailed diff presentation, source evidence on failure, and structured diagnostics in `ckconfig`; wire native PromptKit facets through @@ -304,6 +326,11 @@ Default tests remain offline and independent of real credentials. - [ ] New flags preserve selected omission/empty/zero semantics, parse malformed inputs through the existing usage path, and do not leak state between runs. Numeric decoding of provider JSON matches the selected strategy in OD-2. +- [ ] The same public execution-flag collection works in a standard subcommand + and an application-owned command with its own typed input. Parsing, presence, + metadata, and selected subsets remain consistent; omitted retry values retain + the applicable native defaults. Application execution behavior remains outside + the collection. - [ ] Namespace defaults, explicit clearing, qualified selections, and catalog filters are forwarded according to the selected design. - [ ] Metadata discovery distinguishes effective and historical paths, retains @@ -332,7 +359,8 @@ Default tests remain offline and independent of real credentials. do not start acquisition. New operation/flag metadata and static completion match the implemented surface. - [ ] Maintained consumer examples demonstrate the selected CLI tasks and the - configuration failure workflow with deterministic local evidence. + configuration failure workflow with deterministic local evidence, including + collection reuse by an application-owned command. - [ ] Canonical documentation, module release notes, and roadmap links agree with the implemented boundary. Open decisions are resolved or deliberately superseded before the corresponding behavior is claimed complete. @@ -390,6 +418,11 @@ stay entirely within CLI ownership; select vocabulary and formats before coding. ### OD-2: Request controls and provider-parameter grammar +**Agreed design direction:** execution flags are public reusable CLI collections +owned by `ckprompt`, available to standard and application-owned commands using +existing core APIs. The remaining decisions here concern request controls and +grammar, not whether application commands may reuse the collections. + **Recommendation:** give validation and preview the applicable execution flags already on smoke tests, and add a singleton `--extra-params JSON` object option to all three. Use native whole-map replacement, including native behavior for