@flowscripter/dynamic-cli-framework 1.0.0

package/src/launcher.ts

@@ -0,0 +1,127 @@
+import process from "node:process";
+import path from "node:path";
+import type CLIConfig from "./api/CLIConfig.ts";
+import type SubCommand from "./api/command/SubCommand.ts";
+import DefaultRuntimeCLI from "./cli/DefaultRuntimeCLI.ts";
+import type Command from "./api/command/Command.ts";
+import type RunResult from "./api/RunResult.ts";
+import type { ServiceProvider } from "./api/service/ServiceProvider.ts";
+
+function parseVersion(moduleUrl?: string): string | undefined {
+  if (moduleUrl === undefined) {
+    return undefined;
+  }
+
+  const v = moduleUrl.match(/@([^\/]+)[\/$]?/);
+  if (v === null) {
+    return undefined;
+  }
+  return v[1];
+}
+
+/**
+ * Launch a {@link DefaultRuntimeCLI} with a single specified {@link SubCommand} instance.
+ *
+ * @param command the {@link SubCommand} to add to the CLI.
+ * @param description optional description of the CLI.
+ * @param name optional name of the CLI. If not provided, `process.execPath` will be used in an attempt to derive the name.
+ * @param version optional version of the CLI. If not provided the optionally provided {@link callingModuleUrl} will be used in an attempt to derive the version. If not possible the default is `N/A`.
+ * @param envVarsEnabled optionally support checking env variables for default argument values.
+ * @param configEnabled optionally enable configuration file support for default argument values.
+ * @param keyValueServiceEnabled optionally provide a {@link KeyValueService} implementation: `configEnabled` must be true in this case
+ * @param callingModuleUrl optional URL of the calling module, can be used in an attempt to derive the version of the CLI if {@link version} is not provided. If not possible the default is `N/A`.
+ * @param serviceProviders optional array of {@link ServiceProvider} instances to add to the CLI.
+ */
+export async function launchSingleCommandCLI(
+  command: SubCommand,
+  description?: string,
+  name?: string,
+  version?: string,
+  envVarsEnabled = false,
+  configEnabled = false,
+  keyValueServiceEnabled = false,
+  callingModuleUrl?: string,
+  serviceProviders?: ReadonlyArray<ServiceProvider>,
+): Promise<RunResult> {
+  if (!name) {
+    name = path.basename(process.execPath);
+  }
+  const cliConfig: CLIConfig = {
+    description,
+    name,
+    version: version || parseVersion(callingModuleUrl) || "N/A",
+  };
+
+  if (!configEnabled && keyValueServiceEnabled) {
+    throw new Error(
+      "configEnabled must be true if keyValueServiceEnabled is true",
+    );
+  }
+  const validateAllCommands = process.env.CLI_VALIDATE_ALL !== undefined;
+  const cli = new DefaultRuntimeCLI(
+    cliConfig,
+    envVarsEnabled,
+    configEnabled,
+    keyValueServiceEnabled,
+    validateAllCommands,
+  );
+
+  cli.addCommand(command);
+
+  serviceProviders?.forEach((service) => cli.addServiceProvider(service));
+
+  return await cli.run();
+}
+
+/**
+ * Launch a {@link DefaultRuntimeCLI} with multiple specified {@link Command} instances.
+ *
+ * @param commands the {@link Command} instances to add to the CLI.
+ * @param description optional description of the CLI.
+ * @param name optional name of the CLI. If not provided, `process.execPath` will be used in an attempt to derive the name.
+ * @param version optional version of the CLI. If not provided the optionally provided {@link callingModuleUrl} will be used in an attempt to derive the version. If not possible the default is `N/A`.
+ * @param envVarsEnabled optionally support checking env variables for default argument values.
+ * @param configEnabled optionally enable configuration file support for default argument values.
+ * @param keyValueServiceEnabled optionally provide a {@link KeyValueService} implementation: `configEnabled` must be true in this case
+ * @param callingModuleUrl optional URL of the calling module, can be used in an attempt to derive the version of the CLI if {@link version} is not provided. If not possible the default is `N/A`.
+ * @param serviceProviders optional array of {@link ServiceProvider} instances to add to the CLI.
+ */
+export async function launchMultiCommandCLI(
+  commands: ReadonlyArray<Command>,
+  description?: string,
+  name?: string,
+  version?: string,
+  envVarsEnabled = false,
+  configEnabled = false,
+  keyValueServiceEnabled = false,
+  callingModuleUrl?: string,
+  serviceProviders?: ReadonlyArray<ServiceProvider>,
+): Promise<RunResult> {
+  if (!name) {
+    name = path.basename(process.execPath);
+  }
+  const cliConfig: CLIConfig = {
+    description,
+    name,
+    version: version || parseVersion(callingModuleUrl) || "N/A",
+  };
+  if (!configEnabled && keyValueServiceEnabled) {
+    throw new Error(
+      "configEnabled must be true if keyValueServiceEnabled is true",
+    );
+  }
+  const validateAllCommands = process.env.CLI_VALIDATE_ALL !== undefined;
+  const cli = new DefaultRuntimeCLI(
+    cliConfig,
+    envVarsEnabled,
+    configEnabled,
+    keyValueServiceEnabled,
+    validateAllCommands,
+  );
+
+  commands.forEach((command) => cli.addCommand(command));
+
+  serviceProviders?.forEach((service) => cli.addServiceProvider(service));
+
+  return await cli.run();
+}

