refactor(cli/upgrade): migrate to CommandOutput with markdown rendering

Convert cli/upgrade final-result messages to structured UpgradeResult
data returned via CommandOutput, while keeping transient progress
messages as log.info to stderr.

Changes:
- Define UpgradeResult type with action, versions, channel, method, and
  warnings fields
- resolveTargetVersion returns discriminated union ResolveResult instead
  of string|null, enabling early-return paths to carry structured data
- migrateToStandaloneForNightly returns warnings[] instead of logging
- formatUpgradeResult() human formatter with ✓/⚠ markers and exhaustive
  action switch
- All code paths return { data: UpgradeResult }
- --json and --fields flags now supported automatically

Author: BYK

src/commands/cli/upgrade.ts

@@ -30,6 +30,7 @@ import {
   setReleaseChannel,
 } from "../../lib/db/release-channel.js";
 import { UpgradeError } from "../../lib/errors.js";
+import { formatUpgradeResult } from "../../lib/formatters/human.js";
 import { logger } from "../../lib/logger.js";
 import {
   detectInstallationMethod,
@@ -48,6 +49,30 @@ const log = logger.withTag("cli.upgrade");
 /** Special version strings that select a channel rather than a specific release. */
 const CHANNEL_VERSIONS = new Set(["nightly", "stable"]);
 
+/**
+ * Structured result of the upgrade command.
+ *
+ * Returned as `{ data: UpgradeResult }` and rendered via the output config.
+ * In JSON mode the object is serialized as-is; in human mode it's passed to
+ * {@link formatUpgradeResult}.
+ */
+export type UpgradeResult = {
+  /** What action was taken */
+  action: "upgraded" | "downgraded" | "up-to-date" | "checked" | "channel-only";
+  /** Current CLI version before upgrade */
+  currentVersion: string;
+  /** Target version (the version we upgraded/downgraded to, or the latest available) */
+  targetVersion: string;
+  /** Release channel */
+  channel: "stable" | "nightly";
+  /** Installation method used */
+  method: string;
+  /** Whether the user forced the upgrade */
+  forced: boolean;
+  /** Warnings to display (e.g., PATH shadowing from old package manager install) */
+  warnings?: string[];
+};
+
 type UpgradeFlags = {
   readonly check: boolean;
   readonly force: boolean;
@@ -90,15 +115,26 @@ type ResolveTargetOptions = {
   flags: UpgradeFlags;
 };
 
+/**
+ * Result of resolving the target version.
+ *
+ * - `target`: the version string to upgrade/downgrade to (proceed with upgrade)
+ * - `UpgradeResult`: structured result when no upgrade should proceed
+ *   (check-only mode, already up to date, or channel-only switch)
+ */
+type ResolveResult =
+  | { kind: "target"; target: string }
+  | { kind: "done"; result: UpgradeResult };
+
 /**
  * Resolve the target version and handle check-only mode.
  *
- * @returns The target version string, or null if no upgrade should proceed
- *          (check-only mode, already up to date without --force, or channel unchanged).
+ * @returns A `ResolveResult` indicating whether to proceed with the upgrade
+ *   or return a completed result immediately.
  */
 async function resolveTargetVersion(
   opts: ResolveTargetOptions
-): Promise<string | null> {
+): Promise<ResolveResult> {
   const { method, channel, versionArg, channelChanged, flags } = opts;
   const latest = await fetchLatestVersion(method, channel);
   const target = versionArg?.replace(VERSION_PREFIX_REGEX, "") ?? latest;
@@ -110,13 +146,25 @@ async function resolveTargetVersion(
   }
 
   if (flags.check) {
-    return handleCheckMode(target, versionArg);
+    return {
+      kind: "done",
+      result: buildCheckResult({ target, versionArg, method, channel, flags }),
+    };
   }
 
   // Skip if already on target — unless forced or switching channels
   if (CLI_VERSION === target && !flags.force && !channelChanged) {
-    log.success("Already up to date.");
-    return null;
+    return {
+      kind: "done",
+      result: {
+        action: "up-to-date",
+        currentVersion: CLI_VERSION,
+        targetVersion: target,
+        channel,
+        method,
+        forced: false,
+      },
+    };
   }
 
   // Validate that a specific pinned version actually exists.
@@ -133,23 +181,39 @@ async function resolveTargetVersion(
     }
   }
 
-  return target;
+  return { kind: "target", target };
 }
 
 /**
- * Print check-only output and return null (no upgrade to perform).
+ * Build the structured result for check-only mode.
  */
-function handleCheckMode(target: string, versionArg: string | undefined): null {
-  if (CLI_VERSION === target) {
-    log.success("You are already on the target version.");
-  } else {
+function buildCheckResult(opts: {
+  target: string;
+  versionArg: string | undefined;
+  method: InstallationMethod;
+  channel: ReleaseChannel;
+  flags: UpgradeFlags;
+}): UpgradeResult {
+  const { target, versionArg, method, channel, flags } = opts;
+  const result: UpgradeResult = {
+    action: "checked",
+    currentVersion: CLI_VERSION,
+    targetVersion: target,
+    channel,
+    method,
+    forced: flags.force,
+  };
+
+  // When already on target, no update hint needed
+  if (CLI_VERSION !== target) {
     const cmd =
       versionArg && !CHANNEL_VERSIONS.has(versionArg)
         ? `sentry cli upgrade ${target}`
         : "sentry cli upgrade";
-    log.info(`Run '${cmd}' to update.`);
+    result.warnings = [`Run '${cmd}' to update.`];
   }
-  return null;
+
+  return result;
 }
 
 /**
@@ -272,17 +336,18 @@ async function executeStandardUpgrade(opts: {
  *   1. Download the nightly binary to a temp path
  *   2. Install it to `determineInstallDir()` (same logic as the curl installer)
  *   3. Run setup on the new binary to update completions, PATH, and metadata
- *   4. Warn about the old package-manager installation that may still be in PATH
+ *   4. Return warnings about the old package-manager installation that may still be in PATH
  *
  * @param versionArg - Specific version requested by the user, or undefined for
  *   latest nightly. When a specific version is given, its release tag is used
  *   instead of the rolling "nightly" tag so the correct binary is downloaded.
+ * @returns Warnings about the old installation that may shadow the new one
  */
 async function migrateToStandaloneForNightly(
   method: InstallationMethod,
   target: string,
   versionArg: string | undefined
-): Promise<void> {
+): Promise<string[]> {
   log.info("Nightly builds are only available as standalone binaries.");
   log.info("Migrating to standalone installation...");
 
@@ -311,7 +376,7 @@ async function migrateToStandaloneForNightly(
     releaseLock(downloadResult.lockPath);
   }
 
-  // Warn about the potentially shadowing old installation
+  // Build warnings about the potentially shadowing old installation.
   // Note: install info is already recorded by the child `setup --install`
   // process, so no redundant setInstallInfo call is needed here.
   const uninstallHints: Record<string, string> = {
@@ -321,11 +386,15 @@ async function migrateToStandaloneForNightly(
     yarn: "yarn global remove sentry",
     brew: "brew uninstall getsentry/tools/sentry",
   };
+  const warnings: string[] = [];
+  warnings.push(
+    `Your ${method}-installed sentry may still appear earlier in PATH.`
+  );
   const hint = uninstallHints[method];
-  log.warn(`Your ${method}-installed sentry may still appear earlier in PATH.`);
   if (hint) {
-    log.warn(`Consider removing it: ${hint}`);
+    warnings.push(`Consider removing it: ${hint}`);
   }
+  return warnings;
 }
 
 export const upgradeCommand = buildCommand({
@@ -348,6 +417,7 @@ export const upgradeCommand = buildCommand({
       "  sentry cli upgrade --force      # Force re-download even if up to date\n" +
       "  sentry cli upgrade --method npm # Force using npm to upgrade",
   },
+  output: { json: true, human: formatUpgradeResult },
   parameters: {
     positional: {
       kind: "tuple",
@@ -381,11 +451,7 @@ export const upgradeCommand = buildCommand({
       },
     },
   },
-  async func(
-    this: SentryContext,
-    flags: UpgradeFlags,
-    version?: string
-  ): Promise<void> {
+  async func(this: SentryContext, flags: UpgradeFlags, version?: string) {
     // Resolve effective channel and version from positional
     const { channel, versionArg } = resolveChannelAndVersion(version);
 
@@ -419,27 +485,41 @@ export const upgradeCommand = buildCommand({
     log.info(`Installation method: ${method}`);
     log.info(`Current version: ${CLI_VERSION}`);
 
-    const target = await resolveTargetVersion({
+    const resolved = await resolveTargetVersion({
       method,
       channel,
       versionArg,
       channelChanged,
       flags,
     });
-    if (!target) {
-      return;
+    if (resolved.kind === "done") {
+      return { data: resolved.result };
     }
 
+    const { target } = resolved;
     const downgrade = isDowngrade(CLI_VERSION, target);
     log.info(`${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.
     if (channel === "nightly" && method !== "curl") {
-      await migrateToStandaloneForNightly(method, target, versionArg);
-      log.success(`Successfully installed nightly ${target}.`);
-      return;
+      const warnings = await migrateToStandaloneForNightly(
+        method,
+        target,
+        versionArg
+      );
+      return {
+        data: {
+          action: downgrade ? "downgraded" : "upgraded",
+          currentVersion: CLI_VERSION,
+          targetVersion: target,
+          channel,
+          method,
+          forced: flags.force,
+          warnings,
+        } satisfies UpgradeResult,
+      };
     }
 
     await executeStandardUpgrade({
@@ -450,8 +530,15 @@ export const upgradeCommand = buildCommand({
       execPath: this.process.execPath,
     });
 
-    log.success(
-      `Successfully ${downgrade ? "downgraded" : "upgraded"} to ${target}.`
-    );
+    return {
+      data: {
+        action: downgrade ? "downgraded" : "upgraded",
+        currentVersion: CLI_VERSION,
+        targetVersion: target,
+        channel,
+        method,
+        forced: flags.force,
+      } satisfies UpgradeResult,
+    };
   },
 });

src/lib/formatters/human.ts

@@ -2003,3 +2003,87 @@ export function formatFixResult(data: FixResult): string {
 
   return renderMarkdown(lines.join("\n"));
 }
+
+// CLI Upgrade Formatting
+
+/** Structured upgrade result (imported from the command module) */
+type UpgradeResult = import("../../commands/cli/upgrade.js").UpgradeResult;
+
+/** Action descriptions for human-readable output */
+const ACTION_DESCRIPTIONS: Record<UpgradeResult["action"], string> = {
+  upgraded: "Upgraded",
+  downgraded: "Downgraded",
+  "up-to-date": "Already up to date",
+  checked: "Update check complete",
+  "channel-only": "Channel updated",
+};
+
+/**
+ * Format upgrade result as rendered markdown.
+ *
+ * Produces a concise summary line with the action taken, version info,
+ * and any warnings (e.g., PATH shadowing from old package manager install).
+ * Designed as the `human` formatter for the `cli upgrade` command's
+ * {@link OutputConfig}.
+ *
+ * @param data - Structured upgrade result collected by the command
+ * @returns Rendered terminal string
+ */
+export function formatUpgradeResult(data: UpgradeResult): string {
+  const lines: string[] = [];
+
+  switch (data.action) {
+    case "upgraded":
+    case "downgraded": {
+      const verb = ACTION_DESCRIPTIONS[data.action];
+      lines.push(
+        `${colorTag("green", "✓")} ${verb} to ${safeCodeSpan(data.targetVersion)}`
+      );
+      if (data.currentVersion !== data.targetVersion) {
+        lines.push(
+          `${escapeMarkdownInline(data.currentVersion)} → ${escapeMarkdownInline(data.targetVersion)}`
+        );
+      }
+      break;
+    }
+    case "up-to-date":
+      lines.push(
+        `${colorTag("green", "✓")} Already up to date (${safeCodeSpan(data.currentVersion)})`
+      );
+      break;
+    case "checked": {
+      if (data.currentVersion === data.targetVersion) {
+        lines.push(
+          `${colorTag("green", "✓")} You are already on the target version (${safeCodeSpan(data.currentVersion)})`
+        );
+      } else {
+        lines.push(
+          `Latest: ${safeCodeSpan(data.targetVersion)} (current: ${safeCodeSpan(data.currentVersion)})`
+        );
+      }
+      break;
+    }
+    case "channel-only":
+      lines.push(
+        `${colorTag("green", "✓")} Channel set to ${escapeMarkdownInline(data.channel)}`
+      );
+      break;
+    default: {
+      // Exhaustive check — all action types should be handled above
+      const _: never = data.action;
+      lines.push(
+        `${ACTION_DESCRIPTIONS[_ as UpgradeResult["action"]] ?? "Done"}`
+      );
+    }
+  }
+
+  // Append warnings with ⚠ markers
+  if (data.warnings && data.warnings.length > 0) {
+    lines.push("");
+    for (const warning of data.warnings) {
+      lines.push(`${colorTag("yellow", "⚠")} ${escapeMarkdownInline(warning)}`);
+    }
+  }
+
+  return renderMarkdown(lines.join("\n"));
+}