@nitra/cursor 5.0.3 → 5.2.0

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.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
+
+- local-inference: маршрут моделей за префіксом `omlx/` напряму в omlx HTTP (npm/lib/omlx.mjs) минаючи pi; coverage-classify і fix/llm-worker переведено на спільний callOmlx, docgen де-дубльовано; pi лишається шаром для хмари й агентних задач (ADR 260610-1349)
+
 ## [5.0.3] - 2026-06-10
 
 ### Changed
@@ -69,7 +86,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/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/models.mjs

@@ -5,13 +5,21 @@
  * Налаштовується один раз у середовищі; кожен скіл посилається на потрібний тир.
  *
  * Приклад ~/.bashrc або .env:
- *   N_LOCAL_MIN_MODEL=ollama/gemma3:4b
+ *   N_LOCAL_MIN_MODEL=omlx/mlx-community--gemma-4-e2b-it-4bit
  *   N_CLOUD_MIN_MODEL=openai/gpt-5.4-mini
  *   N_CLOUD_AVG_MODEL=openai/gpt-5.4
  *   N_CLOUD_MAX_MODEL=openai/gpt-5.5
  *
  * Значення '' означає "pi дефолтний провайдер" (залежить від ~/.pi конфігу).
  *
+ * ## Бекенд за префіксом model-id
+ *
+ * model-id з префіксом `omlx/...` маршрутизується прямим HTTP до локального
+ * omlx-сервера (`npm/lib/omlx.mjs`), минаючи pi; решта (`openai/...`,
+ * `ollama/...`, '') — через pi CLI. Тому локальні тири варто задавати у форматі
+ * `omlx/<model>`, аби local-inference йшов напряму, а pi лишався шаром для хмари
+ * (див. ADR 260610-1349).
+ *
  * ## Каскад local → cloud (контракт)
  *
  * Використовуйте resolveModel(tier) замість прямих констант — система прозоро

package/lib/omlx.mjs

@@ -0,0 +1,147 @@
+/**
+ * Спільний транспорт до локального omlx-сервера (OpenAI-сумісний MLX,
+ * `http://localhost:8000/v1/chat/completions`). Text-only: жодних `tools`/
+ * `tool_calls` — сервер їх не підтримує (див. ADR
+ * `260610-1349-агентна-пастка-js-owned-loop-через-omlx-замість-pi-tool-loop`).
+ *
+ * Маршрутизація між omlx і pi — за конвенцією префікса в model-id:
+ *   `omlx/<model>` → прямий HTTP до omlx (локальний inference, без pi)
+ *   будь-що інше    → pi CLI (хмарні провайдери або pi-дефолт)
+ *
+ * Так `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'
+
+const OMLX_PREFIX = 'omlx/'
+
+/**
+ * Чи цей model-id адресує локальний omlx-бекенд (префікс `omlx/`).
+ * @param {unknown} model перевірюваний model-id
+ * @returns {boolean} true, якщо рядок починається з `omlx/`
+ */
+export function isOmlxModel(model) {
+  return typeof model === 'string' && model.startsWith(OMLX_PREFIX)
+}
+
+/**
+ * Прибирає `omlx/`-префікс → чистий model-id для omlx API.
+ * Не-omlx-рядки повертає без змін.
+ * @param {string} model model-id (можливо з префіксом)
+ * @returns {string} model-id без `omlx/`
+ */
+export function omlxModelId(model) {
+  return isOmlxModel(model) ? model.slice(OMLX_PREFIX.length) : 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, apiKey?: string }} [opts] URL, timeout, температура, ліміт виходу, fallback-модель, API-ключ
+ * @returns {string} непорожній контент відповіді
+ * @throws на curl-помилці, не-200 exit, поганому JSON чи порожньому контенті
+ */
+export function callOmlx(messages, model, opts = {}) {
+  const {
+    url = env.N_CURSOR_OMLX_URL ?? DEFAULT_OMLX_URL,
+    timeoutMs = 60_000,
+    temperature = 0.2,
+    maxTokens = 4096,
+    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',
+        ...authArgs,
+        '--max-time',
+        String(Math.ceil(timeoutMs / 1000)),
+        '--data-binary',
+        '@-'
+      ],
+      { input: body, encoding: 'utf8', timeout: timeoutMs + 5000 }
+    )
+    if (r.error) {
+      lastErr = new Error(`omlx curl error: ${r.error.message}`)
+      break
+    }
+    if (r.status !== 0) {
+      if (TRANSIENT_CURL_CODES.has(r.status) && attempt < 3) {
+        lastErr = new Error(`omlx curl exit ${r.status} (transient, retry ${attempt})`)
+        continue
+      }
+      throw new Error(`omlx curl exit ${r.status}: ${r.stderr?.slice(0, 300) ?? ''}`)
+    }
+    let j
+    try {
+      j = JSON.parse(r.stdout)
+    } catch {
+      throw new Error(`omlx bad json: ${r.stdout?.slice(0, 200) ?? ''}`)
+    }
+    if (j.error) throw new Error(`omlx api: ${JSON.stringify(j.error).slice(0, 300)}`)
+    const content = j.choices?.[0]?.message?.content?.trim() ?? ''
+    if (!content) {
+      const finish = j.choices?.[0]?.finish_reason
+      throw new Error(`omlx empty content (finish=${finish})`)
+    }
+    return content
+  }
+  throw lastErr ?? new Error('omlx unknown failure')
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nitra/cursor",
-  "version": "5.0.3",
+  "version": "5.2.0",
   "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
 
 ## Огляд