Compare commits
97 Commits
d53a64650b
...
main
| Author | SHA1 | Date | |
|---|---|---|---|
| b47cb35966 | |||
| 39b4bddbc9 | |||
| 7e45ffca43 | |||
| 672b7f0ebd | |||
| f44078724a | |||
| af6cf8b6f1 | |||
| 7e65c29a61 | |||
| 846f8470dc | |||
| 32ff928786 | |||
| 25c59ff62f | |||
| 38866110a7 | |||
| 65d24fb88f | |||
| 8be65fd3a1 | |||
| 0117f3f35d | |||
| 0e9cbc9c2a | |||
| faa8cb5822 | |||
| 7db626781e | |||
| c523def852 | |||
| c7a5ff316d | |||
| a6c6f1e4ab | |||
| 85df36a770 | |||
| 6b7a0847d4 | |||
| e44247b5b1 | |||
| 97cced5d88 | |||
| 0238f82847 | |||
| ed29bdc473 | |||
| c3c6849bed | |||
| 1e67c429b7 | |||
| b537cb38ae | |||
| 065a615e5f | |||
| 6900cad104 | |||
| c3e6245416 | |||
| 16a4f7ee12 | |||
| a3c58141a0 | |||
| 86692d58f9 | |||
| bcbfc0fa4a | |||
| e476c08ea4 | |||
| 8824ce330f | |||
| 87142508e3 | |||
| 7cc877ea7f | |||
| 7ee362f1c3 | |||
| 084e6d178b | |||
| 86ec48d2e4 | |||
| 3868822277 | |||
| d83c5f0062 | |||
| 981eb6be8f | |||
| 6b027873a5 | |||
| d00cc8037d | |||
| b4b618a913 | |||
| 8ba001750e | |||
| fa9ed78a6d | |||
| 4dae8e0d36 | |||
| 35eaefd05d | |||
| f85f93bdfb | |||
| 0e34ea1d48 | |||
| 97a93d3393 | |||
| 435ec79185 | |||
| 33d2ebf44c | |||
| e93fb8d5ab | |||
| 69dc5cc8ec | |||
| 5d62f9a88b | |||
| ba9079ee74 | |||
| 583c5bdf1b | |||
| bccf03a99f | |||
| 39a958675d | |||
| 413b0d7134 | |||
| ff4bdaa483 | |||
| ebcc5b32a0 | |||
| ce661252d0 | |||
| ed7e722077 | |||
| bcfca7a044 | |||
| 05f5607968 | |||
| 1657c9f65d | |||
| c3023cb609 | |||
| 6593ccbeaf | |||
| 341fe93e3b | |||
| 65d0e518e5 | |||
| 4a0e3c83db | |||
| f5451a0cf5 | |||
| 381668568f | |||
| 8afb49c018 | |||
| 535f47ef20 | |||
| dcb9bae215 | |||
| f1f71d8cdf | |||
| 39af6ef941 | |||
| e1c934a492 | |||
| dd760d84e0 | |||
| 6db49b3949 | |||
| f1672f6f95 | |||
| 428f435734 | |||
| c4abdc19df | |||
| 08327c2e63 | |||
| 2850498043 | |||
| fe9817f354 | |||
| 40cbf42438 | |||
| 44a318694b | |||
| 9389f69eb0 |
@@ -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:
|
||||||
|
|||||||
@@ -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 ./...
|
||||||
|
|||||||
@@ -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:
|
||||||
- |
|
- |
|
||||||
|
|||||||
@@ -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
|
||||||
|
|||||||
@@ -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
56
cmd/narratio/main_test.go
Normal 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)
|
||||||
|
}
|
||||||
|
})
|
||||||
|
}
|
||||||
|
}
|
||||||
84
docs/adr/0001-classify-session-content.md
Normal file
84
docs/adr/0001-classify-session-content.md
Normal 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.
|
||||||
76
docs/adr/0002-assign-subprocess-content-ownership.md
Normal file
76
docs/adr/0002-assign-subprocess-content-ownership.md
Normal 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.
|
||||||
38
docs/adr/0003-assign-configuration-ownership.md
Normal file
38
docs/adr/0003-assign-configuration-ownership.md
Normal 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.
|
||||||
808
docs/cli.md
808
docs/cli.md
@@ -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).
|
|
||||||
|
|||||||
273
docs/config.md
273
docs/config.md
@@ -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 |
|
||||||
|
|||||||
@@ -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
|
||||||
|
|
||||||
|
|||||||
@@ -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
|
||||||
|
|||||||
@@ -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;
|
||||||
|
|||||||
@@ -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
|
||||||
|
|||||||
@@ -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
|
||||||
|
|||||||
@@ -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;
|
||||||
|
|||||||
@@ -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.
|
|
||||||
|
|||||||
@@ -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`
|
||||||
|
|||||||
@@ -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`.
|
||||||
|
|||||||
@@ -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
|
||||||
|
|||||||
@@ -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
|
||||||
|
|||||||
@@ -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
|
||||||
|
|
||||||
|
|||||||
@@ -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
|
||||||
|
|||||||
@@ -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
|
||||||
|
|||||||
@@ -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.
|
||||||
|
|||||||
@@ -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
|
||||||
|
|
||||||
|
|||||||
@@ -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
|
||||||
|
|
||||||
|
|||||||
@@ -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.
|
||||||
|
|
||||||
|
|||||||
@@ -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
|
||||||
|
|
||||||
|
|||||||
@@ -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
|
||||||
|
|
||||||
|
|||||||
@@ -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
|
||||||
|
|||||||
@@ -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;
|
||||||
|
|||||||
@@ -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
|
||||||
|
|
||||||
|
|||||||
@@ -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:
|
||||||
|
|||||||
@@ -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
40
docs/releases/v3.1.0.md
Normal 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
175
docs/roadmap/audita.md
Normal 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
280
docs/roadmap/workspace.md
Normal 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.
|
||||||
@@ -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.
|
||||||
|
|
||||||
|
|||||||
@@ -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.
|
||||||
|
|||||||
@@ -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
|
|
||||||
|
|||||||
12
examples/campaigns/sample-campaign/fragments/brenna.yml
Normal file
12
examples/campaigns/sample-campaign/fragments/brenna.yml
Normal 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
|
||||||
7
examples/campaigns/sample-campaign/fragments/inputs.yml
Normal file
7
examples/campaigns/sample-campaign/fragments/inputs.yml
Normal 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
|
||||||
@@ -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
|
|
||||||
|
|||||||
@@ -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
|
||||||
|
|||||||
@@ -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
|
||||||
|
|||||||
@@ -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
|
|
||||||
|
|||||||
@@ -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
|
|
||||||
|
|||||||
@@ -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
|
|
||||||
|
|||||||
@@ -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
|
|
||||||
|
|||||||
@@ -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:
|
||||||
|
|||||||
@@ -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
|
||||||
|
|||||||
2
examples/session-inputs/local-audio.yml
Normal file
2
examples/session-inputs/local-audio.yml
Normal file
@@ -0,0 +1,2 @@
|
|||||||
|
inputs:
|
||||||
|
audio_dir: ../audio
|
||||||
@@ -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
11
go.mod
@@ -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
22
go.sum
@@ -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=
|
||||||
|
|||||||
@@ -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"
|
||||||
)
|
)
|
||||||
|
|||||||
@@ -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"
|
||||||
)
|
)
|
||||||
|
|
||||||
|
|||||||
@@ -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.
|
||||||
|
|||||||
@@ -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"
|
||||||
|
|||||||
@@ -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"
|
||||||
)
|
)
|
||||||
|
|
||||||
|
|||||||
@@ -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
|
||||||
|
|||||||
@@ -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
|
||||||
}
|
}
|
||||||
|
|
||||||
|
|||||||
@@ -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,
|
||||||
|
|||||||
@@ -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")
|
||||||
|
|||||||
@@ -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"
|
||||||
)
|
)
|
||||||
|
|
||||||
|
|||||||
@@ -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
|
||||||
|
|||||||
@@ -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) {
|
||||||
|
|||||||
@@ -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}
|
||||||
|
|||||||
@@ -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()
|
||||||
|
|
||||||
|
|||||||
@@ -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)
|
||||||
|
|||||||
@@ -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
|
||||||
|
|||||||
84
internal/app/artifact_catalog_command.go
Normal file
84
internal/app/artifact_catalog_command.go
Normal 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
|
||||||
|
}
|
||||||
119
internal/app/artifact_inspection.go
Normal file
119
internal/app/artifact_inspection.go
Normal 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
|
||||||
|
}
|
||||||
@@ -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 {
|
||||||
@@ -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"}) {
|
||||||
|
|||||||
@@ -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
|
|
||||||
}
|
|
||||||
@@ -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)
|
|
||||||
}
|
|
||||||
})
|
|
||||||
}
|
|
||||||
}
|
}
|
||||||
|
|||||||
@@ -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
|
||||||
}
|
}
|
||||||
|
|||||||
@@ -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())
|
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
|
|||||||
244
internal/app/catalog_execution_test.go
Normal file
244
internal/app/catalog_execution_test.go
Normal 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)
|
||||||
|
}
|
||||||
@@ -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)
|
||||||
}
|
}
|
||||||
|
|||||||
240
internal/app/clean_command.go
Normal file
240
internal/app/clean_command.go
Normal 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
|
||||||
|
}
|
||||||
98
internal/app/clean_command_test.go
Normal file
98
internal/app/clean_command_test.go
Normal 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"))
|
||||||
|
}
|
||||||
@@ -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())
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|||||||
@@ -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)
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
|
|||||||
@@ -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{}
|
||||||
|
|||||||
91
internal/app/command_outcome.go
Normal file
91
internal/app/command_outcome.go
Normal 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
|
||||||
|
}
|
||||||
56
internal/app/command_reporting.go
Normal file
56
internal/app/command_reporting.go
Normal 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
|
||||||
|
}
|
||||||
173
internal/app/command_reporting_test.go
Normal file
173
internal/app/command_reporting_test.go
Normal 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")
|
||||||
|
}
|
||||||
|
}
|
||||||
44
internal/app/command_selection.go
Normal file
44
internal/app/command_selection.go
Normal 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 }
|
||||||
30
internal/app/command_test_helpers_test.go
Normal file
30
internal/app/command_test_helpers_test.go
Normal 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
|
||||||
|
}
|
||||||
@@ -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, "|"))
|
|
||||||
}
|
}
|
||||||
|
|||||||
235
internal/app/commands_boundary_test.go
Normal file
235
internal/app/commands_boundary_test.go
Normal 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())
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
@@ -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)
|
||||||
|
|||||||
@@ -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 }
|
|
||||||
|
|||||||
@@ -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
|
|
||||||
})
|
|
||||||
}
|
|
||||||
@@ -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")
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|||||||
@@ -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
Reference in New Issue
Block a user