@nitra/cursor 1.41.0 → 2.0.0

package/scripts/dispatcher/lib/state-store.mjs

@@ -0,0 +1,173 @@
+/**
+ * Crash-safe сховище runtime-стану `flow` (spec §4, §4.1).
+ *
+ * Локація — **sibling-файл** `.worktrees/<sanitized-branch>.flow.json` поруч із
+ * checkout (НЕ всередині нього: файл усередині worktree = untracked у feature-
+ * гілці й ризикує потрапити в `git add -A`). Деривація шляху: для checkout-
+ * директорії `.worktrees/feat-x` стан → `.worktrees/feat-x.flow.json`.
+ *
+ * Crash-safety (§4.1):
+ *  - **atomic write**: temp на тому ж FS → `fsync` файла → `rename` (атомарна
+ *    заміна; частковий запис неможливий);
+ *  - **fail-closed на corruption**: нечитабельний/невалідний JSON або несумісний
+ *    `schema_version` → throw (не стартуємо новий flow над зіпсованим станом).
+ *
+ * Усі шляхи — абсолютні (вимога `no-relative-fs-path`).
+ */
+import {
+  closeSync,
+  existsSync,
+  fsyncSync,
+  mkdirSync,
+  openSync,
+  readFileSync,
+  renameSync,
+  rmSync,
+  writeFileSync
+} from 'node:fs'
+import { basename, dirname, isAbsolute, join } from 'node:path'
+import { randomBytes } from 'node:crypto'
+import { pid } from 'node:process'
+
+import { appendEvent } from './events.mjs'
+
+export const SCHEMA_VERSION = 1
+
+/**
+ * Шлях sibling-файла стану для заданого checkout-каталогу worktree.
+ * @param {string} worktreeDir абсолютний шлях checkout (напр. `…/.worktrees/feat-x`)
+ * @returns {string} абсолютний шлях `…/.worktrees/feat-x.flow.json`
+ */
+export function flowStatePath(worktreeDir) {
+  if (!isAbsolute(worktreeDir)) {
+    throw new Error(`flowStatePath: очікується абсолютний шлях (отримано: ${worktreeDir})`)
+  }
+  return join(dirname(worktreeDir), `${basename(worktreeDir)}.flow.json`)
+}
+
+/**
+ * fsync файла за абсолютним шляхом (дані на диск до rename).
+ * @param {string} path абсолютний шлях
+ * @returns {void}
+ */
+function fsyncPath(path) {
+  const fd = openSync(path, 'r')
+  try {
+    fsyncSync(fd)
+  } finally {
+    closeSync(fd)
+  }
+}
+
+/**
+ * Атомарно записує стан: temp(той самий каталог)+fsync+rename. Додає
+ * `schema_version`. Повертає фактично записаний об'єкт.
+ * @param {string} statePath абсолютний шлях `.flow.json`
+ * @param {object} state стан без `schema_version`
+ * @returns {object} записаний об'єкт (зі `schema_version`)
+ */
+export function writeState(statePath, state) {
+  if (!isAbsolute(statePath)) {
+    throw new Error(`writeState: очікується абсолютний шлях (отримано: ${statePath})`)
+  }
+  const dir = dirname(statePath)
+  mkdirSync(dir, { recursive: true })
+  const payload = { schema_version: SCHEMA_VERSION, ...state }
+  const tmp = join(dir, `.${basename(statePath)}.${pid}.${randomBytes(6).toString('hex')}.tmp`)
+  writeFileSync(tmp, `${JSON.stringify(payload, null, 2)}\n`, 'utf8')
+  fsyncPath(tmp)
+  renameSync(tmp, statePath)
+  // best-effort fsync каталогу (durability rename). Не на всіх платформах
+  // (Windows кидає EISDIR/EPERM) — тому загорнуто й помилки ігноруємо.
+  try {
+    fsyncPath(dir)
+  } catch {
+    /* fsync каталогу недоступний на цій платформі — некритично */
+  }
+  return payload
+}
+
+/**
+ * Читає стан. Відсутній файл → null. Пошкоджений JSON або несумісний
+ * `schema_version` → throw (**fail-closed**, §4.1.6).
+ * @param {string} statePath абсолютний шлях `.flow.json`
+ * @returns {object | null} стан або null, якщо файлу нема
+ */
+export function readState(statePath) {
+  if (!isAbsolute(statePath)) {
+    throw new Error(`readState: очікується абсолютний шлях (отримано: ${statePath})`)
+  }
+  if (!existsSync(statePath)) return null
+  const raw = readFileSync(statePath, 'utf8')
+  let parsed
+  try {
+    parsed = JSON.parse(raw)
+  } catch {
+    throw new Error(`readState: пошкоджений стан (невалідний JSON) у ${statePath} — fail-closed`)
+  }
+  if (typeof parsed !== 'object' || parsed === null || parsed.schema_version !== SCHEMA_VERSION) {
+    throw new Error(
+      `readState: несумісний або пошкоджений schema_version у ${statePath} ` +
+        `(очікується ${SCHEMA_VERSION}) — fail-closed`
+    )
+  }
+  return parsed
+}
+
+/**
+ * Читає стан, застосовує `fn` і атомарно записує результат. Якщо файлу нема —
+ * `fn` отримує `{}`.
+ * @param {string} statePath абсолютний шлях `.flow.json`
+ * @param {(state: object) => object} fn трансформер стану
+ * @returns {object} записаний об'єкт
+ */
+export function updateState(statePath, fn) {
+  const current = readState(statePath)
+  return writeState(statePath, fn(current ?? {}))
+}
+
+/**
+ * Видаляє sibling-файл стану (cleanup при `worktree remove` / `flow cancel`).
+ * Ідемпотентно (відсутній файл — не помилка).
+ * @param {string} statePath абсолютний шлях `.flow.json`
+ * @returns {void}
+ */
+export function removeState(statePath) {
+  if (!isAbsolute(statePath)) {
+    throw new Error(`removeState: очікується абсолютний шлях (отримано: ${statePath})`)
+  }
+  rmSync(statePath, { force: true })
+}
+
+/**
+ * WAL-перехід (§4.1.2): спершу дописує подію в журнал, ТОДІ атомарно змінює
+ * статус у snapshot. Якщо запис стану впаде — подія вже durable (журнал —
+ * джерело для reconcile при `resume`).
+ * @param {{ statePath: string, eventsPath: string }} paths шляхи стану й журналу
+ * @param {object} event подія переходу
+ * @param {(state: object) => object} stateFn трансформер стану
+ * @param {() => number} [now] фабрика часу (ms)
+ * @returns {object} записаний стан
+ */
+export function recordTransition({ statePath, eventsPath }, event, stateFn, now = Date.now) {
+  appendEvent(eventsPath, event, now)
+  return updateState(statePath, stateFn)
+}
+
+/**
+ * Прибирає всі runtime-sibling-и worktree: `.flow.json`, `.events.jsonl`,
+ * лок-каталог `.flow-lock-<branch>/`. Ідемпотентно. Викликається `flow cancel`
+ * і `worktree remove` (інакше sibling-и осиротіють — git їх не чистить).
+ * @param {string} worktreeDir абсолютний шлях checkout (`…/.worktrees/feat-x`)
+ * @returns {void}
+ */
+export function cleanupFlowSiblings(worktreeDir) {
+  if (!isAbsolute(worktreeDir)) {
+    throw new Error(`cleanupFlowSiblings: очікується абсолютний шлях (отримано: ${worktreeDir})`)
+  }
+  const base = basename(worktreeDir)
+  const dir = dirname(worktreeDir)
+  rmSync(join(dir, `${base}.flow.json`), { force: true })
+  rmSync(join(dir, `${base}.events.jsonl`), { force: true })
+  rmSync(join(dir, `.flow-lock-${base}`), { recursive: true, force: true })
+}

