opencode-hashline 1.0.0

package/README.ru.md

@@ -0,0 +1,417 @@
+<div align="center">
+
+# 🔗 opencode-hashline
+
+**Контентно-адресуемое хеширование строк для точного редактирования кода с помощью AI**
+
+[![CI](https://github.com/izzzzzi/opencode-hashline/actions/workflows/ci.yml/badge.svg)](https://github.com/izzzzzi/opencode-hashline/actions/workflows/ci.yml)
+[![npm version](https://img.shields.io/npm/v/opencode-hashline.svg?style=flat&colorA=18181B&colorB=28CF8D)](https://www.npmjs.com/package/opencode-hashline)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg?style=flat&colorA=18181B&colorB=28CF8D)](LICENSE)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.9-blue?style=flat&colorA=18181B&colorB=3178C6)](https://www.typescriptlang.org/)
+[![Node.js](https://img.shields.io/badge/Node.js-ESM-green?style=flat&colorA=18181B&colorB=339933)](https://nodejs.org/)
+
+**🇷🇺 Русский** | [🇬🇧 English](README.md)
+
+<br />
+
+*Hashline-плагин для [OpenCode](https://github.com/anomalyco/opencode) — аннотирует каждую строку файла детерминированным хеш-тегом, чтобы AI мог ссылаться на код и редактировать его с хирургической точностью.*
+
+</div>
+
+---
+
+## 📖 Что такое Hashline?
+
+Hashline аннотирует каждую строку файла коротким детерминированным hex-хешем. Когда AI читает файл, он видит:
+
+```
+#HL 1:a3f|function hello() {
+#HL 2:f1c|  return "world";
+#HL 3:0e7|}
+```
+
+> **Примечание:** Длина хеша адаптивная — она зависит от размера файла (2 символа для ≤256 строк, 3 символа для ≤4096 строк, 4 символа для >4096 строк). В примерах ниже используются 3-символьные хеши. Префикс `#HL ` защищает от ложных срабатываний при удалении хешей и является настраиваемым.
+
+AI-модель может ссылаться на строки по их хеш-тегам для точного редактирования:
+
+- **«Заменить строку `2:f1c`»** — указать конкретную строку однозначно
+- **«Заменить блок от `1:a3f` до `3:0e7`»** — указать диапазон строк
+- **«Вставить после `3:0e7`»** — вставить в точное место
+
+### 🤔 Почему это помогает?
+
+Традиционные номера строк сдвигаются при редактировании, вызывая ошибки смещения и устаревшие ссылки. Хеш-теги Hashline **контентно-адресуемы** — они вычисляются из индекса строки и её содержимого, что делает их стабильной, верифицируемой ссылкой для точной коммуникации о местоположении в коде.
+
+---
+
+## ✨ Возможности
+
+### 📏 Адаптивная длина хеша
+
+Длина хеша автоматически адаптируется к размеру файла для минимизации коллизий:
+
+| Размер файла | Длина хеша | Возможных значений |
+|-------------|:----------:|:------------------:|
+| ≤ 256 строк | 2 hex-символа | 256 |
+| ≤ 4 096 строк | 3 hex-символа | 4 096 |
+| > 4 096 строк | 4 hex-символа | 65 536 |
+
+### 🏷️ Магический префикс (`#HL `)
+
+Строки аннотируются настраиваемым префиксом (по умолчанию: `#HL `), чтобы предотвратить ложные срабатывания при удалении хешей. Это гарантирует, что строки данных вроде `1:ab|some data` не будут случайно обрезаны.
+
+```
+#HL 1:a3|function hello() {
+#HL 2:f1|  return "world";
+#HL 3:0e|}
+```
+
+Префикс можно настроить или отключить для обратной совместимости:
+
+```typescript
+// Кастомный префикс
+const hl = createHashline({ prefix: ">> " });
+
+// Отключить префикс (legacy-формат: "1:a3|code")
+const hl = createHashline({ prefix: false });
+```
+
+### 💾 LRU-кеширование
+
+Встроенный LRU-кеш (`filePath → annotatedContent`) с настраиваемым размером (по умолчанию 100 файлов). При повторном чтении того же файла с неизменённым содержимым возвращается кешированный результат. Кеш автоматически инвалидируется при изменении содержимого файла.
+
+### ✅ Верификация хешей
+
+Проверка того, что строка не изменилась с момента чтения — защита от race conditions:
+
+```typescript
+import { verifyHash } from "opencode-hashline";
+
+const result = verifyHash(2, "f1c", currentContent);
+if (!result.valid) {
+  console.error(result.message); // "Hash mismatch at line 2: ..."
+}
+```
+
+Верификация хешей использует длину предоставленной хеш-ссылки (а не текущий размер файла), поэтому ссылка вроде `2:f1` остаётся валидной даже если файл вырос.
+
+### 🔍 Чувствительность к отступам
+
+Вычисление хеша использует `trimEnd()` (а не `trim()`), поэтому изменения ведущих пробелов (отступов) обнаруживаются как изменения содержимого, а завершающие пробелы игнорируются.
+
+### 📐 Range-операции
+
+Резолвинг и замена диапазонов строк по хеш-ссылкам:
+
+```typescript
+import { resolveRange, replaceRange } from "opencode-hashline";
+
+// Получить строки между двумя хеш-ссылками
+const range = resolveRange("1:a3f", "3:0e7", content);
+console.log(range.lines); // ["function hello() {", '  return "world";', "}"]
+
+// Заменить диапазон новым содержимым
+const newContent = replaceRange(
+  "1:a3f", "3:0e7", content,
+  "function goodbye() {\n  return 'farewell';\n}"
+);
+```
+
+### ⚙️ Конфигурируемость
+
+Создание кастомных экземпляров Hashline с определёнными настройками:
+
+```typescript
+import { createHashline } from "opencode-hashline";
+
+const hl = createHashline({
+  exclude: ["**/node_modules/**", "**/*.min.js"],
+  maxFileSize: 512_000,  // 512 КБ
+  hashLength: 3,         // принудительно 3-символьные хеши
+  cacheSize: 200,        // кешировать до 200 файлов
+  prefix: "#HL ",        // магический префикс (по умолчанию)
+});
+
+// Использование настроенного экземпляра
+const annotated = hl.formatFileWithHashes(content, "src/app.ts");
+const isExcluded = hl.shouldExclude("node_modules/foo.js"); // true
+```
+
+#### Параметры конфигурации
+
+| Параметр | Тип | По умолчанию | Описание |
+|----------|-----|:------------:|----------|
+| `exclude` | `string[]` | См. ниже | Glob-паттерны для исключения файлов |
+| `maxFileSize` | `number` | `1_000_000` | Макс. размер файла в байтах |
+| `hashLength` | `number \| undefined` | `undefined` (адаптивно) | Принудительная длина хеша |
+| `cacheSize` | `number` | `100` | Макс. файлов в LRU-кеше |
+| `prefix` | `string \| false` | `"#HL "` | Префикс строки (`false` для отключения) |
+
+Паттерны исключения по умолчанию: lock-файлы, `node_modules`, минифицированные файлы, бинарные файлы (изображения, шрифты, архивы и т.д.).
+
+---
+
+## 📦 Установка
+
+```bash
+npm install opencode-hashline
+```
+
+---
+
+## 🔧 Конфигурация
+
+Добавьте плагин в ваш `opencode.json`:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": ["opencode-hashline"]
+}
+```
+
+### Файлы конфигурации
+
+Плагин загружает конфигурацию из следующих мест (в порядке приоритета, более поздние перезаписывают ранние):
+
+| Приоритет | Расположение | Область |
+|:---------:|-------------|---------|
+| 1 | `~/.config/opencode/opencode-hashline.json` | Глобальная (все проекты) |
+| 2 | `<project>/opencode-hashline.json` | Локальная (проект) |
+| 3 | Программная конфигурация через `createHashlinePlugin()` | Аргумент фабрики |
+
+Пример `opencode-hashline.json`:
+
+```json
+{
+  "exclude": ["**/node_modules/**", "**/*.min.js"],
+  "maxFileSize": 1048576,
+  "hashLength": 0,
+  "cacheSize": 100,
+  "prefix": "#HL "
+}
+```
+
+Вот и всё! Плагин автоматически:
+
+| # | Действие | Описание |
+|:-:|----------|----------|
+| 1 | 📝 **Аннотирует чтение файлов** | При чтении файла AI каждая строка получает `#HL` хеш-префикс |
+| 2 | 📎 **Аннотирует `@file` упоминания** | Файлы, прикреплённые через `@filename` в промпте, тоже аннотируются хешлайнами |
+| 3 | ✂️ **Убирает хеш-префиксы при редактировании** | При записи/редактировании файла хеш-префиксы удаляются перед применением изменений |
+| 4 | 🧠 **Внедряет инструкции в системный промпт** | AI получает инструкции по интерпретации и использованию hashline-ссылок |
+| 5 | 💾 **Кеширует результаты** | Повторные чтения того же файла возвращают кешированные аннотации |
+| 6 | 🔍 **Фильтрует по инструменту** | Только инструменты чтения файлов (например `read_file`, `cat`, `view`) получают аннотации; остальные не затрагиваются |
+| 7 | ⚙️ **Учитывает конфигурацию** | Исключённые файлы и файлы, превышающие `maxFileSize`, пропускаются |
+| 8 | 🧩 **Регистрирует `hashline_edit` tool** | Применяет replace/delete/insert по hash-ссылкам без точного `old_string`-матчинга |
+
+---
+
+## 🛠️ Как это работает
+
+### Вычисление хеша
+
+Хеш каждой строки вычисляется из:
+- **0-based индекса** строки
+- **Содержимого строки** с обрезанными завершающими пробелами (trimEnd) — ведущие пробелы (отступы) ЗНАЧИМЫ
+
+Это подаётся в хеш-функцию **FNV-1a**, сводится к соответствующему модулю в зависимости от размера файла и отображается как hex-строка.
+
+### Хуки и tool плагина
+
+Плагин регистрирует четыре хука OpenCode и один кастомный tool:
+
+| Хук | Назначение |
+|-----|-----------|
+| `tool.hashline_edit` | Hash-aware правки по ссылкам вроде `5:a3f` или `#HL 5:a3f|...` |
+| `tool.execute.after` | Добавляет hashline-аннотации в вывод инструментов чтения файлов |
+| `tool.execute.before` | Убирает hashline-префиксы из аргументов инструментов редактирования |
+| `chat.message` | Аннотирует `@file` упоминания в сообщениях пользователя (записывает аннотированный контент во временный файл и подменяет URL) |
+| `experimental.chat.system.transform` | Добавляет инструкции по использованию hashline в системный промпт |
+
+---
+
+## 🔌 Программный API
+
+Основные утилиты экспортируются из субпути `opencode-hashline/utils` (чтобы избежать конфликтов с загрузчиком плагинов OpenCode, который вызывает каждый экспорт как функцию Plugin):
+
+```typescript
+import {
+  computeLineHash,
+  formatFileWithHashes,
+  stripHashes,
+  parseHashRef,
+  normalizeHashRef,
+  buildHashMap,
+  getAdaptiveHashLength,
+  verifyHash,
+  resolveRange,
+  replaceRange,
+  applyHashEdit,
+  HashlineCache,
+  createHashline,
+  shouldExclude,
+  matchesGlob,
+  resolveConfig,
+  DEFAULT_PREFIX,
+} from "opencode-hashline/utils";
+```
+
+### Основные функции
+
+```typescript
+// Вычислить хеш для одной строки
+const hash = computeLineHash(0, "function hello() {"); // например "a3f"
+
+// Вычислить хеш с определённой длиной
+const hash4 = computeLineHash(0, "function hello() {", 4); // например "a3f2"
+
+// Аннотировать содержимое файла (адаптивная длина хеша, с префиксом #HL)
+const annotated = formatFileWithHashes(fileContent);
+// "#HL 1:a3|function hello() {\n#HL 2:f1|  return \"world\";\n#HL 3:0e|}"
+
+// Аннотировать с определённой длиной хеша
+const annotated3 = formatFileWithHashes(fileContent, 3);
+
+// Аннотировать без префикса (legacy-формат)
+const annotatedLegacy = formatFileWithHashes(fileContent, undefined, false);
+
+// Убрать аннотации, получить оригинальное содержимое
+const original = stripHashes(annotated);
+```
+
+### Хеш-ссылки и верификация
+
+```typescript
+// Разобрать хеш-ссылку
+const { line, hash } = parseHashRef("2:f1c"); // { line: 2, hash: "f1c" }
+
+// Нормализовать ссылку из аннотированной строки
+const ref = normalizeHashRef("#HL 2:f1c|const x = 1;"); // "2:f1c"
+
+// Построить карту соответствий
+const map = buildHashMap(fileContent); // Map<"2:f1c", 2>
+
+// Верифицировать хеш-ссылку (использует hash.length, а не размер файла)
+const result = verifyHash(2, "f1c", fileContent);
+```
+
+### Range-операции
+
+```typescript
+// Резолвить диапазон
+const range = resolveRange("1:a3f", "3:0e7", fileContent);
+
+// Заменить диапазон
+const newContent = replaceRange("1:a3f", "3:0e7", fileContent, "новое содержимое");
+
+// Hash-aware операция редактирования (replace/delete/insert_before/insert_after)
+const edited = applyHashEdit(
+  { operation: "replace", startRef: "1:a3f", endRef: "3:0e7", replacement: "новое содержимое" },
+  fileContent
+).content;
+```
+
+### Утилиты
+
+```typescript
+// Проверить, нужно ли исключить файл
+const excluded = shouldExclude("node_modules/foo.js", ["**/node_modules/**"]);
+
+// Создать настроенный экземпляр
+const hl = createHashline({ cacheSize: 50, hashLength: 3 });
+```
+
+---
+
+## 📊 Бенчмарк
+
+### Корректность: hashline vs str_replace
+
+Оба подхода протестированы на **60 фикстурах из [react-edit-benchmark](https://github.com/can1357/oh-my-pi/tree/main/packages/react-edit-benchmark)** — мутированных файлах React с известными багами (инвертированные булевы, перепутанные операторы, удалённые guard-клаузы и т.д.):
+
+| | hashline | str_replace |
+|---|:---:|:---:|
+| **Прошло** | **60/60 (100%)** | 58/60 (96.7%) |
+| **Провалено** | 0 | 2 |
+| **Неоднозначные правки** | 0 | 4 |
+
+str_replace ломается, когда `old_string` встречается в файле несколько раз (например, повторяющиеся guard-клаузы, похожие блоки кода). Hashline адресует каждую строку уникально через `lineNumber:hash`, поэтому неоднозначность исключена.
+
+```bash
+# Запустите сами:
+npx tsx benchmark/run.ts              # режим hashline
+npx tsx benchmark/run.ts --no-hash    # режим str_replace
+```
+
+<details>
+<summary>Ошибки str_replace (категория structural)</summary>
+
+- `structural-remove-early-return-001` — `old_string` совпал в нескольких местах, замена применена не к тому
+- `structural-remove-early-return-002` — аналогичная проблема
+- `structural-delete-statement-002` — неоднозначное совпадение (первое совпадение оказалось верным)
+- `structural-delete-statement-003` — неоднозначное совпадение (первое совпадение оказалось верным)
+
+</details>
+
+### Расход токенов
+
+Аннотации hashline добавляют префикс `#HL <line>:<hash>|` (~12 символов / ~3 токена) на строку:
+
+| | Без хешей | С хешами | Оверхед |
+|---|---:|---:|:---:|
+| **Символы** | 404K | 564K | +40% |
+| **Токены (~)** | ~101K | ~141K | +40% |
+
+Оверхед стабильно ~40% независимо от размера файла. Для типичного файла на 200 строк (~800 токенов) hashline добавляет ~600 токенов — пренебрежимо мало при контекстном окне в 200K.
+
+### Производительность
+
+| Размер файла | Аннотация | Правка | Удаление хешей |
+|-------------:|:---------:|:------:|:--------------:|
+| **10** строк | 0.05 мс | 0.01 мс | 0.03 мс |
+| **100** строк | 0.12 мс | 0.02 мс | 0.08 мс |
+| **1 000** строк | 0.95 мс | 0.04 мс | 0.60 мс |
+| **5 000** строк | 4.50 мс | 0.08 мс | 2.80 мс |
+| **10 000** строк | 9.20 мс | 0.10 мс | 5.50 мс |
+
+> Типичный файл из 1 000 строк аннотируется за **< 1 мс** — незаметно для пользователя.
+
+---
+
+## 🧑‍💻 Разработка
+
+```bash
+# Установить зависимости
+npm install
+
+# Запустить тесты
+npm test
+
+# Собрать
+npm run build
+
+# Проверка типов
+npm run typecheck
+```
+
+---
+
+## 💡 Вдохновение и теоретическая база
+
+Идея hashline вдохновлена концепциями из **oh-my-pi** от [can1357](https://github.com/can1357/oh-my-pi) — AI-тулкита для разработки (coding agent CLI, unified LLM API, TUI-библиотеки) — и статьи «The Harness Problem» (проблема обвязки).
+
+**Суть проблемы:** современные AI-модели обладают огромными возможностями, но инструменты (harness), которые передают модели контекст и применяют её правки к файлам, теряют информацию и порождают ошибки. Модель видит содержимое файла, но при редактировании вынуждена «угадывать» контекст окружающих строк. Search-and-replace ломается на дубликатах строк, а diff-формат тоже ненадёжен на практике.
+
+Hashline решает эту проблему, присваивая каждой строке короткий детерминированный хеш-тег (например, `2:f1c`), что делает адресацию строк **точной и однозначной**. Модель может ссылаться на любую строку или диапазон без ошибок смещения и путаницы с дубликатами.
+
+**Ссылки:**
+- [oh-my-pi от can1357](https://github.com/can1357/oh-my-pi) — AI-тулкит для разработки: coding agent CLI, unified LLM API, TUI-библиотеки
+- [The Harness Problem](https://blog.can.ac/2026/02/12/the-harness-problem/) — блог-пост с подробным описанием проблемы
+- [Статья на Хабре](https://habr.com/ru/companies/bothub/news/995986/) — описание подхода на русском языке
+
+---
+
+## 📄 Лицензия
+
+[MIT](LICENSE) © opencode-hashline contributors

package/dist/chunk-C2EVIAGV.js

@@ -0,0 +1,177 @@
+import {
+  formatFileWithHashes,
+  getByteLength,
+  resolveConfig,
+  shouldExclude,
+  stripHashes
+} from "./chunk-IVZSANZ4.js";
+
+// src/hooks.ts
+import { appendFileSync } from "fs";
+import { join } from "path";
+import { homedir } from "os";
+var DEBUG_LOG = join(homedir(), ".config", "opencode", "hashline-debug.log");
+function debug(...args) {
+  const line = `[${(/* @__PURE__ */ new Date()).toISOString()}] ${args.map((a) => typeof a === "string" ? a : JSON.stringify(a)).join(" ")}
+`;
+  try {
+    appendFileSync(DEBUG_LOG, line);
+  } catch {
+  }
+}
+var FILE_READ_TOOLS = ["read", "file_read", "read_file", "cat", "view"];
+var FILE_EDIT_TOOLS = ["write", "file_write", "file_edit", "edit", "edit_file", "patch", "apply_patch", "multiedit"];
+function isFileReadTool(toolName, args) {
+  const lower = toolName.toLowerCase();
+  const nameMatch = FILE_READ_TOOLS.some(
+    (name) => lower === name || lower.endsWith(`.${name}`)
+  );
+  if (nameMatch) return true;
+  if (args && typeof args === "object") {
+    if (typeof args.path === "string" || typeof args.filePath === "string" || typeof args.file === "string") {
+      const writeIndicators = ["write", "edit", "patch", "execute", "run", "command", "shell", "bash"];
+      const isWrite = writeIndicators.some((w) => lower.includes(w));
+      if (!isWrite) return true;
+    }
+  }
+  return false;
+}
+function createFileReadAfterHook(cache, config) {
+  const resolved = config ?? resolveConfig();
+  const hashLen = resolved.hashLength || 0;
+  const prefix = resolved.prefix;
+  return async (input, output) => {
+    debug("tool.execute.after:", input.tool, "args:", input.args);
+    if (!isFileReadTool(input.tool, input.args)) {
+      debug("skipped: not a file-read tool");
+      return;
+    }
+    if (!output.output || typeof output.output !== "string") {
+      debug("skipped: no string output, type:", typeof output.output, "keys:", Object.keys(output));
+      return;
+    }
+    const content = output.output;
+    if (resolved.maxFileSize > 0) {
+      const byteLength = getByteLength(content);
+      if (byteLength > resolved.maxFileSize) {
+        return;
+      }
+    }
+    const filePath = input.args?.path || input.args?.file || input.args?.filePath;
+    if (typeof filePath === "string" && shouldExclude(filePath, resolved.exclude)) {
+      return;
+    }
+    if (cache && typeof filePath === "string") {
+      const cached = cache.get(filePath, content);
+      if (cached) {
+        output.output = cached;
+        return;
+      }
+    }
+    const annotated = formatFileWithHashes(content, hashLen || void 0, prefix);
+    output.output = annotated;
+    debug("annotated", typeof filePath === "string" ? filePath : input.tool, "lines:", content.split("\n").length);
+    if (cache && typeof filePath === "string") {
+      cache.set(filePath, content, annotated);
+    }
+  };
+}
+function createFileEditBeforeHook(config) {
+  const resolved = config ?? resolveConfig();
+  const prefix = resolved.prefix;
+  return async (input, output) => {
+    const toolName = input.tool.toLowerCase();
+    const isFileEdit = FILE_EDIT_TOOLS.some(
+      (name) => toolName === name || toolName.endsWith(`.${name}`)
+    );
+    if (!isFileEdit) return;
+    if (!output.args || typeof output.args !== "object") return;
+    const contentFields = [
+      "content",
+      "new_content",
+      "old_content",
+      "old_string",
+      "new_string",
+      "replacement",
+      "text",
+      "diff",
+      "patch",
+      "patchText"
+    ];
+    for (const field of contentFields) {
+      if (typeof output.args[field] === "string") {
+        output.args[field] = stripHashes(output.args[field], prefix);
+      }
+    }
+  };
+}
+function createSystemPromptHook(config) {
+  const resolved = config ?? resolveConfig();
+  const prefix = resolved.prefix === false ? "" : resolved.prefix;
+  return async (_input, output) => {
+    output.system.push(
+      [
+        "## Hashline \u2014 Line Reference System",
+        "",
+        `File contents are annotated with hashline prefixes in the format \`${prefix}<line>:<hash>|<content>\`.`,
+        "The hash length adapts to file size: 3 chars for files \u22644096 lines, 4 chars for larger files.",
+        "",
+        "### Example (small file, 3-char hashes):",
+        "```",
+        `${prefix}1:a3f|function hello() {`,
+        `${prefix}2:f1c|  return "world";`,
+        `${prefix}3:0e7|}`,
+        "```",
+        "",
+        "### Example (large file, 4-char hashes):",
+        "```",
+        `${prefix}1:a3f2|import { useState } from 'react';`,
+        `${prefix}2:f12c|`,
+        `${prefix}3:0e7a|export function App() {`,
+        "```",
+        "",
+        "### How to reference lines:",
+        "You can reference specific lines using their hash tags (e.g., `2:f1c` or `2:f12c`).",
+        "When editing files, you may include or omit the hash prefixes \u2014 they will be stripped automatically.",
+        "",
+        "### Edit operations using hash references:",
+        "",
+        "**Preferred tool-based edit (hash-aware):**",
+        '- Use the `hashline_edit` tool with refs like `startRef: "2:f1c"` and optional `endRef`.',
+        "- This avoids fragile old_string matching because edits are resolved by hash references.",
+        "",
+        "**Replace a single line:**",
+        '- "Replace line 2:f1c" \u2014 target a specific line unambiguously',
+        "",
+        "**Replace a block of lines:**",
+        '- "Replace block from 1:a3f to 3:0e7" \u2014 replace a range of lines',
+        "- Example: replace lines 1:a3f through 3:0e7 with new content",
+        "",
+        "**Insert content:**",
+        '- "Insert after 3:0e7" \u2014 insert new lines after a specific line',
+        '- "Insert before 1:a3f" \u2014 insert new lines before a specific line',
+        "",
+        "**Delete lines:**",
+        '- "Delete lines from 2:f1c to 3:0e7" \u2014 remove a range of lines',
+        "",
+        "### Hash verification rules:",
+        "- **Always verify** that the hash reference matches the current line content before editing.",
+        "- If a hash doesn't match, the file may have changed since you last read it \u2014 re-read the file first.",
+        '- 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.",
+        "",
+        "### 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."
+      ].join("\n")
+    );
+  };
+}
+
+export {
+  isFileReadTool,
+  createFileReadAfterHook,
+  createFileEditBeforeHook,
+  createSystemPromptHook
+};