@nitra/cursor 11.4.0 → 12.0.0

package/rules/npm-module/js/docs/skill_meta.md

@@ -1,14 +1,12 @@
 ---
+type: JS Module
+title: skill_meta.mjs
+resource: npm/rules/npm-module/js/skill_meta.mjs
 docgen:
-  source: npm/rules/npm-module/js/skill_meta.mjs
   crc: a069397b
   score: 100
 ---
 
-# skill_meta.mjs
-
-## Огляд
-
 Перевірка стану конфігурації. Файл перевіряє відповідність між полями worktree та requireRoot. Перевірка спирається на конфіги meta.json.
 
 ## Поведінка

package/rules/php/docs/fix.md

@@ -1,14 +1,12 @@
 ---
+type: JS Module
+title: fix.mjs
+resource: npm/rules/php/fix.mjs
 docgen:
-  source: npm/rules/php/fix.mjs
   crc: 38cf876b
   score: 100
 ---
 
-# fix.mjs
-
-## Огляд
-
 Виконує застосування політики JS-занепокоєних до mdc-refs на вхідному контексті прогону та повертає результат.
 
 Виконується при запуску через командний рядок, виконуючи повний еквівалент команди `npx @nitra/cursor fix <id>` та повертає код виходу.

package/rules/php/docs/index.md

@@ -0,0 +1,11 @@
+---
+type: Directory Index
+title: npm/rules/php
+resource: npm/rules/php/
+---
+
+# npm/rules/php
+
+| Файл | Тип |
+|---|---|
+| [fix.mjs](fix.md) | JS Module |

package/rules/php/js/docs/index.md

@@ -0,0 +1,11 @@
+---
+type: Directory Index
+title: npm/rules/php/js
+resource: npm/rules/php/js/
+---
+
+# npm/rules/php/js
+
+| Файл | Тип |
+|---|---|
+| [tooling.mjs](tooling.md) | JS Module |

package/rules/php/js/docs/tooling.md

@@ -1,14 +1,12 @@
 ---
+type: JS Module
+title: tooling.mjs
+resource: npm/rules/php/js/tooling.mjs
 docgen:
-  source: npm/rules/php/js/tooling.mjs
   crc: a3e6a475
   score: 95
 ---
 
-# tooling.mjs
-
-## Огляд
-
 Огляд
 Файл перевіряє наявність конфігураційних файлів для визначення залежностей та робочих потоків. Файл використовується для встановлення наявності певних файлів у репозиторії.
 

package/rules/php/lint/docs/index.md

@@ -0,0 +1,11 @@
+---
+type: Directory Index
+title: npm/rules/php/lint
+resource: npm/rules/php/lint/
+---
+
+# npm/rules/php/lint
+
+| Файл | Тип |
+|---|---|
+| [lint.mjs](lint.md) | JS Module |

package/rules/php/lint/docs/lint.md

@@ -1,13 +1,11 @@
 ---
+type: JS Module
+title: lint.mjs
+resource: npm/rules/php/lint/lint.mjs
 docgen:
-  source: npm/rules/php/lint/lint.mjs
   crc: cafd914f
 ---
 
-# lint.mjs — PHP lint runner
-
-## Огляд
-
 Модуль `lint.mjs` реалізує крок `lint-php` згідно з правилом `php.mdc`. Він виконує статичний та безпековий аналіз PHP-проєкту, який лежить у поточному робочому каталозі (`process.cwd()`), послідовно прогоняючи такі інструменти:
 
 1. `composer audit --no-interaction` — обовʼязковий аудит залежностей через Composer.

package/rules/python/docs/fix.md

@@ -1,14 +1,12 @@
 ---
+type: JS Module
+title: fix.mjs
+resource: npm/rules/python/fix.mjs
 docgen:
-  source: npm/rules/python/fix.mjs
   crc: 38cf876b
   score: 100
 ---
 
-# fix.mjs
-
-## Огляд
-
 Виконує застосування JS-занепокоєних на вхідному контексті, застосовує визначену політику, генерує посилання на MDC та повертає результат прогону
 
 ## Поведінка

package/rules/python/docs/index.md

@@ -0,0 +1,11 @@
+---
+type: Directory Index
+title: npm/rules/python
+resource: npm/rules/python/
+---
+
+# npm/rules/python
+
+| Файл | Тип |
+|---|---|
+| [fix.mjs](fix.md) | JS Module |

package/rules/python/js/docs/applies.md

@@ -1,14 +1,12 @@
 ---
+type: JS Module
+title: applies.mjs
+resource: npm/rules/python/js/applies.mjs
 docgen:
-  source: npm/rules/python/js/applies.mjs
   crc: ed79bd71
   score: 100
 ---
 
-# applies.mjs
-
-## Огляд
-
 Файл перевіряє наявність файлу pyproject.toml у корені репозиторію.
 
 ## Поведінка

package/rules/python/js/docs/index.md

@@ -0,0 +1,12 @@
+---
+type: Directory Index
+title: npm/rules/python/js
+resource: npm/rules/python/js/
+---
+
+# npm/rules/python/js
+
+| Файл | Тип |
+|---|---|
+| [applies.mjs](applies.md) | JS Module |
+| [tooling.mjs](tooling.md) | JS Module |

package/rules/python/js/docs/tooling.md

@@ -1,14 +1,12 @@
 ---
+type: JS Module
+title: tooling.mjs
+resource: npm/rules/python/js/tooling.mjs
 docgen:
-  source: npm/rules/python/js/tooling.mjs
   crc: f4dc22e2
   score: 95
 ---
 
-# tooling.mjs
-
-## Огляд
-
 Файл виконує перевірку наявності конфігураційних та залежностей у кореневому каталозі репозиторію. Він перевіряє структуру проекту відповідно до вимог, визначених у package.json.
 
 ## Поведінка

package/rules/python/lint/docs/index.md

@@ -0,0 +1,11 @@
+---
+type: Directory Index
+title: npm/rules/python/lint
+resource: npm/rules/python/lint/
+---
+
+# npm/rules/python/lint
+
+| Файл | Тип |
+|---|---|
+| [lint.mjs](lint.md) | JS Module |

package/rules/python/lint/docs/lint.md

@@ -1,13 +1,11 @@
 ---
+type: JS Module
+title: lint.mjs
+resource: npm/rules/python/lint/lint.mjs
 docgen:
-  source: npm/rules/python/lint/lint.mjs
   crc: 92c8f115
 ---
 
-# `lint.mjs` — лінт-крок `lint-python`
-
-## Огляд
-
 Модуль `npm/rules/python/lint/lint.mjs` реалізує крок `lint-python` — частину
 загального лінт-пайплайну монорепозиторію. Крок виконує перевірку Python-частини
 проєкту відповідно до правила `python.mdc` і базується на пакетному менеджері

package/rules/rego/docs/fix.md

@@ -1,14 +1,12 @@
 ---
+type: JS Module
+title: fix.mjs
+resource: npm/rules/rego/fix.mjs
 docgen:
-  source: npm/rules/rego/fix.mjs
   crc: 38cf876b
   score: 100
 ---
 
-# fix.mjs
-
-## Огляд
-
 Огляд: Функція run виконує перевірку правила. Повертає число, що інформує про успішність або порушення. Виконання правила через командний рядок повертає код виходу, який встановлює статус процесу.
 
 ## Поведінка

package/rules/rego/docs/index.md

@@ -0,0 +1,11 @@
+---
+type: Directory Index
+title: npm/rules/rego
+resource: npm/rules/rego/
+---
+
+# npm/rules/rego
+
+| Файл | Тип |
+|---|---|
+| [fix.mjs](fix.md) | JS Module |

package/rules/rego/js/docs/applies.md

@@ -1,14 +1,12 @@
 ---
+type: JS Module
+title: applies.mjs
+resource: npm/rules/rego/js/applies.mjs
 docgen:
-  source: npm/rules/rego/js/applies.mjs
   crc: 059e378c
   score: 100
 ---
 
-# applies.mjs
-
-## Огляд
-
 Файл виконує перевірку наявності файлів із розширенням `.rego` у визначеній директорії. Функція видає повідомлення про старт перевірки та повертає код виходу.
 
 ## Поведінка

package/rules/rego/js/docs/index.md

@@ -0,0 +1,12 @@
+---
+type: Directory Index
+title: npm/rules/rego/js
+resource: npm/rules/rego/js/
+---
+
+# npm/rules/rego/js
+
+| Файл | Тип |
+|---|---|
+| [applies.mjs](applies.md) | JS Module |
+| [lint.mjs](lint.md) | JS Module |

package/rules/rego/js/docs/lint.md

@@ -1,14 +1,12 @@
 ---
+type: JS Module
+title: lint.mjs
+resource: npm/rules/rego/js/lint.mjs
 docgen:
-  source: npm/rules/rego/js/lint.mjs
   crc: 8c033173
   score: 100
 ---
 
-# lint.mjs
-
-## Огляд
-
 Файл виконує передачу перевірок у наявні CLI правила. Функція повертає Promise з кодом виходу.
 
 ## Поведінка

