@tgcloud/cli 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Telegram Messenger
+
+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

@@ -0,0 +1,53 @@
+# @tgcloud/cli
+
+The command-line tool for [Telegram Serverless](https://core.telegram.org/bots/serverless) —
+run your bot's backend on Telegram's own infrastructure, with no server to host or scale.
+Write it in JavaScript, deploy with a single command, and manage your project, database,
+and bot right from the terminal.
+
+## Install
+
+The CLI is normally a project-local dev-dependency. The fastest way to start a
+new project — which installs it for you — is:
+
+```sh
+npm create @tgcloud/bot example_bot
+```
+
+To add it to an existing project:
+
+```sh
+npm install -D @tgcloud/cli
+```
+
+Inside a project you run it with `npx tgcloud <command>`, or through the `npm run`
+scripts the scaffold sets up.
+
+Requires Node.js 18 or newer.
+
+## Quick start
+
+```sh
+npx tgcloud init      # scaffold a project
+npx tgcloud login     # link a bot
+npx tgcloud push      # deploy
+```
+
+Run `npx tgcloud --help` to see every command.
+
+## Global install
+
+You can also install the CLI globally if you'd rather run a bare `tgcloud` from any
+folder instead of `npx tgcloud`:
+
+```sh
+npm install -g @tgcloud/cli
+```
+
+## Documentation
+
+Full documentation: https://core.telegram.org/bots/serverless
+
+## License
+
+MIT

package/bin/tgcloud.js

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

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@tgcloud/cli",
+  "version": "0.1.0",
+  "description": "CLI for the Telegram serverless platform",
+  "keywords": [
+    "telegram",
+    "telegram-bot",
+    "bot",
+    "serverless",
+    "cli",
+    "deploy",
+    "tgcloud"
+  ],
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "tgcloud": "bin/tgcloud.js"
+  },
+  "files": [
+    "bin",
+    "src"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "chalk": "^5.3.0",
+    "commander": "^12.0.0",
+    "diff": "^9.0.0",
+    "json5": "^2.2.3",
+    "ora": "^8.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/api/client.js

@@ -0,0 +1,136 @@
+const PROD_URL = 'https://cloud.telegram.org';
+// TG_CLOUD_API_URL overrides the base. TGCLOUD_BETA=1
+// targets the beta backend by appending /beta to whichever base is in effect.
+const API_BASE = process.env.TG_CLOUD_API_URL || PROD_URL;
+const BASE_URL =
+  process.env.TGCLOUD_BETA === '1' ? `${API_BASE.replace(/\/+$/, '')}/beta` : API_BASE;
+
+function isDebug() {
+  return process.env.TGCLOUD_DEBUG === '1' || process.env.TGCLOUD_DEBUG === 'true';
+}
+
+/**
+ * Extract app_id from token.
+ * Token format: "app1234:feiugjritgjr" → app_id = "app1234"
+ */
+function extractAppId(token) {
+  const parts = token.split(':');
+  if (parts.length !== 2 || !/^app\d+$/.test(parts[0])) {
+    throw new Error('Invalid token format. Expected "app<id>:<secret>".');
+  }
+  return parts[0];
+}
+
+export async function request(method, path, token, body) {
+  const appId = extractAppId(token);
+  const url = `${BASE_URL}/${appId}/manage${path}`;
+  const headers = {
+    'Authorization': `Bearer ${token}`,
+    'Content-Type': 'application/json',
+  };
+
+  if (isDebug()) {
+    // Bearer token is redacted. App-id (public part) is shown.
+    console.error(`\n[debug] → ${method} ${url}`);
+    console.error(`[debug]   Authorization: Bearer ${appId}:***`);
+    if (body !== undefined) {
+      console.error('[debug]   body:', JSON.stringify(body, null, 2));
+    }
+  }
+
+  const res = await fetch(url, {
+    method,
+    headers,
+    body: body ? JSON.stringify(body) : undefined,
+  });
+
+  return parseEnvelope(res);
+}
+
+/**
+ * Request a platform-global, unauthenticated endpoint (no app-id, no token) —
+ * e.g. GET /capabilities, which describes the project layout and is the same
+ * for every bot. Same `{ ok, result }` envelope as `request`.
+ */
+export async function requestPublic(method, path) {
+  const url = `${BASE_URL}${path}`;
+
+  if (isDebug()) {
+    console.error(`\n[debug] → ${method} ${url} (public)`);
+  }
+
+  const res = await fetch(url, {
+    method,
+    headers: { 'Content-Type': 'application/json' },
+  });
+
+  return parseEnvelope(res);
+}
+
+async function parseEnvelope(res) {
+  const rawText = await res.text();
+
+  if (isDebug()) {
+    console.error(`[debug] ← HTTP ${res.status} ${res.statusText}`);
+    console.error(`[debug]   body: ${rawText.length ? rawText : '(empty)'}`);
+  }
+
+  let data;
+  try {
+    data = JSON.parse(rawText);
+  } catch {
+    throw new Error(`Invalid response from server (not JSON). HTTP ${res.status}`);
+  }
+
+  if (typeof data !== 'object' || data === null || typeof data.ok === 'undefined') {
+    throw new Error('Invalid response format: expected { ok, result }.');
+  }
+
+  if (!data.ok) {
+    // Error envelope: { ok:false, description, error_code, parameters? }. The
+    // server sends a human `description`; `data.error` is an alternate string form
+    // used as a fallback.
+    const err = new Error(data.description || data.error || `Server error (HTTP ${res.status})`);
+    err.description = data.description;     // human text
+    err.code = data.error_code ?? data.error; // numeric error_code, or string form
+    err.status = res.status;
+    err.parameters = data.parameters || {};
+    throw err;
+  }
+
+  return data.result;
+}
+
+/**
+ * Human-facing one-liner for a server error: prefer the server's `description`,
+ * fall back to the code/message, and append the offending module when the
+ * server identifies one (e.g. MODULE_NAME_INVALID → which module).
+ */
+export function describeServerError(err) {
+  // Network/transport failure: fetch() rejects with a TypeError and no HTTP
+  // status (server errors always set err.status via parseEnvelope). The raw
+  // message is just "fetch failed", which isn't actionable — give the user
+  // something they can do something about.
+  if (
+    err &&
+    err.status == null &&
+    (err.name === 'TypeError' || /fetch failed/i.test(err.message || ''))
+  ) {
+    return (
+      `Could not reach the tgcloud server at ${BASE_URL}. ` +
+      'Check your connection (or the TG_CLOUD_API_URL setting).'
+    );
+  }
+
+  let msg = err?.description || err?.message || 'Server error';
+  const mod = err?.parameters?.module;
+  if (mod && !msg.includes(mod)) msg += ` (module: ${mod})`;
+  return stripControl(msg);
+}
+
+// Server-provided strings (error descriptions, version hints) get printed to the
+// user's terminal — strip control/escape bytes so a hostile or buggy server
+// can't inject ANSI sequences (screen clears, cursor moves, misleading output).
+export function stripControl(s) {
+  return String(s).replace(/[\x00-\x1f\x7f]/g, '');
+}

package/src/api/endpoints.js

@@ -0,0 +1,124 @@
+import { request, requestPublic, describeServerError } from './client.js';
+import { pathToModule, moduleToPath } from '../core/snapshot.js';
+
+/**
+ * Fetch the platform's project-layout descriptor (GET /capabilities).
+ * Global and unauthenticated — describes the shape of a project (root files,
+ * module directories and their flags), identical for every bot.
+ *
+ * Returns the raw descriptor object; validation/sanitization is the caller's
+ * job (core/project-layout.js → validateDescriptor).
+ */
+export async function fetchCapabilities() {
+  return requestPublic('GET', '/capabilities');
+}
+
+/**
+ * Batch deploy: push changed modules, implicitly delete modules not in the manifest.
+ *
+ * Concurrency control:
+ *   - If `expected_revision` is provided, server must match it atomically; otherwise
+ *     it returns a revision-mismatch error with the current revision.
+ *   - If `expected_revision` is null/omitted, the deploy is unconditional ("force").
+ *     Caller is responsible for any extra safety (e.g. --force flag).
+ *
+ * @param {string} token
+ * @param {object} payload
+ * @param {number|null} [payload.expected_revision] — client's last_known_revision
+ * @param {string[]}    payload.manifest            — full list of module names (without .js)
+ * @param {Object<string,string>} payload.changed_sources  — map moduleName → content
+ *
+ * @returns {Promise<{ revision: number, canonical_modules: Object<string,string>, db_changes?: any[] }>}
+ */
+export async function batchDeploy(token, { expected_revision, manifest, changed_sources }) {
+  const body = { manifest, changed_sources };
+  if (expected_revision != null) body.expected_revision = expected_revision;
+  return request('POST', '/deploy', token, body);
+}
+
+/**
+ * Run a module on the server without deploying.
+ *
+ * `moduleName` is the full module path without `.js`, e.g. "handlers/message".
+ * The server only accepts modules from `handlers/`.
+ *
+ * `sources` is the FULL module space for this invocation: { moduleName: code }.
+ * Server resolves all imports against `sources` only — its deployed state
+ * is not consulted. The target `moduleName` must be a key in `sources`.
+ */
+export async function runFunction(token, moduleName, sources, args, ctx) {
+  return request('POST', '/run', token, {
+    module: moduleName,
+    sources,
+    args,
+    ctx: ctx || {},
+  });
+}
+
+/**
+ * Full server state for pull/fetch.
+ * Returns { revision, canonical_modules: { moduleName: content } }.
+ */
+export async function getFiles(token) {
+  return request('GET', '/get', token);
+}
+
+/**
+ * Webhook status the platform manages (GET /webhook).
+ *
+ * The platform owns the bot's webhook (SDK Bot API `getWebhookInfo`/`setWebhook`
+ * are restricted), so this is a manage-plane read. Returns the live webhook plus
+ * `expected` (what the platform would set for the deployed handler set) and a
+ * server-computed `in_sync` verdict.
+ *
+ * @returns {Promise<{ url:string, allowed_updates:string[], pending_update_count:number,
+ *   last_error_date?:number, last_error_message?:string,
+ *   expected:{ url:string, allowed_updates:string[] }, in_sync:boolean }>}
+ */
+export async function getWebhook(token) {
+  return request('GET', '/webhook', token);
+}
+
+/**
+ * Re-assert the platform webhook + allowed_updates from the deployed handler set
+ * (POST /webhook/sync). Repairs a desync (e.g. someone called setWebhook with the
+ * raw bot token). Returns the same shape as getWebhook, now in_sync.
+ */
+export async function syncWebhook(token, { drop_pending = false } = {}) {
+  const body = {};
+  if (drop_pending) body.drop_pending_updates = true;
+  return request('POST', '/webhook/sync', token, body);
+}
+
+/**
+ * Get the current DB migration status without applying anything.
+ * Computes diff between DEPLOYED schema and DB.
+ * Returns { db_changes: [...] }.
+ */
+export async function getMigrationStatus(token) {
+  return request('GET', '/migrate', token);
+}
+
+/**
+ * Compute/apply migration via POST /migrate.
+ *
+ *   apply:   list of change id's to apply (see changeId() in db-changes.js).
+ *            Each id identifies one entry from the current db_changes list.
+ *            For safe changes the caller typically sends all ids in one call;
+ *            for warning changes — one id per call (per-change confirmation).
+ *   schema:  if present, server uses this schema string (instead of its
+ *            currently-deployed schema.js) for diff calculation. Server's
+ *            stored schema.js is NOT updated — caller must `push` afterward.
+ *   dry_run: if true, server only returns db_changes, no changes are applied.
+ *            `apply` is ignored when `dry_run: true`.
+ */
+export async function applyMigration(token, { apply, schema, dry_run = false } = {}) {
+  const body = {};
+  if (apply != null) body.apply = apply;
+  if (schema != null) body.schema = schema;
+  if (dry_run) body.dry_run = true;
+  return request('POST', '/migrate', token, body);
+}
+
+// Re-export for convenience
+export { pathToModule, moduleToPath, describeServerError };

package/src/cli.js

@@ -0,0 +1,51 @@
+import { program } from 'commander';
+import { enterProjectRoot } from './core/project-root.js';
+import { readCliVersion } from './core/capabilities.js';
+import { registerLogin } from './commands/login.js';
+import { registerInit } from './commands/init.js';
+import { registerAdd } from './commands/add.js';
+import { registerDeploy } from './commands/deploy.js';
+import { registerStatus } from './commands/status.js';
+import { registerDiff } from './commands/diff.js';
+import { registerRun } from './commands/run.js';
+import { registerPull } from './commands/pull.js';
+import { registerMigrate } from './commands/migrate.js';
+import { registerFetch } from './commands/fetch.js';
+import { registerReset } from './commands/reset.js';
+import { registerWebhook } from './commands/webhook.js';
+import { registerCompletion } from './commands/completion.js';
+
+program
+  .name('tgcloud')
+  .description('CLI for the Telegram serverless platform')
+  .version(readCliVersion())
+  .option('--debug', 'Log HTTP requests and responses')
+  .option('--no-pager', 'Disable the pager; write output straight to stdout')
+  .hook('preAction', (thisCommand, actionCommand) => {
+    const opts = thisCommand.opts();
+    if (opts.debug) process.env.TGCLOUD_DEBUG = '1';
+    // commander sets `pager: false` when --no-pager is given; default is `true`.
+    if (opts.pager === false) process.env.TGCLOUD_NO_PAGER = '1';
+
+    // Resolve the project root (nearest ancestor with .tgcloud/) and operate
+    // from there, so commands work from any subdirectory. `init` is exempt: it
+    // creates a new project in the current directory and guards against nesting
+    // itself.
+    if (actionCommand.name() !== 'init') enterProjectRoot();
+  });
+
+registerLogin(program);
+registerInit(program);
+registerAdd(program);
+registerDeploy(program);
+registerStatus(program);
+registerDiff(program);
+registerRun(program);
+registerPull(program);
+registerFetch(program);
+registerReset(program);
+registerMigrate(program);
+registerWebhook(program);
+registerCompletion(program);
+
+program.parse();

package/src/commands/add.js

@@ -0,0 +1,133 @@
+import fs from 'fs';
+import path from 'path';
+import chalk from 'chalk';
+import { fileURLToPath } from 'url';
+import { syncCapabilities } from '../core/capabilities.js';
+import {
+  moduleDirs,
+  nestableDirs,
+  directoryByName,
+  templates,
+  sanitizeRelPath,
+} from '../core/project-layout.js';
+import { success, info, fatal } from '../utils/logger.js';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const templatesDir = path.join(__dirname, '..', 'templates');
+
+// The reserved per-directory starter (on disk) that `add` scaffolds from — the
+// server serves the same template under the directory key ("handlers/").
+// `$$BASENAME$$` in it is replaced with the new module's name.
+const ADD_TEMPLATE = '_default_.js';
+// `$$BASENAME$$` → the leaf name (the update type for handlers/, the function
+// parameter). `$$MODULE$$` → the full module name incl. any nested lib/ path
+// (e.g. `lib/internal/util`), which is how the module is imported.
+const NAME_TOKEN = /\$\$BASENAME\$\$/g;
+const MODULE_TOKEN = /\$\$MODULE\$\$/g;
+
+// Split a raw target into (dir, leaf). Accepts a trailing `.js`, a trailing
+// slash, or no leaf at all (→ error). "handlers/message" →
+// { dir: 'handlers', leaf: 'message' }; "handlers" or "handlers/" →
+// { dir: 'handlers', leaf: null }.
+function parseTarget(raw) {
+  const s = String(raw).replace(/\\/g, '/').replace(/\.js$/i, '').replace(/\/+$/, '');
+  const segments = s.split('/').filter(Boolean);
+  if (!segments.length) return null;
+  const [dir, ...rest] = segments;
+  return { dir, leaf: rest.length ? rest.join('/') : null };
+}
+
+// Content for a new module: the directory's starter template — the server's
+// copy (from GET /capabilities `templates`, keyed by the directory itself, e.g.
+// `"handlers/"`), else the CLI's bundled `<dir>/dir-default.js`, else empty —
+// with `$$BASENAME$$` replaced by the module name.
+//
+// This directory-level template is deliberately distinct from the exact-path
+// `init` starters (e.g. the onboarding handlers/message.js): `init` seeds a
+// fresh project with worked examples; `add` gives a clean per-directory stub.
+// Sharing them would leak the onboarding echo into every added handler.
+function moduleContent(dir, moduleName, basename) {
+  const serverTemplates = templates();
+  let raw = serverTemplates[`${dir}/`];
+  if (raw == null) {
+    const bundled = path.join(templatesDir, dir, ADD_TEMPLATE);
+    raw = fs.existsSync(bundled) ? fs.readFileSync(bundled, 'utf-8') : '';
+  }
+  return raw.replace(MODULE_TOKEN, moduleName).replace(NAME_TOKEN, basename);
+}
+
+// A bare directory ("tgcloud add handlers") is an error — you must name the
+// module. When the directory advertises a closed vocabulary (handlers/ = update
+// types), the error lists the names still available so it's actionable without a
+// separate lookup. (Tab-completion offers the same set; see commands/completion.js.)
+function requireLeaf(dir, desc) {
+  const allowed = desc && desc.allowedNames;
+  if (allowed && allowed.length) {
+    const available = allowed.filter((n) => !fs.existsSync(path.join(dir, `${n}.js`)));
+    if (!available.length) fatal(`Every ${dir}/ module already exists.`);
+    fatal(
+      `Specify a name, e.g. "${dir}/${available[0]}". ` +
+      `Available ${dir}/ types: ${available.join(', ')}.`
+    );
+  }
+  fatal(`Specify a name, e.g. "${dir}/<name>".`);
+}
+
+export function registerAdd(program) {
+  program
+    .command('add <target>')
+    .description(
+      'Scaffold a new module — e.g. "tgcloud add handlers/message" or ' +
+      '"tgcloud add lib/cart". The name is required; give just the directory ' +
+      '("tgcloud add handlers") to see the valid names.'
+    )
+    .action(async (target) => {
+      // Refresh the layout so allowed names and directory templates reflect the
+      // latest server descriptor (best-effort; offline falls back to baseline).
+      await syncCapabilities();
+
+      const parsed = parseTarget(target);
+      if (!parsed) fatal(`Invalid target: ${target}`);
+      const { dir } = parsed;
+
+      const dirs = moduleDirs();
+      if (!dirs.includes(dir)) {
+        fatal(`Unknown directory "${dir}". Add modules under: ${dirs.map((d) => d + '/').join(', ')}.`);
+      }
+
+      const desc = directoryByName(dir);
+      const leaf = parsed.leaf;
+      if (!leaf) requireLeaf(dir, desc); // fatal — never returns
+
+      // A flat directory (e.g. handlers/) takes a single-segment name only.
+      if (leaf.includes('/') && !nestableDirs().has(dir)) {
+        fatal(`${dir}/ is flat — use a single name, not a nested path.`);
+      }
+
+      const relPath = `${dir}/${leaf}.js`;
+      if (!sanitizeRelPath(relPath)) {
+        fatal(`Invalid module name: ${leaf}`);
+      }
+
+      // Enforce a closed name set when the directory advertises one.
+      const finalName = leaf.split('/').pop();
+      if (desc && desc.allowedNames && !desc.allowedNames.includes(finalName)) {
+        fatal(
+          `"${finalName}" is not a valid ${dir}/ module name. ` +
+          `Allowed: ${desc.allowedNames.join(', ')}.`
+        );
+      }
+
+      if (fs.existsSync(relPath)) {
+        fatal(`${relPath} already exists.`);
+      }
+
+      const parentDir = path.dirname(relPath);
+      if (parentDir && parentDir !== '.') fs.mkdirSync(parentDir, { recursive: true });
+      fs.writeFileSync(relPath, moduleContent(dir, `${dir}/${leaf}`, finalName));
+
+      info(`Adding a new ${dir}/ module...`);
+      success(relPath);
+      info(`Edit it, then deploy with ${chalk.cyan('tgcloud push')}.`);
+    });
+}