97 Commits

Author SHA1 Message Date
b47cb35966 Remove completed CommandKit roadmap documents
All checks were successful
ci/woodpecker/push/verify Pipeline was successful
2026-11-20 15:29:55 +00:00
39b4bddbc9 Use native configuration validation and diagnostics 2026-11-20 15:22:57 +00:00
7e45ffca43 Classify invalid artifact relations as input errors 2026-11-20 13:48:55 +00:00
672b7f0ebd Use canonical source identities in publication reports 2026-11-20 13:45:17 +00:00
f44078724a Build publication report indexes once 2026-11-20 13:44:09 +00:00
af6cf8b6f1 Look up family identities without copying catalogs 2026-11-20 13:43:18 +00:00
7e65c29a61 Share provenance snapshots during catalog derivation 2026-11-20 13:42:11 +00:00
846f8470dc Keep source provenance out of prepare reuse decisions 2026-11-20 13:40:55 +00:00
32ff928786 Clarify optional spell catalog clearing 2026-11-20 13:39:20 +00:00
25c59ff62f Preserve campaign defaults in materialized sessions 2026-11-20 13:38:21 +00:00
38866110a7 Record CommandKit algorithm audit findings 2026-11-20 13:12:32 +00:00
65d24fb88f Record the party selection resume integration gap 2026-11-20 13:02:23 +00:00
8be65fd3a1 Record CommandKit migration review findings 2026-11-20 12:54:56 +00:00
0117f3f35d Verify native workflows and explain identity mismatches 2026-11-20 06:50:56 +00:00
0e9cbc9c2a Document the native CLI and migration workflows 2026-11-20 06:41:59 +00:00
faa8cb5822 Finish native completion and retire legacy command machinery 2026-11-20 06:32:47 +00:00
7db626781e Report audio, speaker, and artifact work progress 2026-11-20 06:04:34 +00:00
c523def852 Route console diagnostics and stage progress through native reporting 2026-11-20 05:59:09 +00:00
c7a5ff316d Propagate cancellation and preserve resumable state 2026-11-20 05:53:49 +00:00
a6c6f1e4ab Preserve partial run results and terminal failure causes 2026-11-20 05:47:41 +00:00
85df36a770 Add native restore and session cleanup commands 2026-11-20 05:41:16 +00:00
6b7a0847d4 Add native session initialization and remote lock commands 2026-11-20 05:29:27 +00:00
e44247b5b1 Report structured session validation and inspection results 2026-11-20 05:23:32 +00:00
97cced5d88 Expose native session planning and artifact catalogs 2026-11-20 05:15:43 +00:00
0238f82847 Install native run and artifact regeneration commands 2026-11-20 05:10:04 +00:00
ed29bdc473 Support independent native configuration comparisons and overrides 2026-11-20 05:06:26 +00:00
c3c6849bed Expose native configuration inspection scopes 2026-11-20 05:02:46 +00:00
1e67c429b7 Share lazy configuration and session acquisition 2026-11-20 04:54:12 +00:00
b537cb38ae Preserve derived publication and preparation evidence 2026-11-20 04:49:29 +00:00
065a615e5f Use derived artifact catalogs throughout planning and execution 2026-11-20 04:42:23 +00:00
6900cad104 Derive artifact catalogs from the selected party without changing configuration 2026-11-20 04:33:02 +00:00
c3e6245416 Complete session defaults within the ConfigKit lifecycle 2026-11-20 04:24:20 +00:00
16a4f7ee12 Retain authoritative pipeline and campaign load results 2026-11-20 04:17:29 +00:00
a3c58141a0 Adopt the native CommandKit application boundary 2026-11-20 04:13:05 +00:00
86692d58f9 Plan the CommandKit adoption sprint 2026-11-20 04:05:11 +00:00
bcbfc0fa4a Clarify progress and verbose reporting in the CommandKit roadmap 2026-11-20 03:46:30 +00:00
e476c08ea4 Consolidate the CommandKit adoption roadmap 2026-11-20 02:17:59 +00:00
8824ce330f Defer execution overrides to a reusable CommandKit binding 2026-11-20 01:17:56 +00:00
87142508e3 Record artifacts command family and pending override binding 2026-11-20 01:09:33 +00:00
7cc877ea7f Align configuration ownership policy with ADR 0003
All checks were successful
ci/woodpecker/push/verify Pipeline was successful
2026-11-20 00:46:06 +00:00
7ee362f1c3 Clarify configuration ownership and native inspection boundaries 2026-11-20 00:16:42 +00:00
084e6d178b Simplify CommandKit overrides and add party file selection 2026-11-19 18:53:26 +00:00
86ec48d2e4 Record delivery decisions and end-to-end sprint guidance 2026-11-19 18:16:43 +00:00
3868822277 Record diagnostics and invocation lifecycle decisions 2026-11-19 18:09:17 +00:00
d83c5f0062 Record agreed CommandKit reporting decisions 2026-11-19 17:50:25 +00:00
981eb6be8f Record native configuration override decisions 2026-11-19 16:24:52 +00:00
6b027873a5 Record session acquisition and selector decisions 2026-11-19 16:15:25 +00:00
d00cc8037d Record agreed configuration scopes and inspection views 2026-11-19 16:12:21 +00:00
b4b618a913 Record agreed CommandKit command organization 2026-11-19 16:01:02 +00:00
8ba001750e Record CommandKit migration direction and open decisions 2026-11-19 15:54:26 +00:00
fa9ed78a6d Remove completed ConfigKit planning documents
All checks were successful
ci/woodpecker/push/verify Pipeline was successful
2026-11-18 14:33:12 +00:00
4dae8e0d36 Stream verified prepared inputs into publication archives 2026-11-18 04:17:37 +00:00
35eaefd05d Read selected remote sessions directly without listing run history 2026-11-18 04:12:56 +00:00
f85f93bdfb Reuse party provenance within each inspection 2026-11-18 04:10:29 +00:00
0e34ea1d48 Reuse native source records and catalog source indexes 2026-11-18 04:09:24 +00:00
97a93d3393 Honor remote session authoring updates after publication 2026-11-18 04:08:43 +00:00
435ec79185 Initialize standalone sessions from native local authoring context 2026-11-18 04:06:29 +00:00
33d2ebf44c Pin Go attribution to the released source commit 2026-11-18 04:03:40 +00:00
e93fb8d5ab Record publish defaults and destinations at field level 2026-11-18 04:03:33 +00:00
69dc5cc8ec Make restore lock contention coverage independent of startup timing 2026-11-18 04:02:30 +00:00
5d62f9a88b Report effective resource contributors without superseded definitions 2026-11-18 03:59:09 +00:00
ba9079ee74 Record algorithmic refactoring opportunities 2026-11-18 01:10:44 +00:00
583c5bdf1b Record configuration integration audit findings 2026-11-18 00:30:09 +00:00
bccf03a99f Record ConfigKit migration review findings 2026-11-17 23:57:45 +00:00
39a958675d Verify native configuration workflows end to end 2026-11-17 22:49:22 +00:00
413b0d7134 Align configuration documentation with native loading 2026-11-17 22:42:53 +00:00
ff4bdaa483 Demonstrate native configuration authoring 2026-11-17 22:38:51 +00:00
ebcc5b32a0 Use native configuration diff and source evidence 2026-11-17 22:35:56 +00:00
ce661252d0 Render final configuration through native snapshots 2026-11-17 22:31:03 +00:00
ed7e722077 Publish and restore prepared session documents 2026-11-17 22:27:24 +00:00
bcfca7a044 Materialize effective campaign and session inputs 2026-11-17 22:21:55 +00:00
05f5607968 Render imported party rosters as canonical inputs 2026-11-17 22:18:57 +00:00
1657c9f65d Load campaign and session imports from their sources 2026-11-17 22:15:05 +00:00
c3023cb609 Resolve pipeline resources from their source locations 2026-11-17 22:09:58 +00:00
6593ccbeaf Use native pipeline discovery and independent secrets bootstrap 2026-11-17 22:06:29 +00:00
341fe93e3b Adopt ConfigKit and Go toolchain baseline 2026-11-17 21:59:19 +00:00
65d0e518e5 Plan the native ConfigKit migration 2026-11-17 20:41:34 +00:00
4a0e3c83db Record the agreed ConfigKit adoption decisions 2026-11-17 20:27:47 +00:00
f5451a0cf5 Outline native ConfigKit adoption and configuration ergonomics 2026-11-17 20:23:22 +00:00
381668568f Adopt the updated standard repository policies 2026-11-17 19:56:32 +00:00
8afb49c018 Record the ConfigKit configuration ownership boundary 2026-10-05 14:03:51 +00:00
535f47ef20 Cover inherited Notarius path resolution 2026-10-04 15:35:45 +00:00
dcb9bae215 Verify inherited configuration inspection commands 2026-10-04 15:33:16 +00:00
f1f71d8cdf Document native configuration inheritance 2026-10-04 15:25:48 +00:00
39af6ef941 Verify inherited credential safety 2026-10-04 14:41:34 +00:00
e1c934a492 Assert credential-safe projections survive rotation 2026-10-04 14:02:43 +00:00
dd760d84e0 Compare inherited effective pipeline values 2026-10-04 14:00:55 +00:00
6db49b3949 Verify inherited configuration semantics 2026-10-04 13:49:42 +00:00
f1672f6f95 Preserve composite ConfigKit provenance 2026-10-04 13:34:27 +00:00
428f435734 Accept composed ConfigKit artifact definitions 2026-10-04 13:10:53 +00:00
c4abdc19df Upgrade ConfigKit to v0.5.0 2026-10-04 12:53:29 +00:00
08327c2e63 Add documentation style guidance to the plan 2026-10-04 12:49:08 +00:00
2850498043 Simplify the ConfigKit adoption plan 2026-10-04 12:42:58 +00:00
fe9817f354 Plan the ConfigKit upgrade and workspace development 2026-10-04 12:28:09 +00:00
40cbf42438 Document Narratio v3.1.0 release
All checks were successful
ci/woodpecker/push/verify Pipeline was successful
ci/woodpecker/tag/release Pipeline was successful
2026-09-29 18:02:18 +00:00
44a318694b Forward Scriptorium credentials through the shared adapter path 2026-09-29 17:50:30 +00:00
9389f69eb0 Report missing Scriptorium credential forwarding 2026-09-29 17:40:35 +00:00
289 changed files with 12578 additions and 9001 deletions

View File

@@ -3,12 +3,12 @@ when:
steps: steps:
validate-release: validate-release:
image: golang:1.26.7 image: golang:1.27.4
commands: commands:
- ./scripts/check-release-candidate.sh "$CI_COMMIT_TAG" - ./scripts/check-release-candidate.sh "$CI_COMMIT_TAG"
build-release-assets: build-release-assets:
image: golang:1.26.7 image: golang:1.27.4
depends_on: depends_on:
- validate-release - validate-release
commands: commands:

View File

@@ -3,6 +3,6 @@ when:
steps: steps:
shuffled-race-tests: shuffled-race-tests:
image: golang:1.26 image: golang:1.27.4
commands: commands:
- go test -race -shuffle=on -count=3 ./... - go test -race -shuffle=on -count=3 ./...

View File

@@ -3,30 +3,30 @@ when:
steps: steps:
tests: tests:
image: golang:1.26 image: golang:1.27.4
commands: commands:
- go test ./... - go test ./...
race-tests: race-tests:
image: golang:1.26 image: golang:1.27.4
depends_on: tests depends_on: tests
commands: commands:
- go test -race ./... - go test -race ./...
static-analysis: static-analysis:
image: golang:1.26 image: golang:1.27.4
depends_on: tests depends_on: tests
commands: commands:
- go vet ./... - go vet ./...
build: build:
image: golang:1.26 image: golang:1.27.4
depends_on: tests depends_on: tests
commands: commands:
- go build ./... - go build ./...
cross-build: cross-build:
image: golang:1.26 image: golang:1.27.4
depends_on: [race-tests, static-analysis, build] depends_on: [race-tests, static-analysis, build]
commands: commands:
- | - |

View File

@@ -5,7 +5,8 @@ polished transcripts, validated Notarius extraction lanes, and generated
artifacts. artifacts.
It runs a deterministic workflow with manifest-driven continuation, remote It runs a deterministic workflow with manifest-driven continuation, remote
publish, and restore support. publish, and restore support. Its CommandKit CLI provides native configuration
inspection, structured operation reports, progress, and shell completion.
```sh ```sh
narratio run 2026-04-04 narratio run 2026-04-04

View File

@@ -1,11 +1,22 @@
package main package main
import ( import (
"context"
"os" "os"
"os/signal"
"syscall"
"go.maximumdirect.net/commandkit"
"gitea.maximumdirect.net/eric/narratio/internal/app" "gitea.maximumdirect.net/eric/narratio/internal/app"
) )
func main() { func main() {
os.Exit(app.Execute(os.Args[1:], os.Stdout, os.Stderr)) os.Exit(runProcess(os.Args[1:], commandkit.Streams{Out: os.Stdout, Err: os.Stderr}, app.Execute))
}
func runProcess(args []string, streams commandkit.Streams, execute func(context.Context, []string, commandkit.Streams) commandkit.Outcome) int {
ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
defer stop()
return execute(ctx, args, streams).Status
} }

56
cmd/narratio/main_test.go Normal file
View File

@@ -0,0 +1,56 @@
package main
import (
"bufio"
"context"
"fmt"
"os"
"os/exec"
"syscall"
"testing"
"time"
"go.maximumdirect.net/commandkit"
)
func TestProcessSignalsCancelInvocation(t *testing.T) {
if os.Getenv("NARRATIO_TEST_SIGNAL_CHILD") == "1" {
os.Exit(runProcess(nil, commandkit.Streams{Out: os.Stdout, Err: os.Stderr}, func(ctx context.Context, _ []string, streams commandkit.Streams) commandkit.Outcome {
fmt.Fprintln(streams.Out, "ready")
<-ctx.Done()
return commandkit.Failure("interrupted").WithCause(ctx.Err())
}))
}
for _, sig := range []os.Signal{os.Interrupt, syscall.SIGTERM} {
t.Run(sig.String(), func(t *testing.T) {
ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
defer cancel()
child := exec.CommandContext(ctx, os.Args[0], "-test.run=^TestProcessSignalsCancelInvocation$")
child.Env = append(os.Environ(), "NARRATIO_TEST_SIGNAL_CHILD=1")
out, err := child.StdoutPipe()
if err != nil {
t.Fatal(err)
}
child.Stderr = os.Stderr
if err := child.Start(); err != nil {
t.Fatal(err)
}
scanner := bufio.NewScanner(out)
if !scanner.Scan() || scanner.Text() != "ready" {
_ = child.Process.Kill()
_ = child.Wait()
t.Fatal("child failed to register its signal context")
}
if err := child.Process.Signal(sig); err != nil {
_ = child.Process.Kill()
_ = child.Wait()
t.Fatal(err)
}
err = child.Wait()
exit, ok := err.(*exec.ExitError)
if !ok || exit.ExitCode() != 1 {
t.Fatalf("child result=%v, want operational exit 1", err)
}
})
}
}

View File

@@ -0,0 +1,84 @@
# 0001. Classify session content by purpose and lifecycle
## Status
Proposed
## Date
2026-10-01
## Context
Narratio coordinates applications that produce transcripts, artifacts,
diagnostics, and working files. The current session layout mixes some of these
roles, including complete Notarius bundles under `artifacts/`. Operators use
transcripts and artifacts to evaluate results during development and need
predictable locations for diagnostics.
A shared classification model will guide the workspace design and subsequent
adapter changes. The [operator guide](../operations.md#local-state-layout)
describes the implemented layout.
## Decision
Classify content by its primary purpose and lifecycle:
| Category | Purpose |
| --- | --- |
| Inputs | Material consumed by an application, including audio, configuration, and reference documents. |
| Outputs | Completed substantive products, including intermediate artifacts exposed for further use. |
| Logs | Records of execution, including process logs, execution reports, warnings, and diagnostic summaries. |
| Cache | Reusable information whose absence permits ordinary recomputation or retrieval. |
| State | Application condition, progress, recovery records, and unfinished work. |
Classification is relative to the consuming application. An output of one stage
can serve as an input to another while retaining its output location. Completed
outputs reused to skip work remain Outputs. Narratio's manifest is State and
records whether those outputs are reusable.
Classify checkpoints according to their recovery behavior. A checkpoint needed
to continue a particular interrupted operation is State. A saved work result
that can be reused or recomputed is Cache. Recomputation cost informs retention
policy. File-specific classification remains necessary for stores serving both
purposes.
Treat Debug as a capture and retention mode that can include detailed Logs,
snapshots of State, and other diagnostic evidence. Retained debug snapshots have
a diagnostic role; live recovery records retain their State role.
Apply these directory principles to Narratio:
- Store completed artifacts, including intermediate artifacts like
`session_bounds.json`, directly in a flat `artifacts/` directory.
- Store combined transcripts directly in `transcripts/`, with a subdirectory
for the initial per-speaker transcripts.
- Store prepared external audio in `audio/` and other prepared external inputs
in `inputs/`.
- Organize Logs under `logs/` by stage. Execution reports belong to this category.
- Organize Cache under a cache root by the application that owns its format and
reuse behavior.
- Treat scratch files and unfinished outputs as State until completion permits
promotion to Outputs.
## Alternatives Considered
- Group outputs by producer. This exposes subprocess packaging to operators;
flat artifact and transcript locations better support comparison and review.
- Group Logs by application. Stage names match the operator's workflow and
collect diagnostics from stages that invoke multiple applications.
- Classify all checkpoints as State. Recovery behavior provides a more useful
distinction for eviction and reuse decisions.
- Treat all Debug material as Logs. A separate debug location can accommodate
retained state snapshots and larger diagnostic bundles when needed.
## Consequences
Each managed file family needs an identified role, owner, scope, and retention
rule. Subprocess bundles require classification before their contents are
placed in Narratio's output and diagnostic directories.
Physical roots, retention rules, the mechanism for presenting latest logs,
debug placement, and ambiguous checkpoint classifications remain open. The file
inventory and subsequent roadmap will resolve these choices and define the
migration. Current versus historical views are separate from content categories.

View File

@@ -0,0 +1,76 @@
# 0002. Assign subprocess content ownership
## Status
Proposed
## Date
2026-10-03
## Context
[ADR 0001](0001-classify-session-content.md) defines content categories and
operator-facing directory principles. Narratio also needs an ownership boundary
for the applications it invokes. That boundary determines who selects locations,
manages retained files, and controls cleanup.
The current subprocess workflows can execute with fresh working state. Notarius
can reuse persistent chunk-plan and checkpoint caches. Narratio maintains its own
session progress and recovery records.
## Decision
Assign responsibility by content category:
| Category | Responsibility |
| --- | --- |
| Inputs | Narratio supplies paths to prepared inputs, transcripts, and artifacts. |
| Outputs | Narratio selects destinations and promotes completed products into the output locations defined by ADR 0001. |
| Logs | Narratio selects stage-based destinations and captures subprocess output streams. |
| Debug | Narratio selects the destination when capture is enabled; the subprocess defines the diagnostic contents. |
| Subprocess State | Each application manages its working directory, temporary files, and execution lifecycle through its own configuration and defaults. |
| Subprocess Cache | Each application manages its configured persistent cache, including its format, identity, and reuse behavior. |
Narratio retains ownership of its own State, including the session manifest,
recovery bookkeeping, and staging files it manages.
Recommend a dedicated cache root for each cache-aware application, configurable
through that application's supported controls. For system-wide deployments,
`/var/cache/<application>` is a suggested location; `/var/cache/notarius` is an
example for Notarius. Each application defines its cache configuration, defaults,
and internal layout. Operators select locations and retention settings through
those controls. Narratio's session cleanup leaves subprocess caches under their
separate lifecycle policies.
Subprocesses retain ownership of their file formats and bundle structures.
Narratio can receive a complete result bundle at a selected staging destination
and promote the selected products into its canonical output directories.
Diagnostic snapshots of subprocess State follow the Debug destination selected
by Narratio.
Narratio's `runs/` directory can hold staging outputs and retained execution
evidence. Subprocess working directories follow the application's configuration
and may reside elsewhere. Narratio cleanup manages Narratio-owned material;
subprocess State and Cache follow their separate lifecycle policies.
## Alternatives Considered
- Place all subprocess working files and caches inside each Narratio session.
This makes sessions easier to collect as a unit, but couples application
internals and cache retention to Narratio's session lifecycle.
- Allow subprocesses to choose output, log, and debug destinations independently.
This simplifies invocation but scatters the material operators inspect.
- Give Narratio control of downstream bundle formats. This simplifies some
destination mappings but increases integration coupling. Selecting and
promoting products preserves application ownership of those formats.
## Consequences
Adapters need supported controls for Narratio-selected output, log, and debug
locations. Upstream changes may be needed where those destinations are coupled
to application working directories or to one another.
Workspace layout and file classification can proceed independently of subprocess
working-directory conventions. Exact debug placement, retained diagnostic views,
and migration steps remain for the workspace design and roadmap.

View File

@@ -0,0 +1,38 @@
# 0003. Assign configuration ownership
## Status
Accepted
## Date
2026-11-19
## Context
Configuration loading, inspection, and domain execution need explicit ownership
so that effective configuration has one authority.
## Decision
- **ConfigKit owns configuration policy and resolution through the final
handoff.** Narratio supplies its schema, defaults, and configuration rules
through ConfigKit's supported extension points. The completed ConfigKit
result is authoritative.
- **Narratio owns domain interpretation and execution.** It consumes the
completed configuration without mutation and produces separate domain
objects. It must not construct a replacement effective configuration.
- **CommandKit owns CLI mechanics and presentation; `ckconfig` exposes
ConfigKit's inspection features.** Narratio supplies selection and acquisition
wiring and exposes those features through native adapters, without altering
their semantics or substituting its own inspection views.
## Alternatives Considered
Post-handoff configuration resolution and custom inspection projections are
rejected because they create competing configuration authorities.
## Consequences
Domain catalogs and plans remain separate from native configuration inspection.
Missing configuration or inspection capabilities are addressed upstream.

View File

@@ -1,485 +1,449 @@
# CLI Reference # CLI Reference
## Shortest Useful Command ## Command tree
```bash
narratio run 2026-04-04
```
This runs the canonical full pipeline for session `2026-04-04`.
## Command Overview
Top-level commands:
- `version`: print the Narratio build version.
- `run <session_id>`: run all or one contiguous range of the canonical stage order.
- `regenerate-artifacts <session_id>`: force-run extraction through analysis.
- `run-stage <stage> <session_id>`: run one stage.
- `analyze <session_id>`: force-run analyze.
- `publish <session_id>`: force-run publish.
- `clean <session_id>` or `clean --all`: remove local work/spool state.
- `session <subcommand>`: session helper commands.
- `config <subcommand>`: validate, display, source-trace, catalog, or compare resolved pipeline configuration.
Session subcommands:
- `session init <session_id>`
- `session plan <session_id>`
- `session validate <session_id>`
- `session status <session_id>`
- `session restore <session_id>`
- `session artifacts <session_id>`
- `session locks <session_id>`
- `session locks add <session_id> <source>`
- `session locks remove <session_id> <source>`
## Common Config Flags
Most session-aware commands accept:
- `--config <pipeline.yml>`
- `--campaign <id>`
- `--campaign-file <campaign.yml>`
- `--session <session.yml>`
- `--session-id <session_id>`
- `--previous-session-id <session_id>`
- `--overlay <name>`
- `--secrets-dir <directory>`
Rules:
- `--campaign` and `--campaign-file` are mutually exclusive.
- `--session` is not used by `session init`.
- if both positional `<session_id>` and `--session-id` are provided, values must match.
- `--previous-session-id` is a strict expectation: the selected session file
must contain the same `previous_session_id`.
- `--overlay` selects `overlays/<name>.yml` relative to the pipeline root. It
may be supplied once; omitted, empty, and the exact name `default` select the
base configuration, while an unknown named overlay fails. The same selection
applies to all common-flag commands, including `regenerate-artifacts`.
- `--secrets-dir` selects ConfigKit credential-file bootstrap explicitly. A
relative value uses caller CWD. Without the flag, a present `secrets/`
directory beside the resolved root pipeline is used; an absent one is skipped.
- `clean --all` cannot be combined with campaign/session selectors.
- notification delivery is currently limited to the configured `noop` mode; see
the [configuration reference](./config.md#notifications).
## Session ID Input Rules
Session-aware commands accept one of these forms:
- positional session ID: `... <session_id>`
- compatibility flag: `... --session-id <session_id>`
When both are present, command parsing requires an exact match.
Commands with additional positionals keep their command-specific order:
- `run-stage <stage> <session_id>` or `run-stage <stage> --session-id <session_id>`
- `session locks add <session_id> <source>` or `session locks add --session-id <session_id> <source>`
- `session locks remove <session_id> <source>` or `session locks remove --session-id <session_id> <source>`
## Command Reference
### `config validate`, `config show`, `config sources`, `config artifacts`, and `config diff`
```bash
narratio config validate [--config <pipeline.yml>] [--campaign <id> | --campaign-file <campaign.yml>] [--overlay <name>] [--secrets-dir <directory>]
narratio config show [--config <pipeline.yml>] [--campaign <id> | --campaign-file <campaign.yml>] [--overlay <name>] [--secrets-dir <directory>]
narratio config sources [--config <pipeline.yml>] [--campaign <id> | --campaign-file <campaign.yml>] [--overlay <name>] [--secrets-dir <directory>]
narratio config artifacts [--config <pipeline.yml>] [--campaign <id> | --campaign-file <campaign.yml>] [--overlay <name>] [--secrets-dir <directory>]
narratio config diff <left-overlay> <right-overlay> [--config <pipeline.yml>] [--campaign <id> | --campaign-file <campaign.yml>] [--secrets-dir <directory>]
```
These commands resolve the selected overlay, defaults, ordinary paths, and—if
a campaign is selected—the campaign-owned party. They neither discover or load
a session nor create a workspace, manifest, run, lock, adapter, or remote
connection. Like every pipeline-loading command, they bootstrap the selected or
conventional secrets directory before resolving configuration; `config show`
never includes bootstrap reports or secret values in its YAML output.
Typed credential references, including `notarius.credentials[]`, must therefore
resolve even though these inspection commands never construct an adapter.
Campaign selection is optional for a pipeline without party-driven artifact
families. A pipeline with `scriptorium.artifact_families` needs a selected or
configured default campaign so Narratio can expand its concrete artifacts and
publish rules. `--campaign` and `--campaign-file` remain mutually exclusive.
Session, range, force, and artifact-execution flags are not accepted.
`config validate` writes a concise root-path, selected-overlay (or `none`), and
effective-digest summary after successful complete validation. `config show`
writes one deterministic, secret-free YAML document containing defaulted and
expanded concrete configuration. It omits ConfigKit directives, artifact
family declarations, and runtime provenance.
`config sources` reports the same fully validated resolution without printing
effective values. Its header identifies the root, ordered imports, selected
overlay and its file, selected campaign, party source, and digest. The
remaining tab-separated records are sorted as `path`, `role`, and `source`.
Roles distinguish root, import, overlay, centralized default, campaign, party,
and generated family ownership. A generated party member has
one family record and one party record at the same logical path. The output
never reads or prints secret values.
`config artifacts` prints the concrete catalog used by analysis, ordered by
artifact key. Its tab-separated header is `key`, `source`, `definitions`,
`enabled`, `output`, `dependencies`, `family`, `character`, `family_source`, and
`party_source`. Definitions and effective dependencies are sorted comma-separated
lists, and control characters in fields are escaped. Family-member rows identify
their family, character, defining family file, and party file. An empty catalog
prints only the header. Ordinary artifacts can be inspected without a campaign;
party-driven families retain the campaign requirement. See
[Scriptorium Artifact Entries](./config.md#scriptorium-artifact-entries) for the
configuration layout.
`config diff` resolves both supplied overlay names independently and compares
their fully resolved, secret-free effective mappings. It does
not accept `--overlay`; the two positional names must be distinct, valid
overlays. When party-driven families are present, both overlays must resolve to
the same selected campaign and party. Use `--campaign-file` if overlay-specific
campaign configuration would otherwise select different files.
Equal overlays print `no differences`. Otherwise, sorted tab-separated records
use one of these forms, with compact JSON values:
```text ```text
added <path> <right-value> narratio
removed <path> <left-value> ├── run SESSION
changed <path> <left-value> <right-value> ├── artifacts
│ ├── list
│ └── regenerate SESSION
├── session
│ ├── init SESSION
│ ├── plan SESSION
│ ├── validate SESSION
│ ├── status SESSION
│ ├── restore SESSION
│ ├── clean [SESSION | --all]
│ ├── artifacts SESSION
│ └── locks
│ ├── list SESSION
│ ├── add SESSION SOURCE
│ └── remove SESSION SOURCE
├── config
│ ├── scopes
│ ├── validate
│ ├── show
│ ├── sources
│ ├── explain
│ └── diff
├── version
├── completion bash|zsh|fish
└── help [COMMAND...]
``` ```
Mappings are flattened to their logical field paths; lists remain one atomic Bare root and command groups display help. Use `narratio help session plan`
value. The command compares defaulted concrete artifacts and publish rules, not or `narratio session plan --help` for command-local flags and operands. Help,
overlay names, source-file layout, or formatting. It succeeds when differences version, completion, and `config scopes` do not bootstrap credentials, load
are found, making it suitable for review and migration checks. configuration, contact storage, or initialize adapters.
### `version` ## Invocation syntax
```bash Place flags after the complete command path; they may be interspersed with
narratio version operands there. For example, `narratio session plan --format json SESSION`
and `narratio session plan SESSION --format json` are equivalent. Flags are
local to the selected command. `--` ends option parsing.
Value flags accept `--name value` or `--name=value`. Boolean flags accept
presence as true or an explicit value such as `--force=false`. Repeated
single-value flags use the last successfully parsed value; every occurrence
must parse. Repeatable flags accumulate values. An explicitly supplied empty,
false, or zero value differs from omission. Narratio additionally normalizes
repeatable `--artifacts` values as described below.
## Configuration selectors
| Selector | Meaning |
| --- | --- |
| `--config PATH` | Exact pipeline root, regardless of configuration scope; omission uses discovery. |
| `--overlay NAME` | Pipeline overlay; omitted, empty, or `default` selects the base. |
| `--campaign ID` | Select and assert the effective campaign identity. |
| `--campaign-file PATH` | Exact campaign source; may accompany its identity assertion. |
| `--session ID` | Session identity for native configuration inspection only. |
| `--session-file PATH` | Exact session source; domain commands use positional `SESSION` as the identity assertion. |
| `--party-file PATH` | Select the canonical roster instead of the campaign's default file. |
| `--secrets-dir PATH` | Explicit credential-bootstrap directory. |
| `--previous-session-id ID` | Assert the configured previous-session identity on applicable domain commands. |
Explicit relative file/directory paths use the invocation directory. Explicit
file errors and identity mismatches fail without fallback. A file selects the
source; an identity asserts its effective ID after resolution. File-only
configuration inspection may obtain identity from the file. Selecting a party
file does not rewrite the campaign's party setting; the selected roster feeds
players, family expansion, planning, and execution consistently.
Selectors are installed only where applicable; command help lists them.
`session init` creates new input and therefore has no existing-session-file
or party-file selection. `session clean --all` accepts pipeline/overlay/secrets
selection and rejects campaign, session, party, and previous-session selectors.
When no explicit session file is selected, local discovery precedes remote
acquisition. Only local absence permits remote fallback, with a known identity.
Remote loading prefers authored session-root YAML, then the current commit's
prepared snapshot only when the authored object is absent. Read-only commands
may perform these reads without initializing runtime state. See
[discovery](config.md#discovery-and-selection) and
[credential bootstrap](config.md#secrets-handling) for configuration details.
## Run
```sh
narratio run SESSION
narratio run SESSION --from extract --through analyze
narratio run SESSION --stage analyze --force --artifacts session_recap
``` ```
Official release binaries report their exact Git tag. Binaries built directly The default is the full canonical pipeline:
from source without release linker metadata report `dev`. `prepare`, `transcribe`, `merge`, `polish`, `normalize`, `trim`, `render`,
`extract`, `analyze`, `publish`, `notify`, `cleanup`.
`--from` and `--through` select inclusive contiguous bounds. `--stage` selects
one stage and cannot accompany explicitly supplied range flags. `--force`
reruns selected work; dependent invalidation can extend beyond that range.
Bounded starts require valid preceding manifest state. Ordinary execution uses
semantic resume checks rather than rerunning all selected work.
### `run` Analysis-only rebuilding uses `run SESSION --stage analyze --force`; it does
not refresh extraction. Publishing alone uses `run SESSION --stage publish`,
adding `--force` when a rerun is intended. It does not schedule cleanup. See
[operations](operations.md#artifact-development-workflows) for regeneration workflows.
```bash ## Artifacts regenerate
narratio run <session_id> [--from <stage>] [--through <stage>] [--force] [--artifacts <name[,name...]>] [...common config flags]
```sh
narratio artifacts regenerate SESSION
narratio artifacts regenerate SESSION --artifacts session_recap,player_handout
``` ```
Behavior: Forces the fixed inclusive `extract` through `analyze` range. It refreshes the
whole configured Notarius extraction bundle and chunk work, then selected
analysis targets and required prerequisites. `--artifacts` narrows analysis,
not extraction lanes. Publication, notification, and cleanup are outside this
range. Independent `--from`, `--through`, `--stage`, and `--force` flags are
not installed on this command. It accepts applicable context selectors and
returns the same run report as `run`.
- evaluates one inclusive contiguous range of the canonical stage order; ## Artifacts list
- defaults an omitted `--from` to `prepare` and an omitted `--through` to
`cleanup`, so omitting both retains full-pipeline behavior;
- rejects unknown endpoints and a `--from` endpoint after `--through`;
- runs `render` before `extract`; an omitted or disabled Notarius
configuration records an explicit `notarius_disabled` self-skip;
- resolves every selected typed credential during the initial configuration
load, including Notarius credentials when extract is disabled, outside the
selected range, or later skipped as resumable;
- skips already-succeeded stages unless `--force` is set or a stage-specific
resume check finds its durable result obsolete;
- applies `--force` only to stages in the selected range;
- rejects repeated `--from`, `--through`, or `--force` options, including
`--name=value` spellings;
- continues interrupted or partially completed sessions by running non-succeeded stages;
- writes the session manifest as the sole durable progress ledger. Each
invocation also creates its run-local directory and returns an immediate
command summary; neither creates another durable progress record.
- reports the resolved overlay (or `none`) and effective configuration digest.
When `--artifacts` is present, the selected range must contain `analyze` or ```sh
`publish`. Either consumer is sufficient, including a one-stage range. narratio artifacts list --config pipeline.yml --campaign-file campaign.yml
### `regenerate-artifacts`
```bash
narratio regenerate-artifacts <session_id> [--artifacts <name[,name...]>] [...common config flags]
``` ```
Exactly equivalent to: Lists domain definitions: source identities, producers, outputs, dependencies,
and selected-party family/member provenance. It acquires the context needed to
derive that catalog, without requiring a session solely for listing definitions.
It does not add generated members to native `config show` output.
```bash ## Session plan
narratio run <session_id> --force --from extract --through analyze [caller options]
```sh
narratio session plan SESSION --stage analyze --force --format json
``` ```
The command always reruns extraction. Analysis rebuilds the selected configured Accepts the same stage/range, force, artifact, and context selections as `run`.
artifacts and any prerequisites required by those targets; without Reports execution/reuse actions and reasons, analysis targets, prerequisite work,
`--artifacts`, it uses the normal default analysis selection. Publish and notify and publication mappings through shared planners. Planning reads existing state
never run. Common session/configuration options and repeatable artifact values without creating a workspace, changing manifests, acquiring execution locks, or
pass through unchanged. initializing stage adapters. It does not predict unknown output identities.
The forced extraction rebuilds the complete configured Notarius bundle, ## Session validate
disables Notarius checkpoint loading, and requests chunk-plan refresh.
`--artifacts` narrows only the analysis work; it never selects Notarius lanes.
Because the expansion owns `--force`, `--from`, and `--through`, callers cannot ```sh
supply those options. The shared `run` parser reports them as duplicate narratio session validate SESSION --session-file ./session.yml
singleton flags. The alias has no private execution options or behavior, and
runtime diagnostics may identify the operation as `run`.
### `run-stage`
```bash
narratio run-stage <stage> <session_id> [--force] [--artifacts <name[,name...]>] [...common config flags]
``` ```
Valid stage names: Read-only preflight checks configuration and required input, audio,
previous-session, publication, and lock readiness. Material findings remain in
the report regardless of diagnostic visibility. Invalid configuration uses the
native input classification; readiness failures are operational failures.
- `prepare` ## Session status
- `transcribe`
- `merge`
- `polish`
- `normalize`
- `trim`
- `render`
- `extract`
- `analyze`
- `publish`
- `notify`
- `cleanup`
Rules: ```sh
narratio session status SESSION --format json
- `--artifacts` is accepted only for `analyze` and `publish` stage targets.
### `analyze`
```bash
narratio analyze <session_id> [--artifacts <name[,name...]>] [...common config flags]
``` ```
Equivalent to: Reports local manifest stages and artifacts, configuration provenance, readiness,
and remote current state when storage is available. Remote output entries retain
exact committed declarations and carried-output origins separately from current
configured destinations. An absent remote current pointer is a reported missing
state, rather than an error by itself. Genuine inspection failures can return a
partial report with a failed outcome.
```bash ## Session artifacts
narratio run-stage analyze <session_id> --force [...common config flags]
```sh
narratio session artifacts SESSION --remote
``` ```
This selects only `analyze`: it does not invoke Notarius, replace extraction, Reports definitions, dependencies, local availability/evidence, and optional
or remove existing extract outputs. `--artifacts` narrows the forced analysis remote publication state without reading artifact payload bodies. Without
targets and their required analysis prerequisites. `--remote`, this command avoids remote artifact inspection. Current publication
outcomes include `published`, `carried_locked`, `locked_unpublished`,
`optional_missing`, and `unselected`.
### `publish` ## Session init
```bash ```sh
narratio publish <session_id> [--artifacts <name[,name...]>] [...common config flags] narratio session init SESSION --output ./session.yml --audio-dir ./audio
narratio session init SESSION --remote --audio-s3-prefix audio/session/
``` ```
Equivalent to: Choose exactly one destination: `--output PATH` or `--remote`. Options include
`--date YYYY-MM-DD`, `--title TEXT`, `--previous-session-id ID`, `--force`,
configuration/overlay/campaign/secrets selectors, and exactly one audio override
if needed: `--audio-dir PATH` or `--audio-s3-prefix PREFIX`.
```bash A configured session template retains its import/resource authoring context;
narratio run-stage publish <session_id> --force [...common config flags] relative CLI audio paths use the invocation directory. Generated YAML is
standalone and concrete. `--format` changes only the confirmation report,
never the generated YAML file. See [initialization](operations.md#session-initialization).
## Session restore
```sh
narratio session restore SESSION --dry-run
narratio session restore SESSION --force --include-audio
``` ```
This command selects only `publish`; it does not invoke cleanup. Use a normal Uses pointer-selected committed state and returns actions/conflicts. Dry runs
full run to include configured cleanup, or `run-stage cleanup` to retry cleanup make no local directory or mode changes. Actual restore preserves confined
from valid publication evidence. replacement, transition locking, incomplete-restore recovery markers, and
manifest-last installation. `--force` permits replacement only of eligible
regular files. The public report is separate from the persisted restore
execution report. See [restore operations](operations.md#restore-workflow).
### `clean` ## Session clean
```bash ```sh
narratio clean <session_id> [--dry-run] [--clear-cache] [...common config flags] narratio session clean SESSION --dry-run
narratio clean --all [--dry-run] [--clear-cache] [--config <pipeline.yml>] narratio session clean --all --dry-run --clear-cache
``` ```
Behavior: Choose positional `SESSION` or `--all`. Removes the selected local workspace
and spool state; cache deletion requires `--clear-cache`. Dry runs return planned
actions without deletion. Partial failures retain completed actions. This manual
operation is separate from the pipeline cleanup stage. Exact scope and recovery
implications belong in [cleanup operations](operations.md#cleanup).
- session mode removes the selected session's local work and spool state; ## Session locks
- `--all` removes all local session work and spool state;
- cache remains unless `--clear-cache` is provided.
See [Operations: Cleanup](./operations.md#cleanup) for manual and pipeline-stage ```sh
deletion scope. narratio session locks list SESSION
narratio session locks add SESSION narratio.artifact.session_recap --reason 'manual review'
### `session plan` narratio session locks remove SESSION narratio.artifact.session_recap
```bash
narratio session plan <session_id> [--from <stage>] [--through <stage>] [--force] [--artifacts <name[,name...]>] [...common config flags]
``` ```
Uses the same inclusive bounds, endpoint validation, force scope, and artifact A bare locks group displays help. List reports independent remote locks sorted
selection contract as `run`. It validates config and prints run/skip decisions by source. Add reports an existing lock unless `--force` requests one
for selected stages only without creating the local workdir or changing the conditional, generation-matched replacement; concurrent change requires retry.
manifest. Resume-capable selected stages are checked against durable evidence. Remove is idempotent. `--reason TEXT` is available on add. See
The output includes the resolved overlay (or `none`) and effective configuration [publish locks](operations.md#publish-locks) for their publication effect.
digest without writing provenance or any manifest state.
For `analyze`, the preview also lists explicit targets, prerequisite-only work,
execution order, and reusable current artifacts with concise reasons. These
artifact decisions come from the same reconciliation and work planner used by
execution; the preview does not predict output identities.
### `session validate` ## `--artifacts` selection rules
```bash `run`, `session plan`, and `artifacts regenerate` accept repeatable
narratio session validate <session_id> [...common config flags] `--artifacts NAME[,NAME...]`. Values are trimmed, deduplicated, and sorted.
Family keys select all concrete members; concrete keys select one member.
Analysis includes required prerequisite closure. Publication selects applicable
configured artifact outputs. The option requires a selected analysis or publish
consumer and does not select built-in output sources or individual extraction
lanes. See [artifact configuration](config.md#scriptorium-artifact-families).
## Configuration inspection
`config scopes` lists operations and features without loading. The four scopes
are `app` (default), `campaign`, `session`, and `party`. They expose their actual
typed ConfigKit results, with native provenance, resolution history, and safe
secret views. App inspection needs no campaign/party expansion. Domain catalogs
and execution plans are separate views.
```sh
narratio config show --scope app --format json
narratio config show --scope session --session SESSION --session-file ./session.yml
narratio config show --scope party --party-file ./party.yml
narratio config show --path /scriptorium --format yaml
narratio config sources --scope campaign --campaign-file ./campaign.yml
narratio config explain --path /scriptorium --format json
narratio config explain --list --under /scriptorium --historical
narratio config validate --details --severity error
``` ```
Read-only preflight checks for config validity, required inputs, audio mode, - `show` displays safe effective values; `--path POINTER` selects a current
previous-session requirements, publish outputs, and independent remote locks. value, including present null. An empty pointer selects the root.
- `sources` lists native source records, imports, placements, version evidence,
and empty optional-import selections. `--source-id ID` selects a record from
that load. Available source evidence can be reported after load failure.
- `explain --path POINTER` reports effective/history fragments, origins,
resolution reasons/dependencies, and safe secret-reference metadata.
`explain --list` discovers paths. `--under POINTER`, `--historical`, and
`--explicit=true|false` filter discovery; they require `--list`. Historical-only
paths do not match an explicitness filter. Neither mode supplied shows help.
- `validate` returns concise status or native structured scope outcomes.
`--details` includes findings; repeatable `--severity error|warning` and
`--code CODE` filter displayed findings, never validation success.
- `--scope all` is supported for show/validate, requiring applicable context for
every reached scope. It is unsupported for sources, explain, and diff.
### `session status` Paths use JSON Pointer: escape `/` as `~1` and `~` as `~0`. Malformed pointers
fail as usage; a well-formed unknown selected path fails operationally.
Native report fields and detailed source/history semantics are documented in the
[selected CommandKit CLI contract](https://forge.maximumdirect.net/base-layer/commandkit/src/commit/b57bfe176cff05a892e6cb07ebb5f350239e55d4/docs/cli.md#configuration-scopes).
```bash ### Independent comparisons and overrides
narratio session status <session_id> [...common config flags]
```sh
narratio config diff --config pipeline.yml --against-config pipeline.yml --against-overlay testing --details --check
narratio config diff --scope party --party-file before.yml --against-party-file after.yml
narratio config show --scope app --set '/whisperx/concurrency=2'
``` ```
Prints local manifest state and, when storage is available, status for the Diff loads each side independently. In addition to native `--against-config`
pointer-selected remote commit and its declared published outputs. Current and `--against-overlay`, applicable scopes accept `--against-campaign`,
publish metadata reports `published`, `carried_locked`, `locked_unpublished`, `--against-campaign-file`, `--against-session`, `--against-session-file`, and
`optional_missing`, and `unselected`; carried output lines include the run `--against-party-file`. Omitted right-side selectors use their own normal
derived from their exact declared key, the key itself, and its declared defaults; they never inherit left-side selections. Each party default follows
destination. A separately displayed `dest` is the destination requested by the that side's campaign.
current configuration and may differ while an older declaration is locked.
### `session init` Concise diff reports `additions`, `changes`, and `deletions`; detailed diff
reports `scope` and `differences` with `path`, `before`, `after`, and
`hidden_changed`. Snapshots distinguish absence, null, and redaction. Comparison
uses effective values rather than source arrangement. Secret changes remain
hidden safely. A diff is inspection output, not a configuration patch.
```bash Only app inspection supports ordered, repeatable `--set POINTER=JSON`, plus
narratio session init <session_id> --output ./session.yml [options] `--against-set POINTER=JSON` for the comparison side. ConfigKit applies these
narratio session init <session_id> --remote [options] during that load. They affect only that invocation. Other scopes and aggregate
inspection reject overrides. Execution/planning use files and overlays;
they have no field-override flags.
## Reporting and visibility
Reports go to stdout; diagnostics and progress go to stderr. Domain commands
return one final public report where useful, including meaningful partial work
on failure. `--format text|yaml|json` selects presentation. Automatic structured
reports use YAML; text uses the same data. Version and native inspection commands
may have native text renderers. Report format does not change artifact formats.
There is no public report schema-version field.
| Category | Ordinary | `--quiet` | `--verbose` | `--debug` |
| --- | --- | --- | --- | --- |
| Final report | Shown | Hidden | Shown | Shown |
| Terminal failure | Shown | Shown | Shown | Shown |
| Info and Warning | Hidden | Hidden | Shown | Shown |
| Debug | Hidden | Hidden | Hidden | Shown |
| Progress by default | Hidden | Hidden | Hidden | Shown |
The last enabled quiet/verbose/debug mode wins. Explicit false clears only the
currently selected matching mode, returning to ordinary mode. There is no mode
stack. Independent `--progress` or `--progress=false` overrides the default;
quiet always suppresses progress. Verbose and progress can be combined.
Progress covers stage transitions/reuse, audio transfers/cache reuse, and
individual durable speaker/artifact checkpoints and validated reuse. Info adds
selected sources, destinations, and decision context. Concurrent completion
order is not fixed. Workers settle before the final report.
Console debug does not enable downstream debug captures or change retention.
Downstream streams stay in captured logs and are not replayed automatically.
Quiet changes visibility, not execution, persistence, or logging. A report or
diagnostic delivery failure can fail the invocation after durable work has
completed; it does not roll back that work.
### Public domain report fields
Optional fields appear when meaningful; these reports do not expose raw
manifests, resolved credentials, or internal dependency containers.
| Report | Fields |
| --- | --- |
| Run/regenerate | `campaign`, `session_id`, `run_id`, `stages`, `executed`, `skipped`, `stage_results`, `available_artifacts`, `artifact_targets`, `complete` |
| Plan | `campaign`, `session_id`, `stages` with `name`, `action`, `reason`, optional `analysis`; `publication_actions` |
| Catalog | `artifacts` with source, producer, output, enabled state, dependencies, optional concrete key and family/member/source provenance |
| Validation | `campaign`, `session_id`, `session_source`, `valid`, `findings` with severity, category, message |
| Status/artifacts | Identities/source, `local_manifest`, `stages`, `artifacts`, optional `remote`, configuration provenance, audio/previous-artifact readiness, `findings` |
| Init | `campaign`, `session_id`, `destination`, `remote`, `written` |
| Locks | Identities, `operation`, `result`, `complete`, optional `source`, `locks` |
| Restore | Identities/run, `dry_run`, `complete`, `status`, `downloaded`, `conflicts`, `actions` |
| Clean | Optional identities, `all`, `dry_run`, `complete`, `cache`, `actions`, optional `error` |
Run `stages` is the complete selection. `executed` includes attempted work,
including failures and self-skips. `skipped` includes reuse and self-skips.
Each `stage_results` entry has `name`, `attempted`, `outcome`
(`completed`, `failed`, `reused`, `skipped`, `not_attempted`), and optional
`reason`. Available artifacts carry `stage`, optional `source`, `kind`, `path`,
optional `producer_run_id`, and durable `evidence` (`stage_result`,
`speaker_checkpoint`, `artifact_checkpoint`). Failed or unpersisted work is not
reported as completed.
Plan analysis contains `targets`, `prerequisites`, `execute`, and `reuse`;
artifact entries identify key, optional family/character, role, reason, and
force. Publication actions identify source, destination, required, and selected.
Remote status outputs retain source, destination, required, state, lock state,
optional outcome, declared destination/key, origin run, and error. Restore
actions carry kind, relative local path, remote key, status, optional reason/error.
Clean actions carry path, status (`would_delete`, `deleted`, `missing`, `empty`,
`failed`), and optional error; cache records whether it was preserved, requested,
processed, or not applicable. Lock rows include source, reason, creation time,
and whether publication is configured for that source.
## Cancellation and exit status
Ctrl-C and termination cancel acquisition and active operations. Narratio stops
scheduling work, waits for started workers, attempts terminal local manifest
persistence, and releases acquired resources. Successful checkpoints remain
resumable. Cancellation does not schedule cleanup. Abrupt process death has no
added finalization guarantee.
| Status | Meaning |
| --- | --- |
| `0` | Success, including ordinary diff with differences. |
| `1` | Operational/readiness failure, cancellation, or output failure. |
| `2` | Invalid invocation or identifiable invalid configuration input. |
| `3` | `config diff --check` found differences. |
Missing/unreadable sources and ambiguous or callback loading failures are
operational; malformed or explicitly rejected configuration input uses native
input classification. Mixed failures preserve underlying causes and operational
precedence. Terminal failure is presented once, including in quiet mode.
## Version and completion
```sh
narratio version --format text
narratio version --scope commandkit --format json
source <(narratio completion bash)
source <(narratio completion zsh)
narratio completion fish | source
``` ```
Required target selection: Version text is `NAME VERSION` with an optional revision; structured identity
contains `name`, `version`, and `revision`. Development builds without an embedded
version report `dev`. Bash requires bash-completion initialized; Zsh requires
its completion system initialized. Native completion offers command/flag names,
static stage/scope values, and applicable file/directory hints. Dynamic campaign
and artifact completion is deferred.
- exactly one of: ## Migration from the previous CLI
- `--output <path>`
- `--remote`
Options: Removed command paths have no compatibility aliases.
- `--config <pipeline.yml>` | Previous invocation | Current invocation |
- `--campaign <id>` or `--campaign-file <campaign.yml>` | --- | --- |
- `--secrets-dir <directory>` | `run-stage STAGE SESSION` | `run SESSION --stage STAGE` |
- `--previous-session-id <id>` | `analyze SESSION` | `run SESSION --stage analyze --force` |
- `--date <YYYY-MM-DD>` | `publish SESSION` | `run SESSION --stage publish --force` |
- `--title <text>` | `regenerate-artifacts SESSION` | `artifacts regenerate SESSION` |
- `--audio-dir <path>` | `clean SESSION` / `clean --all` | `session clean SESSION` / `session clean --all` |
- `--audio-s3-prefix <prefix>` | `config artifacts` | `artifacts list` |
- `--force` | `session locks SESSION` | `session locks list SESSION` |
| `--session FILE` | `--session-file FILE`; inspection `--session` now asserts identity |
| `--session-id ID` | Positional `SESSION` on domain commands; `--session ID` on config inspection |
| `config diff LEFT_OVERLAY RIGHT_OVERLAY` | `config diff --overlay LEFT_OVERLAY --against-overlay RIGHT_OVERLAY` |
Rules: Campaign identity and file selectors may now accompany each other. Party-file
selection consistently overrides the roster without editing campaign settings.
- `--audio-dir` and `--audio-s3-prefix` are mutually exclusive. Native configuration inspection retains declarations and their actual evidence;
- if campaign `session_template_file` is configured, `session init` renders it. use catalog/plan/session views for generated domain products. Comparison defaults
- generated session YAML must be concrete (no unresolved `{{ ... }}` placeholders). are independent. Field overrides are inspection-only. Update scripts to consume
structured reports and exit classifications, place flags after the complete
### `session restore` command path, and account for native repetition and cancellation behavior.
```bash
narratio session restore <session_id> [--dry-run] [--force] [--include-audio] [...common config flags]
```
Behavior:
- discovers committed remote current state;
- plans local restores;
- writes an execution report;
- blocks unresolved conflicts. `--force` permits replacement only of eligible
regular files.
See [Operations: Restore Workflow](./operations.md#restore-workflow) for the
default restore scope, report location, and conflict-handling workflow.
### `session artifacts`
```bash
narratio session artifacts <session_id> [--remote] [...common config flags]
```
Lists effective built-in, configured Scriptorium, and configured extraction
sources; reports planned, available, unavailable, and published state without
reading payload bodies; and includes publish rules, lock state, and optional
remote published-state availability. Remote inspection uses exact commit
declarations and displays the five current publish outcomes when recorded.
### `session locks`
```bash
narratio session locks <session_id> [...common config flags]
narratio session locks add <session_id> <source> [--reason <text>] [--force] [...common config flags]
narratio session locks remove <session_id> <source> [...common config flags]
```
Behavior:
- list mode validates and reports independent remote locks sorted by source;
- add creates one lock and reports an existing lock unless `--force` is used;
- `--force` performs one generation-matched replacement and reports a
concurrent change for operator retry; and
- remove is idempotent and reports when the source was not locked.
See [Operations: Publish Locks](./operations.md#publish-locks) for lock storage
and publication behavior.
## `--artifacts` Selection Rules
An artifact-family key selects all of its concrete character members. A
concrete generated key selects only that member; mixed family and concrete
selection is deduplicated and executed as concrete keys. The resulting plan
and command output identify both the concrete key and, where applicable, its
family and character ID.
- accepted on `run`, `session plan`, `run-stage`, `analyze`, and `publish`;
- repeatable and comma-separated values are combined, surrounding whitespace
is removed, and duplicate names are collapsed;
- names must exist in `pipeline.scriptorium.artifacts`;
- empty entries are invalid;
- on `run-stage`, only `analyze` and `publish` accept the option.
Effects:
- selects explicit analyze targets; required configured prerequisites may be
reused or rebuilt before them;
- filters publish rules that source `narratio.artifact.<name>`;
- does not filter built-in transcript/bounds or explicitly configured
`narratio.extraction.<name>` publish sources; and
- does not select or filter Notarius lanes.
## Common Workflows
Run full pipeline:
```bash
narratio run 2026-04-04
```
Dry-run restore plan:
```bash
narratio session restore 2026-04-04 --dry-run
```
Generate a concrete session file from template/default structure:
```bash
narratio session init 2026-04-04 --output ./session.yml --date 2026-04-04 --title "Session 12"
```
Force publish only:
```bash
narratio publish 2026-04-04
```
Regenerate post-transcript artifacts without publishing:
```bash
narratio regenerate-artifacts 2026-04-04 --artifacts session_recap,player_handout
```
## Output And Exit Behavior
- Successful commands write their result or summary to standard output and
exit with status `0`.
- Command failures and invalid invocations write an error to standard error and
exit with status `1`.
- An unknown top-level command also prints the top-level usage summary to
standard error.
- `session restore --help` prints its command-specific usage and exits with
status `0`.
Output is intended for operator inspection. Narratio does not currently offer
a machine-readable CLI output mode; durable machine-readable state is recorded
in manifests and reports described in [Operations](./operations.md).

View File

@@ -2,7 +2,8 @@
## Purpose ## Purpose
Narratio resolves three YAML documents: Narratio loads pipeline, campaign, and session YAML, with a canonical party
roster selected explicitly or through the campaign:
- `pipeline.yml`: pipeline/runtime settings - `pipeline.yml`: pipeline/runtime settings
- `campaign.yml`: campaign identity and stable input defaults - `campaign.yml`: campaign identity and stable input defaults
@@ -12,10 +13,20 @@ Narratio resolves three YAML documents:
### `pipeline.yml` ### `pipeline.yml`
When `--config` is omitted, search order is: An explicit `--config` selects exactly that file, including a custom filename.
Otherwise ConfigKit searches these locations in order:
1. `/usr/local/etc/narratio/pipeline.yml` 1. The working directory, for `narratio.yml` then `narratio.yaml`.
2. `/etc/narratio/pipeline.yml` 2. The Go user-config directory's `narratio/` subdirectory, for those named
files followed by `config.yml`, `config.yaml`, `main.yml`, and `main.yaml`.
3. The Go user-config directory itself, for the named files.
4. `/usr/local/etc/narratio/` and then `/etc/narratio/`, each for named files
followed by the generic filenames above.
5. `/etc/`, for the named files.
On Linux, the user-config directory normally follows `XDG_CONFIG_HOME`, or
`~/.config` when it is unset. A selected invalid file fails loading; discovery
does not continue to another candidate.
### `campaign.yml` ### `campaign.yml`
@@ -27,56 +38,52 @@ Selection rules:
### `session.yml` ### `session.yml`
When `--session` is omitted, local search order is: An explicit `--session-file` selects exactly that file. Otherwise local search
order is:
1. `/usr/local/etc/narratio/session.yml` 1. `/usr/local/etc/narratio/session.yml`
2. `/etc/narratio/session.yml` 2. `/etc/narratio/session.yml`
If local session discovery fails and a `session_id` is known, Narratio attempts remote session loading from: If no local session exists and a `session_id` is known, Narratio loads the
session from configured object storage. Downloaded session bytes are contextless
snapshots, with remote object
provenance retained independently of locally materialized checksums.
- `{root_prefix}/campaigns/{campaign}/sessions/{session_id}/session.yml` Remote loading prefers an authored session-root `session.yml`, including updates
from `session init --remote --force`. When that object is absent, loading falls
back to the current commit's standalone prepared session. Published snapshots
remain immutable; restore validates the pointer-selected committed state.
using configured object storage. ### Native inspection and domain derivation
The downloaded remote session file is command-scoped: Narratio removes it after Native configuration inspection exposes four actual typed ConfigKit results:
the command finishes and records only the remote object provenance alongside app (the default pipeline scope), campaign, session, and party. Defaults,
the durable copied session input. normalization, and configuration-owned validation finish within their supported
load lifecycle. Session configuration includes applicable campaign defaults
before handoff. Completed values remain unchanged by planning or execution.
### Read-only effective pipeline inspection App inspection retains artifact-family declarations and needs no campaign or
party solely for expansion. Narratio derives concrete artifact catalogs, players,
resolved dependencies, and publication actions separately using the selected
canonical roster. `artifacts list` inspects those domain definitions;
`session plan` and `session artifacts` expose decisions and availability.
`narratio config validate`, `narratio config show`, `narratio config sources`, Native sources/explanations retain actual imports, origins, history, and recorded
and `narratio config artifacts` use the same `--config`, `--campaign`, resolution evidence. Comparisons load each side independently using its own
`--campaign-file`, and normal defaults. App-only inspection overrides apply during that invocation's
`--overlay` selection rules as pipeline commands, but do not select, discover, load. Safe views hide resolved credentials. Persisted preparation projections
or load a session. They resolve configured typed credential references as part retain reference names and do not replace the native inspection result.
of the ordinary ConfigKit load but expose only their environment-variable names; See the [CLI reference](cli.md#configuration-inspection) for scopes, selectors,
they do not create runtime state. path operations, overrides, comparison modes, and report shapes.
`narratio config diff <left-overlay> <right-overlay>` uses the same pipeline and
campaign selectors, resolves each named overlay with an independent ConfigKit
load, and does not accept a separate `--overlay` flag.
Campaign selection is optional only when the resolved pipeline has no ### Party selection
`scriptorium.artifact_families`. When families are declared, Narratio selects a
campaign through an explicit flag or `pipeline.campaigns.default_campaign_id`,
then parses the campaign-owned party and expands concrete artifacts and any
family publish rules before validation. `config validate` prints the resulting
root, overlay, and effective digest. `config show` emits the normalized
effective pipeline YAML, with defaults and concrete expansion included but
ConfigKit directives and family declarations omitted. This review projection is
not promised to be a reloadable authoring document. `config sources` prints a stable
source projection instead of effective values: root/import/overlay/default
ownership plus campaign/party and generated-family records. Canonical derived
players trace to the party. `config artifacts` lists the concrete artifact map,
effective dependencies, and defining sources. The [CLI reference](cli.md#config-validate-config-show-config-sources-config-artifacts-and-config-diff)
owns command syntax and output conventions.
`config diff` compares normalized field values rather than YAML text or source `--party-file` selects an exact canonical roster instead of the campaign-default
ownership. It emits sorted `added`, `removed`, and `changed` records, uses file. Explicit relative paths use the invocation directory; invalid or missing
compact deterministic JSON values, treats lists atomically, and reports `no explicit input fails without fallback. The campaign's configured party field
differences` when the complete effective configurations are equal. Concrete remains unchanged. Inspection, players, family derivation, planning, and execution
family members and generated publish rules participate after expansion; moving use the same selected roster. Format and validation belong in the
an equal value between eligible root/import sources does not create a [party integration contract](integrations/party.md).
difference.
### Migrating to the maintained bundle ### Migrating to the maintained bundle
@@ -87,7 +94,8 @@ in the fixed `overlays/testing.yml` overlay. Put ordinary artifacts and families
in the recommended one-definition files shown by that bundle. Convert campaign in the recommended one-definition files shown by that bundle. Convert campaign
rosters to [canonical party input](integrations/party.md), then express character rosters to [canonical party input](integrations/party.md), then express character
work as families. Inspect the result with `config validate`, `config show`, work as families. Inspect the result with `config validate`, `config show`,
`config sources`, and `config artifacts`; use `config diff default testing` to `config sources`, and `artifacts list`; use
`config diff --against-overlay testing` to
review the overlay before running a session. Unversioned party documents are review the overlay before running a session. Unversioned party documents are
rejected. rejected.
@@ -104,23 +112,14 @@ remote state with an unsafe legacy identity must be migrated before use.
- ConfigKit performs strict typed YAML decoding and accepts exactly one document; - ConfigKit performs strict typed YAML decoding and accepts exactly one document;
unknown fields, duplicate keys, and trailing documents fail load. unknown fields, duplicate keys, and trailing documents fail load.
- A pipeline file may explicitly import additive YAML fragments through the - Local pipeline, campaign, session, and party documents may declare native
root-only `configkit.imports` list. Imported files contribute fields to one imports and sibling inheritance. Only the pipeline selects an overlay.
logical pipeline document; they do not override fields supplied by the root - An omitted overlay, empty overlay option, and exact `default` select the base;
or another import. another name selects `overlays/<name>.yml` relative to the pipeline root.
- An omitted overlay, an empty overlay option, and the exact name `default`
select the base configuration. Any other name selects
`overlays/<name>.yml` relative to the pipeline root. Move previously selected
`profiles/<name>.yml` files there; the old directory is not searched, and
`--profile` is no longer accepted for Narratio pipeline selection. Explicit
imports from a directory named `profiles` remain valid.
- Campaign, session, and canonical-party documents are strict single-source
ConfigKit schemas. They do not enable imports, overlays, or `configkit`
directives.
- Configured timeout and retry-delay durations must be positive. An omitted - Configured timeout and retry-delay durations must be positive. An omitted
artifact timeout continues to inherit its configured Scriptorium timeout. artifact timeout continues to inherit its configured Scriptorium timeout.
- Session files must be concrete; unresolved `{{ ... }}` placeholders fail load. - Session files must be concrete; unresolved `{{ ... }}` placeholders fail load.
- Session and party inputs inspected before typed loading are limited to 8 MiB. - ConfigKit applies its acquisition limits to configuration sources and imports.
- Pipeline defaults are applied before validation. - Pipeline defaults are applied before validation.
- Defaults apply only to absent fields. Explicit empty strings, zero values, - Defaults apply only to absent fields. Explicit empty strings, zero values,
`false`, and `null` retain ConfigKit's typed meaning and are then checked by `false`, and `null` retain ConfigKit's typed meaning and are then checked by
@@ -132,9 +131,10 @@ remote state with an unsafe legacy identity must be migrated before use.
`party_file`) are campaign-owned; the first three may be overridden by the `party_file`) are campaign-owned; the first three may be overridden by the
session. The optional `spell_catalog_file` also inherits a campaign value session. The optional `spell_catalog_file` also inherits a campaign value
when omitted by the session. when omitted by the session.
- `party_file` is parsed when pipeline and campaign configuration are combined. - The selected party is parsed when domain context or party inspection needs
It must be a versioned [canonical party](integrations/party.md), is it. It must be a versioned [canonical party](integrations/party.md). The
campaign-owned and derives the players input internally. `players_file` and campaign supplies its default file; an explicit CLI selection replaces it
for the invocation and supplies the derived players input. `players_file` and
session `party_file` are unsupported configuration keys. session `party_file` are unsupported configuration keys.
- Exactly one audio mode must be configured in session input: - Exactly one audio mode must be configured in session input:
- local (`audio_dir` or `audio_files`), or - local (`audio_dir` or `audio_files`), or
@@ -142,57 +142,74 @@ remote state with an unsafe legacy identity must be migrated before use.
### Pipeline imports and overlays ### Pipeline imports and overlays
Large pipeline configurations may be split into explicitly named fragments and Local pipeline, campaign, session, and party files can use source-root
may use fixed-path selected overlays: `config.imports` and `config.sequences`. Every acquired document has its own
source-root controls, including imported fragments. Nested `config` keys are
ordinary data. `extends` is reserved for native sibling inheritance; parents
remain ordinary entries subject to Narratio's effective-domain validation.
```yaml ```yaml
configkit: config:
imports: imports:
- path: config/storage.yml - path: artifacts/session-recap.yml
- path: config/integrations.yaml destination: [scriptorium, artifacts, session_recap]
required: true
campaigns: - dir: artifacts/families
root: /usr/local/share/narratio/campaigns pattern: "*.yml"
``` ```
The maintained [production/testing bundle](../examples/production-testing/pipeline.yml) Imports support `path`, `dir`, and `glob` selectors, applicable filters and
is a complete copyable example of this structure, including canonical-party relative destinations. Paths are relative to the declaring source. Missing or
artifact families. empty selections are optional by default; use `required: true` when a selection
is essential. Selected invalid input fails. Destinations place content under
literal mapping keys, independent of filenames; nested imports can declare
relative destinations. Strict peer contributions must satisfy ConfigKit's
composition rules, and Narratio validates the resulting effective entries.
Imports are resolved relative to the directory containing the root pipeline A selected pipeline overlay is applied after base composition. It may declare
file and are loaded in declaration order. Narratio does not scan directories or root `config.sequences` but cannot import other files. Ordinary overlay lists
infer fragments. Each import must be a confined regular `.yml` or `.yaml` file: replace the lower list; declared collections can use native `replace`, `append`,
absolute paths, traversal, symlinks, directories, duplicate files, and an or `upsert`. Upsert replaces a whole matching record; an empty append or upsert
import of the root pipeline itself are rejected. Imported files cannot declare does not clear the lower list. Mapping and identified-list inheritance follow
another `configkit` control section. native sibling rules. See the pinned [ConfigKit configuration contract](https://forge.maximumdirect.net/base-layer/configkit/src/commit/51ef3144158db1a09fabdbd1c7ae59908c84923b/docs/config.md)
and [consumer guide](https://forge.maximumdirect.net/base-layer/configkit/src/commit/51ef3144158db1a09fabdbd1c7ae59908c84923b/docs/consumers/README.md)
for full selection, composition, collection, and reserved-key semantics.
The [maintained bundle](../examples/production-testing/pipeline.yml) illustrates
these controls, family expansion, and a split roster.
Base merging is additive. A map may be extended by multiple files when every Relative host-resource paths, including integration configuration files,
leaf is distinct, but a scalar, list, or map/list/scalar kind cannot be claimed workspace/campaign/spool/cache roots, campaign template and stable inputs, and
more than once, even when the repeated values are identical. Conflict errors session stable inputs and local audio references, resolve from the effective
name the full field path and every source that claimed it. Narratio additionally value's defining source. Inherited values follow their origin. When no distinct
rejects an artifact or artifact-family key declared by more than one base file, usable source context exists, the main source is the fallback; if it too is
even when those files contribute disjoint children. contextless, the invocation directory is used. Explicit CLI-relative file paths
use the invocation directory. Artifact outputs, publish destinations, logical
IDs, and binary names retain their domain meanings.
Overlay names are case-sensitive and use ConfigKit's safe fixed-path naming The effective digest excludes source layout, overlay identity, and secret values;
rules. Only the selected overlay is opened; a malformed unselected overlay does credential reference names and resolved resource paths participate. Prepared
not affect a base or different-overlay load. Maps merge recursively, overlay campaign, session, and party documents contain effective standalone values rather
scalars replace base scalars, and overlay lists replace base lists completely. than authored import directives. Session fields omitted by the author remain
Explicit `false`, zero, empty strings, empty containers, and null values remain eligible to inherit the receiving campaign's values.
explicit inputs and are not refilled by defaults. Overlays cannot inherit,
stack, import files, or declare another ConfigKit control section.
During ConfigKit loading, Narratio applies fresh typed defaults, recorded ### Upgrade from earlier configuration
entry-level defaults and normalization, read-only file-local validation, and
ordinary path resolution before computing a deterministic effective
configuration digest. The digest represents the normalized, secret-free
runtime pipeline mapping; it excludes ConfigKit directives, source
provenance, overlay identity, and raw environment secret values. Equivalent
effective mappings therefore have the same digest regardless of how fields are
split among the root and imports.
An imported field has the same meaning it would have in a monolithic root - Rename source-root `configkit:` controls to `config:`. Nested `config` data
pipeline. In particular, ordinary relative pipeline paths continue to resolve and the Go `configkit` package and secret tags have different meanings.
from the root pipeline directory, not from the importing fragment's directory. - Rename or move pipeline files to the discovery names above, or retain a custom
filename such as `pipeline.yml` and pass it with `--config`.
- Move conventional secrets to `/usr/local/etc/narratio/secrets`, supply them
through the environment, or pass the previous directory with `--secrets-dir`.
- Review relative resource references moved into fragments: their defining
source now supplies the base. Mark necessary imports `required: true`.
- Review lists and use `config.sequences` where append or whole-record upsert is
intended. Verify the effective result with the inspection commands.
- Prepared documents contain effective values; retain authored roots and their
companions separately for editing. Separately installed downstream tools own
their own configuration migrations.
These control-key changes require a major version for the eventual Narratio
release. This migration does not itself publish a release.
## Minimal Working Configuration ## Minimal Working Configuration
@@ -237,8 +254,8 @@ inputs:
stage range, or eligible for resume. Omit the field or set it to `null` when stage range, or eligible for resume. Omit the field or set it to `null` when
that deployment should not require the credential. that deployment should not require the credential.
- Every command that loads a pipeline accepts `--secrets-dir <path>`. When the - Every command that loads a pipeline accepts `--secrets-dir <path>`. When the
flag is omitted, Narratio uses a present `secrets/` directory beside the flag is omitted, Narratio uses `/usr/local/etc/narratio/secrets` when present;
resolved root `pipeline.yml`; an absent conventional directory is ignored. an absent conventional directory is ignored.
Explicit relative paths are resolved from the caller's working directory, Explicit relative paths are resolved from the caller's working directory,
and a missing or empty explicit selection is an error. and a missing or empty explicit selection is an error.
- Each immediate regular file whose name is a valid environment-variable name - Each immediate regular file whose name is a valid environment-variable name
@@ -294,7 +311,7 @@ Rules:
| Field | Type | Required | Default / Rule | | Field | Type | Required | Default / Rule |
| --- | --- | --- | --- | | --- | --- | --- | --- |
| `configkit.imports[].path` | string | No | explicit additive pipeline fragment relative to the root pipeline directory; `.yml` or `.yaml` regular files only | | `config.imports` | list | No | native source-root import selections; see [imports and overlays](#pipeline-imports-and-overlays) |
| `pipeline.workspace.root` | string | No | `/var/lib/narratio` | | `pipeline.workspace.root` | string | No | `/var/lib/narratio` |
| `pipeline.workspace.cleanup_after_publish` | bool | No | `false`; selects the published run's workspace target for final cleanup and requires effective `pipeline.publish.enabled=true` and `pipeline.publish.upload_run=true` | | `pipeline.workspace.cleanup_after_publish` | bool | No | `false`; selects the published run's workspace target for final cleanup and requires effective `pipeline.publish.enabled=true` and `pipeline.publish.upload_run=true` |
| `pipeline.campaigns.root` | string | No | `/usr/local/share/narratio/campaigns` | | `pipeline.campaigns.root` | string | No | `/usr/local/share/narratio/campaigns` |
@@ -359,10 +376,10 @@ Rules:
| `pipeline.notarius.binary` | string | No | `notarius` | | `pipeline.notarius.binary` | string | No | `notarius` |
| `pipeline.notarius.credentials[]` | list[secret reference] | No | empty; exact environment-variable names forwarded to Notarius | | `pipeline.notarius.credentials[]` | list[secret reference] | No | empty; exact environment-variable names forwarded to Notarius |
| `pipeline.notarius.config_overlay` | string | No | unset; exact Notarius ConfigKit overlay selector | | `pipeline.notarius.config_overlay` | string | No | unset; exact Notarius ConfigKit overlay selector |
| `pipeline.notarius.config_path` | string | Conditional | required when enabled; relative paths resolve from the pipeline file directory | | `pipeline.notarius.config_path` | string | Conditional | required when enabled; relative paths resolve from their defining source |
| `pipeline.notarius.pipeline_id` | string | Conditional | required when enabled | | `pipeline.notarius.pipeline_id` | string | Conditional | required when enabled |
| `pipeline.notarius.timeout` | duration | No | `3h`; must be positive | | `pipeline.notarius.timeout` | duration | No | `3h`; must be positive |
| `pipeline.notarius.working_directory` | string | No | directory containing resolved `config_path`; relative paths resolve from the pipeline file directory | | `pipeline.notarius.working_directory` | string | No | directory containing resolved `config_path`; relative paths resolve from their defining source |
| `pipeline.notarius.resume` | bool | No | `false`; request compatible Notarius checkpoint reuse during ordinary executed extraction | | `pipeline.notarius.resume` | bool | No | `false`; request compatible Notarius checkpoint reuse during ordinary executed extraction |
| `pipeline.notarius.chunk_cache` | string | No | empty; when set, exactly `auto`, `bypass`, or `refresh` | | `pipeline.notarius.chunk_cache` | string | No | empty; when set, exactly `auto`, `bypass`, or `refresh` |
| `pipeline.notarius.references` | map[string]string | No | empty; maps normalized Notarius selectors to supported prepared Narratio source IDs; maximum 256 entries | | `pipeline.notarius.references` | map[string]string | No | empty; maps normalized Notarius selectors to supported prepared Narratio source IDs; maximum 256 entries |
@@ -374,6 +391,7 @@ Rules:
| `pipeline.render.include_segment_ids` | bool | No | `true` | | `pipeline.render.include_segment_ids` | bool | No | `true` |
| `pipeline.render.include_metadata` | bool | No | `false` | | `pipeline.render.include_metadata` | bool | No | `false` |
| `pipeline.scriptorium.binary` | string | No | `scriptorium` | | `pipeline.scriptorium.binary` | string | No | `scriptorium` |
| `pipeline.scriptorium.credentials[]` | list[secret reference] | No | empty; exact environment-variable names forwarded to Scriptorium |
| `pipeline.scriptorium.config_path` | string | No | empty | | `pipeline.scriptorium.config_path` | string | No | empty |
| `pipeline.scriptorium.timeout` | duration | No | `10m` | | `pipeline.scriptorium.timeout` | duration | No | `10m` |
| `pipeline.scriptorium.render_debug` | bool | No | `false` | | `pipeline.scriptorium.render_debug` | bool | No | `false` |
@@ -544,6 +562,25 @@ contract-incompatible lane fails extraction. See the
current ten-lane D&D mapping and the [Notarius contract](./integrations/notarius.md) current ten-lane D&D mapping and the [Notarius contract](./integrations/notarius.md)
for compatibility ownership. for compatibility ownership.
### Scriptorium Credentials
Set `scriptorium.credentials: [OPENROUTER_API_KEY]` in the pipeline file to
forward that provider key to Scriptorium. List additional provider names only
when the selected downstream configuration needs them. The same list applies
to trim bounds generation, analysis (including character families), and their
render-debug calls. Scriptorium retains provider/profile selection; Narratio
does not pass a model-request `--api-key-env` override.
As with Audita and Notarius, names are ConfigKit secret references resolved at
pipeline load time using the existing environment/secrets bootstrap precedence,
even when no Scriptorium stage executes. Omitted, null, or empty lists forward
nothing. An overlay replaces the entire list; `[]` clears it. Captured values
are forwarded under their exact names and registered for diagnostic redaction.
Inspection and generated metadata contain names only. Credential changes do
not invalidate completed trim or analysis work; rotating values also leaves
the effective configuration digest unchanged. Other environment variables
retain the shared minimal subprocess inheritance rules.
### Scriptorium Artifact Entries ### Scriptorium Artifact Entries
For each `pipeline.scriptorium.artifacts.<name>`: For each `pipeline.scriptorium.artifacts.<name>`:
@@ -586,19 +623,19 @@ does not provide adapter-specific input passthrough fields.
Each `narratio.artifact.<name>` input source automatically contributes an Each `narratio.artifact.<name>` input source automatically contributes an
effective dependency on that configured artifact. Narratio unions these inferred effective dependency on that configured artifact. Narratio unions these inferred
edges with explicit `depends_on` entries, then trims, deduplicates, and sorts the edges with explicit `depends_on` entries, then trims, deduplicates, and sorts the
result during final configuration resolution. Authors use `depends_on` only for result during domain catalog derivation. Authors use `depends_on` only for
ordering constraints that are not already expressed by an artifact input. ordering constraints that are not already expressed by an artifact input.
Use [`narratio config artifacts`](./cli.md#config-validate-config-show-config-sources-config-artifacts-and-config-diff) Use [`narratio artifacts list`](./cli.md#artifacts-list)
to inspect keys, definition sources, outputs, and effective dependencies without to inspect keys, definition sources, outputs, and effective dependencies without
loading a session or creating runtime state. loading a session or creating runtime state.
### Scriptorium Artifact Families ### Scriptorium Artifact Families
`pipeline.scriptorium.artifact_families` declares a shared artifact template `pipeline.scriptorium.artifact_families` declares a shared artifact template
for every canonical campaign character. Configuration resolution expands each for every canonical campaign character. Domain catalog derivation expands each
family into ordinary `pipeline.scriptorium.artifacts` entries before analyze family into separate concrete artifact entries before analyze planning or
planning or Scriptorium invocation. Party parsing rejects unsupported document Scriptorium invocation, retaining the authored declarations in configuration.
schemas before family expansion. Party parsing rejects unsupported document schemas before family expansion.
For each `pipeline.scriptorium.artifact_families.<name>`: For each `pipeline.scriptorium.artifact_families.<name>`:
@@ -609,7 +646,11 @@ For each `pipeline.scriptorium.artifact_families.<name>`:
| `output_path_pattern` | string | Yes | safe path beneath `artifacts/` with exactly one `{character_id}` token and no other brace syntax | | `output_path_pattern` | string | Yes | safe path beneath `artifacts/` with exactly one `{character_id}` token and no other brace syntax |
| `member_vars` | map | No | maps an ordinary Scriptorium variable name to a supported canonical character selector | | `member_vars` | map | No | maps an ordinary Scriptorium variable name to a supported canonical character selector |
| `member_dependencies` | list | No | unique family keys; each generated member depends on the corresponding generated member of each listed family | | `member_dependencies` | list | No | unique family keys; each generated member depends on the corresponding generated member of each listed family |
| `publish` | map | No | typed family publish policy (`enabled`, `required`, `dest_pattern`) expanded into concrete publish outputs when enabled | | `publish` | map | No | typed family publish policy (`enabled`, `required`, `dest_pattern`) validated against effective `pipeline.publish` settings and expanded into concrete publish outputs when enabled |
An enabled family publish declaration is validated against the effective
`pipeline.publish` configuration, including its defaults; it does not require
an explicit `publish.enabled` declaration in the same source file.
Generated keys are `<family>_<character_id>` and generated output paths must Generated keys are `<family>_<character_id>` and generated output paths must
not collide with explicit artifacts or another generated artifact. Families not collide with explicit artifacts or another generated artifact. Families
@@ -647,7 +688,7 @@ integration.
| `inputs.speakers_file` | string | Yes | stable input default | | `inputs.speakers_file` | string | Yes | stable input default |
| `inputs.autocorrect_file` | string | Yes | stable input default | | `inputs.autocorrect_file` | string | Yes | stable input default |
| `inputs.glossary_file` | string | Yes | stable input default | | `inputs.glossary_file` | string | Yes | stable input default |
| `inputs.party_file` | string | Yes | stable campaign party source; relative paths resolve from `campaign.yml` | | `inputs.party_file` | string | Yes | stable campaign party source; relative paths resolve from their defining source |
| `inputs.spell_catalog_file` | string | No | optional spell-catalog overlay default; required when a Notarius reference selects `narratio.input.spell_catalog` | | `inputs.spell_catalog_file` | string | No | optional spell-catalog overlay default; required when a Notarius reference selects `narratio.input.spell_catalog` |
### Session ### Session
@@ -662,7 +703,7 @@ integration.
| `inputs.speakers_file` | string | No | overrides campaign stable input | | `inputs.speakers_file` | string | No | overrides campaign stable input |
| `inputs.autocorrect_file` | string | No | overrides campaign stable input | | `inputs.autocorrect_file` | string | No | overrides campaign stable input |
| `inputs.glossary_file` | string | No | overrides campaign stable input | | `inputs.glossary_file` | string | No | overrides campaign stable input |
| `inputs.spell_catalog_file` | string | No | overrides the optional campaign spell catalog; empty or omitted inherits the campaign value | | `inputs.spell_catalog_file` | string | No | omission inherits the campaign spell catalog; an explicit empty string clears this optional input |
| `inputs.audio_dir` | string | Conditional | local audio mode | | `inputs.audio_dir` | string | Conditional | local audio mode |
| `inputs.audio_files[]` | list[string] | Conditional | local audio mode | | `inputs.audio_files[]` | list[string] | Conditional | local audio mode |
| `inputs.audio_s3.prefix` | string | Conditional | S3 audio mode | | `inputs.audio_s3.prefix` | string | Conditional | S3 audio mode |

View File

@@ -16,8 +16,10 @@ commit-after-completed-work rule; it does not authorize pushing or releasing.
## Go Prerequisite ## Go Prerequisite
Maintained development and verification require Go 1.26. Use the official Go The Go consumer minimum is 1.27.0, declared in `go.mod`. Maintained development
1.26 toolchain before running repository commands. and verification use the official Go 1.27.4 toolchain. Release validation and
builds use the selected patch version and setup instructions in the
[release procedure](release.md#release-toolchain).
## Policy Reading Guide ## Policy Reading Guide

View File

@@ -1,8 +1,8 @@
# Canonical Party Input # Canonical Party Input
`party.yml` is a campaign-owned roster input. It must be a single, versioned `party.yml` is a campaign-owned roster input. Its main document must declare
`narratio.party.v1` document when Narratio resolves a pipeline, campaign, and `narratio.party.v1` when Narratio resolves the roster. Local party files may
session together. import fragments; fragments need no version header.
```yaml ```yaml
schema_version: narratio.party.v1 schema_version: narratio.party.v1
@@ -48,8 +48,8 @@ The configuration rules and source-relative path behavior are defined in the
## Derived players document ## Derived players document
During `prepare`, Narratio copies the canonical party source bytes unchanged During `prepare`, Narratio renders the effective roster as standalone canonical
to `inputs/party.yml` and writes this deterministic players-only projection to `inputs/party.yml` and writes this deterministic players-only projection to
`inputs/players.yml`: `inputs/players.yml`:
```yaml ```yaml

View File

@@ -21,7 +21,7 @@ Both request types carry:
- output path; - output path;
- timeout; - timeout;
- generated config + stdout/stderr log paths; - generated config + stdout/stderr log paths;
- optional API-key env var name; - optional list of already-resolved credential references;
- optional working directory. - optional working directory.
## Result Contract ## Result Contract
@@ -39,7 +39,16 @@ Request validation fails for:
- non-positive timeout; - non-positive timeout;
- empty input/var names; - empty input/var names;
- empty input path values; - empty input path values;
- missing required credential env var when `APIKeyEnv` is set. - unresolved or empty selected credential references.
Both modes use the shared credential forwarding used by Audita and Notarius:
selected names and captured values augment the minimal child environment, and
all selected values are registered for captured-stream redaction. The adapter
does not reread the parent environment or override Scriptorium's provider
selection with `--api-key-env`. Generated invocation records and result metadata
contain `credential_env_names`, never credential values. This does not scan or
redact files written directly by Scriptorium. Selection semantics belong in
[Scriptorium credentials](../config.md#scriptorium-credentials).
Run behavior: Run behavior:
- subprocess errors propagate with context; - subprocess errors propagate with context;

View File

@@ -69,13 +69,13 @@ It also serializes an effective resume request as `--resume` and a nonempty
validated chunk mode as `--chunk_cache <mode>`. The extract stage, not the validated chunk mode as `--chunk_cache <mode>`. The extract stage, not the
adapter, resolves force precedence before constructing the request. adapter, resolves force precedence before constructing the request.
Its request may also carry already-resolved ConfigKit secret references. Its request may also carry already-resolved ConfigKit secret references.
Audita's request carries the same kind of list. Both adapters use the shared Audita and Scriptorium requests carry the same kind of list. All three adapters use the shared
subprocess helper to convert their selected references into exact-name child subprocess helper to convert their selected references into exact-name child
environment overrides and sensitive-name registration. That helper rejects environment overrides and sensitive-name registration. That helper rejects
unresolved or empty programmatic references, but neither adapter rereads the unresolved or empty programmatic references, but no adapter rereads the
parent environment or inspects downstream configuration to discover names. parent environment or inspects downstream configuration to discover names.
Empty lists add no credential overrides. See the public [Audita](../integrations/audita.md) Empty lists add no credential overrides. See the public [Audita](../integrations/audita.md)
and [Notarius](../integrations/notarius.md) contracts for selection and [Notarius](../integrations/notarius.md), and [Scriptorium](../integrations/scriptorium.md) contracts for selection and
downstream-file boundaries. downstream-file boundaries.
Application-owned object-store construction loads configured filesystem Application-owned object-store construction loads configured filesystem

View File

@@ -58,16 +58,16 @@ Configured definitions are always registered. Without an explicit selection,
the effective analyze set contains enabled definitions. With `--artifacts`, the the effective analyze set contains enabled definitions. With `--artifacts`, the
exact named configured definitions become the effective set for that invocation, exact named configured definitions become the effective set for that invocation,
regardless of their `enabled` value. The effective-set resolver itself does not regardless of their `enabled` value. The effective-set resolver itself does not
expand dependencies. Configuration has already materialized the sorted union of expand dependencies. Shared domain catalog derivation has materialized the sorted
explicit ordering edges and configured-artifact input edges, and the analyze union of explicit ordering edges and configured-artifact input edges, and the analyze
work planner closes targets over that one concrete prerequisite graph. work planner closes targets over that one concrete prerequisite graph.
Availability is separate from executability. Configuration may normalize a Availability is separate from executability. Invocation selection normalizes a
family selection into its concrete generated members before this resolver runs. family selection into its concrete generated members before this resolver runs.
The effective set retains optional family The effective set retains optional family
and character origin metadata, but its keys, catalog sources, and runtime and character origin metadata, but its keys, catalog sources, and runtime
lookups remain concrete configured-artifact identities. lookups remain concrete configured-artifact identities.
Family publish policies are likewise expanded into ordinary configured-source Family publish policies are likewise expanded into ordinary configured-source
publish rules during configuration resolution. publish actions during domain catalog derivation.
Configured outputs, including non-executable prerequisites, become available Configured outputs, including non-executable prerequisites, become available
only when the versioned analyze state identifies a current result whose source, only when the versioned analyze state identifies a current result whose source,
contract, canonical configured path, size, and checksum match a confined contract, canonical configured path, size, and checksum match a confined

View File

@@ -37,6 +37,8 @@ Restore planner action kinds:
Planner behavior: Planner behavior:
- prepared campaign, session, and party inputs are restored from their declared
immutable run objects to their canonical local input paths;
- a new-protocol restore uses only the selected commit's declared artifact set; - a new-protocol restore uses only the selected commit's declared artifact set;
each action carries that artifact's immutable key, checksum, size, and each action carries that artifact's immutable key, checksum, size, and
generation; generation;

View File

@@ -1,216 +1,98 @@
# Configuration Internals # Configuration Internals
User-visible fields, defaults, and selection behavior belong in the User-visible fields, defaults, discovery, and selection belong in the
[Configuration Reference](../config.md). This document describes the internal [Configuration Reference](../config.md). This document describes the
pipeline-loading boundary implemented by `internal/config`. `internal/config` loading and derivation boundary established by
[ADR 0003](../adr/0003-assign-configuration-ownership.md).
## Pipeline Loading ## Typed Configuration Handoff
`LoadPipeline` assembles and validates a pipeline in this order: Pipeline, campaign, session, and party loaders retain their actual typed
ConfigKit results. ConfigKit owns imports, overlay composition, inheritance,
presence, typed secrets, and native source/history evidence. Narratio's
supported definition callbacks complete configuration-owned defaults,
normalization, resource resolution, and validation before handoff. Consumers
read completed values without mutation.
1. Give ConfigKit a fresh typed `PipelineConfig` default value, the root file, Session definitions receive selected-campaign defaults before loading finishes.
enabled imports, and the caller's overlay selection. Omitted, empty, and Recorded resolution preserves explicit empty/null/false/zero behavior and
exact `default` selections use the base; named overlays use the fixed truthful dependencies. Campaign, session, and previous-session assertions run
`overlays/<name>.yml` convention. against resolved values in native validation callbacks. Standalone document
2. ConfigKit parses the root and declared imports, additively merges base renderers preserve materialization semantics without providing a second
sources, applies only the selected overlay, and strictly decodes the result. inspection authority.
3. The definition resolver applies recorded entry-level and inherited defaults,
runs deterministic domain normalization, records derived publish destinations,
and resolves ordinary paths relative to the root pipeline file.
4. The definition validator performs read-only checks that require only the
pipeline file. Checks requiring canonical-party family expansion remain at
the existing explicit pipeline/campaign resolution boundary.
5. Narratio inspects public ConfigKit metadata to reject artifact and family keys
declared by multiple base files, adapts source ownership records, attaches
runtime-only state, and computes the normalized effective digest.
This ordering preserves monolithic configuration behavior. Moving a field to Resource resolution consults native entry origins and source contexts. A usable
an imported fragment changes its source ownership, not its path base, default, effective source supplies the base, otherwise the main source and then captured
or schema semantics. invocation directory provide the fallback. Explicit CLI paths use the invocation
directory. See [resource rules](../config.md#pipeline-imports-and-overlays).
## Loaded Context Resolution ## Invocation Acquisition
`LoadedPipelineCampaign` carries one already composed pipeline and its selected `internal/app/configuration_acquisition.go` owns lazy invocation selections and
campaign into session resolution. `LoadSessionWithPipelineCampaignOptions` acquired context. Exact sources and effective-identity assertions are
loads a local session against that context, while complementary. App acquisition needs no campaign or party for expansion;
`ResolveLoadedPipelineCampaign` also accepts an already loaded remote session campaign acquisition needs no session. Session acquisition loads campaign
or no session while a caller retrieves one. Compatibility loaders route through context when required for defaults. Explicit party acquisition does not require
these functions after their initial pipeline and campaign reads. a session. Credential bootstrap runs once per reached invocation after static
input checks.
Application commands own pipeline and campaign discovery, campaign-file versus `LoadedPipelineCampaign` retains one selected pipeline/campaign while local or
registry selection, and the corresponding mutual-exclusion rules. Once they remote session resolution proceeds. Only absence permits remote fallback;
have a `LoadedPipelineCampaign`, local session discovery and remote-session access, decoding, and identity failures retain their causes. Remote acquisition
download retain that exact pipeline object and its private provenance. Removing prefers authored session-root input and uses the committed prepared snapshot
a temporary downloaded session file therefore cannot invalidate the resolved only when authored input is absent. Temporary materialization retains object
pipeline or campaign context. provenance and releases resources on success or failure. Read-only acquisition
creates no runtime workspace, execution lock, restore state, or stage adapter.
Campaign and session files use independent ConfigKit definitions with imports ## Native Inspection
and overlays disabled. Campaign files normally load directly from their source;
session files are first read through the 8 MiB bounded-read boundary because the
application must reject unresolved template placeholders before passing an exact
byte snapshot to ConfigKit. Local and remotely downloaded session bytes then use
the same typed loader and retain the existing post-load identity expectations,
stable-input precedence, and source-relative path semantics.
The application also has a separate read-only inspection resolver for `config `configuration_commands.go` adapts actual results with `ckconfig.FromConfigKit`.
validate`, `config show`, `config sources`, and `config artifacts`. It uses the Native show, sources, explain/history, validation, and comparisons consume that
same production root, overlay, and campaign selection functions, but never routes result's values and evidence. There is no flattened replacement snapshot,
through session discovery, synthetic source reconciliation, or generated family catalog in app inspection.
remote-session download, adapter composition, workspace
initialization, manifest access, or cleanup. A pipeline with retained artifact
family declarations must resolve its selected campaign before ordinary pipeline
validation, which expands its canonical-party members and generated publish
rules. A pipeline without those declarations may be validated by itself.
Secret-directory bootstrap remains invocation-scoped and happens before the
ordinary ConfigKit load because explicit typed references must resolve even for
inspection.
`MarshalEffectivePipeline` is the configuration-owned projection for `config Comparison sides load independently using each side's normal defaults and
show`. It serializes one explicit typed safe projection with the existing YAML selectors. App-only overrides pass through native selection into ConfigKit;
encoder. The projection has no slots for resolution-only artifact family they remain invocation-local. Field overrides are unavailable to domain
declarations or private provenance. The result has one trailing newline; execution/planning and other scopes. Shared bootstrap does not imply shared
commands do not marshal runtime objects directly. overridden results. Public inspection and error paths preserve typed-secret
redaction and credential reference metadata. Load failures retain native errors
and source evidence; domain commands use `ckconfig.AdaptDiagnostics` for their
presentation without rewriting diagnostic records.
`EffectivePipelineSources` and `EffectiveCampaignSources` provide the separate ## Canonical Party And Derived Catalog
safe provenance projection for `config sources`. Pipeline ownership begins with
the complete logical field paths projected from the schema and classifies
each contributor as root, import, overlay, or centralized default. The
projection replaces generated concrete member paths with paired family and
canonical-party records, and does the same for generated publish rules.
Campaign records identify campaign-owned fields and party inputs; canonical
derived players point to the party source. The application command only joins these sorted
records with selection metadata and never reparses configuration files.
`EffectiveArtifactCatalog` projects the same finalized concrete artifact map for File-backed party loading supports imports; contextless `ParseParty` accepts
`config artifacts`. It derives source identity from each map key, carries sorted bytes. The definition checks the main version and effective roster. Native
effective dependencies, aggregates ConfigKit definition contributors, and adds source coordinates establish roster order, favoring each child's declaration.
family/character/party provenance for generated members. It does not inspect A deterministic renderer materializes canonical party YAML. The selected roster
files named after artifacts or infer another runtime graph. supplies both the players projection and concrete family members, including when
an explicit party file replaces the campaign default.
`config diff` uses a thin paired loader that performs two independent ConfigKit `ArtifactCatalog` carries derived artifacts, family/member origins, resolved
loads. When campaign dependencies, and expanded publication outputs separately from pipeline values.
resolution is needed, the command loads one selected campaign and party and Family declarations remain in the typed pipeline result. Derivation sorts
expands both effective pipelines from that same party value. The configuration family keys and character IDs, substitutes `{character_id}` in outputs,
owner projects each normalized effective mapping directly from that same typed resolves closed member variables, and checks key/output collisions and domain
projection into sorted logical paths using JSON number preservation; dependencies. Member-artifact inputs become ordinary concrete artifact sources;
mapping leaves are compared individually while sequence values remain atomic. family publish declarations become ordinary publication actions. No family
Values are compact deterministic JSON representations for command output, not wildcard matcher is added to runtime publication.
raw YAML fragments, ownership records, or secret material. A differing digest
with no projected difference is treated as an internal consistency error.
Campaign context construction reads the campaign-owned party source through Catalog listing, planning, stage execution, artifact inspection, fingerprinting,
`ParseParty`. The required canonical party retains its raw bytes and normalized and previous-session requirements consume the same derived products. Validation
roster in runtime-only `ResolvedParty` provenance. Canonical resolution creates of these products belongs to domain derivation rather than app inspection.
a deterministic `derived_from_party` players projection. The party is the only External roster shape belongs in the [party contract](../integrations/party.md).
configured roster authority; player and session-party fields are unsupported.
## Canonical Party Domain ## Safe Persistence And Semantic Resume
`ParseParty` is the package-owned boundary for parsing a party source. Its Preparation materializes standalone campaign/session/party/players inputs and
single-source ConfigKit definition disables imports and overlays, requires a secret-safe pipeline projection. The projection preserves credential names,
`schema_version` through `VersionRule`, and strictly decodes the family declarations, numeric values, and null/empty distinctions. It is a
character-keyed typed schema before applying Narratio's party-domain checks. persistence service, not a fabricated native result. An effective digest is
Successful metadata coordinates recover authored character-map order without a informational; resume compares result-affecting semantic evidence from the same
second YAML parse; class and alias slice order comes directly from typed decode. concrete products used by execution. Source arrangement, provenance, and overlay
The canonical value retains a separate exact byte copy of its source so labels alone do not invalidate work.
consumers can materialize the authored party document without reserializing it.
Its `PlayersYAML` method deterministically derives the ID-sorted, versioned
players-only projection.
An unversioned source is rejected before resolution, family expansion, or Focused configuration/application fixtures cover imports, defaults, selected
prepare-stage materialization. rosters, independent comparisons, override isolation, secret-safe persistence,
and unchanged completed configuration across domain derivation and execution.
## Validation Ownership
Configuration validation remains within `internal/config`, with the public
entry points and pipeline-domain sequencing separated from the private owners
for core pipeline/session rules, external adapters, publish/storage, Notarius,
Scriptorium, and shared scalar/path checks. These are package-local ownership
boundaries rather than extension points or a general validation framework.
Validation is read-only, fails fast, and does not define which of several
independent invalid fields is reported first. Map-backed declarations are
nevertheless traversed deterministically. Reusable domain normalization is an
explicit preceding operation for both loaded and programmatically constructed
pipelines. Notarius normalization commits canonical scalar, reference, and output
values only after the complete normalization succeeds; its validator then checks
that candidate without changing it. Scriptorium validates artifact declarations
and outputs, dependencies and inputs, variables, referenced outputs, and the final
dependency graph in deterministic artifact order.
Diagnostics identify the relevant semantic field. Merge conflicts also
retain every claiming source needed to correct an additive ownership conflict.
Complete prose, punctuation, formatting, and private validation choreography are
not compatibility contracts.
## Diagnostics And Runtime Metadata
Syntax, duplicate-key, merge, overlay, and schema failures include the
relevant source name and full field path. Additive conflicts report every
claiming source so operators can repair the split without repeatedly
rediscovering additional conflicts.
The loaded pipeline retains private runtime metadata for the absolute root
path, ordered imports, selected overlay name, source, and path, original
ConfigKit metadata and source snapshots, effective digest,
and leaf ownership. Base
leaves retain their root/import owners, replaced leaves belong to the selected
overlay, and centrally supplied values use the synthetic `default` owner. This
metadata does not participate in YAML decoding or alter the public
configuration model.
The effective digest is SHA-256 over a versioned deterministic JSON encoding of
the same typed safe projection used by show and diff. Runtime Notarius paths remain absolute for
execution, but the digest substitutes their normalized logical values captured
before root-relative resolution, so relocating an equivalent configuration
bundle does not change provenance. Because ConfigKit and resolution metadata
are private, the digest excludes source layout, overlay name, and ownership.
Configuration stores credentials as ConfigKit typed references. A successful
load resolves their values inside the opaque typed boundary, while this safe
projection serializes only `EnvName()` identities. Credential-value changes are
therefore never hashed; reference-name changes remain ordinary provenance.
The optional Notarius credential follows the same path even for disabled or
resumable extraction; normalization copies the opaque reference without reading
or resolving it again. Direct YAML serialization has a configuration-owned safe
projection so only the reference name can leave this boundary.
`recomputePipelineEffectiveDigest` is the single package-owned refresh point
for later runtime expansion.
## Test Surfaces
`pipeline_configkit_test.go` exercises real imports and fixed-path overlays,
base selection, unselected-overlay isolation, source attribution, and Narratio's
unique artifact/family base-declaration rule. Existing focused configuration
tests protect defaults, explicit-value semantics, strict decoding, validation,
metadata, and root-relative path behavior. Application configuration-loader tests protect the
single-read boundary by changing the pipeline file after its initial load and
confirming local session resolution retains the original pipeline. Other
configuration tests continue to protect defaults and validation after assembly.
`party_test.go` protects the versioned typed party schema, domain invariants,
authored character order, retained bytes, and deterministic players projection
without involving campaign or runtime wiring.
`party_resolution_test.go` protects campaign-owned party loading, canonical
input restrictions, source provenance, and virtual players input selection.
## Artifact Family Resolution
Pipeline loading retains `scriptorium.artifact_families` as a resolution-only
declaration. Once campaign party resolution establishes a canonical roster,
configuration expands families in sorted family-key and character-ID order
into ordinary `ScriptoriumArtifactConfig` values. The expansion owns the narrow
`{character_id}` output substitution, closed member-variable selectors, key and
output collision checks, and the runtime-only family-origin catalog. It then
removes family declarations from `ScriptoriumConfig`, runs ordinary Scriptorium
validation, and refreshes the effective pipeline digest. Stages and adapters
therefore receive only concrete artifact maps.
The catalog retains sorted family member keys plus family/character/source
origins and the typed dependency/publish declarations for their later owners.
`member_dependencies` add corresponding ordinary concrete dependencies, while
the family-only `narratio.member_artifact.<family>` input form is rewritten to
the matching ordinary configured-artifact source. The catalog records those
resolved dependency and input identities with their declaring family and party
member. No member-artifact source is registered as a runtime policy source.
An enabled family publish declaration expands to ordinary configured-artifact
publish rules before the existing publish and lock validators run. Runtime
publication consequently receives no family wildcard or special matcher.

View File

@@ -373,4 +373,4 @@ where the last session transition can require operator interpretation.
- Transcribe speaker state: `internal/manifest/transcribe_state.go` - Transcribe speaker state: `internal/manifest/transcribe_state.go`
- Package tests: `internal/manifest/*_test.go` - Package tests: `internal/manifest/*_test.go`
- Assembled execution behavior: `internal/app/runner_test.go`, - Assembled execution behavior: `internal/app/runner_test.go`,
`internal/app/run_stage_test.go` `internal/app/run_selection_test.go`

View File

@@ -16,7 +16,8 @@ cmd/narratio -> internal/app -> configuration and production composition
-> manifests and artifact resolution -> durable local/remote output -> manifests and artifact resolution -> durable local/remote output
``` ```
The executable delegates process behavior to the application boundary. The The executable supplies signal-aware context and caller-owned streams to the
native CommandKit application boundary. The
application resolves configuration, composes concrete collaborators, acquires application resolves configuration, composes concrete collaborators, acquires
session safety controls, and runs commands. Pipeline commands execute the session safety controls, and runs commands. Pipeline commands execute the
canonical stage sequence through adapter interfaces, while manifests record canonical stage sequence through adapter interfaces, while manifests record
@@ -26,8 +27,10 @@ The pipeline runner follows one explicit invocation lifecycle: inspect bounded
prerequisites without mutation, prepare the workspace layout, acquire one prerequisites without mutation, prepare the workspace layout, acquire one
session lock, load or create the authoritative session manifest, compose only session lock, load or create the authoritative session manifest, compose only
the collaborators needed by the selected range, execute each selected stage in the collaborators needed by the selected range, execute each selected stage in
order, and then return the summary. Cleanup, when selected, is the ordinary order, finalize terminal state, release resources, and return a possibly partial
final stage rather than runner finalization work. summary with preserved failure causes. Narrow terminal local persistence detaches
cancellation; active work retains the canceled operation context. Cleanup, when
selected, is the ordinary final stage rather than runner finalization work.
The lock remains held from manifest initialization through finalization, and a The lock remains held from manifest initialization through finalization, and a
failed stage or required manifest save prevents later stages from starting. failed stage or required manifest save prevents later stages from starting.
@@ -36,8 +39,8 @@ failed stage or required manifest save prevents later stages from starting.
| Area | Implemented owners | Responsibility | | Area | Implemented owners | Responsibility |
| --- | --- | --- | | --- | --- | --- |
| Executable | `cmd/narratio` | Process entry, standard stream wiring, argument handoff, and exit status. | | Executable | `cmd/narratio` | Process entry, standard stream wiring, argument handoff, and exit status. |
| Application orchestration | `internal/app` | Command dispatch, configuration selection, secret-file environment loading, production composition, session locking, planning, execution, restore, and user-facing reporting. | | Application orchestration | `internal/app` | Native CommandKit declarations/reporting, lazy configuration selection, secret-file environment loading, production composition, session locking, planning, execution, restore, and user-facing reporting. |
| Configuration | [`internal/config`](configuration.md) | ConfigKit-backed pipeline imports and overlays, canonical party and family expansion, strict YAML loading, defaults, normalization, session templating, and validation. | | Configuration | [`internal/config`](configuration.md) | Typed ConfigKit results and lifecycle defaults, imports/overlays, canonical party loading, separate catalog/player/publication derivation, session templating, and validation. |
| Pipeline stages | `internal/stage` | Canonical stage registry, shared stage contract, execution dependencies, and implemented stage behavior. | | Pipeline stages | `internal/stage` | Canonical stage registry, shared stage contract, execution dependencies, and implemented stage behavior. |
| External boundaries | `internal/adapters`, `internal/audio` | WhisperX HTTP, downstream subprocesses, notification, object storage, and S3 audio materialization behind Narratio contracts. | | External boundaries | `internal/adapters`, `internal/audio` | WhisperX HTTP, downstream subprocesses, notification, object storage, and S3 audio materialization behind Narratio contracts. |
| Manifests | `internal/manifest` | Durable session progress, stage transitions, validation, and atomic persistence. | | Manifests | `internal/manifest` | Durable session progress, stage transitions, validation, and atomic persistence. |
@@ -45,7 +48,7 @@ failed stage or required manifest save prevents later stages from starting.
| Previous-session cache | `internal/previouscache` | Deterministic planning and materialization requirements for configured previous-session inputs. | | Previous-session cache | `internal/previouscache` | Deterministic planning and materialization requirements for configured previous-session inputs. |
| Artifact policy | `internal/artifactpolicy` | Source and destination policy, configured artifact identity validation, and publish destination safety. | | Artifact policy | `internal/artifactpolicy` | Source and destination policy, configured artifact identity validation, and publish destination safety. |
| Shared models and file operations | `internal/artifactmodel`, `internal/contracts`, [`internal/fileops`](fileops.md) | Transcript and artifact data contracts plus atomic single-file replacement, bounded reads, workspace modes, and root-scoped cleanup helpers. | | Shared models and file operations | `internal/artifactmodel`, `internal/contracts`, [`internal/fileops`](fileops.md) | Transcript and artifact data contracts plus atomic single-file replacement, bounded reads, workspace modes, and root-scoped cleanup helpers. |
| Logging | `internal/logging` | Application logger construction and shared structured logging behavior. | | Logging | `internal/logging` | Small Narratio-owned diagnostic/progress interface adapted to the invocation reporter. |
The application boundary composes concrete implementations. Stages depend on The application boundary composes concrete implementations. Stages depend on
Narratio-level contracts; external transport and SDK details remain in Narratio-level contracts; external transport and SDK details remain in
@@ -107,7 +110,7 @@ so any earlier replacement can stale a prior cleanup result.
## Focused Documentation ## Focused Documentation
- [Configuration Internals](configuration.md): pipeline imports and overlays, - [Configuration Internals](configuration.md): pipeline imports and overlays,
field ownership, decoding, and root-relative path semantics. field ownership, decoding, and source-relative resource semantics.
- [Adapter Internals](adapters.md): external adapter boundaries, composition, - [Adapter Internals](adapters.md): external adapter boundaries, composition,
failure behavior, and test surfaces. failure behavior, and test surfaces.
- [Artifact Internals](artifacts.md): source identities, runtime catalog, - [Artifact Internals](artifacts.md): source identities, runtime catalog,
@@ -137,4 +140,4 @@ before changing behavior.
The stage registry is implemented in `internal/stage/placeholders.go` and its The stage registry is implemented in `internal/stage/placeholders.go` and its
ordering is protected by `internal/app/planner_test.go`. Cross-invocation skip, ordering is protected by `internal/app/planner_test.go`. Cross-invocation skip,
force, failure, and invalidation behavior is exercised in force, failure, and invalidation behavior is exercised in
`internal/app/runner_test.go` and `internal/app/run_stage_test.go`. `internal/app/runner_test.go` and `internal/app/run_selection_test.go`.

View File

@@ -53,7 +53,7 @@ Supported source families:
manifest record and durable output pass the configured-artifact evidence manifest record and durable output pass the configured-artifact evidence
contract; an incidental or stale canonical file is unavailable. contract; an incidental or stale canonical file is unavailable.
- validates selected artifact dependency order (cycle-safe topo ordering). - validates selected artifact dependency order (cycle-safe topo ordering).
- consumes only the concrete dependency graph finalized by configuration; - consumes only the concrete dependency graph derived in the shared domain catalog;
planning, prerequisite closure, execution, reuse, invalidation, and semantic planning, prerequisite closure, execution, reuse, invalidation, and semantic
evidence do not infer a second graph from inputs. evidence do not infer a second graph from inputs.
- resolves required/optional inputs per artifact source definition into an - resolves required/optional inputs per artifact source definition into an

View File

@@ -39,9 +39,9 @@ stage non-resumable. A failure is recorded against cleanup; publish remains
succeeded and remote current state is unchanged. On a later normal full run, succeeded and remote current state is unchanged. On a later normal full run,
valid upstream stages are skipped and cleanup is retried without republishing. valid upstream stages are skipped and cleanup is retried without republishing.
`narratio publish` selects publish only and never invokes cleanup. A bounded run `narratio run SESSION --stage publish` selects publish only and never invokes cleanup. A bounded run
through `notify` or any earlier endpoint also excludes it. Operators may run through `notify` or any earlier endpoint also excludes it. Operators may run
`narratio run-stage cleanup <session_id>` directly; missing, failed, malformed, `narratio run <session_id> --stage cleanup` directly; missing, failed, malformed,
or identity-mismatched publication evidence fails before deletion. or identity-mismatched publication evidence fails before deletion.
## Implementation And Tests ## Implementation And Tests

View File

@@ -39,8 +39,8 @@ Materialize canonical current-session inputs before processing stages.
- materializes a configured spell catalog with checksum and provenance, or - materializes a configured spell catalog with checksum and provenance, or
safely removes an obsolete canonical spell catalog and its manifest record safely removes an obsolete canonical spell catalog and its manifest record
when the effective input is omitted. when the effective input is omitted.
- copies the validated canonical party bytes unchanged and deterministically - renders standalone effective campaign, session, and canonical party documents,
generates the prepared players projection. and deterministically generates the prepared players projection.
- scans enabled configured artifact inputs for `narratio.previous_session.artifact.*` requirements. - scans enabled configured artifact inputs for `narratio.previous_session.artifact.*` requirements.
- clears managed `previous/` state on every invocation, then, when requirements exist: - clears managed `previous/` state on every invocation, then, when requirements exist:
- resolves the pointer-selected previous source through the shared resolver; - resolves the pointer-selected previous source through the shared resolver;
@@ -71,15 +71,15 @@ previous-artifact requirement set. A change reruns prepare and
stales its fixed descendants. Existing successful records without this stales its fixed descendants. Existing successful records without this
evidence rerun once when selected. evidence rerun once when selected.
Workspace, spool, and cache placement and absolute source relocation are not Workspace, spool, and cache placement are not semantic when logical selection,
semantic when logical selection, canonical names, and bytes are equivalent. canonical names, and effective bytes are equivalent.
The fingerprint deliberately does not read or rehash large audio. Prepared The fingerprint deliberately does not read or rehash large audio. Prepared
input checksums remain the content provenance. Before reusing success, prepare input checksums remain the content provenance. Before reusing success, prepare
validates every durable prepared copy and compares current stable-input bytes, validates every durable prepared copy and compares current stable-input bytes,
canonical party and derived-player bytes, local audio membership/checksums, or effective campaign/session, canonical party and derived-player bytes, local audio
S3 key/size/entity-tag identity with that provenance. Source relocation with membership/checksums, or S3 key/size/entity-tag identity with that provenance.
equivalent names and bytes remains reusable; changed or unavailable evidence Source relocation with equivalent effective documents, names, and bytes remains
causes a normal prepare rerun. reusable; changed or unavailable evidence causes a normal prepare rerun.
## Related Contracts And Tests ## Related Contracts And Tests

View File

@@ -15,8 +15,8 @@ Upload run/session outputs to object storage and atomically advance remote curre
## Outputs ## Outputs
- uploaded session manifest, declared run-local diagnostics, and selected - uploaded session manifest, prepared campaign/session/party inputs, declared
publish outputs; run-local diagnostics, and selected publish outputs;
- uploaded durable previous-session cache files when present; - uploaded durable previous-session cache files when present;
- immutable run-scoped commit manifest; and - immutable run-scoped commit manifest; and
- current commit pointer, written last. - current commit pointer, written last.
@@ -34,7 +34,10 @@ and optional rules, destination resolution, and collision inputs live in
remote verification live in `publish_transfer.go`; committed-manifest, remote verification live in `publish_transfer.go`; committed-manifest,
immutable-commit, and current-pointer encoding and writes live in immutable-commit, and current-pointer encoding and writes live in
`publish_commit.go`. `publish_output_plan.go` owns the deterministic, I/O-free `publish_commit.go`. `publish_output_plan.go` owns the deterministic, I/O-free
five-outcome model and its secret-free metadata projection. five-outcome model and its secret-free metadata projection. Prepared input
objects are committed under the immutable run; the committed standalone session
supports remote loading when no authored session override is available. The
[configuration reference](../config.md#sessionyml) owns input selection.
- when publishing or run upload is disabled, completes successfully with no - when publishing or run upload is disabled, completes successfully with no
outputs and records explanatory metadata. This is not an explicit self-skip: outputs and records explanatory metadata. This is not an explicit self-skip:
@@ -126,7 +129,7 @@ evidence does not replace those safety checks.
The commit boundary and cleanup authorization are normative architecture invariants; see The commit boundary and cleanup authorization are normative architecture invariants; see
[Architecture](../policy/architecture.md#publish-commit-boundary). [Architecture](../policy/architecture.md#publish-commit-boundary).
Publish never deletes local state. The standalone `publish` command selects Publish never deletes local state. `run SESSION --stage publish` selects
only this stage; a full run selects notify and cleanup afterward. only this stage; a full run selects notify and cleanup afterward.
## Related Contracts And Tests ## Related Contracts And Tests

View File

@@ -72,7 +72,7 @@ The canonical cleanup stage:
republishing. republishing.
Manual cleanup uses the same root-confined deletion mechanism. Invocation Manual cleanup uses the same root-confined deletion mechanism. Invocation
syntax and exact deletion scope belong in [CLI](../cli.md#clean) and syntax and exact deletion scope belong in [CLI](../cli.md#session-clean) and
[Operations](../operations.md#cleanup). [Operations](../operations.md#cleanup).
## Invariants ## Invariants

View File

@@ -6,17 +6,13 @@ For command syntax, see [docs/cli.md](./cli.md). For field-level config, see [do
## Campaign and Session Selection ## Campaign and Session Selection
Campaign selection priority: Identity and exact-file selection are complementary: a selected file supplies
configuration and an explicit ID asserts its effective identity. Session domain
- `--campaign-file` commands take positional identity; `--session-file` selects its source. An
- `--campaign` explicit `--party-file` supplies the roster consistently across consumers.
- `pipeline.campaigns.default_campaign_id` See [CLI selectors](cli.md#configuration-selectors) and
[configuration discovery](config.md#discovery-and-selection) for selection rules.
Session source priority: Existing scripts should follow the [CLI migration table](cli.md#migration-from-the-previous-cli).
- `--session`
- local default search paths
- remote session object (S3) when local session file is not found and storage is configured
## Session Initialization ## Session Initialization
@@ -70,21 +66,19 @@ narratio run 2026-04-04
narratio session status 2026-04-04 narratio session status 2026-04-04
``` ```
Run, plan, and status output identify the resolved pipeline overlay (or `none`) Status distinguishes currently resolved configuration provenance from the last
and effective configuration digest. Status distinguishes the current resolved persisted configuration, helping diagnose overlay switches without changing
value from the last value persisted in the session manifest, which helps semantic resume authority. Run and plan reports describe execution and decisions;
diagnose overlay switches without changing resume authority. see the [report fields](cli.md#public-domain-report-fields).
Before switching an operational overlay, compare its effective meaning with the Before switching an operational overlay, compare its effective configuration
production base through `narratio config diff default <overlay>`. with the base through `narratio config diff --against-overlay NAME`. When using an
The command is read-only and succeeds whether it finds differences or not. Its explicit root, supply it with both `--config` and `--against-config`. Each side
sorted records describe defaulted, expanded concrete configuration—not source loads independently using its own defaults. Native inspection retains authored
file layout—so it can be used to review model, artifact, and publish changes family declarations; use `narratio artifacts list` to review concrete identities,
without creating a session or run. Use `narratio config artifacts` to review the outputs, dependencies, and selected-party members. See
concrete artifact identities, definitions, outputs, and dependencies. Select the [configuration inspection](cli.md#configuration-inspection) for selection and
same campaign explicitly when overlays could resolve different campaign paths; comparison details.
see the [CLI reference](cli.md#config-validate-config-show-config-sources-config-artifacts-and-config-diff)
for syntax and record format.
## Stage Execution and Continuation Behavior ## Stage Execution and Continuation Behavior
@@ -148,7 +142,7 @@ the stage self-skip.
Single-stage execution: Single-stage execution:
```bash ```bash
narratio run-stage normalize 2026-04-04 --force narratio run 2026-04-04 --stage normalize --force
``` ```
Contiguous bounded execution uses inclusive canonical endpoints: Contiguous bounded execution uses inclusive canonical endpoints:
@@ -199,7 +193,7 @@ canonical `transcripts/raw/<speaker>.json` files remain durable, however.
After correcting the underlying problem, retry normally: After correcting the underlying problem, retry normally:
```bash ```bash
narratio run-stage transcribe 2026-04-04 narratio run 2026-04-04 --stage transcribe
``` ```
Narratio hashes the current prepared audio, validates recorded transcript JSON, Narratio hashes the current prepared audio, validates recorded transcript JSON,
@@ -213,7 +207,7 @@ a WhisperX model or private server-side configuration changes behind the same
URL and language: URL and language:
```bash ```bash
narratio run-stage transcribe 2026-04-04 --force narratio run 2026-04-04 --stage transcribe --force
``` ```
Force durably clears the reusable collection before sending requests. If that Force durably clears the reusable collection before sending requests. If that
@@ -242,21 +236,21 @@ Choose the narrowest workflow that matches the intended replacement:
| Intent | Command | Preserved and rebuilt state | | Intent | Command | Preserved and rebuilt state |
| --- | --- | --- | | --- | --- | --- |
| Rebuild analysis only | [`narratio analyze 2026-04-04`](./cli.md#analyze) | Preserves transcripts and the current extraction bundle; force-runs selected analysis artifacts and their required analysis prerequisites. | | Rebuild analysis only | [`narratio run 2026-04-04 --stage analyze --force`](./cli.md#run) | Preserves transcripts and the current extraction bundle; force-runs selected analysis artifacts and their required analysis prerequisites. |
| Rebuild extraction and analysis | [`narratio regenerate-artifacts 2026-04-04`](./cli.md#regenerate-artifacts) | Preserves transcripts; force-runs the complete configured extraction bundle, then selected analysis. `--artifacts` narrows analysis only. | | Rebuild extraction and analysis | [`narratio artifacts regenerate 2026-04-04`](./cli.md#artifacts-regenerate) | Preserves transcripts; force-runs the complete configured extraction bundle, then selected analysis. `--artifacts` narrows analysis only. |
| Continue bounded work normally | [`narratio run 2026-04-04 --from extract --through analyze`](./cli.md#run) | Uses ordinary resume decisions: current extraction and analysis can be skipped, while incomplete or obsolete work runs. | | Continue bounded work normally | [`narratio run 2026-04-04 --from extract --through analyze`](./cli.md#run) | Uses ordinary resume decisions: current extraction and analysis can be skipped, while incomplete or obsolete work runs. |
All three stop before publication. Inspect the results and run All three stop before publication. Inspect the results and run
[`narratio publish`](./cli.md#publish) separately when delivery is intended. [`narratio run SESSION --stage publish --force`](./cli.md#run) separately when delivery is intended.
For the extraction-plus-analysis development loop, use: For the extraction-plus-analysis development loop, use:
```bash ```bash
narratio regenerate-artifacts 2026-04-04 narratio artifacts regenerate 2026-04-04
narratio regenerate-artifacts 2026-04-04 --artifacts session_recap,player_handout narratio artifacts regenerate 2026-04-04 --artifacts session_recap,player_handout
``` ```
This command is a transparent expansion to a forced bounded `run` from This command shares the forced bounded execution operation from
`extract` through `analyze`. Extraction always rebuilds its complete configured `extract` through `analyze`. Extraction always rebuilds its complete configured
bundle. Analysis rebuilds the selected targets and their required analysis bundle. Analysis rebuilds the selected targets and their required analysis
prerequisites, or uses the normal default selection when no artifact names are prerequisites, or uses the normal default selection when no artifact names are
@@ -268,7 +262,7 @@ set is ready:
```bash ```bash
narratio session artifacts 2026-04-04 narratio session artifacts 2026-04-04
narratio publish 2026-04-04 narratio run 2026-04-04 --stage publish --force
``` ```
If planning or execution reports stale, missing, failed, or tampered If planning or execution reports stale, missing, failed, or tampered
@@ -352,8 +346,9 @@ not create a separate workspace or retain a separate current extraction result.
Narratio cannot observe edits inside Notarius configuration behind an unchanged Narratio cannot observe edits inside Notarius configuration behind an unchanged
selector. Force extraction after such an edit when a replacement is intended. selector. Force extraction after such an edit when a replacement is intended.
Use `regenerate-artifacts` when both extraction and analysis must be rebuilt; Use `artifacts regenerate` when both extraction and analysis must be rebuilt;
use `analyze` when the existing extraction bundle should be preserved. Field use `run SESSION --stage analyze --force` when the existing extraction bundle
should be preserved. Field
semantics belong in [Configuration](./config.md#notarius-configuration-overlay), semantics belong in [Configuration](./config.md#notarius-configuration-overlay),
with Audita selectors covered under with Audita selectors covered under
[Audita selection and credentials](./config.md#audita-selection-and-credentials). [Audita selection and credentials](./config.md#audita-selection-and-credentials).
@@ -367,13 +362,13 @@ concrete character artifact. Select a concrete generated key to operate on one
member only. Manifests and plan output retain the concrete key as the durable member only. Manifests and plan output retain the concrete key as the durable
identity and include the family and character ID as optional provenance. identity and include the family and character ID as optional provenance.
`--artifacts` can be used on `run`, `session plan`, `run-stage`, `analyze`, and `--artifacts` can be used on `run`, `session plan`, and
`publish`. For a bounded run or plan, the selected range must contain `analyze` `artifacts regenerate`. For a bounded run or plan, the selected range must contain `analyze`
or `publish`. or `publish`.
Selection behavior: Selection behavior:
- validates names against `pipeline.scriptorium.artifacts`; - validates names against the derived concrete catalog and family selections;
- selects explicit analyze targets and permits their required configured - selects explicit analyze targets and permits their required configured
prerequisites to be reused or rebuilt first; prerequisites to be reused or rebuilt first;
- filters publish rules for `narratio.artifact.<name>` sources only; - filters publish rules for `narratio.artifact.<name>` sources only;
@@ -429,7 +424,7 @@ prepared file is missing or inconsistent with its manifest checksum, repair
the source configuration and refresh prepared state first: the source configuration and refresh prepared state first:
```bash ```bash
narratio run-stage prepare 2026-04-04 --force narratio run 2026-04-04 --stage prepare --force
``` ```
Starting a replacement clears the previous extraction payload from the current Starting a replacement clears the previous extraction payload from the current
@@ -538,7 +533,7 @@ contract](./integrations/audita.md) for report placement and limits.
Narratio's polish resume evidence tracks selected config path, Audita overlay, Narratio's polish resume evidence tracks selected config path, Audita overlay,
profiles, ordered modules, description, schema, and output identity. Editing profiles, ordered modules, description, schema, and output identity. Editing
Audita-owned files behind unchanged selectors is invisible to Narratio; force Audita-owned files behind unchanged selectors is invisible to Narratio; force
polish with `narratio run-stage polish <session-id> --force` after such edits. polish with `narratio run <session-id> --stage polish --force` after such edits.
## External Command Lifecycle ## External Command Lifecycle
@@ -581,7 +576,7 @@ the committed manifest and declared transcript/artifact objects.
To intentionally replace the current extraction result, run: To intentionally replace the current extraction result, run:
```bash ```bash
narratio run-stage extract 2026-04-04 --force narratio run 2026-04-04 --stage extract --force
``` ```
Narratio automatically reruns extraction when its recorded invocation contract, Narratio automatically reruns extraction when its recorded invocation contract,
@@ -610,22 +605,18 @@ before commit selection.
Run publish only: Run publish only:
```bash ```bash
narratio publish 2026-04-04 narratio run 2026-04-04 --stage publish --force
``` ```
Equivalent: This selection stops after publish and does not invoke cleanup. A
```bash
narratio run-stage publish 2026-04-04 --force
```
This standalone command stops after publish and does not invoke cleanup. A
default full `run` continues through notify and cleanup. default full `run` continues through notify and cleanup.
Publish commit model: Publish commit model:
- uploads eligible run files under `{session_prefix}/runs/{run_id}/`, excluding - uploads eligible run files under `{session_prefix}/runs/{run_id}/`, excluding
audio and the run-local Notarius staging bundle; audio and the run-local Notarius staging bundle;
- uploads prepared campaign, session, and party documents under the run's
`prepare/inputs/` prefix, when recorded by the manifest;
- uploads configured published outputs and `previous/**` cache files into the - uploads configured published outputs and `previous/**` cache files into the
same immutable run scope, including only explicitly configured extraction same immutable run scope, including only explicitly configured extraction
lanes; lanes;
@@ -687,7 +678,7 @@ Operational rules:
Examples: Examples:
```bash ```bash
narratio session locks 2026-04-04 narratio session locks list 2026-04-04
narratio session locks add 2026-04-04 narratio.artifact.session_recap --reason "manual edits" --force narratio session locks add 2026-04-04 narratio.artifact.session_recap --reason "manual edits" --force
narratio session locks remove 2026-04-04 narratio.artifact.session_recap narratio session locks remove 2026-04-04 narratio.artifact.session_recap
``` ```
@@ -714,8 +705,8 @@ plan, so it is not a network-free operation.
Default restore scope: Default restore scope:
- the committed session manifest and the committed transcript/artifact objects - the committed session manifest, prepared campaign/session/party documents,
declared by the selected remote commit and transcript/artifact objects declared by the selected remote commit
- `previous/**` when needed by configured previous-session artifact inputs; - `previous/**` when needed by configured previous-session artifact inputs;
each is selected from its exact committed `published_output` declaration each is selected from its exact committed `published_output` declaration
@@ -821,7 +812,7 @@ ConfigKit.
Every pipeline-loading command bootstraps credentials once, before the first Every pipeline-loading command bootstraps credentials once, before the first
configuration load and before any adapter is constructed. `--secrets-dir` configuration load and before any adapter is constructed. `--secrets-dir`
selects an explicit directory (relative paths use caller CWD). Otherwise a selects an explicit directory (relative paths use caller CWD). Otherwise a
present `secrets/` beside the resolved root pipeline is used, while an absent present `/usr/local/etc/narratio/secrets` directory is used, while an absent
conventional directory is skipped. Explicit missing/empty selections and conventional directory is skipped. Explicit missing/empty selections and
invalid existing directories fail the command. ConfigKit follows a symlink used invalid existing directories fail the command. ConfigKit follows a symlink used
as the selected directory, but immediate entries must be regular non-symlink as the selected directory, but immediate entries must be regular non-symlink
@@ -845,20 +836,20 @@ the session workload.
Session-scoped cleanup: Session-scoped cleanup:
```bash ```bash
narratio clean 2026-04-04 narratio session clean 2026-04-04
``` ```
Global cleanup: Global cleanup:
```bash ```bash
narratio clean --all narratio session clean --all
``` ```
Dry-run and cache variants: Dry-run and cache variants:
```bash ```bash
narratio clean 2026-04-04 --dry-run --clear-cache narratio session clean 2026-04-04 --dry-run --clear-cache
narratio clean --all --dry-run --clear-cache narratio session clean --all --dry-run --clear-cache
``` ```
Rules: Rules:
@@ -877,9 +868,9 @@ Cleanup derives only the configured run-scoped spool and workspace targets,
uses root-confined deletion, and does not read or mutate object storage. A uses root-confined deletion, and does not read or mutate object storage. A
failure leaves publish succeeded and the remote committed snapshot current. failure leaves publish succeeded and the remote committed snapshot current.
Retry with a normal full run: valid upstream work, including publish and notify, Retry with a normal full run: valid upstream work, including publish and notify,
is skipped while the failed cleanup stage runs again. `run-stage cleanup` is is skipped while the failed cleanup stage runs again. `run SESSION --stage cleanup` is
also available when the manifest has valid publish evidence. A range ending at also available when the manifest has valid publish evidence. A range ending at
`notify` or earlier and the standalone `publish` command never delete local `notify` or earlier and `run SESSION --stage publish` never delete local
state. state.
Older local manifests that contain the retired cleanup-obligation field are Older local manifests that contain the retired cleanup-obligation field are
@@ -898,3 +889,9 @@ normal migration path.
- Restore requires configured object storage and committed remote current state. - Restore requires configured object storage and committed remote current state.
- Pipeline-loading commands bootstrap filesystem secrets once before configuration - Pipeline-loading commands bootstrap filesystem secrets once before configuration
resolution and object-store initialization. resolution and object-store initialization.
Console progress and informational diagnostics use native invocation visibility.
`--progress` shows work without requiring verbose mode; `--verbose` adds source
and decision context. Console `--debug` does not enable downstream debug capture
or change retention. Downstream streams stay in captured logs. See
[CLI reporting](cli.md#reporting-and-visibility) for mode combinations and formats.

View File

@@ -11,14 +11,14 @@ Copyright (C) 2026 Eric Rakestraw
SPDX-License-Identifier: CC-BY-SA-4.0 SPDX-License-Identifier: CC-BY-SA-4.0
License and notices: [CC BY-SA 4.0](licenses/CC-BY-SA-4.0.txt) | License and notices: [CC BY-SA 4.0](licenses/CC-BY-SA-4.0.txt) |
[COPYRIGHT](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/COPYRIGHT) | [COPYRIGHT](https://gitea.maximumdirect.net/eric/policy/src/commit/593c9b52273c5c879785ae9e995d21026df467b4/COPYRIGHT) |
[LICENSE](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/LICENSE). [LICENSE](https://gitea.maximumdirect.net/eric/policy/src/commit/593c9b52273c5c879785ae9e995d21026df467b4/LICENSE).
[Source](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843). [Source](https://gitea.maximumdirect.net/eric/policy/src/commit/593c9b52273c5c879785ae9e995d21026df467b4).
## ConfigKit ## ConfigKit
Selected module: `gitea.maximumdirect.net/eric/ConfigKit` at `v0.4.2`. Selected module: `go.maximumdirect.net/configkit` at `v1.2.1`.
Copyright (C) 2026 Eric Rakestraw Copyright (C) 2026 Eric Rakestraw
@@ -26,10 +26,68 @@ SPDX-License-Identifier: LGPL-3.0-or-later
License and notices: [LGPL 3.0](licenses/LGPL-3.0.txt) | License and notices: [LGPL 3.0](licenses/LGPL-3.0.txt) |
[GPL 3.0](licenses/GPL-3.0.txt) | [GPL 3.0](licenses/GPL-3.0.txt) |
[COPYRIGHT](https://gitea.maximumdirect.net/eric/ConfigKit/src/commit/67c03690181c5af8dde6be325abac241dae6732f/COPYRIGHT) | [COPYRIGHT](https://forge.maximumdirect.net/base-layer/configkit/src/commit/51ef3144158db1a09fabdbd1c7ae59908c84923b/COPYRIGHT) |
[LICENSE](https://gitea.maximumdirect.net/eric/ConfigKit/src/commit/67c03690181c5af8dde6be325abac241dae6732f/LICENSE). [LICENSE](https://forge.maximumdirect.net/base-layer/configkit/src/commit/51ef3144158db1a09fabdbd1c7ae59908c84923b/LICENSE).
[Source](https://gitea.maximumdirect.net/eric/ConfigKit/src/commit/67c03690181c5af8dde6be325abac241dae6732f). [Source](https://forge.maximumdirect.net/base-layer/configkit/src/commit/51ef3144158db1a09fabdbd1c7ae59908c84923b).
## CommandKit
Selected module: `go.maximumdirect.net/commandkit` at `v0.7.0`.
Copyright (C) 2026 Eric Rakestraw
SPDX-License-Identifier: LGPL-3.0-or-later
License and notices: [LGPL 3.0](licenses/LGPL-3.0.txt) |
[GPL 3.0](licenses/GPL-3.0.txt) |
[COPYRIGHT](https://forge.maximumdirect.net/base-layer/commandkit/src/commit/b57bfe176cff05a892e6cb07ebb5f350239e55d4/COPYRIGHT) |
[LICENSE](https://forge.maximumdirect.net/base-layer/commandkit/src/commit/b57bfe176cff05a892e6cb07ebb5f350239e55d4/LICENSE).
[Source](https://forge.maximumdirect.net/base-layer/commandkit/src/commit/b57bfe176cff05a892e6cb07ebb5f350239e55d4).
## CommandKit ckconfig
Selected module: `go.maximumdirect.net/ckconfig` at `v0.9.0`.
Copyright (C) 2026 Eric Rakestraw
SPDX-License-Identifier: LGPL-3.0-or-later
License and notices: [LGPL 3.0](licenses/LGPL-3.0.txt) |
[GPL 3.0](licenses/GPL-3.0.txt) |
[COPYRIGHT](https://forge.maximumdirect.net/base-layer/commandkit/src/commit/9962368f0c1ea1f6ad010638e94621091105d745/integrations/ckconfig/COPYRIGHT) |
[LICENSE](https://forge.maximumdirect.net/base-layer/commandkit/src/commit/9962368f0c1ea1f6ad010638e94621091105d745/integrations/ckconfig/LICENSE).
[Source](https://forge.maximumdirect.net/base-layer/commandkit/src/commit/9962368f0c1ea1f6ad010638e94621091105d745).
## Cobra
Selected module: `github.com/spf13/cobra` at `v1.10.2` (transitive dependency).
Copyright 2013-2023 The Cobra Authors
SPDX-License-Identifier: Apache-2.0
License and notices: [Apache 2.0](licenses/Apache-2.0.txt) |
[LICENSE.txt](https://github.com/spf13/cobra/blob/88b30ab89da2d0d0abb153818746c5a2d30eccec/LICENSE.txt).
[Source](https://github.com/spf13/cobra/commit/88b30ab89da2d0d0abb153818746c5a2d30eccec).
## pflag
Selected module: `github.com/spf13/pflag` at `v1.1.0` (transitive dependency).
Copyright (c) 2012 Alex Ogier. All rights reserved.
Copyright (c) 2012 The Go Authors. All rights reserved.
SPDX-License-Identifier: BSD-3-Clause
License and notices: [BSD 3-Clause](licenses/BSD-3-Clause.txt) |
[LICENSE](https://github.com/spf13/pflag/blob/f8a990678a6d44385313e9b19e40737f889f9b14/LICENSE).
[Source](https://github.com/spf13/pflag/commit/f8a990678a6d44385313e9b19e40737f889f9b14).
## YAML v3 ## YAML v3
@@ -54,7 +112,7 @@ License and notices: [MIT](licenses/MIT.txt) |
## YAML v4 ## YAML v4
Selected module: `go.yaml.in/yaml/v4` at `v4.0.0-rc.6`. Selected module: `go.yaml.in/yaml/v4` at `v4.0.0`.
Copyright 2006-2010 Kirill Simonov Copyright 2006-2010 Kirill Simonov
@@ -66,10 +124,10 @@ SPDX-License-Identifier: MIT AND Apache-2.0
License and notices: [MIT](licenses/MIT.txt) | License and notices: [MIT](licenses/MIT.txt) |
[Apache 2.0](licenses/Apache-2.0.txt) | [Apache 2.0](licenses/Apache-2.0.txt) |
[LICENSE](https://github.com/yaml/go-yaml/blob/1c17b9cee72bf81ae73a8be50fbd7dd3a9985125/LICENSE) | [LICENSE](https://github.com/yaml/go-yaml/blob/f2f9563503f11b7a60da0c532175dcc693ce8d5a/LICENSE) |
[NOTICE](https://github.com/yaml/go-yaml/blob/1c17b9cee72bf81ae73a8be50fbd7dd3a9985125/NOTICE). [NOTICE](https://github.com/yaml/go-yaml/blob/f2f9563503f11b7a60da0c532175dcc693ce8d5a/NOTICE).
[Source](https://github.com/yaml/go-yaml/commit/1c17b9cee72bf81ae73a8be50fbd7dd3a9985125). [Source](https://github.com/yaml/go-yaml/commit/f2f9563503f11b7a60da0c532175dcc693ce8d5a).
## go-cmp ## go-cmp
@@ -114,18 +172,18 @@ License and notices: [BSD 3-Clause](licenses/BSD-3-Clause.txt) |
## Go runtime and standard library ## Go runtime and standard library
Material: Go `1.26.7` runtime and standard library material incorporated in Material: Go `1.27.4` runtime and standard library material incorporated in
release binaries built with the declared `golang:1.26.7` CI toolchain. release binaries built with the declared `golang:1.27.4` CI toolchain.
Copyright 2009 The Go Authors. Copyright 2009 The Go Authors.
SPDX-License-Identifier: BSD-3-Clause SPDX-License-Identifier: BSD-3-Clause
License and notices: [BSD 3-Clause](licenses/BSD-3-Clause.txt) | License and notices: [BSD 3-Clause](licenses/BSD-3-Clause.txt) |
[LICENSE](https://github.com/golang/go/blob/e3336a22ad3f0a90bd252c95d8b5544e02674205/LICENSE) | [LICENSE](https://github.com/golang/go/blob/7b2881024c95a11ddb86663a616340aa3a88b67f/LICENSE) |
[PATENTS](https://github.com/golang/go/blob/e3336a22ad3f0a90bd252c95d8b5544e02674205/PATENTS). [PATENTS](https://github.com/golang/go/blob/7b2881024c95a11ddb86663a616340aa3a88b67f/PATENTS).
[Source](https://github.com/golang/go/commit/e3336a22ad3f0a90bd252c95d8b5544e02674205). [Source](https://github.com/golang/go/commit/7b2881024c95a11ddb86663a616340aa3a88b67f).
## AWS SDK for Go v2 ## AWS SDK for Go v2

View File

@@ -2,9 +2,9 @@
**Base Policy Version:** 1.3 **Base Policy Version:** 1.3
**Last Updated**: 2026-09-28 **Last Updated**: 2026-11-17
**Upstream Source**: https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/docs/policy/agents.md **Upstream Source**: https://gitea.maximumdirect.net/eric/policy/src/commit/593c9b52273c5c879785ae9e995d21026df467b4/docs/policy/agents.md
## Purpose ## Purpose

View File

@@ -2,9 +2,9 @@
**Base Policy Version:** 1.3 **Base Policy Version:** 1.3
**Last Updated**: 2026-09-28 **Last Updated**: 2026-11-19
**Upstream Source**: https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/docs/policy/architecture.md **Upstream Source**: https://gitea.maximumdirect.net/eric/policy/src/commit/593c9b52273c5c879785ae9e995d21026df467b4/docs/policy/architecture.md
## Purpose And Ownership ## Purpose And Ownership
@@ -52,7 +52,7 @@ their domains:
- Notarius extracts validated structured artifact bundles; and - Notarius extracts validated structured artifact bundles; and
- Scriptorium executes prompts and produces configured artifacts. - Scriptorium executes prompts and produces configured artifacts.
Narratio owns orchestration, configuration resolution, session and run state, Narratio owns orchestration, configuration interpretation, session and run state,
artifact and path modeling, manifest persistence, stage sequencing, resume, artifact and path modeling, manifest persistence, stage sequencing, resume,
restore, cleanup gates, and publish semantics. External contracts are defined restore, cleanup gates, and publish semantics. External contracts are defined
in the [integration documentation](../integrations/). in the [integration documentation](../integrations/).
@@ -73,7 +73,7 @@ itself an architectural goal.
## Ownership And Dependency Direction ## Ownership And Dependency Direction
The application boundary owns command dispatch, configuration selection, The application boundary owns command composition, configuration selection,
production composition, session locking, and top-level lifecycle. It may depend production composition, session locking, and top-level lifecycle. It may depend
on concrete implementations to assemble a run. on concrete implementations to assemble a run.
@@ -172,18 +172,30 @@ or other non-regular conflict into a successful restore.
## Configuration ## Configuration
Configuration is strict, explicit, centralized, and operator-oriented. Configuration ownership follows
[ADR 0003](../adr/0003-assign-configuration-ownership.md):
- ConfigKit owns configuration policy and resolution through the final handoff.
Narratio supplies its schema, defaults, and configuration rules through
supported extension points. The completed ConfigKit result is authoritative.
- Narratio consumes that result without mutation and derives separate domain
objects. It must not construct a replacement effective configuration.
- CommandKit owns CLI mechanics and presentation; `ckconfig` exposes ConfigKit
inspection. Narratio supplies selection and acquisition wiring through native
adapters without changing upstream semantics or substituting inspection views.
Missing configuration or inspection capabilities are addressed upstream.
- YAML decoding rejects unknown fields. - YAML decoding rejects unknown fields.
- Defaults are centralized and testable. - Defaults are centralized and testable.
- Empty configured values do not silently replace meaningful defaults. - Defaults apply only to absent fields. Explicit false, zero, empty, and null
values remain present and are evaluated by Narratio's domain rules.
- Validation rejects invalid configuration before stage execution where - Validation rejects invalid configuration before stage execution where
practical. practical.
- Root-owned imports and one selected overlay resolve deterministically through - ConfigKit resolves local imports and the selected pipeline overlay.
the configuration owner; commands do not implement their own merge rules. - Canonical party rosters are campaign-owned inputs. Narratio derives players
- Canonical party rosters are campaign-owned. Their derived players projection projections and concrete character-family artifacts as separate domain
and concrete character-family artifacts are resolved before runtime stages objects before execution, without modifying configuration.
or adapters receive configuration.
- Resume uses stage- or artifact-owned semantic evidence for observable - Resume uses stage- or artifact-owned semantic evidence for observable
result-affecting configuration; overlay identity and an effective digest are result-affecting configuration; overlay identity and an effective digest are
provenance, never blanket cache keys. provenance, never blanket cache keys.
@@ -253,7 +265,7 @@ rereads remote storage. A cleanup failure makes the invocation incomplete while
leaving publish succeeded and the committed remote snapshot authoritative. A leaving publish succeeded and the committed remote snapshot authoritative. A
normal later full run reuses valid upstream stages and retries cleanup. normal later full run reuses valid upstream stages and retries cleanup.
The standalone `publish` command selects only publish and therefore never `run SESSION --stage publish` selects only publish and therefore never
invokes cleanup. Operators may select cleanup directly only when the manifest invokes cleanup. Operators may select cleanup directly only when the manifest
contains valid successful publication evidence. contains valid successful publication evidence.

View File

@@ -1,15 +1,15 @@
# Documentation Policy # Documentation Policy
**Base Policy Version:** 1.11 **Base Policy Version:** 1.12
**Last Updated**: 2026-09-28 **Last Updated**: 2026-11-17
**Upstream Source**: https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/docs/policy/documentation.md **Upstream Source**: https://gitea.maximumdirect.net/eric/policy/src/commit/593c9b52273c5c879785ae9e995d21026df467b4/docs/policy/documentation.md
## Purpose ## Purpose
This policy assigns each documentation topic to one canonical owner. Its goal is This policy assigns each documentation topic to one canonical owner. Its goal is
to keep Narratio's documentation accurate, concise, discoverable, and resistant to keep this application's documentation accurate, concise, discoverable, and resistant
to drift for users, operators, developers, integrators, and LLM coding agents. to drift for users, operators, developers, integrators, and LLM coding agents.
## Core Rules ## Core Rules
@@ -75,19 +75,19 @@ secret values.
| Release policy | `docs/policy/release.md` | Versioning, compatibility, release integrity and immutability, release documentation, proportionate gates, publication controls, completion, and required versus optional checks. | Repository-specific commands, product installation guidance, CLI version semantics, historical release summaries, and CI implementation detail. | | Release policy | `docs/policy/release.md` | Versioning, compatibility, release integrity and immutability, release documentation, proportionate gates, publication controls, completion, and required versus optional checks. | Repository-specific commands, product installation guidance, CLI version semantics, historical release summaries, and CI implementation detail. |
| Open source licensing and attribution policy | `docs/policy/oss.md` | License defaults and author choices, COPYRIGHT and attribution formats, license/notice links, discoverability, maintenance, and concrete exceptions. | Component entries, license texts, release commands, and dependency security review. | | Open source licensing and attribution policy | `docs/policy/oss.md` | License defaults and author choices, COPYRIGHT and attribution formats, license/notice links, discoverability, maintenance, and concrete exceptions. | Component entries, license texts, release commands, and dependency security review. |
| Project copyright and license grant | `COPYRIGHT` | Project identity, copyright holders and years, SPDX expression, grant, warranty disclaimer, and third-party statement. | Complete license texts and upstream component attribution. | | Project copyright and license grant | `COPYRIGHT` | Project identity, copyright holders and years, SPDX expression, grant, warranty disclaimer, and third-party statement. | Complete license texts and upstream component attribution. |
| Project license text | `LICENSE` | Complete GPLv3 project license text. | Companion dependency license texts and upstream component attribution. | | Project license texts | `LICENSE` | Complete project and incorporated companion license texts, with required project-specific fields. | General licensing policy and upstream component attribution. |
| Upstream component attribution | `docs/oss/attribution.md` | House Format component entries: identity, material scope and modifications where applicable, copyright, license, required notices, and license, notice, and source links. | General attribution policy, exception reasoning, research narratives, compliance commentary, and complete standard license texts. | | Upstream component attribution | `docs/oss/attribution.md` | House Format component entries: identity, material scope and modifications where applicable, copyright, license, required notices, and license, notice, and source links. | General attribution policy, exception reasoning, research narratives, compliance commentary, and complete standard license texts. |
| Standard dependency license texts | `docs/oss/licenses/` | Complete, verbatim standard license texts shared by applicable entries. | Project-specific upstream notices, attribution prose, and policy interpretation. | | Standard dependency license texts | `docs/oss/licenses/` | Complete, verbatim standard license texts shared by applicable entries. | Project-specific upstream notices, attribution prose, and policy interpretation. |
| Repository-specific release procedure | `docs/release.md` | Maintainer prerequisites, candidate preparation, validation and publication commands and automated guards, asynchronous deliverables, delivery status, optional consumer verification, and recovery. | General release requirements, product installation guidance, historical release summaries, and current compatibility contracts. | | Repository-specific release procedure | `docs/release.md` | Maintainer prerequisites, candidate preparation, validation and publication commands and automated guards, asynchronous deliverables, delivery status, optional consumer verification, and recovery. | General release requirements, product installation guidance, historical release summaries, and current compatibility contracts. |
| CLI contract (if applicable) | `docs/cli.md` | Commands, arguments, flags, invocation semantics, and exit codes. | End-to-end operating procedures, configuration field definitions, runtime filesystem layout, module implementation details. | | CLI contract (if applicable) | `docs/cli.md` | Commands, arguments, flags, invocation semantics, and exit codes. | End-to-end operating procedures, configuration field definitions, runtime filesystem layout, module implementation details. |
| Configuration contract (if applicable) | `docs/config.md` | Discovery, precedence, schema, fields, defaults, environment overrides, validation, and selectable module and validator keys. | Complete example files, CLI syntax, runtime state lifecycle, module implementation details. | | Configuration contract (if applicable) | `docs/config.md` | Discovery, precedence, schema, fields, defaults, environment overrides, validation, and selectable module and validator keys. | Complete example files, CLI syntax, runtime state lifecycle, module implementation details. |
| Operations | `docs/operations.md` | Runtime workflows, physical filesystem and state layout, output, cache and debug handling, resume, cleanup, permissions, recovery, and limits. | CLI flag syntax, configuration field definitions, logical output schemas, implementation mechanics. | | Operations (if applicable) | `docs/operations.md` | Runtime workflows, physical filesystem and state layout, output, cache and debug handling, resume, cleanup, permissions, recovery, and limits. | CLI flag syntax, configuration field definitions, logical output schemas, implementation mechanics. |
| Troubleshooting | `docs/troubleshooting.md` | Symptom-driven diagnosis, likely causes, safe inspection, and remedies. | Canonical commands, configuration definitions, operational procedures, and integration contracts. | | Troubleshooting | `docs/troubleshooting.md` | Symptom-driven diagnosis, likely causes, safe inspection, and remedies. | Canonical commands, configuration definitions, operational procedures, and integration contracts. |
| Integration contracts for external components (if applicable) | `docs/integrations/` | External formats and protocols, upstream and downstream contracts, logical output paths and schemas, media types, and compatibility. | Physical runtime placement and lifecycle, internal transformations, CLI syntax, configuration defaults. | | Integration contracts for external components (if applicable) | `docs/integrations/` | External formats and protocols, upstream and downstream contracts, logical output paths and schemas, media types, and compatibility. | Physical runtime placement and lifecycle, internal transformations, CLI syntax, configuration defaults. |
| Inventory of implemented internal packages | `docs/internal/overview.md` | Implemented packages and components, responsibilities, and links to focused internal docs. | Normative architecture, contributor reading policy, external contracts. | | Inventory of implemented internal packages | `docs/internal/overview.md` | Implemented packages and components, responsibilities, and links to focused internal docs. | Normative architecture, contributor reading policy, external contracts. |
| Behavior and architecture of internal packages | Other files under `docs/internal/` | Implementation flow, collaborators, state transitions, package-local guarantees and failures, and relevant tests. | Global architecture invariants, configuration definitions and defaults, external schemas, operator procedures. | | Behavior and architecture of internal packages | Other files under `docs/internal/` | Implementation flow, collaborators, state transitions, package-local guarantees and failures, and relevant tests. | Global architecture invariants, configuration definitions and defaults, external schemas, operator procedures. |
| Architectural decision records | `docs/adr/` | Significant decisions, context, alternatives, rationale, consequences, and supersession history. | Current behavior reference, implementation status, task sequencing. | | Architectural decision records | `docs/adr/` | Records of significant architectural decisions and supporting rationale. | Ordinary design choices, current behavior reference, implementation status, task sequencing. |
| Future work and implementation status | `docs/roadmap/` | Proposed, accepted, deferred, or rejected work; implementation status, sequencing, and task breakdowns. | Implemented behavior reference and architectural decision rationale. | | Future work and implementation status | `docs/roadmap/` | Proposed, accepted, or future work; implementation status, sequencing, and task breakdowns. | Implemented behavior reference and architectural decision rationale. |
| Release-note history | `docs/releases/` | One checked-in summary per source release under the procedure; the note at its immutable tag is the release record. | Current commands, behavior, contracts, and compatibility definitions. | | Release-note history | `docs/releases/` | One checked-in summary per source release under the procedure; the note at its immutable tag is the release record. | Current commands, behavior, contracts, and compatibility definitions. |
| Complete copyable artifacts | `examples/` | Maintained configuration, inputs, and other copyable or runnable files. | Field-by-field reference, command reference, prose explanation. | | Complete copyable artifacts | `examples/` | Maintained configuration, inputs, and other copyable or runnable files. | Field-by-field reference, command reference, prose explanation. |
@@ -153,8 +153,15 @@ Use sequentially numbered ADR filenames such as
Treat the decision content of an accepted ADR as immutable. When a decision Treat the decision content of an accepted ADR as immutable. When a decision
changes, create a new ADR and update the earlier ADR's status to superseded. changes, create a new ADR and update the earlier ADR's status to superseded.
Rejected architectural alternatives belong in the ADR; rejected product ideas
belong in the roadmap. ADRs should be reserved for major architectural decisions, such as ownership
boundaries, large-scale architectural features, or invariants that rise to
the level of architectural significance. Routine choices, implementation
decisions, and rejected suggestions do not warrant an ADR unless they
otherwise represent a significant architectural decision.
Roadmaps should preserve plausible future work, not rejected product
ideas.
## Maintenance ## Maintenance

View File

@@ -2,9 +2,9 @@
**Base Policy Version:** 1.0 **Base Policy Version:** 1.0
**Last Updated**: 2026-09-28 **Last Updated**: 2026-11-17
**Upstream Source**: https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/docs/policy/meta.md **Upstream Source**: https://gitea.maximumdirect.net/eric/policy/src/commit/593c9b52273c5c879785ae9e995d21026df467b4/docs/policy/meta.md
## Origin And Local Authority ## Origin And Local Authority

View File

@@ -1,10 +1,10 @@
# Open Source Licensing And Attribution Policy # Open Source Licensing And Attribution Policy
**Base Policy Version:** 1.8 **Base Policy Version:** 1.9
**Last Updated**: 2026-09-28 **Last Updated**: 2026-11-17
**Upstream Source**: https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/docs/policy/oss.md **Upstream Source**: https://gitea.maximumdirect.net/eric/policy/src/commit/593c9b52273c5c879785ae9e995d21026df467b4/docs/policy/oss.md
## Purpose And Scope ## Purpose And Scope
@@ -74,6 +74,9 @@ individual packages.
Use the upstream [application COPYRIGHT example](https://gitea.maximumdirect.net/eric/policy/src/commit/a469273adda336625f96b9d769ea27b33999f146/examples/licensing/application/COPYRIGHT) Use the upstream [application COPYRIGHT example](https://gitea.maximumdirect.net/eric/policy/src/commit/a469273adda336625f96b9d769ea27b33999f146/examples/licensing/application/COPYRIGHT)
or [library COPYRIGHT example](https://gitea.maximumdirect.net/eric/policy/src/commit/a469273adda336625f96b9d769ea27b33999f146/examples/licensing/library/COPYRIGHT) or [library COPYRIGHT example](https://gitea.maximumdirect.net/eric/policy/src/commit/a469273adda336625f96b9d769ea27b33999f146/examples/licensing/library/COPYRIGHT)
to create the project’s root `COPYRIGHT` file. to create the project’s root `COPYRIGHT` file.
Use the COPYRIGHT examples exactly as provided, except for placeholder
substitutions and changes expressly required or authorized by this policy or
the author.
Use verified project names, contribution years, and copyright holders. Use verified project names, contribution years, and copyright holders.
For another selected license, adapt the grant, SPDX expression, disclaimer, and For another selected license, adapt the grant, SPDX expression, disclaimer, and
text references together to reflect the author's selected grant. text references together to reflect the author's selected grant.
@@ -169,10 +172,15 @@ source files; the central attribution entry does not authorize stripping them.
## Discoverability ## Discoverability
End Narratio's README with two friendly statements linking to its actual grant End the project's README with two friendly statements linking to its actual
in root `COPYRIGHT` and to `docs/oss/attribution.md`, using paths relative to grant in `COPYRIGHT` and the attribution document. For example, for a project
the README. The statements identify Narratio's GPL v3.0-or-later grant and make with the stated license:
the open source attribution notices discoverable.
```markdown
PROJECT_NAME is licensed under the [LGPL v3.0 or later](COPYRIGHT).
[Open Source attribution notices](docs/oss/attribution.md) are available.
```
Each new checked-in release document and its hosted download page must end Each new checked-in release document and its hosted download page must end
with links whose visible text is `COPYRIGHT | LICENSE | ATTRIBUTION`. Use absolute with links whose visible text is `COPYRIGHT | LICENSE | ATTRIBUTION`. Use absolute

View File

@@ -1,10 +1,10 @@
# Release Policy # Release Policy
**Base Policy Version:** 1.4 **Base Policy Version:** 1.7
**Last Updated**: 2026-09-28 **Last Updated**: 2026-11-17
**Upstream Source**: https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/docs/policy/release.md **Upstream Source**: https://gitea.maximumdirect.net/eric/policy/src/commit/593c9b52273c5c879785ae9e995d21026df467b4/docs/policy/release.md
## Purpose ## Purpose
@@ -12,6 +12,9 @@ This policy defines a proportionate workflow for validating and publishing an
intended source revision under a fresh version. Releases should require little intended source revision under a fresh version. Releases should require little
routine intervention, avoid repeated work, and preserve published contents. routine intervention, avoid repeated work, and preserve published contents.
Adopt stronger verification or reproducibility requirements through an explicit
project-specific decision justified by the intended audience and support needs.
The repository-specific commands belong in `docs/release.md`. Historical release The repository-specific commands belong in `docs/release.md`. Historical release
summaries belong in `docs/releases/`. The procedure must agree with the adopted summaries belong in `docs/releases/`. The procedure must agree with the adopted
policy and link to it rather than introduce additional release requirements. policy and link to it rather than introduce additional release requirements.
@@ -59,9 +62,14 @@ requires a deliberate update to the policy and procedure where needed.
For releases at or after `v1.0.0`: For releases at or after `v1.0.0`:
- a major release may make intentional incompatible changes; - a major release may make intentional incompatible changes;
- a minor release may add backward-compatible behavior; and - a minor release may add backward-compatible behavior or raise the Go consumer
minimum as described below; and
- a patch release may make backward-compatible fixes. - a patch release may make backward-compatible fixes.
In this context, "backward-compatible" means only that pre-existing, valid
configurations will continue to work following the release. Behavior need not
remain strictly identical.
Before `v1.0.0`, a minor release may change a documented public, operational, Before `v1.0.0`, a minor release may change a documented public, operational,
configuration, data, integration, or compatibility contract when the release configuration, data, integration, or compatibility contract when the release
note explains the impact and required consumer action. A patch release must note explains the impact and required consumer action. A patch release must
@@ -71,6 +79,36 @@ Additional compatibility promises and deliberate exceptions belong in the
adopted policy or canonical contract documentation. Release notes explain adopted policy or canonical contract documentation. Release notes explain
changes; they do not redefine current compatibility contracts. changes; they do not redefine current compatibility contracts.
## Consumer Minimum And Release Toolchain
Distinguish the minimum toolchain supported for consumers from the toolchain
maintainers use to build and validate a release. Record the consumer minimum in
the language's standard metadata and explain its support meaning in canonical
documentation. Define the selected release toolchain and its setup commands in
`docs/release.md`. Toolchain selection and upgrade cadence are repository-specific
choices.
For Go repositories, normally declare the initial stable release of the selected
series as the consumer minimum, such as `go 1.26.0`. Use a higher patch minimum
when a dependency or an identified correctness fix requires it, and document
the reason.
For release-policy purposes, successful build and release validation on the
selected Go patch release are sufficient to presume support across that Go
series, subject to the declared consumer minimum and concrete evidence of
incompatibility. Investigate specific compatibility concerns as they arise.
Use the selected release toolchain for candidate validation and release builds,
including CI jobs performing those tasks. A newer validation patch version alone
leaves the consumer minimum unchanged.
A minor release may raise the Go consumer minimum, including from one Go series
to the next, both before and after `v1.0.0`. This is an explicit exception to the
backward-compatibility requirement for minor releases. Patch releases preserve
the consumer minimum. Explain an increase's impact and required consumer action
in the release note. Other incompatible changes remain subject to the versioning
rules above.
## Release Documentation And Preparation ## Release Documentation And Preparation
Every new release must include `docs/releases/<version>.md` in the tagged Every new release must include `docs/releases/<version>.md` in the tagged
@@ -206,7 +244,8 @@ release without replacing its contents or reusing its version.
Maintain `docs/release.md` as a short, executable maintainer runbook. It must Maintain `docs/release.md` as a short, executable maintainer runbook. It must
identify: identify:
1. prerequisites, primary branch, and authoritative remote; 1. prerequisites, selected release toolchain, primary branch, and authoritative
remote;
2. version and release-note preparation; 2. version and release-note preparation;
3. one publication command with its selected local checks and automated guards; 3. one publication command with its selected local checks and automated guards;
4. declared deliverables, required build targets, and automation responsibilities; 4. declared deliverables, required build targets, and automation responsibilities;

View File

@@ -2,9 +2,9 @@
**Base Policy Version:** 1.3 **Base Policy Version:** 1.3
**Last Updated**: 2026-09-28 **Last Updated**: 2026-11-17
**Upstream Source**: https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/docs/policy/testing.md **Upstream Source**: https://gitea.maximumdirect.net/eric/policy/src/commit/593c9b52273c5c879785ae9e995d21026df467b4/docs/policy/testing.md
## Purpose ## Purpose

View File

@@ -7,16 +7,18 @@ The source release completes when the intended tag is successfully pushed to
## Prepare the candidate ## Prepare the candidate
Use `main` and the authoritative Git remote `origin`. Install Git, a POSIX Use `main` and the authoritative Git remote `origin`. Install Git, a POSIX
shell, standard Unix build tools, and Go 1.26. Have the selected Go modules shell, standard Unix build tools, and the [release toolchain](#release-toolchain).
available before offline validation. Git access must permit fetch and tag push. Have the selected Go modules available before offline validation. Git access
must permit fetch and tag push.
Application-provider credentials are not required; Gitea delivery credentials Application-provider credentials are not required; Gitea delivery credentials
belong to CI. belong to CI.
Choose an unused stable `vMAJOR.MINOR.PATCH` under the Choose an unused stable `vMAJOR.MINOR.PATCH` under the
[compatibility rules](policy/release.md#versioning-and-compatibility). Narratio [compatibility rules](policy/release.md#versioning-and-compatibility). Narratio
is past v1.0.0, so intentional CLI or configuration breaks require a major is past v1.0.0; apply the policy's effective-configuration compatibility
release. Update affected canonical documentation with the change. Write the definition and Go consumer-minimum exception. Update affected canonical
matching `docs/releases/vMAJOR.MINOR.PATCH.md` with a short summary and any documentation with the change. Write the matching
`docs/releases/vMAJOR.MINOR.PATCH.md` with a short summary and any
relevant compatibility impact or upgrade action; choose sections to suit the relevant compatibility impact or upgrade action; choose sections to suit the
release. release.
@@ -39,6 +41,27 @@ before tagging; record its exact commit if needed:
git rev-parse HEAD git rev-parse HEAD
``` ```
## Release toolchain
The selected release toolchain is Go 1.27.4, matching the validation and build
jobs in `.woodpecker/release.yml`. With an official Go installation available,
select it before candidate validation and publication:
```sh
export GOTOOLCHAIN=go1.27.4
go version
```
Go downloads the selected toolchain if needed. Complete that setup and module
preparation before offline candidate validation. Keep this selection and the
release CI images aligned when deliberately updating the release toolchain.
The consumer minimum is Go 1.27.0 as declared in `go.mod`.
Successful release validation on the selected patch establishes presumed
support across that series, subject to the declared minimum and concrete
evidence of incompatibility, under the
[release policy](policy/release.md#consumer-minimum-and-release-toolchain).
## Publish ## Publish
From a clean `main` checkout at the pushed candidate, run one command: From a clean `main` checkout at the pushed candidate, run one command:

View File

@@ -11,6 +11,7 @@ See the [release procedure](../release.md) for creating a candidate and tag.
When asynchronous publication succeeds, the corresponding Gitea release is the When asynchronous publication succeeds, the corresponding Gitea release is the
canonical source for downloadable binaries and checksums. canonical source for downloadable binaries and checksums.
- [v3.1.0](v3.1.0.md)
- [v3.0.0](v3.0.0.md) - [v3.0.0](v3.0.0.md)
- [v2.2.1](v2.2.1.md) - [v2.2.1](v2.2.1.md)
- [v2.2.0](v2.2.0.md) - [v2.2.0](v2.2.0.md)

40
docs/releases/v3.1.0.md Normal file
View File

@@ -0,0 +1,40 @@
# Narratio v3.1.0
This minor release adds explicit provider-credential forwarding to Scriptorium
for trim bounds generation and artifact analysis.
## Compatibility and upgrade
Existing pipelines remain valid. An omitted, null, or empty
`pipeline.scriptorium.credentials` list continues to forward no provider keys.
When Scriptorium needs a credential, provision its environment variable through
Narratio's existing environment or secrets-directory mechanism and list the
exact name in the pipeline, for example:
```yaml
scriptorium:
credentials: [OPENROUTER_API_KEY]
```
Selected references must resolve to nonempty values when Narratio loads the
pipeline, even if the current command will not run Scriptorium. A Narratio
overlay replaces the complete list, and `[]` clears it. After correcting a
failed trim or analysis invocation, retry normally; successful work need not be
forced solely because a credential was added or rotated. See
[Scriptorium credentials](../config.md#scriptorium-credentials) and the
[401 troubleshooting guide](../troubleshooting.md#scriptorium-returns-http-401-during-trim-or-analyze).
## Changes
- Forward selected, already-resolved credential names and values to Scriptorium
for trim, analysis, character-family generation, and render-debug calls.
Scriptorium still owns provider and profile selection; Narratio does not add
a model-request `--api-key-env` override.
- Register selected values for captured subprocess-output and failure-diagnostic
redaction. Inspection and invocation metadata contain credential names, never
their values. This protection does not scan files Scriptorium writes directly.
- Reuse the credential-forwarding boundary shared with Audita and Notarius.
Retire the completed Scriptorium credential-forwarding bug report from the
source roadmap; its history remains in Git.
[COPYRIGHT](https://gitea.maximumdirect.net/eric/narratio/src/tag/v3.1.0/COPYRIGHT) | [LICENSE](https://gitea.maximumdirect.net/eric/narratio/src/tag/v3.1.0/LICENSE) | [ATTRIBUTION](https://gitea.maximumdirect.net/eric/narratio/src/tag/v3.1.0/docs/oss/attribution.md)

175
docs/roadmap/audita.md Normal file
View File

@@ -0,0 +1,175 @@
# Adopt Audita v3 and independent diagnostic destinations
## Purpose
Adopt Audita v3.0.0 for transcript polishing and use its independent output
destinations to implement the Audita portion of the
[session workspace roadmap](workspace.md). Operators should find the completed
transcript, ordinary reports, and optional debug evidence in their respective
Narratio locations.
This document defines the Audita adoption scope and target. The workspace
roadmap owns shared layout, latest-attempt views, and retention behavior. Its
referenced ADRs remain Proposed. Implementation sequencing belongs in a
subsequent implementation plan.
## Reviewed Upstream Release
The reviewed Audita v3.0.0 tag identifies commit
`3b4933256eff84327b812e7ae12babf743bc04a6`. Its
[release notes](https://gitea.maximumdirect.net/eric/audita/src/tag/v3.0.0/docs/releases/v3.0.0.md),
[CLI reference](https://gitea.maximumdirect.net/eric/audita/src/tag/v3.0.0/docs/cli.md),
[configuration reference](https://gitea.maximumdirect.net/eric/audita/src/tag/v3.0.0/docs/config.md),
and [operations guide](https://gitea.maximumdirect.net/eric/audita/src/tag/v3.0.0/docs/operations.md)
own the downstream contracts.
Audita now honors an explicit `--report-dir` alongside file transcript output.
Its existing `--work-dir` selects the parent of retained debug captures, with
capture enabled separately through configuration or `--debug`. These controls
satisfy Narratio's requested destination separation. Further upstream changes
are unnecessary for this scope.
## Current Baseline
Narratio's [Audita integration](../integrations/audita.md) and
[polish stage](../internal/stage-polish.md) describe the implemented behavior:
- The adapter invokes `process` with a transcript, glossary, and staged transcript
destination. It supports independent downstream configuration, overlay,
profile, module, description, and output-schema selectors.
- The adapter supplies no reporting, debug, or work-directory flags. Audita
controls debug capture and placement through its own configuration.
- Ordinary reports are discovered beside the staged transcript. The polish
stage validates returned report paths against those adjacent filenames.
- Only the validated polished transcript becomes a canonical stage output.
Reports, captured streams, and the generated invocation record are diagnostics.
- Selected credential references use Narratio's shared exact-name forwarding and
captured-stream redaction boundary.
The existing invocation remains usable with Audita v3 after deployment-side
profile migration. Narratio changes are needed to request and consume the
new destination separation.
## Targeted End State
### Products and diagnostics
Narratio supplies separate destinations for each actual polish attempt:
| Content | Destination and control |
| --- | --- |
| Corrected transcript | Run-local staging via `--output`; validated and promoted to `transcripts/polished.json` on success. |
| Ordinary reports | `runs/<run_id>/polish/logs/` via `--report-dir`. |
| Captured stdout, stderr, and Narratio invocation record | The same run-local polish log directory. |
| Optional debug evidence | `runs/<run_id>/polish/debug/` via `--work-dir`; Audita may create its own `run-*` subdirectory beneath it. |
The workspace roadmap's `logs/polish` and `debug/polish` links expose the latest
attempt. Narratio supplies actual run destinations to Audita and records those
paths in manifest diagnostics. Shared link updates and cleanup protection are
implemented by the workspace work rather than separately inside the adapter.
### Capture selection
Add an optional `pipeline.audita.debug` boolean, defaulting to false. A true
value passes `--debug`. False or omission supplies no capture override and
preserves Audita configuration and overlay behavior; it does not disable debug
enabled downstream.
Supply `--work-dir` for each executing attempt so downstream-enabled capture
also lands in the Narratio-selected debug directory. Selecting that destination
alone does not enable capture. Ordinary production operation retains Audita's
default reporting and debug settings. Narratio adds no reporting enable/disable
flag or debug-disable flag.
Debug selection affects diagnostics for an executing stage. Changing it alone
does not invalidate a completed transcript. Operators use the existing force
workflow when fresh polish or debug evidence is needed.
### Ownership and compatibility
Use a clean adoption of Audita v3's CLI contract, without version-dependent
adapter branches or legacy profile conversion. Audita continues to own its
configuration, profiles, prompts, runtime State, and diagnostic contents.
Narratio owns supplied destinations and transcript promotion.
Keep existing selectors and shared credentials such as `OPENROUTER_API_KEY` and
`RAKESTRAWHOME_API_KEY` under their configured exact names. Audita's examples
do not require Narratio to adopt application-specific credential aliases.
Operators continue to list the credential references required by all configured
Audita backends.
Audita is a separately installed executable. Its adoption of ConfigKit v0.5.0
and PromptKit v0.12.0 does not require changing Narratio's own library
dependencies as part of this feature.
## Required Changes
### Deployment configuration migration
Document the manual migration of Audita-owned PromptKit files:
- Wrap profile definitions under keyed `profiles:` mappings, remove inner `id`
fields, and replace `base_profile` with `extends`. Preserve selected profile
IDs when appropriate.
- Review explicit zeros, omitted values, and nulls against the new generation
control semantics. Validate the final configuration root, including unused
definitions and backend references.
- Rename any backend literally named `extends` and update its references.
- Validate production configuration and each used testing overlay with Audita's
offline `config validate` command. Audita application configuration continues
to use `version: 2`.
Keep the detailed downstream format owned by the pinned Audita documentation.
Narratio does not inspect, rewrite, or automatically migrate these files.
Deployment can migrate Audita before the workspace changes land.
### Adapter and polish stage
Carry explicit report and debug destinations through the Audita request and
construct the supported flags inside the adapter. Wire the debug selector
through configuration and runner composition.
Discover the existing three report filenames in the requested report directory.
Update polish's expected-path validation to the same location. Update invocation
records and safe result metadata to describe the selected destinations and
capture request. Preserve available failure evidence and the original subprocess
error.
Keep existing transcript validation, report read bounds, timeouts, credential
forwarding, and captured-stream redaction. Reports remain optional diagnostics;
early failures or downstream-disabled reporting may produce none. Exit-zero
runs with recoverable model errors remain successful. A nonzero exit, including
a late report-write failure, never authorizes transcript promotion. Narratio
does not add report-schema parsing or report-status success gates.
### Workspace integration and lifecycle
Use the shared workspace path owner for run-local log/debug destinations and
the agreed latest-attempt behavior. Preserve previous views on skipped stages;
actual attempts refresh both views, including on failure. An attempt without
debug capture exposes an empty current debug directory.
Keep full Audita debug bundles local in this feature. Preserve existing declared
diagnostic publication and apply the workspace roadmap's retention protection
to latest link targets. This feature inherits that roadmap's clean session
cutover and unchanged treatment of older completed outputs after invalidation
or failed replacement.
### Documentation and verification
When implemented, update the configuration reference and examples, Audita
integration contract, polish internals, and operator guide. Reference Audita v3's
profile migration and explain the shared Audita/Notarius overlay development
workflow. Downstream configuration edits behind unchanged selectors still
require explicitly forcing the affected stage to replace reused outputs.
Revise the workspace roadmap's upstream-request description when this adoption
is incorporated; Audita v3.0.0 supplies the previously missing capability.
Use focused offline tests for separate transcript/report/debug destinations,
enable-only debug selection, capture enabled by downstream configuration,
available failure reports, and preservation of nonzero-exit behavior. Verify
that reports remain diagnostics and only a successful validated transcript is
promoted. Shared latest-view and cleanup tests belong to the workspace change.
Default Narratio tests use subprocess doubles and temporary filesystems and
remain independent of sibling checkouts, real credentials, and paid providers.

280
docs/roadmap/workspace.md Normal file
View File

@@ -0,0 +1,280 @@
# Session workspace organization
## Purpose
Give operators predictable locations for session inputs, completed outputs,
logs, and debug evidence. Apply the taxonomy in
[ADR 0001](../adr/0001-classify-session-content.md) and the ownership boundary in
[ADR 0002](../adr/0002-assign-subprocess-content-ownership.md).
This roadmap defines the target behavior and required changes. Implementation
sequencing belongs in a subsequent implementation plan. The ADRs remain
Proposed pending their acceptance.
## Confirmed Requirements
- Completed artifacts occupy a flat `artifacts/` directory. Intermediate
products such as `session_bounds.json` belong here.
- Combined transcripts occupy `transcripts/` directly. Initial per-speaker
transcripts occupy a subdirectory beneath it.
- Prepared external audio occupies `audio/`; other prepared external inputs
occupy `inputs/`. Outputs consumed by later stages retain their output paths.
- Logs and Debug use matching latest-attempt views: `logs/<stage>` and
`debug/<stage>` are symlinks to the producing run's directories. Both views
advance when a stage starts an actual attempt, including attempts that fail.
A skipped stage leaves its previous views intact.
- Execution reports and invocation records are Logs. Historical Logs and Debug
remain under their producing runs, subject to cleanup.
- Narratio can selectively request supported subprocess debug capture through
configuration. Omission preserves application configuration and defaults;
Narratio needs no explicit downstream debug-disable override.
- Prepared session audio is the single retained Narratio-managed audio copy.
Remove Narratio's separate persistent audio cache and spool duplicates.
- Configurations that produce colliding artifact names or destinations fail
validation before execution. Validation covers the effective pipeline,
including expanded character families and built-in artifact destinations.
- Narratio selects input, output, log, and debug paths. Subprocess applications
own their working State and Cache through their supported configuration.
- A dedicated cache root such as `/var/cache/notarius` is a deployment
recommendation. The application owns its cache defaults, internal layout,
identity, and reuse semantics. Narratio session cleanup respects that boundary.
- Narratio retains its own manifest, recovery records, and managed staging State.
- This is a clean cutover for newly prepared sessions. Existing-session migration
and backward compatibility shims are outside the feature.
- Treatment of older completed files after invalidation or failed replacement
remains unchanged, including their availability through manifest-backed
resolution. Directory reorganization does not authorize new stale-file
deletion, automatic fallback, or rollback behavior.
## Current Baseline
The [operator guide](../operations.md#local-state-layout) owns the current
physical layout. Relevant differences from the target are:
- Extraction moves the complete Notarius bundle to
`artifacts/notarius/<run_id>/`. Resume evidence and artifact resolution depend
on that bundle and its index.
- Merge and normalize promote Seriatim execution reports into `artifacts/`.
- Analysis output paths and character-family patterns can introduce nested
artifact directories. Output-path configuration also permits locations that
need reconciliation with the selected directory categories.
- Standard combined transcript paths already match the target. Layout creation
also creates an unused `transcripts/trimmed/` directory.
- Most subprocess diagnostics live under individual run directories. Root-level
log paths lack a consistent latest-attempt view. Audita reports sit beside
its staged transcript, and restore writes a separate top-level report.
- Prepared previous-session inputs occupy `previous/`. Narratio-owned reference
snapshots supplied to Notarius occupy session `cache/notarius/references/`.
These snapshots are distinct from Notarius's own execution caches.
- Audita debug placement follows downstream configuration. Narratio does not
expose Notarius debug capture, and Scriptorium render-debug placement varies.
- Narratio maintains separate S3 audio cache and spool paths in addition to the
prepared session audio copy.
## Target Layout And Ownership
Retain the configurable workspace root and its current system-wide default,
`/var/lib/narratio`. Sessions remain under
`/var/lib/narratio/work/<campaign>/<session>` by default. The following paths
express the selected categories:
| Path | Contents and role |
| --- | --- |
| `manifest.json` | Narratio's durable progress and output references. |
| `artifacts/<filename>` | Completed artifact payloads, including session bounds. |
| `transcripts/<filename>` | Completed combined transcripts and rendered transcripts. |
| `transcripts/raw/<speaker>.json` | Completed initial per-speaker transcripts. |
| `audio/` | Prepared external audio. |
| `inputs/` | Prepared configuration, references, and previous-session inputs. |
| `logs/<stage>` | Symlink to the latest attempt's run-local logs and execution reports. |
| `debug/<stage>` | Symlink to the latest attempt's run-local debug directory, empty when no capture is produced. |
| `runs/<run_id>/<stage>/logs/` | Actual logs and execution reports for that attempt. |
| `runs/<run_id>/<stage>/debug/` | Actual debug captures for that attempt, including retained state snapshots. |
| `runs/<run_id>/` | Narratio staging, original tool bundles, and retained execution evidence. |
For example, the latest views use relative links within the session:
```text
logs/polish -> ../runs/<run_id>/polish/logs/
debug/polish -> ../runs/<run_id>/polish/debug/
```
Each stage's latest attempt can belong to a different run. Producers write to
the actual run paths; the symlinks provide operator navigation without duplicate
diagnostic storage.
Narratio's lock and restore marker remain its own State. Their current placement
can remain; introducing another root-level State directory is unnecessary for
this feature. Generated records that describe an invocation belong with Logs;
configuration actually supplied as an input follows its input or staging role.
Subprocesses may create internal working directories wherever their configuration
directs. Narratio-selected staging destinations for result bundles remain valid
under ADR 0002. Cache locations are documented as operator recommendations using
each application's existing configuration surface.
## Required Changes
### Output paths and configuration
Centralize the revised paths in the existing path owner. Apply the flat artifact
rule to explicit artifacts, expanded families, extraction outputs, and session
bounds. Preserve logical source identities used by dependencies and publication.
Keep explicit analysis filenames and require flat destinations. Derive extraction
filenames from configured extraction keys with a `.json` extension, with an
explicit extraction filename override for naming preferences or collisions.
Retain `session_bounds.json` as the default bounds filename. Do not silently
rename conflicting files. Report conflicting producers and the shared destination
in configuration errors. Validate the effective configuration after composition
and family expansion.
Keep combined transcript destinations directly beneath `transcripts/`. Remove
obsolete directory scaffolding and reconcile configurable output paths with
their category. Local path changes do not require flattening explicitly
configured remote publish destinations.
### Notarius result handling and reuse
Receive and validate the complete Notarius bundle in Narratio staging. Promote
selected accepted payloads to their flat artifact destinations. Classify the
receipt, warnings, rejection summaries, and diagnostics as Logs. Keep bundle
indexes and other management metadata with the bundle or Narratio State according
to their use.
Revise extraction evidence, catalog hydration, and resume checks to resolve
promoted products independently of the old `artifacts/notarius/` layout. Retain
the identity, provenance, contract, and checksum evidence needed for current
reuse behavior. Historical bundles may remain available for inspection under
their existing retention semantics; relocating them beneath `runs/` must not
silently shorten their lifetime through run cleanup.
Preserve ordinary resume and forced-extraction behavior. Subprocess caches remain
under Notarius's control.
### Inputs
Place prepared previous-session material beneath `inputs/previous/`. Place the
stable reference snapshots Narratio supplies to Notarius beneath
`inputs/references/`, retaining their content identities where needed for reuse.
Update preparation, input resolution, manifest references, and restore mappings.
Keep source configuration ownership and prepared-file validation unchanged.
### Audio acquisition
Simplify acquisition to one prepared session copy under `audio/`. Remove the
separate Narratio S3 audio cache and routine retained spool copies, together with
their obsolete configuration, manifest bookkeeping, and cleanup controls.
Preparation may use temporary download files before installing validated audio.
Preserve reuse of valid prepared audio and update restore to use the same layout.
Recreating a session after its prepared audio is removed requires fetching the
source again. Original recordings remain outside this cleanup change. Removing
spool/cache handling does not authorize new deletion of prepared session audio.
Subprocess caches remain independently configured and managed.
### Logs and execution reports
Provide one consistent latest-attempt view per stage. Include failed attempts;
a skipped stage leaves its previous view intact. Distinguish multiple applications
or artifact invocations within a stage through their filenames. Route Seriatim
reports, Audita reports, Notarius diagnostic records, and Narratio invocation
records through this model. Treat restore execution as its own diagnostic group
under `logs/restore/`, using run-local evidence and a latest-attempt view.
Prevent a new attempt from presenting old diagnostic files as newly generated
ones. At the start of each actual stage attempt, create its run-local log and
debug directories and refresh both latest symlinks. An attempt without debug
output exposes an empty debug directory rather than an older capture. Preserve
subprocess errors and available evidence on failure. Retain existing
captured-stream redaction and limits.
Keep historical files at their run paths; rotating the links does not move files.
Run cleanup must preserve directories targeted by current latest links. Do not
introduce an automatic history age or count limit. Publication and manifest
diagnostic references use actual run paths. Adjust path handling for these
Narratio-managed navigation links without relying on arbitrary symlink traversal.
### Debug controls and placement
Add selective Narratio configuration for Audita and Notarius debug capture using
their supported enabling CLI flags. An enabled Narratio selector requests
capture; an omitted or false selector passes no debug override and preserves the
application's configured/default behavior. Do not add a downstream disable flag.
Supply the actual run-local debug directories, exposed through `debug/polish`
and `debug/extract`. Control the destination when capture can be enabled through
downstream configuration as well, including Audita overlays, using supported
destination controls without changing capture enablement. Audita's debug
work-directory option selects diagnostic storage and belongs to this placement
responsibility.
Route Scriptorium's existing analysis and bounds render-debug products to the
run-local directories exposed through `debug/analyze` and `debug/trim`. Preserve
its existing per-artifact selection capability. Seriatim requires no invented
debug mode; its ordinary reports are
Logs. Subprocess-defined bundle contents and nested run directories are allowed
beneath the selected run-local debug root. Logs and Debug share the same
latest-attempt semantics and cleanup protection.
Keep new full Audita and Notarius debug bundles local in this feature. Preserve
publication of currently declared diagnostics, including existing render-debug
products. Enabling capture does not implicitly add full debug bundles to remote
archives.
Debug controls govern capture when a stage executes. They do not independently
require regeneration of valid substantive outputs. Document the existing force
workflow for obtaining fresh diagnostic evidence when a stage would be reused.
Preserve downstream failure semantics for diagnostic writes and the existing
boundary of Narratio's captured-stream redaction.
### Audita destination support
Request upstream support for independently selecting the transcript output,
ordinary report/log directory, and debug/retained working directory, then adopt
a supporting release. Audita currently ignores `--report-dir` when transcript
output is a file; honoring that destination is the principal missing capability.
Narratio continues to capture subprocess stdout and stderr itself.
Direct ordinary reports, including failure reports, to the actual polish log
directory, the transcript to its staged product destination, and retained debug
material to the actual polish debug directory. This feature uses the supported
upstream controls in a clean cutover without version-based compatibility branches.
### Manifest, publication, restore, and cleanup
Update all consumers of changed paths and file categories together. Preserve
per-speaker and per-artifact completed-work reuse. Keep publication driven by
declared products and diagnostics, with new full debug bundles remaining local.
Restore new-format products and inputs to their new locations.
Define an explicit way to identify supported session state for the clean
cutover. Document regeneration with the new version and manual configuration
updates. Avoid accepting old state through path fallbacks or silently rewriting
old local sessions or remote snapshots.
Preserve existing invalidation and failed-replacement behavior. Review retention
by content role before changing cleanup targets, especially when durable products
or historical bundles move. Run cleanup preserves the current log and debug
link targets; explicit removal of an entire session removes its local views
with it. Subprocess working State and Cache remain outside Narratio's cleanup
responsibility.
### Documentation and verification
Update configuration examples, the operator guide, adapter contracts, workspace
internals, and the architecture policy when implementation lands. Replace the
current architectural assumption that extraction requires a complete immutable
bundle beneath `artifacts/` with the selected product-promotion model. Retire
policy and documentation for Narratio's removed audio cache/spool lifecycle and
document the managed latest-attempt symlinks. Keep per-application cache locations
as deployment recommendations owned by each application's configuration.
Use focused behavioral coverage for flat output placement, collision rejection,
latest-attempt diagnostics on success and failure, debug selection and routing,
unchanged completed-work reuse, failed replacement, and new-format publish/restore.
Cover empty debug views after attempts without capture, preserved views for
skipped stages, cleanup protection of latest targets, and audio acquisition,
reuse, and restore without persistent spool/cache duplicates. Exercise cleanup
against products and separately owned caches. Use temporary filesystems and
subprocess doubles; default tests remain offline and independent
of sibling checkouts or paid providers.

View File

@@ -39,7 +39,7 @@ Likely cause:
Diagnostics: Diagnostics:
```bash ```bash
narratio session validate 2026-04-04 --session /path/session.yml narratio session validate 2026-04-04 --session-file /path/session.yml
``` ```
Safe fix: Safe fix:
@@ -62,7 +62,7 @@ Likely cause:
Diagnostics: Diagnostics:
```bash ```bash
narratio session plan 2026-04-04 --config /path/pipeline.yml --campaign-file /path/campaign.yml --session /path/session.yml narratio session plan 2026-04-04 --config /path/pipeline.yml --campaign-file /path/campaign.yml --session-file /path/session.yml
``` ```
Safe fix: Safe fix:
@@ -90,12 +90,12 @@ Symptom:
Likely cause: Likely cause:
- the campaign `party.yml` is an unversioned legacy document, or names a - the campaign party main document is unversioned, or names a
schema other than `narratio.party.v1`. schema other than `narratio.party.v1`.
Safe fix: Safe fix:
- replace the file with one exact, single-document - replace the main file with a versioned
[`narratio.party.v1` party](./integrations/party.md); do not add a version [`narratio.party.v1` party](./integrations/party.md); do not add a version
marker to an otherwise incompatible legacy structure. The versioned party is marker to an otherwise incompatible legacy structure. The versioned party is
the only configured roster authority. the only configured roster authority.
@@ -115,22 +115,27 @@ Diagnostics:
narratio config sources --config /path/pipeline.yml --overlay testing narratio config sources --config /path/pipeline.yml --overlay testing
``` ```
Add `--campaign` or `--campaign-file` when the pipeline has party-driven Native sources list the actual files and import evidence for the selected
artifact families. The output identifies each effective logical field's root, scope. To trace a value, use `config explain --path POINTER`, or discover paths
import, overlay, default, campaign, party, or family source without printing with `config explain --list`. App inspection keeps family declarations;
the field value or credential contents. `artifacts list` derives concrete members from the selected campaign/party.
Safe fix: Safe fix:
- move a duplicated base field so it has one owner; - inspect the field's effective origin and history;
- correct the selected overlay; or - correct the selected source or overlay; or
- correct the campaign party/family declaration that owns generated values. - select the intended roster when reviewing family members.
To review what would actually change before switching overlays, run `config To compare an explicit pipeline root with its testing overlay, select the root
diff` with the same pipeline and campaign selectors. It compares normalized on both sides:
effective values rather than YAML formatting or source-file layout.
Relevant reference: [Configuration inspection](./config.md#read-only-effective-pipeline-inspection). ```sh
narratio config diff --config /path/pipeline.yml --against-config /path/pipeline.yml --against-overlay testing --details
```
The sides use independent defaults. Comparison concerns effective native values,
including declarations, rather than generated domain objects or YAML layout.
See [configuration inspection](./cli.md#configuration-inspection).
## Audio mode conflict ## Audio mode conflict
@@ -164,7 +169,7 @@ Likely causes:
- key not defined in `pipeline.scriptorium.artifacts`; - key not defined in `pipeline.scriptorium.artifacts`;
- empty list entry (for example trailing comma); - empty list entry (for example trailing comma);
- `run-stage` used with non-`analyze`/`publish` target. - selected run/plan range contains neither `analyze` nor `publish`.
Diagnostics: Diagnostics:
@@ -201,7 +206,7 @@ narratio session plan 2026-04-04 --from render --through analyze
Safe fix: Safe fix:
- widen the bounded range to include the first reported stage, or recover that - widen the bounded range to include the first reported stage, or recover that
stage explicitly with `run-stage` before retrying. The failed check does not stage explicitly with `run --stage` before retrying. The failed check does not
create a run-local directory or modify the manifest. Narratio does not create a run-local directory or modify the manifest. Narratio does not
resume-validate excluded prefix stages, and stages after `--through` are not resume-validate excluded prefix stages, and stages after `--through` are not
prerequisites. prerequisites.
@@ -242,7 +247,7 @@ Safe fix:
for a successful checkpoint. for a successful checkpoint.
```bash ```bash
narratio run-stage transcribe 2026-04-04 narratio run 2026-04-04 --stage transcribe
``` ```
Valid earlier speaker checkpoints remain reusable even while aggregate Valid earlier speaker checkpoints remain reusable even while aggregate
@@ -270,7 +275,7 @@ Safe fix:
retry if the replacement attempt is interrupted. retry if the replacement attempt is interrupted.
```bash ```bash
narratio run-stage transcribe 2026-04-04 --force narratio run 2026-04-04 --stage transcribe --force
``` ```
Transport replay and application retries do not provide an exactly-once remote Transport replay and application retries do not provide an exactly-once remote
@@ -374,7 +379,7 @@ Safe fix:
An exit-zero polish with a valid transcript succeeds even when Audita reports An exit-zero polish with a valid transcript succeeds even when Audita reports
recoverable errors or no corrections. Missing reports are allowed when Audita recoverable errors or no corrections. Missing reports are allowed when Audita
reporting is disabled externally. Edits to Audita-owned files behind unchanged reporting is disabled externally. Edits to Audita-owned files behind unchanged
selectors require `narratio run-stage polish <session-id> --force` to replace a selectors require `narratio run <session-id> --stage polish --force` to replace a
previously successful result. See the [Audita integration contract](./integrations/audita.md). previously successful result. See the [Audita integration contract](./integrations/audita.md).
## Notarius executable missing ## Notarius executable missing
@@ -446,7 +451,7 @@ Safe fix:
evidence before extraction: evidence before extraction:
```bash ```bash
narratio run-stage prepare 2026-04-04 --force narratio run 2026-04-04 --stage prepare --force
``` ```
Do not point Notarius directly at the original source path or edit the manifest Do not point Notarius directly at the original source path or edit the manifest
@@ -606,7 +611,7 @@ Symptom:
Safe fix: Safe fix:
```bash ```bash
narratio run-stage extract 2026-04-04 --force narratio run 2026-04-04 --stage extract --force
``` ```
Narratio fingerprints its invocation contract and prepared Narratio reference Narratio fingerprints its invocation contract and prepared Narratio reference
@@ -649,7 +654,7 @@ Safe fix:
the canonical path as a substitute for current evidence. the canonical path as a substitute for current evidence.
```bash ```bash
narratio analyze 2026-04-04 --artifacts session_recap narratio run 2026-04-04 --stage analyze --force --artifacts session_recap
``` ```
Relevant references: [Operations: Artifact Selection](./operations.md#artifact-selection) Relevant references: [Operations: Artifact Selection](./operations.md#artifact-selection)
@@ -729,7 +734,7 @@ Safe fix:
```bash ```bash
narratio run 2026-04-04 narratio run 2026-04-04
narratio publish 2026-04-04 narratio run 2026-04-04 --stage publish --force
``` ```
After current records exist, inspect them and publish explicitly. Do not copy After current records exist, inspect them and publish explicitly. Do not copy
@@ -739,6 +744,20 @@ manifest-owned.
Relevant references: [Operations: Stage Execution and Continuation Behavior](./operations.md#stage-execution-and-continuation-behavior) Relevant references: [Operations: Stage Execution and Continuation Behavior](./operations.md#stage-execution-and-continuation-behavior)
and [Manifest Internals](./internal/manifest.md#transcribe-owned-speaker-state). and [Manifest Internals](./internal/manifest.md#transcribe-owned-speaker-state).
## Scriptorium returns HTTP 401 during trim or analyze
Check that Narratio's pipeline selects the credential names required by
Scriptorium, for example `scriptorium.credentials: [OPENROUTER_API_KEY]`.
Provision the values through the existing environment or secrets directory;
exporting a key without selecting it does not forward it to the child process.
See [Scriptorium credentials](config.md#scriptorium-credentials).
Once corrected, retry the failed run normally; forcing previously successful
transcription or analysis is unnecessary. If authentication still fails, check
the selected Scriptorium backend, credential validity, and provider access
without printing keys. A 401 can indicate an invalid key as well as a missing
one.
## Scriptorium private input changed without a rerun ## Scriptorium private input changed without a rerun
Symptom: Symptom:
@@ -760,7 +779,7 @@ Safe fix:
reusable unless selected themselves. reusable unless selected themselves.
```bash ```bash
narratio analyze 2026-04-04 --artifacts session_recap narratio run 2026-04-04 --stage analyze --force --artifacts session_recap
``` ```
Relevant reference: [Analyze Internals](./internal/stage-analyze.md#invariants). Relevant reference: [Analyze Internals](./internal/stage-analyze.md#invariants).
@@ -794,7 +813,7 @@ narratio session restore 2026-04-04
or rerun prepare after correcting session config: or rerun prepare after correcting session config:
```bash ```bash
narratio run-stage prepare 2026-04-04 --force narratio run 2026-04-04 --stage prepare --force
``` ```
Relevant reference: [Operations: Restore Workflow](./operations.md#restore-workflow). Relevant reference: [Operations: Restore Workflow](./operations.md#restore-workflow).
@@ -896,7 +915,7 @@ Diagnostics:
```bash ```bash
narratio session artifacts 2026-04-04 --remote narratio session artifacts 2026-04-04 --remote
narratio session status 2026-04-04 narratio session status 2026-04-04
narratio run-stage publish 2026-04-04 --force narratio run 2026-04-04 --stage publish --force
``` ```
Safe fix: Safe fix:
@@ -929,8 +948,8 @@ Safe fix:
- rerun render and then retry downstream stage(s): - rerun render and then retry downstream stage(s):
```bash ```bash
narratio run-stage render 2026-04-04 --force narratio run 2026-04-04 --stage render --force
narratio run-stage analyze 2026-04-04 --force narratio run 2026-04-04 --stage analyze --force
``` ```
Relevant reference: [Operations: Stage Execution](./operations.md#stage-execution-and-continuation-behavior). Relevant reference: [Operations: Stage Execution](./operations.md#stage-execution-and-continuation-behavior).
@@ -944,7 +963,7 @@ Symptom:
Likely causes: Likely causes:
- missing, unreadable, or invalid explicit `--secrets-dir`; - missing, unreadable, or invalid explicit `--secrets-dir`;
- invalid entries in the conventional `secrets/` directory beside the root pipeline; - invalid entries in `/usr/local/etc/narratio/secrets`;
- missing credential environment variables; - missing credential environment variables;
- invalid S3 endpoint/bucket settings. - invalid S3 endpoint/bucket settings.

View File

@@ -12,25 +12,36 @@ in the [configuration reference](../docs/config.md).
- [Production-shaped pipeline](pipeline.production.yml): S3 storage, publish, - [Production-shaped pipeline](pipeline.production.yml): S3 storage, publish,
external tools, and configured Scriptorium artifacts. external tools, and configured Scriptorium artifacts.
- [Production-base/testing-overlay bundle](production-testing/pipeline.yml): - [Production-base/testing-overlay bundle](production-testing/pipeline.yml):
explicit `conf.d` imports, one ordinary artifact per `artifacts/<key>.yml`, explicit required `conf.d` imports, an optional local import, destination-mounted
one family per `artifact-families/<key>.yml`, and the fixed artifact files, a YAML-filtered directory of keyed families, and the fixed
`overlays/testing.yml` overlay. Production values live in the base. The `overlays/testing.yml` overlay. Production values live in the base. The
bundle demonstrates an input-only artifact dependency, two character families bundle demonstrates an input-only artifact dependency, two character families
sharing the campaign party, and a testing-only disabled artifact. Inspect it sharing the campaign party, and a testing-only disabled artifact. The testing
offline with: overlay's `testing_notes` artifact inherits the recap prompt, inputs, and
testing profile while retaining its disabled status and separate output path.
The testing overlay upserts the transcript publish rule by `source`. A
destination key defines each artifact ID; filenames do not. Full-root and
disjoint definitions are also valid. Upsert replaces a matching list record
as a whole; empty append or upsert contributions leave existing entries intact.
Inspect it offline with:
```sh ```sh
narratio config validate --config examples/production-testing/pipeline.yml --campaign-file examples/campaigns/sample-campaign/campaign.yml narratio config validate --config examples/production-testing/pipeline.yml
narratio config show --config examples/production-testing/pipeline.yml --campaign-file examples/campaigns/sample-campaign/campaign.yml --overlay testing narratio config show --config examples/production-testing/pipeline.yml --overlay testing
narratio config sources --config examples/production-testing/pipeline.yml --campaign-file examples/campaigns/sample-campaign/campaign.yml --overlay testing narratio config sources --config examples/production-testing/pipeline.yml --overlay testing
narratio config artifacts --config examples/production-testing/pipeline.yml --campaign-file examples/campaigns/sample-campaign/campaign.yml --overlay testing narratio artifacts list --config examples/production-testing/pipeline.yml --campaign-file examples/campaigns/sample-campaign/campaign.yml --overlay testing
narratio config diff default testing --config examples/production-testing/pipeline.yml --campaign-file examples/campaigns/sample-campaign/campaign.yml narratio config diff --against-config examples/production-testing/pipeline.yml --against-overlay testing --config examples/production-testing/pipeline.yml
``` ```
These inspection commands load configuration and resolve explicit credential These inspection commands load configuration and resolve explicit credential
references, but do not load a session or create runtime state. This bundle is references, but do not load a session or create runtime state. This bundle is
intentionally local-storage and credential-reference free so the walkthrough intentionally local-storage and credential-reference free so the walkthrough
needs no tools or cloud services. needs no tools or cloud services. Native app inspection retains family
declarations; `artifacts list` derives their concrete members using the selected
campaign. Diff selects the example root on both sides because omitted
right-side selectors use their own discovery defaults. To isolate the
walkthrough from installed credential files, add `--secrets-dir` pointing to
an existing empty directory to each command.
- [Full annotated pipeline](pipeline.full.annotated.yml): every implemented - [Full annotated pipeline](pipeline.full.annotated.yml): every implemented
pipeline section with explanatory comments. pipeline section with explanatory comments.
- [Extraction subset pipeline](pipeline.extraction-subset.yml): a focused - [Extraction subset pipeline](pipeline.extraction-subset.yml): a focused
@@ -43,7 +54,9 @@ with the sample campaign and a compatible local- or S3-audio session.
- [Sample campaign](campaigns/sample-campaign/campaign.yml), its - [Sample campaign](campaigns/sample-campaign/campaign.yml), its
[session template](campaigns/sample-campaign/session.template.yml), and its [session template](campaigns/sample-campaign/session.template.yml), and its
adjacent stable inputs provide a complete campaign directory shape. adjacent stable inputs provide a complete campaign directory shape. Its
imported settings and split party demonstrate local secondary imports;
relative resources follow the file that supplies each value.
- [Local-audio session](session.local-audio.yml) and - [Local-audio session](session.local-audio.yml) and
[S3-audio session](session.s3-audio.yml) are concrete session files. [S3-audio session](session.s3-audio.yml) are concrete session files.
- [Session template](session.template.yml) and the campaign-local equivalent - [Session template](session.template.yml) and the campaign-local equivalent
@@ -76,8 +89,8 @@ names, or the Narratio credential lists must be changed to match. See the
[Audita v2 migration guide](https://gitea.maximumdirect.net/eric/audita/src/tag/v2.0.0/docs/migrations/v2.md) [Audita v2 migration guide](https://gitea.maximumdirect.net/eric/audita/src/tag/v2.0.0/docs/migrations/v2.md)
for maintained downstream configuration examples. for maintained downstream configuration examples.
For a deployed bundle, keep credential files out of source control in a For a deployed bundle, keep credential files out of source control in the
`secrets/` directory beside the root `pipeline.yml`, one file per referenced conventional `/usr/local/etc/narratio/secrets` directory, one file per referenced
environment-variable name, or select another directory with `--secrets-dir`. environment-variable name, or select another directory with `--secrets-dir`.
Static S3 credentials are optional: omit both S3 credential references to use Static S3 credentials are optional: omit both S3 credential references to use
the AWS SDK discovery chain. the AWS SDK discovery chain.

View File

@@ -1,8 +1,5 @@
config:
imports:
- path: fragments/inputs.yml
required: true
campaign_id: sample-campaign campaign_id: sample-campaign
session_template_file: ./session.template.yml
inputs:
speakers_file: ./speakers.yml
autocorrect_file: ./autocorrect.yml
glossary_file: ./glossary.yml
party_file: ./party.yml
spell_catalog_file: ./spell_catalog.json

View File

@@ -0,0 +1,12 @@
brenna:
player:
name: Rowan Hale
character:
name: Brenna
alias:
- Shield of Dawn
classes:
- name: paladin
level: 6
- name: warlock
level: 2

View File

@@ -0,0 +1,7 @@
session_template_file: ../session.template.yml
inputs:
speakers_file: ../speakers.yml
autocorrect_file: ../autocorrect.yml
glossary_file: ../glossary.yml
party_file: ../party.yml
spell_catalog_file: ../spell_catalog.json

View File

@@ -1,4 +1,9 @@
schema_version: narratio.party.v1 schema_version: narratio.party.v1
config:
imports:
- path: fragments/brenna.yml
destination: [characters]
required: true
characters: characters:
arannis: arannis:
@@ -12,15 +17,3 @@ characters:
classes: classes:
- name: wizard - name: wizard
level: 8 level: 8
brenna:
player:
name: Rowan Hale
character:
name: Brenna
alias:
- Shield of Dawn
classes:
- name: paladin
level: 6
- name: warlock
level: 2

View File

@@ -217,6 +217,9 @@ notarius:
scriptorium: scriptorium:
binary: scriptorium binary: scriptorium
# Select provider names provisioned through Narratio's environment/secrets.
# Used for trim, analysis, and render-debug calls; no provider override.
# credentials: [OPENROUTER_API_KEY, RAKESTRAWHOME_API_KEY]
config_path: /usr/local/etc/scriptorium/config.yml config_path: /usr/local/etc/scriptorium/config.yml
timeout: 10m timeout: 10m
render_debug: false render_debug: false

View File

@@ -68,6 +68,7 @@ normalize:
scriptorium: scriptorium:
binary: scriptorium binary: scriptorium
# credentials: [OPENROUTER_API_KEY] # Enable when this provider is configured.
config_path: /usr/local/etc/scriptorium/config.yml config_path: /usr/local/etc/scriptorium/config.yml
timeout: 10m timeout: 10m
render_debug: false render_debug: false

View File

@@ -1,20 +1,18 @@
scriptorium: character_items:
artifact_families: enabled: true
character_items: for_each: party.characters
enabled: true prompt_id: dnd.character_items
for_each: party.characters profile_id: production-placeholder
prompt_id: dnd.character_items output_path_pattern: artifacts/characters/{character_id}/items.md
profile_id: production-placeholder inputs:
output_path_pattern: artifacts/characters/{character_id}/items.md character_meta:
inputs: source: narratio.member_artifact.character_meta
character_meta: required: true
source: narratio.member_artifact.character_meta member_vars:
required: true character_id: character_id
member_vars: character_name: character.name
character_id: character_id aliases: character.alias_summary
character_name: character.name publish:
aliases: character.alias_summary enabled: true
publish: required: false
enabled: true dest_pattern: artifacts/characters/{character_id}/items.md
required: false
dest_pattern: artifacts/characters/{character_id}/items.md

View File

@@ -1,13 +1,11 @@
scriptorium: character_meta:
artifact_families: enabled: true
character_meta: for_each: party.characters
enabled: true prompt_id: dnd.character_meta
for_each: party.characters profile_id: production-placeholder
prompt_id: dnd.character_meta output_path_pattern: artifacts/characters/{character_id}/meta.md
profile_id: production-placeholder member_vars:
output_path_pattern: artifacts/characters/{character_id}/meta.md character_id: character_id
member_vars: character_name: character.name
character_id: character_id player_name: player.name
character_name: character.name class_summary: character.class_summary
player_name: player.name
class_summary: character.class_summary

View File

@@ -1,11 +1,8 @@
scriptorium: enabled: true
artifacts: prompt_id: dnd.player_handout
player_handout: profile_id: production-placeholder
enabled: true output_path: artifacts/player-handout.md
prompt_id: dnd.player_handout inputs:
profile_id: production-placeholder recap:
output_path: artifacts/player-handout.md source: narratio.artifact.session_recap
inputs: required: true
recap:
source: narratio.artifact.session_recap
required: true

View File

@@ -1,11 +1,8 @@
scriptorium: enabled: true
artifacts: prompt_id: dnd.session_recap
session_recap: profile_id: production-placeholder
enabled: true output_path: artifacts/session-recap.md
prompt_id: dnd.session_recap inputs:
profile_id: production-placeholder transcript:
output_path: artifacts/session-recap.md source: narratio.transcript.final_trimmed
inputs: required: true
transcript:
source: narratio.transcript.final_trimmed
required: true

View File

@@ -1,3 +1,15 @@
config:
sequences:
- destination: [publish, outputs]
key: source
mode: upsert
publish:
outputs:
- source: narratio.transcript.final_markdown
dest: transcripts/final.md
required: false
audita: audita:
proposal_profile: narratio-testing-model-placeholder proposal_profile: narratio-testing-model-placeholder
validation_profile: narratio-testing-validator-placeholder validation_profile: narratio-testing-validator-placeholder
@@ -9,6 +21,7 @@ scriptorium:
player_handout: player_handout:
profile_id: testing-placeholder profile_id: testing-placeholder
testing_notes: testing_notes:
extends: session_recap
enabled: false enabled: false
output_path: artifacts/testing-notes.md output_path: artifacts/testing-notes.md
artifact_families: artifact_families:

View File

@@ -1,13 +1,25 @@
# Copyable production-base/testing-overlay entry point. ConfigKit expands only # ConfigKit assembles these declared sources; destinations define artifact IDs.
# these explicit path and glob imports; Narratio never scans directories itself. config:
configkit:
imports: imports:
- path: conf.d/platform.yml - path: conf.d/platform.yml
required: true
- path: conf.d/storage.yml - path: conf.d/storage.yml
required: true
- path: conf.d/transcript.yml - path: conf.d/transcript.yml
required: true
- path: conf.d/publish.yml - path: conf.d/publish.yml
- glob: artifacts/*.yml required: true
- glob: artifact-families/*.yml - path: conf.d/local.yml
- path: artifacts/session_recap.yml
destination: [scriptorium, artifacts, session_recap]
required: true
- path: artifacts/player_handout.yml
destination: [scriptorium, artifacts, player_handout]
required: true
- dir: artifact-families
pattern: "*.yml"
destination: [scriptorium, artifact_families]
required: true
scriptorium: scriptorium:
binary: scriptorium binary: scriptorium

View File

@@ -0,0 +1,2 @@
inputs:
audio_dir: ../audio

View File

@@ -1,5 +1,7 @@
config:
imports:
- path: session-inputs/local-audio.yml
required: true
session_id: 2026-05-03 session_id: 2026-05-03
date: 2026-05-03 date: 2026-05-03
title: Sample Session title: Sample Session
inputs:
audio_dir: ./audio

11
go.mod
View File

@@ -1,14 +1,16 @@
module gitea.maximumdirect.net/eric/narratio module gitea.maximumdirect.net/eric/narratio
go 1.26.0 go 1.27.0
require ( require (
gitea.maximumdirect.net/eric/ConfigKit v0.4.2
github.com/aws/aws-sdk-go-v2/config v1.32.17 github.com/aws/aws-sdk-go-v2/config v1.32.17
github.com/aws/aws-sdk-go-v2/credentials v1.19.16 github.com/aws/aws-sdk-go-v2/credentials v1.19.16
github.com/aws/aws-sdk-go-v2/service/s3 v1.101.0 github.com/aws/aws-sdk-go-v2/service/s3 v1.101.0
github.com/aws/smithy-go v1.25.1 github.com/aws/smithy-go v1.25.1
github.com/google/go-cmp v0.7.0 github.com/google/go-cmp v0.7.0
go.maximumdirect.net/ckconfig v0.9.0
go.maximumdirect.net/commandkit v0.7.0
go.maximumdirect.net/configkit v1.2.1
golang.org/x/sync v0.22.0 golang.org/x/sync v0.22.0
golang.org/x/sys v0.47.0 golang.org/x/sys v0.47.0
gopkg.in/yaml.v3 v3.0.1 gopkg.in/yaml.v3 v3.0.1
@@ -29,5 +31,8 @@ require (
github.com/aws/aws-sdk-go-v2/service/sso v1.30.17 // indirect github.com/aws/aws-sdk-go-v2/service/sso v1.30.17 // indirect
github.com/aws/aws-sdk-go-v2/service/ssooidc v1.35.21 // indirect github.com/aws/aws-sdk-go-v2/service/ssooidc v1.35.21 // indirect
github.com/aws/aws-sdk-go-v2/service/sts v1.42.1 // indirect github.com/aws/aws-sdk-go-v2/service/sts v1.42.1 // indirect
go.yaml.in/yaml/v4 v4.0.0-rc.6 // indirect github.com/inconshreveable/mousetrap v1.1.0 // indirect
github.com/spf13/cobra v1.10.2 // indirect
github.com/spf13/pflag v1.1.0 // indirect
go.yaml.in/yaml/v4 v4.0.0 // indirect
) )

22
go.sum
View File

@@ -1,5 +1,3 @@
gitea.maximumdirect.net/eric/ConfigKit v0.4.2 h1:ZMxmv8pOnLtAx2hFTf8Z+pHKUbR89xErkBhwjr4yK24=
gitea.maximumdirect.net/eric/ConfigKit v0.4.2/go.mod h1:tYWpsrbLyu05r8+1MapWp5fN6ZrX9I8hU2xEPedYmYk=
github.com/aws/aws-sdk-go-v2 v1.41.7 h1:DWpAJt66FmnnaRIOT/8ASTucrvuDPZASqhhLey6tLY8= github.com/aws/aws-sdk-go-v2 v1.41.7 h1:DWpAJt66FmnnaRIOT/8ASTucrvuDPZASqhhLey6tLY8=
github.com/aws/aws-sdk-go-v2 v1.41.7/go.mod h1:4LAfZOPHNVNQEckOACQx60Y8pSRjIkNZQz1w92xpMJc= github.com/aws/aws-sdk-go-v2 v1.41.7/go.mod h1:4LAfZOPHNVNQEckOACQx60Y8pSRjIkNZQz1w92xpMJc=
github.com/aws/aws-sdk-go-v2/aws/protocol/eventstream v1.7.10 h1:gx1AwW1Iyk9Z9dD9F4akX5gnN3QZwUB20GGKH/I+Rho= github.com/aws/aws-sdk-go-v2/aws/protocol/eventstream v1.7.10 h1:gx1AwW1Iyk9Z9dD9F4akX5gnN3QZwUB20GGKH/I+Rho=
@@ -36,10 +34,26 @@ github.com/aws/aws-sdk-go-v2/service/sts v1.42.1 h1:F/M5Y9I3nwr2IEpshZgh1GeHpOIt
github.com/aws/aws-sdk-go-v2/service/sts v1.42.1/go.mod h1:mTNxImtovCOEEuD65mKW7DCsL+2gjEH+RPEAexAzAio= github.com/aws/aws-sdk-go-v2/service/sts v1.42.1/go.mod h1:mTNxImtovCOEEuD65mKW7DCsL+2gjEH+RPEAexAzAio=
github.com/aws/smithy-go v1.25.1 h1:J8ERsGSU7d+aCmdQur5Txg6bVoYelvQJgtZehD12GkI= github.com/aws/smithy-go v1.25.1 h1:J8ERsGSU7d+aCmdQur5Txg6bVoYelvQJgtZehD12GkI=
github.com/aws/smithy-go v1.25.1/go.mod h1:YE2RhdIuDbA5E5bTdciG9KrW3+TiEONeUWCqxX9i1Fc= github.com/aws/smithy-go v1.25.1/go.mod h1:YE2RhdIuDbA5E5bTdciG9KrW3+TiEONeUWCqxX9i1Fc=
github.com/cpuguy83/go-md2man/v2 v2.0.6/go.mod h1:oOW0eioCTA6cOiMLiUPZOpcVxMig6NIQQ7OS05n1F4g=
github.com/google/go-cmp v0.7.0 h1:wk8382ETsv4JYUZwIsn6YpYiWiBsYLSJiTsyBybVuN8= github.com/google/go-cmp v0.7.0 h1:wk8382ETsv4JYUZwIsn6YpYiWiBsYLSJiTsyBybVuN8=
github.com/google/go-cmp v0.7.0/go.mod h1:pXiqmnSA92OHEEa9HXL2W4E7lf9JzCmGVUdgjX3N/iU= github.com/google/go-cmp v0.7.0/go.mod h1:pXiqmnSA92OHEEa9HXL2W4E7lf9JzCmGVUdgjX3N/iU=
go.yaml.in/yaml/v4 v4.0.0-rc.6 h1:1h7H1ohdUh93/FyE4YaDa1Zh64K6VVbjF4K6WUxMtH4= github.com/inconshreveable/mousetrap v1.1.0 h1:wN+x4NVGpMsO7ErUn/mUI3vEoE6Jt13X2s0bqwp9tc8=
go.yaml.in/yaml/v4 v4.0.0-rc.6/go.mod h1:aZqd9kCMsGL7AuUv/m/PvWLdg5sjJsZ4oHDEnfPPfY0= github.com/inconshreveable/mousetrap v1.1.0/go.mod h1:vpF70FUmC8bwa3OWnCshd2FqLfsEA9PFc4w1p2J65bw=
github.com/russross/blackfriday/v2 v2.1.0/go.mod h1:+Rmxgy9KzJVeS9/2gXHxylqXiyQDYRxCVz55jmeOWTM=
github.com/spf13/cobra v1.10.2 h1:DMTTonx5m65Ic0GOoRY2c16WCbHxOOw6xxezuLaBpcU=
github.com/spf13/cobra v1.10.2/go.mod h1:7C1pvHqHw5A4vrJfjNwvOdzYu0Gml16OCs2GRiTUUS4=
github.com/spf13/pflag v1.0.9/go.mod h1:McXfInJRrz4CZXVZOBLb0bTZqETkiAhM9Iw0y3An2Bg=
github.com/spf13/pflag v1.1.0 h1:6W6MbVUrnMb8PEhjkqwsVLY7ryuzRfFHF4mQd7L94ag=
github.com/spf13/pflag v1.1.0/go.mod h1:McXfInJRrz4CZXVZOBLb0bTZqETkiAhM9Iw0y3An2Bg=
go.maximumdirect.net/ckconfig v0.9.0 h1:s9Ikga4wt4K1NpLCX9bLhm5vbcm1Fgqy9yk2lmO4Sss=
go.maximumdirect.net/ckconfig v0.9.0/go.mod h1:yGjFVr2UzjJjiwDdMwsKehuQfvvtv7rTEOIk5NQOY00=
go.maximumdirect.net/commandkit v0.7.0 h1:toLDGhHoVe6gBX5HWuzQ/Joz0cBqEhJXolW21m3axBk=
go.maximumdirect.net/commandkit v0.7.0/go.mod h1:sVp3JXKpm2YrP4Ie8Q3nWmQgwBdPN8uO+wQU72erDns=
go.maximumdirect.net/configkit v1.2.1 h1:f+/6WjNl6CULbMr6ZSVwi4aty9rmuDfJlvpeU7I+HZM=
go.maximumdirect.net/configkit v1.2.1/go.mod h1:ewu6blSokUDCMovy8JBXAdXRikGmlHXAQpFghnPWRfs=
go.yaml.in/yaml/v3 v3.0.4/go.mod h1:DhzuOOF2ATzADvBadXxruRBLzYTpT36CKvDb3+aBEFg=
go.yaml.in/yaml/v4 v4.0.0 h1:/LG1pNO84Z4l603j/xMn69CcS5OYhMQ/f7l2LoQUGuw=
go.yaml.in/yaml/v4 v4.0.0/go.mod h1:aZqd9kCMsGL7AuUv/m/PvWLdg5sjJsZ4oHDEnfPPfY0=
golang.org/x/sync v0.22.0 h1:SZjpbeLmrCk4xhRSZFNZW5gFUeCeFgjekvI/+gfScek= golang.org/x/sync v0.22.0 h1:SZjpbeLmrCk4xhRSZFNZW5gFUeCeFgjekvI/+gfScek=
golang.org/x/sync v0.22.0/go.mod h1:9xrNwdLfx4jkKbNva9FpL6vEN7evnE43NNNJQ2LF3+0= golang.org/x/sync v0.22.0/go.mod h1:9xrNwdLfx4jkKbNva9FpL6vEN7evnE43NNNJQ2LF3+0=
golang.org/x/sys v0.47.0 h1:o7XGOvZQCADBQQ4Y7VNq2dRWQR7JmOUW8Kxx4ZsNgWs= golang.org/x/sys v0.47.0 h1:o7XGOvZQCADBQQ4Y7VNq2dRWQR7JmOUW8Kxx4ZsNgWs=

View File

@@ -10,7 +10,7 @@ import (
"strings" "strings"
"time" "time"
configkit "gitea.maximumdirect.net/eric/ConfigKit" configkit "go.maximumdirect.net/configkit"
"gitea.maximumdirect.net/eric/narratio/internal/adapters/subprocess" "gitea.maximumdirect.net/eric/narratio/internal/adapters/subprocess"
"gitea.maximumdirect.net/eric/narratio/internal/fileops" "gitea.maximumdirect.net/eric/narratio/internal/fileops"
) )

View File

@@ -10,7 +10,7 @@ import (
"testing" "testing"
"time" "time"
configkit "gitea.maximumdirect.net/eric/ConfigKit" configkit "go.maximumdirect.net/configkit"
"gitea.maximumdirect.net/eric/narratio/internal/adapters/subprocess" "gitea.maximumdirect.net/eric/narratio/internal/adapters/subprocess"
) )

View File

@@ -3,7 +3,7 @@ package notarius
import ( import (
"context" "context"
configkit "gitea.maximumdirect.net/eric/ConfigKit" configkit "go.maximumdirect.net/configkit"
) )
// FakeRunner is a configurable in-memory runner for stage tests. // FakeRunner is a configurable in-memory runner for stage tests.

View File

@@ -5,7 +5,7 @@ import (
"context" "context"
"time" "time"
configkit "gitea.maximumdirect.net/eric/ConfigKit" configkit "go.maximumdirect.net/configkit"
) )
const ReceiptSchemaVersion = "notarius.run-result.v2" const ReceiptSchemaVersion = "notarius.run-result.v2"

View File

@@ -11,7 +11,7 @@ import (
"testing" "testing"
"time" "time"
configkit "gitea.maximumdirect.net/eric/ConfigKit" configkit "go.maximumdirect.net/configkit"
sharedsubprocess "gitea.maximumdirect.net/eric/narratio/internal/adapters/subprocess" sharedsubprocess "gitea.maximumdirect.net/eric/narratio/internal/adapters/subprocess"
) )

View File

@@ -3,6 +3,7 @@ package scriptorium
import ( import (
"context" "context"
"fmt" "fmt"
"slices"
"gitea.maximumdirect.net/eric/narratio/internal/fileops" "gitea.maximumdirect.net/eric/narratio/internal/fileops"
) )
@@ -65,6 +66,7 @@ func (f *FakeRunner) RunArtifact(ctx context.Context, req RunArtifactRequest) (A
if err := ctx.Err(); err != nil { if err := ctx.Err(); err != nil {
return ArtifactResult{}, err return ArtifactResult{}, err
} }
req.Credentials = slices.Clone(req.Credentials)
f.RunRequests = append(f.RunRequests, req) f.RunRequests = append(f.RunRequests, req)
if f.RunErr != nil { if f.RunErr != nil {
return ArtifactResult{}, f.RunErr return ArtifactResult{}, f.RunErr
@@ -105,6 +107,7 @@ func (f *FakeRunner) RenderArtifact(ctx context.Context, req RenderArtifactReque
if err := ctx.Err(); err != nil { if err := ctx.Err(); err != nil {
return ArtifactResult{}, err return ArtifactResult{}, err
} }
req.Credentials = slices.Clone(req.Credentials)
f.RenderRequests = append(f.RenderRequests, req) f.RenderRequests = append(f.RenderRequests, req)
if f.RenderErr != nil { if f.RenderErr != nil {
return ArtifactResult{}, f.RenderErr return ArtifactResult{}, f.RenderErr

View File

@@ -4,6 +4,8 @@ package scriptorium
import ( import (
"context" "context"
"time" "time"
configkit "go.maximumdirect.net/configkit"
) )
const ( const (
@@ -32,7 +34,7 @@ type RunArtifactRequest struct {
StderrLogPath string StderrLogPath string
GeneratedConfigPath string GeneratedConfigPath string
Timeout time.Duration Timeout time.Duration
APIKeyEnv string Credentials []configkit.Secret
WorkingDir string WorkingDir string
} }
@@ -49,7 +51,7 @@ type RenderArtifactRequest struct {
StderrLogPath string StderrLogPath string
GeneratedConfigPath string GeneratedConfigPath string
Timeout time.Duration Timeout time.Duration
APIKeyEnv string Credentials []configkit.Secret
WorkingDir string WorkingDir string
} }

View File

@@ -28,7 +28,12 @@ func (r *SubprocessRunner) RunArtifact(ctx context.Context, req RunArtifactReque
if r == nil { if r == nil {
return ArtifactResult{}, fmt.Errorf("scriptorium subprocess runner is nil") return ArtifactResult{}, fmt.Errorf("scriptorium subprocess runner is nil")
} }
credentialPresent, err := validateCommonRunRequest(req.Binary, req.ConfigPath, req.PromptID, req.OutputPath, req.Timeout, req.APIKeyEnv, req.InputPaths, req.Vars) err := validateCommonRunRequest(req.Binary, req.ConfigPath, req.PromptID, req.OutputPath, req.Timeout, req.InputPaths, req.Vars)
if err != nil {
return ArtifactResult{}, err
}
envOverrides, sensitiveNames, err := subprocess.CredentialEnvironment(req.Credentials)
if err != nil { if err != nil {
return ArtifactResult{}, err return ArtifactResult{}, err
} }
@@ -46,8 +51,7 @@ func (r *SubprocessRunner) RunArtifact(ctx context.Context, req RunArtifactReque
InputPaths: cloneStringMap(req.InputPaths), InputPaths: cloneStringMap(req.InputPaths),
Vars: cloneStringMap(req.Vars), Vars: cloneStringMap(req.Vars),
OutputPath: req.OutputPath, OutputPath: req.OutputPath,
APIKeyEnv: strings.TrimSpace(req.APIKeyEnv), CredentialNames: sensitiveNames,
APIKeyEnvPresent: credentialPresent,
WorkingDir: req.WorkingDir, WorkingDir: req.WorkingDir,
RenderFormat: "", RenderFormat: "",
RenderPromptStore: false, RenderPromptStore: false,
@@ -56,7 +60,6 @@ func (r *SubprocessRunner) RunArtifact(ctx context.Context, req RunArtifactReque
} }
} }
envOverrides, sensitiveNames := credentialEnvironment(req.APIKeyEnv)
runRes, runErr := subprocess.Run(ctx, subprocess.RunRequest{ runRes, runErr := subprocess.Run(ctx, subprocess.RunRequest{
Executable: req.Binary, Executable: req.Binary,
Args: args, Args: args,
@@ -80,12 +83,11 @@ func (r *SubprocessRunner) RunArtifact(ctx context.Context, req RunArtifactReque
PromptID: req.PromptID, PromptID: req.PromptID,
ProfileID: req.ProfileID, ProfileID: req.ProfileID,
Metadata: map[string]any{ Metadata: map[string]any{
"adapter": "scriptorium_subprocess", "adapter": "scriptorium_subprocess",
"config_path": strings.TrimSpace(req.ConfigPath), "config_path": strings.TrimSpace(req.ConfigPath),
"inputs_count": len(req.InputPaths), "inputs_count": len(req.InputPaths),
"vars_count": len(req.Vars), "vars_count": len(req.Vars),
"api_key_env": strings.TrimSpace(req.APIKeyEnv), "credential_env_names": sensitiveNames,
"api_key_env_present": credentialPresent,
}, },
} }
@@ -114,7 +116,12 @@ func (r *SubprocessRunner) RenderArtifact(ctx context.Context, req RenderArtifac
if r == nil { if r == nil {
return ArtifactResult{}, fmt.Errorf("scriptorium subprocess runner is nil") return ArtifactResult{}, fmt.Errorf("scriptorium subprocess runner is nil")
} }
credentialPresent, err := validateCommonRunRequest(req.Binary, req.ConfigPath, req.PromptID, req.OutputPath, req.Timeout, req.APIKeyEnv, req.InputPaths, req.Vars) err := validateCommonRunRequest(req.Binary, req.ConfigPath, req.PromptID, req.OutputPath, req.Timeout, req.InputPaths, req.Vars)
if err != nil {
return ArtifactResult{}, err
}
envOverrides, sensitiveNames, err := subprocess.CredentialEnvironment(req.Credentials)
if err != nil { if err != nil {
return ArtifactResult{}, err return ArtifactResult{}, err
} }
@@ -132,8 +139,7 @@ func (r *SubprocessRunner) RenderArtifact(ctx context.Context, req RenderArtifac
InputPaths: cloneStringMap(req.InputPaths), InputPaths: cloneStringMap(req.InputPaths),
Vars: cloneStringMap(req.Vars), Vars: cloneStringMap(req.Vars),
OutputPath: req.OutputPath, OutputPath: req.OutputPath,
APIKeyEnv: strings.TrimSpace(req.APIKeyEnv), CredentialNames: sensitiveNames,
APIKeyEnvPresent: credentialPresent,
WorkingDir: req.WorkingDir, WorkingDir: req.WorkingDir,
RenderFormat: "json", RenderFormat: "json",
RenderPromptStore: false, RenderPromptStore: false,
@@ -142,7 +148,6 @@ func (r *SubprocessRunner) RenderArtifact(ctx context.Context, req RenderArtifac
} }
} }
envOverrides, sensitiveNames := credentialEnvironment(req.APIKeyEnv)
runRes, runErr := subprocess.Run(ctx, subprocess.RunRequest{ runRes, runErr := subprocess.Run(ctx, subprocess.RunRequest{
Executable: req.Binary, Executable: req.Binary,
Args: args, Args: args,
@@ -166,13 +171,12 @@ func (r *SubprocessRunner) RenderArtifact(ctx context.Context, req RenderArtifac
PromptID: req.PromptID, PromptID: req.PromptID,
ProfileID: req.ProfileID, ProfileID: req.ProfileID,
Metadata: map[string]any{ Metadata: map[string]any{
"adapter": "scriptorium_subprocess", "adapter": "scriptorium_subprocess",
"config_path": strings.TrimSpace(req.ConfigPath), "config_path": strings.TrimSpace(req.ConfigPath),
"inputs_count": len(req.InputPaths), "inputs_count": len(req.InputPaths),
"vars_count": len(req.Vars), "vars_count": len(req.Vars),
"api_key_env": strings.TrimSpace(req.APIKeyEnv), "credential_env_names": sensitiveNames,
"api_key_env_present": credentialPresent, "format": "json",
"format": "json",
}, },
} }
@@ -191,57 +195,39 @@ func validateCommonRunRequest(
promptID string, promptID string,
outputPath string, outputPath string,
timeout time.Duration, timeout time.Duration,
apiKeyEnv string,
inputPaths map[string]string, inputPaths map[string]string,
vars map[string]string, vars map[string]string,
) (bool, error) { ) error {
if strings.TrimSpace(binary) == "" { if strings.TrimSpace(binary) == "" {
return false, fmt.Errorf("scriptorium binary is required") return fmt.Errorf("scriptorium binary is required")
} }
if strings.TrimSpace(configPath) == "" && configPath != "" { if strings.TrimSpace(configPath) == "" && configPath != "" {
return false, fmt.Errorf("scriptorium config path must be non-empty when provided") return fmt.Errorf("scriptorium config path must be non-empty when provided")
} }
if strings.TrimSpace(promptID) == "" { if strings.TrimSpace(promptID) == "" {
return false, fmt.Errorf("scriptorium prompt id is required") return fmt.Errorf("scriptorium prompt id is required")
} }
if strings.TrimSpace(outputPath) == "" { if strings.TrimSpace(outputPath) == "" {
return false, fmt.Errorf("scriptorium output path is required") return fmt.Errorf("scriptorium output path is required")
} }
if timeout <= 0 { if timeout <= 0 {
return false, fmt.Errorf("scriptorium timeout must be > 0") return fmt.Errorf("scriptorium timeout must be > 0")
} }
for name, path := range inputPaths { for name, path := range inputPaths {
if strings.TrimSpace(name) == "" { if strings.TrimSpace(name) == "" {
return false, fmt.Errorf("scriptorium input names must be non-empty") return fmt.Errorf("scriptorium input names must be non-empty")
} }
if strings.TrimSpace(path) == "" { if strings.TrimSpace(path) == "" {
return false, fmt.Errorf("scriptorium input %q path is required", name) return fmt.Errorf("scriptorium input %q path is required", name)
} }
} }
for name := range vars { for name := range vars {
if strings.TrimSpace(name) == "" { if strings.TrimSpace(name) == "" {
return false, fmt.Errorf("scriptorium variable names must be non-empty") return fmt.Errorf("scriptorium variable names must be non-empty")
} }
} }
trimmedEnv := strings.TrimSpace(apiKeyEnv) return nil
if trimmedEnv == "" {
return false, nil
}
value, ok := os.LookupEnv(trimmedEnv)
if !ok || strings.TrimSpace(value) == "" {
return false, fmt.Errorf("scriptorium required credential environment variable %s is not set", trimmedEnv)
}
return true, nil
}
func credentialEnvironment(apiKeyEnv string) (map[string]string, []string) {
name := strings.TrimSpace(apiKeyEnv)
if name == "" {
return nil, nil
}
value, _ := os.LookupEnv(name)
return map[string]string{name: value}, []string{name}
} }
func buildRunArgs(req RunArtifactRequest) []string { func buildRunArgs(req RunArtifactRequest) []string {
@@ -258,9 +244,6 @@ func buildRunArgs(req RunArtifactRequest) []string {
for _, kv := range sortedKeyValues(req.Vars) { for _, kv := range sortedKeyValues(req.Vars) {
args = append(args, "--var", kv) args = append(args, "--var", kv)
} }
if envName := strings.TrimSpace(req.APIKeyEnv); envName != "" {
args = append(args, "--api-key-env", envName)
}
args = append(args, "--timeout", req.Timeout.String()) args = append(args, "--timeout", req.Timeout.String())
args = append(args, "--out", req.OutputPath) args = append(args, "--out", req.OutputPath)
return args return args
@@ -280,9 +263,6 @@ func buildRenderArgs(req RenderArtifactRequest) []string {
for _, kv := range sortedKeyValues(req.Vars) { for _, kv := range sortedKeyValues(req.Vars) {
args = append(args, "--var", kv) args = append(args, "--var", kv)
} }
if envName := strings.TrimSpace(req.APIKeyEnv); envName != "" {
args = append(args, "--api-key-env", envName)
}
args = append(args, "--timeout", req.Timeout.String()) args = append(args, "--timeout", req.Timeout.String())
args = append(args, "--format", "json") args = append(args, "--format", "json")
args = append(args, "--out", req.OutputPath) args = append(args, "--out", req.OutputPath)
@@ -316,8 +296,7 @@ type invocationPayload struct {
InputPaths map[string]string InputPaths map[string]string
Vars map[string]string Vars map[string]string
OutputPath string OutputPath string
APIKeyEnv string CredentialNames []string
APIKeyEnvPresent bool
WorkingDir string WorkingDir string
RenderFormat string RenderFormat string
RenderPromptStore bool RenderPromptStore bool
@@ -336,8 +315,7 @@ func writeInvocationConfig(path string, payload invocationPayload) error {
"input_paths": payload.InputPaths, "input_paths": payload.InputPaths,
"vars": payload.Vars, "vars": payload.Vars,
"output_path": payload.OutputPath, "output_path": payload.OutputPath,
"api_key_env": payload.APIKeyEnv, "credential_env_names": payload.CredentialNames,
"api_key_env_present": payload.APIKeyEnvPresent,
"working_dir": payload.WorkingDir, "working_dir": payload.WorkingDir,
"render_format": payload.RenderFormat, "render_format": payload.RenderFormat,
"render_prompt_logged": payload.RenderPromptStore, "render_prompt_logged": payload.RenderPromptStore,

View File

@@ -9,6 +9,8 @@ import (
"strings" "strings"
"testing" "testing"
"time" "time"
configkit "go.maximumdirect.net/configkit"
) )
func TestSubprocessRunnerRunSuccessBuildsDeterministicArgsAndCapturesLogs(t *testing.T) { func TestSubprocessRunnerRunSuccessBuildsDeterministicArgsAndCapturesLogs(t *testing.T) {
@@ -16,6 +18,13 @@ func TestSubprocessRunnerRunSuccessBuildsDeterministicArgsAndCapturesLogs(t *tes
t.Setenv("GO_WANT_SCRIPTORIUM_HELPER", "1") t.Setenv("GO_WANT_SCRIPTORIUM_HELPER", "1")
t.Setenv("SCRIPTORIUM_HELPER_MODE", "run_success") t.Setenv("SCRIPTORIUM_HELPER_MODE", "run_success")
t.Setenv("OPENAI_KEY_SOURCE", "super-secret") t.Setenv("OPENAI_KEY_SOURCE", "super-secret")
loaded, err := configkit.Load[struct {
Credentials []configkit.Secret `yaml:"credentials"`
}](configkit.Bytes("test.yml", []byte("credentials: [OPENAI_KEY_SOURCE]\n")))
if err != nil {
t.Fatal(err)
}
t.Setenv("OPENAI_KEY_SOURCE", "changed-after-load")
recordPath := filepath.Join(t.TempDir(), "record.json") recordPath := filepath.Join(t.TempDir(), "record.json")
t.Setenv("SCRIPTORIUM_HELPER_RECORD_PATH", recordPath) t.Setenv("SCRIPTORIUM_HELPER_RECORD_PATH", recordPath)
@@ -34,7 +43,7 @@ func TestSubprocessRunnerRunSuccessBuildsDeterministicArgsAndCapturesLogs(t *tes
StderrLogPath: filepath.Join(dir, "logs", "scriptorium.run.stderr.log"), StderrLogPath: filepath.Join(dir, "logs", "scriptorium.run.stderr.log"),
GeneratedConfigPath: filepath.Join(dir, "config", "scriptorium.run.generated.yml"), GeneratedConfigPath: filepath.Join(dir, "config", "scriptorium.run.generated.yml"),
Timeout: mustParseScriptoriumDuration(t, "2s"), Timeout: mustParseScriptoriumDuration(t, "2s"),
APIKeyEnv: "OPENAI_KEY_SOURCE", Credentials: loaded.Config.Credentials,
} }
writeScriptoriumFile(t, req.InputPaths["transcript"], `{"segments":[]}`) writeScriptoriumFile(t, req.InputPaths["transcript"], `{"segments":[]}`)
writeScriptoriumFile(t, req.InputPaths["other"], "notes\n") writeScriptoriumFile(t, req.InputPaths["other"], "notes\n")
@@ -70,7 +79,6 @@ func TestSubprocessRunnerRunSuccessBuildsDeterministicArgsAndCapturesLogs(t *tes
"--input", "transcript=" + req.InputPaths["transcript"], "--input", "transcript=" + req.InputPaths["transcript"],
"--var", "campaign_name=Icewind Dale", "--var", "campaign_name=Icewind Dale",
"--var", "session_id=2026-05-03", "--var", "session_id=2026-05-03",
"--api-key-env", "OPENAI_KEY_SOURCE",
"--timeout", "2s", "--timeout", "2s",
"--out", req.OutputPath, "--out", req.OutputPath,
} }
@@ -94,13 +102,31 @@ func TestSubprocessRunnerRunExitCodeOneFails(t *testing.T) {
t.Setenv("GO_WANT_SCRIPTORIUM_HELPER", "1") t.Setenv("GO_WANT_SCRIPTORIUM_HELPER", "1")
t.Setenv("SCRIPTORIUM_HELPER_MODE", "fail_exit1") t.Setenv("SCRIPTORIUM_HELPER_MODE", "fail_exit1")
t.Setenv("SCRIPTORIUM_HELPER_RECORD_PATH", filepath.Join(t.TempDir(), "record.json")) t.Setenv("SCRIPTORIUM_HELPER_RECORD_PATH", filepath.Join(t.TempDir(), "record.json"))
t.Setenv("CUSTOM_PROVIDER_KEY", "synthetic-failure-secret")
loaded, loadErr := configkit.Load[struct {
Credentials []configkit.Secret `yaml:"credentials"`
}](configkit.Bytes("test.yml", []byte("credentials: [CUSTOM_PROVIDER_KEY]\n")))
if loadErr != nil {
t.Fatal(loadErr)
}
runner := NewSubprocessRunner() runner := NewSubprocessRunner()
req := runReqForTest(t, writeScriptoriumHelperWrapper(t)) req := runReqForTest(t, writeScriptoriumHelperWrapper(t))
req.Credentials = loaded.Config.Credentials
res, err := runner.RunArtifact(context.Background(), req) res, err := runner.RunArtifact(context.Background(), req)
if err == nil { if err == nil {
t.Fatal("RunArtifact() error = nil, want non-nil") t.Fatal("RunArtifact() error = nil, want non-nil")
} }
if strings.Contains(err.Error(), "synthetic-failure-secret") {
t.Fatal("failure leaked credential")
}
data, readErr := os.ReadFile(req.StderrLogPath)
if readErr != nil {
t.Fatal(readErr)
}
if strings.Contains(string(data), "synthetic-failure-secret") || !strings.Contains(string(data), "<redacted>") {
t.Fatal("failure log did not redact selected credential")
}
if res.ExitCode != 1 { if res.ExitCode != 1 {
t.Fatalf("ExitCode = %d, want 1", res.ExitCode) t.Fatalf("ExitCode = %d, want 1", res.ExitCode)
} }
@@ -245,6 +271,7 @@ func TestScriptoriumSubprocessHelper(t *testing.T) {
os.Exit(0) os.Exit(0)
case "fail_exit1": case "fail_exit1":
_, _ = os.Stderr.WriteString("scriptorium helper failure\n") _, _ = os.Stderr.WriteString("scriptorium helper failure\n")
_, _ = os.Stderr.WriteString(os.Getenv("CUSTOM_PROVIDER_KEY"))
os.Exit(1) os.Exit(1)
case "fail_exit2_with_output": case "fail_exit2_with_output":
writeScriptoriumHelperFile(outputPath, "validation failed artifact\n") writeScriptoriumHelperFile(outputPath, "validation failed artifact\n")

View File

@@ -14,7 +14,7 @@ import (
"github.com/aws/aws-sdk-go-v2/service/s3/types" "github.com/aws/aws-sdk-go-v2/service/s3/types"
"github.com/aws/smithy-go" "github.com/aws/smithy-go"
configkit "gitea.maximumdirect.net/eric/ConfigKit" configkit "go.maximumdirect.net/configkit"
"gitea.maximumdirect.net/eric/narratio/internal/config" "gitea.maximumdirect.net/eric/narratio/internal/config"
) )

View File

@@ -3,7 +3,7 @@ package subprocess
import ( import (
"fmt" "fmt"
configkit "gitea.maximumdirect.net/eric/ConfigKit" configkit "go.maximumdirect.net/configkit"
) )
// CredentialEnvironment returns captured secret values and names for a child // CredentialEnvironment returns captured secret values and names for a child

View File

@@ -4,7 +4,7 @@ import (
"reflect" "reflect"
"testing" "testing"
configkit "gitea.maximumdirect.net/eric/ConfigKit" configkit "go.maximumdirect.net/configkit"
) )
func TestCredentialEnvironmentUsesCapturedReferences(t *testing.T) { func TestCredentialEnvironmentUsesCapturedReferences(t *testing.T) {

View File

@@ -9,27 +9,14 @@ import (
"gitea.maximumdirect.net/eric/narratio/internal/config" "gitea.maximumdirect.net/eric/narratio/internal/config"
) )
type artifactSelectionFlag struct { func normalizeArtifactNames(values []string) ([]string, error) {
values []string if len(values) == 0 {
}
func (f *artifactSelectionFlag) String() string {
return strings.Join(f.values, ",")
}
func (f *artifactSelectionFlag) Set(value string) error {
f.values = append(f.values, value)
return nil
}
func (f *artifactSelectionFlag) Normalize() ([]string, error) {
if len(f.values) == 0 {
return nil, nil return nil, nil
} }
seen := map[string]struct{}{} seen := map[string]struct{}{}
out := make([]string, 0, len(f.values)) out := make([]string, 0, len(values))
for _, raw := range f.values { for _, raw := range values {
for _, part := range strings.Split(raw, ",") { for _, part := range strings.Split(raw, ",") {
name := strings.TrimSpace(part) name := strings.TrimSpace(part)
if name == "" { if name == "" {
@@ -47,11 +34,6 @@ func (f *artifactSelectionFlag) Normalize() ([]string, error) {
return out, nil return out, nil
} }
func validateSelectedArtifacts(cfg *config.Config, selected []string) error {
_, err := resolveEffectiveArtifacts(cfg, selected)
return err
}
func resolveEffectiveArtifacts(cfg *config.Config, selected []string) (artifacts.EffectiveArtifactSet, error) { func resolveEffectiveArtifacts(cfg *config.Config, selected []string) (artifacts.EffectiveArtifactSet, error) {
if cfg == nil || cfg.Pipeline == nil || cfg.Pipeline.Scriptorium == nil { if cfg == nil || cfg.Pipeline == nil || cfg.Pipeline.Scriptorium == nil {
if len(selected) == 0 { if len(selected) == 0 {
@@ -59,7 +41,7 @@ func resolveEffectiveArtifacts(cfg *config.Config, selected []string) (artifacts
} }
return artifacts.EffectiveArtifactSet{}, fmt.Errorf("--artifacts requires pipeline.scriptorium.artifacts to be configured") return artifacts.EffectiveArtifactSet{}, fmt.Errorf("--artifacts requires pipeline.scriptorium.artifacts to be configured")
} }
configured := artifacts.ConfiguredArtifactDefinitions(cfg.Pipeline.Scriptorium.Artifacts) configured := artifacts.ConfiguredArtifactDefinitions(cfg.ConcreteArtifacts())
normalized, err := normalizeArtifactSelection(cfg, selected) normalized, err := normalizeArtifactSelection(cfg, selected)
if err != nil { if err != nil {
return artifacts.EffectiveArtifactSet{}, err return artifacts.EffectiveArtifactSet{}, err
@@ -74,18 +56,18 @@ func resolveEffectiveArtifacts(cfg *config.Config, selected []string) (artifacts
} }
return artifacts.EffectiveArtifactSet{}, err return artifacts.EffectiveArtifactSet{}, err
} }
if err := validateEffectiveArtifactConfiguration(cfg.Pipeline.Scriptorium.Artifacts, effective); err != nil { if err := validateEffectiveArtifactConfiguration(cfg.ConcreteArtifacts(), effective); err != nil {
return artifacts.EffectiveArtifactSet{}, err return artifacts.EffectiveArtifactSet{}, err
} }
return effective.WithOrigins(effectiveArtifactOrigins(cfg.Pipeline)), nil return effective.WithOrigins(effectiveArtifactOrigins(cfg.ArtifactCatalog)), nil
} }
func normalizeArtifactSelection(cfg *config.Config, selected []string) ([]string, error) { func normalizeArtifactSelection(cfg *config.Config, selected []string) ([]string, error) {
if len(selected) == 0 { if len(selected) == 0 {
return nil, nil return nil, nil
} }
configured := cfg.Pipeline.Scriptorium.Artifacts configured := cfg.ConcreteArtifacts()
families := config.ArtifactFamilies(cfg.Pipeline).Families families := config.ArtifactFamilies(cfg.ArtifactCatalog).Families
set := make(map[string]struct{}, len(selected)) set := make(map[string]struct{}, len(selected))
for _, raw := range selected { for _, raw := range selected {
key := strings.TrimSpace(raw) key := strings.TrimSpace(raw)
@@ -111,8 +93,8 @@ func normalizeArtifactSelection(cfg *config.Config, selected []string) ([]string
return normalized, nil return normalized, nil
} }
func effectiveArtifactOrigins(pipeline *config.PipelineConfig) map[string]artifacts.EffectiveArtifactOrigin { func effectiveArtifactOrigins(derived *config.ArtifactCatalog) map[string]artifacts.EffectiveArtifactOrigin {
catalog := config.ArtifactFamilies(pipeline) catalog := config.ArtifactFamilies(derived)
origins := make(map[string]artifacts.EffectiveArtifactOrigin, len(catalog.Members)) origins := make(map[string]artifacts.EffectiveArtifactOrigin, len(catalog.Members))
for key, member := range catalog.Members { for key, member := range catalog.Members {
origins[key] = artifacts.EffectiveArtifactOrigin{Family: member.Family, CharacterID: member.CharacterID} origins[key] = artifacts.EffectiveArtifactOrigin{Family: member.Family, CharacterID: member.CharacterID}

View File

@@ -13,26 +13,26 @@ import (
"gitea.maximumdirect.net/eric/narratio/internal/manifest" "gitea.maximumdirect.net/eric/narratio/internal/manifest"
) )
func TestExecuteRunStageArtifactsUnsupportedStageFails(t *testing.T) { func TestExecuteRunSingleStageArtifactsUnsupportedStageFails(t *testing.T) {
workspaceRoot := t.TempDir() workspaceRoot := t.TempDir()
pipelinePath, campaignPath, sessionPath := writeValidConfigFilesWithScriptoriumArtifacts(t, workspaceRoot) pipelinePath, campaignPath, sessionPath := writeValidConfigFilesWithScriptoriumArtifacts(t, workspaceRoot)
var stdout bytes.Buffer var stdout bytes.Buffer
var stderr bytes.Buffer var stderr bytes.Buffer
code := Execute( code := executeForTest(
[]string{"run-stage", "extract", "2026-05-03", "--config", pipelinePath, "--campaign-file", campaignPath, "--session", sessionPath, "--artifacts", "session_recap"}, []string{"run", "2026-05-03", "--stage", "extract", "--config", pipelinePath, "--campaign-file", campaignPath, "--session-file", sessionPath, "--artifacts", "session_recap"},
&stdout, &stdout,
&stderr, &stderr,
) )
if code == 0 { if code == 0 {
t.Fatal("exit code = 0, want non-zero") t.Fatal("exit code = 0, want non-zero")
} }
if !strings.Contains(stderr.String(), `run-stage: --artifacts is only supported for stages "analyze" and "publish"`) { if !strings.Contains(stderr.String(), `--artifacts requires a selected range containing analyze or publish`) {
t.Fatalf("stderr = %q, want stage-gating error", stderr.String()) t.Fatalf("stderr = %q, want stage-gating error", stderr.String())
} }
} }
func TestExecuteRunStagePublishPropagatesSelectedArtifacts(t *testing.T) { func TestExecuteRunSingleStagePublishPropagatesSelectedArtifacts(t *testing.T) {
workspaceRoot := t.TempDir() workspaceRoot := t.TempDir()
pipelinePath, campaignPath, sessionPath := writeValidConfigFilesWithScriptoriumArtifacts(t, workspaceRoot) pipelinePath, campaignPath, sessionPath := writeValidConfigFilesWithScriptoriumArtifacts(t, workspaceRoot)
@@ -49,11 +49,9 @@ func TestExecuteRunStagePublishPropagatesSelectedArtifacts(t *testing.T) {
var stdout bytes.Buffer var stdout bytes.Buffer
var stderr bytes.Buffer var stderr bytes.Buffer
code := executeWithPipelineExecutor( code := executeWithPipelineExecutor(
[]string{ []string{"run", "2026-05-03", "--stage", "publish",
"run-stage", "publish", "2026-05-03",
"--config", pipelinePath, "--config", pipelinePath,
"--campaign-file", campaignPath, "--campaign-file", campaignPath, "--session-file", sessionPath,
"--session", sessionPath,
"--artifacts", "session_recap", "--artifacts", "session_recap",
}, },
&stdout, &stdout,
@@ -77,20 +75,20 @@ func TestExecuteUnknownArtifactsFailValidation(t *testing.T) {
var stdout bytes.Buffer var stdout bytes.Buffer
var stderr bytes.Buffer var stderr bytes.Buffer
code := Execute( code := executeForTest(
[]string{"run", "2026-05-03", "--config", pipelinePath, "--campaign-file", campaignPath, "--session", sessionPath, "--artifacts", "unknown_artifact"}, []string{"run", "2026-05-03", "--config", pipelinePath, "--campaign-file", campaignPath, "--session-file", sessionPath, "--artifacts", "unknown_artifact"},
&stdout, &stdout,
&stderr, &stderr,
) )
if code == 0 { if code == 0 {
t.Fatal("exit code = 0, want non-zero") t.Fatal("exit code = 0, want non-zero")
} }
if !strings.Contains(stderr.String(), `run: --artifacts includes unknown artifact "unknown_artifact"`) { if !strings.Contains(stderr.String(), `--artifacts includes unknown artifact "unknown_artifact"`) {
t.Fatalf("stderr = %q, want unknown-artifact validation error", stderr.String()) t.Fatalf("stderr = %q, want unknown-artifact validation error", stderr.String())
} }
} }
func TestRunStageArtifactsDoesNotImplyForce(t *testing.T) { func TestRunSingleStageArtifactsDoesNotImplyForce(t *testing.T) {
workspaceRoot := t.TempDir() workspaceRoot := t.TempDir()
pipelinePath, campaignPath, sessionPath := writeValidConfigFilesWithScriptoriumArtifacts(t, workspaceRoot) pipelinePath, campaignPath, sessionPath := writeValidConfigFilesWithScriptoriumArtifacts(t, workspaceRoot)
manifestPath := filepath.Join(workspaceRoot, "work", "sample-campaign", "2026-05-03", "manifest.json") manifestPath := filepath.Join(workspaceRoot, "work", "sample-campaign", "2026-05-03", "manifest.json")
@@ -102,16 +100,18 @@ func TestRunStageArtifactsDoesNotImplyForce(t *testing.T) {
t.Fatalf("save manifest: %v", err) t.Fatalf("save manifest: %v", err)
} }
seedInvocationPrerequisites(t, workspaceRoot, "analyze")
var out bytes.Buffer var out bytes.Buffer
err := RunStage( err := invokeNativeCommand(
context.Background(), context.Background(),
[]string{"analyze", "2026-05-03", "--config", pipelinePath, "--campaign-file", campaignPath, "--session", sessionPath, "--artifacts", "session_recap,session_recap"}, []string{"run", "--stage", "analyze", "2026-05-03", "--config", pipelinePath, "--campaign-file", campaignPath, "--session-file", sessionPath, "--artifacts", "session_recap,session_recap"},
&out, &out,
) )
if err != nil { if err != nil {
t.Fatalf("RunStage() error = %v", err) t.Fatalf("single-stage run error = %v", err)
} }
if !strings.Contains(out.String(), "stage=analyze executed=1 skipped=0 force=false") { if !runCountsMatch(t, out.Bytes(), 1, 0, "analyze") {
t.Fatalf("output = %q, want legacy analyze evidence rebuilt without implying force", out.String()) t.Fatalf("output = %q, want legacy analyze evidence rebuilt without implying force", out.String())
} }
} }
@@ -122,9 +122,9 @@ func TestRunArtifactsWithSucceededAnalyzeSkipsUnlessForced(t *testing.T) {
manifestPath := filepath.Join(workspaceRoot, "work", "sample-campaign", "2026-05-03", "manifest.json") manifestPath := filepath.Join(workspaceRoot, "work", "sample-campaign", "2026-05-03", "manifest.json")
store := &manifest.LocalStore{} store := &manifest.LocalStore{}
if err := RunStage( if err := invokeNativeCommand(
context.Background(), context.Background(),
[]string{"prepare", "2026-05-03", "--config", pipelinePath, "--campaign-file", campaignPath, "--session", sessionPath}, []string{"run", "--stage", "prepare", "2026-05-03", "--config", pipelinePath, "--campaign-file", campaignPath, "--session-file", sessionPath},
&bytes.Buffer{}, &bytes.Buffer{},
); err != nil { ); err != nil {
t.Fatalf("seed prepare stage: %v", err) t.Fatalf("seed prepare stage: %v", err)
@@ -143,15 +143,15 @@ func TestRunArtifactsWithSucceededAnalyzeSkipsUnlessForced(t *testing.T) {
} }
var out bytes.Buffer var out bytes.Buffer
err = Run( err = invokeNativeCommand(
context.Background(), context.Background(),
[]string{"2026-05-03", "--config", pipelinePath, "--campaign-file", campaignPath, "--session", sessionPath, "--artifacts", "session_recap"}, []string{"run", "2026-05-03", "--config", pipelinePath, "--campaign-file", campaignPath, "--session-file", sessionPath, "--artifacts", "session_recap"},
&out, &out,
) )
if err != nil { if err != nil {
t.Fatalf("Run() error = %v", err) t.Fatalf("Run() error = %v", err)
} }
if !strings.Contains(out.String(), "executed=5 skipped=9") { if !runCountsMatch(t, out.Bytes(), 5, 9, "") {
t.Fatalf("output = %q, want extract reconsidered and legacy analyze plus delivery rebuilt", out.String()) t.Fatalf("output = %q, want extract reconsidered and legacy analyze plus delivery rebuilt", out.String())
} }
} }
@@ -176,7 +176,7 @@ func TestExecuteAnalyzeForceRunsAnalyze(t *testing.T) {
var stdout bytes.Buffer var stdout bytes.Buffer
var stderr bytes.Buffer var stderr bytes.Buffer
code := executeWithPipelineExecutor( code := executeWithPipelineExecutor(
[]string{"analyze", "2026-05-03", "--config", pipelinePath, "--campaign-file", campaignPath, "--session", sessionPath}, []string{"run", "--stage", "analyze", "--force", "2026-05-03", "--config", pipelinePath, "--campaign-file", campaignPath, "--session-file", sessionPath},
&stdout, &stdout,
&stderr, &stderr,
executor, executor,
@@ -190,7 +190,7 @@ func TestExecuteAnalyzeForceRunsAnalyze(t *testing.T) {
if !capturedForce { if !capturedForce {
t.Fatal("captured force = false, want true") t.Fatal("captured force = false, want true")
} }
if !strings.Contains(stdout.String(), "narratio analyze: executed=1 skipped=0 force=true; manifest=") { if !runCountsMatch(t, stdout.Bytes(), 1, 0, "") {
t.Fatalf("stdout = %q, want analyze summary", stdout.String()) t.Fatalf("stdout = %q, want analyze summary", stdout.String())
} }
} }
@@ -208,12 +208,9 @@ func TestExecuteAnalyzePropagatesSelectedArtifacts(t *testing.T) {
var stdout bytes.Buffer var stdout bytes.Buffer
var stderr bytes.Buffer var stderr bytes.Buffer
code := executeWithPipelineExecutor( code := executeWithPipelineExecutor(
[]string{ []string{"run", "--stage", "analyze", "--force", "2026-05-03",
"analyze",
"2026-05-03",
"--config", pipelinePath, "--config", pipelinePath,
"--campaign-file", campaignPath, "--campaign-file", campaignPath, "--session-file", sessionPath,
"--session", sessionPath,
"--artifacts", "player_handout,session_recap", "--artifacts", "player_handout,session_recap",
}, },
&stdout, &stdout,
@@ -234,56 +231,31 @@ func TestExecuteAnalyzeUnknownArtifactFailsValidation(t *testing.T) {
var stdout bytes.Buffer var stdout bytes.Buffer
var stderr bytes.Buffer var stderr bytes.Buffer
code := Execute( code := executeForTest(
[]string{"analyze", "2026-05-03", "--config", pipelinePath, "--campaign-file", campaignPath, "--session", sessionPath, "--artifacts", "unknown_artifact"}, []string{"run", "--stage", "analyze", "--force", "2026-05-03", "--config", pipelinePath, "--campaign-file", campaignPath, "--session-file", sessionPath, "--artifacts", "unknown_artifact"},
&stdout, &stdout,
&stderr, &stderr,
) )
if code == 0 { if code == 0 {
t.Fatal("exit code = 0, want non-zero") t.Fatal("exit code = 0, want non-zero")
} }
if !strings.Contains(stderr.String(), `analyze: --artifacts includes unknown artifact "unknown_artifact"`) { if !strings.Contains(stderr.String(), `--artifacts includes unknown artifact "unknown_artifact"`) {
t.Fatalf("stderr = %q, want unknown-artifact validation error", stderr.String()) t.Fatalf("stderr = %q, want unknown-artifact validation error", stderr.String())
} }
} }
func TestExecuteAnalyzeRejectsPositionalArgsAndForceFlag(t *testing.T) { func TestExecuteAnalyzeMissingConfigUsesSharedAcquisition(t *testing.T) {
cases := []struct { deps, _, executor := guardedMissingPipelineDiscovery(t)
name string
args []string
want string
}{
{name: "extra positional", args: []string{"analyze", "2026-05-03", "extra"}, want: "analyze: unexpected positional arguments"},
{name: "force flag", args: []string{"analyze", "--force"}, want: "analyze: invalid flags: flag provided but not defined: -force"},
}
for _, tc := range cases {
t.Run(tc.name, func(t *testing.T) {
var stdout bytes.Buffer
var stderr bytes.Buffer
code := Execute(tc.args, &stdout, &stderr)
if code == 0 {
t.Fatal("exit code = 0, want non-zero")
}
if !strings.Contains(stderr.String(), tc.want) {
t.Fatalf("stderr = %q, want %q", stderr.String(), tc.want)
}
})
}
}
func TestExecuteAnalyzeMissingConfigUsesRunStageLoadingPath(t *testing.T) {
deps, missingPath, executor := guardedMissingPipelineDiscovery(t)
var stdout bytes.Buffer var stdout bytes.Buffer
var stderr bytes.Buffer var stderr bytes.Buffer
code := executeWithDependencies([]string{"analyze", "2026-05-03"}, &stdout, &stderr, deps, executor) code := executeWithDependencies([]string{"run", "2026-05-03", "--stage", "analyze", "--force"}, &stdout, &stderr, deps, executor)
if code == 0 { if code == 0 {
t.Fatal("exit code = 0, want non-zero") t.Fatal("exit code = 0, want non-zero")
} }
if stdout.Len() != 0 { if stdout.Len() != 0 {
t.Fatalf("stdout = %q, want empty", stdout.String()) t.Fatalf("stdout = %q, want empty", stdout.String())
} }
if got := stderr.String(); !strings.Contains(got, "analyze: no pipeline config path provided") || if got := stderr.String(); !strings.Contains(got, "source.missing") {
!strings.Contains(got, "no default pipeline config found") || !strings.Contains(got, missingPath) {
t.Fatalf("stderr = %q, want pipeline discovery error", stderr.String()) t.Fatalf("stderr = %q, want pipeline discovery error", stderr.String())
} }
} }
@@ -310,7 +282,7 @@ func TestExecutePublishForceRunsPublish(t *testing.T) {
var stdout bytes.Buffer var stdout bytes.Buffer
var stderr bytes.Buffer var stderr bytes.Buffer
code := executeWithPipelineExecutor( code := executeWithPipelineExecutor(
[]string{"publish", "2026-05-03", "--config", pipelinePath, "--campaign-file", campaignPath, "--session", sessionPath, "--artifacts", "session_recap"}, []string{"run", "--stage", "publish", "--force", "2026-05-03", "--config", pipelinePath, "--campaign-file", campaignPath, "--session-file", sessionPath, "--artifacts", "session_recap"},
&stdout, &stdout,
&stderr, &stderr,
executor, executor,
@@ -327,86 +299,46 @@ func TestExecutePublishForceRunsPublish(t *testing.T) {
if strings.Join(capturedArtifacts, ",") != "session_recap" { if strings.Join(capturedArtifacts, ",") != "session_recap" {
t.Fatalf("captured artifacts = %#v, want [session_recap]", capturedArtifacts) t.Fatalf("captured artifacts = %#v, want [session_recap]", capturedArtifacts)
} }
if !strings.Contains(stdout.String(), "narratio publish: executed=1 skipped=0 force=true; manifest=") { if !runCountsMatch(t, stdout.Bytes(), 1, 0, "") {
t.Fatalf("stdout = %q, want publish summary", stdout.String()) t.Fatalf("stdout = %q, want publish summary", stdout.String())
} }
} }
func TestExecutePublishRejectsUnsupportedArgsAndFlags(t *testing.T) {
cases := []struct {
name string
args []string
want string
}{
{name: "extra positional", args: []string{"publish", "2026-05-03", "extra"}, want: "publish: unexpected positional arguments"},
{name: "force flag", args: []string{"publish", "--force"}, want: "publish: invalid flags: flag provided but not defined: -force"},
}
for _, tc := range cases {
t.Run(tc.name, func(t *testing.T) {
var stdout bytes.Buffer
var stderr bytes.Buffer
code := Execute(tc.args, &stdout, &stderr)
if code == 0 {
t.Fatal("exit code = 0, want non-zero")
}
if !strings.Contains(stderr.String(), tc.want) {
t.Fatalf("stderr = %q, want %q", stderr.String(), tc.want)
}
})
}
}
func TestExecutePublishUnknownArtifactFailsValidation(t *testing.T) { func TestExecutePublishUnknownArtifactFailsValidation(t *testing.T) {
workspaceRoot := t.TempDir() workspaceRoot := t.TempDir()
pipelinePath, campaignPath, sessionPath := writeValidConfigFilesWithScriptoriumArtifacts(t, workspaceRoot) pipelinePath, campaignPath, sessionPath := writeValidConfigFilesWithScriptoriumArtifacts(t, workspaceRoot)
var stdout bytes.Buffer var stdout bytes.Buffer
var stderr bytes.Buffer var stderr bytes.Buffer
code := Execute( code := executeForTest(
[]string{"publish", "2026-05-03", "--config", pipelinePath, "--campaign-file", campaignPath, "--session", sessionPath, "--artifacts", "unknown_artifact"}, []string{"run", "--stage", "publish", "--force", "2026-05-03", "--config", pipelinePath, "--campaign-file", campaignPath, "--session-file", sessionPath, "--artifacts", "unknown_artifact"},
&stdout, &stdout,
&stderr, &stderr,
) )
if code == 0 { if code == 0 {
t.Fatal("exit code = 0, want non-zero") t.Fatal("exit code = 0, want non-zero")
} }
if !strings.Contains(stderr.String(), `publish: --artifacts includes unknown artifact "unknown_artifact"`) { if !strings.Contains(stderr.String(), `--artifacts includes unknown artifact "unknown_artifact"`) {
t.Fatalf("stderr = %q, want unknown-artifact validation error", stderr.String()) t.Fatalf("stderr = %q, want unknown-artifact validation error", stderr.String())
} }
} }
func TestExecutePublishMissingConfigUsesRunStageLoadingPath(t *testing.T) { func TestExecutePublishMissingConfigUsesSharedAcquisition(t *testing.T) {
deps, missingPath, executor := guardedMissingPipelineDiscovery(t) deps, _, executor := guardedMissingPipelineDiscovery(t)
var stdout bytes.Buffer var stdout bytes.Buffer
var stderr bytes.Buffer var stderr bytes.Buffer
code := executeWithDependencies([]string{"publish", "2026-05-03"}, &stdout, &stderr, deps, executor) code := executeWithDependencies([]string{"run", "2026-05-03", "--stage", "publish", "--force"}, &stdout, &stderr, deps, executor)
if code == 0 { if code == 0 {
t.Fatal("exit code = 0, want non-zero") t.Fatal("exit code = 0, want non-zero")
} }
if stdout.Len() != 0 { if stdout.Len() != 0 {
t.Fatalf("stdout = %q, want empty", stdout.String()) t.Fatalf("stdout = %q, want empty", stdout.String())
} }
if got := stderr.String(); !strings.Contains(got, "publish: no pipeline config path provided") || if got := stderr.String(); !strings.Contains(got, "source.missing") {
!strings.Contains(got, "no default pipeline config found") || !strings.Contains(got, missingPath) {
t.Fatalf("stderr = %q, want pipeline discovery error", stderr.String()) t.Fatalf("stderr = %q, want pipeline discovery error", stderr.String())
} }
} }
func TestExecuteUsageIncludesAnalyzeAndPublish(t *testing.T) {
var stdout bytes.Buffer
var stderr bytes.Buffer
code := Execute(nil, &stdout, &stderr)
if code == 0 {
t.Fatal("exit code = 0, want non-zero")
}
if !strings.Contains(stderr.String(), "analyze") {
t.Fatalf("stderr = %q, want usage to include analyze", stderr.String())
}
if !strings.Contains(stderr.String(), "publish") {
t.Fatalf("stderr = %q, want usage to include publish", stderr.String())
}
}
func writeValidConfigFilesWithScriptoriumArtifacts(t *testing.T, workspaceRoot string) (string, string, string) { func writeValidConfigFilesWithScriptoriumArtifacts(t *testing.T, workspaceRoot string) (string, string, string) {
t.Helper() t.Helper()

View File

@@ -66,7 +66,7 @@ characters:
} }
} }
func TestArtifactSelectionFlagNormalize(t *testing.T) { func TestNormalizeArtifactNames(t *testing.T) {
tests := []struct { tests := []struct {
name string name string
inputs []string inputs []string
@@ -92,14 +92,7 @@ func TestArtifactSelectionFlagNormalize(t *testing.T) {
for _, tt := range tests { for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) { t.Run(tt.name, func(t *testing.T) {
var flag artifactSelectionFlag got, err := normalizeArtifactNames(tt.inputs)
for _, in := range tt.inputs {
if err := flag.Set(in); err != nil {
t.Fatalf("Set(%q) error = %v", in, err)
}
}
got, err := flag.Normalize()
if tt.wantErr != "" { if tt.wantErr != "" {
if err == nil { if err == nil {
t.Fatalf("Normalize() error = nil, want %q", tt.wantErr) t.Fatalf("Normalize() error = nil, want %q", tt.wantErr)
@@ -124,7 +117,7 @@ func TestArtifactSelectionFlagNormalize(t *testing.T) {
} }
} }
func TestValidateSelectedArtifacts(t *testing.T) { func TestResolveSelectedArtifacts(t *testing.T) {
tests := []struct { tests := []struct {
name string name string
cfg *config.Config cfg *config.Config
@@ -188,7 +181,10 @@ func TestValidateSelectedArtifacts(t *testing.T) {
for _, tt := range tests { for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) { t.Run(tt.name, func(t *testing.T) {
err := validateSelectedArtifacts(tt.cfg, tt.selected) if tt.cfg.Pipeline != nil && tt.cfg.Pipeline.Scriptorium != nil {
tt.cfg.ArtifactCatalog = &config.ArtifactCatalog{Artifacts: tt.cfg.Pipeline.Scriptorium.Artifacts}
}
_, err := resolveEffectiveArtifacts(tt.cfg, tt.selected)
if tt.wantErr != "" { if tt.wantErr != "" {
if err == nil { if err == nil {
t.Fatalf("error = nil, want %q", tt.wantErr) t.Fatalf("error = nil, want %q", tt.wantErr)

View File

@@ -20,6 +20,7 @@ import (
func TestExecuteStagesRetriesFromLastAnalyzeCheckpoint(t *testing.T) { func TestExecuteStagesRetriesFromLastAnalyzeCheckpoint(t *testing.T) {
cfg := testConfig(t) cfg := testConfig(t)
cfg.Pipeline.Scriptorium = &config.ScriptoriumConfig{Artifacts: checkpointRecoveryArtifacts("original")} cfg.Pipeline.Scriptorium = &config.ScriptoriumConfig{Artifacts: checkpointRecoveryArtifacts("original")}
cfg.ArtifactCatalog = &config.ArtifactCatalog{Artifacts: cfg.Pipeline.Scriptorium.Artifacts}
store := &manifest.LocalStore{} store := &manifest.LocalStore{}
seed := manifest.New(cfg.Session.SessionID, time.Now().UTC()) seed := manifest.New(cfg.Session.SessionID, time.Now().UTC())
seed.Campaign = cfg.Session.Campaign seed.Campaign = cfg.Session.Campaign
@@ -47,7 +48,7 @@ func TestExecuteStagesRetriesFromLastAnalyzeCheckpoint(t *testing.T) {
upstream := cloneStageRecords(baseline, "prepare", "transcribe", "merge", "polish", "normalize", "trim") upstream := cloneStageRecords(baseline, "prepare", "transcribe", "merge", "polish", "normalize", "trim")
unrelated := baseline.Stages["analyze"].AnalyzeArtifacts["unrelated"] unrelated := baseline.Stages["analyze"].AnalyzeArtifacts["unrelated"]
cfg.Pipeline.Scriptorium.Artifacts = checkpointRecoveryArtifacts("revised") cfg.ArtifactCatalog.Artifacts = checkpointRecoveryArtifacts("revised")
failure := errors.New("injected quest-log failure") failure := errors.New("injected quest-log failure")
failingRunner := &analyzeCheckpointRunner{FailPrompt: "quest-log-revised", Err: failure} failingRunner := &analyzeCheckpointRunner{FailPrompt: "quest-log-revised", Err: failure}
if _, err := executeStages(context.Background(), cfg, []stage.Stage{analyze}, RunOptions{ if _, err := executeStages(context.Background(), cfg, []stage.Stage{analyze}, RunOptions{
@@ -106,6 +107,7 @@ func TestExecuteStagesJoinsAnalyzeFailureWithTerminalSaveFailure(t *testing.T) {
"chronicle": {Enabled: true, PromptID: "chronicle", OutputPath: "artifacts/chronicle.md"}, "chronicle": {Enabled: true, PromptID: "chronicle", OutputPath: "artifacts/chronicle.md"},
}, },
} }
cfg.ArtifactCatalog = &config.ArtifactCatalog{Artifacts: cfg.Pipeline.Scriptorium.Artifacts}
artifactErr := errors.New("injected analyze failure") artifactErr := errors.New("injected analyze failure")
terminalErr := errors.New("injected terminal save failure") terminalErr := errors.New("injected terminal save failure")
store := &failedAnalyzeSaveStore{Store: &manifest.LocalStore{}, Err: terminalErr} store := &failedAnalyzeSaveStore{Store: &manifest.LocalStore{}, Err: terminalErr}
@@ -131,6 +133,7 @@ func TestExecuteStagesPersistsAnalyzeCheckpointFailureRecovery(t *testing.T) {
"quest_log": {Enabled: true, PromptID: "quest-log", OutputPath: "artifacts/quest_log.md"}, "quest_log": {Enabled: true, PromptID: "quest-log", OutputPath: "artifacts/quest_log.md"},
}, },
} }
cfg.ArtifactCatalog = &config.ArtifactCatalog{Artifacts: cfg.Pipeline.Scriptorium.Artifacts}
baseStore := &manifest.LocalStore{} baseStore := &manifest.LocalStore{}
seed := manifest.New(cfg.Session.SessionID, time.Now().UTC()) seed := manifest.New(cfg.Session.SessionID, time.Now().UTC())
seed.Campaign = cfg.Session.Campaign seed.Campaign = cfg.Session.Campaign

View File

@@ -0,0 +1,84 @@
package app
import (
"context"
"errors"
"sort"
"gitea.maximumdirect.net/eric/narratio/internal/artifacts"
"gitea.maximumdirect.net/eric/narratio/internal/config"
"go.maximumdirect.net/commandkit"
)
type artifactCatalogReport struct {
Artifacts []artifactDefinitionReport `json:"artifacts"`
}
type artifactDefinitionReport struct {
Key string `json:"key,omitempty"`
Source string `json:"source"`
Producer string `json:"producer"`
Output string `json:"output,omitempty"`
Enabled *bool `json:"enabled,omitempty"`
Dependencies []string `json:"dependencies"`
Family string `json:"family,omitempty"`
CharacterID string `json:"character_id,omitempty"`
DefinitionSources []string `json:"definition_sources,omitempty"`
FamilySources []string `json:"family_sources,omitempty"`
PartySource string `json:"party_source,omitempty"`
}
func artifactCatalogCommand(deps commandDependencies) commandkit.Command {
common := newConfigurationFlags(func(input *configurationSelection) *configurationSelection { return input })
return commandkit.NewCommand(commandkit.CommandSpec[configurationSelection]{
Name: "list", Summary: "List artifact definitions for the selected pipeline and party.",
Flags: []commandkit.Flag[configurationSelection]{common.Config, common.Overlay, common.Campaign, common.CampaignFile, common.PartyFile, common.SecretsDir},
CheckInput: checkConfigurationSelection,
Run: func(invocation commandkit.Invocation, input configurationSelection) commandkit.Outcome {
report, err := loadArtifactCatalogReport(invocation.Context, input, withCommandReporting(deps, invocation))
if report != nil {
err = errors.Join(err, invocation.Reporter().Report(commandkit.Report{Value: report}))
}
return reportOperationOutcome(invocation, err)
},
})
}
func loadArtifactCatalogReport(ctx context.Context, input configurationSelection, deps commandDependencies) (report *artifactCatalogReport, err error) {
deps = normalizeCommandDependencies(deps)
deps.secretsBootstrap = &secretsBootstrap{}
acquired := newConfigurationAcquisition(input, deps)
defer func() { err = errors.Join(err, acquired.Close()) }()
catalog, err := acquired.Catalog(ctx)
if err != nil {
return nil, err
}
return describeArtifactDefinitions(acquired.pipeline, catalog)
}
func describeArtifactDefinitions(pipeline *config.PipelineConfig, catalog *config.ArtifactCatalog) (*artifactCatalogReport, error) {
configured := artifacts.ConfiguredArtifactDefinitions(catalog.Artifacts)
effective, err := artifacts.ResolveEffectiveArtifactSet(configured, nil)
if err != nil {
return nil, err
}
runtime, err := artifacts.BootstrapRuntimeCatalog(configured, effective, artifacts.ExtractionDefinitionsFromConfig(pipeline.Notarius))
if err != nil {
return nil, err
}
report := &artifactCatalogReport{Artifacts: []artifactDefinitionReport{}}
for _, spec := range artifacts.RuntimeTranscriptArtifacts() {
report.Artifacts = append(report.Artifacts, artifactDefinitionReport{Source: spec.SourceID, Producer: spec.ProducerStage, Output: spec.CanonicalRelPath, Dependencies: []string{}})
}
if bounds, ok := runtime.Lookup(artifacts.ArtifactBoundsSession); ok {
report.Artifacts = append(report.Artifacts, artifactDefinitionReport{Source: bounds.SourceID, Producer: bounds.ProducerStage, Output: bounds.CanonicalRelPath, Dependencies: []string{}})
}
for _, record := range catalog.Records {
report.Artifacts = append(report.Artifacts, artifactDefinitionReport{Key: record.Key, Source: record.SourceID, Producer: "analyze", Output: record.OutputPath, Enabled: &record.Enabled, Dependencies: append([]string{}, record.Dependencies...), Family: record.FamilyKey, CharacterID: record.CharacterID, DefinitionSources: record.DefinitionSources, FamilySources: record.FamilySources, PartySource: record.PartySource})
}
for _, entry := range runtime.ListExtraction() {
enabled := pipeline.Notarius != nil && pipeline.Notarius.Enabled
report.Artifacts = append(report.Artifacts, artifactDefinitionReport{Key: entry.ExtractionKey, Source: entry.SourceID, Producer: entry.ProducerStage, Enabled: &enabled, Dependencies: []string{}})
}
sort.Slice(report.Artifacts, func(i, j int) bool { return report.Artifacts[i].Source < report.Artifacts[j].Source })
return report, nil
}

View File

@@ -0,0 +1,119 @@
package app
import (
"strings"
"gitea.maximumdirect.net/eric/narratio/internal/artifacts"
"gitea.maximumdirect.net/eric/narratio/internal/config"
"gitea.maximumdirect.net/eric/narratio/internal/manifest"
)
func buildHelperArtifactCatalog(cfg *config.Config, m *manifest.Manifest) (*artifacts.ArtifactCatalog, error) {
configured := artifacts.ConfiguredArtifactDefinitions(nil)
if cfg.Pipeline.Scriptorium != nil {
configured = artifacts.ConfiguredArtifactDefinitions(cfg.ConcreteArtifacts())
}
extractionDefinitions := artifacts.ExtractionDefinitionsFromConfig(cfg.Pipeline.Notarius)
effective, err := artifacts.ResolveEffectiveArtifactSet(configured, nil)
if err != nil {
return nil, err
}
catalog, err := artifacts.BootstrapRuntimeCatalog(configured, effective, extractionDefinitions)
if err != nil {
return nil, err
}
paths := artifacts.NewLocalStore(cfg.Pipeline.Workspace.Root).SessionPathsFor(cfg.Session.Campaign, cfg.Session.SessionID)
if cfg.Pipeline.Notarius != nil && cfg.Pipeline.Notarius.Enabled {
catalog.HydrateExtractionArtifacts(paths, m, extractionDefinitions)
}
catalog.HydrateAnalyzeArtifacts(paths, m, configured)
return catalog, nil
}
func remoteLockSourceSet(locks []artifacts.RemoteLock) map[string]struct{} {
out := make(map[string]struct{}, len(locks))
for _, lock := range locks {
out[lock.Source] = struct{}{}
}
return out
}
func committedPublishOutputOutcomes(m *manifest.Manifest) map[string]string {
out := map[string]string{}
if m == nil || m.Stages["publish"] == nil {
return out
}
raw := m.Stages["publish"].Metadata["publish_output_outcomes"]
appendOutcome := func(item map[string]any) {
source, sourceOK := item["source"].(string)
status, statusOK := item["status"].(string)
if sourceOK && statusOK && isPublishOutputOutcome(status) {
out[source] = status
}
}
switch items := raw.(type) {
case []any:
for _, rawItem := range items {
if item, ok := rawItem.(map[string]any); ok {
appendOutcome(item)
}
}
case []map[string]any:
for _, item := range items {
appendOutcome(item)
}
}
return out
}
func isPublishOutputOutcome(status string) bool {
switch status {
case "published", "carried_locked", "locked_unpublished", "optional_missing", "unselected":
return true
default:
return false
}
}
func committedPublishedOutputs(commit *artifacts.RemoteCommitManifest) map[string]artifacts.RemoteArtifact {
out := map[string]artifacts.RemoteArtifact{}
if commit == nil {
return out
}
for _, artifact := range commit.Artifacts {
if artifact.Type != artifacts.RemoteArtifactTypePublishedOutput {
continue
}
if _, exists := out[artifact.Source]; !exists {
out[artifact.Source] = artifact
}
}
return out
}
func helperExtractionOutputSet(catalog *artifacts.ArtifactCatalog) map[string]struct{} {
out := map[string]struct{}{}
if catalog == nil {
return out
}
for _, entry := range catalog.ListExtraction() {
if strings.TrimSpace(entry.ExtractionKey) != "" {
out[entry.ExtractionKey] = struct{}{}
}
}
return out
}
func helperConfiguredOutputPathMap(catalog *artifacts.ArtifactCatalog) map[string]string {
out := map[string]string{}
if catalog == nil {
return out
}
for _, entry := range catalog.ListConfigured() {
if strings.TrimSpace(entry.ConfiguredKey) == "" {
continue
}
out[entry.ConfiguredKey] = strings.TrimSpace(entry.CanonicalRelPath)
}
return out
}

View File

@@ -22,6 +22,7 @@ func TestBuildHelperArtifactCatalogUsesAnalyzeManifestEvidence(t *testing.T) {
}, },
Session: &config.SessionConfig{Campaign: "campaign", SessionID: "session"}, Session: &config.SessionConfig{Campaign: "campaign", SessionID: "session"},
} }
cfg.ArtifactCatalog = &config.ArtifactCatalog{Artifacts: cfg.Pipeline.Scriptorium.Artifacts}
paths := artifacts.NewLocalStore(root).SessionPathsFor("campaign", "session") paths := artifacts.NewLocalStore(root).SessionPathsFor("campaign", "session")
outputPath := filepath.Join(paths.ArtifactsDir, "session_recap.md") outputPath := filepath.Join(paths.ArtifactsDir, "session_recap.md")
if err := os.MkdirAll(filepath.Dir(outputPath), 0o755); err != nil { if err := os.MkdirAll(filepath.Dir(outputPath), 0o755); err != nil {

View File

@@ -3,7 +3,6 @@ package app
import ( import (
"bytes" "bytes"
"context" "context"
"io"
"os" "os"
"path/filepath" "path/filepath"
"reflect" "reflect"
@@ -39,7 +38,7 @@ func TestAssembledFullRunUsesCanonicalOrder(t *testing.T) {
} }
} }
func TestAssembledCanonicalAndAliasArtifactRegenerationRequestsMatch(t *testing.T) { func TestAssembledForcedRangeAndRegenerationRequestsMatch(t *testing.T) {
workspaceRoot := t.TempDir() workspaceRoot := t.TempDir()
pipelinePath, campaignPath, sessionPath := writeValidConfigFilesWithScriptoriumArtifacts(t, workspaceRoot) pipelinePath, campaignPath, sessionPath := writeValidConfigFilesWithScriptoriumArtifacts(t, workspaceRoot)
type capturedRequest struct { type capturedRequest struct {
@@ -56,23 +55,22 @@ func TestAssembledCanonicalAndAliasArtifactRegenerationRequestsMatch(t *testing.
} }
base := []string{ base := []string{
"2026-05-03", "--force", "--from", "extract", "--through", "analyze", "2026-05-03", "--force", "--from", "extract", "--through", "analyze",
"--config", pipelinePath, "--campaign-file", campaignPath, "--session", sessionPath, "--config", pipelinePath, "--campaign-file", campaignPath, "--session-file", sessionPath,
} }
deps := fakeCommandDependencies(&storage.FakeBackend{}, nil) deps := fakeCommandDependencies(&storage.FakeBackend{}, nil)
if err := runWithDependencies(context.Background(), base, &bytes.Buffer{}, executor, deps); err != nil { if err := invokeNativeCommandWith(context.Background(), append([]string{"run"}, base...), &bytes.Buffer{}, executor, deps); err != nil {
t.Fatalf("canonical unselected Run() error = %v", err) t.Fatalf("canonical unselected Run() error = %v", err)
} }
selected := append(append([]string(nil), base...), "--artifacts", "session_recap") selected := append(append([]string(nil), base...), "--artifacts", "session_recap")
if err := runWithDependencies(context.Background(), selected, &bytes.Buffer{}, executor, deps); err != nil { if err := invokeNativeCommandWith(context.Background(), append([]string{"run"}, selected...), &bytes.Buffer{}, executor, deps); err != nil {
t.Fatalf("canonical selected Run() error = %v", err) t.Fatalf("canonical selected Run() error = %v", err)
} }
var stdout, stderr bytes.Buffer var stdout, stderr bytes.Buffer
alias := []string{ regeneration := []string{"artifacts", "regenerate", "2026-05-03", "--artifacts", "session_recap",
"regenerate-artifacts", "2026-05-03", "--artifacts", "session_recap", "--config", pipelinePath, "--campaign-file", campaignPath, "--session-file", sessionPath,
"--config", pipelinePath, "--campaign-file", campaignPath, "--session", sessionPath,
} }
if code := executeWithDependencies(alias, &stdout, &stderr, deps, executor); code != 0 { if code := executeWithDependencies(regeneration, &stdout, &stderr, deps, executor); code != 0 {
t.Fatalf("alias exit=%d stderr=%q", code, stderr.String()) t.Fatalf("regeneration exit=%d stderr=%q", code, stderr.String())
} }
if len(captured) != 3 { if len(captured) != 3 {
t.Fatalf("captured requests = %#v", captured) t.Fatalf("captured requests = %#v", captured)
@@ -83,7 +81,7 @@ func TestAssembledCanonicalAndAliasArtifactRegenerationRequestsMatch(t *testing.
} }
if !reflect.DeepEqual(captured[1], captured[2]) || !reflect.DeepEqual(captured[1].stages, wantStages) || if !reflect.DeepEqual(captured[1], captured[2]) || !reflect.DeepEqual(captured[1].stages, wantStages) ||
!reflect.DeepEqual(captured[1].artifacts, []string{"session_recap"}) || !captured[1].force { !reflect.DeepEqual(captured[1].artifacts, []string{"session_recap"}) || !captured[1].force {
t.Fatalf("canonical=%#v alias=%#v, want identical bounded request", captured[1], captured[2]) t.Fatalf("forced range=%#v regeneration=%#v, want identical bounded request", captured[1], captured[2])
} }
} }
@@ -142,6 +140,7 @@ func TestAssembledLegacyAnalyzeTransitionPublishesOnlyCurrentRecords(t *testing.
"player_handout": {Enabled: true, PromptID: "dnd.player_handout", OutputPath: "artifacts/player_handout.md"}, "player_handout": {Enabled: true, PromptID: "dnd.player_handout", OutputPath: "artifacts/player_handout.md"},
"session_recap": {Enabled: true, PromptID: "dnd.session_recap", OutputPath: "artifacts/session_recap.md"}, "session_recap": {Enabled: true, PromptID: "dnd.session_recap", OutputPath: "artifacts/session_recap.md"},
}} }}
cfg.ArtifactCatalog = &config.ArtifactCatalog{Artifacts: cfg.Pipeline.Scriptorium.Artifacts}
cfg.Pipeline.Storage.Backend = config.StorageBackendS3 cfg.Pipeline.Storage.Backend = config.StorageBackendS3
cfg.Pipeline.Storage.S3 = &config.StorageS3Config{Bucket: "archive", RootPrefix: "dnd"} cfg.Pipeline.Storage.S3 = &config.StorageS3Config{Bucket: "archive", RootPrefix: "dnd"}
cfg.Pipeline.Publish = &config.PublishConfig{ cfg.Pipeline.Publish = &config.PublishConfig{
@@ -151,6 +150,7 @@ func TestAssembledLegacyAnalyzeTransitionPublishesOnlyCurrentRecords(t *testing.
{Source: artifacts.ConfiguredArtifactSourceID("session_recap"), Dest: "artifacts/session_recap.md", Required: boolPtr(true)}, {Source: artifacts.ConfiguredArtifactSourceID("session_recap"), Dest: "artifacts/session_recap.md", Required: boolPtr(true)},
}, },
} }
cfg.ArtifactCatalog.PublishOutputs = cfg.Pipeline.Publish.Outputs
paths, err := artifacts.NewLocalStore(cfg.Pipeline.Workspace.Root).EnsureLayoutFor(cfg.Session.Campaign, cfg.Session.SessionID) paths, err := artifacts.NewLocalStore(cfg.Pipeline.Workspace.Root).EnsureLayoutFor(cfg.Session.Campaign, cfg.Session.SessionID)
if err != nil { if err != nil {
t.Fatal(err) t.Fatal(err)
@@ -202,7 +202,7 @@ func TestAssembledLegacyAnalyzeTransitionPublishesOnlyCurrentRecords(t *testing.
t.Fatalf("legacy transition invalidated %s: %#v", transcriptStage, afterPartial.Stages[transcriptStage]) t.Fatalf("legacy transition invalidated %s: %#v", transcriptStage, afterPartial.Stages[transcriptStage])
} }
} }
configured := artifacts.ConfiguredArtifactDefinitions(cfg.Pipeline.Scriptorium.Artifacts) configured := artifacts.ConfiguredArtifactDefinitions(cfg.ArtifactCatalog.Artifacts)
effective, err := artifacts.ResolveEffectiveArtifactSet(configured, nil) effective, err := artifacts.ResolveEffectiveArtifactSet(configured, nil)
if err != nil { if err != nil {
t.Fatal(err) t.Fatal(err)
@@ -252,40 +252,23 @@ func TestAssembledSplitBundleCommandsUseOneEffectiveFamilyConfiguration(t *testi
t.Fatalf("example workspace stat = %v, want absent", err) t.Fatalf("example workspace stat = %v, want absent", err)
} }
var validated bytes.Buffer for _, operation := range []string{"validate", "show", "sources"} {
if err := ConfigValidate(context.Background(), []string{"--config", pipelinePath, "--campaign-file", campaignPath}, &validated); err != nil { nativeInspectionForTest(t, []string{"config", operation, "--config", pipelinePath, "--overlay", "testing"})
t.Fatalf("validate production base: %v", err)
} }
if !strings.Contains(validated.String(), "overlay=none") { diff := nativeInspectionForTest(t, []string{"config", "diff", "--details", "--config", pipelinePath, "--against-config", pipelinePath, "--against-overlay", "testing", "--format", "json"})
t.Fatalf("validate output = %q, want production base", validated.String()) if !strings.Contains(diff, "/audita/proposal_profile") || !strings.Contains(diff, "/scriptorium/artifact_families/character_items/profile_id") {
} t.Fatalf("profile diff = %q, want authored profile changes", diff)
for _, command := range []func(context.Context, []string, io.Writer) error{ConfigShow, ConfigSources} {
if err := command(context.Background(), []string{
"--config", pipelinePath, "--campaign-file", campaignPath, "--overlay", "testing",
}, io.Discard); err != nil {
t.Fatalf("testing inspection command %T: %v", command, err)
}
}
var diff bytes.Buffer
if err := ConfigDiff(context.Background(), []string{
"default", "testing", "--config", pipelinePath, "--campaign-file", campaignPath,
}, &diff); err != nil {
t.Fatalf("compare profiles: %v", err)
}
if !strings.Contains(diff.String(), "audita.proposal_profile") || !strings.Contains(diff.String(), "character_items_arannis.profile_id") {
t.Fatalf("profile diff = %q, want proposal profile and expanded family changes", diff.String())
} }
common := []string{ common := []string{
"2026-05-03", "--config", pipelinePath, "--campaign-file", campaignPath, "2026-05-03", "--config", pipelinePath, "--campaign-file", campaignPath, "--session-file", sessionPath, "--overlay", "testing",
"--session", sessionPath, "--overlay", "testing",
} }
var planned bytes.Buffer var planned bytes.Buffer
if err := Plan(context.Background(), common, &planned); err != nil { if err := invokeNativeCommand(context.Background(), append([]string{"session", "plan"}, common...), &planned); err != nil {
t.Fatalf("plan testing bundle: %v", err) t.Fatalf("plan testing bundle: %v", err)
} }
if !strings.Contains(planned.String(), "overlay=testing") { if report := decodeNativeReport[sessionPlanReport](t, planned.Bytes()); report.Campaign != "sample-campaign" || len(report.Stages) != len(canonicalStageNames()) {
t.Fatalf("plan output = %q, want testing provenance", planned.String()) t.Fatalf("plan=%#v", report)
} }
var capturedCfg *config.Config var capturedCfg *config.Config
@@ -299,7 +282,7 @@ func TestAssembledSplitBundleCommandsUseOneEffectiveFamilyConfiguration(t *testi
} }
runArgs := append(append([]string(nil), common...), "--from", "analyze", "--through", "analyze", "--artifacts", "character_items_arannis") runArgs := append(append([]string(nil), common...), "--from", "analyze", "--through", "analyze", "--artifacts", "character_items_arannis")
var runOut bytes.Buffer var runOut bytes.Buffer
if err := runWithPipelineExecutor(context.Background(), runArgs, &runOut, executor); err != nil { if err := invokeNativeCommandWith(context.Background(), append([]string{"run"}, runArgs...), &runOut, executor, commandDependencies{}); err != nil {
t.Fatalf("bounded family run: %v", err) t.Fatalf("bounded family run: %v", err)
} }
if !reflect.DeepEqual(capturedPlan.Names(), []string{"analyze"}) { if !reflect.DeepEqual(capturedPlan.Names(), []string{"analyze"}) {
@@ -308,7 +291,7 @@ func TestAssembledSplitBundleCommandsUseOneEffectiveFamilyConfiguration(t *testi
if profile, ok := config.SelectedPipelineOverlay(capturedCfg.Pipeline); !ok || profile.Name != "testing" { if profile, ok := config.SelectedPipelineOverlay(capturedCfg.Pipeline); !ok || profile.Name != "testing" {
t.Fatalf("captured profile = %#v, selected=%t", profile, ok) t.Fatalf("captured profile = %#v, selected=%t", profile, ok)
} }
if digest := config.EffectivePipelineDigest(capturedCfg.Pipeline); digest == "" || !strings.Contains(runOut.String(), "digest="+digest) { if digest := config.EffectivePipelineDigest(capturedCfg.Pipeline); digest == "" {
t.Fatalf("run output = %q, want effective digest %q", runOut.String(), digest) t.Fatalf("run output = %q, want effective digest %q", runOut.String(), digest)
} }
if got := capturedOptions.EffectiveArtifacts.Keys(); !reflect.DeepEqual(got, []string{"character_items_arannis"}) { if got := capturedOptions.EffectiveArtifacts.Keys(); !reflect.DeepEqual(got, []string{"character_items_arannis"}) {

View File

@@ -1,118 +0,0 @@
package app
import (
"flag"
"fmt"
"io"
"strconv"
)
type boundedRunRequest struct {
Config commonConfigFlags
Plan BoundedPlan
Force bool
SelectedArtifacts []string
}
type singletonStringFlag struct {
name string
value string
set bool
}
func (f *singletonStringFlag) String() string { return f.value }
func (f *singletonStringFlag) Set(value string) error {
if f.set {
return fmt.Errorf("--%s may be specified only once", f.name)
}
f.value = value
f.set = true
return nil
}
func (f singletonStringFlag) pointer() *string {
if !f.set {
return nil
}
value := f.value
return &value
}
type singletonBoolFlag struct {
name string
value bool
set bool
}
func (f *singletonBoolFlag) String() string { return strconv.FormatBool(f.value) }
func (f *singletonBoolFlag) IsBoolFlag() bool { return true }
func (f *singletonBoolFlag) Set(raw string) error {
if f.set {
return fmt.Errorf("--%s may be specified only once", f.name)
}
value, err := strconv.ParseBool(raw)
if err != nil {
return fmt.Errorf("--%s requires a boolean value: %w", f.name, err)
}
f.value = value
f.set = true
return nil
}
func parseBoundedRunRequest(command string, args []string, help io.Writer) (boundedRunRequest, error) {
fs := flag.NewFlagSet(command, flag.ContinueOnError)
fs.SetOutput(help)
var configFlags commonConfigFlags
var from singletonStringFlag
var through singletonStringFlag
var force singletonBoolFlag
var selectedArtifacts artifactSelectionFlag
from.name = "from"
through.name = "through"
force.name = "force"
addCommonConfigFlags(fs, &configFlags)
fs.Var(&from, "from", "first canonical stage to select (inclusive)")
fs.Var(&through, "through", "last canonical stage to select (inclusive)")
fs.Var(&force, "force", "rerun selected stages even when already succeeded")
fs.Var(&selectedArtifacts, "artifacts", "configured artifact names to execute and publish (comma-separated or repeatable)")
fs.Usage = func() {
invocation := "narratio run"
if command == "plan" {
invocation = "narratio session plan"
}
_, _ = fmt.Fprintf(help, "Usage: %s <session_id> [--from <stage>] [--through <stage>] [--force] [--artifacts <name[,name...]>] [common config flags]\n\n", invocation)
_, _ = fmt.Fprintln(help, "Bounds are inclusive; omitted --from or --through selects the beginning or end of the canonical pipeline.")
_, _ = fmt.Fprintln(help)
_, _ = fmt.Fprintln(help, "Flags:")
fs.PrintDefaults()
}
if err := parseSessionAwareFlags(command, fs, args, &configFlags.sessionID); err != nil {
return boundedRunRequest{}, err
}
if configFlags.sessionID == "" {
return boundedRunRequest{}, fmt.Errorf("%s: session_id is required", command)
}
plan, err := BuildBoundedPlan(from.value, through.value)
if err != nil {
return boundedRunRequest{}, fmt.Errorf("%s: %w", command, err)
}
normalizedArtifacts, err := selectedArtifacts.Normalize()
if err != nil {
return boundedRunRequest{}, fmt.Errorf("%s: invalid --artifacts: %w", command, err)
}
if len(normalizedArtifacts) > 0 && !plan.Contains("analyze") && !plan.Contains("publish") {
return boundedRunRequest{}, fmt.Errorf("%s: --artifacts requires a selected range containing analyze or publish", command)
}
return boundedRunRequest{
Config: configFlags,
Plan: plan,
Force: force.value,
SelectedArtifacts: normalizedArtifacts,
}, nil
}

View File

@@ -3,10 +3,10 @@ package app
import ( import (
"bytes" "bytes"
"context" "context"
"io"
"path/filepath" "path/filepath"
"reflect" "reflect"
"strings"
"testing" "testing"
"time" "time"
@@ -14,125 +14,6 @@ import (
"gitea.maximumdirect.net/eric/narratio/internal/manifest" "gitea.maximumdirect.net/eric/narratio/internal/manifest"
) )
func TestBoundedRunParsingIsSharedByRunAndPlan(t *testing.T) {
args := []string{
"2026-05-03",
"--from", "extract",
"--through=publish",
"--force",
"--artifacts", "session_recap,player_handout",
"--artifacts=session_recap",
"--config", "pipeline.yml",
}
runRequest, err := parseBoundedRunRequest("run", args, io.Discard)
if err != nil {
t.Fatalf("parse run request: %v", err)
}
planRequest, err := parseBoundedRunRequest("plan", args, io.Discard)
if err != nil {
t.Fatalf("parse plan request: %v", err)
}
if !reflect.DeepEqual(runRequest.Plan.Names(), planRequest.Plan.Names()) ||
runRequest.Plan.From() != planRequest.Plan.From() ||
runRequest.Plan.Through() != planRequest.Plan.Through() ||
runRequest.Force != planRequest.Force ||
!reflect.DeepEqual(runRequest.SelectedArtifacts, planRequest.SelectedArtifacts) ||
runRequest.Config != planRequest.Config {
t.Fatalf("run request = %#v, plan request = %#v", runRequest, planRequest)
}
wantArtifacts := []string{"player_handout", "session_recap"}
if !reflect.DeepEqual(runRequest.SelectedArtifacts, wantArtifacts) {
t.Fatalf("artifacts = %#v, want %#v", runRequest.SelectedArtifacts, wantArtifacts)
}
}
func TestBoundedRunParsingRejectsDuplicateSingletons(t *testing.T) {
tests := []struct {
name string
args []string
want string
}{
{name: "from separate", args: []string{"session", "--from", "render", "--from", "extract"}, want: "--from may be specified only once"},
{name: "from equals", args: []string{"session", "--from=render", "--from=extract"}, want: "--from may be specified only once"},
{name: "through mixed", args: []string{"session", "--through", "analyze", "--through=publish"}, want: "--through may be specified only once"},
{name: "force separate", args: []string{"session", "--force", "--force"}, want: "--force may be specified only once"},
{name: "force equals", args: []string{"session", "--force=true", "--force=false"}, want: "--force may be specified only once"},
{name: "overlay", args: []string{"session", "--overlay", "production", "--overlay=testing"}, want: "--overlay may be specified only once"},
}
for _, test := range tests {
t.Run(test.name, func(t *testing.T) {
_, err := parseBoundedRunRequest("run", test.args, io.Discard)
if err == nil || !strings.Contains(err.Error(), test.want) {
t.Fatalf("error = %v, want %q", err, test.want)
}
})
}
}
func TestBoundedRunParsingRetainsExplicitOverlayPresence(t *testing.T) {
withoutOverlay, err := parseBoundedRunRequest("run", []string{"session"}, io.Discard)
if err != nil {
t.Fatal(err)
}
if got := withoutOverlay.Config.sessionOptions().Overlay; got != nil {
t.Fatalf("omitted overlay = %#v, want nil", got)
}
withOverlay, err := parseBoundedRunRequest("run", []string{"session", "--overlay", "testing"}, io.Discard)
if err != nil {
t.Fatal(err)
}
if got := withOverlay.Config.sessionOptions().Overlay; got == nil || *got != "testing" {
t.Fatalf("explicit overlay = %#v, want testing", got)
}
explicitEmpty, err := parseBoundedRunRequest("run", []string{"session", "--overlay", ""}, io.Discard)
if err != nil {
t.Fatal(err)
}
if got := explicitEmpty.Config.sessionOptions().Overlay; got == nil || *got != "" {
t.Fatalf("explicit empty overlay = %#v, want non-nil empty", got)
}
}
func TestBoundedRunParsingUsesSharedRangeValidation(t *testing.T) {
args := []string{"session", "--from", "publish", "--through", "render"}
runRequest, runErr := parseBoundedRunRequest("run", args, io.Discard)
planRequest, planErr := parseBoundedRunRequest("plan", args, io.Discard)
if runErr == nil || planErr == nil {
t.Fatalf("run request=%#v error=%v; plan request=%#v error=%v", runRequest, runErr, planRequest, planErr)
}
runDetail := strings.TrimPrefix(runErr.Error(), "run: ")
planDetail := strings.TrimPrefix(planErr.Error(), "plan: ")
if runDetail != planDetail || !strings.Contains(runDetail, `from stage "publish" occurs after through stage "render"`) {
t.Fatalf("run error = %q, plan error = %q", runErr, planErr)
}
}
func TestBoundedRunParsingGatesArtifactSelectionByRange(t *testing.T) {
for _, test := range []struct {
name string
through string
wantErr bool
}{
{name: "render only", through: "render", wantErr: true},
{name: "analyze only", through: "analyze"},
{name: "publish only", through: "publish"},
} {
t.Run(test.name, func(t *testing.T) {
_, err := parseBoundedRunRequest("run", []string{
"session", "--from", test.through, "--through", test.through, "--artifacts", "session_recap",
}, io.Discard)
if test.wantErr && (err == nil || !strings.Contains(err.Error(), "range containing analyze or publish")) {
t.Fatalf("error = %v, want artifact/range error", err)
}
if !test.wantErr && err != nil {
t.Fatalf("error = %v", err)
}
})
}
}
func TestRunPassesBoundedPlanToRunner(t *testing.T) { func TestRunPassesBoundedPlanToRunner(t *testing.T) {
workspaceRoot := t.TempDir() workspaceRoot := t.TempDir()
pipelinePath, campaignPath, sessionPath := writeValidConfigFiles(t, workspaceRoot) pipelinePath, campaignPath, sessionPath := writeValidConfigFiles(t, workspaceRoot)
@@ -148,15 +29,13 @@ func TestRunPassesBoundedPlanToRunner(t *testing.T) {
} }
var out bytes.Buffer var out bytes.Buffer
err := runWithPipelineExecutor(context.Background(), []string{ err := invokeNativeCommandWith(context.Background(), []string{"run", "2026-05-03",
"2026-05-03",
"--from", "render", "--from", "render",
"--through", "extract", "--through", "extract",
"--force", "--force",
"--config", pipelinePath, "--config", pipelinePath,
"--campaign-file", campaignPath, "--campaign-file", campaignPath, "--session-file", sessionPath,
"--session", sessionPath, }, &out, executor, commandDependencies{})
}, &out, executor)
if err != nil { if err != nil {
t.Fatalf("Run() error = %v", err) t.Fatalf("Run() error = %v", err)
} }
@@ -179,44 +58,18 @@ func TestPlanPrintsOnlyBoundedRange(t *testing.T) {
t.Fatalf("save prerequisite manifest: %v", err) t.Fatalf("save prerequisite manifest: %v", err)
} }
var out bytes.Buffer var out bytes.Buffer
err := Plan(context.Background(), []string{ err := invokeNativeCommand(context.Background(), []string{"session", "plan", "2026-05-03",
"2026-05-03",
"--from", "render", "--from", "render",
"--through", "extract", "--through", "extract",
"--config", pipelinePath, "--config", pipelinePath,
"--campaign-file", campaignPath, "--campaign-file", campaignPath, "--session-file", sessionPath,
"--session", sessionPath,
}, &out) }, &out)
if err != nil { if err != nil {
t.Fatalf("Plan() error = %v", err) t.Fatalf("Plan() error = %v", err)
} }
got := out.String() report := decodeNativeReport[sessionPlanReport](t, out.Bytes())
if !strings.Contains(got, "render: run\nextract: run\ntotals: run=2 skip=0") { if len(report.Stages) != 2 || report.Stages[0].Name != "render" || report.Stages[1].Name != "extract" || report.Stages[0].Action != "run" || report.Stages[1].Action != "run" {
t.Fatalf("output = %q, want bounded decisions", got) t.Fatalf("bounded plan=%#v", report)
} }
if strings.Contains(got, "trim: ") || strings.Contains(got, "analyze: ") {
t.Fatalf("output = %q, contains excluded stages", got)
}
}
func TestBoundedRunCommandHelp(t *testing.T) {
for _, test := range []struct {
name string
args []string
want string
}{
{name: "run", args: []string{"run", "--help"}, want: "Usage: narratio run <session_id> [--from <stage>] [--through <stage>]"},
{name: "plan", args: []string{"session", "plan", "--help"}, want: "Usage: narratio session plan <session_id> [--from <stage>] [--through <stage>]"},
} {
t.Run(test.name, func(t *testing.T) {
var stdout bytes.Buffer
var stderr bytes.Buffer
if code := Execute(test.args, &stdout, &stderr); code != 0 {
t.Fatalf("exit code = %d, stderr = %q", code, stderr.String())
}
if !strings.Contains(stdout.String(), test.want) || stderr.Len() != 0 {
t.Fatalf("stdout = %q stderr = %q, want %q", stdout.String(), stderr.String(), test.want)
}
})
}
} }

View File

@@ -12,9 +12,6 @@ import (
func resolveCampaignConfigPath(pipelineCfg *config.PipelineConfig, campaignIDFlag, campaignFileFlag string) (string, error) { func resolveCampaignConfigPath(pipelineCfg *config.PipelineConfig, campaignIDFlag, campaignFileFlag string) (string, error) {
campaignID := strings.TrimSpace(campaignIDFlag) campaignID := strings.TrimSpace(campaignIDFlag)
campaignFile := strings.TrimSpace(campaignFileFlag) campaignFile := strings.TrimSpace(campaignFileFlag)
if campaignID != "" && campaignFile != "" {
return "", fmt.Errorf("--campaign and --campaign-file are mutually exclusive")
}
if campaignFile != "" { if campaignFile != "" {
return filepath.Clean(campaignFile), nil return filepath.Clean(campaignFile), nil
} }

View File

@@ -50,13 +50,11 @@ func TestResolveCampaignConfigPathUsesDefaultCampaignID(t *testing.T) {
} }
} }
func TestResolveCampaignConfigPathRejectsCampaignIDAndFile(t *testing.T) { func TestResolveCampaignConfigPathCombinesIdentityAndFile(t *testing.T) {
_, err := resolveCampaignConfigPath(&config.PipelineConfig{}, "dilfs", filepath.Join(t.TempDir(), "campaign.yml")) explicit := filepath.Join(t.TempDir(), "campaign.yml")
if err == nil { got, err := resolveCampaignConfigPath(&config.PipelineConfig{}, "dilfs", explicit)
t.Fatal("expected error, got nil") if err != nil || got != explicit {
} t.Fatalf("path=%q error=%v", got, err)
if !strings.Contains(err.Error(), "mutually exclusive") {
t.Fatalf("error = %q, want mutual exclusion", err.Error())
} }
} }

View File

@@ -0,0 +1,244 @@
package app
import (
"bytes"
"context"
"encoding/json"
"errors"
"os"
"path/filepath"
"reflect"
"strings"
"testing"
"time"
"gitea.maximumdirect.net/eric/narratio/internal/adapters/scriptorium"
"gitea.maximumdirect.net/eric/narratio/internal/artifactpolicy"
"gitea.maximumdirect.net/eric/narratio/internal/artifacts"
"gitea.maximumdirect.net/eric/narratio/internal/config"
"gitea.maximumdirect.net/eric/narratio/internal/manifest"
"go.maximumdirect.net/commandkit"
)
func TestSelectedPartyCatalogDrivesBoundedAnalysis(t *testing.T) {
dir := t.TempDir()
pipelinePath := filepath.Join(dir, "pipeline.yml")
const secret = "synthetic-family-workflow-credential"
t.Setenv("NARRATIO_WORKFLOW_TEST_KEY", secret)
mustWriteTestFile(t, pipelinePath, "config:\n imports:\n - {path: family.yml, required: true}\n")
mustWriteTestFile(t, filepath.Join(dir, "overlays", "testing.yml"), "scriptorium:\n artifact_families:\n character_note:\n prompt_id: note-testing\n")
mustWriteTestFile(t, filepath.Join(dir, "family.yml"), `whisperx:
transcribe_url: https://transcription.example.test/transcribe
workspace:
root: `+filepath.Join(dir, "work")+`
scriptorium:
credentials: [NARRATIO_WORKFLOW_TEST_KEY]
artifact_families:
character_meta:
enabled: false
for_each: party.characters
prompt_id: meta
output_path_pattern: artifacts/{character_id}/meta.md
inputs:
players: {source: narratio.input.players, required: true}
character_note:
enabled: false
for_each: party.characters
prompt_id: note
output_path_pattern: artifacts/{character_id}/note.md
inputs:
meta: {source: narratio.member_artifact.character_meta, required: true}
member_vars:
character_name: character.name
`)
campaignPath := filepath.Join(dir, "campaign.yml")
mustWriteTestFile(t, campaignPath, "campaign_id: campaign\ninputs: {speakers_file: speakers.yml, autocorrect_file: autocorrect.yml, glossary_file: glossary.yml, party_file: default-party.yml}\n")
partyPath := filepath.Join(dir, "selected-party.yml")
mustWriteTestFile(t, partyPath, "schema_version: narratio.party.v1\ncharacters:\n ivy:\n player: {name: Selected Player}\n character: {name: Ivy, classes: [{name: ranger}]}\n")
sessionPath := filepath.Join(dir, "session.yml")
mustWriteTestFile(t, sessionPath, "session_id: session\ninputs: {audio_dir: audio}\n")
overlay := "testing"
pipeline, err := config.LoadPipelineWithOptions(pipelinePath, config.PipelineLoadOptions{Overlay: &overlay})
if err != nil {
t.Fatal(err)
}
campaign, err := config.LoadCampaign(campaignPath)
if err != nil {
t.Fatal(err)
}
loaded, err := config.LoadPipelineCampaignWithPartyFile(pipelinePath, pipeline, campaignPath, campaign, &partyPath)
if err != nil {
t.Fatal(err)
}
cfg, err := config.LoadSessionWithPipelineCampaignOptions(loaded, sessionPath, config.SessionLoadOptions{})
if err != nil {
t.Fatal(err)
}
before, err := json.Marshal(cfg.Pipeline)
if err != nil {
t.Fatal(err)
}
catalogSelection := []string{"--config", pipelinePath, "--overlay", overlay, "--campaign-file", campaignPath, "--party-file", partyPath, "--secrets-dir", t.TempDir(), "--format", "json"}
common := append(append([]string{}, catalogSelection...), "--session-file", sessionPath)
for _, scope := range []string{"app", "session", "party"} {
output := nativeInspectionForTest(t, append([]string{"config", "show", "--scope", scope}, common...))
if strings.Contains(output, secret) {
t.Fatal("native inspection exposed credentials")
}
if scope == "app" && (!strings.Contains(output, "artifact_families") || strings.Contains(output, "character_meta_ivy")) {
t.Fatal("native app inspection substituted derived configuration")
}
if scope == "session" {
var effective map[string]any
if err := json.Unmarshal([]byte(output), &effective); err != nil {
t.Fatal(err)
}
if effective["campaign"] != "campaign" || effective["session_id"] != "session" {
t.Fatalf("inspection lost resolved session defaults: %#v", effective)
}
}
if scope == "party" && !strings.Contains(output, "Selected Player") {
t.Fatal("party inspection used a different roster")
}
}
diff := nativeInspectionForTest(t, []string{"config", "diff", "--config", pipelinePath, "--against-config", pipelinePath, "--against-overlay", overlay, "--details", "--format", "json"})
if !strings.Contains(diff, "/scriptorium/artifact_families/character_note/prompt_id") || strings.Contains(diff, secret) {
t.Fatalf("unexpected independent comparison: %s", diff)
}
catalog := nativeInspectionForTest(t, append([]string{"artifacts", "list"}, catalogSelection...))
if !strings.Contains(catalog, "character_note_ivy") {
t.Fatal("catalog omitted selected member")
}
selected := []string{"--stage", "analyze", "--artifacts", "character_note"}
planned := nativeInspectionForTest(t, append(append([]string{"session", "plan", "session"}, common...), "--stage", "prepare"))
if !strings.Contains(planned, "prepare") || strings.Contains(planned, secret) {
t.Fatal("initial plan lost selection or exposed credentials")
}
if _, err := os.Stat(cfg.Pipeline.Workspace.Root); !os.IsNotExist(err) {
t.Fatalf("inspection or planning created workspace: %v", err)
}
plan, err := BuildBoundedPlan("analyze", "analyze")
if err != nil {
t.Fatal(err)
}
paths := artifacts.NewLocalStore(cfg.Pipeline.Workspace.Root).SessionPathsFor("campaign", "session")
now := time.Now().UTC()
seed := manifest.New("session", now)
seed.Campaign = "campaign"
for _, name := range plan.PrefixNames() {
seed.MarkStageSucceeded(name, now, nil)
}
playersPath := filepath.Join(paths.InputsDir, "players.yml")
mustWriteTestFile(t, playersPath, string(cfg.Party.Players))
checksum, err := artifacts.SHA256File(playersPath)
if err != nil {
t.Fatal(err)
}
descriptor, ok := artifactpolicy.DescribePreparedInputSource("narratio.input.players")
if !ok {
t.Fatal("players source is unavailable")
}
seed.Inputs = append(seed.Inputs, manifest.InputRecord{Kind: descriptor.ManifestKind, Path: playersPath, Checksum: checksum})
saveBoundedManifest(t, cfg, seed)
persisted, err := os.ReadFile(manifestPathFor(cfg))
if err != nil {
t.Fatal(err)
}
planned = nativeInspectionForTest(t, append(append([]string{"session", "plan", "session"}, common...), selected...))
if !strings.Contains(planned, "character_meta_ivy") || strings.Contains(planned, secret) {
t.Fatal("plan lost prerequisites or exposed credentials")
}
afterPlan, err := os.ReadFile(manifestPathFor(cfg))
if err != nil || !bytes.Equal(persisted, afterPlan) {
t.Fatal("planning changed durable state")
}
failure := errors.New("synthetic later artifact failure")
runner := &familyWorkflowRunner{failure: failure}
var captured *config.Config
application, err := newApplication(commandDependencies{}, func(ctx context.Context, acquired *config.Config, selected BoundedPlan, options RunOptions) (*RunSummary, error) {
captured = acquired
before, err := json.Marshal(acquired.Pipeline)
if err != nil {
return nil, err
}
options.Env = &Env{Scriptorium: runner}
summary, runErr := executePlan(ctx, acquired, selected, options)
after, err := json.Marshal(acquired.Pipeline)
if err != nil || !bytes.Equal(before, after) {
t.Fatal("native execution mutated completed configuration")
}
return summary, runErr
})
if err != nil {
t.Fatal(err)
}
args := append(append([]string{"run", "session"}, common...), selected...)
var output, diagnostics bytes.Buffer
outcome := application.Execute(context.Background(), args, commandkit.Streams{Out: &output, Err: &diagnostics})
if outcome.Status != 1 || !errors.Is(outcome.Cause, failure) {
t.Fatalf("failed outcome=%#v diagnostics=%s", outcome, diagnostics.String())
}
partial := decodeNativeReport[runReport](t, output.Bytes())
if partial.Complete || len(partial.StageResults) != 1 || partial.StageResults[0].Outcome != "failed" || len(partial.AvailableArtifacts) == 0 {
t.Fatalf("partial report=%#v", partial)
}
failed, err := (&manifest.LocalStore{}).Load(context.Background(), manifestPathFor(cfg))
if err != nil {
t.Fatal(err)
}
if failed.Stages["analyze"].AnalyzeArtifacts["character_meta_ivy"].Status != manifest.AnalyzeArtifactCurrent {
t.Fatal("earlier family checkpoint was lost")
}
if strings.Contains(output.String()+diagnostics.String(), secret) {
t.Fatal("failure report exposed credentials")
}
runner.failure = nil
output.Reset()
diagnostics.Reset()
outcome = application.Execute(context.Background(), args, commandkit.Streams{Out: &output, Err: &diagnostics})
if outcome.Status != 0 {
t.Fatalf("retry status=%d diagnostics=%s", outcome.Status, diagnostics.String())
}
summary := decodeNativeReport[runReport](t, output.Bytes())
if !summary.Complete || !reflect.DeepEqual(summary.Executed, []string{"analyze"}) || len(runner.RunRequests) != 2 || runner.RunRequests[0].PromptID != "meta" || runner.RunRequests[1].PromptID != "note-testing" {
t.Fatalf("bounded family retry: summary=%+v requests=%+v", summary, runner.RunRequests)
}
if captured == nil || len(captured.Pipeline.Scriptorium.Artifacts) != 0 || strings.Contains(output.String()+diagnostics.String(), secret) {
t.Fatal("retry lost the configuration/report boundary")
}
players, err := os.ReadFile(runner.RunRequests[0].InputPaths["players"])
if err != nil || !strings.Contains(string(players), "Selected Player") || runner.RunRequests[1].Vars["character_name"] != "Ivy" {
t.Fatalf("selected roster did not reach both domain consumers: %v", err)
}
current, err := (&manifest.LocalStore{}).Load(context.Background(), manifestPathFor(cfg))
if err != nil {
t.Fatal(err)
}
for _, key := range []string{"character_meta_ivy", "character_note_ivy"} {
record := current.Stages["analyze"].AnalyzeArtifacts[key]
if record.Status != manifest.AnalyzeArtifactCurrent || record.CharacterID != "ivy" || record.Family == "" {
t.Fatalf("family output identity: %+v", record)
}
}
after, err := json.Marshal(cfg.Pipeline)
if err != nil {
t.Fatal(err)
}
if !bytes.Equal(before, after) || len(cfg.Pipeline.Scriptorium.Artifacts) != 0 {
t.Fatal("execution changed completed pipeline configuration")
}
}
// familyWorkflowRunner replaces only the downstream process, retaining real
// acquisition, catalog derivation, execution, persistence, and reporting.
type familyWorkflowRunner struct {
scriptorium.FakeRunner
failure error
}
func (r *familyWorkflowRunner) RunArtifact(ctx context.Context, request scriptorium.RunArtifactRequest) (scriptorium.ArtifactResult, error) {
if request.PromptID == "note-testing" && r.failure != nil {
return scriptorium.ArtifactResult{}, r.failure
}
return r.FakeRunner.RunArtifact(ctx, request)
}

View File

@@ -1,177 +1,12 @@
package app package app
import ( import (
"context"
"flag"
"fmt" "fmt"
"io"
"os" "os"
"path/filepath" "path/filepath"
"strings" "strings"
"gitea.maximumdirect.net/eric/narratio/internal/artifacts"
"gitea.maximumdirect.net/eric/narratio/internal/config"
"gitea.maximumdirect.net/eric/narratio/internal/fileops"
) )
// Clean removes local workspace/spool state while preserving durable cache
// state unless cache cleanup is explicitly requested.
func Clean(ctx context.Context, args []string, out io.Writer) error {
return cleanWithDependencies(ctx, args, out, commandDependencies{})
}
func cleanWithDependencies(ctx context.Context, args []string, out io.Writer, deps commandDependencies) error {
deps = normalizeCommandDependencies(deps)
fs := flag.NewFlagSet("clean", flag.ContinueOnError)
fs.SetOutput(io.Discard)
var flags commonConfigFlags
var all bool
var dryRun bool
var clearCache bool
addCommonConfigFlags(fs, &flags)
fs.BoolVar(&all, "all", false, "clean all local session work/spool state")
fs.BoolVar(&dryRun, "dry-run", false, "print cleanup targets without deleting")
fs.BoolVar(&clearCache, "clear-cache", false, "also clear durable S3 audio cache entries")
if err := parseSessionAwareFlags("clean", fs, args, &flags.sessionID); err != nil {
return err
}
if all {
return cleanAllLocalWithDependencies(flags, dryRun, clearCache, out, deps)
}
return cleanSessionWithDependencies(ctx, flags, dryRun, clearCache, out, deps)
}
func cleanSessionWithDependencies(ctx context.Context, flags commonConfigFlags, dryRun, clearCache bool, out io.Writer, deps commandDependencies) error {
if strings.TrimSpace(flags.sessionID) == "" {
return fmt.Errorf("clean: session_id is required unless --all is set")
}
loaded, err := loadCommandConfigWithDependencies(ctx, flags.pipelinePath, flags.campaignPath, flags.campaignFilePath, flags.sessionPath, flags.sessionOptions(), flags.secretsDir.pointer(), deps)
if err != nil {
return fmt.Errorf("clean: %w", err)
}
defer func() { _ = loaded.Close() }()
cfg := loaded.Config
if cfg == nil || cfg.Pipeline == nil || cfg.Session == nil {
return fmt.Errorf("clean: resolved pipeline and session config are required")
}
campaign := strings.TrimSpace(cfg.Session.Campaign)
sessionID := strings.TrimSpace(cfg.Session.SessionID)
if campaign == "" || sessionID == "" {
return fmt.Errorf("clean: campaign and session_id are required")
}
if dryRun {
fmt.Fprintf(out, "Clean plan for %s/%s\n", campaign, sessionID)
} else {
fmt.Fprintf(out, "Cleaned %s/%s\n", campaign, sessionID)
}
workDir := artifacts.SessionWorkDirForCampaign(cfg.Pipeline.Workspace.Root, campaign, sessionID)
spoolDir := artifacts.SessionSpoolDir(cfg.Pipeline.Spool.Root, campaign, sessionID)
if err := reportCleanScopedDir(out, cfg.Pipeline.Workspace.Root, workDir, "clean.workspace.session", dryRun); err != nil {
return fmt.Errorf("clean: %w", err)
}
if err := reportCleanScopedDir(out, cfg.Pipeline.Spool.Root, spoolDir, "clean.spool.session", dryRun); err != nil {
return fmt.Errorf("clean: %w", err)
}
if clearCache {
if err := cleanSessionAudioCacheWithDependencies(ctx, cfg, dryRun, out, deps); err != nil {
return fmt.Errorf("clean: %w", err)
}
} else {
fmt.Fprintln(out, "Cache: preserved")
}
return nil
}
func cleanAllLocalWithDependencies(flags commonConfigFlags, dryRun, clearCache bool, out io.Writer, deps commandDependencies) error {
if strings.TrimSpace(flags.campaignPath) != "" ||
strings.TrimSpace(flags.campaignFilePath) != "" ||
strings.TrimSpace(flags.sessionPath) != "" ||
strings.TrimSpace(flags.sessionID) != "" ||
strings.TrimSpace(flags.previousSessionID) != "" {
return fmt.Errorf("clean: --all cannot be combined with --campaign, --campaign-file, --session, a session_id, or --previous-session-id")
}
_, pipelineCfg, err := loadPipelineConfigWithDependencies(flags.pipelinePath, config.PipelineLoadOptions{Overlay: flags.overlay.pointer()}, flags.secretsDir.pointer(), deps)
if err != nil {
return fmt.Errorf("clean: %w", err)
}
if dryRun {
fmt.Fprintln(out, "Clean plan for all local sessions")
} else {
fmt.Fprintln(out, "Cleaned all local sessions")
}
workRoot := filepath.Join(pipelineCfg.Workspace.Root, config.PathWorkDirSegment)
if err := reportCleanScopedDir(out, pipelineCfg.Workspace.Root, workRoot, "clean.workspace.all", dryRun); err != nil {
return fmt.Errorf("clean: %w", err)
}
if err := reportCleanRootChildren(out, pipelineCfg.Spool.Root, "clean.spool.all", dryRun); err != nil {
return fmt.Errorf("clean: %w", err)
}
if clearCache {
if err := cleanAllAudioCache(pipelineCfg, dryRun, out); err != nil {
return fmt.Errorf("clean: %w", err)
}
} else {
fmt.Fprintln(out, "Cache: preserved")
}
return nil
}
func reportCleanScopedDir(out io.Writer, root, target, policy string, dryRun bool) error {
dir, err := validateScopedDir(root, target, policy)
if err != nil {
return err
}
if dryRun {
if dir.Exists {
fmt.Fprintf(out, "Would delete: %s\n", dir.TargetAbs)
} else {
fmt.Fprintf(out, "Would skip missing: %s\n", dir.TargetAbs)
}
return nil
}
if !dir.Exists {
fmt.Fprintf(out, "Missing: %s\n", dir.TargetAbs)
return nil
}
if err := fileops.RemoveAllUnderRoot(dir.RootAbs, dir.TargetAbs); err != nil {
return fmt.Errorf("cleanup policy %s: remove %q: %w", policy, dir.TargetAbs, err)
}
fmt.Fprintf(out, "Deleted: %s\n", dir.TargetAbs)
return nil
}
func reportCleanRootChildren(out io.Writer, root, policy string, dryRun bool) error {
rootAbs, entries, err := cleanableRootChildren(root, policy)
if err != nil {
return err
}
if len(entries) == 0 {
if dryRun {
fmt.Fprintf(out, "Would skip empty: %s\n", rootAbs)
} else {
fmt.Fprintf(out, "Empty: %s\n", rootAbs)
}
return nil
}
for _, entry := range entries {
if dryRun {
fmt.Fprintf(out, "Would delete: %s\n", entry)
continue
}
if err := fileops.RemoveAllUnderRoot(rootAbs, entry); err != nil {
return fmt.Errorf("cleanup policy %s: remove %q: %w", policy, entry, err)
}
fmt.Fprintf(out, "Deleted: %s\n", entry)
}
return nil
}
func cleanableRootChildren(root, policy string) (string, []string, error) { func cleanableRootChildren(root, policy string) (string, []string, error) {
rootAbs, exists, err := validateCleanRoot(root, policy) rootAbs, exists, err := validateCleanRoot(root, policy)
if err != nil { if err != nil {
@@ -199,83 +34,6 @@ func cleanableRootChildren(root, policy string) (string, []string, error) {
return rootAbs, out, nil return rootAbs, out, nil
} }
func cleanSessionAudioCacheWithDependencies(ctx context.Context, cfg *config.Config, dryRun bool, out io.Writer, deps commandDependencies) error {
if cfg.Session.Inputs.AudioS3 == nil {
fmt.Fprintln(out, "Cache: skipped (session does not use audio_s3)")
return nil
}
if cfg.Pipeline.Storage.S3 == nil || strings.TrimSpace(cfg.Pipeline.Storage.S3.Bucket) == "" {
return fmt.Errorf("clear cache requires pipeline.storage.s3.bucket")
}
store, err := newCommandObjectStoreWithDependencies(ctx, cfg, nil, deps)
if err != nil {
return fmt.Errorf("initialize object store for cache cleanup: %w", err)
}
sessionPrefix := artifacts.S3SessionPrefix(cfg.Pipeline.Storage.S3.RootPrefix, cfg.Session.Campaign, cfg.Session.SessionID)
audioPrefix := artifacts.S3AudioPrefix(sessionPrefix, cfg.Session.Inputs.AudioS3.Prefix)
objects, err := store.List(ctx, audioPrefix)
if err != nil {
return fmt.Errorf("list s3 audio objects under %q: %w", audioPrefix, err)
}
count := 0
for _, obj := range objects {
key := strings.TrimSpace(obj.Key)
if key == "" || strings.HasSuffix(key, "/") || !cleanIsFlac(key) {
continue
}
cachePath, err := artifacts.S3AudioCachePath(cfg.Pipeline.Cache.Root, cfg.Pipeline.Storage.S3.Bucket, key)
if err != nil {
return err
}
deleted, err := reportCleanScopedFile(out, cfg.Pipeline.Cache.Root, cachePath, "clean.cache.session", dryRun)
if err != nil {
return err
}
if deleted {
count++
}
}
if count == 0 {
fmt.Fprintf(out, "Cache: no cached S3 audio files found for %s\n", audioPrefix)
}
return nil
}
func cleanAllAudioCache(cfg *config.PipelineConfig, dryRun bool, out io.Writer) error {
if cfg.Storage.S3 == nil || strings.TrimSpace(cfg.Storage.S3.Bucket) == "" {
return fmt.Errorf("clear cache requires pipeline.storage.s3.bucket")
}
namespaceDir, err := artifacts.S3AudioCacheNamespaceDir(cfg.Cache.Root, cfg.Storage.S3.Bucket, cfg.Storage.S3.RootPrefix)
if err != nil {
return err
}
return reportCleanScopedDir(out, cfg.Cache.Root, namespaceDir, "clean.cache.all", dryRun)
}
func reportCleanScopedFile(out io.Writer, root, target, policy string, dryRun bool) (bool, error) {
file, err := validateScopedFile(root, target, policy)
if err != nil {
return false, err
}
if dryRun {
if file.Exists {
fmt.Fprintf(out, "Would delete cache file: %s\n", file.TargetAbs)
return true, nil
}
fmt.Fprintf(out, "Would skip missing cache file: %s\n", file.TargetAbs)
return false, nil
}
if !file.Exists {
fmt.Fprintf(out, "Missing cache file: %s\n", file.TargetAbs)
return false, nil
}
if err := fileops.RemoveAllUnderRoot(file.RootAbs, file.TargetAbs); err != nil {
return false, fmt.Errorf("cleanup policy %s: remove %q: %w", policy, file.TargetAbs, err)
}
fmt.Fprintf(out, "Deleted cache file: %s\n", file.TargetAbs)
return true, nil
}
func validateScopedFile(root, target, policy string) (scopedDir, error) { func validateScopedFile(root, target, policy string) (scopedDir, error) {
return validateScopedTarget(root, target, policy, false) return validateScopedTarget(root, target, policy, false)
} }

View File

@@ -0,0 +1,240 @@
package app
import (
"context"
"errors"
"fmt"
"path/filepath"
"strings"
"gitea.maximumdirect.net/eric/narratio/internal/artifacts"
"gitea.maximumdirect.net/eric/narratio/internal/config"
"gitea.maximumdirect.net/eric/narratio/internal/fileops"
"go.maximumdirect.net/commandkit"
)
type cleanCommandInput struct {
Selection configurationSelection
PreviousSession commandkit.Supplied[string]
All, DryRun, ClearCache bool
}
type cleanCommandReport struct {
Campaign string `json:"campaign,omitempty"`
SessionID string `json:"session_id,omitempty"`
All bool `json:"all"`
DryRun bool `json:"dry_run"`
Complete bool `json:"complete"`
Cache string `json:"cache"`
Actions []cleanAction `json:"actions"`
Error string `json:"error,omitempty"`
}
type cleanAction struct {
Path string `json:"path"`
Status string `json:"status"`
Error string `json:"error,omitempty"`
}
func checkCleanInput(input *cleanCommandInput) error {
if err := checkConfigurationSelection(input.Selection); err != nil {
return err
}
if input.All {
if input.Selection.Session.Set || input.Selection.SessionFile.Set || input.Selection.Campaign.Set || input.Selection.CampaignFile.Set || input.Selection.PartyFile.Set || input.PreviousSession.Set {
return fmt.Errorf("--all cannot be combined with session, campaign, party, or previous-session selections")
}
} else if !input.Selection.Session.Set {
return fmt.Errorf("session identity is required unless --all is set")
}
return nil
}
func cleanCommand(deps commandDependencies) commandkit.Command {
common := newConfigurationFlags(func(input **cleanCommandInput) *configurationSelection { return &(*input).Selection })
return commandkit.NewCommand(commandkit.CommandSpec[*cleanCommandInput]{Name: "clean", Summary: "Remove selected local session data, preserving cache unless requested.", NewInput: func() *cleanCommandInput { return &cleanCommandInput{} },
Flags: []commandkit.Flag[*cleanCommandInput]{common.Config, common.Overlay, common.Campaign, common.CampaignFile, common.SessionFile, common.PartyFile, common.SecretsDir,
commandkit.ValueFlag(commandkit.FlagMeta{Name: "previous-session-id", Usage: "Assert the previous session identity."}, nil, stringValue, func(input **cleanCommandInput, value commandkit.Supplied[string]) { (*input).PreviousSession = value }),
commandkit.BoolFlag(commandkit.FlagMeta{Name: "all", Usage: "Clean all local session workspace and spool entries."}, false, func(input **cleanCommandInput, value commandkit.Supplied[bool]) { (*input).All = value.Value }),
commandkit.BoolFlag(commandkit.FlagMeta{Name: "dry-run", Usage: "Preview exact paths without deleting them."}, false, func(input **cleanCommandInput, value commandkit.Supplied[bool]) { (*input).DryRun = value.Value }),
commandkit.BoolFlag(commandkit.FlagMeta{Name: "clear-cache", Usage: "Also remove the selected S3 audio cache entries."}, false, func(input **cleanCommandInput, value commandkit.Supplied[bool]) { (*input).ClearCache = value.Value }),
},
Arguments: []commandkit.Argument[*cleanCommandInput]{commandkit.ValueArgument(commandkit.ArgumentMeta{Name: "SESSION", Usage: "Session identity, omitted with --all."}, false, stringValue, func(input **cleanCommandInput, value commandkit.Supplied[string]) { (*input).Selection.Session = value })},
CheckInput: checkCleanInput,
Run: func(invocation commandkit.Invocation, input *cleanCommandInput) commandkit.Outcome {
report, err := cleanSelectedSession(invocation.Context, input, withCommandReporting(deps, invocation))
if report != nil {
err = errors.Join(err, invocation.Reporter().Report(commandkit.Report{Value: report}))
}
return reportOperationOutcome(invocation, err)
},
})
}
func cleanSelectedSession(ctx context.Context, input *cleanCommandInput, deps commandDependencies) (report *cleanCommandReport, err error) {
deps = normalizeCommandDependencies(deps)
deps.secretsBootstrap = &secretsBootstrap{}
acquired := newConfigurationAcquisition(input.Selection, deps)
acquired.previousSessionID = input.PreviousSession.Value
defer func() {
err = errors.Join(err, acquired.Close())
if report != nil {
report.Complete = err == nil && !input.DryRun
if err != nil {
report.Error = err.Error()
}
}
}()
report = &cleanCommandReport{All: input.All, DryRun: input.DryRun, Cache: "preserved", Actions: []cleanAction{}}
if input.ClearCache {
report.Cache = "requested"
}
pipeline, err := acquired.Pipeline(ctx)
if err != nil {
return report, err
}
appendTarget := func(root, target, policy string, directory bool) error {
if err := ctx.Err(); err != nil {
return err
}
action, err := cleanScopedTarget(root, target, policy, directory, input.DryRun)
report.Actions = append(report.Actions, action)
return err
}
if input.All {
if err := appendTarget(pipeline.Workspace.Root, filepath.Join(pipeline.Workspace.Root, config.PathWorkDirSegment), "clean.workspace.all", true); err != nil {
return report, err
}
actions, err := cleanRootChildren(ctx, pipeline.Spool.Root, "clean.spool.all", input.DryRun)
report.Actions = append(report.Actions, actions...)
if err != nil {
return report, err
}
if input.ClearCache {
if pipeline.Storage.S3 == nil || strings.TrimSpace(pipeline.Storage.S3.Bucket) == "" {
return report, fmt.Errorf("clear cache requires pipeline.storage.s3.bucket")
}
namespace, err := artifacts.S3AudioCacheNamespaceDir(pipeline.Cache.Root, pipeline.Storage.S3.Bucket, pipeline.Storage.S3.RootPrefix)
if err != nil {
return report, err
}
if err := appendTarget(pipeline.Cache.Root, namespace, "clean.cache.all", true); err != nil {
return report, err
}
report.Cache = "processed"
}
return report, nil
}
cfg, err := acquired.Domain(ctx)
if err != nil {
return report, err
}
report.Campaign = cfg.Session.Campaign
report.SessionID = cfg.Session.SessionID
work := artifacts.SessionWorkDirForCampaign(pipeline.Workspace.Root, report.Campaign, report.SessionID)
spool := artifacts.SessionSpoolDir(pipeline.Spool.Root, report.Campaign, report.SessionID)
if err := appendTarget(pipeline.Workspace.Root, work, "clean.workspace.session", true); err != nil {
return report, err
}
if err := appendTarget(pipeline.Spool.Root, spool, "clean.spool.session", true); err != nil {
return report, err
}
if input.ClearCache {
if cfg.Session.Inputs.AudioS3 == nil {
report.Cache = "not_applicable"
return report, nil
}
actions, err := cleanSessionCache(ctx, cfg, input.DryRun, deps)
report.Actions = append(report.Actions, actions...)
if err != nil {
return report, err
}
report.Cache = "processed"
}
return report, nil
}
func cleanScopedTarget(root, target, policy string, directory, dryRun bool) (cleanAction, error) {
action := cleanAction{Path: target, Status: "failed"}
scoped, err := validateScopedTarget(root, target, policy, directory)
if err != nil {
action.Error = err.Error()
return action, err
}
action.Path = scoped.TargetAbs
if !scoped.Exists {
action.Status = "missing"
return action, nil
}
if dryRun {
action.Status = "would_delete"
return action, nil
}
if err := fileops.RemoveAllUnderRoot(scoped.RootAbs, scoped.TargetAbs); err != nil {
action.Error = err.Error()
return action, fmt.Errorf("cleanup policy %s: remove %q: %w", policy, scoped.TargetAbs, err)
}
action.Status = "deleted"
return action, nil
}
func cleanRootChildren(ctx context.Context, root, policy string, dryRun bool) ([]cleanAction, error) {
rootAbs, entries, err := cleanableRootChildren(root, policy)
if err != nil {
return []cleanAction{{Path: root, Status: "failed", Error: err.Error()}}, err
}
if len(entries) == 0 {
return []cleanAction{{Path: rootAbs, Status: "empty"}}, nil
}
actions := make([]cleanAction, 0, len(entries))
for _, entry := range entries {
if err := ctx.Err(); err != nil {
return actions, err
}
action := cleanAction{Path: entry, Status: "would_delete"}
if !dryRun {
if err := fileops.RemoveAllUnderRoot(rootAbs, entry); err != nil {
action.Status = "failed"
action.Error = err.Error()
return append(actions, action), fmt.Errorf("cleanup policy %s: remove %q: %w", policy, entry, err)
}
action.Status = "deleted"
}
actions = append(actions, action)
}
return actions, nil
}
func cleanSessionCache(ctx context.Context, cfg *config.Config, dryRun bool, deps commandDependencies) ([]cleanAction, error) {
if cfg.Pipeline.Storage.S3 == nil || strings.TrimSpace(cfg.Pipeline.Storage.S3.Bucket) == "" {
return nil, fmt.Errorf("clear cache requires pipeline.storage.s3.bucket")
}
store, err := newCommandObjectStoreWithDependencies(ctx, cfg, deps)
if err != nil {
return nil, fmt.Errorf("initialize object store for cache cleanup: %w", err)
}
prefix := artifacts.S3SessionPrefix(cfg.Pipeline.Storage.S3.RootPrefix, cfg.Session.Campaign, cfg.Session.SessionID)
audioPrefix := artifacts.S3AudioPrefix(prefix, cfg.Session.Inputs.AudioS3.Prefix)
objects, err := store.List(ctx, audioPrefix)
if err != nil {
return nil, fmt.Errorf("list s3 audio objects under %q: %w", audioPrefix, err)
}
actions := []cleanAction{}
for _, object := range objects {
if err := ctx.Err(); err != nil {
return actions, err
}
key := strings.TrimSpace(object.Key)
if key == "" || strings.HasSuffix(key, "/") || !cleanIsFlac(key) {
continue
}
cache, err := artifacts.S3AudioCachePath(cfg.Pipeline.Cache.Root, cfg.Pipeline.Storage.S3.Bucket, key)
if err != nil {
return actions, err
}
action, err := cleanScopedTarget(cfg.Pipeline.Cache.Root, cache, "clean.cache.session", false, dryRun)
actions = append(actions, action)
if err != nil {
return actions, err
}
}
return actions, nil
}

View File

@@ -0,0 +1,98 @@
package app
import (
"bytes"
"context"
"encoding/json"
"os"
"path/filepath"
"testing"
"gitea.maximumdirect.net/eric/narratio/internal/artifacts"
"gitea.maximumdirect.net/eric/narratio/internal/config"
"go.maximumdirect.net/commandkit"
configkit "go.maximumdirect.net/configkit"
)
func TestCleanCommandReportsCompletedActionsBeforeLaterFailure(t *testing.T) {
workspace := t.TempDir()
pipeline, campaign, session := writeValidConfigFiles(t, workspace)
work := artifacts.SessionWorkDirForCampaign(workspace, "sample-campaign", "2026-05-03")
mustWriteTestFile(t, filepath.Join(work, "manifest.json"), "{}")
spool := artifacts.SessionSpoolDir(filepath.Join(workspace, "spool"), "sample-campaign", "2026-05-03")
if err := os.MkdirAll(filepath.Dir(spool), 0755); err != nil {
t.Fatal(err)
}
outside := t.TempDir()
sentinel := filepath.Join(outside, "retained")
mustWriteTestFile(t, sentinel, "retained")
if err := os.Symlink(outside, spool); err != nil {
t.Fatal(err)
}
var out, diagnostic bytes.Buffer
outcome := Execute(context.Background(), []string{"session", "clean", "2026-05-03", "--config", pipeline, "--campaign-file", campaign, "--session-file", session, "--format", "json"}, commandkit.Streams{Out: &out, Err: &diagnostic})
if outcome.Status != 1 {
t.Fatalf("status=%d diagnostics=%s", outcome.Status, diagnostic.String())
}
var report cleanCommandReport
if err := json.Unmarshal(out.Bytes(), &report); err != nil {
t.Fatal(err)
}
if report.Complete || len(report.Actions) != 2 || report.Actions[0].Status != "deleted" || report.Actions[1].Status != "failed" || report.Error == "" {
t.Fatalf("partial report=%#v", report)
}
cleanAssertMissing(t, work)
cleanAssertExists(t, sentinel)
}
func TestCleanCommandChecksAllSelectionBeforeBootstrap(t *testing.T) {
app, err := newApplication(commandDependencies{
loadSecretsDir: func(string) (*configkit.SecretsReport, error) {
t.Fatal("invalid cleanup bootstrapped secrets")
return nil, nil
},
loadPipelineConfig: func(string, config.PipelineLoadOptions) (*config.PipelineConfig, error) {
t.Fatal("invalid cleanup loaded configuration")
return nil, nil
},
}, executePlan)
if err != nil {
t.Fatal(err)
}
for _, args := range [][]string{
{"session", "clean"},
{"session", "clean", "session", "--all"},
{"session", "clean", "--all", "--campaign", "campaign"},
{"session", "clean", "--all", "--campaign-file", "campaign.yml"},
{"session", "clean", "--all", "--session-file", "session.yml"},
{"session", "clean", "--all", "--party-file", "party.yml"},
{"session", "clean", "--all", "--previous-session-id", "previous"},
{"clean"},
} {
var out, diagnostic bytes.Buffer
outcome := app.Execute(context.Background(), args, commandkit.Streams{Out: &out, Err: &diagnostic})
if outcome.Status != 2 {
t.Fatalf("%v status=%d diagnostics=%s", args, outcome.Status, diagnostic.String())
}
}
}
func TestCleanAllCommandNeedsOnlyPipelineConfiguration(t *testing.T) {
root := t.TempDir()
pipeline := filepath.Join(root, "pipeline.yml")
mustWriteTestFile(t, pipeline, "workspace: {root: ./workspace}\nspool: {root: ./spool}\nwhisperx: {transcribe_url: https://transcription.example.test/transcribe}\n")
var out, diagnostic bytes.Buffer
outcome := Execute(context.Background(), []string{"session", "clean", "--all", "--dry-run", "--config", pipeline, "--format", "json"}, commandkit.Streams{Out: &out, Err: &diagnostic})
if outcome.Status != 0 {
t.Fatalf("status=%d diagnostics=%s", outcome.Status, diagnostic.String())
}
var report cleanCommandReport
if err := json.Unmarshal(out.Bytes(), &report); err != nil {
t.Fatal(err)
}
if !report.All || !report.DryRun || report.Complete || report.Campaign != "" || report.Cache != "preserved" {
t.Fatalf("report=%#v", report)
}
cleanAssertMissing(t, filepath.Join(root, "workspace"))
cleanAssertMissing(t, filepath.Join(root, "spool"))
}

View File

@@ -26,14 +26,14 @@ func TestExecuteCleanSessionDeletesWorkAndSpoolButPreservesCache(t *testing.T) {
var stdout bytes.Buffer var stdout bytes.Buffer
var stderr bytes.Buffer var stderr bytes.Buffer
code := Execute([]string{"clean", "2026-05-03", "--config", pipelinePath, "--campaign-file", campaignPath, "--session", sessionPath}, &stdout, &stderr) code := executeForTest([]string{"session", "clean", "2026-05-03", "--config", pipelinePath, "--campaign-file", campaignPath, "--session-file", sessionPath}, &stdout, &stderr)
if code != 0 { if code != 0 {
t.Fatalf("exit code = %d, want 0; stderr=%q", code, stderr.String()) t.Fatalf("exit code = %d, want 0; stderr=%q", code, stderr.String())
} }
cleanAssertMissing(t, workDir) cleanAssertMissing(t, workDir)
cleanAssertMissing(t, spoolDir) cleanAssertMissing(t, spoolDir)
cleanAssertExists(t, cachePath) cleanAssertExists(t, cachePath)
if !strings.Contains(stdout.String(), "Cache: preserved") { if !strings.Contains(stdout.String(), "cache: preserved") {
t.Fatalf("stdout = %q, want cache preserved", stdout.String()) t.Fatalf("stdout = %q, want cache preserved", stdout.String())
} }
} }
@@ -48,13 +48,13 @@ func TestExecuteCleanSessionDryRunDeletesNothing(t *testing.T) {
var stdout bytes.Buffer var stdout bytes.Buffer
var stderr bytes.Buffer var stderr bytes.Buffer
code := Execute([]string{"clean", "2026-05-03", "--config", pipelinePath, "--campaign-file", campaignPath, "--session", sessionPath, "--dry-run"}, &stdout, &stderr) code := executeForTest([]string{"session", "clean", "2026-05-03", "--config", pipelinePath, "--campaign-file", campaignPath, "--session-file", sessionPath, "--dry-run"}, &stdout, &stderr)
if code != 0 { if code != 0 {
t.Fatalf("exit code = %d, want 0; stderr=%q", code, stderr.String()) t.Fatalf("exit code = %d, want 0; stderr=%q", code, stderr.String())
} }
cleanAssertExists(t, workDir) cleanAssertExists(t, workDir)
cleanAssertExists(t, spoolDir) cleanAssertExists(t, spoolDir)
if !strings.Contains(stdout.String(), "Would delete:") { if !strings.Contains(stdout.String(), "status: would_delete") {
t.Fatalf("stdout = %q, want dry-run delete plan", stdout.String()) t.Fatalf("stdout = %q, want dry-run delete plan", stdout.String())
} }
} }
@@ -65,11 +65,11 @@ func TestExecuteCleanMissingSessionPathsSucceeds(t *testing.T) {
var stdout bytes.Buffer var stdout bytes.Buffer
var stderr bytes.Buffer var stderr bytes.Buffer
code := Execute([]string{"clean", "2026-05-03", "--config", pipelinePath, "--campaign-file", campaignPath, "--session", sessionPath}, &stdout, &stderr) code := executeForTest([]string{"session", "clean", "2026-05-03", "--config", pipelinePath, "--campaign-file", campaignPath, "--session-file", sessionPath}, &stdout, &stderr)
if code != 0 { if code != 0 {
t.Fatalf("exit code = %d, want 0; stderr=%q", code, stderr.String()) t.Fatalf("exit code = %d, want 0; stderr=%q", code, stderr.String())
} }
if !strings.Contains(stdout.String(), "Missing:") { if !strings.Contains(stdout.String(), "status: missing") {
t.Fatalf("stdout = %q, want missing path output", stdout.String()) t.Fatalf("stdout = %q, want missing path output", stdout.String())
} }
} }
@@ -105,7 +105,7 @@ inputs:
var stdout bytes.Buffer var stdout bytes.Buffer
var stderr bytes.Buffer var stderr bytes.Buffer
code := executeWithDependencies([]string{"clean", "2026-05-03", "--config", pipelinePath, "--campaign-file", campaignPath, "--session", sessionPath, "--clear-cache"}, &stdout, &stderr, deps, executePlan) code := executeWithDependencies([]string{"session", "clean", "2026-05-03", "--config", pipelinePath, "--campaign-file", campaignPath, "--session-file", sessionPath, "--clear-cache"}, &stdout, &stderr, deps, executePlan)
if code != 0 { if code != 0 {
t.Fatalf("exit code = %d, want 0; stderr=%q", code, stderr.String()) t.Fatalf("exit code = %d, want 0; stderr=%q", code, stderr.String())
} }
@@ -122,11 +122,11 @@ func TestExecuteCleanLocalAudioClearCacheIsNoop(t *testing.T) {
var stdout bytes.Buffer var stdout bytes.Buffer
var stderr bytes.Buffer var stderr bytes.Buffer
code := Execute([]string{"clean", "2026-05-03", "--config", pipelinePath, "--campaign-file", campaignPath, "--session", sessionPath, "--clear-cache"}, &stdout, &stderr) code := executeForTest([]string{"session", "clean", "2026-05-03", "--config", pipelinePath, "--campaign-file", campaignPath, "--session-file", sessionPath, "--clear-cache"}, &stdout, &stderr)
if code != 0 { if code != 0 {
t.Fatalf("exit code = %d, want 0; stderr=%q", code, stderr.String()) t.Fatalf("exit code = %d, want 0; stderr=%q", code, stderr.String())
} }
if !strings.Contains(stdout.String(), "Cache: skipped (session does not use audio_s3)") { if !strings.Contains(stdout.String(), "cache: not_applicable") {
t.Fatalf("stdout = %q, want local audio cache no-op", stdout.String()) t.Fatalf("stdout = %q, want local audio cache no-op", stdout.String())
} }
} }
@@ -143,7 +143,7 @@ func TestExecuteCleanAllDeletesWorkAndSpoolContentsButPreservesCache(t *testing.
var stdout bytes.Buffer var stdout bytes.Buffer
var stderr bytes.Buffer var stderr bytes.Buffer
code := Execute([]string{"clean", "--config", pipelinePath, "--all"}, &stdout, &stderr) code := executeForTest([]string{"session", "clean", "--config", pipelinePath, "--all"}, &stdout, &stderr)
if code != 0 { if code != 0 {
t.Fatalf("exit code = %d, want 0; stderr=%q", code, stderr.String()) t.Fatalf("exit code = %d, want 0; stderr=%q", code, stderr.String())
} }
@@ -170,7 +170,7 @@ func TestExecuteCleanAllClearCacheRemovesS3AudioNamespaceOnly(t *testing.T) {
var stdout bytes.Buffer var stdout bytes.Buffer
var stderr bytes.Buffer var stderr bytes.Buffer
code := Execute([]string{"clean", "--config", pipelinePath, "--all", "--clear-cache"}, &stdout, &stderr) code := executeForTest([]string{"session", "clean", "--config", pipelinePath, "--all", "--clear-cache"}, &stdout, &stderr)
if code != 0 { if code != 0 {
t.Fatalf("exit code = %d, want 0; stderr=%q", code, stderr.String()) t.Fatalf("exit code = %d, want 0; stderr=%q", code, stderr.String())
} }
@@ -184,7 +184,7 @@ func TestExecuteCleanAllRejectsSessionScopedFlags(t *testing.T) {
var stdout bytes.Buffer var stdout bytes.Buffer
var stderr bytes.Buffer var stderr bytes.Buffer
code := Execute([]string{"clean", "2026-05-03", "--config", pipelinePath, "--campaign-file", campaignPath, "--all"}, &stdout, &stderr) code := executeForTest([]string{"session", "clean", "2026-05-03", "--config", pipelinePath, "--campaign-file", campaignPath, "--all"}, &stdout, &stderr)
if code == 0 { if code == 0 {
t.Fatal("exit code = 0, want non-zero") t.Fatal("exit code = 0, want non-zero")
} }
@@ -196,11 +196,11 @@ func TestExecuteCleanAllRejectsSessionScopedFlags(t *testing.T) {
func TestCleanRequiresSessionID(t *testing.T) { func TestCleanRequiresSessionID(t *testing.T) {
var stdout bytes.Buffer var stdout bytes.Buffer
var stderr bytes.Buffer var stderr bytes.Buffer
code := Execute([]string{"clean"}, &stdout, &stderr) code := executeForTest([]string{"session", "clean"}, &stdout, &stderr)
if code == 0 { if code == 0 {
t.Fatal("exit code = 0, want non-zero") t.Fatal("exit code = 0, want non-zero")
} }
if !strings.Contains(stderr.String(), "session_id is required unless --all is set") { if !strings.Contains(stderr.String(), "session identity is required unless --all is set") {
t.Fatalf("stderr = %q, want missing session-id", stderr.String()) t.Fatalf("stderr = %q, want missing session-id", stderr.String())
} }
} }
@@ -208,22 +208,22 @@ func TestCleanRequiresSessionID(t *testing.T) {
func TestCleanRejectsUnsafeTargets(t *testing.T) { func TestCleanRejectsUnsafeTargets(t *testing.T) {
root := t.TempDir() root := t.TempDir()
outside := t.TempDir() outside := t.TempDir()
if err := reportCleanScopedDir(&bytes.Buffer{}, root, filepath.Join(outside, "target"), "test.outside", false); err == nil { if _, err := cleanScopedTarget(root, filepath.Join(outside, "target"), "test.outside", true, false); err == nil {
t.Fatal("outside target error = nil, want error") t.Fatal("outside target error = nil, want error")
} }
if err := reportCleanScopedDir(&bytes.Buffer{}, root, root, "test.root", false); err == nil { if _, err := cleanScopedTarget(root, root, "test.root", true, false); err == nil {
t.Fatal("root target error = nil, want error") t.Fatal("root target error = nil, want error")
} }
filePath := filepath.Join(root, "file.txt") filePath := filepath.Join(root, "file.txt")
mustWriteTestFile(t, filePath, "file") mustWriteTestFile(t, filePath, "file")
if err := reportCleanScopedDir(&bytes.Buffer{}, root, filePath, "test.file", false); err == nil { if _, err := cleanScopedTarget(root, filePath, "test.file", true, false); err == nil {
t.Fatal("file target error = nil, want error") t.Fatal("file target error = nil, want error")
} }
symlinkPath := filepath.Join(root, "link") symlinkPath := filepath.Join(root, "link")
if err := os.Symlink(filepath.Join(root, "missing"), symlinkPath); err != nil { if err := os.Symlink(filepath.Join(root, "missing"), symlinkPath); err != nil {
t.Fatalf("Symlink() error = %v", err) t.Fatalf("Symlink() error = %v", err)
} }
if err := reportCleanScopedDir(&bytes.Buffer{}, root, symlinkPath, "test.symlink", false); err == nil { if _, err := cleanScopedTarget(root, symlinkPath, "test.symlink", true, false); err == nil {
t.Fatal("symlink target error = nil, want error") t.Fatal("symlink target error = nil, want error")
} }
} }
@@ -231,11 +231,11 @@ func TestCleanRejectsUnsafeTargets(t *testing.T) {
func TestClearIsNotCommandAlias(t *testing.T) { func TestClearIsNotCommandAlias(t *testing.T) {
var stdout bytes.Buffer var stdout bytes.Buffer
var stderr bytes.Buffer var stderr bytes.Buffer
code := Execute([]string{"clear"}, &stdout, &stderr) code := executeForTest([]string{"clear"}, &stdout, &stderr)
if code == 0 { if code == 0 {
t.Fatal("exit code = 0, want non-zero") t.Fatal("exit code = 0, want non-zero")
} }
if !strings.Contains(stderr.String(), `unknown command: "clear"`) { if code != 2 {
t.Fatalf("stderr = %q, want unknown clear command", stderr.String()) t.Fatalf("stderr = %q, want unknown clear command", stderr.String())
} }
} }

View File

@@ -164,7 +164,7 @@ func TestCleanupFailurePreservesPublishAndRetriesWithoutRepublishing(t *testing.
} }
} }
func TestRunStageCleanupUsesPublishEvidenceAndFailsClosedWithoutIt(t *testing.T) { func TestRunSingleStageCleanupUsesPublishEvidenceAndFailsClosedWithoutIt(t *testing.T) {
workspaceRoot := t.TempDir() workspaceRoot := t.TempDir()
pipelinePath, campaignPath, sessionPath := writeValidConfigFiles(t, workspaceRoot) pipelinePath, campaignPath, sessionPath := writeValidConfigFiles(t, workspaceRoot)
enableCleanupForCommandTest(t, pipelinePath) enableCleanupForCommandTest(t, pipelinePath)
@@ -192,14 +192,15 @@ func TestRunStageCleanupUsesPublishEvidenceAndFailsClosedWithoutIt(t *testing.T)
} }
} }
seedInvocationPrerequisites(t, workspaceRoot, "cleanup")
var output bytes.Buffer var output bytes.Buffer
if err := RunStage(context.Background(), []string{ if err := invokeNativeCommand(context.Background(), []string{"run", "--stage", "cleanup", cfg.Session.SessionID, "--config", pipelinePath,
"cleanup", cfg.Session.SessionID, "--config", pipelinePath, "--campaign-file", campaignPath, "--session-file", sessionPath,
"--campaign-file", campaignPath, "--session", sessionPath,
}, &output); err != nil { }, &output); err != nil {
t.Fatalf("RunStage(cleanup): %v", err) t.Fatalf("single-stage run (cleanup): %v", err)
} }
if !strings.Contains(output.String(), "stage=cleanup executed=1 skipped=0") { if !runCountsMatch(t, output.Bytes(), 1, 0, "cleanup") {
t.Fatalf("output = %q, want direct cleanup execution", output.String()) t.Fatalf("output = %q, want direct cleanup execution", output.String())
} }
for _, target := range []string{workspaceTarget, spoolTarget} { for _, target := range []string{workspaceTarget, spoolTarget} {
@@ -218,12 +219,12 @@ func TestRunStageCleanupUsesPublishEvidenceAndFailsClosedWithoutIt(t *testing.T)
missingRoot := t.TempDir() missingRoot := t.TempDir()
missingPipeline, missingCampaign, missingSession := writeValidConfigFiles(t, missingRoot) missingPipeline, missingCampaign, missingSession := writeValidConfigFiles(t, missingRoot)
enableCleanupForCommandTest(t, missingPipeline) enableCleanupForCommandTest(t, missingPipeline)
err = RunStage(context.Background(), []string{ seedInvocationPrerequisites(t, missingRoot, "cleanup")
"cleanup", "2026-05-03", "--config", missingPipeline, err = invokeNativeCommand(context.Background(), []string{"run", "--stage", "cleanup", "2026-05-03", "--config", missingPipeline,
"--campaign-file", missingCampaign, "--session", missingSession, "--campaign-file", missingCampaign, "--session-file", missingSession,
}, &bytes.Buffer{}) }, &bytes.Buffer{})
if err == nil || !strings.Contains(err.Error(), "cleanup requires a recorded publish stage") { if err == nil || !strings.Contains(err.Error(), "publish") {
t.Fatalf("RunStage(cleanup) without evidence error = %v", err) t.Fatalf("single-stage run (cleanup) without evidence error = %v", err)
} }
} }

View File

@@ -4,16 +4,17 @@ import (
"context" "context"
"io" "io"
configkit "gitea.maximumdirect.net/eric/ConfigKit"
"gitea.maximumdirect.net/eric/narratio/internal/adapters/storage" "gitea.maximumdirect.net/eric/narratio/internal/adapters/storage"
"gitea.maximumdirect.net/eric/narratio/internal/config" "gitea.maximumdirect.net/eric/narratio/internal/config"
"gitea.maximumdirect.net/eric/narratio/internal/logging"
configkit "go.maximumdirect.net/configkit"
) )
type commandDependencies struct { type commandDependencies struct {
reporter logging.Reporter
diagnostics io.Writer diagnostics io.Writer
resolvePipelineConfigPath func(string) (string, error) pipelineSearch *configkit.Search
loadPipelineConfig func(string, config.PipelineLoadOptions) (*config.PipelineConfig, error) loadPipelineConfig func(string, config.PipelineLoadOptions) (*config.PipelineConfig, error)
downloadObjectToTemp func(context.Context, storage.ObjectStore, string, string) (string, error)
loadSecretsDir func(string) (*configkit.SecretsReport, error) loadSecretsDir func(string) (*configkit.SecretsReport, error)
secretsBootstrap *secretsBootstrap secretsBootstrap *secretsBootstrap
newObjectStore func(context.Context, *config.Config) (storage.ObjectStore, error) newObjectStore func(context.Context, *config.Config) (storage.ObjectStore, error)
@@ -26,17 +27,11 @@ func normalizeCommandDependencies(deps commandDependencies) commandDependencies
if deps.diagnostics == nil { if deps.diagnostics == nil {
deps.diagnostics = io.Discard deps.diagnostics = io.Discard
} }
if deps.resolvePipelineConfigPath == nil {
deps.resolvePipelineConfigPath = resolvePipelineConfigPath
}
if deps.loadPipelineConfig == nil { if deps.loadPipelineConfig == nil {
deps.loadPipelineConfig = config.LoadPipelineWithOptions deps.loadPipelineConfig = config.LoadPipelineWithOptions
} }
if deps.downloadObjectToTemp == nil {
deps.downloadObjectToTemp = storage.DownloadObjectToTemp
}
if deps.loadSecretsDir == nil { if deps.loadSecretsDir == nil {
deps.loadSecretsDir = configkit.LoadSecretsDir deps.loadSecretsDir = configkit.LoadSecretsIntoEnvironment
} }
if deps.secretsBootstrap == nil { if deps.secretsBootstrap == nil {
deps.secretsBootstrap = &secretsBootstrap{} deps.secretsBootstrap = &secretsBootstrap{}

View File

@@ -0,0 +1,91 @@
package app
import (
"gitea.maximumdirect.net/eric/narratio/internal/config"
"go.maximumdirect.net/ckconfig"
"go.maximumdirect.net/commandkit"
"go.maximumdirect.net/configkit"
)
// inputError identifies an invalid Narratio request independently of native
// configuration diagnostics. Operational errors retain their own classification.
type inputError struct {
message string
cause error
}
func (e *inputError) Unwrap() error { return e.cause }
func (e *inputError) Error() string { return e.message }
func operationOutcome(err error) commandkit.Outcome {
if err == nil {
return commandkit.Success()
}
if classifyOperationError(err) == commandkit.OutcomeUsage {
return commandkit.Usage(err.Error()).WithCause(err)
}
return commandkit.Failure(err.Error()).WithCause(err)
}
func classifyOperationError(err error) commandkit.OutcomeKind {
switch err.(type) {
case *inputError, *config.ArtifactCatalogInputError:
return commandkit.OutcomeUsage
}
switch wrapped := err.(type) {
case interface{ Unwrap() []error }:
found := false
for _, child := range wrapped.Unwrap() {
if child == nil {
continue
}
found = true
if classifyOperationError(child) != commandkit.OutcomeUsage {
return commandkit.OutcomeOperational
}
}
if found {
return commandkit.OutcomeUsage
}
case interface{ Unwrap() error }:
if child := wrapped.Unwrap(); child != nil {
return classifyOperationError(child)
}
}
return ckconfig.ClassifyConfigurationError(err)
}
// reportOperationOutcome leaves native configuration evidence to ckconfig while
// retaining the operation's context and any joined cleanup or persistence causes.
func reportOperationOutcome(inv commandkit.Invocation, err error) commandkit.Outcome {
outcome := operationOutcome(err)
var details []commandkit.Detail
var visit func(error)
visit = func(e error) {
if e == nil {
return
}
if load, ok := e.(*configkit.LoadError); ok {
warnings, explanation := ckconfig.AdaptDiagnostics("Configuration:\n", load.Sources(), load.Diagnostics())
for _, warning := range warnings {
_ = inv.Reporter().Warn("", warning.Write)
}
details = append(details, explanation.Details...)
return
}
switch wrapped := e.(type) {
case interface{ Unwrap() []error }:
for _, child := range wrapped.Unwrap() {
visit(child)
}
case interface{ Unwrap() error }:
visit(wrapped.Unwrap())
}
}
visit(err)
if len(details) > 0 {
outcome = outcome.WithExplanation(err.Error(), details...)
}
return outcome
}

View File

@@ -0,0 +1,56 @@
package app
import (
"fmt"
"io"
"go.maximumdirect.net/commandkit"
)
// Native reporting retains its own delivery failures until invocation finalization.
// Console delivery failures must not interrupt domain work or checkpoint saves.
type nativeConsole struct{ reporter *commandkit.Reporter }
func (r nativeConsole) Info(message string, fields ...any) {
_ = r.reporter.Info(message, consoleFields(fields))
}
func (r nativeConsole) Warn(message string, fields ...any) {
_ = r.reporter.Warn(message, consoleFields(fields))
}
func (r nativeConsole) Debug(message string, fields ...any) {
_ = r.reporter.Debug(message, consoleFields(fields))
}
func (r nativeConsole) Progress(message string, fields ...any) {
_ = r.reporter.Progress(message, consoleFields(fields))
}
func consoleFields(fields []any) commandkit.Detail {
if len(fields) == 0 {
return nil
}
return func(w io.Writer) error {
for index := 0; index < len(fields); index += 2 {
value := any("")
if index+1 < len(fields) {
value = fields[index+1]
}
if _, err := fmt.Fprintf(w, "%v=%v\n", fields[index], value); err != nil {
return err
}
}
return nil
}
}
func withCommandReporting(deps commandDependencies, invocation commandkit.Invocation) commandDependencies {
deps.reporter = nativeConsole{reporter: invocation.Reporter()}
deps.diagnostics = bootstrapInfoWriter{reporter: invocation.Reporter()}
return deps
}
type bootstrapInfoWriter struct{ reporter *commandkit.Reporter }
func (w bootstrapInfoWriter) Write(body []byte) (int, error) {
_ = w.reporter.Info("", func(destination io.Writer) error { _, err := destination.Write(body); return err })
return len(body), nil
}

View File

@@ -0,0 +1,173 @@
package app
import (
"bytes"
"context"
"encoding/json"
"errors"
"os"
"path/filepath"
"strings"
"testing"
"gitea.maximumdirect.net/eric/narratio/internal/config"
"gitea.maximumdirect.net/eric/narratio/internal/manifest"
"gitea.maximumdirect.net/eric/narratio/internal/stage"
"go.maximumdirect.net/commandkit"
)
type diagnosticStage struct {
result *stage.StageResult
err error
}
func (s diagnosticStage) Name() string { return "prepare" }
func (s diagnosticStage) Run(_ context.Context, env *stage.Env, _ *manifest.Manifest) (*stage.StageResult, error) {
env.Info("stage context")
env.Warn("stage warning")
env.Debug("stage diagnostic")
return s.result, s.err
}
func TestNativeConsoleVisibilityDoesNotChangeExecution(t *testing.T) {
for _, test := range []struct {
name string
flags []string
info, debug, progress, quiet bool
}{
{name: "ordinary"},
{name: "verbose", flags: []string{"--verbose"}, info: true},
{name: "progress", flags: []string{"--progress"}, progress: true},
{name: "verbose progress", flags: []string{"--verbose", "--progress"}, info: true, progress: true},
{name: "quiet", flags: []string{"--debug", "--progress", "--quiet"}, quiet: true},
{name: "debug", flags: []string{"--debug"}, info: true, debug: true, progress: true},
{name: "debug without progress", flags: []string{"--debug", "--progress=false"}, info: true, debug: true},
{name: "cleared debug", flags: []string{"--debug", "--debug=false"}},
{name: "last progress value", flags: []string{"--progress=false", "--progress=true"}, progress: true},
{name: "last mode", flags: []string{"--quiet", "--verbose"}, info: true},
} {
t.Run(test.name, func(t *testing.T) {
pipeline, campaign, session := writeValidConfigFiles(t, t.TempDir())
logPath := filepath.Join(t.TempDir(), "captured.log")
const captured = "synthetic-private-downstream-output"
if err := os.WriteFile(logPath, []byte(captured), 0o600); err != nil {
t.Fatal(err)
}
var saved *RunSummary
app, err := newApplication(commandDependencies{}, func(ctx context.Context, cfg *config.Config, plan BoundedPlan, opts RunOptions) (*RunSummary, error) {
if len(plan.Names()) != 1 || plan.Names()[0] != "prepare" || opts.Force {
t.Fatal("console flags changed execution selection")
}
if cfg.Pipeline.Trim.Bounds.RenderDebug || (cfg.Pipeline.Scriptorium != nil && cfg.Pipeline.Scriptorium.RenderDebug) {
t.Fatal("console debug changed downstream capture")
}
var err error
saved, err = executeStages(ctx, cfg, []stage.Stage{diagnosticStage{result: &stage.StageResult{Logs: []string{logPath}}}}, opts)
return saved, err
})
if err != nil {
t.Fatal(err)
}
args := []string{"run", "2026-05-03", "--stage", "prepare", "--config", pipeline, "--campaign-file", campaign, "--session-file", session, "--format", "json"}
args = append(args, test.flags...)
var out, diagnostic bytes.Buffer
outcome := app.Execute(context.Background(), args, commandkit.Streams{Out: &out, Err: &diagnostic})
if outcome.Status != 0 || saved == nil || !saved.Complete {
t.Fatalf("outcome=%#v diagnostics=%s", outcome, diagnostic.String())
}
text := diagnostic.String()
for _, check := range []struct {
fragment string
want bool
}{{"stage context", test.info}, {"selected pipeline configuration", test.info}, {"stage warning", test.info}, {"stage diagnostic", test.debug}, {"manifest saved", test.debug}, {"starting stage", test.progress}, {"stage succeeded", test.progress}} {
if strings.Contains(text, check.fragment) != check.want {
t.Fatalf("visibility for %q = %v, want %v; diagnostics=%s", check.fragment, !check.want, check.want, text)
}
}
if strings.Contains(text+out.String(), captured) {
t.Fatal("replayed captured downstream output")
}
if test.quiet {
if out.Len() != 0 || diagnostic.Len() != 0 {
t.Fatal("quiet produced successful console output")
}
return
}
var report runReport
if err := json.Unmarshal(out.Bytes(), &report); err != nil {
t.Fatal(err)
}
if !report.Complete || len(report.StageResults) != 1 || report.StageResults[0].Outcome != "completed" {
t.Fatalf("report=%#v", report)
}
})
}
}
func TestNativeConsoleReportsSelfSkipReuseAndSingleFailure(t *testing.T) {
pipeline, campaign, session := writeValidConfigFiles(t, t.TempDir())
cause := errors.New("synthetic stage failure")
for _, test := range []struct {
name string
selected stage.Stage
flags []string
want string
status int
}{
{name: "self skip", selected: diagnosticStage{result: &stage.StageResult{Disposition: stage.StageDispositionSkipped, SkipReason: "disabled"}}, flags: []string{"--progress"}, want: "stage skipped"},
{name: "success", selected: diagnosticStage{}, flags: []string{"--progress"}, want: "stage succeeded"},
{name: "reuse", selected: failingStage{name: "prepare", err: errors.New("must reuse")}, flags: []string{"--progress"}, want: "reusing stage"},
{name: "failure", selected: diagnosticStage{err: cause}, flags: []string{"--force", "--progress"}, status: 1},
{name: "quiet failure", selected: diagnosticStage{err: cause}, flags: []string{"--force", "--quiet"}, status: 1},
} {
t.Run(test.name, func(t *testing.T) {
app, err := newApplication(commandDependencies{}, func(ctx context.Context, cfg *config.Config, _ BoundedPlan, opts RunOptions) (*RunSummary, error) {
return executeStages(ctx, cfg, []stage.Stage{test.selected}, opts)
})
if err != nil {
t.Fatal(err)
}
args := []string{"run", "2026-05-03", "--stage", "prepare", "--config", pipeline, "--campaign-file", campaign, "--session-file", session, "--format", "json"}
var out, diagnostic bytes.Buffer
outcome := app.Execute(context.Background(), append(args, test.flags...), commandkit.Streams{Out: &out, Err: &diagnostic})
if outcome.Status != test.status {
t.Fatalf("outcome=%#v diagnostics=%s", outcome, diagnostic.String())
}
if test.status == 1 {
if strings.Count(diagnostic.String(), cause.Error()) != 1 {
t.Fatalf("failure presented repeatedly: %s", diagnostic.String())
}
return
}
if !strings.Contains(diagnostic.String(), test.want) {
t.Fatalf("missing %q: %s", test.want, diagnostic.String())
}
})
}
}
func TestNativeConsoleDeliveryFailureDoesNotInterruptCheckpointing(t *testing.T) {
pipeline, campaign, session := writeValidConfigFiles(t, t.TempDir())
writeErr := errors.New("diagnostic destination unavailable")
var saved *RunSummary
app, err := newApplication(commandDependencies{}, func(ctx context.Context, cfg *config.Config, _ BoundedPlan, opts RunOptions) (*RunSummary, error) {
var err error
saved, err = executeStages(ctx, cfg, []stage.Stage{diagnosticStage{}}, opts)
return saved, err
})
if err != nil {
t.Fatal(err)
}
var out bytes.Buffer
outcome := app.Execute(context.Background(), []string{"run", "2026-05-03", "--stage", "prepare", "--config", pipeline, "--campaign-file", campaign, "--session-file", session, "--progress", "--format", "json"}, commandkit.Streams{Out: &out, Err: runReportWriteFunc(func([]byte) (int, error) { return 0, writeErr })})
if outcome.Status != 1 || !errors.Is(outcome.Presentation.Diagnostics.WriteError, writeErr) || saved == nil || !saved.Complete {
t.Fatalf("outcome=%#v summary=%#v", outcome, saved)
}
durable, err := (&manifest.LocalStore{}).Load(context.Background(), saved.ManifestPath)
if err != nil {
t.Fatal(err)
}
if durable.Stages["prepare"].Status != manifest.StatusSucceeded {
t.Fatal("diagnostic delivery failure interrupted domain work")
}
}

View File

@@ -0,0 +1,44 @@
package app
import "go.maximumdirect.net/commandkit"
// configurationSelection distinguishes source selection from identity assertions
// and retains explicit empty selections until the operation checks its inputs.
type configurationSelection struct {
Config commandkit.Supplied[string]
Overlay commandkit.Supplied[string]
Campaign commandkit.Supplied[string]
CampaignFile commandkit.Supplied[string]
Session commandkit.Supplied[string]
SessionFile commandkit.Supplied[string]
PartyFile commandkit.Supplied[string]
SecretsDir commandkit.Supplied[string]
}
type configurationFlags[I any] struct {
Config, Overlay, Campaign, CampaignFile commandkit.Flag[I]
Session, SessionFile, PartyFile, SecretsDir commandkit.Flag[I]
}
func newConfigurationFlags[I any](selection func(*I) *configurationSelection) configurationFlags[I] {
return configurationFlags[I]{
Config: commandkit.ValueFlag(commandkit.FlagMeta{Name: "config", Completion: commandkit.CompleteFiles(), Usage: "Pipeline configuration file."}, nil, stringValue,
func(in *I, v commandkit.Supplied[string]) { selection(in).Config = v }),
Overlay: commandkit.ValueFlag(commandkit.FlagMeta{Name: "overlay", Usage: "Pipeline overlay."}, nil, stringValue,
func(in *I, v commandkit.Supplied[string]) { selection(in).Overlay = v }),
Campaign: commandkit.ValueFlag(commandkit.FlagMeta{Name: "campaign", Usage: "Assert the campaign identity."}, nil, stringValue,
func(in *I, v commandkit.Supplied[string]) { selection(in).Campaign = v }),
CampaignFile: commandkit.ValueFlag(commandkit.FlagMeta{Name: "campaign-file", Completion: commandkit.CompleteFiles(), Usage: "Campaign configuration file."}, nil, stringValue,
func(in *I, v commandkit.Supplied[string]) { selection(in).CampaignFile = v }),
Session: commandkit.ValueFlag(commandkit.FlagMeta{Name: "session", Usage: "Assert the session identity for configuration inspection."}, nil, stringValue,
func(in *I, v commandkit.Supplied[string]) { selection(in).Session = v }),
SessionFile: commandkit.ValueFlag(commandkit.FlagMeta{Name: "session-file", Completion: commandkit.CompleteFiles(), Usage: "Session configuration file."}, nil, stringValue,
func(in *I, v commandkit.Supplied[string]) { selection(in).SessionFile = v }),
PartyFile: commandkit.ValueFlag(commandkit.FlagMeta{Name: "party-file", Completion: commandkit.CompleteFiles(), Usage: "Party file replacing the campaign default."}, nil, stringValue,
func(in *I, v commandkit.Supplied[string]) { selection(in).PartyFile = v }),
SecretsDir: commandkit.ValueFlag(commandkit.FlagMeta{Name: "secrets-dir", Completion: commandkit.CompleteDirectories(), Usage: "Credential-bootstrap directory."}, nil, stringValue,
func(in *I, v commandkit.Supplied[string]) { selection(in).SecretsDir = v }),
}
}
func stringValue(value string) (string, error) { return value, nil }

View File

@@ -0,0 +1,30 @@
package app
import (
"context"
"io"
"gitea.maximumdirect.net/eric/narratio/internal/adapters/storage"
"gitea.maximumdirect.net/eric/narratio/internal/config"
"go.maximumdirect.net/commandkit"
)
func executeForTest(args []string, stdout, stderr io.Writer) int {
return executeWithDependencies(args, stdout, stderr, commandDependencies{}, executePlan)
}
func executeWithPipelineExecutor(args []string, stdout, stderr io.Writer, executor pipelineExecutor) int {
return executeWithDependencies(args, stdout, stderr, commandDependencies{}, executor)
}
func executeWithDependencies(args []string, stdout, stderr io.Writer, deps commandDependencies, executor pipelineExecutor) int {
if deps.newObjectStore == nil {
deps.newObjectStore = func(context.Context, *config.Config) (storage.ObjectStore, error) { return &storage.FakeBackend{}, nil }
}
application, err := newApplication(deps, executor)
if err != nil {
panic(err)
}
return application.Execute(context.Background(), args, commandkit.Streams{Out: stdout, Err: stderr}).Status
}

View File

@@ -2,70 +2,50 @@ package app
import ( import (
"context" "context"
"fmt"
"io" "gitea.maximumdirect.net/eric/narratio/internal/buildinfo"
"strings" "go.maximumdirect.net/commandkit"
) )
var supportedCommands = []string{"version", "run", "regenerate-artifacts", "run-stage", "analyze", "publish", "clean", "session", "config"} // NewApplication constructs the native command boundary without acquiring configuration
// or initializing external services.
// Execute dispatches CLI commands and returns a process exit code. func NewApplication() (*commandkit.App, error) {
func Execute(args []string, stdout, stderr io.Writer) int { return newApplication(commandDependencies{}, executePlan)
return executeWithDependencies(args, stdout, stderr, commandDependencies{}, executePlan)
} }
func executeWithPipelineExecutor(args []string, stdout, stderr io.Writer, executor pipelineExecutor) int { func newApplication(deps commandDependencies, executor pipelineExecutor) (*commandkit.App, error) {
return executeWithDependencies(args, stdout, stderr, commandDependencies{}, executor) return commandkit.New(
commandkit.Identity{Name: "narratio", Version: buildinfo.Version},
commandkit.Completion("narratio"),
configurationCommand(deps),
executionCommand("run", "Execute a session pipeline.", false, deps, executor),
commandkit.Group("artifacts", "Inspect and regenerate configured artifacts.",
artifactCatalogCommand(deps),
executionCommand("regenerate", "Rebuild extraction and analysis artifacts.", true, deps, executor),
),
commandkit.Group("session", "Manage and inspect sessions.",
sessionPlanCommand(deps),
restoreCommand(deps),
cleanCommand(deps),
sessionInitializationCommand(deps),
sessionValidationCommand(deps),
sessionStateCommand("status", true, deps),
sessionStateCommand("artifacts", false, deps),
commandkit.Group("locks", "Manage remote publication locks.",
lockCommand("list", deps),
lockCommand("add", deps),
lockCommand("remove", deps),
),
),
)
} }
func executeWithDependencies(args []string, stdout, stderr io.Writer, deps commandDependencies, executor pipelineExecutor) int { // Execute runs an invocation with caller-owned context and streams and returns
if deps.diagnostics == nil { // its finalized native outcome. The process boundary owns exit handling.
deps.diagnostics = stderr func Execute(ctx context.Context, args []string, streams commandkit.Streams) commandkit.Outcome {
} application, err := NewApplication()
deps = normalizeCommandDependencies(deps)
if len(args) == 0 {
printUsage(stderr)
return 1
}
ctx := context.Background()
cmd := args[0]
cmdArgs := args[1:]
var err error
switch cmd {
case "version":
err = Version(cmdArgs, stdout)
case "run":
err = runWithDependencies(ctx, cmdArgs, stdout, executor, deps)
case "regenerate-artifacts":
err = regenerateArtifactsWithDependencies(ctx, cmdArgs, stdout, executor, deps)
case "run-stage":
err = runStageWithDependencies(ctx, cmdArgs, stdout, executor, deps)
case "analyze":
err = analyzeWithDependencies(ctx, cmdArgs, stdout, executor, deps)
case "publish":
err = publishWithDependencies(ctx, cmdArgs, stdout, executor, deps)
case "session":
err = sessionWithDependencies(ctx, cmdArgs, stdout, deps)
case "clean":
err = cleanWithDependencies(ctx, cmdArgs, stdout, deps)
case "config":
err = configWithDependencies(ctx, cmdArgs, stdout, deps)
default:
fmt.Fprintf(stderr, "unknown command: %q\n\n", cmd)
printUsage(stderr)
return 1
}
if err != nil { if err != nil {
fmt.Fprintf(stderr, "%v\n", err) return operationOutcome(err)
return 1
} }
return application.Execute(ctx, args, streams)
return 0
}
func printUsage(w io.Writer) {
fmt.Fprintf(w, "Usage: narratio <%s>\n", strings.Join(supportedCommands, "|"))
} }

View File

@@ -0,0 +1,235 @@
package app
import (
"bytes"
"context"
"errors"
"fmt"
"io"
"os"
"path/filepath"
"strings"
"testing"
"gitea.maximumdirect.net/eric/narratio/internal/adapters/storage"
"gitea.maximumdirect.net/eric/narratio/internal/config"
"go.maximumdirect.net/commandkit"
"go.maximumdirect.net/configkit"
)
func TestNativeDiscoveryDoesNotAcquireConfiguration(t *testing.T) {
root := t.TempDir()
t.Chdir(root)
if err := os.WriteFile(filepath.Join(root, "pipeline.yml"), []byte("invalid: ["), 0600); err != nil {
t.Fatal(err)
}
application, err := newApplication(commandDependencies{
loadPipelineConfig: func(string, config.PipelineLoadOptions) (*config.PipelineConfig, error) {
t.Fatal("discovery loaded pipeline configuration")
return nil, nil
},
newObjectStore: func(context.Context, *config.Config) (storage.ObjectStore, error) {
t.Fatal("discovery initialized object storage")
return nil, nil
},
loadSecretsDir: func(string) (*configkit.SecretsReport, error) {
t.Fatal("discovery bootstrapped credentials")
return nil, nil
},
}, nil)
if err != nil {
t.Fatal(err)
}
for _, args := range [][]string{nil, {"help"}, {"--help"}, {"session"}, {"artifacts"}, {"version"}, {"help", "run"}, {"help", "config", "show"}, {"session", "locks"}, {"config", "scopes"}, {"completion"}, {"completion", "bash"}, {"completion", "zsh"}, {"completion", "fish"}} {
var out, diagnostics bytes.Buffer
outcome := application.Execute(context.Background(), args, commandkit.Streams{Out: &out, Err: &diagnostics})
if outcome.Status != 0 || out.Len() == 0 || diagnostics.Len() != 0 {
t.Fatalf("%v: outcome=%+v stdout=%q stderr=%q", args, outcome, out.String(), diagnostics.String())
}
}
for _, query := range []struct {
args []string
fragment string
}{
{[]string{"__complete", "run", "--config", "missing.yml", "--secrets-dir", "missing-secrets", "--stage", "tr"}, "transcribe\n"},
{[]string{"__complete", "session", "plan", "--from", "an"}, "analyze\n"},
{[]string{"__complete", "run", "--through", "pub"}, "publish\n"},
{[]string{"__complete", "config", "show", "--scope", ""}, "party\n"},
{[]string{"__complete", "run", "--config", ""}, ":0\n"},
{[]string{"__complete", "session", "status", "--session-file", ""}, ":0\n"},
{[]string{"__complete", "session", "plan", "--party-file", ""}, ":0\n"},
{[]string{"__complete", "config", "diff", "--scope", "party", "--against-party-file", ""}, ":0\n"},
{[]string{"__complete", "session", "init", "--output", ""}, ":0\n"},
{[]string{"__complete", "session", "init", "--audio-dir", ""}, ":16\n"},
{[]string{"__complete", "run", "--secrets-dir", ""}, ":16\n"},
} {
var out, diagnostics bytes.Buffer
outcome := application.Execute(context.Background(), query.args, commandkit.Streams{Out: &out, Err: &diagnostics})
if outcome.Status != 0 || diagnostics.Len() != 0 || !strings.Contains(out.String(), query.fragment) {
t.Fatalf("query=%v outcome=%#v reply=%q diagnostic=%s", query.args, outcome, out.String(), diagnostics.String())
}
}
if outcome := application.Execute(context.Background(), []string{"unknown"}, commandkit.Streams{}); outcome.Status != 2 {
t.Fatalf("invalid invocation: %+v", outcome)
}
}
func TestNativeSelectionRetainsPresenceAndCallerContext(t *testing.T) {
flags := newConfigurationFlags(func(in *configurationSelection) *configurationSelection { return in })
type contextKey struct{}
ctx := context.WithValue(context.Background(), contextKey{}, "caller")
application, err := commandkit.New(commandkit.Identity{Name: "narratio"}, commandkit.NewCommand(commandkit.CommandSpec[configurationSelection]{
Name: "inspect",
Flags: []commandkit.Flag[configurationSelection]{flags.Config, flags.Overlay, flags.Campaign, flags.CampaignFile, flags.Session, flags.SessionFile, flags.PartyFile, flags.SecretsDir},
CheckInput: func(in configurationSelection) error {
if !in.Config.Set || in.Config.Value != "" || !in.Campaign.Set || !in.CampaignFile.Set || in.PartyFile.Set {
t.Fatalf("selection lost presence or complementary selectors: %+v", in)
}
return nil
},
Run: func(inv commandkit.Invocation, in configurationSelection) commandkit.Outcome {
if inv.Context.Value(contextKey{}) != "caller" {
t.Fatal("caller context lost")
}
return commandkit.Success()
},
}))
if err != nil {
t.Fatal(err)
}
outcome := application.Execute(ctx, []string{"inspect", "--config=", "--campaign", "campaign", "--campaign-file", "campaign.yml"}, commandkit.Streams{})
if outcome.Status != 0 {
t.Fatalf("selection outcome: %+v", outcome)
}
}
func TestOperationOutcomePreservesCausesAndOperationalPrecedence(t *testing.T) {
path := filepath.Join(t.TempDir(), "pipeline.yml")
if err := os.WriteFile(path, []byte("invalid: ["), 0600); err != nil {
t.Fatal(err)
}
_, invalid := config.LoadPipeline(path)
if invalid == nil {
t.Fatal("expected invalid configuration")
}
input := &inputError{message: "invalid identity selection"}
operational := errors.New("storage unavailable")
_, catalogInput := config.DeriveArtifactCatalog(&config.PipelineConfig{Scriptorium: &config.ScriptoriumConfig{Artifacts: map[string]config.ScriptoriumArtifactConfig{
"result": {OutputPath: "artifacts/result.md", DependsOn: []string{"missing"}},
}}}, config.ResolvedParty{})
var catalogError *config.ArtifactCatalogInputError
if !errors.As(catalogInput, &catalogError) || errors.Unwrap(catalogError) == nil {
t.Fatalf("catalog validation lost its typed input cause: %v", catalogInput)
}
for _, tc := range []struct {
err error
status int
}{
{nil, 0}, {input, 2}, {invalid, 2},
{catalogInput, 2},
{errors.Join(catalogInput, operational), 1},
{errors.Join(catalogInput, context.Canceled), 1},
{fmt.Errorf("request: %w", errors.Join(input, invalid)), 2},
{errors.Join(input, operational), 1},
{fmt.Errorf("request: %w", errors.Join(invalid, context.Canceled)), 1},
} {
outcome := operationOutcome(tc.err)
if outcome.Status != tc.status || (tc.err != nil && !errors.Is(outcome.Cause, tc.err)) {
t.Fatalf("%v: outcome=%+v, want status %d and original cause", tc.err, outcome, tc.status)
}
}
application, err := commandkit.New(commandkit.Identity{Name: "narratio"}, commandkit.NewCommand(commandkit.CommandSpec[struct{}]{
Name: "fail", Run: func(commandkit.Invocation, struct{}) commandkit.Outcome { return operationOutcome(operational) },
}))
if err != nil {
t.Fatal(err)
}
var diagnostics bytes.Buffer
outcome := application.Execute(context.Background(), []string{"fail", "--quiet"}, commandkit.Streams{Out: io.Discard, Err: &diagnostics})
if outcome.Status != 1 || !errors.Is(outcome.Cause, operational) || strings.Count(diagnostics.String(), operational.Error()) != 1 {
t.Fatalf("failure delivery: outcome=%+v diagnostics=%q", outcome, diagnostics.String())
}
}
func TestNativeTreeRejectsRemovedRoutesAndMissingOperandsBeforeAcquisition(t *testing.T) {
application, err := newApplication(commandDependencies{
loadPipelineConfig: func(string, config.PipelineLoadOptions) (*config.PipelineConfig, error) {
t.Fatal("invalid input loaded configuration")
return nil, nil
},
loadSecretsDir: func(string) (*configkit.SecretsReport, error) {
t.Fatal("invalid input bootstrapped credentials")
return nil, nil
},
}, nil)
if err != nil {
t.Fatal(err)
}
cases := [][]string{{"run"}, {"artifacts", "regenerate"}, {"session", "init"}, {"session", "validate"}, {"session", "status"}, {"session", "plan"}, {"session", "artifacts"}, {"session", "restore"}, {"session", "clean"}, {"session", "locks", "list"}, {"session", "locks", "add"}, {"session", "locks", "remove"}, {"run-stage"}, {"analyze"}, {"publish"}, {"regenerate-artifacts"}, {"clean"}, {"plan"}, {"status"}, {"resume"}, {"lock"}, {"unlock"}, {"config", "artifacts"}, {"run", "session", "--session-id", "session"}, {"session", "status", "session", "--manifest", "manifest.json"}}
for _, args := range cases {
var out, diagnostic bytes.Buffer
outcome := application.Execute(context.Background(), args, commandkit.Streams{Out: &out, Err: &diagnostic})
if outcome.Status != 2 {
t.Fatalf("args=%v status=%d diagnostic=%s", args, outcome.Status, diagnostic.String())
}
}
}
func TestDomainCommandsUseNativeConfigurationDiagnostics(t *testing.T) {
root := t.TempDir()
invalid := filepath.Join(root, "invalid.yml")
if err := os.WriteFile(invalid, []byte("unknown_field: true\n"), 0600); err != nil {
t.Fatal(err)
}
for _, tc := range []struct {
path, code string
status int
}{
{invalid, "decode.unknown_field", 2},
{filepath.Join(root, "missing.yml"), "source.missing", 1},
} {
for _, command := range [][]string{{"config", "show"}, {"artifacts", "list"}} {
var out, diag bytes.Buffer
args := append(append([]string{}, command...), "--config", tc.path, "--quiet")
result := Execute(context.Background(), args, commandkit.Streams{Out: &out, Err: &diag})
var load *configkit.LoadError
if result.Status != tc.status || !errors.As(result.Cause, &load) || out.Len() != 0 {
t.Fatalf("%v: %+v", args, result)
}
if !strings.Contains(diag.String(), tc.code) || !strings.Contains(diag.String(), tc.path) || strings.Contains(diag.String(), "strict decode failed or validation failed") {
t.Fatalf("%v: %s", args, diag.String())
}
}
}
}
func TestNativeDiagnosticsRetainWarningsAndJoinedOperationalCause(t *testing.T) {
_, loadErr := configkit.Load(configkit.NoSource(), configkit.Options[struct{}]{Definition: configkit.Definition[struct{}]{Validate: func(_ *struct{}, v *configkit.Validation) {
v.Warning(configkit.Keys(), "review warning")
v.Error(configkit.Keys(), "review invalid input")
}}})
if loadErr == nil {
t.Fatal("expected validation failure")
}
cleanup := errors.New("resource release failed")
for _, verbose := range []bool{false, true} {
application, err := commandkit.New(commandkit.Identity{Name: "test"}, commandkit.NewCommand(commandkit.CommandSpec[struct{}]{Name: "fail", Run: func(inv commandkit.Invocation, _ struct{}) commandkit.Outcome {
return reportOperationOutcome(inv, errors.Join(loadErr, cleanup))
}}))
if err != nil {
t.Fatal(err)
}
args := []string{"fail"}
if verbose {
args = append(args, "--verbose")
}
var diag bytes.Buffer
outcome := application.Execute(context.Background(), args, commandkit.Streams{Out: io.Discard, Err: &diag})
if outcome.Status != 1 || !errors.Is(outcome.Cause, cleanup) || !errors.Is(outcome.Cause, loadErr) {
t.Fatalf("%+v", outcome)
}
if !strings.Contains(diag.String(), "review invalid input") || !strings.Contains(diag.String(), cleanup.Error()) || strings.Contains(diag.String(), "review warning") != verbose {
t.Fatalf("verbose=%t: %s", verbose, diag.String())
}
}
}

View File

@@ -3,6 +3,7 @@ package app
import ( import (
"bytes" "bytes"
"context" "context"
"encoding/json"
"fmt" "fmt"
"net/http" "net/http"
"net/http/httptest" "net/http/httptest"
@@ -13,7 +14,6 @@ import (
"time" "time"
"gitea.maximumdirect.net/eric/narratio/internal/artifacts" "gitea.maximumdirect.net/eric/narratio/internal/artifacts"
"gitea.maximumdirect.net/eric/narratio/internal/config"
"gitea.maximumdirect.net/eric/narratio/internal/manifest" "gitea.maximumdirect.net/eric/narratio/internal/manifest"
) )
@@ -27,115 +27,24 @@ func TestExecuteValidCommands(t *testing.T) {
pipelinePath, campaignPath, sessionPath := writeValidConfigFiles(t, workspaceRoot, srv.URL) pipelinePath, campaignPath, sessionPath := writeValidConfigFiles(t, workspaceRoot, srv.URL)
cases := []struct { for _, command := range [][]string{{"run", "2026-05-03"}, {"session", "plan", "2026-05-03"}, {"session", "status", "2026-05-03"}, {"run", "2026-05-03", "--stage", "polish"}} {
name string args := append(command, "--config", pipelinePath, "--campaign-file", campaignPath, "--session-file", sessionPath, "--format", "json")
args []string var stdout, stderr bytes.Buffer
wantOut string if code := executeForTest(args, &stdout, &stderr); code != 0 || stderr.Len() != 0 {
}{ t.Fatalf("args=%v status=%d diagnostics=%s", args, code, stderr.String())
{name: "run", args: []string{"run", "2026-05-03", "--config", pipelinePath, "--campaign-file", campaignPath, "--session", sessionPath}, wantOut: "narratio run: session 2026-05-03; executed=12 skipped=2; manifest="}, }
{name: "session plan", args: []string{"session", "plan", "2026-05-03", "--config", pipelinePath, "--campaign-file", campaignPath, "--session", sessionPath}, wantOut: "analyze: skip\n targets: none\n prerequisites: none\n execute: none\n reuse: none\npublish: skip\nnotify: skip"}, var report map[string]any
{name: "session status", args: []string{"session", "status", "2026-05-03", "--config", pipelinePath, "--campaign-file", campaignPath, "--session", sessionPath}, wantOut: "Session: 2026-05-03"}, if err := json.Unmarshal(stdout.Bytes(), &report); err != nil {
{name: "run-stage", args: []string{"run-stage", "polish", "2026-05-03", "--config", pipelinePath, "--campaign-file", campaignPath, "--session", sessionPath}, wantOut: "narratio run-stage: stage=polish executed=0 skipped=1 force=false; manifest="}, t.Fatal(err)
}
if report["session_id"] != "2026-05-03" {
t.Fatalf("report=%v", report)
}
} }
for _, tc := range cases {
t.Run(tc.name, func(t *testing.T) {
var stdout bytes.Buffer
var stderr bytes.Buffer
code := Execute(tc.args, &stdout, &stderr)
if code != 0 {
t.Fatalf("exit code = %d, want 0", code)
}
if stderr.Len() != 0 {
t.Fatalf("stderr = %q, want empty", stderr.String())
}
if !strings.Contains(stdout.String(), tc.wantOut) {
t.Fatalf("stdout = %q, want to contain %q", stdout.String(), tc.wantOut)
}
})
}
} }
func TestExecuteMissingRequiredFlags(t *testing.T) { func TestExecuteRunSingleStageNormalizeIsAccepted(t *testing.T) {
cases := []struct {
name string
args []string
want string
controlledDiscovery bool
}{
{name: "run missing session", args: []string{"run"}, want: "run: session_id is required"},
{name: "plan old top-level removed", args: []string{"plan"}, want: `unknown command: "plan"`},
{name: "status old top-level removed", args: []string{"status"}, want: `unknown command: "status"`},
{name: "resume removed", args: []string{"resume"}, want: `unknown command: "resume"`},
{name: "run-stage missing name", args: []string{"run-stage", "--config", "a", "--session", "b"}, want: "run-stage: expected stage name and session_id"},
{name: "run-stage missing session", args: []string{"run-stage", "polish"}, want: "run-stage: expected stage name and session_id"},
{name: "run missing config uses defaults", args: []string{"run", "2026-05-03", "--session", "session.yml"}, want: "run: no pipeline config path provided", controlledDiscovery: true},
}
for _, tc := range cases {
t.Run(tc.name, func(t *testing.T) {
var stdout bytes.Buffer
var stderr bytes.Buffer
deps := commandDependencies{}
executor := pipelineExecutor(executePlan)
missingPath := ""
if tc.controlledDiscovery {
deps, missingPath, executor = guardedMissingPipelineDiscovery(t)
}
code := executeWithDependencies(tc.args, &stdout, &stderr, deps, executor)
if code == 0 {
t.Fatalf("exit code = 0, want non-zero")
}
if stdout.Len() != 0 {
t.Fatalf("stdout = %q, want empty", stdout.String())
}
if !strings.Contains(stderr.String(), tc.want) {
t.Fatalf("stderr = %q, want to contain %q", stderr.String(), tc.want)
}
if tc.controlledDiscovery {
if got := stderr.String(); !strings.Contains(got, "no default pipeline config found") || !strings.Contains(got, missingPath) {
t.Fatalf("stderr = %q, want controlled searched path %q", got, missingPath)
}
}
})
}
}
func TestExecuteRunStageUnknownFails(t *testing.T) {
workspaceRoot := t.TempDir()
pipelinePath, campaignPath, sessionPath := writeValidConfigFiles(t, workspaceRoot, "https://example.com/transcribe")
var stdout bytes.Buffer
var stderr bytes.Buffer
code := Execute([]string{"run-stage", "unknown", "2026-05-03", "--config", pipelinePath, "--campaign-file", campaignPath, "--session", sessionPath}, &stdout, &stderr)
if code == 0 {
t.Fatal("exit code = 0, want non-zero")
}
if !strings.Contains(stderr.String(), "unknown stage") {
t.Fatalf("stderr = %q, want unknown stage error", stderr.String())
}
}
func TestExecuteRunStageArchiveAliasFails(t *testing.T) {
workspaceRoot := t.TempDir()
pipelinePath, campaignPath, sessionPath := writeValidConfigFiles(t, workspaceRoot, "https://example.com/transcribe")
var stdout bytes.Buffer
var stderr bytes.Buffer
code := Execute([]string{"run-stage", "archive", "2026-05-03", "--config", pipelinePath, "--campaign-file", campaignPath, "--session", sessionPath}, &stdout, &stderr)
if code == 0 {
t.Fatal("exit code = 0, want non-zero")
}
if !strings.Contains(stderr.String(), `unknown stage "archive"`) {
t.Fatalf("stderr = %q, want unknown stage alias error", stderr.String())
}
}
func TestExecuteRunStageNormalizeIsAccepted(t *testing.T) {
workspaceRoot := t.TempDir() workspaceRoot := t.TempDir()
pipelinePath, campaignPath, sessionPath := writeValidConfigFiles(t, workspaceRoot, "https://example.com/transcribe") pipelinePath, campaignPath, sessionPath := writeValidConfigFiles(t, workspaceRoot, "https://example.com/transcribe")
workRoot := filepath.Join(workspaceRoot, "work", "sample-campaign", "2026-05-03") workRoot := filepath.Join(workspaceRoot, "work", "sample-campaign", "2026-05-03")
@@ -143,25 +52,27 @@ func TestExecuteRunStageNormalizeIsAccepted(t *testing.T) {
mustWriteTestFile(t, polishedPath, `{"segments":[{"id":1}]}`) mustWriteTestFile(t, polishedPath, `{"segments":[{"id":1}]}`)
seedCurrentBuiltInEvidence(t, filepath.Join(workRoot, "manifest.json"), "2026-05-03", "sample-campaign", "polish", artifacts.TranscriptOutputKindPolished, artifacts.ArtifactTranscriptPolished, polishedPath) seedCurrentBuiltInEvidence(t, filepath.Join(workRoot, "manifest.json"), "2026-05-03", "sample-campaign", "polish", artifacts.TranscriptOutputKindPolished, artifacts.ArtifactTranscriptPolished, polishedPath)
seedInvocationPrerequisites(t, workspaceRoot, "normalize")
var stdout bytes.Buffer var stdout bytes.Buffer
var stderr bytes.Buffer var stderr bytes.Buffer
code := Execute([]string{"run-stage", "normalize", "2026-05-03", "--config", pipelinePath, "--campaign-file", campaignPath, "--session", sessionPath}, &stdout, &stderr) code := executeForTest([]string{"run", "2026-05-03", "--stage", "normalize", "--config", pipelinePath, "--campaign-file", campaignPath, "--session-file", sessionPath}, &stdout, &stderr)
if code != 0 { if code != 0 {
t.Fatalf("exit code = %d, want 0; stderr=%q", code, stderr.String()) t.Fatalf("exit code = %d, want 0; stderr=%q", code, stderr.String())
} }
if !strings.Contains(stdout.String(), "stage=normalize executed=1 skipped=0") { if !runCountsMatch(t, stdout.Bytes(), 1, 0, "normalize") {
t.Fatalf("stdout = %q, want normalize stage execution", stdout.String()) t.Fatalf("stdout = %q, want normalize stage execution", stdout.String())
} }
} }
func TestExecuteRunStageTranscribeUsesConfiguredWhisperXServer(t *testing.T) { func TestExecuteRunSingleStageTranscribeUsesConfiguredWhisperXServer(t *testing.T) {
workspaceRoot := t.TempDir() workspaceRoot := t.TempDir()
var serverCalls int var serverCalls int
srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
serverCalls++ serverCalls++
w.Header().Set("Content-Type", "application/json") w.Header().Set("Content-Type", "application/json")
_, _ = w.Write([]byte(`{"source":"run-stage-test","segments":[{"speaker":"alice"}]}`)) _, _ = w.Write([]byte(`{"source":"selected-stage-test","segments":[{"speaker":"alice"}]}`))
})) }))
defer srv.Close() defer srv.Close()
@@ -170,14 +81,14 @@ func TestExecuteRunStageTranscribeUsesConfiguredWhisperXServer(t *testing.T) {
var stdout bytes.Buffer var stdout bytes.Buffer
var stderr bytes.Buffer var stderr bytes.Buffer
code := Execute([]string{"run-stage", "prepare", "2026-05-03", "--config", pipelinePath, "--campaign-file", campaignPath, "--session", sessionPath}, &stdout, &stderr) code := executeForTest([]string{"run", "2026-05-03", "--stage", "prepare", "--config", pipelinePath, "--campaign-file", campaignPath, "--session-file", sessionPath}, &stdout, &stderr)
if code != 0 { if code != 0 {
t.Fatalf("prepare exit code = %d, want 0; stderr=%q", code, stderr.String()) t.Fatalf("prepare exit code = %d, want 0; stderr=%q", code, stderr.String())
} }
stdout.Reset() stdout.Reset()
stderr.Reset() stderr.Reset()
code = Execute([]string{"run-stage", "transcribe", "2026-05-03", "--config", pipelinePath, "--campaign-file", campaignPath, "--session", sessionPath, "--force"}, &stdout, &stderr) code = executeForTest([]string{"run", "2026-05-03", "--stage", "transcribe", "--config", pipelinePath, "--campaign-file", campaignPath, "--session-file", sessionPath, "--force"}, &stdout, &stderr)
if code != 0 { if code != 0 {
t.Fatalf("transcribe exit code = %d, want 0; stderr=%q", code, stderr.String()) t.Fatalf("transcribe exit code = %d, want 0; stderr=%q", code, stderr.String())
} }
@@ -194,12 +105,12 @@ func TestExecuteRunStageTranscribeUsesConfiguredWhisperXServer(t *testing.T) {
if got == `{"schema":"speaker_transcript.v1","segments":[]}` { if got == `{"schema":"speaker_transcript.v1","segments":[]}` {
t.Fatalf("got noop transcript output: %q", got) t.Fatalf("got noop transcript output: %q", got)
} }
if !strings.Contains(got, `"source":"run-stage-test"`) { if !strings.Contains(got, `"source":"selected-stage-test"`) {
t.Fatalf("output = %q, want run-stage server json", got) t.Fatalf("output = %q, want selected-stage server JSON", got)
} }
} }
func TestExecuteRunStagePolishLoadsCredentialFromSecretsDir(t *testing.T) { func TestExecuteRunSingleStagePolishLoadsCredentialFromSecretsDir(t *testing.T) {
workspaceRoot := t.TempDir() workspaceRoot := t.TempDir()
configDir := t.TempDir() configDir := t.TempDir()
sessionID := "2026-05-03" sessionID := "2026-05-03"
@@ -265,13 +176,15 @@ inputs:
seedCurrentBuiltInEvidence(t, filepath.Join(workRoot, "manifest.json"), sessionID, "sample-campaign", "merge", artifacts.TranscriptOutputKindBase, artifacts.ArtifactTranscriptBase, basePath) seedCurrentBuiltInEvidence(t, filepath.Join(workRoot, "manifest.json"), sessionID, "sample-campaign", "merge", artifacts.TranscriptOutputKindBase, artifacts.ArtifactTranscriptBase, basePath)
mustWriteTestFile(t, filepath.Join(workRoot, "inputs", "glossary.yml"), "[]\n") mustWriteTestFile(t, filepath.Join(workRoot, "inputs", "glossary.yml"), "[]\n")
seedInvocationPrerequisites(t, workspaceRoot, "polish")
var stdout bytes.Buffer var stdout bytes.Buffer
var stderr bytes.Buffer var stderr bytes.Buffer
code := Execute([]string{"run-stage", "polish", sessionID, "--config", pipelinePath, "--campaign-file", campaignPath, "--session", sessionPath, "--force"}, &stdout, &stderr) code := executeForTest([]string{"run", sessionID, "--stage", "polish", "--config", pipelinePath, "--campaign-file", campaignPath, "--session-file", sessionPath, "--force", "--secrets-dir", secretsDir}, &stdout, &stderr)
if code != 0 { if code != 0 {
t.Fatalf("exit code = %d, want 0; stderr=%q", code, stderr.String()) t.Fatalf("exit code = %d, want 0; stderr=%q", code, stderr.String())
} }
if !strings.Contains(stdout.String(), "stage=polish executed=1 skipped=0") { if !runCountsMatch(t, stdout.Bytes(), 1, 0, "polish") {
t.Fatalf("stdout = %q, want polish execution", stdout.String()) t.Fatalf("stdout = %q, want polish execution", stdout.String())
} }
recorded, err := (&manifest.LocalStore{}).Load(context.Background(), filepath.Join(workRoot, "manifest.json")) recorded, err := (&manifest.LocalStore{}).Load(context.Background(), filepath.Join(workRoot, "manifest.json"))
@@ -357,7 +270,7 @@ inputs:
var stdout bytes.Buffer var stdout bytes.Buffer
var stderr bytes.Buffer var stderr bytes.Buffer
code := Execute([]string{"run", "2026-05-03", "--config", pipelinePath, "--campaign-file", campaignPath, "--session", sessionPath, "--secrets-dir", filepath.Join(configDir, "missing-secrets")}, &stdout, &stderr) code := executeForTest([]string{"run", "2026-05-03", "--config", pipelinePath, "--campaign-file", campaignPath, "--session-file", sessionPath, "--secrets-dir", filepath.Join(configDir, "missing-secrets")}, &stdout, &stderr)
if code == 0 { if code == 0 {
t.Fatal("exit code = 0, want non-zero") t.Fatal("exit code = 0, want non-zero")
} }
@@ -375,20 +288,16 @@ func TestExecuteUsesDefaultPipelineConfigPathWhenConfigFlagOmitted(t *testing.T)
defer srv.Close() defer srv.Close()
pipelinePath, campaignPath, sessionPath := writeValidConfigFiles(t, workspaceRoot, srv.URL) pipelinePath, campaignPath, sessionPath := writeValidConfigFiles(t, workspaceRoot, srv.URL)
originalDefaults := append([]string(nil), config.DefaultPipelineConfigSearchPaths...) withDefaultPipelineCampaignConfigs(t, pipelinePath, campaignPath)
config.DefaultPipelineConfigSearchPaths = []string{pipelinePath}
defer func() {
config.DefaultPipelineConfigSearchPaths = originalDefaults
}()
_ = campaignPath _ = campaignPath
var stdout bytes.Buffer var stdout bytes.Buffer
var stderr bytes.Buffer var stderr bytes.Buffer
code := Execute([]string{"run", "2026-05-03", "--session", sessionPath}, &stdout, &stderr) code := executeForTest([]string{"run", "2026-05-03", "--session-file", sessionPath}, &stdout, &stderr)
if code != 0 { if code != 0 {
t.Fatalf("exit code = %d, want 0; stderr=%q", code, stderr.String()) t.Fatalf("exit code = %d, want 0; stderr=%q", code, stderr.String())
} }
if !strings.Contains(stdout.String(), "narratio run: session 2026-05-03; executed=12 skipped=2; manifest=") { if !runCountsMatch(t, stdout.Bytes(), 12, 2, "") {
t.Fatalf("stdout = %q, want successful run output", stdout.String()) t.Fatalf("stdout = %q, want successful run output", stdout.String())
} }
} }
@@ -402,7 +311,7 @@ func TestExecuteMissingCampaignConfigReportsRegistryPath(t *testing.T) {
var stdout bytes.Buffer var stdout bytes.Buffer
var stderr bytes.Buffer var stderr bytes.Buffer
code := Execute([]string{"run", "2026-05-03", "--config", pipelinePath, "--session", sessionPath}, &stdout, &stderr) code := executeForTest([]string{"run", "2026-05-03", "--config", pipelinePath, "--session-file", sessionPath}, &stdout, &stderr)
if code == 0 { if code == 0 {
t.Fatal("exit code = 0, want non-zero") t.Fatal("exit code = 0, want non-zero")
} }
@@ -423,11 +332,11 @@ func TestExecuteUsesPipelineDefaultCampaignID(t *testing.T) {
var stdout bytes.Buffer var stdout bytes.Buffer
var stderr bytes.Buffer var stderr bytes.Buffer
code := Execute([]string{"session", "status", "2026-05-03", "--config", pipelinePath, "--session", sessionPath}, &stdout, &stderr) code := executeForTest([]string{"session", "status", "2026-05-03", "--config", pipelinePath, "--session-file", sessionPath}, &stdout, &stderr)
if code != 0 { if code != 0 {
t.Fatalf("exit code = %d, want 0; stderr=%q", code, stderr.String()) t.Fatalf("exit code = %d, want 0; stderr=%q", code, stderr.String())
} }
if !strings.Contains(stdout.String(), "Campaign: sample-campaign") { if decodeNativeReport[sessionStateReport](t, stdout.Bytes()).Campaign != "sample-campaign" {
t.Fatalf("stdout = %q, want default campaign", stdout.String()) t.Fatalf("stdout = %q, want default campaign", stdout.String())
} }
} }
@@ -452,35 +361,20 @@ inputs:
var stdout bytes.Buffer var stdout bytes.Buffer
var stderr bytes.Buffer var stderr bytes.Buffer
code := Execute([]string{"session", "status", "2026-05-03", "--config", pipelinePath, "--campaign", "icewind", "--session", sessionPath}, &stdout, &stderr) code := executeForTest([]string{"session", "status", "2026-05-03", "--config", pipelinePath, "--campaign", "icewind", "--session-file", sessionPath}, &stdout, &stderr)
if code != 0 { if code != 0 {
t.Fatalf("exit code = %d, want 0; stderr=%q", code, stderr.String()) t.Fatalf("exit code = %d, want 0; stderr=%q", code, stderr.String())
} }
if !strings.Contains(stdout.String(), "Campaign: icewind") { if decodeNativeReport[sessionStateReport](t, stdout.Bytes()).Campaign != "icewind" {
t.Fatalf("stdout = %q, want selected campaign", stdout.String()) t.Fatalf("stdout = %q, want selected campaign", stdout.String())
} }
} }
func TestExecuteRejectsCampaignIDAndCampaignFile(t *testing.T) {
workspaceRoot := t.TempDir()
pipelinePath, campaignPath, sessionPath := writeValidConfigFiles(t, workspaceRoot)
var stdout bytes.Buffer
var stderr bytes.Buffer
code := Execute([]string{"session", "status", "2026-05-03", "--config", pipelinePath, "--campaign", "sample-campaign", "--campaign-file", campaignPath, "--session", sessionPath}, &stdout, &stderr)
if code == 0 {
t.Fatal("exit code = 0, want non-zero")
}
if !strings.Contains(stderr.String(), "mutually exclusive") {
t.Fatalf("stderr = %q, want mutually exclusive error", stderr.String())
}
}
func TestExecuteInvalidCommand(t *testing.T) { func TestExecuteInvalidCommand(t *testing.T) {
var stdout bytes.Buffer var stdout bytes.Buffer
var stderr bytes.Buffer var stderr bytes.Buffer
code := Execute([]string{"bogus"}, &stdout, &stderr) code := executeForTest([]string{"bogus"}, &stdout, &stderr)
if code == 0 { if code == 0 {
t.Fatalf("exit code = 0, want non-zero") t.Fatalf("exit code = 0, want non-zero")
} }
@@ -496,22 +390,6 @@ func TestExecuteInvalidCommand(t *testing.T) {
} }
} }
func TestExecuteMissingCommand(t *testing.T) {
var stdout bytes.Buffer
var stderr bytes.Buffer
code := Execute(nil, &stdout, &stderr)
if code == 0 {
t.Fatalf("exit code = 0, want non-zero")
}
if stdout.Len() != 0 {
t.Fatalf("stdout = %q, want empty", stdout.String())
}
if !strings.Contains(stderr.String(), "Usage: narratio") {
t.Fatalf("stderr = %q, want usage message", stderr.String())
}
}
func writeValidConfigFiles(t *testing.T, workspaceRoot string, transcribeURL ...string) (string, string, string) { func writeValidConfigFiles(t *testing.T, workspaceRoot string, transcribeURL ...string) (string, string, string) {
t.Helper() t.Helper()
@@ -601,9 +479,9 @@ inputs:
func materializePrepareResumeFixture(t *testing.T, pipelinePath, campaignPath, sessionPath string) { func materializePrepareResumeFixture(t *testing.T, pipelinePath, campaignPath, sessionPath string) {
t.Helper() t.Helper()
if err := RunStage( if err := invokeNativeCommand(
context.Background(), context.Background(),
[]string{"prepare", "2026-05-03", "--config", pipelinePath, "--campaign-file", campaignPath, "--session", sessionPath}, []string{"run", "--stage", "prepare", "2026-05-03", "--config", pipelinePath, "--campaign-file", campaignPath, "--session-file", sessionPath},
&bytes.Buffer{}, &bytes.Buffer{},
); err != nil { ); err != nil {
t.Fatalf("materialize prepare resume fixture: %v", err) t.Fatalf("materialize prepare resume fixture: %v", err)

View File

@@ -3,209 +3,132 @@ package app
import ( import (
"bytes" "bytes"
"context" "context"
"encoding/json"
"errors" "errors"
"os"
"path/filepath" "path/filepath"
"reflect" "reflect"
"strings"
"testing" "testing"
"gitea.maximumdirect.net/eric/narratio/internal/config"
"go.maximumdirect.net/commandkit"
) )
const artifactCatalogHeader = "key\tsource\tdefinitions\tenabled\toutput\tdependencies\tfamily\tcharacter\tfamily_source\tparty_source\n" func catalogReportForTest(t *testing.T, args []string) *artifactCatalogReport {
t.Helper()
output := nativeInspectionForTest(t, append([]string{"artifacts", "list", "--format", "json"}, args...))
var report artifactCatalogReport
if err := json.Unmarshal([]byte(output), &report); err != nil {
t.Fatal(err)
}
return &report
}
func TestConfigArtifactsReportsOrdinaryCatalogWithoutCampaign(t *testing.T) { func TestNativeCatalogValidationErrorsAreUsage(t *testing.T) {
dir := t.TempDir() pipeline, campaign, session := writeValidConfigFiles(t, t.TempDir())
pipelinePath := filepath.Join(dir, "pipeline.yml") data, err := os.ReadFile(pipeline)
mustWriteTestFile(t, pipelinePath, `workspace: if err != nil {
root: `+filepath.Join(dir, "workspace")+` t.Fatal(err)
whisperx: }
transcribe_url: https://transcription.example.com/transcribe mustWriteTestFile(t, pipeline, string(data)+`scriptorium:
scriptorium:
binary: scriptorium
artifacts: artifacts:
zeta: result:
enabled: false enabled: false
output_path: artifacts/zeta.md output_path: artifacts/result.md
depends_on: [missing]
`)
for _, args := range [][]string{
{"artifacts", "list", "--config", pipeline},
{"run", "2026-05-03", "--stage", "analyze", "--config", pipeline, "--campaign-file", campaign, "--session-file", session},
} {
var out, diagnostic bytes.Buffer
outcome := Execute(context.Background(), args, commandkit.Streams{Out: &out, Err: &diagnostic})
var input *config.ArtifactCatalogInputError
if outcome.Status != 2 || !errors.As(outcome.Cause, &input) {
t.Fatalf("%v: status=%d cause=%v diagnostics=%s", args, outcome.Status, outcome.Cause, &diagnostic)
}
}
}
func TestArtifactCatalogCommandWithoutCampaignPreservesDependencies(t *testing.T) {
dir := t.TempDir()
pipeline := filepath.Join(dir, "pipeline.yml")
mustWriteTestFile(t, pipeline, `workspace:
root: `+filepath.Join(dir, "workspace")+`
whisperx: {transcribe_url: https://transcription.example.test/transcribe}
scriptorium:
artifacts:
zeta: {enabled: false, output_path: artifacts/zeta.md}
alpha: alpha:
enabled: false enabled: false
output_path: artifacts/alpha.md output_path: artifacts/alpha.md
inputs: inputs:
upstream: {source: narratio.artifact.zeta, required: true} upstream: {source: narratio.artifact.zeta, required: true}
`) `)
report := catalogReportForTest(t, []string{"--config", pipeline})
var out bytes.Buffer found := map[string]artifactDefinitionReport{}
if err := ConfigArtifacts(context.Background(), []string{"--config", pipelinePath}, &out); err != nil { for _, entry := range report.Artifacts {
t.Fatalf("ConfigArtifacts() error = %v", err) found[entry.Source] = entry
} }
lines := strings.Split(strings.TrimSuffix(out.String(), "\n"), "\n") alpha := found["narratio.artifact.alpha"]
if len(lines) != 3 || !strings.HasPrefix(lines[1], "alpha\t") || !strings.HasPrefix(lines[2], "zeta\t") { if alpha.Producer != "analyze" || alpha.Enabled == nil || *alpha.Enabled || !reflect.DeepEqual(alpha.Dependencies, []string{"zeta"}) || !reflect.DeepEqual(alpha.DefinitionSources, []string{pipeline}) {
t.Fatalf("catalog order/output = %q", out.String()) t.Fatalf("alpha=%#v", alpha)
} }
alpha := strings.Split(lines[1], "\t") if found["narratio.transcript.base"].Producer != "merge" {
if len(alpha) != 10 { t.Fatal("catalog omitted built-in producer")
t.Fatalf("alpha fields = %#v", alpha)
} }
if alpha[1] != "narratio.artifact.alpha" || alpha[2] != pipelinePath || alpha[3] != "false" || alpha[4] != "artifacts/alpha.md" || alpha[5] != "zeta" { if _, err := os.Stat(filepath.Join(dir, "workspace")); !os.IsNotExist(err) {
t.Fatalf("alpha record = %#v", alpha) t.Fatalf("listing created workspace: %v", err)
} }
} }
func TestConfigArtifactsEmptyCatalogWritesOnlyHeader(t *testing.T) { func TestArtifactCatalogCommandUsesExplicitRosterAndNativeConfiguration(t *testing.T) {
dir := t.TempDir() pipeline, _ := writeInspectionFamilyConfig(t)
pipelinePath := filepath.Join(dir, "pipeline.yml") overlay := filepath.Join(filepath.Dir(pipeline), "overlays", "testing.yml")
mustWriteTestFile(t, pipelinePath, "workspace:\n root: "+filepath.Join(dir, "workspace")+"\nwhisperx:\n transcribe_url: https://transcription.example.com/transcribe\n") mustWriteTestFile(t, overlay, "scriptorium:\n artifact_families:\n character_note:\n prompt_id: dnd.character_note.testing\n")
var out bytes.Buffer roster := filepath.Join(t.TempDir(), "selected.yml")
if err := ConfigArtifacts(context.Background(), []string{"--config", pipelinePath}, &out); err != nil { mustWriteTestFile(t, roster, "schema_version: narratio.party.v1\ncharacters:\n synthetic_character:\n player: {name: Synthetic Player}\n character: {name: Synthetic Character, classes: [{name: ranger}]}\n")
selected := "testing"
loaded, err := config.LoadPipelineWithOptions(pipeline, config.PipelineLoadOptions{Overlay: &selected})
if err != nil {
t.Fatal(err) t.Fatal(err)
} }
if out.String() != artifactCatalogHeader { var before, after bytes.Buffer
t.Fatalf("empty catalog = %q, want header only", out.String()) if err := loaded.ConfigKitResult().WriteEffective(&before); err != nil {
}
}
func TestConfigArtifactsReportsGeneratedFamilyProvenance(t *testing.T) {
pipelinePath, campaignPath := writeInspectionFamilyConfig(t)
var out bytes.Buffer
if err := ConfigArtifacts(context.Background(), []string{"--config", pipelinePath, "--campaign-file", campaignPath}, &out); err != nil {
t.Fatal(err) t.Fatal(err)
} }
records := catalogRecordsByKey(t, out.String()) app, err := newApplication(commandDependencies{loadPipelineConfig: func(string, config.PipelineLoadOptions) (*config.PipelineConfig, error) { return loaded, nil }}, executePlan)
meta := records["character_meta_arannis"] if err != nil {
note := records["character_note_arannis"]
partyPath := filepath.Join(filepath.Dir(campaignPath), "party.yml")
if len(meta) != 10 || meta[6] != "character_meta" || meta[7] != "arannis" || meta[8] != pipelinePath || meta[9] != partyPath {
t.Fatalf("generated meta record = %#v", meta)
}
if len(note) != 10 || note[5] != "character_meta_arannis" || note[6] != "character_note" {
t.Fatalf("generated note record = %#v", note)
}
}
func TestConfigArtifactsReportsOverlayFamilyContributors(t *testing.T) {
pipelinePath, campaignPath := writeInspectionFamilyConfig(t)
overlayPath := filepath.Join(filepath.Dir(pipelinePath), "overlays", "testing.yml")
mustWriteTestFile(t, overlayPath, `scriptorium:
artifact_families:
character_note:
prompt_id: dnd.character_note.testing
`)
args := []string{"--config", pipelinePath, "--campaign-file", campaignPath, "--overlay", "testing"}
var catalog bytes.Buffer
if err := ConfigArtifacts(context.Background(), args, &catalog); err != nil {
t.Fatal(err) t.Fatal(err)
} }
records := catalogRecordsByKey(t, catalog.String()) var out, diagnostic bytes.Buffer
if got := strings.Split(records["character_note_arannis"][2], ","); !reflect.DeepEqual(got, []string{overlayPath, pipelinePath}) { outcome := app.Execute(context.Background(), []string{"artifacts", "list", "--config", pipeline, "--overlay", selected, "--party-file", roster, "--format", "json"}, commandkit.Streams{Out: &out, Err: &diagnostic})
t.Fatalf("generated family definitions = %#v", got) if outcome.Status != 0 {
t.Fatalf("status=%d diagnostics=%s", outcome.Status, diagnostic.String())
} }
var report artifactCatalogReport
var sources bytes.Buffer if err := json.Unmarshal(out.Bytes(), &report); err != nil {
if err := ConfigSources(context.Background(), args, &sources); err != nil {
t.Fatal(err) t.Fatal(err)
} }
want := "scriptorium.artifacts.character_note_arannis.prompt_id\tfamily\t" + overlayPath found := false
if !strings.Contains(sources.String(), want) { for _, entry := range report.Artifacts {
t.Fatalf("sources output missing overlay family contributor %q:\n%s", want, sources.String()) if entry.Family == "character_note" {
} if entry.CharacterID != "synthetic_character" || entry.PartySource != roster || entry.Key != "character_note_synthetic_character" {
} t.Fatalf("member=%#v", entry)
}
func TestConfigArtifactsReportsBaseAndOverlayContributors(t *testing.T) { if !reflect.DeepEqual(entry.DefinitionSources, []string{overlay, pipeline}) {
dir := t.TempDir() t.Fatalf("definition sources=%v", entry.DefinitionSources)
pipelinePath := filepath.Join(dir, "pipeline.yml") }
overlayPath := filepath.Join(dir, "overlays", "testing.yml") found = true
mustWriteTestFile(t, pipelinePath, `workspace:
root: /srv/narratio
whisperx:
transcribe_url: https://transcription.example.com/transcribe
scriptorium:
binary: scriptorium
artifacts:
notes:
enabled: false
output_path: artifacts/notes.md
`)
mustWriteTestFile(t, overlayPath, `scriptorium:
artifacts:
notes:
enabled: true
prompt_id: notes
overlay_only:
enabled: false
output_path: artifacts/overlay-only.md
`)
var out bytes.Buffer
if err := ConfigArtifacts(context.Background(), []string{"--config", pipelinePath, "--overlay", "testing"}, &out); err != nil {
t.Fatal(err)
}
records := catalogRecordsByKey(t, out.String())
if got := strings.Split(records["notes"][2], ","); !reflect.DeepEqual(got, []string{overlayPath, pipelinePath}) {
t.Fatalf("notes definitions = %#v", got)
}
if got := records["overlay_only"][2]; got != overlayPath {
t.Fatalf("overlay-only definition = %q, want %q", got, overlayPath)
}
}
func TestConfigArtifactsIdentityDoesNotDependOnDefinitionFilename(t *testing.T) {
inlineDir := t.TempDir()
inlinePath := filepath.Join(inlineDir, "pipeline.yml")
mustWriteTestFile(t, inlinePath, artifactIdentityPipeline("", "recap"))
importDir := t.TempDir()
importPath := filepath.Join(importDir, "pipeline.yml")
mustWriteTestFile(t, importPath, artifactIdentityPipeline("artifacts.yml", ""))
mustWriteTestFile(t, filepath.Join(importDir, "artifacts.yml"), "scriptorium:\n artifacts:\n recap:\n enabled: false\n output_path: artifacts/recap.md\n")
for _, path := range []string{inlinePath, importPath} {
var out bytes.Buffer
if err := ConfigArtifacts(context.Background(), []string{"--config", path}, &out); err != nil {
t.Fatal(err)
}
if got := catalogRecordsByKey(t, out.String())["recap"][1]; got != "narratio.artifact.recap" {
t.Fatalf("source identity for %s = %q", path, got)
} }
} }
} if !found {
t.Fatal("catalog omitted selected family member")
func TestConfigArtifactsPropagatesWriterErrorsAndEscapesFields(t *testing.T) {
dir := t.TempDir()
pipelinePath := filepath.Join(dir, "pipeline.yml")
mustWriteTestFile(t, pipelinePath, "workspace:\n root: /srv/narratio\nwhisperx:\n transcribe_url: https://transcription.example.com/transcribe\n")
want := errors.New("write rejected")
err := ConfigArtifacts(context.Background(), []string{"--config", pipelinePath}, rejectingCatalogWriter{err: want})
if !errors.Is(err, want) {
t.Fatalf("ConfigArtifacts() error = %v, want writer error", err)
} }
if got := escapeCatalogField("a\\b\tc\nd\r"); got != `a\\b\tc\nd\r` { if err := loaded.ConfigKitResult().WriteEffective(&after); err != nil {
t.Fatalf("escaped field = %q", got) t.Fatal(err)
}
if !bytes.Equal(before.Bytes(), after.Bytes()) {
t.Fatal("catalog derivation changed native configuration")
} }
} }
func catalogRecordsByKey(t *testing.T, output string) map[string][]string {
t.Helper()
lines := strings.Split(strings.TrimSuffix(output, "\n"), "\n")
if len(lines) == 0 || lines[0]+"\n" != artifactCatalogHeader {
t.Fatalf("catalog header = %q", output)
}
records := make(map[string][]string, len(lines)-1)
for _, line := range lines[1:] {
fields := strings.Split(line, "\t")
records[fields[0]] = fields
}
return records
}
func artifactIdentityPipeline(importPath, inlineKey string) string {
document := "workspace:\n root: /srv/narratio\nwhisperx:\n transcribe_url: https://transcription.example.com/transcribe\nscriptorium:\n binary: scriptorium\n"
if importPath != "" {
document = "configkit:\n imports:\n - path: " + importPath + "\n" + document
}
if inlineKey != "" {
document += " artifacts:\n " + inlineKey + ":\n enabled: false\n output_path: artifacts/recap.md\n"
}
return document
}
type rejectingCatalogWriter struct{ err error }
func (w rejectingCatalogWriter) Write([]byte) (int, error) { return 0, w.err }

View File

@@ -1,385 +0,0 @@
package app
import (
"context"
"errors"
"flag"
"fmt"
"io"
"sort"
"strconv"
"strings"
"gitea.maximumdirect.net/eric/narratio/internal/config"
)
type inspectionFlags struct {
pipelinePath string
campaignPath string
campaignFilePath string
overlay singletonStringFlag
secretsDir singletonStringFlag
}
type inspectionConfig struct {
PipelinePath string
Pipeline *config.PipelineConfig
CampaignPath string
Campaign *config.CampaignConfig
Party config.ResolvedParty
}
// Config dispatches read-only pipeline configuration commands.
func Config(ctx context.Context, args []string, out io.Writer) error {
return configWithDependencies(ctx, args, out, commandDependencies{})
}
func configWithDependencies(ctx context.Context, args []string, out io.Writer, deps commandDependencies) error {
deps = normalizeCommandDependencies(deps)
if len(args) == 0 {
return fmt.Errorf("config: expected subcommand: validate|show|sources|artifacts|diff")
}
if args[0] == "--help" || args[0] == "-h" {
writeConfigCommandUsage(out)
return nil
}
switch args[0] {
case "validate":
return configValidateWithDependencies(ctx, args[1:], out, deps)
case "show":
return configShowWithDependencies(ctx, args[1:], out, deps)
case "sources":
return configSourcesWithDependencies(ctx, args[1:], out, deps)
case "artifacts":
return configArtifactsWithDependencies(ctx, args[1:], out, deps)
case "diff":
return configDiffWithDependencies(ctx, args[1:], out, deps)
default:
return fmt.Errorf("config: unknown subcommand %q", args[0])
}
}
// ConfigValidate validates one fully resolved effective pipeline without
// loading session state or constructing runtime collaborators.
func ConfigValidate(ctx context.Context, args []string, out io.Writer) error {
return configValidateWithDependencies(ctx, args, out, commandDependencies{})
}
func configValidateWithDependencies(_ context.Context, args []string, out io.Writer, deps commandDependencies) error {
flags, err := parseInspectionFlags("config validate", args, out)
if err != nil {
if errors.Is(err, flag.ErrHelp) {
return nil
}
return err
}
resolved, err := resolveInspectionConfigWithDependencies(flags, deps)
if err != nil {
return fmt.Errorf("config validate: %w", err)
}
_, err = fmt.Fprintf(out, "Configuration valid: root=%s; overlay=%s; digest=%s\n",
inspectionRootPath(resolved), inspectionOverlay(resolved.Pipeline), config.EffectivePipelineDigest(resolved.Pipeline))
return err
}
// ConfigShow validates and renders one fully resolved effective pipeline
// without loading session state or constructing runtime collaborators.
func ConfigShow(ctx context.Context, args []string, out io.Writer) error {
return configShowWithDependencies(ctx, args, out, commandDependencies{})
}
func configShowWithDependencies(_ context.Context, args []string, out io.Writer, deps commandDependencies) error {
flags, err := parseInspectionFlags("config show", args, out)
if err != nil {
if errors.Is(err, flag.ErrHelp) {
return nil
}
return err
}
resolved, err := resolveInspectionConfigWithDependencies(flags, deps)
if err != nil {
return fmt.Errorf("config show: %w", err)
}
data, err := config.MarshalEffectivePipeline(resolved.Pipeline)
if err != nil {
return fmt.Errorf("config show: %w", err)
}
_, err = out.Write(data)
return err
}
// ConfigSources validates and reports deterministic effective configuration
// ownership without loading session state or runtime collaborators.
func ConfigSources(ctx context.Context, args []string, out io.Writer) error {
return configSourcesWithDependencies(ctx, args, out, commandDependencies{})
}
func configSourcesWithDependencies(_ context.Context, args []string, out io.Writer, deps commandDependencies) error {
flags, err := parseInspectionFlags("config sources", args, out)
if err != nil {
if errors.Is(err, flag.ErrHelp) {
return nil
}
return err
}
resolved, err := resolveInspectionConfigWithDependencies(flags, deps)
if err != nil {
return fmt.Errorf("config sources: %w", err)
}
records, err := config.EffectivePipelineSources(resolved.Pipeline, resolved.Party)
if err != nil {
return fmt.Errorf("config sources: %w", err)
}
records = append(records, config.EffectiveCampaignSources(resolved.CampaignPath, resolved.Campaign, resolved.Party)...)
sortInspectionSourceRecords(records)
if err := writeInspectionSourceHeader(out, resolved); err != nil {
return err
}
for _, record := range records {
if _, err := fmt.Fprintf(out, "%s\t%s\t%s\n", record.Path, record.Role, record.Source); err != nil {
return err
}
}
return nil
}
// ConfigArtifacts validates and reports the effective concrete artifact catalog
// without loading session state or runtime collaborators.
func ConfigArtifacts(ctx context.Context, args []string, out io.Writer) error {
return configArtifactsWithDependencies(ctx, args, out, commandDependencies{})
}
func configArtifactsWithDependencies(_ context.Context, args []string, out io.Writer, deps commandDependencies) error {
flags, err := parseInspectionFlags("config artifacts", args, out)
if err != nil {
if errors.Is(err, flag.ErrHelp) {
return nil
}
return err
}
resolved, err := resolveInspectionConfigWithDependencies(flags, deps)
if err != nil {
return fmt.Errorf("config artifacts: %w", err)
}
records, err := config.EffectiveArtifactCatalog(resolved.Pipeline, resolved.Party)
if err != nil {
return fmt.Errorf("config artifacts: %w", err)
}
if _, err := fmt.Fprintln(out, "key\tsource\tdefinitions\tenabled\toutput\tdependencies\tfamily\tcharacter\tfamily_source\tparty_source"); err != nil {
return err
}
for _, record := range records {
fields := []string{
record.Key,
record.SourceID,
strings.Join(normalizedCatalogPaths(record.DefinitionSources), ","),
strconv.FormatBool(record.Enabled),
record.OutputPath,
strings.Join(record.Dependencies, ","),
record.FamilyKey,
record.CharacterID,
config.NormalizedConfigurationPath(record.FamilySource),
config.NormalizedConfigurationPath(record.PartySource),
}
for index := range fields {
fields[index] = escapeCatalogField(fields[index])
}
if _, err := fmt.Fprintln(out, strings.Join(fields, "\t")); err != nil {
return err
}
}
return nil
}
func normalizedCatalogPaths(paths []string) []string {
result := make([]string, len(paths))
for index, path := range paths {
result[index] = config.NormalizedConfigurationPath(path)
}
sort.Strings(result)
return result
}
func escapeCatalogField(value string) string {
value = strings.ReplaceAll(value, "\\", "\\\\")
value = strings.ReplaceAll(value, "\t", "\\t")
value = strings.ReplaceAll(value, "\r", "\\r")
return strings.ReplaceAll(value, "\n", "\\n")
}
func parseInspectionFlags(command string, args []string, out io.Writer) (inspectionFlags, error) {
fs := flag.NewFlagSet(command, flag.ContinueOnError)
fs.SetOutput(out)
var flags inspectionFlags
fs.StringVar(&flags.pipelinePath, "config", "", "path to pipeline.yml (optional; defaults searched)")
fs.StringVar(&flags.campaignPath, "campaign", "", "campaign ID")
fs.StringVar(&flags.campaignFilePath, "campaign-file", "", "path to campaign.yml")
flags.overlay.name = "overlay"
fs.Var(&flags.overlay, "overlay", "named pipeline overlay")
flags.secretsDir.name = "secrets-dir"
fs.Var(&flags.secretsDir, "secrets-dir", "secrets directory (optional; defaults beside pipeline.yml)")
fs.Usage = func() {
fmt.Fprintf(out, "Usage: narratio %s [--config <pipeline.yml>] [--campaign <id> | --campaign-file <campaign.yml>] [--overlay <name>] [--secrets-dir <path>]\n\n", command)
fmt.Fprintln(out, "Resolves configuration without a session, workspace, manifest, adapters, or external services.")
fmt.Fprintln(out)
fmt.Fprintln(out, "Flags:")
fs.PrintDefaults()
}
if err := fs.Parse(args); err != nil {
return inspectionFlags{}, fmt.Errorf("%s: invalid flags: %w", command, err)
}
if fs.NArg() != 0 {
return inspectionFlags{}, fmt.Errorf("%s: unexpected positional arguments", command)
}
if strings.TrimSpace(flags.campaignPath) != "" && strings.TrimSpace(flags.campaignFilePath) != "" {
return inspectionFlags{}, fmt.Errorf("%s: --campaign and --campaign-file are mutually exclusive", command)
}
return flags, nil
}
func resolveInspectionConfigWithDependencies(flags inspectionFlags, deps commandDependencies) (*inspectionConfig, error) {
pipelinePath, pipeline, err := loadPipelineConfigWithDependencies(flags.pipelinePath, config.PipelineLoadOptions{Overlay: flags.overlay.pointer()}, flags.secretsDir.pointer(), deps)
if err != nil {
return nil, err
}
needsCampaign := pipelineHasArtifactFamilies(pipeline)
hasCampaignSelection := strings.TrimSpace(flags.campaignPath) != "" || strings.TrimSpace(flags.campaignFilePath) != ""
if !needsCampaign && !hasCampaignSelection {
if err := validateInspectionPipeline(pipelinePath, pipeline); err != nil {
return nil, err
}
return &inspectionConfig{PipelinePath: pipelinePath, Pipeline: pipeline}, nil
}
campaignPath, err := resolveCampaignConfigPath(pipeline, flags.campaignPath, flags.campaignFilePath)
if err != nil {
if needsCampaign {
return nil, fmt.Errorf("pipeline.scriptorium.artifact_families requires a campaign: %w", err)
}
return nil, err
}
campaign, err := config.LoadCampaign(campaignPath)
if err != nil {
return nil, err
}
if selectedID := strings.TrimSpace(flags.campaignPath); selectedID != "" && strings.TrimSpace(flags.campaignFilePath) == "" {
if got := config.CampaignID(campaign); got != selectedID {
return nil, fmt.Errorf("campaign config %q invalid: campaign_id %q does not match selected campaign %q", campaignPath, got, selectedID)
}
}
loaded, err := config.LoadPipelineCampaign(pipelinePath, pipeline, campaignPath, campaign)
if err != nil {
return nil, err
}
if err := validateInspectionPipeline(loaded.PipelinePath, loaded.Pipeline); err != nil {
return nil, err
}
if err := validateInspectionCampaign(loaded.CampaignPath, loaded.Campaign); err != nil {
return nil, err
}
return &inspectionConfig{
PipelinePath: loaded.PipelinePath,
Pipeline: loaded.Pipeline,
CampaignPath: loaded.CampaignPath,
Campaign: loaded.Campaign,
Party: loaded.Party,
}, nil
}
func pipelineHasArtifactFamilies(pipeline *config.PipelineConfig) bool {
return pipeline != nil && pipeline.Scriptorium != nil && len(pipeline.Scriptorium.ArtifactFamilies) != 0
}
func validateInspectionPipeline(path string, pipeline *config.PipelineConfig) error {
if err := config.ValidatePipelineConfig(pipeline); err != nil {
return fmt.Errorf("pipeline config %q invalid: %w", path, err)
}
return nil
}
func validateInspectionCampaign(path string, campaign *config.CampaignConfig) error {
if err := config.ValidateCampaignConfig(campaign); err != nil {
return fmt.Errorf("campaign config %q invalid: %w", path, err)
}
return nil
}
func inspectionRootPath(resolved *inspectionConfig) string {
if resolved == nil {
return ""
}
if root := config.EffectivePipelineRootPath(resolved.Pipeline); root != "" {
return root
}
return resolved.PipelinePath
}
func inspectionOverlay(pipeline *config.PipelineConfig) string {
if overlay, ok := config.SelectedPipelineOverlay(pipeline); ok {
return overlay.Name
}
return "none"
}
func writeConfigCommandUsage(out io.Writer) {
fmt.Fprintln(out, "Usage: narratio config <validate|show|sources|artifacts|diff>")
fmt.Fprintln(out)
fmt.Fprintln(out, "Use config validate to check an effective pipeline, config show to print normalized YAML, config sources to report ownership, config artifacts to list concrete artifacts, or config diff to compare two overlays.")
}
func writeInspectionSourceHeader(out io.Writer, resolved *inspectionConfig) error {
if _, err := fmt.Fprintf(out, "root: %s\n", inspectionRootPath(resolved)); err != nil {
return err
}
imports := config.EffectivePipelineImports(resolved.Pipeline)
if len(imports) == 0 {
if _, err := fmt.Fprintln(out, "imports: none"); err != nil {
return err
}
}
for _, imported := range imports {
if _, err := fmt.Fprintf(out, "import: %s\n", config.NormalizedConfigurationPath(imported)); err != nil {
return err
}
}
if overlay, ok := config.SelectedPipelineOverlay(resolved.Pipeline); ok {
if _, err := fmt.Fprintf(out, "overlay: name=%s selection=%s path=%s\n", overlay.Name, overlay.Source, config.NormalizedConfigurationPath(overlay.OverlayPath)); err != nil {
return err
}
} else if _, err := fmt.Fprintln(out, "overlay: none"); err != nil {
return err
}
if resolved.Campaign == nil {
if _, err := fmt.Fprintln(out, "campaign: none"); err != nil {
return err
}
if _, err := fmt.Fprintln(out, "party: none"); err != nil {
return err
}
} else {
if _, err := fmt.Fprintf(out, "campaign: id=%s source=%s\n", config.CampaignID(resolved.Campaign), config.NormalizedConfigurationPath(resolved.CampaignPath)); err != nil {
return err
}
if _, err := fmt.Fprintf(out, "party: source=%s\n", config.NormalizedConfigurationPath(resolved.Party.Source.Path)); err != nil {
return err
}
}
if _, err := fmt.Fprintf(out, "digest: %s\n", config.EffectivePipelineDigest(resolved.Pipeline)); err != nil {
return err
}
_, err := fmt.Fprintln(out, "path\trole\tsource")
return err
}
func sortInspectionSourceRecords(records []config.EffectivePipelineSourceRecord) {
sort.Slice(records, func(left, right int) bool {
if records[left].Path != records[right].Path {
return records[left].Path < records[right].Path
}
if records[left].Role != records[right].Role {
return records[left].Role < records[right].Role
}
return records[left].Source < records[right].Source
})
}

View File

@@ -4,58 +4,20 @@ import (
"bytes" "bytes"
"context" "context"
"io" "io"
"net/http"
"net/http/httptest"
"os" "os"
"path/filepath" "path/filepath"
"strings" "strings"
"testing" "testing"
configkit "gitea.maximumdirect.net/eric/ConfigKit"
"gitea.maximumdirect.net/eric/narratio/internal/config" "gitea.maximumdirect.net/eric/narratio/internal/config"
) )
func TestConfigCommandHelpAndDispatch(t *testing.T) {
for _, test := range []struct {
name string
args []string
want string
code int
}{
{name: "top level help", args: []string{"config", "--help"}, want: "Usage: narratio config <validate|show|sources|artifacts|diff>"},
{name: "validate help", args: []string{"config", "validate", "--help"}, want: "Usage: narratio config validate"},
{name: "show help", args: []string{"config", "show", "--help"}, want: "Usage: narratio config show"},
{name: "sources help", args: []string{"config", "sources", "--help"}, want: "Usage: narratio config sources"},
{name: "artifacts help", args: []string{"config", "artifacts", "--help"}, want: "Usage: narratio config artifacts"},
{name: "diff help", args: []string{"config", "diff", "--help"}, want: "Usage: narratio config diff"},
{name: "unknown", args: []string{"config", "unknown"}, want: `config: unknown subcommand "unknown"`, code: 1},
{name: "missing", args: []string{"config"}, want: "config: expected subcommand: validate|show|sources|artifacts|diff", code: 1},
{name: "session flag", args: []string{"config", "validate", "--session", "session.yml"}, want: "flag provided but not defined", code: 1},
{name: "stage flag", args: []string{"config", "show", "--from", "prepare"}, want: "flag provided but not defined", code: 1},
{name: "force flag", args: []string{"config", "show", "--force"}, want: "flag provided but not defined", code: 1},
{name: "artifact flag", args: []string{"config", "show", "--artifacts", "recap"}, want: "flag provided but not defined", code: 1},
{name: "retired selector", args: []string{"config", "validate", "--profile", "testing"}, want: "flag provided but not defined", code: 1},
} {
t.Run(test.name, func(t *testing.T) {
var stdout, stderr bytes.Buffer
code := Execute(test.args, &stdout, &stderr)
if code != test.code {
t.Fatalf("exit code = %d, want %d; stdout=%q stderr=%q", code, test.code, stdout.String(), stderr.String())
}
combined := stdout.String() + stderr.String()
if !strings.Contains(combined, test.want) {
t.Fatalf("output = %q, want %q", combined, test.want)
}
})
}
}
func TestExecuteConfigUsesInvocationPipelineLoader(t *testing.T) { func TestExecuteConfigUsesInvocationPipelineLoader(t *testing.T) {
dir := t.TempDir() dir := t.TempDir()
pipelinePath := filepath.Join(dir, "pipeline.yml") pipelinePath := filepath.Join(dir, "pipeline.yml")
mustWriteTestFile(t, pipelinePath, "workspace:\n root: "+filepath.Join(dir, "workspace")+"\nwhisperx:\n transcribe_url: https://transcription.example.com/transcribe\n") mustWriteTestFile(t, pipelinePath, "workspace:\n root: "+filepath.Join(dir, "workspace")+"\nwhisperx:\n transcribe_url: https://transcription.example.com/transcribe\n")
for _, subcommand := range []string{"validate", "show", "sources", "artifacts"} { for _, subcommand := range []string{"validate", "show", "sources"} {
t.Run(subcommand, func(t *testing.T) { t.Run(subcommand, func(t *testing.T) {
calls := 0 calls := 0
deps := commandDependencies{ deps := commandDependencies{
@@ -82,408 +44,6 @@ func TestExecuteConfigUsesInvocationPipelineLoader(t *testing.T) {
} }
} }
func TestConfigValidateAndShowPipelineOnlyAreSideEffectFree(t *testing.T) {
dir := t.TempDir()
workspaceRoot := filepath.Join(dir, "workspace-does-not-exist")
pipelinePath := filepath.Join(dir, "pipeline.yml")
secretsDir := filepath.Join(dir, "secrets")
const secret = "inspection-secret-must-not-escape"
mustWriteTestFile(t, filepath.Join(secretsDir, "INSPECTION_SECRET"), secret+"\n")
calls := 0
server := httptest.NewServer(http.HandlerFunc(func(http.ResponseWriter, *http.Request) { calls++ }))
defer server.Close()
mustWriteTestFile(t, pipelinePath, `workspace:
root: `+workspaceRoot+`
whisperx:
transcribe_url: `+server.URL+`
`)
t.Setenv("INSPECTION_SECRET", secret)
var validateOut bytes.Buffer
if err := ConfigValidate(context.Background(), []string{"--config", pipelinePath}, &validateOut); err != nil {
t.Fatalf("ConfigValidate() error = %v", err)
}
if !strings.Contains(validateOut.String(), "Configuration valid: root=") || !strings.Contains(validateOut.String(), "; overlay=none; digest=") {
t.Fatalf("validate output = %q", validateOut.String())
}
var showOut bytes.Buffer
if err := ConfigShow(context.Background(), []string{"--config", pipelinePath}, &showOut); err != nil {
t.Fatalf("ConfigShow() error = %v", err)
}
show := showOut.String()
if !strings.HasSuffix(show, "\n") || !strings.Contains(show, "workspace:\n") || !strings.Contains(show, "root: "+workspaceRoot) {
t.Fatalf("show output = %q", show)
}
if strings.Contains(show, "artifact_families") || strings.Contains(show, "resolution") {
t.Fatalf("show output leaked resolution-only fields: %q", show)
}
if strings.Contains(show, secret) {
t.Fatalf("show output leaked a raw secret: %q", show)
}
var sourcesOut bytes.Buffer
if err := ConfigSources(context.Background(), []string{"--config", pipelinePath}, &sourcesOut); err != nil {
t.Fatalf("ConfigSources() error = %v", err)
}
if strings.Contains(sourcesOut.String(), secret) {
t.Fatalf("sources output leaked a raw secret: %q", sourcesOut.String())
}
writeInspectionOverlays(t, pipelinePath, "whisperx:\n language: en\n", "whisperx:\n language: fr\n")
var diffOut bytes.Buffer
if err := ConfigDiff(context.Background(), []string{"production", "testing", "--config", pipelinePath}, &diffOut); err != nil {
t.Fatalf("ConfigDiff() error = %v", err)
}
if strings.Contains(diffOut.String(), secret) {
t.Fatalf("diff output leaked a raw secret: %q", diffOut.String())
}
if calls != 0 {
t.Fatalf("inspection invoked configured external endpoint %d time(s)", calls)
}
if _, err := os.Stat(workspaceRoot); !os.IsNotExist(err) {
t.Fatalf("workspace root stat error = %v, want absent", err)
}
}
func TestConfigDiffReportsSemanticOverlayChanges(t *testing.T) {
workspaceRoot := t.TempDir()
pipelinePath, _, _ := writeValidConfigFiles(t, workspaceRoot)
writeInspectionOverlays(t, pipelinePath, `workspace:
cleanup_after_publish: true
publish:
upload_run: true
whisperx:
language: en
audita:
modules: [glossary, grammar]
scriptorium:
artifacts:
production_only:
enabled: false
output_path: artifacts/production.md
`, `workspace:
cleanup_after_publish: false
whisperx:
language: fr
audita:
modules: []
scriptorium:
artifacts:
testing_only:
enabled: false
output_path: artifacts/testing.md
`)
args := []string{"production", "testing", "--config", pipelinePath}
var first, second bytes.Buffer
if err := ConfigDiff(context.Background(), args, &first); err != nil {
t.Fatalf("ConfigDiff() error = %v", err)
}
if err := ConfigDiff(context.Background(), args, &second); err != nil {
t.Fatalf("second ConfigDiff() error = %v", err)
}
if first.String() != second.String() {
t.Fatalf("diff output is not deterministic:\nfirst=%q\nsecond=%q", first.String(), second.String())
}
output := first.String()
for _, want := range []string{
"changed\taudita.modules\t[\"glossary\",\"grammar\"]\t[]\n",
"changed\tworkspace.cleanup_after_publish\ttrue\tfalse\n",
"changed\twhisperx.language\t\"en\"\t\"fr\"\n",
"removed\tscriptorium.artifacts.production_only.enabled\tfalse\n",
"added\tscriptorium.artifacts.testing_only.enabled\tfalse\n",
} {
if !strings.Contains(output, want) {
t.Fatalf("diff output missing %q:\n%s", want, output)
}
}
if strings.Index(output, "audita.modules") > strings.Index(output, "workspace.cleanup_after_publish") {
t.Fatalf("diff records are not sorted by path:\n%s", output)
}
var reversed bytes.Buffer
if err := ConfigDiff(context.Background(), []string{"testing", "production", "--config", pipelinePath}, &reversed); err != nil {
t.Fatalf("reversed ConfigDiff() error = %v", err)
}
if !strings.Contains(reversed.String(), "changed\twhisperx.language\t\"fr\"\t\"en\"\n") {
t.Fatalf("reversed diff did not independently resolve overlays:\n%s", reversed.String())
}
}
func TestConfigShowPreservesNullAndEmptyCollections(t *testing.T) {
dir := t.TempDir()
pipelinePath := filepath.Join(dir, "pipeline.yml")
mustWriteTestFile(t, pipelinePath, `workspace:
root: /tmp/narratio-work
whisperx:
transcribe_url: https://transcription.example.test/transcribe
audita:
modules: null
scriptorium:
artifacts: null
`)
mustWriteTestFile(t, filepath.Join(dir, "overlays", "empty.yml"), `audita:
modules: []
scriptorium:
artifacts: {}
`)
var base, empty bytes.Buffer
if err := ConfigShow(context.Background(), []string{"--config", pipelinePath}, &base); err != nil {
t.Fatal(err)
}
if err := ConfigShow(context.Background(), []string{"--config", pipelinePath, "--overlay", "empty"}, &empty); err != nil {
t.Fatal(err)
}
for _, want := range []string{"modules: null\n", "artifacts: null\n"} {
if !strings.Contains(base.String(), want) {
t.Fatalf("base show output missing %q:\n%s", want, base.String())
}
}
for _, want := range []string{"modules: []\n", "artifacts: {}\n"} {
if !strings.Contains(empty.String(), want) {
t.Fatalf("empty-overlay show output missing %q:\n%s", want, empty.String())
}
}
var diff bytes.Buffer
if err := ConfigDiff(context.Background(), []string{"default", "empty", "--config", pipelinePath}, &diff); err != nil {
t.Fatal(err)
}
for _, want := range []string{
"changed\taudita.modules\tnull\t[]\n",
"changed\tscriptorium.artifacts\tnull\t{}\n",
} {
if !strings.Contains(diff.String(), want) {
t.Fatalf("diff output missing %q:\n%s", want, diff.String())
}
}
}
func TestConfigDiffComparesExpandedFamiliesAndPublishRules(t *testing.T) {
pipelinePath, campaignPath := writeInspectionFamilyConfig(t)
writeInspectionOverlays(t, pipelinePath, `scriptorium:
artifact_families:
character_note:
enabled: false
member_vars:
character_name: character.name
publish:
enabled: true
required: false
`, `scriptorium:
artifact_families:
character_note:
enabled: true
prompt_id: dnd.character_note
member_vars:
character_name: character.class_summary
publish:
enabled: true
required: true
`)
var out bytes.Buffer
if err := ConfigDiff(context.Background(), []string{
"production", "testing", "--config", pipelinePath, "--campaign-file", campaignPath,
}, &out); err != nil {
t.Fatalf("ConfigDiff() error = %v", err)
}
output := out.String()
for _, want := range []string{
"changed\tscriptorium.artifacts.character_note_arannis.enabled\tfalse\ttrue\n",
"changed\tscriptorium.artifacts.character_note_arannis.vars.character_name\t\"Arannis\"\t\"wizard\"\n",
"changed\tpublish.outputs\t",
} {
if !strings.Contains(output, want) {
t.Fatalf("family diff output missing %q:\n%s", want, output)
}
}
}
func TestConfigDiffReportsEqualityAndRejectsInvalidInput(t *testing.T) {
workspaceRoot := t.TempDir()
pipelinePath, campaignPath, _ := writeValidConfigFiles(t, workspaceRoot)
writeInspectionOverlays(t, pipelinePath, "whisperx:\n language: en\n", "whisperx:\n language: en\n")
var equal bytes.Buffer
if err := ConfigDiff(context.Background(), []string{"production", "testing", "--config", pipelinePath}, &equal); err != nil {
t.Fatalf("ConfigDiff() equal overlays error = %v", err)
}
if got := equal.String(); got != "no differences\n" {
t.Fatalf("equal diff output = %q", got)
}
for _, args := range [][]string{
{"production", "testing", "extra", "--config", pipelinePath},
{"production", "--config", pipelinePath},
{"production", "production", "--config", pipelinePath},
{"unknown", "testing", "--config", pipelinePath},
{"production", "testing", "--config", pipelinePath, "--overlay", "production"},
{"production", "testing", "--config", pipelinePath, "--config", pipelinePath},
{"production", "testing", "--config", pipelinePath, "--campaign", "sample-campaign", "--campaign-file", campaignPath},
} {
if err := ConfigDiff(context.Background(), args, io.Discard); err == nil {
t.Fatalf("ConfigDiff(%q) succeeded, want error", args)
}
}
}
func TestConfigDiffBootstrapsSecretsOnceForBothOverlays(t *testing.T) {
workspaceRoot := t.TempDir()
pipelinePath, _, _ := writeValidConfigFiles(t, workspaceRoot)
writeInspectionOverlays(t, pipelinePath, "whisperx:\n language: en\n", "whisperx:\n language: fr\n")
secretsDir := t.TempDir()
const secretName = "NARRATIO_DIFF_BOOTSTRAP_REPORT"
restoreEnvAfterTest(t, secretName)
if err := os.Unsetenv(secretName); err != nil {
t.Fatal(err)
}
mustWriteSecretFile(t, filepath.Join(secretsDir, secretName), "diff-secret-must-not-appear\n")
bootstrapCalls := 0
var diagnostics bytes.Buffer
deps := commandDependencies{loadSecretsDir: func(got string) (*configkit.SecretsReport, error) {
bootstrapCalls++
if got != secretsDir {
t.Fatalf("secrets directory = %q, want %q", got, secretsDir)
}
return configkit.LoadSecretsDir(got)
}, diagnostics: &diagnostics}
if err := configDiffWithDependencies(context.Background(), []string{
"production", "testing", "--config", pipelinePath, "--secrets-dir", secretsDir,
}, io.Discard, deps); err != nil {
t.Fatalf("config diff: %v", err)
}
if bootstrapCalls != 1 {
t.Fatalf("bootstrap calls = %d, want 1", bootstrapCalls)
}
if got := diagnostics.String(); strings.Count(got, `name="`+secretName+`"`) != 1 {
t.Fatalf("bootstrap report count = %d, want 1; diagnostics = %q", strings.Count(got, `name="`+secretName+`"`), got)
}
if strings.Contains(diagnostics.String(), "diff-secret-must-not-appear") {
t.Fatalf("bootstrap diagnostics exposed secret value: %q", diagnostics.String())
}
}
func TestConfigInspectionOutputsNeverExposeResolvedCredentialValues(t *testing.T) {
const firstCanary = "inspection-credential-canary-one"
const secondCanary = "inspection-credential-canary-two"
for name, value := range map[string]string{
"NARRATIO_INSPECT_ACCESS": firstCanary,
"NARRATIO_INSPECT_SECRET": firstCanary,
"NARRATIO_INSPECT_LLM_ONE": firstCanary,
"NARRATIO_INSPECT_LLM_TWO": secondCanary,
"NARRATIO_INSPECT_NOTARIUS_ONE": firstCanary,
"NARRATIO_INSPECT_NOTARIUS_TWO": secondCanary,
} {
t.Setenv(name, value)
}
workspaceRoot := t.TempDir()
pipelinePath, _, _ := writeValidConfigFiles(t, workspaceRoot)
pipelineData, err := os.ReadFile(pipelinePath)
if err != nil {
t.Fatal(err)
}
pipelineYAML := strings.Replace(string(pipelineData), " bucket: test-bucket\n", ` bucket: test-bucket
access_key_id: NARRATIO_INSPECT_ACCESS
secret_access_key: NARRATIO_INSPECT_SECRET
`, 1)
pipelineYAML += `notarius:
enabled: false
credentials: [NARRATIO_INSPECT_NOTARIUS_ONE]
`
if err := os.WriteFile(pipelinePath, []byte(pipelineYAML), 0o644); err != nil {
t.Fatal(err)
}
writeInspectionOverlays(t, pipelinePath,
"audita:\n proposal_profile: production\n credentials: [NARRATIO_INSPECT_LLM_ONE]\n",
"audita:\n proposal_profile: testing\n credentials: [NARRATIO_INSPECT_LLM_TWO]\nnotarius:\n credentials: [NARRATIO_INSPECT_NOTARIUS_TWO]\n",
)
mustWriteTestFile(t, filepath.Join(filepath.Dir(pipelinePath), "overlays", "without-notarius-key.yml"), "notarius:\n credentials: []\n")
var validate bytes.Buffer
if err := ConfigValidate(context.Background(), []string{"--config", pipelinePath, "--overlay", "production"}, &validate); err != nil {
t.Fatalf("config validate: %v", err)
}
var show bytes.Buffer
if err := ConfigShow(context.Background(), []string{"--config", pipelinePath, "--overlay", "production"}, &show); err != nil {
t.Fatalf("config show: %v", err)
}
var sources bytes.Buffer
if err := ConfigSources(context.Background(), []string{"--config", pipelinePath, "--overlay", "production"}, &sources); err != nil {
t.Fatalf("config sources: %v", err)
}
var catalog bytes.Buffer
if err := ConfigArtifacts(context.Background(), []string{"--config", pipelinePath, "--overlay", "production"}, &catalog); err != nil {
t.Fatalf("config artifacts: %v", err)
}
var diff bytes.Buffer
if err := ConfigDiff(context.Background(), []string{"production", "testing", "--config", pipelinePath}, &diff); err != nil {
t.Fatalf("config diff: %v", err)
}
var removed bytes.Buffer
if err := ConfigShow(context.Background(), []string{"--config", pipelinePath, "--overlay", "without-notarius-key"}, &removed); err != nil {
t.Fatalf("config show with removed Notarius credential: %v", err)
}
for label, output := range map[string]string{"show": show.String(), "sources": sources.String(), "artifacts": catalog.String(), "diff": diff.String()} {
if strings.Contains(output, firstCanary) || strings.Contains(output, secondCanary) {
t.Fatalf("%s output exposed credential value: %q", label, output)
}
}
for _, reference := range []string{"NARRATIO_INSPECT_ACCESS", "NARRATIO_INSPECT_SECRET", "NARRATIO_INSPECT_LLM_ONE", "NARRATIO_INSPECT_NOTARIUS_ONE"} {
if !strings.Contains(show.String(), reference) {
t.Fatalf("show omitted safe credential reference %q: %q", reference, show.String())
}
}
if !strings.Contains(diff.String(), "NARRATIO_INSPECT_LLM_ONE") || !strings.Contains(diff.String(), "NARRATIO_INSPECT_LLM_TWO") ||
!strings.Contains(diff.String(), "NARRATIO_INSPECT_NOTARIUS_ONE") || !strings.Contains(diff.String(), "NARRATIO_INSPECT_NOTARIUS_TWO") {
t.Fatalf("diff omitted safe credential references: %q", diff.String())
}
if !strings.Contains(sources.String(), "notarius.credentials") {
t.Fatalf("sources omitted Notarius credential ownership: %q", sources.String())
}
if strings.Contains(removed.String(), "NARRATIO_INSPECT_NOTARIUS_ONE") {
t.Fatalf("empty overlay did not remove Notarius credential: %q", removed.String())
}
}
func TestConfigValidateRejectsUnavailableNotariusCredential(t *testing.T) {
const envName = "NARRATIO_INSPECT_NOTARIUS_MISSING"
restoreEnvAfterTest(t, envName)
path := filepath.Join(t.TempDir(), "pipeline.yml")
mustWriteTestFile(t, path, "whisperx:\n transcribe_url: https://transcription.example.test/transcribe\nnotarius:\n enabled: false\n credentials: ["+envName+"]\n")
err := ConfigValidate(context.Background(), []string{"--config", path}, io.Discard)
if err == nil || !strings.Contains(err.Error(), "secret.unset") {
t.Fatalf("ConfigValidate() error = %v, want unavailable credential failure", err)
}
}
func TestConfigCommandsInspectMaintainedSplitBundleWithoutRuntimeState(t *testing.T) {
examplesDir := filepath.Join("..", "..", "examples")
pipelinePath := filepath.Join(examplesDir, "production-testing", "pipeline.yml")
campaignPath := filepath.Join(examplesDir, "campaigns", "sample-campaign", "campaign.yml")
workspacePath := filepath.Join(examplesDir, "production-testing", "workspace")
if _, err := os.Stat(workspacePath); !os.IsNotExist(err) {
t.Fatalf("example workspace stat = %v, want absent", err)
}
for _, command := range []func(context.Context, []string, io.Writer) error{ConfigValidate, ConfigShow, ConfigSources, ConfigArtifacts} {
if err := command(context.Background(), []string{"--config", pipelinePath, "--campaign-file", campaignPath}, io.Discard); err != nil {
t.Fatalf("inspection command %T error = %v", command, err)
}
}
var diff bytes.Buffer
if err := ConfigDiff(context.Background(), []string{"default", "testing", "--config", pipelinePath, "--campaign-file", campaignPath}, &diff); err != nil {
t.Fatalf("ConfigDiff() error = %v", err)
}
if !strings.Contains(diff.String(), "audita.proposal_profile") {
t.Fatalf("split bundle overlay diff = %q, want proposal profile change", diff.String())
}
if _, err := os.Stat(workspacePath); !os.IsNotExist(err) {
t.Fatalf("inspection created example workspace: %v", err)
}
}
func writeInspectionOverlays(t *testing.T, pipelinePath, production, testing string) { func writeInspectionOverlays(t *testing.T, pipelinePath, production, testing string) {
t.Helper() t.Helper()
overlaysDir := filepath.Join(filepath.Dir(pipelinePath), "overlays") overlaysDir := filepath.Join(filepath.Dir(pipelinePath), "overlays")
@@ -491,278 +51,6 @@ func writeInspectionOverlays(t *testing.T, pipelinePath, production, testing str
mustWriteTestFile(t, filepath.Join(overlaysDir, "testing.yml"), testing) mustWriteTestFile(t, filepath.Join(overlaysDir, "testing.yml"), testing)
} }
func TestConfigCommandsSelectOverlaysAndCampaigns(t *testing.T) {
workspaceRoot := t.TempDir()
pipelinePath, campaignPath, _ := writeValidConfigFiles(t, workspaceRoot)
enableCommandTestOverlays(t, pipelinePath)
var defaultOut bytes.Buffer
if err := ConfigValidate(context.Background(), []string{"--config", pipelinePath}, &defaultOut); err != nil {
t.Fatalf("default ConfigValidate() error = %v", err)
}
if !strings.Contains(defaultOut.String(), "overlay=none") {
t.Fatalf("default output = %q", defaultOut.String())
}
var explicitOut bytes.Buffer
if err := ConfigShow(context.Background(), []string{"--config", pipelinePath, "--overlay", "testing"}, &explicitOut); err != nil {
t.Fatalf("explicit ConfigShow() error = %v", err)
}
if !strings.Contains(explicitOut.String(), "language: fr") {
t.Fatalf("explicit show output = %q", explicitOut.String())
}
for _, args := range [][]string{
{"--config", pipelinePath, "--campaign", "sample-campaign"},
{"--config", pipelinePath, "--campaign-file", campaignPath},
} {
var out bytes.Buffer
if err := ConfigValidate(context.Background(), args, &out); err != nil {
t.Fatalf("ConfigValidate(%q) error = %v", args, err)
}
}
}
func TestConfigCommandsExpandFamiliesAndRequireCampaign(t *testing.T) {
pipelinePath, campaignPath := writeInspectionFamilyConfig(t)
for _, command := range []func(context.Context, []string, io.Writer) error{ConfigValidate, ConfigShow, ConfigArtifacts} {
var out bytes.Buffer
err := command(context.Background(), []string{"--config", pipelinePath}, &out)
if err == nil || !strings.Contains(err.Error(), "artifact_families requires a campaign") {
t.Fatalf("family command without campaign error = %v", err)
}
}
var show bytes.Buffer
if err := ConfigShow(context.Background(), []string{"--config", pipelinePath, "--campaign-file", campaignPath}, &show); err != nil {
t.Fatalf("ConfigShow() error = %v", err)
}
if !strings.Contains(show.String(), "character_note_arannis:") || strings.Contains(show.String(), "artifact_families") {
t.Fatalf("expanded show output = %q", show.String())
}
loadedPipeline, err := config.LoadPipeline(pipelinePath)
if err != nil {
t.Fatal(err)
}
loadedCampaign, err := config.LoadCampaign(campaignPath)
if err != nil {
t.Fatal(err)
}
loaded, err := config.LoadPipelineCampaign(pipelinePath, loadedPipeline, campaignPath, loadedCampaign)
if err != nil {
t.Fatal(err)
}
var validateOut bytes.Buffer
if err := ConfigValidate(context.Background(), []string{"--config", pipelinePath, "--campaign-file", campaignPath}, &validateOut); err != nil {
t.Fatal(err)
}
if !strings.Contains(validateOut.String(), "digest="+config.EffectivePipelineDigest(loaded.Pipeline)) {
t.Fatalf("inspection digest = %q, want %q", validateOut.String(), config.EffectivePipelineDigest(loaded.Pipeline))
}
}
func TestConfigValidateReportsCanonicalPartyAndImportErrors(t *testing.T) {
pipelinePath, campaignPath := writeInspectionFamilyConfig(t)
mustWriteTestFile(t, filepath.Join(filepath.Dir(campaignPath), "party.yml"), "schema_version: narratio.party.v2\ncharacters: {}\n")
if err := ConfigValidate(context.Background(), []string{"--config", pipelinePath, "--campaign-file", campaignPath}, io.Discard); err == nil || !strings.Contains(err.Error(), "unsupported") {
t.Fatalf("canonical party error = %v", err)
}
dir := t.TempDir()
rootPath := filepath.Join(dir, "pipeline.yml")
mustWriteTestFile(t, rootPath, `configkit:
imports:
- path: conf.yml
workspace:
root: /one
whisperx:
transcribe_url: https://transcription.example.com/transcribe
`)
mustWriteTestFile(t, filepath.Join(dir, "conf.yml"), "workspace:\n root: /two\n")
err := ConfigValidate(context.Background(), []string{"--config", rootPath}, io.Discard)
if err == nil || !strings.Contains(err.Error(), "/workspace/root") || !strings.Contains(err.Error(), "pipeline.yml") || !strings.Contains(err.Error(), "conf.yml") {
t.Fatalf("import diagnostic = %v", err)
}
}
func TestConfigSourcesReportsStableOwnership(t *testing.T) {
workspaceRoot := t.TempDir()
pipelinePath, campaignPath, _ := writeValidConfigFiles(t, workspaceRoot)
enableCommandTestOverlays(t, pipelinePath)
args := []string{"--config", pipelinePath, "--campaign-file", campaignPath, "--overlay", "testing"}
var first, second bytes.Buffer
if err := ConfigSources(context.Background(), args, &first); err != nil {
t.Fatalf("first ConfigSources() error = %v", err)
}
if err := ConfigSources(context.Background(), args, &second); err != nil {
t.Fatalf("second ConfigSources() error = %v", err)
}
if first.String() != second.String() {
t.Fatalf("sources output is not deterministic:\nfirst=%q\nsecond=%q", first.String(), second.String())
}
output := first.String()
for _, want := range []string{
"root: ",
"imports: none",
"overlay: name=testing selection=explicit path=",
"campaign: id=sample-campaign source=",
"party: source=",
"digest: ",
"path\trole\tsource\n",
"workspace.root\troot\t",
"whisperx.language\toverlay\t",
"derived.players\tparty\t",
"trim.enabled\tdefault\tdefault",
} {
if !strings.Contains(output, want) {
t.Fatalf("sources output missing %q:\n%s", want, output)
}
}
}
func TestConfigSourcesReportsCanonicalFamilyAndPublishOrigins(t *testing.T) {
pipelinePath, campaignPath := writeInspectionFamilyConfig(t)
var out bytes.Buffer
if err := ConfigSources(context.Background(), []string{"--config", pipelinePath, "--campaign-file", campaignPath}, &out); err != nil {
t.Fatalf("ConfigSources() error = %v", err)
}
output := out.String()
partyPath := filepath.Join(filepath.Dir(campaignPath), "party.yml")
for _, want := range []string{
"party: source=" + partyPath,
"derived.players\tparty\t" + partyPath,
"scriptorium.artifacts.character_note_arannis.enabled\tfamily\t" + pipelinePath,
"scriptorium.artifacts.character_note_arannis.enabled\tparty\t" + partyPath,
"scriptorium.artifacts.character_note_arannis.depends_on\tfamily\t" + pipelinePath,
"scriptorium.artifacts.character_note_arannis.inputs.prior.source\tparty\t" + partyPath,
"publish.outputs[",
"\tfamily\t" + pipelinePath,
"\tparty\t" + partyPath,
} {
if !strings.Contains(output, want) {
t.Fatalf("sources output missing %q:\n%s", want, output)
}
}
}
func TestConfigSourcesPreservesOverlayOwnershipThroughFamilyExpansion(t *testing.T) {
pipelinePath, campaignPath := writeInspectionFamilyConfig(t)
overlayPath := filepath.Join(filepath.Dir(pipelinePath), "overlays", "testing.yml")
mustWriteTestFile(t, overlayPath, `scriptorium:
artifact_families:
character_note:
enabled: true
prompt_id: dnd.character_note
`)
var out bytes.Buffer
if err := ConfigSources(context.Background(), []string{"--config", pipelinePath, "--campaign-file", campaignPath, "--overlay", "testing"}, &out); err != nil {
t.Fatalf("ConfigSources() error = %v", err)
}
want := "scriptorium.artifacts.character_note_arannis.enabled\tfamily\t" + overlayPath
if !strings.Contains(out.String(), want) {
t.Fatalf("sources output missing overlay-generated ownership %q:\n%s", want, out.String())
}
}
func TestConfigSourcesAttributesInferredArtifactDependencies(t *testing.T) {
dir := t.TempDir()
pipelinePath := filepath.Join(dir, "pipeline.yml")
inputPath := filepath.Join(dir, "input-only.yml")
overlayPath := filepath.Join(dir, "overlays", "testing.yml")
mustWriteTestFile(t, pipelinePath, `configkit:
imports:
- path: input-only.yml
workspace:
root: /srv/narratio
whisperx:
transcribe_url: https://transcription.example.test/transcribe
scriptorium:
artifacts:
first:
enabled: false
output_path: artifacts/first.md
second:
enabled: false
output_path: artifacts/second.md
mixed:
enabled: false
output_path: artifacts/mixed.md
depends_on: [first]
`)
mustWriteTestFile(t, inputPath, `scriptorium:
artifacts:
input_only:
enabled: false
output_path: artifacts/input-only.md
inputs:
prior:
source: narratio.artifact.first
`)
mustWriteTestFile(t, overlayPath, `scriptorium:
artifacts:
mixed:
inputs:
prior:
source: narratio.artifact.second
`)
var out bytes.Buffer
if err := ConfigSources(context.Background(), []string{"--config", pipelinePath, "--overlay", "testing"}, &out); err != nil {
t.Fatal(err)
}
for _, want := range []string{
"scriptorium.artifacts.input_only.depends_on\timport\t" + inputPath,
"scriptorium.artifacts.mixed.depends_on\troot\t" + pipelinePath,
"scriptorium.artifacts.mixed.depends_on\toverlay\t" + overlayPath,
} {
if !strings.Contains(out.String(), want) {
t.Fatalf("sources output missing dependency contributor %q:\n%s", want, out.String())
}
}
if strings.Contains(out.String(), "scriptorium.artifacts.input_only.depends_on\tdefault\tdefault") {
t.Fatalf("inferred dependency retained default attribution:\n%s", out.String())
}
}
func TestConfigSourcesReportsRootImportOverlayAndDefaultOwnership(t *testing.T) {
dir := t.TempDir()
rootPath := filepath.Join(dir, "pipeline.yml")
importPath := filepath.Join(dir, "base.yml")
overlayPath := filepath.Join(dir, "overlays", "testing.yml")
mustWriteTestFile(t, rootPath, `configkit:
imports:
- path: base.yml
workspace:
root: /srv/narratio
whisperx:
transcribe_url: https://transcription.example.com/transcribe
`)
mustWriteTestFile(t, importPath, "storage:\n backend: local\n")
mustWriteTestFile(t, overlayPath, "whisperx:\n language: fr\n")
var out bytes.Buffer
if err := ConfigSources(context.Background(), []string{"--config", rootPath, "--overlay", "testing"}, &out); err != nil {
t.Fatalf("ConfigSources() error = %v", err)
}
output := out.String()
for _, want := range []string{
"import: " + importPath,
"overlay: name=testing selection=explicit path=" + overlayPath,
"workspace.root\troot\t" + rootPath,
"storage.backend\timport\t" + importPath,
"whisperx.language\toverlay\t" + overlayPath,
"trim.enabled\tdefault\tdefault",
} {
if !strings.Contains(output, want) {
t.Fatalf("sources output missing %q:\n%s", want, output)
}
}
}
func writeInspectionFamilyConfig(t *testing.T) (string, string) { func writeInspectionFamilyConfig(t *testing.T) (string, string) {
t.Helper() t.Helper()
dir := t.TempDir() dir := t.TempDir()
@@ -813,3 +101,91 @@ characters:
`) `)
return pipelinePath, campaignPath return pipelinePath, campaignPath
} }
func TestNativeBundleInspectionAndExecutionAgree(t *testing.T) {
examples, err := filepath.Abs(filepath.Join("..", "..", "examples"))
if err != nil {
t.Fatal(err)
}
bundle := t.TempDir()
if err := os.CopyFS(bundle, os.DirFS(examples)); err != nil {
t.Fatal(err)
}
root := filepath.Join(bundle, "production-testing")
pipeline := filepath.Join(root, "narratio.yml")
if err := os.Rename(filepath.Join(root, "pipeline.yml"), pipeline); err != nil {
t.Fatal(err)
}
f, err := os.OpenFile(pipeline, os.O_APPEND|os.O_WRONLY, 0)
if err != nil {
t.Fatal(err)
}
if _, err := f.WriteString("\naudita:\n credentials: [NARRATIO_BUNDLE_TEST_KEY]\n"); err != nil {
t.Fatal(err)
}
if err := f.Close(); err != nil {
t.Fatal(err)
}
const secretName = "NARRATIO_BUNDLE_TEST_KEY"
const secretValue = "synthetic-bundle-secret"
restoreEnvAfterTest(t, secretName)
if err := os.Unsetenv(secretName); err != nil {
t.Fatal(err)
}
secrets := filepath.Join(bundle, "secrets")
mustWriteSecretFile(t, filepath.Join(secrets, secretName), secretValue)
t.Chdir(root)
campaign := filepath.Join(bundle, "campaigns", "sample-campaign", "campaign.yml")
common := []string{"--campaign-file", campaign, "--secrets-dir", secrets}
for _, operation := range []string{"validate", "show", "sources"} {
args := []string{"config", operation, "--secrets-dir", secrets}
out := nativeInspectionForTest(t, args)
if strings.Contains(out, secretValue) {
t.Fatalf("%s exposed credential value", operation)
}
if operation == "show" && !strings.Contains(out, "artifact_families") {
t.Fatal("native show omitted authored families")
}
}
catalog := nativeInspectionForTest(t, append([]string{"artifacts", "list", "--format", "json"}, common...))
if !strings.Contains(catalog, "character_meta_arannis") {
t.Fatal("domain catalog omitted concrete family member")
}
diff := nativeInspectionForTest(t, []string{"config", "diff", "--details", "--against-overlay", "testing", "--secrets-dir", secrets, "--format", "json"})
if !strings.Contains(diff, "/audita/proposal_profile") || strings.Contains(diff, secretValue) {
t.Fatalf("unexpected diff: %s", diff)
}
workspace := filepath.Join(root, "conf.d", "workspace")
if _, err := os.Stat(workspace); !os.IsNotExist(err) {
t.Fatalf("inspection created workspace: %v", err)
}
var execution *config.Config
executor := func(_ context.Context, cfg *config.Config, _ BoundedPlan, _ RunOptions) (*RunSummary, error) {
execution = cfg
return &RunSummary{SessionID: "2026-05-03"}, nil
}
runArgs := append([]string{"2026-05-03", "--session-file", filepath.Join(bundle, "session.local-audio.yml"), "--overlay", "testing"}, common...)
var plan bytes.Buffer
planArgs := append(append([]string{}, runArgs...), "--from", "prepare", "--through", "prepare")
if err := invokeNativeCommand(context.Background(), append([]string{"session", "plan"}, planArgs...), &plan); err != nil {
t.Fatal(err)
}
if report := decodeNativeReport[sessionPlanReport](t, plan.Bytes()); len(report.Stages) != 1 || report.Stages[0].Name != "prepare" || report.Stages[0].Action != "run" {
t.Fatalf("unexpected plan: %s", plan.String())
}
if _, err := os.Stat(workspace); !os.IsNotExist(err) {
t.Fatalf("plan created workspace: %v", err)
}
if err := invokeNativeCommandWith(context.Background(), append([]string{"run"}, runArgs...), io.Discard, executor, commandDependencies{}); err != nil {
t.Fatal(err)
}
if execution == nil || execution.Session.Inputs.AudioDir != filepath.Join(bundle, "audio") || execution.Campaign.Inputs.PartyFile != filepath.Join(bundle, "campaigns", "sample-campaign", "party.yml") {
t.Fatalf("execution did not resolve imported session and campaign resources: %+v", execution)
}
if execution.Pipeline.Audita.ProposalProfile != "narratio-testing-model-placeholder" {
t.Fatalf("execution did not use the inspected overlay: %q", execution.Pipeline.Audita.ProposalProfile)
}
if _, ok := execution.ArtifactCatalog.Artifacts["character_meta_arannis"]; !ok {
t.Fatal("execution did not expand the inspected party family")
}
}

View File

@@ -1,313 +0,0 @@
package app
import (
"context"
"errors"
"flag"
"fmt"
"io"
"sort"
"strings"
"gitea.maximumdirect.net/eric/narratio/internal/config"
)
type configDiffFlags struct {
pipelinePath singletonStringFlag
campaignPath singletonStringFlag
campaignFilePath singletonStringFlag
secretsDir singletonStringFlag
}
type configDiffRequest struct {
leftOverlay string
rightOverlay string
flags configDiffFlags
}
type configDiffResolved struct {
left *inspectionConfig
right *inspectionConfig
}
type configDiffRecord struct {
Kind string
Path string
Left string
Right string
}
// ConfigDiff compares two explicitly selected overlays through the same
// read-only configuration resolution boundary used by config validate, show,
// and sources. Differences describe normalized effective values rather than
// the layout of root, import, or overlay files.
func ConfigDiff(ctx context.Context, args []string, out io.Writer) error {
return configDiffWithDependencies(ctx, args, out, commandDependencies{})
}
func configDiffWithDependencies(_ context.Context, args []string, out io.Writer, deps commandDependencies) error {
request, err := parseConfigDiffRequest(args, out)
if err != nil {
if errors.Is(err, flag.ErrHelp) {
return nil
}
return err
}
resolved, err := resolveConfigDiff(request, deps)
if err != nil {
return fmt.Errorf("config diff: %w", err)
}
leftValues, err := config.EffectivePipelineValues(resolved.left.Pipeline)
if err != nil {
return fmt.Errorf("config diff: project left effective configuration: %w", err)
}
rightValues, err := config.EffectivePipelineValues(resolved.right.Pipeline)
if err != nil {
return fmt.Errorf("config diff: project right effective configuration: %w", err)
}
records, err := diffEffectivePipelineValues(leftValues, rightValues)
if err != nil {
return fmt.Errorf("config diff: %w", err)
}
leftDigest := config.EffectivePipelineDigest(resolved.left.Pipeline)
rightDigest := config.EffectivePipelineDigest(resolved.right.Pipeline)
if len(records) == 0 {
if leftDigest != rightDigest {
return fmt.Errorf("internal error: effective pipeline digests differ without a semantic difference")
}
_, err := fmt.Fprintln(out, "no differences")
return err
}
for _, record := range records {
switch record.Kind {
case "added":
if _, err := fmt.Fprintf(out, "added\t%s\t%s\n", record.Path, record.Right); err != nil {
return err
}
case "removed":
if _, err := fmt.Fprintf(out, "removed\t%s\t%s\n", record.Path, record.Left); err != nil {
return err
}
case "changed":
if _, err := fmt.Fprintf(out, "changed\t%s\t%s\t%s\n", record.Path, record.Left, record.Right); err != nil {
return err
}
default:
return fmt.Errorf("internal error: unsupported difference kind %q", record.Kind)
}
}
return nil
}
func parseConfigDiffRequest(args []string, out io.Writer) (configDiffRequest, error) {
overlays, flagArgs := splitConfigDiffArguments(args)
fs := flag.NewFlagSet("config diff", flag.ContinueOnError)
fs.SetOutput(out)
var request configDiffRequest
request.flags.pipelinePath.name = "config"
request.flags.campaignPath.name = "campaign"
request.flags.campaignFilePath.name = "campaign-file"
request.flags.secretsDir.name = "secrets-dir"
fs.Var(&request.flags.pipelinePath, "config", "path to pipeline.yml (optional; defaults searched)")
fs.Var(&request.flags.campaignPath, "campaign", "campaign ID")
fs.Var(&request.flags.campaignFilePath, "campaign-file", "path to campaign.yml")
fs.Var(&request.flags.secretsDir, "secrets-dir", "secrets directory (optional; defaults beside pipeline.yml)")
fs.Usage = func() {
fmt.Fprintln(out, "Usage: narratio config diff <left-overlay> <right-overlay> [--config <pipeline.yml>] [--campaign <id> | --campaign-file <campaign.yml>] [--secrets-dir <path>]")
fmt.Fprintln(out)
fmt.Fprintln(out, "Compares fully resolved overlays without a session, workspace, manifest, adapters, or external services.")
fmt.Fprintln(out)
fmt.Fprintln(out, "Flags:")
fs.PrintDefaults()
}
if err := fs.Parse(flagArgs); err != nil {
return configDiffRequest{}, fmt.Errorf("config diff: invalid flags: %w", err)
}
overlays = append(overlays, fs.Args()...)
if len(overlays) != 2 || strings.TrimSpace(overlays[0]) == "" || strings.TrimSpace(overlays[1]) == "" {
return configDiffRequest{}, fmt.Errorf("config diff: exactly two non-empty overlay names are required")
}
if overlays[0] == overlays[1] {
return configDiffRequest{}, fmt.Errorf("config diff: overlay names must differ")
}
if request.flags.campaignPath.set && request.flags.campaignFilePath.set {
return configDiffRequest{}, fmt.Errorf("config diff: --campaign and --campaign-file are mutually exclusive")
}
request.leftOverlay = overlays[0]
request.rightOverlay = overlays[1]
return request, nil
}
// splitConfigDiffArguments accepts the documented positional-first syntax and
// also permits flags before or between overlay names. Values belonging to the
// supported string flags stay with their flag so they are not mistaken for
// overlay names.
func splitConfigDiffArguments(args []string) (overlays, flagArgs []string) {
for index := 0; index < len(args); index++ {
argument := args[index]
if !strings.HasPrefix(argument, "-") || argument == "-" {
overlays = append(overlays, argument)
continue
}
flagArgs = append(flagArgs, argument)
name, hasValue := strings.CutPrefix(argument, "--")
if !hasValue {
continue
}
name, _, hasInlineValue := strings.Cut(name, "=")
if hasInlineValue || !configDiffStringFlag(name) || index+1 >= len(args) {
continue
}
index++
flagArgs = append(flagArgs, args[index])
}
return overlays, flagArgs
}
func configDiffStringFlag(name string) bool {
switch name {
case "config", "campaign", "campaign-file", "secrets-dir":
return true
default:
return false
}
}
func resolveConfigDiff(request configDiffRequest, deps commandDependencies) (*configDiffResolved, error) {
deps = normalizeCommandDependencies(deps)
pipelinePath, leftPipeline, err := loadPipelineConfigWithDependencies(request.flags.pipelinePath.value, config.PipelineLoadOptions{Overlay: &request.leftOverlay}, request.flags.secretsDir.pointer(), deps)
if err != nil {
return nil, fmt.Errorf("load left pipeline overlay: %w", err)
}
_, rightPipeline, err := loadPipelineConfigWithDependencies(request.flags.pipelinePath.value, config.PipelineLoadOptions{Overlay: &request.rightOverlay}, request.flags.secretsDir.pointer(), deps)
if err != nil {
return nil, fmt.Errorf("load right pipeline overlay: %w", err)
}
needsCampaign := pipelineHasArtifactFamilies(leftPipeline) || pipelineHasArtifactFamilies(rightPipeline)
hasCampaignSelection := request.flags.campaignPath.set || request.flags.campaignFilePath.set
if !needsCampaign && !hasCampaignSelection {
if err := validateInspectionPipeline(pipelinePath, leftPipeline); err != nil {
return nil, err
}
if err := validateInspectionPipeline(pipelinePath, rightPipeline); err != nil {
return nil, err
}
return &configDiffResolved{
left: &inspectionConfig{PipelinePath: pipelinePath, Pipeline: leftPipeline},
right: &inspectionConfig{PipelinePath: pipelinePath, Pipeline: rightPipeline},
}, nil
}
campaignPath, err := resolveSharedDiffCampaignPath(leftPipeline, rightPipeline, request.flags)
if err != nil {
if needsCampaign {
return nil, fmt.Errorf("pipeline.scriptorium.artifact_families requires one shared campaign: %w", err)
}
return nil, err
}
campaign, err := config.LoadCampaign(campaignPath)
if err != nil {
return nil, err
}
if request.flags.campaignPath.set && !request.flags.campaignFilePath.set {
if got := config.CampaignID(campaign); got != request.flags.campaignPath.value {
return nil, fmt.Errorf("campaign config %q invalid: campaign_id %q does not match selected campaign %q", campaignPath, got, request.flags.campaignPath.value)
}
}
leftLoaded, err := config.LoadPipelineCampaign(pipelinePath, leftPipeline, campaignPath, campaign)
if err != nil {
return nil, err
}
rightLoaded, err := config.LoadPipelineCampaignWithParty(pipelinePath, rightPipeline, campaignPath, campaign, leftLoaded.Party)
if err != nil {
return nil, err
}
if err := validateInspectionPipeline(leftLoaded.PipelinePath, leftLoaded.Pipeline); err != nil {
return nil, err
}
if err := validateInspectionPipeline(rightLoaded.PipelinePath, rightLoaded.Pipeline); err != nil {
return nil, err
}
if err := validateInspectionCampaign(campaignPath, campaign); err != nil {
return nil, err
}
return &configDiffResolved{
left: &inspectionConfig{
PipelinePath: leftLoaded.PipelinePath,
Pipeline: leftLoaded.Pipeline,
CampaignPath: leftLoaded.CampaignPath,
Campaign: campaign,
Party: leftLoaded.Party,
},
right: &inspectionConfig{
PipelinePath: rightLoaded.PipelinePath,
Pipeline: rightLoaded.Pipeline,
CampaignPath: rightLoaded.CampaignPath,
Campaign: campaign,
Party: rightLoaded.Party,
},
}, nil
}
func resolveSharedDiffCampaignPath(left, right *config.PipelineConfig, flags configDiffFlags) (string, error) {
leftPath, leftErr := resolveCampaignConfigPath(left, flags.campaignPath.value, flags.campaignFilePath.value)
if leftErr != nil {
return "", leftErr
}
rightPath, rightErr := resolveCampaignConfigPath(right, flags.campaignPath.value, flags.campaignFilePath.value)
if rightErr != nil {
return "", rightErr
}
if leftPath != rightPath {
return "", fmt.Errorf("overlay selections resolve different campaign files; specify --campaign-file to compare one campaign")
}
return leftPath, nil
}
func diffEffectivePipelineValues(left, right []config.EffectivePipelineValueRecord) ([]configDiffRecord, error) {
leftByPath, err := effectivePipelineValueMap("left", left)
if err != nil {
return nil, err
}
rightByPath, err := effectivePipelineValueMap("right", right)
if err != nil {
return nil, err
}
paths := make([]string, 0, len(leftByPath)+len(rightByPath))
seen := make(map[string]struct{}, len(leftByPath)+len(rightByPath))
for path := range leftByPath {
seen[path] = struct{}{}
paths = append(paths, path)
}
for path := range rightByPath {
if _, exists := seen[path]; !exists {
paths = append(paths, path)
}
}
sort.Strings(paths)
records := make([]configDiffRecord, 0)
for _, path := range paths {
leftValue, leftExists := leftByPath[path]
rightValue, rightExists := rightByPath[path]
switch {
case !leftExists:
records = append(records, configDiffRecord{Kind: "added", Path: path, Right: rightValue})
case !rightExists:
records = append(records, configDiffRecord{Kind: "removed", Path: path, Left: leftValue})
case leftValue != rightValue:
records = append(records, configDiffRecord{Kind: "changed", Path: path, Left: leftValue, Right: rightValue})
}
}
return records, nil
}
func effectivePipelineValueMap(side string, records []config.EffectivePipelineValueRecord) (map[string]string, error) {
values := make(map[string]string, len(records))
for _, record := range records {
if _, exists := values[record.Path]; exists {
return nil, fmt.Errorf("internal error: %s effective configuration has duplicate path %q", side, record.Path)
}
values[record.Path] = record.Value
}
return values, nil
}

Some files were not shown because too many files have changed in this diff Show More