@nitra/cursor 1.8.155 → 1.8.157

package/CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog
+
+Усі помітні зміни цього модуля документуються тут.
+
+Формат — [Keep a Changelog](https://keepachangelog.com/uk/1.1.0/), нумерація — [SemVer](https://semver.org/lang/uk/).
+
+## [1.8.157] - 2026-04-30
+
+### Added
+
+- Правило `npm-module.mdc`: секція **CHANGELOG** — разом із bump build-версії в `npm/package.json` обовʼязково оновлювати `npm/CHANGELOG.md` (Keep a Changelog).
+- `check-npm-module.mjs`: перевірка наявності `npm/CHANGELOG.md`, наявності в `files` у `npm/package.json` і запису для поточної версії.
+- `check-hasura.mjs`: перевірка `HASURA_GRAPHQL_ENDPOINT` у `*.env` для проєктів **nitra** і **abie** — має бути внутрішнім кластерним URL виду `http://<service>.<namespace>.svc.<cluster>.internal:<port>`; за наявності `hasura/k8s/base/svc-hl.yaml` та `hasura/k8s/base/namespace.yaml` додатково звіряється `<service>` і `<namespace>`.
+
+### Changed
+
+- `npm/package.json`: `CHANGELOG.md` додано в масив `files`, щоб публікувався разом із пакетом.
+- `hasura.mdc`: текст правила переформульовано як людинозрозумілий з прикладом і посиланням на `check-hasura.mjs`.

package/bin/auto-rules.md

@@ -16,6 +16,8 @@ ga - якщо присутня директорія .github/workflows
 
 graphql - якщо хоч в одному js або vue файлі присутній gql` темплейт літерал
 
+hasura - якщо в директорії присутній config.yaml, який містить рядок `metadata_directory: metadata`
+
 js-lint - якщо присутній хоч один js файл
 
 js-run - якщо це вкладена директорія з package.json (не в корені) та в devDependencies немає vite

package/mdc/hasura.mdc

@@ -0,0 +1,31 @@
+---
+description: Правила для директорії з hasura graphql-engine
+alwaysApply: true
+version: '1.0'
+---
+
+## Підключення для оновлення метаданих у CI (Nitra та Abinbevefes)
+
+У `*.env` для атрибута `HASURA_GRAPHQL_ENDPOINT` підключення має бути **усередині кластера**, а не через публічний домен — інакше CI кладе метадані через зовнішній бекенд і ламає перевипуск/міграції.
+
+Приклад **неправильного** значення:
+
+```env
+HASURA_GRAPHQL_ENDPOINT=https://napitkivmeste.tech/contract/ql
+```
+
+Правильне значення:
+
+```env
+HASURA_GRAPHQL_ENDPOINT=http://contract-h.ua-contract.svc.abie-ua.internal:8080
+```
+
+де `contract-h` — це `metadata.name` сервісу з `hasura/k8s/base/svc-hl.yaml`, а `ua-contract` — `metadata.name` namespace з `hasura/k8s/base/namespace.yaml`.
+
+Правило застосовується для проєктів **nitra** (у кореневому `package.json` `"repository": "https://github.com/nitra/*"`) і **abie** (`"repository": "https://github.com/abinbevefes/*"`); для інших репозиторіїв перевірка пропускається.
+
+## Перевірка
+
+`npx @nitra/cursor check hasura`
+
+Деталі алгоритму — у `check-hasura.mjs`.

package/mdc/js-lint.mdc

@@ -1,10 +1,10 @@
 ---
 description: Перевірка JavaScript коду
 alwaysApply: true
-version: '1.15'
+version: '1.16'
 ---
 
-**oxlint**, **ESLint**, **jscpd**. У скрипті **`lint-js`** і в CI — **`bunx oxlint`**, **`bunx eslint`**, **`bunx jscpd`** (у CI без **`--fix`** для oxlint/eslint — див. приклад workflow нижче). Без **prettier** і **@nitra/prettier-config**. У **`devDependencies`** має бути **`@nitra/eslint-config` мінімум `^3.6.12`** (з ним транзитивно йде **`@e18e/eslint-plugin`** для oxlint); пакет **`@e18e/eslint-plugin`** окремо не додавай. Пакети oxlint/eslint/jscpd не додавай без потреби монорепо.
+**oxlint**, **ESLint**, **jscpd**. У скрипті **`lint-js`** і в CI — **`bunx oxlint`**, **`bunx eslint`**, **`bunx jscpd`** (у CI без **`--fix`** для oxlint/eslint — див. приклад workflow нижче). Без **prettier** і **@nitra/prettier-config**. У **`devDependencies`** має бути **`@nitra/eslint-config` мінімум `^3.8.0`** (з цієї версії правило `no-restricted-syntax` забороняє `for...in`; також транзитивно йде **`@e18e/eslint-plugin`** для oxlint); пакет **`@e18e/eslint-plugin`** окремо не додавай. Пакети oxlint/eslint/jscpd не додавай без потреби монорепо.
 
 ```json title=".vscode/extensions.json"
 {
@@ -25,12 +25,12 @@ version: '1.15'
     "lint-js": "bunx oxlint --fix && bunx eslint --fix . && bunx jscpd ."
   },
   "devDependencies": {
-    "@nitra/eslint-config": "^3.6.12"
+    "@nitra/eslint-config": "^3.8.0"
   }
 }
 ```
 
-У корені має бути **`.oxlintrc.json`**, який **збігається з каноном** oxlint з пакета **`@nitra/cursor`**: файл **`npm/scripts/utils/oxlint-canonical.json`** (plugins, jsPlugins з **`@e18e/eslint-plugin`**, categories, повний набір **rules** із канону — додаткові записи в **`rules`** дозволені; також **`settings`**, **`env`**, **`globals`**, **`ignorePatterns`**). Оновити можна з репозиторію пакета або скопіювавши файл після **`bun ./scripts/utils/rebuild-oxlint-canonical.mjs`** (джерело правил — **`oxlint-rules.tsv`** + скелет **`oxlint-canonical-skeleton.json`**). Модуль **`@e18e/eslint-plugin`** не оголошуй окремо в **`package.json`** — він уже в залежностях **`@nitra/eslint-config`** (з **3.6.12**), oxlint підвантажує його з **`node_modules`**.
+У корені має бути **`.oxlintrc.json`**, який **збігається з каноном** oxlint з пакета **`@nitra/cursor`**: файл **`npm/scripts/utils/oxlint-canonical.json`** (plugins, jsPlugins з **`@e18e/eslint-plugin`**, categories, повний набір **rules** із канону — додаткові записи в **`rules`** дозволені; також **`settings`**, **`env`**, **`globals`**, **`ignorePatterns`**). Оновити можна з репозиторію пакета або скопіювавши файл після **`bun ./scripts/utils/rebuild-oxlint-canonical.mjs`** (джерело правил — **`oxlint-rules.tsv`** + скелет **`oxlint-canonical-skeleton.json`**). Модуль **`@e18e/eslint-plugin`** не оголошуй окремо в **`package.json`** — він уже в залежностях **`@nitra/eslint-config`** (з **3.8.0**), oxlint підвантажує його з **`node_modules`**.
 
 Мінімум для розуміння структури (реальний корінь конфігу має збігатися з каноном повністю):
 
@@ -144,6 +144,31 @@ export default [
 }
 ```
 
