@rt-tools/agent-kit 0.3.0 → 0.5.0

package/assets/patterns/entity-models-new.md

@@ -0,0 +1,124 @@
+---
+name: entity-models-new
+kind: pattern
+rule: entity-models
+description: Паттерн правила entity-models. Брать при объявлении новой модели сущности и её маппера — готовый неймспейс I<Сущность> с Api, State и Draft, короткий и полный уровни, наследник BaseMapper с typeCast, что делать после правки .proto.
+---
+
+# Объявить модель сущности и её перевод
+
+Паттерн правила `entity-models`. Что при этом должно быть верно — закон
+`docs/constitution/entity-models.md`.
+
+## Когда брать
+
+- Заводится новая сущность админки.
+- У существующей появляется короткий уровень.
+- Правится маппер или контракт этой сущности.
+
+## Модель — неймспейс в `util` домена
+
+Файл `libs/<семья>/<домен>/util/src/lib/models/<сущность>.model.ts`:
+
+```typescript
+export namespace IPromoCode {
+    export namespace Short {
+        export type Api = PromoCodeListItem;
+
+        export interface State {
+            readonly id: string;
+            readonly code: string;
+        }
+    }
+
+    export type Api = PromoCodeInfo;
+
+    export interface State extends Short.State {
+        readonly usageCount: number;
+        /** Пусто = код действует на любой объект владельца */
+        readonly propertyId: string;
+        /** 0 = без предела */
+        readonly usageLimit: number;
+    }
+
+    /** Что уходит на сервер при сохранении: id пуст — код новый */
+    export interface Draft {
+        readonly id: string;
+        readonly code: string;
+    }
+}
+
+export enum EPromoDiscountKind {
+    Percent = 'percent',
+    Amount = 'amount',
+}
+```
+
+Перечисления домена лежат в том же файле, но **вне** неймспейса. Глубже двух уровней
+вложенности не заводить: `IPromoCode.Short.State` читается, третий уровень уже нет.
+
+Псевдонимы выборки объявляются там же:
+
+```typescript
+export type Query = IList.Query.State<EPromoCodeSortProperty, EPromoCodeFilterProperty>;
+export type ListResult = IList.Result.State<IPromoCode.State, EPromoCodeSortProperty, EPromoCodeFilterProperty>;
+```
+
+## Маппер — в `api` домена, свой на каждый уровень
+
+Файл `libs/<семья>/<домен>/api/src/lib/mappers/<сущность>-model.mapper.ts`:
+
+```typescript
+export class PromoCodeModelMapper extends BaseMapper<IPromoCode.State> {
+    public override mapFrom(raw: IPromoCode.Api): IPromoCode.State {
+        return {
+            id: this.typeCast.getAsString(raw?.id),
+            code: this.typeCast.getAsString(raw?.code),
+            usageCount: this.typeCast.getAsNumber(raw?.usageCount),
+            usageLimit: this.typeCast.getAsNumber(raw?.usageLimit),
+        };
+    }
+}
+```
+
+Маппер без состояния и без DI:
+
+```typescript
+readonly #mapper: PromoCodeModelMapper = new PromoCodeModelMapper();
+```
+
+На каждый уровень — свой класс: `PromoCodeShortModelMapper` и `PromoCodeModelMapper`.
+
+## Строковое поле с конечным набором сверяется явно
+
+`getAsType` умолчания не принимает: значение вне набора он пишет в консоль и возвращает
+строкой `'unknown'`.
+
+```typescript
+kind: promoDiscountKindOf(raw?.kind) ?? EPromoDiscountKind.Percent,
+```
+
+## После правки контракта
+
+```bash
+cd libs/common/proto && npx buf lint
+npm run proto:generate
+```
+
+Ни `buf lint`, ни `buf breaking` не входят в `check:all` и в CI — гоняются руками.
+Сгенерированные типы лежат в репозитории, и без перегенерации расхождение вылезет сборкой
+чужого приложения.
+
+Снятое поле помечается `reserved` с его номером и именем.
+
+## Частые промахи
+
+- `Api` переписан руками вместо псевдонима — разойдётся с контрактом молча.
+- `??` вместо `typeCast` — контракт отдаёт значения по умолчанию, и проверка на `undefined`
+  не ловит ничего.
+- `as Type` в маппере — запрещено правилом `typescript-conventions`.
+- `null` или `undefined` в `State` — пустое выражается пустой строкой или нулём, а смысл нуля
+  объясняется комментарием рядом с полем.
+- `readonly`-массив отдан в запрос: init-тип сообщения требует изменяемый, модель отдаётся
+  копией.
+- Общий тип на админку и сайт — у гостя своя короткая форма записи.

package/assets/patterns/entity-store.md

@@ -0,0 +1,91 @@
+---
+name: entity-store
+kind: pattern
+rule: entity-conventions
+description: Паттерн правила entity-conventions. Брать при заведении или правке стора админки — готовый наследник общей основы списочного стора, обвязка mutate, имена методов от действия, действие со своей занятостью. Не брать для панели — это паттерн entity-aside.
+---
+
+# Стор сущности
+
+Паттерн правила `entity-conventions`. Что при этом должно быть верно — закон
+`docs/constitution/entity-editing.md`.
+
+## Когда брать
+
+- Заводится `<сущность>.store.ts`.
+- Правится метод загрузки или записи существующего стора.
+
+## Наследник объявляет своё в четырёх строках
+
+```typescript
+@Injectable()
+export class PromoCodesStore extends BaseListStoreService<
+    IPromoCodesState,
+    string,
+    IPromoCode.State,
+    EPromoCodeSortProperty,
+    EPromoCodeFilterProperty,
+    IPromoCode.Draft
+> {
+    protected override readonly apiService: PromoCodeApiService = inject(PromoCodeApiService);
+    protected override readonly listErrorKey: string = 'promoCodesLoadFailed';
+
+    constructor() {
+        super({ ...INITIAL_STATE.LIST }, { name: 'PromoCodesStore' });
+
+        this.setConfig({ usePagination: true, useSorting: true, useFiltering: true, useSearch: true });
+    }
+
+    protected override mutationErrorKeyOf(error: unknown): string {
+        return promoRejectionKey(error);
+    }
+}
+```
+
+Конфиг решает, что уходит в выборку. Выключено всё — выборки нет вовсе, и сервер отдаёт список
+целиком. Из основы работают загрузка и перезапрос, смена страницы, порядка, условий отбора и
+строки поиска, догрузка следующей страницы, правка одной записи в списке и сброс выборки.
+
+Файл называется `<сущность>.store.ts`: имя `<сущность>-store.service.ts` выводит его и из
+правила линтера, и из гейта скилов.
+
+## Метод правки отдаёт поток
+
+```typescript
+public save(draft: IPromoCode.Draft): Observable<IPromoCode.State | null> {
+    return this.mutate(this.apiService.save(draft));
+}
+```
+
+`mutate` держит занятость, гашение прежней ошибки, перечитывание списка после успеха и ключ
+отказа. Мутация завершается **перечитанным списком**, а не отправленным запросом: панель
+закрывается по значению потока, и список, перечитанный после закрытия, показал бы прежнее
+значение.
+
+## Имена — от действия, а не от домена
+
+| ✗                                    | ✓          |
+| ------------------------------------ | ---------- |
+| `createBooking()`, `updateBooking()` | `save()`   |
+| `deleteBooking()`, `removeFeed()`    | `remove()` |
+| `loadBookings()`, `fetchFeeds()`     | `load()`   |
+
+Имя домена уже в имени стора и в его алиасе.
+
+## Действие со своей занятостью
+
+Идёт мимо `mutate`: опрос подписки на календарь держит `pollingId`, потому что панель на минуту
+опроса не гасится, а ключ отказа кладёт `setErrorKey`.
+
+## Частые промахи
+
+- Булев ответ у метода правки: он теряет и записанную запись, и причину отказа — панель узнаёт
+  только «не вышло».
+- Своя обвязка занятости и ошибки вокруг вызова сервиса: всё это в `mutate`.
+- Свои сигналы записей, занятости и отказа: они в общей основе.
+- Подписка на сигнал отказа загрузки: сигнал делят список и панель, и один отказ показался бы
+  дважды. Отказ загрузки идёт отдельным потоком.
+- Второе поле сортировки: порядок в выборке один — его не принимают ни таблица, ни контракт,
+  ни разбор на сервере.
+- Хвост с `EMPTY`, приклеенный к мутации: он гасится `defaultIfEmpty`, иначе отказ приклеенного
+  потока превращает удачную запись в вечный спиннер.

package/assets/patterns/git-workflow-commit.azure.md

@@ -0,0 +1,259 @@
+---
+name: git-workflow-commit
+kind: pattern
+rule: git-workflow
+description: Паттерн правила git-workflow для дерева в Azure DevOps. Брать на заведение рабочего элемента, ветки, коммит, пуш и создание PR — заведение элемента со всеми шагами, перевод по состояниям, слияние двух задач в одну, сверка очереди работ, работа от учётной записи машинной работы, формат заголовка, привязка PR к элементу, ревьювер, исполнитель и метки, чеклист проверок до публикации, обход требования документа. Не брать для миграций и перезапуска прода — это паттерны git-workflow-migration и git-workflow-restart.
+---
+
+# Ветка, коммит и PR
+
+Паттерн правила `git-workflow`. Что при этом должно быть верно — закон
+`docs/constitution/delivery.md`.
+
+## Когда брать
+
+- Заводится рабочий элемент, с которого начинается правка.
+- Заводится ветка под него.
+- Готовится коммит или пуш.
+- Открывается PR.
+- Работа перешла на следующий шаг, и элемент переводится в другое состояние.
+
+## Сначала рабочий элемент, потом ветка
+
+Заведение состоит из четырёх шагов: элемент, номер в его заголовке, исполнитель, состояние
+`New`. Область и итерация ставятся тут же: элемент без них лежит в корне проекта и на доску
+команды не попадает — заведён, а в очереди работ его нет.
+
+Все четыре делает одна команда дерева, а не рука: делить их значит забывать последний.
+
+```bash
+npm run task:new -- --title 'Письма владельцу не уходят молча' \
+    --type Bug --area '<проект>\<команда>' --slug mail-owner-silence < описание.md
+```
+
+Скрипт под этой командой заводит проект — пакет её не везёт. Что он делает вызовами `az`:
+
+```bash
+az boards work-item create --type Bug --title '[<номер>] …' \
+    --org https://dev.azure.com/<организация> --project <проект> \
+    --assigned-to <бот> --area '<проект>\<команда>' --iteration '<проект>\<итерация>'
+az boards work-item update --id <номер> --title '[<номер>] …'   # номер известен после создания
+```
+
+Номер в заголовок руками не пишется — он известен только после создания, и команда дописывает
+его сама.
+
+Чем сверить, что очередь работ в порядке:
+
+```bash
+npm run check:board
+```
+
+Она смотрит только открытое: состояние, область и исполнителя у каждого открытого элемента, а
+у каждого открытого PR — номер в заголовке, привязанный элемент и то, что второго PR с тем же
+номером нет. Имя ветки не судит: у открытого PR его не переименовать.
+
+## Две задачи, которые чинятся одной правкой
+
+Если по ходу выяснилось, что правка закрывает и соседний элемент, — это одна задача, а не две.
+Слить их можно, пока правка не въехала в главную ветку:
+
+```bash
+# то, чего в поглотившем элементе не было, дописывается в его описание
+az boards work-item update --id <поглотивший> --description "$(cat тело.md)"
+# поглощённый связывается с ним как дубликат и закрывается
+az boards work-item relation add --id <поглощённый> --relation-type duplicate-of \
+    --target-id <поглотивший>
+az boards work-item update --id <поглощённый> --state 'Removed'
+```
+
+Связь ставится до закрытия: закрытый без неё элемент читается как сделанный, а сделан он не
+был. Состояние снятого зависит от процесса проекта — `Removed` есть в Agile и Scrum, в Basic
+его нет; какое здесь, сказано в `implementation.md`.
+
+После слияния ветки поглощения нет: она въехала, и откатывается целиком.
+
+## Ветка заводится отдельным вызовом
+
+Гард главной ветки разбирает текст команды и смотрит ветку на момент запуска, поэтому
+составная команда отклоняется целиком — ветки в ней ещё нет:
+
+```bash
+✗ git checkout -b 85-guest-token && git commit -m 'feat(admin): …'
+✓ git checkout -b 85-guest-token
+✓ git commit -F -
+```
+
+Имя несёт номер элемента, slug строчными латинскими через дефис; точная форма — в
+`implementation.md`. Гард поставки разбирает её на месте и отбивает промах до первого коммита,
+а по номеру спрашивает доску: элемент должен существовать, быть открытым и иметь исполнителя.
+
+Имя без номера (`feat/…`, `fix/…`) законно, пока ветка живёт локально — под пробу и разбор.
+PR с неё не откроется: правка, доезжающая до главной ветки, начинается с задачи.
+
+## Состояние элемента двигается вместе с работой
+
+Ветка заведена — элемент уже не `New`, а `Active`. PR открыт — он ждёт разбора. Оба перевода
+делает одна команда, вторым вызовом сразу за тем, который его вызвал:
+
+```bash
+npm run task:move -- 86 in-progress   # сразу после git checkout -b 86-…
+npm run task:move -- 86 in-review     # сразу после az repos pr create
+```
+
+Под ней — правка поля состояния:
+
+```bash
+az boards work-item update --id 86 --state 'Active'
+```
+
+Имена состояний берутся у процесса проекта, а не назначаются правилом: Agile, Scrum и Basic
+называют одни и те же три шага по-разному, и перевод в состояние, которого в процессе нет,
+отвечает отказом на каждой задаче подряд.
+
+Перевод не откладывается на потом: очередь работ читают между шагами, а не после них.
+
+## Коммит подписывается учётной записью машинной работы
+
+Токен читается в переменную и не печатается; автор и коммиттер задаются переменными той же
+команды. `git config` не годится — конфиг общий с основным деревом и переписал бы подпись
+владельцу:
+
+```bash
+TOKEN=$(tr -d '\n' < ~/.config/<дерево>-bot-token)
+
+GIT_AUTHOR_NAME="<бот>" GIT_AUTHOR_EMAIL="<почта бота>" \
+GIT_COMMITTER_NAME="<бот>" GIT_COMMITTER_EMAIL="<почта бота>" \
+    git commit -F -
+```
+
+Заголовок — `type(scope): description`. Типы: `feat`, `fix`, `refactor`, `docs`, `style`,
+`test`, `chore`, `perf`. Области — свои у дерева, они перечислены в `implementation.md`. Точка
+в конце заголовка не принимается.
+
+Строка `AB#<номер>` в теле коммита привязывает его к рабочему элементу. Она не заменяет
+привязки самого PR: коммит связывается с элементом, а очередь работ читает связь PR.
+
+## Документ едет тем же коммитом
+
+`docs-guard` требует пару и называет её сам. Обход — строка в теле, причина обязательна:
+
+```
+Docs-skip: правка только в тестах хука, зеркала у него нет
+```
+
+## Номер элемента стоит в его заголовке и в заголовке PR
+
+Форма одна на оба — `[<номер>] <текст>`. Номер стоит в самом заголовке, а не только в теле: в
+списке PR тела не видно. Тот же номер несёт и имя ветки, поэтому элемент, ветка и PR читаются
+как одно.
+
+Элемент говорит, что не так; PR тем же номером отчитывается, что сделано:
+
+```
+элемент  [86] Пустой адрес владельца — письма не уходят молча
+PR       [86] Письмо владельцу с незаполненным адресом попадает в логи
+```
+
+Инфинитив в заголовок PR не переносится: «исправить» становится «исправлено», «вернуть» —
+«возвращено», «добавить» — «добавлено».
+
+Тип и область — `fix(site):`, `docs(common):` — в заголовок PR не идут: это формат заголовка
+коммита, и там его сверяет `commitlint`.
+
+## PR привязывается к элементу при создании
+
+Привязка задаётся флагом, а не правкой после: у токена может не быть права править чужой
+элемент, и вторая команда обойдётся молча, оставив PR ни с чем не связанным.
+
+```bash
+AZURE_DEVOPS_EXT_PAT="$TOKEN" az repos pr create \
+    --title '[86] Письмо владельцу с незаполненным адресом попадает в логи' \
+    --source-branch 86-mail-owner-silence --target-branch main \
+    --work-items 86 --reviewers <владелец> --delete-source-branch true \
+    --description 'Закрывает рабочий элемент 86.'
+```
+
+Ревьювер — всегда владелец: без запроса разбора PR не показывается ему в очереди. Один PR
+закрывает элемент целиком — половину задачи одним PR не выкатывают: у задачи одна ветка, и
+работа, которая в неё не влезает, делится на задачи до того, как ветка заводится.
+
+У уже открытого PR то же ставится правкой:
+
+```bash
+az repos pr work-item add --id 205 --work-items 86
+az repos pr reviewer add --id 205 --reviewers <владелец>
+az repos pr update --id 205 --description "$(cat тело.md)"
+```
+
+Правка описания переписывает его целиком. Тело перечитывается всякий раз, когда в ветку что-то
+влилось после публикации: отчёт утверждает про дерево, а дерево с тех пор изменилось.
+
+## Состояние PR читается, а не додумывается
+
+Команды правки отвечают нулевым кодом и тогда, когда ничего не сделали. Поэтому после них PR
+перечитывают:
+
+```bash
+az repos pr show --id 205 \
+    --query '{author: createdBy.uniqueName, reviewers: reviewers[].uniqueName, work: workItemRefs[].id}'
+```
+
+Владельцу называют то, что прочитали, а не то, что заказывали.
+
+Открытый PR означает, что элемент ждёт разбора, — состояние переставляется тем же движением:
+
+```bash
+npm run task:move -- 86 in-review
+```
+
+## Что проверяется до публикации PR
+
+Конвейер видит только отправленное, а отправляется оно пушем. Линтеры, юниты и сценарии хуков
+снимает гейт пуша — ниже то, чего он не знает.
+
+1. **В ветке только та правка, за которой её заводили** — `git diff main...HEAD --stat`. Чужой
+   домен в списке файлов означает, что правка расползлась, и её надо вернуть в свои границы.
+2. **Ни мока, ни подменённого ответа, ни отладочной строки** — `git diff main...HEAD` читается
+   целиком, а не по именам файлов. На прод они уезжают молча и портят настоящие данные.
+3. **Документ едет тем же коммитом.** Пару называет `docs-guard`, но спек домена и правку его
+   поведения он не знает — это остаётся за автором.
+4. **Проверки текстов и раскладки зелёные** — те, что дерево завело в `tools/`. Какие именно
+   есть здесь — `implementation.md` правила.
+5. **Все приложения дерева собираются** — `nx build` по каждому. Гейт пуша сборку не гоняет.
+6. **Видимый текст заведён во всех локалях перевода** — тестом полноты словарей, если дерево
+   переводится.
+7. **Правка вёрстки подтверждена замером**, а не взглядом, и снята при узком экране — паттерн
+   `browser-verification-measure`.
+8. **Правка разметки публичного сайта проверена на прод-сборке по всем локалям перевода** —
+   паттерн `seo-verify`.
+9. **PR привязан к рабочему элементу**, ревьювер и исполнитель стоят.
+10. **Заголовок PR несёт номер элемента и называет работу сделанной:** `[<номер>] <Что
+сделано>`, тем же номером, что стоит у элемента и в имени ветки.
+11. **Очередь работ сходится** — `npm run check:board`.
+12. **Состояние PR прочитано, а не выведено из кодов возврата.**
+
+Сразу после публикации элемент переводится в разбор, и сверка очереди прогоняется ещё раз: до
+открытия PR состояние она не судит, а после открытия расхождение видит.
+
+Сделанное рассуждением и сделанное замером в теле PR разводятся прямо: непроверенное,
+названное проверенным, ревьювер принимает за проверенное.
+
+## Частые промахи
+
+- Область и итерация не заданы: элемент заведён, но на доску команды не попал.
+- Состояние взято не из процесса проекта: перевод отвечает отказом на каждой задаче, и это
+  читается как сломанная команда, а не как неверное имя состояния.
+- PR открыт без `--work-items`: связи нет, и по очереди работ не видно, за чем эта правка.
+- `AB#<номер>` в коммите принят за привязку PR: он связывает коммит, а очередь читает связь PR.
+- `git add` с несколькими путями не добавляет ничего, если хоть один путь не существует:
+  команда обрывается на первом промахе целиком. Следующий `git commit --amend` при этом уносит
+  в коммит всё, что осталось в индексе. Состав коммита читается `git show --stat` сразу после
+  него, а не на разборе PR.
+- PR открыт без ревьювера: он не попадает во входящие владельца, и очередь стоит, выглядя
+  работающей.
+- `--delete-source-branch` забыт: ветки задач копятся в репозитории, и по списку веток больше
+  не видно, какая работа идёт сейчас.
+- Автозавершение включено до того, как прогнаны проверки до пуша: конвейер зелёный на том, что
+  он умеет, и слияние происходит без всего остального.
+- Правка владельца ни токена, ни переменных не берёт — они только для машинной работы.