@nitra/cursor 3.18.2 → 3.20.0

package/rules/rego/lint/lint.mjs

@@ -1,7 +1,7 @@
 /**
- * Лінт Rego-полісі (`conftest.mdc` + `rego.mdc`): preflight на `opa` і `regal`,
- * далі послідовно `opa check --strict`, `regal lint` і опційний
- * `conftest verify` (для `*_test.rego`-файлів) якщо conftest у PATH.
+ * Лінт Rego-полісі (`conftest.mdc` + `rego.mdc`): `ensureTool` на `opa` і `regal`
+ * (авто-install per-platform або hard-fail), далі послідовно `opa check --strict`,
+ * `regal lint` і опційний `conftest verify` (для `*_test.rego`-файлів) якщо conftest у PATH.
  *
  * Чому два-три інструменти:
  * - `opa check --strict` — компіляція з типами і строгим режимом (мертвий код, неоднозначні
@@ -13,10 +13,10 @@
  *   Якщо conftest відсутній у PATH — пропускаємо без помилки (тести опційні в локальному середовищі;
  *   у CI потрібно встановити conftest).
  *
- * Без preflight-у на бінарники лінт мовчки злетить з невиразним повідомленням від shell —
- * друкуємо явні install-hints (як це робить `lint-ga.mjs` для shellcheck/uv). `opa` додатково
- * потрібен VS Code-розширенню `tsandall.opa` (LSP, format-on-save через `opa fmt`) — деталі в
- * `mdc/rego.mdc`.
+ * `opa`/`regal` резолвляться через `ensureTool` (PATH → кеш → авто-install brew/scoop/GitHub
+ * Release → hard-fail) — без них лінт мовчки злетів би з невиразним повідомленням від shell.
+ * `opa` додатково потрібен VS Code-розширенню `tsandall.opa` (LSP, format-on-save через
+ * `opa fmt`) — деталі в `mdc/rego.mdc`.
  *
  * Цілі лінту: `npm/rules/` (де живуть Rego-полісі пакета `@nitra/cursor` — у
  * `npm/rules/<id>/policy/<concern>/`). Усі три інструменти приймають один шлях
@@ -31,47 +31,13 @@ import { existsSync } from 'node:fs'
 import { resolve } from 'node:path'
 
 import { isRunAsCli } from '../../../scripts/cli-entry.mjs'
+import { ensureTool } from '../../../scripts/lib/ensure-tool.mjs'
 import { resolveCmd } from '../../../scripts/utils/resolve-cmd.mjs'
 import { runStandardLint } from '../../../scripts/lib/run-standard-lint.mjs'
 
 /** Шляхи з Rego-полісі (відносно cwd). Існують не всі на ранніх стадіях — фільтруємо нижче. */
 const LINT_TARGETS = ['npm/rules']
 
-/**
- * Друкує підказку зі встановлення `opa` (потрібен для `opa check --strict` і VS Code LSP).
- * @returns {void}
- */
-function printOpaInstallHints() {
-  process.stderr.write(
-    [
-      '❌ opa не знайдено в PATH.',
-      '   Без нього не запускається `opa check --strict` (типи + мертвий код у *.rego),',
-      '   і не працює VS Code-розширення `tsandall.opa` (LSP, format-on-save через opa fmt).',
-      '   Встанови:',
-      '     macOS:     brew install opa',
-      '     Universal: https://www.openpolicyagent.org/docs/latest/#1-download-opa',
-      ''
-    ].join('\n')
-  )
-}
-
-/**
- * Друкує підказку зі встановлення `regal`.
- * @returns {void}
- */
-function printRegalInstallHints() {
-  process.stderr.write(
-    [
-      '❌ regal не знайдено в PATH.',
-      '   Без нього не перевіряється rego.v1 синтаксис у *.rego (правило `conftest`).',
-      '   Встанови:',
-      '     macOS:     brew install regal',
-      '     Universal: https://docs.styra.com/regal#installation',
-      ''
-    ].join('\n')
-  )
-}
-
 /**
  * Запускає крок з відображенням команди користувачу. Stdout/stderr передаємо як є
  * (`stdio: 'inherit'`), щоб виглядало як прямий виклик у shell.
@@ -101,19 +67,8 @@ function runStep(bin, args, cwd) {
  */
 export function runLintRegoSteps(cwd = process.cwd()) {
   const root = resolve(cwd)
-  const opa = resolveCmd('opa')
-  const regal = resolveCmd('regal')
-
-  let preflightOk = true
-  if (!opa) {
-    printOpaInstallHints()
-    preflightOk = false
-  }
-  if (!regal) {
-    printRegalInstallHints()
-    preflightOk = false
-  }
-  if (!preflightOk) return 1
+  const opa = ensureTool('opa')
+  const regal = ensureTool('regal')
 
   const targets = LINT_TARGETS.filter(rel => existsSync(resolve(root, rel)))
   if (targets.length === 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}`
+  )
+}