@nitra/cursor 12.8.5 → 12.8.7

package/rules/nginx-default-tpl/js/dockerfile.mdc

@@ -0,0 +1,36 @@
+## Dockerfile — стиснення статики та envsubst шаблону
+
+Dockerfile потребує двох кроків, пов'язаних з nginx-шаблоном.
+
+### Стиснення статики (gzip_static)
+
+Щоб nginx міг використовувати `gzip_static on`, файли необхідно стиснути під час збирання образу:
+
+```dockerfile
+RUN find /usr/share/nginx/html -type f \( \
+  -name '*.js' -o -name '*.css' -o -name '*.map' -o -name '*.xml' -o \
+  -name '*.webmanifest' -o -name '*.html' -o -name '*.wasm' -o -name '*.ttf' \
+  \) -exec gzip -k {} +
+```
+
+Прапорець `-k` зберігає оригінальний файл поруч зі стиснутим `.gz`.
+
+### envsubst для default.conf.template
+
+Для підстановки змінних середовища у шаблон:
+
+```dockerfile
+# 1) Витягнути імена змінних з ini (ігноруємо коментарі/порожні)
+# 2) Зробити список для envsubst: $NAMESPACE $NAMESPACE2 ...
+# 3) Підвантажити значення з ini і підставити лише їх
+RUN NAMES=$(sed -nE '/^\s*[#;]/d; /^\s*$/d; s/^\s*([A-Za-z_][A-Za-z0-9_]*)\s*=.*/\1/p' /tpl/values-$BRANCH.ini) && \
+ VARS=$(printf '%s\n' $NAMES | awk '{printf "$%s ", $0}') && \
+  export $(grep -v '^#' /tpl/values-$BRANCH.ini | xargs) && \
+  envsubst "$VARS" < /tpl/default.conf.template > /app/default.conf
+```
+
+Перевірки (автоматичні):
+
+- Dockerfile містить `find … /usr/share/nginx/html … gzip -k` — крок стиснення статики
+- Dockerfile містить `envsubst` і посилання на `default.conf.template`
+- Якщо немає жодного Dockerfile / Containerfile поруч з `default.conf.template` — це помилка

package/rules/nginx-default-tpl/js/http-route.mdc

@@ -0,0 +1,41 @@
+## HTTPRoute в k8s — редирект і backendRefs
+
+Якщо в `default.conf.template` були `proxy_pass`-секції — їхню логіку потрібно перенести
+до HTTPRoute в k8s. `default.conf.template` **не повинен** містити жодного proxy.
+
+HTTPRoute має містити два правила:
+
+1. **Exact → RequestRedirect 301 (https)** — редирект з `/$PUBLIC_PATH` на `/$PUBLIC_PATH/`
+2. **PathPrefix → backendRefs:8080** — проксі трафіку на сервіс
+
+```yaml
+spec:
+  rules:
+    - matches:
+        - path:
+            type: Exact
+            value: /$PUBLIC_PATH
+      filters:
+        - type: RequestRedirect
+          requestRedirect:
+            scheme: https
+            path:
+              type: ReplaceFullPath
+              replaceFullPath: /$PUBLIC_PATH/
+            statusCode: 301
+    - matches:
+        - path:
+            type: PathPrefix
+            value: /$PUBLIC_PATH/
+      backendRefs:
+        - name: $SERVICE_NAME
+          port: 8080
+```
+
+де `$PUBLIC_PATH` підставляється з ini-файлу dev-середовища, а для інших середовищ — через `kustomization.yaml`.
+`$SERVICE_NAME` — ім'я k8s-сервісу, що приймає трафік на порту 8080.
+
+Перевірки (автоматичні):
+
+- перше правило має `path.type: Exact` і фільтр `RequestRedirect` з `scheme: https`, `path.type: ReplaceFullPath`, `statusCode: 301`
+- друге правило має `path.type: PathPrefix` і `backendRefs` з `port: 8080`

package/rules/nginx-default-tpl/js/ini-keys.mdc

@@ -0,0 +1,21 @@
+## Конфігураційні *.ini файли і envsubst
+
+Поруч з `default.conf.template` мають бути конфігураційні файли `*.ini` для кожного
+середовища (наприклад, `values-dev.ini`, `values-prod.ini`).
+
+Формат ini-файлу:
+
+```ini
+PUBLIC_PATH=/app
+SERVICE_NAME=my-frontend
+```
+
+Кожна змінна з `*.ini` **повинна використовуватись** у `default.conf.template` як `$KEY`
+(через envsubst). Якщо у `*.ini` є ключ, що відсутній у шаблоні — його треба вилучити з ini
+або додати в шаблон.
+
+Перевірки (автоматичні):
+
+- Поруч з кожним `default.conf.template` є щонайменше один `*.ini` файл
+- Кожен ключ з `*.ini` (рядки виду `KEY=value`, без коментарів `#`/`;` і порожніх рядків)
+  присутній у шаблоні як `$KEY`

