@nitra/cursor 3.29.0 → 4.0.0

package/scripts/dispatcher/lib/planner.mjs

@@ -1,73 +0,0 @@
-/**
- * Декларативний планувальник (spec §3 Ф1). Просить субагента видати суворий
- * покроковий JSON-план, парсить і **валідує** його (fail-closed на невалідному).
- * Нормалізує кроки до `{ step, task, status: 'pending', retry_count: 0 }`.
- */
-
-/** Заборонені плейсхолдер-значення `task` (план із ними — не план, fail-closed). */
-const PLACEHOLDER = /^(tbd|todo|fixme|\.\.\.|placeholder)$/i
-
-/**
- * Системно-користувацький промпт планувальника.
- * @param {string} task опис фічі
- * @returns {string} промпт
- */
-export function plannerPrompt(task) {
-  return [
-    'Ти — архітектор. Розбий задачу на суворий покроковий план реалізації.',
-    'Кожен крок — ≤ 5 хв розробки, з чіткими критеріями приймання коду.',
-    'Поверни ЛИШЕ JSON-масив без коментарів: [{ "task": "...", "acceptance": "..." }, ...].',
-    '',
-    `Задача: ${task}`
-  ].join('\n')
-}
-
-/**
- * Парсить і валідує план із тексту відповіді (толерує markdown-огорожу).
- * @param {string} text відповідь субагента
- * @returns {{ step: number, task: string, status: string, retry_count: number, acceptance?: string }[]} нормалізований план
- */
-export function parsePlan(text) {
-  const str = String(text)
-  const start = str.indexOf('[')
-  const end = str.lastIndexOf(']')
-  if (start === -1 || end === -1 || end < start) {
-    throw new Error('planner: не знайдено JSON-масив плану — fail-closed')
-  }
-  let arr
-  try {
-    arr = JSON.parse(str.slice(start, end + 1))
-  } catch {
-    throw new Error('planner: невалідний JSON плану — fail-closed')
-  }
-  if (!Array.isArray(arr) || arr.length === 0) {
-    throw new Error('planner: план має бути непорожнім масивом — fail-closed')
-  }
-  return arr.map((s, i) => {
-    const task = typeof s === 'string' ? s : s?.task
-    if (!task || typeof task !== 'string') {
-      throw new Error(`planner: крок ${i} без текстового поля task — fail-closed`)
-    }
-    const trimmed = task.trim()
-    if (!trimmed || PLACEHOLDER.test(trimmed)) {
-      throw new Error(`planner: крок ${i} — placeholder/порожній task (${task}) — fail-closed`)
-    }
-    const step = { step: i, task, status: 'pending', retry_count: 0 }
-    if (s?.acceptance) step.acceptance = String(s.acceptance)
-    return step
-  })
-}
-
-/**
- * Генерує план через субагента-планувальника.
- * @param {{ runner: { runStep: (prompt: string, opts?: object) => { ok: boolean, output: string } | Promise<{ ok: boolean, output: string }> }, task: string, cwd?: string }} input ін'єкції
- * @returns {Promise<object[]>} нормалізований план
- */
-export async function generatePlan({ runner, task, cwd }) {
-  const res = await runner.runStep(plannerPrompt(task), { cwd })
-  if (!res.ok) {
-    const detail = res.output ? `:\n${res.output}` : ''
-    throw new Error(`planner: субагент-планувальник завершився помилкою${detail}`)
-  }
-  return parsePlan(res.output)
-}

package/scripts/dispatcher/lib/review.mjs

