opencode-gotcha 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 voischev
+
+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

@@ -1,3 +1,314 @@
-# Temporary Holding Version
+# opencode-gotcha
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Память проверенных обходов и рабочих приёмов для [OpenCode](https://opencode.ai),
+близкая к телу: агент узнаёт знакомую задачу или ловушку и использует успешный
+опыт до очередной серии долгих итераций.
+
+Публичная поставка — npm-пакет `opencode-gotcha`. Репозиторий разработки в SourceCraft закрытый.
+
+**Первый MVP работает в OpenCode V1 и V2.** Он хранит зацепки в Markdown, предоставляет
+пять инструментов, автоматически добавляет ранжированный индекс в контекст
+и восстанавливает его после компакции и перезапуска. Проверена работа
+в OpenCode **1.19.3** и **2.2.6**, включая установку из tarball в чистом окружении.
+Собственных runtime-зависимостей нет; V2-вход не требует SDK,
+для V1 используется опциональная peer-зависимость `@opencode-ai/plugin`.
+
+Фоновое извлечение — следующий этап. Внутренняя документация разработки,
+проектная память, тесты и CI-конфигурация в npm-пакет не входят.
+
+## Быстрый старт
+
+Для OpenCode V2 подключить npm-пакет в проектном `opencode.jsonc`:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugins": [{
+    "package": "opencode-gotcha@latest",
+    "options": { "origin": { "scope": "local" } }
+  }]
+}
+```
+
+Конфигурация V2 обновляется автоматически; принудительное обновление — `/reload`.
+Индекс появится в контексте автоматически. При первом
+сохранении создаётся `.opencode/gotcha/`; включайте его в обычный PR с кодом.
+Для проверки пути можно попросить агента вызвать `gotcha_index`.
+
+Также поддерживаются checkout и собранный tarball для участников закрытого репозитория.
+V1-вход `index.js` сохранён; ему дополнительно нужен peer `@opencode-ai/plugin`.
+V2 не импортирует SDK V1 и загружает npm-пакет через экспорт `./server`.
+
+## Что такое зацепка
+
+Зацепка — короткое прикладное знание: **при таких условиях возникает такая
+задача или проблема; вот проверенный приём и успешный пример решения**.
+
+Сохраняем проверенные обходы проблем и приёмы выполнения повторяющихся задач,
+которые сокращают нетривиальный поиск или долгие итерации. Возникновение ошибки
+необязательно: достаточно неочевидного рабочего способа, который пригодится
+снова. Ценность зацепки — в экономии будущих итераций и предотвращении тупиков.
+
+У записи должны быть:
+
+- узнаваемая задача или симптом: цель работы, сообщение об ошибке, поведение инструмента;
+- условия применимости: инструмент, окружение, версия или особенности проекта;
+- конкретный рабочий приём: действия, команда или запрос;
+- воспроизводимый успешный пример: исходные данные, действие и ожидаемый результат;
+- основание: наблюдаемый результат проверки и, когда доступен, источник.
+
+Неработающий путь добавляется, если он действительно был и его легко повторить.
+Для повторяющейся задачи важно показать, какой поиск или какие действия экономит
+приём. Частота задачи сама по себе недостаточна: запись должна сохранять полезный
+неочевидный опыт.
+
+### Что сохраняем
+
+| Подходит | Что делает запись полезной |
+| --- | --- |
+| Обход повторяющегося сбоя инструмента | Узнаваемый симптом, условия и проверенный способ продолжить |
+| Неочевидная особенность команды или API | Работающий пример с условиями и проверкой результата |
+| Короткий путь после долгого поиска решения | Объяснение, когда он применим и какие итерации экономит |
+| Приём выполнения повторяющейся задачи | Воспроизводимый успешный пример: входные данные, действия и ожидаемый результат |
+
+Примеры повторяющихся задач: запуск нужной проверки без полной пересборки,
+подбор рабочей формы сложного API-запроса или короткий сценарий проверки плагина.
+Для каждой такой записи нужен проверенный пример и объяснение сокращённого пути.
+
+Живой статус задачи остаётся в исходной системе. Разбор исправленного бага —
+в задаче или PR; повторно применимый вывод из него может стать зацепкой.
+Общие предпочтения пользователя, обычная справка и очевидные инструкции
+относятся к соответствующим правилам и документации.
+
+Если актуальный ответ уже есть в коде, документации, `AGENTS.md` или схеме
+инструмента, зацепка ссылается на него и объясняет неочевидную ловушку или
+сокращённый путь. Предположение о причине обозначается в тексте; рабочий приём
+подтверждается проверкой. Условия и результат важнее уверенной формулировки.
+
+## Как агент пользуется памятью
+
+1. Получает компактный индекс зацепок в контексте работы.
+2. Перед повторяющейся задачей, повторной попыткой после знакомой ошибки или
+   долгим перебором подходов проверяет индекс на подходящую задачу, симптомы и условия.
+3. Читает полную релевантную запись через `gotcha_read`, сверяет её применимость
+   и проверяет результат выбранного приёма.
+4. После найденного и проверенного приёма или обхода ищет существующую зацепку:
+   уточняет её или сохраняет новую через `gotcha_save`.
+5. При пересмотре обновляет изменившиеся условия и удаляет потерявшие смысл записи.
+
+Сохранённая зацепка — контекст прошлого опыта. Актуальные условия, код и
+документация определяют, можно ли применить её сейчас.
+
+## Где живут зацепки
+
+Основной режим — **проектная память, которая хранится и коммитится вместе с кодом**:
+
+```text
+.opencode/gotcha/
+├── .gitignore
+├── MEMORY.md
+├── bash-grep-sigpipe.md
+└── <ключ>.md
+```
+
+Одна зацепка — один Markdown-файл со стабильным ключом. Ссылки в `MEMORY.md`
+относительны каталогу хранилища. Плагин сообщает выбранный каталог агенту,
+чтобы подробные записи находились независимо от рабочей директории.
+
+Проектные записи и индекс включаются в обычный PR. Так участники получают
+зацепки после checkout, а изменение приёма можно обсудить вместе с кодом.
+Сам плагин обновляет файлы; Git-коммиты и публикация выполняются в рамках
+обычного процесса работы с репозиторием.
+
+### Выбор хранилища
+
+Место подключения плагина задаёт область по умолчанию. Существующая проектная
+память имеет приоритет:
+
+| Ситуация | Выбранное хранилище |
+| --- | --- |
+| В проектной области OpenCode уже есть `.opencode/gotcha/` | Проектное, в том числе при глобальном подключении плагина |
+| Плагин подключён локально, проектного хранилища ещё нет | Проектное; создаётся при первом сохранении |
+| Плагин подключён глобально, проектного хранилища нет | `<каталог глобальной конфигурации OpenCode>/gotcha/` |
+
+Обычно глобальный каталог — `~/.config/opencode/gotcha/`. Проектные записи
+физически находятся в проекте; глобальная память — самостоятельный карман
+общих зацепок.
+
+Проектный путь определяется относительно проектной конфигурации или локального
+каталога плагинов, который обнаружил OpenCode. Запуск из подкаталога выбирает
+то же хранилище этой проектной области. Вложенная проектная конфигурация задаёт
+собственную область; worktree с собственной копией конфигурации и памяти
+использует её.
+
+Для каждой операции выбирается одно хранилище, общее для инструментов и инъекции.
+Путь к npm-модулю в кэше OpenCode сам по себе не определяет область подключения.
+
+## Ранжированный индекс
+
+`MEMORY.md` — читаемый индекс и единственный источник счётчиков и дат:
+
+```markdown
+# MEMORY
+
+| Использований | Запись | Описание | Создана | Обновлена | Последнее использование |
+| ---: | --- | --- | --- | --- | --- |
+| 3 | [bash-grep-sigpipe](bash-grep-sigpipe.md) | Exit 141 при grep -q и включённом pipefail | 2026-10-28 | 2026-10-28 | 2026-10-28 |
+```
+
+- Создание зацепки = **1 использование**.
+- Каждый успешный `gotcha_read` добавляет **1** и обновляет дату использования.
+- Повторное сохранение обновляет содержимое, описание и дату изменения,
+  сохраняя накопленный счётчик, даты создания и последнего использования.
+- Порядок строк — по убыванию счётчика, при равенстве — по ключу.
+- Показ индекса, пересмотр, инъекция и компакция счётчики не увеличивают.
+- Метрики находятся в таблице. Изменения индекса записываются атомарно;
+  работа нескольких процессов с одним хранилищем требует блокировки записи.
+
+«Использование» здесь означает создание или явное чтение полной записи.
+Это показатель востребованности, а не доказательство успешного применения
+приёма. Популярность определяет порядок просмотра; задача, симптомы и условия —
+релевантность конкретной задаче.
+
+В контекст попадает индекс, подробности читаются по необходимости. При росте
+индекса сначала сокращаются описания, затем остаются ключи в ранжированном
+порядке. Целевой размер индекса — 20 000 байт; при очень большом числе записей
+список ключей может превышать этот размер, поскольку ключи не отбрасываются.
+Сжатие выполняется для запроса без переписывания пользовательских файлов.
+
+## Формат записи
+
+```markdown
+# Короткое название зацепки
+
+## Когда пригодится
+Повторяющаяся задача или симптом; условия, инструмент, окружение и версия.
+
+## Что не помогает (необязательно)
+Неудачный подход, если он был и его легко повторить.
+
+## Рабочий приём
+Конкретные действия и объяснение, какой поиск или какие итерации они сокращают.
+
+## Успешный пример
+Исходные данные, команда или запрос и ожидаемый результат.
+
+## Как проверено
+Наблюдаемый результат, условия проверки и доступный источник.
+```
+
+### Пример: grep находит строку, но конвейер завершается с кодом 141
+
+Ниже — пример готовой зацепки. Команды проверены для Bash с `pipefail`:
+получены коды 141 для раннего завершения, 0 при совпадении после обхода
+и 1 при отсутствии совпадения.
+
+````markdown
+# Раннее завершение grep -q вызывает SIGPIPE у производителя
+
+## Когда пригодится
+В Bash включён pipefail. Достаточно большой конечный поток передан в grep -q;
+совпадение встречается в начале. grep завершается с кодом 0, но производитель
+получает SIGPIPE, и весь конвейер возвращает 141.
+
+## Что не помогает
+Повторять тот же конвейер: проблема связана с ранним закрытием канала,
+а не с отсутствием искомой строки.
+
+## Рабочий приём
+Для конечного потока дать grep дочитать вход, перенаправив найденные строки
+в /dev/null. Обход применим, когда допустимо дождаться завершения производителя.
+Для бесконечного потока нужен другой способ остановки производителя.
+
+## Успешный пример
+Следующий конечный поток содержит строку 1. Команда возвращает 0:
+
+```bash
+set -o pipefail
+seq 100000 | grep '^1$' > /dev/null
+```
+
+## Как проверено
+В Bash с pipefail команда seq 100000 | grep -q '^1$' возвращает 141.
+Вариант без -q с перенаправлением в /dev/null возвращает 0.
+Замена шаблона на '^0$' возвращает 1: проверка отсутствия совпадения сохраняется.
+````
+
+### Пример: повторно проверять счётчики без запуска OpenCode
+
+Это пример приёма для повторяющейся задачи без предшествующей ошибки.
+Он относится к файловому ядру в этом репозитории и опирается на
+самодостаточный тест в [test/store.test.mjs](test/store.test.mjs).
+
+````markdown
+# Проверять счётчики и сортировку отдельным тестом хранилища
+
+## Когда пригодится
+В этом репозитории нужно повторно проверить изменение счётчиков и порядок
+индекса. В test/store.test.mjs есть самодостаточный тест, который создаёт
+изолированное хранилище и вызывает методы GotchaStore напрямую.
+
+## Рабочий приём
+Из корня репозитория запустить только этот сценарий через фильтр node:test.
+Это сокращает ручную проверку с запуском OpenCode и последовательностью вызовов
+инструментов. Сценарий проверяет файловые операции, а интеграция с хостом
+проверяется отдельно.
+
+## Успешный пример
+Нужны установленные зависимости проекта. Команда:
+
+```bash
+node --test --test-name-pattern='^индекс ранжируется по использованию, при равенстве — по ключу$' test/store.test.mjs
+```
+
+Ожидаемый результат: один прошедший тест и код завершения 0. Сценарий создаёт
+три записи со счётчиком 1, читает beta один раз и gamma дважды, затем уточняет
+gamma. Итоговый порядок: gamma — 3, beta — 2, alpha — 1.
+
+## Как проверено
+Команда выполнена: один тест прошёл, код завершения 0. Проверяются также
+сохранение счётчика при обновлении и порядок после создания нового экземпляра ядра.
+Источник: test/store.test.mjs, тест «индекс ранжируется по использованию,
+при равенстве — по ключу».
+````
+
+## Инструменты первого MVP
+
+Эти инструменты предоставляет основной вход `opencode-gotcha`.
+Параметры и критерии сохранения доступны агенту во встроенных описаниях инструментов.
+
+| Инструмент | Назначение |
+| --- | --- |
+| `gotcha_save` | Создать или уточнить зацепку, обновить индекс |
+| `gotcha_read` | Прочитать полную запись и увеличить счётчик |
+| `gotcha_index` | Показать ранжированный индекс |
+| `gotcha_forget` | Удалить запись и её строку индекса |
+| `gotcha_review` | Пересмотреть записи, их востребованность и условия применимости |
+
+В первом MVP агент следует директиве плагина и сам вызывает сохранение, когда
+найден проверенный повторно применимый обход или рабочий приём для задачи.
+Фоновое извлечение оценивается отдельным этапом на реальных сессиях.
+
+## Поэтапное развитие
+
+Каждый этап — отдельный небольшой PR с проверяемым результатом.
+Этапы 1–6 завершены: первый MVP готов. Следующий этап — фоновое извлечение
+зацепок из реальных сессий.
+
+| Этап | Состав | Критерий готовности |
+| --- | --- | --- |
+| 1. Концепция | Назначение, критерии сохранения, область памяти, формат и примеры | Понятно, что сохранять и когда читать |
+| 2. Каркас и хранилище | Пакет opencode-gotcha, файлы записей, перенос ранжированного индекса, блокировка записи | Файловые операции проверяются независимо от OpenCode, включая несколько процессов |
+| 3. Область памяти | Выбор проектного или глобального каталога | Локальное и глобальное подключение, подкаталоги и worktree выбирают ожидаемое хранилище |
+| 4. Инструменты | gotcha_save/read/index/forget/review и директива использования | Агент проходит полный цикл работы с зацепкой |
+| 5. Контекст | Инъекция индекса, восстановление после перезапуска и компакции | Зацепки доступны в новой и продолженной сессии |
+| 6. Установка | Инструкции и проверка упакованного пакета в чистом окружении | Установка и ручная проверка в OpenCode воспроизводимы |
+| 7. Фоновое извлечение | Поиск приёмов для повторяющихся задач и обходов после неудач или долгих итераций | Извлекаются проверенные приёмы с успешными примерами, без самоповторов |
+
+Основные части реализации: хранилище, выбор области, инструменты и подключение
+к контексту. Адаптеры V1 и V2 используют общее ядро, схемы и выполнение
+инструментов; ядро проверяется отдельно.
+
+При извлечении учитываются результаты инструментов и проверок. Синтетические
+инъекции, служебные запросы и уже показанные зацепки отделяются от нового опыта.
+Повторный опыт уточняет существующую запись.

package/index.js

@@ -0,0 +1,41 @@
+import { createScopedStore } from "./src/scope.js";
+import { selectPluginOrigin } from "./src/origin.js";
+import { createGotchaToolsV1 } from "./src/tools-v1.js";
+import { createContextReader } from "./src/context.js";
+
+export const GotchaPlugin = async (ctx, options = {}) => {
+  let config;
+  let selection;
+
+  function getSelected() {
+    if (!selection) {
+      selection = (async () => {
+        const origin = await selectPluginOrigin(config, import.meta.url, options.origin, ctx.directory);
+        return createScopedStore({
+          directory: ctx.directory, worktree: ctx.worktree, origin,
+          globalConfigDirectory: options.globalConfigDirectory,
+        });
+      })().catch((error) => {
+        selection = undefined;
+        throw error;
+      });
+    }
+    return selection;
+  }
+
+  const context = createContextReader(getSelected, (error) =>
+    ctx.client?.app?.log({ body: { service: "opencode-gotcha", level: "error", message: error.message } }));
+
+  return {
+    config: async (loaded) => { config = loaded; },
+    tool: createGotchaToolsV1(getSelected),
+    "experimental.chat.system.transform": async (_input, output) => {
+      output.system.push(await context());
+    },
+    "experimental.session.compacting": async (_input, output) => {
+      const memory = await context();
+      if (output.prompt !== undefined) output.prompt += `\n\n${memory}`;
+      else output.context.push(memory);
+    },
+  };
+};

package/package.json

@@ -1,6 +1,53 @@
 {
   "name": "opencode-gotcha",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "Память проверенных обходов и рабочих приёмов для повторяющихся задач в OpenCode.",
+  "type": "module",
+  "main": "index.js",
+  "exports": {
+    ".": "./index.js",
+    "./server": "./v2/index.js",
+    "./v2": "./v2/index.js",
+    "./store": "./src/store.js",
+    "./scope": "./src/scope.js"
+  },
+  "files": [
+    "index.js",
+    "v2",
+    "src",
+    "LICENSE"
+  ],
+  "peerDependencies": {
+    "@opencode-ai/plugin": ">=1.18.21 <2"
+  },
+  "peerDependenciesMeta": {
+    "@opencode-ai/plugin": { "optional": true }
+  },
+  "devDependencies": {
+    "@opencode-ai/plugin": "1.18.21"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.mjs",
+    "smoke:package": "node scripts/package-smoke.mjs",
+    "smoke:v2": "node scripts/v2-smoke.mjs",
+    "release": "node scripts/release.mjs",
+    "check": "node --check index.js && node --check v2/index.js && node --check src/markdown.js && node --check src/store.js && node --check src/lock.js && node --check src/scope.js && node --check src/origin.js && node --check src/tools.js && node --check src/tools-v1.js && node --check src/directive.js && node --check src/context.js && node --check scripts/release.mjs"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://git.sourcecraft.dev/voischev/opencode-gotcha.git"
+  },
+  "homepage": "https://www.npmjs.com/package/opencode-gotcha",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "keywords": [
+    "opencode",
+    "opencode-plugin",
+    "plugin",
+    "memory",
+    "gotcha"
+  ],
+  "license": "MIT"
+}

package/src/context.js

@@ -0,0 +1,52 @@
+import { parseIndex, rankEntries, usageCount } from "./markdown.js";
+import { gotchaDirective } from "./directive.js";
+
+export const INDEX_TARGET_BYTES = 20000;
+
+function rows(entries, descriptionLength) {
+  return entries.map((entry) => {
+    const link = `- [${entry.key}](${entry.filename})`;
+    if (descriptionLength === 0) return link;
+    const description = entry.desc.length > descriptionLength
+      ? `${Array.from(entry.desc).slice(0, descriptionLength).join("")}…`
+      : entry.desc;
+    return `${link} (${entry.accessCount})${description ? ` — ${description}` : ""}`;
+  }).join("\n");
+}
+
+export function formatContextIndex(index) {
+  const entries = rankEntries(parseIndex(index).map((entry) => ({ ...entry, accessCount: usageCount(entry.accessCount) })));
+  if (entries.length === 0) {
+    return index.trim()
+      ? "В индексе нет распознанных записей. Полный текст доступен через gotcha_index."
+      : "Хранилище пока пусто. Сохраняй проверенные приёмы через gotcha_save.";
+  }
+  const full = rows(entries, Infinity);
+  if (Buffer.byteLength(full, "utf8") <= INDEX_TARGET_BYTES) return full;
+  const notice = "Индекс большой: описания сокращены; полный индекс — gotcha_index. Пересмотр — gotcha_review.\n";
+  const shortened = notice + rows(entries, 40);
+  if (Buffer.byteLength(shortened, "utf8") <= INDEX_TARGET_BYTES) return shortened;
+  return "Индекс большой: показаны все ключи без описаний; полный индекс — gotcha_index. Пересмотр — gotcha_review.\n" + rows(entries, 0);
+}
+
+export async function gotchaContext(selected) {
+  const index = await selected.store.index();
+  return `${gotchaDirective(selected)}\n\n## Актуальный индекс зацепок\n\n${formatContextIndex(index)}`;
+}
+
+export function createContextReader(getSelected, report) {
+  let reportedError;
+  return async () => {
+    try {
+      const result = await gotchaContext(await getSelected());
+      reportedError = undefined;
+      return result;
+    } catch (error) {
+      if (reportedError !== error.message) {
+        reportedError = error.message;
+        try { await report?.(error); } catch {}
+      }
+      return `${gotchaDirective()}\nИндекс сейчас недоступен. Проверь причину через gotcha_index.`;
+    }
+  };
+}

