@nitra/cursor 12.8.6 → 12.8.8

package/rules/hasura/policy/svc_hl/svc_hl.mdc

@@ -0,0 +1,15 @@
+## Rego-gate: іменування headless та clusterIP Service
+
+Rego-пакет: `hasura.svc_hl`
+
+Цільові файли: `hasura/k8s/base/svc.yaml`, `hasura/k8s/base/svc-hl.yaml`
+
+Перевіряє два правила іменування Kubernetes Service:
+
+- **Headless Service** (`spec.clusterIP: None`) — ім'я має закінчуватись на `-h-hl`
+- **ClusterIP Service** (не headless) — ім'я має закінчуватись на `-h`
+
+Ресурси з `kind != "Service"` пропускаються без помилок.
+
+✓ `db-h-hl` (headless), `db-h` (clusterIP)
+✗ `contract-h` як headless, `db-h-hl` як clusterIP

package/rules/image-avif/js/avif_generation.mdc

@@ -0,0 +1,26 @@
+## Чотирикроковий пайплайн генерації AVIF-двійників
+
+AVIF-двійники (`<name>.<ext>.avif`) генерує **виключно** `npx @nitra/cursor fix image-avif`. Правило `image-compress` відповідає лише за стиснення початкових raster/SVG-файлів через `@nitra/minify-image`, а AVIF лишається окремим правилом. Перевірка виконує чотири кроки в порядку:
+
+1. **Pre-scan**: шукає у `.vue`/`.html` хоча б одне raster-посилання, яке потенційно треба переписати на AVIF-двійник (`import x from '...png'` або `<img src="...png" />`). Пакети з opt-out `disable-avif: true` пропускаються. **Якщо жодного raster-посилання не знайдено — `check image-avif` завершується успіхом одразу: ні `npx --avif`, ні rewrite, ні cleanup-сиріт не виконуються** (нічого було б змінювати). Так уникаємо дорогого `npx @nitra/minify-image` у проєктах, де AVIF не вживається.
+2. Запускає `npx @nitra/minify-image --src=. --write --avif` (≥ **3.3.1**) — генерує `<name>.<ext>.avif` поряд з кожним PNG/JPEG/GIF. CLI порівнює sha1 кожного raster-сорсу зі збереженим у `.n-minify-image.tsv` і перезаписує `<source>.avif` при зміні оригіналу.
+3. Сканує `.vue` (а також `.html`) файли в кожному workspace-пакеті (root + workspaces) і автоматично переписує raster-посилання на AVIF-двійник у двох формах:
+   - **Імпорт-пов'язані** — `import x from '...png|jpg|jpeg|gif'` (далі `:src="x"` у шаблоні);
+   - **Прямі статичні** — `<img src="...png" />` у `<template>` (Vite перетворює такий шлях на asset-імпорт на етапі збірки, тож вимога та сама).
+4. Видаляє AVIF-сироти: ходить по всіх `<...>.avif` у репозиторії; якщо на двійник не лишилось жодного посилання у `.vue`/`.html` — файл видаляється. **AVIF на диску лишається лише там, де заміна реально відбулась** — тому невикористані оригінали не накопичують `.avif`-«хвости». **Зауваж**: cleanup виконується ЛИШЕ якщо pre-scan на кроці 1 знайшов хоча б одне raster-посилання — інакше осиротілі `.avif` залишаються недоторканими (видаляться вже наступним прогоном, коли в `.vue`/`.html` зʼявиться raster для конвертації).
+
+```vue title="App.vue (після check image-avif)"
+<script setup>
+import welcomeImage from './assets/welcome.png.avif'
+</script>
+
+<template>
+  <img :src="welcomeImage" alt="Welcome" />
+</template>
+```
+
+Реактивне `:src="..."` (з JS-виразом — змінною, тернарником, викликом тощо) **не сканується** — значення обчислюється у рантаймі й шлях туди потрапляє через імпорт або інший резолвинг, який ловить імпорт-перевірка вище. SVG не торкаємо (vector → AVIF безглуздо). Атрибути `data-src=`, `obj.src=` у `<script>` тощо також пропускаються.
+
+Якщо raster-посилання у `.vue`/`.html` не вдалось переписати (наприклад, оригіналу немає на диску, тож і `.avif` не згенерувався) — `check image-avif` падає з помилкою на конкретний файл.
+
+AVIF-двійники **зберігаємо в git** — це готові артефакти для віддачі браузеру (без них ефект від AVIF втрачається на чистому checkout-і).

