@nitra/cursor 3.19.0 → 3.20.0

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\`).`;
 }
 
 /**

package/skills/fix/SKILL.md

@@ -12,10 +12,10 @@ description: >-
 
 ## Workflow
 
-1. **Діагностика** — запусти перевірку (за замовчуванням лише правила з `.cursor/rules/*.mdc`, для яких у пакеті є programmatic check; повний набір — явні аргументи: `npx @nitra/cursor fix bun ga …`):
+1. **Діагностика** — запусти перевірку через retry-обгортку `n_cursor_npx` (визначена у worktree-preflight, крок 0.1: переживає транзитну CDN-гонку щойно опублікованої версії, а реальний `❌` від `fix` віддає одразу). За замовчуванням — лише правила з `.cursor/rules/*.mdc`, для яких у пакеті є programmatic check; повний набір — явні аргументи: `n_cursor_npx fix bun ga …`:
 
 ```bash
-npx @nitra/cursor fix
+n_cursor_npx fix
 ```
 
 2. **Аналіз** — зчитай вивід, знайди всі `❌` та визнач які правила порушено
@@ -40,10 +40,10 @@ bun i
 oxfmt .
 ```
 
-6. **Верифікація** — перевір що все виправлено:
+6. **Верифікація** — перевір що все виправлено (та сама retry-обгортка `n_cursor_npx`):
 
 ```bash
-npx @nitra/cursor fix
+n_cursor_npx fix
 ```
 
 7. **Результат** — всі `❌` від `npx @nitra/cursor fix` мають стати `✅`. Якщо залишились `❌` — повтори кроки 3-6. Лінт-помилки від `bun run lint` тут **не виправляй** — вони на скіл `/n-lint`.

package/types/bin/n-cursor.d.ts

@@ -1,2 +1,2 @@
 #!/usr/bin/env node
-export {}
+export {};

package/rules/npm-module/policy/npm_publish_yml/npm_publish_yml.rego

@@ -1,87 +0,0 @@
-# Перевірка `.github/workflows/npm-publish.yml` (npm-module.mdc).
-#
-# Канон надходить через --data: { "template": { "snippet": ... } }
-# Структура --data сформована з template/npm-publish.yml.snippet.yml.
-# Per-concern field-by-field: path/substring-маркери з expected_uses_set читаються
-# зі steps template, експектації branches/paths — subset-of.
-#
-# Універсальні workflow-перевірки (concurrency, заборонені setup-bun/cache/install,
-# shell line-continuation) — у `ga.workflow_common`.
-package npm_module.npm_publish_yml
-
-import rego.v1
-
-# YAML 1.1 quirk: ключ `on:` → boolean true → у конфтесті ключ "true".
-gha_on := input["true"]
-
-# Required marker — substring у `uses` для ідентифікації npm-publish кроку.
-publish_action_marker := "JS-DevTools/npm-publish"
-
-# Очікувані літерали з template.
-expected_paths := {p | some p in data.template.snippet.on.push.paths}
-
-expected_branches := {b | some b in data.template.snippet.on.push.branches}
-
-expected_permissions := data.template.snippet.jobs["release-publish"].permissions
-
-# Required publish-step (за маркером): expected `with.package` value з template.
-expected_publish_with_package := s.with.package if {
-	some s in data.template.snippet.jobs["release-publish"].steps
-	contains(object.get(s, "uses", ""), publish_action_marker)
-}
-
-# ── deny: paths містить кожне з expected_paths (subset-of) ───────────────
-
-deny contains msg if {
-	some required_path in expected_paths
-	not path_present(required_path)
-	msg := sprintf("npm-publish.yml: у on.push.paths має бути `%s` (npm-module.mdc)", [required_path])
-}
-
-# ── deny: branches містить кожне з expected_branches (subset-of) ─────────
-
-deny contains msg if {
-	some required_branch in expected_branches
-	not required_branch in {b | some b in gha_on.push.branches}
-	msg := sprintf("npm-publish.yml: on.push.branches має містити `%s` (npm-module.mdc)", [required_branch])
-}
-
-# ── deny: id-token: write у permissions хоч одного job ────────────────────
-
-deny contains msg if {
-	required := expected_permissions["id-token"]
-	not any_job_has_id_token(required)
-	msg := sprintf("npm-publish.yml: permissions має містити `id-token: %s` (OIDC) (npm-module.mdc)", [required])
-}
-
-# ── deny: крок з uses-маркером npm-publish та канонічним with.package ────
-
-deny contains msg if {
-	not has_npm_publish_step
-	msg := sprintf(
-		"npm-publish.yml: очікується `uses: %s` з `with.package: %s` (npm-module.mdc)",
-		[publish_action_marker, expected_publish_with_package],
-	)
-}
-
-# ── helpers ────────────────────────────────────────────────────────────────
-
-# Path присутній, якщо хоч один шлях у actual містить required як substring
-# (npm/** glob у workflow може бути записаний як `npm/**` або `'npm/**'`).
-path_present(required) if {
-	some p in gha_on.push.paths
-	is_string(p)
-	contains(p, required)
-}
-
-any_job_has_id_token(required) if {
-	some job in object.get(input, "jobs", {})
-	job.permissions["id-token"] == required
-}
-
-has_npm_publish_step if {
-	some job in object.get(input, "jobs", {})
-	some step in object.get(job, "steps", [])
-	contains(object.get(step, "uses", ""), publish_action_marker)
-	step.with.package == expected_publish_with_package
-}