@rt-tools/agent-kit 0.22.0 → 0.23.0

package/lib/push-gate.js

@@ -0,0 +1,93 @@
+/**
+ * Набор проверок перед пушем — итоговый и снятое из умолчания.
+ *
+ * Набор собирается из двух файлов: умолчания пакета и надстройки профиля дерева. Результат
+ * сборки не показывался нигде — чтобы его прочитать, надо было звать функцию профиля руками из
+ * оболочки. Из этой невидимости выросли три разных промаха: дерево дописало в надстройку команду,
+ * уже стоявшую в умолчании, и гоняло проверку дважды за пуш; другое дерево выкусило из умолчания
+ * сплошную проверку одной строкой `rt_push_checks_default "$@" | grep -v …` — строка выглядела
+ * настройкой, а была снятием охраны; а расхождение набора с конвейером узнавалось из красного
+ * конвейера после заявки.
+ *
+ * Набор ЗОВЁТСЯ, а не пересказывается чтением: он ветвится по содержимому дерева — есть ли
+ * настройка раскладки, есть ли конфиг линтера стилей, какие проверки разложены, — и разобранный
+ * по тексту функции разойдётся с настоящим молча.
+ *
+ * ОТКАЗ В ПОЛЬЗУ ЧИТАТЕЛЯ: нет профиля, нет функции, вызов упал или завис — раздела нет, а
+ * причина названа строкой. Разбор состояния ничего не пишет, и своим отказом чинить тут нечего.
+ */
+import { execFileSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+/** Имя функции профиля, собирающей набор, и имя её умолчания. */
+const PUSH_CHECKS = 'rt_push_checks';
+const PUSH_CHECKS_DEFAULT = `${PUSH_CHECKS}_default`;
+/** Сколько ждать сборки набора. Сама она ничего не гоняет — печатает строки. */
+const TIMEOUT_MS = 10_000;
+/**
+ * Строки, которые вернула названная функция профиля. Профиль собирается из тех же файлов и в том
+ * же порядке, что читает сам гард: сперва разложенное умолчание пакета, поверх — надстройка
+ * дерева. Судить по одной надстройке значило бы получить пустой набор у всякого дерева, которое
+ * умолчаний не переписывало.
+ */
+function callProfile(root, defaults, fn) {
+    const sources = [join(root, defaults, 'project.sh'), join(root, '.claude/rt-kit', 'project.sh')].filter((one) => existsSync(one));
+    if (!sources.length) {
+        return null;
+    }
+    // База пустая: с ней умолчание печатает полный набор, а не набор по вкладу ветки. Разбор
+    // состояния читают, чтобы увидеть набор целиком, а не тот, что выпал бы на сегодняшнюю ветку.
+    const script = sources.map((one) => `. ${JSON.stringify(one)} 2>/dev/null`).join('; ') +
+        `; command -v ${fn} >/dev/null 2>&1 || exit 3; ${fn} ''`;
+    try {
+        // Полный путь к оболочке, а не имя: имя разрешается через `PATH`, а он в чужой среде
+        // бывает записываемым — тогда «bash» указывает не туда. Ищется он тем же способом, каким
+        // ищут его хуки: в двух местах, где оболочка лежит на всякой машине.
+        const shell = ['/bin/bash', '/usr/bin/bash'].find((one) => existsSync(one)) ?? '/bin/bash';
+        const out = execFileSync(shell, ['-c', script], {
+            cwd: root,
+            encoding: 'utf8',
+            timeout: TIMEOUT_MS,
+            stdio: ['ignore', 'pipe', 'ignore'],
+        });
+        return out
+            .split('\n')
+            .map((line) => line.trim())
+            .filter((line) => line.length > 0);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Итоговый набор перед пушем и то, что печатало умолчание, а в итог не попало.
+ *
+ * Разница считается по вызовам, а не по признаку переопределения: дерево, переписавшее функцию
+ * целиком и вернувшее тот же набор, из умолчания не убрало ничего, а дерево, дописавшее фильтр,
+ * убрало — и по одному факту переопределения эти два случая неразличимы.
+ *
+ * Названа разница ровно тем, что она есть: строкой умолчания, которой в итоге нет. Снятием
+ * охраны она НЕ называется — дерево могло заменить команду своим вариантом, зовущим ту же
+ * проверку другим прогонщиком, и такая замена выглядит отсюда точно так же. Что из двух
+ * случилось, видно только в надстройке, и читает её человек.
+ */
+export function pushGateLines(root, defaults) {
+    const final = callProfile(root, defaults, PUSH_CHECKS);
+    if (final === null) {
+        return ['набор перед пушем: собрать не удалось — нет профиля дерева либо функции rt_push_checks'];
+    }
+    const base = callProfile(root, defaults, PUSH_CHECKS_DEFAULT);
+    const cut = base === null ? [] : base.filter((one) => !final.includes(one));
+    return [
+        `набор перед пушем: ${final.length}`,
+        ...final.map((one) => `  ${one}`),
+        ...(cut.length
+            ? [
+                `умолчание печатало, а в наборе нет: ${cut.length}`,
+                ...cut.map((one) => `  ${one}`),
+                '  это либо снятие охраны, либо замена своим вариантом той же проверки — различает их надстройка профиля',
+            ]
+            : []),
+    ];
+}
+//# sourceMappingURL=push-gate.js.map

package/lib/push-gate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"push-gate.js","sourceRoot":"","sources":["../../../projects/agent-kit/src/lib/push-gate.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Набор проверок перед пушем — итоговый и снятое из умолчания.\n *\n * Набор собирается из двух файлов: умолчания пакета и надстройки профиля дерева. Результат\n * сборки не показывался нигде — чтобы его прочитать, надо было звать функцию профиля руками из\n * оболочки. Из этой невидимости выросли три разных промаха: дерево дописало в надстройку команду,\n * уже стоявшую в умолчании, и гоняло проверку дважды за пуш; другое дерево выкусило из умолчания\n * сплошную проверку одной строкой `rt_push_checks_default \"$@\" | grep -v …` — строка выглядела\n * настройкой, а была снятием охраны; а расхождение набора с конвейером узнавалось из красного\n * конвейера после заявки.\n *\n * Набор ЗОВЁТСЯ, а не пересказывается чтением: он ветвится по содержимому дерева — есть ли\n * настройка раскладки, есть ли конфиг линтера стилей, какие проверки разложены, — и разобранный\n * по тексту функции разойдётся с настоящим молча.\n *\n * ОТКАЗ В ПОЛЬЗУ ЧИТАТЕЛЯ: нет профиля, нет функции, вызов упал или завис — раздела нет, а\n * причина названа строкой. Разбор состояния ничего не пишет, и своим отказом чинить тут нечего.\n */\nimport { execFileSync } from 'node:child_process';\nimport { existsSync } from 'node:fs';\nimport { join } from 'node:path';\n\n/** Имя функции профиля, собирающей набор, и имя её умолчания. */\nconst PUSH_CHECKS: string = 'rt_push_checks';\nconst PUSH_CHECKS_DEFAULT: string = `${PUSH_CHECKS}_default`;\n\n/** Сколько ждать сборки набора. Сама она ничего не гоняет — печатает строки. */\nconst TIMEOUT_MS: number = 10_000;\n\n/**\n * Строки, которые вернула названная функция профиля. Профиль собирается из тех же файлов и в том\n * же порядке, что читает сам гард: сперва разложенное умолчание пакета, поверх — надстройка\n * дерева. Судить по одной надстройке значило бы получить пустой набор у всякого дерева, которое\n * умолчаний не переписывало.\n */\nfunction callProfile(root: string, defaults: string, fn: string): readonly string[] | null {\n    const sources: readonly string[] = [join(root, defaults, 'project.sh'), join(root, '.claude/rt-kit', 'project.sh')].filter(\n        (one: string): boolean => existsSync(one)\n    );\n    if (!sources.length) {\n        return null;\n    }\n\n    // База пустая: с ней умолчание печатает полный набор, а не набор по вкладу ветки. Разбор\n    // состояния читают, чтобы увидеть набор целиком, а не тот, что выпал бы на сегодняшнюю ветку.\n    const script: string =\n        sources.map((one: string): string => `. ${JSON.stringify(one)} 2>/dev/null`).join('; ') +\n        `; command -v ${fn} >/dev/null 2>&1 || exit 3; ${fn} ''`;\n\n    try {\n        // Полный путь к оболочке, а не имя: имя разрешается через `PATH`, а он в чужой среде\n        // бывает записываемым — тогда «bash» указывает не туда. Ищется он тем же способом, каким\n        // ищут его хуки: в двух местах, где оболочка лежит на всякой машине.\n        const shell: string = ['/bin/bash', '/usr/bin/bash'].find((one: string): boolean => existsSync(one)) ?? '/bin/bash';\n        const out: string = execFileSync(shell, ['-c', script], {\n            cwd: root,\n            encoding: 'utf8',\n            timeout: TIMEOUT_MS,\n            stdio: ['ignore', 'pipe', 'ignore'],\n        });\n\n        return out\n            .split('\\n')\n            .map((line: string): string => line.trim())\n            .filter((line: string): boolean => line.length > 0);\n    } catch {\n        return null;\n    }\n}\n\n/**\n * Итоговый набор перед пушем и то, что печатало умолчание, а в итог не попало.\n *\n * Разница считается по вызовам, а не по признаку переопределения: дерево, переписавшее функцию\n * целиком и вернувшее тот же набор, из умолчания не убрало ничего, а дерево, дописавшее фильтр,\n * убрало — и по одному факту переопределения эти два случая неразличимы.\n *\n * Названа разница ровно тем, что она есть: строкой умолчания, которой в итоге нет. Снятием\n * охраны она НЕ называется — дерево могло заменить команду своим вариантом, зовущим ту же\n * проверку другим прогонщиком, и такая замена выглядит отсюда точно так же. Что из двух\n * случилось, видно только в надстройке, и читает её человек.\n */\nexport function pushGateLines(root: string, defaults: string): string[] {\n    const final: readonly string[] | null = callProfile(root, defaults, PUSH_CHECKS);\n    if (final === null) {\n        return ['набор перед пушем: собрать не удалось — нет профиля дерева либо функции rt_push_checks'];\n    }\n\n    const base: readonly string[] | null = callProfile(root, defaults, PUSH_CHECKS_DEFAULT);\n    const cut: readonly string[] = base === null ? [] : base.filter((one: string): boolean => !final.includes(one));\n\n    return [\n        `набор перед пушем: ${final.length}`,\n        ...final.map((one: string): string => `  ${one}`),\n        ...(cut.length\n            ? [\n                  `умолчание печатало, а в наборе нет: ${cut.length}`,\n                  ...cut.map((one: string): string => `  ${one}`),\n                  '  это либо снятие охраны, либо замена своим вариантом той же проверки — различает их надстройка профиля',\n              ]\n            : []),\n    ];\n}\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rt-tools/agent-kit",
-  "version": "0.22.0",
+  "version": "0.23.0",
   "description": "Переносимый слой правил для агента: законы, хуки, проверки и агенты, раскладываемые в репозиторий одной командой",
   "author": "RT Team",
   "license": "Apache-2.0",

package/assets/laws/application/access.md

@@ -1,34 +0,0 @@
-# Закон о доступе
-
-Кто что может делать: вход владельца, права на действия, поведение публичных путей.
-Правила держат все процедуры контракта и все разделы админки.
-
-## Терминология
-
-| Термин         | Определение                                                                                 |
-| -------------- | ------------------------------------------------------------------------------------------- |
-| Право          | Пара «ресурс и действие», например `bookings:manage`. Не роль: роль набирается из прав      |
-| Пресет         | Именованный набор прав, который выдаётся пользователю целиком                               |
-| Оверрайд       | Точечная правка права поверх пресета для одного пользователя                                |
-| Публичный путь | Процедура, доступная гостю без входа. Публичность объявляется, а не получается по умолчанию |
-
-## Статьи
-
-- **Каждая процедура объявляет свой доступ, и объявление ровно одно.** Процедура без
-  объявления или с двумя объявлениями не даёт приложению подняться.
-- **Доступов четыре: по праву, любому вошедшему, публично и публично с чтением входа.**
-  Последний отдаёт вошедшему больше, чем гостю, — так админ видит скрытые объекты в общем
-  списке.
-- **Права пользователя — это права пресета, поверх которых применены его оверрайды.**
-- **Запрос без входа туда, где вход нужен, отбивается как неаутентифицированный, а вход
-  без нужного права — как отказ в доступе.** Это разные ответы: первый лечится входом,
-  второй — нет.
-- **Право проверяется до тела процедуры.** Обработчик не решает, пускать ли вызывающего.
-- **Публичность объявляется с причиной.** Причина живёт в коде рядом с объявлением и
-  наружу не уходит.
-- **Админка не показывает разделы, на которые у владельца нет права.**
-- **Адрес раздела закрыт тем же правом, что и пункт меню.** Иначе скрытый пункт закрывает
-  раздел лишь на вид: адрес открывается по прямой ссылке.
-- **Пока права не получены, админка ничего не прячет.** Пустая шапка после сетевого сбоя
-  выглядит как сломанная админка и не оставляет выхода; запрос без права всё равно
-  отобьётся на сервере.

package/assets/laws/application/locales.md

@@ -1,33 +0,0 @@
-# Закон о локалях и переводах
-
-Как в системе устроены языки: адреса публичного сайта, подписи интерфейса, переводы
-контента и язык админки. Правила держат сайт, админку, письма и документ-подтверждение
-одновременно.
-
-## Терминология
-
-| Термин           | Определение                                                                                                                                |
-| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
-| Локаль сайта     | Один из восьми языков, на которых существует публичный сайт. Не то же, что валюта показа: валюта у локали лишь начальная и меняется гостем |
-| Локаль ввода     | Язык, на котором владелец написал текст объекта. Задаёт истину: остальные семь считаются производными                                      |
-| Словарь          | Набор подписей интерфейса для одной локали. Живёт в репозитории, а не в базе                                                               |
-| Перевод контента | Текст объекта на локали, отличной от локали ввода. Живёт в базе и заполняется системой                                                     |
-
-## Статьи
-
-- **Локаль по умолчанию отдаётся из корня, остальные семь — из-под префикса пути.**
-- **Видимый человеку текст интерфейса берётся из словарей и заводится во всех восьми
-  локалях.** Ключ, потерянный в одной локали, гость видит на кнопке как есть.
-- **Пустой перевод считается пропуском, а не переводом.** На экране он выглядит как
-  задуманный: кнопка без подписи, заголовок без текста.
-- **Переводы контента производные: владелец пишет текст на своём языке, остальные семь
-  локалей заполняет система при сохранении.** Табов локалей в формах нет — правка вручную
-  всё равно была бы перезаписана.
-- **Отказ перевода сохранение не срывает.** Текст на локали ввода записывается, прежние
-  переводы остаются, и владелец видит предупреждение, а не сообщение об успехе.
-- **Локаль, для которой перевода не пришло, сохраняет прежнее значение.** Половина ответа
-  лучше пустого описания на витрине.
-- **Язык админки выбирает владелец, и выбор живёт в его профиле.** Он же уходит в локаль
-  ввода при сохранении объекта.
-- **У локали есть начальная валюта показа.** Дальше валюту выбирает гость, и его выбор
-  сильнее умолчания локали.

package/assets/laws/application/search-visibility.md

@@ -1,24 +0,0 @@
-# Закон о видимости в поиске
-
-Как публичный сайт выглядит для поисковика. Страница живёт в нескольких языках под одним
-доменом, и от разметки зависит, считает поисковик эти адреса одной страницей на разных
-языках или дублями друг друга. Ошибка здесь не видна ни в сборке, ни в браузере: она
-проявляется падением выдачи через недели.
-
-## Статьи
-
-- **У страницы один канонический адрес — её собственный, на её языке.** Общий канонический
-  адрес на все языки означает, что остальные версии объявлены копиями и в выдачу не попадут.
-- **Разметка страницы при переходе переписывается, а не накапливается.** Иначе на второй
-  открытой странице остаётся описание первой, и два адреса объявляют один канонический.
-- **Языковая версия объявляется поисковику только тогда, когда её перевод готов.** Позвать
-  поисковика на страницу, где текст остался на чужом языке, — значит отдать дубль под
-  неверным языковым тегом.
-- **Страница объявляет себя структурированными данными.** Без них поисковик разбирает
-  содержимое догадками.
-- **Карта сайта строится из живых данных, а не из файла.** Файл устаревает молча в тот же
-  день, когда добавили страницу.
-- **Прежний адрес страницы ведёт на новый постоянным перенаправлением.** Смена адреса без
-  перенаправления обнуляет накопленный вес страницы.
-- **Перенаправление с прежнего адреса живёт в кэше наравне со страницами.** Некэшируемое
-  перенаправление не вытесняет из кэша старую страницу, и гость видит её ещё сутки.

package/assets/patterns/permissions-procedure.md

@@ -1,71 +0,0 @@
----
-name: permissions-procedure
-kind: pattern
-rule: permissions
-description: Паттерн правила permissions. Брать при заведении процедуры Connect и при закрытии раздела админки — готовые декораторы доступа, отбивка без входа и без права, декларация пункта меню с правом и флагом. Не брать для устройства самого меню — это правило navigation.
----
-
-# Объявление доступа
-
-Паттерн правила `permissions`. Что при этом должно быть верно — закон
-`docs/constitution/application/access.md`.
-
-## Когда брать
-
-- Заводится процедура Connect.
-- Раздел админки закрывается правом.
-- Процедура должна отвечать гостю.
-
-## Декоратор на классе процедуры
-
-Объявление ровно одно; без него приложение не поднимается:
-
-```typescript
-@Injectable()
-@ConnectProcedure()
-@RequiresPermission('chat:manage')
-export class LinkBookingProcedure implements IConnectProcedure<typeof ChatService.method.linkBooking> {
-    public readonly method: typeof ChatService.method.linkBooking = ChatService.method.linkBooking;
-}
-```
-
-| Декоратор                                    | Кому доступно                                     |
-| -------------------------------------------- | ------------------------------------------------- |
-| `@RequiresPermission('<ресурс>:<действие>')` | вошедшему с этим правом                           |
-| `@RequiresAuth('<причина>')`                 | любому вошедшему; так живут профиль и выбор языка |
-| `@PublicProcedure('<причина>')`              | гостю без входа                                   |
-| `@OptionalAuthProcedure('<причина>')`        | гостю, но токен читается, если он есть            |
-
-Аргумент — причина для читателя кода. Ни в ответ, ни в лог она не уходит.
-
-## Отбивка
-
-Перехватчик отвечает до тела процедуры:
-
-- нет входа там, где вход нужен, — `Code.Unauthenticated`;
-- вход есть, права нет — `Code.PermissionDenied`;
-- процедура, о которой перехватчик ничего не знает, — тоже отказ в доступе, а не пропуск.
-
-Обработчик решения о допуске не принимает.
-
-## Раздел админки
-
-Пункт меню и адрес закрываются одной декларацией в
-`libs/admin/common/container/util`: шапка берёт из неё подписи и адреса, гвард — права.
-Второго объявления этой связи не заводится.
-
-Гейтинг двухслойный: право пользователя и флаг раздела. Пункт с флагом объявляется без прав и
-без адреса — право открывает экран, а экрана нет. Появится экран — флаг снимается, права
-добавляются.
-
-## Частые промахи
-
-- Два объявления доступа на одной процедуре: приложение не поднимется, и увидено это будет
-  только при запуске.
-- Проверка права внутри `handle`: право проверяется до тела.
-- Своё объявление прав рядом с маршрутами: оно разойдётся с декларацией меню, и получится
-  «пункта не видно, а страница открывается».
-- Гвард, повешенный на защищённую группу целиком: он отрабатывает один раз за загрузку
-  страницы и переходов между разделами не видит.
-- Ожидание прав, которое роняется на отказе запроса: с неизвестными правами не закрывается
-  ничего, и пустая шапка выхода владельцу не оставляет.

package/assets/patterns/seo-page.md

@@ -1,104 +0,0 @@
----
-name: seo-page
-kind: pattern
-rule: seo
-description: Паттерн правила seo. Брать, когда правится разметка страницы публичного сайта, заводится маршрут или страница должна попасть в карту сайта: готовый вызов службы мета-тегов, ветки локалей, строка карты. Проверка отданной разметки — паттерн seo-verify.
----
-
-# Разметка страницы публичного сайта
-
-Паттерн правила `seo`. Что при этом должно быть верно — закон
-`docs/constitution/application/search-visibility.md`.
-
-## Когда брать
-
-- Правится шаблон страницы сайта, её заголовок, описание или картинка для соцсетей.
-- Заводится новый маршрут сайта.
-- Появилась страница, которая должна попасть в `sitemap.xml`.
-
-## Разметку ставит сервис, а не шаблон
-
-Страница собирает данные и одним вызовом отдаёт их `PropertySeoService`. Своих `<meta>` в
-шаблоне не заводить: они не помечены `data-<префикс>-seo`, не переписываются при переходе и
-переживут смену страницы.
-
-Образец — `property-page.component.ts:#applySeo`:
-
-```typescript
-readonly #seo: PropertySeoService = inject(PropertySeoService);
-
-constructor() {
-    effect((): void => this.#applySeo());
-}
-
-#applySeo(): void {
-    const property: IProperty.State | null = this.property();
-    if (!property) {
-        return;
-    }
-
-    const name: string = this.propertyName();
-    const cover: IPhotoView | null = this.coverDesktop();
-
-    this.#seo.apply({
-        property,
-        name,
-        pageTitle: name ? `${name} — ${this.#titleSuffix()}` : this.#titleSuffix(),
-        description: property.shortDescription || this.#descriptionFallback(),
-        ogImageUrl: cover ? photoOgUrl(cover.baseUrl) : `${SITE_ORIGIN}/${BRAND_OG_IMAGE}`,
-        ogImageAlt: cover ? cover.alt : name,
-        ogImageWidth: OG_IMAGE_WIDTH,
-        ogImageHeight: OG_IMAGE_HEIGHT,
-        locale: this.#localeId,
-    });
-}
-```
-
-Вызов идёт из `effect`, а не из конструктора напрямую: объект приходит сигналом, и на первом
-кадре его ещё нет. Ранний выход по пустому объекту обязателен — без него разметка встала бы на
-пустых значениях и второй раз уже не переписалась бы.
-
-У картинки есть запасной вариант: объект без обложки отдаёт брендовое изображение того же формата,
-иначе превью в соцсети пустует.
-
-## Новый маршрут заводится веткой на каждую локаль
-
-Ветки собирает `apps/site/src/app/app.routes.ts` из `LOCALE_CODES`. Локаль по умолчанию своей
-ветки не имеет — она отдаётся из корня.
-
-```typescript
-export const appRoutes: Route[] = [
-    ...LOCALE_CODES.filter((code: ELocale): boolean => code !== DEFAULT_LOCALE).map((code: ELocale): Route => ({
-        path: code,
-        children: propertyRoutes,
-    })),
-    ...propertyRoutes,
-];
-```
-
-Новый путь дописывается в `propertyRoutes` — тогда он появляется во всех восьми ветках сразу.
-Ветки перечислены явными кодами, а не `:locale`: иначе `/<адрес страницы>` был бы принят за
-язык, а не за адрес объекта.
-
-## Страница попадает в карту сайта явно
-
-Карта строится из объектов, а не из маршрутов, и новая страница сама туда не попадёт. Записи
-собирает `buildSitemap` (слой `util` домена страницы объекта), отдаёт обработчик
-`/sitemap.xml` в `apps/site/src/server.ts`. Правка идёт вместе со спекой в
-`sitemap.util.spec.ts`.
-
-## Тексты идут из словарей
-
-`pageTitle` и `description` собираются из переведённых значений и заводятся во всех восьми
-локалях. Без перевода они уезжают в выдачу по-английски, и заметно это только в чужой локали.
-
-## Частые промахи
-
-- `<meta>` в шаблоне вместо вызова сервиса — тег не помечен `data-<префикс>-seo` и переживёт переход.
-- Вызов без раннего выхода по пустому объекту — разметка встаёт на пустых значениях.
-- Новый путь дописан мимо `propertyRoutes` — работает только в локали по умолчанию,
-  `/de/<путь>` отдаёт 404.
-- Свой разбор адреса вместо `splitRequestUrl` — теряется всё после второго `?`, и источник
-  заявки считается неверно.
-- Правка разметки без проверки на прод-сборке: в дев-сервере теги ставит не тот путь. Проверка
-  описана паттерном `seo-verify`.

package/assets/patterns/seo-verify.md

@@ -1,83 +0,0 @@
----
-name: seo-verify
-kind: pattern
-rule: seo
-description: Паттерн правила seo. Брать после любой правки, задевающей разметку публичного сайта, meta или маршруты — готовые команды сборки, поднятия SSR и проверки отданного HTML по локалям, карты сайта и кэшируемости перенаправления. Не брать для самой правки разметки — это паттерн seo-page.
----
-
-# Проверка разметки на прод-сборке
-
-Паттерн правила `seo`. Что при этом должно быть верно — закон
-`docs/constitution/application/search-visibility.md`.
-
-## Когда брать
-
-После любой правки, задевающей разметку сайта, `meta`, маршруты, `server.ts`, `robots.txt`
-или `deploy/nginx.conf`.
-
-## Дев-сервер здесь не показатель
-
-Теги ставятся при отдаче страницы сервером. В дев-режиме этот путь другой, поэтому проверка
-идёт на собранном приложении с поднятым SSR.
-
-```bash
-npx nx build site
-PORT={{prodSitePort}} node dist/apps/site/server/server.mjs &
-```
-
-Порт {{prodSitePort}} — тот же, что берёт стенд; дев-серверы владельца на {{sitePort}} и {{adminPort}} при этом не
-трогаются. Angular SSR отвечает `400` на чужой `Host`, поэтому запросы идут с
-`-H "Host: localhost"`.
-
-## Что смотреть в отданном HTML
-
-```bash
-for locale in "" <префиксы локалей>; do
-    printf '%-10s ' "${locale:-en}"
-    curl -s -H "Host: localhost" "http://localhost:{{prodSitePort}}/${locale}<адрес страницы>" \
-        | grep -c -E '<title>|name="description"|property="og:|rel="canonical"|hreflang=|application/ld\+json'
-done
-```
-
-В ответе каждой локали должны быть `<title>`, `description`, набор `og:*`, `canonical`,
-полный набор `hreflang` плюс `x-default` и блок `application/ld+json`.
-
-Отдельно проверяется, что `canonical` ведёт на **свой** язык, а не на локаль по умолчанию:
-
-```bash
-curl -s -H "Host: localhost" http://localhost:{{prodSitePort}}/de/<адрес страницы> \
-    | grep -o 'rel="canonical" href="[^"]*"'
-```
-
-## Карта сайта
-
-```bash
-curl -s -H "Host: localhost" http://localhost:{{prodSitePort}}/sitemap.xml | head -20
-```
-
-Карта строится из живых данных, а не из файла. Пустой ответ означает, что не поднялся запрос
-за объектами, — это отказ, а не «объектов нет».
-
-## Кэшируемость перенаправления
-
-Проверяется только на стенде с настоящим `deploy/nginx.conf`: голый SSR отдаёт заголовки, но
-не показывает, попадёт ли ответ в кэш.
-
-```bash
-curl -sI http://<стенд>/<прежний-slug> | grep -i -E 'HTTP/|location|cache-control|x-cache'
-```
-
-Ответ обязан быть `301`, нести `Cache-Control` со сроком и попадать в кэш. Некэшируемое
-перенаправление не вытесняет старую запись, и гость видит прежнюю страницу до суток.
-
-## Тексты
-
-`title` и `description` берутся из словарей во всех локалях перевода. Непереведённый ключ уезжает
-в выдачу по-английски — полноту словарей держит `npx nx test common-i18n`.
-
-## Частые промахи
-
-- Проверка в дев-сервере: разметку там ставит другой путь, и отсутствие тега не видно.
-- Проверка одной локали: расходится обычно та, которую не смотрели.
-- Проверка кэша без nginx: заголовки видны, попадание в кэш — нет.
-- Вывод по коду ответа: `200` приходит и со страницы без разметки.

package/assets/patterns/translations-content.md

@@ -1,107 +0,0 @@
----
-name: translations-content
-kind: pattern
-rule: translations
-description: Паттерн правила translations. Брать при работе с переводами содержимого записи — производный перевод при сохранении, запись локали руками через язык админки, разбор отказа провайдера, сброс кэша отданных страниц. Не брать для подписей интерфейса — это паттерн translations-key.
----
-
-# Перевод содержимого записи
-
-Паттерн правила `translations`. Что при этом должно быть верно — закон
-`docs/constitution/application/locales.md`.
-
-## Когда брать
-
-- Владелец правит тексты записи, и остальные локали должны догнать.
-- Админка ответила, что сохранила на языке ввода, а перевод на остальные не удался.
-- Локаль надо заполнить руками: провайдер недоступен, а страница на этом языке нужна сегодня.
-- Проверяется, что отданная страница показывает свежий текст.
-
-## Перевод идёт сам, и просить его нечем
-
-Кнопки «перевести» нет. Владелец печатает на своём языке, а процедура сохранения зовёт перевод
-до транзакции и кладёт в хранилище уже все локали. Локаль ввода приезжает полем запроса и
-берётся из языка админки, а не из браузера гостя.
-
-В партию идёт не всё подряд: сборщик отбрасывает строку, чей исходный текст не менялся **и**
-которая переведена на все целевые локали. Отсюда два следствия:
-
-- сохранение записи без правки текстов провайдера не зовёт вовсе — перестановка изображения или
-  правка числа ничего не стоит;
-- строка, у которой хоть одна локаль пуста, поедет на перевод при первом же сохранении, без
-  правки самого текста.
-
-## Локаль пишется руками через язык админки
-
-Табов локалей в форме нет, и это не упущение: поле одно, а какая локаль за ним стоит, решает
-язык интерфейса. Значит записать перевод руками — это переключить язык в шапке админки и
-заполнить те же поля.
-
-Путь этот не аварийный: пока у провайдера пуст счёт, он и есть обычный порядок, и каждый
-видимый текст заводится по разу на локаль. Считать его временным и ждать автоперевода не надо.
-
-Порядок такой:
-
-1. Меню владельца в шапке → выбрать язык.
-2. Открыть запись. Текстовые поля покажут текст **этой** локали; пустые они там, где локали у
-   записи нет.
-3. Заполнить и сохранить.
-
-Соседние локали при этом целы: черновик пишет в карту по коду локали, а остальные ключи уезжают
-в запрос как пришли. Отказ провайдера ничего не портит — в хранилище ложится ровно то, что
-прислала форма.
-
-Записанное руками потом не перетирается: у поля заполнены все локали, и сборщик партии больше
-не берёт его, пока владелец не изменит исходный текст.
-
-Собирать вызов сохранения скриптом для этого не надо, и правило это прямо запрещает: черновик
-перезаписывает запись целиком, а вложенная запись, не попавшая в список, удаляется вместе со
-своими связями.
-
-## Отказ провайдера читается не по экрану
-
-Владельцу показывается одна фраза без причины. Причина живёт в логах строкой своего контекста:
-
-```bash
-docker compose -f <состав прода> --env-file <файл окружения> logs api --since 30m \
-    | grep -i translation
-```
-
-Строка несёт код ответа, но не текст: клиент бросает отказ по коду, не читая тела. Что именно
-ответил провайдер, спрашивается у него напрямую тем же ключом; для разового вызова его берут
-руками — приложение эту переменную не читает, но значение там то же, что владелец завёл в
-админке. Отказ по деньгам означает пустой счёт, а не сломанный ключ: список моделей при этом
-отдаётся, и строка интеграции показывает «работает». Где лежит сам ключ и почему проба
-зелёная — паттерн `git-workflow-secrets`.
-
-## Отданная страница показывает прежний текст, пока не сброшен кэш
-
-Записанный перевод виден в хранилище сразу, а гостю — нет: страницы лежат в кэше прокси. На
-проде он сбрасывается так же, как на стенде:
-
-```bash
-docker exec <контейнер прокси> sh -c 'rm -rf /var/cache/nginx/site/*; nginx -s reload'
-```
-
-Сверяется отданной разметкой по каждой правленой локали, а не взглядом на админку:
-
-```bash
-for l in <локали>; do
-    printf '%-8s ' "$l"
-    curl -sL "https://<адрес сайта>/$l/" | grep -oE '<meta name="description" content="[^"]{0,80}'
-done
-```
-
-## Частые промахи
-
-- **Проверять результат в админке.** Форма показывает то, что в хранилище, и молчит о кэше: три
-  локали были записаны и проверены, а сайт ещё полчаса отдавал прежний текст на всех.
-- **Считать, что перевода нет, раз пришло предупреждение.** Прежние локали остаются на месте;
-  пустой окажется только та, которой не было раньше.
-- **Писать в хранилище напрямую.** Запись в боевое хранилище запрещена совсем, а колонка со
-  свободной структурой выглядит безобидной целью — тексты правятся через админку, и другого
-  пути у них нет.
-- **Переводить имя собственное.** Оно остаётся как есть во всех локалях: так велит словарь в
-  задании провайдеру, и рукописный перевод обязан вести себя так же.
-- **Копировать одно письмо языка в другое.** Упрощённое и традиционное письмо — разные локали и
-  разное письмо; посимвольная копия простояла на проде, и гость читал чужие иероглифы.