@reliverse/rempts 1.6.0

package/bin/core-impl/launcher/deprecated/command.ts.txt

@@ -0,0 +1,95 @@
+import type {
+  ArgsDef,
+  CommandContext,
+  CommandDef,
+  RunCommandOptions,
+} from "~/libs/core/core-types.js";
+
+import { CLIError, resolveValue } from "./_utils.js";
+import { parseArgs } from "./args.js";
+
+export function defineCommand<const T extends ArgsDef = ArgsDef>(
+  def: CommandDef<T>,
+): CommandDef<T> {
+  return def;
+}
+
+export async function runCommand<T extends ArgsDef = ArgsDef>(
+  cmd: CommandDef<T>,
+  opts: RunCommandOptions,
+): Promise<{ result: unknown }> {
+  const cmdArgs = await resolveValue(cmd.args || {});
+  const parsedArgs = parseArgs<T>(opts.rawArgs, cmdArgs);
+
+  const context: CommandContext<T> = {
+    rawArgs: opts.rawArgs,
+    args: parsedArgs,
+    data: opts.data,
+    cmd,
+  };
+
+  // Setup hook
+  if (typeof cmd.setup === "function") {
+    await cmd.setup(context);
+  }
+
+  // Handle sub command
+  let result: unknown;
+  try {
+    const subCommands = await resolveValue(cmd.subCommands);
+    if (subCommands && Object.keys(subCommands).length > 0) {
+      const subCommandArgIndex = opts.rawArgs.findIndex(
+        (arg) => !arg.startsWith("-"),
+      );
+      const subCommandName = opts.rawArgs[subCommandArgIndex];
+      if (subCommandName) {
+        if (!subCommands[subCommandName]) {
+          throw new CLIError(
+            `Unknown command \`${subCommandName}\``,
+            "E_UNKNOWN_COMMAND",
+          );
+        }
+        const subCommand = await resolveValue(subCommands[subCommandName]);
+        if (subCommand) {
+          await runCommand(subCommand, {
+            rawArgs: opts.rawArgs.slice(subCommandArgIndex + 1),
+          });
+        }
+      } else if (!cmd.run) {
+        // biome-ignore lint/style/noUnusedTemplateLiteral: <explanation>
+        throw new CLIError(`No command specified.`, "E_NO_COMMAND");
+      }
+    }
+
+    // Handle main command
+    if (typeof cmd.run === "function") {
+      result = await cmd.run(context);
+    }
+  } finally {
+    if (typeof cmd.cleanup === "function") {
+      await cmd.cleanup(context);
+    }
+  }
+  return { result };
+}
+
+export async function resolveSubCommand<T extends ArgsDef = ArgsDef>(
+  cmd: CommandDef<T>,
+  rawArgs: string[],
+  parent?: CommandDef<T>,
+): Promise<[CommandDef<T>, CommandDef<T>?]> {
+  const subCommands = await resolveValue(cmd.subCommands);
+  if (subCommands && Object.keys(subCommands).length > 0) {
+    const subCommandArgIndex = rawArgs.findIndex((arg) => !arg.startsWith("-"));
+    const subCommandName = rawArgs[subCommandArgIndex];
+    const subCommand = await resolveValue(subCommands[subCommandName]);
+    if (subCommand) {
+      return resolveSubCommand(
+        subCommand,
+        rawArgs.slice(subCommandArgIndex + 1),
+        cmd,
+      );
+    }
+  }
+  return [cmd, parent];
+}

package/bin/core-impl/launcher/deprecated/launcher-mod.ts.txt

@@ -0,0 +1,50 @@
+import { relinka } from "@reliverse/relinka";
+
+import type { ArgsDef, CommandDef } from "~/libs/core/core-types.js";
+
+import { CLIError } from "./_utils.js";
+import { resolveSubCommand, runCommand } from "./command.js";
+import { showUsage as _showUsage } from "./usage.js";
+
+export type RunMainOptions = {
+  rawArgs?: string[];
+  showUsage?: typeof _showUsage;
+};
+
+export async function runMain<T extends ArgsDef = ArgsDef>(
+  cmd: CommandDef<T>,
+  opts: RunMainOptions = {},
+) {
+  const rawArgs = opts.rawArgs || process.argv.slice(2);
+  const showUsage = opts.showUsage || _showUsage;
+  try {
+    if (rawArgs.includes("--help") || rawArgs.includes("-h")) {
+      await showUsage(...(await resolveSubCommand(cmd, rawArgs)));
+      process.exit(0);
+    } else if (rawArgs.length === 1 && rawArgs[0] === "--version") {
+      const meta =
+        typeof cmd.meta === "function" ? await cmd.meta() : await cmd.meta;
+      if (!meta?.version) {
+        throw new CLIError("No version specified", "E_NO_VERSION");
+      }
+      relinka("info", meta.version);
+    } else {
+      await runCommand(cmd, { rawArgs });
+    }
+  } catch (error: any) {
+    const isCLIError = error instanceof CLIError;
+    if (isCLIError) {
+      await showUsage(...(await resolveSubCommand(cmd, rawArgs)));
+      relinka("error", error.message);
+    } else {
+      relinka("error", error, "\n");
+    }
+    process.exit(1);
+  }
+}
+
+export function createMain<T extends ArgsDef = ArgsDef>(
+  cmd: CommandDef<T>,
+): (opts?: RunMainOptions) => Promise<void> {
+  return (opts: RunMainOptions = {}) => runMain(cmd, opts);
+}

