devrites 4.2.0 → 4.4.0

package/engine/internal/parallel/lease.go

@@ -0,0 +1,244 @@
+package parallel
+
+import (
+	"encoding/json"
+	"fmt"
+	"os"
+	"path/filepath"
+	"regexp"
+	"strings"
+	"time"
+)
+
+const (
+	StatusRunning         = "running"
+	StatusAborted         = "aborted"
+	StatusIntegrateFailed = "integrate-failed"
+	StatusComplete        = "complete"
+
+	WrightPending = "pending"
+	WrightGreen   = "green"
+	WrightRed     = "red"
+	WrightGap     = "gap"
+)
+
+var (
+	slugRE      = regexp.MustCompile(`^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$`)
+	batchRE     = regexp.MustCompile(`^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$`)
+	sliceRE     = regexp.MustCompile(`^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$`)
+	shaRE       = regexp.MustCompile(`(?i)^[0-9a-f]{7,40}$`)
+	jsonFenceRE = regexp.MustCompile("(?s)```json\\n(.*?)\\n```")
+)
+
+// Lease is the machine-readable parallel batch lease (control tree only).
+type Lease struct {
+	BatchID             string       `json:"batch_id"`
+	CreatedAt           string       `json:"created_at"`
+	BaseSHA             string       `json:"base_sha"`
+	N                   int          `json:"n"`
+	Status              string       `json:"status"`
+	ControlPIDOrSession string       `json:"control_pid_or_session"`
+	Slices              []LeaseSlice `json:"slices"`
+}
+
+// LeaseSlice records one worker worktree under the lease.
+type LeaseSlice struct {
+	ID             string   `json:"id"`
+	Paths          []string `json:"paths"`
+	WorktreePath   string   `json:"worktree_path"`
+	Branch         string   `json:"branch"`
+	WrightStatus   string   `json:"wright_status"`
+	TransferCommit string   `json:"transfer_commit,omitempty"`
+}
+
+func LeasePath(repoRoot, slug string) (string, error) {
+	if err := validateSlug(slug); err != nil {
+		return "", err
+	}
+	return filepath.Join(repoRoot, ".devrites", "work", slug, "parallel-lease.md"), nil
+}
+
+func ScratchRoot(repoRoot string) string {
+	return filepath.Join(repoRoot, ".scratch", "parallel-wt")
+}
+
+func WorkerBranch(slug, batchID, sliceID string) string {
+	return fmt.Sprintf("devrites/parallel/%s/%s/%s", slug, batchID, sliceID)
+}
+
+func IntegrateBranchName(slug, batchID string) string {
+	return fmt.Sprintf("devrites/parallel/%s/%s/integrate", slug, batchID)
+}
+
+func WorkerWorktreePath(repoRoot, batchID, sliceID string) string {
+	return filepath.Join(ScratchRoot(repoRoot), batchID, sliceID)
+}
+
+func validateSlug(slug string) error {
+	if !slugRE.MatchString(slug) {
+		return fmt.Errorf("invalid slug %q", slug)
+	}
+	return nil
+}
+
+func validateBatchID(batchID string) error {
+	if !batchRE.MatchString(batchID) {
+		return fmt.Errorf("invalid batch id %q", batchID)
+	}
+	return nil
+}
+
+func validateSliceID(id string) error {
+	if !sliceRE.MatchString(id) {
+		return fmt.Errorf("invalid slice id %q", id)
+	}
+	return nil
+}
+
+func ValidateLease(lease *Lease) error {
+	if lease == nil {
+		return fmt.Errorf("lease is nil")
+	}
+	if err := validateBatchID(lease.BatchID); err != nil {
+		return err
+	}
+	if lease.CreatedAt == "" {
+		return fmt.Errorf("lease missing created_at")
+	}
+	if !shaRE.MatchString(lease.BaseSHA) {
+		return fmt.Errorf("invalid base_sha %q", lease.BaseSHA)
+	}
+	switch lease.Status {
+	case StatusRunning, StatusAborted, StatusIntegrateFailed, StatusComplete:
+	default:
+		return fmt.Errorf("invalid lease status %q", lease.Status)
+	}
+	if len(lease.Slices) < 2 || len(lease.Slices) > 3 {
+		return fmt.Errorf("lease must have 2 or 3 slices (got %d)", len(lease.Slices))
+	}
+	if lease.N != len(lease.Slices) {
+		return fmt.Errorf("lease n=%d does not match slices=%d", lease.N, len(lease.Slices))
+	}
+	seen := make(map[string]struct{}, len(lease.Slices))
+	for i, sl := range lease.Slices {
+		if err := validateSliceID(sl.ID); err != nil {
+			return fmt.Errorf("slice %d: %w", i, err)
+		}
+		if _, ok := seen[sl.ID]; ok {
+			return fmt.Errorf("duplicate slice id %q", sl.ID)
+		}
+		seen[sl.ID] = struct{}{}
+		if _, err := validateSlicePaths(sl.Paths, fmt.Sprintf("slice %q", sl.ID), ""); err != nil {
+			return err
+		}
+		switch sl.WrightStatus {
+		case "", WrightPending, WrightGreen, WrightRed, WrightGap:
+		default:
+			return fmt.Errorf("slice %q: invalid wright_status %q", sl.ID, sl.WrightStatus)
+		}
+		if sl.TransferCommit != "" && !shaRE.MatchString(sl.TransferCommit) {
+			return fmt.Errorf("slice %q: invalid transfer_commit %q", sl.ID, sl.TransferCommit)
+		}
+	}
+	return nil
+}
+
+func EmitLeaseMarkdown(lease *Lease) (string, error) {
+	if err := ValidateLease(lease); err != nil {
+		return "", err
+	}
+	payload, err := json.MarshalIndent(lease, "", "  ")
+	if err != nil {
+		return "", err
+	}
+	var b strings.Builder
+	b.WriteString("# parallel-lease.md — advisory control lease for /rite-build --parallel\n")
+	b.WriteString("# Machine block below is authoritative for helpers; YAML mirrors schema.\n\n")
+	fmt.Fprintf(&b, "batch_id: %s\n", yamlQuote(lease.BatchID))
+	fmt.Fprintf(&b, "created_at: %s\n", yamlQuote(lease.CreatedAt))
+	fmt.Fprintf(&b, "base_sha: %s\n", yamlQuote(lease.BaseSHA))
+	fmt.Fprintf(&b, "n: %d\n", lease.N)
+	fmt.Fprintf(&b, "status: %s\n", yamlQuote(lease.Status))
+	fmt.Fprintf(&b, "control_pid_or_session: %s\n", yamlQuote(lease.ControlPIDOrSession))
+	b.WriteString("slices:\n")
+	for _, sl := range lease.Slices {
+		fmt.Fprintf(&b, "  - id: %s\n", yamlQuote(sl.ID))
+		if len(sl.Paths) == 0 {
+			b.WriteString("    paths: []\n")
+		} else {
+			b.WriteString("    paths:\n")
+			for _, p := range sl.Paths {
+				fmt.Fprintf(&b, "      - %s\n", yamlQuote(p))
+			}
+		}
+		fmt.Fprintf(&b, "    worktree_path: %s\n", yamlQuote(sl.WorktreePath))
+		fmt.Fprintf(&b, "    branch: %s\n", yamlQuote(sl.Branch))
+		status := sl.WrightStatus
+		if status == "" {
+			status = WrightPending
+		}
+		fmt.Fprintf(&b, "    wright_status: %s\n", yamlQuote(status))
+		if sl.TransferCommit != "" {
+			fmt.Fprintf(&b, "    transfer_commit: %s\n", yamlQuote(sl.TransferCommit))
+		}
+	}
+	b.WriteString("\n<!-- machine-readable lease SSOT -->\n")
+	b.WriteString("```json\n")
+	b.Write(payload)
+	b.WriteString("\n```\n")
+	return b.String(), nil
+}
+
+func yamlQuote(v string) string {
+	if v == "" || strings.ContainsAny(v, ":#{}[]&*!|>'\"%@`") || strings.TrimSpace(v) != v {
+		raw, _ := json.Marshal(v)
+		return string(raw)
+	}
+	return v
+}
+
+func WriteLease(path string, lease *Lease) error {
+	text, err := EmitLeaseMarkdown(lease)
+	if err != nil {
+		return err
+	}
+	if err := os.MkdirAll(filepath.Dir(path), 0o755); err != nil {
+		return err
+	}
+	tmp := path + ".tmp"
+	if err := os.WriteFile(tmp, []byte(text), 0o644); err != nil {
+		return err
+	}
+	return os.Rename(tmp, path)
+}
+
+func ReadLease(path string) (*Lease, error) {
+	data, err := os.ReadFile(path)
+	if err != nil {
+		return nil, err
+	}
+	match := jsonFenceRE.FindSubmatch(data)
+	if match == nil {
+		return nil, fmt.Errorf("lease missing machine-readable json fence: %s", path)
+	}
+	var lease Lease
+	if err := json.Unmarshal(match[1], &lease); err != nil {
+		return nil, fmt.Errorf("lease json invalid: %w", err)
+	}
+	if err := ValidateLease(&lease); err != nil {
+		return nil, err
+	}
+	return &lease, nil
+}
+
+func ClearLease(path string) error {
+	err := os.Remove(path)
+	if err != nil && !os.IsNotExist(err) {
+		return err
+	}
+	return nil
+}
+
+func NowUTC() string {
+	return time.Now().UTC().Format(time.RFC3339)
+}

