@mammothb/pi-hashline 0.2.0

package/LICENSE

@@ -0,0 +1,18 @@
+MIT License
+
+Copyright (c) 2026 mammothb
+
+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/index.ts

@@ -0,0 +1,36 @@
+/**
+ * Hashline anchoring for pi — content-addressed read/edit with stale-edit
+ * protection.
+ *
+ * To activate, load this extension:
+ *   pi -e ./index.ts
+ *
+ * @module
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+import { createEditTool } from "./src/edit";
+import { createGrepTool } from "./src/grep";
+import { injectPrompt } from "./src/prompt";
+import { createReadTool } from "./src/read";
+import { InMemorySnapshotStore } from "./src/snapshots";
+import { createWriteTool } from "./src/write";
+
+export * from "./src/format";
+export * from "./src/snapshots";
+export * from "./src/types";
+
+export default function (pi: ExtensionAPI) {
+  const snapshots = new InMemorySnapshotStore();
+
+  pi.registerTool(createReadTool(snapshots));
+  pi.registerTool(createEditTool(snapshots));
+  pi.registerTool(createWriteTool(snapshots));
+  pi.registerTool(createGrepTool(snapshots));
+
+  // Inject the hashline grammar prompt before each agent turn.
+  pi.on("context", (event, _ctx) => {
+    injectPrompt(event.messages);
+  });
+}

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@mammothb/pi-hashline",
+  "version": "0.2.0",
+  "description": "Hashline anchoring for pi — content-addressed read/edit with stale-edit protection",
+  "keywords": [
+    "pi-package"
+  ],
+  "license": "MIT",
+  "files": [
+    "index.ts",
+    "src"
+  ],
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ]
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*",
+    "typebox": "*"
+  },
+  "dependencies": {
+    "diff": "^8.0.0"
+  }
+}

package/src/apply.ts

@@ -0,0 +1,255 @@
+/**
+ * Apply a parsed list of {@link Edit}s to a text body.
+ *
+ * Pure function — no filesystem, no tag validation. Handles insert ordering
+ * so that deletes don't shift insert anchors (all anchors are pre-edit line
+ * numbers). Deletes are applied back-to-front; inserts within each anchor
+ * line preserve order (before-anchor → replacement → after-anchor).
+ */
+
+import { cloneCursor } from "./tokenizer";
+import type { Anchor, ApplyResult, Edit } from "./types";
+
+// ─── Internal types ──────────────────────────────────────────────────
+
+type InsertEdit = Extract<Edit, { kind: "insert" }>;
+type DeleteEdit = Extract<Edit, { kind: "delete" }>;
+type AppliedEdit = InsertEdit | DeleteEdit;
+
+interface IndexedEdit {
+  edit: AppliedEdit;
+  idx: number;
+}
+
+// ─── Helpers ─────────────────────────────────────────────────────────
+
+function isReplacementInsert(
+  edit: Edit,
+): edit is InsertEdit & { mode: "replacement" } {
+  return edit.kind === "insert" && edit.mode === "replacement";
+}
+
+/** Clone an edit so the applier owns its own copies. */
+function cloneAppliedEdit(edit: AppliedEdit, index: number): AppliedEdit {
+  if (edit.kind === "delete") {
+    return { ...edit, anchor: { ...edit.anchor }, index };
+  }
+  return { ...edit, cursor: cloneCursor(edit.cursor), index };
+}
+
+/** Collect anchors from an edit for line-bound validation. */
+function getEditAnchors(edit: AppliedEdit): Anchor[] {
+  if (edit.kind === "delete") {
+    return [edit.anchor];
+  }
+  if (
+    edit.cursor.kind === "before_anchor" ||
+    edit.cursor.kind === "after_anchor"
+  ) {
+    return [edit.cursor.anchor];
+  }
+  return [];
+}
+
+// ─── Validation ──────────────────────────────────────────────────────
+
+/**
+ * Verify every anchored edit points at an existing line.
+ * bof/eof inserts are exempt — they don't target a line number.
+ */
+function validateLineBounds(edits: AppliedEdit[], totalLines: number): void {
+  for (const edit of edits) {
+    for (const anchor of getEditAnchors(edit)) {
+      if (anchor.line < 1 || anchor.line > totalLines) {
+        throw new Error(
+          `Line ${anchor.line} does not exist (file has ${totalLines} lines)`,
+        );
+      }
+    }
+  }
+}
+
+// ─── Insert-at-boundary helpers ──────────────────────────────────────
+
+/**
+ * Insert lines at the start of the file.
+ * Handles the edge case where the file is just `[""]` (empty).
+ */
+function insertAtStart(
+  fileLines: string[],
+  lines: string[],
+): number | undefined {
+  if (lines.length === 0) {
+    return undefined;
+  }
+  if (fileLines.length === 1 && fileLines[0] === "") {
+    fileLines.splice(0, 1, ...lines);
+    return 1;
+  }
+  fileLines.splice(0, 0, ...lines);
+  return 1;
+}
+
+/**
+ * Insert lines at the end of the file.
+ * Handles the trailing-newline convention (last element is `""`).
+ * Returns the first changed line (1-indexed).
+ */
+function insertAtEnd(fileLines: string[], lines: string[]): number | undefined {
+  if (lines.length === 0) {
+    return undefined;
+  }
+  if (fileLines.length === 1 && fileLines[0] === "") {
+    fileLines.splice(0, 1, ...lines);
+    return 1;
+  }
+  // If file ends with `""` (trailing newline), insert before it.
+  const insertIdx =
+    fileLines.length > 0 && fileLines[fileLines.length - 1] === ""
+      ? fileLines.length - 1
+      : fileLines.length;
+  fileLines.splice(insertIdx, 0, ...lines);
+  return insertIdx + 1;
+}
+
+// ─── Bucket edits by anchor line ─────────────────────────────────────
+
+function bucketByLine(edits: IndexedEdit[]): Map<number, IndexedEdit[]> {
+  const byLine = new Map<number, IndexedEdit[]>();
+  for (const entry of edits) {
+    const line =
+      entry.edit.kind === "delete"
+        ? entry.edit.anchor.line
+        : entry.edit.cursor.kind === "before_anchor" ||
+            entry.edit.cursor.kind === "after_anchor"
+          ? entry.edit.cursor.anchor.line
+          : 0; // won't be used (bof/eof are partitioned out)
+    const bucket = byLine.get(line);
+    if (bucket) bucket.push(entry);
+    else byLine.set(line, [entry]);
+  }
+  return byLine;
+}
+
+// ─── Core applier ────────────────────────────────────────────────────
+
+/**
+ * Apply a parsed list of edits to a text body.
+ *
+ * All line numbers are relative to the pre-edit file. Deletes are applied
+ * back-to-front so earlier indices stay valid; inserts within a single anchor
+ * line are ordered: before-anchor → replacement → current line (if not
+ * deleted) → after-anchor.
+ *
+ * Throws if a block edit reaches here unresolved (should have been expanded
+ * by `resolveBlockEdits` before calling).
+ */
+export function applyEdits(text: string, edits: readonly Edit[]): ApplyResult {
+  if (edits.length === 0) {
+    return { text };
+  }
+  // Block edits must be resolved before reaching the applier.
+  for (const edit of edits) {
+    if (edit.kind === "block") {
+      throw new Error(
+        "internal error: unresolved `replace block` edit reached the applier (resolveBlockEdits was not run).",
+      );
+    }
+  }
+
+  const fileLines = text.split("\n");
+  let firstChangedLine: number | undefined;
+
+  const track = (line: number) => {
+    if (firstChangedLine === undefined || line < firstChangedLine) {
+      firstChangedLine = line;
+    }
+  };
+
+  // Clone edits so we own the objects.
+  const cloned = (edits as readonly AppliedEdit[]).map((edit, index) =>
+    cloneAppliedEdit(edit, index),
+  );
+
+  // Partition: bof, eof, anchored.
+  const bofLines: string[] = [];
+  const eofLines: string[] = [];
+  const anchorEdits: IndexedEdit[] = [];
+
+  for (const edit of cloned) {
+    if (edit.kind === "insert" && edit.cursor.kind === "bof") {
+      bofLines.push(edit.text);
+    } else if (edit.kind === "insert" && edit.cursor.kind === "eof") {
+      eofLines.push(edit.text);
+    } else {
+      anchorEdits.push({ edit, idx: edit.index });
+    }
+  }
+
+  // Validate anchored edits point at existing lines.
+  validateLineBounds(
+    anchorEdits.map((e) => e.edit),
+    fileLines.length,
+  );
+
+  // Group anchored edits by target line, process back-to-front.
+  const byLine = bucketByLine(anchorEdits);
+
+  for (const line of [...byLine.keys()].sort((a, b) => b - a)) {
+    const bucket = byLine.get(line);
+    if (!bucket) {
+      continue;
+    }
+    // Stable sort by original edit index within the bucket.
+    bucket.sort((a, b) => a.idx - b.idx);
+
+    const before: string[] = [];
+    const replacement: string[] = [];
+    const after: string[] = [];
+    let deleted = false;
+
+    for (const { edit } of bucket) {
+      if (isReplacementInsert(edit)) {
+        replacement.push(edit.text);
+      } else if (
+        edit.kind === "insert" &&
+        edit.cursor.kind === "after_anchor"
+      ) {
+        after.push(edit.text);
+      } else if (edit.kind === "insert") {
+        before.push(edit.text);
+      } else if (edit.kind === "delete") {
+        deleted = true;
+      }
+    }
+
+    // No-op bucket (shouldn't happen after validation).
+    if (
+      before.length === 0 &&
+      replacement.length === 0 &&
+      after.length === 0 &&
+      !deleted
+    ) {
+      continue;
+    }
+
+    const idx = line - 1;
+    const currentLine = fileLines[idx] ?? "";
+
+    const newContent = deleted
+      ? [...before, ...replacement, ...after]
+      : [...before, ...replacement, currentLine, ...after];
+
+    fileLines.splice(idx, 1, ...newContent);
+    track(line);
+  }
+
+  // Apply boundary inserts.
+  const bofChanged = insertAtStart(fileLines, bofLines);
+  if (bofChanged !== undefined) track(bofChanged);
+
+  const eofChanged = insertAtEnd(fileLines, eofLines);
+  if (eofChanged !== undefined) track(eofChanged);
+
+  return { text: fileLines.join("\n"), firstChangedLine };
+}

