@reliverse/rempts 1.7.29 → 1.7.30

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

@@ -7,21 +7,21 @@ import process from "node:process";
 import { readPackageJSON } from "pkg-types";
 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 +145,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 +164,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 +184,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 +206,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 +223,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 +241,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 +262,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 +315,268 @@ 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 };
+  }
+  if (command.run && (globalCliMeta.name || globalCliMeta.version || globalCliMeta.description)) {
+    const mergedMeta = { ...command.meta };
+    if (globalCliMeta.name && !command.meta?.name) {
+      mergedMeta.name = globalCliMeta.name;
     }
+    if (globalCliMeta.version && !command.meta?.version) {
+      mergedMeta.version = globalCliMeta.version;
+    }
+    if (globalCliMeta.description && !command.meta?.description) {
+      mergedMeta.description = globalCliMeta.description;
+    }
+    command = {
+      ...command,
+      meta: mergedMeta
+    };
   }
-  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
-      };
-    }
-    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)) {
+  return {
+    /**
+     * @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(
-        "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."
+        "warn",
+        "\u26A0\uFE0F  Deprecated: .run() method is deprecated. Use createCli() directly instead."
       );
-      process.exit(1);
-    }
-    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;
+      relinka("warn", "   Instead of: createCli({...}).run()");
+      relinka("warn", "   Use: await createCli({...})");
+      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;
         }
       }
-    }
-    const fileBasedEnabled = parserOptions.fileBasedCmds?.enable;
-    if (fileBasedEnabled && rawArgv.length > 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 runFileBasedSubCmd(
-          subName,
-          subCmdArgv,
-          parserOptions.fileBasedCmds,
-          parserOptions,
-          command.onCmdExit ? async (_subCtx) => {
-            await command.onCmdExit?.(ctx);
-          } : void 0
-        );
-        if (autoExit) process.exit(0);
-        return;
-      } catch (err) {
-        relinka("error", "Error loading file-based subcommand:", err.message);
-        if (autoExit) 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;
+        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
+          };
         }
-        try {
-          const cmd = await loadSubCommand(spec);
-          if (cmd.meta.aliases?.includes(maybeSub)) {
-            subSpec = spec;
-            break;
+        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."
+          );
+          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;
+            }
           }
-        } 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
-          });
+        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 runFileBasedSubCmd(
+              subName,
+              subCmdArgv,
+              parserOptions.fileBased,
+              parserOptions,
+              command.onCmdExit ? async (_subCtx) => {
+                await command.onCmdExit?.(ctx);
+              } : void 0,
+              globalCliMeta
+            );
+            if (autoExit) process.exit(0);
+            return;
+          } catch (err) {
+            relinka(
+              "error",
+              "Error loading file-based subcommand:",
+              err.message
+            );
+            if (autoExit) process.exit(1);
+            throw err;
+          }
+        }
+        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;
         }
-        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
-          );
+        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;
-        } catch (err) {
-          relinka("error", "Error running subcommand:", err.message);
-          if (autoExit) process.exit(1);
-          throw err;
         }
+        try {
+          await runCommandWithArgs(
+            command,
+            rawArgv,
+            parserOptions,
+            globalCliMeta
+          );
+        } finally {
+        }
+        await relinkaShutdown();
+      } finally {
+        if (typeof command.onLauncherExit === "function")
+          await command.onLauncherExit();
       }
+      throw new Error(
+        "\u26A0\uFE0F  Deprecated: .run() method is deprecated. Use createCli() directly instead.\n   Instead of: createCli({...}).run()\n   Use: await createCli({...})"
+      );
     }
-    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 (autoExit) process.exit(0);
-      return;
-    }
-    try {
-      await runCommandWithArgs(command, rawArgv, parserOptions);
-    } finally {
-    }
-    await relinkaShutdown();
-  } finally {
-    if (typeof command.onLauncherExit === "function")
-      await command.onLauncherExit();
-  }
+  };
 }
 function checkHelp(argv) {
   return argv.includes("--help") || argv.includes("-h");
@@ -482,9 +601,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 +619,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 +652,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 +678,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 +704,7 @@ async function runSubCommand(spec, argv, parserOptions, parentFinish) {
       subCommand,
       argv,
       parserOptions,
+      globalCliMeta,
       true
     );
     if (typeof parentFinish === "function" && subCtx)
@@ -588,10 +712,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 +734,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 +757,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 +784,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 +911,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 +920,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 +939,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 +990,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 +1008,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 +1040,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;