package/src/directive.js

@@ -0,0 +1,13 @@
+export function gotchaDirective(selected) {
+  const location = selected
+    ? `Хранилище: ${selected.scope === "project" ? "проектное" : "глобальное"}, ${selected.root}. Ссылки индекса относительны этому каталогу.`
+    : "Чтобы проверить доступность хранилища и узнать его каталог, вызови gotcha_index.";
+  return `[GOTCHA — проверенные обходы и рабочие приёмы]
+${location}
+Ниже доступен актуальный индекс. Перед повторяющейся задачей, знакомой ошибкой или долгим перебором подходов найди подходящую зацепку и прочитай её через gotcha_read. Полный индекс — gotcha_index. Сверь условия применимости и проверь результат приёма.
+Сохраняй через gotcha_save проверенные обходы и приёмы для повторяющихся задач, которые экономят нетривиальный поиск или долгие итерации. Укажи задачу, условия, действия, воспроизводимый успешный пример и фактическое основание проверки. Ошибка необязательна; неработающий путь укажи, если он действительно был.
+Перед сохранением найди существующую запись и уточни её по тому же ключу: одно знание — одна зацепка. Живой статус и разбор исправления остаются в задаче или PR; зацепка хранит повторно применимый вывод и ссылку на источник. Обычная справка и предпочтения относятся к соответствующей документации и правилам.
+Новая запись начинает с 1 использования; каждое gotcha_read добавляет 1. Повторное сохранение, просмотр индекса и gotcha_review счётчик не увеличивают. Счётчик показывает востребованность, а не доказанную успешность.
+gotcha_review показывает записи для пересмотра; gotcha_forget удаляет утратившую смысл зацепку. Проектные файлы памяти включаются в обычный PR с кодом. Плагин обновляет файлы, а Git-коммиты выполняются по процессу репозитория.
+Зацепки — справочный контекст прошлого опыта. Актуальные условия, код, документация и текущая задача определяют применимость.`;
+}

