@flowscripter/dynamic-cli-framework 7.0.10 → 7.1.0

package/src/service/upgrade/DefaultUpgradeService.ts

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

package/src/service/upgrade/UpgradeServiceProvider.ts

@@ -16,7 +16,7 @@ import DefaultUpgradeService from "./DefaultUpgradeService.ts";
 import { UpgradeSubCommand } from "./command/UpgradeSubCommand.ts";
 import type { UpgradeLocationsConfig } from "./UpgradeLocationsConfig.ts";
 import getLogger from "../../util/logger.ts";
-import type { StartupTask } from "@flowscripter/dynamic-cli-framework-api";
+import type { StartupTask, StartupTaskOutcome } from "@flowscripter/dynamic-cli-framework-api";
 
 const logger = getLogger("UpgradeServiceProvider");
 
@@ -40,16 +40,56 @@ export function createUpgradeCheckStartupTask(
   };
 }
 
+/**
+ * Build the blocking {@link StartupTask} which offers to enable automatic upgrades and, when they
+ * are enabled, checks for and installs a newer version, 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: UpgradeServiceProvider,
+  priority: number,
+): StartupTask {
+  return {
+    id: `${UPGRADE_SERVICE_ID}-auto-upgrade`,
+    priority,
+    mode: "blocking",
+    run: (context: Context) => provider.runAutoUpgrade(context),
+  };
+}
+
 export default class UpgradeServiceProvider implements ServiceProvider {
   readonly serviceId: string = UPGRADE_SERVICE_ID;
   readonly servicePriority: number;
   readonly #config: UpgradeLocationsConfig;
   #upgradeService: DefaultUpgradeService | undefined;
   #cliConfig: CLIConfig | undefined;
+  #keyValueService: KeyValueService | undefined;
+  readonly #restartAfterAutoUpgrade: boolean;
+  #restartArgs: ReadonlyArray<string> = [];
 
-  public constructor(servicePriority: number, config: UpgradeLocationsConfig) {
+  /**
+   * @param servicePriority the priority of the service.
+   * @param config the upgrade locations.
+   * @param restartAfterAutoUpgrade whether to run the upgraded executable, with the arguments from
+   * {@link setRestartArgs}, after a successful automatic upgrade and end the run with its result.
+   */
+  public constructor(
+    servicePriority: number,
+    config: UpgradeLocationsConfig,
+    restartAfterAutoUpgrade = false,
+  ) {
     this.servicePriority = servicePriority;
     this.#config = config;
+    this.#restartAfterAutoUpgrade = restartAfterAutoUpgrade;
+  }
+
+  /**
+   * Set the CLI arguments to run the upgraded executable with when restarting after an automatic
+   * upgrade. These are kept internal to the framework and never exposed to startup tasks.
+   */
+  public setRestartArgs(args: ReadonlyArray<string>): void {
+    this.#restartArgs = args;
   }
 
   public get upgradeService(): DefaultUpgradeService | undefined {
@@ -65,9 +105,8 @@ export default class UpgradeServiceProvider implements ServiceProvider {
     });
   }
 
