@nitra/cursor 4.1.0 → 4.1.1

package/scripts/dispatcher/lib/docs/events.md

@@ -119,6 +119,7 @@ Default-експорт відсутній.
 1. **Обчислення шляху журналу** — один раз на сесію/процес:
    ```js
    import { flowEventsPath, appendEvent, readEvents } from './events.mjs'
+   
    const eventsPath = flowEventsPath('/repo/.worktrees/feat-x')
    // → '/repo/.worktrees/feat-x.events.jsonl'
    ```

package/scripts/dispatcher/lib/executor.mjs

@@ -49,7 +49,7 @@ export function patchStep(state, index, patch) {
  * @returns {Promise<{ status: 'done' | 'blocked-on-human', step?: number }>} результат
  */
 export async function executePlan(paths, deps) {
-  const { runner, verify, commit, cwd, maxRepairAttempts = 3, log = () => {}, now = Date.now } = deps
+  const { runner, verify, commit, cwd, maxRepairAttempts = 3, log = () => { /* noop */ }, now = Date.now } = deps
   let state = readState(paths.statePath)
   if (!state?.plan?.length) {
     throw new Error('executor: у стані немає плану — спершу planner')

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

@@ -14,10 +14,10 @@ import { resolveModel } from '../../../lib/models.mjs'
 
 /**
  * Викликає pi і повертає { ok, output }.
- * @param {string} prompt
+ * @param {string} prompt текст промпта
  * @param {string} model  provider/model-id або '' для pi-дефолту
- * @param {{ cwd?: string }} [opts]
- * @returns {{ ok: boolean, output: string }}
+ * @param {{ cwd?: string }} [opts] опційні параметри (cwd)
+ * @returns {{ ok: boolean, output: string }} результат із статусом і output
  */
 function callPi(prompt, model, { cwd } = {}) {
   const modelArgs = model ? ['--model', model] : []
@@ -27,26 +27,26 @@ function callPi(prompt, model, { cwd } = {}) {
     timeout: 600_000
   })
   const ok = !r.error && r.status === 0
-  const output = (r.stdout ?? '') + (r.error ? r.error.message : !ok ? (r.stderr ?? '') : '')
+  const output = (r.stdout ?? '') + (r.error ? r.error.message : (ok ? '' : (r.stderr ?? '')))
   return { ok, output }
 }
 
 /**
  * Створює pi-runner. Повертає { backend: 'pi', runStep }.
  * @param {{ model?: string, callPi?: Function }} [deps]  ін'єкції для тестів
- * @returns {Promise<{ backend: string, runStep: (prompt: string, opts?: object) => Promise<{ ok: boolean, output: string }> }>}
+ * @returns {Promise<{ backend: string, runStep: (prompt: string, opts?: object) => Promise<{ ok: boolean, output: string }> }>} runner із backend='pi' і методом runStep
  */
-export async function createRunner(deps = {}) {
+export function createRunner(deps = {}) {
   const model = deps.model ?? resolveModel('avg')
   const callPiFn = deps.callPi ?? callPi
 
   return {
     backend: 'pi',
-    async runStep(prompt, opts = {}) {
+    runStep(prompt, opts = {}) {
       try {
         return callPiFn(prompt, model, opts)
-      } catch (e) {
-        return { ok: false, output: String(e?.message ?? e) }
+      } catch (error) {
+        return { ok: false, output: String(error?.message ?? error) }
       }
     }
   }

package/scripts/dispatcher/trace.mjs

@@ -24,6 +24,10 @@ const INFO_LINK_FIELDS = new Set(['flow'])
 /** Каталоги з traceable-артефактами. */
 const DIRS = ['docs/tasks', 'docs/specs', 'docs/plans', 'docs/adr']
 
+const LEADING_QUOTE_RE = /^["']/u
+const TRAILING_QUOTE_RE = /["']$/u
+const SIMPLE_KEY_CHAR_RE = /[a-z_]/iu
+
 /**
  * Парсить плаский YAML-front-matter (key: value). Не обробляє вкладеність —
  * достатньо для spec/plan/task-record полів. Інлайн-коментарі (` #…`) відрізає.
@@ -43,7 +47,7 @@ export function parseFrontMatter(content) {
     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, '')
+    val = val.trim().replace(LEADING_QUOTE_RE, '').replace(TRAILING_QUOTE_RE, '')
     fm[key] = val === '' || val === 'null' ? null : val
   }
   return fm
@@ -55,7 +59,7 @@ export function parseFrontMatter(content) {
  * @returns {boolean} true для простого ключа
  */
 function isSimpleKey(key) {
-  return key.length > 0 && [...key].every(c => /[a-z_]/iu.test(c))
+  return key.length > 0 && [...key].every(c => SIMPLE_KEY_CHAR_RE.test(c))
 }
 
 /**

package/scripts/docs/build-agents-commands.md

@@ -154,6 +154,7 @@ const items = await buildAgentsCommandBulletItems(process.cwd())
 
    ```js
    import { buildAgentsCommandBulletItems } from '/абсолютний/шлях/до/build-agents-commands.mjs'
+   
    const items = await buildAgentsCommandBulletItems('/абсолютний/шлях/до/тимчасової/теки')
    console.log(items)
    ```

package/scripts/docs/cli-entry.md

@@ -94,6 +94,9 @@ export function isRunAsCli(metaUrl)
 ```js
 import { isRunAsCli } from './cli-entry.mjs' // або відносний шлях
 
+/**
+ *
+ */
 export async function runCli(argv) {
   // ...
 }
@@ -111,6 +114,9 @@ if (isRunAsCli(import.meta.url)) {
 // my-tool.mjs
 import { isRunAsCli } from '../scripts/cli-entry.mjs'
 
+/**
+ *
+ */
 export function doWork(args) {
   /* ... */
 }

package/scripts/graph/index.mjs

@@ -0,0 +1,115 @@
+/**
+ * `n-cursor graph` — CLI entry point для нової graph-архітектури.
+ * Реалізує команди з docs/думка.MD (фінальний дизайн 2026-06-07).
+ */
+
+/**
+ * @param {string[]} argv процесні аргументи після 'graph'
+ * @returns {Promise<number>} exit code
+ */
+export async function runGraphCli(argv) {
+  const [cmd, ...rest] = argv
+
+  const hasJson = rest.includes('--json')
+  const cleanRest = rest.filter(a => a !== '--json')
+
+  switch (cmd) {
+    case 'scan':
+      return (await import('./scan.mjs')).runScan(cleanRest, { json: hasJson })
+
+    case 'status': {
+      const path = cleanRest[0]
+      return (await import('./status.mjs')).runStatus(path, { json: hasJson })
+    }
+
+    case 'setup':
+      return (await import('./setup.mjs')).runSetup(cleanRest)
+
+    case 'init': {
+      const [name, ...initRest] = cleanRest
+      return (await import('./init.mjs')).runInit(name, parseFlags(initRest))
+    }
+
+    case 'plan': {
+      const flags = parseFlags(cleanRest)
+      return (await import('./plan.mjs')).runPlan(flags.path, flags)
+    }
+
+    case 'run': {
+      const flags = parseFlags(cleanRest)
+      return (await import('./run.mjs')).runRun(flags.path, flags)
+    }
+
+    case 'kill': {
+      const path = cleanRest[0]
+      return (await import('./kill.mjs')).runKill(path)
+    }
+
+    case 'invalidate': {
+      const flags = parseFlags(cleanRest)
+      return (await import('./invalidate.mjs')).runInvalidate(flags.path, flags)
+    }
+
+    case 'done':
+    case 'audit':
+    case 'failed':
+    case 'spawn': {
+      const path = cleanRest[0]
+      return (await import('./signals.mjs')).runSignal(cmd, path, parseFlags(cleanRest.slice(1)))
+    }
+
+    case undefined:
+    case '--help':
+    case 'help':
+      printHelp()
+      return 0
+
+    default:
+      console.error(`Unknown graph command: ${cmd}`)
+      printHelp()
+      return 1
+  }
+}
+
+/** @param {string[]} args @returns {Record<string, string | boolean>} */
+function parseFlags(args) {
+  /** @type {Record<string, string | boolean>} */
+  const flags = {}
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i]
+    if (a.startsWith('--')) {
+      const key = a.slice(2)
+      const next = args[i + 1]
+      if (next && !next.startsWith('--')) {
+        flags[key] = next
+        i++
+      } else {
+        flags[key] = true
+      }
+    } else if (!flags.path) {
+      flags.path = a
+    }
+  }
+  return flags
+}
+
+function printHelp() {
+  console.log(`n-cursor graph <command> [options]
+
+Commands:
+  setup                              Initialize project (.n-cursor.json, hooks)
+  init <name> [--task "..."]         Create task.md for a new node
+  plan [<path>] [--mode agent]       Stage 1: spec + decompose → plan_NNN.md
+  status [<path>] [--json]           Show graph or node state
+  scan [--json]                      Full scan; exit 1 if any failed nodes
+  run [<path>] [--actor a] [--auto]  Execute node or run orchestrator
+  kill <path>                        Kill worktrees + cascade invalidate
+  invalidate <path> [--no-cascade]   Mark node as invalidated
+
+Agent signals (called from within worktree):
+  done <path>                        Signal success → merge
+  audit <path>                       Request audit → pending-audit_NNN.md
+  failed <path>                      Signal failure
+  spawn <path>                       Register composite subgraph
+`)
+}

package/scripts/graph/lib/config.mjs

@@ -0,0 +1,62 @@
+/**
+ * Завантаження `.n-cursor.json` + per-node `.n-cursor-override.json`.
+ * Всі поля опціональні — повертає merge із дефолтами.
+ */
+import { existsSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+/** @typedef {{ tasks_dir: string, worktrees_dir: string, warn_worktrees_above: number, max_worktrees: number, default_budget_sec: number, budget_hard_sec_multiplier: number, progress_timeout_sec: number, stderr_lines: number, claude_model: string, audit_model: string, model_map: Record<string,string>, stale_worktree_min: number, system_prompt: string }} GraphConfig */
+
+/** @type {GraphConfig} */
+const DEFAULTS = {
+  tasks_dir: './tasks',
+  worktrees_dir: './.worktrees',
+  warn_worktrees_above: 4,
+  max_worktrees: 8,
+  default_budget_sec: 1800,
+  budget_hard_sec_multiplier: 3,
+  progress_timeout_sec: 300,
+  stderr_lines: 50,
+  claude_model: 'claude-sonnet-4-6',
+  audit_model: 'claude-haiku-4-5-20251001',
+  model_map: {
+    MIM: 'claude-haiku-4-5-20251001',
+    AVG: 'claude-sonnet-4-6',
+    MAX: 'claude-opus-4-8',
+  },
+  stale_worktree_min: 30,
+  system_prompt: '.n-cursor/system-prompt.md',
+}
+
+/**
+ * Читає `.n-cursor.json` з root та мержить із дефолтами.
+ * @param {string} root
+ * @returns {GraphConfig}
+ */
+export function loadConfig(root) {
+  const path = join(root, '.n-cursor.json')
+  if (!existsSync(path)) return { ...DEFAULTS }
+  try {
+    const raw = JSON.parse(readFileSync(path, 'utf8'))
+    return { ...DEFAULTS, ...raw, model_map: { ...DEFAULTS.model_map, ...raw.model_map } }
+  } catch {
+    return { ...DEFAULTS }
+  }
+}
+
+/**
+ * Читає per-node `.n-cursor-override.json` та мержить із базовим конфігом.
+ * @param {GraphConfig} base
+ * @param {string} nodePath абсолютний шлях до директорії вузла
+ * @returns {GraphConfig}
+ */
+export function loadNodeOverride(base, nodePath) {
+  const path = join(nodePath, '.n-cursor-override.json')
+  if (!existsSync(path)) return base
+  try {
+    const raw = JSON.parse(readFileSync(path, 'utf8'))
+    return { ...base, ...raw }
+  } catch {
+    return base
+  }
+}

package/scripts/graph/lib/dag.mjs

@@ -0,0 +1,161 @@
+/**
+ * Побудова DAG з файлової структури `tasks/`.
+ * Читає task.md кожного вузла (один раз), будує граф в пам'яті.
+ * Deps satisfaction вираховується пакетно — не per-node.
+ */
+import { existsSync, readFileSync, readdirSync } from 'node:fs'
+import { join, relative } from 'node:path'
+
+import { parseFrontmatter } from './frontmatter.mjs'
+import { deriveAtomicState, deriveCompositeState } from './state.mjs'
+
+/**
+ * @typedef {{
+ *   id: string,
+ *   path: string,
+ *   parentId: string | null,
+ *   deps: string[],
+ *   mode: string,
+ *   executor: { type: string, model_tier: string, skills: string[] },
+ *   budget_sec: number,
+ *   isComposite: boolean,
+ *   children: string[],
+ *   state: import('./state.mjs').NodeState,
+ *   meta: Record<string, unknown>
+ * }} GraphNode
+ */
+
+/**
+ * Сканує tasks_dir і будує повний DAG.
+ * @param {string} tasksDir абсолютний шлях
+ * @param {string} [worktreesDir]
+ * @returns {Map<string, GraphNode>}
+ */
+export function buildDag(tasksDir, worktreesDir = '') {
+  /** @type {Map<string, GraphNode>} */
+  const nodes = new Map()
+
+  // 1. Collect all nodes
+  collectNodes(tasksDir, tasksDir, null, nodes)
+
+  // 2. Resolve parent-child relationships
+  for (const node of nodes.values()) {
+    if (node.parentId) {
+      const parent = nodes.get(node.parentId)
+      if (parent && !parent.children.includes(node.id)) {
+        parent.children.push(node.id)
+        parent.isComposite = true
+      }
+    }
+  }
+
+  // 3. Derive states (bottom-up)
+  const resolvedIds = new Set()
+  deriveStatesBottomUp(tasksDir, nodes, resolvedIds, worktreesDir)
+
+  return nodes
+}
+
+/**
+ * @param {string} dir поточна директорія
+ * @param {string} tasksDir корінь tasks
+ * @param {string | null} parentId
+ * @param {Map<string, GraphNode>} nodes
+ */
+function collectNodes(dir, tasksDir, parentId, nodes) {
+  const taskFile = join(dir, 'task.md')
+  if (!existsSync(taskFile)) return
+
+  const id = relative(tasksDir, dir).replace(/\\/gu, '/')
+  if (!id) return
+
+  const { data } = parseFrontmatter(readSafe(taskFile))
+
+  /** @type {string[]} */
+  const deps = Array.isArray(data.deps) ? data.deps.map(String) : []
+
+  const executor = typeof data.executor === 'object' && data.executor !== null
+    ? data.executor
+    : { type: 'agent', model_tier: 'AVG', skills: [] }
+
+  /** @type {GraphNode} */
+  const node = {
+    id,
+    path: dir,
+    parentId,
+    deps,
+    mode: String(data.mode ?? 'human'),
+    executor: {
+      type: String(executor.type ?? 'agent'),
+      model_tier: String(executor.model_tier ?? 'AVG'),
+      skills: Array.isArray(executor.skills) ? executor.skills : [],
+    },
+    budget_sec: Number(data.budget_sec ?? 1800),
+    isComposite: false,
+    children: [],
+    state: 'needs-plan',
+    meta: data,
+  }
+
+  nodes.set(id, node)
+
+  // Scan children
+  try {
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+      if (entry.isDirectory()) {
+        collectNodes(join(dir, entry.name), tasksDir, id, nodes)
+      }
+    }
+  } catch { /* skip */ }
+}
+
+/**
+ * Обходить граф знизу вверх (листи → корінь) і деривує стани.
+ * @param {string} tasksDir
+ * @param {Map<string, GraphNode>} nodes
+ * @param {Set<string>} resolvedIds
+ * @param {string} worktreesDir
+ */
+function deriveStatesBottomUp(tasksDir, nodes, resolvedIds, worktreesDir) {
+  // Topological sort (Kahn's algorithm by deps within siblings)
+  const visited = new Set()
+  const order = []
+
+  /** @param {string} id */
+  function visit(id) {
+    if (visited.has(id)) return
+    visited.add(id)
+    const node = nodes.get(id)
+    if (!node) return
+    for (const child of node.children) visit(child)
+    order.push(id)
+  }
+
+  for (const id of nodes.keys()) visit(id)
+
+  // Process leaves first (order is reversed)
+  for (const id of order) {
+    const node = nodes.get(id)
+    if (!node) continue
+
+    if (node.isComposite) {
+      const childStates = node.children.map(cid => nodes.get(cid)?.state ?? 'needs-plan')
+      node.state = deriveCompositeState(node.path, childStates)
+    } else {
+      const depsResolved = node.deps.every(dep => {
+        // Deps are sibling IDs — resolve relative to parent
+        const siblingId = node.parentId ? `${node.parentId}/${dep}` : dep
+        const sibling = nodes.get(siblingId) ?? nodes.get(dep)
+        return sibling?.state === 'resolved'
+      })
+      node.state = deriveAtomicState(node.path, { depsResolved })
+    }
+
+    if (node.state === 'resolved') resolvedIds.add(id)
+  }
+}
+
+/** @param {string} path @returns {string} */
+function readSafe(path) {
+  try { return readFileSync(path, 'utf8') } catch { return '' }
+}

package/scripts/graph/lib/frontmatter.mjs

@@ -0,0 +1,70 @@
+/**
+ * Мінімальний YAML-фронтматер парсер для Markdown-файлів.
+ * Підтримує: рядки, числа, boolean, масиви (flow і block), вкладені об'єкти (один рівень).
+ */
+
+const FM_RE = /^---\r?\n([\s\S]*?)\r?\n---/u
+
+/**
+ * @param {string} content вміст md-файлу
+ * @returns {{ data: Record<string, unknown>, body: string }}
+ */
+export function parseFrontmatter(content) {
+  const m = FM_RE.exec(content)
+  if (!m) return { data: {}, body: content }
+  const raw = m[1]
+  const body = content.slice(m[0].length).trimStart()
+  return { data: parseYamlBlock(raw), body }
+}
+
+/**
+ * @param {string} block YAML-блок між ---
+ * @returns {Record<string, unknown>}
+ */
+function parseYamlBlock(block) {
+  const result = {}
+  const lines = block.split(/\r?\n/u)
+  let i = 0
+
+  while (i < lines.length) {
+    const line = lines[i]
+    const keyMatch = /^([a-z_][a-z0-9_]*):\s*(.*)/iu.exec(line)
+    if (!keyMatch) { i++; continue }
+
+    const key = keyMatch[1]
+    const rest = keyMatch[2].trim()
+
+    if (rest === '' || rest === '|' || rest === '>') {
+      // block scalar або об'єкт — збираємо indented рядки
+      const children = []
+      i++
+      while (i < lines.length && /^\s+/u.test(lines[i])) {
+        children.push(lines[i])
+        i++
+      }
+      if (children.length > 0 && /^\s+-\s+/u.test(children[0])) {
+        result[key] = children.map(l => l.replace(/^\s+-\s+/u, '').trim())
+      } else {
+        result[key] = parseYamlBlock(children.map(l => l.replace(/^\s{2}/u, '')).join('\n'))
+      }
+    } else if (rest.startsWith('[')) {
+      result[key] = rest.slice(1, rest.lastIndexOf(']')).split(',').map(s => s.trim()).filter(Boolean)
+      i++
+    } else {
+      result[key] = parseScalar(rest)
+      i++
+    }
+  }
+
+  return result
+}
+
+/** @param {string} s */
+function parseScalar(s) {
+  if (s === 'true') return true
+  if (s === 'false') return false
+  if (s === 'null' || s === '~') return null
+  const n = Number(s)
+  if (!Number.isNaN(n) && s !== '') return n
+  return s.replace(/^["']|["']$/gu, '')
+}

package/scripts/graph/lib/nnn.mjs

@@ -0,0 +1,77 @@
+/**
+ * NNN-лічильники — рахують існуючі файли певного патерну і повертають наступний NNN.
+ * Zero-padded до 3 цифр: 001, 002, …
+ */
+import { readdirSync } from 'node:fs'
+
+/**
+ * @param {string} dir абсолютний шлях до директорії вузла
+ * @param {RegExp} pattern регексп для імен файлів (напр. /^run_(\d{3})\.md$/)
+ * @returns {number} кількість файлів що підходять
+ */
+export function countFiles(dir, pattern) {
+  try {
+    return readdirSync(dir).filter(f => pattern.test(f)).length
+  } catch {
+    return 0
+  }
+}
+
+/**
+ * @param {string} dir
+ * @returns {string} наступний NNN для run_NNN.md (zero-padded)
+ */
+export function nextRunNNN(dir) {
+  const count = countFiles(dir, /^run_\d{3}\.md$/u)
+  return String(count + 1).padStart(3, '0')
+}
+
+/**
+ * @param {string} dir
+ * @returns {string} наступний NNN для plan_NNN.md (zero-padded)
+ */
+export function nextPlanNNN(dir) {
+  const count = countFiles(dir, /^plan_\d{3}\.md$/u)
+  return String(count + 1).padStart(3, '0')
+}
+
+/**
+ * Знаходить NNN останнього fact_NNN.md.
+ * @param {string} dir
+ * @returns {string | null}
+ */
+export function latestFactNNN(dir) {
+  try {
+    const files = readdirSync(dir)
+      .filter(f => /^fact_\d{3}\.md$/u.test(f))
+      .sort()
+    if (files.length === 0) return null
+    return files.at(-1).replace('fact_', '').replace('.md', '')
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Знаходить NNN pending-audit без відповідного audit-result.
+ * @param {string} dir
+ * @returns {string | null}
+ */
+export function pendingAuditNNN(dir) {
+  try {
+    const files = readdirSync(dir)
+    const pending = files.filter(f => /^pending-audit_\d{3}\.md$/u.test(f)).sort()
+    for (const p of pending) {
+      const nnn = p.replace('pending-audit_', '').replace('.md', '')
+      if (!files.includes(`audit-result_${nnn}.md`)) return nnn
+    }
+    return null
+  } catch {
+    return null
+  }
+}
+
+/** @param {number} n @returns {string} */
+export function pad3(n) {
+  return String(n).padStart(3, '0')
+}