@nitra/cursor 3.18.2 → 3.20.0

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}`)
+  }
+}

package/scripts/lib/run-conftest-batch.mjs

@@ -4,15 +4,13 @@
  * пер-документні правила винесені у `npm/policy/<rule>/<name>/` як rego-полісі
  * (Rego-authoritative). JS у `check-*.mjs` робить cross-file частину (walking
  * дерева, парність, kustomize-резолюція), а пер-документне валідаційне ядро
- * делегується сюди — один спавн `conftest` на (`namespace`, `policyDir`),
+ * делегується сюді — один спавн `conftest` на (`namespace`, `policyDir`),
  * незалежно від кількості файлів. Це закриває дублювання JS↔rego і прибирає
  * ризик дрифту (типу `spec.config` vs `spec.default.config` у
  * `health_check_policy.rego`, що ми ловили cross-check тестами).
  *
- * Hard-fail на відсутність `conftest` у PATH — узгоджено з рішенням Plan B:
- * якщо правило делегує свою логіку до Rego, а інструмент відсутній, тиха
- * відмова приховує реальні порушення. Друкуємо install-hint (як `lint-rego.mjs`
- * робить для opa/regal).
+ * Hard-fail на відсутність `conftest` — через `ensureTool`, що спочатку
+ * намагається авто-встановити, і лише після невдачі кидає виняток.
  */
 import { spawnSync } from 'node:child_process'
 import { existsSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs'
@@ -20,7 +18,7 @@ import { tmpdir } from 'node:os'
 import { dirname, join } from 'node:path'
 import { fileURLToPath } from 'node:url'
 
-import { resolveCmd } from '../utils/resolve-cmd.mjs'
+import { ensureTool } from './ensure-tool.mjs'
 
 /**
   Каталог пакета `@nitra/cursor`, від якого ресолвимо вшиті директорії правил.
@@ -30,23 +28,6 @@ const PACKAGE_ROOT = dirname(dirname(dirname(fileURLToPath(import.meta.url))))
 /** Шлях до кореня правил. У npm-tarball публікується через `files: ["rules"]`. Кожне правило: `rules/<id>/policy/<name>/`. */
 const RULES_ROOT = join(PACKAGE_ROOT, 'rules')
 
-/**
- * Друкує install-hint для conftest і кидає виняток, щоб викликана `check-*`
- * команда ясно завершилась з кодом 1.
- * @returns {never} завжди кидає; для точки виклику — non-returning
- */
-function failConftestMissing() {
-  throw new Error(
-    [
-      '❌ conftest не знайдено в PATH.',
-      '   Без нього не запускається пер-документна валідація через rego-полісі (npm/policy/).',
-      '   Встанови:',
-      '     macOS:     brew install conftest',
-      '     Universal: https://www.conftest.dev/install/'
-    ].join('\n')
-  )
-}
-
 /**
  * @typedef {object} ConftestViolation
  * @property {string} filename абсолютний шлях до файла, що дав порушення (з output conftest)
@@ -80,16 +61,13 @@ export function buildConftestArgs(p) {
 /**
  * Виконує `conftest test` для всіх файлів одним спавном і повертає масив
  * порушень. Якщо `files` порожній — повертає `[]` без спавна. Якщо `conftest`
- * не у PATH — кидає виняток (hard fail, див. модульний docstring).
+ * не у PATH і авто-встановлення не вдалось — кидає виняток (hard fail).
  * @param {ConftestBatchOptions} opts параметри запуску
  * @returns {ConftestViolation[]} масив порушень (порожній — все ок)
  */
 export function runConftestBatch(opts) {
   if (opts.files.length === 0) return []
-  const conftestBin = resolveCmd('conftest')
-  if (!conftestBin) {
-    failConftestMissing()
-  }
+  const conftestBin = ensureTool('conftest')
   // policyDirRel — формат `<rule>/<name>` (наприклад `abie/base_deployment_preem`).
   // Реальний шлях у новій структурі: `rules/<rule>/policy/<name>`.
   const slash = opts.policyDirRel.indexOf('/')

package/scripts/lib/run-rule.mjs

@@ -13,13 +13,20 @@
  * Це дає той самий 0/1 контракт, що й попередня модель «один check.mjs на правило».
  */
 import { readFile } from 'node:fs/promises'
-import { join } from 'node:path'
+import { join, relative } from 'node:path'
 
 import { findMissingMdcRefs } from './check-mdc-template-refs.mjs'
 import { createCheckReporter } from './check-reporter.mjs'
 import { resolveTargetFiles } from './resolve-target-files.mjs'
 import { runConftestBatch } from './run-conftest-batch.mjs'
-import { resolveConcernTemplateData } from './template.mjs'
+import {
+  checkContains,
+  checkDeny,
+  checkSnippet,
+  checkTextSubset,
+  parseByExt,
+  resolveConcernTemplateData
+} from './template.mjs'
 
 const APPLIES_CONCERN_NAME = 'applies'
 
@@ -52,6 +59,46 @@ async function evaluateAppliesGate(bundledRulesDir, rule) {
   return Boolean(await mod.applies())
 }
 
+/**
+ * Snippet-driven перевірка концерну (`target.json:"check":"template"`): канон зі
+ * `template/<target>.snippet|deny|contains.<ext>` звіряється з actual-файлом
+ * generic deep-subset-ом, без `.rego`. Семантика — subset-of: усі канонічні
+ * поля/елементи обовʼязкові, зайві дозволені; масиви матчаться за наявністю
+ * (order-insensitive). Сніпет — єдине джерело істини: його зміна одразу змінює enforce.
+ * @param {string} concernAbsDir абсолютний `rules/<id>/policy/<concern>/`
+ * @param {object} target розпарсений `target.json`
+ * @param {string[]} files актуальні файли-таргети (resolveTargetFiles)
+ * @param {string} ruleId id правила (для `source` у повідомленнях)
+ * @param {string} concernName імʼя концерну (для summary)
+ * @returns {Promise<number>} 0 — OK, 1 — є порушення
+ */
+export async function runTemplateSubsetConcern(concernAbsDir, target, files, ruleId, concernName) {
+  const reporter = createCheckReporter()
+  const data = await resolveConcernTemplateData(concernAbsDir, target)
+  if (!data) {
+    reporter.pass(`${concernName}: немає template-сніпета — пропущено`)
+    return reporter.getExitCode()
+  }
+  for (const file of files) {
+    const rel = relative(process.cwd(), file) || file
+    const actual = await parseByExt(file)
+    const opts = { targetPath: rel, source: `${ruleId}.mdc` }
+    const violations = [
+      ...(typeof data.snippet === 'string'
+        ? checkTextSubset(actual, data.snippet, opts)
+        : checkSnippet(actual, data.snippet, opts)),
+      ...checkDeny(actual, data.deny, opts),
+      ...checkContains(actual, data.contains, opts)
+    ]
+    if (violations.length === 0) {
+      reporter.pass(`${concernName}: ${rel} відповідає канону (template subset)`)
+    } else {
+      for (const v of violations) reporter.fail(v)
+    }
+  }
+  return reporter.getExitCode()
+}
+
 /**
  * Запускає одну policy-полісі через `runConftestBatch`. Створює локальний репортер,
  * читає `target.json`, визначає файли, фіксує fail/pass — і повертає exit-код.
@@ -63,8 +110,9 @@ async function evaluateAppliesGate(bundledRulesDir, rule) {
  */
 async function runPolicyConcern(bundledRulesDir, ruleId, concernName, walkCache) {
   const reporter = createCheckReporter()
-  const targetPath = join(bundledRulesDir, ruleId, 'policy', concernName, 'target.json')
-  /** @type {{ files: { single?: string, walkGlob?: string|string[], required?: boolean }, missingMessage?: string }} */
+  const concernAbsDir = join(bundledRulesDir, ruleId, 'policy', concernName)
+  const targetPath = join(concernAbsDir, 'target.json')
+  /** @type {{ check?: 'template', files: { single?: string, walkGlob?: string|string[], required?: boolean }, missingMessage?: string }} */
   const target = JSON.parse(await readFile(targetPath, 'utf8'))
   const files = await resolveTargetFiles(target.files, process.cwd(), walkCache)
   if (files.length === 0) {
@@ -76,10 +124,18 @@ async function runPolicyConcern(bundledRulesDir, ruleId, concernName, walkCache)
     }
     return reporter.getExitCode()
   }
+
+  // `"check": "template"` — концерн без власного `.rego`: канон зі `template/`
+  // звіряється напряму через generic deep-subset (`checkSnippet`/`checkDeny`/
+  // `checkContains`/`checkTextSubset`). Редагування сніпета автоматично змінює
+  // enforce — без правок rego й без міграторів.
+  if (target.check === 'template') {
+    return runTemplateSubsetConcern(concernAbsDir, target, files, ruleId, concernName)
+  }
+
   // Rego не дозволяє '-' в імені пакета, тому kebab-id у `.n-cursor.json:rules`
   // мапиться на snake у namespace. Файлова структура `rules/<id>/policy/` лишається kebab.
   const regoNamespace = `${ruleId.replaceAll('-', '_')}.${concernName}`
-  const concernAbsDir = join(bundledRulesDir, ruleId, 'policy', concernName)
   const templateData = await resolveConcernTemplateData(concernAbsDir, target)
   const violations = runConftestBatch({
     policyDirRel: `${ruleId}/${concernName}`,

package/scripts/lib/template.mjs

@@ -26,7 +26,7 @@ const LEADING_BANG_RE = /^!/
  * @param {string} path шлях до файлу
  * @returns {Promise<unknown>} розпарсений вміст
  */
-async function parseByExt(path) {
+export async function parseByExt(path) {
   const raw = await readFile(path, 'utf8')
   const ext = extname(path).toLowerCase()
   if (ext === '.json' || ext === '.jsonc') return JSON.parse(stripJsonComments(raw))
@@ -112,6 +112,27 @@ function quote(v) {
   return typeof v === 'string' ? JSON.stringify(v) : String(v)
 }
 
+/** Ключі, за якими ідентифікуємо елемент масиву обʼєктів у повідомленні (напр. workflow-крок). */
+const ELEMENT_ID_KEYS = ['uses', 'name', 'id', 'run']
+
+/**
+ * Людинозрозумілий опис елемента масиву для повідомлення про відсутність.
+ * Для скаляра — `quote`; для обʼєкта — перший наявний ідентифікуючий ключ
+ * (`uses`/`name`/`id`/`run`), інакше компактний JSON.
+ * @param {unknown} needle елемент сніпета, якого бракує в actual
+ * @returns {string} опис для тексту порушення
+ */
+function describeElement(needle) {
+  if (needle !== null && typeof needle === 'object' && !Array.isArray(needle)) {
+    const obj = /** @type {Record<string, unknown>} */ (needle)
+    for (const k of ELEMENT_ID_KEYS) {
+      if (typeof obj[k] === 'string') return `елемент з ${k}: ${quote(obj[k])}`
+    }
+    return `елемент ${JSON.stringify(needle)}`
+  }
+  return quote(needle)
+}
+
 /**
  * Deep subset-of check. Every leaf in `snippet` must equal same path in `actual`.
  * Arrays in snippet: every element must be present in actual array.
@@ -131,10 +152,15 @@ export function checkSnippet(actual, snippet, opts, path = []) {
       violations.push(`${targetPath}: ${formatPath(path)} має бути масивом (${source})`)
       return violations
     }
+    // Subset-of, order-insensitive: кожен елемент сніпета має структурно міститись
+    // хоча б в одному елементі actual. Для обʼєктів — рекурсивний subset
+    // (`checkSnippet` без порушень), тож порядок ключів, зайві поля й зайві елементи
+    // не ламають збіг. Критично для впорядкованих масивів як `steps`, де елементи
+    // сортувати не можна (порядок кроків семантичний) — матч лишається за наявністю.
     for (const needle of snippet) {
-      const found = actual.some(a => JSON.stringify(a) === JSON.stringify(needle))
+      const found = actual.some(a => checkSnippet(a, needle, opts, [...path, '[]']).length === 0)
       if (!found) {
-        violations.push(`${targetPath}: ${formatPath(path)} має містити ${quote(needle)} (${source})`)
+        violations.push(`${targetPath}: ${formatPath(path)} має містити ${describeElement(needle)} (${source})`)
       }
     }
     return violations

package/scripts/lib/worktree-notice.mjs

@@ -5,6 +5,16 @@
  * і не паралелитись. Підказка адресована агенту, який читає `SKILL.md`, тож
  * вставляється в текст між стабільними маркерами — ре-синк ідемпотентний:
  * наявний блок замінюється, при `worktree:false` — видаляється.
+ *
+ * Крок 0.1 блоку додає `bun install` у щойно створеному дереві (локальна копія
+ * CLI усуває гонку з CDN) і shell-обгортку `n_cursor_npx` навколо bootstrap-виклику
+ * `npx`: на ETARGET/notarget та мережевих помилках npm падає ДО запуску бінарника,
+ * тож retry мусить жити на рівні shell-інструкції, а не в JS-хендлерах CLI.
+ * Обгортка ретраїть лише транзитні помилки реєстру/мережі (30с інтервал, дефолт
+ * 5 хв, env `N_CURSOR_NPX_RETRY_MAX_MIN`, ceiling 10 хв) і віддає реальний nonzero
+ * CLI одразу. Команди винесені окремим кроком ПІСЛЯ worktree-створення, бо
+ * вимагають command substitution, заборонену у «без-expansion» preflight-снипеті
+ * (узгоджено з worktree.mdc).
  */
 
 /** Маркер початку worktree-блоку (стабільний, не залежить від тексту всередині). */
@@ -124,7 +134,48 @@ npx @nitra/cursor worktree add "feature/x-${suffix}" "n-${suffix}: worktree-only
 cd ".worktrees/feature-x-${suffix}"
 \`\`\`
 
-Тобто branch-argument лишає slash як у git-гілці, а шлях для \`cd\` бере sanitized форму: slash → \`-\`.`;
+Тобто branch-argument лишає slash як у git-гілці, а шлях для \`cd\` бере sanitized форму: slash → \`-\`.
+
+**Крок 0.1 — bootstrap у новому дереві (після \`cd\`, окремий крок — поза «без-expansion» блоком вище).** Дерево щойно створене й **без** \`node_modules\`. Спершу постав залежності локально: тоді \`npx\` бере локальну копію \`@nitra/cursor\` і гонки з CDN немає взагалі. Retry-обгортка нижче — safety-net на випадок, коли версію щойно опубліковано, але edge-кеш CDN ще її не має: \`npm\` тоді падає з \`ETARGET\`/\`notarget\` **до** запуску бінарника (внутрішній JS-retry у \`n-cursor\` для цього кейсу марний — бінарник ще не стартував).
+
+\`\`\`bash
+# Локальна копія @nitra/cursor (девзалежність споживача) — npx бере її, без походу в реєстр.
+bun install
+
+# n_cursor_npx <args> — обгортка bootstrap-виклику "npx @nitra/cursor <args>".
+# Ретраїмо ЛИШЕ транзитні помилки реєстру/мережі (CDN ще не пропагував щойно
+# опубліковану версію). Реальний nonzero від CLI (fix повернув ❌, lint-помилка) —
+# віддаємо одразу, без ретраю. Інтервал 30с; дефолт-ліміт 5 хв
+# (env N_CURSOR_NPX_RETRY_MAX_MIN), hard-ceiling 10 хв.
+# Чому 5 хв: CDN-пропагація npm зазвичай < 2 хв, 5 хв — запас; довше → ймовірно
+# реальна проблема (невірна версія / аутейдж), краще віддати помилку, ніж висіти.
+n_cursor_npx() {
+  max_min="\${N_CURSOR_NPX_RETRY_MAX_MIN:-5}"
+  case "$max_min" in '' | *[!0-9]*) max_min=5 ;; esac
+  [ "$max_min" -gt 10 ] && max_min=10
+  deadline=$(( $(date +%s) + max_min * 60 ))
+  attempt=1
+  transient='ETARGET|notarget|No matching version|ENOTFOUND|ETIMEDOUT|EAI_AGAIN|ECONNRESET|50[0-9] |502 Bad Gateway|503 Service Unavailable|504 Gateway'
+  while :; do
+    err=$(mktemp)
+    npx @nitra/cursor "$@" 2>"$err"
+    code=$?
+    cat "$err" >&2
+    [ "$code" -eq 0 ] && { rm -f "$err"; return 0; }
+    if grep -Eq "$transient" "$err" && [ "$(date +%s)" -lt "$deadline" ]; then
+      rm -f "$err"
+      echo "n-cursor: очікую пропагації версії по CDN… спроба $attempt, повтор через 30с" >&2
+      attempt=$((attempt + 1))
+      sleep 30
+    else
+      rm -f "$err"
+      return "$code"
+    fi
+  done
+}
+\`\`\`
+
+Усі подальші bootstrap-виклики \`npx @nitra/cursor <cmd>\` у цій сесії роби через \`n_cursor_npx <cmd>\`. Якщо опинився у свіжому shell без цієї функції — спершу повтори блок вище (\`bun install\` + визначення \`n_cursor_npx\`).`;
 }
 
 /**