package/src/runtime/DefaultContext.ts

@@ -0,0 +1,32 @@
+import type Context from "../api/Context.ts";
+import type CLIConfig from "../api/CLIConfig.ts";
+
+/**
+ * Default implementation of a {@link Context}.
+ */
+export default class DefaultContext implements Context {
+  readonly #serviceInstancesById: Map<string, unknown> = new Map();
+
+  public constructor(readonly cliConfig: CLIConfig) {
+  }
+
+  public addServiceInstance(id: string, serviceInstance: unknown) {
+    if (this.#serviceInstancesById.has(id)) {
+      throw new Error(
+        `Service ID: ${id} duplicates the ID of an existing service`,
+      );
+    }
+    this.#serviceInstancesById.set(id, serviceInstance);
+  }
+
+  public getServiceById(id: string): unknown {
+    if (!this.#serviceInstancesById.has(id)) {
+      throw new Error(`Service with ID: ${id} does not exist`);
+    }
+    return this.#serviceInstancesById.get(id);
+  }
+
+  public doesServiceExist(id: string): boolean {
+    return this.#serviceInstancesById.has(id);
+  }
+}

package/src/runtime/argument/ArgumentTypeGuards.ts

@@ -0,0 +1,8 @@
+import type Argument from "../../api/argument/Argument.ts";
+import type ComplexOption from "../../api/argument/ComplexOption.ts";
+
+export function isComplexOption(
+  argument: Argument | ComplexOption,
+): argument is ComplexOption {
+  return (argument as ComplexOption).properties !== undefined;
+}

package/src/runtime/command/CommandTypeGuards.ts

@@ -0,0 +1,30 @@
+import type SubCommand from "../../api/command/SubCommand.ts";
+import type GroupCommand from "../../api/command/GroupCommand.ts";
+import type GlobalCommand from "../../api/command/GlobalCommand.ts";
+import type GlobalModifierCommand from "../../api/command/GlobalModifierCommand.ts";
+import type Command from "../../api/command/Command.ts";
+
+export function isGroupCommand(
+  command: Command,
+): command is GroupCommand {
+  return (command as GroupCommand).memberSubCommands !== undefined;
+}
+
+export function isSubCommand(
+  command: Command,
+): command is SubCommand {
+  return (command as SubCommand).options !== undefined;
+}
+
+export function isGlobalModifierCommand(
+  command: Command,
+): command is GlobalModifierCommand {
+  return (command as GlobalModifierCommand).executePriority !== undefined;
+}
+
+export function isGlobalCommand(
+  command: Command,
+): command is GlobalCommand {
+  return !isGroupCommand(command) && !isSubCommand(command) &&
+    !isGlobalModifierCommand(command);
+}