@nitra/cursor 5.1.0 → 5.2.1

package/scripts/lib/docs/discover-check-rules-from-cursor.md

@@ -1,3 +1,9 @@
+---
+docgen:
+  source: npm/scripts/lib/discover-check-rules-from-cursor.mjs
+  crc: 5e312e3e
+---
+
 # discover-check-rules-from-cursor.mjs
 
 ## Огляд

package/scripts/lib/docs/discover-checkable-rules.md

@@ -1,3 +1,9 @@
+---
+docgen:
+  source: npm/scripts/lib/discover-checkable-rules.mjs
+  crc: 39016d17
+---
+
 # discover-checkable-rules.mjs
 
 ## Огляд

package/scripts/lib/docs/ensure-tool.md

@@ -1,3 +1,9 @@
+---
+docgen:
+  source: npm/scripts/lib/ensure-tool.mjs
+  crc: 230254b3
+---
+
 # ensure-tool.mjs
 
 ## Огляд

package/scripts/lib/docs/generated-markdown.md

@@ -1,3 +1,9 @@
+---
+docgen:
+  source: npm/scripts/lib/generated-markdown.mjs
+  crc: 14b85a57
+---
+
 # generated-markdown.mjs
 
 ## Огляд

package/scripts/lib/docs/gha-workflow.md

@@ -1,3 +1,9 @@
+---
+docgen:
+  source: npm/scripts/lib/gha-workflow.mjs
+  crc: 266986bf
+---
+
 # gha-workflow.mjs
 
 ## Огляд

package/scripts/lib/docs/inline-template-links.md

@@ -1,3 +1,9 @@
+---
+docgen:
+  source: npm/scripts/lib/inline-template-links.mjs
+  crc: 7726f0ef
+---
+
 # inline-template-links.mjs
 
 ## Огляд

package/scripts/lib/docs/list-rule-ids.md

@@ -1,3 +1,9 @@
+---
+docgen:
+  source: npm/scripts/lib/list-rule-ids.mjs
+  crc: 5ef1ead5
+---
+
 # list-rule-ids.mjs
 
 ## Огляд

package/scripts/lib/docs/load-cursor-config.md

@@ -1,3 +1,9 @@
+---
+docgen:
+  source: npm/scripts/lib/load-cursor-config.mjs
+  crc: c86a80f4
+---
+
 # load-cursor-config.mjs
 
 ## Огляд

package/scripts/lib/docs/mirror-parity.md

@@ -1,3 +1,9 @@
+---
+docgen:
+  source: npm/scripts/lib/mirror-parity.mjs
+  crc: 15dc336a
+---
+
 ## Огляд
 
 Модуль `mirror-parity.mjs` забезпечує перевірку парності (parity) між «дзеркальними» файлами правил Cursor у `.cursor/rules/n-<id>.mdc` та їх канонічними джерелами у `npm/rules/<id>/<id>.mdc`. Ідея така: репозиторій містить два представлення одного й того ж правила:

package/scripts/lib/docs/read-n-cursor-config-lite.md

@@ -1,3 +1,9 @@
+---
+docgen:
+  source: npm/scripts/lib/read-n-cursor-config-lite.mjs
+  crc: a5fb0592
+---
+
 # read-n-cursor-config-lite.mjs
 
 ## Огляд

package/scripts/lib/docs/resolve-target-files.md

@@ -1,3 +1,9 @@
+---
+docgen:
+  source: npm/scripts/lib/resolve-target-files.mjs
+  crc: a3b361d9
+---
+
 # resolve-target-files.mjs
 
 ## Огляд

package/scripts/lib/docs/root-notice.md

@@ -1,3 +1,9 @@
+---
+docgen:
+  source: npm/scripts/lib/root-notice.mjs
+  crc: 5f3ca2bb
+---
+
 # root-notice.mjs
 
 ## Огляд

package/scripts/lib/docs/rule-meta-helpers.md

