@nitra/cursor 1.8.168 → 1.8.170

package/CHANGELOG.md

@@ -4,6 +4,21 @@
 
 Формат — [Keep a Changelog](https://keepachangelog.com/uk/1.1.0/), нумерація — [SemVer](https://semver.org/lang/uk/).
 
+## [1.8.170] - 2026-05-03
+
+### Changed
+
+- `image.mdc` (v1.4) / `check-image.mjs`: правило перейшло на split-cache `@nitra/minify-image` ≥ **3.2.0**. Замість єдиного `.minify-image-cache.tsv` (який раніше мав бути або в `.gitignore`, або у `files`) тепер: (а) `.n-minify-image.tsv` у корені — committed source of truth з SHA-1/originalSize/size; правило вимагає, щоб він НЕ був у `.gitignore`; (б) `node_modules/.cache/@nitra/minify-image/mtime.tsv` — локальний fast-path, авто-gitignored через `node_modules/`, окремої перевірки не потребує. Додано міграційний fail: якщо `.minify-image-cache.tsv` лежить у корені або згадується в `.gitignore` — підказка з командою `git rm --cached` + `rm -f`. README + image.mdc-секція `## Split-cache` пояснюють, чому коміт hash-кешу осмислений (переживає `git clone`/`checkout`, на відміну від mtime).
+
+## [1.8.169] - 2026-05-03
+
+### Added
+
+- `image.mdc` (v1.3) / `check-image.mjs`: нове правило `image` для оптимізації зображень через [`@nitra/minify-image`](https://www.npmjs.com/package/@nitra/minify-image). Перевіряє лише локальну конфігурацію (CI-workflow не вимагається — sharp/svgo тягнуть бінарні залежності, цінність на ubuntu-runner-ах нижча за час прогону): скрипт `lint-image` у `package.json` з обовʼязковим викликом `npx @nitra/minify-image --src=. --write --avif` (авто-оптимізація на місці + AVIF-двійники для PNG/JPEG/GIF), `bun run lint-image` в агрегованому `lint`, заборона `@nitra/minify-image` у `dependencies`/`devDependencies` (CLI лише через `npx`, симетрично до `markdownlint-cli2` у `text.mdc`) і рядок `.minify-image-cache.tsv` у `.gitignore` (або, рідше, у `files` пакета). AVIF-двійники (`<name>.<ext>.avif`) зберігаються в git як готові артефакти для віддачі браузеру.
+- `image.mdc` (v1.3) / `check-image.mjs`: у `.vue` файлах кожного workspace-пакета raster-посилання мають вести на AVIF-двійник (`...png.avif`) у двох формах: (а) `import x from '...png|jpg|jpeg|gif'` (далі `:src="x"`); (б) прямі статичні атрибути `<img src="...png" />` у `<template>` (Vite перетворює їх на asset-імпорти при збірці). Реактивне `:src="..."` не сканується (JS-вираз — резолвиться через імпорт, який ловиться у формі (а)); `data-src=`, `obj.src=` у `<script>`, SVG-імпорти теж пропускаємо. Опт-аут на рівні воркспейс-пакета: `"@nitra/minify-image": { "disable-avif": true }` у `package.json` цього пакета. Дедуплікація обходу: при walk-у кореня `.` піддерева інших workspace-роди пропускаються (інакше `App.vue` у `demo/` доповідався б двічі).
+- `auto-rules.mjs` / `auto-rules.md`: введено граф залежностей між правилами (`AUTO_RULE_DEPENDENCIES`, синтаксис у `auto-rules.md` — `rule - [other]`). Правило `image` описане як `image - [vue]` — варто автододати лише разом з `vue`, без дублювання вихідної умови «`.vue`-файли». Транзитивне розгортання дозволяє ланцюги (`a → b → c`) і поважає `disable-rules` (якщо vue вимкнено — image теж не додається).
+- `vue.mdc` (v1.4) / `check-vue.mjs`: посилено перевірку `vite.config` — окрім згадки `AutoImport` тепер вимагається, щоб у виклику `AutoImport({ imports: [...] })` був присутній рядковий елемент `'vue'`. Без цього `unplugin-auto-import` не надасть `ref` / `createApp` / тощо, і прибирати явні value-імпорти з `'vue'` стає небезпечно (зламає код). Якщо `'vue'` у `imports` відсутній — value-імпорти більше не оголошуються забороненими, а fail зʼявляється на конфізі vite. Балансована екстракція аргументів `AutoImport(...)` через `extractAutoImportCallArgs` працює для багаторядкових об'єктів.
+
 ## [1.8.168] - 2026-05-03
 
 ### Added

package/bin/auto-rules.md

@@ -4,6 +4,8 @@
 
 ## Правила, які автоматично додається до .n-cursor.json
 
+Синтаксис `rule - [other]` означає: правило `rule` варто автододати лише якщо всі правила у списку `[other]` вже додані до конфігу (граф залежностей між правилами; умова не дублюється).
+
 abie - якщо в кореневому package.json в секції "repository" присутній текст "<https://github.com/abinbevefes/**/>"
 
 bun - якщо в корені проекту є package.json
@@ -18,6 +20,8 @@ graphql - якщо хоч в одному js або vue файлі присут
 
 hasura - якщо в директорії присутній config.yaml, який містить рядок `metadata_directory: metadata`
 
+image - [vue]
+
 js-lint - якщо присутній хоч один js файл
 
 js-run - якщо це вкладена директорія з package.json (не в корені) та в devDependencies немає vite

package/mdc/image.mdc

@@ -0,0 +1,99 @@
+---
+description: Оптимізація зображень через @nitra/minify-image у локальному lint
+alwaysApply: true
+version: '1.4'
+---
+
+CLI [`@nitra/minify-image`](https://www.npmjs.com/package/@nitra/minify-image) (≥ **3.2.0**) запускається через `npx` (як `markdownlint-cli2` у text.mdc) і **не** додається в `dependencies` / `devDependencies`. Канонічний `lint-image` — авто-оптимізація з прапорцями `--write --avif`: стискає raster/SVG на місці й створює AVIF-двійники (`<name>.<ext>.avif`) поряд з кожним PNG/JPEG/GIF. Split-cache робить повторні прогони дешевими — і локально, і після `git clone`.
+
+Перевірка лише локальна — у CI `lint-image` не запускаємо (sharp/svgo тягнуть бінарні залежності, цінність на ubuntu-runner-ах нижча за час прогону). Окремий workflow `lint-image.yml` створювати не треба.
+
+## `package.json`
+
+```json title="package.json"
+{
+  "scripts": {
+    "lint": "bun run lint-js && bun run lint-text && bun run lint-ga && bun run lint-image && oxfmt .",
+    "lint-image": "npx @nitra/minify-image --src=. --write --avif"
+  }
+}
+```
+
+Якщо в `package.json` уже є агрегований `lint`, додай у його ланцюжок `bun run lint-image` (як `bun run lint-text`, `bun run lint-js`, `bun run lint-ga`). Так розробник, що локально гонить `bun run lint`, перед фіксацією одразу бачить, чи зросли зображення, і отримує свіжі AVIF-двійники.
+
+## Split-cache
+
+Починаючи з `@nitra/minify-image` **3.2.0** кеш розбитий на два файли з різною семантикою:
+
+### `.n-minify-image.tsv` — source of truth у git
+
+У корені сканованого каталогу. Формат: `<rel-path>\t<sha1-hex>\t<originalSize>\t<size>`.
+
+Slow-path і джерело даних для `Project lifetime savings`. **Має бути в git** — після `git clone` чи `git checkout` (mtime скидається на час checkout-у) CLI читає файл, рахує SHA-1 і порівнює зі збереженим у TSV хешем; на match локальний mtime-кеш зігрівається без reprocess. Рядки відсортовані алфавітно, hash і size змінюються лише при реальній зміні контенту — diff чистий.
+
+### `node_modules/.cache/@nitra/minify-image/mtime.tsv` — локальний fast-path
+
+Формат: `<rel-path>\t<mtime>\t<size>`. При збігу `(size, mtime)` CLI пропускає файл без читання — константа per-file.
+
+Лежить під `node_modules/`, тож **авто-gitignored** за конвенцією JS-tooling-у (так кешуються ESLint, Babel, webpack, Turbo). Окремий рядок у `.gitignore` не потрібен. `rm -rf node_modules` зносить — наступний запуск відновлює його через slow-path проти `.n-minify-image.tsv`, без reprocess.
+
+### Міграція з versions < 3.2
+
+Старий єдиний `.minify-image-cache.tsv` (4 колонки `path\tmtime\toriginalSize\tsize`, зазвичай у `.gitignore`) автоматично читається при першому запуску для seed-у `originalSize` у `.n-minify-image.tsv` (lifetime savings не скидається). Після цього старий файл видаляють вручну:
+
+```bash
+git rm --cached .minify-image-cache.tsv 2>/dev/null || true
+rm -f .minify-image-cache.tsv
+# прибери відповідний рядок з .gitignore, якщо був
+```
+
+AVIF-двійники (`<name>.<ext>.avif`) **зберігаємо в git** — це готові артефакти для віддачі браузеру (без них ефект від `--avif` втрачається на чистому checkout-і).
+
+## AVIF-імпорти у `.vue`
+
+Раз `--avif` гарантує `<name>.<ext>.avif` поряд з кожним PNG/JPEG/GIF, у `.vue` файлах потрібно посилатись саме на AVIF-двійник, а не на оригінал:
+
+```vue title="App.vue (правильно)"
+<script setup>
+import welcomeImage from './assets/welcome.png.avif'
+</script>
+
+<template>
+  <img :src="welcomeImage" alt="Welcome" />
+</template>
+```
+
+```vue title="App.vue (неправильно — втрачає AVIF)"
+<script setup>
+import welcomeImage from './assets/welcome.png'
+</script>
+```
+
+Перевірка `check image` сканує `.vue` файли в кожному workspace-пакеті (root + workspaces) і вимагає AVIF-двійник для двох форм:
+
+1. **Імпорт-пов'язані** — `import x from '...png|jpg|jpeg|gif'` (далі `:src="x"` у шаблоні).
+2. **Прямі статичні** — `<img src="...png" />` у `<template>` (Vite перетворює такий шлях на asset-імпорт на етапі збірки, тож вимога та сама).
+
+Реактивне `:src="..."` (з JS-виразом — змінною, тернарником, викликом тощо) **не сканується** — значення обчислюється у рантаймі й шлях туди потрапляє через імпорт або інший резолвинг, який ловить імпорт-перевірка вище. SVG не торкаємо (vector → AVIF безглуздо). Атрибути `data-src=`, `obj.src=` у `<script>` тощо також пропускаються.
+
+### Опт-аут для конкретного пакета
+
+У workspace-пакеті, де AVIF-імпорти небажані (наприклад, мобільний бандл, де AVIF-підтримка не гарантована), додай у `package.json` цього пакета:
+
+```json title="apps/mobile/package.json"
+{
+  "@nitra/minify-image": {
+    "disable-avif": true
+  }
+}
+```
+
+Тоді перевірка пропускає `.vue` файли цього пакета. У root-`package.json` опт-аут діє лише для файлів кореня (вкладені workspaces перевіряються незалежно — вмикай прапор у кожному пакеті, де треба).
+
+## Заборонені залежності
+
+`@nitra/minify-image` не повинен зʼявлятися ні в `dependencies`, ні в `devDependencies` кореневого `package.json` — CLI запускається лише через `npx` (так само, як `markdownlint-cli2` у text.mdc). Якщо потрібен явний пін — закладай діапазон версій npm у самому виклику (`npx @nitra/minify-image@^3 --src=. --write --avif`).
+
+## Перевірка
+
+`npx @nitra/cursor check image` (охоплює `lint-image` з обовʼязковими `--src=.`, `--write`, `--avif`, агрегований `lint`, `.n-minify-image.tsv` НЕ в `.gitignore` (має бути в git), відсутність застарілого `.minify-image-cache.tsv` у корені, AVIF-імпорти у `.vue` файлах кожного workspace-пакета).

package/mdc/vue.mdc

@@ -1,7 +1,7 @@
 ---
 description: Vue
 alwaysApply: true
-version: '1.3'
+version: '1.4'
 ---
 
 # Vue 3 Composition API — правила для .cursorrules

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nitra/cursor",
-  "version": "1.8.168",
+  "version": "1.8.170",
   "description": "CLI для завантаження cursor-правил (префікс n-) у локальний репозиторій",
   "keywords": [
     "cli",
@@ -49,6 +49,6 @@
     "node": ">=25"
   },
   "devDependencies": {
-    "@nitra/cursor": "^1.8.168"
+    "@nitra/cursor": "^1.8.170"
   }
 }

package/scripts/auto-rules.mjs

@@ -30,6 +30,7 @@ export const AUTO_RULE_ORDER = Object.freeze([
   'ga',
   'graphql',
   'hasura',
+  'image',
   'js-lint',
   'js-mssql',
   'js-bun-db',
@@ -46,6 +47,17 @@ export const AUTO_RULE_ORDER = Object.freeze([
 /** Порядок автододавання skills відповідно до `auto-rules.md`. */
 export const AUTO_SKILL_ORDER = Object.freeze(['abie-kustomize', 'fix', 'lint'])
 
+/**
+ * Граф залежностей між правилами (`auto-rules.md` синтаксис `rule - [other]`).
+ * Ключ варто автододати, коли всі правила-залежності вже додані до конфігу — щоб
+ * не дублювати вихідну умову, достатньо описати її у залежності.
+ */
+export const AUTO_RULE_DEPENDENCIES = Object.freeze(
+  /** @type {Record<string, readonly string[]>} */ ({
+    image: Object.freeze(['vue'])
+  })
+)
+
 const ABIE_REPOSITORY_URL_MARKER = 'https://github.com/abinbevefes/'
 const HASURA_CONFIG_MARKER = 'metadata_directory: metadata'
 const JS_LIKE_RE = /\.(?:mjs|cjs|js|jsx|ts|tsx)$/iu
@@ -493,6 +505,30 @@ export async function collectAutoRuleFacts(root) {
   return facts
 }
 
+/**
+ * Транзитивно розгортає правила за `AUTO_RULE_DEPENDENCIES`: повторно проходить
+ * усіма парами «правило → залежності» доки на одному з проходів не зʼявляється
+ * нове додавання. Це дозволяє ланцюги (`a → b → c`) і не вимагає від автора правил
+ * стежити за порядком викликів `addRule`.
+ * @param {string[]} detectedRules уже зібрані id правил (мутується через addRule)
+ * @param {(ruleId: string) => void} addRule callback із спільної фабрики (поважає `disable-rules` і дублі)
+ * @returns {void}
+ */
+function resolveRuleDependencies(detectedRules, addRule) {
+  let changed = true
+  while (changed) {
+    changed = false
+    for (const [ruleId, deps] of Object.entries(AUTO_RULE_DEPENDENCIES)) {
+      if (detectedRules.includes(ruleId)) continue
+      if (deps.every(d => detectedRules.includes(d))) {
+        const before = detectedRules.length
+        addRule(ruleId)
+        if (detectedRules.length > before) changed = true
+      }
+    }
+  }
+}
+
 /**
  * Визначає авто-правила та skills згідно з `auto-rules.md`.
  * @param {object} params параметри аналізу
@@ -588,6 +624,7 @@ export async function detectAutoRulesAndSkills({
   if (facts.hasVueSource) {
     addRule('vue')
   }
+  resolveRuleDependencies(detectedRules, addRule)
 
   const autoSkillChecks = [
     { enabled: isAbie, id: 'abie-kustomize' },

package/scripts/check-image.mjs

@@ -0,0 +1,320 @@
+/**
+ * Перевіряє відповідність репозиторію правилу image.mdc для оптимізації зображень
+ * через `@nitra/minify-image` ≥ 3.2.0 (локально — у CI лінт зображень не запускається).
+ *
+ * Очікування:
+ * - у кореневому `package.json` є скрипт `lint-image`, який викликає `npx @nitra/minify-image`
+ *   з обовʼязковими `--src=.`, `--write` і `--avif` (авто-оптимізація з AVIF-двійниками);
+ * - якщо в `package.json` є агрегований скрипт `lint`, він викликає `bun run lint-image`
+ *   (симетрично до `lint-text`, `lint-js`, `lint-ga`);
+ * - `@nitra/minify-image` не оголошений у `dependencies`/`devDependencies` —
+ *   CLI запускається лише через `npx` (як `markdownlint-cli2` у `text.mdc`);
+ * - `.n-minify-image.tsv` (committed source of truth з sha1/originalSize/size) НЕ
+ *   в `.gitignore` — він має бути в git. Локальний mtime-кеш у
+ *   `node_modules/.cache/@nitra/minify-image/mtime.tsv` авто-gitignored через `node_modules/`,
+ *   окремої перевірки не вимагає;
+ * - застарілий `.minify-image-cache.tsv` (з версій < 3.2) видалений з кореня — інакше
+ *   проєкт лишається у напівпереміщеному стані;
+ * - у `.vue` файлах raster-імпорти (`.png` / `.jpg` / `.jpeg` / `.gif`) посилаються на
+ *   AVIF-двійники (`...png.avif` тощо), оскільки `--avif` гарантує їх наявність поряд із
+ *   оригіналами. Можна вимкнути на рівні воркспейс-пакета через `"@nitra/minify-image": {
+ *   "disable-avif": true }` у його `package.json`.
+ */
+import { existsSync } from 'node:fs'
+import { readFile } from 'node:fs/promises'
+import { join, relative } from 'node:path'
+
+import { createCheckReporter } from './utils/check-reporter.mjs'
+import { walkDir } from './utils/walkDir.mjs'
+import { getMonorepoPackageRootDirs } from './utils/workspaces.mjs'
+
+/** Імʼя CLI-пакета: рядок у `lint-image` і заборонений у залежностях. */
+const MINIFY_PACKAGE_NAME = '@nitra/minify-image'
+
+/** Імʼя committed-кешу (sha1 + originalSize + size) у `@nitra/minify-image` ≥ 3.2.0. */
+const HASH_CACHE_FILENAME = '.n-minify-image.tsv'
+
+/** Імʼя застарілого 4-колонкового кешу (`@nitra/minify-image` < 3.2). Має бути видалений після міграції. */
+const LEGACY_CACHE_FILENAME = '.minify-image-cache.tsv'
+
+/** Поле в `package.json` для конфігу @nitra/minify-image (наприклад, `disable-avif`). */
+const PKG_CONFIG_FIELD = '@nitra/minify-image'
+
+/**
+ * Регексп для імпортів raster-зображень у `.vue` файлах.
+ * Захоплює `import name from '...ext'` (як default, так і type-only форми не потрібні —
+ * type-imports asset-ів не існує). Захоплюється повний шлях у групі 1.
+ */
+const VUE_RASTER_IMPORT_RE = /import\s+\w[\w$]*\s+from\s+['"]([^'"\n]+\.(?:png|jpe?g|gif))['"]/giu
+
+/**
+ * Регексп для прямих посилань на raster-зображення у HTML-атрибуті `src="..."` шаблона `.vue`
+ * (наприклад `<img src="./hero.png" />`). Vite перетворює такі шляхи на asset-імпорти на етапі
+ * збірки, тож для них теж діє вимога вживати AVIF-двійник.
+ *
+ * Лукбехайнд `(?<![:\-_.])` виключає реактивне `:src="..."` (там JS-вираз — змінна або виклик,
+ * перевіряється через імпорт), `data-src="..."` і `obj.src=...` у `<script>`.
+ */
+const VUE_RASTER_STATIC_SRC_RE = /(?<![:\-_.])\bsrc\s*=\s*['"]([^'"\s]+\.(?:png|jpe?g|gif))['"]/giu
+
+/**
+ * Перевіряє скрипт `lint-image` у `package.json`.
+ *
+ * Має містити виклик `npx @nitra/minify-image` з обовʼязковими прапорцями `--src=.`,
+ * `--write` (авто-оптимізація на місці) і `--avif` (AVIF-двійники для PNG/JPEG/GIF).
+ * Без `--write`/`--avif` лінт лише оцінює економію — для проєктних коммітів цього мало.
+ * @param {string|undefined} lintImage значення `scripts['lint-image']`
+ * @param {(msg: string) => void} pass callback при успішній перевірці
+ * @param {(msg: string) => void} fail callback при помилці
+ * @returns {void}
+ */
+function checkLintImageScript(lintImage, pass, fail) {
+  const canonical = `npx ${MINIFY_PACKAGE_NAME} --src=. --write --avif`
+  if (typeof lintImage !== 'string' || !lintImage.trim()) {
+    fail(`package.json: додай скрипт "lint-image" з \`${canonical}\` (image.mdc)`)
+    return
+  }
+  if (!lintImage.includes(`npx ${MINIFY_PACKAGE_NAME}`)) {
+    fail(`package.json: lint-image має викликати \`npx ${MINIFY_PACKAGE_NAME}\` (image.mdc)`)
+    return
+  }
+  /** @type {{ flag: string, variants: string[], hint: string }[]} */
+  const requiredFlags = [
+    { flag: '--src=.', variants: ['--src=.', '--src .'], hint: '`--src=.`' },
+    { flag: '--write', variants: ['--write'], hint: '`--write` (авто-оптимізація на місці)' },
+    { flag: '--avif', variants: ['--avif'], hint: '`--avif` (AVIF-двійники для PNG/JPEG/GIF)' }
+  ]
+  const missing = requiredFlags.filter(f => !f.variants.some(v => lintImage.includes(v)))
+  if (missing.length > 0) {
+    fail(
+      `package.json: lint-image має містити ${missing.map(f => f.hint).join(', ')} — канонічний виклик: \`${canonical}\` (image.mdc)`
+    )
+    return
+  }
+  pass(`package.json: lint-image викликає \`${canonical}\``)
+}
+
+/**
+ * Перевіряє, що агрегований `lint` (якщо є) кличе `bun run lint-image` —
+ * симетрично до `lint-text`, `lint-js`, `lint-ga`.
+ * @param {string|undefined} lintAggregate значення `scripts.lint`
+ * @param {(msg: string) => void} pass callback при успішній перевірці
+ * @param {(msg: string) => void} fail callback при помилці
+ * @returns {void}
+ */
+function checkLintAggregateIncludesImage(lintAggregate, pass, fail) {
+  if (typeof lintAggregate !== 'string' || !lintAggregate.trim()) {
+    return
+  }
+  if (lintAggregate.includes('bun run lint-image')) {
+    pass('package.json: агрегований `lint` викликає `bun run lint-image`')
+  } else {
+    fail('package.json: у `lint` додай `bun run lint-image` (image.mdc, симетрично до lint-text / lint-js / lint-ga)')
+  }
+}
+
+/**
+ * Забороняє `@nitra/minify-image` у `dependencies` чи `devDependencies` —
+ * CLI завжди запускається через `npx` (як `markdownlint-cli2` у `text.mdc`).
+ * @param {{ dependencies?: Record<string, unknown>, devDependencies?: Record<string, unknown> }} pkg розібраний package.json
+ * @param {(msg: string) => void} pass callback при успішній перевірці
+ * @param {(msg: string) => void} fail callback при помилці
+ * @returns {void}
+ */
+function checkMinifyImageNotInDeps(pkg, pass, fail) {
+  const inDeps = Boolean(pkg.dependencies && MINIFY_PACKAGE_NAME in pkg.dependencies)
+  const inDevDeps = Boolean(pkg.devDependencies && MINIFY_PACKAGE_NAME in pkg.devDependencies)
+  if (inDeps || inDevDeps) {
+    fail(
+      `package.json: ${MINIFY_PACKAGE_NAME} не додавай у dependencies/devDependencies — лише через \`npx\` (image.mdc)`
+    )
+  } else {
+    pass(`package.json: ${MINIFY_PACKAGE_NAME} не оголошено в dependencies/devDependencies`)
+  }
+}
+
+/**
+ * Зчитує всі змістовні рядки `.gitignore` (без коментарів і порожніх). Якщо файла нема — `null`.
+ * @returns {Promise<string[] | null>} список trim-нутих рядків або `null`
+ */
+async function readGitignoreLines() {
+  if (!existsSync('.gitignore')) return null
+  const raw = await readFile('.gitignore', 'utf8')
+  return raw
+    .split('\n')
+    .map(l => l.trim())
+    .filter(l => l.length > 0 && !l.startsWith('#'))
+}
+
+/**
+ * Перевіряє, що `.n-minify-image.tsv` НЕ в `.gitignore` — він має бути в git
+ * (split-cache 3.2.0: source of truth для slow-path і lifetime savings).
+ *
+ * Сам факт існування файла НЕ вимагається — на свіжому проєкті без обробки
+ * зображень його ще нема, це нормально.
+ * @param {(msg: string) => void} pass callback при успішній перевірці
+ * @param {(msg: string) => void} fail callback при помилці
+ * @returns {Promise<void>}
+ */
+async function checkHashCacheNotIgnored(pass, fail) {
+  const lines = await readGitignoreLines()
+  if (lines && lines.includes(HASH_CACHE_FILENAME)) {
+    fail(
+      `.gitignore: прибери рядок \`${HASH_CACHE_FILENAME}\` — це закомічений source of truth split-cache 3.2.0 (image.mdc)`
+    )
+  } else {
+    pass(`${HASH_CACHE_FILENAME} не в .gitignore (має бути в git)`)
+  }
+}
+
+/**
+ * Перевіряє, що застарілий `.minify-image-cache.tsv` (з версій < 3.2) видалений
+ * з кореня. Якщо лежить — користувач не завершив міграцію на split-cache, що
+ * залишає файл як орфана у git-історії.
+ * @param {(msg: string) => void} pass callback при успішній перевірці
+ * @param {(msg: string) => void} fail callback при помилці
+ * @returns {Promise<void>}
+ */
+async function checkLegacyCacheRemoved(pass, fail) {
+  if (existsSync(LEGACY_CACHE_FILENAME)) {
+    fail(
+      `${LEGACY_CACHE_FILENAME} застарілий (split-cache 3.2.0) — видали: ` +
+        `\`git rm --cached ${LEGACY_CACHE_FILENAME} 2>/dev/null || true && rm -f ${LEGACY_CACHE_FILENAME}\` ` +
+        '(також прибери відповідний рядок з .gitignore, якщо є)'
+    )
+    return
+  }
+  const lines = await readGitignoreLines()
+  if (lines && lines.includes(LEGACY_CACHE_FILENAME)) {
+    fail(
+      `.gitignore: прибери застарілий рядок \`${LEGACY_CACHE_FILENAME}\` — split-cache 3.2.0 його не використовує`
+    )
+    return
+  }
+  pass(`${LEGACY_CACHE_FILENAME} відсутній (міграція на split-cache завершена)`)
+}
+
+/**
+ * Чи у `package.json` пакета вимкнено avif-перевірку Vue-імпортів.
+ * Очікувана форма: `"@nitra/minify-image": { "disable-avif": true }`.
+ * @param {Record<string, unknown>} pkg розібраний package.json пакета
+ * @returns {boolean} true, якщо опт-аут активовано
+ */
+function packageHasAvifDisabled(pkg) {
+  const cfg = pkg[PKG_CONFIG_FIELD]
+  return Boolean(cfg && typeof cfg === 'object' && /** @type {Record<string, unknown>} */ (cfg)['disable-avif'] === true)
+}
+
+/**
+ * Сканує `.vue` файли одного workspace-пакета на raster-імпорти, що ще не використовують `.avif`.
+ *
+ * Файли, що належать іншим workspace-пакетам, ігноруються — кожен пакет перевіряється рівно
+ * один раз (інакше при обході кореня `.` ми б повторно зайшли в `demo/` і подвоїли звіти).
+ * @param {string} packageRoot відносний шлях до кореня пакета (наприклад `'.'` або `'demo'`)
+ * @param {string[]} otherRootsAbs абсолютні шляхи інших workspace-коренів — їх піддерева пропускаємо
+ * @param {(msg: string) => void} pass callback при успішній перевірці
+ * @param {(msg: string) => void} fail callback при помилці
+ * @returns {Promise<void>}
+ */
+async function checkVueAvifImportsInPackage(packageRoot, otherRootsAbs, pass, fail) {
+  const absRoot = join(process.cwd(), packageRoot)
+  const label = packageRoot === '.' ? 'корінь' : packageRoot
+  /** @type {string[]} */
+  const vueFiles = []
+  await walkDir(absRoot, absPath => {
+    if (!absPath.endsWith('.vue')) return
+    if (otherRootsAbs.some(other => absPath.startsWith(`${other}/`))) return
+    vueFiles.push(absPath)
+  })
+  if (vueFiles.length === 0) return
+
+  let violations = 0
+  for (const absPath of vueFiles) {
+    const rel = relative(process.cwd(), absPath).split('\\').join('/')
+    const content = await readFile(absPath, 'utf8')
+    for (const match of content.matchAll(VUE_RASTER_IMPORT_RE)) {
+      violations++
+      const importPath = match[1]
+      fail(
+        `[${label}] ${rel}: import з '${importPath}' має посилатись на AVIF-двійник '${importPath}.avif' ` +
+          `(lint-image --avif створює його поряд). Вимкнути локально: "@nitra/minify-image": { "disable-avif": true } у package.json пакета`
+      )
+    }
+    for (const match of content.matchAll(VUE_RASTER_STATIC_SRC_RE)) {
+      violations++
+      const srcPath = match[1]
+      fail(
+        `[${label}] ${rel}: пряме \`src="${srcPath}"\` у шаблоні має використовувати AVIF-двійник \`src="${srcPath}.avif"\` ` +
+          `(або винеси у import + \`:src="..."\`). Вимкнути локально: "@nitra/minify-image": { "disable-avif": true } у package.json пакета`
+      )
+    }
+  }
+  if (violations === 0) {
+    pass(`[${label}] усі raster-посилання у .vue вже на .avif (або відсутні)`)
+  }
+}
+
+/**
+ * Сканує всі workspace-пакети: для кожного перевіряє opt-out і за потреби викликає
+ * перевірку Vue-imports. Перевірка пропускається, якщо в репозиторії немає workspaces
+ * або немає `.vue`-файлів — тоді `image` правило не для цього проєкту.
+ * @param {(msg: string) => void} pass callback при успішній перевірці
+ * @param {(msg: string) => void} fail callback при помилці
+ * @returns {Promise<void>}
+ */
+async function checkVueAvifImports(pass, fail) {
+  const roots = await getMonorepoPackageRootDirs()
+  const absRootsByRel = new Map(roots.map(r => [r, join(process.cwd(), r)]))
+  for (const root of roots) {
+    const pkgPath = join(root, 'package.json')
+    if (!existsSync(pkgPath)) continue
+    const pkg = JSON.parse(await readFile(pkgPath, 'utf8'))
+    if (packageHasAvifDisabled(pkg)) {
+      pass(`[${root === '.' ? 'корінь' : root}] avif-import enforcement вимкнено через "@nitra/minify-image.disable-avif"`)
+      continue
+    }
+    const otherRootsAbs = roots.filter(r => r !== root && r !== '.').map(r => absRootsByRel.get(r) ?? '')
+    await checkVueAvifImportsInPackage(root, otherRootsAbs, pass, fail)
+  }
+}
+
+/**
+ * Перевіряє кореневий `package.json`: скрипти, заборонені залежності, агрегований `lint`.
+ * @param {(msg: string) => void} pass callback при успішній перевірці
+ * @param {(msg: string) => void} fail callback при помилці
+ * @returns {Promise<boolean>} `true`, якщо `package.json` знайдено й оброблено; `false` — нема
+ */
+async function checkPackageJsonImage(pass, fail) {
+  if (!existsSync('package.json')) {
+    fail('package.json не знайдено в корені — додай (image.mdc)')
+    return false
+  }
+  const pkg = JSON.parse(await readFile('package.json', 'utf8'))
+  const scripts = /** @type {Record<string, unknown>} */ (pkg.scripts || {})
+  checkLintImageScript(typeof scripts['lint-image'] === 'string' ? scripts['lint-image'] : undefined, pass, fail)
+  checkLintAggregateIncludesImage(typeof scripts.lint === 'string' ? scripts.lint : undefined, pass, fail)
+  checkMinifyImageNotInDeps(pkg, pass, fail)
+  return true
+}
+
+/**
+ * Перевіряє відповідність проєкту правилам `image.mdc` (split-cache 3.2.0):
+ * `lint-image` через `npx @nitra/minify-image --src=. --write --avif`, агрегований `lint`,
+ * `.n-minify-image.tsv` НЕ в `.gitignore` (committed source of truth), застарілий
+ * `.minify-image-cache.tsv` видалений, AVIF-імпорти у `.vue` файлах. CI-workflow
+ * для image не вимагається — лінт зображень виконується лише локально.
+ * @returns {Promise<number>} 0 — все OK, 1 — є проблеми
+ */
+export async function check() {
+  const reporter = createCheckReporter()
+  const { pass, fail } = reporter
+
+  const pkgFound = await checkPackageJsonImage(pass, fail)
+  if (pkgFound) {
+    await checkHashCacheNotIgnored(pass, fail)
+    await checkLegacyCacheRemoved(pass, fail)
+  }
+  await checkVueAvifImports(pass, fail)
+
+  return reporter.getExitCode()
+}

package/scripts/check-vue.mjs

@@ -205,19 +205,57 @@ function checkViteVersion(devDeps, prefix, passFn, fail) {
   }
 }
 
+/**
+ * Витягує текст аргументів першого виклику `AutoImport(` з vite.config зі збалансованими дужками.
+ * Повертає `null`, якщо виклик не знайдено або дужки не збалансовані (тоді перевірка `'vue'`
+ * у списку `imports` пропускається — інші чек-сигнали все одно спрацюють).
+ * @param {string} content повний текст vite.config
+ * @returns {string | null} текст усередині `AutoImport(...)` без зовнішніх дужок, або `null`
+ */
+function extractAutoImportCallArgs(content) {
+  const marker = 'AutoImport('
+  const idx = content.indexOf(marker)
+  if (idx === -1) return null
+  const start = idx + marker.length
+  let depth = 1
+  for (let i = start; i < content.length; i++) {
+    const ch = content[i]
+    if (ch === '(') depth++
+    else if (ch === ')') {
+      depth--
+      if (depth === 0) return content.slice(start, i)
+    }
+  }
+  return null
+}
+
+/**
+ * Чи передано `'vue'` (або `"vue"`) як рядковий елемент у `imports` всередині виклику `AutoImport(...)`.
+ * Без auto-import-ів `vue` забороняти явні value-імпорти `from 'vue'` небезпечно — їх видалення
+ * зламає код, бо `ref` / `createApp` тощо більше нікому надати.
+ * @param {string} content повний текст vite.config
+ * @returns {boolean} true, якщо `AutoImport({ imports: [..., 'vue', ...] })` сконфігуровано
+ */
+function viteConfigHasVueInAutoImports(content) {
+  const args = extractAutoImportCallArgs(content)
+  if (args === null) return false
+  return args.includes("'vue'") || args.includes('"vue"')
+}
+
 /**
  * Перевіряє vite.config на наявність VueMacros і AutoImport.
  * @param {string} rootDir параметр rootDir
  * @param {string} prefix параметр prefix
  * @param {(msg: string) => void} passFn callback при успішній перевірці
  * @param {(msg: string) => void} fail callback при помилці
+ * @returns {Promise<{ hasVueAutoImport: boolean }>} ознака успішно сконфігурованого vue-auto-import (для checkVueImportViolations)
  */
 async function checkViteConfig(rootDir, prefix, passFn, fail) {
   const configFiles = ['vite.config.js', 'vite.config.ts', 'vite.config.mjs']
   const viteConfig = configFiles.find(f => existsSync(join(rootDir, f)))
   if (!viteConfig) {
     fail(`${prefix}немає vite.config.js|ts|mjs у каталозі пакета`)
-    return
+    return { hasVueAutoImport: false }
   }
   const content = await readFile(join(rootDir, viteConfig), 'utf8')
   if (ESBUILD_RE.test(content)) {
@@ -235,23 +273,48 @@ async function checkViteConfig(rootDir, prefix, passFn, fail) {
     }
   }
 
+  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('process.env.npm_lifecycle_event')) {
     fail(
       `${prefix}${viteConfig} використовує process.env.npm_lifecycle_event — у Bun це не працює. ` +
         `Перенеси логіку на mode (defineConfig(({ mode }) => ...)) і передавай mode в helper-функції.`
     )
   }
+
+  return { hasVueAutoImport }
 }
 
 /**
  * Сканує джерела пакета на заборонені value-імпорти з vue.
+ *
+ * Якщо `unplugin-auto-import` не сконфігурований на `'vue'` у `vite.config`, явні value-імпорти
+ * формально не заборонені — їх видалення зламає код. У цьому випадку перевірка пропускається,
+ * а fail про відсутній `'vue'` у `AutoImport.imports` уже зареєстровано в `checkViteConfig`.
  * @param {string} rootDir параметр rootDir
  * @param {string} absPackageRoot параметр absPackageRoot
  * @param {string} prefix параметр prefix
+ * @param {boolean} hasVueAutoImport чи `AutoImport({ imports: [..., 'vue', ...] })` сконфігуровано
  * @param {(msg: string) => void} passFn callback при успішній перевірці
  * @param {(msg: string) => void} fail callback при помилці
  */
-async function checkVueImportViolations(rootDir, absPackageRoot, prefix, passFn, fail) {
+async function checkVueImportViolations(rootDir, absPackageRoot, hasVueAutoImport, prefix, passFn, fail) {
+  if (!hasVueAutoImport) {
+    passFn(
+      `${prefix}value-імпорти з 'vue' не заборонені — спершу додай 'vue' до AutoImport.imports у vite.config`
+    )
+    return
+  }
   /** @type {string[]} */
   const sourcePaths = []
   await walkDir(absPackageRoot, absPath => {
@@ -323,8 +386,8 @@ async function checkVuePackage(rootDir, fail, passFn) {
     'vite-plugin-vue-layouts-next відсутній — bun add -d vite-plugin-vue-layouts-next'
   )
 
-  await checkViteConfig(rootDir, prefix, passFn, fail)
-  await checkVueImportViolations(rootDir, join(process.cwd(), rootDir), prefix, passFn, fail)
+  const { hasVueAutoImport } = await checkViteConfig(rootDir, prefix, passFn, fail)
+  await checkVueImportViolations(rootDir, join(process.cwd(), rootDir), hasVueAutoImport, prefix, passFn, fail)
   await checkEsbuildMentions(rootDir, join(process.cwd(), rootDir), prefix, passFn, fail)
 }
 

package/scripts/sync-claude-config.mjs

@@ -91,7 +91,7 @@ export function mergeHooks(existing, fromTemplate) {
   /** @type {Record<string, HookGroup[]>} */
   const out = {}
   for (const [event, groups] of Object.entries(existing ?? {})) {
-    out[event] = Array.isArray(groups) ? groups.slice() : []
+    out[event] = Array.isArray(groups) ? [...groups] : []
   }
   for (const [event, templateGroups] of Object.entries(fromTemplate ?? {})) {
     const existingGroups = (out[event] ?? []).filter(g => !isManagedHookGroup(g))
@@ -111,10 +111,10 @@ export function mergeHooks(existing, fromTemplate) {
  */
 export function mergeSettings(existing, template) {
   /** @type {ClaudeSettings} */
-  const merged = { ...(existing ?? {}) }
+  const merged = { ...existing }
   const mergedAllow = mergeAllowList(existing?.permissions?.allow, template.permissions?.allow)
   if (mergedAllow.length > 0) {
-    merged.permissions = { ...(existing?.permissions ?? {}), allow: mergedAllow }
+    merged.permissions = { ...existing?.permissions, allow: mergedAllow }
   }
   const mergedHooks = mergeHooks(existing?.hooks, template.hooks)
   if (Object.keys(mergedHooks).length > 0) {
@@ -132,12 +132,12 @@ export function mergeSettings(existing, template) {
  */
 async function readJsonOrUndefined(path) {
   if (!existsSync(path)) {
-    return undefined
+    return
   }
   try {
     return JSON.parse(await readFile(path, 'utf8'))
   } catch {
-    return undefined
+    return
   }
 }