@nitra/cursor 1.8.154 → 1.8.155

package/bin/auto-rules.md

@@ -18,7 +18,7 @@ graphql - якщо хоч в одному js або vue файлі присут
 
 js-lint - якщо присутній хоч один js файл
 
-js-pino - якщо присутній хоч один js файл, не в монорепо проекті з vue та директорії tempo
+js-run - якщо це вкладена директорія з package.json (не в корені) та в devDependencies немає vite
 
 js-mssql - якщо в хоч одному package.json в секції dependencies присутній пакет mssql
 

package/mdc/js-lint.mdc

@@ -26,9 +26,6 @@ version: '1.15'
   },
   "devDependencies": {
     "@nitra/eslint-config": "^3.6.12"
-  },
-  "engines": {
-    "node": ">=24"
   }
 }
 ```
@@ -138,11 +135,12 @@ export default [
 
 ## Додаткові js правила
 
-Завжди додавай до package.json що підтримується 24+ версія node:
+Завжди додавай до package.json що підтримується 24+ версія node і Bun 1.3+:
 
 ```json title="package.json"
 "engines": {
-  "node": ">=24"
+  "node": ">=24",
+  "bun": ">=1.3"
 }
 ```
 

package/mdc/js-run.mdc

@@ -0,0 +1,115 @@
+---
+description: Це правила для backend проектів на JavaScript/Node.js, сюди входять і job і WEB сервери.
+alwaysApply: true
+version: '1.1'
+---
+
+## Структура проекту
+
+Рекомендується використовувати таку структуру проекту:
+
+```
+k8s/ # тут всі файли для деплойменту в Kubernetes, включаючи kustomize
+src/ # тут всі файли необхідні для роботи проекту
+Dockerfile
+package.json
+readme.md
+```
+
+
+## Використання @nitra/pino
+
+Проект використовує @nitra/pino для логування.
+Якщо в проекті присутній @nitra/bunyan, то він повинен бути замінений на @nitra/pino — як у `package.json`, так і в коді: усі `import` / `require` / динамічні `import()` з `@nitra/bunyan` (і застарілого `bunyan`) треба замінити на `@nitra/pino` і за потреби адаптувати виклики під його API.
+
+В **/k8s/base/configmap.yaml повинен бути заданий OTEL_RESOURCE_ATTRIBUTES: 'service.name=<project_name>,service.namespace=<project_namespace>'
+а в директоріях з kustomize повинні бути перевизначені значення OTEL_RESOURCE_ATTRIBUTES і в них service.namespace повинен відповідати namespace, в якому знаходиться дана директорія.
+
+## Внутрішні аліаси
+
+Якщо в проекті є підключення до баз даних, зовнішніх graphql на кшталт:
+
+```js
+import { SQL } from 'bun'
+
+// або
+
+import sql from 'mssql'
+
+// або
+
+import { GraphQLClient } from '@nitra/graphql-request'
+```
+
+то ці підключення повинні бути винесені в окремий файл, наприклад `/src/conn/pg.js`, в package.json повинні бути додано аліас:
+
+```json
+{
+  "imports": {
+    "#conn/*": "./src/conn/*"
+  },
+}
+
+```
+
+так виглядатиме підключення до PostgreSQL в коді:
+```javascript title="Приклад підключення до PostgreSQL в /src/conn/pg.js"
+import { checkEnv, env } from '@nitra/check-env'
+import { SQL } from 'bun'
+
+checkEnv(['PG_CONN'])
+
+export const pool = new SQL({ url: env.PG_CONN })
+
+```
+
+а так до GraphQL:
+
+```js
+import { checkEnv } from '@nitra/check-env'
+import { GraphQLClient } from '@nitra/graphql-request'
+
+checkEnv(['QL', 'X_HASURA_ADMIN_SECRET'])
+
+export { gql } from '@nitra/graphql-request'
+
+export const graphQLClientSmart = new GraphQLClient(process.env.QL, {
+  headers: {
+    'X-Hasura-Admin-Secret': process.env.X_HASURA_ADMIN_SECRET
+  }
+})
+```
+
+
+а в коді повинно бути використано:
+
+```js
+import { pool } from '#conn/pg.js'
+
+// або
+
+import { gql, graphQLClient } from '@nitra/graphql-request'
+```
+
+
+
+## CheckEnv
+
+Усі змінні оточення, які використовуються в коді, повинні бути перевірені за допомогою `checkEnv` з пакету `@nitra/check-env`. Це гарантує, що всі необхідні змінні оточення встановлені перед запуском програми. (Виключенням можуть бути задані коментарем)
+
+
+```javascript title="Приклад підключення до PostgreSQL в /src/conn/pg.js"
+import { checkEnv, env } from '@nitra/check-env'
+import { SQL } from 'bun'
+
+checkEnv(['PG_CONN'])
+
+export const pool = new SQL({ url: env.PG_CONN })
+
+// @nitra/cursor ignore-next-line checkEnv
+console.log(process.env.OPTIONAL_ENV_VAR)
+```
+
+## Перевірка
+
+`npx @nitra/cursor check js-run`

package/package.json

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

package/scripts/auto-rules.mjs

@@ -31,7 +31,7 @@ export const AUTO_RULE_ORDER = Object.freeze([
   'js-lint',
   'js-mssql',
   'js-bun-db',
-  'js-pino',
+  'js-run',
   'k8s',
   'nginx-default-tpl',
   'npm-module',
@@ -138,6 +138,68 @@ async function collectDependencyKeysPresentInPackageJsonTree(root, dependencyKey
   return found
 }
 
+/**
+ * Перевіряє, чи існує хоча б один вкладений `package.json` (не кореневий),
+ * у якому в `devDependencies` відсутня залежність `vite`.
+ * @param {string} root абсолютний шлях до кореня репозиторію
+ * @returns {Promise<boolean>} true, якщо знайдено вкладений package.json без `vite` у devDependencies
+ */
+async function hasNestedPackageJsonWithoutViteDevDependency(root) {
+  let result = false
+
+  /**
+   * Перевіряє один package.json: повертає true, якщо в `devDependencies` немає `vite`.
+   * @param {string} absPath абсолютний шлях до package.json
+   * @returns {Promise<boolean>} true, якщо vite відсутній у devDependencies
+   */
+  async function packageJsonLacksViteDevDependency(absPath) {
+    try {
+      const parsed = JSON.parse(await readFile(absPath, 'utf8'))
+      const devDeps = parsed?.devDependencies
+      if (!devDeps || typeof devDeps !== 'object' || Array.isArray(devDeps)) {
+        return true
+      }
+      return !Object.hasOwn(devDeps, 'vite')
+    } catch {
+      return false
+    }
+  }
+
+  /**
+   * Рекурсивний обхід каталогу з пропуском службових директорій.
+   * @param {string} dir абсолютний шлях каталогу
+   * @returns {Promise<void>}
+   */
+  async function walk(dir) {
+    if (result) return
+    let entries
+    try {
+      entries = await readdir(dir, { withFileTypes: true })
+    } catch {
+      return
+    }
+    for (const entry of entries) {
+      if (result) return
+      const absPath = join(dir, entry.name)
+      if (entry.isDirectory()) {
+        if (!IGNORED_DIR_NAMES.has(entry.name)) {
+          await walk(absPath)
+        }
+        continue
+      }
+      if (entry.isFile() && entry.name === 'package.json' && absPath !== join(root, 'package.json')) {
+        if (await packageJsonLacksViteDevDependency(absPath)) {
+          result = true
+          return
+        }
+      }
+    }
+  }
+
+  await walk(root)
+  return result
+}
+
 /**
  * Фіксує ознаки, що залежать лише від імені підкаталогу.
  * @param {string} dirName імʼя каталогу
@@ -438,6 +500,7 @@ export async function detectAutoRulesAndSkills({
   const depHits = await collectDependencyKeysPresentInPackageJsonTree(root, ['mssql', 'pg', 'pg-format', 'mysql2'])
   const hasMssqlDependency = depHits.has('mssql')
   const hasJsBunDbSignal = depHits.has('pg') || depHits.has('pg-format') || depHits.has('mysql2') || facts.hasBunSqlImport
+  const hasNestedNodePackage = await hasNestedPackageJsonWithoutViteDevDependency(root)
 
   /** @type {string[]} */
   const detectedRules = []
@@ -478,7 +541,7 @@ export async function detectAutoRulesAndSkills({
     { enabled: facts.hasJsLikeSource, id: 'js-lint' },
     { enabled: hasMssqlDependency, id: 'js-mssql' },
     { enabled: hasJsBunDbSignal, id: 'js-bun-db' },
-    { enabled: facts.hasJsLikeSource && !(isMonorepo && facts.hasVueSource && facts.hasTempoDir), id: 'js-pino' },
+    { enabled: hasNestedNodePackage, id: 'js-run' },
     { enabled: facts.hasK8sDir, id: 'k8s' },
     { enabled: facts.hasNginxDefaultTplFile, id: 'nginx-default-tpl' },
     { enabled: npmDirExists, id: 'npm-module' },

package/scripts/check-js-lint.mjs

@@ -7,7 +7,7 @@
  * globals, ignorePatterns. `@nitra/eslint-config` у devDependencies мінімум **3.6.12** (транзитивний
  * `@e18e/eslint-plugin` для oxlint), `.jscpd.json` (gitignore, exitCode, reporters, minLines), workflow
  * `lint-js.yml` (checkout@v6, setup-bun-deps, bunx без --fix), без prettier, `engines.node` >= 24,
- * `"type": "module"` у кореневому і всіх workspace `package.json`. Дубль перевірки JS у `lint.yml` — заборонено.
+ * `engines.bun` >= 1.3, `"type": "module"` у кореневому і всіх workspace `package.json`. Дубль перевірки JS у `lint.yml` — заборонено.
  */
 import { existsSync } from 'node:fs'
 import { readFile } from 'node:fs/promises'
@@ -264,38 +264,62 @@ function checkPackageJsonTypeModule(label, pkg, passFn, failFn) {
 }
 
 /**
- * `"type": "module"` у кожного workspace з package.json.
+ * `"type": "module"`, `engines.node >= 24` і `engines.bun >= 1.3` у кожному workspace `package.json`.
  * @param {unknown[]} workspaces поле workspaces з package.json
  * @param {(msg: string) => void} passFn callback при успішній перевірці
  * @param {(msg: string) => void} failFn callback при помилці
  */
-async function checkWorkspacePackagesTypeModule(workspaces, passFn, failFn) {
+async function checkWorkspacePackages(workspaces, passFn, failFn) {
   for (const ws of workspaces) {
     const wsPkgPath = `${ws}/package.json`
     if (existsSync(wsPkgPath)) {
       const wsPkg = JSON.parse(await readFile(wsPkgPath, 'utf8'))
       checkPackageJsonTypeModule(wsPkgPath, wsPkg, passFn, failFn)
+      checkEnginesNode(wsPkgPath, wsPkg, passFn, failFn)
+      checkEnginesBun(wsPkgPath, wsPkg, passFn, failFn)
     }
   }
 }
 
 /**
  * engines.node >= 24.
+ * @param {string} label шлях або назва пакета для повідомлень
  * @param {{ engines?: { node?: string } }} pkg розпарсений package.json
  * @param {(msg: string) => void} passFn callback при успішній перевірці
  * @param {(msg: string) => void} failFn callback при помилці
  */
-function checkEnginesNode(pkg, passFn, failFn) {
+function checkEnginesNode(label, pkg, passFn, failFn) {
   const nodeEngine = pkg.engines?.node
   if (nodeEngine) {
     const firstNumeric = String(nodeEngine).split(NON_DIGITS_RE).find(Boolean)
     if (firstNumeric && Number(firstNumeric) >= 24) {
-      passFn(`engines.node: "${nodeEngine}"`)
+      passFn(`${label}: engines.node "${nodeEngine}"`)
+    } else {
+      failFn(`${label}: engines.node "${nodeEngine}" — має бути >=24`)
+    }
+  } else {
+    failFn(`${label} не містить engines.node — додай: "engines": { "node": ">=24" }`)
+  }
+}
+
+/**
+ * engines.bun >= 1.3.
+ * @param {string} label шлях або назва пакета для повідомлень
+ * @param {{ engines?: { bun?: string } }} pkg розпарсений package.json
+ * @param {(msg: string) => void} passFn callback при успішній перевірці
+ * @param {(msg: string) => void} failFn callback при помилці
+ */
+function checkEnginesBun(label, pkg, passFn, failFn) {
+  const bunEngine = pkg.engines?.bun
+  if (bunEngine) {
+    const [major, minor] = String(bunEngine).split(NON_DIGITS_RE).filter(Boolean).map(Number)
+    if (Number.isFinite(major) && Number.isFinite(minor) && (major > 1 || (major === 1 && minor >= 3))) {
+      passFn(`${label}: engines.bun "${bunEngine}"`)
     } else {
-      failFn(`engines.node: "${nodeEngine}" — має бути >=24`)
+      failFn(`${label}: engines.bun "${bunEngine}" — має бути >=1.3`)
     }
   } else {
-    failFn('package.json не містить engines.node — додай: "engines": { "node": ">=24" }')
+    failFn(`${label} не містить engines.bun — додай: "engines": { "bun": ">=1.3" }`)
   }
 }
 
@@ -311,7 +335,7 @@ async function checkPackageJsonJsLint(passFn, failFn) {
   checkPackageJsonTypeModule('package.json', pkg, passFn, failFn)
 
   const workspaces = Array.isArray(pkg.workspaces) ? pkg.workspaces : []
-  await checkWorkspacePackagesTypeModule(workspaces, passFn, failFn)
+  await checkWorkspacePackages(workspaces, passFn, failFn)
 
   const lintJs = pkg.scripts?.['lint-js']
   if (lintJs) {
@@ -328,7 +352,8 @@ async function checkPackageJsonJsLint(passFn, failFn) {
   }
 
   checkPackageJsonLintDeps(pkg, passFn, failFn)
-  checkEnginesNode(pkg, passFn, failFn)
+  checkEnginesNode('package.json', pkg, passFn, failFn)
+  checkEnginesBun('package.json', pkg, passFn, failFn)
 }
 
 /**

package/scripts/check-js-run.mjs

@@ -0,0 +1,227 @@
+/**
+ * Для кожного workspace-пакета перевіряє правило js-run.mdc.
+ *
+ * Покрито:
+ *  - заборона `@nitra/bunyan` / `bunyan` як у залежностях `package.json`, так і в коді
+ *    (`import` / `require` / динамічний `import()`); імпорти сканує AST через `oxc-parser`
+ *    (див. `utils/bunyan-imports.mjs`);
+ *  - наявність `OTEL_RESOURCE_ATTRIBUTES` зі значеннями `service.name=` та `service.namespace=`
+ *    у `k8s/base/configmap.yaml`, якщо такий файл існує (відповідність імені ConfigMap імені
+ *    Deployment перевіряється в `check-k8s.mjs`);
+ *  - «Внутрішні аліаси» (`#conn/*`): імпорти `bun#SQL`, будь-який `mssql`, `@nitra/graphql-request#GraphQLClient`
+ *    дозволені лише у каталозі conn (за замовчуванням `src/conn/`; за наявності
+ *    `package.json#imports['#conn/*']` — у його цільовому каталозі); поза ним — порушення
+ *    (див. `utils/conn-imports-scan.mjs`);
+ *  - «CheckEnv»: кожне `process.env.X` (включно з `process.env['X']` і деструктуризацією
+ *    `const { X } = process.env`) має бути закрите літеральним викликом `checkEnv(['X', ...])`
+ *    у тому ж файлі або коментарем `// @nitra/cursor ignore-next-line checkEnv` на попередньому
+ *    рядку (див. `utils/check-env-scan.mjs`).
+ */
+import { existsSync } from 'node:fs'
+import { readFile } from 'node:fs/promises'
+import { join, relative } from 'node:path'
+
+import {
+  findBunyanImportsInText,
+  isBunyanScanSourceFile,
+  shouldSkipFileForBunyanScan
+} from './utils/bunyan-imports.mjs'
+import { findUncheckedProcessEnvInText, isCheckEnvScanSourceFile } from './utils/check-env-scan.mjs'
+import { createCheckReporter } from './utils/check-reporter.mjs'
+import {
+  findConnFactoryImportsInText,
+  isConnImportsScanSourceFile,
+  isInsideConnDir,
+  resolveConnDirFromPackageJson
+} from './utils/conn-imports-scan.mjs'
+import { walkDir } from './utils/walkDir.mjs'
+import { getMonorepoPackageRootDirs } from './utils/workspaces.mjs'
+
+/**
+ * Перетворює абсолютний шлях у posix-формі відносно кореня пакета.
+ * @param {string} absPackageRoot абсолютний корінь пакета
+ * @param {string} absPath абсолютний шлях до файлу
+ * @returns {string} відносний posix-шлях
+ */
+function relPosix(absPackageRoot, absPath) {
+  return relative(absPackageRoot, absPath).split('\\').join('/')
+}
+
+/**
+ * Сканує джерела пакета на заборонені імпорти `@nitra/bunyan` / `bunyan`.
+ * @param {string} absPackageRoot абсолютний шлях до кореня пакета
+ * @param {string} label префікс повідомлення `[<pkg>] `
+ * @param {(msg: string) => void} fail callback при помилці
+ * @returns {Promise<number>} кількість знайдених порушень
+ */
+async function checkBunyanImports(absPackageRoot, label, fail) {
+  /** @type {string[]} */
+  const sourcePaths = []
+  await walkDir(absPackageRoot, absPath => {
+    const rel = relPosix(absPackageRoot, absPath)
+    if (!shouldSkipFileForBunyanScan(rel) && isBunyanScanSourceFile(rel)) {
+      sourcePaths.push(absPath)
+    }
+  })
+
+  let violations = 0
+  for (const absPath of sourcePaths) {
+    const rel = relPosix(absPackageRoot, absPath)
+    const content = await readFile(absPath, 'utf8')
+    for (const v of findBunyanImportsInText(content, rel)) {
+      violations++
+      fail(`${label}${rel}:${v.line} — заміни '${v.module}' на '@nitra/pino': ${v.snippet}`)
+    }
+  }
+  return violations
+}
+
+/**
+ * Збирає всі JS/TS-файли пакета (без node_modules, dist тощо).
+ * @param {string} absPackageRoot абсолютний шлях до кореня пакета
+ * @returns {Promise<string[]>} абсолютні шляхи до файлів
+ */
+async function collectSourceFiles(absPackageRoot) {
+  /** @type {string[]} */
+  const out = []
+  await walkDir(absPackageRoot, absPath => {
+    const rel = relPosix(absPackageRoot, absPath)
+    if (isCheckEnvScanSourceFile(rel)) out.push(absPath)
+  })
+  return out
+}
+
+/**
+ * Перевіряє правило «Внутрішні аліаси» для пакета.
+ * @param {string} absPackageRoot абсолютний корінь пакета
+ * @param {string[]} sourcePaths абсолютні шляхи до файлів
+ * @param {unknown} pkgJson розпарсений `package.json` пакета (або null)
+ * @param {string} label префікс повідомлення `[<pkg>] `
+ * @param {(msg: string) => void} fail callback при помилці
+ * @returns {Promise<number>} кількість порушень
+ */
+async function checkConnImports(absPackageRoot, sourcePaths, pkgJson, label, fail) {
+  const connDir = resolveConnDirFromPackageJson(pkgJson)
+  let violations = 0
+  for (const absPath of sourcePaths) {
+    const rel = relPosix(absPackageRoot, absPath)
+    if (!isConnImportsScanSourceFile(rel)) continue
+    if (isInsideConnDir(rel, connDir)) continue
+    const content = await readFile(absPath, 'utf8')
+    for (const v of findConnFactoryImportsInText(content, rel)) {
+      violations++
+      const target = v.specifier === '*' ? `'${v.module}'` : `{ ${v.specifier} } from '${v.module}'`
+      fail(
+        `${label}${rel}:${v.line} — імпорт ${target} має бути в '${connDir}/' і реекспортуватися через '#conn/*': ${v.snippet}`
+      )
+    }
+  }
+  return violations
+}
+
+/**
+ * Перевіряє правило «CheckEnv» для пакета.
+ * @param {string} absPackageRoot абсолютний корінь пакета
+ * @param {string[]} sourcePaths абсолютні шляхи до файлів
+ * @param {string} label префікс повідомлення `[<pkg>] `
+ * @param {(msg: string) => void} fail callback при помилці
+ * @returns {Promise<number>} кількість порушень
+ */
+async function checkProcessEnvUsage(absPackageRoot, sourcePaths, label, fail) {
+  let violations = 0
+  for (const absPath of sourcePaths) {
+    const rel = relPosix(absPackageRoot, absPath)
+    const content = await readFile(absPath, 'utf8')
+    for (const v of findUncheckedProcessEnvInText(content, rel)) {
+      violations++
+      fail(
+        `${label}${rel}:${v.line} — process.env.${v.name} без checkEnv(['${v.name}']) (або '// @nitra/cursor ignore-next-line checkEnv' попереду)`
+      )
+    }
+  }
+  return violations
+}
+
+/**
+ * Перевіряє відповідність правилам js-run.mdc для одного workspace-пакета.
+ * @param {string} rootDir відносний шлях workspace (не `'.'`)
+ * @param {(msg: string) => void} fail функція зворотного виклику для реєстрації помилки перевірки
+ * @param {(msg: string) => void} passFn успішне повідомлення (як у check-reporter)
+ * @returns {Promise<void>} завершується після перевірок цього пакета
+ */
+async function checkWorkspacePackage(rootDir, fail, passFn) {
+  const label = `[${rootDir}] `
+  const absPackageRoot = join(process.cwd(), rootDir)
+  /** @type {unknown} */
+  let pkgJson = null
+  const pkgPath = join(rootDir, 'package.json')
+  if (existsSync(pkgPath)) {
+    pkgJson = JSON.parse(await readFile(pkgPath, 'utf8'))
+    const deps = /** @type {Record<string, unknown>} */ (pkgJson).dependencies
+    const devDeps = /** @type {Record<string, unknown>} */ (pkgJson).devDependencies
+    const allDeps = { ...(deps || {}), ...(devDeps || {}) }
+
+    if (allDeps['@nitra/bunyan']) {
+      fail(`${label}@nitra/bunyan знайдено — замінити на @nitra/pino`)
+    }
+    if (allDeps.bunyan) {
+      fail(`${label}bunyan знайдено — замінити на @nitra/pino`)
+    }
+  }
+
+  const importViolations = await checkBunyanImports(absPackageRoot, label, fail)
+  if (importViolations === 0) {
+    passFn(`${label}немає імпортів '@nitra/bunyan' / 'bunyan' у джерелах`)
+  }
+
+  const sourcePaths = await collectSourceFiles(absPackageRoot)
+
+  const connViolations = await checkConnImports(absPackageRoot, sourcePaths, pkgJson, label, fail)
+  if (connViolations === 0) {
+    const connDir = resolveConnDirFromPackageJson(pkgJson)
+    passFn(`${label}імпорти підключень (bun#SQL / mssql / @nitra/graphql-request#GraphQLClient) лише в '${connDir}/'`)
+  }
+
+  const envViolations = await checkProcessEnvUsage(absPackageRoot, sourcePaths, label, fail)
+  if (envViolations === 0) {
+    passFn(`${label}усі process.env.* закриті checkEnv(['…']) або '// @nitra/cursor ignore-next-line checkEnv'`)
+  }
+
+  const configmapPath = join(rootDir, 'k8s', 'base', 'configmap.yaml')
+  if (existsSync(configmapPath)) {
+    const content = await readFile(configmapPath, 'utf8')
+    if (content.includes('OTEL_RESOURCE_ATTRIBUTES')) {
+      passFn(`${label}k8s/base/configmap.yaml містить OTEL_RESOURCE_ATTRIBUTES`)
+      if (content.includes('service.name=') && content.includes('service.namespace=')) {
+        passFn(`${label}OTEL_RESOURCE_ATTRIBUTES містить service.name та service.namespace`)
+      } else {
+        fail(`${label}OTEL_RESOURCE_ATTRIBUTES має містити service.name=<name>,service.namespace=<namespace>`)
+      }
+    } else {
+      fail(`${label}k8s/base/configmap.yaml не містить OTEL_RESOURCE_ATTRIBUTES`)
+    }
+  }
+}
+
+/**
+ * Перевіряє відповідність проєкту правилам js-run.mdc лише для workspace-пакетів (не корінь репо).
+ * @returns {Promise<number>} 0 — все OK, 1 — є проблеми
+ */
+export async function check() {
+  const reporter = createCheckReporter()
+  const { pass, fail } = reporter
+
+  const roots = await getMonorepoPackageRootDirs()
+  const workspaceRoots = roots.filter(r => r !== '.')
+
+  if (workspaceRoots.length === 0) {
+    pass('js-run: немає workspace-пакетів у кореневому package.json — перевірку залежностей і k8s у пакетах пропущено')
+    return reporter.getExitCode()
+  }
+
+  for (const r of workspaceRoots) {
+    await checkWorkspacePackage(r, fail, pass)
+  }
+
+  return reporter.getExitCode()
+}

