base-layer/commandkit
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity

Add configuration path discovery

Browse Source
This commit is contained in:
Eric Rakestraw
2026-11-07 04:44:01 +00:00
parent aeb70e5873
commit b38130548e
8 changed files with 307 additions and 20 deletions
Download Patch File Download Diff File Expand all files Collapse all files

19
docs/cli.md
View File

@@ -421,21 +421,32 @@ for native evidence definitions.
### Explain a configuration path
`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` or `--format json` selects
JSON Pointer path. An explicitly empty path selects the root. `config explain
--list` discovers paths when the selected scope supports path discovery. An
invocation with neither mode displays help; the two modes cannot be combined.
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
example config explain --path /profiles/team~1summary --format yaml
example config explain --path= --format yaml
example config explain --list --under /profiles --historical
```
Listing normally includes current paths. `--historical` adds paths that only
occurred in history; `--under POINTER` selects a subtree, and `--explicit=true`
or `--explicit=false` filters current paths by native explicitness. Historical-only
paths do not match an explicitness filter. These options require `--list`.
The report contains the scope and each selected path's current presence and,
when present, its explicitness. Path discovery does not include values or history.
Pointer tokens use JSON Pointer escaping: `~1` represents `/` and `~0`
represents `~`. A malformed pointer is a usage error with status `2` and is
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.
configuration is an operational error with status `1`. Text output includes
the scope's native explanation and available field metadata. Structured output
includes metadata when supplied by the scope.
Structured output uses these root fields:

8
docs/roadmap/implementation.md
View File

@@ -1,6 +1,6 @@
# Shared reporting and PromptKit v0.20.0 implementation plan
Status: implementation in progress; Stages 1–16 complete.
Status: implementation in progress; Stages 1–17 complete.
## Scope, authority, and execution
@@ -610,6 +610,12 @@ algorithms remain upstream tests.
## Stage 17: Explanation discovery and metadata
**Complete.** Explain supports discovery filters and field metadata, with
mode and capability checks before acquisition. `Invocation.Help` renders the
selected command's existing help when no mode is selected, avoiding application
factories. Root, ckconfig, and ckprompt workspace suites passed with Go 1.27.0,
including historical paths, escaped subtrees, and help delivery.
Extend `config explain` under [OD-4](promptkit-v0.20.0.md#od-4-configuration-path-and-metadata-presentation).
Track supplied `--path` separately from its value; root `--path ''` is an
operation. Bare invocation shows successful command help before input/state