@nitra/cursor 1.8.158 → 1.8.160

package/.claude-template/commands/n-check.md

@@ -0,0 +1,11 @@
+---
+description: >-
+  Запустити всі програмні перевірки правил (`npx @nitra/cursor check`)
+---
+
+# n-check
+
+Запусти `npx @nitra/cursor check` і пройдися по результатах.
+
+- Якщо є помилки — виправи відповідно до правила, на яке вказує перевірка.
+- Якщо все чисто — підтверди коротким повідомленням і переходь до наступного кроку.

package/.claude-template/npm-CLAUDE.md

@@ -0,0 +1,23 @@
+<!-- Файл генерується автоматично через `npx @nitra/cursor`. Не редагуй вручну. -->
+
+# Робота в `npm/`
+
+Path-scoped нагадування для агента: підвантажується автоматично, коли редагуємо файли під `npm/`.
+
+## Перед коміт-релевантними змінами в `npm/`
+
+1. Підвищ `version` у `npm/package.json` (build-bump, не більше одного кроку відносно `HEAD`).
+2. Додай запис у `npm/CHANGELOG.md` форматом Keep a Changelog: `## [версія] - YYYY-MM-DD` + секції `### Added/Changed/Fixed/Removed`.
+
+Без обох пунктів `npx @nitra/cursor check npm-module` падає, а `Stop` hook блокує завершення ходу.
+
+## Перевірка локально
+
+```bash
+npx @nitra/cursor check npm-module
+```
+
+## Джерело правил
+
+- `.cursor/rules/n-npm-module.mdc` — повний текст правила
+- `npm/scripts/check-npm-module.mjs` — алгоритм перевірки

package/.claude-template/settings.template.json

@@ -0,0 +1,26 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(bun *)",
+      "Bash(bun run *)",
+      "Bash(bun test *)",
+      "Bash(bunx *)",
+      "Bash(npx --no @nitra/cursor *)",
+      "Bash(npx @nitra/cursor *)"
+    ]
+  },
+  "hooks": {
+    "Stop": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "npx --no @nitra/cursor stop-hook",
+            "timeout": 60
+          }
+        ]
+      }
+    ]
+  }
+}

package/CHANGELOG.md

