pi-hashline-edit-pro 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 RimuruW
+
+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 @@
+# pi-hashline-edit-pro
+
+A [pi-coding-agent](https://github.com/badlogic/pi-mono/tree/main/packages/coding-agent) extension that replaces the built-in `read` and `edit` tools with a hash-anchored line-editing workflow. **Strict semantics** — no silent relocation, no autocorrection, no fuzzy fallback. **Higher-entropy anchors** — 4-character content hashes over a 64-character URL-safe base64 alphabet (24 bits / 16 777 216 buckets) so birthday-paradox collisions are effectively zero in any realistic file.
+
+This is a fork of [pi-hashline-edit](https://github.com/RimuruW/pi-hashline-edit) by RimuruW. The strict-semantics policy is unchanged. This fork extends the upstream design in two compounding ways: a 4-character hash length and an occurrence-aware discriminator that makes identical content at different positions hash to different values.
+
+Every line returned by `read` carries a short content hash. Edits reference those hashes instead of raw text, so the tool can detect stale context and reject outdated changes before they reach the file.
+
+## Why fork?
+
+The original uses 2-character hashes of a 16-character alphabet, with the hash being a pure function of line content. That's 8 bits / 256 buckets, and two byte-identical lines (e.g. repeated `import` statements, repeated `}`) always share a hash because the hash is `xxHash32(content)`.
+
+This fork makes **two** changes that compound:
+
+1. **Bump hash length to 4 characters** of the 64-char URL-safe base64 alphabet → 24 bits / 16 777 216 buckets. Birthday-paradox collisions are effectively nullified for any realistic file.
+2. **Make the hash occurrence-aware.** The hash for line N is `xxHash32("C{occurrence}:{content}")` where `occurrence` is the running count of that content string earlier in the file. Symbol-only lines use `"S{lineNumber}"` as the discriminator. Two `import {...}` statements at different positions now hash to different values, so the model can target a specific occurrence without resorting to `offset` + a small `limit` window.
+
+## Installation
+
+```bash
+# From npm (once published)
+pi install npm:pi-hashline-edit-pro
+
+# From a local checkout
+pi install /path/to/pi-hashline-edit-pro
+```
+
+## How It Works
+
+### `read` — tagged line output
+
+Text files are returned with a `HASH:content` prefix on every line. The line number is no longer part of the wire format — only the 4-character hash followed by the line content. Example output for the source below; the hashes are the real xxHash-derived values for the file content shown:
+
+```js
+function hello() {
+  console.log("world");
+}
+```
+
+would be returned as:
+
+```text
+0qH3:function hello() {
+szJr:  console.log("world");
+_zlP:}
+```
+
+- `HASH` — 4-character content hash from the URL-safe base64 alphabet `A-Za-z0-9-_`.
+
+Optional parameters:
+
+- `offset` — start reading from this line number (1-indexed).
+- `limit` — maximum number of lines to return.
+
+Images (JPEG, PNG, GIF, WebP) are passed through as attachments and do not participate in the hashline protocol. Binary and directory paths are rejected with a descriptive error. Empty files return an advisory suggesting `prepend`/`append` instead of a synthetic anchor.
+
+### `edit` — hash-anchored modifications
+
+Edits use the `HASH:content` anchors from `read` output to target lines precisely:
+
+```json
+{
+  "path": "src/main.ts",
+  "edits": [
+    { "op": "replace", "start": "ve7o", "end": "ve7o", "lines": ["  console.log('hashline');"] }
+  ]
+}
+```
+
+| Op | Purpose | Fields |
+|---|---|---|
+| `replace` | Replace the inclusive range `start`..`end`. To replace a single line, set `start` = `end`. | `start` required, `end` required, `lines` |
+| `append` | Insert lines after `pos`. Omit `pos` to append at EOF. | `pos` optional, `lines` |
+| `prepend` | Insert lines before `pos`. Omit `pos` to prepend at BOF. | `pos` optional, `lines` |
+
+- **Request structure validation.** The request envelope (path, edits, returnMode, returnRanges) and individual edit items are validated before any file I/O. Unknown fields, missing required fields, invalid types, and malformed anchors are rejected with `[E_BAD_SHAPE]` or `[E_BAD_OP]`. This catches structural errors early with actionable messages.
+- **Legacy dialect rejected.** The native top-level `oldText`/`newText` (and `old_text`/`new_text`) dialect and `op: "replace_text"` are rejected with `[E_LEGACY_SHAPE]`. The error message tells the model to call `read` first and send `{op:"replace", start:"<HASH>", end:"<HASH>", lines:[...]}` (or `append`/`prepend` with `pos`).
+
+All edits in a single call validate against the same pre-edit snapshot and apply bottom-up, so line numbers stay consistent across operations.
+
+### Chained edits
+
+After a successful edit, the result text contains an `--- Anchors ---` block with fresh `HASH:content` references for the changed region. These can be used directly in the next `edit` call on the same file without a full re-read, provided the next edit targets the same or nearby lines. For distant changes, use `read` first.
+
+### Auto-read after write
+
+After a successful `write`, the extension automatically reads the file and appends a `--- Auto-read (hashline anchors) ---` block to the result. This gives the model immediate `HASH:content` anchors for the newly written file without requiring a separate `read` call. The workflow becomes:
+
+1. `write` a file → result includes hashline anchors
+2. `edit` using those anchors directly
+
+For large files (>2000 lines), the auto-read output is truncated with a pagination hint. Use `read` with `offset` to see more.
+### Diff for the host
+
+The post-edit diff (with `+`/`-` markers and new `HASH:content` anchors) is exposed to the host UI via `details.diff`. It is intentionally **not** in the LLM-visible text — the model only needs the fresh anchors in `text` to chain follow-up edits, and re-emitting the diff would cost extra tokens.
+
+## Design Decisions
+
+- **Stale anchors fail.** A hash mismatch means the file has changed since the last `read`. The error includes fresh `>>> HASH:content` lines for the affected region; the model copies the HASH portion and retries.
+- **No fallback relocation.** Mismatched anchors are never silently relocated to a "close enough" line. This trades convenience for correctness.
+- **Strict patch content.** If `lines` contains `+HASH:` display prefixes (or `-N   ` diff rows), the edit is rejected with `[E_INVALID_PATCH]`. Bare `HASH:` content (the first 5 chars of a `lines` entry looking like a 4-char hash followed by `:`) is also rejected with `[E_BARE_HASH_PREFIX]` — issue #24. When the suspect's prefix happens to match a real file-line hash, the error message flags that as strong evidence the model copied a hash from the read output; the model should rephrase the line (quote it, escape the colon, or use a different identifier shape) and retry.
+- **Legacy dialect rejected.** The native top-level `oldText`/`newText` (and `old_text`/`new_text`) dialect and `op: "replace_text"` are rejected with `[E_LEGACY_SHAPE]`. The error message tells the model to call `read` first and send `{op:"replace", start:"<HASH>", end:"<HASH>", lines:[...]}` (or `append`/`prepend` with `pos`).
+- **Atomic writes.** Files are written via temp-file-then-rename to avoid corruption from interrupted writes. Symlink chains are resolved so the target file is updated without replacing the symlink. Hard-linked files are updated in place to preserve the shared inode. File permissions are preserved across atomic renames.
+- **Per-file mutation queue.** Edits queue by the canonical write target, so concurrent edits through different symlink paths still serialize onto the same underlying file.
+
+## Hashing
+
+Hashes are computed with [xxhashjs](https://github.com/pierrec/js-xxhash) (xxHash32), then mapped to a 4-character string from the URL-safe base64 alphabet `A-Za-z0-9-_` — 64 distinct characters, 6 bits per position, **24 bits of entropy per anchor**.
+
+The alphabet is sized for an LLM consumer. The model tokenizes — it doesn't squint at pixel glyphs — so the human-readability heuristics used by smaller hand-curated alphabets (no G/L/I/O because they look like digits, no vowels so the hash doesn't accidentally spell a word, no hex digits so it can't be confused with `0xFF`) don't apply. The full 64 chars give maximum entropy per character, with case and digits included.
+
+Hashes are **occurrence-aware**: a discriminator prefix is mixed into the xxHash input before the line content. Symbol-only lines (lone `}`, etc.) use `S{lineNumber}` as the discriminator; content lines use `C{occurrence}` where `occurrence` is the running count of that canonical content earlier in the file. This way:
+
+- `}` on line 5 and `}` on line 17 hash differently (different `S{...}` prefix).
+- `import { foo } from 'bar';` on line 3 and the same string on line 47 hash differently (different `C{...}` prefix — 1 vs 2).
+
+The runtime always precomputes the full per-line hash array for a file via `computeLineHashes(content)`, then looks up by line number during validation and during `read` / `edit` response formatting. There is no per-line recomputation that could disagree with what the model saw in its last read.
+
+`HASH_LENGTH` and `HASH_ALPHABET` are constants at the top of `src/hashline/hash.ts`; bump the length to 5 if you ever need even more entropy.
+
+### Trade-off: the bare-prefix detector
+
+With a 64-char alphabet, the regex `^\s*[A-Za-z0-9_-]{4}:` matches a LOT of code (any 4-char identifier followed by `:` — `todo:`, `done:`, `note:`, `init:`). The "did the model accidentally paste a hash into its content?" detector used to fire on a count-based heuristic (too noisy at 64 chars), then on a "strong signal" gate (the prefix matches a real file-line hash) and only warned, then escalated to a strict rejection. Today the first 5 characters of every `lines` entry are checked; if they look like a 4-char hash followed by `:`, the edit is rejected with `[E_BARE_HASH_PREFIX]`. The false-positive cost (rejecting `init:`, `data:`, etc.) is real but small: the model can rephrase the line (quote it, add a leading space, use a different identifier shape) and retry. The false-negative cost (a stray hash in the file) is silent and catastrophic.
+
+## Development
+
+Requires [Node.js](https://nodejs.org) and npm.
+
+```bash
+npm install
+npm test
+```
+
+Set `PI_HASHLINE_DEBUG=1` to show an "active" notification at session start.
+
+## Credits
+
+- [RimuruW](https://github.com/RimuruW) — original `pi-hashline-edit` and the strict-semantics policy
+- [can1357](https://github.com/can1357) — original [oh-my-pi](https://github.com/can1357/oh-my-pi) implementation and the hashline concept
+
+## License
+
+[MIT](LICENSE)

package/index.ts

@@ -0,0 +1,64 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { readFile } from "fs/promises";
+import { join, isAbsolute } from "path";
+import { computeLineHashes, formatHashlineRegion } from "./src/hashline";
+import { registerEditTool } from "./src/edit";
+import { registerReadTool } from "./src/read";
+
+export default function (pi: ExtensionAPI): void {
+  registerReadTool(pi);
+  registerEditTool(pi);
+
+  // Auto-read after write: append hashline read output to write results
+  // so the model immediately has anchors for subsequent edits.
+  pi.on("tool_result", async (event, ctx) => {
+    if (event.toolName !== "write" || event.isError) return;
+
+    const filePath = (event.input as Record<string, unknown>)?.path;
+    if (typeof filePath !== "string") return;
+
+    try {
+      const absolutePath = isAbsolute(filePath) ? filePath : join(ctx.cwd, filePath);
+      const content = await readFile(absolutePath, "utf-8");
+
+      // Normalize and compute hashline output
+      const normalized = content.replace(/\r\n/g, "\n").replace(/\r/g, "\n");
+      const lines = normalized.split("\n");
+      const visibleLines = normalized.endsWith("\n") ? lines.slice(0, -1) : lines;
+
+      if (visibleLines.length === 0) return;
+
+      // Truncate to a reasonable limit to avoid excessive token usage
+      const MAX_LINES = 2000;
+      const truncated = visibleLines.length > MAX_LINES;
+      const displayLines = truncated ? visibleLines.slice(0, MAX_LINES) : visibleLines;
+
+      const hashes = computeLineHashes(normalized);
+      const selectedHashes = hashes.slice(0, displayLines.length);
+      const hashlineOutput = formatHashlineRegion(selectedHashes, displayLines);
+
+      // Add pagination hint if truncated
+      const paginationHint = truncated
+        ? `\n\n[Showing lines 1-${MAX_LINES} of ${visibleLines.length}. Use offset=${MAX_LINES + 1} to continue.]`
+        : "";
+
+      if (hashlineOutput) {
+        return {
+          content: [
+            ...(event.content ?? []),
+            { type: "text", text: `\n\n--- Auto-read (hashline anchors) ---\n${hashlineOutput}${paginationHint}` },
+          ],
+        };
+      }
+    } catch {
+      // Auto-read failure should not affect write result
+    }
+  });
+
+  const debugValue = process.env.PI_HASHLINE_DEBUG;
+  if (debugValue === "1" || debugValue === "true") {
+    pi.on("session_start", async (_event, ctx) => {
+      ctx.ui.notify("Hashline Edit mode active", "info");
+    });
+  }
+}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "pi-hashline-edit-pro",
+  "version": "0.2.0",
+  "description": "Strict hashline read/edit tool override for pi-coding-agent with hash-anchored edits (4-char, 24-bit)",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/YuGiMob/pi-hashline-edit-pro.git"
+  },
+  "author": "pi-hashline-edit-pro contributors",
+  "keywords": [
+    "pi-package",
+    "pi",
+    "coding-agent",
+    "extension",
+    "hashline",
+    "hash-anchored",
+    "strict"
+  ],
+  "license": "MIT",
+  "files": [
+    "index.ts",
+    "src",
+    "prompts",
+    "README.md",
+    "LICENSE"
+  ],
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ]
+  },
+  "dependencies": {
+    "diff": "^8.0.2",
+    "file-type": "^21.3.0",
+    "xxhashjs": "^0.2.2"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": ">=0.74.0",
+    "@earendil-works/pi-tui": "*",
+    "@sinclair/typebox": "*"
+  },
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "^0.74.0",
+    "@types/node": "^22.0.0",
+    "@types/xxhashjs": "^0.2.4",
+    "vitest": "^4.1.8"
+  }
+}

package/prompts/edit-snippet.md

@@ -0,0 +1 @@
+Edit a text file via bare HASH anchors from read

package/prompts/edit.md

@@ -0,0 +1,58 @@
+Patch a text file using `HASH` anchors copied verbatim from `read`.
+
+Put all operations on one file in a single `edit` call. Stack every region into the `edits` array, even when they are far apart. Anchors within one call must all come from the same pre-edit read; the runtime applies them atomically against that one snapshot, so you do not adjust anchors for line-number shifts between edits in the same call.
+
+Hashes are 4 characters (e.g. `aB3x`), alphabet `A-Za-z0-9-_`. The wire format for `start`/`end`/`pos` is the bare hash only — no line number, no trailing content, no `HASH:content` form.
+
+Ops:
+- `replace` — replace the inclusive range `start`..`end`. Both anchors are required. Single line: `start = end`. To delete a range, use `lines: []`. Do NOT use the `pos` field on `replace`; use `start`.
+- `append` — insert `lines` after `pos`; omit `pos` to append at EOF.
+- `prepend` — insert `lines` before `pos`; omit `pos` to prepend at BOF. Use `prepend` at an anchor to insert a new block between line N-1 and N (anchor on the line *after* the insertion point).
+
+Examples:
+
+1. Single line replace:
+```json
+{ "path": "src/main.ts", "edits": [
+  { "op": "replace", "start": "MQXV", "end": "MQXV", "lines": ["const x = 1;"] }
+] }
+```
+
+2. Range replace (3 lines → 3 new lines):
+```json
+{ "path": "src/main.ts", "edits": [
+  { "op": "replace", "start": "ZPMQ", "end": "VRWS", "lines": [
+    "function greet(name) {",
+    "  return `Hello, ${name}`;",
+    "}"
+  ] }
+] }
+```
+
+3. Multiple regions in one call (delete two non-adjacent ranges, insert before a third anchor):
+```json
+{ "path": "src/server.ts", "edits": [
+  { "op": "replace", "start": "aB3x", "end": "xY7q", "lines": [] },
+  { "op": "replace", "start": "MQXV", "end": "ZPMQ", "lines": [] },
+  { "op": "prepend", "pos": "VRWS", "lines": ["// inserted before VRWS"] }
+] }
+```
+
+Rules:
+- `replace` requires both `start` and `end`. A single-line replace is `start=X, end=X`. To replace more than one line, set `end` to a different line's hash.
+- `start`, `end`, `pos` are bare 4-character HASH strings only. Other forms are rejected with `[E_BAD_REF]`.
+- `lines` is literal file content. No `HASH:` prefix, no leading `+`/`-` (those are read/diff metadata, not file content). The first 5 characters of every `lines` entry are checked; if they look like a 4-char hash followed by `:` (after any leading whitespace), the edit is rejected with `[E_BARE_HASH_PREFIX]`. For `.py` files, this becomes a `[W_BARE_HASH_PREFIX]` warning instead (Python syntax like `else:`, `except:` triggers the detector).
+- Copy anchors from the most recent `read` of the file. Do not guess or construct them.
+- All edits in one call must be non-conflicting. The runtime rejects with `[E_EDIT_CONFLICT]` if: two `replace` ranges overlap; two `append`/`prepend` target the same insertion boundary (e.g. two EOF appends on a newline-terminated file); or an `append`/`prepend` falls inside a `replace` range in the same call. Fix: merge into one, use different boundaries, or split into a follow-up `edit` call.
+- If `lines` matches the current content byte-for-byte, the edit is classified as `Classification: noop` (file unchanged, not an error).
+
+On success (`changed` mode, default), the response text contains an `--- Anchors ---` block with fresh `HASH:content` for the changed region (2 lines of context, capped at ~12 lines / 50 KB). Use those for nearby follow-up edits instead of re-reading. If the response says `Anchors omitted; use read for subsequent edits`, the region was too large — call `read` again. For distant follow-ups, or on any error, call `read` again. `full` and `ranges` modes put previews in `details`; the model only needs what's in the text.
+
+Errors are text starting with a bracketed code (e.g. `[E_BAD_SHAPE]`, `[E_STALE_ANCHOR]`, `[E_BAD_OP]`, `[E_INVALID_PATCH]`, `[E_LEGACY_SHAPE]`, `[E_EDIT_CONFLICT]`, `[E_BAD_REF]`, `[E_AMBIGUOUS_ANCHOR]`, `[E_BARE_HASH_PREFIX]`, `[E_WOULD_EMPTY]`). The message tells you what to retry; stale-anchor errors include `>>> HASH:content` lines, ready to copy.
+
+The legacy `oldText`/`newText` shape (top-level or as `op: "replace_text"`) is rejected with `[E_LEGACY_SHAPE]`. Use hash-anchored edits instead.
+
+Auto-read after write:
+- After a successful `write`, the result includes a `--- Auto-read (hashline anchors) ---` block with HASH:content for the written file.
+- Use those anchors directly for `edit` calls without a separate `read`.
+- This enables a seamless write → edit workflow with no extra tool calls.

package/prompts/read-guidelines.md

@@ -0,0 +1,3 @@
+- Use read before edit when you do not have current HASH anchors for the file.
+- Copy exactly the 4-character HASH (the part before the `:`); never include the `:` or line content in `pos`/`end`.
+- A HASH may start with `-`; that is a normal alphabet character, not a diff-remove marker.

package/prompts/read-snippet.md

@@ -0,0 +1 @@
+Read a text file with HASH:content anchors for edit (copy the HASH portion into `start`/`end`/`pos`)

package/prompts/read.md

@@ -0,0 +1,28 @@
+Read a text file. Each line is returned as `HASH:content`. The HASH is the 4 characters before the first `:`; the content after is the line verbatim. Pass the 4-character HASH into `edit`'s `start`/`end` (for `replace`) or `pos` (for `append`/`prepend`) — never the rendered `HASH:content` form.
+
+HASH shape:
+- 4 characters (e.g. `aB3x`), from the URL-safe base64 alphabet `A-Za-z0-9-_`. A HASH can start with any of these characters, including `-`. A leading `-` is a normal alphabet char, not a diff-remove marker.
+- The line number is not part of the wire format. Anchor by HASH, never by reading a line number off the rendered output.
+
+HASH → edit:
+- Copy exactly the 4 characters before the `:`. Use that bare 4-character HASH as `start` or `end` (for `replace`) or `pos` (for `append`/`prepend`) in the next `edit` call.
+- Do not include the `:`, the line content, or surrounding whitespace. The wire format for `start`/`end`/`pos` is the bare 4-character HASH only.
+
+Pagination:
+- Large files return a truncated preview with a `nextOffset` line. Call `read` again with `offset=nextOffset` to continue.
+- For nearby follow-up edits, prefer the `--- Anchors ---` block from a previous `edit` call — fresh HASHes, cheaper than re-reading.
+- Empty files return an advisory suggesting `prepend`/`append` instead of a synthetic anchor.
+
+Error recovery:
+- `[E_STALE_ANCHOR]` — the file changed since your last read. The error includes fresh `>>> HASH:content` lines; copy the HASH portion (4 chars before `:`) and retry.
+- `[E_BAD_REF]` — malformed HASH. Re-read and try again with a valid 4-character HASH.
+
+File kinds:
+- Text files are returned as `HASH:content` lines.
+- Images (JPEG, PNG, GIF, WebP) are returned as visual attachments; the HASH-line protocol does not apply.
+- Binary files and directories are rejected with a descriptive error.
+
+Auto-read after write:
+- After a successful `write`, the result includes a `--- Auto-read (hashline anchors) ---` block with HASH:content for the written file.
+- Use those anchors directly for `edit` calls without a separate `read`.
+- The auto-read output follows the same format and rules as `read` output.

package/src/edit-diff.ts

@@ -0,0 +1,234 @@
+import * as Diff from "diff";
+import {
+  computeLineHashes,
+  HASH_LENGTH,
+} from "./hashline";
+
+// ─── Line ending normalization ──────────────────────────────────────────
+
+export function detectLineEnding(content: string): "\r\n" | "\n" {
+  const crlfIdx = content.indexOf("\r\n");
+  const lfIdx = content.indexOf("\n");
+  if (lfIdx === -1 || crlfIdx === -1) return "\n";
+  return crlfIdx < lfIdx ? "\r\n" : "\n";
+}
+
+export function normalizeToLF(text: string): string {
+  return text.replace(/\r\n/g, "\n").replace(/\r/g, "\n");
+}
+
+export function restoreLineEndings(
+  text: string,
+  ending: "\r\n" | "\n",
+): string {
+  return ending === "\r\n" ? text.replace(/\n/g, "\r\n") : text;
+}
+
+export function stripBom(content: string): { bom: string; text: string } {
+  return content.startsWith("\uFEFF")
+    ? { bom: "\uFEFF", text: content.slice(1) }
+    : { bom: "", text: content };
+}
+
+// ─── Diff generation ────────────────────────────────────────────────────
+
+function formatDiffPreviewLine(
+  prefix: " " | "+" | "-",
+  line: string,
+  hash: string | undefined,
+): string {
+  if (hash === undefined) {
+    // Removed lines have no hash, but they still need column alignment with
+    // the hash-prefixed lines (` HASH:`, `+HASH:`). Pad with `HASH_LENGTH`
+    // spaces so the `:` lines up in the same column.
+    return `${prefix}${" ".repeat(HASH_LENGTH)}:${line}`;
+  }
+  return `${prefix}${hash}:${line}`;
+}
+
+export function generateDiffString(
+  oldContent: string,
+  newContent: string,
+  contextLines = 4,
+  newContentHashes?: string[],
+): { diff: string; firstChangedLine: number | undefined } {
+  const parts = Diff.diffLines(oldContent, newContent);
+  const output: string[] = [];
+  const effectiveNewHashes = newContentHashes ?? computeLineHashes(newContent);
+
+  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) {
+          const hash = effectiveNewHashes[newLineNum - 1];
+          output.push(formatDiffPreviewLine("+", line, hash));
+          newLineNum++;
+        } else {
+          output.push(
+            formatDiffPreviewLine("-", line, undefined),
+          );
+          oldLineNum++;
+        }
+      }
+      lastWasChange = true;
+      continue;
+    }
+
+    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(` ...`);
+        oldLineNum += skipStart;
+        newLineNum += skipStart;
+      }
+      for (const line of linesToShow) {
+        const hash = effectiveNewHashes[newLineNum - 1];
+        output.push(formatDiffPreviewLine(" ", line, hash));
+
+        oldLineNum++;
+        newLineNum++;
+      }
+      if (skipEnd > 0) {
+        output.push(` ...`);
+        oldLineNum += skipEnd;
+        newLineNum += skipEnd;
+      }
+    } else {
+      oldLineNum += raw.length;
+      newLineNum += raw.length;
+    }
+    lastWasChange = false;
+  }
+
+  return { diff: output.join("\n"), firstChangedLine };
+}
+
+export interface CompactHashlineDiffPreview {
+  preview: string;
+  addedLines: number;
+  removedLines: number;
+}
+
+type DiffPreviewKind = "context" | "addition" | "deletion";
+
+function classifyDiffPreviewLine(line: string): DiffPreviewKind | null {
+  if (line.startsWith("+")) return "addition";
+  if (line.startsWith("-")) return "deletion";
+  if (line.startsWith(" ")) return "context";
+  return null;
+}
+
+function summarizeOmitted(count: number, label: string): string {
+  return `... ${count} more ${label} line${count === 1 ? "" : "s"}`;
+}
+
+function collapseDiffPreviewRun(
+  lines: string[],
+  maxVisible: number,
+  label: string,
+): string[] {
+  if (lines.length <= maxVisible) {
+    return lines;
+  }
+
+  return [
+    ...lines.slice(0, maxVisible),
+    summarizeOmitted(lines.length - maxVisible, label),
+  ];
+}
+
+export function buildCompactHashlineDiffPreview(
+  diff: string,
+  options: {
+    maxUnchangedRun?: number;
+    maxAdditionRun?: number;
+    maxDeletionRun?: number;
+    maxOutputLines?: number;
+  } = {},
+): CompactHashlineDiffPreview {
+  const {
+    maxUnchangedRun = 2,
+    maxAdditionRun = 4,
+    maxDeletionRun = 4,
+    maxOutputLines = 12,
+  } = options;
+
+  if (!diff.trim()) {
+    return { preview: "", addedLines: 0, removedLines: 0 };
+  }
+
+  const lines = diff.split("\n").filter((line) => line.length > 0);
+  const previewLines: string[] = [];
+  let addedLines = 0;
+  let removedLines = 0;
+
+  for (let index = 0; index < lines.length; ) {
+    const kind = classifyDiffPreviewLine(lines[index]!);
+    let end = index + 1;
+    while (end < lines.length && classifyDiffPreviewLine(lines[end]!) === kind) {
+      end += 1;
+    }
+
+    const run = lines.slice(index, end);
+    switch (kind) {
+      case "addition":
+        addedLines += run.length;
+        previewLines.push(...collapseDiffPreviewRun(run, maxAdditionRun, "added"));
+        break;
+      case "deletion":
+        removedLines += run.length;
+        previewLines.push(...collapseDiffPreviewRun(run, maxDeletionRun, "removed"));
+        break;
+      case "context":
+        previewLines.push(...collapseDiffPreviewRun(run, maxUnchangedRun, "unchanged"));
+        break;
+      default:
+        previewLines.push(...run);
+        break;
+    }
+
+    index = end;
+  }
+
+  if (previewLines.length > maxOutputLines) {
+    const visibleLines = previewLines.slice(0, maxOutputLines);
+    visibleLines.push(
+      summarizeOmitted(previewLines.length - maxOutputLines, "preview"),
+    );
+    return {
+      preview: visibleLines.join("\n"),
+      addedLines,
+      removedLines,
+    };
+  }
+
+  return {
+    preview: previewLines.join("\n"),
+    addedLines,
+    removedLines,
+  };
+}