opencode-hashline 1.2.0 → 1.3.1

package/dist/utils.cjs

@@ -34,13 +34,17 @@ __export(utils_exports, {
   DEFAULT_EXCLUDE_PATTERNS: () => DEFAULT_EXCLUDE_PATTERNS,
   DEFAULT_PREFIX: () => DEFAULT_PREFIX,
   HashlineCache: () => HashlineCache,
+  HashlineError: () => HashlineError,
   applyHashEdit: () => applyHashEdit,
   buildHashMap: () => buildHashMap,
+  computeFileRev: () => computeFileRev,
   computeLineHash: () => computeLineHash,
   createFileEditBeforeHook: () => createFileEditBeforeHook,
   createFileReadAfterHook: () => createFileReadAfterHook,
   createHashline: () => createHashline,
   createSystemPromptHook: () => createSystemPromptHook,
+  extractFileRev: () => extractFileRev,
+  findCandidateLines: () => findCandidateLines,
   formatFileWithHashes: () => formatFileWithHashes,
   getAdaptiveHashLength: () => getAdaptiveHashLength,
   getByteLength: () => getByteLength,
@@ -53,6 +57,7 @@ __export(utils_exports, {
   resolveRange: () => resolveRange,
   shouldExclude: () => shouldExclude,
   stripHashes: () => stripHashes,
+  verifyFileRev: () => verifyFileRev,
   verifyHash: () => verifyHash
 });
 module.exports = __toCommonJS(utils_exports);
@@ -115,7 +120,9 @@ var DEFAULT_CONFIG = {
   // 0 = adaptive
   cacheSize: 100,
   prefix: DEFAULT_PREFIX,
-  debug: false
+  debug: false,
+  fileRev: true,
+  safeReapply: false
 };
 function resolveConfig(config, pluginConfig) {
   const merged = {
@@ -131,9 +138,55 @@ function resolveConfig(config, pluginConfig) {
     hashLength: merged.hashLength ?? DEFAULT_CONFIG.hashLength,
     cacheSize: merged.cacheSize ?? DEFAULT_CONFIG.cacheSize,
     prefix: merged.prefix !== void 0 ? merged.prefix : DEFAULT_CONFIG.prefix,
-    debug: merged.debug ?? DEFAULT_CONFIG.debug
+    debug: merged.debug ?? DEFAULT_CONFIG.debug,
+    fileRev: merged.fileRev ?? DEFAULT_CONFIG.fileRev,
+    safeReapply: merged.safeReapply ?? DEFAULT_CONFIG.safeReapply
   };
 }
+var HashlineError = class extends Error {
+  code;
+  expected;
+  actual;
+  candidates;
+  hint;
+  lineNumber;
+  filePath;
+  constructor(opts) {
+    super(opts.message);
+    this.name = "HashlineError";
+    this.code = opts.code;
+    this.expected = opts.expected;
+    this.actual = opts.actual;
+    this.candidates = opts.candidates;
+    this.hint = opts.hint;
+    this.lineNumber = opts.lineNumber;
+    this.filePath = opts.filePath;
+  }
+  toDiagnostic() {
+    const parts = [`[${this.code}] ${this.message}`];
+    if (this.filePath) {
+      parts.push(`  File: ${this.filePath}`);
+    }
+    if (this.lineNumber !== void 0) {
+      parts.push(`  Line: ${this.lineNumber}`);
+    }
+    if (this.expected !== void 0 && this.actual !== void 0) {
+      parts.push(`  Expected hash: ${this.expected}`);
+      parts.push(`  Actual hash:   ${this.actual}`);
+    }
+    if (this.candidates && this.candidates.length > 0) {
+      parts.push(`  Candidates (${this.candidates.length}):`);
+      for (const c of this.candidates) {
+        const preview = c.content.length > 60 ? c.content.slice(0, 60) + "..." : c.content;
+        parts.push(`    - line ${c.lineNumber}: ${preview}`);
+      }
+    }
+    if (this.hint) {
+      parts.push(`  Hint: ${this.hint}`);
+    }
+    return parts.join("\n");
+  }
+};
 function fnv1aHash(str) {
   let hash = 2166136261;
   for (let i = 0; i < str.length; i++) {
@@ -163,33 +216,90 @@ function computeLineHash(idx, line, hashLen = 3) {
   const hash = raw % modulus;
   return hash.toString(16).padStart(hashLen, "0");
 }
-function formatFileWithHashes(content, hashLen, prefix) {
+function computeFileRev(content) {
+  const normalized = content.includes("\r\n") ? content.replace(/\r\n/g, "\n") : content;
+  const hash = fnv1aHash(normalized);
+  return hash.toString(16).padStart(8, "0");
+}
+function extractFileRev(annotatedContent, prefix) {
+  const effectivePrefix = prefix === void 0 ? DEFAULT_PREFIX : prefix === false ? "" : prefix;
+  const escapedPrefix = effectivePrefix.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const pattern = new RegExp(`^${escapedPrefix}REV:([0-9a-f]{8})$`);
+  const firstLine = annotatedContent.split("\n")[0];
+  const match = firstLine.match(pattern);
+  return match ? match[1] : null;
+}
+function verifyFileRev(expectedRev, currentContent) {
+  const actualRev = computeFileRev(currentContent);
+  if (actualRev !== expectedRev) {
+    throw new HashlineError({
+      code: "FILE_REV_MISMATCH",
+      message: `File revision mismatch: expected "${expectedRev}", got "${actualRev}". The file has changed since it was last read.`,
+      expected: expectedRev,
+      actual: actualRev,
+      hint: "Re-read the file to get fresh hash references and a new file revision."
+    });
+  }
+}
+function findCandidateLines(originalLineNumber, expectedHash, lines, hashLen) {
+  const effectiveLen = hashLen && hashLen >= 2 ? hashLen : expectedHash.length;
+  const originalIdx = originalLineNumber - 1;
+  const candidates = [];
+  for (let i = 0; i < lines.length; i++) {
+    if (i === originalIdx) continue;
+    const candidateHash = computeLineHash(originalIdx, lines[i], effectiveLen);
+    if (candidateHash === expectedHash) {
+      candidates.push({
+        lineNumber: i + 1,
+        // 1-based
+        content: lines[i]
+      });
+    }
+  }
+  return candidates;
+}
+function formatFileWithHashes(content, hashLen, prefix, includeFileRev) {
   const normalized = content.includes("\r\n") ? content.replace(/\r\n/g, "\n") : content;
   const lines = normalized.split("\n");
   const effectiveLen = hashLen && hashLen >= 3 ? hashLen : getAdaptiveHashLength(lines.length);
   const effectivePrefix = prefix === void 0 ? DEFAULT_PREFIX : prefix === false ? "" : prefix;
+  const hashLens = new Array(lines.length).fill(effectiveLen);
   const hashes = new Array(lines.length);
-  const seen = /* @__PURE__ */ new Map();
-  const upgraded = /* @__PURE__ */ new Set();
   for (let idx = 0; idx < lines.length; idx++) {
-    const hash = computeLineHash(idx, lines[idx], effectiveLen);
-    if (seen.has(hash)) {
-      const longerLen = Math.min(effectiveLen + 1, 8);
-      const prevIdx = seen.get(hash);
-      if (!upgraded.has(prevIdx)) {
-        hashes[prevIdx] = computeLineHash(prevIdx, lines[prevIdx], longerLen);
-        upgraded.add(prevIdx);
+    hashes[idx] = computeLineHash(idx, lines[idx], effectiveLen);
+  }
+  let hasCollisions = true;
+  while (hasCollisions) {
+    hasCollisions = false;
+    const seen = /* @__PURE__ */ new Map();
+    for (let idx = 0; idx < lines.length; idx++) {
+      const h = hashes[idx];
+      const group = seen.get(h);
+      if (group) {
+        group.push(idx);
+      } else {
+        seen.set(h, [idx]);
+      }
+    }
+    for (const [, group] of seen) {
+      if (group.length < 2) continue;
+      for (const idx of group) {
+        const newLen = Math.min(hashLens[idx] + 1, 8);
+        if (newLen === hashLens[idx]) continue;
+        hashLens[idx] = newLen;
+        hashes[idx] = computeLineHash(idx, lines[idx], newLen);
+        hasCollisions = true;
       }
-      hashes[idx] = computeLineHash(idx, lines[idx], longerLen);
-      upgraded.add(idx);
-    } else {
-      seen.set(hash, idx);
-      hashes[idx] = hash;
     }
   }
-  return lines.map((line, idx) => {
+  const annotatedLines = lines.map((line, idx) => {
     return `${effectivePrefix}${idx + 1}:${hashes[idx]}|${line}`;
-  }).join("\n");
+  });
+  if (includeFileRev) {
+    const rev = computeFileRev(content);
+    annotatedLines.unshift(`${effectivePrefix}REV:${rev}`);
+  }
+  return annotatedLines.join("\n");
 }
 var stripRegexCache = /* @__PURE__ */ new Map();
 function stripHashes(content, prefix) {
@@ -200,9 +310,10 @@ function stripHashes(content, prefix) {
     hashLinePattern = new RegExp(`^([+ \\-])?${escapedPrefix}\\d+:[0-9a-f]{2,8}\\|`);
     stripRegexCache.set(escapedPrefix, hashLinePattern);
   }
+  const revPattern = new RegExp(`^${escapedPrefix}REV:[0-9a-f]{8}$`);
   const lineEnding = detectLineEnding(content);
   const normalized = lineEnding === "\r\n" ? content.replace(/\r\n/g, "\n") : content;
-  const result = normalized.split("\n").map((line) => {
+  const result = normalized.split("\n").filter((line) => !revPattern.test(line)).map((line) => {
     const match = line.match(hashLinePattern);
     if (match) {
       const patchMarker = match[1] || "";
@@ -216,7 +327,10 @@ function parseHashRef(ref) {
   const match = ref.match(/^(\d+):([0-9a-f]{2,8})$/);
   if (!match) {
     const display = ref.length > 100 ? `${ref.slice(0, 100)}\u2026` : ref;
-    throw new Error(`Invalid hash reference: "${display}". Expected format: "<line>:<2-8 char hex>"`);
+    throw new HashlineError({
+      code: "INVALID_REF",
+      message: `Invalid hash reference: "${display}". Expected format: "<line>:<2-8 char hex>"`
+    });
   }
   return {
     line: parseInt(match[1], 10),
@@ -234,9 +348,10 @@ function normalizeHashRef(ref) {
     return `${parseInt(annotated[1], 10)}:${annotated[2].toLowerCase()}`;
   }
   const display = ref.length > 100 ? `${ref.slice(0, 100)}\u2026` : ref;
-  throw new Error(
-    `Invalid hash reference: "${display}". Expected "<line>:<hash>" or an annotated line like "#HL <line>:<hash>|..."`
-  );
+  throw new HashlineError({
+    code: "INVALID_REF",
+    message: `Invalid hash reference: "${display}". Expected "<line>:<hash>" or an annotated line like "#HL <line>:<hash>|..."`
+  });
 }
 function buildHashMap(content, hashLen) {
   const lines = content.split("\n");
@@ -249,50 +364,97 @@ function buildHashMap(content, hashLen) {
   }
   return map;
 }
-function verifyHash(lineNumber, hash, currentContent, hashLen, lines) {
+function verifyHash(lineNumber, hash, currentContent, hashLen, lines, safeReapply) {
   const contentLines = lines ?? currentContent.split("\n");
   const effectiveLen = hashLen && hashLen >= 2 ? hashLen : hash.length;
   if (lineNumber < 1 || lineNumber > contentLines.length) {
     return {
       valid: false,
+      code: "TARGET_OUT_OF_RANGE",
       message: `Line ${lineNumber} is out of range (file has ${contentLines.length} lines)`
     };
   }
   const idx = lineNumber - 1;
   const actualHash = computeLineHash(idx, contentLines[idx], effectiveLen);
   if (actualHash !== hash) {
+    const candidates = findCandidateLines(lineNumber, hash, contentLines, effectiveLen);
+    if (safeReapply && candidates.length === 1) {
+      return {
+        valid: true,
+        relocatedLine: candidates[0].lineNumber,
+        candidates
+      };
+    }
+    if (safeReapply && candidates.length > 1) {
+      return {
+        valid: false,
+        code: "AMBIGUOUS_REAPPLY",
+        expected: hash,
+        actual: actualHash,
+        candidates,
+        message: `Hash mismatch at line ${lineNumber}: expected "${hash}", got "${actualHash}". Found ${candidates.length} candidate lines \u2014 ambiguous reapply.`
+      };
+    }
     return {
       valid: false,
+      code: "HASH_MISMATCH",
       expected: hash,
       actual: actualHash,
+      candidates,
       message: `Hash mismatch at line ${lineNumber}: expected "${hash}", got "${actualHash}". The file may have changed since it was read.`
     };
   }
   return { valid: true };
 }
-function resolveRange(startRef, endRef, content, hashLen) {
+function resolveRange(startRef, endRef, content, hashLen, safeReapply) {
   const start = parseHashRef(startRef);
   const end = parseHashRef(endRef);
   if (start.line > end.line) {
-    throw new Error(
-      `Invalid range: start line ${start.line} is after end line ${end.line}`
-    );
+    throw new HashlineError({
+      code: "INVALID_RANGE",
+      message: `Invalid range: start line ${start.line} is after end line ${end.line}`
+    });
   }
   const lineEnding = detectLineEnding(content);
   const normalized = lineEnding === "\r\n" ? content.replace(/\r\n/g, "\n") : content;
   const lines = normalized.split("\n");
-  const startVerify = verifyHash(start.line, start.hash, normalized, hashLen, lines);
+  const startVerify = verifyHash(start.line, start.hash, normalized, hashLen, lines, safeReapply);
   if (!startVerify.valid) {
-    throw new Error(`Start reference invalid: ${startVerify.message}`);
+    throw new HashlineError({
+      code: startVerify.code ?? "HASH_MISMATCH",
+      message: `Start reference invalid: ${startVerify.message}`,
+      expected: startVerify.expected,
+      actual: startVerify.actual,
+      candidates: startVerify.candidates,
+      lineNumber: start.line,
+      hint: startVerify.candidates && startVerify.candidates.length > 0 ? `Content may have moved. Candidates: ${startVerify.candidates.map((c) => `line ${c.lineNumber}`).join(", ")}` : "Re-read the file to get fresh hash references."
+    });
   }
-  const endVerify = verifyHash(end.line, end.hash, normalized, hashLen, lines);
+  const effectiveStartLine = startVerify.relocatedLine ?? start.line;
+  const endVerify = verifyHash(end.line, end.hash, normalized, hashLen, lines, safeReapply);
   if (!endVerify.valid) {
-    throw new Error(`End reference invalid: ${endVerify.message}`);
+    throw new HashlineError({
+      code: endVerify.code ?? "HASH_MISMATCH",
+      message: `End reference invalid: ${endVerify.message}`,
+      expected: endVerify.expected,
+      actual: endVerify.actual,
+      candidates: endVerify.candidates,
+      lineNumber: end.line,
+      hint: endVerify.candidates && endVerify.candidates.length > 0 ? `Content may have moved. Candidates: ${endVerify.candidates.map((c) => `line ${c.lineNumber}`).join(", ")}` : "Re-read the file to get fresh hash references."
+    });
+  }
+  const effectiveEndLine = endVerify.relocatedLine ?? end.line;
+  if (effectiveStartLine > effectiveEndLine) {
+    throw new HashlineError({
+      code: "INVALID_RANGE",
+      message: `Invalid effective range after relocation: start line ${effectiveStartLine} is after end line ${effectiveEndLine}`,
+      hint: "The referenced lines may have been reordered. Re-read the file to get fresh references."
+    });
   }
-  const rangeLines = lines.slice(start.line - 1, end.line);
+  const rangeLines = lines.slice(effectiveStartLine - 1, effectiveEndLine);
   return {
-    startLine: start.line,
-    endLine: end.line,
+    startLine: effectiveStartLine,
+    endLine: effectiveEndLine,
     lines: rangeLines,
     content: rangeLines.join(lineEnding)
   };
@@ -308,22 +470,37 @@ function replaceRange(startRef, endRef, content, replacement, hashLen) {
   const result = [...before, ...replacementLines, ...after].join("\n");
   return lineEnding === "\r\n" ? result.replace(/\n/g, "\r\n") : result;
 }
-function applyHashEdit(input, content, hashLen) {
+function applyHashEdit(input, content, hashLen, safeReapply) {
   const lineEnding = detectLineEnding(content);
   const workContent = lineEnding === "\r\n" ? content.replace(/\r\n/g, "\n") : content;
+  if (input.fileRev) {
+    verifyFileRev(input.fileRev, workContent);
+  }
   const normalizedStart = normalizeHashRef(input.startRef);
   const start = parseHashRef(normalizedStart);
   const lines = workContent.split("\n");
-  const startVerify = verifyHash(start.line, start.hash, workContent, hashLen, lines);
+  const startVerify = verifyHash(start.line, start.hash, workContent, hashLen, lines, safeReapply);
   if (!startVerify.valid) {
-    throw new Error(`Start reference invalid: ${startVerify.message}`);
+    throw new HashlineError({
+      code: startVerify.code ?? "HASH_MISMATCH",
+      message: `Start reference invalid: ${startVerify.message}`,
+      expected: startVerify.expected,
+      actual: startVerify.actual,
+      candidates: startVerify.candidates,
+      lineNumber: start.line,
+      hint: startVerify.candidates && startVerify.candidates.length > 0 ? `Content may have moved. Candidates: ${startVerify.candidates.map((c) => `line ${c.lineNumber}`).join(", ")}` : "Re-read the file to get fresh hash references."
+    });
   }
+  const effectiveStartLine = startVerify.relocatedLine ?? start.line;
   if (input.operation === "insert_before" || input.operation === "insert_after") {
     if (input.replacement === void 0) {
-      throw new Error(`Operation "${input.operation}" requires "replacement" content`);
+      throw new HashlineError({
+        code: "MISSING_REPLACEMENT",
+        message: `Operation "${input.operation}" requires "replacement" content`
+      });
     }
     const insertionLines = input.replacement.split("\n");
-    const insertIndex = input.operation === "insert_before" ? start.line - 1 : start.line;
+    const insertIndex = input.operation === "insert_before" ? effectiveStartLine - 1 : effectiveStartLine;
     const next2 = [
       ...lines.slice(0, insertIndex),
       ...insertionLines,
@@ -331,34 +508,54 @@ function applyHashEdit(input, content, hashLen) {
     ].join("\n");
     return {
       operation: input.operation,
-      startLine: start.line,
-      endLine: start.line,
+      startLine: effectiveStartLine,
+      endLine: effectiveStartLine,
       content: lineEnding === "\r\n" ? next2.replace(/\n/g, "\r\n") : next2
     };
   }
   const normalizedEnd = normalizeHashRef(input.endRef ?? input.startRef);
   const end = parseHashRef(normalizedEnd);
   if (start.line > end.line) {
-    throw new Error(
-      `Invalid range: start line ${start.line} is after end line ${end.line}`
-    );
+    throw new HashlineError({
+      code: "INVALID_RANGE",
+      message: `Invalid range: start line ${start.line} is after end line ${end.line}`
+    });
   }
-  const endVerify = verifyHash(end.line, end.hash, workContent, hashLen, lines);
+  const endVerify = verifyHash(end.line, end.hash, workContent, hashLen, lines, safeReapply);
   if (!endVerify.valid) {
-    throw new Error(`End reference invalid: ${endVerify.message}`);
+    throw new HashlineError({
+      code: endVerify.code ?? "HASH_MISMATCH",
+      message: `End reference invalid: ${endVerify.message}`,
+      expected: endVerify.expected,
+      actual: endVerify.actual,
+      candidates: endVerify.candidates,
+      lineNumber: end.line,
+      hint: endVerify.candidates && endVerify.candidates.length > 0 ? `Content may have moved. Candidates: ${endVerify.candidates.map((c) => `line ${c.lineNumber}`).join(", ")}` : "Re-read the file to get fresh hash references."
+    });
+  }
+  const effectiveEndLine = endVerify.relocatedLine ?? end.line;
+  if (effectiveStartLine > effectiveEndLine) {
+    throw new HashlineError({
+      code: "INVALID_RANGE",
+      message: `Invalid effective range after relocation: start line ${effectiveStartLine} is after end line ${effectiveEndLine}`,
+      hint: "The referenced lines may have been reordered. Re-read the file to get fresh references."
+    });
   }
   const replacement = input.operation === "delete" ? "" : input.replacement;
   if (replacement === void 0) {
-    throw new Error(`Operation "${input.operation}" requires "replacement" content`);
+    throw new HashlineError({
+      code: "MISSING_REPLACEMENT",
+      message: `Operation "${input.operation}" requires "replacement" content`
+    });
   }
-  const before = lines.slice(0, start.line - 1);
-  const after = lines.slice(end.line);
+  const before = lines.slice(0, effectiveStartLine - 1);
+  const after = lines.slice(effectiveEndLine);
   const replacementLines = input.operation === "delete" ? [] : replacement.split("\n");
   const next = [...before, ...replacementLines, ...after].join("\n");
   return {
     operation: input.operation,
-    startLine: start.line,
-    endLine: end.line,
+    startLine: effectiveStartLine,
+    endLine: effectiveEndLine,
     content: lineEnding === "\r\n" ? next.replace(/\n/g, "\r\n") : next
   };
 }
@@ -455,7 +652,7 @@ function createHashline(config) {
         const cached = cache.get(filePath, content);
         if (cached) return cached;
       }
-      const result = formatFileWithHashes(content, hl, pfx);
+      const result = formatFileWithHashes(content, hl, pfx, resolved.fileRev);
       if (filePath) {
         cache.set(filePath, content, result);
       }
@@ -471,16 +668,16 @@ function createHashline(config) {
       return buildHashMap(content, hl);
     },
     verifyHash(lineNumber, hash, currentContent) {
-      return verifyHash(lineNumber, hash, currentContent, hl);
+      return verifyHash(lineNumber, hash, currentContent, hl, void 0, resolved.safeReapply);
     },
     resolveRange(startRef, endRef, content) {
-      return resolveRange(startRef, endRef, content, hl);
+      return resolveRange(startRef, endRef, content, hl, resolved.safeReapply);
     },
     replaceRange(startRef, endRef, content, replacement) {
       return replaceRange(startRef, endRef, content, replacement, hl);
     },
     applyHashEdit(input, content) {
-      return applyHashEdit(input, content, hl);
+      return applyHashEdit(input, content, hl, resolved.safeReapply);
     },
     normalizeHashRef(ref) {
       return normalizeHashRef(ref);
@@ -490,6 +687,18 @@ function createHashline(config) {
     },
     shouldExclude(filePath) {
       return shouldExclude(filePath, resolved.exclude);
+    },
+    computeFileRev(content) {
+      return computeFileRev(content);
+    },
+    verifyFileRev(expectedRev, currentContent) {
+      return verifyFileRev(expectedRev, currentContent);
+    },
+    extractFileRev(annotatedContent) {
+      return extractFileRev(annotatedContent, pfx);
+    },
+    findCandidateLines(originalLineNumber, expectedHash, lines, hashLen) {
+      return findCandidateLines(originalLineNumber, expectedHash, lines, hashLen);
     }
   };
 }
@@ -579,7 +788,7 @@ function createFileReadAfterHook(cache, config) {
         return;
       }
     }
-    const annotated = formatFileWithHashes(content, hashLen || void 0, prefix);
+    const annotated = formatFileWithHashes(content, hashLen || void 0, prefix, resolved.fileRev);
     output.output = annotated;
     debug("annotated", typeof filePath === "string" ? filePath : input.tool, "lines:", content.split("\n").length);
     if (cache && typeof filePath === "string") {
@@ -691,10 +900,32 @@ function createSystemPromptHook(config) {
         '- Hash references include both the line number AND the content hash, so `2:f1c` means "line 2 with hash f1c".',
         "- If you see a mismatch, do NOT proceed with the edit \u2014 re-read the file to get fresh references.",
         "",
+        "### File revision (`#HL REV:<hash>`):",
+        "- When files are read, the first line may contain a file revision header: `" + prefix + "REV:<8-char-hex>`.",
+        "- This is a hash of the entire file content. Pass it as the `fileRev` parameter to `hashline_edit` to verify the file hasn't changed.",
+        "- If the file was modified between read and edit, the revision check fails with `FILE_REV_MISMATCH` \u2014 re-read the file.",
+        "",
+        "### Safe reapply (`safeReapply`):",
+        "- Pass `safeReapply: true` to `hashline_edit` to enable automatic line relocation.",
+        "- If a line moved (e.g., due to insertions above), safe reapply finds it by content hash.",
+        "- If exactly one match is found, the edit proceeds at the new location.",
+        "- If multiple matches exist, the edit fails with `AMBIGUOUS_REAPPLY` \u2014 re-read the file.",
+        "",
+        "### Structured error codes:",
+        "- `HASH_MISMATCH` \u2014 line content changed since last read",
+        "- `FILE_REV_MISMATCH` \u2014 file was modified since last read",
+        "- `AMBIGUOUS_REAPPLY` \u2014 multiple candidate lines found during safe reapply",
+        "- `TARGET_OUT_OF_RANGE` \u2014 line number exceeds file length",
+        "- `INVALID_REF` \u2014 malformed hash reference",
+        "- `INVALID_RANGE` \u2014 start line is after end line",
+        "- `MISSING_REPLACEMENT` \u2014 replace/insert operation without replacement content",
+        "",
         "### Best practices:",
         "- Use hash references for all edit operations to ensure precision.",
         "- When making multiple edits, work from bottom to top to avoid line number shifts.",
-        "- For large replacements, use range references (e.g., `1:a3f to 10:b2c`) instead of individual lines."
+        "- For large replacements, use range references (e.g., `1:a3f to 10:b2c`) instead of individual lines.",
+        "- Use `fileRev` to guard against stale edits on critical files.",
+        "- Use `safeReapply: true` when editing files that may have shifted due to earlier edits."
       ].join("\n")
     );
   };
@@ -705,13 +936,17 @@ function createSystemPromptHook(config) {
   DEFAULT_EXCLUDE_PATTERNS,
   DEFAULT_PREFIX,
   HashlineCache,
+  HashlineError,
   applyHashEdit,
   buildHashMap,
+  computeFileRev,
   computeLineHash,
   createFileEditBeforeHook,
   createFileReadAfterHook,
   createHashline,
   createSystemPromptHook,
+  extractFileRev,
+  findCandidateLines,
   formatFileWithHashes,
   getAdaptiveHashLength,
   getByteLength,
@@ -724,5 +959,6 @@ function createSystemPromptHook(config) {
   resolveRange,
   shouldExclude,
   stripHashes,
+  verifyFileRev,
   verifyHash
 });

package/dist/utils.d.cts

@@ -1,5 +1,5 @@
-import { H as HashlineConfig, e as HashlineCache } from './hashline-yhMw1Abs.cjs';
-export { D as DEFAULT_CONFIG, f as DEFAULT_EXCLUDE_PATTERNS, g as DEFAULT_PREFIX, a as HashEditInput, b as HashEditOperation, c as HashEditResult, d as HashlineInstance, R as ResolvedRange, V as VerifyHashResult, h as applyHashEdit, i as buildHashMap, j as computeLineHash, k as createHashline, l as formatFileWithHashes, m as getAdaptiveHashLength, n as getByteLength, o as matchesGlob, p as normalizeHashRef, q as parseHashRef, r as replaceRange, s as resolveConfig, t as resolveRange, u as shouldExclude, v as stripHashes, w as verifyHash } from './hashline-yhMw1Abs.cjs';
+import { H as HashlineConfig, f as HashlineCache } from './hashline-A7k2yn3G.cjs';
+export { C as CandidateLine, D as DEFAULT_CONFIG, g as DEFAULT_EXCLUDE_PATTERNS, h as DEFAULT_PREFIX, a as HashEditInput, b as HashEditOperation, c as HashEditResult, i as HashlineError, d as HashlineErrorCode, e as HashlineInstance, R as ResolvedRange, V as VerifyHashResult, j as applyHashEdit, k as buildHashMap, l as computeFileRev, m as computeLineHash, n as createHashline, o as extractFileRev, p as findCandidateLines, q as formatFileWithHashes, r as getAdaptiveHashLength, s as getByteLength, t as matchesGlob, u as normalizeHashRef, v as parseHashRef, w as replaceRange, x as resolveConfig, y as resolveRange, z as shouldExclude, A as stripHashes, B as verifyFileRev, E as verifyHash } from './hashline-A7k2yn3G.cjs';
 import { Hooks } from '@opencode-ai/plugin';
 
 /**

package/dist/utils.d.ts

@@ -1,5 +1,5 @@
-import { H as HashlineConfig, e as HashlineCache } from './hashline-yhMw1Abs.js';
-export { D as DEFAULT_CONFIG, f as DEFAULT_EXCLUDE_PATTERNS, g as DEFAULT_PREFIX, a as HashEditInput, b as HashEditOperation, c as HashEditResult, d as HashlineInstance, R as ResolvedRange, V as VerifyHashResult, h as applyHashEdit, i as buildHashMap, j as computeLineHash, k as createHashline, l as formatFileWithHashes, m as getAdaptiveHashLength, n as getByteLength, o as matchesGlob, p as normalizeHashRef, q as parseHashRef, r as replaceRange, s as resolveConfig, t as resolveRange, u as shouldExclude, v as stripHashes, w as verifyHash } from './hashline-yhMw1Abs.js';
+import { H as HashlineConfig, f as HashlineCache } from './hashline-A7k2yn3G.js';
+export { C as CandidateLine, D as DEFAULT_CONFIG, g as DEFAULT_EXCLUDE_PATTERNS, h as DEFAULT_PREFIX, a as HashEditInput, b as HashEditOperation, c as HashEditResult, i as HashlineError, d as HashlineErrorCode, e as HashlineInstance, R as ResolvedRange, V as VerifyHashResult, j as applyHashEdit, k as buildHashMap, l as computeFileRev, m as computeLineHash, n as createHashline, o as extractFileRev, p as findCandidateLines, q as formatFileWithHashes, r as getAdaptiveHashLength, s as getByteLength, t as matchesGlob, u as normalizeHashRef, v as parseHashRef, w as replaceRange, x as resolveConfig, y as resolveRange, z as shouldExclude, A as stripHashes, B as verifyFileRev, E as verifyHash } from './hashline-A7k2yn3G.js';
 import { Hooks } from '@opencode-ai/plugin';
 
 /**

package/dist/utils.js

@@ -3,16 +3,20 @@ import {
   createFileReadAfterHook,
   createSystemPromptHook,
   isFileReadTool
-} from "./chunk-VPCMHCTB.js";
+} from "./chunk-VSVVWPET.js";
 import {
   DEFAULT_CONFIG,
   DEFAULT_EXCLUDE_PATTERNS,
   DEFAULT_PREFIX,
   HashlineCache,
+  HashlineError,
   applyHashEdit,
   buildHashMap,
+  computeFileRev,
   computeLineHash,
   createHashline,
+  extractFileRev,
+  findCandidateLines,
   formatFileWithHashes,
   getAdaptiveHashLength,
   getByteLength,
@@ -24,20 +28,25 @@ import {
   resolveRange,
   shouldExclude,
   stripHashes,
+  verifyFileRev,
   verifyHash
-} from "./chunk-I6RACR3D.js";
+} from "./chunk-GKXY5ZBM.js";
 export {
   DEFAULT_CONFIG,
   DEFAULT_EXCLUDE_PATTERNS,
   DEFAULT_PREFIX,
   HashlineCache,
+  HashlineError,
   applyHashEdit,
   buildHashMap,
+  computeFileRev,
   computeLineHash,
   createFileEditBeforeHook,
   createFileReadAfterHook,
   createHashline,
   createSystemPromptHook,
+  extractFileRev,
+  findCandidateLines,
   formatFileWithHashes,
   getAdaptiveHashLength,
   getByteLength,
@@ -50,5 +59,6 @@ export {
   resolveRange,
   shouldExclude,
   stripHashes,
+  verifyFileRev,
   verifyHash
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-hashline",
-  "version": "1.2.0",
+  "version": "1.3.1",
   "description": "Hashline plugin for OpenCode — content-addressable line hashing for precise AI code editing",
   "main": "dist/opencode-hashline.cjs",
   "module": "dist/opencode-hashline.js",