@tgcloud/cli 0.1.0

package/src/commands/completion.js

@@ -0,0 +1,298 @@
+import fs from 'fs';
+import path from 'path';
+import {
+  ROOT_FILES,
+  moduleDirs,
+  nestableDirs,
+  runnableDirs,
+  directoryByName,
+} from '../core/project-layout.js';
+
+// Shell completion, cobra/npm-style: a `completion <shell>` command prints a
+// thin shim, and a hidden `__complete <words...>` command computes candidates.
+// The shim, invoked by the shell on <Tab>, calls back into `__complete` so the
+// suggestions are dynamic — real handler update-types, locally present modules,
+// current command/flag set — without the shell knowing anything about tgcloud.
+//
+// Wire format of `__complete`: one candidate per line, then a final directive
+// line `:<bitmask>` (always printed, even with zero candidates). bit 1 (value
+// 4, matching the shim's `& 4`) means "no trailing space" — used when the
+// candidate is a directory prefix the user keeps typing into (e.g. `handlers/`).
+
+const NOSPACE = 4;
+
+// --- candidate sources ------------------------------------------------------
+// All of these are best-effort and never throw: completion must stay silent on
+// a malformed or absent project rather than break the user's shell. We also
+// never hit the network here — `directoryByName` reads the cached descriptor.
+
+function listJs(dir) {
+  try {
+    return fs.readdirSync(dir, { withFileTypes: true })
+      .filter((e) => e.isFile() && e.name.endsWith('.js'))
+      .map((e) => e.name.replace(/\.js$/, ''));
+  } catch {
+    return [];
+  }
+}
+
+// Working-dir module files (relative, with `.js`), tolerant of any fs error and
+// of a flat directory that wrongly contains subdirs (scanFiles() would fatal).
+function moduleFiles() {
+  const out = [];
+  const nestable = nestableDirs();
+  for (const rf of ROOT_FILES) {
+    try { if (fs.existsSync(rf)) out.push(rf); } catch { /* ignore */ }
+  }
+  const walk = (dir, base) => {
+    let entries;
+    try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch { return; }
+    for (const e of entries) {
+      const full = path.join(dir, e.name);
+      if (e.isDirectory()) { if (nestable.has(base)) walk(full, base); }
+      else if (e.isFile() && e.name.endsWith('.js')) out.push(full);
+    }
+  };
+  for (const dir of moduleDirs()) {
+    try { if (fs.existsSync(dir)) walk(dir, dir); } catch { /* ignore */ }
+  }
+  return out.map((f) => f.split(path.sep).join('/'));
+}
+
+// `tgcloud add <target>`: first a directory (`handlers/`, `lib/`), then — for a
+// directory with a closed vocabulary (handlers/ = update types) — the names not
+// already present — the same available-names set `add` lists when given a bare
+// directory (commands/add.js's requireLeaf), from the same source.
+function completeAdd(cur) {
+  if (!cur.includes('/')) {
+    return { items: moduleDirs().map((d) => `${d}/`), nospace: true };
+  }
+  const slash = cur.indexOf('/');
+  const dir = cur.slice(0, slash);
+  const desc = directoryByName(dir);
+  if (!desc || !desc.allowedNames) return { items: [], nospace: false };
+  const existing = new Set(listJs(dir));
+  return {
+    items: desc.allowedNames.filter((n) => !existing.has(n)).map((n) => `${dir}/${n}`),
+    nospace: false,
+  };
+}
+
+// `tgcloud run <module>`: modules that actually exist locally in a runnable
+// directory. With a single runnable dir (v1: handlers/), offer the bare leaf
+// name — what users type; otherwise the full `dir/name` path.
+function completeRun() {
+  const runnable = runnableDirs();
+  const rset = new Set(runnable);
+  const bare = runnable.length === 1;
+  const items = [];
+  for (const rel of moduleFiles()) {
+    const top = rel.split('/')[0];
+    if (!rset.has(top)) continue;
+    const mod = rel.replace(/\.js$/, '');
+    items.push(bare ? mod.slice(top.length + 1) : mod);
+  }
+  return { items: [...new Set(items)], nospace: false };
+}
+
+// Targeted `push`/`reset`/`diff`: the deployable file paths.
+function completeFiles() {
+  return { items: moduleFiles(), nospace: false };
+}
+
+function longFlags(cmd) {
+  return cmd ? cmd.options.map((o) => o.long).filter(Boolean) : [];
+}
+
+// A command's subcommand names (aliases included), minus the hidden __complete.
+function subNames(cmd) {
+  return cmd.commands
+    .filter((c) => c.name() !== '__complete')
+    .flatMap((c) => [c.name(), ...c.aliases()]);
+}
+
+// Walk the already-typed words down the command tree. Returns the deepest
+// matched command (`node`) and the positional words consumed under it (flags,
+// and — best effort — words that match a subcommand, are not positionals).
+// Descending into a subcommand resets the positional count.
+function resolvePath(program, prior) {
+  let node = program;
+  const positionals = [];
+  for (const w of prior) {
+    if (w.startsWith('-')) continue; // a flag (its value, if any, is ignored)
+    const child = node.commands.find(
+      (c) => c.name() === w || (c.aliases && c.aliases().includes(w))
+    );
+    if (child) { node = child; positionals.length = 0; }
+    else positionals.push(w);
+  }
+  return { node, positionals };
+}
+
+// Positional completion for a leaf command (no subcommands of its own).
+function completeLeaf(name, first, cur) {
+  const empty = { items: [], nospace: false };
+  switch (name) {
+    case 'add': return first ? completeAdd(cur) : empty;
+    case 'run': return first ? completeRun() : empty;
+    case 'push': return completeFiles();
+    case 'reset': case 'diff': return first ? completeFiles() : empty;
+    case 'completion': return first ? { items: ['bash', 'zsh', 'fish'], nospace: false } : empty;
+    default: return empty;
+  }
+}
+
+// Core dispatcher: given the words typed after `tgcloud` (last = current partial
+// word, possibly ''), return { items, nospace }. Every item is already filtered
+// to the current prefix.
+function computeCandidates(program, words) {
+  const cur = words.length ? words[words.length - 1] : '';
+  const prior = words.slice(0, -1);
+  const empty = { items: [], nospace: false };
+
+  let result;
+  // `help` is commander's implicit command (not in program.commands): it takes a
+  // command name as its argument. Handle it before the tree walk.
+  if (prior[0] === 'help') {
+    const rest = prior.slice(1).filter((w) => !w.startsWith('-'));
+    result = (rest.length === 0 && !cur.startsWith('-'))
+      ? { items: subNames(program), nospace: false }
+      : empty;
+  } else {
+    const { node, positionals } = resolvePath(program, prior);
+    const atTop = node === program;
+    const first = positionals.length === 0;
+
+    if (cur.startsWith('-')) {
+      // This command's own flags. At the top level also the global flags (+
+      // implicit --help/--version); commander rejects globals after a subcommand.
+      result = atTop
+        ? { items: [...longFlags(program), '--help', '--version'], nospace: false }
+        : { items: [...longFlags(node), '--help'], nospace: false };
+    } else if (node.commands.some((c) => c.name() !== '__complete') && first) {
+      // The command has subcommands and none is chosen yet → offer them.
+      // `help` is a valid top-level target too.
+      const names = subNames(node);
+      if (atTop) names.push('help');
+      result = { items: names, nospace: false };
+    } else {
+      result = completeLeaf(node.name(), first, cur);
+    }
+  }
+
+  const seen = new Set();
+  const items = result.items.filter((it) => {
+    if (typeof it !== 'string' || !it.startsWith(cur) || seen.has(it)) return false;
+    seen.add(it);
+    return true;
+  });
+  return { items, nospace: result.nospace };
+}
+
+// --- shim scripts -----------------------------------------------------------
+// Emitted by `completion <shell>`. Each collects the words up to the cursor,
+// calls `tgcloud __complete -- …`, and feeds the candidates back, honoring the
+// no-space directive. `-- ` guards words that begin with `-` from being parsed
+// as options by the __complete invocation.
+
+const BASH = `# tgcloud bash completion.  Enable with:  eval "$(tgcloud completion bash)"
+_tgcloud_complete() {
+  local out cands directive
+  out="$(tgcloud __complete -- "\${COMP_WORDS[@]:1:COMP_CWORD}" 2>/dev/null)"
+  [ -z "$out" ] && return 0
+  directive="\${out##*$'\\n'}"
+  if [ "$out" = "$directive" ]; then cands=""; else cands="\${out%$'\\n'*}"; fi
+  COMPREPLY=()
+  local line
+  while IFS= read -r line; do [ -n "$line" ] && COMPREPLY+=("$line"); done <<< "$cands"
+  case "$directive" in
+    :*) [ $(( \${directive#:} & ${NOSPACE} )) -ne 0 ] && compopt -o nospace 2>/dev/null ;;
+  esac
+}
+complete -F _tgcloud_complete tgcloud
+`;
+
+const ZSH = `#compdef tgcloud
+# tgcloud zsh completion.  Enable with:  eval "$(tgcloud completion zsh)"
+# or:  tgcloud completion zsh > "\${fpath[1]}/_tgcloud"
+_tgcloud() {
+  local out directive d
+  local -a lines cands
+  out="$(tgcloud __complete -- "\${(@)words[2,CURRENT]}" 2>/dev/null)"
+  [[ -z "$out" ]] && return 0
+  lines=("\${(@f)out}")
+  directive="\${lines[-1]}"
+  cands=("\${(@)lines[1,-2]}")
+  (( \${#cands} )) || return 0
+  # Write -S '' literally: an empty element in an unquoted array expansion is
+  # dropped by zsh, which would make -S swallow the following '--' as its suffix.
+  d="\${directive#:}"
+  if [[ "$d" == <-> ]] && (( (d & ${NOSPACE}) != 0 )); then
+    compadd -S '' -- $cands
+  else
+    compadd -- $cands
+  fi
+}
+if [ "\${funcstack[1]}" = "_tgcloud" ]; then
+  _tgcloud "$@"
+else
+  compdef _tgcloud tgcloud
+fi
+`;
+
+const FISH = `# tgcloud fish completion.  Enable with:
+#   tgcloud completion fish > ~/.config/fish/completions/tgcloud.fish
+function __tgcloud_complete
+  set -l tokens (commandline -opc) (commandline -ct)
+  set -e tokens[1]
+  tgcloud __complete -- $tokens 2>/dev/null | string match -rv '^:'
+end
+complete -c tgcloud -f -a '(__tgcloud_complete)'
+`;
+
+const SHIMS = { bash: BASH, zsh: ZSH, fish: FISH };
+
+const INSTRUCTIONS = `# tgcloud shell completion
+#
+# Run one of these, then restart your shell:
+#
+#   bash:  echo 'eval "$(tgcloud completion bash)"' >> ~/.bashrc
+#          (requires the bash-completion package)
+#   zsh:   echo 'eval "$(tgcloud completion zsh)"'  >> ~/.zshrc
+#          (ensure 'autoload -U compinit && compinit' runs in ~/.zshrc)
+#   fish:  tgcloud completion fish > ~/.config/fish/completions/tgcloud.fish
+#
+# Usage: tgcloud completion <bash|zsh|fish>
+`;
+
+export function registerCompletion(program) {
+  program
+    .command('completion [shell]')
+    .description('Print a shell completion script (bash, zsh, or fish)')
+    .action((shell) => {
+      const s = (shell || '').toLowerCase();
+      if (SHIMS[s]) {
+        process.stdout.write(SHIMS[s]);
+        return;
+      }
+      // No/unknown shell: print human instructions as comments, so an accidental
+      // `eval "$(tgcloud completion)"` is a harmless no-op rather than an error.
+      if (s) process.stdout.write(`# Unknown shell "${s}".\n`);
+      process.stdout.write(INSTRUCTIONS);
+    });
+
+  program
+    .command('__complete [words...]', { hidden: true })
+    .description('Internal: emit shell-completion candidates.')
+    .action((words = [], _opts, cmd) => {
+      let out = '';
+      try {
+        const { items, nospace } = computeCandidates(cmd.parent, words);
+        for (const it of items) out += `${it}\n`;
+        out += `:${nospace ? NOSPACE : 0}\n`;
+      } catch {
+        out = ':0\n';
+      }
+      process.stdout.write(out);
+    });
+}

