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
|
||||
|
||||
Reference in New Issue
Block a user