@cuzfrog/pi-module-gates 0.6.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Cause Chung
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,137 @@
+# pi-module-gates - Constraints liberate, liberties constrain.
+
+pi cli extension that controls the entropy of the codebase by enforcing code module boundaries.
+It helps combat slop generation and code architecture degradation.
+
+## Installation
+
+```bash
+pi install npm:@cuzfrog/pi-module-gates
+```
+
+Or load directly for a single session:
+
+```bash
+pi -e npm:@cuzfrog/pi-module-gates
+```
+
+## Problem
+
+AI coding agents produce edits with limited context knowledge (myopia) — their changes may leak implementation details, and break architectural contracts (slop).
+
+### Approach
+
+**Module contracts as guardrails.** Each directory can contain a descriptor file that declares:
+
+- `visible` — the set of exports allowed to be added or modified in that module
+- `readonly` — files and directories the agent must not touch
+
+The extension intercepts agent `write`/`edit` operations and enforces these contracts. Violations are blocked with a clear reason.
+
+### How it works
+
+1. **Indexing** — On session start, scans the project tree for descriptor files and builds a module index.
+2. **System prompt** — Injects a hint so the agent knows to respect descriptor file conventions.
+3. **Gating** — On every write/edit, checks:
+   - **Readonly gate** — is the target file locked?
+   - **Export gate** — would the change introduce an export not in the `visible` list?
+   - **Import gate** (not implemented yet) — would the change introduce an import violating visibility scope?
+
+System prompt:
+```markdown
+## Module gates (boundary enforcement)
+   This project uses `module.md` files to declare visibility and readonly rules that you should follow.
+   If you cannot comply, reconsider your design, if impossible, raise to the user with tradeoffs.
+   Each `module.md` gates its branching point in the tree.
+   A `module.md` with a `visible` list means only entries in the list are allowed to be visible outside the module.
+   A `module.md` and its mentioned `readonly` files are readonly.
+   Violations will be blocked.
+```
+`module.md` filename is configurable.
+
+## Module Descriptor Semantics
+
+A module descriptor is a Markdown file (default name: `MODULE.md`) placed in a directory. You can piggy-back on your module context file for example `CONTEXT.md`.
+
+### Simple readonly constraints
+
+```markdown
+---
+readonly: [mod.rs]
+---
+
+Any prose for the agent to better understand the module.
+```
+
+### Visibility whitelist
+
+```yaml
+visible:
+  - greet # equivalent to `path: ./greet`
+  - sub/mod1/Foo
+```
+or:
+```yaml
+visible:
+  - path: my_function
+    modifier: pub(crate) # (optional) demands an exact match
+```
+
+| Scenario | Behavior |
+|----------|----------|
+| `visible` key absent or no `MODULE.md` | Module is unconstrained — exports are not gated. Equivalent to `null` internally. |
+| `visible: []` | Module is fully closed — no new exports may be added. Editing existing exports is still allowed. |
+| Malformed YAML frontmatter | The module is left unguarded and an info notification is emitted. |
+
+### Export gating
+
+```
+project/
+  MODULE.md          visible: [Foo, Bar]
+  src/
+    MODULE.md        visible: [Bar, Baz]
+    app.ts           ← checked against `src/MODULE.md` only
+```
+A `MODULE.md` only enforces exports within its immediate directory.
+
+### Import gating (not implemented yet)
+
+```yaml
+# parent/MODULE.md
+visible:
+  - sub/Tool # type Tool is allowed to be imported from parent
+
+# parent/sub/MODULE.md (before complement pass)
+visible:
+  - Bar # type Bar is allowed to be imported from parent/sub within parent, but not outside parent
+```
+A `MODULE.md` semantically gates exposures at the module level it resides.
+
+## Configuration
+
+Add a `module-gate` entry to `.pi/settings.json`:
+
+```json
+{
+  "module-gate": {
+    "moduleDescriptorFileName": "MODULE.md",
+    "moduleDescriptorReadonly": true,
+    "sourceRoot": "src/"
+  }
+}
+```
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `moduleDescriptorFileName` | `"MODULE.md"` | File name used for module descriptors (case-insensitive) |
+| `moduleDescriptorReadonly` | `true` | When `true`, descriptor files are readonly.|
+| `sourceRoot` | `"src/"` | Directory to scan for descriptor files and enforce gates. Set to `""` to scan from project root. |
+
+When no settings file exists or no `module-gate` key is present, defaults apply.
+
+## License
+
+MIT
+
+## Author
+Cause Chung (cuzfrog@gmail.com)

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@cuzfrog/pi-module-gates",
+  "version": "0.6.0",
+  "description": "pi extension that controls the entropy of the codebase by enforcing code module boundaries.",
+  "keywords": ["pi-package"],
+  "type": "module",
+  "scripts": {
+    "check": "tsc --noEmit",
+    "test": "vitest run"
+  },
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "0.75.4",
+    "@types/node": "22.19.19",
+    "typescript": "5.9.3",
+    "vitest": "4.1.7"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/cuzfrog/pi-module-gate.git"
+  },
+  "bugs": {
+    "url": "https://github.com/cuzfrog/pi-module-gate/issues"
+  },
+  "homepage": "https://github.com/cuzfrog/pi-module-gate#readme",
+  "license": "MIT",
+  "author": "Cause Chung (cuzfrog@gmail.com)",
+  "files": ["src/", "README.md", "LICENSE"],
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  }
+}

