Initialize narratio Go module and CLI scaffold

internal/app/app.go

@@ -0,0 +1,26 @@
+package app
+
+import (
+	"log/slog"
+
+	"gitea.maximumdirect.net/eric/narratio/internal/adapters/analyzer"
+	"gitea.maximumdirect.net/eric/narratio/internal/adapters/audita"
+	"gitea.maximumdirect.net/eric/narratio/internal/adapters/notify"
+	"gitea.maximumdirect.net/eric/narratio/internal/adapters/seriatim"
+	"gitea.maximumdirect.net/eric/narratio/internal/adapters/whisperx"
+	"gitea.maximumdirect.net/eric/narratio/internal/artifacts"
+	"gitea.maximumdirect.net/eric/narratio/internal/config"
+)
+
+// Env is the shared dependency container passed to orchestrator components.
+type Env struct {
+	Config        *config.Config
+	ArtifactStore artifacts.Store
+	Logger        *slog.Logger
+
+	WhisperX whisperx.Client
+	Seriatim seriatim.Runner
+	Audita   audita.Runner
+	Analyzer analyzer.Runner
+	Notifier notify.Sender
+}

internal/app/commands.go

@@ -0,0 +1,56 @@
+package app
+
+import (
+	"context"
+	"fmt"
+	"io"
+	"strings"
+)
+
+var supportedCommands = []string{"run", "plan", "status", "resume", "run-stage"}
+
+// Execute dispatches CLI commands and returns a process exit code.
+func Execute(args []string, stdout, stderr io.Writer) int {
+	if len(args) == 0 {
+		printUsage(stderr)
+		return 1
+	}
+
+	ctx := context.Background()
+	cmd := args[0]
+	cmdArgs := args[1:]
+
+	var err error
+	switch cmd {
+	case "run":
+		err = Run(ctx, cmdArgs, stdout)
+	case "plan":
+		err = Plan(ctx, cmdArgs, stdout)
+	case "status":
+		err = Status(ctx, cmdArgs, stdout)
+	case "resume":
+		err = Resume(ctx, cmdArgs, stdout)
+	case "run-stage":
+		err = RunStage(ctx, cmdArgs, stdout)
+	default:
+		fmt.Fprintf(stderr, "unknown command: %q\n\n", cmd)
+		printUsage(stderr)
+		return 1
+	}
+
+	if err != nil {
+		fmt.Fprintf(stderr, "%v\n", err)
+		return 1
+	}
+
+	return 0
+}
+
+func printUsage(w io.Writer) {
+	fmt.Fprintf(w, "Usage: narratio <%s>\n", strings.Join(supportedCommands, "|"))
+}
+
+func placeholder(out io.Writer, command string) error {
+	_, err := fmt.Fprintf(out, "narratio %s: not yet implemented\n", command)
+	return err
+}

internal/app/commands_test.go

@@ -0,0 +1,75 @@
+package app
+
+import (
+	"bytes"
+	"strings"
+	"testing"
+)
+
+func TestExecuteValidCommands(t *testing.T) {
+	cases := []struct {
+		name    string
+		args    []string
+		wantOut string
+	}{
+		{name: "run", args: []string{"run"}, wantOut: "narratio run: not yet implemented"},
+		{name: "plan", args: []string{"plan"}, wantOut: "narratio plan: not yet implemented"},
+		{name: "status", args: []string{"status"}, wantOut: "narratio status: not yet implemented"},
+		{name: "resume", args: []string{"resume"}, wantOut: "narratio resume: not yet implemented"},
+		{name: "run-stage", args: []string{"run-stage", "polish"}, wantOut: "narratio run-stage: not yet implemented"},
+	}
+
+	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 TestExecuteInvalidCommand(t *testing.T) {
+	var stdout bytes.Buffer
+	var stderr bytes.Buffer
+
+	code := Execute([]string{"bogus"}, &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())
+	}
+	out := stderr.String()
+	if !strings.Contains(out, "unknown command") {
+		t.Fatalf("stderr = %q, want unknown command message", out)
+	}
+	if !strings.Contains(out, "Usage: narratio") {
+		t.Fatalf("stderr = %q, want usage message", out)
+	}
+}
+
+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())
+	}
+}

internal/app/doc.go

@@ -0,0 +1,3 @@
+// Package app contains CLI command wiring and top-level application orchestration
+// primitives for narratio.
+package app

internal/app/plan.go

@@ -0,0 +1,11 @@
+package app
+
+import (
+	"context"
+	"io"
+)
+
+// Plan is a placeholder for future stage planning behavior.
+func Plan(_ context.Context, _ []string, out io.Writer) error {
+	return placeholder(out, "plan")
+}

internal/app/resume.go

@@ -0,0 +1,11 @@
+package app
+
+import (
+	"context"
+	"io"
+)
+
+// Resume is a placeholder for future resume-from-manifest behavior.
+func Resume(_ context.Context, _ []string, out io.Writer) error {
+	return placeholder(out, "resume")
+}

internal/app/run.go

@@ -0,0 +1,11 @@
+package app
+
+import (
+	"context"
+	"io"
+)
+
+// Run is a placeholder for the future end-to-end pipeline execution command.
+func Run(_ context.Context, _ []string, out io.Writer) error {
+	return placeholder(out, "run")
+}

internal/app/run_stage.go

@@ -0,0 +1,11 @@
+package app
+
+import (
+	"context"
+	"io"
+)
+
+// RunStage is a placeholder for future single-stage execution behavior.
+func RunStage(_ context.Context, _ []string, out io.Writer) error {
+	return placeholder(out, "run-stage")
+}

internal/app/status.go

@@ -0,0 +1,11 @@
+package app
+
+import (
+	"context"
+	"io"
+)
+
+// Status is a placeholder for future manifest status inspection behavior.
+func Status(_ context.Context, _ []string, out io.Writer) error {
+	return placeholder(out, "status")
+}