@nitra/cursor 1.28.4 → 1.28.6

package/CHANGELOG.md

@@ -4,6 +4,13 @@
 
 Формат — [Keep a Changelog](https://keepachangelog.com/uk/1.1.0/), нумерація — [SemVer](https://semver.org/lang/uk/).
 
+## [1.28.5] - 2026-05-28
+
+### Fixed
+
+- **`scripts/utils/resolve-js-root.mjs`** — `resolveAllJsRoots()` тепер розгортає glob-патерни (`cf/*`, `packages/*` тощо) у списку `workspaces` через `node:fs/promises#glob`. Без цього `cf/*` як літерал не резолвився через `existsSync`, і `resolveJsRoot()` падав на fallback → `cwd`; `n-cursor coverage` із кореня запускав vitest у root-у проєкту без `vitest.config.js` (через `gt/tests/setup.mjs` не підвантажувався). `resolveJsRoot()` тепер тонкий wrapper над `resolveAllJsRoots()[0]`. Додано 2 тести: glob-розгортання `cf/*` і fallback на `[cwd]` при порожньому збігу.
+- **`rules/js-lint/coverage/coverage.mjs#collect()`** — у monorepo тепер ітерує **всі** JS-roots з `resolveAllJsRoots()`, запускає vitest + Stryker у кожному окремо та сумує `lcov` (через локальний `addCoverage`) і `mutation` (через `addMutation`). Шляхи у `survived[].file` і `survived[].exampleTest.testFile` рібейзяться відносно `cwd` (`relative(cwd, jsRoot)`/`join(wsRel, file)`), щоб `coverage-fix.mjs#buildFixPrompt` коректно читав source-файли через `join(projectRoot, file)`. `detect()` повертає `true`, якщо vitest є хоча б в одному workspace АБО в кореневому `package.json`. Додано тест агрегування у monorepo з `cf/*`-glob.
+
 ## [1.28.4] - 2026-05-28
 
 ### Changed

package/package.json

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

package/rules/js-bun-db/js-bun-db.mdc

@@ -46,6 +46,60 @@ PostgreSQL 18+, MariaDB 10.6+ (сумісний з MySQL-протоколом,
 
 Для multi-row `VALUES` у `MERGE` / `INSERT` з конкретними типами — паралельні масиви по колонках і `unnest($1::TYPE[], $2::TYPE[], ...) AS t(col1, col2, ...)`. Кожна колонка передається одним параметром-масивом; типи задаються кастом масиву (`::uuid[]`, `::bigint[]`, `::numeric[]`, `::text[]`, …).
 
+#### Приклад: MERGE з UNNEST і динамічними колонками
+
+```javascript
+// ❌ format + pgWrite.unsafe — N×7 окремих значень, план змінюється при кожному batch.length
+const valuesSql = batch
+  .map(row => format('(%L::int, %L::date, %L::jsonb)', row.id, row.date, JSON.stringify(row.data)))
+  .join(',')
+const sql = format(`MERGE INTO t USING (VALUES %s) AS s(id, date, data) ON ...`, valuesSql)
+await pgWrite.unsafe(sql)
+
+// ✅ UNNEST — 3 параметри незалежно від розміру batch; план стабільний і може кешуватись
+const ids   = batch.map(r => r.id)
+const dates = batch.map(r => r.date)
+const data  = batch.map(r => JSON.stringify(r.data))
+
+await pgWrite`
+  WITH s(id, date, data) AS (
+    SELECT * FROM unnest(
+      ${ids}::int[],
+      ${dates}::date[],
+      ${data}::jsonb[]
+    )
+  )
+  MERGE INTO my_table AS t
+  USING s ON t.id = s.id
+  WHEN MATCHED THEN
+    UPDATE SET date = s.date, data = s.data
+  WHEN NOT MATCHED THEN
+    INSERT (id, date, data) VALUES (s.id, s.date, s.data)
+`
+```
+
+Якщо частина колонок у SET/INSERT залежить від параметра (plan/fact, тип тощо) — динамічні імена колонок не можна параметризувати через `${value}`; використовуй умовні Bun SQL фрагменти:
+
+```javascript
+// ✅ умовні фрагменти для динамічних ідентифікаторів колонок
+const colFrag  = isPlan ? pgWrite`plan_value`  : pgWrite`fact_value`
+const hashFrag = isPlan ? pgWrite`hash = s.hash,` : pgWrite``
+
+await pgWrite`
+  ...
+  WHEN MATCHED THEN
+    UPDATE SET
+      ${colFrag} = s.value,
+      ${hashFrag}
+      updated_by = s.updated_by
+  WHEN NOT MATCHED THEN
+    INSERT (id, ${colFrag}, updated_by)
+    VALUES (s.id, s.value, s.updated_by)
+`
+```
+
+`UNION ALL`-цикл замість `unnest` підходить для малих динамічних запитів (2–5 рядків), де кожна гілка семантично різна. Для bulk upsert — завжди `unnest`.
+
 ### Заборонений «drop-in» шим
 
 ```javascript
@@ -285,6 +339,26 @@ const ids = [1, 2, 3]
 await sql`SELECT * FROM users WHERE id IN ${sql(ids)}`
 ```
 
+Multi-row INSERT з масиву об'єктів — `sql(rows)` генерує column list і VALUES автоматично:
+
+```javascript
+// ❌ format + pgWrite.unsafe — ручне склеювання рядків, injection-вектор
+const insertWfQry = `insert into approval.workflow (request_id, job_title_id, name, status)
+  values ${approverJobs.map(job => `('${request.id}', ${job.id}, '${job.short_name}', 'pending')`).join(', ')}`
+await pgWrite.unsafe(insertWfQry)
+
+// ✅ sql(rows) — один параметр-масив, bind через wire-protocol
+const wfRows = approverJobs.map(job => ({
+  request_id: request.id,
+  job_title_id: job.id,
+  name: job.short_name,
+  status: job.id === nextJobId ? 'current' : 'pending'
+}))
+await sql`INSERT INTO approval.workflow ${sql(wfRows)}`
+```
+
+Коли потрібен стабільний план для великих batch'ів (N > 20) або строгі типи колонок — використовуй `unnest` (деталі у `#### Приклад: MERGE з UNNEST і динамічними колонками`). Для невеликих INSERT'ів де колонки відомі — `sql(rows)` коротший і зрозуміліший.
+
 ## `IN (...)`: значення з template literal — тільки через змінну + guard на пустоту
 
 Якщо список для `IN (...)` підставляється через `${...}` у template literal, його **потрібно**:

package/rules/js-lint/coverage/coverage.mjs

@@ -10,9 +10,9 @@ import { spawnSync } from 'node:child_process'
 import { existsSync, readFileSync } from 'node:fs'
 import { mkdtemp, readFile, rm } from 'node:fs/promises'
 import { tmpdir } from 'node:os'
-import { join } from 'node:path'
+import { join, relative } from 'node:path'
 
-import { resolveJsRoot } from '../../../scripts/utils/resolve-js-root.mjs'
+import { resolveAllJsRoots } from '../../../scripts/utils/resolve-js-root.mjs'
 
 const TEST_BLOCK_START = /^\s*(it|test)\(/
 const FILE_EXTENSION = /\.[^.]+$/
@@ -30,21 +30,24 @@ function hasVitestDep(pkg) {
 
 /**
  * Чи провайдер застосовний у поточному cwd. Активується, коли `vitest`
- * декларовано у JS-root АБО у кореневому `package.json` (workspace-проєкт із
- * hoisted node_modules — типовий патерн bun monorepo, де npm-module rule
- * забороняє devDeps у published workspace-у, тож вони живуть у корені).
- * Інакше silent skip із hint у stderr (одноразово).
+ * декларовано хоча б в одному JS-root АБО у кореневому `package.json`
+ * (workspace-проєкт із hoisted node_modules — типовий патерн bun monorepo,
+ * де npm-module rule забороняє devDeps у published workspace-у, тож вони
+ * живуть у корені). Інакше silent skip із hint у stderr (одноразово).
  * @param {string} cwd корінь проєкту
  * @returns {Promise<boolean>} true, якщо проєкт сумісний з vitest-based coverage
  */
 export async function detect(cwd) {
-  const jsRoot = await resolveJsRoot(cwd)
-  if (jsRoot === null) return false
-  const pkgPath = join(jsRoot, 'package.json')
-  if (!existsSync(pkgPath)) return false
-  const pkg = JSON.parse(await readFile(pkgPath, 'utf8'))
-  if (hasVitestDep(pkg)) return true
-  if (jsRoot !== cwd) {
+  const jsRoots = await resolveAllJsRoots(cwd)
+  if (jsRoots.length === 0) return false
+  for (const jsRoot of jsRoots) {
+    const pkgPath = join(jsRoot, 'package.json')
+    if (!existsSync(pkgPath)) continue
+    const pkg = JSON.parse(await readFile(pkgPath, 'utf8'))
+    if (hasVitestDep(pkg)) return true
+  }
+  const rootInJsRoots = jsRoots.includes(cwd)
+  if (!rootInJsRoots) {
     const rootPkgPath = join(cwd, 'package.json')
     if (existsSync(rootPkgPath)) {
       const rootPkg = JSON.parse(await readFile(rootPkgPath, 'utf8'))
@@ -224,40 +227,91 @@ const defaultRunner = {
 }
 
 /**
- * Збирає JS-метрики покриття + мутаційного тестування.
+ * Збирає JS-метрики покриття + мутаційного тестування. У monorepo ітерує кожен
+ * JS-root з `resolveAllJsRoots()` (включно з glob-патернами на кшталт `cf/*`),
+ * запускає vitest+Stryker у кожному та сумує lcov/mutation. Шляхи файлів у
+ * `survived` рібейзяться відносно `cwd`, щоб `coverage-fix.mjs` знаходив джерела.
  * @param {string} cwd корінь проєкту
  * @param {{runner?: typeof defaultRunner}} [opts] runner-ін'єкція для тестів
  * @returns {Promise<Array<{area:string, coverage:object, mutation:{caught:number,total:number}}>>} рядки для COVERAGE.md
  */
 export async function collect(cwd, opts = {}) {
   const runner = opts.runner ?? defaultRunner
-  const jsRoot = await resolveJsRoot(cwd)
-  if (jsRoot === null) throw new Error('js-lint coverage: package.json не знайдено')
+  const jsRoots = await resolveAllJsRoots(cwd)
+  if (jsRoots.length === 0) throw new Error('js-lint coverage: package.json не знайдено')
+
+  let coverage = { lines: { covered: 0, total: 0 }, functions: { covered: 0, total: 0 } }
+  let mutation = { caught: 0, total: 0 }
+  const survived = []
+
+  for (const jsRoot of jsRoots) {
+    const wsRel = relative(cwd, jsRoot)
+
+    // 1. Coverage через vitest run --coverage (v8 provider пише lcov.info у lcovDir)
+    const lcovDir = await mkdtemp(join(tmpdir(), 'js-lint-cov-'))
+    try {
+      const code = await runner.runJsCoverage({ cwd: jsRoot, lcovDir })
+      if (code !== 0) throw new Error(`JS coverage exit ${code}`)
+      coverage = addCoverage(coverage, parseLcov(await readFile(join(lcovDir, 'lcov.info'), 'utf8')))
+    } finally {
+      await rm(lcovDir, { recursive: true, force: true })
+    }
+
+    // 2. Mutation через Stryker
+    await runner.runStryker({ cwd: jsRoot })
+    let mutationReport
+    try {
+      mutationReport = JSON.parse(await readFile(join(jsRoot, 'reports', 'stryker', 'mutation.json'), 'utf8'))
+    } catch {
+      throw new Error(
+        'js-lint coverage: stryker не залишив mutation.json — ' +
+          'запусти `npx @nitra/cursor fix test` для встановлення canonical stryker.config.mjs, ' +
+          'або налаштуй його вручну'
+      )
+    }
+    const parsed = parseStrykerReport(mutationReport, jsRoot)
+    mutation = addMutation(mutation, { caught: parsed.caught, total: parsed.total })
 
-  // 1. Coverage через vitest run --coverage (v8 provider пише lcov.info у lcovDir)
-  const lcovDir = await mkdtemp(join(tmpdir(), 'js-lint-cov-'))
-  let coverage
-  try {
-    const code = await runner.runJsCoverage({ cwd: jsRoot, lcovDir })
-    if (code !== 0) throw new Error(`JS coverage exit ${code}`)
-    coverage = parseLcov(await readFile(join(lcovDir, 'lcov.info'), 'utf8'))
-  } finally {
-    await rm(lcovDir, { recursive: true, force: true })
+    for (const group of parsed.survived) {
+      survived.push({
+        ...group,
+        file: wsRel === '' ? group.file : join(wsRel, group.file),
+        exampleTest: group.exampleTest
+          ? {
+              ...group.exampleTest,
+              testFile: wsRel === '' ? group.exampleTest.testFile : join(wsRel, group.exampleTest.testFile)
+            }
+          : null
+      })
+    }
   }
 
-  // 2. Mutation через Stryker
-  await runner.runStryker({ cwd: jsRoot })
-  let mutationReport
-  try {
-    mutationReport = JSON.parse(await readFile(join(jsRoot, 'reports', 'stryker', 'mutation.json'), 'utf8'))
-  } catch {
-    throw new Error(
-      'js-lint coverage: stryker не залишив mutation.json — ' +
-        'запусти `npx @nitra/cursor fix test` для встановлення canonical stryker.config.mjs, ' +
-        'або налаштуй його вручну'
-    )
+  return [{ area: 'JS', coverage, mutation, survived }]
+}
+
+/**
+ * Сумування coverage-totals — імпортується з оркестратора при потребі; тут
+ * локальна копія, щоб уникнути циклу test/coverage → js-lint/coverage.
+ * @param {{lines:{covered:number,total:number}, functions:{covered:number,total:number}}} a перший
+ * @param {{lines:{covered:number,total:number}, functions:{covered:number,total:number}}} b другий
+ * @returns {{lines:{covered:number,total:number}, functions:{covered:number,total:number}}} сума
+ */
+function addCoverage(a, b) {
+  return {
+    lines: { covered: a.lines.covered + b.lines.covered, total: a.lines.total + b.lines.total },
+    functions: {
+      covered: a.functions.covered + b.functions.covered,
+      total: a.functions.total + b.functions.total
+    }
   }
-  const { caught, total, survived } = parseStrykerReport(mutationReport, jsRoot)
+}
 
-  return [{ area: 'JS', coverage, mutation: { caught, total }, survived }]
+/**
+ * Сумування mutation-counts.
+ * @param {{caught:number,total:number}} a перший
+ * @param {{caught:number,total:number}} b другий
+ * @returns {{caught:number,total:number}} сума
+ */
+function addMutation(a, b) {
+  return { caught: a.caught + b.caught, total: a.total + b.total }
 }

package/rules/style-lint/style-lint.mdc

@@ -5,6 +5,92 @@ globs: "**/*.{css,scss,vue}"
 alwaysApply: false
 ---
 
+## Quasar як стильова основа
+
+У Vue-проектах використовуй **Quasar** як базову стильову систему:
+
+- **Класи компонентів:** `q-pa-*`, `q-ma-*`, `q-mt-*`, `q-mb-*`, `row`, `col`, `col-*`, `items-center`, `justify-between`, `text-*`, `bg-*`, `shadow-*` тощо — стандартні утиліти Quasar.
+- **Кольори:** використовуй Quasar CSS-змінні через класи (`text-primary`, `bg-accent`, `text-negative` тощо) або через SCSS-змінні (`$primary`, `$accent`) у `.scss`-файлах.
+- **Не пиши власні утиліти**, якщо є відповідний Quasar-клас.
+
+## Кольори: quasar-variables.scss і app.scss
+
+Основні кольори визначай виключно через стандартні Quasar-змінні: `$primary`, `$secondary`, `$accent`, `$positive`, `$negative`, `$warning`.
+
+Якщо потрібен додатковий колір — визнач його в `quasar-variables.scss`, і **обов'язково** додай до `app.scss` відповідні `.text-*` / `.bg-*` класи:
+
+```scss
+/* quasar-variables.scss */
+$white-a1: color.adjust(white, $alpha: -0.85);
+```
+
+```scss
+/* app.scss */
+.text-white-a1 {
+  color: $white-a1 !important;
+}
+
+.bg-white-a1 {
+  background-color: $white-a1 !important;
+}
+```
+
+## Gap між flex/grid-елементами — .n-gap-*
+
+Для відступів між плаваючими елементами (flex, grid) використовуй класи `.n-gap-*` замість `q-gutter-*`. Якщо класів немає в `app.scss` — додай:
+
+```scss
+// GAP
+.n-gap-xs {
+  gap: 4px;
+}
+
+.n-gap-sm {
+  gap: 8px;
+}
+
+.n-gap-md {
+  gap: 16px;
+}
+
+.n-gap-lg {
+  gap: 24px;
+}
+```
+
+## Фікси компонентів Quasar
+
+При використанні компонента `q-scroll-area` або `q-tooltip` додай до `app.scss` відповідні фікси. Аналогічно — фікс масштабування на iOS.
+
+```scss
+// FIX стилі для прокручуваної області по висоті екрана
+.q-scrollarea {
+  display: flex;
+  flex-direction: column;
+  height: auto;
+  min-height: 0;
+  max-height: 100%;
+
+  .scroll {
+    flex: 10000 1 0%;
+  }
+}
+
+// FIX tooltip
+.q-tooltip {
+  font-size: 1em;
+}
+
+// FIX не зумувати на iOS
+@media (width <= 600px) {
+  input,
+  textarea,
+  select {
+    font-size: 16px;
+  }
+}
+```
+
 ## Генерація та редагування стилів (Cursor і інші агенти)
 
 - **Джерело правил:** перед тим як писати або суттєво змінювати **`.css`**, **`.scss`** або стилі в **`.vue`**, переглянь у корені проєкту (і в релевантних пакетах монорепо, якщо є) поле **`stylelint`** у **`package.json`** (зокрема `extends`), наявні **`.stylelintrc.*`**, **`stylelint.config.*`** та **`.stylelintignore`**. Не покладайся на «типові» правила stylelint з пам’яті — дотримуйся **проєктного** **`@nitra/stylelint-config`** і будь-яких локальних доповнень у репозиторії.
@@ -94,3 +180,92 @@ jobs:
 ```text title=".stylelintignore"
 dist/
 ```
+
+## Адмінські таблиці — n-admin-table
+
+Для таблиць, що мають займати всю висоту сторінки (або блоку), додавай клас `n-admin-table` і атрибути `hide-no-data`, `dense`, `flat`. Таблиця автоматично розтягнеться на весь доступний простір. У блоках меншої висоти — задай їм явний `height`.
+
+```vue
+<!-- ТАБЛИЦЯ -->
+<q-table class="n-admin-table" hide-no-data flat dense />
+```
+
+Якщо клас `.n-admin-table` не визначено в `app.scss` — додай:
+
+```scss
+// ADMIN TABLE
+.n-admin-table {
+  height: calc(100vh - 106px);
+
+  thead {
+    position: sticky;
+    z-index: 3;
+    top: 0;
+
+    tr th {
+      background-color: $grey-3;
+      height: 36px !important;
+    }
+  }
+
+  // tbody td {
+  //   font-size: 14px;
+  // }
+
+  tbody tr:last-child td {
+    border-bottom: 1px solid rgb(0 0 0 / 12%) !important;
+  }
+
+  th:first-child,
+  td:first-child,
+  th:last-child,
+  td:last-child {
+    width: 1px;
+    white-space: nowrap;
+  }
+
+  .q-table__bottom {
+    background-color: $grey-3;
+  }
+
+  .q-table__progress th {
+    height: 1px !important;
+  }
+
+  .text-wrap {
+    max-width: 250px;
+    white-space: normal;
+  }
+
+  // sticky columns
+  td.sticky-left {
+    position: sticky;
+    left: 0;
+    z-index: 2;
+    background-color: white;
+    box-shadow: 2px 0 5px #0002;
+  }
+
+  td.sticky-right {
+    position: sticky;
+    right: 0;
+    z-index: 2;
+    background-color: white;
+    box-shadow: -2px 0 5px #0002;
+  }
+
+  th.sticky-left {
+    position: sticky;
+    left: 0;
+    z-index: 3;
+    box-shadow: 2px 0 5px #0002;
+  }
+
+  th.sticky-right {
+    position: sticky;
+    right: 0;
+    z-index: 3;
+    box-shadow: -2px 0 5px #0002;
+  }
+}
+```

package/rules/vue/vue.mdc

@@ -12,18 +12,30 @@ alwaysApply: false
 ```javascript
 const vue3CompositionApiBestPractices = [
   'Використовуй функцію setup() для логіки компонента',
-  'Реалізуй computed properties через $computed()',
-  'Використовуй watch і watchEffect для side effects',
+  'Реалізуй computed змінні через $computed()',
+  'Реалізуй ref змінні через $ref',
+  'Використовуй watch і watchEffect для побічних ефектів',
   'Підключай lifecycle hooks: onMounted, onUpdated тощо',
-  'не використовуй provide/inject для dependency injection'
+  'Для глибоко вкладених залежностей використовуй composables, props/emits або store'
+  'не використовуй provide/inject для залежностей'
 ]
 ```
 
+## Quasar як UI-основа
+
+У Vue-проектах використовуй **Quasar** як базовий UI-фреймворк:
+
+- **Компоненти:** `q-btn`, `q-input`, `q-select`, `q-table`, `q-dialog`, `q-card`, `q-layout`, `q-page`, `q-drawer` тощо — основа UI.
+- **Плагіни:** `Notify`, `Dialog`, `Loading` та інші Quasar-плагіни.
+- **Кольори:** використовуй Quasar CSS-змінні (`primary`, `secondary`, `accent`, `positive`, `negative`, `warning`, `info`, `dark`) і утиліти (`text-primary`, `bg-accent` тощо).
+- **Утиліти:** flex-layout (`row`, `col`, `items-center`), spacing (`q-pa-md`, `q-mt-sm`), shadow (`shadow-2`) — зі стандартної бібліотеки Quasar.
+- **Кастомні компоненти** `@nitra/components` — **надбудова** над Quasar, а не заміна; їх слід надавати перевагу лише там, де вони є (див. розділ `@nitra/components` нижче).
+
 ## Структура папок
 
 ```javascript
 const folderStructure = `
-src/
+  src/
   components/
   composables/
   views/
@@ -76,7 +88,7 @@ const additionalInstructions = `
 
 ### Патерни та антипатерни
 
-- **provide/inject** — для глибоко вкладених залежностей; **renderless**-компоненти / **slots** — коли логіку відділяєш від розмітки.
+- Для глибоко вкладених залежностей використовуй **composables**, **props/emits** або **store**; **renderless**-компоненти / **slots** — коли логіку відділяєш від розмітки.
 - **HTTP:** окремі модулі **services** або **composables** для API; **async/await**.
 - **Події:** батько–дитина через **emits**; для не пов’язаних гілок — **store**.
 - Не мутуй **props** напряму — оновлення через подію вгору або v-model.
@@ -343,6 +355,292 @@ import path from 'node:path'
 Правило стосується саме `.vue` файлів. Допоміжні `.ts`/`.js` модулі, які споживаються лише server-side
 (наприклад, окремий пакет утіліт), можуть імпортувати Node-built-ins без обмежень.
 
+## @nitra/components — надавай перевагу перед Quasar-компонентами
+
+При створенні нової функціональності використовуй компоненти `@nitra/components`, якщо логіка компонента дозволяє отримати потрібний функціонал. Заміни:
+
+| Завдання | `@nitra/components` | Замість Quasar |
+| --- | --- | --- |
+| Діалоги | `NDialog` | `q-dialog` |
+| Multi-вибір | `NSelectMulti` | `q-select` (multiple) |
+| Текстовий редактор | `NEditor` | `q-editor` |
+| Вибір дати | `NDate` | — |
+| Вибір місяця/року | `NDateMonthYear` | — |
+| Діапазон дат | `NDateRange` | — |
+| Дата і час | `NDateTime` | — |
+| Drag&drop список | `NDraggableList` | — |
+| Редаговане значення | `NEditableString` | — |
+| Повідомлення | `NCallout` | — |
+| Хедер проекту | `NHeader` | — |
+| Перемикання мов | `NLang` | — (якщо `NHeader` не використовується) |
+| Меню проекту | `NMenu` | — |
+| Зображення (масив / одиночне) | `NImages` | — |
+| Завантаження файлів | `NUploader` | — |
+| Вибір колонок `q-table` | `NTableColumns` | — |
+
+## NHeader — телепорт-слоти на сторінках
+
+У проектах з `NHeader` використовуй `<teleport>` для вбудовування контенту сторінки в шапку:
+
+| Слот | Призначення |
+| --- | --- |
+| `#header-subtitle` | Заголовок сторінки (якщо потрібно перевизначити subtitle) |
+| `#header-center` | Важливі повідомлення та елементи управління |
+| `#header-filters` | Фільтри, кнопки та інші елементи управління сторінки |
+
+Оскільки `NHeader` за замовчуванням темний, додавай до полів і селектів у телепортах: `dark`, `standout="bg-white text-primary"`, `:options-dark="false"`.
+
+Завжди обгортай `<teleport>` в `v-if="mounted"` (де `mounted` — `$ref(false)`, що встановлюється в `onMounted`), щоб уникнути помилки відсутності target-елемента при SSR / першому рендері.
+
+```vue
+<template>
+  <q-page>
+    <!-- ФІЛЬТРИ В ШАПЦІ -->
+    <teleport v-if="mounted" to="#header-filters">
+      <div class="col row items-center n-gap-sm q-pa-sm">
+        <q-input
+          v-model="pageStore.filterName"
+          :label="t`Поиск по названию`"
+          debounce="200"
+          standout="bg-white text-primary"
+          clearable
+          dense
+          dark
+          class="col"
+          style="min-width: 120px">
+          <template #prepend>
+            <q-icon name="search" />
+          </template>
+        </q-input>
+
+        <n-select-multi
+          v-model="pageStore.filterRequestTypes"
+          :options="requestTypeOptions"
+          :label="t`Тип запроса`"
+          dark
+          standout="bg-white text-primary"
+          :options-dark="false"
+          style="min-width: 180px; max-width: 400px"
+          dense
+          emit-value
+          map-options
+          clearable
+          searchable
+          :stack-label="false" />
+
+        <q-btn
+          @click="addItem"
+          icon="add"
+          :label="t`Добавить`"
+          color="primary"
+          no-caps
+          padding="8px 12px"
+          unelevated />
+      </div>
+    </teleport>
+
+    <!-- ОСНОВНИЙ КОНТЕНТ -->
+    ...
+  </q-page>
+</template>
+<script setup>
+const mounted = $ref(false)
+onMounted(() => { mounted = true })
+</script>
+```
+
+## @nitra/tfm — переклади
+
+Використовуй `@nitra/tfm` для всіх текстів. Переклади для всіх мов проекту оголошуй наприкінці `<script setup>` у функції `getTr()`. Змінна `lang` із `@nitra/tfm` — для визначення або зміни поточної мови застосунку.
+
+```vue
+<template>
+  {{ lang }}
+  {{ t`Анкеты` }}
+  {{ subtitle }}
+</template>
+<script setup>
+import { lang, tf as tfm } from '@nitra/tfm'
+const t = tfm.bind({ tr: getTr() })
+const subtitle = $computed(() => t`Анкеты`)
+
+/**
+ * LOCALIZATION
+ * @returns {object} translations
+ */
+function getTr() {
+  return {
+    Анкеты: { en: 'Surveys', ro: 'Sondaje', tr: 'Anketler' }
+  }
+}
+</script>
+```
+
+## Layout з NHeader
+
+Для нових layout-ів використовуй `NHeader` з вбудованими `NLang` і `NMenu`.
+
+```vue
+<template>
+  <q-layout view="hHh Lpr lFf">
+    <n-header
+      v-model="leftSideOpened"
+      :logo="baseUrl + 'logo.png'"
+      :logo-url="homeUrl"
+      title="My App"
+      :subtitle="subtitle"
+      :username="userName"
+      toolbar-dark>
+      <template #top-toolbar>
+        <div class="platform-ios-only q-py-lg" />
+      </template>
+      <div>default slot content</div>
+    </n-header>
+
+    <!-- ЛЕВАЯ КОЛОНКА -->
+    <q-drawer v-model="leftSideOpened" :breakpoint="700" :width="300" overlay class="col column shadow-5 bg-grey-1">
+      <div class="platform-ios-only q-py-lg" />
+      <div v-if="!$q.screen.gt.xs" class="q-pa-sm row items-center">
+        <q-icon name="account_circle" color="primary" size="32px" class="q-mr-sm" />
+        <div class="text-subtitle1">{{ user.name }}</div>
+      </div>
+      <n-menu v-model="activeMenu" :menu="menu" />
+      <q-space />
+      <n-menu :menu="homeMenu" />
+      <div class="platform-ios-only q-py-md" />
+    </q-drawer>
+
+    <q-page-container>
+      <router-view />
+    </q-page-container>
+  </q-layout>
+</template>
+<script setup>
+import { lang, tf as tfm } from '@nitra/tfm'
+const t = tfm.bind({ tr: getTr() })
+
+const baseUrl = import.meta.env.BASE_URL
+const homeUrl = String.raw`https:\\` + import.meta.env.VITE_DOMAIN
+
+// Ліва колонка
+const leftSideOpened = $ref(false)
+const activeMenu = $ref(null)
+
+// Заголовок у шапці з поточного пункту меню
+const subtitle = computed(() => (activeMenu ? getTr()[activeMenu.labelKey]?.[lang.value] || activeMenu?.labelKey : ''))
+
+// Меню
+const menu = computed(() =>
+  [
+    {
+      icon: 'sym_o_store',
+      label: t`Клиенты`,
+      labelKey: t`Клиенты`,
+      routeName: 'customer'
+    },
+    {
+      icon: 'sym_o_route',
+      label: t`Маршруты и визиты`,
+      items: [
+        {
+          icon: 'sym_o_route',
+          label: t`Маршруты`,
+          labelKey: t`Маршруты`,
+          routeName: 'route'
+        },
+        {
+          icon: 'sym_o_event_upcoming',
+          label: t`Переносы маршрутов`,
+          labelKey: t`Переносы маршрутов`,
+          routeName: 'route_postpone'
+        }
+      ]
+    }
+  ].filter(item => {
+    if (item.items?.length) {
+      item.items = item.items.filter(i => can[i.permissionRoute || i.routeName])
+      return item.items.length > 0
+    }
+    return can[item.routeName]
+  })
+)
+
+/**
+ * LOCALIZATION
+ * @returns {object} translations
+ */
+function getTr() {
+  return {
+    Клиенты: { en: 'Customers', ro: 'Clienți', tr: 'Müşteriler' }
+  }
+}
+</script>
+```
+
+## Pinia store для стану сторінки
+
+Зберігай у Pinia store:
+
+- вибрані значення фільтрів
+- вибрані для відображення колонки (`NTableColumns`)
+- кількість записів на сторінці (pagination)
+
+Називай store за назвою сторінки або компонента — `customerPageStore`, `routePageStore` тощо. На сторінці звертайся до нього через змінну `pageStore`.
+
+```javascript
+// store/customerPage.js
+export const useCustomerPageStore = defineStore('customerPage', {
+  state: () => ({
+    filterName: '',
+    filterStatus: [],
+    columns: [],
+    rowsPerPage: 20
+  })
+})
+```
+
+```vue
+<script setup>
+const pageStore = useCustomerPageStore()
+</script>
+```
+
+## Коментарі в `<template>`
+
+Додавай коментарі в `<template>` відповідно до логічного призначення блоку. Коментарі допомагають швидко орієнтуватися в розмітці.
+
+```vue
+<template>
+  <q-page>
+    <!-- ФІЛЬТРИ В ШАПЦІ -->
+    <teleport v-if="mounted" to="#header-filters">...</teleport>
+
+    <!-- ТАБЛИЦЯ -->
+    <q-table ... />
+
+    <!-- ДІАЛОГ РЕДАГУВАННЯ -->
+    <n-dialog v-model="editDialog">...</n-dialog>
+  </q-page>
+</template>
+```
+
+## Статичні файли — BASE_URL
+
+Для підключення статичних файлів не використовуй відносні шляхи. Завжди будуй URL через `import.meta.env.BASE_URL`:
+
+```vue
+<!-- Погано -->
+<img src="/logo.png" />
+<img src="./assets/logo.png" />
+
+<!-- Добре -->
+<img :src="baseUrl + 'logo.png'" />
+```
+
+```javascript
+const baseUrl = import.meta.env.BASE_URL
+```
+
 ## Перевірка
 
 `npx @nitra/cursor fix vue` — перевіряє залежності, `vite.config`, наявність **`src/vite-env.d.ts`** з `/// <reference types="vite/client" />` та **`jsconfig.json`** у корені Vue-пакета; обходить джерела Vue-пакета (`.vue`, `.ts`, `.js` тощо) на заборонені value-імпорти з модуля `vue` (дозволені лише type-only та side-effect `import 'vue'`) і додатково сканує `.vue` SFC на імпорти Node-нативних модулів (`node:*` префікс або bare-ім’я вбудованого модуля Node — `fs`, `path`, `timers/promises` тощо). Імпорти аналізуються через **oxc-parser** (`module.staticImports`); для `.vue` вміст `<script>` витягується з SFC, далі той самий парсер (логіка в `npm/rules/vue/js/packages/vue-forbidden-imports.mjs`).

package/scripts/utils/resolve-js-root.mjs

@@ -1,33 +1,48 @@
 /**
  * Резолвить корінь JS-коду в проєкті: для workspace-projects — перший workspace
- * (наприклад `app/` у mail app), для single-package — корінь cwd. Спільна утиліта
- * для coverage-провайдера js-lint і test-концерну stryker_config (DRY).
+ * (з підтримкою glob-патернів типу `cf/*`), для single-package — корінь cwd.
+ * Спільна утиліта для coverage-провайдера js-lint і test-концерну stryker_config (DRY).
  */
 import { existsSync } from 'node:fs'
-import { readFile } from 'node:fs/promises'
+import { glob, readFile } from 'node:fs/promises'
 import { join } from 'node:path'
 
+const WORKSPACE_GLOB_IGNORE = ['**/node_modules/**', '**/.git/**']
+
+/**
+ * Розгортає один workspace-патерн у список абсолютних шляхів каталогів з package.json.
+ * Літеральні патерни перевіряються через existsSync; glob-патерни — через node:fs/promises#glob.
+ * @param {string} cwd корінь проєкту
+ * @param {string} pattern workspace-патерн з package.json (наприклад, `app` або `cf/*`)
+ * @returns {Promise<string[]>} абсолютні шляхи до workspace-каталогів
+ */
+async function expandWorkspacePattern(cwd, pattern) {
+  if (!pattern.includes('*')) {
+    const wsPath = join(cwd, pattern)
+    return existsSync(join(wsPath, 'package.json')) ? [wsPath] : []
+  }
+  const results = []
+  for await (const rel of glob(`${pattern}/package.json`, { cwd, exclude: WORKSPACE_GLOB_IGNORE })) {
+    const wsRel = rel.replace(/[/\\]package\.json$/, '')
+    results.push(join(cwd, wsRel))
+  }
+  return results.sort()
+}
+
 /**
  * @param {string} cwd корінь проєкту (де `.n-cursor.json` і кореневий package.json)
  * @returns {Promise<string|null>} абсолютний шлях до JS-root або null без кореневого package.json
  */
 export async function resolveJsRoot(cwd) {
-  const rootPkgPath = join(cwd, 'package.json')
-  if (!existsSync(rootPkgPath)) return null
-  const rootPkg = JSON.parse(await readFile(rootPkgPath, 'utf8'))
-  const workspaces = Array.isArray(rootPkg.workspaces) ? rootPkg.workspaces : []
-  if (workspaces.length > 0) {
-    const wsPath = join(cwd, workspaces[0])
-    if (existsSync(join(wsPath, 'package.json'))) return wsPath
-  }
-  return cwd
+  const roots = await resolveAllJsRoots(cwd)
+  if (roots.length === 0) return null
+  return roots[0]
 }
 
 /**
  * Plural-варіант: повертає всі JS-roots проєкту. Для workspace-projects — кожен
- * workspace з власним `package.json`; для single-package — `[cwd]`. Порожній
- * масив без кореневого package.json. Використовується test-концерном
- * `stryker_config` для per-workspace baseline-копіювання.
+ * workspace з власним `package.json` (з розгортанням glob-патернів); для
+ * single-package — `[cwd]`. Порожній масив без кореневого package.json.
  * @param {string} cwd корінь проєкту
  * @returns {Promise<string[]>} абсолютні шляхи до всіх JS-roots
  */
@@ -35,12 +50,11 @@ export async function resolveAllJsRoots(cwd) {
   const rootPkgPath = join(cwd, 'package.json')
   if (!existsSync(rootPkgPath)) return []
   const rootPkg = JSON.parse(await readFile(rootPkgPath, 'utf8'))
-  const workspaces = Array.isArray(rootPkg.workspaces) ? rootPkg.workspaces : []
-  if (workspaces.length === 0) return [cwd]
+  const patterns = Array.isArray(rootPkg.workspaces) ? rootPkg.workspaces : []
+  if (patterns.length === 0) return [cwd]
   const roots = []
-  for (const ws of workspaces) {
-    const wsPath = join(cwd, ws)
-    if (existsSync(join(wsPath, 'package.json'))) roots.push(wsPath)
+  for (const pattern of patterns) {
+    roots.push(...(await expandWorkspacePattern(cwd, pattern)))
   }
   return roots.length > 0 ? roots : [cwd]
 }