package/rules/image-avif/js/package_json_optout.mdc

@@ -0,0 +1,21 @@
+## Опт-аут для конкретного пакета
+
+У workspace-пакеті, де AVIF-імпорти небажані (наприклад, мобільний бандл або публічний сайт без гарантованої AVIF-підтримки), додай у `package.json` цього пакета. Заборонений typo `disabled-avif` (канон — `disable-avif`): [package.json.deny.json](./policy/package_json/template/package.json.deny.json).
+
+```json title="apps/site/package.json"
+{
+  "@nitra/minify-image": {
+    "disable-avif": true
+  }
+}
+```
+
+Тоді перевірка пропускає `.vue` файли цього пакета і не видаляє наявні `.avif` всередині як «сироти». У root-`package.json` опт-аут діє лише для файлів кореня (вкладені workspaces перевіряються незалежно — вмикай прапор у кожному пакеті, де треба).
+
+### Валідація package.json через conftest (Rego)
+
+Rego-пакет `image_avif.package_json` перевіряє коректність конфігурації опт-ауту у `package.json`:
+
+- Поле `"@nitra/minify-image"` має бути обʼєктом (якщо задано).
+- Ключ `"disable-avif"` має бути `boolean`.
+- Забороняє typo-ключі (наприклад, `"disabled-avif"`) через deny-template із [`package.json.deny.json`](./policy/package_json/template/package.json.deny.json).

package/rules/image-avif/main.mdc

@@ -5,41 +5,12 @@ globs: "**/*.{png,jpg,jpeg,gif,avif,vue,html}"
 alwaysApply: false
 ---
 
-AVIF-двійники (`<name>.<ext>.avif`) генерує **виключно** `npx @nitra/cursor fix image-avif`. Правило `image-compress` відповідає лише за стиснення початкових raster/SVG-файлів через `@nitra/minify-image`, а AVIF лишається окремим правилом. Перевірка робить чотири кроки в порядку:
+Правило забезпечує, що кожне raster-зображення (`png`, `jpg`, `jpeg`, `gif`), на яке посилаються `.vue`/`.html` файли, має AVIF-двійник і що посилання переписані на нього. Генерація, rewrite і cleanup AVIF-сиріт виконуються автоматично через `npx @nitra/cursor fix image-avif`.
 
-1. **Pre-scan**: шукає у `.vue`/`.html` хоча б одне raster-посилання, яке потенційно треба переписати на AVIF-двійник (`import x from '...png'` або `<img src="...png" />`). Пакети з opt-out `disable-avif: true` пропускаються. **Якщо жодного raster-посилання не знайдено — `check image-avif` завершується успіхом одразу: ні `npx --avif`, ні rewrite, ні cleanup-сиріт не виконуються** (нічого було б змінювати). Так уникаємо дорогого `npx @nitra/minify-image` у проєктах, де AVIF не вживається.
-2. Запускає `npx @nitra/minify-image --src=. --write --avif` (≥ **3.3.1**) — генерує `<name>.<ext>.avif` поряд з кожним PNG/JPEG/GIF. CLI порівнює sha1 кожного raster-сорсу зі збереженим у `.n-minify-image.tsv` і перезаписує `<source>.avif` при зміні оригіналу.
-3. Сканує `.vue` (а також `.html`) файли в кожному workspace-пакеті (root + workspaces) і автоматично переписує raster-посилання на AVIF-двійник у двох формах:
-   - **Імпорт-пов'язані** — `import x from '...png|jpg|jpeg|gif'` (далі `:src="x"` у шаблоні);
-   - **Прямі статичні** — `<img src="...png" />` у `<template>` (Vite перетворює такий шлях на asset-імпорт на етапі збірки, тож вимога та сама).
-4. Видаляє AVIF-сироти: ходить по всіх `<...>.avif` у репозиторії; якщо на двійник не лишилось жодного посилання у `.vue`/`.html` — файл видаляється. **AVIF на диску лишається лише там, де заміна реально відбулась** — тому невикористані оригінали не накопичують `.avif`-«хвости». **Зауваж**: cleanup виконується ЛИШЕ якщо pre-scan на кроці 1 знайшов хоча б одне raster-посилання — інакше осиротілі `.avif` залишаються недоторканими (видаляться вже наступним прогоном, коли в `.vue`/`.html` зʼявиться raster для конвертації).
+[image-avif-avif_generation](./js/avif_generation.mdc)
 
