@cratis/pi 0.0.1 → 2.0.2

package/package/corpus/harnesses/pi/extensions/cratis-hooks/index.ts

@@ -0,0 +1,213 @@
+/**
+ * Cratis enforcement hooks for the Pi coding agent.
+ *
+ * The corpus enforcement scripts under `.cratis/ai/hooks/scripts/` are the single source of truth and
+ * are wired into Claude Code via `.claude/settings.json`. Pi has no markdown/JSON hook format —
+ * lifecycle enforcement is done in an extension — so this bridge subscribes to the equivalent Pi
+ * events and drives the SAME scripts, synthesizing the Claude hook JSON they read on stdin:
+ *
+ *   Claude PreToolUse  (Write|Edit)  →  Pi `tool_call`      →  cratis-guard-writes.sh  (exit 2 = block)
+ *   Claude PostToolUse (Write|Edit)  →  Pi `tool_result`    →  cratis-pattern-scan.sh  (advisory context)
+ *   Claude Stop                       →  Pi `agent_settled`  →  cratis-quality-gate.sh  (exit 2 = keep going)
+ *
+ * Nothing here duplicates corpus content: it is adapter machinery, the Pi peer of the Claude
+ * `hooks` block in `.claude/settings.json`. Every environment escape hatch the scripts honor
+ * (CRATIS_HOOKS_ALLOW_PROTECTED_WRITES, CRATIS_HOOKS_SKIP_SCAN, CRATIS_HOOKS_SKIP_GATE, …) still
+ * works because the scripts are executed unchanged.
+ */
+
+import { spawn } from "node:child_process";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+const extensionPath = fileURLToPath(import.meta.url);
+const bundledCorpusRoot = path.resolve(path.dirname(extensionPath), "..", "..", "..", "..");
+const isPackagedExtension = extensionPath.includes(`${path.sep}package${path.sep}corpus${path.sep}`);
+
+interface ScriptRun {
+	code: number;
+	stdout: string;
+	stderr: string;
+	/** The script could not be executed at all, as opposed to running and deciding. */
+	failed?: boolean;
+}
+
+/**
+ * Run a corpus hook script, feeding `stdinJson` on stdin. Never throws.
+ *
+ * `failed` separates "the script ran and returned a verdict" from "the script never ran", which
+ * the exit code alone cannot express: bash exits 127 for a missing script, and a script that
+ * fails to spawn produces no code at all. Both used to surface as `code: 0` — indistinguishable
+ * from a deliberate allow — so a hook that was absent or unrunnable silently permitted the very
+ * writes it exists to refuse. Callers decide what to do with `failed`; this function only reports
+ * it honestly.
+ */
+function runScript(script: string, stdinJson: string, cwd: string, signal?: AbortSignal): Promise<ScriptRun> {
+	return new Promise<ScriptRun>((resolve) => {
+		let proc: ReturnType<typeof spawn>;
+		try {
+			proc = spawn("bash", [script], { cwd, stdio: ["pipe", "pipe", "pipe"] });
+		} catch (error) {
+			resolve({ code: 127, stdout: "", stderr: String(error), failed: true });
+			return;
+		}
+		let stdout = "";
+		let stderr = "";
+		proc.stdout?.on("data", (d) => (stdout += d.toString()));
+		proc.stderr?.on("data", (d) => (stderr += d.toString()));
+		proc.on("error", (error) => resolve({ code: 127, stdout, stderr: stderr || String(error), failed: true }));
+		proc.on("close", (code) => resolve({ code: code ?? 0, stdout, stderr, failed: code === 127 }));
+		if (signal) {
+			const kill = () => proc.kill("SIGTERM");
+			if (signal.aborted) kill();
+			else signal.addEventListener("abort", kill, { once: true });
+		}
+		try {
+			proc.stdin?.write(stdinJson);
+			proc.stdin?.end();
+		} catch {
+			/* ignore */
+		}
+	});
+}
+
+/** file_path + written content, extracted from Pi's write/edit tool inputs. */
+function writeTarget(toolName: string, input: any): { filePath?: string; content?: string; newString?: string } {
+	const filePath = input?.path ?? input?.file_path;
+	if (toolName === "write") return { filePath, content: typeof input?.content === "string" ? input.content : undefined };
+	if (toolName === "edit") {
+		const edits = Array.isArray(input?.edits) ? input.edits : [];
+		const newString = edits.map((e: any) => (typeof e?.newText === "string" ? e.newText : "")).join("\n");
+		return { filePath, newString: newString || undefined };
+	}
+	return { filePath };
+}
+
+/**
+ * Whether a hook script is installed at all.
+ *
+ * A repository that ships no hook scripts is a supported configuration — the corpus scripts
+ * themselves degrade to a silent no-op when `jq` is missing, on the stated principle that a hook
+ * must never break a session. So an absent script is not an error and is not enforced.
+ *
+ * The dangerous case is the other one: the script is present, so this repository clearly intends
+ * the guard to run, but it cannot be executed. That is a broken guard rather than an absent one,
+ * and it is the case that must never be mistaken for permission.
+ */
+function isInstalled(script: string): boolean {
+	try {
+		return fs.statSync(script).isFile();
+	} catch {
+		return false;
+	}
+}
+
+export default function (pi: ExtensionAPI) {
+	if (isPackagedExtension && fs.existsSync(path.join(process.cwd(), ".cratis", "ai.manifest.json"))) return;
+	const managedScriptsDir = path.join(process.cwd(), ".cratis", "ai", "hooks", "scripts");
+	const scriptsDir = fs.existsSync(managedScriptsDir) ? managedScriptsDir : path.join(bundledCorpusRoot, "hooks", "scripts");
+	const guardWrites = path.join(scriptsDir, "cratis-guard-writes.sh");
+	const patternScan = path.join(scriptsDir, "cratis-pattern-scan.sh");
+	const qualityGate = path.join(scriptsDir, "cratis-quality-gate.sh");
+
+	// Mirrors Claude's `stop_hook_active`: true only while the model is continuing because the
+	// gate already blocked once this user turn, so the gate never blocks twice in a row (no loop).
+	let gateActive = false;
+	pi.on("input", async (event) => {
+		if (event.source !== "extension") gateActive = false; // a fresh user turn resets the guard
+	});
+
+	// ── PreToolUse → guard writes (blocking) ──
+	pi.on("tool_call", async (event, ctx) => {
+		if (event.toolName !== "write" && event.toolName !== "edit") return;
+		const { filePath, content, newString } = writeTarget(event.toolName, (event as any).input);
+		if (!filePath) return;
+		if (!isInstalled(guardWrites)) return; // no guard installed in this repository - nothing to enforce
+		const payload = JSON.stringify({ cwd: ctx.cwd, tool_input: { file_path: filePath, content, new_string: newString } });
+		const run = await runScript(guardWrites, payload, ctx.cwd, ctx.signal);
+
+		// The guard is installed but could not run. Allowing here would mean the one case the guard
+		// exists to catch - a protected write - passes silently precisely because the guard is broken.
+		// Block instead, and say why, so a broken guard is loud rather than permissive.
+		if (run.failed) {
+			return {
+				block: true,
+				reason:
+					`cratis-guard-writes is installed at ${guardWrites} but could not be run, so this write cannot be checked.` +
+					`${run.stderr.trim() ? `\n\n${run.stderr.trim()}` : ""}` +
+					"\n\nFix the script (or remove it if this repository is not meant to enforce write guards) and retry.",
+			};
+		}
+		if (run.code === 2) return { block: true, reason: run.stderr.trim() || "Blocked by cratis-guard-writes." };
+	});
+
+	// ── PostToolUse → deterministic pattern scan (advisory; injects reminders the model sees) ──
+	pi.on("tool_result", async (event, ctx) => {
+		if (event.toolName !== "write" && event.toolName !== "edit") return;
+		if (event.isError) return;
+		const { filePath } = writeTarget(event.toolName, (event as any).input);
+		if (!filePath) return;
+		if (!isInstalled(patternScan)) return;
+		const payload = JSON.stringify({
+			cwd: ctx.cwd,
+			session_id: ctx.sessionManager.getSessionId?.() ?? "nosession",
+			tool_input: { file_path: filePath },
+		});
+		const run = await runScript(patternScan, payload, ctx.cwd, ctx.signal);
+
+		// Advisory, not a gate: a broken pattern scan must not fail a write that already succeeded.
+		// It is still surfaced rather than swallowed, because a scan that silently stops running
+		// looks exactly like a scan that finds nothing.
+		if (run.failed) {
+			const existing = Array.isArray(event.content) ? event.content : [];
+			return {
+				content: [
+					...existing,
+					{
+						type: "text",
+						text: `\n\n[cratis-hooks] cratis-pattern-scan is installed but could not be run, so no pattern checks were applied to this edit.`,
+					},
+				],
+			};
+		}
+		if (run.code !== 0 || !run.stdout.trim()) return;
+		let reminder = "";
+		try {
+			reminder = JSON.parse(run.stdout)?.hookSpecificOutput?.additionalContext ?? "";
+		} catch {
+			reminder = "";
+		}
+		if (!reminder.trim()) return;
+		const existing = Array.isArray(event.content) ? event.content : [];
+		return { content: [...existing, { type: "text", text: `\n\n[cratis-hooks]\n${reminder.trim()}` }] };
+	});
+
+	// ── Stop → quality gate (re-runs the gates the change touched; keeps the model going on failure) ──
+	pi.on("agent_settled", async (_event, ctx) => {
+		if (!isInstalled(qualityGate)) return;
+		const payload = JSON.stringify({
+			session_id: ctx.sessionManager.getSessionId?.() ?? "nosession",
+			stop_hook_active: gateActive,
+		});
+		const run = await runScript(qualityGate, payload, ctx.cwd);
+
+		// A gate that cannot run has not passed. Say so rather than letting the turn end quietly,
+		// but only once per user turn, on the same re-entry guard a real gate failure uses.
+		if (run.failed && !gateActive) {
+			gateActive = true;
+			pi.sendUserMessage(
+				`The Cratis quality gate is installed at ${qualityGate} but could not be run, so nothing was verified this turn.` +
+					`${run.stderr.trim() ? `\n\n${run.stderr.trim()}` : ""}`,
+				{ deliverAs: "followUp" },
+			);
+			return;
+		}
+		if (run.code === 2 && !gateActive) {
+			gateActive = true; // don't block again until the next user turn resets it
+			const message = run.stderr.trim() || "A Cratis quality gate failed. Fix it and re-run the gate.";
+			pi.sendUserMessage(message, { deliverAs: "followUp" });
+		}
+	});
+}

