2026-05-02 10:37:38 -05:00
package config
2026-05-02 10:43:45 -05:00
import (
"fmt"
2026-05-02 11:44:15 -05:00
"path/filepath"
2026-05-16 22:57:42 +00:00
"regexp"
2026-11-17 22:15:05 +00:00
"slices"
2026-05-20 14:26:32 +00:00
"sort"
2026-05-16 22:57:42 +00:00
"strings"
2026-05-02 10:37:38 -05:00
2026-11-17 22:06:29 +00:00
configkit "go.maximumdirect.net/configkit"
2026-05-02 10:43:45 -05:00
)
// LoadPipeline loads pipeline configuration from a YAML file with strict field checking.
func LoadPipeline ( path string ) ( * PipelineConfig , error ) {
2026-08-30 13:25:02 +00:00
return LoadPipelineWithOptions ( path , PipelineLoadOptions { } )
}
2026-09-25 15:24:03 +00:00
// PipelineLoadOptions carries an optional explicit overlay selection. Nil,
2026-09-07 03:54:41 +00:00
// empty, and the exact name "default" select the base configuration.
2026-08-30 13:25:02 +00:00
type PipelineLoadOptions struct {
2026-09-25 15:24:03 +00:00
Overlay * string
2026-11-17 22:06:29 +00:00
Search * configkit . Search
2026-08-30 13:25:02 +00:00
}
// LoadPipelineWithOptions loads pipeline configuration with strict field
2026-09-25 15:24:03 +00:00
// checking and optional named-overlay selection.
2026-08-30 13:25:02 +00:00
func LoadPipelineWithOptions ( path string , opts PipelineLoadOptions ) ( * PipelineConfig , error ) {
2026-09-07 03:54:41 +00:00
cfg , err := loadPipelineWithConfigKit ( path , opts )
2026-08-30 12:33:43 +00:00
if err != nil {
2026-09-07 03:54:41 +00:00
return nil , err
2026-08-30 15:10:38 +00:00
}
2026-11-17 22:09:58 +00:00
return finalizeLoadedPipeline ( cfg )
2026-08-30 15:10:38 +00:00
}
2026-09-25 15:24:03 +00:00
// LoadPipelineOverlayPair resolves two overlays as independent ConfigKit loads.
func LoadPipelineOverlayPair ( path , leftOverlay , rightOverlay string ) ( * PipelineConfig , * PipelineConfig , error ) {
if leftOverlay == rightOverlay {
return nil , nil , fmt . Errorf ( "load pipeline overlays: left and right overlay selections must differ" )
2026-08-30 15:10:38 +00:00
}
2026-09-25 15:24:03 +00:00
leftOptions := PipelineLoadOptions { Overlay : & leftOverlay }
rightOptions := PipelineLoadOptions { Overlay : & rightOverlay }
2026-09-07 03:54:41 +00:00
left , err := LoadPipelineWithOptions ( path , leftOptions )
2026-08-30 15:10:38 +00:00
if err != nil {
2026-09-25 15:24:03 +00:00
return nil , nil , fmt . Errorf ( "load left pipeline overlay: %w" , err )
2026-08-30 15:10:38 +00:00
}
2026-09-07 03:54:41 +00:00
right , err := LoadPipelineWithOptions ( path , rightOptions )
2026-08-30 15:10:38 +00:00
if err != nil {
2026-09-25 15:24:03 +00:00
return nil , nil , fmt . Errorf ( "load right pipeline overlay: %w" , err )
2026-08-30 15:10:38 +00:00
}
return left , right , nil
}
2026-11-17 22:09:58 +00:00
func finalizeLoadedPipeline ( cfg * PipelineConfig ) ( * PipelineConfig , error ) {
2026-09-07 04:39:49 +00:00
finalizeArtifactDependencies ( cfg )
2026-08-30 13:25:02 +00:00
if err := finalizePipelineResolution ( cfg ) ; err != nil {
return nil , fmt . Errorf ( "load pipeline config: %w" , err )
}
2026-08-30 14:15:57 +00:00
retainArtifactFamilyDeclarations ( cfg )
2026-08-30 12:33:43 +00:00
return cfg , nil
2026-05-02 10:43:45 -05:00
}
2026-05-20 20:41:28 -05:00
// LoadCampaign loads campaign configuration from a YAML file with strict field checking.
func LoadCampaign ( path string ) ( * CampaignConfig , error ) {
2026-09-07 04:02:21 +00:00
return loadCampaignWithConfigKit ( path )
2026-05-20 20:41:28 -05:00
}
2026-05-02 10:43:45 -05:00
// LoadSession loads session configuration from a YAML file with strict field checking.
func LoadSession ( path string ) ( * SessionConfig , error ) {
2026-05-16 22:57:42 +00:00
return LoadSessionWithOptions ( path , SessionLoadOptions { } )
}
2026-05-22 17:38:23 -05:00
// SessionLoadOptions configures expected session identity checks.
2026-05-16 22:57:42 +00:00
type SessionLoadOptions struct {
2026-05-20 14:26:32 +00:00
SessionID string
PreviousSessionID string
2026-09-25 15:24:03 +00:00
Overlay * string
2026-05-16 22:57:42 +00:00
}
// LoadSessionWithOptions loads session configuration from a YAML file with
2026-05-22 17:38:23 -05:00
// strict field checking.
2026-05-16 22:57:42 +00:00
func LoadSessionWithOptions ( path string , opts SessionLoadOptions ) ( * SessionConfig , error ) {
2026-11-17 22:15:05 +00:00
cfg , _ , err := loadSessionSource ( configkit . File ( path ) , path , opts , true )
return cfg , err
2026-05-20 20:55:13 -05:00
}
2026-05-16 22:57:42 +00:00
2026-11-17 22:15:05 +00:00
// LoadSessionBytesWithOptions loads a contextless session snapshot.
2026-05-20 20:55:13 -05:00
func LoadSessionBytesWithOptions ( label string , data [ ] byte , opts SessionLoadOptions ) ( * SessionConfig , error ) {
2026-11-17 22:15:05 +00:00
cfg , _ , err := loadSessionSource ( configkit . Bytes ( label , data ) , label , opts , false )
return cfg , err
}
2026-05-16 22:57:42 +00:00
2026-11-17 22:15:05 +00:00
func validateSessionIdentity ( label string , cfg * SessionConfig , opts SessionLoadOptions ) error {
2026-05-16 22:57:42 +00:00
if strings . TrimSpace ( opts . SessionID ) != "" && strings . TrimSpace ( cfg . SessionID ) != "" && strings . TrimSpace ( cfg . SessionID ) != strings . TrimSpace ( opts . SessionID ) {
2026-11-17 22:15:05 +00:00
return fmt . Errorf ( "load session config: session file %q: session_id mismatch: --session-id %q does not match session_id %q" , label , strings . TrimSpace ( opts . SessionID ) , strings . TrimSpace ( cfg . SessionID ) )
2026-05-16 22:57:42 +00:00
}
2026-11-17 22:15:05 +00:00
if expected := strings . TrimSpace ( opts . PreviousSessionID ) ; expected != "" {
actual := strings . TrimSpace ( cfg . PreviousSessionID )
if actual == "" {
return fmt . Errorf ( "load session config: session file %q: previous_session_id is required when --previous-session-id %q is provided" , label , expected )
2026-08-10 21:32:15 +00:00
}
2026-11-17 22:15:05 +00:00
if actual != expected {
return fmt . Errorf ( "load session config: session file %q: previous_session_id mismatch: --previous-session-id %q does not match previous_session_id %q" , label , expected , actual )
2026-08-10 21:32:15 +00:00
}
2026-05-20 14:26:32 +00:00
}
2026-11-17 22:15:05 +00:00
return nil
2026-05-02 10:43:45 -05:00
}
2026-05-20 20:41:28 -05:00
// Load loads and resolves combined pipeline, campaign, and session configuration.
// Passing only a session path is supported for package-internal compatibility;
// in that form campaign.yml is expected next to the session file.
func Load ( pipelinePath string , paths ... string ) ( * Config , error ) {
campaignPath , sessionPath , err := campaignSessionPaths ( paths ... )
if err != nil {
return nil , err
}
return LoadWithSessionOptions ( pipelinePath , campaignPath , sessionPath , SessionLoadOptions { } )
2026-05-16 22:57:42 +00:00
}
2026-05-20 20:41:28 -05:00
// LoadWithSessionOptions loads and resolves combined pipeline, campaign, and
2026-05-22 17:38:23 -05:00
// session configuration with expected session identity checks.
2026-05-20 20:41:28 -05:00
func LoadWithSessionOptions ( pipelinePath , campaignPath , sessionPath string , sessionOpts SessionLoadOptions ) ( * Config , error ) {
2026-09-25 15:24:03 +00:00
pipelineCfg , err := LoadPipelineWithOptions ( pipelinePath , PipelineLoadOptions { Overlay : sessionOpts . Overlay } )
2026-05-02 10:43:45 -05:00
if err != nil {
return nil , err
}
2026-05-20 20:41:28 -05:00
campaignCfg , err := LoadCampaign ( campaignPath )
if err != nil {
return nil , err
}
2026-08-30 14:01:51 +00:00
loaded , err := LoadPipelineCampaign ( pipelinePath , pipelineCfg , campaignPath , campaignCfg )
if err != nil {
return nil , err
}
return LoadSessionWithPipelineCampaignOptions ( loaded , sessionPath , sessionOpts )
2026-08-30 13:32:45 +00:00
}
// LoadedPipelineCampaign retains one already loaded pipeline and campaign for
// subsequent local or remote session resolution. It prevents a command from
// reloading the root pipeline after campaign selection.
type LoadedPipelineCampaign struct {
PipelinePath string
Pipeline * PipelineConfig
CampaignPath string
Campaign * CampaignConfig
2026-08-30 14:01:51 +00:00
Party ResolvedParty
}
// LoadPipelineCampaign combines already loaded pipeline and campaign documents
// with their campaign-owned party source. Callers that later resolve a session
// retain this context rather than independently reimplementing party loading.
func LoadPipelineCampaign ( pipelinePath string , pipeline * PipelineConfig , campaignPath string , campaign * CampaignConfig ) ( LoadedPipelineCampaign , error ) {
if pipeline == nil {
return LoadedPipelineCampaign { } , fmt . Errorf ( "pipeline config is required" )
}
if campaign == nil {
return LoadedPipelineCampaign { } , fmt . Errorf ( "campaign config is required" )
}
party , err := resolveCampaignParty ( campaignPath , campaign )
if err != nil {
return LoadedPipelineCampaign { } , err
}
2026-08-30 15:10:38 +00:00
return LoadPipelineCampaignWithParty ( pipelinePath , pipeline , campaignPath , campaign , party )
}
// LoadPipelineCampaignWithParty combines an already loaded pipeline and
// campaign with one already resolved campaign-owned party. It is useful when
// more than one independently resolved pipeline must be expanded against the
// exact same party document.
func LoadPipelineCampaignWithParty ( pipelinePath string , pipeline * PipelineConfig , campaignPath string , campaign * CampaignConfig , party ResolvedParty ) ( LoadedPipelineCampaign , error ) {
if pipeline == nil {
return LoadedPipelineCampaign { } , fmt . Errorf ( "pipeline config is required" )
}
if campaign == nil {
return LoadedPipelineCampaign { } , fmt . Errorf ( "campaign config is required" )
}
2026-09-02 12:04:35 +00:00
if party . Canonical == nil {
2026-08-30 15:10:38 +00:00
return LoadedPipelineCampaign { } , fmt . Errorf ( "resolved campaign party is required" )
}
2026-08-30 14:15:57 +00:00
if err := expandPipelineArtifactFamilies ( pipeline , party ) ; err != nil {
return LoadedPipelineCampaign { } , err
}
2026-08-30 14:01:51 +00:00
return LoadedPipelineCampaign {
PipelinePath : pipelinePath ,
Pipeline : pipeline ,
CampaignPath : campaignPath ,
Campaign : campaign ,
Party : party ,
} , nil
2026-08-30 13:32:45 +00:00
}
2026-05-20 20:41:28 -05:00
2026-08-30 13:32:45 +00:00
// LoadSessionWithPipelineCampaignOptions loads one local session and combines
// it with an already loaded pipeline and campaign.
func LoadSessionWithPipelineCampaignOptions ( loaded LoadedPipelineCampaign , sessionPath string , sessionOpts SessionLoadOptions ) ( * Config , error ) {
2026-05-16 22:57:42 +00:00
sessionCfg , err := LoadSessionWithOptions ( sessionPath , sessionOpts )
2026-05-02 10:43:45 -05:00
if err != nil {
return nil , err
}
2026-08-30 13:32:45 +00:00
return ResolveLoadedPipelineCampaign ( loaded , sessionPath , sessionCfg , SessionSource {
2026-05-20 20:55:13 -05:00
Source : "session_config" ,
LocalPath : sessionPath ,
} )
}
2026-08-30 13:32:45 +00:00
// ResolveLoadedPipelineCampaign combines an already loaded pipeline and
// campaign with optional already loaded session data. A nil session preserves
// the resolved pipeline/campaign context for callers that need to locate or
// retrieve a session without rereading the root pipeline.
func ResolveLoadedPipelineCampaign ( loaded LoadedPipelineCampaign , sessionPath string , sessionCfg * SessionConfig , sessionSource SessionSource ) ( * Config , error ) {
2026-08-30 14:01:51 +00:00
if loaded . Pipeline == nil {
return nil , fmt . Errorf ( "pipeline config is required" )
}
if loaded . Campaign == nil {
return nil , fmt . Errorf ( "campaign config is required" )
}
2026-09-02 12:04:35 +00:00
if loaded . Party . Canonical == nil {
2026-08-30 14:01:51 +00:00
party , err := resolveCampaignParty ( loaded . CampaignPath , loaded . Campaign )
if err != nil {
return nil , err
}
loaded . Party = party
}
2026-08-30 13:32:45 +00:00
cfg := & Config {
Pipeline : loaded . Pipeline ,
Campaign : loaded . Campaign ,
Session : sessionCfg ,
PipelinePath : loaded . PipelinePath ,
CampaignPath : loaded . CampaignPath ,
SessionPath : sessionPath ,
SessionSource : sessionSource ,
2026-08-30 14:01:51 +00:00
Party : loaded . Party ,
}
2026-11-17 22:15:05 +00:00
campaignDocument := * loaded . Campaign
cfg . CampaignDocument = & campaignDocument
2026-08-30 13:32:45 +00:00
if sessionCfg == nil {
return cfg , nil
}
2026-11-17 22:15:05 +00:00
sessionDocument := * sessionCfg
sessionDocument . Inputs . AudioFiles = slices . Clone ( sessionCfg . Inputs . AudioFiles )
if sessionCfg . Inputs . AudioS3 != nil {
audio := * sessionCfg . Inputs . AudioS3
sessionDocument . Inputs . AudioS3 = & audio
}
cfg . SessionDocument = & sessionDocument
2026-08-30 13:32:45 +00:00
stableInputs , err := mergeCampaignSession ( loaded . Campaign , sessionCfg , loaded . CampaignPath , sessionPath )
2026-05-20 20:41:28 -05:00
if err != nil {
return nil , err
}
2026-08-30 13:32:45 +00:00
if strings . TrimSpace ( cfg . SessionSource . Source ) == "" {
cfg . SessionSource . Source = "session_config"
2026-05-20 20:55:13 -05:00
}
2026-08-30 13:32:45 +00:00
if strings . TrimSpace ( cfg . SessionSource . LocalPath ) == "" {
cfg . SessionSource . LocalPath = sessionPath
2026-05-20 20:55:13 -05:00
}
2026-08-30 13:32:45 +00:00
cfg . StableInputs = stableInputs
return cfg , nil
}
2026-05-20 20:41:28 -05:00
2026-08-30 13:32:45 +00:00
// Resolve builds final stage-facing configuration from already loaded
// pipeline, campaign, and session documents.
func Resolve ( pipelinePath string , pipelineCfg * PipelineConfig , campaignPath string , campaignCfg * CampaignConfig , sessionPath string , sessionCfg * SessionConfig , sessionSource SessionSource ) ( * Config , error ) {
if sessionCfg == nil {
return nil , fmt . Errorf ( "session config is required" )
}
2026-08-30 14:01:51 +00:00
loaded , err := LoadPipelineCampaign ( pipelinePath , pipelineCfg , campaignPath , campaignCfg )
if err != nil {
return nil , err
}
return ResolveLoadedPipelineCampaign ( loaded , sessionPath , sessionCfg , sessionSource )
2026-05-02 10:43:45 -05:00
}
2026-05-20 20:41:28 -05:00
func campaignSessionPaths ( paths ... string ) ( campaignPath , sessionPath string , err error ) {
switch len ( paths ) {
case 1 :
sessionPath = paths [ 0 ]
campaignPath = filepath . Join ( filepath . Dir ( sessionPath ) , "campaign.yml" )
case 2 :
campaignPath = paths [ 0 ]
sessionPath = paths [ 1 ]
default :
return "" , "" , fmt . Errorf ( "load config: expected session path or campaign and session paths" )
}
return campaignPath , sessionPath , nil
}
func mergeCampaignSession ( campaignCfg * CampaignConfig , sessionCfg * SessionConfig , campaignPath , sessionPath string ) ( ResolvedStableInputs , error ) {
if campaignCfg == nil {
return ResolvedStableInputs { } , fmt . Errorf ( "campaign config is required" )
}
if sessionCfg == nil {
return ResolvedStableInputs { } , fmt . Errorf ( "session config is required" )
}
2026-08-29 14:55:24 +00:00
if campaignCfg . Inputs . SpellCatalogFile != "" && strings . TrimSpace ( campaignCfg . Inputs . SpellCatalogFile ) == "" {
return ResolvedStableInputs { } , fmt . Errorf ( "campaign.inputs.spell_catalog_file must be non-empty when provided" )
}
if sessionCfg . Inputs . SpellCatalogFile != "" && strings . TrimSpace ( sessionCfg . Inputs . SpellCatalogFile ) == "" {
return ResolvedStableInputs { } , fmt . Errorf ( "session.inputs.spell_catalog_file must be non-empty when provided" )
}
2026-05-20 20:41:28 -05:00
2026-05-22 23:01:27 -05:00
campaignName := CampaignID ( campaignCfg )
2026-05-20 20:41:28 -05:00
sessionCampaign := strings . TrimSpace ( sessionCfg . Campaign )
if sessionCampaign != "" && campaignName != "" && sessionCampaign != campaignName {
return ResolvedStableInputs { } , fmt . Errorf (
"campaign/session config invalid: session campaign %q does not match campaign config %q" ,
sessionCampaign ,
campaignName ,
)
}
if sessionCampaign == "" {
sessionCfg . Campaign = campaignName
}
stable := ResolvedStableInputs {
SpeakersFile : selectStableInput (
campaignCfg . Inputs . SpeakersFile ,
sessionCfg . Inputs . SpeakersFile ,
campaignPath ,
sessionPath ,
) ,
AutocorrectFile : selectStableInput (
campaignCfg . Inputs . AutocorrectFile ,
sessionCfg . Inputs . AutocorrectFile ,
campaignPath ,
sessionPath ,
) ,
GlossaryFile : selectStableInput (
campaignCfg . Inputs . GlossaryFile ,
sessionCfg . Inputs . GlossaryFile ,
campaignPath ,
sessionPath ,
) ,
2026-05-27 09:34:05 -05:00
PartyFile : selectStableInput (
campaignCfg . Inputs . PartyFile ,
2026-09-02 12:04:35 +00:00
"" ,
2026-05-27 09:34:05 -05:00
campaignPath ,
sessionPath ,
) ,
2026-08-29 14:55:24 +00:00
SpellCatalogFile : selectStableInput (
campaignCfg . Inputs . SpellCatalogFile ,
sessionCfg . Inputs . SpellCatalogFile ,
campaignPath ,
sessionPath ,
) ,
2026-05-20 20:41:28 -05:00
}
2026-11-17 22:15:05 +00:00
for _ , field := range [ ] struct {
name string
input * ResolvedInputFile
} {
{ "speakers_file" , & stable . SpeakersFile } , { "autocorrect_file" , & stable . AutocorrectFile } ,
{ "glossary_file" , & stable . GlossaryFile } , { "party_file" , & stable . PartyFile } ,
{ "spell_catalog_file" , & stable . SpellCatalogFile } ,
} {
metadata := campaignCfg . resolution
if field . input . Source == "session_config" {
metadata = sessionCfg . resolution
}
if metadata != nil && metadata . sources [ "/inputs/" + field . name ] != "" {
field . input . ConfigPath = metadata . sources [ "/inputs/" + field . name ]
}
}
2026-05-20 20:41:28 -05:00
sessionCfg . Inputs . SpeakersFile = stable . SpeakersFile . Path
sessionCfg . Inputs . AutocorrectFile = stable . AutocorrectFile . Path
sessionCfg . Inputs . GlossaryFile = stable . GlossaryFile . Path
2026-08-29 14:55:24 +00:00
sessionCfg . Inputs . SpellCatalogFile = stable . SpellCatalogFile . Path
2026-05-20 20:41:28 -05:00
return stable , nil
}
2026-05-22 23:01:27 -05:00
// CampaignID returns the canonical campaign identity from campaign config.
func CampaignID ( cfg * CampaignConfig ) string {
if cfg == nil {
return ""
}
return strings . TrimSpace ( cfg . CampaignID )
}
2026-05-20 20:41:28 -05:00
func selectStableInput ( campaignValue , sessionValue , campaignPath , sessionPath string ) ResolvedInputFile {
if strings . TrimSpace ( sessionValue ) != "" {
return ResolvedInputFile {
Path : sessionValue ,
ConfigPath : sessionPath ,
Source : "session_config" ,
}
}
return ResolvedInputFile {
Path : campaignValue ,
ConfigPath : campaignPath ,
Source : "campaign_config" ,
}
}
2026-05-22 17:38:23 -05:00
var sessionTemplatePlaceholderPattern = regexp . MustCompile ( ` \ { \ { [^}]*\}\} ` )
var sessionTemplateVariablePattern = regexp . MustCompile ( ` \ { \ { \s*([a-zA-Z_][a-zA-Z0-9_]*)\s*\}\} ` )
2026-05-20 14:26:32 +00:00
2026-05-22 17:38:23 -05:00
func rejectSessionTemplatePlaceholders ( label , content string ) error {
placeholders := sessionTemplatePlaceholderPattern . FindAllString ( content , - 1 )
if len ( placeholders ) == 0 {
return nil
}
2026-05-20 14:26:32 +00:00
seen := map [ string ] struct { } { }
2026-05-22 17:38:23 -05:00
vars := make ( [ ] string , 0 , len ( placeholders ) )
for _ , placeholder := range placeholders {
name := strings . TrimSpace ( placeholder )
if match := sessionTemplateVariablePattern . FindStringSubmatch ( placeholder ) ; len ( match ) > 1 {
name = match [ 1 ]
2026-05-20 14:26:32 +00:00
}
2026-05-22 17:38:23 -05:00
if _ , ok := seen [ name ] ; ok {
continue
}
seen [ name ] = struct { } { }
vars = append ( vars , name )
}
sort . Strings ( vars )
return fmt . Errorf (
"session file %q contains template placeholder(s): %s; session.yml must be concrete; run narratio session init to generate it" ,
label ,
strings . Join ( vars , ", " ) ,
)
2026-05-20 14:26:32 +00:00
}
2026-05-02 11:44:15 -05:00
func shortName ( path , fallback string ) string {
base := filepath . Base ( path )
if base == "." || base == string ( filepath . Separator ) {
return fallback
}
return base
}