@nitra/cursor 3.21.1 → 3.23.0

package/scripts/docs/build-agents-commands.md

@@ -0,0 +1,183 @@
+# build-agents-commands.mjs
+
+## Огляд
+
+Модуль `build-agents-commands.mjs` формує перелік маркованих елементів (bullet items) для секції «Команди» у файлі `AGENTS.md`, який згенерує CLI `@nitra/cursor` під час синхронізації правил/шаблону.
+
+Принципи побудови списку:
+
+- Джерело істини — поле `scripts` у `package.json` цільового репозиторію (кореневого, не залежно від workspace).
+- Спочатку додається фіксований рядок про встановлення залежностей: `bun i` (конвенція bun-монорепо).
+- Далі — відомі ключі скриптів у заздалегідь визначеному порядку (`SCRIPT_KEYS_ORDER`), але лише ті, що реально присутні у `package.json` як непорожні рядки.
+- Після них — усі додаткові ключі, що починаються з `lint-` і ще не були додані, у лексикографічному порядку.
+- Наприкінці завжди додаються фіксовані рядки про CLI `@nitra/cursor` (синхронізація правил та `programmatic` перевірки) та про `knip` (пошук невикористаних залежностей/експортів).
+
+Модуль повертає масив об'єктів з єдиним полем `name`, який далі споживає функція `expandMustacheSection` під час підставлення в Mustache-шаблон `AGENTS.template.md` (секція `commands`).
+
+## Експорти / API
+
+| Експорт                         | Тип                                                                | Призначення                                                     |
+| ------------------------------- | ------------------------------------------------------------------ | --------------------------------------------------------------- |
+| `buildAgentsCommandBulletItems` | `async function(projectRoot: string): Promise<{ name: string }[]>` | Будує масив елементів секції `commands` для Mustache-розкриття. |
+
+Інших публічних експортів (`default`, ре-експортів) у файлі немає. Внутрішні допоміжні функції та константи (`PACKAGE_NAME`, `AGENTS_MD`, `SCRIPT_KEYS_ORDER`, `readPackageScripts`) не експортуються.
+
+## Функції
+
+### `readPackageScripts(projectRoot)`
+
+Внутрішня (не експортована) функція. Безпечно читає поле `scripts` з `package.json` у вказаному корені.
+
+- **Сигнатура**: `async function readPackageScripts(projectRoot: string): Promise<Record<string, string>>`
+- **Параметри**:
+  - `projectRoot` — абсолютний шлях до кореня репозиторію (де лежить `package.json`).
+- **Повертає**: `Promise<Record<string, string>>` — об'єкт `scripts` із `package.json`. У випадку відсутності файлу, помилки IO, некоректного JSON або відсутності/непридатного типу поля `scripts` — порожній об'єкт `{}`.
+- **Алгоритм**:
+  1. Формує абсолютний шлях `pkgPath = join(projectRoot, 'package.json')`.
+  2. Якщо файл не існує (`existsSync`) — повертає `{}`.
+  3. Інакше — `readFile(pkgPath, 'utf8')`, `JSON.parse(raw)`.
+  4. Перевіряє, що `pkg` — об'єкт, у нього є поле `scripts` типу `object`. Якщо так — повертає його (з JSDoc-кастом до `Record<string, string>`).
+  5. Будь-який кинутий виняток (некоректний JSON, помилка читання) глушиться `try/catch` без логу — секція команд лишається з мінімумом (`bun i` + рядки про CLI).
+- **Side effects**: лише синхронне `existsSync` та асинхронне читання файлу `package.json` із FS. Жодних мутацій глобального стану, жодного `console.*`, жодного `process.exit`.
+
+### `buildAgentsCommandBulletItems(projectRoot)` (експортована)
+
+Основний публічний API модуля.
+
+- **Сигнатура**: `export async function buildAgentsCommandBulletItems(projectRoot: string): Promise<{ name: string }[]>`
+- **Параметри**:
+  - `projectRoot` — абсолютний шлях до кореня репозиторію (зазвичай `process.cwd()` виклику CLI).
+- **Повертає**: `Promise<{ name: string }[]>` — впорядкований список елементів секції `commands`. Кожен елемент — об'єкт з полем `name`, що містить уже готовий рядок маркованого пункту Markdown (починається з `- **<підпис>**: \`<команда>\``).
+- **Алгоритм**:
+  1. Викликає `readPackageScripts(projectRoot)` та зберігає результат у `scripts`.
+  2. Ініціалізує масив `items` одним фіксованим елементом:
+     `- **Залежності**: \`bun i\``.
+  3. Створює `Set<string>` під назвою `added` для відстеження уже доданих ключів скриптів (запобігає дублюванню при подальшому fallback-проході).
+  4. Ітерує `SCRIPT_KEYS_ORDER` у заданому порядку: `test`, `lint`, `lint-js`, `lint-text`, `lint-ga`, `lint-k8s`, `lint-docker`, `start`, `dev`, `build`. Для кожного ключа, для якого `scripts[key]` — непорожній рядок, додає у `items` об'єкт `{ name: '- **<key>**: \`bun run <key>\`' }`і фіксує ключ у`added`.
+  5. Збирає масив `lintExtraKeys`: усі ключі `scripts`, які починаються з `lint-`, не входять у `added` і мають значення типу `string`. Сортує лексикографічно через `toSorted((a, b) => a.localeCompare(b))` (іммутабельне сортування — оригінальний масив `Object.keys(scripts)` не змінюється).
+  6. Дописує у `items` пункти для кожного `lintExtraKey` за тим самим шаблоном.
+  7. Додає три фіксовані хвостові пункти:
+     - `- **Оновити правила та AGENTS.md** (після змін у правилах/шаблоні CLI): \`npx @nitra/cursor\``
+     - `- **Перевірки правил (programmatic)**: \`npx @nitra/cursor fix\``
+     - `- **knip (невикористані залежності та експорти)**: \`bunx knip\``
+  8. Повертає `items`.
+- **Контракт для споживача**: масив гарантовано непорожній (мінімум 4 елементи: `bun i` + 3 хвостові), навіть якщо `package.json` відсутній або порожній. Усі рядки вже містять Markdown-формат та зворотні апострофи навколо команд.
+- **Side effects**: тільки опосередковані через `readPackageScripts` (читання `package.json`). Сама функція чиста відносно власних аргументів і повертає новий масив.
+
+## Константи
+
+- `PACKAGE_NAME = '@nitra/cursor'` — npm-ім'я CLI, що інтерполюється у хвостові пункти.
+- `AGENTS_MD = 'AGENTS.md'` — ім'я файлу, на який посилається пункт «Оновити правила та AGENTS.md».
+- `SCRIPT_KEYS_ORDER` — JSDoc-кастований до `const` масив із 10 ключів скриптів. Визначає фіксований порядок виводу відомих скриптів. Порядок:
+  1. `test`
+  2. `lint`
+  3. `lint-js`
+  4. `lint-text`
+  5. `lint-ga`
+  6. `lint-k8s`
+  7. `lint-docker`
+  8. `start`
+  9. `dev`
+  10. `build`
+
+## Залежності
+
+Усі імпорти — з вбудованих модулів Node.js (`node:`-префіксовані). Жодних сторонніх npm-залежностей.
+
+| Імпорт       | Джерело            | Використання                                                               |
+| ------------ | ------------------ | -------------------------------------------------------------------------- |
+| `existsSync` | `node:fs`          | Швидка синхронна перевірка наявності `package.json` перед спробою читання. |
+| `readFile`   | `node:fs/promises` | Асинхронне читання `package.json` у UTF-8.                                 |
+| `join`       | `node:path`        | Побудова крос-платформового шляху `projectRoot + 'package.json'`.          |
+
+Глобальні API: `JSON.parse`, `Object.keys`, `Array.prototype.filter`, `Array.prototype.toSorted` (Node ≥ 20), `String.prototype.localeCompare`, `String.prototype.startsWith`, `Set` (`add`, `has`).
+
+Вимога рантайму: Node.js з підтримкою ESM (`import`), `node:`-префіксу та `Array.prototype.toSorted` (Node ≥ 20). Файл — ESM (`.mjs`).
+
+## Потік виконання / Використання
+
+Типовий сценарій інтеграції в CLI `@nitra/cursor` (генерація `AGENTS.md` з Mustache-шаблону):
+
+1. CLI отримує `projectRoot` (`process.cwd()` або переданий шлях до репозиторію користувача).
+2. Викликає `buildAgentsCommandBulletItems(projectRoot)` для отримання масиву елементів секції `commands`.
+3. Передає результат у функцію розкриття Mustache-секцій (наприклад, `expandMustacheSection(template, 'commands', items)`), яка робить ітерацію по `{{#commands}} {{name}} {{/commands}}` у `AGENTS.template.md`.
+4. Отриманий Markdown записується у `AGENTS.md` у корені цільового репозиторію.
+
+Приклад використання (псевдокод):
+
+```js
+import { buildAgentsCommandBulletItems } from './build-agents-commands.mjs'
+
+const items = await buildAgentsCommandBulletItems(process.cwd())
+// items: [
+//   { name: '- **Залежності**: `bun i`' },
+//   { name: '- **test**: `bun run test`' },           // якщо є у package.json
+//   { name: '- **lint**: `bun run lint`' },           // якщо є у package.json
+//   ...
+//   { name: '- **lint-rego**: `bun run lint-rego`' }, // алфавітний fallback для lint-*
+//   { name: '- **Оновити правила та AGENTS.md** (...): `npx @nitra/cursor`' },
+//   { name: '- **Перевірки правил (programmatic)**: `npx @nitra/cursor fix`' },
+//   { name: '- **knip (невикористані залежності та експорти)**: `bunx knip`' }
+// ]
+```
+
+Граничні випадки:
+
+- **`package.json` відсутній** — повертається список лише з `bun i` + 3 хвостових пунктів (4 елементи).
+- **`package.json` некоректний (битий JSON, IO-помилка)** — те саме, що й при відсутності: виняток глушиться, повертається мінімум.
+- **`scripts` відсутній/не об'єкт** — те саме: мінімум 4 елементи.
+- **Скрипт визначений у `package.json` як порожній рядок** — пропускається (умова `scripts[key].length > 0`).
+- **Скрипт визначений не рядком (число/масив/object)** — пропускається (умова `typeof scripts[key] === 'string'`).
+- **Додаткові `lint-*` ключі**, відсутні у `SCRIPT_KEYS_ORDER` (наприклад, `lint-rego`, `lint-vue`, `lint-style`), будуть автоматично додані у відсортованому порядку після основного блоку.
+- **Дублювання** виключено: `added: Set<string>` гарантує, що один і той самий ключ не з'явиться двічі (особливо актуально для `lint-*`, які присутні і в `SCRIPT_KEYS_ORDER`, і в загальному переліку).
+
+## Rebuild Test
+
+Сценарій ручної верифікації (за припущенням, що файл імпортується з тестового скрипта):
+
+1. Підготувати тимчасову теку з мінімальним `package.json`:
+
+   ```json
+   {
+     "name": "demo",
+     "scripts": {
+       "test": "bun test",
+       "lint": "eslint .",
+       "lint-rego": "regal lint",
+       "dev": "vite",
+       "empty": ""
+     }
+   }
+   ```
+
+2. Виконати:
+
+   ```js
+   import { buildAgentsCommandBulletItems } from '/абсолютний/шлях/до/build-agents-commands.mjs'
+   const items = await buildAgentsCommandBulletItems('/абсолютний/шлях/до/тимчасової/теки')
+   console.log(items)
+   ```
+
+3. Очікуваний результат (за порядком):
+   1. `- **Залежності**: \`bun i\``
+   2. `- **test**: \`bun run test\``(із`SCRIPT_KEYS_ORDER`)
+   3. `- **lint**: \`bun run lint\``(із`SCRIPT_KEYS_ORDER`)
+   4. `- **dev**: \`bun run dev\``(із`SCRIPT_KEYS_ORDER`)
+   5. `- **lint-rego**: \`bun run lint-rego\``(fallback`lint-\*`, відсортовано)
+   6. `- **Оновити правила та AGENTS.md** (після змін у правилах/шаблоні CLI): \`npx @nitra/cursor\``
+   7. `- **Перевірки правил (programmatic)**: \`npx @nitra/cursor fix\``
+   8. `- **knip (невикористані залежності та експорти)**: \`bunx knip\``
+
+4. Перевірити, що:
+   - Скрипт `empty` (порожнє значення) пропущено.
+   - Ключі з `SCRIPT_KEYS_ORDER`, яких немає у `scripts`, не з'являються.
+   - `lint-rego` (не з основного списку) додано у блоці fallback, відсортовано.
+   - Жоден ключ не дублюється.
+
+5. Окремо перевірити шлях без `package.json`:
+   - Викликати `buildAgentsCommandBulletItems('/неіснуючий/шлях')` або теку без `package.json`.
+   - Очікувати рівно 4 елементи: `bun i`, `npx @nitra/cursor`, `npx @nitra/cursor fix`, `bunx knip`.
+
+6. Окремо перевірити битий JSON:
+   - Покласти `package.json` зі вмістом `{ "scripts":` (синтаксична помилка).
+   - Очікувати ті самі 4 мінімальні елементи (виняток зглушено всередині `readPackageScripts`).

