@tgcloud/cli 0.1.0

package/src/commands/reset.js

@@ -0,0 +1,95 @@
+import fs from 'fs';
+import path from 'path';
+import { localDiff } from '../core/local-diff.js';
+import { readSnapshotFile, snapshotExists } from '../core/snapshot.js';
+import { confirm, closePrompts } from '../utils/prompt.js';
+import chalk from 'chalk';
+import { done, info, fatal } from '../utils/logger.js';
+
+/**
+ * Reset working-directory files to match the local snapshot.
+ * - With a file argument: reset that file (no confirmation).
+ * - Without: reset all changed files, with a single confirmation prompt.
+ *
+ * Semantics:
+ *   modified    → rewrite with snapshot content
+ *   newLocal    → delete (file was added locally, not in snapshot)
+ *   remoteOnly  → restore (file was deleted locally, still in snapshot)
+ */
+export function registerReset(program) {
+  program
+    .command('reset [file]')
+    .description('Discard local changes by copying from the local snapshot (offline)')
+    .action(async (targetFile) => {
+      try {
+        await runReset(targetFile);
+      } finally {
+        closePrompts();
+      }
+    });
+}
+
+async function runReset(targetFile) {
+      if (!snapshotExists()) {
+        fatal('No local snapshot. Run "tgcloud pull" or "tgcloud fetch" first.');
+      }
+
+      const diff = localDiff();
+      const changes = [
+        ...diff.modified.map((f) => ({ ...f, kind: 'modified' })),
+        ...diff.newLocal.map((f) => ({ ...f, kind: 'new' })),
+        ...diff.remoteOnly.map((f) => ({ ...f, kind: 'deleted' })),
+      ];
+
+      const filtered = targetFile
+        ? changes.filter((c) => c.path === targetFile)
+        : changes;
+
+      if (!filtered.length) {
+        info(targetFile
+          ? `${targetFile}: no local changes to reset.`
+          : 'Working directory clean. Nothing to reset.');
+        return;
+      }
+
+      // Without a file argument — confirm the full reset.
+      if (!targetFile) {
+        console.log(`Will reset ${filtered.length} file${filtered.length === 1 ? '' : 's'}:`);
+        for (const c of filtered) {
+          console.log('  ' + chalk.dim(`${labelFor(c.kind).padEnd(7)} →`) + ` ${c.path}`);
+        }
+        const ok = await confirm('Reset all local changes?');
+        if (!ok) {
+          info('Cancelled.');
+          return;
+        }
+      }
+
+      for (const c of filtered) {
+        if (c.kind === 'modified' || c.kind === 'deleted') {
+          const content = readSnapshotFile(c.path);
+          if (content == null) {
+            fatal(`Snapshot missing for ${c.path} (unexpected).`);
+          }
+          const dir = path.dirname(c.path);
+          if (dir !== '.' && !fs.existsSync(dir)) {
+            fs.mkdirSync(dir, { recursive: true });
+          }
+          fs.writeFileSync(c.path, content);
+          done(c.path, 'restored');
+        } else if (c.kind === 'new') {
+          if (fs.existsSync(c.path)) fs.unlinkSync(c.path);
+          done(c.path, 'removed');
+        }
+      }
+}
+
+// Bare verb; the caller pads it so the → arrows line up (longest is "restore").
+function labelFor(kind) {
+  switch (kind) {
+    case 'modified': return 'modify';
+    case 'new':      return 'remove';
+    case 'deleted':  return 'restore';
+    default:         return '';
+  }
+}

package/src/commands/run.js

