pi-shorthand 0.1.0 → 0.3.0

package/README.md

@@ -1,11 +1,13 @@
 # pi-shorthand
 
-A [Pi](https://github.com/earendil-works/pi) tool for token-efficient writes. The model writes a whole
-change as one small Bun program, in shorthand, instead of calling `read`, `edit` and `bash` over
-and over: fewer tokens, and fewer round trips.
+![A code call in Pi: the verdict, then the diff it applied, then the program's output](https://raw.githubusercontent.com/sebinsua/pi-shorthand/main/docs/screenshot.png?v=2)
 
-The program sees your repo as normal, but its writes are held back. If it succeeds, they're applied
-and the model gets the diff. If it fails, nothing changes.
+A [Pi](https://github.com/earendil-works/pi) tool for editing repositories with Bun programs.
+The model can combine ordinary JavaScript, text edits and structural transformations in one call.
+
+The program sees your repo as normal, but its writes are held back. By default, they're applied only
+if the program succeeds and destination files are unchanged, and the model gets the diff.
+The program performs the edit; tests, type-checks and other verification run separately afterward.
 
 ## Install
 
@@ -15,8 +17,10 @@ pi install npm:pi-shorthand
 
 Or from GitHub (`pi install git:github.com/sebinsua/pi-shorthand`), or a local clone: `npm install`, then `pi install /path/to/pi-shorthand`.
 
+A project install (`pi install -l`) only loads once you trust the project: Pi asks, or run `pi --approve`.
+
 You also need Bun, git, and either [bubblewrap](https://github.com/containers/bubblewrap) 0.9+
-(Linux) or [AgentFS](https://github.com/tursodatabase/agentfs) (macOS:
+(Linux) or [AgentFS](https://github.com/tursodatabase/agentfs) and `clang` (macOS:
 `curl -fsSL https://agentfs.ai/install | bash`).
 
 ## What a program can use
@@ -24,28 +28,55 @@ You also need Bun, git, and either [bubblewrap](https://github.com/containers/bu
 Anything in Bun or Node, plus these globals (no imports):
 
 ```ts
-await $`bun test src/api.test.ts`; // Bun's shell (the only async one)
+await $`git ls-files`.text(); // Bun's shell (the only async one)
 glob("src/**/*.ts"); // → ["src/a.ts", …]
 grep("oldApi(", "src"); // → [{ file, line, text }, …]
 sg.find("oldApi($$$ARGS)", "src"); // ast-grep search
 sg.rewrite("oldApi($$$ARGS)", "newApi($$$ARGS)", "src");
+sg.insert("initialize();", { before: sg.one("run();", "src/app.ts") });
+sg.move(sg.one("function helper() { $$$BODY }", "src/old.ts"), { endOf: sg.file("src/new.ts") });
+sg.remove(sg.one("obsolete();", "src/app.ts"));
 sg.parse(sg.Lang.TypeScript, source); // ast-grep's own API (or import from "@ast-grep/napi")
 grit("`console.log($x)` => `logger.info($x)`", "src");
 ```
 
+`sg.find`, `sg.one`, `sg.rewrite` and `grit` also accept `sg.file("src/app.ts")` directly, including
+in arrays mixed with paths. Search reads the file's current contents. Missing targets are valid insertion
+destinations but cannot be searched. An explicit target can select an ignored file inside the workspace;
+the tool still only applies Git-visible changes.
+
+[api.d.ts](api.d.ts) exposes the actual injected helper types for editor completion and external TypeScript
+checking of editing programs. Include it in the program's TypeScript project (or reference
+`pi-shorthand/api` via `compilerOptions.types` when installed as a package). This supplies types, not runtime
+globals. Bun execution does not automatically type-check programs or run application verification.
+
 ## Options
 
-- `rollback`: `"all"` (default) applies nothing if the program fails. `"file"` keeps the files it
-  finished writing.
+- `title`: a short description shown with the call (required).
+- `rollback`: `"all"` (default) applies nothing if the program fails. After a timeout, `"file"`
+  keeps changed files that were no longer open for writing if writer inspection succeeds. Other
+  failures apply nothing because open writers cannot be identified after the process exits.
 - `timeout`: seconds before the program is killed. Default 2.
 
 ## Good to know
 
 - Only files git tracks, or would track, are applied.
-- On macOS your repo is briefly swapped for the overlay while a program runs (about 150 ms), so your
-  editor may notice. On Linux nothing outside the program sees it (about 15 ms).
+- Successful edits are formatted with detected installed project tools (Prettier, oxfmt, Biome, Ruff,
+  Black, gofmt or rustfmt) before the final diff. Ambiguous setups are skipped; formatter failures warn
+  without discarding completed edits. Set `PI_SHORTHAND_FORMAT=0` to disable. No project config is required.
+- Each run snapshots the checkout first; reflinks make that cheap where supported, while other
+  filesystems copy its contents and use corresponding temporary space. On macOS the program runs at
+  a private AgentFS mount, so use paths relative to its working directory for repository files.
+- Runs against the same checkout are serialized. If another process edits a destination while a run
+  is in progress, shorthand checks it again immediately before replacing it and reports a conflict.
+  A non-cooperating writer can still race the final filesystem rename or removal itself.
 - To try it with only `read` and `code`: `pi --tools read,code`.
-- To watch runs as they happen, including each command a program starts: `tail -f ~/.cache/pi-shorthand/runs.jsonl`.
+- Run history is stored in `~/.cache/pi-shorthand/runs.jsonl` with directory mode `0700` and file
+  mode `0600`. It records timestamps, opaque run IDs, lifecycle events, exit status, durations,
+  counts, helper names, and shell executable names. It does not record programs, output, errors,
+  arguments, repository paths, file paths, or diffs. The log rotates at 1 MiB and expires after
+  seven days. Set `PI_SHORTHAND_HISTORY=0` to disable it. To watch enabled history:
+  `tail -f ~/.cache/pi-shorthand/runs.jsonl`.
 
 ## Developing
 
@@ -55,6 +86,8 @@ hook runs it; `npm run format` fixes formatting.
 `npm test` runs the tests against real overlays (it needs AgentFS on macOS, bubblewrap on Linux).
 `test/linux.sh` runs them on Linux in Docker.
 
-`bun e2e/run.ts --repo <path or git URL> --task "…" --setup baseline|code|read-code --check "…"` runs Pi
-with a real model on a fresh copy of a repo and summarises what it did (time, turns, tool calls,
-tokens, whether the check passed).
+`bun e2e/suite.ts` previews the local benchmark suite without calling a model. Add `--execute` to run it.
+The [comparison harness](e2e/README.md) supports stock, optional and replacement editing tools, controlled
+documentation/skills, independent task checks, saved final changes and session reports.
+`bun e2e/run.ts --repo <path or git URL> --task "…" --setups baseline,replace,code --check "…"` runs Pi
+with a real model on fresh copies of your own repository.

package/api.d.ts

@@ -0,0 +1,14 @@
+/** Types for programs executed by the code tool. Type-only: this does not install runtime globals. */
+import type { ShorthandGlobals } from "./prelude.ts";
+
+declare global {
+	const $: ShorthandGlobals["$"];
+	const edit: ShorthandGlobals["edit"];
+	const glob: ShorthandGlobals["glob"];
+	const grep: ShorthandGlobals["grep"];
+	const sg: ShorthandGlobals["sg"];
+	const grit: ShorthandGlobals["grit"];
+}
+
+export type { RewriteResult } from "./prelude.ts";
+export type { ShorthandGlobals };

package/display.ts

@@ -7,9 +7,14 @@
  * on failure the output, then what would have changed; for an exploration, just the output.
  */
 
-import { keyHint, renderDiff, type Theme } from "@earendil-works/pi-coding-agent";
+import { getLanguageFromPath, highlightCode, keyHint, renderDiff, type Theme } from "@earendil-works/pi-coding-agent";
 import type { FileChange, RunResult } from "./runner.ts";
 
+type ToolBackground = "toolSuccessBg" | "toolErrorBg";
+
+const ANSI_CUBE_VALUES = [0, 95, 135, 175, 215, 255];
+const ANSI_GRAY_VALUES = Array.from({ length: 24 }, (_, index) => 8 + index * 10);
+
 const OUTPUT_PREVIEW_LINES = 5; // like Pi's bash tool
 const INLINE_DIFF_LINES = 40; // a longer diff collapses to a list of its files…
 const LISTED_FILES = 8; // …showing this many, then "and N more files"
@@ -21,6 +26,19 @@ export function callLine(args: { title?: string; timeout?: number; rollback?: st
 	return `${theme.fg("toolTitle", theme.bold("code"))} ${args.title ?? ""}${suffix ? theme.fg("muted", ` (${suffix})`) : ""}`;
 }
 
+/** Text to show when a completed tool result has no structured RunResult details. */
+export function unstructuredResultText(content: readonly unknown[]): string {
+	const text = content
+		.flatMap((block) =>
+			typeof block === "object" && block !== null && "type" in block && block.type === "text" && "text" in block
+				? [String(block.text)]
+				: [],
+		)
+		.join("\n")
+		.trim();
+	return text || "Code failed without result details";
+}
+
 /** Lines that belong to the verdict line above them. */
 function indent(line: string): string {
 	return `  ${line}`;
@@ -43,21 +61,28 @@ export function resultLines(run: RunResult, expanded: boolean, theme: Theme): st
 	const error = run.exitCode !== 0 && !run.timedOut ? errorMessage(run.output) : undefined;
 	if (error) lines.push(indent(theme.fg("error", error)));
 	if (error && run.errorLine) lines.push(indent(theme.fg("muted", shorten(run.errorLine, 88))));
+	for (const file of run.conflicts) lines.push(indent(theme.fg("error", `changed while running: ${file}`)));
 	// A command still running is what it was stuck on; otherwise the last step it logged is a clue.
 	for (const command of run.stillRunning) lines.push(indent(theme.fg("warning", `stuck on $ ${command}`)));
 	if (run.timedOut && run.stillRunning.length === 0 && run.lastStep) {
 		lines.push(indent(theme.fg("warning", `last step: ${run.lastStep}`)));
 	}
 	for (const file of run.rolledBack) {
-		lines.push(indent(theme.fg("warning", `rolled back ${file}: half-written when the program was killed`)));
+		const reason = run.writerInspectionFailed
+			? "open writers could not be inspected at the timeout"
+			: run.timedOut
+				? "half-written when the program was killed"
+				: "finished writes unknown after the program exited";
+		lines.push(indent(theme.fg("warning", `rolled back ${file}: ${reason}`)));
 	}
 	for (const warning of [...run.warnings, ...printedWarnings]) lines.push(indent(theme.fg("warning", `⚠ ${warning}`)));
 
 	// The sections, each after a blank line.
 	const sections: string[][] = [];
-	if (applied.length > 0) sections.push(diffLines(applied, expanded, theme));
+	const background: ToolBackground = run.exitCode === 0 && run.conflicts.length === 0 ? "toolSuccessBg" : "toolErrorBg";
+	if (applied.length > 0) sections.push(diffLines(applied, expanded, theme, background));
 	if (output && (expanded || !error)) sections.push(outputLines(output, expanded, run.changes.length > 0, theme));
-	if (notApplied.length > 0) sections.push(notAppliedLines(notApplied, expanded, theme));
+	if (notApplied.length > 0) sections.push(notAppliedLines(notApplied, expanded, theme, background));
 	for (const section of sections) lines.push("", ...section);
 	return lines;
 }
@@ -69,6 +94,15 @@ function verdict(run: RunResult, applied: FileChange[], theme: Theme): string {
 	const failure = run.timedOut ? `Timed out after ${run.timeoutMs / 1000}s` : "Failed";
 	const exit = run.timedOut ? "" : muted(` · exit ${run.exitCode}`);
 
+	if (run.conflicts.length > 0) {
+		const program = run.timedOut
+			? ` · timed out after ${run.timeoutMs / 1000}s`
+			: run.exitCode
+				? ` · exit ${run.exitCode}`
+				: "";
+		const application = applied.length === 0 ? "nothing applied" : `${fileCount(applied)} applied`;
+		return theme.fg("error", `✕ Conflict · ${application}${program}`) + took;
+	}
 	if (run.exitCode === 0 && run.changes.length === 0) return theme.fg("success", "✓ No changes") + took;
 	if (run.exitCode === 0) {
 		return theme.fg("success", `✓ Applied ${fileCount(applied)}`) + ` · ${stats(applied, theme)}` + took;
@@ -104,8 +138,8 @@ function outputLines(output: string, expanded: boolean, labelled: boolean, theme
 }
 
 /** Each file's diff under its name, in Pi's own diff style. A long diff collapses to a list of files. */
-function diffLines(changes: FileChange[], expanded: boolean, theme: Theme): string[] {
-	const files = changes.map((change) => [fileLine(change, theme), ...renderDiff(toPiDiff(change.patch)).split("\n")]);
+function diffLines(changes: FileChange[], expanded: boolean, theme: Theme, background: ToolBackground): string[] {
+	const files = changes.map((change) => [fileLine(change, theme), ...renderFileDiff(change, theme, background)]);
 	const total = files.reduce((sum, file) => sum + file.length, 0);
 	if (!expanded && total > INLINE_DIFF_LINES) {
 		return [...fileList(changes, theme), theme.fg("muted", `(${keyHint("app.tools.expand", "to see the diff")})`)];
@@ -117,9 +151,152 @@ function diffLines(changes: FileChange[], expanded: boolean, theme: Theme): stri
 	return [...lines.slice(0, EXPANDED_DIFF_LINES), theme.fg("muted", `… ${more} more lines of diff`)];
 }
 
-function notAppliedLines(changes: FileChange[], expanded: boolean, theme: Theme): string[] {
+function renderFileDiff(change: FileChange, theme: Theme, background: ToolBackground): string[] {
+	const diff = toPiDiff(change.patch);
+	const language = getLanguageFromPath(change.path);
+	if (!language || diff === " binary file changed") return renderDiff(diff).split("\n");
+
+	const rendered: string[] = [];
+	let hunk: string[] = [];
+	const flush = () => {
+		if (hunk.length > 0) rendered.push(...renderSyntaxHunk(hunk, language, theme, background));
+		hunk = [];
+	};
+	for (const line of diff.split("\n")) {
+		if (/^\s+\.\.\.$/.test(line)) {
+			flush();
+			rendered.push(theme.fg("toolDiffContext", line));
+		} else {
+			hunk.push(line);
+		}
+	}
+	flush();
+	return rendered;
+}
+
+function renderSyntaxHunk(lines: string[], language: string, theme: Theme, background: ToolBackground): string[] {
+	const parsed = lines.map((line) => {
+		const match = line.match(/^([+\- ])(\s*\d*) (.*)$/);
+		return match ? { prefix: match[1], number: match[2], code: match[3] } : undefined;
+	});
+	const oldLines = parsed.flatMap((line) => (line && line.prefix !== "+" ? [line.code] : []));
+	const newLines = parsed.flatMap((line) => (line && line.prefix !== "-" ? [line.code] : []));
+	const oldHighlighted = highlightCode(oldLines.join("\n"), language);
+	const newHighlighted = highlightCode(newLines.join("\n"), language);
+	let oldIndex = 0;
+	let newIndex = 0;
+
+	return parsed.map((line, index) => {
+		if (!line) return theme.fg("toolDiffContext", lines[index]);
+		if (line.prefix === "-") {
+			const content = theme.fg("toolDiffRemoved", `-${line.number} `) + oldHighlighted[oldIndex++];
+			return tintedDiffLine(content, "toolDiffRemoved", background, theme);
+		}
+		if (line.prefix === "+") {
+			const content = theme.fg("toolDiffAdded", `+${line.number} `) + newHighlighted[newIndex++];
+			return tintedDiffLine(content, "toolDiffAdded", background, theme);
+		}
+		oldIndex++;
+		return theme.fg("toolDiffContext", ` ${line.number} `) + newHighlighted[newIndex++];
+	});
+}
+
+function tintedDiffLine(
+	line: string,
+	changeColor: "toolDiffAdded" | "toolDiffRemoved",
+	baseBackground: ToolBackground,
+	theme: Theme,
+): string {
+	const base = ansiRgb(theme.getBgAnsi(baseBackground));
+	const change = ansiRgb(theme.getFgAnsi(changeColor));
+	if (!base || !change) return line;
+	const [red, green, blue] = base.map((channel, index) => Math.round(channel * 0.86 + change[index] * 0.14));
+	const background =
+		theme.getColorMode() === "truecolor"
+			? `\x1b[48;2;${red};${green};${blue}m`
+			: `\x1b[48;5;${ansi256(red, green, blue)}m`;
+	return `${background}${line}${theme.getBgAnsi(baseBackground)}`;
+}
+
+function ansiRgb(code: string): [number, number, number] | undefined {
+	const truecolor = code.match(/\[(?:38|48);2;(\d+);(\d+);(\d+)m/);
+	if (truecolor) return [Number(truecolor[1]), Number(truecolor[2]), Number(truecolor[3])];
+	const indexed = code.match(/\[(?:38|48);5;(\d+)m/);
+	return indexed ? rgbFromAnsi256(Number(indexed[1])) : undefined;
+}
+
+function rgbFromAnsi256(index: number): [number, number, number] | undefined {
+	if (index < 0 || index > 255) return undefined;
+	if (index < 16) {
+		const palette = [
+			[0, 0, 0],
+			[128, 0, 0],
+			[0, 128, 0],
+			[128, 128, 0],
+			[0, 0, 128],
+			[128, 0, 128],
+			[0, 128, 128],
+			[192, 192, 192],
+			[128, 128, 128],
+			[255, 0, 0],
+			[0, 255, 0],
+			[255, 255, 0],
+			[0, 0, 255],
+			[255, 0, 255],
+			[0, 255, 255],
+			[255, 255, 255],
+		] as const;
+		return [...palette[index]];
+	}
+	if (index >= 232) {
+		const gray = 8 + (index - 232) * 10;
+		return [gray, gray, gray];
+	}
+	const cube = index - 16;
+	return [
+		ansiCubeChannel(Math.floor(cube / 36)),
+		ansiCubeChannel(Math.floor((cube % 36) / 6)),
+		ansiCubeChannel(cube % 6),
+	];
+}
+
+function ansiCubeChannel(value: number): number {
+	return value === 0 ? 0 : 55 + value * 40;
+}
+
+function ansi256(red: number, green: number, blue: number): number {
+	const [redIndex, greenIndex, blueIndex] = [red, green, blue].map((channel) =>
+		closestIndex(channel, ANSI_CUBE_VALUES),
+	);
+	const cube = [ANSI_CUBE_VALUES[redIndex], ANSI_CUBE_VALUES[greenIndex], ANSI_CUBE_VALUES[blueIndex]];
+	const cubeIndex = 16 + 36 * redIndex + 6 * greenIndex + blueIndex;
+	const cubeDistance = colorDistance([red, green, blue], cube);
+
+	const luminance = Math.round(0.299 * red + 0.587 * green + 0.114 * blue);
+	const grayOffset = closestIndex(luminance, ANSI_GRAY_VALUES);
+	const gray = ANSI_GRAY_VALUES[grayOffset];
+	const grayDistance = colorDistance([red, green, blue], [gray, gray, gray]);
+	const spread = Math.max(red, green, blue) - Math.min(red, green, blue);
+	return spread < 10 && grayDistance < cubeDistance ? 232 + grayOffset : cubeIndex;
+}
+
+function closestIndex(value: number, choices: number[]): number {
+	let closest = 0;
+	for (let index = 1; index < choices.length; index++) {
+		if (Math.abs(value - choices[index]) < Math.abs(value - choices[closest])) closest = index;
+	}
+	return closest;
+}
+
+function colorDistance(first: number[], second: number[]): number {
+	return (
+		(first[0] - second[0]) ** 2 * 0.299 + (first[1] - second[1]) ** 2 * 0.587 + (first[2] - second[2]) ** 2 * 0.114
+	);
+}
+
+function notAppliedLines(changes: FileChange[], expanded: boolean, theme: Theme, background: ToolBackground): string[] {
 	const heading = theme.fg("muted", `Would have changed ${fileCount(changes)} · `) + stats(changes, theme);
-	if (expanded) return [heading, "", ...diffLines(changes, true, theme)];
+	if (expanded) return [heading, "", ...diffLines(changes, true, theme, background)];
 	return [heading + theme.fg("muted", ` (${keyHint("app.tools.expand", "to see the diff")})`)];
 }
 
@@ -133,7 +310,19 @@ function fileList(changes: FileChange[], theme: Theme): string[] {
 /** e.g. "src/a.ts +3 −1", or "src/new.ts (new) +12 −0" */
 function fileLine(change: FileChange, theme: Theme): string {
 	const kind = change.kind === "modified" ? "" : theme.fg("muted", change.kind === "added" ? " (new)" : " (deleted)");
-	return `${theme.fg("accent", change.path)}${kind} ${stats([change], theme)}`;
+	const metadata = fileMetadataSummary(change);
+	return `${theme.fg("accent", change.path)}${kind}${metadata ? theme.fg("muted", ` (${metadata})`) : ""} ${stats([change], theme)}`;
+}
+
+export function fileMetadataSummary(change: FileChange): string {
+	if (change.beforeType && change.afterType && change.beforeType !== change.afterType) {
+		return `${change.beforeType} → ${change.afterType}`;
+	}
+	if (change.afterType === "symlink" && change.beforeType !== "symlink") return "symlink";
+	if (change.beforeMode !== undefined && change.afterMode !== undefined && change.beforeMode !== change.afterMode) {
+		return `${change.beforeMode.toString(8)} → ${change.afterMode.toString(8)}`;
+	}
+	return "";
 }
 
 /** "+6 −2", in the diff colours. */

package/format.ts

@@ -0,0 +1,148 @@
+/** Best-effort formatting using existing project tools. Runs inside the editing workspace. */
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, extname, join, relative, resolve } from "node:path";
+
+type Command = { name: string; executable: string; args: string[]; cwd: string };
+
+function text(file: string): string {
+	try {
+		return readFileSync(file, "utf8");
+	} catch {
+		return "";
+	}
+}
+
+function directories(start: string, root: string): string[] {
+	const result = [];
+	for (let dir = start; ; dir = dirname(dir)) {
+		result.push(dir);
+		if (dir === root || dirname(dir) === dir) return result;
+	}
+}
+
+export function formatterFor(file: string, root: string): Command | null {
+	root = resolve(root);
+	const extension = extname(file);
+	const js = /\.(?:[cm]?[jt]sx?|jsonc?|css|scss|less|html|vue|svelte|mdx?|ya?ml|graphql)$/i.test(extension);
+	for (const cwd of directories(dirname(resolve(root, file)), root)) {
+		const has = (...names: string[]) => names.some((name) => existsSync(join(cwd, name)));
+		let name: string | undefined;
+		let args: string[] = [];
+		if (js) {
+			let pkg: {
+				scripts?: Record<string, string>;
+				dependencies?: Record<string, string>;
+				devDependencies?: Record<string, string>;
+				prettier?: unknown;
+			};
+			try {
+				pkg = JSON.parse(text(join(cwd, "package.json")) || "{}");
+			} catch {
+				return null;
+			}
+			const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+			const choices = [
+				...(deps.prettier ||
+				pkg.prettier !== undefined ||
+				has(
+					".prettierrc",
+					".prettierrc.json",
+					".prettierrc.yaml",
+					".prettierrc.yml",
+					".prettierrc.js",
+					".prettierrc.cjs",
+					".prettierrc.mjs",
+					"prettier.config.js",
+					"prettier.config.cjs",
+					"prettier.config.mjs",
+					"prettier.config.ts",
+				)
+					? ["prettier"]
+					: []),
+				...(deps.oxfmt || has(".oxfmtrc.json", ".oxfmtrc.jsonc") ? ["oxfmt"] : []),
+				...(deps["@biomejs/biome"] || has("biome.json", "biome.jsonc") ? ["biome"] : []),
+			];
+			// Recognize the executable, never execute an arbitrary package script.
+			const script = pkg.scripts?.format;
+			const scripted = script?.match(/^(prettier|oxfmt|biome)(?:\s|$)/)?.[1];
+			// Custom wrappers/options may encode conventions we cannot reproduce. Leave them alone.
+			if (
+				script &&
+				(!scripted ||
+					/[;&|`$<>]/.test(script) ||
+					(script.match(/(?<!\S)--?[\w-]+(?:=\S+)?/g) ?? []).some(
+						(flag) => !["--write", "--check", "--ignore-unknown"].includes(flag),
+					))
+			)
+				return null;
+			if (!scripted && choices.length > 1) return null;
+			name = scripted ?? choices[0];
+			args =
+				name === "prettier"
+					? ["--write", "--ignore-unknown"]
+					: name === "biome"
+						? ["format", "--write", "--files-ignore-unknown=true"]
+						: [];
+		} else if (extension === ".py" || extension === ".pyi") {
+			const config = text(join(cwd, "pyproject.toml"));
+			const ruff = has("ruff.toml", ".ruff.toml") || /\[tool\.ruff(?:\.|\])/.test(config);
+			const black = /\[tool\.black\]/.test(config);
+			if (ruff && black) return null;
+			name = ruff ? "ruff" : black ? "black" : undefined;
+			args = name === "ruff" ? ["format"] : [];
+		} else if (extension === ".go" && has("go.mod", "go.work")) {
+			name = "gofmt";
+			args = ["-w"];
+		} else if (extension === ".rs" && has("Cargo.toml")) {
+			const cargo = text(join(cwd, "Cargo.toml"));
+			if (/edition\s*\.\s*workspace\s*=/.test(cargo)) return null;
+			name = "rustfmt";
+			args = ["--edition", cargo.match(/^\s*edition\s*=\s*["'](\d+)["']/m)?.[1] ?? "2015"];
+		}
+		if (!name) continue;
+		const search = directories(cwd, root);
+		const candidates = search.map((dir) => join(dir, js ? "node_modules/.bin" : ".venv/bin", name!));
+		// JS formatters must belong to this project, not the extension's dependencies.
+		const executable = candidates.find((candidate) => Bun.which(candidate)) ?? (!js ? Bun.which(name) : null);
+		return executable ? { name, executable, args, cwd } : null;
+	}
+	return null;
+}
+
+export async function formatChanged(
+	files: string[],
+	root: string,
+): Promise<{ messages: string[]; warnings: string[] }> {
+	const groups = new Map<string, { command: Command; files: string[] }>();
+	const result = { messages: [] as string[], warnings: [] as string[] };
+	for (const file of files) {
+		const command = formatterFor(file, root);
+		if (!command) continue;
+		const key = JSON.stringify(command);
+		const group = groups.get(key) ?? { command, files: [] };
+		group.files.push("./" + relative(command.cwd, resolve(root, file)));
+		groups.set(key, group);
+	}
+	for (const { command, files: targets } of groups.values()) {
+		try {
+			const child = Bun.spawn([command.executable, ...command.args, ...targets], {
+				cwd: command.cwd,
+				stdout: "pipe",
+				stderr: "pipe",
+			});
+			const [code, stdout, stderr] = await Promise.all([
+				child.exited,
+				new Response(child.stdout).text(),
+				new Response(child.stderr).text(),
+			]);
+			if (code !== 0)
+				result.warnings.push(
+					`${command.name} formatting failed: ${(stderr || stdout).trim().slice(-2000) || `exit ${code}`}`,
+				);
+			else result.messages.push(`Formatted ${targets.length} file(s) with ${command.name}.`);
+		} catch (error) {
+			result.warnings.push(`${command.name} formatting failed: ${String(error)}`);
+		}
+	}
+	return result;
+}