devrites 5.11.0 → 5.12.0

package/engine/internal/lib/claims.go

@@ -0,0 +1,411 @@
+package lib
+
+import (
+	"bufio"
+	"crypto/rand"
+	"encoding/hex"
+	"encoding/json"
+	"fmt"
+	"io"
+	"os"
+	"path/filepath"
+	"sort"
+	"strconv"
+	"strings"
+	"time"
+
+	"github.com/devrites/devrites/internal/parallel"
+)
+
+// ClaimsFile is the repo-level append-only claim ledger under .devrites.
+// Advisory, session-scoped file claims let concurrent agent sessions sharing
+// one working tree see each other's write intent before overlapping edits
+// collide. A claim never blocks a writer by force — it surfaces the conflict
+// so the second session can route around it or stop for the human.
+const ClaimsFile = "claims.jsonl"
+
+const (
+	claimDefaultTTL = 30
+	claimMinTTL     = 1
+	claimMaxTTL     = 240
+)
+
+const claimUsage = `usage: devrites-engine claim <add|release|list|check> ...
+
+  claim add --session <id> [--ttl <minutes>] [--reason <s>] <path>...
+  claim release --session <id> --id <claim-id>
+  claim list [--session <id>] [--all]
+  claim check [--session <id>] <path>...
+`
+
+type claimRecord struct {
+	ID        string   `json:"id"`
+	Session   string   `json:"session"`
+	Paths     []string `json:"paths"`
+	Reason    string   `json:"reason,omitempty"`
+	ClaimedAt string   `json:"claimed_at"`
+	ExpiresAt string   `json:"expires_at"`
+	Released  bool     `json:"released,omitempty"`
+}
+
+// RunClaim manages the advisory file-claim ledger.
+func RunClaim(root string, args []string, stdout, stderr io.Writer) int {
+	if len(args) == 0 {
+		fmt.Fprint(stderr, claimUsage)
+		return 2
+	}
+	sub, rest := args[0], args[1:]
+	switch sub {
+	case "add":
+		return claimAdd(root, rest, stdout, stderr)
+	case "release":
+		return claimRelease(root, rest, stdout, stderr)
+	case "list":
+		return claimList(root, rest, stdout, stderr)
+	case "check":
+		return claimCheck(root, rest, stdout, stderr)
+	default:
+		fmt.Fprintf(stderr, "devrites: unknown claim command %q\n", sub)
+		return 2
+	}
+}
+
+func claimsPath(root string) string {
+	return filepath.Join(root, ClaimsFile)
+}
+
+func readClaims(path string) (latest map[string]*claimRecord, order []string, bad int, err error) {
+	latest = map[string]*claimRecord{}
+	f, err := os.Open(path) // #nosec G304 -- path is the validated project claims ledger
+	if err != nil {
+		if os.IsNotExist(err) {
+			return latest, nil, 0, nil
+		}
+		return nil, nil, 0, err
+	}
+	defer func() { _ = f.Close() }()
+	scanner := bufio.NewScanner(f)
+	scanner.Buffer(make([]byte, 64<<10), 1<<20)
+	for scanner.Scan() {
+		line := strings.TrimSpace(scanner.Text())
+		if line == "" {
+			continue
+		}
+		var rec claimRecord
+		if json.Unmarshal([]byte(line), &rec) != nil || rec.ID == "" || rec.Session == "" {
+			bad++
+			continue
+		}
+		if _, seen := latest[rec.ID]; !seen {
+			order = append(order, rec.ID)
+		}
+		r := rec
+		latest[rec.ID] = &r
+	}
+	return latest, order, bad, scanner.Err()
+}
+
+func liveClaims(latest map[string]*claimRecord, order []string, now time.Time) []*claimRecord {
+	var out []*claimRecord
+	for _, id := range order {
+		rec := latest[id]
+		if rec == nil || rec.Released {
+			continue
+		}
+		expires, err := time.Parse(time.RFC3339, rec.ExpiresAt)
+		if err != nil || !expires.After(now) {
+			continue
+		}
+		out = append(out, rec)
+	}
+	return out
+}
+
+func appendClaim(path string, rec *claimRecord) error {
+	line, err := json.Marshal(rec)
+	if err != nil {
+		return err
+	}
+	f, err := os.OpenFile(path, os.O_APPEND|os.O_CREATE|os.O_WRONLY, 0o600) // #nosec G304 -- path is the validated project claims ledger
+	if err != nil {
+		return err
+	}
+	_, werr := f.Write(append(line, '\n'))
+	cerr := f.Close()
+	if werr != nil {
+		return werr
+	}
+	return cerr
+}
+
+func normalizeClaimPaths(raw []string) ([]string, error) {
+	if len(raw) == 0 {
+		return nil, fmt.Errorf("at least one path is required")
+	}
+	seen := map[string]struct{}{}
+	out := make([]string, 0, len(raw))
+	for _, p := range raw {
+		norm, err := parallel.NormalizePath(p)
+		if err != nil {
+			return nil, err
+		}
+		if norm == ".devrites" || strings.HasPrefix(norm, ".devrites/") ||
+			norm == ".git" || strings.HasPrefix(norm, ".git/") {
+			return nil, fmt.Errorf("path must not claim control-tree or git internals: %q", norm)
+		}
+		if _, dup := seen[norm]; dup {
+			return nil, fmt.Errorf("duplicate path %q", norm)
+		}
+		seen[norm] = struct{}{}
+		out = append(out, norm)
+	}
+	sort.Strings(out)
+	return out, nil
+}
+
+func validSession(s string) bool {
+	if s == "" || len(s) > 128 {
+		return false
+	}
+	for _, r := range s {
+		if !(r >= 'a' && r <= 'z' || r >= 'A' && r <= 'Z' || r >= '0' && r <= '9' ||
+			r == '-' || r == '_' || r == '.' || r == ':' || r == '/') {
+			return false
+		}
+	}
+	return true
+}
+
+// claimConflicts returns live claims by other sessions covering any path.
+func claimConflicts(live []*claimRecord, session string, paths []string) []*claimRecord {
+	want := map[string]struct{}{}
+	for _, p := range paths {
+		want[p] = struct{}{}
+	}
+	var out []*claimRecord
+	for _, rec := range live {
+		if rec.Session == session {
+			continue
+		}
+		for _, p := range rec.Paths {
+			if _, hit := want[p]; hit {
+				out = append(out, rec)
+				break
+			}
+		}
+	}
+	return out
+}
+
+func printConflicts(w io.Writer, conflicts []*claimRecord) {
+	for _, rec := range conflicts {
+		fmt.Fprintf(w, "claim: BLOCKED: %s held by session %q until %s", strings.Join(rec.Paths, ","), rec.Session, rec.ExpiresAt)
+		if rec.Reason != "" {
+			fmt.Fprintf(w, " (%s)", rec.Reason)
+		}
+		fmt.Fprintln(w)
+	}
+}
+
+func newClaimID() string {
+	var b [4]byte
+	if _, err := rand.Read(b[:]); err != nil {
+		return fmt.Sprintf("cl-%d", time.Now().UnixNano())
+	}
+	return fmt.Sprintf("cl-%d-%s", time.Now().UnixNano(), hex.EncodeToString(b[:]))
+}
+
+func claimAdd(root string, args []string, stdout, stderr io.Writer) int {
+	session, reason := "", ""
+	ttl := claimDefaultTTL
+	var raw []string
+	for i := 0; i < len(args); i++ {
+		switch args[i] {
+		case "--session":
+			session = argAt(args, i+1)
+			i++
+		case "--reason":
+			reason = argAt(args, i+1)
+			i++
+		case "--ttl":
+			n, err := strconv.Atoi(argAt(args, i+1))
+			if err != nil {
+				fmt.Fprintf(stderr, "claim: --ttl expects minutes, got %q\n", argAt(args, i+1))
+				return 2
+			}
+			ttl = min(max(n, claimMinTTL), claimMaxTTL)
+			i++
+		default:
+			raw = append(raw, args[i])
+		}
+	}
+	if !validSession(session) {
+		fmt.Fprintln(stderr, "claim: --session is required (1-128 chars: letters, digits, - _ . : /)")
+		return 2
+	}
+	paths, err := normalizeClaimPaths(raw)
+	if err != nil {
+		fmt.Fprintf(stderr, "claim: %v\n", err)
+		return 2
+	}
+	path := claimsPath(root)
+	latest, order, _, err := readClaims(path)
+	if err != nil {
+		fmt.Fprintf(stderr, "claim: %v\n", err)
+		return 2
+	}
+	now := time.Now().UTC()
+	conflicts := claimConflicts(liveClaims(latest, order, now), session, paths)
+	if len(conflicts) > 0 {
+		printConflicts(stderr, conflicts)
+		return 3
+	}
+	rec := &claimRecord{
+		ID:        newClaimID(),
+		Session:   session,
+		Paths:     paths,
+		Reason:    reason,
+		ClaimedAt: now.Format(time.RFC3339),
+		ExpiresAt: now.Add(time.Duration(ttl) * time.Minute).Format(time.RFC3339),
+	}
+	if err := appendClaim(path, rec); err != nil {
+		fmt.Fprintf(stderr, "claim: %v\n", err)
+		return 2
+	}
+	fmt.Fprintf(stdout, "claim: %s claimed %d path(s) until %s\n", rec.ID, len(paths), rec.ExpiresAt)
+	return 0
+}
+
+func claimRelease(root string, args []string, stdout, stderr io.Writer) int {
+	session, id := "", ""
+	for i := 0; i < len(args); i++ {
+		switch args[i] {
+		case "--session":
+			session = argAt(args, i+1)
+			i++
+		case "--id":
+			id = argAt(args, i+1)
+			i++
+		default:
+			fmt.Fprintf(stderr, "claim: unknown flag %q\n", args[i])
+			return 2
+		}
+	}
+	if session == "" || id == "" {
+		fmt.Fprintln(stderr, "claim: release requires --session and --id")
+		return 2
+	}
+	path := claimsPath(root)
+	latest, _, _, err := readClaims(path)
+	if err != nil {
+		fmt.Fprintf(stderr, "claim: %v\n", err)
+		return 2
+	}
+	rec, ok := latest[id]
+	if !ok {
+		fmt.Fprintf(stderr, "claim: unknown claim %q\n", id)
+		return 2
+	}
+	if rec.Session != session {
+		fmt.Fprintf(stderr, "claim: %q belongs to session %q, not %q\n", id, rec.Session, session)
+		return 2
+	}
+	if rec.Released {
+		fmt.Fprintf(stderr, "claim: %q already released\n", id)
+		return 2
+	}
+	released := *rec
+	released.Released = true
+	if err := appendClaim(path, &released); err != nil {
+		fmt.Fprintf(stderr, "claim: %v\n", err)
+		return 2
+	}
+	fmt.Fprintf(stdout, "claim: %s released %d path(s)\n", id, len(rec.Paths))
+	return 0
+}
+
+func claimList(root string, args []string, stdout, stderr io.Writer) int {
+	session := ""
+	all := false
+	for i := 0; i < len(args); i++ {
+		switch args[i] {
+		case "--session":
+			session = argAt(args, i+1)
+			i++
+		case "--all":
+			all = true
+		default:
+			fmt.Fprintf(stderr, "claim: unknown flag %q\n", args[i])
+			return 2
+		}
+	}
+	latest, order, bad, err := readClaims(claimsPath(root))
+	if err != nil {
+		fmt.Fprintf(stderr, "claim: %v\n", err)
+		return 2
+	}
+	now := time.Now().UTC()
+	rows := liveClaims(latest, order, now)
+	if all {
+		rows = rows[:0]
+		for _, id := range order {
+			rows = append(rows, latest[id])
+		}
+	}
+	printed := 0
+	for _, rec := range rows {
+		if rec == nil || (session != "" && rec.Session != session) {
+			continue
+		}
+		state := "live"
+		if rec.Released {
+			state = "released"
+		} else if exp, err := time.Parse(time.RFC3339, rec.ExpiresAt); err != nil || !exp.After(now) {
+			state = "expired"
+		}
+		fmt.Fprintf(stdout, "%s %-8s session=%s paths=%s until=%s", rec.ID, state, rec.Session, strings.Join(rec.Paths, ","), rec.ExpiresAt)
+		if rec.Reason != "" {
+			fmt.Fprintf(stdout, " reason=%q", rec.Reason)
+		}
+		fmt.Fprintln(stdout)
+		printed++
+	}
+	if printed == 0 {
+		fmt.Fprintln(stdout, "claim: no claims")
+	}
+	if bad > 0 {
+		fmt.Fprintf(stdout, "claim: %d unparsed ledger line(s)\n", bad)
+	}
+	return 0
+}
+
+func claimCheck(root string, args []string, stdout, stderr io.Writer) int {
+	session := ""
+	var raw []string
+	for i := 0; i < len(args); i++ {
+		switch args[i] {
+		case "--session":
+			session = argAt(args, i+1)
+			i++
+		default:
+			raw = append(raw, args[i])
+		}
+	}
+	paths, err := normalizeClaimPaths(raw)
+	if err != nil {
+		fmt.Fprintf(stderr, "claim: %v\n", err)
+		return 2
+	}
+	latest, order, _, err := readClaims(claimsPath(root))
+	if err != nil {
+		fmt.Fprintf(stderr, "claim: %v\n", err)
+		return 2
+	}
+	conflicts := claimConflicts(liveClaims(latest, order, time.Now().UTC()), session, paths)
+	if len(conflicts) > 0 {
+		printConflicts(stdout, conflicts)
+		return 3
+	}
+	fmt.Fprintf(stdout, "claim: %d path(s) free\n", len(paths))
+	return 0
+}

