pi-shorthand 0.3.0 → 0.3.1

package/README.md

@@ -23,6 +23,10 @@ You also need Bun, git, and either [bubblewrap](https://github.com/containers/bu
 (Linux) or [AgentFS](https://github.com/tursodatabase/agentfs) and `clang` (macOS:
 `curl -fsSL https://agentfs.ai/install | bash`).
 
+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.
+
 ## What a program can use
 
 Anything in Bun or Node, plus these globals (no imports):
@@ -67,6 +71,9 @@ globals. Bun execution does not automatically type-check programs or run applica
 - 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.

package/overlay-macos.ts

@@ -11,6 +11,7 @@ import { homedir, tmpdir } from "node:os";
 import * as path from "node:path";
 import { $ } from "bun";
 import { Database } from "bun:sqlite";
+import { historyEnabled, RUN_HISTORY_FILE, RUN_HISTORY_LOCK_DIR } from "./history.ts";
 import { copyStableTree } from "./overlay-linux.ts";
 import type { FilesystemEntry, Overlay } from "./runner.ts";
 
@@ -31,7 +32,9 @@ export async function openMacOverlay(repo: string, tempDir: string): Promise<Ove
 	const base = path.join(tempDir, "base");
 	const mountContainer = await fs.mkdtemp(path.join(await fs.realpath(tmpdir()), "pi-shorthand-workspace-"));
 	const mount = path.join(mountContainer, "repo");
+	const scratch = path.join(mountContainer, "tmp");
 	await fs.mkdir(mount);
+	await fs.mkdir(scratch);
 	const state: RecoveryState = { runnerPid: process.pid, tempDir, mountContainer, mount };
 	await writeRecoveryState(stateFile, state);
 
@@ -48,11 +51,12 @@ export async function openMacOverlay(repo: string, tempDir: string): Promise<Ove
 			originalDir: base,
 			writableDir: mount,
 			executionDir: mount,
+			environment: { TMPDIR: scratch, TMP: scratch, TEMP: scratch },
 			gitExcludes: ["._*"],
 			wrap: (command) => [
 				"/usr/bin/sandbox-exec",
 				"-p",
-				sandboxProfile(repo, tempDir, mount, stateFile, gitMetadata, processDeniedCanary, cleanupHelper),
+				sandboxProfile(repo, tempDir, mount, stateFile, gitMetadata, processDeniedCanary, cleanupHelper, scratch),
 				...command,
 			],
 			terminateProcesses: async () => {
@@ -209,8 +213,8 @@ async function serveAndMount(
 	}
 }
 
-/** The program may write only to its private mount, excluding the real checkout and Git metadata. */
-function sandboxProfile(
+/** Restrict writes to the workspace, private scratch space, devices and optional run history. */
+export function sandboxProfile(
 	repo: string,
 	tempDir: string,
 	mount: string,
@@ -218,10 +222,21 @@ function sandboxProfile(
 	gitMetadata: string[],
 	processDeniedCanary: string,
 	cleanupHelper: string,
+	scratch: string,
 ): string {
 	return [
 		"(version 1)",
 		"(allow default)",
+		"(deny file-write*)",
+		`(allow file-write* (require-all (subpath ${JSON.stringify(mount)}) (require-not (subpath ${JSON.stringify(path.join(mount, ".git"))}))))`,
+		`(allow file-write* (subpath ${JSON.stringify(scratch)}))`,
+		'(allow file-write-data (literal "/dev/null") (literal "/dev/tty"))',
+		...(historyEnabled()
+			? [
+					`(allow file-write-data (literal ${JSON.stringify(RUN_HISTORY_FILE)}))`,
+					`(allow file-write* (subpath ${JSON.stringify(RUN_HISTORY_LOCK_DIR)}))`,
+				]
+			: []),
 		`(deny file-read* (subpath ${JSON.stringify(repo)}))`,
 		`(deny file-write* (subpath ${JSON.stringify(repo)}))`,
 		`(deny file-write* (subpath ${JSON.stringify(tempDir)}))`,

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-shorthand",
-	"version": "0.3.0",
+	"version": "0.3.1",
 	"description": "Pi tool for editing repositories with Bun programs, text edits and structural transformations.",
 	"keywords": [
 		"ast-grep",
@@ -33,7 +33,7 @@
 		"lint": "oxlint --deny-warnings",
 		"format": "oxfmt",
 		"check": "tsc -p . && oxlint --deny-warnings && oxfmt --check",
-		"postinstall": "grit init --global",
+		"setup:grit": "grit init --global",
 		"prepare": "git config core.hooksPath .githooks 2>/dev/null || true"
 	},
 	"dependencies": {

package/runner.ts

@@ -363,10 +363,10 @@ async function conflictingFiles(repo: string, changes: Change[]): Promise<string
 /** Compares the complete no-follow filesystem entry and rechecks the path leading to it. */
 async function destinationMatches(repo: string, change: Change): Promise<boolean> {
 	const target = path.join(repo, change.file);
-	if (!(await safeParentChain(repo, target))) return false;
+	if (!(await safeParentChain(repo, target, change.before === null))) return false;
 	try {
 		const current = await snapshotEntry(target);
-		return entriesEqual(current, change.before) && (await safeParentChain(repo, target));
+		return entriesEqual(current, change.before) && (await safeParentChain(repo, target, change.before === null));
 	} catch (error) {
 		if (error instanceof UnsupportedEntryError) return false;
 		throw error;
@@ -374,13 +374,17 @@ async function destinationMatches(repo: string, change: Change): Promise<boolean
 }
 
 /** Every existing ancestor must remain a real directory inside the checkout, never a symlink. */
-async function safeParentChain(repo: string, target: string): Promise<boolean> {
+async function safeParentChain(repo: string, target: string, allowMissing = false): Promise<boolean> {
 	const relative = path.relative(repo, target);
 	if (relative.startsWith("..") || path.isAbsolute(relative)) return false;
 	let parent = path.dirname(target);
 	while (parent !== repo) {
-		const stats = await fs.lstat(parent).catch(() => null);
-		if (!stats?.isDirectory() || stats.isSymbolicLink()) return false;
+		try {
+			const stats = await fs.lstat(parent);
+			if (!stats.isDirectory() || stats.isSymbolicLink()) return false;
+		} catch (error) {
+			if (!allowMissing || (error as NodeJS.ErrnoException).code !== "ENOENT") return false;
+		}
 		parent = path.dirname(parent);
 	}
 	return true;
@@ -707,11 +711,59 @@ interface PreparedChange {
 	installed?: { dev: number; ino: number; mode: number };
 }
 
+interface CreatedDirectory {
+	path: string;
+	dev: number;
+	ino: number;
+}
+
+/** Create missing parents individually, checking existing ancestors without following symlinks. */
+async function createParents(repo: string, target: string, created: CreatedDirectory[]): Promise<boolean> {
+	if (!(await safeParentChain(repo, target, true))) return false;
+	const parts = path.relative(repo, path.dirname(target)).split(path.sep).filter(Boolean);
+	let directory = repo;
+	for (const part of parts) {
+		directory = path.join(directory, part);
+		if (!(await safeParentChain(repo, directory))) return false;
+		try {
+			await fs.mkdir(directory);
+			const stats = await fs.lstat(directory);
+			created.push({ path: directory, dev: stats.dev, ino: stats.ino });
+		} catch (error) {
+			if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
+		}
+		const stats = await fs.lstat(directory);
+		if (!stats.isDirectory() || stats.isSymbolicLink()) return false;
+	}
+	return true;
+}
+
+/** Remove only empty, unchanged directories created by this transaction. */
+export async function applyChanges(
+	repo: string,
+	changes: Change[],
+	options: { abort: AbortSignal; testHooks?: ApplicationTestHooks },
+): Promise<{ applied: Change[]; conflicts: string[]; warnings: string[] }> {
+	const created: CreatedDirectory[] = [];
+	try {
+		return await applyPreparedChanges(repo, changes, options, created);
+	} finally {
+		for (const directory of created.toReversed()) {
+			if (!(await safeParentChain(repo, directory.path))) continue;
+			const stats = await fs.lstat(directory.path).catch(() => null);
+			if (stats?.isDirectory() && stats.dev === directory.dev && stats.ino === directory.ino) {
+				await fs.rmdir(directory.path).catch(() => {});
+			}
+		}
+	}
+}
+
 /** Prepares every resource first, then rolls the complete commit back on any failure or conflict. */
-async function applyChanges(
+async function applyPreparedChanges(
 	repo: string,
 	changes: Change[],
 	options: { abort: AbortSignal; testHooks?: ApplicationTestHooks },
+	created: CreatedDirectory[],
 ): Promise<{ applied: Change[]; conflicts: string[]; warnings: string[] }> {
 	const { abort, testHooks = {} } = options;
 	const {
@@ -727,7 +779,10 @@ async function applyChanges(
 	try {
 		for (const change of changes) {
 			const target = path.join(repo, change.file);
-			if (!(await safeParentChain(repo, target))) {
+			if (
+				!(await destinationMatches(repo, change)) ||
+				(change.after && !(await createParents(repo, target, created)))
+			) {
 				await cleanupPrepared(prepared);
 				return { applied: [], conflicts: await conflictingFiles(repo, changes), warnings: [] };
 			}

package/skills/shorthand/advanced-refactors.md

@@ -158,8 +158,9 @@ belong to `code`, not necessarily ordinary shell calls. `node:fs` and ordinary B
 ## Execution options
 
 Programs run in an isolated repository workspace. Use relative paths: the live checkout's absolute
-path is inaccessible on macOS. On Linux, host paths outside the repository are read-only and
-`$TMPDIR` is private to the run. Writes to `.git` are blocked.
+path is inaccessible on macOS. On both platforms, host paths outside the workspace are read-only
+(including external symlink targets), apart from run-history logging. `$TMPDIR` is private to the run.
+Writes to `.git` are blocked.
 
 The default timeout is two seconds; request more for longer transformations.
 By default a failed program applies nothing. `rollback: "file"` can retain closed files after a