@nitra/cursor 1.8.88 → 1.8.94

package/README.md

@@ -16,7 +16,7 @@
 {
   "$schema": "https://unpkg.com/@nitra/cursor/schemas/n-cursor.json",
   "rules": ["npm-module", "text"],
-  "skills": ["fix"]
+  "skills": ["fix", "lint"]
 }
 ```
 

package/mdc/npm-module.mdc

@@ -1,11 +1,46 @@
 ---
 description: Оформлення репозиторію для npm модуля
 alwaysApply: true
-version: '1.3'
+version: '1.7'
 ---
 
 Bun monorepo: workspace **`npm/`**, кореневий **`package.json`**, **`.github/workflows/`**; опційно **`demo/`**.
 
+## TypeScript declaration (`npm/types`)
+
+Файл **`npm/package.json`** має містити **`"types"`** (шлях до головного `.d.ts` або `.d.mts` під **`./types/…`**) і запис **`"types"`** у **`files`**, щоб npm публікував декларації.
+
+Генерація — через **`tsc`** і **`bunx -p typescript`** (окремий пакет **`typescript`** у `devDependencies` не потрібен).
+
+### Варіант A: є вихідний **`.js`** під **`npm/src/`**
+
+Якщо під **`npm/src`** (рекурсивно) є хоча б один файл **`.js`**:
+
+- **`"types": "./types/index.d.ts"`**;
+- у **hk** на **`pre-commit`** з каталогу **`npm/`** викликай:
+
+```bash
+bunx -p typescript tsc src/**/*.js --declaration --allowJs --emitDeclarationOnly --outDir types --skipLibCheck
+```
+
+Якщо glob не розгортається — **`bash -O globstar`** або **`include`** у **`tsconfig`** з тими самими **`compilerOptions`**.
+
+### Варіант B: немає **`npm/src/**/*.js`** (наприклад лише **`bin/`**, **`scripts/**/*.mjs`**)
+
+Не створюй штучний **`src/index.js`**. Замість цього:
+
+1. Додай **`npm/tsconfig.emit-types.json`** з **`include`** на реальні шляхи (`.js` / `.mjs`), **`compilerOptions`**: **`allowJs`**, **`declaration`**, **`emitDeclarationOnly`**, **`outDir`: `"types"`**, **`skipLibCheck`**: **`true`** (за потреби **`rootDir`**, **`module`**, **`moduleResolution`**).
+2. Після першого **`tsc`** подивись, який **`.d.ts`** / **`.d.mts`** відповідає публічному API, і вкажи його в **`types`** (наприклад **`./types/bin/cli.d.ts`**).
+3. У **hk** на **`pre-commit`** з **`npm/`** викликай **`tsc -p tsconfig.emit-types.json`**. Якщо через імпорти **TypeScript** все одно згенерує зайві **`.d.mts`** у **`types/`**, після **`tsc`** обрізай дерево до потрібного entrypoint (наприклад залиш лише **`types/bin/n-cursor.d.ts`** через **`find`**), щоб у пакеті не збирались декларації внутрішніх модулів.
+
+Файл **`tsconfig.emit-types.json`** тримай у репозиторії для **hk** / локальної генерації; у **`files`** його не додавай, якщо не хочеш публікувати його на **npm**.
+
+## Git hooks: hk + pre-commit
+
+У корені репозиторію — **`hk.pkl`** (або **`.config/hk.pkl`**) з **`["pre-commit"]`** і командою з відповідного варіанту (A або B) вище.
+
+Після додавання **`hk.pkl`**: **`hk install`**.
+
 ## Build версія
 
 Після змін у **`npm/`** обовʼязково підвищ **build**-версію в **`npm/package.json`**, але не роби зайвих підвищень: між номером у файлі й тим, що вже збережено в **git** (`HEAD`), має лишатися не більше одного кроку **+1**.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nitra/cursor",
-  "version": "1.8.88",
+  "version": "1.8.94",
   "description": "CLI для завантаження cursor-правил (префікс n-) у локальний репозиторій",
   "keywords": [
     "cli",
@@ -23,6 +23,7 @@
     "n-cursor": "./bin/n-cursor.js"
   },
   "files": [
+    "types",
     "mdc",
     "bin",
     "github-actions",
@@ -32,6 +33,7 @@
     "AGENTS.template.md"
   ],
   "type": "module",
+  "types": "./types/bin/n-cursor.d.ts",
   "scripts": {
     "test": "bun test tests",
     "rename-yaml-extensions": "bun ./bin/n-cursor.js rename-yaml-extensions"

package/scripts/check-abie.mjs

@@ -543,7 +543,7 @@ export function kustomizationHasAbieDeploymentNodeSelectorPatch(raw, mode) {
  * Чи YAML відносно кореня належить до **`${pkgRel}/k8s/**`** поза піддеревами **`ua/`** та **`ru/`** (base-шар abie).
  * @param {string} relFromRoot відносний шлях від кореня
  * @param {string} pkgRelFromRoot каталог пакета відносно кореня (без завершального слеша після імені пакета)
- * @returns {boolean}
+ * @returns {boolean} `true`, якщо шлях належить до base-шару abie
  */
 export function isK8sYamlInAbiePackageExcludingUaRuOverlays(relFromRoot, pkgRelFromRoot) {
   const normRel = relFromRoot.replaceAll('\\', '/')
@@ -560,7 +560,7 @@ export function isK8sYamlInAbiePackageExcludingUaRuOverlays(relFromRoot, pkgRelF
  * З HTTPRoute-документа рахує **`backendRefs`** до **`auth-run-hl`** / **`filelint-hl`** і порушення **`namespace: dev`**.
  * @param {unknown} obj корінь YAML
  * @param {string} rel відносний шлях (повідомлення)
- * @returns {{ refCount: number, errors: string[] }}
+ * @returns {{ refCount: number, errors: string[] }} кількість посилань і список порушень
  */
 function httpRouteDocSharedCrossNsBackendStats(obj, rel) {
   /** @type {string[]} */
@@ -582,26 +582,22 @@ function httpRouteDocSharedCrossNsBackendStats(obj, rel) {
   }
   let refCount = 0
   for (const rule of rules) {
-    if (rule === null || typeof rule !== 'object' || Array.isArray(rule)) {
-      continue
-    }
-    const brs = /** @type {Record<string, unknown>} */ (rule).backendRefs
-    if (!Array.isArray(brs)) {
-      continue
-    }
-    for (const br of brs) {
-      if (br === null || typeof br !== 'object' || Array.isArray(br)) {
-        continue
-      }
-      const brRec = /** @type {Record<string, unknown>} */ (br)
-      const name = brRec.name
-      if (typeof name !== 'string' || !ABIE_SHARED_CROSS_NS_BACKEND_SET.has(name)) {
-        continue
-      }
-      refCount++
-      const ns = brRec.namespace
-      if (typeof ns !== 'string' || ns !== 'dev') {
-        errors.push(`${rel}: HTTPRoute backendRefs до ${name} має містити namespace: dev (abie.mdc)`)
+    if (rule !== null && typeof rule === 'object' && !Array.isArray(rule)) {
+      const brs = /** @type {Record<string, unknown>} */ (rule).backendRefs
+      if (Array.isArray(brs)) {
+        for (const br of brs) {
+          if (br !== null && typeof br === 'object' && !Array.isArray(br)) {
+            const brRec = /** @type {Record<string, unknown>} */ (br)
+            const name = brRec.name
+            if (typeof name === 'string' && ABIE_SHARED_CROSS_NS_BACKEND_SET.has(name)) {
+              refCount++
+              const ns = brRec.namespace
+              if (typeof ns !== 'string' || ns !== 'dev') {
+                errors.push(`${rel}: HTTPRoute backendRefs до ${name} має містити namespace: dev (abie.mdc)`)
+              }
+            }
+          }
+        }
       }
     }
   }
@@ -613,7 +609,7 @@ function httpRouteDocSharedCrossNsBackendStats(obj, rel) {
  * @param {string} root корінь репозиторію
  * @param {string} pkgAbs абсолютний шлях до каталогу пакета
  * @param {string[]} yamlFilesAbs усі **yaml** під **k8s** (як **findK8sYamlFiles**)
- * @returns {Promise<{ refCount: number, baseErrors: string[] }>}
+ * @returns {Promise<{ refCount: number, baseErrors: string[] }>} кількість посилань і базові помилки
  */
 export async function analyzeAbieSharedBackendRefsInPackageK8s(root, pkgAbs, yamlFilesAbs) {
   const pkgRel = relative(root, pkgAbs).replaceAll('\\', '/') || pkgAbs
@@ -622,34 +618,36 @@ export async function analyzeAbieSharedBackendRefsInPackageK8s(root, pkgAbs, yam
   const baseErrors = []
   for (const abs of yamlFilesAbs) {
     const rel = relative(root, abs).replaceAll('\\', '/') || abs
-    if (!isK8sYamlInAbiePackageExcludingUaRuOverlays(rel, pkgRel)) {
-      continue
-    }
-    let raw
-    try {
-      raw = await readFile(abs, 'utf8')
-    } catch {
-      continue
-    }
-    const body = stripBom(raw)
-    const lines = body.split(/\r?\n/u)
-    const first = lines[0] ?? ''
-    const rest = MODELINE_RE.test(first.trim()) ? lines.slice(1).join('\n') : body
-    /** @type {import('yaml').Document[]} */
-    let docs
-    try {
-      docs = parseAllDocuments(rest)
-    } catch {
-      continue
-    }
-    for (const doc of docs) {
-      if (doc.errors.length > 0) {
-        continue
+    if (isK8sYamlInAbiePackageExcludingUaRuOverlays(rel, pkgRel)) {
+      let raw
+      try {
+        raw = await readFile(abs, 'utf8')
+      } catch {
+        raw = undefined
+      }
+      if (raw !== undefined) {
+        const body = stripBom(raw)
+        const lines = body.split(/\r?\n/u)
+        const first = lines[0] ?? ''
+        const rest = MODELINE_RE.test(first.trim()) ? lines.slice(1).join('\n') : body
+        /** @type {import('yaml').Document[] | undefined} */
+        let docs
+        try {
+          docs = parseAllDocuments(rest)
+        } catch {
+          docs = undefined
+        }
+        if (docs !== undefined) {
+          for (const doc of docs) {
+            if (doc.errors.length === 0) {
+              const obj = doc.toJSON()
+              const st = httpRouteDocSharedCrossNsBackendStats(obj, rel)
+              refCount += st.refCount
+              baseErrors.push(...st.errors)
+            }
+          }
+        }
       }
-      const obj = doc.toJSON()
-      const st = httpRouteDocSharedCrossNsBackendStats(obj, rel)
-      refCount += st.refCount
-      baseErrors.push(...st.errors)
     }
   }
   return { refCount, baseErrors }
@@ -659,7 +657,7 @@ export async function analyzeAbieSharedBackendRefsInPackageK8s(root, pkgAbs, yam
  * Рахує операції JSON6902 з **`path`**: **`/spec/rules/…/backendRefs/…/namespace`** та **`value`** overlay.
  * @param {string} combined сукупний текст patch **HTTPRoute**
  * @param {'ua' | 'ru'} mode overlay
- * @returns {number}
+ * @returns {number} кількість знайдених патчів namespace
  */
 function countAbieHttpRouteBackendRefNamespacePatchesInCombined(combined, mode) {
   const re =
@@ -1073,8 +1071,8 @@ async function ensureUaRuAbieHttpRoutePatches(root, yamlFilesAbs, fail, passFn)
   /** @type {Map<string, Promise<{ refCount: number, baseErrors: string[] }>>} */
   const sharedBackendAnalysisByPkg = new Map()
   /**
-   * @param {string} pkgAbs
-   * @returns {Promise<{ refCount: number, baseErrors: string[] }>}
+   * @param {string} pkgAbs абсолютний шлях до каталогу пакета
+   * @returns {Promise<{ refCount: number, baseErrors: string[] }>} кількість посилань і базові помилки
    */
   const getSharedBackendAnalysis = pkgAbs => {
     let p = sharedBackendAnalysisByPkg.get(pkgAbs)

package/scripts/check-k8s.mjs

@@ -34,6 +34,7 @@
  * кожен **Service** — **`spec.clusterIP: None`** та ім’я на **`-hl`**. У маршрутах **Gateway API**
  * (**`HTTPRoute`**, **`GRPCRoute`**, **`TCPRoute`**, **`TLSRoute`**, **`UDPRoute`**, група **`gateway.networking.k8s.io`**)
  * посилання **`backendRefs` / `backendRef`** на **Service** мають вказувати лише сервіси з суфіксом **`-hl`** у **`name`**.
+ * **HealthCheckPolicy** (**`networking.gke.io/v1`**, GKE): **`spec.targetRef`** на **Service** — **`name`** з суфіксом **`-hl`** (див. k8s.mdc).
  * Якщо **`kustomization.yaml`** посилається на **`svc.yaml`** (**`resources`**, **`bases`**, **`components`**, **`crds`**,
  * **`patches[].path`**, **`patchesStrategicMerge`**), у **тому ж** файлі має бути посилання на відповідний **`svc-hl.yaml`**
  * в **тому ж каталозі**, що й **`svc.yaml`** (логіка збігається з **`pathsFromKustomizationObject`**).
@@ -1146,11 +1147,40 @@ export function serviceSvcHlYamlHeadlessViolation(manifest) {
   return null
 }
 
+/**
+ * Чи **HealthCheckPolicy** (GKE) у **`spec.targetRef`** посилається на headless **Service** (суфікс **`-hl`**).
+ *
+ * Застосовується лише для **`apiVersion: networking.gke.io/v1`** і **`targetRef.kind: Service`** (або без **`kind`**).
+ * Інші **`targetRef.kind`** скрипт не оцінює.
+ * @param {unknown} manifest корінь YAML-документа
+ * @returns {string | null} текст порушення або null
+ */
+export function healthCheckPolicyTargetRefHeadlessServiceViolation(manifest) {
+  if (manifest === null || manifest === undefined || typeof manifest !== 'object' || Array.isArray(manifest))
+    return null
+  const rec = /** @type {Record<string, unknown>} */ (manifest)
+  if (rec.kind !== 'HealthCheckPolicy') return null
+  if (rec.apiVersion !== 'networking.gke.io/v1') return null
+  const spec = rec.spec
+  if (spec === null || spec === undefined || typeof spec !== 'object' || Array.isArray(spec)) return null
+  const targetRef = /** @type {Record<string, unknown>} */ (spec).targetRef
+  if (targetRef === null || targetRef === undefined || typeof targetRef !== 'object' || Array.isArray(targetRef)) {
+    return 'HealthCheckPolicy: потрібний spec.targetRef (див. k8s.mdc)'
+  }
+  const tr = /** @type {Record<string, unknown>} */ (targetRef)
+  const k = tr.kind
+  if (typeof k === 'string' && k !== '' && k !== 'Service') return null
+  const n = tr.name
+  if (typeof n !== 'string' || !n.endsWith(SVC_HL_NAME_SUFFIX)) {
+    return `HealthCheckPolicy: spec.targetRef.name має бути headless Service (суфікс «${SVC_HL_NAME_SUFFIX}»; див. k8s.mdc)`
+  }
+  return null
+}
+
 /**
  * Чи об’єкт схожий на **backendRef** до **Kubernetes Service** у Gateway API.
  *
  * Вимагає числовий **`port`**, щоб не плутати з **`HTTPHeaderMatch`** тощо (там теж є **`name`**, але без **`port`**).
- *
  * @param {unknown} obj вузол у дереві **`spec`**
  * @returns {boolean} true, якщо враховуємо поле **`name`** як посилання на Service
  */
@@ -1436,7 +1466,7 @@ export function isK8sBaseManifestYamlPath(rel, baseLower) {
 /**
  * Парсить усі YAML-документи: **metadata.namespace**, **Deployment.resources**, **Hasura image pin**,
  * **Service — заборонені GKE-анотації**, **`svc.yaml`** (**`spec.type: ClusterIP`**), **`svc-hl.yaml`**
- * (**headless**, суфікс **`-hl`** у **`metadata.name`**).
+ * (**headless**, суфікс **`-hl`** у **`metadata.name`**), **HealthCheckPolicy** (**`targetRef.name`** з **`-hl`**).
  * @param {string} rel відносний шлях
  * @param {string} baseLower basename файлу (нижній регістр)
  * @param {string} body вміст після modeline
@@ -1504,6 +1534,10 @@ function validateK8sYamlPolicyDocuments(rel, baseLower, body, fail, kustomizeMan
           fail(`${rel}: Service (документ ${di + 1}): ${svcH}`)
         }
       }
+      const hcpHl = healthCheckPolicyTargetRefHeadlessServiceViolation(obj)
+      if (hcpHl !== null) {
+        fail(`${rel}: документ ${di + 1}: ${hcpHl}`)
+      }
     }
   }
 }

package/scripts/check-npm-module.mjs

@@ -1,11 +1,19 @@
 /**
  * Перевіряє структуру npm-модуля в монорепо за правилом npm-module.mdc.
  *
- * Workspace `npm/`, `npm/package.json`, workflow `npm-publish.yml` з OIDC, `on.push.paths` з glob для каталогу npm (див. npm-module.mdc).
+ * Workspace `npm/`, `npm/package.json`, workflow `npm-publish.yml` з OIDC, `on.push.paths` з glob для каталогу npm.
+ *
+ * Якщо під `npm/src` є хоча б один файл `.js`, очікується канонічний layout: `types` → `./types/index.d.ts`,
+ * згенерований `index.d.ts` у `npm/types/`, і hk з викликом `tsc` по файлах під `npm/src`.
+ *
+ * Якщо таких файлів немає — layout через `npm/tsconfig.emit-types.json`: поле `types` має вказувати на існуючий
+ * файл під `./types/…`, у hk — `tsc -p tsconfig.emit-types.json`, у JSON-конфігу — потрібні compilerOptions для emit.
+ *
  * Поля workflow перевіряються після **YAML parse**, щоб не плутати з коментарями.
  */
 import { existsSync } from 'node:fs'
 import { readFile, stat } from 'node:fs/promises'
+import { join } from 'node:path'
 
 import { createCheckReporter } from './utils/check-reporter.mjs'
 import {
@@ -15,6 +23,121 @@ import {
   pushHasMainBranch,
   pushPathsIncludeNpmGlob
 } from './utils/gha-workflow.mjs'
+import { walkDir } from './utils/walkDir.mjs'
+
+/** Канонічний entrypoint типів для пакетів із вихідним `.js` під каталогом `npm/src` */
+const TYPES_INDEX = './types/index.d.ts'
+
+/** Файл проєкту TypeScript для emit без каталогу `src` (див. npm-module.mdc) */
+const EMIT_TYPES_CONFIG = 'npm/tsconfig.emit-types.json'
+
+/**
+ * Чи є під `npm/src` хоча б один `.js` (рекурсивно).
+ * @returns {Promise<boolean>} `true`, якщо знайдено хоча б один `.js`
+ */
+async function npmSrcTreeHasJsFile() {
+  const root = 'npm/src'
+  if (!existsSync(root)) {
+    return false
+  }
+  let found = false
+  await walkDir(root, p => {
+    if (p.endsWith('.js')) {
+      found = true
+    }
+  })
+  return found
+}
+
+/**
+ * Знаходить текстовий вміст конфігурації hk для перевірки npm-module.
+ * @returns {Promise<{ path: string, text: string } | null>} знайдений файл або `null`
+ */
+async function readHkConfig() {
+  const candidates = ['hk.pkl', '.config/hk.pkl']
+  for (const p of candidates) {
+    if (existsSync(p)) {
+      const text = await readFile(p, 'utf8')
+      return { path: p, text }
+    }
+  }
+  return null
+}
+
+/**
+ * Підрядки для hk при layout з каталогом `npm/src` і glob `src` + `.js` у команді (див. npm-module.mdc).
+ * @param {string} hkText текст конфігурації hk
+ * @returns {string[]} відсутні фрагменти
+ */
+function missingHkSrcLayoutFragments(hkText) {
+  const need = [
+    '["pre-commit"]',
+    'bunx -p typescript tsc',
+    'src/**/*.js',
+    '--declaration',
+    '--allowJs',
+    '--emitDeclarationOnly',
+    '--outDir types',
+    '--skipLibCheck'
+  ]
+  return need.filter(s => !hkText.includes(s))
+}
+
+/**
+ * Підрядки для hk при layout з `tsconfig.emit-types.json` (див. npm-module.mdc).
+ * @param {string} hkText текст конфігурації hk
+ * @returns {string[]} відсутні фрагменти
+ */
+function missingHkEmitTypesConfigFragments(hkText) {
+  const need = ['["pre-commit"]', 'bunx -p typescript tsc', 'tsconfig.emit-types.json']
+  return need.filter(s => !hkText.includes(s))
+}
+
+/**
+ * Перевіряє `npm/tsconfig.emit-types.json` на мінімальний набір опцій для `emitDeclarationOnly` у `types/`.
+ * @param {unknown} parsed результат `JSON.parse` конфігурації
+ * @returns {string[]} повідомлення про помилки (порожній — OK)
+ */
+function emitTypesConfigIssues(parsed) {
+  const issues = []
+  if (!parsed || typeof parsed !== 'object') {
+    return ['некоректний JSON']
+  }
+  const co = /** @type {{ [k: string]: unknown }} */ (parsed).compilerOptions
+  if (!co || typeof co !== 'object') {
+    return ['відсутній compilerOptions']
+  }
+  const get = k => /** @type {{ [k: string]: unknown }} */ (co)[k]
+  if (get('allowJs') !== true) {
+    issues.push('compilerOptions.allowJs має бути true')
+  }
+  if (get('declaration') !== true) {
+    issues.push('compilerOptions.declaration має бути true')
+  }
+  if (get('emitDeclarationOnly') !== true) {
+    issues.push('compilerOptions.emitDeclarationOnly має бути true')
+  }
+  if (get('outDir') !== 'types') {
+    issues.push('compilerOptions.outDir має бути "types"')
+  }
+  if (get('skipLibCheck') !== true) {
+    issues.push('compilerOptions.skipLibCheck має бути true')
+  }
+  return issues
+}
+
+/**
+ * Шлях на дискі до файлу з поля `types` у `npm/package.json` (значення на кшталт `./types/bin/x.d.ts`).
+ * @param {string} typesField значення поля `types` з `package.json`
+ * @returns {string | null} абсолютний шлях або `null`
+ */
+function npmTypesFileFromPackageField(typesField) {
+  if (typeof typesField !== 'string' || !typesField.startsWith('./types/')) {
+    return null
+  }
+  const rel = typesField.slice(2)
+  return join('npm', rel)
+}
 
 /**
  * Перевіряє відповідність проєкту правилам npm-module.mdc
@@ -57,6 +180,87 @@ export async function check() {
     fail('npm/package.json не існує — створи package.json для npm модуля')
   }
 
+  const useSrcJsLayout = await npmSrcTreeHasJsFile()
+
+  if (existsSync('npm/package.json')) {
+    const npmPkg = JSON.parse(await readFile('npm/package.json', 'utf8'))
+    const typesField = npmPkg.types
+
+    if (useSrcJsLayout) {
+      if (typesField === TYPES_INDEX) {
+        pass(`npm/package.json: "types": "${TYPES_INDEX}" (layout npm/src + .js)`)
+      } else {
+        fail(`npm/package.json: при наявності .js під npm/src очікується "types": "${TYPES_INDEX}"`)
+      }
+    } else {
+      if (typeof typesField === 'string' && /^\.\/types\/.+\.d\.(ts|mts)$/.test(typesField)) {
+        pass(`npm/package.json: "types" вказує на файл під ./types/… (${typesField})`)
+      } else {
+        fail(
+          'npm/package.json: без .js під npm/src поле types має бути рядком виду ./types/….d.ts або .d.mts (див. npm-module.mdc)'
+        )
+      }
+    }
+
+    const files = npmPkg.files
+    if (Array.isArray(files) && files.includes('types')) {
+      pass('npm/package.json: files містить "types"')
+    } else {
+      fail('npm/package.json: масив files має містити "types"')
+    }
+
+    const typesPath = useSrcJsLayout ? join('npm', 'types', 'index.d.ts') : npmTypesFileFromPackageField(typesField)
+    if (typesPath && existsSync(typesPath)) {
+      pass(`${typesPath} існує`)
+    } else {
+      fail(
+        useSrcJsLayout
+          ? `Відсутній ${join('npm', 'types', 'index.d.ts')} (згенеруй tsc з npm-module.mdc)`
+          : `Файл для поля types не знайдено або шлях не під ./types/ — ${String(typesField)}`
+      )
+    }
+  }
+
+  if (!useSrcJsLayout) {
+    if (existsSync(EMIT_TYPES_CONFIG)) {
+      pass(`${EMIT_TYPES_CONFIG} існує`)
+      let raw
+      try {
+        raw = JSON.parse(await readFile(EMIT_TYPES_CONFIG, 'utf8'))
+      } catch {
+        fail(`${EMIT_TYPES_CONFIG}: некоректний JSON`)
+        raw = null
+      }
+      if (raw) {
+        const issues = emitTypesConfigIssues(raw)
+        if (issues.length === 0) {
+          pass(`${EMIT_TYPES_CONFIG}: compilerOptions придатні для emitDeclarationOnly → types/`)
+        } else {
+          fail(`${EMIT_TYPES_CONFIG}: ${issues.join('; ')}`)
+        }
+      }
+    } else {
+      fail(
+        `Без .js під npm/src потрібен ${EMIT_TYPES_CONFIG} (див. npm-module.mdc: emit через tsconfig, без штучного src/index.js)`
+      )
+    }
+  }
+
+  const hk = await readHkConfig()
+  if (hk) {
+    pass(`${hk.path} існує`)
+    const missing = useSrcJsLayout ? missingHkSrcLayoutFragments(hk.text) : missingHkEmitTypesConfigFragments(hk.text)
+    if (missing.length === 0) {
+      pass(
+        `${hk.path}: pre-commit містить очікуваний виклик tsc (${useSrcJsLayout ? 'layout src' : 'tsconfig emit-types'})`
+      )
+    } else {
+      fail(`${hk.path}: онови pre-commit крок (npm-module.mdc); не знайдено: ${missing.join(', ')}`)
+    }
+  } else {
+    fail('Очікується hk.pkl або .config/hk.pkl з pre-commit і tsc (npm-module.mdc)')
+  }
+
   if (existsSync('.github/workflows')) {
     pass('.github/workflows/ існує')
   } else {

package/skills/lint/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: n-lint
+description: >-
+  Запустити кореневий bun run lint, виправити порушення й підтвердити чистий вихід
+---
+
+# n-lint — лінт проєкту через кореневий скрипт
+
+## Мета
+
+Один раз узгоджено прогнати весь ланцюжок **`lint`** з кореневого **`package.json`**, усунути помилки (авто- та вручну) і переконатися, що **`bun run lint`** завершується з кодом **`0`**.
+
+## Передумови
+
+- Поточна робоча директорія — **корінь репозиторію**, де є **`package.json`** зі скриптом **`lint`**.
+- Залежності встановлені (**`bun i`**) — якщо після правок змінювався **`package.json`** / lockfile, знову виконай **`bun i`** перед наступним запуском лінту.
+
+## Workflow
+
+1. **Запуск** — виконай повний лінт:
+
+```bash
+bun run lint
+```
+
+2. **Якщо exit code не 0** — проаналізуй вивід (останній упавший крок у ланцюжку **`lint`** часто видно з stderr / логів):
+   - Де скрипт уже робить **auto-fix** (**`--fix`**, **`markdownlint-cli2 --fix`**, **`oxfmt`** тощо) — перезапусти **`bun run lint`** після змін файлів.
+   - Де auto-fix **немає** (наприклад, **jscpd**, **cspell**, **zizmor**, перевірки без прапорця fix) — виправ код, конфіги або винятки **узгоджено з** `.cursor/rules/` (не розширюй ignore лише щоб приховати проблему без причини).
+
+3. **Цикл** — повторюй кроки 1–2, доки **`bun run lint`** не завершиться успішно. Після суттєвих правок за потреби ще раз **`bun run lint`**, щоб переконатися, що не зламав наступний крок у скрипті **`lint`**.
+
+4. **Верифікація** — фінальна перевірка (обов’язково з кодом **0**):
+
+```bash
+bun run lint
+```
+
+5. **Результат** — коротко опиши, що саме виправлено; якщо щось блокує нульовий exit code — залиш чітке пояснення й наступні кроки для людини.
+
+## Примітка
+
+Цей скіл **не** замінює **`npx @nitra/cursor check`**: **`lint`** перевіряє лінтери/формат у **`package.json`**, а **`check`** — програмні правила пакета **`@nitra/cursor`**. За потреби запускай обидва.

package/types/bin/n-cursor.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {}