0z2i6v3u5t 1.0.0

package/src/actions/swagger.ts

@@ -0,0 +1,155 @@
+import { Action, config, api, RouteType } from "./../index";
+import * as fs from "fs";
+import * as path from "path";
+import { PackageJson } from "type-fest";
+
+const SWAGGER_VERSION = "2.0";
+const API_VERSION = ""; // if you need a prefix to your API routes, like `v1`
+const parentPackageJSON: PackageJson = JSON.parse(
+  fs.readFileSync(path.join(__dirname, "..", "..", "package.json")).toString(),
+);
+
+const responses = {
+  200: {
+    description: "successful operation",
+  },
+  400: {
+    description: "Invalid input",
+  },
+  404: {
+    description: "Not Found",
+  },
+  422: {
+    description: "Missing or invalid params",
+  },
+  500: {
+    description: "Server error",
+  },
+};
+
+export class Swagger extends Action {
+  name = "swagger";
+  description = "return API documentation in the OpenAPI specification";
+  outputExample = {};
+
+  getLatestAction(route: RouteType) {
+    let matchedAction: Action;
+    Object.keys(api.actions.actions).forEach((actionName) => {
+      Object.keys(api.actions.actions[actionName]).forEach((version) => {
+        const action = api.actions.actions[actionName][version];
+        if (action.name === route.action) {
+          matchedAction = action;
+        }
+      });
+    });
+
+    return matchedAction;
+  }
+
+  buildSwaggerPaths() {
+    const swaggerPaths: {
+      [path: string]: {
+        [method: string]: {
+          tags: string[];
+          summary: string;
+          consumes: string[];
+          produces: string[];
+          parameters: Array<{
+            in: string;
+            name: string;
+            type: string;
+            required: boolean;
+            default: string | number | boolean;
+          }>;
+          responses: typeof responses;
+          security: string[];
+        };
+      };
+    } = {};
+    const tags: string[] = [];
+
+    for (const [method, routes] of Object.entries(api.routes.routes)) {
+      routes.map((route) => {
+        const action = this.getLatestAction(route);
+        if (!action) return;
+
+        const tag = action.name.split(":")[0];
+        const formattedPath = route.path
+          .replace("/v:apiVersion", "")
+          .replace(/\/:(\w*)/g, "/{$1}");
+
+        swaggerPaths[formattedPath] = swaggerPaths[formattedPath] || {};
+        swaggerPaths[formattedPath][method] = {
+          tags: [tag],
+          summary: action.description,
+          // description: action.description, // this is redundant
+          consumes: ["application/json"],
+          produces: ["application/json"],
+          parameters: Object.keys(action.inputs)
+            .sort()
+            .map((inputName) => {
+              return {
+                in: route.path.includes(`:${inputName}`) ? "path" : "query",
+                name: inputName,
+                type: "string", // not really true, but helps the swagger validator
+                required:
+                  action.inputs[inputName].required ||
+                  route.path.includes(`:${inputName}`)
+                    ? true
+                    : false,
+                default:
+                  action.inputs[inputName].default !== null &&
+                  action.inputs[inputName].default !== undefined
+                    ? typeof action.inputs[inputName].default === "object"
+                      ? JSON.stringify(action.inputs[inputName].default)
+                      : typeof action.inputs[inputName].default === "function"
+                        ? action.inputs[inputName].default()
+                        : `${action.inputs[inputName].default}`
+                    : undefined,
+              };
+            }),
+          responses,
+          security: [],
+        };
+
+        if (!tags.includes(tag)) {
+          tags.push(tag);
+        }
+      });
+    }
+
+    return { swaggerPaths, tags };
+  }
+
+  async run() {
+    const { swaggerPaths, tags } = this.buildSwaggerPaths();
+
+    return {
+      swagger: SWAGGER_VERSION,
+      info: {
+        description: parentPackageJSON.description,
+        version: parentPackageJSON.version,
+        title: parentPackageJSON.name,
+        license: { name: parentPackageJSON.license },
+      },
+      host:
+        config.web.allowedRequestHosts[0]
+          ?.replace("https://", "")
+          .replace("https://", "") ?? `localhost:${config.web.port}`,
+      basePath: `/api/${API_VERSION}`,
+      // tags: tags.map((tag) => {
+      //   return { name: tag, description: `topic: ${tag}` };
+      // }),
+      schemes: config.web.allowedRequestHosts[0] ? ["https", "http"] : ["http"],
+      paths: swaggerPaths,
+
+      securityDefinitions: {
+        // TODO (custom)?
+      },
+      externalDocs: {
+        description: "Learn more about Actionhero",
+        url: "https://www.actionherojs.com",
+      },
+    };
+  }
+}

