@flowscripter/dynamic-cli-framework 2.1.0 → 2.3.0

package/src/cli/BaseCLI.ts

@@ -51,6 +51,8 @@ import ArgumentPrompterServiceProvider from "../service/argumentPrompter/Argumen
 import DefaultCompletionService from "../service/completion/DefaultCompletionService.ts";
 import CompletionServiceProvider from "../service/completion/CompletionServiceProvider.ts";
 import ImagePrinterServiceProvider from "../service/imagePrinter/ImagePrinterServiceProvider.ts";
+import SpawnServiceProvider from "../service/spawn/SpawnServiceProvider.ts";
+import UpgradeServiceProvider from "../service/upgrade/UpgradeServiceProvider.ts";
 const logger = getLogger("BaseCLI");
 
 /**
@@ -69,6 +71,9 @@ const logger = getLogger("BaseCLI");
  * Optionally enabled via {@link BaseCLIFeatureOptions}:
  *
  * * {@link ImagePrinterServiceProvider}
+ * * {@link SpawnServiceProvider}
+ * * {@link CompletionServiceProvider}
+ * * {@link UpgradeServiceProvider}
  *
  * `keyReader` is optional. If omitted, or if the stderr {@link Terminal} is not a TTY, prompting is
  * unavailable: {@link PrompterServiceProvider} (and {@link ArgumentPrompterServiceProvider}, if
@@ -130,6 +135,9 @@ export default class BaseCLI implements CLI {
       argumentPrompterServiceEnabled: false,
       completionServiceEnabled: false,
       imagePrinterServiceEnabled: false,
+      spawnServiceEnabled: false,
+      upgradeServiceEnabled: false,
+      upgradeLocationsConfig: { supportedPlatforms: [] },
       validateAllCommands: false,
       promptingEnabled: true,
       ...options,
@@ -262,6 +270,10 @@ export default class BaseCLI implements CLI {
       }
     }
 
+    if (this.#options.spawnServiceEnabled) {
+      this.addServiceProvider(new SpawnServiceProvider(58));
+    }
+
     if (this.#options.completionServiceEnabled) {
       const completionService = new DefaultCompletionService();
       this.addServiceProvider(
@@ -269,6 +281,10 @@ export default class BaseCLI implements CLI {
       );
     }
 
+    if (this.#options.upgradeServiceEnabled) {
+      this.addServiceProvider(new UpgradeServiceProvider(6, this.#options.upgradeLocationsConfig));
+    }
+
     const configurationServiceProvider = new ConfigurationServiceProvider(
       90,
       this.#options.envVarsSupportEnabled,

package/src/cli/BaseCLIFeatureOptions.ts

@@ -1,3 +1,5 @@
+import type { UpgradeLocationsConfig } from "../service/upgrade/UpgradeLocationsConfig.ts";
+
 export default interface BaseCLIFeatureOptions {
   readonly configFileSupportEnabled?: boolean;
   readonly envVarsSupportEnabled?: boolean;
@@ -6,6 +8,9 @@ export default interface BaseCLIFeatureOptions {
   readonly argumentPrompterServiceEnabled?: boolean;
   readonly completionServiceEnabled?: boolean;
   readonly imagePrinterServiceEnabled?: boolean;
+  readonly spawnServiceEnabled?: boolean;
+  readonly upgradeServiceEnabled?: boolean;
+  readonly upgradeLocationsConfig?: UpgradeLocationsConfig;
   readonly validateAllCommands?: boolean;
   readonly promptingEnabled?: boolean;
 }

package/src/command/VersionCommand.ts

@@ -2,6 +2,8 @@ import type { Context } from "@flowscripter/dynamic-cli-framework-api";
 import type { GlobalCommand } from "@flowscripter/dynamic-cli-framework-api";
 import type { PrinterService } from "@flowscripter/dynamic-cli-framework-api";
 import { PRINTER_SERVICE_ID } from "@flowscripter/dynamic-cli-framework-api";
+import { UPGRADE_SERVICE_ID } from "@flowscripter/dynamic-cli-framework-api";
+import type { UpgradeService } from "@flowscripter/dynamic-cli-framework-api";
 
 /**
  * Implementation of a {@link GlobalCommand} which outputs the version of the CLI.
@@ -13,6 +15,16 @@ export default class VersionCommand implements GlobalCommand {
 
   public async execute(context: Context): Promise<void> {
     const printerService = context.getServiceById(PRINTER_SERVICE_ID) as PrinterService;
-    await printerService.print(`${context.cliConfig.version}\n`);
+
+    let line = context.cliConfig.version;
+    if (context.doesServiceExist(UPGRADE_SERVICE_ID)) {
+      const upgradeService = context.getServiceById(UPGRADE_SERVICE_ID) as UpgradeService;
+      const result = await upgradeService.checkForUpgrade().catch(() => undefined);
+      if (result?.updateAvailable) {
+        line += ` (${result.latestVersion} available, run '${context.cliConfig.name} upgrade')`;
+      }
+    }
+
+    await printerService.print(`${line}\n`);
   }
 }

package/src/service/banner/BannerServiceProvider.ts

@@ -7,6 +7,8 @@ import type ConfigurationServiceProvider from "../configuration/ConfigurationSer
 import type { AsciiBannerGeneratorService } from "@flowscripter/dynamic-cli-framework-api";
 import { ASCII_BANNER_GENERATOR_SERVICE_ID } 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 type { UpgradeService } from "@flowscripter/dynamic-cli-framework-api";
 export const BANNER_SERVICE_ID = "@flowscripter/dynamic-cli-framework/banner-service";
 
 /**
@@ -68,6 +70,17 @@ export default class BannerServiceProvider implements ServiceProvider {
     if (cliConfig.version.length > 0) {
       await printerService.info(`  ${printerService.secondary("version: " + cliConfig.version)}\n`);
     }
+    if (context.doesServiceExist(UPGRADE_SERVICE_ID)) {
+      const upgradeService = context.getServiceById(UPGRADE_SERVICE_ID) as UpgradeService;
+      const result = await upgradeService.checkForUpgrade().catch(() => undefined);
+      if (result?.updateAvailable) {
+        await printerService.info(
+          `  ${printerService.secondary(
+            `(${result.latestVersion} available, run '${cliConfig.name} upgrade')`,
+          )}\n`,
+        );
+      }
+    }
     if (this.#configurationServiceProvider) {
       const configLocation = this.#configurationServiceProvider.configLocation;
       if (configLocation && configLocation.length > 0) {

package/src/service/plugin/DefaultPluginService.ts

@@ -1,8 +1,8 @@
 import type { PluginService } from "@flowscripter/dynamic-cli-framework-api";
 import type {
   MarketplacePluginManager,
-  VersionedPluginDescriptor,
   SearchQuery,
+  VersionedPluginDescriptor,
 } from "@flowscripter/dynamic-plugin-framework";
 
 export default class DefaultPluginService implements PluginService {

package/src/service/plugin/DefaultPluginServiceProvider.ts

@@ -1,20 +1,37 @@
 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 type { MarketplacePluginManager } from "@flowscripter/dynamic-plugin-framework";
+import type { PrinterService, SpawnService } from "@flowscripter/dynamic-cli-framework-api";
+import { PRINTER_SERVICE_ID, SPAWN_SERVICE_ID } from "@flowscripter/dynamic-cli-framework-api";
+import type {
+  MarketplacePluginManager,
+  SpawnCapable,
+} from "@flowscripter/dynamic-plugin-framework";
 import { PLUGIN_SERVICE_ID } from "@flowscripter/dynamic-cli-framework-api";
 import DefaultPluginService from "./DefaultPluginService.ts";
 import { PluginGroupCommand } from "./command/PluginGroupCommand.ts";
+import SpawnInterfaceAdapter, {
+  type SpawnInterfaceAdapterOptions,
+} from "./SpawnInterfaceAdapter.ts";
+import getLogger from "../../util/logger.ts";
+
+const logger = getLogger("DefaultPluginServiceProvider");
 
 export default class DefaultPluginServiceProvider implements ServiceProvider {
   readonly serviceId = PLUGIN_SERVICE_ID;
   readonly servicePriority: number;
   readonly #pluginManager: MarketplacePluginManager;
+  readonly #spawnInterfaceAdapterOptions: SpawnInterfaceAdapterOptions;
   #pluginService: DefaultPluginService | undefined;
 
-  constructor(pluginManager: MarketplacePluginManager, servicePriority = 50) {
+  constructor(
+    pluginManager: MarketplacePluginManager,
+    servicePriority = 50,
+    spawnInterfaceAdapterOptions: SpawnInterfaceAdapterOptions = {},
+  ) {
     this.#pluginManager = pluginManager;
     this.servicePriority = servicePriority;
+    this.#spawnInterfaceAdapterOptions = spawnInterfaceAdapterOptions;
   }
 
   async getServiceInfo(_cliConfig: CLIConfig): Promise<ServiceInfo> {
@@ -25,5 +42,24 @@ export default class DefaultPluginServiceProvider implements ServiceProvider {
     };
   }
 
-  async initService(_context: Context): Promise<void> {}
+  initService(context: Context): Promise<void> {
+    if (!context.doesServiceExist(SPAWN_SERVICE_ID)) {
+      logger.debug("SpawnService not available, plugin manager will spawn processes directly");
+      return Promise.resolve();
+    }
+    if (!("setSpawn" in this.#pluginManager)) {
+      logger.debug("Plugin manager does not support SpawnCapable, skipping spawn injection");
+      return Promise.resolve();
+    }
+
+    const spawnService = context.getServiceById(SPAWN_SERVICE_ID) as SpawnService;
+    const printerService = context.getServiceById(PRINTER_SERVICE_ID) as PrinterService;
+    const adapter = new SpawnInterfaceAdapter(
+      spawnService,
+      printerService,
+      this.#spawnInterfaceAdapterOptions,
+    );
+    (this.#pluginManager as unknown as SpawnCapable).setSpawn(adapter);
+    return Promise.resolve();
+  }
 }

package/src/service/plugin/SpawnInterfaceAdapter.ts

@@ -0,0 +1,62 @@
+import type { PrinterService, SpawnService } from "@flowscripter/dynamic-cli-framework-api";
+import type { SpawnInterface, SpawnResult } from "@flowscripter/dynamic-plugin-framework";
+
+export interface SpawnInterfaceAdapterOptions {
+  quoteColor?: string;
+  markMinimumDisplayTimeMs?: number;
+}
+
+/**
+ * Adapts a {@link SpawnService} to dynamic-plugin-framework's {@link SpawnInterface}, wrapping
+ * spawned process output in a quoted, marked block via {@link PrinterService} that is cleared
+ * again once the process exits (subject to {@link SpawnInterfaceAdapterOptions.markMinimumDisplayTimeMs}).
+ */
+export default class SpawnInterfaceAdapter implements SpawnInterface {
+  readonly #spawnService: SpawnService;
+  readonly #printerService: PrinterService;
+  readonly #quoteColor: string | undefined;
+  readonly #markMinimumDisplayTimeMs: number;
+
+  public constructor(
+    spawnService: SpawnService,
+    printerService: PrinterService,
+    options: SpawnInterfaceAdapterOptions = {},
+  ) {
+    this.#spawnService = spawnService;
+    this.#printerService = printerService;
+    this.#quoteColor = options.quoteColor;
+    this.#markMinimumDisplayTimeMs = options.markMinimumDisplayTimeMs ?? 1000;
+  }
+
+  public async spawn(
+    command: ReadonlyArray<string>,
+    options: { cwd: string },
+  ): Promise<SpawnResult> {
+    this.#printerService.startQuote(this.#quoteColor);
+    this.#printerService.startMark();
+
+    // onOutput is synchronous and may be called concurrently for stdout/stderr lines, but
+    // printerService.info() is async and must not be invoked concurrently with itself - queue
+    // writes so they're applied one at a time, in call order.
+    let writeQueue: Promise<void> = Promise.resolve();
+    const onOutput = (line: string): void => {
+      writeQueue = writeQueue.then(() => this.#printerService.info(`${line}\n`));
+    };
+
+    const result = await this.#spawnService.spawn(command, {
+      cwd: options.cwd,
+      stdio: "wrapped",
+      onOutput,
+    });
+
+    await writeQueue;
+
+    this.#printerService.endQuote();
+    this.#printerService.endMark();
+    await this.#printerService.clearMarked(this.#markMinimumDisplayTimeMs);
+
+    return result.ok
+      ? { ok: true, exitCode: result.exitCode }
+      : { ok: false, exitCode: result.exitCode, error: result.error };
+  }
+}