package/src/commands/deploy.js

@@ -0,0 +1,319 @@
+import fs from 'fs';
+import chalk from 'chalk';
+import { resolveToken, retryOnAuthError } from '../core/credentials.js';
+import { syncCapabilities } from '../core/capabilities.js';
+import { scanFiles, warnStrayFiles } from '../core/scanner.js';
+import { syncedDirs, ROOT_FILES, findDisallowedModules } from '../core/project-layout.js';
+import { localDiff } from '../core/local-diff.js';
+import { batchDeploy, getFiles } from '../api/endpoints.js';
+import { describeServerError } from '../api/client.js';
+import { pathToModule, replaceSnapshot } from '../core/snapshot.js';
+import { loadState, saveState } from '../core/state.js';
+import { formatBriefSummary } from '../core/db-changes.js';
+import { confirm, closePrompts } from '../utils/prompt.js';
+import {
+  done,
+  modified,
+  newFile,
+  deleted,
+  info,
+  fatal,
+} from '../utils/logger.js';
+import { createSpinner } from '../utils/spinner.js';
+
+const SCHEMA_FILE = 'schema.js';
+
+export function registerDeploy(program) {
+  program
+    .command('push [files...]')
+    .description('Deploy changed modules to the cloud (batch). Optional files/dirs narrow what is sent.')
+    .option('--force', 'Skip concurrency check — overwrite whatever is in the cloud')
+    .action(async (targetFiles, options) => {
+      // Refresh the project layout from the server before scanning, so the
+      // manifest reflects any directories the platform has added since release.
+      await syncCapabilities();
+
+      const scanned = scanFiles();
+
+      // Resolve explicit targets (specific files, shell-expanded globs, or a
+      // directory like `handlers/`) to a set of deployable paths. A named target
+      // that isn't deployable — missing, or a stray .js outside a module dir —
+      // is a hard error: you asked for it by name, so we don't silently skip it.
+      let targeted = false;
+      let targetSet = null;
+      if (targetFiles && targetFiles.length) {
+        targeted = true;
+        targetSet = resolveTargets(targetFiles, scanned);
+      } else {
+        // Full deploy: nudge about stray root-level .js (non-blocking).
+        warnStrayFiles();
+      }
+
+      // Reject module names a directory doesn't allow (e.g. handlers/ accepts
+      // only Bot API update types) locally, before the deploy round-trip.
+      const disallowed = findDisallowedModules(scanned);
+      if (disallowed.length) {
+        const d = disallowed[0];
+        fatal(
+          `${d.file}: "${d.name}" is not a valid module name in ${d.dir}/. ` +
+          `Allowed: ${d.allowed.join(', ')}.`
+        );
+      }
+
+      // 1. Compute what changed locally (offline).
+      const diff = localDiff();
+
+      console.log('\nChecking changes...');
+      const changedPaths = []; // modified + newLocal, will be validated and sent
+      const deletedPaths = []; // remoteOnly, will be omitted from manifest
+
+      for (const f of diff.modified) {
+        if (targeted && !targetSet.has(f.path)) continue;
+        modified(f.path);
+        changedPaths.push(f.path);
+      }
+      for (const f of diff.newLocal) {
+        if (targeted && !targetSet.has(f.path)) continue;
+        newFile(f.path);
+        changedPaths.push(f.path);
+      }
+      for (const f of diff.remoteOnly) {
+        if (targeted && !targetSet.has(f.path)) continue;
+        deleted(f.path);
+        deletedPaths.push(f.path);
+      }
+      // Unchanged (matched) files are intentionally not listed — only changes
+      // are worth showing. If everything matched, the no-changes path below fires.
+
+      if (!changedPaths.length && !deletedPaths.length) {
+        info('\nNo changes to deploy.');
+        return;
+      }
+
+      // 2. Build the batch payload.
+      //    Manifest = the complete set of modules that should exist on the
+      //    server after this deploy. Anything on the server not in the manifest
+      //    is implicitly deleted.
+      // Only files in `synced` directories (plus root files) belong to the
+      // deployed module space. Today every directory is synced, so this filter
+      // is a no-op; it honors the descriptor's `synced` flag for future
+      // local-only dirs.
+      const synced = new Set(syncedDirs());
+      const inDeployedSpace = (p) => {
+        if (ROOT_FILES.includes(p)) return true;
+        return synced.has(p.split(/[\\/]/)[0]);
+      };
+
+      // A NEW local-only module (in the working dir, not yet on the server) may
+      // only enter the manifest if we also send its source. A targeted deploy
+      // narrows `changed_sources` to the target, so any untargeted new module
+      // would land in the manifest WITHOUT a source — and the server rejects it
+      // with MODULE_NOT_FOUND (it has no copy to keep). Exclude those. Modules
+      // already on the server (matched/modified) stay regardless of the target,
+      // so a targeted deploy doesn't prune them.
+      const newLocalSet = new Set(diff.newLocal.map((f) => f.path));
+      const manifestPaths = scanned.filter((p) => {
+        if (!inDeployedSpace(p)) return false;
+        if (targeted && newLocalSet.has(p) && !targetSet.has(p)) return false;
+        return true;
+      });
+      // Targeted deploy (`push <file>`) must touch only the requested file: it
+      // must NOT prune modules that exist on the server but are absent from the
+      // working dir. Those `remoteOnly` paths aren't scanned (not on disk), so
+      // we add them back to the manifest to keep the server from deleting them.
+      // A full deploy (no targets) omits them on purpose, which is how
+      // deletions are synced.
+      if (targeted) {
+        for (const f of diff.remoteOnly) {
+          if (inDeployedSpace(f.path)) manifestPaths.push(f.path);
+        }
+      }
+
+      const manifest = manifestPaths.map(pathToModule);
+
+      const changed_sources = {};
+      for (const p of changedPaths) {
+        if (!inDeployedSpace(p)) continue;
+        changed_sources[pathToModule(p)] = fs.readFileSync(p, 'utf-8');
+      }
+
+      const state = loadState();
+      let expected_revision = options.force ? null : state.last_known_revision;
+
+      // Never-synced guard. A null last_known_revision sends
+      // expected_revision:null, which the server treats as force — so a first
+      // push from a freshly-bound project would silently overwrite (and prune)
+      // a bot that already has deployed content, with no conflict prompt. Before
+      // that, check the server: if it already has modules, refuse unless --force.
+      // (`login` normally syncs on bind so this won't fire; it's the safety net
+      // for env-token-only use or a manually cleared snapshot.)
+      if (expected_revision == null && !options.force) {
+        let remote;
+        try {
+          remote = await retryOnAuthError(async () => getFiles(await resolveToken()));
+        } catch (err) {
+          fatal(describeServerError(err));
+        }
+        const remoteCount = Object.keys(remote?.canonical_modules || {}).length;
+        if (remoteCount > 0) {
+          fatal(
+            `This bot already has ${remoteCount} deployed module${remoteCount === 1 ? '' : 's'}` +
+            (remote.revision != null ? ` (revision ${remote.revision})` : '') +
+            `, but this project has never synced with it.\n` +
+            `  Run "tgcloud fetch" to review the difference, then push,\n` +
+            `  or "tgcloud push --force" to overwrite the bot with your local project.`
+          );
+        }
+        // Empty bot: safe to proceed. Adopt its revision so the deploy is a
+        // normal conditional create (409 if content appears before we send).
+        if (remote?.revision != null) expected_revision = remote.revision;
+      }
+
+      if (deletedPaths.length) {
+        const n = deletedPaths.length;
+        const plural = n === 1 ? '' : 's';
+        const isTTY = process.stdout.isTTY || process.env.TGCLOUD_ASSUME_TTY === '1';
+        // A full push prunes server modules that are absent locally (the documented
+        // deletion model). In an interactive terminal, confirm first — a stray cd or
+        // a partial checkout could otherwise wipe modules from a single command.
+        // Targeted pushes never prune (remoteOnly is re-added above); CI (non-TTY)
+        // and --force proceed without a prompt so scripted deploys aren't blocked.
+        if (!targeted && !options.force && isTTY) {
+          const ok = await confirm(
+            `\n${n} module${plural} in the cloud ${n === 1 ? 'is' : 'are'} absent locally and will be DELETED. Continue?`
+          );
+          closePrompts();
+          if (!ok) { info('Cancelled.'); return; }
+        } else {
+          info(`\n${n} module${plural} will be deleted in the cloud (absent locally).`);
+        }
+      }
+
+      // 4. Send the batch (with automatic re-auth on 401/403).
+      const startTime = Date.now();
+      let response;
+      try {
+        response = await retryOnAuthError(async () => {
+          const token = await resolveToken();
+          const spinner = createSpinner(
+            `Deploying ${changedPaths.length} change${changedPaths.length === 1 ? '' : 's'}...`
+          );
+          spinner.start();
+          try {
+            const r = await batchDeploy(token, { expected_revision, manifest, changed_sources });
+            spinner.stop();
+            return r;
+          } catch (err) {
+            spinner.stop();
+            throw err;
+          }
+        });
+      } catch (err) {
+        // A revision mismatch gets its own actionable help block; any other
+        // server failure prints one Error: line (no ora ✖ glyph).
+        if (isRevisionMismatch(err)) {
+          showRevisionMismatchHelp(err);
+        } else {
+          console.error(chalk.red('Error: ') + describeServerError(err));
+        }
+        process.exit(1);
+      }
+
+      for (const p of changedPaths) done(p);
+      for (const p of deletedPaths) done(p, 'deleted');
+
+      // 5. Update local snapshot and state from server's canonical response.
+      if (response?.canonical_modules) {
+        replaceSnapshot(response.canonical_modules);
+      }
+      if (response?.revision != null) {
+        const s = loadState();
+        s.last_known_revision = response.revision;
+        saveState(s);
+      }
+
+      const elapsed = ((Date.now() - startTime) / 1000).toFixed(1);
+      info(`\nDone in ${elapsed}s`);
+
+      // 6. If schema.js was deployed and the server reported pending db_changes,
+      // print them as a heads-up and suggest `tgcloud migrate`. push/deploy
+      // never applies DB migrations itself — that's a separate, explicit command.
+      const schemaDeployed = changedPaths.includes(SCHEMA_FILE);
+      if (schemaDeployed && response?.db_changes?.length) {
+        const n = response.db_changes.length;
+        console.log('');
+        console.log(chalk.bold(`Schema out of sync — ${n} change${n === 1 ? '' : 's'}:`));
+        console.log(formatBriefSummary(response.db_changes));
+        console.log('');
+        info('Run "tgcloud migrate" to apply schema changes to the database.');
+      }
+    });
+}
+
+/**
+ * Turn raw `deploy` targets into a set of deployable module paths. Each target
+ * is either an exact scanned file, or a directory (`handlers/`) expanded to the
+ * scanned files under it. Anything else — a missing path, or a stray .js outside
+ * a module directory — aborts with a per-target reason (you named it explicitly,
+ * so silently dropping it would be wrong).
+ */
+function resolveTargets(rawTargets, scanned) {
+  const scannedSet = new Set(scanned);
+  const targetSet = new Set();
+  const bad = [];
+  for (const raw of rawTargets) {
+    if (scannedSet.has(raw)) {
+      targetSet.add(raw);
+      continue;
+    }
+    // Accept a bare module name without the `.js` extension, so a target reads
+    // the same as `tgcloud run` (run handlers/message ≡ push handlers/message).
+    const withExt = raw.endsWith('.js') ? raw : `${raw}.js`;
+    if (scannedSet.has(withExt)) {
+      targetSet.add(withExt);
+      continue;
+    }
+    const dir = raw.replace(/[\\/]+$/, '');
+    const under = scanned.filter((p) => p.startsWith(dir + '/'));
+    if (under.length) {
+      under.forEach((p) => targetSet.add(p));
+      continue;
+    }
+    bad.push(raw);
+  }
+  if (bad.length) {
+    const w = Math.max(...bad.map((t) => t.length));
+    const lines = bad.map(
+      (t) => `  ${t.padEnd(w)}  — ${fs.existsSync(t) ? 'not in a deployed module directory' : 'not found'}`
+    );
+    fatal(
+      `Cannot deploy:\n${lines.join('\n')}\n` +
+      `Run "tgcloud status" to see deployable files.`
+    );
+  }
+  return targetSet;
+}
+
+function isRevisionMismatch(err) {
+  const p = err.parameters || {};
+  return typeof p.current_revision === 'number' || err.status === 409;
+}
+
+function showRevisionMismatchHelp(err) {
+  const p = err.parameters || {};
+  console.error(chalk.yellow(
+    '\nServer has new revisions since your last sync.'
+  ));
+  if (p.current_revision != null) {
+    console.error(chalk.dim(`  Server revision: ${p.current_revision}`));
+  }
+  if (p.expected_revision != null) {
+    console.error(chalk.dim(`  Your revision:   ${p.expected_revision}`));
+  }
+  console.error(
+    '\nOptions:\n' +
+    '  tgcloud fetch           — pull latest into snapshot, then re-check diff\n' +
+    '  tgcloud pull            — pull latest into both snapshot and working dir\n' +
+    '  tgcloud push --force    — overwrite server state (dangerous)'
+  );
+}

