@nitra/cursor 3.28.0 → 4.0.0

package/scripts/dispatcher/lib/flow-signals.mjs

@@ -0,0 +1,235 @@
+/**
+ * Handlers сигнальних команд `flow done/audit/failed/spawn` (думка.MD).
+ *
+ * Агент ніколи не знає свій абсолютний path — команди обчислюють path вузла з
+ * env var `NCURSOR_NODE_PATH` (встановлюється wrapper-скриптом) або з файлу
+ * `.n-cursor/current-node` у корені worktree. Якщо нічого — error.
+ *
+ * done    → делегує `n-cursor graph done <path>`
+ * audit   → створює `pending-audit_NNN.md` → делегує `n-cursor graph audit <path>`
+ * failed  → делегує `n-cursor graph failed <path>`
+ * spawn   → делегує `n-cursor graph spawn <path>`
+ *
+ * Всі IO ін'єктуються для тестування без реальних процесів і диска.
+ */
+import { spawnSync } from 'node:child_process'
+import { existsSync, readdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { cwd as processCwd } from 'node:process'
+
+/**
+ * Резолвить шлях вузла з env або fallback-файлу.
+ * @param {{
+ *   env?: Record<string, string | undefined>,
+ *   cwd?: string,
+ *   readFile?: (p: string, enc: string) => string,
+ *   exists?: (p: string) => boolean
+ * }} deps ін'єкції
+ * @returns {{ nodePath: string | null, error: string | null }} результат
+ */
+export function resolveNodePath(deps = {}) {
+  const env = deps.env ?? process.env
+  const cwd = deps.cwd ?? processCwd()
+  const exists = deps.exists ?? existsSync
+  const readFile = deps.readFile ?? ((p, enc) => readFileSync(p, enc))
+
+  // 1. Env var
+  const fromEnv = env['NCURSOR_NODE_PATH']
+  if (fromEnv && fromEnv.trim().length > 0) {
+    return { nodePath: fromEnv.trim(), error: null }
+  }
+
+  // 2. Fallback-файл .n-cursor/current-node у CWD (корінь worktree)
+  const fallbackPath = join(cwd, '.n-cursor', 'current-node')
+  if (exists(fallbackPath)) {
+    try {
+      const content = readFile(fallbackPath, 'utf8').trim()
+      if (content.length > 0) {
+        return { nodePath: content, error: null }
+      }
+    } catch {
+      // якщо не читається — fallthrough до error
+    }
+  }
+
+  return { nodePath: null, error: 'NCURSOR_NODE_PATH not set and .n-cursor/current-node not found' }
+}
+
+/**
+ * Знаходить поточний найбільший номер `outputs_NNN.md`.
+ * @param {string} dir директорія вузла
+ * @param {(dir: string) => string[]} readdir ін'єктована readdir
+ * @returns {string | null} рядок типу `001` або null якщо не знайдено
+ */
+function findCurrentOutputsNum(dir, readdir) {
+  const files = readdir(dir)
+  let max = -1
+  for (const f of files) {
+    const m = f.match(/^outputs_(\d+)\.md$/)
+    if (m) {
+      const n = parseInt(m[1], 10)
+      if (n > max) max = n
+    }
+  }
+  return max >= 0 ? String(max).padStart(3, '0') : null
+}
+
+/**
+ * Виконує n-cursor graph <sub> <nodePath>.
+ * @param {string} sub підкоманда graph
+ * @param {string} nodePath шлях вузла
+ * @param {{
+ *   run: (cmd: string, args: string[]) => { status: number, stdout: string, stderr: string }
+ * }} deps
+ * @returns {number} exit code
+ */
+function delegateToGraph(sub, nodePath, deps) {
+  const result = deps.run('npx', ['@nitra/cursor', 'graph', sub, nodePath])
+  return result.status ?? 1
+}
+
+/**
+ * Реальний sync-runner процесу.
+ * @param {string} cmd
+ * @param {string[]} args
+ * @returns {{ status: number, stdout: string, stderr: string }}
+ */
+function realRun(cmd, args) {
+  const r = spawnSync(cmd, args, { encoding: 'utf8' })
+  return { status: r.status ?? 1, stdout: r.stdout ?? '', stderr: r.stderr ?? '' }
+}
+
+/**
+ * Базовий handler для сигнальних команд без аудиту.
+ * @param {string} sub підкоманда graph
+ * @param {{
+ *   cwd?: string,
+ *   env?: Record<string, string | undefined>,
+ *   log?: (m: string) => void,
+ *   run?: (cmd: string, args: string[]) => { status: number, stdout: string, stderr: string },
+ *   readFile?: (p: string, enc: string) => string,
+ *   exists?: (p: string) => boolean
+ * }} deps ін'єкції
+ * @returns {Promise<number>} exit code
+ */
+async function signalHandler(sub, deps = {}) {
+  const cwd = deps.cwd ?? processCwd()
+  const log = deps.log ?? console.error
+  const run = deps.run ?? realRun
+
+  const { nodePath, error } = resolveNodePath({ env: deps.env, cwd, readFile: deps.readFile, exists: deps.exists })
+  if (!nodePath) {
+    log(`flow ${sub}: ${error}`)
+    return 1
+  }
+
+  log(`flow ${sub}: node path = ${nodePath}`)
+  const code = delegateToGraph(sub, nodePath, { run })
+  if (code !== 0) {
+    log(`flow ${sub}: graph ${sub} завершився з кодом ${code}`)
+  }
+  return code
+}
+
+/**
+ * `flow done` — сигналізує успіх → `graph done <path>`.
+ * @param {string[]} _rest аргументи (не використовуються)
+ * @param {object} [deps] ін'єкції
+ * @returns {Promise<number>} exit code
+ */
+export async function done(_rest, deps = {}) {
+  return signalHandler('done', deps)
+}
+
+/**
+ * `flow failed` — сигналізує провал → `graph failed <path>`.
+ * @param {string[]} _rest аргументи (не використовуються)
+ * @param {object} [deps] ін'єкції
+ * @returns {Promise<number>} exit code
+ */
+export async function failed(_rest, deps = {}) {
+  return signalHandler('failed', deps)
+}
+
+/**
+ * `flow spawn` — сигналізує розклад → `graph spawn <path>`.
+ * @param {string[]} _rest аргументи (не використовуються)
+ * @param {object} [deps] ін'єкції
+ * @returns {Promise<number>} exit code
+ */
+export async function spawn(_rest, deps = {}) {
+  return signalHandler('spawn', deps)
+}
+
+/**
+ * `flow audit` — створює `pending-audit_NNN.md` → `graph audit <path>`.
+ *
+ * NNN у `pending-audit_NNN.md` = NNN відповідного `outputs_NNN.md`.
+ * Якщо outputs відсутні — error.
+ *
+ * @param {string[]} _rest аргументи (не використовуються)
+ * @param {{
+ *   cwd?: string,
+ *   env?: Record<string, string | undefined>,
+ *   log?: (m: string) => void,
+ *   run?: (cmd: string, args: string[]) => { status: number, stdout: string, stderr: string },
+ *   readFile?: (p: string, enc: string) => string,
+ *   writeFile?: (p: string, content: string, enc: string) => void,
+ *   readdir?: (dir: string) => string[],
+ *   exists?: (p: string) => boolean,
+ *   now?: () => string
+ * }} [deps] ін'єкції
+ * @returns {Promise<number>} exit code
+ */
+export async function audit(_rest, deps = {}) {
+  const cwd = deps.cwd ?? processCwd()
+  const log = deps.log ?? console.error
+  const readdir = deps.readdir ?? (d => (existsSync(d) ? readdirSync(d) : []))
+  const writeFile = deps.writeFile ?? ((p, c, enc) => writeFileSync(p, c, enc))
+  const exists = deps.exists ?? existsSync
+  const nowFn = deps.now ?? (() => new Date().toISOString())
+  const run = deps.run ?? realRun
+
+  const { nodePath, error } = resolveNodePath({ env: deps.env, cwd, readFile: deps.readFile, exists })
+  if (!nodePath) {
+    log(`flow audit: ${error}`)
+    return 1
+  }
+
+  // Знаходимо поточний outputs NNN
+  const outputsNum = findCurrentOutputsNum(cwd, readdir)
+  if (!outputsNum) {
+    log('flow audit: outputs_NNN.md не знайдено — спершу напиши outputs')
+    return 1
+  }
+
+  const pendingPath = join(cwd, `pending-audit_${outputsNum}.md`)
+  if (exists(pendingPath)) {
+    log(`flow audit: ${pendingPath} вже існує — audit вже запитано для outputs_${outputsNum}.md`)
+    return 1
+  }
+
+  const content = [
+    '---',
+    `created_at: ${nowFn()}`,
+    `outputs_ref: outputs_${outputsNum}.md`,
+    `actor: agent`,
+    '---',
+    ''
+  ].join('\n')
+
+  try {
+    writeFile(pendingPath, content, 'utf8')
+  } catch (err) {
+    log(`flow audit: не вдалося записати ${pendingPath} — ${err instanceof Error ? err.message : String(err)}`)
+    return 1
+  }
+
+  log(`flow audit: ${pendingPath} створено`)
+  log(`flow audit: node path = ${nodePath}`)
+  const code = delegateToGraph('audit', nodePath, { run })
+  if (code !== 0) {
+    log(`flow audit: graph audit завершився з кодом ${code}`)
+  }
+  return code
+}

package/scripts/dispatcher/lib/flow-verify.mjs

@@ -0,0 +1,127 @@
+/**
+ * Handler `flow verify` — Stage 2 structural check (думка.MD § "flow verify").
+ *
+ * Перевіряє що `outputs_NNN.md` існує і непорожній у директорії поточного вузла
+ * (CWD). Якщо так — виводить `## Done when` секцію з `task.md` та вміст
+ * `outputs_NNN.md` на stdout для агентської self-evaluation.
+ *
+ * exit 0 = структурно OK
+ * exit 1 = структурна помилка (outputs відсутній або порожній)
+ *
+ * НІЯКОГО артефакту не пишеться. FS ін'єктується для тестування без диска.
+ */
+import { existsSync, readdirSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { cwd as processCwd } from 'node:process'
+
+const FRONT_MATTER_RE = /^---\r?\n([\s\S]*?)\r?\n---/
+const SECTION_RE = /^## (.+)$/m
+
+/**
+ * Читає секцію за заголовком із markdown-файлу.
+ * Повертає вміст від заголовка до наступного `## ` або кінця файлу.
+ * @param {string} text вміст файлу
+ * @param {string} heading заголовок без `## `
+ * @returns {string | null} вміст секції (включно з рядком заголовка) або null
+ */
+function extractSection(text, heading) {
+  const lines = text.split(/\r?\n/)
+  const start = lines.findIndex(l => l === `## ${heading}`)
+  if (start === -1) return null
+  const end = lines.findIndex((l, i) => i > start && SECTION_RE.test(l))
+  const section = end === -1 ? lines.slice(start) : lines.slice(start, end)
+  return section.join('\n').trimEnd()
+}
+
+/**
+ * Знаходить outputs-файл з найбільшим NNN у директорії вузла.
+ * @param {string[]} files список файлів директорії
+ * @returns {string | null} ім'я файлу (напр. `outputs_001.md`) або null
+ */
+export function findLatestOutputs(files) {
+  let max = -1
+  let best = null
+  for (const f of files) {
+    const m = f.match(/^outputs_(\d+)\.md$/)
+    if (m) {
+      const n = parseInt(m[1], 10)
+      if (n > max) {
+        max = n
+        best = f
+      }
+    }
+  }
+  return best
+}
+
+/**
+ * `flow verify` handler.
+ *
+ * @param {string[]} _rest аргументи після `verify` (не використовуються)
+ * @param {{
+ *   cwd?: string,
+ *   log?: (m: string) => void,
+ *   readFile?: (path: string, enc: string) => string,
+ *   readdir?: (dir: string) => string[],
+ *   exists?: (path: string) => boolean
+ * }} [deps] ін'єкції
+ * @returns {Promise<number>} exit code (0=OK, 1=структурна помилка)
+ */
+export async function verify(_rest, deps = {}) {
+  const cwd = deps.cwd ?? processCwd()
+  const log = deps.log ?? console.error
+  const readFile = deps.readFile ?? ((p, enc) => readFileSync(p, enc))
+  const readdir = deps.readdir ?? (d => (existsSync(d) ? readdirSync(d) : []))
+  const exists = deps.exists ?? existsSync
+
+  // Перевіряємо outputs_NNN.md
+  const files = readdir(cwd)
+  const outputsName = findLatestOutputs(files)
+  if (!outputsName) {
+    log('flow verify: outputs_NNN.md не знайдено — структурна помилка')
+    return 1
+  }
+
+  const outputsPath = join(cwd, outputsName)
+  if (!exists(outputsPath)) {
+    log(`flow verify: ${outputsName} не існує — структурна помилка`)
+    return 1
+  }
+
+  let outputsContent
+  try {
+    outputsContent = readFile(outputsPath, 'utf8')
+  } catch (err) {
+    log(`flow verify: не вдалося прочитати ${outputsName} — ${err instanceof Error ? err.message : String(err)}`)
+    return 1
+  }
+
+  // Перевіряємо що файл не порожній (без front-matter — суто тіло)
+  const withoutFm = outputsContent.replace(FRONT_MATTER_RE, '').trim()
+  if (withoutFm.length === 0) {
+    log(`flow verify: ${outputsName} порожній — структурна помилка`)
+    return 1
+  }
+
+  // Виводимо Done when + outputs на stdout для агентської self-evaluation
+  const outLines = [`## verify context`, ``]
+
+  const taskPath = join(cwd, 'task.md')
+  if (exists(taskPath)) {
+    try {
+      const taskContent = readFile(taskPath, 'utf8')
+      const doneWhen = extractSection(taskContent, 'Done when')
+      if (doneWhen) {
+        outLines.push(doneWhen, '')
+      }
+    } catch {
+      // якщо task.md недоступний — не блокуємо verify
+    }
+  }
+
+  outLines.push(`### ${outputsName}`, ``, outputsContent.trimEnd())
+
+  console.log(outLines.join('\n'))
+
+  return 0
+}

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

@@ -1,122 +1,53 @@
 /**
- * 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).
+ * SubagentRunner — спавн субагента через pi (провайдер-нейтрально).
+ * Модель обирається через resolveModel('avg') (каскад local→cloud) або через deps.model.
  *
- * pi.dev для inner-спавну НЕ використовується: у автономному режимі pi.dev —
- * зовнішній драйвер, тож спавн ним внутрішніх субагентів = рекурсія (§9.1).
+ * Контракт runner-а: { backend: 'pi', runStep(prompt, { cwd }) → Promise<{ ok, output }> }.
+ * Усі callers (planner, executor, plan-panel, review, budget) використовують саме цей контракт.
  *
- * Усі probe-залежності (`spawn`/`isInPath`/`canImportSdk`/`query`) ін'єктуються,
- * щоб тестувати без реальних процесів і без SDK.
+ * pi НЕ спавниться рекурсивно коли pi — зовнішній драйвер (§9.1).
+ * У цьому проєкті зовнішній драйвер — Claude Code; pi як субагент — безпечно.
  */
 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.'
+import { resolveModel } from '../../../lib/models.mjs'
 
 /**
- * Чи є бінарник у PATH (через `command -v`).
- * @param {string} name ім'я виконуваного
- * @param {typeof import('node:child_process').spawnSync} [spawn] ін'єкція для тестів
- * @returns {boolean} true, якщо знайдено
+ * Викликає pi і повертає { ok, output }.
+ * @param {string} prompt
+ * @param {string} model  provider/model-id або '' для pi-дефолту
+ * @param {{ cwd?: string }} [opts]
+ * @returns {{ ok: boolean, output: string }}
  */
-export function isBinaryInPath(name, spawn = spawnSync) {
-  const r = spawn('command', ['-v', name], { shell: true, encoding: 'utf8' })
-  return (r.status ?? 1) === 0
+function callPi(prompt, model, { cwd } = {}) {
+  const modelArgs = model ? ['--model', model] : []
+  const r = spawnSync('pi', ['-p', prompt, ...modelArgs, '--no-session'], {
+    cwd,
+    encoding: 'utf8',
+    timeout: 600_000
+  })
+  const ok = !r.error && r.status === 0
+  const output = (r.stdout ?? '') + (r.error ? r.error.message : !ok ? (r.stderr ?? '') : '')
+  return { ok, output }
 }
 
 /**
- * Обирає backend субагентів за пріоритетом sdk > claude > cursor.
- * @param {{ hasApiKey: boolean, canImportSdk: boolean, isInPath: (name: string) => boolean }} probes доступність
- * @returns {'sdk' | 'claude' | 'cursor' | null} backend або null
+ * Створює 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 }> }>}
  */
-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 ?? ''}` }
-    }
-  }
-}
+export async function createRunner(deps = {}) {
+  const model = deps.model ?? resolveModel('avg')
+  const callPiFn = deps.callPi ?? callPi
 
-/**
- * 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
+    backend: 'pi',
+    async runStep(prompt, opts = {}) {
       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 callPiFn(prompt, model, opts)
+      } catch (e) {
+        return { ok: false, output: String(e?.message ?? e) }
       }
-      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/worktree-cli.mjs

@@ -15,7 +15,6 @@ 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,
   buildDirtyNotice,
@@ -161,7 +160,8 @@ 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)
+  // В новій архітектурі (думка.MD) state зберігається у файлах вузлів (task.md, outputs, run),
+  // а не у .flow.json/.events.jsonl/lock sibling-ах. Cleanup sibling-ів більше не потрібен.
   ctx.log(`✅ прибрано: ${paths.checkout} (гілку ${branch} лишено)`)
   return 0
 }