package/scripts/dispatcher/lib/subagent-runner.mjs

@@ -0,0 +1,120 @@
+/**
+ * SubagentRunner (spec §15.1) — абстракція спавну сфокусованого субагента для
+ * Активного Раннера (Ф3/Ф4). Backend обирається за доступністю:
+ *   1. `claude-agent-sdk` (програмний, потребує `ANTHROPIC_API_KEY`);
+ *   2. `claude -p` (CLI-auth користувача);
+ *   3. `cursor-agent -p` (CLI-auth).
+ * Нема жодного → throw (polyfill без runner-а не стартує, §2.2).
+ *
+ * pi.dev для inner-спавну НЕ використовується: у автономному режимі pi.dev —
+ * зовнішній драйвер, тож спавн ним внутрішніх субагентів = рекурсія (§9.1).
+ *
+ * Усі probe-залежності (`spawn`/`isInPath`/`canImportSdk`/`query`) ін'єктуються,
+ * щоб тестувати без реальних процесів і без SDK.
+ */
+import { spawnSync } from 'node:child_process'
+import { env as processEnv } from 'node:process'
+
+const NO_BACKEND =
+  'SubagentRunner: ні claude-agent-sdk (з ANTHROPIC_API_KEY), ні `claude`/`cursor-agent` у PATH — ' +
+  'субагентів спавнити нічим. Встанови CLI-runner або задай ANTHROPIC_API_KEY.'
+
+/**
+ * Чи є бінарник у PATH (через `command -v`).
+ * @param {string} name ім'я виконуваного
+ * @param {typeof import('node:child_process').spawnSync} [spawn] ін'єкція для тестів
+ * @returns {boolean} true, якщо знайдено
+ */
+export function isBinaryInPath(name, spawn = spawnSync) {
+  const r = spawn('command', ['-v', name], { shell: true, encoding: 'utf8' })
+  return (r.status ?? 1) === 0
+}
+
+/**
+ * Обирає backend субагентів за пріоритетом sdk > claude > cursor.
+ * @param {{ hasApiKey: boolean, canImportSdk: boolean, isInPath: (name: string) => boolean }} probes доступність
+ * @returns {'sdk' | 'claude' | 'cursor' | null} backend або null
+ */
+export function selectBackend({ hasApiKey, canImportSdk, isInPath }) {
+  if (hasApiKey && canImportSdk) return 'sdk'
+  if (isInPath('claude')) return 'claude'
+  if (isInPath('cursor-agent')) return 'cursor'
+  return null
+}
+
+/**
+ * CLI-runner (`claude -p` / `cursor-agent -p`) — CLI-auth, без API key.
+ * @param {'claude' | 'cursor-agent'} bin виконуваний
+ * @param {{ spawn?: typeof import('node:child_process').spawnSync }} [deps] ін'єкція
+ * @returns {{ backend: string, runStep: (prompt: string, opts?: { cwd?: string }) => { ok: boolean, output: string } }} runner
+ */
+export function cliRunner(bin, deps = {}) {
+  const spawn = deps.spawn ?? spawnSync
+  return {
+    backend: bin,
+    runStep(prompt, { cwd } = {}) {
+      const r = spawn(bin, ['-p'], { input: prompt, cwd, encoding: 'utf8' })
+      return { ok: (r.status ?? 1) === 0, output: `${r.stdout ?? ''}${r.stderr ?? ''}` }
+    }
+  }
+}
+
+/**
+ * SDK-runner (`claude-agent-sdk`). `query` ін'єктується; за замовчуванням —
+ * динамічний import (optional dependency).
+ * @param {{ query?: (input: object) => object }} [deps] ін'єкція (query повертає async-iterable повідомлень)
+ * @returns {{ backend: string, runStep: (prompt: string, opts?: { cwd?: string }) => Promise<{ ok: boolean, output: string }> }} runner
+ */
+export function sdkRunner(deps = {}) {
+  return {
+    backend: 'sdk',
+    async runStep(prompt, { cwd } = {}) {
+      let query = deps.query
+      if (!query) {
+        const mod = await import('@anthropic-ai/claude-agent-sdk')
+        query = mod.query
+      }
+      let output = ''
+      let ok = true
+      try {
+        for await (const msg of query({ prompt, options: { cwd, maxTurns: 20, allowedTools: ['Read', 'Edit', 'Bash'] } })) {
+          if (typeof msg?.text === 'string') output += msg.text
+          if (msg?.type === 'result') ok = msg.is_error !== true
+        }
+      } catch (error) {
+        return { ok: false, output: String(error?.message ?? error) }
+      }
+      return { ok, output }
+    }
+  }
+}
+
+/**
+ * Створює runner за доступним backend-ом. `backend`/probe-и можна задати явно
+ * (тести); інакше визначаються з env/PATH/SDK.
+ * @param {{ backend?: string, env?: Record<string, string | undefined>, isInPath?: (name: string) => boolean, canImportSdk?: boolean, spawn?: (cmd: string, args: string[], opts: object) => object, query?: (input: object) => object }} [deps] ін'єкції
+ * @returns {Promise<{ backend: string, runStep: (prompt: string, opts?: object) => object }>} runner
+ */
+export async function createRunner(deps = {}) {
+  const env = deps.env ?? processEnv
+  const isInPath = deps.isInPath ?? (name => isBinaryInPath(name, deps.spawn))
+  const canImportSdk = deps.canImportSdk ?? (await probeSdk())
+  const backend =
+    deps.backend ?? selectBackend({ hasApiKey: Boolean(env.ANTHROPIC_API_KEY), canImportSdk, isInPath })
+  if (!backend) throw new Error(NO_BACKEND)
+  if (backend === 'sdk') return sdkRunner(deps)
+  return cliRunner(backend === 'claude' ? 'claude' : 'cursor-agent', deps)
+}
+
+/**
+ * Чи імпортується `claude-agent-sdk` (optional dependency).
+ * @returns {Promise<boolean>} true, якщо доступний
+ */
+async function probeSdk() {
+  try {
+    await import('@anthropic-ai/claude-agent-sdk')
+    return true
+  } catch {
+    return false
+  }
+}

