@flowscripter/dynamic-cli-framework 7.0.11 → 7.1.1

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/prompter/DefaultPrompterService.ts

@@ -1,4 +1,4 @@
-import type { PrompterService } from "@flowscripter/dynamic-cli-framework-api";
+import type { Context, PrompterService } from "@flowscripter/dynamic-cli-framework-api";
 import {
   type Prompt,
   type PromptResult,
@@ -33,7 +33,7 @@ export const DEFAULT_PROMPTER_CONFIG: PrompterServiceConfig = {
 export default class DefaultPrompterService implements PrompterService {
   promptEnabled = true;
 
-  readonly #ctx: PromptContext;
+  #ctx: PromptContext;
 
   public constructor(
     config: PrompterServiceConfig,
@@ -44,6 +44,10 @@ export default class DefaultPrompterService implements PrompterService {
     this.#ctx = { config, terminal, keyReader, printerService };
   }
 
+  setContext(context: Context): void {
+    this.#ctx = { ...this.#ctx, context };
+  }
+
   prompt(promptDef: Prompt): Promise<PromptResult> {
     if (!this.promptEnabled) {
       if (promptDef.defaultOption) {

package/src/service/prompter/PrompterServiceProvider.ts

@@ -1,9 +1,9 @@
 import type { Context } from "@flowscripter/dynamic-cli-framework-api";
 import type { ServiceInfo, ServiceProvider } from "@flowscripter/dynamic-cli-framework-api";
-import type { PrompterService } from "@flowscripter/dynamic-cli-framework-api";
 import { PROMPTER_SERVICE_ID } from "@flowscripter/dynamic-cli-framework-api";
 import NoPromptCommand from "./command/NoPromptCommand.ts";
-import type { CLIConfig } from "@flowscripter/dynamic-cli-framework-api";
+import type { CLIConfig, PrompterService } from "@flowscripter/dynamic-cli-framework-api";
+import DefaultPrompterService from "./DefaultPrompterService.ts";
 
 export default class PrompterServiceProvider implements ServiceProvider {
   readonly serviceId: string = PROMPTER_SERVICE_ID;
@@ -22,7 +22,10 @@ export default class PrompterServiceProvider implements ServiceProvider {
     });
   }
 
-  initService(_context: Context): Promise<void> {
+  initService(context: Context): Promise<void> {
+    if (this.prompterService instanceof DefaultPrompterService) {
+      this.prompterService.setContext(context);
+    }
     return Promise.resolve();
   }
 }

package/src/service/prompter/prompt/PromptContext.ts

@@ -1,4 +1,10 @@
-import type { Prompt } from "@flowscripter/dynamic-cli-framework-api";
+import type {
+  Context,
+  Prompt,
+  ShutdownService,
+  SpawnService,
+} from "@flowscripter/dynamic-cli-framework-api";
+import { SHUTDOWN_SERVICE_ID, SPAWN_SERVICE_ID } from "@flowscripter/dynamic-cli-framework-api";
 import type Terminal from "../../../terminal/Terminal.ts";
 import type KeyReader from "../../../terminal/KeyReader.ts";
 import type { PrinterService } from "@flowscripter/dynamic-cli-framework-api";
@@ -9,6 +15,18 @@ export interface PromptContext {
   readonly terminal: Terminal;
   readonly keyReader: KeyReader;
   readonly printerService: PrinterService;
+  readonly context?: Context;
+}
+
+export function interrupt(ctx: PromptContext): void {
+  (ctx.context?.getServiceById(SHUTDOWN_SERVICE_ID) as ShutdownService | undefined)?.interrupt();
+}
+
+export function getSpawnService(ctx: PromptContext): SpawnService | undefined {
+  if (!ctx.context?.doesServiceExist(SPAWN_SERVICE_ID)) {
+    return undefined;
+  }
+  return ctx.context.getServiceById(SPAWN_SERVICE_ID) as SpawnService;
 }
 
 export function physicalLineCount(terminal: Terminal, text: string): number {

package/src/service/prompter/prompt/promptMultiSelect.ts

@@ -1,7 +1,6 @@
 import type { Prompt, PromptResult } from "@flowscripter/dynamic-cli-framework-api";
 import { SpecialKey } from "../../../terminal/KeyReader.ts";
-import ShutdownServiceProvider from "../../shutdown/ShutdownServiceProvider.ts";
-import { headerLineCount, renderPromptHeader } from "./PromptContext.ts";
+import { headerLineCount, renderPromptHeader, interrupt } from "./PromptContext.ts";
 import type { PromptContext } from "./PromptContext.ts";
 
 export default async function promptMultiSelect(
@@ -74,7 +73,7 @@ export default async function promptMultiSelect(
         throw new Error("Prompt cancelled");
       } else if (keyEvent.specialKey === SpecialKey.INTERRUPT) {
         await ctx.terminal.showCursor();
-        ShutdownServiceProvider.onInterrupt();
+        interrupt(ctx);
         throw new Error("Interrupted");
       }
     }

package/src/service/prompter/prompt/promptOpenUrl.ts

@@ -1,14 +1,13 @@
-import type { Prompt, PromptResult } from "@flowscripter/dynamic-cli-framework-api";
+import type { Prompt, PromptResult, SpawnService } from "@flowscripter/dynamic-cli-framework-api";
 import { SpecialKey } from "../../../terminal/KeyReader.ts";
-import ShutdownServiceProvider from "../../shutdown/ShutdownServiceProvider.ts";
-import { renderPromptHeader } from "./PromptContext.ts";
+import { getSpawnService, interrupt, renderPromptHeader } from "./PromptContext.ts";
 import type { PromptContext } from "./PromptContext.ts";
 
 function isRemoteSession(): boolean {
   return !!(process.env.SSH_CONNECTION || process.env.SSH_CLIENT || process.env.SSH_TTY);
 }
 
-async function defaultOpenUrl(url: string): Promise<void> {
+export async function defaultOpenUrl(spawnService: SpawnService, url: string): Promise<void> {
   const parsed = new URL(url);
   if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
     throw new Error(`Unsupported URL protocol: ${parsed.protocol}`);
@@ -22,11 +21,16 @@ async function defaultOpenUrl(url: string): Promise<void> {
   } else {
     cmd = ["xdg-open", url];
   }
-  const proc = Bun.spawn(cmd, { stdout: "ignore", stderr: "ignore" });
-  const exitCode = await proc.exited;
-  if (exitCode !== 0) {
-    throw new Error(`Failed to open URL (exit code ${exitCode})`);
+  const result = await spawnService.spawn(cmd, { mode: "ignore", longRunning: false });
+  if (result.ok) {
+    return;
   }
+  if ("error" in result && result.error) {
+    throw result.error;
+  }
+  throw new Error(
+    `Failed to open URL (exit code ${"exitCode" in result ? result.exitCode : "unknown"})`,
+  );
 }
 
 export default async function promptOpenUrl(
@@ -39,8 +43,11 @@ export default async function promptOpenUrl(
 
   const url = String(promptDef.options[0]!.returnedValue);
   const displayLabel = promptDef.options[0]!.displayValue;
-  const openUrlFn = ctx.config.openUrl ?? defaultOpenUrl;
-  const canOpenBrowser = !isRemoteSession();
+  const spawnService = getSpawnService(ctx);
+  const openUrlFn =
+    ctx.config.openUrl ??
+    (spawnService ? (target: string) => defaultOpenUrl(spawnService, target) : undefined);
+  const canOpenBrowser = openUrlFn !== undefined && !isRemoteSession();
 
   ctx.keyReader.enableRawMode();
   try {
@@ -72,7 +79,7 @@ export default async function promptOpenUrl(
       } else if (keyEvent.specialKey === SpecialKey.ESCAPE) {
         throw new Error("Prompt cancelled");
       } else if (keyEvent.specialKey === SpecialKey.INTERRUPT) {
-        ShutdownServiceProvider.onInterrupt();
+        interrupt(ctx);
         throw new Error("Interrupted");
       }
     }

package/src/service/prompter/prompt/promptSingleSelect.ts

@@ -1,7 +1,6 @@
 import type { Prompt, PromptResult } from "@flowscripter/dynamic-cli-framework-api";
 import { SpecialKey } from "../../../terminal/KeyReader.ts";
-import ShutdownServiceProvider from "../../shutdown/ShutdownServiceProvider.ts";
-import { headerLineCount, renderPromptHeader } from "./PromptContext.ts";
+import { headerLineCount, renderPromptHeader, interrupt } from "./PromptContext.ts";
 import type { PromptContext } from "./PromptContext.ts";
 
 export default async function promptSingleSelect(
@@ -75,7 +74,7 @@ export default async function promptSingleSelect(
         throw new Error("Prompt cancelled");
       } else if (keyEvent.specialKey === SpecialKey.INTERRUPT) {
         await ctx.terminal.showCursor();
-        ShutdownServiceProvider.onInterrupt();
+        interrupt(ctx);
         throw new Error("Interrupted");
       }
     }

package/src/service/prompter/prompt/promptText.ts

@@ -1,8 +1,7 @@
 import type { Prompt, PromptResult } from "@flowscripter/dynamic-cli-framework-api";
 import type { SingleValueType } from "@flowscripter/dynamic-cli-framework-api";
 import { SpecialKey } from "../../../terminal/KeyReader.ts";
-import ShutdownServiceProvider from "../../shutdown/ShutdownServiceProvider.ts";
-import { renderPromptHeader } from "./PromptContext.ts";
+import { renderPromptHeader, interrupt } from "./PromptContext.ts";
 import type { PromptContext } from "./PromptContext.ts";
 
 export default async function promptText(
@@ -32,7 +31,7 @@ export default async function promptText(
           throw new Error("Prompt cancelled");
         } else if (keyEvent.specialKey === SpecialKey.INTERRUPT) {
           await ctx.terminal.write("\n");
-          ShutdownServiceProvider.onInterrupt();
+          interrupt(ctx);
           throw new Error("Interrupted");
         } else if (keyEvent.specialKey === SpecialKey.BACKSPACE) {
           if (buffer.length > 0) {

package/src/service/shutdown/DefaultShutdownService.ts

@@ -5,6 +5,12 @@ import { shutdownState } from "./ShutdownState.ts";
 export default class DefaultShutdownService implements ShutdownService {
   static readonly taskList = new PriorityTaskList<ShutdownTask>();
 
+  readonly #onInterrupt: () => void;
+
+  public constructor(onInterrupt: () => void = () => {}) {
+    this.#onInterrupt = onInterrupt;
+  }
+
   registerTask(task: ShutdownTask): void {
     DefaultShutdownService.taskList.add(task);
   }
@@ -17,6 +23,10 @@ export default class DefaultShutdownService implements ShutdownService {
     shutdownState.longRunningMode = false;
   }
 
+  interrupt(): void {
+    this.#onInterrupt();
+  }
+
   get isShutdownRequested(): boolean {
     return shutdownState.shutdownRequested;
   }

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";
@@ -16,7 +16,7 @@ export default class ShutdownServiceProvider implements ServiceProvider {
   static #shutdownInProgress = false;
 
   public constructor(readonly servicePriority: number) {
-    this.#shutdownService = new DefaultShutdownService();
+    this.#shutdownService = new DefaultShutdownService(ShutdownServiceProvider.onInterrupt);
     process.on("beforeExit", ShutdownServiceProvider.shutdown);
     process.on("SIGINT", ShutdownServiceProvider.onInterrupt);
     process.on("SIGTERM", ShutdownServiceProvider.onTerminate);
@@ -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> {

package/src/service/upgrade/UpgradeServiceProvider.ts

@@ -16,7 +16,7 @@ import DefaultUpgradeService from "./DefaultUpgradeService.ts";
 import { UpgradeSubCommand } from "./command/UpgradeSubCommand.ts";
 import type { UpgradeLocationsConfig } from "./UpgradeLocationsConfig.ts";
 import getLogger from "../../util/logger.ts";
-import type { StartupTask } from "@flowscripter/dynamic-cli-framework-api";
+import type { StartupTask, StartupTaskOutcome } from "@flowscripter/dynamic-cli-framework-api";
 
 const logger = getLogger("UpgradeServiceProvider");
 
@@ -42,7 +42,7 @@ export function createUpgradeCheckStartupTask(
 
 /**
  * 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.
  */
@@ -65,10 +65,31 @@ export default class UpgradeServiceProvider implements ServiceProvider {
   #upgradeService: DefaultUpgradeService | undefined;
   #cliConfig: CLIConfig | undefined;
   #keyValueService: KeyValueService | undefined;
+  readonly #restartAfterAutoUpgrade: boolean;
+  #restartArgs: ReadonlyArray<string> = [];
 
-  public constructor(servicePriority: number, config: UpgradeLocationsConfig) {
+  /**
+   * @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.
+   */
+  public constructor(
+    servicePriority: number,
+    config: UpgradeLocationsConfig,
+    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.
+   */
+  public setRestartArgs(args: ReadonlyArray<string>): void {
+    this.#restartArgs = args;
   }
 
   public get upgradeService(): DefaultUpgradeService | undefined {
@@ -113,13 +134,25 @@ export default class UpgradeServiceProvider implements ServiceProvider {
    * 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.
    */
-  public async runAutoUpgrade(context: Context): Promise<void> {
+  public async runAutoUpgrade(context: Context): Promise<void | StartupTaskOutcome> {
     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;
@@ -136,8 +169,7 @@ export default class UpgradeServiceProvider implements ServiceProvider {
         return;
       }
       if (status === "enabled") {
-        await this.#checkAndUpgrade(context, upgradeService, cliConfig);
-        return;
+        return this.#checkAndUpgrade(context, upgradeService, cliConfig, keyValueService);
       }
     }
 
@@ -183,14 +215,15 @@ export default class UpgradeServiceProvider implements ServiceProvider {
     }
 
     await keyValueService.set("upgrade-status", "enabled");
-    await this.#checkAndUpgrade(context, upgradeService, cliConfig);
+    return this.#checkAndUpgrade(context, upgradeService, cliConfig, keyValueService);
   }
 
   async #checkAndUpgrade(
     context: Context,
     upgradeService: DefaultUpgradeService,
     cliConfig: CLIConfig,
-  ): Promise<void> {
+    keyValueService: KeyValueService,
+  ): Promise<void | StartupTaskOutcome> {
     try {
       const checkResult = await upgradeService.getUpgradeCheckResult();
       if (checkResult.status === "failed") {
@@ -201,21 +234,46 @@ export default class UpgradeServiceProvider implements ServiceProvider {
         return;
       }
       const upgradeResult = await upgradeService.upgrade();
-      if (!context.doesServiceExist(PRINTER_SERVICE_ID)) {
-        return;
-      }
-      const printerService = context.getServiceById(PRINTER_SERVICE_ID) as PrinterService;
-      if (upgradeResult.ok) {
-        await printerService.info(
-          `${cliConfig.name} upgraded (${upgradeResult.oldVersion} -> ${upgradeResult.newVersion})\n`,
-          Icon.SUCCESS,
-        );
-      } else {
-        await printerService.error(
+      const printerService = context.doesServiceExist(PRINTER_SERVICE_ID)
+        ? (context.getServiceById(PRINTER_SERVICE_ID) as PrinterService)
+        : 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 executable = upgradeService.resolveUpgradedExecutable(checkResult.installMethod);
+      if (executable === undefined) {
+        await printerService?.info(
+          `Restart ${cliConfig.name} to use ${upgradeResult.newVersion}\n`,
+          Icon.INFORMATION,
+        );
+        return;
+      }
+
+      // 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/src/service/upgrade/command/UpgradeSubCommand.ts

@@ -11,7 +11,7 @@ import {
   UPGRADE_SERVICE_ID,
 } from "@flowscripter/dynamic-cli-framework-api";
 import type { PrinterService } from "@flowscripter/dynamic-cli-framework-api";
-import type DefaultUpgradeService from "../DefaultUpgradeService.ts";
+import type { UpgradeService } from "@flowscripter/dynamic-cli-framework-api";
 
 export class UpgradeSubCommand implements SubCommand {
   readonly name = "upgrade";
@@ -38,7 +38,7 @@ export class UpgradeSubCommand implements SubCommand {
 
   public async execute(context: Context, argumentValues: Values): Promise<void> {
     const printerService = context.getServiceById(PRINTER_SERVICE_ID) as PrinterService;
-    const upgradeService = context.getServiceById(UPGRADE_SERVICE_ID) as DefaultUpgradeService;
+    const upgradeService = context.getServiceById(UPGRADE_SERVICE_ID) as UpgradeService;
     const cliName = context.cliConfig.name;
     const currentVersion = context.cliConfig.version;