fix(cli): honor -- when scanning argv for help

Review found a real regression in the pre-dispatch help interception: the
shared scanner did not know about the POSIX end-of-options marker, so
`taskless check -- -h` was read as a help request and printed usage instead
of scanning a path literally named `-h` — the escape hatch check.ts was
built to support. splitRawArguments now treats everything after `--` as a
positional and will not swallow `--` as the value of `-d`.

check.ts's extractPositionalPaths was the second copy of that rule (the
complete one). It now calls the shared scanner, passing its own value-taking
flag `--timeout`, and the root's onlyInitFlags scan — a third copy — goes
through the same scanner's flags.

Tests: unit coverage for the scanner and hasHelpFlag, plus a CLI case
asserting `check --json -- -h` still runs check. Verified the case fails
against the previous commit's build.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Jwc9FFroR3mTZ4hLiSkkX3

Author: theCodeDrift

packages/cli/src/commands/check.ts

@@ -4,6 +4,7 @@ import { defineCommand } from "citty";
 
 import { hasValeRules, runEngines } from "../rules/dispatch";
 import { assembleEngineConfigs } from "../rules/assemble";
+import { splitRawArguments } from "../util/argv";
 import { formatText } from "../util/format";
 import { ensureTasklessDirectory } from "../filesystem/directory";
 import { listRuleIds, planEngineDispatch } from "../rules/engines";
@@ -66,40 +67,13 @@ async function filterExistingPaths(
 }
 
 /**
- * Extract positional arguments from rawArgs. citty's rawArgs contains the
- * original argv for this subcommand, so we drop anything starting with `-`
- * and drop known flag values (e.g. `-d <value>`). Once `--` is seen, all
- * remaining arguments are treated as positional paths (conventional POSIX
- * end-of-options marker), which lets users pass paths that begin with `-`.
+ * Extract positional path arguments from rawArgs. The shared scanner knows the
+ * global value-taking flags and the POSIX `--` end-of-options marker (which is
+ * what lets a path beginning with `-` be scanned); `--timeout` is check's own
+ * value-taking flag, so it is named here rather than in the shared set.
  */
 function extractPositionalPaths(rawArguments: string[]): string[] {
-  const paths: string[] = [];
-  let afterDoubleDash = false;
-  for (let index = 0; index < rawArguments.length; index++) {
-    const argument = rawArguments[index]!;
-    if (afterDoubleDash) {
-      paths.push(argument);
-      continue;
-    }
-    if (argument === "--") {
-      afterDoubleDash = true;
-      continue;
-    }
-    if (argument.startsWith("-")) {
-      // Skip value for short/long flags that take a value
-      if (
-        (argument === "-d" ||
-          argument === "--dir" ||
-          argument === "--timeout") &&
-        index + 1 < rawArguments.length
-      ) {
-        index += 1;
-      }
-      continue;
-    }
-    paths.push(argument);
-  }
-  return paths;
+  return splitRawArguments(rawArguments, ["--timeout"]).positionals;
 }
 
 /** A runtime rule that will not run, with why (advisory). */

packages/cli/src/index.ts

@@ -15,7 +15,7 @@ import {
   shutdownTelemetry,
 } from "./telemetry";
 import { emitRunEvents, resolveCommandName, resolveCwd } from "./telemetry-run";
-import { hasHelpFlag, splitRawArguments } from "./util/argv";
+import { DIR_FLAGS, hasHelpFlag, splitRawArguments } from "./util/argv";
 import { showResolvedUsage } from "./util/help";
 import { CLIError } from "./util/cli-error";
 