package/src/config.ts

@@ -0,0 +1,29 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+export type ModuleGateConfig = {
+  moduleDescriptorFileName: string;
+  moduleDescriptorReadonly: boolean;
+  sourceRoot: string;
+};
+
+const DEFAULTS: ModuleGateConfig = {
+  moduleDescriptorFileName: "module.md",
+  moduleDescriptorReadonly: true,
+  sourceRoot: "src/",
+};
+
+export function loadConfig(cwd: string): ModuleGateConfig {
+  const settingsPath = path.join(cwd, ".pi", "settings.json");
+  let userConfig: Partial<ModuleGateConfig> = {};
+  try {
+    const raw = fs.readFileSync(settingsPath, "utf-8");
+    const settings = JSON.parse(raw);
+    if (settings["module-gate"] && typeof settings["module-gate"] === "object") {
+      userConfig = settings["module-gate"];
+    }
+  } catch {
+    // file doesn't exist or invalid — use defaults
+  }
+  return { ...DEFAULTS, ...userConfig };
+}

package/src/context/system-prompt.ts

@@ -0,0 +1,19 @@
+import type { ModuleIndex } from "../types.ts";
+
+export function buildSystemPromptHint(
+  index: ModuleIndex,
+  systemPrompt: string,
+  descriptorFileName: string,
+): string {
+  if (index.contracts.length === 0) return systemPrompt;
+
+  return systemPrompt + `
+
+## Module gates (boundary enforcement)
+This project uses \`${descriptorFileName}\`(case-insensitive) files to declare visibility and readonly rules that you should follow.
+If you cannot comply, reconsider your design, if impossible, raise to the user with tradeoffs.
+Each \`${descriptorFileName}\` gates its branching point in the tree.
+A \`${descriptorFileName}\` with a \`visible\` list means only entries in the list are allowed to be visible outside the module.
+A \`${descriptorFileName}\` and its mentioned \`readonly\` files are readonly.
+Violations will be blocked.`;
+}

package/src/gates/checkers/index.ts

@@ -0,0 +1,2 @@
+import "./typescript.ts";
+import "./rust.ts";

package/src/gates/checkers/registry.ts

@@ -0,0 +1,19 @@
+import * as path from "node:path";
+import type { Signature } from "../../types.ts";
+
+export interface ExportChecker {
+  extensions: string[];
+  getNewExports(before: string, after: string): Signature[];
+}
+
+const checkerRegistry = new Map<string, ExportChecker>();
+
+export function registerChecker(checker: ExportChecker): void {
+  for (const ext of checker.extensions) {
+    checkerRegistry.set(ext, checker);
+  }
+}
+
+export function getChecker(filePath: string): ExportChecker | undefined {
+  return checkerRegistry.get(path.extname(filePath));
+}

package/src/gates/checkers/rust.ts

