@alcyone-labs/arg-parser 2.12.2 → 2.13.0

package/dist/index.mjs

@@ -1588,6 +1588,9 @@ const zodFlagSchema = z.object({
   ),
   setWorkingDirectory: z.boolean().optional().describe(
     "If true, this flag's value becomes the effective working directory for file operations."
+  ),
+  positional: z.number().int().positive("Positional index must be a positive integer (1, 2, 3...)").optional().describe(
+    "If set, this flag captures the Nth trailing positional argument (1-indexed). Multiple flags can have different positional values to capture multiple trailing args in order."
   )
 }).transform((obj) => {
   const newObj = { ...obj };
@@ -4430,7 +4433,11 @@ class ArgParserBase {
       const autoDiscoveredEnvFile = this.#configurationManager.discoverEnvFile(basePath);
       if (autoDiscoveredEnvFile) {
         console.warn(`Auto-discovered env file: ${autoDiscoveredEnvFile}`);
-        dotenv.config({ path: autoDiscoveredEnvFile, quiet: true });
+        dotenv.config({
+          path: autoDiscoveredEnvFile,
+          quiet: true,
+          override: true
+        });
         try {
           const { finalParser: envFinalParser, parserChain: envParserChain } = this.#_identifyCommandChainAndParsers(
             processArgs,
@@ -5175,6 +5182,31 @@ class ArgParserBase {
         }
       }
     }
+    const trailingArgs = [];
+    for (let i = 0; i < args.length; i++) {
+      if (!consumedIndices.has(i)) {
+        const arg = args[i];
+        if (!arg.startsWith("-")) {
+          trailingArgs.push({ index: i, value: arg });
+        }
+      }
+    }
+    const positionalFlags = flags.filter(
+      (f) => typeof f["positional"] === "number" && f["positional"] > 0
+    ).sort(
+      (a, b) => a["positional"] - b["positional"]
+    );
+    for (const posFlag of positionalFlags) {
+      const posIndex = posFlag["positional"] - 1;
+      const existingValue = output[posFlag["name"]];
+      const hasExistingValue = posFlag["allowMultiple"] ? Array.isArray(existingValue) && existingValue.length > 0 : existingValue !== void 0;
+      if (hasExistingValue) continue;
+      if (posIndex < trailingArgs.length) {
+        const trailing = trailingArgs[posIndex];
+        await this._addToOutput(posFlag, trailing.value, output, options);
+        consumedIndices.add(trailing.index);
+      }
+    }
     let firstUnconsumedIndex = args.length;
     for (let i = 0; i < args.length; i++) {
       if (!consumedIndices.has(i)) {
@@ -5208,6 +5240,22 @@ class ArgParserBase {
 `;
     }
     const indent = (level = 1) => "  ".repeat(level);
+    const positionalFlagsForUsage = this.#flagManager.flags.filter(
+      (f) => typeof f["positional"] === "number" && f["positional"] > 0
+    ).sort(
+      (a, b) => a["positional"] - b["positional"]
+    );
+    if (positionalFlagsForUsage.length > 0) {
+      const commandName = this.#subCommandName || this.#appCommandName || this.#appName;
+      const posArgs = positionalFlagsForUsage.map((f) => {
+        const isMandatory = typeof f["mandatory"] === "function" ? true : f["mandatory"];
+        const argName = f["valueHint"] || f["name"].toUpperCase();
+        return isMandatory ? `<${argName}>` : `[${argName}]`;
+      }).join(" ");
+      help += `${cyan("Usage:")} ${commandName} [OPTIONS] ${posArgs}
+
+`;
+    }
     if (this.#subCommands.size > 0) {
       help += `${cyan("Available sub-commands:")}
 `;
@@ -5216,7 +5264,12 @@ class ArgParserBase {
         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(actualSubParserInstance.#description || "")}`;
+        let subHelp = `${indent()}${green(name)}`;
+        const subDescription = actualSubParserInstance.#description;
+        if (subDescription) {
+          subHelp += `
+${indent(2)}${white(subDescription)}`;
+        }
         const flagsFromSubManager = actualSubParserInstance && actualSubParserInstance.#flagManager ? actualSubParserInstance.#flagManager.flags : void 0;
         const subFlags = (flagsFromSubManager || []).filter(
           (f) => f["name"] !== "help"
@@ -5339,6 +5392,9 @@ ${cyan("Flags:")}
             `Allowed values: ${flag["enum"].map((v) => `'${v}'`).join(", ")}`
           );
         }
+        if (typeof flag["positional"] === "number" && flag["positional"] > 0) {
+          metaLines.push(`Positional argument #${flag["positional"]}`);
+        }
         const maxOptionLength = Math.max(
           ...localFlags.map(
             (f) => f["options"].join(", ").length