@nitra/cursor 3.27.0 → 3.29.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/docs/coverage-fix-extract.md

@@ -0,0 +1,32 @@
+# coverage-fix-extract.mjs
+
+## Огляд
+
+Цей файл витягує вцілілі мутанти з файлу `COVERAGE.md` у форматі JSON. Витягнуті дані надаються агенту для вирішення проблем з покриттям, зменшуючи навантаження на LLM-оркестратор та забезпечуючи ефективний обмін інформацією. Це ключовий компонент процесу `n-coverage-fix`, що дозволяє агенту швидко реагувати на зміни в покритті.
+
+## Поведінка
+
+parseSurvivedBlock: Витягує JSON-масив вцілілих мутантів із тексту `COVERAGE.md`.
+readSurvived: Читає `COVERAGE.md` із кореня проєкту і повертає групи вцілілих.
+buildIndex: Згортає групи вцілілих у компактний index `[{file, mutants}]`.
+runCoverageFixCli: CLI: `index` друкує компактний JSON-масив, `slice --file <path>` — промпт для одного файлу.
+
+## Публічний API
+
+- parseSurvivedBlock — Витягує дані про вцілілих мутантів з `COVERAGE.md` у форматі JSON.
+- readSurvived — Зчитує `COVERAGE.md` та повертає структуровані дані про вцілілих.
+- buildIndex — Створює компактний індекс у форматі JSON, що містить інформацію про файли та мутанти.
+- runCoverageFixCli — CLI для друку та обрізки даних з `COVERAGE.md`.
+
+## Гарантії поведінки
+
+- Скрипт парсить файл `COVERAGE.md`.
+- Результатом парсингу є об'єкт з інформацією про вцілілі мутанти.
+- Скрипт повертає об'єкт, якщо файл `COVERAGE.md` існує та може бути успішно прочитаний.
+- Якщо файл `COVERAGE.md` не існує, скрипт повертає порожній об'єкт.
+- Скрипт не змінює вміст файлу `COVERAGE.md`.
+- Скрипт не запускає Stryker.
+- Скрипт не генерує винятків.
+- Скрипт не використовує кешування.
+- Використання команди `index` повертає мінімальний об'єкт, що містить інформацію про вцілілі мутанти.
+- Використання команди `slice --file <path>` повертає промпт для одного файлу, що містить контекст ±3 рядки.

package/scripts/docs/lint-cli.md

@@ -0,0 +1,25 @@
+# lint-cli.mjs
+
+## Огляд
+
+Файл забезпечує оркестрацію виконання правил лінтингу для проєкту. Він сканує правила, визначені в файлах `meta.json`, та викликає відповідні файли `lint.mjs` для перевірки коду. Це дозволяє автоматично виявляти та повідомляти про помилки в коді на основі набору визначених правил.
+
+## Поведінка
+
+selectLintRules: Вибирає id правил для фази, алфавітно.
+runLint: Запускає lint-оркестрацію. Збирає змінені файли, якщо потрібно, та запускає lint для кожного правила, яке відповідає вибраній фазі.
+
+## Публічний API
+
+- selectLintRules — Вибирає набір правил для перевірки.
+- runLint — Запускає процес перевірки.
+
+## Гарантії поведінки
+
+- Оркестратор запускає правила лінтингу, визначені в файлах `rules/<id>/meta.json`.
+- Для режиму `quick` оркестратор обробляє лише змінені файли, визначені за допомогою `git diff`.
+- Для режиму `ci` оркестратор обробляє весь проєкт.
+- Порядок виконання правил визначається алфавітним порядком імен файлів `rules/<id>/js/lint.mjs`.
+- Перший виклик функції `lint` повертає ненульове значення, що призводить до зупинки виконання.
+- Режим `quick` не використовує кешування.
+- Режим `ci` не використовує кешування.

package/scripts/docs/post-tool-use-fix.md

