Деплой каталога скилов на сервер mappa

⚙️ СЛУЖЕБНЫЙ РАНБУК — только для администратора проекта .admin. Применять/выполнять шаги может только .admin (оператор проекта admin). Другим проектам/агентам — читать по запросу, не выполнять. Из проекта не выносить: не копировать в другие вики, не пересказывать, не публиковать. Нужен деплой или прод-операция по этому ранбуку — поставить задачу админу (.admin) и написать письмо. Админ выполняет, остальные верифицируют.

✅ Финализирован (2026-08-28, task:1462); core-путь обновлён 2026-08-28 (деплой 0.30.0, task:1469). Команды деплоя — из README каталогов (deploy-catalog.mjs, task:1461 done). Core-immutable — ЗАКРЫТ: с mappa 0.30.0 PATCH /skills kind=core работает (source=admin, task:1466 live); deploy-catalog (149ca36) применяет core программно. Ранбук отражает программный путь.

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 core — с source=admin (1466 live); DELETE core — 403.
Токен: MAPPA_API_TOKEN — <из pass mappa/full-env> (тот же, что env 3/3 стека mappa).
Deploy-скрипт (task:1461 done): scripts/deploy-catalog.mjs в каждом каталоге-репо (синк изменений вместо oneshot-засева seed-skills.ts, task:1448; kind по имени репо или --kind). Тесты: scripts/deploy-catalog.test.mjs (node --test scripts/). Семантика: отсутствующие → POST (create); изменённые → PATCH (update); core — PATCH с source=admin (1466 live с 0.30.0, deploy-catalog 149ca36); DELETE core — 403.
Обратное направление (НЕ этот ранбук): scripts/sync-skills.ts (task:1381) — синк каталога mappa → диск харнесса (pi/CC). Разделять: здесь деплой исходников в mappa.

Шаги (команды из README каталогов, task:1461)

Вход: письмо-уведомление от проекта-держателя каталога (что изменилось: скилы/версии) → ops-таска на борде .admin (если ещё нет) → прогон по ранбуку.
Pre-flight: git pull каталога-репо (mappa-skills / mappa-vitya-skills); ENV: MAPPA_API_TOKEN из pass mappa/full-env (+ MAPPA_CORE_URL опц., дефолт https://mappa.vds.kzntsv.site); admin_secret_scan — 0 хитов (тела с секретом → 422).
Dry-run (из чекаута каталога):
```
node scripts/deploy-catalog.mjs --dry-run   # дефолт тоже dry-run
```
Сверить план: create / update / up-to-date (core-правки помечаются (core, source=admin)) — нет ли неожиданного (лишний create = чужой каталог).
Apply:
```
node scripts/deploy-catalog.mjs --apply
```
Применяет create + update (PATCH; core — с source=admin, см. п.4).
core-обновление (программный путь, 1466 live с 0.30.0): если в плане есть ~ <name> (core, source=admin) — правки core применяются PATCH-ом (source=admin, event-аудит skill.core_update). Ручной шаг НЕ нужен. DELETE core — по-прежнему 403 (удаление — только фикс исходника / пересоздание каталога-сущности).
Verify (см. ниже).
Фиксация: письмо-отчёт проекту-держателю (verify-таблица) + закрытие ops-таски.

Конкретика: mappa-skills → kind=core (10 скилов), mappa-vitya-skills → kind=methodology (2 скила, фильтр mappa-vitya-). Скрипт определяет kind по имени репо (или --kind core|methodology).

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

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

Проект, который пушит изменения в каталог-репо, при каждом замерженном изменении исходников (новый SKILL.md / правка / удаление) шлёт письмо-уведомление в .admin (inbox_send, from проект-владелец, type action): какие скилы затронуты, что изменилось. Адресант НЕ фиксирован на проекте («кто пришлёт, тот и держатель»): сейчас mappa → mappa-skills (core), skills → mappa-vitya-skills (methodology); сменится владелец каталога — сменится адресант.
.admin по письму: ops-таска (при необходимости) → прогон деплоя по этому ранбуку (dry-run → apply → verify) → письмо-отчёт + закрытие таски.
Триггер — только письмо. Без CI/крона/автоматики (подтверждено оператором 2026-08-28).

Verify / smoke

GET https://mappa.vds.kzntsv.site/skills (с MAPPA_API_TOKEN) — затронутые скилы присутствуют, version актуальна (из frontmatter SKILL.md), enabled:true.
Прогон без ошибок: created/updated без 4xx/5xx (ошибки → в письме); PATCH применён (в т.ч. core — source=admin).
Потребительская сторона: sync-skills.ts подхватит обновления на дисках харнессов (после /reload, спека wiki:3300 п.11) — verify-контур, не часть деплоя.
База (первый прогон 2026-08-28 после деплоя 0.30.0): mappa-skills — 8 up-to-date + 2 updated (mappa-bootstrap, mappa-brainstorm-promote — через core-PATCH source=admin); mappa-vitya-skills — 2 up-to-date.

Rollback

Откат содержимого (methodology): revert коммита в репо-источнике → повторный --apply (PATCH вернёт прежнее тело).
Откат (core): revert коммита в репо-источнике → повторный --apply — PATCH с source=admin вернёт прежнее тело (программный путь).
Удаление ошибочного скила: methodology — DELETE /skills; core — DELETE 403 (только фикс исходника / пересоздание каталога-сущности).

Gotchas

kind=core PATCH — закрыт (1466 live с 0.30.0) — PATCH /skills kind=core с source=admin работает (event-аудит skill.core_update; deploy-catalog шлёт source=admin, 149ca36). Без source=admin — 403 (иммутабельность core для обычных агентов сохраняется). DELETE core — 403 всегда. (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)

Решения оператора (2026-08-28, inbox:2620)

Стоящее правило — подтверждено как сформулировано: деплой каталога при каждом изменении исходников; уведомление письмом → ops-таска → dry-run → apply → verify; триггер только письмом, без CI/автоматики.
Адресант уведомлений — НЕ фиксировать на проекте: «кто пришлёт, тот и держатель». Проект, пушащий изменения в каталог-репо, шлёт письмо в .admin. Сейчас: mappa (core), skills (methodology); сменится владелец каталога — сменится адресант.
Обновление core (immutable) — ДОДЕЛАТЬ: core должны обновляться деплоем по определённому пути. ВЫПОЛНЕНО (2026-08-28, деплой 0.30.0, task:1469): доработка /skills — task:1466 → PATCH core с source=admin; deploy-catalog применяет core программно.

Статус (2026-08-28): core-путь программный (1466 live); ранбук актуален; первый прогон после деплоя: 2 core-скила обновлены через core-PATCH (mappa-bootstrap, mappa-brainstorm-promote).

12 KiB Raw Blame History Unescape Escape