@alcyone-labs/arg-parser 2.10.2 → 2.10.3

package/dist/index.mjs

@@ -1370,6 +1370,22 @@ const _DxtPathResolver = class _DxtPathResolver {
 };
 _DxtPathResolver._cachedContext = null;
 let DxtPathResolver = _DxtPathResolver;
+const FlagInheritance = {
+  /**
+   * No flags are inherited from the parent.
+   */
+  NONE: "none",
+  /**
+   * Inherits flags only from the direct parent at the time of attachment (Snapshot behavior).
+   * Equivalent to `true` in legacy boolean config.
+   */
+  DirectParentOnly: "direct-parent-only",
+  /**
+   * Inherits flags from the entire parent chain, ensuring grandchildren receive root flags
+   * even in bottom-up construction scenarios.
+   */
+  AllParents: "all-parents"
+};
 const zodDxtOptionsSchema = z.object({
   sensitive: z.boolean().optional().describe(
     "Whether this field should be marked as sensitive in DXT user_config"
@@ -3685,6 +3701,7 @@ class ArgParserBase {
   #dxtGenerator;
   #configurationManager;
   #fuzzyMode = false;
+  #triggerAutoHelpIfNoHandler = false;
   // Track dynamically added flags so we can clean them between parses
   #dynamicFlagNames = /* @__PURE__ */ new Set();
   // MCP-related managers
@@ -3712,6 +3729,7 @@ class ArgParserBase {
     this.#handleErrors = options.handleErrors ?? true;
     this.#autoExit = options.autoExit ?? true;
     this.#inheritParentFlags = options.inheritParentFlags ?? false;
+    this.#triggerAutoHelpIfNoHandler = options.triggerAutoHelpIfNoHandler ?? false;
     this.#description = options.description;
     this.#handler = options.handler;
     this.#appCommandName = options.appCommandName;
@@ -3916,7 +3934,9 @@ class ArgParserBase {
       subParser.#appCommandName = this.#appCommandName;
     }
     subParser.#autoExit = this.#autoExit;
-    if (subParser.#inheritParentFlags) {
+    subParser.#triggerAutoHelpIfNoHandler = this.#triggerAutoHelpIfNoHandler;
+    const shouldInherit = subParser.#inheritParentFlags === true || subParser.#inheritParentFlags === FlagInheritance.DirectParentOnly || subParser.#inheritParentFlags === FlagInheritance.AllParents;
+    if (shouldInherit) {
       const parentFlags = this.#flagManager.flags;
       for (const parentFlag of parentFlags) {
         if (!subParser.#flagManager.hasFlag(parentFlag["name"])) {
@@ -3925,11 +3945,36 @@ class ArgParserBase {
       }
     }
     this.#subCommands.set(subCommandConfig.name, subCommandConfig);
+    this.#propagateFlagsRecursive(subParser);
     if (subCommandConfig.handler) {
       subParser.setHandler(subCommandConfig.handler);
     }
     return this;
   }
+  /**
+   * Propagates available flags from the current parser to its subcommands,
+   * if those subcommands are configured to inherit recursively (AllParents).
+   */
+  #propagateFlagsRecursive(parser) {
+    for (const [_, subConfig] of parser.getSubCommands()) {
+      const childParser = subConfig.parser;
+      if (!(childParser instanceof ArgParserBase)) continue;
+      const isAllParents = childParser.#inheritParentFlags === FlagInheritance.AllParents;
+      if (isAllParents) {
+        const parentFlags = parser.#flagManager.flags;
+        let flagsAdded = false;
+        for (const parentFlag of parentFlags) {
+          if (!childParser.#flagManager.hasFlag(parentFlag["name"])) {
+            childParser.#flagManager._setProcessedFlagForInheritance(parentFlag);
+            flagsAdded = true;
+          }
+        }
+        if (flagsAdded) {
+          this.#propagateFlagsRecursive(childParser);
+        }
+      }
+    }
+  }
   /**
    * Sets the handler function for this specific parser instance.
    * This handler will be executed if this parser is the final one
@@ -4592,16 +4637,29 @@ class ArgParserBase {
         finalParseResultArgs["$commandChain"] = commandChainSoFar;
       }
       let handlerToExecute = void 0;
+      const handlerContext = {
+        args: currentLevelArgs,
+        parentArgs: accumulatedParentArgs,
+        commandChain: commandChainSoFar,
+        parser: currentParser,
+        parentParser,
+        // displayHelp implementation that respects autoExit setting
+        displayHelp: () => {
+          console.log(currentParser.helpText());
+          if (currentParser.getAutoExit() && typeof process === "object" && typeof process.exit === "function") {
+            process.exit(0);
+          }
+        }
+      };
       if (currentParser.#handler) {
         handlerToExecute = {
           handler: currentParser.#handler,
-          context: {
-            args: currentLevelArgs,
-            parentArgs: accumulatedParentArgs,
-            commandChain: commandChainSoFar,
-            parser: currentParser,
-            parentParser
-          }
+          context: handlerContext
+        };
+      } else if (currentParser.#triggerAutoHelpIfNoHandler) {
+        handlerToExecute = {
+          handler: (ctx) => ctx.displayHelp(),
+          context: handlerContext
         };
       }
       return { finalArgs: finalParseResultArgs, handlerToExecute };
@@ -5716,6 +5774,9 @@ ${simpleChalk.dim(`Try '${commandNameToSuggest} --help' for usage details.`)}`
     return options;
   }
 }
+const autoHelpHandler = async (ctx) => {
+  ctx.displayHelp();
+};
 function sanitizeMcpToolName(name) {
   if (!name || typeof name !== "string") {
     throw new Error("Tool name must be a non-empty string");
@@ -6203,7 +6264,12 @@ function generateMcpToolsFromArgParser(rootParser, options) {
                     parser: rootParser,
                     parentArgs: void 0,
                     isMcp: true,
-                    getFlag
+                    getFlag,
+                    displayHelp: () => {
+                      console.error(
+                        "Help display is not supported in MCP mode."
+                      );
+                    }
                   };
                   const handlerResult = await toolConfig.handler(handlerContext);
                   if (process.env["MCP_DEBUG"]) {
@@ -6444,7 +6510,12 @@ function generateMcpToolsFromArgParser(rootParser, options) {
                   parser: finalParser,
                   parentArgs: resolvedParentArgs,
                   isMcp: true,
-                  getFlag
+                  getFlag,
+                  displayHelp: () => {
+                    console.error(
+                      "Help display is not supported in MCP mode."
+                    );
+                  }
                 };
                 try {
                   handlerResponse = await handlerToCall(handlerContext);
@@ -7129,7 +7200,10 @@ Migration guide: https://github.com/alcyone-labs/arg-parser/blob/main/docs/MCP-M
               parentArgs: {},
               commandChain: [toolConfig.name],
               parser: this,
-              isMcp: true
+              isMcp: true,
+              displayHelp: () => {
+                console.error("Help display is not supported in MCP mode.");
+              }
             };
             const startTime = Date.now();
             const result = await toolConfig.handler(context);
@@ -26217,6 +26291,7 @@ export {
   ConfigPluginRegistry,
   DxtPathResolver,
   EnvConfigPlugin,
+  FlagInheritance,
   JsonConfigPlugin,
   Logger,
   OutputSchemaPatterns,
@@ -26225,6 +26300,7 @@ export {
   index$2 as UI,
   YamlConfigPlugin,
   absolutePath,
+  autoHelpHandler,
   convertFlagToJsonSchemaProperty,
   convertFlagsToJsonSchema,
   convertFlagsToZodSchema,