@nitra/cursor 11.2.0 → 11.4.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## [11.4.0] - 2026-06-15
+
+### Changed
+
+- Додано логіку відсіювання неактуальних правил/скілів за `availableRules`/`availableSkills
+
+## [11.3.0] - 2026-06-15
+
+### Changed
+
+- lint: opt-in `meta.json: llmFix:true` тепер реально дротується (раніше прапор був декоративний — opportunistic LLM-fix біг просто на `!readOnly`). `runLint` читає `llmFix` з meta правила й передає в `lint(files, cwd, { readOnly, llmFix })`; правило без прапора лишається detect-only. Це й забезпечує safety-тріаж зі спеки (логічні лінтери не вмикають LLM-fix випадково). doc-files і text позначені `llmFix:true`; cspell-класифікація гейтиться через `llmFix` (проведено `runLintTextCli`/`runLintTextSteps`/`runCspellText`), standalone `lint-text` передає `llmFix:true`. Принагідно: justified `no-unsanitized/method`-disable на package-internal динамічний import у `runLint` (pre-existing).
+
 ## [11.2.0] - 2026-06-15
 
 ### Changed

package/bin/docs/n-cursor.md

@@ -173,7 +173,7 @@
 #### Вкладена normalizeConfigWithAutoRules(parsedConfig)
 
 - **Сигнатура:** `async function normalizeConfigWithAutoRules(parsedConfig: Record<string, unknown>): Promise<Record<string, unknown>>`
-- **Призначення:** перевіряє типи полів, обчислює `auto-detected rules` (`detectAutoRules`), будує ефективний список правил (поточні + auto, мінус `disable-rules`), за яким `detectAutoSkills` визначає скіли. Далі `mergeConfigWithAutoDetected` зливає дані, після чого `$schema` вирівнюється до `CONFIG_SCHEMA_URL`, додаються `disable-rules`/`disable-skills` (якщо непорожні), результат проходить через `sortConfigIdArrays`.
+- **Призначення:** перевіряє типи полів, обчислює `auto-detected rules` (`detectAutoRules`), будує ефективний список правил (поточні + auto, мінус `disable-rules`), за яким `detectAutoSkills` визначає скіли. Далі `mergeConfigWithAutoDetected` зливає дані (передаючи `availableRules`/`availableSkills` із каталогів пакета, щоб відсіяти з `rules`/`skills` неактуальні id, яких уже немає у пакеті — прибрані логуються через `🧹`), після чого `$schema` вирівнюється до `CONFIG_SCHEMA_URL`, додаються `disable-rules`/`disable-skills` (якщо непорожні), результат проходить через `sortConfigIdArrays`.
 
 ### logRuleMigrationsIfAny(parsedConfig)
 

package/bin/n-cursor.js

@@ -25,7 +25,7 @@
  *   `npx \@nitra/cursor lint-text`   — канонічний lint-text (text.mdc): `cspell` → `shellcheck` (з auto-fix) →
  *                                     `markdownlint-cli2 --fix` → `v8r` (json/json5/yaml/yml/toml)
  *   `npx \@nitra/cursor lint-doc-files`  — детермінований детектор застарілості файлових док (`stale`: `missing`|`crc-mismatch`); правило doc-files (ignore-glob у `npm/rules/doc-files/js/docgen-ignore.mjs`; тека `docs/` поряд із джерелом). Режими: повний (exit 1), `--json` (exit 0), `--missing-only`, `--hook`/`--git` (hook-протокол, exit 2), `--degraded`
- *   `npx \@nitra/cursor fix-doc-files`   — JS-оркестрована генерація файлових док (роутинг local/cloud) зі штампом CRC (`--limit`/`--from`/`--overwrite`/`--retry-degraded`); `--stamp` — детерміноване перештампування CRC без LLM
+ *   `npx \@nitra/cursor fix-doc-files`   — JS-оркестрована генерація файлових док (роутинг local/cloud) зі штампом CRC (`--limit`/`--from`/`--overwrite`); `--stamp` — детерміноване перештампування CRC без LLM
  *   `npx \@nitra/cursor doc-aggregate modules` — JSON-лістинг логічних модулів (межі за `package.json`) для Tier 2 скілу doc-aggregate
  *   `npx \@nitra/cursor skill list`     — скіли пакета без синку в проєкт
  *   `npx \@nitra/cursor skill taze`     — промпт на stdout
@@ -315,9 +315,18 @@ async function readConfig(paths = {}) {
     const merged = mergeConfigWithAutoDetected({
       config: parsedConfig,
       detectedRules: autoDetectedRules.rules,
-      detectedSkills: autoDetectedSkills.skills
+      detectedSkills: autoDetectedSkills.skills,
+      availableRules,
+      availableSkills
     })
 
+    if (merged.pruned) {
+      const parts = []
+      if (merged.pruned.rules.length > 0) parts.push(`rules: ${merged.pruned.rules.join(', ')}`)
+      if (merged.pruned.skills.length > 0) parts.push(`skills: ${merged.pruned.skills.join(', ')}`)
+      console.log(`🧹 Прибрано з ${CONFIG_FILE} неактуальні (немає у пакеті) — ${parts.join('; ')}\n`)
+    }
+
     const rest = Object.fromEntries(Object.entries(parsedConfig).filter(([k]) => k !== '$schema'))
     const normalized = {
       $schema: CONFIG_SCHEMA_URL,
@@ -1568,7 +1577,8 @@ try {
     case 'lint-text': {
       // Канонічний lint-text: cspell → shellcheck → dotenv → markdownlint → v8r (text.mdc).
       // `--read-only` (CI): без авто-фіксу (markdownlint/shellcheck/dotenv) — нуль мутацій.
-      process.exitCode = await runLintTextCli({ readOnly: args.includes('--read-only') })
+      // `llmFix:true` — text llmFix-capable, тож standalone lint-text робить omlx-класифікацію cspell.
+      process.exitCode = await runLintTextCli({ readOnly: args.includes('--read-only'), llmFix: true })
 
       break
     }
@@ -1649,7 +1659,7 @@ try {
     }
     case 'fix-doc-files': {
       // n-cursor fix-doc-files — local-only генерація файлових док (omlx) + CRC-штамп
-      // (--limit/--from/--overwrite/--retry-degraded); --stamp — детерміноване
+      // (--limit/--from/--overwrite); --stamp — детерміноване
       // перештампування source+crc без LLM. У CI не запускається (потрібна локальна модель).
       if (args.includes('--stamp')) {
         const { runDocFilesStampCli } = await import('../rules/doc-files/js/docgen-files-batch.mjs')

package/package.json

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

package/rules/doc-files/js/lint.mjs

@@ -98,13 +98,14 @@ function collectStale(files, cwd) {
  * Крок агрегатора lint для doc-files (opportunistic LLM-fix tier).
  * @param {string[] | undefined} files quick: лише ці файли; undefined: весь репозиторій
  * @param {string} [cwd] корінь репо
- * @param {{ readOnly?: boolean }} [opts] readOnly: лише детект (CI/hook), без мутацій/LLM
+ * @param {{ readOnly?: boolean, llmFix?: boolean }} [opts] readOnly: лише детект (CI/hook);
+ *   llmFix: opt-in opportunistic-генерація (з `meta.json: llmFix:true`) — без нього detect-only
  * @returns {Promise<number>} 0 — доки свіжі; 1 — є застарілі (детект, fix пропущено чи помилка генерації)
  */
-export async function lint(files, cwd = process.cwd(), { readOnly = false } = {}) {
+export async function lint(files, cwd = process.cwd(), { readOnly = false, llmFix = false } = {}) {
   const stale = collectStale(files, cwd)
   if (stale.length === 0) return 0
-  if (readOnly) return reportStale(stale)
+  if (readOnly || !llmFix) return reportStale(stale)
 
   // fix-by-default: opportunistic-генерація через спільне ядро (preflight omlx →
   // батч із circuit-breaker'ом). omlx недоступний → runGenerationBatch друкує причину

package/rules/lint/js/orchestrate.mjs

@@ -108,15 +108,23 @@ export async function runLint(opts = {}) {
     return 0
   }
 
-  const ids = selectLintRules(readAllMeta(rulesDir), full)
+  const metaById = readAllMeta(rulesDir)
+  const ids = selectLintRules(metaById, full)
   for (const id of ids) {
     const lintPath = join(rulesDir, id, 'js', 'lint.mjs')
     if (!existsSync(lintPath)) {
       log(`⚠️  lint: правило ${id} має lint-фазу, але немає js/lint.mjs — пропускаю.\n`)
       continue
     }
+    // lintPath = join(rulesDir, id, …) — суто package-internal (rulesDir пакета + id зі
+    // selectLintRules за власним meta), не зовнішній вхід → ін'єкції немає.
+    // eslint-disable-next-line no-unsanitized/method
     const mod = await import(lintPath)
-    const code = await mod.lint(changed, cwd, { readOnly })
+    // `llmFix` (opt-in opportunistic LLM-fix, спека 2026-06-15): лише правила з
+    // `meta.json: llmFix:true` отримують fix-сходинку; решта — detect-only. Це й
+    // забезпечує safety-тріаж (логічні лінтери не вмикають LLM-fix випадково).
+    const llmFix = metaById[id]?.llmFix === true
+    const code = await mod.lint(changed, cwd, { readOnly, llmFix })
     if (code !== 0) return code
   }
 

package/rules/text/js/lint.mjs

@@ -6,9 +6,10 @@ import { runLintTextCli } from '../lint/lint.mjs'
 /**
  * @param {string[] | undefined} _files ігнорується (whole-repo аналіз)
  * @param {string} [_cwd] корінь (ігнорується — CLI працює від process.cwd())
- * @param {{ readOnly?: boolean }} [opts] readOnly → детект без авто-фіксу (нуль мутацій)
+ * @param {{ readOnly?: boolean, llmFix?: boolean }} [opts] readOnly → детект без авто-фіксу (нуль мутацій);
+ *   llmFix → opt-in omlx-класифікація cspell (з `meta.json: llmFix:true`)
  * @returns {Promise<number>} exit code
  */
 export function lint(_files, _cwd, opts = {}) {
-  return runLintTextCli({ readOnly: opts.readOnly === true })
+  return runLintTextCli({ readOnly: opts.readOnly === true, llmFix: opts.llmFix === true })
 }

package/rules/text/lint/cspell-fix.mjs

@@ -113,9 +113,10 @@ export function appendWordsToDict(cwd, words) {
  * cspell-крок lint-text: класифікація → словник (нова схема).
  * @param {string} [cwd] корінь
  * @param {boolean} [readOnly] true → лише детект (нуль мутацій)
+ * @param {boolean} [llmFix] opt-in omlx-класифікація (з `meta.json: llmFix:true`); без нього — лише детект
  * @returns {number} 0 — чисто; 1 — лишились знахідки / помилка середовища
  */
-export function runCspellText(cwd = process.cwd(), readOnly = false) {
+export function runCspellText(cwd = process.cwd(), readOnly = false, llmFix = false) {
   const bin = resolveCmd('npx')
   if (!bin) {
     process.stderr.write('❌ npx не знайдено в PATH (cspell).\n')
@@ -124,7 +125,7 @@ export function runCspellText(cwd = process.cwd(), readOnly = false) {
 
   const first = detectCspell(cwd, bin)
   if (first.code === 0) return 0
-  if (readOnly) {
+  if (readOnly || !llmFix) {
     process.stdout.write(first.out)
     return first.code
   }

package/rules/text/lint/lint.mjs

@@ -97,9 +97,10 @@ function preflight(dep) {
 /**
  * Внутрішні кроки `lint-text` без локу.
  * @param {boolean} [readOnly] true → лише детект без авто-фіксу (нуль мутацій — CI/pre-commit)
+ * @param {boolean} [llmFix] opt-in omlx-класифікація cspell (інші кроки фіксяться детерміновано за readOnly)
  * @returns {number} 0 — все OK, інакше — код першого кроку, що впав
  */
-function runLintTextSteps(readOnly = false) {
+function runLintTextSteps(readOnly = false, llmFix = false) {
   // Auto-install: throws on failure → propagates as exit 1 from runStandardLint
   ensureTool('shellcheck')
   ensureTool('dotenv-linter')
@@ -107,8 +108,8 @@ function runLintTextSteps(readOnly = false) {
   // patch потрібен лише для авто-фіксу shellcheck; у read-only пропускаємо preflight.
   if (!readOnly && !preflight(PATCH_PREFLIGHT)) return 1
 
-  console.log(`\n▶ cspell (${readOnly ? 'перевірка' : 'omlx-автофікс одруків + перевірка'})`)
-  const cspellCode = runCspellText(process.cwd(), readOnly)
+  console.log(`\n▶ cspell (${!readOnly && llmFix ? 'omlx-класифікація + словник + перевірка' : 'перевірка'})`)
+  const cspellCode = runCspellText(process.cwd(), readOnly, llmFix)
   if (cspellCode !== 0) return cspellCode
 
   console.log(`\n▶ shellcheck (${readOnly ? 'перевірка' : 'авто-фікс + фінальна перевірка'} *.sh)`)
@@ -129,8 +130,9 @@ function runLintTextSteps(readOnly = false) {
 
 /**
  * Публічна CLI-форма: серіалізує через `withLock('lint-text')` + дедуп за станом git-дерева.
- * @param {{ readOnly?: boolean }} [opts] readOnly → детект без авто-фіксу
+ * @param {{ readOnly?: boolean, llmFix?: boolean }} [opts] readOnly → детект без авто-фіксу;
+ *   llmFix → omlx-класифікація cspell (opt-in із `meta.json: llmFix:true`)
  * @returns {Promise<number>} код виходу
  */
 export const runLintTextCli = (opts = {}) =>
-  runStandardLint(import.meta.dirname, () => runLintTextSteps(opts.readOnly === true))
+  runStandardLint(import.meta.dirname, () => runLintTextSteps(opts.readOnly === true, opts.llmFix === true))

package/rules/text/meta.json

@@ -1 +1 @@
-{ "auto": "завжди", "lint": "per-file" }
+{ "auto": "завжди", "lint": "per-file", "llmFix": true }

package/scripts/auto-rules.mjs

@@ -392,14 +392,45 @@ export async function detectAutoRules({
 }
 
 /**
- * Доповнює конфіг автодетектом (лише додає; існуючі вручну задані елементи не прибирає).
+ * Розділяє список id на доступні в пакеті й застарілі (відсутні).
+ * Без `available` нічого не прибирає — усе вважається доступним.
+ * @param {string[]} ids перелік id (rules або skills)
+ * @param {string[] | undefined} available id, що реально є у каталозі пакета
+ * @returns {{ kept: string[], pruned: string[] }} відфільтровані й прибрані id
+ */
+function partitionByAvailability(ids, available) {
+  if (!available) return { kept: ids, pruned: [] }
+  const availableSet = new Set(available)
+  const kept = []
+  const pruned = []
+  for (const id of ids) {
+    if (availableSet.has(id)) kept.push(id)
+    else pruned.push(id)
+  }
+  return { kept, pruned }
+}
+
+/**
+ * Доповнює конфіг автодетектом (лише додає; існуючі вручну задані елементи не прибирає),
+ * а за наявності `availableRules`/`availableSkills` ще й прибирає з `rules`/`skills`
+ * неактуальні id, яких уже немає у пакеті (наприклад, правило чи скіл видалено з нової
+ * версії \@nitra/cursor) — інакше sync щоразу падав би на завантаженні відсутнього
+ * `rules/<id>.mdc` чи `skills/<id>/`. Прибрані id повертаються у полі `pruned` (для логу).
  * @param {object} params параметри оновлення
  * @param {{ rules: unknown, skills?: unknown, ['disable-rules']?: unknown, ['disable-skills']?: unknown }} params.config розпарсений `.n-cursor.json`
  * @param {string[]} params.detectedRules правила, визначені автодетектом
  * @param {string[]} params.detectedSkills skills, визначені автодетектом
- * @returns {{ rules: string[], skills: string[] } & Record<string, unknown>} новий нормалізований конфіг
+ * @param {string[]} [params.availableRules] id правил, наявних у каталозі `rules/` пакета (для відсіву неактуальних)
+ * @param {string[]} [params.availableSkills] id skills, наявних у каталозі `skills/` пакета (для відсіву неактуальних)
+ * @returns {{ rules: string[], skills: string[], pruned?: { rules: string[], skills: string[] } } & Record<string, unknown>} новий нормалізований конфіг
  */
-export function mergeConfigWithAutoDetected({ config, detectedRules, detectedSkills }) {
+export function mergeConfigWithAutoDetected({
+  config,
+  detectedRules,
+  detectedSkills,
+  availableRules,
+  availableSkills
+}) {
   const existingRules = migrateRuleIds(normalizeIdList(config.rules))
   const existingSkills = normalizeIdList(config.skills)
   const disableRules = migrateRuleIds(normalizeIdList(config['disable-rules']))
@@ -419,13 +450,19 @@ export function mergeConfigWithAutoDetected({ config, detectedRules, detectedSki
     }
   }
 
-  /** @type {{ rules: string[], skills: string[] } & Record<string, unknown>} */
-  const normalized = { rules, skills }
+  const { kept: keptRules, pruned: prunedRules } = partitionByAvailability(rules, availableRules)
+  const { kept: keptSkills, pruned: prunedSkills } = partitionByAvailability(skills, availableSkills)
+
+  /** @type {{ rules: string[], skills: string[], pruned?: { rules: string[], skills: string[] } } & Record<string, unknown>} */
+  const normalized = { rules: keptRules, skills: keptSkills }
   if (disableRules.length > 0) {
     normalized['disable-rules'] = disableRules
   }
   if (disableSkills.length > 0) {
     normalized['disable-skills'] = disableSkills
   }
+  if (prunedRules.length > 0 || prunedSkills.length > 0) {
+    normalized.pruned = { rules: prunedRules, skills: prunedSkills }
+  }
   return normalized
 }

package/scripts/docs/auto-rules.md

@@ -1,7 +1,7 @@
 ---
 docgen:
   source: npm/scripts/auto-rules.mjs
-  crc: 972b56fc
+  crc: d50b922f
   score: 90
 ---
 
@@ -29,7 +29,7 @@ detectAutoRules
 Визначає активні правила на основі spec, перевіряючи їх проти згенерованих фактів.
 
 mergeConfigWithAutoDetected
-Доповнює конфігурацію, додаючи визначені автоправила та налаштування, з урахуванням legacy-ID.
+Доповнює конфігурацію, додаючи визначені автоправила та налаштування, з урахуванням legacy-ID; за наявності `availableRules`/`availableSkills` ще й відсіює з `rules`/`skills` неактуальні id, яких немає у пакеті (повертає їх у полі `pruned`).
 
 ## Публічний API