@@ -1,176 +0,0 @@
-/**
- * `flow review` — adversarial-перевірка коду ПІСЛЯ написання (ідея з BMAD
- * quick-dev: self-check → adversarial-review). Незалежний субагент читає ЛИШЕ
- * `git diff base_commit` і шукає логічні баги/ризики, яких не ловлять механічні
- * гейти `verify` (lint+coverage). Findings пишуться у `.flow.json`; команда
- * інформативна (м'які ворота — завжди код 0). Кількість рецензентів — за `level`.
- *
- * Уся IO (`run`/`runner`/`now`) ін'єктується — тестується без git/LLM.
- */
-import { cwd as processCwd } from 'node:process'
-
-import { realRun } from './commands.mjs'
-import { flowEventsPath } from './events.mjs'
-import { reviewersFor } from './level.mjs'
-import { readState, recordTransition } from './state-store.mjs'
-import { resolveActiveFlowState } from './flow-resolve.mjs'
-import { createRunner } from './subagent-runner.mjs'
-
-/** Ліміт diff у промпті (символів) — щоб не роздувати контекст рецензента. */
-const DIFF_LIMIT = 12_000
-
-/**
- * Текст diff від base: `base...HEAD` (закомічене) + `git diff` (робоче дерево).
- * @param {string} base базовий комміт
- * @param {(cmd: string, args: string[], opts: object) => { stdout: string }} run git-runner
- * @param {string} cwd worktree
- * @returns {string} склеєний diff (trim)
- */
-export function diffFromBase(base, run, cwd) {
-  const committed = run('git', ['diff', `${base}...HEAD`], { cwd })
-  const working = run('git', ['diff'], { cwd })
-  return `${committed.stdout ?? ''}\n${working.stdout ?? ''}`.trim()
-}
-
-/**
- * Промпт adversarial-рецензента. Фокус — diff, але рецензент працює у робочій теці
- * репо й має інструмент `Read`, тож cross-file твердження мусить верифікувати читанням.
- * Для high-risk додає безпекову лінзу.
- * @param {string} diff текст diff
- * @param {string} [risk] low|med|high — фокус перевірки
- * @returns {string} промпт
- */
-export function reviewerPrompt(diff, risk) {
-  const lens =
-    risk === 'high'
-      ? "ОСОБЛИВА УВАГА БЕЗПЕЦІ: auth/доступи, секрети/токени, ін'єкції, валідація входу, незворотні операції."
-      : ''
-  return [
-    'Ти — прискіпливий adversarial-рецензент. Знайди баги, ризики й smells, які ВНОСИТЬ або зачіпає цей diff.',
-    'Якщо тобі доступний інструмент Read — ти в робочій теці репо: читай ТОЧКОВО потрібні referenced-файли' +
-      ' (викликану функцію, інший модуль, spec/plan, конфіг), щоб ПЕРЕВІРИТИ cross-file твердження перед репортом.' +
-      ' Якщо Read недоступний — рецензуй лише diff.',
-    'Сусідні файли читай ДЛЯ КОНТЕКСТУ й верифікації, а не щоб шукати в них окремі преіснуючі баги:' +
-      ' репортуй лише те, що вносить/ламає цей diff.',
-    'НЕ видавай нефальсифіковних findings виду «з diff не видно / не показано / можливо» —' +
-      ' або підтверди читанням файлу, або відкинь. Кожен finding має бути перевірним фактом.',
-    lens,
-    'Поверни ЛИШЕ JSON-масив: [{ "severity": "high|med|low", "file": "...", "issue": "...", "suggestion": "..." }].',
-    'Якщо проблем нема — поверни [].',
-    '',
-    'DIFF (фокус рецензування):',
-    diff.slice(0, DIFF_LIMIT)
-  ]
-    .filter(Boolean)
-    .join('\n')
-}
-
-/**
- * Парсить findings із відповіді рецензента. Fail-soft: сміття/невалідний JSON → [].
- * @param {string} text відповідь субагента
- * @returns {{ severity?: string, file?: string, issue?: string, suggestion?: string }[]} findings
- */
-export function parseFindings(text) {
-  const s = String(text)
-  const start = s.indexOf('[')
-  const end = s.lastIndexOf(']')
-  if (start === -1 || end === -1 || end < start) return []
-  try {
-    const arr = JSON.parse(s.slice(start, end + 1))
-    return Array.isArray(arr) ? arr : []
-  } catch {
-    return []
-  }
-}
-
-/**
- * Дедуплікує findings за (file, issue).
- * @param {object[]} findings вхідні
- * @returns {object[]} без дублікатів
- */
-export function dedupeFindings(findings) {
-  const seen = new Set()
-  const out = []
-  for (const f of findings) {
-    const key = `${f?.file ?? ''}::${f?.issue ?? ''}`
-    if (seen.has(key)) continue
-    seen.add(key)
-    out.push(f)
-  }
-  return out
-}
-
-/**
- * Іконка за severity finding-а.
- * @param {string} severity рівень
- * @returns {string} емодзі
- */
-function severityIcon(severity) {
-  if (severity === 'high') return '🔴'
-  if (severity === 'med') return '🟡'
-  return '⚪'
-}
-
-/**
- * `flow review` — спавнить adversarial-рецензента(ів) на diff від base.
- * @param {string[]} _rest аргументи (не використовуються)
- * @param {{ cwd?: string, log?: (m: string) => void, run?: (cmd: string, args: string[], opts: object) => { stdout: string }, runner?: object, now?: () => number }} [deps] ін'єкції
- * @returns {Promise<number>} exit code (0 завжди — інформативна; 1 лише якщо нема стану/runner)
- */
-export async function review(_rest, deps = {}) {
-  const cwd0 = deps.cwd ?? processCwd()
-  const log = deps.log ?? console.error
-  const run = deps.run ?? realRun
-  const now = deps.now ?? Date.now
-
-  const resolved = resolveActiveFlowState({ cwd: cwd0, branch: deps.branch }, deps)
-  if (!resolved.statePath) {
-    log(`review: ${resolved.error}`)
-    return 1
-  }
-  if (resolved.autoResolved) log(`flow: авторезолвлено активний flow «${resolved.label}» (cwd поза worktree)`)
-  const cwd = resolved.worktreeDir ?? cwd0
-  const statePath = resolved.statePath
-  const state = readState(statePath)
-  if (!state) {
-    log('review: стану нема — спершу `flow init`')
-    return 1
-  }
-
-  const base = state.metadata?.base_commit ?? 'HEAD~1'
-  const diff = diffFromBase(base, run, cwd)
-  if (!diff) {
-    log('review: нема змін від base — нічого ревʼювити')
-    return 0
-  }
-
-  let runner = deps.runner
-  if (!runner) {
-    try {
-      runner = await createRunner(deps)
-    } catch (error) {
-      log(`review: ${error.message}`)
-      return 1
-    }
-  }
-
-  const reviewers = reviewersFor(state.level ?? 1, state.risk)
-  const prompt = reviewerPrompt(diff, state.risk)
-  const results = await Promise.all(Array.from({ length: reviewers }, () => runner.runStep(prompt, { cwd })))
-  const findings = dedupeFindings(results.flatMap(r => (r.ok ? parseFindings(r.output) : [])))
-
-  recordTransition(
-    { statePath, eventsPath: flowEventsPath(cwd) },
-    { type: 'review', findings: findings.length },
-    s => ({ ...s, review: { at: new Date(now()).toISOString(), reviewers, findings } }),
-    now
-  )
-
-  for (const f of findings) {
-    log(`${severityIcon(f.severity)} ${f.file ?? '?'}: ${f.issue ?? ''}`)
-  }
-  const high = findings.filter(f => f.severity === 'high').length
-  if (high > 0) log(`⚠️ review: ${high} high-severity — рекомендовано виправити перед release`)
-  log(`review: ${findings.length} findings (рецензентів: ${reviewers})`)
-  return 0
-}

package/scripts/dispatcher/lib/reviewer.mjs

@@ -1,44 +0,0 @@
-/**
- * Level-1 «Суддя» (spec §8.4): проганяє Quality Gates (§5) через **ін'єктований**
- * `run`-runner і повертає структурований verdict. Не знає про LLM/API-ключі —
- * чистий FS/Git/процеси. Один і той самий `runReview` обслуговує і Пасивний
- * Турнікет (`flow verify`), і Активний Раннер (per-step Ф4).
- *
- * Fail-fast: на першому проваленому gate зупиняємось. Fingerprint дерева
- * (`worktree-fingerprint`) фіксуємо лише на повному pass — щоб зберегти у стан і
- * пізніше ловити stale-результат (§5).
- */
-import { worktreeFingerprint } from '../../utils/worktree-fingerprint.mjs'
-
-/**
- * Канонічні gate-и verify (lint + coverage; coverage включає тести+мутації).
- * Обидва — scoped до змінених файлів: `lint` через quick-режим (`changed-files.mjs`),
- * `coverage --changed` через vitest `--changed`/Stryker `--mutate` по diff від base.
- * Турнікет (`flow verify`/per-step) перевіряє лише змінене; повний coverage —
- * окремо (`bun run coverage`, `/n-coverage-fix`).
- */
-export const DEFAULT_GATES = [
-  { name: 'lint', cmd: ['npx', '@nitra/cursor', 'lint'] },
-  { name: 'coverage', cmd: ['npx', '@nitra/cursor', 'coverage', '--changed'] }
-]
-
-/**
- * Проганяє gate-и й повертає verdict.
- * @param {{ run: (cmd: string, args: string[], opts: object) => { status: number, stdout?: string, stderr?: string }, cwd: string, gates?: { name: string, cmd: string[] }[], fingerprint?: () => string | null }} input ін'єкції
- * @returns {{ pass: boolean, gates: { name: string, ok: boolean }[], failedOutput: string | null, fingerprint: string | null }} verdict
- */
-export function runReview({ run, cwd, gates = DEFAULT_GATES, fingerprint = () => worktreeFingerprint() }) {
-  const results = []
-  let failedOutput = null
-  for (const g of gates) {
-    const r = run(g.cmd[0], g.cmd.slice(1), { cwd })
-    const ok = (r?.status ?? 1) === 0
-    results.push({ name: g.name, ok })
-    if (!ok) {
-      failedOutput = `${r?.stdout ?? ''}\n${r?.stderr ?? ''}`.trim() || null
-      break
-    }
-  }
-  const pass = results.length === gates.length && results.every(x => x.ok)
-  return { pass, gates: results, failedOutput, fingerprint: pass ? fingerprint() : null }
-}

