@smwb/onreel-git-mcp 0.2.0 → 0.3.0

package/README.md

@@ -0,0 +1,489 @@
+# @smwb/onreel-git-mcp
+
+Библиотека модулей, выделенных из [onreel](https://git.sourcecraft.dev/elfenmail/onreel) в отдельно
+версионируемый npm-пакет:
+
+- **git-обвязка** — запуск `git` дочерним процессом через пул с таймаутами и ограничением параллелизма,
+  операции над worktree, ветками, статусом, diff, коммитом и rebase, и **безопасные пути**
+  (проверка confinement по realpath, отказ на симлинк);
+- **листинги** — список записей одного каталога worktree для ревью;
+- **жизненный цикл worktree** — замки, двухфазное создание и очистка, сверка при старте, свип и корзина —
+  против портов хранения, которые реализует потребитель;
+- **адаптеры трекеров** — единая модель задач и пять адаптеров: GitHub, GitLab, Jira, SourceCraft и локальный
+  трекер поверх хранилища потребителя;
+- **MCP stdio-сервер** — JSON-RPC 2.0 поверх stdin/stdout, инструменты строятся из таблицы команд вызывающего.
+
+Пакет ESM, рантайм-зависимость одна — `zod`. Публичная поверхность держится документированной здесь:
+новый субпуть или публичный символ добавляют вместе с записью в этом README.
+
+## Установка
+
+```sh
+npm i @smwb/onreel-git-mcp
+```
+
+Требуется **Node.js >= 24** (в `package.json` — `engines`) и **Linux**: код рассчитывает на маску прав
+сессии (`umask`), групповой `SIGKILL` процесса git и чтение `/proc/<pid>/environ` в выборе принципала MCP.
+CI и тесты идут на образе `node:24-bookworm`; в репозиторий git должен быть доступен как команда —
+своих git-библиотек в зависимостях нет.
+
+Импортируют по субпутям, ядро (`src/kernel/`) своего субпути не имеет — его типы достаются из тех
+субпутей, где они нужны вызывающему.
+
+| Субпуть | Что отдаёт | Ссылка |
+|---|---|---|
+| `@smwb/onreel-git-mcp` | срез контракта: константы env, zod-схемы и типы (`Issue`, `Worktree`, `ContractError`), чистые помощники (`contractError`, `sessionUmask`), `VERSION` | [Контракт](#контракт) |
+| `…/git` | `runGit`, `GitError`, управление пулом, операции над репозиторием и worktree, безопасные пути, маскирование секретов | [git](#git) |
+| `…/files` | `listWorktreeDir`, `DirRefusal` | [files](#files) |
+| `…/worktree` | замки, `finishPreparing`/`finishCleaning`, reconciler, корзина — против порта `WorktreeStore` | [worktree](#worktree) |
+| `…/tracker` | типы портов, реестр, `registerBuiltinTrackers()`, пять фабрик адаптеров, файловое хранилище токенов | [tracker](#tracker) |
+| `…/mcp` | `serveMcp`, `mcpToolSpecs`, сборщики инструментов, выбор принципала | [mcp](#mcp) |
+| `…/package.json` | манифест пакета | [package.json](#packagejson) |
+
+Побочных эффектов при импорте нет нигде (R-001): регистрации, пулы и фоновые циклы запускаются только
+явными вызовами — `registerBuiltinTrackers()`, `startWorktreeReconciler()`, `serveMcp()`.
+
+Дальше — рабочие примеры; их же компилируемая версия лежит в [`examples/`](examples) и проверяется
+`npm run typecheck` в CI. Примеры импортируют `src/` напрямую, а не субпути пакета: в CI линтер и
+typecheck идут до `npm run build`, когда `dist/` ещё нет. Node 24 выполняет TypeScript напрямую, поэтому
+каждый пример запускается и без сборки: `node examples/git.lib.ts`.
+
+## Контракт
+
+Корневой субпуть — срез контракта onreel: константы имён переменных окружения, схемы и выведенные из них
+типы, чистые помощники ошибок. Имена `ONREEL_*` заморожены как есть: их смена ломает interop onreel ↔ библиотека.
+
+```ts
+import { ENV_TOKEN, HOST_CONTRACT_VERSION, VERSION, contractError, formatVersion } from '@smwb/onreel-git-mcp';
+
+const version = formatVersion(HOST_CONTRACT_VERSION); // '1.14' — версия контракта host
+console.log(`библиотека ${VERSION}, контракт host ${version}, токен читают из ${ENV_TOKEN}`);
+
+// Ошибку собирают здесь и отдают наружу: код из каталога, непустое сообщение и обязательные nextSteps.
+const error = contractError('not_found', 'Задачи 42 нет.', ['Откройте список задач.']);
+console.log(error.code, error.message, error.nextSteps.join(' '));
+```
+
+## git
+
+Каждая git-команда — дочерний процесс `git`: аргументы массивом (без shell), не больше четырёх
+одновременно, таймаут 120 с (`GIT_TIMEOUT_MS`), для `worktree add` — 600 с (`GIT_CHECKOUT_TIMEOUT_MS`),
+вывод не больше 16 МиБ. Всё, что приходит от клиента, git получает только после `--end-of-options`
+или уже резолвленным в sha. Окружение ребёнка очищено от унаследованных `GIT_*`, права создаваемых
+файлов берутся из маски сессии.
+
+```ts
+import {
+  addWorktree,
+  changedFiles,
+  closeGitPool,
+  commitChanges,
+  currentBranch,
+  GitError,
+  headOf,
+  readWorktreeFile,
+  repoToplevel,
+  resolveCommit,
+  runGit,
+} from '@smwb/onreel-git-mcp/git';
+
+const repo = await repoToplevel('/home/user/project');
+const branch = await currentBranch(repo); // detached HEAD — undefined
+const baseSha = await headOf(repo);
+
+await addWorktree(repo, '/home/user/.onreel/workspaces/project-1a2b3c/run-1/task-1', 'onreel/run-1/task-1', baseSha);
+
+const wt = '/home/user/.onreel/workspaces/project-1a2b3c/run-1/task-1';
+const outcome = await commitChanges(wt, '#12 Правка по задаче'); // committed: false, если коммитить нечего
+const changes = await changedFiles(wt, baseSha);                 // отслеживаемые против базы; без неотслеживаемых
+const file = await readWorktreeFile(wt, 'src/main.ts', 64 * 1024); // {size, binary, truncated, text?}
+console.log(branch, outcome.committed, changes.length, file?.text === undefined);
+
+// Нештатный код, таймаут или переполнение вывода — GitError.
+const missing = await resolveCommit(repo, 'refs/heads/нет-такой-ветки'); // undefined, не ошибка
+try {
+  await runGit(['rev-parse', '--verify', 'HEAD^1'], repo, { okCodes: [] });
+} catch (error) {
+  if (error instanceof GitError) console.log(error.exitCode, error.timedOut, error.stderr);
+}
+```
+
+**Остановка процесса.** `closeGitPool()` вызывает потребитель в своей точке остановки host'а: очередь
+отклоняется, запущенные git убиваются групповым `SIGKILL`. `isGitPoolClosed()` позволяет отличить сбой
+«пул закрыт, мы останавливаемся» от настоящей ошибки git — в последнем случае запись `failed` не пишут.
+`reopenGitPool()` — только для тестов.
+
+**Маскирование секретов (D-272, D-194).** `GitError` маскирует аргументы и stderr **до** обрезки, иначе
+срез оставил бы префикс секрета, который шаблон не узнаёт; stdout маскируется при первом чтении. Шаблонов
+R1–R8 (URL с `user:pass@`, `Authorization:`, известные ключи доступа, JWT, PEM, `onr_…`-токен, присваивания
+вида `token = …`, пароли в CLI-флагах) бывает мало — значение, не похожее ни на один шаблон, регистрируют
+в приёмнике секретов:
+
+```ts
+import { defaultSecretSink, redactSecretText, type SecretSink } from '@smwb/onreel-git-mcp/git';
+
+defaultSecretSink.register(process.env.MYopaqueValue ?? ''); // короче 8 символов — игнорируется
+console.log(redactSecretText('клон https://user:секрет@git.example/o/r и MYopaqueValue'));
+
+// Потребитель со своим журналом подставляет свой приёмник — тем же типом SecretSink.
+const known = new Set<string>();
+const sink: SecretSink = {
+  register(secret: string): void {
+    known.add(secret);
+  },
+};
+```
+
+Значения `SecretSink`, `defaultSecretSink` и `redactSecretText` реэкспортированы из `…/git`; отдельного
+субпути `…/kernel` у пакета нет.
+
+## files
+
+`listWorktreeDir` отдаёт записи одного каталога worktree: не глубже одного уровня, симлинки не разыменовываются
+(`symlink` остаётся листом), служебный `.git` пропускается без учёта регистра, каталог и путь запроса проверяются
+на confinement по realpath. `truncated` ставится, если просмотрели больше `scanMax` записей или обрезали по
+`maxEntries`; имя не в UTF-8 тоже обрезает список с этим признаком.
+
+```ts
+import { DirRefusal, listWorktreeDir } from '@smwb/onreel-git-mcp/files';
+
+try {
+  const root = await listWorktreeDir(dataDir, worktreePath, undefined);
+  const nested = await listWorktreeDir(dataDir, worktreePath, 'src', { maxEntries: 200, scanMax: 1000 });
+  console.log(root.truncated, root.entries.map((entry) => `${entry.kind} ${entry.path}`), nested.entries.length);
+} catch (error) {
+  // Причина отказа — часть контракта: её контроллер переводит в ошибку worktree.files по матрице D-367.
+  if (error instanceof DirRefusal) console.log(error.reason); // 'outside_worktree' | 'excluded' | 'not_found' | …
+  else throw error;
+}
+```
+
+## worktree
+
+Двухфазные создание и очистка (onreel D-050): receipt-транзакция потребителя записала `preparing` или
+`cleaning`, библиотека доводит состояние до `ready`, `cleaned` или `failed`, работая с git и диском вне
+транзакции. Состояние читается и пишется через **порт `WorktreeStore`** — его реализует вызывающий (D-003);
+в пакете нет ни SQLite, ни ledger, ни другой конкретной БД.
+
+```ts
+import {
+  finishPreparing,
+  isWorktreeBusy,
+  startWorktreeReconciler,
+  withWorktreeLock,
+  type WorktreeLifecycleServices,
+  type WorktreeStore,
+} from '@smwb/onreel-git-mcp/worktree';
+
+const services: WorktreeLifecycleServices = {
+  store: myStore satisfies WorktreeStore,
+  dataDir: '/home/user/.onreel',
+  log: (line) => console.error(line),
+};
+
+await finishPreparing(services, 'wt-9'); // preparing → ready с HEAD; сбой → failed и сразу очистка остатков
+
+const reconciler = startWorktreeReconciler(services); // 30 с по умолчанию (WORKTREE_RECONCILE_INTERVAL_MS)
+await reconciler.kick(); // свип вне таймера: после мержа, после stop воркера
+await reconciler.stop();
+
+// Замок — один на worktree в пределах процесса: создание, очистка, коммит и rebase не перекрываются.
+console.log(isWorktreeBusy('wt-9'));
+await withWorktreeLock('wt-9', async () => {
+  /* работа с этим worktree */
+});
+```
+
+Стартует `startWorktreeReconciler` — он же делает сверку при старте (`reconcileWorktreesAtStart`: осиротевший
+`preparing` → `failed` и в очистку) и доочищает корзину (`emptyTrash`). `sweepWorktrees` отдельно готовит к
+очистке `ready`-worktree завершённых задач и доводит начатые `cleaning`. Незакоммиченные изменения без явного
+решения вызывающего (`discardChanges`) очистка не выбрасывает: worktree уходит в `failed` и ждёт решения.
+
+Порт `WorktreeStore` раскрывает пять методов и явную единицу работы — `inTransaction(fn)`, которой вызывают
+все переходы (`markWorktreeReady`, `markWorktreeFailed`, `requestWorktreeCleanup`, `completeWorktreeCleanup`);
+вложенность и асинхронные обратные вызовы не поддерживаются. **Эталон реализации — `test/helpers/memory-store.lib.ts`
+в тестовом дереве пакета** (D-003): он же образец семантики для потребителей, включая копию-на-коммит в
+`inTransaction` и отказ броска как откат.
+
+## tracker
+
+Единая модель задач поверх внешних трекеров и локального хранилища. Адаптер — `TrackerAdapter` (list/get/create/
+update/comments/comment), подключаемый трекер — `TrackerDefinition` (`descriptor` для интерфейса + фабрика).
+`fetch` **приходит в контексте**, а не берётся из глобальной области: тесты подставляют свою функцию, потребитель —
+свою обёртку с прокси.
+
+```ts
+import {
+  findTracker,
+  localTracker,
+  registerBuiltinTrackers,
+  TrackerError,
+  type AdapterContext,
+  type TrackerAdapter,
+  type TrackerFetch,
+} from '@smwb/onreel-git-mcp/tracker';
+
+// Явный вызов, а не побочный эффект импорта (R-001); повтор — no-op.
+registerBuiltinTrackers();
+console.log(findTracker('github')?.descriptor.title); // 'GitHub'; реестр пуст без этого вызова
+
+const fetch: TrackerFetch = (input, init) =>
+  Promise.resolve(new Response(JSON.stringify({ number: 7, title: 'Падает сборка', state: 'open', labels: [] }), { status: 200 }));
+
+const context: AdapterContext = {
+  projectId: 'p1',
+  connection: { target: 'o/r', token: 'секрет-только-в-памяти' }, // расшифровку даёт хранилище вызывающего
+  fetch,
+  store: myLocalIssueStore, // порт LocalIssueStore — нужен только локальному трекеру
+  author: 'owner',
+};
+
+const adapter: TrackerAdapter = (findTracker('github') ?? localTracker()).create(context);
+const issue = await adapter.get('7');
+try {
+  await adapter.update('7', { status: 'in_progress' });
+} catch (error) {
+  // 'failed' | 'unknown_issue' | 'invalid_request' | 'not_found' | 'unsupported' | 'conflict' | 'rate_limited'
+  if (error instanceof TrackerError) console.log(error.failure);
+  else throw error;
+}
+```
+
+Фабрики: `localTracker()`, `sourcecraftTracker()`, `githubTracker()`, `gitlabTracker()`, `jiraTracker()`.
+Сопоставление статусов и приоритетов — открытые таблицы (`SOURCECRAFT_STATUSES`, `JIRA_PRIORITIES`,
+`GITHUB_PRIORITY_LABELS`, `GITLAB_PRIORITY_LABELS`, …), чтобы потребитель видел, во что именно преводится его
+статус. Свои трекеры добавляют в реестр явным `registerTracker(definition)`; повторный `kind` — исключение, а не
+молчаливая замена. Типы порта `LocalIssueStore` (и его строк) реэкспортированы из `…/tracker` — реализацию, как и
+для `WorktreeStore`, пишет потребитель; эталон в памяти — `test/helpers/tracker-fixtures.lib.ts`.
+
+Таймаут запроса к трекеру — `TRACKER_TIMEOUT_MS` (15 с), тело ответа ошибки обрезают до
+`TRACKER_ERROR_BODY_MAX` (300 символов) и маскируют; 404 с `missingIsIssue` — `unknown_issue`, а не «неверный
+адрес». 404 с заданным `missing` отдаёт его код и текст (`not_found`), статус из `conflictOn` — `conflict`,
+429 и 403, который выглядит лимитом частоты (`x-ratelimit-remaining: 0` или `retry-after`) — `rate_limited`
+(подробнее — в подразделе ниже).
+
+### Фильтры, сортировка и страницы
+
+`IssueQuery` — `PageQuery` плюс необязательные фильтры (D-004): `status` (категории статуса), `labels`
+(должны присутствовать все перечисленные), `assignee` (в том же виде, что в `Issue.assignee`; `null` — задачи
+без исполнителя), `author` (логин или slug трекера), `search` (как ищет сам трекер: у SourceCraft — префикс
+заголовка, у локального — подстрока заголовка и описания), `createdAfter`/`createdBefore`/`updatedAfter`/
+`updatedBefore` (мс Unix epoch, границы включительно) и `sort` — `ListSort<IssueSortField>` (`{ field, direction? }`,
+где `direction` — `SortDirection`). Без `sort` — прежний порядок трекера: GitHub, GitLab, Jira и локальный отдают
+новые первыми, SourceCraft — свои (старые первыми). Без `direction` — `desc`.
+`comments` принимает `CommentQuery`: `updatedAfter` (мс) и `order` — `SortDirection` (`asc` по умолчанию).
+Трекеры ограничивают размер страницы (GitHub и GitLab — до 100): `limit` выше потолка вернёт страницу размером
+потолка.
+
+Что умеет каждый список, описывают `IssueCapabilities` в разделе `issues` определения трекера:
+`{ list: ListCapabilities<IssueFilter, IssueSortField>, comments: CommentCapabilities }`. `ListCapabilities`
+перечисляет `filters` — фильтры, которые адаптер применяет (любой другой — отказ `unsupported` **до запроса**),
+`clientSide` — часть `filters`, которую адаптер проверяет по полученной странице: такая страница бывает короче
+`limit` и даже пустой при живом `nextCursor`, и `sorts` — поля сортировки. `CommentCapabilities` описывает
+список комментариев так же: `filters` и `clientSide` по `updatedAfter` и `order` вместо `sorts` — допустимые
+порядки, первый из них по умолчанию. Возможности статичны и сериализуются в JSON.
+У определения без раздела читаются `LEGACY_ISSUE_CAPABILITIES` — через `issueCapabilitiesOf(definition)`:
+
+| Трекер | `list.filters` | `list.clientSide` | `list.sorts` | `comments` |
+|---|---|---|---|---|
+| GitHub | все `ISSUE_FILTERS` | `status` | `created`, `updated`, `comments` | `updatedAfter`; порядок `asc` |
+| GitLab | все `ISSUE_FILTERS` | `status` | `created`, `updated`, `priority`, `title` | `updatedAfter` (на странице); `asc`, `desc` |
+| Jira | все `ISSUE_FILTERS` | — | `created`, `updated`, `priority`, `title` | как у GitLab |
+| SourceCraft | все `ISSUE_FILTERS` | `assignee` | `created`, `updated`, `priority`, `title` | как у GitLab |
+| локальный | без `author` | без `status` | — | `updatedAfter` (на странице); `asc` |
+
+У GitHub фильтры `search` и диапазоны `created*`/`updated*` идут через Search API (30 запросов/мин,
+не больше 1000 результатов). Границы времени там — квалификаторы `q` без кавычек: одна граница —
+`created:>=<ISO>` или `created:<=<ISO>`, обе границы одного поля — один диапазон `created:<ISO>..<ISO>`
+(два отдельных квалификатора GitHub объединяет через OR, и вместо фильтра он отдал бы почти всё, а кавычки
+в дате не читает вовсе — отдал бы пустой список). У SourceCraft статус уходит в QL-фильтр
+(`SOURCECRAFT_STATUS_FILTER`), но всё равно перепроверяется на странице. Правила модели, которые держат тесты:
+
+- **R1 — проверка до запроса.** Метод списка сначала зовёт `assertListQuery`/`assertCommentQuery`: фильтр
+  или сортировка вне возможностей — `TrackerError('unsupported')` без единого запроса, а неверное значение
+  (`limit` < 1, время не целое ≥ 0, пустая строка, метка с `,` там, где трекер ждёт CSV) — `invalid_request`.
+- **R2 — время.** Время в мс Unix epoch, границы включительно; наверх уходят как `isoTime(ms)` (у Jira —
+  UTC с округлением минут наружу: `after` вниз, `before` вверх).
+- **R3 — значения.** `labels` — все должны присутствовать; `assignee` — как в `Issue.assignee`, `null` —
+  без исполнителя; `author` — логин или slug трекера; `search` — как ищет сам трекер.
+- **R4 — умолчания.** Без `sort` — прежний порядок трекера: GitHub, GitLab, Jira и локальный отдают новые
+  первыми, у SourceCraft — свой порядок по умолчанию (старые первыми); без `direction` — `desc`, у комментариев
+  без `order` — `asc`.
+- **R5 — страницы.** `clientSide`-фильтр применяется к элементам каждой полученной страницы, `nextCursor` —
+  курсор трекера; страницы бывают короче `limit` и пустыми.
+- **R6 — экранирование.** Каждое значение пользователя, попадающее в JQL, QL SourceCraft или `q` поиска GitHub,
+  проходит `quoted()` (`\` и `"` экранируются); свободный текст GitHub уходит одной фразой в кавычках, так что
+  `repo:чужой/репозиторий` из ввода не добавит чужой репозиторий в выдачу. Даты `isoTime(ms)` в `q` — исключение:
+  их кладут без кавычек (значение машинное, `[0-9TZ:.-]`), иначе GitHub не найдёт ни одной задачи.
+- **R7 — прежние трекеры.** Определение без раздела `issues` читается как `LEGACY_ISSUE_CAPABILITIES`
+  через `issueCapabilitiesOf()` — свои трекеры потребителя продолжают работать без изменений.
+
+Помощники фильтров — публичные символы субпути: `usedFilters` (имена заполненных фильтров в порядке
+констант), `assertListQuery`/`assertCommentQuery` (проверка запроса по возможностям), `issueCapabilitiesOf`,
+`isoTime` (мс → ISO 8601 UTC), `inTimeRange` (включительные границы, заданная граница и неизвестное время —
+не проходит), `containsText` (подстрока без учёта регистра), `quoted` (экранирование для JQL/QL/`q`),
+`keysFor` (обратный поиск по таблице сопоставления). Имена фильтров и полей сортировки — константы
+`ISSUE_FILTERS`, `ISSUE_SORT_FIELDS`, `COMMENT_FILTERS` и выведенные из них типы `IssueFilter`,
+`IssueSortField`, `CommentFilter`. За модель отвечают запись D-004 и правило R-002.
+
+**Новые коды отказа.** `TrackerFailure` расширен четырьмя кодами; `requestJson` выставляет их по ответу,
+а потребитель сопоставляет со своим контрактом:
+
+| `TrackerFailure` | Когда возникает | Код контракта потребителя |
+|---|---|---|
+| `not_found` | 404 сущности, заданный через `missing` (PR, прогон, задание) | `not_found` |
+| `unsupported` | фильтр/сортировка вне возможностей, неподдержанная операция | `capability_unsupported` |
+| `conflict` | статус из `conflictOn` (405/409/422): переход сейчас невозможен | `lifecycle_conflict` |
+| `rate_limited` | 429, 403 с `x-ratelimit-remaining: 0` и 403 с `retry-after` (вторичные лимиты GitHub: Search API — 30 запросов/мин); задержка — из `retry-after`, иначе `x-ratelimit-reset` (GitHub), иначе `ratelimit-reset` (GitLab) | `rate_limited` |
+
+Все четыре кода уже есть в каталоге ошибок контракта (`errorCatalog`), срез контракта не меняется.
+Исчерпывающий `switch` по `TrackerFailure` у потребителя после обновления нужно дополнить.
+
+## mcp
+
+`serveMcp` — построчный JSON-RPC 2.0 на stdio, только инструменты: `initialize`, `ping`, `tools/list`,
+`tools/call` и `notifications/cancelled`. Своей таблицы команд у библиотеки нет — она приходит параметром,
+инструмент строится из строки таблицы (имя — путь через `_`, свойства — флаги без `--` плюс `request-id`).
+Конверт результата тот же, что у CLI `--json`: `{ok: true, requestId, duplicate, result}` или
+`{ok: false, requestId, error: {code, message, nextSteps}}`.
+
+```ts
+import { mcpToolSpecs, serveMcp, type CommandSpec } from '@smwb/onreel-git-mcp/mcp';
+
+const specs: readonly CommandSpec[] = [
+  {
+    path: ['orch', 'run', 'list'],
+    handler: 'verb',
+    verb: 'run.list',
+    mutation: false,
+    flags: [{ name: 'limit', parse: 'int', field: 'limit', help: 'размер страницы' }],
+    summary: 'Список Run',
+    roles: ['owner'],
+  },
+  {
+    path: ['orch', 'hello'],
+    handler: 'local',
+    flags: [{ name: 'name', parse: 'string', required: true, help: 'имя для приветствия' }],
+    summary: 'Сказать приветствие',
+    roles: ['owner'],
+  },
+];
+
+const stop = new AbortController();
+process.once('SIGINT', () => stop.abort());
+
+await serveMcp({
+  specs: mcpToolSpecs(specs), // отсекает строку самой команды `orch mcp`
+  execute: async (spec, values, globals) => ({ result: { command: spec.path.join(' '), values }, requestId: globals.requestId }),
+  globals: { json: false, help: false },
+  io: {
+    env: process.env,
+    cwd: process.cwd(),
+    stdout: (text) => process.stdout.write(text), // канал протокола: больше никаких строк
+    stderr: (text) => process.stderr.write(text),
+    signal: stop.signal, // SIGINT: начатые вызовы отменяются
+  },
+  input: process.stdin,
+  discovery: (globals, env) => globals.dataDir ?? env['ONREEL_DATA_DIR'],
+});
+```
+
+Сервер отвечает `serverInfo` с `name: 'onreel'` и версией контракта host; согласовывает любую из
+`MCP_PROTOCOL_VERSIONS` (`2025-11-25` … `2024-11-05`) и отдаёт `structuredContent` от `2025-06-18`. Прочее:
+`notifications/progress` каждые `MCP_PROGRESS_INTERVAL_MS` (15 с), если клиент прислал `progressToken`; строка
+длиннее `MCP_MAX_LINE_BYTES` (8 МиБ) отбрасывается с ошибкой парсинга; после конца stdin начатые вызовы живут
+`MCP_EOF_GRACE_MS` (5 с).
+
+**Принципал** (от чьего имени работает сервер) выбирают один раз при запуске: env агента
+(`ONREEL_HOST_URL` + `ONREEL_TOKEN`) — агент; явный `--data-dir` — владелец; иначе владелец по `host.json`,
+каталог для которого даёт `DiscoveryProvider` — библиотека не знает ни имени переменной, ни домашнего каталога CLI
+потребителя. `findAgentAncestor()` поднимается по предкам через `/proc/<pid>/environ` и `/proc/<pid>/status`:
+если сервер запущен внутри процесса агента с урезанным окружением, выбор владельца запрещён
+(`{kind: 'refused'}`), и каждый вызов вернёт `unauthorized` с объяснением. **Это Linux-специфика:** вне Linux
+`/proc` нет, цепочка обрывается, `findAgentAncestor()` возвращает `undefined` (исключения не бросается) и сервер
+при урезанном env выберет владельца. Кому это важно — передаёт `agentAncestor` сам или задаёт `principal` явно.
+
+```ts
+import { findAgentAncestor, mcpPrincipal, principalText, toolOf } from '@smwb/onreel-git-mcp/mcp';
+
+const principal = mcpPrincipal({ json: false, help: false }, process.env, findAgentAncestor(), discovery);
+console.log(principalText(principal)); // одна фраза — она попадает в instructions ответа initialize
+console.log(toolOf(specs[0]!, process.env).inputSchema); // обязательны флаги, которые нечем заполнить из env
+```
+
+## package.json
+
+Единственный не-API субпуть — манифест пакета, для инструментов, которым нужны имя и версия
+установленной копии:
+
+```ts
+import manifest from '@smwb/onreel-git-mcp/package.json' with { type: 'json' };
+
+console.log(manifest.name, manifest.version);
+```
+
+Коду вместо этого взять `VERSION` из корневого субпути: он типизирован и не требует
+`resolveJsonModule` и import attributes.
+
+## Безопасность
+
+- **Хранение токенов.** `writeTrackerToken(dataDir, projectId, token)` кладёт токены в
+  `<dataDir>/tracker-secrets.json` с правами **0600** (каталог — 0700), запись идёт через временный файл и
+  `rename`, одиночная запись сериализуется очередью, чтобы два подключения не затерли друг друга. `deleteTrackerToken`
+  и пустая строка убирают значение. Наружу из хранилища выходит только признак «токен есть» (`hasTrackerToken`),
+  а при чтении и записи значение регистрируется в приёмнике секретов.
+- **Маскирование секретов.** `redactSecretText` и `SecretSink` (по умолчанию `defaultSecretSink`) — один redactor
+  на библиотеку: его применяют `GitError` (D-272), `requestJson` (тексты отказов трекера) и внутренний отказ
+  `serveMcp`. Свой журнал потребителя подключают приёмником `SecretSink`; известные значения добавляют до
+  форматирования текста, короткая строка (менее 8 символов) не регистрируется — она дала бы слишком много ложных
+  срабатываний.
+- **Ограничение путей.** `checkRepoPath` отказывает базовому репозиторию, который абсолютным путём или по realpath
+  лежит внутри каталога данных (там ledger и токены), `prepareWorktreeParent` создаёт каталоги по одному и не
+  принимает симлинк, `checkManagedPath` перед удалением проверяет и сам каталог, и его realpath. `listWorktreeDir`
+  и `readWorktreeFile` работают только внутри realpath worktree, `.git` не показываются, симлинк за пределы —
+  `PathEscapeError` / `DirRefusal('unsafe_path')`.
+- **Канал stdout.** В `serveMcp` `io.stdout` занят протоколом: вывод обработчика команды уходит в никуда, а
+  сообщения трекеров и git в журнал идут через `io.stderr` уже замаскированными.
+- **Окружение детей.** `runGit` снимает унаследованные `GIT_*` (иначе `GIT_DIR` увёл бы host работать с чужим
+  репозиторием), ставит `GIT_TERMINAL_PROMPT=0`, `GIT_OPTIONAL_LOCKS=0` и `LC_ALL=C`, права создаваемых файлов
+  берёт из маски сессии (`ONREEL_SESSION_UMASK`).
+
+## Совместимость
+
+- Только ESM (`"type": "module"`): CJS-потребителю нужен `import()` или обёртка.
+- Node.js >= 24, Linux; macOS/Windows не тестируются (см. `/proc` и групповой `SIGKILL` выше).
+- Публикуется собранный ESM и `.d.ts` из `dist/` (D-002) — суффиксы `.ts` в импортах исходников стирает сборка,
+  их не нужно править в потребителе.
+- `sideEffects: false`, один рантайм-зависимый пакет — `zod`.
+- Реестр трекеров, пул git, замки worktree и redactor — модульная глобальна на процесс: несколько независимых
+  «хостов» в одном процессе делят их. Запросы к внешним API идут `fetch` из контекста; узлы без TLS-цепей
+  внешнего трекера — задача вызывающего.
+- Имена `ONREEL_*` и `HOST_CONTRACT_VERSION` (`1.14`) заморожены: они держат interop с onreel.
+
+## Как внести изменение
+
+1. Начните с задачи в трекере репозитория и переведите её в «в работе» (правила — в `AGENTS.md`).
+2. Реализуйте изменение; новый публичный символ или субпуть описывают здесь, в README, и добавляют
+   компилируемый пример в [`examples/`](examples).
+3. Прогоните проверки так же, как CI:
+
+   ```sh
+   npm run typecheck   # src, test и examples
+   npm run lint
+   npm test
+   npm run build
+   ```
+
+4. Изменение публичной поверхности (субпутевые экспорты, имена и сигнатуры публичных символов) требует changeset:
+   `npx changeset`, выбрать этот пакет и `minor` для обратно-совместимого дополнения. Без changeset релизный
+   workflow не выпустит версию.
+5. Откройте PR с заголовком и коммитами, начинающимися с номера задачи (`#12 …`); в `main` — только через PR
+   с зелёным CI. После мержа push в `main` запускает релизный workflow: pending-ченджсеты собираются в
+   «Version Packages» PR, а когда их нет — `changeset publish` публикует пакет и ставит теги.
+
+## Происхождение
+
+Код перенесён из onreel @ `b73407be076a5df73931d1340f70910ca13c908d` (`src/host/worktree/`,
+`src/host/tracker/`, `src/cli/mcp/`, нужная часть `src/contract/`) с заменой внутренних связок на швы ядра.
+Происхождение по файлам — в шапках исходников. Контроллеры `@smwb/srv`, CLI-обвязка и реализации хранилищ поверх
+ledger остаются в onreel: это клей хоста, а не код библиотеки.

package/dist/index.d.ts

@@ -2,5 +2,4 @@ export * from './contract/contract.const.ts';
 export * from './contract/contract.schema.ts';
 export * from './contract/contract.types.ts';
 export * from './contract/contract.lib.ts';
-/** Версия пакета; держится равной version в package.json (обновляется релизом changesets). */
-export declare const VERSION = "0.1.0";
+export declare const VERSION: string;

package/dist/index.js

@@ -56,8 +56,98 @@ import {
   worktreeStatusSchema
 } from "./chunk-4ZGRXIVA.js";
 
+// package.json
+var package_default = {
+  name: "@smwb/onreel-git-mcp",
+  version: "0.3.0",
+  description: "\u0411\u0438\u0431\u043B\u0438\u043E\u0442\u0435\u043A\u0430 \u043C\u043E\u0434\u0443\u043B\u0435\u0439, \u0432\u044B\u0434\u0435\u043B\u0435\u043D\u043D\u044B\u0445 \u0438\u0437 onreel: git-\u043E\u043F\u0435\u0440\u0430\u0446\u0438\u0438 \u0438 \u0431\u0435\u0437\u043E\u043F\u0430\u0441\u043D\u044B\u0435 \u043F\u0443\u0442\u0438, \u0441\u043F\u0438\u0441\u043E\u043A \u0444\u0430\u0439\u043B\u043E\u0432 worktree, \u0436\u0438\u0437\u043D\u0435\u043D\u043D\u044B\u0439 \u0446\u0438\u043A\u043B worktree \u043F\u0440\u043E\u0442\u0438\u0432 \u043F\u043E\u0440\u0442\u0430 WorktreeStore, \u0430\u0434\u0430\u043F\u0442\u0435\u0440\u044B \u0442\u0440\u0435\u043A\u0435\u0440\u043E\u0432 GitHub/GitLab/Jira/SourceCraft/\u043B\u043E\u043A\u0430\u043B\u044C\u043D\u043E\u0433\u043E \u0438 MCP-\u0441\u0435\u0440\u0432\u0435\u0440 \u043D\u0430 stdio",
+  keywords: [
+    "git",
+    "worktree",
+    "mcp",
+    "issue-tracker",
+    "github",
+    "gitlab",
+    "jira",
+    "sourcecraft",
+    "onreel",
+    "typescript"
+  ],
+  type: "module",
+  engines: {
+    node: ">=24"
+  },
+  files: [
+    "dist"
+  ],
+  sideEffects: false,
+  publishConfig: {
+    access: "public",
+    registry: "https://registry.npmjs.org/"
+  },
+  repository: {
+    type: "git",
+    url: "git+https://git.sourcecraft.dev/elfenmail/onreel-git-mcp.git"
+  },
+  homepage: "https://git.sourcecraft.dev/elfenmail/onreel-git-mcp",
+  license: "MIT",
+  exports: {
+    ".": {
+      types: "./dist/index.d.ts",
+      import: "./dist/index.js",
+      default: "./dist/index.js"
+    },
+    "./git": {
+      types: "./dist/git/index.d.ts",
+      import: "./dist/git/index.js",
+      default: "./dist/git/index.js"
+    },
+    "./files": {
+      types: "./dist/files/index.d.ts",
+      import: "./dist/files/index.js",
+      default: "./dist/files/index.js"
+    },
+    "./worktree": {
+      types: "./dist/worktree/index.d.ts",
+      import: "./dist/worktree/index.js",
+      default: "./dist/worktree/index.js"
+    },
+    "./tracker": {
+      types: "./dist/tracker/index.d.ts",
+      import: "./dist/tracker/index.js",
+      default: "./dist/tracker/index.js"
+    },
+    "./mcp": {
+      types: "./dist/mcp/index.d.ts",
+      import: "./dist/mcp/index.js",
+      default: "./dist/mcp/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  scripts: {
+    build: "tsup && tsc -p tsconfig.build.json",
+    typecheck: "tsc -p tsconfig.json && tsc -p tsconfig.examples.json",
+    lint: "oxlint --type-aware",
+    test: 'node --test "test/**/*.test.ts"',
+    changeset: "changeset",
+    version: "changeset version",
+    release: "npm run build && changeset publish"
+  },
+  dependencies: {
+    zod: "^4.6.5"
+  },
+  devDependencies: {
+    "@changesets/cli": "2.29.2",
+    "@types/node": "24.19.1",
+    oxlint: "1.87.0",
+    "oxlint-tsgolint": "7.0.2003",
+    tsup: "8.5.1",
+    typescript: "7.0.2"
+  }
+};
+
 // src/index.ts
-var VERSION = "0.1.0";
+var VERSION = package_default.version;
 export {
   CONTRACT_ERROR_MESSAGE_MAX,
   CONTRACT_ERROR_NEXT_STEP_MAX,

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/index.ts"],"sourcesContent":["// Корневой подпуть пакета @smwb/onreel-git-mcp: срез контракта (константы, схемы, типы, чистые\n// функции) и версия пакета. Всё без побочных эффектов при импорте (R-001). Швы ядра\n// (SecretSink, WorktreeStore, LocalIssueStore) и модули git/files/worktree/tracker/mcp\n// экспортируют свои подпути — см. exports в package.json и README.\nexport * from './contract/contract.const.ts';\nexport * from './contract/contract.schema.ts';\nexport * from './contract/contract.types.ts';\nexport * from './contract/contract.lib.ts';\n\n/** Версия пакета; держится равной version в package.json (обновляется релизом changesets). */\nexport const VERSION = '0.1.0';\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAUO,IAAM,UAAU;","names":[]}
+{"version":3,"sources":["../package.json","../src/index.ts"],"sourcesContent":["{\n  \"name\": \"@smwb/onreel-git-mcp\",\n  \"version\": \"0.3.0\",\n  \"description\": \"Библиотека модулей, выделенных из onreel: git-операции и безопасные пути, список файлов worktree, жизненный цикл worktree против порта WorktreeStore, адаптеры трекеров GitHub/GitLab/Jira/SourceCraft/локального и MCP-сервер на stdio\",\n  \"keywords\": [\n    \"git\",\n    \"worktree\",\n    \"mcp\",\n    \"issue-tracker\",\n    \"github\",\n    \"gitlab\",\n    \"jira\",\n    \"sourcecraft\",\n    \"onreel\",\n    \"typescript\"\n  ],\n  \"type\": \"module\",\n  \"engines\": {\n    \"node\": \">=24\"\n  },\n  \"files\": [\n    \"dist\"\n  ],\n  \"sideEffects\": false,\n  \"publishConfig\": {\n    \"access\": \"public\",\n    \"registry\": \"https://registry.npmjs.org/\"\n  },\n  \"repository\": {\n    \"type\": \"git\",\n    \"url\": \"git+https://git.sourcecraft.dev/elfenmail/onreel-git-mcp.git\"\n  },\n  \"homepage\": \"https://git.sourcecraft.dev/elfenmail/onreel-git-mcp\",\n  \"license\": \"MIT\",\n  \"exports\": {\n    \".\": {\n      \"types\": \"./dist/index.d.ts\",\n      \"import\": \"./dist/index.js\",\n      \"default\": \"./dist/index.js\"\n    },\n    \"./git\": {\n      \"types\": \"./dist/git/index.d.ts\",\n      \"import\": \"./dist/git/index.js\",\n      \"default\": \"./dist/git/index.js\"\n    },\n    \"./files\": {\n      \"types\": \"./dist/files/index.d.ts\",\n      \"import\": \"./dist/files/index.js\",\n      \"default\": \"./dist/files/index.js\"\n    },\n    \"./worktree\": {\n      \"types\": \"./dist/worktree/index.d.ts\",\n      \"import\": \"./dist/worktree/index.js\",\n      \"default\": \"./dist/worktree/index.js\"\n    },\n    \"./tracker\": {\n      \"types\": \"./dist/tracker/index.d.ts\",\n      \"import\": \"./dist/tracker/index.js\",\n      \"default\": \"./dist/tracker/index.js\"\n    },\n    \"./mcp\": {\n      \"types\": \"./dist/mcp/index.d.ts\",\n      \"import\": \"./dist/mcp/index.js\",\n      \"default\": \"./dist/mcp/index.js\"\n    },\n    \"./package.json\": \"./package.json\"\n  },\n  \"scripts\": {\n    \"build\": \"tsup && tsc -p tsconfig.build.json\",\n    \"typecheck\": \"tsc -p tsconfig.json && tsc -p tsconfig.examples.json\",\n    \"lint\": \"oxlint --type-aware\",\n    \"test\": \"node --test \\\"test/**/*.test.ts\\\"\",\n    \"changeset\": \"changeset\",\n    \"version\": \"changeset version\",\n    \"release\": \"npm run build && changeset publish\"\n  },\n  \"dependencies\": {\n    \"zod\": \"^4.6.5\"\n  },\n  \"devDependencies\": {\n    \"@changesets/cli\": \"2.29.2\",\n    \"@types/node\": \"24.19.1\",\n    \"oxlint\": \"1.87.0\",\n    \"oxlint-tsgolint\": \"7.0.2003\",\n    \"tsup\": \"8.5.1\",\n    \"typescript\": \"7.0.2\"\n  }\n}\n","// Корневой подпуть пакета @smwb/onreel-git-mcp: срез контракта (константы, схемы, типы, чистые\n// функции) и версия пакета. Всё без побочных эффектов при импорте (R-001). Швы ядра\n// (SecretSink, WorktreeStore, LocalIssueStore) и модули git/files/worktree/tracker/mcp\n// экспортируют свои подпути — см. exports в package.json и README.\nimport pkg from '../package.json' with { type: 'json' };\n\nexport * from './contract/contract.const.ts';\nexport * from './contract/contract.schema.ts';\nexport * from './contract/contract.types.ts';\nexport * from './contract/contract.lib.ts';\n\n// Версия пакета — из version в package.json: статический импорт JSON, его значение tsup подставляет\n// в бандл на сборке, поэтому VERSION не расходится с релизом changesets (тот правит только version).\nexport const VERSION: string = pkg.version;\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA;AAAA,EACE,MAAQ;AAAA,EACR,SAAW;AAAA,EACX,aAAe;AAAA,EACf,UAAY;AAAA,IACV;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,EACF;AAAA,EACA,MAAQ;AAAA,EACR,SAAW;AAAA,IACT,MAAQ;AAAA,EACV;AAAA,EACA,OAAS;AAAA,IACP;AAAA,EACF;AAAA,EACA,aAAe;AAAA,EACf,eAAiB;AAAA,IACf,QAAU;AAAA,IACV,UAAY;AAAA,EACd;AAAA,EACA,YAAc;AAAA,IACZ,MAAQ;AAAA,IACR,KAAO;AAAA,EACT;AAAA,EACA,UAAY;AAAA,EACZ,SAAW;AAAA,EACX,SAAW;AAAA,IACT,KAAK;AAAA,MACH,OAAS;AAAA,MACT,QAAU;AAAA,MACV,SAAW;AAAA,IACb;AAAA,IACA,SAAS;AAAA,MACP,OAAS;AAAA,MACT,QAAU;AAAA,MACV,SAAW;AAAA,IACb;AAAA,IACA,WAAW;AAAA,MACT,OAAS;AAAA,MACT,QAAU;AAAA,MACV,SAAW;AAAA,IACb;AAAA,IACA,cAAc;AAAA,MACZ,OAAS;AAAA,MACT,QAAU;AAAA,MACV,SAAW;AAAA,IACb;AAAA,IACA,aAAa;AAAA,MACX,OAAS;AAAA,MACT,QAAU;AAAA,MACV,SAAW;AAAA,IACb;AAAA,IACA,SAAS;AAAA,MACP,OAAS;AAAA,MACT,QAAU;AAAA,MACV,SAAW;AAAA,IACb;AAAA,IACA,kBAAkB;AAAA,EACpB;AAAA,EACA,SAAW;AAAA,IACT,OAAS;AAAA,IACT,WAAa;AAAA,IACb,MAAQ;AAAA,IACR,MAAQ;AAAA,IACR,WAAa;AAAA,IACb,SAAW;AAAA,IACX,SAAW;AAAA,EACb;AAAA,EACA,cAAgB;AAAA,IACd,KAAO;AAAA,EACT;AAAA,EACA,iBAAmB;AAAA,IACjB,mBAAmB;AAAA,IACnB,eAAe;AAAA,IACf,QAAU;AAAA,IACV,mBAAmB;AAAA,IACnB,MAAQ;AAAA,IACR,YAAc;AAAA,EAChB;AACF;;;AC1EO,IAAM,UAAkB,gBAAI;","names":[]}