@nitra/cursor 5.2.1 → 5.3.1

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## [5.3.1] - 2026-06-11
+
+### Fixed
+
+- lint: усунено eslint/oxlint-помилки (24) — ігнор кореневого `.worktrees/` в eslint.config, GENERIC_RE→масив дрібних patternів (sonarjs/regex-complexity), Array#sort→toSorted; cspell: додано `ollama` у словник
+
+## [5.3.0] - 2026-06-11
+
+### Added
+
+- js-lint: нові JS-файли створюються з явним розширенням .mjs/.cjs (не .js); приклади нового вихідного коду в js-run/js-bun-db/vue переведено на .mjs. test: підтримка vitest.config.mjs — pool-forks і stryker_config приймають .mjs/.js (новий канон .mjs, legacy .js не дублюється), stryker.configFile приводиться до фактичного імені. style-lint: чекер розпізнає stylelint.config.mjs/.cjs та .stylelintrc.mjs/.cjs.
+- llm wire-trace: always-on багатий JSONL-запис на кожен `callLlm` (обидва канали — reasoning + слід) у `<cwd>/.n-cursor/llm-trace.jsonl` (gitignored, недеструктивна ротація 50 MB, kill-switch `N_CURSOR_LLM_TRACE=0`); `callOmlxRaw` дістає reasoning_content/usage/finish_reason/attempts (`callOmlx` лишається `string`-обгорткою); `fix`+`coverage-classify` мігровано з прямого `callOmlx`/`pi`-spawn на спільний `callLlm` (caller-мітка). Спека: docs/specs/2026-06-10-omlx-wire-trace-capture-design.md
+
 ## [5.2.1] - 2026-06-11
 
 ### Changed

package/bin/n-cursor.js

