tgcloud-mcp 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alexander Khmara
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,126 @@
-# Temporary Holding Version
+# tgcloud-mcp — MCP-сервер для Telegram serverless bots
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![CI](https://github.com/sdamarketing/tgcloud_mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/sdamarketing/tgcloud_mcp/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/tgcloud-mcp?style=flat-square)](https://www.npmjs.com/package/tgcloud-mcp)
+[![ghcr](https://img.shields.io/badge/ghcr-sdamarketing%2Ftgcloud--mcp-blue?style=flat-square)](https://github.com/sdamarketing/tgcloud_mcp/pkgs/container/tgcloud-mcp)
+
+Учит AI-ассистента управлять serverless-ботами Telegram ([core.telegram.org/bots/serverless](https://core.telegram.org/bots/serverless)):
+вы говорите ассистенту «создай бота», «задеплой», «покажи статус вебхука» — а он выполняет
+это через `tgcloud` CLI, не трогая терминал руками.
+
+Работает с любым MCP-клиентом: **opencode, Claude Code, Claude Desktop, Cursor, VS Code (Copilot), Windsurf, Zed**.
+
+## Что умеет
+
+14 инструментов — полный срез команд `tgcloud` CLI:
+
+| Категория | Инструменты | Что делают |
+|---|---|---|
+| **Жизненный цикл** | `create_project`, `init_project`, `login_bot`, `add_module` | скаффолд проекта, привязка бота по токену @BotFather, новые хендлеры и lib-модули |
+| **Синхронизация** | `status`, `diff`, `push`, `pull`, `fetch`, `reset` | просмотр изменений, атомарный деплой, синхронизация с облаком |
+| **Данные** | `run_handler`, `migrate` | прогон хендлера без деплоя (с логами), миграции БД с dry-run |
+| **Вебхук** | `webhook_status`, `webhook_sync` | диагностика «бот молчит», перенастройка вебхука |
+
+Плюс MCP-**ресурсы** `tgcloud://docs/*` — встроенная справка платформы
+(структура проекта, правила импортов, `sdk/db`, `sdk/api`, `sdk/fetch`, CLI).
+
+## Безопасность
+
+- **Деструктивное требует подтверждения.** `reset`, `push --force`, `webhook sync --drop-pending`
+  и применение миграций отказываются работать без `confirm: true` — ассистент сначала покажет,
+  что будет изменено, и спросит согласие.
+- **Токены не утекают.** Токен бота передаётся в CLI через stdin и маскируется во всех выводах —
+  ассистент никогда его не видит в ответах инструментов.
+
+## Установка
+
+Требуется Node.js 20+ (CLI платформы tgcloud требует 18+).
+
+**Из npm:**
+
+```bash
+npm install -g tgcloud-mcp
+tgcloud-mcp setup     # мастер: настройка MCP-клиента
+```
+
+**В одну команду (macOS / Linux / WSL)** — клон в `~/.tgcloud-mcp` + мастер:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/sdamarketing/tgcloud_mcp/main/install.sh | bash
+```
+
+**Docker:**
+
+```bash
+docker run -i --rm ghcr.io/sdamarketing/tgcloud-mcp
+```
+
+**Из исходников:**
+
+```bash
+git clone https://github.com/sdamarketing/tgcloud_mcp.git
+cd tgcloud_mcp
+npm install && npm test    # build + smoke + e2e
+```
+
+Подробно (токены, клиенты, переменные, решение проблем) — **[docs/SETUP.md](docs/SETUP.md)**.
+
+## Подключение к агенту
+
+Конфиг MCP-клиента (пример для opencode / Claude Code / Cursor — формат `mcpServers` одинаковый):
+
+```json
+{
+  "mcpServers": {
+    "tgcloud": {
+      "command": "tgcloud-mcp"
+    }
+  }
+}
+```
+
+Переменные окружения (опционально):
+
+| Переменная | По умолчанию | Назначение |
+|---|---|---|
+| `TGCLOUD_CLI` | `npx` | Команда запуска CLI (можно указать глобально установленный `tgcloud`) |
+| `TGCLOUD_CLI_ARGS` | `tgcloud` | Аргументы-префикс перед субкомандой |
+| `TGCLOUD_TIMEOUT_MS` | `120000` | Таймаут одной команды CLI |
+
+## Пример диалога
+
+> **Вы:** создай эхо-бота в ~/bots/echo  
+> **Агент:** `create_project` → `login_bot` (спросит токен у @BotFather) → правит `handlers/message.js` → `push` → `webhook_sync` — бот жив.  
+> **Вы:** напиши тест и проверь  
+> **Агент:** `run_handler` с payload `{ chat: { id: 1 }, text: "hi" }` — показывает вывод и логи.
+
+## Кукбук
+
+📗 **[Serverless-бот с мини-аппом за вечер](docs/cookbook-srl-bot.md)** — пошаговый
+рецепт на примере реального бота «Дневник обучения»: скаффолд, токены, база и миграции,
+inline-кнопки, Mini App с endpoints. Самоснятые форматы CLI и грабли включены.
+
+## Скилл для агентов
+
+В репозитории лежит скилл `skills/tgcloud` — процедурные знания для агента:
+структура проекта, правила bare-импортов, рецепты (`create → login → run → push`),
+guardrails платформы. Установка: скопируйте каталог в `~/.agents/skills/tgcloud`
+или подключите через ваш менеджер скиллов.
+
+## Структура репозитория
+
+```
+src/
+├─ index.ts            # сервер, регистрация инструментов/ресурсов
+├─ config.ts           # env-конфиг
+├─ runner.ts           # запуск tgcloud CLI: spawn, таймауты, маскировка секретов
+├─ utils.ts            # runTool/result-хелперы, dangerTool (confirm-guard)
+└─ tools/              # lifecycle, sync, data, webhook
+resources/docs/        # справка платформы → MCP-ресурсы
+skills/tgcloud/        # скилл для AI-агентов
+scripts/smoke-test.mjs # stdio smoke-тест
+```
+
+## Лицензия
+
+MIT

package/bin/tgcloud-mcp.mjs

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import '../dist/index.js';

package/dist/config.js

@@ -0,0 +1,12 @@
+export function loadConfig() {
+    const commandArgs = (process.env.TGCLOUD_CLI_ARGS ?? 'tgcloud')
+        .split(' ')
+        .map((s) => s.trim())
+        .filter(Boolean);
+    const timeoutMs = Number(process.env.TGCLOUD_TIMEOUT_MS ?? '120000');
+    return {
+        command: process.env.TGCLOUD_CLI ?? 'npx',
+        commandArgs,
+        timeoutMs: Number.isFinite(timeoutMs) && timeoutMs > 0 ? timeoutMs : 120000,
+    };
+}

package/dist/index.js

@@ -0,0 +1,31 @@
+#!/usr/bin/env node
+import { readFileSync } from 'node:fs';
+import { McpServer } from '@modelcontextprotocol/server';
+import { StdioServerTransport } from '@modelcontextprotocol/server/stdio';
+import { loadConfig } from './config.js';
+import { TgcloudRunner } from './runner.js';
+import { registerLifecycleTools } from './tools/lifecycle.js';
+import { registerSyncTools } from './tools/sync.js';
+import { registerDataTools } from './tools/data.js';
+import { registerWebhookTools } from './tools/webhook.js';
+import { registerDocResources } from './resources.js';
+async function main() {
+    const config = loadConfig();
+    const runner = new TgcloudRunner(config);
+    const server = new McpServer({
+        name: 'tgcloud',
+        version: JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version,
+    });
+    registerLifecycleTools(server, runner);
+    registerSyncTools(server, runner);
+    registerDataTools(server, runner);
+    registerWebhookTools(server, runner);
+    registerDocResources(server);
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+main().catch((cause) => {
+    const message = cause instanceof Error ? cause.message : String(cause);
+    process.stderr.write(`tgcloud-mcp failed to start: ${message}\n`);
+    process.exit(1);
+});

package/dist/resources.js

@@ -0,0 +1,49 @@
+import { readFile } from 'node:fs/promises';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+const DOCS_DIR = join(dirname(fileURLToPath(import.meta.url)), '..', 'resources', 'docs');
+const DOCS = [
+    {
+        name: 'tgcloud-project-structure',
+        uri: 'tgcloud://docs/project-structure',
+        title: 'Структура проекта tgcloud и правила импортов',
+        file: 'project-structure.md',
+        description: 'handlers/, lib/, schema.js, .tgcloud/; только bare-импорты, без относительных путей и расширений',
+    },
+    {
+        name: 'tgcloud-cli',
+        uri: 'tgcloud://docs/cli',
+        title: 'Справочник tgcloud CLI',
+        file: 'cli.md',
+        description: 'init, login, add, run, status, diff, push, pull, fetch, reset, migrate, webhook, completion',
+    },
+    {
+        name: 'tgcloud-sdk-db',
+        uri: 'tgcloud://docs/sdk-db',
+        title: 'sdk/db — база данных',
+        file: 'sdk-db.md',
+        description: 'schema.js, таблицы и модификаторы, query builder, insert/update/delete, raw SQL',
+    },
+    {
+        name: 'tgcloud-sdk-api',
+        uri: 'tgcloud://docs/sdk-api',
+        title: 'sdk/api — Telegram Bot API',
+        file: 'sdk-api.md',
+        description: 'Вызов любых методов Bot API, развёрнутый result, BotApiError',
+    },
+    {
+        name: 'tgcloud-sdk-fetch',
+        uri: 'tgcloud://docs/sdk-fetch',
+        title: 'sdk/fetch — HTTP-клиент',
+        file: 'sdk-fetch.md',
+        description: 'fetch с body-хелперами (json/form/text), лимит 32 МБ, только текстовые ответы',
+    },
+];
+export function registerDocResources(server) {
+    for (const doc of DOCS) {
+        server.registerResource(doc.name, doc.uri, { title: doc.title, description: doc.description, mimeType: 'text/markdown' }, async (uri) => {
+            const text = await readFile(join(DOCS_DIR, doc.file), 'utf8');
+            return { contents: [{ uri: uri.href, text, mimeType: 'text/markdown' }] };
+        });
+    }
+}

package/dist/runner.js

@@ -0,0 +1,111 @@
+import { spawn } from 'node:child_process';
+import { statSync } from 'node:fs';
+import { isAbsolute, resolve } from 'node:path';
+import { maskSecrets } from './utils.js';
+export class TgcloudError extends Error {
+    code;
+    stderr;
+    constructor(message, code, stderr) {
+        super(message);
+        this.code = code;
+        this.stderr = stderr;
+        this.name = 'TgcloudError';
+    }
+}
+export class TgcloudRunner {
+    config;
+    constructor(config) {
+        this.config = config;
+    }
+    /** Проверяет project_dir: абсолютный путь к существующему каталогу. */
+    resolveProjectDir(dir) {
+        if (!isAbsolute(dir)) {
+            throw new Error(`project_dir должен быть абсолютным путём, получено: ${dir}`);
+        }
+        let st;
+        try {
+            st = statSync(dir);
+        }
+        catch {
+            throw new Error(`Каталог не существует: ${dir}`);
+        }
+        if (!st.isDirectory()) {
+            throw new Error(`Не является каталогом: ${dir}`);
+        }
+        return resolve(dir);
+    }
+    /** Запуск произвольной команды (npm create и т.п.). */
+    exec(command, args, opts) {
+        return this.spawn(command, args, opts);
+    }
+    /** Запуск tgcloud CLI: tgcloud <args...> в каталоге проекта. */
+    tgcloud(args, opts) {
+        return this.spawn(this.config.command, [...this.config.commandArgs, ...args], opts);
+    }
+    /** Тот же запуск, но с ошибкой при ненулевом коде возврата. */
+    async tgcloudOrThrow(args, opts) {
+        const out = await this.tgcloud(args, opts);
+        const text = [out.stdout, out.stderr].filter(Boolean).join('\n').trim();
+        if (out.code !== 0) {
+            throw new TgcloudError(`tgcloud завершился с кодом ${out.code}:\n${text}`, out.code, out.stderr);
+        }
+        return text || '(команда выполнена, вывод пуст)';
+    }
+    spawn(command, args, opts) {
+        const timeoutMs = opts.timeoutMs ?? this.config.timeoutMs;
+        return new Promise((resolvePromise, rejectPromise) => {
+            const child = spawn(command, args, {
+                cwd: opts.cwd,
+                env: { ...process.env, ...opts.env },
+                stdio: ['pipe', 'pipe', 'pipe'],
+            });
+            let stdout = '';
+            let stderr = '';
+            let settled = false;
+            const timer = setTimeout(() => {
+                if (!settled) {
+                    settled = true;
+                    child.kill('SIGKILL');
+                    rejectPromise(new Error(`Таймаут команды (${timeoutMs} мс): ${command} ${args.join(' ')}`));
+                }
+            }, timeoutMs);
+            child.stdout.on('data', (d) => {
+                stdout += d.toString();
+            });
+            child.stderr.on('data', (d) => {
+                stderr += d.toString();
+            });
+            child.on('error', (err) => {
+                if (!settled) {
+                    settled = true;
+                    clearTimeout(timer);
+                    rejectPromise(new Error(`Не удалось запустить ${command}: ${err.message}`));
+                }
+            });
+            child.on('close', (code) => {
+                if (!settled) {
+                    settled = true;
+                    clearTimeout(timer);
+                    resolvePromise({
+                        code: code ?? -1,
+                        stdout: maskSecrets(stdout),
+                        stderr: maskSecrets(stderr),
+                    });
+                }
+            });
+            if (opts.input !== undefined) {
+                child.stdin.write(opts.input);
+            }
+            child.stdin.end();
+        });
+    }
+    /** Форматирует вывод команды в читаемый текст для агента. */
+    format(out) {
+        const parts = [`exit code: ${out.code}`];
+        if (out.stdout.trim())
+            parts.push(`--- stdout ---\n${out.stdout.trim()}`);
+        if (out.stderr.trim())
+            parts.push(`--- stderr ---\n${out.stderr.trim()}`);
+        return parts.join('\n');
+    }
+}

package/dist/tools/data.js

@@ -0,0 +1,63 @@
+import * as z from 'zod/v4';
+import { dangerTool, runTool } from '../utils.js';
+const projectDir = z
+    .string()
+    .describe('Абсолютный путь к каталогу проекта tgcloud (содержит .tgcloud/)');
+const confirm = z
+    .boolean()
+    .optional()
+    .describe('Обязательный confirm: true для применения миграций, удаляющих данные (deprecated-колонки/таблицы)');
+export function registerDataTools(server, runner) {
+    server.registerTool('run_handler', {
+        title: 'Прогнать хендлер без деплоя',
+        description: 'Выполняет модуль на платформе c локальными файлами, без деплоя (tgcloud run). ' +
+            'Быстрый способ проверить хендлер: payload и контекст — в формате JSON5. ' +
+            'Возвращает вывод и захваченные console-логи.',
+        inputSchema: z.object({
+            project_dir: projectDir,
+            module: z.string().describe('Путь модуля, например handlers/message'),
+            args: z
+                .string()
+                .optional()
+                .describe('Аргумент-хендлера в JSON5, например \'{ chat: { id: 1 }, text: "hi" }\''),
+            ctx: z.string().optional().describe('Контекст выполнения в JSON5 (передаётся как --ctx)'),
+        }),
+    }, async (args) => runTool(async () => {
+        const cwd = runner.resolveProjectDir(args.project_dir);
+        const cliArgs = ['run', args.module];
+        if (args.args !== undefined)
+            cliArgs.push(args.args);
+        if (args.ctx !== undefined)
+            cliArgs.push('--ctx', args.ctx);
+        return runner.format(await runner.tgcloud(cliArgs, { cwd }));
+    }));
+    server.registerTool('migrate', {
+        title: 'Миграции базы данных',
+        description: 'Применяет изменения schema.js к базе (tgcloud migrate). ' +
+            'По умолчанию dry_run=true — только показывает diff без изменений (--dry-run). ' +
+            'Применение (dry_run=false) требует confirm: true и идёт неинтерактивно через --yes: ' +
+            'если в схеме есть .deprecated(...)-колонки/таблицы, данные будут удалены безвозвратно. ' +
+            'В интерактивном терминале migrate без флагов спрашивает по каждому изменению ' +
+            '([y]es / [n]o / [q]uit); для агента используй только --dry-run и --yes.',
+        inputSchema: z.object({
+            project_dir: projectDir,
+            dry_run: z
+                .boolean()
+                .optional()
+                .describe('true (по умолчанию) — только предпросмотр изменений (--dry-run)'),
+            confirm,
+        }),
+    }, async (args) => {
+        if (args.dry_run !== false) {
+            return runTool(async () => {
+                const cwd = runner.resolveProjectDir(args.project_dir);
+                return runner.format(await runner.tgcloud(['migrate', '--dry-run'], { cwd }));
+            });
+        }
+        return dangerTool(args, async () => {
+            const cwd = runner.resolveProjectDir(args.project_dir);
+            const out = await runner.tgcloud(['migrate', '--yes'], { cwd });
+            return runner.format(out);
+        });
+    });
+}

package/dist/tools/lifecycle.js

@@ -0,0 +1,77 @@
+import * as z from 'zod/v4';
+import { runTool } from '../utils.js';
+const projectDir = z
+    .string()
+    .describe('Абсолютный путь к каталогу проекта tgcloud (содержит .tgcloud/)');
+export function registerLifecycleTools(server, runner) {
+    server.registerTool('create_project', {
+        title: 'Создать проект бота',
+        description: 'Скаффолдит новый проект serverless-бота через `npm create @tgcloud/bot <name>` ' +
+            'внутри каталога parent_dir. Требуется Node.js 18+ и доступ к npm registry.',
+        inputSchema: z.object({
+            parent_dir: z.string().describe('Абсолютный путь к каталогу, где будет создан проект'),
+            name: z
+                .string()
+                .regex(/^[a-z0-9][a-z0-9._-]*$/i, 'Имя проекта: латиница, цифры, точки, - и _')
+                .describe('Имя каталога нового проекта, например my-bot'),
+        }),
+    }, async (args) => runTool(async () => {
+        const parent = runner.resolveProjectDir(args.parent_dir);
+        const out = await runner.exec('npm', ['create', '--yes', '@tgcloud/bot', args.name], {
+            cwd: parent,
+        });
+        return runner.format(out);
+    }));
+    server.registerTool('init_project', {
+        title: 'Инициализировать пустой проект',
+        description: 'Скаффолдит проект tgcloud в существующем (обычно пустом) каталоге: schema.js, handlers/, lib/. Работает офлайн.',
+        inputSchema: z.object({ project_dir: projectDir }),
+    }, async (args) => runTool(async () => {
+        const cwd = runner.resolveProjectDir(args.project_dir);
+        return runner.format(await runner.tgcloud(['init'], { cwd }));
+    }));
+    server.registerTool('login_bot', {
+        title: 'Привязать бота к проекту',
+        description: 'Выполняет `tgcloud login`: привязывает бота к проекту по CLI access token ' +
+            '(формат app<id>:<secret>; @BotFather → ваш бот → Serverless → CLI Access → Access token). ' +
+            'Это НЕ API-токен бота вида 123456:AA…. ' +
+            'CLI требует интерактивный терминал, поэтому токен передаётся через stdin с ' +
+            'TGCLOUD_ASSUME_TTY=1; во всех выводах токен маскируется. ' +
+            'НИКОГДА не показывай токен пользователю после вызова. ' +
+            'Для CI вместо login достаточно переменной окружения TGCLOUD_TOKEN на shell.',
+        inputSchema: z.object({
+            project_dir: projectDir,
+            token: z
+                .string()
+                .regex(/^app\d+:[A-Za-z0-9_-]+$/, 'Ожидается CLI access token формата app<id>:<secret>')
+                .describe('CLI access token из @BotFather (Serverless → CLI Access), формат app<id>:<secret>'),
+        }),
+    }, async (args) => runTool(async () => {
+        const cwd = runner.resolveProjectDir(args.project_dir);
+        const out = await runner.tgcloud(['login'], {
+            cwd,
+            input: `${args.token}\n`,
+            env: { TGCLOUD_ASSUME_TTY: '1' },
+        });
+        return runner.format(out);
+    }));
+    server.registerTool('add_module', {
+        title: 'Добавить модуль',
+        description: 'Скаффолдит модуль через `tgcloud add <target>` (в tgcloud/-layout). ' +
+            'handlers/<type> — хендлер апдейтов (плоско, один уровень; типы: message, callback_query, ' +
+            'inline_query, chat_member, my_chat_member и др.); endpoints/<name> — серверная функция ' +
+            'Mini App (POST /api/<name>); lib/<path> — общий модуль (вложенные пути допускаются). ' +
+            'Существующие файлы не перезаписываются.',
+        inputSchema: z.object({
+            project_dir: projectDir,
+            target: z
+                .string()
+                .regex(/^(handlers|endpoints|lib)\/[a-z0-9._/-]+$/i, 'target: handlers/<type>, endpoints/<name> или lib/<path>')
+                .describe('Путь модуля, например handlers/callback_query, endpoints/getProfile или lib/cart'),
+        }),
+    }, async (args) => runTool(async () => {
+        const cwd = runner.resolveProjectDir(args.project_dir);
+        const out = await runner.tgcloud(['add', args.target], { cwd });
+        return runner.format(out);
+    }));
+}

package/dist/tools/sync.js

@@ -0,0 +1,79 @@
+import * as z from 'zod/v4';
+import { dangerTool, runTool } from '../utils.js';
+const projectDir = z
+    .string()
+    .describe('Абсолютный путь к каталогу проекта tgcloud (содержит .tgcloud/)');
+const confirm = z
+    .boolean()
+    .optional()
+    .describe('Обязательный confirm: true для деструктивных операций (флаг --force, reset и т.п.)');
+export function registerSyncTools(server, runner) {
+    server.registerTool('status', {
+        title: 'Статус проекта',
+        description: 'Показывает локальные изменения относительно задеплоенной версии (tgcloud status). Работает офлайн.',
+        inputSchema: z.object({ project_dir: projectDir }),
+    }, async (args) => runTool(async () => {
+        const cwd = runner.resolveProjectDir(args.project_dir);
+        return runner.format(await runner.tgcloud(['status'], { cwd }));
+    }));
+    server.registerTool('diff', {
+        title: 'Построчный diff',
+        description: 'Построчное сравнение локального проекта с задеплоенной версией (tgcloud diff). Работает офлайн.',
+        inputSchema: z.object({ project_dir: projectDir }),
+    }, async (args) => runTool(async () => {
+        const cwd = runner.resolveProjectDir(args.project_dir);
+        const out = await runner.tgcloud(['diff'], { cwd });
+        return out.stdout.trim() || '(изменений нет)';
+    }));
+    server.registerTool('push', {
+        title: 'Деплой в облако',
+        description: 'Загружает изменённые модули в облако атомарным батчем (tgcloud push). ' +
+            'Без files — зеркалирует всё локальное состояние. ' +
+            'force=true (пропуск проверок конкурентности) — деструктивно, требует confirm: true.',
+        inputSchema: z.object({
+            project_dir: projectDir,
+            files: z
+                .array(z.string())
+                .optional()
+                .describe('Конкретные файлы/каталоги для деплоя; без них — всё изменённое'),
+            force: z.boolean().optional().describe('Передать --force (опасно, требует confirm: true)'),
+            confirm,
+        }),
+    }, async (args) => {
+        const exec = async () => {
+            const cwd = runner.resolveProjectDir(args.project_dir);
+            const cliArgs = ['push'];
+            if (args.files?.length)
+                cliArgs.push(...args.files);
+            if (args.force)
+                cliArgs.push('--force');
+            return runner.format(await runner.tgcloud(cliArgs, { cwd }));
+        };
+        return args.force ? dangerTool(args, exec) : runTool(exec);
+    });
+    server.registerTool('pull', {
+        title: 'Синхронизировать из облака',
+        description: 'Приводит локальный проект к состоянию облака: обновляет референс-копию и рабочие файлы (tgcloud pull).',
+        inputSchema: z.object({ project_dir: projectDir }),
+    }, async (args) => runTool(async () => {
+        const cwd = runner.resolveProjectDir(args.project_dir);
+        return runner.format(await runner.tgcloud(['pull'], { cwd }));
+    }));
+    server.registerTool('fetch', {
+        title: 'Обновить референс-копию',
+        description: 'Обновляет локальную референс-копию задеплоенного состояния, НЕ трогая рабочие файлы (tgcloud fetch). Полезно перед разбором конфликтов.',
+        inputSchema: z.object({ project_dir: projectDir }),
+    }, async (args) => runTool(async () => {
+        const cwd = runner.resolveProjectDir(args.project_dir);
+        return runner.format(await runner.tgcloud(['fetch'], { cwd }));
+    }));
+    server.registerTool('reset', {
+        title: 'Откатить локальные изменения',
+        description: 'ДЕСТРУКТИВНО: отбрасывает все локальные изменения и восстанавливает рабочий каталог ' +
+            'к последнему известному состоянию облака (tgcloud reset). Требует confirm: true.',
+        inputSchema: z.object({ project_dir: projectDir, confirm }),
+    }, async (args) => dangerTool(args, async () => {
+        const cwd = runner.resolveProjectDir(args.project_dir);
+        return runner.format(await runner.tgcloud(['reset'], { cwd, input: 'y\n' }));
+    }));
+}

package/dist/tools/webhook.js

@@ -0,0 +1,38 @@
+import * as z from 'zod/v4';
+import { dangerTool, runTool } from '../utils.js';
+const projectDir = z
+    .string()
+    .describe('Абсолютный путь к каталогу проекта tgcloud (содержит .tgcloud/)');
+export function registerWebhookTools(server, runner) {
+    server.registerTool('webhook_status', {
+        title: 'Статус вебхука',
+        description: 'Показывает текущее состояние вебхука бота (tgcloud webhook): URL, allowed_updates, ' +
+            'накопившиеся апдейты и ошибки доставки. Первый шаг диагностики «бот молчит».',
+        inputSchema: z.object({ project_dir: projectDir }),
+    }, async (args) => runTool(async () => {
+        const cwd = runner.resolveProjectDir(args.project_dir);
+        return runner.format(await runner.tgcloud(['webhook'], { cwd }));
+    }));
+    server.registerTool('webhook_sync', {
+        title: 'Перенастроить вебхук',
+        description: 'Перенаправляет вебхук на проект и пересобирает allowed_updates (tgcloud webhook sync). ' +
+            'drop_pending=true отбрасывает накопившиеся апдейты — деструктивно, требует confirm: true.',
+        inputSchema: z.object({
+            project_dir: projectDir,
+            drop_pending: z
+                .boolean()
+                .optional()
+                .describe('Отбросить накопившиеся апдейты (--drop-pending, требует confirm: true)'),
+            confirm: z.boolean().optional().describe('Обязательный confirm: true при drop_pending=true'),
+        }),
+    }, async (args) => {
+        const exec = async () => {
+            const cwd = runner.resolveProjectDir(args.project_dir);
+            const cliArgs = ['webhook', 'sync'];
+            if (args.drop_pending)
+                cliArgs.push('--drop-pending');
+            return runner.format(await runner.tgcloud(cliArgs, { cwd }));
+        };
+        return args.drop_pending ? dangerTool(args, exec) : runTool(exec);
+    });
+}

package/dist/utils.js

@@ -0,0 +1,42 @@
+/** Маскирует секреты (токены ботов и т.п.) в тексте, который уходит агенту. */
+export function maskSecrets(text) {
+    return text
+        // Токен Telegram-бота: 123456789:AA...
+        .replace(/\b\d{6,12}:[A-Za-z0-9_-]{30,}\b/g, '***')
+        // Пары вида token=... / "token": "..." (длинные значения)
+        .replace(/((?:token|secret|password|authorization)["'\s:=]+)[^\s"',]{12,}/gi, '$1***');
+}
+export function jsonResult(data) {
+    const text = maskSecrets(data === undefined ? 'null' : JSON.stringify(data, null, 2));
+    return { content: [{ type: 'text', text }] };
+}
+export function textResult(text) {
+    return { content: [{ type: 'text', text: maskSecrets(text) }] };
+}
+export function errorResult(message) {
+    return { content: [{ type: 'text', text: maskSecrets(message) }], isError: true };
+}
+export async function runTool(fn) {
+    try {
+        const data = await fn();
+        return typeof data === 'string' ? textResult(data) : jsonResult(data);
+    }
+    catch (cause) {
+        const message = cause instanceof Error ? cause.message : String(cause);
+        return errorResult(message);
+    }
+}
+/**
+ * Guard для деструктивных операций: без confirm: true отказывает.
+ * Агент обязан показать пользователю, что будет изменено, получить явное
+ * согласие и только потом повторить вызов с confirm=true.
+ */
+export async function dangerTool(args, fn) {
+    return runTool(async () => {
+        if (args.confirm !== true) {
+            throw new Error('Отказано: деструктивная операция. Покажите пользователю, что именно будет изменено, ' +
+                'получите явное подтверждение и повторите вызов с confirm=true.');
+        }
+        return fn();
+    });
+}

package/package.json

@@ -1,6 +1,55 @@
 {
   "name": "tgcloud-mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "MCP server for Telegram serverless bots (@tgcloud) — project lifecycle, deploys, migrations and webhooks through the tgcloud CLI",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "tgcloud-mcp": "bin/tgcloud-mcp.mjs"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "typecheck": "tsc --noEmit",
+    "smoke": "node scripts/smoke-test.mjs",
+    "setup": "node scripts/setup.mjs",
+    "links": "node scripts/generate-install-links.mjs",
+    "docs:check": "node scripts/check-docs-drift.mjs",
+    "update": "node scripts/self-update.mjs",
+    "test": "npm run build && npm run smoke && node tests/e2e.mjs",
+    "prepublishOnly": "npm run test"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/server": "^2.1.0",
+    "zod": "^4.2.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "typescript": "^5.7.0"
+  },
+  "files": [
+    "dist",
+    "bin",
+    "resources",
+    "skills",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "mcp",
+    "telegram",
+    "bots",
+    "serverless",
+    "tgcloud"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sdamarketing/tgcloud_mcp.git"
+  },
+  "homepage": "https://github.com/sdamarketing/tgcloud_mcp",
+  "bugs": "https://github.com/sdamarketing/tgcloud_mcp/issues"
+}

package/resources/docs/cli.md

@@ -0,0 +1,85 @@
+# tgcloud CLI — справочник
+
+Требуется Node.js 18+. CLI — локальная dev-зависимость проекта (`@tgcloud/cli`),
+вызов из каталога проекта: `npx tgcloud <cmd>`.
+
+## Старт
+
+```bash
+npm create @tgcloud/bot my-bot    # скаффолд (CLI ставится в проект)
+npx tgcloud init                  # скаффолд в текущем каталоге (офлайн)
+npx tgcloud login                 # привязка бота — ИНТЕРАКТИВНО (нужен TTY)
+```
+
+**Токен** — CLI access token формата `app<id>:<secret>`
+(@BotFather → ваш бот → Serverless → CLI Access → Access token).
+Это НЕ Bot API токен вида `123456:AA…` — он будет отвергнут.
+
+Неинтерактивный логин:
+```bash
+printf 'app...\n' | TGCLOUD_ASSUME_TTY=1 npx tgcloud login
+# или для CI: export TGCLOUD_TOKEN='app...'  (тогда login не нужен вообще)
+```
+
+## Модули
+
+```bash
+npx tgcloud add handlers/callback_query   # хендлер апдейта
+npx tgcloud add endpoints/getProfile      # endpoint для Mini App
+npx tgcloud add lib/cart                  # общий модуль
+npx tgcloud add handlers                  # без имени — покажет ошибку-подсказку
+```
+Существующие файлы не перезаписываются.
+
+## Запуск без деплоя (server-side, локальные файлы)
+
+```bash
+npx tgcloud run handlers/message '{ chat: { id: 1 }, text: "hi" }'
+npx tgcloud run handlers/message "$(cat args.json5)"
+npx tgcloud run endpoints/getProfile '{}' --ctx '{ initData: { user: { id: 1 } } }'
+```
+Аргументы/контекст — JSON5. Вывод `console.*` захватывается и отображается.
+
+## Деплой и синхронизация
+
+**Деплой никогда не трогает базу** — миграции отдельным шагом.
+
+```bash
+npx tgcloud status         # локальные изменения vs снапшот (офлайн)
+npx tgcloud diff [file]    # построчный diff (офлайн)
+npx tgcloud push [files..] # атомарный деплой модулей (+ static-билд мини-аппа);
+                           # сообщит о pending-изменениях БД; обновляет вебхук
+npx tgcloud push --force   # пропустить проверки конкурентности (ОПАСНО)
+npx tgcloud fetch          # обновить локальный снапшот из облака (файлы не трогает)
+npx tgcloud pull           # облако → снапшот + рабочие файлы
+npx tgcloud reset [file]   # отбросить локальные изменения (офлайн, из снапшота)
+```
+
+## База данных
+
+```bash
+npx tgcloud push                 # сначала деплой schema.js; сообщит о pending-изменениях
+npx tgcloud migrate              # применить изменения (ИНТЕРАКТИВНО)
+npx tgcloud migrate --dry-run    # предпросмотр без применения
+```
+Удаление — только через `.deprecated('reason')` на колонке/таблице/индексе;
+удаление декларации ничего не дропает. Смена типа колонки — руками через `db.run()`.
+**Foreign keys нет** — `.references()`/`foreignKey()` бросают при декларации.
+
+## Вебхук
+
+Платформа сама управляет вебхуком (из задеплоенных handlers/*) и обновляет его на push.
+
+```bash
+npx tgcloud webhook                          # состояние и синхронность
+npx tgcloud webhook sync [--drop-pending]    # починить рассинхрон
+```
+
+## Прочее
+
+```bash
+npx tgcloud upgrade      # миграция layout проектов pre-0.2.0 → tgcloud/
+npx tgcloud completion <bash|zsh|fish>
+TG_CLOUD_API_URL=…       # переопределение базового URL API
+TGCLOUD_BETA=1           # /beta-окружение API
+```

package/resources/docs/project-structure.md

@@ -0,0 +1,98 @@
+# Структура проекта tgcloud
+
+Скаффолд (`npm create @tgcloud/bot my-bot`, @tgcloud/cli 0.2.x):
+
+```plaintext
+my-bot/
+├─ tgcloud/              # весь платформенный код — деплоится только он
+│  ├─ handlers/          # хендлеры апдейтов — плоско, один уровень
+│  │  ├─ message.js
+│  │  └─ callback_query.js
+│  ├─ endpoints/         # серверные функции для Mini App (POST /api/<name>)
+│  ├─ lib/               # общие модули; подкаталоги разрешены
+│  │  └─ internal/util.js
+│  └─ schema.js          # схема БД — один файл
+├─ tgcloud.jsonc         # конфиг проекта (static-блок для Mini App)
+├─ docs/tgcloud-sdk.md   # полный SDK-референс (в скаффолде)
+├─ AGENTS.md             # ориентация для AI-агентов (в скаффолде)
+└─ .tgcloud/             # состояние CLI: креды, снапшот, кэш (gitignored)
+```
+
+Деплоятся только `.js` под `tgcloud/` (`schema.js`, `lib/`, `handlers/`, `endpoints/`)
+плюс static-билд мини-аппа, если указан в `tgcloud.jsonc`. Имя модуля — путь
+внутри `tgcloud/` без расширения: `tgcloud/handlers/message.js` → `handlers/message`.
+
+## Правила импортов
+
+**Проектные модули — относительным путём С расширением `.js`; SDK — по имени.**
+
+```javascript
+// из tgcloud/handlers/message.js:
+import { users } from '../schema.js';          // ✅
+import { addItem } from '../lib/cart.js';      // ✅
+import { users } from '../schema';             // ❌ без .js — не компилируется
+import x from '../../src/x.js';                // ❌ вне tgcloud/ ничего недоступно
+import { db, api, fetch, BotApiError } from 'sdk';      // ✅ SDK по имени
+import { table, integer, text, eq, sql } from 'sdk/db'; // ✅ подмодули SDK
+```
+
+Исключение: имя модуля без расширения (`from 'lib/cart'`) тоже резолвится, но
+пишите относительные импорты — это канонический стиль платформы.
+
+В рантайме — V8 isolate: **нет файловой системы, нет npm-пакетов**.
+Доступны только `sdk` и модули проекта.
+
+## Хендлеры (handlers/)
+
+Файл по имени типа апдейта (`message`, `callback_query`, `inline_query`,
+`chat_member`, `my_chat_member`, …). `export default` вызывается с payload
+соответствующего типа; второй аргумент — `ctx` (полный `Update` — `ctx.update`):
+
+```javascript
+import { api } from 'sdk';
+
+export default async function (message, ctx) {
+  await api.sendMessage({
+    chat_id: message.chat.id,
+    text: `You said: ${message.text ?? '(no text)'}`,
+  });
+}
+```
+
+## Endpoints (endpoints/) — серверная сторона Mini App
+
+`tgcloud/endpoints/<name>.js` вызывается мини-аппом как `POST /api/<name>`:
+
+```javascript
+import { EndpointError } from 'sdk';
+
+export default async function (input, ctx) {
+  // input — JSON-тело (объект); возвращаемое значение уйдёт как JSON.
+  // ctx.initData — проверенные платформой init data; ctx.initData.user — вызывающий.
+  if (!ctx.initData.user) throw new EndpointError('Unauthorized', { code: 'AUTH' });
+  return { ok: true };
+}
+```
+
+- `EndpointError(description, { code })` → 400 с description/parameters;
+  любое другое исключение → безликий 500.
+- Вызов из фронта: `Telegram.WebApp.Serverless.call('<name>', input, (err, result) => …)`
+  из официального `telegram-web-app.js` (сам шлёт init data).
+- Имена: буквы, цифры, `_`, не с цифры. Скаффолд: `tgcloud add endpoints/<name>`.
+  Тест: `tgcloud run endpoints/<name> '{}' --ctx '{ initData: { user: { id: 1 } } }'`.
+
+## Mini App (фронтенд)
+
+- `tgcloud.jsonc` → `{ "static": { "source": "dist" } }` — build-папка деплоится и
+  хостится как Mini App на `https://app<app_id>.tgcloud.ai/` (`push` печатает точный URL).
+  Опции: `"spa": true`, `immutable`, `headers`, `redirects`; шорткат `"static": "dist"`;
+  `"static": false` — убрать сайт при следующем push.
+- **Собирай перед push** — push заливает папку как есть, build не запускает.
+- Фронт — обычный браузерный код с npm; недоступен из модулей tgcloud/ и наоборот.
+  Общается с ботом только через endpoints.
+- Не добавляй `X-Frame-Options`/строгий `frame-ancestors` — Mini App открывается в iframe.
+
+## Логирование
+
+`console.log/info/warn/error/trace`; вывод захватывается при `tgcloud run`,
+`error`/`trace` со стектрейсом, строки помечаются `[file:line]`.

package/resources/docs/sdk-api.md

@@ -0,0 +1,31 @@
+# sdk/api — Telegram Bot API
+
+Прямой доступ ко всему Telegram Bot API: `api.<method>(params)`.
+Поддерживаются все текущие и будущие методы без обновления SDK.
+
+```javascript
+import { api, BotApiError } from 'sdk';   // или from 'sdk/api'
+
+const me = await api.getMe();             // результат развёрнут из { ok, result }
+await api.sendMessage({ chat_id: id, text: 'Hello!' });
+await api.editMessageText({ chat_id, message_id, text: 'Updated' });
+await api.answerCallbackQuery({ callback_query_id, text: 'Done' });
+```
+
+- Параметры — snake_case Bot API (`chat_id`, `message_id`, `reply_markup`, …).
+- Ответ разворачивается из envelope `result`.
+- Ошибки бросают `BotApiError` с полями `.code`, `.description`, `.method`, `.parameters`.
+
+```javascript
+import { api, BotApiError } from 'sdk';
+
+try {
+  await api.deleteMessage({ chat_id, message_id });
+} catch (e) {
+  if (e instanceof BotApiError && e.code === 400) {
+    // 400 — сообщение уже удалено; ок
+  } else {
+    throw e;
+  }
+}
+```

package/resources/docs/sdk-db.md

@@ -0,0 +1,87 @@
+# sdk/db — база данных
+
+SQLite-подобная БД. Всё асинхронно — всегда `await`.
+
+## Схема (schema.js, один файл в корне)
+
+```javascript
+import { table, integer, text, boolean, json, index, unique, check, sql } from 'sdk/db';
+
+export const users = table('users', {
+  id:      integer('id').primaryKey({ autoIncrement: true }),
+  tgId:    integer('tg_id').unique(),
+  name:    text('name').notNull(),
+  lang:    text('lang').default('en'),
+  isAdmin: boolean('is_admin').default(false),
+  prefs:   json('prefs'),
+  created: integer('created_at', { mode: 'timestamp' }).default(sql`(unixepoch())`),
+}, (t) => ({
+  createdIdx: index('idx_users_created').on(t.created),
+  uqEmail:    unique('uq_email').on(t.email),
+  chk:        check('chk_done', sql`${t.done} in (0, 1)`),
+  lower:      index('idx_lower').on(sql`lower(${t.email})`),   // expression index
+  active:     index('idx_active').on(t.userId).where(sql`done = 0`),  // partial index
+}));
+```
+
+Модификаторы колонок: `.primaryKey({autoIncrement})`, `.notNull()`, `.unique()`,
+`.default(v)`, `.generatedAlwaysAs(sql\`...\`, { mode: 'stored' | 'virtual' })`,
+`.deprecated('reason')` — пометить на удаление (применится следующим `migrate` как warning-drop).
+
+Удалить таблицу: `table(...).deprecated('unused')`. Дропы происходят ТОЛЬКО через
+`.deprecated()` — удаление декларации из schema.js ничего не дропает.
+Смена типа колонки не автоматическая — вручную через `db.run(...)`.
+
+**Foreign keys нет**: `.references()`/`foreignKey()` бросают при декларации
+(рантайм работает с FK off) — целостность обеспечивает код приложения.
+
+**Деплой не трогает базу**: `push` только сообщает о pending-изменениях,
+применение — отдельным `tgcloud migrate` (интерактивно).
+
+## Запросы
+
+```javascript
+import { db } from 'sdk';
+import { todos } from 'schema';
+import { eq, and, desc, asc, count, sql } from 'sdk/db';
+
+await db.select().from(todos).all();                       // все строки
+await db.select().from(todos).where(eq(todos.id, 1)).get();// первая или null
+await db.select().from(todos).values();                    // массивы значений
+await db.select({ id: todos.id, n: count() })
+  .from(todos).groupBy(todos.userId).having(sql`count(*) > ${1}`).all();
+await db.$count(todos);                                    // count(*)
+await db.$count(todos, eq(todos.done, false));             // count с фильтром
+```
+
+Цепочки: `.where(c1, c2)` (AND), `.orderBy(desc(t.x), asc(t.id))`, `.limit(n)`, `.offset(n)`,
+`.groupBy(col)`, `.having(cond)`, `.distinct()`.
+
+Операторы из `sdk/db`: `eq ne gt gte lt lte like notLike isNull isNotNull and or not
+between notBetween inArray notInArray count sum avg min max asc desc sql`.
+
+## Insert / Update / Delete
+
+```javascript
+await db.insert(todos).values({ userId: 1, text: 'Buy milk' }).run();
+await db.insert(todos).values([{ text: 'A' }, { text: 'B' }]).run();      // батч
+await db.insert(todos).values({ text: 'X' }).returning().run();           // вернуть строку
+await db.insert(users).values({ tgId: 42, name: 'Ann' })
+  .onConflictDoUpdate({ target: users.tgId, set: { name: 'Ann' } }).run(); // upsert
+await db.update(todos).set({ done: true }).where(eq(todos.id, 1)).run();
+await db.delete(todos).where(eq(todos.id, 1)).run();
+```
+
+## Raw SQL
+
+```javascript
+await db.run('UPDATE todos SET done = 1 WHERE id = :id', { ':id': 5 });   // запись
+await db.all(sql`SELECT * FROM todos WHERE done = ${false}`);             // несколько строк
+await db.get(sql`SELECT count(*) AS c FROM todos`);                       // одна строка
+```
+
+Тег `sql` биндит `${value}` как параметр, `${table.column}` — как экранированный
+идентификатор; `sql.raw('...')` — литерал без биндинга. Вложенные фрагменты `sql` склеиваются.
+
+> Raw-запросы не привязаны к таблицам: boolean → 0/1, json → строка, timestamp → число.
+> Конверсия значений работает только в table-bound билдере.

package/resources/docs/sdk-fetch.md

@@ -0,0 +1,29 @@
+# sdk/fetch — HTTP-клиент
+
+Fetch-подобный клиент для внешних API и вебхуков. Ограничения: ответ только
+текстовый (бинарные payload не поддерживаются), лимит ответа — 32 МБ.
+
+```javascript
+import { fetch } from 'sdk';   // или from 'sdk/fetch'
+
+const res = await fetch('https://api.example.com/users', {
+  method: 'POST',
+  headers: { 'Content-Type': 'application/json' },
+  body: JSON.stringify({ name: 'Pavel' }),
+});
+if (!res.ok) throw new Error(res.statusText);
+const data = await res.json();
+```
+
+## Body-хелперы (выставляют Content-Type)
+
+```javascript
+await fetch(url, { method: 'POST', body: fetch.body.json({ a: 1 }) });   // application/json
+await fetch(url, { method: 'POST', body: fetch.body.form({ a: 1 }) });   // x-www-form-urlencoded
+await fetch(url, { method: 'POST', body: fetch.body.text('hi') });       // text/plain
+```
+
+## Ответ
+
+- `res.status` (number), `res.statusText`, `res.ok` (200–299), `res.url`, `res.headers`
+- `res.json()`, `res.text()`, `res.body` (ReadableStream — поточное чтение)

package/skills/tgcloud/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: tgcloud
+description: Управление serverless-ботами Telegram (@tgcloud) через tgcloud-mcp — скаффолд, токены, хендлеры, деплой, миграции БД, вебхуки. Use when the user asks to create/deploy/debug a Telegram serverless bot, mentions tgcloud, @tgcloud/bot, or works in a project with handlers/ + lib/ + schema.js.
+---
+
+# Skill: tgcloud
+
+Все операции — через MCP-инструменты сервера `tgcloud` (репозиторий tgcloud_mcp).
+Если инструментов нет — предложи установить: `npm install -g tgcloud-mcp` и добавить
+в конфиг MCP-клиента `{"mcpServers": {"tgcloud": {"command": "tgcloud-mcp"}}}`.
+
+Встроенная справка платформы доступна как MCP-ресурсы `tgcloud://docs/*` —
+читай ДО написания кода бота.
+
+## Правила платформы (коротко)
+
+- Структура: весь платформенный код в `tgcloud/` — `handlers/` (плоско, по типу
+  апдейта), `endpoints/` (серверные функции Mini App), `lib/` (можно вложенно),
+  `schema.js`. Рядом `tgcloud.jsonc`, `AGENTS.md`, `docs/tgcloud-sdk.md`.
+  `.tgcloud/` (креды/кэш) не коммитить.
+- Импорты: проектные модули — ОТНОСИТЕЛЬНЫМ путём С расширением `.js`
+  (`import { users } from '../schema.js'`); SDK — по имени
+  (`import { api, db, fetch, BotApiError } from 'sdk'`). Без .js у относительного
+  импорта — НЕ компилируется. Вне tgcloud/ недоступно ничего.
+- SDK: `api` — весь Bot API (ошибки — `BotApiError` с `.code`/`.description`);
+  `db` — query builder + raw SQL; `fetch` — текстовый HTTP, лимит 32 МБ;
+  `EndpointError` — корректный отказ endpoint'а (400).
+- Всё асинхронно, всегда `await`. Логи — `console.*` (видны при `run_handler`).
+- БД: без foreign keys; дропы только через `.deprecated('reason')`;
+  `push` не трогает БД — миграции отдельным шагом.
+- Токен для `login_bot` — CLI access token формата `app<id>:<secret>`
+  (@BotFather → бот → Serverless → CLI Access), НЕ Bot API токен.
+
+## Рецепты
+
+### Новый бот с нуля
+
+```
+create_project { parent_dir, name }          # npm create @tgcloud/bot
+→ спроси у пользователя CLI-токен из @BotFather
+login_bot { project_dir, token }             # токен никуда не выводим
+→ add_module / правим handlers/message.js, schema.js
+run_handler { project_dir, module: 'handlers/message', args: '{ chat: { id: 1 }, text: "hi" }' }
+push { project_dir }
+migrate { project_dir }                      # dry_run=true по умолчанию — предпросмотр
+webhook_sync { project_dir }                 # бот жив
+```
+
+### «Бот молчит»
+
+```
+webhook_status { project_dir }   # URL, allowed_updates, pending, ошибки доставки
+status / diff { project_dir }    # что не задеплоено
+push { project_dir }             # доставить изменения
+webhook_sync { project_dir }     # перепривязать вебхук
+```
+
+### Изменение схемы БД
+
+```
+1. правим schema.js
+2. push { project_dir }                              # деплой схемы
+3. migrate { project_dir }                           # dry-run предпросмотр
+4. показать пользователю изменения; если есть .deprecated(...) — предупредить об удалении данных
+5. migrate { project_dir, dry_run: false, confirm: true }
+```
+
+## Guardrails (жёстко)
+
+- `reset`, `push force`, `webhook_sync drop_pending`, `migrate dry_run:false` —
+  ТОЛЬКО с `confirm: true` после явного согласия пользователя.
+- Токен бота никогда не печатаем, не коммитим, не кладём в файлы — только в `login_bot`.
+- Не придумывай команды CLI — список в ресурсе `tgcloud://docs/cli`.