@tgcloud/cli 0.1.0

package/src/commands/fetch.js

@@ -0,0 +1,23 @@
+import { syncSnapshot } from '../core/sync.js';
+import { info } from '../utils/logger.js';
+
+/**
+ * Download current server state into .tgcloud/remote/ ONLY.
+ * Working directory is not modified.
+ */
+export function registerFetch(program) {
+  program
+    .command('fetch')
+    .description('Update local snapshot from the cloud without touching working directory')
+    .action(async () => {
+      try {
+        const { count, revision } = await syncSnapshot();
+        info(
+          `Snapshot updated — ${count} module${count === 1 ? '' : 's'}` +
+          (revision != null ? ` (revision ${revision})` : '')
+        );
+      } catch {
+        process.exit(1);
+      }
+    });
+}

package/src/commands/init.js

@@ -0,0 +1,226 @@
+import fs from 'fs';
+import path from 'path';
+import chalk from 'chalk';
+import { execSync } from 'child_process';
+import { createHash } from 'crypto';
+import { fileURLToPath } from 'url';
+import { success, info, fatal } from '../utils/logger.js';
+import { loadState, saveState } from '../core/state.js';
+import { findProjectRoot } from '../core/project-root.js';
+import {
+  scaffoldEntries,
+  templates,
+} from '../core/project-layout.js';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const templatesDir = path.join(__dirname, '..', 'templates');
+
+function sha256Hex(buffer) {
+  return 'sha256:' + createHash('sha256').update(buffer).digest('hex');
+}
+
+// Content for a scaffolded file, by its relative path: prefer the server-provided
+// template (from GET /capabilities, keyed by path), else the CLI's bundled copy.
+// Returns null when neither exists — the file is skipped.
+function templateContent(relPath, serverTemplates) {
+  if (serverTemplates[relPath] != null) return serverTemplates[relPath];
+  const bundled = path.join(templatesDir, relPath);
+  return fs.existsSync(bundled) ? fs.readFileSync(bundled, 'utf-8') : null;
+}
+
+// Ensure a valid Node manifest exists — `init` owns the canonical package.json
+// shape (create-bot writes only a frozen `{ name, private }` stub before it can
+// run `npm install`, so the evolving fields live here in the CLI, not there).
+//
+// Additive merge: fill only MISSING top-level keys, never overwrite existing
+// ones — critical for `devDependencies` that `npm install` wrote in the
+// create-bot flow, and for a user's own fields when `init` runs standalone.
+// `scripts` is all-or-nothing: added only when the key is absent entirely (if
+// the user already has scripts, we don't inject into their object). The script
+// bodies are bare `tgcloud …` on purpose: npm puts node_modules/.bin on PATH
+// when running a script, so bare resolves there. Returns 'created' | 'updated' |
+// null (unchanged, or a malformed file we refuse to clobber).
+function ensurePackageJson() {
+  const defaults = {
+    name: path.basename(process.cwd()),
+    version: '0.1.0',
+    private: true,
+    type: 'module',
+  };
+  const existed = fs.existsSync('package.json');
+  let pkg = {};
+  if (existed) {
+    try {
+      pkg = JSON.parse(fs.readFileSync('package.json', 'utf-8'));
+    } catch {
+      return null; // malformed — leave the user's file untouched
+    }
+  }
+  let changed = false;
+  for (const [k, v] of Object.entries(defaults)) {
+    if (!(k in pkg)) { pkg[k] = v; changed = true; }
+  }
+  if (!('scripts' in pkg)) {
+    pkg.scripts = { deploy: 'tgcloud push', status: 'tgcloud status', run: 'tgcloud run' };
+    changed = true;
+  }
+  if (!existed || changed) {
+    fs.writeFileSync('package.json', JSON.stringify(pkg, null, 2) + '\n');
+    return existed ? 'updated' : 'created';
+  }
+  return null;
+}
+
+// Print the created dirs/files as a flat, alphabetical ✓ checklist — same shape
+// as `push`'s deploy list: files by full path, plus any created dir that stayed
+// empty (so an otherwise-invisible starter folder still shows). Dot-entries
+// (.gitignore, .tgcloud/) sort to the top.
+function printCreated(dirs, files) {
+  const emptyDirs = dirs
+    .filter((d) => !files.some((f) => f === d || f.startsWith(d + '/')))
+    .map((d) => `${d}/`);
+  const entries = [...files, ...emptyDirs].sort((a, b) => a.localeCompare(b));
+  for (const e of entries) success(e);
+}
+
+// Best-effort git setup for a freshly scaffolded project.
+//
+// Skip entirely when we're already inside a git work tree (a nested backend/
+// folder): a second `git init` there creates an embedded repo the outer one can
+// only track as a bare gitlink, so the files silently vanish on clone.
+//
+// Otherwise init + stage + commit as ONE all-or-nothing step, so we never leave
+// a half-initialized repo (empty, or inited-but-uncommitted — the odd middle
+// ground). The commit uses the user's own git
+// identity; if that's unset (or git is missing) the commit fails and we roll the
+// just-created .git back rather than leave a repo with no first commit.
+//
+// Prints a single plain-text line (not a ✓ file entry) so git status reads as a
+// note about the repo, not as one of the scaffolded files.
+function setupGit() {
+  try {
+    execSync('git rev-parse --is-inside-work-tree', { stdio: 'ignore' });
+    info('Using the existing git repository.');
+    return;
+  } catch {
+    // not inside a work tree — create a fresh repo below
+  }
+
+  try {
+    execSync('git init', { stdio: 'ignore' });
+  } catch {
+    return; // git not installed — nothing to roll back
+  }
+
+  try {
+    execSync('git add -A', { stdio: 'ignore' });
+    execSync('git commit -m "Initial commit"', { stdio: 'ignore' });
+    info('Initialized a git repository with an initial commit.');
+  } catch {
+    fs.rmSync('.git', { recursive: true, force: true });
+    info('Skipped git — set your git user.name and user.email, then run "git init" yourself.');
+  }
+}
+
+export function registerInit(program) {
+  program
+    .command('init')
+    .description('Initialize a new tgcloud project (local scaffolding only)')
+    .option('--no-git', 'Skip git repository initialization and the initial commit')
+    .action(async (options) => {
+      // Refuse to create a project nested inside another one. Re-running `init`
+      // in the same directory is fine (idempotent scaffolding); only an ancestor
+      // that is already a project is an error — that would shadow the outer one.
+      const existing = findProjectRoot();
+      if (existing && path.resolve(existing) !== path.resolve(process.cwd())) {
+        fatal(
+          `Already inside a tgcloud project at ${existing}.\n` +
+          `Run "tgcloud init" in a separate directory, or cd to that project to work on it.`
+        );
+      }
+
+      // Track the scaffolded project files so we can hash them for init_templates.
+      const scaffoldedFiles = [];
+      // Collect what we create and print it sorted at the end (folders first,
+      // then files, each alphabetical) rather than in descriptor order.
+      const createdDirs = [];
+      const createdFiles = [];
+
+      // Walk the layout's scaffold list (path-driven: server-provided when
+      // available, baseline otherwise). Directories end with "/"; files — which
+      // may be nested paths like docs/guide.md or handlers/message.js — get
+      // their content from the templates map (by path), else the bundled copy.
+      const serverTemplates = templates();
+
+      for (const entry of scaffoldEntries()) {
+        if (entry.endsWith('/')) {
+          const dir = entry.slice(0, -1);
+          if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+          createdDirs.push(dir);
+          continue;
+        }
+        if (fs.existsSync(entry)) continue;
+        const content = templateContent(entry, serverTemplates);
+        if (content == null) continue; // no template for this file — skip
+        const dir = path.dirname(entry);
+        if (dir && dir !== '.') fs.mkdirSync(dir, { recursive: true });
+        fs.writeFileSync(entry, content);
+        createdFiles.push(entry);
+        // Track deployable modules (.js) for init_templates; docs (.md, etc.)
+        // don't deploy, so a change to them isn't a skeleton modification.
+        if (entry.endsWith('.js')) scaffoldedFiles.push(entry);
+      }
+
+      // .gitignore — ensure .tgcloud/ is ignored.
+      const gitignoreContent = fs.readFileSync(path.join(templatesDir, 'gitignore'), 'utf-8');
+      if (fs.existsSync('.gitignore')) {
+        const existing = fs.readFileSync('.gitignore', 'utf-8');
+        const linesToAdd = gitignoreContent.split('\n').filter(
+          (line) => line && !existing.split('\n').includes(line)
+        );
+        if (linesToAdd.length) {
+          const suffix = existing.endsWith('\n') ? '' : '\n';
+          fs.appendFileSync('.gitignore', suffix + linesToAdd.join('\n') + '\n');
+        }
+      } else {
+        fs.writeFileSync('.gitignore', gitignoreContent);
+      }
+      createdFiles.push('.gitignore');
+
+      // package.json — create the canonical manifest, or fill missing fields in
+      // one already written by create-bot (with npm's devDependencies) / the user.
+      if (ensurePackageJson()) createdFiles.push('package.json');
+
+      // Record init_templates in state.json — hashes of the scaffolded files,
+      // used to detect whether the user modified the skeleton before the first deploy.
+      //
+      // On re-run we preserve existing init_templates and only add hashes for
+      // files we actually scaffolded this time. This avoids wiping the marker
+      // if someone runs `init` again in an already-initialized project.
+      const state = loadState();
+      for (const file of scaffoldedFiles) {
+        state.init_templates[file] = sha256Hex(fs.readFileSync(file));
+      }
+      saveState(state);
+      createdFiles.push('.tgcloud/state.json');
+
+      // --- output: intro, then a flat ✓ checklist of what we created ---
+      info('Creating a new tgcloud project...');
+      printCreated(createdDirs, createdFiles);
+
+      // Version control — last, so the initial commit captures the full scaffold.
+      if (options.git) setupGit();
+
+      // "Project ready" + the files note is always init's — it owns the scaffold,
+      // so the description stays here (generic, no hardcoded names, survives new
+      // directories the platform may add). Only the numbered "Next steps" is suppressed
+      // when a bootstrap (create-bot) delegates and sets TGCLOUD_INIT_QUIET_NEXT:
+      // it prints its own, leading with `cd` and using npx.
+      info('\nProject ready. The scaffolded files are a starting point — edit or delete as you like.');
+      if (!process.env.TGCLOUD_INIT_QUIET_NEXT) {
+        info('\nNext steps:');
+        info(`  ${chalk.cyan('tgcloud login')}   ${chalk.dim('# link this project to a bot')}`);
+        info(`  ${chalk.cyan('tgcloud push')}    ${chalk.dim('# deploy to the cloud')}`);
+      }
+    });
+}

