Add application configuration inspection commands
This commit is contained in:
34
docs/cli.md
34
docs/cli.md
@@ -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`
|
||||
|
||||
@@ -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:
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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) |
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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.
|
||||
|
||||
Reference in New Issue
Block a user