@nitra/cursor 5.2.0 → 5.3.0

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## [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
+
+- adr
+
 ## [5.2.0] - 2026-06-11
 
 ### Changed

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/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/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.0",
+  "version": "5.3.0",
   "description": "CLI для завантаження cursor-правил (префікс n-) у локальний репозиторій",
   "keywords": [
     "cli",