package/rules/nginx-default-tpl/js/template-structure.mdc

@@ -0,0 +1,86 @@
+## Канонічна структура default.conf.template
+
+`default.conf.template` — єдиний nginx-конфіг для фронтенду зі статичними файлами.
+Він **не повинен** містити жодних `proxy_pass`, `proxy_redirect`, `proxy_set_header`,
+`fastcgi_pass`, `grpc_pass`, `uwsgi_pass`. Усю проксі-логіку потрібно винести в HTTPRoute (k8s).
+
+Канонічний вигляд файлу:
+
+```nginx
+server_tokens off;
+port_in_redirect off;
+client_max_body_size 0;
+client_body_buffer_size 512M;
+
+server {
+    listen 8080;
+    server_name _;
+
+    # disable all log
+    access_log off;
+    # `error_log off;` — НЕ валідний nginx: "off" трактується як ім'я файлу (/etc/nginx/off)
+    # і падає під readOnlyRootFilesystem. /dev/null — writable device.
+    error_log /dev/null crit;
+
+    # This would be the directory where your Vite app's static files are stored at
+    root /usr/share/nginx/html;
+
+    location /healthz {
+        add_header Content-Type text/plain;
+        access_log off;
+        return 200 "healthy";
+    }
+
+    # Без gz стиснених файлів, 1 year is 31536000 seconds
+    location ~ ^$PUBLIC_PATH/(.+\.(?:gif|jpe?g|png|ico|woff2|xlsx))$ {
+        alias /usr/share/nginx/html/$1;
+        add_header 'Cache-Control' "public,max-age=31536000,immutable";
+    }
+
+    # С gz стисненими файлами, 1 year is 31536000 seconds
+    location ~ ^$PUBLIC_PATH/(.+\.(?:svg|js|css|ttf|map|xml|webmanifest|wasm))$ {
+        alias /usr/share/nginx/html/$1;
+        add_header 'Cache-Control' "public,max-age=31536000,immutable";
+
+        # дозволяє віддавати замість звичайного файлу попередньо стиснутий файл з таким же ім'ям та з розширенням ".gz"
+        gzip_static on;
+    }
+
+    location $PUBLIC_PATH/ {
+        index index.html;
+        alias /usr/share/nginx/html/;
+
+        #  eliminates the step of copying the data into the buffer and enables direct copying data from one file descriptor to another.
+        sendfile on;
+        # to prevent one fast connection from entirely occupying the worker process
+        sendfile_max_chunk 512k;
+        # to send HTTP response headers in one packet right after the chunk of data has been obtained by sendfile().
+        tcp_nopush on;
+
+        # дозволяє віддавати замість звичайного файлу попередньо стиснутий файл з таким же ім'ям та з розширенням ".gz"
+        gzip_static on;
+
+        try_files $uri $uri/ /index.html =404;
+    }
+}
+```
+
+Обов'язкові вимоги до структури (перевіряються автоматично):
+
+- `server_tokens off` — приховує версію nginx у відповідях
+- `port_in_redirect off` — виключає порт з redirect-заголовків
+- `client_max_body_size 0` — без ліміту тіла запиту
+- `client_body_buffer_size 512M`
+- `listen 8080`
+- `server_name _` — catch-all
+- `access_log off`
+- `error_log /dev/null crit` (НЕ `error_log off;` — це некоректно в nginx)
+- `root /usr/share/nginx/html`
+- `location /healthz` з `return 200` і рядком `healthy`
+- location для статики без gzip (`gif|jpeg|png|ico|woff2|xlsx`) з `Cache-Control: max-age=31536000,immutable`
+- location для статики з gzip (`svg|js|css|ttf|map|xml|webmanifest|wasm`) з `gzip_static on`
+- `gzip_static on` щонайменше двічі (два location зі стисненням)
+- `$PUBLIC_PATH` у location — плейсхолдер підставляється через envsubst
+- `sendfile on`, `sendfile_max_chunk 512k`, `tcp_nopush on`
+- `try_files $uri $uri/ /index.html =404`
+- **Відсутність** будь-якого `proxy_pass` / `fastcgi_pass` / `grpc_pass` / `uwsgi_pass`

