tdd-enforcer 0.3.3 → 0.3.5

package/engine/state.test.ts

@@ -1,8 +1,8 @@
 import { mkdirSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-import { describe, expect, it } from "vitest";
-import { loadPhaseState, savePhaseState } from "./state.js";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { loadPhaseState, loadTddState, savePhaseState } from "./state.js";
 
 function withTempDir(fn: (dir: string) => void) {
 	const dir = join(tmpdir(), `tdd-state-test-${Date.now()}`);
@@ -82,3 +82,275 @@ describe("savePhaseState", () => {
 		});
 	});
 });
+
+// ── loadTddState ────────────────────────────────────────────────────────────
+
+const validRules = {
+	blockedInRed: ["tests/**/*.test.ts"],
+	blockedInGreen: ["src/**/*.ts"],
+	testCommands: ["npm test"],
+	timeoutSeconds: 30,
+};
+
+const validPhase = {
+	enabled: true,
+	current: "red",
+};
+
+describe("loadTddState", () => {
+	let mockExistsSync: ReturnType<typeof vi.fn>;
+	let mockLoadConfig: ReturnType<typeof vi.fn>;
+	let mockInitGit: ReturnType<typeof vi.fn>;
+	let mockLoadPhaseState: ReturnType<typeof vi.fn>;
+	let mockSavePhaseState: ReturnType<typeof vi.fn>;
+	let mockHeadMessage: ReturnType<typeof vi.fn>;
+	let mockNextPhase: ReturnType<typeof vi.fn>;
+	let mockStageFiles: ReturnType<typeof vi.fn>;
+
+	const realNextPhase = (p: string) =>
+		p === "red"
+			? "green"
+			: p === "green"
+				? "refactor"
+				: p === "refactor"
+					? "red"
+					: null;
+
+	function makeDeps(overrides = {}) {
+		return {
+			existsSync: mockExistsSync,
+			loadConfig: mockLoadConfig,
+			initGit: mockInitGit,
+			loadPhaseState: mockLoadPhaseState,
+			savePhaseState: mockSavePhaseState,
+			headMessage: mockHeadMessage,
+			nextPhase: mockNextPhase,
+			stageFiles: mockStageFiles,
+			...overrides,
+		};
+	}
+
+	beforeEach(() => {
+		vi.clearAllMocks();
+		mockExistsSync = vi.fn().mockImplementation((path: string) => {
+			if (path.includes(".git")) return false;
+			if (path.includes(".pi/tdd")) return true;
+			return true;
+		});
+		mockLoadConfig = vi.fn().mockReturnValue(validRules);
+		mockInitGit = vi.fn();
+		mockLoadPhaseState = vi.fn().mockReturnValue(validPhase);
+		mockSavePhaseState = vi.fn();
+		mockHeadMessage = vi.fn().mockReturnValue("tdd: red");
+		mockNextPhase = vi.fn().mockImplementation(realNextPhase);
+		mockStageFiles = vi.fn();
+	});
+
+	it("returns missing dir error when .pi/tdd does not exist", () => {
+		mockExistsSync.mockReturnValue(false);
+		const result = loadTddState("/test", makeDeps());
+		expect(result.ok).toBe(false);
+		expect(result.reason).toContain("Missing .pi/tdd/");
+	});
+
+	it("returns missing rules.json error when only dir exists", () => {
+		mockExistsSync.mockImplementation((path: string) => {
+			if (path.includes("rules.json")) return false;
+			if (path.includes(".pi/tdd")) return true;
+			return false;
+		});
+		const result = loadTddState("/test", makeDeps());
+		expect(result.ok).toBe(false);
+		expect(result.reason).toContain("rules.json");
+	});
+
+	it("auto-creates state.json when missing (default RED disabled)", () => {
+		mockExistsSync.mockImplementation((path: string) => {
+			if (path.includes("state.json")) return false;
+			if (path.includes(".git")) return false;
+			return true;
+		});
+		mockHeadMessage.mockReturnValue("tdd: init");
+		const result = loadTddState("/test", makeDeps());
+		expect(result.ok).toBe(true);
+		if (result.ok) {
+			expect(result.state.enabled).toBe(false);
+			expect(result.state.current).toBe("red");
+		}
+		expect(mockInitGit).toHaveBeenCalled();
+		expect(mockSavePhaseState).toHaveBeenCalledWith("/test", {
+			enabled: false,
+			current: "red",
+		});
+	});
+
+	it("auto-creates state.json when corrupted (recovers to default)", () => {
+		mockExistsSync.mockImplementation((path: string) => {
+			if (path.includes("state.json")) return true;
+			if (path.includes(".git")) return false;
+			return true;
+		});
+		mockLoadPhaseState.mockImplementation(() => {
+			throw new Error("corrupt");
+		});
+		mockHeadMessage.mockReturnValue("tdd: init");
+		const result = loadTddState("/test", makeDeps());
+		expect(result.ok).toBe(true);
+		if (result.ok) {
+			expect(result.state.enabled).toBe(false);
+			expect(result.state.current).toBe("red");
+		}
+	});
+
+	it("returns invalid rules.json error for malformed JSON", () => {
+		mockLoadConfig.mockImplementation(() => {
+			throw new Error("Unexpected token");
+		});
+		const result = loadTddState("/test", makeDeps());
+		expect(result.ok).toBe(false);
+		expect(result.reason).toContain("Invalid .pi/tdd/rules.json");
+	});
+
+	it("returns ok when state.json has enabled: false (callers check enabled)", () => {
+		mockLoadPhaseState.mockReturnValue({ enabled: false, current: "red" });
+		const result = loadTddState("/test", makeDeps());
+		expect(result.ok).toBe(true);
+		if (result.ok) {
+			expect(result.state.enabled).toBe(false);
+			expect(result.state.current).toBe("red");
+		}
+	});
+
+	it("returns ok with state and config when everything valid", () => {
+		mockLoadPhaseState.mockReturnValue(validPhase);
+		const result = loadTddState("/test", makeDeps());
+		expect(result.ok).toBe(true);
+		if (result.ok) {
+			expect(result.state.current).toBe("red");
+			expect(result.state.enabled).toBe(true);
+			expect(result.config.testCommands).toEqual(["npm test"]);
+			expect(result.config.blockedInRed).toEqual(["tests/**/*.test.ts"]);
+		}
+	});
+
+	it("auto-creates git repo when missing", () => {
+		let gitExists = false;
+		mockExistsSync.mockImplementation((path: string) => {
+			if (path.includes(".git")) return gitExists;
+			if (path.includes(".pi/tdd")) return true;
+			return true;
+		});
+		mockInitGit.mockImplementation(() => {
+			gitExists = true;
+		});
+		const result = loadTddState("/test", makeDeps());
+		expect(result.ok).toBe(true);
+		expect(mockInitGit).toHaveBeenCalled();
+	});
+
+	it("handles multiple calls without error", () => {
+		const r1 = loadTddState("/test", makeDeps());
+		expect(r1.ok).toBe(true);
+		const r2 = loadTddState("/test", makeDeps());
+		expect(r2.ok).toBe(true);
+		expect(mockLoadConfig).toHaveBeenCalledTimes(2);
+	});
+
+	it("recovers from invalid current phase in state.json (auto-creates default)", () => {
+		mockLoadPhaseState.mockImplementation(() => {
+			throw new Error("invalid phase");
+		});
+		mockHeadMessage.mockReturnValue("tdd: init");
+		const result = loadTddState("/test", makeDeps());
+		expect(result.ok).toBe(true);
+		if (result.ok) {
+			expect(result.state.enabled).toBe(false);
+			expect(result.state.current).toBe("red");
+		}
+	});
+
+	it("recoverState: HEAD tdd:red → enabled green", () => {
+		mockExistsSync.mockImplementation((path: string) => {
+			if (path.includes("state.json")) return false;
+			return true;
+		});
+		mockHeadMessage.mockReturnValue("tdd: red");
+		mockNextPhase.mockImplementation(realNextPhase);
+		const result = loadTddState("/test", makeDeps());
+		expect(result.ok).toBe(true);
+		if (result.ok) {
+			expect(result.state.enabled).toBe(true);
+			expect(result.state.current).toBe("green");
+		}
+	});
+
+	it("recoverState: HEAD tdd:green → enabled refactor", () => {
+		mockExistsSync.mockImplementation((path: string) => {
+			if (path.includes("state.json")) return false;
+			return true;
+		});
+		mockHeadMessage.mockReturnValue("tdd: green");
+		const result = loadTddState("/test", makeDeps());
+		expect(result.ok).toBe(true);
+		if (result.ok) {
+			expect(result.state.enabled).toBe(true);
+			expect(result.state.current).toBe("refactor");
+		}
+	});
+
+	it("recoverState: HEAD tdd:refactor → enabled red", () => {
+		mockExistsSync.mockImplementation((path: string) => {
+			if (path.includes("state.json")) return false;
+			return true;
+		});
+		mockHeadMessage.mockReturnValue("tdd: refactor");
+		const result = loadTddState("/test", makeDeps());
+		expect(result.ok).toBe(true);
+		if (result.ok) {
+			expect(result.state.enabled).toBe(true);
+			expect(result.state.current).toBe("red");
+		}
+	});
+
+	it("force-adds state.json after creating it from recovery", () => {
+		mockExistsSync.mockImplementation((path: string) => {
+			if (path.includes("state.json")) return false;
+			if (path.includes(".git")) return false;
+			return true;
+		});
+		mockHeadMessage.mockReturnValue("tdd: init");
+		const result = loadTddState("/test", makeDeps());
+		expect(result.ok).toBe(true);
+		expect(mockStageFiles).toHaveBeenCalledWith("/test", [
+			".pi/tdd/state.json",
+		]);
+	});
+
+	it("does not force-add state.json when it already exists and is valid", () => {
+		mockExistsSync.mockImplementation((path: string) => {
+			if (path.includes("state.json")) return true;
+			if (path.includes(".git")) return true;
+			return true;
+		});
+		const result = loadTddState("/test", makeDeps());
+		expect(result.ok).toBe(true);
+		expect(mockStageFiles).not.toHaveBeenCalled();
+	});
+
+	it("force-adds state.json after recovering from corrupted state", () => {
+		mockExistsSync.mockImplementation((path: string) => {
+			if (path.includes("state.json")) return true;
+			if (path.includes(".git")) return true;
+			return true;
+		});
+		mockLoadPhaseState.mockImplementation(() => {
+			throw new Error("corrupt");
+		});
+		mockHeadMessage.mockReturnValue("tdd: init");
+		const result = loadTddState("/test", makeDeps());
+		expect(result.ok).toBe(true);
+		expect(mockStageFiles).toHaveBeenCalledWith("/test", [
+			".pi/tdd/state.json",
+		]);
+	});
+});

