From ff4bdaa483276684140e25110ca3f0a38416c3d2 Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Tue, 17 Nov 2026 22:38:51 +0000 Subject: [PATCH] Demonstrate native configuration authoring --- docs/roadmap/implementation.md | 2 +- examples/README.md | 16 ++++-- .../campaigns/sample-campaign/campaign.yml | 11 ++-- .../sample-campaign/fragments/brenna.yml | 12 +++++ .../sample-campaign/fragments/inputs.yml | 7 +++ examples/campaigns/sample-campaign/party.yml | 17 ++----- .../artifact-families/character_items.yml | 38 +++++++------- .../artifact-families/character_meta.yml | 24 ++++----- .../artifacts/player_handout.yml | 19 +++---- .../artifacts/session_recap.yml | 19 +++---- .../production-testing/overlays/testing.yml | 12 +++++ examples/production-testing/pipeline.yml | 20 ++++++-- examples/session-inputs/local-audio.yml | 2 + examples/session.local-audio.yml | 6 ++- internal/config/collection_authoring_test.go | 50 +++++++++++++++++++ internal/config/load_validate_test.go | 22 ++++++++ 16 files changed, 191 insertions(+), 86 deletions(-) create mode 100644 examples/campaigns/sample-campaign/fragments/brenna.yml create mode 100644 examples/campaigns/sample-campaign/fragments/inputs.yml create mode 100644 examples/session-inputs/local-audio.yml create mode 100644 internal/config/collection_authoring_test.go diff --git a/docs/roadmap/implementation.md b/docs/roadmap/implementation.md index 0956da7..220c5ec 100644 --- a/docs/roadmap/implementation.md +++ b/docs/roadmap/implementation.md @@ -339,7 +339,7 @@ contributors, optional empty imports, atomic lists, and pointer escaping in allowed dynamic mapping keys. Inspection remains secret-safe and read-only, without source reparsing or provenance-based acceptance gates. -## Stage 10: Exercise native authoring and maintain ergonomic examples +## Stage 10: Exercise native authoring and maintain ergonomic examples [x] Read the production/testing bundle, artifact/family tests, native destinations and collection rules, and maintained example tests. diff --git a/examples/README.md b/examples/README.md index 532012f..b488207 100644 --- a/examples/README.md +++ b/examples/README.md @@ -12,13 +12,17 @@ in the [configuration reference](../docs/config.md). - [Production-shaped pipeline](pipeline.production.yml): S3 storage, publish, external tools, and configured Scriptorium artifacts. - [Production-base/testing-overlay bundle](production-testing/pipeline.yml): - explicit `conf.d` imports, one ordinary artifact per `artifacts/.yml`, - one family per `artifact-families/.yml`, and the fixed + explicit required `conf.d` imports, an optional local import, destination-mounted + artifact files, a YAML-filtered directory of keyed families, and the fixed `overlays/testing.yml` overlay. Production values live in the base. The bundle demonstrates an input-only artifact dependency, two character families sharing the campaign party, and a testing-only disabled artifact. The testing 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 @@ -45,7 +49,9 @@ with the sample campaign and a compatible local- or S3-audio session. - [Sample campaign](campaigns/sample-campaign/campaign.yml), 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 [S3-audio session](session.s3-audio.yml) are concrete session files. - [Session template](session.template.yml) and the campaign-local equivalent @@ -78,8 +84,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) for maintained downstream configuration examples. -For a deployed bundle, keep credential files out of source control in a -`secrets/` directory beside the root `pipeline.yml`, one file per referenced +For a deployed bundle, keep credential files out of source control in the +conventional `/usr/local/etc/narratio/secrets` directory, one file per referenced environment-variable name, or select another directory with `--secrets-dir`. Static S3 credentials are optional: omit both S3 credential references to use the AWS SDK discovery chain. diff --git a/examples/campaigns/sample-campaign/campaign.yml b/examples/campaigns/sample-campaign/campaign.yml index 454bded..560807d 100644 --- a/examples/campaigns/sample-campaign/campaign.yml +++ b/examples/campaigns/sample-campaign/campaign.yml @@ -1,8 +1,5 @@ +config: + imports: + - path: fragments/inputs.yml + required: true 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 diff --git a/examples/campaigns/sample-campaign/fragments/brenna.yml b/examples/campaigns/sample-campaign/fragments/brenna.yml new file mode 100644 index 0000000..437f9b2 --- /dev/null +++ b/examples/campaigns/sample-campaign/fragments/brenna.yml @@ -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 diff --git a/examples/campaigns/sample-campaign/fragments/inputs.yml b/examples/campaigns/sample-campaign/fragments/inputs.yml new file mode 100644 index 0000000..51cd76a --- /dev/null +++ b/examples/campaigns/sample-campaign/fragments/inputs.yml @@ -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 diff --git a/examples/campaigns/sample-campaign/party.yml b/examples/campaigns/sample-campaign/party.yml index ad3a9d0..3078549 100644 --- a/examples/campaigns/sample-campaign/party.yml +++ b/examples/campaigns/sample-campaign/party.yml @@ -1,4 +1,9 @@ schema_version: narratio.party.v1 +config: + imports: + - path: fragments/brenna.yml + destination: [characters] + required: true characters: arannis: @@ -12,15 +17,3 @@ characters: classes: - name: wizard level: 8 - brenna: - player: - name: Rowan Hale - character: - name: Brenna - alias: - - Shield of Dawn - classes: - - name: paladin - level: 6 - - name: warlock - level: 2 diff --git a/examples/production-testing/artifact-families/character_items.yml b/examples/production-testing/artifact-families/character_items.yml index ff17a00..9a0cd73 100644 --- a/examples/production-testing/artifact-families/character_items.yml +++ b/examples/production-testing/artifact-families/character_items.yml @@ -1,20 +1,18 @@ -scriptorium: - artifact_families: - character_items: - enabled: true - for_each: party.characters - prompt_id: dnd.character_items - profile_id: production-placeholder - output_path_pattern: artifacts/characters/{character_id}/items.md - inputs: - character_meta: - source: narratio.member_artifact.character_meta - required: true - member_vars: - character_id: character_id - character_name: character.name - aliases: character.alias_summary - publish: - enabled: true - required: false - dest_pattern: artifacts/characters/{character_id}/items.md +character_items: + enabled: true + for_each: party.characters + prompt_id: dnd.character_items + profile_id: production-placeholder + output_path_pattern: artifacts/characters/{character_id}/items.md + inputs: + character_meta: + source: narratio.member_artifact.character_meta + required: true + member_vars: + character_id: character_id + character_name: character.name + aliases: character.alias_summary + publish: + enabled: true + required: false + dest_pattern: artifacts/characters/{character_id}/items.md diff --git a/examples/production-testing/artifact-families/character_meta.yml b/examples/production-testing/artifact-families/character_meta.yml index 8f2c825..b95e552 100644 --- a/examples/production-testing/artifact-families/character_meta.yml +++ b/examples/production-testing/artifact-families/character_meta.yml @@ -1,13 +1,11 @@ -scriptorium: - artifact_families: - character_meta: - enabled: true - for_each: party.characters - prompt_id: dnd.character_meta - profile_id: production-placeholder - output_path_pattern: artifacts/characters/{character_id}/meta.md - member_vars: - character_id: character_id - character_name: character.name - player_name: player.name - class_summary: character.class_summary +character_meta: + enabled: true + for_each: party.characters + prompt_id: dnd.character_meta + profile_id: production-placeholder + output_path_pattern: artifacts/characters/{character_id}/meta.md + member_vars: + character_id: character_id + character_name: character.name + player_name: player.name + class_summary: character.class_summary diff --git a/examples/production-testing/artifacts/player_handout.yml b/examples/production-testing/artifacts/player_handout.yml index 857cbfc..ab27a64 100644 --- a/examples/production-testing/artifacts/player_handout.yml +++ b/examples/production-testing/artifacts/player_handout.yml @@ -1,11 +1,8 @@ -scriptorium: - artifacts: - player_handout: - enabled: true - prompt_id: dnd.player_handout - profile_id: production-placeholder - output_path: artifacts/player-handout.md - inputs: - recap: - source: narratio.artifact.session_recap - required: true +enabled: true +prompt_id: dnd.player_handout +profile_id: production-placeholder +output_path: artifacts/player-handout.md +inputs: + recap: + source: narratio.artifact.session_recap + required: true diff --git a/examples/production-testing/artifacts/session_recap.yml b/examples/production-testing/artifacts/session_recap.yml index e0dba10..9dc8516 100644 --- a/examples/production-testing/artifacts/session_recap.yml +++ b/examples/production-testing/artifacts/session_recap.yml @@ -1,11 +1,8 @@ -scriptorium: - artifacts: - session_recap: - enabled: true - prompt_id: dnd.session_recap - profile_id: production-placeholder - output_path: artifacts/session-recap.md - inputs: - transcript: - source: narratio.transcript.final_trimmed - required: true +enabled: true +prompt_id: dnd.session_recap +profile_id: production-placeholder +output_path: artifacts/session-recap.md +inputs: + transcript: + source: narratio.transcript.final_trimmed + required: true diff --git a/examples/production-testing/overlays/testing.yml b/examples/production-testing/overlays/testing.yml index 891222b..41472c9 100644 --- a/examples/production-testing/overlays/testing.yml +++ b/examples/production-testing/overlays/testing.yml @@ -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: proposal_profile: narratio-testing-model-placeholder validation_profile: narratio-testing-validator-placeholder diff --git a/examples/production-testing/pipeline.yml b/examples/production-testing/pipeline.yml index 63b354b..328edaf 100644 --- a/examples/production-testing/pipeline.yml +++ b/examples/production-testing/pipeline.yml @@ -1,13 +1,25 @@ -# Copyable production-base/testing-overlay entry point. ConfigKit expands only -# these explicit path and glob imports; Narratio never scans directories itself. +# ConfigKit assembles these declared sources; destinations define artifact IDs. config: imports: - path: conf.d/platform.yml + required: true - path: conf.d/storage.yml + required: true - path: conf.d/transcript.yml + required: true - path: conf.d/publish.yml - - glob: artifacts/*.yml - - glob: artifact-families/*.yml + required: true + - 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: binary: scriptorium diff --git a/examples/session-inputs/local-audio.yml b/examples/session-inputs/local-audio.yml new file mode 100644 index 0000000..958683a --- /dev/null +++ b/examples/session-inputs/local-audio.yml @@ -0,0 +1,2 @@ +inputs: + audio_dir: ../audio diff --git a/examples/session.local-audio.yml b/examples/session.local-audio.yml index 623eb0e..0487c89 100644 --- a/examples/session.local-audio.yml +++ b/examples/session.local-audio.yml @@ -1,5 +1,7 @@ +config: + imports: + - path: session-inputs/local-audio.yml + required: true session_id: 2026-05-03 date: 2026-05-03 title: Sample Session -inputs: - audio_dir: ./audio diff --git a/internal/config/collection_authoring_test.go b/internal/config/collection_authoring_test.go new file mode 100644 index 0000000..fcb299e --- /dev/null +++ b/internal/config/collection_authoring_test.go @@ -0,0 +1,50 @@ +package config + +import ( + "reflect" + "strings" + "testing" +) + +func TestAuthoredPublishOutputCollectionOperations(t *testing.T) { + dir := t.TempDir() + root := writePipelineFixture(t, dir, "pipeline.yml", `config: + sequences: + - destination: [publish, outputs] + key: source +publish: + outputs: + - {source: narratio.transcript.final_markdown, dest: transcripts/base.md, required: true} +`) + for _, tc := range []struct { + name string + mode string + body string + want []string + }{ + {"append", "append", "[{source: narratio.transcript.final_trimmed, dest: transcripts/extra.json, required: false}]", []string{"transcripts/base.md", "transcripts/extra.json"}}, + {"upsert", "upsert", "[{source: narratio.transcript.final_markdown, dest: transcripts/replaced.md, required: false}]", []string{"transcripts/replaced.md"}}, + {"replace", "replace", "[]", []string{}}, + {"empty append", "append", "[]", []string{"transcripts/base.md"}}, + {"empty upsert", "upsert", "[]", []string{"transcripts/base.md"}}, + } { + t.Run(tc.name, func(t *testing.T) { + selection := strings.ReplaceAll(tc.name, " ", "_") + writePipelineFixture(t, dir, "overlays/"+selection+".yml", "config:\n sequences:\n - destination: [publish, outputs]\n key: source\n mode: "+tc.mode+"\npublish:\n outputs: "+tc.body+"\n") + cfg, err := LoadPipelineWithOptions(root, PipelineLoadOptions{Overlay: &selection}) + if err != nil { + t.Fatal(err) + } + got := make([]string, 0, len(cfg.Publish.Outputs)) + for _, output := range cfg.Publish.Outputs { + got = append(got, output.Dest) + } + if !reflect.DeepEqual(got, tc.want) { + t.Fatalf("output destinations = %v, want %v", got, tc.want) + } + if tc.name == "upsert" && (cfg.Publish.Outputs[0].Required == nil || *cfg.Publish.Outputs[0].Required) { + t.Fatal("upsert did not replace the whole matching output") + } + }) + } +} diff --git a/internal/config/load_validate_test.go b/internal/config/load_validate_test.go index db7bd18..d98bf7f 100644 --- a/internal/config/load_validate_test.go +++ b/internal/config/load_validate_test.go @@ -429,6 +429,28 @@ func TestExamplesLoadAndValidate(t *testing.T) { if len(cfg.Pipeline.Publish.Outputs) != 3 { t.Fatalf("publish outputs = %#v, want transcript plus two family outputs", cfg.Pipeline.Publish.Outputs) } + foundTranscript := false + for _, output := range cfg.Pipeline.Publish.Outputs { + if output.Source == "narratio.transcript.final_markdown" { + foundTranscript = true + if output.Required == nil || *output.Required != (profile.selection == "") { + t.Fatalf("overlay transcript output = %#v", output) + } + } + } + if !foundTranscript { + t.Fatal("transcript output is missing") + } + for label, render := range map[string]func() ([]byte, error){ + "campaign": func() ([]byte, error) { return RenderCampaignDocument(cfg) }, + "session": func() ([]byte, error) { return RenderSessionDocument(cfg, cfg.Session.SessionID) }, + "party": cfg.Party.Canonical.YAML, + } { + data, err := render() + if err != nil || strings.Contains(string(data), "imports:") || strings.Contains(string(data), "extends:") { + t.Fatalf("standalone %s = %q, %v", label, data, err) + } + } catalog, err := EffectiveArtifactCatalog(cfg.Pipeline, cfg.Party) if err != nil { t.Fatal(err)