@nitra/cursor 1.6.27 → 1.8.1

package/README.md

@@ -4,7 +4,7 @@
 
 ## Як це працює
 
-Репозиторій `@nitra/cursor` містить cursor-правила у директорії `mdc/`. CLI завантажує обрані правила з npm (через unpkg.com) і копіює їх у `.cursor/rules/` поточного проекту з префіксом `n-`.
+Репозиторій `@nitra/cursor` містить cursor-правила у директорії `mdc/`. CLI копіює обрані правила з **каталогу `mdc/` того пакету, з якого виконується `bin/n-cursor.js`**: після `npm i` / `bun add` це зазвичай `node_modules/@nitra/cursor/mdc`; при **`npx @nitra/cursor`** пакет потрапляє в **кеш npx/npm**, і правила читаються з тієї розпакованої копії (у корені проєкту залежність не обов’язкова). Жодних окремих HTTP-запитів до CDN для файлів правил немає — лише те, що вже є в tarball пакету.
 
 Наприклад, правило `mdc/js-format.mdc` буде збережено як `.cursor/rules/n-js-format.mdc`.
 
@@ -28,16 +28,7 @@
 | `npm-module` | Структура репозиторію для npm-модуля (bun mono)   |
 | `text`       | Текстові файли: cspell, CI                        |
 
-Щоб завантажити правила конкретної версії пакету, додайте поле `version`:
-
-```json
-{
-  "$schema": "https://unpkg.com/@nitra/cursor/schemas/n-cursor.json",
-  "version": "2.5.0",
-  "rules": ["js-format", "text"],
-  "skills": ["fix"]
-}
-```
+Щоб використовувати конкретну версію правил, оновіть залежність `@nitra/cursor` у проєкті (`bun add -d @nitra/cursor@<версія>` тощо). Поле `version` у `.n-cursor.json`, якщо воно лишилось у старих конфігах, **ігнорується**.
 
 ### v8r і власний каталог схем
 
