@nitra/cursor 5.1.0 → 5.2.1

package/.claude-template/settings.template.json

@@ -20,6 +20,28 @@
             "timeout": 300
           }
         ]
+      },
+      {
+        "matcher": "Edit|Write|MultiEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "npx --no @nitra/cursor doc-files check --hook",
+            "timeout": 120
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "npx --no @nitra/cursor doc-files check --git",
+            "timeout": 120
+          }
+        ]
       }
     ]
   }

package/.pi-template/extensions/n-cursor-adr/docs/index.md

@@ -1,3 +1,9 @@
+---
+docgen:
+  source: npm/.pi-template/extensions/n-cursor-adr/index.ts
+  crc: 3233716f
+---
+
 # index.ts
 
 ## Огляд
@@ -23,12 +29,12 @@
 
 ## Гарантії поведінки
 
-*   Доступ до файлу дозволений
-*   Операція запису та модифікації даних дозволена
-*   При виникненні помилок система перехоплює їх
-*   Система не генерує винятків назовні
-*   Система не використовує кешування
-*   Система не виконує операцій з мережею
-*   Логіка пропуску та обмеження швидкості залишається у бах (bash)
-*   Логіка вибору LLM-CLI залишається у бах (bash)
-*   Перевірка рекурсії здійснюється через змінні середовища встановлені бах перед запуском LLM CLI
+- Доступ до файлу дозволений
+- Операція запису та модифікації даних дозволена
+- При виникненні помилок система перехоплює їх
+- Система не генерує винятків назовні
+- Система не використовує кешування
+- Система не виконує операцій з мережею
+- Логіка пропуску та обмеження швидкості залишається у бах (bash)
+- Логіка вибору LLM-CLI залишається у бах (bash)
+- Перевірка рекурсії здійснюється через змінні середовища встановлені бах перед запуском LLM CLI

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # Changelog
 
