relay-flow 0.0.1 → 0.2.0-alpha

package/internal/harness/plugin_selection_test.go

@@ -0,0 +1,126 @@
+package harness_test
+
+// This file intentionally lives in one package but exercises all three
+// plugin registries (task, runner, harness); they share one behavior.
+
+import (
+	"context"
+	"strings"
+	"testing"
+
+	"github.com/rajpopat27/relay-flow/internal/config"
+	"github.com/rajpopat27/relay-flow/internal/harness"
+	"github.com/rajpopat27/relay-flow/internal/runner"
+	"github.com/rajpopat27/relay-flow/internal/task"
+)
+
+// 3.9: plugin selection per specs/integration-contracts "Plugin types are
+// selected at machine scope": one plugin of each kind selected at root,
+// unknown names error listing registered names, duplicate registration
+// panics.
+
+func TestHarnessRegistryUnknownNameListsRegistered(t *testing.T) {
+	harness.Register("fakeharness-unknown", func(config.RawValues) (harness.Harness, error) {
+		return newFakeHarness(), nil
+	})
+	_, err := harness.New("does-not-exist", config.RawValues{})
+	if err == nil {
+		t.Fatal("unknown harness name accepted")
+	}
+	if !strings.Contains(err.Error(), "fakeharness-unknown") {
+		t.Fatalf("error %q does not list registered names", err)
+	}
+}
+
+func TestRunnerRegistryUnknownNameListsRegistered(t *testing.T) {
+	runner.Register("fakerunner-unknown", func(config.RawValues) (runner.Runner, error) {
+		return nil, nil
+	})
+	_, err := runner.New("does-not-exist", config.RawValues{})
+	if err == nil {
+		t.Fatal("unknown runner name accepted")
+	}
+	if !strings.Contains(err.Error(), "fakerunner-unknown") {
+		t.Fatalf("error %q does not list registered names", err)
+	}
+}
+
+func TestTaskRegistryUnknownNameListsRegistered(t *testing.T) {
+	task.Register("faketask-unknown", task.Factory{
+		RequiredRepoKeys: func() []string { return nil },
+		TaskScopeKey: func(_, _ config.RawValues) (string, error) {
+			return "scope", nil
+		},
+		New: func(context.Context, task.RepoSpec) (task.System, error) {
+			return nil, nil
+		},
+	})
+	_, err := task.New(context.Background(), "does-not-exist", task.RepoSpec{})
+	if err == nil {
+		t.Fatal("unknown task name accepted")
+	}
+	if !strings.Contains(err.Error(), "faketask-unknown") {
+		t.Fatalf("error %q does not list registered names", err)
+	}
+}
+
+func TestDuplicateRegistrationPanics(t *testing.T) {
+	assertPanic := func(name string, fn func()) {
+		t.Helper()
+		defer func() {
+			if r := recover(); r == nil {
+				t.Fatalf("%s duplicate registration did not panic", name)
+			}
+		}()
+		fn()
+	}
+
+	harness.Register("dup-harness-x", func(config.RawValues) (harness.Harness, error) { return nil, nil })
+	assertPanic("harness", func() {
+		harness.Register("dup-harness-x", func(config.RawValues) (harness.Harness, error) { return nil, nil })
+	})
+
+	runner.Register("dup-runner-x", func(config.RawValues) (runner.Runner, error) { return nil, nil })
+	assertPanic("runner", func() {
+		runner.Register("dup-runner-x", func(config.RawValues) (runner.Runner, error) { return nil, nil })
+	})
+
+	factory := task.Factory{
+		RequiredRepoKeys: func() []string { return nil },
+		TaskScopeKey:     func(_, _ config.RawValues) (string, error) { return "s", nil },
+		New:              func(context.Context, task.RepoSpec) (task.System, error) { return nil, nil },
+	}
+	task.Register("dup-task-x", factory)
+	assertPanic("task", func() { task.Register("dup-task-x", factory) })
+}
+
+func TestNamesListsRegistered(t *testing.T) {
+	// Self-contained: register fixtures within this test rather than relying
+	// on earlier tests in the binary.
+	harness.Register("names-harness-x", func(config.RawValues) (harness.Harness, error) { return nil, nil })
+	runner.Register("names-runner-x", func(config.RawValues) (runner.Runner, error) { return nil, nil })
+	task.Register("names-task-x", task.Factory{
+		RequiredRepoKeys: func() []string { return nil },
+		TaskScopeKey:     func(_, _ config.RawValues) (string, error) { return "s", nil },
+		New:              func(context.Context, task.RepoSpec) (task.System, error) { return nil, nil },
+	})
+
+	if !contains(harness.Names(), "names-harness-x") {
+		t.Fatalf("harness.Names() = %v", harness.Names())
+	}
+	if !contains(runner.Names(), "names-runner-x") {
+		t.Fatalf("runner.Names() = %v", runner.Names())
+	}
+	if !contains(task.Names(), "names-task-x") {
+		t.Fatalf("task.Names() = %v", task.Names())
+	}
+}
+
+func contains(xs []string, want string) bool {
+	for _, x := range xs {
+		if x == want {
+			return true
+		}
+	}
+	return false
+}

