@nitra/cursor 12.8.6 → 12.8.8

package/rules/docker/js/compile.mdc

@@ -0,0 +1,44 @@
+## Компіляція bun-проєкту в бінарник
+
+Якщо проект має `bun install` крок, та не є фронтенд проектом (тобто не має `bun build` крок без `--compile`), **і не має нативного `.node`-аддона з динамічним завантаженням** (див. `native-addon.mdc`), то потрібно щоб була компіляція коду, і далі у фінальному образі був тільки бінарник. Цей образ не містить компілятора, npm, Bun — тільки runtime libs.
+
+Тригер перевірки:
+- у Dockerfile є крок `bun install` (або `bun i`);
+- фінальний FROM — `mirror.gcr.io/library/alpine:*` (тобто не nginx/openresty frontend).
+
+Очікування:
+- у build stage є `bun build --compile`;
+- у фінальному stage немає викликів `bun` (залишків build tooling).
+
+### Канон — компільований бінарник на alpine
+
+```dockerfile
+FROM mirror.gcr.io/oven/bun:alpine AS build-env
+
+WORKDIR /app
+
+ENV NODE_ENV=production
+
+COPY package.json .
+COPY bunfig.toml .
+
+RUN bun install --production
+
+COPY ./src ./src
+
+# Компілюємо в бінарник
+RUN bun build --compile --outfile app ./src/index.js
+
+FROM mirror.gcr.io/library/alpine:latest
+
+# (libstdc++ libgcc) для Bun runtime, (tzdata) для часового поясу
+RUN apk add --no-cache libstdc++ libgcc tzdata
+
+WORKDIR /app
+
+COPY --from=build-env /app/app ./app
+
+CMD ["./app"]
+```
+
+Перевіряє `getBunCompileHint` у **`npm/rules/docker/js/lint.mjs`**.

package/rules/docker/js/hadolint.mdc