package/scripts/dispatcher/lib/snapshot.mjs

@@ -1,58 +0,0 @@
-/**
- * Completion snapshot (spec §3 Ф5, §7): перед cleanup transient `.flow.json`
- * durable-слід задачі має пережити. Будуємо стислий summary і вписуємо його в
- * task record (`docs/tasks/<id>.md`) між HTML-маркерами (idempotent upsert).
- */
-import { existsSync, readFileSync, writeFileSync } from 'node:fs'
-import { isAbsolute } from 'node:path'
-
-const SUMMARY_START = '<!-- flow:summary:start -->'
-const SUMMARY_END = '<!-- flow:summary:end -->'
-
-/**
- * Будує completion snapshot зі стану.
- * @param {object} state стан `.flow.json`
- * @param {() => number} [now] фабрика часу (ms)
- * @returns {object} snapshot (status, branch, base_commit, gates, change, notified, finished_at)
- */
-export function buildCompletionSnapshot(state, now = Date.now) {
-  return {
-    status: state.status ?? 'done',
-    branch: state.branch ?? null,
-    base_commit: state.metadata?.base_commit ?? state.base_commit ?? null,
-    gates: Object.fromEntries((state.gates ?? []).map(g => [g.name, g.ok ? 'ok' : 'fail'])),
-    change: state.change ?? null,
-    notified: state.notified ?? null,
-    finished_at: new Date(now()).toISOString()
-  }
-}
-
-/**
- * Вставляє/оновлює блок Summary в markdown-контенті (між маркерами).
- * @param {string} content вихідний markdown
- * @param {object} snapshot completion snapshot
- * @returns {string} оновлений markdown
- */
-export function upsertSummaryBlock(content, snapshot) {
-  const block = `${SUMMARY_START}\n## Summary\n\`\`\`json\n${JSON.stringify(snapshot, null, 2)}\n\`\`\`\n${SUMMARY_END}`
-  const i = content.indexOf(SUMMARY_START)
-  const j = content.indexOf(SUMMARY_END)
-  if (i !== -1 && j !== -1 && j > i) {
-    return content.slice(0, i) + block + content.slice(j + SUMMARY_END.length)
-  }
-  return `${content.trimEnd()}\n\n${block}\n`
-}
-
-/**
- * Вписує snapshot у task record (створює файл, якщо його нема).
- * @param {string} taskPath абсолютний шлях `docs/tasks/<id>.md`
- * @param {object} snapshot completion snapshot
- * @returns {void}
- */
-export function writeSummaryToTaskRecord(taskPath, snapshot) {
-  if (!isAbsolute(taskPath)) {
-    throw new Error(`writeSummaryToTaskRecord: очікується абсолютний шлях (отримано: ${taskPath})`)
-  }
-  const content = existsSync(taskPath) ? readFileSync(taskPath, 'utf8') : ''
-  writeFileSync(taskPath, upsertSummaryBlock(content, snapshot), 'utf8')
-}

package/scripts/dispatcher/lib/spec.mjs

