commandkit/integrations/ckprompt/examples/composed/README.md

Composed consumer

This example is part of the ckprompt module and uses core v0.4.0, ckconfig v0.3.0, ConfigKit v1.1.0, and PromptKit v0.20.0. It requires Go 1.27.0. The current work uses the aligned local workspace until the required ckconfig release is published.

This example composes application configuration, PromptKit configuration, PromptKit comparison and catalogs, definition and requirements inspection, and one application-owned command:

go run . config scopes
go run . config validate --scope all --campaign spring --limit=0
go run . config diff --scope app --config fixtures/before.yml --against-config fixtures/after.yml
go run . config diff --scope app --config fixtures/before.yml --against-config fixtures/after.yml --campaign spring --limit=0
go run . config diff --scope app --campaign spring --limit=0 --against-campaign autumn --against-limit=0 --set '/campaigns/spring/model="left"' --against-set '/campaigns/spring/model="right"' --details
go run . config diff --scope promptkit --config fixtures/before.yml --against-config fixtures/after.yml --campaign spring --against-campaign spring
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 list backends --campaign spring
go run . promptkit list namespaces --campaign spring
go run . promptkit list collections --campaign spring
go run . list collections --campaign spring
go run . pk list bundles --campaign spring
go run . promptkit list prompts --namespace field-notes --campaign spring
go run . promptkit show prompt briefing --campaign spring --format yaml
go run . promptkit show prompt briefing --campaign spring --prompt-namespace field-notes
go run . promptkit show prepared briefing --campaign spring --input topic=sprint --profile spring --extra-params '{"campaign":"preview"}'
go run . pk show prompt briefing --campaign spring --fmt 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 . promptkit requirements validate briefing --campaign spring --llm-input-file topic=fixtures/topic.txt
go run . promptkit requirements validate briefing --campaign spring --llm-input-file topic=fixtures/topic.txt --llm-var mode=full --llm-input-file notes=fixtures/notes.txt --format yaml
go run . promptkit requirements validate briefing --campaign spring
go run . promptkit test text_inference --campaign spring --prompt briefing --profile spring
go run . smoke text_inference --campaign spring --llm-prompt briefing --llm-profile spring
go run . promptkit test all --campaign spring --llm-prompt briefing --llm-profile spring
go run . pk --hlep
go run . session restore session-42 --campaign spring
go run . request inspect --llm-prompt briefing --llm-profile= --llm-model example --llm-input-text topic=sprint --format json

newApp installs application-owned command and flag aliases alongside the complete ckconfig and ckprompt declarations. list collections and promptkit list bundles both reach the canonical collection command; pk shortens the PromptKit group. --fmt is scoped to named prompt inspection and --hlep is available globally. The smoke shortcut retains the canonical promptkit test KIND operand, including the special all aggregate.

The example installs Completion("composed-example"). Build it as go build -o composed-example .. Initialize bash-completion first if using Bash, then load a shell script as described in the CLI reference. Try completion after composed-example pk show prompt briefing --fmt= or after the filename prefix in composed-example config show --config=fixtures/. The already-entered pk alias selects the PromptKit command context without loading an engine.

The composition installs ckconfig.Command(suite) and the complete ckprompt.Declarations(definitions) in a []commandkit.Declaration with root-installed routing rules. The PromptKit declarations include scoped aliases; the application-owned request inspect command reuses the flag collections with their canonical names and does not install those aliases. Group children remain canonical Command values. For command-only slices, convert each Command to Declaration before appending aliases. The consumer guide includes minimal direct-call and slice-conversion examples; this README documents the maintained complete consumer.

The sources and session store are small in-memory fixtures. --campaign is a typed selector shared by the app and PromptKit configuration scopes. Their ckconfig.Suite[*inspectionInput, *runCache] uses NewInput to initialize each selected scope's input separately and NewState to create one cache shared by that invocation's acquisitions. Prompt/profile inspection prepares its input and cache independently for its invocation, using the same application and engine loader functions. See the consumer guide and the suites' GoDoc for initialization timing and ownership.

The application-scope comparison reports the changed default campaign and the updated campaigns.spring.model. The PromptKit-scope comparison selects spring on both sides and reports the native engine change in the atomic profiles list. The application input check requires --limit=0 when --campaign is supplied. Catalogs use the same selection-aware loader: the prompt catalog includes briefing, and the profile catalog includes the selected autumn profile. Prompt inspection uses an ID only. The default PromptKit bundle also contributes profiles and a backend to the engine inventory and source reports. The synthetic field-notes collection provides one backend, profile, and prompt for collection discovery and native namespace filtering. The example's shared run cache keys successful results by the complete supplied configuration/overlay selection, CLI overrides, and the supplied campaign, including presence. The campaign override and application scope's --set records are applied through ConfigKit before loading. The PromptKit configuration scope does not enable --set because its released configuration loader has no override handoff. An aggregate operation therefore rejects overrides when that scope is selected. These are choices for this example's loaders and do not define a CommandKit cache policy.

Smoke testing is explicitly wired with ckprompt.WithSmokeTesting and its optional request builder is nil, so CommandKit forwards the selected native request. Applications that need to adjust the request can provide a typed builder that starts with the seed and returns the chosen native request:

definitions = ckprompt.WithSmokeTesting(definitions, loadEngine,
	func(ctx context.Context, seed ckprompt.SmokeRequest, input *inspectionInput, state *runCache) (promptkit.SmokeTestRequest, error) {
		request := seed.Request
		request.ProfileID = "spring"
		return request, nil
	})

The example injects a small in-memory promptkit.LLMClient through its shared run state. Catalog, inspection, and requirements commands do not call it; inference smoke commands do. No model service or credentials are required. Native HTTP checks may retain unsupported or not-applicable observations because the selected local backend does not configure a network probe. An aggregate smoke command can return an operational outcome for a native diagnostic while still delivering the complete aggregate report.

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 for the command and report contract.

The validation and preview commands exercise concrete PromptKit request preparation. The first uses the builder's campaign-specific default topic variable and the operator's topic file. The second also selects the notes branch and supplies its file. Validation reports only prompt_id and valid: true; preview returns the prepared request, including rendered messages and effective provider settings. Neither executes the prompt. The validation command without inputs intentionally fails because the prompt's required topic artifact is not supplied. The builder defaults variables from the selected campaign but leaves artifact bindings to the operator. The requirements show commands remain discovery reports: partial discovery can succeed even when a concrete request would fail validation.

Use the aligned local workspace to test the three current sources, as described in the developer guide. Once released dependency requirements are aligned, GOWORK=off go test ./... from this example directory checks it against its declared dependencies.