Compare commits
2 Commits
v0.5.0
...
integratio
| Author | SHA1 | Date | |
|---|---|---|---|
| 88ac6e76e4 | |||
| 5c96053255 |
@@ -14,28 +14,27 @@ applications.
|
|||||||
| `go.maximumdirect.net/ckconfig` | You want operators to view, validate, explain, and compare ConfigKit configuration. |
|
| `go.maximumdirect.net/ckconfig` | You want operators to view, validate, explain, and compare ConfigKit configuration. |
|
||||||
| `go.maximumdirect.net/ckprompt` | You want operators to inspect PromptKit resources, check and preview requests, or run smoke tests. |
|
| `go.maximumdirect.net/ckprompt` | You want operators to inspect PromptKit resources, check and preview requests, or run smoke tests. |
|
||||||
|
|
||||||
The following distinguishes published combinations from the current checkout:
|
The following lists the current release set and earlier module combinations:
|
||||||
|
|
||||||
| Selection | Core | ckconfig | ckprompt | Upstream libraries and status |
|
| Selection | Core | ckconfig | ckprompt | Upstream libraries and status |
|
||||||
| --- | --- | --- | --- | --- |
|
| --- | --- | --- | --- | --- |
|
||||||
| Published core | v0.4.0 | — | — | Usable independently. |
|
| Published core | v0.5.0 | — | — | Usable independently. |
|
||||||
| Published ConfigKit integration | v0.4.0 | v0.4.0 | — | ConfigKit v1.1.0. |
|
| ConfigKit integration | v0.5.0 | v0.5.0 | — | ConfigKit v1.1.0. |
|
||||||
|
| PromptKit integration | v0.5.0 | v0.5.0 | v0.5.0 | ConfigKit v1.1.0 and PromptKit v0.20.0. |
|
||||||
| Earlier matched integration set | v0.3.0 | v0.2.0 | v0.2.0 | ConfigKit v0.8.0 and PromptKit v0.16.0, using their earlier import paths. |
|
| Earlier matched integration set | v0.3.0 | v0.2.0 | v0.2.0 | ConfigKit v0.8.0 and PromptKit v0.16.0, using their earlier import paths. |
|
||||||
| Current source | Local | Local | Local | ConfigKit v1.1.0 and PromptKit v0.20.0; use an aligned workspace until release dependencies are updated. |
|
|
||||||
|
|
||||||
Install the published core with:
|
Install the published core with:
|
||||||
|
|
||||||
```sh
|
```sh
|
||||||
go get go.maximumdirect.net/commandkit@v0.4.0
|
go get go.maximumdirect.net/commandkit@v0.5.0
|
||||||
```
|
```
|
||||||
|
|
||||||
Core v0.5.0 and ckprompt v0.3.0 have unpublished candidate notes. Current
|
Select either integration with `go get go.maximumdirect.net/ckconfig@v0.5.0`
|
||||||
ckprompt source calls `ckconfig.AdaptDiagnostics`, which is absent from its
|
or `go get go.maximumdirect.net/ckprompt@v0.5.0`. The integrations select core
|
||||||
selected released ckconfig v0.4.0 dependency. It therefore needs local
|
v0.5.0, and ckprompt selects ckconfig v0.5.0, which includes `AdaptDiagnostics`.
|
||||||
ckconfig source in the workspace until [release
|
They build independently against these released dependencies; a local workspace
|
||||||
alignment](../roadmap/future.md#pending-release-and-integration-work) is
|
is optional for development. Published ckconfig v0.3.0 also uses ConfigKit v1.1.0
|
||||||
complete. Published ckconfig v0.3.0 also uses ConfigKit v1.1.0 and does not
|
and does not compose with ckprompt v0.2.0's earlier ConfigKit dependency.
|
||||||
compose with ckprompt v0.2.0's earlier ConfigKit dependency.
|
|
||||||
|
|
||||||
Importing a module does not install its commands. Pass commands to
|
Importing a module does not install its commands. Pass commands to
|
||||||
`commandkit.New` or `App.Register` explicitly. ckprompt depends on ckconfig's
|
`commandkit.New` or `App.Register` explicitly. ckprompt depends on ckconfig's
|
||||||
|
|||||||
@@ -62,7 +62,7 @@ capability proposals in [future work](roadmap/future.md).
|
|||||||
| Public facade or adapter boundaries | [Internal overview](internal/overview.md), [ADR 0002](adr/0002-public-facade-and-cli-backend.md), [ADR 0004](adr/0004-optional-integration-modules.md), and the architecture policy |
|
| Public facade or adapter boundaries | [Internal overview](internal/overview.md), [ADR 0002](adr/0002-public-facade-and-cli-backend.md), [ADR 0004](adr/0004-optional-integration-modules.md), and the architecture policy |
|
||||||
| Module ownership and public contracts | [Consumer guide](consumers/guide.md), [internal overview](internal/overview.md), [core GoDoc](../doc.go), [ckconfig GoDoc](../integrations/ckconfig/doc.go), [ckprompt GoDoc](../integrations/ckprompt/doc.go), and applicable ADRs |
|
| Module ownership and public contracts | [Consumer guide](consumers/guide.md), [internal overview](internal/overview.md), [core GoDoc](../doc.go), [ckconfig GoDoc](../integrations/ckconfig/doc.go), [ckprompt GoDoc](../integrations/ckprompt/doc.go), and applicable ADRs |
|
||||||
| Unfinished work and capability proposals | [Future work](roadmap/future.md) |
|
| Unfinished work and capability proposals | [Future work](roadmap/future.md) |
|
||||||
| Documentation refresh record | [Documentation roadmap](roadmap/documentation-refresh.md) |
|
| Completed documentation refresh | [Retired refresh record](https://forge.maximumdirect.net/base-layer/commandkit/src/commit/5c960532552037d38119941389e558f78bf73aad/docs/roadmap/documentation-refresh.md) |
|
||||||
| Completed planning and implementation history | [Completed dependency upgrades, PromptKit validation, discovery, smoke testing, and remediation](https://gitea.maximumdirect.net/eric/CommandKit/src/commit/a6278a6d9f940948ec7745955d745523aaff0734/docs/roadmap), [earlier ConfigKit and PromptKit adoption and remediation](https://gitea.maximumdirect.net/eric/CommandKit/src/commit/8a82620dfcd34c0ae56bbecb0d014eb49786bc92/docs/roadmap), [earlier retired records](https://gitea.maximumdirect.net/eric/CommandKit/src/commit/6bc37e7ba64ca0920b4d0cc77039a18d4006b24e/docs/roadmap), and [completed module implementation and remediation](https://gitea.maximumdirect.net/eric/CommandKit/src/commit/bb2528532b78d30e52f5082e491a5e1fd9b0fb99/docs/roadmap) in Git history |
|
| Completed planning and implementation history | [Completed dependency upgrades, PromptKit validation, discovery, smoke testing, and remediation](https://gitea.maximumdirect.net/eric/CommandKit/src/commit/a6278a6d9f940948ec7745955d745523aaff0734/docs/roadmap), [earlier ConfigKit and PromptKit adoption and remediation](https://gitea.maximumdirect.net/eric/CommandKit/src/commit/8a82620dfcd34c0ae56bbecb0d014eb49786bc92/docs/roadmap), [earlier retired records](https://gitea.maximumdirect.net/eric/CommandKit/src/commit/6bc37e7ba64ca0920b4d0cc77039a18d4006b24e/docs/roadmap), and [completed module implementation and remediation](https://gitea.maximumdirect.net/eric/CommandKit/src/commit/bb2528532b78d30e52f5082e491a5e1fd9b0fb99/docs/roadmap) in Git history |
|
||||||
| Release tooling | [Maintainer release procedure](release.md) |
|
| Release tooling | [Maintainer release procedure](release.md) |
|
||||||
| Performance maintenance | [Internal overview](internal/overview.md), existing benchmarks, and [possible further efficiency work](roadmap/future.md#possible-further-efficiency-work) |
|
| Performance maintenance | [Internal overview](internal/overview.md), existing benchmarks, and [possible further efficiency work](roadmap/future.md#possible-further-efficiency-work) |
|
||||||
@@ -117,11 +117,10 @@ go work init . ./integrations/ckconfig ./integrations/ckprompt
|
|||||||
If a workspace already exists, ensure it includes these three modules. Preserve
|
If a workspace already exists, ensure it includes these three modules. Preserve
|
||||||
the ignored `go.work` and `go.work.sum`; do not commit them. Use
|
the ignored `go.work` and `go.work.sum`; do not commit them. Use
|
||||||
`GOWORK=off GOTOOLCHAIN=local` for dependency preparation
|
`GOWORK=off GOTOOLCHAIN=local` for dependency preparation
|
||||||
and independent module suites. The integrations select released core v0.4.0;
|
and independent module suites. Both integrations select released core v0.5.0;
|
||||||
ckprompt also selects released ckconfig v0.4.0.
|
ckprompt also selects released ckconfig v0.5.0. Their declared dependencies
|
||||||
Current ckprompt source requires a ckconfig helper absent from that release, so
|
support independent builds. The aligned workspace exercises the local sources
|
||||||
its independent suite remains pending release and dependency alignment; the
|
together.
|
||||||
aligned workspace exercises the current source together.
|
|
||||||
Run `GOWORK=off GOTOOLCHAIN=local go test ./...` separately from each module
|
Run `GOWORK=off GOTOOLCHAIN=local go test ./...` separately from each module
|
||||||
directory. From the repository root, a workspace containing all three modules can
|
directory. From the repository root, a workspace containing all three modules can
|
||||||
also run:
|
also run:
|
||||||
|
|||||||
@@ -117,11 +117,11 @@ GOWORK=off GOTOOLCHAIN=local go get \
|
|||||||
go.maximumdirect.net/ckconfig@vCKCONFIG_VERSION
|
go.maximumdirect.net/ckconfig@vCKCONFIG_VERSION
|
||||||
```
|
```
|
||||||
|
|
||||||
Run only the command for the integration being prepared. In the current release
|
Run only the command for the integration being prepared. ckprompt needs a
|
||||||
sequence, ckprompt needs a ckconfig release containing `AdaptDiagnostics`;
|
ckconfig release containing `AdaptDiagnostics`; v0.5.0 contains it, while v0.4.0
|
||||||
ckconfig v0.4.0 does not contain it. Validate the integration with the workspace
|
does not. Validate the integration with the workspace disabled against its
|
||||||
disabled against its updated requirements, using the selected module's release
|
updated requirements, using the selected module's release validation below.
|
||||||
validation below. An aligned workspace can hide an outdated dependency.
|
An aligned workspace can hide an outdated dependency.
|
||||||
|
|
||||||
Review and commit the resulting `go.mod` and `go.sum` changes with the release
|
Review and commit the resulting `go.mod` and `go.sum` changes with the release
|
||||||
candidate, and make its release note agree with the selected versions. The sum
|
candidate, and make its release note agree with the selected versions. The sum
|
||||||
|
|||||||
@@ -1,253 +0,0 @@
|
|||||||
# Documentation refresh
|
|
||||||
|
|
||||||
Status: implemented and verified. Release/dependency alignment remains separate
|
|
||||||
work in [future.md](future.md#pending-release-and-integration-work).
|
|
||||||
|
|
||||||
## Purpose
|
|
||||||
|
|
||||||
Refresh CommandKit's documentation for the next minor release. Operators should
|
|
||||||
be able to find a command, understand what it does, and interpret its results
|
|
||||||
without learning the implementation. Application developers should have a short
|
|
||||||
path from choosing a module to using its public API. Maintainer documentation
|
|
||||||
and exact API contracts can retain technical detail where it is useful.
|
|
||||||
|
|
||||||
This roadmap captures the accepted documentation review recommendations. The
|
|
||||||
[documentation policy](../policy/documentation.md) remains authoritative for
|
|
||||||
audience, canonical ownership, examples, and document lifecycle. No new policy,
|
|
||||||
documentation framework, or ADR is needed.
|
|
||||||
|
|
||||||
## Scope and boundaries
|
|
||||||
|
|
||||||
The sprint covers current READMEs, the CLI reference, consumer guidance,
|
|
||||||
maintained example instructions, generated help descriptions, package
|
|
||||||
introductions, and release notes being prepared for publication.
|
|
||||||
|
|
||||||
Preserve API and CLI behavior: command and flag names, defaults, format
|
|
||||||
selection, report fields, status semantics, availability, and ownership rules.
|
|
||||||
Source edits for help text and GoDoc are in scope; runtime refactoring and new
|
|
||||||
features are not. If review exposes a behavioral defect or an unresolved
|
|
||||||
contract, record it separately rather than silently changing behavior through
|
|
||||||
an editorial revision.
|
|
||||||
|
|
||||||
Use existing documentation owners. Move useful detail to its appropriate owner
|
|
||||||
or link to the existing explanation; do not duplicate contracts. Keep exact
|
|
||||||
ownership, callback lifetime, error identity, and concurrency rules in GoDoc.
|
|
||||||
Internal documentation and maintainer procedures need only changes justified by
|
|
||||||
clarity or affected navigation, not a wholesale simplification.
|
|
||||||
|
|
||||||
Preserve accepted ADR decisions, historical published release records, license
|
|
||||||
texts, and attribution. Apply release-note editing to unpublished candidates
|
|
||||||
after checking their publication status under the
|
|
||||||
[release policy](../policy/release.md). Dependency alignment and publication
|
|
||||||
remain separate work under the [release procedure](../release.md).
|
|
||||||
|
|
||||||
## Audience and writing approach
|
|
||||||
|
|
||||||
| Audience | Starting points | Approach |
|
|
||||||
| --- | --- | --- |
|
|
||||||
| Prospective users | Root and integration READMEs | Explain purpose, useful capabilities, and where to start. |
|
|
||||||
| CLI operators | CLI reference and generated help | Lead with tasks, commands, results, and relevant limitations. |
|
|
||||||
| Go application developers | Consumer guide, examples, package introductions | Show a small useful integration first; explain choices and responsibilities next. |
|
|
||||||
| API users and maintainers | Symbol GoDoc, internal docs, development and release guides | Retain precise technical detail needed for correct use and maintenance. |
|
|
||||||
|
|
||||||
Use short, direct sentences and familiar terms. Define necessary domain terms
|
|
||||||
where first used; avoid a separate glossary unless one proves useful. For
|
|
||||||
example, explain a configuration scope as a named configuration such as `app`
|
|
||||||
or `promptkit`.
|
|
||||||
|
|
||||||
Where meaning permits, prefer “load configuration” to “acquire configuration,”
|
|
||||||
“command output” to “substantive results,” and “files and other sources used to
|
|
||||||
load configuration” to “source inventory captured during acquisition.” These
|
|
||||||
are editorial examples, not a mechanical replacement list. Keep technical names
|
|
||||||
when referring to an API symbol or a distinction that matters to the reader.
|
|
||||||
|
|
||||||
## Work areas
|
|
||||||
|
|
||||||
### 1. Product and module introductions
|
|
||||||
|
|
||||||
Update the [root README](../../README.md), [ckconfig README](../../integrations/ckconfig/README.md),
|
|
||||||
and [ckprompt README](../../integrations/ckprompt/README.md).
|
|
||||||
|
|
||||||
- Explain what the library helps applications and operators do before describing
|
|
||||||
declarations, adapters, or reporting internals.
|
|
||||||
- Keep the module overview, explicit installation distinction, and navigation.
|
|
||||||
Link to the consumer guide for compatibility and integration details.
|
|
||||||
- Provide the shortest useful starting example or a direct link to it, rather
|
|
||||||
than a catalog of callback counts or implementation responsibilities.
|
|
||||||
|
|
||||||
An illustrative root opening is: “CommandKit helps Go applications build
|
|
||||||
consistent command-line interfaces. It provides typed flags and arguments,
|
|
||||||
help, output formatting, and error reporting. Optional integrations add commands
|
|
||||||
for inspecting configuration and working with PromptKit.” Final wording can
|
|
||||||
evolve during implementation.
|
|
||||||
|
|
||||||
### 2. CLI tasks and reference detail
|
|
||||||
|
|
||||||
Refresh the [CLI reference](../cli.md), particularly reporting, configuration,
|
|
||||||
prepared-request preview, requirements, and smoke testing.
|
|
||||||
|
|
||||||
- Begin each operation with its purpose and a small command example. Explain
|
|
||||||
results and important limitations before detailed report fields.
|
|
||||||
- Replace installation and callback introductions with an operator explanation
|
|
||||||
of command availability; link to the consumer guide for application wiring.
|
|
||||||
- Move API-only material such as callback construction, writer ownership, and
|
|
||||||
`Outcome.Presentation` access to its existing developer-facing owner where
|
|
||||||
appropriate. Retain observable output, failure, and status behavior here.
|
|
||||||
- Organize detailed report shapes and edge cases into reference subsections so
|
|
||||||
they remain available without interrupting the ordinary task.
|
|
||||||
- Make application-defined flags and optional convenience aliases identifiable;
|
|
||||||
examples must not imply every application installs them.
|
|
||||||
|
|
||||||
Retain distinctions operators need: omission versus an explicit empty value,
|
|
||||||
concise versus detailed reports, independent comparison sides, redaction,
|
|
||||||
partial evidence on failure, and which operations can contact providers.
|
|
||||||
Explain that requirements discovery, request validation, prepared preview, and
|
|
||||||
smoke testing answer different questions. Successful preparation does not
|
|
||||||
guarantee later execution, and a smoke command's successful status does not
|
|
||||||
mean every reported observation is positive.
|
|
||||||
|
|
||||||
### 3. Guided examples
|
|
||||||
|
|
||||||
Refresh the [core example](../../examples/core/README.md),
|
|
||||||
[ConfigKit example](../../integrations/ckconfig/examples/simple/README.md), and
|
|
||||||
[composed example](../../integrations/ckprompt/examples/composed/README.md).
|
|
||||||
|
|
||||||
- State the working directory, required Go version, and applicable workspace or
|
|
||||||
independent-module setup before commands.
|
|
||||||
- Start with a few useful commands and explain expected results beside them.
|
|
||||||
Group additional examples by task rather than presenting one long command block.
|
|
||||||
- Label intentional failures beside the relevant command, including how to
|
|
||||||
interpret the result. Distinguish application status from `go run`'s own exit
|
|
||||||
behavior when explaining shell results.
|
|
||||||
- Explain early that the composed example uses local fixtures and requires no
|
|
||||||
model service or credentials; do not imply this about every consuming app.
|
|
||||||
- Put alias wiring, shared state, and cache explanations after the walkthrough,
|
|
||||||
linking to API contracts rather than repeating them.
|
|
||||||
|
|
||||||
### 4. Consumer guide and public API orientation
|
|
||||||
|
|
||||||
Update the [consumer guide](../consumers/guide.md) and the package introductions
|
|
||||||
in [core](../../doc.go), [ckconfig](../../integrations/ckconfig/doc.go), and
|
|
||||||
[ckprompt](../../integrations/ckprompt/doc.go).
|
|
||||||
|
|
||||||
- Demonstrate `Reporter.Report` with a small value so the recommended path to
|
|
||||||
shared `--format` support is visible. Explain raw output as a separate choice.
|
|
||||||
- Make the initial greeting example's name, description, and output agree; it
|
|
||||||
currently prints the count rather than a greeting.
|
|
||||||
- Present module compatibility in a compact table that distinguishes published
|
|
||||||
releases from current source requirements. Keep exact version guidance in
|
|
||||||
this owner and link from module introductions.
|
|
||||||
- Lead package introductions with purpose and primary entry points. Keep exact
|
|
||||||
symbol contracts in GoDoc, including factory timing, supplied values, error
|
|
||||||
handling, and object ownership.
|
|
||||||
|
|
||||||
Recheck compatibility statements when implementing the refresh. Current source
|
|
||||||
and released dependencies can differ; the
|
|
||||||
[pending alignment work](future.md#pending-release-and-integration-work) owns
|
|
||||||
the outstanding release work. Do not present workspace success as proof that
|
|
||||||
the selected published dependencies support an independent build.
|
|
||||||
|
|
||||||
### 5. Generated help
|
|
||||||
|
|
||||||
Review command summaries, descriptions, flag usage, and argument usage across
|
|
||||||
core and both integrations. These strings are operator documentation even when
|
|
||||||
stored in Go source.
|
|
||||||
|
|
||||||
Use action-oriented descriptions and explain choices where useful. In
|
|
||||||
particular, the [smoke command](../../integrations/ckprompt/smoke_command.go)
|
|
||||||
should explain that it can run one test or all tests and identify accepted kinds;
|
|
||||||
“Run one PromptKit smoke test” and “Native smoke-test kind” are insufficient.
|
|
||||||
The [request flag descriptions](../../integrations/ckprompt/request_flags.go)
|
|
||||||
can use direct wording such as “Use this model.” Preserve flag names, grammar,
|
|
||||||
defaults, and supported operations.
|
|
||||||
|
|
||||||
### 6. Release notes
|
|
||||||
|
|
||||||
Review the [core v0.5.0 note](../releases/v0.5.0.md) and applicable unpublished
|
|
||||||
integration candidates for the upcoming releases. Explain user benefits before
|
|
||||||
implementation mechanisms: accepted deferred messages are no longer lost,
|
|
||||||
YAML values retain their intended types, and installation and help avoid repeated
|
|
||||||
work. Remove unnecessary discussion of scratch paths, chain suffixes, and batch
|
|
||||||
detachment from the release summary.
|
|
||||||
|
|
||||||
Retain compatibility guidance, required consumer actions, meaningful API names,
|
|
||||||
and license/attribution links. Verify candidate dependencies against the versions
|
|
||||||
actually selected for publication. Do not invent release dates or performance
|
|
||||||
guarantees, or revise published historical notes as part of this refresh.
|
|
||||||
|
|
||||||
## Suggested sprint sequence
|
|
||||||
|
|
||||||
1. Refresh README introductions and the CLI reference together to establish
|
|
||||||
vocabulary and the operator/developer split.
|
|
||||||
2. Update example walkthroughs and generated help to match that language.
|
|
||||||
3. Polish consumer guidance, package introductions, and candidate release notes.
|
|
||||||
4. Review the changed documentation together for consistency and validate the
|
|
||||||
affected examples, help, and navigation.
|
|
||||||
|
|
||||||
No unresolved product decision blocks implementation planning. Exact wording,
|
|
||||||
section placement, and illustrative examples are ordinary editorial choices.
|
|
||||||
|
|
||||||
## Validation and completion checklist
|
|
||||||
|
|
||||||
Use the existing [documentation checks](../development.md#documentation-validation)
|
|
||||||
and [testing policy](../policy/testing.md). Review prose and local links; run
|
|
||||||
affected maintained examples and inspect representative help when those change.
|
|
||||||
For Go example or help-source edits, run the relevant existing package tests.
|
|
||||||
Do not add wording snapshots, readability gates, or a new checker framework.
|
|
||||||
Record workspace and independent-module results separately, including any
|
|
||||||
dependency limitation. This work adds no release gates.
|
|
||||||
|
|
||||||
- [x] README openings explain purpose and give a clear starting path.
|
|
||||||
- [x] CLI sections explain operator tasks before reference detail; necessary
|
|
||||||
behavior, report fields, status rules, and limitations remain discoverable.
|
|
||||||
- [x] Example setup is explicit, commands have nearby explanations, and intended
|
|
||||||
failures are labeled.
|
|
||||||
- [x] Consumer guidance demonstrates formatted reporting, has a coherent initial
|
|
||||||
example, and distinguishes published compatibility from current source needs.
|
|
||||||
- [x] Package introductions and generated help use clear, accurate language;
|
|
||||||
precise API contracts remain intact.
|
|
||||||
- [x] Unpublished release notes explain benefits and consumer impact while
|
|
||||||
historical records and required notices remain preserved.
|
|
||||||
- [x] Changed commands, snippets, and help have appropriate verification; local
|
|
||||||
links and Markdown whitespace checks pass.
|
|
||||||
- [x] Final review confirms consistent terminology, canonical ownership, and no
|
|
||||||
unintended behavior or contract changes.
|
|
||||||
|
|
||||||
## Implementation and verification
|
|
||||||
|
|
||||||
Completed the six work areas above. READMEs and package introductions now lead
|
|
||||||
with purpose and starting points; the CLI reference separates operator tasks
|
|
||||||
from report detail and developer wiring. Examples are grouped by task with
|
|
||||||
setup, expected results, and intentional failures explained nearby. The consumer
|
|
||||||
guide demonstrates shared report formatting and distinguishes published modules
|
|
||||||
from current source. Help strings and unpublished candidate notes use the same
|
|
||||||
plain language. Exact symbol contracts and runtime behavior were preserved.
|
|
||||||
|
|
||||||
Verification used Go 1.27.0 and existing cached dependencies:
|
|
||||||
|
|
||||||
- The aligned workspace suites passed for core, ckconfig, and ckprompt, including
|
|
||||||
their maintained examples.
|
|
||||||
- Independent core and ckconfig suites passed with `GOWORK=off`.
|
|
||||||
- Independent ckprompt compilation confirmed the existing dependency limitation:
|
|
||||||
released ckconfig v0.4.0 lacks `AdaptDiagnostics`. No module requirements,
|
|
||||||
checksums, or workspace files were changed to hide it. Its README, example,
|
|
||||||
consumer guidance, and candidate note identify the pending alignment.
|
|
||||||
- All 48 `go run` invocations in the three example READMEs were exercised with
|
|
||||||
binaries built from the aligned workspace, from the documented directories.
|
|
||||||
Results matched the walkthroughs, including two failed-load examples, missing
|
|
||||||
request input, and comparison status 3. Shared help and completion behavior
|
|
||||||
also passed the existing suites; representative rendered help was inspected.
|
|
||||||
- Both new consumer-guide report snippets compiled in a temporary consumer using
|
|
||||||
local core. Six checks confirmed greeting counts, empty-list output, and YAML
|
|
||||||
and JSON formatting.
|
|
||||||
- Local Markdown links, including incoming links to renamed sections, and
|
|
||||||
whitespace were checked. Go source changes are limited to help strings,
|
|
||||||
package comments, and formatting; no new tests or validation framework were
|
|
||||||
added.
|
|
||||||
- The authoritative remote had neither the core v0.5.0 nor ckprompt v0.3.0 tag
|
|
||||||
when their candidate notes were revised. Published notes, accepted ADRs,
|
|
||||||
policies, and license/attribution records were left intact.
|
|
||||||
|
|
||||||
The updated ckprompt candidate still requires dependency guidance to be finalized
|
|
||||||
when release alignment occurs. This is release preparation, not unfinished
|
|
||||||
editorial work or evidence of an independently buildable candidate.
|
|
||||||
@@ -1,6 +1,6 @@
|
|||||||
# Future work
|
# Future work
|
||||||
|
|
||||||
Status: pending release/dependency alignment, optional shell validation, and
|
Status: pending ckprompt v0.5.0 publication, optional shell validation, and
|
||||||
future capability proposals.
|
future capability proposals.
|
||||||
No delivery dates are selected here.
|
No delivery dates are selected here.
|
||||||
|
|
||||||
@@ -9,6 +9,7 @@ No delivery dates are selected here.
|
|||||||
Earlier completed roadmaps, implementation plans, and review findings have been retired.
|
Earlier completed roadmaps, implementation plans, and review findings have been retired.
|
||||||
This document preserves unfinished work and unselected ideas under the
|
This document preserves unfinished work and unselected ideas under the
|
||||||
[release policy](../policy/release.md#release-documentation-and-preparation).
|
[release policy](../policy/release.md#release-documentation-and-preparation).
|
||||||
|
The completed [documentation refresh](https://forge.maximumdirect.net/base-layer/commandkit/src/commit/5c960532552037d38119941389e558f78bf73aad/docs/roadmap/documentation-refresh.md) remains available in Git history.
|
||||||
The completed audits, consolidated remediation, implementation plan, and
|
The completed audits, consolidated remediation, implementation plan, and
|
||||||
declaration-path follow-up remain available in the
|
declaration-path follow-up remain available in the
|
||||||
[audit remediation retirement snapshot](https://forge.maximumdirect.net/base-layer/commandkit/src/commit/aac0e11ae67c78a35745ed9a25688aa51c15e793/docs/roadmap).
|
[audit remediation retirement snapshot](https://forge.maximumdirect.net/base-layer/commandkit/src/commit/aac0e11ae67c78a35745ed9a25688aa51c15e793/docs/roadmap).
|
||||||
@@ -30,23 +31,12 @@ an idea here does not select its syntax, API, priority, or delivery date.
|
|||||||
|
|
||||||
## Pending release and integration work
|
## Pending release and integration work
|
||||||
|
|
||||||
### Audit remediation release alignment
|
|
||||||
|
|
||||||
The audit remediation is complete in source. The released ckconfig v0.4.0 does
|
|
||||||
not include `AdaptDiagnostics`, which current ckprompt source uses. Select and
|
|
||||||
publish appropriate releases in dependency order, align module requirements and
|
|
||||||
checksums, and rerun independent module suites under the
|
|
||||||
[release procedure](../release.md). No publication is implied by source completion.
|
|
||||||
|
|
||||||
### ckprompt release
|
### ckprompt release
|
||||||
|
|
||||||
The PromptKit v0.20.0 adoption is complete. The
|
Core and ckconfig v0.5.0 are published. The ckprompt v0.5.0 candidate now selects
|
||||||
[ckprompt v0.3.0 candidate](../../integrations/ckprompt/docs/releases/v0.3.0.md)
|
both releases and replaces the unpublished v0.3.0 draft. Complete validation and
|
||||||
remains unpublished and needs revalidation against the current source and aligned
|
publication using the [release procedure](../release.md). Hosted delivery is a
|
||||||
dependencies. Publication and hosted delivery remain separate operations
|
separate operation.
|
||||||
under the [release procedure](../release.md).
|
|
||||||
The published ckprompt v0.2.0 retains its earlier dependencies; see the
|
|
||||||
[consumer guide](../consumers/guide.md#module-selection) for module selection.
|
|
||||||
|
|
||||||
### Optional shell completion validation
|
### Optional shell completion validation
|
||||||
|
|
||||||
|
|||||||
39
integrations/ckconfig/docs/releases/v0.5.0.md
Normal file
39
integrations/ckconfig/docs/releases/v0.5.0.md
Normal file
@@ -0,0 +1,39 @@
|
|||||||
|
# CommandKit ckconfig v0.5.0
|
||||||
|
|
||||||
|
CommandKit ckconfig v0.5.0 improves configuration explanations, preserves
|
||||||
|
available inspection evidence after loader failures, and uses CommandKit core
|
||||||
|
v0.5.0 for reporting and input handling. ConfigKit remains at v1.1.0, and the
|
||||||
|
consumer minimum remains Go 1.27.0.
|
||||||
|
|
||||||
|
## Changes
|
||||||
|
|
||||||
|
- Configuration explanations render the same acquired evidence in text, YAML,
|
||||||
|
and JSON, including available field metadata, history, and source labels.
|
||||||
|
- Failed loads retain available ConfigKit result evidence for inspection.
|
||||||
|
Cancellation during aggregate configuration display remains an operation
|
||||||
|
failure rather than being reported as a rendering failure.
|
||||||
|
- The new `AdaptDiagnostics` helper captures native ConfigKit diagnostics for
|
||||||
|
CLI presentation. Both standard integrations use the same adapter.
|
||||||
|
- Validation and path discovery avoid rebuilding filter sets and subtree
|
||||||
|
prefixes repeatedly. Scope setup and operation preparation are simpler,
|
||||||
|
preserving independent comparison inputs and existing CLI behavior.
|
||||||
|
|
||||||
|
## Compatibility and upgrade
|
||||||
|
|
||||||
|
Select `go.maximumdirect.net/ckconfig v0.5.0` with CommandKit core v0.5.0.
|
||||||
|
Custom `ExplanationReader` implementations need only `Explain`; the interface
|
||||||
|
no longer requires `WriteExplanation`. CommandKit renders the acquired evidence
|
||||||
|
instead of invoking a provider's text writer. Applications that customized that
|
||||||
|
writer should review their text output.
|
||||||
|
|
||||||
|
Effective configuration writers supply one safe YAML document. Conversion
|
||||||
|
preserves resolved scalar types rather than formatting or comments. Core
|
||||||
|
v0.5.0 preserves numeric-looking strings and explicit numeric tags; review
|
||||||
|
callers that relied on automatic conversion of strings into numbers.
|
||||||
|
|
||||||
|
See the [configuration CLI reference](../../../../docs/cli.md#configuration-scopes)
|
||||||
|
and [consumer guide](../../../../docs/consumers/guide.md#configkit-scopes).
|
||||||
|
|
||||||
|
[COPYRIGHT](https://forge.maximumdirect.net/base-layer/commandkit/src/tag/integrations/ckconfig/v0.5.0/integrations/ckconfig/COPYRIGHT) |
|
||||||
|
[LICENSE](https://forge.maximumdirect.net/base-layer/commandkit/src/tag/integrations/ckconfig/v0.5.0/integrations/ckconfig/LICENSE) |
|
||||||
|
[ATTRIBUTION](https://forge.maximumdirect.net/base-layer/commandkit/src/tag/integrations/ckconfig/v0.5.0/integrations/ckconfig/docs/oss/attribution.md)
|
||||||
@@ -3,7 +3,7 @@ module go.maximumdirect.net/ckconfig
|
|||||||
go 1.27.0
|
go 1.27.0
|
||||||
|
|
||||||
require (
|
require (
|
||||||
go.maximumdirect.net/commandkit v0.4.0
|
go.maximumdirect.net/commandkit v0.5.0
|
||||||
go.maximumdirect.net/configkit v1.1.0
|
go.maximumdirect.net/configkit v1.1.0
|
||||||
go.yaml.in/yaml/v4 v4.0.0-rc.6
|
go.yaml.in/yaml/v4 v4.0.0-rc.6
|
||||||
)
|
)
|
||||||
|
|||||||
@@ -8,6 +8,8 @@ github.com/spf13/pflag v1.0.9 h1:9exaQaMOCwffKiiiYk6/BndUBv+iRViNW+4lEMi0PvY=
|
|||||||
github.com/spf13/pflag v1.0.9/go.mod h1:McXfInJRrz4CZXVZOBLb0bTZqETkiAhM9Iw0y3An2Bg=
|
github.com/spf13/pflag v1.0.9/go.mod h1:McXfInJRrz4CZXVZOBLb0bTZqETkiAhM9Iw0y3An2Bg=
|
||||||
go.maximumdirect.net/commandkit v0.4.0 h1:bWqflDWDn98FUCgh+0e+w6LGmvWIkaeJK519H7PjD2Y=
|
go.maximumdirect.net/commandkit v0.4.0 h1:bWqflDWDn98FUCgh+0e+w6LGmvWIkaeJK519H7PjD2Y=
|
||||||
go.maximumdirect.net/commandkit v0.4.0/go.mod h1:ZS98DewKNVBygKVDoh5MFD09CnPlP37dS9pVsID5Eoc=
|
go.maximumdirect.net/commandkit v0.4.0/go.mod h1:ZS98DewKNVBygKVDoh5MFD09CnPlP37dS9pVsID5Eoc=
|
||||||
|
go.maximumdirect.net/commandkit v0.5.0 h1:Ln+bCp+FwCg4tZD3NaMKQXUDB3mPusgwsnRZmb0+3cM=
|
||||||
|
go.maximumdirect.net/commandkit v0.5.0/go.mod h1:ZS98DewKNVBygKVDoh5MFD09CnPlP37dS9pVsID5Eoc=
|
||||||
go.maximumdirect.net/configkit v1.1.0 h1:UzXN2ZMnEkcL0O4YSLqD9qd9M1gb/NWCHQR/H8AaQzA=
|
go.maximumdirect.net/configkit v1.1.0 h1:UzXN2ZMnEkcL0O4YSLqD9qd9M1gb/NWCHQR/H8AaQzA=
|
||||||
go.maximumdirect.net/configkit v1.1.0/go.mod h1:s1zLJ9GGB/1Q4a+aOHMLISonJxWFgNWpA6SpPlOafeA=
|
go.maximumdirect.net/configkit v1.1.0/go.mod h1:s1zLJ9GGB/1Q4a+aOHMLISonJxWFgNWpA6SpPlOafeA=
|
||||||
go.yaml.in/yaml/v4 v4.0.0-rc.6 h1:1h7H1ohdUh93/FyE4YaDa1Zh64K6VVbjF4K6WUxMtH4=
|
go.yaml.in/yaml/v4 v4.0.0-rc.6 h1:1h7H1ohdUh93/FyE4YaDa1Zh64K6VVbjF4K6WUxMtH4=
|
||||||
|
|||||||
@@ -12,8 +12,7 @@ does not install commands.
|
|||||||
|
|
||||||
The module path is `go.maximumdirect.net/ckprompt`. See the
|
The module path is `go.maximumdirect.net/ckprompt`. See the
|
||||||
[consumer guide](https://forge.maximumdirect.net/base-layer/commandkit/src/branch/main/docs/consumers/guide.md#module-selection)
|
[consumer guide](https://forge.maximumdirect.net/base-layer/commandkit/src/branch/main/docs/consumers/guide.md#module-selection)
|
||||||
for compatible releases, Go requirements, and the current source's dependency
|
for compatible releases and Go requirements.
|
||||||
alignment requirement.
|
|
||||||
|
|
||||||
## Example
|
## Example
|
||||||
|
|
||||||
|
|||||||
@@ -1,8 +1,8 @@
|
|||||||
# CommandKit ckprompt v0.3.0
|
# CommandKit ckprompt v0.5.0
|
||||||
|
|
||||||
This unpublished candidate adds PromptKit v0.20.0 support, including request
|
CommandKit ckprompt v0.5.0 adds PromptKit v0.20.0 support, including request
|
||||||
preview, namespace selection, and shared text, YAML, and JSON output. It uses
|
preview, namespace selection, and shared text, YAML, and JSON output. It requires
|
||||||
ConfigKit v1.1.0 and requires Go 1.27.0.
|
CommandKit core v0.5.0, ckconfig v0.5.0, ConfigKit v1.1.0, and Go 1.27.0.
|
||||||
|
|
||||||
## Operator features
|
## Operator features
|
||||||
|
|
||||||
@@ -20,22 +20,33 @@ let application commands offer the same request flags. `ckprompt.Declarations`
|
|||||||
adds the standard commands with their shorter flag aliases. Literal and file
|
adds the standard commands with their shorter flag aliases. Literal and file
|
||||||
inputs keep their command-line order.
|
inputs keep their command-line order.
|
||||||
|
|
||||||
## Compatibility and preparation
|
## Correctness improvements
|
||||||
|
|
||||||
This candidate changes resource report shapes, input flags, formatting, and
|
Aggregate smoke testing retains cancellation when it stops remaining tests,
|
||||||
configuration comparison behavior. Review the current
|
including previously returned errors and reports. A prepared-request preview
|
||||||
|
fails if the provider returns no prepared request without an error. Parsed
|
||||||
|
provider-parameter objects are copied between independent request destinations,
|
||||||
|
so mutations in one callback do not change later requests. Configuration
|
||||||
|
inspection shares ckconfig's native diagnostic adapter.
|
||||||
|
|
||||||
|
## Compatibility and upgrade
|
||||||
|
|
||||||
|
This pre-1.0 minor release changes resource report shapes, input flags,
|
||||||
|
formatting, and configuration comparison behavior. Review the current
|
||||||
[CLI reference](../../../../docs/cli.md#promptkit-definition-inspection) and
|
[CLI reference](../../../../docs/cli.md#promptkit-definition-inspection) and
|
||||||
[consumer guide](../../../../docs/consumers/guide.md#promptkit-configuration-definitions-and-requirements)
|
[consumer guide](../../../../docs/consumers/guide.md#promptkit-configuration-definitions-and-requirements)
|
||||||
when updating declarations or code that reads reports. Applications continue to
|
when updating declarations or code that reads reports. Applications continue to
|
||||||
own engine construction, credentials, and execution.
|
own engine construction, credentials, and execution.
|
||||||
|
|
||||||
The current source requires `ckconfig.AdaptDiagnostics`, which is absent from
|
Upgrade all three CommandKit modules to v0.5.0 together. This release follows
|
||||||
its selected ckconfig v0.4.0 dependency. Before publication, complete
|
published ckprompt v0.2.0 and adopts the vanity imports
|
||||||
[dependency alignment](../../../../docs/roadmap/future.md#pending-release-and-integration-work)
|
`go.maximumdirect.net/configkit` and `go.maximumdirect.net/promptkit`.
|
||||||
and update this candidate's dependency guidance to the selected releases.
|
Replace earlier upstream import paths consistently; types from different
|
||||||
|
module identities cannot be mixed. Review callers of the former prompt
|
||||||
|
version-report API and use native prompt, profile, and backend inspections.
|
||||||
The [module selection table](../../../../docs/consumers/guide.md#module-selection)
|
The [module selection table](../../../../docs/consumers/guide.md#module-selection)
|
||||||
distinguishes published combinations from the current workspace.
|
records the release dependencies.
|
||||||
|
|
||||||
[COPYRIGHT](https://forge.maximumdirect.net/base-layer/commandkit/src/tag/integrations/ckprompt/v0.3.0/integrations/ckprompt/COPYRIGHT) |
|
[COPYRIGHT](https://forge.maximumdirect.net/base-layer/commandkit/src/tag/integrations/ckprompt/v0.5.0/integrations/ckprompt/COPYRIGHT) |
|
||||||
[LICENSE](https://forge.maximumdirect.net/base-layer/commandkit/src/tag/integrations/ckprompt/v0.3.0/integrations/ckprompt/LICENSE) |
|
[LICENSE](https://forge.maximumdirect.net/base-layer/commandkit/src/tag/integrations/ckprompt/v0.5.0/integrations/ckprompt/LICENSE) |
|
||||||
[ATTRIBUTION](https://forge.maximumdirect.net/base-layer/commandkit/src/tag/integrations/ckprompt/v0.3.0/integrations/ckprompt/docs/oss/attribution.md)
|
[ATTRIBUTION](https://forge.maximumdirect.net/base-layer/commandkit/src/tag/integrations/ckprompt/v0.5.0/integrations/ckprompt/docs/oss/attribution.md)
|
||||||
@@ -4,11 +4,10 @@ This example combines application and PromptKit configuration, resource
|
|||||||
inspection, request checks, and smoke tests. It uses local fixtures and an
|
inspection, request checks, and smoke tests. It uses local fixtures and an
|
||||||
in-memory model client. **No model service or credentials are required.**
|
in-memory model client. **No model service or credentials are required.**
|
||||||
|
|
||||||
Use Go 1.27.0 on `PATH` and an aligned workspace containing all three local
|
Use Go 1.27.0 on `PATH`. An aligned workspace containing all three local modules
|
||||||
modules. Follow the [workspace setup](../../../../docs/development.md#documentation-validation)
|
exercises their current sources; follow the [workspace setup](../../../../docs/development.md#documentation-validation)
|
||||||
from the repository root first. Current ckprompt source needs a helper in local
|
from the repository root. The example also builds independently with
|
||||||
ckconfig source that its released dependency does not yet contain; independent
|
`GOWORK=off` against its module's released dependencies.
|
||||||
builds remain pending [release alignment](../../../../docs/roadmap/future.md#pending-release-and-integration-work).
|
|
||||||
The [consumer guide](../../../../docs/consumers/guide.md#module-selection) owns
|
The [consumer guide](../../../../docs/consumers/guide.md#module-selection) owns
|
||||||
version and compatibility details.
|
version and compatibility details.
|
||||||
|
|
||||||
@@ -168,5 +167,5 @@ for suite composition, builders, and ownership, and the [source](main.go) for
|
|||||||
the complete application.
|
the complete application.
|
||||||
|
|
||||||
Run `GOWORK=auto GOTOOLCHAIN=local go test ./...` from this example directory
|
Run `GOWORK=auto GOTOOLCHAIN=local go test ./...` from this example directory
|
||||||
for an aligned workspace check. Once dependency alignment is complete, also use
|
for an aligned workspace check. Use
|
||||||
`GOWORK=off GOTOOLCHAIN=local go test ./...` to check the declared releases.
|
`GOWORK=off GOTOOLCHAIN=local go test ./...` to check the declared releases.
|
||||||
|
|||||||
@@ -3,8 +3,8 @@ module go.maximumdirect.net/ckprompt
|
|||||||
go 1.27.0
|
go 1.27.0
|
||||||
|
|
||||||
require (
|
require (
|
||||||
go.maximumdirect.net/ckconfig v0.4.0
|
go.maximumdirect.net/ckconfig v0.5.0
|
||||||
go.maximumdirect.net/commandkit v0.4.0
|
go.maximumdirect.net/commandkit v0.5.0
|
||||||
go.maximumdirect.net/configkit v1.1.0
|
go.maximumdirect.net/configkit v1.1.0
|
||||||
go.maximumdirect.net/promptkit v0.20.0
|
go.maximumdirect.net/promptkit v0.20.0
|
||||||
go.yaml.in/yaml/v4 v4.0.0-rc.6
|
go.yaml.in/yaml/v4 v4.0.0-rc.6
|
||||||
|
|||||||
@@ -12,8 +12,12 @@ github.com/spf13/pflag v1.0.9 h1:9exaQaMOCwffKiiiYk6/BndUBv+iRViNW+4lEMi0PvY=
|
|||||||
github.com/spf13/pflag v1.0.9/go.mod h1:McXfInJRrz4CZXVZOBLb0bTZqETkiAhM9Iw0y3An2Bg=
|
github.com/spf13/pflag v1.0.9/go.mod h1:McXfInJRrz4CZXVZOBLb0bTZqETkiAhM9Iw0y3An2Bg=
|
||||||
go.maximumdirect.net/ckconfig v0.4.0 h1:7MpI/jIy+3BZrVME5rhKQibh5U9IA3s97BUJ2EOG41s=
|
go.maximumdirect.net/ckconfig v0.4.0 h1:7MpI/jIy+3BZrVME5rhKQibh5U9IA3s97BUJ2EOG41s=
|
||||||
go.maximumdirect.net/ckconfig v0.4.0/go.mod h1:Mk6QOfHrFy00uE0/gw9h6/Y9LcdTShVEzM/oI/HGDns=
|
go.maximumdirect.net/ckconfig v0.4.0/go.mod h1:Mk6QOfHrFy00uE0/gw9h6/Y9LcdTShVEzM/oI/HGDns=
|
||||||
|
go.maximumdirect.net/ckconfig v0.5.0 h1:5YCPFySTFIFR+gzd0FjqkTPEVB7zkGa8kOEYh4aBvWc=
|
||||||
|
go.maximumdirect.net/ckconfig v0.5.0/go.mod h1:BONXRSQlHdJvYVw9mN6lMV4G4ldlV/5fRO9EEApA99s=
|
||||||
go.maximumdirect.net/commandkit v0.4.0 h1:bWqflDWDn98FUCgh+0e+w6LGmvWIkaeJK519H7PjD2Y=
|
go.maximumdirect.net/commandkit v0.4.0 h1:bWqflDWDn98FUCgh+0e+w6LGmvWIkaeJK519H7PjD2Y=
|
||||||
go.maximumdirect.net/commandkit v0.4.0/go.mod h1:ZS98DewKNVBygKVDoh5MFD09CnPlP37dS9pVsID5Eoc=
|
go.maximumdirect.net/commandkit v0.4.0/go.mod h1:ZS98DewKNVBygKVDoh5MFD09CnPlP37dS9pVsID5Eoc=
|
||||||
|
go.maximumdirect.net/commandkit v0.5.0 h1:Ln+bCp+FwCg4tZD3NaMKQXUDB3mPusgwsnRZmb0+3cM=
|
||||||
|
go.maximumdirect.net/commandkit v0.5.0/go.mod h1:ZS98DewKNVBygKVDoh5MFD09CnPlP37dS9pVsID5Eoc=
|
||||||
go.maximumdirect.net/configkit v1.1.0 h1:UzXN2ZMnEkcL0O4YSLqD9qd9M1gb/NWCHQR/H8AaQzA=
|
go.maximumdirect.net/configkit v1.1.0 h1:UzXN2ZMnEkcL0O4YSLqD9qd9M1gb/NWCHQR/H8AaQzA=
|
||||||
go.maximumdirect.net/configkit v1.1.0/go.mod h1:s1zLJ9GGB/1Q4a+aOHMLISonJxWFgNWpA6SpPlOafeA=
|
go.maximumdirect.net/configkit v1.1.0/go.mod h1:s1zLJ9GGB/1Q4a+aOHMLISonJxWFgNWpA6SpPlOafeA=
|
||||||
go.maximumdirect.net/promptkit v0.20.0 h1:ZpwbjiCZWXdnnZ26RuWKoOco0jFnaAX8m2tQAX7ZlnM=
|
go.maximumdirect.net/promptkit v0.20.0 h1:ZpwbjiCZWXdnnZ26RuWKoOco0jFnaAX8m2tQAX7ZlnM=
|
||||||
|
|||||||
Reference in New Issue
Block a user