@nitra/cursor 3.3.0 → 3.4.1

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## [3.4.1] - 2026-06-01
+
+### Fixed
+
+- worktree add: перевіряє зайнятість назви й автоматично обирає вільну (base, base2, base3, …) замість падіння на 'a branch named … already exists'
+
+## [3.4.0] - 2026-06-01
+
+### Added
+
+- flow: команда review (adversarial diff-review за рівнем) + scale-adaptive level в init (L0–L3, керує глибиною review)
+
 ## [3.3.0] - 2026-06-01
 
 ### Added

package/package.json

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

package/rules/flow/flow.mdc

@@ -20,7 +20,10 @@ Composer, Claude Code) працює **Пасивний Турнікет**: ти,
    ```
 
    Створює ізольований worktree (`.worktrees/<branch>/`) і стан задачі. Якщо ти
-   вже в worktree — новий не вкладається.
+   вже в worktree — новий не вкладається. `init` визначає **рівень** задачі
+   (L0 тривіальне … L3 архітектурне) за описом: для L0 (fix/typo/bump) фази
+   Spec/План можна пропустити; для L≥1 вони рекомендовані. Рівень також керує
+   глибиною `review`.
 
 2. **Spec (дизайн)** — рекомендовано, не блокує. Brainstorm нашими термінами
    (НЕ викликаючи superpowers):
@@ -62,10 +65,21 @@ Composer, Claude Code) працює **Пасивний Турнікет**: ти,
    Проганяє Quality Gates (lint + coverage). Повертає `0` (pass) або `1` із
    виводом проваленого gate.
 
-6. **На провал** — виправ код за виводом і виклич `flow verify` знову. Максимум
+6. **Review (adversarial)** — рекомендовано перед release:
+
+   ```
+   npx @nitra/cursor flow review
+   ```
+
+   Незалежний субагент читає ЛИШЕ `git diff` від `base_commit` і шукає логічні
+   баги/ризики, яких не ловлять механічні гейти. Кількість рецензентів — за
+   рівнем (L0→1 … L3→3). Findings пишуться у `.flow.json` (не блокує); high-
+   severity варто виправити перед фінішем.
+
+7. **На провал** — виправ код за виводом і виклич `flow verify` знову. Максимум
    **3 спроби**; якщо не вдається — зупинись і поклич людину.
 
-7. **Фініш** — лише після зеленого `verify`:
+8. **Фініш** — лише після зеленого `verify`:
 
    ```
    npx @nitra/cursor flow release --bump <patch|minor|major> --section <Added|Changed|Fixed> --message "<що зроблено>"

package/scripts/dispatcher/index.mjs

@@ -10,14 +10,16 @@
 import { cancel, repair, resume, run } from './lib/active.mjs'
 import { init, release, verify } from './lib/commands.mjs'
 import { plan } from './lib/plan.mjs'
