devrites 4.5.0 → 4.7.0

package/engine/internal/parallel/ops_test.go

@@ -0,0 +1,211 @@
+package parallel
+
+import (
+	"errors"
+	"fmt"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+// commitIn makes a one-file green commit inside a worker worktree and returns
+// its transfer commit SHA.
+func commitIn(t *testing.T, wt, file, marker string) string {
+	t.Helper()
+	body := "package main\n\nfunc " + marker + "() {}\n"
+	if err := os.WriteFile(filepath.Join(wt, file), []byte(body), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	gitOk(t, wt, "add", file)
+	gitOk(t, wt, "commit", "-m", "slice "+marker)
+	return gitOk(t, wt, "rev-parse", "HEAD")
+}
+
+// greenBatch creates a running lease with two recorded-green slices.
+func greenBatch(t *testing.T, repo, base, slug, batch string) *Lease {
+	t.Helper()
+	lease, err := Create(CreateOpts{
+		Root:    repo,
+		Slug:    slug,
+		BatchID: batch,
+		BaseSHA: base,
+		Slices: []SlicePaths{
+			{ID: "slice-a", Paths: []string{"src/a.go"}},
+			{ID: "slice-b", Paths: []string{"src/b.go"}},
+		},
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+	tcA := commitIn(t, lease.Slices[0].WorktreePath, "src/a.go", "A")
+	tcB := commitIn(t, lease.Slices[1].WorktreePath, "src/b.go", "B")
+	if _, err := RecordGreen(repo, slug, "slice-a", tcA); err != nil {
+		t.Fatal(err)
+	}
+	if _, err := RecordGreen(repo, slug, "slice-b", tcB); err != nil {
+		t.Fatal(err)
+	}
+	return lease
+}
+
+type seamRestore struct {
+	origLease  func(string, *Lease) error
+	origRemove func(string, string) error
+	origWarn   func(string, ...any)
+}
+
+func swapSeams(t *testing.T) {
+	t.Helper()
+	s := seamRestore{origLease: writeLease, origRemove: removeWorktree, origWarn: warnf}
+	t.Cleanup(func() { writeLease, removeWorktree, warnf = s.origLease, s.origRemove, s.origWarn })
+}
+
+// TestIntegrateFailedTransitionSurvivesTransientWriteFailure proves the
+// integrate-failed lease transition is retried once when the first write
+// fails, so the on-disk lease honestly records integrate-failed instead of a
+// stale running status.
+func TestIntegrateFailedTransitionSurvivesTransientWriteFailure(t *testing.T) {
+	repo, base := setupRepo(t)
+	slug, batch := "demo-feature", "batch1"
+	greenBatch(t, repo, base, slug, batch)
+	leasePath, err := LeasePath(repo, slug)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	// Corrupt a transfer commit so Integrate fails mid-flight via fail().
+	corrupted, err := ReadLease(leasePath)
+	if err != nil {
+		t.Fatal(err)
+	}
+	corrupted.Slices[0].TransferCommit = strings.Repeat("deadbeef", 5)
+	if err := WriteLease(leasePath, corrupted); err != nil {
+		t.Fatal(err)
+	}
+
+	swapSeams(t)
+	calls := 0
+	writeLease = func(path string, l *Lease) error {
+		calls++
+		if calls == 1 {
+			return errors.New("transient lease write failure")
+		}
+		// delegates to the real WriteLease captured by swapSeams
+		return origWriteLease()(path, l)
+	}
+
+	_, got, err := Integrate(IntegrateOpts{Root: repo, Slug: slug, ApplyToControl: true})
+	if err == nil {
+		t.Fatal("expected integrate failure from corrupted transfer commit")
+	}
+	if calls != 2 {
+		t.Fatalf("lease write calls=%d want 2 (initial + one retry)", calls)
+	}
+	if got == nil || got.Status != StatusIntegrateFailed {
+		t.Fatalf("returned lease status=%v want integrate-failed", got)
+	}
+	onDisk, err := ReadLease(leasePath)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if onDisk.Status != StatusIntegrateFailed {
+		t.Fatalf("on-disk lease status=%s want integrate-failed", onDisk.Status)
+	}
+	if head := gitOk(t, repo, "rev-parse", "HEAD"); head != base {
+		t.Fatalf("control head %s want base %s", head, base)
+	}
+}
+
+// origWriteLease returns the real WriteLease bypassing any test override.
+func origWriteLease() func(string, *Lease) error {
+	return WriteLease
+}
+
+// TestIntegrateSurfacesStuckStagingWorktree proves a staging-worktree removal
+// failure on the integrate success path is propagated (fail closed, status
+// integrate-failed, control untouched) instead of silently compounding into
+// un-cleanable branch state.
+func TestIntegrateSurfacesStuckStagingWorktree(t *testing.T) {
+	repo, base := setupRepo(t)
+	slug, batch := "demo-feature", "batch1"
+	greenBatch(t, repo, base, slug, batch)
+	leasePath, err := LeasePath(repo, slug)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	swapSeams(t)
+	removeWorktree = func(string, string) error {
+		return errors.New("simulated locked staging worktree")
+	}
+
+	_, got, err := Integrate(IntegrateOpts{Root: repo, Slug: slug, ApplyToControl: true})
+	if err == nil {
+		t.Fatal("expected integrate to surface the stuck staging worktree")
+	}
+	if !strings.Contains(err.Error(), "staging worktree") {
+		t.Fatalf("error should name the staging worktree, got %v", err)
+	}
+	if got == nil || got.Status != StatusIntegrateFailed {
+		t.Fatalf("returned lease status=%v want integrate-failed", got)
+	}
+	onDisk, err := ReadLease(leasePath)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if onDisk.Status != StatusIntegrateFailed {
+		t.Fatalf("on-disk lease status=%s want integrate-failed", onDisk.Status)
+	}
+	if head := gitOk(t, repo, "rev-parse", "HEAD"); head != base {
+		t.Fatalf("control head %s want base %s (merge must not apply when staging cleanup fails)", head, base)
+	}
+}
+
+// TestCleanupWarnsOnFailedBranchCleanup proves Cleanup reports branch cleanup
+// failures instead of erasing the lease while orphans remain.
+func TestCleanupWarnsOnFailedBranchCleanup(t *testing.T) {
+	repo, base := setupRepo(t)
+	slug, batch := "demo-feature", "batch1"
+	lease, err := Create(CreateOpts{
+		Root:    repo,
+		Slug:    slug,
+		BatchID: batch,
+		BaseSHA: base,
+		Slices: []SlicePaths{
+			{ID: "slice-a", Paths: []string{"src/a.go"}},
+			{ID: "slice-b", Paths: []string{"src/b.go"}},
+		},
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+	branchA := lease.Slices[0].Branch
+
+	swapSeams(t)
+	// Removal "fails" without removing; Cleanup's own RemoveAll then deletes
+	// the worktree directory while the stale git registration still lists the
+	// branch as checked out, so deleteBranch refuses and must be reported.
+	removeWorktree = func(string, string) error {
+		return errors.New("simulated stuck worker worktree")
+	}
+	var warnings []string
+	warnf = func(format string, args ...any) {
+		warnings = append(warnings, fmt.Sprintf(format, args...))
+	}
+
+	if err := Cleanup(repo, slug, true); err != nil {
+		t.Fatalf("cleanup continues after reporting failures: %v", err)
+	}
+	joined := strings.Join(warnings, "\n")
+	if !strings.Contains(joined, branchA) {
+		t.Fatalf("warnings should name the stuck branch %s, got:\n%s", branchA, joined)
+	}
+	leasePath, err := LeasePath(repo, slug)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if _, err := os.Stat(leasePath); !os.IsNotExist(err) {
+		t.Fatalf("cleanup should still clear the lease, got %v", err)
+	}
+}

package/engine/internal/state/cmd/workflowmanifest/main.go

@@ -7,6 +7,7 @@ import (
 	"encoding/json"
 	"flag"
 	"fmt"
+	"io"
 	"os"
 
 	"github.com/devrites/devrites/internal/state"
@@ -42,9 +43,19 @@ func workflowPhases() []workflowPhase {
 }
 
 func main() {
-	outPath := flag.String("out", "workflow_manifest.json", "output path")
-	check := flag.Bool("check", false, "fail when the output is stale")
-	flag.Parse()
+	os.Exit(run(os.Args[1:], os.Stderr))
+}
+
+// run is the testable entry point. It returns the process exit code.
+func run(args []string, stderr io.Writer) int {
+	flags := flag.NewFlagSet("workflowmanifest", flag.ContinueOnError)
+	flags.SetOutput(io.Discard)
+	outPath := flags.String("out", "workflow_manifest.json", "output path")
+	check := flags.Bool("check", false, "fail when the output is stale")
+	if err := flags.Parse(args); err != nil {
+		fmt.Fprintln(stderr, err)
+		return 2
+	}
 
 	document := struct {
 		GeneratedBy      string                 `json:"generatedBy"`
@@ -61,25 +72,25 @@ func main() {
 	}
 	data, err := json.MarshalIndent(document, "", "  ")
 	if err != nil {
-		fatal(err)
+		fmt.Fprintln(stderr, err)
+		return 1
 	}
 	data = append(data, '\n')
 	if *check {
 		current, err := os.ReadFile(*outPath)
 		if err != nil {
-			fatal(err)
+			fmt.Fprintln(stderr, err)
+			return 1
 		}
 		if !bytes.Equal(current, data) {
-			fatal(fmt.Errorf("%s is stale; run go generate ./internal/state", *outPath))
+			fmt.Fprintf(stderr, "%s is stale; run go generate ./internal/state\n", *outPath)
+			return 1
 		}
-		return
+		return 0
 	}
 	if err := os.WriteFile(*outPath, data, 0o644); err != nil {
-		fatal(err)
+		fmt.Fprintln(stderr, err)
+		return 1
 	}
-}
-
-func fatal(err error) {
-	fmt.Fprintln(os.Stderr, err)
-	os.Exit(1)
+	return 0
 }

package/engine/internal/state/cmd/workflowmanifest/main_test.go

@@ -0,0 +1,96 @@
+package main
+
+import (
+	"bytes"
+	"encoding/json"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"github.com/devrites/devrites/internal/state"
+)
+
+func TestRunWritesDeterministicManifest(t *testing.T) {
+	dir := t.TempDir()
+	out := filepath.Join(dir, "workflow_manifest.json")
+
+	if code := run([]string{"--out", out}, os.Stderr); code != 0 {
+		t.Fatalf("run exit=%d", code)
+	}
+	first, err := os.ReadFile(out)
+	if err != nil {
+		t.Fatal(err)
+	}
+	var document struct {
+		GeneratedBy   string `json:"generatedBy"`
+		SchemaVersion int    `json:"schemaVersion"`
+		Phases        []struct {
+			ID              state.Phase `json:"id"`
+			TransitionRight string      `json:"transitionRight"`
+		} `json:"phases"`
+	}
+	if err := json.Unmarshal(first, &document); err != nil {
+		t.Fatalf("manifest is not valid JSON: %v", err)
+	}
+	if document.SchemaVersion != state.SchemaVersion {
+		t.Fatalf("schemaVersion=%d want %d", document.SchemaVersion, state.SchemaVersion)
+	}
+	if !strings.HasPrefix(document.GeneratedBy, "go generate ./internal/state") {
+		t.Fatalf("generatedBy %q", document.GeneratedBy)
+	}
+	if len(document.Phases) == 0 {
+		t.Fatal("manifest must list phases")
+	}
+
+	// Deterministic: a second run produces identical bytes.
+	if code := run([]string{"--out", out}, os.Stderr); code != 0 {
+		t.Fatalf("second run exit=%d", code)
+	}
+	second, err := os.ReadFile(out)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !bytes.Equal(first, second) {
+		t.Fatal("manifest output is not deterministic")
+	}
+}
+
+func TestRunCheckPassesOnCurrentAndFailsOnStale(t *testing.T) {
+	dir := t.TempDir()
+	out := filepath.Join(dir, "workflow_manifest.json")
+
+	if code := run([]string{"--out", out}, os.Stderr); code != 0 {
+		t.Fatalf("generate exit=%d", code)
+	}
+	if code := run([]string{"--out", out, "--check"}, os.Stderr); code != 0 {
+		t.Fatalf("check on current manifest exit=%d", code)
+	}
+
+	if err := os.WriteFile(out, []byte("{\"stale\": true}\n"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	stderr := &strings.Builder{}
+	if code := run([]string{"--out", out, "--check"}, stderr); code != 1 {
+		t.Fatalf("check on stale manifest exit=%d want 1", code)
+	}
+	if !strings.Contains(stderr.String(), "is stale") {
+		t.Fatalf("stderr should name the stale manifest, got %q", stderr.String())
+	}
+}
+
+func TestRunCheckFailsOnMissingManifest(t *testing.T) {
+	dir := t.TempDir()
+	missing := filepath.Join(dir, "absent.json")
+	stderr := &strings.Builder{}
+	if code := run([]string{"--out", missing, "--check"}, stderr); code != 1 {
+		t.Fatalf("check on missing manifest exit=%d want 1", code)
+	}
+}
+
+func TestRunRejectsUnknownFlags(t *testing.T) {
+	stderr := &strings.Builder{}
+	if code := run([]string{"--bogus"}, stderr); code != 2 {
+		t.Fatalf("unknown flag exit=%d want 2", code)
+	}
+}

package/engine/internal/state/cursor.go

@@ -20,6 +20,7 @@ const (
 	CursorAFKSlicesRemaining = "afk_slices_remaining"
 	CursorReturnPhase        = "return_phase"
 	CursorReturnNextAction   = "return_next_action"
+	CursorSchema             = "schema"
 )
 
 var cursorKeyAliases = map[string]string{
@@ -168,6 +169,79 @@ func DeleteCursorField(lines []string, key string) []string {
 	return out
 }
 
+// CursorForm reports the presentation of the state.md cursor: "table" when a
+// canonical table row exists, "legacy" when only bullet fields exist, and
+// "none" when neither is present.
+func CursorForm(lines []string) string {
+	form := "none"
+	for _, line := range lines {
+		_, _, kind, ok := parseCursorLine(line)
+		if !ok {
+			continue
+		}
+		if kind == cursorLineTable {
+			return "table"
+		}
+		if form == "none" {
+			form = "legacy"
+		}
+	}
+	return form
+}
+
+// ConvertCursorToTable rewrites legacy bullet cursor fields into canonical
+// table rows in place. A bullet whose key resolves to a canonical cursor key
+// is a cursor field wherever it appears — the same rule CursorField uses to
+// read — so such a bullet is converted even inside prose sections. Prose
+// without a canonical cursor key is preserved, and a value carrying a raw pipe
+// keeps its bullet form because a table cell cannot represent it. It reports
+// whether any line changed.
+func ConvertCursorToTable(lines []string) ([]string, bool) {
+	changed := false
+	out := append([]string(nil), lines...)
+	for i, line := range out {
+		key, value, kind, ok := parseCursorLine(line)
+		if !ok || kind != cursorLineLegacy {
+			continue
+		}
+		if !isMigratableCursorKey(key) {
+			continue
+		}
+		if strings.Contains(value, "|") {
+			continue
+		}
+		spelling, ok := canonicalCursorSpelling(key)
+		if !ok {
+			continue
+		}
+		indent := line[:len(line)-len(strings.TrimLeft(line, " \t"))]
+		out[i] = indent + "| " + spelling + " | " + value + " |"
+		changed = true
+	}
+	return out, changed
+}
+
+func isMigratableCursorKey(key string) bool {
+	_, ok := canonicalCursorSpelling(key)
+	return ok
+}
+
+// canonicalCursorSpelling maps a cursor key (including aliases) to the
+// canonical table-row spelling. Matching is normalization-based, so
+// "Next step" resolves to the "next_action" spelling.
+func canonicalCursorSpelling(key string) (string, bool) {
+	normalized := normalizeCursorKey(key)
+	canonicals := []string{CursorPhase, CursorStatus, CursorNextAction, CursorQuestionID,
+		CursorActiveSlice, CursorAFKSlicesRemaining, CursorReturnPhase,
+		CursorReturnNextAction, CursorSchema}
+	for _, canonical := range canonicals {
+		if normalized == normalizeCursorKey(canonical) {
+			return canonical, true
+		}
+	}
+	return "", false
+}
+
 func structuralCursorLines(lines []string) ([]string, bool) {
 	if len(lines) == 0 {
 		return nil, true

package/engine/internal/state/schema.go

@@ -2,8 +2,9 @@ package state
 
 //go:generate go run ./cmd/workflowmanifest -out workflow_manifest.json
 
-// SchemaVersion versions the persisted workflow/state manifest.
-const SchemaVersion = 2
+// SchemaVersion versions the persisted workflow/state manifest and the
+// workspace contract the engine accepts.
+const SchemaVersion = 3
 
 const EvidenceFile = "evidence.md"
 

package/engine/internal/state/state_test.go

@@ -703,7 +703,7 @@ func TestStatusRejectsCorruptStateMarkdownWithoutContentDisclosure(t *testing.T)
 	if err := os.MkdirAll(dir, 0o755); err != nil {
 		t.Fatal(err)
 	}
-	if err := os.WriteFile(filepath.Join(dir, "state.md"), []byte("| phase | build |\x00\n"), 0o644); err != nil {
+	if err := os.WriteFile(filepath.Join(dir, "state.md"), []byte("| phase | build |\x00\n| schema | 3 |\n"), 0o644); err != nil {
 		t.Fatal(err)
 	}
 	want := `compute status: feature "corrupt": state.md is malformed (malformed_markdown); repair state.md and retry`
@@ -720,7 +720,7 @@ func TestOnlyCanonicalWorkLayoutIsDiscovered(t *testing.T) {
 	if err := os.MkdirAll(legacy, 0o755); err != nil {
 		t.Fatal(err)
 	}
-	if err := os.WriteFile(filepath.Join(legacy, "state.md"), []byte("- Phase: spec\n"), 0o644); err != nil {
+	if err := os.WriteFile(filepath.Join(legacy, "state.md"), []byte("- Phase: spec\n- Schema: 3\n"), 0o644); err != nil {
 		t.Fatal(err)
 	}
 	if _, err := Status(root, "alias"); err == nil {

package/engine/internal/state/workflow_manifest.json

@@ -1,6 +1,6 @@
 {
   "generatedBy": "go generate ./internal/state; DO NOT EDIT",
-  "schemaVersion": 2,
+  "schemaVersion": 3,
   "authorityPolicy": {
     "principlesTrust": "Project principles may become project policy only after explicit provenance and validation; arbitrary project-local Markdown is never inherently trusted executable instruction.",
     "trackedState": [

package/engine/internal/state/workspaceschema.go

@@ -0,0 +1,58 @@
+package state
+
+import (
+	"errors"
+	"fmt"
+	"os"
+	"path/filepath"
+	"strconv"
+	"strings"
+)
+
+// ErrWorkspaceSchemaRefused identifies a workspace whose declared schema is not
+// the current engine contract; callers map it to the blocked exit code.
+var ErrWorkspaceSchemaRefused = errors.New("workspace schema version refused")
+
+// workspaceSchemaKey is the state.md cursor row carrying the workspace schema
+// version. Workspaces written before the v5 engine carry no row and resolve to
+// schema 2, the last pre-v5 contract.
+const workspaceSchemaKey = CursorSchema
+
+// WorkspaceSchema reports the schema version declared by the feature's
+// state.md cursor. A missing row means the pre-v5 (schema 2) contract.
+func WorkspaceSchema(root, slug string) (int, error) {
+	raw, err := os.ReadFile(filepath.Join(featureDir(root, slug), LedgerFile))
+	if err != nil {
+		return 0, fmt.Errorf("read workspace schema for %s: %w", slug, err)
+	}
+	lines := strings.Split(strings.ReplaceAll(string(raw), "\r\n", "\n"), "\n")
+	return workspaceSchemaRow(lines)
+}
+
+// RequireWorkspaceSchema refuses feature workspaces whose schema is not the
+// current one, naming the exact recovery path for each direction.
+func RequireWorkspaceSchema(root, slug string) error {
+	version, err := WorkspaceSchema(root, slug)
+	if err != nil {
+		return err
+	}
+	if version < SchemaVersion {
+		return fmt.Errorf("%w: workspace %s predates the v5 workspace schema (schema %d, engine requires %d); run devrites-engine migrate %s", ErrWorkspaceSchemaRefused, slug, version, SchemaVersion, slug)
+	}
+	if version > SchemaVersion {
+		return fmt.Errorf("%w: workspace %s declares schema %d, newer than this engine's %d; upgrade devrites", ErrWorkspaceSchemaRefused, slug, version, SchemaVersion)
+	}
+	return nil
+}
+
+func workspaceSchemaRow(lines []string) (int, error) {
+	value, ok := CursorField(lines, workspaceSchemaKey)
+	if !ok {
+		return 2, nil
+	}
+	version, err := strconv.Atoi(strings.TrimSpace(value))
+	if err != nil || version <= 0 {
+		return 0, fmt.Errorf("state.md schema row is invalid (value %q); expected the workspace schema version", value)
+	}
+	return version, nil
+}

package/engine/internal/state/workspaceschema_test.go

@@ -0,0 +1,67 @@
+package state
+
+import (
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+func writeSchemaWorkspace(t *testing.T, stateBody string) (root, slug string) {
+	t.Helper()
+	root = t.TempDir()
+	slug = "demo"
+	if err := os.MkdirAll(featureDir(root, slug), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(featureDir(root, slug), LedgerFile), []byte(stateBody), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	return root, slug
+}
+
+func TestWorkspaceSchemaDefaultsToPreV5WhenRowIsAbsent(t *testing.T) {
+	root, slug := writeSchemaWorkspace(t, "- Phase: build\n- Status: running\n")
+	version, err := WorkspaceSchema(root, slug)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if version != 2 {
+		t.Fatalf("version=%d want 2 (pre-v5 default)", version)
+	}
+	if err := RequireWorkspaceSchema(root, slug); err == nil {
+		t.Fatal("pre-v5 workspace must be refused")
+	} else if !strings.Contains(err.Error(), "devrites-engine migrate demo") {
+		t.Fatalf("refusal must name migrate, got %v", err)
+	}
+}
+
+func TestWorkspaceSchemaAcceptsCurrentAndRefusesNewer(t *testing.T) {
+	root, slug := writeSchemaWorkspace(t, "| phase | build |\n| schema | 3 |\n")
+	if err := RequireWorkspaceSchema(root, slug); err != nil {
+		t.Fatalf("current schema must pass, got %v", err)
+	}
+
+	root, slug = writeSchemaWorkspace(t, "| phase | build |\n| schema | 4 |\n")
+	err := RequireWorkspaceSchema(root, slug)
+	if err == nil {
+		t.Fatal("newer schema must be refused")
+	}
+	if !strings.Contains(err.Error(), "upgrade devrites") {
+		t.Fatalf("newer-schema refusal must name the upgrade path, got %v", err)
+	}
+}
+
+func TestWorkspaceSchemaRefusesMalformedRow(t *testing.T) {
+	root, slug := writeSchemaWorkspace(t, "| phase | build |\n| schema | banana |\n")
+	if err := RequireWorkspaceSchema(root, slug); err == nil {
+		t.Fatal("malformed schema row must be refused")
+	}
+}
+
+func TestWorkspaceSchemaMissingLedgerIsRefused(t *testing.T) {
+	root := t.TempDir()
+	if err := RequireWorkspaceSchema(root, "absent"); err == nil {
+		t.Fatal("missing workspace must be refused")
+	}
+}