@nitra/cursor 1.6.27 → 1.7.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 поточного проєкту.
@@ -33,10 +33,9 @@ import { cwd } from 'node:process'
 import { fileURLToPath } from 'node:url'
 
 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'
@@ -87,19 +86,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 +134,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 +177,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 +189,40 @@ 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')
+}
+
+/**
+ * Версія з `package.json` установленого пакету (каталог поруч із `bin/`).
+ * @returns {Promise<string | null>} поле `version` рядком або `null`, якщо файлу немає / помилка парсингу
+ */
+async function readBundledPackageVersion() {
+  const pkgPath = join(binDir, '..', 'package.json')
+  if (!existsSync(pkgPath)) {
+    return null
+  }
+  try {
+    const raw = await readFile(pkgPath, 'utf8')
+    const pkg = JSON.parse(raw)
+    return typeof pkg.version === 'string' ? pkg.version : null
+  } catch {
+    return null
+  }
+}
+
 /**
  * Нормалізує id skill з конфігу до форми без префікса n- (як «fix»)
  * @param {string} skillName елемент масиву skills або ім'я каталогу
@@ -618,7 +626,7 @@ async function runChecks(requestedRules) {
 }
 
 /**
- * Завантажує правила з npm та синхронізує локальні файли
+ * Копіює правила з каталогу `mdc/` установленого пакету та синхронізує `.cursor/rules`
  * @returns {Promise<void>}
  */
 async function runSync() {
@@ -633,8 +641,12 @@ 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}`)
@@ -646,13 +658,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++

package/mdc/bun.mdc

@@ -1,7 +1,7 @@
 ---
 description: Bun як єдиний package manager у монорепо
 alwaysApply: true
-version: '1.2'
+version: '1.3'
 ---
 
 Проект використовує тільки Bun для керування залежностями та запуску скриптів.
@@ -87,3 +87,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"
@@ -95,7 +97,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 +121,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/js-lint.mdc

@@ -140,6 +140,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.8'
 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`**):
@@ -105,13 +107,13 @@ 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`
 

package/mdc/text.mdc

@@ -201,6 +201,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.7.1",
   "description": "CLI для завантаження cursor-правил (префікс n-) у локальний репозиторій",
   "keywords": [
     "cli",
@@ -32,7 +32,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-k8s.mjs

@@ -14,7 +14,7 @@ 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'
@@ -59,7 +59,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 +140,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-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/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). */
@@ -29,7 +30,7 @@ const DATREE_CRD_SCHEMA_LOCATION =
  * @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)
 }