Add the artifact regeneration command

internal/app/commands.go

@@ -7,7 +7,9 @@ import (
 	"strings"
 )
 
-var supportedCommands = []string{"run", "run-stage", "analyze", "publish", "clean", "session"}
+var supportedCommands = []string{"run", "regenerate-artifacts", "run-stage", "analyze", "publish", "clean", "session"}
+
+var runCommandFn = Run
 
 // Execute dispatches CLI commands and returns a process exit code.
 func Execute(args []string, stdout, stderr io.Writer) int {
@@ -23,7 +25,9 @@ func Execute(args []string, stdout, stderr io.Writer) int {
 	var err error
 	switch cmd {
 	case "run":
-		err = Run(ctx, cmdArgs, stdout)
+		err = runCommandFn(ctx, cmdArgs, stdout)
+	case "regenerate-artifacts":
+		err = RegenerateArtifacts(ctx, cmdArgs, stdout)
 	case "run-stage":
 		err = RunStage(ctx, cmdArgs, stdout)
 	case "analyze":

internal/app/regenerate_artifacts.go

@@ -0,0 +1,43 @@
+package app
+
+import (
+	"context"
+	"fmt"
+	"io"
+)
+
+// RegenerateArtifacts expands the convenience command into its canonical run
+// invocation. The run command remains the sole owner of parsing and execution.
+func RegenerateArtifacts(ctx context.Context, args []string, out io.Writer) error {
+	if containsHelpOption(args) {
+		printRegenerateArtifactsHelp(out)
+		return nil
+	}
+
+	expanded := make([]string, 0, len(args)+5)
+	if len(args) > 0 {
+		expanded = append(expanded, args[0])
+		args = args[1:]
+	}
+	expanded = append(expanded, "--force", "--from", "extract", "--through", "analyze")
+	expanded = append(expanded, args...)
+	return runCommandFn(ctx, expanded, out)
+}
+
+func containsHelpOption(args []string) bool {
+	for _, arg := range args {
+		if arg == "-h" || arg == "--help" {
+			return true
+		}
+	}
+	return false
+}
+
+func printRegenerateArtifactsHelp(out io.Writer) {
+	_, _ = fmt.Fprintln(out, "Usage: narratio regenerate-artifacts <session_id> [--artifacts <name[,name...]>] [common config flags]")
+	_, _ = fmt.Fprintln(out)
+	_, _ = fmt.Fprintln(out, "Exactly equivalent to:")
+	_, _ = fmt.Fprintln(out, "  narratio run <session_id> --force --from extract --through analyze [caller options]")
+	_, _ = fmt.Fprintln(out)
+	_, _ = fmt.Fprintln(out, "Extraction always runs; selected analysis artifacts and their required prerequisites are rebuilt. Publish and notify never run.")
+}

internal/app/regenerate_artifacts_test.go

@@ -0,0 +1,106 @@
+package app
+
+import (
+	"bytes"
+	"context"
+	"io"
+	"reflect"
+	"strings"
+	"testing"
+)
+
+func TestRegenerateArtifactsForwardsExactCanonicalRunArguments(t *testing.T) {
+	original := runCommandFn
+	t.Cleanup(func() { runCommandFn = original })
+	var captured []string
+	runCommandFn = func(_ context.Context, args []string, _ io.Writer) error {
+		captured = append([]string(nil), args...)
+		return nil
+	}
+
+	code := Execute([]string{
+		"regenerate-artifacts", "2026-05-03",
+		"--artifacts", "session_recap,player_handout",
+		"--artifacts=player_handout",
+		"--config", "pipeline.yml",
+		"--campaign", "sample-campaign",
+	}, io.Discard, io.Discard)
+	if code != 0 {
+		t.Fatalf("Execute() code = %d, want 0", code)
+	}
+	want := []string{
+		"2026-05-03", "--force", "--from", "extract", "--through", "analyze",
+		"--artifacts", "session_recap,player_handout",
+		"--artifacts=player_handout",
+		"--config", "pipeline.yml",
+		"--campaign", "sample-campaign",
+	}
+	if !reflect.DeepEqual(captured, want) {
+		t.Fatalf("forwarded args = %#v, want %#v", captured, want)
+	}
+}
+
+func TestRegenerateArtifactsHelpDoesNotInvokeRun(t *testing.T) {
+	original := runCommandFn
+	t.Cleanup(func() { runCommandFn = original })
+	called := false
+	runCommandFn = func(_ context.Context, _ []string, _ io.Writer) error {
+		called = true
+		return nil
+	}
+
+	var stdout bytes.Buffer
+	var stderr bytes.Buffer
+	if code := Execute([]string{"regenerate-artifacts", "--help"}, &stdout, &stderr); code != 0 {
+		t.Fatalf("Execute() code = %d, stderr = %q", code, stderr.String())
+	}
+	if called {
+		t.Fatal("help invoked canonical run handler")
+	}
+	for _, detail := range []string{
+		"narratio run <session_id> --force --from extract --through analyze",
+		"Extraction always runs",
+		"Publish and notify never run",
+	} {
+		if !strings.Contains(stdout.String(), detail) {
+			t.Fatalf("help = %q, want %q", stdout.String(), detail)
+		}
+	}
+	if stderr.Len() != 0 {
+		t.Fatalf("stderr = %q, want empty", stderr.String())
+	}
+}
+
+func TestRegenerateArtifactsOwnedOptionsFailThroughRunParser(t *testing.T) {
+	for _, test := range []struct {
+		name  string
+		args  []string
+		owned string
+	}{
+		{name: "force", args: []string{"--force"}, owned: "force"},
+		{name: "from", args: []string{"--from=render"}, owned: "from"},
+		{name: "through", args: []string{"--through", "publish"}, owned: "through"},
+	} {
+		t.Run(test.name, func(t *testing.T) {
+			args := []string{"regenerate-artifacts", "2026-05-03"}
+			args = append(args, test.args...)
+			var stderr bytes.Buffer
+			if code := Execute(args, io.Discard, &stderr); code == 0 {
+				t.Fatalf("Execute(%#v) code = 0", args)
+			}
+			if !strings.Contains(stderr.String(), "--"+test.owned+" may be specified only once") {
+				t.Fatalf("stderr = %q, want shared duplicate %s error", stderr.String(), test.owned)
+			}
+		})
+	}
+}
+
+func TestRegenerateArtifactsRejectsUnknownOptionsThroughRunParser(t *testing.T) {
+	var stderr bytes.Buffer
+	if code := Execute([]string{"regenerate-artifacts", "2026-05-03", "--regenerate-only"}, io.Discard, &stderr); code == 0 {
+		t.Fatal("Execute() code = 0")
+	}
+	if !strings.Contains(stderr.String(), "flag provided but not defined") || !strings.Contains(stderr.String(), "regenerate-only") {
+		t.Fatalf("stderr = %q, want canonical parser unknown-option error", stderr.String())
+	}
+}