pi-edit-first 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 sorinirimies
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,83 @@
-# Temporary Holding Version
+# pi-edit-first
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Pi 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.
+
+## Rules
+
+| # | Blocks | Tells the model |
+|---|---|---|
+| 1 | `write` over an existing file longer than `maxWriteLines` (default 40) | use `edit` with targeted replacements |
+| 2 | `write` of `Cargo.toml`, `settings.gradle[.kts]`, `package.json` in a dir with no project yet | run `cargo init` / `android create` / `npm init -y` |
+
+## Install
+
+```bash
+pi install npm:pi-edit-first
+# or
+pi install git:github.com/sorinirimies/pi-edit-first
+```
+
+Applies to every pi session (including pi run as an external agent in editors).
+
+## 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
+
+## Config (optional)
+
+`~/.pi/agent/edit-first.json`:
+
+```json
+{ "maxWriteLines": 40, "scaffold": true, "ignore": ["CHANGELOG.md", "*.lock"] }
+```
+
+## Notes
+
+- A block costs one extra round trip, far cheaper than a whole-file rewrite.
+- 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

@@ -0,0 +1,236 @@
+/**
+ * pi-edit-first — make the agent edit, not rewrite.
+ *
+ * Zero prompt tokens: enforcement happens in a `tool_call` hook. The model only
+ * sees a short reason when a call is blocked.
+ *
+ * Rules
+ *   1. `write` over an existing file longer than `maxWriteLines` is blocked → use `edit`.
+ *   2. `write` of a project manifest (Cargo.toml, settings.gradle[.kts], package.json)
+ *      in a directory with no project yet is blocked → use a scaffolder.
+ *
+ * Commands
+ *   /edit-first               status + 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): <agent dir>/edit-first.json
+ *   { "maxWriteLines": 40, "scaffold": true, "ignore": ["CHANGELOG.md", "*.lock"] }
+ */
+
+import { existsSync } from "node:fs";
+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 {
+	maxWriteLines: number;
+	scaffold: boolean;
+	ignore: string[];
+}
+
+const DEFAULTS: Config = { maxWriteLines: 40, scaffold: true, ignore: [] };
+
+/** 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"));
+		return {
+			maxWriteLines:
+				Number.isFinite(p.maxWriteLines) && p.maxWriteLines > 0 ? p.maxWriteLines : DEFAULTS.maxWriteLines,
+			scaffold: typeof p.scaffold === "boolean" ? p.scaffold : DEFAULTS.scaffold,
+			ignore: Array.isArray(p.ignore) ? p.ignore.filter((x: unknown) => typeof x === "string") : [],
+		};
+	} catch {
+		return { ...DEFAULTS };
+	}
+}
+
+/** Minimal glob: `*` matches anything except `/`; matched against path or basename. */
+/** Minimal glob (`*` = anything except `/`) against the path or its basename. */
+export function matchesIgnore(path: string, patterns: string[]): boolean {
+	return patterns.some((pat) => {
+		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));
+	});
+}
+
+
+// ---------------------------------------------------------------------------
+// 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"] },
+	"settings.gradle.kts": {
+		hint: "run `android create` or `gradle init`",
+		exists: ["settings.gradle.kts", "settings.gradle"],
+	},
+	"settings.gradle": {
+		hint: "run `android create` or `gradle init`",
+		exists: ["settings.gradle.kts", "settings.gradle"],
+	},
+	"package.json": { hint: "run `npm init -y`", exists: ["package.json"] },
+};
+
+export default function editFirst(pi: ExtensionAPI) {
+	let config: Config = { ...DEFAULTS };
+	let enabled = true;
+	let blocked = 0;
+	const allowed = new Set<string>();
+
+	pi.on("session_start", async () => {
+		config = await loadConfig();
+		enabled = true;
+		blocked = 0;
+		allowed.clear();
+	});
+
+	/**
+	 * 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 = resolveToolPath(raw, ctx.cwd);
+
+		if (allowed.has(abs) || matchesIgnore(raw, config.ignore)) return undefined;
+
+		const deny = (reason: string) => {
+			blocked++;
+			if (ctx.hasUI) ctx.ui.notify(`edit-first: blocked write to ${raw}`, "warning");
+			return { block: true as const, reason };
+		};
+
+		if (existsSync(abs)) {
+			let count: { lines: number; capped: boolean };
+			try {
+				count = await countLinesCapped(abs, config.maxWriteLines + COUNT_HEADROOM);
+			} catch {
+				return undefined;
+			}
+			if (count.lines > config.maxWriteLines) {
+				const size = count.capped ? `over ${count.lines} lines` : `${count.lines} lines`;
+				return deny(
+					`"${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}.`,
+				);
+			}
+			return undefined;
+		}
+
+		if (config.scaffold) {
+			const scaffold = SCAFFOLDS[basename(abs)];
+			if (scaffold && dirname(abs) === resolve(ctx.cwd)) {
+				const hasProject = scaffold.exists.some((f) => existsSync(join(dirname(abs), f)));
+				if (!hasProject) {
+					return deny(
+						`No project here yet. Do not hand-write ${basename(abs)}: ${scaffold.hint}, then fill in the logic.`,
+					);
+				}
+			}
+		}
+		return undefined;
+	};
+
+	pi.on("tool_call", async (event, ctx) => {
+		try {
+			return await guard(event, ctx);
+		} catch {
+			return undefined;
+		}
+	});
+
+	pi.registerCommand("edit-first", {
+		description: "Status, on/off, or `allow <path>` for pi-edit-first",
+		handler: async (args, ctx) => {
+			const [cmd, ...rest] = (args ?? "").trim().split(/\s+/).filter(Boolean);
+			if (cmd === "off") enabled = false;
+			else if (cmd === "on") enabled = true;
+			else if (cmd === "allow" && rest.length > 0) {
+				const p = rest.join(" ");
+				allowed.add(resolveToolPath(p, ctx.cwd));
+				ctx.ui.notify(`edit-first: full rewrite of ${p} allowed this session`, "info");
+				return;
+			}
+			ctx.ui.notify(
+				`edit-first: ${enabled ? "on" : "off"} · maxWriteLines=${config.maxWriteLines} · scaffold=${config.scaffold} · blocked=${blocked}`,
+				"info",
+			);
+		},
+	});
+}

package/package.json

@@ -1,6 +1,30 @@
 {
   "name": "pi-edit-first",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "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",
+  "author": "sorinirimies",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sorinirimies/pi-edit-first.git"
+  },
+  "homepage": "https://github.com/sorinirimies/pi-edit-first#readme",
+  "files": ["extensions", "README.md", "LICENSE"],
+  "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"
+  }
+}