@nitra/cursor 3.19.0 → 3.20.0

package/rules/text/lint/lint.mjs

@@ -1,6 +1,7 @@
 /**
- * CLI-обгортка над канонічним `lint-text` (text.mdc): preflight на `shellcheck`, `patch`
- * (для авто-фіксу shellcheck) і `dotenv-linter`; далі послідовно
+ * CLI-обгортка над канонічним `lint-text` (text.mdc): авто-встановлює `shellcheck` і `dotenv-linter`
+ * через `ensureTool` (brew/scoop/GitHub Release per-platform), перевіряє наявність `patch`
+ * (для авто-фіксу shellcheck); далі послідовно
  *   1) `cspell .` — перевірка правопису з `@nitra/cspell-dict`;
  *   2) `runShellcheckText()` — авто-фікс і фінальна перевірка `*.sh` через `shellcheck`;
  *   3) `runDotenvLinter()` — авто-фікс і фінальна перевірка `.env*` через `dotenv-linter`;
@@ -9,7 +10,7 @@
  *
  * Без preflight локальний прогін може пройти cspell/markdownlint, а CI на ubuntu-latest
  * (де shellcheck передвстановлений, але dotenv-linter — ні) падає на кроці dotenv-linter
- * з неінформативним повідомленням. Preflight збирає всі відсутні бінарники до першого кроку.
+ * з неінформативним повідомленням. ensureTool збирає всі відсутні бінарники до першого кроку.
  *
  * Перший ненульовий код з ланцюжка повертається як код виходу; наступні кроки не запускаються.
  * Експортовано як `runLintTextCli` — використовується з `bin/n-cursor.js` як підкоманда `lint-text`.
@@ -22,6 +23,7 @@ import { platform } from 'node:process'
 import { runLintStep } from '../../../scripts/lib/run-lint-step.mjs'
 import { resolveCmd } from '../../../scripts/utils/resolve-cmd.mjs'
 import { runStandardLint } from '../../../scripts/lib/run-standard-lint.mjs'
+import { ensureTool } from '../../../scripts/lib/ensure-tool.mjs'
 import { runDotenvLinter } from './run-dotenv-linter.mjs'
 import { runShellcheckText } from './run-shellcheck.mjs'
 import { runV8rWithGlobs } from './run-v8r.mjs'
@@ -36,22 +38,6 @@ import { runV8rWithGlobs } from './run-v8r.mjs'
  * @property {string} successMsg повідомлення на pass-шлях
  */
 
