@nitra/cursor 1.13.62 → 1.13.63

package/CHANGELOG.md

@@ -4,6 +4,19 @@
 
 Формат — [Keep a Changelog](https://keepachangelog.com/uk/1.1.0/), нумерація — [SemVer](https://semver.org/lang/uk/).
 
+## [1.13.63] - 2026-05-20
+
+### Fixed
+
+- **`check changelog`**: новий local-only воркспейс (маніфест відсутній на merge-base з `dev`/`main`, напр. `demo/` на `main`) більше не вимагає штучного bump — достатньо початкової `version` і запису в `CHANGELOG.md` (раніше `Vbase === ∅` помилково трактувалось як «version не підвищено»).
+- **`check changelog`**: на гілці **`main`** база порівняння — **`origin/main`** (або `HEAD~1` без remote), не `dev`; коли `origin/main` збігається з `HEAD`, diff порожній (не fallback на `HEAD~1`); feature-гілки — `merge-base` з `dev`, інакше з `main` (репо без `dev`).
+
+### Changed
+
+- Правило **`changelog`** ([changelog.mdc](rules/changelog/changelog.mdc) `2.5`): блок **STOP** перенесено на початок (тригер шляхів, інверсія, три кроки до завершення відповіді) — щоб агент не пропускав bump після правок у `npm/skills/` тощо, коли чеклист губився внизу довгого alwaysApply-правила.
+- **`.cursor/rules/scripts.mdc`**: секція «Завершення задачі після правок у пакетному workspace» — cross-STOP з **n-changelog** (останні кроки сесії перед відповіддю).
+- **`hk.pkl`**: pre-commit крок **`npm-changelog`** (`glob: npm/**`, `bun ./npm/bin/n-cursor.js check changelog`) — програмний стоп-кран при commit, якщо агент забув bump.
+
 ## [1.13.62] - 2026-05-20
 
 ### Changed

package/package.json

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

package/rules/changelog/changelog.mdc

@@ -1,9 +1,25 @@
 ---
 description: CHANGELOG.md в кожному workspace, з двома моделями бази порівняння (npm і Python)
-version: '2.4'
+version: '2.5'
 alwaysApply: true
 ---
 
+## STOP — перед завершенням відповіді агента
+
+> **Якщо в цій сесії ти змінив(ла) файли в пакетному workspace** (код, rego, правила, скіли, скрипти, конфіги, тести — **не** лише `docs/` / `doc/`) — **не завершуй задачу**, поки не виконаєш **усі три** кроки нижче в **тому ж** наборі змін. Це не «опційно після синку» — це частина PR.
+
+1. **`version`** у `<ws>/package.json` (або `[project].version` у `pyproject.toml`) → **patch +1** відносно `git show HEAD:<ws>/package.json`, якщо ще не піднято.
+2. **`CHANGELOG.md`** того workspace → **нова** секція `## [версія] - YYYY-MM-DD` **зверху** (не bullet-и в стару версію).
+3. **`npx @nitra/cursor check changelog`** (у репо `@nitra/cursor`: `bun ./npm/bin/n-cursor.js check changelog`) → exit **`0`**.
+
+**Тригер шляхів (приклади):** `npm/**`, `packages/foo/**`, будь-який каталог з власним `package.json` / `pyproject.toml`, куди потрапили правки.
+
+**Інверсія (bump не потрібен):** лише `docs/` / `doc/`; лише `.gitignore`; лише сам релізний крок (`CHANGELOG.md` + `version`).
+
+**Pre-commit (людина):** `hk` у цьому репо також запускає `check changelog` при змінах під `npm/**` — агент не покладайся лише на commit hook; виконай кроки 1–3 **до** фінальної відповіді.
+
+---
+
 У кожному **пакетному** workspace (каталог із `package.json` або `pyproject.toml`) має бути власний **`CHANGELOG.md`**. Спільного на репозиторій змісту змін **не існує** — кожен пакет веде свій.
 
 **Маніфест версії:**
@@ -13,7 +29,9 @@ alwaysApply: true
 
 Каталоги лише з `pyproject.toml` (без `package.json`) теж враховуються; `node_modules/`, `.venv/`, `venv/` при пошуку ігноруються.
 
-## Чеклист агента (будь-який репозиторій з цим правилом)
+## Чеклист агента (деталі)
+
+Повний алгоритм — у блоці **STOP** вище; тут лише уточнення.
 
 **Інверсія (за замовчуванням не вимагають bump/CHANGELOG):**
 
@@ -21,13 +39,7 @@ alwaysApply: true
 - файли під **`.gitignore`**;
 - правки **лише** `CHANGELOG.md` або поля `version` у маніфесті як сам релізний крок.
 
-**Вимагають bump + нову секцію CHANGELOG** — усі інші зміни в каталозі workspace (код, rego, правила, конфіги, тести тощо).
-
-Перед завершенням задачі:
-
-1. **`version`** у `<ws>/package.json` або `[project].version` у `<ws>/pyproject.toml` підвищено (build/patch +1 на PR), якщо зміни входять у реліз.
-2. **`CHANGELOG.md`** — **нова** секція `## [версія] - YYYY-MM-DD` зверху (не дописуй bullet-и в стару версію).
-3. **`npx @nitra/cursor check changelog`** — exit `0`.
+**Вимагають bump + нову секцію CHANGELOG** — усі інші зміни в каталозі workspace (код, rego, правила, скіли, конфіги, тести тощо).
 
 Перевірка програмна (`changelog/fix/consistency/check.mjs`).
 
@@ -48,14 +60,14 @@ alwaysApply: true
 
 ### local-only
 
-**npm:** `private: true` або без `files`. **Python:** без пари name+version для реєстру. База = **`dev` або `main`** (перша наявна), `git merge-base`:
+**npm:** `private: true` або без `files`. **Python:** без пари name+version для реєстру. База залежить від гілки:
 
 1. На **`dev`** local-only не активний (крім незакомічених registry-published).
-2. На feature-гілці — bump + CHANGELOG **раз на PR**.
-3. Після merge на інтеграційну гілку diff порожній → pass.
-4. Direct-commit на `main` ловиться так само.
+2. На **`main`** — diff від **`origin/main`** (попередній опублікований `main`); без remote — від `HEAD~1`. **`dev` не використовується** як база на `main`.
+3. На **feature-гілці** — `merge-base` з **`dev`**, якщо є; інакше з **`main`** (репо без `dev`).
+4. Bump + CHANGELOG **раз на PR** / direct-commit на `main`.
 
-Якщо немає git або немає `dev`/`main` — local-only пропускається.
+Якщо немає git або немає `dev`/`main`/`origin/main` — local-only пропускається.
 
 ## Формат CHANGELOG.md
 

package/rules/changelog/fix/consistency/check.mjs

@@ -10,8 +10,9 @@
  *    Якщо локальна версія відрізняється — потрібен CHANGELOG; для npm також `"CHANGELOG.md"`
  *    у `files`. Якщо версії збігаються, але в git є релевантні зміни без bump — fail.
  *
- * 2) **local-only** (приватні npm, без `files`, Python без імені/версії для реєстру): PR-scoped
- *    перевірка проти `dev` / `main` через `git merge-base`.
+ * 2) **local-only** (приватні npm, без `files`, Python без імені/версії для реєстру):
+ *    feature-гілка — `merge-base` з `dev`, інакше з `main`; на `main` — diff від
+ *    `origin/main` (попередній опублікований main) або `HEAD~1` без remote.
  *
  * Усі `git` і зовнішні виклики — через `execFile` / `fetch`, без shell-інтерполяції.
  */
