@nitra/cursor 3.1.0 → 3.2.1

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # Changelog
 
+## [3.2.1] - 2026-06-01
+
+### Fixed
+
+- worktree-only skills: прибрано shell expansion з preflight, щоб агент створював worktree literal-командами без confirmation prompt
+
+## [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

package/bin/n-cursor.js

@@ -651,7 +651,7 @@ function buildClaudeWorktreeEnforcementSectionLines() {
     '',
     '## 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.',
+    'Скіл із **`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>` і без shell expansion (без command substitution, variable expansion чи backticks). Чисте робоче дерево — **не** привід пропустити preflight.',
     ''
   ]
 }

package/package.json

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

package/rules/docker/docker.mdc

@@ -1,6 +1,6 @@
 ---
 description: Dockerfile — lint-docker / hadolint; перевірка check-docker
-version: '1.10'
+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 принцип, наприклад:

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,10 @@
  * Кореневий .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'
@@ -109,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')
@@ -150,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
 
@@ -166,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})`
   }
 
@@ -310,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 репортер перевірок
@@ -322,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}`)

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/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/scripts/lib/worktree-notice.mjs

@@ -8,32 +8,133 @@
  */
 
 /** Маркер початку 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 = `> [!IMPORTANT]
-> **Worktree-only skill.** Виконується **виключно** в окремому git-worktree (\`.worktrees/<branch>/\`) і **не** паралелиться — один інстанс за раз.
+const FALLBACK_SUFFIX = "task";
 
-**Крок 0 — preflight (обовʼязковий, перед будь-якими іншими діями).** Якщо перевірка падає — **STOP**: створи worktree і лише тоді продовжуй. Не виконуй **жоден** наступний крок скіла, поки preflight не завершився успіхом.
+/** Наявний блок разом із сусідніми порожніми рядками (для чистого видалення). */
+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;
+
+/** Значення `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
-git rev-parse --show-toplevel | grep -q '/\\.worktrees/' \\
-  || { echo "ABORT: не у worktree. Спершу: npx @nitra/cursor worktree add <branch> \\"<навіщо>\\" && cd .worktrees/<branch>"; exit 1; }
-\`\`\``
+git rev-parse --show-toplevel
+git branch --show-current
+\`\`\`
 
-/** Наявний блок разом із сусідніми порожніми рядками (для чистого видалення). */
-const BLOCK_RE = /\n*<!-- n-cursor:worktree:start -->[\s\S]*?<!-- n-cursor:worktree:end -->\n*/u
+Якщо перша команда показала, що ти **не** в \`.worktrees/\`, візьми вивід другої команди як \`<current-branch>\` і виконай **literal-команди без shell expansion** (без command substitution, variable expansion чи backticks). Наприклад, якщо поточна гілка \`feature/x\`:
 
-/** Закриття YAML-frontmatter на початку файла. */
-const FRONTMATTER_RE = /^(---\n[\s\S]*?\n---\n)/u
+\`\`\`bash
+npx @nitra/cursor worktree add "feature/x-${suffix}" "n-${suffix}: worktree-only skill"
+cd ".worktrees/feature-x-${suffix}"
+\`\`\`
+
+Тобто branch-argument лишає slash як у git-гілці, а шлях для \`cd\` бере sanitized форму: slash → \`-\`.`;
+}
 
 /**
  * Канонічний блок 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}`;
 }
 
 /**
@@ -43,19 +144,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, "")}`;
 }