package/rules/nginx-default-tpl/js/vscode.mdc

@@ -0,0 +1,37 @@
+## VS Code — розширення та налаштування nginx
+
+Коли у проєкті є `default.conf.template`, очікуються відповідні VS Code конфігурації
+для підтримки nginx-синтаксису.
+
+### .vscode/extensions.json
+
+`recommendations` має містити розширення `ahmadalli.vscode-nginx-conf`:
+
+```json
+{
+  "recommendations": [
+    "ahmadalli.vscode-nginx-conf"
+  ]
+}
+```
+
+### .vscode/settings.json
+
+Має бути увімкнений `formatOnSave` і встановлений форматер nginx:
+
+```json
+{
+  "editor.formatOnSave": true,
+  "[nginx]": {
+    "editor.defaultFormatter": "ahmadalli.vscode-nginx-conf"
+  }
+}
+```
+
+Перевірки виконуються через Rego-пакети (conftest):
+
+- `nginx_default_tpl.vscode_extensions` — перевіряє наявність `ahmadalli.vscode-nginx-conf` у `recommendations`
+- `nginx_default_tpl.vscode_settings` — перевіряє `editor.formatOnSave: true` і `[nginx].editor.defaultFormatter: "ahmadalli.vscode-nginx-conf"`
+
+Ці перевірки активуються **лише** якщо в проєкті знайдено `default.conf.template`
+(умовне правило, не auto-discoverable без JS-gate).

package/rules/nginx-default-tpl/main.mdc

@@ -5,120 +5,14 @@ globs: "**/default.{conf.template,tpl.conf}"
 alwaysApply: false
 ---
 
-default.conf.template повинен виглядати так:
+Правило забезпечує відповідність `default.conf.template` канонічній структурі nginx для фронтенду зі статичними файлами, а також перевіряє пов'язані артефакти: HTTPRoute (k8s), Dockerfile, ini-файли середовищ і VS Code конфігурацію.
 
