@tgcloud/cli 0.1.0

package/src/core/run-output.js

@@ -0,0 +1,134 @@
+import chalk from 'chalk';
+import JSON5 from 'json5';
+
+/**
+ * Render server-side runtime output of a function: console.log/debug/info/warn/error
+ * entries plus the return value or error.
+ *
+ * Each log entry:
+ *   {
+ *     _: "log" | "dbg" | "inf" | "wrn" | "err",
+ *     t: <seconds-since-start>,
+ *     m: "<full message>",     // or…
+ *     M: "<truncated message>", // …if the server truncated it
+ *     o: "<module>:<line>"     // optional origin
+ *   }
+ *
+ * Total `time` (passed to formatRunReturn) is in seconds.
+ *
+ * Output format: single-char prefix per entry, message text, and time delta on
+ * the right. Args are pre-formatted by the server — the CLI only colorizes by
+ * severity.
+ */
+
+/**
+ * `> name(args)` — input invocation line. Shows only the module's basename
+ * (no directory) since that matches how a JS function is normally referenced.
+ * Plain weight so the trailing `< value` return line stands out via bold.
+ */
+export function formatRunHeader(moduleName, args) {
+  const baseName = moduleName.split('/').pop();
+  let argsText = '';
+  if (args !== undefined) {
+    try { argsText = formatValue(args); }
+    catch { argsText = String(args); }
+  }
+  return chalk.cyan('> ') + `${baseName}(${argsText})`;
+}
+
+export function formatRunLogs(logs) {
+  if (!Array.isArray(logs) || logs.length === 0) return [];
+
+  const lines = [];
+  let prevMs = 0;
+
+  for (const entry of logs) {
+    const tMs = (entry.t || 0) * 1000;
+    const deltaMs = Math.max(0, tMs - prevMs);
+    prevMs = tMs;
+
+    // `m` = full message; `M` = truncated. Mutually exclusive.
+    const truncated = entry.M != null;
+    const rawMessage = truncated ? entry.M : (entry.m ?? '');
+
+    const prefix = typePrefix(entry._);
+    const message = colorize(entry._, rawMessage);
+    const truncSuffix = truncated ? chalk.dim(' …[truncated]') : '';
+    const time = chalk.dim(`+${formatMs(deltaMs)}`);
+    const origin = formatOrigin(entry.o);
+    const originText = origin ? '  ' + chalk.dim(`[${origin}]`) : '';
+
+    lines.push(`${prefix} ${message}${truncSuffix}  ${time}${originText}`);
+  }
+
+  return lines;
+}
+
+/**
+ * Tint message text by severity. wrn/err get a coloured wash so the line
+ * stands out beyond the prefix chip; log/dbg/inf stay default.
+ */
+function colorize(type, text) {
+  switch (type) {
+    case 'wrn': return chalk.yellow(text);
+    case 'err': return chalk.red(text);
+    default:    return text;
+  }
+}
+
+/**
+ * Render the `o` (origin) field from a log entry. Accepts either a string
+ * (`"handlers/message:6"`) or an object (`{ m, l }` / `{ module, line }`).
+ */
+function formatOrigin(o) {
+  if (!o) return '';
+  if (typeof o === 'string') return o;
+  if (typeof o === 'object') {
+    const mod = o.m ?? o.module;
+    const line = o.l ?? o.line;
+    if (mod != null && line != null) return `${mod}:${line}`;
+    if (mod != null) return String(mod);
+  }
+  return '';
+}
+
+/**
+ * One-line representation of the return value: cyan `<` + bold value + dim total time.
+ * Only the value itself is bold so it stands out from the surrounding log stream
+ * and the plain-weight header above.
+ */
+export function formatRunReturn(value, totalSeconds) {
+  const valueText = chalk.bold(formatValue(value));
+  const timeText = totalSeconds != null
+    ? chalk.dim(`  ${formatMs(totalSeconds * 1000)}`)
+    : '';
+  return chalk.cyan('< ') + valueText + timeText;
+}
+
+function typePrefix(type) {
+  switch (type) {
+    case 'inf': return chalk.blue('i');
+    case 'wrn': return chalk.yellow('!');
+    case 'err': return chalk.red('x');
+    case 'dbg':
+    case 'log':
+    default:    return ' ';
+  }
+}
+
+export function formatValue(v) {
+  if (v === undefined) return chalk.dim('undefined');
+  if (typeof v === 'string') return v;
+  if (v && typeof v === 'object' && v.__error) {
+    return chalk.red(`Error: ${v.message || ''}`);
+  }
+  try {
+    return JSON5.stringify(v);
+  } catch {
+    return String(v);
+  }
+}
+
+function formatMs(ms) {
+  return Math.max(0, Math.round(ms)) + 'ms';
+}

