@flowscripter/dynamic-cli-framework 7.0.11 → 7.1.1

package/dist/src/service/upgrade/DefaultUpgradeService.d.ts

@@ -1,10 +1,22 @@
-import type { CLIConfig, Context, UpgradeCheckResult, UpgradeResult } from "@flowscripter/dynamic-cli-framework-api";
-import { InstallMethod, SupportedArch, SupportedOs, type UpgradeService } from "@flowscripter/dynamic-cli-framework-api";
+import type { CLIConfig, Context, SpawnResult, UpgradeCheckResult, UpgradeResult } from "@flowscripter/dynamic-cli-framework-api";
+import { InstallMethod, RunState, SupportedArch, SupportedOs, type UpgradeService } from "@flowscripter/dynamic-cli-framework-api";
 import type { UpgradeLocationsConfig } from "./UpgradeLocationsConfig.ts";
 export declare const UPGRADE_CHECK_CACHE_KEY = "upgrade-check-result";
 export declare function describeUpgradeCheckResult(result: UpgradeCheckResult): string;
+/**
+ * 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 declare function toRunState(result: SpawnResult): RunState | undefined;
 export default class DefaultUpgradeService implements UpgradeService {
     #private;
+    readonly restartedFromVersion: string | undefined;
     constructor(config: UpgradeLocationsConfig, cliConfig: CLIConfig);
     setContext(context: Context): void;
     getUpgradeCheckResult(): Promise<UpgradeCheckResult>;
@@ -19,6 +31,22 @@ export default class DefaultUpgradeService implements UpgradeService {
      * Returns `undefined` if nothing has been persisted yet or no KeyValueService is available.
      */
     getCachedUpgradeCheckResult(): Promise<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).
+     */
+    resolveUpgradedExecutable(installMethod: InstallMethod): string | 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.
+     */
+    restart(executable: string, args: ReadonlyArray<string>): Promise<RunState | undefined>;
     detectOs(): SupportedOs | undefined;
     detectArch(): SupportedArch | undefined;
     detectInstallMethod(os: SupportedOs): Promise<InstallMethod | undefined>;