-/** @type {PreflightDep} */
-const SHELLCHECK_PREFLIGHT = {
-  bin: 'shellcheck',
-  winBins: ['shellcheck.exe'],
-  explanation: [
-    'Без нього `runShellcheckText()` пропускає перевірку tracked `*.sh` — локально lint-text',
-    'може бути зеленим, а CI (shellcheck + patch) падає на тих самих скриптах.'
-  ].join('\n   '),
-  install: [
-    'macOS:         brew install shellcheck',
-    'Debian/Ubuntu: sudo apt-get install -y shellcheck',
-    'Arch:          sudo pacman -S shellcheck'
-  ],
-  successMsg: '✅ shellcheck знайдено в PATH — lint-text перевірить *.sh'
-}
-
 /** @type {PreflightDep} */
 const PATCH_PREFLIGHT = {
   bin: 'patch',
@@ -62,22 +48,6 @@ const PATCH_PREFLIGHT = {
   successMsg: '✅ patch знайдено в PATH — shellcheck auto-fix працюватиме'
 }
 
-/** @type {PreflightDep} */
-const DOTENV_LINTER_PREFLIGHT = {
-  bin: 'dotenv-linter',
-  winBins: ['dotenv-linter.exe'],
-  explanation: [
-    'Без нього не виконається крок `.env*` у lint-text — локально cspell/markdownlint',
-    'пройдуть, а CI без Install dotenv-linter впаде неінформативно.'
-  ].join('\n   '),
-  install: [
-    'macOS:     brew install dotenv-linter',
-    'Linux:     curl -sSfL https://git.io/JLbXn | sh -s -- -b /usr/local/bin',
-    'cargo:     cargo install dotenv-linter'
-  ],
-  successMsg: '✅ dotenv-linter знайдено в PATH — lint-text перевірить .env*'
-}
-
 /**
  * Шукає шлях до бінарника `dep.bin` у `PATH`; на Windows додатково перебирає `dep.winBins`.
  * @param {PreflightDep} dep опис залежності з canon-списку preflight-перевірок
@@ -128,11 +98,12 @@ function preflight(dep) {
  * @returns {number} 0 — все OK, інакше — код першого кроку, що впав
  */
 function runLintTextSteps() {
-  let preflightOk = true
-  for (const dep of [SHELLCHECK_PREFLIGHT, PATCH_PREFLIGHT, DOTENV_LINTER_PREFLIGHT]) {
-    if (!preflight(dep)) preflightOk = false
-  }
-  if (!preflightOk) return 1
+  // Auto-install: throws on failure → propagates as exit 1 from runStandardLint
+  ensureTool('shellcheck')
+  ensureTool('dotenv-linter')
+
+  // patch is hint-only (system tool)
+  if (!preflight(PATCH_PREFLIGHT)) return 1
 
   const cspellCode = runLintStep('cspell', 'npx', ['cspell', '.'])
   if (cspellCode !== 0) return cspellCode

package/rules/worktree/policy/vscode_settings/target.json

@@ -0,0 +1,5 @@
+{
+  "$schema": "https://unpkg.com/@nitra/cursor/schemas/target.json",
+  "check": "template",
+  "files": { "single": ".vscode/settings.json" }
+}

package/rules/worktree/policy/vscode_settings/template/settings.json.snippet.json

@@ -0,0 +1,8 @@
+{
+  "search.exclude": {
+    "**/.worktrees/**": true
+  },
+  "files.exclude": {
+    "**/.worktrees/**": true
+  }
+}

package/rules/worktree/policy/zed_settings/target.json

@@ -0,0 +1,5 @@
+{
+  "$schema": "https://unpkg.com/@nitra/cursor/schemas/target.json",
+  "check": "template",
+  "files": { "single": ".zed/settings.json" }
+}

package/rules/worktree/policy/zed_settings/template/settings.json.snippet.json

@@ -0,0 +1,12 @@
+{
+  "file_scan_exclusions": [
+    "**/.git",
+    "**/.svn",
+    "**/.hg",
+    "**/.DS_Store",
+    "**/Thumbs.db",
+    "**/node_modules",
+    "**/.worktrees",
+    "**/.claude/worktrees"
+  ]
+}

package/rules/worktree/worktree.mdc

@@ -20,6 +20,58 @@ alwaysApply: true
 Слеш у гілці перетворюється на дефіс: `feat/skill-meta` → `.worktrees/feat-skill-meta/`.
 Git-гілка лишається з оригінальним імʼям (`feat/skill-meta`).
 
+## Налаштування редакторів
+
+Worktree-каталоги — це вкладені копії всього дерева. Якщо редактор індексує їх,
+пошук дає дублі, а file-watcher вантажить диск. Тому редактор має **виключити**
+`.worktrees/` (а для Zed ще й приватний `.claude/worktrees/`) з пошуку та сканування.
+
+Канон перевіряється **лише** якщо файл налаштувань уже є — проєктам без VS Code / Zed
+нічого не нав'язується.
+
+### VS Code
+
+У `.vscode/settings.json` обовʼязково виключи `**/.worktrees/**` з пошуку і з дерева
+файлів. `node_modules` додавати не треба — VS Code виключає його з пошуку дефолтно.
+
+```json title=".vscode/settings.json"
+{
+  "search.exclude": {
+    "**/.worktrees/**": true
+  },
+  "files.exclude": {
+    "**/.worktrees/**": true
+  }
+}
+```
+
+Канон (subset — інші ключі дозволені): [settings.json.snippet.json](./policy/vscode_settings/template/settings.json.snippet.json)
+
+### Zed
+
+Zed **замінює** масив `file_scan_exclusions` цілком (не зливає з дефолтами), тому в
+`.zed/settings.json` перелічуй і дефолти Zed, і `**/.worktrees`, і `**/.claude/worktrees`.
+Перевірка вимагає **всі** записи канону (бо інакше дефолти губляться).
+
+```json title=".zed/settings.json"
+{
+  "file_scan_exclusions": [
+    "**/.git",
+    "**/.svn",
+    "**/.hg",
+    "**/.DS_Store",
+    "**/Thumbs.db",
+    "**/node_modules",
+    "**/.worktrees",
+    "**/.claude/worktrees"
+  ]
+}
+```
+
+Канон (усі елементи обовʼязкові, зайві дозволені): [settings.json.snippet.json](./policy/zed_settings/template/settings.json.snippet.json)
+
+`.zed/settings.json` без стабільної схеми в Schema Store — додай його до `.v8rignore` (як `.vscode/*`, див. **text.mdc**).
+
 ## Команди
 
 - **Створити** (опис обовʼязковий): `npx @nitra/cursor worktree add <branch> "<навіщо>"`

package/schemas/target.json

@@ -12,6 +12,11 @@
       "format": "uri",
       "description": "Опційне посилання на JSON Schema для IDE-валідації; очікувано https://unpkg.com/@nitra/cursor/schemas/target.json"
     },
+    "check": {
+      "type": "string",
+      "enum": ["template"],
+      "description": "Режим перевірки концерну. 'template' → без власного <name>.rego: канон зі template/<target>.snippet|deny|contains.<ext> звіряється generic deep-subset-ом (checkSnippet/checkDeny/checkContains/checkTextSubset). Сніпет — єдине джерело істини: його зміна одразу змінює enforce, без правок rego й міграторів. Без поля → класичний rego-режим (пара з <name>.rego)."
+    },
     "files": {
       "oneOf": [
         {

package/scripts/lib/assert-project-root.mjs

@@ -0,0 +1,74 @@
+/**
+ * Guard для дефолтної синхронізації `npx @nitra/cursor` (гілка без підкоманди).
+ *
+ * Дефолтний sync (`runSync` у `bin/n-cursor.js`) скаффолдить у `cwd()` керовані
+ * артефакти — `.cursor/rules/`, `.cursor/skills/`, `.claude/`, `AGENTS.md`,
+ * `CLAUDE.md`, `.n-cursor.json`, `.gitignore` — і запускає `bun install`. Усе це
+ * розраховане на **корінь** проєкту-споживача. Якщо бінар викликати напряму
+ * (`bun npm/bin/n-cursor.js`, `node …/n-cursor.js`) з піддиректорії git-репо,
+ * `cwd()` — та піддиректорія, і конфіг розкидається не туди.
+ *
+ * `bun run start`/`npm start` цей кейс не створює (менеджер скидає cwd на корінь
+ * пакета), але прямий виклик бінаря — створює. Тому guard прив'язаний до
+ * **git-кореня**, а не до конкретного монорепо: CLI публічний і легітимно
+ * запускається в корені будь-якого репо-споживача.
+ */
+import { spawnSync } from 'node:child_process'
+import { realpathSync } from 'node:fs'
+import { cwd } from 'node:process'
+
+/**
+ * Корінь git-репозиторію для `dir` через `git rev-parse --show-toplevel`.
+ * Повертає realpath-шлях кореня або `null`, якщо `dir` поза git-репо чи `git`
+ * недоступний — у такому разі визначити корінь неможливо, тож не блокуємо.
+ * @param {string} [dir] каталог, з якого питаємо git
+ * @returns {string | null} абсолютний (realpath) корінь репо або null
+ */
+export function gitToplevel(dir = cwd()) {
+  const res = spawnSync('git', ['rev-parse', '--show-toplevel'], { cwd: dir, encoding: 'utf8' })
+  if (res.status !== 0 || typeof res.stdout !== 'string') return null
+  const top = res.stdout.trim()
+  return top.length > 0 ? top : null
+}
+
+/**
+ * Безпечний realpath: повертає реальний шлях `dir`, а якщо його не існує —
+ * сам `dir` без змін (порівняння нижче все одно дасть коректний результат).
+ * Потрібен бо `git rev-parse --show-toplevel` віддає realpath (symlink'и
+ * розгорнуті), а `cwd()` — ні; без нормалізації корінь під symlink-шляхом
+ * (типово `/var` → `/private/var` на macOS) хибно вважався б піддиректорією.
+ * @param {string} dir шлях для нормалізації
+ * @returns {string} realpath або вихідний шлях
+ */
+function safeRealpath(dir) {
+  try {
+    return realpathSync(dir)
+  } catch {
+    return dir
+  }
+}
+
+/**
+ * Кидає помилку, якщо `dir` — піддиректорія git-репозиторію (тобто не його
+ * корінь). Поза git-репо (немає toplevel) — пропускає без помилки.
+ *
+ * Викликати лише перед дефолтним sync (до перших мутацій файлів), не для
+ * підкоманд із власним `--root` чи read-only-логікою.
+ * @param {string} [dir] каталог, що перевіряємо (типово `cwd()`)
+ * @throws {Error} коли `dir` всередині git-репо, але не його корінь
+ * @returns {void}
+ */
+export function assertCwdIsProjectRoot(dir = cwd()) {
+  const top = gitToplevel(dir)
+  if (top === null) return
+  const here = safeRealpath(dir)
+  if (here === top) return
+  throw new Error(
+    `❌ @nitra/cursor запущено не в корені проєкту.\n` +
+      `   Поточний каталог: ${here}\n` +
+      `   Корінь git-репо:  ${top}\n` +
+      `   Дефолтна синхронізація скаффолдить .cursor/, .claude/, CLAUDE.md, .n-cursor.json\n` +
+      `   і робить bun install у поточному каталозі — із піддиректорії це розкидало б\n` +
+      `   конфіг не туди. Перейдіть у корінь репозиторію: cd ${top}`
+  )
+}

package/scripts/lib/ensure-tool.mjs

@@ -0,0 +1,352 @@
+/**
+ * Авто-встановлення зовнішніх CLI-залежностей пакету `@nitra/cursor`.
+ *
+ * `ensureTool(toolId)` — єдиний seam резолву зовнішніх бінарників: PATH → кеш → авто-install → hard-fail.
+ * Новий тул = один запис у реєстрі `TOOLS`, без дублювання install-логіки в кожному `lint.mjs`/`fix.mjs`.
+ *
+ * Per-platform matrix: macOS → brew, Windows → scoop (fallback: GitHub Release), Linux → GitHub Release binary.
+ * Бінарники кешуються у `~/.cache/@nitra/cursor/bin/` (Linux/Mac), `%LOCALAPPDATA%\@nitra\cursor\bin\` (Win).
+ *
+ * `ensureHkInstall(hkBin)` — реєструє git pre-commit hook через `hk install`; пропускається в CI.
+ */
+import { spawnSync } from 'node:child_process'
+import { chmodSync, existsSync, mkdirSync, renameSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+import { arch, env, platform } from 'node:process'
+
+import { resolveCmd } from '../utils/resolve-cmd.mjs'
+
+/** Префікс `v` у git-тегу релізу (`v1.2.3` → `1.2.3`). */
+const TAG_V_PREFIX_RE = /^v/
+
+/**
+ * Повертає каталог керованого кешу бінарників для поточного OS.
+ * @returns {string} абсолютний шлях
+ */
+function getCacheDir() {
+  if (platform === 'win32') {
+    const localAppData = env['LOCALAPPDATA'] ?? join(homedir(), 'AppData', 'Local')
+    return join(localAppData, '@nitra', 'cursor', 'bin')
+  }
+  return join(homedir(), '.cache', '@nitra', 'cursor', 'bin')
+}
+
+/**
+ * Мапить `process.arch` у формат, що вживається в назвах GitHub-release ресурсів.
+ * @param {'x64'|'arm64'|string} nodeArch значення `process.arch`
+ * @param {'hk'|'conftest'|'actionlint'} style стиль іменування платформи
+ * @returns {string} рядок архітектури для asset-шаблону
+ */
+function mapArch(nodeArch, style) {
+  if (style === 'actionlint') {
+    return nodeArch === 'x64' ? 'amd64' : 'arm64'
+  }
+  if (style === 'conftest') {
+    return nodeArch === 'x64' ? 'x86_64' : 'arm64'
+  }
+  // hk / shellcheck / dotenv-linter: x64 → x86_64, arm64 → aarch64
+  return nodeArch === 'x64' ? 'x86_64' : 'aarch64'
+}
+
+/**
+ * @typedef {object} ToolEntry
+ * @property {string} brew формула brew (macOS)
+ * @property {string|null} scoop назва пакету scoop (Windows); null = недоступний
+ * @property {string} github репо у форматі `owner/repo`
+ * @property {(ver: string) => string} asset повертає назву release-ресурсу для Linux
+ * @property {string} archStyle стиль маппінгу архітектури: 'hk'|'conftest'|'actionlint'
+ * @property {boolean} [archive] чи є release-ресурс архівом (tar) — default `true`; `false` = сирий бінарник (download + chmod)
+ * @property {((ver: string) => string)|null} [binFinder] для архівів де бінарник не у корені; повертає відносний шлях
+ */
+
+/** @type {Record<string, ToolEntry>} */
+const TOOLS = {
+  hk: {
+    brew: 'hk',
+    scoop: 'hk',
+    github: 'jdx/hk',
+    archStyle: 'hk',
+    asset: _ver => `hk-${mapArch(arch, 'hk')}-unknown-linux-gnu.tar.gz`,
+    binFinder: null
+  },
+  conftest: {
+    brew: 'conftest',
+    scoop: 'conftest',
+    github: 'open-policy-agent/conftest',
+    archStyle: 'conftest',
+    asset: ver => `conftest_${ver}_Linux_${mapArch(arch, 'conftest')}.tar.gz`,
+    binFinder: null
+  },
+  shellcheck: {
+    brew: 'shellcheck',
+    scoop: 'shellcheck',
+    github: 'koalaman/shellcheck',
+    archStyle: 'hk',
+    asset: ver => `shellcheck-v${ver}.linux.${mapArch(arch, 'hk')}.tar.xz`,
+    binFinder: ver => `shellcheck-v${ver}/shellcheck`
+  },
+  actionlint: {
+    brew: 'actionlint',
+    scoop: 'actionlint',
+    github: 'rhysd/actionlint',
+    archStyle: 'actionlint',
+    asset: ver => `actionlint_${ver}_linux_${mapArch(arch, 'actionlint')}.tar.gz`,
+    binFinder: null
+  },
+  'dotenv-linter': {
+    brew: 'dotenv-linter',
+    scoop: null,
+    github: 'dotenv-linter/dotenv-linter',
+    archStyle: 'hk',
+    asset: _ver => `dotenv-linter-linux-${mapArch(arch, 'hk')}.tar.gz`,
+    binFinder: null
+  },
+  opa: {
+    brew: 'opa',
+    scoop: 'opa',
+    github: 'open-policy-agent/opa',
+    archStyle: 'actionlint',
+    archive: false,
+    asset: _ver => `opa_linux_${mapArch(arch, 'actionlint')}`,
+    binFinder: null
+  },
+  regal: {
+    brew: 'regal',
+    scoop: null,
+    github: 'StyraInc/regal',
+    archStyle: 'conftest',
+    archive: false,
+    asset: _ver => `regal_Linux_${mapArch(arch, 'conftest')}`,
+    binFinder: null
+  },
+  hadolint: {
+    brew: 'hadolint',
+    scoop: 'hadolint',
+    github: 'hadolint/hadolint',
+    archStyle: 'conftest',
+    archive: false,
+    asset: _ver => `hadolint-linux-${mapArch(arch, 'conftest')}`,
+    binFinder: null
+  },
+  kubeconform: {
+    brew: 'kubeconform',
+    scoop: 'kubeconform',
+    github: 'yannh/kubeconform',
+    archStyle: 'actionlint',
+    asset: _ver => `kubeconform-linux-${mapArch(arch, 'actionlint')}.tar.gz`,
+    binFinder: null
+  },
+  kubescape: {
+    brew: 'kubescape',
+    scoop: 'kubescape',
+    github: 'kubescape/kubescape',
+    archStyle: 'actionlint',
+    archive: false,
+    asset: ver => `kubescape_${ver}_linux_${mapArch(arch, 'actionlint')}`,
+    binFinder: null
+  }
+}
+
+/**
+ * Отримує останній тег з GitHub Releases API через curl (sync).
+ * @param {string} repo репо у форматі `owner/repo`
+ * @param {string} curlBin абсолютний шлях до curl
+ * @returns {string} рядок версії без префікса `v`, наприклад `0.4.1`
+ */
+function fetchLatestVersion(repo, curlBin) {
+  const url = `https://api.github.com/repos/${repo}/releases/latest`
+  const r = spawnSync(curlBin, ['-sSL', '-H', 'Accept: application/vnd.github+json', url], { encoding: 'utf8' })
+  if (r.error) throw new Error(`curl failed: ${r.error.message}`)
+  if (r.status !== 0) throw new Error(`curl exit ${r.status}: ${(r.stderr ?? '').slice(0, 300)}`)
+  let parsed
+  try {
+    parsed = JSON.parse(r.stdout)
+  } catch {
+    throw new Error(`GitHub API response is not JSON: ${r.stdout.slice(0, 200)}`)
+  }
+  const tag = parsed['tag_name']
+  if (!tag) throw new Error(`GitHub API: tag_name missing for ${repo}`)
+  return tag.replace(TAG_V_PREFIX_RE, '')
+}
+
+/**
+ * Завантажує та розпаковує GitHub Release бінарник у кеш-директорію.
+ * Повертає абсолютний шлях до бінарника.
+ * @param {string} toolId ключ у TOOLS
+ * @param {ToolEntry} entry опис тула
+ * @param {string} cacheDir абсолютний шлях до кешу
+ * @returns {string} абсолютний шлях до готового бінарника
+ */
+function installFromGithub(toolId, entry, cacheDir) {
+  const curlBin = resolveCmd('curl')
+  if (!curlBin) throw new Error(`curl не знайдено в PATH — потрібен для завантаження ${toolId}`)
+  const tarBin = resolveCmd('tar')
+  if (!tarBin) throw new Error(`tar не знайдено в PATH — потрібен для встановлення ${toolId}`)
+
+  const ver = fetchLatestVersion(entry.github, curlBin)
+  const assetName = entry.asset(ver)
+  const downloadUrl = `https://github.com/${entry.github}/releases/download/v${ver}/${assetName}`
+
+  mkdirSync(cacheDir, { recursive: true })
+  const archivePath = join(cacheDir, assetName)
+
+  const dlResult = spawnSync(curlBin, ['-sSL', '-o', archivePath, downloadUrl], { encoding: 'utf8' })
+  if (dlResult.error) throw new Error(`Завантаження ${toolId} не вдалось: ${dlResult.error.message}`)
+  if (dlResult.status !== 0)
+    throw new Error(`curl exit ${dlResult.status} при завантаженні ${toolId}: ${(dlResult.stderr ?? '').slice(0, 300)}`)
+
+  // Сирий бінарник (archive: false) — завантажений файл і є бінарником: перейменовуємо у <toolId> + chmod.
+  if (entry.archive === false) {
+    const binPath = join(cacheDir, toolId)
+    renameSync(archivePath, binPath)
+    chmodSync(binPath, 0o755)
+    return binPath
+  }
+
+  // .tar.xz потребує -J замість -z
+  const isXz = assetName.endsWith('.tar.xz')
+  const tarFlags = isXz ? ['-xJf'] : ['-xzf']
+  const extractResult = spawnSync(tarBin, [...tarFlags, archivePath, '-C', cacheDir], { encoding: 'utf8' })
+  if (extractResult.error) throw new Error(`tar failed for ${toolId}: ${extractResult.error.message}`)
+  if (extractResult.status !== 0)
+    throw new Error(`tar exit ${extractResult.status} для ${toolId}: ${(extractResult.stderr ?? '').slice(0, 300)}`)
+
+  const binRelPath = entry.binFinder ? entry.binFinder(ver) : toolId
+  const binPath = join(cacheDir, binRelPath)
+  if (!existsSync(binPath)) {
+    throw new Error(`Бінарник ${toolId} не знайдено після розпакування: ${binPath}`)
+  }
+
+  const rmBin = resolveCmd('rm')
+  if (rmBin) spawnSync(rmBin, [archivePath])
+
+  return binPath
+}
+
+/**
+ * Встановлює тул через brew (macOS). Hard-fail на будь-яку помилку.
+ * @param {string} toolId ключ у TOOLS
+ * @param {ToolEntry} entry опис тула
+ * @returns {string} абсолютний шлях до встановленого бінарника
+ */
+function installViaBrew(toolId, entry) {
+  const brewBin = resolveCmd('brew')
+  if (!brewBin) throw new Error(`brew не знайдено в PATH. Встанови Homebrew: https://brew.sh`)
+  const r = spawnSync(brewBin, ['install', entry.brew], { stdio: 'inherit', encoding: 'utf8' })
+  if (r.error) throw new Error(`brew install ${toolId} не вдалось: ${r.error.message}`)
+  if (r.status !== 0) throw new Error(`brew install ${toolId} завершився з кодом ${r.status}`)
+  const resolved = resolveCmd(toolId)
+  if (!resolved) throw new Error(`${toolId} не знайдено в PATH після brew install`)
+  return resolved
+}
+
+/**
+ * Встановлює тул через scoop (Windows). Кидає якщо scoop недоступний або пакет null.
+ * @param {string} toolId ключ у TOOLS
+ * @param {ToolEntry} entry опис тула
+ * @returns {string} абсолютний шлях до встановленого бінарника
+ */
+function installViaScoop(toolId, entry) {
+  if (!entry.scoop) {
+    throw new Error(`${toolId} недоступний у Scoop. Встанови вручну:\n   https://github.com/${entry.github}/releases`)
+  }
+  const scoopBin = resolveCmd('scoop')
+  if (!scoopBin) throw new Error(`scoop не знайдено в PATH. Встанови Scoop: https://scoop.sh`)
+  const r = spawnSync(scoopBin, ['install', entry.scoop], { stdio: 'inherit', encoding: 'utf8' })
+  if (r.error) throw new Error(`scoop install ${toolId} не вдалось: ${r.error.message}`)
+  if (r.status !== 0) throw new Error(`scoop install ${toolId} завершився з кодом ${r.status}`)
+  const resolved = resolveCmd(toolId)
+  if (!resolved) throw new Error(`${toolId} не знайдено в PATH після scoop install`)
+  return resolved
+}
+
+/**
+ * Виконує авто-встановлення тула відповідно до поточного OS.
+ * @param {string} toolId ключ у TOOLS
+ * @param {ToolEntry} entry опис тула
+ * @param {string} cacheDir каталог кешу для Linux-бінарників
+ * @returns {string} абсолютний шлях до бінарника
+ */
+function autoInstall(toolId, entry, cacheDir) {
+  if (platform === 'darwin') return installViaBrew(toolId, entry)
+  if (platform === 'win32') {
+    try {
+      return installViaScoop(toolId, entry)
+    } catch {
+      // Scoop недоступний або тул не в Scoop → GitHub Release fallback
+      return installFromGithub(toolId, entry, cacheDir)
+    }
+  }
+  // Linux
+  return installFromGithub(toolId, entry, cacheDir)
+}
+
+/**
+ * Будує install-hint повідомлення для hard-fail.
+ * @param {string} toolId ключ у TOOLS
+ * @param {ToolEntry} entry опис тула
+ * @returns {string} рядок помилки з підказками
+ */
+function buildHint(toolId, entry) {
+  const lines = [
+    `❌ ${toolId} не знайдено в PATH і авто-встановлення відключено (N_CURSOR_NO_AUTO_INSTALL).`,
+    '   Встанови:'
+  ]
+  if (platform === 'darwin') {
+    lines.push(`     macOS: brew install ${entry.brew}`)
+  } else if (platform === 'win32') {
+    if (entry.scoop) lines.push(`     Windows: scoop install ${entry.scoop}`)
+    lines.push(`     або: https://github.com/${entry.github}/releases`)
+  } else {
+    lines.push(`     Linux: https://github.com/${entry.github}/releases`)
+  }
+  return lines.join('\n')
+}
+
+/**
+ * Резолвить і за необхідності авто-встановлює зовнішній CLI-тул.
+ *
+ * Порядок: PATH → кеш → авто-install (якщо не N_CURSOR_NO_AUTO_INSTALL) → hard-fail.
+ * Повертає абсолютний шлях або кидає Error.
+ * @param {string} toolId ключ у реєстрі TOOLS (`'hk'`, `'conftest'`, `'shellcheck'`, `'actionlint'`, `'dotenv-linter'`, `'opa'`, `'regal'`, `'hadolint'`, `'kubeconform'`, `'kubescape'`)
+ * @returns {string} абсолютний шлях до бінарника
+ */
+export function ensureTool(toolId) {
+  const entry = TOOLS[toolId]
+  if (!entry) throw new Error(`ensureTool: невідомий тул '${toolId}'`)
+
+  // 1. PATH
+  const fromPath = resolveCmd(toolId)
+  if (fromPath) return fromPath
+
+  // 2. Кеш
+  const cacheDir = getCacheDir()
+  const cachedBin = join(cacheDir, toolId)
+  if (existsSync(cachedBin)) return cachedBin
+
+  // 3. Авто-install (якщо не заблоковано)
+  if (!env['N_CURSOR_NO_AUTO_INSTALL']) {
+    return autoInstall(toolId, entry, cacheDir)
+  }
+
+  // 4. Hard-fail з per-OS підказкою
+  throw new Error(buildHint(toolId, entry))
+}
+
+/**
+ * Реєструє git pre-commit hook через `hk install`.
+ * Пропускається в CI (`process.env.CI`). Попереджає (не кидає) на помилку.
+ * @param {string} hkBin абсолютний шлях до бінарника hk
+ * @returns {void}
+ */
+export function ensureHkInstall(hkBin) {
+  if (env['CI']) return
+
+  const r = spawnSync(hkBin, ['install'], { stdio: 'inherit', encoding: 'utf8' })
+  if (r.error) {
+    console.warn(`⚠️ hk install не вдалось: ${r.error.message}`)
+  } else if (r.status !== 0) {
+    console.warn(`⚠️ hk install завершився з кодом ${r.status}`)
+  }
+}