@@ -1243,7 +1243,73 @@ function logRemovedManagedItems(title, basePath, names) {
 }
 
 /**
- * Spawn-wrapper для `npx @nitra/cursor fix [<rule>...]`. Один шлях у коді: для кожного правила
+ * Визначає список правил для fix: явно задані (з валідацією проти available) або
+ * discovery з `.cursor/rules/*.mdc`. Друкує діагностику й кидає на невідомих правилах.
+ * @param {string[]} requestedRules запитані правила (порожній → discovery)
+ * @param {string[]} available доступні в пакеті rule-id
+ * @param {boolean} json json-режим (впливає на early-return вивід при порожньому discovery)
+ * @returns {Promise<string[]|null>} список id або null — нічого запускати (вивід уже зроблено)
+ */
+async function resolveFixRuleIds(requestedRules, available, json) {
+  if (requestedRules.length > 0) {
+    const unknown = requestedRules.filter(id => !available.includes(id))
+    if (unknown.length > 0) {
+      console.error(`❌ Невідомі правила: ${unknown.join(', ')}`)
+      console.log(`   Доступні: ${available.join(', ')}`)
+      throw new Error(`Unknown rules: ${unknown.join(', ')}`)
+    }
+    return requestedRules
+  }
+
+  const mdcFiles = await listProjectRulesMdcFiles()
+  if (mdcFiles.length === 0) {
+    throw new Error(
+      `Немає файлів *.mdc у ${RULES_DIR}/. Запустіть \`npx ${PACKAGE_NAME}\` або вкажіть правила: \`npx ${PACKAGE_NAME} fix bun ga\``
+    )
+  }
+  const idsToRun = discoverCheckRulesFromCursorRules(available, mdcFiles)
+  if (idsToRun.length === 0) {
+    if (json) {
+      process.stdout.write(`${JSON.stringify({ total: 0, failed: 0, rules: [] })}\n`)
+      return null
+    }
+    console.log(
+      `\n🔍 ${PACKAGE_NAME} fix — у ${RULES_DIR}/ немає правил з programmatic перевіркою ` +
+        `(відповідного fix.mjs у пакеті). Нічого не запущено.\n`
+    )
+    return null
+  }
+  return idsToRun
+}
+
+/**
+ * Прогоняє `fix.mjs` кожного правила окремим процесом; збирає timings і (для json) per-rule output.
+ * @param {string[]} idsToRun правила до запуску
+ * @param {boolean} json json-режим — захоплює stdout/stderr у структуру замість inherit у термінал
+ * @returns {{ totalFailed: number, timings: {id:string, ms:number, ok:boolean}[], ruleResults: {ruleId:string, ok:boolean, output:string}[] }} підсумок прогону
+ */
+function runRuleFixProcesses(idsToRun, json) {
+  let totalFailed = 0
+  const timings = []
+  const ruleResults = []
+  for (const id of idsToRun) {
+    const fixPath = join(BUNDLED_RULES_DIR, id, 'fix.mjs')
+    const startedAt = Date.now()
+    const result = json
+      ? spawnSync('bun', [fixPath], { encoding: 'utf8' })
+      : spawnSync('bun', [fixPath], { stdio: 'inherit' })
+    const ok = result.status === 0
+    timings.push({ id: `fix-${id}`, ms: Date.now() - startedAt, ok })
+    if (json) {
+      ruleResults.push({ ruleId: id, ok, output: `${result.stdout ?? ''}${result.stderr ?? ''}`.trim() })
+    }
+    if (!ok) totalFailed++
+  }
+  return { totalFailed, timings, ruleResults }
+}
+
+/**
+ * Spawn-wrapper для `npx \@nitra/cursor fix [<rule>...]`. Один шлях у коді: для кожного правила
  * робить `bun rules/<id>/fix.mjs` як окремий процес. Сам `fix.mjs` читає `.n-cursor.json`,
  * перевіряє whitelist (`runRuleCli`) і друкує per-rule summary.
  *
@@ -1272,56 +1338,12 @@ async function runFixCommand(requestedRules, opts = {}) {
     throw new Error('No rules found')
   }
 
-  let idsToRun
-  if (requestedRules.length > 0) {
-    const unknown = requestedRules.filter(id => !available.includes(id))
-    if (unknown.length > 0) {
-      console.error(`❌ Невідомі правила: ${unknown.join(', ')}`)
-      console.log(`   Доступні: ${available.join(', ')}`)
-      throw new Error(`Unknown rules: ${unknown.join(', ')}`)
-    }
-    idsToRun = requestedRules
-  } else {
-    const mdcFiles = await listProjectRulesMdcFiles()
-    if (mdcFiles.length === 0) {
-      throw new Error(
-        `Немає файлів *.mdc у ${RULES_DIR}/. Запустіть \`npx ${PACKAGE_NAME}\` або вкажіть правила: \`npx ${PACKAGE_NAME} fix bun ga\``
-      )
-    }
-    idsToRun = discoverCheckRulesFromCursorRules(available, mdcFiles)
-    if (idsToRun.length === 0) {
-      if (json) {
-        process.stdout.write(`${JSON.stringify({ total: 0, failed: 0, rules: [] })}\n`)
-        return
-      }
-      console.log(
-        `\n🔍 ${PACKAGE_NAME} fix — у ${RULES_DIR}/ немає правил з programmatic перевіркою ` +
-          `(відповідного fix.mjs у пакеті). Нічого не запущено.\n`
-      )
-      return
-    }
-  }
+  // json-режим: захоплюємо stdout/stderr правила у структуру (а не inherit у термінал),
+  // щоб віддати агенту згруповано {ruleId, ok, output} і він читав лише впалі.
+  const idsToRun = await resolveFixRuleIds(requestedRules, available, json)
+  if (idsToRun === null) return
 
-  let totalFailed = 0
-  /** @type {{ id: string, ms: number, ok: boolean }[]} */
-  const timings = []
-  /** @type {{ ruleId: string, ok: boolean, output: string }[]} */
-  const ruleResults = []
-  for (const id of idsToRun) {
-    const fixPath = join(BUNDLED_RULES_DIR, id, 'fix.mjs')
-    const startedAt = Date.now()
-    // json-режим: захоплюємо stdout/stderr правила у структуру (а не inherit у термінал),
-    // щоб віддати агенту згруповано {ruleId, ok, output} і він читав лише впалі.
-    const result = json
-      ? spawnSync('bun', [fixPath], { encoding: 'utf8' })
-      : spawnSync('bun', [fixPath], { stdio: 'inherit' })
-    const ok = result.status === 0
-    timings.push({ id: `fix-${id}`, ms: Date.now() - startedAt, ok })
-    if (json) {
-      ruleResults.push({ ruleId: id, ok, output: `${result.stdout ?? ''}${result.stderr ?? ''}`.trim() })
-    }
-    if (!ok) totalFailed++
-  }
+  const { totalFailed, timings, ruleResults } = runRuleFixProcesses(idsToRun, json)
 
   if (json) {
     process.stdout.write(`${JSON.stringify({ total: idsToRun.length, failed: totalFailed, rules: ruleResults })}\n`)

package/lib/llm.mjs

@@ -7,15 +7,16 @@
  *
  * Жодних env-перемикачів бекенда: рядок моделі сам визначає транспорт.
  *
- * Wire-trace (ADR 260610-1516/1524): якщо виставлено `N_CURSOR_LLM_TRACE=<file>`,
- * кожен виклик append-ить один JSONL-рядок з бекендом, моделлю, тривалістю і
- * розмірами prompt/output. Трейс fail-safe: помилка запису не ламає виклик.
+ * Wire-trace (спека 2026-06-10-omlx-wire-trace-capture-design): **always-on**
+ * багатий JSONL-запис на кожен виклик — обидва канали (reasoning + слід). Для
+ * omlx захоплює content/reasoning/usage/finish_reason/attempts; для pi — лише
+ * те, що CLI дає (rich-поля null). Деталі запису/шляху/ротації — `omlx-trace.mjs`.
  */
 import { spawnSync } from 'node:child_process'
-import { appendFileSync } from 'node:fs'
 import { env } from 'node:process'
 
-import { callOmlx, isOmlxModel } from './omlx.mjs'
+import { callOmlxRaw, isOmlxModel } from './omlx.mjs'
+import { buildTraceRecord, writeTrace } from './omlx-trace.mjs'
 
 /** Дефолтний timeout одного виклику (узгоджено з LOCAL_TIMEOUT доки-конвеєра). */
 const DEFAULT_TIMEOUT_MS = 120_000
@@ -29,20 +30,6 @@ 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 вимкнено.
@@ -64,42 +51,68 @@ function callPi(messages, model, timeoutMs) {
 }
 
 /**
- * Універсальний LLM-виклик з маршрутизацією за префіксом model-id.
+ * Універсальний LLM-виклик з маршрутизацією за префіксом model-id і always-on
+ * wire-trace (обидва канали).
  * @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
+ * @param {{ timeoutMs?: number, temperature?: number, maxTokens?: number, url?: string, caller?: string }} [opts] timeout, температура, ліміт виходу, override URL, мітка викликача для trace
  * @returns {string} текст відповіді (непорожній на omlx; pi може повернути '')
  */
 export function callLlm(messages, model, opts = {}) {
-  const { timeoutMs = DEFAULT_TIMEOUT_MS, temperature = 0.2, maxTokens, url } = opts
+  const { timeoutMs = DEFAULT_TIMEOUT_MS, temperature = 0.2, maxTokens, url, caller } = opts
   const backend = pickBackend(model)
+  const resolvedCaller = caller ?? env.N_CURSOR_TRACE_CALLER ?? 'unknown'
   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
+    let content
+    let reasoning = null
+    let reasoningSource = null
+    let finishReason = null
+    let usage = null
+    let attempts = 1
+    if (backend === 'omlx') {
+      const raw = callOmlxRaw(messages, model, { url, timeoutMs, temperature, ...(maxTokens ? { maxTokens } : {}) })
+      ;({ content, reasoning, reasoningSource, finishReason, usage, attempts } = raw)
+    } else {
+      content = callPi(messages, model, timeoutMs)
+    }
+    writeTrace(
+      buildTraceRecord({
+        ts: new Date().toISOString(),
+        caller: resolvedCaller,
+        backend,
+        model,
+        temperature,
+        maxTokens,
+        messages,
+        content,
+        reasoning,
+        reasoningSource,
+        finishReason,
+        usage,
+        ms: Date.now() - t0,
+        attempts,
+        ok: true,
+        error: null
+      })
+    )
+    return content
   } catch (error) {
-    trace({
-      ts: new Date().toISOString(),
-      backend,
-      model,
-      ms: Date.now() - t0,
-      promptChars,
-      ok: false,
-      error: String(error.message).slice(0, 200)
-    })
+    writeTrace(
+      buildTraceRecord({
+        ts: new Date().toISOString(),
+        caller: resolvedCaller,
+        backend,
+        model,
+        temperature,
+        maxTokens,
+        messages,
+        ms: Date.now() - t0,
+        attempts: null,
+        ok: false,
+        error: String(error.message).slice(0, 200)
+      })
+    )
     throw error
   }
 }
