feat(upgrade): show changelog summary during CLI upgrade

Show inline changelog summaries when running `sentry cli upgrade`. When
upgrading across multiple versions, displays a flat summary of new features,
bug fixes, and performance improvements from all intermediate releases.

- Parse GitHub Release bodies via `marked.lexer()` AST for stable channel
- Parse conventional commit messages via GitHub Commits API for nightly
- Fetch runs in parallel with binary download (zero added latency)
- Filter to features/fixes/performance only (skip docs, internal changes)
- Clamp output to ~1.3x terminal height to keep it scannable
- Works with --check mode (preview what you would get)
- Graceful degradation: offline, rate-limited, or network errors → no changelog

Closes #421

Author: BYK

AGENTS.md

@@ -899,6 +899,9 @@ mock.module("./some-module", () => ({
 <!-- lore:019d0b69-1430-74f0-8e9a-426a5c7b321d -->
 * **Bun compiled binary sourcemap options and size impact**: Binary build (\`script/build.ts\`) uses two steps: (1) \`Bun.build()\` produces \`dist-bin/bin.js\` + \`.map\` with \`sourcemap: "linked"\` and minification. (2) \`Bun.build()\` with \`compile: true\` produces native binary — no sourcemap embedded. Bun's compiled binaries use \`/$bunfs/root/bin.js\` as the virtual path in stack traces. Sourcemap upload must use \`--url-prefix '/$bunfs/root/'\` so Sentry can match frames. The upload runs \`sentry-cli sourcemaps inject dist-bin/\` first (adds debug IDs), then uploads both JS and map. Bun's compile step strips comments (including \`//# debugId=\`), but debug ID matching still works via the injected runtime snippet + URL prefix matching. Size: +0.04 MB gzipped vs +2.30 MB for inline sourcemaps. Without \`SENTRY\_AUTH\_TOKEN\`, upload is skipped gracefully.
 
+<!-- lore:019cbeba-e4d3-748c-ad50-fe3c3d5c0a0d -->
+* **Auth token env var override pattern: SENTRY\_AUTH\_TOKEN > SENTRY\_TOKEN > SQLite**: Auth in \`src/lib/db/auth.ts\` follows layered precedence: \`SENTRY\_AUTH\_TOKEN\` > \`SENTRY\_TOKEN\` > SQLite OAuth token. \`getEnvToken()\` trims env vars (empty/whitespace = unset). \`AuthSource\` tracks provenance. \`ENV\_SOURCE\_PREFIX = "env:"\` — use \`.length\` not hardcoded 4. Env tokens bypass refresh/expiry. \`isEnvTokenActive()\` guards auth commands. Logout must NOT clear stored auth when env token active. These functions stay in \`db/auth.ts\` despite not touching DB because they're tightly coupled with token retrieval.
+
 <!-- lore:019cb8ea-c6f0-75d8-bda7-e32b4e217f92 -->
 * **CLI telemetry DSN is public write-only — safe to embed in install script**: The CLI's Sentry DSN (\`SENTRY\_CLI\_DSN\` in \`src/lib/constants.ts\`) is a public write-only ingest key already baked into every binary. Safe to hardcode in install scripts. Opt-out: \`SENTRY\_CLI\_NO\_TELEMETRY=1\`.
 

src/commands/cli/upgrade.ts

@@ -35,6 +35,10 @@ import { formatUpgradeResult } from "../../lib/formatters/human.js";
 import { CommandOutput } from "../../lib/formatters/output.js";
 import { logger } from "../../lib/logger.js";
 import { withProgress } from "../../lib/polling.js";
+import {
+  type ChangelogSummary,
+  fetchChangelog,
+} from "../../lib/release-notes.js";
 import {
   detectInstallationMethod,
   executeUpgrade,
@@ -76,6 +80,8 @@ export type UpgradeResult = {
   offline?: boolean;
   /** Warnings to display (e.g., PATH shadowing from old package manager install) */
   warnings?: string[];
+  /** Changelog summary for the version range. Absent for offline or on fetch failure. */
+  changelog?: ChangelogSummary;
 };
 
 type UpgradeFlags = {
@@ -592,6 +598,50 @@ function persistChannel(
   }
 }
 
+/**
+ * Start a best-effort changelog fetch in parallel with the binary download.
+ *
+ * Returns a promise that resolves to the changelog or undefined. Never
+ * throws — errors are swallowed so the upgrade is not blocked.
+ */
+function startChangelogFetch(
+  channel: ReleaseChannel,
+  currentVersion: string,
+  targetVersion: string,
+  offline: boolean
+): Promise<ChangelogSummary | undefined> {
+  if (offline || currentVersion === targetVersion) {
+    return Promise.resolve(undefined);
+  }
+  return fetchChangelog({
+    channel,
+    fromVersion: currentVersion,
+    toVersion: targetVersion,
+  })
+    .then((result) => result ?? undefined)
+    .catch(() => undefined as undefined);
+}
+
+/**
+ * Build a check-only result with optional changelog, ready to yield.
+ */
+async function buildCheckResultWithChangelog(opts: {
+  target: string;
+  versionArg: string | undefined;
+  method: InstallationMethod;
+  channel: ReleaseChannel;
+  flags: UpgradeFlags;
+  offline: boolean;
+  changelogPromise: Promise<ChangelogSummary | undefined>;
+}): Promise<UpgradeResult> {
+  const result = buildCheckResult(opts);
+  if (opts.offline) {
+    result.offline = true;
+  }
+  result.changelog = await opts.changelogPromise;
+  return result;
+}
+
 export const upgradeCommand = buildCommand({
   docs: {
     brief: "Update the Sentry CLI to the latest version",
@@ -672,25 +722,48 @@ export const upgradeCommand = buildCommand({
             persistChannel(channel, channelChanged, version),
         })
     );
+    // Early exit for check-only (online) and up-to-date results.
     if (resolved.kind === "done") {
-      return yield new CommandOutput(resolved.result);
+      const result = resolved.result;
+      // For --check with a version diff, fetch changelog before returning.
+      if (
+        result.action === "checked" &&
+        result.currentVersion !== result.targetVersion
+      ) {
+        result.changelog = await startChangelogFetch(
+          channel,
+          CLI_VERSION,
+          result.targetVersion,
+          false
+        );
+      }
+      return yield new CommandOutput(result);
     }
 
     const { target, offline } = resolved;
 
-    // --check with offline just reports the cached version
+    // Start changelog fetch early — it runs in parallel with the download.
+    const changelogPromise = startChangelogFetch(
+      channel,
+      CLI_VERSION,
+      target,
+      offline
+    );
+
+    // --check with offline fallback: resolveTargetWithFallback returns
+    // kind: "target" for offline check, so guard against actual upgrade.
     if (flags.check) {
-      const checkResult = buildCheckResult({
-        target,
-        versionArg,
-        method,
-        channel,
-        flags,
-      });
-      if (offline) {
-        checkResult.offline = true;
-      }
-      return yield new CommandOutput(checkResult);
+      return yield new CommandOutput(
+        await buildCheckResultWithChangelog({
+          target,
+          versionArg,
+          method,
+          channel,
+          flags,
+          offline,
+          changelogPromise,
+        })
+      );
     }
 
     // Skip if already on target — unless forced or switching channels
@@ -708,38 +781,30 @@ export const upgradeCommand = buildCommand({
     const downgrade = isDowngrade(CLI_VERSION, target);
     log.debug(`${downgrade ? "Downgrading" : "Upgrading"} to ${target}`);
 
-    // Nightly is GitHub-only. If the current install method is not curl,
-    // migrate to a standalone binary first then return — the migration
-    // handles setup internally.
+    // Perform the actual upgrade
+    let warnings: string[] | undefined;
     if (channel === "nightly" && method !== "curl") {
-      const warnings = await migrateToStandaloneForNightly(
+      // Nightly is GitHub-only. If the current install method is not curl,
+      // migrate to a standalone binary — the migration handles setup internally.
+      warnings = await migrateToStandaloneForNightly(
         method,
         target,
         versionArg,
         flags.json
       );
-      yield new CommandOutput({
-        action: downgrade ? "downgraded" : "upgraded",
-        currentVersion: CLI_VERSION,
-        targetVersion: target,
-        channel,
+    } else {
+      await executeStandardUpgrade({
         method,
-        forced: flags.force,
-        warnings,
-      } satisfies UpgradeResult);
-      return;
+        channel,
+        versionArg,
+        target,
+        execPath: this.process.execPath,
+        offline,
+        json: flags.json,
+      });
     }
 
-    await executeStandardUpgrade({
-      method,
-      channel,
-      versionArg,
-      target,
-      execPath: this.process.execPath,
-      offline,
-      json: flags.json,
-    });
-
+    const changelog = await changelogPromise;
     yield new CommandOutput({
       action: downgrade ? "downgraded" : "upgraded",
       currentVersion: CLI_VERSION,
@@ -748,6 +813,8 @@ export const upgradeCommand = buildCommand({
       method,
       forced: flags.force,
       offline: offline || undefined,
+      warnings,
+      changelog,
     } satisfies UpgradeResult);
     return;
   },

src/lib/delta-upgrade.ts

@@ -146,6 +146,8 @@ export type GitHubAsset = {
 export type GitHubRelease = {
   tag_name: string;
   assets: GitHubAsset[];
+  /** Markdown release notes body. May be empty or absent for pre-releases. */
+  body?: string;
 };
 
 /**

src/lib/formatters/human.ts

@@ -2080,6 +2080,101 @@ export function formatFixResult(data: FixResult): string {
 /** Structured upgrade result (imported from the command module) */
 type UpgradeResult = import("../../commands/cli/upgrade.js").UpgradeResult;
 
+/** Category → markdown heading for changelog sections */
+type ChangeCategory = import("../release-notes.js").ChangeCategory;
+
+/** Heading text for each changelog category */
+const CATEGORY_HEADINGS: Record<ChangeCategory, string> = {
+  features: "#### New Features ✨",
+  fixes: "#### Bug Fixes 🐛",
+  performance: "#### Performance ⚡",
+};
+
+/**
+ * Max terminal height multiplier for changelog clamping.
+ *
+ * When the total rendered changelog would exceed this fraction of the
+ * terminal height, items are truncated to keep output scannable.
+ */
+const CHANGELOG_HEIGHT_FACTOR = 1.3;
+
+/** Lines consumed by the upgrade status header/metadata above the changelog */
+const CHANGELOG_HEADER_OVERHEAD = 6;
+
+/** Minimum number of changelog items to show even on tiny terminals */
+const MIN_CHANGELOG_ITEMS = 5;
+
+/** Default max items for non-TTY output (no terminal height available) */
+const DEFAULT_MAX_CHANGELOG_ITEMS = 30;
+
+/**
+ * Compute the maximum number of changelog lines based on terminal height.
+ *
+ * Uses ~1.3x the terminal height minus header overhead. Returns a generous
+ * default for non-TTY output where terminal height is unknown.
+ */
+function getMaxChangelogLines(): number {
+  // process.stdout.rows is allowed in formatters (not in command files)
+  const termHeight = process.stdout.rows;
+  if (!termHeight) {
+    return DEFAULT_MAX_CHANGELOG_ITEMS;
+  }
+  return Math.max(
+    MIN_CHANGELOG_ITEMS,
+    Math.floor(termHeight * CHANGELOG_HEIGHT_FACTOR) - CHANGELOG_HEADER_OVERHEAD
+  );
+}
+
+/**
+ * Format the changelog section as markdown for rendering.
+ *
+ * Re-serializes the filtered section markdown with category headings so
+ * that `renderMarkdown()` applies consistent heading/list styling.
+ * Clamps the rendered output to fit ~1.3x the terminal height.
+ *
+ * @param data - Upgrade result with changelog
+ * @returns Rendered changelog string, or empty string if no changelog
+ */
+function formatChangelog(data: UpgradeResult): string {
+  if (!data.changelog || data.changelog.sections.length === 0) {
+    return "";
+  }
+
+  const { changelog } = data;
+  const lines: string[] = ["", "### What's new", ""];
+
+  for (const section of changelog.sections) {
+    lines.push(CATEGORY_HEADINGS[section.category]);
+    lines.push(section.markdown);
+  }
+
+  if (changelog.truncated) {
+    const more = changelog.originalCount - changelog.totalItems;
+    lines.push(
+      `<muted>...and ${more} more changes — https://github.com/getsentry/cli/releases</muted>`
+    );
+  }
+
+  // Render through the markdown pipeline, then clamp to terminal height
+  const rendered = renderMarkdown(lines.join("\n"));
+  const renderedLines = rendered.split("\n");
+  const maxLines = getMaxChangelogLines();
+
+  if (renderedLines.length <= maxLines) {
+    return rendered;
+  }
+
+  // Truncate and add a "more" indicator
+  const clamped = renderedLines.slice(0, maxLines);
+  const remaining = changelog.originalCount - changelog.totalItems;
+  const moreText =
+    remaining > 0
+      ? "...and more — https://github.com/getsentry/cli/releases"
+      : "...truncated — https://github.com/getsentry/cli/releases";
+  clamped.push(isPlainOutput() ? moreText : muted(moreText));
+  return clamped.join("\n");
+}
+
 /** Action descriptions for human-readable output */
 const ACTION_DESCRIPTIONS: Record<UpgradeResult["action"], string> = {
   upgraded: "Upgraded",
@@ -2159,7 +2254,15 @@ export function formatUpgradeResult(data: UpgradeResult): string {
     }
   }
 
-  return renderMarkdown(lines.join("\n"));
+  const result = renderMarkdown(lines.join("\n"));
+
+  // Append changelog if available
+  const changelogOutput = formatChangelog(data);
+  if (changelogOutput) {
+    return `${result}\n${changelogOutput}`;
+  }
+
+  return result;
 }
 
 // Dashboard formatters