@alcyone-labs/arg-parser 2.8.0 → 2.8.2

package/dist/index.mjs

@@ -1073,6 +1073,7 @@ const zodFlagSchema = z.object({
     "Allow passing the same flag multiple times, e.g., `-f val1 -f val2` results in an array."
   ),
   description: z.union([z.string(), z.array(z.string())]).optional().describe("Textual description for help messages."),
+  valueHint: z.string().optional().describe("Hint/example value shown in help and examples."),
   options: z.array(z.string().min(1)).min(1, "Flag must have at least one option (e.g., ['-f', '--flag'])").describe("Array of option strings, e.g., ['-f', '--flag']."),
   defaultValue: z.any().optional().describe("Default value if the flag is not provided."),
   type: z.union([
@@ -4250,6 +4251,35 @@ ${cyan("Flags:")}
           typeName = flag["type"];
         }
         metaLines.push(`Type: ${typeName}`);
+        {
+          let isRepeatable = false;
+          try {
+            if (typeof flag["type"] === "function" && flag["type"].name === "Array") {
+              isRepeatable = true;
+            }
+            const anyType = flag["type"];
+            if (anyType && typeof anyType === "object" && anyType._def && anyType._def.typeName === "ZodArray") {
+              isRepeatable = true;
+            }
+            if (flag["allowMultiple"]) isRepeatable = true;
+          } catch {
+          }
+          const primaryOpt = flag["options"].find((o) => o.startsWith("--")) ?? flag["options"][0];
+          const valueHint = flag["valueHint"];
+          if (!flag["flagOnly"]) {
+            if (isRepeatable) {
+              metaLines.push("Multiple values allowed (repeat flag)");
+              const v1 = valueHint ?? "value1";
+              const v2 = valueHint ?? "value2";
+              metaLines.push(
+                `Example: ${primaryOpt} ${v1} ${primaryOpt} ${v2}`
+              );
+            } else {
+              const v = valueHint ?? "value";
+              metaLines.push(`Example: ${primaryOpt} ${v}`);
+            }
+          }
+        }
         if (typeDetails.length > 0) {
           metaLines.push(...typeDetails);
         }