@@ -0,0 +1,145 @@
+import fs from 'fs';
+import path from 'path';
+import chalk from 'chalk';
+import JSON5 from 'json5';
+import { resolveToken, retryOnAuthError } from '../core/credentials.js';
+import { syncCapabilities } from '../core/capabilities.js';
+import { scanFiles } from '../core/scanner.js';
+import { runnableDirs } from '../core/project-layout.js';
+import { pathToModule } from '../core/snapshot.js';
+import { runFunction, describeServerError } from '../api/endpoints.js';
+import { createSpinner } from '../utils/spinner.js';
+import { fatal } from '../utils/logger.js';
+import { formatRunHeader, formatRunLogs, formatRunReturn } from '../core/run-output.js';
+
+function parseJson5Inline(str, errorMsg) {
+  try {
+    return JSON5.parse(str);
+  } catch (err) {
+    fatal(`${errorMsg}: ${err.message}`);
+  }
+}
+
+function isRunnable(filePath, runnable) {
+  return runnable.some((dir) =>
+    filePath.startsWith(dir + path.sep) || filePath.startsWith(dir + '/')
+  );
+}
+
+function resolveFilePath(input) {
+  const runnable = runnableDirs();
+  const allowed = new Set(scanFiles().filter((p) => isRunnable(p, runnable)));
+  const candidates = [];
+
+  const withExt = input.endsWith('.js') ? input : `${input}.js`;
+
+  if (input.includes('/') || input.includes(path.sep)) {
+    candidates.push(withExt);
+  } else {
+    for (const dir of runnable) {
+      candidates.push(path.join(dir, withExt));
+    }
+  }
+
+  for (const candidate of candidates) {
+    const normalized = path.normalize(candidate);
+    if (allowed.has(normalized) && fs.existsSync(normalized)) {
+      return normalized;
+    }
+  }
+
+  for (const candidate of candidates) {
+    const normalized = path.normalize(candidate);
+    if (fs.existsSync(normalized) && !isRunnable(normalized, runnable)) {
+      fatal(
+        `${normalized} is not runnable. Only modules in ${runnable.map((d) => d + '/').join(' and ')} can be run.`
+      );
+    }
+  }
+
+  if (candidates.length === 1) {
+    fatal(`Module not found: ${candidates[0]}. Run "tgcloud status" to see your modules.`);
+  } else {
+    fatal(`Module not found in any of: ${candidates.join(', ')}. Run "tgcloud status" to see your modules.`);
+  }
+}
+
+export function registerRun(program) {
+  program
+    .command('run <module> [args]')
+    .description(
+      'Run a module in the cloud without deploying. <module> can be a bare ' +
+      'name (searches handlers/) or a relative path inside that directory. ' +
+      '[args] is an optional JSON5 expression with ' +
+      'arguments to pass to the function. ' +
+      'Read args from a file: tgcloud run module "$(cat args.json5)".'
+    )
+    .option('--ctx <json5>', 'JSON5 context')
+    .action(async (moduleArg, positionalArgs, options) => {
+      // Refresh the layout so the runnable-directory whitelist reflects any
+      // directories the platform has added since this CLI was released.
+      await syncCapabilities();
+
+      const filePath = resolveFilePath(moduleArg);
+      const moduleName = pathToModule(filePath);
+
+      const args = positionalArgs !== undefined
+        ? parseJson5Inline(positionalArgs, 'Invalid JSON5 in args')
+        : undefined;
+
+      const ctx = options.ctx !== undefined
+        ? parseJson5Inline(options.ctx, 'Invalid JSON5 in --ctx')
+        : undefined;
+
+      // Build the full module space from the local working directory.
+      // The server resolves all imports against this map alone — its deployed
+      // state is not consulted, so we send EVERY local module so locally
+      // modified `lib/*` (and others) are picked up. Syntax is validated
+      // server-side (it compiles only the imported graph and reports
+      // `Module error: … [module:line:col]`); we don't pre-check locally.
+      const allFiles = scanFiles();
+      const sources = {};
+      for (const f of allFiles) {
+        sources[pathToModule(f)] = fs.readFileSync(f, 'utf-8');
+      }
+      if (!(moduleName in sources)) {
+        fatal(`Internal: ${moduleName} not in collected sources.`);
+      }
+
+      try {
+        await retryOnAuthError(async () => {
+          const token = await resolveToken();
+
+          // Print the invocation header BEFORE starting the spinner, so the
+          // spinner animation appears underneath it: `>` line stays as the
+          // "input echo", spinner is the "in flight" indicator below.
+          console.log(formatRunHeader(moduleName, args));
+          const spinner = createSpinner('Running...');
+          spinner.start();
+
+          let result;
+          try {
+            result = await runFunction(token, moduleName, sources, args, ctx);
+            spinner.stop();
+          } catch (err) {
+            // Header already printed. Mirror the success path: any logs the
+            // server emitted, then a SINGLE error line (with timing when the
+            // server reported it). Don't use spinner.fail() here — it would
+            // print the (often multi-line) message a second time.
+            spinner.stop();
+            const params = err.parameters || {};
+            for (const line of formatRunLogs(params.log)) console.log(line);
+            const ms = params.time != null ? Math.max(0, Math.round(params.time * 1000)) : null;
+            const suffix = ms != null ? chalk.dim(`  ${ms}ms`) : '';
+            console.log(chalk.red(`✗ ${describeServerError(err)}`) + suffix);
+            throw err;
+          }
+
+          for (const line of formatRunLogs(result.log)) console.log(line);
+          console.log(formatRunReturn(result.result, result.time));
+        });
+      } catch {
+        process.exit(1);
+      }
+    });
+}