package/src/service/spawn/DefaultSpawnService.ts

@@ -0,0 +1,120 @@
+import type {
+  PrinterService,
+  ShutdownService,
+  SpawnOptions,
+  SpawnResult,
+  SpawnService,
+} from "@flowscripter/dynamic-cli-framework-api";
+import getLogger from "../../util/logger.ts";
+
+const logger = getLogger("DefaultSpawnService");
+
+const SHUTDOWN_GRACE_PERIOD_MS = 5000;
+
+export default class DefaultSpawnService implements SpawnService {
+  #printerService: PrinterService | undefined;
+  #shutdownService: ShutdownService | undefined;
+
+  public setDependencies(printerService: PrinterService, shutdownService: ShutdownService): void {
+    this.#printerService = printerService;
+    this.#shutdownService = shutdownService;
+  }
+
+  async #pipeLines(
+    stream: ReadableStream<Uint8Array> | number | undefined,
+    streamName: "stdout" | "stderr",
+    onOutput: (line: string, stream: "stdout" | "stderr") => void,
+  ): Promise<void> {
+    if (typeof stream !== "object" || stream === null) {
+      return;
+    }
+    const decoder = new TextDecoder();
+    const reader = stream.getReader();
+    let buffer = "";
+    for (;;) {
+      const { done, value } = await reader.read();
+      if (done) {
+        break;
+      }
+      buffer += decoder.decode(value, { stream: true });
+      let newlineIndex = buffer.indexOf("\n");
+      while (newlineIndex !== -1) {
+        onOutput(buffer.slice(0, newlineIndex), streamName);
+        buffer = buffer.slice(newlineIndex + 1);
+        newlineIndex = buffer.indexOf("\n");
+      }
+    }
+    if (buffer.length > 0) {
+      onOutput(buffer, streamName);
+    }
+  }
+
+  public async spawn(
+    command: ReadonlyArray<string>,
+    options: SpawnOptions = {},
+  ): Promise<SpawnResult> {
+    if (this.#printerService === undefined || this.#shutdownService === undefined) {
+      throw new Error("DefaultSpawnService.spawn() called before setDependencies()");
+    }
+    const printerService = this.#printerService;
+    const shutdownService = this.#shutdownService;
+    const stdio = options.stdio ?? "inherit";
+    const longRunning = options.longRunning ?? true;
+
+    if (stdio === "inherit") {
+      await printerService.hideSpinner();
+      await printerService.hideAllProgressBars();
+    }
+
+    let proc;
+    try {
+      proc = Bun.spawn([...command], {
+        cwd: options.cwd,
+        stdin: stdio === "wrapped" ? "ignore" : "inherit",
+        stdout: stdio === "wrapped" ? "pipe" : "inherit",
+        stderr: stdio === "wrapped" ? "pipe" : "inherit",
+      });
+    } catch (error) {
+      logger.debug(() => `Failed to launch command '${command.join(" ")}': ${error}`);
+      return { ok: false, error: error as Error };
+    }
+
+    let settled = false;
+
+    if (longRunning) {
+      shutdownService.enterLongRunningMode();
+    }
+
+    shutdownService.addShutdownListener(async () => {
+      if (settled) {
+        return;
+      }
+      logger.debug(() => `Sending SIGTERM to spawned command '${command.join(" ")}'`);
+      proc.kill("SIGTERM");
+      await Promise.race([
+        proc.exited.then(() => {}),
+        new Promise<void>((resolve) => setTimeout(resolve, SHUTDOWN_GRACE_PERIOD_MS)),
+      ]);
+      if (!settled) {
+        logger.debug(() => `Sending SIGKILL to spawned command '${command.join(" ")}'`);
+        proc.kill("SIGKILL");
+      }
+    });
+
+    if (stdio === "wrapped" && options.onOutput) {
+      const onOutput = options.onOutput;
+      void this.#pipeLines(proc.stdout, "stdout", onOutput);
+      void this.#pipeLines(proc.stderr, "stderr", onOutput);
+    }
+
+    try {
+      const exitCode = await proc.exited;
+      settled = true;
+      return exitCode === 0 ? { ok: true, exitCode } : { ok: false, exitCode };
+    } finally {
+      if (longRunning) {
+        shutdownService.leaveLongRunningMode();
+      }
+    }
+  }
+}