package/src/commands/login.js

@@ -0,0 +1,56 @@
+import { loginInteractive } from '../core/credentials.js';
+import { syncSnapshot } from '../core/sync.js';
+import { closePrompts } from '../utils/prompt.js';
+import { info, warn, fatal } from '../utils/logger.js';
+
+/**
+ * Explicit, interactive authentication. The only command that prompts for a
+ * token; every other command reads it from .tgcloud/credentials or TGCLOUD_TOKEN
+ * and errors if absent (see core/credentials.js → resolveToken).
+ */
+export function registerLogin(program) {
+  program
+    .command('login')
+    .description('Link this project to a bot by saving its token (interactive)')
+    .action(async () => {
+      // Requires a real terminal — refuse in scripts/CI rather than hang on a
+      // hidden prompt. TGCLOUD_ASSUME_TTY=1 overrides the check for non-TTY stdio.
+      const tty = process.stdout.isTTY || process.env.TGCLOUD_ASSUME_TTY === '1';
+      if (!tty) {
+        fatal('"tgcloud login" requires an interactive terminal.\n  For CI, set the TGCLOUD_TOKEN environment variable instead.');
+      }
+
+      if (process.env.TGCLOUD_TOKEN) {
+        warn('TGCLOUD_TOKEN is set and takes priority; the saved token is used only when it is unset.');
+      }
+
+      // closePrompts() releases the shared stdin reader (used by askPassword's
+      // non-interactive path) so the process can exit. A null result means no
+      // token was provided (e.g. closed stdin) — exit non-zero so scripts don't
+      // mistake a no-op for a successful link.
+      let token;
+      try {
+        token = await loginInteractive();
+      } finally {
+        closePrompts();
+      }
+      if (!token) process.exit(1);
+
+      // Sync the snapshot on bind: this records the bot's current
+      // revision + modules, so a subsequent first `push` conflict-checks against
+      // the bot's real state instead of silently force-overwriting it (a null
+      // last_known_revision is treated as force by the server). The working dir
+      // is untouched, so any local files stay and `status` shows the diff.
+      // Best-effort: a failed or offline sync must not fail the login itself.
+      try {
+        const { count, revision } = await syncSnapshot({ spinnerText: 'Syncing bot state...' });
+        info(
+          `Synced — ${count} module${count === 1 ? '' : 's'} on the bot` +
+          (revision != null ? ` (revision ${revision})` : '') +
+          (count > 0 ? '. Run "tgcloud status" to compare with your local files.' : '.')
+        );
+      } catch {
+        // Token is saved; the next online command will sync. Don't block login.
+      }
+    });
+}

