eric/narratio
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 17 Wiki Activity

Add bounded run and plan commands

Browse Source
This commit is contained in:
Eric Rakestraw
2026-08-29 18:07:24 +00:00
parent 700ab655ca
commit 3bcf2c08dd
8 changed files with 363 additions and 51 deletions
Download Patch File Download Diff File Expand all files Collapse all files

110
internal/app/bounded_run.go Normal file
View File

@@ -0,0 +1,110 @@
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
}
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
}

185
internal/app/bounded_run_test.go Normal file
View File

@@ -0,0 +1,185 @@
package app
import (
"bytes"
"context"
"io"
"path/filepath"
"reflect"
"strings"
"testing"
"gitea.maximumdirect.net/eric/narratio/internal/config"
"gitea.maximumdirect.net/eric/narratio/internal/stage"
)
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"},
}
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 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) {
workspaceRoot := t.TempDir()
pipelinePath, campaignPath, sessionPath := writeValidConfigFiles(t, workspaceRoot)
var capturedStages []string
var capturedOptions RunOptions
original := executeStagesFn
t.Cleanup(func() { executeStagesFn = original })
executeStagesFn = func(_ context.Context, _ *config.Config, stages []stage.Stage, options RunOptions) (*RunSummary, error) {
capturedStages = stageNames(stages)
capturedOptions = options
return &RunSummary{SessionID: "2026-05-03", ManifestPath: filepath.Join(workspaceRoot, "manifest.json")}, nil
}
var out bytes.Buffer
err := Run(context.Background(), []string{
"2026-05-03",
"--from", "render",
"--through", "extract",
"--force",
"--config", pipelinePath,
"--campaign-file", campaignPath,
"--session", sessionPath,
}, &out)
if err != nil {
t.Fatalf("Run() error = %v", err)
}
want := []string{"render", "extract"}
if !reflect.DeepEqual(capturedStages, want) || !reflect.DeepEqual(capturedOptions.Plan.Names(), want) || !capturedOptions.Force {
t.Fatalf("stages = %#v options = %#v", capturedStages, capturedOptions)
}
}
func TestPlanPrintsOnlyBoundedRange(t *testing.T) {
workspaceRoot := t.TempDir()
pipelinePath, campaignPath, sessionPath := writeValidConfigFiles(t, workspaceRoot)
var out bytes.Buffer
err := Plan(context.Background(), []string{
"2026-05-03",
"--from", "render",
"--through", "extract",
"--config", pipelinePath,
"--campaign-file", campaignPath,
"--session", sessionPath,
}, &out)
if err != nil {
t.Fatalf("Plan() error = %v", err)
}
got := out.String()
if !strings.Contains(got, "render: run\nextract: run\ntotals: run=2 skip=0") {
t.Fatalf("output = %q, want bounded decisions", got)
}
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)
}
})
}
}

26
internal/app/plan.go
View File