@@ -67,23 +67,17 @@ const main = defineCommand({
     // Only take action when no positional args (i.e. no subcommand) were
     // provided. A value following `-d`/`--dir` is a flag value, not a
     // positional, so splitRawArguments skips it.
-    if (splitRawArguments(rawArgs).positionals.length > 0) {
+    const { positionals, flags } = splitRawArguments(rawArgs);
+    if (positionals.length > 0) {
       return;
     }
 
     // Only delegate to `init` when the only flags present are ones init
-    // also understands (`-d` / `--dir`). Version/json flags and any unknown
-    // flags should fall through to citty's default help instead of silently
-    // launching the wizard. (`--help`/`-h` never reach here — they are
-    // intercepted before dispatch below.)
-    const onlyInitFlags = rawArgs.every((argument, index) => {
-      if (!argument.startsWith("-")) {
-        const previous = rawArgs[index - 1];
-        return previous === "-d" || previous === "--dir";
-      }
-      if (argument === "-d" || argument === "--dir") return true;
-      return false;
-    });
+    // also understands (`-d` / `--dir`). Version/json flags, a bare `--`, and
+    // any unknown flags should fall through to citty's default help instead of
+    // silently launching the wizard. (`--help`/`-h` never reach here — they
+    // are intercepted before dispatch below.)
+    const onlyInitFlags = flags.every((flag) => DIR_FLAGS.has(flag));
     if (!onlyInitFlags) {
       await showUsage(cmd);
       return;

packages/cli/src/util/argv.ts

@@ -1,32 +1,66 @@
 /**
  * Raw-argv scanning shared by everything that has to answer "which tokens are
  * positionals?" — subcommand resolution for `--help`, the root command's
- * no-subcommand check, and telemetry's command name. One copy, because the
- * rule is subtle: `-d`/`--dir` take a value, so the token after one of them is
- * a flag value and NOT a positional (`taskless -d /tmp check` runs `check`,
- * not `/tmp`).
+ * no-subcommand check, `check`'s path arguments, and telemetry's command name.
+ * One copy, because the rules are subtle:
+ *
+ * - `-d`/`--dir` take a value, so the token after one of them is a flag value
+ *   and NOT a positional (`taskless -d /tmp check` runs `check`, not `/tmp`).
+ * - `--` is the POSIX end-of-options marker: every token after it is a
+ *   positional even if it starts with `-`, which is what lets `taskless check
+ *   -- -h` scan a path literally named `-h` instead of asking for help.
  */
 
-/** Flags that consume the following token as their value. */
-const VALUE_FLAGS = new Set(["-d", "--dir"]);
+/** Flags every command takes a value for. */
+export const DIR_FLAGS = new Set(["-d", "--dir"]);
+
+/** The POSIX end-of-options marker. */
+const END_OF_OPTIONS = "--";
 
 export interface SplitArguments {
-  /** Tokens that are not flags and not the value of a value-taking flag. */
+  /**
+   * Tokens that are not flags and not the value of a value-taking flag, plus
+   * everything after `--`.
+   */
   positionals: string[];
-  /** Tokens that start with `-`. Values consumed by them are not included. */
+  /**
+   * Option tokens, in order, including the `--` marker itself. Values consumed
+   * by a value-taking flag are not included.
+   */
   flags: string[];
 }
 
-/** Split raw argv into positionals and flags, skipping flag values. */
-export function splitRawArguments(rawArguments: string[]): SplitArguments {
+/**
+ * Split raw argv into positionals and flags, skipping flag values and honoring
+ * `--`. `valueFlags` names flags beyond `-d`/`--dir` that consume the next
+ * token (e.g. `check`'s `--timeout`).
+ */
+export function splitRawArguments(
+  rawArguments: string[],
+  valueFlags: readonly string[] = []
+): SplitArguments {
+  const consumesValue =
+    valueFlags.length > 0 ? new Set([...DIR_FLAGS, ...valueFlags]) : DIR_FLAGS;
   const positionals: string[] = [];
   const flags: string[] = [];
   for (let index = 0; index < rawArguments.length; index++) {
     const argument = rawArguments[index]!;
+    if (argument === END_OF_OPTIONS) {
+      flags.push(argument);
+      positionals.push(...rawArguments.slice(index + 1));
+      break;
+    }
     if (argument.startsWith("-")) {
       flags.push(argument);
-      // `--dir=<path>` carries its own value; `-d <path>` eats the next token.
-      if (VALUE_FLAGS.has(argument)) index++;
+      // `--dir=<path>` carries its own value; `-d <path>` eats the next token —
+      // unless that token is `--`, which ends the options rather than being one.
+      if (
+        consumesValue.has(argument) &&
+        rawArguments[index + 1] !== undefined &&
+        rawArguments[index + 1] !== END_OF_OPTIONS
+      ) {
+        index++;
+      }
       continue;
     }
     positionals.push(argument);
@@ -35,8 +69,9 @@ export function splitRawArguments(rawArguments: string[]): SplitArguments {
 }
 
 /**
- * True when argv asks for help. Scanned through `splitRawArguments` so a flag value
- * that happens to read like `-h` is not mistaken for a help request.
+ * True when argv asks for help. Scanned through `splitRawArguments` so neither
+ * a flag value nor a path after `--` that happens to read like `-h` is mistaken
+ * for a help request.
  */
 export function hasHelpFlag(rawArguments: string[]): boolean {
   const { flags } = splitRawArguments(rawArguments);

packages/cli/test/help-flag.test.ts

@@ -5,6 +5,8 @@ import { join, resolve } from "node:path";
 import { promisify } from "node:util";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 
+import { hasHelpFlag, splitRawArguments } from "../src/util/argv";
+
 const execFileAsync = promisify(execFile);
 const binPath = resolve(import.meta.dirname, "../dist/index.js");
 
@@ -70,6 +72,24 @@ describe("--help below the root", () => {
     expect(await readdir(temporaryDirectory)).toEqual([]);
   });
 
+  // `--` is the escape hatch `check` supports so a path beginning with `-` can
+  // still be scanned. Intercepting help before dispatch must not eat it.
+  it("does not read a path after -- as a help request", async () => {
+    const { stdout } = await execFileAsync("node", [
+      binPath,
+      "check",
+      "-d",
+      temporaryDirectory,
+      "--json",
+      "--",
+      "-h",
+    ]);
+
+    expect(stdout).not.toContain("USAGE");
+    const parsed = JSON.parse(stdout.trim()) as { success: boolean };
+    expect(parsed.success).toBe(true);
+  });
+
   it("leaves the root's --help unchanged", async () => {
     const { stdout } = await execFileAsync("node", [binPath, "--help"]);
 
@@ -80,6 +100,50 @@ describe("--help below the root", () => {
   });
 });
 
+describe("splitRawArguments", () => {
+  it("treats the token after -d/--dir as a value, not a positional", () => {
+    expect(splitRawArguments(["-d", "/tmp", "check"])).toEqual({
+      positionals: ["check"],
+      flags: ["-d"],
+    });
+  });
+
+  it("treats everything after -- as a positional", () => {
+    expect(splitRawArguments(["check", "--", "-h", "--json"])).toEqual({
+      positionals: ["check", "-h", "--json"],
+      flags: ["--"],
+    });
+  });
+
+  it("does not swallow -- as the value of -d", () => {
+    expect(splitRawArguments(["-d", "--", "src"])).toEqual({
+      positionals: ["src"],
+      flags: ["-d", "--"],
+    });
+  });
+
+  it("accepts command-specific value flags", () => {
+    expect(
+      splitRawArguments(["check", "--timeout", "5", "src"], ["--timeout"])
+        .positionals
+    ).toEqual(["check", "src"]);
+  });
+});
+
+describe("hasHelpFlag", () => {
+  it.each([
+    [["check", "--help"], true],
+    [["auth", "login", "-h"], true],
+    [["-d", "/tmp", "check", "--help"], true],
+    [["check"], false],
+    // A path after `--`, and a directory that reads like a flag, are values.
+    [["check", "--", "-h"], false],
+    [["-d", "-h", "check"], false],
+  ])("resolves %j to %s", (argv, expected) => {
+    expect(hasHelpFlag(argv)).toBe(expected);
+  });
+});
+
 // REGRESSION GUARD — DO NOT "SIMPLIFY" THE HELP PATH TO citty's runMain.
 //
 // runMain's help branch calls process.exit(0), which does not run `finally`