feat(upgrade): add --offline flag and automatic offline fallback

Add --offline flag to 'sentry cli upgrade' that uses only cached version
info (from background checks) and cached patches (from background
prefetch) — no network calls at all.

When a normal upgrade encounters a network error during version
discovery, automatically falls back to the offline path if cached
data is available, logging a warning about the fallback.

The infrastructure for offline upgrades already existed:
- Background version checks store latest version in SQLite
- Background patch prefetch caches patch chains to disk
- Delta upgrade already checks cache before network

This change wires those pieces together with a new entry point.

Changes:
- Add --offline flag to upgrade command
- Add resolveOfflineTarget() for cached version lookup
- Add resolveTargetWithFallback() for auto network→cache fallback
- Thread offline param through executeUpgrade/downloadBinaryToTemp
  to prevent full-binary download fallback when offline
- Show '(offline, from cache)' in human output for offline upgrades
- Validate --offline is only used with curl-installed binaries

Author: BYK

src/commands/cli/upgrade.ts

@@ -29,6 +29,7 @@ import {
   type ReleaseChannel,
   setReleaseChannel,
 } from "../../lib/db/release-channel.js";
+import { getVersionCheckInfo } from "../../lib/db/version-check.js";
 import { UpgradeError } from "../../lib/errors.js";
 import { formatUpgradeResult } from "../../lib/formatters/human.js";
 import { CommandOutput } from "../../lib/formatters/output.js";
@@ -70,13 +71,16 @@ export type UpgradeResult = {
   method: string;
   /** Whether the user forced the upgrade */
   forced: boolean;
+  /** Whether the upgrade was performed offline (from cache) */
+  offline?: boolean;
   /** Warnings to display (e.g., PATH shadowing from old package manager install) */
   warnings?: string[];
 };
 
 type UpgradeFlags = {
   readonly check: boolean;
   readonly force: boolean;
+  readonly offline: boolean;
   readonly method?: InstallationMethod;
 };
 
@@ -108,6 +112,108 @@ function resolveChannelAndVersion(positional: string | undefined): {
   };
 }
 