package/src/commands/status.js

@@ -0,0 +1,72 @@
+import chalk from 'chalk';
+import { localDiff } from '../core/local-diff.js';
+import { warnStrayFiles } from '../core/scanner.js';
+import { snapshotExists } from '../core/snapshot.js';
+import { loadState } from '../core/state.js';
+import { loadCredentials, maskToken } from '../core/credentials.js';
+import { webhookStatusLine } from './webhook.js';
+
+export function registerStatus(program) {
+  program
+    .command('status')
+    .description('Show working-directory status relative to the local snapshot (offline)')
+    .action(async () => {
+      // Linked-to info (best-effort, offline)
+      const creds = loadCredentials();
+      const state = loadState();
+
+      // Mirror resolveToken()'s priority (env first, then saved creds) so the
+      // shown app-id is the one commands actually use, and label both sources.
+      if (process.env.TGCLOUD_TOKEN) {
+        console.log(chalk.dim(`Linked to ${maskToken(process.env.TGCLOUD_TOKEN)} (from env)`));
+      } else if (creds?.token) {
+        console.log(chalk.dim(`Linked to ${maskToken(creds.token)} (saved)`));
+      } else {
+        console.log(chalk.dim('Not linked to a bot yet.'));
+      }
+
+      if (state.last_known_revision != null) {
+        console.log(chalk.dim(`Local revision: ${state.last_known_revision}`));
+      }
+
+      // Best-effort webhook health. status is otherwise offline; this line is the
+      // sole networked call, silent on any failure (see webhookStatusLine).
+      const whLine = await webhookStatusLine();
+      if (whLine) console.log(whLine);
+
+      if (!snapshotExists()) {
+        console.log('\n' + chalk.yellow('Warning: ') +
+          'No local snapshot. Run "tgcloud pull" or "tgcloud fetch" first.');
+      }
+
+      const diff = localDiff();
+
+      if (diff.modified.length) {
+        console.log(chalk.yellow('\nModified:'));
+        for (const f of diff.modified) console.log(`  ${f.path}`);
+      }
+
+      if (diff.newLocal.length) {
+        console.log(chalk.green('\nNew (not yet deployed):'));
+        for (const f of diff.newLocal) console.log(`  ${f.path}`);
+      }
+
+      if (diff.remoteOnly.length) {
+        console.log(chalk.red('\nDeleted locally (still in snapshot):'));
+        for (const f of diff.remoteOnly) console.log(`  ${f.path}`);
+      }
+
+      const anyChanges = diff.modified.length + diff.newLocal.length + diff.remoteOnly.length;
+
+      if (!anyChanges && diff.matched.length) {
+        console.log(chalk.green('\nWorking directory clean.'));
+      }
+
+      // Nudge about misplaced modules at the root (independent of tracked diff).
+      warnStrayFiles();
+
+      if (!anyChanges && !diff.matched.length) {
+        console.log('\nNo files found. Run "tgcloud init" to scaffold a project.');
+      }
+    });
+}

package/src/commands/webhook.js