package/src/service/spawn/SpawnServiceProvider.ts

@@ -0,0 +1,32 @@
+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 type { PrinterService, ShutdownService } from "@flowscripter/dynamic-cli-framework-api";
+import { PRINTER_SERVICE_ID, SHUTDOWN_SERVICE_ID } from "@flowscripter/dynamic-cli-framework-api";
+import { SPAWN_SERVICE_ID } from "@flowscripter/dynamic-cli-framework-api";
+import DefaultSpawnService from "./DefaultSpawnService.ts";
+
+export default class SpawnServiceProvider implements ServiceProvider {
+  readonly serviceId: string = SPAWN_SERVICE_ID;
+  readonly servicePriority: number;
+  #spawnService: DefaultSpawnService | undefined;
+
+  public constructor(servicePriority: number) {
+    this.servicePriority = servicePriority;
+  }
+
+  public getServiceInfo(_cliConfig: CLIConfig): Promise<ServiceInfo> {
+    this.#spawnService = new DefaultSpawnService();
+    return Promise.resolve({
+      service: this.#spawnService,
+      commands: [],
+    });
+  }
+
+  public initService(context: Context): Promise<void> {
+    const printerService = context.getServiceById(PRINTER_SERVICE_ID) as PrinterService;
+    const shutdownService = context.getServiceById(SHUTDOWN_SERVICE_ID) as ShutdownService;
+    this.#spawnService!.setDependencies(printerService, shutdownService);
+    return Promise.resolve();
+  }
+}