@nitra/cursor 10.1.0 → 10.2.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## [10.2.0] - 2026-06-15
+
+### Added
+
+- tool-surface rule — паритет «UI ↔ LLM ↔ оркестратор»: будь-яка дія фронтенду виконувана без UI через спільний каталог тулів (catalog → dispatch → UI/CLI/LLM-адаптери). Платформо-незалежне ядро; per-stack деталі делегуються правилам tauri/vue/capacitor. Авто-активація на фронтенд-залежностях. Додано per-stack секцію «Tool Surface у Tauri» в правило tauri (делегація в Rust-крейт/бінарник, два транспорти, схеми через schemars, дозволи плагінів).
+
 ## [10.1.0] - 2026-06-15
 
 ### Changed

package/bin/n-cursor.js

@@ -4,19 +4,18 @@
  * n-cursor — CLI завантаження правил та перевірки проєкту
  *
  * Використання:
- *   `npx \@nitra/cursor`             — завантажити cursor-правила
- *   `npx \@nitra/cursor fix`         — автономний оркестратор: T0-auto + LLM (haiku→sonnet); convergence-loop до чистого стану [--max-iter N] [rules]
- *                                     якщо в корені вже є `.n-cursor.json`, спочатку зчитується конфіг і за потреби дописується `$schema`
- *   `npx \@nitra/cursor fix bun`     — оркестратор лише для вказаних правил; `--json` = check-only (structured output для CI)
+ *   `npx \@nitra/cursor`             — завантажити cursor-правила (синк); якщо в корені вже є `.n-cursor.json`,
+ *                                     спочатку зчитується конфіг і за потреби дописується `$schema`
  *   `npx \@nitra/cursor rename-yaml-extensions` — k8s `*.yml` → `*.yaml`, `.github` `*.yaml` → `*.yml` (опції: `--dry-run`, `--root=…`; див. bin/rename-yaml-extensions.mjs)
  *   `npx \@nitra/cursor post-tool-use-fix` — точка входу PostToolUse hook Claude Code: читає stdin JSON,
  *                                     дістає `tool_input.file_path`, маршрутизує його у відповідні правила
  *                                     (`*.mjs` → `js-lint`, `*.vue` → `js-lint style-lint vue` тощо) і викликає
  *                                     `fix` лише з ними. Прописується автоматично в `.claude/settings.json`.
- *   `npx \@nitra/cursor fix`         — автономний оркестратор (meta.json: orchestrator:true): T0-auto → LLM via pi (haiku→sonnet) → check-gate → loop; [--max-iter N] [rules]
- *   `npx \@nitra/cursor lint`        — оркестратор lint-ланцюжка з кореневого `package.json` з вимірюванням часу
- *                                     кожного `lint-*` / `oxfmt` скрипта (fail-fast); канонічна заміна
- *                                     раніше ручного `lint-ga && lint-js && …` агрегатора.
+ *   `npx \@nitra/cursor lint`        — data-driven оркестратор lint+конформності по `rules/<id>/meta.json` (`lint: per-file|full`):
+ *                                     за замовчуванням fix-by-default по дельті vs origin (лише `per-file` правила); `--full` =
+ *                                     весь репо (`per-file` ∪ `full`); `--read-only` = без мутацій/LLM (CI); позиційні
+ *                                     (не-флаг) аргументи — фільтр правил конформності (мапить колишній `fix <rule>`).
+ *                                     CI = `lint --read-only --full` (весь репо, нуль мутацій/LLM).
  *   `npx \@nitra/cursor lint-ga`     — канонічний lint-ga (ga.mdc): preflight на `shellcheck` →
  *                                     `bunx github-actionlint` → `uvx zizmor --offline --collect=workflows .`
  *   `npx \@nitra/cursor lint-rego`   — канонічний lint-rego (conftest.mdc + rego.mdc):
@@ -1542,12 +1541,6 @@ try {
 
       break
     }
