@crouton-kit/crouter 0.3.33 → 0.3.34

package/dist/builtin-pi-packages/pi-crtr-extensions/extensions/nested-context.ts

@@ -0,0 +1,327 @@
+/**
+ * Nested Context Loader
+ *
+ * Pi only loads AGENTS.md / CLAUDE.md from the cwd's ancestor chain at startup.
+ * Anything *below* the launch dir (subproject CLAUDE.md files, .claude/rules/)
+ * is never pulled in. This extension fills that gap:
+ *
+ * When the `read` tool reads a file, we walk from that file's directory up to
+ * the session cwd and surface, appended to the read result:
+ *   1. Each directory's CLAUDE.md / AGENTS.md (first match per dir).
+ *   2. Each directory's .claude/rules/*.md — unconditionally if the rule has no
+ *      `paths:` frontmatter, or only when the read file matches one of its
+ *      `paths:` globs.
+ *
+ * Guarantees:
+ *   - No duplicates. A `seen` set tracks every absolute path already loaded,
+ *     including the files pi loaded at startup (seeded in session_start) and any
+ *     context/rule file the agent reads directly.
+ *   - Bounded. Anchored to the file's own parent chain (not the session cwd),
+ *     stops at $HOME, and skips generated/dependency dirs (node_modules, ...).
+ *
+ * Install: drop in ~/.pi/agent/extensions/ (global) or .pi/extensions/ (project).
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+
+// First-match-per-dir order mirrors pi's own loader (AGENTS.md wins over CLAUDE.md).
+const CONTEXT_FILENAMES = ["AGENTS.md", "AGENTS.MD", "CLAUDE.md", "CLAUDE.MD"];
+
+// Directory names we never descend into / load context from.
+const JUNK_DIRS = new Set([
+	"node_modules",
+	".git",
+	".venv",
+	"venv",
+	"dist",
+	"build",
+	".next",
+	".cache",
+	".yalc",
+	".sisyphus",
+	".crouter",
+]);
+
+interface RuleFile {
+	name: string;
+	paths: string[];
+	body: string;
+}
+
+function realpathOrSelf(p: string): string {
+	try {
+		return fs.realpathSync(p);
+	} catch {
+		return p;
+	}
+}
+
+function isJunkPath(absDir: string): boolean {
+	return absDir.split(path.sep).some((seg) => JUNK_DIRS.has(seg));
+}
+
+// Nearest enclosing git repo root for a path (walk up looking for `.git`).
+function gitRoot(p: string): string | null {
+	let d = p;
+	const root = path.parse(d).root;
+	while (true) {
+		if (fs.existsSync(path.join(d, ".git"))) return d;
+		if (d === root) return null;
+		const parent = path.dirname(d);
+		if (parent === d) return null;
+		d = parent;
+	}
+}
+
+// Display paths relative to the nearest git repo root, else absolute.
+function disp(p: string): string {
+	const root = gitRoot(p);
+	if (!root) return p;
+	const rel = path.relative(root, p);
+	return rel === "" ? "." : rel;
+}
+
+// Escape a value for use inside an XML-ish attribute in the injected block.
+function attr(s: string): string {
+	return s
+		.replace(/&/g, "&")
+		.replace(/"/g, """)
+		.replace(/</g, "&lt;")
+		.replace(/>/g, "&gt;");
+}
+
+const AUTO_CONTEXT_RE = /<auto-loaded-context(?:\s[^>]*)?>\n([\s\S]*?)\n<\/auto-loaded-context>/;
+
+function mergeAutoLoadedContext(items: string[], content: Array<{ type: string; text?: string }>) {
+	const existingText = content.map((block) => block.text ?? "").join("\n");
+	const fresh = items.map((item) => item.trim()).filter((item) => item !== "" && !existingText.includes(item));
+	if (fresh.length === 0) return content;
+	const inner = fresh.join("\n");
+
+	const existingIdx = content.findIndex((block) => typeof block.text === "string" && AUTO_CONTEXT_RE.test(block.text));
+	if (existingIdx !== -1) {
+		return content.map((block, idx) => {
+			if (idx !== existingIdx || typeof block.text !== "string") return block;
+			return {
+				...block,
+				text: block.text.replace(AUTO_CONTEXT_RE, (_whole, current: string) => {
+					const trimmed = String(current).trim();
+					return `<auto-loaded-context>\n${inner}${trimmed === "" ? "" : `\n${trimmed}`}\n</auto-loaded-context>`;
+				}),
+			};
+		});
+	}
+
+	return [{ type: "text" as const, text: `<auto-loaded-context>\n${inner}\n</auto-loaded-context>` }, ...content];
+}
+
+function firstContextFile(dir: string): string | null {
+	for (const name of CONTEXT_FILENAMES) {
+		const fp = path.join(dir, name);
+		if (fs.existsSync(fp) && fs.statSync(fp).isFile()) return fp;
+	}
+	return null;
+}
+
+function findMarkdown(dir: string): string[] {
+	const out: string[] = [];
+	let entries: fs.Dirent[];
+	try {
+		entries = fs.readdirSync(dir, { withFileTypes: true });
+	} catch {
+		return out;
+	}
+	for (const e of entries) {
+		const fp = path.join(dir, e.name);
+		if (e.isDirectory()) out.push(...findMarkdown(fp));
+		else if (e.isFile() && e.name.endsWith(".md")) out.push(fp);
+	}
+	return out;
+}
+
+// Minimal frontmatter parse: pulls `name` and the `paths:` list. Avoids a YAML dep.
+function parseRule(filePath: string): RuleFile {
+	let raw = "";
+	try {
+		raw = fs.readFileSync(filePath, "utf-8");
+	} catch {
+		return { name: path.basename(filePath, ".md"), paths: [], body: "" };
+	}
+	const fm = raw.match(/^---\n([\s\S]*?)\n---\n?([\s\S]*)$/);
+	if (!fm) return { name: path.basename(filePath, ".md"), paths: [], body: raw };
+
+	const [, front, body] = fm;
+	const lines = front.split("\n");
+	let name = path.basename(filePath, ".md");
+	const paths: string[] = [];
+	let inPaths = false;
+
+	const clean = (s: string) => s.trim().replace(/^["']|["']$/g, "");
+	for (const line of lines) {
+		const nameMatch = line.match(/^name:\s*(.+)$/);
+		if (nameMatch) {
+			name = clean(nameMatch[1]);
+			inPaths = false;
+			continue;
+		}
+		const pathsInline = line.match(/^paths:\s*(.*)$/);
+		if (pathsInline) {
+			const rest = pathsInline[1].trim();
+			if (rest === "" || rest === "[]") {
+				inPaths = true; // YAML list form follows on subsequent lines
+			} else {
+				// Inline form: a single glob or a comma/space-separated list,
+				// optionally wrapped in [ ... ].
+				inPaths = false;
+				for (const part of rest.replace(/^\[|\]$/g, "").split(/[,]/)) {
+					const g = clean(part);
+					if (g) paths.push(g);
+				}
+			}
+			continue;
+		}
+		if (inPaths) {
+			const item = line.match(/^\s*-\s*(.+)$/);
+			if (item) {
+				paths.push(clean(item[1]));
+				continue;
+			}
+			if (/^\S/.test(line)) inPaths = false; // dedented to next key
+		}
+	}
+	return { name, paths, body: body.trim() };
+}
+
+function ruleMatches(absFile: string, baseDir: string, globs: string[]): boolean {
+	if (globs.length === 0) return true; // unconditional rule
+	const rel = path.relative(baseDir, absFile);
+	return globs.some((g) => {
+		try {
+			return path.matchesGlob(rel, g) || path.matchesGlob(absFile, g);
+		} catch {
+			return false;
+		}
+	});
+}
+
+export default function nestedContext(pi: ExtensionAPI) {
+	const seen = new Set<string>();
+
+	// Seed `seen` with everything pi already loaded at startup: the global
+	// agent file plus every CLAUDE.md/AGENTS.md on the cwd ancestor chain.
+	pi.on("session_start", async (_event, ctx) => {
+		const globalDir = path.join(os.homedir(), ".pi", "agent");
+		const globalCtx = firstContextFile(globalDir);
+		if (globalCtx) seen.add(realpathOrSelf(globalCtx));
+
+		let dir = path.resolve(ctx.cwd);
+		const root = path.parse(dir).root;
+		while (true) {
+			const cf = firstContextFile(dir);
+			if (cf) seen.add(realpathOrSelf(cf));
+			if (dir === root) break;
+			const parent = path.dirname(dir);
+			if (parent === dir) break;
+			dir = parent;
+		}
+	});
+
+	pi.on("tool_result", async (event, ctx) => {
+		if (event.toolName !== "read") return;
+		if (event.isError) return;
+
+		const rawPath = (event.input as { path?: string; file_path?: string })?.path
+			?? (event.input as { file_path?: string })?.file_path;
+		if (!rawPath) return;
+
+		const cwd = path.resolve(ctx.cwd);
+		// The model often passes a leading ~ ; pi's read tool expands it but
+		// event.input keeps the raw form, so expand it ourselves before resolving.
+		const expanded = rawPath.startsWith("~")
+			? path.join(os.homedir(), rawPath.slice(1))
+			: rawPath;
+		const absFile = realpathOrSelf(path.resolve(cwd, expanded));
+
+		// Anchor to the FILE's own location, not the session cwd: walk its parent
+		// chain up to the home directory (or filesystem root if outside home).
+		const home = os.homedir();
+		const fsRoot = path.parse(absFile).root;
+
+		// If the agent read a context/rule file directly, mark it loaded so we
+		// never re-inject it later, and don't append it to its own read.
+		seen.add(absFile);
+
+		type Block = { order: number; text: string };
+		const blocks: Block[] = [];
+
+		let dir = path.dirname(absFile);
+		let depth = 0;
+		while (true) {
+			if (!isJunkPath(dir)) {
+				// 1) Directory context file.
+				const cf = firstContextFile(dir);
+				if (cf) {
+					const real = realpathOrSelf(cf);
+					if (!seen.has(real)) {
+						seen.add(real);
+						try {
+							const content = fs.readFileSync(cf, "utf-8").trim();
+							blocks.push({
+								order: depth,
+								text:
+									`<project-guidance src="${attr(disp(cf))}" scope="${attr(`${disp(dir)}/`)}">\n` +
+									`${content}\n` +
+									`</project-guidance>`,
+							});
+						} catch {
+							/* unreadable; skip */
+						}
+					}
+				}
+
+				// 2) .claude/rules for this directory.
+				const rulesDir = path.join(dir, ".claude", "rules");
+				for (const rf of findMarkdown(rulesDir)) {
+					// Skip stray context files living inside a rules dir; they are not rules.
+					if (CONTEXT_FILENAMES.includes(path.basename(rf))) continue;
+					const real = realpathOrSelf(rf);
+					if (seen.has(real)) continue;
+					const rule = parseRule(rf);
+					if (!ruleMatches(absFile, dir, rule.paths)) continue; // may match on a later read
+					seen.add(real);
+					blocks.push({
+						order: depth,
+						text:
+							`<rule name="${attr(rule.name)}" src="${attr(disp(rf))}">\n` +
+							`${rule.body}\n` +
+							`</rule>`,
+					});
+				}
+			}
+
+			if (dir === home || dir === fsRoot) break;
+			const parent = path.dirname(dir);
+			if (parent === dir) break;
+			dir = parent;
+			depth += 1;
+		}
+
+		if (blocks.length === 0) return;
+
+		// Outermost-first, so the most specific (nearest) guidance reads last/closest
+		// to the file content that follows it.
+		blocks.sort((a, b) => b.order - a.order);
+		const merged = mergeAutoLoadedContext(blocks.map((b) => b.text), event.content);
+		if (merged === event.content) return;
+
+		if (ctx.hasUI) {
+			ctx.ui.notify(`Loaded ${blocks.length} nested context file(s)`, "info");
+		}
+
+		// Prepend or merge, so the governing guidance appears before the file output.
+		return { content: merged };
+	});
+}