package/bin/core-impl/launcher/deprecated/usage.ts.txt

@@ -0,0 +1,157 @@
+import { re } from "@reliverse/relico";
+import { relinka } from "@reliverse/relinka";
+
+import type { ArgsDef, CommandDef } from "~/libs/core/core-types.js";
+
+import { formatLineColumns, resolveValue } from "./_utils.js";
+import { resolveArgs } from "./args.js";
+
+export async function showUsage<T extends ArgsDef = ArgsDef>(
+  cmd: CommandDef<T>,
+  parent?: CommandDef<T>,
+) {
+  try {
+    // biome-ignore lint/style/useTemplate: <explanation>
+    relinka("info", (await renderUsage(cmd, parent)) + "\n");
+  } catch (error) {
+    relinka("error", String(error));
+  }
+}
+
+// `no` prefix matcher (kebab-case or camelCase)
+const negativePrefixRe = /^no[-A-Z]/;
+
+export async function renderUsage<T extends ArgsDef = ArgsDef>(
+  cmd: CommandDef<T>,
+  parent?: CommandDef<T>,
+) {
+  const cmdMeta = await resolveValue(cmd.meta || {});
+  const cmdArgs = resolveArgs(await resolveValue(cmd.args || {}));
+  const parentMeta = await resolveValue(parent?.meta || {});
+
+  const commandName =
+    (parentMeta.name ? `${parentMeta.name} ` : "") +
+    (cmdMeta.name || process.argv[1]);
+
+  const argLines: string[][] = [];
+  const posLines: string[][] = [];
+  const commandsLines: string[][] = [];
+  const usageLine = [];
+
+  for (const arg of cmdArgs) {
+    if (arg.type === "positional") {
+      const name = arg.name.toUpperCase();
+      const isRequired = arg.required !== false && arg.default === undefined;
+      // (isRequired ? " (required)" : " (optional)"
+      const defaultHint = arg.default ? `="${arg.default}"` : "";
+      posLines.push([
+        // biome-ignore lint/style/useTemplate: <explanation>
+        "`" + name + defaultHint + "`",
+        arg.description || "",
+        arg.valueHint ? `<${arg.valueHint}>` : "",
+      ]);
+      usageLine.push(isRequired ? `<${name}>` : `[${name}]`);
+    } else {
+      const isRequired = arg.required === true && arg.default === undefined;
+      const argStr =
+        [...(arg.alias || []).map((a) => `-${a}`), `--${arg.name}`].join(", ") +
+        (arg.type === "string" && (arg.valueHint || arg.default)
+          ? `=${
+              arg.valueHint ? `<${arg.valueHint}>` : `"${arg.default || ""}"`
+            }`
+          : "") +
+        (arg.type === "enum" && arg.options
+          ? `=<${arg.options.join("|")}>`
+          : "");
+      argLines.push([
+        // biome-ignore lint/style/useTemplate: <explanation>
+        "`" + argStr + (isRequired ? " (required)" : "") + "`",
+        arg.description || "",
+      ]);
+
+      /**
+       * print negative boolean arg variant usage when
+       * - enabled by default or has `negativeDescription`
+       * - not prefixed with `no-` or `no[A-Z]`
+       */
+      if (
+        arg.type === "boolean" &&
+        (arg.default === true || arg.negativeDescription) &&
+        !negativePrefixRe.test(arg.name)
+      ) {
+        const negativeArgStr = [
+          ...(arg.alias || []).map((a) => `--no-${a}`),
+          `--no-${arg.name}`,
+        ].join(", ");
+        argLines.push([
+          // biome-ignore lint/style/useTemplate: <explanation>
+          "`" + negativeArgStr + (isRequired ? " (required)" : "") + "`",
+          arg.negativeDescription || "",
+        ]);
+      }
+
+      if (isRequired) {
+        usageLine.push(argStr);
+      }
+    }
+  }
+
+  if (cmd.subCommands) {
+    const commandNames: string[] = [];
+    const subCommands = await resolveValue(cmd.subCommands);
+    for (const [name, sub] of Object.entries(subCommands)) {
+      const subCmd = await resolveValue(sub);
+      const meta = await resolveValue(subCmd?.meta);
+      if (meta?.hidden) {
+        continue;
+      }
+      commandsLines.push([`\`${name}\``, meta?.description || ""]);
+      commandNames.push(name);
+    }
+    usageLine.push(commandNames.join("|"));
+  }
+
+  const usageLines: (string | undefined)[] = [];
+
+  const version = cmdMeta.version || parentMeta.version;
+
+  usageLines.push(
+    re.gray(
+      `${cmdMeta.description} (${
+        commandName + (version ? ` v${version}` : "")
+      })`,
+    ),
+    "",
+  );
+
+  const hasOptions = argLines.length > 0 || posLines.length > 0;
+  usageLines.push(
+    `${re.underline(re.bold("USAGE"))} \`${commandName}${
+      hasOptions ? " [OPTIONS]" : ""
+    } ${usageLine.join(" ")}\``,
+    "",
+  );
+
+  if (posLines.length > 0) {
+    usageLines.push(re.underline(re.bold("ARGUMENTS")), "");
+    usageLines.push(formatLineColumns(posLines, "  "));
+    usageLines.push("");
+  }
+
+  if (argLines.length > 0) {
+    usageLines.push(re.underline(re.bold("OPTIONS")), "");
+    usageLines.push(formatLineColumns(argLines, "  "));
+    usageLines.push("");
+  }
+
+  if (commandsLines.length > 0) {
+    usageLines.push(re.underline(re.bold("COMMANDS")), "");
+    usageLines.push(formatLineColumns(commandsLines, "  "));
+    usageLines.push(
+      "",
+      `Use \`${commandName} <command> --help\` for more information about a command.`,
+    );
+  }
+
+  return usageLines.filter((l) => typeof l === "string").join("\n");
+}