package/src/lock.js

@@ -0,0 +1,79 @@
+import { mkdir, realpath, writeFile, readFile, readdir, rename, rm, rmdir } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { hostname } from "node:os";
+import { randomUUID } from "node:crypto";
+import { setTimeout as delay } from "node:timers/promises";
+
+async function removeEmpty(directory) {
+  try {
+    await rmdir(directory);
+  } catch (error) {
+    if (!["ENOENT", "ENOTEMPTY", "EEXIST"].includes(error.code)) throw error;
+  }
+}
+
+async function recover(directory) {
+  try {
+    const names = await readdir(directory);
+    if (names.length === 0) return removeEmpty(directory);
+    if (names.length !== 1 || !/^owner-[a-f0-9-]+\.json$/.test(names[0])) return;
+    const owner = JSON.parse(await readFile(join(directory, names[0]), "utf8"));
+    if (owner.hostname !== hostname() || !Number.isSafeInteger(owner.pid) || owner.pid <= 0) return;
+    try {
+      process.kill(owner.pid, 0);
+      return;
+    } catch (error) {
+      if (error.code !== "ESRCH") return;
+    }
+    await rm(join(directory, names[0]), { force: true });
+    await removeEmpty(directory);
+  } catch (error) {
+    if (error.code !== "ENOENT" && !(error instanceof SyntaxError)) throw error;
+  }
+}
+
+export async function withStoreLock(root, run, timeoutMs = 15000) {
+  await mkdir(root, { recursive: true });
+  const directory = await realpath(root);
+  const token = randomUUID();
+  const lock = join(directory, ".gotcha.lock");
+  const staging = join(directory, `.gotcha.lock.${token}.tmp`);
+  const ownerName = `owner-${token}.json`;
+  const ownerPath = join(lock, ownerName);
+  const assertOwned = () => {
+    if (!existsSync(ownerPath)) throw new Error(`Потеряна блокировка хранилища ${directory}`);
+  };
+  try {
+    await mkdir(staging);
+    await writeFile(join(staging, ownerName), JSON.stringify({ pid: process.pid, hostname: hostname() }), { flag: "wx" });
+    const deadline = performance.now() + timeoutMs;
+    try {
+      while (true) {
+        try {
+          await rename(staging, lock);
+          break;
+        } catch (error) {
+          if (!["EEXIST", "ENOTEMPTY"].includes(error.code)) throw error;
+        }
+        await recover(lock);
+        const remaining = deadline - performance.now();
+        if (remaining <= 0) throw new Error("Истекло время ожидания блокировки");
+        await delay(Math.min(25, remaining));
+      }
+    } catch (cause) {
+      throw new Error(`Не удалось заблокировать хранилище ${directory}: ${cause.message}`, { cause });
+    }
+    try {
+      assertOwned();
+      const result = await run(assertOwned);
+      assertOwned();
+      return result;
+    } finally {
+      await rm(ownerPath, { force: true });
+      await removeEmpty(lock);
+    }
+  } finally {
+    await rm(staging, { recursive: true, force: true });
+  }
+}

