@flowscripter/dynamic-cli-framework 2.2.0 → 2.3.0

package/src/service/upgrade/DefaultUpgradeService.ts

@@ -0,0 +1,379 @@
+import process from "node:process";
+import { mkdtemp } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import type {
+  CLIConfig,
+  SpawnService,
+  UpgradeCheckResult,
+  UpgradeResult,
+} from "@flowscripter/dynamic-cli-framework-api";
+import {
+  InstallMethod,
+  SupportedArch,
+  SupportedOs,
+  type UpgradeService,
+} from "@flowscripter/dynamic-cli-framework-api";
+import semver from "semver";
+import type { UpgradeLocationsConfig } from "./UpgradeLocationsConfig.ts";
+import getLogger from "../../util/logger.ts";
+
+const logger = getLogger("DefaultUpgradeService");
+
+const OS_LABELS: Record<SupportedOs, string> = {
+  [SupportedOs.LINUX]: "Linux",
+  [SupportedOs.MACOS]: "MacOS",
+  [SupportedOs.WINDOWS]: "Windows",
+};
+
+export default class DefaultUpgradeService implements UpgradeService {
+  #spawnService: SpawnService | undefined;
+  readonly #config: UpgradeLocationsConfig;
+  readonly #cliConfig: CLIConfig;
+
+  public constructor(config: UpgradeLocationsConfig, cliConfig: CLIConfig) {
+    this.#config = config;
+    this.#cliConfig = cliConfig;
+  }
+
+  public setDependencies(spawnService: SpawnService): void {
+    this.#spawnService = spawnService;
+  }
+
+  public detectOs(): SupportedOs | undefined {
+    switch (process.platform) {
+      case "linux":
+        return SupportedOs.LINUX;
+      case "darwin":
+        return SupportedOs.MACOS;
+      case "win32":
+        return SupportedOs.WINDOWS;
+      default:
+        return undefined;
+    }
+  }
+
+  public detectArch(): SupportedArch | undefined {
+    switch (process.arch) {
+      case "x64":
+        return SupportedArch.X64;
+      case "arm64":
+        return SupportedArch.ARM64;
+      default:
+        return undefined;
+    }
+  }
+
+  public async detectInstallMethod(os: SupportedOs): Promise<InstallMethod | undefined> {
+    if (os === SupportedOs.MACOS && this.#config.homebrew && (await this.#isHomebrewInstalled())) {
+      return InstallMethod.HOMEBREW;
+    }
+    if (os === SupportedOs.WINDOWS && this.#config.winget && (await this.#isWingetInstalled())) {
+      return InstallMethod.WINGET;
+    }
+    if (os === SupportedOs.LINUX && this.#config.linuxScript && this.#isLinuxScriptInstall()) {
+      return InstallMethod.LINUX_SCRIPT;
+    }
+    if (this.#config.githubRelease) {
+      return InstallMethod.GITHUB_RELEASE;
+    }
+    return undefined;
+  }
+
+  public async checkForUpgrade(
+    osOverride?: SupportedOs,
+    archOverride?: SupportedArch,
+    installMethodOverride?: InstallMethod,
+  ): Promise<UpgradeCheckResult | undefined> {
+    const os = osOverride ?? this.detectOs();
+    const arch = archOverride ?? this.detectArch();
+    if (!os || !arch || !this.#isPlatformSupported(os, arch)) {
+      return undefined;
+    }
+
+    const installMethod = installMethodOverride ?? (await this.detectInstallMethod(os));
+    if (!installMethod) {
+      return undefined;
+    }
+
+    const latestVersion = await this.#getLatestVersion(installMethod);
+    if (!latestVersion) {
+      return undefined;
+    }
+
+    const currentVersion = this.#cliConfig.version;
+    const coercedCurrent = semver.coerce(currentVersion);
+    const coercedLatest = semver.coerce(latestVersion);
+    if (!coercedCurrent || !coercedLatest) {
+      logger.debug(() => `Unable to compare versions '${currentVersion}' and '${latestVersion}'`);
+      return undefined;
+    }
+
+    return {
+      currentVersion,
+      latestVersion,
+      updateAvailable: semver.gt(coercedLatest, coercedCurrent),
+      os,
+      arch,
+      installMethod,
+    };
+  }
+
+  public async upgrade(
+    osOverride?: SupportedOs,
+    archOverride?: SupportedArch,
+    installMethodOverride?: InstallMethod,
+  ): Promise<UpgradeResult> {
+    const oldVersion = this.#cliConfig.version;
+    const checkResult = await this.checkForUpgrade(osOverride, archOverride, installMethodOverride);
+    if (!checkResult) {
+      return {
+        ok: false,
+        oldVersion,
+        error: new Error("No upgrade location configured for the detected or requested platform"),
+      };
+    }
+    if (!this.#spawnService) {
+      return { ok: false, oldVersion, error: new Error("SpawnService is not available") };
+    }
+
+    try {
+      switch (checkResult.installMethod) {
+        case InstallMethod.LINUX_SCRIPT:
+          await this.#upgradeViaLinuxScript();
+          break;
+        case InstallMethod.HOMEBREW:
+          await this.#upgradeViaHomebrew();
+          break;
+        case InstallMethod.WINGET:
+          await this.#upgradeViaWinget();
+          break;
+        case InstallMethod.GITHUB_RELEASE:
+          await this.#upgradeViaGithubRelease(checkResult.os, checkResult.arch);
+          break;
+      }
+      return { ok: true, oldVersion, newVersion: checkResult.latestVersion };
+    } catch (error) {
+      return { ok: false, oldVersion, error: error as Error };
+    }
+  }
+
+  #isPlatformSupported(os: SupportedOs, arch: SupportedArch): boolean {
+    return this.#config.supportedPlatforms.some(
+      (platform) => platform.os === os && platform.arch === arch,
+    );
+  }
+
+  async #isHomebrewInstalled(): Promise<boolean> {
+    if (!this.#spawnService || !this.#config.homebrew) {
+      return false;
+    }
+    const result = await this.#spawnService.spawn(
+      ["brew", "list", "--versions", this.#config.homebrew.formula],
+      { stdio: "wrapped", longRunning: false },
+    );
+    return result.ok;
+  }
+
+  async #isWingetInstalled(): Promise<boolean> {
+    if (!this.#spawnService || !this.#config.winget) {
+      return false;
+    }
+    const result = await this.#spawnService.spawn(
+      ["winget", "list", "--id", this.#config.winget.packageId],
+      { stdio: "wrapped", longRunning: false },
+    );
+    return result.ok;
+  }
+
+  #isLinuxScriptInstall(): boolean {
+    return process.execPath.startsWith("/usr/local/bin/");
+  }
+
+  async #getLatestVersion(installMethod: InstallMethod): Promise<string | undefined> {
+    switch (installMethod) {
+      case InstallMethod.GITHUB_RELEASE:
+      case InstallMethod.LINUX_SCRIPT:
+        return this.#getLatestGithubReleaseVersion();
+      case InstallMethod.HOMEBREW:
+        return this.#getLatestHomebrewVersion();
+      case InstallMethod.WINGET:
+        return this.#getLatestWingetVersion();
+      default:
+        return undefined;
+    }
+  }
+
+  async #getLatestGithubReleaseVersion(): Promise<string | undefined> {
+    if (!this.#config.githubRelease) {
+      return undefined;
+    }
+    const { owner, repo } = this.#config.githubRelease;
+    try {
+      const response = await fetch(`https://api.github.com/repos/${owner}/${repo}/releases/latest`);
+      if (!response.ok) {
+        return undefined;
+      }
+      const data = (await response.json()) as { tag_name?: string };
+      return data.tag_name?.replace(/^v/, "");
+    } catch (error) {
+      logger.debug(() => `Failed to fetch latest GitHub release for ${owner}/${repo}: ${error}`);
+      return undefined;
+    }
+  }
+
+  async #getLatestHomebrewVersion(): Promise<string | undefined> {
+    if (!this.#config.homebrew) {
+      return undefined;
+    }
+    const { tap, formula } = this.#config.homebrew;
+    const [tapOwner, tapName] = tap.split("/");
+    if (!tapOwner || !tapName) {
+      return undefined;
+    }
+    try {
+      const response = await fetch(
+        `https://raw.githubusercontent.com/${tapOwner}/homebrew-${tapName}/main/${formula}.rb`,
+      );
+      if (!response.ok) {
+        return undefined;
+      }
+      const text = await response.text();
+      return /version\s+"v?([^"]+)"/.exec(text)?.[1];
+    } catch (error) {
+      logger.debug(() => `Failed to fetch homebrew formula for ${tap}/${formula}: ${error}`);
+      return undefined;
+    }
+  }
+
+  async #getLatestWingetVersion(): Promise<string | undefined> {
+    if (!this.#spawnService || !this.#config.winget) {
+      return undefined;
+    }
+    const lines: string[] = [];
+    const result = await this.#spawnService.spawn(
+      ["winget", "show", "--id", this.#config.winget.packageId],
+      {
+        stdio: "wrapped",
+        longRunning: false,
+        onOutput: (line) => lines.push(line),
+      },
+    );
+    if (!result.ok) {
+      return undefined;
+    }
+    for (const line of lines) {
+      const match = /Version:\s*(\S+)/.exec(line);
+      if (match?.[1]) {
+        return match[1];
+      }
+    }
+    return undefined;
+  }
+
+  async #upgradeViaLinuxScript(): Promise<void> {
+    const { scriptUrl } = this.#config.linuxScript!;
+    const result = await this.#spawnService!.spawn(["sh", "-c", `curl -fsSL ${scriptUrl} | sh`]);
+    if (!result.ok) {
+      throw new Error(
+        `Install script failed: ${result.error?.message ?? `exit code ${result.exitCode}`}`,
+      );
+    }
+  }
+
+  async #upgradeViaHomebrew(): Promise<void> {
+    const { tap, formula } = this.#config.homebrew!;
+    const result = await this.#spawnService!.spawn(["brew", "upgrade", `${tap}/${formula}`]);
+    if (!result.ok) {
+      throw new Error(
+        `brew upgrade failed: ${result.error?.message ?? `exit code ${result.exitCode}`}`,
+      );
+    }
+  }
+
+  async #upgradeViaWinget(): Promise<void> {
+    const { packageId } = this.#config.winget!;
+    const result = await this.#spawnService!.spawn([
+      "winget",
+      "upgrade",
+      "--id",
+      packageId,
+      "--silent",
+      "--accept-package-agreements",
+      "--accept-source-agreements",
+    ]);
+    if (!result.ok) {
+      throw new Error(
+        `winget upgrade failed: ${result.error?.message ?? `exit code ${result.exitCode}`}`,
+      );
+    }
+  }
+
+  async #upgradeViaGithubRelease(os: SupportedOs, arch: SupportedArch): Promise<void> {
+    const { owner, repo, assetPattern } = this.#config.githubRelease!;
+    const archLabel =
+      os === SupportedOs.MACOS ? "aarch64" : arch === SupportedArch.X64 ? "x64" : "arm64";
+    const assetName = assetPattern.replace("{os}", OS_LABELS[os]).replace("{arch}", archLabel);
+    const url = `https://github.com/${owner}/${repo}/releases/latest/download/${assetName}`;
+
+    const response = await fetch(url);
+    if (!response.ok) {
+      throw new Error(`Failed to download release asset '${assetName}': HTTP ${response.status}`);
+    }
+
+    const tmpDir = await mkdtemp(join(tmpdir(), "upgrade-"));
+    const archivePath = join(tmpDir, assetName);
+    await Bun.write(archivePath, await response.arrayBuffer());
+
+    const currentExecutable = process.execPath;
+
+    if (os === SupportedOs.WINDOWS) {
+      const extractResult = await this.#spawnService!.spawn([
+        "powershell",
+        "-Command",
+        `Expand-Archive -Path '${archivePath}' -DestinationPath '${tmpDir}' -Force`,
+      ]);
+      if (!extractResult.ok) {
+        throw new Error("Failed to extract release archive");
+      }
+      const extractedBinary = join(tmpDir, `${this.#cliConfig.name}.exe`);
+      const oldPath = `${currentExecutable}.old.exe`;
+      const moveResult = await this.#spawnService!.spawn([
+        "cmd",
+        "/c",
+        "move",
+        "/y",
+        currentExecutable,
+        oldPath,
+      ]);
+      if (!moveResult.ok) {
+        throw new Error("Failed to move current executable aside");
+      }
+      const copyResult = await this.#spawnService!.spawn([
+        "cmd",
+        "/c",
+        "copy",
+        "/y",
+        extractedBinary,
+        currentExecutable,
+      ]);
+      if (!copyResult.ok) {
+        throw new Error("Failed to copy new executable into place");
+      }
+    } else {
+      const extractResult = await this.#spawnService!.spawn([
+        "unzip",
+        "-o",
+        archivePath,
+        "-d",
+        tmpDir,
+      ]);
+      if (!extractResult.ok) {
+        throw new Error("Failed to extract release archive");
+      }
+      const extractedBinary = join(tmpDir, this.#cliConfig.name);
+      await Bun.write(currentExecutable, Bun.file(extractedBinary));
+      await this.#spawnService!.spawn(["chmod", "+x", currentExecutable]);
+    }
+  }
+}

