@nitra/cursor 3.21.1 → 3.23.0

package/skills/docgen/js/docgen-scan.mjs

@@ -1,27 +1,35 @@
 /**
  * docgen scanner — детермінований обхід проєкту для скілу `docgen`.
  *
- * Друкує JSON-список кодових файлів із обчисленим `docPath` (тека `docs/` поряд із
- * джерелом). Рішення про overwrite/skip приймає скіл — scanner лише лістить і ставить
- * прапор `exists`. LLM/мережі тут немає: уся генерація доки — у субагентах скілу.
+ * Друкує JSON-список кодових файлів із відносними `sourcePath`/`docPath`
+ * (тека `docs/` поряд із джерелом). Рішення про overwrite/skip приймає скіл —
+ * scanner лише лістить і ставить прапор `exists`. LLM/мережі тут немає: уся
+ * генерація доки — у субагентах скілу.
  */
 // eslint-disable-next-line unicorn/import-style
 import path from 'node:path'
 import { existsSync, readdirSync, statSync } from 'node:fs'
 
 import { isRunAsCli } from '../../../scripts/cli-entry.mjs'
+import { isDocgenIgnored } from './docgen-ignore.mjs'
 
 /** Кодові розширення, для яких генеруємо документацію. */
 const SOURCE_EXTENSIONS = new Set(['.js', '.mjs', '.ts', '.vue', '.py'])
 
-/** Теки, які scanner ніколи не заходить (включно з самими `docs/`). */
-const IGNORED_DIRS = new Set([
-  'node_modules', 'dist', '.git', '__pycache__', 'coverage', '.cursor', '.claude', 'docs'
-])
-
 /** `*.test.*`, `*.spec.*` — тести, документувати не треба. */
 const TEST_FILE_RE = /\.(?:test|spec)\.[^.]+$/u
 
