test: split the args.test.ts aggregation along source topology

[thymikee]

Summary

Stacked on #1100 (it edits the same file — GitHub will retarget this to main when #1100 merges).

AGENTS.md's refocused size rules apply the LOC tripwires to tests with no exemption and require test files to mirror source topology 1:1. args.test.ts violated both: a 2,503-line aggregation sitting in src/utils/__tests__ while everything it exercises lives in src/cli/parser. This splits it into six focused files, every test block moved verbatim — 142 tests before, 142 after, all passing:

File	Tests	Lines	Covers
src/cli/parser/__tests__/args-parse-interaction.test.ts	29	~335	parseArgs shapes: press/click/swipe/gesture/type/record/screenshot…
src/cli/parser/__tests__/args-parse-session.test.ts	41	~894	parseArgs shapes: session/daemon/device flags, passthrough, install/metro/connect/proxy/auth…
src/cli/parser/__tests__/args-validation.test.ts	17	~177	strict/compat modes, rejections, deterministic errors
src/cli/parser/__tests__/cli-help-topics.test.ts	15	~586	global usage + help topics
src/cli/parser/__tests__/cli-help-command-usage.test.ts	35	~367	per-command usage copy
src/utils/__tests__/command-schema-guards.test.ts	5	~158	schema/catalog/capability guards + the cli.ts dispatch-literal walk (oxc-parser helpers live here, beside command-schema.ts)

AGENTS.md testing-matrix and help-source pointers updated to the new paths — including the pre-existing stale src/utils/cli-help.ts / cli-flags.ts references (both actually live under src/cli/parser/). No other references to args.test.ts remain in the repo.

The win is primarily agent-context locality (no more whole-file reads to find one fixture) plus vitest file-level parallelism; the six files run in 1.5s wall with per-file test time of 10–60ms each.

Validation

All 142 relocated tests pass, and the full unit + smoke suites are green: 346 test files / 3211 tests, smoke 13/13, check:quick (oxlint + tsgo) clean, fallow audit vs origin/main clean. Split was done mechanically (verbatim block moves with per-file import pruning verified by noUnusedLocals + oxlint), so no assertion text changed.

Touched files: 8 (1 deleted, 6 created, AGENTS.md).

🤖 Generated with Claude Code

https://claude.ai/code/session_01FqeW8sA2ZnvnftdvpCqFMS

---

Generated by Claude Code

[github-actions]

Size Report

Metric	Base	Current	Diff
JS raw	1.5 MB	1.5 MB	0 B
JS gzip	491.3 kB	491.3 kB	0 B
npm tarball	590.3 kB	590.3 kB	0 B
npm unpacked	2.1 MB	2.1 MB	0 B

Startup median (7 runs, lower is better):

Scenario	Base	Current	Diff
CLI --version	26.9 ms	26.1 ms	-0.8 ms
CLI --help	51.4 ms	49.9 ms	-1.4 ms

Top changed chunks: no changes in the largest emitted chunks.

[thymikee]

CI is green now, but I found one actionable docs consistency miss before ready-for-human:

AGENTS.md still has stale CLI parser paths in a few adjacent sections:

• line 95: src/utils/cli-help.ts / src/utils/cli-flags.ts
• line 113: src/utils/cli-flags.ts
• line 262: src/utils/cli-help.ts
• line 280: src/utils/cli-help.ts / src/utils/cli-flags.ts

Those files do not exist on this branch; the actual paths are src/cli/parser/cli-help.ts and src/cli/parser/cli-flags.ts. The PR already updates two AGENTS references correctly, so this looks like the same cleanup just missed in nearby guidance. Once those are fixed, the split itself looks mechanically sound and checks are already green.

[thymikee]

Addressed directly in 8bcf1da: updated the remaining stale AGENTS.md references from src/utils/cli-help.ts / src/utils/cli-flags.ts to src/cli/parser/cli-help.ts / src/cli/parser/cli-flags.ts, and fixed the adjacent key-file entry from src/utils/args.ts to src/cli/parser/args.ts. Verified the stale-path grep is clean locally. Docs-only change; waiting for the restarted checks.

[github-actions]

PR Preview Action v1.8.1
Preview removed because the pull request was closed.
2026-07-04 19:46 UTC