package/dist/src/service/upgrade/DefaultUpgradeService.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"DefaultUpgradeService.d.ts","sourceRoot":"","sources":["../../../../src/service/upgrade/DefaultUpgradeService.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EACV,SAAS,EACT,OAAO,EAOP,kBAAkB,EAClB,aAAa,EAEd,MAAM,yCAAyC,CAAC;AACjD,OAAO,EAEL,aAAa,EAIb,aAAa,EACb,WAAW,EACX,KAAK,cAAc,EACpB,MAAM,yCAAyC,CAAC;AAEjD,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,6BAA6B,CAAC;AAwC1E,eAAO,MAAM,uBAAuB,yBAAyB,CAAC;AAY9D,wBAAgB,0BAA0B,CAAC,MAAM,EAAE,kBAAkB,GAAG,MAAM,CAI7E;AAQD,MAAM,CAAC,OAAO,OAAO,qBAAsB,YAAW,cAAc;;IAMlE,YAAmB,MAAM,EAAE,sBAAsB,EAAE,SAAS,EAAE,SAAS,EAGtE;IAEM,UAAU,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAExC;IA4DM,qBAAqB,IAAI,OAAO,CAAC,kBAAkB,CAAC,CAe1D;IAED;;;;OAIG;IACU,wBAAwB,IAAI,OAAO,CAAC,kBAAkB,CAAC,CASnE;IAED;;;OAGG;IACU,2BAA2B,IAAI,OAAO,CAAC,kBAAkB,GAAG,SAAS,CAAC,CAWlF;IAEM,QAAQ,IAAI,WAAW,GAAG,SAAS,CAWzC;IAEM,UAAU,IAAI,aAAa,GAAG,SAAS,CAS7C;IAEY,mBAAmB,CAAC,EAAE,EAAE,WAAW,GAAG,OAAO,CAAC,aAAa,GAAG,SAAS,CAAC,CAsCpF;IA2CY,eAAe,CAC1B,UAAU,CAAC,EAAE,WAAW,EACxB,YAAY,CAAC,EAAE,aAAa,EAC5B,qBAAqB,CAAC,EAAE,aAAa,GACpC,OAAO,CAAC,kBAAkB,CAAC,CAsC7B;IAEY,OAAO,CAClB,UAAU,CAAC,EAAE,WAAW,EACxB,YAAY,CAAC,EAAE,aAAa,EAC5B,qBAAqB,CAAC,EAAE,aAAa,GACpC,OAAO,CAAC,aAAa,CAAC,CAkDxB;CAwTF"}
+{"version":3,"file":"DefaultUpgradeService.d.ts","sourceRoot":"","sources":["../../../../src/service/upgrade/DefaultUpgradeService.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EACV,SAAS,EACT,OAAO,EAKP,WAAW,EAEX,kBAAkB,EAClB,aAAa,EAEd,MAAM,yCAAyC,CAAC;AACjD,OAAO,EAEL,aAAa,EAGb,QAAQ,EAER,aAAa,EACb,WAAW,EACX,KAAK,cAAc,EACpB,MAAM,yCAAyC,CAAC;AAEjD,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,6BAA6B,CAAC;AAwC1E,eAAO,MAAM,uBAAuB,yBAAyB,CAAC;AAY9D,wBAAgB,0BAA0B,CAAC,MAAM,EAAE,kBAAkB,GAAG,MAAM,CAI7E;AAaD;;;;;;;;;GASG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,WAAW,GAAG,QAAQ,GAAG,SAAS,CAiBpE;AAQD,MAAM,CAAC,OAAO,OAAO,qBAAsB,YAAW,cAAc;;IAKlE,SAAgB,oBAAoB,EAAE,MAAM,GAAG,SAAS,CAAC;IAEzD,YAAmB,MAAM,EAAE,sBAAsB,EAAE,SAAS,EAAE,SAAS,EAItE;IAEM,UAAU,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAExC;IA4DM,qBAAqB,IAAI,OAAO,CAAC,kBAAkB,CAAC,CAe1D;IAED;;;;OAIG;IACU,wBAAwB,IAAI,OAAO,CAAC,kBAAkB,CAAC,CASnE;IAED;;;OAGG;IACU,2BAA2B,IAAI,OAAO,CAAC,kBAAkB,GAAG,SAAS,CAAC,CAWlF;IAED;;;;;OAKG;IACI,yBAAyB,CAAC,aAAa,EAAE,aAAa,GAAG,MAAM,GAAG,SAAS,CAUjF;IAoBD;;;;;;;OAOG;IACU,OAAO,CAClB,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,aAAa,CAAC,MAAM,CAAC,GAC1B,OAAO,CAAC,QAAQ,GAAG,SAAS,CAAC,CAY/B;IAEM,QAAQ,IAAI,WAAW,GAAG,SAAS,CAWzC;IAEM,UAAU,IAAI,aAAa,GAAG,SAAS,CAS7C;IAEY,mBAAmB,CAAC,EAAE,EAAE,WAAW,GAAG,OAAO,CAAC,aAAa,GAAG,SAAS,CAAC,CAsCpF;IA2CY,eAAe,CAC1B,UAAU,CAAC,EAAE,WAAW,EACxB,YAAY,CAAC,EAAE,aAAa,EAC5B,qBAAqB,CAAC,EAAE,aAAa,GACpC,OAAO,CAAC,kBAAkB,CAAC,CAsC7B;IAEY,OAAO,CAClB,UAAU,CAAC,EAAE,WAAW,EACxB,YAAY,CAAC,EAAE,aAAa,EAC5B,qBAAqB,CAAC,EAAE,aAAa,GACpC,OAAO,CAAC,aAAa,CAAC,CAkDxB;CA2TF"}

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

@@ -1,9 +1,9 @@
 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 { FETCH_SERVICE_ID, InstallMethod, KEY_VALUE_SERVICE_ID, PRINTER_SERVICE_ID, SPAWN_SERVICE_ID, SupportedArch, SupportedOs, } from "@flowscripter/dynamic-cli-framework-api";
+import { basename, dirname, join } from "node:path";
+import { FETCH_SERVICE_ID, InstallMethod, KEY_VALUE_SERVICE_ID, PRINTER_SERVICE_ID, RunState, SPAWN_SERVICE_ID, SupportedArch, SupportedOs, } from "@flowscripter/dynamic-cli-framework-api";
 import semver from "semver";
 import getLogger from "../../util/logger.js";
 const logger = getLogger("DefaultUpgradeService");
@@ -38,6 +38,40 @@ export function describeUpgradeCheckResult(result) {
         ? `Upgrade check result: failed - ${result.error.message}`
         : `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(Object.values(RunState).filter((value) => 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) {
+    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;
+    }
+    if (result.exitCode > SIGNAL_EXIT_CODE_BASE) {
+        return RunState.TERMINATED;
+    }
+    return RunState.RUNTIME_ERROR;
+}
 const OS_LABELS = {
     [SupportedOs.LINUX]: "Linux",
     [SupportedOs.MACOS]: "MacOS",
@@ -48,9 +82,11 @@ export default class DefaultUpgradeService {
     #upgradeCheckPromise;
     #config;
     #cliConfig;
+    restartedFromVersion;
     constructor(config, cliConfig) {
         this.#config = config;
         this.#cliConfig = cliConfig;
+        this.restartedFromVersion = process.env[RESTARTED_FROM_VERSION_ENV_VAR] || undefined;
     }
     setContext(context) {
         this.#context = context;
@@ -150,6 +186,61 @@ export default class DefaultUpgradeService {
         const cached = await this.#safeKeyValueCall(() => keyValueService.get(UPGRADE_CHECK_CACHE_KEY));
         return cached;
     }
+    /**
+     * 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).
+     */
+    resolveUpgradedExecutable(installMethod) {
+        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() {
+        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.
+     */
+    async restart(executable, args) {
+        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);
+    }
     detectOs() {
         switch (process.platform) {
             case "linux":
@@ -331,15 +422,17 @@ export default class DefaultUpgradeService {
     // `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) {
-        let realExecutable = process.execPath;
+        return this.#resolveRealExecutable().includes(`/Cellar/${formula}/`);
+    }
+    #resolveRealExecutable() {
         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() {
         if (!this.#spawnService || !this.#config.homebrew) {

package/dist/src/service/upgrade/UpgradeServiceProvider.d.ts

@@ -3,7 +3,7 @@ import type { Context } from "@flowscripter/dynamic-cli-framework-api";
 import type { CLIConfig } from "@flowscripter/dynamic-cli-framework-api";
 import DefaultUpgradeService from "./DefaultUpgradeService.ts";
 import type { UpgradeLocationsConfig } from "./UpgradeLocationsConfig.ts";
-import type { StartupTask } from "@flowscripter/dynamic-cli-framework-api";
+import type { StartupTask, StartupTaskOutcome } from "@flowscripter/dynamic-cli-framework-api";
 /**
  * Build the background {@link StartupTask} which opportunistically refreshes the upgrade-check
  * cache (see {@link DefaultUpgradeService.refreshUpgradeCheckCache}) that the banner task reads
@@ -13,7 +13,7 @@ import type { StartupTask } from "@flowscripter/dynamic-cli-framework-api";
 export declare function createUpgradeCheckStartupTask(upgradeService: DefaultUpgradeService, priority: number): StartupTask;
 /**
  * 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.
  */
@@ -22,7 +22,18 @@ export default class UpgradeServiceProvider implements ServiceProvider {
     #private;
     readonly serviceId: string;
     readonly servicePriority: number;
-    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.
+     */
+    constructor(servicePriority: number, config: UpgradeLocationsConfig, restartAfterAutoUpgrade?: boolean);
+    /**
+     * 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: ReadonlyArray<string>): void;
     get upgradeService(): DefaultUpgradeService | undefined;
     getServiceInfo(cliConfig: CLIConfig): Promise<ServiceInfo>;
     initService(context: Context): Promise<void>;
@@ -31,8 +42,12 @@ 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.
      */
-    runAutoUpgrade(context: Context): Promise<void>;
+    runAutoUpgrade(context: Context): Promise<void | StartupTaskOutcome>;
 }
 //# sourceMappingURL=UpgradeServiceProvider.d.ts.map

package/dist/src/service/upgrade/UpgradeServiceProvider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"UpgradeServiceProvider.d.ts","sourceRoot":"","sources":["../../../../src/service/upgrade/UpgradeServiceProvider.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,yCAAyC,CAAC;AAC5F,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,yCAAyC,CAAC;AACvE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAYzE,OAAO,qBAAqB,MAAM,4BAA4B,CAAC;AAE/D,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,6BAA6B,CAAC;AAE1E,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,yCAAyC,CAAC;AAI3E;;;;;GAKG;AACH,wBAAgB,6BAA6B,CAC3C,cAAc,EAAE,qBAAqB,EACrC,QAAQ,EAAE,MAAM,GACf,WAAW,CASb;AAED;;;;;GAKG;AACH,wBAAgB,4BAA4B,CAC1C,QAAQ,EAAE,sBAAsB,EAChC,QAAQ,EAAE,MAAM,GACf,WAAW,CAOb;AAED,MAAM,CAAC,OAAO,OAAO,sBAAuB,YAAW,eAAe;;IACpE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAsB;IAChD,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IAMjC,YAAmB,eAAe,EAAE,MAAM,EAAE,MAAM,EAAE,sBAAsB,EAGzE;IAED,IAAW,cAAc,IAAI,qBAAqB,GAAG,SAAS,CAE7D;IAEM,cAAc,CAAC,SAAS,EAAE,SAAS,GAAG,OAAO,CAAC,WAAW,CAAC,CAOhE;IAEM,WAAW,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAsBlD;IAED;;;;;;OAMG;IACU,cAAc,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAqE3D;CAoCF"}
+{"version":3,"file":"UpgradeServiceProvider.d.ts","sourceRoot":"","sources":["../../../../src/service/upgrade/UpgradeServiceProvider.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,yCAAyC,CAAC;AAC5F,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,yCAAyC,CAAC;AACvE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAYzE,OAAO,qBAAqB,MAAM,4BAA4B,CAAC;AAE/D,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,6BAA6B,CAAC;AAE1E,OAAO,KAAK,EAAE,WAAW,EAAE,kBAAkB,EAAE,MAAM,yCAAyC,CAAC;AAI/F;;;;;GAKG;AACH,wBAAgB,6BAA6B,CAC3C,cAAc,EAAE,qBAAqB,EACrC,QAAQ,EAAE,MAAM,GACf,WAAW,CASb;AAED;;;;;GAKG;AACH,wBAAgB,4BAA4B,CAC1C,QAAQ,EAAE,sBAAsB,EAChC,QAAQ,EAAE,MAAM,GACf,WAAW,CAOb;AAED,MAAM,CAAC,OAAO,OAAO,sBAAuB,YAAW,eAAe;;IACpE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAsB;IAChD,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IAQjC;;;;;OAKG;IACH,YACE,eAAe,EAAE,MAAM,EACvB,MAAM,EAAE,sBAAsB,EAC9B,uBAAuB,UAAQ,EAKhC;IAED;;;OAGG;IACI,cAAc,CAAC,IAAI,EAAE,aAAa,CAAC,MAAM,CAAC,GAAG,IAAI,CAEvD;IAED,IAAW,cAAc,IAAI,qBAAqB,GAAG,SAAS,CAE7D;IAEM,cAAc,CAAC,SAAS,EAAE,SAAS,GAAG,OAAO,CAAC,WAAW,CAAC,CAOhE;IAEM,WAAW,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAsBlD;IAED;;;;;;;;;;OAUG;IACU,cAAc,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,GAAG,kBAAkB,CAAC,CA4EhF;CA8DF"}

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.1",
   "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.2.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/completion/command/CompletionCompleteSubCommand.ts

@@ -4,7 +4,7 @@ import type { Positional } from "@flowscripter/dynamic-cli-framework-api";
 import type { Context } from "@flowscripter/dynamic-cli-framework-api";
 import { type Values, ValueTypeName } from "@flowscripter/dynamic-cli-framework-api";
 import { COMPLETION_SERVICE_ID, ShellType } from "@flowscripter/dynamic-cli-framework-api";
-import type DefaultCompletionService from "../DefaultCompletionService.ts";
+import type { CompletionService } from "@flowscripter/dynamic-cli-framework-api";
 import { PRINTER_SERVICE_ID } from "@flowscripter/dynamic-cli-framework-api";
 import type { PrinterService } from "@flowscripter/dynamic-cli-framework-api";
 
@@ -33,9 +33,7 @@ export class CompletionCompleteSubCommand implements SubCommand {
   ];
 
   async execute(context: Context, argumentValues: Values): Promise<void> {
-    const completionService = context.getServiceById(
-      COMPLETION_SERVICE_ID,
-    ) as DefaultCompletionService;
+    const completionService = context.getServiceById(COMPLETION_SERVICE_ID) as CompletionService;
     const printerService = context.getServiceById(PRINTER_SERVICE_ID) as PrinterService;
 
     const shellType = argumentValues.shell as ShellType;

package/src/service/completion/command/CompletionIntegrationSubCommand.ts

@@ -5,7 +5,7 @@ import type { Positional } from "@flowscripter/dynamic-cli-framework-api";
 import type { Context } from "@flowscripter/dynamic-cli-framework-api";
 import { type Values, ValueTypeName } from "@flowscripter/dynamic-cli-framework-api";
 import { COMPLETION_SERVICE_ID, ShellType } from "@flowscripter/dynamic-cli-framework-api";
-import type DefaultCompletionService from "../DefaultCompletionService.ts";
+import type { CompletionService } from "@flowscripter/dynamic-cli-framework-api";
 import { Icon, PRINTER_SERVICE_ID } from "@flowscripter/dynamic-cli-framework-api";
 import type { PrinterService } from "@flowscripter/dynamic-cli-framework-api";
 
@@ -33,9 +33,7 @@ export class CompletionIntegrationSubCommand implements SubCommand {
   ];
 
   async execute(context: Context, argumentValues: Values): Promise<void> {
-    const completionService = context.getServiceById(
-      COMPLETION_SERVICE_ID,
-    ) as DefaultCompletionService;
+    const completionService = context.getServiceById(COMPLETION_SERVICE_ID) as CompletionService;
     const printerService = context.getServiceById(PRINTER_SERVICE_ID) as PrinterService;
 
     const shellType = argumentValues.shell as ShellType;

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) {