package/rules/rego/lint/docs/index.md

@@ -0,0 +1,11 @@
+---
+type: Directory Index
+title: npm/rules/rego/lint
+resource: npm/rules/rego/lint/
+---
+
+# npm/rules/rego/lint
+
+| Файл | Тип |
+|---|---|
+| [lint.mjs](lint.md) | JS Module |

package/rules/rego/lint/docs/lint.md

@@ -1,13 +1,11 @@
 ---
+type: JS Module
+title: lint.mjs
+resource: npm/rules/rego/lint/lint.mjs
 docgen:
-  source: npm/rules/rego/lint/lint.mjs
   crc: 1059537a
 ---
 
-# lint.mjs — Лінт Rego-полісі (`opa` + `regal` + опційний `conftest`)
-
-## Огляд
-
 Модуль реалізує лінт-крок для Rego-полісі пакета `@nitra/cursor`, який живуть у каталозі
 `npm/rules/<id>/policy/<concern>/`. Він послідовно запускає три інструменти й повертає код
 виходу першого, що впав:

package/rules/release/docs/change.md

@@ -1,13 +1,11 @@
 ---
+type: JS Module
+title: change.mjs
+resource: npm/rules/release/change.mjs
 docgen:
-  source: npm/rules/release/change.mjs
   crc: 1ff4f816
 ---
 
-# `change.mjs` — створення одного change-файлу
-
-## Огляд
-
 Модуль реалізує CLI-команду `n-cursor change`, яка створює **один** change-файл у каталозі `<ws>/.changes/<timestamp>-<rand>.md` усередині конкретного workspace монорепо. Файл містить мінімальний YAML-frontmatter (`bump`, `section`) та текст опису зміни.
 
 Призначення — замінити ручне редагування `CHANGELOG.md` під час feature-флоу: розробник (або агент) додає декларативний запис про зміну, а агрегація у фінальний `CHANGELOG.md` відбувається пізніше в CI (відповідно до правила `n-changelog.mdc` v3.0).

package/rules/release/docs/fix.md

@@ -1,14 +1,12 @@
 ---
+type: JS Module
+title: fix.mjs
+resource: npm/rules/release/fix.mjs
 docgen:
-  source: npm/rules/release/fix.mjs
   crc: 22936815
   score: 100
 ---
 
-# fix.mjs
-
-## Огляд
-
 Файл ініціює виконання визначеного правила. Правило виконує необхідні дії з наданим контекстом. Виконане правило повертає отриманий результат.
 
 ## Поведінка

package/rules/release/docs/index.md

@@ -0,0 +1,13 @@
+---
+type: Directory Index
+title: npm/rules/release
+resource: npm/rules/release/
+---
+
+# npm/rules/release
+
+| Файл | Тип |
+|---|---|
+| [change.mjs](change.md) | JS Module |
+| [fix.mjs](fix.md) | JS Module |
+| [release.mjs](release.md) | JS Module |

package/rules/release/docs/release.md

@@ -1,13 +1,11 @@
 ---
+type: JS Module
+title: release.mjs
+resource: npm/rules/release/release.mjs
 docgen:
-  source: npm/rules/release/release.mjs
-  crc: b2b02de4
+  crc: 9aa2796b
 ---
 
-# `release.mjs` — оркестратор реліз-процесу `n-cursor release`
-
-## Огляд
-
 Модуль `npm/rules/release/release.mjs` — це ядро команди `n-cursor release`. Він агрегує per-workspace change-файли (накопичені у `CHANGES_DIR` кожного воркспейсу) у:
 
 1. version-bump у маніфесті пакета (`package.json` для npm-пакетів або `pyproject.toml` для Python),

package/rules/release/lib/docs/aggregate.md

@@ -1,13 +1,11 @@
 ---
+type: JS Module
+title: aggregate.mjs
+resource: npm/rules/release/lib/aggregate.mjs
 docgen:
-  source: npm/rules/release/lib/aggregate.mjs
   crc: 1f78a0fe
 ---
 
-# aggregate.mjs
-
-## Огляд
-
 Модуль `aggregate.mjs` забезпечує **агрегацію change-файлів одного workspace** у дві основні сутності:
 
 1. Новий рядок версії згідно semver-правил (`x.y.z` → бамп `major|minor|patch`).

package/rules/release/lib/docs/change-file.md

@@ -1,11 +1,11 @@
 ---
+type: JS Module
+title: change-file.mjs
+resource: npm/rules/release/lib/change-file.mjs
 docgen:
-  source: npm/rules/release/lib/change-file.mjs
   crc: 9284bc96
 ---
 
