@khanhicetea/pi-better-tool 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 pi-better-tool contributors
+
+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

@@ -0,0 +1,120 @@
+# pi-better-tool
+
+Better built-in tools for the [pi coding agent](https://github.com/earendil-works/pi-mono) — starting with an `edit` override that turns failed edits into recoverable ones.
+
+## Why
+
+The built-in `edit` tool requires `edits[].oldText` to match **exactly and uniquely**. When it doesn't, the tool fails with a bare error:
+
+```
+Could not find edits[1] in /code/app.go. The oldText must match exactly including all whitespace and newlines.
+```
+
+That failure wastes a whole loop: the model has to `read` the file again, guess a larger context, and retry — sometimes failing again. `pi-better-tool` keeps the refusal (writing the wrong occurrence would be worse) but returns **recovery context** so the next call succeeds without re-reading:
+
+- **Ambiguous match (2+ occurrences)** — every occurrence's line number plus the **minimum prefix/suffix context** that makes each occurrence unique, rendered as ready-to-use `oldText` snippets.
+- **Text not found** — the closest matching region (fuzzy line similarity), a line-by-line comparison against your `oldText`, the exact file bytes to retry with, and likely causes (tabs vs spaces, indentation, case).
+
+## Install
+
+```bash
+pi install npm:@khanhicetea/pi-better-tool
+```
+
+For local development from this monorepo:
+
+```bash
+pi install /absolute/path/to/pi-kit/packages/pi-better-tool
+```
+
+It is also registered in the root `package.json` under `pi.extensions`.
+
+## Example: ambiguous oldText
+
+```text
+Found 2 occurrences of the text in dup.go. The text must be unique. Please provide more context to make it unique.
+
+Occurrences:
+  1. lines 2-3
+  2. lines 6-7
+
+Retry with a disambiguated oldText: pick ONE occurrence below and reuse its snippet exactly. Each snippet already includes the minimum surrounding context that makes it unique:
+
+Occurrence 1 (lines 2-3) — minimum context: 0 lines before, 1 line after:
+```
+	log()
+}
+
+func second() {
+```
+
+Occurrence 2 (lines 6-7) — minimum context: 0 lines before, 0 lines after:
+```
+	log()
+}
+```
+
+Tip: use the snippet byte-for-byte as the new oldText, and make newText the snippet with your change applied (the snippet may span whole lines).
+
+No changes were written — the file was not modified.
+```
+
+## Example: text not found
+
+```text
+Could not find the exact text in tabs.go. The old text must match exactly including all whitespace and newlines.
+
+Closest match in the file: lines 3-5 (~91% line similarity).
+Differences vs your oldText (2 of 3 compared lines match):
+  file line 4 differs from your oldText line 2:
+    file:     →tab→fmt.Println("hi")
+    oldText:      fmt.Println("hi")
+
+Exact file content at lines 3-5 — retry using this text as oldText (then apply your change to newText):
+```
+func main() {
+	fmt.Println("hi")
+}
+```
+
+Possible cause:
+- whitespace mismatch: the text matches when ALL whitespace is removed — check tabs vs spaces and indentation width
+
+No changes were written — the file was not modified.
+```
+
+## Behavior
+
+Happy-path semantics are **identical** to the built-in `edit` tool:
+
+- same schema (`path` + `edits[{oldText,newText}]`), including the compatibility shim for models that send `edits` as a JSON string, a single edit object, or legacy top-level `oldText`/`newText`
+- same matching engine ported from pi's `edit-diff.ts`: exact match first, fuzzy fallback (trailing whitespace, smart quotes, dashes, unicode spaces), uniqueness checked in fuzzy-normalized space, all edits matched against the original content, overlap/empty/no-change detection
+- same BOM and CRLF handling
+- same success result shape (`details.diff` / `details.patch` / `details.firstChangedLine`), and no custom renderers — the built-in diff renderer is inherited
+
+Failure behavior is the difference: errors carry the recovery context described above, and nothing is written on failure (edits remain atomic).
+
+Diagnostics degrade gracefully: files over ~2 MB skip the analysis and return the plain built-in-style error; repeated blocks that cannot be disambiguated within 12 context lines get a guidance note instead of snippets.
+
+## Development
+
+```bash
+npm run check     # typecheck + tests
+npm test          # vitest only
+```
+
+## Publishing
+
+From the repository root, verify the package and inspect its tarball before publishing:
+
+```bash
+npm run check --workspace=@khanhicetea/pi-better-tool
+npm pack --dry-run --workspace=@khanhicetea/pi-better-tool
+npm publish --workspace=@khanhicetea/pi-better-tool
+```
+
+The package is configured for public publishing under the `@khanhicetea` scope. npm authentication is required.
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,44 @@
+{
+	"name": "@khanhicetea/pi-better-tool",
+	"version": "0.1.0",
+	"description": "Better built-in tools for pi: an edit tool override that returns recovery context (closest match + disambiguation snippets) instead of bare failures",
+	"type": "module",
+	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/khanhicetea/pi-kit.git",
+		"directory": "packages/pi-better-tool"
+	},
+	"homepage": "https://github.com/khanhicetea/pi-kit/tree/main/packages/pi-better-tool",
+	"bugs": {
+		"url": "https://github.com/khanhicetea/pi-kit/issues"
+	},
+	"keywords": ["pi-package", "pi-extension", "edit", "tools"],
+	"files": ["src", "README.md", "LICENSE"],
+	"scripts": {
+		"test": "vitest run",
+		"typecheck": "tsc --noEmit",
+		"check": "npm run typecheck && npm test",
+		"prepublishOnly": "npm run check"
+	},
+	"peerDependencies": {
+		"@earendil-works/pi-coding-agent": "*",
+		"typebox": "*"
+	},
+	"devDependencies": {
+		"@earendil-works/pi-coding-agent": "0.82.1",
+		"@types/node": "^24.0.0",
+		"typebox": "^1.0.0",
+		"typescript": "^5.9.0",
+		"vitest": "^3.2.0"
+	},
+	"pi": {
+		"extensions": ["./src/index.ts"]
+	},
+	"engines": {
+		"node": ">=20"
+	},
+	"publishConfig": {
+		"access": "public"
+	}
+}

