@nitra/cursor 3.27.0 → 3.28.0

package/rules/security/js/sample_secret.mjs

@@ -1,31 +1,4 @@
-/**
- * FS-частина правила `security`: concern `sample_secret`.
- *
- * Перевіряє, що фейкові credential-значення у *прикладних* файлах записані як
- * канонічний placeholder `sample-secret`, а не як bare `secret`.
- *
- * `sample-secret` містить підрядок `sample`, який є у вшитому списку
- * `DefaultFalsePositives` TruffleHog — таке значення сканер відсіює
- * гарантовано й незалежно від версії. Bare `secret` наразі не фіксується сканером
- * лише тому, що випадково присутнє у словнику `fp_words.txt`; це крихка поведінка,
- * що залежить від версії інструмента, на яку не варто покладатися.
- *
- * Прикладними вважаються файли, чий basename має суфікс `.example` / `.sample`
- * / `.template` / `.dist` або infix `.example.` / `.sample.` / `.template.`, а
- * також будь-які файли всередині каталогів `fixtures` / `fixture` /
- * `__fixtures__`. Решта файлів не сканується — там `secret` майже завжди
- * частина реального коду, а не placeholder.
- *
- * Порушенням є лише `secret` у *позиції значення* — одразу після `=`, `:` чи
- * `=>` (з опційними лапками). Імена ключів (`client_secret`, `JWT_SECRET`) не
- * чіпаються: матч прив'язаний до значення, не до ключа.
- *
- * Чому regex, а не AST: прикладні файли — різнорідні конфіги (`.env`, YAML,
- * JSON, TOML, plain `.dist`), єдиного AST для них немає, тож скан порядковий.
- * Чому JS, а не Rego: щоб знайти прикладні файли, треба обійти дерево
- * (`readdir`), а вміст — неструктурований текст (conftest парсить лише
- * структуровані документи).
- */
+/** @see ./docs/sample_secret.md */
 import { readFile } from 'node:fs/promises'
 import { relative, sep } from 'node:path'
 

package/rules/security/js/trufflehog.mjs

@@ -1,11 +1,4 @@
-/**
- * FS-частина правила `security`.
- *
- * Перевіряє:
- *  - наявність `package.json` (структуру валідує policy security.package_json);
- *  - наявність `.trufflehog-exclude` у корені та subset канонічних patterns
- *    (text-subset, бо `.trufflehog-exclude` — plain text, не структурований).
- */
+/** @see ./docs/trufflehog.md */
 import { existsSync } from 'node:fs'
 import { readFile } from 'node:fs/promises'
 import { dirname, join } from 'node:path'

package/rules/style-lint/js/lint.mjs

@@ -1,8 +1,4 @@
-/**
- * Quick-крок lint правила style-lint: stylelint --fix по css/scss/vue.
- *
- * `files` (quick) → лише style-файли з них; undefined (ci) → весь glob `**\/*.{css,scss,vue}`.
- */
+/** @see ./docs/lint.md */
 import { spawnSync } from 'node:child_process'
 
 const STYLE_EXT_RE = /\.(?:css|scss|vue)$/u

package/rules/style-lint/js/tooling.mjs

@@ -1,22 +1,4 @@
-/**
- * Перевіряє CSS/SCSS лінт за правилом style-lint.mdc.
- *
- * **Що тут лишилося** (FS / cross-file — не покривається conftest):
- *  - наявність зовнішнього файлу конфігу stylelint (`.stylelintrc.*`,
- *    `stylelint.config.js`) як альтернатива полю `stylelint` у `package.json`
- *    (cross-file: треба знати, чи є поле, чи немає);
- *  - `.stylelintignore` у корені.
- *
- * **Що покрила Rego** (`npx \@nitra/cursor check`):
- *  - `npm/policy/style_lint/package_json/` — скрипт `lint-style` через `npx stylelint`,
- *    `@nitra/stylelint-config` у `devDependencies`, поле `stylelint.extends`;
- *  - `npm/policy/style_lint/lint_style_yml/` — `npx stylelint` у `run` workflow;
- *  - `npm/policy/style_lint/vscode_extensions/` — `stylelint.vscode-stylelint`
- *    у `recommendations` `.vscode/extensions.json`;
- *  - `npm/policy/style_lint/vscode_settings/` — `css.validate`/`scss.validate`/
- *    `less.validate: false` у `.vscode/settings.json`.
- * @param {string} cwd корінь репозиторію
- */
+/** @see ./docs/tooling.md */
 import { existsSync } from 'node:fs'
 import { readFile } from 'node:fs/promises'
 import { join } from 'node:path'

