@nitra/cursor

Консольна утиліта для завантаження cursor-правил із префіксом n- у локальний git-репозиторій.

Як це працює

Репозиторій @nitra/cursor містить cursor-правила у директорії mdc/. CLI копіює обрані правила з каталогу mdc/ того пакету, з якого виконується bin/n-cursor.js: після npm i / bun add це зазвичай node_modules/@nitra/cursor/mdc; при npx @nitra/cursor пакет потрапляє в кеш npx/npm, і правила читаються з тієї розпакованої копії (у корені проєкту залежність не обов’язкова). Жодних окремих HTTP-запитів до CDN для файлів правил немає — лише те, що вже є в tarball пакету.

Наприклад, правило mdc/text.mdc буде збережено як .cursor/rules/n-text.mdc.

Підготовка

Перед першим запуском у вашому репозиторії створіть файл .n-cursor.json у корені проекту зі списком правил для завантаження:

{
  "$schema": "https://unpkg.com/@nitra/cursor/schemas/n-cursor.json",
  "rules": ["npm-module", "text"],
  "skills": ["fix"]
}

Доступні правила:

| Назва | Опис | | ------------ | ----------------------------------------------- | | npm-module | Структура репозиторію для npm-модуля (bun mono) | | text | Текст, oxfmt, cspell, markdownlint, v8r, CI | | k8s | Kubernetes YAML, Kustomize, kubeconform |

Щоб використовувати конкретну версію правил, оновіть залежність @nitra/cursor у проєкті (bun add -d @nitra/cursor@<версія> тощо). Поле version у .n-cursor.json, якщо воно лишилось у старих конфігах, ігнорується.

Правило k8s і Kustomize

У цільовому репозиторії з маніфестами під **/k8s дотримуйтесь mdc/k8s.mdc з пакету (після синку — .cursor/rules/n-k8s.mdcабо копія зnode_modules/@nitra/cursor/mdc/k8s.mdc).

Коротко:

• Структура Kustomize: спільне виноситься в base; вміст base відповідає тому, як має виглядати середовище dev; окремої директорії dev/ немає — за dev відповідає base. У інших середовищах — тонкі overlays (часто лише kustomization.yaml і patches / оверрайди).
• Namespace задається в kustomization.yaml (namespace:), а не через metadata.namespace у кожному ресурсі; окремі patches лише на зміну namespace не потрібні.
• У Deployment для кожного контейнера: resources (перевіряє npx @nitra/cursor check k8s);
• Рядки в base, які змінюються в overlays, позначайте коментарем на рядку (узгоджено в команді), наприклад: # буде замінено через kustomize.
• Після перенесення в base / overlays видаляйте застарілі маніфести та каталоги, які більше не потрібні.

Повний текст правил — у k8s.mdc; programmatic перевірки — у npm/scripts/check-k8s.mjs (у встановленому пакеті — scripts/check-k8s.mjs).

v8r і власний каталог схем

Скрипт scripts/run-v8r.mjs передає в v8r каталог schemas/v8r-catalog.json пакета автоматично (у репозиторії той самий файл, що й npm/schemas/v8r-catalog.json від кореня монорепо). Якщо викликаєш bunx v8r напряму, передай -c: локально node_modules/@nitra/cursor/schemas/v8r-catalog.json або unpkg. JSON Schema конфігурації: n-cursor.json.

Запуск

npx @nitra/cursor
npx @nitra/cursor check
npx @nitra/cursor check bun ga

Команда check запускає programmatic перевірки з каталогу scripts/ пакету. Якщо в корені репозиторію вже є .n-cursor.json, перед перевірками виконується зчитування конфігу — зокрема додається або виправляється поле $schema, якщо воно відсутнє або не збігається з очікуваним URL.

CLI автоматично (команда завантаження правил без підкоманди check):