@@ -0,0 +1,139 @@
+import chalk from 'chalk';
+import { resolveToken, retryOnAuthError, peekToken } from '../core/credentials.js';
+import { getWebhook, syncWebhook, describeServerError } from '../api/endpoints.js';
+import { stripControl } from '../api/client.js';
+import { createSpinner } from '../utils/spinner.js';
+import { info, success } from '../utils/logger.js';
+
+// Set difference for the allowed_updates diff shown on a mismatch.
+function diffSets(actual = [], expected = []) {
+  const a = new Set(actual);
+  const e = new Set(expected);
+  return {
+    missing: expected.filter((x) => !a.has(x)), // expected but not delivered
+    extra: actual.filter((x) => !e.has(x)),     // delivered but not expected
+  };
+}
+
+// Render a full webhook status block. `wh` is the server payload; the server
+// computes `in_sync` and we just display it.
+function renderWebhook(wh) {
+  // One value column for the whole block: 2-space indent + label padded to 18,
+  // so values line up at column 20 regardless of label length.
+  const row = (label, value) => console.log('  ' + `${label}:`.padEnd(18) + value);
+
+  console.log(chalk.dim('Webhook:'));
+  row('url', wh.url || chalk.dim('(none set)'));
+  row('allowed updates', (wh.allowed_updates || []).join(', ') || chalk.dim('(none)'));
+  row('pending updates', wh.pending_update_count ?? 0);
+  if (wh.last_error_message) {
+    // Plain text — a last error may be a one-off, not necessarily the current
+    // state. Timestamp trimmed to "YYYY-MM-DD HH:MM UTC" for readability. Guard
+    // the date: a NaN/out-of-range last_error_date would make toISOString() throw
+    // (RangeError) and kill the whole command with no message.
+    let when = '';
+    const ts = Number(wh.last_error_date);
+    if (Number.isFinite(ts)) {
+      const d = new Date(ts * 1000);
+      if (!Number.isNaN(d.getTime())) {
+        when = ` (${d.toISOString().slice(0, 16).replace('T', ' ')} UTC)`;
+      }
+    }
+    row('last error', `${stripControl(wh.last_error_message)}${when}`);
+  }
+
+  if (wh.in_sync) {
+    console.log(chalk.green('  ✓ in sync with your deployed handlers'));
+    return;
+  }
+
+  console.log(chalk.red('  ✗ OUT OF SYNC with your deployed handlers'));
+  const expected = wh.expected || {};
+  // Detail rows share the settings block's value column — the red status line
+  // already sets them apart, so no extra indent or color. Instead of a
+  // missing/stale diff, just show what the webhook should be (compare with the
+  // live "allowed updates" above).
+  if (expected.url && expected.url !== wh.url) {
+    row('expected url', expected.url);
+  }
+  const { missing, extra } = diffSets(wh.allowed_updates, expected.allowed_updates);
+  if (missing.length || extra.length) {
+    row('expected updates', (expected.allowed_updates || []).join(', '));
+  }
+  console.log('Run "tgcloud webhook sync" to fix.');
+}
+
+// Best-effort one-liner for `tgcloud status`. Returns a string or null; never
+// throws — status is an offline command, so any failure (offline, no token,
+// endpoint absent) just omits the line. Guarded by a short timeout so a slow or
+// unreachable server can't stall status (the manage `request` has no timeout).
+export async function webhookStatusLine({ timeoutMs = 2500 } = {}) {
+  try {
+    const token = peekToken();
+    if (!token) return null; // offline / not linked — status stays fully offline
+    const wh = await Promise.race([
+      getWebhook(token),
+      new Promise((_, reject) => setTimeout(() => reject(new Error('timeout')), timeoutMs)),
+    ]);
+    if (typeof wh?.in_sync !== 'boolean') return null;
+    if (wh.in_sync) return chalk.dim('Webhook: in sync');
+    return chalk.dim('Webhook: OUT OF SYNC') + '\n' +
+      chalk.yellow('Warning: ') + 'Webhook doesn\'t match your handlers. Run "tgcloud webhook sync" to fix.';
+  } catch {
+    return null;
+  }
+}
+
+export function registerWebhook(program) {
+  const cmd = program
+    .command('webhook')
+    .description('Show the bot webhook the cloud manages, and whether it is in sync')
+    .action(async () => {
+      try {
+        await retryOnAuthError(async () => {
+          const token = await resolveToken();
+          const spinner = createSpinner('Checking webhook...');
+          spinner.start();
+          let wh;
+          try {
+            wh = await getWebhook(token);
+            spinner.stop();
+          } catch (err) {
+            spinner.stop();
+            console.error(chalk.red('Error: ') + describeServerError(err));
+            throw err;
+          }
+          renderWebhook(wh);
+        });
+      } catch {
+        process.exit(1);
+      }
+    });
+
+  cmd
+    .command('sync')
+    .description('Re-point the webhook at the cloud and refresh allowed_updates from your handlers')
+    .option('--drop-pending', 'Discard updates queued at Telegram before the sync')
+    .action(async (opts) => {
+      try {
+        await retryOnAuthError(async () => {
+          const token = await resolveToken();
+          const spinner = createSpinner('Syncing webhook...');
+          spinner.start();
+          let wh;
+          try {
+            wh = await syncWebhook(token, { drop_pending: !!opts.dropPending });
+            spinner.stop();
+          } catch (err) {
+            spinner.stop();
+            console.error(chalk.red('Error: ') + describeServerError(err));
+            throw err;
+          }
+          success('Webhook synced.');
+          renderWebhook(wh);
+        });
+      } catch {
+        process.exit(1);
+      }
+    });
+}