package/src/commands/migrate.js

@@ -0,0 +1,142 @@
+import fs from 'fs';
+import chalk from 'chalk';
+import { resolveToken, retryOnAuthError } from '../core/credentials.js';
+import { getMigrationStatus, applyMigration, describeServerError } from '../api/endpoints.js';
+import { runMigrationFlow } from '../core/migration-flow.js';
+import { closePrompts } from '../utils/prompt.js';
+import { createSpinner } from '../utils/spinner.js';
+import { fatal } from '../utils/logger.js';
+import { ROOT_FILE } from '../core/project-layout.js';
+import { readSnapshotFile } from '../core/snapshot.js';
+
+/**
+ * Compare local schema file with the snapshot (= last-deployed version).
+ * Returns a short label describing the discrepancy, or null if they match.
+ */
+function localSchemaDivergence() {
+  const localExists = fs.existsSync(ROOT_FILE);
+  const remoteContent = readSnapshotFile(ROOT_FILE);
+
+  if (!localExists && remoteContent == null) return null;
+  if (!localExists && remoteContent != null) return 'deleted_locally';
+  if (localExists && remoteContent == null) return 'new_locally';
+
+  const localContent = fs.readFileSync(ROOT_FILE, 'utf-8');
+  return localContent === remoteContent ? null : 'modified_locally';
+}
+
+function printSchemaDivergenceWarning(kind) {
+  const base = '\n' + chalk.yellow('Warning: ') + `Your local ${ROOT_FILE} differs from what's deployed.`;
+  const detail =
+    `  The pending changes below are the diff between the DEPLOYED schema and the DB —\n` +
+    `  they do NOT include your local edits. Run "tgcloud push" first if you want\n` +
+    `  those edits to be part of this migration, or use "--local" to diff against\n` +
+    `  your local schema instead.`;
+  console.log(base);
+  console.log(detail);
+
+  if (kind === 'new_locally') {
+    console.log(`  (Note: ${ROOT_FILE} is new locally — never deployed.)`);
+  } else if (kind === 'deleted_locally') {
+    console.log(`  (Note: ${ROOT_FILE} was deleted locally but still exists in the cloud.)`);
+  }
+  console.log('');
+}
+
+export function registerMigrate(program) {
+  program
+    .command('migrate')
+    .description('Apply pending database schema changes')
+    .option('--yes', 'Apply all safe + all warning changes without prompting (for CI)')
+    .option('--safe', 'Apply only safe changes, skip warning and manual')
+    .option('--local', `Compute diff against your local ${ROOT_FILE} instead of the deployed version`)
+    .option('--dry-run', 'Show pending changes without applying anything')
+    .action(async (options) => {
+      if (options.yes && options.safe) {
+        fatal('--yes and --safe are mutually exclusive.');
+      }
+      if (options.dryRun && (options.yes || options.safe)) {
+        fatal('--dry-run cannot be combined with --yes/--safe (nothing to apply in dry-run mode).');
+      }
+
+      // Non-interactive session + no explicit mode → ambiguous, bail out.
+      // TGCLOUD_ASSUME_TTY=1 overrides the check, treating piped stdio as interactive.
+      const tty = process.stdout.isTTY || process.env.TGCLOUD_ASSUME_TTY === '1';
+      if (!tty && !options.dryRun && !options.safe && !options.yes) {
+        fatal('non-interactive session — specify --safe, --yes, or --dry-run.');
+      }
+
+      // Load local schema if --local is requested.
+      let localSchema = null;
+      if (options.local) {
+        if (!fs.existsSync(ROOT_FILE)) {
+          fatal(`--local requires a local ${ROOT_FILE}, none found.`);
+        }
+        localSchema = fs.readFileSync(ROOT_FILE, 'utf-8');
+      }
+
+      let migrateFailed = false;
+      try {
+        await retryOnAuthError(async () => {
+          const token = await resolveToken();
+
+          const spinner = createSpinner('Checking schema...');
+          spinner.start();
+
+          let status;
+          try {
+            if (localSchema != null) {
+              status = await applyMigration(token, { schema: localSchema, dry_run: true });
+            } else {
+              status = await getMigrationStatus(token);
+            }
+            spinner.stop();
+          } catch (err) {
+            spinner.stop();
+            console.error(chalk.red('Error: ') + describeServerError(err));
+            throw err;
+          }
+
+          const dbChanges = status?.db_changes || [];
+
+          if (options.local) {
+            console.log(chalk.dim(`(diff computed against your local ${ROOT_FILE})`));
+          }
+
+          if (!dbChanges.length) {
+            const target = options.local
+              ? `your local ${ROOT_FILE}`
+              : `the deployed ${ROOT_FILE}`;
+            console.log(`No schema changes. Database is in sync with ${target}.`);
+            if (!options.local) {
+              const divergence = localSchemaDivergence();
+              if (divergence) printSchemaDivergenceWarning(divergence);
+            }
+            return;
+          }
+
+          if (!options.local) {
+            const divergence = localSchemaDivergence();
+            if (divergence) printSchemaDivergenceWarning(divergence);
+          }
+
+          const result = await runMigrationFlow(token, dbChanges, {
+            yes: options.yes,
+            safe: options.safe,
+            dryRun: options.dryRun,
+            schema: localSchema,
+          });
+          if (result?.failed > 0) migrateFailed = true;
+        });
+      } catch {
+        process.exit(1);
+      } finally {
+        closePrompts();
+      }
+
+      // Some changes were attempted but rejected by the server — surface a
+      // non-zero exit so CI/scripts can detect a failed migration. Manual/undoc
+      // changes (never applied by design) and user-skipped changes do NOT count.
+      if (migrateFailed) process.exit(1);
+    });
+}