package/src/apply.ts

@@ -0,0 +1,277 @@
+/**
+ * Edit matching and application engine.
+ *
+ * A port of pi's built-in `applyEditsToNormalizedContent` with one key
+ * difference: instead of throwing opaque errors, `analyzeEdits` returns a
+ * structured failure describing *why* an edit failed, which the diagnostics
+ * layer turns into actionable recovery context for the model.
+ *
+ * Matching semantics are kept identical to the built-in tool:
+ * - exact match first, then fuzzy-normalized fallback (trailing whitespace,
+ *   smart quotes, dashes, unicode spaces)
+ * - uniqueness is always checked in fully fuzzy-normalized space
+ * - all edits match against the same original content (not incrementally)
+ * - overlap detection, empty-oldText and no-change detection
+ */
+
+import {
+	countFuzzyOccurrences,
+	findAllOccurrences,
+	getLineSpans,
+	lineAt,
+	normalizeForFuzzyMatch,
+	normalizeToLF,
+	splitLinesWithEndings,
+	type LineSpan,
+} from "./text.ts";
+
+export interface EditOp {
+	oldText: string;
+	newText: string;
+}
+
+/** 1-based inclusive line range. */
+export interface LineRange {
+	start: number;
+	end: number;
+}
+
+export type EditFailure =
+	| { kind: "empty-old-text"; editIndex: number }
+	| { kind: "not-found"; editIndex: number }
+	| {
+			kind: "ambiguous";
+			editIndex: number;
+			/** Offsets of every occurrence, enumerated in fully fuzzy-normalized space. */
+			occurrenceOffsets: number[];
+	  }
+	| {
+			kind: "overlap";
+			firstEditIndex: number;
+			secondEditIndex: number;
+			firstRange: LineRange;
+			secondRange: LineRange;
+	  }
+	| { kind: "no-change" };
+
+export interface Replacement {
+	editIndex: number;
+	matchIndex: number;
+	matchLength: number;
+	newText: string;
+}
+
+export interface EditAnalysis {
+	/** Sorted by matchIndex ascending. */
+	replacements: Replacement[];
+	usedFuzzyMatch: boolean;
+}
+
+export interface FuzzyFindResult {
+	found: boolean;
+	index: number;
+	matchLength: number;
+	usedFuzzyMatch: boolean;
+	contentForReplacement: string;
+}
+
+export type AnalyzeResult = { ok: true; analysis: EditAnalysis } | { ok: false; failure: EditFailure };
+
+export function normalizeEdits(edits: EditOp[]): EditOp[] {
+	return edits.map((edit) => ({
+		oldText: normalizeToLF(edit.oldText),
+		newText: normalizeToLF(edit.newText),
+	}));
+}
+
+/** Find oldText in content, trying exact match first, then fuzzy match. */
+export function fuzzyFindText(content: string, oldText: string): FuzzyFindResult {
+	const exactIndex = content.indexOf(oldText);
+	if (exactIndex !== -1) {
+		return {
+			found: true,
+			index: exactIndex,
+			matchLength: oldText.length,
+			usedFuzzyMatch: false,
+			contentForReplacement: content,
+		};
+	}
+	const fuzzyContent = normalizeForFuzzyMatch(content);
+	const fuzzyOldText = normalizeForFuzzyMatch(oldText);
+	const fuzzyIndex = fuzzyContent.indexOf(fuzzyOldText);
+	if (fuzzyIndex === -1) {
+		return {
+			found: false,
+			index: -1,
+			matchLength: 0,
+			usedFuzzyMatch: false,
+			contentForReplacement: content,
+		};
+	}
+	return {
+		found: true,
+		index: fuzzyIndex,
+		matchLength: fuzzyOldText.length,
+		usedFuzzyMatch: true,
+		contentForReplacement: fuzzyContent,
+	};
+}
+
+function rangeOf(spans: LineSpan[], matchIndex: number, matchLength: number): LineRange {
+	return {
+		start: lineAt(spans, matchIndex) + 1,
+		end: lineAt(spans, matchIndex + Math.max(1, matchLength) - 1) + 1,
+	};
+}
+
+export function analyzeEdits(normalizedContent: string, rawEdits: EditOp[]): AnalyzeResult {
+	const edits = normalizeEdits(rawEdits);
+	for (let i = 0; i < edits.length; i++) {
+		if (edits[i].oldText.length === 0) {
+			return { ok: false, failure: { kind: "empty-old-text", editIndex: i } };
+		}
+	}
+
+	const initialMatches = edits.map((edit) => fuzzyFindText(normalizedContent, edit.oldText));
+	const usedFuzzyMatch = initialMatches.some((match) => match.usedFuzzyMatch);
+	const base = usedFuzzyMatch ? normalizeForFuzzyMatch(normalizedContent) : normalizedContent;
+	const fuzzyBase = normalizeForFuzzyMatch(base);
+	const spans = getLineSpans(base);
+
+	const replacements: Replacement[] = [];
+	for (let i = 0; i < edits.length; i++) {
+		const edit = edits[i];
+		const matchResult = fuzzyFindText(base, edit.oldText);
+		if (!matchResult.found) {
+			return { ok: false, failure: { kind: "not-found", editIndex: i } };
+		}
+		const occurrences = countFuzzyOccurrences(fuzzyBase, edit.oldText);
+		if (occurrences > 1) {
+			const occurrenceOffsets = findAllOccurrences(fuzzyBase, normalizeForFuzzyMatch(edit.oldText));
+			return {
+				ok: false,
+			failure: { kind: "ambiguous", editIndex: i, occurrenceOffsets },
+			};
+		}
+		replacements.push({
+			editIndex: i,
+			matchIndex: matchResult.index,
+			matchLength: matchResult.matchLength,
+			newText: edit.newText,
+		});
+	}
+
+	replacements.sort((a, b) => a.matchIndex - b.matchIndex);
+	for (let i = 1; i < replacements.length; i++) {
+		const previous = replacements[i - 1];
+		const current = replacements[i];
+		if (previous.matchIndex + previous.matchLength > current.matchIndex) {
+			return {
+				ok: false,
+				failure: {
+					kind: "overlap",
+					firstEditIndex: previous.editIndex,
+					secondEditIndex: current.editIndex,
+					firstRange: rangeOf(spans, previous.matchIndex, previous.matchLength),
+					secondRange: rangeOf(spans, current.matchIndex, current.matchLength),
+				},
+			};
+		}
+	}
+
+	return { ok: true, analysis: { replacements, usedFuzzyMatch } };
+}
+
+function applyReplacements(content: string, replacements: Replacement[], offset = 0): string {
+	let result = content;
+	for (let i = replacements.length - 1; i >= 0; i--) {
+		const replacement = replacements[i];
+		const matchIndex = replacement.matchIndex - offset;
+		result =
+			result.substring(0, matchIndex) + replacement.newText + result.substring(matchIndex + replacement.matchLength);
+	}
+	return result;
+}
+
+/** 0-based, end-exclusive window of lines used by the fuzzy overlay. */
+interface InternalLineWindow {
+	startLine: number;
+	endLine: number;
+}
+
+function getReplacementLineRange(lines: LineSpan[], replacement: Replacement): InternalLineWindow {
+	const replacementStart = replacement.matchIndex;
+	const replacementEnd = replacement.matchIndex + replacement.matchLength;
+	let startLine = -1;
+	for (let i = 0; i < lines.length; i++) {
+		const line = lines[i];
+		if (replacementStart >= line.start && replacementStart < line.end) {
+			startLine = i;
+			break;
+		}
+	}
+	if (startLine === -1) {
+		throw new Error("Replacement range is outside the base content.");
+	}
+	let endLine = startLine;
+	while (endLine < lines.length && lines[endLine].end < replacementEnd) {
+		endLine++;
+	}
+	if (endLine >= lines.length) {
+		throw new Error("Replacement range is outside the base content.");
+	}
+	return { startLine, endLine: endLine + 1 };
+}
+
+/**
+ * Apply replacements matched against `baseContent` to `originalContent` while
+ * preserving unchanged line blocks from the original (fuzzy-match overlay).
+ */
+function applyReplacementsPreservingUnchangedLines(
+	originalContent: string,
+	baseContent: string,
+	replacements: Replacement[],
+): string {
+	const originalLines = splitLinesWithEndings(originalContent);
+	const baseLines = getLineSpans(baseContent);
+	if (originalLines.length !== baseLines.length) {
+		throw new Error("Cannot preserve unchanged lines because the base content has a different line count.");
+	}
+
+	const groups: Array<InternalLineWindow & { replacements: Replacement[] }> = [];
+	const sortedReplacements = [...replacements].sort((a, b) => a.matchIndex - b.matchIndex);
+	for (const replacement of sortedReplacements) {
+		const range = getReplacementLineRange(baseLines, replacement);
+		const current = groups[groups.length - 1];
+		if (current && range.startLine < current.endLine) {
+			current.endLine = Math.max(current.endLine, range.endLine);
+			current.replacements.push(replacement);
+			continue;
+		}
+		groups.push({ ...range, replacements: [replacement] });
+	}
+
+	let originalLineIndex = 0;
+	let result = "";
+	for (const group of groups) {
+		result += originalLines.slice(originalLineIndex, group.startLine).join("");
+		const groupStartOffset = baseLines[group.startLine].start;
+		const groupEndOffset = baseLines[group.endLine - 1].end;
+		result += applyReplacements(baseContent.slice(groupStartOffset, groupEndOffset), group.replacements, groupStartOffset);
+		originalLineIndex = group.endLine;
+	}
+	result += originalLines.slice(originalLineIndex).join("");
+	return result;
+}
+
+export function applyAnalysis(normalizedContent: string, analysis: EditAnalysis): { baseContent: string; newContent: string } {
+	const baseContent = normalizedContent;
+	const newContent = analysis.usedFuzzyMatch
+		? applyReplacementsPreservingUnchangedLines(
+				normalizedContent,
+				normalizeForFuzzyMatch(normalizedContent),
+				analysis.replacements,
+			)
+		: applyReplacements(baseContent, analysis.replacements);
+	return { baseContent, newContent };
+}