@nitra/cursor 3.0.0 → 3.2.0

package/CHANGELOG.md

@@ -1,5 +1,32 @@
 # Changelog
 
+## [3.2.0] - 2026-06-01
+
+### Added
+
+- docker: правило «нативний .node-аддон не компілювати» — sharp/@img/*/argon2 у deps + `bun build --compile` прапорцюється (компілятор не вшиває динамічний require → краш у рантаймі); канон — node_modules + `bun <entry>` на mirror.gcr.io/oven/bun:alpine (легітимний bun-рантайм як фінальний stage). lib/docker-native-addon.mjs + інтеграція в js/lint.mjs
+
+### Changed
+
+- CLI sync: блоки Skills/Commands/Pi skills (разом із рядками ⬇) друкуються лише за наявності помилок — за чистого прогону вивід коротший
+- js-lint-ci правило стало Auto Attached (glob як у js-lint) замість alwaysApply — не висить у кожному контексті, тригериться на JS/конфіги лінтерів
+- правила js-lint: knip/dependency-аналіз перенесено з js-lint у js-lint-ci (його декларована зона); додано заборону @nitra/as-integrations-fastify з міграцією на @as-integrations/fastify ^3.1.0 (specifier-only, код незмінний)
+
+### Fixed
+
+- worktree-only skills: preflight сам створює worktree від поточної гілки з коротким суфіксом без запиту назви
+
+## [3.1.0] - 2026-06-01
+
+### Added
+
+- docker: для фінального nginx-unprivileged stage — окрема non-root-перевірка (lib/docker-nginx-user.mjs): жодного USER root/switch-back USER 101|nginx, COPY/ADD лише з --chown=nginx:nginx; gzip під дефолтним uid=101
+
+### Changed
+
+- worktree-only skills: банер у SKILL.md став жорстким fail-fast preflight (Крок 0, STOP/ABORT) замість поради; CLAUDE.md отримав секцію-правило про worktree:true скіли
+- vue: увесь стек auto-import (заборона value-імпортів з vue, вимога 'vue' у AutoImport.imports та наявності VueMacros/AutoImport у vite.config) не застосовується до бібліотек компонентів — пакетів із vue у peerDependencies (їхні джерела не проходять через unplugin-auto-import споживача); інші перевірки (esbuild, npm_lifecycle_event) лишаються; додано isVueComponentLibraryPkg
+
 ## [3.0.0] - 2026-06-01
 
 ### Added

package/bin/n-cursor.js

@@ -641,6 +641,21 @@ function buildClaudeLintParallelismSectionLines() {
   ]
 }
 
+/**
+ * Рендерить секцію для CLAUDE.md: скіли з `meta.json.worktree === true` запускаються
+ * лише в окремому git-worktree (дублює fail-fast банер `SKILL.md` як завжди-читане правило).
+ * @returns {string[]} рядки для вставки (з порожнім рядком на початку)
+ */
+function buildClaudeWorktreeEnforcementSectionLines() {
+  return [
+    '',
+    '## Worktree-only skills (`meta.json` → `worktree: true`)',
+    '',
+    'Скіл із **`worktree: true`** у `meta.json` запускається **виключно** в окремому git-worktree (`.worktrees/<current-branch>-<suffix>/`) — **не** в основному дереві й **не** паралельно. Перший крок такого скіла (блок `n-cursor:worktree:start` у його `SKILL.md`) — **preflight**: якщо `git rev-parse --show-toplevel` не вказує під `.worktrees/`, **STOP** і не питай користувача про назву гілки; створи worktree від поточної гілки готовим snippet з `SKILL.md` за конвенцією `<current-branch>-<suffix>`. Чисте робоче дерево — **не** привід пропустити preflight.',
+    ''
+  ]
+}
+
 /**
  * Рендерить секцію Skills для CLAUDE.md з урахуванням наявних slash-команд.
  * @returns {Promise<string[]>} готові рядки секції (або порожній масив)
@@ -701,6 +716,7 @@ async function syncClaudeMd(ignore) {
   }
 
   lines.push(...buildClaudeLintParallelismSectionLines())
+  lines.push(...buildClaudeWorktreeEnforcementSectionLines())
 
   const skillsSectionLines = await buildClaudeSkillsSectionLines()
   lines.push(...skillsSectionLines)

package/package.json

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

package/rules/docker/docker.mdc

@@ -1,6 +1,6 @@
 ---
 description: Dockerfile — lint-docker / hadolint; перевірка check-docker
-version: '1.9'
+version: '1.11'
 globs: "**/Dockerfile*"
 alwaysApply: false
 ---
@@ -25,7 +25,7 @@ alwaysApply: false
 
 ## компіляція
 
-Якщо проект має bun install крок, та не є фронтенд проектом (тобто не має bun build крок), то потрібно щоб була компіляція коду, і далі у фінальному образі був тільки бінарник і Цей образ не містив компілятора, npm, Bun — тільки runtime libs. Наприклад:
+Якщо проект має bun install крок, та не є фронтенд проектом (тобто не має bun build крок), **і не має нативного `.node`-аддона з динамічним завантаженням** (див. наступну секцію), то потрібно щоб була компіляція коду, і далі у фінальному образі був тільки бінарник і Цей образ не містив компілятора, npm, Bun — тільки runtime libs. Наприклад:
 
 ```dockerfile
 FROM mirror.gcr.io/oven/bun:alpine AS build-env
@@ -56,6 +56,50 @@ COPY --from=build-env /app/app ./app
 CMD ["./app"]
 ```
 
+### виняток: нативний `.node`-аддон (sharp / @img/* / argon2)
+
+Якщо в `package.json#dependencies` є нативний `.node`-аддон, який вантажиться через **динамічний `require`** — передусім **`sharp`**; той самий клас — **`@img/*`**, **`argon2`** — його **не можна** пакувати через `bun build --compile`.
+
+`bun build --compile` не трейсить `require(\`@img/sharp-${platform}/sharp.node\`)` і не вшиває нативний біндинг → компільований бінарник падає в рантаймі: `Could not load the "sharp" module using the linuxmusl-arm64 runtime`. Доведено реальними docker-збірками (bun 1.3.14, sharp 0.34.5); відтворюється і на darwin-arm64 (тобто не musl/glibc-залежне). `apk add vips` **НЕ лікує** — він дає системний libvips, а бракує саме `sharp.node`.
+
+Канон — ship `node_modules` і запускати через `bun <entry>` на базі `mirror.gcr.io/oven/bun:alpine` (це легітимний виняток до правила «лише alpine/scratch у фінальному stage» — тут потрібен саме bun-рантайм). База `oven/bun` уже має non-root користувача `bun` (uid/gid 1000). Entry бери з наявного `--outfile`-таргета / `package.json#main` / `scripts.start`; якщо не визначити — лиши TODO-маркер, не вгадуй.
+
+Перевіряє **`npm/rules/docker/lib/docker-native-addon.mjs`** (підключено в **`npm/rules/docker/js/lint.mjs`**, точка входу обходу — **`npm/rules/docker/fix.mjs`**). Список нативних аддонів — розширювана константа `NATIVE_ADDON_PACKAGES` / `NATIVE_ADDON_SCOPES` у чек-модулі.
+
+#### Антипатерн (це правило ловить)
+
+```dockerfile
+RUN bun build --compile --outfile app ./src/index.js     # ← з sharp у deps
+FROM mirror.gcr.io/library/alpine:latest
+RUN apk add --no-cache ... vips                           # системний vips не рятує
+COPY --from=build-env --chown=app:app /app/app ./app
+USER app
+CMD ["./app"]
+```
+
+#### Канон (привести до цього)
+
+```dockerfile
+FROM mirror.gcr.io/oven/bun:alpine AS build-env
+WORKDIR /app
+ENV NODE_ENV=production
+COPY package.json .
+RUN bun install --production
+COPY ./src ./src
+
+FROM mirror.gcr.io/oven/bun:alpine
+RUN apk add --no-cache tzdata
+WORKDIR /app
+# база oven/bun має non-root користувача bun (uid/gid 1000)
+COPY --from=build-env --chown=bun:bun /app/node_modules ./node_modules
+COPY --from=build-env --chown=bun:bun /app/src ./src
+COPY --from=build-env --chown=bun:bun /app/package.json ./package.json
+USER bun
+CMD ["bun", "src/index.js"]
+```
+
+Для проєктів **без** нативних аддонів standalone-бінарник на alpine лишається каноном (секція «компіляція» вище).
+
 ## не превілейований образ
 
 Для всих образів потрібно щоб використовувся non root принцип, наприклад:
@@ -88,6 +132,44 @@ CMD ["./app"]
 
 ```
 
+### nginx-unprivileged — без USER, із --chown
+
+Окрема гілка для фронтенду на базі **`nginxinc/nginx-unprivileged`** (будь-який тег, з/без `mirror.gcr.io/`-префікса). Цей образ **уже** оголошує `USER 101` і `EXPOSE 8080`, тож у фінальному stage **не потрібні** жодні явні `USER`-інструкції:
+
+- **жодного `USER root` / `USER 0`** для білд-кроків: він перезатирає успадкований `USER 101`, і якщо потім не повернути non-root — фінальний образ лишається root, а k8s із `runAsNonRoot: true` падає з `CreateContainerConfigError`;
+- **жодного switch-back** `USER 101` / `USER nginx` наприкінці stage — це лише симптом зайвого `USER root` на початку (повертати треба саме **числовим** UID, бо kubelet не підтверджує non-root за іменем `nginx`). Канон — взагалі не виходити з-під дефолтного 101;
+- **`COPY`/`ADD` лише з `--chown`** (канон — `--chown=nginx:nginx`): без нього файли копіюються власником root і дефолтний non-root користувач (uid=101) не зможе читати статику.
+
+Build-stage не чіпаємо — там root і tooling норма. Перевіряє **`npm/rules/docker/lib/docker-nginx-user.mjs`** (підключено в **`npm/rules/docker/js/lint.mjs`**, точка входу обходу — **`npm/rules/docker/fix.mjs`**).
+
+#### Антипатерн (це правило ловить)
+
+```dockerfile
+FROM mirror.gcr.io/nginxinc/nginx-unprivileged:alpine-slim
+USER root
+COPY ./k8s/nginx.conf /etc/nginx/conf.d/default.conf
+COPY --from=build /app/dist ./
+RUN find ./ -type f -name "*.js" -exec gzip -k {} \;
+USER 101          # повернення назад — симптом того, що був зайвий USER root
+EXPOSE 8080
+```
+
+#### Канон (привести до цього)
+
+```dockerfile
+FROM mirror.gcr.io/nginxinc/nginx-unprivileged:alpine-slim
+
+COPY --chown=nginx:nginx ./k8s/nginx.conf /etc/nginx/conf.d/default.conf
+
+WORKDIR /usr/share/nginx/html
+
+COPY --from=build --chown=nginx:nginx /app/dist ./
+
+RUN find ./ -type f -name "*.js" -exec gzip -k {} \;
+```
+
+(без жодного `USER`, gzip під дефолтним користувачем 101; `EXPOSE 8080` теж зайвий — база вже його оголошує)
+
 ## Область
 
 - Усі файли з іменем **`Dockerfile`** або **`Dockerfile.*`** (наприклад `Dockerfile.prod`) у репозиторії, крім ігнорованих каталогів (`node_modules`, `.git`, `dist`, …) — як у **`rules/docker/fix.mjs`**.

package/rules/docker/js/lint.mjs

@@ -15,6 +15,11 @@
  * то очікується компіляція в один бінарник через `bun build --compile` у build stage, а у
  * фінальному stage не повинно залишатися build tooling (Bun/Node).
  *
+ * Виняток — проєкти з нативним `.node`-аддоном (sharp/@img/argon2), який вантажиться через
+ * динамічний `require`: їх НЕ можна компілювати (`bun build --compile` не вшиває нативний
+ * біндинг → краш у рантаймі). Для них канон — node_modules + `bun <entry>` на базі
+ * `mirror.gcr.io/oven/bun:alpine` (див. `../lib/docker-native-addon.mjs`).
+ *
  * Мета — щоб у фінальному образі не було build tooling (Bun/Node та залежностей), а лише
  * дозволений runtime (alpine, scratch, debian slim, за потреби php/python, nginx або openresty).
  *
@@ -28,9 +33,11 @@
  * Кореневий .hadolint.yaml підхоплюється hadolint автоматично.
  */
 import { readFile } from 'node:fs/promises'
-import { basename } from 'node:path'
+import { basename, dirname, join } from 'node:path'
 
 import { getMirrorGcrHint, getFromImageToken } from '../lib/docker-mirror.mjs'
+import { getNativeAddonDeps, getNativeAddonNoCompileHint } from '../lib/docker-native-addon.mjs'
+import { getNginxUnprivilegedUserHint } from '../lib/docker-nginx-user.mjs'
 import { lintDockerfileWithHadolint, posixRel } from '../lib/docker-hadolint.mjs'
 import { createCheckReporter } from '../../../scripts/lib/check-reporter.mjs'
 import { loadCursorIgnorePaths } from '../../../scripts/lib/load-cursor-config.mjs'
@@ -108,15 +115,24 @@ const RUNTIME_IMAGES = /** @type {const} */ ([
 /** @type {RegExp} */
 const DEBIAN_VIA_MIRROR_RE = /^mirror\.gcr\.io\/library\/debian:(.+)$/i
 
+/** Bun-рантайм як фінальний stage — легітимний лише за наявності нативного .node-аддона (див. docker.mdc). */
+const BUN_RUNTIME_IMAGE = 'mirror.gcr.io/oven/bun'
+
 /**
  * Чи ref фінального `FROM` відповідає дозволеним у docker.mdc (multistage / runtime).
  * @param {string} lastLower ref без digest, lower case
+ * @param {boolean} [hasNativeAddon] чи проєкт залежить від нативного .node-аддона (sharp/@img/argon2)
  * @returns {boolean} true, якщо образ дозволений як фінальний runtime
  */
-function isAllowedFinalRuntimeImage(lastLower) {
+function isAllowedFinalRuntimeImage(lastLower, hasNativeAddon = false) {
   if (lastLower === 'scratch' || lastLower.startsWith('scratch:')) {
     return true
   }
+  // Для нативних аддонів канон — ship node_modules + `bun <entry>`, тож фінальний stage на
+  // mirror.gcr.io/oven/bun:* легітимний (compile неможливий, див. docker-native-addon.mjs).
+  if (hasNativeAddon && (lastLower === BUN_RUNTIME_IMAGE || lastLower.startsWith(`${BUN_RUNTIME_IMAGE}:`))) {
+    return true
+  }
   const deb = lastLower.match(DEBIAN_VIA_MIRROR_RE)
   if (deb) {
     return deb[1].toLowerCase().includes('slim')
@@ -149,11 +165,13 @@ export function splitDockerfileStages(fileContent) {
 /**
  * Перевіряє базові вимоги до структури Dockerfile:
  * - multistage: мінімум 2 FROM
- * - фінальний FROM: дозволені образи в docker.mdc (alpine, scratch, debian slim, php, python, nginx, openresty, …)
+ * - фінальний FROM: дозволені образи в docker.mdc (alpine, scratch, debian slim, php, python, nginx, openresty, …);
+ *   для проєктів із нативним .node-аддоном додатково дозволено mirror.gcr.io/oven/bun:* (bun-рантайм)
  * @param {string} fileContent вміст Dockerfile/Containerfile
+ * @param {{ hasNativeAddon?: boolean }} [opts] опції: hasNativeAddon — є нативний .node-аддон (sharp/@img/argon2)
  * @returns {string | null} повідомлення помилки або null
  */
-export function getMultistageAndRuntimeHint(fileContent) {
+export function getMultistageAndRuntimeHint(fileContent, { hasNativeAddon = false } = {}) {
   const stages = parseFromStages(fileContent)
   if (stages.length === 0) return null
 
@@ -165,7 +183,7 @@ export function getMultistageAndRuntimeHint(fileContent) {
   const lastImage = (last?.image || '').split('@')[0] || ''
   const lastLower = lastImage.toLowerCase()
 
-  if (!isAllowedFinalRuntimeImage(lastLower)) {
+  if (!isAllowedFinalRuntimeImage(lastLower, hasNativeAddon)) {
     return `фінальний FROM має бути дозволеним runtime-образом (див. docker.mdc: multistage), зараз: ${last?.image} (рядок ${last?.line})`
   }
 
@@ -309,6 +327,32 @@ export async function check(cwd = process.cwd()) {
   return reporter.getExitCode()
 }
 
+/**
+ * Читає `dependencies` найближчого `package.json` (від каталогу Dockerfile вгору до кореня репо).
+ * Build-контекст Dockerfile — зазвичай його ж каталог, тож беремо найбільш специфічний package.json.
+ * @param {string} abs абсолютний шлях до Dockerfile/Containerfile
+ * @param {string} root корінь репозиторію
+ * @returns {Promise<Record<string, unknown>>} dependencies або порожній об'єкт
+ */
+async function readNearestDependencies(abs, root) {
+  let dir = dirname(abs)
+  for (;;) {
+    try {
+      const pkg = JSON.parse(await readFile(join(dir, 'package.json'), 'utf8'))
+      const deps = pkg?.dependencies
+      if (deps && typeof deps === 'object' && !Array.isArray(deps)) return deps
+      return {}
+    } catch {
+      /* немає package.json у цьому каталозі — піднімаємось вище */
+    }
+    if (dir === root) break
+    const parent = dirname(dir)
+    if (parent === dir) break
+    dir = parent
+  }
+  return {}
+}
+
 /**
  * Перевіряє один Dockerfile/Containerfile: mirror.gcr.io, multistage/runtime, compile/non-root/nginx tag і hadolint.
  * @param {ReturnType<typeof createCheckReporter>} reporter репортер перевірок
@@ -321,14 +365,24 @@ async function checkDockerfile(reporter, root, abs) {
   const rel = posixRel(root, abs) || basename(abs)
   const content = await readFile(abs, 'utf8')
 
+  const nativeAddons = getNativeAddonDeps(await readNearestDependencies(abs, root))
+  const hasNativeAddon = nativeAddons.length > 0
+
   const hint = getMirrorGcrHint(content)
   if (hint) fail(`${rel} (mirror.gcr.io): ${hint}`)
 
-  const multistageHint = getMultistageAndRuntimeHint(content)
+  const multistageHint = getMultistageAndRuntimeHint(content, { hasNativeAddon })
   if (multistageHint) fail(`${rel} (multistage): ${multistageHint}`)
 
-  const compileHint = getBunCompileHint(content)
-  if (compileHint) fail(`${rel} (compile): ${compileHint}`)
+  // Нативні .node-аддони (sharp/@img/argon2) керують окремо: compile заборонено (бінарник падає
+  // в рантаймі), канон — node_modules + `bun <entry>`. Генеричне compile-правило для них не діє.
+  if (hasNativeAddon) {
+    const nativeAddonHint = getNativeAddonNoCompileHint(content, nativeAddons)
+    if (nativeAddonHint) fail(`${rel} (native-addon): ${nativeAddonHint}`)
+  } else {
+    const compileHint = getBunCompileHint(content)
+    if (compileHint) fail(`${rel} (compile): ${compileHint}`)
+  }
 
   const nonRootHint = getNonRootRuntimeHint(content)
   if (nonRootHint) fail(`${rel} (non-root): ${nonRootHint}`)
@@ -336,6 +390,9 @@ async function checkDockerfile(reporter, root, abs) {
   const nginxSlimHint = getNginxAlpineSlimTagHint(content)
   if (nginxSlimHint) fail(`${rel} (nginx tag): ${nginxSlimHint}`)
 
+  const nginxUserHint = getNginxUnprivilegedUserHint(content)
+  if (nginxUserHint) fail(`${rel} (nginx non-root): ${nginxUserHint}`)
+
   const { ok, stdout, stderr, via } = lintDockerfileWithHadolint(root, abs)
   const tail = (stdout + stderr).trim()
   if (ok) {

package/rules/docker/lib/docker-native-addon.mjs

@@ -0,0 +1,93 @@
+/**
+ * Перевірка для проєктів, що залежать від нативного `.node`-аддона, який вантажиться через
+ * **динамічний `require`** (передусім **sharp**; той самий клас — `@img/*`, `argon2`).
+ *
+ * Такі аддони **не можна** пакувати через `bun build --compile`: компілятор не трейсить
+ * динамічний `require(\`@img/sharp-${platform}/sharp.node\`)` і не вшиває нативний біндинг, тож
+ * компільований бінарник падає в рантаймі (`Could not load the "sharp" module using the
+ * linuxmusl-arm64 runtime`). Доведено реальними docker-збірками (bun 1.3.14, sharp 0.34.5),
+ * відтворюється і на darwin-arm64 — тобто не musl/glibc-залежне. `apk add vips` НЕ лікує: він
+ * дає системний libvips, а бракує саме `sharp.node`.
+ *
+ * Канон для таких проєктів — НЕ компілювати, а ship `node_modules` і запускати через
+ * `bun <entry>` на базі `mirror.gcr.io/oven/bun:alpine` (див. docker.mdc: компіляція). Це
+ * легітимний виняток до правила «лише alpine/scratch у фінальному stage» — тут потрібен
+ * саме bun-рантайм.
+ *
+ * Це окрема гілка від генеричного compile-правила (`getBunCompileHint` у `../js/lint.mjs`):
+ * для проєктів БЕЗ нативних аддонів standalone-бінарник на alpine лишається каноном.
+ *
+ * Взірець структури dep-специфічного чек-модуля — сусідній `./docker-mirror.mjs`.
+ */
+
+/**
+ * Розширюваний список нативних `.node`-аддонів із динамічним завантаженням біндингу.
+ * Точні імена пакетів.
+ */
+export const NATIVE_ADDON_PACKAGES = /** @type {const} */ (['sharp', 'argon2'])
+
+/**
+ * Scope-префікси нативних аддонів (будь-який пакет у scope трактуємо як нативний).
+ * `@img/*` — платформо-специфічні біндинги sharp (`@img/sharp-linuxmusl-arm64` тощо).
+ */
+export const NATIVE_ADDON_SCOPES = /** @type {const} */ (['@img/'])
+
+const BUN_BUILD_COMPILE_RE = /\bbun\s+build\b[^\n]*\s--compile\b/iu
+const APK_ADD_VIPS_RE = /\bapk\s+add\b[^\n]*\bvips\b/iu
+
+/**
+ * Чи ім'я пакета — нативний `.node`-аддон зі списку (точне ім'я або scope-префікс).
+ * @param {string} name — ім'я npm-пакета
+ * @returns {boolean} true, якщо це знаний нативний аддон
+ */
+export function isNativeAddonPackage(name) {
+  if (NATIVE_ADDON_PACKAGES.includes(/** @type {never} */ (name))) return true
+  return NATIVE_ADDON_SCOPES.some(scope => name.startsWith(scope))
+}
+
+/**
+ * Повертає імена нативних аддонів, наявних у `dependencies` пакета.
+ * @param {unknown} dependencies — об'єкт `package.json#dependencies`
+ * @returns {string[]} відсортовані імена знайдених нативних аддонів (порожній — якщо немає)
+ */
+export function getNativeAddonDeps(dependencies) {
+  if (!dependencies || typeof dependencies !== 'object' || Array.isArray(dependencies)) return []
+  return Object.keys(dependencies)
+    .filter(name => isNativeAddonPackage(name))
+    .toSorted((a, b) => a.localeCompare(b))
+}
+
+/**
+ * Перевіряє антипатерн «нативний аддон + `bun build --compile`».
+ *
+ * Тригер:
+ * - у `package.json#dependencies` є нативний аддон (`getNativeAddonDeps` непорожній);
+ * - **і** Dockerfile містить `bun build --compile`.
+ *
+ * Прапорцює compile-крок як помилку; додатково — зайвий `apk add ... vips`, доданий для
+ * компенсації (системний vips не рятує). Канон описано в docker.mdc.
+ * @param {string} fileContent — вміст Dockerfile/Containerfile
+ * @param {string[]} nativeAddons — знайдені нативні аддони (з `getNativeAddonDeps`)
+ * @returns {string | null} повідомлення помилки або null
+ */
+export function getNativeAddonNoCompileHint(fileContent, nativeAddons) {
+  if (!Array.isArray(nativeAddons) || nativeAddons.length === 0) return null
+  if (!BUN_BUILD_COMPILE_RE.test(fileContent)) return null
+
+  /** @type {string[]} */
+  const problems = [
+    `проєкт залежить від нативного .node-аддона (${nativeAddons.join(', ')}) з динамічним require — ` +
+      '`bun build --compile` не вшиває нативний біндинг, тож бінарник падає в рантаймі. ' +
+      'Прибери compile-крок: ship node_modules + `bun <entry>` на базі mirror.gcr.io/oven/bun:alpine ' +
+      '(docker.mdc: компіляція). Entry бери з наявного --outfile-таргета / package.json#main / ' +
+      'scripts.start; якщо не визначити — лиши TODO-маркер, не вгадуй'
+  ]
+
+  if (APK_ADD_VIPS_RE.test(fileContent)) {
+    problems.push(
+      'зайвий `apk add ... vips` — системний libvips не лікує брак `sharp.node`; прибери разом із compile-кроком'
+    )
+  }
+
+  return problems.join('\n     - ')
+}

