fix: problems due to new version; feat: new cli utility

Author: js2me

cli/constants.js

@@ -0,0 +1,10 @@
+const root_command = Symbol("root");
+const skip_command = Symbol("skip");
+
+const reservedOptions = ["version", "help"];
+
+module.exports = {
+  root_command,
+  skip_command,
+  reservedOptions,
+};

cli/execute.js

@@ -0,0 +1,139 @@
+const _ = require("lodash");
+const { root_command, skip_command } = require("./constants");
+const { parseArgs } = require("./parse-args");
+const didYouMean = require("didyoumean");
+
+didYouMean.threshold = 0.5;
+
+const execute = (params, commands, instance) => {
+  const args = parseArgs(params.args, params.from);
+
+  return new Promise((resolve, reject) => {
+    const { command, usageOptions, error } = processArgs(commands, args);
+
+    if (error) {
+      reject(new Error(error));
+    }
+
+    if (!usageOptions.length && command.name === root_command) {
+      usageOptions.push(command.options.find((option) => option.flags.name === "help"));
+    }
+
+    const operationOptions = usageOptions.filter((option) => option.operation);
+    if (operationOptions.length) {
+      operationOptions[0].operation();
+      resolve({
+        command: skip_command,
+        options: {},
+      });
+      return;
+    } else {
+      let error = "";
+
+      const processUserOptionData = (data, option) => {
+        if (!data.length && !option.flags.value) {
+          return !option.flags.isNoFlag;
+        }
+        if (option.flags.value) {
+          if (option.flags.value.variadic) {
+            return data.reduce((acc, d) => {
+              acc.push(...d.split(",").map(option.flags.value.formatter));
+              return acc;
+            }, []);
+          } else {
+            return option.flags.value.formatter(data[0] || option.default);
+          }
+        }
+
+        return option.default;
+      };
+
+      const parsedOptionsObject = command.options.reduce((acc, option) => {
+        if (error) return acc;
+
+        const userOption = usageOptions.find((o) => o.flags.name === option.flags.name);
+
+        if (!userOption && option.required) {
+          error = `required option '${option.flags.raw}' not specified`;
+          return acc;
+        }
+
+        if (userOption) {
+          acc[option.flags.name] = processUserOptionData(userOption.$data, option);
+        } else {
+          acc[option.flags.name] = option.default;
+        }
+
+        return acc;
+      }, {});
+
+      if (error) {
+        reject(new Error(error));
+      } else {
+        resolve({
+          command: command.name === root_command ? null : command.name,
+          options: parsedOptionsObject,
+        });
+      }
+    }
+  });
+};
+
+const processArgs = (commands, args) => {
+  let command = null;
+  let usageOptions = [];
+  let walkingOption = null;
+  let error = "";
+
+  let allFlagKeys = [];
+
+  _.forEach(args, (arg, i) => {
+    if (error) return;
+
+    if (i === 0) {
+      command = commands[arg] || commands[root_command];
+      allFlagKeys = command.options.reduce((acc, option) => [...acc, ...option.flags.keys], []);
+    }
+    if (arg.startsWith("-")) {
+      const option = command.options.find((option) => option.flags.keys.includes(arg));
+
+      if (!option) {
+        const tip = didYouMean(arg, allFlagKeys);
+        error = `unknown option ${arg}${tip ? `\n(Did you mean ${tip} ?)` : ""}`;
+      }
+
+      if (option) {
+        if (walkingOption && walkingOption.flags.name === option.flags.name) {
+          return;
+        }
+        const existedOption = usageOptions.find((o) => o.flags.name === option.flags.name);
+        if (existedOption) {
+          walkingOption = existedOption;
+        } else {
+          walkingOption = {
+            ...option,
+            $data: [],
+          };
+          usageOptions.push(walkingOption);
+        }
+      }
+
+      return;
+    }
+
+    if (walkingOption) {
+      walkingOption.$data.push(arg);
+    }
+  });
+  command = command || commands[root_command];
+
+  return {
+    command,
+    usageOptions,
+    error,
+  };
+};
+
+module.exports = {
+  execute,
+};

cli/index.d.ts

@@ -0,0 +1,35 @@
+import { skip_command } from "./constants";
+
+type CliStructOption = {
+  flags?: string;
+  description?: string;
+  default?: unknown;
+};
+
+type CliStruct = {
+  inherited?: string | null;
+  name?: string;
+  alias?: string;
+  version?: string;
+  description?: string;
+  options: CliStructOption[];
+  commands?: CliStruct[];
+};
+
+type ExecuteOptions = {
+  args: string[];
+};
+
+type ExecuteOutput = {
+  command: null | string;
+  options: Record<string, any>;
+};
+
+type CliInstance = {
+  addCommand: (struct: CliStruct) => CliInstance;
+  execute: (options: ExecuteOptions) => Promise<ExecuteOutput>;
+};
+
+type Cli = <S extends Omit<CliStruct, "inherited">>(struct: S) => CliInstance;
+
+export declare const cli: Cli;

cli/index.js

