@flowscripter/dynamic-cli-framework 7.0.11 → 7.1.0

package/dist/src/cli/BaseCLI.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"BaseCLI.d.ts","sourceRoot":"","sources":["../../../src/cli/BaseCLI.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,yCAAyC,CAAC;AACnE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAIzE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,yCAAyC,CAAC;AAGvE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,yCAAyC,CAAC;AAC/E,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAsBzE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,yCAAyC,CAAC;AAS3E,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AACjD,OAAO,KAAK,QAAQ,MAAM,yBAAyB,CAAC;AAGpD,OAAO,KAAK,MAAM,MAAM,uBAAuB,CAAC;AAChD,OAAO,KAAK,SAAS,MAAM,0BAA0B,CAAC;AACtD,OAAO,KAAK,qBAAqB,MAAM,4BAA4B,CAAC;AAqCpE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,MAAM,CAAC,OAAO,OAAO,OAAQ,YAAW,GAAG;;IAazC,YACE,SAAS,EAAE,SAAS,EACpB,oBAAoB,EAAE,cAAc,EACpC,oBAAoB,EAAE,cAAc,EACpC,aAAa,EAAE,OAAO,EACtB,aAAa,EAAE,OAAO,EACtB,cAAc,EAAE,QAAQ,EACxB,cAAc,EAAE,QAAQ,EACxB,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,SAAS,GAAG,SAAS,EAChC,OAAO,CAAC,EAAE,qBAAqB,EAkEhC;IAED;;;;;;;OAOG;IACI,kBAAkB,CAAC,eAAe,EAAE,eAAe,QAEzD;IAED;;;;;;;;OAQG;IACH;;;;;OAKG;IACI,cAAc,CAAC,IAAI,EAAE,WAAW,QAEtC;IAEM,UAAU,CAAC,OAAO,EAAE,OAAO,QAQjC;IAEK,GAAG,CAAC,IAAI,EAAE,aAAa,CAAC,MAAM,CAAC,GAAG,OAAO,CAAC,SAAS,CAAC,CA8PzD;CACF"}
+{"version":3,"file":"BaseCLI.d.ts","sourceRoot":"","sources":["../../../src/cli/BaseCLI.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,yCAAyC,CAAC;AACnE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAIzE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,yCAAyC,CAAC;AAGvE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,yCAAyC,CAAC;AAC/E,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAsBzE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,yCAAyC,CAAC;AAS3E,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AACjD,OAAO,KAAK,QAAQ,MAAM,yBAAyB,CAAC;AAGpD,OAAO,KAAK,MAAM,MAAM,uBAAuB,CAAC;AAChD,OAAO,KAAK,SAAS,MAAM,0BAA0B,CAAC;AACtD,OAAO,KAAK,qBAAqB,MAAM,4BAA4B,CAAC;AAqCpE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,MAAM,CAAC,OAAO,OAAO,OAAQ,YAAW,GAAG;;IAazC,YACE,SAAS,EAAE,SAAS,EACpB,oBAAoB,EAAE,cAAc,EACpC,oBAAoB,EAAE,cAAc,EACpC,aAAa,EAAE,OAAO,EACtB,aAAa,EAAE,OAAO,EACtB,cAAc,EAAE,QAAQ,EACxB,cAAc,EAAE,QAAQ,EACxB,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,SAAS,GAAG,SAAS,EAChC,OAAO,CAAC,EAAE,qBAAqB,EAmEhC;IAED;;;;;;;OAOG;IACI,kBAAkB,CAAC,eAAe,EAAE,eAAe,QAEzD;IAED;;;;;;;;OAQG;IACH;;;;;OAKG;IACI,cAAc,CAAC,IAAI,EAAE,WAAW,QAEtC;IAEM,UAAU,CAAC,OAAO,EAAE,OAAO,QAQjC;IAEK,GAAG,CAAC,IAAI,EAAE,aAAa,CAAC,MAAM,CAAC,GAAG,OAAO,CAAC,SAAS,CAAC,CAoQzD;CACF"}

package/dist/src/cli/BaseCLI.js

@@ -109,6 +109,7 @@ export default class BaseCLI {
             fetchServiceEnabled: false,
             upgradeServiceEnabled: false,
             upgradeLocationsConfig: { supportedPlatforms: [] },
+            restartAfterAutoUpgrade: false,
             pluginServiceEnabled: false,
             pluginServiceRemoteConfig: { name: "", registryUrl: "", packageJsonNamespace: "" },
             pluginServiceLocalConfig: { nodeModulesPath: "", packageJsonNamespace: "" },
@@ -229,7 +230,8 @@ export default class BaseCLI {
         }
         let upgradeServiceProvider;
         if (this.#options.upgradeServiceEnabled) {
-            upgradeServiceProvider = new UpgradeServiceProvider(UPGRADE_SERVICE_PRIORITY, this.#options.upgradeLocationsConfig);
+            upgradeServiceProvider = new UpgradeServiceProvider(UPGRADE_SERVICE_PRIORITY, this.#options.upgradeLocationsConfig, this.#options.restartAfterAutoUpgrade);
+            upgradeServiceProvider.setRestartArgs(args);
             this.addServiceProvider(upgradeServiceProvider);
         }
         if (this.#options.pluginServiceEnabled) {
@@ -285,6 +287,10 @@ export default class BaseCLI {
             this.#commandRegistry.addCommand(new VersionCommand());
             // run...
             const runResult = await run(args, this.#commandRegistry, this.#serviceProviderRegistry, configurationServiceProvider, keyValueServiceProvider, this.#context, 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/dist/src/cli/BaseCLIFeatureOptions.d.ts

@@ -12,6 +12,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/dist/src/cli/BaseCLIFeatureOptions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"BaseCLIFeatureOptions.d.ts","sourceRoot":"","sources":["../../../src/cli/BaseCLIFeatureOptions.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,8CAA8C,CAAC;AAC3F,OAAO,KAAK,EACV,2BAA2B,EAC3B,yBAAyB,EAC1B,MAAM,wCAAwC,CAAC;AAEhD,MAAM,CAAC,OAAO,WAAW,qBAAqB;IAC5C,QAAQ,CAAC,wBAAwB,CAAC,EAAE,OAAO,CAAC;IAC5C,QAAQ,CAAC,qBAAqB,CAAC,EAAE,OAAO,CAAC;IACzC,QAAQ,CAAC,sBAAsB,CAAC,EAAE,OAAO,CAAC;IAC1C,QAAQ,CAAC,oBAAoB,CAAC,EAAE,OAAO,CAAC;IACxC,QAAQ,CAAC,8BAA8B,CAAC,EAAE,OAAO,CAAC;IAClD,QAAQ,CAAC,wBAAwB,CAAC,EAAE,OAAO,CAAC;IAC5C,QAAQ,CAAC,0BAA0B,CAAC,EAAE,OAAO,CAAC;IAC9C,QAAQ,CAAC,mBAAmB,CAAC,EAAE,OAAO,CAAC;IACvC,QAAQ,CAAC,mBAAmB,CAAC,EAAE,OAAO,CAAC;IACvC,QAAQ,CAAC,qBAAqB,CAAC,EAAE,OAAO,CAAC;IACzC,QAAQ,CAAC,sBAAsB,CAAC,EAAE,sBAAsB,CAAC;IACzD,QAAQ,CAAC,oBAAoB,CAAC,EAAE,OAAO,CAAC;IACxC,QAAQ,CAAC,yBAAyB,CAAC,EAAE,2BAA2B,CAAC;IACjE,QAAQ,CAAC,wBAAwB,CAAC,EAAE,yBAAyB,CAAC;IAC9D,QAAQ,CAAC,mBAAmB,CAAC,EAAE,OAAO,CAAC;IACvC,QAAQ,CAAC,gBAAgB,CAAC,EAAE,OAAO,CAAC;CACrC"}
+{"version":3,"file":"BaseCLIFeatureOptions.d.ts","sourceRoot":"","sources":["../../../src/cli/BaseCLIFeatureOptions.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,8CAA8C,CAAC;AAC3F,OAAO,KAAK,EACV,2BAA2B,EAC3B,yBAAyB,EAC1B,MAAM,wCAAwC,CAAC;AAEhD,MAAM,CAAC,OAAO,WAAW,qBAAqB;IAC5C,QAAQ,CAAC,wBAAwB,CAAC,EAAE,OAAO,CAAC;IAC5C,QAAQ,CAAC,qBAAqB,CAAC,EAAE,OAAO,CAAC;IACzC,QAAQ,CAAC,sBAAsB,CAAC,EAAE,OAAO,CAAC;IAC1C,QAAQ,CAAC,oBAAoB,CAAC,EAAE,OAAO,CAAC;IACxC,QAAQ,CAAC,8BAA8B,CAAC,EAAE,OAAO,CAAC;IAClD,QAAQ,CAAC,wBAAwB,CAAC,EAAE,OAAO,CAAC;IAC5C,QAAQ,CAAC,0BAA0B,CAAC,EAAE,OAAO,CAAC;IAC9C,QAAQ,CAAC,mBAAmB,CAAC,EAAE,OAAO,CAAC;IACvC,QAAQ,CAAC,mBAAmB,CAAC,EAAE,OAAO,CAAC;IACvC,QAAQ,CAAC,qBAAqB,CAAC,EAAE,OAAO,CAAC;IACzC,QAAQ,CAAC,sBAAsB,CAAC,EAAE,sBAAsB,CAAC;IACzD;;;OAGG;IACH,QAAQ,CAAC,uBAAuB,CAAC,EAAE,OAAO,CAAC;IAC3C,QAAQ,CAAC,oBAAoB,CAAC,EAAE,OAAO,CAAC;IACxC,QAAQ,CAAC,yBAAyB,CAAC,EAAE,2BAA2B,CAAC;IACjE,QAAQ,CAAC,wBAAwB,CAAC,EAAE,yBAAyB,CAAC;IAC9D,QAAQ,CAAC,mBAAmB,CAAC,EAAE,OAAO,CAAC;IACvC,QAAQ,CAAC,gBAAgB,CAAC,EAAE,OAAO,CAAC;CACrC"}

package/dist/src/cli/DefaultRuntimeCLI.js

@@ -39,7 +39,7 @@ export default class DefaultRuntimeCLI extends BaseCLI {
         logger.debug(() => `keyReader constructed: ${keyReader !== undefined}`);
         const promptingEnabled = stdinIsTty && stderrIsTty;
         logger.debug(() => `promptingEnabled default: ${promptingEnabled}`);
-        super(cliConfig, Writable.toWeb(process.stdout), Writable.toWeb(process.stderr), supportsColor.stdout !== false, supportsColor.stderr !== false, stdoutTerminal, stderrTerminal, new TtyStyler(colorLevel, supportsHyperlinks(process.stderr)), keyReader, { promptingEnabled, ...options });
+        super(cliConfig, Writable.toWeb(process.stdout), Writable.toWeb(process.stderr), supportsColor.stdout !== false, supportsColor.stderr !== false, stdoutTerminal, stderrTerminal, new TtyStyler(colorLevel, supportsHyperlinks(process.stderr)), keyReader, { promptingEnabled, restartAfterAutoUpgrade: true, ...options });
     }
     async run() {
         const runResult = await super.run(process.argv.slice(2));

package/dist/src/runtime/runner.d.ts

@@ -6,6 +6,13 @@ import type ConfigurationServiceProvider from "../service/configuration/Configur
 import type KeyValueServiceProvider from "../service/configuration/KeyValueServiceProvider.ts";
 import type { Command } from "@flowscripter/dynamic-cli-framework-api";
 import DefaultStartupService from "../service/startup/DefaultStartupService.ts";
+/**
+ * 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;
+};
 /**
  * Scan arguments and execute the parsed {@link Command} clauses with provided argument values
  * using the provided {@link Context}.
@@ -34,6 +41,8 @@ import DefaultStartupService from "../service/startup/DefaultStartupService.ts";
  *    - 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
@@ -80,5 +89,5 @@ import DefaultStartupService from "../service/startup/DefaultStartupService.ts";
  * @param defaultCommand optional {@link SubCommand} or {@link GlobalCommand} implementation to attempt to parse arguments for and execute if
  * no non-modifier {@link Command} name is identified in the provided arguments.
  */
-export declare function run(args: ReadonlyArray<string>, commandRegistry: CommandRegistry, serviceProviderRegistry: ServiceProviderRegistry, configurationServiceProvider: ConfigurationServiceProvider | undefined, keyValueServiceProvider: KeyValueServiceProvider | undefined, context: Context, defaultCommand?: Command, startupService?: DefaultStartupService): Promise<RunResult>;
+export declare function run(args: ReadonlyArray<string>, commandRegistry: CommandRegistry, serviceProviderRegistry: ServiceProviderRegistry, configurationServiceProvider: ConfigurationServiceProvider | undefined, keyValueServiceProvider: KeyValueServiceProvider | undefined, context: Context, defaultCommand?: Command, startupService?: DefaultStartupService): Promise<RunnerResult>;
 //# sourceMappingURL=runner.d.ts.map

package/dist/src/runtime/runner.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"runner.d.ts","sourceRoot":"","sources":["../../../src/runtime/runner.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,yCAAyC,CAAC;AACvE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAEzE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,yCAAyC,CAAC;AAiB/E,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,yCAAyC,CAAC;AAEvF,OAAO,KAAK,4BAA4B,MAAM,0DAA0D,CAAC;AACzG,OAAO,KAAK,uBAAuB,MAAM,qDAAqD,CAAC;AAK/F,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,yCAAyC,CAAC;AAKvE,OAAO,qBAAqB,MAAM,6CAA6C,CAAC;AAqfhF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyEG;AACH,wBAAsB,GAAG,CACvB,IAAI,EAAE,aAAa,CAAC,MAAM,CAAC,EAC3B,eAAe,EAAE,eAAe,EAChC,uBAAuB,EAAE,uBAAuB,EAChD,4BAA4B,EAAE,4BAA4B,GAAG,SAAS,EACtE,uBAAuB,EAAE,uBAAuB,GAAG,SAAS,EAC5D,OAAO,EAAE,OAAO,EAChB,cAAc,CAAC,EAAE,OAAO,EACxB,cAAc,CAAC,EAAE,qBAAqB,GACrC,OAAO,CAAC,SAAS,CAAC,CA6JpB"}
+{"version":3,"file":"runner.d.ts","sourceRoot":"","sources":["../../../src/runtime/runner.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,yCAAyC,CAAC;AACvE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAEzE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,yCAAyC,CAAC;AAiB/E,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,yCAAyC,CAAC;AAEvF,OAAO,KAAK,4BAA4B,MAAM,0DAA0D,CAAC;AACzG,OAAO,KAAK,uBAAuB,MAAM,qDAAqD,CAAC;AAK/F,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,yCAAyC,CAAC;AAKvE,OAAO,qBAAqB,MAAM,6CAA6C,CAAC;AAKhF;;;GAGG;AACH,MAAM,MAAM,YAAY,GAAG,SAAS,GAAG;IAAE,QAAQ,CAAC,aAAa,CAAC,EAAE,IAAI,CAAA;CAAE,CAAC;AAkfzE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2EG;AACH,wBAAsB,GAAG,CACvB,IAAI,EAAE,aAAa,CAAC,MAAM,CAAC,EAC3B,eAAe,EAAE,eAAe,EAChC,uBAAuB,EAAE,uBAAuB,EAChD,4BAA4B,EAAE,4BAA4B,GAAG,SAAS,EACtE,uBAAuB,EAAE,uBAAuB,GAAG,SAAS,EAC5D,OAAO,EAAE,OAAO,EAChB,cAAc,CAAC,EAAE,OAAO,EACxB,cAAc,CAAC,EAAE,qBAAqB,GACrC,OAAO,CAAC,YAAY,CAAC,CAoKvB"}

package/dist/src/runtime/runner.js

@@ -389,6 +389,8 @@ async function findAndExecuteDefaultNonModifierCommand(availableArgs, unusedArgs
  *    - 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
@@ -477,7 +479,11 @@ export async function run(args, commandRegistry, serviceProviderRegistry, config
             ? keyValueServiceProvider.getContextForScope(context, "service", task.id)
             : 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) => {

package/dist/src/service/configuration/DefaultKeyValueService.d.ts

@@ -7,8 +7,16 @@ import type DefaultSecretService from "./DefaultSecretService.ts";
  */
 export default class DefaultKeyValueService implements KeyValueService {
     #private;
-    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>);
     isDirty(): boolean;
+    markClean(): void;
+    flush(): Promise<void>;
     get<T extends ValueNode = ValueNode>(key: string): Promise<T>;
     has(key: string): Promise<boolean>;
     set(key: string, value: SettableValueNode): Promise<void>;

package/dist/src/service/configuration/DefaultKeyValueService.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"DefaultKeyValueService.d.ts","sourceRoot":"","sources":["../../../../src/service/configuration/DefaultKeyValueService.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,SAAS,EACT,eAAe,EACf,iBAAiB,EAClB,MAAM,yCAAyC,CAAC;AAEjD,OAAO,KAAK,oBAAoB,MAAM,2BAA2B,CAAC;AAGlE;;;;GAIG;AACH,MAAM,CAAC,OAAO,OAAO,sBAAuB,YAAW,eAAe;;IAKpE,YAAY,YAAY,EAAE,GAAG,CAAC,MAAM,EAAE,SAAS,CAAC,EAAE,aAAa,CAAC,EAAE,oBAAoB,EAGrF;IAEM,OAAO,IAAI,OAAO,CAExB;IAEY,GAAG,CAAC,CAAC,SAAS,SAAS,GAAG,SAAS,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC,CAsBzE;IAEM,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAExC;IAEY,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,CAGrE;IAsCY,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAO9C;CAsBF"}
+{"version":3,"file":"DefaultKeyValueService.d.ts","sourceRoot":"","sources":["../../../../src/service/configuration/DefaultKeyValueService.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,SAAS,EACT,eAAe,EACf,iBAAiB,EAClB,MAAM,yCAAyC,CAAC;AAEjD,OAAO,KAAK,oBAAoB,MAAM,2BAA2B,CAAC;AAGlE;;;;GAIG;AACH,MAAM,CAAC,OAAO,OAAO,sBAAuB,YAAW,eAAe;;IAMpE;;;;;OAKG;IACH,YACE,YAAY,EAAE,GAAG,CAAC,MAAM,EAAE,SAAS,CAAC,EACpC,aAAa,CAAC,EAAE,oBAAoB,EACpC,cAAc,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,EAKrC;IAEM,OAAO,IAAI,OAAO,CAExB;IAEM,SAAS,IAAI,IAAI,CAEvB;IAEY,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAGlC;IAEY,GAAG,CAAC,CAAC,SAAS,SAAS,GAAG,SAAS,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC,CAsBzE;IAEM,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAExC;IAEY,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,CAGrE;IAsCY,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAO9C;CAsBF"}

package/dist/src/service/configuration/DefaultKeyValueService.js

@@ -9,13 +9,28 @@ export default class DefaultKeyValueService {
     #keyValueData;
     #dirty = false;
     #secretService;
-    constructor(keyValueData, secretService) {
+    #flushToStorage;
+    /**
+     * @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, secretService, flushToStorage) {
         this.#keyValueData = keyValueData;
         this.#secretService = secretService;
+        this.#flushToStorage = flushToStorage;
     }
     isDirty() {
         return this.#dirty;
     }
+    markClean() {
+        this.#dirty = false;
+    }
+    async flush() {
+        await this.#flushToStorage?.();
+        this.#dirty = false;
+    }
     async get(key) {
         const value = this.#keyValueData.get(key);
         if (value === undefined) {

package/dist/src/service/configuration/KeyValueServiceProvider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"KeyValueServiceProvider.d.ts","sourceRoot":"","sources":["../../../../src/service/configuration/KeyValueServiceProvider.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;AACzE,OAAO,KAAK,EACV,eAAe,EAGhB,MAAM,yCAAyC,CAAC;AAIjD,OAAO,KAAK,4BAA4B,MAAM,mCAAmC,CAAC;AAClF,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,mCAAmC,CAAC;AAgClF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwDG;AACH,MAAM,CAAC,OAAO,OAAO,uBAAwB,YAAW,eAAe;;IACrE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAwB;IAClD,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IAIjC,SAAgB,sBAAsB,EAAE,OAAO,CAAC;IAChD,SAAgB,oBAAoB,EAAE,OAAO,CAAC;IAW9C;;;;;;;;OAQG;IACH,YACE,eAAe,EAAE,MAAM,EACvB,4BAA4B,EAAE,4BAA4B,EAC1D,sBAAsB,UAAQ,EAC9B,oBAAoB,UAAQ,EAY7B;IAEM,cAAc,CAAC,SAAS,EAAE,SAAS,GAAG,OAAO,CAAC,WAAW,CAAC,CAUhE;IAED;;;;;;;;;;OAUG;IACI,wBAAwB,CAC7B,SAAS,EAAE,wBAAwB,EACnC,QAAQ,EAAE,MAAM,GACf,eAAe,CAsBjB;IAED;;;;;;;;;;;;;;OAcG;IACI,kBAAkB,CACvB,OAAO,EAAE,OAAO,EAChB,SAAS,EAAE,wBAAwB,EACnC,QAAQ,EAAE,MAAM,GACf,OAAO,CAaT;IAeY,WAAW,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CASxD;CACF"}
+{"version":3,"file":"KeyValueServiceProvider.d.ts","sourceRoot":"","sources":["../../../../src/service/configuration/KeyValueServiceProvider.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;AACzE,OAAO,KAAK,EACV,eAAe,EAGhB,MAAM,yCAAyC,CAAC;AAIjD,OAAO,KAAK,4BAA4B,MAAM,mCAAmC,CAAC;AAClF,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,mCAAmC,CAAC;AAoClF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwDG;AACH,MAAM,CAAC,OAAO,OAAO,uBAAwB,YAAW,eAAe;;IACrE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAwB;IAClD,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IAIjC,SAAgB,sBAAsB,EAAE,OAAO,CAAC;IAChD,SAAgB,oBAAoB,EAAE,OAAO,CAAC;IAW9C;;;;;;;;OAQG;IACH,YACE,eAAe,EAAE,MAAM,EACvB,4BAA4B,EAAE,4BAA4B,EAC1D,sBAAsB,UAAQ,EAC9B,oBAAoB,UAAQ,EAY7B;IAEM,cAAc,CAAC,SAAS,EAAE,SAAS,GAAG,OAAO,CAAC,WAAW,CAAC,CAUhE;IAED;;;;;;;;;;OAUG;IACI,wBAAwB,CAC7B,SAAS,EAAE,wBAAwB,EACnC,QAAQ,EAAE,MAAM,GACf,eAAe,CAwBjB;IAED;;;;;;;;;;;;;;OAcG;IACI,kBAAkB,CACvB,OAAO,EAAE,OAAO,EAChB,SAAS,EAAE,wBAAwB,EACnC,QAAQ,EAAE,MAAM,GACf,OAAO,CAaT;IAqBY,WAAW,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CASxD;CACF"}

package/dist/src/service/configuration/KeyValueServiceProvider.js

@@ -22,6 +22,9 @@ class UnreachableKeyValueService {
     delete() {
         return Promise.reject(new Error(UnreachableKeyValueService.#message));
     }
+    flush() {
+        return Promise.reject(new Error(UnreachableKeyValueService.#message));
+    }
     static #message = "KeyValueService accessed without a resolved scope - this should be unreachable";
 }
 /**
@@ -151,7 +154,7 @@ export default class KeyValueServiceProvider {
         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;
     }
@@ -184,15 +187,19 @@ export default class KeyValueServiceProvider {
     }
     /**
      * 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() {
-        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();
+        }
     }
     async initService(context) {
         if (this.keyValueServiceEnabled || this.secretServiceEnabled) {

package/dist/src/service/shutdown/ShutdownServiceProvider.js

@@ -1,6 +1,6 @@
 import process from "node:process";
 import DefaultShutdownService from "./DefaultShutdownService.js";
-import { SHUTDOWN_SERVICE_ID } from "@flowscripter/dynamic-cli-framework-api";
+import { RunState, SHUTDOWN_SERVICE_ID } from "@flowscripter/dynamic-cli-framework-api";
 import getLogger from "../../util/logger.js";
 import { shutdownState } from "./ShutdownState.js";
 const logger = getLogger("ShutdownServiceProvider");
@@ -29,7 +29,7 @@ export default class ShutdownServiceProvider {
         shutdownState.interruptCount++;
         if (!shutdownState.longRunningMode || shutdownState.interruptCount >= 3) {
             ShutdownServiceProvider.shutdown().then(() => {
-                process.exit(130);
+                process.exit(RunState.INTERRUPTED);
             });
         }
         else {
@@ -38,7 +38,7 @@ export default class ShutdownServiceProvider {
     }
     static onTerminate() {
         ShutdownServiceProvider.shutdown().then(() => {
-            process.exit(143);
+            process.exit(RunState.TERMINATED);
         });
     }
     static async shutdown() {

package/dist/src/service/spawn/DefaultSpawnService.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"DefaultSpawnService.d.ts","sourceRoot":"","sources":["../../../../src/service/spawn/DefaultSpawnService.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,OAAO,EAGP,YAAY,EACZ,WAAW,EACX,YAAY,EACb,MAAM,yCAAyC,CAAC;AASjD;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,aAAa,CAAC,MAAM,CAAC,GAAG,MAAM,EAAE,CAa3E;AAED,MAAM,CAAC,OAAO,OAAO,mBAAoB,YAAW,YAAY;;IAGvD,UAAU,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAExC;IA+CY,KAAK,CAChB,OAAO,EAAE,aAAa,CAAC,MAAM,CAAC,EAC9B,OAAO,GAAE,YAAiB,GACzB,OAAO,CAAC,WAAW,CAAC,CA0FtB;CACF"}
+{"version":3,"file":"DefaultSpawnService.d.ts","sourceRoot":"","sources":["../../../../src/service/spawn/DefaultSpawnService.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,OAAO,EAGP,YAAY,EACZ,WAAW,EACX,YAAY,EACb,MAAM,yCAAyC,CAAC;AASjD;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,aAAa,CAAC,MAAM,CAAC,GAAG,MAAM,EAAE,CAa3E;AAED,MAAM,CAAC,OAAO,OAAO,mBAAoB,YAAW,YAAY;;IAGvD,UAAU,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAExC;IA+CY,KAAK,CAChB,OAAO,EAAE,aAAa,CAAC,MAAM,CAAC,EAC9B,OAAO,GAAE,YAAiB,GACzB,OAAO,CAAC,WAAW,CAAC,CA2FtB;CACF"}

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

@@ -80,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",

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"}