@@ -124,7 +137,7 @@ const AUTH_ERROR_MARKER = 'authentication_error'
 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 })
+    callOmlxRaw([{ role: 'user', content: 'ok' }], model, { url, timeoutMs, maxTokens: 1, temperature: 0 })
     return { ok: true, reason: null, detail: '' }
   } catch (error) {
     const detail = String(error.message)

package/lib/models.mjs

@@ -14,7 +14,7 @@
  *
  * ## Бекенд за префіксом model-id
  *
- * model-id з префіксом `omlx/...` маршрутизується прямим HTTP до локального
+ * model-id з префіксом `omlx/...` іде прямим HTTP до локального
  * omlx-сервера (`npm/lib/omlx.mjs`), минаючи pi; решта (`openai/...`,
  * `ollama/...`, '') — через pi CLI. Тому локальні тири варто задавати у форматі
  * `omlx/<model>`, аби local-inference йшов напряму, а pi лишався шаром для хмари

package/lib/omlx-trace.mjs

@@ -0,0 +1,158 @@
+/**
+ * Wire-trace LLM-викликів: будує й пише багатий JSONL-запис на кожен виклик
+ * `callLlm` (див. `npm/lib/llm.mjs`). Захоплює **обидва канали** — reasoning
+ * (думки моделі) і спостережуваний слід (request/response/usage/latency/retry).
+ *
+ * Дизайн-спека: `docs/specs/2026-06-10-omlx-wire-trace-capture-design.md`.
+ *
+ * Двошарова модель:
+ *   - RAW (цей модуль) → `<cwd>/.n-cursor/llm-trace.jsonl` (gitignored, локальний,
+ *     недеструктивна ротація) — сирий потік, доживає до батч-агрегації.
+ *   - AGGREGATE (друга спека) → `docs/omlx-insights/` (коммітиться в git, назавжди).
+ *
+ * Always-on: пишеться завжди. `N_CURSOR_LLM_TRACE=0|false|off|no` — kill-switch;
+ * будь-яке інше значення — override-шлях замість дефолтного.
+ */
+import { appendFileSync, existsSync, mkdirSync, renameSync, statSync } from 'node:fs'
+import { createHash } from 'node:crypto'
+import { dirname, join } from 'node:path'
+import { cwd, env } from 'node:process'
+
+/** Ліміт символів на одне `message.content` у записі (захист обсягу/чутливості). */
+export const MAX_MSG_CHARS = 8000
+
+/** Поріг недеструктивної ротації активного файлу (байти). */
+export const ROTATE_BYTES = 50 * 1024 * 1024
+
+/** Значення `N_CURSOR_LLM_TRACE`, що вимикають трасування повністю. */
+const KILL_VALUES = new Set(['0', 'false', 'off', 'no'])
+
+/**
+ * Шлях активного trace-файлу або `null`, якщо трасування вимкнено kill-switch-ем.
+ * Пріоритет: `N_CURSOR_LLM_TRACE` (kill-switch → null; інакше явний шлях) →
+ * дефолт `<cwd>/.n-cursor/llm-trace.jsonl` (корінь споживацького проєкту).
+ * @returns {string|null} абсолютний/відносний шлях до .jsonl або null
+ */
+export function tracePath() {
+  const override = env.N_CURSOR_LLM_TRACE
+  if (override !== undefined) {
+    if (KILL_VALUES.has(override.toLowerCase())) return null
+    if (override) return override
+  }
+  return join(cwd(), '.n-cursor', 'llm-trace.jsonl')
+}
+
+/**
+ * Обрізає кожне `message.content` до `MAX_MSG_CHARS` і рахує sha256 повного
+ * (необрізаного) масиву для дедуплікації.
+ * @param {Array<{role:string, content:string}>} messages вихідні messages
+ * @returns {{ messages: Array<{role:string, content:string}>, messages_sha256: string, messages_truncated: boolean }} обрізані messages, hash і прапор обрізки
+ */
+export function capMessages(messages) {
+  const src = messages ?? []
+  let truncated = false
+  const capped = src.map(m => {
+    const content = m?.content ?? ''
+    if (content.length > MAX_MSG_CHARS) {
+      truncated = true
+      return { role: m.role, content: content.slice(0, MAX_MSG_CHARS) }
+    }
+    return { role: m?.role, content }
+  })
+  const messages_sha256 = createHash('sha256').update(JSON.stringify(src)).digest('hex')
+  return { messages: capped, messages_sha256, messages_truncated: truncated }
+}
+
+/**
+ * Будує нормалізований trace-запис. Поля, яких backend не дає (pi: reasoning/
+ * usage/finish_reason), лишаються `null` за побудовою.
+ * @param {object} i вхід
+ * @param {string} i.ts ISO-час завершення виклику
+ * @param {string} i.caller хто викликав (doc-files|fix|coverage|unknown)
+ * @param {'omlx'|'pi'} i.backend бекенд
+ * @param {string} i.model model-id
+ * @param {number} [i.temperature] температура
+ * @param {number} [i.maxTokens] ліміт виходу
+ * @param {Array<{role:string, content:string}>} i.messages messages запиту
+ * @param {string|null} [i.content] відповідь
+ * @param {string|null} [i.reasoning] думки моделі
+ * @param {string|null} [i.reasoningSource] джерело reasoning
+ * @param {string|null} [i.finishReason] finish_reason
+ * @param {object|null} [i.usage] usage verbatim
+ * @param {number} i.ms latency
+ * @param {number|null} [i.attempts] кількість спроб
+ * @param {boolean} i.ok успіх
+ * @param {string|null} [i.error] текст помилки
+ * @returns {object} JSONL-готовий запис
+ */
+export function buildTraceRecord(i) {
+  const capped = capMessages(i.messages)
+  return {
+    ts: i.ts,
+    caller: i.caller,
+    backend: i.backend,
+    model: i.model,
+    temperature: i.temperature ?? null,
+    max_tokens: i.maxTokens ?? null,
+    messages: capped.messages,
+    messages_sha256: capped.messages_sha256,
+    messages_truncated: capped.messages_truncated,
+    content: i.content ?? null,
+    reasoning: i.reasoning ?? null,
+    reasoning_source: i.reasoningSource ?? null,
+    finish_reason: i.finishReason ?? null,
+    usage: i.usage ?? null,
+    ms: i.ms,
+    attempts: i.attempts ?? null,
+    ok: i.ok,
+    error: i.error ?? null
+  }
+}
+
+/**
+ * Імʼя архіву для ротації: `llm-trace.jsonl` → `llm-trace.<seq>.jsonl`
+ * (нестандартні імена без `.jsonl` → `<file>.<seq>`).
+ * @param {string} file активний trace-файл
+ * @param {number} seq порядковий номер архіву
+ * @returns {string} шлях архіву
+ */
+function archiveName(file, seq) {
+  return file.endsWith('.jsonl') ? `${file.slice(0, -'.jsonl'.length)}.${seq}.jsonl` : `${file}.${seq}`
+}
+
+/**
+ * Недеструктивна ротація: якщо активний файл перевищує `ROTATE_BYTES`,
+ * перейменовує його в перший вільний `llm-trace.<seq>.jsonl` (без перезапису
+ * наявних архівів). Відсутній файл / помилка stat — no-op.
+ * @param {string} file активний trace-файл
+ */
+export function rotateIfNeeded(file) {
+  let size
+  try {
+    size = statSync(file).size
+  } catch {
+    return // файлу ще нема — нічого ротувати
+  }
+  if (size <= ROTATE_BYTES) return
+  let seq = 1
+  while (existsSync(archiveName(file, seq))) seq++
+  renameSync(file, archiveName(file, seq))
+}
+
+/**
+ * Fail-safe запис одного trace-рядка. Резолвить шлях (kill-switch → no-op),
+ * ротує за потреби, створює теку, append-ить JSONL. Будь-яка помилка IO
+ * ковтається — трасування **ніколи** не ламає основний виклик.
+ * @param {object} record запис від `buildTraceRecord`
+ */
+export function writeTrace(record) {
+  const file = tracePath()
+  if (!file) return
+  try {
+    rotateIfNeeded(file)
+    mkdirSync(dirname(file), { recursive: true })
+    appendFileSync(file, JSON.stringify(record) + '\n')
+  } catch {
+    // трейс не має ламати основний виклик
+  }
+}

package/lib/omlx.mjs

@@ -70,16 +70,42 @@ export function omlxModelId(model) {
 }
 
 /**
- * Прямий HTTP-виклик до omlx через `curl` (spawnSync). Повертає текст
- * `choices[0].message.content`. Ретраїть лише transient curl-помилки
- * (18 = transfer closed, 52 = empty reply, 56 = recv failure).
+ * Витягує reasoning (думки моделі) з omlx-`message`. Джерела за пріоритетом:
+ *   - `field`     — окреме поле `message.reasoning_content` (Qwen3-Thinking тощо);
+ *   - `think_tag` — `<think>…</think>` усередині `content` (інші thinking-моделі);
+ *   - `truncated` — `finish_reason: "length"` зрізав думку в `content` до закриття
+ *                   тега → сирий reasoning лишився в `content` без `</think>`;
+ *   - `null`      — reasoning немає (не-thinking модель).
+ * @param {{content?:string, reasoning_content?:string}} message обʼєкт `choices[0].message`
+ * @param {string|null} finishReason `choices[0].finish_reason`
+ * @returns {{ reasoning: string|null, reasoningSource: 'field'|'think_tag'|'truncated'|null }} текст думок і його джерело
+ */
+const THINK_TAG_RE = /<think>([\s\S]*?)<\/think>/
+
+/**
+ *
+ */
+export function extractReasoning(message, finishReason) {
+  const field = message?.reasoning_content
+  if (field && field.trim()) return { reasoning: field, reasoningSource: 'field' }
+  const content = message?.content ?? ''
+  const m = content.match(THINK_TAG_RE)
+  if (m) return { reasoning: m[1].trim(), reasoningSource: 'think_tag' }
+  if (finishReason === 'length' && content.trim()) return { reasoning: content, reasoningSource: 'truncated' }
+  return { reasoning: null, reasoningSource: null }
+}
+
+/**
+ * Ядро прямого HTTP-виклику до omlx через `curl` (spawnSync). Повертає **багатий**
+ * обʼєкт: контент + reasoning + usage + finish_reason + кількість спроб. Ретраїть
+ * лише 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} непорожній контент відповіді
+ * @returns {{ content:string, reasoning:string|null, reasoningSource:string|null, finishReason:string|null, usage:object|null, attempts:number }} багатий результат виклику
  * @throws на curl-помилці, не-200 exit, поганому JSON чи порожньому контенті
  */
-export function callOmlx(messages, model, opts = {}) {
+export function callOmlxRaw(messages, model, opts = {}) {
   const {
     url = env.N_CURSOR_OMLX_URL ?? DEFAULT_OMLX_URL,
     timeoutMs = 60_000,
@@ -136,12 +162,24 @@ export function callOmlx(messages, model, opts = {}) {
       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
+    const message = j.choices?.[0]?.message ?? {}
+    const finishReason = j.choices?.[0]?.finish_reason ?? null
+    const content = message.content?.trim() ?? ''
+    if (!content) throw new Error(`omlx empty content (finish=${finishReason})`)
+    const { reasoning, reasoningSource } = extractReasoning(message, finishReason)
+    return { content, reasoning, reasoningSource, finishReason, usage: j.usage ?? null, attempts: attempt }
   }
   throw lastErr ?? new Error('omlx unknown failure')
 }
+
+/**
+ * Тонка обгортка над `callOmlxRaw` для споживачів, яким потрібен лише текст.
+ * Контракт незмінний: повертає непорожній `choices[0].message.content`.
+ * @param {Array<{role:string, content:string}>} messages OpenAI-messages
+ * @param {string} model model-id (з/без `omlx/`-префікса)
+ * @param {object} [opts] ті самі опції, що й у `callOmlxRaw`
+ * @returns {string} непорожній контент відповіді
+ */
+export function callOmlx(messages, model, opts = {}) {
+  return callOmlxRaw(messages, model, opts).content
+}

package/package.json

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

package/rules/js-bun-db/js-bun-db.mdc

@@ -2,7 +2,7 @@
 description: Використання pg / mysql2 / Bun SQL у Node.js та Bun
 globs: "**/package.json,**/src/conn/**"
 alwaysApply: false
-version: '1.14'
+version: '1.15'
 ---
 
 ## Підтримувані версії баз даних
@@ -300,10 +300,10 @@ const rows = await sql.unsafe(query, values)
 
 Дефолтний експорт `sql` з `'bun'` сам читає змінні середовища (`DATABASE_URL`, `POSTGRES_URL`, `MYSQL_URL`, `PGHOST`/`PGUSER`/... та `MYSQL_HOST`/`MYSQL_USER`/...) і керує пулом — окремий `Pool` як у `pg` створювати не треба.
 
-Для явного конфігу — `new SQL(...)` як **singleton** на рівні модуля, а не на кожен запит. Файл кладеться у `src/conn/db.js` і експортує іменовані константи `pgWrite` (основний запис) та `pgRead` (read-only replica), щоб glob `**/src/conn/**` у правилах покривав ці файли:
+Для явного конфігу — `new SQL(...)` як **singleton** на рівні модуля, а не на кожен запит. Файл кладеться у `src/conn/db.mjs` і експортує іменовані константи `pgWrite` (основний запис) та `pgRead` (read-only replica), щоб glob `**/src/conn/**` у правилах покривав ці файли:
 
 ```javascript
-// src/conn/db.js
+// src/conn/db.mjs
 import { SQL } from 'bun'
 
 export const pgWrite = new SQL({
@@ -454,16 +454,16 @@ ${pgRead.array(ids, 'int4')}
 
 OXC formatter (oxfmt ≥ 0.49) примусово розгортає будь-який `CallExpression`, де перший аргумент є `CallExpression` з callback, у багаторядковий блок — незалежно від `printWidth`. Тому `pgWrite.array(arr.map(r => r.field), 'type')` всередині tagged template literal завжди стає 4-рядковим блоком. `col(arr, 'field')` (перший аргумент — identifier, другий — string literal) цей тригер не зачіпає і лишається однорядковим.
 
-Канонічне місце хелпера — `src/utils/col.js` (або `src/conn/col.js` залежно від структури проєкту):
+Канонічне місце хелпера — `src/utils/col.mjs` (або `src/conn/col.mjs` залежно від структури проєкту):
 
 ```javascript
-// src/utils/col.js
+// src/utils/col.mjs
 export const col = (arr, key) => arr.map(r => r[key])
 ```
 
 ```javascript
-import { pgWrite } from '#src/conn/db.js'
-import { col } from '#src/utils/col.js'
+import { pgWrite } from '#src/conn/db.mjs'
+import { col } from '#src/utils/col.mjs'
 
 // ❌ oxfmt розгортає на 4+ рядки незалежно від printWidth
 ${pgWrite.array(rows.map(r => r.id), 'int4')}

package/rules/js-lint/js-lint.mdc

@@ -2,7 +2,7 @@
 description: Перевірка JavaScript коду
 globs: "**/{.oxlintrc.json,eslint.config.js,.jscpd.json,knip.json,package.json},**/*.{js,mjs,cjs,jsx,ts,tsx}"
 alwaysApply: false
-version: '1.29'
+version: '1.30'
 ---
 
 **oxlint**, **ESLint**, **jscpd**, **knip**. У скрипті **`lint-js`** і в CI — **`bunx oxlint`**, **`bunx eslint`**, **`bunx jscpd`**, **`bunx knip`** (у CI без **`--fix`** для oxlint/eslint — див. приклад workflow нижче). Без **prettier** і **@nitra/prettier-config**. У **`devDependencies`** має бути **`@nitra/eslint-config`** — версія не нижче канонічного мінімуму зі snippet нижче (semver-поріг, єдине джерело істини) (з **3.8.0** правило `no-restricted-syntax` забороняє `for...in`; з **3.9.2** у `getConfig` вбудовано ignore для **`**/adr/**`** — ADR-документи не валідуються ESLint, локально цей glob додавати не потрібно; також транзитивно йде **`@e18e/eslint-plugin`** для oxlint). Dependency-політику CI-етапу (`@e18e/eslint-plugin` і oxlint/eslint/jscpd/knip окремо не додавати) винесено в `js-lint-ci`.
@@ -23,6 +23,19 @@ version: '1.29'
 
 Канон `type` + `scripts.lint-js` (substring requirement) і мінімальна `@nitra/eslint-config` (semver-поріг `devDependencies`): [package.json.snippet.json](./policy/package_json/template/package.json.snippet.json)
 
+## Розширення нових файлів — `.mjs` / `.cjs`, не `.js`
+
+**Нові** JS-файли створюй з явним розширенням модуля:
+
+- **`.mjs`** — для ESM (типовий випадок);
+- **`.cjs`** — для CommonJS, де він справді потрібен.
+
+Голий **`.js`** для нового файлу **заборонено**. Розширення `.js` інтерпретується як ESM чи CJS лише за полем `package.json#type`, тож той самий файл читається по-різному залежно від пакета. Явне `.mjs`/`.cjs` робить тип модуля однозначним **без читання `package.json`** — навіть якщо `type` зміниться або файл перемістять в інший пакет. Це доповнює вимогу `"type": "module"` вище: `type` лишається каноном для всього дерева, а розширення нового файлу прибирає залежність від нього.
+
+Стосується **backend і frontend** — будь-який новий вихідний файл: `src/`, тести `*.test.*`, `scripts/`, `src/conn/` тощо.
+
+**Існуючі `.js` лишаються як є** — масово перейменовувати не треба; це конвенція для нового коду. Автоматичної перевірки тут немає: stateless-скан не відрізнить новий файл від існуючого, тож `.js` нікого не фейлить.
+
 У `.vscode/extensions.json` `recommendations` мають містити `dbaeumer.vscode-eslint`, `github.vscode-github-actions`, `oxc.oxc-vscode`: [extensions.json.snippet.json](./policy/vscode_extensions/template/extensions.json.snippet.json)
 
 У корені має бути **`.oxlintrc.json`**, який **збігається з каноном** oxlint з пакета **`@nitra/cursor`**: файл **`npm/rules/js-lint/js/data/tooling/oxlint-canonical.json`** (plugins, jsPlugins з **`@e18e/eslint-plugin`**, categories, повний набір **rules** із канону — додаткові записи в **`rules`** дозволені; також **`settings`**, **`env`**, **`globals`**). Поле **`ignorePatterns`** працює як **`rules`**: канонічні патерни з **`oxlint-canonical.json`** (наразі **`**/schema.graphql`**, **`**/auto-imports.d.ts`**) мають бути присутні, додаткові локальні glob-и дозволені. Канон **`oxlint-canonical.json`** — source-of-truth, редагується напряму; у споживачі оновлюється копіюванням файлу з репозиторію пакета. Модуль **`@e18e/eslint-plugin`** не оголошуй окремо в **`package.json`** — він уже в залежностях **`@nitra/eslint-config`** (з **3.8.0**), oxlint підвантажує його з **`node_modules`**.