-    case 'lint-ci': {
-      // CI = весь репо в read-only (нуль мутацій, нуль LLM) — еквівалент `lint --read-only --full`.
-      process.exitCode = await runLint({ full: true, readOnly: true })
-
-      break
-    }
     case 'lint-ga': {
       // Канонічний lint-ga з preflight на shellcheck → actionlint → zizmor → check-ga (ga.mdc).
       // Останній крок (check-ga) async — тому await обов'язковий, інакше process.exitCode буде Promise.
@@ -1727,7 +1720,7 @@ try {
     default: {
       console.error(`❌ Невідома команда: ${command}`)
       console.error(
-        `   Очікується: (без аргументів) синхронізація правил, rename-yaml-extensions, post-tool-use-fix, lint, lint-ga, lint-rego, lint-k8s, lint-docker, lint-text, lint-doc-files, fix-doc-files, coverage, coverage-fix, taze, start-check, change, release, skill, worktree, lint-ci, trace, doc-files, doc-aggregate`
+        `   Очікується: (без аргументів) синхронізація правил, rename-yaml-extensions, post-tool-use-fix, lint, lint-ga, lint-rego, lint-k8s, lint-docker, lint-text, lint-doc-files, fix-doc-files, coverage, coverage-fix, taze, start-check, change, release, skill, worktree, trace, doc-files, doc-aggregate`
       )
       process.exitCode = 1
     }

package/package.json

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

package/rules/doc-files/js/docgen-extract.mjs

@@ -42,8 +42,13 @@ const IMPORT_AS_RE = /[ \t]{1,8}as[ \t]{1,8}.{0,200}/
 const WRITE_FS_RE = /\b(writeFile|mkdir|rmdir|unlink|appendFile|createWriteStream|rm\()/
 const CATCH_RE = /catch\s*\(/
 const TRY_RE = /\btry\s*\{/
-const FALSY_RETURN_RE = /return\s+(false|null|''|"")/
-const NETWORK_RE = /\bfetch\(|https?\.|axios|got\(/
+// Falsy-return як «fail-safe» — лише коли воно в catch/error-гілці (інакше це
+// звичайний guard `if (!x) return null`, не обробка помилки). Уникає over-claim.
+const FALSY_RETURN_RE = /catch[\s\S]{0,400}?return\s+(false|null|''|"")/
+// Мережа: окрім явного fetch/http, ловимо абстраговані клієнти (graphql/db/rpc/
+// octokit/.request/.query). Хибний false-negative тут = небезпечна гарантія
+// «без мережі», тож свідомо схиляємось до over-detection (м'якший бік помилки).
+const NETWORK_RE = /\bfetch\(|https?:\/\/|\bhttps?\.|axios|\bgot\(|graphql|\.request\(|\.query\(|\.mutate\(|octokit|node-fetch|undici|\bgrpc\b|websocket/i
 // Кеш — лише за ІМЕНОВАНИМ маркером (`cache`/`Cache`/`memoize`), не за будь-яким
 // `new Map()`: акумулятор (напр. `byPath = new Map()`) — не кеш, а хибна гарантія
 // «Кешує результати» гірша за пропуск (фабрикація > мовчання).

package/rules/js-lint-ci/js-lint-ci.mdc

@@ -1,5 +1,5 @@
 ---
-description: Крос-файловий ci-етап js-lint — jscpd (детектор клонів) і knip (невикористані експорти). Лише у lint-ci, по всьому репо.
+description: Крос-файловий ci-етап js-lint — jscpd (детектор клонів) і knip (невикористані експорти). Лише у `lint --full`, по всьому репо.
 globs: "**/{.oxlintrc.json,eslint.config.js,.jscpd.json,knip.json,package.json},**/*.{js,mjs,cjs,jsx,ts,tsx}"
 alwaysApply: false
 version: '1.0'
@@ -8,7 +8,7 @@ version: '1.0'
 # js-lint-ci — крос-файловий ci-етап
 
 `jscpd` і `knip` аналізують увесь граф проєкту, тож мають сенс лише у повному прогоні
-`npx @nitra/cursor lint-ci` (не у швидкому `lint` по змінених файлах). Per-file режиму нема.
+`npx @nitra/cursor lint --full` (CI: `lint --read-only --full`) — не у швидкому `lint` по змінених файлах. Per-file режиму нема.
 
 Швидкий етап js-lint (oxlint/eslint) — у правилі `js-lint` (`lint: per-file`).
 

package/rules/tauri/tauri.mdc

@@ -2,7 +2,7 @@
 description: Tauri
 globs: "**/src-tauri/**,**/tauri.conf.json"
 alwaysApply: false
-version: '1.4'
+version: '1.5'
 ---
 
 У `.vscode/extensions.json` `recommendations` має містити `tauri-apps.tauri-vscode`:
@@ -66,3 +66,25 @@ exclude_globs = [
   - якщо обидва канонічні ключі (`additional_cargo_test_args`, `exclude_globs`) вже присутні — `manual cargo-mutants config preserved`, нічого не зміниться;
   - якщо якийсь канонічний ключ відсутній — додається окремим блоком у кінці файла, без зміни існуючих значень.
 - Послідовний `fix test` → `fix tauri` створює Tauri-config; повторний `fix tauri` не дублює секцій; повторний `fix test` не перетирає Tauri-tuning.
+
+## Tool Surface у Tauri (реалізація ядра `tool-surface`)
+
+Це per-stack реалізація правила **`tool-surface`** (`n-tool-surface`) для Tauri+Rust. Контракт (каталог → `dispatch` → UI/оркестратор/LLM, інваріант паритету, конверт) — у тому правилі; тут — як він лягає на Tauri.
+
+**Реальна робота живе в Rust, JS-каталог — тонкий call surface.** Handler тула не містить логіки сам — він **делегує** в native. Одна реалізація в Rust-крейті backs два споживачі:
+
+- **Бінарник** (`src-tauri` як CLI, або окремий crate-bin) — headless-вхід для оркестратора;
+- **Tauri-команда** (`#[tauri::command]`) — той самий крейт-fn, обгорнутий для UI.
+
+**Два транспорти одного каталогу** (`src/tool/transports`):
+
+- **UI (in-app):** `invoke(tool.tauri, input)` → Tauri-команда → крейт. Ключі `input` мапляться 1:1 на аргументи команди (camelCase, напр. `tasksDir`); поля вкладених struct лишаються snake_case (Tauri конвертить лише імена top-level аргументів).
+- **Оркестратор (headless):** `bin/<app>.mjs` спавнить зібраний бінарник (`<bin> <verb> …` per-verb, або уніфікований `<bin> exec '<json>'`), парсить JSON stdout.
+
+**Конверт:** Tauri-команда повертає `Result<T, String>`; адаптер мапить у `{ ok, output }` / `{ ok:false, error }`. Бінарник друкує конверт у stdout, exit ≠ 0 на `ok:false`.
+
+**Єдине джерело схем:** надавай перевагу `schemars`-derive на Rust-param-структурах → бінарник віддає маніфест (`<bin> schema`); або тримай схему в JS-каталозі й валідуй до `invoke`. **Не дублюй** контракт між Rust і JS — лише деривація + спільні тест-вектори.
+
+**Дозволи:** будь-який плагін, який смикають тули (`tauri-plugin-dialog`, `tauri-plugin-http` для локальної LLM тощо), має бути в `src-tauri/capabilities/*.json` і зареєстрований у `lib.rs` — інакше виклик тихо падає.
+
+**LLM-раннер in-app:** chat-loop ходить до OpenAI-сумісного ендпоінта через `tauri-plugin-http` fetch (бо webview-fetch обмежений CSP/capability), а тули виконує через спільний `dispatch` (той самий, що й UI).

package/rules/tool-surface/fix.mjs

@@ -0,0 +1,18 @@
+import { isRunAsCli, runRuleCli } from '../../scripts/lib/run-rule-cli.mjs'
+import { runStandardRule } from '../../scripts/lib/run-standard-rule.mjs'
+
+/**
+ * Запускає правило: applies → JS-concerns → policy → mdc-refs (через runStandardRule).
+ * Library mode: викликається CLI orchestration через `import + run(ctx)`.
+ * @param {import('../../scripts/lib/run-standard-rule.mjs').RuleContext} [ctx] контекст прогону (walkCache тощо)
+ * @returns {Promise<number>} 0 — OK, 1 — порушення
+ */
+export function run(ctx) {
+  return runStandardRule(import.meta.dirname, ctx)
+}
+
+if (isRunAsCli(import.meta.url)) {
+  // Standalone: bun rules/<id>/fix.mjs — повний еквівалент `npx @nitra/cursor fix <id>`
+  // (config-loading + whitelist + summary). Дві ролі fix.mjs: library (run) + standalone (main).
+  process.exitCode = await runRuleCli(import.meta.dirname)
+}

package/rules/tool-surface/meta.json

@@ -0,0 +1 @@
+{ "auto": { "predicate": "depInAnyPackageJson", "arg": ["vue", "react", "svelte", "@angular/core", "preact", "solid-js", "@tauri-apps/api", "@capacitor/core"] } }

package/rules/tool-surface/tool-surface.mdc

@@ -0,0 +1,72 @@
+---
+description: Tool Surface — будь-яка дія фронтенду має бути виконуваною без UI (CLI + LLM) через спільний каталог тулів; UI/оркестратор/LLM — рівноправні адаптери
+alwaysApply: true
+version: '1.0'
+---
+
+# Tool Surface — паритет «UI ↔ LLM ↔ оркестратор»
+
+## Принцип
+
+**Будь-яка дія, яку людина виконує через фронтенд, мусить бути виконуваною як `tool` — без UI — бо вона організована як іменований виклик зі схемою, до якого однаково дотягуються UI, скриптовий оркестратор і LLM.**
+
+Ключовий новий споживач — **LLM**, тож одиниця називається `tool`. Фронтенд — лише один з адаптерів, а не єдині двері.
+
+## Це НЕ про «винести логіку на бекенд»
+
+Лінія поділу не «фронт ↔ бек», а:
+
+> виклик, досяжний **лише через UI-взаємодію** → погано
+> виклик, досяжний як **іменований tool зі схемою** → добре
+
+JS-логіка може лишатися на фронті — її лише треба **витягнути** з обробника події в окремий tool (ім'я + параметри + схема), який однаково кличе UI, оркестратор і LLM. Tool Surface — це **call surface**, не обов'язково бекенд.
+
+## Три шари
+
+1. **Tool Catalog** (`src/tool/`) — декларативний каталог. Кожен tool: `name`, `summary`, схема входу/виходу, `handler`. Handler **може бути фронтендовою JS-функцією** (або делегувати в native/HTTP/DB). Це **єдине джерело правди**; з нього генеруються schema-маніфест (для LLM) і типи клієнта.
+2. **Dispatch** — одна функція `dispatch(name, input) → { ok, output } | { ok: false, error }`: валідує вхід за схемою, кличе handler, повертає **уніфікований конверт**. Не прив'язана до UI-рендеру/подій.
+3. **Споживачі** (усі обов'язкові):
+   - **UI** — компонент кличе `dispatch`, без inline-логіки дії.
+   - **Оркестратор** — машинний вхід `<bin> <tool> '<json>'` (+ `schema`/`list`). Кличуть скрипти, не люди — людський CLI з verb-ами не потрібен.
+   - **LLM** — tool-маніфест із каталогу; tool_call маршрутизується в `dispatch`.
+
+## Інваріант паритету (серце правила)
+
+- **Жодної дії, досяжної лише через UI-взаємодію.** Обробник події **делегує** в `dispatch`/каталог, а не містить inline-логіку (мережа, мутація моделі, виклик бекенду).
+- Дозволено: логіка у фронтенд-коді. Заборонено: логіка **зашита** в обробник кліку/сабміту так, що дотягтись можна лише кліком.
+- Кожен tool каталогу має **усіх** споживачів (UI + оркестратор + LLM), інакше це не headless.
+
+## Єдине джерело схем
+
+Схема входу tool-а живе в каталозі (zod / JSON Schema; для Rust — `schemars`). З неї генеруються: tool-маніфест для LLM (формат залежить від провайдера — OpenAI function-calling, Anthropic tools або MCP), CLI-довідка, типи клієнта. Тул-визначення **не повинні розходитися** з каталогом — лише деривація, не дублювання.
+
+## Уніфікований конверт
+
+```jsonc
+{ "ok": true,  "output": { /* результат */ } }
+{ "ok": false, "error": { "code": "validation|not_found|io|…", "message": "…" } }
+```
+
+Оркестратор: `ok:false` → ненульовий exit. UI/LLM: `Result` / tool_result з `is_error`.
+
+## Дворівнева структура (архітектура спільна, реалізація per-stack)
+
+Архітектура **спільна**, реалізація **навмисно розходиться** за стеком. Це правило тримає платформо-незалежне **ядро**; конкретику делегують профільні правила:
+
+| Рівень | Що тут | Де |
+|---|---|---|
+| **Ядро** | принцип, інваріант паритету, контракт каталог/`dispatch`/схема/конверт, 3 споживачі | це правило |
+| **Tauri+Rust** | handler делегує в Rust-крейт/бінарник; машинний bin; `invoke`/spawn | `n-tauri` |
+| **Capacitor / pure-web** | handler — JS напряму; bin = node/bun-скрипт, що імпортує handlers | `n-capacitor` |
+| **UI-адаптер** | компонент делегує в `dispatch`, нуль inline-логіки | `n-vue` |
+
+## Конвенція файлів
+
+```
+src/tool/
+  catalog.(js|ts)     ← каталог тулів (single source): name, summary, input schema, mapping
+  dispatch.(js|ts)    ← dispatch(name, input) + валідація + конверт
+  manifest.(js|ts)    ← каталог → LLM tools ; CLI help
+  transports.(js|ts)  ← UI-транспорт (invoke/fetch) ; CLI-транспорт (spawn/import)
+bin/<app>.mjs         ← машинний вхід: <tool> '<json>' | schema | list
+```

package/schemas/rule-meta.json

@@ -8,8 +8,8 @@
   "properties": {
     "lint": {
       "type": "string",
-      "enum": ["quick", "ci"],
-      "description": "Фаза lint-кроку: quick (по змінених, у lint і lint-ci) або ci (лише lint-ci)."
+      "enum": ["per-file", "full"],
+      "description": "Scope lint-кроку: per-file (декомпозиція по змінених файлах, дельта vs origin) або full (нероздільно крос-файловий, лише `lint --full`)."
     },
     "auto": {
       "description": "Умова автоактивації правила: \"завжди\", масив id правил-залежностей, glob, або іменований предикат.",