@nitra/cursor 5.3.4 → 6.0.0

package/scripts/utils/docs/with-lock.md

@@ -1,25 +1,32 @@
+---
+docgen:
+  source: npm/scripts/utils/with-lock.mjs
+  crc: 21848085
+  score: 95
+---
+
 # with-lock.mjs
 
 ## Огляд
 
-Цей файл реалізує механізм захисту від одночасного виконання критичних операцій, забезпечуючи атомарний lock та дедуплікацію даних для інтенсивних команд. Він використовується для запобігання конфліктів при одночасному виконанні операцій, які можуть призвести до пошкодження даних або непередбачуваних результатів. Механізм гарантує, що кожен прогін операцій виконується без повторень та з атомарним lock.
+Файл реалізує механізм захисту важких команд через атомарне блокування та унікалізацію результатів. Функції дозволяють перевіряти можливість повторного використання результату з кешу та виконувати команду через серіалізований механізм. Механізм використовує `mkdirSync-based lock` та `sha256-dedup` з TTL.
 
 ## Поведінка
 
-- `shouldDedup`: Перевіряє, чи можна повторно використати кешований результат, враховуючи код виходу, відбитковий дерева та час завершення.
-- `withLock`: Встановлює lock-директорію, запускає вказану функцію, кешує результат та повторно використовує його, якщо можливо, з використанням дедуплікації за відбитком.
+shouldDedup
+Перевіряє можливість повторного використання результату з кешу.
+
+withLock
+Серіалізує важку команду через атомарний lock та dedup.
 
 ## Публічний API
 
-- shouldDedup — Перевіряє, чи можна використовувати попередньо обчислену відповідь для уникнення повторних обчислень.
-- withLock — Забезпечує унікальність виконання важкої операції за допомогою блокування та перевірки на основі відбитків.
+shouldDedup — Чи можна пропустити повторний прогін за кешованим result.json.
+withLock — Серіалізує важку команду через атомарний lock і dedup за fingerprint.
 
 ## Гарантії поведінки
 
-- **Атомарність:** Операції lock та dedup виконуються як атомарні дії.
-- **Захист від помилок:** У разі виникнення помилки, функція повертає `false` та `null`.
-- **Детектування неактивного PID:** Перевіряється, чи процес, що утримує lock, все ще активний.
-- **Дедуплікація з обмеженням часу:** Проводиться дедуплікація за допомогою SHA256 з обмеженням часу (TTL).
-- **Кешування:** Результати прогону кешуються для прискорення наступних проходів.
-- **Відсутність винятків:** Функції не викликають винятків.
-- **Створення директорій:** Використовується `mkdirSync` для створення директорій.
+- Перехоплює помилки і не пропускає винятків назовні (fail-safe).
+- За невдачі повертає значення помилки (`false`/`null`/`Err`) замість генерування винятку чи паніки.
+- Кешує результати в межах одного прогону.
+- Не звертається до мережі.

package/scripts/utils/with-lock.mjs

@@ -126,9 +126,11 @@ export async function withLock(key, runFn, opts = {}) {
     /* result.json не існує або пошкоджений */
   }
 
