@nitra/cursor 3.21.1 → 3.23.0

package/scripts/lib/docs/discover-checkable-rules.md

@@ -0,0 +1,165 @@
+# discover-checkable-rules.mjs
+
+## Огляд
+
+Модуль `discover-checkable-rules.mjs` — це discovery-шар для CLI-команди `fix`. Його завдання — швидко просканувати файлову структуру каталогу `npm/rules/` та виявити «прогонні» правила, тобто правила, у яких є щонайменше один JS-концерн або policy-концерн. Правила, які складаються тільки з декларативних артефактів (`.mdc` + `auto.md`) без жодного прогонного концерну, відсіюються.
+
+Виокремлюються два типи концернів:
+
+- **JS concerns** — окремі файли `rules/<id>/js/<concern>.mjs`. Кожен файл — один концерн (flat-конвенція).
+- **Policy concerns** — підкаталоги `rules/<id>/policy/<concern>/`, у яких присутній файл `target.json` (поруч із якого зазвичай лежить `<concern>.rego`).
+
+Модуль свідомо не парсить вміст `target.json` і не читає JS-файли — це лише швидкий «структурний» скан (шляхи + назви) без I/O-вмісту. Парсинг покладено на runner.
+
+Файли-помічники з префіксом `_` (зокрема каталог `_lib/`), тестові файли `*.test.mjs`, а також приховані файли/каталоги (`.`-префікс) ігноруються.
+
+Історичний контекст конвенції розкладки JS-концернів:
+
+- `js/<concern>/check.mjs` — версії 1.13.80–1.13.89 (вкладений каталог на концерн);
+- `js/<concern>.mjs` — версії 1.13.90+ (flat: концерн = файл, а не каталог).
+
+Допоміжні файли, тести, шаблони й дані винесені в окремі топ-level папки правила: `js/_lib/`, `tests/`, `templates/`, `data/`.
+
+## Експорти / API
+
+Модуль експортує дві асинхронні функції:
+
+| Експорт                                   | Тип                                                | Призначення                                                                                    |
+| ----------------------------------------- | -------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
+| `discoverOneRule(ruleDir, ruleId)`        | `async (string, string) => Promise<CheckableRule>` | Будує опис одного правила за заданим шляхом каталогу та id, без обходу `rules/`.               |
+| `discoverCheckableRules(bundledRulesDir)` | `async (string) => Promise<CheckableRule[]>`       | Сканує цілий каталог `npm/rules/` і повертає масив правил, для яких є JS- або policy-концерни. |
+
+Внутрішніми (не експортованими) залишаються функції `listJsConcerns` і `listPolicyConcerns`.
+
+### Типи (JSDoc `@typedef`)
+
+```text
+JsConcern        { name: string }                                  // basename файла js/<name>.mjs без розширення
+PolicyConcern    { name: string }                                  // imʼя підкаталогу policy/<name>/
+CheckableRule    {
+                   id: string,                                     // = basename каталогу rules/<id>/
+                   jsConcerns: JsConcern[],                        // алфавітно
+                   policyConcerns: PolicyConcern[],                // алфавітно
+                 }
+```
+
+## Функції
+
+### `listJsConcerns(jsDir)` (internal)
+
+- **Сигнатура:** `async function listJsConcerns(jsDir: string): Promise<JsConcern[]>`
+- **Параметри:**
+  - `jsDir` — абсолютний шлях до каталогу `rules/<id>/js/`.
+- **Повертає:** масив `JsConcern[]`, відсортований алфавітно за `name` через `Array.prototype.toSorted` із компаратором `localeCompare`.
+- **Логіка:**
+  1. Якщо каталог `jsDir` не існує (`existsSync` повертає `false`) — повертається `[]`.
+  2. Читається вміст через `readdir(jsDir, { withFileTypes: true })` — тобто отримуються `Dirent`-обʼєкти з метаінформацією.
+  3. Пропускаються:
+     - сутності, що не є файлом (`!entry.isFile()`);
+     - файли без розширення `.mjs`;
+     - тестові файли `*.test.mjs`;
+     - службові файли з префіксом `_` (наприклад вміст `_lib/`, хоча сам `_lib` як каталог не буде файлом і відсіється раніше);
+     - приховані файли з префіксом `.`.
+  4. Для решти файлів обчислюється `name = entry.name.slice(0, -'.mjs'.length)` — basename без розширення.
+- **Side effects:** лише файлові читання (`existsSync`, `readdir`), без запису.
+
+### `listPolicyConcerns(policyDir)` (internal)
+
+- **Сигнатура:** `async function listPolicyConcerns(policyDir: string): Promise<PolicyConcern[]>`
+- **Параметри:**
+  - `policyDir` — абсолютний шлях до каталогу `rules/<id>/policy/`.
+- **Повертає:** масив `PolicyConcern[]`, відсортований алфавітно за `name`.
+- **Логіка:**
+  1. Якщо `policyDir` не існує — повертається `[]`.
+  2. Читається вміст з `withFileTypes: true`.
+  3. Пропускаються будь-які записи, що не є каталогом, а також приховані каталоги (префікс `.`).
+  4. Для кожного підкаталогу перевіряється наявність файла `target.json` через `existsSync(join(policyDir, entry.name, 'target.json'))`. Якщо `target.json` є — підкаталог зараховується як policy-концерн.
+- **Side effects:** лише файлові читання, без запису.
+
+### `discoverOneRule(ruleDir, ruleId)` (exported)
+
+- **Сигнатура:** `export async function discoverOneRule(ruleDir: string, ruleId: string): Promise<CheckableRule>`
+- **Параметри:**
+  - `ruleDir` — абсолютний шлях до каталогу правила `rules/<id>/`;
+  - `ruleId` — ідентифікатор правила, зазвичай `basename(ruleDir)`. Передається явно, бо функція не виводить його з шляху самостійно.
+- **Повертає:** обʼєкт `CheckableRule` з полями `id`, `jsConcerns`, `policyConcerns`. На відміну від `discoverCheckableRules`, тут не виконується фільтрація «має бути хоч щось» — повертається опис як є (можуть бути порожні масиви концернів).
+- **Логіка:** паралельно (точніше — послідовно `await`-ить) запускає `listJsConcerns(join(ruleDir, 'js'))` і `listPolicyConcerns(join(ruleDir, 'policy'))` та збирає результати в обʼєкт.
+- **Використання:** викликається `runStandardRule`-flow для per-rule entry-point, коли потрібно отримати опис конкретного правила, а не сканувати весь каталог.
+- **Side effects:** лише читання файлової системи.
+
+### `discoverCheckableRules(bundledRulesDir)` (exported)
+
+- **Сигнатура:** `export async function discoverCheckableRules(bundledRulesDir: string): Promise<CheckableRule[]>`
+- **Параметри:**
+  - `bundledRulesDir` — абсолютний шлях до кореневого каталогу всіх правил (зазвичай `npm/rules/`).
+- **Повертає:** масив `CheckableRule[]`, відсортований алфавітно за `id`. Включаються тільки правила, у яких `jsConcerns.length > 0 || policyConcerns.length > 0`.
+- **Логіка:**
+  1. Якщо `bundledRulesDir` не існує — повертається `[]`.
+  2. Читається вміст каталогу з `withFileTypes: true`.
+  3. Пропускаються сутності, які не є каталогом, та приховані каталоги (префікс `.`).
+  4. Для кожного підкаталогу формується `ruleDir = join(bundledRulesDir, entry.name)` і викликається `discoverOneRule(ruleDir, entry.name)`.
+  5. Правила, у яких немає жодного JS- або policy-концерну (декларативні-only), відсіюються.
+- **Side effects:** лише читання файлової системи (без запису, без мережевих викликів).
+
+## Залежності
+
+Виключно зовнішні стандартні модулі Node.js:
+
+- `node:fs` → `existsSync` — синхронна перевірка існування шляху;
+- `node:fs/promises` → `readdir` — асинхронне читання вмісту каталогу (з `withFileTypes: true` повертає `Dirent[]`);
+- `node:path` → `join` — кросплатформова конкатенація шляхів.
+
+Внутрішніх імпортів з інших модулів проєкту немає. Це робить модуль чистим discovery-шаром без бізнес-логіки, що дозволяє безпечно його тестувати ізольовано (потрібна лише підготовлена файлова структура у тимчасовому каталозі).
+
+Зворотні залежності (хто використовує цей модуль): runner-флоу CLI `fix` (зокрема `runStandardRule`), який після discovery читає `target.json` для policy-концернів і виконує JS-концерни.
+
+## Потік виконання / Використання
+
+### Типовий сценарій 1. Повний скан правил для CLI `fix`
+
+```javascript
+import { discoverCheckableRules } from './discover-checkable-rules.mjs'
+
+const rules = await discoverCheckableRules('/abs/path/to/npm/rules')
+for (const rule of rules) {
+  // rule.id, rule.jsConcerns, rule.policyConcerns
+}
+```
+
+Послідовність дій усередині:
+
+1. `discoverCheckableRules` перевіряє існування кореневого каталогу.
+2. Перебирає підкаталоги верхнього рівня (= потенційні правила).
+3. Для кожного підкаталогу викликає `discoverOneRule`, який своєю чергою:
+   - сканує `rules/<id>/js/` через `listJsConcerns`;
+   - сканує `rules/<id>/policy/` через `listPolicyConcerns`;
+4. Якщо знайдено хоч один концерн — правило додається у вихідний масив.
+5. Масив сортується за `id`.
+
+### Типовий сценарій 2. Per-rule entry-point
+
+```javascript
+import { discoverOneRule } from './discover-checkable-rules.mjs'
+
+const rule = await discoverOneRule('/abs/path/to/npm/rules/n-js-lint', 'n-js-lint')
+// rule.id === 'n-js-lint'
+// rule.jsConcerns — список JS-концернів у js/
+// rule.policyConcerns — список policy-концернів у policy/
+```
+
+Цей шлях оминає енумерацію всього `rules/`, що корисно коли id правила вже відомий (наприклад, передано аргументом CLI).
+
+### Гарантії та обмеження
+
+- **Чистота:** функції — read-only (не пишуть у ФС, не виконують код концернів). Це дозволяє безпечно викликати їх повторно.
+- **Сортування:** усі результати алфавітно відсортовані через `toSorted` із `localeCompare`. Це робить вивід детермінованим між запусками й між платформами (хоч порядок `readdir` залежить від ФС).
+- **Толерантність до відсутніх каталогів:** будь-яка з директорій (`rules/`, `js/`, `policy/`) може бути відсутня — повертається порожній масив без помилки.
+- **Тести/хелпери:** файли з префіксом `_` і `*.test.mjs` гарантовано виключаються із JS-концернів.
+- **Що _не_ робиться:** не валідуються імена концернів, не парситься `target.json`, не перевіряється наявність `<name>.rego` поруч із `target.json`. Це робота runner-а.
+
+### Eage cases
+
+- Файл з префіксом `.` у `js/` — пропускається.
+- Підкаталог у `js/` (наприклад `_lib/`) — не є файлом, відсіюється першою перевіркою `entry.isFile()`.
+- Підкаталог у `policy/` без `target.json` — пропускається; наявність `<name>.rego` без `target.json` не зараховується.
+- Порожнє правило (тільки `.mdc`/`auto.md` без `js/` і `policy/`) — не потрапляє у вихід `discoverCheckableRules`, але буде повернене з порожніми масивами в `discoverOneRule`.

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` доступний.