devrites 2.6.0 → 3.0.0

package/engine/internal/doctor/doctor.go

@@ -0,0 +1,178 @@
+// 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
+
+import (
+	"encoding/json"
+	"fmt"
+	"os"
+	"path/filepath"
+	"strings"
+
+	"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.
+const Unknown = "unknown"
+
+// Report is the resolved version triangle plus its verdict.
+type Report struct {
+	Binary       string   // the engine binary version
+	Pack         string   // the installed pack version, or Unknown
+	StateSchema  int      // the highest schemaVersion declared on disk
+	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
+}
+
+// Diagnose resolves the triangle for the project rooted at projectDir with the
+// .devrites directory at root, and computes the skew verdict.
+//
+//   - 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.
+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
+	}
+
+	r := &Report{
+		Binary:       version.Version,
+		Pack:         packVersion(projectDir),
+		StateSchema:  stateSchema,
+		BinarySchema: state.SchemaVersion,
+		Checks:       driftChecks(projectDir),
+	}
+
+	switch {
+	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",
+			r.StateSchema, r.BinarySchema)
+	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)
+	default:
+		r.Verdict = "ok: binary, pack, and state schema are compatible"
+	}
+	return r, nil
+}
+
+// packSkew reports whether the binary is comparably older than the pack.
+func (r *Report) packSkew() bool {
+	if r.Pack == Unknown {
+		return false
+	}
+	cmp, ok := version.Compare(r.Binary, r.Pack)
+	return ok && cmp < 0
+}
+
+// Render produces the deterministic doctor report with a trailing newline.
+func (r *Report) Render() string {
+	var b strings.Builder
+	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.Checks) == 0 {
+		fmt.Fprintln(&b, "checks: ok")
+	} else {
+		fmt.Fprintln(&b, "checks:")
+		for _, check := range r.Checks {
+			fmt.Fprintf(&b, "  - %s\n", check)
+		}
+	}
+	return b.String()
+}
+
+// packVersion discovers the installed DevRites pack version. It prefers an
+// explicit marker (.claude/devrites.version) and falls back to the npm
+// package.json at the project root; either absent leaves the pack Unknown so no
+// false skew is asserted.
+func packVersion(projectDir string) string {
+	if v := firstLine(filepath.Join(projectDir, ".claude", "devrites.version")); v != "" {
+		return v
+	}
+	if v := packageJSONVersion(filepath.Join(projectDir, "package.json")); v != "" {
+		return v
+	}
+	return Unknown
+}
+
+func firstLine(path string) string {
+	raw, err := os.ReadFile(path)
+	if err != nil {
+		return ""
+	}
+	line, _, _ := strings.Cut(string(raw), "\n")
+	return strings.TrimSpace(line)
+}
+
+func driftChecks(projectDir string) []string {
+	var checks []string
+	settings := filepath.Join(projectDir, ".claude", "settings.json")
+	if isFile(settings) {
+		body := readString(settings)
+		if !strings.Contains(body, "devrites-engine hook") {
+			checks = append(checks, "WARN: .claude/settings.json exists but does not reference devrites-engine hooks")
+		}
+	} else if isDir(filepath.Join(projectDir, ".claude")) {
+		checks = append(checks, "WARN: .claude/settings.json missing — Claude hooks/statusline may be absent")
+	}
+	if isDir(filepath.Join(projectDir, ".claude", "skills")) && !isDir(filepath.Join(projectDir, ".agents", "skills")) {
+		checks = append(checks, "WARN: Claude skills installed but Codex skill mirror .agents/skills is missing")
+	}
+	if isDir(filepath.Join(projectDir, ".claude", "agents")) && !isDir(filepath.Join(projectDir, ".codex", "agents")) {
+		checks = append(checks, "WARN: Claude agents installed but Codex agent mirror .codex/agents is missing")
+	}
+	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")
+	}
+	return checks
+}
+
+func readString(path string) string {
+	raw, err := os.ReadFile(path)
+	if err != nil {
+		return ""
+	}
+	return string(raw)
+}
+
+func isFile(path string) bool {
+	info, err := os.Stat(path)
+	return err == nil && !info.IsDir()
+}
+
+func isDir(path string) bool {
+	info, err := os.Stat(path)
+	return err == nil && info.IsDir()
+}
+
+func packageJSONVersion(path string) string {
+	raw, err := os.ReadFile(path)
+	if err != nil {
+		return ""
+	}
+	var pkg struct {
+		Version string `json:"version"`
+	}
+	if err := json.Unmarshal(raw, &pkg); err != nil {
+		return ""
+	}
+	return strings.TrimSpace(pkg.Version)
+}

package/engine/internal/doctor/doctor_test.go