package/internal/identity/identity.go

@@ -0,0 +1,37 @@
+// Package identity defines the opaque run and node-visit identifiers used
+// across relay-flow. It imports no other relay-flow package.
+package identity
+
+import (
+	"crypto/rand"
+	"encoding/hex"
+	"net/url"
+	"strings"
+)
+
+// RunID identifies one durable run. Opaque to consumers.
+type RunID string
+
+// NodeVisitID identifies one entry into a workflow node. Opaque to consumers.
+type NodeVisitID string
+
+// NewRunID returns the deterministic run ID for a (repo, workflow, ticket)
+// triple. Each component is path-escaped so the joined ID is delimiter-safe.
+func NewRunID(repo, workflow, ticket string) RunID {
+	return RunID(strings.Join([]string{
+		url.PathEscape(repo),
+		url.PathEscape(workflow),
+		url.PathEscape(ticket),
+	}, "/"))
+}
+
+// NewNodeVisitID returns a fresh random node-visit ID. Generation happens
+// once per node entry as a durable replay-safe side effect; this function
+// only produces the random value.
+func NewNodeVisitID() NodeVisitID {
+	var b [16]byte
+	if _, err := rand.Read(b[:]); err != nil {
+		panic(err)
+	}
+	return NodeVisitID(hex.EncodeToString(b[:]))
+}

package/internal/logging/logging.go

@@ -0,0 +1,56 @@
+// Package logging configures the process-wide slog logger for serve.
+// Task 9.1: --debug serve flag OR RELAY_FLOW_LOG_LEVEL env (flag wins);
+// default info. Output goes to server.log AND stderr, stdlib slog only.
+package logging
+
+import (
+	"fmt"
+	"io"
+	"log/slog"
+	"os"
+	"strings"
+)
+
+// Options control Setup. Debug is the --debug serve flag; Env is the value
+// of RELAY_FLOW_LOG_LEVEL (read once by the caller for testability).
+// Flag wins over env.
+type Options struct {
+	Debug bool
+	Env   string
+}
+
+// Setup installs the process-wide slog logger writing to logPath AND
+// stderr. Effective level: --debug flag → debug; else RELAY_FLOW_LOG_LEVEL
+// (debug|info|warn|error, case-insensitive); else info. Unknown env values
+// are ignored (info). The returned closer flushes/closes the log file; it
+// is safe to call more than once.
+func Setup(logPath string, o Options) (io.Closer, error) {
+	f, err := os.OpenFile(logPath, os.O_CREATE|os.O_APPEND|os.O_WRONLY, 0o600)
+	if err != nil {
+		return nil, fmt.Errorf("open server log %s: %w", logPath, err)
+	}
+	if err := f.Chmod(0o600); err != nil {
+		_ = f.Close()
+		return nil, fmt.Errorf("chmod server log %s: %w", logPath, err)
+	}
+	level := levelFor(o)
+	h := slog.NewTextHandler(io.MultiWriter(f, os.Stderr), &slog.HandlerOptions{Level: level})
+	slog.SetDefault(slog.New(h))
+	return f, nil
+}
+
+func levelFor(o Options) slog.Level {
+	if o.Debug {
+		return slog.LevelDebug
+	}
+	switch strings.ToLower(strings.TrimSpace(o.Env)) {
+	case "debug":
+		return slog.LevelDebug
+	case "warn":
+		return slog.LevelWarn
+	case "error":
+		return slog.LevelError
+	default:
+		return slog.LevelInfo
+	}
+}