@@ -0,0 +1,50 @@
+## lint-docker: hadolint і CI-workflow
+
+### Область lint-docker
+
+CLI **`hadolint`** приймає лише **явні шляхи** (`[DOCKERFILE...]` у **`hadolint --help`**); обхід репозиторію робить правило **`n-cursor lint docker`** (реалізація — **`npm/rules/docker/js/lint.mjs`**).
+
+**Область lint-docker (вужча, ніж `check docker`):** лише файли з іменем **`Dockerfile`** та **`*.Dockerfile`** (суфікс **`.dockerfile`** без урахування регістру, наприклад **`api.Dockerfile`**). Файли **`Dockerfile.prod`**, **`Containerfile`** тощо **не** входять у **`lint-docker`**; їх ловить **`check docker`** (`rules/docker/fix.mjs`).
+
+Обхід: **`walkDir`** з тими самими пропусками каталогів, що й **`rules/docker/fix.mjs`**. Виклик **`hadolint`** як **нативного бінарника** через **`ensureTool`** (PATH → кеш → авто-install brew/scoop/GitHub Release; **без** `docker run`) — спільна логіка **`npm/rules/docker/lib/docker-hadolint.mjs`**.
+
+### GitHub Actions workflow
+
+Додай workflow **`.github/workflows/lint-docker.yml`** (гілки **`dev`** і **`main`**, лише **`.yml`**, узгоджено з **`ga.mdc`**):
+
+- Канон: [lint-docker.yml.snippet.yml](./policy/lint_docker_yml/template/lint-docker.yml.snippet.yml)
+
+Локально hadolint авто-встановлюється через **`ensureTool`** (latest, без піну версії). У CI встанови його кроком із workflow-сніпета (curl-download бінарника — без `docker run`).
+
+### Конфігурація hadolint
+
+Кореневий **`.hadolint.yaml`**: вимкнення правил, trusted registries — [документація](https://github.com/hadolint/hadolint#configure). Щоб не додавати **`# hadolint ignore=DL3007`** у кожному **`FROM`** з **`:latest`**, у корені репозиторію задати глобально:
+
+```yaml title=".hadolint.yaml"
+ignored:
+  - DL3007
+  - DL3008
+  - DL3018
+```
+
+Де DL3007 — «Не використовуй тег latest у FROM»
+Де DL3018 — «Піни версії пакетів у apk add»
+
+### Запуск
+
+1. **`n-cursor lint docker`** — **`js/lint.mjs`**: **`Dockerfile`** та **`*.Dockerfile`** (lint-docker); у CI використовуй **`n-cursor lint docker --read-only`** і встанови hadolint (приклад у workflow).
+2. **`npx @nitra/cursor fix docker`** — **`rules/docker/fix.mjs`**, виклик hadolint як у **`docker-hadolint.mjs`** (нативний бінарник через **`ensureTool`**; **без** `docker run`).
+
+Окремий `package.json`-скрипт `lint-docker` не потрібен і не перевіряється — єдина точка входу для правила: **`n-cursor lint docker`**.
+
+Якщо немає файлів у межах відповідного набору (**`lint-docker`** або **`check docker`**) — перевірка пропускається (exit 0).
+
+Винятки: **`# hadolint ignore=DL3008`** (або інший код) у Dockerfile або **`ignored`** у **`.hadolint.yaml`** (наприклад **DL3007** для **`:latest`** — div. вище).
+
+### Rego-перевірка (conftest)
+
+Пакет `docker.lint_docker_yml` перевіряє `.github/workflows/lint-docker.yml` на відповідність канонічному сніпету:
+
+- `on.push.paths` містить обов'язкові шляхи з template;
+- присутні всі `uses:` кроки з template;
+- всі `run:` підрядки з template є у workflow.

package/rules/docker/js/mirror.mdc

@@ -0,0 +1,13 @@
+## GCR-дзеркало замість Docker Hub
+
+Для образів з Docker Hub — **`oven/bun`**, **`alpine`**, **`nginx`**, **`nginxinc/nginx-unprivileged`**, **`node`** — у **`FROM`** треба вказувати дзеркало GCR, а не pull напряму з Hub:
+
+| Docker Hub | GCR-дзеркало |
+|---|---|
+| `oven/bun` | `mirror.gcr.io/oven/bun` |
+| `alpine` | `mirror.gcr.io/library/alpine` |
+| `nginx` | `mirror.gcr.io/library/nginx` |
+| `node` | `mirror.gcr.io/library/node` |
+| `nginxinc/nginx-unprivileged` | `mirror.gcr.io/nginxinc/nginx-unprivileged` |
+
+Перевіряє **`npm/rules/docker/lib/docker-mirror.mjs`** (через `getMirrorGcrHint`); точка входу обходу — **`npm/rules/docker/fix.mjs`** та **`npm/rules/docker/js/lint.mjs`**.

package/rules/docker/js/multistage.mdc

@@ -0,0 +1,13 @@
+## Multistage build і дозволені runtime-образи
+
+Dockerfile/Containerfile **має бути multistage build**: окремий build stage (залежності/компіляція) і окремий runtime stage. У фінальному stage дозволені лише мінімальні базові образи:
+
+- **backend (типово)**: `mirror.gcr.io/library/alpine:*`
+- **ультра-легкі (glibc / одна статична збірка)**: `scratch` — тільки як `FROM scratch` (офіційний порожній базовий шар), коли весь **runtime** уже в `COPY --from=…`
+- **glibc, Debian (slim)**: `mirror.gcr.io/library/debian:*` **лише** з тегом, у якому є `slim` (наприклад `bookworm-slim`, `trixie-slim`), а не `bookworm` без `slim`. Debian-slim виправданий **лише** коли потрібен саме glibc-рантайм (нативні glibc-залежності, prebuilds без musl-варіанта). **Non-root сам по собі не є підставою** переходити сюди: `mirror.gcr.io/oven/bun:alpine` уже має користувача `bun` (uid/gid 1000), тож `USER bun` дає non-root **без зміни бази**. Перехід Alpine→Debian заради лише non-root — **антипатерн** (більший образ + зайва musl→glibc міграція bun-бінарника)
+- **виняток (інтерпретовані стеки)**: `mirror.gcr.io/library/php:*` або `mirror.gcr.io/library/python:*` — якщо сервіс має крутитися в офіційному runtime PHP чи Python, а не як один бінарник на Alpine; інакше лишай **alpine** у фінальному stage
+- **frontend**: `mirror.gcr.io/nginxinc/nginx-unprivileged:*` або `mirror.gcr.io/openresty/openresty:*`
+
+Це стримує зайвий build tooling (Bun, **node_modules** зі збірки) у фінальному образі; для **alpine** / **nginx** / **openresty** у **runtime** лишаються лише відповідні вимоги, для **php** / **python** (виняток) — цільовий інтерпретований **stack**; **scratch** і **debian** з тегом **`*slim*`** — коли glibc і мінімальне оточення Debian важливіші за musl в **alpine**.
+
+Перевіряє `getMultistageAndRuntimeHint` у **`npm/rules/docker/js/lint.mjs`**.

package/rules/docker/js/native-addon.mdc

@@ -0,0 +1,43 @@
+## Виняток: нативний `.node`-аддон (sharp / @img/* / argon2)
+
+Якщо в `package.json#dependencies` є нативний `.node`-аддон, який вантажиться через **динамічний `require`** — передусім **`sharp`**; той самий клас — **`@img/*`**, **`argon2`** — його **не можна** пакувати через `bun build --compile`.
+
+`bun build --compile` не трейсить `require(\`@img/sharp-${platform}/sharp.node\`)` і не вшиває нативний біндинг → компільований бінарник падає в рантаймі: `Could not load the "sharp" module using the linuxmusl-arm64 runtime`. Доведено реальними docker-збірками (bun 1.3.14, sharp 0.34.5); відтворюється і на darwin-arm64 (тобто не musl/glibc-залежне). `apk add vips` **НЕ лікує** — він дає системний libvips, а бракує саме `sharp.node`.
+
+Канон — ship `node_modules` і запускати через `bun <entry>` на базі `mirror.gcr.io/oven/bun:alpine` (це легітимний виняток до правила «лише alpine/scratch у фінальному stage» — тут потрібен саме bun-рантайм). База `oven/bun` уже має non-root користувача `bun` (uid/gid 1000). Entry бери з наявного `--outfile`-таргета / `package.json#main` / `scripts.start`; якщо не визначити — лиши TODO-маркер, не вгадуй.
+
+Список нативних аддонів — розширювана константа `NATIVE_ADDON_PACKAGES` / `NATIVE_ADDON_SCOPES` у **`npm/rules/docker/lib/docker-native-addon.mjs`** (підключено в **`npm/rules/docker/js/lint.mjs`**, точка входу обходу — **`npm/rules/docker/fix.mjs`**).
+
+### Антипатерн (це правило ловить)
+
+```dockerfile
+RUN bun build --compile --outfile app ./src/index.js     # ← з sharp у deps
+FROM mirror.gcr.io/library/alpine:latest
+RUN apk add --no-cache ... vips                           # системний vips не рятує
+COPY --from=build-env --chown=app:app /app/app ./app
+USER app
+CMD ["./app"]
+```
+
+### Канон (привести до цього)
+
+```dockerfile
+FROM mirror.gcr.io/oven/bun:alpine AS build-env
+WORKDIR /app
+ENV NODE_ENV=production
+COPY package.json .
+RUN bun install --production
+COPY ./src ./src
+
+FROM mirror.gcr.io/oven/bun:alpine
+RUN apk add --no-cache tzdata
+WORKDIR /app
+# база oven/bun має non-root користувача bun (uid/gid 1000)
+COPY --from=build-env --chown=bun:bun /app/node_modules ./node_modules
+COPY --from=build-env --chown=bun:bun /app/src ./src
+COPY --from=build-env --chown=bun:bun /app/package.json ./package.json
+USER bun
+CMD ["bun", "src/index.js"]
+```
+
+Для проєктів **без** нативних аддонів standalone-бінарник на alpine лишається каноном (див. `compile.mdc`).

package/rules/docker/js/nginx-tag.mdc

@@ -0,0 +1,7 @@
+## Мінімальний тег для nginx-unprivileged
+
+Якщо використовується nginx, то **використовуй** `mirror.gcr.io/nginxinc/nginx-unprivileged:alpine-slim` (і не `latest` / `alpine`).
+
+Тег `alpine-slim` є обов'язковим для всіх `FROM` з образом `nginxinc/nginx-unprivileged` — будь-який інший тег (включаючи без тега) прапорцюється як порушення.
+
+Перевіряє `getNginxAlpineSlimTagHint` у **`npm/rules/docker/js/lint.mjs`**.

package/rules/docker/js/nginx-user.mdc

@@ -0,0 +1,37 @@
+## nginx-unprivileged — без USER, із --chown
+
+Окрема гілка для фронтенду на базі **`nginxinc/nginx-unprivileged`** (будь-який тег, з/без `mirror.gcr.io/`-префікса). Цей образ **уже** оголошує `USER 101` і `EXPOSE 8080`, тож у фінальному stage **не потрібні** жодні явні `USER`-інструкції:
+
+- **жодного `USER root` / `USER 0`** для білд-кроків: він перезатирає успадкований `USER 101`, і якщо потім не повернути non-root — фінальний образ лишається root, а k8s із `runAsNonRoot: true` падає з `CreateContainerConfigError`;
+- **жодного switch-back** `USER 101` / `USER nginx` наприкінці stage — це лише симптом зайвого `USER root` на початку (повертати треба саме **числовим** UID, бо kubelet не підтверджує non-root за іменем `nginx`). Канон — взагалі не виходити з-під дефолтного 101;
+- **`COPY`/`ADD` лише з `--chown`** (канон — `--chown=nginx:nginx`): без нього файли копіюються власником root і дефолтний non-root користувач (uid=101) не зможе читати статику.
+
+Build-stage не чіпаємо — там root і tooling норма. Перевіряє **`npm/rules/docker/lib/docker-nginx-user.mjs`** (підключено в **`npm/rules/docker/js/lint.mjs`**, точка входу обходу — **`npm/rules/docker/fix.mjs`**).
+
+### Антипатерн (це правило ловить)
+
+```dockerfile
+FROM mirror.gcr.io/nginxinc/nginx-unprivileged:alpine-slim
+USER root
+COPY ./k8s/nginx.conf /etc/nginx/conf.d/default.conf
+COPY --from=build /app/dist ./
+RUN find ./ -type f -name "*.js" -exec gzip -k {} \;
+USER 101          # повернення назад — симптом того, що був зайвий USER root
+EXPOSE 8080
+```
+
+### Канон (привести до цього)
+
+```dockerfile
+FROM mirror.gcr.io/nginxinc/nginx-unprivileged:alpine-slim
+
+COPY --chown=nginx:nginx ./k8s/nginx.conf /etc/nginx/conf.d/default.conf
+
+WORKDIR /usr/share/nginx/html
+
+COPY --from=build --chown=nginx:nginx /app/dist ./
+
+RUN find ./ -type f -name "*.js" -exec gzip -k {} \;
+```
+
+(без жодного `USER`, gzip під дефолтним користувачем 101; `EXPOSE 8080` теж зайвий — база вже його оголошує)

package/rules/docker/js/non-root.mdc

@@ -0,0 +1,39 @@
+## Non-root принцип у фінальному stage
+
+Для всіх образів потрібно щоб використовувся non-root принцип. **Спосіб** досягнення non-root залежить від **бази**, а не від зміни ОС — змінювати дистрибутив (Alpine→Debian) заради лише non-root **не треба**. Два шляхи:
+
+- **standalone-бінарник на `alpine:latest`** (секція компіляції) — у `alpine` немає готового non-root користувача, тож його створюємо явно: `addgroup -g 1000 app && adduser -D -u 1000 -G app app` + `COPY --chown=app:app` + `USER app` (приклад нижче);
+- **ship `node_modules` на `mirror.gcr.io/oven/bun:alpine`** (виняток: нативний `.node`-аддон) — користувач `bun` (uid/gid 1000) **уже в базі**, тож достатньо `COPY --chown=bun:bun …` + `USER bun`; базу на Debian-slim міняти **не треба** — це той самий антипатерн, що й у переліку фінальних образів.
+
+### Приклад для standalone-бінарника на alpine
+
+```dockerfile
+# Stage 1
+FROM oven/bun:alpine AS build-env
+WORKDIR /app
+COPY package.json bunfig.toml .
+RUN bun install --production
+COPY ./src ./src
+RUN bun build --compile --outfile app ./src/index.js
+
+# Stage 2
+FROM alpine:latest
+RUN apk add --no-cache libstdc++ libgcc tzdata
+
+# Додати non-root user
+RUN addgroup -g 1000 app && adduser -D -u 1000 -G app app
+
+WORKDIR /app
+
+# Змінити власника файлу
+COPY --from=build-env --chown=app:app /app/app ./app
+
+# Запускати як non-root
+USER app
+
+CMD ["./app"]
+```
+
+Перевіряє `getNonRootRuntimeHint` у **`npm/rules/docker/js/lint.mjs`**.
+
+> **Примітка:** для `nginxinc/nginx-unprivileged` канон відрізняється — дивись `nginx-user.mdc`.

package/rules/docker/main.mdc

@@ -7,211 +7,28 @@ alwaysApply: false
 
 # Docker — hadolint
 
-Для образів з Docker Hub — **`oven/bun`**, **`alpine`**, **`nginxinc/nginx-unprivileged`**, **`node`** — у **`FROM`** треба вказувати дзеркало GCR, а не pull напряму з Hub: **`mirror.gcr.io/oven/bun`**, **`mirror.gcr.io/library/alpine`**, **`mirror.gcr.io/nginxinc/nginx-unprivileged`**, **`mirror.gcr.io/library/node`**. Перевіряє **`rules/docker/fix.mjs`**, деталі в **`npm/rules/docker/js/lint/docker-mirror.mjs`**.
+Правило перевіряє Dockerfile / Containerfile: GCR-дзеркало замість Docker Hub, multistage build з дозволеними runtime-образами, компіляцію bun-проєктів у бінарник, виняток для нативних `.node`-аддонів, non-root у фінальному stage, nginx-специфічні вимоги та hadolint CI-workflow.
 
-Також Dockerfile/Containerfile **має бути multistage build**: окремий build stage (залежності/компіляція) і окремий runtime stage. У фінальному stage дозволені лише мінімальні базові образи:
+## Активація
 
-- **backend (типово)**: `mirror.gcr.io/library/alpine:*`
-- **ультра-легкі (glibc / одна статична збірка)**: `scratch` — тільки як `FROM scratch` (офіційний порожній базовий шар), коли весь **runtime** уже в `COPY --from=…`
-- **glibc, Debian (slim)**: `mirror.gcr.io/library/debian:*` **лише** з тегом, у якому є `slim` (наприклад `bookworm-slim`, `trixie-slim`), а не `bookworm` без `slim`. Debian-slim виправданий **лише** коли потрібен саме glibc-рантайм (нативні glibc-залежності, prebuilds без musl-варіанта). **Non-root сам по собі не є підставою** переходити сюди: `mirror.gcr.io/oven/bun:alpine` уже має користувача `bun` (uid/gid 1000), тож `USER bun` дає non-root **без зміни бази**. Перехід Alpine→Debian заради лише non-root — **антипатерн** (більший образ + зайва musl→glibc міграція bun-бінарника)
-- **виняток (інтерпретовані стеки)**: `mirror.gcr.io/library/php:*` або `mirror.gcr.io/library/python:*` — якщо сервіс має крутитися в офіційному runtime PHP чи Python, а не як один бінарник на Alpine; інакше лишай **alpine** у фінальному stage
-- **frontend**: `mirror.gcr.io/nginxinc/nginx-unprivileged:*` або `mirror.gcr.io/openresty/openresty:*`
+Спрацьовує на всі файли `Dockerfile*`; `check docker` (`fix.mjs`) обробляє також `Containerfile` та `Containerfile.*`.
 
-Це стримує зайвий build tooling (Bun, **node_modules** зі збірки) у фінальному образі; для **alpine** / **nginx** / **openresty** у **runtime** лишаються лише відповідні вимоги, для **php** / **python** (виняток) — цільовий інтерпретований **stack**; **scratch** і **debian** з тегом **`*slim*`** — коли glibc і мінімальне оточення Debian важливіші за musl в **alpine**.
+## Швидкий gate через conftest
 
-## Мінімальні образи
+[docker-lint_docker_yml](./policy/lint_docker_yml/lint_docker_yml.mdc)
 
-Якщо використовується nginx, то **використовуй** `mirror.gcr.io/nginxinc/nginx-unprivileged:alpine-slim` (і не `latest` / `alpine`).
+[docker-mirror](./js/mirror.mdc)
 
-## компіляція
+[docker-multistage](./js/multistage.mdc)
 
-Якщо проект має bun install крок, та не є фронтенд проектом (тобто не має bun build крок), **і не має нативного `.node`-аддона з динамічним завантаженням** (див. наступну секцію), то потрібно щоб була компіляція коду, і далі у фінальному образі був тільки бінарник і Цей образ не містив компілятора, npm, Bun — тільки runtime libs. Наприклад:
+[docker-compile](./js/compile.mdc)
 
-```dockerfile
-FROM mirror.gcr.io/oven/bun:alpine AS build-env
+[docker-native-addon](./js/native-addon.mdc)
 
-WORKDIR /app
+[docker-non-root](./js/non-root.mdc)
 
-ENV NODE_ENV=production
+[docker-nginx-tag](./js/nginx-tag.mdc)
 
-COPY package.json .
-COPY bunfig.toml .
+[docker-nginx-user](./js/nginx-user.mdc)
 
-RUN bun install --production
-
-COPY ./src ./src
-
-# Компілюємо в бінарник
-RUN bun build --compile --outfile app ./src/index.js
-
-FROM mirror.gcr.io/library/alpine:latest
-
-# (libstdc++ libgcc) для Bun runtime, (tzdata) для часового поясу
-RUN apk add --no-cache libstdc++ libgcc tzdata
-
-WORKDIR /app
-
-COPY --from=build-env /app/app ./app
-
-CMD ["./app"]
-```
-
-### виняток: нативний `.node`-аддон (sharp / @img/* / argon2)
-
-Якщо в `package.json#dependencies` є нативний `.node`-аддон, який вантажиться через **динамічний `require`** — передусім **`sharp`**; той самий клас — **`@img/*`**, **`argon2`** — його **не можна** пакувати через `bun build --compile`.
-
-`bun build --compile` не трейсить `require(\`@img/sharp-${platform}/sharp.node\`)` і не вшиває нативний біндинг → компільований бінарник падає в рантаймі: `Could not load the "sharp" module using the linuxmusl-arm64 runtime`. Доведено реальними docker-збірками (bun 1.3.14, sharp 0.34.5); відтворюється і на darwin-arm64 (тобто не musl/glibc-залежне). `apk add vips` **НЕ лікує** — він дає системний libvips, а бракує саме `sharp.node`.
-
-Канон — ship `node_modules` і запускати через `bun <entry>` на базі `mirror.gcr.io/oven/bun:alpine` (це легітимний виняток до правила «лише alpine/scratch у фінальному stage» — тут потрібен саме bun-рантайм). База `oven/bun` уже має non-root користувача `bun` (uid/gid 1000). Entry бери з наявного `--outfile`-таргета / `package.json#main` / `scripts.start`; якщо не визначити — лиши TODO-маркер, не вгадуй.
-
-Перевіряє **`npm/rules/docker/lib/docker-native-addon.mjs`** (підключено в **`npm/rules/docker/js/lint.mjs`**, точка входу обходу — **`npm/rules/docker/fix.mjs`**). Список нативних аддонів — розширювана константа `NATIVE_ADDON_PACKAGES` / `NATIVE_ADDON_SCOPES` у чек-модулі.
-
-#### Антипатерн (це правило ловить)
-
-```dockerfile
-RUN bun build --compile --outfile app ./src/index.js     # ← з sharp у deps
-FROM mirror.gcr.io/library/alpine:latest
-RUN apk add --no-cache ... vips                           # системний vips не рятує
-COPY --from=build-env --chown=app:app /app/app ./app
-USER app
-CMD ["./app"]
-```
-
-#### Канон (привести до цього)
-
-```dockerfile
-FROM mirror.gcr.io/oven/bun:alpine AS build-env
-WORKDIR /app
-ENV NODE_ENV=production
-COPY package.json .
-RUN bun install --production
-COPY ./src ./src
-
-FROM mirror.gcr.io/oven/bun:alpine
-RUN apk add --no-cache tzdata
-WORKDIR /app
-# база oven/bun має non-root користувача bun (uid/gid 1000)
-COPY --from=build-env --chown=bun:bun /app/node_modules ./node_modules
-COPY --from=build-env --chown=bun:bun /app/src ./src
-COPY --from=build-env --chown=bun:bun /app/package.json ./package.json
-USER bun
-CMD ["bun", "src/index.js"]
-```
-
-Для проєктів **без** нативних аддонів standalone-бінарник на alpine лишається каноном (секція «компіляція» вище).
-
-## не превілейований образ
-
-Для всіх образів потрібно щоб використовувся non-root принцип. **Спосіб** досягнення non-root залежить від **бази**, а не від зміни ОС — змінювати дистрибутив (Alpine→Debian) заради лише non-root **не треба**. Два шляхи:
-
-- **standalone-бінарник на `alpine:latest`** (секція «компіляція») — у `alpine` немає готового non-root користувача, тож його створюємо явно: `addgroup -g 1000 app && adduser -D -u 1000 -G app app` + `COPY --chown=app:app` + `USER app` (приклад нижче);
-- **ship `node_modules` на `mirror.gcr.io/oven/bun:alpine`** (секція «виняток: нативний `.node`-аддон») — користувач `bun` (uid/gid 1000) **уже в базі**, тож достатньо `COPY --chown=bun:bun …` + `USER bun`; базу на Debian-slim міняти **не треба** — це той самий антипатерн, що й у переліку фінальних образів вище.
-
-Приклад для standalone-бінарника на alpine:
-
-```dockerfile
-# Stage 1
-FROM oven/bun:alpine AS build-env
-WORKDIR /app
-COPY package.json bunfig.toml .
-RUN bun install --production
-COPY ./src ./src
-RUN bun build --compile --outfile app ./src/index.js
-
-# Stage 2
-FROM alpine:latest
-RUN apk add --no-cache libstdc++ libgcc tzdata
-
-# ✅ Додати non-root user
-RUN addgroup -g 1000 app && adduser -D -u 1000 -G app app
-
-WORKDIR /app
-
-# ✅ Змінити власника файлу
-COPY --from=build-env --chown=app:app /app/app ./app
-
-# ✅ Запускати як non-root
-USER app
-
-CMD ["./app"]
-
-```
-
-### nginx-unprivileged — без USER, із --chown
-
-Окрема гілка для фронтенду на базі **`nginxinc/nginx-unprivileged`** (будь-який тег, з/без `mirror.gcr.io/`-префікса). Цей образ **уже** оголошує `USER 101` і `EXPOSE 8080`, тож у фінальному stage **не потрібні** жодні явні `USER`-інструкції:
-
-- **жодного `USER root` / `USER 0`** для білд-кроків: він перезатирає успадкований `USER 101`, і якщо потім не повернути non-root — фінальний образ лишається root, а k8s із `runAsNonRoot: true` падає з `CreateContainerConfigError`;
-- **жодного switch-back** `USER 101` / `USER nginx` наприкінці stage — це лише симптом зайвого `USER root` на початку (повертати треба саме **числовим** UID, бо kubelet не підтверджує non-root за іменем `nginx`). Канон — взагалі не виходити з-під дефолтного 101;
-- **`COPY`/`ADD` лише з `--chown`** (канон — `--chown=nginx:nginx`): без нього файли копіюються власником root і дефолтний non-root користувач (uid=101) не зможе читати статику.
-
-Build-stage не чіпаємо — там root і tooling норма. Перевіряє **`npm/rules/docker/lib/docker-nginx-user.mjs`** (підключено в **`npm/rules/docker/js/lint.mjs`**, точка входу обходу — **`npm/rules/docker/fix.mjs`**).
-
-#### Антипатерн (це правило ловить)
-
-```dockerfile
-FROM mirror.gcr.io/nginxinc/nginx-unprivileged:alpine-slim
-USER root
-COPY ./k8s/nginx.conf /etc/nginx/conf.d/default.conf
-COPY --from=build /app/dist ./
-RUN find ./ -type f -name "*.js" -exec gzip -k {} \;
-USER 101          # повернення назад — симптом того, що був зайвий USER root
-EXPOSE 8080
-```
-
-#### Канон (привести до цього)
-
-```dockerfile
-FROM mirror.gcr.io/nginxinc/nginx-unprivileged:alpine-slim
-
-COPY --chown=nginx:nginx ./k8s/nginx.conf /etc/nginx/conf.d/default.conf
-
-WORKDIR /usr/share/nginx/html
-
-COPY --from=build --chown=nginx:nginx /app/dist ./
-
-RUN find ./ -type f -name "*.js" -exec gzip -k {} \;
-```
-
-(без жодного `USER`, gzip під дефолтним користувачем 101; `EXPOSE 8080` теж зайвий — база вже його оголошує)
-
-## Область
-
-- Усі файли з іменем **`Dockerfile`** або **`Dockerfile.*`** (наприклад `Dockerfile.prod`) у репозиторії, крім ігнорованих каталогів (`node_modules`, `.git`, `dist`, …) — як у **`rules/docker/fix.mjs`**.
-- Також скрипт перевірки обробляє **`Containerfile`** та **`Containerfile.*`** (Podman / альтернативні імена), навіть якщо glob правила спрацьовує переважно на `Dockerfile*`.
-
-## lint-docker
-
-CLI **`hadolint`** приймає лише **явні шляхи** (`[DOCKERFILE...]` у **`hadolint --help`**); обхід репозиторію робить правило **`n-cursor lint docker`** (реалізація — **`npm/rules/docker/js/lint.mjs`**).
-
-**Область lint-docker (вужча, ніж `check docker`):** лише файли з іменем **`Dockerfile`** та **`*.Dockerfile`** (суфікс **`.dockerfile`** без урахування регістру, наприклад **`api.Dockerfile`**). Файли **`Dockerfile.prod`**, **`Containerfile`** тощо **не** входять у **`lint-docker`**; їх ловить **`check docker`** (`rules/docker/fix.mjs`).
-
-Обхід: **`walkDir`** з тими самими пропусками каталогів, що й **`rules/docker/fix.mjs`**. Виклик **`hadolint`** як **нативного бінарника** через **`ensureTool`** (PATH → кеш → авто-install brew/scoop/GitHub Release; **без** `docker run`) — спільна логіка **`npm/rules/docker/lib/docker-hadolint.mjs`**.
-
-Окремий `package.json`-скрипт `lint-docker` не потрібен і не перевіряється — єдина точка входу для правила: **`n-cursor lint docker`**.
-
-Додай workflow **`.github/workflows/lint-docker.yml`** (гілки **`dev`** і **`main`**, лише **`.yml`**, узгоджено з **`ga.mdc`**):
-
-- Канон: [lint-docker.yml.snippet.yml](./policy/lint_docker_yml/template/lint-docker.yml.snippet.yml)
-
-Локально hadolint авто-встановлюється через **`ensureTool`** (latest, без піну версії). У CI встанови його кроком із workflow-сніпета (curl-download бінарника — без `docker run`).
-
-## Запуск
-
-1. **`n-cursor lint docker`** — **`js/lint.mjs`**: **`Dockerfile`** та **`*.Dockerfile`** (див. **`lint-docker`**); у CI використовуй **`n-cursor lint docker --read-only`** і встанови hadolint (приклад у workflow).
-2. **`npx @nitra/cursor fix docker`** — **`rules/docker/fix.mjs`**, виклик hadolint як у **`docker-hadolint.mjs`** (нативний бінарник через **`ensureTool`**; **без** `docker run`).
-3. Кореневий **`.hadolint.yaml`**: вимкнення правил, trusted registries — [документація](https://github.com/hadolint/hadolint#configure). Щоб не додавати **`# hadolint ignore=DL3007`** у кожному **`FROM`** з **`:latest`**, у корені репозиторію задати глобально:
-
-```yaml title=".hadolint.yaml"
-ignored:
-  - DL3007
-  - DL3008
-  - DL3018
-```
-
-Де DL3007 - «Не використовуй тег latest у FROM»
-Де DL3018 - «Піни версії пакетів у apk add»
-
-Якщо немає файлів у межах відповідного набору (**`lint-docker`** або **`check docker`**) — перевірка пропускається (exit 0).
-
-Винятки: **`# hadolint ignore=DL3008`** (або інший код) у Dockerfile або **`ignored`** у **`.hadolint.yaml`** (наприклад **DL3007** для **`:latest`** — див. вище).
+[docker-hadolint](./js/hadolint.mdc)

package/rules/docker/policy/lint_docker_yml/lint_docker_yml.mdc

@@ -0,0 +1,14 @@
+## Перевірка `.github/workflows/lint-docker.yml`
+
+Rego-пакет: `docker.lint_docker_yml`
+
+Цільовий файл: `.github/workflows/lint-docker.yml`
+
+Перевіряє, що CI-workflow lint-docker відповідає канонічному сніпету:
+
+- `on.push.paths` містить усі три glob-маски: `**/Dockerfile`, `**/*.Dockerfile`, `**/*.dockerfile`
+- присутні кроки `uses: actions/checkout@v6` та `uses: ./.github/actions/setup-bun-deps`
+- крок install hadolint містить рядок із версією `v2.12.0` (substring-перевірка)
+- крок lint містить `n-cursor lint docker --read-only`
+
+Канонічний шаблон: [lint-docker.yml.snippet.yml](./template/lint-docker.yml.snippet.yml)

package/rules/efes/main.mdc

@@ -20,4 +20,4 @@ bun add -d @nitra/efes-shared
 
 Пакети (директорія в **`npm/rules/efes/policy/`** → namespace → що перевіряє):
 
-- **`package_json_shared/`** → `efes.package_json_shared` — у кореневому `package.json` `devDependencies` має містити `@nitra/efes-shared` (presence-only, версію не фіксуємо). **Цільові файли:** `package.json`.
+[efes-package_json_shared](./policy/package_json_shared/package_json_shared.mdc)

package/rules/efes/policy/package_json_shared/package_json_shared.mdc

@@ -0,0 +1,30 @@
+## Наявність `@nitra/efes-shared` у `devDependencies`
+
+Rego-пакет: `efes.package_json_shared`
+
+**Цільовий файл:** `package.json` (корінь проєкту, обовʼязковий).
+
+**Що перевіряється:** у `devDependencies` кореневого `package.json` має бути ключ `@nitra/efes-shared`. Версію не фіксуємо — лише presence. Наявність лише у `dependencies` (не `devDependencies`) — теж помилка.
+
+**Виправлення:**
+
+```bash
+bun add -d @nitra/efes-shared
+```
+
+**Приклади:**
+
+✓ правильно — `devDependencies` містить пакет:
+```json
+{ "devDependencies": { "@nitra/efes-shared": "^1.0.0" } }
+```
+
+✗ неправильно — `devDependencies` відсутній або порожній:
+```json
+{ "name": "my-project" }
+```
+
+✗ неправильно — пакет лише у `dependencies`:
+```json
+{ "dependencies": { "@nitra/efes-shared": "^1.0.0" } }
+```

package/rules/ga/js/lint_toolchain.mdc

@@ -0,0 +1,15 @@
+## Лінт-тулчейн: actionlint, zizmor, n-cursor lint ga
+
+**Лінт:** [actionlint](https://github.com/rhysd/actionlint) через [github-actionlint](https://www.npmjs.com/package/github-actionlint); [zizmor](https://docs.zizmor.sh) — `uvx`, офлайн. Запуск — через **`n-cursor lint ga`** (CI — `--read-only`; бінарка з `node_modules/.bin/` пакету `@nitra/cursor`), який робить preflight на `shellcheck` і послідовно запускає `actionlint` та `zizmor`. Окремого `package.json`-скрипта немає.
+
+> Виклик через bin-ім'я `n-cursor` (а **не** `npx @nitra/cursor`): `bun x`/`npx` для скоупованого пакету з одним bin-ім'ям повертає 0 без виконання, тому в CI-кроці `run:` використовуй саме `n-cursor lint <rule>`.
+
+CLI робить preflight на `shellcheck` і `uv` (`uvx`) у `PATH`, потім запускає `bunx github-actionlint` і `uvx zizmor --offline --collect=workflows .`.
+
+Послідовність кроків `n-cursor lint ga`:
+
+1. `ensureTool`: `shellcheck` і `conftest` (авто-install або hard-fail)
+2. preflight: `uv` (для `uvx zizmor`) — hint-only, без авто-install
+3. `bunx github-actionlint`
+4. `uvx zizmor --offline --collect=workflows .`
+5. `rules/ga/check()` — Rego-полісі (батч conftest з `npm/policy/ga/`) + JS cross-file перевірки правил `ga.mdc`

package/rules/ga/js/required_workflows.mdc

@@ -0,0 +1,35 @@
+## Канонічні обов'язкові workflow-файли
+
+Кожен з цих файлів перевіряється окремим Rego-пакетом через conftest з відповідним `--namespace`.
+
+### `clean-ga-workflows.yml`
+
+Очищення старих GitHub Actions workflow runs за розкладом.
+
+- Канон: [clean-ga-workflows.yml.snippet.yml](./policy/clean_ga_workflows/template/clean-ga-workflows.yml.snippet.yml)
+
+Rego-пакет `ga.clean_ga_workflows` перевіряє: `name`, `on.schedule[].cron`, `workflow_dispatch: {}`, `jobs.cleanup_old_workflows`, `runs-on`, `permissions` (actions: write, contents: read), перший крок (`uses`, `with.token`, `with.save_period`, `with.save_min_runs_number`).
+
+### `clean-merged-branch.yml`
+
+Видалення злитих гілок за розкладом та вручну.
+
+- Канон: [clean-merged-branch.yml.snippet.yml](./policy/clean_merged_branch/template/clean-merged-branch.yml.snippet.yml)
+
+Інші гілки в `ignore_branches` — допустимо. Rego-пакет `ga.clean_merged_branch` перевіряє: `name`, `on.schedule[].cron`, `workflow_dispatch: {}`, `jobs.cleanup_old_branches`, `permissions`, крок 0 (`id`, `uses`, `with.github_token`, `with.last_commit_age_days`, `with.ignore_branches`, `with.dry_run: no`), крок 1 (name, env.DELETED_BRANCHES, run з echo Deleted branches).
+
+### `lint-ga.yml`
+
+CI-лінт GitHub Actions workflows через actionlint + zizmor.
+
+- Канон: [lint-ga.yml.snippet.yml](./policy/lint_ga/template/lint-ga.yml.snippet.yml)
+
+Rego-пакет `ga.lint_ga` перевіряє: `name`, `on.push.branches` і `on.pull_request.branches` (мають містити dev і main), `on.push.paths` (мають містити `.github/actions/**` і `.github/workflows/**`), `jobs.lint-ga`, `runs-on`, `permissions.contents`, наявність кроку Install conftest, крок `run: n-cursor lint ga --read-only`.
+
+### `git-ai.yml`
+
+Автоматизація PR-коментарів через git-ai CI.
+
+- Канон: [git-ai.yml.snippet.yml](./policy/git_ai/template/git-ai.yml.snippet.yml)
+
+Rego-пакет `ga.git_ai` перевіряє: `name`, `on.pull_request.types` (має містити `closed`), `jobs.git-ai`, умову `if:` job (merged PR), `permissions.contents`, наявність кроку встановлення (`https://usegitai.com/install.sh`) та запуску (`git-ai ci github run`).

package/rules/ga/js/vscode.mdc

@@ -0,0 +1,17 @@
+## VS Code — розширення та налаштування для GitHub Actions
+
+### `.vscode/extensions.json`
+
+Має рекомендувати `github.vscode-github-actions`:
+
+- Канон: [extensions.json.snippet.json](./policy/vscode_extensions/template/extensions.json.snippet.json)
+
+Rego-пакет `ga.vscode_extensions`: кожне розширення з template має бути в `recommendations`. Додаткові рекомендації від інших правил — допустимі.
+
+### `.vscode/settings.json`
+
+Для мови `github-actions-workflow` має `editor.defaultFormatter = "oxc.oxc-vscode"`:
+
+- Канон: [settings.json.snippet.json](./policy/vscode_settings/template/settings.json.snippet.json)
+
+Rego-пакет `ga.vscode_settings`: перевіряє всі ключі з template у відповідному language-block.