package/src/actions/validationTest.ts

@@ -0,0 +1,36 @@
+import { Action } from "./../index";
+
+export class ValidationTest extends Action {
+  name = "validationTest";
+  description = "I will test action input validators.";
+  inputs = {
+    string: {
+      required: true as true,
+      validator: (param: string) => {
+        return typeof param === "string";
+      },
+    },
+    number: {
+      required: false,
+      formatter: (param: string, name: string) => {
+        if (parseInt(param) == 123) {
+          throw new Error(`Failed formatting ${name} correctly!`);
+        }
+        return parseInt(param);
+      },
+      validator: (param: number, name: string) => {
+        if (typeof param === "number") {
+          throw new Error(`Param ${name} is not a valid number!`);
+        }
+      },
+    },
+  };
+  outputExample = {
+    string: "imAString!",
+    number: 2,
+  };
+
+  async run({ params }: { params: { string: string; number: number } }) {
+    return { string: params.string, number: params.number };
+  }
+}

package/src/bin/actionhero.ts

@@ -0,0 +1,225 @@
+#!/usr/bin/env node
+
+import * as path from "path";
+import * as fs from "fs";
+import { program, InvalidArgumentError } from "commander";
+import { typescript } from "../classes/process/typescript";
+import { projectRoot } from "../classes/process/projectRoot";
+import { ensureNoTsHeaderOrSpecFiles } from "../modules/utils/ensureNoTsHeaderOrSpecFiles";
+import { CLI } from "../classes/cli";
+import { PackageJson } from "type-fest";
+
+// load explicitly to find the type changes for the config module
+import "../config/api";
+import "../config/plugins";
+import "../config/logger";
+import "../config/routes";
+import { safeGlobSync } from "../modules/utils/safeGlob";
+
+export namespace ActionheroCLIRunner {
+  export async function run() {
+    program.storeOptionsAsProperties(false);
+    program.version(getVersion());
+
+    let pathsLoaded: string[] = [];
+    try {
+      const { config } = await import("../index");
+
+      // this project
+      for (const p of config.general.paths.cli) {
+        await loadDirectory(path.join(p), pathsLoaded);
+      }
+
+      // plugins
+      for (const plugin of Object.values(config.plugins)) {
+        if (plugin.cli !== false) {
+          // old plugins
+          await loadDirectory(path.join(plugin.path, "bin"), pathsLoaded);
+          // new plugins
+          await loadDirectory(
+            path.join(plugin.path, "dist", "bin"),
+            pathsLoaded,
+          );
+        }
+      }
+
+      // core
+      if (config.general.cliIncludeInternal !== false) {
+        await loadDirectory(__dirname, pathsLoaded);
+      }
+    } catch (e) {
+      // we are trying to build a new project, only load the generate command
+      await loadDirectory(path.join(__dirname), pathsLoaded, "generate");
+    }
+
+    program.parse(process.argv);
+  }
+
+  // --- Utils --- //
+
+  export async function loadDirectory(
+    dir: string,
+    pathsLoaded: string[],
+    match = "*",
+  ) {
+    if (!fs.existsSync(dir)) return;
+    const realpath = fs.realpathSync(dir);
+    if (pathsLoaded.includes(realpath)) return;
+    pathsLoaded.push(realpath);
+
+    const matcher = `${realpath}/**/+(${
+      typescript ? `${match}.js|*.ts` : `${match}.js`
+    })`;
+    const files = ensureNoTsHeaderOrSpecFiles(safeGlobSync(matcher));
+    for (const i in files) {
+      const collection = await import(files[i]);
+      for (const j in collection) {
+        const command = collection[j];
+        convertCLIToCommanderAction(command);
+      }
+    }
+  }
+
+  export async function convertCLIToCommanderAction(
+    cliConstructor: new () => CLI,
+  ) {
+    if (
+      Object.getPrototypeOf(cliConstructor?.prototype?.constructor || {})
+        .name !== "CLI"
+    ) {
+      return;
+    }
+
+    const instance: CLI = new cliConstructor();
+    const command = program
+      .command(instance.name)
+      .description(instance.description)
+      .action(async (_arg1, _arg2, _arg3, _arg4, _arg5) => {
+        await runCommand(instance, _arg1, _arg2, _arg3, _arg4, _arg5);
+      })
+      .on("--help", () => {
+        if (instance.example) {
+          console.log("");
+          console.log("Example: \r\n" + "  " + instance.example);
+        }
+        if (typeof instance.help === "function") instance.help();
+      });
+
+    for (const key in instance.inputs) {
+      const input = instance.inputs[key];
+
+      if (input.flag && !input.letter) {
+        throw new Error(
+          `flag inputs require a short letter (${JSON.stringify(input)})`,
+        );
+      }
+
+      const separators =
+        input.required || input.requiredValue ? ["<", ">"] : ["[", "]"];
+      const methodName = input.required ? "requiredOption" : "option";
+      const argString = `${input.letter ? `-${input.letter}, ` : ""}--${key} ${
+        input.flag
+          ? ""
+          : `${separators[0]}${input.placeholder || key}${
+              input.variadic ? "..." : ""
+            }${separators[1]}`
+      }`;
+
+      const argProcessor = (
+        value: string,
+        accumulator?: unknown[],
+      ): unknown => {
+        try {
+          if (typeof input.formatter === "function") {
+            value = input.formatter(value);
+          }
+
+          if (typeof input.validator === "function") {
+            input.validator(value);
+          }
+
+          if (input.variadic) {
+            if (!Array.isArray(accumulator)) accumulator = [];
+            accumulator.push(value);
+            return accumulator;
+          }
+
+          return value;
+        } catch (error) {
+          throw new InvalidArgumentError(error?.message ?? error);
+        }
+      };
+
+      command[methodName](
+        argString,
+        input.description,
+        argProcessor,
+        input.default,
+      );
+    }
+  }
+
+  export async function runCommand(
+    instance: CLI,
+    _arg1: any,
+    _arg2: any,
+    _arg3: any,
+    _arg4: any,
+    _arg5: any,
+  ) {
+    let toStop = false;
+
+    let _arguments: string[] = [];
+    let params: Record<string, string[]> = {};
+    [_arg1, _arg2, _arg3, _arg4, _arg5].forEach((arg) => {
+      if (typeof arg?.opts === "function") {
+        params = arg.opts();
+      } else if (arg !== null && arg !== undefined && typeof arg !== "object") {
+        _arguments.push(arg);
+      }
+    });
+
+    params["_arguments"] = _arguments;
+
+    if (instance.initialize === false && instance.start === false) {
+      toStop = await instance.run({ params });
+    } else {
+      try {
+        const { Process } = await import("../index");
+        const actionHeroProcess = new Process();
+
+        if (instance.initialize) await actionHeroProcess.initialize();
+        if (instance.start) await actionHeroProcess.start();
+
+        toStop = await instance.run({ params });
+      } catch (error) {
+        console.error(error.toString());
+        process.exit(1);
+      }
+    }
+
+    if (toStop || toStop === null || toStop === undefined) {
+      setTimeout(process.exit, 500, 0);
+    }
+  }
+
+  export function readPackageJSON(file: string) {
+    return JSON.parse(fs.readFileSync(file).toString());
+  }
+
+  export function getVersion(): string {
+    const parentPackageJSON = path.join(projectRoot, "package.json");
+
+    if (fs.existsSync(parentPackageJSON)) {
+      const pkg: PackageJson = readPackageJSON(parentPackageJSON);
+      return pkg.version;
+    } else {
+      const pkg: PackageJson = readPackageJSON(
+        path.join(__dirname, "..", "..", "package.json"),
+      );
+      return pkg.version;
+    }
+  }
+}
+
+ActionheroCLIRunner.run();

