pi-shorthand 0.3.1 → 0.4.0

package/README.md

@@ -1,100 +1,41 @@
 # pi-shorthand
 
-![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)
+![A code call in Pi](https://raw.githubusercontent.com/sebinsua/pi-shorthand/main/docs/screenshot.png?v=2)
 
 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
 
+Install pi-shorthand and initialize Grit:
+
 ```sh
 pi install npm:pi-shorthand
+npx @getgrit/cli init --global
+```
+
+On macOS, install clang and AgentFS:
+
+```sh
+xcode-select --install
+curl -fsSL https://agentfs.ai/install | bash
 ```
 
-Or from GitHub (`pi install git:github.com/sebinsua/pi-shorthand`), or a local clone: `npm install`, then `pi install /path/to/pi-shorthand`.
+On Linux, install bubblewrap 0.9 or later. For Debian and Ubuntu:
 
-A project install (`pi install -l`) only loads once you trust the project: Pi asks, or run `pi --approve`.
+```sh
+sudo apt install bubblewrap
+```
 
-You also need Bun, git, and either [bubblewrap](https://github.com/containers/bubblewrap) 0.9+
-(Linux) or [AgentFS](https://github.com/tursodatabase/agentfs) and `clang` (macOS:
-`curl -fsSL https://agentfs.ai/install | bash`).
+## Technical choices
 
-The optional `grit()` helper needs Grit’s modules initialized before sandboxed use. Run
-`npm run setup:grit` from this package’s directory if you want to use it. This explicitly runs
-`grit init --global` and changes your user-level Grit state; package installation does not run it.
+pi-shorthand gives Pi a programming environment instead of a patch format. This makes multi-file and structural edits possible in one call, but does not guarantee that Pi will find it easier or more reliable than its built-in edit tool. Which works better depends on the model and the task.
 
-## What a program can use
+Programs edit an isolated snapshot, with host files outside the repository kept read-only. By default, a failure keeps completed files and rolls back files involved in failed or interrupted edits; changes are applied only if their destination files have not changed.
 
-Anything in Bun or Node, plus these globals (no imports):
+## Diagnosing slow calls
 
-```ts
-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");
-```
+Calls taking longer than their configured program timeout (two seconds by default) show a muted timing footer. The timeout limits the editing program, not the entire transaction. Live progress also names the active setup or cleanup step.
+
+The footer separates parent-observed startup/IPC, runner work, and response/exit overhead. Snapshot detail includes inventory, copy, verification, attempt count, entry count, and logical file bytes. Nested measurements overlap and must not be added to their containing phase totals; logical bytes are not measured disk I/O. Formatting and edit execution include separate subprocess-wait and cleanup measurements.
 
-`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
-
-- `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.
-- 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.
-- Generated programs can write to the private workspace and run-specific temporary space; host files
-  outside those roots are read-only, including targets reached through repository symlinks. Run-history
-  logging has a narrow write exception. On macOS, the live checkout is also unreadable.
-- 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`.
-- 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
-
-`npm run check` type-checks (TypeScript 7), lints (oxlint) and checks formatting (oxfmt). A pre-commit
-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/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.
+Infrastructure failures retain completed measurements and identify the failed phase. If the runner exits before reporting completion, its execution interval is marked as observed/incomplete. Structured diagnostics are attached to tool result details; source contents and individual filenames are not recorded in diagnostic events.

package/api.d.ts

@@ -8,6 +8,7 @@ declare global {
 	const grep: ShorthandGlobals["grep"];
 	const sg: ShorthandGlobals["sg"];
 	const grit: ShorthandGlobals["grit"];
+	const ts: ShorthandGlobals["ts"];
 }
 
 export type { RewriteResult } from "./prelude.ts";

package/diagnostics.ts

@@ -0,0 +1,142 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+
+export interface DiagnosticSpan {
+	name: string;
+	startMs: number;
+	durationMs?: number;
+	failed?: boolean;
+}
+
+export interface Diagnostics {
+	spans: DiagnosticSpan[];
+	counters: Record<string, number>;
+	phase?: string;
+	failurePhase?: string;
+	runnerMs?: number;
+	startupMs?: number;
+	responseMs?: number;
+	wallMs?: number;
+	incomplete?: boolean;
+}
+
+const context = new AsyncLocalStorage<{
+	startedAt: number;
+	diagnostics: Diagnostics;
+	publish: (diagnostics: Diagnostics) => void;
+	phaseSpan?: DiagnosticSpan;
+}>();
+
+/** Run-local, bounded metadata only: never record source text, filenames or command output. */
+export async function withDiagnostics<T>(
+	operation: () => Promise<T>,
+	publish: (diagnostics: Diagnostics) => void,
+): Promise<{ value: T; diagnostics: Diagnostics }> {
+	const state = {
+		startedAt: performance.now(),
+		diagnostics: { spans: [], counters: {} } as Diagnostics,
+		publish: (diagnostics: Diagnostics) => {
+			try {
+				publish(diagnostics);
+			} catch {
+				/* Diagnostics must not change the operation's outcome. */
+			}
+		},
+	};
+	return context.run(state, async () => {
+		state.publish(state.diagnostics);
+		try {
+			return { value: await operation(), diagnostics: state.diagnostics };
+		} catch (error) {
+			diagnosticFailure();
+			throw error;
+		} finally {
+			const active = context.getStore()!;
+			if (active.phaseSpan)
+				active.phaseSpan.durationMs = Math.round(performance.now() - state.startedAt - active.phaseSpan.startMs);
+			state.diagnostics.runnerMs = Math.round(performance.now() - state.startedAt);
+			state.publish(state.diagnostics);
+		}
+	});
+}
+
+export async function measure<T>(name: string, operation: () => Promise<T>): Promise<T> {
+	const state = context.getStore();
+	if (!state) return operation();
+	const start = performance.now();
+	const span: DiagnosticSpan = { name, startMs: Math.round(start - state.startedAt) };
+	state.diagnostics.spans.push(span);
+	state.publish(state.diagnostics);
+	try {
+		return await operation();
+	} catch (error) {
+		span.failed = true;
+		throw error;
+	} finally {
+		span.durationMs = Math.round(performance.now() - start);
+		state.publish(state.diagnostics);
+	}
+}
+
+export function diagnosticCounter(name: string, value: number, add = false) {
+	const state = context.getStore();
+	if (!state) return;
+	state.diagnostics.counters[name] = value + (add ? (state.diagnostics.counters[name] ?? 0) : 0);
+	state.publish(state.diagnostics);
+}
+
+export function diagnosticPhase(phase: string) {
+	const state = context.getStore();
+	if (!state) return;
+	const now = Math.round(performance.now() - state.startedAt);
+	if (state.phaseSpan) state.phaseSpan.durationMs = now - state.phaseSpan.startMs;
+	state.phaseSpan = { name: phase, startMs: now };
+	state.diagnostics.spans.push(state.phaseSpan);
+	state.diagnostics.phase = phase;
+	state.publish(state.diagnostics);
+}
+
+export function diagnosticFailure() {
+	const state = context.getStore();
+	if (!state || state.diagnostics.failurePhase) return;
+	state.diagnostics.failurePhase = state.diagnostics.phase;
+	if (state.phaseSpan) state.phaseSpan.failed = true;
+}
+
+/** Spans are nested within runner phases; these figures must not be added to the phase total. */
+const duration = (ms: number) => `${ms}ms`;
+
+/** Parent-observed startup includes event delivery; a missing final event means execution is incomplete. */
+export function completeDiagnostics(diagnostics: Diagnostics, wallMs: number, startupMs: number): Diagnostics {
+	diagnostics.wallMs = Math.round(wallMs);
+	diagnostics.startupMs = Math.round(startupMs);
+	if (diagnostics.runnerMs === undefined) {
+		diagnostics.incomplete = true;
+		diagnostics.runnerMs = Math.max(0, diagnostics.wallMs - diagnostics.startupMs);
+	}
+	diagnostics.responseMs = Math.max(0, diagnostics.wallMs - diagnostics.startupMs - diagnostics.runnerMs);
+	return diagnostics;
+}
+
+export function diagnosticLines(diagnostics: Diagnostics): string[] {
+	const lines: string[] = [];
+	if (diagnostics.wallMs !== undefined) {
+		lines.push(
+			`wall ${duration(diagnostics.wallMs)} · runner startup/IPC ${duration(diagnostics.startupMs ?? 0)} · runner${diagnostics.incomplete ? " (observed, incomplete)" : ""} ${duration(diagnostics.runnerMs ?? 0)} · response/exit ${duration(diagnostics.responseMs ?? 0)}`,
+		);
+	}
+	if (diagnostics.spans.length) {
+		lines.push("phase detail (nested measurements overlap):");
+		lines.push(
+			...diagnostics.spans
+				.filter((span) => span.durationMs !== 0)
+				.map(
+					(span) =>
+						`  ${span.name}: ${span.durationMs === undefined ? "incomplete" : duration(span.durationMs)}${span.failed ? " (failed)" : ""}`,
+				),
+		);
+	}
+	const counters = Object.entries(diagnostics.counters);
+	if (counters.length) lines.push(counters.map(([name, value]) => `${name}: ${value}`).join(" · "));
+	if (diagnostics.failurePhase) lines.push(`failed during: ${diagnostics.failurePhase}`);
+	return lines;
+}

package/display.ts

@@ -8,7 +8,8 @@
  */
 
 import { getLanguageFromPath, highlightCode, keyHint, renderDiff, type Theme } from "@earendil-works/pi-coding-agent";
-import type { FileChange, RunResult } from "./runner.ts";
+import type { FileChange, RunResult, RunTimings } from "./runner.ts";
+import { diagnosticLines } from "./diagnostics.ts";
 
 type ToolBackground = "toolSuccessBg" | "toolErrorBg";
 
@@ -21,7 +22,7 @@ const LISTED_FILES = 8; // …showing this many, then "and N more files"
 const EXPANDED_DIFF_LINES = 2000; // even expanded, a diff of hundreds of files stops here
 
 export function callLine(args: { title?: string; timeout?: number; rollback?: string }, theme: Theme): string {
-	const settings = [args.rollback === "file" && "rollback per file", args.timeout && `timeout ${args.timeout}s`];
+	const settings = [args.rollback === "all" && "rollback all", args.timeout && `program timeout ${args.timeout}s`];
 	const suffix = settings.filter(Boolean).join(", ");
 	return `${theme.fg("toolTitle", theme.bold("code"))} ${args.title ?? ""}${suffix ? theme.fg("muted", ` (${suffix})`) : ""}`;
 }
@@ -69,29 +70,65 @@ export function resultLines(run: RunResult, expanded: boolean, theme: Theme): st
 	}
 	for (const file of run.rolledBack) {
 		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";
+			? "open writers could not be inspected"
+			: "file edit failed or was interrupted";
 		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[][] = [];
-	const background: ToolBackground = run.exitCode === 0 && run.conflicts.length === 0 ? "toolSuccessBg" : "toolErrorBg";
+	const background: ToolBackground =
+		run.exitCode === 0 && run.conflicts.length === 0 && run.rolledBack.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, background));
 	for (const section of sections) lines.push("", ...section);
+	const timing = timingBreakdown(run);
+	if (timing) lines.push("", theme.fg("muted", `timing: ${timing}`));
+	if (run.diagnostics && ((run.diagnostics.wallMs ?? run.durationMs) >= run.timeoutMs || run.exitCode !== 0)) {
+		lines.push(...diagnosticLines(run.diagnostics).map((line) => theme.fg("muted", line)));
+	}
 	return lines;
 }
 
+const TIMING_LABELS: Record<keyof RunTimings, string> = {
+	resolveRepositoryMs: "repository",
+	waitForLockMs: "lock wait",
+	workspaceSetupMs: "workspace setup",
+	programMs: "program",
+	scanChangesMs: "change scan",
+	formatMs: "formatter",
+	workspaceCloseMs: "workspace cleanup",
+	checkConflictsMs: "conflict check",
+	applyMs: "apply",
+	renderDiffMs: "diff",
+	unattributedMs: "other",
+};
+
+/** Explain calls exceeding the configured program budget, even when no individual phase does. */
+export function timingBreakdown(run: RunResult): string | undefined {
+	if (!run.timings || (run.diagnostics?.wallMs ?? run.durationMs) < run.timeoutMs) return undefined;
+	const significant = Object.entries(run.timings)
+		.map(([phase, milliseconds]) => ({
+			label: TIMING_LABELS[phase as keyof RunTimings],
+			milliseconds,
+		}))
+		.filter(({ milliseconds }) => milliseconds > 0)
+		.toSorted((a, b) => b.milliseconds - a.milliseconds);
+	if (significant.length === 0) return undefined;
+	return significant.map(({ label, milliseconds }) => `${label} ${formatDuration(milliseconds)}`).join(" · ");
+}
+
+function formatDuration(milliseconds: number): string {
+	return milliseconds < 1_000 ? `${milliseconds}ms` : `${(milliseconds / 1_000).toFixed(1)}s`;
+}
+
 /** e.g. "✓ Applied 3 files · +6 −6 · 0.6s" or "✕ Failed · rolled back all changes · exit 1 · 0.2s" */
 function verdict(run: RunResult, applied: FileChange[], theme: Theme): string {
 	const muted = (text: string) => theme.fg("muted", text);
 	const took = muted(` · ${(run.durationMs / 1000).toFixed(1)}s`);
-	const failure = run.timedOut ? `Timed out after ${run.timeoutMs / 1000}s` : "Failed";
+	const failure = run.timedOut ? `Program timed out after ${run.timeoutMs / 1000}s` : "Failed";
 	const exit = run.timedOut ? "" : muted(` · exit ${run.exitCode}`);
 
 	if (run.conflicts.length > 0) {
@@ -104,7 +141,7 @@ function verdict(run: RunResult, applied: FileChange[], theme: Theme): string {
 		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) {
+	if (run.exitCode === 0 && run.rolledBack.length === 0) {
 		return theme.fg("success", `✓ Applied ${fileCount(applied)}`) + ` · ${stats(applied, theme)}` + took;
 	}
 	if (applied.length > 0) {

package/file-outcomes.ts

@@ -0,0 +1,100 @@
+/** Per-file edit outcomes sent to the runner over a private inherited descriptor. */
+import { spawnSync } from "node:child_process";
+import { realpathSync, writeSync } from "node:fs";
+import { isAbsolute, relative, resolve } from "node:path";
+
+export type FileOutcomeEvent =
+	| { type: "begin"; id: number; files: string[] }
+	| { type: "end" | "fail"; id: number }
+	| { type: "error"; files: string[] }
+	| { type: "writers"; files: string[] | null };
+
+const descriptor = process.env.PI_SHORTHAND_OUTCOMES_FD;
+const root = process.env.PI_SHORTHAND_EXECUTION_ROOT;
+const forceInspectionFailure = process.env.PI_SHORTHAND_INSPECTION_FAILURE === "1";
+// Subprocesses do not inherit descriptor 3 by default, so do not advertise it to them.
+delete process.env.PI_SHORTHAND_OUTCOMES_FD;
+delete process.env.PI_SHORTHAND_EXECUTION_ROOT;
+delete process.env.PI_SHORTHAND_INSPECTION_FAILURE;
+let nextId = 0;
+
+function send(event: FileOutcomeEvent): void {
+	if (!descriptor) return;
+	const bytes = Buffer.from(JSON.stringify(event) + "\n");
+	let offset = 0;
+	while (offset < bytes.length) offset += writeSync(Number(descriptor), bytes, offset);
+}
+
+function paths(files: readonly string[]): string[] {
+	if (!root) return [];
+	return [
+		...new Set(
+			files
+				.filter((file) => typeof file === "string")
+				.flatMap((file) => {
+					const absolute = resolve(file);
+					try {
+						return [relative(root, absolute), relative(root, realpathSync(absolute))];
+					} catch {
+						return [relative(root, absolute)];
+					}
+				}),
+		),
+	].filter((file) => file !== ".." && !file.startsWith("../") && !isAbsolute(file));
+}
+
+/** An operation may touch several files (for example, moving a node between files). */
+export function editingFiles<T>(files: readonly string[], edit: () => T): T {
+	if (!descriptor) return edit();
+	const id = nextId++;
+	send({ type: "begin", id, files: paths(files) });
+	try {
+		const result = edit();
+		send({ type: "end", id });
+		return result;
+	} catch (error) {
+		send({ type: "fail", id });
+		throw error;
+	}
+}
+
+export function installFileOutcomeTracking(): void {
+	if (!descriptor) return;
+	process.on("uncaughtExceptionMonitor", (error) => {
+		// Native filesystem errors identify their paths even when no editing helper was involved.
+		const details = (typeof error === "object" && error !== null ? error : {}) as { path?: unknown; dest?: unknown };
+		const files = [details.path, details.dest].filter((file): file is string => typeof file === "string");
+		send({ type: "error", files: paths(files) });
+	});
+	process.on("exit", (code) => {
+		if (code === 0) return;
+		send({ type: "writers", files: inspectWriters() });
+	});
+}
+
+/** Exit handlers run before descriptors close, so ordinary errors can be inspected too. */
+function inspectWriters(): string[] | null {
+	if (!root || forceInspectionFailure) return null;
+	// bubblewrap replaces /dev, hiding the host's message-queue mount. Exempt that unrelated
+	// mount from stat probes; otherwise lsof reports incomplete output for every Linux run.
+	const args = ["-n", "-P", "-F", "an", ...(process.platform === "linux" ? ["-e", "/dev/mqueue"] : [])];
+	const result = spawnSync("lsof", args, {
+		encoding: "utf8",
+		timeout: 2000,
+		maxBuffer: 64 * 1024 * 1024,
+	});
+	if (result.error || result.status !== 0 || result.stderr) return null;
+	return parseOpenWriters(result.stdout, root);
+}
+
+export function parseOpenWriters(output: string, directory: string): string[] {
+	const files = new Set<string>();
+	let access = "";
+	for (const line of output.split("\n")) {
+		if (line.startsWith("f")) access = "";
+		if (line.startsWith("a")) access = line.slice(1);
+		if (line.startsWith(`n${directory}/`) && (access === "w" || access === "u"))
+			files.add(relative(directory, line.slice(1)));
+	}
+	return [...files];
+}

package/format.ts

@@ -4,6 +4,14 @@ import { dirname, extname, join, relative, resolve } from "node:path";
 
 type Command = { name: string; executable: string; args: string[]; cwd: string };
 
+/** A conservative filter: configuration and executable discovery still happen inside the sandbox. */
+export function supportsFormatting(file: string): boolean {
+	return (
+		/\.(?:[cm]?[jt]sx?|jsonc?|css|scss|less|html|vue|svelte|mdx?|ya?ml|graphql)$/i.test(file) ||
+		[".py", ".pyi", ".go", ".rs"].includes(extname(file))
+	);
+}
+
 function text(file: string): string {
 	try {
 		return readFileSync(file, "utf8");