@cuzfrog/pi-module-gates 0.15.0 → 0.16.3

package/README.md

@@ -1,6 +1,6 @@
 # pi-module-gates - Constraints liberate, liberties constrain.
 
-Expirimental pi cli extension that controls the entropy of the codebase by enforcing code module boundaries.
+Experimental pi cli extension that controls the entropy of the codebase by enforcing code module boundaries.
 It helps combat slop generation and code architecture degradation.
 
 ## Problem
@@ -134,6 +134,47 @@ Add a `module-gates` entry to `.pi/settings.json`:
 
 When no settings file exists or no `module-gates` key is present, defaults apply.
 
+## Claude Code Support
+
+### Install
+Add the following to `.claude/settings.json` in the current project, pointing the `PreToolUse` hook at the installed binary.
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Edit|MultiEdit|Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bun ${CLAUDE_PROJECT_DIR}/node_modules/@cuzfrog/pi-module-gates/src/claude/pre-tool-use.ts",
+            "statusMessage": "Module gate checking edit..."
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+If `pi-module-gates` is already installed in pi global dir, you can use below path instead:
+```
+~/.pi/agent/npm/node_modules/@cuzfrog/pi-module-gates/src/claude/pre-tool-use.ts
+```
+
+### System prompt
+You need to add [system-prompt.md](src/context/system-prompt.template.md) manually to your context.
+
+### Configuration
+
+Claude Code uses the same `.pi/settings.json#module-gates` block as the pi extension. See the Configuration section above.
+
+### Troubleshooting
+Prompt:
+```
+Check if PreToolUse hook `pi-module-gates` is triggered and runs expectedly.
+```
+
 ## License
 
 MIT

package/bin/pi-module-gates.mjs

