@crouton-kit/crouter 0.3.33 → 0.3.35

package/dist/builtin-pi-packages/pi-crtr-extensions/extensions/frontmatter-rules/index.ts

@@ -0,0 +1,442 @@
+/**
+ * Frontmatter Rules
+ *
+ * Conditional "pi rules" that load only when the agent reads a markdown file
+ * whose YAML frontmatter satisfies a rule's `when:` condition. This is the
+ * inverse of nested-context's `.claude/rules` path-glob matching: here the
+ * *content* of the read document (its frontmatter) decides which rules apply,
+ * not the document's path.
+ *
+ * Rule files live in `.pi/rules/*.md` (walked up the read file's ancestor
+ * chain, so a project-root rules dir governs everything beneath it) plus a
+ * global `~/.pi/rules/`. Each rule declares a `when:` condition in its own
+ * frontmatter; the rule body (markdown after the frontmatter) is what gets
+ * injected ahead of the file contents in the read result.
+ *
+ * Rule file shape:
+ *   ---
+ *   name: Security review rules        # optional, defaults to filename
+ *   description: ...                   # optional, shown in the injection header
+ *   when:
+ *     tags: { contains: security }     # see "Condition language" below
+ *   ---
+ *   <rule guidance in markdown>
+ *
+ * Condition language (evaluated against the READ file's frontmatter object):
+ *   A `when:` block is a map of <field> -> <matcher>, AND-ed across fields.
+ *   `field` may be dotted to reach nested values (e.g. meta.owner).
+ *
+ *   Matcher forms:
+ *     scalar (string/number/bool/null)
+ *         field === value, OR (if the field is an array) the array includes value
+ *     array  [a, b, c]
+ *         membership/intersection: field is one of these, OR the field array
+ *         shares any element with these
+ *     object { <op>: <arg>, ... }   (multiple ops AND together)
+ *         eq          equals (scalar or array-includes)
+ *         ne          not eq
+ *         in          [..] — field (or any of its array elements) is in the list
+ *         nin         not in
+ *         exists      true|false — field is present / absent
+ *         contains    field array includes this value
+ *         containsAll [..] — field array includes all of these
+ *         containsAny [..] — field array includes any of these
+ *         matches     regex string, case-sensitive (tests String(field); arrays: any)
+ *         imatches    regex string, case-insensitive
+ *         gt gte lt lte   numeric comparison
+ *
+ *   Combinators (reserved keys at any condition level):
+ *     all: [ {..}, {..} ]   every sub-condition true (AND)
+ *     any: [ {..}, {..} ]   at least one true (OR)
+ *     not: { .. }           sub-condition false
+ *   Sibling field matchers next to combinators are AND-ed in.
+ *
+ *   A rule with no `when:` is inert (never auto-loads) — keeps reads quiet.
+ *
+ * Notes:
+ *   - Only .md/.mdx/.markdown reads are considered, and only if they have
+ *     frontmatter that parses to a YAML object.
+ *   - Each rule file is injected at most once per session (deduped by realpath),
+ *     so reading many matching documents won't re-spam the same rule.
+ *
+ * Install: directory lives in ~/.pi/agent/extensions/ (global) or a project's
+ * .pi/extensions/. Run `npm install` here once so `yaml` resolves.
+ */
+
+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";
+import { parse as parseYaml } from "yaml";
+
+const MARKDOWN_EXTS = new Set([".md", ".mdx", ".markdown"]);
+
+const JUNK_DIRS = new Set([
+	"node_modules",
+	".git",
+	".venv",
+	"venv",
+	"dist",
+	"build",
+	".next",
+	".cache",
+	".yalc",
+	".sisyphus",
+	".crouter",
+]);
+
+type Frontmatter = Record<string, unknown>;
+
+interface Rule {
+	name: string;
+	description?: string;
+	when?: unknown;
+	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, "&amp;")
+		.replace(/"/g, "&quot;")
+		.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];
+}
+
+// Pull the leading `--- ... ---` YAML block out of a markdown file.
+function extractFrontmatter(raw: string): Frontmatter | null {
+	const m = raw.match(/^\uFEFF?---\r?\n([\s\S]*?)\r?\n---[ \t]*(?:\r?\n|$)/);
+	if (!m) return null;
+	try {
+		const parsed = parseYaml(m[1]);
+		if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+			return parsed as Frontmatter;
+		}
+	} catch {
+		/* malformed frontmatter — treat as none */
+	}
+	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() && MARKDOWN_EXTS.has(path.extname(e.name).toLowerCase())) out.push(fp);
+	}
+	return out;
+}
+
+function parseRuleFile(filePath: string): Rule {
+	const fallback = (): Rule => ({ name: path.basename(filePath).replace(/\.[^.]+$/, ""), body: "" });
+	let raw = "";
+	try {
+		raw = fs.readFileSync(filePath, "utf-8");
+	} catch {
+		return fallback();
+	}
+	const m = raw.match(/^\uFEFF?---\r?\n([\s\S]*?)\r?\n---[ \t]*(?:\r?\n([\s\S]*))?$/);
+	if (!m) {
+		// No frontmatter: whole file is body, but inert (no `when`).
+		return { name: path.basename(filePath).replace(/\.[^.]+$/, ""), body: raw.trim() };
+	}
+	let front: Frontmatter = {};
+	try {
+		const parsed = parseYaml(m[1]);
+		if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) front = parsed as Frontmatter;
+	} catch {
+		/* malformed rule frontmatter */
+	}
+	const name = typeof front.name === "string" && front.name.trim()
+		? front.name.trim()
+		: path.basename(filePath).replace(/\.[^.]+$/, "");
+	const description = typeof front.description === "string" ? front.description.trim() : undefined;
+	return { name, description, when: front.when, body: (m[2] ?? "").trim() };
+}
+
+// ---- Condition language ----------------------------------------------------
+
+function asArray(v: unknown): unknown[] {
+	if (Array.isArray(v)) return v;
+	if (v === undefined) return [];
+	return [v];
+}
+
+// Scalar equality with light, predictable coercion: exact match, or
+// string/number cross-compare so `version: 2` matches frontmatter "2".
+function scalarEq(a: unknown, b: unknown): boolean {
+	if (a === b) return true;
+	if (
+		(typeof a === "number" || typeof a === "string") &&
+		(typeof b === "number" || typeof b === "string")
+	) {
+		return String(a) === String(b);
+	}
+	return false;
+}
+
+// Resolve a (possibly dotted) field path against the frontmatter object.
+function getField(fm: unknown, key: string): unknown {
+	if (fm && typeof fm === "object" && key in (fm as Record<string, unknown>)) {
+		return (fm as Record<string, unknown>)[key];
+	}
+	if (!key.includes(".")) return undefined;
+	let cur: unknown = fm;
+	for (const part of key.split(".")) {
+		if (cur == null || typeof cur !== "object") return undefined;
+		cur = (cur as Record<string, unknown>)[part];
+	}
+	return cur;
+}
+
+function toRegExp(arg: unknown, flags: string): RegExp | null {
+	if (typeof arg !== "string") return null;
+	try {
+		return new RegExp(arg, flags);
+	} catch {
+		return null;
+	}
+}
+
+function applyOp(op: string, value: unknown, arg: unknown): boolean {
+	const vals = asArray(value);
+	switch (op) {
+		case "eq":
+			return Array.isArray(value) ? value.some((v) => scalarEq(v, arg)) : scalarEq(value, arg);
+		case "ne":
+			return !applyOp("eq", value, arg);
+		case "in":
+			return asArray(arg).some((a) => vals.some((v) => scalarEq(v, a)));
+		case "nin":
+			return !applyOp("in", value, arg);
+		case "exists":
+			return (value !== undefined) === (arg !== false);
+		case "contains":
+			return vals.some((v) => scalarEq(v, arg));
+		case "containsAll":
+			return asArray(arg).every((a) => vals.some((v) => scalarEq(v, a)));
+		case "containsAny":
+			return asArray(arg).some((a) => vals.some((v) => scalarEq(v, a)));
+		case "matches":
+		case "imatches": {
+			const re = toRegExp(arg, op === "imatches" ? "i" : "");
+			if (!re) return false;
+			return vals.some((v) => typeof v === "string" || typeof v === "number" ? re.test(String(v)) : false);
+		}
+		case "gt":
+		case "gte":
+		case "lt":
+		case "lte": {
+			const n = Number(value);
+			const t = Number(arg);
+			if (Number.isNaN(n) || Number.isNaN(t)) return false;
+			if (op === "gt") return n > t;
+			if (op === "gte") return n >= t;
+			if (op === "lt") return n < t;
+			return n <= t;
+		}
+		default:
+			return false; // unknown op never matches
+	}
+}
+
+function matchField(value: unknown, matcher: unknown): boolean {
+	if (matcher === null || ["string", "number", "boolean"].includes(typeof matcher)) {
+		if (Array.isArray(value)) return value.some((v) => scalarEq(v, matcher));
+		return scalarEq(value, matcher);
+	}
+	if (Array.isArray(matcher)) {
+		const vals = asArray(value);
+		return matcher.some((m) => vals.some((v) => scalarEq(v, m)));
+	}
+	if (matcher && typeof matcher === "object") {
+		return Object.entries(matcher as Record<string, unknown>).every(([op, arg]) =>
+			applyOp(op, value, arg),
+		);
+	}
+	return false;
+}
+
+function evalCondition(cond: unknown, fm: Frontmatter): boolean {
+	if (cond == null) return false;
+	if (Array.isArray(cond)) return cond.every((sub) => evalCondition(sub, fm));
+	if (typeof cond !== "object") return false;
+	const c = cond as Record<string, unknown>;
+	const hasCombinator = "all" in c || "any" in c || "not" in c;
+	if (hasCombinator) {
+		let ok = true;
+		if ("all" in c) ok = ok && asArray(c.all).every((s) => evalCondition(s, fm));
+		if ("any" in c) ok = ok && asArray(c.any).some((s) => evalCondition(s, fm));
+		if ("not" in c) ok = ok && !evalCondition(c.not, fm);
+		for (const k of Object.keys(c)) {
+			if (k === "all" || k === "any" || k === "not") continue;
+			ok = ok && matchField(getField(fm, k), c[k]);
+		}
+		return ok;
+	}
+	const keys = Object.keys(c);
+	if (keys.length === 0) return false; // empty `when:` is inert, not match-all
+	return keys.every((k) => matchField(getField(fm, k), c[k]));
+}
+
+// ---- Extension -------------------------------------------------------------
+
+export default function frontmatterRules(pi: ExtensionAPI) {
+	const seen = new Set<string>();
+
+	pi.on("session_start", async () => {
+		seen.clear();
+	});
+
+	pi.on("tool_result", async (event, ctx) => {
+		if (event.toolName !== "read" || 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;
+		if (!MARKDOWN_EXTS.has(path.extname(rawPath).toLowerCase())) return;
+
+		const cwd = path.resolve(ctx.cwd);
+		const expanded = rawPath.startsWith("~") ? path.join(os.homedir(), rawPath.slice(1)) : rawPath;
+		const absFile = realpathOrSelf(path.resolve(cwd, expanded));
+
+		// Read from disk (not event.content) so frontmatter is clean and
+		// unaffected by the read tool's formatting/truncation.
+		let raw = "";
+		try {
+			raw = fs.readFileSync(absFile, "utf-8");
+		} catch {
+			return;
+		}
+		const fm = extractFrontmatter(raw);
+		if (!fm) return; // no frontmatter -> nothing to match
+
+		// Collect candidate rule directories: each ancestor's `.pi/rules`, plus
+		// a global `~/.pi/rules`. Dedup directories before scanning.
+		const home = os.homedir();
+		const fsRoot = path.parse(absFile).root;
+		const ruleDirs: { dir: string; order: number }[] = [];
+		const seenDirs = new Set<string>();
+		const pushDir = (d: string, order: number) => {
+			const real = realpathOrSelf(d);
+			if (seenDirs.has(real)) return;
+			seenDirs.add(real);
+			ruleDirs.push({ dir: d, order });
+		};
+
+		let dir = path.dirname(absFile);
+		let depth = 0;
+		while (true) {
+			if (!isJunkPath(dir)) pushDir(path.join(dir, ".pi", "rules"), depth);
+			if (dir === home || dir === fsRoot) break;
+			const parent = path.dirname(dir);
+			if (parent === dir) break;
+			dir = parent;
+			depth += 1;
+		}
+		// Global rules rank as the outermost (highest order = farthest).
+		pushDir(path.join(home, ".pi", "rules"), depth + 1);
+
+		type Block = { order: number; text: string };
+		const blocks: Block[] = [];
+
+		for (const { dir: rulesDir, order } of ruleDirs) {
+			for (const rf of findMarkdown(rulesDir)) {
+				const real = realpathOrSelf(rf);
+				if (seen.has(real)) continue;
+				const rule = parseRuleFile(rf);
+				if (rule.when === undefined) continue; // inert without a condition
+				if (!evalCondition(rule.when, fm)) continue; // may match a later read
+				seen.add(real);
+				const descAttr = rule.description ? ` description="${attr(rule.description)}"` : "";
+				blocks.push({
+					order,
+					text:
+						`<rule name="${attr(rule.name)}" src="${attr(disp(rf))}"${descAttr}>\n` +
+						`${rule.body}\n` +
+						`</rule>`,
+				});
+			}
+		}
+
+		if (blocks.length === 0) return;
+
+		// Outermost-first so the most specific (nearest) rule reads last/closest
+		// to the file content that follows.
+		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} frontmatter rule(s)`, "info");
+		}
+
+		return { content: merged };
+	});
+}

package/dist/builtin-pi-packages/pi-crtr-extensions/extensions/frontmatter-rules/test.ts

@@ -0,0 +1,119 @@
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import frontmatterRules from "./index.ts";
+
+// ---- Tiny mock harness -----------------------------------------------------
+type Handler = (event: any, ctx: any) => Promise<any>;
+function makePi() {
+	const handlers: Record<string, Handler> = {};
+	const pi: any = { on: (name: string, h: Handler) => (handlers[name] = h) };
+	return { pi, handlers };
+}
+
+const tmp = fs.mkdtempSync(path.join(os.tmpdir(), "fmr-test-"));
+const ctx = { cwd: tmp, hasUI: false };
+
+function rule(rel: string, content: string) {
+	const fp = path.join(tmp, rel);
+	fs.mkdirSync(path.dirname(fp), { recursive: true });
+	fs.writeFileSync(fp, content);
+}
+function doc(rel: string, content: string) {
+	const fp = path.join(tmp, rel);
+	fs.mkdirSync(path.dirname(fp), { recursive: true });
+	fs.writeFileSync(fp, content);
+	return fp;
+}
+
+// Rules at project root .pi/rules
+rule(".pi/rules/security.md", `---\nname: Security review\nwhen:\n  tags: { contains: security }\n---\nDo a threat model.`);
+rule(".pi/rules/spec.md", `---\nwhen:\n  type: spec\n---\nFollow the spec checklist.`);
+rule(".pi/rules/high-prio-api.md", `---\nname: High prio API\nwhen:\n  all:\n    - type: spec\n    - priority: { gte: 3 }\n  any:\n    - { area: api }\n    - { tags: { containsAny: [api, http] } }\n---\nGet API review.`);
+rule(".pi/rules/inert.md", `---\nname: No condition\n---\nThis should never auto-load.`);
+rule(".pi/rules/nested-field.md", `---\nwhen:\n  meta.owner: alice\n---\nPing alice.`);
+rule(".pi/rules/regex.md", `---\nwhen:\n  title: { imatches: "^api[- ]" }\n---\nName matched regex.`);
+// A deeper rules dir that should NOT apply to a file above it
+rule("sub/.pi/rules/deep.md", `---\nwhen:\n  type: spec\n---\nDeep rule.`);
+
+const { pi, handlers } = makePi();
+frontmatterRules(pi);
+
+let pass = 0;
+let fail = 0;
+async function check(name: string, filePath: string, expectRules: string[], notExpect: string[] = [], freshSeen = true) {
+	if (freshSeen) await handlers["session_start"]({}, ctx); // reset dedup
+	const event = {
+		toolName: "read",
+		isError: false,
+		input: { path: filePath },
+		content: [{ type: "text", text: "FILE_BODY" }],
+	};
+	const res = await handlers["tool_result"](event, ctx);
+	const text: string = res?.content?.[0]?.text ?? "";
+	const ok =
+		expectRules.every((r) => text.includes(r)) &&
+		notExpect.every((r) => !text.includes(r)) &&
+		(expectRules.length === 0 ? res === undefined : true);
+	if (ok) {
+		pass++;
+		console.log(`  ok  ${name}`);
+	} else {
+		fail++;
+		console.log(`FAIL  ${name}`);
+		console.log(`      expected: ${JSON.stringify(expectRules)} absent: ${JSON.stringify(notExpect)}`);
+		console.log(`      got:\n${text.split("\n").map((l) => "        " + l).join("\n")}`);
+	}
+}
+
+(async () => {
+	// 1. array `contains` on tags
+	await check("tags contains security", doc("a.md", `---\ntags: [security, infra]\n---\nbody`), ["Security review"], ["spec", "High prio"]);
+
+	// 2. scalar equality on type
+	await check("type spec equality", doc("b.md", `---\ntype: spec\n---\nbody`), ["Follow the spec checklist"], ["Security review"]);
+
+	// 3. combinator all+any with gte and containsAny
+	await check("complex all/any/gte", doc("c.md", `---\ntype: spec\npriority: 4\ntags: [http]\n---\nbody`),
+		["High prio API", "Follow the spec checklist"]);
+
+	// 4. complex should fail when priority too low
+	await check("complex fails low priority", doc("d.md", `---\ntype: spec\npriority: 1\narea: api\n---\nbody`),
+		["Follow the spec checklist"], ["High prio API"]);
+
+	// 5. inert rule never loads; no frontmatter match at all -> undefined result
+	await check("no matching frontmatter -> no injection", doc("e.md", `---\nrandom: value\n---\nbody`), []);
+
+	// 6. nested dotted field
+	await check("nested dotted field", doc("f.md", `---\nmeta:\n  owner: alice\n---\nbody`), ["Ping alice"]);
+
+	// 7. case-insensitive regex
+	await check("imatches regex", doc("g.md", `---\ntitle: "API Gateway"\n---\nbody`), ["Name matched regex"]);
+
+	// 8. file with NO frontmatter -> skip entirely
+	await check("no frontmatter -> skip", doc("h.md", `# just a heading\nno frontmatter`), []);
+
+	// 9. deep rule applies to files in its subtree
+	await check("deep rule in subtree", doc("sub/deep-doc.md", `---\ntype: spec\n---\nbody`),
+		["Deep rule", "Follow the spec checklist"]);
+
+	// 10. deep rule does NOT apply to files above it (file at root)
+	await check("deep rule not above", doc("top.md", `---\ntype: spec\n---\nbody`),
+		["Follow the spec checklist"], ["Deep rule"]);
+
+	// 11. dedup across reads within a session (no fresh seen): second matching read injects nothing
+	await handlers["session_start"]({}, ctx);
+	await check("dedup first read", doc("dq1.md", `---\ntype: spec\n---\nbody`), ["Follow the spec checklist"], [], false);
+	await check("dedup second read (already seen)", doc("dq2.md", `---\ntype: spec\n---\nbody`), [], [], false);
+
+	// 12. non-markdown read ignored
+	const tsEvent = { toolName: "read", isError: false, input: { path: doc("x.ts", "const a=1;") }, content: [{ type: "text", text: "x" }] };
+	await handlers["session_start"]({}, ctx);
+	const tsRes = await handlers["tool_result"](tsEvent, ctx);
+	if (tsRes === undefined) { pass++; console.log("  ok  non-markdown ignored"); }
+	else { fail++; console.log("FAIL  non-markdown ignored"); }
+
+	console.log(`\n${pass} passed, ${fail} failed`);
+	fs.rmSync(tmp, { recursive: true, force: true });
+	process.exit(fail === 0 ? 0 : 1);
+})();