package/scripts/dispatcher/trace.mjs

@@ -0,0 +1,114 @@
+/**
+ * `n-cursor trace` (spec §5.4/§7) — наскрізна простежуваність: читає front-matter
+ * артефактів у `docs/{tasks,specs,plans,adr}`, будує ланцюг за лінками
+ * (`adr`/`spec`/`plan`/`change`/`task`) і **флагує розриви** (лінк на неіснуючий
+ * файл). Read-only. `--json` для machine-readable.
+ *
+ * FS-доступ (`readdir`/`readFile`/`exists`) ін'єктується — тестується без диска.
+ */
+import { existsSync, readdirSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { cwd as processCwd } from 'node:process'
+
+/** Поля-лінки у front-matter, що утворюють ланцюг. */
+const LINK_FIELDS = ['adr', 'spec', 'plan', 'change', 'task']
+
+/** Каталоги з traceable-артефактами. */
+const DIRS = ['docs/tasks', 'docs/specs', 'docs/plans', 'docs/adr']
+
+/**
+ * Парсить плаский YAML-front-matter (key: value). Не обробляє вкладеність —
+ * достатньо для spec/plan/task-record полів. Інлайн-коментарі (` #…`) відрізає.
+ * @param {string} content вміст файла
+ * @returns {Record<string, string | null> | null} мапа полів або null, якщо немає front-matter
+ */
+export function parseFrontMatter(content) {
+  if (!content.startsWith('---')) return null
+  const end = content.indexOf('\n---', 3)
+  if (end === -1) return null
+  const fm = {}
+  for (const line of content.slice(3, end).split('\n')) {
+    const ci = line.indexOf(':')
+    if (ci === -1) continue
+    const key = line.slice(0, ci).trim()
+    if (!isSimpleKey(key)) continue
+    let val = line.slice(ci + 1)
+    const hi = val.indexOf(' #')
+    if (hi !== -1) val = val.slice(0, hi)
+    val = val.trim().replace(/^["']/u, '').replace(/["']$/u, '')
+    fm[key] = val === '' || val === 'null' ? null : val
+  }
+  return fm
+}
+
+/**
+ * Чи `key` — простий ідентифікатор (літери/підкреслення).
+ * @param {string} key ключ
+ * @returns {boolean} true для простого ключа
+ */
+function isSimpleKey(key) {
+  return key.length > 0 && [...key].every(c => /[a-z_]/iu.test(c))
+}
+
+/**
+ * Будує аналіз: для кожного артефакту — його лінки зі статусом ok/розрив.
+ * @param {{ file: string, fm: Record<string, string | null> }[]} artifacts артефакти з front-matter
+ * @param {(target: string) => boolean} exists чи існує цільовий файл лінка
+ * @returns {{ file: string, kind: string | null, id: string | null, status: string | null, links: { field: string, target: string, ok: boolean }[] }[]} аналіз
+ */
+export function analyze(artifacts, exists) {
+  return artifacts.map(({ file, fm }) => ({
+    file,
+    kind: fm.kind ?? null,
+    id: fm.id ?? null,
+    status: fm.status ?? null,
+    links: LINK_FIELDS.filter(f => fm[f]).map(f => ({ field: f, target: fm[f], ok: exists(fm[f]) }))
+  }))
+}
+
+/**
+ * Текстовий рендер аналізу.
+ * @param {object[]} analysis результат `analyze`
+ * @returns {string} людино-читабельний вивід
+ */
+export function render(analysis) {
+  if (analysis.length === 0) return 'trace: артефактів із front-matter не знайдено'
+  const lines = []
+  for (const a of analysis) {
+    lines.push(`${a.kind ?? '?'} · ${a.id ?? a.file} [${a.status ?? '—'}]`)
+    for (const l of a.links) {
+      const mark = l.ok ? '→' : '✗'
+      const note = l.ok ? '' : ' (РОЗРИВ — файл відсутній)'
+      lines.push(`   ${mark} ${l.field}: ${l.target}${note}`)
+    }
+  }
+  return lines.join('\n')
+}
+
+/**
+ * CLI `n-cursor trace [--json]`. Повертає 1, якщо є розриви ланцюга.
+ * @param {string[]} args аргументи
+ * @param {{ cwd?: string, readdir?: (dir: string) => string[], readFile?: (file: string) => string, exists?: (file: string) => boolean, log?: (m: string) => void }} [deps] ін'єкції
+ * @returns {number} exit code (0 — цілісно, 1 — є розриви)
+ */
+export function runTraceCli(args, deps = {}) {
+  const root = deps.cwd ?? processCwd()
+  const readdir = deps.readdir ?? (dir => (existsSync(dir) ? readdirSync(dir) : []))
+  const readFile = deps.readFile ?? (file => readFileSync(file, 'utf8'))
+  const exists = deps.exists ?? (file => existsSync(file))
+  const log = deps.log ?? console.log
+
+  const artifacts = []
+  for (const dir of DIRS) {
+    for (const name of readdir(join(root, dir))) {
+      if (!name.endsWith('.md')) continue
+      const rel = `${dir}/${name}`
+      const fm = parseFrontMatter(readFile(join(root, rel)))
+      if (fm && (fm.id || fm.kind)) artifacts.push({ file: rel, fm })
+    }
+  }
+
+  const analysis = analyze(artifacts, target => exists(join(root, target)))
+  log(args.includes('--json') ? JSON.stringify(analysis, null, 2) : render(analysis))
+  return analysis.some(a => a.links.some(l => !l.ok)) ? 1 : 0
+}

package/scripts/utils/with-lock.mjs

@@ -13,7 +13,8 @@ const DEFAULTS = {
   ttl: 600_000,
   staleThreshold: 1_800_000,
   waitTimeout: 1_200_000,
-  pollInterval: 1500
+  pollInterval: 1500,
+  onWaitTimeout: 'run-unlocked'
 }
 
 /**
@@ -57,11 +58,11 @@ export function shouldDedup(result, fingerprint, ttl) {
  * Серіалізує важку команду через атомарний lock і dedup за fingerprint.
  * @param {string} key ключ локу (наприклад `lint-ga`, `fix-bun`)
  * @param {() => number | Promise<number>} runFn основна робота; повертає exit code
- * @param {{ttl?:number, staleThreshold?:number, waitTimeout?:number, pollInterval?:number, cacheDir?:string, getFingerprint?:() => string | null}} [opts] TTL, шлях кешу та override fingerprint
+ * @param {{ttl?:number, staleThreshold?:number, waitTimeout?:number, pollInterval?:number, onWaitTimeout?:'run-unlocked'|'fail', cacheDir?:string, getFingerprint?:() => string | null}} [opts] TTL, шлях кешу, поведінка на таймаут (default `run-unlocked`; `fail` = fail-closed) та override fingerprint
  * @returns {Promise<number>} exit code виконаної або дедуплікованої команди
  */
 export async function withLock(key, runFn, opts = {}) {
-  const { ttl, staleThreshold, waitTimeout, pollInterval } = { ...DEFAULTS, ...opts }
+  const { ttl, staleThreshold, waitTimeout, pollInterval, onWaitTimeout } = { ...DEFAULTS, ...opts }
   const getFingerprint = opts.getFingerprint ?? worktreeFingerprint
   const cacheDir = opts.cacheDir ?? resolveLockCacheDir(key)
   const lockDir = join(cacheDir, 'lock')
@@ -76,6 +77,9 @@ export async function withLock(key, runFn, opts = {}) {
 
   while (true) {
     if (Date.now() - loopStart >= waitTimeout) {
+      if (onWaitTimeout === 'fail') {
+        throw new Error(`${key}: не вдалося взяти лок за ${waitTimeout / 60_000} хв — fail-closed`)
+      }
       console.error(`⚠️ ${key}: чекав ${waitTimeout / 60_000} хв — запускаю без локу`)
       return await runFn()
     }

package/scripts/worktree-cli.mjs

@@ -15,6 +15,7 @@ import { existsSync, readdirSync, readFileSync, rmSync, writeFileSync } from 'no
 import { join } from 'node:path'
 import { cwd as processCwd } from 'node:process'
 
+import { cleanupFlowSiblings } from './dispatcher/lib/state-store.mjs'
 import { buildDescription, findOrphanDescFiles, worktreePaths } from './lib/worktree.mjs'
 
 const USAGE = [
@@ -136,6 +137,7 @@ function cmdRemove(rest, ctx) {
     return 1
   }
   if (existsSync(paths.descFile)) rmSync(paths.descFile, { force: true })
+  cleanupFlowSiblings(paths.checkout) // flow-sibling-и (.flow.json/.events.jsonl/lock) — інакше осиротіють (§1.4)
   ctx.log(`✅ прибрано: ${paths.checkout} (гілку ${branch} лишено)`)
   return 0
 }
@@ -185,16 +187,21 @@ export function runWorktreeCli(argv, options = {}) {
   }
   const [sub, ...rest] = argv
   switch (sub) {
-    case 'add':
+    case 'add': {
       return Promise.resolve(cmdAdd(rest, ctx))
-    case 'remove':
+    }
+    case 'remove': {
       return Promise.resolve(cmdRemove(rest, ctx))
-    case 'list':
+    }
+    case 'list': {
       return Promise.resolve(cmdList(ctx))
-    case 'prune':
+    }
+    case 'prune': {
       return Promise.resolve(cmdPrune(ctx))
-    default:
+    }
+    default: {
       ctx.logError(USAGE)
       return Promise.resolve(1)
+    }
   }
 }