@flowscripter/dynamic-cli-framework 7.0.10 → 7.1.0

package/dist/src/service/spawn/DefaultSpawnService.js

@@ -1,6 +1,7 @@
 import process from "node:process";
 import { PRINTER_SERVICE_ID, SHUTDOWN_SERVICE_ID } from "@flowscripter/dynamic-cli-framework-api";
 import getLogger from "../../util/logger.js";
+import { CLEANUP_SHUTDOWN_TASK_PRIORITY } from "../../runtime/lifecycle/priorities.js";
 const logger = getLogger("DefaultSpawnService");
 const SHUTDOWN_GRACE_PERIOD_MS = 5000;
 /**
@@ -79,6 +80,7 @@ export default class DefaultSpawnService {
         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",
@@ -94,7 +96,7 @@ export default class DefaultSpawnService {
         }
         shutdownService.registerTask({
             id: `spawn:${command.join(" ")}`,
-            priority: 0,
+            priority: CLEANUP_SHUTDOWN_TASK_PRIORITY,
             run: async () => {
                 if (settled) {
                     return;

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
@@ -11,13 +11,43 @@ import type { StartupTask } from "@flowscripter/dynamic-cli-framework-api";
  * regular blocking init task) so it can run in `"background"` mode.
  */
 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, 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.
+ */
+export declare function createAutoUpgradeStartupTask(provider: UpgradeServiceProvider, priority: number): StartupTask;
 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>;
+    /**
+     * Offer to enable automatic upgrades (storing the answer as `upgrade-status` in the upgrade
+     * 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 | 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,MAAM,CAAC,OAAO,OAAO,sBAAuB,YAAW,eAAe;;IACpE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAsB;IAChD,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IAKjC,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;IAEY,WAAW,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAqFxD;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

@@ -24,15 +24,46 @@ 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, 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.
+ */
+export function createAutoUpgradeStartupTask(provider, priority) {
+    return {
+        id: `${UPGRADE_SERVICE_ID}-auto-upgrade`,
+        priority,
+        mode: "blocking",
+        run: (context) => provider.runAutoUpgrade(context),
+    };
+}
 export default class UpgradeServiceProvider {
     serviceId = UPGRADE_SERVICE_ID;
     servicePriority;
     #config;
     #upgradeService;
     #cliConfig;
-    constructor(servicePriority, config) {
+    #keyValueService;
+    #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;
@@ -45,9 +76,8 @@ export default class UpgradeServiceProvider {
             commands: [new UpgradeSubCommand()],
         });
     }
