Деплой каталога скилов на сервер 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)

Вход: письмо-уведомление от владельцев репо (что изменилось: скилы/версии) → ops-таска на борде .admin (если ещё нет) → прогон по этому ранбуку.
Pre-flight: git pull каталога-репо; проверить, что README/скрипт 1461 на месте; admin_secret_scan — 0 хитов (тела скилов с секретом → 422).
Dry-run: прогнать deploy-скрипт каталога в режиме по умолчанию (--dry-run) → сверить план: какие скилы создаются/обновляются, нет ли неожиданного.
Apply: повторный прогон без dry-run (команда — из README репо, DRAFT).
Verify (см. ниже).
Фиксация: письмо-отчёт владельцам репо (verify-таблица) + закрытие ops-таски.

Конкретика по каждому каталогу: core-вариант (mappa-skills) и methodology-вариант (mappa-vitya-skills, фильтр mappa-vitya-) — скрипты из task:1461.

Стоящее правило: деплой при каждом изменении исходников

Прогон деплоя каталога скилов — при каждом изменении исходников в каталогах-репо. Уведомление — письмом от владельцев репо (mappa-зона — держатель исходников).

Владельцы репо при каждом замерженном изменении исходников (новый SKILL.md / правка / удаление) шлют письмо-уведомление в .admin (inbox_send, from проект-владелец, type action): какие скилы затронуты, что изменилось.
.admin по письму: ops-таска (при необходимости) → прогон деплоя по этому ранбуку (dry-run → apply → verify) → письмо-отчёт + закрытие таски.
Триггер — только письмо. Без 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

kind=core immutable — PATCH/DELETE /skills → 403. Обновление существующих core-скилов: рабочий путь решает task:1461 (entity-update / иной API-путь / документированное ограничение + перезасев). Не пытаться PATCH'ить core. (2026-08-28)
422 secret-scan — тело SKILL.md с секретом (token/password/… ≥6 симв.) → POST /skills → 422. Перед деплоем прогон mcp__mappa__admin_secret_scan (0 hits).
Направление не путать — репо → mappa (этот ранбук, deploy) vs mappa → диск (sync-skills.ts). Перепутать = «обновление с диска» не имеет смысла: каталог — источник, диск — потребитель. (2026-08-28)
Триггер письмом, не таской — таска на борде .admin не пингует живую сессию; уведомление = письмо (канон mappa-messaging). Без письма деплой не стартует. (2026-08-28)

Открытые вопросы (needs-human, task:1462)

Стоящее правило (текст выше) — подтвердить формулировку «деплой при каждом изменении исходников, уведомление письмом от владельцев репо».
Владельцы репо-отправители — кто шлёт письма: mappa (держатель исходников скилов mappa-зоны)? подтвердить адресанта.
Обновление core (immutable) — путь, который предложит task:1461 (entity-update / перезасев / ограничение+ручной шаг) — подтвердить при финализации.

9.3 KiB Raw Blame History Unescape Escape