package/rules/tauri/js/cargo_mutants_config.mjs

@@ -1,23 +1,4 @@
-/**
- * Концерн `cargo_mutants_config` правила tauri (tauri.mdc): для кожного
- * `<workspace>/src-tauri/Cargo.toml` без дублювання гарантує наявність
- * Tauri-specific cargo-mutants налаштувань у `<workspace>/src-tauri/.cargo/mutants.toml`.
- *
- * Семантика (фіксована між Tauri-проєктами):
- *   - `src/main.rs` — binary shell entrypoint (smoke/e2e, не mutation unit);
- *   - `src/**\/{android,ios,mobile}.rs` — mobile plugin bridge / platform glue;
- *   - `src/**\/{macos,windows,linux,desktop}.rs` — desktop platform bridge / OS integration glue.
- *
- * Self-gating: silently skip, якщо в monorepo не знайдено жодного
- * `<ws>/src-tauri/Cargo.toml` (test rule сам створить нейтральний baseline там,
- * де потрібно).
- *
- * Ідемпотентність:
- *   - якщо файл відсутній — створює з Tauri-canonical baseline;
- *   - якщо файл існує і всі канонічні ключі вже є — `manual cargo-mutants config preserved`;
- *   - якщо файл існує, але якихось канонічних top-level ключів немає — додає
- *     лише відсутні ключі окремим блоком у кінці; існуючих значень не торкається.
- */
+/** @see ./docs/cargo_mutants_config.md */
 import { existsSync } from 'node:fs'
 import { mkdir, readFile, writeFile } from 'node:fs/promises'
 import { dirname, join, relative } from 'node:path'

package/rules/tauri/js/tooling.mjs

@@ -1,24 +1,4 @@
-/**
- * Перевіряє інструментарій Tauri (tauri.mdc): VSCode `extensions.json` для
- * проєктів, у яких є маркер Tauri.
- *
- * Cross-file gating (JS):
- *   1. Tauri-маркер визначаємо обходом усіх workspace-пакетів через
- *      `getMonorepoPackageRootDirs()` (корінь + workspaces). Кожен workspace
- *      перевіряється за **будь-яким** з:
- *      - існує каталог `<ws>/src-tauri/`;
- *      - існує файл `<ws>/src-tauri/Cargo.toml`;
- *      - існує файл `<ws>/src-tauri/tauri.conf.json`;
- *      - існує файл `<ws>/tauri.conf.json` (legacy flat-layout);
- *      - `<ws>/package.json#dependencies` чи `devDependencies` містить ключ
- *        з префіксом `@tauri-apps/`.
- *   2. Якщо маркера немає — пропустити перевірку (tauri-tooling не вимагається).
- *   3. Інакше — для `.vscode/extensions.json` зробити FS-existence + делегувати
- *      content `rego.tauri.vscode_extensions` через `runConftestBatch`.
- *
- * Rego-полісі глобально без `target.json` поруч (не auto-discoverable через `n-cursor fix`) — це conditional
- * правило. Plan B: Rego-authoritative + JS-orchestrator з `runConftestBatch`.
- */
+/** @see ./docs/tooling.md */
 import { existsSync, statSync } from 'node:fs'
 import { readFile } from 'node:fs/promises'
 import { join } from 'node:path'

package/rules/test/js/cargo_mutants_config.mjs

@@ -1,15 +1,4 @@
-/**
- * Концерн `cargo_mutants_config` правила test (test.mdc): якщо `rust` присутнє
- * в `.n-cursor.json#rules` і не у `disable-rules` — визначає ВСІ Cargo.toml
- * (cwd і всі workspaces, з підтримкою Tauri-патерну) і копіює canonical
- * baseline `.cargo/mutants.toml` у каталог кожного manifest'а, якщо файлу немає.
- *
- * Self-gating: концерн silently skips коли `rust` не enabled.
- * Якщо `rust` enabled, але жодного Cargo.toml не знайдено — теж silently skip
- * (manifest може з'явитися пізніше; це не помилка).
- *
- * Baseline — порожній файл з коментарем; cargo-mutants має робочі defaults.
- */
+/** @see ./docs/cargo_mutants_config.md */
 import { existsSync } from 'node:fs'
 import { copyFile, mkdir } from 'node:fs/promises'
 import { dirname, join, relative } from 'node:path'

package/rules/test/js/location.mjs

