@nitra/cursor 1.0.0

package/README.md

@@ -0,0 +1,82 @@
+# @nitra/cursor
+
+Консольна утиліта для завантаження cursor-правил Nitra у локальний git-репозиторій.
+
+## Як це працює
+
+Репозиторій `@nitra/cursor` містить cursor-правила у директорії `mdc/`. CLI завантажує обрані правила з npm (через unpkg.com) і копіює їх у `.cursor/rules/` поточного проекту з префіксом `nitra-`.
+
+Наприклад, правило `mdc/js-format.mdc` буде збережено як `.cursor/rules/nitra-js-format.mdc`.
+
+## Підготовка
+
+Перед першим запуском у вашому репозиторії створіть файл `nitra-cursor.json` у корені проекту зі списком правил для завантаження:
+
+```json
+{
+  "rules": [
+    "js-format",
+    "npm-module",
+    "spell"
+  ]
+}
+```
+
+Доступні правила:
+
+| Назва        | Опис                                              |
+| ------------ | ------------------------------------------------- |
+| `js-format`  | Правила форматування JavaScript ecosystem (oxfmt) |
+| `npm-module` | Структура репозиторію для npm-модуля (bun mono)   |
+| `spell`      | Перевірка правопису через cspell                  |
+
+Щоб завантажити правила конкретної версії пакету, додайте поле `version`:
+
+```json
+{
+  "version": "2.5.0",
+  "rules": ["js-format", "spell"]
+}
+```
+
+## Запуск
+
+```bash
+npx @nitra/cursor
+```
+
+CLI автоматично:
+
+1. Знайде `nitra-cursor.json` у поточній директорії
+2. Завантажить кожне з перелічених правил з unpkg.com
+3. Створить директорію `.cursor/rules/` якщо вона відсутня
+4. Збереже файли з префіксом `nitra-`
+
+## Приклад виводу
+
+```
+🔧 @nitra/cursor — завантаження cursor-правил
+
+📋 Правил до завантаження: 3
+  ⬇  js-format → .cursor/rules/nitra-js-format.mdc ... ✅
+  ⬇  npm-module → .cursor/rules/nitra-npm-module.mdc ... ✅
+  ⬇  spell → .cursor/rules/nitra-spell.mdc ... ✅
+
+✨ Готово: 3 завантажено, 0 з помилками
+```
+
+## Структура пакету
+
+```
+npm/
+├── mdc/               # cursor-правила
+│   ├── js-format.mdc
+│   ├── npm-module.mdc
+│   └── spell.mdc
+└── src/
+    └── cli.js         # CLI-скрипт
+```
+
+## Мета проекту
+
+Консольна утиліта яка дозволить оновлювати в локальних GIT репозиторіях правила для cursor з можливістю наслідування правил від файлів в цьому репозиторії та забезпечення версійності правил для cursor.

package/mdc/js-format.mdc

@@ -0,0 +1,95 @@
+---
+description: Правила форматів JavaScript ecosystem
+alwaysApply: true
+version: '1.0'
+---
+
+В корені проекту є файл з правилами форматування для oxfmt:
+
+```json title=".oxfmtrc.json"
+{
+  "arrowParens": "avoid",
+  "printWidth": 120,
+  "bracketSpacing": true,
+  "bracketSameLine": true,
+  "embeddedLanguageFormatting": "auto",
+  "endOfLine": "lf",
+  "htmlWhitespaceSensitivity": "css",
+  "insertPragma": false,
+  "jsxSingleQuote": true,
+  "proseWrap": "preserve",
+  "quoteProps": "as-needed",
+  "requirePragma": false,
+  "semi": false,
+  "singleQuote": true,
+  "tabWidth": 2,
+  "trailingComma": "none",
+  "useTabs": false,
+  "vueIndentScriptAndStyle": false
+}
+```
+
+в файлі .vscode/extensions.json є налаштування для oxfmt:
+
+```json title=".vscode/extensions.json"
+{
+  "recommendations": ["oxc.oxc-vscode"]
+}
+```
+
+в файлі .vscode/settings.json є налаштування для oxfmt:
+
+```json title=".vscode/settings.json"
+{
+  "editor.formatOnSave": true,
+  "[css]": {
+    "editor.defaultFormatter": "oxc.oxc-vscode"
+  },
+  "[graphql]": {
+    "editor.defaultFormatter": "oxc.oxc-vscode"
+  },
+  "[handlebars]": {
+    "editor.defaultFormatter": "oxc.oxc-vscode"
+  },
+  "[html]": {
+    "editor.defaultFormatter": "oxc.oxc-vscode"
+  },
+  "[javascript]": {
+    "editor.defaultFormatter": "oxc.oxc-vscode"
+  },
+  "[json]": {
+    "editor.defaultFormatter": "oxc.oxc-vscode"
+  },
+  "[json5]": {
+    "editor.defaultFormatter": "oxc.oxc-vscode"
+  },
+  "[jsonc]": {
+    "editor.defaultFormatter": "oxc.oxc-vscode"
+  },
+  "[less]": {
+    "editor.defaultFormatter": "oxc.oxc-vscode"
+  },
+  "[markdown]": {
+    "editor.defaultFormatter": "oxc.oxc-vscode"
+  },
+  "[mdx]": {
+    "editor.defaultFormatter": "oxc.oxc-vscode"
+  },
+  "[scss]": {
+    "editor.defaultFormatter": "oxc.oxc-vscode"
+  },
+  "[toml]": {
+    "editor.defaultFormatter": "oxc.oxc-vscode"
+  },
+  "[typescript]": {
+    "editor.defaultFormatter": "oxc.oxc-vscode"
+  },
+  "[vue]": {
+    "editor.defaultFormatter": "oxc.oxc-vscode"
+  },
+  "[yaml]": {
+    "editor.defaultFormatter": "oxc.oxc-vscode"
+  },
+  "oxc.path.oxfmt": "/opt/homebrew/bin/oxfmt"
+}
+```

