fix(scripts): normalize agent-batch help exits (#3068)

Co-authored-by: Steven Enamakel <enamakel@tinyhumans.ai>

scripts/agent-batch/__tests__/cli.test.mjs

@@ -124,3 +124,18 @@ test("status.mjs renders a markdown table from a fixture (no gh needed)", () =>
   // a03 has no PR in the fixture — must still appear with placeholders.
   assert.match(r.stdout, /\| a03 \|.*\| — \| — \| no pr \|/i);
 });
+
+test("direct agent-batch subcommands print help with exit 0", () => {
+  for (const [script, usage] of [
+    [VALIDATE, /usage: validate\.mjs <spec\.json>/],
+    [OVERLAP, /usage: overlap\.mjs <spec\.json>/],
+    [STATUS, /usage: status\.mjs <spec\.json> \[--post\] \[--fixture <file>\]/],
+  ]) {
+    for (const flag of ["--help", "-h", "-?"]) {
+      const r = run(script, [flag]);
+      assert.strictEqual(r.status, 0, r.stderr);
+      assert.match(r.stdout, usage);
+      assert.strictEqual(r.stderr, "");
+    }
+  }
+});

scripts/agent-batch/lib.mjs

@@ -219,7 +219,7 @@ function comparePaths(p1, p2) {
 }
 
 // CLI helper: parse argv after the script name and return { positional, flags }.
-// Recognizes `--flag` and `--flag=value` and `--flag value`.
+// Recognizes `--flag`, `--flag=value`, `--flag value`, and short help flags.
 export function parseArgs(argv) {
   const positional = [];
   const flags = {};
@@ -239,6 +239,8 @@ export function parseArgs(argv) {
           i++;
         }
       }
+    } else if (a === "-h" || a === "-?") {
+      flags[a.slice(1)] = true;
     } else {
       positional.push(a);
     }

scripts/agent-batch/overlap.mjs

@@ -11,11 +11,19 @@ import {
   parseArgs,
 } from "./lib.mjs";
 
+function usage() {
+  return "usage: overlap.mjs <spec.json>";
+}
+
 function main() {
-  const { positional } = parseArgs(process.argv.slice(2));
+  const { positional, flags } = parseArgs(process.argv.slice(2));
+  if (flags.help || flags.h || flags["?"]) {
+    process.stdout.write(`${usage()}\n`);
+    process.exit(0);
+  }
   const specPath = positional[0];
   if (!specPath) {
-    process.stderr.write("usage: overlap.mjs <spec.json>\n");
+    process.stderr.write(`${usage()}\n`);
     process.exit(2);
   }
   let spec;

scripts/agent-batch/status.mjs

@@ -18,6 +18,10 @@ import { loadSpec, validateSpec, SpecError, parseArgs } from "./lib.mjs";
 
 const COMMENT_MARKER = (id) => `<!-- batch:${id} -->`;
 
+function usage() {
+  return "usage: status.mjs <spec.json> [--post] [--fixture <file>]";
+}
+
 function ciCell(rollup) {
   if (rollup === "SUCCESS") return "green";
   if (rollup === "FAILURE") return "failing";
@@ -186,11 +190,13 @@ function postOrUpdateTrackingComment(spec, body) {
 
 function main() {
   const { positional, flags } = parseArgs(process.argv.slice(2));
+  if (flags.help || flags.h || flags["?"]) {
+    process.stdout.write(`${usage()}\n`);
+    process.exit(0);
+  }
   const specPath = positional[0];
   if (!specPath) {
-    process.stderr.write(
-      "usage: status.mjs <spec.json> [--post] [--fixture <file>]\n",
-    );
+    process.stderr.write(`${usage()}\n`);
     process.exit(2);
   }
   let spec;

scripts/agent-batch/validate.mjs

@@ -6,11 +6,19 @@
 
 import { loadSpec, validateSpec, SpecError, parseArgs } from "./lib.mjs";
 
+function usage() {
+  return "usage: validate.mjs <spec.json>";
+}
+
 function main() {
-  const { positional } = parseArgs(process.argv.slice(2));
+  const { positional, flags } = parseArgs(process.argv.slice(2));
+  if (flags.help || flags.h || flags["?"]) {
+    process.stdout.write(`${usage()}\n`);
+    process.exit(0);
+  }
   const specPath = positional[0];
   if (!specPath) {
-    process.stderr.write("usage: validate.mjs <spec.json>\n");
+    process.stderr.write(`${usage()}\n`);
     process.exit(2);
   }
   try {