144 lines
8.0 KiB
Markdown
144 lines
8.0 KiB
Markdown
|
|
# PromptKit v0.23.1 adoption
|
||
|
|
|
||
|
|
## Status and objective
|
||
|
|
|
||
|
|
Proposed. Adopt `go.maximumdirect.net/promptkit v0.23.1` in ckprompt and
|
||
|
|
prepare ckprompt v0.9.0. The work consists of dependency alignment,
|
||
|
|
CommandKit-level regression coverage, documentation, and release preparation.
|
||
|
|
|
||
|
|
The targeted result is that malformed PromptKit configuration encountered
|
||
|
|
through an application-owned engine loader receives CommandKit's existing
|
||
|
|
configuration-input classification. Preserve upstream diagnostics and error
|
||
|
|
identity through the integration. Continue delegating configuration semantics
|
||
|
|
and engine construction behavior to PromptKit and ConfigKit.
|
||
|
|
|
||
|
|
## Current baseline
|
||
|
|
|
||
|
|
This roadmap starts from CommandKit commit
|
||
|
|
`bf45a3f` and the released ckprompt v0.8.0 integration.
|
||
|
|
Its [module metadata](../../integrations/ckprompt/go.mod) selects the following
|
||
|
|
dependencies and consumer minimum.
|
||
|
|
|
||
|
|
| Item | Selected baseline | Adoption target |
|
||
|
|
| --- | --- | --- |
|
||
|
|
| PromptKit | v0.21.0 | v0.23.1 |
|
||
|
|
| ckconfig | v0.8.0 | v0.8.0 |
|
||
|
|
| CommandKit core | v0.6.0 | v0.6.0 |
|
||
|
|
| ConfigKit | v1.2.0 | v1.2.0 |
|
||
|
|
| Go consumer minimum | 1.27.0 | 1.27.0 |
|
||
|
|
|
||
|
|
ckconfig already owns the shared configuration-error classification function.
|
||
|
|
ckprompt uses that classification for engine acquisition failures and adapts
|
||
|
|
typed ConfigKit diagnostics into CommandKit reports. Core carries the selected
|
||
|
|
outcome through invocation reporting and presentation. The existing status
|
||
|
|
contract belongs to the [CLI reference](../cli.md#outcome-status).
|
||
|
|
|
||
|
|
The reported failure involves a valid application configuration that imports a
|
||
|
|
malformed PromptKit companion YAML file. Engine construction returns a typed
|
||
|
|
ConfigKit load error wrapped alongside PromptKit's `ErrInvalidConfig` sentinel.
|
||
|
|
With the earlier multi-error wrapper, the shared classifier encounters an
|
||
|
|
independent sentinel branch and selects operational failure, producing status 1
|
||
|
|
for catalog and configuration-inspection commands. The intended input-error
|
||
|
|
outcome is status 2 with the YAML diagnostic and source context preserved.
|
||
|
|
|
||
|
|
The user-supplied `promptkit-companion-yaml-exit-status.md` records the original
|
||
|
|
reproduction. Its observed application versions include PromptKit v0.23.0.
|
||
|
|
The constructor wrapper responsible for that behavior also exists in the
|
||
|
|
currently selected v0.21.0.
|
||
|
|
|
||
|
|
## Upstream changes and integration scope
|
||
|
|
|
||
|
|
PromptKit v0.23.1 resolves the constructor wrapping defect at source commit
|
||
|
|
`74066167942fcf6f70c112359995739ec9789fa6`. The wrapper exposes the original
|
||
|
|
cause through a single unwrap and recognizes `ErrInvalidConfig` through
|
||
|
|
`errors.Is`. Typed ConfigKit errors remain reachable through `errors.As`.
|
||
|
|
Genuine joined causes remain available for classification. The adoption can
|
||
|
|
therefore use ckconfig's existing classifier. [Upstream constructor](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/74066167942fcf6f70c112359995739ec9789fa6/engine.go)
|
||
|
|
and [error implementation](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/74066167942fcf6f70c112359995739ec9789fa6/errors.go).
|
||
|
|
|
||
|
|
The intervening releases add opt-in conversation capture, continuation,
|
||
|
|
coordination, execution-group summaries, operation timeouts, and prepared-run
|
||
|
|
notifications. Applications own engine setup, native request construction, and
|
||
|
|
execution. Existing native request builders provide the integration point for
|
||
|
|
application-selected request capabilities. Prepared reports continue to expose
|
||
|
|
upstream fields through the existing report path. Review those additive shapes
|
||
|
|
for compatibility during the upgrade. [Upstream consumer guidance](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/74066167942fcf6f70c112359995739ec9789fa6/docs/consumers/pkg-promptkit.md).
|
||
|
|
|
||
|
|
Keep the adoption focused on existing CommandKit operator tasks and the
|
||
|
|
constructor-error fix. Additional CLI capabilities remain subject to the
|
||
|
|
operator needs recorded in [future work](future.md). Preparation and validation
|
||
|
|
documentation should describe the upstream operations actually invoked,
|
||
|
|
including their handling of contexts and request options.
|
||
|
|
|
||
|
|
## Work needed
|
||
|
|
|
||
|
|
### 1. Update the selected dependency
|
||
|
|
|
||
|
|
- Update ckprompt's `go.mod` and `go.sum` to PromptKit v0.23.1 using the
|
||
|
|
published module and its checksums.
|
||
|
|
- Review the resolved module graph against the baseline above. Upstream's
|
||
|
|
module requirements support the existing ConfigKit and Go selections.
|
||
|
|
- Check the selected source's license and notices. Update ckprompt's
|
||
|
|
[attribution](../../integrations/ckprompt/docs/oss/attribution.md) to v0.23.1
|
||
|
|
and its exact source revision. The reviewed upstream license and copyright
|
||
|
|
texts match the v0.21.0 texts.
|
||
|
|
|
||
|
|
### 2. Add regression coverage through real engine construction
|
||
|
|
|
||
|
|
Use local fixtures and `promptkit.NewEngine` through application-owned loader
|
||
|
|
callbacks so the tests include PromptKit's actual public error wrapper. Build
|
||
|
|
on the existing integration tests and configuration-outcome helpers.
|
||
|
|
|
||
|
|
- Exercise malformed companion YAML through a representative `FromEngine`
|
||
|
|
catalog command and the `ConfigScope` show, sources, validate, explain
|
||
|
|
discovery, and diff paths. Cover comparison-side acquisition where it has a
|
||
|
|
distinct failure path.
|
||
|
|
- Verify the existing usage outcome and status 2, the `yaml.invalid`
|
||
|
|
diagnostic and its source context, and the reports supported by sources and
|
||
|
|
validate. Retain access to `*configkit.LoadError` and recognition of
|
||
|
|
`promptkit.ErrInvalidConfig` on the propagated error.
|
||
|
|
- Cover an operational constructor failure and genuine mixed causes so the
|
||
|
|
sentinel's presence does not turn operational failures into usage failures.
|
||
|
|
Include cancellation using the existing cancellation contract and test
|
||
|
|
helpers, retaining status 1 and the cancellation cause.
|
||
|
|
- Confirm that the existing classifier and diagnostic adapters handle these
|
||
|
|
upstream errors. Scope any implementation adjustment to a demonstrated
|
||
|
|
integration failure found during this work.
|
||
|
|
|
||
|
|
The review already exercised real constructor failures against v0.23.1 using
|
||
|
|
temporary module selection. Catalog and all five configuration operations
|
||
|
|
returned status 2 for malformed YAML. Typed identity and mixed-cause
|
||
|
|
classification were preserved. Maintained regression coverage is the remaining
|
||
|
|
work needed to keep that integration behavior checked in the repository.
|
||
|
|
|
||
|
|
### 3. Validate compatibility and update documentation
|
||
|
|
|
||
|
|
- Run ckprompt's complete default suite independently against its published
|
||
|
|
dependency selections with `GOWORK=off`.
|
||
|
|
- Exercise the aligned local workspace and maintained composed consumer for
|
||
|
|
the changed integration paths, following the [developer guide](../development.md#documentation-validation).
|
||
|
|
The review's temporary v0.23.1 selection passed the independent ckprompt and
|
||
|
|
composed-consumer suites.
|
||
|
|
- Review native request and report use for the additive upstream fields,
|
||
|
|
including prepared-run parent identifiers where applicable. Keep tests
|
||
|
|
focused on CommandKit's forwarding and presentation responsibilities.
|
||
|
|
- Update the [consumer guide](../consumers/guide.md), relevant
|
||
|
|
[CLI reference](../cli.md) upstream links, and affected GoDoc to match the
|
||
|
|
selected dependency and existing integration behavior. Use brief integration
|
||
|
|
guidance and upstream references for application-owned capabilities.
|
||
|
|
|
||
|
|
### 4. Prepare the integration release and completion records
|
||
|
|
|
||
|
|
- Prepare `integrations/ckprompt/docs/releases/v0.9.0.md`, explaining the
|
||
|
|
PromptKit upgrade and corrected constructor-failure classification, with the
|
||
|
|
release navigation required by the existing policies.
|
||
|
|
- Update current compatibility documentation for the prepared ckprompt version
|
||
|
|
at the appropriate release-preparation point. Distinguish prepared and
|
||
|
|
published versions in completion records.
|
||
|
|
- Record completed work and verification. Retire this roadmap and the resolved
|
||
|
|
companion-YAML report when their work is complete, preserving any unfinished
|
||
|
|
items in [future work](future.md) and repairing affected references.
|
||
|
|
- Follow the existing [release procedure](../release.md) when publication is
|
||
|
|
authorized. ckprompt can release independently under the
|
||
|
|
[module alignment policy](../policy/release.md#commandkit-downstream-dependency-alignment).
|