@alcyone-labs/arg-parser 2.10.1 → 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);
@@ -9301,12 +9375,61 @@ class List extends Component {
     }
   }
 }
+function stripAnsi(str) {
+  return str.replace(/[\u001b\u009b][[()#;?]*(?:[0-9]{1,4}(?:;[0-9]{0,4})*)?[0-9A-ORZcf-nqry=><]/g, "");
+}
+function visualLength(str) {
+  return stripAnsi(str).length;
+}
+function wrapText(text, width) {
+  if (width <= 0) return [text];
+  const result = [];
+  const lines = text.split("\n");
+  for (const line of lines) {
+    if (visualLength(line) <= width) {
+      result.push(line);
+      continue;
+    }
+    let currentLine = "";
+    let currentVisibleLength = 0;
+    let activeAnsiCodes = [];
+    const tokenRegex = /(\u001b\[(?:\d{1,3}(?:;\d{1,3})*)?[mK])|([\s\S])/g;
+    let match;
+    while ((match = tokenRegex.exec(line)) !== null) {
+      const ansiCode = match[1];
+      const char2 = match[2];
+      if (ansiCode) {
+        currentLine += ansiCode;
+        if (ansiCode === "\x1B[0m") {
+          activeAnsiCodes = [];
+        } else if (ansiCode.endsWith("m")) {
+          activeAnsiCodes.push(ansiCode);
+        }
+      } else if (char2) {
+        if (currentVisibleLength >= width) {
+          result.push(currentLine + "\x1B[0m");
+          currentLine = activeAnsiCodes.join("") + char2;
+          currentVisibleLength = 1;
+        } else {
+          currentLine += char2;
+          currentVisibleLength++;
+        }
+      }
+    }
+    if (currentLine.length > 0) {
+      result.push(currentLine + "\x1B[0m");
+    }
+  }
+  return result;
+}
 class ScrollArea extends Component {
   constructor(config) {
     super(config);
     this.contentLines = [];
     this.scrollOffset = 0;
+    this.wrapText = false;
     this.content = config.content;
+    this.wrapText = !!config.wrapText;
     this.updateContentLines();
   }
   setContent(content) {
@@ -9314,8 +9437,18 @@ class ScrollArea extends Component {
     this.scrollOffset = 0;
     this.updateContentLines();
   }
+  resize(x, y, width, height) {
+    super.resize(x, y, width, height);
+    if (this.wrapText) {
+      this.updateContentLines();
+    }
+  }
   updateContentLines() {
-    this.contentLines = this.content.split("\n");
+    if (this.wrapText && this.width > 0) {
+      this.contentLines = wrapText(this.content, Math.max(1, this.width - 2));
+    } else {
+      this.contentLines = this.content.split("\n");
+    }
   }
   render() {
     const lines = [];
@@ -9330,7 +9463,6 @@ class ScrollArea extends Component {
       const maxTop = this.height - scrollbarHeight;
       scrollbarTop = Math.floor(scrollPercent * maxTop);
     }
-    const stripAnsi = (str) => str.replace(/[\u001b\u009b][[()#;?]*(?:[0-9]{1,4}(?:;[0-9]{0,4})*)?[0-9A-ORZcf-nqry=><]/g, "");
     for (let i = 0; i < this.height; i++) {
       const lineContent = visibleLines[i] || "";
       let prefix = "";
@@ -26159,6 +26291,7 @@ export {
   ConfigPluginRegistry,
   DxtPathResolver,
   EnvConfigPlugin,
+  FlagInheritance,
   JsonConfigPlugin,
   Logger,
   OutputSchemaPatterns,
@@ -26167,6 +26300,7 @@ export {
   index$2 as UI,
   YamlConfigPlugin,
   absolutePath,
+  autoHelpHandler,
   convertFlagToJsonSchemaProperty,
   convertFlagsToJsonSchema,
   convertFlagsToZodSchema,