tdd-enforcer 0.1.0

package/adapters/pi/tools.ts

@@ -0,0 +1,165 @@
+import { Type } from "typebox";
+import { execSync } from "node:child_process";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import {
+  savePhaseState,
+  nextPhase,
+  checkGate,
+  getDisallowedChanges,
+  snapshot,
+  hasParent,
+  resetHard,
+  undoLastCommit,
+  headMessage,
+} from "../../engine/index.js";
+import type { TestRunner, Phase } from "../../engine/index.js";
+import { getNudgePrompt } from "./prompts.js";
+import { loadTddState } from "./helpers.js";
+
+
+export function registerTools(pi: ExtensionAPI): void {
+  pi.registerTool({
+    name: "next_tdd_phase",
+    label: "Next TDD Phase",
+    description:
+      "Advance to the next TDD phase. Runs transition gates (test pass/fail checks) " +
+      "and allowlist validation (no forbidden files modified).",
+    parameters: Type.Object({}),
+    async execute(_toolCallId, _params, _signal, _onUpdate, ctx) {
+      const root = ctx.cwd;
+      const tdd = loadTddState(root);
+      if (!tdd.ok) {
+        return { content: [{ type: "text", text: `TDD: ${tdd.reason}` }], details: {} };
+      }
+
+      const { state, config } = tdd;
+      const from = state.current;
+      const to = nextPhase(from);
+      if (!to) {
+        return { content: [{ type: "text", text: `No next phase from ${from}.` }], details: {} };
+      }
+
+      // 1. Allowlist check
+      const violations = getDisallowedChanges(root, from, config);
+      if (violations.length > 0) {
+        return {
+          content: [
+            {
+              type: "text",
+              text:
+                `BLOCKED: files not allowed in ${from.toUpperCase()} phase:\n` +
+                violations.map((f) => `  - ${f}`).join("\n") +
+                "\nRevert or remove them before proceeding.",
+            },
+          ],
+          details: {},
+        };
+      }
+
+      // 2. Gate check
+      const testRunner: TestRunner = async (commands, timeout) => {
+        const results = await Promise.all(
+          commands.map(async (cmd) => {
+            try {
+              execSync(cmd, { cwd: root, stdio: "pipe", timeout: timeout * 1000 });
+              return { command: cmd, passed: true };
+            } catch {
+              return { command: cmd, passed: false };
+            }
+          }),
+        );
+
+        const failed = results.filter((r) => !r.passed);
+        if (failed.length > 0) {
+          return {
+            passed: false,
+            message: "Tests failed:\n" + failed.map((f) => `  - ${f.command}`).join("\n"),
+          };
+        }
+        return { passed: true, message: "All tests passed." };
+      };
+
+      const gate = await checkGate(from, to, testRunner, config);
+      if (!gate.passed) {
+        return { content: [{ type: "text", text: gate.message }], details: {} };
+      }
+
+      // 3. Snapshot — label with the phase the work was done in
+      snapshot(root, from);
+
+      // 4. Save state
+      state.current = to;
+      savePhaseState(root, state);
+
+      return {
+        content: [{ type: "text", text: getNudgePrompt(to, config) }],
+        details: {},
+      };
+    },
+  });
+
+  pi.registerTool({
+    name: "previous_tdd_phase",
+    label: "Previous TDD Phase",
+    description:
+      "WARNING: Destroys ALL uncommitted changes and pops the last snapshot commit. " +
+      "Working tree keeps the popped commit's content as unstaged changes.",
+    parameters: Type.Object({}),
+    async execute(_toolCallId, _params, _signal, _onUpdate, ctx) {
+      const root = ctx.cwd;
+      const tdd = loadTddState(root);
+      if (!tdd.ok) {
+        return { content: [{ type: "text", text: `TDD: ${tdd.reason}` }], details: {} };
+      }
+
+      const { state } = tdd;
+
+      if (!hasParent(root)) {
+        return {
+          content: [{ type: "text", text: "No previous phase to revert to." }],
+          details: {},
+        };
+      }
+
+      // Read phase from HEAD snapshot commit message (source of truth).
+      // Snapshot is labeled with the phase the work was done in, so we use
+      // it directly — no hardcoded phase map needed.
+      const headMsg = headMessage(root);
+      const phaseMatch = headMsg.match(/^tdd: (red|green|refactor)/);
+      if (!phaseMatch) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: `HEAD commit "${headMsg}" is not a TDD snapshot. Cannot determine previous phase.\n` +
+                    `The private git repo at .pi/tdd must not be manually modified. ` +
+                    `Tampering with it will cause TDD state corruption.`,
+            },
+          ],
+          details: {},
+        };
+      }
+      const prevPhase = phaseMatch[1] as Phase;
+
+      // 1. Nuke any uncommitted changes, WT matches HEAD
+      resetHard(root);
+
+      // 2. Pop last snapshot commit, keep its content as unstaged
+      undoLastCommit(root);
+
+      // 3. Update phase label from the snapshot's own label
+      state.current = prevPhase;
+      savePhaseState(root, state);
+
+      return {
+        content: [
+          {
+            type: "text",
+            text: `Reverted to ${prevPhase.toUpperCase()}. Working tree has the previous snapshot content as unstaged changes.`,
+          },
+        ],
+        details: {},
+      };
+    },
+  });
+}

