fix(upgrade): detect downgrades and skip delta attempt (#358)

## Problem

Two UX issues when running `sentry cli upgrade <older-version>`:

### 1. Wrong messaging for downgrades

```
$ sentry cli upgrade 0.14.0-dev.1772724107
Current version: 0.14.0-dev.1772732047
Upgrading to 0.14.0-dev.1772724107...    ← wrong: this is a downgrade
Successfully upgraded to 0.14.0-dev.1772724107.  ← wrong
```

### 2. Delta attempt wastes 22+ seconds on downgrades

bsdiff patches are one-directional (old→new only), so a downgrade can
never use deltas. But the code still:
1. Fetches a GHCR token (~100ms)
2. Fetches the target manifest (~100ms-30s due to GHCR cold-start
variance)
3. Builds the ENTIRE patch graph by fetching ALL `patch-*` tag manifests
(~1.5s-22s)
4. Only then discovers no forward path exists and falls back to full
download

From [Sentry
traces](https://sentry.sentry.io/explore/traces/trace/7f6f857d216cd614e2c73257b9eacdef):
a downgrade attempt spent **22.3 seconds** in `build-patch-graph` before
returning `result=unavailable`.

## Fix

### New helpers in `binary.ts`

- `compareVersions(a, b)` — wraps `Bun.semver.order()`, works for both
stable (`X.Y.Z`) and nightly (`X.Y.Z-dev.<unix-seconds>`) formats
- `isDowngrade(current, target)` — returns `true` when the target is
older

### Messaging (`upgrade.ts`)

Now says "Downgrading to" / "Successfully downgraded to" when the target
version is older.

### Delta skip (`delta-upgrade.ts`)

`canAttemptDelta()` returns `false` immediately for downgrades, avoiding
all GHCR calls entirely.

## After

```
$ sentry cli upgrade 0.14.0-dev.1772724107
Current version: 0.14.0-dev.1772732047
Downgrading to 0.14.0-dev.1772724107...
Downloading full binary
Successfully downgraded to 0.14.0-dev.1772724107.
```

## Testing

- `bun run typecheck` ✅
- `bun run lint` ✅
- `bun test test/lib/binary.test.ts` ✅ (40 pass — 12 new tests for
compareVersions/isDowngrade)
- `bun test test/lib/delta-upgrade.test.ts` ✅ (69 pass)

Author: BYK

src/commands/cli/upgrade.ts

@@ -17,7 +17,11 @@
 import { homedir } from "node:os";
 import { dirname } from "node:path";
 import type { SentryContext } from "../../context.js";
-import { determineInstallDir, releaseLock } from "../../lib/binary.js";
+import {
+  determineInstallDir,
+  isDowngrade,
+  releaseLock,
+} from "../../lib/binary.js";
 import { buildCommand } from "../../lib/command.js";
 import { CLI_VERSION } from "../../lib/constants.js";
 import {
@@ -209,6 +213,58 @@ async function runSetupOnNewBinary(opts: SetupOptions): Promise<void> {
   }
 }
 
+/**
+ * Execute the standard upgrade path: download via curl or package manager,
+ * then run setup on the new binary.
+ */
+async function executeStandardUpgrade(opts: {
+  method: InstallationMethod;
+  channel: ReleaseChannel;
+  versionArg: string | undefined;
+  target: string;
+  execPath: string;
+}): Promise<void> {
+  const { method, channel, versionArg, target, execPath } = 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);
+
+  // Run setup on the new binary to update completions, agent skills,
+  // and record installation metadata.
+  if (downloadResult) {
+    // Curl: new binary is at temp path, setup --install will place it.
+    // Pin the install directory via SENTRY_INSTALL_DIR so the child's
+    // determineInstallDir() doesn't relocate to a different directory.
+    // Release the download lock after the child exits — if the child used
+    // the same lock path (ppid takeover), this is a harmless no-op.
+    const currentInstallDir = dirname(getCurlInstallPaths().installPath);
+    try {
+      await runSetupOnNewBinary({
+        binaryPath: downloadResult.tempBinaryPath,
+        method,
+        channel,
+        install: true,
+        installDir: currentInstallDir,
+      });
+    } finally {
+      releaseLock(downloadResult.lockPath);
+    }
+  } else if (method !== "brew") {
+    // Package manager: binary already in place, just run setup.
+    // Skip brew — Homebrew's post_install hook already runs setup.
+    await runSetupOnNewBinary({
+      binaryPath: execPath,
+      method,
+      channel,
+      install: false,
+    });
+  }
+}
+
 /**
  * Migrate from a package-manager or Homebrew install to a standalone binary
  * when the user switches to the nightly channel.
@@ -382,7 +438,10 @@ export const upgradeCommand = buildCommand({
       return;
     }
 
-    stdout.write(`\nUpgrading to ${target}...\n`);
+    const downgrade = isDowngrade(CLI_VERSION, target);
+    stdout.write(
+      `\n${downgrade ? "Downgrading" : "Upgrading"} to ${target}...\n`
+    );
 
     // Nightly is GitHub-only. If the current install method is not curl,
     // migrate to a standalone binary first then return — the migration
@@ -393,45 +452,16 @@ export const upgradeCommand = buildCommand({
       return;
     }
 
-    // Standard upgrade path: download (curl) or package manager.
-    // 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);
-
-    // Run setup on the new binary to update completions, agent skills,
-    // and record installation metadata.
-    if (downloadResult) {
-      // Curl: new binary is at temp path, setup --install will place it.
-      // Pin the install directory via SENTRY_INSTALL_DIR so the child's
-      // determineInstallDir() doesn't relocate to a different directory.
-      // Release the download lock after the child exits — if the child used
-      // the same lock path (ppid takeover), this is a harmless no-op.
-      const currentInstallDir = dirname(getCurlInstallPaths().installPath);
-      try {
-        await runSetupOnNewBinary({
-          binaryPath: downloadResult.tempBinaryPath,
-          method,
-          channel,
-          install: true,
-          installDir: currentInstallDir,
-        });
-      } finally {
-        releaseLock(downloadResult.lockPath);
-      }
-    } else if (method !== "brew") {
-      // Package manager: binary already in place, just run setup.
-      // Skip brew — Homebrew's post_install hook already runs setup.
-      await runSetupOnNewBinary({
-        binaryPath: this.process.execPath,
-        method,
-        channel,
-        install: false,
-      });
-    }
+    await executeStandardUpgrade({
+      method,
+      channel,
+      versionArg,
+      target,
+      execPath: this.process.execPath,
+    });
 
-    stdout.write(`\nSuccessfully upgraded to ${target}.\n`);
+    stdout.write(
+      `\nSuccessfully ${downgrade ? "downgraded" : "upgraded"} to ${target}.\n`
+    );
   },
 });

src/lib/binary.ts

@@ -67,6 +67,28 @@ export function isNightlyVersion(version: string): boolean {
   return version.includes("-dev.");
 }
 
+/**
+ * Compare two version strings and return their ordering.
+ *
+ * Uses `Bun.semver.order` which handles both stable (`X.Y.Z`) and
+ * nightly (`X.Y.Z-dev.<unix-seconds>`) versions correctly — the numeric
+ * pre-release identifier is compared numerically per SemVer spec.
+ *
+ * @returns 1 if a > b, -1 if a < b, 0 if equal
+ */
+export function compareVersions(a: string, b: string): -1 | 0 | 1 {
+  return Bun.semver.order(a, b);
+}
+
+/**
+ * Check whether moving from `current` to `target` is a downgrade.
+ *
+ * @returns true if target is older than current
+ */
+export function isDowngrade(current: string, target: string): boolean {
+  return compareVersions(current, target) === 1;
+}
+
 /**
  * Get the binary filename for the current platform.
  *

src/lib/delta-upgrade.ts

@@ -25,6 +25,7 @@ import * as Sentry from "@sentry/bun";
 import {
   GITHUB_RELEASES_URL,
   getPlatformBinaryName,
+  isDowngrade,
   isNightlyVersion,
 } from "./binary.js";
 import { applyPatch } from "./bspatch.js";
@@ -108,6 +109,11 @@ export function canAttemptDelta(targetVersion: string): boolean {
     return false;
   }
 
+  // Downgrades have no forward patch path — skip immediately
+  if (isDowngrade(CLI_VERSION, targetVersion)) {
+    return false;
+  }
+
   return true;
 }
 

test/lib/binary.test.ts

@@ -16,12 +16,14 @@ import {
 import { join } from "node:path";
 import {
   acquireLock,
+  compareVersions,
   determineInstallDir,
   fetchWithUpgradeError,
   getBinaryDownloadUrl,
   getBinaryFilename,
   getBinaryPaths,
   installBinary,
+  isDowngrade,
   releaseLock,
   replaceBinarySync,
 } from "../../src/lib/binary.js";
@@ -459,3 +461,65 @@ describe("acquireLock", () => {
     releaseLock(lockPath);
   });
 });
+
+describe("compareVersions", () => {
+  test("stable: newer > older", () => {
+    expect(compareVersions("0.15.0", "0.14.0")).toBe(1);
+  });
+
+  test("stable: older < newer", () => {
+    expect(compareVersions("0.14.0", "0.15.0")).toBe(-1);
+  });
+
+  test("stable: equal", () => {
+    expect(compareVersions("0.14.0", "0.14.0")).toBe(0);
+  });
+
+  test("nightly: later timestamp > earlier timestamp", () => {
+    expect(
+      compareVersions("0.14.0-dev.1772732047", "0.14.0-dev.1772724107")
+    ).toBe(1);
+  });
+
+  test("nightly: earlier timestamp < later timestamp", () => {
+    expect(
+      compareVersions("0.14.0-dev.1772724107", "0.14.0-dev.1772732047")
+    ).toBe(-1);
+  });
+
+  test("nightly: equal", () => {
+    expect(
+      compareVersions("0.14.0-dev.1772724107", "0.14.0-dev.1772724107")
+    ).toBe(0);
+  });
+
+  test("stable > nightly with same base (semver: release > pre-release)", () => {
+    expect(compareVersions("0.14.0", "0.14.0-dev.1772732047")).toBe(1);
+  });
+});
+
+describe("isDowngrade", () => {
+  test("returns true when target is older stable version", () => {
+    expect(isDowngrade("0.15.0", "0.14.0")).toBe(true);
+  });
+
+  test("returns false when target is newer stable version", () => {
+    expect(isDowngrade("0.14.0", "0.15.0")).toBe(false);
+  });
+
+  test("returns false when versions are equal", () => {
+    expect(isDowngrade("0.14.0", "0.14.0")).toBe(false);
+  });
+
+  test("returns true when target is older nightly (earlier timestamp)", () => {
+    expect(isDowngrade("0.14.0-dev.1772732047", "0.14.0-dev.1772724107")).toBe(
+      true
+    );
+  });
+
+  test("returns false when target is newer nightly (later timestamp)", () => {
+    expect(isDowngrade("0.14.0-dev.1772724107", "0.14.0-dev.1772732047")).toBe(
+      false
+    );
+  });
+});