@nitra/cursor 1.8.158 → 1.8.159

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,21 @@
 
 Формат — [Keep a Changelog](https://keepachangelog.com/uk/1.1.0/), нумерація — [SemVer](https://semver.org/lang/uk/).
 
+## [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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nitra/cursor",
-  "version": "1.8.158",
+  "version": "1.8.159",
   "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/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/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": {