@@ -0,0 +1,27 @@
+# post-tool-use-fix.mjs
+
+## Огляд
+
+Файл забезпечує точкову маршрутизацію `npx @nitra/cursor fix` для конкретних файлів, що були змінені. Він запускає цей процес після редагування, щоб уникнути затримки, спричиненої попереднім синхронним хуком. Це дозволяє швидко та ефективно виправляти правила стилю коду для змінених файлів.
+
+## Поведінка
+
+`routeFilePathToRules`: повертає список ID правил `npm/rules/<id>`, які слід застосувати до вказаного шляху файлу, використовуючи відповідні шаблони glob.
+`runPostToolUseFixCli`: запускає `npx @nitra/cursor fix` з переліченими правилами, отримуючи вхідні дані з stdin, та повертає exit-код запущеного процесу. Якщо не вдається запустити `fix`, повертає 1.
+`readStdin`: зчитує вміст stdin до EOF, повертаючи рядок UTF-8. Якщо stdin TTY, повертає порожній рядок.
+
+## Публічний API
+
+- routeFilePathToRules — Знаходить правила, які відповідають шляху файлу, та повертає їх. Якщо жодного правила не знайдено, повертає порожній масив.
+- runPostToolUseFixCli — Запускає інструмент для виправлення помилок, викликаний з `bin/n-cursor.js` при певних умовах. Дозволяє передавати дані для тестування та замінити стандартну функцію запуску процесу.
+
+## Гарантії поведінки
+
+- Приймає JSON із шляхом файлу як вхідні дані.
+- Якщо файл не має маршруту, повертає `true`.
+- Інакше запускає `npx --no @nitra/cursor fix` з переданими правилами.
+- Не блокує потік (turn).
+- Повертає `false` у разі невдачі запуску `npx`.
+- Не кидає винятків.
+- Ігнорує шляхи `.github` та `.git`.
+- Не використовує кешування.

package/scripts/docs/rename-yaml-extensions.md

