Add application configuration inspection commands

This commit is contained in:
2026-09-26 18:15:28 +00:00
parent 9ac7006a79
commit 3d7c9aa324
11 changed files with 296 additions and 9 deletions

View File

@@ -25,6 +25,9 @@ go run ./cmd/scriptorium render \
- `scriptorium serve`: start the HTTP server.
- `scriptorium inspect prompt`: inspect one prompt definition without model execution.
- `scriptorium inspect profile`: inspect one effective profile without model execution.
- `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.
All commands accept `--config <path>` and `--config-overlay <name>` and reject
positional arguments. `--config-overlay` selects one application configuration
@@ -217,6 +220,37 @@ resolves profile inheritance and backend defaults, but never reads a credential
value, loads a prompt, reserves capacity, or calls a model. Unset provider
controls are shown as zero values when Promptkit leaves them unspecified.
## Application configuration inspection
```text
scriptorium config validate [flags]
scriptorium config show [flags]
scriptorium config sources [flags]
```
Each accepts `--config`, `--config-overlay`, `--prompt-dir`, `--profile-dir`,
`--schema-dir`, `--addr`, `--artifact-root`, `--max-request-bytes`,
`--max-artifact-bytes`, and `--max-response-bytes`. These are application
configuration selectors and overrides; request, credential, backend-editing,
output-format, and output-file flags are not accepted. Positional arguments
are rejected.
`validate` writes no success output; status 0 means the application configuration
loaded and passed its own validation. It does not establish that a prompt
directory exists, credentials are present, or Promptkit can construct an
engine. `show` writes ConfigKit's resolved, redacted YAML snapshot. `sources`
writes one newline-terminated JSON array of source records in load order. Each
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`.
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;
protect it accordingly. Raw API-key values are not read or emitted by these
commands.
## Input And Variable Syntax
`--input name=path` maps an input name to a local file; `--var name=value`

View File

@@ -95,6 +95,15 @@ The size fields must be zero or greater. The [HTTP API](api.md) defines how
each limit is enforced and reported. `server.artifact_root` configures an HTTP
deployment boundary; see [operations](operations.md) for deployment handling.
The `config validate`, `config show`, and `config sources` commands inspect this
application configuration without creating a Promptkit engine. `show` is a
resolved inspection snapshot, not necessarily a reloadable file. Application
validation does not check framework sources, backend connectivity, or credential
availability. `api_key_env` is an environment-variable *name* and remains
visible in inspection; its environment value is never read by ConfigKit.
Ordinary backend `extra_params` values also remain visible, so keep secrets out
of those fields and protect inspection output as potentially sensitive.
## Custom Backends
Use `backends` when a profile selects an application-defined backend ID:

View File

@@ -17,6 +17,15 @@ Pass required API-key environment variables through the child environment. Do
not place raw API keys in arguments. Keep the environment limited to the values
needed for the selected profile.
For application-only preflight, invoke `scriptorium config validate`; it exits
0 with empty stdout when the application configuration loads, but does not
prove that Promptkit sources or credentials are usable. `config show` emits
resolved YAML and `config sources` emits newline-terminated JSON provenance.
All three use the same source selection and explicit overrides as execution
commands and require separate stderr capture for diagnostics. Their output can
include source paths, identifiers, credential reference names, and ordinary
backend parameters; treat it as potentially sensitive.
## Streams And Output Ownership
Capture stdout and stderr separately. Stdout contains the requested artifact or

View File

@@ -7,9 +7,9 @@ public behavior belongs in the linked contracts.
| Component | Implemented responsibility | References |
| --- | --- | --- |
| `cmd/scriptorium` | Process entrypoint that delegates arguments and streams to the CLI adapter. | [CLI contract](../cli.md), [adapter internals](adapters.md) |
| `internal/adapter/cli` | Parses commands, resolves application settings, constructs Promptkit engines, maps requests, and owns process output and exit behavior. | [CLI contract](../cli.md), [adapter internals](adapters.md) |
| `internal/adapter/cli` | Parses execution and application-configuration inspection commands, resolves settings, constructs Promptkit engines only for execution/definition inspection, maps requests, and owns process output and exit behavior. | [CLI contract](../cli.md), [adapter internals](adapters.md) |
| `internal/adapter/http` | Owns routes, DTOs, strict decoding, limits, Promptkit request/result mapping, public error mapping, and restricted HTTP artifact reading. | [HTTP API](../api.md), [adapter internals](adapters.md), [source internals](sources.md) |
| `internal/config` | Discovers and strictly decodes application configuration and applies built-in and CLI precedence. | [configuration contract](../config.md), [adapter internals](adapters.md) |
| `internal/config` | Selects application sources, supplies the ConfigKit definition and explicit overrides, and converts resolved settings for runtime use. | [configuration contract](../config.md), [adapter internals](adapters.md) |
| `internal/defaults` | Holds Scriptorium-owned application and HTTP defaults. | [configuration contract](../config.md) |
| `internal/format` | Formats Promptkit prepared-run and prompt/profile inspection values for CLI text or JSON output. | [CLI contract](../cli.md), [adapter internals](adapters.md) |
| `internal/report` | Projects one terminal Promptkit observation into Scriptorium-owned execution metadata. | [adapter internals](adapters.md) |

View File

@@ -87,14 +87,22 @@ and apply the same retention and access rules as for model input and output.
Before changing production inputs, profiles, or schemas:
1. confirm the deployed configuration selects the intended sources and model
1. use `config validate`, `config show`, or `config sources` to check the
application configuration and its selected sources without constructing an
engine; this does not verify prompt files, provider access, or credentials;
2. confirm the deployed configuration selects the intended sources and model
credentials;
2. use [`render`](cli.md) with the same request inputs and variables to confirm
3. use [`render`](cli.md) with the same request inputs and variables to confirm
preparation without a model call;
3. use [`run`](cli.md) for generation; and
4. retain or discard validation-failed output according to the caller's
4. use [`run`](cli.md) for generation; and
5. retain or discard validation-failed output according to the caller's
policy.
Inspection output can include configuration paths, names, and ordinary backend
parameters. Apply
access and retention controls; the application stores only API-key environment
reference names, not the resolved credential bytes.
The [maintained render script](../examples/render-markdown-summary.sh) is a
copyable preflight example. The CLI reference owns its complete invocation and
exit semantics.

View File

@@ -320,7 +320,11 @@ new scanning, remote acquisition, or path policy is introduced.
## Stage 5: Add Application Validation, Effective Output, And Source Inspection
**Status: Not started.**
**Status: Complete.** Application-only validation, effective YAML, and ordered
JSON source inspection use one shared ConfigKit result without an engine. Tests
cover source composition, CLI provenance, stream failures, and the credential
reference boundary. Public and internal contracts are updated; full test,
race, vet, build, and diff checks passed.
Primary files: a focused `internal/adapter/cli/config.go`, shared config
definition, CLI dispatch/help/tests, and canonical CLI/config documentation.