@flowscripter/dynamic-cli-framework 1.0.0

package/src/util/logger.ts

@@ -0,0 +1,84 @@
+import process from "node:process";
+type LoggerFunction = (
+  message: object | (() => string) | string,
+  ...optionalParams: unknown[]
+) => void;
+
+export interface Logger {
+  trace: LoggerFunction;
+  debug: LoggerFunction;
+  info: LoggerFunction;
+  warn: LoggerFunction;
+  error: LoggerFunction;
+}
+
+const debugEnabled = process.env["CLI_DEBUG"] !== undefined;
+
+function getDefaultLogger(): Logger {
+  if (debugEnabled) {
+    return {
+      trace: () => {},
+      debug: (message, ...optionalParams) => {
+        console.debug(message, optionalParams);
+      },
+      info: (message, ...optionalParams) => {
+        console.info(message, optionalParams);
+      },
+      warn: (message, ...optionalParams) => {
+        console.warn(message, optionalParams);
+      },
+      error: (message, ...optionalParams) => {
+        console.error(message, optionalParams);
+      },
+    };
+  }
+  return {
+    trace: () => {},
+    debug: () => {},
+    info: () => {},
+    warn: () => {},
+    error: (message, ...optionalParams) => {
+      console.error(message, optionalParams);
+    },
+  };
+}
+
+function wrapWithLoggerName(
+  loggerName: string,
+  loggerFunction: LoggerFunction,
+): LoggerFunction {
+  return (message, ...optionalParams) => {
+    if (message instanceof Object) {
+      message.loggerName = loggerName;
+      loggerFunction(message, optionalParams);
+      return;
+    }
+    if (message instanceof Function) {
+      loggerFunction(`${loggerName} ${message()}`, optionalParams);
+      return;
+    }
+    loggerFunction(`${loggerName} ${message}`, optionalParams);
+  };
+}
+
+export default function getLogger(loggerName: string): Logger {
+  if (globalThis.defaultLogger === undefined) {
+    globalThis.defaultLogger = getDefaultLogger();
+  }
+  if (debugEnabled) {
+    return {
+      trace: () => {},
+      debug: wrapWithLoggerName(loggerName, globalThis.defaultLogger.debug),
+      info: wrapWithLoggerName(loggerName, globalThis.defaultLogger.info),
+      warn: wrapWithLoggerName(loggerName, globalThis.defaultLogger.warn),
+      error: wrapWithLoggerName(loggerName, globalThis.defaultLogger.error),
+    };
+  }
+  return {
+    trace: () => {},
+    debug: () => {},
+    info: () => {},
+    warn: () => {},
+    error: wrapWithLoggerName(loggerName, globalThis.defaultLogger.error),
+  };
+}

package/src/util/runnerHelper.ts