-```vue title="App.vue (після check image-avif)"
-<script setup>
-import welcomeImage from './assets/welcome.png.avif'
-</script>
+[image-avif-package_json_optout](./js/package_json_optout.mdc)
 
-<template>
-  <img :src="welcomeImage" alt="Welcome" />
-</template>
-```
+## Швидкий gate через conftest
 
-Реактивне `:src="..."` (з JS-виразом — змінною, тернарником, викликом тощо) **не сканується** — значення обчислюється у рантаймі й шлях туди потрапляє через імпорт або інший резолвинг, який ловить імпорт-перевірка вище. SVG не торкаємо (vector → AVIF безглуздо). Атрибути `data-src=`, `obj.src=` у `<script>` тощо також пропускаються.
-
-Якщо raster-посилання у `.vue`/`.html` не вдалось переписати (наприклад, оригіналу немає на диску, тож і `.avif` не згенерувався) — `check image-avif` падає з помилкою на конкретний файл.
-
-AVIF-двійники **зберігаємо в git** — це готові артефакти для віддачі браузеру (без них ефект від AVIF втрачається на чистому checkout-і).
-
-## Опт-аут для конкретного пакета
-
-У workspace-пакеті, де AVIF-імпорти небажані (наприклад, мобільний бандл або публічний сайт без гарантованої AVIF-підтримки), додай у `package.json` цього пакета. Заборонений typo `disabled-avif` (канон — `disable-avif`): [package.json.deny.json](./policy/package_json/template/package.json.deny.json).
-
-```json title="apps/site/package.json"
-{
-  "@nitra/minify-image": {
-    "disable-avif": true
-  }
-}
-```
-
-Тоді перевірка пропускає `.vue` файли цього пакета і не видаляє наявні `.avif` всередині як «сироти». У root-`package.json` опт-аут діє лише для файлів кореня (вкладені workspaces перевіряються незалежно — вмикай прапор у кожному пакеті, де треба).
+[image-avif-package_json](./policy/package_json/package_json.mdc)

package/rules/image-avif/policy/package_json/package_json.mdc

@@ -0,0 +1,18 @@
+## Rego-gate: структура опт-аут конфігу у package.json
+
+Rego-пакет: `image-avif.package_json`
+
+Цільові файли: `package.json` (передається через `--input` у conftest).
+
+Перевіряє три умови:
+
+- **Тип поля** — `"@nitra/minify-image"` має бути обʼєктом (якщо задано); рядок, масив чи boolean → deny.
+- **Тип прапора** — `"@nitra/minify-image.disable-avif"` має бути `boolean`; рядок або число → deny.
+- **Typo-ключі** — забороняє ключі зі списку deny-template [`package.json.deny.json`](./template/package.json.deny.json) (наприклад, `"disabled-avif"` замість `"disable-avif"`).
+
+Deny-template: [package.json.deny.json](./template/package.json.deny.json)
+
+✓ `{ "@nitra/minify-image": { "disable-avif": true } }`
+✗ `{ "@nitra/minify-image": { "disabled-avif": true } }` — typo-ключ
+✗ `{ "@nitra/minify-image": "disable-avif" }` — поле не є обʼєктом
+✗ `{ "@nitra/minify-image": { "disable-avif": "yes" } }` — не boolean

package/rules/image-compress/js/package_json.mdc

