@flowscripter/dynamic-cli-framework 7.0.11 → 7.1.0

package/dist/src/service/upgrade/UpgradeServiceProvider.js

@@ -26,7 +26,7 @@ export function createUpgradeCheckStartupTask(upgradeService, priority) {
 }
 /**
  * Build the blocking {@link StartupTask} which offers to enable automatic upgrades and, when they
- * are enabled, checks for and installs a newer version (see
+ * are enabled, checks for and installs a newer version, optionally restarting into it (see
  * {@link UpgradeServiceProvider.runAutoUpgrade}). It is registered separately from the provider's
  * own init task so it can run at a lower priority, after consumer startup tasks such as the banner.
  */
@@ -45,9 +45,25 @@ export default class UpgradeServiceProvider {
     #upgradeService;
     #cliConfig;
     #keyValueService;
-    constructor(servicePriority, config) {
+    #restartAfterAutoUpgrade;
+    #restartArgs = [];
+    /**
+     * @param servicePriority the priority of the service.
+     * @param config the upgrade locations.
+     * @param restartAfterAutoUpgrade whether to run the upgraded executable, with the arguments from
+     * {@link setRestartArgs}, after a successful automatic upgrade and end the run with its result.
+     */
+    constructor(servicePriority, config, restartAfterAutoUpgrade = false) {
         this.servicePriority = servicePriority;
         this.#config = config;
+        this.#restartAfterAutoUpgrade = restartAfterAutoUpgrade;
+    }
+    /**
+     * Set the CLI arguments to run the upgraded executable with when restarting after an automatic
+     * upgrade. These are kept internal to the framework and never exposed to startup tasks.
+     */
+    setRestartArgs(args) {
+        this.#restartArgs = args;
     }
     get upgradeService() {
         return this.#upgradeService;
@@ -87,12 +103,20 @@ export default class UpgradeServiceProvider {
      * service's scope) and, when they are enabled, check for and install a newer version. Must be
      * called after {@link initService}.
      *
+     * After a successful upgrade, when restarting is enabled, the upgraded executable is run with the
+     * arguments from {@link setRestartArgs} and its result is returned as an `exitRequest`. Does
+     * nothing in a process which was itself started by such a restart.
+     *
      * @param context the startup task's context, used to look up the Prompter and Printer services.
      */
     async runAutoUpgrade(context) {
         const upgradeService = this.#upgradeService;
         const cliConfig = this.#cliConfig;
         const keyValueService = this.#keyValueService;
+        if (upgradeService.restartedFromVersion !== undefined) {
+            logger.debug(() => `Restarted from version ${upgradeService.restartedFromVersion}, skipping auto-upgrade`);
+            return;
+        }
         if (!context.doesServiceExist(PROMPTER_SERVICE_ID)) {
             logger.debug(() => "PrompterService not available, skipping auto-upgrade");
             return;
@@ -108,8 +132,7 @@ export default class UpgradeServiceProvider {
                 return;
             }
             if (status === "enabled") {
-                await this.#checkAndUpgrade(context, upgradeService, cliConfig);
-                return;
+                return this.#checkAndUpgrade(context, upgradeService, cliConfig, keyValueService);
             }
         }
         const prompterService = context.getServiceById(PROMPTER_SERVICE_ID);
@@ -150,9 +173,9 @@ export default class UpgradeServiceProvider {
             return;
         }
         await keyValueService.set("upgrade-status", "enabled");
-        await this.#checkAndUpgrade(context, upgradeService, cliConfig);
+        return this.#checkAndUpgrade(context, upgradeService, cliConfig, keyValueService);
     }
-    async #checkAndUpgrade(context, upgradeService, cliConfig) {
+    async #checkAndUpgrade(context, upgradeService, cliConfig, keyValueService) {
         try {
             const checkResult = await upgradeService.getUpgradeCheckResult();
             if (checkResult.status === "failed") {
@@ -163,16 +186,32 @@ export default class UpgradeServiceProvider {
                 return;
             }
             const upgradeResult = await upgradeService.upgrade();
-            if (!context.doesServiceExist(PRINTER_SERVICE_ID)) {
+            const printerService = context.doesServiceExist(PRINTER_SERVICE_ID)
+                ? context.getServiceById(PRINTER_SERVICE_ID)
+                : undefined;
+            if (!upgradeResult.ok) {
+                await printerService?.error(`Auto-upgrade failed: ${upgradeResult.error?.message ?? "unknown error"}\n`, Icon.FAILURE);
+                return;
+            }
+            await printerService?.info(`${cliConfig.name} upgraded (${upgradeResult.oldVersion} -> ${upgradeResult.newVersion})\n`, Icon.SUCCESS);
+            if (!this.#restartAfterAutoUpgrade) {
                 return;
             }
-            const printerService = context.getServiceById(PRINTER_SERVICE_ID);
-            if (upgradeResult.ok) {
-                await printerService.info(`${cliConfig.name} upgraded (${upgradeResult.oldVersion} -> ${upgradeResult.newVersion})\n`, Icon.SUCCESS);
+            const executable = upgradeService.resolveUpgradedExecutable(checkResult.installMethod);
+            if (executable === undefined) {
+                await printerService?.info(`Restart ${cliConfig.name} to use ${upgradeResult.newVersion}\n`, Icon.INFORMATION);
+                return;
             }
-            else {
-                await printerService.error(`Auto-upgrade failed: ${upgradeResult.error?.message ?? "unknown error"}\n`, Icon.FAILURE);
+            // the cache write from the background upgrade check lands before the flush, so the shutdown
+            // flush has nothing left to write over the restarted process's configuration
+            await upgradeService.refreshUpgradeCheckCache();
+            // written now so the restarted process sees the stored upgrade-status
+            await keyValueService.flush();
+            const runState = await upgradeService.restart(executable, this.#restartArgs);
+            if (runState !== undefined) {
+                return { exitRequest: { runState } };
             }
+            await printerService?.warn(`${cliConfig.name} upgraded to ${upgradeResult.newVersion}; restart it to use the new version\n`, Icon.ALERT);
         }
         catch (error) {
             logger.debug(() => `Auto-upgrade check failed: ${error}`);

package/dist/src/startup/banner/bannerStartupTask.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"bannerStartupTask.d.ts","sourceRoot":"","sources":["../../../../src/startup/banner/bannerStartupTask.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAA2B,WAAW,EAAE,MAAM,yCAAyC,CAAC;AAYpG,eAAO,MAAM,sBAAsB,4DAA4D,CAAC;AAEhG;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,OAAO,UAAU,uBAAuB,CAC7C,QAAQ,EAAE,MAAM,EAChB,QAAQ,SAAa,GACpB,WAAW,CA+Db"}
+{"version":3,"file":"bannerStartupTask.d.ts","sourceRoot":"","sources":["../../../../src/startup/banner/bannerStartupTask.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAA2B,WAAW,EAAE,MAAM,yCAAyC,CAAC;AAYpG,eAAO,MAAM,sBAAsB,4DAA4D,CAAC;AAEhG;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,OAAO,UAAU,uBAAuB,CAC7C,QAAQ,EAAE,MAAM,EAChB,QAAQ,SAAa,GACpB,WAAW,CAqEb"}

package/dist/src/startup/banner/bannerStartupTask.js

@@ -1,5 +1,4 @@
 import { ASCII_BANNER_GENERATOR_SERVICE_ID, CONFIGURATION_SERVICE_ID, PRINTER_SERVICE_ID, UPGRADE_SERVICE_ID, } from "@flowscripter/dynamic-cli-framework-api";
-import DefaultUpgradeService from "../../service/upgrade/DefaultUpgradeService.js";
 import NoBannerCommand, {} from "./command/NoBannerCommand.js";
 export const BANNER_STARTUP_TASK_ID = "@flowscripter/dynamic-cli-framework/banner-startup-task";
 /**
@@ -26,6 +25,14 @@ export default function createBannerStartupTask(priority, fontName = "standard")
             if (!state.printBanner) {
                 return;
             }
+            const upgradeService = context.doesServiceExist(UPGRADE_SERVICE_ID)
+                ? context.getServiceById(UPGRADE_SERVICE_ID)
+                : undefined;
+            // a process restarted after an automatic upgrade follows the banner already printed by the
+            // process which restarted it
+            if (upgradeService?.restartedFromVersion !== undefined) {
+                return;
+            }
             const printerService = context.getServiceById(PRINTER_SERVICE_ID);
             const asciiBannerGeneratorService = context.getServiceById(ASCII_BANNER_GENERATOR_SERVICE_ID);
             const { cliConfig } = context;
@@ -44,10 +51,7 @@ export default function createBannerStartupTask(priority, fontName = "standard")
                 // result yet) shows no upgrade-available suffix. The cached result is read through the
                 // upgrade service because it is stored in that service's own KeyValueService scope, and
                 // it is ignored if it was recorded by a different version (e.g. before an upgrade).
-                const upgradeService = context.doesServiceExist(UPGRADE_SERVICE_ID)
-                    ? context.getServiceById(UPGRADE_SERVICE_ID)
-                    : undefined;
-                if (upgradeService instanceof DefaultUpgradeService) {
+                if (upgradeService) {
                     const result = await upgradeService.getCachedUpgradeCheckResult();
                     if (result?.status === "checked" &&
                         result.updateAvailable &&

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flowscripter/dynamic-cli-framework",
-  "version": "7.0.11",
+  "version": "7.1.0",
   "description": "A framework for developing CLI applications which supports dynamic discovery and installation of new commands",
   "keywords": [
     "bun",
@@ -48,7 +48,7 @@
     "build": "tsc -p tsconfig.build.json"
   },
   "dependencies": {
-    "@flowscripter/dynamic-cli-framework-api": "^4.0.6",
+    "@flowscripter/dynamic-cli-framework-api": "^4.1.0",
     "@flowscripter/dynamic-plugin-framework": "^2.2.14",
     "emphasize": "^7.0.0",
     "fastest-levenshtein": "^1.0.16",

package/src/cli/BaseCLI.ts

@@ -171,6 +171,7 @@ export default class BaseCLI implements CLI {
       fetchServiceEnabled: false,
       upgradeServiceEnabled: false,
       upgradeLocationsConfig: { supportedPlatforms: [] },
+      restartAfterAutoUpgrade: false,
       pluginServiceEnabled: false,
       pluginServiceRemoteConfig: { name: "", registryUrl: "", packageJsonNamespace: "" },
       pluginServiceLocalConfig: { nodeModulesPath: "", packageJsonNamespace: "" },
@@ -356,7 +357,9 @@ export default class BaseCLI implements CLI {
       upgradeServiceProvider = new UpgradeServiceProvider(
         UPGRADE_SERVICE_PRIORITY,
         this.#options.upgradeLocationsConfig,
+        this.#options.restartAfterAutoUpgrade,
       );
+      upgradeServiceProvider.setRestartArgs(args);
       this.addServiceProvider(upgradeServiceProvider);
     }
 
@@ -474,6 +477,10 @@ export default class BaseCLI implements CLI {
         defaultCommand,
         this.#startupServiceProvider.startupService,
       );
+      // a startup task ended the run, having already handled its outcome itself
+      if (runResult.exitRequested) {
+        return { runState: runResult.runState };
+      }
       // then handle the result...
       if (runResult.runState === RunState.NO_COMMAND) {
         // print usage

package/src/cli/BaseCLIFeatureOptions.ts

@@ -16,6 +16,11 @@ export default interface BaseCLIFeatureOptions {
   readonly fetchServiceEnabled?: boolean;
   readonly upgradeServiceEnabled?: boolean;
   readonly upgradeLocationsConfig?: UpgradeLocationsConfig;
+  /**
+   * When an automatic upgrade on startup succeeds, run the upgraded executable with the same
+   * arguments and end this run with its result, rather than continuing on the old version.
+   */
+  readonly restartAfterAutoUpgrade?: boolean;
   readonly pluginServiceEnabled?: boolean;
   readonly pluginServiceRemoteConfig?: NpmjsPluginRepositoryConfig;
   readonly pluginServiceLocalConfig?: NpmPluginRepositoryConfig;

package/src/cli/DefaultRuntimeCLI.ts

@@ -72,7 +72,7 @@ export default class DefaultRuntimeCLI extends BaseCLI {
       stderrTerminal,
       new TtyStyler(colorLevel, supportsHyperlinks(process.stderr)),
       keyReader,
-      { promptingEnabled, ...options },
+      { promptingEnabled, restartAfterAutoUpgrade: true, ...options },
     );
   }
 

package/src/runtime/runner.ts

@@ -36,6 +36,12 @@ import { sortByPriority } from "./lifecycle/PriorityTaskList.ts";
 
 const logger = getLogger("runner");
 
+/**
+ * The {@link RunResult} returned by {@link run}, with `exitRequested` set when a startup task ended
+ * the run early by returning an `exitRequest`.
+ */
+export type RunnerResult = RunResult & { readonly exitRequested?: true };
+
 /**
  * Wrap a {@link ServiceProvider}'s `initService()` call as a {@link StartupTask} so it can be
  * merged with directly-registered {@link StartupTask}s (e.g. the banner task) into a single
@@ -560,6 +566,8 @@ async function findAndExecuteDefaultNonModifierCommand(
  *    - Run the task: awaited before continuing if its mode is "blocking" (the default, and how
  *      every ServiceProvider's initService() behaves); fired without awaiting if "background"
  *      (errors logged, not propagated).
+ *    - Return immediately if a "blocking" task returned an exitRequest, using its runState and
+ *      skipping the remaining tasks and the command.
  * 2. Scan arguments for any GlobalModifierCommand clauses not provided by a StartupTask
  *    - For each discovered clause:
  *      - Set any argument defaults from ConfigurationServiceProvider
@@ -615,7 +623,7 @@ export async function run(
   context: Context,
   defaultCommand?: Command,
   startupService?: DefaultStartupService,
-): Promise<RunResult> {
+): Promise<RunnerResult> {
   if (defaultCommand && !isSubCommand(defaultCommand) && !isGlobalCommand(defaultCommand)) {
     throw new Error(
       "If a default command is provided, if must be a global command or sub-command!",
@@ -681,7 +689,14 @@ export async function run(
       : context;
 
     if ((task.mode ?? "blocking") === "blocking") {
-      await task.run(taskContext);
+      const outcome = await task.run(taskContext);
+      if (outcome?.exitRequest) {
+        logger.debug(
+          () =>
+            `Startup task '${task.id}' requested exit with run state ${outcome.exitRequest.runState}`,
+        );
+        return { runState: outcome.exitRequest.runState, exitRequested: true };
+      }
     } else {
       void task.run(taskContext).catch((error: unknown) => {
         logger.debug(() => `Background startup task '${task.id}' failed: ${error}`);

package/src/service/configuration/DefaultKeyValueService.ts

@@ -16,16 +16,37 @@ export default class DefaultKeyValueService implements KeyValueService {
   readonly #keyValueData: Map<string, ValueNode>;
   #dirty = false;
   readonly #secretService: DefaultSecretService | undefined;
+  readonly #flushToStorage: (() => Promise<void>) | undefined;
 
-  constructor(keyValueData: Map<string, ValueNode>, secretService?: DefaultSecretService) {
+  /**
+   * @param keyValueData the scope's data.
+   * @param secretService optional secret service for {@link Secret} values.
+   * @param flushToStorage optional callback which writes every scope's pending changes to storage
+   * and marks them clean, invoked by {@link flush}.
+   */
+  constructor(
+    keyValueData: Map<string, ValueNode>,
+    secretService?: DefaultSecretService,
+    flushToStorage?: () => Promise<void>,
+  ) {
     this.#keyValueData = keyValueData;
     this.#secretService = secretService;
+    this.#flushToStorage = flushToStorage;
   }
 
   public isDirty(): boolean {
     return this.#dirty;
   }
 
+  public markClean(): void {
+    this.#dirty = false;
+  }
+
+  public async flush(): Promise<void> {
+    await this.#flushToStorage?.();
+    this.#dirty = false;
+  }
+
   public async get<T extends ValueNode = ValueNode>(key: string): Promise<T> {
     const value = this.#keyValueData.get(key);
     if (value === undefined) {

package/src/service/configuration/KeyValueServiceProvider.ts

@@ -38,6 +38,10 @@ class UnreachableKeyValueService implements KeyValueService {
     return Promise.reject(new Error(UnreachableKeyValueService.#message));
   }
 
+  flush(): Promise<void> {
+    return Promise.reject(new Error(UnreachableKeyValueService.#message));
+  }
+
   static readonly #message =
     "KeyValueService accessed without a resolved scope - this should be unreachable";
 }
@@ -189,7 +193,9 @@ export default class KeyValueServiceProvider implements ServiceProvider {
     const secretService = this.secretServiceEnabled
       ? new DefaultSecretService(this.#cliConfigName!, `${scopeType}_${scopeKey}`)
       : undefined;
-    const scopedService = new DefaultKeyValueService(keyValueData, secretService);
+    const scopedService = new DefaultKeyValueService(keyValueData, secretService, () =>
+      this.#flushDirtyScopes(),
+    );
     scopedServices.set(scopeKey, scopedService);
     return scopedService;
   }
@@ -230,15 +236,21 @@ export default class KeyValueServiceProvider implements ServiceProvider {
 
   /**
    * Flush every scoped KeyValueService's data to the configuration file, if any of them report
-   * themselves dirty. Registered as a low-priority ShutdownTask (see {@link initService}) so it
-   * runs once, after other shutdown cleanup, regardless of how long any scope was written to.
+   * themselves dirty, then mark them all clean. Registered as a low-priority ShutdownTask (see
+   * {@link initService}) so it runs once, after other shutdown cleanup, regardless of how long any
+   * scope was written to. Also backs {@link KeyValueService.flush} for every scope.
    */
   async #flushDirtyScopes(): Promise<void> {
-    const anyDirty = [
+    const scopedServices = [
       ...this.#commandScopedKeyValueServices.values(),
       ...this.#serviceScopedKeyValueServices.values(),
-    ].some((service) => service.isDirty());
-    await this.#configurationServiceProvider.flushIfDirty(anyDirty);
+    ];
+    await this.#configurationServiceProvider.flushIfDirty(
+      scopedServices.some((service) => service.isDirty()),
+    );
+    for (const service of scopedServices) {
+      service.markClean();
+    }
   }
 
   public async initService(context: Context): Promise<void> {

package/src/service/shutdown/ShutdownServiceProvider.ts

@@ -2,7 +2,7 @@ import process from "node:process";
 import type { ServiceInfo, ServiceProvider } from "@flowscripter/dynamic-cli-framework-api";
 import DefaultShutdownService from "./DefaultShutdownService.ts";
 import type { ShutdownService } from "@flowscripter/dynamic-cli-framework-api";
-import { SHUTDOWN_SERVICE_ID } from "@flowscripter/dynamic-cli-framework-api";
+import { RunState, SHUTDOWN_SERVICE_ID } from "@flowscripter/dynamic-cli-framework-api";
 import type { Context } from "@flowscripter/dynamic-cli-framework-api";
 import getLogger from "../../util/logger.ts";
 import type { CLIConfig } from "@flowscripter/dynamic-cli-framework-api";
@@ -37,7 +37,7 @@ export default class ShutdownServiceProvider implements ServiceProvider {
     shutdownState.interruptCount++;
     if (!shutdownState.longRunningMode || shutdownState.interruptCount >= 3) {
       ShutdownServiceProvider.shutdown().then(() => {
-        process.exit(130);
+        process.exit(RunState.INTERRUPTED);
       });
     } else {
       shutdownState.shutdownRequested = true;
@@ -46,7 +46,7 @@ export default class ShutdownServiceProvider implements ServiceProvider {
 
   static onTerminate(): void {
     ShutdownServiceProvider.shutdown().then(() => {
-      process.exit(143);
+      process.exit(RunState.TERMINATED);
     });
   }
 

package/src/service/spawn/DefaultSpawnService.ts

@@ -108,6 +108,7 @@ export default class DefaultSpawnService implements SpawnService {
     try {
       proc = Bun.spawn(resolveForPlatform(command), {
         cwd: options.cwd,
+        env: options.env === undefined ? undefined : { ...process.env, ...options.env },
         stdin: mode === "inherit" ? "inherit" : "ignore",
         stdout: mode === "wrapped" ? "pipe" : mode === "ignore" ? "ignore" : "inherit",
         stderr: mode === "wrapped" ? "pipe" : mode === "ignore" ? "ignore" : "inherit",

package/src/service/upgrade/DefaultUpgradeService.ts

@@ -1,8 +1,8 @@
 import process from "node:process";
-import { realpathSync } from "node:fs";
+import { existsSync, realpathSync } from "node:fs";
 import { mkdtemp, rename, rm } from "node:fs/promises";
 import { tmpdir } from "node:os";
-import { dirname, join } from "node:path";
+import { basename, dirname, join } from "node:path";
 import type {
   CLIConfig,
   Context,
@@ -21,6 +21,7 @@ import {
   InstallMethod,
   KEY_VALUE_SERVICE_ID,
   PRINTER_SERVICE_ID,
+  RunState,
   SPAWN_SERVICE_ID,
   SupportedArch,
   SupportedOs,
@@ -85,6 +86,46 @@ export function describeUpgradeCheckResult(result: UpgradeCheckResult): string {
     : `Upgrade check result: ${JSON.stringify(result)}`;
 }
 
+// Environment variable set on a process restarted after an automatic upgrade, holding the version
+// which restarted it (see DefaultUpgradeService.restart() and restartedFromVersion).
+const RESTARTED_FROM_VERSION_ENV_VAR = "DYNAMIC_CLI_FRAMEWORK_REEXEC_FROM";
+
+// Exit codes from 129 upwards are reported for a child terminated by a signal (128 + signal number).
+const SIGNAL_EXIT_CODE_BASE = 128;
+
+const RUN_STATE_VALUES = new Set<number>(
+  Object.values(RunState).filter((value): value is number => typeof value === "number"),
+);
+
+/**
+ * Map the result of spawning a restarted CLI to the {@link RunState} it ended with.
+ *
+ * The child is the same framework CLI, so it normally exits with a {@link RunState} value, which is
+ * returned as is (this includes 130 for SIGINT and 143 for SIGTERM). Termination by any other
+ * signal, or a timeout, maps to {@link RunState.TERMINATED}, and any other exit code to
+ * {@link RunState.RUNTIME_ERROR}.
+ *
+ * @return the {@link RunState}, or `undefined` if the child could not be started.
+ */
+export function toRunState(result: SpawnResult): RunState | undefined {
+  if (result.ok) {
+    return RunState.SUCCESS;
+  }
+  if ("timedOut" in result) {
+    return RunState.TERMINATED;
+  }
+  if (result.exitCode === undefined) {
+    return undefined;
+  }
+  if (RUN_STATE_VALUES.has(result.exitCode)) {
+    return result.exitCode as RunState;
+  }
+  if (result.exitCode > SIGNAL_EXIT_CODE_BASE) {
+    return RunState.TERMINATED;
+  }
+  return RunState.RUNTIME_ERROR;
+}
+
 const OS_LABELS: Record<SupportedOs, string> = {
   [SupportedOs.LINUX]: "Linux",
   [SupportedOs.MACOS]: "MacOS",
@@ -96,10 +137,12 @@ export default class DefaultUpgradeService implements UpgradeService {
   #upgradeCheckPromise: Promise<UpgradeCheckResult> | undefined;
   readonly #config: UpgradeLocationsConfig;
   readonly #cliConfig: CLIConfig;
+  public readonly restartedFromVersion: string | undefined;
 
   public constructor(config: UpgradeLocationsConfig, cliConfig: CLIConfig) {
     this.#config = config;
     this.#cliConfig = cliConfig;
+    this.restartedFromVersion = process.env[RESTARTED_FROM_VERSION_ENV_VAR] || undefined;
   }
 
   public setContext(context: Context): void {
@@ -214,6 +257,67 @@ export default class DefaultUpgradeService implements UpgradeService {
     return cached as unknown as UpgradeCheckResult | undefined;
   }
 
+  /**
+   * Resolve the executable to restart into after a successful upgrade via `installMethod`.
+   *
+   * @return the executable path, or `undefined` if it cannot be resolved (e.g. for winget, or a
+   * homebrew install whose `opt` link is missing).
+   */
+  public resolveUpgradedExecutable(installMethod: InstallMethod): string | undefined {
+    switch (installMethod) {
+      case InstallMethod.GITHUB_RELEASE:
+      case InstallMethod.LINUX_SCRIPT:
+        return process.execPath;
+      case InstallMethod.HOMEBREW:
+        return this.#resolveHomebrewOptExecutable();
+      case InstallMethod.WINGET:
+        return undefined;
+    }
+  }
+
+  // The running executable lives in a version-specific Cellar directory, e.g.
+  // "<prefix>/Cellar/<formula>/<version>/bin/<exe>", while "<prefix>/opt/<formula>" links to the
+  // installed version, so the upgraded executable is "<prefix>/opt/<formula>/bin/<exe>".
+  #resolveHomebrewOptExecutable(): string | undefined {
+    if (!this.#config.homebrew) {
+      return undefined;
+    }
+    const { formula } = this.#config.homebrew;
+    const realExecutable = this.#resolveRealExecutable();
+    const cellarIndex = realExecutable.indexOf(`/Cellar/${formula}/`);
+    if (cellarIndex === -1) {
+      return undefined;
+    }
+    const prefix = realExecutable.slice(0, cellarIndex);
+    const executable = join(prefix, "opt", formula, "bin", basename(realExecutable));
+    return existsSync(executable) ? executable : undefined;
+  }
+
+  /**
+   * Run `executable` with `args` in place of this process, with terminal input and output
+   * inherited, and wait for it to exit. The child process sees the current version as its
+   * {@link restartedFromVersion}.
+   *
+   * @return the {@link RunState} the child ended with (see {@link toRunState}), or `undefined` if
+   * it could not be started.
+   */
+  public async restart(
+    executable: string,
+    args: ReadonlyArray<string>,
+  ): Promise<RunState | undefined> {
+    const spawnService = this.#spawnService;
+    if (!spawnService) {
+      return undefined;
+    }
+    const result = await spawnService.spawn([executable, ...args], {
+      mode: "inherit",
+      // Ctrl-C reaches the child directly from the terminal, so this process only notes it
+      longRunning: true,
+      env: { [RESTARTED_FROM_VERSION_ENV_VAR]: this.#cliConfig.version },
+    });
+    return toRunState(result);
+  }
+
   public detectOs(): SupportedOs | undefined {
     switch (process.platform) {
       case "linux":
@@ -430,14 +534,17 @@ export default class DefaultUpgradeService implements UpgradeService {
   // `brew`, which has a slow cold start - avoiding it keeps the background upgrade-check
   // StartupTask (see UpgradeServiceProvider) fast even though it runs to completion.
   #isRunningFromHomebrewCellar(formula: string): boolean {
-    let realExecutable = process.execPath;
+    return this.#resolveRealExecutable().includes(`/Cellar/${formula}/`);
+  }
+
+  #resolveRealExecutable(): string {
     try {
-      realExecutable = realpathSync(process.execPath);
+      return realpathSync(process.execPath);
     } catch {
       // process.execPath may not resolve on disk (e.g. a fabricated path in tests) - fall back to
       // the unresolved path rather than treating that as "not installed".
+      return process.execPath;
     }
-    return realExecutable.includes(`/Cellar/${formula}/`);
   }
 
   async #isHomebrewInstalled(): Promise<boolean> {