-# `change-file.mjs`
-
 Модуль для роботи з одиничним **change-файлом** релізного процесу — невеликою markdown-нотаткою, що описує одну зміну в межах workspace і агрегується пізніше при формуванні CHANGELOG / bump версії.
 
 ## Огляд

package/rules/release/lib/docs/fallback.md

@@ -1,13 +1,11 @@
 ---
+type: JS Module
+title: fallback.mjs
+resource: npm/rules/release/lib/fallback.mjs
 docgen:
-  source: npm/rules/release/lib/fallback.mjs
   crc: 99eb10bc
 ---
 
-# fallback.mjs
-
-## Огляд
-
 Модуль `fallback.mjs` реалізує **третє рішення** з ADR `n-cursor-release-design`: коли в певному workspace монорепо виявлено релевантні зміни, але **жодного change-файлу** від розробника не з’явилося, релізний пайплайн все одно повинен мати запис у CHANGELOG. Для цього модуль **синтезує** один штучний запис `change` із commit-subject-ів, які з’явилися від моменту останнього релізного тегу формату `<name>@*` до `HEAD`, обмежуючи журнал git pathspec-ом самого workspace.
 
 Файл експортує дві функції:

package/rules/release/lib/docs/index.md

@@ -0,0 +1,13 @@
+---
+type: Directory Index
+title: npm/rules/release/lib
+resource: npm/rules/release/lib/
+---
+
+# npm/rules/release/lib
+
+| Файл | Тип |
+|---|---|
+| [aggregate.mjs](aggregate.md) | JS Module |
+| [change-file.mjs](change-file.md) | JS Module |
+| [fallback.mjs](fallback.md) | JS Module |

package/rules/release/release.mjs

@@ -64,6 +64,45 @@ async function collectChangeFiles(cwd, manifest, runGit) {
   return [{ file: null, entry: synthesized }]
 }
 