package/internal/logging/logging_test.go

@@ -0,0 +1,116 @@
+package logging
+
+import (
+	"bytes"
+	"io"
+	"log/slog"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+// 9.1: level resolution — --debug flag wins over RELAY_FLOW_LOG_LEVEL;
+// default is info.
+func TestLevelFor(t *testing.T) {
+	cases := []struct {
+		name string
+		opts Options
+		want slog.Level
+	}{
+		{"default info", Options{}, slog.LevelInfo},
+		{"flag debug", Options{Debug: true}, slog.LevelDebug},
+		{"flag wins over env info", Options{Debug: true, Env: "info"}, slog.LevelDebug},
+		{"flag wins over env error", Options{Debug: true, Env: "error"}, slog.LevelDebug},
+		{"env debug", Options{Env: "debug"}, slog.LevelDebug},
+		{"env warn", Options{Env: "warn"}, slog.LevelWarn},
+		{"env error", Options{Env: "ERROR"}, slog.LevelError},
+		{"env unknown ignored", Options{Env: "bogus"}, slog.LevelInfo},
+		{"env empty", Options{Env: ""}, slog.LevelInfo},
+	}
+	for _, c := range cases {
+		t.Run(c.name, func(t *testing.T) {
+			if got := levelFor(c.opts); got != c.want {
+				t.Fatalf("levelFor(%+v) = %v, want %v", c.opts, got, c.want)
+			}
+		})
+	}
+}
+
+// 9.1: Setup writes to BOTH server.log and stderr, creates the log file
+// 0600, and honors the configured level.
+func TestSetupWritesFileAndStderr(t *testing.T) {
+	dir := t.TempDir()
+	logPath := filepath.Join(dir, "server.log")
+
+	// Capture stderr during Setup + one log call.
+	oldStderr := os.Stderr
+	r, w, err := os.Pipe()
+	if err != nil {
+		t.Fatal(err)
+	}
+	os.Stderr = w
+	defer func() { os.Stderr = oldStderr }()
+
+	closer, err := Setup(logPath, Options{Debug: true})
+	if err != nil {
+		t.Fatalf("Setup: %v", err)
+	}
+	defer closer.Close()
+
+	slog.Debug("hello-debug", "ticket", "PAY-1")
+	slog.Info("hello-info", "ticket", "PAY-2")
+
+	_ = w.Close()
+	os.Stderr = oldStderr
+	var stderrBuf bytes.Buffer
+	_, _ = io.Copy(&stderrBuf, r)
+	stderrOut := stderrBuf.String()
+
+	if !strings.Contains(stderrOut, "hello-debug") || !strings.Contains(stderrOut, "hello-info") {
+		t.Fatalf("stderr missing expected lines; got:\n%s", stderrOut)
+	}
+
+	fi, err := os.Stat(logPath)
+	if err != nil {
+		t.Fatalf("server.log not created: %v", err)
+	}
+	if fi.Mode().Perm() != 0o600 {
+		t.Fatalf("server.log mode = %o, want 0600", fi.Mode().Perm())
+	}
+	body, err := os.ReadFile(logPath)
+	if err != nil {
+		t.Fatal(err)
+	}
+	text := string(body)
+	if !strings.Contains(text, "hello-debug") || !strings.Contains(text, "hello-info") {
+		t.Fatalf("server.log missing expected lines; got:\n%s", text)
+	}
+	if !strings.Contains(text, "ticket=PAY-1") || !strings.Contains(text, "ticket=PAY-2") {
+		t.Fatalf("server.log missing structured ticket attr; got:\n%s", text)
+	}
+}
+
+// 9.1: default (no flag, no env) is info — debug lines are suppressed.
+func TestSetupDefaultInfoSuppressesDebug(t *testing.T) {
+	dir := t.TempDir()
+	logPath := filepath.Join(dir, "server.log")
+	closer, err := Setup(logPath, Options{})
+	if err != nil {
+		t.Fatalf("Setup: %v", err)
+	}
+	defer closer.Close()
+	slog.Debug("suppressed-debug")
+	slog.Info("kept-info")
+	body, err := os.ReadFile(logPath)
+	if err != nil {
+		t.Fatal(err)
+	}
+	text := string(body)
+	if strings.Contains(text, "suppressed-debug") {
+		t.Fatalf("debug line should be suppressed at info level; got:\n%s", text)
+	}
+	if !strings.Contains(text, "kept-info") {
+		t.Fatalf("info line missing; got:\n%s", text)
+	}
+}

package/internal/paths/paths.go

@@ -0,0 +1,67 @@
+// Package paths computes the fixed ~/.relay-flow layout and ensures the root
+// directory exists with owner-only permissions.
+package paths
+
+import (
+	"fmt"
+	"os"
+	"path/filepath"
+)
+
+// Paths is the fixed ~/.relay-flow layout. All process artifacts stay under Root.
+type Paths struct {
+	Root      string
+	Config    string
+	Workflows string
+	Database  string
+	Socket    string
+	Lock      string
+	ServerLog string
+	PluginLog string
+}
+
+// ForUserHome returns the Paths rooted at the current user's home directory.
+func ForUserHome() (Paths, error) {
+	home, err := os.UserHomeDir()
+	if err != nil {
+		return Paths{}, fmt.Errorf("resolve user home: %w", err)
+	}
+	root := filepath.Join(home, ".relay-flow")
+	return Paths{
+		Root:      root,
+		Config:    filepath.Join(root, "config.yaml"),
+		Workflows: filepath.Join(root, "workflows"),
+		Database:  filepath.Join(root, "state.db"),
+		Socket:    filepath.Join(root, "server.sock"),
+		Lock:      filepath.Join(root, "server.lock"),
+		ServerLog: filepath.Join(root, "server.log"),
+		PluginLog: filepath.Join(root, "plugin.log"),
+	}, nil
+}
+
+// Ensure creates Root (0700) and the Workflows subdirectory if missing.
+func Ensure(p Paths) error {
+	if err := os.MkdirAll(p.Root, 0o700); err != nil {
+		return fmt.Errorf("create root %s: %w", p.Root, err)
+	}
+	if err := os.Chmod(p.Root, 0o700); err != nil {
+		return fmt.Errorf("chmod root %s: %w", p.Root, err)
+	}
+	if err := os.MkdirAll(p.Workflows, 0o700); err != nil {
+		return fmt.Errorf("create workflows %s: %w", p.Workflows, err)
+	}
+	for _, logPath := range []string{p.ServerLog, p.PluginLog} {
+		f, err := os.OpenFile(logPath, os.O_CREATE|os.O_APPEND|os.O_WRONLY, 0o600)
+		if err != nil {
+			return fmt.Errorf("create log %s: %w", logPath, err)
+		}
+		if err := f.Chmod(0o600); err != nil {
+			f.Close()
+			return fmt.Errorf("chmod log %s: %w", logPath, err)
+		}
+		if err := f.Close(); err != nil {
+			return fmt.Errorf("close log %s: %w", logPath, err)
+		}
+	}
+	return nil
+}

package/internal/recover/recover.go

@@ -0,0 +1,115 @@
+// Package recover implements `serve --recover` (5.6, design.md decision 22,
+// docs/structs-methods-interfaces.md lines 946-965). It runs once, inline,
+// after the engine is open and BEFORE normal pollers start, so recovered
+// runs exist before any poll cycle observes them.
+//
+// Steps per selected (repo, workflow, labeled-parent):
+//  1. Poll active parents (task systems already exclude parents completed
+//     through `end`).
+//  2. Filter to parents whose wf:<name> claim resolves to exactly one bound
+//     workflow via the router.
+//  3. Skip parents carrying the stable <runID>:cancellation marker.
+//  4. CloseTerminals on the run (preserves worktrees/branches/code).
+//  5. EnsureMailboxes (find existing, create only missing).
+//  6. ResetForRecovery on parent + mailboxes (adapter-owned; Jira moves
+//     mailboxes to `To Do` — core never names a status).
+//  7. EnsureRun creates a fresh deterministic run with fresh NodeVisitIDs
+//     and processes from `start`. Old routes/nodes/visits/timers are never
+//     resumed.
+//
+// Comments, labels, worktrees, branches, and code are preserved. Recovery
+// never runs automatically; database loss is never inferred.
+package recover
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"log/slog"
+	"sort"
+
+	"github.com/rajpopat27/relay-flow/internal/identity"
+	"github.com/rajpopat27/relay-flow/internal/repo"
+	"github.com/rajpopat27/relay-flow/internal/router"
+	"github.com/rajpopat27/relay-flow/internal/run"
+	"github.com/rajpopat27/relay-flow/internal/runner"
+	"github.com/rajpopat27/relay-flow/internal/task"
+	"github.com/rajpopat27/relay-flow/internal/workflow"
+)
+
+// MailboxSpecFor builds one spec per agent/HITL work node for a ticket. The
+// engine's MailboxSpecs supplies the production description content; this
+// indirection keeps recover decoupled from the engine package (which imports
+// internal/run and would otherwise form a cycle).
+type MailboxSpecFor func(wf *workflow.Workflow, ticketKey string) []task.MailboxSpec
+
+// FromTaskSystem is the `serve --recover` composition. Explicit flag only;
+// never automatic; database loss is never inferred.
+func FromTaskSystem(ctx context.Context, repoReg *repo.Registry, rnr runner.Runner, runManager *run.RunManager, specsFor MailboxSpecFor) error {
+	for _, rp := range repoReg.List() {
+		tickets, err := rp.TaskSystem.Poll(ctx)
+		if err != nil {
+			return fmt.Errorf("repo %q poll: %w", rp.Name, err)
+		}
+		for _, ticket := range tickets {
+			// Use the router's exact claim semantics: zero claims or zero
+			// matcher hits → ErrNoMatch (not ours, skip); multiple claims
+			// or an unknown/unbound claim → InvalidClaimError (ambiguous
+			// ownership, skip with a warn). Only tickets that resolve to
+			// exactly one bound workflow proceed.
+			wf, err := router.ResolveWorkflow(rp, ticket)
+			if errors.Is(err, router.ErrNoMatch) {
+				continue
+			}
+			if err != nil {
+				slog.Warn("recover: skip ticket with invalid claim", "ticket", ticket.Key, "error", err)
+				continue
+			}
+			// Skip canceled parents: the cancellation marker is the
+			// task-system recovery record.
+			runID := identity.NewRunID(rp.Name, wf.Name, ticket.Key)
+			marked, err := rp.TaskSystem.HasComment(ctx, task.Target{Parent: ticket.Ref()}, run.CancellationMarker(runID))
+			if err != nil {
+				return fmt.Errorf("repo %q ticket %s check cancellation marker: %w", rp.Name, ticket.Key, err)
+			}
+			if marked {
+				continue
+			}
+			// Close stale agent terminals; preserve workspace/code.
+			if err := rnr.CloseTerminals(ctx, runner.RunSpec{
+				RunID:     runID,
+				RepoName:  rp.Name,
+				RepoPath:  rp.Path,
+				TicketKey: ticket.Key,
+			}); err != nil {
+				return fmt.Errorf("repo %q ticket %s close terminals: %w", rp.Name, ticket.Key, err)
+			}
+			// EnsureMailboxes: find existing, create only missing. Specs are
+			// built by the caller (the engine supplies production content).
+			mailboxes, err := rp.TaskSystem.EnsureMailboxes(ctx, ticket.Ref(), wf.Name, specsFor(wf, ticket.Key))
+			if err != nil {
+				return fmt.Errorf("repo %q ticket %s ensure mailboxes: %w", rp.Name, ticket.Key, err)
+			}
+			// Deterministic ordering: sort mailbox keys so adapter-side
+			// effect ordering is reproducible across recoveries.
+			nodeNames := make([]string, 0, len(mailboxes))
+			for node := range mailboxes {
+				nodeNames = append(nodeNames, node)
+			}
+			sort.Strings(nodeNames)
+			mailboxList := make([]task.Mailbox, 0, len(mailboxes))
+			for _, node := range nodeNames {
+				mailboxList = append(mailboxList, mailboxes[node])
+			}
+			// ResetForRecovery: adapter-owned; resets parent + mailboxes.
+			if err := rp.TaskSystem.ResetForRecovery(ctx, ticket.Ref(), mailboxList, wf.TaskConfig); err != nil {
+				return fmt.Errorf("repo %q ticket %s reset for recovery: %w", rp.Name, ticket.Key, err)
+			}
+			// Fresh deterministic run; fresh NodeVisitIDs; from `start`.
+			if err := runManager.EnsureRun(ctx, rp, wf, ticket); err != nil {
+				return fmt.Errorf("repo %q ticket %s ensure run: %w", rp.Name, ticket.Key, err)
+			}
+		}
+	}
+	return nil
+}