-    async initService(context) {
+    initService(context) {
         const upgradeService = this.#upgradeService;
-        const cliConfig = this.#cliConfig;
         const spawnService = context.doesServiceExist(SPAWN_SERVICE_ID)
             ? context.getServiceById(SPAWN_SERVICE_ID)
             : undefined;
@@ -60,10 +90,33 @@ export default class UpgradeServiceProvider {
         if (fetchService === undefined) {
             logger.debug(() => "FetchService not available, upgrade version checks will be unavailable");
         }
-        const keyValueService = context.doesServiceExist(KEY_VALUE_SERVICE_ID)
+        // the KeyValueService from this context is bound to the upgrade service's own scope, so it is
+        // kept for runAutoUpgrade(), whose task context is scoped to the task ID instead
+        this.#keyValueService = context.doesServiceExist(KEY_VALUE_SERVICE_ID)
             ? context.getServiceById(KEY_VALUE_SERVICE_ID)
             : undefined;
         upgradeService.setContext(context);
+        return Promise.resolve();
+    }
+    /**
+     * Offer to enable automatic upgrades (storing the answer as `upgrade-status` in the upgrade
+     * 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;
@@ -79,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);
@@ -121,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") {
@@ -134,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;
             }
-            const printerService = context.getServiceById(PRINTER_SERVICE_ID);
-            if (upgradeResult.ok) {
-                await printerService.info(`${cliConfig.name} upgraded (${upgradeResult.oldVersion} -> ${upgradeResult.newVersion})\n`, Icon.SUCCESS);
+            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;
             }
-            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

@@ -1,15 +1,15 @@
 import type { StartupTask } from "@flowscripter/dynamic-cli-framework-api";
 export declare const BANNER_STARTUP_TASK_ID = "@flowscripter/dynamic-cli-framework/banner-startup-task";
 /**
- * Build the ascii banner {@link StartupTask}, replacing the old `BannerServiceProvider`.
+ * Build the ascii banner {@link StartupTask}.
  *
  * A consumer opts in by passing the result of this function in the `serviceProviders` array
  * argument of {@link launchMultiCommandCLI}/{@link launchSingleCommandCLI} (or via
- * `BaseCLI.addStartupTask`), the same way `new BannerServiceProvider(priority)` used to be passed
- * in that array - there's no default/automatic banner registration.
+ * `BaseCLI.addStartupTask`) - there's no default/automatic banner registration.
  *
- * @param priority the priority of the task (higher runs earlier - the same semantics
- * `BannerServiceProvider.servicePriority` had).
+ * @param priority the priority of the task (higher runs earlier). It must be above
+ * `AUTO_UPGRADE_STARTUP_TASK_PRIORITY` (10) for the banner to print before the automatic upgrade
+ * prompt and upgrade.
  * @param fontName an optional [FIGlet](http://www.figlet.org) font name to use for the banner,
  * defaults to "standard".
  */

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,17 +1,16 @@
 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";
 /**
- * Build the ascii banner {@link StartupTask}, replacing the old `BannerServiceProvider`.
+ * Build the ascii banner {@link StartupTask}.
  *
  * A consumer opts in by passing the result of this function in the `serviceProviders` array
  * argument of {@link launchMultiCommandCLI}/{@link launchSingleCommandCLI} (or via
- * `BaseCLI.addStartupTask`), the same way `new BannerServiceProvider(priority)` used to be passed
- * in that array - there's no default/automatic banner registration.
+ * `BaseCLI.addStartupTask`) - there's no default/automatic banner registration.
  *
- * @param priority the priority of the task (higher runs earlier - the same semantics
- * `BannerServiceProvider.servicePriority` had).
+ * @param priority the priority of the task (higher runs earlier). It must be above
+ * `AUTO_UPGRADE_STARTUP_TASK_PRIORITY` (10) for the banner to print before the automatic upgrade
+ * prompt and upgrade.
  * @param fontName an optional [FIGlet](http://www.figlet.org) font name to use for the banner,
  * defaults to "standard".
  */
@@ -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/index.ts

@@ -207,6 +207,26 @@ export { default as PluginServiceProvider } from "./src/service/plugin/PluginSer
 
 // Core CLI
 export { default as BaseCLI } from "./src/cli/BaseCLI.ts";
+export {
+  SHUTDOWN_SERVICE_PRIORITY,
+  STARTUP_SERVICE_PRIORITY,
+  CONFIGURATION_SERVICE_PRIORITY,
+  KEY_VALUE_SERVICE_PRIORITY,
+  PRINTER_SERVICE_PRIORITY,
+  PROMPTER_SERVICE_PRIORITY,
+  TABLE_GENERATOR_SERVICE_PRIORITY,
+  ARGUMENT_PROMPTER_SERVICE_PRIORITY,
+  SPAWN_SERVICE_PRIORITY,
+  FETCH_SERVICE_PRIORITY,
+  UPGRADE_SERVICE_PRIORITY,
+  UPGRADE_CHECK_STARTUP_TASK_PRIORITY,
+  IMAGE_PRINTER_SERVICE_PRIORITY,
+  PLUGIN_SERVICE_PRIORITY,
+  AUTO_UPGRADE_STARTUP_TASK_PRIORITY,
+  COMPLETION_SERVICE_PRIORITY,
+  CLEANUP_SHUTDOWN_TASK_PRIORITY,
+  KEY_VALUE_FLUSH_SHUTDOWN_TASK_PRIORITY,
+} from "./src/runtime/lifecycle/priorities.ts";
 export { default as DefaultRuntimeCLI } from "./src/cli/DefaultRuntimeCLI.ts";
 
 // Terminal API

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flowscripter/dynamic-cli-framework",
-  "version": "7.0.10",
+  "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",