+/**
+ * Resolve the target version from the local cache (SQLite) instead of
+ * fetching from the network. Used by `--offline` and as automatic
+ * fallback when `fetchLatestVersion()` hits a network error.
+ *
+ * @param versionArg - Explicit version from the user, bypasses the cache lookup
+ * @returns The target version string
+ * @throws {UpgradeError} When no cached version is available
+ */
+function resolveOfflineTarget(versionArg: string | undefined): string {
+  if (versionArg) {
+    return versionArg.replace(VERSION_PREFIX_REGEX, "");
+  }
+  const { latestVersion } = getVersionCheckInfo();
+  if (!latestVersion) {
+    throw new UpgradeError(
+      "network_error",
+      "No cached version available. Run any command to trigger a background version check, then retry."
+    );
+  }
+  return latestVersion;
+}
+
+/**
+ * Resolve the target version, trying the network first and falling back to
+ * the local cache when offline or when the network is unavailable.
+ *
+ * @returns `{ target, offline }` — the resolved version and whether the
+ *   resolution used the offline path (explicit or automatic fallback).
+ *   Returns `null` when `resolveTargetVersion` returns a "done" result
+ *   (check-only or already up-to-date); the caller should yield that result.
+ */
+async function resolveTargetWithFallback(opts: {
+  resolveOpts: ResolveTargetOptions;
+  versionArg: string | undefined;
+  offline: boolean;
+}): Promise<
+  | { kind: "target"; target: string; offline: boolean }
+  | { kind: "done"; result: UpgradeResult }
+> {
+  const { resolveOpts, versionArg, offline } = opts;
+
+  if (offline) {
+    const target = resolveOfflineTarget(versionArg);
+    log.info(`Offline mode: using cached target ${target}`);
+    return { kind: "target", target, offline: true };
+  }
+
+  try {
+    const resolved = await resolveTargetVersion(resolveOpts);
+    if (resolved.kind === "done") {
+      return resolved;
+    }
+    return { kind: "target", target: resolved.target, offline: false };
+  } catch (error) {
+    // Automatic offline fallback: if the network fails, try the cache
+    if (!(error instanceof UpgradeError && error.reason === "network_error")) {
+      throw error;
+    }
+    try {
+      const target = resolveOfflineTarget(versionArg);
+      log.warn("Network unavailable, falling back to cached upgrade target");
+      log.info(`Using cached target: ${target}`);
+      return { kind: "target", target, offline: true };
+    } catch {
+      // No cached version either — re-throw original network error
+      throw error;
+    }
+  }
+}
+
+/**
+ * Validate the installation method against the requested flags and channel.
+ * Throws on unsupported combinations.
+ */
+function validateMethod(
+  method: InstallationMethod,
+  versionArg: string | undefined,
+  channel: ReleaseChannel,
+  offline: boolean
+): void {
+  if (method === "unknown") {
+    throw new UpgradeError("unknown_method");
+  }
+  // Homebrew manages versioning through the formula — pinning a specific
+  // stable version is not supported via this command.
+  if (method === "brew" && versionArg && channel === "stable") {
+    throw new UpgradeError(
+      "unsupported_operation",
+      "Homebrew does not support installing a specific version. Run 'brew upgrade getsentry/tools/sentry' to upgrade to the latest formula version."
+    );
+  }
+  // Offline mode is only supported for curl-installed binaries — package
+  // managers always need network to fetch and install packages.
+  if (offline && method !== "curl") {
+    throw new UpgradeError(
+      "unsupported_operation",
+      "Offline upgrade is only supported for curl-installed binaries."
+    );
+  }
+}
+
 type ResolveTargetOptions = {
   method: InstallationMethod;
   channel: ReleaseChannel;
@@ -286,15 +392,21 @@ async function executeStandardUpgrade(opts: {
   versionArg: string | undefined;
   target: string;
   execPath: string;
+  offline?: boolean;
 }): Promise<void> {
-  const { method, channel, versionArg, target, execPath } = opts;
+  const { method, channel, versionArg, target, execPath, offline } = opts;
 
   // Use the rolling "nightly" tag only when upgrading to latest nightly
   // (no specific version was requested). A specific version arg always
   // uses its own tag so the correct release is downloaded.
   const downloadTag =
     channel === "nightly" && !versionArg ? NIGHTLY_TAG : undefined;
-  const downloadResult = await executeUpgrade(method, target, downloadTag);
+  const downloadResult = await executeUpgrade(
+    method,
+    target,
+    downloadTag,
+    offline
+  );
 
   // Run setup on the new binary to update completions, agent skills,
   // and record installation metadata.
@@ -398,6 +510,34 @@ async function migrateToStandaloneForNightly(
   return warnings;
 }
 
+/**
+ * Resolve the channel, version arg, method, and channel-changed flag from
+ * the positional version argument and flags. Extracted to keep `func()`
+ * complexity under the biome limit.
+ */
+async function resolveContext(
+  version: string | undefined,
+  flags: UpgradeFlags
+): Promise<{
+  channel: ReleaseChannel;
+  versionArg: string | undefined;
+  channelChanged: boolean;
+  method: InstallationMethod;
+}> {
+  const { channel, versionArg } = resolveChannelAndVersion(version);
+  const currentChannel = getReleaseChannel();
+  const channelChanged = channel !== currentChannel;
+
+  // Persist the channel so version-check and future upgrades respect it.
+  if (channelChanged || CHANNEL_VERSIONS.has(version ?? "")) {
+    setReleaseChannel(channel);
+  }
+
+  const method = flags.method ?? (await detectInstallationMethod());
+  validateMethod(method, versionArg, channel, flags.offline);
+  return { channel, versionArg, channelChanged, method };
+}
+
 export const upgradeCommand = buildCommand({
   docs: {
     brief: "Update the Sentry CLI to the latest version",
@@ -416,7 +556,8 @@ export const upgradeCommand = buildCommand({
       "  sentry cli upgrade 0.5.0        # Install a specific stable version\n" +
       "  sentry cli upgrade --check      # Check for updates without installing\n" +
       "  sentry cli upgrade --force      # Force re-download even if up to date\n" +
-      "  sentry cli upgrade --method npm # Force using npm to upgrade",
+      "  sentry cli upgrade --method npm # Force using npm to upgrade\n" +
+      "  sentry cli upgrade --offline    # Upgrade from cached patches (no network)",
   },
   output: { human: formatUpgradeResult },
   parameters: {
@@ -443,6 +584,12 @@ export const upgradeCommand = buildCommand({
         brief: "Force upgrade even if already on the latest version",
         default: false,
       },
+      offline: {
+        kind: "boolean",
+        brief:
+          "Upgrade using only cached version info and patches (no network)",
+        default: false,
+      },
       method: {
         kind: "parsed",
         parse: parseInstallationMethod,
@@ -453,51 +600,42 @@ export const upgradeCommand = buildCommand({
     },
   },
   async *func(this: SentryContext, flags: UpgradeFlags, version?: string) {
-    // Resolve effective channel and version from positional
-    const { channel, versionArg } = resolveChannelAndVersion(version);
-
-    // Track whether the user is deliberately switching channels
-    const currentChannel = getReleaseChannel();
-    const channelChanged = channel !== currentChannel;
-
-    // Persist the channel so version-check and future upgrades respect it.
-    // We do this upfront — even if the download is skipped (e.g. --check) —
-    // so the preference is always recorded.
-    if (channelChanged || CHANNEL_VERSIONS.has(version ?? "")) {
-      setReleaseChannel(channel);
-    }
-
-    // Resolve installation method (detects or uses user-specified)
-    const method = flags.method ?? (await detectInstallationMethod());
-
-    if (method === "unknown") {
-      throw new UpgradeError("unknown_method");
-    }
-
-    // Homebrew manages versioning through the formula — pinning a specific
-    // stable version is not supported via this command.
-    if (method === "brew" && versionArg && channel === "stable") {
-      throw new UpgradeError(
-        "unsupported_operation",
-        "Homebrew does not support installing a specific version. Run 'brew upgrade getsentry/tools/sentry' to upgrade to the latest formula version."
-      );
-    }
+    const { channel, versionArg, channelChanged, method } =
+      await resolveContext(version, flags);
 
     log.info(`Installation method: ${method}`);
     log.info(`Current version: ${CLI_VERSION}`);
 
-    const resolved = await resolveTargetVersion({
-      method,
-      channel,
+    const resolved = await resolveTargetWithFallback({
+      resolveOpts: { method, channel, versionArg, channelChanged, flags },
       versionArg,
-      channelChanged,
-      flags,
+      offline: flags.offline,
     });
     if (resolved.kind === "done") {
       return yield new CommandOutput(resolved.result);
     }
 
-    const { target } = resolved;
+    const { target, offline } = resolved;
+
+    // --check with offline just reports the cached version
+    if (flags.check) {
+      return yield new CommandOutput(
+        buildCheckResult({ target, versionArg, method, channel, flags })
+      );
+    }
+
+    // Skip if already on target — unless forced or switching channels
+    if (CLI_VERSION === target && !flags.force && !channelChanged) {
+      return yield new CommandOutput({
+        action: "up-to-date",
+        currentVersion: CLI_VERSION,
+        targetVersion: target,
+        channel,
+        method,
+        forced: false,
+        offline: offline || undefined,
+      } satisfies UpgradeResult);
+    }
     const downgrade = isDowngrade(CLI_VERSION, target);
     log.info(`${downgrade ? "Downgrading" : "Upgrading"} to ${target}...`);
 
@@ -528,6 +666,7 @@ export const upgradeCommand = buildCommand({
       versionArg,
       target,
       execPath: this.process.execPath,
+      offline,
     });
 
     yield new CommandOutput({
@@ -537,6 +676,7 @@ export const upgradeCommand = buildCommand({
       channel,
       method,
       forced: flags.force,
+      offline: offline || undefined,
     } satisfies UpgradeResult);
     return;
   },

src/lib/formatters/human.ts

@@ -2036,8 +2036,9 @@ export function formatUpgradeResult(data: UpgradeResult): string {
     case "upgraded":
     case "downgraded": {
       const verb = ACTION_DESCRIPTIONS[data.action];
+      const offlineNote = data.offline ? " (offline, from cache)" : "";
       lines.push(
-        `${colorTag("green", "✓")} ${verb} to ${safeCodeSpan(data.targetVersion)}`
+        `${colorTag("green", "✓")} ${verb} to ${safeCodeSpan(data.targetVersion)}${escapeMarkdownInline(offlineNote)}`
       );
       if (data.currentVersion !== data.targetVersion) {
         lines.push(

src/lib/upgrade.ts

@@ -616,7 +616,8 @@ async function downloadStableToPath(
  */
 export async function downloadBinaryToTemp(
   version: string,
-  downloadTag?: string
+  downloadTag?: string,
+  offline?: boolean
 ): Promise<DownloadResult> {
   const { tempPath, lockPath } = getCurlInstallPaths();
 
@@ -636,6 +637,11 @@ export async function downloadBinaryToTemp(
     if (deltaResult) {
       const kb = (deltaResult.patchBytes / 1024).toFixed(1);
       log.info(`Applied delta patch (${kb} KB downloaded)`);
+    } else if (offline) {
+      throw new UpgradeError(
+        "network_error",
+        `No cached patches available for upgrade to ${version}. Run 'sentry cli upgrade' with network access first.`
+      );
     } else {
       log.debug("Downloading full binary");
       await downloadFullBinary(version, downloadTag, tempPath);
@@ -793,11 +799,12 @@ function executeUpgradePackageManager(
 export async function executeUpgrade(
   method: InstallationMethod,
   version: string,
-  downloadTag?: string
+  downloadTag?: string,
+  offline?: boolean
 ): Promise<DownloadResult | null> {
   switch (method) {
     case "curl":
-      return downloadBinaryToTemp(version, downloadTag);
+      return downloadBinaryToTemp(version, downloadTag, offline);
     case "brew":
       await executeUpgradeHomebrew();
       return null;