package/src/commands/diff.js

@@ -0,0 +1,57 @@
+import chalk from 'chalk';
+import { localDiff } from '../core/local-diff.js';
+import { computeDiff } from '../core/file-diff.js';
+import { createPager } from '../utils/pager.js';
+
+export function registerDiff(program) {
+  program
+    .command('diff [file]')
+    .description('Show line-by-line diff between working directory and local snapshot (offline)')
+    .action(async (targetFile) => {
+      const diff = localDiff();
+
+      const allChanged = [
+        ...diff.modified.map((f) => ({ ...f, kind: 'modified' })),
+        ...diff.newLocal.map((f) => ({ ...f, kind: 'new', remoteContent: '' })),
+        ...diff.remoteOnly.map((f) => ({ ...f, kind: 'deleted', localContent: '' })),
+      ];
+
+      const filtered = targetFile
+        ? allChanged.filter((f) => f.path === targetFile)
+        : allChanged;
+
+      // Collect patches first so we don't even launch the pager for empty output.
+      const chunks = [];
+      for (const f of filtered) {
+        const patch = computeDiff(f.remoteContent || '', f.localContent || '', f.path);
+        if (patch) chunks.push(formatPatch(patch));
+      }
+
+      if (!chunks.length) {
+        console.log('No changes.');
+        return;
+      }
+
+      const pager = createPager();
+      try {
+        for (const chunk of chunks) {
+          pager.write(chunk);
+          if (!chunk.endsWith('\n')) pager.write('\n');
+        }
+      } finally {
+        await pager.close();
+      }
+    });
+}
+
+function formatPatch(patch) {
+  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');
+}