@nitra/cursor 3.27.0 → 3.28.0

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`.
+- Не використовує кешування.

package/scripts/lib/docs/resolve-target-files.md

@@ -0,0 +1,34 @@
+# resolve-target-files.mjs
+
+## Огляд
+
+Цей файл відповідає за перевірку наявності файлів, що відповідають певним правилам, вказаним у файлах `policy/<name>/target.json`. Він створює список файлів для подальшого використання, використовуючи або конкретні відносні шляхи, або обхід каталогу з використанням шаблонів та ігнорування файлів. Це забезпечує узгодженість та контроль над файлами, які потрібно обробити, відповідно до заданих політик.
+
+## Поведінка
+
+1.  **Ініціалізація:** Отримує специфікацію файлів з `target.json`, включаючи `single` або `walkGlob`.
+2.  **Обробка `single`:** Якщо `files.single` є рядком, перевіряє, чи шлях є відносним та не містить сегменту `..`. Якщо шлях безпечний, перевіряє наявності файлу за шляхом та повертає масив з абсолютним шляхом, якщо файл існує, або порожній масив, якщо ні.
+3.  **Обробка `walkGlob`:** Якщо `files.walkGlob` є не визначеним, або є масивом рядків, виконує обхід дерева файлів від заданого кореня.
+4.  **Завантаження ігнорування:** Завантажує список абсолютних шляхів, які слід ігнорувати, з конфігурації `.n-cursor.json:ignore`.
+5.  **Кешування обходу:** Використовує кеш обходу дерева (Map) для запобігання повторному обходу одного й того ж набору ігнорування. Якщо обхід вже виконано для заданого набору ігнорування, повертає результат з кешу.
+6.  **Обхід дерева:** Якщо обхід не кешований або кеш порожній, виконує обхід дерева файлів від заданого кореня, використовуючи `walkDir`. Під час обходу генерує відносні шляхи файлів від кореня.
+7.  **Фільтрація за масками:** Для кожного відносного шляху файлу застосовує маски `walkGlob` за допомогою `picomatch`. Фільтрує файли, які відповідають маскам, та виключає ті, що відповідають негативним маскам.
+8.  **Збіг з ігноруванням:** Перевіряє, чи файл не входить до списку ігнорування.
+9.  **Збіг шляху:** Перетворює відносні шляхи файлів у абсолютні шляхи, додавши корень.
+10. **Повернення результатів:** Повертає масив абсолют
+
+## Публічний API
+
+resolveTargetFiles — Знаходить файли, що вказані в `target.json:files`.
+
+## Гарантії поведінки
+
+- **Контракт на поліси:** Зчитуються лише файли з репозиторію.
+- **`single`:** Якщо `existsSync`, повертається список файлів, що відповідають `single`. Інакше, повертається порожній список.
+- **`walkGlob`:** Використовується picomatch для обробки glob-шаблонів відносно шляхів, отриманих з обходу `walkDir` від `root`.
+- **Ігнорування:** Підтримується ігнорування файлів за допомогою `.n-cursor.json:ignore` та кешування шляхів ігнорування у `walkCache`.
+- **Кешування:** Результати обходу кешуються для повторного використання при однаковому наборі ігнорувань.
+- **Path-traversal:** При розв'язанні шляхів у формі `single` виникає помилка.
+- **Відсутність результатів:** Якщо не знайдено жодного файлу, що відповідає критеріям, повертається порожній список.
+- **Fail-safe:** Якщо `required` встановлено на `true`, і не знайдено жодного файлу, що відповідає критеріям, виникає помилка.
+-

package/scripts/lib/docs/root-notice.md

@@ -0,0 +1,28 @@
+# root-notice.mjs
+
+## Огляд
+
+Цей файл вставляє root-guard preflight для скілів, які змінюють проєкт у поточному каталозі. Він забезпечує, що скіл виконується in-place, без ізоляції worktree, і використовується для випадків, коли не потрібна ізоляція worktree. Це гарантує коректне виконання скілу від імені проєкту.
+
+## Поведінка
+
+ROOT_START: вставляє маркер початку root-блоку.
+ROOT_END: вставляє маркер кінця root-блоку.
+injectRootNotice: вставляє, оновлює або видаляє root-guard блок у вмісті `SKILL.md` на основі параметра `enabled`.
+
+## Публічний API
+
+- ROOT_START — Позначає початок блоку root.
+- ROOT_END — Позначає кінець блоку root.
+- injectRootNotice — Змінює вміст `SKILL.md` щодо root-guard блоку.
+
+## Гарантії поведінки
+
+- Якщо `requireRoot: true` у `meta.json`, то поточний робочий каталог є коренем проєкту.
+- Якщо `requireRoot: false`, то блок не вставляється.
+- Вставка відбувається лише між маркерами.
+- Вставка ре-синк ідемпотентно: наявний блок замінюється.
+- `ROOT_START` викликається перед вставкою блоку.
+- `ROOT_END` викликається після вставки блоку.
+- `injectRootNotice` викликається під час вставки блоку.
+- Немає кешування.

package/scripts/lib/docs/rule-meta-helpers.md

@@ -0,0 +1,34 @@
+# rule-meta-helpers.mjs
+
+## Огляд
+
+Цей файл містить хелпери для автоматичного виявлення та обробки правил конфігурації репозиторіїв. Він надає функції для ідентифікації ID міграцій, нормалізації списків та визначення URL репозиторіїв, а також для виявлення монорепо-пакетів. Ці функції використовуються для автоматизованої обробки конфігурації та забезпечення узгодженості в репозиторіях.
+
+## Поведінка
+
+`RULE_MIGRATIONS`: містить відомості про застарілі ідентифікатори правил та їхні відповідні актуальні ідентифікатори.
+`migrateRuleIds`: перетворює введений список ідентифікаторів правил на список, де застарілі ідентифікатори замінені на актуальні, зберігаючи порядок і усуваючи дублікати.
+`detectLegacyRuleIds`: витягує з введеного списку ідентифікаторів правил ті, що потребують заміни на актуальні.
+`normalizeIdList`: нормалізує введений список ідентифікаторів правил, видаляючи пробіли, перетворюючи на нижній регістр та зберігаючи порядок, усуваючи дублікати.
+`getRepositoryUrl`: повертає URL репозиторію з `package.json`, якщо він є рядком або об'єктом, інакше повертає `null`.
+`isMonorepoPackage`: визначає, чи оголошено `workspaces` в `package.json`, повертаючи `true` якщо так, і `false` в іншому випадку.
+
+## Публічний API
+
+- RULE_MIGRATIONS — Карта, яка відображає застарілі rule-id на актуальні, для автоматичної міграції при читанні конфігурації.
+- migrateRuleIds — Розгортає застарілі rule-id згідно з `RULE_MIGRATIONS`, зберігаючи порядок, дедуплікуючи та не змінюючи вхідний список.
+- detectLegacyRuleIds — Повертає список застарілих rule-id, для яких є відповідність у `RULE_MIGRATIONS`, для логування міграції.
+- normalizeIdList — Нормалізує список ідентифікаторів, видаляючи пробіли, перетворюючи на нижній регістр та зберігаючи порядок.
+- getRepositoryUrl — Отримує URL репозиторію з `package.json`.
+- isMonorepoPackage — Перевіряє, чи `package.json` містить поле `workspaces`, що вказує на монорепо.
+
+## Гарантії поведінки
+
+- `RULE_MIGRATIONS` повертає `true`, якщо успішно виконано міграцію правил. Повертає `false` у разі помилки.
+- `migrateRuleIds` змінює внутрішній стан, щоб відобразити успішну міграцію ідентифікаторів правил.
+- `detectLegacyRuleIds` повертає список ідентифікаторів правил, які вважаються застарілими.
+- `normalizeIdList` повертає нормалізований список ідентифікаторів правил.
+- `getRepositoryUrl` повертає URL репозиторію, якщо він існує. Повертає `null` у разі помилки.
+- `isMonorepoPackage` повертає `true`, якщо пакет є частиною монорепо. Повертає `false` у разі помилки.
+- Функції не викликають винятки. У разі невдачі повертають `false` або `null`.
+- Кеш не використовується.

package/scripts/lib/docs/rule-meta.md

@@ -0,0 +1,34 @@
+# rule-meta.mjs
+
+## Огляд
+
+Цей файл парсує метадані правил npm/rules/<id>/meta.json для автоматичного виявлення проблемних місць у коді. Він визначає, коли правило має бути активним, використовуючи різні специфікації, такі як завжди-ввімкнене правило, правило, яке активується після виявлення залежностей, або правило, яке активується на основі glob-шаблонів чи незводимих предикатів. Це дозволяє системі динамічно визначати та застосовувати правила, не потребуючи явного налаштування.
+
+## Поведінка
+
+`RULE_ALWAYS`: визначає літерал для активації правила "завжди".
+`parseRuleAutoSpec`: нормалізує значення `meta.json.auto` у дискриміновану форму.
+`parseRuleLintPhase`: нормалізує значення `meta.json.lint` у фазу lint.
+`readRuleMetaRaw`: читає та парсить `meta.json` одного правила, повертаючи об’єкт або `null`.
+
+## Публічний API
+
+- RULE_ALWAYS — Активує правило.
+- parseRuleAutoSpec — Перетворює значення `meta.json.auto` на конкретну опцію.
+- parseRuleLintPhase — Перетворює значення `meta.json.lint` на фазу lint.
+- readRuleMetaRaw — Зчитує та аналізує файл `meta.json` правила.
+
+## Гарантії поведінки
+
+- `RULE_ALWAYS` повертає `true` якщо правило активне.
+- `parseRuleAutoSpec` повертає `true` якщо специфікація правила успішно розібрана.
+- `parseRuleAutoSpec` повертає `false` якщо специфікація правила не може бути розібрана.
+- `parseRuleLintPhase` повертає `true` якщо правило успішно розібрано на етапі linting.
+- `parseRuleLintPhase` повертає `false` якщо правило не може бути розібрано на етапі linting.
+- `readRuleMetaRaw` повертає `true` якщо метадані правила успішно прочитані.
+- `readRuleMetaRaw` повертає `false` якщо метадані правила не можуть бути прочитані.
+- У разі невдачі, функція повертає `false` або `null`.
+- Функції не кидають винятків.
+- Немає кешування.
+- Немає гарантій щодо стану файлів або каталогів.
+- Поля `worktree` правила не використовуються.

package/scripts/lib/docs/rule-predicates.md

@@ -0,0 +1,30 @@
+# rule-predicates.mjs
+
+## Огляд
+
+Цей файл містить набір предикатів, які використовуються для автоматичного визначення правил. Ці предикати дозволяють перевіряти наявність файлів, вміст source-коду та інформацію з репозиторіїв, щоб виявляти потенційні порушення правил. Він забезпечує механізм для автоматизованого пошуку та виявлення правил на основі даних.
+
+## Поведінка
+
+1.  **Ініціалізація перевірки репозиторію:** Отримує URL репозиторію з кореневого `package.json` або з `meta.json.repository`. Перевіряє, чи URL існує і чи містить він вказаний маркер.
+2.  **Перевірка залежностей у дереві:** Для кожного `package.json` у дереві репозиторію, перебирає всі пакети в залежностях. Якщо пакет має вказаний маркер, повертає `true`. Ігнорує директорії `node_modules`, `.git`, `.next` та `.turbo`.
+3.  **Перевірка вкладених `package.json`:** Для кореневого `package.json` перевіряє, чи є в будь-якому вкладеному `package.json` відсутній `vite` у секції `devDependencies`. Ігнорує директорії `node_modules`, `.git`, `.next` та `.turbo`.
+4.  **Перевірка фактів:** Якщо надано факти, перевіряє наявність `hasGqlTaggedTemplates` та `hasHasuraConfig`. Якщо `hasGqlTaggedTemplates` має значення `true`, повертає `true`. Якщо `hasHasuraConfig` має значення `true`, повертає `true`.
+5.  **Перевірка наявності `bun`:** Якщо надано факти, перевіряє наявність `hasBunSqlImport`. Якщо `hasBunSqlImport` має значення `true`, повертає `true`.
+6.  **Перевірка залежностей `pg`:** Якщо надано факти, перевіряє наявність `pg`, `pg-format` або `mysql2` у залежностях. Якщо будь-яка з цих залежностей присутня, повертає `true`.
+7.  **Перевірка вкладеного `package.json` без `vite`:** Отримує кореневий `package.json`. Перебирає всі вкладені `package.json` (крім кореневого). Якщо вкладений `package.json` не містить `vite` у `devDependencies`, повер
+
+## Публічний API
+
+RULE_PREDICATES — Зберігає предикати та їх реалізації. Використовується для виклику через `meta.json.auto.predicate`.
+
+## Гарантії поведінки
+
+- Функція повертає результат виконання предиката.
+- Результат може бути істинним або хибним.
+- При виникненні помилки, результат завжди хибний.
+- Не враховує наявність `.git` та `node_modules` у файловій системі.
+- Не використовує кешування.
+- Не генерує винятків.
+- Аргументи предиката можуть бути значеннями, отриманими з файлів `meta.json`, шляхів у файловій системі або URL-адрес.
+- Результат залежить від вмісту та структури зазначених джерел.

package/scripts/lib/docs/run-conftest-batch.md

@@ -0,0 +1,26 @@
+# run-conftest-batch.mjs
+
+## Огляд
+
+Файл запускає `conftest test` на заданому списку файлів, виявляючи порушення правил, визначених у Rego-полісіях. Він використовується для автоматизованої перевірки конфігураційних файлів на відповідність заданим вимогам. Результати перевірки повертаються у структурованому вигляді, що дозволяє інтегрувати результати в інші процеси валідації.
+
+## Поведінка
+
+buildConftestArgs: Будує аргументи командного рядка для запуску `conftest test`, враховуючи список файлів, namespace та додаткові аргументи.
+runConftestBatch: Запускає `conftest test` для заданого списку файлів, повертає масив порушень у форматі JSON, якщо `conftest` успішно завершився, і кидає виняток, якщо `conftest` не знайдено або завершився з помилкою. Створює тимчасову директорію для збереження даних шаблону, якщо передано `templateData`.
+
+## Публічний API
+
+- buildConftestArgs: Створює аргументи для тесту conftest. Витягнуто для зручності тестування. Зберігає поточну структуру аргументів (файли перед `-p`, `--output json` та `--no-color` для читабельного виводу) і вставляє `--data` після `--namespace`, якщо він заданий.
+- runConftestBatch: Запускає `conftest test` для всіх файлів з одного процесу та повертає масив помилок. Якщо `files` порожній, повертає порожній масив. Якщо `conftest` не знайдено в системному шляху та автоматична установка не вдалася, виникає помилка.
+
+## Гарантії поведінки
+
+- Запускає `conftest test` на заданому списку файлів.
+- Повертає всі виявлені порушення у структурованому вигляді.
+- Якщо `conftest` не встановлено, намагається автоматично встановити його.
+- У разі невдачі встановлення `conftest`, завершує роботу з помилкою.
+- Не кидає винятків назовні.
+- Не використовує кешування.
+- Не перехоплює помилки, а завершує роботу з помилкою.
+- Не має взаємодії з мережею.

package/scripts/lib/docs/run-lint-step.md

@@ -0,0 +1,25 @@
+# run-lint-step.mjs
+
+## Огляд
+
+Цей файл забезпечує спільний хелпер для запуску окремих кроків у ланцюжку linting, що використовується CLI-обгортками. Він імітує прямий виклик команд у shell, логуючи команди та перенаправляючи stdout/stderr на користувацькі stream-и. Це дозволяє уникнути дублювання обгорток у різних `rules/<id>/js/lint.mjs` файлах.
+
+## Поведінка
+
+1.  Записує в лог повідомлення про початок виконання кроку ланцюжка з описом команди та її аргументів.
+2.  Визначає шлях до виконуваного файлу команди на основі її імені.
+3.  Якщо шлях не знайдено в системному PATH, записує повідомлення про помилку та повертає код 127.
+4.  Запускає визначену команду з заданими аргументами, передаючи стандартний потік введення/виведення (stdio) потокам користувача.
+5.  Якщо команда завершилася з помилкою, записує повідомлення про помилку та повертає код 1.
+6.  Якщо команда завершилася успішно, повертає код виходу дочірнього процесу, який дорівнює 0, якщо все добре, або 1, якщо виникла помилка.
+
+## Публічний API
+
+runLintStep — запускає процес linting та перевіряє його успішність.
+
+## Гарантії поведінки
+
+- Запускає один крок ланцюжка linting.
+- Перенаправляє stdout та stderr на користувацькі stream-и (stdio: 'inherit').
+- Не використовує кешування.
+- Не має внутрішніх приватних імен.

package/scripts/lib/docs/run-rule-cli.md

@@ -0,0 +1,27 @@
+# run-rule-cli.mjs
+
+## Огляд
+
+Цей файл є самостійним CLI-запускомком для правила, який дозволяє запускати правила з файлів `.n-cursor.json` та виконувати їхні дії. Він забезпечує інтеграцію з інструментом `cursor`, імітуючи старий `npx @nitra/cursor fix <id>`. Файл виконує перевірку whitelist, генерує summary та повертає агрегований код виходу.
+
+## Поведінка
+
+1.  Визначає ID правила на основі шляху директорії правила.
+2.  Зчитує конфігурацію з файлу `.n-cursor.json`.
+3.  Перевіряє, чи правило включено в конфігурації. Якщо ні, пропускає перевірку та повертає код успіху (0).
+4.  Виводить інформаційне повідомлення про початок перевірки правила.
+5.  Створює або отримує кеш для обходу файлової структури.
+6.  Запускає стандартний процес перевірки правила, передаючи кеш.
+7.  Отримує код завершення процесу перевірки правила.
+8.  Виводить підсумковий результат перевірки (успіх або невдача).
+9.  Повертає код завершення процесу перевірки правила.
+
+## Гарантії поведінки
+
+- Запускає правило з файлу `fix.mjs`.
+- Читає файл `.n-cursor.json` для конфігурації правила.
+- Перевіряє, чи правило включено в whitelist.
+- Виводить підсумкову інформацію про результат виконання.
+- Повертає код завершення, що відображає загальний статус виконання.
+- Кешує результати для уникнення повторного виконання, поки не змінено конфігурацію або не було перезапущено.
+- Не здійснює жодних мережевих запитів.

package/scripts/lib/docs/run-rule.md

@@ -0,0 +1,32 @@
+# run-rule.mjs
+
+## Огляд
+
+Цей файл є оркестратором правил, що запускається з командного рядка. Він застосовує правила, визначаючи та виконуючи концерни, а також політичні концерни, використовуючи кешування для підвищення ефективності. Файл забезпечує централізований спосіб виконання правил та збору результатів.
+
+## Поведінка
+
+- `runTemplateSubsetConcern`: Перевіряє файл-концерт за допомогою шаблону, повертаючи 0, якщо все ОК, або 1, якщо є порушення.
+- `evaluateAppliesGate`: Викликає функцію `applies` з `js/applies.mjs`, якщо вона існує та повертає `true`.
+- `runPolicyConcern`: Запускає policy-концерт через `runConftestBatch`, повертаючи 0, якщо все ОК, або 1, якщо є порушення.
+- `runRule`: Оркеструє правила, викликаючи `evaluateAppliesGate`, JS-концерни та policy-концерни, об'єднуючи exit-коди.
+
+## Публічний API
+
+- runTemplateSubsetConcern — Перевірка відповідності шаблонів: порівнює конфігурацію шаблонів з фактичним файлом, забезпечуючи дотримання правил.
+- runRule — Запуск правила: виконує послідовність дій, включаючи перевірку концернів, і застосовує політику.
+
+## Гарантії поведінки
+
+- `applies-гейт` викликає `applies` з `js/applies.mjs`.
+- `applies` повертає `false` — виводить `✅ правило не застосовне` і завершує.
+- `JS-концерни` викликають `applies` після `applies-гейт`.
+- `JS-концерни` можуть викликати `check` для виведення контексту.
+- `Policy-концерни` викликають `runConftestBatch`.
+- `resolveTargetFiles` кешує результати `walkCache` між `JS-концернами`.
+- `createCheckReporter` у `Policy-концерни` OR-ює exit-коди.
+- Exit-код правила — 0 або 1.
+- `runTemplateSubsetConcern` запускає підмножину шаблонів.
+- `runRule` запускає правило.
+- Кеш використовується для зберігання результатів `resolveTargetFiles` у межах прогону.
+- Немає взаємодії з мережею.

package/scripts/lib/docs/run-standard-lint.md

@@ -0,0 +1,22 @@
+# run-standard-lint.mjs
+
+## Огляд
+
+Файл забезпечує централізовану точку запуску для підкоманд `lint-<rule>` у `@nitra/cursor`. Він серіалізує та дедублює запуски, використовуючи `withLock`, щоб гарантувати узгодженість та ефективність. Це дозволяє легко інтегрувати нові правила та обробляти крос-cutting концерни, не вносячи змін у окремі файли правил.
+
+## Поведінка
+
+runLintFooCli: Запускає лінт для правила, використовуючи `runStandardLint`.
+runStandardLint: Серіалізує та дедуплікує запуск лінту, використовуючи блокування. Визначає ідентифікатор правила з шляху.
+
+## Публічний API
+
+- runLintFooCli — Перевіряє код на відповідність стандартам Foo CLI.
+- runStandardLint — Перевіряє код на відповідність загальним стандартам кодування.
+
+## Гарантії поведінки
+
+- Приймає `ruleId` з шляху файлу.
+- Створює блокування з іменем `lint-<ruleId>`.
+- Використовує попередньо збережені результати для уникнення повторного виконання.
+- Повертає результат виконання.

package/scripts/lib/docs/run-standard-rule.md

@@ -0,0 +1,24 @@
+# run-standard-rule.mjs
+
+## Огляд
+
+Цей файл забезпечує публічний інтерфейс для оркестрування правил. Він обігріває виклик `discoverOneRule` до виконання правил, керуючи їхнім виконанням на основі контексту та політики. Це централізована точка інтеграції для запуску правил, забезпечуючи дедуплікацію та кешування для оптимізації продуктивності.
+
+## Поведінка
+
+1.  Отримує шлях до директорії правила.
+2.  Визначає ідентифікатор правила з назви директорії.
+3.  Отримує дані правила з директорії правила.
+4.  Отримує або створює кеш для прогону.
+5.  Запускає виконання правила, використовуючи отримані дані та кеш.
+6.  Забезпечує унікальний лок для паралельного запуску правила.
+7.  Повертає код успіху (0) або код помилки (1) в залежності від результатів виконання правила.
+
+## Гарантії поведінки
+
+- Виконання правил інкапсулює логіку `discoverOneRule` та `runRule`.
+- Виконання правил відбувається всередині блоку `withLock`.
+- Виконання правил дедублюється на основі стану git-дерева.
+- Різні правила можуть виконуватися паралельно.
+- Кеш використовується для зберігання результатів виконання правил в межах одного прогону.
+- Не допускається локальна логіка всередині правил. Розширення поведінки реалізується через опції контексту.

package/scripts/lib/docs/skill-meta.md

@@ -0,0 +1,31 @@
+# skill-meta.mjs
+
+## Огляд
+
+Цей файл парсить метадані скілу з файлу `meta.json` та надає інформацію про його конфігурацію. Він служить єдиним джерелом правди про скіл, замінюючи старий `auto.md`, і використовується для визначення, чи потрібно запускати скіл в окремому worktree, чи з кореня репозиторію. Це забезпечує узгодженість даних про скіли та полегшує їх використання в інших частинах системи.
+
+## Поведінка
+
+SKILL_ALWAYS: визначає літерал для безумовної автоактивації.
+parseSkillAutoSpec: перетворює значення `auto` з `meta.json` у об’єкт `SkillAutoSpec`.
+skillRequiresRoot: визначає, чи вимагає скіл запуску з кореня репо.
+readSkillMetaRaw: читає та парсить `meta.json` одного скіла, повертаючи розпарсений об’єкт або `null`.
+
+## Публічний API
+
+- SKILL_ALWAYS — Активує скіл завжди.
+- parseSkillAutoSpec — Перетворює специфікацію авто-скілу з JSON.
+- skillRequiresRoot — Перевіряє, чи потрібен скілу доступ до кореневої директорії.
+- readSkillMetaRaw — Зчитує та аналізує метадані скілу з файлу JSON.
+
+## Гарантії поведінки
+
+- Повертає `false` якщо не вдається розібрати `meta.json`.
+- Повертає `null` якщо не вдається визначити `auto.spec`.
+- `auto.spec` завжди є масивом id правил, якщо `auto.spec` визначено.
+- `worktree` має значення `true` лише для скілів, які потребують окремого git-worktree.
+- `requireRoot` має значення `true` лише для скілів, які мутують в CWD без worktree-ізоляції.
+- Якщо `worktree` має значення `true`, поле `requireRoot` не використовується.
+- Не використовує кеш.
+- Не кидає винятків.
+- Гарантує, що `meta.json` є єдиним джерелом правди для скілу.

package/scripts/lib/docs/sync-gitignore-worktree.md

@@ -0,0 +1,31 @@
+# sync-gitignore-worktree.mjs
+
+## Огляд
+
+Файл забезпечує, що кореневий `.gitignore` проєкту ігнорує локальні git-worktree. Він гарантує, що всі артефакти, пов'язані з worktree, правильно включені в `.gitignore`, забезпечуючи консистентність та уникнення непередбачуваних проблем. Це ключовий компонент системи завжди-активного flow/worktree-tooling.
+
+## Поведінка
+
+1.  Визначає корінь проєкту.
+2.  Перевіряє наявність в кореневому файлі `.gitignore` запису, що відповідає каталогу `.worktrees/`.
+3.  Якщо запису немає, викликає утиліту для додавання запису `.worktrees/` до `.gitignore`.
+4.  Утиліта додає запис, якщо його ще немає, інакше не робить нічого.
+5.  Повертає значення `true`, якщо запис було додано, інакше `false`.
+
+## Публічний API
+
+syncGitignoreWorktree — Синхронізує файл `.gitignore` в каталозі `worktrees` з кореневим файлом `.gitignore`.
+
+## Гарантії поведінки
+
+- Гарантує, що кореневий `.gitignore` проєкту ігнорує локальні git-worktree (`.worktrees/`).
+- Викликається з дефолтного sync (`npx \@nitra/cursor`) окремим top-level кроком.
+- Не викликається в контексті `syncClaudeConfig`.
+- `.worktrees/` є артефактом завжди-активного flow/worktree-tooling.
+- Один запис `.worktrees/` покриває каталог worktree та всі sibling-файли в ньому.
+- Запис безумовний, без гейта за `.n-cursor.json`-правилами.
+- Продюсер артефактів — завжди-активний flow.
+- Делегує наявній idempotent+append-only утиліті `ensureGitignoreEntries`.
+- `ensureGitignoreEntries` не перезаписує/не видаляє наявні рядки.
+- `ensureGitignoreEntries` створює `.gitignore`, якщо нема.
+- Не використовує кешування.