package/scripts/docs/cli-entry.md

@@ -0,0 +1,153 @@
+# `cli-entry.mjs`
+
+## Огляд
+
+Модуль `npm/scripts/cli-entry.mjs` — невеликий утилітарний ESM-модуль (Node.js, `.mjs`), який дає можливість іншому модулю-caller'у з'ясувати, **чи запущено його як точку входу CLI** (тобто прямим викликом `node my-script.mjs` або через `bin`-shim з `package.json`), **чи його просто імпортували** з іншого модуля (наприклад, з юніт-тестів, з фасадного CLI-агрегатора, з devtools).
+
+Це класична Node.js-задача: ESM-модулі не мають `require.main === module` ідіоми CommonJS, і canonical-альтернативою служить порівняння `import.meta.url` (URL поточного файлу-модуля) із `process.argv[1]` (шлях, переданий Node.js при запуску). Модуль інкапсулює цю перевірку в одну іменовану функцію `isRunAsCli(metaUrl)` і вирішує три типові проблеми «з полів»:
+
+1. **`import.meta` лексично прив'язаний до файлу, де записаний.** Якщо помістити `import.meta.url` усередину helper-функції тут, у `cli-entry.mjs`, то будь-який модуль, що викличе helper, отримає URL **цього** helper-файлу, а не URL caller-модуля. Тому функція **обов'язково** приймає `metaUrl` як аргумент від caller'а.
+2. **Symlink-розбіжності.** На macOS `/tmp` — це симлінка на `/private/tmp`; npm/pnpm-bin'и створюють shim-скрипти в `node_modules/.bin/*`, які часто є симлінками або обгортками; pnpm-style content-addressable links теж дають різні поверхневі шляхи. Без нормалізації naive-порівняння рядків дасть `false` навіть для коректного прямого запуску. Тому модуль обертає **обидві** сторони порівняння у `realpathSync()`.
+3. **Безпечні fallback'и.** Якщо `metaUrl` не передано, або `process.argv[1]` відсутній (наприклад, REPL, embedded-runtime), або `realpathSync` кидає (файл видалено / нема прав / шлях не існує) — функція повертає `false`, а не throw. Семантика: «не впевнені, що CLI → вважаємо, що не CLI».
+
+Модуль не має side-effects на рівні top-level (лише imports), не має CLI-shebang, не виконується самостійно. Це чисто бібліотечний експорт для consumer-модулів.
+
+## Експорти / API
+
+| Експорт      | Тип                       | Призначення                                          |
+| ------------ | ------------------------- | ---------------------------------------------------- |
+| `isRunAsCli` | `function` (named export) | Перевірити, чи модуль-caller є точкою входу процесу. |
+
+Default export відсутній.
+
+## Функції
+
+### `isRunAsCli(metaUrl)`
+
+#### Сигнатура
+
+```js
+export function isRunAsCli(metaUrl)
+```
+
+Згідно JSDoc у файлі:
+
+```js
+/**
+ * @param {string | URL} [metaUrl] `import.meta.url` модуля-caller'а. Без нього — завжди `false`.
+ * @returns {boolean} `true`, якщо файл, з якого передано `metaUrl`, є `process.argv[1]`.
+ */
+```
+
+#### Параметри
+
+- **`metaUrl`** — `string | URL | undefined`. Очікується значення `import.meta.url` модуля-caller'а. Це може бути або рядок виду `file:///abs/path/to/caller.mjs`, або об'єкт `URL` із тим самим протоколом `file:`. Параметр опціональний: якщо `undefined`/`null`/порожній рядок — функція коротко повертає `false`, не виконуючи решту перевірок.
+
+#### Повертає
+
+- **`boolean`**:
+  - `true` — якщо canonical-шлях файлу caller'а (отриманий через `realpathSync(fileURLToPath(metaUrl))`) **точно дорівнює** canonical-шляху `process.argv[1]` (отриманому через `realpathSync(resolve(entry))`).
+  - `false` у всіх інших випадках:
+    - `metaUrl` не передано (`!metaUrl`);
+    - `process.argv[1]` відсутній/порожній (`!entry`);
+    - будь-яка з операцій `realpathSync`/`fileURLToPath`/`resolve` кидає виняток (зокрема `ENOENT`, `EACCES`, некоректний URL-формат, не-`file:` протокол);
+    - canonical-шляхи відрізняються (звичайний випадок «модуль імпортовано, а не запущено»).
+
+#### Алгоритм (покроково)
+
+1. Early-return: якщо `metaUrl` falsy — `false`.
+2. Зчитати `entry = process.argv[1]` (другий елемент `argv`: перший — шлях до бінарника `node`, другий — шлях до скрипта-точки входу).
+3. Early-return: якщо `entry` falsy — `false`.
+4. У `try`-блоці:
+   - Конвертувати `metaUrl` (URL вигляду `file://...`) у звичайний абсолютний шлях через `fileURLToPath(metaUrl)`.
+   - Нормалізувати симлінки в цьому шляху через `realpathSync(...)` → `callerPath`.
+   - Зробити `resolve(entry)` (на випадок, якщо `argv[1]` був відносним) і теж прогнати через `realpathSync(...)` → `entryPath`.
+   - Повернути `callerPath === entryPath` (строге порівняння рядків).
+5. У `catch` — повернути `false` (без логування, без re-throw). Будь-яка помилка трактується як «не CLI».
+
+#### Side effects
+
+- **Sync I/O:** `realpathSync` — це **синхронний** виклик файлової системи (двічі за виклик: для caller-шляху й для entry-шляху). Це блокує event loop на час stat-операцій. Для CLI-entry-перевірки, що зазвичай робиться один раз при старті — прийнятно.
+- **Файли:** функція **тільки читає** метадані файлової системи (resolve симлінків). Не пише, не створює, не видаляє.
+- **Глобальний стан:** не змінює `process`, `globalThis`, не реєструє listener'ів.
+- **Кидає:** ніколи (внутрішній `try/catch` ловить усі винятки `realpathSync`).
+- **Детермінізм:** результат залежить від (a) поточного `process.argv[1]`, (b) існування й canonical-шляху обох файлів у ФС на момент виклику. Те саме `metaUrl` за різних `argv[1]` дасть різні відповіді.
+
+## Залежності
+
+### Зовнішні (Node.js core, без npm-залежностей)
+
+- **`node:fs`** → `realpathSync` — синхронне розкриття симлінків і нормалізація шляху до canonical-форми.
+- **`node:path`** → `resolve` — приведення `process.argv[1]` до абсолютного шляху (на випадок відносного шляху в `argv[1]`).
+- **`node:url`** → `fileURLToPath` — конвертація URL-форми `file://...` (як у `import.meta.url`) у platform-native шлях ФС (включно з обробкою percent-encoding і Windows-шляхів виду `file:///C:/...`).
+
+Усі імпорти — з prefix-формою `node:` (best practice для ESM, явно вказує на built-in-модулі й виключає колізії з npm-пакетами).
+
+### Внутрішні (npm/scripts/...)
+
+Немає. Модуль не імпортує жодного локального файлу — чиста утиліта поверх Node.js core.
+
+### Зворотні залежності (хто може його використовувати)
+
+Будь-який ESM-скрипт у `npm/scripts/**`, який має «двоїсту» природу: експортує функціонал для тестів/інших модулів **і** може бути запущений напряму як CLI. Типовий патерн:
+
+```js
+import { isRunAsCli } from './cli-entry.mjs' // або відносний шлях
+
+export async function runCli(argv) {
+  // ...
+}
+
+if (isRunAsCli(import.meta.url)) {
+  await runCli(process.argv.slice(2))
+}
+```
+
+## Потік виконання / Використання
+
+### Базовий use-case (типовий CLI-скрипт)
+
+```js
+// my-tool.mjs
+import { isRunAsCli } from '../scripts/cli-entry.mjs'
+
+export function doWork(args) {
+  /* ... */
+}
+
+if (isRunAsCli(import.meta.url)) {
+  // Гарантовано: цей файл запущено як `node my-tool.mjs ...`
+  // або через bin-shim з package.json.
+  const result = doWork(process.argv.slice(2))
+  process.exit(result.exitCode ?? 0)
+}
+```
+
+Коли той самий `my-tool.mjs` імпортується в юніт-тесті (`import { doWork } from '.../my-tool.mjs'`), `process.argv[1]` вказуватиме на runner тестів (наприклад, `bun test` або `vitest`), не на `my-tool.mjs`, тому `isRunAsCli(import.meta.url)` поверне `false` і блок CLI-запуску не виконається. Це core-патерн testability для ESM CLI.
+
+### Сценарії, у яких функція повертає `false`
+
+1. **Caller не передав `metaUrl`** — `isRunAsCli()` без аргументу. Логічно: helper не може дізнатися caller'а без явної передачі `import.meta.url`.
+2. **`process.argv[1]` відсутній** — REPL (`node` без аргументу), embedded-runtime, runtime'и без `argv`.
+3. **Модуль імпортовано іншим модулем** — `argv[1]` указує на інший файл, canonical-шляхи різні.
+4. **Файл-caller видалено / нема прав** — `realpathSync` кидає → `catch` → `false`.
+5. **`metaUrl` не є валідним `file:`-URL** — `fileURLToPath` кидає → `catch` → `false`. Наприклад, `data:`-URL, HTTP-loader-URL, або синтаксично битий рядок.
+
+### Сценарії, у яких функція повертає `true`
+
+1. **Прямий запуск:** `node /abs/path/to/my-tool.mjs` — `argv[1] === '/abs/path/to/my-tool.mjs'`, `metaUrl === 'file:///abs/path/to/my-tool.mjs'`. Після canonicalization — рівні.
+2. **Запуск через bin-shim:** `npx my-tool` або `bun my-tool` (якщо `package.json` має `"bin": { "my-tool": "./my-tool.mjs" }`). `argv[1]` указує на shim у `node_modules/.bin/`, який є симлінкою на `my-tool.mjs`. `realpathSync` розкриває симлінку, шляхи стають однакові.
+3. **Запуск з відносним шляхом:** `node ./my-tool.mjs` із CWD = `/abs/path/to/`. `resolve(entry)` приведе до `/abs/path/to/my-tool.mjs`, потім `realpathSync` нормалізує.
+4. **macOS `/tmp` vs `/private/tmp`:** якщо файл лежить у `/tmp/x.mjs` (тобто `/private/tmp/x.mjs`), а `argv[1]` указує `/tmp/x.mjs` — `realpathSync` обидва зведе до `/private/tmp/x.mjs`.
+
+### Граничні випадки й нюанси
+
+- **Windows.** `fileURLToPath` коректно обробляє `file:///C:/...` → `C:\\...`. `realpathSync` працює і на Windows-junction'ах. Функція кросплатформенна.
+- **Workers/child processes.** У worker-thread `process.argv` зазвичай той самий, що в parent (якщо не змінено через `argv`-опцію `Worker`). У child-process через `spawn('node', ['child.mjs'])` `argv[1]` буде `child.mjs` — функція працює очікувано.
+- **Bun.** Bun підтримує ту саму ESM-семантику `import.meta.url` й `process.argv`. Модуль ідентично працює під Bun.
+- **`node --experimental-loader` / custom loaders.** `import.meta.url` залишається `file:`-URL для звичайних модулів. Якщо loader переписує URL на не-`file:` схему — `fileURLToPath` кине, `catch` поверне `false`. Безпечна деградація.
+- **Без розширення / з різним розширенням.** Якщо `argv[1]` без `.mjs`, а Node.js резолвить його з extension lookup — `realpathSync` повертає реальний файл із розширенням, тому порівняння лишається коректним.
+
+### Rebuild test
+
+Reading через `import { isRunAsCli } from './cli-entry.mjs'`, виклик `isRunAsCli(import.meta.url)` із caller-скрипта, прогон у двох режимах (прямий запуск `node caller.mjs` → очікуємо `true`; імпорт із іншого скрипта `node other.mjs` → очікуємо `false`) відтворюють поведінку 1-в-1. Жодних схованих залежностей від env-змінних чи глобального стану модуль не має; усі вхідні дані — `metaUrl` (параметр) і `process.argv[1]` (стандарт Node.js).

