@rt-tools/agent-kit 0.22.0 → 0.23.0

package/assets/patterns/translations-key.md

@@ -1,64 +0,0 @@
----
-name: translations-key
-kind: pattern
-rule: translations
-description: Паттерн правила translations. Брать, когда в интерфейсе появляется видимый текст — куда положить ключ, как подставить его в разметку и в класс, чем дозаполнить остальные семь локалей и чем проверить полноту. Не брать для перевода контента объекта — его заполняет бэкенд.
----
-
-# Ключ перевода
-
-Паттерн правила `translations`. Что при этом должно быть верно — закон
-`docs/constitution/application/locales.md`.
-
-## Когда брать
-
-- В интерфейсе появляется любой текст, который видит человек.
-- Правится подпись, пустое состояние, текст отказа, подпись кнопки подтверждения.
-
-## Куда кладётся ключ
-
-`libs/common/i18n/src/lib/dictionaries/<локаль>/<раздел>.json`. Разделов четыре, и наборы
-ключей сверяются внутри раздела:
-
-| Раздел        | Что в нём                   |
-| ------------- | --------------------------- |
-| `common.json` | общее для сайта и админки   |
-| `site.json`   | публичный сайт              |
-| `admin.json`  | админ-панель                |
-| `mail.json`   | письма и документ-основание |
-
-Набор локалей перевода назван в `implementation.md` правила. Ключ заводится во
-всех — пустое значение считается пропуском, а не переводом.
-
-## Подстановка
-
-В разметке — пайпом:
-
-```html
-<h1 rtElem="title">{{ 'bookingsTitle' | transloco }}</h1>
-<<префикс>-table [emptyMessage]="'bookingsEmpty' | transloco" [ariaLabel]="'bookingsTableAria' | transloco">
-```
-
-В классе — сигналом:
-
-```typescript
-protected readonly title: Signal<string> = translateSignal('promoCodesTitle');
-```
-
-## Дозаполнить и проверить
-
-```bash
-npm run i18n:fill        # дозаполняет недостающее в остальных локалях
-npx nx test common-i18n  # роняет сборку на недостающем или пустом ключе
-```
-
-## Частые промахи
-
-- Текст строкой прямо в шаблоне: он уедет в интерфейс по-английски во всех локалях перевода.
-- Ключ заведён только в `en` и `ru`: тест полноты падает, но замечают это уже в гейте пуша.
-- Пустая строка вместо перевода: на экране она выглядит как задуманная — кнопка без подписи,
-  заголовок без текста.
-- Ключ положен не в свой раздел: наборы сверяются внутри раздела, и расхождение вылезет как
-  недостача в другом.
-- Свой ключ успеха у панели правки записи: текст успеха принадлежит мутации, и заводится он во
-  всех локалях перевода сразу.

package/assets/rules/permissions.md

@@ -1,116 +0,0 @@
----
-name: permissions
-kind: rule
-law: access
-description: Правило под «Закон о доступе». Брать при заведении или правке процедуры Connect, перехватчика входа, гварда маршрута админки и декларации меню. Называет четыре вида доступа, декораторы, сложение пресета с оверрайдами и гейтинг разделов админки. Готовый код — в паттерне permissions-procedure.
----
-
-# Доступ — как это устроено здесь
-
-Правило под закон `docs/constitution/application/access.md`. Закон говорит, что должно быть верно;
-здесь — чем это названо в этом дереве и где лежит. Устройство самих разделов админки —
-`navigation`.
-
-## Как это называется здесь
-
-| В законе           | Здесь                                                                                                                                                                   |
-| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| право              | пара «ресурс и действие» строкой: `bookings:manage`, `chat:manage`                                                                                                      |
-| объявление доступа | декоратор на классе процедуры: `@RequiresPermission('bookings:manage')`, `@RequiresAuth('причина')`, `@PublicProcedure('причина')`, `@OptionalAuthProcedure('причина')` |
-| пресет             | именованный набор прав, выдаваемый пользователю целиком                                                                                                                 |
-| оверрайд           | точечная правка права поверх пресета для одного пользователя                                                                                                            |
-| отбивка без входа  | `Code.Unauthenticated`                                                                                                                                                  |
-| отбивка без права  | `Code.PermissionDenied`                                                                                                                                                 |
-
-## Где это лежит
-
-В этом дереве — таблица в `implementation.md` рядом. Пути живут там, а не здесь: правило
-переносится между репозиториями, раскладка — нет, и путь, названный в правиле, врёт в первом
-же дереве, которое держит код иначе.
-
-## Ход
-
-Ход проверки доступа: чем закрыта процедура, откуда берутся права вошедшего и чем отличается
-отсутствие входа от отсутствия права.
-
-```mermaid
-flowchart TD
-    A[Вызов процедуры] --> B{Каким видом доступа она объявлена}
-    B -->|Публично| C{Она заводит запись}
-    C -->|Да| D[Работает ещё и ограничитель частоты]
-    C -->|Нет| E[Работа идёт]
-    B -->|Любому вошедшему| F{Вход есть}
-    B -->|По праву| F
-    F -->|Нет| G[Отбивается как неаутентифицированный]
-    F -->|Да| H{Учётная запись ещё существует}
-    H -->|Нет| G
-    H -->|Да| I[Права читаются при каждом вызове: пресет плюс личные правки поверх]
-    I --> J{Право дано}
-    J -->|Да| E
-    J -->|Нет, либо роль о нём молчит| K[Отбивается как отказ в доступе: молчание — не разрешение]
-    D --> E
-```
-
-## Как закон применяется здесь
-
-- **Каждая процедура объявляет свой доступ декоратором, и объявление ровно одно.**
-  Процедура без объявления или с двумя объявлениями не даёт приложению подняться.
-- **Видов доступа четыре: по праву, любому вошедшему, публично и публично с чтением входа.**
-  Последний отдаёт вошедшему больше, чем гостю, — так владелец видит скрытые объекты в общем
-  списке.
-- **Права пользователя — это права пресета, поверх которых применены его оверрайды.**
-- **У человека одна роль во владении, и держит это хранилище.** Две принадлежности в одном
-  владении пришлось бы складывать, а результат сложения запретов и разрешений по двум строкам
-  не прочитать. Права разных владений не складываются вовсе: они записаны у принадлежности, а
-  не у учётной записи.
-- **Право, о котором роль ничего не говорит, считается неданным.** Значение, которое не булево,
-  отбрасывается при сложении: отсутствующее право и прямо отобранное означают одно и то же, и
-  «непусто» правом не считается.
-- **Права вошедшего читаются при каждом вызове, а не берутся из выданного входа.** Выданный
-  вход говорит только о том, кто пришёл: подписанное однажды живёт часами и правку прав не
-  переживает, поэтому отобранное право открывало бы раздел до конца дня.
-- **Учётная запись, которой больше нет, вызовов, требующих входа, не открывает.** Тем же
-  чтением отбивается и человек, потерявший принадлежность в своём владении: работать ему не в
-  чем.
-- **Счётчик и рекламные сигналы включает ответ гостя, а не наличие ключа в настройках.**
-  Решений два, и хранятся они парой: «разрешил счёт посещений, но не рекламу» — законное
-  состояние, а третьим значением перечисления его пришлось бы заводить заново на каждое новое
-  разрешение. Всё, что не пара булевых значений, читается как неотвеченный вопрос, то есть как
-  отказ: хранилище принимает что угодно, а решать по испорченной записи нельзя. Своя
-  статистика к согласию не привязана — она не уходит наружу.
-- **Публичная процедура, заводящая запись, закрыта ещё и ограничителем частоты.** Право её не
-  сторожит, и без предела скорость роста таблицы задаёт отправитель, а не владелец. Считается
-  по ключу клиента, и ключ у всех таких процедур общий: второй ответ на вопрос «кто это»
-  разошёлся бы с первым. Публичная процедура, которая только читает, ограничителя не требует.
-- **Запрос без входа отбивается как неаутентифицированный, а вход без права — как отказ в
-  доступе.** Это разные ответы: первый лечится входом, второй — нет.
-- **Право проверяется перехватчиком до тела процедуры.** Обработчик не решает, пускать ли
-  вызывающего.
-- **Публичность объявляется с причиной.** Причина — аргумент декоратора, записанный для
-  читателя кода; ни в ответ, ни в лог она не уходит.
-- **Пункт меню и адрес раздела закрыты по одной декларации.** Иначе скрытый пункт закрывает
-  раздел лишь на вид: адрес открывается по прямой ссылке.
-- **Пока права не получены, админка ничего не прячет.** Пустая шапка после сетевого сбоя
-  выглядит как сломанная админка и не оставляет выхода.
-
-## Чего из закона здесь нет
-
-Право, отобранное посреди сессии, до перевхода не действует: токен живёт со своими правами до
-истечения — это `Q-A-1` в законе. Смены пароля из интерфейса нет вовсе: ни экрана, ни
-процедуры, ни восстановления забытого — `Q-A-2`.
-
-## Паттерны
-
-- `permissions-procedure` — объявление доступа у процедуры и гейтинг раздела админки.
-
-## Ловушки
-
-- **Процедура, о которой перехватчик ничего не знает, отбивается как отказ в доступе, а не
-  пропускается.**
-- **Гвард стоит на дочерних маршрутах защищённой группы, а не на самой группе:** гвард группы
-  отрабатывает один раз за загрузку страницы и переходов между разделами не видит.
-- **Права приходят ответом профиля уже внутри защищённой группы**, поэтому гвард дожидается
-  запуска админки. Отказ запроса ожидание не роняет: с неизвестными правами не закрывается
-  ничего.
-- Декораторы живут в `util` домена аутентификации, а не рядом с перехватчиком: их ставит
-  каждый домен с процедурами, и ребро к объявлениям дешевле ребра к секрету и базе.

package/assets/rules/seo.md

@@ -1,139 +0,0 @@
----
-name: seo
-kind: rule
-law: search-visibility
-description: Правило под «Закон о видимости в поиске». Брать при любой правке, доходящей до разметки публичного сайта: шаблоны страниц, мета-теги, микроразметка, канонический адрес, языковые версии, карта сайта. Паттерны: seo-page, seo-verify.
----
-
-# Видимость в поиске — как это устроено здесь
-
-Правило под закон `docs/constitution/application/search-visibility.md`. Закон говорит, что должно быть
-верно; здесь — чем это названо в этом коде, где лежит и что из закона у нас не применяется.
-
-## Как это называется здесь
-
-| В законе                     | Здесь                                                                    |
-| ---------------------------- | ------------------------------------------------------------------------ |
-| язык страницы                | локаль перевода; их набор — в `implementation.md` рядом                  |
-| язык по умолчанию            | `DEFAULT_LOCALE`, то есть `en`; отдаётся из корня, без префикса в адресе |
-| язык, перевод которого готов | `readyLocales` — поле объекта, а не список локалей сайта                 |
-| канонический адрес           | `${SITE_ORIGIN}${propertyPath(slug, locale)}`                            |
-| структурированные данные     | JSON-LD типа `LodgingBusiness`                                           |
-| прежний адрес страницы       | прежний slug объекта                                                     |
-
-Локаль по умолчанию отдаётся из корня, остальные — с префиксом `/<код>/`. Префикс — часть
-маршрута, а не часть сборки: `<base href>` в разметке всегда `/`.
-
-## Где это лежит
-
-В этом дереве — таблица в `implementation.md` рядом. Пути живут там, а не здесь: правило
-переносится между репозиториями, раскладка — нет, и путь, названный в правиле, врёт в первом
-же дереве, которое держит код иначе.
-
-## Ход
-
-Ход отдачи страницы поисковику: что ставится в разметку, чем связаны локали и что делается с
-прежним адресом.
-
-```mermaid
-flowchart TD
-    A[Страница отдаётся] --> B[Свои теги помечаются признаком и при повторе переписываются, а не множатся]
-    B --> C[Канонический адрес ведёт на локализованный путь этой страницы]
-    C --> D[Связи локалей строятся по готовым локалям плюс запасная]
-    D --> E{Локаль самой страницы}
-    E -->|В список запасных не попадает| F[Иначе она объявлена и своей, и чужой]
-    F --> G[Данные для поиска отдаются блоками: отказ одного не уносит остальные]
-    G --> H{Адрес страницы менялся}
-    H -->|Да| I[С прежнего идёт перенаправление со сроком хранения, покрытое проверкой]
-    H -->|Нет| J[Готово]
-    I --> J
-```
-
-## Как закон применяется здесь
-
-- **Свои теги помечены атрибутом `data-<префикс>-seo`** и при повторном применении переписываются.
-  Чужое в `<head>` не трогается: после гидратации там остаются теги от отдачи сервером.
-- **`canonical` ведёт на локализованный путь** `${SITE_ORIGIN}${propertyPath(slug, locale)}`,
-  а не на корень и не на адрес локали по умолчанию.
-- **`hreflang` строится по `readyLocales`**, плюс `x-default` на локаль по умолчанию. Список
-  локалей сайта для этого не годится: переводы контента заполняет бэк, и готовы они не всегда.
-- **`og:locale:alternate` не включает локаль самой страницы** — иначе она объявлена и
-  основной, и альтернативной сразу.
-- **`url` в JSON-LD — канонический адрес страницы объекта**, не корень сайта.
-- **Корень локали отдаёт страницу единственного объекта** с каноническим адресом на `/{slug}`;
-  посетителя уводит туда nginx ответом 302.
-- **Перенаправление с прежнего адреса отдаётся с `Cache-Control: max-age`** и покрыто
-  `proxy_cache_valid 200 301`. Ключ кэша строится без `$args`, поэтому запросы со строкой
-  запроса идут мимо кэша (`proxy_cache_bypass` / `proxy_no_cache $is_args`).
-- **Страница отдаёт блоки JSON-LD каждый своим тегом**, а не одним графом: отказ одного не
-  уносит остальные, и в отданной разметке видно, какой из них собрался.
-- **Цена уходит и предложением, и диапазоном** — суммой в валюте хранения и с единицей своего
-  периода. Цена по датам, скидки и пересчёт в валюту гостя в разметку не идут.
-- **Сводная оценка появляется от первого отзыва** и считается из оценок самих отзывов. Ноль
-  отзывов — поля нет вовсе: ни нуля, ни пустой строки.
-- **Блок вопросов собирается из вопросов записи**, а ноль вопросов блока не даёт.
-- **Крошки ведут от корня локали к странице записи** адресами той же локали, что и открытая
-  страница. Без названия сайта крошки не выпускаются вовсе.
-- **Сохранение записи уведомляет поисковика об изменении её адресов.** В уведомление уходят
-  страницы записи на готовых локалях по нынешнему и прежним адресам; корни локалей и карта
-  сайта — нет. Отказ приёмника сохранение не отменяет и возвращается владельцу исходом.
-- **Приёмников несколько, и каждый получает свой запрос.** Опрашиваются они одновременно, а
-  потолок ожидания считается на приёмник: последовательный обход сложил бы все потолки в одно
-  ожидание владельца. Переменная окружения перекрывает адреса всех приёмников разом — этим
-  отправку и проверяют локальным приёмником.
-- **Исход возвращается перечислением по приёмнику, а владельцу показывается списком.** Приёмник
-  в нём назван словом, а не адресом. Строка отвечает за приём запроса, а не за осведомлённость
-  поисковика: раздаёт полученное любой приёмник, поэтому отказ одного адреса не значит, что его
-  поисковик не узнал. Подписью объявляется только полный отказ.
-- **Удаление записи уведомляет поисковика теми же адресами.** Отдельного «страница исчезла»
-  протокол не знает: площадка приходит по адресу и видит ответ сайта сама. Адреса собираются до
-  удаления строки — каскад унесёт прежние вместе с записью, — а исход наружу не выходит:
-  страницы уже нет, и читать подпись некому. Снятие с публикации идёт через сохранение и
-  уведомляет тем же путём.
-- **Переименование адреса и снятие прежнего адреса тоже уведомляют поисковика.**
-  Переименование — всеми адресами записи, снятие — одним снятым; готовые локали у снятого
-  считаются по текстам записи, которой он принадлежал, и ради них выборка снятия отдаёт не
-  только адрес. Исход наружу не выходит ни там, ни там: владелец на странице адресов
-  спрашивает про адрес, а не про уведомление.
-- **Правка настроек владельца уведомляет поисковика адресами всех действующих записей.**
-  Видимой гостю считается та же правка, которой сбрасывается кэш, — а правка невидимого поля
-  уведомления не шлёт. Уходят живые адреса, без прежних, и готовые локали считаются по каждой
-  записи отдельно; отправка идёт на владеющую сущность — записи разных сущностей в одну не
-  попадают. Работа идёт в фоне за сохранением настроек, поэтому исход остаётся в логах:
-  показать его владельцу негде.
-- **Каждая отправка оставляет запись, и заводится она до обращения к приёмникам.** Повод,
-  записи, объявленные адреса и исход по каждому приёмнику ложатся рядом; пустой исход означает
-  «отправка идёт», а спустя несколько минут — что процесс упал посреди опроса. Пишут её все
-  места, откуда уведомление уходит. Отказ записи отправку не отменяет.
-- **Непрошедшие запросы владелец повторяет нажатием, и повтор заводит новую запись.**
-  Повторяется последняя отправка записи — у ранней адреса могли устареть, — и запрос уходит
-  только тем приёмникам, чей исход не «принял»; у оборванной записи это все её приёмники. Повод
-  у новой записи свой, а право строже, чем у чтения: повтор объявляет адреса поисковику.
-  Автоповтора по расписанию нет.
-- **Записи отправок держит ночная чистка: сперва предел, потом срок.** Тот же порядок, что у
-  ленты происшествий: срок, снятый первым, оставил бы предел меряться по уже почищенной
-  таблице.
-
-## Чего из закона здесь нет
-
-Что отдаёт корень локали — единственную запись или список, — правило не утверждает: это
-состояние дерева, и живёт оно в компаньоне рядом. Развилка от этого не исчезает: там, где
-список появляется, канонический адрес корня пересматривается; это `Q-SV-1` в законе.
-
-## Паттерны
-
-- `seo-page` — правка разметки страницы: теги, JSON-LD, новый маршрут, новая страница в карте.
-- `seo-verify` — проверка отданной разметки на прод-сборке.
-
-## Ловушки
-
-- Тег, добавленный мимо `PropertySeoService`, не помечен `data-<префикс>-seo` — он не будет ни
-  переписан, ни удалён при следующем применении и переживёт переход между страницами.
-- Новый маршрут сайта без ветки в `app.routes.ts` под каждую локаль существует только в
-  локали по умолчанию: `/de/<путь>` отдаст 404 и поисковику, и гостю.
-- Новая страница не попадает в `sitemap.xml` сама — карта строится из объектов, а не из
-  маршрутов.
-- Адрес режется по **первому** `?` и только им: `req.url.split('?')` теряет всё после второго
-  знака, и перенаправление приходит на страницу без UTM-хвоста — источник заявки считается
-  неверно. Разрез живёт в `splitRequestUrl`
-  (слой `util` домена страницы объекта) и покрыт спеками; свой не заводить.

