@reliverse/rempts 1.7.65 → 2.2.7

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

@@ -1,1037 +0,0 @@
-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";
-const isBunRuntime = Boolean(
-  // Prefer versions flag to avoid TS type needs
-  process?.versions?.bun || typeof globalThis.Bun !== "undefined"
-);
-const _pathExistsCache = /* @__PURE__ */ new Map();
-async function pathExists(p) {
-  const cached = _pathExistsCache.get(p);
-  if (cached !== void 0) return cached;
-  try {
-    if (isBunRuntime) {
-      const bun = globalThis.Bun;
-      if (bun?.file) {
-        const exists = await bun.file(p).exists();
-        _pathExistsCache.set(p, exists);
-        return exists;
-      }
-    }
-    await stat(p);
-    _pathExistsCache.set(p, true);
-    return true;
-  } catch (_error) {
-    _pathExistsCache.set(p, false);
-    return false;
-  }
-}
-async function isDirectory(p) {
-  try {
-    const s = await stat(p);
-    return s.isDirectory();
-  } catch {
-    return false;
-  }
-}
-let _cachedPkgJson;
-async function readPkgJsonCached() {
-  if (_cachedPkgJson) return _cachedPkgJson;
-  try {
-    if (isBunRuntime) {
-      const bun = globalThis.Bun;
-      if (bun?.file) {
-        _cachedPkgJson = await bun.file("package.json").json();
-      } else {
-        _cachedPkgJson = await readPackageJSON();
-      }
-    } else {
-      _cachedPkgJson = await readPackageJSON();
-    }
-  } catch (_e) {
-    _cachedPkgJson = void 0;
-  }
-  return _cachedPkgJson;
-}
-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");
-let _relinkaConfigured = false;
-async function ensureRelinkaConfigured() {
-  if (_relinkaConfigured) return;
-  await relinkaConfig();
-  _relinkaConfigured = true;
-}
-function debugLog(...args) {
-  if (isDebugMode) {
-    void ensureRelinkaConfigured().then(() => 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 = {
-    ...options.meta !== void 0 && { meta: options.meta },
-    args: options.args || {},
-    ...options.run !== void 0 && { run: options.run },
-    ...commands !== void 0 && { commands },
-    ...onCmdInit !== void 0 && { onCmdInit },
-    ...onCmdExit !== void 0 && { onCmdExit },
-    ...onLauncherInit !== void 0 && { onLauncherInit },
-    ...onLauncherExit !== void 0 && { onLauncherExit },
-    // Backward-compatible aliases
-    ...onCmdInit !== void 0 && { setup: onCmdInit },
-    ...onCmdExit !== void 0 && { cleanup: onCmdExit }
-  };
-  Object.defineProperty(cmdObj, "subCommands", {
-    get() {
-      return this.commands;
-    },
-    enumerable: false,
-    configurable: true
-  });
-  return cmdObj;
-}
-let _cachedDefaultCliName;
-let _cachedDefaultCliVersion;
-let _cachedDefaultCliDescription;
-async function getDefaultCliNameAndVersion() {
-  if (_cachedDefaultCliName)
-    return { name: _cachedDefaultCliName, version: _cachedDefaultCliVersion };
-  try {
-    const pkg = await readPkgJsonCached() ?? {};
-    let name = pkg.name || "cli";
-    if (name.startsWith("@")) {
-      name = name.split("/").pop() || name;
-    }
-    _cachedDefaultCliName = name;
-    _cachedDefaultCliVersion = pkg.version;
-    if (pkg.description && !_cachedDefaultCliDescription) {
-      _cachedDefaultCliDescription = pkg.description;
-    }
-    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) {
-      await getDefaultCliNameAndVersion();
-      if (_cachedDefaultCliDescription) description = _cachedDefaultCliDescription;
-    }
-    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 = {
-      ...options.fileBased !== void 0 && { fileBased: options.fileBased },
-      ...options.autoExit !== void 0 && { autoExit: options.autoExit },
-      ...options.metaSettings !== void 0 && { metaSettings: options.metaSettings }
-    };
-    globalCliMeta = {
-      ...options.name !== void 0 && { name: options.name },
-      ...options.version !== void 0 && { version: options.version },
-      ...options.description !== void 0 && { description: options.description }
-    };
-  } else {
-    const inlineOptions = options;
-    const {
-      name,
-      version,
-      description,
-      fileBased,
-      autoExit,
-      metaSettings,
-      mainCommand,
-      ...commandOptions
-    } = inlineOptions;
-    command = {
-      ...commandOptions.meta !== void 0 && { meta: commandOptions.meta },
-      ...commandOptions.args !== void 0 && { args: commandOptions.args },
-      ...commandOptions.run !== void 0 && { run: commandOptions.run },
-      ...commandOptions.commands !== void 0 && { commands: commandOptions.commands },
-      ...commandOptions.onCmdInit !== void 0 && { onCmdInit: commandOptions.onCmdInit },
-      ...commandOptions.onCmdExit !== void 0 && { onCmdExit: commandOptions.onCmdExit },
-      ...commandOptions.onLauncherInit !== void 0 && {
-        onLauncherInit: commandOptions.onLauncherInit
-      },
-      ...commandOptions.onLauncherExit !== void 0 && {
-        onLauncherExit: commandOptions.onLauncherExit
-      }
-    };
-    parserOptions = {
-      ...fileBased !== void 0 && { fileBased },
-      ...autoExit !== void 0 && { autoExit },
-      ...metaSettings !== void 0 && { metaSettings }
-    };
-    globalCliMeta = {
-      ...name !== void 0 && { name },
-      ...version !== void 0 && { version },
-      ...description !== void 0 && { 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)) {
-        await ensureRelinkaConfigured();
-        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) {
-          await ensureRelinkaConfigured();
-          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) {
-            await ensureRelinkaConfigured();
-            relinka("error", "Error running subcommand:", err.message);
-            if (autoExit) process.exit(1);
-            throw err;
-          }
-        }
-      }
-      await ensureRelinkaConfigured();
-      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 (_relinkaConfigured) 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 isDirectory(nextDir)) {
-      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 isDirectory(startDir)) {
-    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 isDirectory(nextDir)) {
-      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];
-}