package/engine/state.ts

@@ -1,10 +1,17 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
-import type { PhaseState } from "./types.js";
+import { loadConfig } from "./config.js";
+import { headMessage, initGit, stageFiles } from "./git.js";
+import { nextPhase } from "./transition.js";
+import type { Config, PhaseState } from "./types.js";
 
 const TDD_DIR = ".pi/tdd";
 const VALID_PHASES = new Set(["red", "green", "refactor"]);
 
+export type TddLoadResult =
+	| { ok: true; state: PhaseState; config: Config }
+	| { ok: false; reason: string };
+
 export function phaseStatePath(projectRoot: string): string {
 	return join(projectRoot, TDD_DIR, "state.json");
 }
@@ -38,3 +45,130 @@ export function savePhaseState(projectRoot: string, state: PhaseState): void {
 	ensureDir(path);
 	writeFileSync(path, JSON.stringify(state, null, 2), "utf-8");
 }
+
+/**
+ * Recover state.json from private git HEAD, or create default.
+ * Returns the state (does not save to disk — caller does that).
+ */
+function recoverState(
+	root: string,
+	tddDir: string,
+	deps: {
+		existsSync: typeof existsSync;
+		headMessage: typeof headMessage;
+		nextPhase: typeof nextPhase;
+	} = { existsSync, headMessage, nextPhase },
+): PhaseState {
+	const gitDir = join(tddDir, ".git");
+	if (deps.existsSync(gitDir)) {
+		try {
+			const msg = deps.headMessage(root);
+			const m = msg.match(/^tdd: (red|green|refactor|init)$/);
+			if (m) {
+				const label = m[1];
+				if (label === "init") {
+					return { enabled: false, current: "red" };
+				}
+				const next = deps.nextPhase(label);
+				return { enabled: true, current: next ?? "red" };
+			}
+		} catch {
+			// No commits or bad HEAD — fall through to default
+		}
+	}
+	return { enabled: false, current: "red" };
+}
+
+/**
+ * Load TDD state + config in one go.
+ * Auto-creates state.json from private git HEAD when missing or corrupted.
+ * Returns ok:true with state and config when rules.json is valid.
+ * Returns ok:false with a specific reason string otherwise.
+ *
+ * Callers must check state.enabled themselves if they need active enforcement.
+ */
+export function loadTddState(
+	root: string,
+	deps: {
+		existsSync: typeof existsSync;
+		loadConfig: typeof loadConfig;
+		initGit: typeof initGit;
+		loadPhaseState: typeof loadPhaseState;
+		savePhaseState: typeof savePhaseState;
+		headMessage: typeof headMessage;
+		nextPhase: typeof nextPhase;
+		stageFiles: typeof stageFiles;
+	} = {
+		existsSync,
+		loadConfig,
+		initGit,
+		loadPhaseState,
+		savePhaseState,
+		headMessage,
+		nextPhase,
+		stageFiles,
+	},
+): TddLoadResult {
+	const tddDir = join(root, ".pi", "tdd");
+	if (!deps.existsSync(tddDir)) {
+		return {
+			ok: false,
+			reason:
+				"Missing .pi/tdd/ directory. See the tdd-enforcer skill to learn how to set up TDD configs.",
+		};
+	}
+
+	const rulesPath = join(tddDir, "rules.json");
+	if (!deps.existsSync(rulesPath)) {
+		return {
+			ok: false,
+			reason:
+				"Missing .pi/tdd/rules.json. See the tdd-enforcer skill to learn how to set up TDD configs.",
+		};
+	}
+
+	let config: Config;
+	try {
+		config = deps.loadConfig(root);
+	} catch (e) {
+		return {
+			ok: false,
+			reason: `Invalid .pi/tdd/rules.json: ${(e as Error).message}. See the tdd-enforcer skill.`,
+		};
+	}
+
+	// Init git if missing — required for state recovery and all consumers
+	const gitDir = join(tddDir, ".git");
+	if (!deps.existsSync(gitDir)) {
+		try {
+			deps.initGit(root);
+		} catch (e) {
+			return {
+				ok: false,
+				reason: `Failed to initialise private git repo: ${(e as Error).message}`,
+			};
+		}
+	}
+
+	// Auto-create state.json if missing or corrupted
+	const phasePath = join(tddDir, "state.json");
+	let state: PhaseState | undefined;
+	if (deps.existsSync(phasePath)) {
+		try {
+			state = deps.loadPhaseState(root);
+		} catch {
+			// Corrupted — recover below
+		}
+	}
+	if (!state) {
+		state = recoverState(root, tddDir, {
+			existsSync: deps.existsSync,
+			headMessage: deps.headMessage,
+			nextPhase: deps.nextPhase,
+		});
+		deps.savePhaseState(root, state);
+		deps.stageFiles(root, [".pi/tdd/state.json"]);
+	}
+
+	return { ok: true, state, config };
+}