+## [5.2.1] - 2026-06-11
+
+### Changed
+
+- adr
+
+## [5.2.0] - 2026-06-11
+
+### Changed
+
+- doc-files: local-only конвеєр (Крок 0 за ADR 260610-2228) — спільний npm/lib/llm.mjs з роутингом за префіксом omlx/ і wire-trace; видалено cloud-ескалації та pre-route sym; degraded-маркер score/issues у frontmatter, gen --retry-degraded і check --degraded; preflight omlx (down/memory-guard/auth) перед масовим прогоном; callOmlx шле Authorization Bearer (N_CURSOR_OMLX_KEY або ~/.omlx/settings.json)
+- doc-files: міграція корпусу док на CRC-контракт — 126 git-актуальним докам застамповано frontmatter (дока не старіша за джерело за git-історією); 76 файлів (73 git-відсталі доки + 3 без док) лишено stale як чесний беклог перегенерації локальним конвеєром
+
+### Fixed
+
+- lint: санація шарів, що ховалися за першим падінням oxlint — повний bun run lint доведено до lint-js/style зелених: JSDoc/regex/sonarjs фікси у ~25 файлах, slow-regex обмежено bounded-квантифікаторами, eslint ignore для згенерованих docs/*.md, jscpd ignore (.git, COVERAGE.md, docs, відомі легасі-клони), knip ignoreBinaries (pi/claude/fix-t0), stylelint/cspell ignore згенерованих артефактів; docgen-ignore у doc-aggregate став re-export з doc-files
+
 ## [5.1.0] - 2026-06-10
 
 ### Changed
@@ -75,7 +92,7 @@
 
 ### Added
 
-- lib/models.mjs: global model tier classification (LOCAL_MIN/AVG/MAX, CLOUD_MIN/AVG/MAX) via N_*_MODEL env vars; fix llm-worker uses CLOUD_MIN/AVG by default
+- lib/models.mjs: global model tier classification (LOCAL*MIN/AVG/MAX, CLOUD_MIN/AVG/MAX) via N*\*\_MODEL env vars; fix llm-worker uses CLOUD_MIN/AVG by default
 
 ### Changed
 

package/bin/n-cursor.js

@@ -25,8 +25,11 @@
  *   `npx \@nitra/cursor lint-docker` — канонічний lint-docker (docker.mdc): `hadolint` по `Dockerfile`/`*.Dockerfile`
  *   `npx \@nitra/cursor lint-text`   — канонічний lint-text (text.mdc): `cspell` → `shellcheck` (з auto-fix) →
  *                                     `markdownlint-cli2 --fix` → `v8r` (json/json5/yaml/yml/toml)
- *   `npx \@nitra/cursor docgen scan`    — детермінований JSON-лістинг кодових файлів для скілу docgen (відносні `sourcePath`; ignore-glob snippet у `npm/skills/docgen/js/docgen-ignore.mjs`; тека `docs/` поряд із джерелом)
- *   `npx \@nitra/cursor docgen modules` — детермінований JSON-лістинг логічних модулів (межі за `package.json`) для Tier 2 скілу docgen
+ *   `npx \@nitra/cursor doc-files scan`  — JSON-лістинг кодових файлів зі станом застарілості (`stale`: `missing`|`crc-mismatch`) для обовʼязкового скілу doc-files (ignore-glob у `npm/skills/doc-files/js/docgen-ignore.mjs`; тека `docs/` поряд із джерелом)
+ *   `npx \@nitra/cursor doc-files check` — детектор застарілості для hook'ів (`--hook` PostToolUse, `--git` Stop-гейт із порогом `--max`); exit 2 — стале знайдено
+ *   `npx \@nitra/cursor doc-files gen`   — JS-оркестрована генерація файлових док (роутинг local/cloud) зі штампом CRC у frontmatter (`--limit`/`--from`/`--overwrite`)
+ *   `npx \@nitra/cursor doc-files stamp` — детерміновано (пере)штампувати CRC у наявних доках без LLM
+ *   `npx \@nitra/cursor doc-aggregate modules` — JSON-лістинг логічних модулів (межі за `package.json`) для Tier 2 скілу doc-aggregate
  *   `npx \@nitra/cursor skill list`     — скіли пакета без синку в проєкт
  *   `npx \@nitra/cursor skill taze`     — промпт на stdout
  *   `npx \@nitra/cursor skill cursor taze ["task"]` — Cursor CLI (`cursor-agent -p`)
@@ -663,6 +666,22 @@ function buildClaudeWorktreeEnforcementSectionLines() {
   ]
 }
 
+/**
+ * Рендерить секцію для CLAUDE.md: doc-files — обовʼязковий крок задачі (як lint).
+ * Після зміни кодового файлу його дока має бути перегенерована; застарілість
+ * детермінується за CRC і контролюється Stop-hook'ом.
+ * @returns {string[]} рядки для вставки (з порожнім рядком на початку)
+ */
+function buildClaudeDocFilesSectionLines() {
+  return [
+    '',
+    '## Файлова документація (`doc-files` — обовʼязковий крок, як lint)',
+    '',
+    'Після зміни чи додавання кодового файлу його файлова дока (`<dir>/docs/<stem>.md`) має бути **актуальною** — це **обовʼязковий крок кожної задачі**, нарівні з lint. Застарілість детермінується за **CRC** джерела у frontmatter доки. PostToolUse hook (`doc-files check --hook`) **сигналить** про дрейф після правки; Stop-hook (`doc-files check --git`) **блокує завершення** задачі за наявності застарілих док (виняток — масовий прогін понад поріг `N_CURSOR_DOC_FILES_GATE_MAX`, дефолт 50). Регенерація — `/doc-files` (JS-оркестрована, не диспатч субагентів). Агрегуюча дока (module-summary, доменні) — окремий скіл `/doc-aggregate`, за запитом.',
+    ''
+  ]
+}
+
 /**
  * Рендерить секцію Skills для CLAUDE.md з урахуванням наявних slash-команд.
  * @returns {Promise<string[]>} готові рядки секції (або порожній масив)
@@ -722,7 +741,11 @@ async function syncClaudeMd(ignore) {
     lines.push(`@${RULES_DIR}/${mdcFile}`)
   }
 
-  lines.push(...buildClaudeLintParallelismSectionLines(), ...buildClaudeWorktreeEnforcementSectionLines())
+  lines.push(
+    ...buildClaudeLintParallelismSectionLines(),
+    ...buildClaudeWorktreeEnforcementSectionLines(),
+    ...buildClaudeDocFilesSectionLines()
+  )
 
   const skillsSectionLines = await buildClaudeSkillsSectionLines()
   lines.push(...skillsSectionLines)
@@ -1550,7 +1573,7 @@ async function runSync() {
 /**
  * Команди, що мутують проєкт у CWD і вимагають кореня репо. `undefined`/`''` —
  * дефолтний sync; `check` — deprecated-alias `fix`. Решта (read-only `trace`,
- * `--root`-команди `docgen`/`rename-yaml-extensions`, `worktree`,
+ * `--root`-команди `doc-files`/`doc-aggregate`/`rename-yaml-extensions`, `worktree`,
  * sub-лінтери) гард не зачіпає.
  */
 const ROOT_GUARDED_COMMANDS = new Set([undefined, '', 'fix', 'check', 'lint', 'coverage', 'change', 'release'])
