devrites 2.6.1 → 3.0.0

package/engine/internal/lib/buildreadiness.go

@@ -0,0 +1,88 @@
+package lib
+
+import (
+	"fmt"
+	"io"
+	"os"
+	"regexp"
+	"strings"
+
+	"github.com/devrites/devrites/internal/workflow"
+)
+
+// BuildReadiness decides whether a feature is ready to build, reading only its
+// recorded state (state.md) — an open HITL question, a blocked plan, or an
+// unapproved plan each stops the build with a distinct, actionable exit code
+// rather than trusting the model to honour a prose checklist. It never mutates
+// the workspace.
+//
+// The command is `build-readiness` (the plain `readiness` name is the separate
+// completeness gate), but its messages keep the `readiness:` prefix. Exit codes:
+//
+//	0  ready to build
+//	2  plan not approved   → /rite-define, then confirm the plan
+//	3  awaiting a human     → /rite-resolve <qid> "<answer>"
+//	4  blocked              → /rite-plan repair (or unblock)
+//	5  no workspace/state.md → /rite-spec <feature>
+func BuildReadiness(root string, args []string, stdout, stderr io.Writer) int {
+	slug := slugOrActive(root, args)
+	s := featureFile(root, slug, "state.md")
+	if slug == "" || !isFile(s) {
+		shown := slug
+		if shown == "" {
+			shown = "<unset>"
+		}
+		fmt.Fprintf(stderr, "readiness: no active workspace/state.md (slug=%s) — run %s <feature>\n", shown, workflow.ForVerb("spec").Both())
+		return 5
+	}
+
+	data, _ := os.ReadFile(s)
+	lines := splitLinesNoTrailing(data)
+
+	status := readinessField(lines, "Status")
+	switch status {
+	case "awaiting_human":
+		fmt.Fprintf(stderr, "readiness: STOP — Status: awaiting_human. Resume with %s <qid> \"<answer>\".\n", workflow.ForVerb("resolve").Both())
+		return 3
+	case "blocked":
+		fmt.Fprintf(stderr, "readiness: STOP — Status: blocked. Repair with %s repair (or unblock).\n", workflow.ForVerb("plan").Both())
+		return 4
+	}
+
+	approved := readinessField(lines, "Plan approved")
+	if approved == "" || approved == "none" {
+		fmt.Fprintf(stderr, "readiness: STOP — plan not approved (state.md has no \"Plan approved\"). Run %s.\n", workflow.ForVerb("define").Both())
+		return 2
+	}
+
+	shownStatus := status
+	if shownStatus == "" {
+		shownStatus = "running"
+	}
+	fmt.Fprintf(stdout, "readiness: OK — plan approved %s, status %s. Ready to build.\n", approved, shownStatus)
+	return 0
+}
+
+// fieldAnnotation trims a trailing " # comment" or " | none" annotation off a
+// state.md field value.
+var fieldAnnotation = regexp.MustCompile(`[[:space:]]*(#|\|).*$`)
+
+// readinessField reads a `Key: value` field from state.md, tolerating a leading
+// "- " bullet and trimming any trailing annotation and blanks. It returns the
+// first match, or "" when the key is absent. A key may contain spaces (e.g.
+// "Plan approved") — it is matched literally.
+func readinessField(lines []string, key string) string {
+	field := regexp.MustCompile(`^[[:space:]]*-?[[:space:]]*` + key + `:[[:space:]]*`)
+	for _, line := range lines {
+		loc := field.FindStringIndex(line)
+		if loc == nil {
+			continue
+		}
+		value := line[loc[1]:]
+		if m := fieldAnnotation.FindStringIndex(value); m != nil {
+			value = value[:m[0]]
+		}
+		return strings.TrimRight(value, spaceChars)
+	}
+	return ""
+}

package/engine/internal/lib/checkacceptance.go