package/src/markdown.js

@@ -0,0 +1,70 @@
+const KEY_RE = /^[a-zA-Z0-9_-]{1,64}$/;
+const INDEX_HEADER = "| Использований | Запись | Описание | Создана | Обновлена | Последнее использование |";
+const INDEX_SEPARATOR = "| ---: | --- | --- | --- | --- | --- |";
+
+export function keyError(key) {
+  if (typeof key !== "string" || !KEY_RE.test(key)) {
+    return "ошибка: ключ должен быть из букв/цифр/_/- (макс. 64 символа)";
+  }
+  return key.toLowerCase() === "memory" ? "ошибка: ключ MEMORY зарезервирован для индекса" : null;
+}
+
+export function descriptionFromValue(value) {
+  const text = value.trim().replace(/\s+/g, " ");
+  return (text.split(/[.!?\n]/)[0].trim() || text).slice(0, 160);
+}
+
+export function usageCount(value) {
+  const count = Number(value);
+  return Number.isSafeInteger(count) && count >= 1 ? count : 1;
+}
+
+export function indexDate(value) {
+  return /^\d{4}-\d{2}-\d{2}$/.test(value ?? "") ? value : "";
+}
+
+export function rankEntries(entries) {
+  return entries.sort((a, b) =>
+    b.accessCount - a.accessCount || (a.key < b.key ? -1 : a.key > b.key ? 1 : 0));
+}
+
+function encodeCell(value) {
+  return String(value ?? "").replace(/&/g, "&amp;").replace(/\|/g, "&#124;").replace(/\s+/g, " ").trim();
+}
+
+function decodeCell(value) {
+  return value.trim().replace(/\\\|/g, "|").replace(/&#124;/g, "|").replace(/&amp;/g, "&");
+}
+
+function parseIndexLine(line) {
+  const text = line.trim();
+  if (text.startsWith("|")) {
+    const cells = text.split(/(?<!\\)\|/).slice(1, -1).map(decodeCell);
+    if (cells.length !== 6) return null;
+    const link = cells[1].match(/^\[([^\]]+)\]\(([^)]+)\)$/);
+    if (!link || keyError(link[1])) return null;
+    return {
+      key: link[1], filename: link[2], desc: cells[2], accessCount: usageCount(cells[0]),
+      created: indexDate(cells[3]), updated: indexDate(cells[4]), lastUsed: indexDate(cells[5]),
+    };
+  }
+  const match = text.match(/^- \[([^\]]+)\]\(([^)]+)\)(.*)$/);
+  if (!match || keyError(match[1])) return null;
+  return { key: match[1], filename: match[2], desc: match[3].replace(/^ —\s*/, "").trim() };
+}
+
+export function parseIndex(index) {
+  return index.split("\n").map(parseIndexLine).filter(Boolean);
+}
+
+export function renderIndex(index, entries) {
+  const lines = (index.trim() ? index : "# MEMORY\n").split("\n");
+  const managed = lines.map((line, i) => Boolean(parseIndexLine(line)) || line.trim() === INDEX_HEADER ||
+    (i > 0 && lines[i - 1].trim() === INDEX_HEADER && /^\|(?:\s*:?-+:?\s*\|){6}$/.test(line.trim())));
+  const first = managed.indexOf(true);
+  const kept = lines.filter((_line, i) => !managed[i]);
+  const table = [INDEX_HEADER, INDEX_SEPARATOR, ...rankEntries(entries).map((entry) =>
+    `| ${[entry.accessCount, `[${entry.key}](${entry.filename})`, entry.desc, entry.created, entry.updated, entry.lastUsed].map(encodeCell).join(" | ")} |`)];
+  kept.splice(first < 0 ? kept.length : first, 0, ...table);
+  return `${kept.join("\n").trimEnd()}\n`;
+}

