@nitra/cursor 3.22.0 → 3.23.1

package/scripts/dispatcher/lib/docs/snapshot.md

@@ -0,0 +1,247 @@
+# snapshot.mjs
+
+## Огляд
+
+Модуль `snapshot.mjs` — частина шару `lib/` диспетчера flow-задач (`npm/scripts/dispatcher/lib/`). Його єдине призначення — створення та збереження **completion snapshot** (підсумкового слугу про виконання задачі) у durable-сховище, ще до того, як буде видалено transient-файл `.flow.json`.
+
+Контекст і причина існування модуля (зі специфікації §3 Ф5, §7):
+
+- Стан виконання flow-задачі тимчасово живе у файлі `.flow.json` всередині гілки/робочої теки.
+- На етапі завершення (cleanup) цей transient-стан видаляється.
+- Але потрібно, щоб **слід** про виконану задачу пережив cleanup: для аудиту, історії, ретроспективи.
+- Тому перед видаленням ми будуємо стислий JSON-snapshot і вписуємо його в **task record** — markdown-файл `docs/tasks/<id>.md` між двома HTML-маркерами. Запис **ідемпотентний**: повторний прогін перезаписує блок Summary, а не дублює його.
+
+Модуль експонує три pure/IO-функції з чітко розділеними рівнями (чиста трансформація → чистий upsert у тексті → IO у файлову систему), що робить логіку легко тестованою без mock-ів FS на більшості шляхів.
+
+## Експорти / API
+
+Модуль експортує три іменовані функції (`export function ...`):
+
+| Експорт                                        | Тип          | Призначення                                                                                  |
+| ---------------------------------------------- | ------------ | -------------------------------------------------------------------------------------------- |
+| `buildCompletionSnapshot(state, now?)`         | pure-функція | Складає JSON-об'єкт snapshot зі стану `.flow.json`.                                          |
+| `upsertSummaryBlock(content, snapshot)`        | pure-функція | Вставляє або оновлює блок Summary у наданому markdown-тексті між маркерами.                  |
+| `writeSummaryToTaskRecord(taskPath, snapshot)` | IO-функція   | Читає файл task record (якщо існує), застосовує `upsertSummaryBlock` і пише результат назад. |
+
+Внутрішні (не експортовані) константи:
+
+- `SUMMARY_START = '<!-- flow:summary:start -->'` — відкриваючий HTML-коментар-маркер.
+- `SUMMARY_END = '<!-- flow:summary:end -->'` — закриваючий HTML-коментар-маркер.
+
+Ці маркери — публічний контракт формату task record: будь-який інший інструмент може шукати ці ж літерали, щоб витягнути або переписати блок.
+
+## Функції
+
+### `buildCompletionSnapshot(state, now = Date.now)`
+
+**Сигнатура:**
+
+```js
+buildCompletionSnapshot(state: object, now?: () => number): object
+```
+
+**Параметри:**
+
+- `state` — об'єкт стану задачі (типово розпарсений `.flow.json`). Очікувані поля (всі опційні, мають дефолти):
+  - `state.status` — рядковий статус, дефолт `'done'`.
+  - `state.branch` — назва гілки, дефолт `null`.
+  - `state.metadata?.base_commit` — base commit гілки; якщо відсутній, fallback `state.base_commit`; дефолт `null`.
+  - `state.gates` — масив об'єктів `{ name, ok }`; кожен gate перетворюється у пару `[name, ok ? 'ok' : 'fail']`.
+  - `state.change` — інформація про change-файл (n-changelog), дефолт `null`.
+  - `state.notified` — статус нотифікації, дефолт `null`.
+- `now` — фабрика часу: функція, що повертає мілісекунди (`number`). За замовчуванням — `Date.now`. Передається явно, щоб **тести могли інжектувати детерміністичний час**.
+
+**Повертає:**
+
+Об'єкт `snapshot` із полями:
+
+```text
+{
+  status:       string,   // state.status ?? 'done'
+  branch:       string|null,
+  base_commit:  string|null,
+  gates:        Record<string,'ok'|'fail'>, // плоска мапа name → status
+  change:       any|null,
+  notified:     any|null,
+  finished_at:  string    // ISO-8601, отриманий через new Date(now()).toISOString()
+}
+```
+
+**Side effects:** жодних. Це чиста функція (за умови чистоти переданої `now`).
+
+**Особливості реалізації:**
+
+- Поле `base_commit` має **двоступеневий fallback**: спочатку `state.metadata?.base_commit`, потім `state.base_commit`. Це покриває обидва формати state, що зустрічаються в практиці.
+- `gates` нормалізуються до **рядкового** статусу `'ok'`/`'fail'` (а не булевого `ok`), щоб JSON у markdown був самодокументованим і людиночитним.
+- `finished_at` обчислюється з результату виклику `now()`, тому час фіксується саме в момент побудови snapshot.
+- Якщо `state.gates` відсутній — використовується порожній масив, і поле `gates` буде `{}`.
+
+### `upsertSummaryBlock(content, snapshot)`
+
+**Сигнатура:**
+
+```js
+upsertSummaryBlock(content: string, snapshot: object): string
+```
+
+**Параметри:**
+
+- `content` — вихідний markdown-текст task record (може бути порожнім рядком).
+- `snapshot` — об'єкт, що буде серіалізований у JSON (через `JSON.stringify(..., null, 2)`) усередину блоку.
+
+**Повертає:** новий markdown-рядок зі вставленим або оновленим блоком Summary.
+
+**Side effects:** жодних, чиста рядкова трансформація.
+
+**Структура блоку, який будує функція:**
+
+````text
+<!-- flow:summary:start -->
+## Summary
+```json
+{ ... pretty-printed snapshot ... }
+````
+
+<!-- flow:summary:end -->
+
+````
+
+(У реальному виводі трійні бектики справжні; тут показано схематично, бо ми всередині markdown.)
+
+**Алгоритм (idempotent upsert):**
+
+1. Сформувати рядок `block` із маркерів, заголовка `## Summary`, fenced JSON-блоку та закриваючого маркера.
+2. Знайти індекси `i = content.indexOf(SUMMARY_START)` та `j = content.indexOf(SUMMARY_END)`.
+3. Якщо обидва маркери знайдено і `j > i` — **замінити** діапазон `[i, j + len(SUMMARY_END))` на `block`. Це гарантує, що повторний виклик не дублює блок і не залишає старого вмісту.
+4. Інакше (маркерів немає, або вони у неправильному порядку) — **дописати** блок у кінець: `content.trimEnd() + '\n\n' + block + '\n'`. `trimEnd()` прибирає лишні хвостові переноси, потім додається порожній рядок-розділювач.
+
+**Кейси (контракт):**
+
+| Вхідний `content` | Поведінка |
+|---|---|
+| Порожній рядок `''` | Дописує `\n\n<block>\n` (фактично починається з `\n\n` через `trimEnd('')`). |
+| Markdown без маркерів | Дописує блок у кінець із розділювачем. |
+| Markdown із валідною парою маркерів | Замінює вміст між ними (включно з самими маркерами) на свіжий блок. |
+| Markdown із поодиноким `SUMMARY_START` без `SUMMARY_END` | Йде у гілку append (дописати в кінець). |
+| Markdown із `SUMMARY_END` перед `SUMMARY_START` (`j <= i`) | Теж йде в append. |
+
+### `writeSummaryToTaskRecord(taskPath, snapshot)`
+
+**Сигнатура:**
+
+```js
+writeSummaryToTaskRecord(taskPath: string, snapshot: object): void
+````
+
+**Параметри:**
+
+- `taskPath` — **абсолютний** шлях до task record-файла (типово `<repo>/docs/tasks/<id>.md`).
+- `snapshot` — об'єкт snapshot (зазвичай результат `buildCompletionSnapshot`).
+
+**Повертає:** `void`.
+
+**Side effects:**
+
+- Кидає `Error`, якщо `taskPath` **не** абсолютний (`isAbsolute(taskPath) === false`). Текст помилки: `writeSummaryToTaskRecord: очікується абсолютний шлях (отримано: <taskPath>)`.
+- Якщо файл існує — читає його синхронно (`readFileSync(taskPath, 'utf8')`).
+- Якщо файл не існує — використовує порожній рядок як base.
+- Записує результат `upsertSummaryBlock(...)` у `taskPath` синхронно (`writeFileSync(..., 'utf8')`). Файл буде створено, якщо його не було.
+
+**Особливості:**
+
+- Усі IO — **синхронні**. Це свідомий вибір: функція викликається на cleanup-етапі диспетчера, де простота й детерміністичність важливіші за throughput.
+- Не створює проміжних каталогів. Очікується, що `docs/tasks/` уже існує (інакше `writeFileSync` кине `ENOENT`).
+- Не виконує бекапу: попередній блок Summary перезаписується новим (про що дбає `upsertSummaryBlock`).
+
+## Залежності
+
+**Зовнішні (Node.js core, через `node:` префікс):**
+
+- `node:fs` — `existsSync`, `readFileSync`, `writeFileSync` (синхронний IO).
+- `node:path` — `isAbsolute` (валідація вхідного шляху).
+
+**Внутрішніх залежностей** (на інші модулі диспетчера) — **немає**. Модуль самодостатній і не імпортує нічого з `lib/` чи проєкту.
+
+**Зовнішні npm-пакети:** відсутні.
+
+**Тип/середовище:** ESM (`.mjs`, `import`-синтаксис), запускається у Node.js / Bun.
+
+## Потік виконання / Використання
+
+### Сценарій 1: завершення flow-задачі (основний use case)
+
+Псевдокод callsite (типового місця виклику в диспетчері):
+
+```js
+import { readFileSync, existsSync } from 'node:fs'
+import { join } from 'node:path'
+import { buildCompletionSnapshot, writeSummaryToTaskRecord } from './lib/snapshot.mjs'
+
+// 1. Зчитати transient-стан.
+const state = JSON.parse(readFileSync('.flow.json', 'utf8'))
+
+// 2. Побудувати completion snapshot.
+const snapshot = buildCompletionSnapshot(state)
+
+// 3. Уписати його в durable task record.
+const taskPath = join(repoRoot, 'docs', 'tasks', `${state.id}.md`)
+writeSummaryToTaskRecord(taskPath, snapshot)
+
+// 4. Тепер безпечно видаляти `.flow.json` (cleanup).
+```
+
+### Сценарій 2: тестування (інжекція часу)
+
+`buildCompletionSnapshot` приймає `now` як параметр, тож тест може зафіксувати `finished_at`:
+
+```js
+const fixedNow = () => 1_700_000_000_000
+const snap = buildCompletionSnapshot(state, fixedNow)
+// snap.finished_at === '2023-11-14T22:13:20.000Z'
+```
+
+### Сценарій 3: ідемпотентний повторний запис
+
+Виклик `writeSummaryToTaskRecord` на тому ж шляху з тим самим snapshot **не** змінює файл змістовно (тільки переписує блок Summary тим самим вмістом). На різних snapshot — оновлює блок без дублювання та без впливу на решту markdown поза маркерами.
+
+### Потік даних
+
+```
+.flow.json (transient)
+       │
+       ▼  JSON.parse
+   state object
+       │
+       ▼  buildCompletionSnapshot(state, now)
+   snapshot object  ─────────────┐
+                                 ▼  upsertSummaryBlock(content, snapshot)
+docs/tasks/<id>.md (existing) ───┤
+       │                         ▼
+       │                  updated markdown
+       │                         │
+       └─◀────── writeFileSync ──┘
+```
+
+### Інваріанти
+
+- `finished_at` завжди є валідним ISO-8601 рядком.
+- `gates` завжди є об'єктом (нехай і порожнім), ніколи не `undefined`.
+- Файл task record після виклику завжди містить рівно один блок Summary між маркерами.
+- HTML-маркери залишаються в markdown навмисно: вони не рендеряться у GitHub/MD-рендерерах, але слугують machine-readable якорями для idempotent upsert.
+
+## Rebuild Test
+
+Mental-rebuild перевірка (чи документація достатня для відтворення модуля з нуля без перегляду коду):
+
+1. **Призначення зрозуміле?** Так — будувати completion snapshot і вписувати його між HTML-маркерами в `docs/tasks/<id>.md` перед cleanup `.flow.json`.
+2. **Експорти й сигнатури повні?** Так — три функції з типами параметрів, дефолтами, типами повернення.
+3. **Формат snapshot задокументовано?** Так — перелік полів, дефолти, fallback-логіка для `base_commit`, нормалізація `gates` до `'ok'`/`'fail'`.
+4. **Формат блоку в markdown задокументовано?** Так — маркери, `## Summary`, fenced JSON-блок, pretty-print 2 пробіли.
+5. **Алгоритм upsert описаний?** Так — пошук маркерів, заміна діапазону при валідній парі, інакше append із `trimEnd` + `\n\n`.
+6. **Обробка помилок описана?** Так — `Error` на не-абсолютний шлях, відсутність файлу = порожній base.
+7. **Залежності перелічено?** Так — `node:fs` (3 функції), `node:path` (`isAbsolute`).
+8. **Side effects явні?** Так — синхронний IO лише в `writeSummaryToTaskRecord`; решта pure.
+9. **Інваріанти й кейси edge?** Так — порожній content, поодинокий маркер, зворотний порядок маркерів, повторний запис.
+10. **Інжекція часу для тестів?** Так — параметр `now`.
+
+Рекомпіляція з документації → ідентичний за поведінкою модуль: можлива.

package/scripts/dispatcher/lib/docs/spec.md

@@ -0,0 +1,203 @@
+# spec.mjs
+
+## Огляд
+
+Модуль реалізує CLI-підкоманду `flow spec [--panel] [<spec.md>]` — фазу дизайну в lifecycle Пасивного Турнікета (§3 правила `flow.mdc`). Її призначення — зафіксувати у файлі стану воркфлоу (`flow-state`) шлях до spec-документа (`docs/specs/<date>-<slug>.md`), отриманого внаслідок brainstorm-сесії, та виконати read-only верифікацію ланцюга трасування (`trace`) між артефактами ADR → spec → plan.
+
+Ключові властивості:
+
+- **Код не пишеться:** модуль лише оновлює state-store та логує події, лінки front-matter (`adr/spec/plan`) у самому документі формує агент за контрактом `flow.mdc`.
+- **Brainstorm two-track:** human↔agent відбувається у звичайному IDE-діалозі; agent↔agent — через прапор `--panel`, який запускає синтез персон та суддю через `runPanel`.
+- **Risk-driven review:** значення `risk` із front-matter spec-документа (`low | med | high`) перетікає у стан, керуючи глибиною подальшої фази `flow review`.
+- **Worktree-aware:** якщо `cwd` поза worktree, активний flow автоматично резолвиться через `resolveActiveFlowState`.
+
+Модуль є чистою функцією верхнього рівня з контрольованими ін'єкціями залежностей (`deps`), що робить його придатним для unit-тестування без файлової системи реального проєкту.
+
+## Експорти / API
+
+| Експорт             | Тип              | Призначення                                                                              |
+| ------------------- | ---------------- | ---------------------------------------------------------------------------------------- |
+| `spec(rest, deps?)` | `async function` | Точка входу CLI-підкоманди `flow spec`. Повертає exit code (`0` — успіх, `1` — помилка). |
+
+Внутрішні (не експортуються):
+
+| Ідентифікатор                | Тип           | Призначення                                                               |
+| ---------------------------- | ------------- | ------------------------------------------------------------------------- |
+| `RISKS`                      | `Set<string>` | Допустимі рівні ризику: `low`, `med`, `high`.                             |
+| `riskFromSpec(doc, current)` | `function`    | Зчитує валідний `risk` зі spec-frontmatter або повертає поточний у стані. |
+
+## Функції
+
+### `RISKS`
+
+```text
+const RISKS = new Set(['low', 'med', 'high'])
+```
+
+Замкнений перелік допустимих значень поля `risk` у front-matter spec-документа. Будь-яке інше значення (включно з `undefined`, опискою, або відсутністю фронт-матеру) ігнорується — у такому разі ризик у стані не змінюється.
+
+### `riskFromSpec(doc, current)`
+
+**Сигнатура:**
+
+```js
+function riskFromSpec(doc: string, current: string | undefined): string | undefined
+```
+
+**Параметри:**
+
+- `doc` (`string`) — абсолютний або відносний шлях до spec-документа (`*.md`).
+- `current` (`string | undefined`) — поточне значення `risk` із state-store; використовується як fallback, коли в документі не вказано валідного ризику.
+
+**Повертає:** `string | undefined` — рівень ризику (`low`, `med`, `high`) або поточне значення.
+
+**Семантика:**
+
+1. Зчитує вміст файлу `doc` як UTF-8 рядок.
+2. Парсить front-matter через `parseFrontMatter`.
+3. Якщо у фронт-матері є поле `risk` і воно є членом `RISKS` — повертає його.
+4. Інакше повертає `current` (без модифікації).
+
+**Side effects:**
+
+- Виконує синхронний read файлової системи (`readFileSync`).
+- Будь-який виняток (відсутній файл, помилка парсингу, прав доступу) поглинається `try/catch` і функція повертає `current` — це гарантує, що відсутність front-matter не блокує транзицію стану.
+
+### `spec(rest, deps)`
+
+**Сигнатура:**
+
+```js
+async function spec(
+  rest: string[],
+  deps?: {
+    cwd?: string,
+    branch?: string,
+    log?: (m: string) => void,
+    runner?: object,
+    trace?: (cwd: string) => number,
+    now?: () => number
+  }
+): Promise<number>
+```
+
+**Параметри:**
+
+- `rest` (`string[]`) — позиційні аргументи CLI після підкоманди `spec`. Розпізнаються:
+  - `--panel` — флаг увімкнення agent-panel brainstorm.
+  - Будь-який аргумент, що закінчується на `.md` — явний шлях до spec-документа (інакше використовується `resolveArtifact`).
+- `deps` (`object`, опційно) — ін'єкції для тестування та advanced use cases:
+  - `cwd` — стартовий робочий каталог (default: `process.cwd()`).
+  - `branch` — гілка для резолву активного flow (передається у `resolveActiveFlowState`).
+  - `log` — функція логування (default: `console.error`).
+  - `runner` — попередньо створений subagent runner (інакше викликається `createRunner(deps)`).
+  - `trace` — функція трасування для `verifyTrace`.
+  - `now` — джерело часу для `recordTransition` (default: `Date.now`).
+
+**Повертає:** `Promise<number>` — exit code:
+
+- `0` — транзиція стану успішно записана.
+- `1` — помилка резолву стану / відсутній state / помилка створення runner / відсутній spec-документ.
+
+**Потік виконання:**
+
+1. **Резолв активного flow.** Викликає `resolveActiveFlowState({ cwd, branch }, deps)`. Якщо `statePath` не визначено — логує помилку й повертає `1`. Якщо flow авторезолвлено (cwd поза worktree) — логує інформаційне повідомлення з міткою.
+2. **Читання стану.** `readState(statePath)` повертає об'єкт стану або `null`. У разі `null` — логує підказку `flow init` і повертає `1`.
+3. **Опційний panel-brainstorm.** Якщо `rest` містить `--panel`:
+   - Створює runner через `createRunner(deps)` (якщо не передано в `deps.runner`); виняток → лог + `1`.
+   - Викликає `runPanel({ task: state.branch, cwd, runner, log, mode: 'spec' })`.
+   - Якщо повернувся синтез — логує його (з підказкою зберегти в `docs/specs/` і повторити `flow spec`). Об'єктний синтез серіалізується через `JSON.stringify`.
+   - **Важливо:** після `--panel` функція не виходить — продовжує спробу резолву документа (наступний крок). Це дозволяє за один виклик і синтезувати, і зафіксувати.
+4. **Резолв документа.** Шукає в `rest` перший аргумент, що закінчується на `.md`; інакше — `resolveArtifact(cwd, 'specs', state.branch)`. Якщо документ не знайдено або файл не існує — логує підказку про brainstorm і повертає `1`.
+5. **Trace-верифікація.** `verifyTrace(cwd, deps.trace)` — read-only перевірка ланцюга front-matter (adr/spec/plan). Якщо ланцюг розірвано — лише warning у лог (не фатально).
+6. **Обчислення risk.** `risk = riskFromSpec(doc, state.risk)` — front-matter spec має пріоритет над поточним.
+7. **Запис транзиції.** `recordTransition` із параметрами:
+   - `paths`: `{ statePath, eventsPath: flowEventsPath(cwd) }`.
+   - `event`: `{ type: 'spec' }`.
+   - `mutator`: `s => ({ ...s, spec_doc: doc, risk, status: 'spec' })`.
+   - `clock`: `deps.now ?? Date.now`.
+8. **Завершення.** Лог `spec: зафіксовано <doc> → status: spec (risk <risk|—>)` і повернення `0`.
+
+**Side effects:**
+
+- Логування у stderr (`console.error` або кастомний `log`).
+- Read-only доступ до файлової системи (`existsSync`, `readFileSync` у `riskFromSpec`).
+- Запис у state-store та events-log через `recordTransition`.
+- Можливий запуск subagent-runner (panel mode), який сам має побічні ефекти (мережа/IPC).
+
+## Залежності
+
+### Стандартна бібліотека Node.js
+
+| Імпорт              | Звідки         | Використання                                                          |
+| ------------------- | -------------- | --------------------------------------------------------------------- |
+| `existsSync`        | `node:fs`      | Перевірка існування spec-документа перед записом транзиції.           |
+| `readFileSync`      | `node:fs`      | Зчитування spec-документа для парсингу front-matter у `riskFromSpec`. |
+| `cwd as processCwd` | `node:process` | Default-значення для `deps.cwd`.                                      |
+
+### Внутрішні модулі
+
+| Імпорт                           | Шлях                    | Призначення                                                                                                    |
+| -------------------------------- | ----------------------- | -------------------------------------------------------------------------------------------------------------- |
+| `resolveArtifact`, `verifyTrace` | `./artifact.mjs`        | Резолв шляху артефакту за конвенцією `docs/<kind>/<date>-<slug>.md` та верифікація trace-ланцюга front-matter. |
+| `flowEventsPath`                 | `./events.mjs`          | Шлях до файлу подій воркфлоу (для аудиту транзицій).                                                           |
+| `runPanel`                       | `./plan-panel.mjs`      | Запуск agent-panel brainstorm у режимі `mode: 'spec'`.                                                         |
+| `createRunner`                   | `./subagent-runner.mjs` | Фабрика subagent runner для panel mode.                                                                        |
+| `readState`, `recordTransition`  | `./state-store.mjs`     | Читання поточного стану та атомарний запис транзиції з мутатором.                                              |
+| `resolveActiveFlowState`         | `./flow-resolve.mjs`    | Авторезолв активного flow (worktree-awareness, branch fallback).                                               |
+| `parseFrontMatter`               | `../trace.mjs`          | Парсинг YAML-подібного front-matter Markdown-документа.                                                        |
+
+## Потік виконання / Використання
+
+### CLI-сценарій
+
+```bash
+# 1. Простий запис: spec-документ резолвиться за конвенцією branch → docs/specs/
+flow spec
+
+# 2. Явний шлях до документа
+flow spec docs/specs/2026-01-15-new-feature.md
+
+# 3. З agent-panel brainstorm (синтез персон, потім збереження документа вручну)
+flow spec --panel
+
+# 4. Комбіноване: panel + явний документ
+flow spec --panel docs/specs/2026-01-15-new-feature.md
+```
+
+### Граф станів
+
+```
+flow init → status: init
+   ↓
+(brainstorm в IDE або через --panel)
+   ↓
+flow spec → status: spec, spec_doc=<path>, risk=<low|med|high>
+   ↓
+flow plan / flow review / ...
+```
+
+### Інваріанти
+
+- Перед `flow spec` обов'язково має бути виконано `flow init` (інакше — exit 1).
+- Spec-документ має існувати на ФС (`existsSync`).
+- Trace-розрив **не** блокує транзицію — лише warning (бо лінки пише агент і може не встигнути на момент запуску).
+- Panel-mode не перериває основний flow: навіть якщо синтез повернувся, функція продовжує спробу резолвити документ. Якщо документу ще нема — exit 1 з підказкою зберегти результат.
+
+### Контракт із `flow.mdc`
+
+- Контракт front-matter (поля `adr`, `spec`, `plan`, `risk`) — відповідальність агента, що генерує/редагує Markdown-документ.
+- `risk` із spec має пріоритет над попереднім `state.risk` — це механізм downstream-керування глибиною review.
+- Подія `{ type: 'spec' }` фіксується у `events.jsonl` для подальшого аудиту lifecycle.
+
+### Тестованість
+
+Усі зовнішні точки контакту проброшено через `deps`:
+
+- `cwd`, `branch` — детермінований резолв flow.
+- `log` — capture логів у тестах.
+- `runner` — мок subagent без реальних викликів LLM.
+- `trace` — мок trace-перевірки.
+- `now` — детерміновані timestamps у events.
+
+Це дозволяє покрити модуль unit-тестами без файлової системи (тільки `readFileSync`/`existsSync` потребують фейкових файлів або моків `node:fs`).