@@ -0,0 +1,7 @@
+## Заборонені залежності у `package.json`
+
+`@nitra/minify-image` не повинен зʼявлятися ні в `dependencies`, ні в `devDependencies` — CLI запускається лише через `npx`. Якщо потрібен явний пін — у самому виклику (`npx @nitra/minify-image@^3 --src=. --write`).
+
+Перевіряється через Rego-пакет `image_compress.package_json`: [package.json.deny.json](./policy/package_json/template/package.json.deny.json)
+
+Окремий `package.json`-скрипт `lint-image` не потрібен і не перевіряється — єдина точка входу `n-cursor lint image-compress`.

package/rules/image-compress/js/package_setup.mdc

@@ -0,0 +1,13 @@
+## Кеш-файли: що зберігати в git
+
+**`.n-minify-image.tsv`** у корені сканованого каталогу — **має бути в git** (source of truth для sha1-перевірок і lifetime savings). У `.gitignore` його не додавай.
+
+**`node_modules/.cache/@nitra/minify-image/mtime.tsv`** — локальний fast-path; авто-gitignored через `node_modules/`.
+
+Застарілий **`.minify-image-cache.tsv`** у корені (з версій `@nitra/minify-image` < 3.2) — видали після міграції на split-cache:
+
+```sh
+git rm --cached .minify-image-cache.tsv 2>/dev/null || true && rm -f .minify-image-cache.tsv
+```
+
+Також прибери відповідний рядок з `.gitignore`, якщо є.

package/rules/image-compress/main.mdc