-  const onSignal = () => {
+  // Після release лок ре-рейзиться той самий сигнал: `once` вже зняв обробник,
+  // тож процес завершується дефолтною дією з коректним кодом (130/143)
+  const onSignal = signal => {
     release()
-    process.exit(130)
+    process.kill(process.pid, signal)
   }
   process.once('SIGINT', onSignal)
   process.once('SIGTERM', onSignal)

package/skills/doc-aggregate/SKILL.md

@@ -29,10 +29,10 @@ Tier 3 — **один** субагент-синтезатор після зав
 - Файлові доки мають бути свіжі. Перевір і за потреби онови перед агрегацією:
 
 ```bash
-npx @nitra/cursor doc-files check --git
+npx @nitra/cursor lint-doc-files --git
 ```
 
-Якщо багато застарілих — спершу прожени `npx @nitra/cursor doc-files gen`.
+Якщо багато застарілих — спершу прожени `npx @nitra/cursor fix-doc-files`.
 
 ## Крок 1: Tier 2 — module-summary
 

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

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

package/skills/doc-aggregate/js/docs/docgen-ignore.md

@@ -1,7 +1,7 @@
 ---
 docgen:
   source: npm/skills/doc-aggregate/js/docgen-ignore.mjs
-  crc: 8821af65
+  crc: 5faaffd0
 ---
 
 # docgen-ignore

package/skills/doc-aggregate/js/docs/docgen-scan.md

@@ -0,0 +1,78 @@
+---
+docgen:
+  source: npm/skills/doc-aggregate/js/docgen-scan.mjs
+  crc: 193dd362
+  score: 100
+---
+
+# docgen-scan.mjs
+
+## Огляд
+
+isSourceFile
+Перевіряє, чи є файл коду, який слугує джерелом для документування.
+
+scanSourceFiles
+Рекурсивно збирає кодові файли проєкту за позикс-шляхами від кореня.
+
+slugForModule
+Генерує стабільний slug модуля на основі його відносного шляху.
+
+findModuleRoots
+Знаходить абсолютні шляхи коренів модулів, використовуючи дані з package.json.
+
+nearestModuleRoot
+Визначає найближчий модуль-предок для заданого файлу серед усіх доступних коренів модулів.
+
+scanForModules
+Лістить логічні модулі, збираючи члени-файли та інформацію про наявність документації.
+
+resolveRoot
+Парсить аргументи для визначення абсолютної кореневої директорії.
+
+runDocAggregateModulesCli
+Сканує модулі та виводить масив JSON у stdout.
+
+## Поведінка
+
+isSourceFile
+Перевіряє, чи є файл кодовим джерелом для документування
+
+scanSourceFiles
+Рекурсивно збирає кодові файли проєкту по позикс-шляхах від кореня
+
+slugForModule
+Генерує стабільний slug модуля з його відносним шляхом
+
+findModuleRoots
+Знаходить абсолютні шляхи коренів модулів з файлами package.json
+
+nearestModuleRoot
+Знаходить найближчий модуль-предок для файлу серед наявних коренів модулів
+
+scanForModules
+Лістить логічні модулі, збираючи члени-файли та інформацію про наявність документації
+
+resolveRoot
+Парсить аргументи для визначення абсолютного кореня
+
+runDocAggregateModulesCli
+Сканує модулі та виводить JSON-масив у stdout
+
+## Публічний API
+
+- isSourceFile — визначає, чи є файл коду для документування.
+- scanSourceFiles — рекурсивно збирає файли коду проєкту (від кореня за POSIX-шляхом).
+- slugForModule — генерує стабільний slug модуля з його відносним шляхом (для лейблів/логів).
+- findModuleRoots — знаходить кореневі директорії модулів у `package.json` (корінь — це модуль).
+- nearestModuleRoot — визначає найближчий модуль-предок для файлу (найдовший збіг шляху).
+- scanForModules — лістить логічні модулі проєкту з членами-файлами та `docPath module-summary`. Пропускає модулі без кодових файлів.
+- resolveRoot — парсить аргумент `--root <dir>`; за замовчуванням використовує поточну директорію.
+- runDocAggregateModulesCli — виконує команду `doc-aggregate modules`, скануючи модулі та виводячи JSON-масив у stdout.
+
+## Гарантії поведінки
+
+- Read-only: файл не виконує операцій запису у файлову систему.
+- Перехоплює помилки і не пропускає винятків назовні (fail-safe).
+- За невдачі повертає значення помилки (`false`/`null`/`Err`) замість генерування винятку чи паніки.
+- Не звертається до мережі.

package/skills/doc-files/.changes/260612-0031.md

@@ -0,0 +1,5 @@
+---
+bump: patch
+section: Changed
+---
+стале-доки після Rust: оновлено CRC для docgen-prompts, docgen-scan, units-rs; додано units-js.md; тести extractFacts(.rs)

package/skills/doc-files/.changes/260612-0036.md

@@ -0,0 +1,5 @@
+---
+bump: patch
+section: Added
+---
+docs: units.md (docgen для units.mjs — фасад Rust/JS)

package/skills/doc-files/.changes/260612-0114.md

@@ -0,0 +1,5 @@
+---
+bump: patch
+section: Added
+---
+doc-files: регенерація всіх stale doc-файлів; manifests.mjs (303KB) → docgen-ignore

package/skills/doc-files/SKILL.md

@@ -31,7 +31,7 @@ docgen:
 ## Оркестрацію веде JS, не модель; конвеєр — local-only
 
 Уся важка робота — черга, батчинг, виклики LLM і штамп CRC — живе в JS-команді
-`doc-files gen`. **Ти не диспатчиш субагентів і не тримаєш сотні файлів у контексті**
+`fix-doc-files`. **Ти не диспатчиш субагентів і не тримаєш сотні файлів у контексті**
 — тому навіть масовий перший прогін усього репо не «заморює». Цей скіл **тонкий**: твоє завдання —
 запустити генерацію і прочитати підсумок.
 
@@ -50,7 +50,7 @@ docgen:
 ### Крок 1: Генерація застарілих/відсутніх док
 
 ```bash
-npx @nitra/cursor doc-files gen
+npx @nitra/cursor fix-doc-files
 ```
 
 Команда сама: перевіряє omlx (preflight: «сервер лежить» / «модель не влазить у пам'ять
@@ -66,18 +66,18 @@ npx @nitra/cursor doc-files gen
 
 Дочекайся підсумку `✓ OK: <N>  ⚠ degraded: <D>  ✗ Err: <E>`. Якщо є помилки — перелічи
 проблемні файли. Exit-код `1` означає, що хоча б один файл не згенерувався (або не пройшов
-preflight). Degraded — не помилка: дока існує, борг видно у `check --degraded`.
+preflight). Degraded — не помилка: дока існує, борг видно у `lint-doc-files --degraded`.
 
 ### Крок 3 (за потреби): перевірка перед завершенням
 
 ```bash
-npx @nitra/cursor doc-files check --git
+npx @nitra/cursor lint-doc-files --git
 ```
 
 Перевіряє змінені у задачі джерела (`git diff --name-only HEAD`) проти CRC їхніх док.
 Цю ж перевірку виконує **Stop-hook** як твердий гейт: завершити задачу зі застарілими
 доками не можна (виняток — масовий прогін понад поріг `N_CURSOR_DOC_FILES_GATE_MAX`, дефолт 50).
-Degraded-доки гейт **не** блокує (CRC свіжий); їх список — `doc-files check --degraded`.
+Degraded-доки гейт **не** блокує (CRC свіжий); їх список — `lint-doc-files --degraded`.
 
 ## Правила стилю документа (за adr/ci4)
 
@@ -97,4 +97,4 @@ Degraded-доки гейт **не** блокує (CRC свіжий); їх спи
   усі теки `docs/`, а також `*.test.*` / `*.spec.*` / `*.d.ts`. Кореневий repo `docs/` —
   system-wide only: file-level docs туди не пишуться. Список glob-ів — `docgen-ignore.mjs`.
 - Агрегуюча документація (module-summary, доменні доки) — окремий скіл `doc-aggregate`, за запитом.
-- Для наявних док без CRC одноразово: `npx @nitra/cursor doc-files stamp` (штампує frontmatter без LLM).
+- Для наявних док без CRC одноразово: `npx @nitra/cursor fix-doc-files --stamp` (штампує frontmatter без LLM).

package/skills/fix/js/docs/llm-worker.md

@@ -1,33 +1,35 @@
 ---
 docgen:
   source: npm/skills/fix/js/llm-worker.mjs
-  crc: 8317f878
+  crc: 6507b5b7
+  score: 100
 ---
 
 # llm-worker.mjs
 
 ## Огляд
 
-Цей файл є LLM-робітником, який збирає контекст для n-fix оркестратора, зокрема правила з файлів .mdc та звіти про порушення. Він передає цей контекст великій мовній моделі (LLM) для генерації JSON з пропозиціями змін. Після отримання змін, скрипт застосовує їх до відповідних ресурсів.
+MODEL визначає основну модель для виконання операцій. MODEL_HEAVY визначає модель для посиленої обробки. runLlmWorker корегує одне визначене правило порушення через LLM.
 
 ## Поведінка
 
-runLlmWorker: Виправляє одне rule-порушення через pi (C1 pattern). Збирає контекст з rule .mdc, файлів з violation output, та передає його в pi для отримання JSON зі змінами. Застосовує зміни, якщо вони були отримані від pi. Якщо pi не повернув JSON, або не зміг застосувати зміни, повертає помилку. Використовує модель Claude HAIKU за замовчуванням, або модель, вказану в опціях.
+MODEL
+Визначає модель за замовчуванням для роботи.
+
+MODEL_HEAVY
+Визначає модель для важкої ескалації.
+
+runLlmWorker
+Виправляє одне правило порушення через LLM.
 
 ## Публічний API
 
-MODEL_HAIKU — Генерує короткі вірші.
-MODEL_SONNET — Генерує вірші у форматі сонету.
-runLlmWorker — Виправляє порушення правил, використовуючи pi (C1 pattern).
+MODEL — Створює модель.
+MODEL_HEAVY — Створює важку модель.
+runLlmWorker — Виправляє одне порушення правила через pi (C1 pattern).
 
 ## Гарантії поведінки
 
-- Приймає контекст з файлів `.mdc` та файлів з violation.
-- Повертає JSON з пропозиціями змін.
-- Застосовує зміни, отримані від `pi`.
-- Використовує LLM для генерації змін.
-- Викликає LLM через `pi`.
-- Не використовує tool-use.
-- Не кидає винятків.
-- У разі невдачі повертає `false` та `null`.
-- Не використовує кешування.
+- Перехоплює помилки і не пропускає винятків назовні (fail-safe).
+- За невдачі повертає значення помилки (`false`/`null`/`Err`) замість генерування винятку чи паніки.
+- Не звертається до мережі.

package/skills/fix/js/docs/orchestrator.md

@@ -1,38 +1,45 @@
 ---
 docgen:
   source: npm/skills/fix/js/orchestrator.mjs
-  crc: 8b7a7de5
+  crc: e77aaf7b
+  score: 100
 ---
 
 # orchestrator.mjs
 
 ## Огляд
 
-Файл `convergence-loop` є автономним оркестратором для n-fix, який забезпечує перевірку та виправлення коду без участі LLM. Він ініціює детерміністичні перевірки, regex-парсинг та ітеративні процеси з використанням LLM для вирішення складних проблем. Цей компонент є ключовим елементом системи, що автоматизує процес забезпечення коректності коду n-fix.
+runOrchestratorCli
+Запускає ітеративний цикл для перевірки набору правил. Проходить через кроки T0-auto та T1, взаємодіючи з LLM-воркерами. Завершує роботу, перевіряючи, чи всі правила виконані, повертаючи нуль або одиницю залежно від кінцевого стану.
 
 ## Поведінка
 
-1.  **Ініціалізація:** Запускається оркестратор, визначаються максимальна кількість ітерацій (за замовчуванням 3) та порогове значення для ескалації LLM (за замовчуванням 2 невдачі).
-2.  **Первинна перевірка:** Виконується детермінована перевірка (T0) на основі заданих правил, без залучення LLM. Результат перевірки записується.
-3.  **Автоматичний фікс (T0-auto):** Якщо перевірка виявила порушення, запускається автоматичний фікс, який використовує regex для виявлення та виправлення проблем.
-4.  **Ітерація:** Програма повторює наступні кроки до досягнення максимальної кількості ітерацій:
-    - **Перевірка (T0):** Виконується детермінована перевірка (T0) на основі поточного стану.
-    - **Автоматичний фікс (T0-auto):** Якщо перевірка виявила порушення, запускається автоматичний фікс.
-    - **Виклик LLM (T1):** Для кожного порушення, яке не було виправлено автоматичним фіксом, викликається LLM (haiku або sonnet, залежно від кількості попередніх невдач) для генерації рішення.
-    - **Оцінка рішення LLM:** LLM генерує рішення, яке оцінюється на предмет успіху.
-    - **Оновлення стану:** Якщо рішення LLM успішне, порушення виправляється, і кількість невдалих спроб LLM для цього правила встановлюється на нуль.
-5.  **Фінальна перевірка:** Після завершення всіх ітерацій виконується остаточна перевірка, щоб визначити, чи були виправлені всі порушення.
-6.  **Повернення результату:** Оркестратор повертає код 0, якщо всі правила були виправлені, і код 1, якщо хоча б одне правило залишилося не виправленим. У випадку помилки парсингу JSON, повертається null.
+1. Парсинг аргументів
+    Приймає аргументи командного рядка після 'fix'
+    Визначає максимальну кількість ітерацій
+    Визначає фільтр правил
+2. Початкова перевірка
+    Запускає перевірку стану
+    Отримує початковий набір правил
+    Перевіряє наявність помилок
+3. Ітеративний цикл
+    Повторює ітерації до максимального ліміту
+    Виконує крок T0-auto
+    Перевіряє кількість провалів після кроку T0
+    Якщо провалів немає, завершує цикл
+    Виконує крок T1
+    Запускає роботу з LLM-воркерами для кожного правила
+    Збільшує лічильник провалів для невдалих правил
+    Перевіряє стан після LLM
+    Перевіряє наявність невирішених правил
+4. Завершення
+    Перевіряє, чи всі правила вирішено
+    Повертає нуль у разі чистого стану
+    Повертає одиницю у разі невирішеного стану
 
 ## Гарантії поведінки
 
-- Оркестратор запускається при виклику `runOrchestratorCli`.
-- Програма виконує цикл з перевірок, поки не буде досягнуто максимальну кількість ітерацій (`maxIter`).
-- Після кожної ітерації (`T0`, `T0-auto`, `T1`) виконується перевірка.
-- `T0` виконується детерміновано без використання LLM.
-- `T0-auto` виконує regex-парсинг та застосовує програмний фікс у разі виявлення порушення.
-- `T1` використовує LLM через `pi` (ескалація до `haiku` та `sonnet`).
-- `check-gate` повторно запускає `T0` після кожної ітерації.
-- У разі помилки програма повертає `false` або `null`.
-- Програма кешує результати для оптимізації роботи в межах одного запуску.
-- Програма не взаємодіє з мережею.
+- Read-only: файл не виконує операцій запису у файлову систему.
+- Перехоплює помилки і не пропускає винятків назовні (fail-safe).
+- За невдачі повертає значення помилки (`false`/`null`/`Err`) замість генерування винятку чи паніки.
+- Не звертається до мережі.

package/skills/fix/js/docs/t0.md

@@ -1,29 +1,39 @@
+---
+docgen:
+  source: npm/skills/fix/js/t0.mjs
+  crc: 51311329
+  score: 90
+---
+
 # t0.mjs
 
 ## Огляд
 
-Файл `t0-auto` забезпечує детермінований рівень виправлень для n-fix оркестратора, автоматично застосовуючи програмні фікси на основі аналізу вихідних даних `n-cursor fix --json`. Він парсить повідомлення про порушення, видобуваючи з них інформацію про цільові файли або рядки для вставки, і застосовує відповідні фікси. Це дозволяє швидко та передбачувано виправляти помилки, не використовуючи LLM, і є першим етапом у конвергентному циклі виправлення.
+applyT0Auto застосовує паттерни T0-auto до вихідного результату.
+
+filterT0AutoRules фільтрує список правил, для яких присутній хоча б один T0-auto паттерн.
+
+runT0AutoCli запускає перевірку, застосовує T0-auto до провальних правил, виводить результат та перевіряє стан через check-gate.
 
 ## Поведінка
 
-applyT0Auto: Застосовує всі T0-auto паттерни до вхідного `violationOutput` та повертає об'єкт, що вказує, чи застосовано фікс, та список виконаних дій.
-filterT0AutoRules: Повертає список id правил, для яких є хоч один T0-auto паттерн, на основі `failedRules`.
-runT0AutoCli: Запускає `n-cursor fix --json`, застосовує T0-auto, повторно перевіряє check-gate та виводить підсумок. Повертає 0 у разі успіху, 1 у разі помилки.
+applyT0Auto
+Застосовує паттерни T0-auto до одного вихідного результату
+
+filterT0AutoRules
+Фільтрує список правил, для яких існує хоча б один T0-auto паттерн
+
+runT0AutoCli
+Запускає перевірку, застосовує T0-auto до провальних правил, виводить результат та перевіряє стан через check-gate
 
 ## Публічний API
 
-- applyT0Auto — Застосовує автоматичні правила виправлення до виявлених проблем.
-- filterT0AutoRules — Визначає ідентифікатори правил, які мають T0-auto паттерни.
-- runT0AutoCli — Запускає CLI-інструмент для автоматичного виправлення, включаючи перевірку та звітність.
+- applyT0Auto — застосовує всі T0-auto шаблони до одного виводу порушення.
+- filterT0AutoRules — повертає ідентифікатори правил, що мають хоча б один T0-auto шаблон у виводі порушення.
+- runT0AutoCli — виконує команду `n-cursor fix-t0 [правило...]`.
+  - Запускає `fix --json`, застосовує T0-auto до кожного порушення, повторно перевіряє check-gate, виводить звіт.
 
 ## Гарантії поведінки
 
-- `applyT0Auto` застосовує програмний фікс, якщо `violationOutput` містить інформацію, яку можна видобути за допомогою регулярних виразів, і `violation-message` містить цільове значення, що відповідає одному з ідентифікаторів правил T0-auto. Результат: `applied` - boolean, `actions` - string[] (список виконаних дій).
-- `listT0AutoRules` повертає список ідентифікаторів правил T0-auto, які мають хоча б один паттерн.
-- `runT0AutoCli` повертає код виходу 0, якщо процес виконано успішно, і 1, якщо виявлено порушення.
-- T0-auto запускається першим у конвергентному циклі.
-- T1 запускається лише для решти.
-- Система перехоплює помилки та не кидає винятки.
-- В системі немає кешування.
-- Вхідні дані `applyT0Auto` повинні відповідати формату JSON, вихідному від `n-cursor fix --json`.
-- Якщо `violation-message` не містить інформації, яку можна видобути за допомогою регулярних виразів, `applyT0Auto` не виконує жод
+- Перехоплює помилки і не пропускає винятків назовні (fail-safe).
+- Не звертається до мережі.

package/skills/start-check/js/docs/check.md

@@ -1,40 +1,44 @@
 ---
 docgen:
   source: npm/skills/start-check/js/check.mjs
-  crc: 1809127a
+  crc: 1f8fb2f0
+  score: 95
 ---
 
 # check.mjs
 
 ## Огляд
 
-Файл `n-cursor start-check scan|run` є частиною smoke-перевірки для скілу `n-start-check`. Він автоматично аналізує та запускає воркспейси, визначаючи тип стартового скрипта (сервер чи CLI) та перевіряючи успішність його виконання з обмеженням часу. Результати аналізу та запуску записуються у форматі JSON для подальшого аналізу та діагностики проблем.
+Файл надає інструменти для класифікації типів процесу, сканування конфігурації воркспейсів, парсингу логів та запуску скриптів.
 
 ## Поведінка
 
-- `classifyStartType` визначає, чи є команда `start` CLI чи довгим процесом (сервером).
-- `scanStartWorkspaces` сканує монорепо, визначаючи воркспейси з `start`, їхні команди та типи.
-- `parseStartLog` витягує готовність, першу помилку та хвіст логу з процесу.
-- `runWorkspaceStart` запускає команду `start` воркспейсу з grace-таймаутом, класифікує результат та повертає інформацію про процес.
-- `runStartCheckCli` виконує `scan` або `run` воркспейсу, приймаючи аргументи командного рядка.
+classifyStartType
+Визначає тип процесу як сервер чи CLI на основі команди.
+
+scanStartWorkspaces
+Сканує монорепо для отримання інформації про наявність та конфігурацію `start` скриптів у воркспейсах.
+
+parseStartLog
+Парсить лог процесу для визначення готовності, першої помилки та останніх рядків.
+
+runWorkspaceStart
+Запускає `start` для одного воркспейсу з тайм-аутом і класифікує результат.
+
+runStartCheckCli
+Обробляє аргументи командного рядка для сканування або запуску тестування воркспейсів.
 
 ## Публічний API
 
-- classifyStartType — Визначає, чи є команда `start` сервером або CLI.
-- scanStartWorkspaces — Перевіряє монорепо на наявність команди `start` та її типу у кожному воркспейсі.
-- parseStartLog — Аналізує лог процесу `start` для виявлення статусу, помилок та кінця.
-- runWorkspaceStart — Запускає команду `start` у воркспейсі з обмеженим часом та визначає результат.
-- runStartCheckCli — Запускає CLI для сканування воркспейсів з `start` та індивідуального запуску воркспейсу з подальшим виводом результатів у JSON.
+- classifyStartType — визначає, чи команда `start` належить до довготривалого процесу (серверу) чи одноразової дії (CLI).
+- scanStartWorkspaces — переглядає монорепо, витягуючи команду `start`, її команду та тип для кожного воркспейсу.
+- parseStartLog — витягує з логу стадії: готовність (сервер), перша помилка або фінальний результат.
+- runWorkspaceStart — ініціює запуск `start` для одного воркспейсу з обмеженням часу та класифікує отриманий результат.
+- runStartCheckCli — CLI-команда: команда `scan` генерує список воркспейсів зі `start`; команда `run <ws>` запускає один воркспейс і виводить класифікований результат у stdout.
 
 ## Гарантії поведінки
 
-- Скрипт детерміновано виконує перевірку запуску воркспейса.
-- Скрипт використовує `spawnSync` з таймаутом для запуску процесів.
-- Скрипт інтерпретує exit-коди та парсить логи.
-- Результат перевірки воркспейса представлений у форматі `[{workspace, name, hasStart, startCmd, type}]`.
-- У разі невдачі перевірки, скрипт повертає `false` або `null`.
-- Скрипт не кидає винятків.
-- Скрипт не використовує кешування.
-- Скрипт не взаємодіє з мережею.
-- Результат запуску воркспейса представлений у форматі `{workspace, type, exitCode, timedOut, status, ready, firstError, logTail, sideEffects}`.
-- `sideEffects` містить відкат стану воркспейса до його початкового стану перед запуском.
+- Read-only: файл не виконує операцій запису у файлову систему.
+- Перехоплює помилки і не пропускає винятків назовні (fail-safe).
+- За невдачі повертає значення помилки (`false`/`null`/`Err`) замість генерування винятку чи паніки.
+- Не звертається до мережі.

package/skills/taze/js/docs/diff.md

@@ -1,33 +1,57 @@
+---
+docgen:
+  source: npm/skills/taze/js/diff.mjs
+  crc: fe4d76ce
+  score: 100
+---
+
 # diff.mjs
 
 ## Огляд
 
-Файл `n-cursor taze diff` порівнює поточну версію `package.json` з її резервною копією (`package.json.taze-bak`) для виявлення змін залежностей. Він класифікує ці зміни за семантикою версій (major, minor, patch) та надає список оновлень, які потребують уваги. Це автоматизує процес, який раніше виконувався вручну, забезпечуючи швидкий та точний аналіз змін у залежностях монорепо.
+parseVersion
+Парсить версію з specifier.
+
+isBreaking
+Перевіряє перехід версій згідно з caret-семантикою.
+
+diffPackageJson
+Порівнює об'єкти package.json і повертає зміни залежностей.
+
+collectTazeDiff
+Збирає diff по всьому монорепо порівнюючи бекап та новий файл.
+
+runTazeCli
+Друкує результат diff у форматі JSON.
 
 ## Поведінка
 
-`parseVersion` парсує версійний specifier, ігноруючи range-префікси, і повертає об'єкт з major, minor та patch компонентами, або null, якщо spec не є semver.
-`isBreaking` визначає, чи є перехід від старої до нової версії "breaking" за caret-семантикою.
-`diffPackageJson` порівнює два об'єкти `package.json`, виявляє major-оновлення та підраховує minor/patch зміни для залежностей.
-`collectTazeDiff` збирає diff по всіх воркспейсах монорепо, порівнюючи `package.json` з бекапом, та повертає список major-оновлень, кількість minor/patch змін, загальну кількість порівняних воркспейсів та кількість воркспейсів, які були порівняні.
-`runTazeCli` запускає CLI `n-cursor taze diff`, збирає diff по воркспейсах, та виводить результат у форматі JSON.
+parseVersion
+Парсить версію з specifier
+
+isBreaking
+Перевіряє перехід версій згідно з caret-семантикою
+
+diffPackageJson
+Порівнює об'єкти package.json і повертає зміни залежностей
+
+collectTazeDiff
+Збирає diff по всьому монорепо порівнюючи бекап та новий файл
+
+runTazeCli
+Друкує результат diff у форматі JSON
 
 ## Публічний API
 
-- parseVersion — Розбирає semver-версію з специфікатора.
-- isBreaking — Визначає, чи є перехід breaking за caret-семантикою.
-- diffPackageJson — Порівнює два package.json-об'єкти та визначає зміни залежностей.
-- collectTazeDiff — Збирає diff для монорепо, порівнюючи package.json з резервною копією.
-- runTazeCli — Запускає CLI для виведення компактного JSON з інформацією про major-оновлення та кількість minor/patch.
+parseVersion — витягує версію з specifier-а, ігноруючи range-префікси.
+isBreaking — визначає, чи є перехід між версіями breaking за caret-семантикою (зміна найлівішої ненульової частини).
+diffPackageJson — порівнює два package.json-об'єкти та генерує список змін залежностей.
+collectTazeDiff — збирає різницю між версіями всього монорепо, порівнюючи `package.json` з його резервною копією у кожному воркспейсі.
+runTazeCli — виконує команду `n-cursor taze diff` для виведення компактного JSON зі списком major-оновлень та лічилки minor/patch.
 
 ## Гарантії поведінки
 
-- Скрипт повертає `true`, якщо всі воркспейси монорепо успішно порівняні.
-- Скрипт повертає `false` та `null`, якщо виникла будь-яка помилка під час порівняння.
-- Результат порівняння завжди є `null`, якщо `package.json` або `package.json.taze-bak` не є валідним JSON.
-- Результат порівняння містить список major-оновлень, визначених за caret-семантикою.
-- Minor та patch оновлення не включаються в результат.
-- Результат завжди детермінований, тобто при однаковому вході скрипт завжди повертає однаковий результат.
-- Скрипт не використовує кешування.
-- Скрипт не кидає винятків.
-- Скрипт перехоплює помилки та повертає `false` та `null`.
+- Read-only: файл не виконує операцій запису у файлову систему.
+- Перехоплює помилки і не пропускає винятків назовні (fail-safe).
+- За невдачі повертає значення помилки (`false`/`null`/`Err`) замість генерування винятку чи паніки.
+- Не звертається до мережі.