package/mdc/npm-module.mdc

@@ -0,0 +1,14 @@
+---
+description: Оформлення репозиторію для npm модуля
+alwaysApply: true
+version: '1.0'
+---
+
+Проект представляє собою Bun monorepo
+
+Структура проекту:
+
+- .github/workflows/ - скрипти для github actions
+- demo/ - опціонально демо проект
+- npm/ - файли для npm модуля
+- package.json

package/mdc/spell.mdc

@@ -0,0 +1,71 @@
+---
+description: Перевірка правопису в текстових файлах
+alwaysApply: true
+version: '1.1'
+---
+
+У корені проекту має бути `.cspell.json` і залежності для cspell у кореневому `package.json` (зазвичай `devDependencies`).
+
+## Базовий варіант (без окремого словника української)
+
+Якщо текст переважно англійською та достатньо словника nitra:
+
+```json title=".cspell.json"
+{
+  "version": "0.2",
+  "language": "nitra",
+  "ignorePaths": ["**/node_modules/**", "**/vscode-extension/**", "**/.git/**", ".vscode", "report"],
+  "import": ["@nitra/cspell-dict/cspell-ext.json"],
+  "words": []
+}
+```
+
+```json title="package.json"
+{
+  "devDependencies": {
+    "@nitra/cspell-dict": "^1.0.185"
+  }
+}
+```
+
+## Проєкт з українською мовою
+
+Якщо в репозиторії є українська документація, коментарі або рядки в коді — потрібен **окремий словник** `@cspell/dict-uk-ua`, інакше cspell не перевірятиме український правопис коректно.
+
+**1. Залежності** — додай пакет словника поруч із `@nitra/cspell-dict`:
+
+```json title="package.json"
+{
+  "devDependencies": {
+    "@nitra/cspell-dict": "^1.0.185",
+    "@cspell/dict-uk-ua": "^4.0.6"
+  }
+}
+```
+
+Встановлення: `bun add -d @cspell/dict-uk-ua` (або `npm i -D @cspell/dict-uk-ua`).
+
+**2. `.cspell.json`** — у полі `language` має бути `uk` (разом з іншими мовами через кому), у `import` — підключення розширення українського словника:
+
+```json title=".cspell.json"
+{
+  "version": "0.2",
+  "language": "en,uk,nitra",
+  "ignorePaths": ["**/node_modules/**", "**/vscode-extension/**", "**/.git/**", ".vscode", "report"],
+  "import": [
+    "@nitra/cspell-dict/cspell-ext.json",
+    "@cspell/dict-uk-ua/cspell-ext.json"
+  ],
+  "words": []
+}
+```
+
+Підлаштуй `language` під проєкт (наприклад додай `ru-ru`, якщо потрібна перевірка російською). Порядок у `import` може впливати на пріоритет словників — тримай корпоративний `@nitra/cspell-dict` там, де зручно для ваших правил.
+
+## Локальні виключення
+
+У секції `words` у `.cspell.json` додають власні терміни, імена та скорочення, яких немає в словниках.
+
+## Інші мови
+
+Для іншої мови встанови відповідний пакет `@cspell/dict-*`, додай його `cspell-ext.json` у `import` і код мови в `language`. Огляд словників: [streetsidesoftware/cspell-dicts](https://github.com/streetsidesoftware/cspell-dicts).

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@nitra/cursor",
+  "version": "1.0.0",
+  "description": "CLI для завантаження cursor-правил Nitra у локальний репозиторій",
+  "keywords": [
+    "cli",
+    "cursor",
+    "cursor-rules",
+    "mdc",
+    "nitra"
+  ],
+  "homepage": "https://github.com/nitra/cursor#readme",
+  "bugs": {
+    "url": "https://github.com/nitra/cursor/issues"
+  },
+  "license": "ISC",
+  "author": "v@nitra.ai",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nitra/cursor.git"
+  },
+  "bin": {
+    "nitra-cursor": "./src/cli.js"
+  },
+  "files": [
+    "mdc",
+    "src"
+  ],
+  "type": "module",
+  "scripts": {
+    "test": "npx coverage-node test/index.js"
+  },
+  "dependencies": {}
+}

package/src/cli.js