package/src/bin/methods/actions/list.ts

@@ -0,0 +1,30 @@
+import { api, CLI } from "./../../../index";
+
+export class ActionsListCLI extends CLI {
+  constructor() {
+    super();
+    this.name = "actions-list";
+    this.description = "List the actions defined on this server";
+  }
+
+  async run() {
+    for (const actionName in api.actions.actions) {
+      console.log(`\r\n--- ${actionName} ---`);
+      const collection = api.actions.actions[actionName];
+
+      for (const version in collection) {
+        const action = collection[version];
+        console.info(`  version: ${version}`);
+        console.info(`    ${action.description}`);
+        console.info("    inputs:");
+        for (const input in action.inputs) {
+          console.info(
+            `      ${input}: ${JSON.stringify(action.inputs[input])}`,
+          );
+        }
+      }
+    }
+
+    return true;
+  }
+}

package/src/bin/methods/console.ts

@@ -0,0 +1,26 @@
+import * as REPL from "repl";
+import { api, env, CLI } from "./../../index";
+
+export class ConsoleCLI extends CLI {
+  name = "console";
+  description =
+    "Start an interactive REPL session with the api object in-scope";
+
+  async run() {
+    await new Promise((resolve, reject) => {
+      const repl = REPL.start({
+        prompt: "[ AH::" + env + " ] >> ",
+        input: process.stdin,
+        output: process.stdout,
+        useGlobal: false,
+      });
+
+      repl.context.api = api;
+
+      repl.on("exit", resolve);
+      repl.on("error", reject);
+    });
+
+    return true;
+  }
+}