1. Знайде або створить .n-cursor.json у поточній директорії (із полем $schema на JSON Schema пакету; якщо файл уже є без коректного $schema, поле буде додано або оновлено при зчитуванні конфігу)
2. Створить директорію .cursor/rules/, якщо її ще немає
3. Скопіює кожне з перелічених у конфігу правило з mdc/ установленого пакету і збереже файли з префіксом n-
4. Після оновлення файлів на диску згенерує в корені проєкту AGENTS.md: повний вміст береться з шаблону пакету AGENTS.template.md, а список правил у шаблоні формується з усіх наявних файлів *.mdc у .cursor/rules/ (відсортовано за ім’ям)

Приклад виводу

🔧 @nitra/cursor — завантаження cursor-правил

📋 Правил до завантаження: 2
  ⬇  npm-module → .cursor/rules/n-npm-module.mdc ... ✅
  ⬇  text → .cursor/rules/n-text.mdc ... ✅
📝 Оновлено AGENTS.md з AGENTS.template.md

✨ Готово: 2 завантажено, 0 з помилками

Структура пакету

npm/
├── AGENTS.template.md   # шаблон AGENTS.md для цільових репозиторіїв (потрапляє в npm-архів)
├── mdc/                 # cursor-правила (без префікса n-; після синку — .cursor/rules/n-<id>.mdc)
│   ├── npm-module.mdc
│   └── text.mdc
├── skills/              # skills (каталоги <id>/; після синку — .cursor/skills/n-<id>/)
└── bin/
    └── n-cursor.js  # CLI-скрипт

AGENTS.md у проєкті користувача

Після кожного успішного проходу завантаження правил CLI повністю перезаписує файл AGENTS.md у корені поточної директорії (та сама директорія, де лежить .n-cursor.json).

• Джерело тексту — файл AGENTS.template.md з установленого пакету @nitra/cursor (його не редагують у чужому репозиторії; зміни вносять у цьому репозиторії пакету).
• Динамічний список правил - Скрипт зчитує каталог .cursor/rules/ і для кожного файлу з розширенням .mdc додає в шаблон рядок виду - .cursor/rules/<ім’я>.mdc. Туди потрапляють і керовані правила з префіксом n-, і будь-які інші .mdc, які вже лежать у цій папці.
• Редагувати згенерований AGENTS.md у проєкті користувача немає сенсу — наступний запуск CLI знову замінить файл. Власні інструкції для агентів треба закладати в AGENTS.template.md у репозиторії @nitra/cursor або тримати окремо від автогенерації.

Інструкція для розробників пакету

Зміна шаблону AGENTS

1. Редагуйте npm/AGENTS.template.md. Файл має бути перелічений у полі files у npm/package.json, щоб потрапляти в публікацію npm (разом з mdc/ та bin/).
2. Для вставки списку файлів правил використовуйте блок у стилі Mustache з ім’ям секції services і плейсхолдером {{name}}:

{{#services}}
{{name}}
{{/services}}

Під час запуску CLI тіло між {{#services}} і {{/services}} повторюється для кожного *.mdc у .cursor/rules/; у {{name}} підставляється вже готовий markdown-рядок (наприклад - .cursor/rules/n-text.mdc).

3. Після змін у шаблоні перевірте локально: у тестовому репозиторії з .n-cursor.json виконайте npx/bunx на зібраному пакеті або node npm/bin/n-cursor.js з кореня того репозиторію і переконайтеся, що AGENTS.md виглядає як очікується.

Логіка в коді CLI

• Шлях до шаблону: поруч із mdc/, тобто …/node_modules/@nitra/cursor/AGENTS.template.md після встановлення пакету.
• Оновлення AGENTS.md виконується після циклу завантаження правил, щоб список відображав актуальний вміст .cursor/rules/ на диску.
• Якщо каталогу .cursor/rules/ немає або в ньому немає *.mdc, блок {{#services}} стає порожнім; решта шаблону все одно записується в AGENTS.md.

Мета проекту

Консольна утиліта яка дозволить оновлювати в локальних GIT репозиторіях правила для cursor з можливістю наслідування правил від файлів в цьому репозиторії та забезпечення версійності правил для cursor.