@@ -0,0 +1,112 @@
+import type PrinterService from "../api/service/core/PrinterService.ts";
+import {
+  Icon,
+  PRINTER_SERVICE_ID,
+} from "../api/service/core/PrinterService.ts";
+import type { ParseResult } from "../runtime/parser.ts";
+import {
+  isGlobalCommand,
+  isGlobalModifierCommand,
+} from "../runtime/command/CommandTypeGuards.ts";
+import type Context from "../api/Context.ts";
+import { getInvalidArgumentString } from "../runtime/values/argumentValueValidation.ts";
+
+function getCommandString(
+  printerService: PrinterService,
+  parseResult: ParseResult,
+): string {
+  const { command, groupCommand } = parseResult;
+
+  if (groupCommand) {
+    return printerService.yellow(
+      `'${groupCommand.name}:${command.name}'`,
+    );
+  }
+  return printerService.yellow(`'${command.name}'`);
+}
+
+export async function printParseResultError(
+  context: Context,
+  parseResult: ParseResult,
+  isDefaultCommand = false,
+) {
+  const printerService = context.getServiceById(
+    PRINTER_SERVICE_ID,
+  ) as PrinterService;
+  const commandErrorString = isDefaultCommand
+    ? "Parse error: "
+    : `Parse error for command: ${
+      getCommandString(printerService, parseResult)
+    }`;
+  const { command, invalidArguments } = parseResult;
+
+  let errorString = "=> ";
+
+  const skipArgName = isGlobalModifierCommand(command) ||
+    isGlobalCommand(command);
+  const argsString = invalidArguments.map(
+    (arg) => getInvalidArgumentString(arg, skipArgName),
+  ).join(", ");
+  errorString = `${errorString}${printerService.yellow(argsString)}`;
+
+  await printerService.error(
+    `${commandErrorString}\n  ${errorString}\n\n`,
+    Icon.FAILURE,
+  );
+}
+
+export async function printCommandExecutionError(
+  context: Context,
+  parseResult: ParseResult,
+  err: Error,
+  isDefaultCommand = false,
+) {
+  const printerService = context.getServiceById(
+    PRINTER_SERVICE_ID,
+  ) as PrinterService;
+  const commandErrorString = isDefaultCommand
+    ? "Execution error: "
+    : `Execution error for command: ${
+      getCommandString(printerService, parseResult)
+    }`;
+  if (err !== undefined) {
+    await printerService.error(
+      `${commandErrorString}\n  => ${printerService.yellow(err.message)}\n\n`,
+      Icon.FAILURE,
+    );
+  } else {
+    await printerService.error(
+      `${commandErrorString}\n  => ${
+        printerService.yellow("error is undefined")
+      }\n\n`,
+      Icon.FAILURE,
+    );
+  }
+}
+
+export async function printNoCommandSpecifiedError(context: Context) {
+  const printerService = context.getServiceById(
+    PRINTER_SERVICE_ID,
+  ) as PrinterService;
+  await printerService.error("No command specified\n\n");
+}
+
+export async function printUnusedArgsWarning(
+  context: Context,
+  overallUnusedArgs: ReadonlyArray<string>,
+) {
+  const printerService = context.getServiceById(
+    PRINTER_SERVICE_ID,
+  ) as PrinterService;
+  if (overallUnusedArgs.length === 1) {
+    await printerService.warn(
+      `Unused arg: ${overallUnusedArgs[0]}\n\n`,
+      Icon.ALERT,
+    );
+  } else {
+    await printerService.warn(
+      `Unused args: ${overallUnusedArgs.join(" ")}\n\n`,
+      Icon.ALERT,
+    );
+  }
+}

package/tests/cli/BaseCLI.test.ts