@@ -0,0 +1,36 @@
+# rename-yaml-extensions.mjs
+
+## Огляд
+
+Цей файл перейменовує розширення файлів YAML у репозиторіях, відповідно до узгоджених правил. Він автоматизує процес зміни розширення файлів `.yml` на `.yaml` для файлів, що відповідають певним шаблонам шляхів, зокрема для маніфестів Kubernetes та workflow-файлів GitHub. Це забезпечує узгодженість форматування YAML у репозиторії.
+
+## Поведінка
+
+- `posixRelFromRoot`: Обчислює відносний шлях від кореня, замінюючи `\` на `/`. Повертає `null`, якщо шлях поза коренем.
+- `pathMatchesK8sYml`: Перевіряє, чи шлях містить сегмент `k8s` та має розширення `.yml`.
+- `pathMatchesGithubYaml`: Перевіряє, чи шлях містить сегмент `.github` та має розширення `.yaml`.
+- `replaceExtension`: Замінює останнє розширення файлу на вказане, додаючи крапку.
+- `collectRenameOps`: Збирає операції перейменування, обходячи репозиторій, ігноруючи `node_modules`, `.git`, `dist`, `coverage`, `.turbo`, `.next`.
+- `renameYamlExtensions`: Виконує перейменування, симулюючи або реалізуючи перейменування, на основі правил k8s/github, обходячи вказані каталоги.
+- `parseRenameYamlArgs`: Розбирає аргументи командного рядка `--dry-run` та `--root`.
+
+## Публічний API
+
+- posixRelFromRoot — Повертає відносний шлях від кореня файлової системи, або `null`, якщо шлях знаходиться за межами кореня.
+- pathMatchesK8sYml — Перевіряє, чи відповідає шлях формату YAML-маніфестів Kubernetes.
+- pathMatchesGithubYaml — Перевіряє, чи відповідає шлях формату YAML-файлів `.github`.
+- replaceExtension — Замінює розширення файлу на вказане.
+- renameYamlExtensions — Перейменовує YAML-файли відповідно до правил Kubernetes та `.github`.
+- parseRenameYamlArgs — Розбирає аргументи командного рядка для команди перейменування.
+
+## Гарантії поведінки
+
+- Файл `bin/rename-yaml-extensions.mjs` перейменовує розширення YAML файлів.
+- Перейменування відбувається за двома сценаріями:
+  - Файли з сегментом шляху `k8s` та суфіксом `.yml` перейменовуються на `.yaml`.
+  - Файли з сегментом `.github` та суфіксом `.yaml` перейменовуються на `.yml`.
+- Обхід шляхів: `node_modules`, `.git`, `dist`, `coverage`, `.turbo`, `.next` не обробляються.
+- Аргументи CLI: `--dry-run`, `--root`
+- Повертає `false` у разі невдачі.
+- Не кидає винятків.
+- Не використовує кешування.

package/scripts/docs/skills-cli.md

@@ -0,0 +1,35 @@
+# skills-cli.mjs
+
+## Огляд
+
+Це інструмент для запуску скілів з пакету `@nitra/cursor` без синхронізації правил. Він збирає інструкції скілу та контекст проєкту для генерації промптів, які потім можуть бути використані для отримання відповідей від Claude або інших агентів. Інструмент забезпечує зручний інтерфейс командного рядка для взаємодії з скілами.
+
+## Поведінка
+
+- `normalizeSkillId`: Перетворює вхідний `name` скілу (можливо з префіксом `n-`) в нормалізований `id` каталогу.
+- `listSkillIds`: Повертає відсортований список `id` каталогів скілів у каталозі `skills/` пакета, фільтруючи лише ті, що мають файл `SKILL.md`.
+- `getSkillMdPath`: Створює повний шлях до файлу `SKILL.md` скілу на основі `skillsRoot` та `skillId`.
+- `readIfExists`: Перевіряє існування файлу за шляхом `path` та повертає його вміст, якщо файл існує, інакше повертає `null`.
+- `buildSkillPrompt`: Збирає промпт для LLM, включаючи інструкції скілу, текст завдання, та контекст проєкту (package.json, tsconfig.json, .n-cursor.json).
+- `runLlmCli`: Запускає LLM CLI (`claude` або `cursor-agent`) з наданим промптом та робочим каталогом проєкту.
+- `resolveBundledPackageRoot`: Визначає абсолютний шлях до кореня пакета `@nitra/cursor`, використовуючи `import.meta.url` для визначення кореня.
+- `runSkillsCli`: Обробляє аргументи командного рядка для запуску скілів, викликає відповідні функції для збору промптів та запуску LLM CLI.
+
+## Публічний API
+
+- normalizeSkillId: Перетворює ID на стандартний формат.
+- listSkillIds: Повертає список ID навичок.
+- buildSkillPrompt: Створює запит для навички.
+- resolveBundledPackageRoot: Знаходить базову директорію пакета `@nitra/cursor`.
+- runSkillsCli: Запускає CLI для навичок.
+
+## Гарантії поведінки
+
+- Запускає скіли пакета `@nitra/cursor` без синхронізації правил.
+- Читає скіли з файлів `npm/skills/<id>/SKILL.md` або кешу `npx`.
+- Збирає інструкцію скілу та контекст проєкту (package.json, tsconfig.json, .n-cursor.json) для створення промпту.
+- Використовує промпт для генерації відповіді, яка може бути виведена в stdout або делегована `cursor-agent` / `claude`.
+- Підтримує команди `skill list`, `skill taze`, `skill cursor taze`, `skill cursor taze "онови залежності"`, `skill claude taze`.
+- Повертає `false` або `null` у разі невдачі виконання.
+- Не кидає винятки.
+- Не використовує кешування.

package/scripts/docs/sync-claude-config.md

@@ -0,0 +1,52 @@
+# sync-claude-config.mjs
+
+## Огляд
+
+Цей файл синхронізує конфігурацію Claude Code з шаблонів пакету `npm/.claude-template`, включаючи налаштування, slash-команди та хуки. Він забезпечує узгодженість між проєктом та базовою конфігурацією, автоматично оновлюючи та підтримуючи налаштування хуків та команд. Це дозволяє використовувати стандартні налаштування та автоматично адаптувати проєкт до змін у шаблоні.
+
+## Поведінка
+
+- `parseGitignoreFragmentLines`: Розбиває рядок фрагменту `.gitignore` на окремі рядки, видаляє порожні та коментарні рядки.
+- `syncGitignoreAdrFragment`: Дописує відсутні рядки з канонічного фрагменту `.gitignore` у `.gitignore` проєкту.
+- `syncClaudeCommands`: Копіює slash-команди з `commands/` темплейту в `.claude/commands/*.md`.
+- `syncClaudeSettings`: Об'єднує конфігурацію Claude Code з темплейту, зберігаючи користувацькі налаштування та перезаписуючи хуки, що ідентифікуються маркерами.
+- `syncCursorHooksConfig`: Об'єднує конфігурацію хуків Cursor з темплейту, додаючи або видаляючи хуки ADR Stop-hook залежно від наявності правила `adr`.
+- `syncAdrHookScript`: Копіює bash-скрипт ADR capture Stop-hook з темплейту в `.claude/hooks/capture-decisions.sh`.
+- `syncAdrNormalizeHookScript`: Копіює bash-скрипт ADR normalize Stop-hook з темплейту в `.claude/hooks/normalize-decisions.sh`.
+- `syncAdrHookLibScripts`: Копіює bash-скрипти lib-файлів з `commands/` темплейту в `.claude/hooks/lib/`.
+- `removeOrphanAdrHookLib`: Видаляє директорію lib-файлів з `.claude/hooks/lib/`, якщо правило `adr` вимкнено.
+- `syncPiExtensions`: Копіює розширення TypeScript з `npm/.pi-template/extensions/n-cursor-adr/` в `.pi/extensions/n-cursor-adr/`.
+- `removeOrphanPiExtension`: Видаляє директорію розширення TypeScript з `.pi/extensions/n-cursor-adr/`, якщо правило `adr` вимкнено.
+- `syncClaudeConfig`: Синхронізує конфігурацію Claude Code та Cursor hooks, об'єднуючи їх та додаючи/видаляючи хуки
+
+## Публічний API
+
+- MANAGED_HOOK_COMMAND_MARKER — Маркер для фіксації хуків PostToolUse.
+- LEGACY_STOP_HOOK_COMMAND_MARKER — Маркер для legacy-хуків Stop, використовується під час оновлення.
+- ADR_HOOK_COMMAND_MARKER — Маркер для хуків ADR Stop, визначає шлях до скрипту capture-decisions.
+- ADR_NORMALIZE_HOOK_COMMAND_MARKER — Маркер для хуків ADR Stop, визначає шлях до скрипту normalize-decisions.
+- CURSOR_ADR_HOOK_COMMAND_MARKER — Маркер для хуків Cursor ADR Stop, шлях до скрипту в `.cursor/hooks.json`.
+- CURSOR_ADR_NORMALIZE_HOOK_COMMAND_MARKER — Маркер для хуків Cursor ADR Normalize Stop, шлях до скрипту в `.cursor/hooks.json`.
+- MANAGED_HOOK_COMMAND_MARKERS — Усі маркери managed-хуків пакета.
+- PI_DIR — Корінь артефактів pi.dev у проєкті-споживачі.
+- PI_EXTENSIONS_DIR — Директорія pi.dev TS-extensions у проєкті-споживачі.
+- PI_TEMPLATE_DIR_NAME — Назва bundled-директорії pi-template у пакеті `@nitra/cursor`.
+- PI_EXTENSION_NAME — Ім'
+
+## Гарантії поведінки
+
+Немає кешування.
+
+Функція повертає `true`, якщо синхронізація завершилася успішно.
+
+Якщо `claude-config` встановлено на `false` у `.n-cursor.json`, функція не змінює конфігурацію Claude.
+
+`settings.json` оновлюється шляхом об'єднання конфігурації з `.claude-template/settings.json`, де перекриваються команди, що містять `MANAGED_HOOK_COMMAND_MARKER`, дозволи `permissions.allow` об'єднуються, і правила `adr` додаються/видаляються згідно з їх статусом у `.n-cursor.json`.
+
+`.claude/commands/*.md` оновлюється шляхом повного заміщення вмісту з `.claude-template/commands/`.
+
+`.claude/hooks/capture-decisions.sh` оновлюється шляхом повного копіювання з `.claude-template/hooks/` лише тоді, коли правило `adr` увімкнено в `.n-cursor.json`.
+
+`.claude/hooks/normalize-decisions.sh` оновлюється шляхом повного копіюювання з `.claude-template/hooks/` лише тоді, коли правило `adr` увімкнено в `.n-cursor.json`.
+
+`.

package/scripts/docs/sync-setup-bun-deps-action.md

@@ -0,0 +1,26 @@
+# sync-setup-bun-deps-action.mjs
+
+## Огляд
+
+Файл містить конфігурацію GitHub Action `setup-bun-deps`, яка автоматично встановлює залежності проєкту Bun. Він використовується workflow для підготовки середовища проєкту, забезпечуючи узгодженість та спрощуючи виконання тестів та інших завдань, що потребують Bun. Це дозволяє workflow, що використовує `actions/checkout@v6`, безпосередньо використовувати action, не потребуючи додаткової конфігурації.
+
+## Поведінка
+
+1.  Перевіряє наявність шаблону composite action `action.yml` у каталозі `github-actions/setup-bun-deps/` всередині кореня пакету `@nitra/cursor`.
+2.  Якщо шаблон не знайдено, кидає помилку, вказуючи очікуваний шлях та пропонуючи перевстановити пакет.
+3.  Створює каталог `.github/actions/setup-bun-deps` у цільовому репозиторії, якщо його не існує.
+4.  Зчитує вміст файлу `action.yml` з джерела.
+5.  Записує вміст `action.yml` у файл `action.yml` у цільовому репозиторії. Додає новий рядок в кінці файлу, якщо потрібно.
+6.  Повертає об'єкт, що містить інформацію про успішність запису та повний шлях до створеного файлу.
+
+## Публічний API
+
+syncSetupBunDepsAction — Створює файл з залежностями Bun, використовуючи корінь пакета `@nitra/cursor`.
+
+## Гарантії поведінки
+
+- Копіює файл `action.yml` з каталогу `github-actions/setup-bun-deps/` у каталог `.github/actions/setup-bun-deps/`.
+- Забезпечує доступність action `setup-bun-deps` для workflow, що використовує `actions/checkout@v6`.
+- Використовує `npx @nitra/cursor` для ініціалізації action.
+- Не враховує наявність checkout runner.
+- Не має кешування.

package/scripts/docs/upgrade-nitra-cursor-and-install.md

@@ -0,0 +1,29 @@
+# upgrade-nitra-cursor-and-install.mjs
+
+## Огляд
+
+Файл автоматично синхронізує правила командного інтерфейсу (CLI) з останньою версією `@nitra/cursor` з npm registry. Це забезпечує, що локальна версія `@nitra/cursor` завжди актуальна, а також інсталює необхідні залежності за допомогою `bun i`. Він використовується для підтримки узгодженості між локальним проєктом та офіційним репозиторієм npm.
+
+## Поведінка
+
+shouldSkipNpmVersionUpgrade: Визначає, чи потрібно оновлювати версію залежності з npm, враховуючи специфікатор залежності та різні типи специфікаторів (workspace, file, link тощо).
+fetchLatestNitraCursorVersionFromNpm: Отримує останню версію пакета `@nitra/cursor` з npm registry та повертає її як рядок.
+resolveInstalledPackageRoot: Повертає шлях до каталогу `node_modules/@nitra/cursor` якщо залежність встановлена, інакше повертає шлях до кореня пакету поточного процесу CLI (кеш npx).
+upgradeNitraCursorToLatestAndBunInstall: Оновлює версію `@nitra/cursor` у `package.json` до останньої з npm, запускає `bun i` та повертає шлях до каталогу `node_modules/@nitra/cursor`.
+
+## Публічний API
+
+- shouldSkipNpmVersionUpgrade — Перевіряє можливість оминання оновлення версії npm.
+- fetchLatestNitraCursorVersionFromNpm — Отримує останню версію пакета `@nitra/cursor` з npm.
+- resolveInstalledPackageRoot — Знаходить шлях до встановленого пакета.
+- upgradeNitraCursorToLatestAndBunInstall — Оновлює `@nitra/cursor` до останньої версії та встановлює Bun.
+
+## Гарантії поведінки
+
+- Якщо наявна залежність через `workspace:`, `file:`, `link:` – не змінює версію в npm registry та не запускає `bun i`.
+- Запускає `bun i` у корені проєкту після підтягування останньої версії `@nitra/cursor` з npm registry.
+- Повертає шлях до `node_modules/@nitra/cursor`, якщо каталог існує.
+- В іншому випадку повертає шлях до кореня пакету поточного процесу CLI (наприклад, кеш npx).
+- Не кидає винятки.
+- У разі невдачі повертає `false` або `null`.
+- Не використовує кешування.

package/scripts/docs/worktree-cli.md

@@ -0,0 +1,46 @@
+# worktree-cli.mjs
+
+## Огляд
+
+Файл `n-cursor worktree` є CLI-оркестратором для управління git worktree. Він дозволяє додавати, видаляти та перевіряти worktree, забезпечуючи зручний інтерфейс для роботи з декількома гілками в одному репозиторії. Цей інструмент використовується для організації робочого процесу розробника, що працює з кількома гілками.
+
+## Поведінка
+
+1.  **Ініціалізація:** Отримує аргументи командного рядка, включаючи підкоманду та її параметри. Визначає поточний робочий каталог, якщо його не вказано. Ініціалізує контекст для логування та отримання дати.
+2.  **Розбір підкоманди:** Визначає, яку підкоманду було передано. Залежно від підкоманди, виконує відповідні дії.
+3.  **`add` (Створення нового worktree):**
+    - Перевіряє наявність необхідних параметрів: назви гілки та опису.
+    - Визначає унікальну назву гілки, якщо вона вже існує.
+    - Створює новий worktree, використовуючи вказану гілку та опис. Записує опис у файл `.md` у каталозі `.worktrees/`.
+    - Створює нагадування про незакомічені зміни основного дерева, якщо це необхідно.
+4.  **`remove` (Видалення worktree):**
+    - Перевіряє наявність необхідного параметра: назви гілки.
+    - Видаляє checkout та файл `.md` для вказаної гілки.
+    - Видаляє всі осиротілі файли опису, які залишилися після видалення гілки.
+    - Очищає файли flow-sibling-ів (.flow.json/.events.jsonl/lock) для запобігання їх осиротіння.
+5.  **`list` (Перелік worktree):**
+    - Виводить список всіх створених worktree, отриманий за допомогою команди `git worktree list`.
+    - Для кожного worktree виводить його повний шлях та вміст файлу опису `.md`.
+6.  **`prune` (Видалення осиротілих worktree):**
+    - Визначає всі файли опису `.md`, які більше не пов'язані з жодною зареєстрованою гілкою worktree.
+    - Видаляє ці осиротілі файли опису.
+7.  \*\*Викона
+
+## Публічний API
+
+runWorktreeCli — Запускає підкоманду worktree.
+
+## Гарантії поведінки
+
+- `runWorktreeCli` повертає `false` при будь-якій помилці.
+- `runWorktreeCli` повертає `null` при помилці, якщо результат неможливо визначити.
+- Немає кешування.
+- `add <branch> "<опис>"` створює гілку `worktree` з описом.
+- `remove <branch> [--force]` видаляє checkout гілки `worktree`, але не видаляє саму гілку.
+- `list` виводить список всіх `worktree`.
+- `prune` видаляє `worktree` без checkout.
+- Немає гарантій щодо стану git-репозиторію.
+- Немає гарантій щодо наявності незакомічених змін.
+- Немає гарантій щодо наявності осиротілих `worktree`.
+- `runWorktreeCli` не кидає винятків.
+- Помилки переховуються.

package/scripts/lib/docs/assert-project-root.md

@@ -0,0 +1,28 @@
+# assert-project-root.mjs
+
+## Огляд
+
+Файл забезпечує захист від непередбачуваної поведінки при запуску `npx @nitra/cursor` з піддиректорій git-репозиторію. Він гарантує, що процес синхронізації та встановлення артефактів виконується лише з кореневої директорії проєкту, запобігаючи розповсюдженню конфігураційних файлів у невідповідні місця. Це забезпечує узгодженість та передбачуваність процесу налаштування проєкту.
+
+## Поведінка
+
+gitToplevel: Визначає реальний шлях кореня git-репозиторію, використовуючи `git rev-parse --show-toplevel`. Повертає `null`, якщо `git` недоступний або не вдалося визначити корінь.
+safeRealpath: Повертає реальний шлях вказаного каталогу, ігноруючи символічні посилання. Якщо шлях не існує, повертає вихідний шлях без змін.
+assertCwdIsProjectRoot: Перевіряє, чи поточний робочий каталог є коренем git-репозиторію. Якщо так, функція не робить нічого. Якщо каталог знаходиться всередині git-репозиторію, але не є його коренем, викидає помилку, що інформує про необхідність перейти в корінь репозиторію.
+
+## Публічний API
+
+- gitToplevel — Отримує реальний шлях кореня git-репозиторію, використовуючи `git rev-parse --show-toplevel`. Повертає шлях або `null`, якщо `dir` не є коренем репозиторію або `git` недоступний.
+- assertCwdIsProjectRoot — Перевіряє, чи `dir` є коренем git-репозиторію. Якщо `dir` є піддиректорією репозиторію або знаходиться поза репозиторієм (без визначення `toplevel`), то функція пропускає операцію без помилки.
+
+## Гарантії поведінки
+
+- При запуску `npx @nitra/cursor` з кореня будь-якого git-репозиторію, виконується синхронізація проєкту.
+- При запуску `npx @nitra/cursor` з піддиректорії git-репозиторію, `cwd` встановлюється на корінь git-репозиторію.
+- Синхронізація проєкту включає створення та запуск сценаріїв для `.cursor/rules/`, `.cursor/skills/`, `.claude/`, `AGENTS.md`, `CLAUDE.md`, `.n-cursor.json`, `.gitignore`.
+- Синхронізація проєкту включає запуск `bun install`.
+- При невдачі синхронізації повертається `false` або `null`.
+- Немає кешування.
+- Не перехоплює винятки.
+- Функція `gitToplevel` забезпечує доступ до кореня git-репозиторію.
+- Функція `assertCwdIsProjectRoot` перевіряє, чи поточний `cwd` є коренем git-репозиторію.

package/scripts/lib/docs/diff-added-lines.md

@@ -0,0 +1,34 @@
+# diff-added-lines.mjs
+
+## Огляд
+
+Файл визначає, чи є рядок коду новим (introduced) або вже існував у проєкті. Він використовується для класифікації результатів аналізу коду (lint-findings) на основі їхнього розташування відносно версії проєкту. Це допомагає розробникам розуміти, які зміни коду потребують негайної уваги.
+
+## Поведінка
+
+ALL_LINES: мітка, що позначає всі рядки файлу, які були introduced.
+parseAddedLines: парсить вивід `git diff` та повертає мапу, де ключ — ім'я файлу, а значення — множина номерів рядків, які були додані.
+addedLinesByFile: визначає мапу доданих рядків для заданих файлів, використовуючи `git diff` та `git ls-files`.
+isIntroducedLine: перевіряє, чи рядок у файлі є introduced, використовуючи мапу, створену `addedLinesByFile`.
+
+## Публічний API
+
+- ALL_LINES — Вказує на новий, не відстежений файл, що містить усі рядки.
+- parseAddedLines — Аналізує вивід команди `git diff --unified=0` для створення мапи доданих рядків у файлі.
+- addedLinesByFile — Визначає додані рядки у файлах, порівнюючи їх з версією в HEAD, та класифікує їх як відстежені або не відстежені.
+- isIntroducedLine — Перевіряє, чи рядок у файлі є новим, тобто доданим.
+
+## Гарантії поведінки
+
+- `ALL_LINES` повертає список усіх рядків файлу.
+- `ALL_LINES` повертає `false` якщо не вдалося парсити diff.
+- `parseAddedLines` повертає список рядків, які були додані у diff.
+- `parseAddedLines` повертає `false` якщо не вдалося парсити diff.
+- `addedLinesByFile` повертає список рядків, які були додані у кожному файлі.
+- `isIntroducedLine` визначає, чи є рядок доданим у diff.
+- `isIntroducedLine` повертає `false` якщо рядок не був доданий у diff.
+- Результати парсингу кешуються для кожного запуску.
+- Рядок вважається "introduced" якщо він є в diff.
+- Рядок вважається "pre-existing" якщо він не є в diff.
+- Рядки, що не були знайдені в diff, вважаються "untracked".
+- `ALL_LINES` повертає всі рядки з diff, навіть якщо вони "untracked".

package/scripts/lib/docs/read-n-cursor-config-lite.md

@@ -0,0 +1,28 @@
+# read-n-cursor-config-lite.mjs
+
+## Огляд
+
+Цей файл читає файл `.n-cursor.json`, що містить список правил для конфігурації. Він повертає цей список, щоб `fix.mjs` міг використовувати правила для визначення конфігурації. Це забезпечує базове читання конфігурації правил для запуску `fix.mjs` з командного рядка.
+
+## Поведінка
+
+**readNCursorConfigLite**
+Зчитує конфігурацію з файлу `.n-cursor.json`. Повертає об'єкт з інформацією про правила та вимкнені правила. Якщо файл відсутній, повертає конфігурацію з порожнім масивом правил.
+
+**isRuleEnabled**
+Перевіряє, чи правило з активним статусом згідно з конфігурацією. Повертає `true`, якщо файл відсутній, правило вимкнено в `disable-rules` або присутнє в `rules`. Повертає `false` в іншому випадку.
+
+## Публічний API
+
+- readNCursorConfigLite — Завантажує конфігурацію курсора.
+- isRuleEnabled — Перевіряє статус активності правила.
+
+## Гарантії поведінки
+
+- Якщо файл `.n-cursor.json` відсутній, вважається, що всі правила включені.
+- Якщо файл `.n-cursor.json` існує, але поле `rules` порожнє, вважається, що всі правила включені.
+- Якщо файл `.n-cursor.json` існує і має поле `rules`, але поле `rules` порожнє, вважається, що всі правила включені.
+- Якщо правило вказане в полі `disable-rules`, воно вимкнено.
+- Повертає `false` якщо файл `.n-cursor.json` відсутній або недійсний.
+- Повертає `null` якщо не вдалося прочитати файл `.n-cursor.json`.
+- Не використовує кешування.