devrites 3.0.6 → 3.1.0

package/engine/internal/devritespaths/paths.go

@@ -6,6 +6,8 @@ import (
 	"os"
 	"path/filepath"
 	"strings"
+
+	"github.com/devrites/devrites/internal/safepath"
 )
 
 const (
@@ -19,22 +21,59 @@ const (
 	ManifestName = ".claude/devrites.manifest"
 )
 
-// WorkspaceOverride resolves DEVRITES_WORKSPACE relative to the project
-// directory that contains the .devrites root.
+// WorkspaceOverride resolves a valid DEVRITES_WORKSPACE. Invalid overrides are
+// ignored here so path construction stays inside root; callers that surface
+// diagnostics use WorkspaceOverrideChecked.
 func WorkspaceOverride(root, slug string) string {
+	path, _ := WorkspaceOverrideChecked(root, slug)
+	return path
+}
+
+// WorkspaceOverrideChecked resolves DEVRITES_WORKSPACE relative to the project
+// and proves its physical path remains inside the selected .devrites root.
+func WorkspaceOverrideChecked(root, slug string) (string, error) {
 	raw := strings.TrimSpace(os.Getenv("DEVRITES_WORKSPACE"))
 	if raw == "" {
-		return ""
+		return "", nil
 	}
 	path := raw
 	if !filepath.IsAbs(path) {
 		path = filepath.Join(filepath.Dir(root), path)
 	}
-	path = filepath.Clean(path)
-	if slug == "" || filepath.Base(path) == slug {
-		return path
+	abs, err := filepath.Abs(path)
+	if err != nil {
+		return "", fmt.Errorf("DRV-WORKSPACE-INVALID: resolve DEVRITES_WORKSPACE: %w", err)
 	}
-	return ""
+	path, err = safepath.ResolveExisting(abs)
+	if err != nil {
+		return "", fmt.Errorf("DRV-WORKSPACE-INVALID: resolve DEVRITES_WORKSPACE %q: %w", raw, err)
+	}
+	if !safepath.WithinResolved(path, root) {
+		return "", fmt.Errorf("DRV-WORKSPACE-OUTSIDE-ROOT: DEVRITES_WORKSPACE %q is outside %q; run `unset DEVRITES_WORKSPACE`", raw, root)
+	}
+	resolvedRoot, err := safepath.ResolveExisting(root)
+	if err != nil {
+		return "", fmt.Errorf("DRV-WORKSPACE-INVALID: resolve DevRites root %q: %w", root, err)
+	}
+	sameRoot := path == resolvedRoot
+	if pathInfo, pathErr := os.Stat(path); pathErr == nil {
+		if rootInfo, rootErr := os.Stat(resolvedRoot); rootErr == nil {
+			sameRoot = os.SameFile(pathInfo, rootInfo)
+		}
+	}
+	rel, relErr := filepath.Rel(resolvedRoot, path)
+	parts := strings.FieldsFunc(rel, func(r rune) bool {
+		return r == '/' || r == '\\'
+	})
+	canonicalWorkspace := relErr == nil && len(parts) == 2 &&
+		(parts[0] == "work" || parts[0] == "features")
+	if sameRoot || !canonicalWorkspace || !validSlug(filepath.Base(path)) {
+		return "", fmt.Errorf("DRV-WORKSPACE-INVALID: DEVRITES_WORKSPACE %q is not a feature workspace; run `unset DEVRITES_WORKSPACE`", raw)
+	}
+	if slug != "" && filepath.Base(path) != slug {
+		return "", fmt.Errorf("DRV-WORKSPACE-SLUG-MISMATCH: DEVRITES_WORKSPACE basename %q does not match feature %q; run `unset DEVRITES_WORKSPACE`", filepath.Base(path), slug)
+	}
+	return path, nil
 }
 
 // FeatureDir is the per-feature workspace directory under root. work/ is
@@ -57,20 +96,36 @@ func FeatureDir(root, slug string) string {
 // ActiveSlug reads and trims the active-feature pointer. A missing pointer file
 // is not an error; it yields the empty slug.
 func ActiveSlug(root string) (string, error) {
-	if ws := WorkspaceOverride(root, ""); ws != "" {
+	if ws, err := WorkspaceOverrideChecked(root, ""); err != nil {
+		return "", err
+	} else if ws != "" {
 		return filepath.Base(ws), nil
 	}
-	raw, err := os.ReadFile(filepath.Join(root, "ACTIVE"))
+	activePath := filepath.Join(root, "ACTIVE")
+	if info, err := os.Lstat(activePath); err == nil && info.Mode()&os.ModeSymlink != 0 {
+		return "", fmt.Errorf("DRV-ACTIVE-SYMLINK: ACTIVE is a symlink; run `rm -f %q`", activePath)
+	}
+	raw, err := os.ReadFile(activePath)
 	if errors.Is(err, os.ErrNotExist) {
 		return "", nil
 	}
 	if err != nil {
 		return "", fmt.Errorf("read active feature: %w", err)
 	}
-	return strings.TrimSpace(string(raw)), nil
+	slug := strings.TrimSpace(string(raw))
+	if slug != "" && !validSlug(slug) {
+		return "", fmt.Errorf("DRV-ACTIVE-INVALID: ACTIVE value %q is not a feature slug; run `rm -f %q`", slug, activePath)
+	}
+	return slug, nil
 }
 
 func isDir(path string) bool {
 	info, err := os.Stat(path)
 	return err == nil && info.IsDir()
 }
+
+func validSlug(slug string) bool {
+	return slug != "" && slug != "." && slug != ".." &&
+		filepath.Base(slug) == slug &&
+		!strings.ContainsAny(slug, `/\`)
+}

package/engine/internal/devritespaths/paths_test.go

@@ -0,0 +1,110 @@
+package devritespaths
+
+import (
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+func TestWorkspaceOverrideCheckedRequiresPhysicalRootContainment(t *testing.T) {
+	project := t.TempDir()
+	root := filepath.Join(project, DevritesRootName)
+	workspace := filepath.Join(root, "work", "feature")
+	if err := os.MkdirAll(workspace, 0o755); err != nil {
+		t.Fatal(err)
+	}
+
+	t.Setenv("DEVRITES_WORKSPACE", workspace)
+	got, err := WorkspaceOverrideChecked(root, "feature")
+	if err != nil {
+		t.Fatal(err)
+	}
+	want, err := filepath.EvalSymlinks(workspace)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if got != want {
+		t.Fatalf("WorkspaceOverrideChecked() = %q, want canonical %q", got, want)
+	}
+	t.Setenv("DEVRITES_WORKSPACE", filepath.Join(DevritesRootName, "work", "feature"))
+	if got, err := WorkspaceOverrideChecked(root, "feature"); err != nil || got != want {
+		t.Fatalf("relative WorkspaceOverrideChecked() = %q, %v; want %q", got, err, want)
+	}
+
+	outside := filepath.Join(t.TempDir(), "feature")
+	t.Setenv("DEVRITES_WORKSPACE", outside)
+	if _, err := WorkspaceOverrideChecked(root, "feature"); err == nil || !strings.Contains(err.Error(), "DRV-WORKSPACE-OUTSIDE-ROOT") {
+		t.Fatalf("outside workspace error = %v, want stable containment diagnostic", err)
+	}
+	if got := WorkspaceOverride(root, "feature"); got != "" {
+		t.Fatalf("unsafe compatibility result = %q, want empty", got)
+	}
+
+	t.Setenv("DEVRITES_WORKSPACE", root)
+	if _, err := WorkspaceOverrideChecked(root, ""); err == nil || !strings.Contains(err.Error(), "DRV-WORKSPACE-INVALID") {
+		t.Fatalf("root-as-workspace error = %v", err)
+	}
+
+	arbitrary := filepath.Join(root, "extensions", "feature")
+	if err := os.MkdirAll(arbitrary, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	t.Setenv("DEVRITES_WORKSPACE", arbitrary)
+	if _, err := WorkspaceOverrideChecked(root, ""); err == nil || !strings.Contains(err.Error(), "DRV-WORKSPACE-INVALID") {
+		t.Fatalf("non-feature path error = %v", err)
+	}
+}
+
+func TestWorkspaceOverrideCheckedRejectsSymlinkEscapeAndSlugMismatch(t *testing.T) {
+	project := t.TempDir()
+	root := filepath.Join(project, DevritesRootName)
+	if err := os.MkdirAll(filepath.Join(root, "work"), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	outside := t.TempDir()
+	link := filepath.Join(root, "work", "feature")
+	if err := os.Symlink(outside, link); err != nil {
+		t.Skipf("symlinks unavailable: %v", err)
+	}
+	t.Setenv("DEVRITES_WORKSPACE", link)
+	if _, err := WorkspaceOverrideChecked(root, "feature"); err == nil || !strings.Contains(err.Error(), "DRV-WORKSPACE-OUTSIDE-ROOT") {
+		t.Fatalf("symlink escape error = %v", err)
+	}
+
+	inside := filepath.Join(root, "work", "other")
+	if err := os.MkdirAll(inside, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	t.Setenv("DEVRITES_WORKSPACE", inside)
+	if _, err := WorkspaceOverrideChecked(root, "feature"); err == nil || !strings.Contains(err.Error(), "DRV-WORKSPACE-SLUG-MISMATCH") {
+		t.Fatalf("slug mismatch error = %v", err)
+	}
+}
+
+func TestActiveSlugRejectsPathTraversal(t *testing.T) {
+	root := filepath.Join(t.TempDir(), DevritesRootName)
+	if err := os.MkdirAll(root, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(root, "ACTIVE"), []byte("../../outside\n"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	if _, err := ActiveSlug(root); err == nil || !strings.Contains(err.Error(), "DRV-ACTIVE-INVALID") {
+		t.Fatalf("ActiveSlug error = %v, want stable invalid-pointer diagnostic", err)
+	}
+
+	if err := os.Remove(filepath.Join(root, "ACTIVE")); err != nil {
+		t.Fatal(err)
+	}
+	target := filepath.Join(t.TempDir(), "ACTIVE")
+	if err := os.WriteFile(target, []byte("feature\n"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.Symlink(target, filepath.Join(root, "ACTIVE")); err != nil {
+		t.Skipf("symlinks unavailable: %v", err)
+	}
+	if _, err := ActiveSlug(root); err == nil || !strings.Contains(err.Error(), "DRV-ACTIVE-SYMLINK") {
+		t.Fatalf("ActiveSlug symlink error = %v, want stable pointer diagnostic", err)
+	}
+}

package/engine/internal/doctor/doctor.go

@@ -1,22 +1,24 @@
-// Package doctor reports the version triangle: the engine binary, the installed
-// DevRites pack, and the on-disk .devrites state schema, and a clear skew
-// verdict. Version skew is a leading cause of silent breakage; doctor turns it
-// into one legible line. Everything here is a read; doctor never mutates state.
+// Package doctor compares the engine, installed pack, and workspace schema
+// versions. It also reports root and installation problems without changing
+// workspace state.
 package doctor
 
 import (
+	"crypto/sha256"
 	"encoding/json"
 	"fmt"
+	"io/fs"
 	"os"
 	"path/filepath"
 	"strings"
 
+	"github.com/devrites/devrites/internal/rootfacts"
 	"github.com/devrites/devrites/internal/state"
 	"github.com/devrites/devrites/internal/version"
 )
 
-// Unknown is the pack value reported when the installed pack version can't be
-// discovered: skew against an unknown pack is not asserted.
+// Unknown is reported when the installed pack version cannot be found. Doctor
+// does not report version skew against this value.
 const Unknown = "unknown"
 
 // Report is the resolved version triangle plus its verdict.
@@ -27,28 +29,45 @@ type Report struct {
 	BinarySchema int      // the schema version this binary understands
 	Verdict      string   // one-line human summary
 	Checks       []string // advisory install/host-artifact drift checks
-	Refuse       bool     // true iff state schema is a newer major than the binary supports
+	Refuse       bool     // true when topology or state schema makes action unsafe
+	Root         rootfacts.Facts
 }
 
-// Diagnose resolves the triangle for the project rooted at projectDir with the
-// .devrites directory at root, and computes the skew verdict.
+// Diagnose compares versions for projectDir and its .devrites root.
 //
-//   - State schema newer (higher major) than the binary supports → Refuse: the
-//     binary would not safely parse it, so it reports that rather than guessing.
-//   - Binary older than the installed pack → a warning, never a block: an older
-//     binary can still run; the user is just told to update.
-//   - Otherwise → ok. Additive changes (older state read by a newer binary) are
-//     always fine.
+//   - A state schema newer than the binary causes a refusal because the binary
+//     cannot safely parse it.
+//   - A binary older than the pack produces a warning but does not block.
+//   - All other comparable versions are compatible. A newer binary can read
+//     older state because schema changes are additive.
 func Diagnose(projectDir, root string) (*Report, error) {
-	stateSchema, err := state.MaxDeclaredSchemaVersion(root)
-	if err != nil {
-		return nil, fmt.Errorf("read state schema: %w", err)
-	}
-	if stateSchema == 0 {
-		// Nothing on disk declares a version: treat it as the current schema;
-		// undeclared state is read as the engine's own version.
-		stateSchema = state.SchemaVersion
+	return DiagnoseFacts(rootfacts.Facts{
+		LexicalProject:  projectDir,
+		PhysicalProject: projectDir,
+		LexicalRoot:     root,
+		PhysicalRoot:    root,
+		SelectionReason: "provided",
+		Hazards:         []rootfacts.Hazard{},
+	})
+}
+
+// DiagnoseFacts reports the same canonical root facts used by state selection
+// and context show.
+func DiagnoseFacts(facts rootfacts.Facts) (*Report, error) {
+	stateSchema := state.SchemaVersion
+	if facts.PhysicalRoot != "" {
+		var err error
+		stateSchema, err = state.MaxDeclaredSchemaVersion(facts.PhysicalRoot)
+		if err != nil {
+			return nil, fmt.Errorf("read state schema: %w", err)
+		}
+		if stateSchema == 0 {
+			// Nothing on disk declares a version: treat it as the current schema;
+			// undeclared state is read as the engine's own version.
+			stateSchema = state.SchemaVersion
+		}
 	}
+	projectDir := facts.PhysicalProject
 
 	r := &Report{
 		Binary:       version.Version,
@@ -56,9 +75,13 @@ func Diagnose(projectDir, root string) (*Report, error) {
 		StateSchema:  stateSchema,
 		BinarySchema: state.SchemaVersion,
 		Checks:       driftChecks(projectDir),
+		Root:         facts,
 	}
 
 	switch {
+	case facts.Refuses():
+		r.Refuse = true
+		r.Verdict = "REFUSE: root or workspace selection is unsafe; apply the reported remediation"
 	case r.StateSchema > r.BinarySchema:
 		r.Refuse = true
 		r.Verdict = fmt.Sprintf("REFUSE: state schema v%d is newer than this binary supports (v%d): update devrites",
@@ -66,6 +89,8 @@ func Diagnose(projectDir, root string) (*Report, error) {
 	case r.packSkew():
 		r.Verdict = fmt.Sprintf("WARN: binary %s is older than the installed pack %s: update the devrites-engine binary",
 			r.Binary, r.Pack)
+	case len(facts.Hazards) > 0:
+		r.Verdict = "WARN: workspace or repository hazards need attention"
 	default:
 		r.Verdict = "ok: binary, pack, and state schema are compatible"
 	}
@@ -84,10 +109,46 @@ func (r *Report) packSkew() bool {
 // Render produces the deterministic doctor report with a trailing newline.
 func (r *Report) Render() string {
 	var b strings.Builder
+	physicalRoot := r.Root.PhysicalRoot
+	if physicalRoot == "" {
+		physicalRoot = "none"
+	}
+	physicalProject := r.Root.PhysicalProject
+	if physicalProject == "" {
+		physicalProject = "unknown"
+	}
+	fmt.Fprintf(&b, "project: %s\n", physicalProject)
+	fmt.Fprintf(&b, "root: %s\n", physicalRoot)
+	fmt.Fprintf(&b, "root-selection: %s\n", r.Root.SelectionReason)
+	if r.Root.LexicalProject != "" && r.Root.LexicalProject != r.Root.PhysicalProject {
+		fmt.Fprintf(&b, "project-lexical: %s\n", r.Root.LexicalProject)
+	}
+	if r.Root.LexicalRoot != "" && r.Root.LexicalRoot != r.Root.PhysicalRoot {
+		fmt.Fprintf(&b, "root-lexical: %s\n", r.Root.LexicalRoot)
+	}
+	if r.Root.Git.TopLevel == "" {
+		fmt.Fprintln(&b, "git: none")
+	} else {
+		fmt.Fprintf(&b, "git: top=%s dir=%s common=%s linked-worktree=%t submodule=%t\n",
+			r.Root.Git.TopLevel, r.Root.Git.Dir, r.Root.Git.CommonDir,
+			r.Root.Git.LinkedWorktree, r.Root.Git.Submodule)
+		if r.Root.Git.Superproject != "" {
+			fmt.Fprintf(&b, "git-superproject: %s\n", r.Root.Git.Superproject)
+		}
+	}
 	fmt.Fprintf(&b, "binary: %s\n", r.Binary)
 	fmt.Fprintf(&b, "pack: %s\n", r.Pack)
 	fmt.Fprintf(&b, "state-schema: v%d (binary supports v%d)\n", r.StateSchema, r.BinarySchema)
 	fmt.Fprintf(&b, "verdict: %s\n", r.Verdict)
+	if len(r.Root.Hazards) == 0 {
+		fmt.Fprintln(&b, "hazards: ok")
+	} else {
+		fmt.Fprintln(&b, "hazards:")
+		for _, hazard := range r.Root.Hazards {
+			fmt.Fprintf(&b, "  - [%s] %s: %s\n", hazard.ID, strings.ToUpper(hazard.Severity), hazard.Message)
+			fmt.Fprintf(&b, "    fix: %s\n", hazard.Remediation)
+		}
+	}
 	if len(r.Checks) == 0 {
 		fmt.Fprintln(&b, "checks: ok")
 	} else {
@@ -142,9 +203,78 @@ func driftChecks(projectDir string) []string {
 	if firstLine(filepath.Join(projectDir, ".claude", "devrites.version")) == "" && isDir(filepath.Join(projectDir, ".claude", "skills")) {
 		checks = append(checks, "WARN: installed skills have no .claude/devrites.version marker")
 	}
+	if generatedClaudeDrift(projectDir) {
+		checks = append(checks, "[DRV-GENERATED-DRIFT] WARN: pack/generated/claude differs from canonical pack/.claude; run `bash scripts/build-host-artifacts.sh`")
+	}
 	return checks
 }
 
+func generatedClaudeDrift(projectDir string) bool {
+	canonical := filepath.Join(projectDir, "pack", ".claude")
+	generated := filepath.Join(projectDir, "pack", "generated", "claude")
+	if !isDir(canonical) {
+		return false
+	}
+	want, err := fileDigests(canonical, func(rel string) bool {
+		return rel == filepath.Join("agents", ".impeccable") ||
+			strings.HasPrefix(rel, filepath.Join("agents", ".impeccable")+string(filepath.Separator))
+	})
+	if err != nil {
+		return true
+	}
+	got, err := fileDigests(generated, nil)
+	if err != nil || len(want) != len(got) {
+		return true
+	}
+	for path, digest := range want {
+		if got[path] != digest {
+			return true
+		}
+	}
+	return false
+}
+
+func fileDigests(root string, skip func(string) bool) (map[string][sha256.Size]byte, error) {
+	rootDir, err := os.OpenRoot(root)
+	if err != nil {
+		return nil, err
+	}
+	defer func() { _ = rootDir.Close() }()
+
+	files := map[string][sha256.Size]byte{}
+	err = filepath.WalkDir(root, func(path string, entry fs.DirEntry, err error) error {
+		if err != nil {
+			return err
+		}
+		rel, err := filepath.Rel(root, path)
+		if err != nil {
+			return err
+		}
+		if rel == "." {
+			return nil
+		}
+		if skip != nil && skip(rel) {
+			if entry.IsDir() {
+				return filepath.SkipDir
+			}
+			return nil
+		}
+		if entry.IsDir() {
+			return nil
+		}
+		if entry.Type()&os.ModeSymlink != 0 || !entry.Type().IsRegular() {
+			return fmt.Errorf("generated tree contains non-regular file %s", rel)
+		}
+		body, err := rootDir.ReadFile(rel)
+		if err != nil {
+			return err
+		}
+		files[filepath.ToSlash(rel)] = sha256.Sum256(body)
+		return nil
+	})
+	return files, err
+}
+
 func readString(path string) string {
 	raw, err := os.ReadFile(path)
 	if err != nil {

package/engine/internal/doctor/doctor_test.go

@@ -6,6 +6,7 @@ import (
 	"strings"
 	"testing"
 
+	"github.com/devrites/devrites/internal/rootfacts"
 	"github.com/devrites/devrites/internal/version"
 )
 
@@ -148,3 +149,76 @@ func TestDiagnoseReportsHostArtifactDrift(t *testing.T) {
 		}
 	}
 }
+
+func TestDiagnoseFactsReportsCanonicalRootAndStaleActive(t *testing.T) {
+	projectDir := t.TempDir()
+	root := filepath.Join(projectDir, ".devrites")
+	if err := os.MkdirAll(root, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(root, "ACTIVE"), []byte("ghost\n"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	facts, err := rootfacts.ResolveFrom(projectDir, projectDir)
+	if err != nil {
+		t.Fatal(err)
+	}
+	r, err := DiagnoseFacts(facts)
+	if err != nil {
+		t.Fatal(err)
+	}
+	out := r.Render()
+	for _, want := range []string{
+		"root: " + facts.PhysicalRoot,
+		"root-selection: DEVRITES_ROOT",
+		"[DRV-ACTIVE-STALE]",
+		"fix: rm -f",
+	} {
+		if !strings.Contains(out, want) {
+			t.Fatalf("doctor output missing %q:\n%s", want, out)
+		}
+	}
+	if r.Refuse {
+		t.Fatal("stale ACTIVE should warn, not turn a read-only doctor run into a refusal")
+	}
+}
+
+func TestDiagnoseReportsCanonicalGeneratedResidue(t *testing.T) {
+	projectDir := t.TempDir()
+	canonical := filepath.Join(projectDir, "pack", ".claude")
+	generated := filepath.Join(projectDir, "pack", "generated", "claude")
+	for _, dir := range []string{canonical, generated} {
+		if err := os.MkdirAll(dir, 0o755); err != nil {
+			t.Fatal(err)
+		}
+	}
+	for _, path := range []string{
+		filepath.Join(canonical, "settings.json"),
+		filepath.Join(generated, "settings.json"),
+	} {
+		if err := os.WriteFile(path, []byte(`{"hooks":{}}`), 0o644); err != nil {
+			t.Fatal(err)
+		}
+	}
+	root := t.TempDir()
+	writeFeature(t, root, "f", 1)
+	aligned, err := Diagnose(projectDir, root)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if strings.Contains(aligned.Render(), "DRV-GENERATED-DRIFT") {
+		t.Fatalf("aligned generated tree reported drift:\n%s", aligned.Render())
+	}
+
+	if err := os.WriteFile(filepath.Join(generated, "legacy.json"), []byte("{}"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	drifted, err := Diagnose(projectDir, root)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !strings.Contains(drifted.Render(), "[DRV-GENERATED-DRIFT]") ||
+		!strings.Contains(drifted.Render(), "bash scripts/build-host-artifacts.sh") {
+		t.Fatalf("generated residue not diagnosed:\n%s", drifted.Render())
+	}
+}