@nitra/cursor 2.0.0 → 3.1.0

package/CHANGELOG.md

@@ -1,5 +1,35 @@
 # Changelog
 
+## [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
+
+- n-cursor flow (v2.0-a Ф0-Ф1.1): каркас dispatcher + CLI `case 'flow'` (init/verify/release/run/resume/cancel/repair — поки stub-и), Capability Router з явною декларацією моделі (native/polyfill, default→polyfill лише за наявного runner-а), crash-safe state-store (.flow.json sibling, atomic temp+fsync+rename, fail-closed на corruption). 29 unit-тестів (withTmpDir).
+- n-cursor flow v2.0-a Ф1.2-Ф1.4: WAL-журнал .events.jsonl (append-only, торований останній рядок толерується), per-branch lock через reuse withLock із fail-closed override (додано опцію onWaitTimeout у спільний with-lock, back-compat), cleanupFlowSiblings (.flow.json/.events.jsonl/lock). recordTransition (WAL: подія до зміни статусу). +22 тести.
+- n-cursor flow v2.0-a Ф2 (verify): reviewer.mjs — Level-1 «Суддя» проганяє lint+coverage gates через ін'єктований runner (fail-fast, fingerprint на повному pass через reuse worktree-fingerprint); flow verify — Пасивний Турнікет: запускає gates у поточному worktree, записує результати+fingerprint у наявний стан (recordTransition), exit 0/1. +11 тестів.
+- n-cursor flow v2.0-a Ф2·2: flow init (n-cursor worktree add + detect-existing-isolation через git rev-parse, init .flow.json з base_commit; reuse worktreePaths/sanitizeBranch) + flow release (n-cursor change + completion snapshot у стан і task record) + snapshot.mjs (buildCompletionSnapshot/upsertSummaryBlock/writeSummaryToTaskRecord). reviewer тепер захоплює вивід проваленого gate. Пасивний Турнікет (init/verify/release) завершено. +18 тестів.
+- n-cursor flow Ф2·4: bundled-правило flow (матеріалізується як .cursor/rules/n-flow.mdc) — контракт Пасивного Турнікета для IDE-агентів (Cursor/Claude Code): init -> сам пишеш код (TDD) -> verify (3 спроби на фейл) -> release. alwaysApply; pure-doc + стандартний fix.mjs (runStandardRule). Авто-дискавериться, активується при sync. Завершує Фасад A повністю.
+- n-cursor flow v2.0-a Ф3 (двигун-блоки): SubagentRunner (§15.1) — selectBackend (sdk>claude>cursor за ANTHROPIC_API_KEY/PATH, fail коли нічого нема), cliRunner (claude/cursor-agent -p, CLI-auth), sdkRunner (claude-agent-sdk, dynamic import); planner — parsePlan (валідація+нормалізація, fail-closed на невалідному) + generatePlan. Усе з мок-ін'єкцією (нуль реальних API/SDK у тестах). +24 тести.
+- n-cursor flow v2.0-a Ф4·a: executor.mjs — серце Активного Раннера. Виконує план покроково: мікропромпт зі стану (не історія) -> спавн субагента -> verify -> commit ЛИШЕ після зеленого (commit-інваріант §4.1.7) -> repair (per-step retry) -> на вичерпанні HITL (blocked-on-human + structured question). microprompt/patchStep — pure. Усе з ін'єкцією runner/verify/commit (нуль реальних LLM/git у тестах). +6 тестів.
+- n-cursor flow v2.0-a Ф4·b: Активний Раннер end-to-end. flow run (ensureWorktree -> planner -> executor; exit 0 done / 1 fail / 2 blocked-on-human), flow resume (safe-resume git reset + HITL-відповіді як hint + свіжі спроби), flow cancel (cleanup sibling-ів), flow repair (--discard-step-work / діагностика). ensureWorktree витягнуто як спільне для init/run. Усі 7 підкоманд реальні. +12 тестів (103 у dispatcher). v2.0-a (Фасади A+B) функціонально завершено.
+- n-cursor flow v2.0-a: (1) budget guard для flow run --autonomous (withBudget обгортає runner, BudgetExceeded при перевищенні maxApiCalls з .n-cursor.json flow.autonomous; на abort -> status failed, exit 1). (2) Ф1.4 борг закрито: worktree remove тепер reuse-кличе cleanupFlowSiblings (flow-sibling-и не осиротіють). Заодно виправлено передіснуючі switch-case-braces у worktree-cli. +4 тести.
+- n-cursor flow v2.0-b: команда n-cursor trace — наскрізна простежуваність (§5.4/§7). Читає front-matter артефактів у docs/{tasks,specs,plans,adr}, будує ланцюг за лінками adr/spec/plan/change/task, флагує розриви (лінк на неіснуючий файл) з exit 1; --json для machine-readable. parseFrontMatter/analyze/render — pure, FS ін'єктовний. Підтверджено на власних spec<->plan. +10 тестів.
+
+### Changed
+
+- n-cursor flow v2.0.0 (major): Dual-Mode Dispatcher — Пасивний Турнікет (flow init/verify/release) + Активний Раннер (flow run/resume/cancel/repair) + n-cursor trace + docs/{specs,plans} міграція
+
 ## [2.0.0] - 2026-05-31
 
 ### 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/<branch>/`) — **не** в основному дереві й **не** паралельно. Перший крок такого скіла (блок `n-cursor:worktree:start` у його `SKILL.md`) — **preflight**: якщо `git rev-parse --show-toplevel` не вказує під `.worktrees/`, **STOP** і спершу `npx @nitra/cursor worktree add <branch> "<навіщо>"` → `cd .worktrees/<branch>`. Чисте робоче дерево — **не** привід пропустити 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": "2.0.0",