package/src/core/capabilities.js

@@ -0,0 +1,83 @@
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import { fetchCapabilities } from '../api/endpoints.js';
+import { saveCachedCapabilities } from './state.js';
+import {
+  validateDescriptor,
+  resetLayout,
+  SUPPORTED_SCHEMA_VERSION,
+} from './project-layout.js';
+import { warn } from '../utils/logger.js';
+import { stripControl } from '../api/client.js';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const CLI_VERSION = readCliVersion();
+
+// Single source of truth for the CLI version — read from package.json, reused by
+// both the capabilities handshake and `tgcloud --version` (cli.js).
+export function readCliVersion() {
+  try {
+    const pkg = JSON.parse(
+      fs.readFileSync(path.join(__dirname, '..', '..', 'package.json'), 'utf-8')
+    );
+    return pkg.version || '0.0.0';
+  } catch {
+    return '0.0.0';
+  }
+}
+
+// Compare dotted numeric versions. Returns true if `a` is strictly older.
+function isOlder(a, b) {
+  const pa = String(a).split('.').map((n) => parseInt(n, 10) || 0);
+  const pb = String(b).split('.').map((n) => parseInt(n, 10) || 0);
+  for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
+    const x = pa[i] || 0;
+    const y = pb[i] || 0;
+    if (x !== y) return x < y;
+  }
+  return false;
+}
+
+/**
+ * Refresh the project-layout descriptor from the server (GET /capabilities),
+ * cache it, and make it the effective layout for the rest of this run.
+ *
+ * Best-effort and silent on failure: if the platform has no /capabilities
+ * endpoint yet, we're offline, or the response is unusable, we keep whatever is
+ * already cached (or the built-in BASELINE). This is what keeps the CLI working
+ * against an older server and offline.
+ *
+ * Online commands call this early (before scanning), so discovery, the deploy
+ * manifest, and the run whitelist reflect the latest layout.
+ */
+export async function syncCapabilities() {
+  let raw;
+  try {
+    raw = await fetchCapabilities();
+  } catch {
+    return; // no endpoint / offline / server error → keep cache + baseline
+  }
+
+  const valid = validateDescriptor(raw);
+  if (!valid) return; // unusable descriptor → ignore, don't clobber the cache
+
+  // Version handshake: warn (but still consume what we can) when the server is
+  // ahead of this CLI. The user keeps working on the subset we understand.
+  if (raw.project_schema_version > SUPPORTED_SCHEMA_VERSION) {
+    warn(
+      `This project's layout is newer than your tgcloud (schema v${raw.project_schema_version} ` +
+      `> v${SUPPORTED_SCHEMA_VERSION}); newer directories may be ignored. ` +
+      `Upgrade: npm i -D @tgcloud/cli@latest`
+    );
+  }
+  if (raw.min_cli_version && isOlder(CLI_VERSION, raw.min_cli_version)) {
+    warn(
+      `This project requires tgcloud ≥ ${stripControl(raw.min_cli_version)} (you have ${CLI_VERSION}). ` +
+      `Upgrade: npm i -D @tgcloud/cli@latest`
+    );
+  }
+
+  saveCachedCapabilities(raw);
+  resetLayout();
+}