@@ -0,0 +1,176 @@
+package lib
+
+import (
+	"fmt"
+	"io"
+	"os"
+	"regexp"
+	"sort"
+	"strings"
+)
+
+// Executable acceptance criteria — a port of check-acceptance.sh. Grades the
+// [ACn]-tagged acceptance criteria in spec.md against seal.md: each spec
+// criterion must be checked ([x]) in seal.md. Without ids it falls back to a
+// count/unchecked heuristic. The spec-time mirror is SpecValidate (shape); this
+// grades proof.
+//
+// Exit codes: 0 every criterion proven · 1 gap (uncovered/unproven) · 2 usage ·
+// 5 missing spec.md or seal.md.
+var (
+	acHeadingRe = regexp.MustCompile(`^##[[:space:]]+[Aa]cceptance [Cc]riteria`)
+	h2Re        = regexp.MustCompile(`^##[[:space:]]`)
+	acIDRe      = regexp.MustCompile(`\[AC[0-9]+\]`)
+	checkedRe   = regexp.MustCompile(`^[[:space:]]*-[[:space:]]*\[[xX]\]`)
+	bulletRe    = regexp.MustCompile(`^[[:space:]]*-[[:space:]]`)
+	checkboxRe  = regexp.MustCompile(`^[[:space:]]*-[[:space:]]*\[[ xX]\]`)
+	uncheckedRe = regexp.MustCompile(`^[[:space:]]*-[[:space:]]*\[[[:space:]]\]`)
+)
+
+// CheckAcceptance grades the acceptance criteria of the workspace dir `ws`. It
+// writes to stdout/stderr and returns the process exit code.
+func CheckAcceptance(ws string, stdout, stderr io.Writer) int {
+	if ws == "" || !isDir(ws) {
+		fmt.Fprintln(stderr, "usage: devrites-engine check-acceptance <workspace-dir>")
+		return 2
+	}
+	spec := ws + "/spec.md"
+	seal := ws + "/seal.md"
+	if !isFile(spec) {
+		fmt.Fprintf(stderr, "check-acceptance: no spec.md in %s\n", ws)
+		return 5
+	}
+	if !isFile(seal) {
+		fmt.Fprintf(stderr, "check-acceptance: no seal.md in %s — feature not sealed\n", ws)
+		return 5
+	}
+
+	specBody, err := acSection(spec)
+	if err != nil {
+		fmt.Fprintf(stderr, "check-acceptance: %v\n", err)
+		return 2
+	}
+	sealBody, err := acSection(seal)
+	if err != nil {
+		fmt.Fprintf(stderr, "check-acceptance: %v\n", err)
+		return 2
+	}
+
+	if sectionEmpty(specBody) {
+		fmt.Fprintln(stderr, "check-acceptance: spec.md has no \"## Acceptance criteria\" section — nothing to grade")
+		return 1
+	}
+
+	specIDs := sortedUniqueIDs(specBody)
+
+	if len(specIDs) > 0 {
+		// ID mode — each spec [ACn] must be checked ([x]) in seal.md.
+		checkedIDs := map[string]bool{}
+		for _, line := range sealBody {
+			if checkedRe.MatchString(line) {
+				for _, id := range acIDRe.FindAllString(line, -1) {
+					checkedIDs[id] = true
+				}
+			}
+		}
+		var missing []string
+		for _, id := range specIDs {
+			if !checkedIDs[id] {
+				missing = append(missing, id)
+			}
+		}
+		total := len(specIDs)
+		if len(missing) > 0 {
+			fmt.Fprintf(stderr, "check-acceptance: %d/%d criteria proven; UNPROVEN/UNCOVERED:%s (must be checked [x] in seal.md)\n",
+				total-len(missing), total, " "+strings.Join(missing, " "))
+			return 1
+		}
+		fmt.Fprintf(stdout, "check-acceptance: OK — all %d acceptance criteria (%s) proven + checked in seal.md\n",
+			total, strings.Join(specIDs, " "))
+		return 0
+	}
+
+	// Fallback (no ids) — count spec criteria vs seal checked/unchecked items.
+	specN := countMatching(specBody, bulletRe)
+	sealTotal := countMatching(sealBody, checkboxRe)
+	sealUnchecked := countMatching(sealBody, uncheckedRe)
+
+	if sealTotal < specN {
+		fmt.Fprintf(stderr, "check-acceptance: seal.md lists %d acceptance items but spec.md has %d criteria — %d dropped. (Tag criteria [AC1].. to grade by id.)\n",
+			sealTotal, specN, specN-sealTotal)
+		return 1
+	}
+	if sealUnchecked > 0 {
+		fmt.Fprintf(stderr, "check-acceptance: %d acceptance criterion(s) unchecked in seal.md (unproven). (Tag criteria [AC1].. to grade by id.)\n", sealUnchecked)
+		return 1
+	}
+	fmt.Fprintf(stdout, "check-acceptance: OK — %d acceptance items all checked in seal.md (no ids; add [AC1].. for id-level grading)\n", sealTotal)
+	return 0
+}
+
+// acSection returns the body lines under an "## Acceptance Criteria" heading
+// (case-insensitive on the words), up to the next "## " heading — mirroring the
+// awk one-liner in check-acceptance.sh.
+func acSection(file string) ([]string, error) {
+	f, err := os.Open(file)
+	if err != nil {
+		return nil, fmt.Errorf("read acceptance section: %w", err)
+	}
+	defer f.Close()
+
+	var body []string
+	in := false
+	sc := newLineScanner(f)
+	for sc.Scan() {
+		line := sc.Text()
+		if acHeadingRe.MatchString(line) {
+			in = true
+			continue // the heading itself is not body (awk's `next`)
+		}
+		if h2Re.MatchString(line) {
+			in = false
+		}
+		if in {
+			body = append(body, line)
+		}
+	}
+	return body, sc.Err()
+}
+
+// sectionEmpty reports whether the acceptance body is empty in the bash sense:
+// awk emits each in-section line with a trailing newline, $() strips the trailing
+// newlines, and `[ -z ]` tests the remainder. A body of only blank lines collapses
+// to "" — so a heading followed by blanks is "nothing to grade", not a fallback.
+func sectionEmpty(lines []string) bool {
+	return strings.TrimRight(strings.Join(lines, "\n"), "\n") == ""
+}
+
+// sortedUniqueIDs extracts every [ACn] id from the lines and returns them sorted
+// and de-duplicated, matching `grep -oE '\[AC[0-9]+\]' | sort -u`.
+func sortedUniqueIDs(lines []string) []string {
+	set := map[string]bool{}
+	for _, line := range lines {
+		for _, id := range acIDRe.FindAllString(line, -1) {
+			set[id] = true
+		}
+	}
+	if len(set) == 0 {
+		return nil
+	}
+	ids := make([]string, 0, len(set))
+	for id := range set {
+		ids = append(ids, id)
+	}
+	sort.Strings(ids) // byte order == `sort` under LC_ALL=C
+	return ids
+}
+
+func countMatching(lines []string, re *regexp.Regexp) int {
+	n := 0
+	for _, line := range lines {
+		if re.MatchString(line) {
+			n++
+		}
+	}
+	return n
+}

