@smwb/onreel-git-mcp 0.1.0 → 0.2.1

package/README.md

@@ -0,0 +1,408 @@
+# @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) {
+  if (error instanceof TrackerError) console.log(error.failure); // 'failed' | 'unknown_issue' | 'invalid_request'
+  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`, а не «неверный адрес».
+
+## 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/chunk-3YP22YLA.js

@@ -0,0 +1,50 @@
+import {
+  CONTRACT_ERROR_MESSAGE_MAX,
+  CONTRACT_ERROR_NEXT_STEP_MAX,
+  DEFAULT_SESSION_UMASK,
+  ENV_SESSION_UMASK,
+  contractErrorSchema
+} from "./chunk-4ZGRXIVA.js";
+
+// src/contract/contract.lib.ts
+function clip(text, max) {
+  return text.length <= max ? text : `${text.slice(0, max - 1)}\u2026`;
+}
+function contractError(code, message, nextSteps, data) {
+  const error = {
+    code,
+    message: clip(message, CONTRACT_ERROR_MESSAGE_MAX),
+    nextSteps: nextSteps.map((step) => clip(step, CONTRACT_ERROR_NEXT_STEP_MAX)),
+    ...data === void 0 ? {} : { data }
+  };
+  return contractErrorSchema.parse(error);
+}
+function formatVersion(version) {
+  return `${version.major}.${version.minor}`;
+}
+function parseUmask(value) {
+  if (value === void 0 || !/^[0-7]{1,4}$/.test(value)) return void 0;
+  const mask = parseInt(value, 8);
+  return mask <= 511 ? mask : void 0;
+}
+function formatUmask(mask) {
+  return mask.toString(8).padStart(4, "0");
+}
+function sessionUmask(env) {
+  return parseUmask(env[ENV_SESSION_UMASK]) ?? DEFAULT_SESSION_UMASK;
+}
+function inheritSessionUmask(env, current) {
+  if (parseUmask(env[ENV_SESSION_UMASK]) === void 0) env[ENV_SESSION_UMASK] = formatUmask(current);
+  return sessionUmask(env);
+}
+
+export {
+  clip,
+  contractError,
+  formatVersion,
+  parseUmask,
+  formatUmask,
+  sessionUmask,
+  inheritSessionUmask
+};
+//# sourceMappingURL=chunk-3YP22YLA.js.map

package/dist/chunk-3YP22YLA.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/contract/contract.lib.ts"],"sourcesContent":["// Функции среза контракта onreel для библиотеки @smwb/onreel-git-mcp (заморожены в части B\n// выделения). Происхождение — onreel @ b73407be076a5df73931d1340f70910ca13c908d, дословные копии:\n//   src/contract/errors.lib.ts — clip, contractError;\n//   src/contract/umask.lib.ts — parseUmask, formatUmask, sessionUmask, inheritSessionUmask\n//     (чистые функции: без process и встроенных модулей Node);\n//   src/contract/version/version.lib.ts — formatVersion.\nimport { CONTRACT_ERROR_MESSAGE_MAX, CONTRACT_ERROR_NEXT_STEP_MAX, DEFAULT_SESSION_UMASK, ENV_SESSION_UMASK, type ErrorCode } from './contract.const.ts';\nimport { contractErrorSchema } from './contract.schema.ts';\nimport type { ContractError, ContractVersion } from './contract.types.ts';\n\n/** Обрезает строку до `max` символов с многоточием: в ошибку попадает и чужой ввод неизвестной длины. */\nexport function clip(text: string, max: number): string {\n  return text.length <= max ? text : `${text.slice(0, max - 1)}…`;\n}\n\n/**\n * Собирает ошибку и проверяет её схемой: длинные `message` и шаги обрезаются, а пустой шаг —\n * ошибка программиста, и функция бросает исключение, а не отдаёт клиенту ответ, который он не разберёт.\n */\nexport function contractError(\n  code: ErrorCode,\n  message: string,\n  nextSteps: [string, ...string[]],\n  data?: Record<string, unknown>,\n): ContractError {\n  const error = {\n    code,\n    message: clip(message, CONTRACT_ERROR_MESSAGE_MAX),\n    nextSteps: nextSteps.map((step) => clip(step, CONTRACT_ERROR_NEXT_STEP_MAX)),\n    ...(data === undefined ? {} : { data }),\n  };\n  return contractErrorSchema.parse(error);\n}\n\nexport function formatVersion(version: ContractVersion): string {\n  return `${version.major}.${version.minor}`;\n}\n\n// --- Маска пользовательских сессий (onreel D-330) ---\n// Чистые функции маски сессий: без process и встроенных модулей Node, потому что contract\n// импортирует и UI. Сам process.umask читают и меняют вызывающие (kernel/umask.lib.ts).\n\n/** Разбирает восьмеричную маску без префикса: 1-4 цифры 0-7, не больше 0o777; иначе undefined. Пробелы не срезаются. */\nexport function parseUmask(value: string | undefined): number | undefined {\n  if (value === undefined || !/^[0-7]{1,4}$/.test(value)) return undefined;\n  const mask = parseInt(value, 8);\n  return mask <= 0o777 ? mask : undefined;\n}\n\n/** Маска как четыре восьмеричные цифры: 0o22 -> «0022». */\nexport function formatUmask(mask: number): string {\n  return mask.toString(8).padStart(4, '0');\n}\n\n/** Маска сессий из env; нет переменной или она неверна — DEFAULT_SESSION_UMASK. */\nexport function sessionUmask(env: Readonly<Record<string, string | undefined>>): number {\n  return parseUmask(env[ENV_SESSION_UMASK]) ?? DEFAULT_SESSION_UMASK;\n}\n\n/**\n * Записывает current в env, если там нет верной маски, и возвращает маску сессий.\n * Верное значение, уже стоящее в env, не перезаписывается: его задал более ранний процесс цепочки\n * (CLI, Electron, systemd), а значение неверное считается незаданным.\n */\nexport function inheritSessionUmask(env: Record<string, string | undefined>, current: number): number {\n  if (parseUmask(env[ENV_SESSION_UMASK]) === undefined) env[ENV_SESSION_UMASK] = formatUmask(current);\n  return sessionUmask(env);\n}\n"],"mappings":";;;;;;;;;AAWO,SAAS,KAAK,MAAc,KAAqB;AACtD,SAAO,KAAK,UAAU,MAAM,OAAO,GAAG,KAAK,MAAM,GAAG,MAAM,CAAC,CAAC;AAC9D;AAMO,SAAS,cACd,MACA,SACA,WACA,MACe;AACf,QAAM,QAAQ;AAAA,IACZ;AAAA,IACA,SAAS,KAAK,SAAS,0BAA0B;AAAA,IACjD,WAAW,UAAU,IAAI,CAAC,SAAS,KAAK,MAAM,4BAA4B,CAAC;AAAA,IAC3E,GAAI,SAAS,SAAY,CAAC,IAAI,EAAE,KAAK;AAAA,EACvC;AACA,SAAO,oBAAoB,MAAM,KAAK;AACxC;AAEO,SAAS,cAAc,SAAkC;AAC9D,SAAO,GAAG,QAAQ,KAAK,IAAI,QAAQ,KAAK;AAC1C;AAOO,SAAS,WAAW,OAA+C;AACxE,MAAI,UAAU,UAAa,CAAC,eAAe,KAAK,KAAK,EAAG,QAAO;AAC/D,QAAM,OAAO,SAAS,OAAO,CAAC;AAC9B,SAAO,QAAQ,MAAQ,OAAO;AAChC;AAGO,SAAS,YAAY,MAAsB;AAChD,SAAO,KAAK,SAAS,CAAC,EAAE,SAAS,GAAG,GAAG;AACzC;AAGO,SAAS,aAAa,KAA2D;AACtF,SAAO,WAAW,IAAI,iBAAiB,CAAC,KAAK;AAC/C;AAOO,SAAS,oBAAoB,KAAyC,SAAyB;AACpG,MAAI,WAAW,IAAI,iBAAiB,CAAC,MAAM,OAAW,KAAI,iBAAiB,IAAI,YAAY,OAAO;AAClG,SAAO,aAAa,GAAG;AACzB;","names":[]}