+  "version": "3.1.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.10'
 globs: "**/Dockerfile*"
 alwaysApply: false
 ---
@@ -88,6 +88,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

@@ -31,6 +31,7 @@ import { readFile } from 'node:fs/promises'
 import { basename } from 'node:path'
 
 import { getMirrorGcrHint, getFromImageToken } from '../lib/docker-mirror.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'
@@ -336,6 +337,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-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-ci/meta.json

@@ -1 +1 @@
-{ "lint": "ci" }
+{ "auto": { "glob": ["**/*.mjs", "**/*.cjs", "**/*.js", "**/*.jsx", "**/*.ts", "**/*.tsx"] }, "lint": "ci" }

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

@@ -12,9 +12,15 @@ export const WORKTREE_START = '<!-- n-cursor:worktree:start -->'
 /** Маркер кінця worktree-блоку. */
 export const WORKTREE_END = '<!-- n-cursor:worktree:end -->'
 
-const NOTICE_BODY =
-  '> **Worktree:** виконуй цей скіл в окремому git-worktree (`git worktree add`); ' +
-  '**не** запускай паралельно — один інстанс за раз.'
+const NOTICE_BODY = `> [!IMPORTANT]
+> **Worktree-only skill.** Виконується **виключно** в окремому git-worktree (\`.worktrees/<branch>/\`) і **не** паралелиться — один інстанс за раз.
+
+**Крок 0 — preflight (обовʼязковий, перед будь-якими іншими діями).** Якщо перевірка падає — **STOP**: створи worktree і лише тоді продовжуй. Не виконуй **жоден** наступний крок скіла, поки preflight не завершився успіхом.
+
+\`\`\`bash
+git rev-parse --show-toplevel | grep -q '/\\.worktrees/' \\
+  || { echo "ABORT: не у worktree. Спершу: npx @nitra/cursor worktree add <branch> \\"<навіщо>\\" && cd .worktrees/<branch>"; exit 1; }
+\`\`\``
 
 /** Наявний блок разом із сусідніми порожніми рядками (для чистого видалення). */
 const BLOCK_RE = /\n*<!-- n-cursor:worktree:start -->[\s\S]*?<!-- n-cursor:worktree:end -->\n*/u