@@ -0,0 +1,19 @@
+import { registerChecker } from "./registry.ts";
+import type { ExportChecker } from "./registry.ts";
+import type { Signature } from "../../types.ts";
+
+const rustChecker: ExportChecker = {
+  extensions: [".rs"],
+  getNewExports(before: string, after: string): Signature[] {
+    const beforeNames = new Set(extractPubItems(before).map((s) => s.name));
+    return extractPubItems(after).filter((sig) => !beforeNames.has(sig.name));
+  },
+};
+
+registerChecker(rustChecker);
+
+function extractPubItems(src: string): Signature[] {
+  return [...src.matchAll(
+    /^(pub(?:\([^)]*\))?)\s+(?:fn|struct|enum|trait|type|const|mod)\s+(\w+)/gm,
+  )].map((m) => ({ modifier: m[1], name: m[2] }));
+}

package/src/gates/checkers/typescript.ts

@@ -0,0 +1,19 @@
+import { registerChecker } from "./registry.ts";
+import type { ExportChecker } from "./registry.ts";
+import type { Signature } from "../../types.ts";
+
+const tsChecker: ExportChecker = {
+  extensions: [".ts", ".tsx", ".js", ".jsx"],
+  getNewExports(before: string, after: string): Signature[] {
+    const beforeNames = new Set(extractExports(before).map((s) => s.name));
+    return extractExports(after).filter((sig) => !beforeNames.has(sig.name));
+  },
+};
+
+registerChecker(tsChecker);
+
+function extractExports(src: string): Signature[] {
+  return [...src.matchAll(
+    /^export\s+(?:default\s+)?(?:\w+\s+)*(?:function(?:\s*\*)?|class|const|let|var|type|interface|enum)\s+(\w+)/gm,
+  )].map((m) => ({ name: m[1] }));
+}

package/src/gates/export-gate.ts

@@ -0,0 +1,74 @@
+import * as path from "node:path";
+import { getChecker } from "./checkers/registry.ts";
+import type { ModuleIndex, Signature } from "../types.ts";
+
+export type ExportViolation = { name: string; imposedBy: string };
+
+export type ExportCheckResult =
+  | { blocked: true; violations: ExportViolation[]; reason: string }
+  | { blocked: false };
+
+export function checkExports(
+  filePath: string,
+  beforeContent: string,
+  afterContent: string,
+  index: ModuleIndex,
+  cwd: string,
+  descriptorFileName: string,
+): ExportCheckResult {
+  const absFile = path.resolve(cwd, filePath);
+  const checker = getChecker(absFile);
+  if (!checker) return { blocked: false };
+
+  const contract = findImmediateContract(absFile, index.contracts);
+  if (!contract || contract.visible === null) return { blocked: false };
+
+  const newExports = checker.getNewExports(beforeContent, afterContent);
+  const violations: ExportViolation[] = [];
+
+  for (const sig of newExports) {
+    const visibleEntry = contract.visible.find((s) => s.name === sig.name);
+    if (!visibleEntry) {
+      violations.push({
+        name: sig.name,
+        imposedBy: path.relative(cwd, path.join(contract.modulePath, descriptorFileName)),
+      });
+      continue;
+    }
+
+    const requiredMod = visibleEntry.modifier;
+    if (requiredMod !== undefined && sig.modifier !== requiredMod) {
+      violations.push({
+        name: `${sig.modifier ?? ""} ${sig.name}`.trim(),
+        imposedBy: path.relative(cwd, path.join(contract.modulePath, descriptorFileName)),
+      });
+      continue;
+    }
+  }
+
+  if (violations.length === 0) return { blocked: false };
+
+  const lines = violations.map(
+    (v) => `  \u2022 ${v.name}  not in visible list of ${v.imposedBy}`,
+  );
+  return {
+    blocked: true,
+    violations,
+    reason: `Export violations:\n${lines.join("\n")}`,
+  };
+}
+
+function findImmediateContract(
+  absFile: string,
+  contracts: { modulePath: string; visible: Signature[] | null }[],
+): { modulePath: string; visible: Signature[] | null } | undefined {
+  let best: { modulePath: string; visible: Signature[] | null } | undefined;
+  for (const c of contracts) {
+    if (absFile.startsWith(c.modulePath + path.sep) || absFile === c.modulePath) {
+      if (!best || c.modulePath.length > best.modulePath.length) {
+        best = c;
+      }
+    }
+  }
+  return best;
+}

package/src/gates/readonly-gate.ts