package/src/origin.js

@@ -0,0 +1,62 @@
+import { realpath, stat } from "node:fs/promises";
+import { dirname, isAbsolute, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+async function physical(path) {
+  try {
+    return await realpath(path);
+  } catch (error) {
+    if (error.code !== "ENOENT") throw error;
+    return resolve(path);
+  }
+}
+
+function pathValue(value) {
+  if (value instanceof URL || typeof value === "string" && value.startsWith("file:")) {
+    return fileURLToPath(value);
+  }
+  return typeof value === "string" && isAbsolute(value) ? value : null;
+}
+
+async function specPath(spec, source, workingDirectory) {
+  const absolute = pathValue(spec);
+  if (absolute) return physical(absolute);
+  if (!/^\.{1,2}[\\/]/.test(spec)) return null;
+  const path = pathValue(source);
+  if (!path) {
+    const base = source === "OPENCODE_CONFIG_CONTENT" && pathValue(workingDirectory);
+    return base ? physical(resolve(base, spec)) : null;
+  }
+  let directory = path;
+  try {
+    if (!(await stat(path)).isDirectory()) directory = dirname(path);
+  } catch (error) {
+    if (error.code !== "ENOENT") throw error;
+    directory = dirname(path);
+  }
+  return physical(resolve(directory, spec));
+}
+
+export async function selectPluginOrigin(config, moduleURL, explicitOrigin, workingDirectory) {
+  const modulePath = await physical(fileURLToPath(moduleURL));
+  const origins = config?.plugin_origins ?? [];
+  if (!Array.isArray(origins)) throw new Error("Некорректные метаданные происхождения плагинов OpenCode");
+  const candidates = [];
+  for (const origin of origins) {
+    if (!origin || typeof origin !== "object") continue;
+    const spec = Array.isArray(origin.spec) ? origin.spec[0] : origin.spec;
+    if (typeof spec !== "string") continue;
+    const path = await specPath(spec, origin.source, workingDirectory);
+    if (/^opencode-gotcha(?:@[^/]+)?$/.test(spec) || path === modulePath || path === dirname(modulePath)) {
+      candidates.push({ scope: origin.scope, source: origin.source });
+    }
+  }
+  const unique = [...new Map(candidates.map((origin) => [JSON.stringify(origin), origin])).values()];
+  if (unique.length > 1) {
+    const matches = explicitOrigin && unique.filter((origin) =>
+      origin.scope === explicitOrigin.scope && String(origin.source) === String(explicitOrigin.source));
+    if (matches?.length === 1) return matches[0];
+    throw new Error("Неоднозначный источник opencode-gotcha: укажите origin для этого подключения");
+  }
+  return unique[0] ?? explicitOrigin;
+}

package/src/scope.js

@@ -0,0 +1,105 @@
+import { realpath, stat } from "node:fs/promises";
+import { basename, dirname, extname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { homedir } from "node:os";
+import { fileURLToPath } from "node:url";
+import { GotchaStore } from "./store.js";
+
+function absolutePath(value, label) {
+  if (value instanceof URL || typeof value === "string" && value.startsWith("file:")) {
+    value = fileURLToPath(value);
+  }
+  if (typeof value !== "string" || !isAbsolute(value)) {
+    throw new TypeError(`${label} должен быть абсолютным путём`);
+  }
+  return resolve(value);
+}
+
+async function info(path) {
+  try {
+    return await stat(path);
+  } catch (error) {
+    if (error.code !== "ENOENT") throw error;
+    return null;
+  }
+}
+
+async function canonical(path) {
+  try {
+    return await realpath(path);
+  } catch (error) {
+    if (error.code !== "ENOENT") throw error;
+    const parent = dirname(path);
+    if (parent === path) throw error;
+    return join(await canonical(parent), basename(path));
+  }
+}
+
+function inside(root, path) {
+  const rel = relative(root, path);
+  return rel === "" || rel !== ".." && !rel.startsWith(`..${sep}`) && !isAbsolute(rel);
+}
+
+async function sourceDirectory(source) {
+  if (!source || source === "OPENCODE_CONFIG_CONTENT" || /^https?:/.test(String(source))) return null;
+  const path = absolutePath(source, "Источник подключения");
+  const state = await info(path);
+  let directory = state?.isDirectory() || !state && !extname(path) ? path : dirname(path);
+  if (["plugin", "plugins"].includes(basename(directory))) directory = dirname(directory);
+  return canonical(directory);
+}
+
+async function projectArea(directory, boundary, globalConfigDirectory) {
+  if (inside(globalConfigDirectory, directory)) return null;
+  for (let current = directory; ; current = dirname(current)) {
+    const configDirectory = join(current, ".opencode");
+    const memory = join(configDirectory, "gotcha");
+    const memoryInfo = await info(memory);
+    if (memoryInfo && !memoryInfo.isDirectory()) throw new Error(`Хранилище должно быть каталогом: ${memory}`);
+    if (memoryInfo) return { projectRoot: current, root: await canonical(memory), existing: true };
+    const configInfo = await info(configDirectory);
+    if (configInfo && !configInfo.isDirectory()) throw new Error(`Ожидался каталог конфигурации: ${configDirectory}`);
+    if (configInfo || (await info(join(current, "opencode.json")))?.isFile() ||
+      (await info(join(current, "opencode.jsonc")))?.isFile()) {
+      return { projectRoot: current, root: join(configDirectory, "gotcha"), existing: false };
+    }
+    if (current === boundary || dirname(current) === current) return null;
+  }
+}
+
+export async function resolveScope({ directory, worktree, origin, globalConfigDirectory } = {}) {
+  const workingDirectory = await realpath(absolutePath(directory, "Рабочий каталог"));
+  if (!(await stat(workingDirectory)).isDirectory()) throw new TypeError("Рабочий каталог должен быть каталогом");
+  const boundary = worktree ? await realpath(absolutePath(worktree, "Worktree")) : undefined;
+  if (boundary && !inside(boundary, workingDirectory)) throw new Error("Рабочий каталог находится за пределами worktree");
+  if (origin && !["local", "global"].includes(origin.scope)) throw new TypeError("Область подключения должна быть local или global");
+
+  const source = await sourceDirectory(origin?.source);
+  const defaultGlobal = process.env.OPENCODE_CONFIG_DIR ||
+    join(process.env.XDG_CONFIG_HOME || join(homedir(), ".config"), "opencode");
+  const globalDirectory = await canonical(absolutePath(
+    globalConfigDirectory ?? (origin?.scope === "global" ? source : null) ?? defaultGlobal,
+    "Глобальный каталог конфигурации",
+  ));
+  const area = await projectArea(workingDirectory, boundary, globalDirectory);
+  if (area?.existing) {
+    return { scope: "project", root: area.root, projectRoot: area.projectRoot, reason: "project-store", source: origin?.source ?? null };
+  }
+  if (!origin) throw new Error("Неизвестна область подключения плагина: нужен источник конфигурации OpenCode");
+  if (origin.scope === "local") {
+    const sourceRoot = source && basename(source) === ".opencode" ? dirname(source) : source;
+    if (sourceRoot && !inside(sourceRoot, workingDirectory)) throw new Error("Локальная конфигурация находится вне рабочей проектной области");
+    const projectRoot = area?.projectRoot ?? sourceRoot ?? workingDirectory;
+    if (boundary && !inside(boundary, projectRoot)) throw new Error("Локальная конфигурация находится за пределами worktree");
+    return {
+      scope: "project", root: await canonical(join(projectRoot, ".opencode", "gotcha")),
+      projectRoot, reason: "local-plugin", source: origin.source ?? null,
+    };
+  }
+  return { scope: "global", root: join(globalDirectory, "gotcha"), projectRoot: null, reason: "global-plugin", source: origin.source ?? null };
+}
+
+export async function createScopedStore({ storeOptions, ...options } = {}) {
+  const selected = await resolveScope(options);
+  const store = new GotchaStore(selected.root, { ...storeOptions, gitignore: selected.scope === "project" });
+  return { ...selected, store };
+}

package/src/store.js

@@ -0,0 +1,210 @@
+import { readFile, writeFile, stat, readdir, rename, rm } from "node:fs/promises";
+import { basename, dirname, join, resolve } from "node:path";
+import { randomUUID } from "node:crypto";
+import { homedir } from "node:os";
+import { descriptionFromValue, indexDate, keyError, parseIndex, rankEntries, renderIndex, usageCount } from "./markdown.js";
+import { withStoreLock } from "./lock.js";
+
+function today() {
+  return new Date().toISOString().slice(0, 10);
+}
+
+async function readOptional(file) {
+  try {
+    return await readFile(file, "utf8");
+  } catch (error) {
+    if (error.code !== "ENOENT") throw error;
+    return "";
+  }
+}
+
+async function atomicWrite(file, content, assertOwned) {
+  const temporary = join(dirname(file), `.${basename(file)}.${randomUUID()}.tmp`);
+  let mode;
+  try {
+    mode = (await stat(file)).mode;
+  } catch (error) {
+    if (error.code !== "ENOENT") throw error;
+  }
+  try {
+    await writeFile(temporary, content, { flag: "wx", mode });
+    assertOwned();
+    await rename(temporary, file);
+  } finally {
+    await rm(temporary, { force: true });
+  }
+}
+
+export class GotchaStore {
+  #cache = null;
+
+  constructor(root, { lockTimeoutMs = 15000, gitignore = false } = {}) {
+    if (typeof root !== "string" || !root.trim()) throw new TypeError("Нужен каталог хранилища");
+    if (!Number.isFinite(lockTimeoutMs) || lockTimeoutMs < 0) throw new TypeError("Некорректное время ожидания блокировки");
+    this.root = resolve(root.startsWith("~/") ? join(homedir(), root.slice(2)) : root);
+    this.indexPath = join(this.root, "MEMORY.md");
+    this.lockTimeoutMs = lockTimeoutMs;
+    this.gitignore = gitignore;
+  }
+
+  async index() {
+    try {
+      const info = await stat(this.indexPath);
+      const signature = `${info.ino}:${info.mtimeMs}:${info.size}`;
+      if (this.#cache?.signature === signature) return this.#cache.content;
+      const content = await readFile(this.indexPath, "utf8");
+      this.#cache = { signature, content };
+      return content;
+    } catch (error) {
+      if (error.code !== "ENOENT") throw error;
+      this.#cache = null;
+      return "";
+    }
+  }
+
+  async list() {
+    return (await this.#loadEntries(await this.index())).filter((entry) => entry.present);
+  }
+
+  async peek(key) {
+    const file = await this.#findFile(key);
+    if (!file) return null;
+    try {
+      const content = await readFile(file, "utf8");
+      const entry = (await this.#loadEntries(await this.index())).find((item) => item.filename === basename(file));
+      return entry ? { entry, content } : null;
+    } catch (error) {
+      if (error.code !== "ENOENT") throw error;
+      return null;
+    }
+  }
+
+  async save({ key, value, description }) {
+    const error = keyError(key);
+    if (error) throw new TypeError(error);
+    if (typeof value !== "string") throw new TypeError("Содержимое записи должно быть строкой");
+    if (description !== undefined && typeof description !== "string") throw new TypeError("Описание записи должно быть строкой");
+    return this.#mutate(async (assertOwned) => {
+      const index = await readOptional(this.indexPath);
+      const entries = await this.#loadEntries(index);
+      const existingFile = await this.#findFile(key);
+      const file = existingFile ?? join(this.root, `${key}.md`);
+      const filename = basename(file);
+      let entry = entries.find((item) => item.filename === filename || item.key === key);
+      if (!entry) {
+        entry = { key, filename, accessCount: 1, created: today(), lastUsed: today() };
+        entries.push(entry);
+      }
+      entry.filename = filename;
+      entry.created ||= today();
+      entry.updated = today();
+      entry.desc = description || descriptionFromValue(value);
+      entry.present = true;
+      await atomicWrite(file, value.endsWith("\n") ? value : `${value}\n`, assertOwned);
+      await this.#writeIndex(index, entries, assertOwned);
+      return { entry, isNew: !existingFile };
+    });
+  }
+
+  async read(key) {
+    if (!(await this.#findFile(key))) return null;
+    return this.#mutate(async (assertOwned) => {
+      const file = await this.#findFile(key);
+      if (!file) return null;
+      const content = await readFile(file, "utf8");
+      const index = await readOptional(this.indexPath);
+      const entries = await this.#loadEntries(index);
+      const entry = entries.find((item) => item.filename === basename(file));
+      entry.accessCount = Math.min(Number.MAX_SAFE_INTEGER, entry.accessCount + 1);
+      entry.lastUsed = today();
+      await this.#writeIndex(index, entries, assertOwned);
+      return { entry, content };
+    });
+  }
+
+  async forget(key) {
+    if (!(await this.#findFile(key))) return null;
+    return this.#mutate(async (assertOwned) => {
+      const file = await this.#findFile(key);
+      if (!file) return null;
+      const content = await readFile(file, "utf8");
+      const index = await readOptional(this.indexPath);
+      const entries = await this.#loadEntries(index);
+      const entry = entries.find((item) => item.filename === basename(file));
+      assertOwned();
+      await rm(file);
+      await rm(join(this.root, ".data", entry.key), { force: true });
+      await this.#writeIndex(index, entries.filter((item) => item !== entry), assertOwned);
+      return { entry, content };
+    });
+  }
+
+  async #mutate(run) {
+    return withStoreLock(this.root, async (assertOwned) => {
+      if (this.gitignore) {
+        assertOwned();
+        try {
+          await writeFile(join(this.root, ".gitignore"), ".gotcha.lock/\n.gotcha.lock.*.tmp/\n.*.md.*.tmp\n", { flag: "wx" });
+        } catch (error) {
+          if (error.code !== "EEXIST") throw error;
+        }
+      }
+      return run(assertOwned);
+    }, this.lockTimeoutMs);
+  }
+
+  async #writeIndex(index, entries, assertOwned) {
+    await atomicWrite(this.indexPath, renderIndex(index, entries), assertOwned);
+    this.#cache = null;
+  }
+
+  async #filenames() {
+    try {
+      const entries = await readdir(this.root, { withFileTypes: true });
+      return entries.filter((entry) => entry.isFile()).map((entry) => entry.name);
+    } catch (error) {
+      if (error.code !== "ENOENT") throw error;
+      return [];
+    }
+  }
+
+  async #findFile(key) {
+    if (keyError(key)) return null;
+    const names = (await this.#filenames()).filter((name) => name.endsWith(".md") && !keyError(basename(name, ".md")));
+    const filename = names.includes(`${key}.md`) ? `${key}.md` : null;
+    return filename ? join(this.root, filename) : null;
+  }
+
+  async #loadEntries(index) {
+    const entries = new Map(parseIndex(index).map((entry) => [entry.key, entry]));
+    const indexedFilenames = new Set([...entries.values()].map((entry) => entry.filename));
+    const names = await this.#filenames();
+    for (const filename of names) {
+      const key = basename(filename, ".md");
+      if (!filename.endsWith(".md") || keyError(key) || indexedFilenames.has(filename)) continue;
+      const entry = entries.get(key);
+      try {
+        entries.set(key, entry
+          ? { ...entry, filename }
+          : { key, filename, desc: descriptionFromValue(await readFile(join(this.root, filename), "utf8")) });
+      } catch (error) {
+        if (error.code !== "ENOENT") throw error;
+      }
+    }
+    const files = new Set(names);
+    for (const entry of entries.values()) {
+      entry.present = files.has(entry.filename);
+      if (entry.accessCount !== undefined) continue;
+      const data = await readOptional(join(this.root, ".data", entry.key));
+      const fields = Object.fromEntries(data.split("\n").filter((line) => line.includes("=")).map((line) => {
+        const separator = line.indexOf("=");
+        return [line.slice(0, separator), line.slice(separator + 1)];
+      }));
+      entry.accessCount = usageCount(fields.access_count);
+      entry.created = indexDate(fields.created);
+      entry.updated = indexDate(fields.updated);
+      entry.lastUsed = indexDate(fields.last_used);
+    }
+    return rankEntries([...entries.values()]);
+  }
+}

