@nitra/cursor 1.6.4 → 1.6.11

package/README.md

@@ -14,6 +14,7 @@
 
 ```json
 {
+  "$schema": "https://unpkg.com/@nitra/cursor/schemas/n-cursor.json",
   "rules": ["js-format", "npm-module", "text"]
 }
 ```
@@ -30,6 +31,7 @@
 
 ```json
 {
+  "$schema": "https://unpkg.com/@nitra/cursor/schemas/n-cursor.json",
   "version": "2.5.0",
   "rules": ["js-format", "text"]
 }
@@ -39,11 +41,15 @@
 
 ```bash
 npx @nitra/cursor
+npx @nitra/cursor check
+npx @nitra/cursor check bun ga
 ```
 
-CLI автоматично:
+Команда `check` запускає programmatic перевірки з каталогу `scripts/` пакету. Якщо в корені репозиторію вже є `.n-cursor.json`, перед перевірками виконується зчитування конфігу — зокрема додається або виправляється поле `$schema`, якщо воно відсутнє або не збігається з очікуваним URL.
 
-1. Знайде або створить `.n-cursor.json` у поточній директорії
+CLI автоматично (команда завантаження правил без підкоманди `check`):
+
+1. Знайде або створить `.n-cursor.json` у поточній директорії (із полем `$schema` на JSON Schema пакету; якщо файл уже є без коректного `$schema`, поле буде додано або оновлено при зчитуванні конфігу)
 2. Створить директорію `.cursor/rules/`, якщо її ще немає
 3. Завантажить кожне з перелічених у конфігу правило з unpkg.com і збереже файли з префіксом `n-`
 4. Після оновлення файлів на диску згенерує в корені проєкту **`AGENTS.md`**: повний вміст береться з шаблону пакету `AGENTS.template.md`, а список правил у шаблоні формується з **усіх наявних файлів `*.mdc`** у `.cursor/rules/` (відсортовано за ім’ям)

package/bin/n-cursor.js

@@ -5,12 +5,14 @@
  *
  * Використання:
  *   `npx \@nitra/cursor`             — завантажити cursor-правила
- *   `npx \@nitra/cursor check`       — перевірити правила, перелічені в AGENTS.md (якщо є check-*.mjs)
+ *   `npx \@nitra/cursor check`       — перевірити правила, перелічені в AGENTS.md (якщо є check-*.mjs);
+ *                                     якщо в корені вже є `.n-cursor.json`, спочатку зчитується конфіг і за потреби дописується `$schema`
  *   `npx \@nitra/cursor check bun`   — перевірити лише вказані правила (ігнорує AGENTS.md)
  *
  * Якщо у корені репозиторію немає .n-cursor.json, спочатку перейменовується за наявності nitra-cursor.json;
  * у `.cursor/rules` файли `nitra-*.mdc` перейменовуються на `n-*.mdc`; інакше конфіг створюється автоматично
- * з усіма правилами з каталогу mdc пакету (їх можна відредагувати після створення).
+ * з усіма правилами з каталогу mdc пакету (їх можна відредагувати після створення). У файлі завжди має бути
+ * поле `$schema` з посиланням на JSON Schema пакету; при зчитуванні конфігу воно додається або виправляється на диску, якщо відсутнє або некоректне.
  *
  * Файл AGENTS.md у корені: щоразу повністю перезаписується змістом з AGENTS.template.md
  * пакету; список правил у шаблоні будується з файлів *.mdc у .cursor/rules поточного проєкту.
@@ -33,6 +35,8 @@ 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`
 const AGENTS_FILE = 'AGENTS.md'
 const AGENTS_TEMPLATE_FILE = 'AGENTS.template.md'
 const RULES_DIR = '.cursor/rules'
