feat: typed command results, batch 3 (clipboard, appstate) — Phase 2

[thymikee]

What

Phase 2 (typed results) batch 3: wire clipboard and appstate into the CommandResultMap spine as closed discriminated unions, grounded in the handlers' literal returns. Continues #913/#934.

command	source	result
clipboard	src/core/dispatch.ts handleClipboardCommand	union on action: read → { text }, write → { textLength, message }
appstate	src/daemon/handlers/session-state.ts handleAppStateCommand	union on platform: Apple (ios/macos) session state, or Android { package, activity }

Notable: handler-grounding caught a gap

The previous hand-written AppStateCommandResult mirror omitted the iOS-only device_udid / ios_simulator_device_set locators that the handler actually returns. The new closed contract includes them — a strictly more accurate public type.

Mechanics (same template as batches 1-2)

• New src/contracts/clipboard.ts and src/contracts/app-state.ts (moved out of the open client-types.ts mirror, dropping the DaemonResponseData index signature).
• CommandResultMap gains clipboard / appstate; client methods return CommandResult<'name'>.
• Public export names preserved (ClipboardCommandResult, AppStateCommandResult re-exported via client-types.ts → index.ts) — no API break.
• The parity test now pins all 12 migrated commands; the public-root export test gains clipboard/appstate samples.

Tighter type surfaced a latent test bug

Closing clipboard to a discriminated union exposed an unguarded .text/.textLength access in an Android integration test (previously masked by the Record index signature). Fixed with discriminant guards — exactly the kind of unsafe access the migration is meant to eliminate.

Verification

• tsc --noEmit exit 0
• oxfmt + oxlint --deny-warnings clean
• fallow audit --base origin/main clean
• vitest core/contracts/client/commands → 104 files / 791 tests pass
• Layering Guard grep empty

Remaining for Phase 2

keyboard (platform×action union — needs the Android keyboard-state types) is the next typed-results batch; wait/alert are genuinely open (wait also has an internal name-collision; alert's iOS path returns a generic Record) and will become CommandRequestResult in the mirror-cleanup PR. Then (b) the TypedError graft and (c) deleting the remaining client-types.ts result mirror.

[github-actions]

Size Report

Metric	Base	Current	Diff
JS raw	1.4 MB	1.4 MB	0 B
JS gzip	450.7 kB	450.7 kB	0 B
npm tarball	553.6 kB	553.9 kB	+281 B
npm unpacked	2.0 MB	2.0 MB	+1.3 kB

Startup median (7 runs, lower is better):

Scenario	Base	Current	Diff
CLI --version	26.9 ms	27.4 ms	+0.5 ms
CLI --help	47.3 ms	48.8 ms	+1.5 ms

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

[thymikee]

Reviewed current head 71a2f3c. I checked the #913/#934 typed-results context, the diff, the clipboard and appstate handler return literals, and the command routing traits. No actionable blockers found: public export names are preserved, clipboard is correctly modeled as a read/write discriminated union, appstate matches the Apple-session vs Android-state handler branches including iOS locators, and all 21 checks are green. Marking ready-for-human.

[github-actions]

PR Preview Action v1.8.1
Preview removed because the pull request was closed.
2026-06-29 17:08 UTC