package/src/tools-v1.js

@@ -0,0 +1,15 @@
+import { tool } from "@opencode-ai/plugin";
+import { createGotchaTools } from "./tools.js";
+
+export function createGotchaToolsV1(getSelected) {
+  return Object.fromEntries(Object.entries(createGotchaTools(getSelected)).map(([name, definition]) => {
+    const args = Object.fromEntries(Object.entries(definition.input.properties).map(([field, schema]) => {
+      let value = tool.schema.string().trim().min(schema.minLength).describe(schema.description);
+      if (schema.maxLength) value = value.max(schema.maxLength);
+      if (schema.pattern) value = value.regex(new RegExp(schema.pattern));
+      if (!definition.input.required.includes(field)) value = value.optional();
+      return [field, value];
+    }));
+    return [name, tool({ description: definition.description, args, execute: definition.execute })];
+  }));
+}

package/src/tools.js

@@ -0,0 +1,96 @@
+import { keyError } from "./markdown.js";
+
+function text(description) {
+  return { type: "string", minLength: 1, description };
+}
+
+const key = {
+  ...text("Стабильный ключ зацепки: латиница, цифры, _ или -, до 64 символов; MEMORY зарезервирован, префикс типа не требуется"),
+  maxLength: 64, pattern: "^(?![Mm][Ee][Mm][Oo][Rr][Yy]$)[A-Za-z0-9_-]+$",
+};
+
+function markdown(args) {
+  const sections = [
+    `# ${args.description}`,
+    `## Когда пригодится\n${args.task}\n\n${args.conditions}`,
+  ];
+  if (args.failedAttempt) sections.push(`## Что не помогает\n${args.failedAttempt}`);
+  sections.push(
+    `## Рабочий приём\n${args.steps}`,
+    `## Успешный пример\n${args.example}`,
+    `## Как проверено\n${args.verification}`,
+  );
+  return `${sections.join("\n\n")}\n`;
+}
+
+function define(getSelected, description, properties, run, optional = []) {
+  const required = Object.keys(properties).filter((field) => !optional.includes(field));
+  return {
+    description,
+    input: { type: "object", properties, required, additionalProperties: false },
+    async execute(input = {}) {
+      const args = {};
+      const fields = [];
+      if (!input || typeof input !== "object" || Array.isArray(input)) fields.push("args");
+      else for (const [field, schema] of Object.entries(properties)) {
+        if (input[field] === undefined && !required.includes(field)) continue;
+        const value = typeof input[field] === "string" ? input[field].trim() : undefined;
+        if (!value || schema.maxLength && value.length > schema.maxLength ||
+          schema.pattern && !new RegExp(schema.pattern).test(value) || field === "key" && keyError(value)) fields.push(field);
+        else args[field] = value;
+      }
+      if (fields.length) {
+        return JSON.stringify({ ok: false, error: `Некорректные параметры: ${fields.join(", ")}` });
+      }
+      let selected;
+      try {
+        selected = await getSelected();
+        return JSON.stringify({ ok: true, scope: selected.scope, root: selected.root, ...await run(args, selected.store) });
+      } catch (error) {
+        return JSON.stringify({
+          ok: false, ...(selected ? { scope: selected.scope, root: selected.root } : {}),
+          error: error.message ?? String(error),
+        });
+      }
+    },
+  };
+}
+
+export function createGotchaTools(getSelected) {
+  return {
+    gotcha_save: define(getSelected,
+      "Сохранить или уточнить проверенный обход или приём повторяющейся задачи. Сначала проверь индекс на дубли. Нужны успешный пример и основание проверки; ошибка необязательна. Создание = 1 использование, обновление сохраняет счётчик.", {
+        key,
+        description: { ...text("Короткое однострочное описание: когда пригодится зацепка"), maxLength: 160, pattern: "^[^\\r\\n]+$" },
+        task: text("Повторяющаяся задача или узнаваемый симптом"),
+        conditions: text("Условия применимости: инструмент, окружение, версия или особенности проекта"),
+        steps: text("Конкретные действия и объяснение, какой поиск или какие итерации они экономят"),
+        example: text("Воспроизводимый успешный пример: исходные данные, команда или запрос и ожидаемый результат"),
+        verification: text("Фактический результат проверки, условия проверки и доступный источник"),
+        failedAttempt: text("Неудачный путь, если он действительно был и его легко повторить"),
+      }, async (args, store) => {
+        const result = await store.save({ key: args.key, description: args.description, value: markdown(args) });
+        return { key: result.entry.key, uses: result.entry.accessCount, action: result.isNew ? "created" : "updated" };
+      }, ["failedAttempt"]),
+    gotcha_read: define(getSelected, "Прочитать полную зацепку и увеличить счётчик использования на 1. Сверь условия и проверь результат приёма.", { key }, async (args, store) => {
+      const result = await store.read(args.key);
+      return result
+        ? { key: result.entry.key, uses: result.entry.accessCount, content: result.content }
+        : { ok: false, key: args.key, error: "Зацепка не найдена" };
+    }),
+    gotcha_index: define(getSelected, "Показать ранжированный индекс и выбранное хранилище. Используй перед повторяющейся задачей или сохранением нового приёма. Счётчики не меняются.", {}, async (_args, store) => ({ index: await store.index() })),
+    gotcha_forget: define(getSelected, "Удалить утратившую смысл зацепку и её строку индекса. Возвращает удалённый текст.", { key }, async (args, store) => {
+      const result = await store.forget(args.key);
+      return result
+        ? { key: result.entry.key, action: "deleted", content: result.content }
+        : { ok: false, key: args.key, error: "Зацепка не найдена" };
+    }),
+    gotcha_review: define(getSelected, "Показать записи по востребованности, описания и даты для пересмотра применимости. Популярность не доказывает успешность; просмотр не увеличивает счётчики.", {}, async (_args, store) => ({
+      entries: (await store.list()).map((entry) => ({
+        key: entry.key, description: entry.desc, uses: entry.accessCount,
+        created: entry.created, updated: entry.updated, lastUsed: entry.lastUsed,
+      })),
+      indexBytes: Buffer.byteLength(await store.index(), "utf8"),
+    })),
+  };
+}

