@reliverse/rempts 1.7.29 → 1.7.31

package/bin/{components → libs}/launcher/launcher-mod.js

@@ -5,23 +5,24 @@ import fs from "@reliverse/relifso";
 import { relinka, relinkaConfig, relinkaShutdown } from "@reliverse/relinka";
 import process from "node:process";
 import { readPackageJSON } from "pkg-types";
+import { createRpcCli } from "./trpc-orpc-support/index.js";
 function buildExampleArgs(args) {
   const parts = [];
-  const positionalKeys = Object.keys(args).filter(
-    (k) => args[k].type === "positional"
+  const positionalKeys = Object.keys(args || {}).filter(
+    (k) => args?.[k]?.type === "positional"
   );
   positionalKeys.forEach((key) => {
-    const def = args[key];
-    if (def.required || Math.random() > 0.5) {
+    const def = args?.[key];
+    if (def && (def.required || Math.random() > 0.5)) {
       parts.push(String(def.default ?? `<${key}>`));
     }
   });
-  const otherKeys = Object.keys(args).filter(
-    (k) => args[k].type !== "positional"
+  const otherKeys = Object.keys(args || {}).filter(
+    (k) => args?.[k]?.type !== "positional"
   );
   for (const key of otherKeys) {
-    const def = args[key];
-    if (def.required || Math.random() > 0.7) {
+    const def = args?.[key];
+    if (def && (def.required || Math.random() > 0.7)) {
       switch (def.type) {
         case "boolean":
           if (def.default === true) {
@@ -145,13 +146,13 @@ function formatTableRow(text, desc, padding) {
   const spaces = " ".repeat(Math.max(0, padding - text.length));
   return `${text}${spaces}| ${desc || ""}`;
 }
-export async function showUsage(command, parserOptions = {}) {
+export async function showUsage(command, parserOptions = {}, globalCliMeta) {
   const { name: fallbackName, version: fallbackVersion } = await getDefaultCliNameAndVersion();
-  const cliName = command.meta?.name || fallbackName;
-  const cliVersion = command.meta?.version || fallbackVersion;
+  const cliName = globalCliMeta?.name || command.meta?.name || fallbackName;
+  const cliVersion = globalCliMeta?.version || command.meta?.version || fallbackVersion;
   relinka("info", `${cliName}${cliVersion ? ` v${cliVersion}` : ""}`);
   if (parserOptions.metaSettings?.showDescriptionOnMain) {
-    let description = command.meta?.description;
+    let description = globalCliMeta?.description || command.meta?.description;
     if (!description) {
       try {
         const pkg = await readPackageJSON();
@@ -164,7 +165,7 @@ export async function showUsage(command, parserOptions = {}) {
     }
   }
   const { name: pkgName } = await getDefaultCliNameAndVersion();
-  const fileCmds = parserOptions.fileBasedCmds;
+  const fileCmds = parserOptions.fileBased;
   if (fileCmds?.enable) {
     const commandsDir = path.resolve(fileCmds.cmdsRootPath);
     const pathSegments = parserOptions._fileBasedPathSegments || [];
@@ -184,16 +185,19 @@ export async function showUsage(command, parserOptions = {}) {
       if (pos) usageLine += ` ${pos}`;
     }
     relinka("log", re.cyan(`Usage: ${usageLine}`));
-    if (directCommands.length > 0) {
+    if (directCommands.length > 0 && allCommands.length > 0) {
       const randomIdx = Math.floor(Math.random() * allCommands.length);
-      const { path: path2, def: exampleDef } = allCommands[randomIdx];
-      const exampleArgs = buildExampleArgs(exampleDef.args || {});
-      relinka(
-        "log",
-        re.cyan(
-          `Example: ${pkgName} ${path2.join(" ")}${exampleArgs ? ` ${exampleArgs}` : ""}`
-        )
-      );
+      const exampleCmd = allCommands[randomIdx];
+      if (exampleCmd) {
+        const { path: path2, def: exampleDef } = exampleCmd;
+        const exampleArgs = buildExampleArgs(exampleDef.args || {});
+        relinka(
+          "log",
+          re.cyan(
+            `Example: ${pkgName} ${path2.join(" ")}${exampleArgs ? ` ${exampleArgs}` : ""}`
+          )
+        );
+      }
     }
     if (allCommands.length > 0) {
       relinka("info", "Available commands (run with `help` to see more):");
@@ -203,7 +207,10 @@ export async function showUsage(command, parserOptions = {}) {
         if (!commandsByPath.has(parentPath)) {
           commandsByPath.set(parentPath, []);
         }
-        commandsByPath.get(parentPath).push(cmd);
+        const group = commandsByPath.get(parentPath);
+        if (group) {
+          group.push(cmd);
+        }
       }
       const groupPaddings = /* @__PURE__ */ new Map();
       for (const [parentPath, cmds] of commandsByPath) {
@@ -217,7 +224,7 @@ export async function showUsage(command, parserOptions = {}) {
         if (parentPath !== "/") {
           relinka("log", re.cyanPastel(`Sub-commands in ${parentPath}:`));
         }
-        const padding = groupPaddings.get(parentPath);
+        const padding = groupPaddings.get(parentPath) || 0;
         for (const { def, path: path2 } of cmds) {
           const desc = def?.meta?.description ?? "";
           const indent = parentPath === "/" ? "" : "  ";
@@ -235,7 +242,7 @@ export async function showUsage(command, parserOptions = {}) {
         try {
           const cmd = await loadSubCommand(spec);
           if (!cmd?.meta?.hidden) {
-            const aliasDisplay = cmd.meta.aliases ? ` (aliases: ${cmd.meta.aliases.join(", ")})` : "";
+            const aliasDisplay = cmd.meta?.aliases ? ` (aliases: ${cmd.meta.aliases.join(", ")})` : "";
             subCommandNames.push(`${name}${aliasDisplay}`);
             subCommandDefs.push({ name, def: cmd });
           }
@@ -256,14 +263,17 @@ export async function showUsage(command, parserOptions = {}) {
     relinka("log", re.cyan(`Usage: ${usageLine}`));
     if (subCommandDefs.length > 0) {
       const randomIdx = Math.floor(Math.random() * subCommandDefs.length);
-      const { name: exampleCmd, def: exampleDef } = subCommandDefs[randomIdx];
-      const exampleArgs = buildExampleArgs(exampleDef.args || {});
-      relinka(
-        "log",
-        re.cyan(
-          `Example: ${pkgName}${parserOptions._isSubcommand ? ` ${cliName}` : ""} ${exampleCmd}${exampleArgs ? ` ${exampleArgs}` : ""}`
-        )
-      );
+      const exampleCmd = subCommandDefs[randomIdx];
+      if (exampleCmd) {
+        const { name: exampleCmdName, def: exampleDef } = exampleCmd;
+        const exampleArgs = buildExampleArgs(exampleDef.args || {});
+        relinka(
+          "log",
+          re.cyan(
+            `Example: ${pkgName}${parserOptions._isSubcommand ? ` ${cliName}` : ""} ${exampleCmdName}${exampleArgs ? ` ${exampleArgs}` : ""}`
+          )
+        );
+      }
     }
     if (subCommandNames.length > 0) {
       relinka("info", "Available commands (run with `help` to see more):");
@@ -306,158 +316,310 @@ export async function showUsage(command, parserOptions = {}) {
     relinka("log", formatTableRow(text, desc, optionsPadding));
   }
 }
-export async function runMain(command, parserOptions = {}) {
-  if (typeof command.onLauncherInit === "function") {
-    try {
-      await command.onLauncherInit();
-    } catch (err) {
-      relinka("error", "Error in onLauncherInit:", err);
-      if (parserOptions.autoExit !== false) process.exit(1);
-      throw err;
-    }
+export function createCli(options, legacyParserOptions) {
+  let command;
+  let parserOptions;
+  let globalCliMeta = {};
+  if (typeof options === "object" && !("run" in options) && !("meta" in options) && !("args" in options) && !("commands" in options)) {
+    command = options;
+    parserOptions = legacyParserOptions || {};
+  } else if ("mainCommand" in options) {
+    command = options.mainCommand;
+    parserOptions = {
+      fileBased: options.fileBased,
+      autoExit: options.autoExit,
+      metaSettings: options.metaSettings
+    };
+    globalCliMeta = {
+      name: options.name,
+      version: options.version,
+      description: options.description
+    };
+  } else {
+    const inlineOptions = options;
+    const {
+      name,
+      version,
+      description,
+      fileBased,
+      autoExit,
+      metaSettings,
+      mainCommand,
+      ...commandOptions
+    } = inlineOptions;
+    command = {
+      meta: commandOptions.meta,
+      args: commandOptions.args,
+      run: commandOptions.run,
+      commands: commandOptions.commands,
+      onCmdInit: commandOptions.onCmdInit,
+      onCmdExit: commandOptions.onCmdExit,
+      onLauncherInit: commandOptions.onLauncherInit,
+      onLauncherExit: commandOptions.onLauncherExit
+    };
+    parserOptions = {
+      fileBased,
+      autoExit,
+      metaSettings
+    };
+    globalCliMeta = { name, version, description };
   }
-  try {
-    if (!parserOptions.fileBasedCmds && !command.commands) {
-      const mainEntry = process.argv[1] ? path.dirname(path.resolve(process.argv[1])) : process.cwd();
-      const defaultCmdsRoot = path.join(mainEntry, "src", "app");
-      const exists = await fs.pathExists(defaultCmdsRoot);
-      const finalCmdsRoot = exists ? defaultCmdsRoot : path.join(mainEntry, "app");
-      parserOptions.fileBasedCmds = {
-        enable: true,
-        cmdsRootPath: finalCmdsRoot
-      };
+  if (command.run && (globalCliMeta.name || globalCliMeta.version || globalCliMeta.description)) {
+    const mergedMeta = { ...command.meta };
+    if (globalCliMeta.name && !command.meta?.name) {
+      mergedMeta.name = globalCliMeta.name;
     }
-    const rawArgv = process.argv.slice(2);
-    const autoExit = parserOptions.autoExit !== false;
-    if (!(parserOptions.fileBasedCmds?.enable || command.commands && Object.keys(command.commands).length > 0 || command.run)) {
-      relinka(
-        "error",
-        "Invalid CLI configuration: No file-based commands, subCommands, or run() handler are defined. This CLI will not do anything.\n\u2502   To fix: add file-based commands (./app), or provide at least one subCommand or a run() handler."
-      );
-      process.exit(1);
+    if (globalCliMeta.version && !command.meta?.version) {
+      mergedMeta.version = globalCliMeta.version;
     }
-    if (parserOptions.fileBasedCmds?.enable && rawArgv.length > 0) {
-      const commandsDir = path.resolve(
-        parserOptions.fileBasedCmds.cmdsRootPath
-      );
-      const resolved = await resolveFileBasedCommandPath(commandsDir, rawArgv);
-      if (resolved) {
-        const { def: subCommand, leftoverArgv, path: pathSegments } = resolved;
-        const helpIdx = leftoverArgv.findIndex(
-          (arg) => arg === "help" || arg === "--help" || arg === "-h"
-        );
-        if (helpIdx !== -1) {
-          await showUsage(subCommand, {
-            ...parserOptions,
-            _fileBasedCurrentDir: pathSegments.length ? path.join(commandsDir, ...pathSegments) : commandsDir,
-            _fileBasedPathSegments: pathSegments
-          });
-          if (autoExit) process.exit(0);
-          return;
-        }
+    if (globalCliMeta.description && !command.meta?.description) {
+      mergedMeta.description = globalCliMeta.description;
+    }
+    command = {
+      ...command,
+      meta: mergedMeta
+    };
+  }
+  const execute = async (_ctx) => {
+    if (options && typeof options === "object" && "rpc" in options && options.rpc) {
+      const rpcOptions = options.rpc;
+      const rpcRunParams = options.rpcRunParams || {};
+      debugLog("RPC integration detected, creating RPC CLI...");
+      try {
+        require("tsx/cjs");
+        await import("tsx/esm");
+        debugLog("tsx loaded successfully for TypeScript support");
+      } catch {
+        debugLog("tsx not available, continuing without TypeScript support");
       }
+      const getRouterMeta = (router) => {
+        if ("_def" in router && router._def && "meta" in router._def) {
+          return router._def.meta;
+        }
+        return void 0;
+      };
+      const routerMeta = getRouterMeta(rpcOptions.router);
+      const rpcCli = createRpcCli({
+        router: rpcOptions.router,
+        name: globalCliMeta.name || routerMeta?.name,
+        version: globalCliMeta.version || routerMeta?.version,
+        description: globalCliMeta.description || routerMeta?.description,
+        usage: rpcOptions.usage,
+        context: rpcOptions.context,
+        trpcServer: rpcOptions.trpcServer,
+        "@valibot/to-json-schema": rpcOptions["@valibot/to-json-schema"],
+        effect: rpcOptions.effect
+      });
+      debugLog(
+        "RPC CLI created, running with argv:",
+        rpcRunParams.argv || process.argv.slice(2)
+      );
+      await rpcCli.run({
+        argv: rpcRunParams.argv || process.argv.slice(2),
+        logger: rpcRunParams.logger || {
+          info: console.log,
+          error: console.error
+        },
+        completion: rpcRunParams.completion,
+        prompts: rpcRunParams.prompts,
+        formatError: rpcRunParams.formatError,
+        process: rpcRunParams.process
+      });
+      return;
     }
-    const fileBasedEnabled = parserOptions.fileBasedCmds?.enable;
-    if (fileBasedEnabled && rawArgv.length > 0 && !isFlag(rawArgv[0])) {
-      const [subName, ...subCmdArgv] = rawArgv;
+    if (typeof command.onLauncherInit === "function") {
       try {
-        const ctx = getParsedContext(command, rawArgv, parserOptions);
-        if (typeof command.onCmdInit === "function")
-          await command.onCmdInit(ctx);
-        await runFileBasedSubCmd(
-          subName,
-          subCmdArgv,
-          parserOptions.fileBasedCmds,
-          parserOptions,
-          command.onCmdExit ? async (_subCtx) => {
-            await command.onCmdExit?.(ctx);
-          } : void 0
-        );
-        if (autoExit) process.exit(0);
-        return;
+        await command.onLauncherInit();
       } catch (err) {
-        relinka("error", "Error loading file-based subcommand:", err.message);
-        if (autoExit) process.exit(1);
+        relinka("error", "Error in onLauncherInit:", err);
+        if (parserOptions.autoExit !== false) process.exit(1);
         throw err;
       }
     }
-    if (!fileBasedEnabled && command.commands && rawArgv.length > 0 && !isFlag(rawArgv[0])) {
-      const [maybeSub, ...subCmdArgv] = rawArgv;
-      let subSpec;
-      for (const [key, spec] of Object.entries(command.commands)) {
-        if (key === maybeSub) {
-          subSpec = spec;
-          break;
-        }
-        try {
-          const cmd = await loadSubCommand(spec);
-          if (cmd.meta.aliases?.includes(maybeSub)) {
-            subSpec = spec;
-            break;
-          }
-        } catch (err) {
-          debugLog(`Error checking alias for command ${key}:`, err);
-        }
+    try {
+      if (!parserOptions.fileBased && !command.commands) {
+        const mainEntry = process.argv[1] ? path.dirname(path.resolve(process.argv[1])) : process.cwd();
+        const defaultCmdsRoot = path.join(mainEntry, "src", "app");
+        const exists = await fs.pathExists(defaultCmdsRoot);
+        const finalCmdsRoot = exists ? defaultCmdsRoot : path.join(mainEntry, "app");
+        parserOptions.fileBased = {
+          enable: true,
+          cmdsRootPath: finalCmdsRoot
+        };
       }
-      if (subSpec) {
-        const helpIdx = subCmdArgv.findIndex(
-          (arg) => arg === "help" || arg === "--help" || arg === "-h"
+      const rawArgv = process.argv.slice(2);
+      const autoExit = parserOptions.autoExit !== false;
+      if (!(parserOptions.fileBased?.enable || command.commands && Object.keys(command.commands).length > 0 || command.run)) {
+        relinka(
+          "error",
+          "Invalid CLI configuration: No file-based commands, subCommands, or run() handler are defined. This CLI will not do anything.\n\u2502   To fix: add file-based commands (./app), or provide at least one subCommand or a run() handler."
         );
-        if (helpIdx !== -1) {
-          const subCommandDef = await loadSubCommand(subSpec);
-          await showUsage(subCommandDef, {
-            ...parserOptions,
-            _isSubcommand: true
-          });
-          if (autoExit) process.exit(0);
-          return;
+        process.exit(1);
+      }
+      if (parserOptions.fileBased?.enable && rawArgv.length > 0) {
+        const commandsDir = path.resolve(parserOptions.fileBased.cmdsRootPath);
+        const resolved = await resolveFileBasedCommandPath(
+          commandsDir,
+          rawArgv
+        );
+        if (resolved) {
+          const {
+            def: subCommand,
+            leftoverArgv,
+            path: pathSegments
+          } = resolved;
+          const helpIdx = leftoverArgv.findIndex(
+            (arg) => arg === "help" || arg === "--help" || arg === "-h"
+          );
+          if (helpIdx !== -1) {
+            await showUsage(
+              subCommand,
+              {
+                ...parserOptions,
+                _fileBasedCurrentDir: pathSegments.length ? path.join(commandsDir, ...pathSegments) : commandsDir,
+                _fileBasedPathSegments: pathSegments
+              },
+              globalCliMeta
+            );
+            if (autoExit) process.exit(0);
+            return;
+          }
         }
+      }
+      const fileBasedEnabled = parserOptions.fileBased?.enable;
+      if (fileBasedEnabled && rawArgv.length > 0 && rawArgv[0] && !isFlag(rawArgv[0])) {
+        const [subName, ...subCmdArgv] = rawArgv;
         try {
           const ctx = getParsedContext(command, rawArgv, parserOptions);
           if (typeof command.onCmdInit === "function")
             await command.onCmdInit(ctx);
-          await runSubCommand(
-            subSpec,
+          await runFileBasedSubCmd(
+            subName,
             subCmdArgv,
-            { ...parserOptions, _isSubcommand: true },
+            parserOptions.fileBased,
+            parserOptions,
             command.onCmdExit ? async (_subCtx) => {
               await command.onCmdExit?.(ctx);
-            } : void 0
+            } : void 0,
+            globalCliMeta
           );
           if (autoExit) process.exit(0);
           return;
         } catch (err) {
-          relinka("error", "Error running subcommand:", err.message);
+          relinka("error", "Error loading file-based subcommand:", err.message);
           if (autoExit) process.exit(1);
           throw err;
         }
       }
-    }
-    await relinkaConfig;
-    if (rawArgv[0] === "help" || checkHelp(rawArgv)) {
-      await showUsage(command, parserOptions);
-      if (autoExit) process.exit(0);
-      return;
-    }
-    if (checkVersion(rawArgv)) {
-      if (command.meta?.name) {
-        relinka(
-          "info",
-          `${command.meta?.name} ${command.meta?.version ? `v${command.meta?.version}` : ""}`
+      if (!fileBasedEnabled && command.commands && rawArgv.length > 0 && rawArgv[0] && !isFlag(rawArgv[0])) {
+        const [maybeSub, ...subCmdArgv] = rawArgv;
+        let subSpec;
+        for (const [key, spec] of Object.entries(command.commands)) {
+          if (key === maybeSub) {
+            subSpec = spec;
+            break;
+          }
+          try {
+            const cmd = await loadSubCommand(spec);
+            if (cmd.meta?.aliases?.includes(maybeSub)) {
+              subSpec = spec;
+              break;
+            }
+          } catch (err) {
+            debugLog(`Error checking alias for command ${key}:`, err);
+          }
+        }
+        if (subSpec) {
+          const helpIdx = subCmdArgv.findIndex(
+            (arg) => arg === "help" || arg === "--help" || arg === "-h"
+          );
+          if (helpIdx !== -1) {
+            const subCommandDef = await loadSubCommand(subSpec);
+            await showUsage(
+              subCommandDef,
+              {
+                ...parserOptions,
+                _isSubcommand: true
+              },
+              globalCliMeta
+            );
+            if (autoExit) process.exit(0);
+            return;
+          }
+          try {
+            const ctx = getParsedContext(command, rawArgv, parserOptions);
+            if (typeof command.onCmdInit === "function")
+              await command.onCmdInit(ctx);
+            await runSubCommand(
+              subSpec,
+              subCmdArgv,
+              { ...parserOptions, _isSubcommand: true },
+              command.onCmdExit ? async (_subCtx) => {
+                await command.onCmdExit?.(ctx);
+              } : void 0,
+              globalCliMeta
+            );
+            if (autoExit) process.exit(0);
+            return;
+          } catch (err) {
+            relinka("error", "Error running subcommand:", err.message);
+            if (autoExit) process.exit(1);
+            throw err;
+          }
+        }
+      }
+      await relinkaConfig;
+      if (rawArgv[0] === "help" || checkHelp(rawArgv)) {
+        await showUsage(command, parserOptions, globalCliMeta);
+        if (autoExit) process.exit(0);
+        return;
+      }
+      if (checkVersion(rawArgv)) {
+        if (command.meta?.name) {
+          relinka(
+            "info",
+            `${command.meta?.name} ${command.meta?.version ? `v${command.meta?.version}` : ""}`
+          );
+        }
+        if (autoExit) process.exit(0);
+        return;
+      }
+      try {
+        await runCommandWithArgs(
+          command,
+          rawArgv,
+          parserOptions,
+          globalCliMeta
         );
+      } finally {
       }
-      if (autoExit) process.exit(0);
-      return;
-    }
-    try {
-      await runCommandWithArgs(command, rawArgv, parserOptions);
+      await relinkaShutdown();
     } finally {
+      if (typeof command.onLauncherExit === "function")
+        await command.onLauncherExit();
     }
-    await relinkaShutdown();
-  } finally {
-    if (typeof command.onLauncherExit === "function")
-      await command.onLauncherExit();
-  }
+  };
+  const promise = execute();
+  const cli = Object.assign(promise, {
+    /**
+     * @deprecated Use createCli() directly instead. This method will be removed in a future version.
+     * @example
+     * // Instead of:
+     * createCli({...}).run()
+     * // Use:
+     * await createCli({...})
+     */
+    async run(_ctx) {
+      relinka(
+        "warn",
+        "\u26A0\uFE0F  Deprecated: .run() method is deprecated. Use createCli() directly instead."
+      );
+      relinka("warn", "   Instead of: createCli({...}).run()");
+      relinka("warn", "   Use: await createCli({...})");
+      return execute(_ctx);
+    }
+  });
+  return cli;
 }
 function checkHelp(argv) {
   return argv.includes("--help") || argv.includes("-h");
@@ -482,9 +644,9 @@ async function loadSubCommand(spec) {
   }
   throw new Error("Subcommand import did not return a valid command");
 }
-async function runFileBasedSubCmd(subName, argv, fileCmdOpts, parserOptions, parentFinish) {
+async function runFileBasedSubCmd(subName, argv, fileCmdOpts, parserOptions, parentFinish, globalCliMeta) {
   async function resolveCmdPath(baseDir, args) {
-    if (args.length === 0 || isFlag(args[0])) {
+    if (args.length === 0 || args[0] && isFlag(args[0])) {
       const possibleFiles2 = [
         path.join(baseDir, "cmd.js"),
         path.join(baseDir, "cmd.ts")
@@ -500,7 +662,7 @@ Unknown command or arguments: ${args.join(" ")}
 Info for this CLI's developer: No valid command file found in ${baseDir}`
       );
     }
-    const nextDir = path.join(baseDir, args[0]);
+    const nextDir = path.join(baseDir, args[0] || "");
     if (await fs.pathExists(nextDir) && (await fs.stat(nextDir)).isDirectory()) {
       return resolveCmdPath(nextDir, args.slice(1));
     }
@@ -533,7 +695,7 @@ Info for this CLI's developer: No valid command file found in ${baseDir}`
     let closestMatch = "";
     let minDistance = Number.POSITIVE_INFINITY;
     for (const cmd of commandNames) {
-      const distance = levenshteinDistance(subName, cmd.split(" ")[0]);
+      const distance = levenshteinDistance(subName, cmd.split(" ")[0] || "");
       if (distance < minDistance) {
         minDistance = distance;
         closestMatch = cmd;
@@ -559,21 +721,25 @@ Info for this CLI's developer: No valid command directory found, expected: ${exp
       subCommand,
       leftoverArgv,
       parserOptions,
-      true
+      globalCliMeta
     );
     if (typeof parentFinish === "function" && subCtx)
       await parentFinish(subCtx);
   } finally {
   }
 }
-async function runSubCommand(spec, argv, parserOptions, parentFinish) {
+async function runSubCommand(spec, argv, parserOptions, parentFinish, globalCliMeta) {
   const subCommand = await loadSubCommand(spec);
   try {
     const helpIdx = argv.findIndex(
       (arg) => arg === "help" || arg === "--help" || arg === "-h"
     );
     if (helpIdx !== -1) {
-      await showUsage(subCommand, { ...parserOptions, _isSubcommand: true });
+      await showUsage(
+        subCommand,
+        { ...parserOptions, _isSubcommand: true },
+        globalCliMeta
+      );
       if (parserOptions.autoExit !== false) process.exit(0);
       return;
     }
@@ -581,6 +747,7 @@ async function runSubCommand(spec, argv, parserOptions, parentFinish) {
       subCommand,
       argv,
       parserOptions,
+      globalCliMeta,
       true
     );
     if (typeof parentFinish === "function" && subCtx)
@@ -588,10 +755,10 @@ async function runSubCommand(spec, argv, parserOptions, parentFinish) {
   } finally {
   }
 }
-async function runCommandWithArgs(command, argv, parserOptions, returnCtx) {
+async function runCommandWithArgs(command, argv, parserOptions, globalCliMeta, returnCtx) {
   const autoExit = parserOptions.autoExit !== false;
   const booleanKeys = Object.keys(command.args || {}).filter(
-    (k) => command.args[k].type === "boolean"
+    (k) => command.args?.[k]?.type === "boolean"
   );
   const defaultMap = {};
   for (const [argKey, def] of Object.entries(command.args || {})) {
@@ -610,26 +777,22 @@ async function runCommandWithArgs(command, argv, parserOptions, returnCtx) {
   debugLog("Parsed arguments:", parsed);
   const finalArgs = {};
   const positionalKeys = Object.keys(command.args || {}).filter(
-    (k) => command.args[k].type === "positional"
+    (k) => command.args?.[k]?.type === "positional"
   );
   const leftoverPositionals = [...parsed._ || []];
   for (let i = 0; i < positionalKeys.length; i++) {
     const key = positionalKeys[i];
-    const def = command.args?.[key];
+    if (!key || !command.args) continue;
+    const def = command.args[key];
     const val = leftoverPositionals[i];
-    if (val == null && def.required) {
-      await showUsage(command, parserOptions);
-      relinka("error", `Missing required positional argument: <${key}>`);
-      if (autoExit) process.exit(1);
-      else throw new Error(`Missing required positional argument: <${key}>`);
-    }
-    finalArgs[key] = val != null ? castArgValue(def, val, key) : def.default;
+    finalArgs[key] = val != null && def ? castArgValue(def, val, key) : def?.default;
   }
   const otherKeys = Object.keys(command.args || {}).filter(
-    (k) => command.args[k].type !== "positional"
+    (k) => command.args?.[k]?.type !== "positional"
   );
   for (const key of otherKeys) {
     const def = command.args?.[key];
+    if (!def) continue;
     let rawVal = parsed[key];
     if (def.type === "array" && rawVal !== void 0 && !Array.isArray(rawVal)) {
       rawVal = [rawVal];
@@ -637,7 +800,7 @@ async function runCommandWithArgs(command, argv, parserOptions, returnCtx) {
     const casted = rawVal !== void 0 ? castArgValue(def, rawVal, key) : def.default;
     const argUsed = rawVal !== void 0 && (def.type === "boolean" ? casted === true : true);
     if (casted == null && def.required) {
-      await showUsage(command, parserOptions);
+      await showUsage(command, parserOptions, globalCliMeta);
       relinka("error", `Missing required argument: --${key}`);
       if (autoExit) process.exit(1);
       else throw new Error(`Missing required argument: --${key}`);
@@ -664,17 +827,17 @@ async function runCommandWithArgs(command, argv, parserOptions, returnCtx) {
     if (command.run) {
       await command.run(ctx);
     } else {
-      const isDispatcher = parserOptions.fileBasedCmds?.enable || command.commands && Object.keys(command.commands).length > 0;
+      const isDispatcher = parserOptions.fileBased?.enable || command.commands && Object.keys(command.commands).length > 0;
       const noSubcommandArgInCurrentCall = !argv.some((arg) => !isFlag(arg));
       if (isDispatcher && noSubcommandArgInCurrentCall) {
         relinka("warn", "Please specify a command");
-        await showUsage(command, parserOptions);
+        await showUsage(command, parserOptions, globalCliMeta);
         if (autoExit) process.exit(0);
         return;
       }
       const cmdName = command.meta?.name || "unknown";
       const attempted = argv.length > 0 ? argv.join(" ") : "(no arguments)";
-      await showUsage(command, parserOptions);
+      await showUsage(command, parserOptions, globalCliMeta);
       relinka("error", `Unknown command or arguments: ${attempted}`);
       if (autoExit) {
         process.exit(1);
@@ -791,7 +954,7 @@ function castArgValue(def, rawVal, argName) {
 }
 function renderPositional(args) {
   const positionalKeys = Object.keys(args || {}).filter(
-    (k) => args[k].type === "positional"
+    (k) => args?.[k]?.type === "positional"
   );
   return positionalKeys.map((k) => `<${k}>`).join(" ");
 }
@@ -800,7 +963,7 @@ export function defineArgs(args) {
 }
 export async function runCmd(command, argv = [], parserOptions = {}) {
   const booleanKeys = Object.keys(command.args || {}).filter(
-    (k) => command.args[k].type === "boolean"
+    (k) => command.args?.[k]?.type === "boolean"
   );
   const defaultMap = {};
   for (const [argKey, def] of Object.entries(command.args || {})) {
@@ -819,23 +982,22 @@ export async function runCmd(command, argv = [], parserOptions = {}) {
   debugLog("Parsed arguments (runCmd):", parsed);
   const finalArgs = {};
   const positionalKeys = Object.keys(command.args || {}).filter(
-    (k) => command.args[k].type === "positional"
+    (k) => command.args?.[k]?.type === "positional"
   );
   const leftoverPositionals = [...parsed._ || []];
   for (let i = 0; i < positionalKeys.length; i++) {
     const key = positionalKeys[i];
-    const def = command.args?.[key];
+    if (!key || !command.args) continue;
+    const def = command.args[key];
     const val = leftoverPositionals[i];
-    if (val == null && def.required) {
-      throw new Error(`Missing required positional argument: <${key}>`);
-    }
-    finalArgs[key] = val != null ? castArgValue(def, val, key) : def.default;
+    finalArgs[key] = val != null && def ? castArgValue(def, val, key) : def?.default;
   }
   const otherKeys = Object.keys(command.args || {}).filter(
-    (k) => command.args[k].type !== "positional"
+    (k) => command.args?.[k]?.type !== "positional"
   );
   for (const key of otherKeys) {
     const def = command.args?.[key];
+    if (!def) continue;
     let rawVal = parsed[key];
     if (def.type === "array" && rawVal !== void 0 && !Array.isArray(rawVal)) {
       rawVal = [rawVal];
@@ -871,7 +1033,7 @@ export async function runCmd(command, argv = [], parserOptions = {}) {
 }
 function getParsedContext(command, argv, parserOptions) {
   const booleanKeys = Object.keys(command.args || {}).filter(
-    (k) => command.args[k].type === "boolean"
+    (k) => command.args?.[k]?.type === "boolean"
   );
   const defaultMap = {};
   for (const [argKey, def] of Object.entries(command.args || {})) {
@@ -889,20 +1051,22 @@ function getParsedContext(command, argv, parserOptions) {
   const parsed = reliArgParser(argv, mergedParserOptions);
   const finalArgs = {};
   const positionalKeys = Object.keys(command.args || {}).filter(
-    (k) => command.args[k].type === "positional"
+    (k) => command.args?.[k]?.type === "positional"
   );
   const leftoverPositionals = [...parsed._ || []];
   for (let i = 0; i < positionalKeys.length; i++) {
     const key = positionalKeys[i];
-    const def = command.args?.[key];
+    if (!key || !command.args) continue;
+    const def = command.args[key];
     const val = leftoverPositionals[i];
-    finalArgs[key] = val != null ? castArgValue(def, val, key) : def.default;
+    finalArgs[key] = val != null && def ? castArgValue(def, val, key) : def?.default;
   }
   const otherKeys = Object.keys(command.args || {}).filter(
-    (k) => command.args[k].type !== "positional"
+    (k) => command.args?.[k]?.type !== "positional"
   );
   for (const key of otherKeys) {
     const def = command.args?.[key];
+    if (!def) continue;
     let rawVal = parsed[key];
     if (def.type === "array" && rawVal !== void 0 && !Array.isArray(rawVal)) {
       rawVal = [rawVal];
@@ -919,7 +1083,7 @@ async function resolveFileBasedCommandPath(cmdsRoot, argv) {
   let currentDir = cmdsRoot;
   const pathSegments = [];
   let leftover = [...argv];
-  while (leftover.length > 0 && !isFlag(leftover[0])) {
+  while (leftover.length > 0 && leftover[0] && !isFlag(leftover[0])) {
     const nextDir = path.join(currentDir, leftover[0]);
     if (await fs.pathExists(nextDir) && (await fs.stat(nextDir)).isDirectory()) {
       currentDir = nextDir;