@@ -0,0 +1,53 @@
+import * as path from "node:path";
+import type { ModuleIndex } from "../types.ts";
+
+export type ReadonlyCheckResult =
+  | { blocked: true; reason: string }
+  | { blocked: false };
+
+export function checkReadonly(
+  filePath: string,
+  index: ModuleIndex,
+  cwd: string,
+  descriptorFileName: string,
+): ReadonlyCheckResult {
+  const absFile = path.resolve(cwd, filePath);
+  const ancestors = getAncestorContracts(absFile, index);
+
+  for (const contract of ancestors) {
+    for (const pattern of contract.readonly) {
+      if (matchesReadonlyPattern(absFile, pattern, contract.modulePath)) {
+        const relModuleMd = path.relative(cwd, path.join(contract.modulePath, descriptorFileName));
+        return {
+          blocked: true,
+          reason: `Readonly rule: file is listed as readonly in ${relModuleMd}`,
+        };
+      }
+    }
+  }
+
+  return { blocked: false };
+}
+
+function getAncestorContracts(absFile: string, index: ModuleIndex) {
+  return index.contracts.filter((c) => absFile.startsWith(c.modulePath + path.sep) || absFile === c.modulePath);
+}
+
+function matchesReadonlyPattern(
+  absFile: string,
+  pattern: string,
+  modulePath: string,
+): boolean {
+  const resolved = path.resolve(modulePath, pattern);
+
+  if (pattern.endsWith("*")) {
+    const prefix = path.resolve(modulePath, pattern.slice(0, -1));
+    return absFile.startsWith(prefix);
+  }
+
+  if (absFile === resolved) return true;
+
+  if (absFile.startsWith(resolved + path.sep)) return true;
+
+  return false;
+}

package/src/graph/MODULE.md

@@ -0,0 +1,4 @@
+---
+visible: [buildModuleIndex]
+---
+

package/src/graph/frontmatter-parser.ts

@@ -0,0 +1,27 @@
+import type { Signature } from "../types.ts";
+
+export type VisibleEntryRaw = string | { path: string; modifier?: string };
+
+export type ModuleFrontmatter = {
+  visible?: VisibleEntryRaw[];
+  readonly?: string[];
+};
+
+export function parseVisibleEntry(raw: VisibleEntryRaw): Signature {
+  if (typeof raw === "string") {
+    const trimmed = raw.trim();
+    return { name: extractNameFromPath(trimmed), path: trimmed };
+  }
+  return {
+    name: extractNameFromPath(raw.path),
+    modifier: raw.modifier,
+    path: raw.path,
+  };
+}
+
+function extractNameFromPath(pathStr: string): string {
+  let p = pathStr.trim();
+  if (p.endsWith("/")) p = p.slice(0, -1);
+  const lastSlash = p.lastIndexOf("/");
+  return lastSlash >= 0 ? p.slice(lastSlash + 1) : p;
+}

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