@@ -2,6 +2,7 @@ package app
import (
"context"
"errors"
"flag"
"fmt"
"io"
@@ -16,20 +17,14 @@ import (
// Plan validates configuration, prepares the local workdir, and prints stage order.
func Plan(ctx context.Context, args []string, out io.Writer) error {
fs := flag.NewFlagSet("plan", flag.ContinueOnError)
fs.SetOutput(io.Discard)
var flags commonConfigFlags
var force bool
addCommonConfigFlags(fs, &flags)
fs.BoolVar(&force, "force", false, "show all stages as scheduled to rerun")
if err := parseSessionAwareFlags("plan", fs, args, &flags.sessionID); err != nil {
request, err := parseBoundedRunRequest("plan", args, out)
if err != nil {
if errors.Is(err, flag.ErrHelp) {
return nil
}
return err
}
if flags.sessionID == "" {
return fmt.Errorf("plan: session_id is required")
}
flags := request.Config
loaded, err := loadCommandConfig(ctx, flags.pipelinePath, flags.campaignPath, flags.campaignFilePath, flags.sessionPath, flags.sessionOptions())
if err != nil {
return fmt.Errorf("plan: %w", err)
@@ -39,6 +34,9 @@ func Plan(ctx context.Context, args []string, out io.Writer) error {
if err := config.Validate(cfg); err != nil {
return fmt.Errorf("plan: %w", err)
}
if _, err := resolveEffectiveArtifacts(cfg, request.SelectedArtifacts); err != nil {
return fmt.Errorf("plan: %w", err)
}
if _, err := loadSecretsFromConfig(cfg, logging.NewLogger(os.Stderr, slog.LevelInfo)); err != nil {
return fmt.Errorf("plan: %w", err)
}
@@ -49,13 +47,13 @@ func Plan(ctx context.Context, args []string, out io.Writer) error {
return fmt.Errorf("plan: prepare workdir: %w", err)
}
stages := BuildFullPlan()
stages := request.Plan.Stages()
var m *manifest.Manifest
m, err = loadManifestIfPresent(ctx, cfg)
if err != nil {
return fmt.Errorf("plan: %w", err)
}
decisions := decideStageActions(stages, m, force)
decisions := decideStageActions(stages, m, request.Force)
runCount := 0
skipCount := 0

34
internal/app/run.go
View File

@@ -2,6 +2,7 @@ package app
import (
"context"
"errors"
"flag"
"fmt"
"io"
@@ -11,22 +12,14 @@ import (
// Run executes the pipeline plan and persists manifest state.
func Run(ctx context.Context, args []string, out io.Writer) error {
fs := flag.NewFlagSet("run", flag.ContinueOnError)
fs.SetOutput(io.Discard)
var flags commonConfigFlags
var force bool
var selectedArtifacts artifactSelectionFlag
addCommonConfigFlags(fs, &flags)
fs.BoolVar(&force, "force", false, "rerun stages even when already succeeded")
fs.Var(&selectedArtifacts, "artifacts", "configured artifact names to execute and publish (comma-separated or repeatable)")
if err := parseSessionAwareFlags("run", fs, args, &flags.sessionID); err != nil {
request, err := parseBoundedRunRequest("run", args, out)
if err != nil {
if errors.Is(err, flag.ErrHelp) {
return nil
}
return err
}
if flags.sessionID == "" {
return fmt.Errorf("run: session_id is required")
}
flags := request.Config
loaded, err := loadCommandConfig(ctx, flags.pipelinePath, flags.campaignPath, flags.campaignFilePath, flags.sessionPath, flags.sessionOptions())
if err != nil {
return fmt.Errorf("run: %w", err)
@@ -36,19 +29,16 @@ func Run(ctx context.Context, args []string, out io.Writer) error {
if err := config.Validate(cfg); err != nil {
return fmt.Errorf("run: %w", err)
}
normalizedArtifacts, err := selectedArtifacts.Normalize()
if err != nil {
return fmt.Errorf("run: invalid --artifacts: %w", err)
}
effectiveArtifacts, err := resolveEffectiveArtifacts(cfg, normalizedArtifacts)
effectiveArtifacts, err := resolveEffectiveArtifacts(cfg, request.SelectedArtifacts)
if err != nil {
return fmt.Errorf("run: %w", err)
}
stages := BuildFullPlan()
stages := request.Plan.Stages()
summary, err := executeStagesFn(ctx, cfg, stages, RunOptions{
Force: force,
SelectedArtifacts: normalizedArtifacts,
Force: request.Force,
SelectedArtifacts: request.SelectedArtifacts,
EffectiveArtifacts: effectiveArtifacts,
Plan: request.Plan,
})
if err != nil {
return fmt.Errorf("run: %w", err)

1
internal/app/runner.go
View File

@@ -26,6 +26,7 @@ type RunOptions struct {
Force bool
SelectedArtifacts []string
EffectiveArtifacts artifacts.EffectiveArtifactSet
Plan BoundedPlan
Env *Env
RunManifestStore manifest.RunStore
}