@nitra/cursor 1.37.0 → 1.38.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## [1.38.0] - 2026-05-31
+
+### Added
+
+- worktree: кросплатформний CLI n-cursor worktree (add/remove/list/prune) — виконавець конвенції .worktrees/ з інвентарним файлом-описом; тонкий skill worktree; pure-doc правило worktree
+
 ## [1.37.0] - 2026-05-31
 
 ### Changed

package/README.md

@@ -68,6 +68,12 @@
 npx @nitra/cursor
 npx @nitra/cursor fix
 npx @nitra/cursor fix bun ga
+
+# Керування git-worktree (.worktrees/ + інвентарний файл-опис)
+npx @nitra/cursor worktree add <branch> "<опис>"
+npx @nitra/cursor worktree list
+npx @nitra/cursor worktree remove <branch> [--force]
+npx @nitra/cursor worktree prune
 ```
 
 Команда `check` запускає programmatic перевірки з каталогу `scripts/` пакету. Якщо в корені репозиторію вже є `.n-cursor.json`, перед перевірками виконується зчитування конфігу — зокрема додається або виправляється поле `$schema`, якщо воно відсутнє або не збігається з очікуваним URL.

package/bin/n-cursor.js

@@ -103,6 +103,7 @@ 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 { runSkillsCli } from '../scripts/skills-cli.mjs'
+import { runWorktreeCli } from '../scripts/worktree-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'
@@ -1525,6 +1526,11 @@ try {
 
       break
     }
+    case 'worktree': {
+      process.exitCode = await runWorktreeCli(args)
+
+      break
+    }
     case undefined:
     case '': {
       await runSync()
@@ -1534,7 +1540,7 @@ try {
     default: {
       console.error(`❌ Невідома команда: ${command}`)
       console.error(
-        `   Очікується: (без аргументів) синхронізація правил, check, rename-yaml-extensions, post-tool-use-fix, lint, lint-ga, lint-rego, lint-k8s, lint-docker, lint-text, coverage, change, release, skill`
+        `   Очікується: (без аргументів) синхронізація правил, check, rename-yaml-extensions, post-tool-use-fix, lint, lint-ga, lint-rego, lint-k8s, lint-docker, lint-text, coverage, change, release, skill, worktree`
       )
       process.exitCode = 1
     }

package/package.json

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

package/rules/worktree/worktree.mdc

@@ -0,0 +1,34 @@
+---
+description: Конвенція git-worktree у цьому репо — створення, інвентаризація та прибирання через n-cursor worktree CLI.
+globs:
+alwaysApply: true
+---
+
+# Worktree-конвенція
+
+Усі git-worktree створюй і прибирай через CLI `n-cursor worktree` — він кладе їх у
+`.worktrees/` (gitignored) і веде інвентарний файл-опис поруч.
+
+## Розташування
+
+```
+.worktrees/
+  feat-skill-meta/        ← git worktree checkout
+  feat-skill-meta.md      ← інвентарний опис поруч (gitignored через .worktrees/)
+```
+
+Слеш у гілці перетворюється на дефіс: `feat/skill-meta` → `.worktrees/feat-skill-meta/`.
+Git-гілка лишається з оригінальним імʼям (`feat/skill-meta`).
+
+## Команди
+
+- **Створити** (опис обовʼязковий): `npx @nitra/cursor worktree add <branch> "<навіщо>"`
+- **Інвентаризація**: `npx @nitra/cursor worktree list`
+- **Прибрати**: `npx @nitra/cursor worktree remove <branch> [--force]`
+- **Прибрати осиротілі**: `npx @nitra/cursor worktree prune`
+
+## Заборони
+
+- Не клади worktree в `.claude/worktrees/` — це приватна директорія харнесу Claude Code.
+- Не клади worktree в батьківський каталог `../cursor-<name>` — ускладнює інвентаризацію.
+- Не створюй worktree вручну (`git worktree add`) повз CLI — інакше не буде інвентарного опису.

package/scripts/lib/worktree.mjs

@@ -0,0 +1,73 @@
+/**
+ * Чиста логіка worktree-tool `n-cursor worktree` (без git/fs side-effects).
+ *
+ * Тут — детерміновані, тестовані без git функції:
+ *  - `sanitizeBranch` — імʼя гілки → безпечне імʼя каталогу/файла (слеш та інші
+ *    небезпечні для шляху символи → дефіс), щоб структура `.worktrees/` лишалась пласкою;
+ *  - `worktreePaths` — шляхи checkout і файла-опису поруч;
+ *  - `buildDescription` — текст інвентарного `.worktrees/<name>.md` за конвенцією worktree.mdc;
+ *  - `findOrphanDescFiles` — `.md`-описи без зареєстрованого worktree (для `prune`).
+ *
+ * Оркестрація (виклики git, запис файлів, argv) — у `npm/scripts/worktree-cli.mjs`.
+ */
+import { basename, join } from 'node:path'
+
+/** Символи, безпечні для імені каталогу/файла; решта → дефіс. */
+const UNSAFE_PATH_CHARS_RE = /[^a-zA-Z0-9._-]+/gu
+
+/**
+ * Перетворює імʼя git-гілки на безпечне імʼя каталогу/файла для `.worktrees/`.
+ * @param {string} branch імʼя git-гілки (наприклад `feat/skill-meta`)
+ * @returns {string} пласке імʼя (наприклад `feat-skill-meta`)
+ */
+export function sanitizeBranch(branch) {
+  if (typeof branch !== 'string' || branch.trim() === '') {
+    throw new Error('worktree: імʼя гілки обовʼязкове')
+  }
+  const sanitized = branch.trim().replace(UNSAFE_PATH_CHARS_RE, '-').replace(/^-+|-+$/gu, '')
+  if (sanitized === '') {
+    throw new Error(`worktree: імʼя гілки "${branch}" не містить допустимих символів`)
+  }
+  return sanitized
+}
+
+/**
+ * Детерміновані шляхи checkout і файла-опису для гілки.
+ * @param {string} repoRoot абсолютний корінь репозиторію
+ * @param {string} branch імʼя git-гілки
+ * @returns {{ checkout: string, descFile: string }} абсолютні шляхи
+ */
+export function worktreePaths(repoRoot, branch) {
+  const name = sanitizeBranch(branch)
+  const dir = join(repoRoot, '.worktrees')
+  return { checkout: join(dir, name), descFile: join(dir, `${name}.md`) }
+}
+
+/**
+ * Текст інвентарного файла-опису worktree.
+ * @param {{ branch: string, task: string, baseCommit: string, date: string }} params поля опису
+ * @returns {string} markdown-вміст `.worktrees/<name>.md`
+ */
+export function buildDescription({ branch, task, baseCommit, date }) {
+  return [
+    `# ${branch}`,
+    '',
+    `**Задача:** ${task}`,
+    `**Дата:** ${date}`,
+    `**База (коміт):** ${baseCommit}`,
+    '',
+    'Прибрати: ' + '`' + `npx @nitra/cursor worktree remove ${branch}` + '`',
+    ''
+  ].join('\n')
+}
+
+/**
+ * `.md`-описи без відповідного зареєстрованого worktree-checkout.
+ * @param {string[]} descFiles абсолютні шляхи `.worktrees/*.md`
+ * @param {string[]} registeredCheckouts абсолютні шляхи зареєстрованих worktree-checkout
+ * @returns {string[]} осиротілі `.md` (підмножина `descFiles`)
+ */
+export function findOrphanDescFiles(descFiles, registeredCheckouts) {
+  const checkoutBasenames = new Set(registeredCheckouts.map(c => basename(c)))
+  return descFiles.filter(md => !checkoutBasenames.has(basename(md).replace(/\.md$/u, '')))
+}

