@nitra/cursor 1.21.0 → 1.23.0

package/.pi-template/extensions/n-cursor-adr/index.ts

@@ -0,0 +1,104 @@
+/**
+ * Pi.dev extension: ADR capture + normalize.
+ *
+ * На pi `agent_end` event серіалізує `ctx.sessionManager.getEntries()` у
+ * Claude-сумісний JSONL у tmpdir, формує stdin JSON і спавнить існуючі
+ * `.claude/hooks/{capture,normalize}-decisions.sh` через `pi.exec`.
+ *
+ * Логіка skip/throttle/LLM-CLI-selection лишається у bash — TS лише
+ * адаптер pi → bash. Recursion guard через env vars, що їх bash виставляє
+ * перед спавном LLM CLI.
+ */
+
+interface PiContext {
+  cwd: string
+  sessionId?: string
+  signal?: AbortSignal
+  sessionManager: { getEntries(): Array<{ message?: { role?: string; content?: unknown } }> }
+  ui?: { notify?: (msg: string, level?: 'info' | 'warning' | 'error') => void }
+}
+
+interface PiExec {
+  exec: (
+    cmd: string,
+    args: string[],
+    opts?: {
+      cwd?: string
+      env?: Record<string, string>
+      input?: string
+      signal?: AbortSignal
+      timeout?: number
+    }
+  ) => Promise<{ code: number; stdout: string; stderr: string }>
+  on: (
+    event: string,
+    handler: (event: unknown, ctx: PiContext) => Promise<void> | void
+  ) => void
+}
+
+import { writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { randomUUID } from 'node:crypto'
+import { env } from 'node:process'
+
+const CAPTURE_HOOK = '.claude/hooks/capture-decisions.sh'
+const NORMALIZE_HOOK = '.claude/hooks/normalize-decisions.sh'
+
+/**
+ * Pi extension entry point.
+ * @param pi pi.dev extension API
+ */
+export default function (pi: PiExec): void {
+  pi.on('agent_end', async (_event, ctx) => {
+    // Recursion guard: bash спавнить LLM CLI (claude/cursor-agent), той може
+    // стартувати pi-сесію. Bash виставляє ці env-vars перед спавном — child
+    // inheritance ловить рекурсивний trigger тут.
+    if (env.CAPTURE_DECISIONS_RUNNING || env.ADR_NORMALIZE_RUNNING) {
+      return
+    }
+
+    let jsonlPath: string
+    try {
+      const entries = ctx.sessionManager.getEntries()
+      const lines = entries
+        .filter(e => e.message?.role === 'user' || e.message?.role === 'assistant')
+        .map(e => JSON.stringify({ type: e.message?.role, message: e.message }))
+        .join('\n')
+      jsonlPath = join(tmpdir(), `n-cursor-pi-transcript-${Date.now()}-${randomUUID()}.jsonl`)
+      writeFileSync(jsonlPath, lines + '\n', 'utf8')
+    } catch (error) {
+      ctx.ui?.notify?.(
+        `@nitra/cursor: transcript serialization failed — ${(error as Error).message}`,
+        'error'
+      )
+      return
+    }
+
+    const stdinPayload = JSON.stringify({
+      transcript_path: jsonlPath,
+      session_id: ctx.sessionId ?? randomUUID()
+    })
+
+    const envOverride = { ...env, CLAUDE_PROJECT_DIR: ctx.cwd } as Record<string, string>
+
+    // Async, не блокує agent_end. Якщо bash-скриптів немає (pi-only консьюмер
+    // із claude-config: false) — pi.exec поверне ENOENT, ловимо у allSettled.
+    await Promise.allSettled([
+      pi.exec('bash', [CAPTURE_HOOK], {
+        cwd: ctx.cwd,
+        env: envOverride,
+        input: stdinPayload,
+        signal: ctx.signal,
+        timeout: 180_000
+      }),
+      pi.exec('bash', [NORMALIZE_HOOK], {
+        cwd: ctx.cwd,
+        env: envOverride,
+        input: stdinPayload,
+        signal: ctx.signal,
+        timeout: 600_000
+      })
+    ])
+  })
+}

package/CHANGELOG.md

@@ -4,6 +4,29 @@
 
 Формат — [Keep a Changelog](https://keepachangelog.com/uk/1.1.0/), нумерація — [SemVer](https://semver.org/lang/uk/).
 
+## [1.23.0] - 2026-05-25
+
+### Added
+
+- **Pi.dev ADR hooks** — bundled TS-extension `npm/.pi-template/extensions/n-cursor-adr/index.ts` копіюється у `.pi/extensions/n-cursor-adr/index.ts` проєкту-споживача коли `adr` ∈ `.n-cursor.json#rules`. На pi `agent_end` event серіалізує `ctx.sessionManager.getEntries()` у Claude-сумісний JSONL у `tmpdir()`, спавнить існуючі `.claude/hooks/{capture,normalize}-decisions.sh` через `pi.exec` (async, `signal: ctx.signal`, timeouts 180s/600s). Жодного дублювання bash-логіки: skip/throttle/LLM-CLI-selection лишається у bash. Recursion guard через env-vars `CAPTURE_DECISIONS_RUNNING` / `ADR_NORMALIZE_RUNNING`, які bash виставляє перед спавном LLM CLI.
+- `npm/scripts/sync-claude-config.mjs`: експорт `PI_DIR`, `PI_EXTENSIONS_DIR`, `PI_TEMPLATE_DIR_NAME`, `PI_EXTENSION_NAME`; нова функція `syncPiExtensions(projectRoot, bundledPackageRoot)` (copy) і `removeOrphanPiExtension(projectRoot)` (cleanup); поле `piExtension: boolean` у відповіді `syncClaudeConfig` (gated на `adr` ∈ rules).
+- `npm/package.json` `files` array: додано `.pi-template` — bundled-директорія шипиться разом із пакетом.
+- `npm/bin/n-cursor.js`: у `🤖 Claude-конфіг`-логу після sync додається `.pi/extensions/n-cursor-adr/index.ts` коли pi-extension згенерована.
+
+## [1.22.0] - 2026-05-25
+
+### Added
+
+- **`npx @nitra/cursor lint`** — оркестратор лінт-ланцюжка з тайменгом на кожен крок. Послідовно запускає присутні у root `package.json` скрипти з фіксованого списку (`lint-ga`, `lint-js`, `lint-rego`, `lint-style`, `lint-text`, `lint-security`, `oxfmt`), **fail-fast** на першому ненульовому exit-коді. Наприкінці друкує таблицю `⏱ Lint timing` з часом кожного кроку — для атрибуції повільних кроків замість анонімного `&&`-агрегатора.
+- **`runFixCommand` тепер друкує `⏱ Fix timing`** після прогону всіх `rules/<id>/fix.mjs` — per-rule час + сума. Маркер `❌` на впалих рядках.
+- `npm/scripts/lib/timing-summary.mjs` — чистий форматер `formatTimingSummary(title, entries)` (спільний для fix і lint). 9 тестів у `tests/timing-summary.test.mjs`.
+- `npm/scripts/lib/run-lint-cli.mjs` — `runLintCli({ cwd, spawnSyncFn, now, log, logError })` з DI для юніт-тестів. 7 тестів у `tests/run-lint-cli.test.mjs`.
+
+### Changed
+
+- Кореневий `package.json` цього монорепо: `lint` → `n-cursor lint`; додано окремий скрипт `oxfmt: "oxfmt ."`, який раніше йшов у хвості ланцюжка прямою командою.
+- Скіли `/n-fix` і `/n-lint`: додано вимогу копіювати таблицю `⏱` з виводу інструмента у фінальне резюме відповіді користувачу.
+
 ## [1.21.0] - 2026-05-25
 
 ### Changed

package/bin/n-cursor.js

@@ -13,6 +13,9 @@
  *                                     дістає `tool_input.file_path`, маршрутизує його у відповідні правила
  *                                     (`*.mjs` → `js-lint`, `*.vue` → `js-lint style-lint vue` тощо) і викликає
  *                                     `fix` лише з ними. Прописується автоматично в `.claude/settings.json`.
+ *   `npx \@nitra/cursor lint`        — оркестратор lint-ланцюжка з кореневого `package.json` з тайменгом
+ *                                     кожного `lint-*` / `oxfmt` скрипта (fail-fast); канонічна заміна
+ *                                     раніше ручного `lint-ga && lint-js && …` агрегатора.
  *   `npx \@nitra/cursor lint-ga`     — канонічний lint-ga (ga.mdc): preflight на `shellcheck` →
  *                                     `bunx github-actionlint` → `uvx zizmor --offline --collect=workflows .`
  *   `npx \@nitra/cursor lint-rego`   — канонічний lint-rego (conftest.mdc + rego.mdc):
@@ -99,6 +102,8 @@ import { upgradeNitraCursorToLatestAndBunInstall } from '../scripts/upgrade-nitr
 import { runRenameYamlExtensionsCli } from './rename-yaml-extensions.mjs'
 import { runSkillsCli } from '../scripts/skills-cli.mjs'
 import { syncSetupBunDepsAction } from '../scripts/sync-setup-bun-deps-action.mjs'
+import { runLintCli } from '../scripts/lib/run-lint-cli.mjs'
+import { formatTimingSummary } from '../scripts/lib/timing-summary.mjs'
 
 const PACKAGE_NAME = '@nitra/cursor'
 const CONFIG_FILE = '.n-cursor.json'
@@ -1183,12 +1188,19 @@ async function runFixCommand(requestedRules) {
   }
 
   let totalFailed = 0
+  /** @type {{ id: string, ms: number, ok: boolean }[]} */
+  const timings = []
   for (const id of idsToRun) {
     const fixPath = join(BUNDLED_RULES_DIR, id, 'fix.mjs')
+    const startedAt = Date.now()
     const result = spawnSync('bun', [fixPath], { stdio: 'inherit' })
-    if (result.status !== 0) totalFailed++
+    const ok = result.status === 0
+    timings.push({ id: `fix-${id}`, ms: Date.now() - startedAt, ok })
+    if (!ok) totalFailed++
   }
 
+  process.stdout.write(formatTimingSummary('Fix timing', timings))
+
   if (totalFailed > 0) {
     throw new Error(`${totalFailed} з ${idsToRun.length} правил мають проблеми`)
   }
@@ -1390,6 +1402,7 @@ async function runSync() {
     if (result.adrHook) parts.push('.claude/hooks/capture-decisions.sh')
     if (result.adrNormalizeHook) parts.push('.claude/hooks/normalize-decisions.sh')
     if (result.gitignoreAdr) parts.push('.gitignore (adr fragment)')
+    if (result.piExtension) parts.push('.pi/extensions/n-cursor-adr/index.ts')
     if (parts.length > 0) {
       console.log(`🤖 Claude-конфіг: ${parts.join(', ')}`)
     }
@@ -1437,6 +1450,13 @@ try {
 
       break
     }
+    case 'lint': {
+      // Оркестратор lint-ланцюжка з тайменгом на кожен крок (fail-fast).
+      // Замінює раніше використовуваний агрегатор `bun run lint-ga && bun run lint-js && …` у root package.json.
+      process.exitCode = runLintCli()
+
+      break
+    }
     case 'lint-ga': {
       // Канонічний lint-ga з preflight на shellcheck → actionlint → zizmor → check-ga (ga.mdc).
       // Останній крок (check-ga) async — тому await обов'язковий, інакше process.exitCode буде Promise.
@@ -1490,7 +1510,7 @@ try {
     default: {
       console.error(`❌ Невідома команда: ${command}`)
       console.error(
-        `   Очікується: (без аргументів) синхронізація правил, check, rename-yaml-extensions, post-tool-use-fix, lint-ga, lint-rego, lint-k8s, lint-docker, lint-text, coverage, skill`
+        `   Очікується: (без аргументів) синхронізація правил, check, rename-yaml-extensions, post-tool-use-fix, lint, lint-ga, lint-rego, lint-k8s, lint-docker, lint-text, coverage, skill`
       )
       process.exitCode = 1
     }

package/package.json

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

package/scripts/lib/run-lint-cli.mjs

@@ -0,0 +1,116 @@
+/**
+ * `n-cursor lint` — оркестратор лінт-ланцюжка з тайменгом на кожен крок.
+ *
+ * Замість агрегатора `bun run lint-ga && bun run lint-js && ... && oxfmt .` у кореневому
+ * `package.json` (де child-процеси анонімні і час кожного не видно), цей орекстратор:
+ *
+ *  - читає `scripts` з кореневого `package.json`,
+ *  - бере **присутні** ключі з фіксованого списку `LINT_SCRIPTS` (відсутні мовчки пропускає),
+ *  - послідовно запускає `bun run <script>`,
+ *  - заміряє час кожного,
+ *  - **fail-fast**: при першому ненульовому exit-коді зупиняється, друкує таблицю
+ *    лише по виконаних і повертає той самий код,
+ *  - друкує підсумкову таблицю `⏱ Lint timing` і повертає 0, якщо все ОК.
+ *
+ * Список + порядок зумисне фіксований: збігається з канонічним ланцюжком, що його раніше
+ * тримав root `package.json`. Динамічний discovery (`scripts/^lint-/`) дав би непередбачуваний
+ * порядок і небажану інтерпретацію кастомних `lint-*` користувача.
+ *
+ * `oxfmt` — окремий рядок поза префіксом `lint-`, ставиться в кінець (як було у `lint`).
+ */
+import { spawnSync as defaultSpawnSync } from 'node:child_process'
+import { existsSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+import { formatTimingSummary } from './timing-summary.mjs'
+
+/**
+ * Імена npm-скриптів, які `n-cursor lint` запускає **по черзі**, якщо вони є у root `package.json`.
+ * Порядок дзеркалить попередній агрегатор `lint`: cheap-checks першими, формат — в кінці.
+ */
+export const LINT_SCRIPTS = /** @type {const} */ ([
+  'lint-ga',
+  'lint-js',
+  'lint-rego',
+  'lint-style',
+  'lint-text',
+  'lint-security',
+  'oxfmt'
+])
+
+/**
+ * Читає `scripts` з `package.json` у заданій теці. Повертає `null`, якщо файла немає, JSON
+ * некоректний або поля `scripts` нема. Не кидає — викликач сам вирішує, що робити.
+ * @param {string} root абсолютний шлях до теки з `package.json`
+ * @returns {Record<string, string> | null} мапа scripts або null
+ */
+function readRootScripts(root) {
+  const packageJsonPath = join(root, 'package.json')
+  if (!existsSync(packageJsonPath)) {
+    return null
+  }
+  try {
+    const parsed = JSON.parse(readFileSync(packageJsonPath, 'utf8'))
+    const scripts = parsed?.scripts
+    if (!scripts || typeof scripts !== 'object') {
+      return null
+    }
+    return /** @type {Record<string, string>} */ (scripts)
+  } catch {
+    return null
+  }
+}
+
+/**
+ * @typedef {{
+ *   cwd?: string,
+ *   spawnSyncFn?: typeof defaultSpawnSync,
+ *   now?: () => number,
+ *   log?: (text: string) => void,
+ *   logError?: (text: string) => void
+ * }} RunLintCliOptions
+ */
+
+/**
+ * Виконує лінт-ланцюжок з тайменгом. Повертає exit-код, не кидає винятків (для прямого
+ * присвоєння у `process.exitCode`).
+ * @param {RunLintCliOptions} [options] DI для тестів (мокаємо spawn / fs / clock)
+ * @returns {number} 0 = успіх, ненульовий = code першого впалого скрипта, або 1 при структурних проблемах
+ */
+export function runLintCli(options = {}) {
+  const root = options.cwd ?? process.cwd()
+  const spawnSync = options.spawnSyncFn ?? defaultSpawnSync
+  const now = options.now ?? Date.now
+  const log = options.log ?? (text => process.stdout.write(text))
+  const logError = options.logError ?? (text => process.stderr.write(text))
+
+  const scripts = readRootScripts(root)
+  if (scripts === null) {
+    logError(`❌ n-cursor lint: не знайдено package.json або поля "scripts" у ${root}\n`)
+    return 1
+  }
+
+  const present = LINT_SCRIPTS.filter(name => typeof scripts[name] === 'string' && scripts[name].length > 0)
+  if (present.length === 0) {
+    log('\nℹ️  n-cursor lint: у package.json немає жодного з lint-* / oxfmt скриптів — нічого запускати.\n')
+    return 0
+  }
+
+  /** @type {{ id: string, ms: number, ok: boolean }[]} */
+  const timings = []
+  let failedCode = 0
+  for (const name of present) {
+    const startedAt = now()
+    const result = spawnSync('bun', ['run', name], { stdio: 'inherit', cwd: root })
+    const code = typeof result.status === 'number' ? result.status : 1
+    const ok = code === 0
+    timings.push({ id: name, ms: now() - startedAt, ok })
+    if (!ok) {
+      failedCode = code === 0 ? 1 : code
+      break
+    }
+  }
+
+  log(formatTimingSummary('Lint timing', timings))
+  return failedCode
+}

package/scripts/lib/timing-summary.mjs

@@ -0,0 +1,66 @@
+/**
+ * Формат таблиці-резюме часу виконання для оркестраторів `fix` / `lint`.
+ *
+ * Дві спільні точки використання:
+ *  - `runFixCommand` у `bin/n-cursor.js` — після прогону всіх `rules/<id>/fix.mjs`.
+ *  - `runLintCli` у `scripts/lib/run-lint-cli.mjs` — після прогону `lint-*` скриптів з кореневого `package.json`.
+ *
+ * Чиста функція без I/O — повертає готовий рядок (з фінальним `\n`), друк — на стороні виклику.
+ * Час виводиться як `<ціла>.<десята>s`, навіть для субсекундних інтервалів — щоб одиниця була стабільна.
+ *
+ * Маркер `❌` на рядку — якщо `ok === false`.
+ * @typedef {{ id: string, ms: number, ok: boolean }} TimingEntry
+ */
+
+/** @type {string} символ горизонтальної риски між списком і `total` */
+const RULER = '─'
+
+/**
+ * Форматує мілісекунди як `<sec>.<десята>s`. Округлення до десятої — нижнє (floor), щоб
+ * однаковий ms давав однаковий вивід у різних таблицях незалежно від платформи (Number.prototype.toFixed
+ * робить round-half-to-even, що для 950ms дає `0.9s` — приймаємо).
+ * @param {number} ms тривалість у мілісекундах (>= 0)
+ * @returns {string} наприклад `0.0s`, `1.2s`, `12.3s`
+ */
+export function formatDurationMs(ms) {
+  const seconds = Math.max(0, ms) / 1000
+  return `${seconds.toFixed(1)}s`
+}
+
+/**
+ * Рендерить таблицю-резюме у вигляді багаторядкового тексту, готового до stdout.
+ *
+ * Структура:
+ *
+ * ```
+ * ⏱  <title>:
+ *    <id>          <duration>  [❌]
+ *    ...
+ *    ──────────────
+ *    total         <sum>
+ * ```
+ *
+ * Ширина колонки id вирівнюється під найдовший id у списку. Мінімальна ширина riski — 14
+ * (узгоджено з типовою довжиною заголовків `fix-js-lint` / `lint-security`).
+ * @param {string} title заголовок таблиці (наприклад, `Fix timing` або `Lint timing`)
+ * @param {TimingEntry[]} timings записи в порядку запуску — друкуються як є, не сортуються
+ * @returns {string} готовий до stdout текст з кінцевим `\n`
+ */
+export function formatTimingSummary(title, timings) {
+  if (timings.length === 0) {
+    return ''
+  }
+  const idWidth = Math.max(14, ...timings.map(t => t.id.length))
+  const lines = [`\n⏱  ${title}:`]
+  let totalMs = 0
+  for (const { id, ms, ok } of timings) {
+    totalMs += ms
+    const failMark = ok ? '' : '  ❌'
+    lines.push(`   ${id.padEnd(idWidth)}  ${formatDurationMs(ms)}${failMark}`)
+  }
+  lines.push(
+    `   ${RULER.repeat(idWidth + 2 + 6)}`,
+    `   ${'total'.padEnd(idWidth)}  ${formatDurationMs(totalMs)}`
+  )
+  return `${lines.join('\n')}\n`
+}

package/scripts/sync-claude-config.mjs

@@ -27,7 +27,7 @@
  * Опт-аут — `claude-config: false` у `.n-cursor.json`.
  */
 import { existsSync } from 'node:fs'
-import { chmod, mkdir, readFile, readdir, writeFile } from 'node:fs/promises'
+import { chmod, mkdir, readFile, readdir, rm, writeFile } from 'node:fs/promises'
 import { join } from 'node:path'
 
 /** Маркер PostToolUse fix-hook'а (`npx --no \@nitra/cursor post-tool-use-fix`). */
@@ -62,6 +62,15 @@ const CURSOR_HOOKS_FILE = `${CURSOR_DIR}/hooks.json`
 const ADR_HOOK_SCRIPT_NAME = 'capture-decisions.sh'
 const ADR_NORMALIZE_HOOK_SCRIPT_NAME = 'normalize-decisions.sh'
 const TEMPLATE_DIR_NAME = '.claude-template'
+
+/** Корінь pi.dev артефактів у проєкті-споживачі. */
+export const PI_DIR = '.pi'
+/** Директорія pi.dev TS-extensions у проєкті-споживачі. */
+export const PI_EXTENSIONS_DIR = `${PI_DIR}/extensions`
+/** Назва bundled-директорії pi-template у пакеті `@nitra/cursor`. */
+export const PI_TEMPLATE_DIR_NAME = '.pi-template'
+/** Імʼя bundled pi-extension'а для ADR capture/normalize. */
+export const PI_EXTENSION_NAME = 'n-cursor-adr'
 /** Відносний шлях до канонічного фрагмента `.gitignore` для ADR Stop-hook'ів у tarball пакета. */
 export const ADR_GITIGNORE_SNIPPET_REL = 'rules/adr/js/templates/hooks/.gitignore.snippet'
 const GITIGNORE_FILE = '.gitignore'
@@ -405,6 +414,52 @@ export function syncAdrNormalizeHookScript(projectRoot, templateDir) {
   return syncHookScript(projectRoot, templateDir, ADR_NORMALIZE_HOOK_SCRIPT_NAME)
 }
 
+/**
+ * Копіює bundled pi.dev TS-extension `npm/.pi-template/extensions/n-cursor-adr/index.ts`
+ * у `.pi/extensions/n-cursor-adr/index.ts` проєкту-споживача. Файл fully-owned: при кожному
+ * sync-у перезаписується. Якщо bundled template відсутній (наприклад, у legacy-версіях
+ * пакета без `.pi-template/`) — повертаємо `{written: false}` без помилки.
+ *
+ * @param {string} projectRoot корінь проєкту-споживача
+ * @param {string} bundledPackageRoot корінь установленого `@nitra/cursor` (із `.pi-template/`)
+ * @returns {Promise<{ written: boolean, path: string }>} чи писали файл, та його відносний шлях
+ */
+export async function syncPiExtensions(projectRoot, bundledPackageRoot) {
+  const srcPath = join(
+    bundledPackageRoot,
+    PI_TEMPLATE_DIR_NAME,
+    'extensions',
+    PI_EXTENSION_NAME,
+    'index.ts'
+  )
+  if (!existsSync(srcPath)) {
+    return { written: false, path: '' }
+  }
+  const content = await readFile(srcPath, 'utf8')
+  const destDir = join(projectRoot, PI_EXTENSIONS_DIR, PI_EXTENSION_NAME)
+  await mkdir(destDir, { recursive: true })
+  const destPath = join(destDir, 'index.ts')
+  await writeFile(destPath, content, 'utf8')
+  return { written: true, path: `${PI_EXTENSIONS_DIR}/${PI_EXTENSION_NAME}/index.ts` }
+}
+
+/**
+ * Видаляє `.pi/extensions/n-cursor-adr/` директорію з проєкту-споживача.
+ * Викликається коли правило `adr` вимкнено у `.n-cursor.json` (симетрично до
+ * cleanup-у `.claude/hooks/{capture,normalize}-decisions.sh`).
+ *
+ * @param {string} projectRoot корінь проєкту-споживача
+ * @returns {Promise<{ removed: boolean, path: string }>} чи було щось видалено та відносний шлях
+ */
+export async function removeOrphanPiExtension(projectRoot) {
+  const extDir = join(projectRoot, PI_EXTENSIONS_DIR, PI_EXTENSION_NAME)
+  if (!existsSync(extDir)) {
+    return { removed: false, path: '' }
+  }
+  await rm(extDir, { recursive: true, force: true })
+  return { removed: true, path: `${PI_EXTENSIONS_DIR}/${PI_EXTENSION_NAME}` }
+}
+
 /**
  * Повертає змістовні (не коментар, не порожній) рядки з text-фрагмента `.gitignore`.
  * @param {string} raw вміст snippet-файлу
@@ -494,7 +549,7 @@ export async function syncClaudeCommands(projectRoot, templateDir) {
  * @param {string} options.bundledPackageRoot корінь установленого `@nitra/cursor`
  * @param {boolean} options.enabled чи увімкнено sync (з `.n-cursor.json` `claude-config`)
  * @param {string[]} [options.rules] список увімкнених правил із `.n-cursor.json` — впливає на ADR Stop-hook (`adr`)
- * @returns {Promise<{ settings: boolean, cursorHooks: boolean, commands: string[], adrHook: boolean, adrNormalizeHook: boolean, gitignoreAdr: boolean }>} прапорці записів settings/Cursor hooks/ADR-hook(s)/`.gitignore` та список slash-команд
+ * @returns {Promise<{ settings: boolean, cursorHooks: boolean, commands: string[], adrHook: boolean, adrNormalizeHook: boolean, gitignoreAdr: boolean, piExtension: boolean }>} прапорці записів settings/Cursor hooks/ADR-hook(s)/`.gitignore`/pi-extension та список slash-команд
  */
 export async function syncClaudeConfig({ projectRoot, bundledPackageRoot, enabled, rules = [] }) {
   if (!enabled) {
@@ -504,7 +559,8 @@ export async function syncClaudeConfig({ projectRoot, bundledPackageRoot, enable
       commands: [],
       adrHook: false,
       adrNormalizeHook: false,
-      gitignoreAdr: false
+      gitignoreAdr: false,
+      piExtension: false
     }
   }
   const templateDir = join(bundledPackageRoot, TEMPLATE_DIR_NAME)
@@ -515,7 +571,8 @@ export async function syncClaudeConfig({ projectRoot, bundledPackageRoot, enable
       commands: [],
       adrHook: false,
       adrNormalizeHook: false,
-      gitignoreAdr: false
+      gitignoreAdr: false,
+      piExtension: false
     }
   }
   const includeAdrHook = Array.isArray(rules) && rules.includes('adr')
@@ -526,6 +583,9 @@ export async function syncClaudeConfig({ projectRoot, bundledPackageRoot, enable
   const gitignoreAdr = includeAdrHook
     ? await syncGitignoreAdrFragment(projectRoot, bundledPackageRoot)
     : { written: false, path: '' }
+  const piExtension = includeAdrHook
+    ? await syncPiExtensions(projectRoot, bundledPackageRoot)
+    : await removeOrphanPiExtension(projectRoot).then(r => ({ written: false, path: r.path }))
   const settings = await syncClaudeSettings(projectRoot, templateDir, { includeAdrHook })
   const cursorHooks = await syncCursorHooksConfig(projectRoot, { includeAdrHook })
   const commands = await syncClaudeCommands(projectRoot, templateDir)
@@ -535,6 +595,7 @@ export async function syncClaudeConfig({ projectRoot, bundledPackageRoot, enable
     commands,
     adrHook: adrHook.written,
     adrNormalizeHook: adrNormalizeHook.written,
-    gitignoreAdr: gitignoreAdr.written
+    gitignoreAdr: gitignoreAdr.written,
+    piExtension: piExtension.written
   }
 }