package/src/service/upgrade/UpgradeLocationsConfig.ts

@@ -0,0 +1,53 @@
+import type { SupportedArch, SupportedOs } from "@flowscripter/dynamic-cli-framework-api";
+
+/**
+ * Location of a manual GitHub release asset, and how to determine the latest available version.
+ */
+export interface GithubReleaseLocation {
+  readonly owner: string;
+  readonly repo: string;
+
+  /**
+   * Asset filename pattern for a release, e.g. `"example-cli_{os}_{arch}.zip"`.
+   * `{os}` is substituted with `Linux`, `MacOS` or `Windows`; `{arch}` with `x64`, `arm64` or
+   * `aarch64` (macOS).
+   */
+  readonly assetPattern: string;
+}
+
+/**
+ * Location of a Linux install script, e.g. as documented for `curl -fsSL <scriptUrl> | sh`.
+ */
+export interface LinuxScriptLocation {
+  readonly scriptUrl: string;
+}
+
+/**
+ * Location of a Homebrew tap formula, e.g. `brew install <tap>/<formula>`.
+ */
+export interface HomebrewLocation {
+  readonly tap: string;
+  readonly formula: string;
+}
+
+/**
+ * Identifier of a Winget package, e.g. `winget install <packageId>`.
+ */
+export interface WingetLocation {
+  readonly packageId: string;
+}
+
+/**
+ * CLI-author supplied configuration describing which os/arch combinations a CLI supports
+ * upgrading, and where to find the latest release for each supported install method.
+ *
+ * An install method is only usable for an os/arch combination if both its config block is
+ * present here AND that combination appears in {@link supportedPlatforms}.
+ */
+export interface UpgradeLocationsConfig {
+  readonly supportedPlatforms: ReadonlyArray<{ os: SupportedOs; arch: SupportedArch }>;
+  readonly githubRelease?: GithubReleaseLocation;
+  readonly linuxScript?: LinuxScriptLocation;
+  readonly homebrew?: HomebrewLocation;
+  readonly winget?: WingetLocation;
+}