@@ -0,0 +1,179 @@
+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 type { ModuleContract, ModuleIndex } from "../types.ts";
+import type { ModuleGateConfig } from "../config.ts";
+import type { Dirent } from "node:fs";
+import { validateVisibleEntries } from "./validation.ts";
+import { parseVisibleEntry, type VisibleEntryRaw, type ModuleFrontmatter } from "./frontmatter-parser.ts";
+
+type IndexContext = {
+  cwd: string;
+  ui: { notify(message: string, type?: string): void };
+};
+
+export async function buildModuleIndex(
+  ctx: IndexContext,
+  config: ModuleGateConfig,
+): Promise<ModuleIndex> {
+  const notify = (msg: string) => ctx.ui.notify(msg, "info");
+  const scanRoot = path.resolve(ctx.cwd, config.sourceRoot);
+
+  const moduleFiles = await findModuleFiles(scanRoot, config.moduleDescriptorFileName);
+  const contracts = buildContracts(moduleFiles, notify, config.moduleDescriptorFileName, config.moduleDescriptorReadonly);
+  applyComplementPass(contracts);
+  const dirToModule = await buildDirToModuleMap(contracts);
+  const index: ModuleIndex = { contracts, dirToModule };
+
+  await validateVisibleEntries(index, ctx.cwd, ctx.ui.notify, config.moduleDescriptorFileName);
+
+  return index;
+}
+
+function buildContracts(
+  moduleFiles: string[],
+  onInfo: (message: string) => void,
+  descriptorFileName: string,
+  moduleDescriptorReadonly: boolean,
+): ModuleContract[] {
+  const contracts: ModuleContract[] = [];
+
+  for (const absModuleFile of moduleFiles) {
+    const modulePath = path.dirname(absModuleFile);
+    const content = fs.readFileSync(absModuleFile, "utf-8");
+
+    let frontmatter: ModuleFrontmatter;
+    let body: string;
+    try {
+      const parsed = parseFrontmatter<ModuleFrontmatter>(content);
+      frontmatter = parsed.frontmatter;
+      body = parsed.body;
+    } catch {
+      onInfo(
+        `[Module Gate] Failed to parse ${absModuleFile} — module will be unguarded`,
+      );
+      continue;
+    }
+
+    const readonlyEntries = frontmatter.readonly ?? [];
+    if (moduleDescriptorReadonly) {
+      readonlyEntries.push(descriptorFileName);
+    }
+
+    contracts.push({
+      modulePath,
+      visible:
+        frontmatter.visible !== undefined
+          ? frontmatter.visible.map(parseVisibleEntry)
+          : null,
+      readonly: readonlyEntries,
+      prose: body.trim(),
+    });
+  }
+
+  contracts.sort((a, b) => a.modulePath.length - b.modulePath.length);
+  return contracts;
+}
+
+async function buildDirToModuleMap(
+  contracts: ModuleContract[],
+): Promise<Map<string, string>> {
+  const dirToModule = new Map<string, string>();
+  const sortedByDepth = [...contracts].sort(
+    (a, b) => a.modulePath.length - b.modulePath.length,
+  );
+
+  for (const contract of sortedByDepth) {
+    const dirs = await walkDirs(contract.modulePath);
+    for (const dir of dirs) {
+      dirToModule.set(dir, contract.modulePath);
+    }
+  }
+
+  return dirToModule;
+}
+
+async function findModuleFiles(dir: string, descriptorFileName: string): Promise<string[]> {
+  const results: string[] = [];
+  const stack: string[] = [dir];
+
+  while (stack.length > 0) {
+    const current = stack.pop()!;
+    let entries: Dirent[];
+    try {
+      entries = await readdir(current, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+
+    for (const entry of entries) {
+      if (entry.name === "node_modules" || entry.name === ".git") continue;
+      const fullPath = path.join(current, entry.name);
+      if (entry.isDirectory()) {
+        stack.push(fullPath);
+      } else if (entry.name.toLowerCase() === descriptorFileName.toLowerCase()) {
+        results.push(fullPath);
+      }
+    }
+  }
+
+  return results;
+}
+
+function applyComplementPass(contracts: ModuleContract[]): void {
+  for (const contract of contracts) {
+    if (contract.visible === null) continue;
+    for (const sig of contract.visible) {
+      if (!sig.path) continue;
+      const targetDir = resolveDir(contract.modulePath, sig.path);
+      if (targetDir === contract.modulePath) continue;
+      const target = contracts.find((c) => c.modulePath === targetDir);
+      if (!target || target.visible === null) continue;
+      if (target.visible.some((s) => s.name === sig.name)) continue;
+      target.visible.push({ name: sig.name, modifier: sig.modifier });
+    }
+  }
+}
+
+function resolveDir(modulePath: string, entryPath: string): string {
+  const dirPart = pathDirPart(entryPath);
+  if (!dirPart) return modulePath;
+  const joined = path.join(modulePath, dirPart);
+  return joined.endsWith(path.sep) ? joined.slice(0, -1) : joined;
+}
+
+function pathDirPart(entryPath: string): string {
+  const trimmed = entryPath.trim();
+  const lastSlash = trimmed.lastIndexOf("/");
+  if (lastSlash < 0) return "";
+  return trimmed.slice(0, lastSlash + 1);
+}
+
+async function walkDirs(root: string): Promise<string[]> {
+  const results: string[] = [root];
+  const stack: string[] = [root];
+
+  while (stack.length > 0) {
+    const current = stack.pop()!;
+    let entries: Dirent[];
+    try {
+      entries = await readdir(current, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+
+    for (const entry of entries) {
+      if (entry.name === "node_modules" || entry.name === ".git") continue;
+      if (entry.isDirectory()) {
+        const fullPath = path.join(current, entry.name);
+        results.push(fullPath);
+        stack.push(fullPath);
+      }
+    }
+  }
+
+  return results;
+}
+
+

package/src/graph/validation.ts

@@ -0,0 +1,116 @@
+import * as path from "node:path";
+import { readdir } from "node:fs/promises";
+import type { ModuleIndex } from "../types.ts";
+import { getChecker } from "../gates/checkers/registry.ts";
+import { readFileSafe } from "../utils.ts";
+import type { Dirent } from "node:fs";
+
+type NotifyFn = (message: string, type?: "info" | "warning" | "error") => void;
+
+export async function validateVisibleEntries(
+  idx: ModuleIndex,
+  cwd: string,
+  notify: NotifyFn,
+  descriptorFileName: string,
+): Promise<void> {
+  const childModules = new Set(
+    idx.contracts.map((c) => c.modulePath),
+  );
+
+  for (const contract of idx.contracts) {
+    if (contract.visible === null) continue;
+
+    const exportedSymbols = await collectExports(contract.modulePath, childModules);
+    // Cache for non-local path resolution
+    const pathExportsCache = new Map<string, Set<string>>();
+
+    for (const sig of contract.visible) {
+      const targetDir = resolveValidationTarget(contract.modulePath, sig.path);
+      const symbols =
+        targetDir !== contract.modulePath
+          ? await resolvePathExports(targetDir, pathExportsCache, childModules)
+          : exportedSymbols;
+
+      if (!symbols.has(sig.name)) {
+        const relModule = path.relative(cwd, path.join(contract.modulePath, descriptorFileName));
+        notify(
+          `[Module Gate] Dangling visible entry "${sig.name}" in ${relModule}`,
+          "info",
+        );
+      }
+    }
+  }
+}
+
+function resolveValidationTarget(modulePath: string, entryPath?: string): string {
+  if (!entryPath) return modulePath;
+  const lastSlash = entryPath.lastIndexOf("/");
+  if (lastSlash < 0) return modulePath;
+  const dirPart = entryPath.slice(0, lastSlash + 1);
+  const joined = path.join(modulePath, dirPart);
+  return joined.endsWith(path.sep) ? joined.slice(0, -1) : joined;
+}
+
+async function collectExports(
+  modulePath: string,
+  childModules: Set<string>,
+): Promise<Set<string>> {
+  const files = await listFiles(modulePath, childModules);
+  const symbols = new Set<string>();
+  for (const filePath of files) {
+    const checker = getChecker(filePath);
+    if (!checker) continue;
+    const content = readFileSafe(filePath);
+    const exports = checker.getNewExports("", content);
+    for (const sig of exports) {
+      symbols.add(sig.name);
+    }
+  }
+  return symbols;
+}
+
+async function resolvePathExports(
+  targetDir: string,
+  cache: Map<string, Set<string>>,
+  childModules: Set<string>,
+): Promise<Set<string>> {
+  let symbols = cache.get(targetDir);
+  if (!symbols) {
+    symbols = await collectExports(targetDir, childModules);
+    cache.set(targetDir, symbols);
+  }
+  return symbols;
+}
+
+async function listFiles(
+  dir: string,
+  childModules: Set<string>,
+): Promise<string[]> {
+  const results: string[] = [];
+  const stack: string[] = [dir];
+
+  while (stack.length > 0) {
+    const current = stack.pop()!;
+    let entries: Dirent[];
+    try {
+      entries = await readdir(current, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+
+    for (const entry of entries) {
+      if (entry.name === "node_modules" || entry.name === ".git") continue;
+      const fullPath = path.join(current, entry.name);
+      if (entry.isDirectory()) {
+        if (childModules.has(fullPath) && fullPath !== dir) continue;
+        stack.push(fullPath);
+      } else {
+        results.push(fullPath);
+      }
+    }
+  }
+
+  return results;
+}
+
+

package/src/index.ts

@@ -0,0 +1,126 @@
+import * as path from "node:path";
+import type {
+  ExtensionAPI,
+  ToolCallEventResult,
+  BeforeAgentStartEventResult,
+} 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/module-index-builder.ts";
+import { findOwningModule, readFileSafe, applyEdits, isWithinSourceRoot } from "./utils.ts";
+import { checkReadonly } from "./gates/readonly-gate.ts";
+import { checkExports } from "./gates/export-gate.ts";
+import { buildSystemPromptHint } from "./context/system-prompt.ts";
+import "./gates/checkers/index.ts";
+
+export default function (pi: ExtensionAPI): void {
+  let index: ModuleIndex;
+  let config: ModuleGateConfig;
+
+  pi.on("session_start", async (_event, ctx) => {
+    config = loadConfig(ctx.cwd);
+    index = await buildModuleIndex(ctx, config);
+    if (index.contracts.length === 0) {
+      ctx.ui.notify(
+        "[Module Gate] No module descriptor files found. Gates are not active.",
+        "info",
+      );
+    }
+  });
+
+  pi.on("before_agent_start", async (event): Promise<BeforeAgentStartEventResult | void> => {
+    if (index.contracts.length === 0) return;
+    return {
+      systemPrompt: buildSystemPromptHint(index, event.systemPrompt, config.moduleDescriptorFileName),
+    };
+  });
+
+  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);
+    }
+    if (isToolCallEventType("write", event)) {
+      return handleWrite(event.input.path, event.input.content, 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 resolvedRoot = path.resolve(cwd, config.sourceRoot);
+
+  if (!isWithinSourceRoot(absPath, resolvedRoot)) return undefined;
+
+  const readonlyResult = checkReadonly(filePath, index, cwd, config.moduleDescriptorFileName);
+  if (readonlyResult.blocked) {
+    return { block: true, reason: formatDenial(filePath, readonlyResult.reason, absPath, index, cwd, config.moduleDescriptorFileName) };
+  }
+
+  const before = readFileSafe(absPath);
+  const after = applyEdits(before, edits);
+
+  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) };
+  }
+
+  return undefined;
+}
+
+function handleWrite(
+  filePath: string,
+  content: string,
+  cwd: string,
+  index: ModuleIndex,
+  config: ModuleGateConfig,
+): ToolCallEventResult | undefined {
+  const absPath = path.resolve(cwd, filePath);
+  const resolvedRoot = path.resolve(cwd, config.sourceRoot);
+
+  if (!isWithinSourceRoot(absPath, resolvedRoot)) return undefined;
+
+  const readonlyResult = checkReadonly(filePath, index, cwd, config.moduleDescriptorFileName);
+  if (readonlyResult.blocked) {
+    return { block: true, reason: formatDenial(filePath, readonlyResult.reason, absPath, index, cwd, config.moduleDescriptorFileName) };
+  }
+
+  const before = readFileSafe(absPath);
+
+  const exportResult = checkExports(filePath, before, content, index, cwd, config.moduleDescriptorFileName);
+  if (exportResult.blocked) {
+    return { block: true, reason: formatDenial(filePath, exportResult.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;
+}

package/src/types.ts

@@ -0,0 +1,17 @@
+export type Signature = {
+  modifier?: string;
+  name: string;
+  path?: string;
+};
+
+export type ModuleContract = {
+  modulePath: string;
+  visible: Signature[] | null;
+  readonly: string[];
+  prose: string;
+};
+
+export type ModuleIndex = {
+  contracts: ModuleContract[];
+  dirToModule: Map<string, string>;
+};

package/src/utils.ts

@@ -0,0 +1,40 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import type { ModuleIndex } from "./types.ts";
+
+export function findOwningModule(
+  absPath: string,
+  index: ModuleIndex,
+): string | undefined {
+  let current = path.dirname(absPath);
+  const root = path.parse(current).root;
+
+  while (true) {
+    const owner = index.dirToModule.get(current);
+    if (owner !== undefined) return owner;
+    if (current === root) break;
+    current = path.dirname(current);
+  }
+
+  return undefined;
+}
+
+export function readFileSafe(absPath: string): string {
+  try {
+    return fs.readFileSync(absPath, "utf-8");
+  } catch {
+    return "";
+  }
+}
+
+export function applyEdits(content: string, edits: { oldText: string; newText: string }[]): string {
+  let result = content;
+  for (const edit of edits) {
+    result = result.replace(edit.oldText, edit.newText);
+  }
+  return result;
+}
+
+export function isWithinSourceRoot(absPath: string, resolvedRoot: string): boolean {
+  return absPath.startsWith(resolvedRoot + path.sep) || absPath === resolvedRoot;
+}