package/package/corpus/harnesses/pi/extensions/cratis-rules/index.ts

@@ -0,0 +1,27 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
+
+const corpusRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..', '..', '..', '..');
+
+/** Loads task-specific rules from the managed corpus. AGENTS.md already supplies general.md. */
+export function managedRules(cwd: string): string {
+    const managedRoot = join(cwd, '.cratis', 'ai', 'rules');
+    const rulesRoot = existsSync(managedRoot) ? managedRoot : join(corpusRoot, 'rules');
+    return readdirSync(rulesRoot, { recursive: true, encoding: 'utf8' })
+        .filter((entry): entry is string => entry.endsWith('.md') && entry !== 'general.md')
+        .sort()
+        .map(entry => readFileSync(join(rulesRoot, entry), 'utf8'))
+        .join('\n\n');
+}
+
+/** Adds every task-specific managed Cratis rule to Pi without requiring the @cratis/pi package. */
+export default function (pi: ExtensionAPI): void {
+    pi.on('before_agent_start', (event, context) => ({
+        systemPrompt: `${event.systemPrompt}\n\n${managedRules(context.cwd)}`,
+    }));
+}

package/package/corpus/harnesses/pi/extensions/package.json

@@ -0,0 +1,4 @@
+{
+  "private": true,
+  "type": "module"
+}

