Add configuration path explanations

This commit is contained in:
2026-09-26 18:17:57 +00:00
parent 3d7c9aa324
commit 41304e4eea
7 changed files with 131 additions and 6 deletions

View File

@@ -28,6 +28,7 @@ go run ./cmd/scriptorium render \
- `scriptorium config validate`: validate application configuration without building an engine.
- `scriptorium config show`: show the resolved application configuration.
- `scriptorium config sources`: show the ordered configuration sources.
- `scriptorium config explain`: explain one effective or historical configuration path.
All commands accept `--config <path>` and `--config-overlay <name>` and reject
positional arguments. `--config-overlay` selects one application configuration
@@ -226,6 +227,7 @@ controls are shown as zero values when Promptkit leaves them unspecified.
scriptorium config validate [flags]
scriptorium config show [flags]
scriptorium config sources [flags]
scriptorium config explain --path JSON_POINTER [flags]
```
Each accepts `--config`, `--config-overlay`, `--prompt-dir`, `--profile-dir`,
@@ -244,10 +246,21 @@ record has `id`, `label`, and `layer`, plus `path` when available; explicit CLI
overrides appear as synthetic sources. Defaults-only input without overrides
produces `[]` for `sources`.
`explain` requires an explicitly supplied `--path` in JSON Pointer syntax.
The empty string selects the root; `/server/addr` selects a field; `~1` and
`~0` escape `/` and `~` inside mapping keys. Numeric tokens are interpreted
according to the containing mapping or sequence. Dotted paths, file paths,
and URL fragments are not accepted. ConfigKit writes a human-readable account
of the effective value and its chronological default, base, overlay, CLI,
and normalization history, including removed historical values. This is not a
JSON schema or a byte-for-byte stable prose format. Unknown and malformed paths
exit 1 without successful explanation output.
Diagnostics and warnings go to stderr, never into successful stdout. Parse,
load, output, and diagnostic-write failures exit 1. Ordinary output writes may
leave partial data on failure. The inspection output can contain paths,
identifiers, `api_key_env` reference names, and ordinary `extra_params` values;
identifiers, `api_key_env` reference names, and ordinary `extra_params` values,
including displaced historical values in explanations;
protect it accordingly. Raw API-key values are not read or emitted by these
commands.