@@ -0,0 +1,141 @@
+#!/usr/bin/env node
+
+/**
+ * @nitra/cursor CLI
+ *
+ * Завантажує cursor-правила з npm-пакету @nitra/cursor у локальний репозиторій.
+ *
+ * Використання:
+ *   npx @nitra/cursor
+ *
+ * Перед запуском у цільовому репо потрібно створити файл nitra-cursor.json
+ * зі списком правил для завантаження.
+ */
+
+import { readFile, writeFile, mkdir } from 'node:fs/promises'
+import { existsSync } from 'node:fs'
+import { join, basename } from 'node:path'
+import { cwd } from 'node:process'
+
+const PACKAGE_NAME = '@nitra/cursor'
+const UNPKG_BASE = 'https://unpkg.com'
+const CONFIG_FILE = 'nitra-cursor.json'
+const RULES_DIR = '.cursor/rules'
+const RULE_PREFIX = 'nitra-'
+
+/**
+ * Завантажує текст з URL
+ * @param {string} url
+ * @returns {Promise<string>}
+ */
+async function fetchText(url) {
+  const response = await fetch(url)
+  if (!response.ok) {
+    throw new Error(`HTTP ${response.status} — не вдалося завантажити: ${url}`)
+  }
+  return response.text()
+}
+
+/**
+ * Зчитує конфіг nitra-cursor.json з поточної директорії
+ * @returns {Promise<{rules: string[], version?: string}>}
+ */
+async function readConfig() {
+  const configPath = join(cwd(), CONFIG_FILE)
+  if (!existsSync(configPath)) {
+    throw new Error(
+      `Файл конфігурації не знайдено: ${CONFIG_FILE}\n` +
+      `Створіть файл ${CONFIG_FILE} у корені репозиторію.\n` +
+      `Приклад:\n` +
+      `{\n  "rules": ["js-format", "npm-module", "spell"]\n}`
+    )
+  }
+  const raw = await readFile(configPath, 'utf8')
+  let config
+  try {
+    config = JSON.parse(raw)
+  } catch {
+    throw new Error(`Невірний JSON у файлі ${CONFIG_FILE}`)
+  }
+  if (!Array.isArray(config.rules) || config.rules.length === 0) {
+    throw new Error(`У ${CONFIG_FILE} має бути непорожній масив "rules"`)
+  }
+  return config
+}
+
+/**
+ * Повертає URL для завантаження правила з unpkg
+ * @param {string} ruleName — ім'я без розширення, наприклад "js-format"
+ * @param {string} [version] — версія пакету (необов'язково, за замовчуванням "latest")
+ * @returns {string}
+ */
+function buildUrl(ruleName, version) {
+  const name = ruleName.endsWith('.mdc') ? ruleName : `${ruleName}.mdc`
+  const ver = version ? `@${version}` : '@latest'
+  return `${UNPKG_BASE}/${PACKAGE_NAME}${ver}/mdc/${name}`
+}
+
+/**
+ * Витягує чисте ім'я файлу правила (без шляху, але зберігає .mdc)
+ * "npm/mdc/js-format.mdc" → "js-format.mdc"
+ * "js-format"              → "js-format.mdc"
+ * @param {string} ruleName
+ * @returns {string}
+ */
+function normalizeRuleName(ruleName) {
+  const name = ruleName.endsWith('.mdc') ? ruleName : `${ruleName}.mdc`
+  return basename(name)
+}
+
+async function main() {
+  console.log(`\n🔧 @nitra/cursor — завантаження cursor-правил\n`)
+
+  // 1. Зчитуємо конфіг
+  let config
+  try {
+    config = await readConfig()
+  } catch (err) {
+    console.error(`❌ ${err.message}`)
+    process.exit(1)
+  }
+
+  const { rules, version } = config
+  if (version) {
+    console.log(`📦 Версія пакету: ${version}`)
+  }
+  console.log(`📋 Правил до завантаження: ${rules.length}`)
+
+  // 2. Створюємо директорію .cursor/rules якщо не існує
+  const rulesDir = join(cwd(), RULES_DIR)
+  await mkdir(rulesDir, { recursive: true })
+
+  // 3. Завантажуємо та зберігаємо кожне правило
+  let successCount = 0
+  let failCount = 0
+
+  for (const rule of rules) {
+    const url = buildUrl(rule, version)
+    const fileName = `${RULE_PREFIX}${normalizeRuleName(rule)}`
+    const destPath = join(rulesDir, fileName)
+
+    try {
+      process.stdout.write(`  ⬇  ${rule} → ${RULES_DIR}/${fileName} ... `)
+      const content = await fetchText(url)
+      await writeFile(destPath, content, 'utf8')
+      console.log(`✅`)
+      successCount++
+    } catch (err) {
+      console.log(`❌`)
+      console.error(`     Помилка: ${err.message}`)
+      failCount++
+    }
+  }
+
+  // 4. Підсумок
+  console.log(`\n✨ Готово: ${successCount} завантажено, ${failCount} з помилками\n`)
+  if (failCount > 0) {
+    process.exit(1)
+  }
+}
+
+main()