package/bin/core-impl/launcher/launcher-mod.d.ts

@@ -0,0 +1,87 @@
+import type { ReliArgParserOptions } from "@reliverse/reliarg";
+type EmptyArgs = Record<string, never>;
+type BaseArgDefinition = {
+    description?: string;
+    required?: boolean;
+    default?: any;
+};
+type PositionalArgDefinition = {
+    type: "positional";
+} & BaseArgDefinition;
+type BooleanArgDefinition = {
+    type: "boolean";
+} & BaseArgDefinition;
+type StringArgDefinition = {
+    type: "string";
+} & BaseArgDefinition;
+type NumberArgDefinition = {
+    type: "number";
+} & BaseArgDefinition;
+type ArrayArgDefinition = {
+    type: "array";
+} & BaseArgDefinition;
+export type ArgDefinition = PositionalArgDefinition | BooleanArgDefinition | StringArgDefinition | NumberArgDefinition | ArrayArgDefinition;
+export type ArgDefinitions = Record<string, ArgDefinition>;
+type CommandMeta = {
+    name: string;
+    version?: string;
+    description?: string;
+    hidden?: boolean;
+    aliases?: string[];
+};
+/**
+ * A subcommand can be either:
+ *   1) A string path to a module with a default export of type Command.
+ *   2) A lazy import function returning a Promise that resolves to { default: Command<any> } or directly to a Command instance.
+ */
+type SubCommandSpec = string | (() => Promise<{
+    default: Command<any>;
+} | Command<any>>);
+export type SubCommandsMap = Record<string, SubCommandSpec>;
+type CommandContext<ARGS> = {
+    args: ARGS;
+    raw: string[];
+};
+type CommandRun<ARGS> = (ctx: CommandContext<ARGS>) => void | Promise<void>;
+type DefineCommandOptions<A extends ArgDefinitions = EmptyArgs> = {
+    meta: CommandMeta;
+    args?: A;
+    run: CommandRun<InferArgTypes<A>>;
+    subCommands?: SubCommandsMap;
+};
+export type Command<A extends ArgDefinitions = EmptyArgs> = {
+    meta: CommandMeta;
+    args: A;
+    run: CommandRun<InferArgTypes<A>>;
+    subCommands?: SubCommandsMap;
+};
+export type InferArgTypes<A extends ArgDefinitions> = {
+    [K in keyof A]: A[K] extends PositionalArgDefinition ? string : A[K] extends BooleanArgDefinition ? boolean : A[K] extends StringArgDefinition ? string : A[K] extends NumberArgDefinition ? number : A[K] extends ArrayArgDefinition ? string[] : never;
+};
+export type FileBasedCmdsOptions = {
+    enable: boolean;
+    cmdsRootPath: string;
+};
+/**
+ * Defines a command with metadata, argument definitions,
+ * an execution function, and subCommands.
+ */
+export declare function defineCommand<A extends ArgDefinitions = EmptyArgs>(options: DefineCommandOptions<A>): Command<A>;
+/**
+ * Show usage for a given command.
+ */
+export declare function showUsage<A extends ArgDefinitions>(command: Command<A>, parserOptions?: ReliArgParserOptions & {
+    fileBasedCmds?: FileBasedCmdsOptions;
+    autoExit?: boolean;
+}): Promise<void>;
+/**
+ * Primary entry point to run a command, with support for subcommands or file-based commands.
+ *
+ * If the user does not provide any subCommands (or they are empty) AND no fileBasedCmds options,
+ * then file-based command detection is automatically enabled with a default cmdsRootPath.
+ */
+export declare function runMain<A extends ArgDefinitions = EmptyArgs>(command: Command<A>, parserOptions?: ReliArgParserOptions & {
+    fileBasedCmds?: FileBasedCmdsOptions;
+    autoExit?: boolean;
+}): Promise<void>;
+export {};