@@ -0,0 +1,80 @@
+#!/usr/bin/env bun
+// Bin entrypoint: executed by `bun` (see package.json#bin) and dispatches to
+// src/cli/*.ts modules. Lives in .mjs for npm-install shebang compatibility on
+// platforms that resolve `bin` to a file path directly; `bun` will load this as
+// JavaScript since it has no TypeScript-specific syntax.
+import { resolve, isAbsolute } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const PKG_ROOT = resolve(fileURLToPath(new URL(".", import.meta.url)), "..");
+
+function printUsage() {
+  process.stderr.write(`Usage: pi-module-gates <command> [...args]
+
+Commands:
+  install-claude [--project-dir <dir>]    Install Claude Code PreToolUse hooks into <dir>/.claude/settings.json
+  uninstall-claude [--project-dir <dir>]  Remove Claude Code PreToolUse hooks from <dir>/.claude/settings.json
+
+Environment:
+  CLAUDE_PROJECT_DIR    Default --project-dir when running inside Claude Code.
+
+Examples:
+  pi-module-gates install-claude
+  pi-module-gates install-claude --project-dir /path/to/project
+  pi-module-gates uninstall-claude
+`);
+}
+
+function parseProjectDir(argv) {
+  let projectDir = process.env.CLAUDE_PROJECT_DIR ?? process.cwd();
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i] === "--project-dir" && i + 1 < argv.length) {
+      projectDir = argv[++i];
+    }
+  }
+  return isAbsolute(projectDir) ? projectDir : resolve(process.cwd(), projectDir);
+}
+
+async function main() {
+  const [cmd, ...rest] = process.argv.slice(2);
+  if (!cmd) {
+    printUsage();
+    process.exit(1);
+  }
+  if (cmd === "-h" || cmd === "--help") {
+    printUsage();
+    process.exit(0);
+  }
+
+  const projectDir = parseProjectDir(rest);
+
+  if (cmd === "install-claude") {
+    const mod = await import(resolve(PKG_ROOT, "src/cli/install-claude.ts"));
+    const result = mod.installClaude({ projectDir });
+    if (!result.ok) {
+      process.stderr.write(`${result.reason}\n`);
+      process.exit(1);
+    }
+    process.exit(0);
+  }
+
+  if (cmd === "uninstall-claude") {
+    const mod = await import(resolve(PKG_ROOT, "src/cli/uninstall-claude.ts"));
+    const result = mod.uninstallClaude({ projectDir });
+    if (!result.ok) {
+      process.stderr.write(`${result.reason}\n`);
+      process.exit(1);
+    }
+    process.exit(0);
+  }
+
+  process.stderr.write(`Unknown command: ${cmd}\n`);
+  printUsage();
+  process.exit(2);
+}
+
+main().catch((err) => {
+  const message = err instanceof Error ? err.message : String(err);
+  process.stderr.write(`[pi-module-gates] Unexpected error: ${message}\n`);
+  process.exit(1);
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cuzfrog/pi-module-gates",
-  "version": "0.15.0",
+  "version": "0.16.3",
   "description": "pi extension that controls the entropy of the codebase by enforcing code module boundaries.",
   "keywords": [
     "pi-package"
@@ -10,6 +10,9 @@
     "check": "tsc --noEmit",
     "test": "vitest run"
   },
+  "bin": {
+    "pi-module-gates": "./bin/pi-module-gates.mjs"
+  },
   "pi": {
     "extensions": [
       "./src/index.ts"
@@ -18,12 +21,16 @@
       "./skills"
     ]
   },
+  "dependencies": {
+    "yaml": "2.8.1"
+  },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": "*"
   },
   "devDependencies": {
     "@earendil-works/pi-coding-agent": "0.79.8",
     "@types/node": "22.19.19",
+    "bun-types": "1.3.14",
     "typescript": "5.9.3",
     "vitest": "4.1.7"
   },
@@ -40,11 +47,12 @@
   "files": [
     "src/",
     "skills/",
+    "bin/",
     "README.md",
     "LICENSE"
   ],
   "engines": {
-    "node": ">=18"
+    "bun": ">=1.3.0"
   },
   "publishConfig": {
     "access": "public",

package/src/claude/index-loader.ts

@@ -0,0 +1,40 @@
+import type { ModuleIndex } from "../types.ts";
+import type { ModuleGateConfig } from "../config.ts";
+import { loadConfig } from "../config.ts";
+import { buildModuleIndex } from "../graph/index.ts";
+
+export type IndexContext = {
+  cwd: string;
+  ui: { notify: (msg: string) => void };
+};
+
+export type LoadIndexResult = {
+  index: ModuleIndex;
+  config: ModuleGateConfig;
+};
+
+export async function loadIndexForHook(cwd: string): Promise<LoadIndexResult> {
+  const config = loadConfig(cwd);
+  const ctx: IndexContext = {
+    cwd,
+    ui: {
+      notify: (m) => process.stderr.write(`[Module Gate] ${m}\n`),
+    },
+  };
+
+  try {
+    const index = await buildModuleIndex(ctx, config);
+    return { index, config };
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    process.stderr.write(`[Module Gate] index build failed: ${message}\n`);
+    return {
+      index: { contracts: [], dirToModule: new Map() },
+      config,
+    };
+  }
+}
+
+export function notifyNoContracts(ctx: IndexContext): void {
+  ctx.ui.notify("No module descriptor files found. Gates are not active.");
+}

package/src/claude/pre-tool-use.ts

@@ -0,0 +1,99 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { applyEdits, readFileSafe } from "../utils.ts";
+import { runGates, type GateEdit } from "../gates/run-gates.ts";
+import { loadIndexForHook, notifyNoContracts } from "./index-loader.ts";
+import "../gates/checkers/index.ts";
+
+type HookEvent = {
+  hook_event_name?: string;
+  tool_name?: string;
+  tool_input?: {
+    file_path?: string;
+    old_string?: string;
+    new_string?: string;
+    edits?: { old_string?: string; new_string?: string }[];
+    content?: string;
+  };
+  cwd?: string;
+};
+
+const notifyCtx = (): { cwd: string; ui: { notify: (m: string) => void } } => ({
+  cwd: process.cwd(),
+  ui: {
+    notify: (m) => process.stderr.write(`[Module Gate] ${m}\n`),
+  },
+});
+
+async function main(): Promise<void> {
+  let raw: string;
+  try {
+    raw = fs.readFileSync(0, "utf-8");
+  } catch {
+    process.exit(0);
+  }
+
+  let event: HookEvent;
+  try {
+    event = JSON.parse(raw);
+  } catch {
+    process.stderr.write("[Module Gate] hook: invalid JSON input; allowing tool call.\n");
+    process.exit(0);
+  }
+
+  if (event.hook_event_name !== "PreToolUse") process.exit(0);
+  if (
+    event.tool_name !== "Edit" &&
+    event.tool_name !== "MultiEdit" &&
+    event.tool_name !== "Write"
+  ) {
+    process.exit(0);
+  }
+
+  const cwd: string = event.cwd ?? process.env.CLAUDE_PROJECT_DIR ?? process.cwd();
+  const toolInput = event.tool_input ?? {};
+  const filePath: string | undefined = toolInput.file_path;
+  if (!filePath) process.exit(0);
+
+  const absPath = path.resolve(cwd, filePath);
+  const before = readFileSafe(absPath);
+  let after: string;
+
+  if (event.tool_name === "Edit") {
+    after = applyEdits(before, [
+      { oldText: toolInput.old_string ?? "", newText: toolInput.new_string ?? "" },
+    ]);
+  } else if (event.tool_name === "MultiEdit") {
+    const edits: GateEdit[] = Array.isArray(toolInput.edits)
+      ? toolInput.edits.map((e) => ({
+          oldText: e.old_string ?? "",
+          newText: e.new_string ?? "",
+        }))
+      : [];
+    after = applyEdits(before, edits);
+  } else {
+    after = toolInput.content ?? "";
+  }
+
+  const { index, config } = await loadIndexForHook(cwd);
+
+  if (index.contracts.length === 0) {
+    notifyNoContracts(notifyCtx());
+    process.exit(0);
+  }
+
+  const result = runGates(filePath, [{ oldText: before, newText: after }], cwd, index, config, before);
+
+  if (result?.block) {
+    process.stderr.write(`${result.reason}\n`);
+    process.exit(2);
+  }
+
+  process.exit(0);
+}
+
+main().catch((err) => {
+  const message = err instanceof Error ? err.message : String(err);
+  process.stderr.write(`[Module Gate] hook internal error: ${message}\n`);
+  process.exit(0);
+});

package/src/claude/settings-writer.ts

@@ -0,0 +1,91 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+export const HOOK_MARKER = "@cuzfrog/pi-module-gates";
+export const PRE_TOOL_USE_MATCHER = "Edit|MultiEdit|Write";
+
+export type ClaudeHookCommand = {
+  type: "command";
+  command: string;
+  statusMessage?: string;
+};
+
+export type ClaudeHook = ClaudeHookCommand | {
+  type: string;
+  command?: string;
+  statusMessage?: string;
+  [key: string]: unknown;
+};
+
+export type HookMatcher = {
+  matcher: string;
+  hooks: ClaudeHook[];
+};
+
+export type ClaudeSettings = {
+  hooks?: Record<string, HookMatcher[]>;
+  [key: string]: unknown;
+};
+
+export function readSettings(projectDir: string): ClaudeSettings {
+  const settingsPath = path.join(projectDir, ".claude", "settings.json");
+  try {
+    const raw = fs.readFileSync(settingsPath, "utf-8");
+    const parsed = JSON.parse(raw);
+    if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+      return parsed as ClaudeSettings;
+    }
+    return {};
+  } catch {
+    return {};
+  }
+}
+
+export function buildPreToolUseEntry(): HookMatcher {
+  return {
+    matcher: PRE_TOOL_USE_MATCHER,
+    hooks: [
+      {
+        type: "command",
+        command: `bun \${CLAUDE_PROJECT_DIR}/node_modules/@cuzfrog/pi-module-gates/src/claude/pre-tool-use.ts`,
+        statusMessage: "Module gate checking edit...",
+      },
+    ],
+  };
+}
+
+export function upsertPreToolUse(settings: ClaudeSettings): ClaudeSettings {
+  const next: ClaudeSettings = JSON.parse(JSON.stringify(settings));
+  next.hooks = next.hooks ?? {};
+  const existing = next.hooks.PreToolUse ?? [];
+  next.hooks.PreToolUse = existing.filter(
+    (m) => !m.hooks.some((h) => typeof h.command === "string" && h.command.includes(HOOK_MARKER)),
+  );
+  next.hooks.PreToolUse.push(buildPreToolUseEntry());
+  return next;
+}
+
+export function removePreToolUse(settings: ClaudeSettings): ClaudeSettings {
+  const next: ClaudeSettings = JSON.parse(JSON.stringify(settings));
+  if (!next.hooks?.PreToolUse) return next;
+  const filtered = next.hooks.PreToolUse.filter(
+    (m) => !m.hooks.some((h) => typeof h.command === "string" && h.command.includes(HOOK_MARKER)),
+  );
+  if (filtered.length === 0) {
+    delete next.hooks.PreToolUse;
+    if (Object.keys(next.hooks).length === 0) {
+      delete next.hooks;
+    }
+  } else {
+    next.hooks.PreToolUse = filtered;
+  }
+  return next;
+}
+
+export function writeSettings(projectDir: string, settings: ClaudeSettings): string {
+  const claudeDir = path.join(projectDir, ".claude");
+  fs.mkdirSync(claudeDir, { recursive: true });
+  const target = path.join(claudeDir, "settings.json");
+  fs.writeFileSync(target, JSON.stringify(settings, null, 2) + "\n", "utf-8");
+  return target;
+}

package/src/cli/install-claude.ts

@@ -0,0 +1,54 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import {
+  readSettings,
+  upsertPreToolUse,
+  writeSettings,
+  HOOK_MARKER,
+  PRE_TOOL_USE_MATCHER,
+} from "../claude/settings-writer.ts";
+
+export type InstallClaudeOptions = {
+  projectDir: string;
+};
+
+export type InstallClaudeResult =
+  | { ok: true; written: string }
+  | { ok: false; reason: string };
+
+export function installClaude(opts: InstallClaudeOptions): InstallClaudeResult {
+  const projectDir = path.resolve(opts.projectDir);
+  if (!fs.existsSync(projectDir) || !fs.statSync(projectDir).isDirectory()) {
+    return { ok: false, reason: `Project directory does not exist: ${projectDir}` };
+  }
+
+  const settingsPath = path.join(projectDir, ".pi", "settings.json");
+  if (!fs.existsSync(settingsPath)) {
+    process.stderr.write(
+      `[Module Gate] No .pi/settings.json found at ${settingsPath} — using defaults.\n`,
+    );
+  }
+
+  const settings = readSettings(projectDir);
+  const updated = upsertPreToolUse(settings);
+  const written = writeSettings(projectDir, updated);
+
+  const relPath = path.relative(projectDir, written) || written;
+  process.stdout.write(`Wrote ${relPath}\n\n`);
+  process.stdout.write("Hook entry inserted under hooks.PreToolUse:\n");
+  const matcher = updated.hooks?.PreToolUse?.find((m) =>
+    m.hooks.some((h) => typeof h.command === "string" && h.command.includes(HOOK_MARKER)),
+  );
+  if (matcher) {
+    process.stdout.write(`  matcher: "${matcher.matcher}"\n`);
+    for (const h of matcher.hooks) {
+      if (typeof h.command === "string") {
+        process.stdout.write(`  command: ${h.command}\n`);
+      }
+      if (h.statusMessage) process.stdout.write(`  status:  ${h.statusMessage}\n`);
+    }
+  }
+  process.stdout.write(`\nMatcher targets: ${PRE_TOOL_USE_MATCHER}\n`);
+
+  return { ok: true, written };
+}

package/src/cli/uninstall-claude.ts

@@ -0,0 +1,40 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import {
+  readSettings,
+  removePreToolUse,
+  writeSettings,
+  HOOK_MARKER,
+} from "../claude/settings-writer.ts";
+
+export type UninstallClaudeOptions = {
+  projectDir: string;
+};
+
+export type UninstallClaudeResult =
+  | { ok: true; removed: boolean; written: string }
+  | { ok: false; reason: string };
+
+export function uninstallClaude(opts: UninstallClaudeOptions): UninstallClaudeResult {
+  const projectDir = path.resolve(opts.projectDir);
+  const settingsPath = path.join(projectDir, ".claude", "settings.json");
+
+  if (!fs.existsSync(settingsPath)) {
+    process.stdout.write(`No .claude/settings.json found at ${settingsPath} — nothing to do.\n`);
+    return { ok: true, removed: false, written: settingsPath };
+  }
+
+  const before = readSettings(projectDir);
+  const beforeHadMarker = JSON.stringify(before).includes(HOOK_MARKER);
+  const after = removePreToolUse(before);
+  const afterHasMarker = JSON.stringify(after).includes(HOOK_MARKER);
+
+  if (beforeHadMarker && !afterHasMarker) {
+    writeSettings(projectDir, after);
+    process.stdout.write(`Removed pi-module-gates hooks from ${settingsPath}.\n`);
+    return { ok: true, removed: true, written: settingsPath };
+  }
+
+  process.stdout.write(`No pi-module-gates hooks found in ${settingsPath}.\n`);
+  return { ok: true, removed: false, written: settingsPath };
+}

package/src/gates/checkers/index.ts

@@ -5,4 +5,5 @@ import "./go.ts";
 import "./kotlin.ts";
 import "./scala.ts";
 
-export { registerChecker, getChecker, ExportChecker } from "./registry.ts";
+export { registerChecker, getChecker } from "./registry.ts";
+export type { ExportChecker } from "./registry.ts";

package/src/gates/run-gates.ts

@@ -0,0 +1,112 @@
+import * as path from "node:path";
+import { parseFrontmatter } from "../utils/frontmatter.ts";
+import type { ModuleIndex } from "../types.ts";
+import type { ModuleGateConfig } from "../config.ts";
+import { readFileSafe, applyEdits, isWithinSourceRoot, findOwningModule } from "../utils.ts";
+import {
+  checkReadonly,
+  checkFrozen,
+  checkExports,
+  checkModuleInterfaceImports,
+} from "./index.ts";
+import "./checkers/index.ts";
+
+export type GateEdit = { oldText: string; newText: string };
+
+export type GateDenial = { block: true; reason: string };
+
+export function runGates(
+  filePath: string,
+  edits: GateEdit[],
+  cwd: string,
+  index: ModuleIndex,
+  config: ModuleGateConfig,
+  beforeOverride?: string,
+): GateDenial | undefined {
+  const absPath = path.resolve(cwd, filePath);
+
+  const before = beforeOverride ?? readFileSafe(absPath);
+  const after = applyEdits(before, edits);
+  const srcRoot = path.resolve(cwd, config.sourceRoot);
+
+  if (!isWithinSourceRoot(absPath, srcRoot)) return undefined;
+
+  const readonlyResult = checkReadonly(filePath, index, cwd, config.moduleDescriptorFileName);
+  if (readonlyResult.blocked) {
+    if (
+      config.moduleDescriptorReadonly === "frontmatter" &&
+      isDescriptorFile(absPath, config.moduleDescriptorFileName)
+    ) {
+      const fmBefore = extractFrontmatter(before);
+      const fmAfter = extractFrontmatter(after);
+      if (JSON.stringify(fmBefore) === JSON.stringify(fmAfter)) {
+        return undefined;
+      }
+      return {
+        block: true,
+        reason: formatDenial(
+          filePath,
+          `Readonly rule: frontmatter of ${config.moduleDescriptorFileName} is readonly`,
+          absPath,
+          index,
+          cwd,
+          config.moduleDescriptorFileName,
+        ),
+      };
+    }
+    return { block: true, reason: formatDenial(filePath, readonlyResult.reason, absPath, index, cwd, config.moduleDescriptorFileName) };
+  }
+
+  const frozenResult = checkFrozen(filePath, before, after, index, cwd, config.moduleDescriptorFileName);
+  if (frozenResult.blocked) {
+    return { block: true, reason: formatDenial(filePath, frozenResult.reason, absPath, index, cwd, config.moduleDescriptorFileName) };
+  }
+
+  const exportResult = checkExports(filePath, before, after, index, cwd, config.moduleDescriptorFileName);
+  if (exportResult.blocked) {
+    return { block: true, reason: formatDenial(filePath, exportResult.reason, absPath, index, cwd, config.moduleDescriptorFileName) };
+  }
+
+  const importResult = checkModuleInterfaceImports(filePath, after, index, cwd, config.disableModuleInterfaceImportGate, config.sourceRoot);
+  if (importResult.blocked) {
+    return { block: true, reason: formatDenial(filePath, importResult.reason, absPath, index, cwd, config.moduleDescriptorFileName) };
+  }
+
+  return undefined;
+}
+
+export function formatDenial(
+  relPath: string,
+  reason: string,
+  absPath: string,
+  index: ModuleIndex,
+  cwd: string,
+  descriptorFileName: string,
+): string {
+  const modulePath = findOwningModule(absPath, index);
+  const contract = modulePath
+    ? index.contracts.find((c) => c.modulePath === modulePath)
+    : undefined;
+
+  let message = `[Module Gate] Write blocked — ${relPath}\n\n${reason}`;
+
+  if (contract && contract.prose) {
+    const relModuleMd = path.relative(cwd, path.join(contract.modulePath, descriptorFileName));
+    message += `\n\nModule contract (${relModuleMd}):\n${contract.prose}`;
+  }
+
+  return message;
+}
+
+export function isDescriptorFile(absPath: string, descriptorFileName: string): boolean {
+  const basename = path.basename(absPath);
+  return basename.toLowerCase() === descriptorFileName.toLowerCase();
+}
+
+export function extractFrontmatter(content: string): Record<string, unknown> {
+  try {
+    return parseFrontmatter(content).frontmatter;
+  } catch {
+    return {};
+  }
+}

package/src/graph/module-index-builder.ts

@@ -1,7 +1,7 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { readdir } from "node:fs/promises";
-import { parseFrontmatter } from "@earendil-works/pi-coding-agent";
+import { parseFrontmatter } from "../utils/frontmatter.ts";
 import type { ModuleContract, ModuleIndex } from "../types.ts";
 import type { ModuleGateConfig } from "../config.ts";
 

package/src/index.ts

@@ -4,18 +4,13 @@ import type {
   ToolCallEventResult,
   BeforeAgentStartEventResult,
 } from "@earendil-works/pi-coding-agent";
-import { isToolCallEventType, parseFrontmatter } from "@earendil-works/pi-coding-agent";
+import { isToolCallEventType } from "@earendil-works/pi-coding-agent";
 import type { ModuleIndex } from "./types.ts";
 import { loadConfig } from "./config.ts";
 import type { ModuleGateConfig } from "./config.ts";
 import { buildModuleIndex } from "./graph/index.ts";
-import { findOwningModule, readFileSafe, applyEdits, isWithinSourceRoot } from "./utils.ts";
-import {
-  checkReadonly,
-  checkExports,
-  checkFrozen,
-  checkModuleInterfaceImports,
-} from "./gates/index.ts";
+import { readFileSafe } from "./utils.ts";
+import { runGates, type GateEdit } from "./gates/run-gates.ts";
 import { buildSystemPromptHint } from "./context/index.ts";
 import "./gates/checkers/index.ts";
 
@@ -43,107 +38,13 @@ export default function (pi: ExtensionAPI): void {
 
   pi.on("tool_call", async (event, ctx): Promise<ToolCallEventResult | void> => {
     if (isToolCallEventType("edit", event)) {
-      return handleEdit(event.input.path, event.input.edits, ctx.cwd, index, config);
+      return runGates(event.input.path, event.input.edits, ctx.cwd, index, config);
     }
     if (isToolCallEventType("write", event)) {
       const absPath = path.resolve(ctx.cwd, event.input.path);
       const before = readFileSafe(absPath);
-      return handleEdit(event.input.path, [{ oldText: before, newText: event.input.content }], ctx.cwd, index, config);
+      const edits: GateEdit[] = [{ oldText: before, newText: event.input.content }];
+      return runGates(event.input.path, edits, ctx.cwd, index, config);
     }
   });
-}
-
-function handleEdit(
-  filePath: string,
-  edits: { oldText: string; newText: string }[],
-  cwd: string,
-  index: ModuleIndex,
-  config: ModuleGateConfig,
-): ToolCallEventResult | undefined {
-  const absPath = path.resolve(cwd, filePath);
-
-  const before = readFileSafe(absPath);
-  const after = applyEdits(before, edits);
-  const srcRoot = path.resolve(cwd, config.sourceRoot);
-
-  if (!isWithinSourceRoot(absPath, srcRoot)) return undefined;
-
-  const readonlyResult = checkReadonly(filePath, index, cwd, config.moduleDescriptorFileName);
-  if (readonlyResult.blocked) {
-    if (
-      config.moduleDescriptorReadonly === "frontmatter" &&
-      isDescriptorFile(absPath, config.moduleDescriptorFileName)
-    ) {
-      const fmBefore = extractFrontmatter(before);
-      const fmAfter = extractFrontmatter(after);
-      if (JSON.stringify(fmBefore) === JSON.stringify(fmAfter)) {
-        return undefined;
-      }
-      return {
-        block: true,
-        reason: formatDenial(
-          filePath,
-          `Readonly rule: frontmatter of ${config.moduleDescriptorFileName} is readonly`,
-          absPath,
-          index,
-          cwd,
-          config.moduleDescriptorFileName,
-        ),
-      };
-    }
-    return { block: true, reason: formatDenial(filePath, readonlyResult.reason, absPath, index, cwd, config.moduleDescriptorFileName) };
-  }
-
-  const frozenResult = checkFrozen(filePath, before, after, index, cwd, config.moduleDescriptorFileName);
-  if (frozenResult.blocked) {
-    return { block: true, reason: formatDenial(filePath, frozenResult.reason, absPath, index, cwd, config.moduleDescriptorFileName) };
-  }
-
-  const exportResult = checkExports(filePath, before, after, index, cwd, config.moduleDescriptorFileName);
-  if (exportResult.blocked) {
-    return { block: true, reason: formatDenial(filePath, exportResult.reason, absPath, index, cwd, config.moduleDescriptorFileName) };
-  }
-
-  const importResult = checkModuleInterfaceImports(filePath, after, index, cwd, config.disableModuleInterfaceImportGate, config.sourceRoot);
-  if (importResult.blocked) {
-    return { block: true, reason: formatDenial(filePath, importResult.reason, absPath, index, cwd, config.moduleDescriptorFileName) };
-  }
-
-  return undefined;
-}
-
-function formatDenial(
-  relPath: string,
-  reason: string,
-  absPath: string,
-  index: ModuleIndex,
-  cwd: string,
-  descriptorFileName: string,
-): string {
-  const modulePath = findOwningModule(absPath, index);
-  const contract = modulePath
-    ? index.contracts.find((c) => c.modulePath === modulePath)
-    : undefined;
-
-  let message = `[Module Gate] Write blocked — ${relPath}\n\n${reason}`;
-
-  if (contract && contract.prose) {
-    const relModuleMd = path.relative(cwd, path.join(contract.modulePath, descriptorFileName));
-    message += `\n\nModule contract (${relModuleMd}):\n${contract.prose}`;
-  }
-
-  return message;
-}
-
-function isDescriptorFile(absPath: string, descriptorFileName: string): boolean {
-  const basename = path.basename(absPath);
-  return basename.toLowerCase() === descriptorFileName.toLowerCase();
-}
-
-function extractFrontmatter(content: string): Record<string, unknown> {
-  try {
-    return parseFrontmatter(content).frontmatter;
-  } catch {
-    return {};
-  }
-}
+}