@@ -1,12 +1,4 @@
-/**
- * Перевіряє, що всі `*.test.mjs` лежать у каталозі `tests/` (а не поряд із джерельним файлом).
- *
- * Конвенція (test.mdc): `dir/foo.mjs` → тест у `dir/tests/foo.test.mjs`.
- * `*_test.rego` виключені: Rego unit-тести живуть поряд із полісі (OPA community convention).
- *
- * Пропускає: `node_modules`, `.git`, `dist`, `build`, `.venv`, `venv` (через `walkDir`)
- * і шляхи з `.n-cursor.json:ignore`.
- */
+/** @see ./docs/location.md */
 import { basename, dirname, relative } from 'node:path'
 
 import { createCheckReporter } from '../../../scripts/lib/check-reporter.mjs'

package/rules/test/js/no-process-chdir.mjs

@@ -1,24 +1,4 @@
-/**
- * Заборона `process.chdir(...)` у тестах.
- *
- * Контекст (test.mdc, секція "Заборона `process.chdir` у тестах"):
- * `process.chdir` — process-wide мутація. Vitest за замовчуванням ставить
- * `pool: 'threads'`, де workers ділять один процес: паралельний test file
- * може перехопити cwd сусіда посеред FS- або `git`-операції. Реальний
- * інцидент — `git init`+`git commit` із tmp-фікстури `withTmpCwd` потрапив у
- * реальний робочий репозиторій і створив rogue commit з автором `test
- * <test@test>`. Тому канон: `withTmpDir(async dir => ...)` зі
- * `scripts/utils/test-helpers.mjs` (без `chdir`) + явні `cwd: dir` у child-
- * процесах + `await check(dir)` для concern-функцій.
- *
- * Цей concern сканує `**\/*.test.{js,mjs}` і падає на будь-яке вживання
- * `process.chdir(`. Виняток — коментарі/документація: regex знаходить лише
- * викликний паттерн (відкривна дужка), тож згадки у JSDoc типу
- * "не використовуй `process.chdir`" не тригерять.
- *
- * Скіпи: `node_modules`, `.git`, `dist`, `build`, `.venv`, `venv` (через
- * `walkDir`) і шляхи з `.n-cursor.json:ignore`.
- */
+/** @see ./docs/no-process-chdir.md */
 import { readFile } from 'node:fs/promises'
 import { basename, relative } from 'node:path'
 

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

@@ -1,26 +1,4 @@
-/**
- * Заборона **relative-path** аргументів у FS-функціях усередині тестів.
- *
- * Контекст (test.mdc, секція "Заборона `process.chdir` у тестах"):
- * Після видалення `withTmpCwd` усі тести отримують `dir` параметром і мають
- * будувати **абсолютні** шляхи через `join(dir, …)`. Якщо хтось забуде префікс
- * і напише `writeFile('foo.json', …)` чи `copyFile(src, 'foo.json')` —
- * relative-path резолвиться у `process.cwd()` (= `npm/`), що зливає тестову
- * фікстуру у production tree. Інцидент v1.28.0: `tests/check-rule-fixtures.test.mjs`
- * залишив `copyFile(src, 'values-dev.ini')` і `copyFile(src, 'default.conf.template')` —
- * створило файли `npm/values-dev.ini` і `npm/default.conf.template`.
- *
- * Сканер AST-based (oxc-parser): знаходить виклики `node:fs`/`node:fs/promises`
- * функцій із **string literal** аргументом-шляхом, який НЕ починається з:
- *   - `/`, `\\` — POSIX/Windows absolute;
- *   - `file:`/`http`/`data:` — URL-схема (передається до `new URL(...)`);
- *   - `${…}` (template-literal з виразом) і `\`…\${dir}\`` патерни — обчислений шлях;
- *   - `:` для Windows-літер диску `C:\…` (рідко в тестах, але legit).
- * Виклики, чий path-аргумент — НЕ literal (CallExpression `join(...)`, BinaryExpression,
- * Identifier, MemberExpression) — пропускаємо: припускаємо що це абсолютний шлях.
- *
- * Скани: `**\/*.test.{js,mjs}` з загальними `walkDir` skip + `.n-cursor.json#ignore`.
- */
+/** @see ./docs/no-relative-fs-path.md */
 import { readFile } from 'node:fs/promises'
 import { basename, relative } from 'node:path'
 

package/rules/test/js/stryker_config.mjs