package/engine/internal/lib/closeout.go

@@ -0,0 +1,69 @@
+package lib
+
+import (
+	"fmt"
+	"io"
+	"os"
+	"path/filepath"
+)
+
+// CloseOut retires a shipped feature: it moves the feature directory into the
+// archive and, when the feature is still the active one, clears the ACTIVE cursor
+// so the next /rite-spec starts clean. The workspace is relocated, never deleted —
+// the audit trail is preserved under archive/<slug>.
+//
+// args is `<slug> [devrites-dir]`. The optional second argument overrides the
+// .devrites directory (default: the resolved root), which lets a caller archive a
+// workspace outside the current one. Exit codes:
+//
+//	0  archived (ACTIVE cleared if it pointed here)
+//	4  no slug given, or the feature has no workspace
+//	5  an archive already exists at the destination — refuse to clobber it
+func CloseOut(root string, args []string, stdout, stderr io.Writer) int {
+	slug := argAt(args, 0)
+	dv := argAt(args, 1)
+	if dv == "" {
+		dv = root
+	}
+	if slug == "" {
+		fmt.Fprintln(stderr, "close-out: usage: devrites-engine close-out <slug> [devrites-dir]")
+		return 4
+	}
+
+	work := featureDir(dv, slug)
+	arch := filepath.Join(dv, "archive", slug)
+	active := filepath.Join(dv, "ACTIVE")
+
+	if !isDir(work) {
+		fmt.Fprintf(stderr, "close-out: no workspace at %s\n", work)
+		return 4
+	}
+	// A broken symlink at the destination still counts as "already there", so use
+	// Lstat rather than Stat to avoid silently overwriting it.
+	if _, err := os.Lstat(arch); err == nil {
+		fmt.Fprintf(stderr, "close-out: archive already exists at %s — refusing to clobber\n", arch)
+		return 5
+	}
+
+	// Fail closed: if the move does not happen, leave the cursor alone and do not
+	// claim success — a lost audit trail must never look like a clean close-out.
+	if err := os.MkdirAll(filepath.Join(dv, "archive"), 0o755); err != nil {
+		fmt.Fprintf(stderr, "close-out: cannot create archive dir: %v\n", err)
+		return 1
+	}
+	if err := os.Rename(work, arch); err != nil {
+		fmt.Fprintf(stderr, "close-out: cannot archive %s -> %s: %v\n", work, arch, err)
+		return 1
+	}
+
+	// Clear ACTIVE only if it still points at the slug we just archived.
+	if isFile(active) {
+		if b, err := os.ReadFile(active); err == nil && stripASCIISpace(string(b)) == slug {
+			_ = os.WriteFile(active, nil, 0o644)
+			fmt.Fprintf(stdout, "close-out: archived %s -> %s and cleared ACTIVE\n", slug, filepath.ToSlash(arch))
+			return 0
+		}
+	}
+	fmt.Fprintf(stdout, "close-out: archived %s -> %s (ACTIVE pointed elsewhere — left as-is)\n", slug, filepath.ToSlash(arch))
+	return 0
+}