+/**
+ * Чи корінь має system-wide docs layout.
+ * Такий корінь зарезервований під репозиторні docs/adr, docs/explanation тощо,
+ * тому file-level docs у нього не пишемо.
+ * @param {string} root абсолютний корінь обходу
+ * @returns {boolean} true — корінь system-wide docs
+ */
+function isSystemWideDocsRoot(root) {
+  return existsSync(path.join(root, 'docs', 'adr')) || existsSync(path.join(root, 'docs', 'explanation'))
+}
+
 /**
  * Чи є файл кодовим джерелом для документування.
  * @param {string} fileName базове ім'я файлу
@@ -35,8 +43,9 @@ export function isSourceFile(fileName) {
 
 /**
  * Обчислює шлях md-документа для кодового файлу: тека `docs/` поряд із джерелом.
+ * Якщо `sourcePath` відносний, `docPath` теж відносний; якщо абсолютний — абсолютний.
  * @param {string} sourcePath шлях до джерела (відносний або абсолютний)
- * @returns {string} шлях до `<dir>/docs/<stem>.md`
+ * @returns {string} шлях до `<dir>/docs/<stem>.md` у тому ж просторі шляхів
  */
 export function docPathForSource(sourcePath) {
   const dir = path.dirname(sourcePath)
@@ -49,7 +58,7 @@ export function docPathForSource(sourcePath) {
  * Синхронний `readdirSync` — детермінований порядок і простий рекурсивний обхід без
  * гонок; обсяг дерева проєкту це дозволяє.
  * @param {string} root абсолютний корінь обходу
- * @returns {Array<{sourcePath:string, relSource:string, docPath:string, exists:boolean}>} список кандидатів
+ * @returns {Array<{sourcePath:string, docPath:string, exists:boolean}>} список кандидатів з відносними шляхами
  */
 export function scanForDocgen(root) {
   const results = []
@@ -66,16 +75,19 @@ export function scanForDocgen(root) {
     }
     for (const entry of entries) {
       const fullPath = path.join(dir, entry.name)
+      const relPath = path.relative(root, fullPath)
       if (entry.isDirectory()) {
-        if (IGNORED_DIRS.has(entry.name)) continue
+        if (isDocgenIgnored(relPath, 'dir')) continue
         walk(fullPath)
       } else if (entry.isFile() && isSourceFile(entry.name)) {
-        const docPath = docPathForSource(fullPath)
+        if (isSystemWideDocsRoot(root) && path.dirname(relPath) === '.') continue
+        const sourcePath = relPath.split(path.sep).join('/')
+        if (isDocgenIgnored(sourcePath)) continue
+        const docPath = docPathForSource(sourcePath)
         results.push({
-          sourcePath: fullPath,
-          relSource: path.relative(root, fullPath),
+          sourcePath,
           docPath,
-          exists: existsSync(docPath)
+          exists: existsSync(path.join(root, docPath))
         })
       }
     }
@@ -95,12 +107,15 @@ export function slugForModule(root, moduleRoot) {
   const rel = path.relative(root, moduleRoot)
   // корінь репо: фіксований sentinel 'root'
   if (rel === '') return 'root'
-  return rel.split(path.sep).join('-').replaceAll(/[^\w-]+/gu, '-')
+  return rel
+    .split(path.sep)
+    .join('-')
+    .replaceAll(/[^\w-]+/gu, '-')
 }
 
 /**
  * Знаходить корені модулів — теки з `package.json` (корінь завжди модуль).
- * Ті ж IGNORED_DIRS, тож `package.json` у node_modules тощо не враховується.
+ * Ті ж ignore-glob правила, тож `package.json` у службових деревах не враховується.
  * @param {string} root абсолютний корінь обходу
  * @returns {string[]} абсолютні шляхи коренів модулів
  */
@@ -117,8 +132,9 @@ export function findModuleRoots(root) {
     }
     for (const entry of entries) {
       const fullPath = path.join(dir, entry.name)
+      const relPath = path.relative(root, fullPath)
       if (entry.isDirectory()) {
-        if (IGNORED_DIRS.has(entry.name)) continue
+        if (isDocgenIgnored(relPath, 'dir')) continue
         walk(fullPath)
       } else if (entry.isFile() && entry.name === 'package.json' && dir !== root) {
         roots.push(dir)
@@ -150,17 +166,17 @@ export function nearestModuleRoot(filePath, moduleRoots) {
  * Лістить логічні модулі проєкту з членами-файлами і docPath module-summary.
  * Модулі без кодових файлів пропускаються.
  * @param {string} root абсолютний корінь обходу
- * @returns {Array<{moduleRoot:string, relRoot:string, slug:string, docPath:string, members:string[], exists:boolean}>} модулі (members — relSource-и, відносні від root)
+ * @returns {Array<{moduleRoot:string, relRoot:string, slug:string, docPath:string, members:string[], exists:boolean}>} модулі (members — sourcePath-и, відносні від root)
  */
 export function scanForModules(root) {
   const files = scanForDocgen(root)
   const moduleRoots = findModuleRoots(root)
   const byRoot = new Map()
   for (const file of files) {
-    const moduleRoot = nearestModuleRoot(file.sourcePath, moduleRoots)
+    const moduleRoot = nearestModuleRoot(path.join(root, file.sourcePath), moduleRoots)
     if (moduleRoot === null) continue
     if (!byRoot.has(moduleRoot)) byRoot.set(moduleRoot, [])
-    byRoot.get(moduleRoot).push(file.relSource)
+    byRoot.get(moduleRoot).push(file.sourcePath)
   }
 
   const results = []

package/skills/llm-patch/SKILL.md

@@ -71,6 +71,14 @@ description: >-
   з одним рядком пояснення кожна.
 - **Реальні обмеження,** які не виводяться з коду: версії в репо-споживачі,
   inflight-міграції, breaking-change політика, зовнішні залежності.
+- **Change-file flow,** якщо завдання змінює файли у пакетному workspace (код,
+  правила, скіли, конфіги, тести — не лише `docs/`): промпт має вимагати
+  `npx @nitra/cursor change --bump <major|minor|patch> --section <Added|Changed|Fixed|Removed> --message "<опис>" [--ws <шлях>]`
+  і `npx @nitra/cursor fix changelog`. **Ніколи** не інструктуй ручне редагування
+  `CHANGELOG.md` чи bump `version` — це робить release flow / CI (деталь —
+  `.cursor/rules/n-changelog.mdc`, не дублюй її текст). Якщо потрібна реліз-нота —
+  це change-файл `<ws>/.changes/<timestamp>-<rand>.md` з `bump:` і `section:`,
+  який створює саме `change` CLI, а не редагування файлу вручну.
 - **Як перевірити** — конкретні команди й специфічні до завдання сигнали
   успіху.
 
@@ -185,6 +193,11 @@ description: >-
   агенту**, не людині. Використовуй "зроби", "онови", "додай".
 - **Без секцій-пустушок:** якщо немає `Обмежень` чи `Симптому` — пропусти
   секцію цілком.
+- **Без ручного changelog/version у промпті:** не формулюй у виводі інструкції
+  на кшталт "додати запис у `CHANGELOG.md`", "bump `version` вручну" чи
+  "оновити `package.json#version`". Зміни у workspace фіксуються винятково
+  через change-file flow (`npx @nitra/cursor change …` → `npx @nitra/cursor fix changelog`);
+  `version`/`CHANGELOG.md` формує CI.
 - **Не вмикай у промпт:** секрети, `.env`, `node_modules`, бінарні файли,
   довгі логи, дампи `tree`, повні JSON конфігів, цитати існуючих
   helpers/функцій з CWD.
@@ -219,17 +232,25 @@ description: >-
 # Точки правки
 
 - `package.json:18` — `engines.node`
-- `CHANGELOG.md` — додати запис; bump `version` (minor)
+
+# Що треба зробити
+
+- Підняти `engines.node` до `>=25`; якщо peer `eslint ^9` несумісний —
+  підняти range.
+- Зафіксувати зміну change-файлом (НЕ редагувати `CHANGELOG.md` чи `version`
+  вручну): `npx @nitra/cursor change --bump minor --section Changed --message "engines.node >=25"`.
 
 # Обмеження
 
-- Дотриматись `.cursor/rules/n-js-lint.mdc`.
+- Дотриматись `.cursor/rules/n-js-lint.mdc` і `.cursor/rules/n-changelog.mdc`
+  (зміни у workspace = change-файл, не ручний CHANGELOG/version bump).
 - Якщо `eslint ^9` офіційно не підтримує Node 25 — підняти peer range.
 
 # Як перевірити
 
 - `bun test` — зелений
 - `node -p "require('./package.json').engines.node"` → `>=25`
+- `npx @nitra/cursor fix changelog` → exit `0`
 ```
 ````
 

package/skills/start-check/SKILL.md

@@ -21,80 +21,53 @@ description: >-
 
 ### 1. Зібрати список воркспейсів
 
-Прочитай поле `workspaces` з кореневого `package.json`. Воно може містити glob-патерни (`packages/*`, `apps/*`) — розгорни кожен у конкретні директорії. Для кожної директорії прочитай її `package.json`.
-
-### 2. Відфільтрувати воркспейси зі `start`-скриптом
-
-Воркспейс перевіряється, лише якщо в його `package.json` є `scripts.start`. Решту — пропусти й познач у звіті як `SKIP (немає start)`.
-
-### 3. Класифікувати `start` і зафіксувати стан репо
-
-Скіл прогоняє **кожен** воркспейс зі `start` — запуск не пропускається. Але `start` буває двох типів, і це впливає і на трактування коду виходу, і на ризик побічних ефектів:
-
-- **Запуск сервера/застосунку** (`vite`, `next dev`, `nuxt dev`, `node`/`bun <server>`, `nodemon` тощо) — успіх визначається за живучістю процесу.
-- **CLI/разова дія** (зокрема ті, що мутують репо — sync, генерація коду, міграції, розгортання, перезапис конфігів) — успіх визначається за кодом виходу; такий `start` може **виконати реальну роботу** й лишити зміни в репозиторії.
-
-Щоб прогін мутаційного `start` не лишив сміття, зафіксуй стан робочого дерева **перед** запусками:
+> **Не парси `package.json`/glob вручну.** Розгортання воркспейсів і класифікацію `start` несе CLI.
 
 ```bash
-git status --porcelain > /tmp/n-start-check.before
+n-cursor start-check scan
 ```
 
-Цей знімок — база, щоб відкотити побічні ефекти (крок 5).
-
-### 4. Прогнати `start` послідовно
+Друкує JSON `[{ workspace, name, hasStart, startCmd, type }]` для root + усіх воркспейсів. `type` — `server` (dev-сервер/демон) чи `cli` (разова дія). Воркспейси з `hasStart:false` — `SKIP (немає start)` у звіті; решту прогоняй послідовно (крок 2).
 
-Запускай воркспейси **по черзі, НЕ паралельно**: dev-сервери конфліктують за портами, а послідовний прогон дає однозначну причину краху.
+### 2. Прогнати `start` кожного воркспейсу — по черзі
 
-`start` буває двох типів — скіл має їх розрізняти:
+> **Не запускай `perl alarm` і не інтерпретуй exit-коди вручну.** CLI запускає процес із grace-таймаутом (крос-платформно через `spawnSync`), класифікує OK/FAIL за типом і парсить лог.
 
-- **Довгий процес** (dev-сервер, демон): успіх = процес живий через grace-період без краху. Бажано дочекатися рядка готовності в логу (`ready`, `listening`, `Local:`, `started` тощо).
-- **Короткий процес** (CLI, разова дія): успіх = вихід із кодом `0`.
-
-macOS не має `timeout` як стандартної утиліти. Обмеж час через `perl` + `alarm`: `alarm` зводить SIGALRM, а `exec` зберігає той самий PID, тож таймер спрацьовує на справжньому процесі й знімає його після grace-періоду:
+Для кожного воркспейсу з `hasStart:true` (**по одному, НЕ паралельно** — dev-сервери конфліктують за портами):
 
 ```bash
-cd <workspace-dir>
-perl -e 'alarm shift; exec @ARGV' 12 bun run start > /tmp/n-start-check.log 2>&1
-CODE=$?
+n-cursor start-check run <workspace>   # напр. demo  (--grace <ms>, дефолт 12000)
 ```
 
-Інтерпретація `CODE`:
-
-- `142` — процес дожив до кінця grace-періоду й був знятий SIGALRM (`128 + 14`). Для **довгого процесу** (dev-сервер) це **успіх** — стартував і не впав.
-- `0` — процес завершився сам без помилки. Для **короткого процесу** (CLI, разова дія) це **успіх**.
-- будь-що інше — **FAIL**: крах або ненульовий вихід ще до кінця grace-періоду.
-
-Звір також лог: для dev-сервера — рядок готовності (`ready`, `listening`, `Local:`); для CLI — відсутність трас помилок.
-
-Альтернатива `cd` — `bun run --filter '<package-name>' start` (запуск за іменем пакета).
+Друкує JSON:
 
-`bun run start` прибирає свій дочірній процес при завершенні; якщо `start` у репо форкає демонів окремо — переконайся, що після перевірки нічого не лишилось висіти.
-
-### 5. Відкотити побічні ефекти прогону
+```
+{ workspace, type, exitCode, timedOut, status, ready, firstError, logTail, sideEffects }
+```
 
-Після кожного запуску звір поточний `git status --porcelain` зі знімком `/tmp/n-start-check.before` і відкоти **лише те, що з'явилося через прогін**:
+- `status: "OK"` — server дожив до кінця grace (`timedOut`) або встиг віддати рядок готовності; cli вийшов із кодом `0`.
+- `status: "FAIL"` — крах/ненульовий код до grace. `firstError` + `logTail` — для діагностики.
+- `sideEffects: { newFiles, changedTracked }` — read-only git-diff проти стану до запуску (для кроку 3).
 
-- нові невідстежувані файли/директорії (яких не було у знімку) — видали;
-- відстежувані файли, що стали зміненими, а у знімку були чисті — `git checkout -- <path>`;
-- усе, що було брудним **до** прогону, — НЕ чіпай: це зміни користувача, не пов'язані з прогоном.
+Розрізняй **помилку коду** (синтаксис, відсутній імпорт, падіння на ініціалізації) і **середовищний збій** (немає `.env`, недоступна БД/порт зайнятий) — останній не означає, що проєкт зламаний.
 
-Gitignored-артефакти (кеші, `node_modules`, логи) у `git status` не з'являються — їх чіпати не треба. Коли побічні ефекти прибрано, дерево повертається до стану знімка, тож наступний воркспейс стартує з чистої бази.
+### 3. Відкотити побічні ефекти прогону
 
-### 6. Зафіксувати результат
+CLI **не** мутує дерево сам (відкат — деструктивний, лишається явним). Якщо `run` повернув непорожній `sideEffects`, відкоти **лише те, що зʼявилося через прогін**, перш ніж запускати наступний воркспейс:
 
-Для кожного воркспейсу — статус і примітка:
+- `sideEffects.newFiles` — нові невідстежувані файли/директорії → видали (`rm`);
+- `sideEffects.changedTracked` — відстежувані файли, що стали зміненими → `git checkout -- <path>`.
 
-- `OK` — стартував (живий dev-сервер або вихід `0`).
-- `FAIL` — крах або ненульовий код. Додай витяг із логу: останні значущі рядки з помилкою.
-- `SKIP` — у воркспейсі немає `start`-скрипта (крок 2). Сам запуск `start` не пропускається.
+Усе, що було брудним **до** прогону, у `sideEffects` не потрапляє (CLI рахує лише різницю) — зміни користувача не чіпай. Gitignored-артефакти (кеші, `node_modules`) у git-diff не зʼявляються.
 
-Якщо мутаційний `start` лишив побічні ефекти (крок 5) — познач це в примітці: проєкт стартує, але `start` не є чистим запуском сервера.
+### 4. Звіт
 
-Розрізняй у звіті **помилку коду** (синтаксис, відсутній імпорт, падіння при ініціалізації) і **середовищний збій** (немає `.env`, недоступна БД/сервіс, зайнятий порт) — останній не означає, що проєкт зламаний.
+Підсумкова таблиця: `воркспейс | статус | примітка`, з даних `scan` + `run`:
 
-### 7. Звіт
+- `OK` — `status:"OK"` (живий dev-сервер або вихід `0`).
+- `FAIL` — `status:"FAIL"`; додай `firstError` / `logTail`.
+- `SKIP` — `hasStart:false`.
 
-Підсумкова таблиця: `воркспейс | статус | примітка`. Якщо є хоч один `FAIL` — винеси його окремо й покажи помилку повністю.
+Якщо `run` повернув непорожній `sideEffects` — познач у примітці: проєкт стартує, але `start` не є чистим запуском (мутує репо). Якщо є хоч один `FAIL` — винеси його окремо з повною помилкою.
 
 Скіл лише **діагностує** запуск. Виправлення коду — поза скоупом; якщо причина FAIL очевидна, познач її у звіті, але не правь, поки про це не попросять окремо.

package/skills/start-check/js/check.mjs

@@ -0,0 +1,211 @@
+/**
+ * `n-cursor start-check scan|run` — детермінована частина smoke-перевірки
+ * bun-монорепо для скілу `n-start-check`.
+ *
+ * Мотивація: скіл раніше казав LLM-агенту вручну розгортати glob-воркспейси,
+ * читати кожен `package.json`, класифікувати `start` (сервер vs CLI), запускати
+ * процес із таймаутом через `perl alarm`, інтерпретувати exit-коди й парсити лог
+ * на рядки готовності/помилки. Усе це детерміновано — скрипт робить це надійно й
+ * крос-платформно (`spawnSync` з `timeout`), а агент лишається тільки з
+ * діагностикою: **чому** саме воркспейс упав.
+ *
+ * `scan` — `[{workspace, name, hasStart, startCmd, type}]`.
+ * `run <ws>` — `{workspace, type, exitCode, timedOut, status, ready, firstError,
+ * logTail, sideEffects}` (sideEffects — read-only git-diff проти стану до запуску;
+ * власне відкат лишається явним кроком скіла).
+ */
+import { spawnSync } from 'node:child_process'
+import { existsSync } from 'node:fs'
+import { readFile } from 'node:fs/promises'
+import { join } from 'node:path'
+
+import { getMonorepoPackageRootDirs } from '../../../scripts/lib/workspaces.mjs'
+
+/** Маркери довгого процесу (dev-сервер/демон) у команді `start`. */
+const SERVER_CMD_RE = /\b(vite|next|nuxt|nodemon|serve|astro|remix|webpack-dev-server|http-server)\b|\bdev\b|--watch/
+/** Рядки готовності dev-сервера в логу (`\b` лише де треба — щоб «already» не матчив «ready»). */
+const READY_RE = /\bready\b|\blistening\b|\bstarted\b|\bcompiled\b|server running|local:/i
+/** Сигнатури помилок у логу. */
+const ERROR_RE = /(error|exception|fatal|cannot find|module not found|unhandled|panic|traceback)/i
+/** Скільки останніх рядків логу повертати. */
+const LOG_TAIL_LINES = 15
+
+/**
+ * Класифікує `start`-команду: довгий процес (сервер) чи разова дія (CLI).
+ * @param {string} startCmd значення `scripts.start`
+ * @returns {'server'|'cli'} тип процесу
+ */
+export function classifyStartType(startCmd) {
+  return typeof startCmd === 'string' && SERVER_CMD_RE.test(startCmd) ? 'server' : 'cli'
+}
+
+/**
+ * Зчитує `package.json` воркспейсу або повертає null.
+ * @param {string} dir абсолютний шлях до каталогу воркспейсу
+ * @returns {Promise<object|null>} розпарсений package.json або null
+ */
+async function readPkg(dir) {
+  const path = join(dir, 'package.json')
+  if (!existsSync(path)) return null
+  try {
+    return JSON.parse(await readFile(path, 'utf8'))
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Сканує монорепо: для кожного воркспейсу — чи є `start`, його команда і тип.
+ * @param {string} cwd корінь репозиторію
+ * @returns {Promise<Array<{workspace:string, name:string|null, hasStart:boolean, startCmd:string|null, type:('server'|'cli'|null)}>>} список воркспейсів
+ */
+export async function scanStartWorkspaces(cwd) {
+  const roots = await getMonorepoPackageRootDirs(cwd)
+  const out = []
+  for (const ws of roots) {
+    const pkg = await readPkg(join(cwd, ws))
+    const startCmd = pkg?.scripts?.start ?? null
+    const hasStart = typeof startCmd === 'string' && startCmd.length > 0
+    out.push({
+      workspace: ws,
+      name: pkg?.name ?? null,
+      hasStart,
+      startCmd: hasStart ? startCmd : null,
+      type: hasStart ? classifyStartType(startCmd) : null
+    })
+  }
+  return out
+}
+
+/**
+ * Парсить лог процесу: готовність (сервер), перша помилка, хвіст.
+ * @param {string} log обʼєднаний stdout+stderr
+ * @returns {{ready:boolean, firstError:string|null, logTail:string}} витяг
+ */
+export function parseStartLog(log) {
+  const text = log ?? ''
+  const lines = text.split('\n')
+  const firstError = lines.find(l => ERROR_RE.test(l))?.trim() ?? null
+  const logTail = lines
+    .filter(l => l.trim() !== '')
+    .slice(-LOG_TAIL_LINES)
+    .join('\n')
+  return { ready: READY_RE.test(text), firstError, logTail }
+}
+
+/**
+ * Read-only знімок `git status --porcelain` як множина рядків.
+ * @param {string} cwd корінь репозиторію
+ * @returns {Set<string>} рядки porcelain (статус + шлях)
+ */
+function gitPorcelain(cwd) {
+  const res = spawnSync('git', ['status', '--porcelain'], { cwd, encoding: 'utf8' })
+  if (res.status !== 0 || typeof res.stdout !== 'string') return new Set()
+  return new Set(res.stdout.split('\n').filter(l => l.trim() !== ''))
+}
+
+/**
+ * Обчислює побічні ефекти прогону як різницю git-станів до/після.
+ * @param {Set<string>} before знімок до
+ * @param {Set<string>} after знімок після
+ * @returns {{newFiles:string[], changedTracked:string[]}} нові untracked і ново-змінені tracked шляхи
+ */
+function diffSideEffects(before, after) {
+  const newFiles = []
+  const changedTracked = []
+  for (const line of after) {
+    if (before.has(line)) continue
+    const path = line.slice(3)
+    if (line.startsWith('??')) newFiles.push(path)
+    else changedTracked.push(path)
+  }
+  return { newFiles, changedTracked }
+}
+
+/**
+ * Запускає `start` одного воркспейсу з grace-таймаутом і класифікує результат.
+ * @param {string} cwd корінь репозиторію
+ * @param {string} workspace відносний шлях воркспейсу
+ * @param {{graceMs?:number, type?:('server'|'cli'), spawnImpl?:Function}} [opts] grace-період, тип (інакше з package.json), інʼєкція spawn для тестів
+ * @returns {Promise<{workspace:string, type:string, exitCode:number|null, timedOut:boolean, status:('OK'|'FAIL'), ready:boolean, firstError:string|null, logTail:string, sideEffects:{newFiles:string[], changedTracked:string[]}}>} результат прогону
+ */
+export async function runWorkspaceStart(cwd, workspace, opts = {}) {
+  const { graceMs = 12_000, spawnImpl = spawnSync } = opts
+  const dir = join(cwd, workspace)
+  const pkg = await readPkg(dir)
+  const startCmd = pkg?.scripts?.start
+  if (typeof startCmd !== 'string' || startCmd.length === 0) {
+    throw new Error(`У воркспейсі ${workspace} немає scripts.start`)
+  }
+  const type = opts.type ?? classifyStartType(startCmd)
+
+  const before = gitPorcelain(cwd)
+  const res = spawnImpl('bun', ['run', 'start'], {
+    cwd: dir,
+    encoding: 'utf8',
+    timeout: graceMs,
+    killSignal: 'SIGTERM'
+  })
+  const timedOut = res.error?.code === 'ETIMEDOUT' || res.signal === 'SIGTERM'
+  const exitCode = typeof res.status === 'number' ? res.status : null
+  const { ready, firstError, logTail } = parseStartLog(`${res.stdout ?? ''}${res.stderr ?? ''}`)
+
+  // server: успіх = дожив до кінця grace (timedOut) або встиг віддати рядок готовності.
+  // cli: успіх = чистий вихід 0 у межах grace.
+  const status = type === 'server' ? (timedOut || ready ? 'OK' : 'FAIL') : exitCode === 0 ? 'OK' : 'FAIL'
+
+  return {
+    workspace,
+    type,
+    exitCode,
+    timedOut,
+    status,
+    ready,
+    firstError,
+    logTail,
+    sideEffects: diffSideEffects(before, gitPorcelain(cwd))
+  }
+}
+
+const USAGE = 'Usage: n-cursor start-check <scan | run <workspace> [--grace <ms>]>'
+
+/**
+ * CLI: `scan` друкує список воркспейсів зі `start`; `run <ws>` запускає один і
+ * друкує класифікований результат. Обидва — JSON у stdout.
+ * @param {string[]} args аргументи після `start-check`
+ * @param {string} [cwd] корінь репозиторію (інʼєкція для тестів)
+ * @returns {Promise<number>} exit code
+ */
+export async function runStartCheckCli(args, cwd = process.cwd()) {
+  const sub = args[0]
+
+  if (sub === 'scan') {
+    process.stdout.write(`${JSON.stringify(await scanStartWorkspaces(cwd))}\n`)
+    return 0
+  }
+
+  if (sub === 'run') {
+    const workspace = args[1] && !args[1].startsWith('--') ? args[1] : undefined
+    if (!workspace) {
+      console.error(USAGE)
+      return 1
+    }
+    const graceAt = args.indexOf('--grace')
+    const graceMs = graceAt === -1 ? undefined : Number(args[graceAt + 1])
+    if (graceAt !== -1 && (!Number.isFinite(graceMs) || graceMs <= 0)) {
+      console.error('✗ --grace очікує додатнє число (мс)')
+      return 1
+    }
+    try {
+      const result = await runWorkspaceStart(cwd, workspace, graceMs ? { graceMs } : {})
+      process.stdout.write(`${JSON.stringify(result)}\n`)
+      return 0
+    } catch (error) {
+      console.error(`✗ ${error.message}`)
+      return 1
+    }
+  }
+
+  console.error(USAGE)
+  return 1
+}

package/skills/taze/SKILL.md

@@ -43,9 +43,15 @@ bun install
 
 ### 3. Виявити major-оновлення
 
-Порівняти `package.json.taze-bak` з оновленим `package.json` (а також `bun.lock.taze-bak` ↔ `bun.lock` для транзитивних). Для кожної залежності, у якої змінилась перша значуща цифра semver (`1.x.x → 2.x.x`, `0.4.x → 0.5.x`, `0.0.x → 0.1.x`) — додати в список «потребує перевірки».
+> **Не порівнюй `package.json` вручну.** Класифікацію semver несе CLI — детерміновано, по всіх воркспейсах.
 
-Minor/patch — пропускати, їх вважаємо сумісними.
+```bash
+n-cursor taze diff
+```
+
+Друкує компактний JSON: `{ "major": [{workspace, pkg, from, to}], "minorPatch": <N>, "totalChanged": <N> }`. `major` — список залежностей, у яких змінилась найлівіша ненульова компонента semver (`1.x→2.x`, `0.4.x→0.5.x`, `0.0.3→0.0.4`); саме він іде в кроки 4–6. `minorPatch` — лічба сумісних (для звіту в кроці 8).
+
+Покриває **прямі** залежності з `package.json` (root + воркспейси). Транзитивні major-стрибки (`bun.lock`) — за потреби переглянь окремо; основний ризик breaking-змін — у прямих.
 
 ### 4. Зібрати breaking changes по кожному major-оновленню
 
@@ -94,7 +100,7 @@ rm package.json.taze-bak bun.lock.taze-bak
 
 Коротко в одному повідомленні:
 
-- **Оновлено (minor/patch):** кількість пакетів, без деталей.
+- **Оновлено (minor/patch):** кількість пакетів (`minorPatch` із кроку 3), без деталей.
 - **Major-оновлення:** список `<name>: <old> → <new>` з посиланням на release notes.
 - **Зрефакторено автоматично:** список файлів і коротко що саме змінено.
 - **Потребує ручного втручання:** список TODO з причиною (нетривіальна міграція / неоднозначність / падіння тестів).