package/engine/transition.test.ts

@@ -25,10 +25,15 @@ describe("nextPhase", () => {
 
 // ── Pure unit tests: checkGate ──────────────────────────────────────────────
 
-function makeRunner(passed: boolean): TestRunner {
+function makeRunner(passed: boolean, timeout?: boolean): TestRunner {
 	return async (_cmds, _timeout) => ({
 		passed,
-		message: passed ? "all ok" : "tests failed",
+		timeout,
+		message: timeout
+			? "npm test: timed out"
+			: passed
+				? "all ok"
+				: "tests failed",
 	});
 }
 
@@ -52,6 +57,19 @@ describe("checkGate", () => {
 			expect(r.passed).toBe(false);
 			expect(r.message).toMatch(/transitioning to GREEN/i);
 		});
+
+		it("blocks on timeout — does not treat as test failure", async () => {
+			const r = await checkGate(
+				"red",
+				"green",
+				makeRunner(false, true),
+				testConfig,
+			);
+			expect(r.passed).toBe(false);
+			expect(r.timeout).toBe(true);
+			expect(r.message).toMatch(/timed out/i);
+			expect(r.message).not.toMatch(/proceed|fail/i);
+		});
 	});
 
 	describe("green → refactor (tests must pass)", () => {
@@ -76,6 +94,19 @@ describe("checkGate", () => {
 			expect(r.passed).toBe(false);
 			expect(r.message).toMatch(/transitioning to REFACTOR/i);
 		});
+
+		it("blocks on timeout with timeout message", async () => {
+			const r = await checkGate(
+				"green",
+				"refactor",
+				makeRunner(false, true),
+				testConfig,
+			);
+			expect(r.passed).toBe(false);
+			expect(r.timeout).toBe(true);
+			expect(r.message).toMatch(/timed out/i);
+			expect(r.message).not.toMatch(/fix them/i);
+		});
 	});
 
 	describe("refactor → red (tests must pass)", () => {
@@ -100,6 +131,19 @@ describe("checkGate", () => {
 			expect(r.passed).toBe(false);
 			expect(r.message).toMatch(/transitioning to RED/i);
 		});
+
+		it("blocks on timeout with timeout message", async () => {
+			const r = await checkGate(
+				"refactor",
+				"red",
+				makeRunner(false, true),
+				testConfig,
+			);
+			expect(r.passed).toBe(false);
+			expect(r.timeout).toBe(true);
+			expect(r.message).toMatch(/timed out/i);
+			expect(r.message).not.toMatch(/fix them/i);
+		});
 	});
 
 	it("passes test commands to the runner", async () => {

package/engine/transition.ts

@@ -13,6 +13,7 @@ export function nextPhase(current: Phase): Phase | null {
 export interface GateResult {
 	passed: boolean;
 	message: string;
+	timeout?: boolean;
 }
 
 export type TestRunner = (
@@ -34,6 +35,15 @@ export async function checkGate(
 ): Promise<GateResult> {
 	const result = await testRunner(config.testCommands, config.timeoutSeconds);
 
+	// Timeout blocks all transitions — don't suggest "fix tests"
+	if (result.timeout) {
+		return {
+			passed: false,
+			timeout: true,
+			message: `Tests timed out after ${config.timeoutSeconds}s. The test command may have hung or an operation may be blocking.`,
+		};
+	}
+
 	switch (`${from}→${to}` as Transition) {
 		case "red→green":
 			if (result.passed) {

package/package.json

@@ -1,8 +1,20 @@
 {
 	"name": "tdd-enforcer",
-	"version": "0.3.3",
+	"version": "0.3.5",
 	"type": "module",
+	"description": "TDD enforcer extension for the pi coding agent — enforces Red-Green-Refactor phases with file access restrictions and transition gates",
+	"license": "MIT",
+	"author": "Cyclone1070 <hoangmai1070@gmail.com>",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/Cyclone1070/tdd-enforcer.git"
+	},
+	"bugs": {
+		"url": "https://github.com/Cyclone1070/tdd-enforcer/issues"
+	},
+	"homepage": "https://github.com/Cyclone1070/tdd-enforcer#readme",
 	"scripts": {
+		"check": "biome check --write . && vitest run",
 		"lint": "biome check .",
 		"lint:fix": "biome check --write .",
 		"test": "vitest run"