fix(arg-parser): take the arguments as stdin text, and block a heredoc that closes early

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

lib/parsers/arg-parser.mjs

@@ -3,7 +3,14 @@
 //
 // Each command has its own valid-flag set; passing flags from another command
 // produces an `unknown_flags` array but does not error — the caller decides.
+//
+// The commands hand $ARGUMENTS to the CLI as stdin text through a quoted
+// heredoc (`--stdin`), never as shell words, so nothing in the arguments is
+// expanded: no `~`, no `$VAR` or `$HOME`, no glob, no command substitution,
+// and `;` is an ordinary character. Write a path out in full; `~/x` stays the
+// three characters `~/x`. Quoting is the parser's own (see `tokenize`).
 
+import { readFileSync } from 'node:fs';
 import { isMain } from '../util/is-main.mjs';
 
 const FLAG_SCHEMA = {
@@ -54,9 +61,14 @@ const FLAG_SCHEMA = {
  *   positional: string[],
  *   unknown: string[],
  *   errors: Array<{code: string, message: string}>,
+ *   tail: string,
  * }}
+ *   `tail` is the raw text after the first token, trimmed, with one balanced
+ *   quote pair around the whole of it removed ('' when there is none): a
+ *   label read whole, with its own spaces and apostrophes.
  */
 export function parseArgs(argString, command) {
+  const tail = tailOf(argString);
   const schema = FLAG_SCHEMA[command];
   if (!schema) {
     return {
@@ -65,10 +77,11 @@ export function parseArgs(argString, command) {
       positional: [],
       unknown: [],
       errors: [{ code: 'ARG_UNKNOWN_COMMAND', message: `Unknown command: ${command}` }],
+      tail,
     };
   }
 
-  const tokens = tokenize(argString);
+  const tokens = tokenize(argString).map((t) => t.value);
   const flags = {};
   const positional = [];
   const unknown = [];
@@ -115,22 +128,61 @@ export function parseArgs(argString, command) {
     unknown.push(tok);
   }
 
-  return { command, flags, positional, unknown, errors };
+  return { command, flags, positional, unknown, errors, tail };
 }
 
-function tokenize(s) {
-  if (typeof s !== 'string') return [];
-  const trimmed = s.trim();
-  if (trimmed === '') return [];
+const isSpace = (c) => /\s/.test(c);
+
+/**
+ * Split argument text into words. Words are separated by whitespace. A word
+ * that starts with `'` or `"` and has the same quote again at the end of a
+ * later word is a balanced pair: the pair groups the words between them into
+ * one value and is removed. A quote with no such partner is a literal
+ * character (`user's` stays `user's`). Nothing is expanded.
+ *
+ * @param {string} text
+ * @returns {Array<{ value: string, start: number, end: number }>}
+ *   `start` / `end` are offsets into `text` (end exclusive), quotes included.
+ */
+export function tokenize(text) {
+  if (typeof text !== 'string') return [];
   const out = [];
-  const re = /"([^"]*)"|'([^']*)'|(\S+)/g;
-  let m;
-  while ((m = re.exec(trimmed)) !== null) {
-    out.push(m[1] !== undefined ? m[1] : m[2] !== undefined ? m[2] : m[3]);
+  const n = text.length;
+  let i = 0;
+  while (i < n) {
+    while (i < n && isSpace(text[i])) i++;
+    if (i >= n) break;
+    const start = i;
+    const q = text[i];
+    if (q === '"' || q === "'") {
+      let j = text.indexOf(q, i + 1);
+      while (j !== -1 && j + 1 < n && !isSpace(text[j + 1])) j = text.indexOf(q, j + 1);
+      if (j !== -1) {
+        out.push({ value: text.slice(i + 1, j), start, end: j + 1 });
+        i = j + 1;
+        continue;
+      }
+    }
+    while (i < n && !isSpace(text[i])) i++;
+    out.push({ value: text.slice(start, i), start, end: i });
   }
   return out;
 }
 
+// The raw text after the first token, trimmed; one balanced quote pair that
+// encloses the whole of it is removed. '' when there is no second token.
+function tailOf(text) {
+  const tokens = tokenize(text);
+  if (tokens.length === 0) return '';
+  const rest = text.slice(tokens[0].end).trim();
+  const inner = tokenize(rest);
+  if (inner.length === 1 && inner[0].start === 0 && inner[0].end === rest.length
+      && (rest[0] === '"' || rest[0] === "'") && inner[0].value.length === rest.length - 2) {
+    return inner[0].value;
+  }
+  return rest;
+}
+
 export { FLAG_SCHEMA };
 
 // Flags a command cannot run without, and its usage line. The CLI below emits
@@ -144,16 +196,41 @@ const REQUIRED = {
   },
 };
 
-// CLI: node lib/parsers/arg-parser.mjs --command <command> -- $ARGUMENTS
-//   stdout: the parse result as JSON. exit 0, or exit 1 with each error as
-//   "Error: <message>" plus the usage line on stderr.
+// CLI: node lib/parsers/arg-parser.mjs --command <command> --stdin <<'VOYAGE_ARGS_EOF_7F3C9E'
+//      $ARGUMENTS
+//      VOYAGE_ARGS_EOF_7F3C9E
+//   reads the whole stdin as the argument text (one trailing newline
+//   removed). The quoted heredoc keeps the shell from expanding anything; the
+//   Bash guard (hooks/scripts/pre-bash-executor.mjs, args-heredoc-closed-early)
+//   refuses a command in which that heredoc would close early.
+// CLI: node lib/parsers/arg-parser.mjs --command <command> -- <word>...
+//   the older argv form, kept: the words after `--` are the arguments.
+//   stdout: the parse result as JSON (with `tail`). exit 0, or exit 1 with
+//   each error as "Error: <message>" plus the usage line on stderr.
 if (isMain(import.meta.url)) {
   const argv = process.argv.slice(2);
   const ci = argv.indexOf('--command');
   const command = ci >= 0 ? argv[ci + 1] : undefined;
   const dd = argv.indexOf('--');
-  const rest = dd >= 0 ? argv.slice(dd + 1) : [];
-  const r = parseArgs(rest.map((t) => (/\s/.test(t) ? `"${t}"` : t)).join(' '), command);
+  // `--stdin` counts only before `--`: after it, it is an argument word.
+  const options = dd >= 0 ? argv.slice(0, dd) : argv;
+  let r;
+  if (options.includes('--stdin')) {
+    let text = '';
+    let readError = null;
+    try {
+      text = readFileSync(0, 'utf8');
+    } catch (e) {
+      readError = e;
+    }
+    r = parseArgs(text.replace(/\r?\n$/, ''), command);
+    if (readError) {
+      r.errors.push({ code: 'ARG_STDIN_UNREADABLE', message: `could not read the arguments from stdin (${readError.code || readError.message})` });
+    }
+  } else {
+    const rest = dd >= 0 ? argv.slice(dd + 1) : [];
+    r = parseArgs(rest.map((t) => (/\s/.test(t) ? `"${t}"` : t)).join(' '), command);
+  }
   const req = REQUIRED[command];
   if (req) {
     for (const [flag, metavar] of req.flags) {