task-script-support-cli 0.3.0 → 0.3.2

package/assets/yargs-template/task-runner/src/commands/verify.ts

@@ -1,10 +1,11 @@
 import { singleton } from "tsyringe";
 import { Command } from "../wrappers/command";
 import CheckEnv from "../tasks/check-env";
-import PrintBanner from "../tasks/print-banner";
+import PrintBanner from "../tasks/banner/print-banner";
 import LogState from "../tasks/log-state";
+import ResolveBannerFont from "../tasks/banner/resolve-banner-font";
 
 @singleton()
 export class VerifyCommand extends Command {
-  tasks = [PrintBanner, CheckEnv, LogState];
+  tasks = [ResolveBannerFont, PrintBanner, CheckEnv, LogState];
 }

package/assets/yargs-template/task-runner/src/services/banner-service.ts

@@ -1,17 +1,21 @@
 import { singleton } from "tsyringe";
 import figlet from "figlet";
 
+/**
+ * BannerService
+ *
+ * Handles the generation of banner text using figlet.
+ *
+ * Some figlet fonts to try:
+ *     ["ANSI Compact", "AMC Slash", "ANSI Shadow",
+ *     "Basic", "Big", "Bell", "Calvin S", "Coinstak",
+ *     "DOS Rebel", "Elite", "Emboss", "Future Smooth",
+ *     "Kban", "Larry 3D 2", "Mono 9", "Shadow",
+ *     "Small Poison", "Star Wars"]
+ */
 @singleton()
 export class BannerService {
-  _selectFonts = [
-    "AMC Slash",
-    "Calvin S",
-    "Bell",
-    "Pagga",
-    "Shadow",
-    "Small Block",
-  ];
-  defaultFontFamily: string = "Cybermedium";
+  defaultFontFamily: string = "Standard";
 
   async toBanner(text: string, font?: string): Promise<string> {
     return await figlet.text(text, {

package/assets/yargs-template/task-runner/src/tasks/banner/print-banner.ts

@@ -0,0 +1,38 @@
+import { autoInjectable } from "tsyringe";
+import { AppState } from "../../types/state";
+import { AppTask } from "../../wrappers/app-task";
+import { BannerService } from "../../services/banner-service";
+import { UtilService } from "../../services/util-service";
+import chalk from "chalk";
+
+/**
+ * Prints an app banner to the console
+ */
+@autoInjectable()
+export default class PrintBanner extends AppTask {
+  loggerName = "Print Banner";
+
+  constructor(
+    private bannerService: BannerService,
+    private utilService: UtilService,
+  ) {
+    super();
+  }
+
+  async run({ data: { banner } }: AppState): Promise<Partial<AppState> | void> {
+    try {
+      console.log(
+        chalk.blueBright(
+          await this.bannerService.toBanner(
+            this.utilService.getAppName(),
+            banner?.font,
+          ),
+        ),
+      );
+
+      this.setData({ banner: { status: "success" } });
+    } catch (err) {
+      this.setData({ banner: { status: "failed" }, errorMessages: [`${err}`] });
+    }
+  }
+}

package/assets/yargs-template/task-runner/src/tasks/banner/resolve-banner-font.ts

@@ -0,0 +1,70 @@
+import { autoInjectable } from "tsyringe";
+import { BannerService } from "../../services/banner-service";
+import ResolverTask from "../../wrappers/electives/resolver-task";
+import { CLIArgs } from "../../types/state";
+
+/**
+ * ResolveBannerFont (Optional ResolverTask Pattern)
+ *
+ * ResolverTask that updates the AppStateData banner field. Resolves the banner
+ * font field via user input (bannerFont arg) or a randomly selected font value
+ * (randomFont arg). Uses BannerService's default otherwise. Doesn't define an
+ * envVar so doesn't support env overrides.
+ */
+@autoInjectable()
+export default class ResolveBannerFont extends ResolverTask {
+  loggerName = "ResolveBannerFont";
+
+  resolveTo = "banner" as const;
+  argVar = "bannerFont" as const;
+
+  constructor(private bannerService: BannerService) {
+    super();
+  }
+
+  /**
+   * Get the default banner font value.
+   */
+  //@override
+  async getDefaultValue<T>(): Promise<T | undefined> {
+    return { font: this.bannerService.defaultFontFamily } as T;
+  }
+
+  /**
+   * Attempt to resolve the font from the CLI args.
+   *
+   * @param args the CLIArgs to resolve from.
+   * @returns the resolved font, or undefined if no font args provided
+   */
+  //@override
+  async getArg<T>(args: CLIArgs) {
+    const bannerFont = args.bannerFont;
+    if (bannerFont) {
+      await this.validateFont(bannerFont);
+      return { font: bannerFont } as T;
+    }
+
+    // also allow --random-font arg as an override
+    if (args.randomFont) {
+      const randomFont = await this.bannerService.getRandomFont();
+      this.logger.debug(`Using random font ${randomFont}`);
+      return { font: randomFont } as T;
+    }
+
+    return undefined;
+  }
+
+  /**
+   * Validate a provided font is supported.
+   *
+   * @param font the font to validate.
+   * @throws Error if the font is not supported.
+   */
+  async validateFont(font: string): Promise<void> {
+    const availableFonts = await this.bannerService.getSupportedFonts();
+
+    if (!availableFonts.includes(font)) {
+      throw new Error(`Unsupported font provided: ${font}`);
+    }
+  }
+}

package/assets/yargs-template/task-runner/src/types/state.ts

@@ -31,6 +31,10 @@ export const EnvironmentConfigKeys = {
   PINO_LOG_TARGET: "PINO_LOG_TARGET",
 };
 
+export const DefaultValues = {
+  debugMode: false,
+};
+
 export type AppTaskClass = TaskClass<AppStateData, CLIArgs>;
 
 export type Yargs = typeof yargs;

package/{dist/assets/yargs-template/task-runner/src/wrappers → assets/yargs-template/task-runner/src/wrappers/electives}/concurrent-task-group.ts

@@ -1,13 +1,13 @@
-import { AppTask } from "./app-task";
+import { AppTask } from "../app-task";
 import { autoInjectable } from "tsyringe";
-import { AppTaskClass } from "../types/state";
+import { AppTaskClass } from "../../types/state";
 
 /**
  * Wrapper for Running a Group of Concurrent Tasks
  *
- * Extend this class and override the tasks array to run tasks
+ * Extend this class and override the tasks field to run tasks
  * concurrently within a Task itself. The fallback run method
- * handles state and execution of the tasks.
+ * handles the state and execution of the tasks.
  */
 @autoInjectable()
 export default class ConcurrentTaskGroup extends AppTask {

package/assets/yargs-template/task-runner/src/wrappers/electives/resolver-task.ts

@@ -0,0 +1,87 @@
+import {
+  AppState,
+  AppStateData,
+  CLIArgs,
+  DefaultValues,
+  EnvironmentConfigKeys,
+} from "../../types/state";
+import { AppTask } from "../app-task";
+import { autoInjectable } from "tsyringe";
+
+/**
+ * ResolverTask
+ *
+ * Wrapper Task that resolves a value in the AppStateData.
+ *
+ * Allows enforcing the following order of precedence for resolving a value:
+ * - CLI arg (if provided)
+ * - Environment variable (if set)
+ * - Default / Fallback value
+ */
+@autoInjectable()
+export default class ResolverTask extends AppTask {
+  loggerName = "Resolver";
+
+  /*
+    Extend the class and override the following fields to customize the resolver.
+  */
+
+  // the target field to resolve on AppStateData
+  declare resolveTo: keyof AppStateData;
+
+  // arg override has highest precedence
+  declare argVar?: keyof CLIArgs;
+
+  // then env override
+  declare envVar?: keyof typeof EnvironmentConfigKeys;
+
+  // finally, a default fallback value can be provided
+  declare defaultKey?: keyof typeof DefaultValues;
+
+  /*
+    Optionally, override these methods to customize additional behavior of the resolver.
+  */
+  async getDefaultValue<T>(): Promise<T | undefined> {
+    return this.defaultKey ? (DefaultValues[this.defaultKey] as T) : undefined;
+  }
+  async getArg<T>(args: CLIArgs): Promise<T | undefined> {
+    if (this.argVar && args[this.argVar]) {
+      return args[this.argVar] as T;
+    }
+  }
+  async getEnv<T>(): Promise<T | undefined> {
+    if (this.envVar && process.env[this.envVar]) {
+      return process.env[this.envVar] as T;
+    }
+  }
+
+  /*
+    The ResolverTask run method keeps the resolution order consistent across all
+    resolver tasks. It should not be overridden subclasses.
+  */
+  async run(): Promise<Partial<AppState> | void> {
+    const argResult = await this.getArg(this.state.args);
+    if (argResult) {
+      return {
+        data: {
+          [this.resolveTo]: argResult,
+        },
+      };
+    }
+
+    const envResult = await this.getEnv();
+    if (envResult) {
+      return {
+        data: {
+          [this.resolveTo]: envResult,
+        },
+      };
+    }
+
+    return {
+      data: {
+        [this.resolveTo]: await this.getDefaultValue(),
+      },
+    };
+  }
+}

package/assets/yargs-template/task-runner/src/wrappers/{sequential-task-group.ts → electives/sequential-task-group.ts}

@@ -1,12 +1,12 @@
-import { AppTask } from "./app-task";
+import { AppTask } from "../app-task";
 import { autoInjectable } from "tsyringe";
-import { AppTaskClass } from "../types/state";
+import { AppTaskClass } from "../../types/state";
 
 /**
  * Wrapper for Running a Group of Sequential Tasks
  *
- * Extend this class and override the tasks array to run a sequence
- * of tasks in order as a Task. The fallback run method handles state
+ * Extend this class and override the tasks field to run a sequence
+ * of tasks in order as a Task. The fallback run method handles the state
  * and execution of the tasks.
  */
 @autoInjectable()

package/assets/yargs-template/task-runner/tests/commands/verify.test.ts

@@ -1,41 +1,34 @@
 /* eslint-disable @typescript-eslint/no-explicit-any */
 import { describe, it, expect, vi } from "vitest";
-import PrintBanner from "../../src/tasks/print-banner";
+import PrintBanner from "../../src/tasks/banner/print-banner";
 import CheckEnv from "../../src/tasks/check-env";
 import { container } from "tsyringe";
-import { CommandService } from "task-script-support";
-import { AppStateData, CLIArgs } from "../../src/types/state";
+import ResolveBannerFont from "../../src/tasks/banner/resolve-banner-font";
+import { VerifyCommand } from "../../src/commands/verify";
+import { CLIArgs } from "../../src/types/state";
 
-// Mock the tasks and their run methods
-vi.mock("../../src/tasks/print-banner", () => {
-  const PrintBannerMock = vi.fn();
-  PrintBannerMock.prototype.run = vi.fn();
-  return { default: PrintBannerMock };
-});
-
-vi.mock("../../src/tasks/check-env", () => {
-  const CheckEnvMock = vi.fn();
-  CheckEnvMock.prototype.run = vi.fn();
-  return { default: CheckEnvMock };
-});
+vi.mock("../../src/tasks/banner/resolve-banner-font");
+vi.mock("../../src/tasks/banner/print-banner");
+vi.mock("../../src/tasks/check-env");
+vi.mock("../../src/tasks/log-state");
 
 describe("verify command", () => {
   it("should run PrintBanner and then CheckEnv", async () => {
-    const tasks = [PrintBanner, CheckEnv];
-    container.register("Args", { useValue: [] });
+    const args: CLIArgs[] = [];
 
+    container.register("Args", { useValue: args });
     // when
-    await new CommandService<AppStateData, CLIArgs>().runTasks(
-      tasks,
-      {} as CLIArgs,
-    );
+    await container.resolve(VerifyCommand).handler(args);
 
     expect(PrintBanner).toHaveBeenCalled();
     expect(CheckEnv).toHaveBeenCalled();
 
     const printBannerInstance = (PrintBanner as any).mock.instances[0];
     const checkEnvInstance = (CheckEnv as any).mock.instances[0];
+    const resolveBannerFontInstance = (ResolveBannerFont as any).mock
+      .instances[0];
 
+    expect(resolveBannerFontInstance.run).toHaveBeenCalled();
     expect(printBannerInstance.run).toHaveBeenCalled();
     expect(checkEnvInstance.run).toHaveBeenCalled();
   });

package/dist/assets/yargs-template/task-runner/src/commands/verify.ts

@@ -1,10 +1,11 @@
 import { singleton } from "tsyringe";
 import { Command } from "../wrappers/command";
 import CheckEnv from "../tasks/check-env";
-import PrintBanner from "../tasks/print-banner";
+import PrintBanner from "../tasks/banner/print-banner";
 import LogState from "../tasks/log-state";
+import ResolveBannerFont from "../tasks/banner/resolve-banner-font";
 
 @singleton()
 export class VerifyCommand extends Command {
-  tasks = [PrintBanner, CheckEnv, LogState];
+  tasks = [ResolveBannerFont, PrintBanner, CheckEnv, LogState];
 }

package/dist/assets/yargs-template/task-runner/src/services/banner-service.ts

@@ -1,17 +1,21 @@
 import { singleton } from "tsyringe";
 import figlet from "figlet";
 
+/**
+ * BannerService
+ *
+ * Handles the generation of banner text using figlet.
+ *
+ * Some figlet fonts to try:
+ *     ["ANSI Compact", "AMC Slash", "ANSI Shadow",
+ *     "Basic", "Big", "Bell", "Calvin S", "Coinstak",
+ *     "DOS Rebel", "Elite", "Emboss", "Future Smooth",
+ *     "Kban", "Larry 3D 2", "Mono 9", "Shadow",
+ *     "Small Poison", "Star Wars"]
+ */
 @singleton()
 export class BannerService {
-  _selectFonts = [
-    "AMC Slash",
-    "Calvin S",
-    "Bell",
-    "Pagga",
-    "Shadow",
-    "Small Block",
-  ];
-  defaultFontFamily: string = "Cybermedium";
+  defaultFontFamily: string = "Standard";
 
   async toBanner(text: string, font?: string): Promise<string> {
     return await figlet.text(text, {

package/dist/assets/yargs-template/task-runner/src/tasks/banner/print-banner.ts

@@ -0,0 +1,38 @@
+import { autoInjectable } from "tsyringe";
+import { AppState } from "../../types/state";
+import { AppTask } from "../../wrappers/app-task";
+import { BannerService } from "../../services/banner-service";
+import { UtilService } from "../../services/util-service";
+import chalk from "chalk";
+
+/**
+ * Prints an app banner to the console
+ */
+@autoInjectable()
+export default class PrintBanner extends AppTask {
+  loggerName = "Print Banner";
+
+  constructor(
+    private bannerService: BannerService,
+    private utilService: UtilService,
+  ) {
+    super();
+  }
+
+  async run({ data: { banner } }: AppState): Promise<Partial<AppState> | void> {
+    try {
+      console.log(
+        chalk.blueBright(
+          await this.bannerService.toBanner(
+            this.utilService.getAppName(),
+            banner?.font,
+          ),
+        ),
+      );
+
+      this.setData({ banner: { status: "success" } });
+    } catch (err) {
+      this.setData({ banner: { status: "failed" }, errorMessages: [`${err}`] });
+    }
+  }
+}

package/dist/assets/yargs-template/task-runner/src/tasks/banner/resolve-banner-font.ts

@@ -0,0 +1,70 @@
+import { autoInjectable } from "tsyringe";
+import { BannerService } from "../../services/banner-service";
+import ResolverTask from "../../wrappers/electives/resolver-task";
+import { CLIArgs } from "../../types/state";
+
+/**
+ * ResolveBannerFont (Optional ResolverTask Pattern)
+ *
+ * ResolverTask that updates the AppStateData banner field. Resolves the banner
+ * font field via user input (bannerFont arg) or a randomly selected font value
+ * (randomFont arg). Uses BannerService's default otherwise. Doesn't define an
+ * envVar so doesn't support env overrides.
+ */
+@autoInjectable()
+export default class ResolveBannerFont extends ResolverTask {
+  loggerName = "ResolveBannerFont";
+
+  resolveTo = "banner" as const;
+  argVar = "bannerFont" as const;
+
+  constructor(private bannerService: BannerService) {
+    super();
+  }
+
+  /**
+   * Get the default banner font value.
+   */
+  //@override
+  async getDefaultValue<T>(): Promise<T | undefined> {
+    return { font: this.bannerService.defaultFontFamily } as T;
+  }
+
+  /**
+   * Attempt to resolve the font from the CLI args.
+   *
+   * @param args the CLIArgs to resolve from.
+   * @returns the resolved font, or undefined if no font args provided
+   */
+  //@override
+  async getArg<T>(args: CLIArgs) {
+    const bannerFont = args.bannerFont;
+    if (bannerFont) {
+      await this.validateFont(bannerFont);
+      return { font: bannerFont } as T;
+    }
+
+    // also allow --random-font arg as an override
+    if (args.randomFont) {
+      const randomFont = await this.bannerService.getRandomFont();
+      this.logger.debug(`Using random font ${randomFont}`);
+      return { font: randomFont } as T;
+    }
+
+    return undefined;
+  }
+
+  /**
+   * Validate a provided font is supported.
+   *
+   * @param font the font to validate.
+   * @throws Error if the font is not supported.
+   */
+  async validateFont(font: string): Promise<void> {
+    const availableFonts = await this.bannerService.getSupportedFonts();
+
+    if (!availableFonts.includes(font)) {
+      throw new Error(`Unsupported font provided: ${font}`);
+    }
+  }
+}

package/dist/assets/yargs-template/task-runner/src/types/state.ts

@@ -31,6 +31,10 @@ export const EnvironmentConfigKeys = {
   PINO_LOG_TARGET: "PINO_LOG_TARGET",
 };
 
+export const DefaultValues = {
+  debugMode: false,
+};
+
 export type AppTaskClass = TaskClass<AppStateData, CLIArgs>;
 
 export type Yargs = typeof yargs;

package/{assets/yargs-template/task-runner/src/wrappers → dist/assets/yargs-template/task-runner/src/wrappers/electives}/concurrent-task-group.ts

@@ -1,13 +1,13 @@
-import { AppTask } from "./app-task";
+import { AppTask } from "../app-task";
 import { autoInjectable } from "tsyringe";
-import { AppTaskClass } from "../types/state";
+import { AppTaskClass } from "../../types/state";
 
 /**
  * Wrapper for Running a Group of Concurrent Tasks
  *
- * Extend this class and override the tasks array to run tasks
+ * Extend this class and override the tasks field to run tasks
  * concurrently within a Task itself. The fallback run method
- * handles state and execution of the tasks.
+ * handles the state and execution of the tasks.
  */
 @autoInjectable()
 export default class ConcurrentTaskGroup extends AppTask {

package/dist/assets/yargs-template/task-runner/src/wrappers/electives/resolver-task.ts

@@ -0,0 +1,87 @@
+import {
+  AppState,
+  AppStateData,
+  CLIArgs,
+  DefaultValues,
+  EnvironmentConfigKeys,
+} from "../../types/state";
+import { AppTask } from "../app-task";
+import { autoInjectable } from "tsyringe";
+
+/**
+ * ResolverTask
+ *
+ * Wrapper Task that resolves a value in the AppStateData.
+ *
+ * Allows enforcing the following order of precedence for resolving a value:
+ * - CLI arg (if provided)
+ * - Environment variable (if set)
+ * - Default / Fallback value
+ */
+@autoInjectable()
+export default class ResolverTask extends AppTask {
+  loggerName = "Resolver";
+
+  /*
+    Extend the class and override the following fields to customize the resolver.
+  */
+
+  // the target field to resolve on AppStateData
+  declare resolveTo: keyof AppStateData;
+
+  // arg override has highest precedence
+  declare argVar?: keyof CLIArgs;
+
+  // then env override
+  declare envVar?: keyof typeof EnvironmentConfigKeys;
+
+  // finally, a default fallback value can be provided
+  declare defaultKey?: keyof typeof DefaultValues;
+
+  /*
+    Optionally, override these methods to customize additional behavior of the resolver.
+  */
+  async getDefaultValue<T>(): Promise<T | undefined> {
+    return this.defaultKey ? (DefaultValues[this.defaultKey] as T) : undefined;
+  }
+  async getArg<T>(args: CLIArgs): Promise<T | undefined> {
+    if (this.argVar && args[this.argVar]) {
+      return args[this.argVar] as T;
+    }
+  }
+  async getEnv<T>(): Promise<T | undefined> {
+    if (this.envVar && process.env[this.envVar]) {
+      return process.env[this.envVar] as T;
+    }
+  }
+
+  /*
+    The ResolverTask run method keeps the resolution order consistent across all
+    resolver tasks. It should not be overridden subclasses.
+  */
+  async run(): Promise<Partial<AppState> | void> {
+    const argResult = await this.getArg(this.state.args);
+    if (argResult) {
+      return {
+        data: {
+          [this.resolveTo]: argResult,
+        },
+      };
+    }
+
+    const envResult = await this.getEnv();
+    if (envResult) {
+      return {
+        data: {
+          [this.resolveTo]: envResult,
+        },
+      };
+    }
+
+    return {
+      data: {
+        [this.resolveTo]: await this.getDefaultValue(),
+      },
+    };
+  }
+}

package/dist/assets/yargs-template/task-runner/src/wrappers/{sequential-task-group.ts → electives/sequential-task-group.ts}

@@ -1,12 +1,12 @@
-import { AppTask } from "./app-task";
+import { AppTask } from "../app-task";
 import { autoInjectable } from "tsyringe";
-import { AppTaskClass } from "../types/state";
+import { AppTaskClass } from "../../types/state";
 
 /**
  * Wrapper for Running a Group of Sequential Tasks
  *
- * Extend this class and override the tasks array to run a sequence
- * of tasks in order as a Task. The fallback run method handles state
+ * Extend this class and override the tasks field to run a sequence
+ * of tasks in order as a Task. The fallback run method handles the state
  * and execution of the tasks.
  */
 @autoInjectable()