@nitra/cursor 3.25.1 → 3.26.0

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## [3.26.0] - 2026-06-06
+
+### Added
+
+- Root-guard для всіх деструктивних точок: CLI-команди fix/lint/coverage/change/release + дефолтний sync хардом перевіряють cwd===git-toplevel (assertCwdIsProjectRoot); worktree-preflight підсилено root-assert (pwd vs toplevel); новий meta.json-флаг requireRoot + injectRootNotice для in-place root-only скілів (n-start-check); skillRequiresRoot як явна похідна ознака захисту; валідація requireRoot у npm-module
+
+### Fixed
+
+- n-changelog: directional version-drift — лише version ВПЕРЕД (> опублікованої/git-бази) валить як ручний bump; version ПОЗАДУ (локаль відстала від CI-релізу, ще не git pull) більше не блокує коміт (compareSemverCore/versionIsAhead)
+
 ## [3.25.1] - 2026-06-06
 
 ### Fixed

package/package.json

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

package/skills/docgen/js/docgen-extract.mjs

@@ -0,0 +1,158 @@
+/**
+ * Stage 0 docgen-конвеєра: детермінована екстракція «факт-листа» з коду (0 токенів LLM).
+ *
+ * Ідея: винести з-під локальної моделі все, що вона псує (імена експортів, stdlib-vs-internal,
+ * крайові деталі поведінки), і віддати їй лише перефразування вже відомих фактів. Тут — суто
+ * парсинг JS/MJS регулярками: жодних мереж, LLM чи запису.
+ *
+ * Повертає об'єкт-факт-лист, який Stage 1 (docgen-prompts) перетворює на точкові промпти.
+ */
+
+const BUILTIN_MODULES = new Set([
+  'fs', 'path', 'crypto', 'os', 'util', 'stream', 'events', 'http', 'https',
+  'url', 'child_process', 'process', 'assert', 'buffer', 'zlib', 'readline'
+])
+
+/** Прибирає `/** *​/`-обрамлення й `*`-префікси, повертає чистий текст рядками. */
+function cleanJsDoc(raw) {
+  return raw
+    .replace(/^\s*\/\*\*?/, '')
+    .replace(/\*\/\s*$/, '')
+    .split('\n')
+    .map(l => l.replace(/^\s*\*?\s?/, '').trimEnd())
+    .join('\n')
+    .trim()
+}
+
+/** Опис (без @-тегів) + параметри з @param як «name — опис». */
+function parseJsDoc(raw) {
+  const text = cleanJsDoc(raw)
+  const lines = text.split('\n')
+  const descLines = []
+  const params = []
+  let ret = ''
+  for (const l of lines) {
+    const pm = l.match(/^@param\s+(?:\{[^}]*\}\s+)?\[?([A-Za-z0-9_.]+)\]?\s*(.*)$/)
+    const rm = l.match(/^@returns?\s+(?:\{[^}]*\}\s+)?(.*)$/)
+    if (pm) {
+      const desc = pm[2].trim()
+      // «опис.» — JSDoc-заглушка без сенсу; не тягнемо її як факт
+      params.push({ name: pm[1], desc: desc === 'опис.' ? '' : desc })
+      continue
+    }
+    if (rm) { ret = rm[1].trim(); continue }
+    if (l.startsWith('@')) continue
+    descLines.push(l)
+  }
+  return { desc: descLines.join('\n').trim(), params, ret }
+}
+
+/** Провідний блок-коментар файлу (намір), якщо він перед першим import/кодом. */
+function extractFileHeader(src) {
+  const m = src.match(/^\s*\/\*\*([\s\S]*?)\*\//)
+  if (!m) return ''
+  // має бути на самому початку (до import/код)
+  if (src.slice(0, m.index).trim() !== '') return ''
+  return parseJsDoc(m[0]).desc
+}
+
+/**
+ * Блок-коментар, що стоїть ВПРИТУЛ перед позицією (лише пробіли між ними).
+ * `(?:(?!\*​/)[\s\S])*` гарантує, що тіло не містить `*​/`, тож захоплюється рівно один
+ * найближчий блок — без жадібного «перестрибування» через імпорти/код.
+ */
+function precedingJsDoc(prefix) {
+  const m = prefix.match(/\/\*\*(?:(?!\*\/)[\s\S])*\*\/\s*$/)
+  return m ? m[0] : null
+}
+
+/** Експорти + JSDoc, що безпосередньо передує кожному. */
+function extractExports(src) {
+  const out = []
+  const re = /export\s+(?:async\s+)?(function|const|class)\s+([A-Za-z0-9_]+)/g
+  let m
+  while ((m = re.exec(src))) {
+    const [, kind, name] = m
+    const jsdocRaw = precedingJsDoc(src.slice(0, m.index))
+    out.push({ name, kind, ...(jsdocRaw ? parseJsDoc(jsdocRaw) : { desc: '', params: [], ret: '' }) })
+  }
+  return out
+}
+
+/** Імпорти, класифіковані на stdlib / npm / internal. */
+function extractImports(src) {
+  const stdlib = new Set(), npm = new Set(), internal = new Set()
+  const re = /^import\s+[\s\S]*?from\s+['"]([^'"]+)['"]/gm
+  let m
+  while ((m = re.exec(src))) {
+    const s = m[1]
+    if (s.startsWith('node:') || BUILTIN_MODULES.has(s.split('/')[0])) stdlib.add(s.replace(/^node:/, ''))
+    else if (s.startsWith('.') || s.startsWith('/')) internal.add(s)
+    else npm.add(s)
+  }
+  return { stdlib: [...stdlib], npm: [...npm], internal: [...internal] }
+}
+
+/** Імена символів, імпортованих із внутрішніх модулів — їх модель не має згадувати. */
+function extractInternalSymbols(src) {
+  const out = new Set()
+  const re = /import\s+(?:([A-Za-z0-9_$]+)\s*,?\s*)?(?:\{([^}]+)\})?\s+from\s+['"](\.[^'"]+)['"]/g
+  let m
+  while ((m = re.exec(src))) {
+    if (m[1]) out.add(m[1].trim())
+    if (m[2]) for (const n of m[2].split(',')) {
+      const name = n.replace(/\s+as\s+.*/, '').trim()
+      if (name) out.add(name)
+    }
+  }
+  return [...out]
+}
+
+/** Поведінкові маркери — евристики регулярками. */
+function extractMarkers(src) {
+  // помітні «пропуски»: dir/segment-літерали у фільтрах
+  const skips = new Set()
+  for (const lit of ['.github', '.git', 'node_modules', 'base/', 'ua/', '.firebase']) {
+    if (src.includes(`'${lit}`) || src.includes(`"${lit}`) || src.includes(`/${lit}`)) skips.add(lit)
+  }
+  return {
+    readOnly: !/\b(writeFile|mkdir|rmdir|unlink|appendFile|createWriteStream|rm\()/.test(src),
+    catchesErrors: /catch\s*\(/.test(src) || /\btry\s*\{/.test(src),
+    returnsFalsyOnFail: /return\s+(false|null|''|"")/.test(src),
+    network: /\bfetch\(|https?\.|axios|got\(/.test(src),
+    caches: /new Map\(\)|Cache|cache/.test(src),
+    skips: [...skips]
+  }
+}
+
+/**
+ * Головний екстрактор: код файлу → факт-лист.
+ * @param {string} src вміст файлу
+ * @param {string} relPath шлях (для контексту/мови екстрактора)
+ * @returns {{relPath:string, lang:string, header:string, exports:Array, imports:object, markers:object}}
+ */
+export function extractFacts(src, relPath) {
+  const lang = relPath.split('.').pop()
+  if (!['js', 'mjs', 'ts'].includes(lang)) {
+    return { relPath, lang, unsupported: true, header: '', exports: [], imports: {}, markers: {} }
+  }
+  return {
+    relPath,
+    lang,
+    header: extractFileHeader(src),
+    exports: extractExports(src),
+    imports: extractImports(src),
+    internalSymbols: extractInternalSymbols(src),
+    markers: extractMarkers(src)
+  }
+}
+
+// CLI для інспекції: node docgen-extract.mjs <file>
+import { isRunAsCli } from '../../../scripts/cli-entry.mjs'
+import { readFileSync } from 'node:fs'
+if (isRunAsCli(import.meta.url)) {
+  const file = process.argv[2]
+  if (!file) { console.error('Usage: node docgen-extract.mjs <file>'); process.exit(1) }
+  const facts = extractFacts(readFileSync(file, 'utf8'), file)
+  console.log(JSON.stringify(facts, null, 2))
+}

package/skills/docgen/js/docgen-gen.mjs

@@ -0,0 +1,133 @@
+/**
+ * docgen-конвеєр (входна точка): код файлу → .md-документація.
+ *
+ * Інверсія керування: веде цей JS, а локальна модель — лише сервіс перефразування.
+ *   Stage 0  extractFacts        — факти з коду (0 токенів)
+ *   Stage 1  sectionInstructions — точкові промпти на кожну секцію (спільний KV-cached префікс)
+ *   Stage 3  assemble            — фіксовані заголовки/порядок + зрізання fence
+ * Режим `--oneshot` — база для порівняння (один промпт на весь документ).
+ */
+import { readFileSync } from 'node:fs'
+import { basename } from 'node:path'
+import { request } from 'node:http'
+import { extractFacts } from './docgen-extract.mjs'
+import { sectionMessages, oneShotMessages } from './docgen-prompts.mjs'
+
+/** Один виклик чату до ollama зі streaming (токени стримуються → socket активний, жодного timeout). */
+async function ollamaChat(messages, { model, numPredict = 600 }) {
+  const body = JSON.stringify({
+    model, messages, stream: true, think: false,
+    options: { num_ctx: 8192, temperature: 0.2, num_predict: numPredict },
+    keep_alive: '15m'
+  })
+  return new Promise((resolve, reject) => {
+    const req = request(
+      { hostname: 'localhost', port: 11434, path: '/api/chat', method: 'POST',
+        headers: { 'Content-Type': 'application/json', 'Content-Length': Buffer.byteLength(body) } },
+      (res) => {
+        let text = '', genTok = 0, buf = ''
+        res.on('data', chunk => {
+          buf += chunk.toString()
+          const lines = buf.split('\n')
+          buf = lines.pop()
+          for (const line of lines) {
+            if (!line.trim()) continue
+            try {
+              const j = JSON.parse(line)
+              text += j.message?.content ?? ''
+              if (j.done) genTok = j.eval_count ?? 0
+            } catch { /* partial line */ }
+          }
+        })
+        res.on('end', () => resolve({ text, genTok }))
+        res.on('error', reject)
+      }
+    )
+    req.on('error', reject)
+    req.write(body)
+    req.end()
+  })
+}
+
+/** Прибирає ```-обгортку й випадковий провідний `##`-заголовок із секції. */
+function stripSection(text) {
+  let t = text.trim()
+  if (t.startsWith('```')) {
+    t = t.replace(/^```[a-z]*\n?/, '').replace(/\n?```\s*$/, '').trim()
+  }
+  t = t.replace(/^#{1,6}\s+.*\n+/, '') // зрізати випадковий заголовок
+  return t.trim()
+}
+
+/**
+ * Stage 2 (детермінований лінт, 0 токенів): зрізає сигнатури `name(args)` → `name`.
+ * Два проходи — щоб зняти вкладені виклики на кшталт `check(cwd = process.cwd())`.
+ * Не чіпає дужки без ідентифікатора перед ними (напр. `(abie.mdc)`, «(наприклад)»).
+ */
+function stripSignatures(text) {
+  let t = text
+  for (let i = 0; i < 2; i++) t = t.replace(/([`\w$.]+)\([^()]*\)/g, '$1')
+  return t
+}
+
+/** Stage 3: фіксовані заголовки у фіксованому порядку. */
+function assemble(stem, sections) {
+  const order = [
+    ['overview', '## Огляд'],
+    ['behavior', '## Поведінка'],
+    ['api', '## Публічний API'],
+    ['guarantees', '## Гарантії поведінки']
+  ]
+  const parts = [`# ${stem}`]
+  for (const [key, title] of order) {
+    const body = sections[key]
+    if (body && body.trim()) parts.push(`${title}\n\n${body.trim()}`)
+  }
+  return parts.join('\n\n') + '\n'
+}
+
+/** Оркестрований режим: секційно-мінімальний контекст — код інгестується лише в `behavior`. */
+async function generateOrchestrated(facts, src, model) {
+  const sections = {}
+  let genTok = 0
+  for (const s of sectionMessages(facts, src)) {
+    const { text, genTok: g } = await ollamaChat(s.messages, { model, numPredict: s.numPredict })
+    sections[s.key] = stripSignatures(stripSection(text))
+    genTok += g
+  }
+  return { md: assemble(basename(facts.relPath), sections), genTok }
+}
+
+/** One-shot режим: один промпт на весь документ. */
+async function generateOneShot(facts, src, model) {
+  const { text, genTok } = await ollamaChat(oneShotMessages(facts, src), { model, numPredict: 1500 })
+  let md = stripSignatures(stripSection(text)) // Stage-2 лінт і для one-shot
+  if (!md.startsWith('#')) md = `# ${basename(facts.relPath)}\n\n${md}`
+  return { md: md + '\n', genTok }
+}
+
+/** Головний API: файл → { md, genTok, ms }. */
+export async function generateDoc(file, { model = 'gemma3:4b', mode = 'orchestrated' } = {}) {
+  const src = readFileSync(file, 'utf8')
+  const facts = extractFacts(src, file)
+  const t0 = Date.now()
+  const r = facts.unsupported
+    ? await generateOneShot(facts, src, model) // fallback для не-JS
+    : mode === 'oneshot'
+      ? await generateOneShot(facts, src, model)
+      : await generateOrchestrated(facts, src, model)
+  return { ...r, ms: Date.now() - t0 }
+}
+
+// CLI: node docgen-gen.mjs <file> [--oneshot] [--model <m>]
+import { isRunAsCli } from '../../../scripts/cli-entry.mjs'
+if (isRunAsCli(import.meta.url)) {
+  const args = process.argv.slice(2)
+  const file = args.find(a => !a.startsWith('--'))
+  const mode = args.includes('--oneshot') ? 'oneshot' : 'orchestrated'
+  const mi = args.indexOf('--model'); const model = mi >= 0 ? args[mi + 1] : 'gemma3:4b'
+  if (!file) { console.error('Usage: node docgen-gen.mjs <file> [--oneshot] [--model <m>]'); process.exit(1) }
+  const r = await generateDoc(file, { model, mode })
+  process.stderr.write(`[${mode}] ${r.ms}ms / ${r.genTok} tok\n`)
+  process.stdout.write(r.md)
+}

package/skills/docgen/js/docgen-prompts.mjs

@@ -0,0 +1,82 @@
+/**
+ * Stage 1 docgen-конвеєра: факт-лист + код → точкові промпти на кожну секцію.
+ *
+ * v2 — СЕКЦІЙНО-МІНІМАЛЬНИЙ контекст: код іде ЛИШЕ у `Поведінку`. `Огляд` бере тільки
+ * header, `API` — лише список експортів, `Гарантії` — лише markers. Так інгест коду
+ * оплачується один раз (а не на кожну секцію), і оркестрація перестає програвати в часі.
+ */
+
+const STYLE = [
+  'Ти технічний письменник. Пишеш лаконічну ПОВЕДІНКОВУ документацію до коду українською, чистим Markdown.',
+  'Пиши ЩО і НАВІЩО, не ЯК. Без вступів і висновків. Не обгортай у ```-блок.',
+  'Заборонено: сигнатури, типи, параметри функцій; перелік stdlib-модулів; опис regex чи внутрішніх приватних імен.'
+].join(' ')
+
+/** Короткий людиночитний витяг фактів (без коду). */
+function factsSummary(facts) {
+  const m = facts.markers || {}
+  const lines = []
+  if (facts.header) lines.push(`Намір файлу: ${facts.header.replace(/\n/g, ' ')}`)
+  if (facts.exports?.length) lines.push(`Публічні функції: ${facts.exports.map(e => e.name).join(', ')}`)
+  if (m.skips?.length) lines.push(`Свідомо пропускає шляхи: ${m.skips.join(', ')}`)
+  lines.push(`Read-only: ${m.readOnly ? 'так' : 'ні'}`)
+  if (m.catchesErrors) lines.push('Перехоплює помилки (fail-safe), не кидає винятків назовні')
+  if (m.returnsFalsyOnFail) lines.push('За невдачі повертає false/null замість винятку')
+  lines.push(m.caches ? 'Кешування: так, у межах прогону' : 'Кешування: НЕМАЄ — не згадуй кеш у гарантіях')
+  if (m.network) lines.push('Звертається до мережі')
+  else lines.push('Робота з мережею: немає')
+  return lines.join('\n')
+}
+
+const msgs = (system, user) => [{ role: 'system', content: system }, { role: 'user', content: user }]
+
+/**
+ * Секційні набори messages з МІНІМАЛЬНИМ контекстом під кожну секцію.
+ * Код потрапляє лише в `behavior`; решта секцій — на факт-листі.
+ * @returns {Array<{key:string, messages:object[], numPredict:number}>}
+ */
+export function sectionMessages(facts, src) {
+  const factsTxt = factsSummary(facts)
+  const multi = (facts.exports?.length || 0) > 1
+  const out = []
+
+  // Огляд — лише факти (без коду)
+  out.push({
+    key: 'overview', numPredict: 220,
+    messages: msgs(`${STYLE}\n\nВІДОМІ ФАКТИ:\n${factsTxt}`,
+      'Напиши вміст секції «Огляд»: 1-3 речення — що файл робить і навіщо існує (роль у системі). Без заголовка, без переліку функцій.')
+  })
+
+  // Поведінка — ЄДИНА секція, якій потрібен код
+  out.push({
+    key: 'behavior', numPredict: 500,
+    messages: msgs(`${STYLE}\n\nФАЙЛ ${facts.relPath}:\n\`\`\`\n${src}\n\`\`\`\n\nВІДОМІ ФАКТИ:\n${factsTxt}`,
+      `Напиши вміст секції «Поведінка»: ${multi ? 'для кожної публічної функції — один короткий пункт «що вона робить»' : 'нумерований алгоритм у бізнес-термінах'}. Якщо у фактах є свідомі пропуски шляхів — згадай їх там, де доречно (не вигадуй інших «не перевіряє»). НЕ пиши аргументи функцій у дужках, без regex.${facts.internalSymbols?.length ? ` НЕ згадуй за іменами службові функції: ${facts.internalSymbols.join(', ')}.` : ''} Без заголовка.`)
+  })
+
+  // API — лише список експортів (без коду)
+  if (multi || facts.exports?.some(e => e.desc)) {
+    const list = facts.exports.map(e => `- ${e.name}: ${e.desc || '(сформулюй стисло з наміру файлу)'}`).join('\n')
+    out.push({
+      key: 'api', numPredict: 320,
+      messages: msgs(STYLE,
+        `Перепиши цей список як стислі маркери «назва — що робить», СВОЇМИ словами (не копіюй дослівно), без типів і сигнатур. Використовуй РІВНО ці назви, не додавай і не прибирай:\n${list}\nБез заголовка.`)
+    })
+  }
+
+  // Гарантії — лише markers (без коду)
+  out.push({
+    key: 'guarantees', numPredict: 300,
+    messages: msgs(`${STYLE}\n\nВІДОМІ ФАКТИ:\n${factsTxt}`,
+      'Напиши вміст секції «Гарантії поведінки» як маркери-інваріанти СУВОРО на основі ВІДОМИХ ФАКТІВ (read-only, fail-safe, пропуски). Згадуй кеш ЛИШЕ якщо у фактах прямо є «Кешує». Без сигнатур у дужках і без імен внутрішніх структур/Map-ів/кешів. Не вигадуй гарантій, яких немає у фактах. Без заголовка.')
+  })
+
+  return out
+}
+
+/** One-shot messages (база для порівняння). */
+export function oneShotMessages(facts, src) {
+  const multi = (facts.exports?.length || 0) > 1
+  return msgs(STYLE,
+    `Напиши документацію для файлу. Секції: ## Огляд (1-3 речення), ## Поведінка (нумерований/маркований алгоритм), ${multi ? '## Публічний API (назва + що робить), ' : ''}## Гарантії поведінки.\n\nФАЙЛ ${facts.relPath}:\n\`\`\`\n${src}\n\`\`\``)
+}