package/scripts/worktree-cli.mjs

@@ -0,0 +1,200 @@
+/**
+ * CLI-оркестратор worktree-tool `n-cursor worktree` (виконавець конвенції `.worktrees/`).
+ *
+ * Підкоманди:
+ *   add <branch> "<опис>"     — git worktree add .worktrees/<sanit> -b <branch> (від HEAD) + .md-опис
+ *   remove <branch> [--force] — прибрати checkout + .md (гілку лишає)
+ *   list                      — git worktree list + вміст .md-описів
+ *   prune                     — git worktree prune + видалити осиротілі .md
+ *
+ * Чисті функції (санітизація, шляхи, текст опису, осиротілі) — у `lib/worktree.mjs`.
+ * Тут лише git-виклики, запис файлів, парсинг argv і звіт.
+ */
+import { spawnSync } from 'node:child_process'
+import { existsSync, readdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { cwd as processCwd } from 'node:process'
+
+import { buildDescription, findOrphanDescFiles, worktreePaths } from './lib/worktree.mjs'
+
+const USAGE = [
+  'Usage:',
+  '  npx @nitra/cursor worktree add <branch> "<опис>"',
+  '  npx @nitra/cursor worktree remove <branch> [--force]',
+  '  npx @nitra/cursor worktree list',
+  '  npx @nitra/cursor worktree prune'
+].join('\n')
+
+/**
+ * Запускає git, повертає { status, stdout, stderr }.
+ * @param {string[]} args аргументи git
+ * @param {string} cwd робочий каталог
+ * @returns {{ status: number, stdout: string, stderr: string }} результат
+ */
+function git(args, cwd) {
+  const r = spawnSync('git', args, { cwd, encoding: 'utf8' })
+  return { status: r.status ?? 1, stdout: r.stdout ?? '', stderr: r.stderr ?? '' }
+}
+
+/**
+ * Поточна дата YYYY-MM-DD (ін'єкція через ctx.now для тестів).
+ * @param {() => Date} now фабрика дати
+ * @returns {string} дата у форматі YYYY-MM-DD
+ */
+function today(now) {
+  return now().toISOString().slice(0, 10)
+}
+
+/**
+ * Реєстровані worktree-checkout (абсолютні шляхи) з `git worktree list --porcelain`.
+ * @param {string} cwd корінь репо
+ * @returns {string[]} абсолютні шляхи checkout
+ */
+function listRegisteredCheckouts(cwd) {
+  return git(['worktree', 'list', '--porcelain'], cwd)
+    .stdout.split('\n')
+    .filter(line => line.startsWith('worktree '))
+    .map(line => line.slice('worktree '.length).trim())
+}
+
+/**
+ * Абсолютні шляхи `.worktrees/*.md`.
+ * @param {string} cwd корінь репо
+ * @returns {string[]} шляхи файлів-описів
+ */
+function listDescFiles(cwd) {
+  const dir = join(cwd, '.worktrees')
+  if (!existsSync(dir)) return []
+  return readdirSync(dir)
+    .filter(n => n.endsWith('.md'))
+    .map(n => join(dir, n))
+}
+
+/**
+ * add: створити worktree від HEAD + .md-опис.
+ * @param {string[]} rest [branch, ...descParts]
+ * @param {{ cwd: string, log: Function, logError: Function, now: () => Date }} ctx контекст
+ * @returns {number} exit code
+ */
+function cmdAdd(rest, ctx) {
+  const [branch, ...descParts] = rest
+  const task = descParts.join(' ').trim()
+  if (!branch) {
+    ctx.logError('worktree add: потрібне імʼя гілки')
+    ctx.logError(USAGE)
+    return 1
+  }
+  if (!task) {
+    ctx.logError('worktree add: опис обовʼязковий — `worktree add <branch> "<опис>"`')
+    return 1
+  }
+  let paths
+  try {
+    paths = worktreePaths(ctx.cwd, branch)
+  } catch (error) {
+    ctx.logError(error.message)
+    return 1
+  }
+  const added = git(['worktree', 'add', paths.checkout, '-b', branch], ctx.cwd)
+  if (added.status !== 0) {
+    ctx.logError(`worktree add не вдався: ${added.stderr.trim()}`)
+    return 1
+  }
+  const baseCommit = git(['rev-parse', '--short', 'HEAD'], ctx.cwd).stdout.trim()
+  const md = buildDescription({ branch, task, baseCommit, date: today(ctx.now) })
+  writeFileSync(paths.descFile, md, 'utf8')
+  ctx.log(`✅ worktree: ${paths.checkout}`)
+  ctx.log(`   опис:    ${paths.descFile}`)
+  return 0
+}
+
+/**
+ * remove: прибрати checkout + .md (гілку лишає).
+ * @param {string[]} rest [branch, ...flags]
+ * @param {{ cwd: string, log: Function, logError: Function }} ctx контекст
+ * @returns {number} exit code
+ */
+function cmdRemove(rest, ctx) {
+  const branch = rest.find(a => !a.startsWith('--'))
+  const force = rest.includes('--force')
+  if (!branch) {
+    ctx.logError('worktree remove: потрібне імʼя гілки')
+    return 1
+  }
+  let paths
+  try {
+    paths = worktreePaths(ctx.cwd, branch)
+  } catch (error) {
+    ctx.logError(error.message)
+    return 1
+  }
+  const args = ['worktree', 'remove', paths.checkout]
+  if (force) args.push('--force')
+  const removed = git(args, ctx.cwd)
+  if (removed.status !== 0) {
+    ctx.logError(`worktree remove не вдався: ${removed.stderr.trim()} (спробуй --force, якщо дерево брудне)`)
+    return 1
+  }
+  if (existsSync(paths.descFile)) rmSync(paths.descFile, { force: true })
+  ctx.log(`✅ прибрано: ${paths.checkout} (гілку ${branch} лишено)`)
+  return 0
+}
+
+/**
+ * list: git worktree list + вміст .md-описів.
+ * @param {{ cwd: string, log: Function }} ctx контекст
+ * @returns {number} exit code
+ */
+function cmdList(ctx) {
+  ctx.log(git(['worktree', 'list'], ctx.cwd).stdout.trimEnd())
+  for (const md of listDescFiles(ctx.cwd)) {
+    ctx.log(`\n--- ${md} ---`)
+    ctx.log(readFileSync(md, 'utf8').trimEnd())
+  }
+  return 0
+}
+
+/**
+ * prune: git worktree prune + видалити осиротілі .md.
+ * @param {{ cwd: string, log: Function }} ctx контекст
+ * @returns {number} exit code
+ */
+function cmdPrune(ctx) {
+  git(['worktree', 'prune'], ctx.cwd)
+  const orphans = findOrphanDescFiles(listDescFiles(ctx.cwd), listRegisteredCheckouts(ctx.cwd))
+  for (const md of orphans) {
+    rmSync(md, { force: true })
+    ctx.log(`🧹 видалено осиротілий опис: ${md}`)
+  }
+  ctx.log(`prune завершено (осиротілих описів: ${orphans.length})`)
+  return 0
+}
+
+/**
+ * Точка входу підкоманди worktree.
+ * @param {string[]} argv аргументи після `worktree`
+ * @param {{ cwd?: string, log?: Function, logError?: Function, now?: () => Date }} [options] ін'єкція для тестів
+ * @returns {Promise<number>} exit code
+ */
+export function runWorktreeCli(argv, options = {}) {
+  const ctx = {
+    cwd: options.cwd ?? processCwd(),
+    log: options.log ?? (line => console.log(line)),
+    logError: options.logError ?? (line => console.error(line)),
+    now: options.now ?? (() => new Date())
+  }
+  const [sub, ...rest] = argv
+  switch (sub) {
+    case 'add':
+      return Promise.resolve(cmdAdd(rest, ctx))
+    case 'remove':
+      return Promise.resolve(cmdRemove(rest, ctx))
+    case 'list':
+      return Promise.resolve(cmdList(ctx))
+    case 'prune':
+      return Promise.resolve(cmdPrune(ctx))
+    default:
+      ctx.logError(USAGE)
+      return Promise.resolve(1)
+  }
+}

package/skills/worktree/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: worktree
+description: >-
+  Створення та керування git-worktree через n-cursor worktree CLI: ізольований
+  workspace у .worktrees/<branch>/ з інвентарним файлом-описом
+---
+
+# worktree — ізольований workspace через CLI
+
+Для роботи в окремому git-worktree використовуй CLI `n-cursor worktree` — він
+однаковий у Claude і Cursor, кладе worktree у `.worktrees/` (gitignored) і сам
+створює інвентарний файл-опис поруч.
+
+## Команди
+
+- Створити (опис **обовʼязковий**):
+  `npx @nitra/cursor worktree add <branch> "<навіщо цей worktree>"`
+- Список активних з описами:
+  `npx @nitra/cursor worktree list`
+- Прибрати (гілку лишає; `--force` для брудного дерева):
+  `npx @nitra/cursor worktree remove <branch> [--force]`
+- Прибрати осиротілі описи / метадані:
+  `npx @nitra/cursor worktree prune`
+
+## Приклад
+
+```bash
+npx @nitra/cursor worktree add feat/skill-meta "реалізація Spec A: meta.json"
+cd .worktrees/feat-skill-meta
+# … робота в ізоляції …
+cd -
+npx @nitra/cursor worktree remove feat/skill-meta
+```
+
+Слеш у гілці перетворюється на дефіс для пласкої структури: `feat/skill-meta`
+→ `.worktrees/feat-skill-meta/`. Git-гілка лишається `feat/skill-meta`.
+
+Конвенція й заборони (де НЕ створювати worktree) — `.cursor/rules/n-worktree.mdc`.

package/skills/worktree/meta.json

@@ -0,0 +1 @@
+{ "worktree": false }