pi-edit-first 0.1.0 → 0.1.2

package/README.md

@@ -1,9 +1,15 @@
 # pi-edit-first
 
-Pi extension that cuts output tokens by making the agent **edit, not rewrite**.
+[![npm](https://img.shields.io/npm/v/pi-edit-first.svg)](https://www.npmjs.com/package/pi-edit-first)
+[![npm downloads](https://img.shields.io/npm/dm/pi-edit-first.svg)](https://www.npmjs.com/package/pi-edit-first)
+[![CI](https://github.com/sorinirimies/pi-edit-first/actions/workflows/ci.yml/badge.svg)](https://github.com/sorinirimies/pi-edit-first/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 
-Enforcement lives in a `tool_call` hook, so it adds **zero tokens to the system prompt**.
-The model only sees a one-line reason when a call is blocked.
+A [pi](https://github.com/earendil-works/pi-coding-agent) extension that cuts output tokens by making the agent **edit, not rewrite**.
+
+Enforcement lives in a `tool_call` hook, so it adds **zero tokens to the system prompt**. The model only sees a one-line reason when a call is blocked.
+
+<img src="examples/vhs/generated/overview.gif" alt="The agent tries to rewrite a whole file; pi-edit-first blocks it and the agent makes a one-line targeted edit instead" width="900">
 
 ## Rules
 
@@ -22,11 +28,27 @@ pi install git:github.com/sorinirimies/pi-edit-first
 
 Applies to every pi session (including pi run as an external agent in editors).
 
+## Previews
+
+Recorded from a real pi with only this plugin loaded; a small scripted mock model plays the agent, so you see the **real guard** reacting to **real tool calls**.
+
+**A whole-file rewrite is blocked, the agent makes a targeted edit** (one line added, not 62 rewritten):
+
+![The write is blocked and the agent falls back to a one-line edit](examples/vhs/generated/overview.gif)
+
+**Hand-written manifests are blocked too** (scaffold with the real tool instead):
+
+![Writing Cargo.toml by hand is blocked: run cargo init](examples/vhs/generated/scaffold.gif)
+
+**Commands:** status and block count, `off` / `on`, and `allow <path>` for one deliberate rewrite:
+
+![/edit-first status, off, on and allow](examples/vhs/generated/commands.gif)
+
 ## Commands
 
-- `/edit-first` — status and block count
-- `/edit-first off` / `on` — disable / enable for this session
-- `/edit-first allow <path>` — allow one full rewrite of `<path>` this session
+- `/edit-first`: status and block count
+- `/edit-first off` / `on`: disable / enable for this session
+- `/edit-first allow <path>`: allow one full rewrite of `<path>` this session
 
 ## Config (optional)
 
@@ -40,6 +62,73 @@ Applies to every pi session (including pi run as an external agent in editors).
 
 - A block costs one extra round trip, far cheaper than a whole-file rewrite.
 - Only affects the `write` tool; `edit` is never blocked.
+- Line counts match `wc -l` (a trailing newline is not an extra line).
 - Does not affect other agents (e.g. Zed's native agent).
 
+## Security notes
+
+- **A token saver, not a sandbox.** It guards pi's `write` tool. An agent can still write files through `bash`; the guard exists to keep wasteful rewrites out of your context, not to confine the agent.
+- **Same path as the tool.** Paths are resolved exactly like pi's own tools (`@file`, `~/file`, `file://`, Unicode spaces, Windows shell paths), so those spellings can't slip past it. A contract test compares it with pi's real `resolveToCwd`.
+- **Fails open.** pi blocks a tool when a `tool_call` handler throws, so any unexpected error here means "allow": the guard can never stop legitimate work.
+- **Constant memory.** Line counts are streamed (64 KB chunks, early exit), never the whole file.
+- No network access, no shell commands, **zero runtime dependencies**.
+
+## Development
+
+```bash
+bun install
+just check          # typecheck + tests + pack check + nushell tests (what CI runs)
+just test           # bun test only (with coverage)
+just coverage       # tests + a coverage table
+```
+
+**Coverage:** every `bun test` collects coverage (`bunfig.toml`) and **fails below 95% lines / 95% functions**. CI shows the table on the run page and uploads `lcov.info`.
+
+CI scripts are [nushell](https://www.nushell.sh) (`scripts/`), the same ones locally and in GitHub / Gitea Actions.
+`just --list` shows every task.
+
+## Demo recordings
+
+The GIFs above live in [`examples/vhs/generated/`](examples/vhs/generated) and are stored with **Git LFS** (`git lfs install` once). They are recorded with [VHS](https://github.com/charmbracelet/vhs) from a **real pi** that loads only this extension, on **synthetic** data (`examples/vhs/fixture.sh`), never from real files, sessions or credentials. The agent is a scripted mock model (`examples/vhs/mock-llm.ts`), so the recording is repeatable.
+
+```sh
+just vhs-all          # every tape (examples/vhs/*.tape): needs vhs, ttyd, ffmpeg, pi, bun, python3
+just vhs-tape overview  # one tape
+just vhs-list         # list the tapes
+just demo             # try it yourself in a real pi on the same synthetic data
+```
+
+## Releases (automatic)
+
+| Workflow | When | What |
+|---|---|---|
+| **CI** | push / PR | quality gate on Linux; tests on macOS and Windows |
+| **Auto-merge library updates** | CI finished on a Dependabot PR | **patch and minor** updates (GitHub Actions) are merged automatically, but only **after CI is green** on that exact commit; a **major** update waits for you. Then it starts the nightly workflow so the update ships |
+| **Nightly Dependency Update** | every night (GitHub 02:00 UTC, Gitea 02:30) and after each auto-merge | `bun update` within ranges, verify on all platforms, commit `chore(deps)`; then **build, tag and publish a new patch** whenever a library was upgraded or merged, or `feat`/`fix`/`perf` commits are waiting since the last tag |
+| **Release** | tag `vX.Y.Z` | validates the tag against `package.json`, runs the gate, `npm publish` (idempotent, with provenance), creates the release |
+
+So library updates need no human: they are merged once CI passes, built, versioned and published as a patch. A downgrade, a failing check, or a major update stops the chain and waits for review.
+
+Manual release: `just bump patch` (or `minor` / `major` / `X.Y.Z`), then `just release-push`.
+
+**Secrets** (repo settings): `NPM_TOKEN` is an npm *granular access token* with publish rights and "bypass 2FA" (required for CI publishing). Optional: `GH_PAT` (lets a tag push trigger the release itself), `GITEA_TOKEN` (Gitea).
+
+Commits follow [Conventional Commits](https://www.conventionalcommits.org); the changelog is generated by git-cliff.
+
+## Related plugins
+
+Three small [pi](https://github.com/earendil-works/pi-coding-agent) extensions that save tokens without adding anything to the system prompt:
+
+| Plugin | What it does |
+|---|---|
+| [**pi-edit-first**](https://github.com/sorinirimies/pi-edit-first) | Blocks whole-file `write` rewrites and hand-written project manifests, steering the agent to targeted `edit` calls and scaffolders |
+| [**pi-read-guard**](https://github.com/sorinirimies/pi-read-guard) | Blocks full reads of large files, steering the agent to `offset`/`limit` or search |
+| [**pi-tokenburn**](https://github.com/sorinirimies/pi-tokenburn) | Live token and cost counter in pi's footer, with charts and budgets |
+
+```bash
+pi install npm:pi-edit-first
+pi install npm:pi-read-guard
+pi install npm:pi-tokenburn
+```
+
 MIT

package/extensions/edit-first.ts

@@ -19,9 +19,10 @@
  */
 
 import { existsSync } from "node:fs";
-import { readFile } from "node:fs/promises";
+import { open, readFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import { basename, dirname, isAbsolute, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 
 interface Config {
@@ -32,12 +33,15 @@ interface Config {
 
 const DEFAULTS: Config = { maxWriteLines: 40, scaffold: true, ignore: [] };
 
-function agentDir(): string {
-	if (process.env.PI_CODING_AGENT_DIR) return process.env.PI_CODING_AGENT_DIR;
-	if (process.env.XDG_CONFIG_HOME) return join(process.env.XDG_CONFIG_HOME, "pi", "agent");
-	return join(homedir(), ".pi", "agent");
+/** Where pi keeps its config: PI_CODING_AGENT_DIR, then $XDG_CONFIG_HOME/pi/agent, then ~/.pi/agent. */
+export function resolveAgentDir(env: Record<string, string | undefined>, home: string): string {
+	if (env.PI_CODING_AGENT_DIR) return env.PI_CODING_AGENT_DIR;
+	if (env.XDG_CONFIG_HOME) return join(env.XDG_CONFIG_HOME, "pi", "agent");
+	return join(home, ".pi", "agent");
 }
 
+const agentDir = () => resolveAgentDir(process.env, homedir());
+
 async function loadConfig(): Promise<Config> {
 	try {
 		const p = JSON.parse(await readFile(join(agentDir(), "edit-first.json"), "utf8"));
@@ -53,17 +57,82 @@ async function loadConfig(): Promise<Config> {
 }
 
 /** Minimal glob: `*` matches anything except `/`; matched against path or basename. */
-function matchesIgnore(path: string, patterns: string[]): boolean {
+/** Minimal glob (`*` = anything except `/`) against the path or its basename. */
+export function matchesIgnore(path: string, patterns: string[]): boolean {
 	return patterns.some((pat) => {
-		const re = new RegExp(`^${pat.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*/g, "[^/]*")}$`);
+		if (pat.length > 256) return false; // absurd pattern: ignore it rather than risk slow matching
+		const body = pat.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*+/g, "*").replace(/\*/g, "[^/]*");
+		const re = new RegExp(`^${body}$`);
 		return re.test(path) || re.test(basename(path));
 	});
 }
 
-function countLines(text: string): number {
-	return text === "" ? 0 : text.split("\n").length;
+
+// ---------------------------------------------------------------------------
+// Path handling — mirrors pi's own tool path resolution (`resolveToCwd`), so the
+// guard looks at the same file the tool will: `@file`, `~/file`, `file://…`,
+// Unicode spaces and Windows shell paths are normalised exactly as pi does.
+// ---------------------------------------------------------------------------
+
+const UNICODE_SPACES = /[\u00A0\u2000-\u200A\u202F\u205F\u3000]/g;
+
+function normalizeWindowsShellPath(filePath: string): string {
+	if (!filePath.startsWith("/") || filePath.startsWith("//") || filePath.includes("\\")) return filePath;
+	const m = filePath.match(/^\/(?:mnt\/|cygdrive\/)?([a-z])(?:\/(.*))?$/i);
+	if (!m) return filePath;
+	return `${m[1].toUpperCase()}:\\${m[2]?.replaceAll("/", "\\") ?? ""}`;
 }
 
+export function resolveToolPath(
+	input: string,
+	cwd: string,
+	home: string = homedir(),
+	platform: string = process.platform,
+): string {
+	let p = input.replace(UNICODE_SPACES, " ");
+	if (p.startsWith("@")) p = p.slice(1);
+	if (platform === "win32") p = normalizeWindowsShellPath(p);
+	if (p === "~") p = home;
+	else if (p.startsWith("~/") || (platform === "win32" && p.startsWith("~\\"))) p = join(home, p.slice(2));
+	if (/^file:\/\//.test(p)) {
+		try {
+			p = fileURLToPath(p);
+		} catch {
+			/* malformed URL: leave as is; the tool will report it */
+		}
+	}
+	return isAbsolute(p) ? resolve(p) : resolve(cwd, p);
+}
+
+/**
+ * Count lines without loading the file: constant memory, and it stops as soon as `cap` is
+ * exceeded. Counts like `wc -l`, plus an unterminated last line. `lines` is exact unless `capped`.
+ */
+export async function countLinesCapped(path: string, cap: number): Promise<{ lines: number; capped: boolean }> {
+	const fh = await open(path, "r");
+	try {
+		const buf = Buffer.allocUnsafe(64 * 1024);
+		let newlines = 0;
+		let size = 0;
+		let lastByte = 0;
+		for (;;) {
+			const { bytesRead } = await fh.read(buf, 0, buf.length, null);
+			if (bytesRead === 0) break;
+			size += bytesRead;
+			for (let i = 0; i < bytesRead; i++) if (buf[i] === 10) newlines++;
+			lastByte = buf[bytesRead - 1];
+			if (newlines > cap) return { lines: cap, capped: true }; // at least `newlines` lines: past the cap
+		}
+		const lines = size === 0 ? 0 : newlines + (lastByte === 10 ? 0 : 1);
+		return lines > cap ? { lines: cap, capped: true } : { lines, capped: false };
+	} finally {
+		await fh.close();
+	}
+}
+
+/** Lines counted exactly up to this many beyond the limit; past that the message says "over N". */
+const COUNT_HEADROOM = 10_000;
+
 /** Manifest → what to run instead, and a marker that proves a project already exists. */
 const SCAFFOLDS: Record<string, { hint: string; exists: string[] }> = {
 	"Cargo.toml": { hint: "run `cargo init` / `cargo new`", exists: ["Cargo.toml"] },
@@ -91,12 +160,16 @@ export default function editFirst(pi: ExtensionAPI) {
 		allowed.clear();
 	});
 
-	pi.on("tool_call", async (event, ctx) => {
+	/**
+	 * pi BLOCKS the tool when a `tool_call` handler throws, so a bug here must never
+	 * stop legitimate work: any unexpected error means "allow".
+	 */
+	const guard = async (event: any, ctx: any) => {
 		if (!enabled || event.toolName !== "write") return undefined;
 
 		const raw = event.input?.path;
 		if (typeof raw !== "string" || raw === "") return undefined;
-		const abs = isAbsolute(raw) ? raw : resolve(ctx.cwd, raw);
+		const abs = resolveToolPath(raw, ctx.cwd);
 
 		if (allowed.has(abs) || matchesIgnore(raw, config.ignore)) return undefined;
 
@@ -107,15 +180,16 @@ export default function editFirst(pi: ExtensionAPI) {
 		};
 
 		if (existsSync(abs)) {
-			let lines = 0;
+			let count: { lines: number; capped: boolean };
 			try {
-				lines = countLines(await readFile(abs, "utf8"));
+				count = await countLinesCapped(abs, config.maxWriteLines + COUNT_HEADROOM);
 			} catch {
 				return undefined;
 			}
-			if (lines > config.maxWriteLines) {
+			if (count.lines > config.maxWriteLines) {
+				const size = count.capped ? `over ${count.lines} lines` : `${count.lines} lines`;
 				return deny(
-					`"${raw}" exists (${lines} lines). Do not rewrite whole files: use the edit tool with small targeted replacements. ` +
+					`"${raw}" exists (${size}). Do not rewrite whole files: use the edit tool with small targeted replacements. ` +
 						`If a full rewrite is truly required, ask the user to run /edit-first allow ${raw}.`,
 				);
 			}
@@ -134,6 +208,14 @@ export default function editFirst(pi: ExtensionAPI) {
 			}
 		}
 		return undefined;
+	};
+
+	pi.on("tool_call", async (event, ctx) => {
+		try {
+			return await guard(event, ctx);
+		} catch {
+			return undefined;
+		}
 	});
 
 	pi.registerCommand("edit-first", {
@@ -144,7 +226,7 @@ export default function editFirst(pi: ExtensionAPI) {
 			else if (cmd === "on") enabled = true;
 			else if (cmd === "allow" && rest.length > 0) {
 				const p = rest.join(" ");
-				allowed.add(isAbsolute(p) ? p : resolve(ctx.cwd, p));
+				allowed.add(resolveToolPath(p, ctx.cwd));
 				ctx.ui.notify(`edit-first: full rewrite of ${p} allowed this session`, "info");
 				return;
 			}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-edit-first",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Pi extension that cuts output tokens: blocks whole-file `write` rewrites and hand-written project manifests, steering the agent to targeted `edit` calls and scaffolders. Zero prompt tokens.",
   "keywords": ["pi-package", "pi-extension", "tokens", "edit", "guard"],
   "license": "MIT",
@@ -11,6 +11,20 @@
   },
   "homepage": "https://github.com/sorinirimies/pi-edit-first#readme",
   "files": ["extensions", "README.md", "LICENSE"],
-  "pi": { "extensions": ["./extensions/edit-first.ts"] },
-  "peerDependencies": { "@earendil-works/pi-coding-agent": "*" }
+  "pi": {
+    "extensions": ["./extensions/edit-first.ts"]
+  },
+  "scripts": {
+    "test": "bun test",
+    "typecheck": "tsc --noEmit",
+    "check": "nu scripts/ci/quality_gate.nu"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "^1.1.0",
+    "@types/bun": "^1.4.2",
+    "typescript": "^7.0.2"
+  }
 }