@@ -0,0 +1,150 @@
+package doctor
+
+import (
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"github.com/devrites/devrites/internal/version"
+)
+
+// withBinaryVersion temporarily overrides the compiled-in binary version so skew
+// verdicts can be exercised deterministically.
+func withBinaryVersion(t *testing.T, v string) {
+	t.Helper()
+	prev := version.Version
+	version.Version = v
+	t.Cleanup(func() { version.Version = prev })
+}
+
+// writeFeature creates a minimal feature.md declaring a schemaVersion under root.
+func writeFeature(t *testing.T, root, slug string, schema int) {
+	t.Helper()
+	dir := filepath.Join(root, "features", slug)
+	if err := os.MkdirAll(dir, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	content := "---\nslug: " + slug + "\nphase: build\nschemaVersion: " +
+		itoa(schema) + "\n---\n\nx\n"
+	if err := os.WriteFile(filepath.Join(dir, "feature.md"), []byte(content), 0o644); err != nil {
+		t.Fatal(err)
+	}
+}
+
+func itoa(n int) string {
+	if n == 0 {
+		return "0"
+	}
+	var b []byte
+	for n > 0 {
+		b = append([]byte{byte('0' + n%10)}, b...)
+		n /= 10
+	}
+	return string(b)
+}
+
+func TestDiagnoseOKWhenAligned(t *testing.T) {
+	withBinaryVersion(t, "2.6.1")
+	root := t.TempDir()
+	writeFeature(t, root, "f", 1) // state v1, binary supports v1
+	r, err := Diagnose(t.TempDir(), root)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if r.Refuse {
+		t.Errorf("Refuse = true, want false when aligned")
+	}
+	if got := r.Verdict; got == "" || got[:2] != "ok" {
+		t.Errorf("verdict = %q, want an ok verdict", got)
+	}
+}
+
+func TestDiagnoseWarnsWhenBinaryOlderThanPack(t *testing.T) {
+	withBinaryVersion(t, "1.0.0")
+	projectDir := t.TempDir()
+	// Pack marker newer than the binary → warn, not refuse.
+	claude := filepath.Join(projectDir, ".claude")
+	if err := os.MkdirAll(claude, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(claude, "devrites.version"), []byte("2.0.0\n"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	root := t.TempDir()
+	writeFeature(t, root, "f", 1)
+
+	r, err := Diagnose(projectDir, root)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if r.Refuse {
+		t.Errorf("a pack-vs-binary skew must warn, not refuse")
+	}
+	if r.Pack != "2.0.0" {
+		t.Errorf("pack = %q, want 2.0.0", r.Pack)
+	}
+	if want := "WARN"; len(r.Verdict) < 4 || r.Verdict[:4] != want {
+		t.Errorf("verdict = %q, want a WARN verdict", r.Verdict)
+	}
+}
+
+func TestDiagnoseRefusesNewerStateSchema(t *testing.T) {
+	withBinaryVersion(t, "2.6.1")
+	root := t.TempDir()
+	writeFeature(t, root, "f", 99) // far newer than the binary supports
+	r, err := Diagnose(t.TempDir(), root)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !r.Refuse {
+		t.Errorf("Refuse = false, want true for a newer-major state schema")
+	}
+	if len(r.Verdict) < 6 || r.Verdict[:6] != "REFUSE" {
+		t.Errorf("verdict = %q, want a REFUSE verdict", r.Verdict)
+	}
+}
+
+func TestDiagnoseDevBinaryNeverFalseWarns(t *testing.T) {
+	withBinaryVersion(t, "dev") // incomparable
+	projectDir := t.TempDir()
+	claude := filepath.Join(projectDir, ".claude")
+	_ = os.MkdirAll(claude, 0o755)
+	_ = os.WriteFile(filepath.Join(claude, "devrites.version"), []byte("9.9.9\n"), 0o644)
+	root := t.TempDir()
+	writeFeature(t, root, "f", 1)
+
+	r, err := Diagnose(projectDir, root)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if r.Refuse || (len(r.Verdict) >= 4 && r.Verdict[:4] == "WARN") {
+		t.Errorf("a dev (incomparable) binary must not warn on skew; verdict=%q", r.Verdict)
+	}
+}
+
+func TestDiagnoseReportsHostArtifactDrift(t *testing.T) {
+	projectDir := t.TempDir()
+	if err := os.MkdirAll(filepath.Join(projectDir, ".claude", "skills", "rite-build"), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(projectDir, ".claude", "settings.json"), []byte(`{"hooks":{}}`), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	root := t.TempDir()
+	writeFeature(t, root, "f", 1)
+
+	r, err := Diagnose(projectDir, root)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(r.Checks) == 0 {
+		t.Fatal("expected drift checks")
+	}
+	out := r.Render()
+	for _, want := range []string{"devrites-engine hooks", "Codex skill mirror", "devrites.version marker"} {
+		if !strings.Contains(out, want) {
+			t.Fatalf("doctor output missing %q:\n%s", want, out)
+		}
+	}
+}

package/engine/internal/fsutil/copy.go

@@ -0,0 +1,101 @@
+package fsutil
+
+import (
+	"fmt"
+	"io/fs"
+	"os"
+	"path/filepath"
+)
+
+// WriteFileAtomic writes path by first writing a sibling temp file and then
+// renaming it into place.
+func WriteFileAtomic(path string, data []byte, perm fs.FileMode) error {
+	if err := os.MkdirAll(filepath.Dir(path), 0o755); err != nil {
+		return fmt.Errorf("atomic write %s: %w", path, err)
+	}
+	tmp, err := os.CreateTemp(filepath.Dir(path), "."+filepath.Base(path)+".tmp-*")
+	if err != nil {
+		return fmt.Errorf("atomic write %s: %w", path, err)
+	}
+	tmpName := tmp.Name()
+	cleanup := true
+	defer func() {
+		if cleanup {
+			_ = os.Remove(tmpName)
+		}
+	}()
+	if _, err := tmp.Write(data); err != nil {
+		_ = tmp.Close()
+		return fmt.Errorf("atomic write %s: %w", path, err)
+	}
+	if err := tmp.Chmod(perm); err != nil {
+		_ = tmp.Close()
+		return fmt.Errorf("atomic write %s: %w", path, err)
+	}
+	if err := tmp.Sync(); err != nil {
+		_ = tmp.Close()
+		return fmt.Errorf("atomic write %s: %w", path, err)
+	}
+	if err := tmp.Close(); err != nil {
+		return fmt.Errorf("atomic write %s: %w", path, err)
+	}
+	if err := replaceFile(tmpName, path); err != nil {
+		return fmt.Errorf("atomic write %s: %w", path, err)
+	}
+	cleanup = false
+	return nil
+}
+
+// FileModTime returns a regular file's modification time in whole seconds.
+func FileModTime(path string) (int64, bool) {
+	info, err := os.Stat(path)
+	if err != nil || !info.Mode().IsRegular() {
+		return 0, false
+	}
+	return info.ModTime().Unix(), true
+}
+
+// NewestModTime returns the newest modification time among regular files.
+func NewestModTime(paths ...string) (newest int64, ok bool) {
+	for _, path := range paths {
+		if modified, exists := FileModTime(path); exists && (!ok || modified > newest) {
+			newest, ok = modified, true
+		}
+	}
+	return newest, ok
+}
+
+// CopyTree recursively copies src to dst, creating parent directories and
+// overwriting files. A missing src is not an error.
+func CopyTree(src, dst string) error {
+	info, err := os.Stat(src)
+	if os.IsNotExist(err) {
+		return nil
+	}
+	if err != nil {
+		return fmt.Errorf("copy %s: %w", src, err)
+	}
+	if !info.IsDir() {
+		data, err := os.ReadFile(src)
+		if err != nil {
+			return fmt.Errorf("copy %s: %w", src, err)
+		}
+		if err := os.MkdirAll(filepath.Dir(dst), 0o755); err != nil {
+			return fmt.Errorf("copy to %s: %w", dst, err)
+		}
+		return os.WriteFile(dst, data, 0o644)
+	}
+	entries, err := os.ReadDir(src)
+	if err != nil {
+		return fmt.Errorf("copy %s: %w", src, err)
+	}
+	if err := os.MkdirAll(dst, 0o755); err != nil {
+		return fmt.Errorf("copy to %s: %w", dst, err)
+	}
+	for _, e := range entries {
+		if err := CopyTree(filepath.Join(src, e.Name()), filepath.Join(dst, e.Name())); err != nil {
+			return err
+		}
+	}
+	return nil
+}

package/engine/internal/fsutil/replace_other.go

@@ -0,0 +1,7 @@
+//go:build !windows
+
+package fsutil
+
+import "os"
+
+func replaceFile(from, to string) error { return os.Rename(from, to) }

package/engine/internal/fsutil/replace_windows.go

@@ -0,0 +1,31 @@
+//go:build windows
+
+package fsutil
+
+import (
+	"syscall"
+	"unsafe"
+)
+
+const moveFileReplaceExisting = 0x1
+
+var moveFileEx = syscall.NewLazyDLL("kernel32.dll").NewProc("MoveFileExW")
+
+func replaceFile(from, to string) error {
+	fromPtr, err := syscall.UTF16PtrFromString(from)
+	if err != nil {
+		return err
+	}
+	toPtr, err := syscall.UTF16PtrFromString(to)
+	if err != nil {
+		return err
+	}
+	if ok, _, callErr := moveFileEx.Call(
+		uintptr(unsafe.Pointer(fromPtr)),
+		uintptr(unsafe.Pointer(toPtr)),
+		moveFileReplaceExisting,
+	); ok == 0 {
+		return callErr
+	}
+	return nil
+}