-```nginx
-server_tokens off;
-port_in_redirect off;
-client_max_body_size 0;
-client_body_buffer_size 512M;
+[nginx-default-tpl-template-structure](./js/template-structure.mdc)
 
-server {
-    listen 8080;
-    server_name _;
+[nginx-default-tpl-http-route](./js/http-route.mdc)
 
-    # disable all log
-    access_log off;
-    # `error_log off;` — НЕ валідний nginx: "off" трактується як ім'я файлу (/etc/nginx/off)
-    # і падає під readOnlyRootFilesystem. /dev/null — writable device.
-    error_log /dev/null crit;
+[nginx-default-tpl-dockerfile](./js/dockerfile.mdc)
 
-    # This would be the directory where your Vite app's static files are stored at
-    root /usr/share/nginx/html;
+[nginx-default-tpl-ini-keys](./js/ini-keys.mdc)
 
-    location /healthz {
-        add_header Content-Type text/plain;
-        access_log off;
-        return 200 "healthy";
-    }
-
-    # Без gz стиснених файлів, 1 year is 31536000 seconds
-    location ~ ^$PUBLIC_PATH/(.+\.(?:gif|jpe?g|png|ico|woff2|xlsx))$ {
-        alias /usr/share/nginx/html/$1;
-        add_header 'Cache-Control' "public,max-age=31536000,immutable";
-    }
-
-    # С gz стисненими файлами, 1 year is 31536000 seconds
-    location ~ ^$PUBLIC_PATH/(.+\.(?:svg|js|css|ttf|map|xml|webmanifest|wasm))$ {
-        alias /usr/share/nginx/html/$1;
-        add_header 'Cache-Control' "public,max-age=31536000,immutable";
-
-        # дозволяє віддавати замість звичайного файлу попередньо стиснутий файл з таким же ім'ям та з розширенням ".gz"
-        gzip_static on;
-    }
-
-    location $PUBLIC_PATH/ {
-        index index.html;
-        alias /usr/share/nginx/html/;
-
-        #  eliminates the step of copying the data into the buffer and enables direct copying data from one file descriptor to another.
-        sendfile on;
-        # to prevent one fast connection from entirely occupying the worker process
-        sendfile_max_chunk 512k;
-        # to send HTTP response headers in one packet right after the chunk of data has been obtained by sendfile().
-        tcp_nopush on;
-
-        # дозволяє віддавати замість звичайного файлу попередньо стиснутий файл з таким же ім'ям та з розширенням ".gz"
-        gzip_static on;
-
-        try_files $uri $uri/ /index.html =404;
-    }
-}
-```
-
-Тобто в ньому не потрібно щоб було жодного proxy_pass секціі і інших опцій для proxy.
-
-Якщо в файлі вже були proxy_pass секції, то їх логіку потрібно перенести до HTTPRoute в k8s.
-
-В HTTPRoute повинна бути секція Exact редиректу на версію з /
-
-```yaml
-spec:
-  rules:
-    - matches:
-        - path:
-            type: Exact
-            value: /$PUBLIC_PATH
-      filters:
-        - type: RequestRedirect
-          requestRedirect:
-            scheme: https
-            path:
-              type: ReplaceFullPath
-              replaceFullPath: /$PUBLIC_PATH/
-            statusCode: 301
-    - matches:
-        - path:
-            type: PathPrefix
-            value: /$PUBLIC_PATH/
-      backendRefs:
-        - name: $SERVICE_NAME
-          port: 8080
-```
-
-де $PUBLIC_PATH підставляється з ini файлу з dev середовища, а якщо для інших середовищ відрізняється то підставляється в kustomization.yaml відповідні значення з ini середовища.
-
-В $SERVICE_NAME повинно бути вказано ім'я сервісу, яке буде використовуватися в k8s.
-
-В Dockerfile потрібно додати команду для стиснення файлів, які потім використовуватимуться з `gzip_static on`:
-
-```dockerfile
-RUN find /usr/share/nginx/html -type f \( \
-  -name '*.js' -o -name '*.css' -o -name '*.map' -o -name '*.xml' -o \
-  -name '*.webmanifest' -o -name '*.html' -o -name '*.wasm' -o -name '*.ttf' \
-  \) -exec gzip -k {} +
-```
-
-Поруч з файлом default.conf.template повинні бути конфігураційні файли *.ini для різних середовищ. В Dockerfile повинна бути команда, для заміни плейсхолдерів в цих файлах на значення з середовища:
-
-```dockerfile
-# 1) Витягнути імена змінних з ini (ігноруємо коментарі/порожні)
-# 2) Зробити список для envsubst: $NAMESPACE $NAMESPACE2 ...
-# 3) Підвантажити значення з ini і підставити лише їх
-RUN NAMES=$(sed -nE '/^\s*[#;]/d; /^\s*$/d; s/^\s*([A-Za-z_][A-Za-z0-9_]*)\s*=.*/\1/p' /tpl/values-$BRANCH.ini) && \
- VARS=$(printf '%s\n' $NAMES | awk '{printf "$%s ", $0}') && \
-  export $(grep -v '^#' /tpl/values-$BRANCH.ini | xargs) && \
-  envsubst "$VARS" < /tpl/default.conf.template > /app/default.conf
-```
-
-Якщо у конфігураційних файлах *.ini є змінні які відсутні в default.conf.template, то їх потрібно вилучити.
+[nginx-default-tpl-vscode](./js/vscode.mdc)

package/rules/npm-module/js/docs/index.md

@@ -6,9 +6,9 @@ resource: npm/rules/npm-module/js/
 
 # npm/rules/npm-module/js
 
-| Файл | Тип |
-|---|---|
+| Файл                                            | Тип       |
+| ----------------------------------------------- | --------- |
 | [header_doc_pointer.mjs](header_doc_pointer.md) | JS Module |
-| [package_structure.mjs](package_structure.md) | JS Module |
-| [rule_meta.mjs](rule_meta.md) | JS Module |
-| [skill_meta.mjs](skill_meta.md) | JS Module |
+| [package_structure.mjs](package_structure.md)   | JS Module |
+| [rule_meta.mjs](rule_meta.md)                   | JS Module |
+| [skill_meta.mjs](skill_meta.md)                 | JS Module |

package/rules/npm-module/js/docs/rule_meta.md

@@ -17,12 +17,12 @@ docgen:
 1. Перевіряє наявність каталогу `npm/rules` у корені репозиторію. Якщо каталог відсутній, завершує роботу, повідомляючи про відсутність правил для валідації.
 2. Ітерує по всім підкаталогах у `npm/rules`, ігноруючи приховані каталоги.
 3. Для кожного каталогу виконує перевірку правила:
-    а. Перевіряє відсутність файлу `auto.md`. Якщо знайдено, повідомляє про залишковий файл.
-    б. Перевіряє наявність файлу `main.mdc`. Якщо відсутній, повідомляє про відсутність обов'язкового файлу (scripts.mdc).
-    в. Зчитує вміст `main.json` каталогу правила. Якщо файл відсутній або невалідний, повідомляє про це та пропускає подальшу валідацію цього правила.
-    г. Перевіряє поле `auto` у `main.json`. Якщо поле присутнє, валідує його структуру та перевіряє, чи всі використані предикати визначені.
-    ґ. Перевіряє поле `lint` у `main.json`. Якщо поле присутнє, валідує його структуру та перевіряє, чи експортує файл `main.mjs` відповідну функцію `lint`.
-    і. Якщо всі перевірки для правила пройдені успішно, повідомляє про валідність `main.json`.
+   а. Перевіряє відсутність файлу `auto.md`. Якщо знайдено, повідомляє про залишковий файл.
+   б. Перевіряє наявність файлу `main.mdc`. Якщо відсутній, повідомляє про відсутність обов'язкового файлу (scripts.mdc).
+   в. Зчитує вміст `main.json` каталогу правила. Якщо файл відсутній або невалідний, повідомляє про це та пропускає подальшу валідацію цього правила.
+   г. Перевіряє поле `auto` у `main.json`. Якщо поле присутнє, валідує його структуру та перевіряє, чи всі використані предикати визначені.
+   ґ. Перевіряє поле `lint` у `main.json`. Якщо поле присутнє, валідує його структуру та перевіряє, чи експортує файл `main.mjs` відповідну функцію `lint`.
+   і. Якщо всі перевірки для правила пройдені успішно, повідомляє про валідність `main.json`.
 4. Після обробки всіх правил повертає код виходу, що відображає загальний статус валідації.
 
 ## Публічний API

package/rules/npm-module/js/docs/skill_meta.md

@@ -17,14 +17,14 @@ docgen:
 1. Перевіряє наявність каталогу `npm/skills` у поточному робочому каталозі. Якщо каталог відсутній, операція завершується успішно.
 2. Ітерує по всіх підкаталогах у `npm/skills`.
 3. Для кожного підкаталогу виконується перевірка метаданих скіла:
-    а. Перевіряється наявність файлу `auto.md` у каталозі скіла. Якщо він присутній, це вважається порушенням.
-    б. Зчитується вміст `main.json` скіла. Якщо файл відсутній або невалідний, перевірка для цього скіла припиняється.
-    в. Виконується перевірка полів `main.json` скіла:
-        i. `worktree` має бути булевим значенням.
-        ii. Якщо поле `auto` визначене, його вміст має бути розпізнаним як "завжди" або непорожній масив правил.
-        iii. `requireRoot` має бути булевим значенням, якщо визначений.
-        iv. Якщо `worktree` встановлено як `true`, а `requireRoot` як `false`, це вважається порушенням.
-    г. Якщо всі поля `main.json` валідні, це вважається успішним результатом для скіла.
+   а. Перевіряється наявність файлу `auto.md` у каталозі скіла. Якщо він присутній, це вважається порушенням.
+   б. Зчитується вміст `main.json` скіла. Якщо файл відсутній або невалідний, перевірка для цього скіла припиняється.
+   в. Виконується перевірка полів `main.json` скіла:
+   i. `worktree` має бути булевим значенням.
+   ii. Якщо поле `auto` визначене, його вміст має бути розпізнаним як "завжди" або непорожній масив правил.
+   iii. `requireRoot` має бути булевим значенням, якщо визначений.
+   iv. Якщо `worktree` встановлено як `true`, а `requireRoot` як `false`, це вважається порушенням.
+   г. Якщо всі поля `main.json` валідні, це вважається успішним результатом для скіла.
 4. Після перевірки всіх скілів повертається код виходу, що відображає загальний статус (0 — успіх, 1 — порушення).
 
 ## Публічний API

package/rules/npm-module/js/header_doc_pointer.mdc

@@ -0,0 +1,18 @@
+## Module-level JSDoc як pointer
+
+Якщо поряд із `js/<stem>.mjs` є файл `js/docs/<stem>.md` — module-level JSDoc у `.mjs` має бути **pointer** (не більше одного непорожнього рядка), а не повноцінний наратив.
+
+Логіка перевірки (`header_doc_pointer.mjs`):
+
+- Сканується перший JSDoc-блок (`/** … */`) до першого `import`/`export` у файлі.
+- Підраховуються непорожні рядки тіла (після зрізання `*`-відступу).
+- Якщо їх більше одного — `check` падає з повідомленням про те, що `docs/<stem>.md` вже описує поведінку і module-level JSDoc має залишатись коротким.
+
+**Покриття:** `npm/rules/*/js/*.mjs` і `npm/skills/*/js/*.mjs` (не тестові файли `*.test.mjs`). Якщо `docs/<stem>.md` відсутня — обмежень на довжину JSDoc немає.
+
+**Приклад правильного pointer-JSDoc:**
+
+```js
+/** @see ./docs/package_structure.md */
+import { existsSync } from 'node:fs'
+```

