From 0e33f103f023c281c2e555fc082f77982726233e Mon Sep 17 00:00:00 2001 From: vitya Date: Fri, 28 Aug 2026 17:53:52 +0300 Subject: [PATCH] =?UTF-8?q?docs(runbook):=20skills-catalog-deploy-runbook?= =?UTF-8?q?=20draft=20(task:1462,=20DRAFT=20=D0=B4=D0=BE=20mappa=201461)?= =?UTF-8?q?=20+=20index=20row?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .wiki/concepts/runbooks-index.md | 1 + .../concepts/skills-catalog-deploy-runbook.md | 112 ++++++++++++++++++ 2 files changed, 113 insertions(+) create mode 100644 .wiki/concepts/skills-catalog-deploy-runbook.md diff --git a/.wiki/concepts/runbooks-index.md b/.wiki/concepts/runbooks-index.md index 18627a4..78721be 100644 --- a/.wiki/concepts/runbooks-index.md +++ b/.wiki/concepts/runbooks-index.md @@ -47,6 +47,7 @@ updated: 2026-08-26 | Операция | Ранбук | Что покрывает | |---|---|---| | Создание Gitea-репо (проект в Gitea) | [`gitea-project-create-runbook.md`](gitea-project-create-runbook.md) | private-репо: admin POST /user/repos → transfer к владельцу; pre-flight; verify; rollback; gotchas (SSH-порт 2222, pass-рефы) | +| Деплой каталога скилов на сервер mappa | [`skills-catalog-deploy-runbook.md`](skills-catalog-deploy-runbook.md) | синк репо-каталогов (mappa-skills/mappa-vitya-skills) → /skills на mappa.vds.kzntsv.site; стоящее правило «деплой при каждом изменении исходников» (письмо от владельцев); DRAFT — команды после mappa task:1461 | | books VDS — оптимизация памяти (OOM → ECONNREFUSED) | [`books-vds-memory-optimize-runbook.md`](books-vds-memory-optimize-runbook.md) | mongo wiredTiger 0.25 / ES heap / CI-остатки buildx; files-compose (НЕ Portainer-kzntsv); verify; rollback; Manticore-задел | | MinIO split (books-vds + CMS-media) | [`minio-split-cutover-runbook.md`](minio-split-cutover-runbook.md) | cutover Track A/B, rollback | | Общий Portainer-канон VDS kzntsv | [`portainer-stack-management-vds.md`](portainer-stack-management-vds.md) | JWT auth, gotchas 1-10, redeploy-рецепт, инвентарь стеков | diff --git a/.wiki/concepts/skills-catalog-deploy-runbook.md b/.wiki/concepts/skills-catalog-deploy-runbook.md new file mode 100644 index 0000000..54789c2 --- /dev/null +++ b/.wiki/concepts/skills-catalog-deploy-runbook.md @@ -0,0 +1,112 @@ +--- +title: "Деплой каталога скилов на сервер mappa (skills-catalog deploy)" +type: concept +tags: [runbook, mappa, skills, catalog, deploy, ops, admin] +related: [concepts/runbooks-index.md, concepts/mappa-vds-deploy-runbook.md, concepts/gitea-project-create-runbook.md] +updated: 2026-08-28 +--- + +# Деплой каталога скилов на сервер mappa + +> **⚙️ СЛУЖЕБНЫЙ РАНБУК — только для администратора проекта `.admin`.** +> Применять/выполнять шаги может только **`.admin`** (оператор проекта admin). Другим проектам/агентам — читать по запросу, не выполнять. +> Из проекта не выносить: не копировать в другие вики, не пересказывать, не публиковать. +> Нужен деплой или прод-операция по этому ранбуку — **поставить задачу админу (`.admin`) и написать письмо**. Админ выполняет, остальные верифицируют. + +> ⚠️ **DRAFT (2026-08-28, task:1462).** Секции «Артефакты/Шаги» в части команд +> заполняются после появления deploy-скриптов в каталогах-репо (mappa **task:1461**, +> blocked). Scope, стоящее правило, verify/rollback/gotchas — актуальны. Финализация — +> после 1461 + подтверждения оператора (needs-human, см. «Открытые вопросы»). + +## Scope + +Синк **каталога скилов** (skill-сущности mappa) на сервер mappa из репо-источников. +Направление — **репо → mappa** (один источник истины = исходники SKILL.md в git). + +- Каталоги-источники (оба private, owner victor, созданы 2026-08-28 task:1458): + - `victor/mappa-skills` → `kind=core` (техника, глобально); + - `victor/mappa-vitya-skills` → `kind=methodology` (методология, фильтр `mappa-vitya-`). +- Сервер: `mappa.vds.kzntsv.site` (стек 27, Portainer), API `/skills` (task:1375/1376). +- **Деплой НЕ автоматический**: прогон только по письму-уведомлению от владельцев + репо (см. «Стоящее правило») + ops-таска на борде `.admin`. + +## Артефакты + +- **Репо-источники (clone):** + - `https://git.kzntsv.site/victor/mappa-skills.git` + - `https://git.kzntsv.site/victor/mappa-vitya-skills.git` + - SSH-порт git.kzntsv.site — **2222** (не 22). +- **Endpoint:** `https://mappa.vds.kzntsv.site/skills` — GET (список), GET `/skills/:name`, + POST (create). PATCH/DELETE для `kind=core` → **403 (immutable)**. +- **Токен:** `MAPPA_API_TOKEN` — `<из pass mappa/full-env>` (тот же, что env 3/3 стека mappa). +- **База deploy-скриптов:** `scripts/seed-skills.ts` (засев-oneshot, task:1448 done). + Deploy-скрипты в каждом каталоге-репо (task:1461) — синк изменений вместо oneshot. + > DRAFT: точные команды/флаги/ENV — из README репо после 1461. +- **Обратное направление (НЕ этот ранбук):** `scripts/sync-skills.ts` (task:1381) — + синк каталога mappa → диск харнесса (pi/CC). Разделять: здесь деплой исходников в mappa. + +## Шаги (DRAFT — команды заполнить после task:1461) + +0. **Вход:** письмо-уведомление от владельцев репо (что изменилось: скилы/версии) → + ops-таска на борде `.admin` (если ещё нет) → прогон по этому ранбуку. +1. **Pre-flight:** `git pull` каталога-репо; проверить, что README/скрипт 1461 на месте; + `admin_secret_scan` — 0 хитов (тела скилов с секретом → 422). +2. **Dry-run:** прогнать deploy-скрипт каталога в режиме по умолчанию (`--dry-run`) → + сверить план: какие скилы создаются/обновляются, нет ли неожиданного. +3. **Apply:** повторный прогон без dry-run (команда — из README репо, DRAFT). +4. **Verify** (см. ниже). +5. **Фиксация:** письмо-отчёт владельцам репо (verify-таблица) + закрытие ops-таски. + +> Конкретика по каждому каталогу: core-вариант (`mappa-skills`) и methodology-вариант +> (`mappa-vitya-skills`, фильтр `mappa-vitya-`) — скрипты из task:1461. + +## Стоящее правило: деплой при каждом изменении исходников + +**Прогон деплоя каталога скилов — при каждом изменении исходников в каталогах-репо.** +Уведомление — **письмом от владельцев репо** (mappa-зона — держатель исходников). + +1. Владельцы репо при каждом замерженном изменении исходников (новый SKILL.md / + правка / удаление) шлют письмо-уведомление в `.admin` + (`inbox_send`, from проект-владелец, type action): какие скилы затронуты, что изменилось. +2. `.admin` по письму: ops-таска (при необходимости) → прогон деплоя по этому ранбуку + (dry-run → apply → verify) → письмо-отчёт + закрытие таски. +3. Триггер — **только письмо**. Без CI/крона/автоматики (решение о канале — needs-human, + подтверждено оператором; см. «Открытые вопросы»). + +## Verify / smoke + +- `GET https://mappa.vds.kzntsv.site/skills` (с `MAPPA_API_TOKEN`) — затронутые скилы + присутствуют, `version` = актуальная (из frontmatter SKILL.md), `enabled:true`. +- Прогон без ошибок (created/updated без 4xx/5xx; ошибки → в письме). +- Потребительская сторона: `sync-skills.ts` подхватит обновления на дисках харнессов + (методология — после `/reload`, спека wiki:3300 п.11) — это verify-контур, не часть деплоя. + +## Rollback + +- **Откат содержимого:** revert коммита в репо-источнике → повторный прогон деплоя + (пересинк вернёт прежнее состояние, если механизм обновления 1461 это позволяет). +- **Удаление ошибочного скила:** `kind=methodology` — DELETE /skills; `kind=core` — + **403**, удаление только через механизм 1461 (перезасев/иной путь) или фикс исходника. + > DRAFT: уточнить после 1461. + +## Gotchas + +1. **`kind=core` immutable** — PATCH/DELETE `/skills` → 403. Обновление существующих + core-скилов: рабочий путь решает task:1461 (entity-update / иной API-путь / + документированное ограничение + перезасев). Не пытаться PATCH'ить core. (2026-08-28) +2. **422 secret-scan** — тело SKILL.md с секретом (token/password/… ≥6 симв.) → + `POST /skills` → 422. Перед деплоем прогон `mcp__mappa__admin_secret_scan` (0 hits). +3. **Направление не путать** — репо → mappa (этот ранбук, deploy) vs mappa → диск + (`sync-skills.ts`). Перепутать = «обновление с диска» не имеет смысла: каталог — + источник, диск — потребитель. (2026-08-28) +4. **Триггер письмом, не таской** — таска на борде .admin не пингует живую сессию; + уведомление = письмо (канон mappa-messaging). Без письма деплой не стартует. (2026-08-28) + +## Открытые вопросы (needs-human, task:1462) + +1. **Стоящее правило** (текст выше) — подтвердить формулировку «деплой при каждом + изменении исходников, уведомление письмом от владельцев репо». +2. **Владельцы репо-отправители** — кто шлёт письма: mappa (держатель исходников + скилов mappa-зоны)? подтвердить адресанта. +3. **Обновление core (immutable)** — путь, который предложит task:1461 + (entity-update / перезасев / ограничение+ручной шаг) — подтвердить при финализации.