@nitra/cursor 1.8.165 → 1.8.168

package/CHANGELOG.md

@@ -4,6 +4,30 @@
 
 Формат — [Keep a Changelog](https://keepachangelog.com/uk/1.1.0/), нумерація — [SemVer](https://semver.org/lang/uk/).
 
+## [1.8.168] - 2026-05-03
+
+### Added
+
+- `lint-ga.mjs`: до preflight на `shellcheck` додано preflight на [`uv`](https://docs.astral.sh/uv/) (постачає `uvx` для `uvx zizmor`). Якщо `uv` відсутній у `PATH` — `n-cursor lint-ga` падає з exit 1 і підказками `brew install uv` / `curl -LsSf https://astral.sh/uv/install.sh | sh` / `pip install uv`. Обидва preflight’и повідомляються незалежно: якщо нема одночасно й `shellcheck`, і `uv`, користувач одразу бачить обидві підказки, а не лише першу.
+- `lint-ga.mjs`: винесено внутрішній `PreflightDep` із `bin`/`winBins`/`explanation`/`install`/`successMsg` — однотипний pattern для додавання нових залежностей у preflight без копіпасти.
+
+## [1.8.167] - 2026-05-03
+
+### Added
+
+- `lint-ga.mjs` / `bin/n-cursor.js`: нова CLI-підкоманда `n-cursor lint-ga` (експорт `runLintGaCli`). Робить preflight на `shellcheck` (exit 1 + brew/apt/pacman підказки, коли його немає в `PATH`), тоді послідовно запускає `bunx github-actionlint` і `uvx zizmor --offline --collect=workflows .` через `spawnSync` з `stdio: 'inherit'`. Тепер і `bun lint-ga` сигналізує про відсутність shellcheck — раніше це робила лише `check ga`.
+- `ga.mdc` (v1.5): канонічний скрипт `lint-ga` у `package.json` тепер `n-cursor lint-ga` (а не `bunx github-actionlint && uvx zizmor …`); `check-ga.mjs` валідує саме цю форму. Виклик через bin-ім’я `n-cursor`, бо `bun run` транслює `npx` у `bun x`, а `bun x @nitra/cursor` для скоупованого пакету з одним bin-ім’ям повертає 0 без виконання.
+
+## [1.8.166] - 2026-05-03
+
+### Added
+
+- `ga.mdc` (v1.4) / `check-ga.mjs`: нова перевірка локального [`shellcheck`](https://www.shellcheck.net/) у `PATH`. Без нього `actionlint` (`bunx github-actionlint`) мовчки пропускає shell-перевірки в `run:` блоках, тож локальний `bun lint-ga` дає зелений результат, який падає в CI на `ubuntu-latest` (де shellcheck передвстановлений). `npx @nitra/cursor check ga` тепер `fail` з підказкою встановлення (`brew install shellcheck` / `apt-get install -y shellcheck` / `pacman -S shellcheck`).
+
+### Changed
+
+- `utils/resolve-cmd.mjs`: явно передаємо `process.env` у `spawnSync('which'/'where', ...)`, щоб у Bun зміни `PATH` у runtime (наприклад, підстановка стабів у тестах) бачилися дочірнім процесом. Без цього Bun використовував би snapshot оточення на старті.
+
 ## [1.8.165] - 2026-05-01
 
 ### Changed

package/bin/n-cursor.js

@@ -11,6 +11,8 @@
  *   `npx \@nitra/cursor rename-yaml-extensions` — k8s `*.yml` → `*.yaml`, `.github` `*.yaml` → `*.yml` (опції: `--dry-run`, `--root=…`; див. bin/rename-yaml-extensions.mjs)
  *   `npx \@nitra/cursor stop-hook`   — точка входу Stop hook Claude Code (читає stdin, виходить 0 при `stop_hook_active`,
  *                                     інакше викликає `check`); прописується автоматично в `.claude/settings.json`
+ *   `npx \@nitra/cursor lint-ga`     — канонічний lint-ga (ga.mdc): preflight на `shellcheck` →
+ *                                     `bunx github-actionlint` → `uvx zizmor --offline --collect=workflows .`
  *
  * Claude Code інтеграція: під час синку, окрім `.cursor/rules` і `.claude/commands` (з skills), CLI ще раз
  * синхронізує `.claude/settings.json` (hooks + permissions; merge — користувацькі поля зберігаються),
@@ -57,6 +59,7 @@ import { buildAgentsCommandBulletItems } from '../scripts/build-agents-commands.
 import { detectAutoRulesAndSkills, mergeConfigWithAutoDetected, normalizeIdList } from '../scripts/auto-rules.mjs'
 import { runStopHookCli } from '../scripts/claude-stop-hook.mjs'
 import { ensureNitraCursorInRootDevDependencies } from '../scripts/ensure-nitra-cursor-dev-dependencies.mjs'
+import { runLintGaCli } from '../scripts/lint-ga.mjs'
 import { syncClaudeConfig } from '../scripts/sync-claude-config.mjs'
 import { upgradeNitraCursorToLatestAndBunInstall } from '../scripts/upgrade-nitra-cursor-and-install.mjs'
 import { runRenameYamlExtensionsCli } from './rename-yaml-extensions.mjs'
@@ -1222,6 +1225,12 @@ try {
 
       break
     }
+    case 'lint-ga': {
+      // Канонічний lint-ga з preflight на shellcheck → actionlint → zizmor (ga.mdc).
+      process.exitCode = runLintGaCli()
+
+      break
+    }
     case undefined:
     case '': {
       await runSync()
@@ -1231,7 +1240,7 @@ try {
     default: {
       console.error(`❌ Невідома команда: ${command}`)
       console.error(
-        `   Очікується: (без аргументів) синхронізація правил, check, rename-yaml-extensions, stop-hook`
+        `   Очікується: (без аргументів) синхронізація правил, check, rename-yaml-extensions, stop-hook, lint-ga`
       )
       process.exitCode = 1
     }

package/mdc/ga.mdc

@@ -1,7 +1,7 @@
 ---
 description: Правила форматів для .github/workflows
 alwaysApply: true
-version: '1.3'
+version: '1.6'
 ---
 
 У `.github/workflows/` лише **`.yml`**. Мають бути **`clean-ga-workflows.yml`**, **`clean-merged-branch.yml`**, **`lint-ga.yml`**, **`git-ai.yml`**. Якщо є **`apply-k8s.yml`** / **`apply-nats-consumer.yml`** — paths у тригері як у фрагментах.
@@ -231,14 +231,24 @@ jobs:
       - uses: ./.github/actions/setup-bun-deps
 ```
 
-**Лінт:** [actionlint](https://github.com/rhysd/actionlint) через [github-actionlint](https://www.npmjs.com/package/github-actionlint); [zizmor](https://docs.zizmor.sh) — `uvx`, офлайн. Скрипт у корені:
+**Лінт:** [actionlint](https://github.com/rhysd/actionlint) через [github-actionlint](https://www.npmjs.com/package/github-actionlint); [zizmor](https://docs.zizmor.sh) — `uvx`, офлайн. Канонічний скрипт у корені делегує виконання CLI `n-cursor lint-ga` (бінарка з `node_modules/.bin/` пакету `@nitra/cursor`), який робить preflight на `shellcheck` і послідовно запускає `actionlint` та `zizmor`:
 
 ```json title="package.json"
 "scripts": {
-  "lint-ga": "bunx github-actionlint && uvx zizmor --offline --collect=workflows ."
+  "lint-ga": "n-cursor lint-ga"
 }
 ```
 
+> Не використовуй `npx --no @nitra/cursor lint-ga` — `bun run` автоматично транслює `npx` у `bun x`, а `bun x` для скоупованого пакету з одним bin-ім’ям повертає 0 без виконання. Виклик через bin-ім’я `n-cursor` працює і у `bun run`, і у `npm run`.
+
+CLI виконує:
+
+1. Preflight на [`shellcheck`](https://www.shellcheck.net/) у `PATH` — без нього `actionlint` мовчки пропускає shell-перевірки в `run:` блоках, тож локальний прогін зеленіє, а CI на `ubuntu-latest` (де shellcheck передвстановлений) падає на тих самих workflow. Встановлення: `brew install shellcheck` (macOS), `sudo apt-get install -y shellcheck` (Debian/Ubuntu), `sudo pacman -S shellcheck` (Arch).
+2. Preflight на [`uv`](https://docs.astral.sh/uv/) у `PATH` — постачає `uvx`, без якого не запуститься `uvx zizmor`. Встановлення: `brew install uv` (macOS), `curl -LsSf https://astral.sh/uv/install.sh | sh` (universal), `pip install uv`.
+3. Якщо хоча б один preflight не пройшов — exit 1 (підказки для всіх відсутніх залежностей друкуються разом, а не лише для першої).
+4. `bunx github-actionlint`.
+5. `uvx zizmor --offline --collect=workflows .`.
+
 **`.github/zizmor.yml`:** для [unpinned-uses](https://docs.zizmor.sh/audits/#unpinned-uses) — політика **`ref-pin`**, якщо в `uses:` семантичні теги. За потреби вимкни [template-injection](https://docs.zizmor.sh/audits/#template-injection):
 
 ```yaml title=".github/zizmor.yml"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nitra/cursor",
-  "version": "1.8.165",
+  "version": "1.8.168",
   "description": "CLI для завантаження cursor-правил (префікс n-) у локальний репозиторій",
   "keywords": [
     "cli",
@@ -49,6 +49,6 @@
     "node": ">=25"
   },
   "devDependencies": {
-    "@nitra/cursor": "^1.8.165"
+    "@nitra/cursor": "^1.8.168"
   }
 }

package/scripts/check-ga.mjs

@@ -35,6 +35,7 @@ import {
   getStepUses,
   parseWorkflowYaml
 } from './utils/gha-workflow.mjs'
+import { resolveCmd } from './utils/resolve-cmd.mjs'
 
 /** Шаблони наявності MegaLinter у вмісті workflow */
 const MEGALINTER_USE_PATTERNS = [/oxsecurity\/megalinter-action/i, /megalinter\/megalinter/i]
@@ -738,16 +739,43 @@ async function checkLintGaScript(passFn, failFn) {
     return
   }
   passFn('package.json містить lint-ga')
-  if (lg.includes('github-actionlint')) {
-    passFn('lint-ga викликає github-actionlint')
+  // Канонічний скрипт делегує виконання CLI `n-cursor lint-ga` (bin з `@nitra/cursor`) — там preflight
+  // на shellcheck + послідовно `bunx github-actionlint` і `uvx zizmor --offline --collect=workflows .`.
+  // Виклик через bin-ім’я `n-cursor`, а не `npx --no @nitra/cursor`, бо `bun run` транслює `npx` у `bun x`,
+  // а `bun x @nitra/cursor` для скоупованого пакету з одним bin-ім’ям повертає 0 без виконання.
+  if (/\bn-cursor\s+lint-ga\b/.test(lg)) {
+    passFn('lint-ga делегує CLI n-cursor lint-ga (preflight shellcheck + actionlint + zizmor)')
   } else {
-    failFn('lint-ga має містити bunx github-actionlint (ga.mdc)')
+    failFn(
+      'lint-ga має бути "n-cursor lint-ga" — CLI робить preflight shellcheck перед actionlint/zizmor (ga.mdc)'
+    )
   }
-  if (lg.includes('zizmor') && lg.includes('--offline')) {
-    passFn('lint-ga викликає zizmor з --offline')
-  } else {
-    failFn('lint-ga має містити zizmor і --offline (ga.mdc)')
+}
+
+/**
+ * Перевіряє наявність локального `shellcheck` у PATH. `actionlint` (`bunx github-actionlint`)
+ * запускає shell-перевірки в кроках `run:` workflow тільки коли `shellcheck` доступний; інакше
+ * мовчки пропускає SC-правила, через що локальний `bun lint-ga` зелений, а CI на ubuntu-latest
+ * (де shellcheck передвстановлений) падає. Тому відсутність бінарника локально — `fail`.
+ *
+ * Кросплатформно: `resolveCmd` використовує `which`/`where` і однаково знаходить `shellcheck`
+ * та `shellcheck.exe` на Windows.
+ * @param {(msg: string) => void} passFn callback при успішній перевірці
+ * @param {(msg: string) => void} failFn callback при помилці
+ */
+function checkShellcheckInstalled(passFn, failFn) {
+  if (resolveCmd('shellcheck')) {
+    passFn('shellcheck встановлений локально, actionlint виконуватиме SC-правила, як у CI')
+    return
   }
+  failFn(
+    [
+      'shellcheck не знайдено в PATH — actionlint без нього мовчки пропускає shell-перевірки в run: блоках,',
+      'тому локальний `bun lint-ga` буде зелений, а CI на ubuntu-latest (де shellcheck передвстановлений) падатиме.',
+      'Встанови: macOS — `brew install shellcheck`; Debian/Ubuntu — `sudo apt-get install -y shellcheck`;',
+      'Arch — `sudo pacman -S shellcheck` (ga.mdc)'
+    ].join(' ')
+  )
 }
 
 /**
@@ -978,6 +1006,7 @@ export async function check() {
   await checkLintGaScript(pass, fail)
   await checkLintGaWorkflow(wfDir, pass, fail)
   await checkGitAiWorkflow(wfDir, pass, fail)
+  checkShellcheckInstalled(pass, fail)
 
   return reporter.getExitCode()
 }

package/scripts/lint-ga.mjs

@@ -0,0 +1,158 @@
+/**
+ * CLI-обгортка над канонічним `lint-ga` (ga.mdc): робить preflight на `shellcheck` і `uv` (для `uvx`),
+ * тоді послідовно виконує `bunx github-actionlint` і `uvx zizmor --offline --collect=workflows .`.
+ *
+ * Без preflight `actionlint` (через `bunx github-actionlint`) мовчки пропускає shell-перевірки в
+ * `run:` блоках, коли `shellcheck` відсутній у PATH; локально `bun lint-ga` лишається зеленим, а CI
+ * на ubuntu-latest (де shellcheck передвстановлений) падає. Preflight робить цю різницю явною.
+ *
+ * `uv` потрібен для `uvx zizmor`. Якщо його нема — `uvx zizmor` падає неінформативно («command not
+ * found»); підказка з командою встановлення коротша й корисніша.
+ *
+ * Експортовано окремо `runLintGaCli` — використовується з `bin/n-cursor.js` як підкоманда `lint-ga`.
+ */
+import { spawnSync } from 'node:child_process'
+import { platform } from 'node:process'
+
+import { resolveCmd } from './utils/resolve-cmd.mjs'
+
+/**
+ * Опис залежності preflight-ом: бінарник, для чого потрібен, і команди встановлення.
+ *
+ * @typedef {object} PreflightDep
+ * @property {string} bin ім'я виконуваного файлу (на Windows додається `.exe` за потреби)
+ * @property {string[]} winBins альтернативні імена на Windows (`shellcheck.exe`); якщо нема — fallback на `bin`
+ * @property {string} explanation 1-2 рядки про наслідки відсутності
+ * @property {string[]} install список рядків з командами встановлення (друкуються як є, з відступом)
+ * @property {string} successMsg повідомлення на pass-шлях
+ */
+
+/** @type {PreflightDep} */
+const SHELLCHECK_PREFLIGHT = {
+  bin: 'shellcheck',
+  winBins: ['shellcheck.exe'],
+  explanation: [
+    'Без нього `actionlint` пропускає shell-перевірки в run: блоках,',
+    'тож локальний прогін зеленіє, а CI на ubuntu-latest (де shellcheck',
+    'передвстановлений) падає на тих самих workflow.'
+  ].join('\n   '),
+  install: [
+    'macOS:        brew install shellcheck',
+    'Debian/Ubuntu: sudo apt-get install -y shellcheck',
+    'Arch:         sudo pacman -S shellcheck'
+  ],
+  successMsg: '✅ shellcheck знайдено в PATH — actionlint виконуватиме SC-правила, як у CI'
+}
+
+/** @type {PreflightDep} */
+const UV_PREFLIGHT = {
+  bin: 'uv',
+  winBins: ['uv.exe'],
+  explanation: [
+    'Без `uv` (а отже без `uvx`) не виконається `uvx zizmor` — second-stage аудит',
+    'workflow на ризики GitHub Actions просто не запуститься.'
+  ].join('\n   '),
+  install: [
+    'macOS:        brew install uv',
+    'Universal:    curl -LsSf https://astral.sh/uv/install.sh | sh',
+    'pip:          pip install uv'
+  ],
+  successMsg: '✅ uv знайдено в PATH — uvx zizmor запуститься'
+}
+
+/**
+ * Шукає бінарник у PATH з урахуванням Windows: спершу `winBins`, потім `bin`.
+ * @param {PreflightDep} dep опис залежності
+ * @returns {string | null} абсолютний шлях або null
+ */
+function resolvePreflightBin(dep) {
+  if (platform === 'win32') {
+    for (const name of dep.winBins) {
+      const r = resolveCmd(name)
+      if (r) return r
+    }
+  }
+  return resolveCmd(dep.bin)
+}
+
+/**
+ * Друкує блок з причиною fail і командами встановлення.
+ * @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('   Деталі: ga.mdc → секція про lint-ga.')
+}
+
+/**
+ * Запускає preflight-перевірку: pass → лог success і повертає true; fail → лог hint і повертає false.
+ * @param {PreflightDep} dep опис залежності
+ * @returns {boolean} чи знайдено бінарник
+ */
+function preflight(dep) {
+  if (resolvePreflightBin(dep)) {
+    console.log(dep.successMsg)
+    return true
+  }
+  printPreflightMissingMessage(dep)
+  return false
+}
+
+/**
+ * Запускає крок lint-ga з відображенням команди користувачу. Stdout/stderr дочірнього процесу
+ * передається користувачу як є (`stdio: 'inherit'`), щоб виглядало як прямий виклик у shell.
+ * @param {string} title заголовок для логу (наприклад `actionlint`)
+ * @param {string} cmd ім'я команди (`bunx`, `uvx`)
+ * @param {string[]} args аргументи команди
+ * @returns {number} код виходу дочірнього процесу (0 — OK, інше — помилка)
+ */
+function runStep(title, cmd, args) {
+  console.log(`\n▶ ${title}: ${cmd} ${args.join(' ')}`)
+  const resolved = resolveCmd(cmd)
+  if (!resolved) {
+    console.error(`❌ ${cmd} не знайдено в PATH (${title}).`)
+    return 127
+  }
+  const r = spawnSync(resolved, args, { stdio: 'inherit', env: process.env })
+  if (r.error) {
+    console.error(`❌ Не вдалося запустити ${cmd}: ${r.error.message}`)
+    return 1
+  }
+  return r.status ?? 1
+}
+
+/**
+ * Виконує канонічний `lint-ga` з preflight-перевірками й послідовним запуском actionlint + zizmor.
+ *
+ * Послідовність:
+ * 1) preflight: `shellcheck` (для actionlint SC-правил) і `uv` (для `uvx zizmor`); відсутній → exit 1;
+ * 2) `bunx github-actionlint`;
+ * 3) `uvx zizmor --offline --collect=workflows .`.
+ *
+ * Якщо хоча б один preflight не пройшов — виходимо одразу з кодом 1, **до** запуску actionlint/zizmor,
+ * бо їхні власні повідомлення про відсутність залежностей менш інформативні (особливо для shellcheck —
+ * actionlint мовчки пропускає SC-правила; ця перевірка — головний сенс обгортки).
+ *
+ * Першу помилку від actionlint/zizmor повертаємо як код виходу; наступні кроки не запускаються
+ * (відповідає `&&` у package.json).
+ * @returns {number} 0 — все OK, інакше — код першого кроку, що впав
+ */
+export function runLintGaCli() {
+  let preflightOk = true
+  for (const dep of [SHELLCHECK_PREFLIGHT, UV_PREFLIGHT]) {
+    if (!preflight(dep)) preflightOk = false
+  }
+  if (!preflightOk) return 1
+
+  const actionlintCode = runStep('actionlint', 'bunx', ['github-actionlint'])
+  if (actionlintCode !== 0) return actionlintCode
+
+  const zizmorCode = runStep('zizmor', 'uvx', ['zizmor', '--offline', '--collect=workflows', '.'])
+  return zizmorCode
+}

package/scripts/utils/resolve-cmd.mjs

@@ -14,7 +14,9 @@ import { platform } from 'node:process'
  */
 export function resolveCmd(cmd) {
   const whichCmd = platform === 'win32' ? 'where' : 'which'
-  const result = spawnSync(whichCmd, [cmd], { encoding: 'utf8' })
+  // Явно передаємо `process.env`, інакше Bun вмикає snapshot оточення на старті процесу
+  // і не бачить змін `process.env.PATH` у runtime (типова ситуація — підстановка стабів у тестах).
+  const result = spawnSync(whichCmd, [cmd], { encoding: 'utf8', env: process.env })
   if (result.status !== 0 || result.error) {
     return null
   }