diff --git a/README.md b/README.md index f51c803..5e98295 100644 --- a/README.md +++ b/README.md @@ -16,7 +16,7 @@ constructing them, and returns outcomes without exiting the process. Its | --- | --- | --- | | `gitea.maximumdirect.net/eric/CommandKit` | `commandkit` | Typed commands, bindings, execution, outcomes, help, and version. | | `gitea.maximumdirect.net/eric/CommandKit/integrations/ckconfig` | `ckconfig` | ConfigKit-backed `config` scopes and inspection commands. | -| `gitea.maximumdirect.net/eric/CommandKit/integrations/ckprompt` | `ckprompt` | PromptKit engine configuration/comparison, prompt/profile catalogs, and named inspection. | +| `gitea.maximumdirect.net/eric/CommandKit/integrations/ckprompt` | `ckprompt` | PromptKit engine configuration/comparison, prompt/profile catalogs, named inspection, and requirements discovery. | Importing an integration does not install commands. Pass its declaration to `commandkit.New` or `App.Register` to install it. The integrations depend on the diff --git a/docs/cli.md b/docs/cli.md index 3c9be74..cea90b5 100644 --- a/docs/cli.md +++ b/docs/cli.md @@ -382,6 +382,85 @@ error identity. Cancellation is also operational: standard handlers check the caller's context at inspection boundaries, and PromptKit can return cancellation from its own inspection methods. Supported cancellation identity is preserved. +## PromptKit requirements + +When `Suite.InspectRequirements` is present, +`ckprompt.Command(suite)` installs the following optional operation. It accepts +one required prompt ID and uses PromptKit's native selection and discovery +rules: + +```text +example promptkit requirements show briefing --campaign spring +example promptkit requirements show briefing --version 2 --profile editorial --var mode=full +example promptkit requirements show briefing --session-id session-42 --var note= --format yaml +``` + +The command accepts these flags: + +| Flag | Values | Default | Meaning | +| --- | --- | --- | --- | +| `--config` | path string | omitted | Select the configuration input; explicit presence is retained. | +| `--overlay` | path string | omitted | Select one overlay; explicit presence is retained. Repeated occurrences use the last value. | +| Suite selectors | application-defined | per selector | The flags captured from `Suite.Selectors`. | +| `--version` | string | empty | Pass the prompt version to PromptKit; empty uses its native version-selection rule. | +| `--profile` | string | empty | Pass the profile ID to PromptKit; empty uses its native profile-selection rule. | +| `--session-id` | string | empty | Pass session context to PromptKit. | +| `--var` | repeatable `KEY=VALUE` | none | Supply caller-variable context for native discovery. | +| `--format` | `yaml` | `yaml` | Select the requirements report format. Other formats are usage errors for this operation. | + +The `promptkit` namespace identifies the PromptKit operation, so there is no +built-in `--scope` flag. The version, profile, and session fields use native +empty-string semantics: an explicit empty string has the same meaning as +omission. PromptKit owns their interpretation, including default version and +profile selection, session context, and selection errors. Requirements +inspection does not require a profile to be execution-ready. See the pinned +[PromptKit requirements API](https://gitea.maximumdirect.net/eric/promptkit/src/commit/143c6e9b3a675872117b0471e2ff8bcb25055a54/requirements.go) +for the owning discovery contract. The built-in flags are singleton bindings; +when repeated, the last value is used. Suite selectors retain their declared +binding behavior. + +Each `--var` occurrence must contain `=`. CommandKit splits at the first +separator and preserves the exact key and remaining value. Empty keys and +values, whitespace, commas, and additional `=` characters are retained. All +occurrences are parsed; duplicate keys use the last value, while any malformed +occurrence is a usage error even if a later assignment is valid. + +The successful report is YAML with selected identities, native completeness, +and the input, variable, and issue inventories. False values and empty +inventories are retained. Input metadata preserves null versus an empty string. +The shape is: + +```yaml +prompt_id: briefing +prompt_version: "2" +profile_id: editorial +complete: false +inputs: + - name: notes + kind: conditional + declared: false + content_type: null + description: null + explanation: "" +variables: [] +issues: + - code: missing_variable + input_name: "" + variable_name: mode + description: "" +``` + +PromptKit owns the inventory, classifications, explanations, completeness, +and structured issues. Completeness means discovery covered the relevant +dependencies; it does not mean inputs or variables are supplied, artifacts are +valid, credentials are available, or execution is ready. A complete report can +contain unsupplied required variables, and an incomplete report can still be +useful. Successfully acquired and delivered partial reports return status `0`; +structured issues remain in YAML and do not independently fail the command. +Provider errors, native selection errors, cancellation, and report delivery +failures use the operational path (status `1`) with supported cause identity. +Syntax, operand, variable-assignment, and format errors use usage status `2`. + ### PromptKit catalogs An installed `ckprompt.Command(suite)` exposes the catalog commands supplied by diff --git a/docs/consumers/guide.md b/docs/consumers/guide.md index d54d743..5e53911 100644 --- a/docs/consumers/guide.md +++ b/docs/consumers/guide.md @@ -11,7 +11,7 @@ through `commandkit.New` or `App.Register`. | --- | --- | | `gitea.maximumdirect.net/eric/CommandKit` | The application needs typed command declarations and common CLI behavior. | | `gitea.maximumdirect.net/eric/CommandKit/integrations/ckconfig` | The application wants ConfigKit-backed configuration scopes and reports. | -| `gitea.maximumdirect.net/eric/CommandKit/integrations/ckprompt` | The application wants PromptKit engine configuration/comparison, prompt/profile catalogs, or named inspection. | +| `gitea.maximumdirect.net/eric/CommandKit/integrations/ckprompt` | The application wants PromptKit engine configuration/comparison, prompt/profile catalogs, named inspection, or requirements discovery. | The two integrations are independent optional imports. `ckprompt` uses the public scope and error contracts from `ckconfig`; importing it does not add the @@ -124,31 +124,35 @@ owns operator syntax and report details. `ckprompt.ConfigScope(loadEngine)` returns a `ckconfig.Scope` for the PromptKit engine's captured configuration. Add that scope to a `ckconfig.Suite` to expose it under `config` with validate/show/sources/explain and native diff operations; -it does not install named definition commands. +it does not install PromptKit catalog, definition, or requirements commands. -`ckprompt.FromEngine(loadEngine)` supplies the prompt/profile catalog callbacks -and named inspection callbacks. Set its `NewInput`, `NewState`, selectors, or -validation when the application needs them, then pass `ckprompt.Command(suite)` -to core. The four callbacks are independently optional; `Command` creates `list` -and `show` groups only when their corresponding callbacks are present. Narrow a -bundled suite before command capture when the application wants catalogs without -named inspections: +`ckprompt.FromEngine(loadEngine)` supplies the prompt/profile catalog callbacks, +named inspection callbacks, and native requirements callback. Set its +`NewInput`, `NewState`, selectors, or validation when the application needs +them, then pass `ckprompt.Command(suite)` to core. All five callbacks are +independently optional; `Command` creates each operation group only when its +callbacks are present. Applications can use the requirements callback alone, +clear it while retaining other operations, wrap it, or replace it with their +own provider. For catalogs without named or requirements inspection, narrow the +suite before command capture: ```go definitions := ckprompt.FromEngine(loadEngine) definitions.InspectPrompt = nil definitions.InspectProfile = nil +definitions.InspectRequirements = nil definitionCommand := ckprompt.Command(definitions) ``` -Each selected inspection or catalog operation prepares one input, applies its -captured selectors, checks that input, and initializes one state value when -those steps are reached. See +Each selected inspection, requirements, or catalog operation prepares one input, +applies its captured selectors, checks that input, and initializes one state +value when those steps are reached. See [ckprompt.Suite's GoDoc](../../integrations/ckprompt/adapters.go) for factory timing, omitted-factory zero values, and caller-owned objects and effects. The loader receives invocation context, explicitly supplied selection, input, -and state. The adapter uses PromptKit's public listing and inspection methods -and preserves acquisition diagnostics and supported error identity. +and state. The adapter uses PromptKit's public listing and inspection methods, +including `Engine.InspectRequirements`, and preserves acquisition diagnostics +and supported error identity. CommandKit-owned listing and inspection code does not execute prompts, contact model providers, or resolve credential values; application loaders and direct callbacks @@ -156,8 +160,8 @@ retain their own effects. The [CLI reference](../cli.md#promptkit-definition-ins owns the command and report contracts. The [composed example](../../integrations/ckprompt/examples/composed/README.md) -combines app and PromptKit config scopes, comparison and catalogs, named -inspection, and an application-owned `session restore` command. +combines app and PromptKit config scopes, comparison and catalogs, named and +requirements inspection, and an application-owned `session restore` command. ## Outcomes and ownership diff --git a/docs/development.md b/docs/development.md index 0232bcc..c59bf5d 100644 --- a/docs/development.md +++ b/docs/development.md @@ -3,8 +3,8 @@ CommandKit is distributed as a core Go module and two optional integration modules. Core owns captured declarations, typed input preparation, installation, dispatch, outcomes, help, and version. `integrations/ckconfig` owns ConfigKit -scope adaptation and reports; `integrations/ckprompt` owns PromptKit engine and -definition inspection adapters. The maintained +scope adaptation and reports; `integrations/ckprompt` owns PromptKit engine, +definition inspection, and requirements discovery adapters. The maintained [consumer guide](consumers/guide.md) links to the three maintained consumers. The [README](../README.md) provides project orientation; the [documentation policy](policy/documentation.md#canonical-ownership) assigns @@ -141,6 +141,8 @@ go run ./examples/core workspace greet --count=0 --tag=first --tag second (cd integrations/ckprompt/examples/composed && go run . promptkit list prompts --config fixtures/before.yml --campaign spring) (cd integrations/ckprompt/examples/composed && go run . promptkit list profiles --config fixtures/after.yml --campaign autumn --format yaml) (cd integrations/ckprompt/examples/composed && go run . promptkit show prompt briefing --campaign spring --format yaml) +(cd integrations/ckprompt/examples/composed && go run . promptkit requirements show briefing --campaign spring) +(cd integrations/ckprompt/examples/composed && go run . promptkit requirements show briefing --campaign spring --var mode=full --format yaml) (cd integrations/ckprompt/examples/composed && go run . session restore session-42 --campaign spring) ``` diff --git a/docs/internal/overview.md b/docs/internal/overview.md index b628bc7..487d227 100644 --- a/docs/internal/overview.md +++ b/docs/internal/overview.md @@ -47,11 +47,12 @@ initialized input, while one suite-owned state value is shared by an invocation' acquisitions or comparison callback. `integrations/ckprompt` owns PromptKit engine loading, configuration-scope -adaptation and native comparison, plus optional prompt/profile catalogs and -named inspection. It uses public core and ckconfig contracts plus PromptKit's -public APIs. It does not add a configuration family when its declaration is -installed; callers compose `ckprompt.ConfigScope` with `ckconfig.Command` -separately when they want configuration operations alongside definition commands. +adaptation and native comparison, plus optional prompt/profile catalogs, named +inspection, and native requirements discovery. It uses public core and ckconfig +contracts plus PromptKit's public APIs. It does not add a configuration family +when its declaration is installed; callers compose `ckprompt.ConfigScope` with +`ckconfig.Command` separately when they want configuration operations alongside +PromptKit commands. The three maintained consumers live at `examples/core`, `integrations/ckconfig/examples/simple`, and diff --git a/docs/roadmap/deferred.md b/docs/roadmap/deferred.md index ea88f3a..6c31883 100644 --- a/docs/roadmap/deferred.md +++ b/docs/roadmap/deferred.md @@ -18,14 +18,6 @@ an idea here does not select its syntax, API, priority, or delivery date. ## Deferred capability targets -### PromptKit requirement inspection - -PromptKit exposes `Engine.InspectRequirements`, but a standard CommandKit -operation for requirement inspection remains deferred. Its command syntax, -selection behavior, presentation, and readiness semantics have not been -selected. Reassess the owning library's public contract and make those product -choices before planning delivery. - ### Comparison extensions Independent per-side domain selectors and an optional assertion mode remain diff --git a/docs/roadmap/implementation.md b/docs/roadmap/implementation.md index 36036a4..82693fa 100644 --- a/docs/roadmap/implementation.md +++ b/docs/roadmap/implementation.md @@ -1,6 +1,6 @@ # Implement PromptKit requirements inspection -Status: in progress; Stages 1 through 5 are complete. +Status: in progress; Stages 1 through 6 are complete. ## Authority and working rules @@ -423,6 +423,21 @@ Historical release notes and pinned retired plans remain historical evidence; do not rewrite them as current reference pages. Current canonical docs must not depend on this temporary plan for their implemented contracts. +**Completed:** Updated the exported API comments in +`integrations/ckprompt/adapters.go`, `command.go`, and `doc.go`; the command and +report contract in `docs/cli.md`; optional callback guidance in +`docs/consumers/guide.md`; module, root, internal, and contributor summaries; +and the composed example README. Removed the delivered capability from +`docs/roadmap/deferred.md` and updated +`docs/roadmap/requirements.md` to describe its historical baseline and point to +the immutable commit that contains the prior deferral. The two example commands +and their semantics match the Stage 5 test and observed output. `gofmt -w +integrations/ckprompt/adapters.go integrations/ckprompt/command.go +integrations/ckprompt/doc.go` and `git diff --check -- '*.md' COPYRIGHT` passed. +A local link and fragment check across nine changed Markdown documents passed; +the stale four-callback and deferred-requirement claim search found no current +documentation claims. No material limitations were encountered. + ## Stage 7: Validate the final module boundaries and complete the sprint **Outcome:** the implemented feature works with its committed dependency graph, diff --git a/docs/roadmap/requirements.md b/docs/roadmap/requirements.md index 11c9cd0..7b3a445 100644 --- a/docs/roadmap/requirements.md +++ b/docs/roadmap/requirements.md @@ -1,8 +1,8 @@ # PromptKit requirements inspection -Status: accepted feature roadmap; implementation has not started. Command +Status: accepted feature roadmap; implementation is in progress. Command placement, public API, caller-variable syntax, and initial presentation are -settled. +settled. The implementation plan records delivery and final validation status. The [implementation plan](implementation.md) owns the ordered delivery steps and stage completion evidence. @@ -35,24 +35,25 @@ is the authority for discovery semantics. Descriptions below explain how CommandKit will expose that API, rather than establishing a separate discovery specification. -## Current baseline +## Baseline at roadmap acceptance -Baseline: CommandKit commit +This table records the pre-implementation state at CommandKit commit [`12b52b3`](https://gitea.maximumdirect.net/eric/CommandKit/src/commit/12b52b3174545d22960c91c3a782a151ab813447). -| Area | Current implementation | Gap to target | +| Area | State then | Gap the roadmap addressed | | --- | --- | --- | | Dependencies | ckprompt already adopts PromptKit v0.14.0, ConfigKit v0.7.1, and YAML v4. Modules require Go 1.26.0. | No dependency or toolchain upgrade is needed for this capability. | | Native capability | PromptKit exposes `Engine.InspectRequirements`, its request, and its structured result. | Adapt this existing public API. | -| Public integration | `Suite[I, S]` provides optional prompt/profile inspection and prompt/profile catalog callbacks. `FromEngine` supplies those four callbacks. | Add an independently optional requirements callback and its engine adapter. | -| Command assembly | `ckprompt.Command` installs available `show` and `list` operations beneath the owned `promptkit` namespace. | Assemble the requirements operation from its own capability. | +| Public integration | The accepted baseline had optional prompt/profile inspection and prompt/profile catalog callbacks. | Add an independently optional requirements callback and its engine adapter. | +| Command assembly | The accepted baseline installed available `show` and `list` operations beneath the owned `promptkit` namespace. | Assemble the requirements operation from its own capability. | | Invocation infrastructure | Typed selectors, configuration selection, input checks, shared state, diagnostics, and buffered report delivery already exist. | Apply those paths to the new operation. | | Presentation | Named prompt/profile reports support text and YAML; catalogs use YAML only. | Define a requirements report with the native evidence and discovery context identities. | -The [deferred-work record](deferred.md#promptkit-requirement-inspection) records -this capability's prior deferral. This roadmap takes it up for planning; -the command remains unimplemented. Existing configuration, catalog, and named -definition operations are not prerequisites for enabling requirements inspection. +The former deferral is retained as an +[immutable historical record](https://gitea.maximumdirect.net/eric/CommandKit/src/commit/ee038df530bfd3518906dc77e8e8f55eef237dda/docs/roadmap/deferred.md). +This roadmap takes the capability up for delivery. Existing configuration, +catalog, and named definition operations are not prerequisites for requirements +inspection. ## Target ownership and package boundaries diff --git a/integrations/ckprompt/README.md b/integrations/ckprompt/README.md index f9604f0..bf5c38c 100644 --- a/integrations/ckprompt/README.md +++ b/integrations/ckprompt/README.md @@ -1,8 +1,9 @@ # CommandKit ckprompt `ckprompt` is the optional PromptKit integration for CommandKit. It adapts -PromptKit engine configuration, native comparison, prompt/profile catalogs, and -named inspection. Importing it does not install either command family. +PromptKit engine configuration, native comparison, prompt/profile catalogs, +named inspection, and prompt requirements discovery. Importing it does not +install either command family. ## Module @@ -19,12 +20,13 @@ Add `ckprompt.ConfigScope(loadEngine)` to the scopes passed to `ckconfig.Command` when the application wants PromptKit engine configuration and native comparison in the `config` family. Install `ckprompt.Command(ckprompt.FromEngine(loadEngine))` separately for prompt/profile -catalogs and named inspections. `FromEngine` supplies all four PromptKit-backed -callbacks; applications may narrow them before capture or provide their own -callbacks with `ckprompt.Suite`. CommandKit-owned inspection and listing code -does not execute prompts or contact model providers; application loaders and -direct callbacks retain their own effects. See the -[CLI reference](https://gitea.maximumdirect.net/eric/CommandKit/src/branch/main/docs/cli.md#promptkit-definition-inspection) +catalogs, named inspections, and requirements discovery. `FromEngine` supplies +all five PromptKit-backed callbacks; applications may narrow, wrap, or replace +them before capture or provide custom callbacks with `ckprompt.Suite`. +Requirements is independently optional. CommandKit-owned inspection and +listing code does not execute prompts or contact model providers; application +loaders and direct callbacks retain their own effects. See the +[CLI reference](https://gitea.maximumdirect.net/eric/CommandKit/src/branch/main/docs/cli.md#promptkit-requirements) for operator commands and report semantics. The maintained [composed example](examples/composed) shows complete application wiring. diff --git a/integrations/ckprompt/adapters.go b/integrations/ckprompt/adapters.go index 8c7ba5c..0265969 100644 --- a/integrations/ckprompt/adapters.go +++ b/integrations/ckprompt/adapters.go @@ -36,7 +36,9 @@ type ProfileRequest struct { type RequirementsRequest struct { // Selection carries the configuration and overlay values supplied to the command. Selection ckconfig.Selection - // Inspection carries PromptKit's discovery context for the selected prompt. + // Inspection forwards PromptKit's native prompt, version, profile, variable, + // and session discovery context. Optional version, profile, and session + // strings retain PromptKit's empty-value semantics. Inspection promptkit.RequirementInspectionRequest } @@ -156,13 +158,15 @@ func promptKitContextError(ctx context.Context) error { return ctx.Err() } -// FromEngine supplies callbacks for prompt and profile catalogs, named -// inspections, and requirements inspection backed by a PromptKit engine loader. -// It does not call the loader during construction. Each selected operation -// passes its context, supplied selection, initialized input, and shared -// invocation state to the loader before calling PromptKit's public listing or -// inspection method. Applications can narrow these callbacks before Command -// captures them. A nil loader is retained as an adapter issue. +// FromEngine supplies prompt and profile catalog callbacks, named inspection +// callbacks, and a requirements inspection callback backed by a PromptKit engine +// loader. The requirements callback forwards RequirementsRequest.Inspection to +// Engine.InspectRequirements. FromEngine does not call the loader during +// construction. Each selected operation passes its context, supplied +// selection, initialized input, and shared invocation state to the loader before +// calling PromptKit's public listing or inspection method. Applications can +// narrow, wrap, or replace these callbacks before Command captures them. A nil +// loader is retained as an adapter issue. func FromEngine[I, S any](load func(context.Context, ckconfig.Selection, I, S) (*promptkit.Engine, error)) Suite[I, S] { if load == nil { return Suite[I, S]{issues: []error{errors.New("PromptKit engine loader is nil")}} diff --git a/integrations/ckprompt/command.go b/integrations/ckprompt/command.go index 34e899d..7bc9f99 100644 --- a/integrations/ckprompt/command.go +++ b/integrations/ckprompt/command.go @@ -49,8 +49,10 @@ type variableAssignment struct { // absent suite claims no namespace; attached construction issues remain // reportable. It adds no configuration family; callers compose ConfigScope // independently. Construction, installation, help, and version do not run -// suite factories or providers. Suite documents invocation input and state -// initialization, zero values, and caller ownership of returned objects. +// suite factories or providers. Command captures suite callbacks and selector +// metadata; callback-referenced objects and effects remain caller-owned. Suite +// documents invocation input and state initialization, zero values, and caller +// ownership of returned objects. // Catalog commands accept config/overlay selection and suite selectors, and // render YAML with `yaml` as the only format and default. Named-show formats are // unchanged. diff --git a/integrations/ckprompt/doc.go b/integrations/ckprompt/doc.go index 4f09281..bad0974 100644 --- a/integrations/ckprompt/doc.go +++ b/integrations/ckprompt/doc.go @@ -1,5 +1,5 @@ // Package ckprompt provides optional PromptKit configuration comparison, -// definition catalogs, and named inspections for CommandKit. Importing ckprompt -// installs neither family; callers compose its declarations with core and -// ckconfig explicitly. +// definition catalogs, named inspections, and prompt requirements inspection +// for CommandKit. Importing ckprompt installs neither family; callers compose +// its declarations with core and ckconfig explicitly. package ckprompt diff --git a/integrations/ckprompt/examples/composed/README.md b/integrations/ckprompt/examples/composed/README.md index 63767ee..4e35a82 100644 --- a/integrations/ckprompt/examples/composed/README.md +++ b/integrations/ckprompt/examples/composed/README.md @@ -1,8 +1,8 @@ # Composed consumer This example composes application configuration, PromptKit configuration, -PromptKit comparison and catalogs, definition inspection, and one -application-owned command: +PromptKit comparison and catalogs, definition and requirements inspection, and +one application-owned command: ```sh go run . config scopes @@ -14,6 +14,8 @@ go run . promptkit list prompts --config fixtures/before.yml --campaign spring go run . promptkit list profiles --config fixtures/after.yml --campaign autumn --format yaml go run . promptkit show prompt briefing --campaign spring --format yaml go run . promptkit show profile spring --campaign spring +go run . promptkit requirements show briefing --campaign spring +go run . promptkit requirements show briefing --campaign spring --var mode=full --format yaml go run . session restore session-42 --campaign spring ``` @@ -38,3 +40,11 @@ supplied configuration/overlay selection and the supplied campaign, including presence. The campaign override is applied through ConfigKit before loading. These are choices for this example's loader and do not define a CommandKit cache policy. + +The first requirements command reports incomplete discovery: PromptKit records +the conditional `notes` input and a missing `mode` issue. Supplying `mode=full` +selects that branch, classifies the undeclared `notes` input as required, and +completes discovery. Both commands return successful reports; the result does +not execute the prompt or establish input, credential, or execution readiness. +See the [CLI reference](../../../../docs/cli.md#promptkit-requirements) for the +command and report contract.