package/rules/docker/lib/docker-nginx-user.mjs

@@ -0,0 +1,122 @@
+/**
+ * Перевірка для фінального (runtime) stage на базі `nginxinc/nginx-unprivileged`.
+ *
+ * Образ `nginx-unprivileged` уже оголошує `USER 101` і `EXPOSE 8080`, тож у Dockerfile
+ * **не повинно** бути жодних явних `USER`-інструкцій у цьому stage:
+ *
+ * - `USER root` (або `USER 0`) для білд-кроків перезатирає успадкований `USER 101`; якщо потім
+ *   не повернути non-root — фінальний образ лишається root, і k8s із `runAsNonRoot: true` падає з
+ *   `CreateContainerConfigError`. Повертати треба саме **числовим** UID (`USER 101`), бо kubelet не
+ *   підтверджує non-root за іменем `nginx` — тож повернення `USER 101`/`USER nginx` у кінці stage
+ *   є симптомом зайвого `USER root` на початку.
+ * - Найбезпечніший канон — взагалі не виходити з-під дефолтного 101: ні `USER root`, ні
+ *   switch-back. Будь-який явний `USER` у такому stage прапорцюється як зайвий.
+ *
+ * Крім того, `COPY`/`ADD` без `--chown` копіює файли власником root — їх не зможе читати дефолтний
+ * non-root користувач (uid=101); тому в цьому stage кожен `COPY`/`ADD` має мати `--chown` (канон —
+ * `--chown=nginx:nginx`).
+ *
+ * Це окрема гілка від генеричного non-root-правила (`addgroup/adduser` + `USER app` для alpine-бекендів,
+ * див. `getNonRootRuntimeHint` у `../js/lint.mjs`): для nginx канон — навпаки, **відсутність** `USER`.
+ *
+ * Тригер — лише фінальний `FROM`, що базується на `nginxinc/nginx-unprivileged` (з урахуванням
+ * `mirror.gcr.io/…`-префікса й будь-якого тега). Build-stage-и не чіпаємо — там root і tooling норма.
+ *
+ * Взірець структури base-image-специфічного чек-модуля — сусідній `./docker-mirror.mjs`.
+ */
+import { getFromImageToken } from './docker-mirror.mjs'
+
+const NEWLINE_RE = /\r?\n/
+const USER_LINE_RE = /^\s*USER\s+([^\s#]+)/iu
+const COPY_ADD_RE = /^\s*(COPY|ADD)\b(.*)$/iu
+const CHOWN_FLAG_RE = /(?:^|\s)--chown=/iu
+
+/** Шлях репозиторію nginx-unprivileged (після зняття `mirror.gcr.io/`/`docker.io/`-префікса й тега/digest). */
+const NGINX_UNPRIVILEGED_REPO_RE = /(?:^|\/)nginxinc\/nginx-unprivileged(?::|@|$)/iu
+
+/**
+ * Чи базується ref `FROM` на образі `nginxinc/nginx-unprivileged` (будь-який тег, з/без `mirror.gcr.io/`).
+ * @param {string} image — токен образу після `FROM`
+ * @returns {boolean} true, якщо це nginx-unprivileged
+ */
+export function isNginxUnprivilegedImage(image) {
+  return NGINX_UNPRIVILEGED_REPO_RE.test((image || '').trim())
+}
+
+/**
+ * @typedef {{ image: string, lines: Array<{ lineNo: number, text: string }> }} FinalStage
+ */
+
+/**
+ * Виділяє фінальний (останній `FROM` … кінець файла) stage з номерами рядків.
+ * @param {string} fileContent — вміст Dockerfile/Containerfile
+ * @returns {FinalStage | null} фінальний stage або null, якщо `FROM` немає
+ */
+function getFinalStage(fileContent) {
+  const lines = fileContent.split(NEWLINE_RE)
+  /** @type {{ image: string, idx: number } | null} */
+  let lastFrom = null
+  for (const [idx, line] of lines.entries()) {
+    const image = getFromImageToken(line)
+    if (image) lastFrom = { image, idx }
+  }
+  if (!lastFrom) return null
+  const stageLines = lines.slice(lastFrom.idx).map((text, i) => ({ lineNo: lastFrom.idx + i + 1, text }))
+  return { image: lastFrom.image, lines: stageLines }
+}
+
+/**
+ * Нормалізує токен `USER` (без лапок, lower-case, без зайвих пробілів).
+ * @param {string} token — захоплений токен після `USER`
+ * @returns {string} нормалізований токен
+ */
+function normalizeUserToken(token) {
+  return token.replaceAll('"', '').replaceAll("'", '').trim().toLowerCase()
+}
+
+/**
+ * Перевіряє фінальний nginx-unprivileged stage на зайві `USER` і `COPY`/`ADD` без `--chown`.
+ *
+ * Збирає всі порушення в один рядок (по одному пункту на рядок) — щоб один прогін показав і
+ * `USER root`, і switch-back `USER 101`, і `COPY` без `--chown` одразу.
+ * @param {string} fileContent — вміст Dockerfile/Containerfile
+ * @returns {string | null} повідомлення помилки або null, якщо порушень немає / це не nginx-stage
+ */
+export function getNginxUnprivilegedUserHint(fileContent) {
+  const stage = getFinalStage(fileContent)
+  if (!stage) return null
+  if (!isNginxUnprivilegedImage(stage.image)) return null
+
+  /** @type {string[]} */
+  const problems = []
+  // Перший рядок stage — це сам FROM; USER/COPY у ньому неможливі, але цикл лишаємо загальним.
+  for (const { lineNo, text } of stage.lines) {
+    const u = text.match(USER_LINE_RE)
+    if (u) {
+      const token = normalizeUserToken(u[1])
+      if (token === 'root' || token === '0') {
+        problems.push(
+          `рядок ${lineNo}: прибери \`USER ${u[1]}\` — у nginx-unprivileged не можна перемикатися на root (інакше фінальний образ лишиться root і k8s із runAsNonRoot впаде)`
+        )
+      } else if (token === '101' || token === 'nginx') {
+        problems.push(
+          `рядок ${lineNo}: прибери зайвий \`USER ${u[1]}\` — база nginx-unprivileged вже працює від uid=101 (повернення USER назад — симптом зайвого USER root)`
+        )
+      } else {
+        problems.push(
+          `рядок ${lineNo}: прибери явний \`USER ${u[1]}\` — база nginx-unprivileged вже працює від non-root (uid=101), окремий USER не потрібен`
+        )
+      }
+      continue
+    }
+    const c = text.match(COPY_ADD_RE)
+    if (c && !CHOWN_FLAG_RE.test(text)) {
+      problems.push(
+        `рядок ${lineNo}: додай \`--chown=nginx:nginx\` до \`${c[1].toUpperCase()}\` — статику має читати non-root користувач (uid=101)`
+      )
+    }
+  }
+
+  if (problems.length === 0) return null
+  return problems.join('\n     - ')
+}

package/rules/flow/meta.json

@@ -1 +1 @@
-{}
+{ "auto": "завжди" }

package/rules/js-lint/js-lint.mdc

@@ -2,10 +2,10 @@
 description: Перевірка JavaScript коду
 globs: "**/{.oxlintrc.json,eslint.config.js,.jscpd.json,knip.json,package.json},**/*.{js,mjs,cjs,jsx,ts,tsx}"
 alwaysApply: false
-version: '1.28'
+version: '1.29'
 ---
 
-**oxlint**, **ESLint**, **jscpd**, **knip**. У скрипті **`lint-js`** і в CI — **`bunx oxlint`**, **`bunx eslint`**, **`bunx jscpd`**, **`bunx knip`** (у CI без **`--fix`** для oxlint/eslint — див. приклад workflow нижче). Без **prettier** і **@nitra/prettier-config**. У **`devDependencies`** має бути **`@nitra/eslint-config`** — версія не нижче канонічного мінімуму зі snippet нижче (semver-поріг, єдине джерело істини) (з **3.8.0** правило `no-restricted-syntax` забороняє `for...in`; з **3.9.2** у `getConfig` вбудовано ignore для **`**/adr/**`** — ADR-документи не валідуються ESLint, локально цей glob додавати не потрібно; також транзитивно йде **`@e18e/eslint-plugin`** для oxlint); пакет **`@e18e/eslint-plugin`** окремо не додавай. Пакети oxlint/eslint/jscpd/knip не додавай без потреби монорепо.
+**oxlint**, **ESLint**, **jscpd**, **knip**. У скрипті **`lint-js`** і в CI — **`bunx oxlint`**, **`bunx eslint`**, **`bunx jscpd`**, **`bunx knip`** (у CI без **`--fix`** для oxlint/eslint — див. приклад workflow нижче). Без **prettier** і **@nitra/prettier-config**. У **`devDependencies`** має бути **`@nitra/eslint-config`** — версія не нижче канонічного мінімуму зі snippet нижче (semver-поріг, єдине джерело істини) (з **3.8.0** правило `no-restricted-syntax` забороняє `for...in`; з **3.9.2** у `getConfig` вбудовано ignore для **`**/adr/**`** — ADR-документи не валідуються ESLint, локально цей glob додавати не потрібно; також транзитивно йде **`@e18e/eslint-plugin`** для oxlint). Dependency-політику CI-етапу (`@e18e/eslint-plugin` і oxlint/eslint/jscpd/knip окремо не додавати) винесено в `js-lint-ci`.
 
 У кожному **`package.json`** проєкту (корінь і всі workspace-пакети) має бути **`"type": "module"`** — весь код у ESM.
 
@@ -62,13 +62,7 @@ version: '1.28'
 
 ## knip
 
-Перевірку невикористаних залежностей і експортів виконує **knip** (заміна `depcheck`). Викликається у скрипті `lint-js` і в CI разом з oxlint/eslint/jscpd — окремий крок у CI не потрібен.
-
-У корені проєкту має бути **`knip.json`**, який стартує з канонічного baseline з пакета `@nitra/cursor` — файл [`npm/rules/js-lint/js/tooling/knip-canonical.json`](./js/tooling/knip-canonical.json). Він покриває типові false-positives для наших правил: `entry` зі CLI-конфігами (eslint, stylelint, oxlint, jscpd, markdownlint-cli2, `commitlint`), `project` для `**/*.{js,mjs,cjs,jsx,ts,tsx,mts,cts}`, `ignore` для `**/__fixtures__/**`, `ignoreDependencies` для пакетів, посилання на які є лише в не-JS-конфігах (`@nitra/cspell-dict`, `/@cspell\/dict-.+/`), і `ignoreBinaries` для CLI, які канон вимагає викликати через `npx`/`bunx` і яких заборонено додавати в `devDependencies` (`actionlint`, `cspell`, `depcheck`, `eslint`, `git-ai`, `jscpd`, `markdownlint-cli2`, `oxfmt`, `oxlint`, `shellcheck`, `uvx`, `v8r`, `zizmor`).
-
-Якщо `knip.json` відсутній — `npx @nitra/cursor fix js-lint` копіює канон у корінь проєкту (side effect). Після створення модифікуй файл під свій проєкт як завгодно: перевіряємо лише наявність, зміст подальших змін не валідується.
-
-Пакет `knip` окремо в `devDependencies` не додавай — `bunx knip` тягне його ad-hoc, як oxlint/eslint/jscpd.
+Залежнісний аналіз (knip — невикористані залежності/експорти, `knip.json` канон) крос-файловий, тож винесений у правило `js-lint-ci` (`lint: ci`). Див. `js-lint-ci`.
 
 ## jscpd: рефакторинг і структура
 

package/rules/js-lint-ci/js-lint-ci.mdc

@@ -1,7 +1,8 @@
 ---
 description: Крос-файловий ci-етап js-lint — jscpd (детектор клонів) і knip (невикористані експорти). Лише у lint-ci, по всьому репо.
-globs:
-alwaysApply: true
+globs: "**/{.oxlintrc.json,eslint.config.js,.jscpd.json,knip.json,package.json},**/*.{js,mjs,cjs,jsx,ts,tsx}"
+alwaysApply: false
+version: '1.0'
 ---
 
 # js-lint-ci — крос-файловий ci-етап
@@ -10,3 +11,35 @@ alwaysApply: true
 `npx @nitra/cursor lint-ci` (не у швидкому `lint` по змінених файлах). Per-file режиму нема.
 
 Швидкий етап js-lint (oxlint/eslint) — у правилі `js-lint` (`lint: quick`).
+
+## Залежнісна політика (що не додавати)
+
+Залежнісний аналіз — крос-файлова зона цього ci-етапу, тож і політика «що не додавати в залежності» живе тут.
+
+`@e18e/eslint-plugin` окремо не додавай — він уже в залежностях `@nitra/eslint-config` (з **3.8.0**), oxlint підвантажує його з `node_modules`. Пакети oxlint/eslint/jscpd/knip теж не додавай у `devDependencies` без потреби монорепо — `bunx` тягне їх ad-hoc.
+
+## knip
+
+Перевірку невикористаних залежностей і експортів виконує **knip** (заміна `depcheck`). Викликається у скрипті `lint-js` і в CI разом з oxlint/eslint/jscpd — окремий крок у CI не потрібен.
+
+У корені проєкту має бути **`knip.json`**, який стартує з канонічного baseline з пакета `@nitra/cursor` — файл [`npm/rules/js-lint/js/tooling/knip-canonical.json`](../js-lint/js/tooling/knip-canonical.json). Він покриває типові false-positives для наших правил: `entry` зі CLI-конфігами (eslint, stylelint, oxlint, jscpd, markdownlint-cli2, `commitlint`), `project` для `**/*.{js,mjs,cjs,jsx,ts,tsx,mts,cts}`, `ignore` для `**/__fixtures__/**`, `ignoreDependencies` для пакетів, посилання на які є лише в не-JS-конфігах (`@nitra/cspell-dict`, `/@cspell\/dict-.+/`, `graphql`), і `ignoreBinaries` для CLI, які канон вимагає викликати через `npx`/`bunx` і яких заборонено додавати в `devDependencies` (`actionlint`, `cspell`, `eslint`, `git-ai`, `jscpd`, `markdownlint-cli2`, `oxfmt`, `oxlint`, `shellcheck`, `uvx`, `v8r`, `zizmor`).
+
+Якщо `knip.json` відсутній — `npx @nitra/cursor fix js-lint` копіює канон у корінь проєкту (side effect). Після створення модифікуй файл під свій проєкт як завгодно: перевіряємо лише наявність, зміст подальших змін не валідується.
+
+Пакет `knip` окремо в `devDependencies` не додавай — `bunx knip` тягне його ad-hoc, як oxlint/eslint/jscpd.
+
+## Заборона `@nitra/as-integrations-fastify`
+
+Пакет **`@nitra/as-integrations-fastify`** заборонений у **`dependencies`**, **`peerDependencies`** та в import-specifier-ах. Це чистий републіш upstream, застряглий на peer `@apollo/server: "^4.0.0"`, тож на Apollo 5 `bun install` дає `warn: incorrect peer dependency`. Заміна — upstream **`@as-integrations/fastify`** (**`^3.1.0`**): peer `@apollo/server: "^4.0.0 || ^5.0.0"` + `fastify: "^5.3.0"`.
+
+Як і knip, це крос-файлова dependency-політика ci-етапу, а не per-file перевірка — інваріант «per-file режиму нема» зберігається.
+
+Міграція — лише specifier у трьох місцях: залежність у `package.json`, `import`, та `vi.mock(...)` / `await import(...)` у тестах. **Код не міняється**, експорти ті самі: `default` → `fastifyApollo`, named → `fastifyApolloDrainPlugin`.
+
+```javascript title="❌ до"
+import fastifyApollo, { fastifyApolloDrainPlugin } from '@nitra/as-integrations-fastify'
+```
+
+```javascript title="✅ після"
+import fastifyApollo, { fastifyApolloDrainPlugin } from '@as-integrations/fastify'
+```

package/rules/vue/js/packages.mjs

@@ -226,6 +226,20 @@ async function checkViteClientEnvAndEditorConfig(rootDir, prefix, passFn, fail,
   passFn(`${prefix}jsconfig.json присутній`)
 }
 
+/**
+ * Чи є пакет бібліотекою компонентів Vue — `vue` оголошено в `peerDependencies`.
+ *
+ * Такі пакети споживаються Vite-проєктами як залежність; їхні власні джерела **не** проходять
+ * через `unplugin-auto-import` споживача (auto-import резолвиться лише в коді самого додатка, не в
+ * `node_modules`). Тому в бібліотеці компонентів явні `import { … } from 'vue'` обовʼязкові, і правило
+ * авто-імпорту (заборона value-імпортів з `'vue'`) до неї **не** застосовується.
+ * @param {{ peerDependencies?: Record<string, string> }} pkg розпарсений package.json
+ * @returns {boolean} true, якщо `vue` присутній у `peerDependencies`
+ */
+export function isVueComponentLibraryPkg(pkg) {
+  return Boolean(pkg?.peerDependencies?.vue)
+}
+
 /**
  * Витягує текст аргументів першого виклику `AutoImport(` з vite.config зі збалансованими дужками.
  * Повертає `null`, якщо виклик не знайдено або дужки не збалансовані (тоді перевірка `'vue'`
@@ -266,13 +280,14 @@ function viteConfigHasVueInAutoImports(content) {
 /**
  * Перевіряє vite.config на наявність VueMacros і AutoImport.
  * @param {string} rootDir параметр rootDir
+ * @param {boolean} isComponentLibrary чи це бібліотека компонентів (vue у peerDependencies) — тоді auto-import не застосовується
  * @param {string} prefix параметр prefix
  * @param {(msg: string) => void} passFn callback при успішній перевірці
  * @param {(msg: string) => void} fail callback при помилці
  * @returns {Promise<{ hasVueAutoImport: boolean }>} ознака успішно сконфігурованого vue-auto-import (для checkVueImportViolations)
  * @param {string} cwd корінь репозиторію
  */
-async function checkViteConfig(rootDir, prefix, passFn, fail, cwd) {
+async function checkViteConfig(rootDir, isComponentLibrary, prefix, passFn, fail, cwd) {
   const configFiles = ['vite.config.js', 'vite.config.ts', 'vite.config.mjs']
   const viteConfig = configFiles.find(f => existsSync(join(cwd, rootDir, f)))
   if (!viteConfig) {
@@ -283,27 +298,36 @@ async function checkViteConfig(rootDir, prefix, passFn, fail, cwd) {
   if (ESBUILD_RE.test(content)) {
     fail(`${prefix}${viteConfig} містить 'esbuild' — заміни на 'rolldown'`)
   }
-  const checks = [
-    { token: 'VueMacros', ok: `${viteConfig} використовує VueMacros`, err: `${viteConfig} не містить VueMacros` },
-    { token: 'AutoImport', ok: `${viteConfig} використовує AutoImport`, err: `${viteConfig} не містить AutoImport` }
-  ]
-  for (const { token, ok, err } of checks) {
-    if (content.includes(token)) {
-      passFn(`${prefix}${ok}`)
-    } else {
-      fail(`${prefix}${err}`)
+  // VueMacros + AutoImport (і 'vue' у його imports) — інструментарій auto-import Vite-додатка;
+  // бібліотека компонентів (vue у peerDependencies) споживається готовою і не потребує цього стеку.
+  // npm_lifecycle_event (Bun-compat) перевіряємо нижче незалежно — це не auto-import.
+  const hasVueAutoImport = viteConfigHasVueInAutoImports(content)
+  if (isComponentLibrary) {
+    passFn(
+      `${prefix}${viteConfig}: бібліотека компонентів (vue у peerDependencies) — VueMacros/AutoImport не вимагаються`
+    )
+  } else {
+    const checks = [
+      { token: 'VueMacros', ok: `${viteConfig} використовує VueMacros`, err: `${viteConfig} не містить VueMacros` },
+      { token: 'AutoImport', ok: `${viteConfig} використовує AutoImport`, err: `${viteConfig} не містить AutoImport` }
+    ]
+    for (const { token, ok, err } of checks) {
+      if (content.includes(token)) {
+        passFn(`${prefix}${ok}`)
+      } else {
+        fail(`${prefix}${err}`)
+      }
     }
-  }
 
-  const hasVueAutoImport = viteConfigHasVueInAutoImports(content)
-  if (content.includes('AutoImport(')) {
-    if (hasVueAutoImport) {
-      passFn(`${prefix}${viteConfig}: AutoImport({ imports: [..., 'vue', ...] }) — value-імпорти з 'vue' покриті`)
-    } else {
-      fail(
-        `${prefix}${viteConfig}: AutoImport не містить 'vue' у imports — додай 'vue' (інакше прибирати ` +
-          `value-імпорти на кшталт \`import { ref } from 'vue'\` небезпечно: ref/createApp тощо нікому буде надати)`
-      )
+    if (content.includes('AutoImport(')) {
+      if (hasVueAutoImport) {
+        passFn(`${prefix}${viteConfig}: AutoImport({ imports: [..., 'vue', ...] }) — value-імпорти з 'vue' покриті`)
+      } else {
+        fail(
+          `${prefix}${viteConfig}: AutoImport не містить 'vue' у imports — додай 'vue' (інакше прибирати ` +
+            `value-імпорти на кшталт \`import { ref } from 'vue'\` небезпечно: ref/createApp тощо нікому буде надати)`
+        )
+      }
     }
   }
 
@@ -367,12 +391,29 @@ async function checkVueNodeImportViolations(rootDir, absPackageRoot, ignorePaths
  * @param {string} rootDir відносний шлях до пакета
  * @param {string} absPackageRoot абсолютний шлях до кореня пакета
  * @param {string[]} ignorePaths абсолютні шляхи каталогів, повністю виключених з обходу
+ * @param {boolean} isComponentLibrary чи це бібліотека компонентів (vue у peerDependencies) — її джерела не проходять auto-import
  * @param {boolean} hasVueAutoImport чи `AutoImport({ imports: [..., 'vue', ...] })` сконфігуровано
  * @param {string} prefix префікс повідомлення `[<pkg>] `
  * @param {(msg: string) => void} passFn callback при успішній перевірці
  * @param {(msg: string) => void} fail callback при помилці
  */
-async function checkVueImportViolations(rootDir, absPackageRoot, ignorePaths, hasVueAutoImport, prefix, passFn, fail) {
+async function checkVueImportViolations(
+  rootDir,
+  absPackageRoot,
+  ignorePaths,
+  isComponentLibrary,
+  hasVueAutoImport,
+  prefix,
+  passFn,
+  fail
+) {
+  if (isComponentLibrary) {
+    passFn(
+      `${prefix}бібліотека компонентів (vue у peerDependencies) — явні value-імпорти з 'vue' дозволені ` +
+        `(джерела не проходять через unplugin-auto-import споживача)`
+    )
+    return
+  }
   if (!hasVueAutoImport) {
     passFn(`${prefix}value-імпорти з 'vue' не заборонені — спершу додай 'vue' до AutoImport.imports у vite.config`)
     return
@@ -409,38 +450,54 @@ async function checkVueImportViolations(rootDir, absPackageRoot, ignorePaths, ha
 /**
  * Перевіряє залежності та vite.config одного Vue-пакета.
  * @param {string} rootDir відносний шлях до пакета
+ * @param {boolean} isComponentLibrary чи це бібліотека компонентів (vue у peerDependencies) — auto-import не застосовується
  * @param {string[]} ignorePaths абсолютні шляхи каталогів, повністю виключених з обходу
  * @param {(msg: string) => void} fail функція зворотного виклику для реєстрації помилки перевірки
  * @param {(msg: string) => void} passFn успішне повідомлення (як у check-reporter)
  * @returns {Promise<void>} завершується після перевірок залежностей, `vite.config` і сканування джерел на імпорти з `vue`
  * @param {string} cwd корінь репозиторію
  */
-async function checkVuePackage(rootDir, ignorePaths, fail, passFn, cwd) {
+async function checkVuePackage(rootDir, isComponentLibrary, ignorePaths, fail, passFn, cwd) {
   const prefix = `[${packageLabel(rootDir)}] `
   passFn(`${prefix}package.json залежності перевіряє npx @nitra/cursor fix → vue.package_json`)
 
   await checkViteClientEnvAndEditorConfig(rootDir, prefix, passFn, fail, cwd)
 
-  const { hasVueAutoImport } = await checkViteConfig(rootDir, prefix, passFn, fail, cwd)
-  await checkVueImportViolations(rootDir, join(cwd, rootDir), ignorePaths, hasVueAutoImport, prefix, passFn, fail)
+  const { hasVueAutoImport } = await checkViteConfig(rootDir, isComponentLibrary, prefix, passFn, fail, cwd)
+  await checkVueImportViolations(
+    rootDir,
+    join(cwd, rootDir),
+    ignorePaths,
+    isComponentLibrary,
+    hasVueAutoImport,
+    prefix,
+    passFn,
+    fail
+  )
   await checkVueNodeImportViolations(rootDir, join(cwd, rootDir), ignorePaths, prefix, passFn, fail)
   await checkEsbuildMentions(rootDir, join(cwd, rootDir), ignorePaths, prefix, passFn, fail)
 }
 
 /**
- * Збирає корені пакетів, у яких у `dependencies` є `vue`.
+ * Збирає корені пакетів, у яких у `dependencies` є `vue`, із ознакою «бібліотека компонентів».
+ *
+ * Пакети, де `vue` лише в `peerDependencies` (без `dependencies`), — це бібліотеки компонентів, які
+ * споживаються Vite-додатками; вони не є самостійними Vite-проєктами, тож app-перевірки (vite-env,
+ * VueMacros тощо) до них не застосовуються — їх не збираємо. Якщо ж пакет має `vue` і в
+ * `dependencies` (повноцінний проєкт), і в `peerDependencies` — позначаємо `isComponentLibrary`,
+ * щоб вимкнути саме правило auto-import (його джерела не проходять через unplugin-auto-import споживача).
  * @param {string[]} roots усі корені пакетів monorepo
- * @returns {Promise<string[]>} перелік пакетів з vue у dependencies
+ * @returns {Promise<Array<{ rootDir: string, isComponentLibrary: boolean }>>} пакети з vue у dependencies
  * @param {string} cwd корінь репозиторію
  */
 async function collectVueRoots(roots, cwd) {
-  /** @type {string[]} */
+  /** @type {Array<{ rootDir: string, isComponentLibrary: boolean }>} */
   const vueRoots = []
   for (const r of roots) {
     const p = join(cwd, r, 'package.json')
     if (!existsSync(p)) continue
     const pkg = JSON.parse(await readFile(p, 'utf8'))
-    if (pkg.dependencies?.vue) vueRoots.push(r)
+    if (pkg.dependencies?.vue) vueRoots.push({ rootDir: r, isComponentLibrary: isVueComponentLibraryPkg(pkg) })
   }
   return vueRoots
 }
@@ -487,8 +544,8 @@ export async function check(cwd = process.cwd()) {
   await checkVueVolarRecommendation(pass, fail, cwd)
 
   const ignorePaths = await loadCursorIgnorePaths(cwd)
-  for (const r of vueRoots) {
-    await checkVuePackage(r, ignorePaths, fail, pass, cwd)
+  for (const { rootDir, isComponentLibrary } of vueRoots) {
+    await checkVuePackage(rootDir, isComponentLibrary, ignorePaths, fail, pass, cwd)
   }
 
   return reporter.getExitCode()

package/rules/vue/vue.mdc

@@ -1,6 +1,6 @@
 ---
 description: Vue
-version: '2.0'
+version: '2.1'
 globs: "**/*.vue"
 alwaysApply: false
 ---
@@ -290,6 +290,8 @@ export default defineConfig({
 
 Потрібно використовувати unplugin-auto-import для автоматичного імпортування компонентів, composables, utils та інших функцій і прибирати з файлів усередині Vite проектів відповідні ручні імпорти, зокрема рядки виду `import { … } from 'vue'` — API Vue (`ref`, `computed`, `watch` тощо) мають підставлятися через auto-import, а не дублюватися явним імпортом з модуля `vue`.
 
+**Виняток — бібліотеки компонентів (`vue` у `peerDependencies`).** Увесь стек auto-import застосовується лише коли `vue` підключено як звичайну `dependencies`. Якщо ж пакет оголошує `vue` у `peerDependencies` — це проєкт-бібліотека компонентів: його джерела споживаються Vite-додатками і **не** проходять через `unplugin-auto-import` споживача (auto-import резолвиться лише в коді самого додатка, не в `node_modules`). Тому до таких пакетів **не** застосовуються: заборона явних `import { ref, computed, … } from 'vue'` (вони обовʼязкові), вимога `'vue'` у `AutoImport.imports`, а також вимоги наявності `VueMacros` / `AutoImport` у `vite.config`. Решта перевірок (заборона `esbuild`, `process.env.npm_lifecycle_event` тощо) лишаються. Тригер винятку — `isVueComponentLibraryPkg` у `npm/rules/vue/js/packages.mjs`.
+
 Потрібно використовувати vite-plugin-vue-layouts-next для автоматичного імпортування layout компонентів.
 
 ## npm_lifecycle_event

package/scripts/lib/worktree-notice.mjs

@@ -8,26 +8,129 @@
  */
 
 /** Маркер початку worktree-блоку (стабільний, не залежить від тексту всередині). */
-export const WORKTREE_START = '<!-- n-cursor:worktree:start -->'
+export const WORKTREE_START = "<!-- n-cursor:worktree:start -->";
 /** Маркер кінця worktree-блоку. */
-export const WORKTREE_END = '<!-- n-cursor:worktree:end -->'
+export const WORKTREE_END = "<!-- n-cursor:worktree:end -->";
 
-const NOTICE_BODY =
-  '> **Worktree:** виконуй цей скіл в окремому git-worktree (`git worktree add`); ' +
-  '**не** запускай паралельно — один інстанс за раз.'
+const FALLBACK_SUFFIX = "task";
 
 /** Наявний блок разом із сусідніми порожніми рядками (для чистого видалення). */
-const BLOCK_RE = /\n*<!-- n-cursor:worktree:start -->[\s\S]*?<!-- n-cursor:worktree:end -->\n*/u
+const BLOCK_RE =
+  /\n*<!-- n-cursor:worktree:start -->[\s\S]*?<!-- n-cursor:worktree:end -->\n*/u;
 
 /** Закриття YAML-frontmatter на початку файла. */
-const FRONTMATTER_RE = /^(---\n[\s\S]*?\n---\n)/u
+const FRONTMATTER_RE = /^(---\n[\s\S]*?\n---\n)/u;
+
+/** Значення `name` з YAML-frontmatter. */
+const NAME_RE = /^name:\s*["']?([^"'\n]+)["']?\s*$/mu;
+
+/** Перший H1 як fallback, якщо frontmatter не містить `name`. */
+const H1_RE = /^#\s+(.+)$/mu;
+
+const CYRILLIC_TRANSLIT = new Map(
+  Object.entries({
+    а: "a",
+    б: "b",
+    в: "v",
+    г: "h",
+    ґ: "g",
+    д: "d",
+    е: "e",
+    є: "ye",
+    ж: "zh",
+    з: "z",
+    и: "y",
+    і: "i",
+    ї: "yi",
+    й: "y",
+    к: "k",
+    л: "l",
+    м: "m",
+    н: "n",
+    о: "o",
+    п: "p",
+    р: "r",
+    с: "s",
+    т: "t",
+    у: "u",
+    ф: "f",
+    х: "kh",
+    ц: "ts",
+    ч: "ch",
+    ш: "sh",
+    щ: "shch",
+    ь: "",
+    ю: "yu",
+    я: "ya",
+    ы: "y",
+    э: "e",
+    ё: "yo",
+    ъ: "",
+  }),
+);
+
+/**
+ * Транслітерує кирилицю в ASCII для короткого suffix.
+ * @param {string} value вхідний текст
+ * @returns {string} транслітерований текст
+ */
+function transliterate(value) {
+  return [...value.toLowerCase()]
+    .map((char) => CYRILLIC_TRANSLIT.get(char) ?? char)
+    .join("");
+}
+
+/**
+ * Робить короткий безпечний suffix для worktree-гілки з назви скіла.
+ * @param {string} content вміст `SKILL.md`
+ * @returns {string} suffix до 10 символів
+ */
+function deriveSuffix(content) {
+  const raw =
+    content.match(NAME_RE)?.[1] ?? content.match(H1_RE)?.[1] ?? FALLBACK_SUFFIX;
+  const slug = transliterate(raw)
+    .trim()
+    .replace(/^n-/u, "")
+    .normalize("NFKD")
+    .replace(/[\u0300-\u036f]/gu, "")
+    .replace(/[^a-z0-9]+/gu, "-")
+    .replace(/^-+|-+$/gu, "");
+
+  return (
+    (slug || FALLBACK_SUFFIX).slice(0, 10).replace(/-+$/u, "") ||
+    FALLBACK_SUFFIX
+  );
+}
+
+/**
+ * Тіло worktree-інструкції з конкретним суфіксом, щоб агент не питав назву гілки.
+ * @param {string} suffix короткий suffix задачі
+ * @returns {string} markdown-блок без маркерів
+ */
+function buildNoticeBody(suffix) {
+  return `> [!IMPORTANT]
+> **Worktree-only skill.** Виконується **виключно** в окремому git-worktree (\`.worktrees/<current-branch>-${suffix}/\`) і **не** паралелиться — один інстанс за раз.
+
+**Крок 0 — preflight (обовʼязковий, перед будь-якими іншими діями).** Якщо перевірка падає — **STOP**: не питай користувача про назву гілки, а сам створи worktree від поточної гілки за конвенцією \`<current-branch>-${suffix}\`. Суфікс \`${suffix}\` — коротка (до 10 символів) транслітерація задачі. Не виконуй **жоден** наступний крок скіла, поки preflight не завершився успіхом.
+
+\`\`\`bash
+if ! git rev-parse --show-toplevel | grep -q '/\\.worktrees/'; then
+  B=$(git branch --show-current)
+  W="\${B}-${suffix}"
+  P="\${W//\\//-}"
+  npx @nitra/cursor worktree add "$W" "n-${suffix}: worktree-only skill"
+  cd ".worktrees/\${P}"
+fi
+\`\`\``;
+}
 
 /**
  * Канонічний блок worktree-інструкції.
+ * @param {string} content вміст `SKILL.md`
  * @returns {string} текст блоку від START до END
  */
-function buildBlock() {
-  return `${WORKTREE_START}\n${NOTICE_BODY}\n${WORKTREE_END}`
+function buildBlock(content) {
+  return `${WORKTREE_START}\n${buildNoticeBody(deriveSuffix(content))}\n${WORKTREE_END}`;
 }
 
 /**
@@ -37,19 +140,19 @@ function buildBlock() {
  * @returns {string} оновлений вміст (ідемпотентно)
  */
 export function injectWorktreeNotice(content, enabled) {
-  const hadBlock = content.includes(WORKTREE_START)
-  const withoutBlock = content.replace(BLOCK_RE, '\n\n')
+  const hadBlock = content.includes(WORKTREE_START);
+  const withoutBlock = content.replace(BLOCK_RE, "\n\n");
 
   if (!enabled) {
-    return hadBlock ? withoutBlock : content
+    return hadBlock ? withoutBlock : content;
   }
 
-  const block = buildBlock()
-  const fm = withoutBlock.match(FRONTMATTER_RE)
+  const block = buildBlock(withoutBlock);
+  const fm = withoutBlock.match(FRONTMATTER_RE);
   if (fm) {
-    const head = fm[1]
-    const rest = withoutBlock.slice(head.length).replace(/^\n+/u, '')
-    return `${head}\n${block}\n\n${rest}`
+    const head = fm[1];
+    const rest = withoutBlock.slice(head.length).replace(/^\n+/u, "");
+    return `${head}\n${block}\n\n${rest}`;
   }
-  return `${block}\n\n${withoutBlock.replace(/^\n+/u, '')}`
+  return `${block}\n\n${withoutBlock.replace(/^\n+/u, "")}`;
 }