diff --git a/README.md b/README.md index 40679a4..f51c803 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 and optional named prompt/profile inspection. | +| `gitea.maximumdirect.net/eric/CommandKit/integrations/ckprompt` | `ckprompt` | PromptKit engine configuration/comparison, prompt/profile catalogs, and named inspection. | 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 4bf0f86..3c9be74 100644 --- a/docs/cli.md +++ b/docs/cli.md @@ -106,8 +106,9 @@ declared scope capabilities and installed handlers, so an operation is listed only when the corresponding command is available. Applications can add `ckprompt.ConfigScope(loadEngine)` to the ConfigKit suite -to expose PromptKit engine configuration through these handlers. This scope -does not install PromptKit prompt or profile definition commands. +to expose PromptKit engine configuration through these handlers. The scope +declares validate, show, sources, explain, and native diff. It does not install +PromptKit prompt or profile definition commands. ### Validate configuration @@ -235,8 +236,11 @@ serialized as `[]`. `config diff` prepares two selections for one scope that declares comparison and invokes its comparison provider after input checks pass. The default scope is `app`; `--scope all` is unsupported. -The PromptKit engine scope does not currently declare comparison, so selecting -`--scope promptkit` is a usage error. +When an application installs `ckprompt.ConfigScope(loadEngine)`, the PromptKit +scope declares comparison and delegates it to PromptKit's captured +configuration inspection API. PromptKit owns the meaning of that native +comparison; CommandKit uses the existing `config diff` preparation and report +path. `--config` and `--overlay` select the left side. `--against-config` and `--against-overlay` independently override the right side. When a right-side field is omitted, it inherits the corresponding left value and supplied state; @@ -250,21 +254,24 @@ YAML is the only format and the default. Explicit `--format yaml` is accepted; example config diff --config before.yml --against-config after.yml example config diff --config base.yml --against-overlay candidate example config diff --config base.yml --overlay current --against-overlay "" +example config diff --scope promptkit --config before.yml --against-config after.yml ``` -ConfigKit compares frozen effective typed values after defaults and resolution; -source or provenance differences alone do not create a change. The report is one -YAML document with `additions`, `changes`, and `deletions` in that order. -Additions and changes preserve semantic paths and contain safe right-side values. -Deletions contain canonical JSON Pointer paths. Explicit null is a value; it is -not a deletion. Changed sequences and native structural replacement regions stay -atomic. +For ConfigKit-backed scopes, ConfigKit compares frozen effective typed values +after defaults and resolution; source or provenance differences alone do not +create a change. PromptKit delegates its native comparison to ConfigKit. The +report is one YAML document with `additions`, `changes`, and `deletions` in that +order. Additions and changes preserve semantic paths and contain right-side +values provided by the native comparison. Deletions contain canonical JSON +Pointer paths. Explicit null is a value; it is not a deletion. Changed sequences +and native structural replacement regions stay atomic. ConfigKit pairs sensitivity across both loads. A concealed change can therefore -appear even when its two safe snapshots are equal. The report omits separate -redaction and hidden-change metadata: a reported masked region changed, but that -does not mean every member inside it changed. Marker-looking public strings stay -ordinary YAML values. An empty comparison succeeds with this shape: +appear even when its two safe snapshots are equal. For those ConfigKit-backed +comparisons, the report omits separate redaction and hidden-change metadata: a +reported masked region changed, but that does not mean every member inside it +changed. Marker-looking public strings stay ordinary YAML values. An empty +comparison succeeds with this shape: ```yaml additions: {} @@ -277,7 +284,7 @@ automatically applicable patch. Exceptional whole-root empty/null transitions can be ambiguous because the report has no root envelope; ordinary field-level null values and deletions retain their distinction. -Successful comparisons return status `0`, including concealed or empty results. +Successful comparisons return status `0`, including empty results. Unsupported scopes and format errors are usage errors; input checks retain the existing usage/operational classification. Load and native comparison failures are operational and preserve supported error identity. @@ -375,6 +382,43 @@ 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 catalogs + +An installed `ckprompt.Command(suite)` exposes the catalog commands supplied by +the suite: + +```text +example promptkit list prompts +example promptkit list profiles --config settings.yml --campaign spring +``` + +Each command accepts `--config`, `--overlay`, and applicable selectors from +`Suite.Selectors`. It takes no ID or version operand and has no `--version` or +`--scope` selector. `--format` defaults to `yaml`; `--format yaml` is accepted, +and other formats are usage errors. + +Each invocation writes one bare YAML sequence. Prompt entries have explicit +string `id` and `version` fields; profile entries are strings. Provider order and +exact identity values are preserved. For example: + +```yaml +- id: briefing + version: "1" +- id: briefing + version: "2" +``` + +```yaml +- autumn +- spring +``` + +Successful nil and allocated-empty inventories both render as `[]`. Catalog +membership and ordering follow the selected provider, and a listed definition +is not a readiness check or execution result. PromptKit owns the meaning of its +native listing APIs; custom providers own their results. Applications retain +their own disclosure choices for catalog data. + ## Outcome status CommandKit usage failures use status `2`; operational failures use status `1`. diff --git a/docs/consumers/guide.md b/docs/consumers/guide.md index c3f1c4a..d54d743 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 or named prompt/profile inspection. | +| `gitea.maximumdirect.net/eric/CommandKit/integrations/ckprompt` | The application wants PromptKit engine configuration/comparison, prompt/profile catalogs, or named inspection. | The two integrations are independent optional imports. `ckprompt` uses the public scope and error contracts from `ckconfig`; importing it does not add the @@ -123,29 +123,41 @@ 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`; it does not install named definition commands. +it under `config` with validate/show/sources/explain and native diff operations; +it does not install named definition commands. -`ckprompt.FromEngine(loadEngine)` supplies PromptKit named prompt and profile -inspection callbacks. Set its `NewInput`, `NewState`, selectors, or validation -when the application needs them, then pass `ckprompt.Command(suite)` to core. -Prompt and profile capabilities can be installed independently by providing -only the corresponding callback. Each selected inspection prepares one input -and one state value when those steps are reached. See +`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: + +```go +definitions := ckprompt.FromEngine(loadEngine) +definitions.InspectPrompt = nil +definitions.InspectProfile = 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 [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 inspection methods and preserves acquisition diagnostics -and error identity. +and state. The adapter uses PromptKit's public listing and inspection methods +and preserves acquisition diagnostics and supported error identity. -CommandKit-owned inspection code does not execute prompts, contact model +CommandKit-owned listing and inspection code does not execute prompts, contact model providers, or resolve credential values; application loaders and direct callbacks retain their own effects. The [CLI reference](../cli.md#promptkit-definition-inspection) -owns the inspection boundary and credential-report semantics. +owns the command and report contracts. The [composed example](../../integrations/ckprompt/examples/composed/README.md) -combines app and PromptKit config scopes, independently registers profile -inspection, and adds an application-owned `session restore` command. +combines app and PromptKit config scopes, comparison and catalogs, named +inspection, and an application-owned `session restore` command. ## Outcomes and ownership diff --git a/docs/development.md b/docs/development.md index 8a5db52..d1ad7b1 100644 --- a/docs/development.md +++ b/docs/development.md @@ -137,6 +137,9 @@ go run ./examples/core workspace greet --count=0 --tag=first --tag second (cd integrations/ckconfig/examples/simple && go run . config diff --config fixtures/before.yml --against-config fixtures/after.yml) (cd integrations/ckprompt/examples/composed && go run . config validate --scope all --campaign spring --limit=0) (cd integrations/ckprompt/examples/composed && go run . config diff --scope app --config fixtures/before.yml --against-config fixtures/after.yml) +(cd integrations/ckprompt/examples/composed && go run . config diff --scope promptkit --config fixtures/before.yml --against-config fixtures/after.yml --campaign spring) +(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 . session restore session-42 --campaign spring) ``` diff --git a/docs/internal/overview.md b/docs/internal/overview.md index 9bee449..b628bc7 100644 --- a/docs/internal/overview.md +++ b/docs/internal/overview.md @@ -47,10 +47,11 @@ 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 optional named prompt/profile 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 both. +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. The three maintained consumers live at `examples/core`, `integrations/ckconfig/examples/simple`, and diff --git a/docs/roadmap/configkit.md b/docs/roadmap/configkit.md index 0af3730..daa693c 100644 --- a/docs/roadmap/configkit.md +++ b/docs/roadmap/configkit.md @@ -36,8 +36,8 @@ disclosure; CommandKit owns selection, coordination, adaptation, and presentatio | --- | --- | | Core module | Go 1.26.0; captured commands, typed bindings, dispatch, outcomes, help, and version. No ConfigKit dependency. ReleaseKit v0.4.0 is the declared maintainer tool. | | `integrations/ckconfig` | Requires ConfigKit v0.7.1. `Scope`, `Suite`, `FromConfigKit`, and `AppCommand` expose independently declared validate/show/sources/explain/diff capabilities. | -| `integrations/ckprompt` | Requires ConfigKit v0.7.1 and PromptKit v0.12.0. It depends on ckconfig's public scope contracts and adapts engine configuration plus named definitions; its ConfigKit scope does not declare comparison. | -| Comparison status | ConfigKit-backed `config diff` is implemented. The [CLI reference](../cli.md#compare-configuration-selections), integration GoDoc, and [implementation record](https://gitea.maximumdirect.net/eric/CommandKit/src/commit/20e19b95694f7fdfd5c342ec4d543152986623dc/docs/roadmap/implementation.md) own current contracts and evidence. PromptKit comparison remains deferred. | +| `integrations/ckprompt` | The later PromptKit adoption selects PromptKit v0.14.0 and ConfigKit v0.7.1. It adapts engine configuration and exposes native comparison, prompt/profile catalogs, and named definitions through ckconfig and core contracts. | +| Comparison status | ConfigKit-backed `config diff` and PromptKit engine-scope comparison are implemented. The [CLI reference](../cli.md#compare-configuration-selections) and [PromptKit adoption record](promptkit.md) describe current behavior; the [implementation record](https://gitea.maximumdirect.net/eric/CommandKit/src/commit/20e19b95694f7fdfd5c342ec4d543152986623dc/docs/roadmap/implementation.md) records ConfigKit completion. | The ConfigKit adapter acquires typed `*configkit.Result[T]` values and exposes effective, source, and explanation facets through `View` for ordinary operations. @@ -62,9 +62,11 @@ and [comparison contract](https://gitea.maximumdirect.net/eric/ConfigKit/src/com ## Dependency adoption and ownership -Both integration modules now select ConfigKit v0.7.1 and carry normal dependency -metadata for their actual graphs. Consumer Go minimums remain 1.26.0, the selected -release toolchain remains 1.26.8, and PromptKit remains v0.12.0 for this work. +Both integration modules select ConfigKit v0.7.1 and carry normal dependency +metadata for their actual graphs. Consumer Go minimums remain 1.26.0, and the +selected release toolchain remains 1.26.8. At completion of this ConfigKit work, +ckprompt still selected PromptKit v0.12.0; the later PromptKit adoption is tracked +in [promptkit.md](promptkit.md). Core continues to have no ConfigKit or optional-integration dependency. ConfigKit's declared tool requirement brings ReleaseKit v0.4.1 into the integration diff --git a/docs/roadmap/deferred.md b/docs/roadmap/deferred.md index a0376d4..ea88f3a 100644 --- a/docs/roadmap/deferred.md +++ b/docs/roadmap/deferred.md @@ -5,8 +5,8 @@ Status: retained future work and unselected proposals; no implementation schedul ## Purpose and authority Completed initial delivery, performance, ReleaseKit upgrade, and remediation -records have been retired. This document preserves their unfinished capability -targets and deferred ideas under the +records have been retired. This document preserves remaining deferred +capabilities and unselected ideas under the [release policy](../policy/release.md#release-documentation-and-preparation). The original records remain available in [Git history](https://gitea.maximumdirect.net/eric/CommandKit/src/commit/6bc37e7ba64ca0920b4d0cc77039a18d4006b24e/docs/roadmap). @@ -18,13 +18,13 @@ an idea here does not select its syntax, API, priority, or delivery date. ## Deferred capability targets -### PromptKit configuration comparison +### PromptKit requirement inspection -ConfigKit-backed `config diff` is implemented by `ckconfig` for scopes that -declare that capability. `ckprompt.ConfigScope` does not declare comparison. -Reassess PromptKit's supported public comparison capabilities before planning a -PromptKit comparison. Do not reach into ConfigKit internals or infer comparison -semantics from rendered YAML. +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 @@ -33,16 +33,6 @@ unselected extensions to the delivered ConfigKit comparison. Consider them only for a concrete consumer need and a deliberate API/behavior decision under the relevant ADRs. -### CAT-01: PromptKit catalogs - -List captured prompt/version entries and named profiles through owning public -catalog APIs, with deterministic reports of loaded definitions. Resource names, -enumeration details, and report shapes remain future design work. - -The initial PromptKit v0.12.0 review did not find public enumeration APIs. -Reassess current released capabilities before planning delivery. Do not infer -catalogs by reparsing configuration YAML or inspecting sibling internals. - ## Other deferred proposals These capabilities remain outside the delivered scope and require a concrete diff --git a/docs/roadmap/implementation.md b/docs/roadmap/implementation.md index 0d55c14..9618481 100644 --- a/docs/roadmap/implementation.md +++ b/docs/roadmap/implementation.md @@ -1,6 +1,6 @@ # Implement PromptKit comparison and catalogs -Status: Stages 1–9 complete; remaining stages are planned. +Status: Stages 1–10 complete; remaining stages are planned. ## Scope and authority @@ -583,6 +583,29 @@ Review diffs, links/fragments, examples, and stale statements; run documented Markdown whitespace checks. Describe native semantics as upstream-owned. Do not promise arbitrary catalog/provider data is safe for public disclosure. +**Completion evidence (2026-10-12)** + +- Updated ckprompt GoDoc for native configuration comparison, all four optional + callbacks, callback narrowing, selector/input preparation, nil-factory zero + values, and catalog YAML defaults. Root and module READMEs now describe the + shipped integration. +- Updated the CLI reference for PromptKit `config diff` and independent prompt + and profile catalogs, including selectors, YAML schema/default, empty results, + and the owning-library boundary for comparison and catalog membership. It + leaves catalog data disclosure with the application/provider. +- Updated consumer guidance with a narrowing-before-capture example, the + internal package overview, and development commands. The PromptKit roadmap now + records delivered behavior; the ConfigKit roadmap summary reflects the later + PromptKit adoption; and `deferred.md` retains only requirement inspection as a + PromptKit capability deferred from this feature. +- Reviewed the architecture policy and ADRs 0004 and 0008–0012. They remain + consistent with the delivered ownership and invocation model; no decision + record changes were needed. Historical baseline and ConfigKit completion + records remain clearly scoped to their original work. +- Markdown whitespace checks passed. A local-link and fragment check passed for + all ten changed Markdown files. Composed example behavior was exercised and + passed with Stage 9's example and complete ckprompt suite checks. + ## Stage 11: Reconcile notices and prepared release notes **Outcome:** distributed metadata/notices match actual graphs, and unpublished diff --git a/docs/roadmap/promptkit.md b/docs/roadmap/promptkit.md index f7b2cea..219c5ef 100644 --- a/docs/roadmap/promptkit.md +++ b/docs/roadmap/promptkit.md @@ -1,7 +1,8 @@ # Adopt PromptKit v0.14.0 and expose comparison and catalogs -Status: accepted feature end state; implementation has not started. Scope, -ownership, catalog API, and initial presentation choices are settled. +Status: comparison, catalogs, and current behavior documentation are implemented. +Dependency notice/release-note reconciliation and complete validation remain in +the [implementation record](implementation.md), Stages 11–12. ## Purpose and authority @@ -34,9 +35,7 @@ This roadmap defines the selected end state. The [implementation plan](implementation.md) assigns the ordered work and records stage completion evidence. -## Current baseline - -Baseline: CommandKit commit `ab270e2`. +## Baseline at commit ab270e2 CommandKit is a prerelease alpha codebase with no existing consumers. The maintained consumer examples demonstrate intended usage; this adoption needs no @@ -48,7 +47,19 @@ consumer migration plan. | `integrations/ckconfig` | ConfigKit v0.7.1; independent validate/show/sources/explain/diff capabilities, paired selection/input preparation, and the shared YAML comparison report and delivery path. Report placement uses a report-local mapping index. | | `integrations/ckprompt` | PromptKit v0.12.0 and ConfigKit v0.7.1. `ConfigScope` exposes validate/show/sources/explain, without comparison. `Suite` and `FromEngine` expose named prompt/profile inspection; `Command` generates only `promptkit show` children. | | Maintained composed consumer | Demonstrates both configuration scopes, app configuration comparison, named prompt/profile inspection, and an application-owned session command. Application configuration caching distinguishes selections and supplied campaign inputs. | -| Deferred work | PromptKit comparison and catalogs are recorded as future capabilities in [deferred.md](deferred.md). They are targets of this adoption; requirement inspection is deferred separately. | +| Deferred work | PromptKit comparison and catalogs were future capabilities at this baseline. The later adoption delivers them; requirement inspection remains deferred in [deferred.md](deferred.md). | + +## Delivered status + +The current repository uses PromptKit v0.14.0. `ConfigScope` declares native +comparison through `config diff`; `FromEngine` supplies prompt/profile catalog +and named-inspection callbacks; and `Command` installs only the supplied `list` +and `show` operations. The maintained composed consumer exercises comparison, +both catalogs, named inspection, and its application-owned session command. +Stages 1–10 and their completion evidence are recorded in the +[implementation plan](implementation.md). Requirement inspection remains +deferred; distribution reconciliation and complete validation are still pending +there. The existing [ckprompt contracts and adapters](../../integrations/ckprompt/adapters.go) and [command assembly](../../integrations/ckprompt/command.go) are the starting @@ -113,8 +124,8 @@ app config diff --scope promptkit --config before.yml --against-config after.yml app config diff --scope promptkit --config base.yml --against-overlay candidate ``` -These are target invocations, not currently implemented PromptKit comparisons. -They use the existing [comparison CLI contract](../cli.md#compare-configuration-selections): +These invocations use the existing +[comparison CLI contract](../cli.md#compare-configuration-selections): one scope, left selectors and inherited right overrides, shared applicable domain selector values, YAML-only additions/changes/deletions presentation, and success for completed comparisons regardless of whether differences exist. There is no @@ -290,7 +301,10 @@ exact strings; quote through the YAML encoder rather than interpreting numeric-looking versions. CommandKit defines these report fields explicitly; serialization of an upstream Go struct does not define the CLI schema. -## Work needed from the baseline +## Selected implementation scope + +The sections below record the scope selected for adoption. Implementation status +and evidence are tracked in the [implementation plan](implementation.md). ### Dependencies and distribution diff --git a/integrations/ckprompt/README.md b/integrations/ckprompt/README.md index 4e374c7..f9604f0 100644 --- a/integrations/ckprompt/README.md +++ b/integrations/ckprompt/README.md @@ -1,9 +1,8 @@ # CommandKit ckprompt -`ckprompt` is the optional PromptKit integration for CommandKit. It can adapt -PromptKit engine configuration into a `ckconfig.Scope` and create core command -declarations for named prompt and profile inspection. Importing it does not -install either command family. +`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. ## Module @@ -17,15 +16,16 @@ for callback, input, state, and acquisition contracts. ## Example Add `ckprompt.ConfigScope(loadEngine)` to the scopes passed to -`ckconfig.Command` when the application wants PromptKit engine configuration in -the `config` family. Install `ckprompt.Command(ckprompt.FromEngine(loadEngine))` -separately for named prompt and profile inspection. `FromEngine` supplies -PromptKit-backed callbacks; applications may provide their own callbacks with -`ckprompt.Suite`. CommandKit-owned inspection code does not execute prompts, -contact model providers, or resolve credentials; application loaders and direct -callbacks retain their own effects. See the +`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) -for the inspection boundary and report semantics. The maintained +for operator commands and report semantics. The maintained [composed example](examples/composed) shows complete application wiring. ## License and attribution diff --git a/integrations/ckprompt/adapters.go b/integrations/ckprompt/adapters.go index 5c498f6..ecb5ed2 100644 --- a/integrations/ckprompt/adapters.go +++ b/integrations/ckprompt/adapters.go @@ -36,15 +36,18 @@ type ProfileRequest struct { // construction failures. // Factory results and callback effects remain caller-owned: Command does not // deep-copy arbitrary objects or repair aliases returned by factories. +// A reached operation prepares one input, applies its captured selectors, and +// checks the input before creating state and calling the selected provider. // Factories are not invoked during construction, installation, help, or version, // and need not run after failure. type Suite[I, S any] struct { - // NewInput is called once when definition input preparation is reached, - // before applying selectors and calling CheckInput. + // NewInput is called once when definition or catalog input preparation is + // reached, before applying selectors and calling CheckInput. // If nil, input is the zero value of I, including nil for pointer types. NewInput func() I - // NewState is called once when inspection is reached, after input checks - // pass. If nil, state is the zero value of S, including nil for pointer types. + // NewState is called once when an inspection or catalog callback is reached, + // after input checks pass. If nil, state is the zero value of S, including + // nil for pointer types. NewState func() S // Selectors declares the original typed flags accepted by definition and // catalog commands. @@ -69,11 +72,12 @@ type Suite[I, S any] struct { type engineLoader[I, S any] func(context.Context, ckconfig.Selection, I, S) (*promptkit.Engine, error) // ConfigScope adapts PromptKit's captured configuration inspection to the -// standard configuration commands. The loader is not called during declaration -// construction or installation; it is called only when a config operation -// selects the promptkit scope, with that operation's input and shared state. -// PromptKit diagnostics and error identity are returned through ckconfig's -// acquisition contract. +// standard configuration commands, including native comparison when the scope +// declares Diff. The loader is not called during declaration construction or +// installation; it is called only when a config operation selects the +// promptkit scope, with that operation's input and shared state. PromptKit +// diagnostics and supported error identity are returned through ckconfig's +// acquisition and comparison contracts. func ConfigScope[I, S any](load func(context.Context, ckconfig.Selection, I, S) (*promptkit.Engine, error)) ckconfig.Scope[I, S] { scope := ckconfig.Scope[I, S]{ Name: "promptkit", @@ -139,11 +143,12 @@ func promptKitContextError(ctx context.Context) error { return ctx.Err() } -// FromEngine creates prompt and profile catalog and inspection callbacks 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. A nil loader is retained as an adapter +// FromEngine supplies callbacks for prompt and profile catalogs and named +// inspections 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. The callbacks can be +// narrowed 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 { diff --git a/integrations/ckprompt/command.go b/integrations/ckprompt/command.go index 9fcbe69..c33e571 100644 --- a/integrations/ckprompt/command.go +++ b/integrations/ckprompt/command.go @@ -31,11 +31,16 @@ type catalogInput[I any] struct { selected I } -// Command captures the optional PromptKit catalog and named inspection trees -// and adds only the operations present in suite. It adds no configuration -// family; callers compose ConfigScope independently. Construction and -// installation do not run suite callbacks. Suite documents invocation input -// and state initialization, zero values, and caller ownership of returned objects. +// Command captures the optional PromptKit catalog and named inspection +// callbacks and adds only supplied operations, generating list and show groups +// independently. An 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. +// 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. func Command[I, S any](suite Suite[I, S]) commandkit.Command { if suite.InspectPrompt == nil && suite.InspectProfile == nil && suite.ListPrompts == nil && suite.ListProfiles == nil { command := commandkit.NoCommand() diff --git a/integrations/ckprompt/doc.go b/integrations/ckprompt/doc.go index 7fff017..4f09281 100644 --- a/integrations/ckprompt/doc.go +++ b/integrations/ckprompt/doc.go @@ -1,4 +1,5 @@ -// Package ckprompt provides optional PromptKit configuration and named -// definition inspections for CommandKit. Importing ckprompt installs neither -// family; callers compose its declarations with core and ckconfig explicitly. +// 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. package ckprompt