@@ -0,0 +1,344 @@
+import process from "node:process";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { describe, expect, test } from "bun:test";
+import {
+  getGlobalModifierCommandWithArgument,
+  getSubCommand,
+  getSubCommandWithOptionAndPositional,
+} from "../fixtures/Command.ts";
+import { getCLIConfig } from "../fixtures/CLIConfig.ts";
+import { RunState } from "../../src/api/RunResult.ts";
+import { ArgumentValueTypeName } from "../../src/api/argument/ArgumentValueTypes.ts";
+import BaseCLI from "../../src/cli/BaseCLI.ts";
+import type KeyValueService from "../../src/api/service/core/KeyValueService.ts";
+import {
+  KEY_VALUE_SERVICE_ID,
+} from "../../src/api/service/core/KeyValueService.ts";
+import type {
+  ServiceInfo,
+  ServiceProvider,
+} from "../../src/api/service/ServiceProvider.ts";
+import type Context from "../../src/api/Context.ts";
+import type CLIConfig from "../../src/api/CLIConfig.ts";
+import StreamString from "../fixtures/StreamString.ts";
+import { expectStringEquals, expectStringIncludes } from "../fixtures/util.ts";
+import TtyTerminal from "../../src/service/printer/terminal/TtyTerminal.ts";
+import TtyStyler from "../../src/service/printer/terminal/TtyStyler.ts";
+
+describe("BaseCLI Tests", () => {
+  test("BaseCLI no command specified works", async () => {
+    const config = getCLIConfig();
+    const dummyStdout = new StreamString();
+    const dummyStderr = new StreamString();
+    const terminal = new TtyTerminal(dummyStdout.writeStream);
+    const baseCLI = new BaseCLI(
+      config,
+      dummyStdout.writableStream,
+      dummyStderr.writableStream,
+      false,
+      false,
+      terminal,
+      new TtyStyler(3),
+      false,
+    );
+
+    baseCLI.addCommand(getSubCommandWithOptionAndPositional());
+
+    const runResult = await baseCLI.run([]);
+
+    expect(runResult.runState).toEqual(RunState.NO_COMMAND);
+  });
+
+  test("BaseCLI command execution works", async () => {
+    const config = getCLIConfig();
+    const dummyStdout = new StreamString();
+    const dummyStderr = new StreamString();
+    const terminal = new TtyTerminal(dummyStderr.writeStream);
+    const baseCLI = new BaseCLI(
+      config,
+      dummyStdout.writableStream,
+      dummyStderr.writableStream,
+      false,
+      false,
+      terminal,
+      new TtyStyler(3),
+      false,
+    );
+
+    let modifierHasRun = false;
+    let subHasRun = false;
+
+    const modifierCommand = getGlobalModifierCommandWithArgument(
+      "modifier",
+      "m",
+      1,
+      {
+        type: ArgumentValueTypeName.STRING,
+      },
+    );
+    const option = {
+      name: "foo",
+      type: ArgumentValueTypeName.STRING,
+      shortAlias: "f",
+    };
+    const subCommand = getSubCommand("command", [option], []);
+
+    modifierCommand.execute = (): Promise<void> => {
+      modifierHasRun = true;
+      return Promise.resolve();
+    };
+    subCommand.execute = (): Promise<void> => {
+      subHasRun = true;
+      return Promise.resolve();
+    };
+
+    baseCLI.addCommand(modifierCommand);
+    baseCLI.addCommand(subCommand);
+
+    const runResult = await baseCLI.run([
+      "unused",
+      "--modifier=bar",
+      "command",
+      "--foo",
+      "bar",
+    ]);
+
+    expect(runResult.runState).toEqual(RunState.SUCCESS);
+    expect(modifierHasRun).toBeTrue();
+    expect(subHasRun).toBeTrue();
+    expectStringEquals(dummyStdout.getString(), "");
+    expectStringIncludes(dummyStderr.getString(), "Unused arg: unused");
+  });
+
+  test("Command and service key value scope isolation works", async () => {
+    // ensure we can remove the config file written by the test
+    const dummyStdout = new StreamString();
+    const dummyStderr = new StreamString();
+    const appName = "foo" + Math.random();
+    const baseCLI = new BaseCLI(
+      getCLIConfig(appName),
+      dummyStdout.writableStream,
+      dummyStderr.writableStream,
+      false,
+      false,
+      new TtyTerminal(dummyStderr.writeStream),
+      new TtyStyler(3),
+      false,
+      true,
+      true,
+    );
+
+    let serviceProvider1Initialised = false;
+    let serviceProvider2Initialised = false;
+    let service1MethodInvoked = false;
+    let service2MethodInvoked = false;
+    let modifierHasRun = false;
+    let subHasRun = false;
+
+    const SERVICE_1 = "service1";
+    const SERVICE_2 = "service2";
+
+    interface ServiceInterface {
+      serviceMethod(context: Context): void;
+    }
+
+    class DefaultService1 implements ServiceInterface {
+      copyOfKeyValueService: KeyValueService | undefined;
+
+      serviceMethod(context: Context): void {
+        // should only have access to the modifierCommand KV scope
+        expect(this.copyOfKeyValueService!.hasKey("name")).toBeTrue();
+        expect(
+          this.copyOfKeyValueService!.getKey("name"),
+        ).toEqual(
+          "modifierCommand",
+        );
+        this.copyOfKeyValueService!.setKey(
+          "name",
+          "defaultService1+modifierCommand",
+        );
+
+        const keyValueService = context.getServiceById(
+          KEY_VALUE_SERVICE_ID,
+        ) as KeyValueService;
+
+        // should only have access to the modifierCommand KV scope
+        expect(keyValueService.hasKey("name")).toBeTrue();
+        expect(
+          this.copyOfKeyValueService!.getKey("name"),
+        ).toEqual(
+          "defaultService1+modifierCommand",
+        );
+
+        service1MethodInvoked = true;
+      }
+    }
+
+    class DefaultService2 implements ServiceInterface {
+      copyOfKeyValueService: KeyValueService | undefined;
+
+      serviceMethod(context: Context): void {
+        // should only have access to the modifierCommand KV scope
+        expect(this.copyOfKeyValueService!.hasKey("name")).toBeTrue();
+        expect(this.copyOfKeyValueService!.getKey("name")).toEqual(
+          "subCommand",
+        );
+        this.copyOfKeyValueService!.setKey(
+          "name",
+          "defaultService2+subCommand",
+        );
+
+        const keyValueService = context.getServiceById(
+          KEY_VALUE_SERVICE_ID,
+        ) as KeyValueService;
+
+        // should only have access to the subCommand KV scope
+        expect(keyValueService.hasKey("name")).toBeTrue();
+        expect(
+          this.copyOfKeyValueService!.getKey("name"),
+        ).toEqual(
+          "defaultService2+subCommand",
+        );
+
+        service2MethodInvoked = true;
+      }
+    }
+
+    class ServiceProvider1 implements ServiceProvider {
+      readonly serviceId = SERVICE_1;
+      readonly servicePriority = 1;
+
+      defaultService1: DefaultService1 | undefined;
+
+      provide(_cliConfig: CLIConfig): Promise<ServiceInfo> {
+        this.defaultService1 = new DefaultService1();
+        return Promise.resolve({
+          service: this.defaultService1,
+          commands: [],
+        });
+      }
+
+      initService(context: Context): Promise<void> {
+        const keyValueService = context.getServiceById(
+          KEY_VALUE_SERVICE_ID,
+        ) as KeyValueService;
+
+        // should only have access to the ServiceProvider1 KV scope
+        expect(keyValueService.hasKey("name")).toBeFalse();
+        keyValueService.setKey("name", "defaultService2");
+
+        // take a copy to check later when service is accessed via a command
+        this.defaultService1!.copyOfKeyValueService = keyValueService;
+
+        serviceProvider1Initialised = true;
+        return Promise.resolve(undefined);
+      }
+    }
+
+    class ServiceProvider2 implements ServiceProvider {
+      readonly serviceId = SERVICE_2;
+      readonly servicePriority = 2;
+
+      defaultService2: DefaultService2 | undefined;
+
+      provide(_cliConfig: CLIConfig): Promise<ServiceInfo> {
+        this.defaultService2 = new DefaultService2();
+        return Promise.resolve({
+          service: this.defaultService2,
+          commands: [],
+        });
+      }
+
+      initService(context: Context): Promise<void> {
+        const keyValueService = context.getServiceById(
+          KEY_VALUE_SERVICE_ID,
+        ) as KeyValueService;
+
+        // should only have access to the ServiceProvider2 KV scope
+        expect(keyValueService.hasKey("name")).toBeFalse();
+        keyValueService.setKey("name", "defaultService2");
+
+        // take a copy to check later when service is accessed via a command
+        this.defaultService2!.copyOfKeyValueService = keyValueService;
+
+        serviceProvider2Initialised = true;
+        return Promise.resolve(undefined);
+      }
+    }
+
+    const modifierCommand = getGlobalModifierCommandWithArgument(
+      "modifier",
+      "m",
+      1,
+      {
+        type: ArgumentValueTypeName.STRING,
+      },
+    );
+    const option = {
+      name: "foo",
+      type: ArgumentValueTypeName.STRING,
+      shortAlias: "f",
+    };
+    const subCommand = getSubCommand("command", [option], []);
+
+    modifierCommand.execute = (context): Promise<void> => {
+      const keyValueService = context.getServiceById(
+        KEY_VALUE_SERVICE_ID,
+      ) as KeyValueService;
+
+      // should only have access to the modifierCommand KV scope
+      expect(keyValueService.hasKey("name")).toBeFalse();
+      keyValueService.setKey("name", "modifierCommand");
+
+      const service1 = context.getServiceById(SERVICE_1) as ServiceInterface;
+
+      service1.serviceMethod(context);
+
+      modifierHasRun = true;
+      return Promise.resolve();
+    };
+    subCommand.execute = (context): Promise<void> => {
+      const keyValueService = context.getServiceById(
+        KEY_VALUE_SERVICE_ID,
+      ) as KeyValueService;
+
+      // should only have access to the subCommand KV scope
+      expect(keyValueService.hasKey("name")).toBeFalse();
+      keyValueService.setKey("name", "subCommand");
+
+      const service2 = context.getServiceById(SERVICE_2) as ServiceInterface;
+
+      service2.serviceMethod(context);
+
+      subHasRun = true;
+      return Promise.resolve();
+    };
+
+    baseCLI.addServiceProvider(new ServiceProvider1());
+    baseCLI.addServiceProvider(new ServiceProvider2());
+    baseCLI.addCommand(modifierCommand);
+    baseCLI.addCommand(subCommand);
+
+    const runResult = await baseCLI.run([
+      "unused",
+      "--modifier=bar",
+      "command",
+      "--foo",
+      "bar",
+    ]);
+
+    expect(runResult.runState).toEqual(RunState.SUCCESS);
+    expect(serviceProvider1Initialised).toBeTrue();
+    expect(serviceProvider2Initialised).toBeTrue();
+    expect(modifierHasRun).toBeTrue();
+    expect(service1MethodInvoked).toBeTrue();
+    expect(subHasRun).toBeTrue();
+    expect(service2MethodInvoked).toBeTrue();
+
+    // cleanup
+    await fs.rm(
+      path.join(process.env.HOME!, `.${appName.replace(/\W/g, "")}.json`),
+    );
+  });
+});