@nitra/cursor 1.8.209 → 1.8.212

package/CHANGELOG.md

@@ -4,6 +4,61 @@
 
 Формат — [Keep a Changelog](https://keepachangelog.com/uk/1.1.0/), нумерація — [SemVer](https://semver.org/lang/uk/).
 
+## [1.8.212] - 2026-05-08
+
+### Changed
+
+- `npm/skills/taze/SKILL.md`: повний workflow замість шаблону-заглушки. Тепер
+  скіл бекапить `package.json`/`bun.lock`, виконує `bunx taze -w -r latest` +
+  `bun install`, виявляє major-стрибки порівнянням з бекапом, тягне breaking
+  changes з CHANGELOG модуля або git-діфу `node_modules` (з фолбеком на
+  встановлення старої версії в `/tmp`), шукає використання зачепленого API в
+  коді через `rg`, рефакторить несумісні місця (нетривіальні міграції — TODO),
+  прибирає тимчасові файли і віддає структурований звіт користувачу.
+
+## [1.8.211] - 2026-05-08
+
+### Added
+
+- Окремий шлях автодетекту для скілів — `npm/bin/auto-skills.md` +
+  `npm/scripts/auto-skills.mjs` (`detectAutoSkills`). Скіли отримують свій
+  словник умов (`skill - [rules]`), залежний від уже виявлених правил, тож не
+  дублюють файлові ознаки з `auto-rules.md`.
+- Нові авто-скіли: `publish-telegram` (завжди) і `taze` (за правилом `bun`).
+- `npm/tests/auto-skills.test.mjs` — окремі тести `detectAutoSkills`
+  (завжди-додавані, залежності від rule-id, `disable-skills`, фільтр за
+  `availableSkills`).
+
+### Changed
+
+- `npm/scripts/auto-rules.mjs`: `detectAutoRulesAndSkills` → `detectAutoRules`
+  (повертає лише `{ rules }`); прибрано `AUTO_SKILL_ORDER` і скіл-логіку.
+  `mergeConfigWithAutoDetected` лишається спільним і приймає вже виявлені
+  rules+skills, тож публічний контракт `.n-cursor.json` не змінився.
+- `npm/bin/n-cursor.js` тепер послідовно викликає `detectAutoRules` і
+  `detectAutoSkills` (скіли отримують `detectedRules` як вхід).
+- `npm/bin/auto-rules.md` залишає тільки правила; секція скілів винесена в
+  `auto-skills.md` з посиланням з `auto-rules.md`.
+
+## [1.8.210] - 2026-05-08
+
+### Added
+
+- `js-bun-db` v1.6: правило тепер забороняє локальні pg-format-сумісні шими у
+  файлах з Bun SQL.
+  - Розділ `## pg-format: повне видалення, без шимів` у `npm/mdc/js-bun-db.mdc`:
+    типові ідіоми `format(...)` → tagged template, заборонений drop-in `format()`
+    і `pg`-сумісна `query(text, params)`-обгортка над `sql.unsafe(...)`.
+  - Два нові AST-детектори у `npm/scripts/utils/bun-sql-scan.mjs`:
+    `findPgFormatShimDefinitionInText` (функції `format` / `pgFormat` /
+    `sqlFormat` / `pgFmt` з `%L`/`%I`/`%s` у тілі, плюс `quoteLiteral` /
+    `quoteIdent` / `escapeLiteral` / `escapeIdent` без додаткової перевірки)
+    та `findPgFormatLikeQueryWrapperInText` (`{ query(text, params) { ...
+    <obj>.unsafe(...) ... } }`). Скан запускається лише у файлах з
+    `import { sql|SQL } from 'bun'`.
+  - `npm/scripts/check-js-bun-db.mjs` рапортує `pgFormatShim` / `queryWrapper` —
+    окремі лічильники й `pass`-рядки, без зміни існуючих перевірок.
+
 ## [1.8.209] - 2026-05-08
 
 ### Removed

package/bin/auto-rules.md

@@ -1,6 +1,6 @@
-# Авто вмикання правил та скілів
+# Авто вмикання правил
 
-В цьому файлі описані умови, по яким повинні скіли та правила автододаватись в конфіг
+В цьому файлі описані умови, по яким повинні правила автододаватись в конфіг. Умови автододавання скілів — у `auto-skills.md` (виносить логіку зі словника правил у пару «правило → скіл»).
 
 ## Правила, які автоматично додається до .n-cursor.json
 
@@ -50,16 +50,6 @@ text - завжди
 
 vue - якщо присутній хоч один vue файл
 
-## Скіли, які автоматично додається до .n-cursor.json
-
-abie-kustomize - якщо в кореневому package.json в секції "repository" присутній текст "<https://github.com/abinbevefes/**/>"
-
-fix - завжди
-
-lint - завжди
-
 ## Виключення
 
 Якщо в .n-cursor.json задано в секції disable-rules правило, то воно автоматично додаватись не повинно.
-
-Якщо в .n-cursor.json задано в секції disable-skills скіл, то він автоматично додаватись не повинен.

package/bin/auto-skills.md

@@ -0,0 +1,21 @@
+# Авто вмикання скілів
+
+В цьому файлі описані умови, по яким повинні скіли автододаватись в конфіг.
+
+## Скіли, які автоматично додається до .n-cursor.json
+
+Синтаксис `skill - [rules]` означає: скіл `skill` варто автододати лише якщо всі правила у списку `[rules]` уже додані до конфігу автодетектом (з `auto-rules.md`). Так залежність не дублює вихідну умову правила.
+
+abie-kustomize - [abie]
+
+fix - завжди
+
+lint - завжди
+
+publish-telegram - завжди
+
+taze - [bun]
+
+## Виключення
+
+Якщо в .n-cursor.json задано в секції disable-skills скіл, то він автоматично додаватись не повинен.

package/bin/n-cursor.js

@@ -58,12 +58,13 @@ import { fileURLToPath } from 'node:url'
 
 import { buildAgentsCommandBulletItems } from '../scripts/build-agents-commands.mjs'
 import {
-  detectAutoRulesAndSkills,
+  detectAutoRules,
   detectLegacyRuleIds,
   mergeConfigWithAutoDetected,
   normalizeIdList,
   RULE_MIGRATIONS
 } from '../scripts/auto-rules.mjs'
+import { detectAutoSkills } from '../scripts/auto-skills.mjs'
 import { runStopHookCli } from '../scripts/claude-stop-hook.mjs'
 import { ensureNitraCursorInRootDevDependencies } from '../scripts/ensure-nitra-cursor-dev-dependencies.mjs'
 import { runLintGaCli } from '../scripts/lint-ga.mjs'
@@ -250,19 +251,22 @@ async function readConfig(paths = {}) {
     const rootPkg = await readRootPackageJsonSafe()
     const disableRules = normalizeIdList(parsedConfig['disable-rules'])
     const disableSkills = normalizeIdList(parsedConfig['disable-skills'])
-    const autoDetected = await detectAutoRulesAndSkills({
+    const autoDetectedRules = await detectAutoRules({
       root: cwd(),
       availableRules,
-      availableSkills,
       packageJsonParsed: rootPkg,
-      disableRules,
+      disableRules
+    })
+    const autoDetectedSkills = detectAutoSkills({
+      availableSkills,
+      detectedRules: autoDetectedRules.rules,
       disableSkills
     })
 
     const merged = mergeConfigWithAutoDetected({
       config: parsedConfig,
-      detectedRules: autoDetected.rules,
-      detectedSkills: autoDetected.skills
+      detectedRules: autoDetectedRules.rules,
+      detectedSkills: autoDetectedSkills.skills
     })
 
     const rest = Object.fromEntries(Object.entries(parsedConfig).filter(([k]) => k !== '$schema'))
@@ -283,16 +287,19 @@ async function readConfig(paths = {}) {
 
   if (!existsSync(configPath)) {
     const rootPkg = await readRootPackageJsonSafe()
-    const autoDetected = await detectAutoRulesAndSkills({
+    const autoDetectedRules = await detectAutoRules({
       root: cwd(),
       availableRules,
-      availableSkills,
       packageJsonParsed: rootPkg
     })
+    const autoDetectedSkills = detectAutoSkills({
+      availableSkills,
+      detectedRules: autoDetectedRules.rules
+    })
     const defaultConfig = sortConfigIdArrays({
       $schema: CONFIG_SCHEMA_URL,
-      rules: autoDetected.rules,
-      skills: autoDetected.skills
+      rules: autoDetectedRules.rules,
+      skills: autoDetectedSkills.skills
     })
     await writeFile(configPath, `${JSON.stringify(defaultConfig, null, 2)}\n`, 'utf8')
     console.log(
@@ -1127,7 +1134,7 @@ async function readBundledVersionAt(packageRoot) {
  * Якщо `upgradeNitraCursorToLatestAndBunInstall` встановив у `node_modules/@nitra/cursor` версію,
  * відмінну від тієї, з якої стартував поточний процес (наприклад, з npx-кешу), запускає бінар нової
  * версії через `spawnSync` і завершує поточний процес із успадкованим exit-кодом. Re-exec потрібен,
- * бо ES-модулі вже завантажені у V8 (RULE_MIGRATIONS, detectAutoRulesAndSkills тощо) і нова логіка
+ * бо ES-модулі вже завантажені у V8 (RULE_MIGRATIONS, detectAutoRules тощо) і нова логіка
  * без повної заміни процесу не підхопиться. Захист від нескінченного циклу — env `NITRA_CURSOR_REEXEC=1`.
  * @param {string} effectivePackageRoot шлях, повернутий `upgradeNitraCursorToLatestAndBunInstall`
  * @returns {Promise<void>} повертається лише якщо re-exec не потрібен (інакше викликає `process.exit`)

package/mdc/js-bun-db.mdc

@@ -1,7 +1,7 @@
 ---
 description: Використання pg / mysql2 / Bun SQL у Node.js та Bun
 alwaysApply: true
-version: '1.5'
+version: '1.6'
 ---
 
 ## Підтримувані версії баз даних
@@ -18,6 +18,58 @@ PostgreSQL 18+, MariaDB 10.6+ (сумісний з MySQL-протоколом,
 
 `pg-format` — це ручне форматування SQL через escape (`format('... %L ...', value)`); такі рядки легко поламати неправильним типом, locale-залежним escape або забутим `%L`. Tagged template Bun SQL параметризує значення нативно (`sql\`... ${value} ...\``) і не лишає простору для injection — окремий «форматер» не потрібен.
 
+## `pg-format`: повне видалення, без шимів
+
+Міграція з `pg-format` — це **зміна стилю запитів**, а не збереження API. У проєкті після переходу на Bun SQL **заборонено** залишати:
+
+- функцію з іменем `format` (чи `pgFormat`, `sqlFormat`, `pgFmt`), що приймає шаблон з `%L` / `%I` / `%s` і значення;
+- допоміжні `quoteLiteral`, `quoteIdent`, `escapeLiteral`, `escapeIdent` як публічні експорти модуля;
+- обгортки `pgRead.query(text, params)` / `pgWrite.query(text, params)` / `db.query(text, params)`, які складають SQL-рядок (з або без `format`) і викликають `sql.unsafe(text, params)` — це повертає injection-поверхню, від якої ми йдемо, тільки під «зручним» іменем.
+
+Замість цього всі точки використання потрібно перевести на tagged template `sql\`...\${value}...\``. Кожне `${value}` стає окремим параметром bind, без рядкового екранування.
+
+### Типові ідіоми `pg-format` → Bun SQL
+
+| Було (`pg-format`)                                 | Стало (Bun SQL)                                                                                  |
+| -------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
+| `format('... WHERE id = %L', id)`                  | `sql\`... WHERE id = ${id}\``                                                                    |
+| `format('... IN (%L)', ids)`                       | `sql\`... IN ${sql(ids)}\`` (з guard на пустоту перед запитом)                                   |
+| `format('INSERT ... VALUES %L', [row])` (1 рядок)  | `sql\`INSERT ... VALUES (${a}, ${b}, ...)\``                                                     |
+| `format('INSERT ... VALUES %L', rows)` (N рядків)  | `sql\`INSERT INTO t ${sql(rows, 'a', 'b')}\`` або `unnest($1::T[], $2::T[]) AS t(a, b)`          |
+| `format('MERGE ... USING (VALUES %L) AS d(...)')`  | `sql\`MERGE ... USING (SELECT * FROM unnest(${arrA}::A[], ${arrB}::B[]) AS t(a, b)) AS d\``      |
+| `format('... %I ...', tableName)` (whitelist)      | `sql.unsafe(\`... \${tableName} ...\`)` з маркером `// allow-unsafe: <причина>` і whitelist'ом   |
+
+Для multi-row `VALUES` у `MERGE` / `INSERT` з конкретними типами — паралельні масиви по колонках і `unnest($1::TYPE[], $2::TYPE[], ...) AS t(col1, col2, ...)`. Кожна колонка передається одним параметром-масивом; типи задаються кастом масиву (`::uuid[]`, `::bigint[]`, `::numeric[]`, `::text[]`, …).
+
+### Заборонений «drop-in» шим
+
+```javascript
+// ❌ pg-format-сумісний шим, що ховає `unsafe` під «безпечним» іменем
+export function format(fmt, ...args) {
+  let i = 0
+  return fmt.replaceAll(/%[LIs]/g, () => quoteLiteral(args[i++]))
+}
+
+// ❌ і його типовий call-site — той самий injection-вектор, що і прямий sql.unsafe із конкатенацією
+await sql.unsafe(format('... WHERE id = %L', userId))
+```
+
+```javascript
+// ❌ pg-сумісна обгортка над Bun SQL — ще один прихований `unsafe`
+export const pgWrite = {
+  query(text, params) {
+    return sql.unsafe(text, params)
+  }
+}
+```
+
+```javascript
+// ✅ напряму tagged template — параметризація через wire-protocol bind
+await sql`... WHERE id = ${userId}`
+```
+
+Виняток для шиму `format()` під час поетапної міграції допускається **тільки** в окремому commit'і з TODO-маркером і дедлайном; готовий код у main з таким шимом — `fail` правила (детектори: `pg-format shim`, `query wrapper over unsafe`).
+
 ## Підключення (singleton + env)
 
 Дефолтний експорт `sql` з `'bun'` сам читає змінні середовища (`DATABASE_URL`, `POSTGRES_URL`, `MYSQL_URL`, `PGHOST`/`PGUSER`/... та `MYSQL_HOST`/`MYSQL_USER`/...) і керує пулом — окремий `Pool` як у `pg` створювати не треба.
@@ -197,6 +249,8 @@ function getUser(id) {
 
 Якщо в коді з'явився `import { sql } from 'bun'`, то `pg`, `pg-format` та `mysql2` мають бути прибрані і з `dependencies`, і з імпортів — щоб не лишалось двох паралельних шляхів до БД та ручного форматування поряд із параметризованими template literal.
 
+Те саме стосується **локальних шимів**: будь-який модуль, що експортує `format`, `pgRead`, `pgWrite`, `query(text, params)`, `quoteLiteral`, `quoteIdent` як обгортку над `sql.unsafe(...)`, потрібно переписати — всі call-site на tagged template, сам шим видалити (див. `## pg-format: повне видалення, без шимів`).
+
 ## Перевірка
 
 `npx @nitra/cursor check js-bun-db`.

package/package.json

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

package/scripts/auto-rules.mjs

@@ -1,13 +1,16 @@
 /**
- * Автовизначення правил і skills для `.n-cursor.json` за умовами з `npm/bin/auto-rules.md`.
+ * Автовизначення правил для `.n-cursor.json` за умовами з `npm/bin/auto-rules.md`.
  *
  * Модуль аналізує дерево проєкту (наявність файлів/директорій, `gql\`...\`` у source,
  * залежності `mssql` / `pg` / `pg-format` / `mysql2` у `package.json`, імпорт `sql`/`SQL` з `bun`, кореневий
  * `package.json`, `config.yaml` з рядком `metadata_directory: metadata` для hasura)
- * та повертає ідентифікатори правил і skills, які потрібно автододати.
+ * та повертає ідентифікатори правил, які потрібно автододати.
  *
- * Також враховує винятки `disable-rules` і `disable-skills`: елементи з цих списків не
- * додаються автоматично.
+ * Враховує винятки `disable-rules`: елементи зі списку не додаються автоматично.
+ *
+ * Автодетект скілів — у `./auto-skills.mjs` (умови — у `npm/bin/auto-skills.md`).
+ * `mergeConfigWithAutoDetected` нижче приймає вже виявлені rules і skills і вливає
+ * їх у конфіг із поправкою на legacy-id (`migrateRuleIds`).
  */
 import { existsSync } from 'node:fs'
 import { readdir, readFile } from 'node:fs/promises'
@@ -47,9 +50,6 @@ export const AUTO_RULE_ORDER = Object.freeze([
   'vue'
 ])
 
-/** Порядок автододавання skills відповідно до `auto-rules.md`. */
-export const AUTO_SKILL_ORDER = Object.freeze(['abie-kustomize', 'fix', 'lint'])
-
 /**
  * Карта міграції застарілих rule-id у `.n-cursor.json` на актуальні.
  * Застосовується автоматично при читанні конфігу (як для `rules`, так і для `disable-rules`).
@@ -575,29 +575,23 @@ function resolveRuleDependencies(detectedRules, addRule) {
 }
 
 /**
- * Визначає авто-правила та skills згідно з `auto-rules.md`.
+ * Визначає авто-правила згідно з `auto-rules.md`.
  * @param {object} params параметри аналізу
  * @param {string} params.root абсолютний шлях до кореня репозиторію
  * @param {string[]} params.availableRules перелік доступних правил з пакету
- * @param {string[]} params.availableSkills перелік доступних skills з пакету
  * @param {unknown} params.packageJsonParsed кореневий package.json (розпарсений) або null
  * @param {string[]} [params.disableRules] список `disable-rules` з конфігу
- * @param {string[]} [params.disableSkills] список `disable-skills` з конфігу
- * @returns {Promise<{ rules: string[], skills: string[] }>} списки id у стабільному порядку
+ * @returns {Promise<{ rules: string[] }>} список id у стабільному порядку (за `AUTO_RULE_ORDER`)
  */
-export async function detectAutoRulesAndSkills({
+export async function detectAutoRules({
   root,
   availableRules,
-  availableSkills,
   packageJsonParsed,
-  disableRules = DEFAULT_DISABLED_LIST,
-  disableSkills = DEFAULT_DISABLED_LIST
+  disableRules = DEFAULT_DISABLED_LIST
 }) {
   const facts = await collectAutoRuleFacts(root)
   const normalizedRules = new Set(availableRules.map(r => r.trim().toLowerCase()))
-  const normalizedSkills = new Set(availableSkills.map(s => s.trim().toLowerCase()))
   const disableRulesSet = new Set(disableRules)
-  const disableSkillsSet = new Set(disableSkills)
 
   const packageJsonExists = existsSync(join(root, 'package.json'))
   const npmDirExists = existsSync(join(root, 'npm'))
@@ -616,8 +610,6 @@ export async function detectAutoRulesAndSkills({
 
   /** @type {string[]} */
   const detectedRules = []
-  /** @type {string[]} */
-  const detectedSkills = []
 
   /**
    * Додає правило до результату, якщо воно доступне і не в disable-списку.
@@ -631,18 +623,6 @@ export async function detectAutoRulesAndSkills({
     detectedRules.push(ruleId)
   }
 
-  /**
-   * Додає skill до результату, якщо він доступний і не в disable-списку.
-   * @param {string} skillId id skill
-   * @returns {void}
-   */
-  function addSkill(skillId) {
-    if (!normalizedSkills.has(skillId) || disableSkillsSet.has(skillId) || detectedSkills.includes(skillId)) {
-      return
-    }
-    detectedSkills.push(skillId)
-  }
-
   const autoRuleChecks = [
     { enabled: isAbie, id: 'abie' },
     { enabled: packageJsonExists, id: 'bun' },
@@ -673,20 +653,8 @@ export async function detectAutoRulesAndSkills({
   }
   resolveRuleDependencies(detectedRules, addRule)
 
-  const autoSkillChecks = [
-    { enabled: isAbie, id: 'abie-kustomize' },
-    { enabled: true, id: 'fix' },
-    { enabled: true, id: 'lint' }
-  ]
-  for (const item of autoSkillChecks) {
-    if (item.enabled) {
-      addSkill(item.id)
-    }
-  }
-
   const rules = AUTO_RULE_ORDER.filter(ruleId => detectedRules.includes(ruleId))
-  const skills = AUTO_SKILL_ORDER.filter(skillId => detectedSkills.includes(skillId))
-  return { rules, skills }
+  return { rules }
 }
 
 /**

package/scripts/auto-skills.mjs

@@ -0,0 +1,78 @@
+/**
+ * Автовизначення skills для `.n-cursor.json` за умовами з `npm/bin/auto-skills.md`.
+ *
+ * Скіли автододаються залежно від уже виявлених правил (auto-rules) — щоб не дублювати
+ * умови, які вже формалізовані для відповідного правила. Наприклад:
+ *
+ * - `abie-kustomize - [abie]` — додається разом з правилом `abie`
+ * - `taze - [bun]` — додається разом з правилом `bun`
+ *
+ * Скіли без секції `[rules]` у `auto-skills.md` (`fix`, `lint`, `publish-telegram`)
+ * додаються завжди, якщо доступні в пакеті й не у `disable-skills`.
+ */
+
+/** Порядок автододавання skills відповідно до `auto-skills.md`. */
+export const AUTO_SKILL_ORDER = Object.freeze([
+  'abie-kustomize',
+  'fix',
+  'lint',
+  'publish-telegram',
+  'taze'
+])
+
+/**
+ * Залежність скілів від правил (`auto-skills.md` синтаксис `skill - [rules]`).
+ * Ключ варто автододати, коли всі правила-залежності вже додані до конфігу автодетектом.
+ */
+export const AUTO_SKILL_RULE_DEPENDENCIES = Object.freeze(
+  /** @type {Record<string, readonly string[]>} */ ({
+    'abie-kustomize': Object.freeze(['abie']),
+    taze: Object.freeze(['bun'])
+  })
+)
+
+/** Скіли без залежностей — додаються завжди (рядок «завжди» в `auto-skills.md`). */
+const ALWAYS_ON_SKILLS = Object.freeze(['fix', 'lint', 'publish-telegram'])
+
+const DEFAULT_DISABLED_LIST = Object.freeze([])
+
+/**
+ * Визначає авто-skills згідно з `auto-skills.md`.
+ * @param {object} params параметри
+ * @param {string[]} params.availableSkills перелік доступних skills із пакету (id без префікса n-)
+ * @param {string[]} params.detectedRules id правил, виявлених auto-rules (вхідні залежності)
+ * @param {string[]} [params.disableSkills] список `disable-skills` з конфігу
+ * @returns {{ skills: string[] }} список id у стабільному порядку (за `AUTO_SKILL_ORDER`)
+ */
+export function detectAutoSkills({ availableSkills, detectedRules, disableSkills = DEFAULT_DISABLED_LIST }) {
+  const normalizedSkills = new Set(availableSkills.map(s => s.trim().toLowerCase()))
+  const disableSkillsSet = new Set(disableSkills)
+  const detectedRulesSet = new Set(detectedRules)
+
+  /** @type {string[]} */
+  const detected = []
+
+  /**
+   * Додає skill до результату, якщо він доступний і не в disable-списку.
+   * @param {string} skillId id skill
+   * @returns {void}
+   */
+  function addSkill(skillId) {
+    if (!normalizedSkills.has(skillId) || disableSkillsSet.has(skillId) || detected.includes(skillId)) {
+      return
+    }
+    detected.push(skillId)
+  }
+
+  for (const skillId of ALWAYS_ON_SKILLS) {
+    addSkill(skillId)
+  }
+
+  for (const [skillId, deps] of Object.entries(AUTO_SKILL_RULE_DEPENDENCIES)) {
+    if (deps.every(d => detectedRulesSet.has(d))) {
+      addSkill(skillId)
+    }
+  }
+
+  return { skills: AUTO_SKILL_ORDER.filter(id => detected.includes(id)) }
+}

package/scripts/check-js-bun-db.mjs

@@ -30,6 +30,8 @@ import {
   findBunSqlPerRequestConnectionInText,
   findBunSqlPgLeftoverCallInText,
   findBunSqlUnsafeUseWithoutAllowMarkerInText,
+  findPgFormatLikeQueryWrapperInText,
+  findPgFormatShimDefinitionInText,
   findUnsafeBunSqlDynamicSqlListInText,
   findUnsafeBunSqlInListMissingEmptyGuardInText,
   isBunSqlScanSourceFile,
@@ -67,13 +69,21 @@ async function findAllSourcePathsForBunSqlScan(repoRoot, ignorePaths) {
  * @param {string[]} sourcePaths абсолютні шляхи джерел
  * @param {string} repoRoot абсолютний шлях до кореня
  * @param {{ pass: (m: string) => void, fail: (m: string) => void }} reporter колбеки pass і fail з перевірки
- * @returns {Promise<{ hasBunSqlImport: boolean, perRequest: number, unsafeCall: number, dynamicList: number }>}
+ * @returns {Promise<{ hasBunSqlImport: boolean, perRequest: number, unsafeCall: number, dynamicList: number, inListGuard: number, pgLeftover: number, pgFormatShim: number, queryWrapper: number }>}
  *   `hasBunSqlImport` — чи знайдено хоч один `import { sql|SQL } from 'bun'` у джерелах;
  *   решта — кількість порушень кожного типу.
  */
 async function scanSourcesForBunSqlPatterns(sourcePaths, repoRoot, reporter) {
   const { fail } = reporter
-  const counts = { perRequest: 0, unsafeCall: 0, dynamicList: 0, inListGuard: 0, pgLeftover: 0 }
+  const counts = {
+    perRequest: 0,
+    unsafeCall: 0,
+    dynamicList: 0,
+    inListGuard: 0,
+    pgLeftover: 0,
+    pgFormatShim: 0,
+    queryWrapper: 0
+  }
   let hasBunSqlImport = false
 
   for (const absPath of sourcePaths) {
@@ -93,7 +103,7 @@ async function scanSourcesForBunSqlPatterns(sourcePaths, repoRoot, reporter) {
  * @param {string} content вміст файлу
  * @param {string} rel posix-шлях відносно `repoRoot`
  * @param {(msg: string) => void} fail callback при помилці
- * @param {{ perRequest: number, unsafeCall: number, dynamicList: number, inListGuard: number, pgLeftover: number }} counts акумулятори
+ * @param {{ perRequest: number, unsafeCall: number, dynamicList: number, inListGuard: number, pgLeftover: number, pgFormatShim: number, queryWrapper: number }} counts акумулятори
  * @returns {void}
  */
 function scanFileForBunSqlPatterns(content, rel, fail, counts) {
@@ -134,6 +144,30 @@ function scanFileForBunSqlPatterns(content, rel, fail, counts) {
     counts.inListGuard++
     fail(messageForBunSqlInListGuard(rel, v))
   }
+  for (const v of findPgFormatShimDefinitionInText(content, rel)) {
+    counts.pgFormatShim++
+    if (v.kind === 'format_function') {
+      fail(
+        `js-bun-db: ${rel}:${v.line} — функція ${JSON.stringify(v.name)} виглядає як pg-format-сумісний шим ` +
+          `(тіло містить %L / %I / %s). Видали шим і переведи всі call-site на tagged template ` +
+          `sql\`...\${value}...\` (js-bun-db.mdc): ${v.snippet}`
+      )
+    } else {
+      fail(
+        `js-bun-db: ${rel}:${v.line} — ${JSON.stringify(v.name)} — це pg-format-специфічний escape-хелпер; ` +
+          `з Bun SQL він не потрібен (параметризація через tagged template), видали і перепиши call-site ` +
+          `(js-bun-db.mdc): ${v.snippet}`
+      )
+    }
+  }
+  for (const v of findPgFormatLikeQueryWrapperInText(content, rel)) {
+    counts.queryWrapper++
+    fail(
+      `js-bun-db: ${rel}:${v.line} — query(text, params)-обгортка над <obj>.unsafe(...) — це прихований ` +
+        `pg-сумісний шим. Видали обгортку (pgRead/pgWrite/db.query) і переведи всі call-site на tagged template ` +
+        `sql\`...\${value}...\` (js-bun-db.mdc): ${v.snippet}`
+    )
+  }
 }
 
 /**
@@ -194,7 +228,7 @@ export async function check() {
     return reporter.getExitCode()
   }
 
-  const { hasBunSqlImport, perRequest, unsafeCall, dynamicList, inListGuard, pgLeftover } =
+  const { hasBunSqlImport, perRequest, unsafeCall, dynamicList, inListGuard, pgLeftover, pgFormatShim, queryWrapper } =
     await scanSourcesForBunSqlPatterns(sourcePaths, repoRoot, reporter)
 
   if (!hasBunSqlImport) {
@@ -220,6 +254,12 @@ export async function check() {
   if (inListGuard === 0) {
     pass('js-bun-db: усі IN-списки винесені у змінні та мають перевірку на пустоту з throw')
   }
+  if (pgFormatShim === 0) {
+    pass('js-bun-db: немає pg-format-сумісних шимів (format/quoteLiteral/quoteIdent/...) у файлах з Bun SQL')
+  }
+  if (queryWrapper === 0) {
+    pass('js-bun-db: немає query(text, params)-обгорток над unsafe(...) у файлах з Bun SQL')
+  }
 
   return reporter.getExitCode()
 }

package/scripts/utils/bun-sql-scan.mjs

@@ -25,6 +25,7 @@ import {
   offsetToLine,
   parseProgramAndCommentsOrNull,
   parseProgramOrNull,
+  templateQuasisText,
   walkAstWithAncestors
 } from './ast-scan-utils.mjs'
 
@@ -43,6 +44,18 @@ const ALLOW_PG_LEFTOVER_MARKER_RE = /\ballow-pg-leftover\s*:\s*\S+/u
 // формально існують і там, тому опт-аут маркером лишається доречним.
 const PG_LEFTOVER_METHOD_NAMES = new Set(['connect', 'end'])
 
+// pg-format placeholders — `%L` (literal), `%I` (identifier), `%s` (raw string).
+// Якщо у тілі функції з підозрілим іменем зустрічається такий літерал/regex —
+// це pg-format-сумісний шим (drop-in замінник pg-format поверх Bun SQL).
+const PG_FORMAT_PLACEHOLDER_RE = /%[LIs]/u
+// Імена функцій-кандидатів на pg-format-шим. Спрацьовує лише у поєднанні
+// з наявністю `%L` / `%I` / `%s` у тілі — щоб не плутати з невинним `format(date)`.
+const PG_FORMAT_SHIM_FUNC_NAMES = new Set(['format', 'pgFormat', 'sqlFormat', 'pgFmt'])
+// Імена quote/escape-хелперів — самі по собі сильний сигнал pg-format-шиму,
+// без додаткової перевірки тіла. Це pg-format-специфічні API, нерідко публікуються
+// як named export з модуля-обгортки.
+const QUOTE_HELPER_NAMES = new Set(['quoteLiteral', 'quoteIdent', 'escapeLiteral', 'escapeIdent'])
+
 /**
  * @param {unknown} node AST node
  * @param {string} name імʼя змінної
@@ -267,6 +280,185 @@ function asPgLeftoverCall(node) {
   return { name: /** @type {'connect' | 'end'} */ (prop.name) }
 }
 
+/**
+ * Чи це CallExpression `<obj>.unsafe(...)` (для пошуку в тілі query-шиму).
+ * Дублює `isUnsafeCall` з основного скану, але локально — щоб не залежати
+ * від порядку оголошень у файлі.
+ * @param {unknown} node AST node
+ * @returns {boolean} true для `<obj>.unsafe(...)`
+ */
+function isUnsafeCallNode(node) {
+  if (!node || node.type !== 'CallExpression') return false
+  const callee = node.callee
+  if (!callee || callee.type !== 'MemberExpression' || callee.computed) return false
+  const prop = callee.property
+  return !!prop && prop.type === 'Identifier' && prop.name === 'unsafe'
+}
+
+/**
+ * Чи містить піддерево вузла рядковий або regex-літерал з `%L` / `%I` / `%s`.
+ * Покриває:
+ * - `Literal` зі строковим `value`,
+ * - `StringLiteral` (oxc),
+ * - `TemplateLiteral` (через текст quasis),
+ * - `RegExpLiteral` / `Literal` з `regex.pattern`.
+ * @param {unknown} root корінь піддерева (зазвичай тіло функції)
+ * @returns {boolean} true, якщо знайдено pg-format-плейсхолдер
+ */
+function nodeContainsPgFormatPlaceholder(root) {
+  let found = false
+  walkAstWithAncestors(root, [], n => {
+    if (found) return
+    const t = n.type
+    if (t === 'Literal' || t === 'StringLiteral') {
+      if (typeof n.value === 'string' && PG_FORMAT_PLACEHOLDER_RE.test(n.value)) {
+        found = true
+        return
+      }
+      const regex = n.regex
+      if (regex && typeof regex.pattern === 'string' && PG_FORMAT_PLACEHOLDER_RE.test(regex.pattern)) {
+        found = true
+        return
+      }
+    }
+    if (t === 'RegExpLiteral' && typeof n.pattern === 'string' && PG_FORMAT_PLACEHOLDER_RE.test(n.pattern)) {
+      found = true
+      return
+    }
+    if (t === 'TemplateLiteral') {
+      if (PG_FORMAT_PLACEHOLDER_RE.test(templateQuasisText(n))) {
+        found = true
+      }
+    }
+  })
+  return found
+}
+
+/**
+ * Витягає (name, body) з вузла, що оголошує функцію верхнього рівня:
+ * - `function format(...) {...}`,
+ * - `const format = (...) => {...}` / `= function(...) {...}`.
+ * @param {Record<string, unknown>} node AST node
+ * @returns {{ name: string, body: unknown } | null} ім'я та тіло, або null
+ */
+function asNamedFunctionDecl(node) {
+  if (node.type === 'FunctionDeclaration' && node.id?.type === 'Identifier') {
+    return { name: node.id.name, body: node.body }
+  }
+  if (node.type === 'VariableDeclarator' && node.id?.type === 'Identifier') {
+    const init = node.init
+    if (init && (init.type === 'ArrowFunctionExpression' || init.type === 'FunctionExpression')) {
+      return { name: node.id.name, body: init.body }
+    }
+  }
+  return null
+}
+
+/**
+ * Знаходить визначення pg-format-сумісних шимів у джерелі. Прапорує:
+ * - функції з іменами `format` / `pgFormat` / `sqlFormat` / `pgFmt`, у тілі яких
+ *   зустрічається літерал/regex з `%L` / `%I` / `%s` — це drop-in pg-format;
+ * - функції з іменами `quoteLiteral` / `quoteIdent` / `escapeLiteral` / `escapeIdent`
+ *   незалежно від тіла — це pg-format-специфічні API, не потрібні з Bun SQL.
+ *
+ * Скан запускається лише в файлах, де є `import { sql|SQL } from 'bun'`, щоб
+ * не плутати, наприклад, форматер дат чи URL-escape з SQL-шимом.
+ * @param {string} content вихідний код
+ * @param {string} [virtualPath] шлях для вибору `lang`
+ * @returns {{ line: number, snippet: string, kind: 'format_function' | 'quote_helper', name: string }[]} список порушень
+ */
+export function findPgFormatShimDefinitionInText(content, virtualPath = 'scan.ts') {
+  if (!textHasBunSqlImport(content)) return []
+  const program = parseProgramOrNull(content, virtualPath)
+  if (!program) return []
+
+  /** @type {{ line: number, snippet: string, kind: 'format_function' | 'quote_helper', name: string }[]} */
+  const out = []
+  walkAstWithAncestors(program, [], node => {
+    const decl = asNamedFunctionDecl(node)
+    if (!decl) return
+    /** @type {'format_function' | 'quote_helper' | null} */
+    let kind = null
+    if (QUOTE_HELPER_NAMES.has(decl.name)) {
+      kind = 'quote_helper'
+    } else if (PG_FORMAT_SHIM_FUNC_NAMES.has(decl.name) && nodeContainsPgFormatPlaceholder(decl.body)) {
+      kind = 'format_function'
+    }
+    if (!kind) return
+    out.push({
+      line: offsetToLine(content, node.start),
+      snippet: normalizeSnippet(content.slice(node.start, Math.min(node.end, node.start + 240))),
+      kind,
+      name: decl.name
+    })
+  })
+  return out
+}
+
+/**
+ * Знаходить pg-сумісні query-обгортки виду
+ * `{ query(text, params) { return <sql>.unsafe(text, params) } }`
+ * у файлах, що імпортують Bun SQL. Така обгортка маскує `unsafe` під
+ * «безпечним» ім'ям і повертає injection-поверхню в код.
+ *
+ * Спрацьовує, коли всі умови виконані:
+ * - вузол — `Property` з `key.name === 'query'` всередині `ObjectExpression`;
+ * - значення — функція з 1–2 параметрами, перший — Identifier з типовим
+ *   pg-іменем (`text` / `sql` / `query`);
+ * - у тілі функції є виклик `<obj>.unsafe(...)`.
+ *
+ * @param {string} content вихідний код
+ * @param {string} [virtualPath] шлях для вибору `lang`
+ * @returns {{ line: number, snippet: string }[]} список порушень
+ */
+export function findPgFormatLikeQueryWrapperInText(content, virtualPath = 'scan.ts') {
+  if (!textHasBunSqlImport(content)) return []
+  const program = parseProgramOrNull(content, virtualPath)
+  if (!program) return []
+
+  /** @type {{ line: number, snippet: string }[]} */
+  const out = []
+  walkAstWithAncestors(program, [], node => {
+    if (node.type !== 'ObjectExpression') return
+    const properties = node.properties
+    if (!Array.isArray(properties)) return
+    for (const prop of properties) {
+      if (!prop || prop.type !== 'Property') continue
+      const key = prop.key
+      const keyName =
+        key && key.type === 'Identifier' ? key.name : key && key.type === 'Literal' ? key.value : null
+      if (keyName !== 'query') continue
+      const value = prop.value
+      if (!value || (value.type !== 'FunctionExpression' && value.type !== 'ArrowFunctionExpression')) continue
+      const params = value.params
+      const firstName = Array.isArray(params) && params[0]?.type === 'Identifier' ? params[0].name : null
+      const looksLikePgQuery =
+        Array.isArray(params) && params.length >= 1 && params.length <= 2 && /^(text|sql|query)$/u.test(firstName || '')
+      if (!looksLikePgQuery) continue
+      if (!nodeContainsUnsafeCall(value.body)) continue
+      out.push({
+        line: offsetToLine(content, prop.start),
+        snippet: normalizeSnippet(content.slice(prop.start, prop.end))
+      })
+    }
+  })
+  return out
+}
+
+/**
+ * Чи є у піддереві виклик `<obj>.unsafe(...)`.
+ * @param {unknown} root корінь піддерева
+ * @returns {boolean} true, якщо знайдено
+ */
+function nodeContainsUnsafeCall(root) {
+  let found = false
+  walkAstWithAncestors(root, [], n => {
+    if (found) return
+    if (isUnsafeCallNode(n)) found = true
+  })
+  return found
+}
+
 /**
  * Знаходить `new SQL(...)` всередині функцій (handler на кожен запит замість singleton).
  * @param {string} content вихідний код

package/skills/taze/SKILL.md

@@ -0,0 +1,106 @@
+---
+name: n-taze
+description: >-
+  Оновлення версій модулів проекту з аналізом major-змін і автоматичним
+  рефакторингом несумісного коду
+---
+
+# n-taze — Оновлення версій проекту
+
+## Мета
+
+Оновити всі модулі проекту до останніх версій, виявити major-оновлення, перевірити сумісність змін з кодом проекту і за потреби зрефакторити несумісні місця.
+
+## Передумови
+
+- Чисте робоче дерево (`git status` без незакоммічених змін у `package.json` / `bun.lock` / `node_modules`) — інакше різницю не відрізнити від оновлення.
+- Встановлений `bun` і доступний `bunx`.
+- Запуск з кореня проекту (де лежить `package.json` / `bun.lock`).
+
+## Workflow
+
+### 1. Зафіксувати стартовий стан
+
+Перед оновленням зберегти список поточних версій, щоб потім обчислити, які модулі стрибнули через major:
+
+```bash
+cp package.json package.json.taze-bak
+cp bun.lock bun.lock.taze-bak
+```
+
+(У monorepo — також усі `*/package.json` воркспейсів. Файли тимчасові, видалити в кінці.)
+
+### 2. Запустити оновлення
+
+```bash
+bunx taze -w -r latest
+bun install
+```
+
+- `-w` — записати нові версії у `package.json`.
+- `-r` — рекурсивно по всіх воркспейсах.
+- `latest` — піднімати навіть major.
+
+### 3. Виявити major-оновлення
+
+Порівняти `package.json.taze-bak` з оновленим `package.json` (а також `bun.lock.taze-bak` ↔ `bun.lock` для транзитивних). Для кожної залежності, у якої змінилась перша значуща цифра semver (`1.x.x → 2.x.x`, `0.4.x → 0.5.x`, `0.0.x → 0.1.x`) — додати в список «потребує перевірки».
+
+Minor/patch — пропускати, їх вважаємо сумісними.
+
+### 4. Зібрати breaking changes по кожному major-оновленню
+
+Для кожного модуля зі списку зібрати фактичні відмінності одним з джерел (у порядку пріоритету):
+
+1. **CHANGELOG / Releases репозиторію модуля** — найшвидше і найточніше. Адресу репозиторію взяти з `package.json` модуля у `node_modules/<name>/package.json` (поле `repository`). Дістати релізи між старою і новою версією.
+2. **Git-різниця в `node_modules/<name>`** — якщо CHANGELOG відсутній або неінформативний, порівняти попередню версію (з кешу bun: `~/.bun/install/cache/<name>@<old-version>/`) з новою (`node_modules/<name>/`) через `diff -r` по `dist/` / `*.d.ts` / публічних entry-points з `exports`.
+3. **Якщо немає кешованої старої версії** — встановити її окремо в тимчасову теку (`mkdir -p /tmp/taze-old && cd /tmp/taze-old && bun add <name>@<old-version>`) і порівняти.
+
+Цікавлять: видалені/перейменовані експорти, змінені сигнатури функцій, змінені типи, змінена поведінка за замовчуванням, видалені CLI-прапорці.
+
+### 5. Перевірити сумісність з кодом проекту
+
+Для кожного breaking change знайти його використання в коді проекту:
+
+```bash
+rg -n "<імпорт|функція|опція>" --type ts --type js --type vue
+```
+
+Класифікувати:
+- **сумісно** — проект не використовує зачеплене API → нічого не робити.
+- **несумісно** — використання знайдено → перейти до п. 6.
+
+### 6. Рефакторинг несумісних місць
+
+Для кожного несумісного місця — застосувати міграцію згідно з changelog модуля (перейменувати імпорт, оновити сигнатуру виклику, замінити видалену опцію еквівалентом тощо). Після правок:
+
+```bash
+bun run lint
+bun run typecheck   # якщо є
+bun test            # якщо є
+```
+
+Якщо міграція нетривіальна або неоднозначна — **не вгадувати**, залишити TODO у коді з посиланням на CHANGELOG і винести в підсумковий звіт як ручну дію.
+
+### 7. Прибрати тимчасові файли
+
+```bash
+rm package.json.taze-bak bun.lock.taze-bak
+```
+
+(І решту бекапів воркспейсів, якщо створювались.)
+
+### 8. Звіт користувачу
+
+Коротко в одному повідомленні:
+
+- **Оновлено (minor/patch):** кількість пакетів, без деталей.
+- **Major-оновлення:** список `<name>: <old> → <new>` з посиланням на release notes.
+- **Зрефакторено автоматично:** список файлів і коротко що саме змінено.
+- **Потребує ручного втручання:** список TODO з причиною (нетривіальна міграція / неоднозначність / падіння тестів).
+- **Стан перевірок:** `lint` / `typecheck` / `test` — pass/fail з номером рядка, де впало.
+
+## Примітка
+
+- Не запускати `bun run lint` паралельно з іншими ESLint-задачами — діє правило з кореневого `CLAUDE.md`.
+- Якщо проект — `npm/` пакет цього репо, після змін у `package.json` / коді треба підняти `version` і додати запис у `CHANGELOG.md` згідно з `npm/CLAUDE.md`.
+- При великій кількості major-оновлень розбити PR по одному модулю на коміт — щоб `git bisect` залишався корисним.