@nitra/cursor 3.22.0 → 3.23.0

package/scripts/lib/docs/ensure-tool.md

@@ -0,0 +1,254 @@
+# ensure-tool.mjs
+
+## Огляд
+
+Модуль `ensure-tool.mjs` — єдина точка резолву зовнішніх CLI-залежностей пакета `@nitra/cursor`. Він гарантує, що потрібний бінарник (`hk`, `conftest`, `shellcheck`, `actionlint`, `dotenv-linter`, `opa`, `regal`, `hadolint`, `kubeconform`, `kubescape`) доступний у системі, виконуючи послідовний пошук:
+
+1. У системному `PATH` (через `resolveCmd`).
+2. У керованому кеші бінарників (`~/.cache/@nitra/cursor/bin/` на Linux/macOS або `%LOCALAPPDATA%\@nitra\cursor\bin\` на Windows).
+3. Авто-встановлення відповідно до OS (`brew` для macOS, `scoop` для Windows із fallback на GitHub Release, прямий завантажувач GitHub Release для Linux).
+4. Hard-fail з персоналізованою підказкою, якщо авто-встановлення вимкнено змінною середовища `N_CURSOR_NO_AUTO_INSTALL`.
+
+Така архітектура усуває дублювання install-логіки в кожному `lint.mjs` / `fix.mjs`: щоб додати нову зовнішню утиліту, достатньо одного запису в реєстрі `TOOLS`. Додатково модуль експортує `ensureHkInstall`, який реєструє git pre-commit hook через `hk install` (пропускається в CI).
+
+Файл написаний для Node.js (ESM), використовує лише стандартну бібліотеку та один локальний хелпер `resolveCmd`.
+
+## Експорти / API
+
+| Експорт                  | Тип        | Призначення                                                                                                    |
+| ------------------------ | ---------- | -------------------------------------------------------------------------------------------------------------- |
+| `ensureTool(toolId)`     | `function` | Резолвить і за потреби встановлює зовнішній CLI. Повертає абсолютний шлях до бінарника або кидає `Error`.      |
+| `ensureHkInstall(hkBin)` | `function` | Виконує `hk install` для реєстрації git pre-commit hook. Жодного return value; на помилку лише `console.warn`. |
+
+Внутрішні (не експортуються, але формують контракт модуля):
+
+- `TOOLS` — реєстр `Record<string, ToolEntry>` із описом install-стратегії для кожного тула.
+- `ToolEntry` — JSDoc-тип, що описує поля одного запису реєстру.
+- Допоміжні функції: `getCacheDir`, `mapArch`, `fetchLatestVersion`, `installFromGithub`, `installViaBrew`, `installViaScoop`, `autoInstall`, `buildHint`.
+
+## Функції
+
+### `getCacheDir()`
+
+- **Сигнатура:** `getCacheDir(): string`
+- **Параметри:** немає.
+- **Повертає:** абсолютний шлях до каталогу кешу бінарників.
+- **Логіка:**
+  - На `win32` бере `process.env.LOCALAPPDATA` (fallback `homedir()/AppData/Local`) і додає `@nitra/cursor/bin`.
+  - На інших платформах повертає `homedir()/.cache/@nitra/cursor/bin`.
+- **Side effects:** немає (тільки читає env / `os.homedir`).
+
+### `mapArch(nodeArch, style)`
+
+- **Сигнатура:** `mapArch(nodeArch: 'x64'|'arm64'|string, style: 'hk'|'conftest'|'actionlint'): string`
+- **Параметри:**
+  - `nodeArch` — значення `process.arch`.
+  - `style` — стиль іменування платформи для release-asset:
+    - `'actionlint'` → `amd64` / `arm64`.
+    - `'conftest'` → `x86_64` / `arm64`.
+    - `'hk'` (та інші release-asset стилі: shellcheck, dotenv-linter) → `x86_64` / `aarch64`.
+- **Повертає:** рядок архітектури, очікуваний у назві release-asset.
+- **Side effects:** немає.
+
+### `fetchLatestVersion(repo, curlBin)`
+
+- **Сигнатура:** `fetchLatestVersion(repo: string, curlBin: string): string`
+- **Параметри:**
+  - `repo` — репозиторій у форматі `owner/repo`.
+  - `curlBin` — абсолютний шлях до бінарника `curl`.
+- **Повертає:** версію останнього релізу без префікса `v` (наприклад `0.4.1`).
+- **Поведінка:** через `spawnSync` викликає `curl -sSL -H "Accept: application/vnd.github+json" https://api.github.com/repos/<repo>/releases/latest`, парсить JSON, бере поле `tag_name`, прибирає префікс `v` за допомогою регексу `TAG_V_PREFIX_RE`.
+- **Помилки:**
+  - `curl failed: ...` — `r.error` ненульове.
+  - `curl exit <status>: ...` — ненульовий exit-код.
+  - `GitHub API response is not JSON: ...` — некоректний JSON.
+  - `GitHub API: tag_name missing for <repo>` — у відповіді немає `tag_name`.
+- **Side effects:** мережевий HTTP-запит до GitHub API.
+
+### `installFromGithub(toolId, entry, cacheDir)`
+
+- **Сигнатура:** `installFromGithub(toolId: string, entry: ToolEntry, cacheDir: string): string`
+- **Параметри:**
+  - `toolId` — ключ у `TOOLS`.
+  - `entry` — `ToolEntry` для цього тула.
+  - `cacheDir` — абсолютний шлях до каталогу кешу.
+- **Повертає:** абсолютний шлях до встановленого бінарника.
+- **Послідовність дій:**
+  1. Резолвить `curl` та `tar` у PATH; за відсутності — кидає `Error`.
+  2. Через `fetchLatestVersion` отримує актуальну версію.
+  3. Формує назву asset через `entry.asset(ver)` і URL `https://github.com/<github>/releases/download/v<ver>/<asset>`.
+  4. Створює `cacheDir` (`mkdirSync` з `recursive: true`).
+  5. Завантажує asset через `curl -sSL -o <archivePath> <downloadUrl>`.
+  6. Якщо `entry.archive === false` — перейменовує завантажений файл у `<cacheDir>/<toolId>`, виставляє права `0o755` і повертає шлях.
+  7. Інакше викликає `tar` із прапорцем `-xJf` (для `.tar.xz`) або `-xzf` (для `.tar.gz`) для розпакування в `cacheDir`.
+  8. Визначає реальний шлях до бінарника через `entry.binFinder(ver)` або просто `toolId`. Перевіряє існування файлу.
+  9. Опціонально видаляє завантажений архів через `rm` (м’яко: якщо `rm` не знайдено, продовжує).
+- **Помилки:**
+  - `curl не знайдено в PATH — потрібен для завантаження <toolId>`.
+  - `tar не знайдено в PATH — потрібен для встановлення <toolId>`.
+  - `Завантаження <toolId> не вдалось: ...` / `curl exit <status> при завантаженні <toolId>: ...`.
+  - `tar failed for <toolId>: ...` / `tar exit <status> для <toolId>: ...`.
+  - `Бінарник <toolId> не знайдено після розпакування: <binPath>`.
+- **Side effects:** мережа, файлова система (створення/перейменування файлів, chmod, видалення архіву).
+
+### `installViaBrew(toolId, entry)`
+
+- **Сигнатура:** `installViaBrew(toolId: string, entry: ToolEntry): string`
+- **Параметри:** `toolId` і `entry` як у попередній функції.
+- **Повертає:** абсолютний шлях до бінарника після встановлення (через повторний `resolveCmd(toolId)`).
+- **Послідовність дій:**
+  1. Резолвить `brew` у PATH; на відсутність кидає `brew не знайдено в PATH. Встанови Homebrew: https://brew.sh`.
+  2. Виконує `brew install <entry.brew>` із `stdio: 'inherit'` (інтерактивний прогрес).
+  3. Перевіряє exit-код і `error` об’єкт.
+  4. Після успіху повторно резолвить `toolId` у PATH; якщо й тоді нема — кидає `... не знайдено в PATH після brew install`.
+- **Side effects:** виклик зовнішнього `brew install` (мережа, мутація системного стану на macOS).
+
+### `installViaScoop(toolId, entry)`
+
+- **Сигнатура:** `installViaScoop(toolId: string, entry: ToolEntry): string`
+- **Параметри:** як вище.
+- **Повертає:** абсолютний шлях до бінарника після встановлення.
+- **Поведінка:** дзеркало `installViaBrew`, але для `scoop install`.
+  - Якщо `entry.scoop === null` — кидає `... недоступний у Scoop. Встанови вручну: https://github.com/<repo>/releases`.
+  - Якщо `scoop` не у PATH — кидає `scoop не знайдено в PATH. Встанови Scoop: https://scoop.sh`.
+- **Side effects:** виклик зовнішнього `scoop install`.
+
+### `autoInstall(toolId, entry, cacheDir)`
+
+- **Сигнатура:** `autoInstall(toolId: string, entry: ToolEntry, cacheDir: string): string`
+- **Поведінка диспетчера за платформою:**
+  - `darwin` → `installViaBrew`.
+  - `win32` → пробує `installViaScoop`, на будь-який throw — fallback на `installFromGithub` (наприклад, для `dotenv-linter` чи `regal`, де `scoop: null`).
+  - Інше (Linux) → `installFromGithub`.
+- **Повертає:** абсолютний шлях до бінарника.
+- **Side effects:** делегує своїм внутрішнім installer-ам.
+
+### `buildHint(toolId, entry)`
+
+- **Сигнатура:** `buildHint(toolId: string, entry: ToolEntry): string`
+- **Параметри:** як вище.
+- **Повертає:** багаторядкове повідомлення для error message при заблокованому авто-installі.
+- **Формат:**
+  - Перший рядок — `❌ <toolId> не знайдено в PATH і авто-встановлення відключено (N_CURSOR_NO_AUTO_INSTALL).`.
+  - Другий рядок — `   Встанови:`.
+  - Далі — OS-specific підказка:
+    - macOS: `     macOS: brew install <entry.brew>`.
+    - Windows: `     Windows: scoop install <entry.scoop>` (якщо доступний) та `     або: https://github.com/<repo>/releases`.
+    - Linux: `     Linux: https://github.com/<repo>/releases`.
+- **Side effects:** немає.
+
+### `ensureTool(toolId)` _(export)_
+
+- **Сигнатура:** `ensureTool(toolId: string): string`
+- **Параметри:** `toolId` — ключ у реєстрі `TOOLS` (`'hk'`, `'conftest'`, `'shellcheck'`, `'actionlint'`, `'dotenv-linter'`, `'opa'`, `'regal'`, `'hadolint'`, `'kubeconform'`, `'kubescape'`).
+- **Повертає:** абсолютний шлях до бінарника.
+- **Послідовність резолву:**
+  1. **Валідація** — якщо `TOOLS[toolId]` відсутній, кидає `ensureTool: невідомий тул '<toolId>'`.
+  2. **PATH** — `resolveCmd(toolId)`; якщо знайдено — повертає одразу.
+  3. **Кеш** — `join(getCacheDir(), toolId)`; якщо файл існує — повертає його шлях. Зауваження: перевірка спрощена і не враховує `entry.binFinder` (для cached binaries `installFromGithub` уже клав фінальний бінарник у відоме місце або кеш просто не містить такого файлу — у такому разі переходимо до install).
+  4. **Авто-install** — якщо змінна середовища `N_CURSOR_NO_AUTO_INSTALL` не виставлена, викликає `autoInstall(toolId, entry, cacheDir)`.
+  5. **Hard-fail** — кидає `Error(buildHint(toolId, entry))`.
+- **Помилки:** будь-яка з помилок `autoInstall` / `installFrom*` піднімається вгору; додатково — `невідомий тул` та `❌ ... не знайдено в PATH`.
+- **Side effects:** мережа, файлова система, виклик зовнішніх install-команд (`brew`, `scoop`, `curl`, `tar`, `rm`).
+
+### `ensureHkInstall(hkBin)` _(export)_
+
+- **Сигнатура:** `ensureHkInstall(hkBin: string): void`
+- **Параметри:**
+  - `hkBin` — абсолютний шлях до бінарника `hk` (зазвичай отриманий через `ensureTool('hk')`).
+- **Повертає:** `void`.
+- **Логіка:**
+  - Якщо `process.env.CI` truthy — функція виходить без дії (не реєструємо hook у CI).
+  - Інакше виконує `spawnSync(hkBin, ['install'], { stdio: 'inherit' })`.
+  - На `r.error` або ненульовий `r.status` виводить попередження через `console.warn` (не кидає!).
+- **Side effects:** запис git pre-commit hook у `.git/hooks/pre-commit` (через `hk`), вивід у stdout/stderr.
+
+## Залежності
+
+### Стандартна бібліотека Node.js
+
+- `node:child_process` — `spawnSync` для синхронного запуску `curl`, `tar`, `brew`, `scoop`, `rm`, `hk`.
+- `node:fs` — `chmodSync`, `existsSync`, `mkdirSync`, `renameSync`.
+- `node:os` — `homedir` для побудови шляху кешу.
+- `node:path` — `join` для конструювання шляхів.
+- `node:process` — `arch`, `env`, `platform`.
+
+### Внутрішні
+
+- `../utils/resolve-cmd.mjs` → `resolveCmd(cmd)` — кросплатформне резолвлення абсолютного шляху до бінарника в PATH (Linux/macOS — like `which`, Windows — like `where`).
+
+### Зовнішні CLI (виконуються через `spawnSync`)
+
+- `curl` — завантаження GitHub API і release-asset.
+- `tar` — розпакування `.tar.gz` / `.tar.xz`.
+- `rm` — м’яке видалення завантаженого архіву (необов’язково).
+- `brew` — install на macOS.
+- `scoop` — install на Windows.
+- `hk` — реєстрація git pre-commit hook у `ensureHkInstall`.
+
+### Змінні середовища
+
+- `N_CURSOR_NO_AUTO_INSTALL` — якщо встановлена, блокує авто-install і змушує `ensureTool` кидати помилку з install-hint.
+- `CI` — якщо truthy, `ensureHkInstall` нічого не робить.
+- `LOCALAPPDATA` (Windows) — використовується для побудови шляху кешу.
+
+## Потік виконання / Використання
+
+### Типовий сценарій `ensureTool('shellcheck')` на Linux x64
+
+1. Викликається `ensureTool('shellcheck')`.
+2. `resolveCmd('shellcheck')` — не знайдено в `PATH`.
+3. `getCacheDir()` повертає `/home/<user>/.cache/@nitra/cursor/bin`.
+4. Перевірка `/home/<user>/.cache/@nitra/cursor/bin/shellcheck` — не існує.
+5. `N_CURSOR_NO_AUTO_INSTALL` не виставлено → `autoInstall(...)`.
+6. На Linux диспетчер викликає `installFromGithub('shellcheck', entry, cacheDir)`:
+   - `fetchLatestVersion('koalaman/shellcheck', curl)` → наприклад `0.10.0`.
+   - asset name = `shellcheck-v0.10.0.linux.x86_64.tar.xz`.
+   - URL = `https://github.com/koalaman/shellcheck/releases/download/v0.10.0/<asset>`.
+   - `mkdirSync(cacheDir, { recursive: true })`.
+   - `curl -sSL -o <cacheDir>/<asset> <url>`.
+   - `tar -xJf <asset> -C <cacheDir>` (бо `.tar.xz`).
+   - `binFinder('0.10.0')` → `shellcheck-v0.10.0/shellcheck`.
+   - Перевірка `existsSync(<cacheDir>/shellcheck-v0.10.0/shellcheck)`.
+   - `rm <archivePath>`.
+   - Повертає `<cacheDir>/shellcheck-v0.10.0/shellcheck`.
+7. Викликач отримує абсолютний шлях і запускає `spawnSync(bin, [...args])`.
+
+### Сценарій блокування авто-installу
+
+```js
+process.env.N_CURSOR_NO_AUTO_INSTALL = '1'
+ensureTool('hk')
+// throws Error із багаторядковим hint, наприклад на macOS:
+// ❌ hk не знайдено в PATH і авто-встановлення відключено (N_CURSOR_NO_AUTO_INSTALL).
+//    Встанови:
+//      macOS: brew install hk
+```
+
+### Сценарій реєстрації git hook
+
+```js
+import { ensureTool, ensureHkInstall } from './lib/ensure-tool.mjs'
+
+const hkBin = ensureTool('hk') // PATH → кеш → brew/scoop/github
+ensureHkInstall(hkBin) // git hook у .git/hooks/pre-commit
+```
+
+У CI (`process.env.CI=true`) другий виклик стає no-op, що зручно для pipeline-ів, де hooks не потрібні.
+
+### Розширення реєстру
+
+Щоб додати новий тул `foo`:
+
+1. Підбрати `brew`-формулу та `scoop`-пакет (або `null`, якщо відсутній).
+2. Знайти GitHub-репо релізів і визначити `archStyle` (`hk` / `conftest` / `actionlint`).
+3. Описати `asset(ver)` та, якщо потрібно, `binFinder(ver)` (коли бінарник лежить не в корені архіву).
+4. Виставити `archive: false` для прямого бінарника без архіву.
+5. Додати запис у `TOOLS`. Жодних змін у викликачах не потрібно — `ensureTool('foo')` запрацює одразу.
+
+### Гарантії та інваріанти
+
+- **Ідемпотентність:** повторний виклик `ensureTool` повертає шлях за O(1) після першого install — спочатку PATH, потім кеш.
+- **Hard-fail:** на будь-яку нерозв’язну помилку install кидається `Error` із описовим повідомленням; немає silent fallback на «обірваний» бінарник.
+- **Кросплатформність:** єдиний публічний API для трьох ОС; OS-specific деталі інкапсульовані всередині модуля.
+- **Безпека для CI:** `ensureHkInstall` ніколи не змінює git-репозиторій під CI, навіть якщо `hk` доступний.

package/scripts/lib/docs/generated-markdown.md

@@ -0,0 +1,275 @@
+# generated-markdown.mjs
+
+## Огляд
+
+Модуль `generated-markdown.mjs` містить набір чистих утиліт для генерації згенерованих маркдаун-файлів (зокрема `AGENTS.md` та `CLAUDE.md`) у межах CLI `n-cursor`. Він виконує дві основні задачі:
+
+1. Розгортає Mustache-подібні блоки `{{#section}}…{{/section}}` із простою підстановкою одного поля `{{prop}}` для кожного елемента переданого масиву.
+2. Нормалізує підсумковий markdown, не лишаючи послідовностей із трьох і більше `\n` (тобто двох і більше порожніх рядків поспіль), щоб результат відповідав правилу markdownlint **MD012** (no multiple blank lines).
+
+Усі функції модуля — суто функціональні (без побічних ефектів, без I/O, без залежностей від глобального стану). Вхід — рядки та звичайні JS-обʼєкти, вихід — рядок.
+
+Файл реалізовано як ES-модуль (ESM), розширення `.mjs`, експорти `export function`.
+
+## Експорти / API
+
+Модуль експортує чотири іменовані функції:
+
+| Експорт                        | Тип                                                                                                                          | Призначення                                                                                                                   |
+| ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
+| `collapseMultipleBlankLines`   | `(text: string) => string`                                                                                                   | Згортає 3+ послідовних `\n` до рівно `\n\n`.                                                                                  |
+| `expandMustacheSection`        | `(template: string, section: string, items: Record<string,string>[], prop: string) => string`                                | Розгортає блок `{{#section}}…{{/section}}` для кожного елемента масиву `items`, підставляючи `item[prop]` замість `{{prop}}`. |
+| `renderAgentsTemplate`         | `(templateText: string, mdcBasenames: string[], skillItems: { name: string }[], commandItems: { name: string }[]) => string` | Високорівневий рендерер шаблону `AGENTS.template.md`: підставляє списки правил, скілів і команд та нормалізує порожні рядки.  |
+| `formatGeneratedMarkdownLines` | `(lines: string[]) => string`                                                                                                | Збирає масив рядків у єдиний markdown-документ із гарантованим завершальним `\n` і без подвійних порожніх рядків.             |
+
+Усі функції детерміновані: для однакових входів повертають однаковий вихід.
+
+## Функції
+
+### `collapseMultipleBlankLines(text)`
+
+**Сигнатура**
+
+```js
+export function collapseMultipleBlankLines(text)
+```
+
+**Параметри**
+
+- `text` (`string`) — вихідний markdown або будь-який текст. Якщо передано не-рядок, він буде явно скастовано через `String(text)`.
+
+**Повертає**
+
+- `string` — той самий текст, у якому всі послідовності з трьох і більше `\n` замінено на рівно два `\n` (тобто між блоками лишається не більше ніж один порожній рядок).
+
+**Алгоритм**
+
+1. Виконує `String(text)` — захист від нерядкового входу (наприклад, `null`, `undefined`, число, обʼєкт).
+2. Викликає `replaceAll(/\n{3,}/g, '\n\n')` — глобальна заміна всіх послідовностей `\n{3,}` на `\n\n`.
+
+**Side effects**
+
+- Немає. Функція чиста.
+
+**Особливості**
+
+- Послідовності `\n\n` (один порожній рядок) залишаються без змін.
+- Працює лише з символом `\n`; `\r\n` (CRLF) не нормалізується явно — якщо вхід містить CRLF, регулярка не спрацює на парах `\r\n\r\n\r\n` як на трьох `\n`.
+
+### `expandMustacheSection(template, section, items, prop)`
+
+**Сигнатура**
+
+```js
+export function expandMustacheSection(template, section, items, prop)
+```
+
+**Параметри**
+
+- `template` (`string`) — вихідний текст шаблону, що може містити нуль чи більше блоків `{{#section}}…{{/section}}`.
+- `section` (`string`) — імʼя секції (наприклад, `services`, `skills`, `commands`). Підставляється у відкриваючий тег `{{#section}}` і закриваючий `{{/section}}`.
+- `items` (`Record<string, string>[]`) — масив елементів-обʼєктів. Для кожного елемента тіло секції повторюється один раз.
+- `prop` (`string`) — імʼя поля, значення якого підставляється замість `{{prop}}` у тілі секції. Значення приводиться до рядка через `String(item[prop])`.
+
+**Повертає**
+
+- `string` — текст шаблону, у якому всі знайдені блоки `{{#section}}…{{/section}}` замінено на згенерований вміст. Якщо блоків немає — повертає вхідний рядок без змін.
+
+**Алгоритм**
+
+1. Будує константи `open = '{{#${section}}}'`, `close = '{{/${section}}}'`, `placeholder = '{{${prop}}}'`.
+2. У циклі шукає першу позицію `start = indexOf(open)` та `end = indexOf(close)` у поточному значенні `result`.
+3. Поки знайдено валідну пару (`start !== -1 && end !== -1 && end > start`):
+   - Витягує `inner = result.slice(start + open.length, end).trim()` — тіло секції без обрамних пробілів/переносів.
+   - Для кожного `item` з `items` будує рядок `inner.split(placeholder).join(String(item[prop]))` — повна заміна всіх входжень `placeholder` на значення поля.
+   - Зʼєднує всі рендери одним `\n` (без зайвих порожніх рядків між елементами).
+   - Підставляє згенерований текст замість усього блоку: `result = result.slice(0, start) + rendered + result.slice(end + close.length)`.
+   - Перераховує `start` і `end` для наступної ітерації.
+4. Повертає `result`.
+
+**Side effects**
+
+- Немає. Функція чиста.
+
+**Особливості й обмеження**
+
+- Блок підставляється лише за умови `end > start`, тобто закриття має йти після відкриття; вкладені секції з тим самим імʼям не підтримуються.
+- `trim()` тіла секції видаляє пробіли/переноси на початку й у кінці — це навмисно, щоб не лишати пустого рядка на стику з оточуючим markdown.
+- Plаceholder `{{prop}}` замінюється через `split(...).join(...)` — це еквівалентно глобальній заміні без побудови RegExp.
+- Якщо `items` порожній — блок замінюється на порожній рядок (`[].join('\n') === ''`).
+- Підстановка `prop` єдина на блок: модуль не підтримує кілька різних змінних усередині одного блоку.
+
+### `renderAgentsTemplate(templateText, mdcBasenames, skillItems, commandItems)`
+
+**Сигнатура**
+
+```js
+export function renderAgentsTemplate(templateText, mdcBasenames, skillItems, commandItems)
+```
+
+**Параметри**
+
+- `templateText` (`string`) — повний вміст файлу `AGENTS.template.md` із Mustache-блоками `{{#services}}`, `{{#skills}}`, `{{#commands}}` (кожен зі своїм `{{name}}` усередині).
+- `mdcBasenames` (`string[]`) — масив імен файлів правил `*.mdc` з каталогу `.cursor/rules` (саме базові імена, без шляху).
+- `skillItems` (`{ name: string }[]`) — готові рядки для секції Skills у форматі `{ name: '…' }` (зазвичай вже включають bullet/опис).
+- `commandItems` (`{ name: string }[]`) — готові рядки для секції commands у форматі `{ name: '…' }`.
+
+**Повертає**
+
+- `string` — готовий вміст `AGENTS.md` із розгорнутими секціями та згорнутими подвійними порожніми рядками.
+
+**Алгоритм**
+
+1. Перетворює `mdcBasenames` на `serviceItems` виду `{ name: '- .cursor/rules/${mdcName}' }` — додає префікс маркера списку й каталог `.cursor/rules/`.
+2. Послідовно викликає `expandMustacheSection` для трьох секцій:
+   - `services` із `serviceItems` і ключем `name`;
+   - `skills` із `skillItems` і ключем `name`;
+   - `commands` із `commandItems` і ключем `name`.
+3. Передає результат у `collapseMultipleBlankLines` і повертає його.
+
+**Side effects**
+
+- Немає. Файлову систему не читає й не пише — лише трансформує переданий рядок.
+
+**Особливості**
+
+- Ключ `name` зашитий у функцію — структура `skillItems` і `commandItems` має містити саме поле `name`.
+- Кожен елемент `mdcBasenames` форматується як bullet списку (`- ...`) у єдиному стилі.
+
+### `formatGeneratedMarkdownLines(lines)`
+
+**Сигнатура**
+
+```js
+export function formatGeneratedMarkdownLines(lines)
+```
+
+**Параметри**
+
+- `lines` (`string[]`) — масив рядків markdown-документа. Кожен елемент — окремий «рядок» (може бути порожнім або містити кілька логічних рядків).
+
+**Повертає**
+
+- `string` — підсумковий текст, у якому:
+  - елементи `lines` зʼєднано через `\n`;
+  - послідовності з 3+ `\n` згорнуто до `\n\n` (через `collapseMultipleBlankLines`);
+  - гарантовано додано завершальний `\n`, якщо його не було.
+
+**Алгоритм**
+
+1. `text = lines.join('\n')` — конкатенація через символ переносу рядка.
+2. `collapsed = collapseMultipleBlankLines(text)` — нормалізація порожніх рядків.
+3. Якщо `collapsed.endsWith('\n')` — повернути як є; інакше повернути `collapsed + '\n'`.
+
+**Side effects**
+
+- Немає.
+
+**Особливості**
+
+- Завершальний `\n` гарантує, що згенерований файл закінчується новим рядком (вимога багатьох лінтерів і POSIX-конвенції).
+- Жодних відступів чи табуляцій функція не корегує — лише вертикальну щільність.
+
+## Залежності
+
+### Зовнішні
+
+- Жодних. Модуль не імпортує нічого ні з `node:*`, ні з npm-пакетів, ні з інших файлів проєкту.
+
+### Внутрішні (між функціями модуля)
+
+- `renderAgentsTemplate` використовує `expandMustacheSection` (тричі) і `collapseMultipleBlankLines` (один раз).
+- `formatGeneratedMarkdownLines` використовує `collapseMultipleBlankLines`.
+- `collapseMultipleBlankLines` і `expandMustacheSection` — незалежні низькорівневі будівельні блоки.
+
+### Runtime
+
+- ECMAScript із підтримкою:
+  - `String.prototype.replaceAll` (Node.js ≥ 15);
+  - класичних `String.prototype.indexOf`, `slice`, `split`, `join`, `trim`, `endsWith`;
+  - синтаксису ESM (`export function`).
+
+## Потік виконання / Використання
+
+Типовий потік генерації `AGENTS.md`:
+
+1. Викликач (CLI `n-cursor`) читає шаблон `AGENTS.template.md` з файлової системи.
+2. Збирає три масиви даних:
+   - список `*.mdc`-файлів із `.cursor/rules` (через `fs.readdir` або еквівалент);
+   - метадані скілів (`name` уже з bullet/описом);
+   - метадані команд (`name` уже з bullet/описом).
+3. Викликає `renderAgentsTemplate(templateText, mdcBasenames, skillItems, commandItems)`.
+4. Записує отриманий рядок у файл `AGENTS.md` (наприклад, через `fs.writeFile`).
+
+Типовий потік генерації багаторядкового документа (наприклад, `CLAUDE.md`):
+
+1. Викликач формує масив рядків `lines` — заголовки, абзаци, bullet-и тощо. Між логічними секціями може лишатися кілька порожніх рядків.
+2. Викликає `formatGeneratedMarkdownLines(lines)` — отримує цілісний документ із чистими стиками секцій та фінальним `\n`.
+3. Записує результат у файл.
+
+Приклад використання `expandMustacheSection` ізольовано:
+
+```js
+import { expandMustacheSection } from './generated-markdown.mjs'
+
+const tpl = '# Rules\n{{#services}}- {{name}}\n{{/services}}\nEnd'
+const out = expandMustacheSection(tpl, 'services', [{ name: 'a.mdc' }, { name: 'b.mdc' }], 'name')
+// out === '# Rules\n- a.mdc\n- b.mdc\nEnd'
+```
+
+Приклад використання `collapseMultipleBlankLines`:
+
+```js
+import { collapseMultipleBlankLines } from './generated-markdown.mjs'
+
+const cleaned = collapseMultipleBlankLines('A\n\n\n\nB')
+// cleaned === 'A\n\nB'
+```
+
+Приклад використання `formatGeneratedMarkdownLines`:
+
+```js
+import { formatGeneratedMarkdownLines } from './generated-markdown.mjs'
+
+const md = formatGeneratedMarkdownLines(['# Title', '', '', '', 'Body'])
+// md === '# Title\n\nBody\n'
+```
+
+## Rebuild Test
+
+Контрольний приклад для перевірки коректності модуля після рефакторингу:
+
+Дано шаблон:
+
+```text
+# Agents
+
+## Services
+{{#services}}
+{{name}}
+{{/services}}
+
+## Skills
+{{#skills}}
+{{name}}
+{{/skills}}
+
+## Commands
+{{#commands}}
+{{name}}
+{{/commands}}
+```
+
+і виклик:
+
+```js
+renderAgentsTemplate(template, ['n-bun.mdc', 'n-vue.mdc'], [{ name: '- /n-fix — fix' }], [{ name: '- /n-lint — lint' }])
+```
+
+Очікувані властивості результату:
+
+- секція `services` містить рядки `- .cursor/rules/n-bun.mdc` і `- .cursor/rules/n-vue.mdc`, розділені одним `\n`;
+- секція `skills` містить рядок `- /n-fix — fix`;
+- секція `commands` містить рядок `- /n-lint — lint`;
+- ніде немає трьох поспіль `\n` (тобто не зʼявляються два порожніх рядки підряд);
+- виклик `formatGeneratedMarkdownLines(result.split('\n'))` повертає той самий зміст із гарантованим завершальним `\n`.