@nitra/cursor 4.1.0 → 4.1.1

package/rules/npm-module/js/header_doc_pointer.mjs

@@ -14,16 +14,27 @@ const MODULE_JSDOC_RE = /\/\*\*[\s\S]*?\*\//
  */
 const CODE_START_RE = /^(?:import|export)\b/m
 
-/** Кількість непорожніх рядків між `/**` і `*\/` (після зрізання `*`-відступу). */
+const NON_WHITESPACE_RE = /\S/
+const STAR_INDENT_RE = /^\s*\*\s?/
+
+/**
+ * Кількість непорожніх рядків між `/**` і `*\/` (після зрізання `*`-відступу).
+ * @param {string} block повний текст JSDoc-блоку з обрамленням
+ * @returns {number} кількість непорожніх рядків у тілі
+ */
 function contentLineCount(block) {
   return block
     .split('\n')
     .slice(1, -1)
-    .filter(l => /\S/.test(l.replace(/^\s*\*\s?/, '')))
+    .filter(l => NON_WHITESPACE_RE.test(l.replace(STAR_INDENT_RE, '')))
     .length
 }
 
-/** Повертає module-level JSDoc або `null`, якщо його немає. */
+/**
+ * Повертає module-level JSDoc або `null`, якщо його немає.
+ * @param {string} source вміст mjs-файлу
+ * @returns {string|null} текст module-level JSDoc-блоку або null
+ */
 function moduleJsDoc(source) {
   const codeStart = CODE_START_RE.exec(source)
   const prefix = codeStart ? source.slice(0, codeStart.index) : source

package/rules/php/docs/fix.md

@@ -58,6 +58,7 @@ export function run(ctx)
 
 ```js
 import { run } from '@nitra/cursor/rules/php/fix.mjs'
+
 const code = await run(sharedCtx)
 ```
 
@@ -81,7 +82,7 @@ const code = await run(sharedCtx)
 У standalone-гілці явно вимкнено два правила лінтера:
 
 ```js
-// eslint-disable-next-line n/no-process-exit, unicorn/no-process-exit -- standalone entry-point має повертати exit-code для CI/IDE
+// eslint-disable-next-line n/no-process-exit -- standalone entry-point має повертати exit-code для CI/IDE
 process.exit(await runRuleCli(import.meta.dirname))
 ```
 

package/rules/php/fix.mjs

@@ -14,6 +14,6 @@ export function run(ctx) {
 if (isRunAsCli(import.meta.url)) {
   // Standalone: bun rules/<id>/fix.mjs — повний еквівалент `npx @nitra/cursor fix <id>`
   // (config-loading + whitelist + summary). Дві ролі fix.mjs: library (run) + standalone (main).
-  // eslint-disable-next-line n/no-process-exit, unicorn/no-process-exit -- standalone entry-point має повертати exit-code для CI/IDE
+  // eslint-disable-next-line n/no-process-exit -- standalone entry-point має повертати exit-code для CI/IDE
   process.exit(await runRuleCli(import.meta.dirname))
 }

package/rules/python/docs/fix.md

@@ -30,6 +30,9 @@ Public-функція правила, делегатор до `runStandardRule`.
 **Сигнатура**
 
 ```js
+/**
+ *
+ */
 export function run(ctx) {
   return runStandardRule(import.meta.dirname, ctx)
 }
@@ -61,7 +64,7 @@ export function run(ctx) {
 
 ```js
 if (isRunAsCli(import.meta.url)) {
-  // eslint-disable-next-line n/no-process-exit, unicorn/no-process-exit
+  // eslint-disable-next-line n/no-process-exit
   process.exit(await runRuleCli(import.meta.dirname))
 }
 ```

package/rules/python/fix.mjs

@@ -14,6 +14,6 @@ export function run(ctx) {
 if (isRunAsCli(import.meta.url)) {
   // Standalone: bun rules/<id>/fix.mjs — повний еквівалент `npx @nitra/cursor fix <id>`
   // (config-loading + whitelist + summary). Дві ролі fix.mjs: library (run) + standalone (main).
-  // eslint-disable-next-line n/no-process-exit, unicorn/no-process-exit -- standalone entry-point має повертати exit-code для CI/IDE
+  // eslint-disable-next-line n/no-process-exit -- standalone entry-point має повертати exit-code для CI/IDE
   process.exit(await runRuleCli(import.meta.dirname))
 }

package/rules/rego/fix.mjs

@@ -14,6 +14,6 @@ export function run(ctx) {
 if (isRunAsCli(import.meta.url)) {
   // Standalone: bun rules/<id>/fix.mjs — повний еквівалент `npx @nitra/cursor fix <id>`
   // (config-loading + whitelist + summary). Дві ролі fix.mjs: library (run) + standalone (main).
-  // eslint-disable-next-line n/no-process-exit, unicorn/no-process-exit -- standalone entry-point має повертати exit-code для CI/IDE
+  // eslint-disable-next-line n/no-process-exit -- standalone entry-point має повертати exit-code для CI/IDE
   process.exit(await runRuleCli(import.meta.dirname))
 }

package/rules/rego/js/lint.mjs

@@ -7,6 +7,6 @@ import { runLintRego } from '../lint/lint.mjs'
  * @param {string[] | undefined} _files ігнорується (whole-repo аналіз)
  * @returns {Promise<number>} exit code
  */
-export async function lint(_files) {
+export function lint(_files) {
   return runLintRego()
 }

package/rules/release/docs/fix.md

@@ -22,6 +22,9 @@
 ### `run(ctx)`
 
 ```js
+/**
+ *
+ */
 export function run(ctx) {
   return runStandardRule(import.meta.dirname, ctx)
 }
@@ -40,7 +43,7 @@ export function run(ctx) {
 
 ```js
 if (isRunAsCli(import.meta.url)) {
-  // eslint-disable-next-line n/no-process-exit, unicorn/no-process-exit -- standalone entry-point має повертати exit-code для CI/IDE
+  // eslint-disable-next-line n/no-process-exit -- standalone entry-point має повертати exit-code для CI/IDE
   process.exit(await runRuleCli(import.meta.dirname))
 }
 ```

package/rules/release/fix.mjs

@@ -12,6 +12,6 @@ export function run(ctx) {
 }
 
 if (isRunAsCli(import.meta.url)) {
-  // eslint-disable-next-line n/no-process-exit, unicorn/no-process-exit -- standalone entry-point має повертати exit-code для CI/IDE
+  // eslint-disable-next-line n/no-process-exit -- standalone entry-point має повертати exit-code для CI/IDE
   process.exit(await runRuleCli(import.meta.dirname))
 }

package/rules/rust/fix.mjs

@@ -14,6 +14,6 @@ export function run(ctx) {
 if (isRunAsCli(import.meta.url)) {
   // Standalone: bun rules/<id>/fix.mjs — повний еквівалент `npx @nitra/cursor fix <id>`
   // (config-loading + whitelist + summary). Дві ролі fix.mjs: library (run) + standalone (main).
-  // eslint-disable-next-line n/no-process-exit, unicorn/no-process-exit -- standalone entry-point має повертати exit-code для CI/IDE
+  // eslint-disable-next-line n/no-process-exit -- standalone entry-point має повертати exit-code для CI/IDE
   process.exit(await runRuleCli(import.meta.dirname))
 }

package/rules/security/docs/fix.md

@@ -74,7 +74,7 @@ export function run(ctx)
 Рядок із `process.exit(await runRuleCli(...))` має локальну директиву:
 
 ```js
-// eslint-disable-next-line n/no-process-exit, unicorn/no-process-exit -- standalone entry-point має повертати exit-code для CI/IDE
+ 
 ```
 
 Це свідома відмова від загальної заборони `process.exit`: для CLI entry-point потрібно повертати числовий код, інакше CI/IDE не зможуть розрізнити OK і порушення. Заборона залишається активною для решти кодової бази.

package/rules/security/fix.mjs

@@ -14,6 +14,6 @@ export function run(ctx) {
 if (isRunAsCli(import.meta.url)) {
   // Standalone: bun rules/<id>/fix.mjs — повний еквівалент `npx @nitra/cursor fix <id>`
   // (config-loading + whitelist + summary). Дві ролі fix.mjs: library (run) + standalone (main).
-  // eslint-disable-next-line n/no-process-exit, unicorn/no-process-exit -- standalone entry-point має повертати exit-code для CI/IDE
+  // eslint-disable-next-line n/no-process-exit -- standalone entry-point має повертати exit-code для CI/IDE
   process.exit(await runRuleCli(import.meta.dirname))
 }

package/rules/style-lint/docs/fix.md

@@ -26,6 +26,9 @@
 ### `run(ctx)`
 
 ```js
+/**
+ *
+ */
 export function run(ctx) {
   return runStandardRule(import.meta.dirname, ctx)
 }

package/rules/style-lint/fix.mjs

@@ -14,6 +14,6 @@ export function run(ctx) {
 if (isRunAsCli(import.meta.url)) {
   // Standalone: bun rules/<id>/fix.mjs — повний еквівалент `npx @nitra/cursor fix <id>`
   // (config-loading + whitelist + summary). Дві ролі fix.mjs: library (run) + standalone (main).
-  // eslint-disable-next-line n/no-process-exit, unicorn/no-process-exit -- standalone entry-point має повертати exit-code для CI/IDE
+  // eslint-disable-next-line n/no-process-exit -- standalone entry-point має повертати exit-code для CI/IDE
   process.exit(await runRuleCli(import.meta.dirname))
 }

package/rules/tauri/docs/fix.md

@@ -33,6 +33,9 @@
 ### `run(ctx)`
 
 ```js
+/**
+ *
+ */
 export function run(ctx) {
   return runStandardRule(import.meta.dirname, ctx)
 }
@@ -57,7 +60,7 @@ export function run(ctx) {
 
 ```js
 if (isRunAsCli(import.meta.url)) {
-  // eslint-disable-next-line n/no-process-exit, unicorn/no-process-exit -- standalone entry-point має повертати exit-code для CI/IDE
+  // eslint-disable-next-line n/no-process-exit -- standalone entry-point має повертати exit-code для CI/IDE
   process.exit(await runRuleCli(import.meta.dirname))
 }
 ```

package/rules/tauri/fix.mjs

@@ -14,6 +14,6 @@ export function run(ctx) {
 if (isRunAsCli(import.meta.url)) {
   // Standalone: bun rules/<id>/fix.mjs — повний еквівалент `npx @nitra/cursor fix <id>`
   // (config-loading + whitelist + summary). Дві ролі fix.mjs: library (run) + standalone (main).
-  // eslint-disable-next-line n/no-process-exit, unicorn/no-process-exit -- standalone entry-point має повертати exit-code для CI/IDE
+  // eslint-disable-next-line n/no-process-exit -- standalone entry-point має повертати exit-code для CI/IDE
   process.exit(await runRuleCli(import.meta.dirname))
 }

package/rules/test/docs/fix.md

@@ -32,6 +32,9 @@
 ### `run(ctx)`
 
 ```js
+/**
+ *
+ */
 export function run(ctx) {
   return runStandardRule(import.meta.dirname, ctx)
 }

package/rules/test/fix.mjs

@@ -14,6 +14,6 @@ export function run(ctx) {
 if (isRunAsCli(import.meta.url)) {
   // Standalone: bun rules/<id>/fix.mjs — повний еквівалент `npx @nitra/cursor fix <id>`
   // (config-loading + whitelist + summary). Дві ролі fix.mjs: library (run) + standalone (main).
-  // eslint-disable-next-line n/no-process-exit, unicorn/no-process-exit -- standalone entry-point має повертати exit-code для CI/IDE
+  // eslint-disable-next-line n/no-process-exit -- standalone entry-point має повертати exit-code для CI/IDE
   process.exit(await runRuleCli(import.meta.dirname))
 }

package/rules/test/js/no-relative-fs-path.mjs

@@ -62,6 +62,7 @@ const FS_PATH_ARG_POSITIONS = new Map([
  * одного з них — це OK (тест свідомо передає absolute чи URL).
  */
 const ABSOLUTE_PREFIXES = ['/', '\\', 'file:', 'http:', 'https:', 'data:']
+const WINDOWS_DRIVE_RE = /^[A-Za-z]:[\\/]/u
 
 /**
  * Чи string literal — relative path (тобто баг). Перевіряє лише string-літерали
@@ -95,7 +96,7 @@ function isRelativeString(s) {
     if (s.startsWith(prefix)) return false
   }
   // Windows drive letter, наприклад `C:\foo` або `C:/foo`.
-  if (/^[A-Za-z]:[\\/]/u.test(s)) return false
+  if (WINDOWS_DRIVE_RE.test(s)) return false
   return true
 }
 

package/rules/text/docs/fix.md

@@ -24,6 +24,9 @@
 ### `run(ctx)`
 
 ```js
+/**
+ *
+ */
 export function run(ctx) {
   return runStandardRule(import.meta.dirname, ctx)
 }

package/rules/text/fix.mjs

@@ -14,6 +14,6 @@ export function run(ctx) {
 if (isRunAsCli(import.meta.url)) {
   // Standalone: bun rules/<id>/fix.mjs — повний еквівалент `npx @nitra/cursor fix <id>`
   // (config-loading + whitelist + summary). Дві ролі fix.mjs: library (run) + standalone (main).
-  // eslint-disable-next-line n/no-process-exit, unicorn/no-process-exit -- standalone entry-point має повертати exit-code для CI/IDE
+  // eslint-disable-next-line n/no-process-exit -- standalone entry-point має повертати exit-code для CI/IDE
   process.exit(await runRuleCli(import.meta.dirname))
 }

package/rules/text/js/lint.mjs

@@ -7,6 +7,6 @@ import { runLintTextCli } from '../lint/lint.mjs'
  * @param {string[] | undefined} _files ігнорується (whole-repo аналіз)
  * @returns {Promise<number>} exit code
  */
-export async function lint(_files) {
+export function lint(_files) {
   return runLintTextCli()
 }

package/rules/vue/fix.mjs

@@ -14,6 +14,6 @@ export function run(ctx) {
 if (isRunAsCli(import.meta.url)) {
   // Standalone: bun rules/<id>/fix.mjs — повний еквівалент `npx @nitra/cursor fix <id>`
   // (config-loading + whitelist + summary). Дві ролі fix.mjs: library (run) + standalone (main).
-  // eslint-disable-next-line n/no-process-exit, unicorn/no-process-exit -- standalone entry-point має повертати exit-code для CI/IDE
+  // eslint-disable-next-line n/no-process-exit -- standalone entry-point має повертати exit-code для CI/IDE
   process.exit(await runRuleCli(import.meta.dirname))
 }

package/rules/worktree/fix.mjs

@@ -14,6 +14,6 @@ export function run(ctx) {
 if (isRunAsCli(import.meta.url)) {
   // Standalone: bun rules/<id>/fix.mjs — повний еквівалент `npx @nitra/cursor fix <id>`
   // (config-loading + whitelist + summary). Дві ролі fix.mjs: library (run) + standalone (main).
-  // eslint-disable-next-line n/no-process-exit, unicorn/no-process-exit -- standalone entry-point має повертати exit-code для CI/IDE
+  // eslint-disable-next-line n/no-process-exit -- standalone entry-point має повертати exit-code для CI/IDE
   process.exit(await runRuleCli(import.meta.dirname))
 }

package/scripts/auto-rules.mjs

@@ -332,7 +332,7 @@ function resolveRuleDependencies(detectedRules, addRule) {
  * @param {{root:string, facts:object, paths:string[], packageJsonParsed:unknown}} ctx контекст
  * @returns {Promise<boolean>} true, якщо правило активне
  */
-async function specMatches(spec, ctx) {
+function specMatches(spec, ctx) {
   if ('always' in spec) return true
   if ('glob' in spec) {
     const res = spec.glob.map(g => globToRegex(g))

package/scripts/coverage-classify/index.mjs

@@ -23,9 +23,9 @@ const FALLBACK_VERDICT = {
 
 /**
  * Викликає pi і повертає raw stdout.
- * @param {string} prompt
+ * @param {string} prompt текст промпта
  * @param {string} model  provider/model-id або '' для pi-дефолту
- * @returns {string}
+ * @returns {string} stdout pi-процесу
  * @throws якщо pi не знайдено або повертає ненульовий exit code
  */
 function callPi(prompt, model) {
@@ -41,11 +41,11 @@ function callPi(prompt, model) {
 
 /**
  * Два тири: LOCAL_MIN → Tier 2 CLOUD_MIN → FALLBACK_VERDICT.
- * @param {{file: string, mutants: object[]}} group
- * @param {object} mutant
- * @param {string} cwd
+ * @param {{file: string, mutants: object[]}} group група мутантів одного файлу
+ * @param {object} mutant конкретний мутант
+ * @param {string} cwd корінь проєкту
  * @param {(prompt: string, model: string) => string} callPiFn  ін'єкція для тестів
- * @returns {object} verdict
+ * @returns {object} verdict класифікації
  */
 function classifyOne(group, mutant, cwd, callPiFn) {
   const prompt = `${SYSTEM_PROMPT}\n\n${buildUserPrompt({ ...mutant, file: group.file }, cwd)}`
@@ -60,8 +60,8 @@ function classifyOne(group, mutant, cwd, callPiFn) {
     try {
       const text = callPiFn(prompt, CLOUD_MIN)
       return parseVerdict(text)
-    } catch (e) {
-      console.warn(`⚠ coverage classify: ${loc} both tiers failed: ${e.message}`)
+    } catch (error) {
+      console.warn(`⚠ coverage classify: ${loc} both tiers failed: ${error.message}`)
       return { ...FALLBACK_VERDICT }
     }
   }
@@ -69,12 +69,12 @@ function classifyOne(group, mutant, cwd, callPiFn) {
 
 /**
  * Класифікує survived мутантів через pi (LOCAL_MIN → CLOUD_MIN → fallback).
- * @param {Array<{file: string, mutants: object[], exampleTest?: object|null, recommendationText?: string|null}>} survived
+ * @param {Array<{file: string, mutants: object[], exampleTest?: object|null, recommendationText?: string|null}>} survived список вцілілих мутантів
  * @param {string} cwd корінь проєкту
  * @param {{cachePath?: string, callPi?: Function}} [opts] ін'єкції для тестів
  * @returns {Promise<Array<{key: string, verdict: object}>>} verdicts
  */
-export async function classify(survived, cwd, opts = {}) {
+export function classify(survived, cwd, opts = {}) {
   const cachePath = opts.cachePath ?? join(cwd, 'npm/reports/coverage-classify.cache.json')
   const callPiFn = opts.callPi ?? callPi
   const cacheModel = `${resolveModel('min') || 'default'}+${CLOUD_MIN || 'cloud'}`

package/scripts/coverage-fix.mjs

@@ -42,9 +42,9 @@ export async function fixSurvivedMutants(survived, projectRoot, opts = {}) {
 
 /**
  * Викликає pi в агентному режимі з live-output до stdout.
- * @param {string} prompt
+ * @param {string} prompt текст промпта
  * @param {string} model  provider/model-id або '' для pi-дефолту
- * @param {{ cwd?: string }} [piOpts]
+ * @param {{ cwd?: string }} [piOpts] опційні параметри (cwd)
  */
 function callPi(prompt, model, { cwd } = {}) {
   const modelArgs = model ? ['--model', model] : []

package/scripts/dispatcher/graph/lib/cmd-init.mjs

@@ -0,0 +1,112 @@
+/**
+ * `n-cursor graph init <name>` — створює task.md шаблон для нового вузла.
+ *
+ * Не потребує LLM. Просто пише task.md з front-matter і порожнім тілом.
+ * Ім'я може містити `/` для вкладених вузлів (напр. "research/collect-data").
+ *
+ * FS ін'єктується для тестованості.
+ */
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { cwd as processCwd } from 'node:process'
+
+import { buildMarkdown } from './frontmatter.mjs'
+import { loadConfig, resolveTasksDir } from './config.mjs'
+
+/**
+ * Будує front-matter для task.md шаблону.
+ * @param {{ now: string, name: string }} params параметри
+ * @returns {Record<string, unknown>} front-matter об'єкт
+ */
+export function buildTaskFrontMatter(params) {
+  return {
+    created_at: params.now,
+    budget_sec: 600,
+    mode: 'human',
+    interactive: true,
+    executor: {
+      type: 'agent',
+      model_tier: 'AVG',
+      skills: ['bash', 'write-files']
+    },
+    hint: 'atomic',
+    deps: []
+  }
+}
+
+/**
+ * `graph init <name>` command handler.
+ * @param {string[]} args аргументи: [name]
+ * @param {{
+ *   cwd?: string,
+ *   log?: (m: string) => void,
+ *   writeFile?: (p: string, c: string, enc: string) => void,
+ *   exists?: (p: string) => boolean,
+ *   mkdir?: (p: string, opts?: object) => void,
+ *   now?: () => string,
+ *   readFile?: (p: string, enc: string) => string
+ * }} [deps] ін'єкції
+ * @returns {Promise<number>} exit code
+ */
+export async function cmdInit(args, deps = {}) {
+  const root = deps.cwd ?? processCwd()
+  const log = deps.log ?? console.log
+  const writeFile = deps.writeFile ?? ((p, c, enc) => writeFileSync(p, c, enc))
+  const exists = deps.exists ?? existsSync
+  const mkdir = deps.mkdir ?? ((p, opts) => mkdirSync(p, opts))
+  const nowFn = deps.now ?? (() => new Date().toISOString())
+
+  const [name] = args
+  if (!name) {
+    log('Usage: n-cursor graph init <name>')
+    log('  name може містити / для вкладених вузлів (напр. "research/collect-data")')
+    return 1
+  }
+
+  const config = loadConfig({ root, readFile: deps.readFile, exists })
+  const tasksDir = resolveTasksDir(config, root)
+
+  const nodeDir = join(tasksDir, name)
+  const taskPath = join(nodeDir, 'task.md')
+
+  if (exists(taskPath)) {
+    log(`init: ${taskPath} вже існує — пропускаємо`)
+    return 0
+  }
+
+  // Створюємо директорію рекурсивно
+  try {
+    mkdir(nodeDir, { recursive: true })
+  } catch (err) {
+    log(`init: не вдалося створити директорію ${nodeDir} — ${err.message ?? String(err)}`)
+    return 1
+  }
+
+  const fm = buildTaskFrontMatter({ now: nowFn(), name })
+  const body = [
+    `## Mission`,
+    ``,
+    `<!-- Опишіть завдання вузла тут -->`,
+    ``,
+    `## Done when`,
+    ``,
+    `<!-- Критерії успіху -->`,
+    ``,
+    `## Context`,
+    ``,
+    `<!-- Додатковий контекст для виконавця -->`,
+    ``
+  ].join('\n')
+
+  const content = buildMarkdown(fm, body)
+
+  try {
+    writeFile(taskPath, content, 'utf8')
+    log(`init: створено ${taskPath}`)
+  } catch (err) {
+    log(`init: не вдалося записати ${taskPath} — ${err.message ?? String(err)}`)
+    return 1
+  }
+
+  return 0
+}

package/scripts/dispatcher/graph/lib/cmd-invalidate.mjs

@@ -0,0 +1,96 @@
+/**
+ * `n-cursor graph invalidate <path> [--no-cascade]` — позначає вузол як invalidated.
+ *
+ * Записує порожній файл `invalidated` у директорію вузла.
+ * За замовчуванням каскадно інвалідує всі залежні вузли.
+ * --no-cascade — лише поточний вузол.
+ *
+ * FS ін'єктується для тестованості.
+ */
+import { execSync } from 'node:child_process'
+import { existsSync, readdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { cwd as processCwd } from 'node:process'
+
+import { loadConfig, resolveTasksDir } from './config.mjs'
+import { scanNodes } from './scanner.mjs'
+import { listActiveWorktrees } from './worktree-ops.mjs'
+
+/**
+ * `graph invalidate <path> [--no-cascade]` command handler.
+ * @param {string[]} args аргументи
+ * @param {{
+ *   cwd?: string,
+ *   log?: (m: string) => void,
+ *   readFile?: (p: string, enc: string) => string,
+ *   writeFile?: (p: string, c: string, enc: string) => void,
+ *   readdir?: (d: string) => string[],
+ *   exists?: (p: string) => boolean,
+ *   execSync?: (cmd: string, opts?: object) => string
+ * }} [deps] ін'єкції
+ * @returns {Promise<number>} exit code
+ */
+export async function cmdInvalidate(args, deps = {}) {
+  const root = deps.cwd ?? processCwd()
+  const log = deps.log ?? console.log
+  const readFile = deps.readFile ?? ((p, enc) => readFileSync(p, enc))
+  const writeFile = deps.writeFile ?? ((p, c, enc) => writeFileSync(p, c, enc))
+  const readdir = deps.readdir ?? (d => (existsSync(d) ? readdirSync(d) : []))
+  const exists = deps.exists ?? existsSync
+  const execSyncFn = deps.execSync ?? ((cmd, o) => execSync(cmd, { ...o, encoding: 'utf8' }))
+
+  let nodePath = null
+  let noCascade = false
+
+  for (const arg of args) {
+    if (arg === '--no-cascade') noCascade = true
+    else if (!arg.startsWith('-')) nodePath = arg
+  }
+
+  if (!nodePath) {
+    log('Usage: n-cursor graph invalidate <path> [--no-cascade]')
+    return 1
+  }
+
+  const config = loadConfig({ root, readFile, exists })
+  const tasksDir = resolveTasksDir(config, root)
+  const nodeDir = join(tasksDir, nodePath)
+
+  if (!exists(join(nodeDir, 'task.md'))) {
+    log(`invalidate: вузол "${nodePath}" не знайдено`)
+    return 1
+  }
+
+  // Записуємо invalidated sentinel
+  try {
+    writeFile(join(nodeDir, 'invalidated'), '', 'utf8')
+    log(`invalidate: вузол "${nodePath}" інвалідовано`)
+  } catch (err) {
+    log(`invalidate: не вдалося записати invalidated — ${err.message ?? String(err)}`)
+    return 1
+  }
+
+  if (noCascade) return 0
+
+  // Каскадна інвалідація
+  const activeWorktrees = listActiveWorktrees(root, { execSync: execSyncFn })
+  const allNodes = scanNodes(tasksDir, activeWorktrees, {
+    readdirSync: readdir,
+    existsSync: exists,
+    readFileSync: readFile
+  })
+
+  const dependents = allNodes.filter(n => n.deps.includes(nodePath))
+  for (const dep of dependents) {
+    if (!exists(join(dep.dir, 'invalidated'))) {
+      try {
+        writeFile(join(dep.dir, 'invalidated'), '', 'utf8')
+        log(`invalidate: каскадна інвалідація "${dep.path}"`)
+      } catch {
+        // пропускаємо
+      }
+    }
+  }
+
+  return 0
+}