package/engine/config.test.ts

@@ -0,0 +1,125 @@
+import { describe, it, expect } from "vitest";
+import { existsSync, mkdirSync, writeFileSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { loadConfig } from "./config.js";
+
+function withTempDir(fn: (dir: string) => void) {
+  const dir = join(tmpdir(), `tdd-test-${Date.now()}`);
+  mkdirSync(dir, { recursive: true });
+  try {
+    fn(dir);
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+describe("loadConfig", () => {
+  it("throws when no config exists", () => {
+    withTempDir((dir) => {
+      expect(() => loadConfig(dir)).toThrow();
+    });
+  });
+
+  it("loads config from rules.json", () => {
+    withTempDir((dir) => {
+      const tddDir = join(dir, ".pi", "tdd");
+      mkdirSync(tddDir, { recursive: true });
+      writeFileSync(
+        join(tddDir, "rules.json"),
+        JSON.stringify({
+          allowedRedPhaseFiles: ["tests/**/*.test.ts"],
+          allowedGreenPhaseFiles: ["src/**/*.ts"],
+          testCommands: ["npm run test"],
+          timeoutSeconds: 60,
+        }),
+        "utf-8",
+      );
+
+      const config = loadConfig(dir);
+      expect(config.allowedRedPhaseFiles).toEqual(["tests/**/*.test.ts"]);
+      expect(config.timeoutSeconds).toBe(60);
+    });
+  });
+
+  it("supports multiple test commands", () => {
+    withTempDir((dir) => {
+      const tddDir = join(dir, ".pi", "tdd");
+      mkdirSync(tddDir, { recursive: true });
+      writeFileSync(
+        join(tddDir, "rules.json"),
+        JSON.stringify({
+          allowedRedPhaseFiles: ["tests/**/*.test.ts"],
+          allowedGreenPhaseFiles: ["src/**/*.ts"],
+          testCommands: ["npm run test:unit", "npm run test:integration"],
+        }),
+        "utf-8",
+      );
+
+      const config = loadConfig(dir);
+      expect(config.testCommands).toHaveLength(2);
+    });
+  });
+
+  describe("validation — throws on invalid content", () => {
+    it("throws when allowedRedPhaseFiles is not an array", () => {
+      withTempDir((dir) => {
+        const tddDir = join(dir, ".pi", "tdd");
+        mkdirSync(tddDir, { recursive: true });
+        writeFileSync(
+          join(tddDir, "rules.json"),
+          JSON.stringify({
+            allowedRedPhaseFiles: "not-an-array",
+            allowedGreenPhaseFiles: ["src/**/*.ts"],
+            testCommands: ["npm test"],
+          }),
+          "utf-8",
+        );
+        expect(() => loadConfig(dir)).toThrow();
+      });
+    });
+
+    it("throws when allowedGreenPhaseFiles is not an array", () => {
+      withTempDir((dir) => {
+        const tddDir = join(dir, ".pi", "tdd");
+        mkdirSync(tddDir, { recursive: true });
+        writeFileSync(
+          join(tddDir, "rules.json"),
+          JSON.stringify({
+            allowedRedPhaseFiles: ["tests/**/*.test.ts"],
+            allowedGreenPhaseFiles: null,
+            testCommands: ["npm test"],
+          }),
+          "utf-8",
+        );
+        expect(() => loadConfig(dir)).toThrow();
+      });
+    });
+
+    it("throws when testCommands is not an array", () => {
+      withTempDir((dir) => {
+        const tddDir = join(dir, ".pi", "tdd");
+        mkdirSync(tddDir, { recursive: true });
+        writeFileSync(
+          join(tddDir, "rules.json"),
+          JSON.stringify({
+            allowedRedPhaseFiles: ["tests/**/*.test.ts"],
+            allowedGreenPhaseFiles: ["src/**/*.ts"],
+            testCommands: "npm test",
+          }),
+          "utf-8",
+        );
+        expect(() => loadConfig(dir)).toThrow();
+      });
+    });
+
+    it("throws on malformed JSON", () => {
+      withTempDir((dir) => {
+        const tddDir = join(dir, ".pi", "tdd");
+        mkdirSync(tddDir, { recursive: true });
+        writeFileSync(join(tddDir, "rules.json"), "not json{{", "utf-8");
+        expect(() => loadConfig(dir)).toThrow();
+      });
+    });
+  });
+});

package/engine/config.ts

@@ -0,0 +1,32 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import type { Config } from "./types.js";
+
+const TDD_DIR = ".pi/tdd";
+
+export function configPath(projectRoot: string): string {
+  return join(projectRoot, TDD_DIR, "rules.json");
+}
+
+export function loadConfig(projectRoot: string): Config {
+  const path = configPath(projectRoot);
+  const raw = readFileSync(path, "utf-8");
+  const parsed = JSON.parse(raw);
+
+  if (!Array.isArray(parsed.allowedRedPhaseFiles)) {
+    throw new Error("rules.json: allowedRedPhaseFiles must be an array");
+  }
+  if (!Array.isArray(parsed.allowedGreenPhaseFiles)) {
+    throw new Error("rules.json: allowedGreenPhaseFiles must be an array");
+  }
+  if (!Array.isArray(parsed.testCommands)) {
+    throw new Error("rules.json: testCommands must be an array");
+  }
+
+  return {
+    allowedRedPhaseFiles: parsed.allowedRedPhaseFiles,
+    allowedGreenPhaseFiles: parsed.allowedGreenPhaseFiles,
+    testCommands: parsed.testCommands,
+    timeoutSeconds: parsed.timeoutSeconds ?? 120,
+  };
+}

package/engine/enforce.test.ts

@@ -0,0 +1,89 @@
+import { describe, it, expect } from "vitest";
+import { isAllowed, disallowedFiles } from "./enforce.js";
+import type { Config } from "./types.js";
+
+const testConfig: Config = {
+  allowedRedPhaseFiles: ["tests/**/*.test.ts", "specs/**/*.spec.ts"],
+  allowedGreenPhaseFiles: ["src/**/*.ts", "lib/**/*.ts"],
+  testCommands: ["npm test"],
+  timeoutSeconds: 30,
+};
+
+describe("isAllowed", () => {
+  it("allows everything in refactor phase", () => {
+    expect(isAllowed("any/file.ts", "refactor", testConfig)).toBe(true);
+    expect(isAllowed("tests/foo.test.ts", "refactor", testConfig)).toBe(true);
+  });
+
+  describe("red phase", () => {
+    it("allows red phase files", () => {
+      expect(isAllowed("tests/unit/foo.test.ts", "red", testConfig)).toBe(true);
+      expect(isAllowed("specs/api.spec.ts", "red", testConfig)).toBe(true);
+    });
+
+    it("blocks green phase files", () => {
+      expect(isAllowed("src/main.ts", "red", testConfig)).toBe(false);
+      expect(isAllowed("lib/helper.ts", "red", testConfig)).toBe(false);
+    });
+
+    it("allows free files (match neither)", () => {
+      expect(isAllowed("README.md", "red", testConfig)).toBe(true);
+      expect(isAllowed("package.json", "red", testConfig)).toBe(true);
+    });
+  });
+
+  describe("green phase", () => {
+    it("allows green phase files", () => {
+      expect(isAllowed("src/main.ts", "green", testConfig)).toBe(true);
+      expect(isAllowed("lib/helper.ts", "green", testConfig)).toBe(true);
+    });
+
+    it("blocks red phase files", () => {
+      expect(isAllowed("tests/unit/foo.test.ts", "green", testConfig)).toBe(false);
+      expect(isAllowed("specs/api.spec.ts", "green", testConfig)).toBe(false);
+    });
+
+    it("allows free files", () => {
+      expect(isAllowed("README.md", "green", testConfig)).toBe(true);
+    });
+  });
+
+  it("handles nested glob patterns", () => {
+    expect(isAllowed("src/deep/nested/file.ts", "green", testConfig)).toBe(true);
+    expect(isAllowed("tests/deep/nested/test.test.ts", "red", testConfig)).toBe(true);
+  });
+});
+
+describe("disallowedFiles", () => {
+  it("returns empty for refactor phase", () => {
+    expect(disallowedFiles(["src/main.ts", "tests/foo.test.ts"], "refactor", testConfig)).toEqual([]);
+  });
+
+  it("returns empty when input list is empty", () => {
+    expect(disallowedFiles([], "red", testConfig)).toEqual([]);
+    expect(disallowedFiles([], "green", testConfig)).toEqual([]);
+  });
+
+  it("filters out green files in red phase", () => {
+    const files = ["src/main.ts", "README.md", "tests/foo.test.ts"];
+    expect(disallowedFiles(files, "red", testConfig)).toEqual(["src/main.ts"]);
+  });
+
+  it("filters out red files in green phase", () => {
+    const files = ["tests/foo.test.ts", "README.md", "src/main.ts"];
+    expect(disallowedFiles(files, "green", testConfig)).toEqual(["tests/foo.test.ts"]);
+  });
+
+  it("allows free files in both phases", () => {
+    const free = ["README.md", "package.json", "docs/guide.md"];
+    expect(disallowedFiles(free, "red", testConfig)).toEqual([]);
+    expect(disallowedFiles(free, "green", testConfig)).toEqual([]);
+  });
+
+  it("blocks everything when all files match the other phase", () => {
+    const redFiles = ["tests/a.test.ts", "specs/b.spec.ts"];
+    const greenFiles = ["src/c.ts", "lib/d.ts"];
+    expect(disallowedFiles(redFiles, "green", testConfig)).toEqual(redFiles);
+    expect(disallowedFiles(greenFiles, "red", testConfig)).toEqual(greenFiles);
+  });
+});

package/engine/enforce.ts

@@ -0,0 +1,31 @@
+import picomatch from "picomatch";
+import type { Phase, Config } from "./types.js";
+
+/**
+ * Check if a file path is allowed to be modified in the current phase.
+ *
+ * Rules:
+ * - REFACTOR: everything allowed
+ * - RED: files matching allowedRedPhaseFiles + free files (match neither set)
+ * - GREEN: files matching allowedGreenPhaseFiles + free files
+ * - Free files (matching neither glob set) are always allowed in all phases
+ */
+export function isAllowed(filePath: string, phase: Phase, config: Config): boolean {
+  if (phase === "refactor") return true;
+
+  const matchesRed = config.allowedRedPhaseFiles.some((p) => picomatch(p)(filePath));
+  const matchesGreen = config.allowedGreenPhaseFiles.some((p) => picomatch(p)(filePath));
+
+  if (phase === "red") return matchesRed || (!matchesRed && !matchesGreen);
+  if (phase === "green") return matchesGreen || (!matchesRed && !matchesGreen);
+
+  return true;
+}
+
+/**
+ * Filter a list of file paths to those that are disallowed in the current phase.
+ */
+export function disallowedFiles(files: string[], phase: Phase, config: Config): string[] {
+  if (phase === "refactor") return [];
+  return files.filter((f) => !isAllowed(f, phase, config));
+}