@nitra/cursor 1.8.81 → 1.8.83

package/bin/n-cursor.js

@@ -32,6 +32,10 @@
  *
  * Якщо в корені є package.json і в ньому ще немає \@nitra/cursor у devDependencies (і не оголошено
  * в dependencies), CLI дописує devDependencies з діапазоном ^<version> поточного пакету — зручно після npx.
+ *
+ * Перед копіюванням правил (режим без підкоманди): оновлення \@nitra/cursor у package.json до
+ * останньої версії з npm (крім workspace:/file:/link: тощо), `bun i`, далі файли беруться з
+ * `node_modules/@nitra/cursor`, якщо пакет з’явився після встановлення.
  */
 
 import { existsSync } from 'node:fs'
@@ -40,10 +44,8 @@ import { basename, dirname, join } from 'node:path'
 import { cwd } from 'node:process'
 import { fileURLToPath } from 'node:url'
 
-import {
-  ensureNitraCursorInRootDevDependencies,
-  readBundledPackageVersion
-} from '../scripts/ensure-nitra-cursor-dev-dependencies.mjs'
+import { ensureNitraCursorInRootDevDependencies } from '../scripts/ensure-nitra-cursor-dev-dependencies.mjs'
+import { upgradeNitraCursorToLatestAndBunInstall } from '../scripts/upgrade-nitra-cursor-and-install.mjs'
 import { runRenameYamlExtensionsCli } from './rename-yaml-extensions.mjs'
 import { syncSetupBunDepsAction } from '../scripts/sync-setup-bun-deps-action.mjs'
 
@@ -68,17 +70,18 @@ const BUNDLED_PACKAGE_ROOT = join(binDir, '..')
 
 /**
  * Імена правил (без .mdc) з каталогу mdc поточної інсталяції пакету
+ * @param {string} [bundledMdcDir] каталог `mdc/` у корені пакету (за замовчуванням — з поточного процесу)
  * @returns {Promise<string[]>} відсортовані імена файлів правил без суфікса .mdc
  */