@@ -1,27 +1,4 @@
-/**
- * Концерн `stryker_config` правила test (test.mdc): якщо `js-lint` присутнє в
- * `.n-cursor.json#rules` і не у `disable-rules` — визначає ВСІ JS-roots
- * (всі workspaces з package.json, або cwd у single-package) і копіює canonical
- * baseline `stryker.config.mjs` + `vitest.config.js` у кожен root, де файлу немає.
- *
- * Для JS-roots із `.vue` файлами (Vue 3 + `<script setup>`) копіюється vue-варіант
- * baseline, який реєструє локальний Ignore-плагін `vue-macros` — інакше Stryker
- * огортає виклики `defineProps`/`defineEmits`/... у coverage-тернарник і
- * `@vue/compiler-sfc` падає при компіляції SFC. Плагін копіюється у той самий
- * jsRoot як `stryker-vue-macros-ignorer.mjs`.
- *
- * Augment (drift-hole): якщо у Vue-root `stryker.config.mjs` уже існував (проєкт
- * мав non-vue config ще до 3.x Vue-підтримки), `ensureBaselineFile` його не
- * перетирає — тож `augmentVueStrykerConfig` точково вставляє `plugins`/`ignorers`
- * у наявний файл (string-splice за AST-аналізом), зберігаючи решту полів і
- * коментарів. Idempotent: повторний прогон нічого не дублює.
- *
- * Self-gating: концерн silently skips коли `js-lint` не enabled — це навмисно,
- * щоб не шуміти у single-language проєктах без JS coverage tooling.
- *
- * Baseline — мінімум для запуску Stryker з vitest-runner + perTest; mutate-патерни
- * лишаються на Stryker defaults (`src/**\/*.{js,mjs,ts,jsx,tsx,cjs}`).
- */
+/** @see ./docs/stryker_config.md */
 import { existsSync } from 'node:fs'
 import { copyFile, glob, readFile, writeFile } from 'node:fs/promises'
 import { dirname, join, relative } from 'node:path'