@@ -1,3 +1,9 @@
+---
+docgen:
+  source: npm/scripts/lib/rule-meta-helpers.mjs
+  crc: a7e1ae1d
+---
+
 # rule-meta-helpers.mjs
 
 ## Огляд

package/scripts/lib/docs/rule-meta.md

@@ -1,3 +1,9 @@
+---
+docgen:
+  source: npm/scripts/lib/rule-meta.mjs
+  crc: 4475d5ff
+---
+
 # rule-meta.mjs
 
 ## Огляд

package/scripts/lib/docs/run-conftest-batch.md

@@ -1,3 +1,9 @@
+---
+docgen:
+  source: npm/scripts/lib/run-conftest-batch.mjs
+  crc: 5ec640a0
+---
+
 # run-conftest-batch.mjs
 
 ## Огляд

package/scripts/lib/docs/run-lint-step.md

@@ -1,3 +1,9 @@
+---
+docgen:
+  source: npm/scripts/lib/run-lint-step.mjs
+  crc: 5932fa98
+---
+
 # run-lint-step.mjs
 
 ## Огляд

package/scripts/lib/docs/run-rule-cli.md

@@ -1,3 +1,9 @@
+---
+docgen:
+  source: npm/scripts/lib/run-rule-cli.mjs
+  crc: ab1715f2
+---
+
 # run-rule-cli.mjs
 
 ## Огляд

package/scripts/lib/docs/run-rule.md

@@ -1,3 +1,9 @@
+---
+docgen:
+  source: npm/scripts/lib/run-rule.mjs
+  crc: 94f3ac44
+---
+
 # run-rule.mjs
 
 ## Огляд

package/scripts/lib/docs/run-standard-lint.md

@@ -1,3 +1,9 @@
+---
+docgen:
+  source: npm/scripts/lib/run-standard-lint.mjs
+  crc: e7e3f0ae
+---
+
 # run-standard-lint.mjs
 
 ## Огляд

package/scripts/lib/docs/run-standard-rule.md

@@ -1,3 +1,9 @@
+---
+docgen:
+  source: npm/scripts/lib/run-standard-rule.mjs
+  crc: aeb5299a
+---
+
 # run-standard-rule.mjs
 
 ## Огляд

package/scripts/lib/docs/skill-meta.md

@@ -1,3 +1,9 @@
+---
+docgen:
+  source: npm/scripts/lib/skill-meta.mjs
+  crc: 0c638d18
+---
+
 # skill-meta.mjs
 
 ## Огляд

package/scripts/lib/docs/template.md

@@ -1,3 +1,9 @@
+---
+docgen:
+  source: npm/scripts/lib/template.mjs
+  crc: 3bc0617f
+---
+
 # template.mjs
 
 ## Огляд

package/scripts/lib/docs/timing-summary.md

@@ -1,3 +1,9 @@
+---
+docgen:
+  source: npm/scripts/lib/timing-summary.mjs
+  crc: f21a9b91
+---
+
 # timing-summary.mjs
 
 ## Огляд

package/scripts/lib/docs/workspaces.md

@@ -1,3 +1,9 @@
+---
+docgen:
+  source: npm/scripts/lib/workspaces.mjs
+  crc: 995c1633
+---
+
 # workspaces.mjs
 
 ## Огляд

package/scripts/lib/docs/worktree-notice.md

@@ -1,3 +1,9 @@
+---
+docgen:
+  source: npm/scripts/lib/worktree-notice.mjs
+  crc: dc4fba22
+---
+
 # worktree-notice.mjs
 
 ## Огляд

package/scripts/lib/docs/worktree.md

@@ -1,3 +1,9 @@
+---
+docgen:
+  source: npm/scripts/lib/worktree.mjs
+  crc: ffcdbca5
+---
+
 # worktree.mjs
 
 ## Огляд

package/scripts/lib/mirror-parity.mjs