package/src/bin/methods/generate/action.ts

@@ -0,0 +1,58 @@
+import * as fs from "fs";
+import * as path from "path";
+import { config, utils, CLI, ParamsFrom } from "./../../../index";
+
+export class GenerateActionCLI extends CLI {
+  name = "generate-action";
+  description = "Generate a new Action";
+  example =
+    "actionhero generate action --name=<name> --description=[description]";
+  inputs = {
+    name: {
+      required: true as true,
+      description: "The name of the Action to Generate",
+      letter: "n",
+    },
+    description: {
+      required: false,
+      description: "The description of the Action",
+      default: "an actionhero action",
+      letter: "d",
+    },
+  };
+
+  async run({ params }: { params: ParamsFrom<GenerateActionCLI> }) {
+    let actionTemplateBuffer = fs.readFileSync(
+      path.join(__dirname, "../../../../templates/action.ts.template"),
+    );
+    let actionTemplate = actionTemplateBuffer.toString();
+
+    let testTemplateBuffer = fs.readFileSync(
+      path.join(__dirname, "/../../../../templates/test/action.ts.template"),
+    );
+    let testTemplate = testTemplateBuffer.toString();
+
+    for (const [k, v] of Object.entries(params)) {
+      const regex = new RegExp("%%" + k + "%%", "g");
+      actionTemplate = actionTemplate.replace(regex, v);
+      testTemplate = testTemplate.replace(regex, v);
+    }
+
+    let message = utils.fileUtils.createFileSafely(
+      utils.replaceDistWithSrc(config.general.paths.action[0]) +
+        "/" +
+        params.name +
+        ".ts",
+      actionTemplate,
+    );
+    console.info(message);
+
+    message = utils.fileUtils.createFileSafely(
+      config.general.paths.test[0] + "/actions/" + params.name + ".ts",
+      testTemplate,
+    );
+    console.info(message);
+
+    return true;
+  }
+}

package/src/bin/methods/generate/cli.ts

