@alcyone-labs/arg-parser 2.7.1 → 2.8.0

package/dist/index.mjs

@@ -9,7 +9,7 @@ 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, _autoExit, _parentParser, _lastParseResult, _inheritParentFlags, _subCommands, _flagManager, _dxtGenerator, _configurationManager, _fuzzyMode, _mcpResourcesManager, _mcpPromptsManager, _mcpNotificationsManager, _ArgParserBase_instances, _identifyCommandChainAndParsers_fn, _handleGlobalChecks_fn, _validateMandatoryFlags_fn, _applyDefaultValues_fn, _prepareAndExecuteHandler_fn, parseFlags_fn, _enableFuzzyMode_fn, displayErrorAndExit_fn, _printRecursiveToConsole_fn, _buildRecursiveString_fn, _buildRecursiveJson_fn, _handleSaveToEnvFlag_fn, _handleBuildDxtFlag_fn, _handleMcpServeFlag_fn, _resolveLoggerConfigForServe_fn, _getMcpServerConfiguration_fn, _startUnifiedMcpServer_fn, _findAllMcpSubCommands_fn, _parseMcpTransportOptions_fn, _ArgParser_instances, _resolveLoggerConfig_fn, registerToolAsSubCommand_fn, _startSingleTransport_fn, processAsyncHandlerPromise_fn, _hasDate, _hasTime, _offset;
+var __flags, _throwForDuplicateFlags, _appName, _appCommandName, _subCommandName, _parameters, _handler, _throwForDuplicateFlags2, _description, _handleErrors, _autoExit, _parentParser, _lastParseResult, _inheritParentFlags, _subCommands, _flagManager, _dxtGenerator, _configurationManager, _fuzzyMode, _dynamicFlagNames, _mcpResourcesManager, _mcpPromptsManager, _mcpNotificationsManager, _ArgParserBase_instances, registerDynamicFlags_fn, resetDynamicFlagsRecursive_fn, _preloadDynamicFlagsForHelp_fn, _identifyCommandChainAndParsers_fn, _handleGlobalChecks_fn, _validateMandatoryFlags_fn, _applyDefaultValues_fn, _prepareAndExecuteHandler_fn, parseFlags_fn, _enableFuzzyMode_fn, displayErrorAndExit_fn, _printRecursiveToConsole_fn, _buildRecursiveString_fn, _buildRecursiveJson_fn, _handleSaveToEnvFlag_fn, _handleBuildDxtFlag_fn, _handleMcpServeFlag_fn, _resolveLoggerConfigForServe_fn, _getMcpServerConfiguration_fn, _startUnifiedMcpServer_fn, _findAllMcpSubCommands_fn, _parseMcpTransportOptions_fn, _ArgParser_instances, _resolveLoggerConfig_fn, registerToolAsSubCommand_fn, _startSingleTransport_fn, processAsyncHandlerPromise_fn, _hasDate, _hasTime, _offset;
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { fileURLToPath } from "node:url";
@@ -1036,13 +1036,17 @@ class ConfigurationManager {
   }
 }
 const zodDxtOptionsSchema = z.object({
-  sensitive: z.boolean().optional().describe("Whether this field should be marked as sensitive in DXT user_config"),
+  sensitive: z.boolean().optional().describe(
+    "Whether this field should be marked as sensitive in DXT user_config"
+  ),
   localDefault: z.string().optional().describe("Default value specific to DXT sandbox environment"),
   type: z.enum(["string", "directory", "file", "boolean", "number"]).optional().describe("DXT input type - determines UI component in DXT clients"),
   multiple: z.boolean().optional().describe("Allow multiple values (for arrays)"),
   min: z.number().optional().describe("Minimum value (for number type)"),
   max: z.number().optional().describe("Maximum value (for number type)"),
-  default: z.any().optional().describe("DXT-specific default value (overrides localDefault if provided)"),
+  default: z.any().optional().describe(
+    "DXT-specific default value (overrides localDefault if provided)"
+  ),
   title: z.string().optional().describe("Custom title for the user_config field")
 }).strict().refine(
   (data2) => {
@@ -1130,7 +1134,12 @@ const zodFlagSchema = z.object({
   env: z.union([z.string(), z.array(z.string())]).optional().describe(
     "Environment variables that should be set from this flag's value in DXT packages."
   ),
-  dxtOptions: zodDxtOptionsSchema.optional().describe("DXT-specific configuration options for enhanced DXT manifest generation")
+  dxtOptions: zodDxtOptionsSchema.optional().describe(
+    "DXT-specific configuration options for enhanced DXT manifest generation"
+  ),
+  dynamicRegister: z.custom((val) => typeof val === "function").optional().describe(
+    "Optional callback that can register additional flags dynamically when this flag is present."
+  )
 }).transform((obj) => {
   const newObj = { ...obj };
   if ("default" in newObj && newObj["default"] !== void 0 && !("defaultValue" in newObj)) {
@@ -3633,6 +3642,9 @@ const _FlagManager = class _FlagManager {
   hasFlag(name) {
     return __privateGet(this, __flags).has(name);
   }
+  removeFlag(name) {
+    return __privateGet(this, __flags).delete(name);
+  }
   getFlag(name) {
     return __privateGet(this, __flags).get(name);
   }
@@ -3679,6 +3691,8 @@ const _ArgParserBase = class _ArgParserBase {
     __privateAdd(this, _dxtGenerator);
     __privateAdd(this, _configurationManager);
     __privateAdd(this, _fuzzyMode, false);
+    // Track dynamically added flags so we can clean them between parses
+    __privateAdd(this, _dynamicFlagNames, /* @__PURE__ */ new Set());
     // MCP-related managers
     __privateAdd(this, _mcpResourcesManager, new McpResourcesManager());
     __privateAdd(this, _mcpPromptsManager, new McpPromptsManager());
@@ -3794,10 +3808,14 @@ const _ArgParserBase = class _ArgParserBase {
           value = flag["type"].parse(parsedJson);
         } catch (error) {
           if (error instanceof SyntaxError) {
-            throw new Error(`Invalid JSON for flag '${flag["name"]}': ${error.message}`);
+            throw new Error(
+              `Invalid JSON for flag '${flag["name"]}': ${error.message}`
+            );
           } else {
             const errorMessage = error instanceof Error ? error.message : String(error);
-            throw new Error(`Validation failed for flag '${flag["name"]}': ${errorMessage}`);
+            throw new Error(
+              `Validation failed for flag '${flag["name"]}': ${errorMessage}`
+            );
           }
         }
       } else {
@@ -3938,9 +3956,13 @@ const _ArgParserBase = class _ArgParserBase {
     debug.log("ArgParserBase.parse() called with args:", processArgs);
     const shouldCheckAutoExecution = (options == null ? void 0 : options.importMetaUrl) && (options == null ? void 0 : options.autoExecute) !== false;
     if (shouldCheckAutoExecution) {
-      const isDirectExecution = _ArgParserBase.isExecutedDirectly(options.importMetaUrl);
+      const isDirectExecution = _ArgParserBase.isExecutedDirectly(
+        options.importMetaUrl
+      );
       if (!isDirectExecution) {
-        debug.log("Auto-execution enabled but script is imported, skipping execution");
+        debug.log(
+          "Auto-execution enabled but script is imported, skipping execution"
+        );
         return {};
       }
     }
@@ -3953,6 +3975,7 @@ const _ArgParserBase = class _ArgParserBase {
         );
       }
     }
+    __privateMethod(this, _ArgParserBase_instances, resetDynamicFlagsRecursive_fn).call(this);
     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) {
@@ -4206,7 +4229,9 @@ ${cyan("Flags:")}
                 if (properties2.length <= 4) {
                   typeDetails.push(`Properties: ${properties2.join(", ")}`);
                 } else {
-                  typeDetails.push(`Properties: ${properties2.slice(0, 4).join(", ")}, ... (${properties2.length} total)`);
+                  typeDetails.push(
+                    `Properties: ${properties2.slice(0, 4).join(", ")}, ... (${properties2.length} total)`
+                  );
                 }
               }
             }
@@ -4388,10 +4413,62 @@ _flagManager = new WeakMap();
 _dxtGenerator = new WeakMap();
 _configurationManager = new WeakMap();
 _fuzzyMode = new WeakMap();
+_dynamicFlagNames = new WeakMap();
 _mcpResourcesManager = new WeakMap();
 _mcpPromptsManager = new WeakMap();
 _mcpNotificationsManager = new WeakMap();
 _ArgParserBase_instances = new WeakSet();
+// Register flags coming from dynamic loaders and track them for cleanup
+registerDynamicFlags_fn = function(flags) {
+  if (!Array.isArray(flags) || flags.length === 0) return;
+  for (const flag of flags) {
+    const name = flag["name"];
+    const existed = __privateGet(this, _flagManager).hasFlag(name);
+    __privateGet(this, _flagManager).addFlag(flag);
+    if (!existed) __privateGet(this, _dynamicFlagNames).add(name);
+  }
+};
+// Remove dynamically registered flags on this parser and all sub-parsers
+resetDynamicFlagsRecursive_fn = function(parser = this) {
+  var _a;
+  for (const name of __privateGet(parser, _dynamicFlagNames)) {
+    __privateGet(parser, _flagManager).removeFlag(name);
+  }
+  __privateGet(parser, _dynamicFlagNames).clear();
+  for (const [, sub] of __privateGet(parser, _subCommands)) {
+    if (sub && sub.parser instanceof _ArgParserBase) {
+      __privateMethod(_a = sub.parser, _ArgParserBase_instances, resetDynamicFlagsRecursive_fn).call(_a);
+    }
+  }
+};
+_preloadDynamicFlagsForHelp_fn = async function(processArgs) {
+  var _a;
+  let currentParser = this;
+  let remaining = [...processArgs];
+  while (true) {
+    let subIndex = -1;
+    for (let i = 0; i < remaining.length; i++) {
+      if (__privateGet(currentParser, _subCommands).has(remaining[i])) {
+        subIndex = i;
+        break;
+      }
+    }
+    const segment = subIndex === -1 ? remaining : remaining.slice(0, subIndex);
+    try {
+      await __privateMethod(_a = currentParser, _ArgParserBase_instances, parseFlags_fn).call(_a, segment, {
+        skipHelpHandling: true,
+        dynamicHelpPreload: true
+      });
+    } catch {
+    }
+    if (subIndex === -1) break;
+    const nextName = remaining[subIndex];
+    const sub = __privateGet(currentParser, _subCommands).get(nextName);
+    if (!sub || !(sub.parser instanceof _ArgParserBase)) break;
+    currentParser = sub.parser;
+    remaining = remaining.slice(subIndex + 1);
+  }
+};
 _identifyCommandChainAndParsers_fn = function(argsToParse, currentParser, commandChainSoFar, parserChainSoFar) {
   let subCommandIndex = -1;
   let subCommandName = null;
@@ -4637,6 +4714,7 @@ _handleGlobalChecks_fn = async function(processArgs, options) {
       (arg) => helpOptions.includes(arg)
     );
     if (helpRequested) {
+      await __privateMethod(this, _ArgParserBase_instances, _preloadDynamicFlagsForHelp_fn).call(this, processArgs);
       console.log(identifiedFinalParser.helpText());
       return this._handleExit(0, "Help displayed", "help");
     }
@@ -4761,8 +4839,95 @@ _prepareAndExecuteHandler_fn = function(handlerToExecute, finalArgs, skipHandler
   }
 };
 parseFlags_fn = async function(args, options) {
-  var _a, _b;
-  const flags = __privateGet(this, _flagManager).flags;
+  var _a, _b, _c;
+  let flags = __privateGet(this, _flagManager).flags;
+  const dynamicCandidates = flags.filter(
+    (f) => typeof f["dynamicRegister"] === "function"
+  );
+  if (dynamicCandidates.length > 0) {
+    const loaderOutput = Object.fromEntries(
+      dynamicCandidates.map((f) => [
+        f["name"],
+        f["allowMultiple"] ? [] : void 0
+      ])
+    );
+    const tmpConsumed = /* @__PURE__ */ new Set();
+    for (const flagToCheck of dynamicCandidates) {
+      if (flagToCheck["allowLigature"] && !flagToCheck["flagOnly"]) {
+        const regex = createRegExp(
+          anyOf$1(
+            ...flagToCheck["options"].map((option) => `${option}=`)
+          ),
+          oneOrMore(char).groupedAs("arg")
+        );
+        for (let i = 0; i < args.length; i++) {
+          if (tmpConsumed.has(i)) continue;
+          const matches = regex.exec(`${args[i]}`);
+          if ((_a = matches == null ? void 0 : matches.groups) == null ? void 0 : _a["arg"]) {
+            await this._addToOutput(
+              flagToCheck,
+              matches.groups["arg"],
+              loaderOutput,
+              options
+            );
+            tmpConsumed.add(i);
+            if (!flagToCheck["allowMultiple"]) break;
+          }
+        }
+      }
+    }
+    for (const flagToCheck of dynamicCandidates) {
+      for (let index2 = 0; index2 < args.length; index2++) {
+        if (tmpConsumed.has(index2)) continue;
+        const value = args[index2];
+        const nextIndex = index2 + 1;
+        const nextValueExists = nextIndex < args.length;
+        const nextValue = nextValueExists ? args[nextIndex] : void 0;
+        const nextValueIsFlag = typeof nextValue === "string" && nextValue.startsWith("-");
+        if (flagToCheck["options"].includes(value)) {
+          tmpConsumed.add(index2);
+          if (flagToCheck["flagOnly"]) {
+            await this._addToOutput(flagToCheck, true, loaderOutput, options);
+          } else if (nextValueExists && !nextValueIsFlag) {
+            await this._addToOutput(
+              flagToCheck,
+              nextValue,
+              loaderOutput,
+              options
+            );
+            tmpConsumed.add(nextIndex);
+          } else if (flagToCheck["type"] === Boolean) {
+            await this._addToOutput(flagToCheck, true, loaderOutput, options);
+          }
+          if (!flagToCheck["allowMultiple"]) break;
+        }
+      }
+    }
+    for (const flagToCheck of dynamicCandidates) {
+      const val = loaderOutput[flagToCheck["name"]];
+      const hasValue = flagToCheck["allowMultiple"] ? Array.isArray(val) && val.length > 0 : val !== void 0;
+      if (!hasValue) continue;
+      const registerFlags = (newFlags) => {
+        if (Array.isArray(newFlags) && newFlags.length) {
+          __privateMethod(this, _ArgParserBase_instances, registerDynamicFlags_fn).call(this, newFlags);
+        }
+      };
+      const dyn = flagToCheck["dynamicRegister"];
+      if (typeof dyn === "function") {
+        const maybe = dyn({
+          value: val,
+          argsSoFar: loaderOutput,
+          parser: this,
+          processArgs: args,
+          forHelp: !!(options == null ? void 0 : options.dynamicHelpPreload),
+          registerFlags
+        });
+        const awaited = maybe && typeof maybe.then === "function" ? await maybe : maybe;
+        if (Array.isArray(awaited)) registerFlags(awaited);
+      }
+    }
+    flags = __privateGet(this, _flagManager).flags;
+  }
   const output = Object.fromEntries(
     flags.map((flag) => [
       flag["name"],
@@ -4782,10 +4947,10 @@ parseFlags_fn = async function(args, options) {
         if (consumedIndices.has(i)) continue;
         const itemToCheck = args[i];
         const matches = regex.exec(`${itemToCheck}`);
-        if ((_a = matches == null ? void 0 : matches.groups) == null ? void 0 : _a["arg"]) {
+        if ((_b = matches == null ? void 0 : matches.groups) == null ? void 0 : _b["arg"]) {
           await this._addToOutput(
             flagToCheck,
-            (_b = matches == null ? void 0 : matches.groups) == null ? void 0 : _b["arg"],
+            (_c = matches == null ? void 0 : matches.groups) == null ? void 0 : _c["arg"],
             output,
             options
           );