@@ -1596,7 +1619,7 @@ try {
   // .n-cursor.json + bun install, а fix/lint/coverage/change/release переписують файли в CWD —
   // усе це ключиться на cwd(). Запуск із піддиректорії git-репо (типово прямий
   // `bun npm/bin/n-cursor.js` не з кореня) зачепив би не той каталог → STOP. Read-only та
-  // `--root`-команди (trace, graph, docgen, rename-yaml-extensions) не зачіпаємо.
+  // `--root`-команди (trace, graph, doc-files, doc-aggregate, rename-yaml-extensions) не зачіпаємо.
   if (ROOT_GUARDED_COMMANDS.has(command)) {
     assertCwdIsProjectRoot(cwd(), describeRootGuardedAction(command))
   }
@@ -1765,17 +1788,51 @@ try {
 
       break
     }
-    case 'docgen': {
-      // n-cursor docgen scan|modules — детермінований лістинг для скілу docgen.
-      // scan — кодові файли; modules — логічні модулі (межі за package.json).
-      // Друкує JSON; генерацію доки робить скіл, диспатчачи субагентів.
-      const { runDocgenScanCli, runDocgenModulesCli } = await import('../skills/docgen/js/docgen-scan.mjs')
-      if (args[0] === 'scan') {
-        process.exitCode = await runDocgenScanCli(args.slice(1))
-      } else if (args[0] === 'modules') {
-        process.exitCode = await runDocgenModulesCli(args.slice(1))
+    case 'doc-files': {
+      // n-cursor doc-files scan|check|gen|stamp — обовʼязковий крок задачі (як lint):
+      // файлова дока поряд із джерелом, застарілість за CRC у frontmatter.
+      //   scan  — JSON-лістинг кодових файлів зі станом stale (missing|crc-mismatch);
+      //   check — детектор застарілості для hook'ів (--hook PostToolUse, --git Stop-гейт);
+      //   gen   — JS-оркестрована генерація доки (роутинг local/cloud) + CRC-штамп;
+      //   stamp — детерміновано (пере)штампувати CRC у наявних доках без LLM.
+      switch (args[0]) {
+        case 'scan': {
+          const { runDocFilesScanCli } = await import('../skills/doc-files/js/docgen-scan.mjs')
+          process.exitCode = runDocFilesScanCli(args.slice(1))
+          break
+        }
+        case 'check': {
+          const { runDocFilesCheckCli } = await import('../skills/doc-files/js/docgen-scan.mjs')
+          process.exitCode = await runDocFilesCheckCli(args.slice(1))
+          break
+        }
+        case 'gen': {
+          const { runDocFilesGenCli } = await import('../skills/doc-files/js/docgen-files-batch.mjs')
+          process.exitCode = await runDocFilesGenCli(args.slice(1))
+          break
+        }
+        case 'stamp': {
+          const { runDocFilesStampCli } = await import('../skills/doc-files/js/docgen-files-batch.mjs')
+          process.exitCode = runDocFilesStampCli(args.slice(1))
+          break
+        }
+        default: {
+          console.error('Usage: npx @nitra/cursor doc-files <scan|check|gen|stamp> [--root <dir>]')
+          process.exitCode = 1
+        }
+      }
+
+      break
+    }
+    case 'doc-aggregate': {
+      // n-cursor doc-aggregate modules — детермінований лістинг логічних модулів
+      // (межі за package.json) для Tier 2 module-summary скілу doc-aggregate.
+      // Друкує JSON; module-summary і доменні доки пише скіл, диспатчачи субагентів.
+      const { runDocAggregateModulesCli } = await import('../skills/doc-aggregate/js/docgen-scan.mjs')
+      if (args[0] === 'modules') {
+        process.exitCode = await runDocAggregateModulesCli(args.slice(1))
       } else {
-        console.error('Usage: npx @nitra/cursor docgen <scan|modules> [--root <dir>]')
+        console.error('Usage: npx @nitra/cursor doc-aggregate <modules> [--root <dir>]')
         process.exitCode = 1
       }
 
@@ -1790,7 +1847,7 @@ try {
     default: {
       console.error(`❌ Невідома команда: ${command}`)
       console.error(
-        `   Очікується: (без аргументів) синхронізація правил, fix, check, rename-yaml-extensions, post-tool-use-fix, lint, lint-ga, lint-rego, lint-k8s, lint-docker, lint-text, coverage, coverage-fix, taze, start-check, fix-t0, change, release, skill, worktree, lint-ci, trace, docgen`
+        `   Очікується: (без аргументів) синхронізація правил, fix, check, rename-yaml-extensions, post-tool-use-fix, lint, lint-ga, lint-rego, lint-k8s, lint-docker, lint-text, coverage, coverage-fix, taze, start-check, fix-t0, change, release, skill, worktree, lint-ci, trace, doc-files, doc-aggregate`
       )
       process.exitCode = 1
     }

package/docs/stryker.config.md

@@ -1,3 +1,9 @@
+---
+docgen:
+  source: npm/stryker.config.mjs
+  crc: b8c7377b
+---
+
 # stryker.config.mjs
 
 ## Огляд

package/docs/vitest.config.md

@@ -1,3 +1,9 @@
+---
+docgen:
+  source: npm/vitest.config.js
+  crc: d4917e1f
+---
+
 # vitest.config.js
 
 ## Огляд

package/lib/docs/llm.md

@@ -0,0 +1,29 @@
+---
+docgen:
+  source: npm/lib/llm.mjs
+  crc: 9ef9f20f
+---
+
+# llm
+
+## Огляд
+
+Єдина точка LLM-викликів для JS-оркестраторів монорепо: ховає вибір транспорту за конвенцією префікса model-id і дає preflight-перевірку локального сервера перед масовими прогонами.
+
+## Поведінка
+
+1. Виклик із model-id з префіксом `omlx/` іде прямим HTTP до локального omlx-сервера зі збереженням ролей повідомлень; будь-який інший model-id (зокрема порожній) — через `pi` CLI, де повідомлення конкатенуються в один текстовий промпт, а інструменти вимкнено.
+2. Якщо виставлено `N_CURSOR_LLM_TRACE` зі шляхом до файлу, кожен виклик дописує один JSONL-рядок: бекенд, модель, тривалість, розміри промпта/відповіді, успіх або текст помилки. Невдалий запис трейсу не впливає на сам виклик.
+3. Preflight локального сервера робить мінімальний запит (одна позиція виходу) і класифікує стан: сервер лежить (`down`), модель не влазить у динамічну стелю пам'яті зайнятої машини (`memory-guard`), сервер вимагає API-ключ (`auth`), інша помилка (`error`). Порожня відповідь живого сервера вважається здоровим станом.
+
+## Публічний API
+
+- `callLlm` — універсальний виклик за messages-масивом із маршрутизацією за префіксом model-id.
+- `pickBackend` — назва бекенда (`omlx` чи `pi`) для заданого model-id.
+- `omlxHealthCheck` — preflight-стан локального сервера: `{ ok, reason, detail }`.
+
+## Гарантії поведінки
+
+- Маршрутизація залежить лише від рядка моделі — жодних env-перемикачів бекенда.
+- Помилка транспорту прокидається винятком; трейс при цьому фіксує невдачу.
+- `memory-guard` означає «машина зайнята, спробуй пізніше», а не дефект моделі чи конвеєра.

package/lib/docs/models.md

@@ -1,30 +1,37 @@
+---
+docgen:
+  source: npm/lib/models.mjs
+  crc: feb82992
+  score: 100
+---
+
 # models.mjs
 
 ## Огляд
 
-Файл визначає ієрархічну класифікацію моделей для системи pi. Класифікація встановлює зв'язок між локальними та хмарними провайдерами. Функція resolveModel забезпечує маршрутизацію вибору моделі залежно від заданого рівня доступності.
+Файл визначає глобальну класифікацію моделей для системи pi, встановлюючи конфігураційні моделі для локального та хмарного інференсу через змінні середовища (наприклад, `N_LOCAL_MIN_MODEL`). Значення моделі мають формат "provider/model-id".
+
+Система надає механізм каскадного вибору моделі через функцію `resolveModel`. Цей механізм послідовно перевіряє локальні тири (`LOCAL_MIN` $\rightarrow$ `LOCAL_AVG` $\rightarrow$ `LOCAL_MAX`), а потім хмарні тири, якщо попередні не визначені. Це забезпечує прозору роботу, навіть якщо локальні моделі відсутні. Прямі константи (наприклад, `LOCAL_MIN`) залишені для випадків, що вимагають явного контролю над вибором моделі.
 
 ## Поведінка
 
-LOCAL_MIN встановлює мінімальний локальний провайдер
-LOCAL_AVG встановлює середній локальний провайдер
-LOCAL_MAX встановлює максимальний локальний провайдер
-CLOUD_MIN встановлює мінімальний хмарний провайдер
-CLOUD_AVG встановлює середній хмарний провайдер
-CLOUD_MAX встановлює максимальний хмарний провайдер
-resolveModel повертає перший непорожній model-id з каскадного перевірки локальних та хмарних провайдерів
-resolveModel приймає тир min avg або max
-resolveModel повертає model-id або порожній рядок якщо жоден тир не задано
+LOCAL_MIN повертає модель для швидкого локального інференсу, або порожній рядок, якщо змінна середовища не встановлена.
+LOCAL_AVG повертає модель для середнього локального інференсу, або порожній рядок, якщо змінна середовища не встановлена.
+LOCAL_MAX повертає модель для максимального локального інференсу, або порожній рядок, якщо змінна середовища не встановлена.
+CLOUD_MIN повертає модель для мінімального хмарного інференсу, або порожній рядок, якщо змінна середовища не встановлена.
+CLOUD_AVG повертає модель для середнього хмарного інференсу, або порожній рядок, якщо змінна середовища не встановлена.
+CLOUD_MAX повертає модель для максимального хмарного інференсу, або порожній рядок, якщо змінна середовища не встановлена.
+resolveModel повертає перший непорожній model-id для запитаного тиру, каскадно перевіряючи локальні тири, а потім хмарний еквівалент, або порожній рядок, якщо жоден тир не задано.
 
 ## Публічний API
 
-LOCAL_MIN — Виконує швидкий локальний inference.
-LOCAL_AVG — Виконує середній локальний inference.
-LOCAL_MAX — Виконує максимальний локальний inference.
-CLOUD_MIN — Виконує мінімальний хмарний inference.
-CLOUD_AVG — Виконує середній хмарний inference.
-CLOUD_MAX — Виконує максимальний хмарний inference.
-resolveModel — Повертає перший непорожній model-id для запиту, перевіряючи спочатку локальні, а потім хмарні варіанти.
+LOCAL_MIN — Швидке виконання моделі на локальному пристрої.
+LOCAL_AVG — Середнє за продуктивністю виконання моделі на локальному пристрої.
+LOCAL_MAX — Найпотужніше виконання моделі на локальному пристрої.
+CLOUD_MIN — Найменш ресурсомістке виконання моделі в хмарі.
+CLOUD_AVG — Середній рівень продуктивності виконання моделі в хмарі.
+CLOUD_MAX — Найпотужніше виконання моделі в хмарі.
+resolveModel — Знаходить і повертає ідентифікатор моделі, починаючи з локальних варіантів, а потім переходячи до хмарних відповідників.
 
 ## Гарантії поведінки
 

package/lib/docs/omlx.md

@@ -0,0 +1,32 @@
+---
+docgen:
+  source: npm/lib/omlx.mjs
+  crc: e29efc97
+---
+
+# omlx
+
+## Огляд
+
+Спільний транспорт до локального omlx-сервера (OpenAI-сумісний MLX-inference на `http://127.0.0.1:8000/v1/chat/completions`). Text-only: сервер не підтримує інструменти, тож модуль шле лише повідомлення й читає текст відповіді.
+
+## Поведінка
+
+1. Виклик будує запит з повідомленнями, моделлю, температурою і лімітом виходу; model-id з префіксом `omlx/` нормалізується до чистого імені, порожній — замінюється дефолтною моделлю (`mlx-community--gemma-4-e2b-it-4bit`, override через `N_CURSOR_OMLX_MODEL`).
+2. Endpoint береться з `N_CURSOR_OMLX_URL` або дефолтний.
+3. Якщо на сервері ввімкнено API-ключ, він резолвиться в порядку: явний параметр виклику → `N_CURSOR_OMLX_KEY` → поле `auth.api_key` з локального `~/.omlx/settings.json` (читання fail-safe) — і шлеться як `Authorization: Bearer`. Без знайденого ключа заголовок не додається.
+4. Тимчасові обриви з'єднання (передача перервана, порожня відповідь, збій прийому) ретраяться до трьох спроб; решта помилок — виняток одразу.
+5. Помилка API у тілі відповіді, невалідний JSON чи порожній контент — виняток із діагностичним префіксом `omlx …`.
+
+## Публічний API
+
+- `callOmlx` — синхронний chat-виклик, повертає непорожній текст відповіді.
+- `isOmlxModel` / `omlxModelId` — перевірка і зняття префікса `omlx/`.
+- `resolveOmlxApiKey` — резолвінг API-ключа за описаним порядком джерел.
+- `DEFAULT_OMLX_URL` / `DEFAULT_OMLX_MODEL` — дефолти endpoint і моделі.
+
+## Гарантії поведінки
+
+- Жодних `tools`/`tool_calls` у запиті — сумісність із text-only сервером.
+- Ролі повідомлень (`system`/`user`) передаються без злиття.
+- Виняток ніколи не ковтається: викликач завжди дізнається про збій.

package/lib/llm.mjs

@@ -0,0 +1,137 @@
+/**
+ * Єдина точка LLM-викликів для JS-оркестраторів (див. ADR 260610-2228).
+ *
+ * Маршрутизація — виключно за префіксом model-id (конвенція `npm/lib/models.mjs`):
+ *   `omlx/<model>` → прямий HTTP до локального omlx-сервера (`callOmlx`)
+ *   будь-що інше   → `pi` CLI (хмарні провайдери або pi-дефолт)
+ *
+ * Жодних env-перемикачів бекенда: рядок моделі сам визначає транспорт.
+ *
+ * Wire-trace (ADR 260610-1516/1524): якщо виставлено `N_CURSOR_LLM_TRACE=<file>`,
+ * кожен виклик append-ить один JSONL-рядок з бекендом, моделлю, тривалістю і
+ * розмірами prompt/output. Трейс fail-safe: помилка запису не ламає виклик.
+ */
+import { spawnSync } from 'node:child_process'
+import { appendFileSync } from 'node:fs'
+import { env } from 'node:process'
+
+import { callOmlx, isOmlxModel } from './omlx.mjs'
+
+/** Дефолтний timeout одного виклику (узгоджено з LOCAL_TIMEOUT доки-конвеєра). */
+const DEFAULT_TIMEOUT_MS = 120_000
+
+/**
+ * Бекенд для model-id: `omlx` — прямий HTTP, `pi` — CLI.
+ * @param {string} model model-id (можливо порожній — pi-дефолт)
+ * @returns {'omlx'|'pi'} назва бекенда
+ */
+export function pickBackend(model) {
+  return isOmlxModel(model) ? 'omlx' : 'pi'
+}
+
+/**
+ * Fail-safe append JSONL-рядка трейсу у файл з `N_CURSOR_LLM_TRACE`.
+ * @param {object} entry один запис трейсу
+ */
+function trace(entry) {
+  const file = env.N_CURSOR_LLM_TRACE
+  if (!file) return
+  try {
+    appendFileSync(file, JSON.stringify(entry) + '\n')
+  } catch {
+    // трейс не має ламати основний виклик
+  }
+}
+
+/**
+ * Виклик через `pi` CLI: messages конкатенуються у plain prompt
+ * (pi не приймає messages-масив), tools вимкнено.
+ * @param {Array<{role:string, content:string}>} messages OpenAI-style messages
+ * @param {string} model model-id для `--model` (порожній — pi-дефолт)
+ * @param {number} timeoutMs ліміт очікування процесу
+ * @returns {string} stdout відповіді
+ */
+function callPi(messages, model, timeoutMs) {
+  const prompt = messages.map(m => m.content).join('\n\n')
+  const modelArgs = model ? ['--model', model] : []
+  const r = spawnSync('pi', ['-p', prompt, ...modelArgs, '--no-session', '--mode', 'text', '--no-tools'], {
+    encoding: 'utf8',
+    timeout: timeoutMs
+  })
+  if (r.error) throw new Error(`pi error: ${r.error.message}`)
+  if (r.status !== 0) throw new Error(`pi exit ${r.status}: ${r.stderr?.slice(0, 300) ?? ''}`)
+  return r.stdout?.trim() ?? ''
+}
+
+/**
+ * Універсальний LLM-виклик з маршрутизацією за префіксом model-id.
+ * @param {Array<{role:string, content:string}>} messages OpenAI-style messages (system зберігається на omlx)
+ * @param {string} model model-id; `omlx/<m>` → прямий HTTP, інакше → pi CLI
+ * @param {{ timeoutMs?: number, temperature?: number, maxTokens?: number, url?: string }} [opts] timeout, температура, ліміт виходу, override URL
+ * @returns {string} текст відповіді (непорожній на omlx; pi може повернути '')
+ */
+export function callLlm(messages, model, opts = {}) {
+  const { timeoutMs = DEFAULT_TIMEOUT_MS, temperature = 0.2, maxTokens, url } = opts
+  const backend = pickBackend(model)
+  const t0 = Date.now()
+  const promptChars = messages.reduce((n, m) => n + (m.content?.length ?? 0), 0)
+  try {
+    const out =
+      backend === 'omlx'
+        ? callOmlx(messages, model, { url, timeoutMs, temperature, ...(maxTokens ? { maxTokens } : {}) })
+        : callPi(messages, model, timeoutMs)
+    trace({
+      ts: new Date().toISOString(),
+      backend,
+      model,
+      ms: Date.now() - t0,
+      promptChars,
+      outChars: out.length,
+      ok: true
+    })
+    return out
+  } catch (error) {
+    trace({
+      ts: new Date().toISOString(),
+      backend,
+      model,
+      ms: Date.now() - t0,
+      promptChars,
+      ok: false,
+      error: String(error.message).slice(0, 200)
+    })
+    throw error
+  }
+}
+
+/** Фрагмент повідомлення omlx про memory-guard (динамічна стеля пам'яті). */
+const MEMORY_GUARD_MARKER = 'memory ceiling'
+/** Тип помилки omlx про відсутній/хибний API-ключ. */
+const AUTH_ERROR_MARKER = 'authentication_error'
+
+/**
+ * Preflight-перевірка omlx перед масовим прогоном: мінімальний chat-виклик
+ * (`max_tokens: 1`). Розрізняє стани, які вимагають різних дій:
+ *   - `down`         — сервер не відповідає (не запущений / не той порт);
+ *   - `memory-guard` — модель не влазить у динамічну стелю пам'яті зайнятої
+ *                      машини → «відклади прогін», а не «модель погана»;
+ *   - `auth`         — сервер вимагає API-ключ → вистав `N_CURSOR_OMLX_KEY`;
+ *   - `error`        — інша помилка API.
+ * Порожній контент відповіді — це ok: сервер живий і модель завантажена.
+ * @param {{ url?: string, model?: string, timeoutMs?: number }} [opts] override URL/моделі/timeout перевірки
+ * @returns {{ ok: boolean, reason: 'down'|'memory-guard'|'auth'|'error'|null, detail: string }} стан сервера і класифікована причина збою
+ */
+export function omlxHealthCheck(opts = {}) {
+  const { url, model = '', timeoutMs = DEFAULT_TIMEOUT_MS } = opts
+  try {
+    callOmlx([{ role: 'user', content: 'ok' }], model, { url, timeoutMs, maxTokens: 1, temperature: 0 })
+    return { ok: true, reason: null, detail: '' }
+  } catch (error) {
+    const detail = String(error.message)
+    if (detail.includes(MEMORY_GUARD_MARKER)) return { ok: false, reason: 'memory-guard', detail }
+    if (detail.includes(AUTH_ERROR_MARKER)) return { ok: false, reason: 'auth', detail }
+    if (detail.startsWith('omlx empty content')) return { ok: true, reason: null, detail }
+    if (detail.startsWith('omlx curl')) return { ok: false, reason: 'down', detail }
+    return { ok: false, reason: 'error', detail }
+  }
+}

package/lib/omlx.mjs

@@ -11,13 +11,40 @@
  * Так `resolveModel(tier)` лишається незмінним: достатньо виставити локальний
  * тир у форматі `N_LOCAL_MIN_MODEL=omlx/mlx-community--gemma-4-e2b-it-4bit`, і
  * виклик сам піде напряму в omlx замість pi.
+ *
+ * Auth: якщо в omlx увімкнено API-ключ, він резолвиться через
+ * `resolveOmlxApiKey` (opts → `N_CURSOR_OMLX_KEY` → `~/.omlx/settings.json`)
+ * і шлеться як `Authorization: Bearer …`.
  */
 import { spawnSync } from 'node:child_process'
+import { readFileSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
 import { env } from 'node:process'
 
 /** Дефолтний endpoint omlx (override — `N_CURSOR_OMLX_URL`). */
 export const DEFAULT_OMLX_URL = 'http://127.0.0.1:8000/v1/chat/completions'
 
+/**
+ * API-ключ для omlx-сервера, коли в ньому ввімкнено auth
+ * (`~/.omlx/settings.json` → `auth.skip_api_key_verification: false`).
+ * Порядок: явний `apiKey` → env `N_CURSOR_OMLX_KEY` → `auth.api_key` із
+ * локального `~/.omlx/settings.json` (zero-config для власної машини; читання
+ * fail-safe) → `null` (заголовок не шлеться).
+ * @param {string} [apiKey] явний ключ із opts виклику
+ * @returns {string|null} ключ для `Authorization: Bearer …` або null
+ */
+export function resolveOmlxApiKey(apiKey) {
+  if (apiKey) return apiKey
+  if (env.N_CURSOR_OMLX_KEY) return env.N_CURSOR_OMLX_KEY
+  try {
+    const settings = JSON.parse(readFileSync(join(homedir(), '.omlx', 'settings.json'), 'utf8'))
+    return settings?.auth?.api_key || null
+  } catch {
+    return null
+  }
+}
+
 /** Дефолтна модель, якщо в id лишився голий `omlx/` (override — `N_CURSOR_OMLX_MODEL`). */
 export const DEFAULT_OMLX_MODEL = 'mlx-community--gemma-4-e2b-it-4bit'
 
@@ -46,10 +73,9 @@ export function omlxModelId(model) {
  * Прямий HTTP-виклик до omlx через `curl` (spawnSync). Повертає текст
  * `choices[0].message.content`. Ретраїть лише transient curl-помилки
  * (18 = transfer closed, 52 = empty reply, 56 = recv failure).
- *
  * @param {Array<{role:string, content:string}>} messages OpenAI-messages (system+user збережено)
  * @param {string} model model-id (з/без `omlx/`-префікса); порожній → дефолт
- * @param {{ url?: string, timeoutMs?: number, temperature?: number, maxTokens?: number, fallbackModel?: string }} [opts]
+ * @param {{ url?: string, timeoutMs?: number, temperature?: number, maxTokens?: number, fallbackModel?: string, apiKey?: string }} [opts] URL, timeout, температура, ліміт виходу, fallback-модель, API-ключ
  * @returns {string} непорожній контент відповіді
  * @throws на curl-помилці, не-200 exit, поганому JSON чи порожньому контенті
  */
@@ -59,18 +85,37 @@ export function callOmlx(messages, model, opts = {}) {
     timeoutMs = 60_000,
     temperature = 0.2,
     maxTokens = 4096,
-    fallbackModel = env.N_CURSOR_OMLX_MODEL ?? DEFAULT_OMLX_MODEL
+    fallbackModel = env.N_CURSOR_OMLX_MODEL ?? DEFAULT_OMLX_MODEL,
+    apiKey
   } = opts
 
   const m = omlxModelId(model) || fallbackModel
   const body = JSON.stringify({ model: m, messages, max_tokens: maxTokens, temperature })
+  // Ключ локального сервера в argv допустимий: localhost-секрет власної машини,
+  // короткоживучий процес; stdin уже зайнятий body (`--data-binary @-`).
+  const key = resolveOmlxApiKey(apiKey)
+  const authArgs = key ? ['-H', `Authorization: Bearer ${key}`] : []
 
   const TRANSIENT_CURL_CODES = new Set([18, 52, 56])
   let lastErr
   for (let attempt = 1; attempt <= 3; attempt++) {
     const r = spawnSync(
       'curl',
-      ['-sS', '-X', 'POST', url, '-H', 'Content-Type: application/json', '-H', 'Connection: close', '--max-time', String(Math.ceil(timeoutMs / 1000)), '--data-binary', '@-'],
+      [
+        '-sS',
+        '-X',
+        'POST',
+        url,
+        '-H',
+        'Content-Type: application/json',
+        '-H',
+        'Connection: close',
+        ...authArgs,
+        '--max-time',
+        String(Math.ceil(timeoutMs / 1000)),
+        '--data-binary',
+        '@-'
+      ],
       { input: body, encoding: 'utf8', timeout: timeoutMs + 5000 }
     )
     if (r.error) {

package/package.json

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

package/rules/abie/docs/fix.md

@@ -1,3 +1,9 @@
+---
+docgen:
+  source: npm/rules/abie/fix.mjs
+  crc: 12fc1644
+---
+
 # fix.mjs
 
 ## Огляд