@@ -9,18 +9,10 @@ CLI [`@nitra/minify-image`](https://www.npmjs.com/package/@nitra/minify-image) (
 
 Окремий workflow `lint-image.yml` створювати не треба; якщо потрібен CI-gate для зображень, використовуй `n-cursor lint image-compress --read-only`.
 
-## `package.json`
+[image-compress-package_setup](./js/package_setup.mdc)
 
-- Заборонені залежності `@nitra/minify-image` у deps/devDeps: [package.json.deny.json](./policy/package_json/template/package.json.deny.json)
+[image-compress-package_json](./js/package_json.mdc)
 
-Окремий `package.json`-скрипт `lint-image` не потрібен і не перевіряється — єдина точка входу `n-cursor lint image-compress`.
+## Швидкий gate через conftest
 
-## Кеш
-
-- **`.n-minify-image.tsv`** у корені сканованого каталогу — **має бути в git** (source of truth для sha1-перевірок і lifetime savings). У `.gitignore` його не додавай.
-- **`node_modules/.cache/@nitra/minify-image/mtime.tsv`** — локальний fast-path; авто-gitignored через `node_modules/`.
-- Застарілий `.minify-image-cache.tsv` у корені — видали (`git rm --cached`, прибери рядок з `.gitignore`).
-
-## Заборонені залежності
-
-`@nitra/minify-image` не повинен зʼявлятися ні в `dependencies`, ні в `devDependencies` — CLI запускається лише через `npx`. Якщо потрібен явний пін — у самому виклику (`npx @nitra/minify-image@^3 --src=. --write`).
+[image-compress-package_json](./policy/package_json/package_json.mdc)

package/rules/image-compress/policy/package_json/package_json.mdc

@@ -0,0 +1,13 @@
+## Заборона `@nitra/minify-image` у залежностях (`package.json`)
+
+Rego-пакет: `image_compress.package_json`
+
+Цільовий файл: `package.json` (єдиний файл проєкту).
+
+Перевіряє поля `dependencies` та `devDependencies`: якщо там присутній пакет `@nitra/minify-image` — deny. Список заборонених пакетів надходить через `--data` з канонічного шаблону:
+
+[package.json.deny.json](./template/package.json.deny.json)
+
+✓ `{}` — порожній `package.json` без залежностей
+✗ `{ "dependencies": { "@nitra/minify-image": "^4.0.1" } }` — заборонено, використовуй `npx`
+✗ `{ "devDependencies": { "@nitra/minify-image": "^4.0.1" } }` — заборонено, використовуй `npx`

package/rules/js/docs/index.md

@@ -6,7 +6,7 @@ resource: npm/rules/js/
 
 # npm/rules/js
 
-| Файл | Тип |
-|---|---|
-| [fix.mjs](fix.md) | JS Module |
+| Файл                | Тип       |
+| ------------------- | --------- |
+| [fix.mjs](fix.md)   | JS Module |
 | [main.mjs](main.md) | JS Module |

package/rules/js/js/dep-policy.mdc

@@ -0,0 +1,17 @@
+## Залежнісна політика (що не додавати)
+
+`@e18e/eslint-plugin` окремо не додавай — він уже в залежностях `@nitra/eslint-config` (з **3.8.0**), oxlint підвантажує його з `node_modules`. Пакети `oxlint`/`eslint`/`jscpd`/`knip` теж не додавай у `devDependencies` без потреби монорепо — `bunx` тягне їх ad-hoc.
+
+### Заборона `@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"`.
+
+Міграція — лише 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/js/js/eslint-config.mdc

@@ -0,0 +1,28 @@
+## ESLint flat config — `eslint.config.js`
+
+У корені проєкту має бути `eslint.config.js` (або `eslint.config.mjs`) з flat config на основі `getConfig` з `@nitra/eslint-config`.
+
+```javascript title="eslint.config.js"
+import { getConfig } from '@nitra/eslint-config'
+
+export default [
+  {
+    ignores: ['**/auto-imports.d.ts']
+  },
+  ...getConfig({
+    node: ['npm']
+  })
+]
+```
+
+У монорепо пакети з Vite (frontend) вкажи в секції `vue`, решту — у секції `node` у виклику `getConfig`.
+
+Обов'язкові умови:
+- файл `eslint.config.js` або `eslint.config.mjs` існує;
+- містить виклик `getConfig`;
+- імпортує з `@nitra/eslint-config`;
+- у `ignores` є запис `**/auto-imports.d.ts`.
+
+Застарілі конфіги (`.eslintrc`, `.eslintrc.js`, `.eslintrc.json`, `.eslintrc.yml`) — **видали**, вони несумісні з flat config.
+
+З версії `@nitra/eslint-config` **3.9.2** `getConfig` вбудовує ignore для `**/adr/**` — ADR-документи не валідуються ESLint, локально цей glob додавати не потрібно.

package/rules/js/js/extensions.mdc

@@ -0,0 +1,8 @@
+## `.vscode/extensions.json` — рекомендовані розширення
+
+У `.vscode/extensions.json` поле `recommendations` має містити:
+- `dbaeumer.vscode-eslint`
+- `github.vscode-github-actions`
+- `oxc.oxc-vscode`
+
+Канон: [extensions.json.snippet.json](./policy/vscode_extensions/template/extensions.json.snippet.json)

package/rules/js/js/file-extensions.mdc

@@ -0,0 +1,12 @@
+## Розширення нових файлів — `.mjs` / `.cjs`, не `.js`
+
+**Нові** JS-файли створюй з явним розширенням модуля:
+
+- **`.mjs`** — для ESM (типовий випадок);
+- **`.cjs`** — для CommonJS, де він справді потрібен.
+
+Голий **`.js`** для нового файлу **заборонено**. Розширення `.js` інтерпретується як ESM чи CJS лише за полем `package.json#type`, тож той самий файл читається по-різному залежно від пакета. Явне `.mjs`/`.cjs` робить тип модуля однозначним **без читання `package.json`** — навіть якщо `type` зміниться або файл перемістять в інший пакет. Це доповнює вимогу `"type": "module"` у `package-json.mdc`: `type` лишається каноном для всього дерева, а розширення нового файлу прибирає залежність від нього.
+
+Стосується **backend і frontend** — будь-який новий вихідний файл: `src/`, тести `*.test.*`, `scripts/`, `src/conn/` тощо.
+
+**Існуючі `.js` лишаються як є** — масово перейменовувати не треба; це конвенція для нового коду. Автоматичної перевірки тут немає: stateless-скан не відрізнить новий файл від існуючого, тож `.js` нікого не фейлить.

package/rules/js/js/for-in.mdc

@@ -0,0 +1,26 @@
+## `for...in` заборонено — рефакторити на `for...of`
+
+Конструкція `for (const k in obj)` обходить успадковані ключі прототипу, тому майже завжди тягне `Object.hasOwn(obj, k)`-guard. Заборонена у `@nitra/eslint-config` через `no-restricted-syntax` для `ForInStatement` (з версії **3.8.0**). У каноні oxlint лишається `guard-for-in` як часткова страховка (oxlint не підтримує `no-restricted-syntax`).
+
+Замість цього обходь масив напряму, а об'єкт — через `Object.entries` / `Object.keys` / `Object.values`. У такому коді guard за `Object.hasOwn` стає непотрібним і має зникнути разом із `for...in`.
+
+```javascript title="❌ до"
+for (const k in obj) {
+  if (!Object.hasOwn(obj, k)) continue
+  use(k, obj[k])
+}
+
+for (const i in arr) {
+  use(arr[i])
+}
+```
+
+```javascript title="✅ після"
+for (const [k, v] of Object.entries(obj)) {
+  use(k, v)
+}
+
+for (const item of arr) {
+  use(item)
+}
+```

package/rules/js/js/jscpd.mdc

@@ -0,0 +1,42 @@
+## `.jscpd.json` — виявлення дублювання коду
+
+У корені проєкту має бути `.jscpd.json`. Мінімум: увімкнути облік `.gitignore`, ненульовий код виходу при знаходженні клонів, консольний звіт.
+
+```json title=".jscpd.json"
+{
+  "gitignore": true,
+  "exitCode": 1,
+  "reporters": ["console"],
+  "minLines": 25,
+  "ignore": [".claude/worktrees/**", "**/dist/**", "**/CHANGELOG.md"]
+}
+```
+
+Канон ключів `.jscpd.json` (`gitignore`, `exitCode`, `reporters`, `minLines`, `ignore` як subset-of): [.jscpd.json.snippet.json](./policy/jscpd/template/.jscpd.json.snippet.json)
+
+### Ігнорування `.claude/worktrees/`
+
+Каталог `.claude/worktrees/` (робочі копії, які Claude Code створює через **superpowers:using-git-worktrees**) має ігноруватися:
+- додай `.claude/worktrees/` у кореневий `.gitignore` (штатне місце для не-комітних робочих копій);
+- у `.jscpd.json` додай `.claude/worktrees/**` у `ignore` як страховку на випадок запуску без `gitignore: true`.
+
+Без цього jscpd сканує паралельну копію репо в worktree і фіксує самозбіги між дзеркальними файлами.
+
+```text title=".gitignore (фрагмент)"
+.claude/worktrees/
+```
+
+### Ігнорування `**/CHANGELOG.md`
+
+`**/CHANGELOG.md` у каноні `ignore`: release-журнали різних пакетів структурно повторюються (заголовки `## [x.y.z] - YYYY-MM-DD`, секції `### Added / Changed / Fixed` за Keep a Changelog), і `jscpd` за `minLines: 25` фіксує їх як клон — це false positive. Без цього в монорепо легко зловити критичний `bun run lint` на парі CHANGELOG-ів довжиною від ~25 рядків.
+
+### Рефакторинг vs конфіг
+
+Коли **jscpd** знаходить клони, спочатку зменшуй дублювання кодом, а не конфігом.
+
+- **Рефакторинг:** винеси спільні фрагменти в функції, модулі, утиліти, composables/hooks, спільні компоненти або базові типи — залежно від контексту.
+- **Структура:** якщо одна й та сама логіка розмазана між файлами чи пакетами, запропонуй зміну структури (наприклад, спільний модуль, `shared/`, внутрішній пакет у monorepo), щоб була **одна канонічна реалізація** і повторні місця лише викликали її.
+
+Розширення `ignore` чи завищення `minLines` лише щоб прибрати звіт — не заміна рефакторингу для справжніх клонів. Якщо збіг **семантично випадковий** (генерований код, формальні шаблони без спільної логіки), після оцінки допустимо точковий `ignore` або зміна порогу — з коротким обґрунтуванням.
+
+Перед рефакторингом перевір чи є тести на блоки які підлягають зміні (Bun.test для js, playwright для vue). Якщо тестів немає або вони не покривають — спочатку створи їх, перевір що вони відпрацьовують коректно, потім роби рефакторинг і ще раз запускай тести.

package/rules/js/js/knip.mdc

@@ -0,0 +1,15 @@
+## `knip.json` — аналіз невикористаних залежностей та експортів
+
+Залежнісний аналіз (knip — невикористані залежності/експорти, `knip.json` канон) крос-файловий; запускається автоматично у `lint --full` разом з jscpd.
+
+У корені проєкту має бути **`knip.json`**, який стартує з канонічного baseline з пакета `@nitra/cursor` — файл [`npm/rules/js/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-.+/`, `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` копіює канон у корінь проєкту (side effect). Після створення модифікуй файл під свій проєкт як завгодно: перевіряємо лише наявність, зміст подальших змін не валідується.
+
+Пакет `knip` окремо в `devDependencies` не додавай — `bunx knip` тягне його ad-hoc, як oxlint/eslint/jscpd.

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

@@ -0,0 +1,58 @@
+## GitHub Actions: `lint-js.yml` — CI-лінт JS
+
+Додай workflow для лінту JS у CI:
+
+```yaml title=".github/workflows/lint-js.yml"
+name: Lint JS
+
+on:
+  push:
+    branches:
+      - dev
+      - main
+    paths:
+      - '**/*.js'
+      - '**/*.mjs'
+      - '**/*.cjs'
+      - '**/*.jsx'
+      - '**/*.ts'
+      - '**/*.tsx'
+      - '**/*.vue'
+      - '**/eslint.config.*'
+
+  pull_request:
+    branches:
+      - dev
+      - main
+
+concurrency:
+  group: ${{ github.ref }}-${{ github.workflow }}
+  cancel-in-progress: true
+
+jobs:
+  eslint:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          persist-credentials: false
+
+      - uses: ./.github/actions/setup-bun-deps
+
+      - name: Eslint
+        run: |
+          bunx oxlint
+          bunx eslint .
+          bunx jscpd .
+          bunx knip --no-config-hints
+```
+
+Канон workflow `.github/workflows/lint-js.yml`: [lint-js.yml.snippet.yml](./policy/lint_js_yml/template/lint-js.yml.snippet.yml)
+
+Перед `./.github/actions/setup-bun-deps` — `actions/checkout@v6` (з `persist-credentials: false`, див. `ga.mdc`). Composite action: Node 24, Bun, кеш, `bun install --frozen-lockfile`.
+
+Один workflow на лінт JS; зайвий `lint.yml` з тими самими кроками (`bunx oxlint`, `bunx eslint`, `jscpd`) — прибери.
+
+У CI `--fix` для oxlint/eslint — **заборонено**: CI лише перевіряє, не виправляє.

package/rules/js/js/oxlintrc.mdc

@@ -0,0 +1,20 @@
+## `.oxlintrc.json` — канонічна конфігурація oxlint
+
+У корені має бути `.oxlintrc.json`, який **збігається з каноном** oxlint з пакета `@nitra/cursor`: файл `npm/rules/js/js/data/tooling/oxlint-canonical.json` (plugins, jsPlugins з `@e18e/eslint-plugin`, categories, повний набір `rules` із канону — додаткові записи в `rules` дозволені; також `settings`, `env`, `globals`).
+
+Поле `ignorePatterns` працює як `rules`: канонічні патерни (наразі `**/schema.graphql`, `**/auto-imports.d.ts`) мають бути присутні; додаткові локальні glob-и дозволені.
+
+Мінімум для розуміння структури (реальний корінь конфігу має збігатися з каноном повністю):
+
+```json title=".oxlintrc.json (фрагмент)"
+{
+  "jsPlugins": ["@e18e/eslint-plugin"],
+  "rules": {
+    "e18e/prefer-includes": "error"
+  }
+}
+```
+
+Модуль `@e18e/eslint-plugin` не оголошуй окремо в `package.json` — він уже в залежностях `@nitra/eslint-config` (з **3.8.0**), oxlint підвантажує його з `node_modules`.
+
+Канон `oxlint-canonical.json` — source-of-truth, редагується напряму; у споживачі оновлюється копіюванням файлу з репозиторію пакета.

package/rules/js/js/package-json.mdc

@@ -0,0 +1,31 @@
+## `package.json` — модульна система та runtime-вимоги
+
+### `"type": "module"` у кожному `package.json`
+
+У **кожному** `package.json` проєкту (корінь і всі workspace-пакети) має бути `"type": "module"` — весь код у ESM.
+
+### `engines` — мінімальні версії Node і Bun
+
+```json title="package.json"
+{
+  "type": "module",
+  "engines": {
+    "node": ">=24",
+    "bun": ">=1.3"
+  },
+  "devDependencies": {
+    "@nitra/eslint-config": "^3.10.0"
+  }
+}
+```
+
+Канон `type`, мінімальна `@nitra/eslint-config` (semver-поріг `devDependencies`) і `engines`: [package.json.snippet.json](./policy/package_json/template/package.json.snippet.json).
+
+### `@nitra/eslint-config` у `devDependencies`
+
+У `devDependencies` кореневого `package.json` має бути `@nitra/eslint-config` — версія не нижче канонічного мінімуму зі snippet (semver-поріг, єдине джерело істини):
+- з **3.8.0** — правило `no-restricted-syntax` забороняє `for...in`;
+- з **3.9.2** — у `getConfig` вбудовано ignore для `**/adr/**`;
+- транзитивно йде `@e18e/eslint-plugin` для oxlint.
+
+Окремого `lint-js` скрипта немає — лінт через `n-cursor lint js` (CI — `--read-only`).

package/rules/js/js/tests.mdc

@@ -0,0 +1,9 @@
+## Тести та покриття
+
+### Unit-тести (Bun test)
+
+Проєкт має бути покритий unit-тестами (**Bun test**). Код: синтаксис Node **24+**, **top level await** (узгоджено з `engines.node` у `package.json`).
+
+### Покриття + мутаційне тестування JS
+
+Покриття + мутаційне тестування JS постачаються через `n-cursor coverage` (правило `test.mdc`). Реалізація провайдера — у `npm/rules/js/coverage/coverage.mjs`: `bun test --coverage --coverage-reporter=lcov` + `bunx stryker run`. Stryker конфігурується в `stryker.config.mjs` у JS-корені (single-package або `workspaces[0]`).

package/rules/js/js/utils-lib-structure.mdc

@@ -0,0 +1,15 @@
+## Структура спільних модулів: `utils/` vs `lib/`
+
+Коли спільні методи виносяться з кількох JS-файлів в окремий каталог — назву каталога обирай за призначенням модулів усередині.
+
+- **`utils/`** — низькорівневі, чисті, generic helpers без бізнес-логіки і без залежностей від домену проєкту. Те, що могло б жити в окремому npm-пакеті. Приклади: `formatDate()`, `chunk(array, size)`, `retry(fn, opts)`, `deepMerge()`, `parseDuration('5m')`, `sleep(ms)`.
+
+- **`lib/`** — внутрішні модулі / підсистеми проєкту, які знають про домен. Більші за `utils/`, часто з власним state, конфігом або side effects. Приклади: `lib/gmail-client.js`, `lib/circuit-breaker.js`, `lib/skill-loader.js`, `lib/safety/dry-run.js`.
+
+Швидкий тест: якщо файл завтра можна опублікувати окремим npm-пакетом без переписування — це `utils/`; якщо він тримає domain-state, читає конфіг проєкту або викликає зовнішні сервіси/файли — це `lib/`. Не плутай із чужими каталогами на кшталт `shared/` чи `common/`: канонічні назви — лише `utils/` і `lib/`.
+
+### Автоматична перевірка імпортів у `utils/`
+
+`npx @nitra/cursor fix js` (концерн `utils_imports`) обходить кожен `utils/`-каталог у воркспейсах і падає, якщо знаходить relative-імпорт з `..` (вихід за межі каталогу) у будь-якому не-тестовому файлі. Це механічне втілення правила «utils не знає про домен»: тільки same-dir (`./X`), bare-пакети та `node:*` дозволені; cross-rule, конфіги проєкту чи sibling-utils — fail.
+
+Якщо потрібна domain-залежність — перенеси файл у `lib/`.