package/src/edit.ts

@@ -0,0 +1,313 @@
+/**
+ * Hashline edit tool override.
+ *
+ * Overrides the built-in `edit` tool to use hashline anchoring. Every edit
+ * must include a `¶PATH#TAG` header copied from the most recent `read`
+ * output. The tag is validated against the live file before any writes
+ * happen — stale tags are rejected with a {@link MismatchError}.
+ *
+ * Multi-section edits (multiple files in one call) are atomic: all sections
+ * are preflighted before any file is written.
+ */
+
+import { constants } from "node:fs";
+import { access, mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, isAbsolute, relative, resolve } from "node:path";
+import type { ToolDefinition } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+
+import { applyEdits } from "./apply";
+import {
+  computeFileHash,
+  formatHashlineHeader,
+  formatNumberedLines,
+} from "./format";
+import { Patch, type PatchSection } from "./input";
+import {
+  HEADTAIL_DRIFT_WARNING,
+  MismatchError,
+  missingTagMessage,
+  nonExistentFileMessage,
+  unrecognizedHashMessage,
+} from "./messages";
+import {
+  detectLineEnding,
+  normalizeToLF,
+  restoreLineEndings,
+} from "./normalize";
+import { tryRecover } from "./recovery";
+import type { SnapshotStore } from "./snapshots";
+
+// ─── Schema ──────────────────────────────────────────────────────────
+
+const EditSchema = Type.Object({
+  edits: Type.String({
+    description:
+      "Hashline patch text: one or more ¶PATH#TAG sections followed by edit operations " +
+      "(replace N..M:, delete N..M, insert before|after|head|tail:). Copy the ¶PATH#TAG " +
+      "header from the read tool output.",
+  }),
+});
+
+// ─── Details type ────────────────────────────────────────────────────
+
+export interface EditToolDetails {
+  /** Per-file results. */
+  files: EditFileResult[];
+  /** Whether any files were changed. */
+  changed: boolean;
+}
+
+export interface EditFileResult {
+  /** Display-relative path. */
+  path: string;
+  /** New snapshot tag after the edit. */
+  fileHash: string;
+  /** Hashline header for the new version. */
+  header: string;
+  /** First changed line (1-indexed), or undefined for no-op. */
+  firstChangedLine?: number;
+  /** Warnings from parsing or drift. */
+  warnings?: string[];
+  /** Numbered preview lines around the change. */
+  preview: string;
+}
+
+// ─── Helpers ─────────────────────────────────────────────────────────
+
+function resolveDisplayPath(rawPath: string, cwd: string): string {
+  const resolved = resolve(cwd, rawPath);
+  try {
+    const rel = relative(cwd, resolved);
+    if (!rel.startsWith("..") && !isAbsolute(rel)) {
+      return rel || ".";
+    }
+  } catch {
+    // Fall through.
+  }
+  return resolved;
+}
+
+/** Show up to 20 lines around the first changed line. */
+function formatPreview(text: string, firstChangedLine?: number): string {
+  if (firstChangedLine === undefined) {
+    return formatNumberedLines(text.split("\n").slice(0, 10).join("\n"), 1);
+  }
+  const lines = text.split("\n");
+  const start = Math.max(0, firstChangedLine - 1 - 5);
+  const end = Math.min(lines.length, firstChangedLine - 1 + 15);
+  return formatNumberedLines(lines.slice(start, end).join("\n"), start + 1);
+}
+
+// ─── Preflight result ────────────────────────────────────────────────
+
+interface PreflightEntry {
+  section: PatchSection;
+  absPath: string;
+  displayPath: string;
+  normalized: string;
+  lineEnding: "\r\n" | "\n";
+  liveHash: string;
+}
+
+// ─── Tool creator ────────────────────────────────────────────────────
+
+export function createEditTool(
+  snapshots: SnapshotStore,
+): ToolDefinition<typeof EditSchema, EditToolDetails> {
+  return {
+    name: "edit",
+    label: "Edit",
+    description:
+      "Edit files using hashline anchoring. Copy the ¶PATH#TAG header from the read " +
+      "tool output and write edit operations (replace, delete, insert) below it. " +
+      "The tag validates you're editing the version you read — stale tags are rejected " +
+      "so you must re-read the file if it changed.",
+    promptSnippet:
+      "Edit files with hashline anchoring — copy ¶PATH#TAG from read/grep/write output",
+    promptGuidelines: [
+      "Use edit to modify existing files. Copy the ¶PATH#TAG header from your most recent read, grep, or write output — the tag is REQUIRED. Use the write tool to create new files.",
+      "After every edit, the file gets a new tag and renumbered lines. Always take the next edit's ¶PATH#TAG and line numbers from the edit response or a fresh read — never reuse old tags.",
+      "On a stale-tag rejection (file changed between read and edit), STOP and re-read the file. Never stack more edits onto stale numbers.",
+      "Use replace N..M: for changes, delete N..M for removal, insert before/after/head/tail: for additions. Body rows are +TEXT only — no -old rows or bare context lines.",
+    ],
+    parameters: EditSchema,
+
+    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+      const { edits: patchText } = params;
+
+      // 1. Parse the patch input.
+      let patch: Patch;
+      try {
+        patch = Patch.parse(patchText, { cwd: ctx.cwd });
+      } catch (err: unknown) {
+        const message =
+          err instanceof Error ? err.message : "invalid edit input";
+        return {
+          content: [{ type: "text", text: `Edit parse error: ${message}` }],
+          details: { files: [], changed: false },
+        };
+      }
+
+      // 2. Preflight: read all files, validate tags.
+      const preflight: PreflightEntry[] = [];
+      const warnings: string[] = [];
+
+      for (const section of patch.sections) {
+        const absPath = resolve(ctx.cwd, section.path);
+        const displayPath = resolveDisplayPath(section.path, ctx.cwd);
+
+        // Check file exists.
+        let rawContent: string;
+        try {
+          await access(absPath, constants.R_OK);
+          rawContent = await readFile(absPath, "utf-8");
+        } catch {
+          return {
+            content: [
+              { type: "text", text: nonExistentFileMessage(displayPath) },
+            ],
+            details: { files: [], changed: false },
+          };
+        }
+
+        // Normalize and hash live content.
+        const lineEnding = detectLineEnding(rawContent);
+        const normalized = normalizeToLF(rawContent);
+        const liveHash = computeFileHash(normalized);
+
+        // Validate tag.
+        if (section.fileHash === undefined) {
+          return {
+            content: [{ type: "text", text: missingTagMessage(displayPath) }],
+            details: { files: [], changed: false },
+          };
+        }
+
+        if (section.fileHash !== liveHash) {
+          // Head/tail-only inserts on stale tag: apply with warning.
+          if (!section.hasAnchoredEdit) {
+            warnings.push(HEADTAIL_DRIFT_WARNING);
+            preflight.push({
+              section,
+              absPath,
+              displayPath,
+              normalized,
+              lineEnding,
+              liveHash,
+            });
+            continue;
+          }
+
+          // Anchored edits on stale tag: try recovery first.
+          const anchorLines = section.collectAnchorLines();
+          const recovered = tryRecover(
+            snapshots,
+            absPath,
+            normalized,
+            section.fileHash,
+            section.edits,
+            anchorLines,
+          );
+
+          if (recovered !== null) {
+            // Recovery succeeded — use recovered text as the base.
+            warnings.push(recovered.warning);
+            preflight.push({
+              section,
+              absPath,
+              displayPath,
+              normalized: recovered.text,
+              lineEnding,
+              liveHash: computeFileHash(recovered.text),
+            });
+            continue;
+          }
+
+          // Recovery failed.
+          const snapshot = snapshots.byHash(absPath, section.fileHash);
+          if (snapshot === null) {
+            return {
+              content: [
+                {
+                  type: "text",
+                  text: unrecognizedHashMessage(section.fileHash),
+                },
+              ],
+              details: { files: [], changed: false },
+            };
+          }
+
+          throw new MismatchError(
+            displayPath,
+            section.fileHash,
+            liveHash,
+            normalized,
+            anchorLines,
+          );
+        }
+
+        preflight.push({
+          section,
+          absPath,
+          displayPath,
+          normalized,
+          lineEnding,
+          liveHash,
+        });
+      }
+
+      // 3. Apply all edits (atomic — preflight passed for all).
+      const fileResults: EditFileResult[] = [];
+
+      for (const pf of preflight) {
+        const {
+          text: newText,
+          firstChangedLine,
+          warnings: applyWarnings,
+        } = applyEdits(pf.normalized, pf.section.edits);
+
+        // Restore line endings and write.
+        const output = restoreLineEndings(newText, pf.lineEnding);
+        await mkdir(dirname(pf.absPath), { recursive: true });
+        await writeFile(pf.absPath, output, "utf-8");
+
+        // Record fresh snapshot.
+        const newHash = snapshots.record(pf.absPath, newText);
+        const header = formatHashlineHeader(pf.displayPath, newHash);
+        const preview = formatPreview(newText, firstChangedLine);
+
+        const fileWarnings = [
+          ...(pf.section.fileHash !== pf.liveHash ? warnings : []),
+          ...(applyWarnings ?? []),
+        ];
+
+        fileResults.push({
+          path: pf.displayPath,
+          fileHash: newHash,
+          header,
+          firstChangedLine,
+          warnings: fileWarnings.length > 0 ? fileWarnings : undefined,
+          preview,
+        });
+      }
+
+      // 4. Format the output.
+      const outputParts = fileResults.map((fr) => {
+        let block = `${fr.header}\n${fr.preview}`;
+        if (fr.warnings && fr.warnings.length > 0) {
+          block += `\n\nWarnings:\n${fr.warnings.map((w) => `- ${w}`).join("\n")}`;
+        }
+        return block;
+      });
+
+      return {
+        content: [{ type: "text", text: outputParts.join("\n\n") }],
+        details: {
+          files: fileResults,
+          changed: fileResults.some((fr) => fr.firstChangedLine !== undefined),
+        },
+      };
+    },
+  };
+}