package/rules/npm-module/js/package_structure.mdc

@@ -0,0 +1,62 @@
+## Структура монорепо та компактний пакет
+
+Bun monorepo: workspace **`npm/`**, кореневий **`package.json`**, **`.github/workflows/`**; опційно **`demo/`**.
+
+Мета — **максимально компактний** опублікований пакет: у npm потрапляє тільки те, що потрібно під час `require`/`import` користувачем.
+
+- **`"files"` обовʼязковий** у `npm/package.json` як **whitelist** того, що публікується (без `"files"` npm пакує майже все — це антипатерн для цього правила).
+- **Тести й фікстури не публікуються — через негативні glob-патерни у `"files"`.** Тести можна (і зазвичай зручніше) тримати **поруч з кодом** усередині шляхів, перелічених у `"files"` (наприклад `*.test.mjs` поруч з модулем чи `fixtures/` під `rules/<id>/js/`). Щоб вони не потрапляли у tarball, `"files"` **обовʼязково має містити негативні glob-патерни**, що їх виключають. Покрий усі форми тестового: фреймворк-тести (`bun:test`, `node:test`, `vitest`, `@jest/globals`, `mocha`, …), test-style каталоги (`tests/`, `__tests__/`, `fixtures/`, `__fixtures__/`, `spec/`, `test/`), файли за патернами `*.test.*` / `*.spec.*`. Орієнтовний набір: `"!**/*.test.*"`, `"!**/*.spec.*"`, `"!**/test-helpers.*"`, `"!**/fixtures/**"`, `"!**/__tests__/**"`. **Rego (`*_test.rego`):** за конвенцією conftest юніт-тест лежить поруч з полісі у тому самому `package` — `*_test.rego` усередині опублікованого `policy/` дозволені; якщо потрібна максимальна компактність, додай `"!**/*_test.rego"` явно (як у самому `@nitra/cursor`).
+- **Лише runtime-залежності у `npm/package.json`.** `devDependencies` тримай у **кореневому** `package.json` монорепо — тоді `npm install @nitra/<pkg>` не тягне інструментарій, потрібний лише для розробки самого пакета.
+
+Перевірки JS (`package_structure.mjs`):
+- Наявність `package.json`, `npm/`, `npm/package.json`.
+- Walk шляхів з `"files"` з застосуванням негативних patterns і скан залишку на тест-патерни (walking + AST). Якщо після застосування негативних patterns у tarball лишається test-style файл — `check` падає з вказівкою, який саме негативний glob треба додати у `"files"`.
+
+## 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`**.
+
+## 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).
+
+Workflow робить **release + publish** одним job (`release-publish`): крок **`Release (bump + CHANGELOG + tag)`** (`bunx n-cursor release` — агрегує change-файли, bump `version`, генерує секцію `CHANGELOG.md`, ставить git-тег) виконується **перед** публікацією. Тому потрібні **`permissions.contents: write`** і **`persist-credentials: true`** з **`fetch-depth: 0`** на `checkout` (release пушить commit-back версії та тег), а також локальний composite **`./.github/actions/setup-bun-deps`** і крок `Configure git identity`. Це узгоджено з **`n-changelog`**: `version`/`CHANGELOG.md` змінює лише `n-cursor release` у CI на `main`. Програмна перевірка (`npm_module.npm_publish_yml`) звіряє **весь канонічний сніпет** напряму (`target.json:"check":"template"`, generic deep-subset): усі поля й кроки сніпета (`on.push.paths`/`branches`, `concurrency`, `permissions.contents/id-token`, `checkout` з `persist-credentials/fetch-depth`, `setup-bun-deps`, `Configure git identity`, `Release`, publish-крок) **обовʼязкові**; зайві кроки/поля дозволені (subset-of), масиви матчаться за наявністю (порядок кроків не важить). Сніпет — єдине джерело істини: його редагування одразу змінює enforce, без правок rego й без міграторів.
+
+- Канон: [npm-publish.yml.snippet.yml](./policy/npm_publish_yml/template/npm-publish.yml.snippet.yml)
+
+## Канонічні конфіги
+
+- Кореневий `package.json` (workspaces): [package.json.snippet.json](./policy/root_package_json/template/package.json.snippet.json)
+- `npm/package.json` (whitelist `files` обовʼязково має містити `types`): [package.json.snippet.json](./policy/npm_package_json/template/package.json.snippet.json)
+- `npm/tsconfig.emit-types.json` (canonical `compilerOptions` для emit-types): [tsconfig.emit-types.json.snippet.json](./policy/emit_types_config/template/tsconfig.emit-types.json.snippet.json)