package/src/core/scanner.js

@@ -0,0 +1,115 @@
+import fs from 'fs';
+import path from 'path';
+import { fatal, warn, info } from '../utils/logger.js';
+import { ROOT_FILES, moduleDirs, nestableDirs } from './project-layout.js';
+
+/**
+ * Return working-directory-relative paths of all project files, with `.js`.
+ *
+ * Includes:
+ *   - each root file (e.g. `schema.js`) at project root, if it exists
+ *   - Every `*.js` file under each module directory. `lib/` allows nesting
+ *     (`lib/internal/util.js`); `handlers/` must be flat.
+ *
+ * The layout (which root files / directories exist, and which directories may
+ * nest) comes from core/project-layout.js — the single source of truth.
+ *
+ * Bails out with a fatal error if a non-nestable directory contains
+ * subdirectories — surfacing the issue locally before any deploy/run round-trip.
+ *
+ * Note: anything OUTSIDE the root files and module directories is not scanned.
+ * A `.js` inside a non-module directory is silently excluded (intentional — it
+ * may be a build script). A stray `.js` at the *project root* is now flagged
+ * separately via findStrayFiles()/warnStrayFiles(), which the dedicated-folder
+ * layout makes safe.
+ */
+export function scanFiles() {
+  const files = [];
+  const nestable = nestableDirs();
+
+  for (const rootFile of ROOT_FILES) {
+    if (fs.existsSync(rootFile)) {
+      files.push(rootFile);
+    }
+  }
+
+  for (const dir of moduleDirs()) {
+    if (!fs.existsSync(dir)) continue;
+    walkJs(dir, dir, files, nestable);
+  }
+
+  // POSIX-normalize so paths match the snapshot/wire side on Windows (where
+  // path.join yields backslashes); no-op on POSIX. Keeps local-diff, the deploy
+  // manifest, and pull's orphan check comparing like-for-like.
+  return files.map((f) => f.split(/[\\/]/).join('/'));
+}
+
+function walkJs(currentDir, baseDir, out, nestable) {
+  for (const entry of fs.readdirSync(currentDir, { withFileTypes: true })) {
+    const full = path.join(currentDir, entry.name);
+    if (entry.isDirectory()) {
+      if (!nestable.has(baseDir)) {
+        fatal(
+          `${baseDir}/ must be flat — found subdirectory ${full}. ` +
+          `Only ${[...nestable].map((d) => d + '/').join(', ')} allow nested modules.`
+        );
+      }
+      walkJs(full, baseDir, out, nestable);
+    } else if (entry.isFile() && entry.name.endsWith('.js')) {
+      out.push(full);
+    }
+  }
+}
+
+// Config files legitimately live at a project root; don't mistake them for
+// misplaced modules. Covers dotfiles (`.eslintrc.js`) and the `*.config.js`
+// convention (`vite.config.js`, `eslint.config.js`, …).
+function isConfigFile(name) {
+  return name.startsWith('.') || /\.config\.js$/.test(name);
+}
+
+/**
+ * `*.js` files sitting directly at the project root that are neither a known
+ * root file (e.g. `schema.js`) nor a recognized config — i.e. modules the
+ * developer most likely misplaced (they would silently deploy to nothing).
+ *
+ * This is the loud counterpart to scanFiles()'s silent scoping, made safe by
+ * the dedicated-folder layout: the project root now holds only tgcloud content,
+ * so a bare `.js` there is unambiguous. Root-level
+ * only — `.js` inside a non-module directory is still intentionally ignored.
+ */
+export function findStrayFiles() {
+  const rootFiles = new Set(ROOT_FILES);
+  let entries;
+  try {
+    entries = fs.readdirSync('.', { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  const out = [];
+  for (const entry of entries) {
+    if (!entry.isFile() || !entry.name.endsWith('.js')) continue;
+    if (rootFiles.has(entry.name) || isConfigFile(entry.name)) continue;
+    out.push(entry.name);
+  }
+  return out;
+}
+
+/**
+ * Print a non-blocking warning for stray root-level `.js` (see findStrayFiles).
+ * Used by `status` and by a full `deploy`; a targeted `deploy` of a stray file
+ * is a hard error instead (handled in the deploy command). Returns the strays.
+ */
+export function warnStrayFiles() {
+  const strays = findStrayFiles();
+  if (!strays.length) return strays;
+  info('');
+  warn(
+    `${strays.length} stray .js file${strays.length === 1 ? '' : 's'} at the ` +
+    `project root will not be deployed:`
+  );
+  for (const f of strays) info(`  ${f}`);
+  const dirs = moduleDirs().map((d) => d + '/').join(', ');
+  info(`Move ${strays.length === 1 ? 'it' : 'them'} into a module directory (${dirs}) to deploy.`);
+  return strays;
+}

package/src/core/snapshot.js

@@ -0,0 +1,132 @@
+import fs from 'fs';
+import path from 'path';
+import { ensureTgcloudDir } from './state.js';
+
+const SNAPSHOT_DIR = path.join('.tgcloud', 'remote');
+
+// Normalize OS separators to the POSIX '/' used by the wire protocol and by
+// every snapshot-vs-server comparison. No-op on POSIX; on Windows it stops
+// backslash module names from breaking the deploy manifest and the pull
+// orphan check (which compares against server names that are always '/').
+function toPosix(p) {
+  return p.split(/[\\/]/).join('/');
+}
+
+/**
+ * Convert a file path (working-dir style, with .js) to a module name
+ * (API style, without .js). e.g. "handlers/message.js" → "handlers/message".
+ */
+export function pathToModule(filePath) {
+  const p = toPosix(filePath);
+  return p.endsWith('.js') ? p.slice(0, -3) : p;
+}
+
+/**
+ * Inverse of pathToModule. "handlers/message" → "handlers/message.js".
+ */
+export function moduleToPath(moduleName) {
+  const p = toPosix(moduleName);
+  return p.endsWith('.js') ? p : p + '.js';
+}
+
+/**
+ * True if .tgcloud/remote/ exists.
+ */
+export function snapshotExists() {
+  return fs.existsSync(SNAPSHOT_DIR);
+}
+
+/**
+ * Read a file from the snapshot. Returns string or null if missing.
+ * relPath is a working-dir-style path, e.g. "handlers/message.js".
+ */
+export function readSnapshotFile(relPath) {
+  const full = path.join(SNAPSHOT_DIR, relPath);
+  if (!fs.existsSync(full)) return null;
+  return fs.readFileSync(full, 'utf-8');
+}
+
+/**
+ * Write a file into the snapshot (creating parent directories as needed).
+ * The content is stored byte-identical to what was passed.
+ */
+export function writeSnapshotFile(relPath, content) {
+  ensureTgcloudDir();
+  const full = path.join(SNAPSHOT_DIR, relPath);
+  const dir = path.dirname(full);
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+  fs.writeFileSync(full, content);
+}
+
+/**
+ * Remove a file from the snapshot. No-op if missing.
+ */
+export function deleteSnapshotFile(relPath) {
+  const full = path.join(SNAPSHOT_DIR, relPath);
+  if (fs.existsSync(full)) fs.unlinkSync(full);
+}
+
+/**
+ * Walk .tgcloud/remote/ and return all file paths relative to it
+ * (e.g. "schema.js", "handlers/message.js").
+ */
+export function listSnapshotPaths() {
+  if (!fs.existsSync(SNAPSHOT_DIR)) return [];
+  const result = [];
+  walk(SNAPSHOT_DIR, '', result);
+  return result.map(toPosix); // POSIX-normalized so keys match server/scanner
+}
+
+function walk(root, rel, out) {
+  const abs = rel ? path.join(root, rel) : root;
+  for (const entry of fs.readdirSync(abs, { withFileTypes: true })) {
+    const childRel = rel ? path.join(rel, entry.name) : entry.name;
+    if (entry.isDirectory()) {
+      walk(root, childRel, out);
+    } else if (entry.isFile()) {
+      out.push(childRel);
+    }
+  }
+}
+
+/**
+ * Apply a canonical_modules map from a server response: write each module
+ * to the snapshot. Keys are module names (no .js); values are full content.
+ *
+ * @param {Object<string, string>} canonicalModules
+ */
+export function applyCanonicalModules(canonicalModules) {
+  if (!canonicalModules) return;
+  for (const [moduleName, content] of Object.entries(canonicalModules)) {
+    writeSnapshotFile(moduleToPath(moduleName), content);
+  }
+}
+
+/**
+ * Replace the entire snapshot with the given canonical_modules. Any files
+ * in the snapshot not present in the new map are removed. Used by `pull`
+ * and `fetch` to bring local snapshot into full sync with server state.
+ */
+export function replaceSnapshot(canonicalModules) {
+  // Ensure the snapshot dir exists even when the server returns no modules, so
+  // `status`/`diff` see a (correctly empty) snapshot rather than "no snapshot".
+  ensureTgcloudDir();
+  if (!fs.existsSync(SNAPSHOT_DIR)) fs.mkdirSync(SNAPSHOT_DIR, { recursive: true });
+
+  const existing = new Set(listSnapshotPaths());
+  const newPaths = new Set();
+
+  if (canonicalModules) {
+    for (const [moduleName, content] of Object.entries(canonicalModules)) {
+      const p = moduleToPath(moduleName);
+      writeSnapshotFile(p, content);
+      newPaths.add(p);
+    }
+  }
+
+  for (const existingPath of existing) {
+    if (!newPaths.has(existingPath)) {
+      deleteSnapshotFile(existingPath);
+    }
+  }
+}

package/src/core/state.js

@@ -0,0 +1,92 @@
+import fs from 'fs';
+import path from 'path';
+
+const TGCLOUD_DIR = '.tgcloud';
+const STATE_FILE = path.join(TGCLOUD_DIR, 'state.json');
+const CAPABILITIES_FILE = path.join(TGCLOUD_DIR, 'capabilities.json');
+
+/**
+ * Default empty state. Used when state.json does not exist yet.
+ */
+function emptyState() {
+  return {
+    last_known_revision: null,
+    init_templates: {},
+  };
+}
+
+/**
+ * Load state from .tgcloud/state.json.
+ * Returns an object with defaults for missing fields.
+ * If the file doesn't exist, returns an empty state.
+ */
+export function loadState() {
+  if (!fs.existsSync(STATE_FILE)) {
+    return emptyState();
+  }
+  try {
+    const raw = fs.readFileSync(STATE_FILE, 'utf-8');
+    const parsed = JSON.parse(raw);
+    return { ...emptyState(), ...parsed };
+  } catch {
+    return emptyState();
+  }
+}
+
+// Write atomically: stage to a temp sibling, then rename over the target.
+// rename is atomic on one filesystem, so a crash/Ctrl-C mid-write can't leave a
+// truncated file — which loadState()/loadCachedCapabilities() would silently
+// swallow as "empty", dropping last_known_revision and init_templates.
+function atomicWrite(file, content) {
+  const tmp = `${file}.${process.pid}.tmp`;
+  fs.writeFileSync(tmp, content);
+  try {
+    fs.renameSync(tmp, file);
+  } catch {
+    // Windows rename can reject an existing target — replace then retry.
+    try { fs.rmSync(file, { force: true }); fs.renameSync(tmp, file); }
+    finally { fs.rmSync(tmp, { force: true }); }
+  }
+}
+
+/**
+ * Save state to .tgcloud/state.json.
+ * Creates .tgcloud/ if it doesn't exist.
+ */
+export function saveState(state) {
+  ensureTgcloudDir();
+  atomicWrite(STATE_FILE, JSON.stringify(state, null, 2) + '\n');
+}
+
+/**
+ * Ensure .tgcloud/ directory exists.
+ */
+export function ensureTgcloudDir() {
+  if (!fs.existsSync(TGCLOUD_DIR)) {
+    fs.mkdirSync(TGCLOUD_DIR, { recursive: true });
+  }
+}
+
+/**
+ * Load the cached project-layout descriptor from .tgcloud/capabilities.json.
+ * Returns the raw object, or null if absent/unreadable. The caller validates
+ * (core/project-layout.js → validateDescriptor) before trusting it; offline
+ * commands read the layout from this cache.
+ */
+export function loadCachedCapabilities() {
+  if (!fs.existsSync(CAPABILITIES_FILE)) return null;
+  try {
+    return JSON.parse(fs.readFileSync(CAPABILITIES_FILE, 'utf-8'));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Persist the latest project-layout descriptor to .tgcloud/capabilities.json.
+ * Stored verbatim as received from the server (after the caller validated it).
+ */
+export function saveCachedCapabilities(descriptor) {
+  ensureTgcloudDir();
+  atomicWrite(CAPABILITIES_FILE, JSON.stringify(descriptor, null, 2) + '\n');
+}

package/src/core/sync.js

@@ -0,0 +1,50 @@
+import chalk from 'chalk';
+import { resolveToken, retryOnAuthError } from './credentials.js';
+import { syncCapabilities } from './capabilities.js';
+import { getFiles } from '../api/endpoints.js';
+import { describeServerError } from '../api/client.js';
+import { replaceSnapshot } from './snapshot.js';
+import { loadState, saveState } from './state.js';
+import { createSpinner } from '../utils/spinner.js';
+
+/**
+ * Download current server state into the local snapshot (.tgcloud/remote/) and
+ * update last_known_revision. The working directory is NOT touched.
+ *
+ * Shared by `tgcloud fetch` and `tgcloud login` (which syncs on bind so a first
+ * push conflict-checks against the bot's real state instead of force-overwriting
+ * it). Refreshes the layout descriptor first, then pulls the module
+ * space. Wrapped in retryOnAuthError so a stale token re-links cleanly.
+ *
+ * @returns {Promise<{ count: number, revision: number|null }>}
+ */
+export async function syncSnapshot({ spinnerText = 'Fetching snapshot...' } = {}) {
+  await syncCapabilities();
+  return await retryOnAuthError(async () => {
+    const token = await resolveToken();
+
+    const spinner = createSpinner(spinnerText);
+    spinner.start();
+
+    let response;
+    try {
+      response = await getFiles(token);
+      spinner.stop();
+    } catch (err) {
+      spinner.stop();
+      console.error(chalk.red('Error: ') + describeServerError(err));
+      throw err;
+    }
+
+    const canonical = response.canonical_modules || {};
+    replaceSnapshot(canonical);
+
+    if (response.revision != null) {
+      const s = loadState();
+      s.last_known_revision = response.revision;
+      saveState(s);
+    }
+
+    return { count: Object.keys(canonical).length, revision: response.revision ?? null };
+  });
+}

package/src/templates/AGENTS.md

@@ -0,0 +1,95 @@
+# AGENTS.md
+
+Orientation for AI coding assistants (and humans) working in this project.
+This file is auto-loaded by Claude Code, Cursor, and similar tools — keep it short
+and true. For the full SDK reference (db, Bot API, fetch), see
+[docs/tgcloud-sdk.md](docs/tgcloud-sdk.md).
+
+## What this project is
+
+A **Telegram Mini App bot** running on Telegram's serverless platform. You write
+JavaScript modules (database schema, shared library code, update handlers); the
+platform runs them in a V8 isolate. The `tgcloud` CLI syncs this local project
+with the bot's cloud environment — think `wrangler`/`vercel` + `drizzle-kit`.
+
+There is no server to run locally and no `node_modules` to import from at runtime:
+the only things available inside a module are the platform SDK and other modules
+in this project.
+
+## Layout
+
+| Path            | What it is                                                        |
+|-----------------|-------------------------------------------------------------------|
+| `schema.js`     | Database schema — tables as **named exports**. One file, at root. |
+| `lib/`          | Shared modules. Subdirectories allowed (`lib/internal/util.js`).  |
+| `handlers/`     | Update handlers, **one level only**. Names match Telegram Bot API update types (`message`, `callback_query`, …). |
+| `docs/`         | Reference docs (this project's, for you). Not deployed.           |
+| `.tgcloud/`     | CLI state (credentials, snapshot, cached layout). **Never edit or read from here** — it's gitignored machine state. |
+
+Only `.js` files in `schema.js`, `lib/`, and `handlers/` are deployed. Everything
+else (Markdown, config, `.tgcloud/`) is local-only.
+
+## Module system — the rules that bite
+
+- **Import by bare module name, never a relative path or file extension.**
+  The platform resolves modules by their name in the module space, not by the
+  filesystem.
+  - ✅ `import { users } from 'schema'`
+  - ✅ `import { addItem } from 'lib/cart'`
+  - ✅ `import { db, api, fetch } from 'sdk'` / `import { eq, sql } from 'sdk/db'`
+  - ❌ `import { users } from './schema'` or `'../schema'` → **won't compile**
+  - ❌ `import x from 'lib/cart.js'` → drop the `.js`
+- **No filesystem, no npm packages** at runtime. Only `sdk` (and its submodules
+  like `sdk/db`) and your own project modules exist.
+- A handler module's `export default` is what the platform invokes, with the
+  update's **payload** as the first argument — for `handlers/message` that's the
+  `Message` (i.e. `update.message`), for `handlers/callback_query` the
+  `CallbackQuery`, and so on. The full `Update` (with `update_id`) is on the
+  second argument: `ctx.update`.
+
+## Platform SDK (`import … from 'sdk'`)
+
+- **`db`** — the database (query builder + schema DSL). Full API: [docs/tgcloud-sdk.md](docs/tgcloud-sdk.md).
+- **`api`** — the Telegram Bot API. `api.<method>({...})` (e.g. `api.sendMessage`,
+  `api.getMe`) returns the **unwrapped** result and **throws `BotApiError`** on
+  failure (`import { BotApiError } from 'sdk'`; it has `.code`/`.description`/`.parameters`).
+- **`fetch`** — outbound HTTP, web-`fetch`-like (`res.status/ok`, `res.json()`,
+  `res.text()`, streaming via `for await`, redirects followed).
+
+## Database — the rules that bite
+
+Full API in [docs/tgcloud-sdk.md](docs/tgcloud-sdk.md). The non-obvious parts:
+
+- **Every DB call is async — always `await`.** `.all()`, `.get()`, `.values()`,
+  `.run()`, `db.$count()` and the raw `db.run/all/get` all return Promises.
+- **No foreign keys.** `.references()` and `foreignKey()` **throw at declaration**
+  — the runtime runs with FKs off, so they'd be silently inert. Enforce integrity
+  in application code (delete children before parents, etc.).
+- **Drops happen only via `.deprecated('reason')`** on a column/table/index.
+  Deleting the declaration does *not* drop anything.
+- **Type changes aren't automatic** — do them by hand with `db.run(...)`.
+
+## Deploy & migrate workflow
+
+**Deploying never touches the database.** Schema sync is a separate, explicit step.
+
+The CLI is a local dev-dependency, so run it with `npx tgcloud <command>` (or use
+the `npm run` scripts in package.json — e.g. `npm run deploy`):
+
+```
+npx tgcloud status     # what changed locally vs the cloud
+npx tgcloud push       # deploy modules to the cloud
+npx tgcloud migrate    # apply schema.js changes to the database (interactive)
+npx tgcloud run <module> [args]   # execute a handler server-side
+npx tgcloud pull       # bring the local project in line with the cloud
+npx tgcloud login      # link this project to a bot
+npx tgcloud webhook    # show the bot's webhook and whether it matches your handlers
+```
+
+After you change `schema.js`, `push` reports what the DB *would* change but applies
+nothing — run `npx tgcloud migrate` to actually apply it.
+
+The platform manages the bot's webhook for you, derived from your deployed
+`handlers/*`, and refreshes it on `push`. If it ever drifts — e.g. someone called
+`setWebhook` with the raw bot token — `npx tgcloud webhook` shows the mismatch and
+`npx tgcloud webhook sync` repairs it.