package/engine/internal/parallel/ops.go

@@ -0,0 +1,416 @@
+package parallel
+
+import (
+	"encoding/json"
+	"fmt"
+	"os"
+	"path/filepath"
+	"sort"
+	"strings"
+)
+
+// CreateOpts configures parallel worktree creation.
+type CreateOpts struct {
+	Root    string
+	Slug    string
+	BatchID string
+	BaseSHA string
+	Session string
+	Slices  []SlicePaths
+}
+
+// Create path-disjoint-gates, creates <=3 worktrees from base, and writes a running lease.
+func Create(opts CreateOpts) (*Lease, error) {
+	if err := validateSlug(opts.Slug); err != nil {
+		return nil, err
+	}
+	if err := validateBatchID(opts.BatchID); err != nil {
+		return nil, err
+	}
+	if len(opts.Slices) < 2 || len(opts.Slices) > 3 {
+		return nil, fmt.Errorf("create requires 2 or 3 slices (got %d)", len(opts.Slices))
+	}
+	if _, err := CheckPathDisjoint(opts.Slices, opts.Root); err != nil {
+		return nil, err
+	}
+	base, err := revParse(opts.Root, opts.BaseSHA)
+	if err != nil {
+		return nil, fmt.Errorf("base sha: %w", err)
+	}
+	leasePath, err := LeasePath(opts.Root, opts.Slug)
+	if err != nil {
+		return nil, err
+	}
+	if _, err := os.Stat(leasePath); err == nil {
+		return nil, fmt.Errorf("lease already exists: %s", leasePath)
+	}
+
+	session := opts.Session
+	if session == "" {
+		session = fmt.Sprintf("pid:%d", os.Getpid())
+	}
+
+	createdPaths := make([]string, 0, len(opts.Slices))
+	createdBranches := make([]string, 0, len(opts.Slices))
+	cleanupPartial := func() {
+		for _, p := range createdPaths {
+			_ = worktreeRemove(opts.Root, p)
+		}
+		for _, b := range createdBranches {
+			_ = deleteBranch(opts.Root, b)
+		}
+	}
+
+	slices := make([]LeaseSlice, 0, len(opts.Slices))
+	for _, sp := range opts.Slices {
+		if err := validateSliceID(sp.ID); err != nil {
+			cleanupPartial()
+			return nil, err
+		}
+		paths, err := validateSlicePaths(sp.Paths, fmt.Sprintf("slice %q", sp.ID), opts.Root)
+		if err != nil {
+			cleanupPartial()
+			return nil, err
+		}
+		branch := WorkerBranch(opts.Slug, opts.BatchID, sp.ID)
+		wt := WorkerWorktreePath(opts.Root, opts.BatchID, sp.ID)
+		if _, err := os.Stat(wt); err == nil {
+			cleanupPartial()
+			return nil, fmt.Errorf("worktree path already exists: %s", wt)
+		}
+		if err := os.MkdirAll(filepath.Dir(wt), 0o755); err != nil {
+			cleanupPartial()
+			return nil, err
+		}
+		if err := worktreeAdd(opts.Root, wt, branch, base); err != nil {
+			cleanupPartial()
+			return nil, fmt.Errorf("worktree add %s: %w", sp.ID, err)
+		}
+		createdPaths = append(createdPaths, wt)
+		createdBranches = append(createdBranches, branch)
+		slices = append(slices, LeaseSlice{
+			ID:           sp.ID,
+			Paths:        paths,
+			WorktreePath: wt,
+			Branch:       branch,
+			WrightStatus: WrightPending,
+		})
+	}
+
+	lease := &Lease{
+		BatchID:             opts.BatchID,
+		CreatedAt:           NowUTC(),
+		BaseSHA:             base,
+		N:                   len(slices),
+		Status:              StatusRunning,
+		ControlPIDOrSession: session,
+		Slices:              slices,
+	}
+	if err := WriteLease(leasePath, lease); err != nil {
+		cleanupPartial()
+		return nil, err
+	}
+	return lease, nil
+}
+
+// RecordGreen marks a slice green with its transfer commit.
+func RecordGreen(repoRoot, slug, sliceID, commit string) (*Lease, error) {
+	leasePath, err := LeasePath(repoRoot, slug)
+	if err != nil {
+		return nil, err
+	}
+	lease, err := ReadLease(leasePath)
+	if err != nil {
+		return nil, err
+	}
+	if lease.Status != StatusRunning {
+		return nil, fmt.Errorf("record-green requires status=running (have %s)", lease.Status)
+	}
+	sha, err := revParse(repoRoot, commit)
+	if err != nil {
+		return nil, fmt.Errorf("transfer commit: %w", err)
+	}
+	found := false
+	for i := range lease.Slices {
+		if lease.Slices[i].ID == sliceID {
+			lease.Slices[i].WrightStatus = WrightGreen
+			lease.Slices[i].TransferCommit = sha
+			found = true
+			break
+		}
+	}
+	if !found {
+		return nil, fmt.Errorf("slice not in lease: %s", sliceID)
+	}
+	if err := WriteLease(leasePath, lease); err != nil {
+		return nil, err
+	}
+	return lease, nil
+}
+
+// Abort marks the lease aborted and restores control tip to base_sha.
+func Abort(repoRoot, slug string, force bool) (*Lease, error) {
+	leasePath, err := LeasePath(repoRoot, slug)
+	if err != nil {
+		return nil, err
+	}
+	lease, err := ReadLease(leasePath)
+	if err != nil {
+		return nil, err
+	}
+	base, err := revParse(repoRoot, lease.BaseSHA)
+	if err != nil {
+		return nil, err
+	}
+	if err := ensureControlAtBase(repoRoot, base, force); err != nil {
+		return nil, err
+	}
+	lease.Status = StatusAborted
+	if err := WriteLease(leasePath, lease); err != nil {
+		return nil, err
+	}
+	return lease, nil
+}
+
+func ensureControlAtBase(repoRoot, base string, force bool) error {
+	head, err := headSHA(repoRoot)
+	if err != nil {
+		return err
+	}
+	if head == base {
+		return nil
+	}
+	dirty, err := porcelainDirty(repoRoot)
+	if err != nil {
+		return err
+	}
+	if dirty && !force {
+		return fmt.Errorf("control tree dirty; refuse reset to base (pass --force to override)")
+	}
+	if err := resetHard(repoRoot, base); err != nil {
+		return err
+	}
+	head, err = headSHA(repoRoot)
+	if err != nil {
+		return err
+	}
+	if head != base {
+		return fmt.Errorf("failed to leave control at base %s", base)
+	}
+	return nil
+}
+
+// IntegrateOpts configures staging integrate.
+type IntegrateOpts struct {
+	Root           string
+	Slug           string
+	ApplyToControl bool
+	Force          bool
+}
+
+// Integrate all-or-nothing applies sibling transfer commits onto a staging branch.
+func Integrate(opts IntegrateOpts) (tip string, lease *Lease, err error) {
+	leasePath, err := LeasePath(opts.Root, opts.Slug)
+	if err != nil {
+		return "", nil, err
+	}
+	lease, err = ReadLease(leasePath)
+	if err != nil {
+		return "", nil, err
+	}
+	if lease.Status != StatusRunning {
+		return "", nil, fmt.Errorf("integrate requires status=running (have %s)", lease.Status)
+	}
+	base, err := revParse(opts.Root, lease.BaseSHA)
+	if err != nil {
+		return "", nil, err
+	}
+	if err := ensureControlAtBase(opts.Root, base, opts.Force); err != nil {
+		return "", nil, err
+	}
+
+	for _, sl := range lease.Slices {
+		if sl.WrightStatus != WrightGreen {
+			return "", nil, fmt.Errorf("slice %s is not green", sl.ID)
+		}
+		if sl.TransferCommit == "" {
+			return "", nil, fmt.Errorf("slice %s missing transfer_commit", sl.ID)
+		}
+	}
+
+	ibranch := IntegrateBranchName(opts.Slug, lease.BatchID)
+	stageWT := filepath.Join(ScratchRoot(opts.Root), lease.BatchID, "integrate")
+	_ = os.RemoveAll(stageWT)
+	if exists, _ := branchExists(opts.Root, ibranch); exists {
+		_ = deleteBranch(opts.Root, ibranch)
+	}
+	if err := os.MkdirAll(filepath.Dir(stageWT), 0o755); err != nil {
+		return "", nil, err
+	}
+	if err := worktreeAdd(opts.Root, stageWT, ibranch, base); err != nil {
+		return "", nil, fmt.Errorf("staging worktree: %w", err)
+	}
+
+	fail := func(reason error) (string, *Lease, error) {
+		_ = worktreeRemove(opts.Root, stageWT)
+		_ = deleteBranch(opts.Root, ibranch)
+		_, _ = git(opts.Root, "worktree", "prune")
+		lease.Status = StatusIntegrateFailed
+		_ = WriteLease(leasePath, lease)
+		_ = ensureControlAtBase(opts.Root, base, true)
+		return "", lease, reason
+	}
+
+	for _, sl := range lease.Slices {
+		tc, err := revParse(opts.Root, sl.TransferCommit)
+		if err != nil {
+			return fail(fmt.Errorf("slice %s transfer: %w", sl.ID, err))
+		}
+		ok, err := isAncestor(opts.Root, base, tc)
+		if err != nil {
+			return fail(err)
+		}
+		if !ok {
+			return fail(fmt.Errorf("transfer_commit for %s is not a descendant of base", sl.ID))
+		}
+		got, err := diffNames(opts.Root, base, tc)
+		if err != nil {
+			return fail(err)
+		}
+		want := append([]string(nil), sl.Paths...)
+		sort.Strings(want)
+		sort.Strings(got)
+		if !pathListsEqual(want, got) {
+			return fail(fmt.Errorf("exact-path proof failed for slice %s: want=%v got=%v", sl.ID, want, got))
+		}
+		for _, p := range got {
+			if p == ".devrites" || strings.HasPrefix(p, ".devrites/") {
+				return fail(fmt.Errorf("path proof failed: .devrites path in transfer: %s", p))
+			}
+		}
+
+		stageHead, err := headSHA(stageWT)
+		if err != nil {
+			return fail(err)
+		}
+		canFF, err := isAncestor(opts.Root, stageHead, tc)
+		if err != nil {
+			return fail(err)
+		}
+		if canFF {
+			if err := mergeFFOnly(stageWT, tc); err != nil {
+				return fail(fmt.Errorf("ff-only integrate failed for slice %s: %w", sl.ID, err))
+			}
+		} else {
+			if err := cherryPickRange(stageWT, base, tc); err != nil {
+				cherryPickAbort(stageWT)
+				return fail(fmt.Errorf("cherry-pick replay failed for slice %s: %w", sl.ID, err))
+			}
+		}
+	}
+
+	tip, err = headSHA(stageWT)
+	if err != nil {
+		return fail(err)
+	}
+	_ = worktreeRemove(opts.Root, stageWT)
+	_, _ = git(opts.Root, "worktree", "prune")
+
+	if opts.ApplyToControl {
+		if err := mergeFFOnly(opts.Root, tip); err != nil {
+			return fail(fmt.Errorf("control fast-forward to integrate tip failed: %w", err))
+		}
+	} else if err := ensureControlAtBase(opts.Root, base, opts.Force); err != nil {
+		return fail(err)
+	}
+
+	lease.Status = StatusComplete
+	if err := WriteLease(leasePath, lease); err != nil {
+		return "", nil, err
+	}
+	return tip, lease, nil
+}
+
+func pathListsEqual(a, b []string) bool {
+	if len(a) != len(b) {
+		return false
+	}
+	for i := range a {
+		if a[i] != b[i] {
+			return false
+		}
+	}
+	return true
+}
+
+// Cleanup removes worker worktrees/branches and clears the lease (complete or --force).
+func Cleanup(repoRoot, slug string, force bool) error {
+	leasePath, err := LeasePath(repoRoot, slug)
+	if err != nil {
+		return err
+	}
+	if _, err := os.Stat(leasePath); os.IsNotExist(err) {
+		return nil
+	}
+	lease, err := ReadLease(leasePath)
+	if err != nil {
+		return err
+	}
+	if lease.Status != StatusComplete && !force {
+		return fmt.Errorf("cleanup refuses status=%s without --force (abort keeps workers for diagnosis)", lease.Status)
+	}
+	for _, sl := range lease.Slices {
+		if sl.WorktreePath != "" {
+			_ = worktreeRemove(repoRoot, sl.WorktreePath)
+			_ = os.RemoveAll(sl.WorktreePath)
+		}
+		if sl.Branch != "" {
+			_ = deleteBranch(repoRoot, sl.Branch)
+		}
+	}
+	ibranch := IntegrateBranchName(slug, lease.BatchID)
+	_ = deleteBranch(repoRoot, ibranch)
+	_ = os.RemoveAll(filepath.Join(ScratchRoot(repoRoot), lease.BatchID))
+	_, _ = git(repoRoot, "worktree", "prune")
+	return ClearLease(leasePath)
+}
+
+// StatusReport returns a human-readable lease status.
+func StatusReport(repoRoot, slug string) (string, error) {
+	leasePath, err := LeasePath(repoRoot, slug)
+	if err != nil {
+		return "", err
+	}
+	if _, err := os.Stat(leasePath); os.IsNotExist(err) {
+		return fmt.Sprintf("status: no lease at %s\n", leasePath), nil
+	}
+	lease, err := ReadLease(leasePath)
+	if err != nil {
+		return "", err
+	}
+	var b strings.Builder
+	fmt.Fprintf(&b, "lease: %s\n", leasePath)
+	fmt.Fprintf(&b, "status: %s\n", lease.Status)
+	fmt.Fprintf(&b, "base_sha: %s\n", lease.BaseSHA)
+	for _, sl := range lease.Slices {
+		tc := sl.TransferCommit
+		if tc == "" {
+			tc = "-"
+		}
+		fmt.Fprintf(&b, "slice %s: wright=%s wt=%s branch=%s transfer=%s\n",
+			sl.ID, sl.WrightStatus, sl.WorktreePath, sl.Branch, tc)
+	}
+	if head, err := headSHA(repoRoot); err == nil {
+		fmt.Fprintf(&b, "control_HEAD: %s\n", head)
+	}
+	return b.String(), nil
+}
+
+// LeaseJSON returns indented lease JSON.
+func LeaseJSON(lease *Lease) (string, error) {
+	b, err := json.MarshalIndent(lease, "", "  ")
+	if err != nil {
+		return "", err
+	}
+	return string(b), nil
+}