pi-edit-first 0.1.0 → 0.1.1

package/README.md

@@ -42,4 +42,42 @@ Applies to every pi session (including pi run as an external agent in editors).
 - Only affects the `write` tool; `edit` is never blocked.
 - 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.
+
+## Releases (automatic)
+
+| Workflow | When | What |
+|---|---|---|
+| **CI** | push / PR | quality gate on Linux; tests on macOS, Windows and extreme time zones |
+| **Nightly Dependency Update** | every night (GitHub 02:00 UTC, Gitea 02:30) | `bun update` within ranges, verify on all platforms, commit `chore(deps)`; then **publish a patch** when a *runtime* dependency was upgraded 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), creates the release |
+
+Dev-tooling-only bumps are committed but never released on their own. A downgrade blocks the whole update.
+
+Manual release: `just bump patch` (or `minor` / `major` / `X.Y.Z`), then `just release-push`.
+
+**Secrets** (repo settings): `NPM_TOKEN` — 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.
+
 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,79 @@ 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. `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;
+		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++;
+			if (newlines + 1 > cap) return { lines: cap, capped: true };
+		}
+		return { lines: size === 0 ? 0 : newlines + 1, 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 +157,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 +177,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 +205,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 +223,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.1",
   "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"
+  }
 }