mcp-hashline-edit-server 0.1.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2025 Mario Zechner (Pi — original codebase)
+Copyright (c) 2025-2026 Can Boluk (oh-my-pi — hashline edit format and implementation)
+
+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,143 @@
+# mcp-hashline-edit-server
+
+An MCP (Model Context Protocol) server that provides hashline-based file editing tools — line-addressed edits using content hashes for integrity verification.
+
+Based on the [hashline edit format](https://blog.can.ac/2026/02/12/the-harness-problem/) from [oh-my-pi](https://github.com/can1357/oh-my-pi).
+
+## What is Hashline?
+
+When an LLM reads a file, every line comes back tagged with a short content hash:
+
+```
+1:a3|function hello() {
+2:f1|  return "world";
+3:0e|}
+```
+
+When editing, the model references those tags — "replace line `2:f1`", "replace range `1:a3` through `3:0e`", "insert after `3:0e`". If the file changed since the last read, the hashes won't match and the edit is rejected before anything gets corrupted.
+
+This means the model doesn't need to reproduce old content (or whitespace) to identify what it wants to change. Benchmark results show hashline matches or beats traditional `str_replace` for most models, with the weakest models gaining the most (up to 10x improvement).
+
+## Requirements
+
+- [Bun](https://bun.sh/) runtime (uses `Bun.hash.xxHash32` for line hashing)
+
+## Install
+
+```bash
+cd mcp-hashline-edit-server
+bun install
+```
+
+## Usage
+
+### With Claude Desktop / Cursor / any MCP client
+
+Add to your MCP configuration:
+
+```json
+{
+  "mcpServers": {
+    "hashline-edit": {
+      "command": "bun",
+      "args": ["run", "/path/to/mcp-hashline-edit-server/src/index.ts"]
+    }
+  }
+}
+```
+
+### Running directly
+
+```bash
+bun run src/index.ts
+```
+
+The server communicates via stdio using the MCP protocol.
+
+## Tools
+
+### `read_file`
+
+Read a file with hashline-prefixed output (`LINE:HASH|content`).
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `path` | string | File path (relative or absolute) |
+| `offset` | number? | Line number to start from (1-indexed) |
+| `limit` | number? | Max lines to read (default: 2000) |
+
+### `edit_file`
+
+Edit a file using hash-verified line references. Supports four edit variants:
+
+**`set_line`** — Replace a single line:
+```json
+{"set_line": {"anchor": "2:f1", "new_text": "  return \"universe\";"}}
+```
+
+**`replace_lines`** — Replace a range:
+```json
+{"replace_lines": {"start_anchor": "1:a3", "end_anchor": "3:0e", "new_text": "function greet() {\n  return \"hi\";\n}"}}
+```
+
+**`insert_after`** — Insert after a line:
+```json
+{"insert_after": {"anchor": "1:a3", "text": "  // new comment"}}
+```
+
+**`replace`** — Substring fuzzy replace (fallback, no hashes needed):
+```json
+{"replace": {"old_text": "return \"world\"", "new_text": "return \"universe\""}}
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `path` | string | File path |
+| `edits` | array | Array of edit operations |
+
+All edits are validated atomically against the file as last read. Edits are sorted and applied bottom-up automatically.
+
+### `write_file`
+
+Create or overwrite a file.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `path` | string | File path |
+| `content` | string | Content to write |
+
+### `grep`
+
+Search files with hashline-prefixed results.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `pattern` | string | Regex pattern |
+| `path` | string? | File or directory to search |
+| `glob` | string? | Filter by glob (e.g., `*.js`) |
+| `type` | string? | Filter by file type |
+| `i` | boolean? | Case-insensitive |
+| `pre` | number? | Context lines before |
+| `post` | number? | Context lines after |
+| `limit` | number? | Max matches (default: 100) |
+
+Requires `rg` (ripgrep) installed on the system.
+
+## How the Hash Works
+
+1. Strip trailing `\r`
+2. Remove all whitespace from the line
+3. Compute `xxHash32` on the whitespace-stripped string
+4. Modulo 256, encode as 2-character lowercase hex (`00`-`ff`)
+
+The hash is whitespace-insensitive — indentation changes alone don't change the hash, making references robust against reformatting.
+
+## Error Recovery
+
+**Hash mismatch**: The error shows updated `LINE:HASH` refs with `>>>` markers. Copy the new refs and retry.
+
+**No-op error**: The replacement text matches current content. Re-read the file to see current state.
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "mcp-hashline-edit-server",
+  "version": "0.1.0",
+  "description": "MCP server providing hashline-based file editing tools — line-addressed edits using content hashes for integrity verification",
+  "type": "module",
+  "main": "src/index.ts",
+  "bin": {
+    "mcp-hashline-edit-server": "src/index.ts"
+  },
+  "license": "MIT",
+  "author": "Submerisble",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Submerisble/mcp-hashline-edit-server"
+  },
+  "keywords": ["mcp", "hashline", "editor", "coding-agent", "model-context-protocol"],
+  "files": ["src", "README.md"],
+  "scripts": {
+    "start": "bun run src/index.ts",
+    "dev": "bun --watch src/index.ts"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.1",
+    "diff": "^7.0.0"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "@types/diff": "^7.0.2",
+    "typescript": "^5.9.3"
+  }
+}

package/src/descriptions.ts

@@ -0,0 +1,63 @@
+/**
+ * Tool descriptions shown to the LLM via MCP.
+ */
+
+export const READ_FILE_DESCRIPTION = `Read a file from the filesystem with hashline-prefixed output.
+
+**IMPORTANT: Use this instead of built-in read tools (Cursor Read, Claude Read). This tool provides content-hashed line references required by edit_file.**
+
+Each line is tagged with a content hash: \`LINE:HASH|content\`.
+The LINE:HASH pairs serve as stable, verifiable anchors for the edit_file tool.
+
+Use \`offset\` and \`limit\` for large files (reads up to 2000 lines by default).
+Supports text files only.`;
+
+export const EDIT_FILE_DESCRIPTION = `Edit a file using hash-verified line references.
+
+**IMPORTANT: Use this instead of built-in edit tools (Cursor StrReplace, Claude Edit). This tool provides hash-verified edits with fuzzy matching, multi-edit batching, and automatic conflict detection.**
+
+Read a file first to get LINE:HASH pairs, then reference them to make edits.
+All edits in one call are validated against the file as last read — line numbers
+and hashes refer to the original state, not after earlier edits in the same array.
+
+**Critical rules:**
+- Copy LINE:HASH refs verbatim from read output — never fabricate or guess hashes
+- new_text/text contains plain replacement lines only — no LINE:HASH prefix, no diff + markers
+- On hash mismatch: use the updated LINE:HASH refs shown by >>> directly
+- If you already edited a file in this turn, re-read before the next edit
+- new_text must differ from the current line content — identical content is rejected
+
+**Edit variants:**
+- \`set_line\`: Replace a single line by its LINE:HASH anchor
+- \`replace_lines\`: Replace a range of lines (start_anchor through end_anchor)
+- \`insert_after\`: Insert new lines after the anchor line
+- \`replace\`: Substring-style fuzzy replace (no LINE:HASH needed; fallback when refs unavailable)
+
+**Atomicity:** Edits are sorted and applied bottom-up automatically.
+new_text: "" means delete (for set_line/replace_lines).
+
+**Recovery:**
+- Hash mismatch (>>> error): copy updated LINE:HASH refs from error and retry
+- No-op error: your replacement matches current content — re-read the file
+- After successful edit, re-read before making another edit to same file`;
+
+export const WRITE_FILE_DESCRIPTION = `Create or overwrite a file at the specified path.
+
+**IMPORTANT: Use this instead of built-in write tools (Cursor Write, Claude Write) to keep all file operations consistent through this server.**
+
+Prefer edit_file for modifying existing files (more precise, preserves formatting).
+Use this for creating new files or when full replacement is simpler.`;
+
+export const GREP_DESCRIPTION = `Search for text patterns in files using regex.
+
+**IMPORTANT: Use this instead of built-in search tools (Cursor Grep, Claude Grep). This tool returns hashline-prefixed results whose LINE:HASH pairs can be passed directly to edit_file for verified edits.**
+
+Results show hashline-prefixed matches: \`LINE:HASH|content\`.
+Match lines are prefixed with \`>>\`, context lines with spaces.
+The LINE:HASH pairs can be used directly with edit_file.
+
+Supports:
+- Full regex syntax (e.g., "log.*Error", "function\\s+\\w+")
+- File filtering by glob pattern or file type
+- Context lines before/after matches
+- Result limiting and offset for pagination`;

package/src/diff.ts

@@ -0,0 +1,154 @@
+/**
+ * Diff generation and replace-mode utilities.
+ */
+import * as Diff from "diff";
+import { DEFAULT_FUZZY_THRESHOLD, findMatch, type FuzzyMatch } from "./fuzzy";
+import { adjustIndentation, normalizeToLF } from "./normalize";
+
+export interface DiffResult {
+	diff: string;
+	firstChangedLine: number | undefined;
+}
+
+export interface ReplaceOptions {
+	fuzzy: boolean;
+	all: boolean;
+	threshold?: number;
+}
+
+export interface ReplaceResult {
+	content: string;
+	count: number;
+}
+
+function countContentLines(content: string): number {
+	const lines = content.split("\n");
+	if (lines.length > 1 && lines[lines.length - 1] === "") lines.pop();
+	return Math.max(1, lines.length);
+}
+
+function formatNumberedDiffLine(prefix: "+" | "-" | " ", lineNum: number, width: number, content: string): string {
+	const padded = String(lineNum).padStart(width, " ");
+	return `${prefix}${padded}|${content}`;
+}
+
+export function generateDiffString(oldContent: string, newContent: string, contextLines = 4): DiffResult {
+	const parts = Diff.diffLines(oldContent, newContent);
+	const output: string[] = [];
+	const maxLineNum = Math.max(countContentLines(oldContent), countContentLines(newContent));
+	const lineNumWidth = String(maxLineNum).length;
+	let oldLineNum = 1;
+	let newLineNum = 1;
+	let lastWasChange = false;
+	let firstChangedLine: number | undefined;
+
+	for (let i = 0; i < parts.length; i++) {
+		const part = parts[i];
+		const raw = part.value.split("\n");
+		if (raw[raw.length - 1] === "") raw.pop();
+
+		if (part.added || part.removed) {
+			if (firstChangedLine === undefined) firstChangedLine = newLineNum;
+			for (const line of raw) {
+				if (part.added) {
+					output.push(formatNumberedDiffLine("+", newLineNum, lineNumWidth, line));
+					newLineNum++;
+				} else {
+					output.push(formatNumberedDiffLine("-", oldLineNum, lineNumWidth, line));
+					oldLineNum++;
+				}
+			}
+			lastWasChange = true;
+		} else {
+			const nextPartIsChange = i < parts.length - 1 && (parts[i + 1].added || parts[i + 1].removed);
+			if (lastWasChange || nextPartIsChange) {
+				let linesToShow = raw;
+				let skipStart = 0;
+				let skipEnd = 0;
+				if (!lastWasChange) {
+					skipStart = Math.max(0, raw.length - contextLines);
+					linesToShow = raw.slice(skipStart);
+				}
+				if (!nextPartIsChange && linesToShow.length > contextLines) {
+					skipEnd = linesToShow.length - contextLines;
+					linesToShow = linesToShow.slice(0, contextLines);
+				}
+				if (skipStart > 0) {
+					output.push(formatNumberedDiffLine(" ", oldLineNum, lineNumWidth, "..."));
+					oldLineNum += skipStart;
+					newLineNum += skipStart;
+				}
+				for (const line of linesToShow) {
+					output.push(formatNumberedDiffLine(" ", oldLineNum, lineNumWidth, line));
+					oldLineNum++;
+					newLineNum++;
+				}
+				if (skipEnd > 0) {
+					output.push(formatNumberedDiffLine(" ", oldLineNum, lineNumWidth, "..."));
+					oldLineNum += skipEnd;
+					newLineNum += skipEnd;
+				}
+			} else {
+				oldLineNum += raw.length;
+				newLineNum += raw.length;
+			}
+			lastWasChange = false;
+		}
+	}
+	return { diff: output.join("\n"), firstChangedLine };
+}
+
+export function replaceText(content: string, oldText: string, newText: string, options: ReplaceOptions): ReplaceResult {
+	if (oldText.length === 0) throw new Error("oldText must not be empty.");
+	const threshold = options.threshold ?? DEFAULT_FUZZY_THRESHOLD;
+	let normalizedContent = normalizeToLF(content);
+	const normalizedOldText = normalizeToLF(oldText);
+	const normalizedNewText = normalizeToLF(newText);
+	let count = 0;
+
+	if (options.all) {
+		const exactCount = normalizedContent.split(normalizedOldText).length - 1;
+		if (exactCount > 0) {
+			return {
+				content: normalizedContent.split(normalizedOldText).join(normalizedNewText),
+				count: exactCount,
+			};
+		}
+		while (true) {
+			const matchOutcome = findMatch(normalizedContent, normalizedOldText, { allowFuzzy: options.fuzzy, threshold });
+			const shouldUseClosest =
+				options.fuzzy &&
+				matchOutcome.closest &&
+				matchOutcome.closest.confidence >= threshold &&
+				(matchOutcome.fuzzyMatches === undefined || matchOutcome.fuzzyMatches <= 1);
+			const match = matchOutcome.match || (shouldUseClosest ? matchOutcome.closest : undefined);
+			if (!match) break;
+			const adjustedNewText = adjustIndentation(normalizedOldText, match.actualText, normalizedNewText);
+			if (adjustedNewText === match.actualText) break;
+			normalizedContent =
+				normalizedContent.substring(0, match.startIndex) +
+				adjustedNewText +
+				normalizedContent.substring(match.startIndex + match.actualText.length);
+			count++;
+		}
+		return { content: normalizedContent, count };
+	}
+
+	const matchOutcome = findMatch(normalizedContent, normalizedOldText, { allowFuzzy: options.fuzzy, threshold });
+	if (matchOutcome.occurrences && matchOutcome.occurrences > 1) {
+		const previews = matchOutcome.occurrencePreviews?.join("\n\n") ?? "";
+		const moreMsg = matchOutcome.occurrences > 5 ? ` (showing first 5 of ${matchOutcome.occurrences})` : "";
+		throw new Error(
+			`Found ${matchOutcome.occurrences} occurrences${moreMsg}:\n\n${previews}\n\nAdd more context lines to disambiguate.`,
+		);
+	}
+	if (!matchOutcome.match) return { content: normalizedContent, count: 0 };
+
+	const match = matchOutcome.match;
+	const adjustedNewText = adjustIndentation(normalizedOldText, match.actualText, normalizedNewText);
+	normalizedContent =
+		normalizedContent.substring(0, match.startIndex) +
+		adjustedNewText +
+		normalizedContent.substring(match.startIndex + match.actualText.length);
+	return { content: normalizedContent, count: 1 };
+}

package/src/fuzzy.ts

@@ -0,0 +1,243 @@
+/**
+ * Fuzzy matching utilities for the edit tool.
+ *
+ * Provides both character-level and line-level fuzzy matching with progressive
+ * fallback strategies for finding text in files.
+ */
+import { countLeadingWhitespace, normalizeForFuzzy, normalizeUnicode } from "./normalize";
+
+// Constants
+
+export const DEFAULT_FUZZY_THRESHOLD = 0.95;
+const SEQUENCE_FUZZY_THRESHOLD = 0.92;
+const FALLBACK_THRESHOLD = 0.8;
+const PARTIAL_MATCH_MIN_LENGTH = 6;
+const PARTIAL_MATCH_MIN_RATIO = 0.3;
+const OCCURRENCE_PREVIEW_CONTEXT = 5;
+const OCCURRENCE_PREVIEW_MAX_LEN = 80;
+
+// Types
+
+export interface FuzzyMatch {
+	actualText: string;
+	startIndex: number;
+	startLine: number;
+	confidence: number;
+}
+
+export interface MatchOutcome {
+	match?: FuzzyMatch;
+	closest?: FuzzyMatch;
+	occurrences?: number;
+	occurrenceLines?: number[];
+	occurrencePreviews?: string[];
+	fuzzyMatches?: number;
+	dominantFuzzy?: boolean;
+}
+
+// Core Algorithms
+
+export function levenshteinDistance(a: string, b: string): number {
+	if (a === b) return 0;
+	const aLen = a.length;
+	const bLen = b.length;
+	if (aLen === 0) return bLen;
+	if (bLen === 0) return aLen;
+
+	let prev = new Array<number>(bLen + 1);
+	let curr = new Array<number>(bLen + 1);
+	for (let j = 0; j <= bLen; j++) prev[j] = j;
+
+	for (let i = 1; i <= aLen; i++) {
+		curr[0] = i;
+		const aCode = a.charCodeAt(i - 1);
+		for (let j = 1; j <= bLen; j++) {
+			const cost = aCode === b.charCodeAt(j - 1) ? 0 : 1;
+			const deletion = prev[j] + 1;
+			const insertion = curr[j - 1] + 1;
+			const substitution = prev[j - 1] + cost;
+			curr[j] = Math.min(deletion, insertion, substitution);
+		}
+		const tmp = prev;
+		prev = curr;
+		curr = tmp;
+	}
+	return prev[bLen];
+}
+
+export function similarity(a: string, b: string): number {
+	if (a.length === 0 && b.length === 0) return 1;
+	const maxLen = Math.max(a.length, b.length);
+	if (maxLen === 0) return 1;
+	const distance = levenshteinDistance(a, b);
+	return 1 - distance / maxLen;
+}
+
+// Line-Based Utilities
+
+function computeRelativeIndentDepths(lines: string[]): number[] {
+	const indents = lines.map(countLeadingWhitespace);
+	const nonEmptyIndents: number[] = [];
+	for (let i = 0; i < lines.length; i++) {
+		if (lines[i].trim().length > 0) nonEmptyIndents.push(indents[i]);
+	}
+	const minIndent = nonEmptyIndents.length > 0 ? Math.min(...nonEmptyIndents) : 0;
+	const indentSteps = nonEmptyIndents.map((indent) => indent - minIndent).filter((step) => step > 0);
+	const indentUnit = indentSteps.length > 0 ? Math.min(...indentSteps) : 1;
+	return lines.map((line, index) => {
+		if (line.trim().length === 0) return 0;
+		if (indentUnit <= 0) return 0;
+		const relativeIndent = indents[index] - minIndent;
+		return Math.round(relativeIndent / indentUnit);
+	});
+}
+
+function normalizeLines(lines: string[], includeDepth = true): string[] {
+	const indentDepths = includeDepth ? computeRelativeIndentDepths(lines) : null;
+	return lines.map((line, index) => {
+		const trimmed = line.trim();
+		const prefix = indentDepths ? `${indentDepths[index]}|` : "|";
+		if (trimmed.length === 0) return prefix;
+		return `${prefix}${normalizeForFuzzy(trimmed)}`;
+	});
+}
+
+function computeLineOffsets(lines: string[]): number[] {
+	const offsets: number[] = [];
+	let offset = 0;
+	for (let i = 0; i < lines.length; i++) {
+		offsets.push(offset);
+		offset += lines[i].length;
+		if (i < lines.length - 1) offset += 1;
+	}
+	return offsets;
+}
+
+// Character-Level Fuzzy Match
+
+interface BestFuzzyMatchResult {
+	best?: FuzzyMatch;
+	aboveThresholdCount: number;
+	secondBestScore: number;
+}
+
+function findBestFuzzyMatchCore(
+	contentLines: string[],
+	targetLines: string[],
+	offsets: number[],
+	threshold: number,
+	includeDepth: boolean,
+): BestFuzzyMatchResult {
+	const targetNormalized = normalizeLines(targetLines, includeDepth);
+	let best: FuzzyMatch | undefined;
+	let bestScore = -1;
+	let secondBestScore = -1;
+	let aboveThresholdCount = 0;
+
+	for (let start = 0; start <= contentLines.length - targetLines.length; start++) {
+		const windowLines = contentLines.slice(start, start + targetLines.length);
+		const windowNormalized = normalizeLines(windowLines, includeDepth);
+		let score = 0;
+		for (let i = 0; i < targetLines.length; i++) {
+			score += similarity(targetNormalized[i], windowNormalized[i]);
+		}
+		score = score / targetLines.length;
+
+		if (score >= threshold) aboveThresholdCount++;
+		if (score > bestScore) {
+			secondBestScore = bestScore;
+			bestScore = score;
+			best = {
+				actualText: windowLines.join("\n"),
+				startIndex: offsets[start],
+				startLine: start + 1,
+				confidence: score,
+			};
+		} else if (score > secondBestScore) {
+			secondBestScore = score;
+		}
+	}
+	return { best, aboveThresholdCount, secondBestScore };
+}
+
+function findBestFuzzyMatch(content: string, target: string, threshold: number): BestFuzzyMatchResult {
+	const contentLines = content.split("\n");
+	const targetLines = target.split("\n");
+	if (targetLines.length === 0 || target.length === 0) {
+		return { aboveThresholdCount: 0, secondBestScore: 0 };
+	}
+	if (targetLines.length > contentLines.length) {
+		return { aboveThresholdCount: 0, secondBestScore: 0 };
+	}
+	const offsets = computeLineOffsets(contentLines);
+	let result = findBestFuzzyMatchCore(contentLines, targetLines, offsets, threshold, true);
+
+	if (result.best && result.best.confidence < threshold && result.best.confidence >= FALLBACK_THRESHOLD) {
+		const noDepthResult = findBestFuzzyMatchCore(contentLines, targetLines, offsets, threshold, false);
+		if (noDepthResult.best && noDepthResult.best.confidence > result.best.confidence) {
+			result = noDepthResult;
+		}
+	}
+	return result;
+}
+
+/**
+ * Find a match for target text within content.
+ */
+export function findMatch(
+	content: string,
+	target: string,
+	options: { allowFuzzy: boolean; threshold?: number },
+): MatchOutcome {
+	if (target.length === 0) return {};
+
+	// Try exact match first
+	const exactIndex = content.indexOf(target);
+	if (exactIndex !== -1) {
+		const occurrences = content.split(target).length - 1;
+		if (occurrences > 1) {
+			const contentLines = content.split("\n");
+			const occurrenceLines: number[] = [];
+			const occurrencePreviews: string[] = [];
+			let searchStart = 0;
+			for (let i = 0; i < 5; i++) {
+				const idx = content.indexOf(target, searchStart);
+				if (idx === -1) break;
+				const lineNumber = content.slice(0, idx).split("\n").length;
+				occurrenceLines.push(lineNumber);
+				const start = Math.max(0, lineNumber - 1 - OCCURRENCE_PREVIEW_CONTEXT);
+				const end = Math.min(contentLines.length, lineNumber + OCCURRENCE_PREVIEW_CONTEXT + 1);
+				const previewLines = contentLines.slice(start, end);
+				const preview = previewLines
+					.map((line, idx) => {
+						const num = start + idx + 1;
+						return `  ${num} | ${line.length > OCCURRENCE_PREVIEW_MAX_LEN ? `${line.slice(0, OCCURRENCE_PREVIEW_MAX_LEN - 1)}…` : line}`;
+					})
+					.join("\n");
+				occurrencePreviews.push(preview);
+				searchStart = idx + 1;
+			}
+			return { occurrences, occurrenceLines, occurrencePreviews };
+		}
+		const startLine = content.slice(0, exactIndex).split("\n").length;
+		return {
+			match: { actualText: target, startIndex: exactIndex, startLine, confidence: 1 },
+		};
+	}
+
+	// Try fuzzy match
+	const threshold = options.threshold ?? DEFAULT_FUZZY_THRESHOLD;
+	const { best, aboveThresholdCount, secondBestScore } = findBestFuzzyMatch(content, target, threshold);
+
+	if (!best) return {};
+
+	if (options.allowFuzzy && best.confidence >= threshold) {
+		if (aboveThresholdCount === 1) return { match: best, closest: best };
+		const dominantDelta = 0.08;
+		const dominantMin = 0.97;
+		if (aboveThresholdCount > 1 && best.confidence >= dominantMin && best.confidence - secondBestScore >= dominantDelta) {
+			return { match: best, closest: best, fuzzyMatches: aboveThresholdCount, dominantFuzzy: true };
+		}
+	}
+	return { closest: best, fuzzyMatches: aboveThresholdCount };
+}