@@ -144,7 +148,7 @@ async function migrateLegacyConfigIfNeeded() {
 
 /**
  * Зчитує конфіг .n-cursor.json з поточної директорії
- * @returns {Promise<{rules: string[], skills: string[], version?: string}>} 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()
@@ -152,7 +156,7 @@ async function readConfig() {
   if (!existsSync(configPath)) {
     const rules = await discoverBundledRuleNames()
     const skills = await discoverBundledSkillNames()
-    const defaultConfig = { rules, skills }
+    const defaultConfig = { $schema: CONFIG_SCHEMA_URL, rules, skills }
     await writeFile(configPath, `${JSON.stringify(defaultConfig, null, 2)}\n`, 'utf8')
     console.log(
       `📝 Створено ${CONFIG_FILE} з усіма правилами (${rules.length}) і skills (${skills.length}) з пакету. За потреби відредагуйте списки.\n`
@@ -175,6 +179,15 @@ async function readConfig() {
     }
     config.skills = await discoverBundledSkillNames()
   }
+
+  if (config.$schema !== CONFIG_SCHEMA_URL) {
+    const { $schema: _omit, ...rest } = config
+    const normalized = { $schema: CONFIG_SCHEMA_URL, ...rest }
+    await writeFile(configPath, `${JSON.stringify(normalized, null, 2)}\n`, 'utf8')
+    console.log(`📝 Оновлено поле $schema у ${CONFIG_FILE}\n`)
+    return normalized
+  }
+
   return config
 }
 
@@ -546,6 +559,17 @@ async function runChecks(requestedRules) {
     throw new Error('No check scripts found')
   }
 
+  const root = cwd()
+  const legacyConfigPath = join(root, 'nitra-cursor.json')
+  if (existsSync(join(root, CONFIG_FILE)) || existsSync(legacyConfigPath)) {
+    try {
+      await readConfig()
+    } catch (error) {
+      console.error(`❌ ${error.message}`)
+      throw error
+    }
+  }
+
   let rulesToCheck
   if (requestedRules.length > 0) {
     rulesToCheck = requestedRules

package/mdc/bun.mdc

@@ -81,3 +81,7 @@ FROM oven/bun:alpine AS build-env
 ## Перевірка
 
 `npx @nitra/cursor check bun`
+
+## lint
+
+Якщо в кореневому @package.json  існують скрипти з префіксом `lint-`, обов'язково створюй `lint` скрипт, який буде запускати всі ці скрипти з лінт-префіксом.

package/mdc/docker.mdc

@@ -0,0 +1,39 @@
+---
+description: Dockerfile — лінт через hadolint (локально або Docker); перевірка check-docker
+version: '1.0'
+globs: "**/Dockerfile*"
+alwaysApply: false
+---
+
+# Docker — hadolint
+
+[hadolint](https://github.com/hadolint/hadolint) перевіряє Dockerfile на типові помилки та рекомендації (`FROM`, `RUN`, `COPY`, shell form тощо).
+
+## Область
+
+- Усі файли з іменем **`Dockerfile`** або **`Dockerfile.*`** (наприклад `Dockerfile.prod`) у репозиторії, крім ігнорованих каталогів (`node_modules`, `.git`, `dist`, …) — як у **`check-docker.mjs`**.
+- Також скрипт перевірки обробляє **`Containerfile`** та **`Containerfile.*`** (Podman / альтернативні імена), навіть якщо glob правила спрацьовує переважно на `Dockerfile*`.
+
+## Запуск
+
+1. **`npx @nitra/cursor check docker`** — те саме, що рекомендовано після змін у Dockerfile.
+2. Спочатку викликається бінарник **`hadolint`** з `PATH`; якщо його немає — **`docker run`** з образом **`hadolint/hadolint:v2.12.0`** (тег узгоджуй з **`HADOLINT_IMAGE`** у `npm/scripts/check-docker.mjs`).
+3. Кореневий **`.hadolint.yaml`**: вимкнення правил, trusted registries — [документація](https://github.com/hadolint/hadolint#configure).
+
+Якщо в репозиторії немає жодного відповідного файлу — перевірка пропускається (exit 0).
+
+## Агентам
+
+- Після правок у Dockerfile проганяй **`check docker`**.
+- Винятки: **`# hadolint ignore=DL3008`** (або інший код) у Dockerfile або правила в **`.hadolint.yaml`**.
+- Образи на базі Bun — див. **`n-bun.mdc`**.
+
+## Редактор
+
+Розширення VS Code / Cursor: **`exiasr.hadolint`** (потрібен бінарник hadolint) — за потреби в **`.vscode/extensions.json`**.
+
+## Перевірка
+
+`npx @nitra/cursor check docker`
+
+Kubernetes YAML і `$schema` у `k8s/` — окреме правило **`k8s.mdc`**, **`check k8s`**.

package/mdc/ga.mdc

@@ -33,6 +33,7 @@ jobs:
           save_min_runs_number: 0
 
 ```
+
 Повинен бути файл .github/workflows/clean-merged-branch.yml, зі змістом:
 
 ```yaml

package/mdc/js-lint.mdc

@@ -29,6 +29,7 @@ version: '1.7'
   }
 }
 ```
+
 У корені проєкту має бути `.jscpd.json`. Мінімум: увімкнути облік `.gitignore`, ненульовий код виходу при знаходженні клонів, консольний звіт. За потреби додай `ignore` (дзеркальні каталоги, шаблони) та `minLines`, щоб відсікти дрібні збіги:
 
 ```json title=".jscpd.json"
@@ -125,6 +126,7 @@ export default [
 ```
 
 У монорепо пакети з Vite (frontend) вкажи в секції `vue`, решту — у секції `node` у виклику `getConfig`.
+
 ## Додаткові js правила
 
 Завжди додавай до package.json що підтримується 24+ версія node:
@@ -134,6 +136,7 @@ export default [
   "node": ">=24"
 }
 ```
+
 **Код:** синтаксис Node **24+**, **top level await**.
 
 ## Перевірка

package/mdc/k8s.mdc

@@ -0,0 +1,59 @@
+---
+description: K8s YAML — перший рядок yaml-language-server $schema; перевірка check-k8s за apiVersion/kind
+version: '1.3'
+globs: "**/k8s/**/*.{yaml,yml}"
+alwaysApply: false
+---
+
+# Kubernetes YAML у шляхах з `k8s`
+
+Для кожного файлу `*.yaml` або `*.yml`, у шляху якого є сегмент директорії **`k8s`** (наприклад `site/k8s/base/deployment.yaml`), **перший рядок** — коментар-директива для [YAML Language Server](https://github.com/redhat-developer/yaml-language-server):
+
+```yaml
+# yaml-language-server: $schema=https://...
+```
+
+Далі — вміст маніфесту. Зайвий порожній рядок між коментарем і YAML не додавай, якщо в проєкті не прийнято інше.
+
+**Розширення:** усі маніфести — **`.yaml`**. Виняток: **`kustomization.yml`** (і `kustomization.yaml`) дозволені за іменем.
+
+**Dockerfile / hadolint** — окреме правило **`docker.mdc`** і **`npx @nitra/cursor check docker`**.
+
+## Перевірка
+
+**`npx @nitra/cursor check k8s`** — узгодженість першого рядка (`$schema`), один рядок `# yaml-language-server` на файл, правило для `.yml`, відповідність URL першому YAML-документу (до `---`) за логікою нижче. Якщо під `k8s` немає yaml/yml — перевірку пропущено. Синтаксис YAML і зміст маніфесту скрипт не перевіряє — вручну.
+
+## Що закодовано в `check-k8s.mjs`
+
+При зміні правил синхронно оновлюй **`YANNH_PIN`**, **`YANNH_GROUPS`**.
+
+- Обхід з пропуском `node_modules`, `.git`, `dist`, `coverage`, `.turbo`, `.next`.
+- **`file:`** у `$schema` — URL до apiVersion/kind не звіряється; **`https:`** — kustomization за іменем файлу → Schema Store; `v1` → yannh; група з `YANNH_GROUPS` → yannh; інакше → datree.
+
+## Коли застосовувати (агентам)
+
+- Зміни в k8s YAML — після правок **`check k8s`**.
+- Якщо перший рядок уже коректний і URL відповідає `apiVersion` / `kind` — не дублюй; змінився ресурс — онови лише `$schema`.
+
+## Визначення схеми YAML (канон)
+
+Орієнтир — **перший документ** (до наступного `---`).
+
+1. **Ім’я** `kustomization.yaml` або `kustomization.yml` → `https://json.schemastore.org/kustomization.json`.
+2. **`apiVersion: v1`** → yannh, PIN **`v1.29.1-standalone-strict`**:  
+   `https://raw.githubusercontent.com/yannh/kubernetes-json-schema/<PIN>/<kind>-v1.json`  
+   `<kind>`: літери в нижньому регістрі без роздільників між CamelCase (наприклад `Service` → `service`).
+3. **`apiVersion: group/version`** і **group** у **`YANNH_GROUPS`** у скрипті → yannh:  
+   `https://raw.githubusercontent.com/yannh/kubernetes-json-schema/<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`
+5. **Немає надійного публічного URL** — не вигадуй: залиш коректний `$schema` або `file:` за узгодженням.
+
+## Багатодокументні YAML
+
+Одна схема на файл; скрипт звіряє **перший** документ. Інші `kind` у тому ж файлі — розділи файли або узгодь у рев’ю.
+
+## Редактор
+
+Для `$schema` у VS Code / Cursor: **Red Hat YAML** (`redhat.vscode-yaml`) — за потреби в **`.vscode/extensions.json`**.

package/mdc/text.mdc

@@ -1,7 +1,7 @@
 ---
 description: Обробка та перевірка текстових файлів (cspell, markdownlint-cli2, v8r, CI)
 alwaysApply: true
-version: '1.16'
+version: '1.17'
 ---
 
 **cspell**, **markdownlint-cli2**, **[v8r](https://chris48s.github.io/v8r/)** ([Schema Store](https://www.schemastore.org/)), розширення **DavidAnson.vscode-markdownlint**, workflow **`lint-text`**.
@@ -12,7 +12,8 @@ version: '1.16'
     "dbaeumer.vscode-eslint",
     "github.vscode-github-actions",
     "oxc.oxc-vscode",
-    "DavidAnson.vscode-markdownlint"
+    "DavidAnson.vscode-markdownlint",
+    "redhat.vscode-yaml"
   ]
 }
 ```
@@ -30,7 +31,14 @@ version: '1.16'
 }
 ```
 
-**v8r:** чотири виклики `(bunx v8r "<glob>" || [ $? -eq 98 ])` — exit **98**, якщо glob порожній. **`.v8rignore`** лише коли немає схеми. Враховує `.gitignore`.
+**v8r:** чотири виклики `(bunx v8r "<glob>" || [ $? -eq 98 ])` — exit **98**, якщо glob порожній. Враховує `.gitignore`.
+
+У корені проєкту має бути **`.v8rignore`**: **v8r** шукає схему в [Schema Store](https://www.schemastore.org/); для JSON без запису там перевірка завершується помилкою. Мінімум виключи **`.vscode/extensions.json`** і **`.vscode/settings.json`** (немає стабільної схеми в каталозі). Інші файли без схеми — за тією ж логікою; не розширюй ignore, щоб приховати проблеми там, де схема є.
+
+```text title=".v8rignore"
+.vscode/extensions.json
+.vscode/settings.json
+```
 
 ```json title=".markdownlint-cli2.jsonc"
 {
@@ -52,6 +60,7 @@ version: '1.16'
 У корені проєкту має бути `.cspell.json` і залежності для cspell у кореневому `package.json` (зазвичай `devDependencies`).
 
 Додай workflow `.github/workflows/lint-text.yml`:
+
 ```yaml title=".github/workflows/lint-text.yml"
 name: Lint Text
 
@@ -63,6 +72,7 @@ on:
       - '.cspell.json'
       - '.gitignore'
       - '.markdownlint-cli2.jsonc'
+      - '.v8rignore'
       - '**/*.js'
       - '**/*.ts'
       - '**/*.vue'
@@ -202,7 +212,6 @@ jobs:
 
 Для іншої мови встанови відповідний пакет `@cspell/dict-*`, додай його `cspell-ext.json` у `import` і код мови в `language`. Огляд словників: [streetsidesoftware/cspell-dicts](https://github.com/streetsidesoftware/cspell-dicts).
 
-
 ## Перевірка
 
 `npx @nitra/cursor check text`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nitra/cursor",
-  "version": "1.6.4",
+  "version": "1.6.11",
   "description": "CLI для завантаження cursor-правил (префікс n-) у локальний репозиторій",
   "keywords": [
     "cli",

package/schemas/n-cursor.json

@@ -6,6 +6,10 @@
   "type": "object",
   "additionalProperties": true,
   "properties": {
+    "$schema": {
+      "type": "string",
+      "description": "Посилання на JSON Schema для автодоповнення та валідації в IDE; має збігатися з $id цієї схеми (рекомендовано завжди вказувати)."
+    },
     "rules": {
       "type": "array",
       "description": "Ідентифікатори правил без префікса n- (відповідають файлам n-<id>.mdc).",

package/scripts/check-bun.mjs

@@ -3,6 +3,9 @@
  *
  * Очікує наявність `bun.lock`, забороняє lockfile та артефакти yarn/pnpm, директорію `.yarn`
  * і поле `packageManager` у кореневому `package.json`.
+ *
+ * Якщо в кореневому `package.json` є скрипти з префіксом `lint-`, перевіряє наявність агрегованого
+ * скрипта `lint`, у якому через `bun run <ім’я>` викликаються всі такі скрипти.
  */
 import { existsSync } from 'node:fs'
 import { readFile } from 'node:fs/promises'
@@ -47,6 +50,26 @@ export async function check() {
     } else {
       pass('package.json не містить packageManager')
     }
+
+    const scripts = pkg.scripts && typeof pkg.scripts === 'object' ? pkg.scripts : {}
+    const lintPrefixed = Object.keys(scripts).filter(name => name.startsWith('lint-'))
+    if (lintPrefixed.length > 0) {
+      const aggregate = typeof scripts.lint === 'string' ? scripts.lint : ''
+      if (aggregate.trim()) {
+        const missing = lintPrefixed.filter(name => !aggregate.includes(`bun run ${name}`))
+        if (missing.length > 0) {
+          fail(
+            `Скрипт \`lint\` має викликати всі lint-* через bun run; відсутньо: ${missing.map(s => `\`${s}\``).join(', ')}`
+          )
+        } else {
+          pass('package.json: агрегований `lint` покриває всі `lint-*` скрипти')
+        }
+      } else {
+        fail(
+          `У package.json є скрипти ${lintPrefixed.map(s => `\`${s}\``).join(', ')}, але немає агрегованого \`lint\` — додай скрипт, який запускає їх через \`bun run\``
+        )
+      }
+    }
   }
 
   return exitCode

package/scripts/check-docker.mjs

@@ -0,0 +1,145 @@
+/**
+ * Запускає hadolint для Dockerfile / Containerfile у всьому репозиторії (див. docker.mdc).
+ *
+ * Знаходить Dockerfile, Dockerfile.*, Containerfile, Containerfile.*; пропускає node_modules, .git
+ * тощо. Спочатку бінарник hadolint з PATH, інакше docker run з образом hadolint/hadolint.
+ * Кореневий .hadolint.yaml підхоплюється hadolint автоматично.
+ */
+import { spawnSync } from 'node:child_process'
+import { basename, relative, sep } from 'node:path'
+
+import { pass } from './utils/pass.mjs'
+import { walkDir } from './utils/walkDir.mjs'
+
+/** Тег образу для резервного запуску (узгоджуй з docker.mdc). */
+const HADOLINT_IMAGE = 'hadolint/hadolint:v2.12.0'
+
+/**
+ * Чи є basename Dockerfile / Containerfile (у т.ч. Dockerfile.prod).
+ * @param {string} name basename шляху
+ * @returns {boolean} true для Dockerfile / Dockerfile.* / Containerfile / Containerfile.*
+ */
+function isDockerfileName(name) {
+  const n = name.toLowerCase()
+  if (n === 'dockerfile' || n === 'containerfile') return true
+  if (n.startsWith('dockerfile.') || n.startsWith('containerfile.')) return true
+  return false
+}
+
+/**
+ * Збирає абсолютні шляхи до Dockerfile / Containerfile від кореня cwd.
+ * @param {string} root корінь репозиторію
+ * @returns {Promise<string[]>} відсортовані абсолютні шляхи
+ */
+async function findDockerfilePaths(root) {
+  /** @type {string[]} */
+  const out = []
+  await walkDir(root, p => {
+    if (isDockerfileName(basename(p))) out.push(p)
+  })
+  return out.toSorted((a, b) => a.localeCompare(b))
+}
+
+/**
+ * Відносний шлях від root з прямими слешами (hadolint у контейнері).
+ * @param {string} root корінь
+ * @param {string} absPath абсолютний шлях
+ * @returns {string} відносний шлях з прямими слешами
+ */
+function posixRel(root, absPath) {
+  return relative(root, absPath).split(sep).join('/')
+}
+
+/**
+ * Запуск hadolint: спочатку PATH, інакше Docker.
+ * @param {string} root корінь репозиторію
+ * @param {string} absPath абсолютний шлях до Dockerfile
+ * @returns {{ ok: boolean, stdout: string, stderr: string, via: string }} результат перевірки hadolint та канал запуску
+ */
+function lintDockerfileWithHadolint(root, absPath) {
+  const rel = posixRel(root, absPath)
+  const local = spawnSync('hadolint', [rel], {
+    cwd: root,
+    encoding: 'utf8',
+    maxBuffer: 10 * 1024 * 1024
+  })
+  if (!local.error) {
+    const ok = local.status === 0
+    return {
+      ok,
+      stdout: local.stdout ?? '',
+      stderr: local.stderr ?? '',
+      via: 'hadolint'
+    }
+  }
+  if (local.error.code !== 'ENOENT') {
+    return {
+      ok: false,
+      stdout: '',
+      stderr: local.error.message,
+      via: 'hadolint'
+    }
+  }
+
+  const docker = spawnSync(
+    'docker',
+    ['run', '--rm', '-v', `${root}:/workdir`, '-w', '/workdir', HADOLINT_IMAGE, rel],
+    {
+      cwd: root,
+      encoding: 'utf8',
+      maxBuffer: 10 * 1024 * 1024
+    }
+  )
+  if (docker.error) {
+    return {
+      ok: false,
+      stdout: '',
+      stderr:
+        `Не знайдено hadolint у PATH і не вдалося запустити Docker (${docker.error.message}). ` +
+        `Встанови hadolint (наприклад brew install hadolint) або Docker (див. docker.mdc).`,
+      via: 'docker'
+    }
+  }
+  const ok = docker.status === 0
+  return {
+    ok,
+    stdout: docker.stdout ?? '',
+    stderr: docker.stderr ?? '',
+    via: 'docker'
+  }
+}
+
+/**
+ * Перевіряє Dockerfile / Containerfile через hadolint (docker.mdc).
+ * @returns {Promise<number>} 0 — все OK, 1 — є зауваження або помилка запуску
+ */
+export async function check() {
+  let exitCode = 0
+  const fail = msg => {
+    console.log(`  ❌ ${msg}`)
+    exitCode = 1
+  }
+
+  const root = process.cwd()
+  const files = await findDockerfilePaths(root)
+
+  if (files.length === 0) {
+    pass('Немає Dockerfile / Containerfile — перевірку hadolint пропущено')
+    return 0
+  }
+
+  pass(`Знайдено файлів для hadolint: ${files.length}`)
+
+  for (const abs of files) {
+    const rel = posixRel(root, abs) || basename(abs)
+    const { ok, stdout, stderr, via } = lintDockerfileWithHadolint(root, abs)
+    const tail = (stdout + stderr).trim()
+    if (ok) {
+      pass(`${rel} (${via})`)
+    } else {
+      fail(`${rel} (${via})${tail ? `:\n${tail}` : ''}`)
+    }
+  }
+
+  return exitCode
+}

package/scripts/check-k8s.mjs

@@ -0,0 +1,292 @@
+/**
+ * Перевіряє Kubernetes YAML у шляхах з сегментом `k8s` (див. k8s.mdc).
+ *
+ * Перший рядок `# yaml-language-server: $schema=…`, без дублікатів, розширення `.yaml`
+ * (окрім `kustomization.yml`); URL схеми за першим документом — kustomization / yannh / datree.
+ * Dockerfile — правило docker.mdc, скрипт check-docker.mjs.
+ */
+import { readFile } from 'node:fs/promises'
+import { basename, relative } from 'node:path'
+
+import { pass } from './utils/pass.mjs'
+import { walkDir } from './utils/walkDir.mjs'
+
+/** Версія набору схем yannh — узгоджено з k8s.mdc */
+const YANNH_PIN = 'v1.29.1-standalone-strict'
+
+const KUSTOMIZATION_SCHEMA = 'https://json.schemastore.org/kustomization.json'
+
+const YANNH_BASE = `https://raw.githubusercontent.com/yannh/kubernetes-json-schema/${YANNH_PIN}/`
+
+const DATREE_CRD_BASE = 'https://raw.githubusercontent.com/datreeio/CRDs-catalog/main/CRDs/'
+
+/**
+ * Групи API Kubernetes, для яких у перевірці очікується схема yannh (не datree CRD catalog).
+ * `gateway.networking.k8s.io` та інші розширення поза цим списком — datree.
+ */
+const YANNH_GROUPS = new Set([
+  'admissionregistration.k8s.io',
+  'apiextensions.k8s.io',
+  'apiregistration.k8s.io',
+  'apps',
+  'authentication.k8s.io',
+  'authorization.k8s.io',
+  'autoscaling',
+  'batch',
+  'certificates.k8s.io',
+  'coordination.k8s.io',
+  'discovery.k8s.io',
+  'events.k8s.io',
+  'flowcontrol.apiserver.k8s.io',
+  'internal.apiserver.k8s.io',
+  'networking.k8s.io',
+  'node.k8s.io',
+  'policy',
+  'rbac.authorization.k8s.io',
+  'resource.k8s.io',
+  'scheduling.k8s.io',
+  'storage.k8s.io',
+  'storagemigration.k8s.io'
+])
+
+const MODELINE_RE = /^#\s*yaml-language-server:\s*\$schema=(\S+)\s*$/
+
+/**
+ * Чи містить шлях сегмент директорії `k8s` (рівно ця назва компонента).
+ * @param {string} filePath шлях до файлу
+ * @returns {boolean} true, якщо серед компонентів шляху є каталог `k8s`
+ */
+function pathHasK8sSegment(filePath) {
+  const parts = filePath.split(/[/\\]/u)
+  return parts.includes('k8s')
+}
+
+/**
+ * Збирає всі yaml/yml під деревом від кореня cwd, якщо шлях містить сегмент `k8s`.
+ * @param {string} root корінь репозиторію (cwd)
+ * @returns {Promise<string[]>} відсортовані абсолютні шляхи до файлів
+ */
+async function findK8sYamlFiles(root) {
+  /** @type {string[]} */
+  const out = []
+  await walkDir(root, p => {
+    if (!pathHasK8sSegment(p)) return
+    if (!/\.ya?ml$/iu.test(p)) return
+    out.push(p)
+  })
+  return out.toSorted((a, b) => a.localeCompare(b))
+}
+
+/**
+ * Прибирає BOM і ділить на рядки.
+ * @param {string} content вміст файлу
+ * @returns {string[]} рядки без BOM на початку
+ */
+function toLines(content) {
+  const body = content.startsWith('\uFEFF') ? content.slice(1) : content
+  return body.split(/\r?\n/u)
+}
+
+/**
+ * Вміст після першого рядка (modeline), без провідних порожніх рядків.
+ * @param {string[]} lines рядки файлу
+ * @returns {string} тіло для парсингу першого YAML-документа
+ */
+function yamlBodyAfterModeline(lines) {
+  let i = 1
+  while (i < lines.length && lines[i].trim() === '') i++
+  return lines.slice(i).join('\n')
+}
+
+/**
+ * Перший YAML-документ (до наступного `---` на окремому рядку).
+ * @param {string} body фрагмент YAML
+ * @returns {string} перший документ без зайвих пробілів по краях
+ */
+function firstYamlDocument(body) {
+  const parts = body.split(/^---\s*$/mu)
+  return (parts[0] ?? body).trim()
+}
+
+/**
+ * Витягує `apiVersion` та `kind` з тексту документа (без повного YAML-парсера).
+ * @param {string} doc фрагмент YAML одного документа
+ * @returns {{ apiVersion?: string, kind?: string }} знайдені поля або властивості відсутні
+ */
+function extractApiVersionAndKind(doc) {
+  const av = doc.match(/^\s*apiVersion:\s*(\S+)\s*$/mu)
+  const k = doc.match(/^\s*kind:\s*(\S+)\s*$/mu)
+  return {
+    apiVersion: av?.[1]?.replaceAll(/^["']|["']$/gu, ''),
+    kind: k?.[1]?.replaceAll(/^["']|["']$/gu, '')
+  }
+}
+
+/**
+ * Kind для імен файлів yannh/datree: лише літери та цифри, нижній регістр (Service → service, HTTPRoute → httproute).
+ * @param {string} kind значення поля kind
+ * @returns {string} рядок для шаблону імені файлу схеми
+ */
+function kindToSchemaFilePart(kind) {
+  return kind.replaceAll(/[^a-zA-Z0-9]/gu, '').toLowerCase()
+}
+
+/**
+ * Очікуваний $schema для маніфесту згідно з k8s.mdc.
+ * @param {string} filePath шлях до файлу (для імені kustomization)
+ * @param {string} doc перший YAML-документ після modeline
+ * @returns {{ expected: string | null, reason: string }} reason — для повідомлень про помилку
+ */
+function expectedSchemaUrl(filePath, doc) {
+  const base = basename(filePath)
+  const baseLower = base.toLowerCase()
+
+  if (baseLower === 'kustomization.yaml' || baseLower === 'kustomization.yml') {
+    return { expected: KUSTOMIZATION_SCHEMA, reason: 'kustomization (ім’я файлу)' }
+  }
+
+  const { apiVersion, kind } = extractApiVersionAndKind(doc)
+  if (!apiVersion || !kind) {
+    return {
+      expected: null,
+      reason: 'не знайдено apiVersion/kind у першому документі (потрібні для перевірки $schema)'
+    }
+  }
+
+  if (apiVersion === 'v1') {
+    const k = kindToSchemaFilePart(kind)
+    return { expected: `${YANNH_BASE}${k}-v1.json`, reason: 'core v1 (yannh)' }
+  }
+
+  if (!apiVersion.includes('/')) {
+    return {
+      expected: null,
+      reason: `нестандартний apiVersion "${apiVersion}" — очікується v1 або group/version`
+    }
+  }
+
+  const slash = apiVersion.indexOf('/')
+  const group = apiVersion.slice(0, Math.max(0, slash))
+  const version = apiVersion.slice(slash + 1)
+  const kindPart = kindToSchemaFilePart(kind)
+  const groupDash = group.replaceAll('.', '-')
+
+  if (YANNH_GROUPS.has(group)) {
+    const url = `${YANNH_BASE}${kindPart}-${groupDash}-${version}.json`
+    return { expected: url, reason: 'вбудований API Kubernetes (yannh)' }
+  }
+
+  const datreeKind = kindToSchemaFilePart(kind)
+  const url = `${DATREE_CRD_BASE}${group}/${datreeKind}_${version}.json`
+  return { expected: url, reason: 'CRD / група поза yannh (datree CRDs-catalog)' }
+}
+
+/**
+ * Підраховує рядки з modeline $schema у файлі.
+ * @param {string[]} lines рядки файлу
+ * @returns {number} скільки рядків містять modeline `$schema`
+ */
+function countSchemaModelines(lines) {
+  return lines.filter(l => /^\s*#\s*yaml-language-server:\s*\$schema=\S+/u.test(l.trim())).length
+}
+
+/**
+ * Перевіряє один YAML у дереві k8s (modeline, схема).
+ * @param {string} abs абсолютний шлях до файлу
+ * @param {string} root корінь репозиторію
+ * @param {(msg: string) => void} fail реєстрація помилки
+ * @param {(msg: string) => void} pass реєстрація успіху
+ * @returns {Promise<void>}
+ */
+async function checkK8sYamlFile(abs, root, fail, pass) {
+  const rel = relative(root, abs) || abs
+  const base = basename(abs)
+  const baseLower = base.toLowerCase()
+
+  if (baseLower.endsWith('.yml') && baseLower !== 'kustomization.yml') {
+    fail(`${rel}: розширення .yml — перейменуй на .yaml (див. k8s.mdc)`)
+    return
+  }
+
+  let raw
+  try {
+    raw = await readFile(abs, 'utf8')
+  } catch (error) {
+    fail(`${rel}: не вдалося прочитати (${error.message})`)
+    return
+  }
+
+  const lines = toLines(raw)
+  if (lines.length === 0 || lines[0].trim() === '') {
+    fail(`${rel}: перший рядок порожній — потрібен # yaml-language-server: $schema=…`)
+    return
+  }
+
+  const m = lines[0].match(MODELINE_RE)
+  if (!m) {
+    fail(
+      `${rel}: перший рядок має бути коментарем # yaml-language-server: $schema=<url> (без префіксів перед #)`
+    )
+    return
+  }
+
+  const schemaUrl = m[1]
+  if (countSchemaModelines(lines) > 1) {
+    fail(`${rel}: кілька рядків yaml-language-server $schema — лиш один modeline на файл (див. k8s.mdc)`)
+    return
+  }
+
+  if (schemaUrl.startsWith('file:')) {
+    pass(`${rel}: локальна схема (file:) — перевірка URL за apiVersion/kind пропущена`)
+    return
+  }
+
+  if (!/^https:/iu.test(schemaUrl)) {
+    fail(`${rel}: $schema має бути https URL або file: (див. k8s.mdc)`)
+    return
+  }
+
+  const body = yamlBodyAfterModeline(lines)
+  const doc = firstYamlDocument(body)
+  const { expected, reason } = expectedSchemaUrl(abs, doc)
+
+  if (expected === null) {
+    fail(`${rel}: ${reason}`)
+    return
+  }
+
+  if (schemaUrl !== expected) {
+    fail(`${rel}: $schema не відповідає правилу (${reason}). Очікується:\n     ${expected}\n     Зараз: ${schemaUrl}`)
+    return
+  }
+
+  pass(`${rel}: $schema узгоджено (${reason})`)
+}
+
+/**
+ * Перевіряє відповідність проєкту правилам k8s.mdc.
+ * @returns {Promise<number>} 0 — все OK, 1 — є проблеми
+ */
+export async function check() {
+  let exitCode = 0
+  const fail = msg => {
+    console.log(`  ❌ ${msg}`)
+    exitCode = 1
+  }
+
+  const root = process.cwd()
+  const yamlFiles = await findK8sYamlFiles(root)
+
+  if (yamlFiles.length === 0) {
+    pass('Немає yaml/yml під k8s — перевірку $schema пропущено')
+    return 0
+  }
+
+  pass(`YAML у k8s: ${yamlFiles.length} файл(ів)`)
+
+  for (const abs of yamlFiles) {
+    await checkK8sYamlFile(abs, root, fail, pass)
+  }
+
+  return exitCode
+}

package/scripts/check-text.mjs

@@ -1,8 +1,8 @@
 /**
  * Перевіряє текстовий стек за правилом text.mdc.
  *
- * cspell, markdownlint-cli2, скрипт `lint-text` з чотирма викликами v8r, workflow `lint-text.yml`,
- * розширення VSCode для markdownlint.
+ * cspell, markdownlint-cli2, скрипт `lint-text` з чотирма викликами v8r, `.v8rignore` (vscode JSON),
+ * workflow `lint-text.yml`, розширення VSCode для markdownlint.
  */
 import { existsSync } from 'node:fs'
 import { readFile } from 'node:fs/promises'
@@ -20,6 +20,24 @@ export async function check() {
     exitCode = 1
   }
 
+  const v8rIgnoreRequired = ['.vscode/extensions.json', '.vscode/settings.json']
+  if (existsSync('.v8rignore')) {
+    const raw = await readFile('.v8rignore', 'utf8')
+    const lines = new Set(raw
+      .split('\n')
+      .map(l => l.trim())
+      .filter(l => l.length > 0 && !l.startsWith('#')))
+    for (const path of v8rIgnoreRequired) {
+      if (lines.has(path)) {
+        pass(`.v8rignore містить ${path}`)
+      } else {
+        fail(`.v8rignore: додай рядок "${path}" (JSON без схеми в Schema Store — див. n-text.mdc)`)
+      }
+    }
+  } else {
+    fail('.v8rignore не існує — створи згідно n-text.mdc (мінімум .vscode/extensions.json і .vscode/settings.json)')
+  }
+
   if (existsSync('.vscode/extensions.json')) {
     try {
       const ext = JSON.parse(await readFile('.vscode/extensions.json', 'utf8'))

package/scripts/utils/walkDir.mjs

@@ -0,0 +1,41 @@
+/**
+ * Рекурсивний обхід каталогів для скриптів перевірки (Dockerfile, k8s YAML тощо).
+ *
+ * Обходить дерево від заданого кореня; для кожного звичайного файлу викликає переданий callback.
+ * Каталоги node_modules, .git, dist, coverage, .turbo, .next не заходяться. Якщо readdir для
+ * каталогу не вдається — тихо виходить без throw.
+ */
+import { readdir } from 'node:fs/promises'
+import { join } from 'node:path'
+
+/**
+ * Рекурсивно обходить каталог, пропускає типові артефакти збірки та залежностей.
+ * @param {string} dir абсолютний шлях
+ * @param {(filePath: string) => void} onFile виклик для кожного файлу
+ * @returns {Promise<void>}
+ */
+export async function walkDir(dir, onFile) {
+  let entries
+  try {
+    entries = await readdir(dir, { withFileTypes: true })
+  } catch {
+    return
+  }
+  for (const e of entries) {
+    const p = join(dir, e.name)
+    if (e.isDirectory()) {
+      const skipDir =
+        e.name === 'node_modules' ||
+        e.name === '.git' ||
+        e.name === 'dist' ||
+        e.name === 'coverage' ||
+        e.name === '.turbo' ||
+        e.name === '.next'
+      if (!skipDir) {
+        await walkDir(p, onFile)
+      }
+    } else if (e.isFile()) {
+      onFile(p)
+    }
+  }
+}