-async function discoverBundledRuleNames() {
-  if (!existsSync(BUNDLED_MDC_DIR)) {
+async function discoverBundledRuleNames(bundledMdcDir = BUNDLED_MDC_DIR) {
+  if (!existsSync(bundledMdcDir)) {
     throw new Error(
       `Не знайдено каталог правил пакету.\n` +
-        `Очікуваний шлях: ${BUNDLED_MDC_DIR}\n` +
+        `Очікуваний шлях: ${bundledMdcDir}\n` +
         `Перевстановіть ${PACKAGE_NAME} або створіть ${CONFIG_FILE} вручну.`
     )
   }
-  const names = await readdir(BUNDLED_MDC_DIR)
+  const names = await readdir(bundledMdcDir)
   const rules = names
     .filter(n => n.endsWith('.mdc'))
     .map(n => n.slice(0, -'.mdc'.length))
@@ -91,13 +94,14 @@ async function discoverBundledRuleNames() {
 
 /**
  * Імена skills (id без префікса n-) з каталогу skills пакету — лише підкаталоги `<id>/` без префікса n-
+ * @param {string} [bundledSkillsDir] каталог `skills/` у корені пакету
  * @returns {Promise<string[]>} відсортовані id
  */
-async function discoverBundledSkillNames() {
-  if (!existsSync(BUNDLED_SKILLS_DIR)) {
+async function discoverBundledSkillNames(bundledSkillsDir = BUNDLED_SKILLS_DIR) {
+  if (!existsSync(bundledSkillsDir)) {
     return []
   }
-  const entries = await readdir(BUNDLED_SKILLS_DIR, { withFileTypes: true })
+  const entries = await readdir(bundledSkillsDir, { withFileTypes: true })
   return entries
     .filter(e => e.isDirectory() && !e.name.startsWith('.') && !e.name.startsWith(RULE_PREFIX))
     .map(e => e.name)
@@ -152,14 +156,17 @@ async function migrateLegacyConfigIfNeeded() {
 
 /**
  * Зчитує конфіг .n-cursor.json з поточної директорії
+ * @param {{ bundledMdcDir?: string, bundledSkillsDir?: string }} [paths] каталоги з пакету-джерела (після `bun i` — зазвичай `node_modules/@nitra/cursor`)
  * @returns {Promise<{ $schema: string, rules: string[], skills: string[], version?: string } & Record<string, unknown>>} rules, skills (id без префікса n-); поле version у файлі за наявності ігнорується при синхронізації правил
  */
-async function readConfig() {
+async function readConfig(paths = {}) {
+  const bundledMdcDir = paths.bundledMdcDir ?? BUNDLED_MDC_DIR
+  const bundledSkillsDir = paths.bundledSkillsDir ?? BUNDLED_SKILLS_DIR
   await migrateLegacyConfigIfNeeded()
   const configPath = join(cwd(), CONFIG_FILE)
   if (!existsSync(configPath)) {
-    const rules = await discoverBundledRuleNames()
-    const skills = await discoverBundledSkillNames()
+    const rules = await discoverBundledRuleNames(bundledMdcDir)
+    const skills = await discoverBundledSkillNames(bundledSkillsDir)
     const defaultConfig = { $schema: CONFIG_SCHEMA_URL, rules, skills }
     await writeFile(configPath, `${JSON.stringify(defaultConfig, null, 2)}\n`, 'utf8')
     console.log(
@@ -181,7 +188,7 @@ async function readConfig() {
     if ('skills' in config) {
       throw new Error(`У ${CONFIG_FILE} поле "skills" має бути масивом рядків`)
     }
-    config.skills = await discoverBundledSkillNames()
+    config.skills = await discoverBundledSkillNames(bundledSkillsDir)
   }
 
   if (config.$schema !== CONFIG_SCHEMA_URL) {
@@ -210,14 +217,15 @@ function normalizeRuleName(ruleName) {
 /**
  * Читає вміст правила з каталогу `mdc/` установленого пакету (наприклад `node_modules/@nitra/cursor/mdc` або кеш npx).
  * @param {string} rule елемент масиву rules з `.n-cursor.json`
+ * @param {string} [bundledMdcDir] каталог `mdc/` у корені пакету-джерела
  * @returns {Promise<string>} текст правила для запису в `.cursor/rules/n-*.mdc`
  */
-function readBundledRuleContent(rule) {
+function readBundledRuleContent(rule, bundledMdcDir = BUNDLED_MDC_DIR) {
   const bundledName = normalizeRuleName(rule)
-  const bundledPath = join(BUNDLED_MDC_DIR, bundledName)
+  const bundledPath = join(bundledMdcDir, bundledName)
   if (!existsSync(bundledPath)) {
     throw new Error(
-      `Немає файлу ${bundledName} у ${BUNDLED_MDC_DIR}. Оновіть ${PACKAGE_NAME} або приберіть "${rule}" з rules у ${CONFIG_FILE}.`
+      `Немає файлу ${bundledName} у ${bundledMdcDir}. Оновіть ${PACKAGE_NAME} або приберіть "${rule}" з rules у ${CONFIG_FILE}.`
     )
   }
   return readFile(bundledPath, 'utf8')
@@ -457,17 +465,18 @@ async function syncClaudeMd(configRules, configSkills) {
 /**
  * Повністю перезаписує AGENTS.md у корені cwd з npm/AGENTS.template.md
  * @param {string[]} configSkills id skills з конфігу
+ * @param {string} [agentsTemplatePath] шлях до AGENTS.template.md у корені пакету-джерела
  * @returns {Promise<void>} завершення запису файлу
  */
-async function syncAgentsMd(configSkills) {
-  if (!existsSync(BUNDLED_AGENTS_TEMPLATE_PATH)) {
+async function syncAgentsMd(configSkills, agentsTemplatePath = BUNDLED_AGENTS_TEMPLATE_PATH) {
+  if (!existsSync(agentsTemplatePath)) {
     throw new Error(
       `Не знайдено шаблон ${AGENTS_TEMPLATE_FILE} у пакеті.\n` +
-        `Очікуваний шлях: ${BUNDLED_AGENTS_TEMPLATE_PATH}\n` +
+        `Очікуваний шлях: ${agentsTemplatePath}\n` +
         `Перевстановіть ${PACKAGE_NAME}.`
     )
   }
-  const templateText = await readFile(BUNDLED_AGENTS_TEMPLATE_PATH, 'utf8')
+  const templateText = await readFile(agentsTemplatePath, 'utf8')
   const mdcFiles = await listProjectRulesMdcFiles()
   const skillItems = await buildSkillBulletItems(configSkills)
   const body = renderAgentsTemplate(templateText, mdcFiles, skillItems)
@@ -485,10 +494,11 @@ async function syncAgentsMd(configSkills) {
 /**
  * Копіює лише skills зі списку configSkills (джерело: skills/<id>/ у пакеті)
  * @param {string[]} configSkills id без префікса n-
+ * @param {string} [bundledSkillsDir] каталог `skills/` у корені пакету-джерела
  * @returns {Promise<{ success: number, fail: number }>} лічильники успішних і невдалих копіювань
  */
-async function syncSkills(configSkills) {
-  if (configSkills.length === 0 || !existsSync(BUNDLED_SKILLS_DIR)) {
+async function syncSkills(configSkills, bundledSkillsDir = BUNDLED_SKILLS_DIR) {
+  if (configSkills.length === 0 || !existsSync(bundledSkillsDir)) {
     return { success: 0, fail: 0 }
   }
 
@@ -500,7 +510,7 @@ async function syncSkills(configSkills) {
 
   for (const skillId of configSkills) {
     const id = normalizeSkillId(skillId)
-    const srcDir = join(BUNDLED_SKILLS_DIR, id)
+    const srcDir = join(bundledSkillsDir, id)
     const destDirName = managedSkillDirName(skillId)
     const destDir = join(skillsRoot, destDirName)
 
@@ -534,10 +544,11 @@ async function syncSkills(configSkills) {
  * Синхронізує .claude/commands/n-<id>.md зі skills пакету.
  * Кожен файл містить посилання на відповідний cursor skill, а не копію інструкцій.
  * @param {string[]} configSkills id без префікса n-
+ * @param {string} [bundledSkillsDir] каталог `skills/` у корені пакету-джерела
  * @returns {Promise<{ success: number, fail: number }>} лічильники успішних і невдалих записів
  */
-async function syncCommands(configSkills) {
-  if (configSkills.length === 0 || !existsSync(BUNDLED_SKILLS_DIR)) {
+async function syncCommands(configSkills, bundledSkillsDir = BUNDLED_SKILLS_DIR) {
+  if (configSkills.length === 0 || !existsSync(bundledSkillsDir)) {
     return { success: 0, fail: 0 }
   }
 
@@ -549,7 +560,7 @@ async function syncCommands(configSkills) {
 
   for (const skillId of configSkills) {
     const id = normalizeSkillId(skillId)
-    const srcSkillMd = join(BUNDLED_SKILLS_DIR, id, 'SKILL.md')
+    const srcSkillMd = join(bundledSkillsDir, id, 'SKILL.md')
     const destDirName = managedSkillDirName(skillId)
     const destFile = join(commandsDir, `${RULE_PREFIX}${id}.md`)
 
@@ -730,6 +741,24 @@ async function runChecks(requestedRules) {
   }
 }
 
+/**
+ * Читає поле `version` з `package.json` пакету за абсолютним шляхом до його кореня.
+ * @param {string} packageRoot корінь пакету (тека з `package.json`)
+ * @returns {Promise<string | null>} semver рядком або null, якщо файлу/поля немає або JSON некоректний
+ */
+async function readBundledVersionAt(packageRoot) {
+  const p = join(packageRoot, 'package.json')
+  if (!existsSync(p)) {
+    return null
+  }
+  try {
+    const pkg = JSON.parse(await readFile(p, 'utf8'))
+    return typeof pkg.version === 'string' ? pkg.version : null
+  } catch {
+    return null
+  }
+}
+
 /**
  * Копіює правила з каталогу `mdc/` установленого пакету та синхронізує `.cursor/rules`
  * @returns {Promise<void>}
@@ -737,18 +766,36 @@ async function runChecks(requestedRules) {
 async function runSync() {
   console.log(`\n🔧 ${PACKAGE_NAME} — завантаження cursor-правил\n`)
 
+  const projectRoot = cwd()
+  let effectivePackageRoot
+  try {
+    effectivePackageRoot = await upgradeNitraCursorToLatestAndBunInstall(projectRoot, BUNDLED_PACKAGE_ROOT)
+  } catch (error) {
+    const msg = error instanceof Error ? error.message : String(error)
+    console.error(`❌ Не вдалося оновити ${PACKAGE_NAME} або виконати bun i: ${msg}`)
+    throw error
+  }
+
+  const bundledMdcDir = join(effectivePackageRoot, 'mdc')
+  const bundledSkillsDir = join(effectivePackageRoot, 'skills')
+  const bundledAgentsTemplatePath = join(effectivePackageRoot, AGENTS_TEMPLATE_FILE)
+
   let config
   try {
-    config = await readConfig()
+    config = await readConfig({ bundledMdcDir, bundledSkillsDir })
   } catch (error) {
     console.error(`❌ ${error.message}`)
     throw error
   }
 
   const { rules, skills, version } = config
-  const bundledVer = await readBundledPackageVersion()
+  const bundledVer = await readBundledVersionAt(effectivePackageRoot)
   if (bundledVer) {
-    console.log(`📦 Джерело правил: ${PACKAGE_NAME}@${bundledVer}`)
+    const line =
+      effectivePackageRoot === BUNDLED_PACKAGE_ROOT
+        ? `📦 Джерело правил: ${PACKAGE_NAME}@${bundledVer}`
+        : `📦 Джерело правил: ${PACKAGE_NAME}@${bundledVer} (шлях: ${effectivePackageRoot})`
+    console.log(`${line}\n`)
   }
   if (version) {
     console.log(`⚠️  Поле "version" у ${CONFIG_FILE} ігнорується; правила беруться з установленого пакету.\n`)
@@ -757,7 +804,7 @@ async function runSync() {
   console.log(`📋 Skills до синхронізації: ${skills.length}`)
 
   try {
-    const { destPath } = await syncSetupBunDepsAction(cwd(), BUNDLED_PACKAGE_ROOT)
+    const { destPath } = await syncSetupBunDepsAction(cwd(), effectivePackageRoot)
     console.log(`📝 Оновлено ${destPath} (composite setup-bun-deps з пакету)\n`)
   } catch (error) {
     console.error(`❌ Не вдалося записати setup-bun-deps action: ${error.message}`)
@@ -776,7 +823,7 @@ async function runSync() {
 
     try {
       process.stdout.write(`  ⬇  ${rule} → ${RULES_DIR}/${fileName} ... `)
-      const content = await readBundledRuleContent(rule)
+      const content = await readBundledRuleContent(rule, bundledMdcDir)
       await writeFile(destPath, content, 'utf8')
       console.log(`✅`)
       successCount++
@@ -801,7 +848,7 @@ async function runSync() {
   }
 
   try {
-    const { success: skillOk, fail: skillFail } = await syncSkills(skills)
+    const { success: skillOk, fail: skillFail } = await syncSkills(skills, bundledSkillsDir)
     if (skills.length > 0) {
       console.log(`\n🧩 Skills: ${skillOk} скопійовано, ${skillFail} з помилками`)
     }
@@ -821,7 +868,7 @@ async function runSync() {
   }
 
   try {
-    const { success: cmdOk, fail: cmdFail } = await syncCommands(skills)
+    const { success: cmdOk, fail: cmdFail } = await syncCommands(skills, bundledSkillsDir)
     if (skills.length > 0) {
       console.log(`\n⌨️  Commands: ${cmdOk} скопійовано, ${cmdFail} з помилками`)
     }
@@ -841,7 +888,7 @@ async function runSync() {
   }
 
   try {
-    await syncAgentsMd(skills)
+    await syncAgentsMd(skills, bundledAgentsTemplatePath)
   } catch (error) {
     console.error(`❌ Не вдалося оновити ${AGENTS_FILE}: ${error.message}`)
     throw error

package/mdc/abie.mdc

@@ -1,10 +1,10 @@
 ---
 description: Правила для проєктів AbInBev Efes
 alwaysApply: true
-version: '1.8'
+version: '1.9'
 ---
 
-Правило **abie** для споживачів **@nitra/cursor**: **k8s** (Deployment + **HealthCheckPolicy** у **`hc.yaml`**, overlay **ua** / **ru** — **nodeSelector**, **HTTPRoute** (будь-який непорожній **`target.name`**), видалення **HealthCheckPolicy** у **ru**), а також гілки **dev**, **ua**, **ru** у **clean-merged-branch**.
+Правило **abie** для споживачів **@nitra/cursor**: **k8s** (Deployment + **HealthCheckPolicy** у **`hc.yaml`**, overlay **ua** / **ru** — **nodeSelector**, **HTTPRoute** (будь-який непорожній **`target.name`**), видалення **HealthCheckPolicy** у **ru**), гілки **dev**, **ua**, **ru** у **clean-merged-branch**, а також заборона артефактів **Firebase Hosting** у корені репозиторію.
 
 **`npx @nitra/cursor check abie`** виконується лише якщо в **`.n-cursor.json`** у **`rules`** є **`abie`** — інакше вихід **0** без зауважень.
 
@@ -135,6 +135,10 @@ spec:
         preem: 'true' # буде замінено через kustomize
 ```
 
+## Firebase Hosting
+
+У корені репозиторію не тримати конфіг і кеш **Firebase Hosting**: видали **`.firebaserc`**, **`firebase.json`** та каталог **`.firebase/`**, якщо вони є.
+
 ## Git branches
 
 У **`.github/workflows/clean-merged-branch.yml`** у кроці **`phpdocker-io/github-actions-delete-abandoned-branches`** значення **`with.ignore_branches`** має містити **dev**, **ua** та **ru** (разом з іншими гілками, якщо потрібно):

package/package.json

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

package/scripts/check-abie.mjs

@@ -8,6 +8,8 @@
  * **`phpdocker-io/github-actions-delete-abandoned-branches`** у **`with.ignore_branches`** мають бути
  * **dev**, **ua** та **ru** (разом з іншими гілками, якщо потрібно).
  *
+ * **Firebase Hosting:** у корені репозиторію не має бути **`.firebaserc`**, **`firebase.json`** та каталогу **`.firebase/`**.
+ *
  * **k8s:** якщо під деревом із сегментом **`k8s`** є YAML з **`kind: Deployment`**, у тій самій директорії
  * має існувати **`hc.yaml`** із **`HealthCheckPolicy`** (**`networking.gke.io/v1`**), modeline **`$schema`**
  * як у abie.mdc, **`/healthz`**, порт **8080**, **`targetRef`** на **Service** з тим самим **`metadata.name`**.
@@ -968,6 +970,30 @@ async function ensureUaRuAbieHttpRoutePatches(root, yamlFilesAbs, fail, passFn)
   }
 }
 
+/**
+ * Перевіряє відсутність артефактів Firebase Hosting у корені репозиторію (abie.mdc).
+ * @param {string} root корінь репозиторію
+ * @param {(msg: string) => void} passFn успішне повідомлення
+ * @param {(msg: string) => void} failFn повідомлення про порушення
+ * @returns {void}
+ */
+function ensureNoFirebaseHostingArtifacts(root, passFn, failFn) {
+  for (const name of ['.firebaserc', 'firebase.json']) {
+    const abs = join(root, name)
+    if (existsSync(abs)) {
+      failFn(`Знайдено заборонений файл Firebase Hosting: ${name} — видали його (abie.mdc)`)
+    } else {
+      passFn(`Немає ${name}`)
+    }
+  }
+  const firebaseDir = join(root, '.firebase')
+  if (existsSync(firebaseDir)) {
+    failFn('Знайдено директорію .firebase — видали її (abie.mdc)')
+  } else {
+    passFn('Немає .firebase/')
+  }
+}
+
 /**
  * Перевіряє відповідність проєкту правилам abie.mdc.
  * @returns {Promise<number>} 0 — OK, 1 — є порушення
@@ -984,6 +1010,7 @@ export async function check() {
   }
 
   pass('Правило abie увімкнено — виконуємо перевірки')
+  ensureNoFirebaseHostingArtifacts(root, pass, fail)
 
   const cleanMergedPath = join(root, '.github/workflows/clean-merged-branch.yml')
   if (existsSync(cleanMergedPath)) {

package/scripts/upgrade-nitra-cursor-and-install.mjs

@@ -0,0 +1,201 @@
+/**
+ * Перед синхронізацією правил CLI підтягує останню опубліковану версію `@nitra/cursor` з npm registry
+ * у кореневий `package.json` і запускає `bun i` у корені проєкту.
+ *
+ * Якщо залежність уже задана через `workspace:`, `file:`, `link:` тощо, запис у registry не
+ * змінюється і `bun i` не викликається — так зберігається робота монорепо та сценаріїв з `workspace:`, `file:` чи `link:`.
+ *
+ * Після встановлення повертається шлях до `node_modules/@nitra/cursor`, якщо каталог з
+ * `package.json` існує; інакше — fallback (корінь пакету поточного процесу CLI, наприклад кеш npx).
+ */
+
+import { execFile } from 'node:child_process'
+import { promisify } from 'node:util'
+import { existsSync } from 'node:fs'
+import { readFile, writeFile } from 'node:fs/promises'
+import { join } from 'node:path'
+
+const PACKAGE_NAME = '@nitra/cursor'
+const NPM_LATEST_URL = 'https://registry.npmjs.org/@nitra/cursor/latest'
+
+const execFileAsync = promisify(execFile)
+
+/**
+ * Чи не можна безпечно підставити semver з npm замість поточного специфікатора залежності.
+ * @param {string} specifier значення з package.json
+ * @returns {boolean} true — залишити як є (монорепо, git, tarball тощо)
+ */
+export function shouldSkipNpmVersionUpgrade(specifier) {
+  const s = String(specifier).trim()
+  if (!s) {
+    return true
+  }
+  if (/^workspace:/i.test(s)) {
+    return true
+  }
+  if (/^file:/i.test(s)) {
+    return true
+  }
+  if (/^link:/i.test(s)) {
+    return true
+  }
+  if (/^portal:/i.test(s)) {
+    return true
+  }
+  if (/^git(\+|:\/\/)/i.test(s)) {
+    return true
+  }
+  if (/^npm:/i.test(s)) {
+    return true
+  }
+  if (/^https?:\/\//i.test(s)) {
+    return true
+  }
+  if (s.startsWith('./') || s.startsWith('../')) {
+    return true
+  }
+  return false
+}
+
+/**
+ * Остання версія пакета з npm (поле `version` у JSON dist-tag `latest`).
+ * @returns {Promise<string>} semver без префікса `^`
+ */
+export async function fetchLatestNitraCursorVersionFromNpm() {
+  const res = await fetch(NPM_LATEST_URL, {
+    headers: { accept: 'application/json' }
+  })
+  if (!res.ok) {
+    throw new Error(`npm registry: ${res.status} ${res.statusText} для ${PACKAGE_NAME}`)
+  }
+  const data = await res.json()
+  if (!data || typeof data.version !== 'string' || !data.version.trim()) {
+    throw new Error(`npm registry: у відповіді для ${PACKAGE_NAME} немає поля version`)
+  }
+  return data.version.trim()
+}
+
+/**
+ * Шлях до встановленого пакета в `node_modules` або fallback.
+ * @param {string} projectRoot корінь репозиторію
+ * @param {string} fallbackPackageRoot корінь пакету з поточного процесу
+ * @returns {string} абсолютний шлях до каталогу з `mdc/`, `scripts/` тощо
+ */
+export function resolveInstalledPackageRoot(projectRoot, fallbackPackageRoot) {
+  const installed = join(projectRoot, 'node_modules', PACKAGE_NAME)
+  if (existsSync(join(installed, 'package.json'))) {
+    return installed
+  }
+  return fallbackPackageRoot
+}
+
+/**
+ * Запускає `bun i` у вказаному каталозі з виводом у поточний stdio.
+ * @param {string} projectRoot cwd для процесу
+ * @returns {Promise<void>} завершується після успішного `bun i`
+ */
+async function runBunInstall(projectRoot) {
+  try {
+    await execFileAsync('bun', ['i'], { cwd: projectRoot, stdio: 'inherit' })
+  } catch (error) {
+    const exitCode = typeof error?.code === 'number' ? error.code : null
+    if (exitCode !== null && exitCode !== 0) {
+      throw new Error(`bun i завершився з кодом ${exitCode}`)
+    }
+    throw error
+  }
+}
+
+/**
+ * Де зараз оголошено `@nitra/cursor` у package.json.
+ * @param {Record<string, unknown>} pkg вміст package.json як об'єкт після читання JSON
+ * @returns {{ section: 'devDependencies' | 'dependencies', value: string } | null} секція та специфікатор або null, якщо залежності немає
+ */
+function findNitraCursorDependency(pkg) {
+  const dev = pkg.devDependencies
+  if (dev && typeof dev === 'object' && !Array.isArray(dev) && PACKAGE_NAME in dev) {
+    const value = dev[PACKAGE_NAME]
+    if (typeof value === 'string') {
+      return { section: 'devDependencies', value }
+    }
+  }
+  const deps = pkg.dependencies
+  if (deps && typeof deps === 'object' && !Array.isArray(deps) && PACKAGE_NAME in deps) {
+    const value = deps[PACKAGE_NAME]
+    if (typeof value === 'string') {
+      return { section: 'dependencies', value }
+    }
+  }
+  return null
+}
+
+/**
+ * Оновлює `@nitra/cursor` до `^<latest>` з npm (якщо дозволено специфікатором), виконує `bun i`,
+ * повертає корінь пакету для читання `mdc/` та інших файлів синхронізації.
+ * @param {string} projectRoot корінь цільового репозиторію (`cwd()`)
+ * @param {string} fallbackPackageRoot корінь пакету з `import.meta.url` (кеш npx або workspace)
+ * @returns {Promise<string>} абсолютний шлях до кореня `@nitra/cursor` для копіювання файлів
+ */
+export async function upgradeNitraCursorToLatestAndBunInstall(projectRoot, fallbackPackageRoot) {
+  const pkgPath = join(projectRoot, 'package.json')
+  if (!existsSync(pkgPath)) {
+    return resolveInstalledPackageRoot(projectRoot, fallbackPackageRoot)
+  }
+
+  let raw
+  try {
+    raw = await readFile(pkgPath, 'utf8')
+  } catch {
+    return resolveInstalledPackageRoot(projectRoot, fallbackPackageRoot)
+  }
+
+  let pkg
+  try {
+    pkg = JSON.parse(raw)
+  } catch {
+    return resolveInstalledPackageRoot(projectRoot, fallbackPackageRoot)
+  }
+
+  if (pkg === null || typeof pkg !== 'object' || Array.isArray(pkg)) {
+    return resolveInstalledPackageRoot(projectRoot, fallbackPackageRoot)
+  }
+
+  const found = findNitraCursorDependency(pkg)
+
+  if (found && shouldSkipNpmVersionUpgrade(found.value)) {
+    console.log(`⏭️  ${PACKAGE_NAME}: специфікатор «${found.value}» — без оновлення з npm та без bun i\n`)
+    return resolveInstalledPackageRoot(projectRoot, fallbackPackageRoot)
+  }
+
+  const latest = await fetchLatestNitraCursorVersionFromNpm()
+  const desired = `^${latest}`
+
+  if (!found) {
+    if (!pkg.devDependencies || typeof pkg.devDependencies !== 'object' || Array.isArray(pkg.devDependencies)) {
+      pkg.devDependencies = {}
+    }
+    pkg.devDependencies[PACKAGE_NAME] = desired
+    await writeFile(pkgPath, `${JSON.stringify(pkg, null, 2)}\n`, 'utf8')
+    console.log(`📝 Додано ${PACKAGE_NAME}@${desired} у devDependencies (остання з npm)\n`)
+    await runBunInstall(projectRoot)
+    console.log(`📦 Виконано bun i у корені проєкту\n`)
+    return resolveInstalledPackageRoot(projectRoot, fallbackPackageRoot)
+  }
+
+  if (found.value === desired) {
+    console.log(`📌 ${PACKAGE_NAME} уже ${desired} у package.json — виконуємо bun i\n`)
+  } else {
+    if (found.section === 'devDependencies') {
+      pkg.devDependencies[PACKAGE_NAME] = desired
+    } else {
+      pkg.dependencies[PACKAGE_NAME] = desired
+    }
+    await writeFile(pkgPath, `${JSON.stringify(pkg, null, 2)}\n`, 'utf8')
+    console.log(`📝 Оновлено ${PACKAGE_NAME} → ${desired} у package.json\n`)
+  }
+
+  await runBunInstall(projectRoot)
+  console.log(`📦 Виконано bun i у корені проєкту\n`)
+
+  return resolveInstalledPackageRoot(projectRoot, fallbackPackageRoot)
+}