Move configuration reports to shared rendering
This commit is contained in:
55
docs/cli.md
55
docs/cli.md
@@ -316,8 +316,8 @@ PromptKit prompt or profile definition commands.
|
||||
`app`; `--scope all` validates every registered scope and is available when each
|
||||
scope declares validation. The command checks all selected capabilities before
|
||||
calling scope providers.
|
||||
Its default format is text; `--format yaml` emits a `scopes` sequence with
|
||||
`name` and `valid: true` for each scope that completed successfully.
|
||||
Automatic output is concise text; structured formats emit a `scopes` sequence
|
||||
with each reached scope and its outcome (`valid`, `failed`, or `canceled`).
|
||||
|
||||
```text
|
||||
example config validate
|
||||
@@ -326,19 +326,21 @@ example config validate --scope all
|
||||
```
|
||||
|
||||
Each successful scope is reported as `SCOPE: valid`. Aggregate validation stops
|
||||
at the first load or output failure; records from earlier successful scopes may
|
||||
already have been written. Provider warnings go to the diagnostic stream and do
|
||||
not alone make validation fail. `--config` and `--overlay` preserve whether an
|
||||
at the first load failure or cancellation, then submits one report containing
|
||||
the reached scopes. Output errors occur after acquisition has stopped. Provider
|
||||
warnings go to the diagnostic stream and do not alone make validation fail.
|
||||
`--config` and `--overlay` preserve whether an
|
||||
empty value was explicitly supplied, so a scope callback can map those inputs to
|
||||
its own ConfigKit load policy. Help and invalid syntax do not call scope
|
||||
providers.
|
||||
|
||||
### Show effective configuration
|
||||
|
||||
`config show` writes the provider's native effective YAML for one scope. Its
|
||||
default scope is `app`; `--format yaml` is accepted and YAML is the only initial
|
||||
format. Single-scope output is passed through unchanged, without a CommandKit
|
||||
header or document marker.
|
||||
`config show` displays the provider's safe effective configuration. The default
|
||||
scope is `app`. The native inspection YAML is converted to a logical report
|
||||
value, preserving meaningful scalar types, empty collections, and redaction.
|
||||
Automatic formatting uses text for a single scalar or nonempty string list and
|
||||
YAML for structured values; `--format` selects text, YAML, or JSON.
|
||||
|
||||
```text
|
||||
example config show
|
||||
@@ -346,24 +348,17 @@ example config show --scope promptkit
|
||||
example config show --scope all
|
||||
```
|
||||
|
||||
`--scope all` acquires every selected scope and checks each effective writer
|
||||
before writing output. It then emits one YAML document per scope in discovery
|
||||
order, with a `# scope: NAME` comment at each document boundary. For ordinary
|
||||
block documents the comment follows the marker. When a native opening marker
|
||||
contains inline content, the comment precedes that marker so it does not
|
||||
interrupt the native value. Existing native markers and leading comments are
|
||||
retained; documents without a marker receive one. Scope labels containing line
|
||||
control characters are quoted to keep them on one comment line. A provider
|
||||
failure leaves the output stream empty. A rendering or output failure may leave
|
||||
an aggregate prefix; `Outcome.Presentation.Output` records incomplete delivery
|
||||
and the destination or rendering error.
|
||||
`--scope all` acquires every selected scope before producing one mapping keyed
|
||||
by scope name, including when only one scope is registered. A single selected
|
||||
scope is unwrapped. A provider failure prevents report output. Conversion or
|
||||
output failures are recorded in `Outcome.Presentation.Output`.
|
||||
|
||||
### List configuration sources
|
||||
|
||||
`config sources` reports the source inventory captured during the selected
|
||||
scope's acquisition. It reads the source facet once and does not reload
|
||||
configuration. The default scope is `app`; `--scope all` is unsupported. Text is
|
||||
the default format, and `--format yaml` returns a structured report:
|
||||
the automatic format, and `--format yaml` or `--format json` returns a structured report:
|
||||
|
||||
```yaml
|
||||
scope: app
|
||||
@@ -415,8 +410,8 @@ for native evidence definitions.
|
||||
|
||||
`config explain --path POINTER` explains the effective and historical value at a
|
||||
JSON Pointer path. `--path` is required; an explicitly empty value selects the
|
||||
root. The default scope is `app`; `--format yaml` selects structured output, and
|
||||
text is the default. `--scope all` is unsupported.
|
||||
root. The default scope is `app`; `--format yaml` or `--format json` selects
|
||||
structured output, and automatic output uses text. `--scope all` is unsupported.
|
||||
|
||||
```text
|
||||
example config explain --path /server/addr
|
||||
@@ -430,7 +425,7 @@ rejected before acquisition. A well-formed path that is unknown in the selected
|
||||
configuration is an operational error with status `1`. Text output comes from
|
||||
the scope's native explanation writer.
|
||||
|
||||
YAML output uses these root fields:
|
||||
Structured output uses these root fields:
|
||||
|
||||
```yaml
|
||||
scope: app
|
||||
@@ -474,8 +469,8 @@ field is omitted, it inherits the corresponding left value and supplied state;
|
||||
an explicit empty string overrides it and remains supplied. Equal selections are
|
||||
allowed; their equality alone does not cause CommandKit to skip the provider.
|
||||
|
||||
YAML is the only format and the default. Explicit `--format yaml` is accepted;
|
||||
`text` and other formats are usage errors. For example:
|
||||
Automatic output is YAML. The shared `--format` also accepts YAML, JSON, and
|
||||
text; text uses the same structured representation. For example:
|
||||
|
||||
```text
|
||||
example config diff --config before.yml --against-config after.yml
|
||||
@@ -487,9 +482,9 @@ example config diff --scope promptkit --config before.yml --against-config after
|
||||
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
|
||||
report contains `additions`, `changes`, and `deletions`. 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.
|
||||
|
||||
@@ -497,7 +492,7 @@ ConfigKit pairs sensitivity across both loads. A concealed change can therefore
|
||||
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
|
||||
changed. Marker-looking public strings stay ordinary strings. An empty
|
||||
comparison succeeds with this shape:
|
||||
|
||||
```yaml
|
||||
|
||||
@@ -114,7 +114,7 @@ static choices or is a filesystem path:
|
||||
|
||||
```go
|
||||
commandkit.FlagMeta{
|
||||
Name: "format",
|
||||
Name: "view",
|
||||
Completion: commandkit.CompleteChoices(
|
||||
commandkit.CompletionChoice{Value: "text", Description: "Readable text"},
|
||||
commandkit.CompletionChoice{Value: "yaml", Description: "YAML output"},
|
||||
@@ -246,7 +246,7 @@ timing, omitted-factory zero values (including nil pointers), and ownership.
|
||||
The application owns the state type and what it caches. `ckconfig.FromConfigKit`
|
||||
adapts a typed ConfigKit loader without calling it during construction.
|
||||
|
||||
The `config` family provides scope discovery, validation, native effective YAML,
|
||||
The `config` family provides scope discovery, validation, safe effective configuration display,
|
||||
source inventory, path explanation, and ConfigKit-backed comparison for the
|
||||
capabilities declared by its scopes. The [CLI reference](../cli.md#configuration-scopes)
|
||||
owns operator syntax and report details.
|
||||
|
||||
@@ -63,8 +63,8 @@ implemented:
|
||||
- Help and command discovery without provider loading or runtime construction.
|
||||
- Provider failures, cancellation, output errors, and preservation of application
|
||||
outcomes and public error identity.
|
||||
- Selected inspection/report contracts, including native YAML and document order
|
||||
for `config show --scope all`.
|
||||
- Selected inspection/report contracts, including safe scalar preservation and
|
||||
scope-keyed aggregation for `config show --scope all`.
|
||||
- Public type ownership and the internal Cobra/pflag import boundary selected by
|
||||
[ADR 0002](../adr/0002-public-facade-and-cli-backend.md).
|
||||
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# Shared reporting and PromptKit v0.20.0 implementation plan
|
||||
|
||||
Status: implementation in progress; Stages 1–6 complete.
|
||||
Status: implementation in progress; Stages 1–7 complete.
|
||||
|
||||
## Scope, authority, and execution
|
||||
|
||||
@@ -250,6 +250,12 @@ ordinary `RepeatFlag` replacement semantics to simulate ordering.
|
||||
|
||||
## Stage 7: Migrate existing ckconfig reports to core
|
||||
|
||||
**Complete.** Existing ckconfig reports use shared rendering, including safe
|
||||
effective values and reached-scope validation aggregation. Focused integration
|
||||
tests and the root and ckconfig workspace suites passed with Go 1.27.0 using
|
||||
`GOTOOLCHAIN=local go test ./... ./integrations/ckconfig/...`. The ckprompt
|
||||
migration remains in the following stages.
|
||||
|
||||
Convert the existing `scopes`, `show`, `sources`, `explain`, `diff`, and concise
|
||||
`validate` report paths in [ckconfig](../../integrations/ckconfig) to the public
|
||||
handoff. Remove local format flags, validators, encoding switches, and encoders.
|
||||
|
||||
Reference in New Issue
Block a user