package/assets/rules/translations.md

@@ -1,96 +0,0 @@
----
-name: translations
-kind: rule
-law: locales
-description: Правило под «Закон о локалях и переводах». Брать при заведении любого видимого текста, правке словарей libs/common/i18n, префиксов локалей сайта и перевода контента объекта. Называет локали перевода, словари, производные переводы и начальную валюту локали. Готовый код — в паттерне translations-key.
----
-
-# Локали и переводы — как это устроено здесь
-
-Правило под закон `docs/constitution/application/locales.md`. Закон говорит, что должно быть верно;
-здесь — чем это названо в этом дереве и где лежит. Разметка сайта для поиска — `seo` под
-своим законом.
-
-## Как это называется здесь
-
-| В законе             | Здесь                                                                                               |
-| -------------------- | --------------------------------------------------------------------------------------------------- |
-| локаль сайта         | одна из локалей перевода; их набор — в `implementation.md` рядом                                    |
-| локаль по умолчанию  | `en` — отдаётся из корня, без префикса в адресе                                                     |
-| локаль ввода         | `source_locale` в запросе сохранения объекта; берётся из языка админки                              |
-| словарь              | JSON-словари Transloco в `libs/common/i18n/src/lib/dictionaries/<локаль>/`, разложенные по разделам |
-| перевод контента     | jsonb по локалям в базе, заполняется бэкендом                                                       |
-| подстановка в шаблон | `\| transloco` в разметке, `translateSignal` в классе                                               |
-
-## Где это лежит
-
-В этом дереве — таблица в `implementation.md` рядом. Пути живут там, а не здесь: правило
-переносится между репозиториями, раскладка — нет, и путь, названный в правиле, врёт в первом
-же дереве, которое держит код иначе.
-
-## Ход
-
-Ход появления видимого текста: откуда он берётся, что делается с непришедшим переводом и чем
-держится полнота словарей.
-
-```mermaid
-flowchart TD
-    A[Появился видимый человеку текст] --> B{Чей он}
-    B -->|Интерфейса| C[Заводится ключом во всех локалях перевода сразу]
-    B -->|Содержимого| D[Владелец пишет на своём языке, остальные локали — производные]
-    C --> E{Перевод пуст}
-    E -->|Да| F[Считается пропуском: подставляется запасной словарь, а прогон краснеет]
-    E -->|Нет| G[Готово]
-    D --> H{Перевод пришёл}
-    H -->|Да| I[Записывается]
-    H -->|Нет| J[Прежнее значение сохраняется, а само сохранение не срывается]
-    I --> G
-    J --> G
-    F --> G
-```
-
-## Как закон применяется здесь
-
-- **Локаль по умолчанию отдаётся из корня, остальные семь — из-под префикса пути.**
-- **Видимый человеку текст берётся из словаря и заводится во всех локалях перевода.** Ключ,
-  потерянный в одной локали, гость видит на кнопке как есть.
-- **Пустой перевод считается пропуском, а не переводом.** Запасной словарь подставляется
-  только на отсутствующий ключ, а пустую строку отдаёт как есть.
-- **Переводы контента производные: владелец пишет на своём языке, остальные семь локалей
-  заполняет бэкенд при сохранении.** Табов локалей в формах админки нет — правка вручную всё
-  равно была бы перезаписана.
-- **Отказ перевода сохранение не срывает.** Текст на локали ввода записывается, прежние
-  переводы остаются, и владелец видит предупреждение, а не сообщение об успехе.
-- **Локаль, для которой перевода не пришло, сохраняет прежнее значение.**
-- **Язык админки выбирает владелец, и выбор живёт в его профиле.** Он же уходит в локаль
-  ввода при сохранении объекта.
-- **У локали есть начальная валюта показа.** Дальше валюту выбирает гость, и его выбор
-  сильнее умолчания локали.
-
-## Чего из закона здесь нет
-
-Страница не показывает, что перевод устарел: владелец правку сохранил, провайдер отказал —
-и гость по-прежнему видит старый текст. Это `Q-L-1` в законе.
-
-## Паттерны
-
-- `translations-key` — заведение ключа во всех локалях перевода и подстановка в разметку.
-- `translations-content` — перевод содержимого записи: производный перевод, запись локали
-  руками, отказ провайдера, сброс кэша отданных страниц.
-
-## Ловушки
-
-- **Полноту словарей держит не рантайм, а тест.** `nx test common-i18n` роняет сборку на
-  недостающем или пустом ключе; дозаполнить недостающее — `npm run i18n:fill`.
-- **Наборы ключей сверяются внутри раздела**, а не по всему словарю сразу: словари разложены
-  на общий, сайт, письма и админку.
-- **Перевод контента идёт до транзакции сохранения:** страница объекта не должна оказаться
-  наполовину переведённой. Кэш сбрасывается после записи и один раз.
-- **Без ключа переводов сохранение проходит,** но переводы остаются прежними, и владелец видит
-  предупреждение об этом на своём экране. Ключ лежит секретом владения в хранилище, а не
-  переменной окружения, и заводит его владелец экраном интеграций: одноимённая переменная в
-  составе прода приложением не читается. Состояния ключа — паттерн `git-workflow-secrets`.
-- **Ветки локалей надеты не на все маршруты сайта, и новый раздел в них не попадает** —
-  раскладка, её ловушка и готовый код лежат в правиле `seo` и паттерне `seo-page`.
-- Новый маршрут сайта без ветки под каждую локаль существует только в локали по умолчанию:
-  путь под префиксом другой локали отдаст 404 и поисковику, и гостю.