@nitra/cursor 1.19.2 → 1.21.0

package/scripts/post-tool-use-fix.mjs

@@ -0,0 +1,129 @@
+/**
+ * PostToolUse hook для Claude Code: точкова маршрутизація `npx @nitra/cursor fix`
+ * за типом зміненого файла. Запускається після кожного `Edit` / `Write` / `MultiEdit`;
+ * замінює дорогий синхронний `Stop`-хук, що ганяв повний `fix` усіх правил на кожному
+ * turn-і.
+ *
+ * Контракт:
+ * - stdin Claude Code: JSON із `tool_input.file_path` (відносний шлях зміненого файла);
+ * - exit 0, якщо файл не маршрутизується (PostToolUse не блокує turn у будь-якому випадку,
+ *   але ми лишаємо exit-код прозорим — для діагностики);
+ * - інакше spawn `npx --no @nitra/cursor fix <rules…>` із пробрасуванням exit-коду.
+ *
+ * Маршрути впорядковані від найбільш специфічного до загального; перший збіг — переможець.
+ * `docs/adr/**\/*.md` свідомо повертає `[]`: ADR-нормалізація вже покривається async
+ * Stop-hook'ом `normalize-decisions.sh` — повторний `fix adr` тут лише сповільнював би turn.
+ */
+import { spawn } from 'node:child_process'
+import { once } from 'node:events'
+
+import picomatch from 'picomatch'
+
+/**
+ * @typedef {object} Route
+ * @property {string} pattern picomatch glob (з підтримкою `**` і `{a,b}`)
+ * @property {string[]} rules ID правил `npm/rules/<id>` (бо `fix.mjs` обов'язковий)
+ */
+
+/** Порядок важливий: специфічні маршрути (`.github/workflows/*`, `**\/k8s/**`) — перед загальними. */
+/** @type {readonly Route[]} */
+const ROUTES = Object.freeze([
+  { pattern: 'docs/adr/**/*.md', rules: [] },
+  { pattern: '.github/workflows/*.{yml,yaml}', rules: ['ga'] },
+  { pattern: '**/k8s/**/*.{yaml,yml}', rules: ['k8s'] },
+  { pattern: '**/*.vue', rules: ['js-lint', 'style-lint', 'vue'] },
+  { pattern: '**/*.{mjs,js,cjs,ts,tsx,jsx}', rules: ['js-lint'] },
+  { pattern: '**/*.{css,scss,sass}', rules: ['style-lint'] },
+  { pattern: '**/*.rego', rules: ['rego'] },
+  { pattern: '{**/,}Dockerfile', rules: ['docker'] },
+  { pattern: '**/*.Dockerfile', rules: ['docker'] },
+  { pattern: '**/*.sh', rules: ['security'] },
+  { pattern: '{**/,}package.json', rules: ['npm-module', 'bun'] },
+  { pattern: '**/*.md', rules: ['text'] }
+])
+
+/**
+ * Повертає список правил, які слід прогнати для зміненого `filePath`.
+ * Перший збіг із `ROUTES` — переможець; невідомі шляхи / некоректні входи → `[]`.
+ * @param {unknown} filePath відносний шлях зміненого файла зі stdin Claude Code
+ * @returns {string[]} ID правил для `npx @nitra/cursor fix`
+ */
+export function routeFilePathToRules(filePath) {
+  if (typeof filePath !== 'string' || filePath === '') {
+    return []
+  }
+  for (const { pattern, rules } of ROUTES) {
+    if (picomatch.isMatch(filePath, pattern, { dot: true })) {
+      return [...rules]
+    }
+  }
+  return []
+}
+
+/**
+ * Зчитує stdin до EOF як utf8 рядок. На TTY — повертає `''` одразу.
+ * @returns {Promise<string>} вміст stdin
+ */
+async function readStdin() {
+  if (process.stdin.isTTY) {
+    return ''
+  }
+  process.stdin.setEncoding('utf8')
+  const chunks = []
+  process.stdin.on('data', chunk => {
+    chunks.push(chunk)
+  })
+  try {
+    await once(process.stdin, 'end')
+  } catch {
+    // 'error' на stdin — повертаємо те, що встигли зібрати
+  }
+  return chunks.join('')
+}
+
+/**
+ * Дістає `tool_input.file_path` зі stdin JSON Claude Code. Невалідний JSON
+ * або відсутнє поле → `null` (не помилка: дехто з тулів — напр. Bash — не пише `file_path`).
+ * @param {string} stdinJson сирий вміст stdin
+ * @returns {string | null} відносний шлях або `null`
+ */
+function extractFilePath(stdinJson) {
+  if (!stdinJson) {
+    return null
+  }
+  try {
+    const obj = JSON.parse(stdinJson)
+    const fp = obj?.tool_input?.file_path
+    return typeof fp === 'string' && fp !== '' ? fp : null
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Точка входу. Викликається з `bin/n-cursor.js` коли argv[0] === `post-tool-use-fix`.
+ * Параметри ін'єктовні для тестів: `stdinJson` обходить read від `process.stdin`,
+ * `spawnFn` — заміна `node:child_process.spawn` (повертає EventEmitter-сумісний об'єкт).
+ * @param {{ stdinJson?: string, spawnFn?: typeof spawn }} [options]
+ * @returns {Promise<number>} exit code (0 — пропущено / fix ОК; інше — exit-код `fix`)
+ */
+export async function runPostToolUseFixCli(options = {}) {
+  const stdinJson = options.stdinJson ?? (await readStdin())
+  const filePath = extractFilePath(stdinJson)
+  if (filePath === null) {
+    return 0
+  }
+  const rules = routeFilePathToRules(filePath)
+  if (rules.length === 0) {
+    return 0
+  }
+  const spawnFn = options.spawnFn ?? spawn
+  const child = spawnFn('npx', ['--no', '@nitra/cursor', 'fix', ...rules], { stdio: 'inherit' })
+  try {
+    const [code] = await once(child, 'exit')
+    return code ?? 1
+  } catch (error) {
+    process.stderr.write(`post-tool-use-fix: не вдалося запустити npx @nitra/cursor fix — ${error.message}\n`)
+    return 1
+  }
+}

package/scripts/sync-claude-config.mjs

@@ -30,8 +30,10 @@ import { existsSync } from 'node:fs'
 import { chmod, mkdir, readFile, readdir, writeFile } from 'node:fs/promises'
 import { join } from 'node:path'
 
-/** Маркер lint Stop-hook'а (`npx --no \@nitra/cursor stop-hook`). */
-export const MANAGED_HOOK_COMMAND_MARKER = '@nitra/cursor stop-hook'
+/** Маркер PostToolUse fix-hook'а (`npx --no \@nitra/cursor post-tool-use-fix`). */
+export const MANAGED_HOOK_COMMAND_MARKER = '@nitra/cursor post-tool-use-fix'
+/** Legacy-маркер старого Stop-hook'а — лишаємо для cleanup-у при оновленні існуючих інсталяцій. */
+export const LEGACY_STOP_HOOK_COMMAND_MARKER = '@nitra/cursor stop-hook'
 /** Маркер ADR Stop-hook'а — підрядок шляху до bash-скрипта capture-decisions. */
 export const ADR_HOOK_COMMAND_MARKER = '.claude/hooks/capture-decisions.sh'
 /** Маркер ADR Stop-hook'а — підрядок шляху до bash-скрипта normalize-decisions. */
@@ -40,9 +42,13 @@ export const ADR_NORMALIZE_HOOK_COMMAND_MARKER = '.claude/hooks/normalize-decisi
 export const CURSOR_ADR_HOOK_COMMAND_MARKER = '.claude/hooks/capture-decisions.sh'
 /** Маркер Cursor ADR Normalize Stop-hook'а — той самий script path, але в `.cursor/hooks.json`. */
 export const CURSOR_ADR_NORMALIZE_HOOK_COMMAND_MARKER = '.claude/hooks/normalize-decisions.sh'
-/** Усі маркери managed-hook'ів пакета — за ними відрізняємо свої записи від користувацьких. */
+/**
+ * Усі маркери managed-hook'ів пакета — за ними відрізняємо свої записи від користувацьких.
+ * Legacy stop-hook включений сюди, щоб старі entries автоматично видалялись при наступному sync-у.
+ */
 export const MANAGED_HOOK_COMMAND_MARKERS = Object.freeze([
   MANAGED_HOOK_COMMAND_MARKER,
+  LEGACY_STOP_HOOK_COMMAND_MARKER,
   ADR_HOOK_COMMAND_MARKER,
   ADR_NORMALIZE_HOOK_COMMAND_MARKER
 ])
@@ -189,9 +195,13 @@ export function mergeAllowList(existing, fromTemplate) {
 }
 
 /**
- * Зливає hooks-секцію: для кожної події в темплейті видаляємо managed-групи
- * з існуючої конфігурації і додаємо актуальні з темплейту. Немені події в
- * темплейті не чіпаються.
+ * Зливає hooks-секцію. Для **кожної події** з обох сторін:
+ *   1) видаляємо managed-групи з існуючої конфігурації (їх ідентифікують маркери з
+ *      `MANAGED_HOOK_COMMAND_MARKERS`, включно з legacy-маркерами — це автоматично
+ *      прибирає застарілі hook'и при переході на нову версію темплейту);
+ *   2) дописуємо managed-групи з темплейту.
+ * Перебір union-у подій важливий: коли пакет переносить hook між подіями (напр. `Stop`
+ * → `PostToolUse`), старі managed entries у вже-непотрібній події теж мають піти.
  * @param {Record<string, HookGroup[]> | undefined} existing поточна `hooks`-секція з .claude/settings.json
  * @param {Record<string, HookGroup[]> | undefined} fromTemplate цільова `hooks`-секція з темплейту
  * @returns {Record<string, HookGroup[]>} результат злиття (порожні події видаляються)
@@ -199,14 +209,13 @@ export function mergeAllowList(existing, fromTemplate) {
 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] : []
-  }
-  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]
+  const allEvents = new Set([...Object.keys(existing ?? {}), ...Object.keys(fromTemplate ?? {})])
+  for (const event of allEvents) {
+    const existingClean = (existing?.[event] ?? []).filter(g => !isManagedHookGroup(g))
+    const templateGroups = fromTemplate?.[event] ?? []
+    const combined = [...existingClean, ...templateGroups]
+    if (combined.length > 0) {
+      out[event] = combined
     }
   }
   return out

package/skills/fix-tests/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: n-fix-tests
+description: >-
+  Ітеративно дописати тести щоб підвищити mutation score — читає вижилі мутанти з COVERAGE.md і запускає агент до конвергенції
+---
+
+# n-fix-tests — підвищення mutation score
+
+## Мета
+
+Читає структурований JSON-блок вижилих мутантів з `COVERAGE.md` і ітеративно дописує тести що їх вловлюють. Зупиняється коли score перестає покращуватись (конвергенція).
+
+## Передумови
+
+- У `COVERAGE.md` є секція `## Вижилі мутанти` з JSON-блоком
+- Залежності встановлені (`bun i`)
+- `bun run coverage` (або `n-cursor coverage`) доступний
+
+## Workflow
+
+### Крок 1: Зчитай вижилих мутантів
+
+Прочитай `COVERAGE.md`. Знайди секцію `## Вижилі мутанти`. Знайди фенсований блок ` ```json ` у цій секції і розпарси JSON-масив.
+
+Якщо секція відсутня або масив порожній — зупинись з повідомленням:
+`✓ Жодних вижилих мутантів — mutation score повний`
+
+Запамʼятай поточну кількість вижилих: `prevCount = масив.length`
+
+### Крок 2: Знайди test-команду і coverage-команду
+
+Прочитай `package.json` у кореневій директорії.
+
+**test-команда** (перша що існує):
+1. `scripts["test"]` з `package.json`
+2. fallback: `bun test`
+
+**coverage-команда** (перша що існує):
+1. `scripts["coverage"]` з `package.json` → виклик: `bun run coverage`
+2. fallback: `n-cursor coverage`
+
+### Крок 3: Для кожного файлу — спауни Agent
+
+Згрупуй мутанти по полю `file`. Для кожної групи виконай:
+
+**3a. Знайди файли:**
+- Source: `<cwd>/<file>` (прочитай вміст)
+- Test файл (перший що існує):
+  - `<dir>/<basename>.test.<ext>` — поруч із source
+  - `<dir>/tests/<basename>.test.<ext>`
+  - `tests/<basename>.test.<ext>` від кореня
+  - Якщо жоден не знайдено — буде створено поруч із source
+
+**3b. Сформуй промпт для Agent:**
+
+```
+Тобі дані вижилі мутанти зі Stryker для файлу `<file>`.
+Ці мутанти вижили тому що наявні тести НЕ вловили конкретні зміни коду.
+
+**Вихідний код** (`<file>`):
+\`\`\`
+<зміст source-файлу>
+\`\`\`
+
+**Наявні тести** (`<test-file>`):
+\`\`\`
+<зміст test-файлу або "файл ще не існує">
+\`\`\`
+
+**Вижилі мутанти** (кожен — зміна коду що НЕ вловлена):
+<для кожного мутанта:>
+- Рядок <line>, колонка <col>: `<original>` → `<replacement>` (тип мутації: <mutantType>)
+
+**Завдання:**
+Допиши мінімальні test-cases у файл `<test-file>` які б вловили кожен із перелічених мутантів.
+Правила:
+- НЕ видаляй і НЕ змінюй наявні тести
+- Стиль тестів — відповідно до наявного файлу (той самий фреймворк, той самий стиль describe/test)
+- Якщо файл ще не існує — створи його з правильними імпортами відповідно до файлів у тому самому каталозі
+- Після написання запусти: `bun test <test-file>` і переконайся що всі тести проходять (виправ якщо падають)
+```
+
+**3c. Запусти Agent** з цим промптом і дочекайся завершення.
+
+### Крок 4: Перевір що всі тести проходять
+
+```bash
+bun test  # або test-команда з кроку 2
+```
+
+Якщо тести падають — поверни конкретний Agent (для того файлу) з помилкою і попроси виправити.
+
+### Крок 5: Запусти coverage і порівняй
+
+```bash
+bun run coverage  # або coverage-команда з кроку 2
+```
+
+Прочитай новий `COVERAGE.md`, знайди і розпарси JSON-масив вижилих.
+`newCount = новий масив.length`
+
+**Рішення:**
+- Якщо `newCount < prevCount` → повтор з Кроку 1 з оновленим масивом
+- Якщо `newCount >= prevCount` → зупинись:
+  `✓ Конвергенція: mutation score більше не покращується. Вижило: <newCount> мутантів.`
+
+## Зупинка після конвергенції
+
+Конвергенція — нормальний результат. Деякі мутанти не можна вбити (захищений зовнішнім станом, недетермінована логіка тощо). Не намагайся виправити те що не змінилось після ітерації.

package/skills/fix-tests/auto.md

@@ -0,0 +1 @@
+[js-lint]

package/scripts/claude-stop-hook.mjs

@@ -1,74 +0,0 @@
-/**
- * Stop-hook для Claude Code: запускається hook'ом із `.claude/settings.json` після того,
- * як агент сигналізує завершення ходу. Прозоро прокидає `npx \@nitra/cursor fix`
- * і повертає його 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'
-import { once } from 'node:events'
-
-/**
- * Зчитує stdin до EOF як utf8 рядок. Якщо stdin порожній (TTY) — повертає '' одразу.
- * @returns {Promise<string>} вміст stdin
- */
-async function readStdin() {
-  if (process.stdin.isTTY) {
-    return ''
-  }
-  process.stdin.setEncoding('utf8')
-  const chunks = []
-  process.stdin.on('data', chunk => {
-    chunks.push(chunk)
-  })
-  try {
-    await once(process.stdin, 'end')
-  } catch {
-    // 'error' на stdin — повертаємо те, що встигли зібрати
-  }
-  return chunks.join('')
-}
-
-/**
- * Чи 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
-  }
-
-  const child = spawn('npx', ['--no', '@nitra/cursor', 'fix'], { stdio: 'inherit' })
-  try {
-    const [code] = await once(child, 'exit')
-    return code ?? 1
-  } catch (error) {
-    process.stderr.write(`stop-hook: не вдалося запустити npx @nitra/cursor fix — ${error.message}\n`)
-    return 1
-  }
-}