@@ -1,97 +0,0 @@
-/**
- * `flow spec [--panel] [<spec.md>]` — фаза дизайну (Пасивний Турнікет, lifecycle
- * §3). Фіксує `docs/specs/<date>-<slug>.md` (дизайн із brainstorm) у стані й
- * верифікує ланцюг через read-only `trace`. Код не пише; лінки front-matter
- * пише агент за контрактом `flow.mdc`.
- *
- * Brainstorm: human↔agent — у діалозі IDE-агента (контракт); agent↔agent —
- * `--panel` (панель персон → суддя, синтез презентується людині).
- */
-import { existsSync, readFileSync } from 'node:fs'
-import { cwd as processCwd } from 'node:process'
-
-import { resolveArtifact, verifyTrace } from './artifact.mjs'
-import { flowEventsPath } from './events.mjs'
-import { runPanel } from './plan-panel.mjs'
-import { createRunner } from './subagent-runner.mjs'
-import { readState, recordTransition } from './state-store.mjs'
-import { resolveActiveFlowState } from './flow-resolve.mjs'
-import { parseFrontMatter } from '../trace.mjs'
-
-/** Допустимі значення ризику у spec-frontmatter. */
-const RISKS = new Set(['low', 'med', 'high'])
-
-/**
- * Зчитує `risk` зі spec-frontmatter, якщо валідний (інакше — поточний у стані).
- * Так risk-нотатка у spec керує глибиною подальшого `flow review`.
- * @param {string} doc шлях spec-doc
- * @param {string | undefined} current поточний risk у стані
- * @returns {string | undefined} ризик
- */
-function riskFromSpec(doc, current) {
-  try {
-    const fm = parseFrontMatter(readFileSync(doc, 'utf8'))
-    return fm && RISKS.has(fm.risk) ? fm.risk : current
-  } catch {
-    return current
-  }
-}
-
-/**
- * @param {string[]} rest аргументи (`--panel`, опц. `<spec.md>`)
- * @param {{ cwd?: string, log?: (m: string) => void, runner?: object, trace?: (cwd: string) => number, now?: () => number }} [deps] ін'єкції
- * @returns {Promise<number>} exit code (0 ok, 1 нема стану/доку)
- */
-export async function spec(rest, deps = {}) {
-  const cwd0 = deps.cwd ?? processCwd()
-  const log = deps.log ?? console.error
-  const resolved = resolveActiveFlowState({ cwd: cwd0, branch: deps.branch }, deps)
-  if (!resolved.statePath) {
-    log(`spec: ${resolved.error}`)
-    return 1
-  }
-  if (resolved.autoResolved) log(`flow: авторезолвлено активний flow «${resolved.label}» (cwd поза worktree)`)
-  const cwd = resolved.worktreeDir ?? cwd0
-  const statePath = resolved.statePath
-  const state = readState(statePath)
-  if (!state) {
-    log('spec: стану нема — спершу `flow init`')
-    return 1
-  }
-
-  if (rest.includes('--panel')) {
-    let runner = deps.runner
-    if (!runner) {
-      try {
-        runner = await createRunner(deps)
-      } catch (error) {
-        log(`spec: ${error.message}`)
-        return 1
-      }
-    }
-    const synth = await runPanel({ task: state.branch, cwd, runner, log, mode: 'spec' })
-    if (synth) {
-      log('spec: панель синтезувала підходи (нижче) — збережи дизайн у docs/specs/ і повтори `flow spec`:')
-      log(typeof synth === 'string' ? synth : JSON.stringify(synth))
-    }
-  }
-
-  const doc = rest.find(a => a.endsWith('.md')) ?? resolveArtifact(cwd, 'specs', state.branch)
-  if (!doc || !existsSync(doc)) {
-    log('spec: нема docs/specs/<date>-<slug>.md — спершу пройди brainstorm (див. flow.mdc)')
-    return 1
-  }
-  if (!verifyTrace(cwd, deps.trace)) {
-    log('⚠️ spec: trace виявив розрив ланцюга — перевір лінки front-matter (adr/spec/plan)')
-  }
-
-  const risk = riskFromSpec(doc, state.risk)
-  recordTransition(
-    { statePath, eventsPath: flowEventsPath(cwd) },
-    { type: 'spec' },
-    s => ({ ...s, spec_doc: doc, risk, status: 'spec' }),
-    deps.now ?? Date.now
-  )
-  log(`spec: зафіксовано ${doc} → status: spec (risk ${risk ?? '—'})`)
-  return 0
-}