pi-edit-first 0.0.0-stage → 0.1.0

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,45 @@
-# 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).
+
+MIT

package/extensions/edit-first.ts

@@ -0,0 +1,157 @@
+/**
+ * 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 { readFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { basename, dirname, isAbsolute, join, resolve } from "node:path";
+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: [] };
+
+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");
+}
+
+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. */
+function matchesIgnore(path: string, patterns: string[]): boolean {
+	return patterns.some((pat) => {
+		const re = new RegExp(`^${pat.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*/g, "[^/]*")}$`);
+		return re.test(path) || re.test(basename(path));
+	});
+}
+
+function countLines(text: string): number {
+	return text === "" ? 0 : text.split("\n").length;
+}
+
+/** 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.on("tool_call", async (event, ctx) => {
+		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);
+
+		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 lines = 0;
+			try {
+				lines = countLines(await readFile(abs, "utf8"));
+			} catch {
+				return undefined;
+			}
+			if (lines > config.maxWriteLines) {
+				return deny(
+					`"${raw}" exists (${lines} lines). 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.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(isAbsolute(p) ? p : resolve(ctx.cwd, p));
+				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,16 @@
 {
   "name": "pi-edit-first",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "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"] },
+  "peerDependencies": { "@earendil-works/pi-coding-agent": "*" }
+}