package/engine/internal/lib/claims_test.go

@@ -0,0 +1,182 @@
+package lib
+
+import (
+	"bytes"
+	"encoding/json"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+	"time"
+)
+
+func claimTestRoot(t *testing.T) string {
+	t.Helper()
+	root := filepath.Join(t.TempDir(), ".devrites")
+	if err := os.MkdirAll(root, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	return root
+}
+
+func runClaim(t *testing.T, root string, args ...string) (int, string, string) {
+	t.Helper()
+	var out, errOut bytes.Buffer
+	code := RunClaim(root, args, &out, &errOut)
+	return code, out.String(), errOut.String()
+}
+
+func TestClaimAddAndList(t *testing.T) {
+	root := claimTestRoot(t)
+	code, out, errOut := runClaim(t, root, "add", "--session", "s1", "--reason", "slice work", "pkg/a.go", "pkg/b.go")
+	if code != 0 {
+		t.Fatalf("add: code=%d stderr=%s", code, errOut)
+	}
+	if !strings.Contains(out, "cl-") || !strings.Contains(out, "2 path(s)") {
+		t.Fatalf("add output missing claim id/paths: %q", out)
+	}
+	code, out, _ = runClaim(t, root, "list")
+	if code != 0 || !strings.Contains(out, "session=s1") || !strings.Contains(out, "pkg/a.go") {
+		t.Fatalf("list: code=%d out=%q", code, out)
+	}
+}
+
+func TestClaimConflictBlocks(t *testing.T) {
+	root := claimTestRoot(t)
+	if code, _, e := runClaim(t, root, "add", "--session", "s1", "pkg/a.go"); code != 0 {
+		t.Fatalf("first add: %d %s", code, e)
+	}
+	code, _, errOut := runClaim(t, root, "add", "--session", "s2", "pkg/a.go")
+	if code != 3 {
+		t.Fatalf("conflicting add should exit 3, got %d", code)
+	}
+	if !strings.Contains(errOut, "BLOCKED") || !strings.Contains(errOut, "s1") {
+		t.Fatalf("conflict output should name holder: %q", errOut)
+	}
+	// Same session re-claim is allowed.
+	if code, _, e := runClaim(t, root, "add", "--session", "s1", "pkg/a.go"); code != 0 {
+		t.Fatalf("same-session re-claim: %d %s", code, e)
+	}
+	// Disjoint path is fine for another session.
+	if code, _, e := runClaim(t, root, "add", "--session", "s2", "pkg/c.go"); code != 0 {
+		t.Fatalf("disjoint add: %d %s", code, e)
+	}
+}
+
+func TestClaimCheck(t *testing.T) {
+	root := claimTestRoot(t)
+	code, out, _ := runClaim(t, root, "check", "pkg/a.go")
+	if code != 0 || !strings.Contains(out, "free") {
+		t.Fatalf("check free: %d %q", code, out)
+	}
+	if code, _, e := runClaim(t, root, "add", "--session", "s1", "pkg/a.go"); code != 0 {
+		t.Fatalf("add: %d %s", code, e)
+	}
+	code, out, _ = runClaim(t, root, "check", "--session", "s2", "pkg/a.go", "pkg/z.go")
+	if code != 3 || !strings.Contains(out, "s1") {
+		t.Fatalf("check conflict: %d %q", code, out)
+	}
+	// Holder's own check is free.
+	code, out, _ = runClaim(t, root, "check", "--session", "s1", "pkg/a.go")
+	if code != 0 {
+		t.Fatalf("check own: %d %q", code, out)
+	}
+}
+
+func TestClaimRelease(t *testing.T) {
+	root := claimTestRoot(t)
+	code, out, _ := runClaim(t, root, "add", "--session", "s1", "pkg/a.go")
+	if code != 0 {
+		t.Fatalf("add: %d", code)
+	}
+	id := strings.Fields(out)[1]
+	// Wrong session cannot release.
+	if code, _, e := runClaim(t, root, "release", "--session", "s2", "--id", id); code != 2 {
+		t.Fatalf("release by wrong session: %d %s", code, e)
+	}
+	if code, _, e := runClaim(t, root, "release", "--session", "s1", "--id", id); code != 0 {
+		t.Fatalf("release: %d %s", code, e)
+	}
+	// Released claim no longer conflicts.
+	code, _, _ = runClaim(t, root, "check", "--session", "s2", "pkg/a.go")
+	if code != 0 {
+		t.Fatalf("check after release: %d", code)
+	}
+	// Double release is a usage error.
+	if code, _, _ := runClaim(t, root, "release", "--session", "s1", "--id", id); code != 2 {
+		t.Fatalf("double release: %d", code)
+	}
+	// Unknown id.
+	if code, _, _ := runClaim(t, root, "release", "--session", "s1", "--id", "cl-nope"); code != 2 {
+		t.Fatalf("unknown release: %d", code)
+	}
+}
+
+func TestClaimExpiry(t *testing.T) {
+	root := claimTestRoot(t)
+	path := filepath.Join(root, ClaimsFile)
+	old := claimRecord{
+		ID:        "cl-old",
+		Session:   "s1",
+		Paths:     []string{"pkg/a.go"},
+		ClaimedAt: time.Now().UTC().Add(-time.Hour).Format(time.RFC3339),
+		ExpiresAt: time.Now().UTC().Add(-time.Minute).Format(time.RFC3339),
+	}
+	line, _ := json.Marshal(old)
+	if err := os.WriteFile(path, append(line, '\n'), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	// Expired claims do not conflict and do not list by default.
+	code, _, errOut := runClaim(t, root, "add", "--session", "s2", "pkg/a.go")
+	if code != 0 {
+		t.Fatalf("add over expired: %d %s", code, errOut)
+	}
+	code, out, _ := runClaim(t, root, "list")
+	if code != 0 || strings.Contains(out, "cl-old") {
+		t.Fatalf("list should hide expired: %d %q", code, out)
+	}
+	code, out, _ = runClaim(t, root, "list", "--all")
+	if code != 0 || !strings.Contains(out, "cl-old") || !strings.Contains(out, "expired") {
+		t.Fatalf("list --all should show expired: %d %q", code, out)
+	}
+}
+
+func TestClaimRejectsBadInput(t *testing.T) {
+	root := claimTestRoot(t)
+	cases := [][]string{
+		{"add", "pkg/a.go"},                                 // no session
+		{"add", "--session", "s1"},                          // no paths
+		{"add", "--session", "s1", "/abs/path.go"},          // absolute
+		{"add", "--session", "s1", "../escape.go"},          // traversal
+		{"add", "--session", "s1", ".devrites/work/x/f.md"}, // control tree
+		{"add", "--session", "s1", "a.go", "a.go"},          // duplicate
+		{"add", "--session", "bad session!", "a.go"},        // bad session
+		{"add", "--session", "s1", "--ttl", "x", "a.go"},    // bad ttl
+	}
+	for _, c := range cases {
+		if code, _, _ := runClaim(t, root, c...); code != 2 {
+			t.Fatalf("args %v: expected exit 2, got %d", c, code)
+		}
+	}
+	// TTL clamps rather than fails.
+	code, _, _ := runClaim(t, root, "add", "--session", "s1", "--ttl", "0", "pkg/a.go")
+	if code != 0 {
+		t.Fatalf("ttl clamp low: %d", code)
+	}
+	code, _, _ = runClaim(t, root, "add", "--session", "s1", "--ttl", "9999", "pkg/b.go")
+	if code != 0 {
+		t.Fatalf("ttl clamp high: %d", code)
+	}
+}
+
+func TestClaimLedgerToleratesMalformedLines(t *testing.T) {
+	root := claimTestRoot(t)
+	path := filepath.Join(root, ClaimsFile)
+	if err := os.WriteFile(path, []byte("not json\n{\"id\":\"x\"}\n"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	code, out, _ := runClaim(t, root, "list")
+	if code != 0 || !strings.Contains(out, "unparsed") {
+		t.Fatalf("malformed ledger: %d %q", code, out)
+	}
+}

package/engine/internal/lib/closeout_test.go

@@ -28,7 +28,7 @@ func runCloseOut(t *testing.T, root string, args ...string) (int, string) {
 
 func TestCloseOutRejectsRootOverrideArgument(t *testing.T) {
 	root := t.TempDir()
-	writeFile(t, filepath.Join(root, "work", "feat", "state.md"), "inside\n- Schema: 3\n")
+	writeFile(t, filepath.Join(root, "work", "feat", "state.md"), "inside\n- Schema: 4\n")
 
 	code, out := runCloseOut(t, root, "feat", t.TempDir())
 	if code != 4 || !strings.Contains(out, "usage: devrites-engine state close <slug>") {
@@ -65,7 +65,7 @@ func TestCloseOutRejectsWorkspaceSymlinkEscape(t *testing.T) {
 func TestCloseOutRejectsArchiveSymlinkEscape(t *testing.T) {
 	root := t.TempDir()
 	outside := t.TempDir()
-	writeFile(t, filepath.Join(root, "work", "feat", "state.md"), "inside\n- Schema: 3\n")
+	writeFile(t, filepath.Join(root, "work", "feat", "state.md"), "inside\n- Schema: 4\n")
 	if err := os.Symlink(outside, filepath.Join(root, "archive")); err != nil {
 		t.Skipf("symlinks unavailable: %v", err)
 	}
@@ -92,7 +92,7 @@ func TestCloseOutRollsBackArchiveWhenActiveCannotBeCleared(t *testing.T) {
 		t.Skip("permission model differs on Windows")
 	}
 	root := t.TempDir()
-	writeFile(t, filepath.Join(root, "work", "feat", "state.md"), "inside\n- Schema: 3\n")
+	writeFile(t, filepath.Join(root, "work", "feat", "state.md"), "inside\n- Schema: 4\n")
 	writeFile(t, filepath.Join(root, "ACTIVE"), "feat\n")
 	if err := os.MkdirAll(filepath.Join(root, "archive"), 0o755); err != nil {
 		t.Fatal(err)