@nitra/cursor 1.1.0 → 1.2.1

package/AGENTS.template.md

@@ -0,0 +1,35 @@
+# AGENTS.md version: '1.0'
+
+## Purpose
+
+This file is the entry point for all AI agents working with this repository.
+
+## Rule source
+
+The primary development rules are stored in the Cursor rules directory:
+
+{{#services}}
+{{name}}
+{{/services}}
+
+## Instructions for all agents
+
+Before making changes, read the relevant rule files for the area you are working on.
+
+## Priority
+
+If rules conflict:
+
+1. AGENTS.md
+2. task-specific rule file
+3. core rule file
+
+## Language
+
+Respond in Ukrainian.
+Keep technical terms in English.
+
+## Behavior
+
+Do not ignore referenced rule files.
+Explicitly follow repository conventions before proposing or applying changes.

package/README.md

@@ -14,11 +14,7 @@
 
 ```json
 {
-  "rules": [
-    "js-format",
-    "npm-module",
-    "spell"
-  ]
+  "rules": ["js-format", "npm-module", "spell"]
 }
 ```
 
@@ -47,10 +43,10 @@ npx @nitra/cursor
 
 CLI автоматично:
 
-1. Знайде `nitra-cursor.json` у поточній директорії
-2. Завантажить кожне з перелічених правил з unpkg.com
-3. Створить директорію `.cursor/rules/` якщо вона відсутня
-4. Збереже файли з префіксом `nitra-`
+1. Знайде або створить `nitra-cursor.json` у поточній директорії
+2. Створить директорію `.cursor/rules/`, якщо її ще немає
+3. Завантажить кожне з перелічених у конфігу правило з unpkg.com і збереже файли з префіксом `nitra-`
+4. Після оновлення файлів на диску згенерує в корені проєкту **`AGENTS.md`**: повний вміст береться з шаблону пакету `AGENTS.template.md`, а список правил у шаблоні формується з **усіх наявних файлів `*.mdc`** у `.cursor/rules/` (відсортовано за ім’ям)
 
 ## Приклад виводу
 
@@ -61,6 +57,7 @@ CLI автоматично:
   ⬇  js-format → .cursor/rules/nitra-js-format.mdc ... ✅
   ⬇  npm-module → .cursor/rules/nitra-npm-module.mdc ... ✅
   ⬇  spell → .cursor/rules/nitra-spell.mdc ... ✅
+📝 Оновлено AGENTS.md з AGENTS.template.md
 
 ✨ Готово: 3 завантажено, 0 з помилками
 ```
@@ -69,7 +66,8 @@ CLI автоматично:
 
 ```
 npm/
-├── mdc/               # cursor-правила
+├── AGENTS.template.md   # шаблон AGENTS.md для цільових репозиторіїв (потрапляє в npm-архів)
+├── mdc/                 # cursor-правила
 │   ├── js-format.mdc
 │   ├── npm-module.mdc
 │   └── spell.mdc
@@ -77,6 +75,37 @@ npm/
     └── nitra-cursor.js  # CLI-скрипт
 ```
 
+## AGENTS.md у проєкті користувача
+
+Після кожного успішного проходу завантаження правил CLI **повністю перезаписує** файл **`AGENTS.md`** у корені поточної директорії (та сама директорія, де лежить `nitra-cursor.json`).
+
+- **Джерело тексту** — файл **`AGENTS.template.md`** з установленого пакету `@nitra/cursor` (його не редагують у чужому репозиторії; зміни вносять у цьому репозиторії пакету).
+- **Динамічний список правил** - Скрипт зчитує каталог **`.cursor/rules/`** і для **кожного файлу з розширенням `.mdc`** додає в шаблон рядок виду `- .cursor/rules/<ім’я>.mdc`. Туди потрапляють і правила Nitra з префіксом `nitra-`, і будь-які інші `.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}}`**:
+
+```markdown
+{{#services}}
+{{name}}
+{{/services}}
+```
+
+Під час запуску CLI тіло між `{{#services}}` і `{{/services}}` повторюється для кожного `*.mdc` у `.cursor/rules/`; у `{{name}}` підставляється вже готовий markdown-рядок (наприклад `- .cursor/rules/nitra-spell.mdc`).
+
+3. Після змін у шаблоні перевірте локально: у тестовому репозиторії з `nitra-cursor.json` виконайте `npx`/`bunx` на зібраному пакеті або `node npm/bin/nitra-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.

package/bin/nitra-cursor.js

@@ -10,6 +10,9 @@
  *
  * Якщо у корені репозиторію немає nitra-cursor.json, він створюється автоматично
  * з усіма правилами з каталогу mdc пакету (їх можна відредагувати після створення).
+ *
+ * Файл AGENTS.md у корені: щоразу повністю перезаписується змістом з AGENTS.template.md
+ * пакету; список правил у шаблоні будується з файлів *.mdc у .cursor/rules поточного проєкту.
  */
 
 import { existsSync } from 'node:fs'
@@ -21,11 +24,14 @@ import { fileURLToPath } from 'node:url'
 const PACKAGE_NAME = '@nitra/cursor'
 const UNPKG_BASE = 'https://unpkg.com'
 const CONFIG_FILE = 'nitra-cursor.json'
+const AGENTS_FILE = 'AGENTS.md'
+const AGENTS_TEMPLATE_FILE = 'AGENTS.template.md'
 const RULES_DIR = '.cursor/rules'
 const RULE_PREFIX = 'nitra-'
 
 const binDir = dirname(fileURLToPath(import.meta.url))
 const BUNDLED_MDC_DIR = join(binDir, '..', 'mdc')
+const BUNDLED_AGENTS_TEMPLATE_PATH = join(binDir, '..', AGENTS_TEMPLATE_FILE)
 
 /**
  * Імена правил (без .mdc) з каталогу mdc поточної інсталяції пакету
@@ -74,7 +80,7 @@ async function readConfig() {
     const defaultConfig = { rules }
     await writeFile(configPath, `${JSON.stringify(defaultConfig, null, 2)}\n`, 'utf8')
     console.log(
-      `📝 Створено ${CONFIG_FILE} з усіма правилами з пакету (${rules.length}). ` + `За потреби відредагуйте список.\n`
+      `📝 Створено ${CONFIG_FILE} з усіма правилами з пакету (${rules.length}). За потреби відредагуйте список.\n`
     )
     return defaultConfig
   }
@@ -115,6 +121,79 @@ function normalizeRuleName(ruleName) {
   return basename(name)
 }
 
+/**
+ * Розгортає в шаблоні блок Mustache {{#section}} … {{/section}} для масиву елементів
+ * @param {string} template вихідний текст шаблону
+ * @param {string} section ім'я секції (наприклад services)
+ * @param {Record<string, string>[]} items елементи для повторення тіла секції
+ * @param {string} prop ключ поля для підстановки замість {{prop}}
+ * @returns {string} текст після розгортання усіх входжень блоку
+ */
+function expandMustacheSection(template, section, items, prop) {
+  const open = `{{#${section}}}`
+  const close = `{{/${section}}}`
+  const placeholder = `{{${prop}}}`
+  let result = template
+  let start = result.indexOf(open)
+  let end = result.indexOf(close)
+  while (start !== -1 && end !== -1 && end > start) {
+    const inner = result.slice(start + open.length, end)
+    const rendered = items.map(item => inner.split(placeholder).join(String(item[prop]))).join('')
+    result = result.slice(0, start) + rendered + result.slice(end + close.length)
+    start = result.indexOf(open)
+    end = result.indexOf(close)
+  }
+  return result
+}
+
+/**
+ * Підставляє у вміст AGENTS.template.md список шляхів до файлів правил
+ * @param {string} templateText вміст AGENTS.template.md
+ * @param {string[]} mdcBasenames імена файлів (*.mdc) з .cursor/rules
+ * @returns {string} готовий markdown для AGENTS.md
+ */
+function renderAgentsTemplate(templateText, mdcBasenames) {
+  const items = mdcBasenames.map(mdcName => ({
+    name: `- ${RULES_DIR}/${mdcName}`
+  }))
+  return expandMustacheSection(templateText, 'services', items, 'name')
+}
+
+/**
+ * Повертає відсортовані імена *.mdc у .cursor/rules поточного проєкту
+ * @returns {Promise<string[]>} базові імена файлів (лише .mdc)
+ */
+async function listProjectRulesMdcFiles() {
+  const rulesDir = join(cwd(), RULES_DIR)
+  if (!existsSync(rulesDir)) {
+    return []
+  }
+  const names = await readdir(rulesDir)
+  return names.filter(n => n.endsWith('.mdc')).sort((a, b) => a.localeCompare(b))
+}
+
+/**
+ * Повністю перезаписує AGENTS.md у корені cwd з npm/AGENTS.template.md
+ * @returns {Promise<void>} завершення запису файлу
+ */
+async function syncAgentsMd() {
+  if (!existsSync(BUNDLED_AGENTS_TEMPLATE_PATH)) {
+    throw new Error(
+      `Не знайдено шаблон ${AGENTS_TEMPLATE_FILE} у пакеті.\n` +
+        `Очікуваний шлях: ${BUNDLED_AGENTS_TEMPLATE_PATH}\n` +
+        `Перевстановіть ${PACKAGE_NAME}.`
+    )
+  }
+  const templateText = await readFile(BUNDLED_AGENTS_TEMPLATE_PATH, 'utf8')
+  const mdcFiles = await listProjectRulesMdcFiles()
+  const body = renderAgentsTemplate(templateText, mdcFiles)
+  const agentsPath = join(cwd(), AGENTS_FILE)
+  const hadFile = existsSync(agentsPath)
+  const out = body.endsWith('\n') ? body : `${body}\n`
+  await writeFile(agentsPath, out, 'utf8')
+  console.log(hadFile ? `📝 Оновлено ${AGENTS_FILE} з ${AGENTS_TEMPLATE_FILE}` : `📝 Створено ${AGENTS_FILE} з ${AGENTS_TEMPLATE_FILE}`)
+}
+
 console.log(`\n🔧 @nitra/cursor — завантаження cursor-правил\n`)
 
 // 1. Зчитуємо конфіг
@@ -158,7 +237,15 @@ for (const rule of rules) {
   }
 }
 
-// 4. Підсумок
+// 4. AGENTS.md зі списком файлів *.mdc у .cursor/rules (після оновлення на диску)
+try {
+  await syncAgentsMd()
+} catch (error) {
+  console.error(`❌ Не вдалося оновити ${AGENTS_FILE}: ${error.message}`)
+  process.exit(1)
+}
+
+// 5. Підсумок
 console.log(`\n✨ Готово: ${successCount} завантажено, ${failCount} з помилками\n`)
 if (failCount > 0) {
   process.exit(1)

package/mdc/nginx-default-tpl.mdc

@@ -0,0 +1,108 @@
+---
+description: Правила nginx для статичних файлів
+version: '1.0'
+---
+
+# Якщо в проекті є файл default.tpl.conf або default.conf.template
+
+Якщо файл називається default.tpl.conf його потрібно перейменувати на default.conf.template
+
+default.conf.template повинен виглядати так:
+
+```nginx
+server_tokens off;
+port_in_redirect off;
+client_max_body_size 0;
+client_body_buffer_size 512M;
+
+server {
+    listen 8080;
+    server_name _;
+
+    # disable all log
+    access_log off;
+    error_log off;
+
+    # This would be the directory where your Vite app's static files are stored at
+    root /usr/share/nginx/html;
+
+    location /healthz {
+        add_header Content-Type text/plain;
+        access_log off;
+        return 200 "healthy";
+    }
+
+    # Без gz стиснених файлів, 1 year is 31536000 seconds
+    location ~ ^$PUBLIC_PATH/(.+\.(?:gif|jpe?g|png|ico|woff2|xlsx))$ {
+        alias /usr/share/nginx/html/$1;
+        add_header 'Cache-Control' "public,max-age=31536000,immutable";
+    }
+
+    # С gz стисненими файлами, 1 year is 31536000 seconds
+    location ~ ^$PUBLIC_PATH/(.+\.(?:svg|js|css|ttf|map|xml|webmanifest|wasm))$ {
+        alias /usr/share/nginx/html/$1;
+        add_header 'Cache-Control' "public,max-age=31536000,immutable";
+
+        # дозволяє віддавати замість звичайного файлу попередньо стиснутий файл з таким же ім'ям та з розширенням ".gz"
+        gzip_static on;
+    }
+
+    location $PUBLIC_PATH/ {
+        index index.html;
+        alias /usr/share/nginx/html/;
+
+        #  eliminates the step of copying the data into the buffer and enables direct copying data from one file descriptor to another.
+        sendfile on;
+        # to prevent one fast connection from entirely occupying the worker process
+        sendfile_max_chunk 512k;
+        # to send HTTP response headers in one packet right after the chunk of data has been obtained by sendfile().
+        tcp_nopush on;
+
+        # дозволяє віддавати замість звичайного файлу попередньо стиснутий файл з таким же ім'ям та з розширенням ".gz"
+        gzip_static on;
+
+        try_files $uri $uri/ /index.html =404;
+    }
+}
+```
+
+Тобто в ньому не потрібно щоб було жодного proxy_pass секціі і інших опцій для проxy.
+
+Якщо в файлі вже були proxy_pass секції, то їх логіку потрібно перенести до HTTPRoute в k8s.
+
+В Dockerfile потрібно додати команду для стиснення файлів, які потім використовуватимуться з `gzip_static on`:
+
+```dockerfile
+RUN for s in js css map xml webmanifest html wasm; do find /usr/share/nginx/html -type f -name "*.$$s" -exec gzip -k {} +; done
+```
+
+Поруч з файлом default.conf.template повинні бути конфігураційні файли *.ini для різних середовищ. В Dockerfile повинна бути команда, для заміни плейсхолдерів в цих файлах на значення з середовища:
+
+```dockerfile
+# 1) Витягнути імена змінних з ini (ігноруємо коментарі/порожні)
+# 2) Зробити список для envsubst: $NAMESPACE $NAMESPACE2 ...
+# 3) Підвантажити значення з ini і підставити лише їх
+RUN NAMES=$(sed -nE '/^\s*[#;]/d; /^\s*$/d; s/^\s*([A-Za-z_][A-Za-z0-9_]*)\s*=.*/\1/p' /tpl/values-$BRANCH.ini) && \
+ VARS=$(printf '%s\n' $NAMES | awk '{printf "$%s ", $0}') && \
+  export $(grep -v '^#' /tpl/values-$BRANCH.ini | xargs) && \
+  envsubst "$VARS" < /tpl/default.conf.template > /app/default.conf
+```
+
+в файлі .vscode/extensions.json є налаштування для oxfmt:
+
+```json title=".vscode/extensions.json"
+{
+  "recommendations": ["ahmadalli.vscode-nginx-conf"]
+}
+```
+
+в файлі .vscode/settings.json є налаштування для oxfmt:
+
+```json title=".vscode/settings.json"
+{
+  "editor.formatOnSave": true,
+  "[nginx]": {
+    "editor.defaultFormatter": "ahmadalli.vscode-nginx-conf"
+  }
+}
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nitra/cursor",
-  "version": "1.1.0",
+  "version": "1.2.1",
   "description": "CLI для завантаження cursor-правил Nitra у локальний репозиторій",
   "keywords": [
     "cli",
@@ -24,7 +24,8 @@
   },
   "files": [
     "mdc",
-    "bin"
+    "bin",
+    "AGENTS.template.md"
   ],
   "type": "module",
   "scripts": {