@@ -310,7 +287,9 @@ async function augmentVueStrykerConfig(reporter, cwd, jsRoot) {
   try {
     recheck = parseSync(target, next, { lang: 'js', sourceType: 'module' })
   } catch (error) {
-    reporter.fail(`stryker.config.mjs: augment дав некоректний результат (${rel}): ${error.message} — відкат, додай вручну`)
+    reporter.fail(
+      `stryker.config.mjs: augment дав некоректний результат (${rel}): ${error.message} — відкат, додай вручну`
+    )
     return
   }
   if (recheck.errors?.length) {

package/rules/test/js/vitest-config-pool-forks.mjs

@@ -1,20 +1,4 @@
-/**
- * `vitest.config.js` має ставити `pool: 'forks'` — defense-in-depth для
- * race-bug у `process.cwd()` (test.mdc, секція "Заборона `process.chdir` у тестах").
- *
- * Чому не достатньо самої заборони `process.chdir(`: third-party код у залежностях
- * може робити chdir всередині vitest worker'а. У `pool: 'threads'` (default) усі
- * workers ділять один процес → race на `process.cwd()` між паралельними test
- * files. `pool: 'forks'` ізолює кожен test file у власному child-процесі.
- *
- * Перевірка — substring у source-тексті `vitest.config.js`. Не парсимо JS AST,
- * бо це може бути будь-який export-формат (ESM default, named, CommonJS).
- * Достатньо знайти `pool:` із значенням `'forks'`/`"forks"` (whitespace дозволений).
- *
- * Скіпи: правило не застосовне, якщо `vitest.config.js` не існує (нема vitest
- * у проєкті) — це не помилка, лише skip. Якщо файл є — `pool: 'forks'`
- * обов'язковий.
- */
+/** @see ./docs/vitest-config-pool-forks.md */
 import { existsSync } from 'node:fs'
 import { readFile } from 'node:fs/promises'
 import { join } from 'node:path'

package/rules/text/js/forbidden-prettier.mjs

@@ -1,13 +1,4 @@
-/**
- * Suspect FS-перевірка: жоден Prettier-артефакт у корені проєкту не дозволений.
- *
- * `text.mdc` забороняє `prettier`, `@nitra/prettier-config` і всі прояви Prettier-конфігів.
- * Rego-полісі `text.package_json` ловить scripts/dependencies/devDependencies; цей concern
- * ловить FS-сторону — конфіги й ignore-файли, які runner Prettier зчитує автоматично.
- *
- * Список синхронізовано з конфіг-форматами Prettier 3.x
- * (https://prettier.io/docs/configuration). Якщо Prettier додасть новий формат — додай рядок.
- */
+/** @see ./docs/forbidden-prettier.md */
 import { existsSync } from 'node:fs'
 import { join } from 'node:path'
 

package/rules/text/js/formatting.mjs

@@ -1,34 +1,4 @@
-/**
- * Перевіряє текстовий стек і форматування за правилом text.mdc.
- *
- * **Що тут лишилося** (FS / VSCode-конфіги / markdown / лінт-скрипт):
- *  - `.v8rignore` (текстовий формат, рядки шляхів);
- *  - `.vscode/extensions.json` рекомендації (markdownlint, oxc, shellcheck) і
- *    `.vscode/settings.json` (`editor.formatOnSave`, `[lang].editor.defaultFormatter`);
- *  - наявність FS-файлів `.oxfmtrc.json`, `.cspell.json`, `.markdownlint-cli2.jsonc`,
- *    `package.json` (саме *існування* — структуру вже валідує Rego);
- *  - абзац про український апостроф у `.cursor/rules/n-text.mdc` /
- *    `npm/mdc/text.mdc` (markdown-текст, не JSON/YAML);
- *  - складна валідація скрипта `lint-text` (cspell, markdownlint, v8r у трьох
- *    варіантах, run-shellrules/text/fix.mjs, обовʼязкові glob-и);
- *  - workflow `lint-text.yml` має крок `bun run lint-text` (структура — rego `text.lint_text`).
- *
- * **Що покрила Rego** (`npx \@nitra/cursor check`):
- *  - `npm/policy/text/oxfmtrc/` — обовʼязкові ключі `.oxfmtrc.json` і канонічні
- *    значення (semi/singleQuote/tabWidth/useTabs/printWidth) + `ignorePatterns`
- *    канонічні glob-и;
- *  - `npm/policy/text/cspell/` — `.cspell.json` `version "0.2"`, `language`,
- *    імпорт `@nitra/cspell-dict`, заборона `@cspell/dict-*`, обовʼязкові
- *    `ignorePaths`;
- *  - `npm/policy/text/markdownlint/` — `.markdownlint-cli2.jsonc` `gitignore: true`
- *    (працює лише якщо файл — валідний JSON без коментарів);
- *  - `npm/policy/text/package_json/` — заборона Prettier (`prettier` поле +
- *    `prettier`/`@nitra/prettier-config` у залежностях), `@nitra/cspell-dict ^2.0.0+`
- *    у `devDependencies`, заборона `markdownlint-cli2` у залежностях.
- *  - `npm/policy/bun/package_json/` — у `devDependencies` лише `@nitra/*`
- *    (раніше дублювалося тут).
- * @param {string} cwd корінь репозиторію
- */
+/** @see ./docs/formatting.md */
 import { existsSync } from 'node:fs'
 import { readFile } from 'node:fs/promises'
 import { join } from 'node:path'

package/rules/vue/js/packages.mjs

@@ -1,27 +1,4 @@
-/**
- * Знаходить пакети з `vue` у dependencies і перевіряє їх за правилом vue.mdc.
- *
- * Вміст `vite.config`, editor-файли для Vite client types, у репозиторії —
- * рекомендацію розширення Vue.volar.
- *
- * Залежності Vue/Vite (`vite >= 8`, `@vitejs/plugin-vue`, `vue-macros`,
- * `unplugin-auto-import`, `vite-plugin-vue-layouts-next`, заборона `esbuild`) —
- * у policy `vue.package_json`.
- *
- * У кожному Vue+Vite-пакеті очікується `src/vite-env.d.ts` з `/// <reference types="vite/client" />`
- * та `jsconfig.json` у корені пакета (типи для імпортів асетів у `.vue`).
- *
- * У `vite.config.*` заборонено використовувати `process.env.npm_lifecycle_event` (Bun не підставляє його як npm),
- * натомість використовуй `mode` з `defineConfig(({ mode }) => ...)`.
- *
- * Заборонені явні value-імпорти з `vue` у джерелах пакета — сканування `.vue`/`.ts`/`.js` тощо
- * через **oxc-parser** (`module.staticImports`; див. `./vue-forbidden-imports.mjs`); дозволені лише type-only та side-effect `import 'vue'`.
- *
- * Окремо в `.vue` SFC заборонено імпорти Node-нативних модулів — `node:*` префікс або bare-ім’я
- * вбудованого модуля Node (`fs`, `path`, `timers/promises` тощо). Vue SFC виконується у браузері,
- * де Node API недоступне; такий код треба тримати у server-side утілітах.
- * @param {string} cwd корінь репозиторію
- */
+/** @see ./docs/packages.md */
 import { existsSync } from 'node:fs'
 import { readFile } from 'node:fs/promises'
 import { join, relative } from 'node:path'

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.
+- Не має кешування.