package/scripts/docs/coverage-fix.md

@@ -0,0 +1,177 @@
+# coverage-fix.mjs
+
+## Огляд
+
+Файл `npm/scripts/coverage-fix.mjs` — це ESM-модуль, який реалізує fix-режим команди `n-cursor coverage --fix`. Його призначення — автоматично запустити агента Claude Code (через офіційний SDK `@anthropic-ai/claude-agent-sdk`) і доручити йому дописати unit-тести, які «вб'ють» вцілілих мутантів, знайдених попереднім прогоном Stryker.
+
+Модуль не виконує власних мутацій коду й не аналізує покриття самостійно — він є тонким адаптером між інвентарем вцілілих мутантів (структури `SurvivedFileGroup[]`, отримані ззовні) і LLM-агентом: формує rich-промпт з контекстом ±3 рядки навколо кожного мутанта, опційно додає приклад уже існуючого тесту, після чого ітерує по стрімінгу повідомлень агента та виводить його текстові реплики у `stdout`.
+
+Файл задумано як єдину публічну точку входу для CLI-флоу `coverage --fix`: викликається з оркестратора `n-cursor coverage`, який групує мутанти Stryker по source-файлах і передає сюди готову структуру разом з абсолютним шляхом до кореня проєкту.
+
+## Експорти / API
+
+| Експорт                                     | Тип              | Призначення                                                                                                                          |
+| ------------------------------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
+| `fixSurvivedMutants(survived, projectRoot)` | `async function` | Публічна функція. Запускає агента, проганяє промпт через `@anthropic-ai/claude-agent-sdk` і друкує текстові повідомлення в `stdout`. |
+
+Внутрішні символи (не експортуються):
+
+| Символ                                  | Тип              | Призначення                                                                                                      |
+| --------------------------------------- | ---------------- | ---------------------------------------------------------------------------------------------------------------- |
+| `buildFixPrompt(survived, projectRoot)` | `async function` | Формує текстовий rich-промпт для агента: список мутантів по файлах, контекст з source, приклади тестів, правила. |
+
+JSDoc-типи, оголошені у файлі:
+
+- `MutantDetail` — `{ line: number, col: number, mutantType: string, original: string, replacement: string }` — опис одного вцілілого мутанта.
+- `SurvivedFileGroup` — `{ file: string, mutants: MutantDetail[], exampleTest: { testFile: string, code: string | null } | null, recommendationText: string | null }` — група мутантів, об'єднаних спільним source-файлом, разом з опційним прикладом існуючого тесту й текстовою рекомендацією.
+
+## Функції
+
+### `fixSurvivedMutants(survived, projectRoot)`
+
+**Сигнатура:** `async function fixSurvivedMutants(survived: SurvivedFileGroup[], projectRoot: string): Promise<void>`
+
+**Параметри:**
+
+- `survived` — масив груп вцілілих мутантів, згрупованих по source-файлу. Кожна група містить шлях до файлу, перелік мутантів, опційний приклад тесту й опційну текстову рекомендацію.
+- `projectRoot` — абсолютний шлях до кореня проєкту. Використовується одночасно як `cwd` для агента і як база для читання source-файлів при підготовці контексту в промпті.
+
+**Що повертає:** `Promise<void>`. Корисний результат — побічний ефект: створені/оновлені тести у файловій системі (їх пише агент через інструменти `Edit`/`Bash`), а також лог у `stdout`.
+
+**Алгоритм:**
+
+1. Обчислює загальну кількість мутантів: `survived.reduce((s, g) => s + g.mutants.length, 0)`.
+2. Якщо загалом 0 мутантів — друкує `✓ Всі мутанти вбиті — доповнення тестів не потрібне` і повертається (без запуску агента, без імпорту SDK).
+3. Викликає `buildFixPrompt(survived, projectRoot)` і отримує текст промпту.
+4. Друкує заголовок `🤖 coverage --fix: запускаю агента для N вцілілих мутантів...`.
+5. Робить **динамічний** `await import('@anthropic-ai/claude-agent-sdk')` (щоб не вимагати пакет у звичайному coverage-прогоні без `--fix`) і дістає функцію `query`.
+6. Запускає агента викликом `query({ prompt, options: { cwd: projectRoot, maxTurns: 20, allowedTools: ['Read', 'Edit', 'Bash'] } })`.
+7. Ітерує отриманий `AsyncIterable` через `for await (const msg of …)`. Для повідомлень з `msg.type === 'text'` друкує `msg.text` у `process.stdout` (без додаткового переносу рядка). Інші типи повідомлень (наприклад, tool_use, tool_result) — мовчазно ігноруються.
+8. Після завершення ітерації друкує фінальний `\n`.
+
+**Опції агента:**
+
+- `cwd: projectRoot` — поточна тека агента, від якої він читає файли й запускає команди.
+- `maxTurns: 20` — обмеження на кількість turns у діалозі з моделлю, щоб уникнути нескінченних циклів.
+- `allowedTools: ['Read', 'Edit', 'Bash']` — агент має право читати файли, редагувати їх (фактично — тест-файли, бо source заборонено правилом у промпті) і виконувати shell-команди (зокрема `bun test`).
+
+**Side effects:**
+
+- Запис у `process.stdout` (`console.log` + `process.stdout.write`).
+- Динамічний імпорт зовнішнього пакету `@anthropic-ai/claude-agent-sdk` — у разі його відсутності `await import(…)` кине помилку (її обробка делегована викликачу).
+- Мережеві виклики до API Anthropic (виконує сам SDK).
+- Зміни у файловій системі проєкту: створення/редагування тест-файлів та потенційне виконання тестових команд агентом через інструмент `Bash`.
+
+**Граничні випадки:**
+
+- `totalMutants === 0` — рання терміновість без імпорту SDK.
+- Помилка `import('@anthropic-ai/claude-agent-sdk')` (пакет не встановлений) — пробрасується нагору; цей файл її не ловить.
+- Помилка з боку стріму `query(...)` — пробрасується нагору; final `\n` не друкується.
+
+### `buildFixPrompt(survived, projectRoot)` (internal)
+
+**Сигнатура:** `async function buildFixPrompt(survived: SurvivedFileGroup[], projectRoot: string): Promise<string>`
+
+**Параметри:** ті самі семантики, що у `fixSurvivedMutants`.
+
+**Що повертає:** текст rich-промпту для агента.
+
+**Алгоритм:**
+
+1. Готує пустий масив `sections`.
+2. Для кожної групи `{ file, mutants, exampleTest }`:
+   1. Намагається прочитати source-файл `join(projectRoot, file)` у `utf8` і розбити на рядки. У разі помилки (`catch {}`) — `srcLines` лишається `[]`, і контекст просто не додасться.
+   2. Для кожного мутанта в групі формує опис:
+      - `ctxStart = Math.max(0, m.line - 4)` — індекс початку контексту (0-based, бо рядки в редакторі 1-based; `m.line - 4` дає 3 рядки до мутанта).
+      - `ctxEnd = Math.min(srcLines.length, m.line + 3)` — індекс кінця (виключний), 3 рядки після мутанта.
+      - `context` — зріз `srcLines.slice(ctxStart, ctxEnd)`, де кожен рядок префіксується абсолютним номером `${ctxStart + i + 1}: ${l}` і з'єднується через `\n`.
+      - Опис мутанта — markdown-bullet з полями: рядок, колонка, тип мутації (`m.mutantType` у backticks), оригінал (`m.original`), вцілілий варіант (`m.replacement`), а нижче — fenced code block з контекстом (якщо контекст не порожній). Порожні елементи фільтруються через `.filter(Boolean)`.
+   3. Якщо є `exampleTest.code` — додає окрему секцію `Приклад тесту з \`${exampleTest.testFile}\``з fenced`js`-блоком. Інакше `exampleSection` — порожній рядок.
+   4. Заштовхує у `sections` рядок виду:
+      ```
+      ### `<file>`<exampleSection>
+      <mutantDescriptions>
+      ```
+3. Повертає одну склеєну рядкову відповідь, що складається з:
+   - Заголовка-завдання (4 рядки): «Твоє завдання — написати unit-тести…» з конкретною інструкцією: знайти/створити тест-файл, додати кейс, що провалиться при заміні коду на «вцілілий варіант».
+   - Розділу `## Вцілілі мутанти` зі склеєними `sections`.
+   - Розділу `## Правила`:
+     - «Не змінюй source-файли — лише test-файли.»
+     - «Використовуй той самий test-фреймворк, що вже в проєкті.»
+     - «Запусти `bun test` (або відповідну команду) після кожного файлу — переконайся, що 0 fail.»
+     - «Якщо мутант охоплений іншим новим тестом — не дублюй.»
+
+**Side effects:** читання source-файлів через `fs/promises.readFile`. Помилки читання (відсутній файл, нечитабельний шлях) тихо проковтуються — функція гарантує, що повертає валідний промпт навіть для повністю відсутніх файлів (просто без контексту).
+
+**Граничні випадки:**
+
+- `srcLines.length === 0` — `context` стає порожнім рядком, fenced-блок з контекстом не додається до bullet.
+- `m.line` поза межами файлу — `slice` поверне порожній зріз; жодного винятку.
+- `exampleTest === null` або `exampleTest.code === null/undefined` — `exampleSection` залишається порожнім (через `?.code` optional chaining).
+- `mutants.length === 0` у групі — група все одно потрапить у `sections` з заголовком і порожнім тілом (виклична сторона зазвичай не подає пусті групи, бо `fixSurvivedMutants` ще раніше відсіче випадок `totalMutants === 0`).
+
+## Залежності
+
+**Зовнішні (npm):**
+
+- `@anthropic-ai/claude-agent-sdk` — офіційний SDK Claude Code, експортує функцію `query()` з async-generator-інтерфейсом для стрімінгу повідомлень агента. Завантажується через **dynamic import**, виключно в момент виклику `fixSurvivedMutants` з ненульовим списком мутантів. Декларується у `dependencies` файлу `npm/package.json` (як зазначено у JSDoc-шапці модуля).
+
+**Node.js stdlib:**
+
+- `node:fs/promises` — використовується `readFile` для читання source-файлів при формуванні контексту в промпті.
+- `node:path` — використовується `join` для зчеплення `projectRoot` з відносним шляхом файлу мутанта.
+
+**Глобальні API середовища:**
+
+- `console.log` — друк інформаційних рядків (старт/пропуск).
+- `process.stdout.write` — потоковий друк reply-чанків агента (без auto-newline).
+
+**Внутрішні залежності проєкту:**
+
+- Модуль не імпортує інших файлів з `npm/scripts/` напряму, але формат вхідної структури `SurvivedFileGroup` визначається сусідніми скриптами в каталозі `npm/scripts/` (там, де живе оркестратор `coverage`, який збирає й групує мутантів Stryker і передає сюди готовий масив).
+
+## Потік виконання / Використання
+
+Типовий ланцюжок:
+
+1. CLI `n-cursor coverage --fix` (зовнішня обгортка) запускає Stryker і збирає список вцілілих мутантів.
+2. Оркестратор групує мутантів по `file`, готує `exampleTest` (опційно) і викликає:
+
+   ```js
+   import { fixSurvivedMutants } from './npm/scripts/coverage-fix.mjs'
+
+   await fixSurvivedMutants(survived, projectRoot)
+   ```
+
+3. `fixSurvivedMutants`:
+   - Перевіряє, що мутанти взагалі є; якщо ні — друкує success-повідомлення і виходить.
+   - Будує промпт через `buildFixPrompt` (читання source-файлів для контексту відбувається саме тут).
+   - Динамічно імпортує `@anthropic-ai/claude-agent-sdk`.
+   - Стрімить агента з обмеженнями: `cwd = projectRoot`, до 20 turns, інструменти `Read | Edit | Bash`.
+   - Друкує всі текстові реплики у `stdout` у реальному часі.
+4. Агент за правилами промпту читає source-файли (лише для розуміння), знаходить/створює відповідні test-файли, дописує кейси, запускає `bun test` і повторює, доки `maxTurns` або модель не вирішить, що готово.
+5. Після завершення стріму `fixSurvivedMutants` дописує фінальний `\n` і повертає `void`.
+
+**Принципи дизайну, що випливають із коду:**
+
+- **Lazy SDK loading.** Імпорт SDK — динамічний, щоб звичайний `coverage` (без `--fix`) не вимагав встановленого `@anthropic-ai/claude-agent-sdk` і не платив за його завантаження.
+- **Ізоляція знань про Stryker.** Цей файл нічого не знає про сам Stryker — він працює з уже нормалізованою структурою `SurvivedFileGroup[]`; уся інтеграція зі Stryker лежить в іншому модулі-оркестраторі.
+- **No source mutation by agent.** Жорстке правило в промпті («Не змінюй source-файли — лише test-файли») задає очікувану поведінку агента; додатково обмежений набір інструментів (`Read | Edit | Bash`) дає змогу йому редагувати тести й запускати тестову команду, але не лазити в систему по непотрібному.
+- **Стрімінг тільки текстових повідомлень.** Інші типи (наприклад, tool_use / tool_result) свідомо не рендеряться, щоб лог у консолі лишався читабельним для людини.
+
+**Приклад вхідної структури:**
+
+```js
+const survived = [
+  {
+    file: 'src/foo.js',
+    mutants: [{ line: 42, col: 10, mutantType: 'ConditionalExpression', original: 'a > b', replacement: 'a >= b' }],
+    exampleTest: { testFile: 'src/foo.test.js', code: "test('foo', () => { /* ... */ })" },
+    recommendationText: null
+  }
+]
+
+await fixSurvivedMutants(survived, '/abs/path/to/project')
+```
+
+> Примітка: поле `recommendationText` присутнє в JSDoc-типі `SurvivedFileGroup`, але в поточній реалізації `coverage-fix.mjs` воно **не** використовується при формуванні промпту — резервоване для майбутнього розширення (наприклад, додавання текстових порад поряд із прикладом тесту).