diff --git a/.wiki/concepts/runbooks-index.md b/.wiki/concepts/runbooks-index.md index 78721be..d03b3f6 100644 --- a/.wiki/concepts/runbooks-index.md +++ b/.wiki/concepts/runbooks-index.md @@ -47,7 +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 | +| Деплой каталога скилов на сервер mappa | [`skills-catalog-deploy-runbook.md`](skills-catalog-deploy-runbook.md) | синк репо-каталогов (mappa-skills/mappa-vitya-skills) → /skills на mappa.vds.kzntsv.site; deploy-catalog.mjs (dry-run → apply); стоящее правило «деплой при каждом изменении исходников» (письмо от держателя каталога); core-immutable interim до mappa task:1466/1467 | | 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 index 534e543..6069c96 100644 --- a/.wiki/concepts/skills-catalog-deploy-runbook.md +++ b/.wiki/concepts/skills-catalog-deploy-runbook.md @@ -13,10 +13,10 @@ updated: 2026-08-28 > Из проекта не выносить: не копировать в другие вики, не пересказывать, не публиковать. > Нужен деплой или прод-операция по этому ранбуку — **поставить задачу админу (`.admin`) и написать письмо**. Админ выполняет, остальные верифицируют. -> ⚠️ **DRAFT (2026-08-28, task:1462).** Секции «Артефакты/Шаги» в части команд -> заполняются после появления deploy-скриптов в каталогах-репо (mappa **task:1461**, -> blocked). Scope, стоящее правило, verify/rollback/gotchas — актуальны. Решения -> оператора по needs-human приняты (см. «Решения оператора»); финализация — после 1461. +> ✅ **Финализирован (2026-08-28, task:1462).** Команды деплоя — из README каталогов +> (deploy-catalog.mjs, task:1461 done). Core-immutable — **interim** (ручной шаг только +> с согласования оператора) до доработки /skills (mappa task:1466/1467): финальный +> механизм программный, ранбук обновится после их деплоя. ## Scope @@ -39,26 +39,44 @@ updated: 2026-08-28 - **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. +- **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); изменённые methodology → PATCH (update); + изменённый core → `! immutable` (не применяется). - **Обратное направление (НЕ этот ранбук):** `scripts/sync-skills.ts` (task:1381) — синк каталога mappa → диск харнесса (pi/CC). Разделять: здесь деплой исходников в mappa. -## Шаги (DRAFT — команды заполнить после task:1461) +## Шаги (команды из README каталогов, 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-таски. +0. **Вход:** письмо-уведомление от проекта-держателя каталога (что изменилось: + скилы/версии) → ops-таска на борде `.admin` (если ещё нет) → прогон по ранбуку. +1. **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). +2. **Dry-run** (из чекаута каталога): + ```bash + node scripts/deploy-catalog.mjs --dry-run # дефолт тоже dry-run + ``` + Сверить план: `create` / `update` / `immutable (!)` / `up-to-date` — нет ли + неожиданного (лишний create = чужой каталог; immutable = правка core). +3. **Apply:** + ```bash + node scripts/deploy-catalog.mjs --apply + ``` + Применяет create + update (**methodology** PATCH). Изменённый **core** — + `! immutable`, НЕ применяется (см. interim, п.4). +4. **core-immutable (interim, до деплоя mappa task:1466/1467):** если в плане есть + `! immutable` — правки core не применены. Путь: согласование с оператором → + обновление сущности вне API (админ-операция .admin / пересоздание) → повторный + dry-run подтверждает. **Финал — программный** (после 1466/1467); ручной шаг — + только с согласования оператора, не «ограничение навсегда». +5. **Verify** (см. ниже). +6. **Фиксация:** письмо-отчёт проекту-держателю (verify-таблица) + закрытие ops-таски. -> Конкретика по каждому каталогу: core-вариант (`mappa-skills`) и methodology-вариант -> (`mappa-vitya-skills`, фильтр `mappa-vitya-`) — скрипты из task:1461. +> Конкретика: `mappa-skills` → kind=core (10 скилов), `mappa-vitya-skills` → +> kind=methodology (2 скила, фильтр mappa-vitya-). Скрипт определяет kind по имени +> репо (или `--kind core|methodology`). ## Стоящее правило: деплой при каждом изменении исходников @@ -78,26 +96,30 @@ updated: 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; ошибки → в письме). + присутствуют, `version` актуальна (из frontmatter SKILL.md), `enabled:true`. +- Прогон без ошибок: created/updated без 4xx/5xx (ошибки → в письме); methodology — + PATCH применён; изменённый core — остался без применения (interim, зафиксировать в письме). - Потребительская сторона: `sync-skills.ts` подхватит обновления на дисках харнессов - (методология — после `/reload`, спека wiki:3300 п.11) — это verify-контур, не часть деплоя. + (после `/reload`, спека wiki:3300 п.11) — verify-контур, не часть деплоя. ## Rollback -- **Откат содержимого:** revert коммита в репо-источнике → повторный прогон деплоя - (пересинк вернёт прежнее состояние, если механизм обновления 1461 это позволяет). -- **Удаление ошибочного скила:** `kind=methodology` — DELETE /skills; `kind=core` — - **403**, удаление только через механизм 1461 (перезасев/иной путь) или фикс исходника. - > DRAFT: уточнить после 1461. +- **Откат содержимого (methodology):** revert коммита в репо-источнике → повторный + `--apply` (PATCH вернёт прежнее тело). +- **Откат (core):** до деплоя 1466/1467 — только админ-операция вне API (revert + исходника → ручной шаг с согласования оператора); после — программный путь из + ранбука-апдейта. +- **Удаление ошибочного скила:** methodology — DELETE /skills; core — 403 (до + 1466/1467 — админ-операция, после — контролируемый путь). ## Gotchas -1. **`kind=core` immutable** — PATCH/DELETE `/skills` → 403. Это **пробел сервера**, - не «ограничение + ручной шаг» как финал: core обязаны обновляться деплоем по - определённому пути → follow-up на доработку `/skills` (требование внесено в task:1461). - Ранбук фиксирует финальный механизм, когда 1461 его определит (до этого — DRAFT). - Не пытаться PATCH'ить core напрямую. (2026-08-28, решения оператора inbox:2620) +1. **`kind=core` immutable (interim)** — PATCH/DELETE `/skills` → 403, deploy-catalog + помечает правки core как `! immutable` и НЕ применяет. Это **пробел сервера** + (решение оператора inbox:2620: «ДОДЕЛАТЬ»): доработка /skills — mappa + **task:1466/1467** (ready; в README репо — 1466, в письме inbox:2625 — 1467 — + проверить дедуп). До её деплоя — ручной шаг только с согласования оператора. + Не пытаться 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 → диск @@ -115,8 +137,10 @@ updated: 2026-08-28 Проект, пушащий изменения в каталог-репо, шлёт письмо в .admin. Сейчас: mappa (core), skills (methodology); сменится владелец каталога — сменится адресант. 3. **Обновление core (immutable)** — ДОДЕЛАТЬ: core должны обновляться деплоем по - определённому пути. 403 = пробел сервера → follow-up на доработку /skills (требование - внесено в task:1461), не «ограничение + ручной шаг» как финал. Ранбук фиксирует - финальный механизм после 1461 (до этого — плейсхолдер DRAFT). + определённому пути. 403 = пробел сервера → доработка /skills (follow-up mappa + **task:1466/1467**, ready; дедуп проверить), не «ограничение + ручной шаг» как финал. + До деплоя доработки — **interim**: ручной шаг только с согласования оператора. -**Статус:** ждём закрытия mappa **task:1461** → финализация ранбука + снятие blocked (task:1462). +**Статус (2026-08-28):** task:1461 done → команды деплоя в ранбуке, task:1462 +финализирована; ранбук-апдейт финального core-механизма — после деплоя 1466/1467 +(штатный WRITE-апдейт).