package/src/utils/frontmatter.ts

@@ -0,0 +1,41 @@
+import { parse } from "yaml";
+
+type ParsedFrontmatter<T extends Record<string, unknown>> = {
+  frontmatter: T;
+  body: string;
+};
+
+const normalizeNewlines = (value: string): string =>
+  value.replace(/\r\n/g, "\n").replace(/\r/g, "\n");
+
+const extractFrontmatter = (
+  content: string,
+): { yamlString: string | null; body: string } => {
+  const normalized = normalizeNewlines(content);
+  if (!normalized.startsWith("---")) {
+    return { yamlString: null, body: normalized };
+  }
+  const endIndex = normalized.indexOf("\n---", 3);
+  if (endIndex === -1) {
+    return { yamlString: null, body: normalized };
+  }
+  return {
+    yamlString: normalized.slice(4, endIndex),
+    body: normalized.slice(endIndex + 4).trim(),
+  };
+};
+
+export function parseFrontmatter<T extends Record<string, unknown> = Record<string, unknown>>(
+  content: string,
+): ParsedFrontmatter<T> {
+  const { yamlString, body } = extractFrontmatter(content);
+  if (!yamlString) {
+    return { frontmatter: {} as T, body };
+  }
+  const parsed = parse(yamlString) as T | null | undefined;
+  return { frontmatter: (parsed ?? ({} as T)), body };
+}
+
+export function stripFrontmatter(content: string): string {
+  return parseFrontmatter(content).body;
+}