@@ -57,7 +48,7 @@ CLI автоматично (команда завантаження правил
 
 1. Знайде або створить `.n-cursor.json` у поточній директорії (із полем `$schema` на JSON Schema пакету; якщо файл уже є без коректного `$schema`, поле буде додано або оновлено при зчитуванні конфігу)
 2. Створить директорію `.cursor/rules/`, якщо її ще немає
-3. Завантажить кожне з перелічених у конфігу правило з unpkg.com і збереже файли з префіксом `n-`
+3. Скопіює кожне з перелічених у конфігу правило з `mdc/` установленого пакету і збереже файли з префіксом `n-`
 4. Після оновлення файлів на диску згенерує в корені проєкту **`AGENTS.md`**: повний вміст береться з шаблону пакету `AGENTS.template.md`, а список правил у шаблоні формується з **усіх наявних файлів `*.mdc`** у `.cursor/rules/` (відсортовано за ім’ям)
 
 ## Приклад виводу

package/bin/n-cursor.js

@@ -12,7 +12,7 @@
  * Якщо у корені репозиторію немає .n-cursor.json, спочатку перейменовується за наявності nitra-cursor.json;
  * у `.cursor/rules` файли `nitra-*.mdc` перейменовуються на `n-*.mdc`; інакше конфіг створюється автоматично
  * з усіма правилами з каталогу mdc пакету (їх можна відредагувати після створення). У файлі завжди має бути
- * поле `$schema` з посиланням на JSON Schema пакету; при зчитуванні конфігу воно додається або виправляється на диску, якщо відсутнє або некоректне.
+ * поле `$schema` з посиланням на JSON Schema пакету (публічний URL для IDE); при зчитуванні конфігу воно додається або виправляється на диску, якщо відсутнє або некоректне.
  *
  * Файл AGENTS.md у корені: щоразу повністю перезаписується змістом з AGENTS.template.md
  * пакету; список правил у шаблоні будується з файлів *.mdc у .cursor/rules поточного проєкту.
@@ -20,10 +20,16 @@
  * Після завантаження: у .cursor/rules видаляються файли *.mdc з префіксом «n-» (керовані
  * пакетом), яких немає у списку rules у .n-cursor.json. Інші .mdc у цій директорії залишаються.
  *
+ * Composite GitHub Action `.github/actions/setup-bun-deps/action.yml` копіюється з каталогу
+ * `github-actions/` пакету при кожному успішному синку (workflows з правил ga / js-lint / text).
+ *
  * Skills копіюються з npm/skills пакету лише для id з масиву «skills» у .n-cursor.json
  * (у JSON — без префікса, каталоги в проєкті — n-<id>, як і для правил). Якщо ключа skills
  * немає, за замовчуванням підтягуються всі bundled skills з префіксом n- у пакеті.
  * Зайві каталоги n-* у .cursor/skills, яких немає у списку, видаляються.
+ *
+ * Якщо в корені є package.json і в ньому ще немає \@nitra/cursor у devDependencies (і не оголошено
+ * в dependencies), CLI дописує devDependencies з діапазоном ^<version> поточного пакету — зручно після npx.
  */
 
 import { existsSync } from 'node:fs'
@@ -32,11 +38,16 @@ import { basename, dirname, join } from 'node:path'
 import { cwd } from 'node:process'
 import { fileURLToPath } from 'node:url'
 
+import {
+  ensureNitraCursorInRootDevDependencies,
+  readBundledPackageVersion
+} from '../scripts/ensure-nitra-cursor-dev-dependencies.mjs'
+import { syncSetupBunDepsAction } from '../scripts/sync-setup-bun-deps-action.mjs'
+
 const PACKAGE_NAME = '@nitra/cursor'
-const UNPKG_BASE = 'https://unpkg.com'
 const CONFIG_FILE = '.n-cursor.json'
-/** URL JSON Schema для `.n-cursor.json` (поле `$schema` у файлі конфігурації) */
-const CONFIG_SCHEMA_URL = `${UNPKG_BASE}/${PACKAGE_NAME}/schemas/n-cursor.json`
+/** Публічний URL JSON Schema для поля `$schema` у `.n-cursor.json` (IDE); вміст правил CLI читає лише з диска пакету */
+const CONFIG_SCHEMA_URL = 'https://unpkg.com/@nitra/cursor/schemas/n-cursor.json'
 const AGENTS_FILE = 'AGENTS.md'
 const AGENTS_TEMPLATE_FILE = 'AGENTS.template.md'
 const RULES_DIR = '.cursor/rules'
@@ -48,6 +59,8 @@ const BUNDLED_MDC_DIR = join(binDir, '..', 'mdc')
 const BUNDLED_SCRIPTS_DIR = join(binDir, '..', 'scripts')
 const BUNDLED_SKILLS_DIR = join(binDir, '..', 'skills')
 const BUNDLED_AGENTS_TEMPLATE_PATH = join(binDir, '..', AGENTS_TEMPLATE_FILE)
+/** Корінь установленого пакету (каталог з `mdc/`, `github-actions/`, …) */
+const BUNDLED_PACKAGE_ROOT = join(binDir, '..')
 
 /**
  * Імена правил (без .mdc) з каталогу mdc поточної інсталяції пакету
@@ -87,19 +100,6 @@ async function discoverBundledSkillNames() {
     .toSorted((a, b) => a.localeCompare(b))
 }
 
-/**
- * Завантажує текст з URL
- * @param {string} url адреса HTTP(S)
- * @returns {Promise<string>} тіло відповіді як UTF-8 текст
- */
-async function fetchText(url) {
-  const response = await fetch(url)
-  if (!response.ok) {
-    throw new Error(`HTTP ${response.status} — не вдалося завантажити: ${url}`)
-  }
-  return response.text()
-}
-
 /**
  * Перейменовує у каталозі правил файли `nitra-*.mdc` → `n-*.mdc`. Якщо `n-*.mdc` уже є, застарілий файл видаляється.
  * @param {string} rulesDir абсолютний шлях до `.cursor/rules`
@@ -148,7 +148,7 @@ async function migrateLegacyConfigIfNeeded() {
 
 /**
  * Зчитує конфіг .n-cursor.json з поточної директорії
- * @returns {Promise<{ $schema: string, rules: string[], skills: string[], version?: string } & Record<string, unknown>>} rules, skills (id без префікса n-), опційно version; при відсутності файлу створює дефолтний конфіг
+ * @returns {Promise<{ $schema: string, rules: string[], skills: string[], version?: string } & Record<string, unknown>>} rules, skills (id без префікса n-); поле version у файлі за наявності ігнорується при синхронізації правил
  */
 async function readConfig() {
   await migrateLegacyConfigIfNeeded()
@@ -191,18 +191,6 @@ async function readConfig() {
   return config
 }
 
-/**
- * Повертає URL для завантаження правила з unpkg
- * @param {string} ruleName - ім'я без розширення, наприклад "js-format"
- * @param {string} [version] - версія пакету (необов'язково, за замовчуванням "latest")
- * @returns {string} повний URL файлу правила на unpkg
- */
-function buildUrl(ruleName, version) {
-  const name = ruleName.endsWith('.mdc') ? ruleName : `${ruleName}.mdc`
-  const ver = version ? `@${version}` : '@latest'
-  return `${UNPKG_BASE}/${PACKAGE_NAME}${ver}/mdc/${name}`
-}
-
 /**
  * Витягує чисте ім'я файлу правила (без шляху, але зберігає .mdc)
  * "npm/mdc/js-format.mdc" → "js-format.mdc"
@@ -215,6 +203,22 @@ function normalizeRuleName(ruleName) {
   return basename(name)
 }
 
+/**
+ * Читає вміст правила з каталогу `mdc/` установленого пакету (наприклад `node_modules/@nitra/cursor/mdc` або кеш npx).
+ * @param {string} rule елемент масиву rules з `.n-cursor.json`
+ * @returns {Promise<string>} текст правила для запису в `.cursor/rules/n-*.mdc`
+ */
+function readBundledRuleContent(rule) {
+  const bundledName = normalizeRuleName(rule)
+  const bundledPath = join(BUNDLED_MDC_DIR, bundledName)
+  if (!existsSync(bundledPath)) {
+    throw new Error(
+      `Немає файлу ${bundledName} у ${BUNDLED_MDC_DIR}. Оновіть ${PACKAGE_NAME} або приберіть "${rule}" з rules у ${CONFIG_FILE}.`
+    )
+  }
+  return readFile(bundledPath, 'utf8')
+}
+
 /**
  * Нормалізує id skill з конфігу до форми без префікса n- (як «fix»)
  * @param {string} skillName елемент масиву skills або ім'я каталогу
@@ -618,7 +622,7 @@ async function runChecks(requestedRules) {
 }
 
 /**
- * Завантажує правила з npm та синхронізує локальні файли
+ * Копіює правила з каталогу `mdc/` установленого пакету та синхронізує `.cursor/rules`
  * @returns {Promise<void>}
  */
 async function runSync() {
@@ -633,12 +637,24 @@ async function runSync() {
   }
 
   const { rules, skills, version } = config
+  const bundledVer = await readBundledPackageVersion()
+  if (bundledVer) {
+    console.log(`📦 Джерело правил: ${PACKAGE_NAME}@${bundledVer}`)
+  }
   if (version) {
-    console.log(`📦 Версія пакету: ${version}`)
+    console.log(`⚠️  Поле "version" у ${CONFIG_FILE} ігнорується; правила беруться з установленого пакету.\n`)
   }
   console.log(`📋 Правил до завантаження: ${rules.length}`)
   console.log(`📋 Skills до синхронізації: ${skills.length}`)
 
+  try {
+    const { destPath } = await syncSetupBunDepsAction(cwd(), BUNDLED_PACKAGE_ROOT)
+    console.log(`📝 Оновлено ${destPath} (composite setup-bun-deps з пакету)\n`)
+  } catch (error) {
+    console.error(`❌ Не вдалося записати setup-bun-deps action: ${error.message}`)
+    throw error
+  }
+
   const rulesDir = join(cwd(), RULES_DIR)
   await mkdir(rulesDir, { recursive: true })
 
@@ -646,13 +662,12 @@ async function runSync() {
   let failCount = 0
 
   for (const rule of rules) {
-    const url = buildUrl(rule, version)
     const fileName = `${RULE_PREFIX}${normalizeRuleName(rule)}`
     const destPath = join(rulesDir, fileName)
 
     try {
       process.stdout.write(`  ⬇  ${rule} → ${RULES_DIR}/${fileName} ... `)
-      const content = await fetchText(url)
+      const content = await readBundledRuleContent(rule)
       await writeFile(destPath, content, 'utf8')
       console.log(`✅`)
       successCount++
@@ -713,6 +728,7 @@ async function runSync() {
 const [command, ...args] = process.argv.slice(2)
 
 try {
+  await ensureNitraCursorInRootDevDependencies(cwd())
   if (command === 'check') {
     await runChecks(args)
   } else {

package/github-actions/setup-bun-deps/action.yml

@@ -0,0 +1,29 @@
+name: Setup Bun dependencies
+description: Checkout, Node 24, Bun, cache та bun install --frozen-lockfile
+
+runs:
+  using: composite
+  steps:
+    - uses: actions/checkout@v6
+      with:
+        persist-credentials: false
+
+    - uses: actions/setup-node@v6
+      with:
+        node-version: '24'
+
+    - uses: oven-sh/setup-bun@v2
+
+    - name: Cache Bun dependencies
+      uses: actions/cache@v5
+      with:
+        path: |
+          ~/.bun/install/cache
+          node_modules
+        key: ${{ runner.os }}-bun-${{ hashFiles('**/bun.lock') }}
+        restore-keys: |
+          ${{ runner.os }}-bun-
+
+    - name: Install dependencies
+      run: bun install --frozen-lockfile
+      shell: bash

package/mdc/bun.mdc

@@ -1,7 +1,7 @@
 ---
 description: Bun як єдиний package manager у монорепо
 alwaysApply: true
-version: '1.2'
+version: '1.3'
 ---
 
 Проект використовує тільки Bun для керування залежностями та запуску скриптів.
@@ -62,10 +62,14 @@ FROM oven/bun:alpine AS build-env
 В Github actions bun повинен налаштований так:
 
 ```yaml
+- uses: actions/setup-node@v6
+  with:
+    node-version: '24'
+
 - uses: oven-sh/setup-bun@v2
 
 - name: Cache Bun dependencies
-  uses: actions/cache@v4
+  uses: actions/cache@v5
   with:
     path: |
       ~/.bun/install/cache
@@ -87,3 +91,5 @@ FROM oven/bun:alpine AS build-env
 Якщо в кореневому @package.json  існують скрипти з префіксом `lint-`, обов'язково створюй `lint` скрипт, який буде запускати всі ці скрипти з лінт-префіксом.
 
 У кінці скрипта `lint` додай `&& oxfmt .`.
+
+Якщо в **`.n-cursor.json`** у масиві **`rules`** є **`docker`**, у кореневому `package.json` **обов'язково** скрипт **`lint-docker`** (див. **`docker.mdc`**) і рядок **`bun run lint-docker`** у **`lint`**. Якщо є **`k8s`** — **обов'язково** **`lint-k8s`** і **`bun run lint-k8s`** у **`lint`** (див. **`k8s.mdc`**). Перевірка — **`npx @nitra/cursor check bun`**.

package/mdc/docker.mdc

@@ -1,6 +1,6 @@
 ---
 description: Dockerfile — lint-docker / hadolint; перевірка check-docker
-version: '1.5'
+version: '1.6'
 globs: "**/Dockerfile*"
 alwaysApply: false
 ---
@@ -30,6 +30,8 @@ CLI **`hadolint`** приймає лише **явні шляхи** (`[DOCKERFILE
 }
 ```
 
+Якщо правило **`docker`** підключено в **`.n-cursor.json`** (масив **`rules`**), у **кореневому** `package.json` **обов'язково** мають бути скрипт **`lint-docker`** і виклик **`bun run lint-docker`** у агрегованому **`lint`** (див. **`bun.mdc`**). Це перевіряє **`npx @nitra/cursor check bun`**.
+
 Додай workflow **`.github/workflows/lint-docker.yml`** (гілка **`dev`**, лише **`.yml`**, узгоджено з **`ga.mdc`**):
 
 ```yaml title=".github/workflows/lint-docker.yml"
@@ -43,12 +45,6 @@ on:
       - '**/Dockerfile'
       - '**/*.Dockerfile'
       - '**/*.dockerfile'
-      - '.hadolint.yaml'
-      - 'npm/scripts/run-docker.mjs'
-      - 'npm/scripts/utils/docker-hadolint.mjs'
-      - 'npm/scripts/check-docker.mjs'
-      - 'npm/mdc/docker.mdc'
-      - 'package.json'
 
   pull_request:
     branches:
@@ -64,7 +60,7 @@ jobs:
     permissions:
       contents: read
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
         with:
           persist-credentials: false
 
@@ -74,10 +70,14 @@ jobs:
           chmod +x /tmp/hadolint
           sudo mv /tmp/hadolint /usr/local/bin/hadolint
 
+      - uses: actions/setup-node@v6
+        with:
+          node-version: '24'
+
       - uses: oven-sh/setup-bun@v2
 
       - name: Cache Bun dependencies
-        uses: actions/cache@v4
+        uses: actions/cache@v5
         with:
           path: |
             ~/.bun/install/cache
@@ -95,7 +95,7 @@ jobs:
 
 Узгоджуй версію hadolint **v2.12.0** з **`HADOLINT_IMAGE`** у **`npm/scripts/utils/docker-hadolint.mjs`**.
 
-Кореневий скрипт **`lint`** (див. **`n-bun.mdc`**) має викликати **`lint-docker`**, якщо він існує.
+Кореневий скрипт **`lint`** (див. **`n-bun.mdc`**) **обов'язково** містить **`bun run lint-docker`**, коли в проєкті підключено правило **`docker`**.
 
 ## Запуск
 
@@ -119,6 +119,6 @@ jobs:
 
 `npx @nitra/cursor check docker`
 
-Після змін у Dockerfile: **`bun run lint-docker`**, якщо скрипт додано в проєкт.
+Після змін у Dockerfile: **`bun run lint-docker`** (обов'язково для проєктів з правилом **`docker`** у **`.n-cursor.json`**).
 
 Kubernetes YAML і `$schema` у `k8s/` — окреме правило **`k8s.mdc`**, **`check k8s`**.

package/mdc/ga.mdc

@@ -26,7 +26,7 @@ jobs:
       contents: read
     steps:
       - name: Delete workflow runs
-        uses: dmvict/clean-workflow-runs@v1.0.0
+        uses: dmvict/clean-workflow-runs@v1
         with:
           token: ${{ github.token }}
           save_period: 31
@@ -55,7 +55,7 @@ jobs:
     steps:
       - id: delete_stuff
         name: Delete those pesky dead branches
-        uses: phpdocker-io/github-actions-delete-abandoned-branches@v2
+        uses: phpdocker-io/github-actions-delete-abandoned-branches@v2.0.3
         with:
           github_token: ${{ github.token }}
           last_commit_age_days: 90
@@ -80,11 +80,8 @@ on:
     branches:
       - dev
     paths:
+      - '.github/actions/**'
       - '.github/workflows/**'
-      - '.github/zizmor.yml'
-      - 'package.json'
-      - 'bun.lock'
-
   pull_request:
     branches:
       - dev
@@ -99,31 +96,16 @@ jobs:
     permissions:
       contents: read
     steps:
-      - uses: actions/checkout@v4
-        with:
-          persist-credentials: false
+      - uses: ./.github/actions/setup-bun-deps
 
-      - uses: oven-sh/setup-bun@v2
-
-      - name: Cache Bun dependencies
-        uses: actions/cache@v4
-        with:
-          path: |
-            ~/.bun/install/cache
-            node_modules
-          key: ${{ runner.os }}-bun-${{ hashFiles('**/bun.lock') }}
-          restore-keys: |
-            ${{ runner.os }}-bun-
-
-      - name: Install dependencies
-        run: bun install --frozen-lockfile
-
-      - uses: astral-sh/setup-uv@v6
+      - uses: astral-sh/setup-uv@v8.0.0
 
       - name: Lint GA
         run: bun run lint-ga
 ```
 
+Composite **`.github/actions/setup-bun-deps/action.yml`**: **`actions/checkout@v6`** (`persist-credentials: false`), **`actions/setup-node@v6`** (**Node 24**), **Bun**, **`actions/cache@v5`** і **`bun install --frozen-lockfile`**. У job достатньо **`- uses: ./.github/actions/setup-bun-deps`**.
+
 ```json title=".vscode/extensions.json"
 {
   "recommendations": ["github.vscode-github-actions"]

package/mdc/js-lint.mdc

@@ -71,7 +71,6 @@ on:
       - '**/*.tsx'
       - '**/*.vue'
       - '**/eslint.config.*'
-      - '.jscpd.json'
 
   pull_request:
     branches:
@@ -87,24 +86,7 @@ jobs:
     permissions:
       contents: read
     steps:
-      - uses: actions/checkout@v4
-        with:
-          persist-credentials: false
-
-      - uses: oven-sh/setup-bun@v2
-
-      - name: Cache Bun dependencies
-        uses: actions/cache@v4
-        with:
-          path: |
-            ~/.bun/install/cache
-            node_modules
-          key: ${{ runner.os }}-bun-${{ hashFiles('**/bun.lock') }}
-          restore-keys: |
-            ${{ runner.os }}-bun-
-
-      - name: Install dependencies
-        run: bun install --frozen-lockfile
+      - uses: ./.github/actions/setup-bun-deps
 
       - name: Eslint
         run: |
@@ -113,6 +95,8 @@ jobs:
           bunx jscpd .
 ```
 
+Composite **`.github/actions/setup-bun-deps/action.yml`** — checkout, Node 24, Bun, кеш і `bun install --frozen-lockfile` (див. **ga.mdc**).
+
 Один workflow на лінт JS; зайвий `lint.yml` з тими самими кроками — прибери.
 
 ```javascript title="eslint.config.js"
@@ -140,6 +124,10 @@ export default [
 }
 ```
 
+## Тести
+
+Проекту повинен бути покритий unit тестами за допомогою Bun test.
+
 **Код:** синтаксис Node **24+**, **top level await**.
 
 ## Перевірка

package/mdc/k8s.mdc

@@ -1,6 +1,6 @@
 ---
 description: K8s YAML — $schema (yaml-language-server); lint-k8s (kubeconform, kubescape); check-k8s
-version: '1.7'
+version: '1.10'
 globs: "**/k8s/**/*.{yaml,yml}"
 alwaysApply: false
 ---
@@ -42,6 +42,8 @@ alwaysApply: false
 }
 ```
 
+Якщо правило **`k8s`** підключено в **`.n-cursor.json`** (масив **`rules`**), у **кореневому** `package.json` **обов'язково** мають бути скрипт **`lint-k8s`** і виклик **`bun run lint-k8s`** у агрегованому **`lint`** (див. **`bun.mdc`**). Це перевіряє **`npx @nitra/cursor check bun`**.
+
 Шлях до скрипта підстав свій (`./scripts/…` після копіювання, `node_modules/@nitra/cursor/scripts/…` якщо пакет у залежностях).
 
 Додай workflow **`.github/workflows/lint-k8s.yml`** (гілка **`dev`**, лише **`.yml`**, узгоджено з **`ga.mdc`**):
@@ -70,7 +72,7 @@ jobs:
     permissions:
       contents: read
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
         with:
           persist-credentials: false
 
@@ -84,10 +86,14 @@ jobs:
           curl -s https://raw.githubusercontent.com/kubescape/kubescape/master/install.sh | /bin/bash
           echo "$HOME/.kubescape/bin" >> $GITHUB_PATH
 
+      - uses: actions/setup-node@v6
+        with:
+          node-version: '24'
+
       - uses: oven-sh/setup-bun@v2
 
       - name: Cache Bun dependencies
-        uses: actions/cache@v4
+        uses: actions/cache@v5
         with:
           path: |
             ~/.bun/install/cache
@@ -105,20 +111,20 @@ jobs:
 
 Після **`install.sh`** kubescape може опинитися поза стандартним PATH; за потреби додай крок **`echo "$HOME/.kubescape/bin" >> $GITHUB_PATH`** (див. документацію [kubescape](https://github.com/kubescape/kubescape#readme)).
 
-Кореневий скрипт **`lint`** (див. **`n-bun.mdc`**) має викликати **`lint-k8s`**, якщо він існує.
+Кореневий скрипт **`lint`** (див. **`n-bun.mdc`**) **обов'язково** містить **`bun run lint-k8s`**, коли в проєкті підключено правило **`k8s`**.
 
 ## Перевірка
 
 **`npx @nitra/cursor check k8s`** — узгодженість першого рядка (`$schema`), один рядок `# yaml-language-server` на файл, правило для `.yml`, відповідність URL першому YAML-документу (до `---`) за логікою нижче. Якщо під `k8s` немає yaml/yml — перевірку пропущено. Синтаксис YAML і зміст маніфесту скрипт не перевіряє — вручну.
 
-Після змін у маніфестах: **`bun run lint-k8s`** (kubeconform + kubescape), якщо скрипт додано в проєкт.
+Після змін у маніфестах: **`bun run lint-k8s`** (kubeconform + kubescape; обов'язково для проєктів з правилом **`k8s`** у **`.n-cursor.json`**).
 
 ## Що закодовано в `check-k8s.mjs`
 
-При зміні правил синхронно оновлюй **`YANNH_PIN`**, **`YANNH_REF`** (якщо зміниться гілка за замовчуванням у репо yannh), **`YANNH_GROUPS`**, а в **`run-k8s.mjs`** — константу **`KUBERNETES_VERSION`** (число з PIN, наприклад `v1.33.9-standalone-strict` → **`1.33.9`**).
+При зміні правил синхронно оновлюй **`YANNH_PIN`**, **`YANNH_REF`** (якщо зміниться гілка за замовчуванням у репо yannh), **`YANNH_GROUPS`**, **`DATREE_CRD_BASE`** (GitHub Pages каталогу CRD), а в **`run-k8s.mjs`** — константу **`KUBERNETES_VERSION`** і **`DATREE_CRD_SCHEMA_LOCATION`** (узгоджено з базою datree у цьому правилі).
 
 - Обхід з пропуском `node_modules`, `.git`, `dist`, `coverage`, `.turbo`, `.next`.
-- **`file:`** у `$schema` — URL до apiVersion/kind не звіряється; **`https:`** — kustomization за іменем файлу → Schema Store; `v1` → yannh; група з `YANNH_GROUPS` → yannh; інакше → datree.
+- **`file:`** у `$schema` — URL до apiVersion/kind не звіряється; **`https:`** — kustomization за іменем файлу → Schema Store; `v1` → yannh; група з `YANNH_GROUPS` → yannh; інакше → datree (GitHub Pages).
 
 ## Коли застосовувати (агентам)
 
@@ -136,8 +142,22 @@ jobs:
 3. **`apiVersion: group/version`** і **group** у **`YANNH_GROUPS`** у скрипті → yannh:
    `https://raw.githubusercontent.com/yannh/kubernetes-json-schema/master/<PIN>/<kind>-<group-з-крапками-як-дефіси>-<version>.json`
    Приклади: `apps/v1` + `Deployment` → `deployment-apps-v1.json`; `networking.k8s.io/v1` + `Ingress` → `ingress-networking-k8s-io-v1.json`.
-4. **Інакше** (CRD тощо) → [datreeio/CRDs-catalog](https://github.com/datreeio/CRDs-catalog):
-   `https://raw.githubusercontent.com/datreeio/CRDs-catalog/main/CRDs/<group>/<kind>_<version>.json`
+4. **Інакше** (CRD тощо) → [datreeio/CRDs-catalog](https://github.com/datreeio/CRDs-catalog) через **GitHub Pages** (канон для `$schema` у редакторі):
+   `https://datreeio.github.io/CRDs-catalog/<group>/<kind>_<version>.json`
+   (`<kind>` — лише літери та цифри в нижньому регістрі, без роздільників між CamelCase, як для yannh.)
+
+   **Приклад (Gateway API):** `apiVersion: gateway.networking.k8s.io/v1beta1`, `kind: HTTPRoute`:
+
+   ```yaml
+   # yaml-language-server: $schema=https://datreeio.github.io/CRDs-catalog/gateway.networking.k8s.io/httproute_v1beta1.json
+   ```
+
+   **Приклад (GKE):** `apiVersion: networking.gke.io/v1`, `kind: HealthCheckPolicy`:
+
+   ```yaml
+   # yaml-language-server: $schema=https://datreeio.github.io/CRDs-catalog/networking.gke.io/healthcheckpolicy_v1.json
+   ```
+
 5. **Немає надійного публічного URL** — не вигадуй: залиш коректний `$schema` або `file:` за узгодженням.
 
 ## Багатодокументні YAML

package/mdc/npm-module.mdc

@@ -8,7 +8,7 @@ Bun monorepo: workspace **`npm/`**, кореневий **`package.json`**, **`.g
 
 ## npm publish
 
-**`npm-publish.yml`:** push у **`main`**, **`paths: npm/**`**, **`JS-DevTools/npm-publish@v4`**, **`with.package: npm/package.json`**, **`permissions.id-token: write`** (OIDC на npm).
+**`npm-publish.yml`:** push у **`main`**, **`on.push.paths`** з **`npm/**`**, **`JS-DevTools/npm-publish@v4.1.5`**, **`with.package: npm/package.json`**, **`permissions.id-token: write`** (OIDC на npm).
 
 ```yaml title=".github/workflows/npm-publish.yml"
 name: npm-publish
@@ -32,17 +32,17 @@ jobs:
       id-token: write # КРИТИЧНО для OIDC!
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
         with:
           persist-credentials: false
 
-      - uses: actions/setup-node@v5
+      - uses: actions/setup-node@v6
         with:
           node-version: '24' # includes npm@11.6.0
           registry-url: 'https://registry.npmjs.org'
 
       - name: Publish package
-        uses: JS-DevTools/npm-publish@v4
+        uses: JS-DevTools/npm-publish@v4.1.5
         with:
           package: npm/package.json
 ```

package/mdc/style-lint.mdc

@@ -76,7 +76,7 @@ jobs:
   stylelint:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
 
       - name: StyleLint
         run: |

package/mdc/text.mdc

@@ -18,7 +18,7 @@ version: '1.22'
 }
 ```
 
-**`package.json`:** скрипт **`lint-text`** і devDependencies **`@nitra/cspell-dict`**, **`markdownlint-cli2`**. Для української додай **`@cspell/dict-uk-ua`**. **`v8r`** лише через **`bun x v8r`** (зазвичай **`bunx v8r`**), не в devDependencies. Окремий пакет **`markdownlint`** не потрібний.
+**`package.json`:** скрипт **`lint-text`** і devDependencies **`@nitra/cspell-dict`**. Для української додай **`@cspell/dict-uk-ua`**. **`v8r`** лише через **`bun x v8r`** (зазвичай **`bunx v8r`**), не в devDependencies. Окремий пакет **`markdownlint`** не потрібний.
 
 У v8r **немає** прапорця тихого режиму; рекомендовано скрипт **`run-v8r.mjs`** з репозиторію пакета `@nitra/cursor` (`npm/scripts/run-v8r.mjs`): один виклик у `lint-text` — під капотом послідовні **`bun x v8r`** для кожного типу (**json**, **json5**, **yml**, **yaml**, **toml**), бо один процес v8r з кількома глобами падає з **98**, якщо хоч один glob порожній, і тоді інші розширення не перевіряються. Вивід при кодах **0** і **98** не показується. Каталог схем **`schemas/v8r-catalog.json`** пакета `@nitra/cursor` скрипт підставляє в v8r сам. За бажання можна передати власні glob-и аргументами скрипта. Шлях до скрипта: `./npm/scripts/…`, `./scripts/…` після копіювання, або `node_modules/@nitra/cursor/scripts/…`.
 
@@ -72,10 +72,6 @@ on:
     branches:
       - dev
     paths:
-      - '.cspell.json'
-      - '.gitignore'
-      - '.markdownlint-cli2.jsonc'
-      - '.v8rignore'
       - '**/*.js'
       - '**/*.ts'
       - '**/*.vue'
@@ -111,29 +107,14 @@ jobs:
     permissions:
       contents: read
     steps:
-      - uses: actions/checkout@v4
-        with:
-          persist-credentials: false
-
-      - uses: oven-sh/setup-bun@v2
-
-      - name: Cache Bun dependencies
-        uses: actions/cache@v4
-        with:
-          path: |
-            ~/.bun/install/cache
-            node_modules
-          key: ${{ runner.os }}-bun-${{ hashFiles('**/bun.lock') }}
-          restore-keys: |
-            ${{ runner.os }}-bun-
-
-      - name: Install dependencies
-        run: bun install --frozen-lockfile
+      - uses: ./.github/actions/setup-bun-deps
 
       - name: Lint text
         run: bun run lint-text
 ```
 
+Composite **`.github/actions/setup-bun-deps/action.yml`** — checkout, Node 24, Bun, кеш і `bun install --frozen-lockfile` (див. **ga.mdc**).
+
 Не дублюй окремий workflow з тими самими кроками cspell/markdownlint.
 
 **`.cspell.json`**, `version: "0.2"`, **`language`**, **`import`** з `@nitra/cspell-dict`, **`ignorePaths`**, **`words`** лише для назв/термінів, коли не виправити текстом.
@@ -201,6 +182,8 @@ jobs:
 
 Підлаштуй `language` під проєкт (наприклад додай `ru-ru`, якщо потрібна перевірка російською). Порядок у `import` може впливати на пріоритет словників — тримай корпоративний `@nitra/cspell-dict` там, де зручно для ваших правил.
 
+**Український апостроф:** у словах не використовуй прямий символ `'` (U+0027); потрібен типографський апостроф `’` (U+2019). Якщо після цього cspell досі підсвічує слово як невідоме — додай його до масиву `words` у `.cspell.json`.
+
 ## Локальні виключення (cspell `words`)
 
 Коли **cspell** підсвічує слово, спочатку **виправ текст**, а не розширюй словник:

package/mdc/vue.mdc

@@ -207,6 +207,10 @@ export default defineConfig({
 })
 ```
 
+## Тести
+
+Проекту повинен бути покритий тестами E2E за допомогою Playwright.
+
 ### Висновок
 
 Дотримуючись цих практик і правил, можна будувати масштабовані, підтримувані та ефективні застосунки на Vue 3 з Composition API. Завжди звіряйся з офіційною документацією Vue 3 щодо оновлень і нових можливостей.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nitra/cursor",
-  "version": "1.6.27",
+  "version": "1.8.1",
   "description": "CLI для завантаження cursor-правил (префікс n-) у локальний репозиторій",
   "keywords": [
     "cli",
@@ -25,6 +25,7 @@
   "files": [
     "mdc",
     "bin",
+    "github-actions",
     "schemas",
     "scripts",
     "skills",
@@ -32,7 +33,7 @@
   ],
   "type": "module",
   "scripts": {
-    "test": "npx coverage-node test/index.js"
+    "test": "bun test tests"
   },
   "engines": {
     "node": ">=24"

package/schemas/n-cursor.json

@@ -29,7 +29,7 @@
     },
     "version": {
       "type": "string",
-      "description": "Версія пакету @nitra/cursor на unpkg для завантаження правил (необов'язково, інакше latest)."
+      "description": "Застаріле поле, ігнорується CLI. Правила завжди копіюються з каталогу mdc/ установленого пакету (node_modules або кеш npx); змініть версію через оновлення залежності."
     }
   },
   "required": ["rules"]

package/scripts/check-bun.mjs

@@ -4,6 +4,9 @@
  * Очікує наявність `bun.lock`, забороняє lockfile та артефакти yarn/pnpm, директорію `.yarn`
  * і поле `packageManager` у кореневому `package.json`.
  *
+ * Якщо в `.n-cursor.json` у `rules` є `docker` або `k8s`, вимагає у кореневому `package.json`
+ * відповідно скриптів `lint-docker` / `lint-k8s` (див. docker.mdc, k8s.mdc).
+ *
  * Якщо в кореневому `package.json` є скрипти з префіксом `lint-`, перевіряє наявність агрегованого
  * скрипта `lint`, у якому через `bun run <ім’я>` викликаються всі такі скрипти, і що рядок `lint`
  * закінчується на `&& oxfmt .`.
@@ -13,6 +16,26 @@ import { readFile } from 'node:fs/promises'
 
 import { pass } from './utils/pass.mjs'
 
+/**
+ * Зчитує ідентифікатори правил з `.n-cursor.json` (поле `rules`).
+ * @returns {Promise<Set<string>>} множина рядків id правил або порожня, якщо файлу/поля немає
+ */
+async function loadNCursorRules() {
+  if (!existsSync('.n-cursor.json')) {
+    return new Set()
+  }
+  try {
+    const raw = JSON.parse(await readFile('.n-cursor.json', 'utf8'))
+    const list = raw?.rules
+    if (!Array.isArray(list)) {
+      return new Set()
+    }
+    return new Set(list.map(String))
+  } catch {
+    return new Set()
+  }
+}
+
 /**
  * Перевіряє відповідність проєкту правилам bun.mdc
  * @returns {Promise<number>} 0 — все OK, 1 — є проблеми
@@ -44,6 +67,8 @@ export async function check() {
     fail('Відсутній bun.lock — запусти bun i')
   }
 
+  const cursorRules = await loadNCursorRules()
+
   if (existsSync('package.json')) {
     const pkg = JSON.parse(await readFile('package.json', 'utf8'))
     if (pkg.packageManager) {
@@ -53,6 +78,24 @@ export async function check() {
     }
 
     const scripts = pkg.scripts && typeof pkg.scripts === 'object' ? pkg.scripts : {}
+
+    if (cursorRules.has('docker')) {
+      if (scripts['lint-docker']) {
+        pass('package.json: є `lint-docker` (правило docker у .n-cursor.json)')
+      } else {
+        fail(
+          'У .n-cursor.json є правило `docker` — додай скрипт `lint-docker` у кореневий package.json (див. docker.mdc)'
+        )
+      }
+    }
+
+    if (cursorRules.has('k8s')) {
+      if (scripts['lint-k8s']) {
+        pass('package.json: є `lint-k8s` (правило k8s у .n-cursor.json)')
+      } else {
+        fail('У .n-cursor.json є правило `k8s` — додай скрипт `lint-k8s` у кореневий package.json (див. k8s.mdc)')
+      }
+    }
     const lintPrefixed = Object.keys(scripts).filter(name => name.startsWith('lint-'))
     if (lintPrefixed.length > 0) {
       const aggregate = typeof scripts.lint === 'string' ? scripts.lint : ''

package/scripts/check-docker.mjs

@@ -16,7 +16,7 @@ import { walkDir } from './utils/walkDir.mjs'
  * @param {string} name basename шляху
  * @returns {boolean} true для Dockerfile / Dockerfile.* / Containerfile / Containerfile.*
  */
-function isDockerfileName(name) {
+export function isDockerfileName(name) {
   const n = name.toLowerCase()
   if (n === 'dockerfile' || n === 'containerfile') return true
   if (n.startsWith('dockerfile.') || n.startsWith('containerfile.')) return true
@@ -28,7 +28,7 @@ function isDockerfileName(name) {
  * @param {string} root корінь репозиторію
  * @returns {Promise<string[]>} відсортовані абсолютні шляхи
  */
-async function findDockerfilePaths(root) {
+export async function findDockerfilePaths(root) {
   /** @type {string[]} */
   const out = []
   await walkDir(root, p => {

package/scripts/check-ga.mjs

@@ -2,7 +2,8 @@
  * Перевіряє GitHub Actions за правилом ga.mdc.
  *
  * Workflows лише з розширенням `.yml`, наявність clean/lint workflow, конфіг zizmor з ref-pin,
- * відсутність MegaLinter, коректний скрипт `lint-ga` у `package.json` і виклик у `lint-ga.yml`.
+ * відсутність MegaLinter, коректний скрипт `lint-ga` у `package.json`, виклик у `lint-ga.yml`,
+ * наявність composite `.github/actions/setup-bun-deps/action.yml` (його записує `npx @nitra/cursor`).
  */
 import { existsSync } from 'node:fs'
 import { readdir, readFile } from 'node:fs/promises'
@@ -34,6 +35,15 @@ export async function check() {
     return exitCode
   }
 
+  const setupBunDepsAction = '.github/actions/setup-bun-deps/action.yml'
+  if (existsSync(setupBunDepsAction)) {
+    pass(`${setupBunDepsAction} існує`)
+  } else {
+    fail(
+      `Відсутній ${setupBunDepsAction} — запустіть npx @nitra/cursor або скопіюйте з пакету (ga.mdc: composite setup-bun-deps)`
+    )
+  }
+
   const files = await readdir(wfDir)
 
   const yamlFiles = files.filter(f => f.endsWith('.yaml'))

package/scripts/check-k8s.mjs

@@ -2,7 +2,8 @@
  * Перевіряє Kubernetes YAML у шляхах з сегментом `k8s` (див. k8s.mdc).
  *
  * Перший рядок `# yaml-language-server: $schema=…`, без дублікатів, розширення `.yaml`
- * (окрім `kustomization.yml`); URL схеми за першим документом — kustomization / yannh / datree.
+ * (окрім `kustomization.yml`); URL схеми за першим документом — kustomization / yannh / datree
+ * (datree: `https://datreeio.github.io/CRDs-catalog/<group>/<kind>_<version>.json`).
  * Dockerfile — правило docker.mdc, скрипт check-docker.mjs.
  */
 import { readFile } from 'node:fs/promises'
@@ -14,14 +15,15 @@ import { walkDir } from './utils/walkDir.mjs'
 /** Версія набору схем yannh — узгоджено з k8s.mdc */
 const YANNH_PIN = 'v1.33.9-standalone-strict'
 
-/** Гілка репозиторію yannh/kubernetes-json-schema для raw.githubusercontent.com (каталог набору — у підшляху після ref). */
+/** Гілка репозиторію yannh/kubernetes-json-schema для raw.githubusercontent.com (каталог набору в URL одразу після ref). */
 const YANNH_REF = 'master'
 
 const KUSTOMIZATION_SCHEMA = 'https://json.schemastore.org/kustomization.json'
 
 const YANNH_BASE = `https://raw.githubusercontent.com/yannh/kubernetes-json-schema/${YANNH_REF}/${YANNH_PIN}/`
 
-const DATREE_CRD_BASE = 'https://raw.githubusercontent.com/datreeio/CRDs-catalog/main/CRDs/'
+/** Публікація [CRDs-catalog](https://github.com/datreeio/CRDs-catalog) на GitHub Pages (те саме дерево, що й raw на `main`). */
+const DATREE_CRD_BASE = 'https://datreeio.github.io/CRDs-catalog/'
 
 /**
  * Групи API Kubernetes, для яких у перевірці очікується схема yannh (не datree CRD catalog).
@@ -59,7 +61,7 @@ const MODELINE_RE = /^#\s*yaml-language-server:\s*\$schema=(\S+)\s*$/
  * @param {string} filePath шлях до файлу
  * @returns {boolean} true, якщо серед компонентів шляху є каталог `k8s`
  */
-function pathHasK8sSegment(filePath) {
+export function pathHasK8sSegment(filePath) {
   const parts = filePath.split(/[/\\]/u)
   return parts.includes('k8s')
 }
@@ -140,7 +142,7 @@ function kindToSchemaFilePart(kind) {
  * @param {string} doc перший YAML-документ після modeline
  * @returns {{ expected: string | null, reason: string }} reason — для повідомлень про помилку
  */
-function expectedSchemaUrl(filePath, doc) {
+export function expectedSchemaUrl(filePath, doc) {
   const base = basename(filePath)
   const baseLower = base.toLowerCase()
 

package/scripts/check-npm-module.mjs

@@ -1,7 +1,7 @@
 /**
  * Перевіряє структуру npm-модуля в монорепо за правилом npm-module.mdc.
  *
- * Workspace `npm/`, `npm/package.json`, workflow `npm-publish.yml` з OIDC і шляхом до пакета.
+ * Workspace `npm/`, `npm/package.json`, workflow `npm-publish.yml` з OIDC, `on.push.paths` з glob для каталогу npm (див. npm-module.mdc).
  */
 import { existsSync } from 'node:fs'
 import { readFile, stat } from 'node:fs/promises'

package/scripts/check-text.mjs

@@ -4,12 +4,42 @@
  * cspell, markdownlint-cli2, скрипт `lint-text` з v8r (`run-v8r.mjs` або чотири `bunx v8r`),
  * `.v8rignore` (vscode JSON),
  * workflow `lint-text.yml`, розширення VSCode для markdownlint.
+ *
+ * Якщо є `.cursor/rules/n-text.mdc` і/або `npm/mdc/text.mdc` — перевіряє наявність абзацу про український
+ * апостроф (U+0027 vs U+2019) і приклад з символом U+2019 у тексті.
  */
 import { existsSync } from 'node:fs'
 import { readFile } from 'node:fs/promises'
 
 import { pass } from './utils/pass.mjs'
 
+/** Заголовок абзацу про апостроф у text.mdc / n-text.mdc. */
+const UK_APOSTROPHE_HEADING = '**Український апостроф:**'
+
+/**
+ * Перевіряє абзац про український апостроф у вмісті правила text.
+ * @param {string} filePath шлях до файлу (для повідомлень)
+ * @param {string} body вміст .mdc у UTF-8
+ * @param {(msg: string) => void} failFn реєструє порушення (exit 1)
+ * @param {(msg: string) => void} passFn реєструє успішну перевірку
+ * @returns {void}
+ */
+function verifyUkApostropheRuleParagraph(filePath, body, failFn, passFn) {
+  if (!body.includes(UK_APOSTROPHE_HEADING)) {
+    failFn(`${filePath}: додай абзац **Український апостроф:** (U+0027 / U+2019, масив words) — див. text.mdc`)
+    return
+  }
+  if (!body.includes('U+0027') || !body.includes('U+2019')) {
+    failFn(`${filePath}: абзац про апостроф має містити позначки U+0027 та U+2019`)
+    return
+  }
+  if (!body.includes('\u2019')) {
+    failFn(`${filePath}: у прикладі має бути типографський символ U+2019 (\u2019)`)
+    return
+  }
+  passFn(`${filePath}: абзац про український апостроф на місці`)
+}
+
 /**
  * Перевіряє відповідність проєкту правилам text.mdc (cspell, markdownlint-cli2, v8r)
  * @returns {Promise<number>} 0 — все OK, 1 — є проблеми
@@ -104,6 +134,16 @@ export async function check() {
     fail('.cspell.json не існує — створи його')
   }
 
+  const textRulePaths = ['.cursor/rules/n-text.mdc', 'npm/mdc/text.mdc'].filter(p => existsSync(p))
+  if (textRulePaths.length === 0) {
+    pass('n-text.mdc / npm/mdc/text.mdc відсутні — перевірку абзацу про апостроф пропущено')
+  } else {
+    for (const p of textRulePaths) {
+      const body = await readFile(p, 'utf8')
+      verifyUkApostropheRuleParagraph(p, body, fail, pass)
+    }
+  }
+
   if (existsSync('package.json')) {
     const pkg = JSON.parse(await readFile('package.json', 'utf8'))
     const devDeps = pkg.devDependencies || {}

package/scripts/cli-entry.mjs

@@ -0,0 +1,27 @@
+/**
+ * Визначення, чи виконується поточний ESM-модуль як точка входу CLI, а не як import у тестах чи інших модулях.
+ *
+ * У Bun використовується `import.meta.main`; у Node — порівняння `import.meta.url` з `process.argv[1]`
+ * після `resolve`, щоб `bun path/to/script.mjs` і `node path/to/script.mjs` коректно вважалися прямим запуском.
+ */
+import { resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+/**
+ * Чи виконується модуль як точка входу CLI (прямий запуск), а не через import.
+ * @returns {boolean} `true`, якщо файл запущено напряму; інакше `false`.
+ */
+export function isRunAsCli() {
+  if (import.meta.main === true) {
+    return true
+  }
+  try {
+    const entry = process.argv[1]
+    if (!entry) {
+      return false
+    }
+    return fileURLToPath(import.meta.url) === resolve(entry)
+  } catch {
+    return false
+  }
+}

package/scripts/ensure-nitra-cursor-dev-dependencies.mjs

@@ -0,0 +1,99 @@
+/**
+ * Дописує `\@nitra/cursor` у `devDependencies` кореневого `package.json` проєкту, якщо пакет ще не
+ * оголошено ні в `devDependencies`, ні в `dependencies`.
+ *
+ * Використовується CLI `n-cursor` при кожному запуску (`npx \@nitra/cursor`, зокрема `check`), щоб
+ * команда `check` і скрипти з `node_modules/\@nitra/cursor/scripts/` були відтворювані після
+ * `bun install` / `npm install`, а не лише з кешу npx.
+ *
+ * Версія діапазону: `^<version>` з поля `version` установленого пакету `\@nitra/cursor`.
+ */
+
+import { existsSync } from 'node:fs'
+import { readFile, writeFile } from 'node:fs/promises'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const PACKAGE_NAME = '@nitra/cursor'
+
+const scriptDir = dirname(fileURLToPath(import.meta.url))
+const bundledPkgPath = join(scriptDir, '..', 'package.json')
+
+/**
+ * Версія з `package.json` пакету `\@nitra/cursor` (каталог на рівень вище за `scripts/`).
+ * @returns {Promise<string | null>} поле `version` рядком або `null`, якщо файлу немає / помилка парсингу
+ */
+export async function readBundledPackageVersion() {
+  if (!existsSync(bundledPkgPath)) {
+    return null
+  }
+  try {
+    const raw = await readFile(bundledPkgPath, 'utf8')
+    const pkg = JSON.parse(raw)
+    return typeof pkg.version === 'string' ? pkg.version : null
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Якщо в `root/package.json` немає `\@nitra/cursor` у `devDependencies` і `dependencies`, дописує
+ * `devDependencies["\@nitra/cursor"]` зі значенням `^<bundledVersion>`.
+ * @param {string} root абсолютний шлях кореня проєкту (зазвичай `process.cwd()`)
+ * @param {{ bundledVersion?: string | null, silent?: boolean }} [options] `bundledVersion` — для тестів;
+ *   `silent` — не писати в консоль при успішному оновленні
+ * @returns {Promise<boolean>} `true`, якщо `package.json` змінено на диску
+ */
+export async function ensureNitraCursorInRootDevDependencies(root, options = {}) {
+  const pkgPath = join(root, 'package.json')
+  if (!existsSync(pkgPath)) {
+    return false
+  }
+
+  let raw
+  try {
+    raw = await readFile(pkgPath, 'utf8')
+  } catch {
+    return false
+  }
+
+  let pkg
+  try {
+    pkg = JSON.parse(raw)
+  } catch {
+    return false
+  }
+
+  if (pkg === null || typeof pkg !== 'object' || Array.isArray(pkg)) {
+    return false
+  }
+
+  const devDeps = pkg.devDependencies
+  const deps = pkg.dependencies
+  if (devDeps && typeof devDeps === 'object' && PACKAGE_NAME in devDeps) {
+    return false
+  }
+  if (deps && typeof deps === 'object' && PACKAGE_NAME in deps) {
+    return false
+  }
+
+  const ver = options.bundledVersion ?? (await readBundledPackageVersion())
+  if (!ver) {
+    return false
+  }
+
+  if (!pkg.devDependencies || typeof pkg.devDependencies !== 'object' || Array.isArray(pkg.devDependencies)) {
+    pkg.devDependencies = {}
+  }
+
+  pkg.devDependencies[PACKAGE_NAME] = `^${ver}`
+
+  const out = `${JSON.stringify(pkg, null, 2)}\n`
+  await writeFile(pkgPath, out, 'utf8')
+
+  if (!options.silent) {
+    console.log(`📝 Додано ${PACKAGE_NAME}@^${ver} у devDependencies у package.json\n`)
+  }
+
+  return true
+}

package/scripts/run-docker.mjs

@@ -9,6 +9,7 @@
  */
 import { basename } from 'node:path'
 
+import { isRunAsCli } from './cli-entry.mjs'
 import { lintDockerfileWithHadolint, posixRel } from './utils/docker-hadolint.mjs'
 import { pass } from './utils/pass.mjs'
 import { walkDir } from './utils/walkDir.mjs'
@@ -18,7 +19,7 @@ import { walkDir } from './utils/walkDir.mjs'
  * @param {string} name basename шляху
  * @returns {boolean} true, якщо ім’я підходить під lint-docker
  */
-function isLintDockerfileName(name) {
+export function isLintDockerfileName(name) {
   const n = name.toLowerCase()
   if (n === 'dockerfile') return true
   return n.endsWith('.dockerfile') && n.length > '.dockerfile'.length
@@ -29,7 +30,7 @@ function isLintDockerfileName(name) {
  * @param {string} root корінь репозиторію
  * @returns {Promise<string[]>} відсортовані абсолютні шляхи
  */
-async function findLintDockerfilePaths(root) {
+export async function findLintDockerfilePaths(root) {
   /** @type {string[]} */
   const out = []
   await walkDir(root, p => {
@@ -73,4 +74,6 @@ async function main() {
   return exitCode
 }
 
-process.exitCode = await main()
+if (isRunAsCli()) {
+  process.exitCode = await main()
+}

package/scripts/run-k8s.mjs

@@ -15,6 +15,7 @@
 import { spawnSync } from 'node:child_process'
 import { basename, dirname } from 'node:path'
 
+import { isRunAsCli } from './cli-entry.mjs'
 import { walkDir } from './utils/walkDir.mjs'
 
 /** Версія Kubernetes для kubeconform — синхронно з YANNH_PIN (без префікса v і суфікса -standalone-strict). */
@@ -22,14 +23,14 @@ const KUBERNETES_VERSION = '1.33.9'
 
 /** Додатковий реєстр схем для CRD (як у README kubeconform). */
 const DATREE_CRD_SCHEMA_LOCATION =
-  'https://raw.githubusercontent.com/datreeio/CRDs-catalog/main/{{.Group}}/{{.ResourceKind}}_{{.ResourceAPIVersion}}.json'
+  'https://datreeio.github.io/CRDs-catalog/{{.Group}}/{{.ResourceKind}}_{{.ResourceAPIVersion}}.json'
 
 /**
  * Чи містить шлях сегмент директорії `k8s`.
  * @param {string} filePath шлях до файлу
  * @returns {boolean} true, якщо серед компонентів шляху є каталог `k8s`
  */
-function pathHasK8sSegment(filePath) {
+export function pathHasK8sSegment(filePath) {
   const parts = filePath.split(/[/\\]/u)
   return parts.includes('k8s')
 }
@@ -39,7 +40,7 @@ function pathHasK8sSegment(filePath) {
  * @param {string} absFile абсолютний шлях до yaml
  * @returns {string | null} абсолютний шлях до `…/k8s` або null, якщо сегмента `k8s` у ланцюжку немає
  */
-function k8sRootFromFile(absFile) {
+export function k8sRootFromFile(absFile) {
   let dir = dirname(absFile)
   for (let i = 0; i < 64; i++) {
     if (basename(dir) === 'k8s') return dir
@@ -55,7 +56,7 @@ function k8sRootFromFile(absFile) {
  * @param {string} root корінь репозиторію
  * @returns {Promise<string[]>} відсортовані абсолютні шляхи до каталогів `k8s`
  */
-async function findK8sRoots(root) {
+export async function findK8sRoots(root) {
   /** @type {Set<string>} */
   const roots = new Set()
   await walkDir(root, p => {
@@ -136,4 +137,6 @@ async function main() {
   return ks
 }
 
-process.exitCode = await main()
+if (isRunAsCli()) {
+  process.exitCode = await main()
+}

package/scripts/run-v8r.mjs

@@ -18,17 +18,36 @@ import { existsSync } from 'node:fs'
 import { dirname, join } from 'node:path'
 import { fileURLToPath } from 'node:url'
 
+import { isRunAsCli } from './cli-entry.mjs'
+
 /** Типові glob-и для форматів, які обробляє v8r (див. опис CLI v8r). */
-const DEFAULT_GLOBS = ['**/*.json', '**/*.json5', '**/*.yml', '**/*.yaml', '**/*.toml']
+export const DEFAULT_V8R_GLOBS = ['**/*.json', '**/*.json5', '**/*.yml', '**/*.yaml', '**/*.toml']
 
 /** Абсолютний шлях до `schemas/v8r-catalog.json` поруч з цим скриптом у пакеті `@nitra/cursor`. */
-const V8R_CATALOG_PATH = join(dirname(fileURLToPath(import.meta.url)), '../schemas/v8r-catalog.json')
+export const V8R_CATALOG_PATH = join(dirname(fileURLToPath(import.meta.url)), '../schemas/v8r-catalog.json')
+
+/**
+ * Повертає шлях до каталогу схем v8r для пакета (для тестів і діагностики).
+ * @returns {string} абсолютний шлях до v8r-catalog.json
+ */
+export function getV8rCatalogPath() {
+  return V8R_CATALOG_PATH
+}
 
-if (existsSync(V8R_CATALOG_PATH)) {
-  const globs = process.argv.length > 2 ? process.argv.slice(2) : DEFAULT_GLOBS
+/**
+ * Запускає послідовні виклики v8r по glob-ам; не змінює process.exitCode (лише повертає код).
+ * @param {string[]} [globs] патерни; за замовчуванням DEFAULT_V8R_GLOBS
+ * @returns {number} 0 — OK, 1 — помилка spawn, 2 — немає каталогу схем, інше — код v8r
+ */
+export function runV8rWithGlobs(globs = DEFAULT_V8R_GLOBS) {
+  if (!existsSync(V8R_CATALOG_PATH)) {
+    process.stderr.write(
+      `run-v8r: не знайдено каталог схем за шляхом ${V8R_CATALOG_PATH} (очікується npm/schemas/v8r-catalog.json у пакеті)\n`
+    )
+    return 2
+  }
 
   for (const pattern of globs) {
-    // Порядок важливий: glob має бути перед -c, інакше yargs у v8r не отримує позиційні patterns.
     const result = spawnSync('bun', ['x', 'v8r', pattern, '-c', V8R_CATALOG_PATH], {
       encoding: 'utf8',
       maxBuffer: 50 * 1024 * 1024,
@@ -38,8 +57,7 @@ if (existsSync(V8R_CATALOG_PATH)) {
 
     if (result.error) {
       process.stderr.write(`${result.error.message}\n`)
-      process.exitCode = 1
-      break
+      return 1
     }
 
     const exitCode = result.status ?? 1
@@ -50,13 +68,13 @@ if (existsSync(V8R_CATALOG_PATH)) {
       if (result.stderr?.length) {
         process.stderr.write(result.stderr)
       }
-      process.exitCode = exitCode
-      break
+      return exitCode
     }
   }
-} else {
-  process.stderr.write(
-    `run-v8r: не знайдено каталог схем за шляхом ${V8R_CATALOG_PATH} (очікується npm/schemas/v8r-catalog.json у пакеті)\n`
-  )
-  process.exitCode = 2
+  return 0
+}
+
+if (isRunAsCli()) {
+  const globs = process.argv.length > 2 ? process.argv.slice(2) : DEFAULT_V8R_GLOBS
+  process.exitCode = runV8rWithGlobs(globs)
 }

package/scripts/sync-setup-bun-deps-action.mjs

@@ -0,0 +1,36 @@
+/**
+ * Копіює composite GitHub Action `setup-bun-deps` з установленого пакету `@nitra/cursor`
+ * у цільовий репозиторій (`.github/actions/setup-bun-deps/action.yml`).
+ *
+ * Використовується CLI `npx \@nitra/cursor`, щоб workflows з правил `ga` / `js-lint` / `text`
+ * могли одразу викликати `uses: ./.github/actions/setup-bun-deps` без ручного копіювання.
+ *
+ * Джерело: каталог `github-actions/setup-bun-deps/` у корені tarball пакету (поруч із `mdc/`, `bin/`).
+ */
+import { existsSync } from 'node:fs'
+import { mkdir, readFile, writeFile } from 'node:fs/promises'
+import { join } from 'node:path'
+
+/** Відносний шлях до `action.yml` всередині кореня пакету */
+const RELATIVE_BUNDLED_ACTION = join('github-actions', 'setup-bun-deps', 'action.yml')
+
+/** Відносний шлях призначення у проєкті-клієнті */
+const RELATIVE_DEST_ACTION = join('.github', 'actions', 'setup-bun-deps', 'action.yml')
+
+/**
+ * Записує у `projectRoot` composite action з `bundledPackageRoot` (корінь установленого `@nitra/cursor`).
+ * @param {string} projectRoot абсолютний шлях до кореня цільового репозиторію
+ * @param {string} bundledPackageRoot абсолютний шлях до кореня пакету (теки з `mdc/`, `github-actions/`)
+ * @returns {Promise<{ written: boolean, destPath: string }>} чи був запис і повний шлях файлу
+ */
+export async function syncSetupBunDepsAction(projectRoot, bundledPackageRoot) {
+  const srcPath = join(bundledPackageRoot, RELATIVE_BUNDLED_ACTION)
+  if (!existsSync(srcPath)) {
+    throw new Error(`Не знайдено шаблон composite action.\nОчікуваний шлях: ${srcPath}\nПеревстановіть @nitra/cursor.`)
+  }
+  const destPath = join(projectRoot, RELATIVE_DEST_ACTION)
+  await mkdir(join(projectRoot, '.github', 'actions', 'setup-bun-deps'), { recursive: true })
+  const content = await readFile(srcPath, 'utf8')
+  await writeFile(destPath, content.endsWith('\n') ? content : `${content}\n`, 'utf8')
+  return { written: true, destPath }
+}