package/engine/internal/lib/command_other.go

@@ -0,0 +1,7 @@
+//go:build !unix
+
+package lib
+
+import "os/exec"
+
+func configureBoundedCommand(_ *exec.Cmd) {}

package/engine/internal/lib/command_unix.go

@@ -0,0 +1,24 @@
+//go:build unix
+
+package lib
+
+import (
+	"errors"
+	"os"
+	"os/exec"
+	"syscall"
+)
+
+func configureBoundedCommand(cmd *exec.Cmd) {
+	cmd.SysProcAttr = &syscall.SysProcAttr{Setpgid: true}
+	cmd.Cancel = func() error {
+		if cmd.Process == nil {
+			return os.ErrProcessDone
+		}
+		err := syscall.Kill(-cmd.Process.Pid, syscall.SIGKILL)
+		if errors.Is(err, syscall.ESRCH) {
+			return os.ErrProcessDone
+		}
+		return err
+	}
+}

package/engine/internal/lib/context.go

@@ -0,0 +1,236 @@
+package lib
+
+import (
+	"encoding/json"
+	"fmt"
+	"io"
+	"os"
+	"path/filepath"
+	"strings"
+
+	"github.com/devrites/devrites/internal/state"
+)
+
+const (
+	contextStart = "<!-- DEVRITES START -->"
+	contextEnd   = "<!-- DEVRITES END -->"
+)
+
+// Context owns only a small delimited block in project context files. It never
+// rewrites the surrounding AGENTS.md / CLAUDE.md content.
+func Context(root string, args []string, stdout, stderr io.Writer) int {
+	switch argAt(args, 0) {
+	case "sync":
+		return contextSync(root, args[1:], stdout, stderr)
+	case "show":
+		return contextShow(root, args[1:], stdout, stderr)
+	default:
+		fmt.Fprintln(stderr, "usage: devrites-engine context sync [file ...] | context show [--json]")
+		return 2
+	}
+}
+
+func contextSync(root string, args []string, stdout, stderr io.Writer) int {
+	targets, err := contextTargets(root, args)
+	if err != nil {
+		fmt.Fprintf(stderr, "context: %v\n", err)
+		return 2
+	}
+	block := managedContextBlock(root)
+	project := filepath.Dir(root)
+	for _, rel := range targets {
+		path := filepath.Join(project, rel)
+		if err := upsertContextBlock(path, block); err != nil {
+			fmt.Fprintf(stderr, "context: %v\n", err)
+			return 1
+		}
+		fmt.Fprintf(stdout, "context: synced %s\n", rel)
+	}
+	return 0
+}
+
+type contextShowDocument struct {
+	Root            string          `json:"root"`
+	Project         string          `json:"project"`
+	ActiveWorkspace string          `json:"activeWorkspace,omitempty"`
+	Source          string          `json:"source"`
+	HostCommands    contextCommands `json:"hostCommands"`
+	Status          []Diagnostic    `json:"status"`
+}
+
+type contextCommands struct {
+	Claude string `json:"claude"`
+	Codex  string `json:"codex"`
+}
+
+func contextShow(root string, args []string, stdout, stderr io.Writer) int {
+	jsonMode := false
+	for _, a := range args {
+		if a == "--json" {
+			jsonMode = true
+			continue
+		}
+		fmt.Fprintln(stderr, "usage: devrites-engine context show [--json]")
+		return 2
+	}
+	doc := contextDocument(root)
+	if jsonMode {
+		b, err := json.MarshalIndent(doc, "", "  ")
+		if err != nil {
+			fmt.Fprintf(stderr, "context: %v\n", err)
+			return 1
+		}
+		_, _ = stdout.Write(append(b, '\n'))
+		return 0
+	}
+	fmt.Fprintln(stdout, "DevRites context")
+	fmt.Fprintf(stdout, "Project: %s\n", doc.Project)
+	fmt.Fprintf(stdout, "Root: %s\n", doc.Root)
+	if doc.ActiveWorkspace != "" {
+		fmt.Fprintf(stdout, "Active workspace: %s (source: %s)\n", doc.ActiveWorkspace, doc.Source)
+	} else {
+		fmt.Fprintf(stdout, "Active workspace: none (source: %s)\n", doc.Source)
+	}
+	fmt.Fprintf(stdout, "Commands: Claude %s · Codex %s\n", doc.HostCommands.Claude, doc.HostCommands.Codex)
+	return 0
+}
+
+func contextDocument(root string) contextShowDocument {
+	project := filepath.Dir(root)
+	slug := activeSlug(root)
+	source := "none"
+	active := ""
+	if strings.TrimSpace(os.Getenv("DEVRITES_WORKSPACE")) != "" {
+		source = "DEVRITES_WORKSPACE"
+	} else if slug != "" {
+		source = "ACTIVE"
+	} else if strings.TrimSpace(os.Getenv("DEVRITES_ROOT")) != "" {
+		source = "DEVRITES_ROOT"
+	}
+	if slug != "" {
+		active = filepath.Join(".devrites", "work", slug)
+		if rel, err := filepath.Rel(project, featureDir(root, slug)); err == nil {
+			active = rel
+		}
+	}
+	return contextShowDocument{
+		Root:            root,
+		Project:         project,
+		ActiveWorkspace: active,
+		Source:          source,
+		HostCommands:    contextCommands{Claude: "/rite", Codex: "$rite"},
+		Status:          []Diagnostic{},
+	}
+}
+
+func contextTargets(root string, args []string) ([]string, error) {
+	if len(args) > 0 {
+		return cleanContextTargets(args)
+	}
+	if configured := parseContextConfig(filepath.Join(root, "context.yaml")); len(configured) > 0 {
+		return cleanContextTargets(configured)
+	}
+	project := filepath.Dir(root)
+	var existing []string
+	for _, rel := range []string{"AGENTS.md", "CLAUDE.md"} {
+		if isFile(filepath.Join(project, rel)) {
+			existing = append(existing, rel)
+		}
+	}
+	if len(existing) > 0 {
+		return existing, nil
+	}
+	return []string{"AGENTS.md"}, nil
+}
+
+func parseContextConfig(path string) []string {
+	data, err := os.ReadFile(path)
+	if err != nil {
+		return nil
+	}
+	var out []string
+	inList := false
+	for _, line := range splitLinesNoTrailing(data) {
+		trimmed := strings.TrimSpace(line)
+		if trimmed == "" || strings.HasPrefix(trimmed, "#") {
+			continue
+		}
+		if strings.HasPrefix(trimmed, "context_files:") {
+			inList = true
+			continue
+		}
+		if inList && strings.HasPrefix(trimmed, "-") {
+			out = append(out, strings.Trim(strings.TrimSpace(strings.TrimPrefix(trimmed, "-")), `"'`))
+			continue
+		}
+		inList = false
+		if k, v, ok := strings.Cut(trimmed, ":"); ok && strings.TrimSpace(k) == "context_file" {
+			out = append(out, strings.Trim(strings.TrimSpace(v), `"'`))
+		}
+	}
+	return out
+}
+
+func cleanContextTargets(raw []string) ([]string, error) {
+	seen := map[string]bool{}
+	var out []string
+	for _, rel := range raw {
+		rel = filepath.Clean(strings.TrimSpace(rel))
+		if rel == "." || rel == "" {
+			continue
+		}
+		if filepath.IsAbs(rel) || strings.Contains(rel, "..") || strings.Contains(rel, `\`) {
+			return nil, fmt.Errorf("unsafe context path %q", rel)
+		}
+		if !seen[rel] {
+			seen[rel] = true
+			out = append(out, rel)
+		}
+	}
+	if len(out) == 0 {
+		return nil, fmt.Errorf("no context files configured")
+	}
+	return out, nil
+}
+
+func managedContextBlock(root string) string {
+	slug := activeSlug(root)
+	lines := []string{
+		contextStart,
+		"DevRites project guidance:",
+		"- Run `devrites-engine preamble` before DevRites workflow work.",
+		"- Use `/rite` (Claude) / `$rite` (Codex) for the DevRites menu.",
+	}
+	if slug != "" {
+		shown := filepath.Join(".devrites", "work", slug)
+		if rel, err := filepath.Rel(filepath.Dir(root), featureDir(root, slug)); err == nil {
+			shown = filepath.ToSlash(rel)
+		}
+		lines = append(lines, "- Active workspace: `"+shown+"/` (selected by `.devrites/ACTIVE` or `DEVRITES_WORKSPACE`).")
+	}
+	if isFile(filepath.Join(root, "principles.md")) {
+		lines = append(lines, "- Project principles: `.devrites/principles.md` are binding gates.")
+	}
+	lines = append(lines, contextEnd, "")
+	return strings.Join(lines, "\n")
+}
+
+func upsertContextBlock(path, block string) error {
+	if err := os.MkdirAll(filepath.Dir(path), 0o755); err != nil {
+		return fmt.Errorf("create context dir: %w", err)
+	}
+	existingBytes, _ := os.ReadFile(path)
+	existing := string(existingBytes)
+	var next string
+	start := strings.Index(existing, contextStart)
+	end := strings.Index(existing, contextEnd)
+	if start >= 0 && end > start {
+		end += len(contextEnd)
+		next = strings.TrimRight(existing[:start], "\n") + "\n\n" + strings.TrimRight(block, "\n") + "\n" + strings.TrimLeft(existing[end:], "\n")
+	} else if strings.TrimSpace(existing) == "" {
+		next = block
+	} else {
+		next = strings.TrimRight(existing, "\n") + "\n\n" + block
+	}
+	return state.AtomicWrite(path, []byte(next), 0o644)
+}