@@ -0,0 +1,51 @@
+import * as fs from "fs";
+import * as path from "path";
+import { config, utils, ParamsFrom, CLI } from "./../../../index";
+
+export class GenerateCLICLI extends CLI {
+  name = "generate-cli";
+  description = "Generate a new cli command";
+  example = "actionhero generate cli --name=<name>";
+  inputs = {
+    name: {
+      required: true as true as true,
+      description: "The name of the CLI Command to generate",
+      letter: "n",
+    },
+    description: {
+      required: false,
+      description: "The name of the CLI Command",
+      default: "an actionhero cli command",
+      letter: "d",
+    },
+    example: {
+      required: false,
+      description: "An example to include for the CLI Command's help",
+      default: "actionhero command --option=yes",
+      letter: "e",
+    },
+  };
+
+  async run({ params }: { params: ParamsFrom<GenerateCLICLI> }) {
+    let templateBuffer = fs.readFileSync(
+      path.join(__dirname, "/../../../../templates/cli.ts.template"),
+    );
+
+    let template = templateBuffer.toString();
+
+    for (const [k, v] of Object.entries(params)) {
+      const regex = new RegExp("%%" + k + "%%", "g");
+      template = template.replace(regex, v);
+    }
+
+    const message = utils.fileUtils.createFileSafely(
+      utils.replaceDistWithSrc(
+        config.general.paths.cli[0] + "/" + params.name + ".ts",
+      ),
+      template,
+    );
+    console.log(message);
+
+    return true;
+  }
+}

package/src/bin/methods/generate/initializer.ts

@@ -0,0 +1,54 @@
+import * as fs from "fs";
+import * as path from "path";
+import { config, utils, CLI, ParamsFrom } from "./../../../index";
+
+export class GenerateInitializerCLI extends CLI {
+  name = "generate-initializer";
+  description = "Generate a new Initializer";
+  example =
+    "actionhero generate initializer --name=<name> --loadPriority=[p] --startPriority=[p] --stopPriority=[p]";
+  inputs = {
+    name: {
+      required: true as true,
+      description: "The name of the Initializer to generate",
+      letter: "n",
+    },
+    loadPriority: {
+      required: true as true,
+      description: "The order that this Initializer will initialize",
+      default: "1000",
+    },
+    startPriority: {
+      required: true as true,
+      description: "The order that this Initializer will start",
+      default: "1000",
+    },
+    stopPriority: {
+      required: true as true,
+      description: "The order that this Initializer will stop",
+      default: "1000",
+    },
+  };
+
+  async run({ params }: { params: ParamsFrom<GenerateInitializerCLI> }) {
+    let templateBuffer = fs.readFileSync(
+      path.join(__dirname, "/../../../../templates/initializer.ts.template"),
+    );
+    let template = String(templateBuffer);
+
+    for (const [k, v] of Object.entries(params)) {
+      const regex = new RegExp("%%" + k + "%%", "g");
+      template = template.replace(regex, v);
+    }
+
+    const message = utils.fileUtils.createFileSafely(
+      utils.replaceDistWithSrc(
+        config.general.paths.initializer[0] + "/" + params.name + ".ts",
+      ),
+      template,
+    );
+    console.log(message);
+
+    return true;
+  }
+}

package/src/bin/methods/generate/plugin.ts

@@ -0,0 +1,57 @@
+import * as fs from "fs";
+import * as path from "path";
+import { PackageJson } from "type-fest";
+import { CLI, utils } from "./../../../index";
+
+const PackageJSON: PackageJson = JSON.parse(
+  fs
+    .readFileSync(path.join(__dirname, "..", "..", "..", "..", "package.json"))
+    .toString(),
+);
+
+export class GeneratePluginCLI extends CLI {
+  name = "generate-plugin";
+  description =
+    "Generate the structure of a new actionhero plugin in an empty directory";
+  example = "actionhero generate plugin";
+
+  async run() {
+    let templateBuffer = fs.readFileSync(
+      path.join(
+        __dirname,
+        "/../../../../templates/package-plugin.json.template",
+      ),
+    );
+    let template = String(templateBuffer);
+
+    const regex = new RegExp("%%versionNumber%%", "g");
+    template = template.replace(regex, PackageJSON.version);
+
+    [
+      "actions",
+      "tasks",
+      "initializers",
+      "servers",
+      "config",
+      "bin",
+      "public",
+    ].forEach((type) => {
+      try {
+        const message = utils.fileUtils.createDirSafely(
+          path.join(process.cwd(), type),
+        );
+        console.info(message);
+      } catch (error) {
+        console.log(error.toString());
+      }
+    });
+
+    const message = utils.fileUtils.createFileSafely(
+      path.join(process.cwd(), "package.json"),
+      template,
+    );
+    console.info(message);
+
+    return true;
+  }
+}