@nitra/cursor 1.8.165 → 1.8.167

package/CHANGELOG.md

@@ -4,6 +4,23 @@
 
 Формат — [Keep a Changelog](https://keepachangelog.com/uk/1.1.0/), нумерація — [SemVer](https://semver.org/lang/uk/).
 
+## [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.5'
 ---
 
 У `.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,22 @@ 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. Перевірку наявності [`shellcheck`](https://www.shellcheck.net/) у `PATH` — без нього `actionlint` мовчки пропускає shell-перевірки в `run:` блоках, тож локальний прогін зеленіє, а CI на `ubuntu-latest` (де shellcheck передвстановлений) падає на тих самих workflow. Якщо бінарника немає — `bun lint-ga` падає одразу, до запуску `actionlint`. Встановлення: `brew install shellcheck` (macOS), `sudo apt-get install -y shellcheck` (Debian/Ubuntu), `sudo pacman -S shellcheck` (Arch).
+2. `bunx github-actionlint`.
+3. `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.167",
   "description": "CLI для завантаження cursor-правил (префікс n-) у локальний репозиторій",
   "keywords": [
     "cli",
@@ -49,6 +49,6 @@
     "node": ">=25"
   },
   "devDependencies": {
-    "@nitra/cursor": "^1.8.165"
+    "@nitra/cursor": "^1.8.167"
   }
 }

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,85 @@
+/**
+ * CLI-обгортка над канонічним `lint-ga` (ga.mdc): додає preflight на наявність `shellcheck`,
+ * тоді послідовно виконує `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 робить цю різницю явною.
+ *
+ * Експортовано окремо `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'
+
+/** Підказки встановлення shellcheck на типових платформах. */
+const SHELLCHECK_INSTALL_HINTS = [
+  'macOS:        brew install shellcheck',
+  'Debian/Ubuntu: sudo apt-get install -y shellcheck',
+  'Arch:         sudo pacman -S shellcheck'
+]
+
+/**
+ * Друкує блок з причиною fail і командами встановлення `shellcheck`.
+ * @returns {void}
+ */
+function printShellcheckMissingMessage() {
+  console.error('❌ shellcheck не знайдено в PATH.')
+  console.error('   Без нього `actionlint` пропускає shell-перевірки в run: блоках,')
+  console.error('   тож локальний прогін зеленіє, а CI на ubuntu-latest (де shellcheck')
+  console.error('   передвстановлений) падає на тих самих workflow. Встанови:')
+  for (const line of SHELLCHECK_INSTALL_HINTS) {
+    console.error(`     ${line}`)
+  }
+  console.error('   Деталі: ga.mdc → секція про lint-ga.')
+}
+
+/**
+ * Запускає крок 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 на `shellcheck`.
+ *
+ * Послідовність:
+ * 1) перевірка наявності `shellcheck` у PATH (на Windows — `shellcheck.exe`); відсутній → exit 1;
+ * 2) `bunx github-actionlint`;
+ * 3) `uvx zizmor --offline --collect=workflows .`.
+ *
+ * Першу помилку повертаємо як код виходу; наступні кроки не запускаються (відповідає `&&` у package.json).
+ * @returns {number} 0 — все OK, інакше — код першого кроку, що впав
+ */
+export function runLintGaCli() {
+  const shellcheckBin = platform === 'win32' ? 'shellcheck.exe' : 'shellcheck'
+  if (!resolveCmd(shellcheckBin)) {
+    printShellcheckMissingMessage()
+    return 1
+  }
+  console.log('✅ shellcheck знайдено в PATH — actionlint виконуватиме SC-правила, як у CI')
+
+  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
   }