package/src/service/upgrade/UpgradeServiceProvider.ts

@@ -0,0 +1,150 @@
+import type { ServiceInfo, ServiceProvider } from "@flowscripter/dynamic-cli-framework-api";
+import type { Context } from "@flowscripter/dynamic-cli-framework-api";
+import type { CLIConfig } from "@flowscripter/dynamic-cli-framework-api";
+import { UPGRADE_SERVICE_ID } from "@flowscripter/dynamic-cli-framework-api";
+import { PROMPTER_SERVICE_ID, PromptType } from "@flowscripter/dynamic-cli-framework-api";
+import type { PrompterService } from "@flowscripter/dynamic-cli-framework-api";
+import { KEY_VALUE_SERVICE_ID } from "@flowscripter/dynamic-cli-framework-api";
+import type { KeyValueService } from "@flowscripter/dynamic-cli-framework-api";
+import { SPAWN_SERVICE_ID } from "@flowscripter/dynamic-cli-framework-api";
+import type { SpawnService } from "@flowscripter/dynamic-cli-framework-api";
+import { Icon, PRINTER_SERVICE_ID } from "@flowscripter/dynamic-cli-framework-api";
+import type { PrinterService } from "@flowscripter/dynamic-cli-framework-api";
+import DefaultUpgradeService from "./DefaultUpgradeService.ts";
+import { UpgradeSubCommand } from "./command/UpgradeSubCommand.ts";
+import type { UpgradeLocationsConfig } from "./UpgradeLocationsConfig.ts";
+import getLogger from "../../util/logger.ts";
+
+const logger = getLogger("UpgradeServiceProvider");
+
+export default class UpgradeServiceProvider implements ServiceProvider {
+  readonly serviceId: string = UPGRADE_SERVICE_ID;
+  readonly servicePriority: number;
+  readonly #config: UpgradeLocationsConfig;
+  #upgradeService: DefaultUpgradeService | undefined;
+  #cliConfig: CLIConfig | undefined;
+
+  public constructor(servicePriority: number, config: UpgradeLocationsConfig) {
+    this.servicePriority = servicePriority;
+    this.#config = config;
+  }
+
+  public getServiceInfo(cliConfig: CLIConfig): Promise<ServiceInfo> {
+    this.#cliConfig = cliConfig;
+    this.#upgradeService = new DefaultUpgradeService(this.#config, cliConfig);
+    return Promise.resolve({
+      service: this.#upgradeService,
+      commands: [new UpgradeSubCommand(this.#upgradeService)],
+    });
+  }
+
+  public async initService(context: Context): Promise<void> {
+    const upgradeService = this.#upgradeService!;
+    const cliConfig = this.#cliConfig!;
+
+    if (context.doesServiceExist(SPAWN_SERVICE_ID)) {
+      const spawnService = context.getServiceById(SPAWN_SERVICE_ID) as SpawnService;
+      upgradeService.setDependencies(spawnService);
+    } else {
+      logger.debug(() => "SpawnService not available, upgrade install methods will be unavailable");
+    }
+
+    if (!context.doesServiceExist(PROMPTER_SERVICE_ID)) {
+      logger.debug(() => "PrompterService not available, skipping auto-upgrade");
+      return;
+    }
+    if (!context.doesServiceExist(KEY_VALUE_SERVICE_ID)) {
+      logger.debug(() => "KeyValueService not available, skipping auto-upgrade");
+      return;
+    }
+
+    const keyValueService = context.getServiceById(KEY_VALUE_SERVICE_ID) as KeyValueService;
+
+    if (await keyValueService.hasKey("upgrade-status")) {
+      const status = await keyValueService.getKey("upgrade-status");
+      if (status === "declined") {
+        logger.debug(() => "Auto-upgrade previously declined, skipping");
+        return;
+      }
+      if (status === "enabled") {
+        await this.#checkAndUpgrade(context, upgradeService, cliConfig);
+        return;
+      }
+    }
+
+    const prompterService = context.getServiceById(PROMPTER_SERVICE_ID) as PrompterService;
+    if (!prompterService.promptEnabled) {
+      logger.debug(() => "Prompting is disabled, skipping auto-upgrade prompt");
+      return;
+    }
+
+    const os = upgradeService.detectOs();
+    const arch = upgradeService.detectArch();
+    if (!os || !arch) {
+      logger.debug(() => "Unsupported OS/arch, skipping auto-upgrade prompt");
+      return;
+    }
+    const installMethod = await upgradeService.detectInstallMethod(os);
+    if (!installMethod) {
+      logger.debug(() => "No supported install method detected, skipping auto-upgrade prompt");
+      return;
+    }
+
+    let enableResult;
+    try {
+      enableResult = await prompterService.prompt({
+        name: "enable-upgrade",
+        promptText: "Would you like to enable automatic upgrades on startup?",
+        description:
+          "This will check for and install newer versions of " +
+          `${cliConfig.name} before it runs each time.`,
+        type: PromptType.TOGGLE,
+        options: [
+          { displayValue: "Yes", returnedValue: true },
+          { displayValue: "No", returnedValue: false },
+        ],
+      });
+    } catch {
+      return;
+    }
+
+    if (enableResult.value !== true) {
+      await keyValueService.setKey("upgrade-status", "declined");
+      return;
+    }
+
+    await keyValueService.setKey("upgrade-status", "enabled");
+    await this.#checkAndUpgrade(context, upgradeService, cliConfig);
+  }
+
+  async #checkAndUpgrade(
+    context: Context,
+    upgradeService: DefaultUpgradeService,
+    cliConfig: CLIConfig,
+  ): Promise<void> {
+    try {
+      const checkResult = await upgradeService.checkForUpgrade();
+      if (!checkResult?.updateAvailable) {
+        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(
+          `Auto-upgrade failed: ${upgradeResult.error?.message ?? "unknown error"}\n`,
+          Icon.FAILURE,
+        );
+      }
+    } catch (error) {
+      logger.debug(() => `Auto-upgrade check failed: ${error}`);
+    }
+  }
+}

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

@@ -0,0 +1,85 @@
+import type { SubCommand } from "@flowscripter/dynamic-cli-framework-api";
+import type { Option } from "@flowscripter/dynamic-cli-framework-api";
+import type { Context } from "@flowscripter/dynamic-cli-framework-api";
+import {
+  type ArgumentValues,
+  ArgumentValueTypeName,
+} from "@flowscripter/dynamic-cli-framework-api";
+import {
+  Icon,
+  InstallMethod,
+  PRINTER_SERVICE_ID,
+  SupportedArch,
+  SupportedOs,
+} from "@flowscripter/dynamic-cli-framework-api";
+import type { PrinterService } from "@flowscripter/dynamic-cli-framework-api";
+import type DefaultUpgradeService from "../DefaultUpgradeService.ts";
+
+export class UpgradeSubCommand implements SubCommand {
+  readonly name = "upgrade";
+  readonly description = "Upgrade to the latest available version";
+  readonly enableConfiguration = false;
+  readonly positionals = [];
+
+  readonly options: ReadonlyArray<Option> = [
+    {
+      name: "os",
+      type: ArgumentValueTypeName.STRING,
+      isOptional: true,
+      allowableValues: Object.values(SupportedOs),
+      description: "Override the detected operating system",
+    },
+    {
+      name: "install-method",
+      type: ArgumentValueTypeName.STRING,
+      isOptional: true,
+      allowableValues: Object.values(InstallMethod),
+      description: "Override the detected install method",
+    },
+  ];
+
+  readonly #upgradeService: DefaultUpgradeService;
+
+  public constructor(upgradeService: DefaultUpgradeService) {
+    this.#upgradeService = upgradeService;
+  }
+
+  public async execute(context: Context, argumentValues: ArgumentValues): Promise<void> {
+    const printerService = context.getServiceById(PRINTER_SERVICE_ID) as PrinterService;
+    const cliName = context.cliConfig.name;
+
+    const os = argumentValues.os as SupportedOs | undefined;
+    const arch = undefined as SupportedArch | undefined;
+    const installMethod = argumentValues["install-method"] as InstallMethod | undefined;
+
+    const checkResult = await this.#upgradeService.checkForUpgrade(os, arch, installMethod);
+    if (!checkResult) {
+      await printerService.error(
+        `No upgrade location is configured for the detected or requested platform.\n`,
+        Icon.FAILURE,
+      );
+      return;
+    }
+
+    if (!checkResult.updateAvailable) {
+      await printerService.print(
+        `${cliName} is already up to date (${checkResult.currentVersion}).\n`,
+      );
+      return;
+    }
+
+    const upgradeResult = await this.#upgradeService.upgrade(os, arch, installMethod);
+    if (!upgradeResult.ok) {
+      await printerService.error(
+        `Failed to upgrade ${cliName}: ${upgradeResult.error?.message ?? "unknown error"}\n`,
+        Icon.FAILURE,
+      );
+      return;
+    }
+
+    await printerService.print(
+      `${cliName} upgraded (${upgradeResult.oldVersion} -> ${upgradeResult.newVersion})\n`,
+      Icon.SUCCESS,
+    );
+  }
+}