@nitra/cursor 1.8.178 → 1.8.180

package/CHANGELOG.md

@@ -4,6 +4,19 @@
 
 Формат — [Keep a Changelog](https://keepachangelog.com/uk/1.1.0/), нумерація — [SemVer](https://semver.org/lang/uk/).
 
+## [1.8.180] - 2026-05-05
+
+### Changed
+
+- `js-run` (mdc v1.1 → v1.2): додано секцію **«Область застосування»** — правило явно не застосовується до frontend-пакетів (маркер `vite` у `devDependencies`). У браузерному бандлі немає `node:process`, тому заміна `process.env.X` на `import { env } from 'node:process'` ламає рантайм (`TypeError: Cannot read properties of undefined (reading 'X')`); для frontend замість `process.env.NODE_ENV` — `import.meta.env.MODE` / `import.meta.env.PROD`, інші ENV — лише `import.meta.env.VITE_*`. Передумова — інцидент у abie/b2b `site/`, де LLM-агент за правилом замінив `process.env.NODE_ENV` у `src/main.js` і вибив прод-бандл.
+- `check-js-run.mjs`: workspace-пакети з `vite` у `devDependencies` пропускаються — нова `packageJsonHasViteDevDependency(pkgJson)`, виклик одразу після `loadPackageJsonAndCheckBunyanDeps`. bunyan-залежність у `package.json` все одно перевіряється (бо це робиться до раннього виходу), але скан `process.env`, `#conn/*` і OTEL configmap для frontend-пакета не запускається. Тести: 2 нові кейси у `check-js-run-fixture.test.mjs` (vite-пакет з прямим `process.env` — pass; non-vite пакет з тим же кодом — fail).
+
+## [1.8.179] - 2026-05-05
+
+### Changed
+
+- `abie` (`check-abie.mjs` / `mdc/abie.mdc`): `httpHealthCheck.requestPath` у `HealthCheckPolicy` (`hc.yaml`) тепер допускає будь-який непорожній шлях від кореня — рядок, що починається з `/` (`/healthz`, `/IsAlive`, `/api/live` тощо), замість жорсткої вимоги `/healthz`. Решта вимог незмінна: `type: HTTP`, `port: 8080`, `targetRef` на headless Service з суфіксом `-hl`. Канонічно рекомендується `/healthz`, але правило не блокує сервіси з власним liveness endpoint. JSDoc у `check-abie.mjs` і опис у `mdc/abie.mdc` приведено у відповідність до коду. Тести: 3 нові кейси у `check-abie.test.mjs` (нестандартний `/IsAlive`, відсутній лідируючий `/`, порожній рядок).
+
 ## [1.8.178] - 2026-05-05
 
 ### Added

package/mdc/abie.mdc

@@ -12,7 +12,7 @@ version: '1.17'
 
 ## k8s: `hc.yaml` поруч із Deployment
 
-Якщо під **`k8s`** є **Deployment**, у **тій самій директорії** має бути **`hc.yaml`** з **HealthCheckPolicy** (**`networking.gke.io/v1`**): коректний modeline **`$schema`**, **`/healthz`**, порт **8080**, **`targetRef.name`** — **headless** **Service** з суфіксом **`-hl`** (узгоджено з парою **`svc.yaml`** / **`svc-hl.yaml`** у **k8s.mdc**): або **`${metadata.name}-hl`**, або те саме ім’я, якщо **`metadata.name`** уже з **`-hl`**.
+Якщо під **`k8s`** є **Deployment**, у **тій самій директорії** має бути **`hc.yaml`** з **HealthCheckPolicy** (**`networking.gke.io/v1`**): коректний modeline **`$schema`**, **`httpHealthCheck.requestPath`** — непорожній шлях від кореня (рядок, що починається з **`/`**: канонічно **`/healthz`**, але також допустимі **`/IsAlive`**, **`/api/live`** тощо — узгоджується з реальним endpoint сервісу), порт **8080**, **`targetRef.name`** — **headless** **Service** з суфіксом **`-hl`** (узгоджено з парою **`svc.yaml`** / **`svc-hl.yaml`** у **k8s.mdc**): або **`${metadata.name}-hl`**, або те саме ім’я, якщо **`metadata.name`** уже з **`-hl`**.
 
 ```yaml title="hc.yaml"
 # yaml-language-server: $schema=https://datreeio.github.io/CRDs-catalog/networking.gke.io/healthcheckpolicy_v1.json

package/mdc/js-run.mdc

@@ -1,9 +1,21 @@
 ---
 description: Це правила для backend проектів на JavaScript/Node.js, сюди входять і job і WEB сервери.
 alwaysApply: true
-version: '1.1'
+version: '1.2'
 ---
 
+## Область застосування
+
+Правило стосується **виключно backend Node.js workspace-пакетів** (jobs, GraphQL/HTTP-сервери, CLI). **Не застосовується** до frontend-пакетів, які бандляться в браузер: маркер — наявність `vite` у `devDependencies` пакета (`site/`, мобільні Capacitor-пакети, будь-яка Vue/Quasar SPA).
+
+У браузерному середовищі:
+
+- немає `node:process` — імпорт `import { env } from 'node:process'` resolve'иться у `undefined`, і `env.X` падає з `TypeError: Cannot read properties of undefined`;
+- `process.env.X` у джерелах пакета відсутнє в рантаймі — Vite або взагалі не підставляє його, або підставляє лише `process.env.NODE_ENV`;
+- усі змінні оточення для frontend задаються через `VITE_*` і доступні як `import.meta.env.VITE_X` (типобезпечно через `vite-check-env`); режим — `import.meta.env.MODE` / `import.meta.env.PROD`.
+
+Тому **у frontend-пакетах не торкайся `process.env.*`** і **не додавай** `import { env } from 'node:process'`. Якщо натрапив на `process.env.NODE_ENV` у frontend-коді — заміна, якщо взагалі потрібна, лише на `import.meta.env.MODE`.
+
 ## Структура проекту
 
 Рекомендується використовувати таку структуру проекту:
@@ -108,6 +120,8 @@ export const db = new SQL({ url: env.PG_CONN })
 
 Прямий доступ до `process.env.X` у коді заборонений — його треба замінити на `env`:
 
+> Стосується лише backend-пакетів (див. **Область застосування**). У frontend-пакетах (`vite` у `devDependencies`) — **не змінюй** `process.env.*` і **не додавай** імпорт `node:process`.
+
 - **обов'язкова змінна** — `import { checkEnv, env } from '@nitra/check-env'` плюс `checkEnv(['X'])`
   у тому ж файлі (приклад див. вище в розділі **CheckEnv**);
 - **опційна змінна** — `import { env } from 'node:process'`:

package/package.json

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

package/scripts/check-abie.mjs

@@ -13,7 +13,7 @@
  *
  * **k8s:** якщо під деревом із сегментом **`k8s`** є YAML з **`kind: Deployment`**, у тій самій директорії
  * має існувати **`hc.yaml`** із **`HealthCheckPolicy`** (**`networking.gke.io/v1`**), modeline **`$schema`**
- * як у abie.mdc, **`/healthz`**, порт **8080**, **`targetRef`** на **headless Service** (ім'я з суфіксом **`-hl`**):
+ * як у abie.mdc, **`requestPath`** — непорожній шлях від кореня (рядок, що починається з **`/`**: **`/healthz`**, **`/IsAlive`**, **`/api/live`** тощо), порт **8080**, **`targetRef`** на **headless Service** (ім'я з суфіксом **`-hl`**):
  * якщо **`metadata.name`** уже закінчується на **`-hl`**, **`targetRef.name`** має збігатися з ним; інакше **`targetRef.name`** = **`${metadata.name}-hl`**.
  * Загальні вимоги до **`# yaml-language-server: $schema`** для інших YAML під **`k8s`** — у **check-k8s.mjs** / **k8s.mdc** (наприклад **HttpBackendGroup** `alb.yc.io/v1alpha1` — **без** modeline).
  * Якщо в дереві **k8s** є **HealthCheckPolicy**, перевіряється **`ru/kustomization.yaml`** з patch **`$patch: delete`**
@@ -1324,7 +1324,10 @@ function validateAbieHcPolicy(policy, relPath) {
   if (httpHc === null || typeof httpHc !== 'object' || Array.isArray(httpHc)) {
     return `${relPath}: відсутній httpHealthCheck (abie.mdc)`
   }
-  if (httpHc.requestPath !== '/healthz') return `${relPath}: httpHealthCheck.requestPath має бути /healthz (abie.mdc)`
+  const requestPath = typeof httpHc.requestPath === 'string' ? httpHc.requestPath.trim() : ''
+  if (requestPath === '' || !requestPath.startsWith('/')) {
+    return `${relPath}: httpHealthCheck.requestPath має бути непорожнім шляхом від кореня (рядок, що починається з /) (abie.mdc)`
+  }
   if (httpHc.port !== 8080) return `${relPath}: httpHealthCheck.port має бути 8080 (abie.mdc)`
   const targetRef = specRec.targetRef
   if (targetRef === null || typeof targetRef !== 'object' || Array.isArray(targetRef)) {

package/scripts/check-docker.mjs

@@ -66,7 +66,7 @@ export function isDockerfileName(name) {
 /**
  * Збирає абсолютні шляхи до Dockerfile / Containerfile від кореня cwd.
  * @param {string} root корінь репозиторію
- * @param {string[]} [ignorePaths=[]] шляхи каталогів, повністю виключених з обходу
+ * @param {string[]} [ignorePaths] шляхи каталогів, повністю виключених з обходу
  * @returns {Promise<string[]>} відсортовані абсолютні шляхи
  */
 export async function findDockerfilePaths(root, ignorePaths = []) {

package/scripts/check-graphql.mjs

@@ -32,6 +32,7 @@ export const REQUIRED_DUMP_SCHEMA_SCRIPT =
 /**
  * Збирає абсолютні шляхи source-файлів, які підлягають скануванню на gql templates.
  * @param {string} root абсолютний шлях кореня
+ * @param {string[]} ignorePaths абсолютні шляхи каталогів, повністю виключених з обходу
  * @returns {Promise<string[]>} список кандидатів
  */
 async function collectScanCandidates(root, ignorePaths) {

package/scripts/check-js-run.mjs

@@ -53,6 +53,7 @@ function relPosix(absPackageRoot, absPath) {
 /**
  * Сканує джерела пакета на заборонені імпорти `@nitra/bunyan` / `bunyan`.
  * @param {string} absPackageRoot абсолютний шлях до кореня пакета
+ * @param {string[]} ignorePaths абсолютні шляхи каталогів, повністю виключених з обходу
  * @param {string} label префікс повідомлення `[<pkg>] `
  * @param {(msg: string) => void} fail callback при помилці
  * @returns {Promise<number>} кількість знайдених порушень
@@ -86,6 +87,7 @@ async function checkBunyanImports(absPackageRoot, ignorePaths, label, fail) {
 /**
  * Збирає всі JS/TS-файли пакета (без node_modules, dist тощо).
  * @param {string} absPackageRoot абсолютний шлях до кореня пакета
+ * @param {string[]} ignorePaths абсолютні шляхи каталогів, повністю виключених з обходу
  * @returns {Promise<string[]>} абсолютні шляхи до файлів
  */
 async function collectSourceFiles(absPackageRoot, ignorePaths) {
@@ -158,6 +160,7 @@ async function checkProcessEnvUsage(absPackageRoot, sourcePaths, label, fail) {
 /**
  * Перевіряє відповідність правилам js-run.mdc для одного workspace-пакета.
  * @param {string} rootDir відносний шлях workspace (не `'.'`)
+ * @param {string[]} ignorePaths абсолютні шляхи каталогів, повністю виключених з обходу
  * @param {(msg: string) => void} fail функція зворотного виклику для реєстрації помилки перевірки
  * @param {(msg: string) => void} passFn успішне повідомлення (як у check-reporter)
  * @returns {Promise<void>} завершується після перевірок цього пакета
@@ -167,6 +170,15 @@ async function checkWorkspacePackage(rootDir, ignorePaths, fail, passFn) {
   const absPackageRoot = join(process.cwd(), rootDir)
   const pkgJson = await loadPackageJsonAndCheckBunyanDeps(rootDir, label, fail)
 
+  // Frontend-пакети (vite у devDependencies) виходять за межі js-run:
+  // браузерний бандл не має `node:process`, а `process.env.*` бандлер
+  // обробляє самостійно. Перевірку process.env / conn-аліасів пропускаємо,
+  // bunyan-залежність уже звірено в `loadPackageJsonAndCheckBunyanDeps`.
+  if (packageJsonHasViteDevDependency(pkgJson)) {
+    passFn(`${label}vite-пакет (frontend) — js-run пропущено (process.env / conn-aliases / OTEL configmap)`)
+    return
+  }
+
   const importViolations = await checkBunyanImports(absPackageRoot, ignorePaths, label, fail)
   if (importViolations === 0) {
     passFn(`${label}немає імпортів '@nitra/bunyan' / 'bunyan' у джерелах`)
@@ -190,6 +202,20 @@ async function checkWorkspacePackage(rootDir, ignorePaths, fail, passFn) {
   await checkOtelConfigmap(rootDir, label, fail, passFn)
 }
 
+/**
+ * Чи має пакет `vite` у `devDependencies` (маркер frontend-пакета — vite/quasar/capacitor SPA).
+ * Семантично ідентично `packageJsonLacksViteDevDependency` з `auto-rules.mjs`, але
+ * приймає вже розпарсений pkgJson.
+ * @param {unknown} pkgJson розпарсений `package.json` пакета (або null)
+ * @returns {boolean} true, якщо `vite` присутній у `devDependencies`
+ */
+function packageJsonHasViteDevDependency(pkgJson) {
+  if (!pkgJson || typeof pkgJson !== 'object' || Array.isArray(pkgJson)) return false
+  const devDeps = /** @type {Record<string, unknown>} */ (pkgJson).devDependencies
+  if (!devDeps || typeof devDeps !== 'object' || Array.isArray(devDeps)) return false
+  return Object.hasOwn(devDeps, 'vite')
+}
+
 /**
  * Завантажує `package.json` пакета (якщо є) і реєструє порушення для bunyan-залежностей.
  * @param {string} rootDir відносний шлях workspace

package/scripts/check-k8s.mjs

@@ -1636,7 +1636,7 @@ export function baseKustomizationNamespaceViolation(obj) {
 /**
  * Збирає всі `*.yaml` та `*.yml` під деревом від кореня cwd, якщо шлях містить сегмент `k8s` (для `.yml` далі — помилка перейменування).
  * @param {string} root корінь репозиторію (cwd)
- * @param {string[]} [ignorePaths=[]] шляхи каталогів, повністю виключених з обходу
+ * @param {string[]} [ignorePaths] шляхи каталогів, повністю виключених з обходу
  * @returns {Promise<string[]>} відсортовані абсолютні шляхи до файлів
  */
 async function findK8sYamlFiles(root, ignorePaths = []) {

package/scripts/check-nginx-default-tpl.mjs

@@ -35,6 +35,7 @@ const GZIP_EXTENSION_RE = /\*\.(?:js|css)/u
 /**
  * Збирає абсолютні шляхи до **default.conf.template** у репозиторії; шлях `tests/fixtures` не обходиться як проєктний шаблон.
  * @param {string} root корінь cwd
+ * @param {string[]} ignorePaths абсолютні шляхи каталогів, повністю виключених з обходу
  * @returns {Promise<string[]>} відсортовані абсолютні шляхи до шаблонів
  */
 export async function findDefaultConfTemplatePaths(root, ignorePaths = []) {
@@ -57,6 +58,7 @@ export async function findDefaultConfTemplatePaths(root, ignorePaths = []) {
  * Знаходить у дереві від `root` усі **default.tpl.conf**. Якщо поруч немає **default.conf.template** —
  * перейменовує файл; якщо є — перезаписує **default.conf.template** вмістом **default.tpl.conf** і видаляє **default.tpl.conf**.
  * @param {string} root корінь обходу (зазвичай cwd репозиторію)
+ * @param {string[]} ignorePaths абсолютні шляхи каталогів, повністю виключених з обходу
  * @returns {Promise<{ renamed: string[], overwritten: string[] }>} відносні шляхи до обробленого **default.tpl.conf** (для звіту)
  */
 export async function migrateDefaultTplConfFiles(root, ignorePaths = []) {
@@ -322,6 +324,7 @@ async function checkTemplateFile(abs, root, passFn, failFn) {
 /**
  * Перевіряє Dockerfile на наявність gzip та envsubst.
  * @param {string} root корінь репозиторію
+ * @param {string[]} ignorePaths абсолютні шляхи каталогів, повністю виключених з обходу
  * @param {(msg: string) => void} passFn callback при успішній перевірці
  * @param {(msg: string) => void} failFn callback при помилці
  */

package/scripts/check-npm-module.mjs

@@ -36,6 +36,7 @@ const EMIT_TYPES_CONFIG = 'npm/tsconfig.emit-types.json'
 
 /**
  * Чи є під `npm/src` хоча б один `.js` (рекурсивно).
+ * @param {string[]} [ignorePaths] абсолютні шляхи каталогів, повністю виключених з обходу
  * @returns {Promise<boolean>} `true`, якщо знайдено хоча б один `.js`
  */
 async function npmSrcTreeHasJsFile(ignorePaths = []) {

package/scripts/claude-stop-hook.mjs

@@ -11,25 +11,27 @@
  *   `npx --no @nitra/cursor stop-hook`
  */
 import { spawn } from 'node:child_process'
+import { once } from 'node:events'
 
 /**
  * Зчитує stdin до EOF як utf8 рядок. Якщо stdin порожній (TTY) — повертає '' одразу.
  * @returns {Promise<string>} вміст stdin
  */
-function readStdin() {
-  return new Promise(resolve => {
-    if (process.stdin.isTTY) {
-      resolve('')
-      return
-    }
-    let data = ''
-    process.stdin.setEncoding('utf8')
-    process.stdin.on('data', chunk => {
-      data += chunk
-    })
-    process.stdin.on('end', () => resolve(data))
-    process.stdin.on('error', () => resolve(data))
+async function readStdin() {
+  if (process.stdin.isTTY) {
+    return ''
+  }
+  process.stdin.setEncoding('utf8')
+  const chunks = []
+  process.stdin.on('data', chunk => {
+    chunks.push(chunk)
   })
+  try {
+    await once(process.stdin, 'end')
+  } catch {
+    // 'error' на stdin — повертаємо те, що встигли зібрати
+  }
+  return chunks.join('')
 }
 
 /**
@@ -60,12 +62,12 @@ export async function runStopHookCli() {
   if (isRecursiveStopHookCall(stdin)) {
     return 0
   }
-  return new Promise(resolve => {
-    const child = spawn('npx', ['--no', '@nitra/cursor', 'check'], { stdio: 'inherit' })
-    child.on('exit', code => resolve(code ?? 1))
-    child.on('error', err => {
-      process.stderr.write(`stop-hook: не вдалося запустити npx @nitra/cursor check — ${err.message}\n`)
-      resolve(1)
-    })
-  })
+  const child = spawn('npx', ['--no', '@nitra/cursor', 'check'], { stdio: 'inherit' })
+  try {
+    const [code] = await once(child, 'exit')
+    return code ?? 1
+  } catch (error) {
+    process.stderr.write(`stop-hook: не вдалося запустити npx @nitra/cursor check — ${error.message}\n`)
+    return 1
+  }
 }

package/scripts/rename-yaml-extensions.mjs

@@ -68,6 +68,7 @@ export function replaceExtension(relPosix, newExt) {
 /**
  * Збирає операції перейменування (без виконання).
  * @param {string} rootAbs абсолютний корінь репозиторію
+ * @param {string[]} ignorePaths абсолютні шляхи каталогів, повністю виключених з обходу
  * @returns {Promise<Array<{ kind: 'k8s' | 'github', fromAbs: string, toAbs: string, relFrom: string, relTo: string }>>} відсортовані операції перейменування без запису на диск
  */
 async function collectRenameOps(rootAbs, ignorePaths) {

package/scripts/sync-claude-config.mjs

@@ -28,27 +28,27 @@ const TEMPLATE_DIR_NAME = '.claude-template'
 
 /**
  * @typedef {object} HookEntry
- * @property {string} type
- * @property {string} command
- * @property {number} [timeout]
+ * @property {string} type тип hook'а у форматі Claude Code (зазвичай `'command'`)
+ * @property {string} command команда, яку виконує Claude Code (наш маркер живе саме тут)
+ * @property {number} [timeout] опційний таймаут у секундах
  */
 
 /**
  * @typedef {object} HookGroup
- * @property {string} [matcher]
- * @property {HookEntry[]} hooks
+ * @property {string} [matcher] патерн (наприклад, `'.*'`) для звуження hook'а
+ * @property {HookEntry[]} hooks впорядкований список команд hook-групи
  */
 
 /**
  * @typedef {object} ClaudeSettings
- * @property {{ allow?: string[] }} [permissions]
- * @property {Record<string, HookGroup[]>} [hooks]
+ * @property {{ allow?: string[] }} [permissions] секція `permissions` із .claude/settings.json
+ * @property {Record<string, HookGroup[]>} [hooks] hooks за подіями (`Stop`, `PreToolUse`, ...)
  */
 
 /**
  * Чи hook-група містить лише наші managed-команди (за маркером).
- * @param {HookGroup} group
- * @returns {boolean}
+ * @param {HookGroup} group hook-група з .claude/settings.json
+ * @returns {boolean} `true`, якщо всі hooks мають маркер `MANAGED_HOOK_COMMAND_MARKER`
  */
 function isManagedHookGroup(group) {
   if (!group?.hooks?.length) {
@@ -60,9 +60,9 @@ function isManagedHookGroup(group) {
 /**
  * Зливає список allow-permissions: union існуючого і темплейтного без дублікатів,
  * порядок — спочатку існуючі (щоб не міняти користувацький порядок), потім нові.
- * @param {string[] | undefined} existing
- * @param {string[] | undefined} fromTemplate
- * @returns {string[]}
+ * @param {string[] | undefined} existing існуючий список з `.claude/settings.json` користувача
+ * @param {string[] | undefined} fromTemplate список з темплейту пакета `@nitra/cursor`
+ * @returns {string[]} об'єднаний список без дублікатів (порядок: існуючі, потім нові)
  */
 export function mergeAllowList(existing, fromTemplate) {
   const out = []
@@ -83,9 +83,9 @@ export function mergeAllowList(existing, fromTemplate) {
  * Зливає hooks-секцію: для кожної події в темплейті видаляємо managed-групи
  * з існуючої конфігурації і додаємо актуальні з темплейту. Немені події в
  * темплейті не чіпаються.
- * @param {Record<string, HookGroup[]> | undefined} existing
- * @param {Record<string, HookGroup[]> | undefined} fromTemplate
- * @returns {Record<string, HookGroup[]>}
+ * @param {Record<string, HookGroup[]> | undefined} existing поточна `hooks`-секція з .claude/settings.json
+ * @param {Record<string, HookGroup[]> | undefined} fromTemplate цільова `hooks`-секція з темплейту
+ * @returns {Record<string, HookGroup[]>} результат злиття (порожні події видаляються)
  */
 export function mergeHooks(existing, fromTemplate) {
   /** @type {Record<string, HookGroup[]>} */
@@ -105,9 +105,9 @@ export function mergeHooks(existing, fromTemplate) {
 
 /**
  * Повертає об'єднаний об'єкт settings.json.
- * @param {ClaudeSettings | undefined} existing
- * @param {ClaudeSettings} template
- * @returns {ClaudeSettings}
+ * @param {ClaudeSettings | undefined} existing існуючий вміст `.claude/settings.json` користувача (або undefined, якщо файла нема)
+ * @param {ClaudeSettings} template settings із темплейту пакета `@nitra/cursor`
+ * @returns {ClaudeSettings} результат merge-у (користувацькі поля збережено, наші перевизначено)
  */
 export function mergeSettings(existing, template) {
   /** @type {ClaudeSettings} */
@@ -127,8 +127,8 @@ export function mergeSettings(existing, template) {
 
 /**
  * Читає JSON-файл; якщо файл відсутній або не валідний — повертає `undefined`.
- * @param {string} path
- * @returns {Promise<ClaudeSettings | undefined>}
+ * @param {string} path абсолютний шлях до JSON-файлу
+ * @returns {Promise<ClaudeSettings | undefined>} розпарсений об'єкт або `undefined` (файл відсутній / невалідний)
  */
 async function readJsonOrUndefined(path) {
   if (!existsSync(path)) {
@@ -146,7 +146,7 @@ async function readJsonOrUndefined(path) {
  * користувацьких полів.
  * @param {string} projectRoot корінь проєкту, куди писати
  * @param {string} templateDir каталог `.claude-template/` усередині пакету
- * @returns {Promise<{ written: boolean, path: string }>}
+ * @returns {Promise<{ written: boolean, path: string }>} результат: чи писали файл, та його відносний шлях
  */
 export async function syncClaudeSettings(projectRoot, templateDir) {
   const templatePath = join(templateDir, 'settings.template.json')
@@ -164,9 +164,9 @@ export async function syncClaudeSettings(projectRoot, templateDir) {
 
 /**
  * Копіює `npm/CLAUDE.md` з темплейту, якщо в проєкті є каталог `npm/`.
- * @param {string} projectRoot
- * @param {string} templateDir
- * @returns {Promise<{ written: boolean, path: string }>}
+ * @param {string} projectRoot корінь проєкту, куди писати
+ * @param {string} templateDir каталог `.claude-template/` усередині пакету `@nitra/cursor`
+ * @returns {Promise<{ written: boolean, path: string }>} результат: чи писали файл, та його відносний шлях
  */
 export async function syncNpmClaudeMd(projectRoot, templateDir) {
   if (!existsSync(join(projectRoot, 'npm'))) {
@@ -185,8 +185,8 @@ export async function syncNpmClaudeMd(projectRoot, templateDir) {
  * Копіює всі slash-команди з `templateDir/commands/` у `.claude/commands/`.
  * Команди ідентифікуються тим, що вони лежать у темплейті — не перетинаються
  * з командами скілів (n-fix, n-lint, ...).
- * @param {string} projectRoot
- * @param {string} templateDir
+ * @param {string} projectRoot корінь проєкту-споживача
+ * @param {string} templateDir каталог `.claude-template/` усередині пакету `@nitra/cursor`
  * @returns {Promise<string[]>} масив відносних шляхів записаних файлів
  */
 export async function syncClaudeCommands(projectRoot, templateDir) {
@@ -211,11 +211,11 @@ export async function syncClaudeCommands(projectRoot, templateDir) {
 /**
  * Виконує повну синхронізацію Claude Code-конфігу з темплейту пакету в проєкт.
  * Використовується з `bin/n-cursor.js` після інших синків.
- * @param {object} options
+ * @param {object} options опції синку
  * @param {string} options.projectRoot корінь проєкту-споживача
  * @param {string} options.bundledPackageRoot корінь установленого `@nitra/cursor`
  * @param {boolean} options.enabled чи увімкнено sync (з `.n-cursor.json` `claude-config`)
- * @returns {Promise<{ settings: boolean, npmClaudeMd: boolean, commands: string[] }>}
+ * @returns {Promise<{ settings: boolean, npmClaudeMd: boolean, commands: string[] }>} прапорці записів settings/CLAUDE.md та список записаних slash-команд
  */
 export async function syncClaudeConfig({ projectRoot, bundledPackageRoot, enabled }) {
   if (!enabled) {

package/scripts/utils/ast-scan-utils.mjs

@@ -118,7 +118,7 @@ export function parseProgramOrNull(content, virtualPath) {
  * базовий `parseProgramOrNull` свідомо лишається без коментарів, щоб не змінювати API.
  * @param {string} content вихідний код
  * @param {string} virtualPath шлях для вибору `lang` (також для діагностики)
- * @returns {{ program: unknown, comments: { type: 'Line' | 'Block', value: string, start: number, end: number }[] } | null}
+ * @returns {{ program: unknown, comments: { type: 'Line' | 'Block', value: string, start: number, end: number }[] } | null} `program` + список коментарів, або `null` якщо парсер віддав помилки/exception
  */
 export function parseProgramAndCommentsOrNull(content, virtualPath) {
   const lang = langFromPath(virtualPath || 'scan.ts')

package/scripts/utils/walkDir.mjs

@@ -25,7 +25,7 @@ function toAbsPosix(p) {
  * Часткові збіги басенейму не враховуються (postgres-master-test ≠ postgres-master).
  * @param {string} dirAbsPosix абсолютний posix-шлях каталогу
  * @param {string[]} ignorePosix вже нормалізовані ignore-шляхи
- * @returns {boolean}
+ * @returns {boolean} `true`, якщо шлях слід пропустити (точний збіг або префікс з `/`)
  */
 function isIgnoredDir(dirAbsPosix, ignorePosix) {
   for (const ig of ignorePosix) {
@@ -39,8 +39,8 @@ function isIgnoredDir(dirAbsPosix, ignorePosix) {
  * Рекурсивно обходить каталог, пропускає типові артефакти збірки/залежностей та `ignorePaths`.
  * @param {string} dir абсолютний шлях
  * @param {(filePath: string) => void} onFile виклик для кожного файлу
- * @param {string[]} [ignorePaths=[]] шляхи каталогів (відносні від cwd або абсолютні), що повністю виключаються з обходу
- * @returns {Promise<void>}
+ * @param {string[]} [ignorePaths] шляхи каталогів (відносні від cwd або абсолютні), що повністю виключаються з обходу
+ * @returns {Promise<void>} резолвиться по завершенню обходу
  */
 export async function walkDir(dir, onFile, ignorePaths = []) {
   const ignorePosix = ignorePaths.map(toAbsPosix)
@@ -49,10 +49,10 @@ export async function walkDir(dir, onFile, ignorePaths = []) {
 
 /**
  * Внутрішній рекурсор. ignorePosix вже нормалізовано — не нормалізуємо повторно на кожному рівні.
- * @param {string} dir
- * @param {(filePath: string) => void} onFile
- * @param {string[]} ignorePosix
- * @returns {Promise<void>}
+ * @param {string} dir абсолютний шлях каталогу для обходу
+ * @param {(filePath: string) => void} onFile колбек, що викликається для кожного звичайного файлу
+ * @param {string[]} ignorePosix вже нормалізовані абсолютні posix-шляхи ігнорованих каталогів
+ * @returns {Promise<void>} резолвиться по завершенню рекурсії
  */
 async function walkDirInner(dir, onFile, ignorePosix) {
   if (ignorePosix.length > 0 && isIgnoredDir(toAbsPosix(dir), ignorePosix)) return