+/**
+ * Пушить release-коміт (із тегами) у апстрім, переживаючи паралельні push у ту саму гілку.
+ * `runGit` — ТИХИЙ раннер (повертає null при помилці), тож non-fast-forward push не кидає, а
+ * повертає null; цей хелпер ЯВНО перевіряє результат, щоб реліз не «вдався» без приземленого
+ * commit-back (саме така мовчазна поразка лишала npm попереду git). За відмовою push:
+ * fetch + rebase release-коміту на свіжий апстрім, пересунути теги на новий HEAD і повторити
+ * (до `attempts` разів). Без апстріму або при rebase-конфлікті — кидаємо, а не маскуємо.
+ * @param {(args: string[]) => Promise<string | null>} runGit git-раннер
+ * @param {string[]} tags теги релізу (вже створені на поточному HEAD)
+ * @param {number} [attempts] максимум спроб push
+ * @returns {Promise<void>} результат; кидає, якщо push так і не приземлився
+ */
+async function pushReleaseWithRetry(runGit, tags, attempts = 5) {
+  for (let attempt = 1; attempt <= attempts; attempt++) {
+    const pushed = await runGit(['push', '--follow-tags'])
+    if (pushed !== null) return
+    if (attempt === attempts) break
+    // push відхилено (найімовірніше non-fast-forward — апстрім пішов уперед) → інтегруємо й пробуємо ще
+    const upstream = (await runGit(['rev-parse', '--abbrev-ref', '--symbolic-full-name', '@{u}']))?.trim()
+    if (!upstream) {
+      throw new Error('release: git push відхилено, а upstream для rebase немає — commit-back не приземлився')
+    }
+    const remote = upstream.includes('/') ? upstream.slice(0, upstream.indexOf('/')) : 'origin'
+    await runGit(['fetch', remote])
+    const rebased = await runGit(['rebase', upstream])
+    if (rebased === null) {
+      await runGit(['rebase', '--abort'])
+      throw new Error(`release: push відхилено і rebase на ${upstream} дав конфлікт — розв'яжи вручну`)
+    }
+    // після rebase хеш release-коміту змінився → пересуваємо теги на новий HEAD
+    for (const tag of tags) {
+      await runGit(['tag', '-f', tag])
+    }
+  }
+  throw new Error(
+    `release: git push не вдався після ${attempts} спроб (non-fast-forward?) — commit-back не приземлився, реліз неуспішний`
+  )
+}
+
 /**
  * @param {object} [opts] опції
  * @param {string} [opts.cwd] корінь
@@ -112,7 +151,7 @@ export async function release(opts = {}) {
     for (const tag of tags) {
       await runGit(['tag', tag])
     }
-    await runGit(['push', '--follow-tags'])
+    await pushReleaseWithRetry(runGit, tags)
   }
   return released
 }

package/rules/rust/docs/fix.md

@@ -1,14 +1,12 @@
 ---
+type: JS Module
+title: fix.mjs
+resource: npm/rules/rust/fix.mjs
 docgen:
-  source: npm/rules/rust/fix.mjs
   crc: 38cf876b
   score: 100
 ---
 
-# fix.mjs
-
-## Огляд
-
 Огляд
 Файл надає механізм для виконання стандартних правил. Використовується для запуску правил через функцію runStandardRule та для запуску правил у режимі командного рядка через runRuleCli.
 

package/rules/rust/docs/index.md

@@ -0,0 +1,11 @@
+---
+type: Directory Index
+title: npm/rules/rust
+resource: npm/rules/rust/
+---
+
+# npm/rules/rust
+
+| Файл | Тип |
+|---|---|
+| [fix.mjs](fix.md) | JS Module |

package/rules/rust/js/docs/applies.md

@@ -1,14 +1,12 @@
 ---
+type: JS Module
+title: applies.mjs
+resource: npm/rules/rust/js/applies.mjs
 docgen:
-  source: npm/rules/rust/js/applies.mjs
   crc: 4cc601f5
   score: 100
 ---
 
-# applies.mjs
-
-## Огляд
-
 Огляд
 Файл виконує перевірку наявності файлу Cargo.toml у кореневому репозиторії та підкаталогах. Функція check генерує звіт про порушення конфігураційних правил.
 

package/rules/rust/js/docs/index.md

@@ -0,0 +1,11 @@
+---
+type: Directory Index
+title: npm/rules/rust/js
+resource: npm/rules/rust/js/
+---
+
+# npm/rules/rust/js
+
+| Файл | Тип |
+|---|---|
+| [applies.mjs](applies.md) | JS Module |

package/rules/rust/lib/docs/has-cargo-toml.md

@@ -1,13 +1,11 @@
 ---
+type: JS Module
+title: has-cargo-toml.mjs
+resource: npm/rules/rust/lib/has-cargo-toml.mjs
 docgen:
-  source: npm/rules/rust/lib/has-cargo-toml.mjs
   crc: f55fc57e
 ---
 
-# has-cargo-toml.mjs
-
-## Огляд
-
 Модуль `has-cargo-toml.mjs` — rule-local утиліта для правил Rust, що визначає наявність маніфесту Cargo (`Cargo.toml`) у дереві файлової системи, починаючи з заданого кореневого каталогу. Використовується як applies-walker на рівні правила: дозволяє правилу Rust динамічно вирішувати, чи варто застосовуватися до конкретного workspace/cwd, шукаючи `Cargo.toml` у поточному каталозі або в будь-якому з підкаталогів.
 
 Реалізація — синхронний рекурсивний обхід каталогів з раннім поверненням (`early return`) при першому ж знайденому `Cargo.toml`, без читання вмісту файлів. Імена директорій, у які заходити не треба (наприклад, `node_modules`, `.git`, `.next`, `.turbo`), передаються ззовні через `Set<string>` — модуль свідомо не містить власного списку, щоб список ігнорувань був єдиним з тим, що в `npm/scripts/auto-rules.mjs` (на рівні виклику).

package/rules/rust/lib/docs/index.md

@@ -0,0 +1,11 @@
+---
+type: Directory Index
+title: npm/rules/rust/lib
+resource: npm/rules/rust/lib/
+---
+
+# npm/rules/rust/lib
+
+| Файл | Тип |
+|---|---|
+| [has-cargo-toml.mjs](has-cargo-toml.md) | JS Module |

package/rules/security/docs/fix.md

@@ -1,14 +1,12 @@
 ---
+type: JS Module
+title: fix.mjs
+resource: npm/rules/security/fix.mjs
 docgen:
-  source: npm/rules/security/fix.mjs
   crc: 38cf876b
   score: 70
 ---
 
-# fix.mjs
-
-## Огляд
-
 Файл ініціює виконання визначеного правила. Правило виконує операцію `applies` з використанням `JS-concerns` для отримання `policy` з `mdc-refs`. При завершенні роботи, якщо виконання відбувається через командний рядок, повертається код виходу для встановлення статусу завершення процесу.
 
 ## Поведінка

package/rules/security/docs/index.md

@@ -0,0 +1,11 @@
+---
+type: Directory Index
+title: npm/rules/security
+resource: npm/rules/security/
+---
+
+# npm/rules/security
+
+| Файл | Тип |
+|---|---|
+| [fix.mjs](fix.md) | JS Module |