diff --git a/docs/packages/cli.mdx b/docs/packages/cli.mdx index befb985852..62faa4eaa0 100644 --- a/docs/packages/cli.mdx +++ b/docs/packages/cli.mdx @@ -1559,7 +1559,7 @@ npx hyperframes compare ./variant-a ./variant-b --labels "A,B" | `--labels` | Comma-separated labels, one per input path | | `--out` | Output path (default `./compare.png`) | | `--cols` | Grid columns (default: a sqrt heuristic, max 4) | -| `--timeout` | Render-ready timeout per variant (default 5000 ms) | +| `--timeout` | Render-ready timeout per variant in ms; must be a positive integer (default 5000) | | `--json` | Machine-readable results | `grade-compare` does the same for colour: candidate grades or LUTs applied to diff --git a/packages/cli/src/cli.agentMode.test.ts b/packages/cli/src/cli.agentMode.test.ts index 2a3a1cc6bd..25c832e4ee 100644 --- a/packages/cli/src/cli.agentMode.test.ts +++ b/packages/cli/src/cli.agentMode.test.ts @@ -231,6 +231,8 @@ describe("agent-mode contract", () => { ["snapshot --frames -3", "--frames must be a positive integer"], ["compare a.html", "need 2+ paths"], ["compare a.html b.html --cols 0", "--cols must be"], + ["compare a.html b.html --timeout abc", "--timeout must be a positive integer"], + ["compare a.html b.html --timeout -1", "--timeout must be a positive integer"], ["grade-compare --for frame.png", "Exactly one of --grades or --luts"], ["check --range 5,1", "Invalid --range"], ["normalize-audio --target music --tolerance=-1", "--tolerance must be"], diff --git a/packages/cli/src/commands/compare.test.ts b/packages/cli/src/commands/compare.test.ts index 3e88e23ed6..fc19b3135a 100644 --- a/packages/cli/src/commands/compare.test.ts +++ b/packages/cli/src/commands/compare.test.ts @@ -44,6 +44,22 @@ describe("parseCompareArgs", () => { // tests; asserting them literally here made this a POSIX-only test.) expect(parsed.variants.map((v) => v.label)).toEqual(["warm", "cool", "hero.alt"]); }); + + it("uses the default timeout when --timeout is omitted", () => { + expect(parseCompareArgs({ _: ["variant-a", "variant-b"] }, "/tmp").timeoutMs).toBe(5000); + }); + + it("accepts a positive integer --timeout", () => { + expect( + parseCompareArgs({ _: ["variant-a", "variant-b"], timeout: "1000" }, "/tmp").timeoutMs, + ).toBe(1000); + }); + + it.each(["abc", "-1", "0", "2.5"])("rejects --timeout %s", (timeout) => { + expect(() => parseCompareArgs({ _: ["variant-a", "variant-b"], timeout }, "/tmp")).toThrow( + "--timeout must be a positive integer", + ); + }); }); describe("capCompareVariants", () => { diff --git a/packages/cli/src/commands/compare.ts b/packages/cli/src/commands/compare.ts index 9bb5457dd6..a37f945164 100644 --- a/packages/cli/src/commands/compare.ts +++ b/packages/cli/src/commands/compare.ts @@ -127,6 +127,16 @@ function parseColumns(value: unknown): number | undefined { return parsed; } +function parseTimeoutMs(value: unknown): number { + const raw = readOptionalString(value); + if (!raw) return DEFAULT_RENDER_READY_TIMEOUT_MS; + const parsed = Number(raw); + if (!Number.isInteger(parsed) || parsed < 1) { + throw new CliUsageError("--timeout must be a positive integer number of milliseconds"); + } + return parsed; +} + function defaultCompareCols(cellCount: number): number { return Math.max(1, Math.min(MAX_COLUMNS, Math.ceil(Math.sqrt(cellCount)))); } @@ -161,9 +171,7 @@ export function parseCompareArgs( atSeconds: parseAtSeconds(args.at), cols: parseColumns(args.cols), json: args.json === true, - timeoutMs: - Number.parseInt(readOptionalString(args.timeout) ?? "", 10) || - DEFAULT_RENDER_READY_TIMEOUT_MS, + timeoutMs: parseTimeoutMs(args.timeout), }; }