+## `for...in` заборонено — рефакторити на `for...of`
+
+Конструкція `for (const k in obj)` обходить успадковані ключі прототипу, тому майже завжди тягне `Object.hasOwn(obj, k)`-guard. Заборонена у `@nitra/eslint-config` через `no-restricted-syntax` для `ForInStatement` (з версії **3.8.0**). У каноні oxlint лишається `guard-for-in` як часткова страховка (oxlint не підтримує `no-restricted-syntax`). Замість цього обходь масив напряму, а обʼєкт — через `Object.entries` / `Object.keys` / `Object.values`. У такому коді guard за `Object.hasOwn` стає непотрібним і має зникнути разом із `for...in`.
+
+```javascript title="❌ до"
+for (const k in obj) {
+  if (!Object.hasOwn(obj, k)) continue
+  use(k, obj[k])
+}
+
+for (const i in arr) {
+  use(arr[i])
+}
+```
+
+```javascript title="✅ після"
+for (const [k, v] of Object.entries(obj)) {
+  use(k, v)
+}
+
+for (const item of arr) {
+  use(item)
+}
+```
+
 ## Тести
 
 Проєкт має бути покритий unit-тестами (**Bun test**). Код: синтаксис Node **24+**, **top level await** (узгоджено з `engines.node` у `package.json`).

package/mdc/js-mssql.mdc