@@ -56,5 +56,5 @@ export async function findMirrorDrift(repoRoot) {
     const expected = await expectedMirrorContent(m.canonicalPath)
     if (readFileSync(m.mirrorPath, 'utf8') !== expected) drift.push(m.id)
   }
-  return drift.sort()
+  return drift.toSorted()
 }

package/scripts/lib/root-notice.mjs

@@ -19,7 +19,7 @@ export const ROOT_START = '<!-- n-cursor:root:start -->'
 export const ROOT_END = '<!-- n-cursor:root:end -->'
 
 /** Наявний блок разом із сусідніми порожніми рядками (для чистого видалення). */
-const BLOCK_RE = /\n*<!-- n-cursor:root:start -->[\s\S]*?<!-- n-cursor:root:end -->\n*/u
+const BLOCK_RE = /\n{0,8}<!-- n-cursor:root:start -->[\s\S]*?<!-- n-cursor:root:end -->\n{0,8}/u
 
 /** Закриття YAML-frontmatter на початку файла. */
 const FRONTMATTER_RE = /^(---\n[\s\S]*?\n---\n)/u

package/scripts/lib/worktree-notice.mjs

@@ -25,22 +25,22 @@ export const WORKTREE_END = '<!-- n-cursor:worktree:end -->'
 const FALLBACK_SUFFIX = 'task'
 
 /** Наявний блок разом із сусідніми порожніми рядками (для чистого видалення). */
-const BLOCK_RE = /\n*<!-- n-cursor:worktree:start -->[\s\S]*?<!-- n-cursor:worktree:end -->\n*/u
+const BLOCK_RE = /\n{0,8}<!-- n-cursor:worktree:start -->[\s\S]*?<!-- n-cursor:worktree:end -->\n{0,8}/u
 
 /** Закриття YAML-frontmatter на початку файла. */
 const FRONTMATTER_RE = /^(---\n[\s\S]*?\n---\n)/u
 
 /** Значення `name` з YAML-frontmatter. */
-const NAME_RE = /^name:\s*["']?([^"'\n]+)["']?\s*$/mu
+const NAME_RE = /^name:[ \t]{0,8}["']?([^"'\n]+?)["']?[ \t]{0,8}$/mu
 
 /** Перший H1 як fallback, якщо frontmatter не містить `name`. */
-const H1_RE = /^#\s+(.+)$/mu
+const H1_RE = /^#[ \t]{1,8}(.+)$/mu
 
 const N_PREFIX_RE = /^n-/u
 const COMBINING_DIACRITICS_RE = /[̀-ͯ]/gu
 const NON_ALPHANUM_RE = /[^a-z0-9]+/gu
