@nitra/cursor 1.13.38 → 1.13.40

package/CHANGELOG.md

@@ -4,6 +4,18 @@
 
 Формат — [Keep a Changelog](https://keepachangelog.com/uk/1.1.0/), нумерація — [SemVer](https://semver.org/lang/uk/).
 
+## [1.13.40] - 2026-05-18
+
+### Fixed
+
+- `lint-text` CLI: preflight на `shellcheck`, `patch` і `dotenv-linter` до ланцюжка cspell/shellcheck/dotenv. Канон `lint-text.yml.snippet.yml` — кроки `Install shellcheck` (apt) і `Install dotenv-linter` (curl); rego `text.lint_text`. Bump `text.mdc` `1.28` → `1.29`.
+
+## [1.13.39] - 2026-05-18
+
+### Fixed
+
+- `lint-ga` CLI: preflight на `conftest` (поряд із `shellcheck`/`uv`) з install-hint; глобальний `catch` у `bin/n-cursor.js` більше не ковтає повідомлення `failConftestMissing()`. Канон `lint-ga.yml.snippet.yml` — крок `Install conftest` для CI; rego `ga.lint_ga` вимагає curl на release conftest.
+
 ## [1.13.38] - 2026-05-18
 
 ### Added

package/bin/n-cursor.js

@@ -1405,7 +1405,11 @@ try {
 } catch (error) {
   if (error instanceof ReexecHandoff) {
     process.exitCode = error.code
+  } else if (error instanceof Error && error.message) {
+    console.error(error.message)
+    process.exitCode = 1
   } else {
+    console.error(error)
     process.exitCode = 1
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nitra/cursor",
-  "version": "1.13.38",
+  "version": "1.13.40",
   "description": "CLI для завантаження cursor-правил (префікс n-) у локальний репозиторій",
   "keywords": [
     "cli",

package/rules/ga/lint/lint.mjs

@@ -1,5 +1,6 @@
 /**
- * CLI-обгортка над канонічним `lint-ga` (ga.mdc): робить preflight на `shellcheck` і `uv` (для `uvx`),
+ * CLI-обгортка над канонічним `lint-ga` (ga.mdc): робить preflight на `shellcheck`, `uv` (для `uvx`)
+ * і `conftest` (для rego-полісі у `check-ga`),
  * тоді послідовно виконує `bunx github-actionlint`, `uvx zizmor --offline --collect=workflows .` і
  * делегує до `check-ga.mjs::check()` — там і Rego-частина (через `runConftestBatch`),
  * і JS cross-file перевірки правил `ga.mdc`.
@@ -17,6 +18,10 @@
  * `uv` потрібен для `uvx zizmor`. Якщо його нема — `uvx zizmor` падає неінформативно («command not
  * found»); підказка з командою встановлення коротша й корисніша.
  *
+ * `conftest` потрібен для `check-ga.mjs::runAllGaRego` (`runConftestBatch`). Без preflight крок
+ * check-ga кидає виняток, який глобальний `catch` у `bin/n-cursor.js` раніше ковтав без логу —
+ * локально це виглядало як мовчазний exit 1.
+ *
  * Експортовано окремо `runLintGaCli` — використовується з `bin/n-cursor.js` як підкоманда `lint-ga`.
  */
 import { platform } from 'node:process'
@@ -68,6 +73,21 @@ const UV_PREFLIGHT = {
   successMsg: '✅ uv знайдено в PATH — uvx zizmor запуститься'
 }
 
+/** @type {PreflightDep} */
+const CONFTEST_PREFLIGHT = {
+  bin: 'conftest',
+  winBins: ['conftest.exe'],
+  explanation: [
+    'Без нього не запускається пер-документна валідація через rego-полісі (npm/rules/*/policy/)',
+    'у кроці check-ga — `runConftestBatch` завершується hard-fail.'
+  ].join('\n   '),
+  install: [
+    'macOS:     brew install conftest',
+    'Universal: https://www.conftest.dev/install/'
+  ],
+  successMsg: '✅ conftest знайдено в PATH — check-ga виконає rego-полісі через runConftestBatch'
+}
+
 /**
  * Шукає бінарник у PATH з урахуванням Windows: спершу `winBins`, потім `bin`.
  * @param {PreflightDep} dep опис залежності
@@ -116,7 +136,7 @@ function preflight(dep) {
  * Виконує канонічний `lint-ga` з preflight-перевірками і делегує до `check-ga.check()`.
  *
  * Послідовність:
- * 1) preflight: `shellcheck` (для actionlint SC-правил) і `uv` (для `uvx zizmor`); відсутній → exit 1;
+ * 1) preflight: `shellcheck`, `uv` (для `uvx zizmor`) і `conftest` (для check-ga); відсутній → exit 1;
  * 2) `bunx github-actionlint`;
  * 3) `uvx zizmor --offline --collect=workflows .`;
  * 4) `check-ga.mjs::check()` — Rego-полісі (батч conftest з `npm/policy/ga/`) + JS cross-file
@@ -132,7 +152,7 @@ function preflight(dep) {
  */
 export async function runLintGaCli() {
   let preflightOk = true
-  for (const dep of [SHELLCHECK_PREFLIGHT, UV_PREFLIGHT]) {
+  for (const dep of [SHELLCHECK_PREFLIGHT, UV_PREFLIGHT, CONFTEST_PREFLIGHT]) {
     if (!preflight(dep)) preflightOk = false
   }
   if (!preflightOk) return 1

package/rules/ga/policy/lint_ga/lint_ga.rego

@@ -92,6 +92,12 @@ deny contains msg if {
 	msg := sprintf("lint-ga.yml: має бути uses: %s (ga.mdc)", [required_use])
 }
 
+deny contains msg if {
+	expected_run_blob != ""
+	not contains(job_run_blob, "open-policy-agent/conftest")
+	msg := "lint-ga.yml: має бути крок Install conftest (ga.mdc)"
+}
+
 deny contains msg if {
 	expected_run_blob != ""
 	not contains(job_run_blob, "bun run lint-ga")

package/rules/ga/policy/lint_ga/template/lint-ga.yml.snippet.yml

@@ -31,5 +31,11 @@ jobs:
 
       - uses: astral-sh/setup-uv@v8.0.0
 
+      - name: Install conftest
+        run: >-
+          curl -fsSL
+          https://github.com/open-policy-agent/conftest/releases/download/v0.62.0/conftest_0.62.0_Linux_x86_64.tar.gz
+          | sudo tar -xz -C /usr/local/bin conftest
+
       - name: Lint GA
         run: bun run lint-ga

package/rules/text/fix/formatting/check.mjs

@@ -12,7 +12,7 @@
  *    `npm/mdc/text.mdc` (markdown-текст, не JSON/YAML);
  *  - складна валідація скрипта `lint-text` (cspell, markdownlint, v8r у трьох
  *    варіантах, run-shellcheck-text.mjs, обовʼязкові glob-и);
- *  - workflow `lint-text.yml` має крок `bun run lint-text`.
+ *  - workflow `lint-text.yml` має крок `bun run lint-text` (структура — rego `text.lint_text`).
  *
  * **Що покрила Rego** (`npx \@nitra/cursor check`):
  *  - `npm/policy/text/oxfmtrc/` — обовʼязкові ключі `.oxfmtrc.json` і канонічні

package/rules/text/lint/lint.mjs

@@ -1,26 +1,134 @@
 /**
- * CLI-обгортка над канонічним `lint-text` (text.mdc): послідовно
+ * CLI-обгортка над канонічним `lint-text` (text.mdc): preflight на `shellcheck`, `patch`
+ * (для авто-фіксу shellcheck) і `dotenv-linter`; далі послідовно
  *   1) `cspell .` — перевірка правопису з `@nitra/cspell-dict`;
  *   2) `runShellcheckText()` — авто-фікс і фінальна перевірка `*.sh` через `shellcheck`;
  *   3) `runDotenvLinter()` — авто-фікс і фінальна перевірка `.env*` через `dotenv-linter`;
  *   4) `bunx markdownlint-cli2 --fix "**\/*.md" "**\/*.mdc"` — авто-фікс Markdown;
- *   5) `runV8rWithGlobs()` — schema-валідація json/json5/yaml/yml/toml через v8r з каталогом `@nitra/cursor`.
+ *   5) `runV8rWithGlobs()` — schema-валідація json/json5/yaml/yml/toml через v8r.
+ *
+ * Без preflight локальний прогін може пройти cspell/markdownlint, а CI на ubuntu-latest
+ * (де shellcheck передвстановлений, але dotenv-linter — ні) падає на кроці dotenv-linter
+ * з неінформативним повідомленням. Preflight збирає всі відсутні бінарники до першого кроку.
  *
  * Перший ненульовий код з ланцюжка повертається як код виходу; наступні кроки не запускаються.
  * Експортовано як `runLintTextCli` — використовується з `bin/n-cursor.js` як підкоманда `lint-text`.
  */
+import { platform } from 'node:process'
+
 import { runLintStep } from '../../../scripts/utils/run-lint-step.mjs'
+import { resolveCmd } from '../../../scripts/utils/resolve-cmd.mjs'
 import { runDotenvLinter } from './run-dotenv-linter.mjs'
 import { runShellcheckText } from './run-shellcheck.mjs'
 import { runV8rWithGlobs } from './run-v8r.mjs'
 
 /**
- * Виконує канонічний `lint-text`: cspell → run-shellcheck → run-dotenv-linter → markdownlint-cli2 → run-v8r.
- * Першу помилку повертаємо як код виходу; наступні кроки не запускаються.
- * Усі кроки синхронні (`spawnSync` + sync-ентрі з пакета), тому функція не async.
+ * Опис залежності preflight-ом.
+ * @typedef {object} PreflightDep
+ * @property {string} bin ім'я виконуваного файлу
+ * @property {string[]} [winBins] альтернативні імена на Windows
+ * @property {string} explanation наслідки відсутності
+ * @property {string[]} install команди встановлення
+ * @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',
+  explanation: [
+    'Без `patch` не застосуються авто-виправлення shellcheck (`shellcheck -f diff` + `patch -p1`).'
+  ].join('\n   '),
+  install: [
+    'macOS:         зазвичай уже є в системі',
+    'Debian/Ubuntu: sudo apt-get install -y patch'
+  ],
+  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*'
+}
+
+/**
+ * @param {PreflightDep} dep
+ * @returns {string | null}
+ */
+function resolvePreflightBin(dep) {
+  if (platform === 'win32' && dep.winBins) {
+    for (const name of dep.winBins) {
+      const r = resolveCmd(name)
+      if (r) return r
+    }
+  }
+  return resolveCmd(dep.bin)
+}
+
+/**
+ * @param {PreflightDep} dep
+ * @returns {void}
+ */
+function printPreflightMissingMessage(dep) {
+  console.error(`❌ ${dep.bin} не знайдено в PATH.`)
+  console.error(`   ${dep.explanation}`)
+  console.error('   Встанови:')
+  for (const line of dep.install) {
+    console.error(`     ${line}`)
+  }
+  console.error('   Деталі: text.mdc → секція про lint-text.')
+}
+
+/**
+ * @param {PreflightDep} dep
+ * @returns {boolean}
+ */
+function preflight(dep) {
+  if (resolvePreflightBin(dep)) {
+    console.log(dep.successMsg)
+    return true
+  }
+  printPreflightMissingMessage(dep)
+  return false
+}
+
+/**
+ * Виконує канонічний `lint-text` з preflight і ланцюжком cspell → shellcheck → dotenv → markdownlint → v8r.
  * @returns {number} 0 — все OK, інакше — код першого кроку, що впав
  */
 export function runLintTextCli() {
+  let preflightOk = true
+  for (const dep of [SHELLCHECK_PREFLIGHT, PATCH_PREFLIGHT, DOTENV_LINTER_PREFLIGHT]) {
+    if (!preflight(dep)) preflightOk = false
+  }
+  if (!preflightOk) return 1
+
   const cspellCode = runLintStep('cspell', 'npx', ['cspell', '.'])
   if (cspellCode !== 0) return cspellCode
 

package/rules/text/policy/lint_text/lint_text.rego

@@ -0,0 +1,100 @@
+# Перевірка `.github/workflows/lint-text.yml` (text.mdc).
+#
+# Канон надходить через --data: { "template": { "snippet": ... } }
+# Структура --data сформована з template/lint-text.yml.snippet.yml.
+# Універсальні workflow-перевірки (checkout, permissions) — у `ga.workflow_common`.
+package text.lint_text
+
+import rego.v1
+
+expected_name := data.template.snippet.name
+
+expected_push_branches := {b | some b in data.template.snippet.on.push.branches}
+
+expected_pr_branches := {b | some b in data.template.snippet.on.pull_request.branches}
+
+expected_push_paths := {p | some p in data.template.snippet.on.push.paths}
+
+expected_runs_on := data.template.snippet.jobs.text["runs-on"]
+
+expected_perms := data.template.snippet.jobs.text.permissions
+
+job := input.jobs.text
+
+job_uses_set contains job.steps[_].uses
+
+job_run_blob := concat("\n", [run |
+	run := job.steps[_].run
+])
+
+expected_uses_set contains u if {
+	some step in data.template.snippet.jobs.text.steps
+	u := object.get(step, "uses", "")
+	u != ""
+}
+
+expected_run_substrings contains r if {
+	some step in data.template.snippet.jobs.text.steps
+	r := object.get(step, "run", "")
+	r != ""
+}
+
+deny contains msg if {
+	input.name != expected_name
+	msg := sprintf("lint-text.yml: name має бути %q (text.mdc)", [expected_name])
+}
+
+deny contains msg if {
+	not branches_superset_of(input.on.push.branches, expected_push_branches)
+	msg := "lint-text.yml: on.push.branches має містити dev і main (text.mdc)"
+}
+
+deny contains msg if {
+	not branches_superset_of(input.on.pull_request.branches, expected_pr_branches)
+	msg := "lint-text.yml: on.pull_request.branches має містити dev і main (text.mdc)"
+}
+
+deny contains msg if {
+	not paths_superset_of(input.on.push.paths, expected_push_paths)
+	msg := "lint-text.yml: on.push.paths має містити очікувані glob-и (text.mdc)"
+}
+
+deny contains msg if {
+	not job
+	msg := "lint-text.yml: jobs.text відсутній (text.mdc)"
+}
+
+deny contains msg if {
+	job["runs-on"] != expected_runs_on
+	msg := sprintf("lint-text.yml: runs-on має бути %s (text.mdc)", [expected_runs_on])
+}
+
+deny contains msg if {
+	job.permissions.contents != expected_perms.contents
+	msg := sprintf("lint-text.yml: permissions.contents має бути %s (text.mdc)", [expected_perms.contents])
+}
+
+deny contains msg if {
+	count(job.steps) == 0
+	msg := "lint-text.yml: jobs.text.steps відсутні (text.mdc)"
+}
+
+deny contains msg if {
+	some required_use in expected_uses_set
+	not required_use in job_uses_set
+	msg := sprintf("lint-text.yml: має бути uses: %s (text.mdc)", [required_use])
+}
+
+deny contains msg if {
+	some required_run in expected_run_substrings
+	not contains(job_run_blob, required_run)
+	msg := sprintf("lint-text.yml: жоден крок run не містить %q (text.mdc)", [required_run])
+}
+
+branches_superset_of(actual, expected) if {
+	expected & {b | some b in actual} == expected
+}
+
+paths_superset_of(actual, expected) if {
+	expected & {p | some p in actual} == expected
+}

package/rules/text/policy/lint_text/target.json

@@ -0,0 +1,4 @@
+{
+  "$schema": "https://unpkg.com/@nitra/cursor/schemas/target.json",
+  "files": { "single": ".github/workflows/lint-text.yml" }
+}

package/rules/text/policy/lint_text/template/lint-text.yml.snippet.yml

@@ -0,0 +1,61 @@
+name: Lint Text
+
+on:
+  push:
+    branches:
+      - dev
+      - main
+    paths:
+      - '**/*.js'
+      - '**/*.ts'
+      - '**/*.vue'
+      - '**/*.html'
+      - '**/*.css'
+      - '**/*.scss'
+      - '**/*.less'
+      - '**/*.json'
+      - '**/*.jsonc'
+      - '**/*.yaml'
+      - '**/*.yml'
+      - '**/*.toml'
+      - '**/*.xml'
+      - '**/*.md'
+      - '**/*.mdc'
+      - '**/*.mdс'
+      - '**/*.txt'
+      - '**/*.go'
+      - '**/*.py'
+      - '**/*.php'
+      - '**/*.sh'
+
+  pull_request:
+    branches:
+      - dev
+      - main
+
+concurrency:
+  group: ${{ github.ref }}-${{ github.workflow }}
+  cancel-in-progress: true
+
+jobs:
+  text:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          persist-credentials: false
+
+      - uses: ./.github/actions/setup-bun-deps
+
+      - name: Install shellcheck
+        run: sudo apt-get update && sudo apt-get install -y shellcheck
+
+      - name: Install dotenv-linter
+        run: >-
+          curl -sSfL https://git.io/JLbXn
+          | sh -s -- -b /usr/local/bin
+
+      - name: Lint text
+        run: bun run lint-text

package/rules/text/text.mdc

@@ -1,7 +1,7 @@
 ---
 description: Обробка та перевірка текстових файлів, oxfmt, cspell, shellcheck (sh), dotenv-linter (.env*), markdownlint-cli2, v8r, CI
 alwaysApply: true
-version: '1.28'
+version: '1.29'
 ---
 
 **oxfmt** (`.oxfmtrc.json`, редактор), **cspell**, **shellcheck** (tracked `*.sh` у `lint-text`), **[dotenv-linter](https://dotenv-linter.github.io/)** (`.env*` у `lint-text`), **markdownlint-cli2**, **[v8r](https://chris48s.github.io/v8r/)** ([Schema Store](https://www.schemastore.org/)), розширення **DavidAnson.vscode-markdownlint** / **timonwong.shellcheck**, workflow **`lint-text`**.
@@ -172,63 +172,9 @@ version: '1.28'
 
 Додай workflow `.github/workflows/lint-text.yml`:
 
-```yaml title=".github/workflows/lint-text.yml"
-name: Lint Text
-
-on:
-  push:
-    branches:
-      - dev
-      - main
-    paths:
-      - '**/*.js'
-      - '**/*.ts'
-      - '**/*.vue'
-      - '**/*.html'
-      - '**/*.css'
-      - '**/*.scss'
-      - '**/*.less'
-      - '**/*.json'
-      - '**/*.jsonc'
-      - '**/*.yaml'
-      - '**/*.yml'
-      - '**/*.toml'
-      - '**/*.xml'
-      - '**/*.md'
-      - '**/*.mdc'
-      - '**/*.mdс'
-      - '**/*.txt'
-      - '**/*.go'
-      - '**/*.py'
-      - '**/*.php'
-      - '**/*.sh'
-
-  pull_request:
-    branches:
-      - dev
-      - main
-
-concurrency:
-  group: ${{ github.ref }}-${{ github.workflow }}
-  cancel-in-progress: true
-
-jobs:
-  text:
-    runs-on: ubuntu-latest
-    permissions:
-      contents: read
-    steps:
-      - uses: actions/checkout@v6
-        with:
-          persist-credentials: false
-
-      - uses: ./.github/actions/setup-bun-deps
-
-      - name: Lint text
-        run: bun run lint-text
-```
+- Канон: [lint-text.yml.snippet.yml](./policy/lint_text/template/lint-text.yml.snippet.yml)
 
-Перед **`./.github/actions/setup-bun-deps`** — **`actions/checkout@v6`** (див. **ga.mdc**). Composite: Node 24, Bun, кеш, `bun install --frozen-lockfile`.
+Перед **`./.github/actions/setup-bun-deps`** — **`actions/checkout@v6`** (див. **ga.mdc**). Після composite — кроки **`Install shellcheck`** (apt) і **`Install dotenv-linter`** (curl), бо `n-cursor lint-text` вимагає обидва бінарники в PATH; на ubuntu-latest shellcheck часто вже є, dotenv-linter — ні. Composite: Node 24, Bun, кеш, `bun install --frozen-lockfile`.
 
 Не дублюй окремий workflow з тими самими кроками cspell/markdownlint.