@nitra/cursor 1.8.167 → 1.8.168

package/CHANGELOG.md

@@ -4,6 +4,13 @@
 
 Формат — [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

package/mdc/ga.mdc

@@ -1,7 +1,7 @@
 ---
 description: Правила форматів для .github/workflows
 alwaysApply: true
-version: '1.5'
+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 у тригері як у фрагментах.
@@ -243,9 +243,11 @@ jobs:
 
 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 .`.
+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):
 

package/package.json

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

package/scripts/lint-ga.mjs

@@ -1,11 +1,14 @@
 /**
- * CLI-обгортка над канонічним `lint-ga` (ga.mdc): додає preflight на наявність `shellcheck`,
+ * 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'
@@ -13,28 +16,94 @@ 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'
-]
+/**
+ * Опис залежності 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 і командами встановлення `shellcheck`.
+ * Друкує блок з причиною fail і командами встановлення.
+ * @param {PreflightDep} dep опис залежності
  * @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) {
+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.
@@ -59,23 +128,27 @@ function runStep(title, cmd, args) {
 }
 
 /**
- * Виконує канонічний `lint-ga` з preflight на `shellcheck`.
+ * Виконує канонічний `lint-ga` з preflight-перевірками й послідовним запуском actionlint + zizmor.
  *
  * Послідовність:
- * 1) перевірка наявності `shellcheck` у PATH (на Windows — `shellcheck.exe`); відсутній → exit 1;
+ * 1) preflight: `shellcheck` (для actionlint SC-правил) і `uv` (для `uvx zizmor`); відсутній → exit 1;
  * 2) `bunx github-actionlint`;
  * 3) `uvx zizmor --offline --collect=workflows .`.
  *
- * Першу помилку повертаємо як код виходу; наступні кроки не запускаються (відповідає `&&` у package.json).
+ * Якщо хоча б один preflight не пройшов — виходимо одразу з кодом 1, **до** запуску actionlint/zizmor,
+ * бо їхні власні повідомлення про відсутність залежностей менш інформативні (особливо для shellcheck —
+ * actionlint мовчки пропускає SC-правила; ця перевірка — головний сенс обгортки).
+ *
+ * Першу помилку від actionlint/zizmor повертаємо як код виходу; наступні кроки не запускаються
+ * (відповідає `&&` у package.json).
  * @returns {number} 0 — все OK, інакше — код першого кроку, що впав
  */
 export function runLintGaCli() {
-  const shellcheckBin = platform === 'win32' ? 'shellcheck.exe' : 'shellcheck'
-  if (!resolveCmd(shellcheckBin)) {
-    printShellcheckMissingMessage()
-    return 1
+  let preflightOk = true
+  for (const dep of [SHELLCHECK_PREFLIGHT, UV_PREFLIGHT]) {
+    if (!preflight(dep)) preflightOk = false
   }
-  console.log('✅ shellcheck знайдено в PATH — actionlint виконуватиме SC-правила, як у CI')
+  if (!preflightOk) return 1
 
   const actionlintCode = runStep('actionlint', 'bunx', ['github-actionlint'])
   if (actionlintCode !== 0) return actionlintCode