-const TRAILING_DASHES_RE = /^-+|-+$/gu
-const TRAILING_DASH_RE = /-+$/u
+const TRAILING_DASHES_RE = /^-{1,80}|-{1,80}$/gu
+const TRAILING_DASH_RE = /-{1,80}$/u
 const LEADING_NEWLINES_RE = /^\n+/u
 
 const CYRILLIC_TRANSLIT = new Map(

package/scripts/lib/worktree.mjs

@@ -28,7 +28,7 @@ export function sanitizeBranch(branch) {
   const sanitized = branch
     .trim()
     .replace(UNSAFE_PATH_CHARS_RE, '-')
-    .replaceAll(/^-+|-+$/gu, '')
+    .replaceAll(/^-{1,80}|-{1,80}$/gu, '')
   if (sanitized === '') {
     throw new Error(`worktree: імʼя гілки "${branch}" не містить допустимих символів`)
   }

package/scripts/sync-claude-config.mjs

@@ -32,6 +32,8 @@ import { join } from 'node:path'
 
 /** Маркер PostToolUse fix-hook'а (`npx --no \@nitra/cursor post-tool-use-fix`). */
 export const MANAGED_HOOK_COMMAND_MARKER = '@nitra/cursor post-tool-use-fix'
+/** Маркер doc-files staleness-hook'ів (PostToolUse `--hook` і Stop-гейт `--git`). */
+export const DOC_FILES_HOOK_COMMAND_MARKER = '@nitra/cursor doc-files check'
 /** Legacy-маркер старого Stop-hook'а — лишаємо для cleanup-у при оновленні існуючих інсталяцій. */
 export const LEGACY_STOP_HOOK_COMMAND_MARKER = '@nitra/cursor stop-hook'
 /** Маркер ADR Stop-hook'а — підрядок шляху до bash-скрипта capture-decisions. */
@@ -48,6 +50,7 @@ export const CURSOR_ADR_NORMALIZE_HOOK_COMMAND_MARKER = '.claude/hooks/normalize
  */
 export const MANAGED_HOOK_COMMAND_MARKERS = Object.freeze([
   MANAGED_HOOK_COMMAND_MARKER,
+  DOC_FILES_HOOK_COMMAND_MARKER,
   LEGACY_STOP_HOOK_COMMAND_MARKER,
   ADR_HOOK_COMMAND_MARKER,
   ADR_NORMALIZE_HOOK_COMMAND_MARKER

package/scripts/utils/docs/ast-scan-utils.md

@@ -1,3 +1,9 @@
+---
+docgen:
+  source: npm/scripts/utils/ast-scan-utils.mjs
+  crc: 0f9b4a21
+---
+
 # ast-scan-utils.mjs
 
 ## Огляд

package/scripts/utils/docs/ensure-gitignore-entries.md

@@ -1,3 +1,9 @@
+---
+docgen:
+  source: npm/scripts/utils/ensure-gitignore-entries.mjs
+  crc: 35e65c1b
+---
+
 # ensure-gitignore-entries.mjs
 
 ## Огляд

package/scripts/utils/docs/find-package-json-paths.md

@@ -1,3 +1,9 @@
+---
+docgen:
+  source: npm/scripts/utils/find-package-json-paths.mjs
+  crc: 06c208de
+---
+
 # find-package-json-paths.mjs
 
 ## Огляд

package/scripts/utils/docs/lock-cache-dir.md

@@ -1,3 +1,9 @@
+---
+docgen:
+  source: npm/scripts/utils/lock-cache-dir.mjs
+  crc: 3b63d4b1
+---
+
 # lock-cache-dir.mjs
 
 ## Огляд

package/scripts/utils/docs/pass.md

@@ -1,3 +1,9 @@
+---
+docgen:
+  source: npm/scripts/utils/pass.mjs
+  crc: 0f69dfba
+---
+
 # pass.mjs
 
 ## Огляд

package/scripts/utils/docs/resolve-cargo-manifest.md

@@ -1,3 +1,9 @@
+---
+docgen:
+  source: npm/scripts/utils/resolve-cargo-manifest.mjs
+  crc: af1efa42
+---
+
 # resolve-cargo-manifest.mjs
 
 ## Огляд

package/scripts/utils/docs/resolve-cmd.md

@@ -1,3 +1,9 @@
+---
+docgen:
+  source: npm/scripts/utils/resolve-cmd.mjs
+  crc: 31c290fc
+---
+
 # resolve-cmd.mjs
 
 ## Огляд

package/scripts/utils/docs/resolve-js-root.md

@@ -1,3 +1,9 @@
+---
+docgen:
+  source: npm/scripts/utils/resolve-js-root.mjs
+  crc: 2c2b9f11
+---
+
 # resolve-js-root.mjs
 
 ## Огляд

package/scripts/utils/docs/test-helpers.md

@@ -1,3 +1,9 @@
+---
+docgen:
+  source: npm/scripts/utils/test-helpers.mjs
+  crc: 0e4357fe
+---
+
 # test-helpers.mjs
 
 ## Огляд

package/scripts/utils/docs/walk-cache.md

@@ -1,3 +1,9 @@
+---
+docgen:
+  source: npm/scripts/utils/walk-cache.mjs
+  crc: 82798fa2
+---
+
 # walk-cache.mjs
 
 ## Огляд

package/scripts/utils/docs/walkDir.md

@@ -1,3 +1,9 @@
+---
+docgen:
+  source: npm/scripts/utils/walkDir.mjs
+  crc: 5e5fec27
+---
+
 # walkDir.mjs
 
 ## Огляд

package/scripts/utils/docs/worktree-fingerprint.md

@@ -1,3 +1,9 @@
+---
+docgen:
+  source: npm/scripts/utils/worktree-fingerprint.mjs
+  crc: df297382
+---
+
 # worktree-fingerprint.mjs
 
 ## Огляд

package/scripts/utils/resolve-js-root.mjs

@@ -27,7 +27,7 @@ async function expandWorkspacePattern(cwd, pattern) {
     const wsRel = rel.replace(PACKAGE_JSON_SUFFIX_RE, '')
     results.push(join(cwd, wsRel))
   }
-  return results.sort()
+  return results.toSorted()
 }
 
 /**

package/skills/doc-aggregate/SKILL.md

@@ -0,0 +1,129 @@
+---
+name: doc-aggregate
+description: >-
+  Агрегуюча документація за запитом: module-summary на кожен логічний модуль (docs/ARCHITECTURE.md) і доменні доки бізнес-процесів у кореневій docs/ — синтез поверх готових файлових док (doc-files), батч-диспатч субагентів у worktree
+---
+
+# doc-aggregate — агрегуюча документація (за запитом)
+
+## Мета
+
+Синтезувати документацію вищого рівня поверх **готових файлових док** (їх підтримує
+обовʼязковий скіл `doc-files`). Два рівні, строго послідовно:
+
+1. **Tier 2 — module-summary**: `<module_root>/docs/ARCHITECTURE.md`, субагент на модуль.
+2. **Tier 3 — доменні доки**: `docs/<домен>.md` у кореневій `docs/`, субагент-синтезатор
+   виділяє бізнес-домени й пише файл на кожен домен.
+
+Агрегат ніколи не випереджає джерело: Tier 3 — лише після завершення всього Tier 2.
+Цей скіл викликається **за запитом** (не обовʼязковий крок задачі).
+
+## ⚠️ Паралелізм
+
+Tier 2 — батчами **по 5** субагентів одночасно (кожен пише свій файл, гонок немає).
+Tier 3 — **один** субагент-синтезатор після завершення всього Tier 2.
+
+## Передумова
+
+- Доступний `npx @nitra/cursor`.
+- Файлові доки мають бути свіжі. Перевір і за потреби онови перед агрегацією:
+
+```bash
+npx @nitra/cursor doc-files check --git
+```
+
+Якщо багато застарілих — спершу прожени `npx @nitra/cursor doc-files gen`.
+
+## Крок 1: Tier 2 — module-summary
+
+Зібрати список модулів:
+
+```bash
+npx @nitra/cursor doc-aggregate modules
+```
+
+Команда друкує JSON-масив (усі шляхи абсолютні):
+
+```json
+[
+  {
+    "moduleRoot": "/abs/npm/rules/adr",
+    "relRoot": "npm/rules/adr",
+    "slug": "npm-rules-adr",
+    "docPath": "/abs/npm/rules/adr/docs/ARCHITECTURE.md",
+    "members": ["npm/rules/adr/index.mjs"],
+    "exists": false
+  }
+]
+```
+
+module-summary **завжди регенерується** (це агрегат — поле `exists` ігноруй). Розбий модулі
+на батчі по 5 і диспатч субагентів. Промпт кожного (підстав `relRoot`, `docPath`, `members`):
+
+```
+Напиши module-summary для одного логічного модуля.
+
+МОДУЛЬ: <relRoot>
+ЗАПИСАТИ В: <docPath>
+ФАЙЛИ МОДУЛЯ (members): <members>
+
+Кроки:
+1. Прочитай файлові доки членів модуля. <member> — sourcePath відносно кореня проєкту
+   (= поточний CWD); його файлова дока — <CWD>/<dir>/docs/<stem>.md. За потреби зазирни
+   в самі файли.
+2. Створи теку для <docPath>, якщо її немає.
+3. Запиши markdown у <docPath> за тими ж правилами стилю, що й файлова дока
+   (українська, чистий Markdown, контекстна незалежність, без HTML).
+
+Секції module-summary:
+## Огляд модуля — призначення модуля <relRoot>, його роль у проєкті.
+## Ключові файли — список із кліковими посиланнями (відносними до розташування цього
+   ARCHITECTURE.md) на члени модуля та їхні файлові доки.
+## Публічний API — що модуль експортує назовні.
+## Внутрішній потік — як компоненти модуля взаємодіють.
+## Підмодулі — вкладені модулі, якщо є.
+
+Поверни лише підтвердження, що файл <docPath> записано.
+```
+
+## Крок 2: Tier 3 — доменні доки
+
+Після завершення **всіх** module-summary диспатч **одного** субагента-синтезатора.
+У промпт підстав конкретний перелік шляхів module-summary (`<module_root>/docs/ARCHITECTURE.md`
+кожного модуля з виводу `doc-aggregate modules`), а не інструкцію їх шукати. Промпт:
+
+```
+Синтезуй доменну документацію бізнес-процесів проєкту.
+
+ДЖЕРЕЛА (module-summary, читай усі): <перелік шляхів ARCHITECTURE.md, підставлений вище>
+
+Кроки:
+1. Прочитай усі module-summary.
+2. Виділи бізнес-домени та процеси (можуть перетинати межі модулів). Доменів може бути багато.
+3. Для КОЖНОГО домену запиши окремий файл docs/<домен>.md у кореневій docs/:
+   - назва файлу — короткий kebab-slug домену;
+   - не перезаписуй файлові доки кореневих файлів у docs/ (напр. app.md, eslint.config.md):
+     якщо слаґ домену збігається з іменем такого файлу — додай суфікс -domain
+     (напр. app-domain.md). Інакше пиши docs/<домен>.md як є;
+   - опиши бізнес-процес домену з кліковими відносними посиланнями на module-summary, конкретні файли й директорії.
+
+Правила стилю — ті ж (українська, чистий Markdown, контекстна незалежність, без HTML).
+
+Поверни перелік створених файлів docs/<домен>.md.
+```
+
+## Крок 3: Підсумок
+
+```
+✓ doc-aggregate завершено.
+Tier 2 (модулі): <M> module-summary.
+Tier 3 (домени): <D> доменних доків у docs/.
+```
+
+Перелічи файли з помилками (субагент впав або не записав `docPath`), якщо такі є.
+Помилка одного модуля не зупиняє решту.
+
+## Нотатки
+
+- Не комітити автоматично — користувач вирішує, коли комітити згенеровану доку.
+- Файлові доки (Tier 1) — окремий обовʼязковий скіл `doc-files`; цей скіл їх не пише, лише агрегує.

package/skills/doc-aggregate/js/docgen-ignore.mjs

@@ -0,0 +1,9 @@
+/**
+ * Re-export спільного списку ignore-глобів зі скіла doc-files.
+ *
+ * Канонічне джерело — `npm/skills/doc-files/js/docgen-ignore.mjs`: обидва скіли
+ * (file-level доки і агрегати) мусять бачити однакове дерево кодових файлів,
+ * інакше агрегат посилатиметься на файли без док (або навпаки). Залежність
+ * спрямована doc-aggregate → doc-files за ADR про розбиття docgen.
+ */
+export * from '../../doc-files/js/docgen-ignore.mjs'