@@ -0,0 +1,69 @@
+const _ = require("lodash");
+const { reservedOptions, root_command } = require("./constants");
+const { processOption } = require("./process-option");
+const { execute } = require("./execute");
+const { displayHelp } = require("./operations/display-help");
+const { displayVersion } = require("./operations/display-version");
+
+const cli = (input) => {
+  const commands = {};
+
+  const addCommand = (command) => {
+    commands[command.name] = {
+      name: command.name,
+      description: `${command.description || ""}`,
+      options: _.compact(_.map(command.options, processOption)),
+    };
+
+    return instance;
+  };
+
+  const instance = {
+    commands,
+    input,
+    addCommand,
+    execute: (params) => execute(params, commands, instance),
+  };
+
+  addCommand({
+    name: root_command,
+    options: [],
+  });
+
+  _.forEach(input.options, (option) => {
+    const processed = processOption(option);
+
+    if (!processed) return;
+
+    if (reservedOptions.includes(processed.name)) {
+      console.warn("reserved option", processed.name);
+      return;
+    }
+
+    commands[root_command].options.push(processed);
+  });
+
+  commands[root_command].options.unshift(
+    processOption({
+      flags: "-v, --version",
+      description: "output the current version",
+      operation: () => displayVersion(instance),
+    }),
+  );
+
+  commands[root_command].options.push(
+    processOption({
+      flags: "-h, --help",
+      description: "display help for command",
+      operation: () => displayHelp(commands, instance),
+    }),
+  );
+
+  _.forEach(input.commands, addCommand);
+
+  return instance;
+};
+
+module.exports = {
+  cli,
+};

cli/operations/display-help.js

@@ -0,0 +1,133 @@
+const _ = require("lodash");
+const { root_command } = require("../constants");
+
+const displayHelp = (commands, instance) => {
+  const generateOptionsOutput = (options) =>
+    options.reduce(
+      (acc, option) => {
+        const flags = `${option.flags.keys.join(", ")}${option.flags.value?.raw ? ` ${option.flags.value?.raw}` : ""}`;
+        const description = `${option.description || ""}${
+          option.default === undefined || (option.flags.isNoFlag && option.default === true)
+            ? ""
+            : ` (default: ${typeof option.default === "string" ? `"${option.default}"` : option.default})`
+        }`;
+
+        if (flags.length > acc.maxLength) {
+          acc.maxLength = flags.length;
+        }
+
+        acc.options.push({
+          flags,
+          description,
+        });
+        return acc;
+      },
+      {
+        options: [],
+        maxLength: 0,
+      },
+    );
+
+  const { options, maxLength: maxOptionLength } = generateOptionsOutput(commands[root_command].options);
+
+  const { commands: commandLabels, maxLength: maxCommandLength } = _.filter(
+    commands,
+    (command) => command.name !== root_command,
+  ).reduce(
+    (acc, command) => {
+      const options = generateOptionsOutput(command.options);
+      const name = `${command.name}${options.length ? " [options]" : ""}`;
+      const description = command.description;
+
+      const maxLength = Math.max(name.length, options.maxLength);
+      if (maxLength > acc.maxLength) {
+        acc.maxLength = maxLength;
+      }
+
+      acc.commands.push({
+        description,
+        name,
+        options,
+      });
+      return acc;
+    },
+    {
+      commands: [],
+      maxLength: maxOptionLength,
+    },
+  );
+
+  const generateOptionsTextOutput = (options, maxLength, spaces) =>
+    options
+      .map((option) => {
+        const spacesText = Array(spaces).fill(" ").join("");
+        const leftStr = `${spacesText}${option.flags.padEnd(maxLength, " ")}  `;
+        const leftStrFiller = Array(leftStr.length).fill(" ").join("");
+        const descriptionLines = option.description.split("\n");
+
+        return (
+          leftStr +
+          descriptionLines
+            .map((line, i) => {
+              if (i === 0) {
+                return line;
+              }
+
+              return `\n${leftStrFiller}${line}`;
+            })
+            .join("")
+        );
+      })
+      .join("\n");
+
+  const optionsOutput = generateOptionsTextOutput(options, maxOptionLength, 2);
+
+  const commandsOutput = commandLabels
+    .map((commandLabel) => {
+      const leftStr = `  ${commandLabel.name.padEnd(maxCommandLength, " ")}    `;
+      const leftStrFiller = Array(leftStr.length).fill(" ").join("");
+      const descriptionLines = commandLabel.description.split("\n");
+      const optionsTextOutput = generateOptionsTextOutput(commandLabel.options.options, maxCommandLength, 4);
+
+      return (
+        leftStr +
+        descriptionLines
+          .map((line, i) => {
+            if (i === 0) {
+              return line;
+            }
+
+            return `\n${leftStrFiller}${line}`;
+          })
+          .join("") +
+        (optionsTextOutput.length ? `\n${optionsTextOutput}` : "")
+      );
+    })
+    .join("\n");
+
+  const outputTest = [
+    optionsOutput &&
+      `Options:
+${optionsOutput}`,
+    commandsOutput &&
+      `Commands:
+${commandsOutput}`,
+  ]
+    .filter(Boolean)
+    .join("\n\n");
+
+  console.log(`Usage: ${[instance.input.name, instance.input.alias].filter(Boolean).join("|")}${
+    optionsOutput ? " [options]" : ""
+  }${commandsOutput ? " [command]" : ""}
+${
+  instance.input.description &&
+  `
+${instance.input.description}`
+}
+
+${outputTest}`);
+};
+
+module.exports = {
+  displayHelp,
+};

cli/operations/display-version.js

@@ -0,0 +1,5 @@
+const displayVersion = (instance) => {
+  console.log(instance.input.version);
+};
+
+module.exports = { displayVersion };