tdd-enforcer 0.2.1 → 0.2.3

package/engine/git.ts

@@ -4,6 +4,24 @@ import { join } from "node:path";
 
 const TDD_DIR = ".pi/tdd";
 
+export type GitDeps = {
+  execSync: (command: string, options?: ExecSyncOptions) => Buffer;
+  existsSync: (path: string) => boolean;
+  mkdirSync: (path: string, options?: { recursive?: boolean }) => void;
+  writeFileSync: (path: string, data: string, encoding: BufferEncoding) => void;
+  unlinkSync: (path: string) => void;
+  rmSync: (path: string, options?: { recursive?: boolean; force?: boolean }) => void;
+};
+
+const defaultDeps: GitDeps = {
+  execSync: execSync as (command: string, options?: ExecSyncOptions) => Buffer,
+  existsSync,
+  mkdirSync,
+  writeFileSync: writeFileSync as (path: string, data: string, encoding: BufferEncoding) => void,
+  unlinkSync,
+  rmSync,
+};
+
 function gitEnv(projectRoot: string): NodeJS.ProcessEnv {
   const gitDir = join(projectRoot, TDD_DIR, ".git");
   return {
@@ -12,116 +30,129 @@ function gitEnv(projectRoot: string): NodeJS.ProcessEnv {
   };
 }
 
-function gitExec(args: string, projectRoot: string, options?: ExecSyncOptions): string {
+function gitExec(args: string, projectRoot: string, deps: GitDeps, options?: ExecSyncOptions): string {
   const env = { ...process.env, ...gitEnv(projectRoot) };
-  return execSync(`git ${args}`, { ...options, env, encoding: "utf-8" } as ExecSyncOptions).toString();
+  return deps.execSync(`git ${args}`, { ...options, env, encoding: "utf-8" } as ExecSyncOptions).toString();
 }
 
-export function initGit(projectRoot: string): void {
+export function initGit(projectRoot: string, deps: GitDeps = defaultDeps): void {
   const tddPath = join(projectRoot, TDD_DIR);
   const gitDir = join(tddPath, ".git");
-  if (existsSync(gitDir)) return;
+  if (deps.existsSync(gitDir)) return;
 
-  mkdirSync(tddPath, { recursive: true });
-  gitExec(`init "${tddPath}"`, projectRoot, { stdio: "pipe" as const });
-  gitExec(`config core.worktree "${projectRoot}"`, projectRoot, { stdio: "pipe" as const });
-  gitExec(`config core.excludesFile "${join(tddPath, ".gitignore")}"`, projectRoot, { stdio: "pipe" as const });
+  deps.mkdirSync(tddPath, { recursive: true });
+  gitExec(`init "${tddPath}"`, projectRoot, deps, { stdio: "pipe" as const });
+  gitExec(`config core.worktree "${projectRoot}"`, projectRoot, deps, { stdio: "pipe" as const });
+  gitExec(`config core.excludesFile "${join(tddPath, ".gitignore")}"`, projectRoot, deps, { stdio: "pipe" as const });
 
   const gitignorePath = join(tddPath, ".gitignore");
-  if (!existsSync(gitignorePath)) {
-    writeFileSync(
+  if (!deps.existsSync(gitignorePath)) {
+    deps.writeFileSync(
       gitignorePath,
       ["node_modules/", ".pnpm-store/", ".next/", "dist/", "build/", ".cache/", "*.log", ".DS_Store", "Thumbs.db", ""].join("\n"),
       "utf-8",
     );
   }
 
-  gitExec("add -A", projectRoot, { stdio: "pipe" as const });
-  gitExec('commit --allow-empty -m "tdd: init"', projectRoot, { stdio: "pipe" as const });
+  gitExec("add -A", projectRoot, deps, { stdio: "pipe" as const });
+  stageFiles(projectRoot, [".pi/tdd/state.json", ".pi/tdd/rules.json", ".pi/tdd/.gitignore"], deps);
+  gitExec('commit --allow-empty -m "tdd: init"', projectRoot, deps, { stdio: "pipe" as const });
 }
 
 /** Destroy the private git repo and re-init from scratch. */
-export function resetGit(projectRoot: string): void {
+export function resetGit(projectRoot: string, deps: GitDeps = defaultDeps): void {
   const tddPath = join(projectRoot, TDD_DIR);
   const gitDir = join(tddPath, ".git");
-  if (existsSync(gitDir)) {
-    rmSync(gitDir, { recursive: true, force: true });
+  if (deps.existsSync(gitDir)) {
+    deps.rmSync(gitDir, { recursive: true, force: true });
   }
-  initGit(projectRoot);
+  initGit(projectRoot, deps);
 }
 
 /** Stage all + commit with --allow-empty so every phase transition has a labeled commit. */
-export function snapshot(projectRoot: string, phase: string): string {
-  gitExec("add -A", projectRoot, { stdio: "pipe" as const });
-  gitExec(`commit --allow-empty -m "tdd: ${phase}"`, projectRoot, { stdio: "pipe" as const });
-  return gitExec("rev-parse HEAD", projectRoot).trim();
+export function snapshot(projectRoot: string, phase: string, deps: GitDeps = defaultDeps): string {
+  gitExec("add -A", projectRoot, deps, { stdio: "pipe" as const });
+  stageFiles(projectRoot, [".pi/tdd/state.json", ".pi/tdd/rules.json", ".pi/tdd/.gitignore"], deps);
+  gitExec(`commit --allow-empty -m "tdd: ${phase}"`, projectRoot, deps, { stdio: "pipe" as const });
+  return gitExec("rev-parse HEAD", projectRoot, deps).trim();
 }
 
-export function modifiedFiles(projectRoot: string): string[] {
-  const out = gitExec("diff --name-only HEAD", projectRoot).trim();
+export function modifiedFiles(projectRoot: string, deps: GitDeps = defaultDeps): string[] {
+  const out = gitExec("diff --name-only HEAD", projectRoot, deps).trim();
   return out ? out.split("\n") : [];
 }
 
-export function untrackedFiles(projectRoot: string): string[] {
-  const out = gitExec("ls-files --others --exclude-standard", projectRoot).trim();
+export function untrackedFiles(projectRoot: string, deps: GitDeps = defaultDeps): string[] {
+  const out = gitExec("ls-files --others --exclude-standard", projectRoot, deps).trim();
   return out ? out.split("\n") : [];
 }
 
-export function changesSinceSnapshot(projectRoot: string): string[] {
-  return [...new Set([...modifiedFiles(projectRoot), ...untrackedFiles(projectRoot)])];
+export function changesSinceSnapshot(projectRoot: string, deps: GitDeps = defaultDeps): string[] {
+  return [...new Set([...modifiedFiles(projectRoot, deps), ...untrackedFiles(projectRoot, deps)])];
 }
 
-export function restoreFilesTo(projectRoot: string, files: string[], source?: string): void {
+export function restoreFilesTo(projectRoot: string, files: string[], source?: string, deps: GitDeps = defaultDeps): void {
   if (files.length === 0) return;
 
   // Separate tracked (git restore) from untracked (delete)
-  const tracked = gitExec("ls-files", projectRoot)
+  const tracked = gitExec("ls-files", projectRoot, deps)
     .trim()
     .split("\n")
     .filter(Boolean);
   const trackedSet = new Set(tracked);
 
   const trackedFiles = files.filter((f) => trackedSet.has(f));
-  const untrackedFiles = files.filter((f) => !trackedSet.has(f));
+  const untrackedFilesList = files.filter((f) => !trackedSet.has(f));
 
   if (trackedFiles.length > 0) {
     const escaped = trackedFiles.map((f) => `"${f}"`).join(" ");
     const sourceFlag = source ? `--source=${source} ` : "";
-    gitExec(`restore ${sourceFlag}--worktree -- ${escaped}`, projectRoot, { stdio: "pipe" as const });
+    gitExec(`restore ${sourceFlag}--worktree -- ${escaped}`, projectRoot, deps, { stdio: "pipe" as const });
   }
 
-  for (const f of untrackedFiles) {
+  for (const f of untrackedFilesList) {
     try {
-      unlinkSync(f);
+      deps.unlinkSync(f);
     } catch {
       // File may already be gone, ignore
     }
   }
 }
 
+/**
+ * Force-stage files in the private git repo, bypassing worktree .gitignore.
+ * Does not commit — call snapshot() or commit separately to persist.
+ */
+export function stageFiles(projectRoot: string, files: string[], deps: GitDeps = defaultDeps): void {
+  const existing = files.filter((f) => deps.existsSync(join(projectRoot, f)));
+  if (existing.length === 0) return;
+  const escaped = existing.map((f) => `"${f}"`).join(" ");
+  gitExec(`add -f ${escaped}`, projectRoot, deps, { stdio: "pipe" as const });
+}
+
 /**
  * Create a lightweight commit of the current working tree without touching the stash ref.
  * Returns the commit hash. Used as a pre-bash baseline for per-command diff.
  */
-export function gitStashCreate(projectRoot: string): string {
-  const hash = gitExec("stash create --include-untracked", projectRoot).trim();
-  if (!hash) throw new Error("git stash create returned empty hash");
+export function gitStashCreate(projectRoot: string, deps: GitDeps = defaultDeps): string {
+  const hash = gitExec("stash create --include-untracked", projectRoot, deps).trim();
+  if (!hash) return "HEAD";
   return hash;
 }
 
-export function headHash(projectRoot: string): string {
-  return gitExec("rev-parse HEAD", projectRoot).trim();
+export function headHash(projectRoot: string, deps: GitDeps = defaultDeps): string {
+  return gitExec("rev-parse HEAD", projectRoot, deps).trim();
 }
 
 /** Get the commit message of HEAD. */
-export function headMessage(projectRoot: string): string {
-  return gitExec("log -1 --format=%s HEAD", projectRoot).trim();
+export function headMessage(projectRoot: string, deps: GitDeps = defaultDeps): string {
+  return gitExec("log -1 --format=%s HEAD", projectRoot, deps).trim();
 }
 
 /** Check if HEAD has a parent commit (i.e. can go back one). */
-export function hasParent(projectRoot: string): boolean {
+export function hasParent(projectRoot: string, deps: GitDeps = defaultDeps): boolean {
   try {
-    gitExec("rev-parse HEAD~1", projectRoot);
+    gitExec("rev-parse HEAD~1", projectRoot, deps);
     return true;
   } catch {
     return false;
@@ -131,21 +162,21 @@ export function hasParent(projectRoot: string): boolean {
 /**
  * Get files changed since a specific commit (instead of HEAD).
  */
-export function changesSince(projectRoot: string, commitHash: string): string[] {
-  const out = gitExec(`diff --name-only ${commitHash} -- .`, projectRoot).trim();
+export function changesSince(projectRoot: string, commitHash: string, deps: GitDeps = defaultDeps): string[] {
+  const out = gitExec(`diff --name-only ${commitHash} -- .`, projectRoot, deps).trim();
   const files = out ? out.split("\n") : [];
   // Also include untracked files
-  const untracked = untrackedFiles(projectRoot);
+  const untracked = untrackedFiles(projectRoot, deps);
   return [...new Set([...files, ...untracked])];
 }
 
 /** Hard reset — discard all uncommitted changes (tracked and untracked), keep HEAD. */
-export function resetHard(projectRoot: string): void {
-  gitExec("reset --hard", projectRoot, { stdio: "pipe" as const });
-  gitExec("clean -fd", projectRoot, { stdio: "pipe" as const });
+export function resetHard(projectRoot: string, deps: GitDeps = defaultDeps): void {
+  gitExec("reset --hard", projectRoot, deps, { stdio: "pipe" as const });
+  gitExec("clean -fd", projectRoot, deps, { stdio: "pipe" as const });
 }
 
 /** Soft reset — remove last commit, keep working tree content as unstaged. */
-export function undoLastCommit(projectRoot: string): void {
-  gitExec("reset --soft HEAD~1", projectRoot, { stdio: "pipe" as const });
+export function undoLastCommit(projectRoot: string, deps: GitDeps = defaultDeps): void {
+  gitExec("reset --soft HEAD~1", projectRoot, deps, { stdio: "pipe" as const });
 }

package/engine/index.ts

@@ -1,5 +1,5 @@
 export { isAllowed, disallowedFiles } from "./enforce.js";
-export { initGit, resetGit, snapshot, changesSinceSnapshot, changesSince, modifiedFiles, untrackedFiles, restoreFilesTo, gitStashCreate, headHash, headMessage, hasParent, resetHard, undoLastCommit } from "./git.js";
+export { initGit, resetGit, snapshot, changesSinceSnapshot, changesSince, modifiedFiles, untrackedFiles, restoreFilesTo, gitStashCreate, stageFiles, headHash, headMessage, hasParent, resetHard, undoLastCommit } from "./git.js";
 export { loadConfig } from "./config.js";
 export { loadPhaseState, savePhaseState } from "./state.js";
 export { nextPhase, checkGate, getDisallowedChanges } from "./transition.js";

package/engine/transition.test.ts

@@ -1,10 +1,7 @@
-import { describe, it, expect } from "vitest";
-import { mkdirSync, writeFileSync, rmSync, existsSync } from "node:fs";
-import { join } from "node:path";
-import { tmpdir } from "node:os";
-import { nextPhase, checkGate, getDisallowedChanges } from "./transition.js";
+import { describe, it, expect, beforeEach, vi } from "vitest";
+import { getDisallowedChanges, nextPhase, checkGate } from "./transition.js";
 import type { Config, TestRunner } from "./types.js";
-import { initGit, snapshot } from "./git.js";
+import picomatch from "picomatch";
 
 // ── Pure unit tests: nextPhase ──────────────────────────────────────────────
 
@@ -124,17 +121,7 @@ describe("checkGate", () => {
   });
 });
 
-// ── Integration tests: getDisallowedChanges ──────────────────────────────────
-
-function withTempDir(fn: (dir: string) => void) {
-  const dir = join(tmpdir(), `tdd-transition-test-${Date.now()}`);
-  mkdirSync(dir, { recursive: true });
-  try {
-    fn(dir);
-  } finally {
-    rmSync(dir, { recursive: true, force: true });
-  }
-}
+// ── Pure unit tests: getDisallowedChanges ────────────────────────────────────
 
 const denyConfig: Config = {
   allowedRedPhaseFiles: ["tests/**/*.test.ts"],
@@ -144,61 +131,79 @@ const denyConfig: Config = {
 };
 
 describe("getDisallowedChanges", () => {
+  let mockChangesSinceSnapshot: ReturnType<typeof vi.fn>;
+  let mockDisallowedFiles: ReturnType<typeof vi.fn>;
+
+  function makeDeps(overrides = {}) {
+    return {
+      changesSinceSnapshot: mockChangesSinceSnapshot,
+      disallowedFiles: mockDisallowedFiles,
+      ...overrides,
+    };
+  }
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mockChangesSinceSnapshot = vi.fn().mockReturnValue([]);
+    mockDisallowedFiles = vi.fn().mockReturnValue([]);
+  });
+
   it("returns empty for refactor phase regardless of git state", () => {
-    withTempDir((dir) => {
-      // No git at all — safe because refactor returns early
-      expect(getDisallowedChanges(dir, "refactor", denyConfig)).toEqual([]);
-    });
+    const result = getDisallowedChanges("/any", "refactor", denyConfig, makeDeps());
+    expect(result).toEqual([]);
+    expect(mockChangesSinceSnapshot).not.toHaveBeenCalled();
   });
 
   it("returns empty when no files changed", () => {
-    withTempDir((dir) => {
-      initGit(dir);
-      snapshot(dir, "red");
-      expect(getDisallowedChanges(dir, "red", denyConfig)).toEqual([]);
-    });
+    mockChangesSinceSnapshot.mockReturnValue([]);
+    const result = getDisallowedChanges("/test", "red", denyConfig, makeDeps());
+    expect(result).toEqual([]);
+    expect(mockChangesSinceSnapshot).toHaveBeenCalledWith("/test");
   });
 
   it("returns disallowed files in red phase", () => {
-    withTempDir((dir) => {
-      initGit(dir);
-      snapshot(dir, "red");
-      mkdirSync(join(dir, "src"), { recursive: true });
-      mkdirSync(join(dir, "tests"), { recursive: true });
-      writeFileSync(join(dir, "src", "main.ts"), "// impl", "utf-8");
-      writeFileSync(join(dir, "tests", "foo.test.ts"), "// test", "utf-8");
-      writeFileSync(join(dir, "README.md"), "// docs", "utf-8");
-      const violations = getDisallowedChanges(dir, "red", denyConfig);
-      expect(violations).toContain("src/main.ts");
-      expect(violations).not.toContain("tests/foo.test.ts");
-      expect(violations).not.toContain("README.md");
+    mockChangesSinceSnapshot.mockReturnValue(["src/main.ts", "tests/foo.test.ts", "README.md"]);
+    const matchesRed = picomatch(denyConfig.allowedRedPhaseFiles);
+    const matchesGreen = picomatch(denyConfig.allowedGreenPhaseFiles);
+    mockDisallowedFiles.mockImplementation((changed: string[], phase: string) => {
+      if (phase === "red") {
+        return changed.filter((f: string) => !matchesRed(f) && matchesGreen(f));
+      }
+      return [];
     });
+    const violations = getDisallowedChanges("/test", "red", denyConfig, makeDeps());
+    expect(violations).toContain("src/main.ts");
+    expect(violations).not.toContain("tests/foo.test.ts");
+    expect(violations).not.toContain("README.md");
   });
 
   it("returns disallowed files in green phase", () => {
-    withTempDir((dir) => {
-      initGit(dir);
-      snapshot(dir, "green");
-      mkdirSync(join(dir, "tests"), { recursive: true });
-      mkdirSync(join(dir, "src"), { recursive: true });
-      writeFileSync(join(dir, "tests", "foo.test.ts"), "// test", "utf-8");
-      writeFileSync(join(dir, "src", "main.ts"), "// impl", "utf-8");
-      writeFileSync(join(dir, "package.json"), "{}", "utf-8");
-      const violations = getDisallowedChanges(dir, "green", denyConfig);
-      expect(violations).toContain("tests/foo.test.ts");
-      expect(violations).not.toContain("src/main.ts");
-      expect(violations).not.toContain("package.json");
+    mockChangesSinceSnapshot.mockReturnValue(["tests/foo.test.ts", "src/main.ts", "package.json"]);
+    const matchesRed = picomatch(denyConfig.allowedRedPhaseFiles);
+    const matchesGreen = picomatch(denyConfig.allowedGreenPhaseFiles);
+    mockDisallowedFiles.mockImplementation((changed: string[], phase: string) => {
+      if (phase === "green") {
+        return changed.filter((f: string) => matchesRed(f) && !matchesGreen(f));
+      }
+      return [];
     });
+    const violations = getDisallowedChanges("/test", "green", denyConfig, makeDeps());
+    expect(violations).toContain("tests/foo.test.ts");
+    expect(violations).not.toContain("src/main.ts");
+    expect(violations).not.toContain("package.json");
   });
 
   it("catches untracked files, not just modified", () => {
-    withTempDir((dir) => {
-      initGit(dir);
-      snapshot(dir, "red");
-      mkdirSync(join(dir, "src"), { recursive: true });
-      writeFileSync(join(dir, "src", "new.ts"), "// brand new", "utf-8");
-      const violations = getDisallowedChanges(dir, "red", denyConfig);
-      expect(violations).toContain("src/new.ts");
+    mockChangesSinceSnapshot.mockReturnValue(["src/new.ts"]);
+    const matchesRed = picomatch(denyConfig.allowedRedPhaseFiles);
+    const matchesGreen = picomatch(denyConfig.allowedGreenPhaseFiles);
+    mockDisallowedFiles.mockImplementation((changed: string[], phase: string) => {
+      if (phase === "red") {
+        return changed.filter((f: string) => !matchesRed(f) && matchesGreen(f));
+      }
+      return [];
     });
+    const violations = getDisallowedChanges("/test", "red", denyConfig, makeDeps());
+    expect(violations).toContain("src/new.ts");
   });
 });

package/engine/transition.ts

@@ -70,9 +70,16 @@ export function getDisallowedChanges(
   projectRoot: string,
   phase: Phase,
   config: Config,
+  deps: {
+    changesSinceSnapshot: typeof changesSinceSnapshot;
+    disallowedFiles: typeof disallowedFiles;
+  } = {
+    changesSinceSnapshot,
+    disallowedFiles,
+  },
 ): string[] {
   if (phase === "refactor") return [];
 
-  const changed = changesSinceSnapshot(projectRoot);
-  return disallowedFiles(changed, phase, config);
+  const changed = deps.changesSinceSnapshot(projectRoot);
+  return deps.disallowedFiles(changed, phase, config);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tdd-enforcer",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "type": "module",
   "keywords": [
     "pi-package"
@@ -9,6 +9,9 @@
     "picomatch": "^4.0.4"
   },
   "devDependencies": {
+    "@earendil-works/pi-coding-agent": "^0.79.6",
+    "@types/node": "^25.9.3",
+    "typebox": "^1.2.16",
     "vitest": "^3"
   },
   "pi": {

package/skills/tdd-enforcer/SKILL.md

@@ -1,3 +1,8 @@
+---
+name: tdd-enforcer
+description: Use when working within TDD enforcer extension — understand phase rules, file locks, agent tools vs user commands, and when to call next/previous phase or ask the user for help.
+---
+
 # TDD Enforcer Skill
 
 This extension enforces the **Red-Green-Refactor** cycle of TDD.

package/tsconfig.json

@@ -0,0 +1,12 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "strict": true,
+    "types": ["node"],
+    "skipLibCheck": true
+  },
+  "include": ["**/*.ts"],
+  "exclude": ["node_modules"]
+}