package/scripts/check-k8s.mjs

@@ -2594,7 +2594,7 @@ async function readFirstDocByKindFromFile(filePath, kind) {
 }
 
 /**
- * Знаходить перший документ **Deployment** серед YAML-файлів каталогу (для перевірки імені ConfigMap, js-pino.mdc).
+ * Знаходить перший документ **Deployment** серед YAML-файлів каталогу (для перевірки імені ConfigMap, js-run.mdc).
  * @param {string} dirPath абсолютний шлях до каталогу
  * @returns {Promise<Record<string, unknown> | null>} об'єкт Deployment або null
  */
@@ -2678,7 +2678,7 @@ function collectConfigMapRefsFromVolumes(volumes, names) {
 /**
  * Збирає унікальні імена **ConfigMap**, на які посилається **Deployment**
  * через `spec.template.spec.containers[*].envFrom[*].configMapRef.name`
- * та `spec.template.spec.volumes[*].configMap.name` (для перевірки js-pino.mdc).
+ * та `spec.template.spec.volumes[*].configMap.name` (для перевірки js-run.mdc).
  * @param {Record<string, unknown>} deployment об'єкт Deployment
  * @returns {Set<string>} унікальні імена ConfigMap
  */

package/scripts/utils/bunyan-imports.mjs

@@ -1,6 +1,6 @@
 /**
  * Знаходить імпорти з `@nitra/bunyan` (і застарілого `bunyan`) у джерелах — їх треба замінити
- * на `@nitra/pino` згідно з js-pino.mdc.
+ * на `@nitra/pino` згідно з js-run.mdc.
  *
  * Семантика береться з **oxc-parser** (`module.staticImports`) — без regex по тілу файлу.
  * Додатково по AST програми ловимо `require('@nitra/bunyan')` і динамічний `import('@nitra/bunyan')`,

package/scripts/utils/check-env-scan.mjs

@@ -0,0 +1,179 @@
+/**
+ * AST-сканер для правила CheckEnv (js-run.mdc).
+ *
+ * Кожне використання `process.env.X` у JS/TS-коді має бути «закрите» одним з двох способів:
+ *  - перед використанням у тому ж файлі викликано `checkEnv(['X', ...])` з пакету `@nitra/check-env`;
+ *  - на рядку безпосередньо перед `process.env.X` стоїть коментар-маркер
+ *    `// @nitra/cursor ignore-next-line checkEnv` (роздільники пробілів довільні; саме слово
+ *    `checkEnv` чутливе до регістру, як в усіх прикладах документа).
+ *
+ * Семантика береться з **oxc-parser** через `parseProgramOrNull`: regex по тілу файлу не
+ * використовується, лише сирий текст рядка з коментарем перевіряється на маркер. Якщо
+ * файл не парситься — повертаємо порожній результат, спочатку треба полагодити синтаксис.
+ *
+ * Покриті форми доступу до `process.env`:
+ *  - `process.env.X` (звичайний MemberExpression);
+ *  - `process.env['X']` (computed з рядковим літералом);
+ *  - `const { X, Y } = process.env` (ObjectPattern; ім'я з ключа);
+ *  - `const { X: alias } = process.env` (ім'я з ключа, не з alias).
+ *
+ * Якщо ключ обчислюваний (наприклад, `process.env[varName]`) — пропускаємо без помилки,
+ * бо за статичним AST неможливо встановити, яка саме змінна оточення використовується.
+ */
+import { offsetToLine, parseProgramOrNull, walkAstWithAncestors } from './ast-scan-utils.mjs'
+
+const SOURCE_FILE_RE = /\.([cm]?[jt]sx?)$/u
+const IGNORE_DIRECTIVE_RE = /\/\/\s*@nitra\/cursor\s+ignore-next-line\s+checkEnv\b/u
+
+/**
+ * Чи є цей вузол виразом `process.env`.
+ * @param {unknown} node AST вузол
+ * @returns {boolean} true, якщо це `MemberExpression` `process.env` (Identifier . Identifier)
+ */
+function isProcessEnvAccess(node) {
+  if (!node || typeof node !== 'object') return false
+  if (node.type !== 'MemberExpression' || node.computed) return false
+  const obj = node.object
+  const prop = node.property
+  return (
+    !!obj &&
+    obj.type === 'Identifier' &&
+    obj.name === 'process' &&
+    !!prop &&
+    prop.type === 'Identifier' &&
+    prop.name === 'env'
+  )
+}
+
+/**
+ * Витягує ім'я ENV з MemberExpression-вузла `process.env.X` або `process.env['X']`.
+ * @param {Record<string, unknown>} node MemberExpression, чий object — `process.env`
+ * @returns {string | null} ім'я змінної оточення або null, якщо ключ не статичний
+ */
+function envNameFromMember(node) {
+  const prop = node.property
+  if (!prop || typeof prop !== 'object') return null
+  if (!node.computed && prop.type === 'Identifier' && typeof prop.name === 'string') return prop.name
+  if (node.computed && prop.type === 'Literal' && typeof prop.value === 'string') return prop.value
+  return null
+}
+
+/**
+ * Збирає всі літеральні імена з виклику `checkEnv([...])` у файлі.
+ * Якщо callee — Identifier `checkEnv` і перший аргумент — ArrayExpression, додає
+ * всі string-літерали до set. Не-літеральні елементи (Identifier, SpreadElement) ігноруються —
+ * це робить перевірку «ліберальною»: ми лише ловимо явно неперевірені змінні.
+ * @param {unknown} programNode корінь AST
+ * @returns {Set<string>} перелік закритих імен ENV
+ */
+function collectCheckedEnvNames(programNode) {
+  /** @type {Set<string>} */
+  const out = new Set()
+  walkAstWithAncestors(programNode, [], node => {
+    if (node.type !== 'CallExpression') return
+    const callee = node.callee
+    if (!callee || callee.type !== 'Identifier' || callee.name !== 'checkEnv') return
+    const args = node.arguments
+    if (!Array.isArray(args) || args.length === 0) return
+    const first = args[0]
+    if (!first || typeof first !== 'object' || first.type !== 'ArrayExpression') return
+    const elements = first.elements
+    if (!Array.isArray(elements)) return
+    for (const el of elements) {
+      if (!el || typeof el !== 'object') continue
+      if (el.type === 'Literal' && typeof el.value === 'string') out.add(el.value)
+    }
+  })
+  return out
+}
+
+/**
+ * Чи закритий рядок ignore-коментарем `// @nitra/cursor ignore-next-line checkEnv`.
+ * @param {string[]} lines рядки файлу (split за \n, без CR)
+ * @param {number} oneBasedLine 1-based номер рядка з `process.env.X`
+ * @returns {boolean} true, якщо попередній рядок містить маркер
+ */
+function hasIgnoreDirective(lines, oneBasedLine) {
+  if (oneBasedLine <= 1) return false
+  const prev = lines[oneBasedLine - 2] ?? ''
+  return IGNORE_DIRECTIVE_RE.test(prev)
+}
+
+/**
+ * Знаходить всі доступи до `process.env.<NAME>`, які не покриті ні літеральним
+ * `checkEnv([...])` у тому ж файлі, ні коментарем-маркером безпосередньо перед.
+ *
+ * @param {string} content вихідний код
+ * @param {string} [virtualPath] шлях для вибору `lang` парсера
+ * @returns {{ line: number, name: string }[]} список порушень
+ */
+export function findUncheckedProcessEnvInText(content, virtualPath = 'scan.ts') {
+  const program = parseProgramOrNull(content, virtualPath)
+  if (!program) return []
+
+  const checked = collectCheckedEnvNames(program)
+  const lines = content.split('\n').map(s => (s.endsWith('\r') ? s.slice(0, -1) : s))
+
+  /** @type {{ line: number, name: string }[]} */
+  const out = []
+  /** @type {Set<string>} */
+  const reported = new Set()
+
+  /**
+   * Реєструє порушення з дедуплікацією за «name@line».
+   * @param {string} name ім'я ENV
+   * @param {number} line 1-based рядок
+   */
+  function report(name, line) {
+    if (checked.has(name)) return
+    if (hasIgnoreDirective(lines, line)) return
+    const key = `${name}@${line}`
+    if (reported.has(key)) return
+    reported.add(key)
+    out.push({ name, line })
+  }
+
+  walkAstWithAncestors(program, [], (node, ancestors) => {
+    if (isProcessEnvAccess(node)) {
+      const parent = ancestors[ancestors.length - 1]
+      // process.env.X / process.env['X']
+      if (parent && typeof parent === 'object' && parent.type === 'MemberExpression' && parent.object === node) {
+        const envName = envNameFromMember(parent)
+        if (envName) report(envName, offsetToLine(content, parent.start))
+      }
+      // const { X, Y } = process.env  → беремо імена з ObjectPattern
+      if (
+        parent &&
+        typeof parent === 'object' &&
+        parent.type === 'VariableDeclarator' &&
+        parent.init === node &&
+        parent.id &&
+        parent.id.type === 'ObjectPattern' &&
+        Array.isArray(parent.id.properties)
+      ) {
+        for (const p of parent.id.properties) {
+          if (!p || typeof p !== 'object' || p.type !== 'Property') continue
+          if (p.computed) continue
+          const key = p.key
+          if (!key || typeof key !== 'object') continue
+          /** @type {string | null} */
+          let name = null
+          if (key.type === 'Identifier' && typeof key.name === 'string') name = key.name
+          else if (key.type === 'Literal' && typeof key.value === 'string') name = key.value
+          if (name) report(name, offsetToLine(content, p.start ?? parent.start))
+        }
+      }
+    }
+  })
+
+  return out
+}
+
+/**
+ * Чи сканувати цей файл за розширенням (JS/TS-сім'я, без `.d.ts`).
+ * @param {string} relativePathPosix відносний шлях (posix)
+ * @returns {boolean} true, якщо розширення підходить для AST-скану
+ */
+export function isCheckEnvScanSourceFile(relativePathPosix) {
+  return SOURCE_FILE_RE.test(relativePathPosix) && !relativePathPosix.endsWith('.d.ts')
+}

package/scripts/utils/conn-imports-scan.mjs

@@ -0,0 +1,144 @@
+/**
+ * AST-сканер для правила «Внутрішні аліаси» (js-run.mdc).
+ *
+ * Імпорти, які створюють підключення до БД / зовнішнього GraphQL, мають жити в окремому
+ * файлі (за замовчуванням — `src/conn/`), а решта коду повинна споживати їх через
+ * pkg-import `#conn/...`. Ловимо такі імпорти в файлах поза каталогом «conn»:
+ *  - `import { SQL } from 'bun'` (named специфікатор `SQL`);
+ *  - `import sql from 'mssql'` або будь-який `import ... from 'mssql'`;
+ *  - `import { GraphQLClient } from '@nitra/graphql-request'` (named `GraphQLClient`).
+ *
+ * Каталог «conn» визначається з поля `package.json#imports['#conn/*']` (якщо є —
+ * відрізаємо `*` і нормалізуємо), інакше дефолт — `src/conn`. Ключ `imports` у
+ * package.json — нативний для Node.js, той самий, що й у документі правила.
+ *
+ * Семантика береться з **oxc-parser** (`module.staticImports`); regex по тілу файлу не
+ * використовується. Якщо файл не парситься — повертаємо порожній результат, спочатку
+ * треба полагодити синтаксис.
+ */
+import { langFromPath, normalizeSnippet, offsetToLine } from './ast-scan-utils.mjs'
+import { parseSync } from 'oxc-parser'
+
+const SOURCE_FILE_RE = /\.([cm]?[jt]sx?)$/u
+const TRAILING_SLASH_RE = /\/+$/u
+
+/**
+ * Нормалізує шлях до posix без хвостових слешів.
+ * @param {string} p вхідний шлях (можливо з `./` або зворотними слешами)
+ * @returns {string} нормалізований posix-шлях без хвостового `/`
+ */
+function toPosixDir(p) {
+  let s = String(p).replaceAll('\\', '/').trim()
+  if (s.startsWith('./')) s = s.slice(2)
+  return s.replace(TRAILING_SLASH_RE, '')
+}
+
+/**
+ * Визначає каталог «conn» за `package.json#imports['#conn/*']`. Дефолт — `src/conn`.
+ * @param {unknown} pkgJson розпарсений package.json (або null)
+ * @returns {string} відносний posix-шлях до каталогу conn (без хвостового `/`)
+ */
+export function resolveConnDirFromPackageJson(pkgJson) {
+  const fallback = 'src/conn'
+  if (!pkgJson || typeof pkgJson !== 'object') return fallback
+  const imports = /** @type {Record<string, unknown>} */ (pkgJson).imports
+  if (!imports || typeof imports !== 'object') return fallback
+  const target = /** @type {Record<string, unknown>} */ (imports)['#conn/*']
+  /** @type {string | null} */
+  let raw = null
+  if (typeof target === 'string') raw = target
+  else if (target && typeof target === 'object') {
+    // умовний експорт: { default: '...', import: '...' }
+    const obj = /** @type {Record<string, unknown>} */ (target)
+    if (typeof obj.default === 'string') raw = obj.default
+    else if (typeof obj.import === 'string') raw = obj.import
+  }
+  if (!raw) return fallback
+  // Прибираємо хвіст `*`, потім слеші
+  let s = toPosixDir(raw)
+  if (s.endsWith('/*')) s = s.slice(0, -2)
+  return s.replace(TRAILING_SLASH_RE, '') || fallback
+}
+
+/**
+ * Чи перебуває файл у каталозі conn (точно або вкладено).
+ * @param {string} relPosix відносний posix-шлях до файлу
+ * @param {string} connDir posix-шлях каталогу conn (без хвостового `/`)
+ * @returns {boolean} true, якщо файл у каталозі conn
+ */
+export function isInsideConnDir(relPosix, connDir) {
+  if (!connDir) return false
+  return relPosix === connDir || relPosix.startsWith(`${connDir}/`)
+}
+
+/**
+ * Чи це порушення правила «Внутрішні аліаси» — імпорт зі стороннього модуля, що створює
+ * підключення (`bun` зі специфікатором `SQL`, будь-який імпорт з `mssql`, або
+ * `@nitra/graphql-request` зі специфікатором `GraphQLClient`).
+ * @param {Record<string, unknown>} staticImport елемент `module.staticImports` з oxc-parser
+ * @returns {{ module: string, specifier: string } | null} опис порушення або null
+ */
+function classifyConnImport(staticImport) {
+  const mod = staticImport.moduleRequest?.value
+  if (typeof mod !== 'string') return null
+  const entries = Array.isArray(staticImport.entries) ? staticImport.entries : []
+
+  if (mod === 'bun') {
+    for (const e of entries) {
+      const name = e?.importName?.name
+      if (name === 'SQL') return { module: mod, specifier: 'SQL' }
+    }
+    return null
+  }
+  if (mod === 'mssql') {
+    return { module: mod, specifier: '*' }
+  }
+  if (mod === '@nitra/graphql-request') {
+    for (const e of entries) {
+      const name = e?.importName?.name
+      if (name === 'GraphQLClient') return { module: mod, specifier: 'GraphQLClient' }
+    }
+    return null
+  }
+  return null
+}
+
+/**
+ * Знаходить імпорти-«фабрики підключень» у тексті файлу.
+ * @param {string} content вихідний код
+ * @param {string} [virtualPath] шлях для вибору `lang` (наприклад `pkg/src/index.ts`)
+ * @returns {{ line: number, snippet: string, module: string, specifier: string }[]} список порушень
+ */
+export function findConnFactoryImportsInText(content, virtualPath = 'scan.ts') {
+  const lang = langFromPath(virtualPath || 'scan.ts')
+  let result
+  try {
+    result = parseSync(virtualPath || 'scan.ts', content, { lang, sourceType: 'module' })
+  } catch {
+    return []
+  }
+  if (result.errors?.length) return []
+
+  /** @type {{ line: number, snippet: string, module: string, specifier: string }[]} */
+  const out = []
+  for (const imp of result.module?.staticImports ?? []) {
+    const hit = classifyConnImport(imp)
+    if (!hit) continue
+    out.push({
+      line: offsetToLine(content, imp.start),
+      snippet: normalizeSnippet(content.slice(imp.start, imp.end)),
+      module: hit.module,
+      specifier: hit.specifier
+    })
+  }
+  return out
+}
+
+/**
+ * Чи сканувати цей файл за розширенням (JS/TS-сім'я, без `.d.ts`).
+ * @param {string} relativePathPosix відносний шлях (posix)
+ * @returns {boolean} true, якщо розширення підходить для AST-скану
+ */
+export function isConnImportsScanSourceFile(relativePathPosix) {
+  return SOURCE_FILE_RE.test(relativePathPosix) && !relativePathPosix.endsWith('.d.ts')
+}

package/mdc/js-pino.mdc

@@ -1,15 +0,0 @@
----
-description: Використання @nitra/pino
-alwaysApply: true
-version: '1.1'
----
-
-Проект використовує @nitra/pino для логування.
-Якщо в проекті присутній @nitra/bunyan, то він повинен бути замінений на @nitra/pino — як у `package.json`, так і в коді: усі `import` / `require` / динамічні `import()` з `@nitra/bunyan` (і застарілого `bunyan`) треба замінити на `@nitra/pino` і за потреби адаптувати виклики під його API.
-
-В **/k8s/base/configmap.yaml повинен бути заданий OTEL_RESOURCE_ATTRIBUTES: 'service.name=<project_name>,service.namespace=<project_namespace>'
-а в директоріях з kustomize повинні бути перевизначені значення OTEL_RESOURCE_ATTRIBUTES і в них service.namespace повинен відповідати namespace, в якому знаходиться дана директорія.
-
-## Перевірка
-
-`npx @nitra/cursor check js-pino`

package/scripts/check-js-pino.mjs

@@ -1,120 +0,0 @@
-/**
- * Для кожного workspace-пакета перевіряє правило js-pino.mdc.
- *
- * Заборона `@nitra/bunyan` / `bunyan` як у залежностях `package.json`, так і в коді
- * (`import` / `require` / динамічний `import()`); наявність `OTEL_RESOURCE_ATTRIBUTES`
- * у `k8s/base/configmap.yaml`, якщо такий файл існує.
- *
- * Перевірка відповідності імені ConfigMap імені Deployment — у `check-k8s.mjs` (k8s.mdc).
- *
- * Імпорти в джерелах сканує AST через `oxc-parser` (див. `utils/bunyan-imports.mjs`),
- * щоб виявити випадки на кшталт `import log from '@nitra/bunyan'`, які лишаються в коді
- * після підміни залежності.
- */
-import { existsSync } from 'node:fs'
-import { readFile } from 'node:fs/promises'
-import { join, relative } from 'node:path'
-
-import {
-  findBunyanImportsInText,
-  isBunyanScanSourceFile,
-  shouldSkipFileForBunyanScan
-} from './utils/bunyan-imports.mjs'
-import { createCheckReporter } from './utils/check-reporter.mjs'
-import { walkDir } from './utils/walkDir.mjs'
-import { getMonorepoPackageRootDirs } from './utils/workspaces.mjs'
-
-/**
- * Сканує джерела пакета на заборонені імпорти `@nitra/bunyan` / `bunyan`.
- * @param {string} absPackageRoot абсолютний шлях до кореня пакета
- * @param {string} label префікс повідомлення `[<pkg>] `
- * @param {(msg: string) => void} fail callback при помилці
- * @returns {Promise<number>} кількість знайдених порушень
- */
-async function checkBunyanImports(absPackageRoot, label, fail) {
-  /** @type {string[]} */
-  const sourcePaths = []
-  await walkDir(absPackageRoot, absPath => {
-    const rel = relative(absPackageRoot, absPath).split('\\').join('/')
-    if (!shouldSkipFileForBunyanScan(rel) && isBunyanScanSourceFile(rel)) {
-      sourcePaths.push(absPath)
-    }
-  })
-
-  let violations = 0
-  for (const absPath of sourcePaths) {
-    const rel = relative(absPackageRoot, absPath).split('\\').join('/')
-    const content = await readFile(absPath, 'utf8')
-    for (const v of findBunyanImportsInText(content, rel)) {
-      violations++
-      fail(`${label}${rel}:${v.line} — заміни '${v.module}' на '@nitra/pino': ${v.snippet}`)
-    }
-  }
-  return violations
-}
-
-/**
- * Перевіряє відповідність правилам js-pino.mdc для одного workspace-пакета.
- * @param {string} rootDir відносний шлях workspace (не `'.'`)
- * @param {(msg: string) => void} fail функція зворотного виклику для реєстрації помилки перевірки
- * @param {(msg: string) => void} passFn успішне повідомлення (як у check-reporter)
- * @returns {Promise<void>} завершується після перевірок цього пакета
- */
-async function checkWorkspacePackage(rootDir, fail, passFn) {
-  const label = `[${rootDir}] `
-  const pkgPath = join(rootDir, 'package.json')
-  if (existsSync(pkgPath)) {
-    const pkg = JSON.parse(await readFile(pkgPath, 'utf8'))
-    const allDeps = { ...pkg.dependencies, ...pkg.devDependencies }
-
-    if (allDeps['@nitra/bunyan']) {
-      fail(`${label}@nitra/bunyan знайдено — замінити на @nitra/pino`)
-    }
-    if (allDeps.bunyan) {
-      fail(`${label}bunyan знайдено — замінити на @nitra/pino`)
-    }
-  }
-
-  const importViolations = await checkBunyanImports(join(process.cwd(), rootDir), label, fail)
-  if (importViolations === 0) {
-    passFn(`${label}немає імпортів '@nitra/bunyan' / 'bunyan' у джерелах`)
-  }
-
-  const configmapPath = join(rootDir, 'k8s', 'base', 'configmap.yaml')
-  if (existsSync(configmapPath)) {
-    const content = await readFile(configmapPath, 'utf8')
-    if (content.includes('OTEL_RESOURCE_ATTRIBUTES')) {
-      passFn(`${label}k8s/base/configmap.yaml містить OTEL_RESOURCE_ATTRIBUTES`)
-      if (content.includes('service.name=') && content.includes('service.namespace=')) {
-        passFn(`${label}OTEL_RESOURCE_ATTRIBUTES містить service.name та service.namespace`)
-      } else {
-        fail(`${label}OTEL_RESOURCE_ATTRIBUTES має містити service.name=<name>,service.namespace=<namespace>`)
-      }
-    } else {
-      fail(`${label}k8s/base/configmap.yaml не містить OTEL_RESOURCE_ATTRIBUTES`)
-    }
-  }
-}
-
-/**
- * Перевіряє відповідність проєкту правилам js-pino.mdc лише для workspace-пакетів (не корінь репо).
- * @returns {Promise<number>} 0 — все OK, 1 — є проблеми
- */
-export async function check() {
-  const reporter = createCheckReporter()
-  const { pass, fail } = reporter
-
-  const roots = await getMonorepoPackageRootDirs()
-  const workspaceRoots = roots.filter(r => r !== '.')
-
-  if (workspaceRoots.length === 0) {
-    pass('js-pino: немає workspace-пакетів у кореневому package.json — перевірку залежностей і k8s у пакетах пропущено')
-    return reporter.getExitCode()
-  }
-
-  for (const r of workspaceRoots) {
-    await checkWorkspacePackage(r, fail, pass)
-  }
-
-  return reporter.getExitCode()
-}