package/rules/npm-module/js/rule_meta.mdc

@@ -0,0 +1,11 @@
+## Валідація `main.json` правил
+
+Кожне правило у `npm/rules/<id>/` повинно мати коректний `main.json` (метадані правила).
+
+Перевірки (`rule_meta.mjs`):
+
+- **`main.mdc` обовʼязковий** у кожному `npm/rules/<id>/` — без нього `check` падає.
+- **`auto.md` є пережитком** — якщо такий файл залишився, `check` вимагає його видалити (метадані тепер у `main.json`).
+- **`main.json` має бути валідним JSON** із коректними полями:
+  - **`auto`** (опційне): `"завжди"` / масив glob-рядків / `{ glob }` / `{ predicate }`. Якщо `predicate` вказано — він має бути зареєстрований у `RULE_PREDICATES`.
+  - **`lint`** (опційне): `"per-file"` або `"full"`. Якщо вказано — `main.mjs` повинен експортувати функцію `lint` (або `export { lint } from …`).

package/rules/npm-module/js/skill_meta.mdc

@@ -0,0 +1,11 @@
+## Валідація `main.json` скілів
+
+Кожен скіл у `npm/skills/<id>/` повинен мати коректний `main.json` (метадані скіла).
+
+Перевірки (`skill_meta.mjs`):
+
+- **`auto.md` є пережитком** — якщо такий файл залишився, `check` вимагає його видалити (метадані тепер у `main.json`).
+- **`main.json` має бути валідним JSON** із коректними полями:
+  - **`worktree`** (обовʼязкове): `boolean`. Якщо `true` — скіл запускається виключно в окремому git-worktree.
+  - **`auto`** (опційне): `"завжди"` або непорожній масив ідентифікаторів правил-тригерів.
+  - **`requireRoot`** (опційне): `boolean`. Значення `false` несумісне з `worktree: true` — таку комбінацію `check` відхиляє.

package/rules/npm-module/main.mdc

@@ -7,53 +7,13 @@ version: '1.14'
 
 Bun monorepo: workspace **`npm/`**, кореневий **`package.json`**, **`.github/workflows/`**; опційно **`demo/`**.
 
-## Компактний пакет
+[npm-module-package_structure](./js/package_structure.mdc)
 
-Мета — **максимально компактний** опублікований пакет: у npm потрапляє тільки те, що потрібно під час `require`/`import` користувачем.
+[npm-module-rule_meta](./js/rule_meta.mdc)
 
-- **`"files"` обовʼязковий** у `npm/package.json` як **whitelist** того, що публікується (без `"files"` npm пакує майже все — це антипатерн для цього правила).
-- **Тести й фікстури не публікуються — через негативні glob-патерни у `"files"`.** Тести можна (і зазвичай зручніше) тримати **поруч з кодом** усередині шляхів, перелічених у `"files"` (наприклад `*.test.mjs` поруч з модулем чи `fixtures/` під `rules/<id>/js/`). Щоб вони не потрапляли у tarball, `"files"` **обовʼязково має містити негативні glob-патерни**, що їх виключають. Покрий усі форми тестового: фреймворк-тести (`bun:test`, `node:test`, `vitest`, `@jest/globals`, `mocha`, …), test-style каталоги (`tests/`, `__tests__/`, `fixtures/`, `__fixtures__/`, `spec/`, `test/`), файли за патернами `*.test.*` / `*.spec.*`. Орієнтовний набір: `"!**/*.test.*"`, `"!**/*.spec.*"`, `"!**/test-helpers.*"`, `"!**/fixtures/**"`, `"!**/__tests__/**"`. **Rego (`*_test.rego`):** за конвенцією conftest юніт-тест лежить поруч з полісі у тому самому `package` — `*_test.rego` усередині опублікованого `policy/` дозволені; якщо потрібна максимальна компактність, додай `"!**/*_test.rego"` явно (як у самому `@nitra/cursor`).
-- **Лише runtime-залежності у `npm/package.json`.** `devDependencies` тримай у **кореневому** `package.json` монорепо — тоді `npm install @nitra/<pkg>` не тягне інструментарій, потрібний лише для розробки самого пакета.
+[npm-module-skill_meta](./js/skill_meta.mdc)
 
