@reliverse/rempts 1.7.52 → 1.7.53

package/bin/libs/launcher/launcher-mod.js

@@ -0,0 +1,975 @@
+import { readdir, stat } from "node:fs/promises";
+import process from "node:process";
+import { re } from "@reliverse/relico";
+import { relinka, relinkaConfig, relinkaShutdown } from "@reliverse/relinka";
+import path from "path";
+import { readPackageJSON } from "pkg-types";
+import { reliArgParser } from "../reliarg/reliarg-mod.js";
+async function pathExists(path2) {
+  try {
+    await stat(path2);
+    return true;
+  } catch (error) {
+    return false;
+  }
+}
+function buildExampleArgs(args) {
+  const parts = [];
+  const positionalKeys = Object.keys(args || {}).filter((k) => args?.[k]?.type === "positional");
+  positionalKeys.forEach((key) => {
+    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");
+  for (const key of otherKeys) {
+    const def = args?.[key];
+    if (def && (def.required || Math.random() > 0.7)) {
+      switch (def.type) {
+        case "boolean":
+          if (def.default === true) {
+            if (Math.random() > 0.5) parts.push(`--no-${key}`);
+          } else {
+            parts.push(`--${key}`);
+          }
+          break;
+        case "string":
+          parts.push(`--${key}=${String(def.default ?? key)}`);
+          break;
+        case "number":
+          parts.push(`--${key}=${String(def.default ?? 42)}`);
+          break;
+        case "array":
+          parts.push(`--${key}=${String(def.default ?? key)}`);
+          break;
+      }
+    }
+  }
+  return parts.join(" ");
+}
+const isDebugMode = process.argv.includes("--debug");
+function debugLog(...args) {
+  if (isDebugMode) {
+    relinka("log", "[DEBUG]", ...args);
+  }
+}
+function isFlag(str) {
+  return str.startsWith("-");
+}
+export function defineCommand(options) {
+  const onCmdInit = options.onCmdInit || options.setup;
+  const onCmdExit = options.onCmdExit || options.cleanup;
+  const onLauncherInit = options.onLauncherInit;
+  const onLauncherExit = options.onLauncherExit;
+  let commands = options.commands;
+  if (!commands) {
+    commands = options.subCommands;
+  }
+  const cmdObj = {
+    meta: options.meta,
+    args: options.args || {},
+    run: options.run,
+    commands,
+    onCmdInit,
+    onCmdExit,
+    onLauncherInit,
+    onLauncherExit,
+    // Backward-compatible aliases
+    setup: onCmdInit,
+    cleanup: onCmdExit
+  };
+  Object.defineProperty(cmdObj, "subCommands", {
+    get() {
+      return this.commands;
+    },
+    enumerable: false,
+    configurable: true
+  });
+  return cmdObj;
+}
+let _cachedDefaultCliName;
+let _cachedDefaultCliVersion;
+async function getDefaultCliNameAndVersion() {
+  if (_cachedDefaultCliName)
+    return { name: _cachedDefaultCliName, version: _cachedDefaultCliVersion };
+  try {
+    const pkg = await readPackageJSON();
+    let name = pkg.name || "cli";
+    if (name.startsWith("@")) {
+      name = name.split("/").pop() || name;
+    }
+    _cachedDefaultCliName = name;
+    _cachedDefaultCliVersion = pkg.version;
+    return { name, version: pkg.version };
+  } catch (_e) {
+    return { name: "cli", version: void 0 };
+  }
+}
+async function findRecursiveFileBasedCommands(baseDir, currentPath = []) {
+  const results = [];
+  const items = await readdir(path.join(baseDir, ...currentPath), {
+    withFileTypes: true
+  });
+  for (const dirent of items) {
+    if (dirent.isDirectory()) {
+      const newPath = [...currentPath, dirent.name];
+      for (const fname of ["cmd.ts", "cmd.js"]) {
+        const fpath = path.join(baseDir, ...newPath, fname);
+        if (await pathExists(fpath)) {
+          try {
+            const imported = await import(path.resolve(fpath));
+            if (imported.default && !imported.default.meta?.hidden) {
+              results.push({
+                name: dirent.name,
+                def: imported.default,
+                path: newPath
+              });
+            }
+          } catch (err) {
+            debugLog(`Skipping file-based command in ${fpath}:`, err);
+          }
+          break;
+        }
+      }
+      const subResults = await findRecursiveFileBasedCommands(baseDir, newPath);
+      results.push(...subResults);
+    }
+  }
+  return results;
+}
+function calculatePadding(items, minPad = 2) {
+  const maxLength = items.reduce((max, item) => Math.max(max, item.text.length), 0);
+  return maxLength + minPad;
+}
+function formatTableRow(text, desc, padding) {
+  const spaces = " ".repeat(Math.max(0, padding - text.length));
+  return `${text}${spaces}| ${desc || ""}`;
+}
+export async function showUsage(command, parserOptions = {}, globalCliMeta) {
+  const { name: fallbackName, version: fallbackVersion } = await getDefaultCliNameAndVersion();
+  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 = globalCliMeta?.description || command.meta?.description;
+    if (!description) {
+      try {
+        const pkg = await readPackageJSON();
+        if (pkg.description) description = pkg.description;
+      } catch (_e) {
+      }
+    }
+    if (description) {
+      relinka("log", description);
+    }
+  }
+  const { name: pkgName } = await getDefaultCliNameAndVersion();
+  const fileCmds = parserOptions.fileBased;
+  if (fileCmds?.enable) {
+    const commandsDir = path.resolve(fileCmds.cmdsRootPath);
+    const pathSegments = parserOptions._fileBasedPathSegments || [];
+    let usageLine = [pkgName, ...pathSegments].join(" ");
+    const allCommands = await findRecursiveFileBasedCommands(commandsDir, pathSegments);
+    const directCommands = allCommands.filter((cmd) => cmd.path.length === pathSegments.length + 1);
+    if (directCommands.length > 0) {
+      usageLine += " <command> [command's options]";
+    } else {
+      usageLine += " [command's options]";
+      const pos = renderPositional(command.args);
+      if (pos) usageLine += ` ${pos}`;
+    }
+    relinka("log", re.cyan(`Usage: ${usageLine}`));
+    if (directCommands.length > 0 && allCommands.length > 0) {
+      const randomIdx = Math.floor(Math.random() * allCommands.length);
+      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):");
+      const commandsByPath = /* @__PURE__ */ new Map();
+      for (const cmd of allCommands) {
+        const parentPath = cmd.path.slice(0, -1).join("/") || "/";
+        if (!commandsByPath.has(parentPath)) {
+          commandsByPath.set(parentPath, []);
+        }
+        const group = commandsByPath.get(parentPath);
+        if (group) {
+          group.push(cmd);
+        }
+      }
+      const groupPaddings = /* @__PURE__ */ new Map();
+      for (const [parentPath, cmds] of commandsByPath) {
+        const items = cmds.map(({ path: path2, def }) => ({
+          text: `${parentPath === "/" ? "" : "  "}\u2022 ${path2.join(" ")}`,
+          desc: def?.meta?.description
+        }));
+        groupPaddings.set(parentPath, calculatePadding(items));
+      }
+      for (const [parentPath, cmds] of commandsByPath) {
+        if (parentPath !== "/") {
+          relinka("log", re.cyanBright(`Sub-commands in ${parentPath}:`));
+        }
+        const padding = groupPaddings.get(parentPath) || 0;
+        for (const { def, path: path2 } of cmds) {
+          const desc = def?.meta?.description ?? "";
+          const indent = parentPath === "/" ? "" : "  ";
+          const text = `${indent}\u2022 ${path2.join(" ")}`;
+          relinka("log", formatTableRow(text, desc, padding));
+        }
+      }
+    }
+  } else {
+    const subCommandNames = [];
+    const subCommandDefs = [];
+    const objectCommands = command.commands;
+    if (objectCommands) {
+      for (const [name, spec] of Object.entries(objectCommands)) {
+        try {
+          const cmd = await loadSubCommand(spec);
+          if (!cmd?.meta?.hidden) {
+            const aliasDisplay = cmd.meta?.aliases ? ` (aliases: ${cmd.meta.aliases.join(", ")})` : "";
+            subCommandNames.push(`${name}${aliasDisplay}`);
+            subCommandDefs.push({ name, def: cmd });
+          }
+        } catch (err) {
+          debugLog(`Error loading command ${name}:`, err);
+        }
+      }
+    }
+    let usageLine = pkgName;
+    if (parserOptions._isSubcommand) {
+      usageLine += ` ${cliName}`;
+    }
+    if (subCommandNames.length > 0) {
+      usageLine += " <command> [command's options]";
+    } else {
+      usageLine += ` [command's options] ${renderPositional(command.args)}`;
+    }
+    relinka("log", re.cyan(`Usage: ${usageLine}`));
+    if (subCommandDefs.length > 0) {
+      const randomIdx = Math.floor(Math.random() * subCommandDefs.length);
+      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):");
+      const commandItems = subCommandDefs.map(({ name, def }) => ({
+        text: `\u2022 ${name}`,
+        desc: def?.meta?.description
+      }));
+      const padding = calculatePadding(commandItems);
+      for (const { text, desc } of commandItems) {
+        relinka("log", formatTableRow(text, desc, padding));
+      }
+    }
+  }
+  relinka("info", "Available options:");
+  const optionItems = [
+    { text: "\u2022 -h, --help", desc: "Show help" },
+    { text: "\u2022 -v, --version", desc: "Show version" },
+    { text: "\u2022 --debug", desc: "Enable debug mode" }
+  ];
+  for (const [key, def] of Object.entries(command.args || {})) {
+    if (def.type === "positional") {
+      optionItems.push({
+        text: `\u2022 <${key}>`,
+        desc: `${def.description ?? ""}${def.required ? " | required" : ""}`
+      });
+    } else {
+      const text = `\u2022 --${key}${"alias" in def && def.alias ? `, -${def.alias}` : ""}`;
+      const parts = [
+        def.description ?? "",
+        `type=${def.type}`,
+        def.default !== void 0 ? `default=${JSON.stringify(def.default)}` : null,
+        def.required ? "required" : null,
+        def.dependencies ? `depends on: ${def.dependencies.map((r) => `--${r}`).join(", ")}` : null
+      ].filter(Boolean);
+      optionItems.push({ text, desc: parts.join(" | ") });
+    }
+  }
+  const optionsPadding = calculatePadding(optionItems);
+  for (const { text, desc } of optionItems) {
+    relinka("log", formatTableRow(text, desc, optionsPadding));
+  }
+}
+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
+    };
+  }
+  const execute = async (_ctx) => {
+    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;
+      }
+    }
+    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 pathExists(defaultCmdsRoot);
+        const finalCmdsRoot = exists ? defaultCmdsRoot : path.join(mainEntry, "app");
+        parserOptions.fileBased = {
+          enable: true,
+          cmdsRootPath: finalCmdsRoot
+        };
+      }
+      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;
+          }
+        }
+      }
+      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;
+      }
+      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 {
+      }
+      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");
+}
+function checkVersion(argv) {
+  return argv.includes("--version") || argv.includes("-v");
+}
+async function loadSubCommand(spec) {
+  if (typeof spec === "string") {
+    const mod = await import(spec);
+    if (!mod.default) {
+      throw new Error(`Subcommand module "${spec}" has no default export`);
+    }
+    return mod.default;
+  }
+  const imported = await spec();
+  if ("default" in imported && imported.default) {
+    return imported.default;
+  }
+  if (imported) {
+    return imported;
+  }
+  throw new Error("Subcommand import did not return a valid command");
+}
+async function runFileBasedSubCmd(subName, argv, fileCmdOpts, parserOptions, parentFinish, globalCliMeta) {
+  async function resolveCmdPath(baseDir, args) {
+    if (args.length === 0 || args[0] && isFlag(args[0])) {
+      const possibleFiles2 = [path.join(baseDir, "cmd.js"), path.join(baseDir, "cmd.ts")];
+      for (const file of possibleFiles2) {
+        if (await pathExists(file)) {
+          return { importPath: file, leftoverArgv: args };
+        }
+      }
+      throw new Error(
+        `
+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] || "");
+    if (await pathExists(nextDir) && (await stat(nextDir)).isDirectory()) {
+      return resolveCmdPath(nextDir, args.slice(1));
+    }
+    const possibleFiles = [path.join(baseDir, "cmd.js"), path.join(baseDir, "cmd.ts")];
+    for (const file of possibleFiles) {
+      if (await pathExists(file)) {
+        return { importPath: file, leftoverArgv: args };
+      }
+    }
+    throw new Error(
+      `
+Unknown command or arguments: ${args.join(" ")}
+Info for this CLI's developer: No valid command file found in ${baseDir}`
+    );
+  }
+  const startDir = path.join(fileCmdOpts.cmdsRootPath, subName);
+  if (!await pathExists(startDir) || !(await stat(startDir)).isDirectory()) {
+    const attempted = [subName, ...argv].join(" ");
+    const expectedPath = path.relative(
+      process.cwd(),
+      path.join(fileCmdOpts.cmdsRootPath, subName, "cmd.{ts,js}")
+    );
+    const allCommands = await findRecursiveFileBasedCommands(fileCmdOpts.cmdsRootPath);
+    const commandNames = allCommands.map((cmd) => cmd.path.join(" "));
+    let closestMatch = "";
+    let minDistance = Number.POSITIVE_INFINITY;
+    for (const cmd of commandNames) {
+      const distance = levenshteinDistance(subName, cmd.split(" ")[0] || "");
+      if (distance < minDistance) {
+        minDistance = distance;
+        closestMatch = cmd;
+      }
+    }
+    const suggestion = minDistance <= 3 ? ` (Did you mean: \`${closestMatch}\`?)` : "";
+    throw new Error(
+      `
+Unknown command or arguments: ${attempted}${suggestion}
+Info for this CLI's developer: No valid command directory found, expected: ${expectedPath}`
+    );
+  }
+  const { importPath, leftoverArgv } = await resolveCmdPath(startDir, argv);
+  const imported = await import(path.resolve(importPath));
+  const subCommand = imported.default;
+  if (!subCommand) {
+    throw new Error(`File-based subcommand has no default export or is invalid: ${importPath}`);
+  }
+  try {
+    const subCtx = await runCommandWithArgs(subCommand, leftoverArgv, parserOptions, globalCliMeta);
+    if (typeof parentFinish === "function" && subCtx) await parentFinish(subCtx);
+  } finally {
+  }
+}
+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 }, globalCliMeta);
+      if (parserOptions.autoExit !== false) process.exit(0);
+      return;
+    }
+    const subCtx = await runCommandWithArgs(subCommand, argv, parserOptions, globalCliMeta, true);
+    if (typeof parentFinish === "function" && subCtx) await parentFinish(subCtx);
+  } finally {
+  }
+}
+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"
+  );
+  const defaultMap = {};
+  for (const [argKey, def] of Object.entries(command.args || {})) {
+    if (def.type === "boolean") {
+      defaultMap[argKey] = def.default !== void 0 ? def.default : false;
+    } else if (def.default !== void 0) {
+      defaultMap[argKey] = def.type === "array" && typeof def.default === "string" ? [def.default] : def.default;
+    }
+  }
+  const mergedParserOptions = {
+    ...parserOptions,
+    boolean: [...parserOptions.boolean || [], ...booleanKeys],
+    defaults: { ...defaultMap, ...parserOptions.defaults || {} }
+  };
+  const parsed = reliArgParser(argv, mergedParserOptions);
+  debugLog("Parsed arguments:", parsed);
+  const finalArgs = {};
+  const positionalKeys = Object.keys(command.args || {}).filter(
+    (k) => command.args?.[k]?.type === "positional"
+  );
+  const leftoverPositionals = [...parsed._ || []];
+  for (let i = 0; i < positionalKeys.length; i++) {
+    const key = positionalKeys[i];
+    if (!key || !command.args) continue;
+    const def = command.args[key];
+    const val = leftoverPositionals[i];
+    finalArgs[key] = val != null && def ? castArgValue(def, val, key) : def?.default;
+  }
+  const otherKeys = Object.keys(command.args || {}).filter(
+    (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];
+    }
+    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, globalCliMeta);
+      relinka("error", `Missing required argument: --${key}`);
+      if (autoExit) process.exit(1);
+      else throw new Error(`Missing required argument: --${key}`);
+    }
+    if (argUsed && def.dependencies?.length) {
+      const missingDeps = def.dependencies.filter((d) => {
+        const depVal = parsed[d] ?? defaultMap[d];
+        return !depVal;
+      });
+      if (missingDeps.length > 0) {
+        const depsList = missingDeps.map((d) => `--${d}`).join(", ");
+        throw new Error(
+          `Argument --${key} can only be used when ${depsList} ${missingDeps.length === 1 ? "is" : "are"} set`
+        );
+      }
+    }
+    finalArgs[key] = def.type === "boolean" ? Boolean(casted) : casted;
+  }
+  const ctx = {
+    args: finalArgs,
+    raw: argv
+  };
+  try {
+    if (command.run) {
+      await command.run(ctx);
+    } else {
+      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, 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, globalCliMeta);
+      relinka("error", `Unknown command or arguments: ${attempted}`);
+      if (autoExit) {
+        process.exit(1);
+      } else {
+        throw new Error(`Command "${cmdName}" is not runnable.`);
+      }
+    }
+  } catch (err) {
+    relinka("error", `Error while executing command:
+${String(err)}`);
+    if (autoExit) process.exit(1);
+    else throw err;
+  }
+  if (returnCtx) return ctx;
+  return;
+}
+function castArgValue(def, rawVal, argName) {
+  if (rawVal == null) {
+    if (def.type === "array" && typeof def.default === "string") {
+      return [def.default];
+    }
+    return def.default ?? void 0;
+  }
+  let castedValue;
+  switch (def.type) {
+    case "boolean":
+      if (typeof rawVal === "string") {
+        const lower = rawVal.toLowerCase();
+        if (lower === "true") castedValue = true;
+        else if (lower === "false") castedValue = false;
+        else castedValue = Boolean(rawVal);
+      } else {
+        castedValue = Boolean(rawVal);
+      }
+      if (def.allowed && !def.allowed.includes(castedValue)) {
+        throw new Error(
+          `Invalid value for --${argName}: ${rawVal}. Allowed values are: ${def.allowed.join(", ")}`
+        );
+      }
+      return castedValue;
+    case "string":
+      castedValue = typeof rawVal === "string" ? rawVal : String(rawVal);
+      if (def.allowed && !def.allowed.includes(castedValue)) {
+        throw new Error(
+          `Invalid value for --${argName}: ${rawVal}. Allowed values are: ${def.allowed.join(", ")}`
+        );
+      }
+      return castedValue;
+    case "number": {
+      const n = Number(rawVal);
+      if (Number.isNaN(n)) {
+        throw new Error(`Invalid number provided for --${argName}: ${rawVal}`);
+      }
+      if (def.allowed && !def.allowed.includes(n)) {
+        throw new Error(
+          `Invalid value for --${argName}: ${rawVal}. Allowed values are: ${def.allowed.join(", ")}`
+        );
+      }
+      return n;
+    }
+    case "positional":
+      castedValue = String(rawVal);
+      if (def.allowed && !def.allowed.includes(castedValue)) {
+        throw new Error(
+          `Invalid value for <${argName}>: ${rawVal}. Allowed values are: ${def.allowed.join(", ")}`
+        );
+      }
+      return castedValue;
+    case "array": {
+      const arrVal = Array.isArray(rawVal) ? rawVal : [String(rawVal)];
+      const result = [];
+      const arrValStr = arrVal.map(String);
+      let warned = false;
+      for (let v of arrValStr) {
+        if (!warned && (v.startsWith("[") && !v.endsWith("]") || !v.startsWith("[") && v.endsWith("]"))) {
+          relinka("error", `Don't use quotes around array elements.`);
+          relinka("error", `Also \u2014 don't use spaces \u2014 unless you wrap the whole array in quotes.`);
+          relinka(
+            "warn",
+            `Array argument --${argName}: Detected possible shell splitting of bracketed value ('${v}').`
+          );
+          relinka(
+            "warn",
+            `If you intended to pass a bracketed list, quote the whole value like: --${argName} "[a, b, c]"`
+          );
+        }
+        warned = true;
+        if (v.startsWith("[") && v.endsWith("]")) {
+          v = v.slice(1, -1);
+        }
+        const parts = v.split(/\s*,\s*/).filter(Boolean);
+        parts.forEach((p) => {
+          if (p.startsWith('"') && p.endsWith('"') || p.startsWith("'") && p.endsWith("'")) {
+            throw new Error(
+              `Array argument --${argName}: Quoted values are not supported due to shell parsing limitations. Please avoid using single or double quotes around array elements.`
+            );
+          }
+          if (def.allowed && !def.allowed.includes(p)) {
+            throw new Error(
+              `Invalid value in array --${argName}: ${p}. Allowed values are: ${def.allowed.join(", ")}`
+            );
+          }
+        });
+        result.push(...parts);
+      }
+      return result;
+    }
+    default:
+      return rawVal;
+  }
+}
+function renderPositional(args) {
+  const positionalKeys = Object.keys(args || {}).filter((k) => args?.[k]?.type === "positional");
+  return positionalKeys.map((k) => `<${k}>`).join(" ");
+}
+export function defineArgs(args) {
+  return args;
+}
+function normalizeArgv(argv) {
+  const normalized = [];
+  for (const arg of argv) {
+    const parts = arg.split(/\s+/).filter((part) => part.length > 0);
+    normalized.push(...parts);
+  }
+  return normalized;
+}
+function getParsedContext(command, argv, parserOptions) {
+  const normalizedArgv = normalizeArgv(argv);
+  const booleanKeys = Object.keys(command.args || {}).filter(
+    (k) => command.args?.[k]?.type === "boolean"
+  );
+  const defaultMap = {};
+  for (const [argKey, def] of Object.entries(command.args || {})) {
+    if (def.type === "boolean") {
+      defaultMap[argKey] = def.default !== void 0 ? def.default : false;
+    } else if (def.default !== void 0) {
+      defaultMap[argKey] = def.type === "array" && typeof def.default === "string" ? [def.default] : def.default;
+    }
+  }
+  const mergedParserOptions = {
+    ...parserOptions,
+    boolean: [...parserOptions.boolean || [], ...booleanKeys],
+    defaults: { ...defaultMap, ...parserOptions.defaults || {} }
+  };
+  const parsed = reliArgParser(normalizedArgv, mergedParserOptions);
+  const finalArgs = {};
+  const positionalKeys = Object.keys(command.args || {}).filter(
+    (k) => command.args?.[k]?.type === "positional"
+  );
+  const leftoverPositionals = [...parsed._ || []];
+  for (let i = 0; i < positionalKeys.length; i++) {
+    const key = positionalKeys[i];
+    if (!key || !command.args) continue;
+    const def = command.args[key];
+    const val = leftoverPositionals[i];
+    finalArgs[key] = val != null && def ? castArgValue(def, val, key) : def?.default;
+  }
+  const otherKeys = Object.keys(command.args || {}).filter(
+    (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];
+    }
+    if (def.type === "boolean") {
+      finalArgs[key] = rawVal !== void 0 ? castArgValue(def, rawVal, key) : false;
+    } else {
+      finalArgs[key] = castArgValue(def, rawVal, key);
+    }
+  }
+  return { args: finalArgs, raw: argv };
+}
+async function resolveFileBasedCommandPath(cmdsRoot, argv) {
+  let currentDir = cmdsRoot;
+  const pathSegments = [];
+  let leftover = [...argv];
+  while (leftover.length > 0 && leftover[0] && !isFlag(leftover[0])) {
+    const nextDir = path.join(currentDir, leftover[0]);
+    if (await pathExists(nextDir) && (await stat(nextDir)).isDirectory()) {
+      currentDir = nextDir;
+      pathSegments.push(leftover[0]);
+      leftover = leftover.slice(1);
+    } else {
+      break;
+    }
+  }
+  for (const fname of ["cmd.ts", "cmd.js"]) {
+    const fpath = path.join(currentDir, fname);
+    if (await pathExists(fpath)) {
+      const imported = await import(path.resolve(fpath));
+      if (imported.default) {
+        return {
+          def: imported.default,
+          path: pathSegments,
+          leftoverArgv: leftover
+        };
+      }
+    }
+  }
+  return null;
+}
+function levenshteinDistance(a, b) {
+  if (a.length === 0) return b.length;
+  if (b.length === 0) return a.length;
+  const matrix = [];
+  for (let i = 0; i <= b.length; i++) {
+    matrix[i] = [i];
+  }
+  for (let j = 0; j <= a.length; j++) {
+    matrix[0][j] = j;
+  }
+  for (let i = 1; i <= b.length; i++) {
+    for (let j = 1; j <= a.length; j++) {
+      if (b.charAt(i - 1) === a.charAt(j - 1)) {
+        matrix[i][j] = matrix[i - 1][j - 1];
+      } else {
+        matrix[i][j] = Math.min(
+          matrix[i - 1][j - 1] + 1,
+          // substitution
+          matrix[i][j - 1] + 1,
+          // insertion
+          matrix[i - 1][j] + 1
+          // deletion
+        );
+      }
+    }
+  }
+  return matrix[b.length][a.length];
+}