@alcyone-labs/arg-parser 1.0.0 → 1.1.0

package/dist/index.mjs

@@ -6,11 +6,15 @@ var __privateGet = (obj, member, getter) => (__accessCheck(obj, member, "read fr
 var __privateAdd = (obj, member, value) => member.has(obj) ? __typeError("Cannot add the same private member more than once") : member instanceof WeakSet ? member.add(obj) : member.set(obj, value);
 var __privateSet = (obj, member, value, setter) => (__accessCheck(obj, member, "write to private field"), setter ? setter.call(obj, value) : member.set(obj, value), value);
 var __privateMethod = (obj, member, method) => (__accessCheck(obj, member, "access private method"), method);
-var __flags, _throwForDuplicateFlags, _appName, _appCommandName, _subCommandName, _parameters, _handler, _throwForDuplicateFlags2, _description, _handleErrors, _parentParser, _lastParseResult, _inheritParentFlags, _subCommands, _flagManager, _ArgParser_instances, _identifyCommandChainAndParsers_fn, _handleGlobalChecks_fn, _validateMandatoryFlags_fn, _applyDefaultValues_fn, _prepareAndExecuteHandler_fn, parseFlags_fn, displayErrorAndExit_fn, _printRecursiveToConsole_fn, _buildRecursiveString_fn, _buildRecursiveJson_fn;
+var __flags, _throwForDuplicateFlags, _appName, _appCommandName, _subCommandName, _parameters, _handler, _throwForDuplicateFlags2, _description, _handleErrors, _parentParser, _lastParseResult, _inheritParentFlags, _subCommands, _flagManager, _fuzzyMode, _ArgParserBase_instances, _identifyCommandChainAndParsers_fn, _handleGlobalChecks_fn, _validateMandatoryFlags_fn, _applyDefaultValues_fn, _prepareAndExecuteHandler_fn, parseFlags_fn, _enableFuzzyMode_fn, displayErrorAndExit_fn, _printRecursiveToConsole_fn, _buildRecursiveString_fn, _buildRecursiveJson_fn, _generateDefaultEnvFileName_fn, _handleSaveToEnvFlag_fn, _saveToEnvFile_fn, _loadEnvFile_fn, _parseEnvFile_fn, _parseYamlFile_fn, _parseJsonFile_fn, _parseTomlFile_fn, _convertConfigToFlagValues_fn, _convertValueToFlagType_fn, _mergeEnvConfigWithArgs_fn, _generateEnvFormat_fn, _generateYamlFormat_fn, _generateJsonFormat_fn, _generateTomlFormat_fn, _getTypeString_fn, _ArgParser_instances, _startSingleTransport_fn;
+import * as fs from "node:fs";
+import * as path from "node:path";
 import chalk from "chalk";
 import { createRegExp, anyOf, oneOrMore, char } from "magic-regexp";
+import * as yaml from "js-yaml";
+import * as toml from "@iarna/toml";
+import * as dotenv from "dotenv";
 import { z } from "zod";
-const path = {};
 const zodFlagSchema = z.object({
   name: z.string().min(1, "Flag name cannot be empty").describe(
     "The output property name, used as a return key `{name: value}`. Must be unique."
@@ -35,14 +39,17 @@ const zodFlagSchema = z.object({
       message: "Must be Boolean constructor"
     }),
     z.any().refine((val) => val === Array, {
+      // Native Array constructor
       message: "Must be Array constructor"
     }),
     z.any().refine((val) => val === Object, {
+      // Native Object constructor
       message: "Must be Object constructor"
     }),
     z.function().args(z.string()).returns(z.any()),
-    // Custom parser function
+    // Custom parser function (value: string) => any
     z.string().refine(
+      // String literal types
       (value) => ["boolean", "string", "number", "array", "object"].includes(
         value.toLowerCase()
       ),
@@ -51,7 +58,7 @@ const zodFlagSchema = z.object({
       }
     )
   ]).default("string").describe(
-    "Expected data type or a custom parser function. Defaults to 'string'."
+    "Expected data type (constructor or string literal) or a custom parser function. Defaults to 'string'."
   ),
   mandatory: z.union([z.boolean(), z.function().args(z.any()).returns(z.boolean())]).optional().describe(
     "Makes the flag mandatory, can be a boolean or a function conditional on other args."
@@ -177,9 +184,9 @@ class ArgParserError extends Error {
     this.commandChain = cmdChain;
   }
 }
-const _ArgParser = class _ArgParser {
+const _ArgParserBase = class _ArgParserBase {
   constructor(options = {}, initialFlags) {
-    __privateAdd(this, _ArgParser_instances);
+    __privateAdd(this, _ArgParserBase_instances);
     __privateAdd(this, _appName, "Argument Parser");
     __privateAdd(this, _appCommandName);
     __privateAdd(this, _subCommandName, "");
@@ -198,6 +205,7 @@ const _ArgParser = class _ArgParser {
     __privateAdd(this, _inheritParentFlags, false);
     __privateAdd(this, _subCommands, /* @__PURE__ */ new Map());
     __privateAdd(this, _flagManager);
+    __privateAdd(this, _fuzzyMode, false);
     __privateSet(this, _appName, options.appName || "app");
     if (options.blankSpaceWidth && !isNaN(Number(options.blankSpaceWidth)) && Number(options.blankSpaceWidth) > 20)
       __privateGet(this, _parameters).blankSpaceWidth = Number(options.blankSpaceWidth);
@@ -247,9 +255,27 @@ const _ArgParser = class _ArgParser {
   get flagNames() {
     return __privateGet(this, _flagManager).flagNames;
   }
+  getAppName() {
+    return __privateGet(this, _appName);
+  }
+  getAppCommandName() {
+    return __privateGet(this, _appCommandName);
+  }
+  getSubCommandName() {
+    return __privateGet(this, _subCommandName);
+  }
+  getDescription() {
+    return __privateGet(this, _description);
+  }
+  getHandler() {
+    return __privateGet(this, _handler);
+  }
+  getSubCommands() {
+    return __privateGet(this, _subCommands);
+  }
   _addToOutput(flag, arg, output, _parseOptions) {
     let value = arg;
-    if (flag.type === Boolean) {
+    if (flag["type"] === Boolean) {
       if (typeof arg === "boolean") {
         value = arg;
       } else if (typeof arg === "string") {
@@ -300,9 +326,9 @@ const _ArgParser = class _ArgParser {
       throw new Error(`Sub-command '${subCommandConfig.name}' already exists`);
     }
     const subParser = subCommandConfig.parser;
-    if (!(subParser instanceof _ArgParser)) {
+    if (!(subParser instanceof _ArgParserBase)) {
       throw new Error(
-        `Parser for subcommand '${subCommandConfig.name}' is not an instance of ArgParser. Please provide 'new ArgParser(...)' for the 'parser' property of an ISubCommand.`
+        `Parser for subcommand '${subCommandConfig.name}' is not an instance of ArgParserBase. Please provide 'new ArgParserBase(...)' for the 'parser' property of an ISubCommand.`
       );
     }
     __privateSet(subParser, _parentParser, this);
@@ -340,21 +366,21 @@ const _ArgParser = class _ArgParser {
     if (filePath) {
       try {
         const dir = path.dirname(filePath);
-        if (!path.existsSync(dir)) {
-          path.mkdirSync(dir, { recursive: true });
+        if (!fs.existsSync(dir)) {
+          fs.mkdirSync(dir, { recursive: true });
         }
         if (filePath.toLowerCase().endsWith(".json")) {
-          const outputObject = __privateMethod(this, _ArgParser_instances, _buildRecursiveJson_fn).call(this, this);
+          const outputObject = __privateMethod(this, _ArgParserBase_instances, _buildRecursiveJson_fn).call(this, this);
           const jsonString = JSON.stringify(outputObject, null, 2);
-          path.writeFileSync(filePath, jsonString);
+          fs.writeFileSync(filePath, jsonString);
           console.log(`ArgParser configuration JSON dumped to: ${filePath}`);
         } else {
-          const outputString = __privateMethod(this, _ArgParser_instances, _buildRecursiveString_fn).call(this, this, 0);
+          const outputString = __privateMethod(this, _ArgParserBase_instances, _buildRecursiveString_fn).call(this, this, 0);
           const plainText = outputString.replace(
             /[\u001b\u009b][[()#;?]*(?:[0-9]{1,4}(?:;[0-9]{0,4})*)?[0-9A-ORZcf-nqry=><]/g,
             ""
           );
-          path.writeFileSync(filePath, plainText);
+          fs.writeFileSync(filePath, plainText);
           console.log(`ArgParser configuration text dumped to: ${filePath}`);
         }
       } catch (error) {
@@ -365,12 +391,21 @@ const _ArgParser = class _ArgParser {
       }
     } else {
       console.log("\n--- ArgParser Configuration Dump ---");
-      __privateMethod(this, _ArgParser_instances, _printRecursiveToConsole_fn).call(this, this, 0);
+      __privateMethod(this, _ArgParserBase_instances, _printRecursiveToConsole_fn).call(this, this, 0);
       console.log("--- End Configuration Dump ---\\n");
     }
   }
   parse(processArgs, options) {
-    if (__privateMethod(this, _ArgParser_instances, _handleGlobalChecks_fn).call(this, processArgs, options)) {
+    var _a;
+    const originalProcessArgs = [...processArgs];
+    const shouldPreventExecution = typeof process !== "undefined" && (process.env["ARGPARSER_FUZZY_MODE"] === "true" || process.argv && process.argv.includes("--s-enable-fuzzy") && !processArgs.includes("--s-enable-fuzzy")) && !(options == null ? void 0 : options.skipHelpHandling);
+    if (shouldPreventExecution) {
+      return {
+        _fuzzyModePreventedExecution: true,
+        _originalInputArgs: originalProcessArgs
+      };
+    }
+    if (__privateMethod(this, _ArgParserBase_instances, _handleGlobalChecks_fn).call(this, processArgs, options)) {
       return {};
     }
     try {
@@ -378,25 +413,34 @@ const _ArgParser = class _ArgParser {
         finalParser: identifiedFinalParser,
         commandChain: identifiedCommandChain,
         parserChain: identifiedParserChain
-      } = __privateMethod(this, _ArgParser_instances, _identifyCommandChainAndParsers_fn).call(this, processArgs, this, [], [this]);
+      } = __privateMethod(this, _ArgParserBase_instances, _identifyCommandChainAndParsers_fn).call(this, processArgs, this, [], [this]);
+      if (__privateMethod(_a = identifiedFinalParser, _ArgParserBase_instances, _handleSaveToEnvFlag_fn).call(_a, processArgs, identifiedParserChain)) {
+        return {};
+      }
       const { finalArgs, handlerToExecute } = this._parseRecursive(
         processArgs,
         this,
         {},
         [],
-        options
+        options,
+        void 0
       );
       if (identifiedCommandChain.length > 0) {
         finalArgs.$commandChain = identifiedCommandChain;
       }
-      __privateMethod(this, _ArgParser_instances, _validateMandatoryFlags_fn).call(this, finalArgs, identifiedParserChain, identifiedCommandChain);
-      __privateMethod(this, _ArgParser_instances, _applyDefaultValues_fn).call(this, finalArgs, identifiedFinalParser);
-      __privateMethod(this, _ArgParser_instances, _prepareAndExecuteHandler_fn).call(this, handlerToExecute, finalArgs, (options == null ? void 0 : options.skipHandlers) ?? false);
+      if (__privateGet(this, _fuzzyMode)) {
+        finalArgs._originalInputArgs = originalProcessArgs;
+      }
+      if (!__privateGet(this, _fuzzyMode)) {
+        __privateMethod(this, _ArgParserBase_instances, _validateMandatoryFlags_fn).call(this, finalArgs, identifiedParserChain, identifiedCommandChain);
+      }
+      __privateMethod(this, _ArgParserBase_instances, _applyDefaultValues_fn).call(this, finalArgs, identifiedFinalParser);
+      __privateMethod(this, _ArgParserBase_instances, _prepareAndExecuteHandler_fn).call(this, handlerToExecute, finalArgs, (options == null ? void 0 : options.skipHandlers) ?? false);
       return finalArgs;
     } catch (error) {
       if (error instanceof ArgParserError) {
         if (__privateGet(this, _handleErrors)) {
-          __privateMethod(this, _ArgParser_instances, displayErrorAndExit_fn).call(this, error);
+          __privateMethod(this, _ArgParserBase_instances, displayErrorAndExit_fn).call(this, error);
           return {};
         } else {
           throw error;
@@ -410,7 +454,7 @@ const _ArgParser = class _ArgParser {
    * Recursive helper for parsing arguments and handling sub-commands.
    * This method assumes the global help check has already been performed in `parse`.
    */
-  _parseRecursive(argsToParse, currentParser, accumulatedParentArgs, commandChainSoFar, options) {
+  _parseRecursive(argsToParse, currentParser, accumulatedParentArgs, commandChainSoFar, options, parentParser) {
     var _a, _b;
     let subCommandIndex = -1;
     let subCommandName = null;
@@ -423,8 +467,8 @@ const _ArgParser = class _ArgParser {
       }
     }
     const argsForCurrentLevel = subCommandIndex === -1 ? argsToParse : argsToParse.slice(0, subCommandIndex);
-    const { parsedArgs: currentLevelArgs, firstUnconsumedIndex } = __privateMethod(_a = currentParser, _ArgParser_instances, parseFlags_fn).call(_a, argsForCurrentLevel, options);
-    __privateMethod(_b = currentParser, _ArgParser_instances, _applyDefaultValues_fn).call(_b, currentLevelArgs, currentParser);
+    const { parsedArgs: currentLevelArgs, firstUnconsumedIndex } = __privateMethod(_a = currentParser, _ArgParserBase_instances, parseFlags_fn).call(_a, argsForCurrentLevel, options);
+    __privateMethod(_b = currentParser, _ArgParserBase_instances, _applyDefaultValues_fn).call(_b, currentLevelArgs, currentParser);
     const combinedArgsFromThisAndParents = {
       ...accumulatedParentArgs,
       ...currentLevelArgs
@@ -449,7 +493,8 @@ const _ArgParser = class _ArgParser {
             args: currentLevelArgs,
             parentArgs: accumulatedParentArgs,
             commandChain: commandChainSoFar,
-            parser: currentParser
+            parser: currentParser,
+            parentParser
           }
         };
       }
@@ -463,7 +508,7 @@ const _ArgParser = class _ArgParser {
       );
     }
     const subCommandConfig = __privateGet(currentParser, _subCommands).get(subCommandName);
-    if (!subCommandConfig || !(subCommandConfig.parser instanceof _ArgParser)) {
+    if (!subCommandConfig || !(subCommandConfig.parser instanceof _ArgParserBase)) {
       throw new ArgParserError(
         `Internal error: Subcommand '${subCommandName}' is misconfigured or its parser is not a valid ArgParser instance.`,
         commandChainSoFar
@@ -481,7 +526,8 @@ const _ArgParser = class _ArgParser {
       nextParser,
       combinedArgsForNextLevel,
       nextCommandChain,
-      options
+      options,
+      currentParser
     );
   }
   helpText() {
@@ -513,7 +559,7 @@ const _ArgParser = class _ArgParser {
 `;
       help += Array.from(__privateGet(this, _subCommands).entries()).sort(([nameA], [nameB]) => nameA.localeCompare(nameB)).map(([name, subCommandConfig]) => {
         const actualSubParserInstance = subCommandConfig.parser;
-        if (!(actualSubParserInstance instanceof _ArgParser)) {
+        if (!(actualSubParserInstance instanceof _ArgParserBase)) {
           return `${indent()}${green(name.padEnd(20))} [Error: Subcommand '${name}' has an invalid parser configuration]`;
         }
         let subHelp = `${indent()}${green(name.padEnd(20))} ${white(__privateGet(actualSubParserInstance, _description) || "")}`;
@@ -556,7 +602,7 @@ ${cyan("Flags:")}
     const localFlags = __privateGet(this, _flagManager).flags;
     if (localFlags.length > 0) {
       help += localFlags.sort((flagA, flagB) => flagA["name"].localeCompare(flagB["name"])).map((flag) => {
-        const optionsText = flag["options"].toSorted((a, b) => a.length - b.length).map((opt) => green(opt)).join(", ");
+        const optionsText = flag["options"].slice().sort((a, b) => a.length - b.length).map((opt) => green(opt)).join(", ");
         const isMandatory = typeof flag.mandatory === "function" ? "dynamic" : flag.mandatory;
         const mandatoryIndicator = isMandatory === true ? ` ${red(__privateGet(this, _parameters).mandatoryCharacter)}` : isMandatory === "dynamic" ? ` ${dim("(conditionally mandatory)")}` : "";
         const descriptionLines = Array.isArray(flag["description"]) ? flag["description"] : [flag["description"]];
@@ -636,7 +682,8 @@ _lastParseResult = new WeakMap();
 _inheritParentFlags = new WeakMap();
 _subCommands = new WeakMap();
 _flagManager = new WeakMap();
-_ArgParser_instances = new WeakSet();
+_fuzzyMode = new WeakMap();
+_ArgParserBase_instances = new WeakSet();
 _identifyCommandChainAndParsers_fn = function(argsToParse, currentParser, commandChainSoFar, parserChainSoFar) {
   let subCommandIndex = -1;
   let subCommandName = null;
@@ -657,7 +704,7 @@ _identifyCommandChainAndParsers_fn = function(argsToParse, currentParser, comman
     };
   }
   const subCommandConfig = __privateGet(currentParser, _subCommands).get(subCommandName);
-  if (!subCommandConfig || !(subCommandConfig.parser instanceof _ArgParser)) {
+  if (!subCommandConfig || !(subCommandConfig.parser instanceof _ArgParserBase)) {
     throw new Error(
       `Internal error: Subcommand '${subCommandName}' configuration is invalid or parser is missing.`
     );
@@ -666,33 +713,72 @@ _identifyCommandChainAndParsers_fn = function(argsToParse, currentParser, comman
   const nextArgs = argsToParse.slice(subCommandIndex + 1);
   const nextCommandChain = [...commandChainSoFar, subCommandName];
   const nextParserChain = [...parserChainSoFar, nextParser];
-  return __privateMethod(this, _ArgParser_instances, _identifyCommandChainAndParsers_fn).call(this, nextArgs, nextParser, nextCommandChain, nextParserChain);
+  return __privateMethod(this, _ArgParserBase_instances, _identifyCommandChainAndParsers_fn).call(this, nextArgs, nextParser, nextCommandChain, nextParserChain);
 };
 _handleGlobalChecks_fn = function(processArgs, options) {
-  var _a, _b, _c, _d;
-  if (processArgs.length === 0 && !__privateGet(this, _parentParser) && !__privateGet(this, _handler)) {
+  var _a, _b, _c, _d, _e, _f;
+  const isRootCliParser = !__privateGet(this, _parentParser) && !!__privateGet(this, _appCommandName);
+  if (processArgs.length === 0 && isRootCliParser && !__privateGet(this, _handler)) {
     console.log(this.helpText());
     if (typeof process === "object" && typeof process.exit === "function") {
       process.exit(0);
     }
     return true;
   }
-  if (processArgs.includes("--LIB-debug-print")) {
+  if (processArgs.includes("--s-debug-print")) {
     this.printAll("ArgParser.full.json");
     if (typeof process === "object" && typeof process.exit === "function") {
       process.exit(0);
     }
     return true;
   }
-  const { finalParser: identifiedFinalParser } = __privateMethod(this, _ArgParser_instances, _identifyCommandChainAndParsers_fn).call(this, processArgs, this, [], [this]);
-  if (processArgs.includes("--LIB-debug")) {
+  if (processArgs.includes("--s-enable-fuzzy")) {
+    __privateMethod(this, _ArgParserBase_instances, _enableFuzzyMode_fn).call(this);
+    const fuzzyIndex = processArgs.indexOf("--s-enable-fuzzy");
+    processArgs.splice(fuzzyIndex, 1);
+  }
+  const withEnvIndex = processArgs.findIndex((arg) => arg === "--s-with-env");
+  if (withEnvIndex !== -1) {
+    if (withEnvIndex + 1 >= processArgs.length) {
+      console.error(chalk.red("Error: --s-with-env requires a file path argument"));
+      if (typeof process === "object" && typeof process.exit === "function") {
+        process.exit(1);
+      }
+      return true;
+    }
+    const filePath = processArgs[withEnvIndex + 1];
+    if (!filePath || filePath.startsWith("-")) {
+      console.error(chalk.red("Error: --s-with-env requires a file path argument"));
+      if (typeof process === "object" && typeof process.exit === "function") {
+        process.exit(1);
+      }
+      return true;
+    }
+    try {
+      const { finalParser: identifiedFinalParser2, parserChain: identifiedParserChain } = __privateMethod(this, _ArgParserBase_instances, _identifyCommandChainAndParsers_fn).call(this, processArgs, this, [], [this]);
+      const envConfigArgs = __privateMethod(_a = identifiedFinalParser2, _ArgParserBase_instances, _loadEnvFile_fn).call(_a, filePath, identifiedParserChain);
+      if (envConfigArgs) {
+        const mergedArgs = __privateMethod(_b = identifiedFinalParser2, _ArgParserBase_instances, _mergeEnvConfigWithArgs_fn).call(_b, envConfigArgs, processArgs);
+        processArgs.length = 0;
+        processArgs.push(...mergedArgs);
+      }
+    } catch (error) {
+      console.error(chalk.red(`Error loading environment file: ${error instanceof Error ? error.message : String(error)}`));
+      if (typeof process === "object" && typeof process.exit === "function") {
+        process.exit(1);
+      }
+      return true;
+    }
+  }
+  const { finalParser: identifiedFinalParser } = __privateMethod(this, _ArgParserBase_instances, _identifyCommandChainAndParsers_fn).call(this, processArgs, this, [], [this]);
+  if (processArgs.includes("--s-debug")) {
     console.log(
-      chalk.yellow.bold("\n--- ArgParser --LIB-debug Runtime Context ---")
+      chalk.yellow.bold("\n--- ArgParser --s-debug Runtime Context ---")
     );
     const {
       commandChain: identifiedCommandChain,
       parserChain: _identifiedParserChain
-    } = __privateMethod(this, _ArgParser_instances, _identifyCommandChainAndParsers_fn).call(this, processArgs, this, [], [this]);
+    } = __privateMethod(this, _ArgParserBase_instances, _identifyCommandChainAndParsers_fn).call(this, processArgs, this, [], [this]);
     console.log(
       `Identified Command Chain: ${chalk.cyan(identifiedCommandChain.join(" -> ") || "(root)")}`
     );
@@ -709,7 +795,7 @@ _handleGlobalChecks_fn = function(processArgs, options) {
     const rootArgsSlice = rootSubCommandIndex === -1 ? remainingArgs : remainingArgs.slice(0, rootSubCommandIndex);
     parsingSteps.push({ level: "(root)", argsSlice: rootArgsSlice });
     try {
-      const { parsedArgs: rootParsedArgs } = __privateMethod(_a = currentParser, _ArgParser_instances, parseFlags_fn).call(_a, rootArgsSlice, { skipHelpHandling: true });
+      const { parsedArgs: rootParsedArgs } = __privateMethod(_c = currentParser, _ArgParserBase_instances, parseFlags_fn).call(_c, rootArgsSlice, { skipHelpHandling: true });
       parsingSteps[0].parsed = rootParsedArgs;
       accumulatedArgs = { ...accumulatedArgs, ...rootParsedArgs };
     } catch (e) {
@@ -726,7 +812,7 @@ _handleGlobalChecks_fn = function(processArgs, options) {
         });
         break;
       }
-      currentParser = (_b = __privateGet(currentParser, _subCommands).get(subCommandName)) == null ? void 0 : _b.parser;
+      currentParser = (_d = __privateGet(currentParser, _subCommands).get(subCommandName)) == null ? void 0 : _d.parser;
       remainingArgs = remainingArgs.slice(1);
       const nextSubCommandIndex = remainingArgs.findIndex(
         (arg) => __privateGet(currentParser, _subCommands).has(arg)
@@ -738,7 +824,7 @@ _handleGlobalChecks_fn = function(processArgs, options) {
       };
       parsingSteps.push(stepInfo);
       try {
-        const { parsedArgs: currentLevelParsedArgs } = __privateMethod(_c = currentParser, _ArgParser_instances, parseFlags_fn).call(_c, currentLevelArgsSlice, {
+        const { parsedArgs: currentLevelParsedArgs } = __privateMethod(_e = currentParser, _ArgParserBase_instances, parseFlags_fn).call(_e, currentLevelArgsSlice, {
           skipHelpHandling: true
         });
         stepInfo.parsed = currentLevelParsedArgs;
@@ -779,21 +865,21 @@ _handleGlobalChecks_fn = function(processArgs, options) {
       )
     );
     identifiedFinalParser.printAll();
-    console.log(chalk.yellow.bold("--- End ArgParser --LIB-debug ---"));
+    console.log(chalk.yellow.bold("--- End ArgParser --s-debug ---"));
     if (typeof process === "object" && typeof process.exit === "function") {
       process.exit(0);
     }
     return true;
   }
   let parserNameForLog = "undefined_parser";
-  if (identifiedFinalParser instanceof _ArgParser) {
+  if (identifiedFinalParser instanceof _ArgParserBase) {
     parserNameForLog = identifiedFinalParser["#subCommandName"] || identifiedFinalParser["#appName"];
   } else if (identifiedFinalParser) {
     parserNameForLog = identifiedFinalParser.name || identifiedFinalParser.appName || "unknown_type";
   }
-  if (!(identifiedFinalParser instanceof _ArgParser)) {
+  if (!(identifiedFinalParser instanceof _ArgParserBase)) {
     console.error(
-      `[ArgParser #_handleGlobalChecks Critical Error] identifiedFinalParser is not an instance of ArgParser. Cannot process help. Name: ${parserNameForLog}, Constructor: ${identifiedFinalParser ? (_d = identifiedFinalParser.constructor) == null ? void 0 : _d.name : "undefined"}`
+      `[ArgParser #_handleGlobalChecks Critical Error] identifiedFinalParser is not an instance of ArgParser. Cannot process help. Name: ${parserNameForLog}, Constructor: ${identifiedFinalParser ? (_f = identifiedFinalParser.constructor) == null ? void 0 : _f.name : "undefined"}`
     );
     return false;
   }
@@ -816,11 +902,27 @@ _handleGlobalChecks_fn = function(processArgs, options) {
 _validateMandatoryFlags_fn = function(finalArgs, parserChain, commandChain) {
   const finalMandatoryFlagsMissing = [];
   const checkedFlagNames = /* @__PURE__ */ new Set();
-  for (const parser of parserChain) {
+  let parsersToValidate = [...parserChain];
+  if (parserChain.length > 1) {
+    const immediateChild = parserChain[1];
+    if (!__privateGet(immediateChild, _inheritParentFlags)) {
+      parsersToValidate = parsersToValidate.slice(1);
+    }
+  }
+  for (let i = 0; i < parsersToValidate.length; i++) {
+    const parser = parsersToValidate[i];
     const currentCommandChain = parser.getCommandChain();
     for (const flag of __privateGet(parser, _flagManager).flags) {
       if (flag["name"] === "help" || checkedFlagNames.has(flag["name"]))
         continue;
+      let flagIsInheritedByChild = false;
+      if (i < parsersToValidate.length - 1) {
+        const immediateChild = parsersToValidate[i + 1];
+        if (__privateGet(immediateChild, _inheritParentFlags) && __privateGet(immediateChild, _flagManager).hasFlag(flag["name"])) {
+          flagIsInheritedByChild = true;
+        }
+      }
+      if (flagIsInheritedByChild) continue;
       const isMandatory = typeof flag["mandatory"] === "function" ? flag["mandatory"](finalArgs) : flag["mandatory"];
       if (!isMandatory) continue;
       const value = finalArgs[flag["name"]];
@@ -869,6 +971,16 @@ _prepareAndExecuteHandler_fn = function(handlerToExecute, finalArgs, skipHandler
   if (skipHandlers || !handlerToExecute) {
     return;
   }
+  if (__privateGet(this, _fuzzyMode)) {
+    const commandChain = handlerToExecute.context.commandChain || [];
+    const args = handlerToExecute.context.args || {};
+    const inputArgs = finalArgs._originalInputArgs || "unknown";
+    const inputArgsStr = Array.isArray(inputArgs) ? inputArgs.join(" ") : inputArgs;
+    console.log(`[--s-enable-fuzzy] handler() skipped for command chain: ${commandChain.join(" ") || "(root)"}`);
+    console.log(`  Input args: [${inputArgsStr}]`);
+    console.log(`  Parsed args: ${JSON.stringify(args)}`);
+    return;
+  }
   const finalParserWhoseHandlerWillRun = handlerToExecute.context.parser;
   const finalParserFlags = __privateGet(finalParserWhoseHandlerWillRun, _flagManager).flags;
   const handlerArgs = handlerToExecute.context.args;
@@ -881,7 +993,23 @@ _prepareAndExecuteHandler_fn = function(handlerToExecute, finalArgs, skipHandler
     }
   }
   handlerToExecute.context.args = handlerArgs;
-  handlerToExecute.handler(handlerToExecute.context);
+  try {
+    const handlerResult = handlerToExecute.handler(handlerToExecute.context);
+    if (handlerResult && typeof handlerResult.then === "function") {
+      finalArgs._asyncHandlerPromise = handlerResult;
+      finalArgs._asyncHandlerInfo = handlerToExecute;
+      handlerResult.catch(() => {
+      });
+      return;
+    }
+    finalArgs.handlerResponse = handlerResult;
+  } catch (error) {
+    if (__privateGet(this, _handleErrors)) {
+      __privateMethod(this, _ArgParserBase_instances, displayErrorAndExit_fn).call(this, new ArgParserError(`Handler error: ${error}`, []));
+    } else {
+      throw error;
+    }
+  }
 };
 parseFlags_fn = function(args, options) {
   var _a, _b;
@@ -949,6 +1077,19 @@ parseFlags_fn = function(args, options) {
   }
   return { parsedArgs: output, firstUnconsumedIndex };
 };
+/**
+ * Enables fuzzy testing mode by disabling error handling and making flags optional
+ */
+_enableFuzzyMode_fn = function() {
+  var _a;
+  __privateSet(this, _fuzzyMode, true);
+  __privateSet(this, _handleErrors, false);
+  for (const [, subCommand] of __privateGet(this, _subCommands)) {
+    if (subCommand.parser instanceof _ArgParserBase) {
+      __privateMethod(_a = subCommand.parser, _ArgParserBase_instances, _enableFuzzyMode_fn).call(_a);
+    }
+  }
+};
 displayErrorAndExit_fn = function(error) {
   let commandNameToSuggest = "your-script";
   if (__privateGet(this, _appCommandName)) {
@@ -961,15 +1102,11 @@ displayErrorAndExit_fn = function(error) {
     } catch {
     }
   }
-  const commandPath = [
-    commandNameToSuggest,
-    ...error.commandChain || []
-  ].join(" ");
   console.error(`
 ${chalk.red.bold("Error:")} ${error.message}`);
   console.error(
     `
-${chalk.dim(`Try '${commandPath} --help' for usage details.`)}`
+${chalk.dim(`Try '${commandNameToSuggest} --help' for usage details.`)}`
   );
   if (typeof process === "object" && typeof process.exit === "function") {
     process.exit(1);
@@ -1036,7 +1173,7 @@ _printRecursiveToConsole_fn = function(parser, level, visited = /* @__PURE__ */
   if (subCommandParsers.length > 0) {
     console.log(`${subIndent}Sub-Commands (${subCommandParsers.length}):`);
     subCommandParsers.forEach((subCommand) => {
-      __privateMethod(this, _ArgParser_instances, _printRecursiveToConsole_fn).call(this, subCommand.parser, level + 1, visited);
+      __privateMethod(this, _ArgParserBase_instances, _printRecursiveToConsole_fn).call(this, subCommand.parser, level + 1, visited);
     });
   } else {
     console.log(`${subIndent}Sub-Commands: ${chalk.dim("none")}`);
@@ -1117,7 +1254,7 @@ _buildRecursiveString_fn = function(parser, level, visited = /* @__PURE__ */ new
   if (subCommandParsers.length > 0) {
     addLine(`${subIndent}Sub-Commands (${subCommandParsers.length}):`);
     subCommandParsers.forEach((subCommand) => {
-      output += __privateMethod(this, _ArgParser_instances, _buildRecursiveString_fn).call(this, subCommand.parser, level + 1, visited);
+      output += __privateMethod(this, _ArgParserBase_instances, _buildRecursiveString_fn).call(this, subCommand.parser, level + 1, visited);
     });
   } else {
     addLine(`${subIndent}Sub-Commands: none`);
@@ -1179,14 +1316,1478 @@ _buildRecursiveJson_fn = function(parser, visited = /* @__PURE__ */ new Set()) {
   const subCommands = Array.from(__privateGet(parser, _subCommands).values());
   if (subCommands.length > 0) {
     subCommands.forEach((sub) => {
-      config.subCommands[sub.name] = __privateMethod(this, _ArgParser_instances, _buildRecursiveJson_fn).call(this, sub.parser, visited);
+      config.subCommands[sub.name] = __privateMethod(this, _ArgParserBase_instances, _buildRecursiveJson_fn).call(this, sub.parser, visited);
     });
   }
   return config;
 };
+/**
+ * Generates a default environment file name based on the app name
+ */
+_generateDefaultEnvFileName_fn = function() {
+  let baseName = "config";
+  if (__privateGet(this, _appCommandName)) {
+    baseName = __privateGet(this, _appCommandName);
+  } else if (__privateGet(this, _appName) && __privateGet(this, _appName) !== "Argument Parser") {
+    baseName = __privateGet(this, _appName);
+  }
+  baseName = baseName.split(/[\s-_]+/).map((word) => word.charAt(0).toUpperCase() + word.slice(1).toLowerCase()).join("");
+  return `${baseName}.env`;
+};
+/**
+ * Handles the --s-save-to-env system flag at the final parser level
+ */
+_handleSaveToEnvFlag_fn = function(processArgs, parserChain) {
+  const saveToEnvIndex = processArgs.findIndex((arg) => arg === "--s-save-to-env");
+  if (saveToEnvIndex !== -1) {
+    let filePath;
+    if (saveToEnvIndex + 1 < processArgs.length) {
+      const nextArg = processArgs[saveToEnvIndex + 1];
+      if (nextArg && !nextArg.startsWith("-")) {
+        filePath = nextArg;
+      } else {
+        filePath = __privateMethod(this, _ArgParserBase_instances, _generateDefaultEnvFileName_fn).call(this);
+      }
+    } else {
+      filePath = __privateMethod(this, _ArgParserBase_instances, _generateDefaultEnvFileName_fn).call(this);
+    }
+    try {
+      __privateMethod(this, _ArgParserBase_instances, _saveToEnvFile_fn).call(this, filePath, processArgs, parserChain);
+      console.log(chalk.green(`Environment configuration saved to: ${filePath}`));
+      if (typeof process === "object" && typeof process.exit === "function") {
+        process.exit(0);
+      }
+      return true;
+    } catch (error) {
+      console.error(chalk.red(`Error saving environment file: ${error instanceof Error ? error.message : String(error)}`));
+      if (typeof process === "object" && typeof process.exit === "function") {
+        process.exit(1);
+      }
+      return true;
+    }
+  }
+  return false;
+};
+/**
+ * Saves the current parser's flags and their values to an environment file
+ * in the specified format based on file extension.
+ */
+_saveToEnvFile_fn = function(filePath, processArgs, parserChain) {
+  const ext = path.extname(filePath).toLowerCase();
+  let format;
+  if (ext === ".yaml" || ext === ".yml") {
+    format = "yaml";
+  } else if (ext === ".json" || ext === ".jsonc") {
+    format = "json";
+  } else if (ext === ".toml" || ext === ".tml") {
+    format = "toml";
+  } else {
+    format = "env";
+  }
+  const allFlags = [];
+  const seenFlagNames = /* @__PURE__ */ new Set();
+  for (let i = parserChain.length - 1; i >= 0; i--) {
+    const parser = parserChain[i];
+    for (const flag of __privateGet(parser, _flagManager).flags) {
+      if (!seenFlagNames.has(flag["name"])) {
+        allFlags.push(flag);
+        seenFlagNames.add(flag["name"]);
+      }
+    }
+  }
+  const flags = allFlags;
+  const { parsedArgs } = __privateMethod(this, _ArgParserBase_instances, parseFlags_fn).call(this, processArgs.filter(
+    (arg) => arg !== "--s-save-to-env" && arg !== filePath
+  ));
+  let content;
+  switch (format) {
+    case "env":
+      content = __privateMethod(this, _ArgParserBase_instances, _generateEnvFormat_fn).call(this, flags, parsedArgs);
+      break;
+    case "yaml":
+      content = __privateMethod(this, _ArgParserBase_instances, _generateYamlFormat_fn).call(this, flags, parsedArgs);
+      break;
+    case "json":
+      content = __privateMethod(this, _ArgParserBase_instances, _generateJsonFormat_fn).call(this, flags, parsedArgs);
+      break;
+    case "toml":
+      content = __privateMethod(this, _ArgParserBase_instances, _generateTomlFormat_fn).call(this, flags, parsedArgs);
+      break;
+  }
+  const dir = path.dirname(filePath);
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+  fs.writeFileSync(filePath, content, "utf8");
+};
+/**
+ * Loads configuration from an environment file in various formats
+ */
+_loadEnvFile_fn = function(filePath, parserChain) {
+  if (!fs.existsSync(filePath)) {
+    throw new Error(`Configuration file not found: ${filePath}`);
+  }
+  const ext = path.extname(filePath).toLowerCase();
+  let format;
+  if (ext === ".yaml" || ext === ".yml") {
+    format = "yaml";
+  } else if (ext === ".json" || ext === ".jsonc") {
+    format = "json";
+  } else if (ext === ".toml" || ext === ".tml") {
+    format = "toml";
+  } else {
+    format = "env";
+  }
+  const fileContent = fs.readFileSync(filePath, "utf8");
+  let rawConfig;
+  switch (format) {
+    case "env":
+      rawConfig = __privateMethod(this, _ArgParserBase_instances, _parseEnvFile_fn).call(this, fileContent);
+      break;
+    case "yaml":
+      rawConfig = __privateMethod(this, _ArgParserBase_instances, _parseYamlFile_fn).call(this, fileContent);
+      break;
+    case "json":
+      rawConfig = __privateMethod(this, _ArgParserBase_instances, _parseJsonFile_fn).call(this, fileContent);
+      break;
+    case "toml":
+      rawConfig = __privateMethod(this, _ArgParserBase_instances, _parseTomlFile_fn).call(this, fileContent);
+      break;
+  }
+  return __privateMethod(this, _ArgParserBase_instances, _convertConfigToFlagValues_fn).call(this, rawConfig, parserChain);
+};
+/**
+ * Parses .env file content using dotenv
+ */
+_parseEnvFile_fn = function(content) {
+  const parsed = dotenv.parse(content);
+  const result = {};
+  for (const [envKey, envValue] of Object.entries(parsed)) {
+    const flagName = envKey.toLowerCase().replace(/_/g, "-");
+    if (envValue === "true") {
+      result[flagName] = true;
+    } else if (envValue === "false") {
+      result[flagName] = false;
+    } else if (/^-?\d+$/.test(envValue)) {
+      result[flagName] = parseInt(envValue, 10);
+    } else if (/^-?\d*\.\d+$/.test(envValue)) {
+      result[flagName] = parseFloat(envValue);
+    } else if (envValue.includes(",")) {
+      result[flagName] = envValue.split(",").map((v) => v.trim());
+    } else {
+      result[flagName] = envValue;
+    }
+  }
+  return result;
+};
+/**
+ * Parses YAML file content
+ */
+_parseYamlFile_fn = function(content) {
+  const parsed = yaml.load(content);
+  if (typeof parsed !== "object" || parsed === null) {
+    throw new Error("YAML file must contain an object at the root level");
+  }
+  const { _meta, ...config } = parsed;
+  return config;
+};
+/**
+ * Parses JSON file content
+ */
+_parseJsonFile_fn = function(content) {
+  const parsed = JSON.parse(content);
+  if (typeof parsed !== "object" || parsed === null) {
+    throw new Error("JSON file must contain an object at the root level");
+  }
+  const { _meta, ...config } = parsed;
+  return config;
+};
+/**
+ * Parses TOML file content
+ */
+_parseTomlFile_fn = function(content) {
+  const parsed = toml.parse(content);
+  if (typeof parsed !== "object" || parsed === null) {
+    throw new Error("TOML file must contain an object at the root level");
+  }
+  return parsed;
+};
+/**
+ * Converts raw configuration values to match flag types and validates them
+ */
+_convertConfigToFlagValues_fn = function(rawConfig, parserChain) {
+  const result = {};
+  const allFlags = [];
+  const seenFlagNames = /* @__PURE__ */ new Set();
+  for (let i = parserChain.length - 1; i >= 0; i--) {
+    const parser = parserChain[i];
+    for (const flag of __privateGet(parser, _flagManager).flags) {
+      if (!seenFlagNames.has(flag["name"])) {
+        allFlags.push(flag);
+        seenFlagNames.add(flag["name"]);
+      }
+    }
+  }
+  for (const [configKey, configValue] of Object.entries(rawConfig)) {
+    const flag = allFlags.find((f) => f["name"] === configKey);
+    if (!flag) {
+      console.warn(chalk.yellow(`Warning: Configuration key '${configKey}' does not match any known flag. Ignoring.`));
+      continue;
+    }
+    try {
+      const convertedValue = __privateMethod(this, _ArgParserBase_instances, _convertValueToFlagType_fn).call(this, configValue, flag);
+      result[configKey] = convertedValue;
+    } catch (error) {
+      console.error(chalk.red(`Error converting configuration value for '${configKey}': ${error instanceof Error ? error.message : String(error)}`));
+      if (typeof process === "object" && typeof process.exit === "function") {
+        process.exit(1);
+      }
+    }
+  }
+  return result;
+};
+/**
+ * Converts a configuration value to match the expected flag type
+ */
+_convertValueToFlagType_fn = function(value, flag) {
+  const flagType = flag["type"];
+  if (value === null || value === void 0) {
+    return value;
+  }
+  if (flagType === Array || flag["allowMultiple"]) {
+    if (Array.isArray(value)) return value;
+    if (typeof value === "string") {
+      return value.split(",").map((v) => v.trim());
+    }
+    return [value];
+  }
+  if (flagType === Boolean) {
+    if (typeof value === "boolean") return value;
+    if (typeof value === "string") {
+      const lowerValue = value.toLowerCase();
+      if (lowerValue === "true" || lowerValue === "1" || lowerValue === "yes") return true;
+      if (lowerValue === "false" || lowerValue === "0" || lowerValue === "no") return false;
+    }
+    throw new Error(`Cannot convert '${value}' to boolean for flag '${flag["name"]}'`);
+  }
+  if (flagType === String) {
+    return String(value);
+  }
+  if (flagType === Number) {
+    const numValue = Number(value);
+    if (isNaN(numValue)) {
+      throw new Error(`Cannot convert '${value}' to number for flag '${flag["name"]}'`);
+    }
+    return numValue;
+  }
+  if (flag["enum"] && flag["enum"].length > 0) {
+    if (!flag["enum"].includes(value)) {
+      throw new Error(`Value '${value}' is not allowed for flag '${flag["name"]}'. Allowed values: ${flag["enum"].join(", ")}`);
+    }
+  }
+  return value;
+};
+/**
+ * Merges environment configuration with command line arguments
+ * CLI arguments take precedence over file configuration
+ */
+_mergeEnvConfigWithArgs_fn = function(envConfig, processArgs) {
+  const result = [...processArgs];
+  const withEnvIndex = result.findIndex((arg) => arg === "--s-with-env");
+  if (withEnvIndex !== -1) {
+    result.splice(withEnvIndex, 2);
+  }
+  const existingFlags = /* @__PURE__ */ new Set();
+  for (let i = 0; i < result.length; i++) {
+    const arg = result[i];
+    if (arg.startsWith("-")) {
+      existingFlags.add(arg);
+      if (arg.includes("=")) {
+        const flagPart = arg.split("=")[0];
+        existingFlags.add(flagPart);
+      }
+    }
+  }
+  for (const [flagName, flagValue] of Object.entries(envConfig)) {
+    const longFlag = `--${flagName}`;
+    if (existingFlags.has(longFlag)) {
+      continue;
+    }
+    if (typeof flagValue === "boolean") {
+      if (flagValue) {
+        result.push(longFlag);
+      }
+    } else if (Array.isArray(flagValue)) {
+      for (const item of flagValue) {
+        result.push(longFlag, String(item));
+      }
+    } else {
+      result.push(longFlag, String(flagValue));
+    }
+  }
+  return result;
+};
+/**
+ * Generates environment file content in Bash .env format
+ */
+_generateEnvFormat_fn = function(flags, parsedArgs) {
+  const lines = [];
+  lines.push("# Environment configuration generated by ArgParser");
+  lines.push("# Format: Bash .env style");
+  lines.push("");
+  for (const flag of flags) {
+    if (flag["name"] === "help") continue;
+    const flagValue = parsedArgs[flag["name"]];
+    const isSet = flagValue !== void 0 && flagValue !== null;
+    const isMandatory = typeof flag["mandatory"] === "function" ? false : flag["mandatory"] ?? false;
+    lines.push(`# ${flag["name"]}: ${Array.isArray(flag["description"]) ? flag["description"].join(" | ") : flag["description"]}`);
+    lines.push(`# Options: ${flag["options"].join(", ")}`);
+    lines.push(`# Type: ${__privateMethod(this, _ArgParserBase_instances, _getTypeString_fn).call(this, flag["type"])}`);
+    if (flag["defaultValue"] !== void 0) {
+      lines.push(`# Default: ${JSON.stringify(flag["defaultValue"])}`);
+    }
+    if (flag["enum"] && flag["enum"].length > 0) {
+      lines.push(`# Allowed values: ${flag["enum"].join(", ")}`);
+    }
+    const envVarName = flag["name"].toUpperCase().replace(/[^A-Z0-9_]/g, "_");
+    let envValue = "";
+    if (isSet) {
+      if (Array.isArray(flagValue)) {
+        envValue = flagValue.join(",");
+      } else if (typeof flagValue === "boolean") {
+        envValue = flagValue ? "true" : "false";
+      } else {
+        envValue = String(flagValue);
+      }
+      lines.push(`${envVarName}="${envValue}"`);
+    } else {
+      const defaultVal = flag["defaultValue"] !== void 0 ? String(flag["defaultValue"]) : "";
+      const prefix = isMandatory ? "" : "# ";
+      lines.push(`${prefix}${envVarName}="${defaultVal}"`);
+    }
+    lines.push("");
+  }
+  return lines.join("\n");
+};
+/**
+ * Generates environment file content in YAML format
+ */
+_generateYamlFormat_fn = function(flags, parsedArgs) {
+  const config = {};
+  const comments = [];
+  comments.push("# Environment configuration generated by ArgParser");
+  comments.push("# Format: YAML");
+  comments.push("");
+  for (const flag of flags) {
+    if (flag["name"] === "help") continue;
+    const flagValue = parsedArgs[flag["name"]];
+    const isSet = flagValue !== void 0 && flagValue !== null;
+    const isMandatory = typeof flag["mandatory"] === "function" ? false : flag["mandatory"] ?? false;
+    comments.push(`# ${flag["name"]}: ${Array.isArray(flag["description"]) ? flag["description"].join(" | ") : flag["description"]}`);
+    comments.push(`# Options: ${flag["options"].join(", ")}`);
+    comments.push(`# Type: ${__privateMethod(this, _ArgParserBase_instances, _getTypeString_fn).call(this, flag["type"])}`);
+    if (flag["defaultValue"] !== void 0) {
+      comments.push(`# Default: ${JSON.stringify(flag["defaultValue"])}`);
+    }
+    if (flag["enum"] && flag["enum"].length > 0) {
+      comments.push(`# Allowed values: ${flag["enum"].join(", ")}`);
+    }
+    if (isSet) {
+      config[flag["name"]] = flagValue;
+    } else if (isMandatory) {
+      config[flag["name"]] = flag["defaultValue"] !== void 0 ? flag["defaultValue"] : null;
+    }
+    comments.push("");
+  }
+  const yamlContent = yaml.dump(config, {
+    indent: 2,
+    lineWidth: -1,
+    noRefs: true,
+    sortKeys: true
+  });
+  return comments.join("\n") + "\n" + yamlContent;
+};
+/**
+ * Generates environment file content in JSON format
+ */
+_generateJsonFormat_fn = function(flags, parsedArgs) {
+  const config = {};
+  const metadata = {
+    _meta: {
+      generated_by: "ArgParser",
+      format: "JSON",
+      flags_info: {}
+    }
+  };
+  for (const flag of flags) {
+    if (flag["name"] === "help") continue;
+    const flagValue = parsedArgs[flag["name"]];
+    const isSet = flagValue !== void 0 && flagValue !== null;
+    const isMandatory = typeof flag["mandatory"] === "function" ? false : flag["mandatory"] ?? false;
+    metadata._meta.flags_info[flag["name"]] = {
+      description: Array.isArray(flag["description"]) ? flag["description"].join(" | ") : flag["description"],
+      options: flag["options"],
+      type: __privateMethod(this, _ArgParserBase_instances, _getTypeString_fn).call(this, flag["type"]),
+      mandatory: isMandatory,
+      defaultValue: flag["defaultValue"],
+      enum: flag["enum"] && flag["enum"].length > 0 ? flag["enum"] : void 0
+    };
+    if (isSet) {
+      config[flag["name"]] = flagValue;
+    } else if (isMandatory) {
+      config[flag["name"]] = flag["defaultValue"] !== void 0 ? flag["defaultValue"] : null;
+    }
+  }
+  const result = { ...metadata, ...config };
+  return JSON.stringify(result, null, 2);
+};
+/**
+ * Generates environment file content in TOML format
+ */
+_generateTomlFormat_fn = function(flags, parsedArgs) {
+  const config = {};
+  const lines = [];
+  lines.push("# Environment configuration generated by ArgParser");
+  lines.push("# Format: TOML");
+  lines.push("");
+  for (const flag of flags) {
+    if (flag["name"] === "help") continue;
+    const flagValue = parsedArgs[flag["name"]];
+    const isSet = flagValue !== void 0 && flagValue !== null;
+    const isMandatory = typeof flag["mandatory"] === "function" ? false : flag["mandatory"] ?? false;
+    lines.push(`# ${flag["name"]}: ${Array.isArray(flag["description"]) ? flag["description"].join(" | ") : flag["description"]}`);
+    lines.push(`# Options: ${flag["options"].join(", ")}`);
+    lines.push(`# Type: ${__privateMethod(this, _ArgParserBase_instances, _getTypeString_fn).call(this, flag["type"])}`);
+    if (flag["defaultValue"] !== void 0) {
+      lines.push(`# Default: ${JSON.stringify(flag["defaultValue"])}`);
+    }
+    if (flag["enum"] && flag["enum"].length > 0) {
+      lines.push(`# Allowed values: ${flag["enum"].join(", ")}`);
+    }
+    if (isSet) {
+      config[flag["name"]] = flagValue;
+    } else if (isMandatory) {
+      config[flag["name"]] = flag["defaultValue"] !== void 0 ? flag["defaultValue"] : null;
+    }
+    lines.push("");
+  }
+  const tomlContent = toml.stringify(config);
+  return lines.join("\n") + "\n" + tomlContent;
+};
+/**
+ * Helper method to get a string representation of a flag's type
+ */
+_getTypeString_fn = function(type) {
+  var _a;
+  if (typeof type === "function") {
+    return type.name || "custom function";
+  } else if (typeof type === "string") {
+    return type;
+  } else if (typeof type === "object" && type) {
+    try {
+      return ((_a = type.constructor) == null ? void 0 : _a.name) || "object";
+    } catch {
+      return "object";
+    }
+  }
+  return "unknown";
+};
+let ArgParserBase = _ArgParserBase;
+function mapArgParserFlagToZodSchema(flag) {
+  let zodSchema;
+  const flagTypeOpt = flag["type"];
+  let typeName;
+  if (typeof flagTypeOpt === "function") {
+    typeName = flagTypeOpt.name.toLowerCase().replace("constructor", "");
+  } else {
+    typeName = String(flagTypeOpt).toLowerCase();
+  }
+  const flagEnum = flag["enum"];
+  const allowMultiple = flag["allowMultiple"];
+  if (allowMultiple) {
+    let itemSchema;
+    if (flagEnum && Array.isArray(flagEnum) && flagEnum.length > 0) {
+      if (flagEnum.every((e) => typeof e === "string")) {
+        itemSchema = z.enum(flagEnum);
+      } else if (flagEnum.every((e) => typeof e === "number")) {
+        const literalSchemas = flagEnum.map((val) => z.literal(val));
+        if (literalSchemas.length === 1) {
+          itemSchema = literalSchemas[0];
+        } else {
+          itemSchema = z.union(
+            literalSchemas
+          );
+        }
+      } else {
+        itemSchema = z.string();
+      }
+    } else {
+      switch (typeName) {
+        case "number":
+          itemSchema = z.number();
+          break;
+        case "boolean":
+          itemSchema = z.boolean();
+          break;
+        default:
+          itemSchema = z.string();
+          break;
+      }
+    }
+    zodSchema = z.array(itemSchema);
+  } else {
+    switch (typeName) {
+      case "string":
+        zodSchema = flagEnum && Array.isArray(flagEnum) && flagEnum.length > 0 && flagEnum.every((e) => typeof e === "string") ? z.enum(flagEnum) : z.string();
+        break;
+      case "number":
+        if (flagEnum && Array.isArray(flagEnum) && flagEnum.length > 0 && flagEnum.every((e) => typeof e === "number")) {
+          const literalSchemas = flagEnum.map((val) => z.literal(val));
+          if (literalSchemas.length === 1) {
+            zodSchema = literalSchemas[0];
+          } else if (literalSchemas.length >= 2) {
+            zodSchema = z.union(
+              literalSchemas
+            );
+          } else {
+            zodSchema = z.number();
+          }
+        } else {
+          zodSchema = z.number();
+        }
+        break;
+      case "boolean":
+        zodSchema = z.boolean();
+        break;
+      case "array":
+        const itemSchema = flagEnum && Array.isArray(flagEnum) && flagEnum.length > 0 && flagEnum.every((e) => typeof e === "string") ? z.enum(flagEnum) : z.string();
+        zodSchema = z.array(itemSchema);
+        break;
+      case "object":
+        zodSchema = z.record(z.string(), z.any());
+        break;
+      default:
+        console.warn(
+          `[MCP Integration] Flag '${flag["name"]}' has an unknown type '${typeName}'. Defaulting to z.string().`
+        );
+        zodSchema = z.string();
+        break;
+    }
+  }
+  const description = flag["description"];
+  if (description) {
+    zodSchema = zodSchema.describe(
+      Array.isArray(description) ? description.join("\n") : description
+    );
+  }
+  const defaultValue = flag["defaultValue"];
+  if (defaultValue !== void 0) {
+    zodSchema = zodSchema.default(defaultValue);
+  } else if (!flag["mandatory"]) {
+    zodSchema = zodSchema.optional();
+  }
+  return zodSchema;
+}
+function generateMcpToolsFromArgParser(rootParser, options) {
+  const tools = [];
+  const visitedParsers = /* @__PURE__ */ new Set();
+  function buildToolsRecursively(currentParser, commandPathParts) {
+    if (visitedParsers.has(currentParser)) return;
+    visitedParsers.add(currentParser);
+    const typedRootParser = rootParser;
+    const typedCurrentParser = currentParser;
+    const appName = typedRootParser.getAppName ? typedRootParser.getAppName() : typedRootParser["#appName"];
+    const currentParserDescription = typedCurrentParser.getDescription ? typedCurrentParser.getDescription() : typedCurrentParser["#description"];
+    const currentParserHandler = typedCurrentParser.getHandler ? typedCurrentParser.getHandler() : typedCurrentParser["#handler"];
+    const currentParserFlags = typedCurrentParser.flags;
+    const subCommandsMap = typedCurrentParser.getSubCommands ? typedCurrentParser.getSubCommands() : typedCurrentParser["#subCommands"];
+    const currentParserSubCommands = subCommandsMap ? Array.from(subCommandsMap.values()) : [];
+    let currentParserCommandName = typedCurrentParser.getAppCommandName ? typedCurrentParser.getAppCommandName() : typedCurrentParser["#appCommandName"];
+    if (!currentParserCommandName && currentParser !== rootParser) {
+      currentParserCommandName = typedCurrentParser.getSubCommandName ? typedCurrentParser.getSubCommandName() : typedCurrentParser["#subCommandName"];
+    }
+    if (currentParser !== rootParser && commandPathParts.length > 0) {
+      currentParserCommandName = commandPathParts[commandPathParts.length - 1];
+    }
+    const currentParserCommandNameOrAppName = currentParserCommandName || appName;
+    const effectiveCommandName = currentParserCommandName || (commandPathParts.length > 0 ? commandPathParts[commandPathParts.length - 1] : appName);
+    let toolName;
+    if (options == null ? void 0 : options.generateToolName) {
+      toolName = options.generateToolName(commandPathParts, appName);
+    } else {
+      if (currentParser === rootParser) {
+        toolName = currentParserCommandNameOrAppName || appName || "root_cmd";
+      } else {
+        toolName = effectiveCommandName || "cmd";
+      }
+      toolName = toolName.replace(/[^a-zA-Z0-9_-]/g, "_");
+    }
+    if (!toolName)
+      toolName = currentParser === rootParser && appName ? appName : "cmd";
+    if (options == null ? void 0 : options.toolNamePrefix) {
+      toolName = options.toolNamePrefix + toolName;
+    }
+    if (options == null ? void 0 : options.toolNameSuffix) {
+      toolName = toolName + options.toolNameSuffix;
+    }
+    if (currentParserHandler) {
+      const flags = currentParserFlags;
+      const zodProperties = {};
+      const hasHelpFlag = flags.some((flag) => flag["name"] === "help");
+      for (const flag of flags) {
+        let flagSchema = mapArgParserFlagToZodSchema(flag);
+        if (hasHelpFlag && flag["name"] !== "help" && flag["mandatory"]) {
+          flagSchema = flagSchema.optional();
+        }
+        zodProperties[flag["name"]] = flagSchema;
+      }
+      const inputSchema = z.object(zodProperties);
+      let outputSchema;
+      if ((options == null ? void 0 : options.outputSchemaMap) && options.outputSchemaMap[toolName]) {
+        const customSchema = options.outputSchemaMap[toolName];
+        outputSchema = typeof customSchema === "object" && !customSchema._def ? z.object(customSchema) : customSchema;
+      } else if (options == null ? void 0 : options.defaultOutputSchema) {
+        outputSchema = options.defaultOutputSchema;
+      }
+      const tool = {
+        name: toolName,
+        description: currentParserDescription || `Executes the ${toolName} command.`,
+        inputSchema,
+        outputSchema,
+        async execute(mcpInputArgs) {
+          var _a, _b, _c, _d, _e, _f;
+          if (mcpInputArgs["help"] === true) {
+            let helpParser = rootParser;
+            const pathParts = [...commandPathParts];
+            for (const part of pathParts) {
+              const subCmd = helpParser.getSubCommand ? helpParser.getSubCommand(part) : void 0;
+              if (subCmd && subCmd.parser) {
+                helpParser = subCmd.parser;
+              } else {
+                break;
+              }
+            }
+            const helpText = helpParser.helpText ? helpParser.helpText() : "Help not available";
+            if ((_a = options == null ? void 0 : options.outputSchemaMap) == null ? void 0 : _a[toolName]) {
+              return {
+                success: true,
+                help: helpText,
+                files: [],
+                commandExecuted: null,
+                stderrOutput: null
+              };
+            }
+            return { success: true, message: helpText };
+          }
+          const argv = [...commandPathParts];
+          const parserFlags = currentParserFlags;
+          for (const flagDef of parserFlags) {
+            const flagName = flagDef["name"];
+            if (mcpInputArgs.hasOwnProperty(flagName)) {
+              const value = mcpInputArgs[flagName];
+              const flagType = flagDef["type"];
+              const flagOptions = flagDef["options"];
+              const isFlagOnly = flagDef["flagOnly"];
+              const allowMultiple = flagDef["allowMultiple"];
+              let flagTypeName = typeof flagType === "function" ? flagType.name.toLowerCase().replace("constructor", "") : String(flagType).toLowerCase();
+              argv.push(flagOptions[0]);
+              if (flagTypeName === "boolean") {
+                if (value === true && isFlagOnly === false)
+                  argv.push(String(value));
+                else if (value === false && isFlagOnly === false)
+                  argv.push(String(value));
+              } else if (flagTypeName === "array") {
+                if (Array.isArray(value)) {
+                  if (allowMultiple) {
+                    const originalArgvLength = argv.length;
+                    value.forEach((item) => {
+                      argv.push(flagOptions[0]);
+                      argv.push(String(item));
+                    });
+                    if (value.length > 0 && argv[originalArgvLength - 1] === flagOptions[0]) {
+                      argv.splice(originalArgvLength - 1, 1);
+                    }
+                  } else {
+                    argv.push(value.join(","));
+                  }
+                } else if (value != null) argv.push(String(value));
+              } else if (value !== null && value !== void 0)
+                argv.push(String(value));
+            }
+          }
+          try {
+            const parseResult = await rootParser.parse(
+              argv
+            );
+            if (parseResult["$error"]) {
+              const errorDetails = parseResult["$error"];
+              const errPayload = {
+                message: `Cmd error: ${errorDetails.type} - ${errorDetails.message}`,
+                details: errorDetails.details
+              };
+              if ((_b = options == null ? void 0 : options.outputSchemaMap) == null ? void 0 : _b[toolName]) {
+                return {
+                  error: errPayload.message,
+                  files: [],
+                  commandExecuted: null,
+                  stderrOutput: ((_c = errPayload.details) == null ? void 0 : _c.stderr) || null
+                };
+              }
+              return {
+                success: false,
+                message: errPayload.message,
+                data: errPayload.details
+              };
+            }
+            let handlerResponse = parseResult["handlerResponse"];
+            if (handlerResponse === void 0 && parseResult["$commandChain"]) {
+              let finalParser = rootParser;
+              let currentArgs = { ...parseResult };
+              let resolvedParentArgs = void 0;
+              const chain = parseResult["$commandChain"];
+              for (let i = 0; i < chain.length; i++) {
+                const cmdName = chain[i];
+                const subCmdInfo = (finalParser == null ? void 0 : finalParser.getSubCommand) ? finalParser.getSubCommand(cmdName) : void 0;
+                if (subCmdInfo && subCmdInfo.parser) {
+                  resolvedParentArgs = { ...currentArgs };
+                  currentArgs = currentArgs[cmdName] || {};
+                  finalParser = subCmdInfo.parser;
+                } else if (i === 0 && finalParser && cmdName === (finalParser.getAppCommandName ? finalParser.getAppCommandName() : finalParser["#appCommandName"] || (finalParser.getAppName ? finalParser.getAppName() : finalParser["#appName"]))) {
+                  currentArgs = { ...parseResult };
+                  break;
+                } else {
+                  finalParser = void 0;
+                  break;
+                }
+              }
+              const finalParserTyped = finalParser;
+              const finalHandler = finalParserTyped.getHandler ? finalParserTyped.getHandler() : finalParserTyped["#handler"];
+              if (finalParser && finalHandler) {
+                const handlerToCall = finalHandler;
+                const handlerContext = {
+                  args: currentArgs,
+                  commandChain: chain,
+                  parser: finalParser,
+                  parentArgs: resolvedParentArgs
+                };
+                try {
+                  handlerResponse = await handlerToCall(handlerContext);
+                } catch (handlerError) {
+                  const errorMsg = `Handler error: ${handlerError.message || String(handlerError)}`;
+                  if ((_d = options == null ? void 0 : options.outputSchemaMap) == null ? void 0 : _d[toolName]) {
+                    return {
+                      error: errorMsg,
+                      files: [],
+                      commandExecuted: null,
+                      stderrOutput: null
+                    };
+                  }
+                  return { success: false, message: errorMsg };
+                }
+              }
+            }
+            if ((_e = options == null ? void 0 : options.outputSchemaMap) == null ? void 0 : _e[toolName]) {
+              return handlerResponse;
+            }
+            return { success: true, data: handlerResponse };
+          } catch (e) {
+            let errorMsg;
+            let errorDetails = e;
+            if (e instanceof Error && e.message) {
+              errorMsg = `Cmd error: handler_error - ${e.message}`;
+              errorDetails = { details: e };
+            } else {
+              errorMsg = `MCP tool exec failed: ${e.message || String(e)}`;
+            }
+            if ((_f = options == null ? void 0 : options.outputSchemaMap) == null ? void 0 : _f[toolName]) {
+              return {
+                error: errorMsg,
+                files: [],
+                commandExecuted: null,
+                stderrOutput: (errorDetails == null ? void 0 : errorDetails.stderr) || null
+              };
+            }
+            return {
+              success: false,
+              message: errorMsg,
+              data: errorDetails
+            };
+          }
+        }
+      };
+      tools.push(tool);
+    }
+    const subCommands = currentParserSubCommands;
+    if (subCommands && (options == null ? void 0 : options.includeSubCommands) !== false) {
+      for (const subCmdObj of subCommands) {
+        if (subCmdObj.isMcp === true) {
+          continue;
+        }
+        const nextPathParts = [...commandPathParts, subCmdObj.name];
+        buildToolsRecursively(
+          subCmdObj.parser,
+          nextPathParts.filter((p) => p)
+        );
+      }
+    }
+  }
+  buildToolsRecursively(rootParser, []);
+  return tools;
+}
+const _ArgParser = class _ArgParser extends ArgParserBase {
+  constructor() {
+    super(...arguments);
+    __privateAdd(this, _ArgParser_instances);
+  }
+  /**
+   * Generate MCP tools from this ArgParser instance
+   * @param options Optional configuration for MCP tool generation
+   * @returns Array of MCP tool structures ready for server registration
+   */
+  toMcpTools(options) {
+    return generateMcpToolsFromArgParser(this, options);
+  }
+  /**
+   * Create an MCP server with tools generated from this ArgParser
+   * @param serverInfo Server configuration
+   * @param toolOptions Optional MCP tool generation options
+   * @returns Configured MCP server instance
+   */
+  createMcpServer(serverInfo, toolOptions) {
+    const { McpServer } = require("@modelcontextprotocol/sdk/server/mcp.js");
+    const server = new McpServer({
+      id: serverInfo.name,
+      version: serverInfo.version,
+      name: serverInfo.name,
+      description: serverInfo.description
+    });
+    const tools = this.toMcpTools(toolOptions);
+    const uniqueTools = tools.reduce((acc, tool) => {
+      if (!acc.find((t) => t.name === tool.name)) {
+        acc.push(tool);
+      }
+      return acc;
+    }, []);
+    uniqueTools.forEach((tool) => {
+      const toolConfig = {
+        description: tool.description || "No description provided.",
+        inputSchema: tool.inputSchema.shape || tool.inputSchema
+      };
+      if (tool.outputSchema) {
+        toolConfig.outputSchema = tool.outputSchema.shape || tool.outputSchema;
+      }
+      server.registerTool(tool.name, toolConfig, tool.execute);
+    });
+    return server;
+  }
+  /**
+   * Start an MCP server using stdio transport
+   * @param serverInfo Server configuration
+   * @param toolOptions Optional MCP tool generation options
+   * @returns Promise that resolves when server is connected
+   */
+  async startMcpServer(serverInfo, toolOptions) {
+    return this.startMcpServerWithTransport(serverInfo, "stdio", {}, toolOptions);
+  }
+  /**
+   * Start an MCP server with multiple transport types simultaneously
+   * @param serverInfo Server configuration
+   * @param transports Array of transport configurations
+   * @param toolOptions Optional MCP tool generation options
+   * @returns Promise that resolves when all servers are started
+   */
+  async startMcpServerWithMultipleTransports(serverInfo, transports, toolOptions) {
+    const server = this.createMcpServer(serverInfo, toolOptions);
+    const startPromises = [];
+    for (const transportConfig of transports) {
+      const promise = __privateMethod(this, _ArgParser_instances, _startSingleTransport_fn).call(this, server, serverInfo, transportConfig);
+      startPromises.push(promise);
+    }
+    await Promise.all(startPromises);
+    console.error(`[${serverInfo.name}] All MCP transports started successfully`);
+  }
+  /**
+   * Start an MCP server with a specific transport type
+   * @param serverInfo Server configuration
+   * @param transportType Type of transport to use
+   * @param transportOptions Transport-specific options
+   * @param toolOptions Optional MCP tool generation options
+   * @returns Promise that resolves when server is connected
+   */
+  async startMcpServerWithTransport(serverInfo, transportType, transportOptions = {}, toolOptions) {
+    const server = this.createMcpServer(serverInfo, toolOptions);
+    await __privateMethod(this, _ArgParser_instances, _startSingleTransport_fn).call(this, server, serverInfo, {
+      type: transportType,
+      ...transportOptions
+    });
+  }
+  /**
+   * Override parse() to handle async handlers properly
+   * This allows ArgParser to work with async handlers while keeping
+   * backwards compatibility for synchronous usage
+   */
+  parse(processArgs, options) {
+    const result = super.parse(processArgs, options);
+    const anyResult = result;
+    if (anyResult._fuzzyModePreventedExecution) {
+      return result;
+    }
+    if (anyResult._asyncHandlerPromise) {
+      return this.parseAsync(processArgs, options);
+    }
+    return result;
+  }
+  /**
+   * Async version of parse for when async handlers are detected
+   */
+  async parseAsync(processArgs, options) {
+    const result = super.parse(processArgs, options);
+    const anyResult = result;
+    if (anyResult._fuzzyModePreventedExecution) {
+      return result;
+    }
+    if (anyResult._asyncHandlerPromise) {
+      try {
+        const handlerResult = await anyResult._asyncHandlerPromise;
+        anyResult.handlerResponse = handlerResult;
+      } catch (error) {
+        if (this["#handleErrors"]) {
+          anyResult.$error = {
+            type: "handler_error",
+            message: error instanceof Error ? error.message : String(error),
+            details: error
+          };
+        } else {
+          throw error;
+        }
+      }
+      delete anyResult._asyncHandlerPromise;
+      delete anyResult._asyncHandlerInfo;
+    }
+    return result;
+  }
+  addMcpSubCommand(subCommandName = "mcp-server", serverInfo, optionsOrToolOptions) {
+    let options;
+    if (optionsOrToolOptions && typeof optionsOrToolOptions === "object" && ("includeSubCommands" in optionsOrToolOptions || "toolNamePrefix" in optionsOrToolOptions || "toolNameSuffix" in optionsOrToolOptions)) {
+      options = { toolOptions: optionsOrToolOptions };
+    } else {
+      options = optionsOrToolOptions || {};
+    }
+    const { defaultTransports, defaultTransport, toolOptions } = options;
+    const mcpHandler = async (ctx) => {
+      if (!ctx.parentParser) {
+        console.error(
+          "[MCP Server] Critical: MCP server handler called without a parent parser context."
+        );
+        process.exit(1);
+      }
+      console.error(`[${serverInfo.name}] Starting MCP Server...`);
+      const mcpParser = ctx.parentParser;
+      const transports = ctx.args["transports"];
+      if (transports) {
+        try {
+          const transportConfigs = JSON.parse(transports);
+          await mcpParser.startMcpServerWithMultipleTransports(serverInfo, transportConfigs, toolOptions);
+        } catch (error) {
+          console.error("❌ Error parsing transports configuration:", error.message);
+          console.error(`Expected JSON format: '[{"type":"stdio"},{"type":"sse","port":3001}]'`);
+          process.exit(1);
+        }
+      } else if (defaultTransports && defaultTransports.length > 0) {
+        await mcpParser.startMcpServerWithMultipleTransports(serverInfo, defaultTransports, toolOptions);
+      } else if (defaultTransport) {
+        await mcpParser.startMcpServerWithTransport(
+          serverInfo,
+          defaultTransport.type,
+          {
+            port: defaultTransport.port,
+            host: defaultTransport.host,
+            path: defaultTransport.path,
+            sessionIdGenerator: defaultTransport.sessionIdGenerator
+          },
+          toolOptions
+        );
+      } else {
+        const transportType = ctx.args["transport"] || "stdio";
+        const transportOptions = {
+          port: ctx.args["port"],
+          host: ctx.args["host"],
+          path: ctx.args["path"]
+        };
+        await mcpParser.startMcpServerWithTransport(serverInfo, transportType, transportOptions, toolOptions);
+      }
+      return new Promise(() => {
+      });
+    };
+    const mcpSubParser = new ArgParserBase({}, [
+      {
+        name: "transport",
+        description: "Transport type for MCP server (single transport mode)",
+        options: ["--transport", "-t"],
+        type: "string",
+        enum: ["stdio", "sse", "streamable-http"],
+        defaultValue: "stdio"
+      },
+      {
+        name: "transports",
+        description: "Multiple transports configuration as JSON array (overrides single transport)",
+        options: ["--transports"],
+        type: "string"
+      },
+      {
+        name: "port",
+        description: "Port number for HTTP-based transports (single transport mode)",
+        options: ["--port", "-p"],
+        type: "number",
+        defaultValue: 3e3
+      },
+      {
+        name: "host",
+        description: "Host address for HTTP-based transports (single transport mode)",
+        options: ["--host"],
+        type: "string",
+        defaultValue: "localhost"
+      },
+      {
+        name: "path",
+        description: "Path for HTTP-based transports (single transport mode)",
+        options: ["--path"],
+        type: "string",
+        defaultValue: "/mcp"
+      }
+    ]);
+    this.addSubCommand({
+      name: subCommandName,
+      description: `Start ${serverInfo.name} as an MCP server`,
+      handler: mcpHandler,
+      parser: mcpSubParser,
+      isMcp: true
+    });
+    return this;
+  }
+  /**
+   * Factory method to create an ArgParser instance with MCP capabilities
+   * This provides a clean API for users who want MCP functionality from the start
+   */
+  static withMcp(options, initialFlags) {
+    return new _ArgParser(options, initialFlags);
+  }
+  /**
+   * Convert an existing ArgParserBase instance to ArgParser with MCP
+   * This allows upgrading existing parsers to support MCP
+   */
+  static fromArgParser(parser) {
+    const originalParser = parser;
+    const mcpParser = new _ArgParser({
+      appName: originalParser.getAppName(),
+      appCommandName: originalParser.getAppCommandName(),
+      description: originalParser.getDescription(),
+      handler: originalParser.getHandler(),
+      handleErrors: originalParser["#handleErrors"],
+      throwForDuplicateFlags: originalParser["#throwForDuplicateFlags"]
+    });
+    const originalFlags = originalParser.flags.filter(
+      (flag) => flag.name !== "help"
+    );
+    if (originalFlags.length > 0) {
+      mcpParser.addFlags(originalFlags);
+    }
+    const newParser = mcpParser;
+    newParser["#subCommandName"] = originalParser["#subCommandName"];
+    newParser["#parameters"] = originalParser["#parameters"];
+    newParser["#parentParser"] = originalParser["#parentParser"];
+    newParser["#lastParseResult"] = originalParser["#lastParseResult"];
+    newParser["#inheritParentFlags"] = originalParser["#inheritParentFlags"];
+    newParser["#subCommands"] = originalParser["#subCommands"];
+    return mcpParser;
+  }
+};
+_ArgParser_instances = new WeakSet();
+_startSingleTransport_fn = async function(server, serverInfo, transportConfig) {
+  switch (transportConfig.type) {
+    case "stdio": {
+      const { StdioServerTransport } = await import("./stdio-DLOResWr.js");
+      const transport = new StdioServerTransport();
+      await server.connect(transport);
+      console.error(`[${serverInfo.name}] MCP Server started with stdio transport`);
+      break;
+    }
+    case "sse": {
+      const { SSEServerTransport } = await import("./sse-BDL3h2Ll.js");
+      const express = (await import("express")).default;
+      const app = express();
+      app.use(express.json());
+      const port = transportConfig.port || 3e3;
+      const path2 = transportConfig.path || "/sse";
+      app.get(path2, (_req, res) => {
+        const transport = new SSEServerTransport(path2, res);
+        server.connect(transport);
+      });
+      await new Promise((resolve) => {
+        app.listen(port, transportConfig.host || "localhost", () => {
+          console.error(`[${serverInfo.name}] MCP Server listening on http://${transportConfig.host || "localhost"}:${port}${path2} (SSE)`);
+          resolve();
+        });
+      });
+      break;
+    }
+    case "streamable-http": {
+      const { StreamableHTTPServerTransport } = await import("./streamableHttp-Vd4Qsgko.js");
+      const express = (await import("express")).default;
+      const app = express();
+      app.use(express.json());
+      const port = transportConfig.port || 3e3;
+      const path2 = transportConfig.path || "/mcp";
+      const transports = {};
+      app.all(path2, async (req, res) => {
+        const sessionId = req.headers["mcp-session-id"];
+        let transport;
+        if (sessionId && transports[sessionId]) {
+          transport = transports[sessionId];
+        } else {
+          transport = new StreamableHTTPServerTransport({
+            sessionIdGenerator: transportConfig.sessionIdGenerator || (() => Math.random().toString(36).substring(7)),
+            onsessioninitialized: (sessionId2) => {
+              transports[sessionId2] = transport;
+            }
+          });
+          transport.onclose = () => {
+            if (transport.sessionId) {
+              delete transports[transport.sessionId];
+            }
+          };
+          await server.connect(transport);
+        }
+        await transport.handleRequest(req, res, req.body);
+      });
+      await new Promise((resolve) => {
+        app.listen(port, transportConfig.host || "localhost", () => {
+          console.error(`[${serverInfo.name}] MCP Server listening on http://${transportConfig.host || "localhost"}:${port}${path2} (HTTP)`);
+          resolve();
+        });
+      });
+      break;
+    }
+    default:
+      throw new Error(`Unsupported transport type: ${transportConfig.type}`);
+  }
+};
 let ArgParser = _ArgParser;
+class ArgParserFuzzyTester {
+  constructor(parser, options = {}) {
+    this.parser = parser;
+    this.options = {
+      maxDepth: options.maxDepth ?? 5,
+      randomTestCases: options.randomTestCases ?? 10,
+      includePerformance: options.includePerformance ?? true,
+      testErrorCases: options.testErrorCases ?? true,
+      verbose: options.verbose ?? false
+    };
+  }
+  /**
+   * Run comprehensive fuzzy testing on the ArgParser instance
+   */
+  async runFuzzyTest() {
+    const commandPaths = this.discoverCommandPaths();
+    const results = [];
+    if (this.options.verbose) {
+      console.log(`Discovered ${commandPaths.length} command paths:`);
+      commandPaths.forEach((path2) => console.log(`  ${path2.join(" ") || "(root)"}`));
+    }
+    for (const commandPath of commandPaths) {
+      const pathResults = await this.testCommandPath(commandPath);
+      results.push(...pathResults);
+    }
+    return this.generateReport(commandPaths, results);
+  }
+  /**
+   * Discover all possible command paths in the parser
+   */
+  discoverCommandPaths() {
+    const paths = [];
+    paths.push([]);
+    this.discoverSubCommandPaths(this.parser, [], paths, 0);
+    return paths;
+  }
+  /**
+   * Recursively discover subcommand paths
+   */
+  discoverSubCommandPaths(parser, currentPath, allPaths, depth) {
+    if (depth >= this.options.maxDepth) return;
+    const subCommands = this.getSubCommands(parser);
+    for (const [subCommandName, subCommand] of subCommands) {
+      const newPath = [...currentPath, subCommandName];
+      allPaths.push(newPath);
+      this.discoverSubCommandPaths(subCommand.parser, newPath, allPaths, depth + 1);
+    }
+  }
+  /**
+   * Get subcommands from a parser instance
+   */
+  getSubCommands(parser) {
+    return parser.getSubCommands();
+  }
+  /**
+   * Get flags from a parser instance
+   */
+  getFlags(parser) {
+    return parser.flags;
+  }
+  /**
+   * Test a specific command path with various flag combinations
+   */
+  async testCommandPath(commandPath) {
+    const results = [];
+    const targetParser = this.getParserForPath(commandPath);
+    const flags = this.getFlags(targetParser);
+    if (this.options.verbose) {
+      console.log(`Testing command path: ${commandPath.join(" ") || "(root)"}`);
+    }
+    const validCombinations = this.generateValidFlagCombinations(flags);
+    for (const flagArgs of validCombinations) {
+      const fullArgs = [...commandPath, ...flagArgs];
+      const result = await this.executeTest(fullArgs, commandPath);
+      results.push(result);
+    }
+    for (let i = 0; i < this.options.randomTestCases; i++) {
+      const randomArgs = this.generateRandomFlagCombination(flags);
+      const fullArgs = [...commandPath, ...randomArgs];
+      const result = await this.executeTest(fullArgs, commandPath);
+      results.push(result);
+    }
+    if (this.options.testErrorCases) {
+      const errorCases = this.generateErrorCases(flags);
+      for (const errorArgs of errorCases) {
+        const fullArgs = [...commandPath, ...errorArgs];
+        const result = await this.executeTest(fullArgs, commandPath, true);
+        results.push(result);
+      }
+    }
+    return results;
+  }
+  /**
+   * Get the parser instance for a specific command path
+   */
+  getParserForPath(commandPath) {
+    let currentParser = this.parser;
+    for (const command of commandPath) {
+      const subCommands = this.getSubCommands(currentParser);
+      const subCommand = subCommands.get(command);
+      if (!subCommand) {
+        throw new Error(`Command path not found: ${commandPath.join(" ")}`);
+      }
+      currentParser = subCommand.parser;
+    }
+    return currentParser;
+  }
+  /**
+   * Generate valid flag combinations for testing
+   */
+  generateValidFlagCombinations(flags) {
+    const combinations = [];
+    const mandatoryFlags = flags.filter(
+      (f) => f["name"] !== "help" && (typeof f["mandatory"] === "boolean" ? f["mandatory"] : false)
+    );
+    const optionalFlags = flags.filter(
+      (f) => f["name"] !== "help" && (typeof f["mandatory"] === "boolean" ? !f["mandatory"] : true)
+    );
+    const mandatoryArgs = [];
+    for (const flag of mandatoryFlags) {
+      const flagArgs = this.generateFlagArgs(flag, "valid");
+      mandatoryArgs.push(...flagArgs);
+    }
+    if (mandatoryArgs.length > 0) {
+      combinations.push([...mandatoryArgs]);
+    } else {
+      combinations.push([]);
+    }
+    for (const flag of optionalFlags) {
+      const flagArgs = this.generateFlagArgs(flag, "valid");
+      if (flagArgs.length > 0) {
+        combinations.push([...mandatoryArgs, ...flagArgs]);
+      }
+    }
+    if (optionalFlags.length > 1) {
+      for (let i = 0; i < optionalFlags.length - 1; i++) {
+        for (let j = i + 1; j < optionalFlags.length; j++) {
+          const flag1Args = this.generateFlagArgs(optionalFlags[i], "valid");
+          const flag2Args = this.generateFlagArgs(optionalFlags[j], "valid");
+          if (flag1Args.length > 0 && flag2Args.length > 0) {
+            combinations.push([...mandatoryArgs, ...flag1Args, ...flag2Args]);
+          }
+        }
+      }
+    }
+    return combinations;
+  }
+  /**
+   * Generate random flag combination
+   */
+  generateRandomFlagCombination(flags) {
+    const args = [];
+    const availableFlags = flags.filter((f) => f["name"] !== "help");
+    for (const flag of availableFlags) {
+      if (Math.random() < 0.3) {
+        const flagArgs = this.generateFlagArgs(flag, "random");
+        args.push(...flagArgs);
+      }
+    }
+    return args;
+  }
+  /**
+   * Generate error test cases
+   */
+  generateErrorCases(flags) {
+    const errorCases = [];
+    errorCases.push(["--invalid-flag"]);
+    errorCases.push(["--nonexistent", "value"]);
+    for (const flag of flags) {
+      if (flag["name"] === "help") continue;
+      const invalidArgs = this.generateFlagArgs(flag, "invalid");
+      if (invalidArgs.length > 0) {
+        errorCases.push(invalidArgs);
+      }
+    }
+    return errorCases;
+  }
+  /**
+   * Generate arguments for a specific flag
+   */
+  generateFlagArgs(flag, mode) {
+    const option = flag["options"][0];
+    if (!option) return [];
+    if (flag["flagOnly"]) {
+      return [option];
+    }
+    const values = this.generateFlagValues(flag, mode);
+    const args = [];
+    for (const value of values) {
+      if (flag["allowLigature"] && Math.random() < 0.5) {
+        args.push(`${option}=${value}`);
+      } else {
+        args.push(option, value);
+      }
+    }
+    return args;
+  }
+  /**
+   * Generate values for a flag based on its type and constraints
+   */
+  generateFlagValues(flag, mode) {
+    const count = flag["allowMultiple"] && mode !== "invalid" ? Math.floor(Math.random() * 3) + 1 : 1;
+    const values = [];
+    for (let i = 0; i < count; i++) {
+      values.push(this.generateSingleFlagValue(flag, mode));
+    }
+    return values;
+  }
+  /**
+   * Generate a single value for a flag
+   */
+  generateSingleFlagValue(flag, mode) {
+    if (mode === "invalid") {
+      if (flag["type"] === Number) return "not-a-number";
+      if (flag["enum"] && flag["enum"].length > 0) return "invalid-enum-value";
+      if (flag["type"] === Boolean) return "not-boolean";
+      return "invalid-value";
+    }
+    if (flag["enum"] && flag["enum"].length > 0) {
+      const randomIndex = Math.floor(Math.random() * flag["enum"].length);
+      return String(flag["enum"][randomIndex]);
+    }
+    if (flag["type"] === Number) {
+      return String(Math.floor(Math.random() * 1e3));
+    }
+    if (flag["type"] === Boolean) {
+      return Math.random() < 0.5 ? "true" : "false";
+    }
+    const testStrings = [
+      "test-value",
+      "hello-world",
+      "file.txt",
+      "/path/to/file",
+      "user@example.com",
+      "123",
+      "special-chars-!@#"
+    ];
+    return testStrings[Math.floor(Math.random() * testStrings.length)];
+  }
+  /**
+   * Execute a single test case
+   */
+  async executeTest(args, commandPath, expectError = false) {
+    const startTime = this.options.includePerformance ? Date.now() : 0;
+    try {
+      const originalArgs = [...args];
+      const testResult = this.parser.parse(args, {
+        skipHelpHandling: true
+      });
+      if (testResult && typeof testResult === "object") {
+        testResult._originalInputArgs = originalArgs;
+      }
+      const executionTime = this.options.includePerformance ? Date.now() - startTime : void 0;
+      return {
+        commandPath,
+        args,
+        success: !expectError,
+        parsedResult: testResult,
+        executionTime
+      };
+    } catch (error) {
+      const executionTime = this.options.includePerformance ? Date.now() - startTime : void 0;
+      return {
+        commandPath,
+        args,
+        success: expectError,
+        error: error instanceof Error ? error.message : String(error),
+        executionTime
+      };
+    }
+  }
+  /**
+   * Generate comprehensive test report
+   */
+  generateReport(commandPaths, results) {
+    const totalTests = results.length;
+    const successfulTests = results.filter((r) => r.success).length;
+    const failedTests = totalTests - successfulTests;
+    const coverageByPath = {};
+    for (const path2 of commandPaths) {
+      const pathKey = path2.join(" ") || "(root)";
+      const pathResults = results.filter(
+        (r) => JSON.stringify(r.commandPath) === JSON.stringify(path2)
+      );
+      coverageByPath[pathKey] = {
+        total: pathResults.length,
+        passed: pathResults.filter((r) => r.success).length
+      };
+    }
+    const errorTypes = {};
+    for (const result of results) {
+      if (result.error) {
+        const errorType = result.error.split(":")[0] || "Unknown";
+        errorTypes[errorType] = (errorTypes[errorType] || 0) + 1;
+      }
+    }
+    return {
+      totalTests,
+      successfulTests,
+      failedTests,
+      commandPaths,
+      results,
+      summary: {
+        coverageByPath,
+        errorTypes
+      }
+    };
+  }
+}
 export {
   ArgParser,
-  ArgParserError
+  ArgParserBase,
+  ArgParserError,
+  ArgParserFuzzyTester,
+  generateMcpToolsFromArgParser,
+  zodFlagSchema
 };
 //# sourceMappingURL=index.mjs.map