package/v2/index.js

@@ -0,0 +1,38 @@
+import { createScopedStore } from "../src/scope.js";
+import { createGotchaTools } from "../src/tools.js";
+import { createContextReader } from "../src/context.js";
+
+export default {
+  id: "opencode-gotcha",
+  async setup(ctx) {
+    let selection;
+    const getSelected = () => {
+      selection ??= createScopedStore({
+        directory: ctx.location.directory,
+        worktree: ctx.location.project.directory,
+        origin: ctx.options.origin,
+        globalConfigDirectory: ctx.options.globalConfigDirectory,
+      }).catch((error) => {
+        selection = undefined;
+        throw error;
+      });
+      return selection;
+    };
+    const context = createContextReader(getSelected, (error) => console.error(`opencode-gotcha: ${error.message}`));
+    const tools = createGotchaTools(getSelected);
+    await ctx.tool.transform((editor) => {
+      for (const [name, definition] of Object.entries(tools)) {
+        editor.add({
+          name, description: definition.description, input: definition.input,
+          options: { codemode: true },
+          execute: async (input) => ({ content: await definition.execute(input) }),
+        });
+      }
+    });
+    for (const kind of ["context", "compaction"]) {
+      await ctx.session.hook(kind, async (event) => {
+        event.system.push({ type: "text", text: await context() });
+      });
+    }
+  },
+};