-Деталі алгоритму перевірки:
-
-- Пер-документні правила для `npm/package.json` (whitelist `files`, заборона `devDependencies`, форма `types`) — у rego-пакеті `npm_module.npm_package_json` (`npm/policy/npm_module/npm_package_json/`).
-- Walk шляхів з `"files"` з застосуванням негативних patterns і скан залишку на тест-патерни (walking + AST JS/TS) — у `check.mjs::checkNoTestsInPublishedFiles` (FS / AST не лягають у rego). Якщо після застосування негативних patterns у tarball лишається test-style файл — `check` падає з вказівкою, який саме негативний glob треба додати у `"files"`.
-
-## 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`**.
+[npm-module-header_doc_pointer](./js/header_doc_pointer.mdc)
 
 ## Версія та CHANGELOG
 
@@ -61,16 +21,11 @@ bunx -p typescript tsc src/**/*.js --declaration --allowJs --emitDeclarationOnly
 
 Повна модель (база порівняння, інверсія шляхів, формат CHANGELOG, post-release-інваріант «верхня секція CHANGELOG == `version`») — у **`n-changelog.mdc`** (джерело істини). Це правило їй підпорядковане й власних інструкцій bump/CHANGELOG не дублює.
 
-## 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).
-
-Workflow робить **release + publish** одним job (`release-publish`): крок **`Release (bump + CHANGELOG + tag)`** (`bunx n-cursor release` — агрегує change-файли, bump `version`, генерує секцію `CHANGELOG.md`, ставить git-тег) виконується **перед** публікацією. Тому потрібні **`permissions.contents: write`** і **`persist-credentials: true`** з **`fetch-depth: 0`** на `checkout` (release пушить commit-back версії та тег), а також локальний composite **`./.github/actions/setup-bun-deps`** і крок `Configure git identity`. Це узгоджено з **`n-changelog`**: `version`/`CHANGELOG.md` змінює лише `n-cursor release` у CI на `main`. Програмна перевірка (`npm_module.npm_publish_yml`) звіряє **весь канонічний сніпет** напряму (`target.json:"check":"template"`, generic deep-subset): усі поля й кроки сніпета (`on.push.paths`/`branches`, `concurrency`, `permissions.contents/id-token`, `checkout` з `persist-credentials/fetch-depth`, `setup-bun-deps`, `Configure git identity`, `Release`, publish-крок) **обовʼязкові**; зайві кроки/поля дозволені (subset-of), масиви матчаться за наявністю (порядок кроків не важить). Сніпет — єдине джерело істини: його редагування одразу змінює enforce, без правок rego й без міграторів.
-
-- Канон: [npm-publish.yml.snippet.yml](./policy/npm_publish_yml/template/npm-publish.yml.snippet.yml)
+## Швидкий gate через conftest
 
-## Канонічні конфіги
+Rego-пакети (запускаються через `npx @nitra/cursor fix`):
 
-- Кореневий `package.json` (workspaces): [package.json.snippet.json](./policy/root_package_json/template/package.json.snippet.json)
-- `npm/package.json` (whitelist `files` обовʼязково має містити `types`): [package.json.snippet.json](./policy/npm_package_json/template/package.json.snippet.json)
-- `npm/tsconfig.emit-types.json` (canonical `compilerOptions` для emit-types): [tsconfig.emit-types.json.snippet.json](./policy/emit_types_config/template/tsconfig.emit-types.json.snippet.json)
+- `npm_module.npm_package_json` — валідує `npm/package.json`: поле `types`, наявність і непорожність `files`, subset-of з template (зокрема `"types"` у `files`), заборона `devDependencies`.
+- `npm_module.root_package_json` — валідує кореневий `package.json`: поле `workspaces` має містити `"npm"`.
+- `npm_module.emit_types_config` — валідує `npm/tsconfig.emit-types.json`: `compilerOptions` відповідає канонічному сніпету (allowJs, declaration, emitDeclarationOnly, outDir, skipLibCheck).
+- `npm_module.npm_publish_yml` — template-driven перевірка `.github/workflows/npm-publish.yml` (deep-subset: усі обовʼязкові поля й кроки з канонічного сніпету).