package/src/commands/pull.js

@@ -0,0 +1,156 @@
+import fs from 'fs';
+import path from 'path';
+import chalk from 'chalk';
+import { resolveToken, retryOnAuthError } from '../core/credentials.js';
+import { syncCapabilities } from '../core/capabilities.js';
+import { getFiles, describeServerError } from '../api/endpoints.js';
+import { replaceSnapshot, moduleToPath, listSnapshotPaths } from '../core/snapshot.js';
+import { loadState, saveState } from '../core/state.js';
+import { computeDiff } from '../core/file-diff.js';
+import { done, skipped, info } from '../utils/logger.js';
+import { confirm, closePrompts } from '../utils/prompt.js';
+import { createSpinner } from '../utils/spinner.js';
+
+/**
+ * Download full server state into working directory AND local snapshot.
+ * After a successful pull, working dir, snapshot, and server are all aligned.
+ *
+ * Throws on network/auth errors — caller decides how to handle.
+ */
+export async function executePull(options = {}) {
+  // Refresh the layout first: a project may contain directories this CLI build
+  // doesn't know about natively. Without this, those files would be written to
+  // the working dir but then ignored by the scanner (and dropped on next deploy).
+  await syncCapabilities();
+  const token = await resolveToken();
+
+  const spinner = createSpinner('Pulling files from the cloud...');
+  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 || {};
+  const moduleNames = Object.keys(canonical);
+  const serverPaths = new Set(moduleNames.map(moduleToPath));
+
+  // Orphans: files previously synced from the server (present in the snapshot)
+  // that the server no longer has, and that still exist in the working dir.
+  // Without removing these, `pull` would leave the working dir out of sync with
+  // the server — the orphan shows up as a "new" file that the next deploy
+  // resurrects. New local files the user created (never synced,
+  // so not in the snapshot) are NOT in this set and are left untouched.
+  // Computed before replaceSnapshot(), which prunes the snapshot.
+  const orphans = listSnapshotPaths().filter(
+    (p) => !serverPaths.has(p) && fs.existsSync(p)
+  );
+
+  if (!moduleNames.length && !orphans.length) {
+    info('No files in the cloud.');
+    replaceSnapshot(canonical);
+    if (response.revision != null) {
+      const s = loadState();
+      s.last_known_revision = response.revision;
+      saveState(s);
+    }
+    return;
+  }
+
+  let pulled = 0;
+
+  for (const moduleName of moduleNames) {
+    const filePath = moduleToPath(moduleName);
+    const remoteContent = canonical[moduleName];
+    const dir = path.dirname(filePath);
+
+    if (dir !== '.' && !fs.existsSync(dir)) {
+      fs.mkdirSync(dir, { recursive: true });
+    }
+
+    if (fs.existsSync(filePath)) {
+      const localContent = fs.readFileSync(filePath, 'utf-8');
+
+      if (localContent === remoteContent) {
+        done(filePath, 'up to date');
+        continue;
+      }
+
+      if (!options.force) {
+        console.log(formatPatch(computeDiff(localContent, remoteContent, filePath)));
+        const overwrite = await confirm(`  Overwrite ${filePath}?`);
+        if (!overwrite) {
+          skipped(filePath, 'skipped');
+          continue;
+        }
+      }
+    }
+
+    fs.writeFileSync(filePath, remoteContent);
+    done(filePath, 'saved');
+    pulled++;
+  }
+
+  // Remove orphans (modules deleted on the server). Confirmed per-file unless
+  // --force, mirroring the overwrite confirmation above.
+  let removed = 0;
+  for (const filePath of orphans) {
+    if (!options.force) {
+      console.log('  ' + chalk.dim('delete →') + ` ${filePath}` + chalk.dim(' (removed in the cloud)'));
+      const ok = await confirm(`  Delete ${filePath}?`);
+      if (!ok) {
+        skipped(filePath, 'kept');
+        continue;
+      }
+    }
+    fs.unlinkSync(filePath);
+    done(filePath, 'deleted');
+    removed++;
+  }
+
+  replaceSnapshot(canonical);
+
+  if (response.revision != null) {
+    const s = loadState();
+    s.last_known_revision = response.revision;
+    saveState(s);
+  }
+
+  const removedNote = removed ? `, deleted ${removed}` : '';
+  info(`\nDone. Pulled ${pulled} file${pulled !== 1 ? 's' : ''}${removedNote}.`);
+}
+
+function formatPatch(patch) {
+  if (!patch) return '';
+  return patch
+    .split('\n')
+    .map((line) => {
+      if (line.startsWith('+') && !line.startsWith('+++')) return chalk.green(line);
+      if (line.startsWith('-') && !line.startsWith('---')) return chalk.red(line);
+      if (line.startsWith('@@')) return chalk.cyan(line);
+      return line;
+    })
+    .join('\n');
+}
+
+export function registerPull(program) {
+  program
+    .command('pull')
+    .description('Download cloud state into working directory and local snapshot')
+    .option('--force', 'Overwrite local files without confirmation')
+    .action(async (options) => {
+      try {
+        await retryOnAuthError(() => executePull(options));
+      } catch {
+        process.exit(1);
+      } finally {
+        closePrompts();
+      }
+    });
+}