package/package/corpus/harnesses/pi/extensions/subagent/agents.ts

@@ -0,0 +1,167 @@
+/**
+ * Agent discovery + format normalization for the Cratis subagent tool.
+ *
+ * The agent definitions are the SINGLE-SOURCE corpus files under `.cratis/ai/agents/*.md`,
+ * surfaced to Pi through symlink adapters in `.pi/agents/*.md`. Those files are written
+ * in the Claude/Copilot shape (Title-Case `name`, a YAML-list `tools:` using Claude tool
+ * names such as `Read`/`Glob`/`Bash`, and a `model:` id). Pi's built-in tools are the
+ * lowercase set `read, write, edit, bash, grep, find, ls`, so this module NORMALIZES the
+ * shared shape to Pi semantics — the adapter layer absorbs the tool difference, exactly
+ * like every other adapter in this corpus, so `.pi/agents/*.md` can stay pure symlinks.
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+import { CONFIG_DIR_NAME, getAgentDir, parseFrontmatter } from "@earendil-works/pi-coding-agent";
+
+const corpusAgentsDir = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..", "..", "..", "agents");
+
+export type AgentScope = "user" | "project" | "both";
+
+export interface AgentConfig {
+	name: string;
+	description: string;
+	tools?: string[];
+	model?: string;
+	systemPrompt: string;
+	source: "package" | "user" | "project";
+	filePath: string;
+}
+
+export interface AgentDiscoveryResult {
+	agents: AgentConfig[];
+	projectAgentsDir: string | null;
+}
+
+type AgentFrontmatter = {
+	name?: unknown;
+	description?: unknown;
+	tools?: unknown;
+	model?: unknown;
+};
+
+/**
+ * Map a Claude/Copilot tool name onto Pi's built-in tool name.
+ *
+ * Pi built-ins: read, write, edit, bash, grep, find, ls. The corpus agents use the
+ * Claude vocabulary (Read/Write/Edit/Bash/Grep/Glob + orchestration tools Agent/Skill/
+ * TodoWrite). `Glob` is Pi's `find`; the orchestration tools have no Pi built-in and are
+ * dropped (Pi has no separate Agent/Skill/Todo tool — subagent nesting and skills are
+ * reached differently). An unknown name is dropped rather than passed through, so a stray
+ * value can never disable Pi's tool allowlist by naming a tool that does not exist.
+ */
+const TOOL_NAME_MAP: Record<string, string | null> = {
+	read: "read",
+	write: "write",
+	edit: "edit",
+	multiedit: "edit",
+	bash: "bash",
+	grep: "grep",
+	find: "find",
+	glob: "find",
+	ls: "ls",
+	// No Pi built-in equivalent — dropped:
+	agent: null,
+	task: null,
+	skill: null,
+	todowrite: null,
+	webfetch: null,
+	websearch: null,
+};
+
+/**
+ * Normalize a frontmatter `tools` value to a de-duplicated list of Pi tool names.
+ * Accepts both YAML spellings in use (`tools: [Read, Bash]` and `tools: Read, Bash`).
+ * Returns `undefined` when nothing maps, so the subagent inherits Pi's full default
+ * toolset rather than being launched with an empty allowlist.
+ */
+export function normalizeTools(value: unknown): string[] | undefined {
+	const raw = Array.isArray(value) ? value : typeof value === "string" ? value.split(",") : [];
+	const mapped = raw
+		.filter((t): t is string => typeof t === "string")
+		.map((t) => t.trim().toLowerCase())
+		.filter(Boolean)
+		.map((t) => (t in TOOL_NAME_MAP ? TOOL_NAME_MAP[t] : null))
+		.filter((t): t is string => typeof t === "string");
+	const deduped = Array.from(new Set(mapped));
+	return deduped.length > 0 ? deduped : undefined;
+}
+
+function loadAgentsFromDir(dir: string, source: "package" | "user" | "project"): AgentConfig[] {
+	const agents: AgentConfig[] = [];
+	if (!fs.existsSync(dir)) return agents;
+
+	let entries: fs.Dirent[];
+	try {
+		entries = fs.readdirSync(dir, { withFileTypes: true });
+	} catch {
+		return agents;
+	}
+
+	for (const entry of entries) {
+		if (!entry.name.endsWith(".md")) continue;
+		// Follow symlinks: the corpus adapters in .pi/agents are symlinks into .cratis/ai/agents.
+		if (!entry.isFile() && !entry.isSymbolicLink()) continue;
+
+		const filePath = path.join(dir, entry.name);
+		let content: string;
+		try {
+			content = fs.readFileSync(filePath, "utf-8");
+		} catch {
+			continue;
+		}
+
+		const { frontmatter, body } = parseFrontmatter<AgentFrontmatter>(content);
+		if (typeof frontmatter.name !== "string" || typeof frontmatter.description !== "string") continue;
+
+		agents.push({
+			name: frontmatter.name,
+			description: frontmatter.description,
+			tools: normalizeTools(frontmatter.tools),
+			model: typeof frontmatter.model === "string" ? frontmatter.model.trim() : undefined,
+			systemPrompt: body,
+			source,
+			filePath,
+		});
+	}
+
+	return agents;
+}
+
+function isDirectory(p: string): boolean {
+	try {
+		return fs.statSync(p).isDirectory();
+	} catch {
+		return false;
+	}
+}
+
+/** Nearest `<ancestor>/.pi/agents` from `cwd` up to the filesystem root. */
+function findNearestProjectAgentsDir(cwd: string): string | null {
+	let currentDir = cwd;
+	while (true) {
+		const candidate = path.join(currentDir, CONFIG_DIR_NAME, "agents");
+		if (isDirectory(candidate)) return candidate;
+		const parentDir = path.dirname(currentDir);
+		if (parentDir === currentDir) return null;
+		currentDir = parentDir;
+	}
+}
+
+export function discoverAgents(cwd: string, scope: AgentScope): AgentDiscoveryResult {
+	const userDir = path.join(getAgentDir(), "agents");
+	const projectAgentsDir = findNearestProjectAgentsDir(cwd);
+
+	const packageAgents = scope === "project" ? [] : loadAgentsFromDir(corpusAgentsDir, "package");
+	const userAgents = scope === "project" ? [] : loadAgentsFromDir(userDir, "user");
+	const projectAgents = scope === "user" || !projectAgentsDir ? [] : loadAgentsFromDir(projectAgentsDir, "project");
+
+	// User agents override package agents; project agents override both.
+	const agentMap = new Map<string, AgentConfig>();
+	for (const agent of packageAgents) agentMap.set(agent.name, agent);
+	for (const agent of userAgents) agentMap.set(agent.name, agent);
+	for (const agent of projectAgents) agentMap.set(agent.name, agent);
+
+	return { agents: Array.from(agentMap.values()), projectAgentsDir };
+}