@7n/rules 1.29.3 → 1.31.0

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # Changelog
 
+## [1.31.0] - 2026-07-19
+
+### Changed
+
+- sync: діапазони вже оголошених плагінів @7n/rules-* у package.json підіймаються до ^latest тим самим кроком, що й ядро — фікси плагінів доїжджають без ручного bun update (bun i сам по собі поважає lockfile); недоступний registry для окремого плагіна — warning і пропуск
+- lint: правило style (stylelint/css/vue-стилі) переїхало з ядра у @7n/rules-lang-js — фінальний крок фази 5 spec lang-plugins-extraction по фронтенд-сімʼї
+
+## [1.30.0] - 2026-07-19
+
+### Added
+
+- ensure-tool: закріплені версії зовнішніх CLI-тулів у tool-pins.json (без latest-lookup на звичайному install-шляху) + tool-pins-refresh.mjs для ручного рефрешу + tool-pins-freshness.test.mjs, що нагадує оновити піни після 30 днів
+
+### Fixed
+
+- ensure-tool: GitHub-токен у lookup релізів, redirect-fallback без API і fail-open детекторів на транзієнтні збої авто-встановлення тулів (rate-limit без tag_name більше не валить lint exit 2)
+
 ## [1.29.3] - 2026-07-19
 
 ### Changed

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@7n/rules",
-  "version": "1.29.3",
+  "version": "1.31.0",
   "description": "CLI еталонних правил і skills (префікс n-): синк у репозиторій, дельта-lint, конформність",
   "keywords": [
     "cli",

package/rules/k8s/dremio_logging/dremio_logging.mdc

@@ -39,6 +39,7 @@ JS-детектор (не rego): `main.mjs`, `lint(ctx)`, per-file, glob `**/dre
 **Що перевіряється:** якщо файл визначає `ConfigMap` з `data["logback.xml"]` (bundled-конфіг образу `zookeeper:3.8.4-jre-17`, монтується поверх `/conf/logback.xml`), його `<root level="...">` має бути `warn`/`error`/`off` (case-insensitive) — не `info`/`debug`/`trace` (дефолт бандлованого файлу) і не відсутній.
 
 **Чому:** readiness/liveness `ruok`-проби виконуються кожні ~10s на кожен zk-под; `NIOServerCnxn` логує це на INFO незалежно від навантаження. Керувати рівнем ззовні НЕ вдається для цього образу:
+
 - `ZOO_LOG4J_PROP` — змінна Bitnami-образів, тут взагалі не читається жодним скриптом.
 - `-Dzookeeper.console.threshold=WARN` через `JVMFLAGS` — перебивається `<property name="zookeeper.console.threshold" value="INFO"/>` у бандлованому файлі.
 

package/scripts/docs/index.md

@@ -4,19 +4,20 @@ title: npm/scripts
 resource: npm/scripts/
 ---
 
-| Файл                                                                                | Тип       |
-| ----------------------------------------------------------------------------------- | --------- |
-| [auto-rules.mjs](auto-rules.md)                                                     | JS Module |
-| [auto-skills.mjs](auto-skills.md)                                                   | JS Module |
-| [build-agents-commands.mjs](build-agents-commands.md)                               | JS Module |
-| [cli-entry.mjs](cli-entry.md)                                                       | JS Module |
+| Файл                                                                      | Тип       |
+| ------------------------------------------------------------------------- | --------- |
+| [auto-rules.mjs](auto-rules.md)                                           | JS Module |
+| [auto-skills.mjs](auto-skills.md)                                         | JS Module |
+| [build-agents-commands.mjs](build-agents-commands.md)                     | JS Module |
+| [cli-entry.mjs](cli-entry.md)                                             | JS Module |
 | [ensure-n-rules-dev-dependencies.mjs](ensure-n-rules-dev-dependencies.md) | JS Module |
-| [hook.mjs](hook.md)                                                                 | JS Module |
-| [post-tool-use-check.mjs](post-tool-use-check.md)                                   | JS Module |
-| [rename-yaml-extensions.mjs](rename-yaml-extensions.md)                             | JS Module |
-| [skills-cli.mjs](skills-cli.md)                                                     | JS Module |
-| [smoke-check-imports.mjs](smoke-check-imports.md)                                   | JS Module |
-| [sync-claude-config.mjs](sync-claude-config.md)                                     | JS Module |
-| [sync-setup-bun-deps-action.mjs](sync-setup-bun-deps-action.md)                     | JS Module |
-| [update-blue-oak.mjs](update-blue-oak.md)                                           | JS Module |
+| [hook.mjs](hook.md)                                                       | JS Module |
+| [post-tool-use-check.mjs](post-tool-use-check.md)                         | JS Module |
+| [rename-yaml-extensions.mjs](rename-yaml-extensions.md)                   | JS Module |
+| [skills-cli.mjs](skills-cli.md)                                           | JS Module |
+| [smoke-check-imports.mjs](smoke-check-imports.md)                         | JS Module |
+| [sync-claude-config.mjs](sync-claude-config.md)                           | JS Module |
+| [sync-setup-bun-deps-action.mjs](sync-setup-bun-deps-action.md)           | JS Module |
+| [tool-pins-refresh.mjs](tool-pins-refresh.md)                             | JS Module |
+| [update-blue-oak.mjs](update-blue-oak.md)                                 | JS Module |
 | [upgrade-n-rules-and-install.mjs](upgrade-n-rules-and-install.md)         | JS Module |

package/scripts/docs/tool-pins-refresh.md

@@ -0,0 +1,28 @@
+---
+type: JS Module
+title: tool-pins-refresh.mjs
+resource: npm/scripts/tool-pins-refresh.mjs
+docgen:
+  crc: f2d4811a
+  model: openai-codex/gpt-5.4-mini
+  score: 80
+  judgeModel: openai-codex/gpt-5.4-mini
+---
+
+## Огляд
+
+Оновлює `scripts/lib/tool-pins.json` свіжими релізами закріплених CLI-тулів для `ensure-tool.mjs` і `Linux/Windows-fallback install-шляху`, а також ставить нову дату піна. Використовується як ручний refresh, коли `tool-pins-freshness.test.mjs` червоніє через піни старші за 30 днів, коли у закріпленому тулі відома вразливість або баг, або коли потрібно оновити закріплені версії до актуальних. Для кожного тула з реєстру `TOOLS` бере останній реліз через `fetchLatestVersion` і переписує `tool-pins.json` із новими версіями та сьогоднішнім `pinnedAt`; друкує diff лише для змінених тулів.
+
+## Поведінка
+
+1. Перевіряє, чи доступний `curl`, бо без нього оновлення піна не виконується.
+2. Зчитує поточний стан `tool-pins.json` як джерело правди для закріплених версій і дати піна.
+3. Для кожного закріпленого CLI-тула отримує актуальну версію з upstream-релізів через мережу.
+4. Порівнює нову версію з уже закріпленою і фіксує лише ті позиції, де є зміна.
+5. Перезаписує `tool-pins.json` новим набором версій і сьогоднішньою датою піна.
+6. Показує короткий звіт про зміни: якщо версії не змінилися, окремо повідомляє, що оновилася лише дата піна; якщо зміни є, перелічує, які тули оновилися.
+7. Не торкається звичайного install-потоку: мережеве оновлення версій виконується тільки цим скриптом, а штатне встановлення працює лише з уже закріпленими значеннями.
+
+## Гарантії поведінки
+
+- (специфічних машинно-виведених гарантій немає)

package/scripts/docs/upgrade-n-rules-and-install.md

@@ -3,7 +3,7 @@ type: JS Module
 title: upgrade-n-rules-and-install.mjs
 resource: npm/scripts/upgrade-n-rules-and-install.mjs
 docgen:
-  crc: f33841b9
+  crc: ab3a4cc2
   model: omlx/gemma-4-e4b-it-OptiQ-4bit
   score: 100
   issues: judge:inaccurate:0.98
@@ -28,6 +28,7 @@ shouldSkipNpmVersionUpgrade — Визначає, чи можна замінит
 fetchLatestNRulesVersionFromNpm — Отримує актуальну версію пакета `@7n/rules` з реєстру npm (через поле `version` у JSON dist-tag `latest`), що доступно на https://registry.npmjs.org/@7n/rules/latest.
 resolveInstalledPackageRoot — Знаходить абсолютний шлях до встановленого пакета у директорії `node_modules`, або надає резервний шлях.
 upgradeNRulesToLatestAndBunInstall — Оновлює `@7n/rules` до останньої версії з npm (якщо це дозволено конфігурацією), виконує встановлення залежностей за допомогою `bun i`, і повертає корінь пакета для подальшої синхронізації конфігураційних файлів, таких як `mdc/`.
+upgradePluginRanges — Підіймає діапазони вже оголошених плагінів `@7n/rules-*` у dependencies/devDependencies до `^latest` з npm (мутує pkg; той самий крок, що й для ядра — бо `bun i` поважає lockfile і фікси плагінів інакше не доїжджають). Специфікатори поза npm-semver (workspace:, file:, git…) не чіпає; недоступний registry для окремого плагіна — warning і пропуск.
 
 ## Гарантії поведінки
 

package/scripts/lib/docs/ensure-tool.md

@@ -3,7 +3,7 @@ type: JS Module
 title: ensure-tool.mjs
 resource: npm/scripts/lib/ensure-tool.mjs
 docgen:
-  crc: b1b054d0
+  crc: c77b4b65
 ---
 
 Модуль `ensure-tool.mjs` — єдина точка резолву зовнішніх CLI-залежностей пакета `@7n/rules`. Він гарантує, що потрібний бінарник (`hk`, `conftest`, `shellcheck`, `actionlint`, `dotenv-linter`, `opa`, `regal`, `hadolint`, `kubeconform`, `kubescape`) доступний у системі, виконуючи послідовний пошук:
@@ -15,6 +15,8 @@ docgen:
 
 Така архітектура усуває дублювання install-логіки в кожному `lint.mjs` / `fix.mjs`: щоб додати нову зовнішню утиліту, достатньо одного запису в реєстрі `TOOLS`. Додатково модуль експортує `ensureHkInstall`, який реєструє git pre-commit hook через `hk install` (пропускається в CI).
 
+Версії для GitHub Release install-шляху (Linux, і Windows-fallback коли `scoop` недоступний) — **закріплені** у `scripts/lib/tool-pins.json`, а не резолвляться як `latest` на кожен install. Причина: CI-runner-и ефемерні, локальний кеш бінарників порожній щоразу, і `latest`-lookup через GitHub API на кожен job означає постійний трафік зі спільних CI-IP — і впирається у rate-limit (60 запитів/год без токена). `fetchLatestVersion` (двоступеневий lookup: GitHub API з `GITHUB_TOKEN`/`GH_TOKEN` за наявності → redirect-fallback повз API) лишається в модулі, але викликається лише вручну — окремим скриптом `scripts/tool-pins-refresh.mjs`, не на звичайному install-шляху. `checkToolPinsFreshness()` рахує вік поточного піна (`tool-pins.json.pinnedAt`) у днях і сигналить `stale: true` після `TOOL_PINS_MAX_AGE_DAYS` (30) — на цьому побудований тест `tool-pins-freshness.test.mjs`, що навмисно червоніє, коли піни застаріли, і нагадує запустити рефреш.
+
 Поруч із синхронною `ensureTool` (публічний API пакета, сигнатура не змінюється) модуль експортує async-варіант `ensureToolAsync(toolId)` для parallel lane `detectAll()` (ADR 260716-1354-внутрішній-паралелізм-lint-оркестратора): конкурентні виклики того самого `toolId` в одному Node-процесі колапсують в один install (in-process single-flight), а auto-install крок додатково серіалізується між процесами через `withLock` (ключ `ensure-tool/<toolId>`) — паралельні Node-процеси (різні CI-shard-и, кілька агентів) не тягнуть той самий бінарник конкурентно. Завантажений архів завжди пишеться в унікальний per-call temp-каталог і публікується атомарним `renameSync` під фіксованим flat-іменем `<toolId>` — цей hardened install-крок спільний для sync і async шляхів.
 
 Файл написаний для Node.js (ESM), використовує лише стандартну бібліотеку, локальний хелпер `resolveCmd` і `withLock` (`../utils/with-lock.mjs`) для міжпроцесної серіалізації async-install-кроку.
@@ -26,12 +28,16 @@ docgen:
 | `ensureTool(toolId)`        | `function` | Резолвить і за потреби встановлює зовнішній CLI (sync). Повертає абсолютний шлях до бінарника або кидає `Error`.                                     |
 | `ensureToolAsync(toolId)`   | `function` | Async-варіант для parallel lane `detectAll()`: single-flight (in-process) + `withLock` (cross-process) навколо auto-install кроку. Повертає `Promise<string>`. |
 | `ensureHkInstall(hkBin)`    | `function` | Виконує `hk install` для реєстрації git pre-commit hook. Жодного return value; на помилку лише `console.warn`.                                       |
+| `ToolProvisionError`        | `class`    | Транзієнтний збій авто-встановлення (мережа, обірваний download). Споживачі розпізнають за `name` і можуть спрацювати fail-open (див. `lint-surface/detect.mjs`). |
+| `fetchLatestVersion(repo, curlBin)` | `function` | Резолвить останній тег релізу: GitHub API (з токеном за наявності) → redirect-fallback повз API. На звичайному install-шляху не викликається — лише зі `scripts/tool-pins-refresh.mjs` і юніт-тестів. |
+| `TOOLS`                     | `object`   | Реєстр `Record<string, ToolEntry>` із описом install-стратегії для кожного тула. Read-only; читається `tool-pins-refresh.mjs`. |
+| `TOOL_PINS_MAX_AGE_DAYS`    | `number`   | Поріг «застарілості» піна версій у днях (30). |
+| `checkToolPinsFreshness(now?)` | `function` | Вік поточного `tool-pins.json.pinnedAt` у днях відносно `now` (за замовчуванням `Date.now()`). Повертає `{ pinnedAt, ageDays, stale }`. |
 
 Внутрішні (не експортуються, але формують контракт модуля):
 
-- `TOOLS` — реєстр `Record<string, ToolEntry>` із описом install-стратегії для кожного тула.
 - `ToolEntry` — JSDoc-тип, що описує поля одного запису реєстру.
-- Допоміжні функції: `getCacheDir`, `mapArch`, `fetchLatestVersion`, `installFromGithub`, `installViaBrew`, `installViaScoop`, `autoInstall`, `buildHint`.
+- Допоміжні функції: `getCacheDir`, `mapArch`, `githubAuthArgs`, `fetchLatestVersionViaApi`, `fetchLatestVersionViaRedirect`, `readToolPins`, `resolvePinnedVersion`, `installFromGithub`, `installViaBrew`, `installViaScoop`, `autoInstall`, `buildHint`.
 
 ## Функції
 
@@ -64,13 +70,24 @@ docgen:
   - `repo` — репозиторій у форматі `owner/repo`.
   - `curlBin` — абсолютний шлях до бінарника `curl`.
 - **Повертає:** версію останнього релізу без префікса `v` (наприклад `0.4.1`).
-- **Поведінка:** через `spawnSync` викликає `curl -sSL -H "Accept: application/vnd.github+json" https://api.github.com/repos/<repo>/releases/latest`, парсить JSON, бере поле `tag_name`, прибирає префікс `v` за допомогою регексу `TAG_V_PREFIX_RE`.
-- **Помилки:**
-  - `curl failed: ...` — `r.error` ненульове.
-  - `curl exit <status>: ...` — ненульовий exit-код.
-  - `GitHub API response is not JSON: ...` — некоректний JSON.
-  - `GitHub API: tag_name missing for <repo>` — у відповіді немає `tag_name`.
-- **Side effects:** мережевий HTTP-запит до GitHub API.
+- **Поведінка:** двоступеневий lookup.
+  1. GitHub API: `curl -sSL https://api.github.com/repos/<repo>/releases/latest` з `Accept: application/vnd.github+json`; якщо в env є `GITHUB_TOKEN` (або `GH_TOKEN`) — додається `Authorization: Bearer <token>`, що піднімає rate-limit із 60/год (per-IP, вичерпується на shared CI-runner-ах) до 5000/год. Парсить JSON, бере `tag_name`, прибирає префікс `v`.
+  2. Redirect-fallback (при будь-якому збої API): `https://github.com/<repo>/releases/latest` переадресовує на `…/releases/tag/<tag>`; тег читається з фінального URL (`curl -sIL -w '%{url_effective}'`). Веб-endpoint не підпадає під API rate-limit.
+- **Помилки:** кидає `ToolProvisionError` лише коли не вдались обидва шляхи; повідомлення містить обидві причини (для API-відповіді без `tag_name` — і її `message`, напр. «API rate limit exceeded»).
+- **Side effects:** мережеві HTTP-запити до GitHub.
+
+### `readToolPins()`
+
+- **Сигнатура:** `readToolPins(): { pinnedAt: string, versions: Record<string, string> }`
+- **Повертає:** розпарсений `tool-pins.json`. Читається синхронно на кожен виклик (без module-level кешу) — довгоживучий процес одразу бачить щойно застосований рефреш.
+- **Side effects:** синхронне читання файлу `scripts/lib/tool-pins.json`.
+
+### `resolvePinnedVersion(toolId)`
+
+- **Сигнатура:** `resolvePinnedVersion(toolId: string): string`
+- **Повертає:** закріплену версію тула з `tool-pins.json.versions[toolId]` (без префікса `v`).
+- **Помилки:** якщо для `toolId` немає запису у `versions` — кидає звичайний (не `ToolProvisionError`) `Error`: це конфігураційна помилка (тул зареєстрували в `TOOLS`, але забули додати пін), а не транзієнтний збій.
+- **Side effects:** делегує в `readToolPins()`.
 
 ### `installFromGithub(toolId, entry, cacheDir)`
 
@@ -82,7 +99,7 @@ docgen:
 - **Повертає:** абсолютний шлях до встановленого бінарника.
 - **Послідовність дій:**
   1. Резолвить `curl` та `tar` у PATH; за відсутності — кидає `Error`.
-  2. Через `fetchLatestVersion` отримує актуальну версію.
+  2. Через `resolvePinnedVersion(toolId)` бере закріплену версію з `tool-pins.json` — жодного мережевого `latest`-lookup на цьому кроці.
   3. Формує назву asset через `entry.asset(ver)` і URL `https://github.com/<github>/releases/download/v<ver>/<asset>`.
   4. Створює `cacheDir` (`mkdirSync` з `recursive: true`) і унікальний per-call temp-каталог усередині нього (`mkdtempSync(join(cacheDir, '.tmp-<toolId>-'))`) — той самий filesystem гарантує, що фінальний `renameSync` не впаде з `EXDEV`.
   5. Завантажує asset у temp-каталог через `curl -sSL -o <tmpDir>/<asset> <downloadUrl>`.
@@ -90,12 +107,20 @@ docgen:
   7. Інакше викликає `tar` із прапорцем `-xJf` (для `.tar.xz`) або `-xzf` (для `.tar.gz`) для розпакування в temp-каталог, знаходить реальний шлях бінарника через `entry.binFinder(ver)` або просто `toolId`, перевіряє його існування — і так само атомарним `renameSync` публікує його у `<cacheDir>/<toolId>` (flat-ім'я, незалежно від вкладеної структури архіву).
   8. У `finally` прибирає весь temp-каталог (`rmSync(tmpDir, { recursive: true, force: true })`) — і архів, і проміжні файли розпакування зникають одним викликом.
 - **Помилки:**
-  - `curl не знайдено в PATH — потрібен для завантаження <toolId>`.
-  - `tar не знайдено в PATH — потрібен для встановлення <toolId>`.
-  - `Завантаження <toolId> не вдалось: ...` / `curl exit <status> при завантаженні <toolId>: ...`.
-  - `tar failed for <toolId>: ...` / `tar exit <status> для <toolId>: ...`.
-  - `Бінарник <toolId> не знайдено після розпакування: <extractedBin>`.
-- **Side effects:** мережа, файлова система (унікальний temp-каталог, атомарна публікація, chmod, очищення temp).
+  - `curl не знайдено в PATH — потрібен для завантаження <toolId>` (`Error` — конфігурація середовища).
+  - `tar не знайдено в PATH — потрібен для встановлення <toolId>` (`Error`).
+  - `ensureTool: немає закріпленої версії для '<toolId>' у tool-pins.json — ...` (`Error` — конфігурація, з `resolvePinnedVersion`).
+  - `Завантаження <toolId> не вдалось: ...` / `curl exit <status> при завантаженні <toolId>: ...` (`ToolProvisionError` — транзієнтний мережевий збій).
+  - `tar failed for <toolId>: ...` / `tar exit <status> для <toolId>: ...` (`Error`).
+  - `Бінарник <toolId> не знайдено після розпакування: <extractedBin>` (`Error`).
+- **Side effects:** мережа (лише download, без `latest`-lookup), файлова система (унікальний temp-каталог, атомарна публікація, chmod, очищення temp).
+
+### `checkToolPinsFreshness(now?)` _(export)_
+
+- **Сигнатура:** `checkToolPinsFreshness(now?: number): { pinnedAt: string, ageDays: number, stale: boolean }`
+- **Параметри:** `now` — час порівняння в ms epoch; за замовчуванням `Date.now()`.
+- **Повертає:** `pinnedAt` з `tool-pins.json`, обчислений `ageDays` (`Math.floor`) і `stale` — `true`, якщо `ageDays > TOOL_PINS_MAX_AGE_DAYS` (30).
+- **Side effects:** делегує в `readToolPins()`.
 
 ### `installViaBrew(toolId, entry)`
 
@@ -174,10 +199,11 @@ docgen:
 ### Стандартна бібліотека Node.js
 
 - `node:child_process` — `spawnSync` для синхронного запуску `curl`, `tar`, `brew`, `scoop`, `rm`, `hk`.
-- `node:fs` — `chmodSync`, `existsSync`, `mkdirSync`, `renameSync`.
+- `node:fs` — `chmodSync`, `existsSync`, `mkdirSync`, `mkdtempSync`, `readFileSync` (читання `tool-pins.json`), `renameSync`, `rmSync`.
 - `node:os` — `homedir` для побудови шляху кешу.
-- `node:path` — `join` для конструювання шляхів.
+- `node:path` — `dirname`, `join` для конструювання шляхів.
 - `node:process` — `arch`, `env`, `platform`.
+- `node:url` — `fileURLToPath` для резолву абсолютного шляху `tool-pins.json` поряд із модулем.
 
 ### Внутрішні
 
@@ -208,14 +234,14 @@ docgen:
 4. Перевірка `/home/<user>/.cache/@7n/rules/bin/shellcheck` — не існує.
 5. `N_CURSOR_NO_AUTO_INSTALL` не виставлено → `autoInstall(...)`.
 6. На Linux диспетчер викликає `installFromGithub('shellcheck', entry, cacheDir)`:
-   - `fetchLatestVersion('koalaman/shellcheck', curl)` → наприклад `0.10.0`.
-   - asset name = `shellcheck-v0.10.0.linux.x86_64.tar.xz`.
-   - URL = `https://github.com/koalaman/shellcheck/releases/download/v0.10.0/<asset>`.
+   - `resolvePinnedVersion('shellcheck')` читає `tool-pins.json.versions.shellcheck` → наприклад `0.11.0` (мережевого запиту немає).
+   - asset name = `shellcheck-v0.11.0.linux.x86_64.tar.xz`.
+   - URL = `https://github.com/koalaman/shellcheck/releases/download/v0.11.0/<asset>`.
    - `mkdirSync(cacheDir, { recursive: true })` і унікальний `tmpDir = mkdtempSync(join(cacheDir, '.tmp-shellcheck-'))`.
    - `curl -sSL -o <tmpDir>/<asset> <url>`.
    - `tar -xJf <asset> -C <tmpDir>` (бо `.tar.xz`).
-   - `binFinder('0.10.0')` → `<tmpDir>/shellcheck-v0.10.0/shellcheck`; перевірка `existsSync`.
-   - Атомарний `renameSync(<tmpDir>/shellcheck-v0.10.0/shellcheck, <cacheDir>/shellcheck)` — публікація під flat-іменем.
+   - `binFinder('0.11.0')` → `<tmpDir>/shellcheck-v0.11.0/shellcheck`; перевірка `existsSync`.
+   - Атомарний `renameSync(<tmpDir>/shellcheck-v0.11.0/shellcheck, <cacheDir>/shellcheck)` — публікація під flat-іменем.
    - `rmSync(tmpDir, { recursive: true, force: true })` у `finally`.
    - Повертає `<cacheDir>/shellcheck`.
 7. Викликач отримує абсолютний шлях і запускає `spawnSync(bin, [...args])`.
@@ -250,7 +276,24 @@ ensureHkInstall(hkBin) // git hook у .git/hooks/pre-commit
 2. Знайти GitHub-репо релізів і визначити `archStyle` (`hk` / `conftest` / `actionlint`).
 3. Описати `asset(ver)` та, якщо потрібно, `binFinder(ver)` (коли бінарник лежить не в корені архіву).
 4. Виставити `archive: false` для прямого бінарника без архіву.
-5. Додати запис у `TOOLS`. Жодних змін у викликачах не потрібно — `ensureTool('foo')` запрацює одразу.
+5. Додати запис у `TOOLS`.
+6. Додати закріплену версію в `tool-pins.json.versions.foo` (напр. запустивши `bun npm/scripts/tool-pins-refresh.mjs` — підхопить новий тул автоматично) — без цього кроку `installFromGithub('foo', …)` на Linux/Windows-fallback впаде з конфігураційною помилкою `немає закріпленої версії для 'foo'`.
+
+Жодних змін у викликачах не потрібно — `ensureTool('foo')` запрацює одразу.
+
+### Рефреш закріплених версій (`tool-pins-refresh.mjs`)
+
+`scripts/lib/tool-pins.json` не оновлюється сам собою — це навмисно (інакше повернулася б проблема з постійними `latest`-lookup-ами). Рефреш — окрема ручна дія:
+
+```sh
+bun npm/scripts/tool-pins-refresh.mjs
+```
+
+Скрипт іде по `TOOLS`, для кожного тула резолвить `fetchLatestVersion(entry.github, curl)` (GitHub API з токеном за наявності → redirect-fallback), переписує `tool-pins.json` свіжими версіями і сьогоднішньою `pinnedAt`, друкує diff версій. Коли запускати:
+
+- тест `tool-pins-freshness.test.mjs` червоніє (`checkToolPinsFreshness().stale === true`, пінам > `TOOL_PINS_MAX_AGE_DAYS` днів);
+- відома вразливість/баг у закріпленому тулі — рефреш раніше терміну;
+- просто хочеться підняти версії тулів на актуальні.
 
 ### Гарантії та інваріанти
 
@@ -258,3 +301,4 @@ ensureHkInstall(hkBin) // git hook у .git/hooks/pre-commit
 - **Hard-fail:** на будь-яку нерозв’язну помилку install кидається `Error` із описовим повідомленням; немає silent fallback на «обірваний» бінарник.
 - **Кросплатформність:** єдиний публічний API для трьох ОС; OS-specific деталі інкапсульовані всередині модуля.
 - **Безпека для CI:** `ensureHkInstall` ніколи не змінює git-репозиторій під CI, навіть якщо `hk` доступний.
+- **Без `latest`-lookup на звичайному install-шляху:** `installFromGithub` бере версію з закріпленого `tool-pins.json`; `fetchLatestVersion` викликається лише з `tool-pins-refresh.mjs` (ручний рефреш) і тестів — CI-job на порожньому кеші не робить запиту до GitHub API для резолву версії.

package/scripts/lib/ensure-tool.mjs

@@ -4,6 +4,17 @@
  * `ensureTool(toolId)` — єдиний seam резолву зовнішніх бінарників: PATH → кеш → авто-install → hard-fail.
  * Новий тул = один запис у реєстрі `TOOLS`, без дублювання install-логіки в кожному `lint.mjs`/`fix.mjs`.
  *
+ * Версії GitHub Release-тулів (Linux/Windows-fallback install-шлях) — **закріплені** у
+ * `tool-pins.json`, а не резолвляться як `latest` на кожен install: CI-runner-и ефемерні,
+ * кеш бінарників порожній щоразу, і `latest`-lookup на кожен job = постійний трафік у
+ * GitHub API з shared-IP (rate-limit). `fetchLatestVersion` (GitHub API з `GITHUB_TOKEN`/
+ * `GH_TOKEN` за наявності, з fallback-ом на redirect `releases/latest` повз API) лишається
+ * — це «мотор» для ручного рефрешу пінів (`tool-pins-refresh.mjs`), у звичайному install
+ * не викликається. `checkToolPinsFreshness()` — гейт «пінам більше 30 днів → час
+ * рефрешнути» (тест `tool-pins-freshness.test.mjs`). Транзієнтні збої download-у
+ * кидаються як `ToolProvisionError` (fail-open seam для lint-детекторів — див.
+ * `lint-surface/detect.mjs`).
+ *
  * Per-platform matrix: macOS → brew, Windows → scoop (fallback: GitHub Release), Linux → GitHub Release binary.
  * Бінарники кешуються у `~/.cache/@7n/rules/bin/` (Linux/Mac), `%LOCALAPPDATA%\@7n\cursor\bin\` (Win).
  * Download завжди пишеться в унікальний per-call temp-каталог і публікується атомарним `renameSync` —
@@ -17,10 +28,11 @@
  * `ensureHkInstall(hkBin)` — реєструє git pre-commit hook через `hk install`; пропускається в CI.
  */
 import { spawnSync } from 'node:child_process'
-import { chmodSync, existsSync, mkdirSync, mkdtempSync, renameSync, rmSync } from 'node:fs'
+import { chmodSync, existsSync, mkdirSync, mkdtempSync, readFileSync, renameSync, rmSync } from 'node:fs'
 import { homedir } from 'node:os'
-import { join } from 'node:path'
+import { dirname, join } from 'node:path'
 import { arch, env, platform } from 'node:process'
+import { fileURLToPath } from 'node:url'
 
 import { resolveCmd } from '../utils/resolve-cmd.mjs'
 import { withLock } from '../utils/with-lock.mjs'
@@ -28,6 +40,68 @@ import { withLock } from '../utils/with-lock.mjs'
 /** Префікс `v` у git-тегу релізу (`v1.2.3` → `1.2.3`). */
 const TAG_V_PREFIX_RE = /^v/
 
+/** Тег релізу з фінального URL redirect-у `releases/latest` (`…/releases/tag/v1.2.3`). */
+const RELEASE_TAG_URL_RE = /\/tag\/([^/\s]+)\s*$/
+
+/** Кількість мілісекунд у добі — для перетворення віку піна в дні. */
+const DAY_MS = 24 * 60 * 60 * 1000
+
+/** Поріг «застарілості» пінів версій (`tool-pins.json.pinnedAt`) у днях. */
+export const TOOL_PINS_MAX_AGE_DAYS = 30
+
+/** Абсолютний шлях до `tool-pins.json`, поряд із цим модулем. */
+const TOOL_PINS_PATH = join(dirname(fileURLToPath(import.meta.url)), 'tool-pins.json')
+
+/**
+ * Читає `tool-pins.json` — синхронно, свіжим на кожен виклик (без module-level кешу),
+ * щоб `ensureTool*`-виклики в довгоживучому процесі бачили щойно застосований рефреш.
+ * @returns {{ pinnedAt: string, versions: Record<string, string> }} закріплені версії й дата піна
+ */
+function readToolPins() {
+  return JSON.parse(readFileSync(TOOL_PINS_PATH, 'utf8'))
+}
+
+/**
+ * Вік поточних пінів версій у днях від `pinnedAt` до `now`.
+ * @param {number} [now] час порівняння (ms epoch); за замовчуванням `Date.now()`
+ * @returns {{ pinnedAt: string, ageDays: number, stale: boolean }} вік і чи перевищено `TOOL_PINS_MAX_AGE_DAYS`
+ */
+export function checkToolPinsFreshness(now = Date.now()) {
+  const { pinnedAt } = readToolPins()
+  const ageDays = Math.floor((now - Date.parse(pinnedAt)) / DAY_MS)
+  return { pinnedAt, ageDays, stale: ageDays > TOOL_PINS_MAX_AGE_DAYS }
+}
+
+/**
+ * Резолвить закріплену версію тула з `tool-pins.json`. Конфігураційна помилка (не
+ * `ToolProvisionError`) — відсутність піна для наявного в `TOOLS` тула означає, що
+ * його забули додати в `tool-pins.json` при реєстрації, а не транзієнтний збій.
+ * @param {string} toolId ключ у `TOOLS`
+ * @returns {string} закріплена версія без префікса `v`
+ */
+function resolvePinnedVersion(toolId) {
+  const { versions } = readToolPins()
+  const version = versions[toolId]
+  if (!version) {
+    throw new Error(`ensureTool: немає закріпленої версії для '${toolId}' у tool-pins.json — додай перед install-ом`)
+  }
+  return version
+}
+
+/**
+ * Транзієнтний збій авто-встановлення зовнішнього тула (GitHub API rate-limit, мережа,
+ * обірваний download). Відрізняється від конфігураційних помилок (невідомий тул,
+ * `N_CURSOR_NO_AUTO_INSTALL`, відсутній curl) — споживачі розпізнають за `name`
+ * і можуть спрацювати fail-open замість валити весь прогін.
+ */
+export class ToolProvisionError extends Error {
+  /** @param {string} message причина збою */
+  constructor(message) {
+    super(message)
+    this.name = 'ToolProvisionError'
+  }
+}
+
 /**
  * Повертає каталог керованого кешу бінарників для поточного OS.
  * @returns {string} абсолютний шлях
@@ -68,8 +142,12 @@ function mapArch(nodeArch, style) {
  * @property {((ver: string) => string)|null} [binFinder] для архівів де бінарник не у корені; повертає відносний шлях
  */
 
-/** @type {Record<string, ToolEntry>} */
-const TOOLS = {
+/**
+ * Реєстр install-стратегій. Експортовано read-only для `tool-pins-refresh.mjs`
+ * (ітерує `entry.github`, щоб рефрешнути `tool-pins.json`) — не мутуй.
+ * @type {Record<string, ToolEntry>}
+ */
+export const TOOLS = {
   hk: {
     brew: 'hk',
     scoop: 'hk',
@@ -156,15 +234,27 @@ const TOOLS = {
   }
 }
 
+/**
+ * Заголовки авторизації GitHub для curl: `GITHUB_TOKEN`/`GH_TOKEN` з env, якщо є.
+ * Токен піднімає rate-limit API з 60/год (per-IP, вичерпується на shared CI-runner-ах)
+ * до 5000/год (per-token).
+ * @returns {string[]} додаткові аргументи curl (порожньо без токена)
+ */
+function githubAuthArgs() {
+  const token = env['GITHUB_TOKEN'] ?? env['GH_TOKEN']
+  return token ? ['-H', `Authorization: Bearer ${token}`] : []
+}
+
 /**
  * Отримує останній тег з GitHub Releases API через curl (sync).
  * @param {string} repo репо у форматі `owner/repo`
  * @param {string} curlBin абсолютний шлях до curl
  * @returns {string} рядок версії без префікса `v`, наприклад `0.4.1`
  */
-function fetchLatestVersion(repo, curlBin) {
+function fetchLatestVersionViaApi(repo, curlBin) {
   const url = `https://api.github.com/repos/${repo}/releases/latest`
-  const r = spawnSync(curlBin, ['-sSL', '-H', 'Accept: application/vnd.github+json', url], { encoding: 'utf8' })
+  const args = ['-sSL', '-H', 'Accept: application/vnd.github+json', ...githubAuthArgs(), url]
+  const r = spawnSync(curlBin, args, { encoding: 'utf8' })
   if (r.error) throw new Error(`curl failed: ${r.error.message}`)
   if (r.status !== 0) throw new Error(`curl exit ${r.status}: ${(r.stderr ?? '').slice(0, 300)}`)
   let parsed
@@ -174,13 +264,60 @@ function fetchLatestVersion(repo, curlBin) {
     throw new Error(`GitHub API response is not JSON: ${r.stdout.slice(0, 200)}`)
   }
   const tag = parsed['tag_name']
-  if (!tag) throw new Error(`GitHub API: tag_name missing for ${repo}`)
+  if (!tag) {
+    // Без tag_name API типово повертає message («API rate limit exceeded …») — показуємо його
+    const apiMessage = typeof parsed['message'] === 'string' ? ` (${parsed['message'].slice(0, 200)})` : ''
+    throw new Error(`GitHub API: tag_name missing for ${repo}${apiMessage}`)
+  }
   return tag.replace(TAG_V_PREFIX_RE, '')
 }
 
 /**
- * Завантажує та розпаковує GitHub Release бінарник у кеш-директорію.
- * Повертає абсолютний шлях до бінарника.
+ * Fallback-резолюція останнього тега без API: `https://github.com/<repo>/releases/latest`
+ * переадресовує на `…/releases/tag/<tag>` — читаємо тег з фінального URL (`%{url_effective}`).
+ * Веб-endpoint не підпадає під API rate-limit, тож працює і на shared-runner-ах без токена.
+ * @param {string} repo репо у форматі `owner/repo`
+ * @param {string} curlBin абсолютний шлях до curl
+ * @returns {string} рядок версії без префікса `v`
+ */
+function fetchLatestVersionViaRedirect(repo, curlBin) {
+  const url = `https://github.com/${repo}/releases/latest`
+  const r = spawnSync(curlBin, ['-sIL', '-w', '%{url_effective}', url], { encoding: 'utf8' })
+  if (r.error) throw new Error(`curl failed: ${r.error.message}`)
+  if (r.status !== 0) throw new Error(`curl exit ${r.status}: ${(r.stderr ?? '').slice(0, 300)}`)
+  const m = RELEASE_TAG_URL_RE.exec(r.stdout)
+  if (!m) throw new Error(`releases/latest redirect без /tag/ у фінальному URL для ${repo}`)
+  return m[1].replace(TAG_V_PREFIX_RE, '')
+}
+
+/**
+ * Отримує останній тег релізу: спершу GitHub API (з токеном за наявності), при збої —
+ * redirect-fallback повз API. Кидає `ToolProvisionError`, лише якщо не вдались обидва шляхи.
+ * Експортовано для юніт-тестів; основний споживач — `installFromGithub`.
+ * @param {string} repo репо у форматі `owner/repo`
+ * @param {string} curlBin абсолютний шлях до curl
+ * @returns {string} рядок версії без префікса `v`, наприклад `0.4.1`
+ */
+export function fetchLatestVersion(repo, curlBin) {
+  let apiError
+  try {
+    return fetchLatestVersionViaApi(repo, curlBin)
+  } catch (error) {
+    apiError = error
+  }
+  try {
+    return fetchLatestVersionViaRedirect(repo, curlBin)
+  } catch (error) {
+    throw new ToolProvisionError(
+      `latest-release lookup не вдався для ${repo} — API: ${apiError.message}; redirect: ${error.message}`
+    )
+  }
+}
+
+/**
+ * Завантажує та розпаковує GitHub Release бінарник у кеш-директорію. Версія береться
+ * закріпленою з `tool-pins.json` — жодного `latest`-lookup у GitHub API на звичайному
+ * install-шляху. Повертає абсолютний шлях до бінарника.
  * @param {string} toolId ключ у TOOLS
  * @param {ToolEntry} entry опис тула
  * @param {string} cacheDir абсолютний шлях до кешу
@@ -192,7 +329,7 @@ function installFromGithub(toolId, entry, cacheDir) {
   const tarBin = resolveCmd('tar')
   if (!tarBin) throw new Error(`tar не знайдено в PATH — потрібен для встановлення ${toolId}`)
 
-  const ver = fetchLatestVersion(entry.github, curlBin)
+  const ver = resolvePinnedVersion(toolId)
   const assetName = entry.asset(ver)
   const downloadUrl = `https://github.com/${entry.github}/releases/download/v${ver}/${assetName}`
 
@@ -204,10 +341,11 @@ function installFromGithub(toolId, entry, cacheDir) {
   try {
     const archivePath = join(tmpDir, assetName)
 
+    // Збої download-у — транзієнтні (мережа/GitHub), тому ToolProvisionError, як і lookup вище.
     const dlResult = spawnSync(curlBin, ['-sSL', '-o', archivePath, downloadUrl], { encoding: 'utf8' })
-    if (dlResult.error) throw new Error(`Завантаження ${toolId} не вдалось: ${dlResult.error.message}`)
+    if (dlResult.error) throw new ToolProvisionError(`Завантаження ${toolId} не вдалось: ${dlResult.error.message}`)
     if (dlResult.status !== 0) {
-      throw new Error(
+      throw new ToolProvisionError(
         `curl exit ${dlResult.status} при завантаженні ${toolId}: ${(dlResult.stderr ?? '').slice(0, 300)}`
       )
     }

package/scripts/lib/lint-surface/detect.mjs

@@ -105,6 +105,26 @@ function normalizeResult(raw, ctx) {
   return diagnostics.length > 0 ? { violations, diagnostics } : { violations }
 }
 
+/**
+ * Fail-open результат для транзієнтного збою авто-встановлення зовнішнього тула
+ * (`ToolProvisionError` з `ensure-tool.mjs`, розпізнається за `name` — errors можуть
+ * приходити з іншого інстансу модуля). GitHub API rate-limit чи мережевий збій на
+ * CI-runner-і не має валити весь lint-прогін exit 2: concern пропускається з
+ * видимою warn-діагностикою, а не тихо.
+ * @param {LintContext} ctx контекст лінту (джерело ruleId/concernId)
+ * @param {Error} error транзієнтна помилка встановлення тула
+ * @returns {LintResult} порожні violations + warn-діагностика про пропуск
+ */
+function toolProvisionSkipResult(ctx, error) {
+  const message = `⚠️ ${ctx.ruleId}/${ctx.concernId} пропущено (транзієнтний збій встановлення тула): ${error.message}`
+  // Diagnostics рендеряться лише у verbose — дублюємо у stderr, щоб пропуск було видно в CI-логах завжди.
+  console.warn(message)
+  return {
+    violations: [],
+    diagnostics: [{ level: 'warn', message }]
+  }
+}
+
 /**
  * Чи має concern ручний (не-`@generated`) `main.mjs`, що перекриває policy-adapter.
  * @param {string} mainPath абсолютний шлях до `main.mjs` concern-а.
@@ -140,6 +160,7 @@ export async function runConcernDetector(concern, ctx) {
         missingMessage: concern.policy.missingMessage
       })
     } catch (error) {
+      if (error?.name === 'ToolProvisionError') return toolProvisionSkipResult(ctx, error)
       throw new DetectorError(ctx.ruleId, ctx.concernId, `policy-adapter кинув: ${error.message}`)
     }
     return normalizeResult(raw, ctx)
@@ -163,6 +184,7 @@ export async function runConcernDetector(concern, ctx) {
   try {
     raw = await mod.lint(ctx)
   } catch (error) {
+    if (error?.name === 'ToolProvisionError') return toolProvisionSkipResult(ctx, error)
     throw new DetectorError(ctx.ruleId, ctx.concernId, `lint() кинув: ${error.message}`)
   }
   return normalizeResult(raw, ctx)

package/scripts/lib/lint-surface/docs/detect.md

@@ -3,9 +3,8 @@ type: JS Module
 title: detect.mjs
 resource: npm/scripts/lib/lint-surface/detect.mjs
 docgen:
-  crc: 6080123e
+  crc: cf3febf6
   model: openai-codex/gpt-5.5
-  tier: cloud-avg
   score: 90
   issues: internal-name:evaluatePolicyConcern,judge:inaccurate:0.92
   judgeModel: openai-codex/gpt-5.4-mini
@@ -19,11 +18,12 @@ docgen:
 
 - `DetectorError` позначає збій detector-а або невалідний результат як помилку інфраструктури лінту, щоб unified lint surface міг завершитись із технічним failure.
 - `runConcernDetector` запускає один concern-detector у read-only режимі, обирає policy-оцінювання за `concern.json` або ручний detector, нормалізує результат до єдиного формату й перетворює аномалії на `DetectorError`.
+- Виняток із fail-fast: помилка з `name === 'ToolProvisionError'` (транзієнтний збій авто-встановлення зовнішнього тула з `ensure-tool.mjs` — GitHub API rate-limit, мережа, обірваний download) не кидається як `DetectorError`. Concern пропускається fail-open: повертаються порожні `violations` + warn-діагностика, а попередження дублюється у stderr (`console.warn`), щоб пропуск було видно в CI-логах і без verbose. Розпізнавання за `name` — помилка може приходити з іншого інстансу модуля `ensure-tool.mjs`.
 
 ## Публічний API
 
 - DetectorError — позначає збій detector-а або непридатний результат; такий стан завершує виконання з exit 2.
-- runConcernDetector — запускає detector для одного concern-а, приводить відповідь до очікуваного формату й перетворює будь-яку аномалію на `DetectorError`.
+- runConcernDetector — запускає detector для одного concern-а, приводить відповідь до очікуваного формату й перетворює будь-яку аномалію на `DetectorError`; транзієнтні `ToolProvisionError` натомість дають fail-open пропуск concern-а з warn-діагностикою.
 
 Код спирається на конфіг `concern.json`.
 
@@ -35,4 +35,4 @@ Concern-и без policy і без `main.mjs` вважаються помилк
 
 ## Гарантії поведінки
 
-- Read-only: не виконує операцій запису (ФС/БД).
+- Read-only: не виконує операцій запису (ФС/БД); єдиний side effect — `console.warn` при fail-open пропуску concern-а через `ToolProvisionError`.