@nitra/cursor 1.8.219 → 1.8.221

package/CHANGELOG.md

@@ -4,6 +4,18 @@
 
 Формат — [Keep a Changelog](https://keepachangelog.com/uk/1.1.0/), нумерація — [SemVer](https://semver.org/lang/uk/).
 
+## [1.8.221] - 2026-05-10
+
+### Changed
+
+- **ci4.mdc:** наповнено правило людинозрозумілим описом C4-моделі як джерела істини. Markdown-файли (C4 + ADR + тести + документація) — офіційне джерело істини про проєкт. Перед змінами агент аналізує відповідні C4-файли; кожна зміна, що впливає на модель, супроводжується оновленням C4-схеми у тому ж PR. ADR описує вплив рішення на C4 (які контейнери/компоненти з'являються/зникають/змінюють відповідальність). Кожен C4-компонент має посилання на відповідні тести. C4-схеми — частина користувацької документації, не закритий артефакт. Алгоритмічної `check-ci4.mjs` поки немає — правило процесне; `## Перевірка` залишено для майбутньої формалізації.
+
+## [1.8.220] - 2026-05-09
+
+### Fixed
+
+- **k8s / `prodOverlayHpaPdbOverrideNeeds`:** виключено Kustomize Component (`kind: Component`) з prod-overlay-перевірки. Раніше `<pkg>/k8s/components/kustomization.yaml` помилково тригерив `прод-оверлей має перевизначати spec.minReplicas/maxReplicas/minAvailable` — але Component є **джерелом** ресурсів для overlays, не overlay сам по собі. Прод-перезаписи живуть у `ru/` / `ua/` / `prod/` тощо, що підключають Component через `components:`. Додано ранній return за `kind: Component` у `npm/scripts/check-k8s.mjs`; уточнення додано до `npm/mdc/k8s.mdc` і регресійний тест у `npm/tests/check-k8s-schema.test.mjs`.
+
 ## [1.8.219] - 2026-05-09
 
 ### Added

package/bin/n-cursor.js

@@ -1137,7 +1137,8 @@ async function readBundledVersionAt(packageRoot) {
  * бо ES-модулі вже завантажені у V8 (RULE_MIGRATIONS, detectAutoRules тощо) і нова логіка
  * без повної заміни процесу не підхопиться. Захист від нескінченного циклу — env `NITRA_CURSOR_REEXEC=1`.
  * @param {string} effectivePackageRoot шлях, повернутий `upgradeNitraCursorToLatestAndBunInstall`
- * @returns {Promise<void>} повертається лише якщо re-exec не потрібен (інакше викликає `process.exit`)
+ * @returns {Promise<void>} повертається лише якщо re-exec не потрібен; інакше кидає `ReexecHandoff`,
+ *   який ловить top-level catch і прокидає exit-код у `process.exitCode`
  */
 async function reexecIfPackageVersionChanged(effectivePackageRoot) {
   if (env.NITRA_CURSOR_REEXEC === '1') {
@@ -1167,7 +1168,23 @@ async function reexecIfPackageVersionChanged(effectivePackageRoot) {
   if (result.error) {
     throw result.error
   }
-  process.exit(typeof result.status === 'number' ? result.status : 1)
+  throw new ReexecHandoff(typeof result.status === 'number' ? result.status : 1)
+}
+
+/**
+ * Сентинельна помилка, яку кидає `reexecIfPackageVersionChanged` після успішного re-exec.
+ * Top-level catch розпізнає її й виставляє `process.exitCode = code` без stack-trace —
+ * процес тоді коректно завершується з тим самим кодом, що й child re-exec-у.
+ */
+class ReexecHandoff extends Error {
+  /**
+   * @param {number} code exit-код, який повернув child-процес
+   */
+  constructor(code) {
+    super('reexec-handoff')
+    this.name = 'ReexecHandoff'
+    this.code = code
+  }
 }
 
 /**
@@ -1329,6 +1346,10 @@ try {
       process.exitCode = 1
     }
   }
-} catch {
-  process.exitCode = 1
+} catch (error) {
+  if (error instanceof ReexecHandoff) {
+    process.exitCode = error.code
+  } else {
+    process.exitCode = 1
+  }
 }

package/mdc/ci4.mdc

@@ -0,0 +1,51 @@
+---
+description: Дизайн проєкту за C4 model (https://c4model.com); Markdown — джерело істини про архітектуру, рішення, тести й документацію
+alwaysApply: true
+version: '1.0'
+---
+
+C4-діаграми проєкту живуть у Markdown поряд із кодом. Це не довідник «для людей із порталу
+архітектора» — це **джерело істини**, з якого LLM-агент і людина читають намір системи перед
+будь-якою зміною коду. Тому правила нижче — не оформлення, а робочий процес.
+
+## Markdown як джерело істини
+
+Уся ключова інформація про проєкт — архітектура (C4), рішення (ADR), тести й документація —
+зберігається у `.md`/`.mdc`-файлах і є **офіційним джерелом істини**. Це єдиний спосіб
+тримати знання разом із кодом — версійно, в одному PR і доступно для агентів. Якщо щось
+важливе про систему існує лише у Confluence/Notion/месенджері — для проєкту цього **немає**.
+
+## Аналіз перед зміною
+
+Перш ніж вносити зміни, агент **читає відповідні C4-файли**: контекст, контейнери, компоненти
+тієї ділянки, до якої входить редагований код. Без цього кроку легко зламати приховані
+залежності між контейнерами або «загубити» зовнішню інтеграцію.
+
+## Оновлення синхронно зі змінами
+
+Кожна зміна, що впливає на C4-модель — нова інтеграція, новий компонент, перейменування,
+зміна напрямку залежності, видалення сервісу — **супроводжується оновленням C4-схеми у тому ж
+PR**. C4 не оновлюється «потім» окремою задачею: розсинхрон між кодом і моделлю — найчастіша
+причина, чому архітектурні документи перестають читати.
+
+## Зв'язок із ADR
+
+ADR (`docs/adr/`) описує **вплив рішення на C4**: які контейнери/компоненти з'являються,
+зникають, змінюють відповідальність. Якщо рішення суттєве — у тілі ADR явно пишемо, які
+C4-схеми потрібно оновити, і робимо це у тому ж PR.
+
+## Зв'язок із тестами
+
+Кожен C4-компонент має **посилання на відповідні тести** — інтеграційні, e2e або юніт залежно
+від рівня. Так перехід «компонент → як його перевіряємо» займає один клік, а не пошук по
+репозиторію.
+
+## Зв'язок із документацією
+
+C4-схеми — частина **користувацької документації**, а не закритий артефакт для команди.
+Контекстна діаграма (рівень 1) і контейнерна (рівень 2) живуть там, де читач шукає вступ у
+проєкт, а не у відокремленій теці «for-architects».
+
+## Перевірка
+
+`npx @nitra/cursor check ci4`

package/mdc/k8s.mdc

@@ -387,6 +387,8 @@ images:
 
 **Overlays** (`ua/`, `ru/`, прод-overlays) підключають `components: [- ../components]` і додають JSON6902-патчі для прод-значень: `/spec/minReplicas`, `/spec/maxReplicas` (HPA), `/spec/minAvailable` (PDB). Dev-середовище (`base`) HPA/PDB не отримує — як і потрібно.
 
+**`<pkg>/k8s/components/kustomization.yaml`** має `kind: Component` (не `kind: Kustomization`) — це **джерело** канонічних HPA/PDB для всіх overlays, а не overlay сам по собі. Прод-перезаписи (`/spec/minReplicas`, `/spec/maxReplicas`, `/spec/minAvailable`) живуть у `<env>/kustomization.yaml`, що підключає Component через `components:`. У самому Component patches не потрібні — він env-неутральний; **`check k8s`** не вимагає прод-патчів від `components/kustomization.yaml`.
+
 У **не-base** оверлеях (без `components/`) поруч із `Deployment` лишається звична схема: окремий **`hpa.yaml`** / **`pdb.yaml`**, якщо такі потрібні для цього середовища. **`check k8s`** звіряє прив'язку за іменами:
 
 - **`hpa.yaml`** (поза **`…/base/`**) — `autoscaling/v2`, `HorizontalPodAutoscaler`, `spec.scaleTargetRef.name` **= `metadata.name`** Deployment.

package/package.json

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

package/scripts/auto-skills.mjs

@@ -12,7 +12,14 @@
  */
 
 /** Порядок автододавання skills відповідно до `auto-skills.md`. */
-export const AUTO_SKILL_ORDER = Object.freeze(['abie-kustomize', 'fix', 'lint', 'llm-patch', 'publish-telegram', 'taze'])
+export const AUTO_SKILL_ORDER = Object.freeze([
+  'abie-kustomize',
+  'fix',
+  'lint',
+  'llm-patch',
+  'publish-telegram',
+  'taze'
+])
 
 /**
  * Залежність скілів від правил (`auto-skills.md` синтаксис `skill - [rules]`).

package/scripts/check-bun.mjs

@@ -104,10 +104,10 @@ export async function check() {
     fail('Відсутній bun.lock — запусти bun i')
   }
 
-  if (!existsSync('bunfig.toml')) {
-    fail('Відсутній bunfig.toml — створи з [install] linker = "hoisted" (bun.mdc)')
-  } else {
+  if (existsSync('bunfig.toml')) {
     pass('bunfig.toml є (структуру перевіряє bun run lint-conftest → bun.bunfig)')
+  } else {
+    fail('Відсутній bunfig.toml — створи з [install] linker = "hoisted" (bun.mdc)')
   }
 
   const cursorRules = await loadNCursorRules()

package/scripts/check-changelog.mjs

@@ -160,9 +160,8 @@ async function readBaseVersion(baseRef, ws) {
  * @returns {boolean} `true`, якщо запис для `version` знайдено
  */
 function changelogHasVersionEntry(text, version) {
-  const escaped = version.replaceAll(/[.+*?^$()[\]{}|\\]/g, String.raw`\$&`)
-  const re = new RegExp(String.raw`^##\s+\[${escaped}\]`, 'm')
-  return re.test(text)
+  const needle = `## [${version}]`
+  return text.startsWith(needle) || text.includes(`\n${needle}`)
 }
 
 /**

package/scripts/check-image-avif.mjs

@@ -3,9 +3,9 @@
  * ув'язування `.avif`-двійників з посиланнями у `.vue`/`.html`.
  *
  * Дії під час `check image-avif`:
- * 1. `npx @nitra/minify-image --src=. --write --avif` — генерує AVIF-двійники.
+ * 1. `npx \@nitra/minify-image --src=. --write --avif` — генерує AVIF-двійники.
  * 2. У кожному workspace-пакеті переписує raster-посилання у `.vue`/`.html` на `.avif`
- *    (де AVIF-двійник реально існує на диску). Pakety з `"@nitra/minify-image": {
+ *    (де AVIF-двійник реально існує на диску). Pakety з `"\@nitra/minify-image": {
  *    "disable-avif": true }` у `package.json` пропускаються.
  * 3. Прибирає AVIF-сироти — `<name>.<ext>.avif`, на які не лишилось жодного посилання
  *    у `.vue`/`.html` репозиторію, видаляються (умова правила: «AVIF лишається лише
@@ -27,13 +27,14 @@ import { env } from 'node:process'
 
 import { createCheckReporter } from './utils/check-reporter.mjs'
 import { loadCursorIgnorePaths } from './utils/load-cursor-config.mjs'
+import { resolveCmd } from './utils/resolve-cmd.mjs'
 import { walkDir } from './utils/walkDir.mjs'
 import { getMonorepoPackageRootDirs } from './utils/workspaces.mjs'
 
 /** Імʼя CLI-пакета, який генерує AVIF. */
 const MINIFY_PACKAGE_NAME = '@nitra/minify-image'
 
-/** Поле в `package.json` для конфігу @nitra/minify-image (наприклад, `disable-avif`). */
+/** Поле в `package.json` для конфігу `\@nitra/minify-image` (наприклад, `disable-avif`). */
 const PKG_CONFIG_FIELD = '@nitra/minify-image'
 
 /**
@@ -279,7 +280,7 @@ async function checkVueAvifImports(ignorePaths, usedAvifAbs, stats, pass, fail)
 
 /**
  * Чи є в репозиторії хоч один raster-файл, який мав би сенс конвертувати у AVIF.
- * Якщо немає — `npx @nitra/minify-image` нема що робити, тож зайвий запуск пропускаємо
+ * Якщо немає — `npx \@nitra/minify-image` нема що робити, тож зайвий запуск пропускаємо
  * (важливо у тестах: фікстурні `.png`-імпорти посилаються на неіснуючі файли, тож
  * minify-image все одно нічого не згенерує — а зайвий npx-спавн повільний і робить шум).
  * @param {string[]} ignorePaths абсолютні шляхи каталогів, повністю виключених з обходу
@@ -299,7 +300,7 @@ async function hasAnyRasterImage(ignorePaths) {
 }
 
 /**
- * Запускає `npx @nitra/minify-image --src=. --write --avif` для генерації AVIF-двійників.
+ * Запускає `npx \@nitra/minify-image --src=. --write --avif` для генерації AVIF-двійників.
  *
  * Виклик best-effort: якщо мережа/кеш недоступні чи бінарника нема — лог-варн без падіння
  * перевірки (валідації package.json і vue-refs все одно прогоняться, vue-refs на
@@ -309,7 +310,14 @@ async function hasAnyRasterImage(ignorePaths) {
  */
 function runAvifGeneration() {
   if (env.NITRA_CURSOR_NO_AVIF_RUN === '1') return
-  const result = spawnSync('npx', [MINIFY_PACKAGE_NAME, '--src=.', '--write', '--avif'], {
+  const npxPath = resolveCmd('npx')
+  if (!npxPath) {
+    console.log(
+      `  ⚠️  'npx' не знайдено в PATH — пропускаємо генерацію AVIF; vue/html-перевірка покаже файли, для яких не вистачає .avif`
+    )
+    return
+  }
+  const result = spawnSync(npxPath, [MINIFY_PACKAGE_NAME, '--src=.', '--write', '--avif'], {
     stdio: 'inherit',
     env
   })

package/scripts/check-image-compress.mjs

@@ -11,7 +11,7 @@
  *
  * **Що покрила Rego** (`bun run lint-conftest`,
  * `npm/policy/image_compress/package_json/`):
- *  - `scripts.lint-image` викликає `npx @nitra/minify-image --src=. --write`
+ *  - `scripts.lint-image` викликає `npx \@nitra/minify-image --src=. --write`
  *    без `--avif` (AVIF — окреме правило `image-avif`);
  *  - агрегований `lint` (якщо є) містить `bun run lint-image`;
  *  - `@nitra/minify-image` НЕ у `dependencies` / `devDependencies` (через `npx`).

package/scripts/check-js-run.mjs

@@ -207,35 +207,56 @@ async function checkConnFileNamingAndExports(absPackageRoot, sourcePaths, pkgJso
   let violations = 0
   for (const absPath of sourcePaths) {
     const rel = relPosix(absPackageRoot, absPath)
-    if (!isInsideConnDir(rel, connDir)) continue
-    if (!isConnFileRulesSourceFile(rel)) continue
-    // пропускаємо реекспортний барель `index.*` (якщо знадобиться) і прихований .d.ts
-    const base = rel.slice(rel.lastIndexOf('/') + 1)
-    if (base.startsWith('index.')) continue
-
+    if (!isConnFileToCheck(rel, connDir)) continue
     const content = await readFile(absPath, 'utf8')
     for (const v of findConnFileRuleViolations(content, rel)) {
       violations++
-      if (v.kind === 'name') {
-        fail(
-          `${label}${rel} — назва файла в '${connDir}/' не відповідає канону js-run: ` +
-            `'ql-<id>', 'pg-{read|write}[-<id>]', 'mysql-{read|write}[-<id>]' або 'mssql-{read|write}[-<id>]' ` +
-            `(kebab-case, [a-z0-9-])`
-        )
-      } else if (v.kind === 'default-export') {
-        fail(`${label}${rel} — 'export default' заборонений у '${connDir}/'; зроби іменований експорт`)
-      } else {
-        const found = v.foundNames?.length ? v.foundNames.join(', ') : '—'
-        fail(
-          `${label}${rel} — очікується іменований експорт 'export const ${v.expectedName} = …' ` +
-            `(camelCase від назви файла); знайдено: ${found}`
-        )
-      }
+      fail(formatConnFileViolation(v, label, rel, connDir))
     }
   }
   return violations
 }
 
+/**
+ * Чи `rel` — це conn-файл, який треба валідувати: під `connDir/`, з JS/TS-розширенням,
+ * не `index.*` (який є реекспортним барелем).
+ * @param {string} rel відносний шлях у posix-форматі
+ * @param {string} connDir каталог conn-файлів (наприклад `src/conn`)
+ * @returns {boolean} true, якщо файл потрібно перевірити
+ */
+function isConnFileToCheck(rel, connDir) {
+  if (!isInsideConnDir(rel, connDir)) return false
+  if (!isConnFileRulesSourceFile(rel)) return false
+  const base = rel.slice(rel.lastIndexOf('/') + 1)
+  return !base.startsWith('index.')
+}
+
+/**
+ * Будує повідомлення про конкретне порушення canon-у файла з `connDir/`.
+ * @param {{ kind: 'name' | 'default-export' | 'export-name', expectedName?: string, foundNames?: string[] }} v опис порушення
+ * @param {string} label префікс повідомлення `[<pkg>] `
+ * @param {string} rel відносний шлях файла
+ * @param {string} connDir каталог conn-файлів
+ * @returns {string} повний текст повідомлення для `fail(...)`
+ */
+function formatConnFileViolation(v, label, rel, connDir) {
+  if (v.kind === 'name') {
+    return (
+      `${label}${rel} — назва файла в '${connDir}/' не відповідає канону js-run: ` +
+      `'ql-<id>', 'pg-{read|write}[-<id>]', 'mysql-{read|write}[-<id>]' або 'mssql-{read|write}[-<id>]' ` +
+      `(kebab-case, [a-z0-9-])`
+    )
+  }
+  if (v.kind === 'default-export') {
+    return `${label}${rel} — 'export default' заборонений у '${connDir}/'; зроби іменований експорт`
+  }
+  const found = v.foundNames?.length ? v.foundNames.join(', ') : '—'
+  return (
+    `${label}${rel} — очікується іменований експорт 'export const ${v.expectedName} = …' ` +
+    `(camelCase від назви файла); знайдено: ${found}`
+  )
+}
+
 /**
  * Перевіряє правило «CheckEnv» для пакета.
  * @param {string} absPackageRoot абсолютний корінь пакета
@@ -297,12 +318,12 @@ async function checkPromiseSetTimeoutPause(absPackageRoot, sourcePaths, label, f
 async function checkWorkspacePackage(rootDir, ignorePaths, workflows, fail, passFn) {
   const label = `[${rootDir}] `
   const absPackageRoot = join(process.cwd(), rootDir)
-  const pkgJson = await loadPackageJsonAndCheckBunyanDeps(rootDir, label, fail)
+  const pkgJson = await loadPackageJson(rootDir)
 
   // Frontend-пакети (vite у devDependencies) виходять за межі js-run:
   // браузерний бандл не має `node:process`, а `process.env.*` бандлер
-  // обробляє самостійно. Перевірку process.env / conn-аліасів пропускаємо,
-  // bunyan-залежність уже звірено в `loadPackageJsonAndCheckBunyanDeps`.
+  // обробляє самостійно. Перевірку process.env / conn-аліасів пропускаємо;
+  // bunyan-залежність валідується в Rego (`bun run lint-conftest`).
   if (packageJsonHasViteDevDependency(pkgJson)) {
     passFn(`${label}vite-пакет (frontend) — js-run пропущено (process.env / conn-aliases / OTEL configmap)`)
     return
@@ -343,7 +364,7 @@ async function checkWorkspacePackage(rootDir, ignorePaths, workflows, fail, pass
     passFn(`${label}немає 'new Promise(r => setTimeout(r, ms))' — паузи через 'node:timers/promises'`)
   }
 
-  await checkOtelConfigmap(rootDir, label, fail, passFn)
+  checkOtelConfigmap(rootDir, passFn)
 
   checkDepcheckInWorkflows(rootDir, workflows, label, fail, passFn)
 }
@@ -388,41 +409,31 @@ function packageJsonHasViteDevDependency(pkgJson) {
 }
 
 /**
- * Завантажує `package.json` пакета (якщо є) і реєструє порушення для bunyan-залежностей.
+ * Завантажує `package.json` пакета (якщо є). Заборону `@nitra/bunyan` / `bunyan`
+ * у dependencies/devDependencies перенесено в Rego (`npm/policy/js_run/package_json/`);
+ * `bun run lint-conftest` запускає її по всіх workspace `package.json`. Тут лишилася
+ * лише AST-перевірка імпортів.
  * @param {string} rootDir відносний шлях workspace
- * @param {string} label префікс повідомлення `[<pkg>] `
- * @param {(msg: string) => void} fail callback при помилці
  * @returns {Promise<unknown>} розпарсений package.json або null
  */
-async function loadPackageJsonAndCheckBunyanDeps(rootDir, label, fail) {
+async function loadPackageJson(rootDir) {
   const pkgPath = join(rootDir, 'package.json')
   if (!existsSync(pkgPath)) return null
-  const pkgJson = JSON.parse(await readFile(pkgPath, 'utf8'))
-  // Заборону `@nitra/bunyan` / `bunyan` у dependencies/devDependencies перенесено
-  // в Rego (`npm/policy/js_run/package_json/`); `bun run lint-conftest` запускає
-  // її по всіх workspace `package.json`. Тут лишилася лише AST-перевірка імпортів.
-  void label
-  void fail
-  return pkgJson
+  return JSON.parse(await readFile(pkgPath, 'utf8'))
 }
 
 /**
- * Перевіряє вміст `k8s/base/configmap.yaml` пакета на наявність OTEL_RESOURCE_ATTRIBUTES
- * з обов'язковими `service.name=` та `service.namespace=` всередині.
+ * Перевіряє наявність `k8s/base/configmap.yaml` пакета. Структуру (наявність
+ * `OTEL_RESOURCE_ATTRIBUTES` з обов'язковими `service.name=` / `service.namespace=`)
+ * перенесено в Rego (`npm/policy/js_run/configmap/`); `bun run lint-conftest`
+ * запускає її на всіх `k8s/base/configmap.yaml`.
  * @param {string} rootDir відносний шлях workspace
- * @param {string} label префікс повідомлення `[<pkg>] `
- * @param {(msg: string) => void} fail callback при помилці
  * @param {(msg: string) => void} passFn успішне повідомлення
- * @returns {Promise<void>} завершується після перевірки configmap
+ * @returns {void}
  */
-function checkOtelConfigmap(rootDir, label, fail, passFn) {
+function checkOtelConfigmap(rootDir, passFn) {
   const configmapPath = join(rootDir, 'k8s', 'base', 'configmap.yaml')
   if (!existsSync(configmapPath)) return
-  // Перевірку `OTEL_RESOURCE_ATTRIBUTES` має містити `service.name=` /
-  // `service.namespace=` перенесено в Rego (`npm/policy/js_run/configmap/`);
-  // `bun run lint-conftest` запускає її на всіх `k8s/base/configmap.yaml`.
-  void label
-  void fail
   passFn(`${rootDir}/k8s/base/configmap.yaml є (OTEL — bun run lint-conftest → js_run.configmap)`)
 }