crank/docs/demo-runbook.md

Demo Runbook

1. Цель документа

Этот документ фиксирует минимальный воспроизводимый сценарий запуска и демонстрации Crank без знания внутренней структуры кода.

2. Предусловия

• доступен PostgreSQL;
• заданы POSTGRES_HOST, POSTGRES_PORT, POSTGRES_DB, POSTGRES_USER, POSTGRES_PASSWORD;
• задан CRANK_STORAGE_ROOT;
• доступны CRANK_ADMIN_BIND и CRANK_MCP_BIND;
• если нужен заполненный demo state без ручного онбординга, задан CRANK_DEMO_SEED=true;
• для UI установлен Node.js;
• для Rust-части установлен toolchain из rust-toolchain.toml.

3. Быстрый локальный запуск

Backend

cargo run -p admin-api

Для предзаполненного demo state:

CRANK_DEMO_SEED=true cargo run -p admin-api

Во втором терминале:

cargo run -p mcp-server

UI

cd apps/ui
npm install
npm run dev

4. Контрольные health endpoints

curl http://127.0.0.1:3001/health
curl http://127.0.0.1:3002/health

Ожидаемо:

• admin-api возвращает {"service":"admin-api","status":"ok"}
• mcp-server возвращает {"service":"mcp-server","status":"ok"}

5. Demo flow

REST

1. Создать REST operation через UI или admin-api.
2. Выполнить test-run.
3. Опубликовать operation.
4. Проверить появление tool в MCP через tools/list.
5. Выполнить tools/call.

GraphQL

1. Создать GraphQL operation с фиксированным query или mutation.
2. Выполнить test-run.
3. Экспортировать YAML.
4. Импортировать YAML в режиме upsert.
5. Опубликовать operation и вызвать ее через MCP.

gRPC

1. Создать gRPC operation.
2. Загрузить descriptor set.
3. Проверить grpc/services discovery summary.
4. Выполнить test-run.
5. Экспортировать YAML.
6. Импортировать YAML в режиме upsert.
7. Опубликовать operation и вызвать ее через MCP.

6. Проверка publish/reload flow

После публикации новой операции mcp-server не требует restart.

Проверка:

1. Открыть MCP session.
2. Вызвать tools/list.
3. Опубликовать новую operation через admin-api.
4. Повторно вызвать tools/list.
5. Убедиться, что новый tool появился после refresh interval.

7. Проверка YAML roundtrip

YAML roundtrip считается успешным, если:

1. operation экспортируется через /api/admin/operations/{operation_id}/export;
2. экспортированный YAML импортируется через /api/admin/operations/import?mode=upsert;
3. создается новая версия operation;
4. test-run новой версии проходит успешно.

8. Что считать готовым demo state

• все три протокола проходят сценарий create -> test-run -> publish -> MCP call;
• YAML export/import проходит хотя бы для REST, GraphQL и gRPC;
• mcp-server подхватывает published changes без restart;
• ошибки admin-api и runtime возвращаются в читаемом виде;
• логи позволяют понять, какая операция создавалась, тестировалась, публиковалась или импортировалась.

9. Post-deploy smoke

Если demo запускается не локально, а на staging/production-like стенде, после deploy нужно пройти отдельный checklist:

• deploy-and-staging-smoke.md