@@ -31,11 +32,11 @@ import {
 
 const execFileAsync = promisify(execFile)
 
-/** Кандидати інтеграційної гілки (перша наявна в репо; див. n-changelog.mdc) */
-const BASE_BRANCH_CANDIDATES = Object.freeze(['dev', 'main'])
+/** Кандидати інтеграційної гілки для feature-гілок (перша наявна; див. n-changelog.mdc). */
+const FEATURE_BASE_BRANCH_CANDIDATES = Object.freeze(['dev', 'main'])
 
-/** Гілки, на яких local-only перевірку пропускаємо (крім незакомічених registry-published). */
-const INTEGRATION_BRANCHES = Object.freeze(['dev', 'main'])
+/** Гілка `dev`: local-only не активний (крім незакомічених registry-published). */
+const LOCAL_ONLY_SKIP_BRANCH = 'dev'
 
 /** Префікси шляхів (posix), які не вважаються релізними змінами — інверсія glob (n-changelog.mdc). */
 const CHANGELOG_IGNORE_PATH_PREFIXES = Object.freeze(['docs/', 'doc/'])
@@ -78,14 +79,6 @@ async function currentBranchName() {
   return typeof out === 'string' ? out.trim() : null
 }
 
-/**
- * @param {string | null} branch параметр
- * @returns {boolean} результат
- */
-function isIntegrationBranch(branch) {
-  return branch !== null && INTEGRATION_BRANCHES.includes(branch)
-}
-
 /**
  * @param {string} ref параметр
  * @returns {string} результат
@@ -94,6 +87,30 @@ function baseRefLabel(ref) {
   return ref.startsWith('origin/') ? ref.slice('origin/'.length) : ref
 }
 
+/**
+ * @param {string} ancestor предок
+ * @param {string} descendant нащадок
+ * @returns {Promise<boolean>} результат
+ */
+async function isGitAncestor(ancestor, descendant) {
+  const out = await gitOrNull(['merge-base', '--is-ancestor', ancestor, descendant])
+  return typeof out === 'string' && out.trim() === 'true'
+}
+
+/**
+ * @param {string} branchName локальна або remote-tracking гілка
+ * @returns {Promise<string | null>} ref для git або null
+ */
+async function resolveBranchRef(branchName) {
+  for (const ref of [branchName, `origin/${branchName}`]) {
+    const out = await gitOrNull(['rev-parse', '--verify', '--quiet', ref])
+    if (typeof out === 'string' && out.trim().length > 0) {
+      return ref
+    }
+  }
+  return null
+}
+
 /**
  * @param {string} relPath параметр
  * @returns {boolean} результат
@@ -119,21 +136,6 @@ async function isPathGitIgnored(relPath) {
   }
 }
 
-/**
- * @returns {Promise<string | null>} результат
- */
-async function resolveBaseRef() {
-  for (const name of BASE_BRANCH_CANDIDATES) {
-    for (const ref of [name, `origin/${name}`]) {
-      const out = await gitOrNull(['rev-parse', '--verify', '--quiet', ref])
-      if (typeof out === 'string' && out.trim().length > 0) {
-        return ref
-      }
-    }
-  }
-  return null
-}
-
 /**
  * @param {string} baseRef параметр
  * @returns {Promise<string | null>} результат
@@ -145,6 +147,47 @@ async function resolveMergeBase(baseRef) {
   return sha.length > 0 ? sha : null
 }
 
+/**
+ * Точка порівняння git для changelog (ref або SHA для `git diff` / `git show`).
+ * @param {string | null} branch поточна гілка
+ * @returns {Promise<{ ref: string, label: string } | null>} результат
+ */
+async function resolveChangelogComparisonPoint(branch) {
+  if (branch === LOCAL_ONLY_SKIP_BRANCH) {
+    return null
+  }
+
+  if (branch === 'main') {
+    const originMainSha = (await gitOrNull(['rev-parse', '--verify', '--quiet', 'origin/main']))?.trim()
+    const headSha = (await gitOrNull(['rev-parse', 'HEAD']))?.trim()
+    if (
+      originMainSha &&
+      headSha &&
+      (originMainSha === headSha || (await isGitAncestor('origin/main', 'HEAD')))
+    ) {
+      return { ref: 'origin/main', label: 'main' }
+    }
+    const parent = await gitOrNull(['rev-parse', '--verify', '--quiet', 'HEAD~1'])
+    if (typeof parent === 'string' && parent.trim().length > 0) {
+      return { ref: parent.trim(), label: 'main~1' }
+    }
+    return null
+  }
+
+  for (const name of FEATURE_BASE_BRANCH_CANDIDATES) {
+    const baseRef = await resolveBranchRef(name)
+    if (!baseRef) {
+      continue
+    }
+    const mergeBase = await resolveMergeBase(baseRef)
+    if (!mergeBase) {
+      continue
+    }
+    return { ref: mergeBase, label: baseRefLabel(baseRef) }
+  }
+  return null
+}
+
 /**
  * @param {string} ws параметр
  * @param {string[]} subWorkspaces параметр
@@ -355,7 +398,8 @@ async function checkPublishedWorkspacePendingGitChanges(manifest, Vcurrent, subW
   }
 
   const branch = await currentBranchName()
-  if (isIntegrationBranch(branch)) {
+
+  if (branch === LOCAL_ONLY_SKIP_BRANCH) {
     if (await workspaceHasRelevantChangesAgainstBase('HEAD', manifest.ws, subWorkspaces)) {
       fail(
         `${label}: у registry-published пакеті є незакомічені зміни при version ${Vcurrent}, що вже в реєстрі. ` +
@@ -365,28 +409,32 @@ async function checkPublishedWorkspacePendingGitChanges(manifest, Vcurrent, subW
     return
   }
 
-  const baseRef = await resolveBaseRef()
-  if (!baseRef) {
-    return
-  }
-  const mergeBase = await resolveMergeBase(baseRef)
-  if (!mergeBase) {
-    return
-  }
-  if (!(await workspaceHasRelevantChangesAgainstBase(mergeBase, manifest.ws, subWorkspaces))) {
-    return
+  const comparison = await resolveChangelogComparisonPoint(branch)
+  if (comparison && (await workspaceHasRelevantChangesAgainstBase(comparison.ref, manifest.ws, subWorkspaces))) {
+    const Vbase = await readBaseVersion(comparison.ref, manifest)
+    const baseLabel = comparison.label
+    if (Vbase === null) {
+      pass(
+        `${label}: новий registry-published воркспейс (на ${baseLabel} відсутній ${mf}) — перевіряємо CHANGELOG для ${Vcurrent}`
+      )
+      await verifyChangelogEntry(manifest.ws, Vcurrent, pass, fail)
+      checkNpmFilesArrayContainsChangelog(manifest, pass, fail)
+    } else if (Vbase === Vcurrent) {
+      fail(
+        `${label}: у цій гілці є зміни в registry-published пакеті, але version у ${mf} ` +
+          `не підвищено (на ${baseLabel} — ${Vbase}). Bump + запис у CHANGELOG.md обов'язкові (n-changelog.mdc)`
+      )
+    } else {
+      pass(`${label}: version змінено (${Vbase} → ${Vcurrent}) — очікується запис CHANGELOG після bump`)
+    }
   }
 
-  const Vbase = await readBaseVersion(mergeBase, manifest)
-  const baseLabel = baseRefLabel(baseRef)
-  if (Vbase === null || Vbase === Vcurrent) {
+  if (branch === 'main' && (await workspaceHasRelevantChangesAgainstBase('HEAD', manifest.ws, subWorkspaces))) {
     fail(
-      `${label}: у цій гілці є зміни в registry-published пакеті, але version у ${mf} ` +
-        `не підвищено (на ${baseLabel} — ${Vbase ?? '∅'}). Bump + запис у CHANGELOG.md обов'язкові на PR (n-changelog.mdc)`
+      `${label}: у registry-published пакеті є незакомічені зміни при version ${Vcurrent}, що вже в реєстрі. ` +
+        `Підвищ version у ${mf} і додай запис у CHANGELOG.md (n-changelog.mdc)`
     )
-    return
   }
-  pass(`${label}: version змінено (${Vbase} → ${Vcurrent}) — очікується запис CHANGELOG після bump`)
 }
 
 /**
@@ -426,13 +474,13 @@ async function checkPublishedWorkspace(manifest, subWorkspaces, getPublishedVers
 }
 
 /**
- * @param {string} mergeBase параметр
+ * @param {string} comparisonRef ref/SHA для `git diff` / `git show`
  * @param {import('../../../../scripts/utils/package-manifest.mjs').PackageManifest} manifest параметр
  * @param {string} baseLabel параметр
  * @param {(msg: string) => void} pass параметр
  * @param {(msg: string) => void} fail параметр
  */
-async function checkLocalOnlyChangedWorkspace(mergeBase, manifest, baseLabel, pass, fail) {
+async function checkLocalOnlyChangedWorkspace(comparisonRef, manifest, baseLabel, pass, fail) {
   const label = workspaceLabel(manifest)
   const mf = manifestFilePath(manifest.ws, manifest)
   const Vcurrent = manifest.version
@@ -440,10 +488,16 @@ async function checkLocalOnlyChangedWorkspace(mergeBase, manifest, baseLabel, pa
     fail(`${label}: у ${mf} відсутнє поле version (потрібне для запису в CHANGELOG)`)
     return
   }
-  const Vbase = await readBaseVersion(mergeBase, manifest)
-  if (Vbase === null || Vbase === Vcurrent) {
+  const Vbase = await readBaseVersion(comparisonRef, manifest)
+  if (Vbase === null) {
+    pass(`${label}: новий воркспейс (на ${baseLabel} відсутній ${mf}) — перевіряємо CHANGELOG для ${Vcurrent}`)
+    if (!(await verifyChangelogEntry(manifest.ws, Vcurrent, pass, fail))) return
+    checkNpmFilesArrayContainsChangelog(manifest, pass, fail)
+    return
+  }
+  if (Vbase === Vcurrent) {
     fail(
-      `${label}: у цій гілці є зміни, але version у ${mf} не підвищено (на ${baseLabel} — ${Vbase ?? '∅'}). Bump + запис у CHANGELOG.md обов'язкові на PR`
+      `${label}: у цій гілці є зміни, але version у ${mf} не підвищено (на ${baseLabel} — ${Vbase}). Bump + запис у CHANGELOG.md обов'язкові на PR`
     )
     return
   }
@@ -466,30 +520,24 @@ async function runLocalOnlyChecks(localOnly, subWorkspaces, pass, fail) {
     return
   }
   const branch = await currentBranchName()
-  if (branch === 'dev') {
+  if (branch === LOCAL_ONLY_SKIP_BRANCH) {
     pass('changelog: поточна гілка = dev — local-only перевірку пропущено')
     return
   }
-  const baseRef = await resolveBaseRef()
-  if (!baseRef) {
+  const comparison = await resolveChangelogComparisonPoint(branch)
+  if (!comparison) {
     pass('changelog: ref dev/main (та origin/*) не знайдено — local-only перевірку пропущено')
     return
   }
-  const mergeBase = await resolveMergeBase(baseRef)
-  if (!mergeBase) {
-    pass(`changelog: merge-base з ${baseRef} не знайдено — local-only перевірку пропущено`)
-    return
-  }
 
-  const baseLabel = baseRefLabel(baseRef)
   let checkedAny = false
   for (const manifest of localOnly) {
-    if (!(await workspaceHasRelevantChangesAgainstBase(mergeBase, manifest.ws, subWorkspaces))) continue
+    if (!(await workspaceHasRelevantChangesAgainstBase(comparison.ref, manifest.ws, subWorkspaces))) continue
     checkedAny = true
-    await checkLocalOnlyChangedWorkspace(mergeBase, manifest, baseLabel, pass, fail)
+    await checkLocalOnlyChangedWorkspace(comparison.ref, manifest, comparison.label, pass, fail)
   }
   if (!checkedAny) {
-    pass(`changelog: local-only воркспейси без змін відносно merge-base(${baseRef})`)
+    pass(`changelog: local-only воркспейси без змін відносно ${comparison.label}`)
   }
 }