@@ -26,7 +26,7 @@ let poolPromise;
 
 export function getPool() {
   if (!poolPromise) {
-    const pool = new sql.ConnectionPool(config);
+    const db = new SQL.ConnectionPool(config);
     poolPromise = pool.connect().catch(err => {
       poolPromise = undefined; // дозволити повторну спробу
       throw err;

package/mdc/js-run.mdc

@@ -16,7 +16,6 @@ package.json
 readme.md
 ```
 
-
 ## Використання @nitra/pino
 
 Проект використовує @nitra/pino для логування.
@@ -53,34 +52,34 @@ import { GraphQLClient } from '@nitra/graphql-request'
 ```
 
 так виглядатиме підключення до 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 })
+export const db = new SQL({ url: env.PG_CONN })
 
 ```
 
 а так до GraphQL:
 
 ```js
-import { checkEnv } from '@nitra/check-env'
+import { checkEnv, env } 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, {
+export const graphQLClientSmart = new GraphQLClient(env.QL, {
   headers: {
-    'X-Hasura-Admin-Secret': process.env.X_HASURA_ADMIN_SECRET
+    'X-Hasura-Admin-Secret': env.X_HASURA_ADMIN_SECRET
   }
 })
 ```
 
-
 а в коді повинно бути використано:
 
 ```js
@@ -91,12 +90,9 @@ import { pool } from '#conn/pg.js'
 import { gql, graphQLClient } from '@nitra/graphql-request'
 ```
 
-
-
 ## CheckEnv
 
-Усі змінні оточення, які використовуються в коді, повинні бути перевірені за допомогою `checkEnv` з пакету `@nitra/check-env`. Це гарантує, що всі необхідні змінні оточення встановлені перед запуском програми. (Виключенням можуть бути задані коментарем)
-
+Усі змінні оточення, які використовуються в коді, повинні бути перевірені за допомогою `checkEnv` з пакету `@nitra/check-env`. Це гарантує, що всі необхідні змінні оточення встановлені перед запуском програми.
 
 ```javascript title="Приклад підключення до PostgreSQL в /src/conn/pg.js"
 import { checkEnv, env } from '@nitra/check-env'
@@ -104,12 +100,28 @@ import { SQL } from 'bun'
 
 checkEnv(['PG_CONN'])
 
-export const pool = new SQL({ url: env.PG_CONN })
+export const db = new SQL({ url: env.PG_CONN })
 
-// @nitra/cursor ignore-next-line checkEnv
-console.log(process.env.OPTIONAL_ENV_VAR)
 ```
 
+## process.env
+
+Прямий доступ до `process.env.X` у коді заборонений — його треба замінити на `env`:
+
+- **обов'язкова змінна** — `import { checkEnv, env } from '@nitra/check-env'` плюс `checkEnv(['X'])`
+  у тому ж файлі (приклад див. вище в розділі **CheckEnv**);
+- **опційна змінна** — `import { env } from 'node:process'`:
+
+```javascript title="Опційна змінна — env з node:process"
+import { env } from 'node:process'
+
+console.log(env.OPTIONAL_ENV_VAR)
+```
+
+Тимчасово приглушити перевірку для конкретного рядка можна коментарем
+`// @nitra/cursor ignore-next-line checkEnv` безпосередньо перед використанням
+(escape-hatch для legacy-коду, не для нових файлів).
+
 ## Перевірка
 
 `npx @nitra/cursor check js-run`

package/mdc/npm-module.mdc

@@ -1,7 +1,7 @@
 ---
 description: Оформлення репозиторію для npm модуля
 alwaysApply: true
-version: '1.7'
+version: '1.8'
 ---
 
 Bun monorepo: workspace **`npm/`**, кореневий **`package.json`**, **`.github/workflows/`**; опційно **`demo/`**.
@@ -49,6 +49,14 @@ bunx -p typescript tsc src/**/*.js --declaration --allowJs --emitDeclarationOnly
 
 **Підказка:** щоб не дублювати bump і бачити різницю зі збереженим деревом, перевір `git status npm/package.json` або `git diff HEAD -- npm/package.json` перед другим підвищенням у тій самій гілці / наборі змін.
 
+## CHANGELOG
+
+Разом із підвищенням **build**-версії в **`npm/package.json`** оновлюй **`npm/CHANGELOG.md`** — додавай новий запис із номером версії та коротким описом змін у модулі. Без оновлення `CHANGELOG.md` зміни в `npm/` зливати в `main` не можна.
+
+Формат — [Keep a Changelog](https://keepachangelog.com/uk/1.1.0/) (новіші версії зверху, мова — українська). Кожен запис починається з рядка `## [версія] - YYYY-MM-DD` і має одну або кілька секцій: `### Added`, `### Changed`, `### Fixed`, `### Removed`.
+
+Файл **`CHANGELOG.md`** має бути в масиві **`files`** у **`npm/package.json`**, щоб публікувався разом із пакетом.
+
 ## npm publish
 
 **`npm-publish.yml`:** push у **`main`**, **`on.push.paths`** з **`npm/**`**, **`JS-DevTools/npm-publish@v4.1.5`**, **`with.package: npm/package.json`**, **`permissions.id-token: write`** (OIDC на npm).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nitra/cursor",
-  "version": "1.8.155",
+  "version": "1.8.157",
   "description": "CLI для завантаження cursor-правил (префікс n-) у локальний репозиторій",
   "keywords": [
     "cli",
@@ -30,7 +30,8 @@
     "schemas",
     "scripts",
     "skills",
-    "AGENTS.template.md"
+    "AGENTS.template.md",
+    "CHANGELOG.md"
   ],
   "type": "module",
   "types": "./types/bin/n-cursor.d.ts",

package/scripts/auto-rules.mjs

@@ -3,7 +3,8 @@
  *
  * Модуль аналізує дерево проєкту (наявність файлів/директорій, `gql\`...\`` у source,
  * залежності `mssql` / `pg` / `pg-format` / `mysql2` у `package.json`, імпорт `sql`/`SQL` з `bun`, кореневий
- * `package.json`) та повертає ідентифікатори правил і skills, які потрібно автододати.
+ * `package.json`, `config.yaml` з рядком `metadata_directory: metadata` для hasura)
+ * та повертає ідентифікатори правил і skills, які потрібно автододати.
  *
  * Також враховує винятки `disable-rules` і `disable-skills`: елементи з цих списків не
  * додаються автоматично.
@@ -28,6 +29,7 @@ export const AUTO_RULE_ORDER = Object.freeze([
   'docker',
   'ga',
   'graphql',
+  'hasura',
   'js-lint',
   'js-mssql',
   'js-bun-db',
@@ -45,6 +47,7 @@ export const AUTO_RULE_ORDER = Object.freeze([
 export const AUTO_SKILL_ORDER = Object.freeze(['abie-kustomize', 'fix', 'lint'])
 
 const ABIE_REPOSITORY_URL_MARKER = 'https://github.com/abinbevefes/'
+const HASURA_CONFIG_MARKER = 'metadata_directory: metadata'
 const JS_LIKE_RE = /\.(?:mjs|cjs|js|jsx|ts|tsx)$/iu
 const STYLE_RE = /\.(?:css|vue)$/iu
 const VUE_RE = /\.vue$/iu
@@ -138,6 +141,24 @@ async function collectDependencyKeysPresentInPackageJsonTree(root, dependencyKey
   return found
 }
 
+/**
+ * Перевіряє один 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
+  }
+}
+
 /**
  * Перевіряє, чи існує хоча б один вкладений `package.json` (не кореневий),
  * у якому в `devDependencies` відсутня залежність `vite`.
@@ -147,28 +168,10 @@ async function collectDependencyKeysPresentInPackageJsonTree(root, dependencyKey
 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>}
+   * @returns {Promise<void>} завершується після обходу всього піддерева або встановлення `result`
    */
   async function walk(dir) {
     if (result) return
@@ -187,11 +190,14 @@ async function hasNestedPackageJsonWithoutViteDevDependency(root) {
         }
         continue
       }
-      if (entry.isFile() && entry.name === 'package.json' && absPath !== join(root, 'package.json')) {
-        if (await packageJsonLacksViteDevDependency(absPath)) {
-          result = true
-          return
-        }
+      if (
+        entry.isFile() &&
+        entry.name === 'package.json' &&
+        absPath !== join(root, 'package.json') &&
+        (await packageJsonLacksViteDevDependency(absPath))
+      ) {
+        result = true
+        return
       }
     }
   }
@@ -313,6 +319,26 @@ async function updateBunSqlFactFromFile(absPath, relPath, facts) {
   }
 }
 
+/**
+ * Оновлює ознаку `hasHasuraConfig`, якщо файл — `config.yaml` із рядком
+ * `metadata_directory: metadata` (маркер hasura graphql-engine).
+ * @param {string} absPath абсолютний шлях до файлу
+ * @param {string} fileName базове імʼя файлу
+ * @param {{ hasHasuraConfig: boolean }} facts агреговані факти
+ * @returns {Promise<void>}
+ */
+async function updateHasuraFactFromFile(absPath, fileName, facts) {
+  if (facts.hasHasuraConfig || fileName !== 'config.yaml') return
+  try {
+    const content = await readFile(absPath, 'utf8')
+    if (content.includes(HASURA_CONFIG_MARKER)) {
+      facts.hasHasuraConfig = true
+    }
+  } catch {
+    /* ігноруємо пошкоджені/недоступні файли */
+  }
+}
+
 /**
  * Обробляє файл під час обходу дерева.
  * @param {string} absPath абсолютний шлях до файлу
@@ -322,6 +348,7 @@ async function updateBunSqlFactFromFile(absPath, relPath, facts) {
  *   hasCapacitorConfig: boolean,
  *   hasDockerfile: boolean,
  *   hasGqlTaggedTemplates: boolean,
+ *   hasHasuraConfig: boolean,
  *   hasJsLikeSource: boolean,
  *   hasNginxDefaultTplFile: boolean,
  *   hasVueOrCssSource: boolean,
@@ -339,6 +366,7 @@ async function processFileEntry(absPath, root, facts) {
   if (shouldScanFileForBunSql(rel, facts)) {
     await updateBunSqlFactFromFile(absPath, rel, facts)
   }
+  await updateHasuraFactFromFile(absPath, fileName, facts)
 }
 
 /**
@@ -407,6 +435,7 @@ export function isMonorepoPackage(packageJson) {
  *   hasGaWorkflowsDir: boolean,
  *   hasBunSqlImport: boolean,
  *   hasGqlTaggedTemplates: boolean,
+ *   hasHasuraConfig: boolean,
  *   hasJsLikeSource: boolean,
  *   hasK8sDir: boolean,
  *   hasNginxDefaultTplFile: boolean,
@@ -423,6 +452,7 @@ export async function collectAutoRuleFacts(root) {
     hasDockerfile: false,
     hasGaWorkflowsDir: existsSync(join(root, '.github', 'workflows')),
     hasGqlTaggedTemplates: false,
+    hasHasuraConfig: false,
     hasJsLikeSource: false,
     hasK8sDir: false,
     hasNginxDefaultTplFile: false,
@@ -496,10 +526,10 @@ export async function detectAutoRulesAndSkills({
       : null
   )
   const isAbie = typeof repositoryUrl === 'string' && repositoryUrl.toLowerCase().includes(ABIE_REPOSITORY_URL_MARKER)
-  const isMonorepo = isMonorepoPackage(packageJsonParsed)
   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 hasJsBunDbSignal =
+    depHits.has('pg') || depHits.has('pg-format') || depHits.has('mysql2') || facts.hasBunSqlImport
   const hasNestedNodePackage = await hasNestedPackageJsonWithoutViteDevDependency(root)
 
   /** @type {string[]} */
@@ -538,6 +568,7 @@ export async function detectAutoRulesAndSkills({
     { enabled: facts.hasDockerfile, id: 'docker' },
     { enabled: facts.hasGaWorkflowsDir, id: 'ga' },
     { enabled: facts.hasGqlTaggedTemplates, id: 'graphql' },
+    { enabled: facts.hasHasuraConfig, id: 'hasura' },
     { enabled: facts.hasJsLikeSource, id: 'js-lint' },
     { enabled: hasMssqlDependency, id: 'js-mssql' },
     { enabled: hasJsBunDbSignal, id: 'js-bun-db' },

package/scripts/build-agents-commands.mjs

@@ -57,9 +57,7 @@ async function readPackageScripts(projectRoot) {
  */
 export async function buildAgentsCommandBulletItems(projectRoot) {
   const scripts = await readPackageScripts(projectRoot)
-  const items = /** @type {{ name: string }[]} */ ([])
-
-  items.push({ name: `- **Залежності**: \`bun i\`` })
+  const items = /** @type {{ name: string }[]} */ ([{ name: `- **Залежності**: \`bun i\`` }])
 
   const added = new Set()
 
@@ -79,10 +77,12 @@ export async function buildAgentsCommandBulletItems(projectRoot) {
     added.add(key)
   }
 
-  items.push({
-    name: `- **Оновити правила та ${AGENTS_MD}** (після змін у правилах/шаблоні CLI): \`npx ${PACKAGE_NAME}\``
-  })
-  items.push({ name: `- **Перевірки правил (programmatic)**: \`npx ${PACKAGE_NAME} check\`` })
+  items.push(
+    {
+      name: `- **Оновити правила та ${AGENTS_MD}** (після змін у правилах/шаблоні CLI): \`npx ${PACKAGE_NAME}\``
+    },
+    { name: `- **Перевірки правил (programmatic)**: \`npx ${PACKAGE_NAME} check\`` }
+  )
 
   return items
 }