-  public async initService(context: Context): Promise<void> {
+  public initService(context: Context): Promise<void> {
     const upgradeService = this.#upgradeService!;
-    const cliConfig = this.#cliConfig!;
 
     const spawnService = context.doesServiceExist(SPAWN_SERVICE_ID)
       ? (context.getServiceById(SPAWN_SERVICE_ID) as SpawnService)
@@ -81,10 +120,38 @@ export default class UpgradeServiceProvider implements ServiceProvider {
     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) as KeyValueService)
       : 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.
+   */
+  public async runAutoUpgrade(context: Context): Promise<void | StartupTaskOutcome> {
+    const upgradeService = this.#upgradeService!;
+    const cliConfig = this.#cliConfig!;
+    const keyValueService = this.#keyValueService;
+
+    if (upgradeService.restartedFromVersion !== undefined) {
+      logger.debug(
+        () =>
+          `Restarted from version ${upgradeService.restartedFromVersion}, skipping auto-upgrade`,
+      );
+      return;
+    }
 
     if (!context.doesServiceExist(PROMPTER_SERVICE_ID)) {
       logger.debug(() => "PrompterService not available, skipping auto-upgrade");
@@ -102,8 +169,7 @@ export default class UpgradeServiceProvider implements ServiceProvider {
         return;
       }
       if (status === "enabled") {
-        await this.#checkAndUpgrade(context, upgradeService, cliConfig);
-        return;
+        return this.#checkAndUpgrade(context, upgradeService, cliConfig, keyValueService);
       }
     }
 
@@ -149,14 +215,15 @@ export default class UpgradeServiceProvider implements ServiceProvider {
     }
 
     await keyValueService.set("upgrade-status", "enabled");
-    await this.#checkAndUpgrade(context, upgradeService, cliConfig);
+    return this.#checkAndUpgrade(context, upgradeService, cliConfig, keyValueService);
   }
 
   async #checkAndUpgrade(
     context: Context,
     upgradeService: DefaultUpgradeService,
     cliConfig: CLIConfig,
-  ): Promise<void> {
+    keyValueService: KeyValueService,
+  ): Promise<void | StartupTaskOutcome> {
     try {
       const checkResult = await upgradeService.getUpgradeCheckResult();
       if (checkResult.status === "failed") {
@@ -167,21 +234,46 @@ export default class UpgradeServiceProvider implements ServiceProvider {
         return;
       }
       const upgradeResult = await upgradeService.upgrade();
-      if (!context.doesServiceExist(PRINTER_SERVICE_ID)) {
-        return;
-      }
-      const printerService = context.getServiceById(PRINTER_SERVICE_ID) as PrinterService;
-      if (upgradeResult.ok) {
-        await printerService.info(
-          `${cliConfig.name} upgraded (${upgradeResult.oldVersion} -> ${upgradeResult.newVersion})\n`,
-          Icon.SUCCESS,
-        );
-      } else {
-        await printerService.error(
+      const printerService = context.doesServiceExist(PRINTER_SERVICE_ID)
+        ? (context.getServiceById(PRINTER_SERVICE_ID) as PrinterService)
+        : undefined;
+      if (!upgradeResult.ok) {
+        await printerService?.error(
           `Auto-upgrade failed: ${upgradeResult.error?.message ?? "unknown error"}\n`,
           Icon.FAILURE,
         );
+        return;
+      }
+      await printerService?.info(
+        `${cliConfig.name} upgraded (${upgradeResult.oldVersion} -> ${upgradeResult.newVersion})\n`,
+        Icon.SUCCESS,
+      );
+      if (!this.#restartAfterAutoUpgrade) {
+        return;
+      }
+
+      const executable = upgradeService.resolveUpgradedExecutable(checkResult.installMethod);
+      if (executable === undefined) {
+        await printerService?.info(
+          `Restart ${cliConfig.name} to use ${upgradeResult.newVersion}\n`,
+          Icon.INFORMATION,
+        );
+        return;
+      }
+
+      // the cache write from the background upgrade check lands before the flush, so the shutdown
+      // flush has nothing left to write over the restarted process's configuration
+      await upgradeService.refreshUpgradeCheckCache();
+      // written now so the restarted process sees the stored upgrade-status
+      await keyValueService.flush();
+      const runState = await upgradeService.restart(executable, this.#restartArgs);
+      if (runState !== undefined) {
+        return { exitRequest: { runState } };
       }
+      await printerService?.warn(
+        `${cliConfig.name} upgraded to ${upgradeResult.newVersion}; restart it to use the new version\n`,
+        Icon.ALERT,
+      );
     } catch (error) {
       logger.debug(() => `Auto-upgrade check failed: ${error}`);
     }

package/src/service/upgrade/command/UpgradeSubCommand.ts

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

package/src/startup/banner/bannerStartupTask.ts

@@ -7,21 +7,21 @@ import {
 } from "@flowscripter/dynamic-cli-framework-api";
 import type { AsciiBannerGeneratorService } from "@flowscripter/dynamic-cli-framework-api";
 import type { ConfigurationService } from "@flowscripter/dynamic-cli-framework-api";
-import DefaultUpgradeService from "../../service/upgrade/DefaultUpgradeService.ts";
+import type { UpgradeService } from "@flowscripter/dynamic-cli-framework-api";
 import NoBannerCommand, { type BannerState } from "./command/NoBannerCommand.ts";
 
 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".
  */
@@ -41,6 +41,15 @@ export default function createBannerStartupTask(
         return;
       }
 
+      const upgradeService = context.doesServiceExist(UPGRADE_SERVICE_ID)
+        ? (context.getServiceById(UPGRADE_SERVICE_ID) as UpgradeService)
+        : 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) as PrinterService;
 
       const asciiBannerGeneratorService = context.getServiceById(
@@ -64,10 +73,7 @@ export default function createBannerStartupTask(
         // 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" &&