+import { review } from './lib/review.mjs'
 import { spec } from './lib/spec.mjs'
 
 const USAGE = [
   'Usage:',
-  '  npx @nitra/cursor flow init "<опис>"      # Фасад A: worktree + .flow.json',
+  '  npx @nitra/cursor flow init "<опис>"      # Фасад A: worktree + .flow.json (+ level)',
   '  npx @nitra/cursor flow spec [--panel]     # Фасад A: фаза дизайну → docs/specs/<…>',
   '  npx @nitra/cursor flow plan [--panel]     # Фасад A: фаза плану → docs/plans/<…> + state',
   '  npx @nitra/cursor flow verify             # Фасад A: Quality Gates (pass/fail)',
+  '  npx @nitra/cursor flow review             # Фасад A: adversarial diff-review (за level)',
   '  npx @nitra/cursor flow release            # Фасад A: .changes + completion snapshot',
   '  npx @nitra/cursor flow run "<опис>"       # Фасад B: повний 5-фазний цикл',
   '  npx @nitra/cursor flow resume             # продовжити з чекпойнта',
@@ -26,13 +28,13 @@ const USAGE = [
 ].join('\n')
 
 /** Підкоманди flow. */
-export const SUBCOMMANDS = ['init', 'spec', 'plan', 'verify', 'release', 'run', 'resume', 'cancel', 'repair']
+export const SUBCOMMANDS = ['init', 'spec', 'plan', 'verify', 'review', 'release', 'run', 'resume', 'cancel', 'repair']
 
 /**
  * Усі handler-и реальні (Ф1 Spec/Plan + Ф2 Турнікет + Ф4 Активний Раннер).
  * @type {Record<string, (rest: string[], deps: object) => Promise<number>>}
  */
-export const DEFAULT_HANDLERS = { init, spec, plan, verify, release, run, resume, cancel, repair }
+export const DEFAULT_HANDLERS = { init, spec, plan, verify, review, release, run, resume, cancel, repair }
 
 /**
  * Точка входу `case 'flow'` у `bin/n-cursor.js`. Парсить підкоманду й

package/scripts/dispatcher/lib/commands.mjs

@@ -12,6 +12,7 @@ import { cwd as processCwd } from 'node:process'
 import { worktreePaths } from '../../lib/worktree.mjs'
 import { worktreeFingerprint } from '../../utils/worktree-fingerprint.mjs'
 import { flowEventsPath } from './events.mjs'
+import { detectLevel } from './level.mjs'
 import { runReview } from './reviewer.mjs'
 import { buildCompletionSnapshot, writeSummaryToTaskRecord } from './snapshot.mjs'
 import { flowStatePath, readState, recordTransition, writeState } from './state-store.mjs'
@@ -101,14 +102,16 @@ export async function init(rest, deps = {}) {
   const now = deps.now ?? Date.now
   const log = deps.log ?? console.error
   const statePath = flowStatePath(ew.worktreeDir)
+  const level = detectLevel(ew.desc)
   writeState(statePath, {
     branch: ew.branch,
     status: 'in_progress',
     started_at: new Date(now()).toISOString(),
     metadata: { base_commit: ew.baseCommit },
+    level,
     plan: []
   })
-  log(`init: ${ew.branch} → ${statePath}`)
+  log(`init: ${ew.branch} (level ${level}) → ${statePath}`)
   return 0
 }
 

package/scripts/dispatcher/lib/level.mjs

@@ -0,0 +1,41 @@
+/**
+ * Scale-adaptive рівень задачі (ідея з BMAD project-levels, у наших термінах).
+ * `init` визначає рівень за описом; рівень right-size'ить, скільки adversarial-
+ * рецензентів спавнить `flow review`, і які фази рекомендовані (контракт).
+ *
+ * Детекція — підрядками (case-insensitive), без regex (уникаємо slow-regex і
+ * проблем зі словомежами для кирилиці).
+ */
+
+/** L3 — велике/архітектурне. */
+const L3_KEYS = ['platform', 'migration', 'rewrite', 'architecture', 'enterprise', 'редизайн', 'міграц', 'переписат']
+/** L0 — тривіальне. */
+const L0_KEYS = ['fix', 'typo', 'bump', 'rename', 'hotfix', 'опечат', 'перейменув']
+/** L2 — багатофайлова фіча/рефактор. */
+const L2_KEYS = ['feature', 'epic', 'refactor', 'рефактор', 'фіча']
+
+/**
+ * Рівень складності задачі за описом: 0 (тривіальне) … 3 (архітектурне).
+ * Пріоритет: L3 > L0 > L2 > дефолт L1.
+ * @param {string} desc опис задачі
+ * @returns {0 | 1 | 2 | 3} рівень
+ */
+export function detectLevel(desc) {
+  const d = String(desc ?? '').toLowerCase()
+  const has = keys => keys.some(k => d.includes(k))
+  if (has(L3_KEYS)) return 3
+  if (has(L0_KEYS)) return 0
+  if (has(L2_KEYS)) return 2
+  return 1
+}
+
+/**
+ * Скільки adversarial-рецензентів спавнити для рівня (глибина review за ризиком).
+ * @param {number} level рівень 0..3
+ * @returns {number} кількість рецензентів (1..3)
+ */
+export function reviewersForLevel(level) {
+  if (level >= 3) return 3
+  if (level === 2) return 2
+  return 1
+}

package/scripts/dispatcher/lib/review.mjs

@@ -0,0 +1,150 @@
+/**
+ * `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 { reviewersForLevel } from './level.mjs'
+import { flowStatePath, readState, recordTransition } from './state-store.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).
+ * @param {string} diff текст diff
+ * @returns {string} промпт
+ */
+export function reviewerPrompt(diff) {
+  return [
+    'Ти — прискіпливий adversarial-рецензент. Знайди баги, ризики й smells ЛИШЕ в цьому diff.',
+    'Поверни ЛИШЕ JSON-масив: [{ "severity": "high|med|low", "file": "...", "issue": "...", "suggestion": "..." }].',
+    'Якщо проблем нема — поверни [].',
+    '',
+    diff.slice(0, DIFF_LIMIT)
+  ].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 cwd = deps.cwd ?? processCwd()
+  const log = deps.log ?? console.error
+  const run = deps.run ?? realRun
+  const now = deps.now ?? Date.now
+
+  const statePath = flowStatePath(cwd)
+  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 = reviewersForLevel(state.level ?? 1)
+  const prompt = reviewerPrompt(diff)
+  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/lib/worktree.mjs

@@ -24,13 +24,39 @@ export function sanitizeBranch(branch) {
   if (typeof branch !== 'string' || branch.trim() === '') {
     throw new Error('worktree: імʼя гілки обовʼязкове')
   }
-  const sanitized = branch.trim().replace(UNSAFE_PATH_CHARS_RE, '-').replace(/^-+|-+$/gu, '')
+  const sanitized = branch
+    .trim()
+    .replace(UNSAFE_PATH_CHARS_RE, '-')
+    .replace(/^-+|-+$/gu, '')
   if (sanitized === '') {
     throw new Error(`worktree: імʼя гілки "${branch}" не містить допустимих символів`)
   }
   return sanitized
 }
 
+/**
+ * Перша вільна назва гілки за конвенцією `base`, `base2`, `base3`, … —
+ * суфікс просто число без розділювача (як `main-fix` → `main-fix2`).
+ * Дає змогу `worktree add` спершу перевірити зайнятість і обрати назву,
+ * що спрацює, замість падіння на `fatal: a branch named '…' already exists`.
+ * @param {string} branch бажане імʼя гілки
+ * @param {(candidate: string) => boolean} isTaken чи зайнята назва (гілка/worktree вже існують)
+ * @param {number} [limit] стеля кількості спроб (захист від нескінченного циклу)
+ * @returns {string} перша вільна назва (= `branch`, якщо вона вільна)
+ */
+export function firstFreeBranch(branch, isTaken, limit = 1000) {
+  if (typeof branch !== 'string' || branch.trim() === '') {
+    throw new Error('worktree: імʼя гілки обовʼязкове')
+  }
+  const base = branch.trim()
+  if (!isTaken(base)) return base
+  for (let n = 2; n <= limit; n++) {
+    const candidate = `${base}${n}`
+    if (!isTaken(candidate)) return candidate
+  }
+  throw new Error(`worktree: не знайдено вільної назви для "${base}" за ${limit} спроб`)
+}
+
 /**
  * Детерміновані шляхи checkout і файла-опису для гілки.
  * @param {string} repoRoot абсолютний корінь репозиторію

package/scripts/worktree-cli.mjs

@@ -16,7 +16,7 @@ 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'
+import { buildDescription, findOrphanDescFiles, firstFreeBranch, worktreePaths } from './lib/worktree.mjs'
 
 const USAGE = [
   'Usage:',
@@ -89,20 +89,34 @@ function cmdAdd(rest, ctx) {
     ctx.logError('worktree add: опис обовʼязковий — `worktree add <branch> "<опис>"`')
     return 1
   }
+  // Зайнята, якщо вже є git-гілка з такою назвою або checkout-каталог `.worktrees/<sanit>`.
+  const isTaken = name => {
+    if (git(['show-ref', '--verify', '--quiet', `refs/heads/${name}`], ctx.cwd).status === 0) return true
+    try {
+      return existsSync(worktreePaths(ctx.cwd, name).checkout)
+    } catch {
+      return false // невалідна для шляху назва — впаде нижче на worktreePaths(chosen) з людинозрозумілим текстом
+    }
+  }
+  let chosen
   let paths
   try {
-    paths = worktreePaths(ctx.cwd, branch)
+    chosen = firstFreeBranch(branch, isTaken)
+    paths = worktreePaths(ctx.cwd, chosen)
   } catch (error) {
     ctx.logError(error.message)
     return 1
   }
-  const added = git(['worktree', 'add', paths.checkout, '-b', branch], ctx.cwd)
+  if (chosen !== branch) {
+    ctx.log(`ℹ️  гілка/worktree "${branch}" уже існує — обрано вільну назву "${chosen}"`)
+  }
+  const added = git(['worktree', 'add', paths.checkout, '-b', chosen], ctx.cwd)
   if (added.status !== 0) {
     ctx.logError(`worktree add не вдався: ${added.stderr.trim()}`)
     return 1
   }
   const baseCommit = git(['rev-parse', '--short', 'HEAD'], ctx.cwd).stdout.trim()
-  const md = buildDescription({ branch, task, baseCommit, date: today(ctx.now) })
+  const md = buildDescription({ branch: chosen, task, baseCommit, date: today(ctx.now) })
   writeFileSync(paths.descFile, md, 'utf8')
   ctx.log(`✅ worktree: ${paths.checkout}`)
   ctx.log(`   опис:    ${paths.descFile}`)