pi-shorthand 0.1.0

package/overlay-macos.ts

@@ -0,0 +1,277 @@
+/**
+ * macOS has no mount namespaces, so for the length of a run:
+ * 1. the repository is renamed to <repo>.pi-base, and an empty directory takes its place;
+ * 2. .git and large ignored directories (node_modules, …) are moved to <repo>.pi-shared and
+ *    symlinked back, so reading them bypasses the overlay (AgentFS copies every file it opens);
+ * 3. AgentFS serves an overlay of the base over NFS, mounted at the repository's path;
+ * 4. the program runs under sandbox-exec, which stops it writing to the base or to .git.
+ * close() puts everything back. <repo>.pi-shared doubles as a lock: another run on the same repository
+ * waits for this one, and if a run crashed part-way, the next one puts everything back first.
+ */
+
+import * as fs from "node:fs/promises";
+import { homedir } from "node:os";
+import * as path from "node:path";
+import { $ } from "bun";
+import type { Overlay } from "./runner.ts";
+
+interface Dirs {
+	repo: string;
+	base: string; // the real files, while the overlay is mounted
+	shared: string; // .git and large ignored directories, while the overlay is mounted
+}
+
+export async function openMacOverlay(repo: string, tempDir: string): Promise<Overlay> {
+	const agentfs = process.env.AGENTFS_BIN ?? Bun.which("agentfs");
+	if (!agentfs) throw new Error("The code tool needs AgentFS: curl -fsSL https://agentfs.ai/install | bash");
+
+	const dirs = { repo, base: `${repo}.pi-base`, shared: `${repo}.pi-shared` };
+	await takeLock(dirs);
+	try {
+		const shared = await moveAside(dirs);
+		const database = await createDatabase(agentfs, dirs.base, tempDir);
+		await serveAndMount(agentfs, database, dirs);
+
+		return {
+			originalDir: dirs.base,
+			writableDir: repo,
+			// The shared entries are symlinks now, which patterns like "node_modules/" don't match.
+			// ._* are the AppleDouble files macOS writes on NFS, where it can't store extended attributes.
+			gitExcludes: ["._*", ...shared.map((entry) => `/${entry}`)],
+			wrap: (command) => ["/usr/bin/sandbox-exec", "-p", sandboxProfile(dirs), ...command],
+			changes: () => changesInDatabase(agentfs, database, dirs),
+			close: () => restore(dirs),
+		};
+	} catch (error) {
+		await restore(dirs);
+		throw error;
+	}
+}
+
+/**
+ * Creating a directory is atomic, so whoever creates <repo>.pi-shared owns the repository until
+ * restore() removes it. Waits while another run is alive; repairs a run that crashed.
+ */
+async function takeLock(dirs: Dirs) {
+	for (let attempt = 0; attempt < 3000; attempt++) {
+		try {
+			await fs.mkdir(dirs.shared);
+			await writeState(dirs, { runnerPid: process.pid, shared: [] });
+			return;
+		} catch (error) {
+			if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
+		}
+		const state = await readState(dirs).catch(() => null);
+		const crashed = state ? !isAlive(state.runnerPid) : await olderThan(dirs.shared, 1000);
+		if (crashed) await restore(dirs);
+		else await Bun.sleep(20);
+	}
+	throw new Error("Another code run on this repository didn't finish within a minute.");
+}
+
+/** Steps 1 and 2. Records what it did in <repo>.pi-shared/state.json, so restore() can undo it. */
+async function moveAside(dirs: Dirs): Promise<string[]> {
+	const shared = await listSharedEntries(dirs.repo);
+	await writeState(dirs, { ...(await readState(dirs)), shared });
+
+	await fs.rename(dirs.repo, dirs.base);
+	await fs.mkdir(dirs.repo);
+	for (const entry of shared) {
+		await fs.mkdir(path.dirname(path.join(dirs.shared, entry)), { recursive: true });
+		await fs.rename(path.join(dirs.base, entry), path.join(dirs.shared, entry));
+		await fs.symlink(path.join(dirs.shared, entry), path.join(dirs.base, entry));
+	}
+	return shared;
+}
+
+/** .git, plus ignored directories (the top-most ones) that don't contain tracked files. */
+async function listSharedEntries(repo: string): Promise<string[]> {
+	const [ignoredOutput, trackedOutput] = await Promise.all([
+		$`git ls-files -z --others --ignored --exclude-standard --directory`.cwd(repo).text(),
+		$`git ls-files -z`.cwd(repo).text(),
+	]);
+	const ignoredDirs = ignoredOutput.split("\0").filter((entry) => entry.endsWith("/"));
+	const tracked = trackedOutput.split("\0");
+
+	const shared = [".git"];
+	for (const dir of ignoredDirs.map((entry) => entry.slice(0, -1)).toSorted()) {
+		const insideShared = shared.some((entry) => dir.startsWith(`${entry}/`));
+		const containsTracked = tracked.some((file) => file.startsWith(`${dir}/`));
+		if (!insideShared && !containsTracked) shared.push(dir);
+	}
+	return shared;
+}
+
+/**
+ * An empty overlay database. `agentfs init` takes ~150 ms, so it runs once per repository to make
+ * a template, and each run gets an instant copy-on-write clone of that.
+ */
+async function createDatabase(agentfs: string, base: string, tempDir: string): Promise<string> {
+	const templateDir = path.join(homedir(), ".cache", "pi-shorthand", Bun.hash(base).toString(16));
+	const templateFiles = path.join(templateDir, ".agentfs"); // where `agentfs init` puts them
+	if (!(await Bun.file(path.join(templateFiles, "template.db")).exists())) {
+		await fs.mkdir(templateDir, { recursive: true });
+		await $`${agentfs} init template --base ${base}`.cwd(templateDir).quiet();
+	}
+
+	await cloneDatabase(templateFiles, "template.db", tempDir, "run.db");
+	return path.join(tempDir, "run.db");
+}
+
+/** Step 3. */
+async function serveAndMount(agentfs: string, database: string, dirs: Dirs) {
+	const port = freePort();
+	const server = Bun.spawn([agentfs, "nfs", database, "--port", String(port)], { stdout: "ignore", stderr: "ignore" });
+	await writeState(dirs, { ...(await readState(dirs)), serverPid: server.pid });
+	await waitForPort(port);
+
+	const options = `locallocks,vers=3,tcp,port=${port},mountport=${port},soft,timeo=100,retrans=5`;
+	await $`/sbin/mount_nfs -o ${options} 127.0.0.1:/ ${dirs.repo}`.quiet();
+}
+
+/** Step 4: allow everything except writing to the original files or to .git. */
+function sandboxProfile(dirs: Dirs): string {
+	return [
+		"(version 1)",
+		"(allow default)",
+		`(deny file-write* (subpath ${JSON.stringify(dirs.base)}))`,
+		`(deny file-write* (subpath ${JSON.stringify(path.join(dirs.shared, ".git"))}))`,
+	].join("\n");
+}
+
+/**
+ * `agentfs diff` lists what's in the overlay (including files that were only read). The server
+ * keeps the database locked, so this diffs a copy-on-write snapshot of it.
+ */
+async function changesInDatabase(agentfs: string, database: string, dirs: Dirs) {
+	const snapshotDir = path.join(path.dirname(database), "snapshot");
+	await cloneDatabase(path.dirname(database), "run.db", snapshotDir, "run.db");
+	const output = await $`${agentfs} diff ${path.join(snapshotDir, "run.db")}`.quiet().text();
+
+	const changes: { file: string; contents: Uint8Array | null }[] = [];
+	for (const line of output.split("\n")) {
+		// e.g. "M f /src/a.ts", "A f /src/new.ts", "D ? /src/old.ts"
+		const match = line.match(/^([AMD]) (\S) \/(.+)$/);
+		if (!match || path.basename(match[3]).startsWith("._")) continue; // AppleDouble files
+		const [, change, type, file] = match;
+
+		if (change !== "D" && type === "f") changes.push({ file, contents: await readFile(path.join(dirs.repo, file)) });
+		if (change === "D") {
+			for (const deleted of await filesUnder(path.join(dirs.base, file))) {
+				changes.push({ file: path.join(file, deleted), contents: null });
+			}
+		}
+	}
+	return changes;
+}
+
+/** The files under a path relative to it: [""] for a file, everything inside for a directory. */
+async function filesUnder(original: string): Promise<string[]> {
+	const stats = await fs.lstat(original).catch(() => null);
+	if (!stats?.isDirectory()) return [""];
+	return fs.readdir(original, { recursive: true });
+}
+
+/** Unmounts, stops the server, renames everything back and releases the lock. */
+async function restore(dirs: Dirs) {
+	if (!(await exists(dirs.shared))) return;
+	const state = await readState(dirs).catch((): State => ({ runnerPid: 0, shared: [] }));
+
+	await $`umount -f ${dirs.repo}`.nothrow().quiet(); // -f: a leftover subprocess may still have files open
+	if (state.serverPid) {
+		try {
+			process.kill(state.serverPid);
+		} catch {
+			// already stopped
+		}
+	}
+
+	if (await exists(dirs.base)) {
+		for (const entry of state.shared) {
+			if (!(await exists(path.join(dirs.shared, entry)))) continue;
+			await fs.rm(path.join(dirs.base, entry), { force: true }); // the symlink
+			await fs.rename(path.join(dirs.shared, entry), path.join(dirs.base, entry));
+		}
+		await fs.rmdir(dirs.repo).catch(() => {}); // the empty mountpoint
+		await fs.rename(dirs.base, dirs.repo);
+	}
+
+	// Never delete <repo>.pi-shared recursively: during a run it holds the real node_modules and .git.
+	await fs.rm(path.join(dirs.shared, "state.json"), { force: true });
+	await removeEmptyDirectories(dirs.shared);
+}
+
+// ── Small helpers ─────────────────────────────────────────────────────────────────
+
+interface State {
+	runnerPid: number;
+	shared: string[];
+	serverPid?: number;
+}
+
+function readState(dirs: Dirs): Promise<State> {
+	return Bun.file(path.join(dirs.shared, "state.json")).json();
+}
+
+async function writeState(dirs: Dirs, state: State) {
+	await Bun.write(path.join(dirs.shared, "state.json"), JSON.stringify(state));
+}
+
+/** Copy-on-write clones a database with its -wal/-shm files, renaming it. */
+async function cloneDatabase(fromDir: string, fromName: string, toDir: string, toName: string) {
+	await fs.mkdir(toDir, { recursive: true });
+	for (const file of await fs.readdir(fromDir)) {
+		if (!file.startsWith(fromName)) continue;
+		await Bun.write(path.join(toDir, file.replace(fromName, toName)), Bun.file(path.join(fromDir, file)));
+	}
+}
+
+async function removeEmptyDirectories(dir: string) {
+	for (const entry of await fs.readdir(dir, { withFileTypes: true })) {
+		if (entry.isDirectory()) await removeEmptyDirectories(path.join(dir, entry.name));
+	}
+	await fs.rmdir(dir); // fails, leaving everything, if it isn't empty
+}
+
+/** A regular file's contents, or null if there's no regular file there. */
+async function readFile(file: string): Promise<Uint8Array | null> {
+	const stats = await fs.lstat(file).catch(() => null);
+	return stats?.isFile() ? Bun.file(file).bytes() : null;
+}
+
+function isAlive(pid: number): boolean {
+	try {
+		process.kill(pid, 0); // signal 0 only checks the process exists
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+async function olderThan(file: string, ms: number): Promise<boolean> {
+	const stats = await fs.stat(file).catch(() => null);
+	return !stats || Date.now() - stats.mtimeMs > ms;
+}
+
+async function exists(file: string): Promise<boolean> {
+	return (await fs.lstat(file).catch(() => null)) !== null;
+}
+
+function freePort(): number {
+	const listener = Bun.listen({ hostname: "127.0.0.1", port: 0, socket: { data() {} } });
+	listener.stop(true);
+	return listener.port;
+}
+
+async function waitForPort(port: number) {
+	for (let attempt = 0; attempt < 1000; attempt++) {
+		try {
+			const socket = await Bun.connect({ hostname: "127.0.0.1", port, socket: { data() {} } });
+			socket.end();
+			return;
+		} catch {
+			await Bun.sleep(2); // not listening yet
+		}
+	}
+	throw new Error("AgentFS's NFS server didn't start.");
+}

package/package.json

@@ -0,0 +1,82 @@
+{
+	"name": "pi-shorthand",
+	"version": "0.1.0",
+	"description": "Pi tool for token-efficient writes: the model makes a whole change with one Bun program, whose writes are held in an overlay and applied only if it succeeds.",
+	"keywords": [
+		"ast-grep",
+		"bun",
+		"code-mode",
+		"gritql",
+		"overlay",
+		"pi",
+		"pi-extension",
+		"pi-package"
+	],
+	"homepage": "https://github.com/sebinsua/pi-shorthand#readme",
+	"bugs": "https://github.com/sebinsua/pi-shorthand/issues",
+	"license": "MIT",
+	"author": "Seb Insua",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/sebinsua/pi-shorthand.git"
+	},
+	"files": [
+		"*.ts",
+		"skills",
+		"README.md"
+	],
+	"type": "module",
+	"scripts": {
+		"test": "bun test",
+		"typecheck": "tsc -p .",
+		"lint": "oxlint --deny-warnings",
+		"format": "oxfmt",
+		"check": "tsc -p . && oxlint --deny-warnings && oxfmt --check",
+		"prepare": "git config core.hooksPath .githooks 2>/dev/null || true"
+	},
+	"dependencies": {
+		"@ast-grep/cli": "^0.45.3",
+		"@ast-grep/napi": "^0.45.3",
+		"@getgrit/cli": "0.1.0-alpha.1743007075",
+		"diff": "^9.0.0"
+	},
+	"devDependencies": {
+		"@earendil-works/pi-ai": "^0.85.1",
+		"@earendil-works/pi-coding-agent": "^0.85.1",
+		"@earendil-works/pi-tui": "^0.85.1",
+		"@types/bun": "^1.4.2",
+		"@types/node": "^26.6.1",
+		"oxfmt": "^0.68.0",
+		"oxlint": "^1.83.0",
+		"typebox": "^1.3.7",
+		"typescript": "^7.0.2"
+	},
+	"peerDependencies": {
+		"@earendil-works/pi-ai": "*",
+		"@earendil-works/pi-coding-agent": "*",
+		"@earendil-works/pi-tui": "*",
+		"typebox": "*"
+	},
+	"peerDependenciesMeta": {
+		"@earendil-works/pi-ai": {
+			"optional": true
+		},
+		"@earendil-works/pi-coding-agent": {
+			"optional": true
+		},
+		"@earendil-works/pi-tui": {
+			"optional": true
+		},
+		"typebox": {
+			"optional": true
+		}
+	},
+	"pi": {
+		"extensions": [
+			"./index.ts"
+		],
+		"skills": [
+			"./skills"
+		]
+	}
+}

package/prelude.ts

@@ -0,0 +1,243 @@
+/**
+ * Preloaded into every `code` program. On top of ordinary Bun and Node it adds these globals:
+ * $ (Bun shell), glob, grep, sg (ast-grep) and grit (GritQL).
+ *
+ * sg is ast-grep's own JavaScript API (@ast-grep/napi: sg.parse, sg.Lang, sg.findInFiles, …) plus two
+ * shortcuts, sg.find and sg.rewrite. Programs can also import "@ast-grep/napi" directly.
+ *
+ * Everything except $ is synchronous: models often call helpers like these without await.
+ * File lists come from git (tracked, plus untracked files that aren't ignored), so node_modules
+ * and build output are left out on every platform.
+ *
+ * Each $ command and helper call is logged to the runner's log (~/.cache/pi-shorthand/runs.jsonl) as it
+ * happens, so `tail -f` shows what a program is doing, including which command it's stuck on.
+ */
+
+import { appendFileSync, existsSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import * as astGrep from "@ast-grep/napi";
+import { Lang, type NapiConfig, parse, type SgNode } from "@ast-grep/napi";
+import { $ as bunShell, Glob } from "bun";
+
+function log(event: string, details: Record<string, unknown>) {
+	const { PI_SHORTHAND_LOG, PI_SHORTHAND_RUN } = process.env;
+	if (!PI_SHORTHAND_LOG) return;
+	appendFileSync(
+		PI_SHORTHAND_LOG,
+		`${JSON.stringify({ time: new Date().toISOString(), run: PI_SHORTHAND_RUN, event, ...details })}\n`,
+	);
+}
+
+/** Runs a helper, logging how long it took and how many results it returned. */
+function logged<T>(helper: string, args: unknown[], run: () => T): T {
+	const startedAt = performance.now();
+	const result = run();
+	const results = Array.isArray(result) ? result.length : result;
+	log("helper", {
+		helper,
+		args: JSON.stringify(args).slice(0, 200),
+		ms: Math.round(performance.now() - startedAt),
+		results,
+	});
+	return result;
+}
+
+/** Bun's shell, logging each command as it starts. */
+const $ = new Proxy(bunShell, {
+	apply(target, thisArg, args: Parameters<typeof bunShell>) {
+		const [strings, ...values] = args;
+		log("command", { command: String.raw({ raw: strings.raw }, ...values).slice(0, 200) });
+		return Reflect.apply(target, thisArg, args);
+	},
+});
+
+/**
+ * Files git sees under a directory that match a glob pattern, relative to the working directory,
+ * sorted. The directory can also be given as { cwd }, as with Bun's Glob.
+ */
+function glob(pattern: string, where: string | { cwd?: string } = "."): string[] {
+	const dir = typeof where === "string" ? where : (where.cwd ?? ".");
+	const output = git(["ls-files", "-z", "--cached", "--others", "--exclude-standard", "--", dir]);
+	const matcher = new Glob(dir === "." ? pattern : `${dir.replace(/\/$/, "")}/${pattern}`);
+	// git still lists a tracked file the program has deleted, so check it's there.
+	const files = [...new Set(output.split("\0"))].filter((file) => file && matcher.match(file) && existsSync(file));
+	return files.toSorted();
+}
+
+/**
+ * Search files git sees. A string is matched literally; a RegExp is matched as a Perl-compatible
+ * regular expression, which is close to JavaScript's syntax.
+ */
+function grep(pattern: string | RegExp, paths: string | string[] = ".") {
+	let flags: string[];
+	if (typeof pattern === "string") {
+		flags = ["-F", "-e", pattern];
+	} else {
+		flags = ["-P", "-e", pattern.source];
+		if (pattern.flags.includes("i")) flags.push("-i");
+	}
+	const output = git(["grep", "-n", "--null", "--untracked", "-I", ...flags, "--", ...[paths].flat()]);
+
+	const matches = [];
+	for (const line of output.split("\n")) {
+		if (line === "") continue;
+		const [file, lineNumber, text] = line.split("\0");
+		matches.push({ file, line: Number(lineNumber), text });
+	}
+	return matches;
+}
+
+function git(args: string[]): string {
+	return Bun.spawnSync(["git", ...args], { stderr: "ignore" }).stdout.toString();
+}
+
+// ── ast-grep ──────────────────────────────────────────────────────────────────────
+// Patterns use ast-grep syntax: $X matches one node, $$$X matches zero or more.
+
+const LANGUAGES: Record<string, Lang> = {
+	ts: Lang.TypeScript,
+	mts: Lang.TypeScript,
+	cts: Lang.TypeScript,
+	tsx: Lang.Tsx,
+	jsx: Lang.Tsx,
+	js: Lang.JavaScript,
+	mjs: Lang.JavaScript,
+	cjs: Lang.JavaScript,
+	html: Lang.Html,
+	css: Lang.Css,
+};
+
+/**
+ * A match. Its captures are in `vars` and also directly on it (capture names are uppercase, so they
+ * can't clash with the other fields): both `m.vars.ARGS` and `m.ARGS` work.
+ */
+type SgMatch = {
+	file: string;
+	line: number;
+	text: string;
+	vars: Record<string, string>; // captured metavariables, e.g. vars.ARGS for $$$ARGS
+	node: SgNode;
+} & Record<string, unknown>;
+
+/**
+ * The JS/TS files to search. `files` is a file, a directory (the JS/TS files in it), a glob, or a list
+ * of any of those. Warns if there are none, since that's almost always a mistake.
+ */
+function sourceFiles(helper: string, files: string | string[]): string[] {
+	const found = [files].flat().flatMap((entry) => {
+		const stats = statSync(entry, { throwIfNoEntry: false });
+		if (stats?.isFile()) return [entry];
+		if (stats?.isDirectory()) return glob("**/*.{ts,mts,cts,tsx,js,mjs,cjs,jsx}", entry);
+		return glob(entry);
+	});
+	const parseable = found.filter((file) => LANGUAGES[file.split(".").pop()!]);
+	if (parseable.length === 0) console.error(`warning: ${helper} found no JS/TS files in ${JSON.stringify(files)}`);
+	return parseable;
+}
+
+function find(pattern: string | NapiConfig, files: string | string[] = "."): SgMatch[] {
+	const matches: SgMatch[] = [];
+	for (const file of sourceFiles("sg.find", files)) {
+		const parsed = parseFile(file);
+		if (!parsed) continue;
+		for (const node of parsed.root.findAll(pattern)) matches.push(toMatch(file, node, parsed.source, pattern));
+	}
+	return matches;
+}
+
+/**
+ * Rewrite matches in place. `replacement` is either a template using the same $X / $$$X
+ * metavariables, or a function returning the new text. A function returning anything other than a
+ * string (undefined, null, false) leaves that match alone, so `(m) => cond && \`…\`` works.
+ * Returns the number of matches rewritten.
+ */
+function rewrite(
+	pattern: string | NapiConfig,
+	replacement: string | ((match: SgMatch) => unknown),
+	files: string | string[] = ".",
+): number {
+	let count = 0;
+	for (const file of sourceFiles("sg.rewrite", files)) {
+		const parsed = parseFile(file);
+		if (!parsed) continue;
+
+		const edits = [];
+		for (const node of parsed.root.findAll(pattern)) {
+			const match = toMatch(file, node, parsed.source, pattern);
+			const newText =
+				typeof replacement === "function"
+					? replacement(match)
+					: replacement.replace(/(\$\$\$|\$)([A-Z_][A-Z0-9_]*)/g, (text, _, name) => match.vars[name] ?? text);
+			if (typeof newText === "string") edits.push(node.replace(newText)); // anything else (undefined, null, false) leaves it
+		}
+		if (edits.length === 0) continue;
+
+		writeFileSync(file, parsed.root.commitEdits(edits));
+		count += edits.length;
+	}
+	// Almost always a mistake, e.g. a bare name as the pattern only matches plain identifiers, not properties.
+	if (count === 0) console.error(`warning: sg.rewrite matched nothing for ${JSON.stringify(pattern)}`);
+	return count;
+}
+
+/** A JS/TS/HTML/CSS file's source and syntax tree, or null for other files. */
+function parseFile(file: string) {
+	const lang = LANGUAGES[file.split(".").pop()!];
+	if (!lang) return null;
+	const source = readFileSync(file, "utf8");
+	return { source, root: parse(lang, source).root() };
+}
+
+function toMatch(file: string, node: SgNode, source: string, pattern: string | NapiConfig): SgMatch {
+	const vars: Record<string, string> = {};
+	for (const [, dollars, name] of JSON.stringify(pattern).matchAll(/(\$\$\$|\$)([A-Z_][A-Z0-9_]*)/g)) {
+		if (dollars === "$$$") {
+			// Slice the original source so separators and formatting are kept ("a, b" rather than "a,b").
+			const nodes = node.getMultipleMatches(name);
+			const first = nodes[0];
+			const last = nodes[nodes.length - 1];
+			vars[name] = first && last ? source.slice(first.range().start.index, last.range().end.index) : "";
+		} else {
+			const captured = node.getMatch(name);
+			if (captured) vars[name] = captured.text();
+		}
+	}
+	return { ...vars, file, line: node.range().start.line + 1, text: node.text(), vars, node };
+}
+
+// ── GritQL ────────────────────────────────────────────────────────────────────────
+
+/**
+ * Apply a GritQL pattern in place (or only match it, with dryRun). Returns the files it matched.
+ * e.g. grit("`console.log($x)` => `logger.info($x)`", "src")
+ */
+function grit(pattern: string, paths: string | string[] = ".", options: { lang?: string; dryRun?: boolean } = {}) {
+	const flags = ["--force", "--jsonl"];
+	if (options.dryRun) flags.push("--dry-run");
+	if (options.lang) flags.push("--language", options.lang);
+
+	const result = Bun.spawnSync(["grit", "apply", ...flags, pattern, ...[paths].flat()]);
+
+	const files = [];
+	for (const line of result.stdout.toString().split("\n")) {
+		if (!line.startsWith("{")) continue;
+		const record = JSON.parse(line);
+		const matched = record.original ?? record; // rewrites nest the match under "original"
+		if (matched.sourceFile) files.push({ file: matched.sourceFile, matches: matched.ranges.length });
+	}
+	if (result.exitCode !== 0 && files.length === 0) {
+		throw new Error(`grit failed: ${result.stderr.toString().trim()}`);
+	}
+	return files;
+}
+
+Object.assign(globalThis, {
+	$,
+	glob: (...args: Parameters<typeof glob>) => logged("glob", args, () => glob(...args)),
+	grep: (...args: Parameters<typeof grep>) => logged("grep", args, () => grep(...args)),
+	sg: {
+		...astGrep,
+		find: (...args: Parameters<typeof find>) => logged("sg.find", args, () => find(...args)),
+		rewrite: (...args: Parameters<typeof rewrite>) => logged("sg.rewrite", args, () => rewrite(...args)),
+	},
+	grit: (...args: Parameters<typeof grit>) => logged("grit", args, () => grit(...args)),
+});