fix(cli): drop the removed durationMs positional from swipe help

[thymikee]

Summary

agent-device swipe --help still advertised a trailing [durationMs] positional that #1393 removed from runtime acceptance, so following the help text produces the INVALID_ARGS migration-hint rejection instead of a working command.

The stale text is generated from the swipe command's help schema — positionalArgs: ['x1', 'y1', 'x2', 'y2', 'durationMs?'] in src/commands/interaction/index.ts — which both cli-help.ts renders into the usage line and assertCommandPositionalArity (src/cli-schema/command-schema.ts) uses to bound how many positionals the parser accepts. Simply deleting 'durationMs?' from that array would also tighten the parser-level arity check, causing a 5th positional to be rejected there with a generic "accepts at most 4 positional argument(s)" error — before the richer, migration-aware rejection in packages/contracts/src/gesture-normalization.ts (assertGestureArity / migrateRetiredSwipeDuration) ever runs.

Fix: drop 'durationMs?' from positionalArgs (fixes the help text) and set allowsExtraPositionals: true on the swipe schema so the generic parser-level arity check steps aside and swipePayloadFromPositionals remains the sole arity gate, preserving the exact runtime migration-hint error.

New first line of swipe --help:

agent-device swipe <x1> <y1> <x2> <y2> [--count <n>] [--pause-ms <ms>] [--pattern one-way|ping-pong]

Other commands checked for the same drift (grepped the gesture-normalization.ts retired migration table for every command that lost a positional in #1393):

• gesture pan / gesture transform — unaffected, durationMs is still a valid optional positional for these.
• gesture fling (lost durationMs), gesture swipe (lost durationMs), gesture rotate (lost velocity) — all render through the single umbrella gesture --help description in src/commands/interaction/index.ts, which already omits the retired positionals for each subcommand (verified live). No drift found.

No pinned test assertions needed updating — cli-help-topics.test.ts and cli-help-command-usage.test.ts only assert /swipe <x1> <y1> <x2> <y2>/ (unanchored, still matches) and don't pin the removed [durationMs] segment.

Gate results

• pnpm typecheck — pass
• pnpm lint — pass
• pnpm format:check — pass (no changes needed)
• npx vitest run src/cli — 15 files / 214 tests pass
• npx vitest run src/replay/__tests__/script.test.ts packages/contracts/src/gesture-normalization.test.ts (runtime migration-message coverage) — 2 files / 55 tests pass
• npx fallow audit --base origin/main — 0 issues
• Live check: node --experimental-strip-types src/bin.ts swipe --help shows the corrected usage; swipe 197 650 197 300 300 still throws the unchanged INVALID_ARGS migration-hint error.

Test plan

• pnpm typecheck
• pnpm lint
• pnpm format:check
• npx vitest run src/cli
• npx fallow audit --base origin/main
• Manually confirmed swipe --help and the runtime rejection message

[github-actions]

Size Report

Metric	Base	Current	Diff
JS raw	1.92 MB	1.92 MB	+12 B
JS gzip	614.6 kB	614.6 kB	-1 B
npm tarball	732.6 kB	732.6 kB	-1 B
npm unpacked	2.57 MB	2.57 MB	+12 B

Startup median (7 runs, lower is better):

Scenario	Base	Current	Diff
CLI --version	26.1 ms	26.1 ms	-0.0 ms
CLI --help	55.8 ms	55.5 ms	-0.2 ms

Top changed chunks:

Chunk	Raw diff	Gzip diff
dist/src/registry.js	+12 B	-1 B

[thymikee]

Implementation direction is correct: the help schema now advertises only the four supported swipe coordinates, while allowsExtraPositionals intentionally lets legacy five-position argv reach the canonical gesture-normalization boundary and retain its migration-aware INVALID_ARGS error.

One test gap blocks readiness: the current tests are vacuous for this regression. They still pass if [durationMs] is restored, and they do not prove that omitting allowsExtraPositionals would replace the migration hint with the generic schema arity error. Please add CLI-level coverage that (1) pins usageForCommand('swipe') without [durationMs], and (2) runs parsing plus the swipe CLI reader for a fifth positional and asserts the existing migration-hint error rather than the generic ‘at most 4 positionals’ rejection. Then rerun the focused CLI/gesture tests. No ready-for-human until that regression is pinned.

[github-actions]

PR Preview Action v1.8.1
Preview removed because the pull request was closed.
2026-08-01 05:45 UTC