@@ -4,6 +4,29 @@
 
 Формат — [Keep a Changelog](https://keepachangelog.com/uk/1.1.0/), нумерація — [SemVer](https://semver.org/lang/uk/).
 
+## [1.8.160] - 2026-05-01
+
+### Changed
+
+- `js-bun-db.mdc` (v1.4): `sql.unsafe(...)` тепер заборонено за замовчуванням — допустимо лише для підстановки назви таблиці/колонки чи dynamic SQL/DDL з code-controlled значенням; інакше переробляємо на tagged template `sql\`...${value}...\``. Кожен легітимний виклик має супроводжуватись маркером `// allow-unsafe: <причина>` на тому ж рядку або рядком вище.
+- `check-js-bun-db.mjs`: замість вузької перевірки `sql.unsafe(\`...${expr}...\`)` тепер сканер `findBunSqlUnsafeUseWithoutAllowMarkerInText` падає на будь-якому `<obj>.unsafe(...)` без маркера-коментаря з непорожньою причиною (line- або block-коментар на тому ж рядку чи безпосередньо перед викликом).
+- `ast-scan-utils.mjs`: додано `parseProgramAndCommentsOrNull` — окремий вхід для перевірок, яким потрібні коментарі поряд з AST.
+
+## [1.8.159] - 2026-05-01
+
+### Added
+
+- Інтеграція з Claude Code: новий каталог `npm/.claude-template/` із `settings.template.json` (Stop hook + permissions allowlist), `npm-CLAUDE.md` (path-scoped нагадування для роботи в `npm/`) і slash-команду `/n-check`.
+- `sync-claude-config.mjs`: під час `npx @nitra/cursor` синхронізує `.claude/settings.json` (merge — користувацькі поля зберігаються, наші hooks ідентифікуються маркером і перезаписуються), `npm/CLAUDE.md` і slash-команди checks.
+- Subcommand `npx @nitra/cursor stop-hook` — точка входу Stop hook Claude Code (читає stdin, виходить 0 при `stop_hook_active=true` для захисту від рекурсії, інакше викликає `check`).
+- Поле `claude-config` у `.n-cursor.json` (default `true`) для опт-ауту.
+- Тести `npm/tests/sync-claude-config.test.mjs` — merge allow-list/hooks, інтеграція, ідемпотентність, опт-аут (12 кейсів).
+
+### Changed
+
+- `npm/schemas/n-cursor.json`: додано опис поля `claude-config`.
+- `npm/package.json`: `.claude-template` додано в масив `files`, щоб публікувався з пакетом.
+
 ## [1.8.158] - 2026-05-01
 
 ### Changed

package/bin/n-cursor.js

@@ -9,6 +9,13 @@
  *                                     якщо в корені вже є `.n-cursor.json`, спочатку зчитується конфіг і за потреби дописується `$schema`
  *   `npx \@nitra/cursor check bun`   — перевірити лише вказані правила (ігнорує AGENTS.md)
  *   `npx \@nitra/cursor rename-yaml-extensions` — k8s `*.yml` → `*.yaml`, `.github` `*.yaml` → `*.yml` (опції: `--dry-run`, `--root=…`; див. bin/rename-yaml-extensions.mjs)
+ *   `npx \@nitra/cursor stop-hook`   — точка входу Stop hook Claude Code (читає stdin, виходить 0 при `stop_hook_active`,
+ *                                     інакше викликає `check`); прописується автоматично в `.claude/settings.json`
+ *
+ * Claude Code інтеграція: під час синку, окрім `.cursor/rules` і `.claude/commands` (з skills), CLI ще раз
+ * синхронізує `.claude/settings.json` (hooks + permissions; merge — користувацькі поля зберігаються),
+ * `npm/CLAUDE.md` (path-scoped нагадування для роботи в `npm/`) і slash-команди checks (`/n-check`).
+ * Опт-аут — поле `claude-config: false` у `.n-cursor.json`.
  *
  * Якщо у корені репозиторію немає .n-cursor.json, спочатку перейменовується за наявності nitra-cursor.json;
  * у `.cursor/rules` файли `nitra-*.mdc` перейменовуються на `n-*.mdc`; інакше конфіг створюється автоматично
@@ -48,7 +55,9 @@ import { fileURLToPath } from 'node:url'
 
 import { buildAgentsCommandBulletItems } from '../scripts/build-agents-commands.mjs'
 import { detectAutoRulesAndSkills, mergeConfigWithAutoDetected, normalizeIdList } from '../scripts/auto-rules.mjs'
+import { runStopHookCli } from '../scripts/claude-stop-hook.mjs'
 import { ensureNitraCursorInRootDevDependencies } from '../scripts/ensure-nitra-cursor-dev-dependencies.mjs'
+import { syncClaudeConfig } from '../scripts/sync-claude-config.mjs'
 import { upgradeNitraCursorToLatestAndBunInstall } from '../scripts/upgrade-nitra-cursor-and-install.mjs'
 import { runRenameYamlExtensionsCli } from './rename-yaml-extensions.mjs'
 import { syncSetupBunDepsAction } from '../scripts/sync-setup-bun-deps-action.mjs'
@@ -1097,6 +1106,7 @@ async function runSync() {
   const config = await runSyncStep('❌ ', () => readConfig({ bundledMdcDir, bundledSkillsDir }))
 
   const { rules, skills, version, ignore } = config
+  const claudeConfigEnabled = config['claude-config'] !== false
   const bundledVer = await readBundledVersionAt(effectivePackageRoot)
   if (bundledVer) {
     const line =
@@ -1160,6 +1170,25 @@ async function runSync() {
     syncClaudeMd(/** @type {string[] | undefined} */ (ignore))
   )
 
+  await runSyncStep('❌ Не вдалося синхронізувати Claude-конфіг: ', async () => {
+    const result = await syncClaudeConfig({
+      projectRoot: cwd(),
+      bundledPackageRoot: effectivePackageRoot,
+      enabled: claudeConfigEnabled
+    })
+    if (!claudeConfigEnabled) {
+      console.log('🤖 Claude-конфіг: пропущено (claude-config: false у .n-cursor.json)')
+      return
+    }
+    const parts = []
+    if (result.settings) parts.push('.claude/settings.json')
+    if (result.npmClaudeMd) parts.push('npm/CLAUDE.md')
+    if (result.commands.length > 0) parts.push(`${result.commands.length} slash-commands`)
+    if (parts.length > 0) {
+      console.log(`🤖 Claude-конфіг: ${parts.join(', ')}`)
+    }
+  })
+
   console.log(`\n✨ Готово: ${successCount} завантажено, ${failCount} з помилками\n`)
   if (failCount > 0) {
     throw new Error(`Не вдалося завантажити ${failCount} з ${rules.length} правил`)
@@ -1185,6 +1214,14 @@ try {
 
       break
     }
+    case 'stop-hook': {
+      // Викликається з .claude/settings.json як Stop hook Claude Code.
+      // Прокидає `check` і поважає stop_hook_active, щоб не зациклюватись.
+      const code = await runStopHookCli()
+      process.exitCode = code
+
+      break
+    }
     case undefined:
     case '': {
       await runSync()
@@ -1193,7 +1230,9 @@ try {
     }
     default: {
       console.error(`❌ Невідома команда: ${command}`)
-      console.error(`   Очікується: (без аргументів) синхронізація правил, check, rename-yaml-extensions`)
+      console.error(
+        `   Очікується: (без аргументів) синхронізація правил, check, rename-yaml-extensions, stop-hook`
+      )
       process.exitCode = 1
     }
   }

package/mdc/js-bun-db.mdc

@@ -1,7 +1,7 @@
 ---
 description: Використання pg / mysql2 / Bun SQL у Node.js та Bun
 alwaysApply: true
-version: '1.3'
+version: '1.4'
 ---
 
 ## Підтримувані версії баз даних
@@ -116,22 +116,43 @@ await sql.begin(async tx => {
 await sql`SELECT * FROM users WHERE id IN ${sql(ids)}`
 ```
 
-## Що НЕ робити
+## `sql.unsafe(...)` за замовчуванням заборонено
+
+Будь-який виклик `sql.unsafe(...)` (так само `tx.unsafe(...)` всередині `sql.begin`) **заборонено**, окрім випадків, коли **обидві** умови виконані:
+
+1. значення підставляється з **коду** — константа, конфіг, whitelist; **не з user input**;
+2. треба підставити те, що **не можна параметризувати** через tagged template:
+   - назву **таблиці**,
+   - назву **колонки**,
+   - **dynamic SQL / DDL** (`CREATE`, `ALTER`, `DROP`, multi-statement migration, серверні `SET`/`SHOW` і подібне).
+
+В усіх інших випадках — переробити на звичайний tagged template `sql\`...\${value}...\``: значення біндяться як параметри й injection не лишається.
 
-### Не використовувати `sql.unsafe(...)` з конкатенацією
+Кожен легітимний `sql.unsafe(...)` має супроводжуватись **маркером-коментарем** з причиною — на тому ж рядку (trailing) або на рядку безпосередньо перед викликом. Маркер — opt-in для перевірки `js-bun-db` і слід для ревʼюера:
 
 ```javascript
-// ❌ конкатенація даних у SQL — SQL injection
+// allow-unsafe: DDL — назву таблиці параметризувати не можна
+await sql.unsafe(`CREATE TABLE ${tableName} (id int)`)
+
+await sql.unsafe('SELECT pg_advisory_lock($1)', [lockId]) // allow-unsafe: pg_advisory_lock — окремий шлях, без tagged template
+```
+
+Формат маркера: `allow-unsafe: <непорожня причина>` у line- або block-коментарі. Без причини (`// allow-unsafe:`) і без маркера взагалі — **fail** перевірки.
+
+❌ Заборонені кейси (треба переробити на tagged template):
+
+```javascript
+// ❌ дані від користувача — параметризуй через tagged template
 await sql.unsafe(`SELECT * FROM users WHERE id = ${userId}`)
 
 // ❌ навіть у tagged template — динамічний список через .join(',')
 await sql`SELECT * FROM users WHERE id IN (${ids.join(',')})`
 ```
 
-`sql.unsafe(text, params)` допустимий лише для **статичного** SQL без даних від користувача (наприклад, разовий DDL-скрипт), і обов'язково з масивом параметрів — ніяких `${...}` у самому рядку.
-
 Для динамічних списків — `sql([...])` або `sql(rows, 'colA', 'colB')`, **не** `.join(',')`.
 
+## Що НЕ робити
+
 ### Не створювати підключення на кожен запит
 
 ```javascript

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nitra/cursor",
-  "version": "1.8.158",
+  "version": "1.8.160",
   "description": "CLI для завантаження cursor-правил (префікс n-) у локальний репозиторій",
   "keywords": [
     "cli",
@@ -30,6 +30,7 @@
     "schemas",
     "scripts",
     "skills",
+    ".claude-template",
     "AGENTS.template.md",
     "CHANGELOG.md"
   ],

package/schemas/n-cursor.json

@@ -54,6 +54,11 @@
     "version": {
       "type": "string",
       "description": "Застаріле поле, ігнорується CLI. Правила завжди копіюються з каталогу mdc/ установленого пакету (node_modules або кеш npx); змініть версію через оновлення залежності."
+    },
+    "claude-config": {
+      "type": "boolean",
+      "description": "Чи синхронізувати `.claude/settings.json` (hooks + permissions, merge зі збереженням користувацьких полів), `npm/CLAUDE.md` (path-scoped нагадування для роботи в `npm/`) і slash-команди checks. За замовчуванням true.",
+      "default": true
     }
   },
   "required": ["rules"]

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

@@ -10,7 +10,11 @@
  * 2) Якщо в коді використовується Bun SQL (імпорт `sql`/`SQL` з `'bun'`), додатково
  *    перевіряє небезпечні патерни:
  *    - `new SQL(...)` всередині функції (пул має бути singleton на рівні модуля).
- *    - `sql.unsafe(\`...${expr}...\`)` (інтерполяція даних у `unsafe` ламає параметризацію).
+ *    - Будь-який `<obj>.unsafe(...)` без маркера-коментаря `// allow-unsafe: <reason>`
+ *      на тому ж рядку або рядком вище. `sql.unsafe` за замовчуванням заборонено;
+ *      допустимий лише для підстановки назви таблиці/колонки чи dynamic SQL/DDL,
+ *      коли значення контролюється кодом (не user input) — в інших випадках
+ *      переробляємо на tagged template `sql\`...\${value}...\``.
  *    - Динамічні SQL-списки через `.join(',')` у `IN (...)` / `VALUES (...)`
  *      (треба `sql([...])`).
  */
@@ -21,9 +25,9 @@ import { join, relative, sep } from 'node:path'
 import { createCheckReporter } from './utils/check-reporter.mjs'
 import {
   findBunSqlPerRequestConnectionInText,
+  findBunSqlUnsafeUseWithoutAllowMarkerInText,
   findUnsafeBunSqlDynamicSqlListInText,
   findUnsafeBunSqlInListMissingEmptyGuardInText,
-  findUnsafeBunSqlUnsafeCallInText,
   isBunSqlScanSourceFile,
   textHasBunSqlImport
 } from './utils/bun-sql-scan.mjs'
@@ -155,11 +159,14 @@ function scanFileForBunSqlPatterns(content, rel, fail, counts) {
         `тримай singleton на рівні модуля (js-bun-db.mdc): ${v.snippet}`
     )
   }
-  for (const v of findUnsafeBunSqlUnsafeCallInText(content, rel)) {
+  for (const v of findBunSqlUnsafeUseWithoutAllowMarkerInText(content, rel)) {
     counts.unsafeCall++
     fail(
-      `js-bun-db: ${rel}:${v.line} — sql.unsafe(\`...\${...}...\`) недопустимо: ` +
-        `використовуй tagged template sql\`...\${value}...\` або sql.unsafe('static', [params]) (js-bun-db.mdc): ${v.snippet}`
+      `js-bun-db: ${rel}:${v.line} — sql.unsafe(...) заборонено за замовчуванням; ` +
+        `допустимо лише для підстановки назви таблиці/колонки чи dynamic SQL/DDL з code-controlled значенням, ` +
+        `інакше переробити на tagged template sql\`...\${value}...\`. ` +
+        `Якщо випадок легітимний — додай маркер "// allow-unsafe: <причина>" на тому ж рядку або рядком вище ` +
+        `(js-bun-db.mdc): ${v.snippet}`
     )
   }
   for (const v of findUnsafeBunSqlDynamicSqlListInText(content, rel)) {
@@ -245,7 +252,7 @@ export async function check() {
     pass('js-bun-db: немає створення new SQL(...) всередині функцій (singleton на рівні модуля)')
   }
   if (unsafeCall === 0) {
-    pass('js-bun-db: немає небезпечних викликів sql.unsafe з інтерполяцією в шаблонному рядку')
+    pass('js-bun-db: усі sql.unsafe(...) або відсутні, або супроводжуються маркером "// allow-unsafe: <причина>"')
   }
   if (dynamicList === 0) {
     pass("js-bun-db: немає небезпечних динамічних SQL-списків через .join(',') у IN/VALUES")

package/scripts/claude-stop-hook.mjs

@@ -0,0 +1,71 @@
+/**
+ * Stop-hook для Claude Code: запускається hook'ом із `.claude/settings.json` після того,
+ * як агент сигналізує завершення ходу. Прозоро прокидає `npx @nitra/cursor check`
+ * і повертає його exit code, щоб помилки правил блокували завершення.
+ *
+ * Захист від нескінченної рекурсії: якщо stdin містить `"stop_hook_active": true`
+ * (Claude Code позначає цей прапорець, коли hook сам спричинив повторний Stop),
+ * виходимо з кодом 0 без повторного запуску перевірок.
+ *
+ * Виклик з `bin/n-cursor.js`:
+ *   `npx --no @nitra/cursor stop-hook`
+ */
+import { spawn } from 'node:child_process'
+
+/**
+ * Зчитує stdin до EOF як utf8 рядок. Якщо stdin порожній (TTY) — повертає '' одразу.
+ * @returns {Promise<string>} вміст stdin
+ */
+function readStdin() {
+  return new Promise(resolve => {
+    if (process.stdin.isTTY) {
+      resolve('')
+      return
+    }
+    let data = ''
+    process.stdin.setEncoding('utf8')
+    process.stdin.on('data', chunk => {
+      data += chunk
+    })
+    process.stdin.on('end', () => resolve(data))
+    process.stdin.on('error', () => resolve(data))
+  })
+}
+
+/**
+ * Чи stdin вказує, що поточний Stop вже виник через попередній Stop hook
+ * (Claude Code передає `stop_hook_active: true`). У такому випадку повторний
+ * запуск перевірок створив би нескінченний цикл — пропускаємо.
+ * @param {string} stdin сирий вміст stdin
+ * @returns {boolean} true, якщо рекурсивний виклик
+ */
+export function isRecursiveStopHookCall(stdin) {
+  if (!stdin) {
+    return false
+  }
+  try {
+    const obj = JSON.parse(stdin)
+    return obj?.stop_hook_active === true
+  } catch {
+    return false
+  }
+}
+
+/**
+ * Точка входу. Викликається з `bin/n-cursor.js` коли argv[0] === 'stop-hook'.
+ * @returns {Promise<number>} exit code (0 — OK / пропуск, 1 — помилки правил)
+ */
+export async function runStopHookCli() {
+  const stdin = await readStdin()
+  if (isRecursiveStopHookCall(stdin)) {
+    return 0
+  }
+  return new Promise(resolve => {
+    const child = spawn('npx', ['--no', '@nitra/cursor', 'check'], { stdio: 'inherit' })
+    child.on('exit', code => resolve(code ?? 1))
+    child.on('error', err => {
+      process.stderr.write(`stop-hook: не вдалося запустити npx @nitra/cursor check — ${err.message}\n`)
+      resolve(1)
+    })
+  })
+}

package/scripts/sync-claude-config.mjs

@@ -0,0 +1,232 @@
+/**
+ * Синхронізує конфігурацію Claude Code (`.claude/settings.json`, `npm/CLAUDE.md`,
+ * slash-команди для checks) у поточний проєкт із темплейтів пакету
+ * `npm/.claude-template/`.
+ *
+ * Архітектура:
+ * - `settings.json` — **merge**: користувацькі поля зберігаються; наші hooks
+ *   ідентифікуються командою-маркером (`MANAGED_HOOK_COMMAND_MARKER`) і
+ *   перезаписуються; permissions.allow зливається через union (із дедублікацією).
+ * - `npm/CLAUDE.md` — **fully owned**: завжди перезаписується; пропускається,
+ *   якщо в проєкті немає каталогу `npm/`.
+ * - `.claude/commands/n-check.md` — fully owned slash-команда.
+ *
+ * Опт-аут — `claude-config: false` у `.n-cursor.json`.
+ */
+import { existsSync } from 'node:fs'
+import { mkdir, readFile, readdir, writeFile } from 'node:fs/promises'
+import { join } from 'node:path'
+
+/** Маркер у command нашого managed-hook'а — за ним відрізняємо свої записи від користувацьких */
+export const MANAGED_HOOK_COMMAND_MARKER = '@nitra/cursor stop-hook'
+
+const CLAUDE_DIR = '.claude'
+const CLAUDE_SETTINGS_FILE = `${CLAUDE_DIR}/settings.json`
+const CLAUDE_COMMANDS_DIR = `${CLAUDE_DIR}/commands`
+const NPM_CLAUDE_MD_FILE = 'npm/CLAUDE.md'
+const TEMPLATE_DIR_NAME = '.claude-template'
+
+/**
+ * @typedef {object} HookEntry
+ * @property {string} type
+ * @property {string} command
+ * @property {number} [timeout]
+ */
+
+/**
+ * @typedef {object} HookGroup
+ * @property {string} [matcher]
+ * @property {HookEntry[]} hooks
+ */
+
+/**
+ * @typedef {object} ClaudeSettings
+ * @property {{ allow?: string[] }} [permissions]
+ * @property {Record<string, HookGroup[]>} [hooks]
+ */
+
+/**
+ * Чи hook-група містить лише наші managed-команди (за маркером).
+ * @param {HookGroup} group
+ * @returns {boolean}
+ */
+function isManagedHookGroup(group) {
+  if (!group?.hooks?.length) {
+    return false
+  }
+  return group.hooks.every(h => typeof h?.command === 'string' && h.command.includes(MANAGED_HOOK_COMMAND_MARKER))
+}
+
+/**
+ * Зливає список allow-permissions: union існуючого і темплейтного без дублікатів,
+ * порядок — спочатку існуючі (щоб не міняти користувацький порядок), потім нові.
+ * @param {string[] | undefined} existing
+ * @param {string[] | undefined} fromTemplate
+ * @returns {string[]}
+ */
+export function mergeAllowList(existing, fromTemplate) {
+  const out = []
+  const seen = new Set()
+  for (const arr of [existing ?? [], fromTemplate ?? []]) {
+    for (const item of arr) {
+      if (typeof item !== 'string' || seen.has(item)) {
+        continue
+      }
+      seen.add(item)
+      out.push(item)
+    }
+  }
+  return out
+}
+
+/**
+ * Зливає hooks-секцію: для кожної події в темплейті видаляємо managed-групи
+ * з існуючої конфігурації і додаємо актуальні з темплейту. Немені події в
+ * темплейті не чіпаються.
+ * @param {Record<string, HookGroup[]> | undefined} existing
+ * @param {Record<string, HookGroup[]> | undefined} fromTemplate
+ * @returns {Record<string, HookGroup[]>}
+ */
+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() : []
+  }
+  for (const [event, templateGroups] of Object.entries(fromTemplate ?? {})) {
+    const existingGroups = (out[event] ?? []).filter(g => !isManagedHookGroup(g))
+    out[event] = [...existingGroups, ...(templateGroups ?? [])]
+    if (out[event].length === 0) {
+      delete out[event]
+    }
+  }
+  return out
+}
+
+/**
+ * Повертає об'єднаний об'єкт settings.json.
+ * @param {ClaudeSettings | undefined} existing
+ * @param {ClaudeSettings} template
+ * @returns {ClaudeSettings}
+ */
+export function mergeSettings(existing, template) {
+  /** @type {ClaudeSettings} */
+  const merged = { ...(existing ?? {}) }
+  const mergedAllow = mergeAllowList(existing?.permissions?.allow, template.permissions?.allow)
+  if (mergedAllow.length > 0) {
+    merged.permissions = { ...(existing?.permissions ?? {}), allow: mergedAllow }
+  }
+  const mergedHooks = mergeHooks(existing?.hooks, template.hooks)
+  if (Object.keys(mergedHooks).length > 0) {
+    merged.hooks = mergedHooks
+  } else {
+    delete merged.hooks
+  }
+  return merged
+}
+
+/**
+ * Читає JSON-файл; якщо файл відсутній або не валідний — повертає `undefined`.
+ * @param {string} path
+ * @returns {Promise<ClaudeSettings | undefined>}
+ */
+async function readJsonOrUndefined(path) {
+  if (!existsSync(path)) {
+    return undefined
+  }
+  try {
+    return JSON.parse(await readFile(path, 'utf8'))
+  } catch {
+    return undefined
+  }
+}
+
+/**
+ * Синхронізує `.claude/settings.json` за темплейтом, зберігаючи решту
+ * користувацьких полів.
+ * @param {string} projectRoot корінь проєкту, куди писати
+ * @param {string} templateDir каталог `.claude-template/` усередині пакету
+ * @returns {Promise<{ written: boolean, path: string }>}
+ */
+export async function syncClaudeSettings(projectRoot, templateDir) {
+  const templatePath = join(templateDir, 'settings.template.json')
+  if (!existsSync(templatePath)) {
+    return { written: false, path: '' }
+  }
+  const template = /** @type {ClaudeSettings} */ (JSON.parse(await readFile(templatePath, 'utf8')))
+  const settingsPath = join(projectRoot, CLAUDE_SETTINGS_FILE)
+  const existing = await readJsonOrUndefined(settingsPath)
+  const merged = mergeSettings(existing, template)
+  await mkdir(join(projectRoot, CLAUDE_DIR), { recursive: true })
+  await writeFile(settingsPath, `${JSON.stringify(merged, null, 2)}\n`, 'utf8')
+  return { written: true, path: CLAUDE_SETTINGS_FILE }
+}
+
+/**
+ * Копіює `npm/CLAUDE.md` з темплейту, якщо в проєкті є каталог `npm/`.
+ * @param {string} projectRoot
+ * @param {string} templateDir
+ * @returns {Promise<{ written: boolean, path: string }>}
+ */
+export async function syncNpmClaudeMd(projectRoot, templateDir) {
+  if (!existsSync(join(projectRoot, 'npm'))) {
+    return { written: false, path: '' }
+  }
+  const templatePath = join(templateDir, 'npm-CLAUDE.md')
+  if (!existsSync(templatePath)) {
+    return { written: false, path: '' }
+  }
+  const content = await readFile(templatePath, 'utf8')
+  await writeFile(join(projectRoot, NPM_CLAUDE_MD_FILE), content, 'utf8')
+  return { written: true, path: NPM_CLAUDE_MD_FILE }
+}
+
+/**
+ * Копіює всі slash-команди з `templateDir/commands/` у `.claude/commands/`.
+ * Команди ідентифікуються тим, що вони лежать у темплейті — не перетинаються
+ * з командами скілів (n-fix, n-lint, ...).
+ * @param {string} projectRoot
+ * @param {string} templateDir
+ * @returns {Promise<string[]>} масив відносних шляхів записаних файлів
+ */
+export async function syncClaudeCommands(projectRoot, templateDir) {
+  const commandsTemplateDir = join(templateDir, 'commands')
+  if (!existsSync(commandsTemplateDir)) {
+    return []
+  }
+  const targetDir = join(projectRoot, CLAUDE_COMMANDS_DIR)
+  await mkdir(targetDir, { recursive: true })
+  const written = []
+  for (const name of await readdir(commandsTemplateDir)) {
+    if (!name.endsWith('.md')) {
+      continue
+    }
+    const content = await readFile(join(commandsTemplateDir, name), 'utf8')
+    await writeFile(join(targetDir, name), content, 'utf8')
+    written.push(`${CLAUDE_COMMANDS_DIR}/${name}`)
+  }
+  return written
+}
+
+/**
+ * Виконує повну синхронізацію Claude Code-конфігу з темплейту пакету в проєкт.
+ * Використовується з `bin/n-cursor.js` після інших синків.
+ * @param {object} options
+ * @param {string} options.projectRoot корінь проєкту-споживача
+ * @param {string} options.bundledPackageRoot корінь установленого `@nitra/cursor`
+ * @param {boolean} options.enabled чи увімкнено sync (з `.n-cursor.json` `claude-config`)
+ * @returns {Promise<{ settings: boolean, npmClaudeMd: boolean, commands: string[] }>}
+ */
+export async function syncClaudeConfig({ projectRoot, bundledPackageRoot, enabled }) {
+  if (!enabled) {
+    return { settings: false, npmClaudeMd: false, commands: [] }
+  }
+  const templateDir = join(bundledPackageRoot, TEMPLATE_DIR_NAME)
+  if (!existsSync(templateDir)) {
+    return { settings: false, npmClaudeMd: false, commands: [] }
+  }
+  const settings = await syncClaudeSettings(projectRoot, templateDir)
+  const npmClaudeMd = await syncNpmClaudeMd(projectRoot, templateDir)
+  const commands = await syncClaudeCommands(projectRoot, templateDir)
+  return { settings: settings.written, npmClaudeMd: npmClaudeMd.written, commands }
+}

package/scripts/utils/ast-scan-utils.mjs

@@ -112,6 +112,29 @@ export function parseProgramOrNull(content, virtualPath) {
   return result.program
 }
 
+/**
+ * Парсить файл і повертає `{ program, comments }` або null. Окремий вхід для перевірок,
+ * яким потрібні коментарі (наприклад, маркер `// allow-unsafe: ...` біля виклику) —
+ * базовий `parseProgramOrNull` свідомо лишається без коментарів, щоб не змінювати API.
+ * @param {string} content вихідний код
+ * @param {string} virtualPath шлях для вибору `lang` (також для діагностики)
+ * @returns {{ program: unknown, comments: { type: 'Line' | 'Block', value: string, start: number, end: number }[] } | null}
+ */
+export function parseProgramAndCommentsOrNull(content, virtualPath) {
+  const lang = langFromPath(virtualPath || 'scan.ts')
+  let result
+  try {
+    result = parseSync(virtualPath || 'scan.ts', content, { lang, sourceType: 'module' })
+  } catch {
+    return null
+  }
+  if (result.errors?.length) return null
+  return {
+    program: result.program,
+    comments: Array.isArray(result.comments) ? result.comments : []
+  }
+}
+
 /**
  * Чи це `.join(...)` виклик (типово для динамічних списків у SQL).
  * @param {unknown} node AST node

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

@@ -4,9 +4,11 @@
  * Знаходить:
  * - `new SQL(...)` всередині функції — пул має бути singleton на рівні модуля,
  *   а не на кожен виклик handler-а.
- * - Виклик `sql.unsafe(\`...${expr}...\`)` з даними у TemplateLiteral —
- *   `sql.unsafe` приймає лише статичний SQL (плюс масив параметрів); інтерполяція
- *   у текст руйнує параметризацію і відкриває SQL injection.
+ * - Будь-який виклик `<obj>.unsafe(...)` без маркера-коментаря `// allow-unsafe: <reason>`
+ *   на тому ж рядку або рядком вище. `sql.unsafe` за замовчуванням заборонено: дозволено
+ *   тільки якщо значення контролюється кодом (не user input) і потрібно підставити
+ *   назву таблиці/колонки або dynamic SQL/DDL. Інакше — переробити на tagged template
+ *   `sql\`...\${value}...\``. Маркер фіксує цю причину для ревʼюера.
  * - Динамічні SQL-списки у tagged template `sql\`... IN (${arr.join(',')}) ...\``:
  *   навіть «через tagged template» у запит потрапляє готовий шматок SQL замість
  *   параметризованих значень — треба `sql([...])`.
@@ -21,6 +23,7 @@ import {
   isSqlListContextTemplate,
   normalizeSnippet,
   offsetToLine,
+  parseProgramAndCommentsOrNull,
   parseProgramOrNull,
   walkAstWithAncestors
 } from './ast-scan-utils.mjs'
@@ -28,6 +31,9 @@ import {
 const SOURCE_FILE_RE = /\.([cm]?[jt]sx?)$/u
 const BUN_SQL_IMPORT_RE = /\bimport\s*\{[\s\S]*?\b(sql|SQL)\b[\s\S]*?\}\s*from\s*["']bun["']/u
 const IN_PLACEHOLDER_END_RE = /\bin\s*(\(\s*)?$/iu
+// `// allow-unsafe: <reason>` — `allow-unsafe`, двокрапка, **непорожня** причина.
+// Без причини маркер не приймається: ціль — лишити слід для ревʼюера, а не «німий» прапорець.
+const ALLOW_UNSAFE_MARKER_RE = /\ballow-unsafe\s*:\s*\S+/u
 
 /**
  * @param {unknown} node AST node
@@ -192,23 +198,46 @@ function isNewSqlConstructor(node) {
 }
 
 /**
- * Чи це виклик `<obj>.unsafe(...)` з TemplateLiteral як першим аргументом і expressions усередині нього.
- * Допустимий лише `sql.unsafe('static text', [params])`; з `${...}` у TemplateLiteral — небезпечно.
+ * Чи це виклик `<obj>.unsafe(...)` (будь-який обʼєкт, не тільки `sql`).
+ * Файл сканується лише якщо є `import { sql|SQL } from 'bun'`, тож у практиці це
+ * або `sql.unsafe`, або `tx.unsafe` всередині `sql.begin(async tx => ...)` —
+ * обидва однаково небезпечні, тому розрізняти імʼя обʼєкта не треба.
  * @param {unknown} node AST node
- * @returns {boolean} true для небезпечного `sql.unsafe(\`... ${x} ...\`)`
+ * @returns {boolean} true для будь-якого `<obj>.unsafe(...)`
  */
-function isUnsafeCallWithInterpolatedTemplate(node) {
+function isUnsafeCall(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
-  if (!prop || prop.type !== 'Identifier' || prop.name !== 'unsafe') return false
-  const args = node.arguments
-  if (!Array.isArray(args) || args.length === 0) return false
-  const first = args[0]
-  if (!first || first.type !== 'TemplateLiteral') return false
-  const expressions = first.expressions
-  return Array.isArray(expressions) && expressions.length > 0
+  return !!prop && prop.type === 'Identifier' && prop.name === 'unsafe'
+}
+
+/**
+ * Чи є біля виклику `<obj>.unsafe(...)` маркер-коментар `// allow-unsafe: <reason>`
+ * (або `/* allow-unsafe: <reason> *\/`) на тому ж рядку, що й початок виклику,
+ * або на рядку, що передує початку виклику. Це навмисно строга суміжність:
+ * відірваний коментар через порожній рядок не зараховується — щоб маркер
+ * стояв саме біля виклику, а не «загубився десь вище».
+ * @param {{ start: number }} callNode виклик `<obj>.unsafe(...)`
+ * @param {{ type: 'Line' | 'Block', value: string, start: number, end: number }[]} comments коментарі з парсера
+ * @param {string} content вихідний код
+ * @returns {boolean} true, якщо маркер знайдено
+ */
+function hasAllowUnsafeMarkerNear(callNode, comments, content) {
+  const callStartLine = offsetToLine(content, callNode.start)
+  for (const c of comments) {
+    if (!c || (c.type !== 'Line' && c.type !== 'Block')) continue
+    if (typeof c.value !== 'string' || !ALLOW_UNSAFE_MARKER_RE.test(c.value)) continue
+    const startLine = offsetToLine(content, c.start)
+    const endLine = offsetToLine(content, c.end)
+    // trailing-коментар на тому ж рядку (`sql.unsafe(...) // allow-unsafe: ...`)
+    if (startLine === callStartLine) return true
+    // коментар на рядку, що безпосередньо передує виклику — для блокових
+    // коментарів важливим є саме `endLine`, бо block може займати кілька рядків.
+    if (endLine === callStartLine - 1) return true
+  }
+  return false
 }
 
 /**
@@ -236,19 +265,28 @@ export function findBunSqlPerRequestConnectionInText(content, virtualPath = 'sca
 }
 
 /**
- * Знаходить виклики `sql.unsafe(\`...${...}...\`)` (TemplateLiteral з expressions).
+ * Знаходить виклики `<obj>.unsafe(...)` без маркера-коментаря `// allow-unsafe: <reason>`
+ * на тому ж рядку або рядком вище. `sql.unsafe` за замовчуванням заборонено: дозволено
+ * лише коли значення контролюється кодом (не user input) і потрібно підставити те, що
+ * не можна параметризувати — назву таблиці/колонки або dynamic SQL/DDL. У всіх інших
+ * випадках — переробити на tagged template `sql\`...\${value}...\``.
+ *
+ * Маркер-коментар фіксує причину для ревʼюера й одночасно слугує opt-in: без нього
+ * перевірка падає, навіть якщо у `unsafe` лежить статичний рядок без інтерполяції.
  * @param {string} content вихідний код
  * @param {string} [virtualPath] шлях для вибору `lang`
  * @returns {{ line: number, snippet: string }[]} список порушень
  */
-export function findUnsafeBunSqlUnsafeCallInText(content, virtualPath = 'scan.ts') {
-  const program = parseProgramOrNull(content, virtualPath)
-  if (!program) return []
+export function findBunSqlUnsafeUseWithoutAllowMarkerInText(content, virtualPath = 'scan.ts') {
+  const parsed = parseProgramAndCommentsOrNull(content, virtualPath)
+  if (!parsed) return []
+  const { program, comments } = parsed
 
   /** @type {{ line: number, snippet: string }[]} */
   const out = []
   walkAstWithAncestors(program, [], node => {
-    if (!isUnsafeCallWithInterpolatedTemplate(node)) return
+    if (!isUnsafeCall(node)) return
+    if (hasAllowUnsafeMarkerNear(node, comments, content)) return
     out.push({
       line: offsetToLine(content, node.start),
       snippet: normalizeSnippet(content.slice(node.start, node.end))

package/scripts/utils/oxlint-canonical-skeleton.json

@@ -1,6 +1,6 @@
 {
   "$schema": "./node_modules/oxlint/configuration_schema.json",
-  "plugins": ["unicorn", "oxc", "import", "jsdoc", "promise", "node"],
+  "plugins": ["unicorn", "oxc", "import", "jsdoc", "promise", "node", "vue"],
   "jsPlugins": ["@e18e/eslint-plugin"],
   "categories": {},
   "rules": {},

package/scripts/utils/oxlint-canonical.json

@@ -1,6 +1,6 @@
 {
   "$schema": "./node_modules/oxlint/configuration_schema.json",
-  "plugins": ["unicorn", "oxc", "import", "jsdoc", "promise", "node"],
+  "plugins": ["unicorn", "oxc", "import", "jsdoc", "promise", "node", "vue"],
   "jsPlugins": ["@e18e/eslint-plugin"],
   "categories": {},
   "rules": {