Skip to content

Commit 71a2f3c

Browse files
committed
feat: typed command results, batch 3 (clipboard, appstate) — Phase 2
Wire two more commands into the CommandResultMap spine as closed shapes, grounded in the handlers' literal returns: - clipboard (src/core/dispatch.ts handleClipboardCommand) -> a discriminated union on `action`: read => { text }, write => { textLength, message }. - appstate (src/daemon/handlers/session-state.ts handleAppStateCommand) -> a discriminated union on `platform`: Apple (ios/macos) session state — now including the iOS-only device_udid / ios_simulator_device_set locators the previous hand-written mirror OMITTED — or Android package/activity. Both result types move from the open client-types.ts mirror (DaemonResponseData & {…}) into new src/contracts/{clipboard,app-state}.ts and are wired through CommandResult<'clipboard'> / CommandResult<'appstate'>. Public export names are preserved (re-exported via client-types.ts -> index.ts), so no API break. Tightening clipboard to a closed union surfaced an unguarded .text/.textLength access in an Android integration test (previously masked by the Record index signature); fixed with discriminant guards. The parity test now pins all 12 migrated commands; the public-root export test gains clipboard/appstate samples. Verified: tsc --noEmit, oxfmt + oxlint --deny-warnings, fallow audit clean, Layering Guard empty, 791 tests across core/contracts/client/commands pass.
1 parent e9975e1 commit 71a2f3c

8 files changed

Lines changed: 98 additions & 30 deletions

File tree

‎src/__tests__/contracts-schema-public.test.ts‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,8 +4,10 @@ import fs from 'node:fs';
44
import path from 'node:path';
55
import {
66
AppError,
7+
type AppStateCommandResult,
78
type BackCommandResult,
89
type BootCommandResult,
10+
type ClipboardCommandResult,
911
type CommandResult,
1012
type RotateCommandResult,
1113
type ShutdownCommandResult,
@@ -142,11 +144,30 @@ test('public root exports typed command result contracts', () => {
142144
} satisfies RotateCommandResult;
143145
const rotateFromMap: CommandResult<'rotate'> = rotate;
144146

147+
const clipboard = {
148+
action: 'write',
149+
textLength: 11,
150+
message: 'Clipboard updated',
151+
} satisfies ClipboardCommandResult;
152+
const clipboardFromMap: CommandResult<'clipboard'> = clipboard;
153+
154+
const appstate = {
155+
platform: 'android',
156+
package: 'com.example.demo',
157+
activity: 'com.example.demo.MainActivity',
158+
} satisfies AppStateCommandResult;
159+
const appstateFromMap: CommandResult<'appstate'> = appstate;
160+
145161
assert.equal(bootFromMap.booted, true);
146162
assert.equal(shutdownFromMap.shutdown.success, true);
147163
assert.equal(viewportFromMap.width, 390);
148164
assert.equal(backFromMap.mode, 'in-app');
149165
assert.equal(rotateFromMap.orientation, 'portrait');
166+
assert.equal(clipboardFromMap.action === 'write' ? clipboardFromMap.textLength : -1, 11);
167+
assert.equal(
168+
appstateFromMap.platform === 'android' ? appstateFromMap.package : '',
169+
'com.example.demo',
170+
);
150171
});
151172

152173
test('public daemon request schema accepts GitHub Actions artifact install sources', () => {

‎src/client-types.ts‎

Lines changed: 4 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -59,6 +59,8 @@ export type {
5959
HomeCommandResult,
6060
RotateCommandResult,
6161
} from './contracts/navigation.ts';
62+
export type { ClipboardCommandResult } from './contracts/clipboard.ts';
63+
export type { AppStateCommandResult } from './contracts/app-state.ts';
6264

6365
export type AgentDeviceDaemonTransport = (
6466
req: Omit<DaemonRequest, 'token'>,
@@ -473,16 +475,6 @@ export type AlertCommandResult = DaemonResponseData & {
473475
items?: string[];
474476
};
475477

476-
export type AppStateCommandResult = DaemonResponseData & {
477-
platform?: Platform;
478-
appName?: string;
479-
appBundleId?: string;
480-
package?: string;
481-
activity?: string;
482-
source?: 'session';
483-
surface?: SessionSurface;
484-
};
485-
486478
export type KeyboardCommandResult = DaemonResponseData & {
487479
platform?: 'android' | 'ios';
488480
action?: 'status' | 'dismiss' | 'enter';
@@ -498,16 +490,6 @@ export type KeyboardCommandResult = DaemonResponseData & {
498490
attempts?: number;
499491
};
500492

501-
export type ClipboardCommandResult =
502-
| (DaemonResponseData & {
503-
action: 'read';
504-
text: string;
505-
})
506-
| (DaemonResponseData & {
507-
action: 'write';
508-
textLength: number;
509-
});
510-
511493
export type ReactNativeCommandOptions = DeviceCommandBaseOptions & {
512494
action: 'dismiss-overlay';
513495
};
@@ -525,13 +507,13 @@ export type ViewportCommandOptions = DeviceCommandBaseOptions & {
525507
export type AgentDeviceCommandClient = {
526508
wait: (options: WaitCommandOptions) => Promise<WaitCommandResult>;
527509
alert: (options?: AlertCommandOptions) => Promise<AlertCommandResult>;
528-
appState: (options?: AppStateCommandOptions) => Promise<AppStateCommandResult>;
510+
appState: (options?: AppStateCommandOptions) => Promise<CommandResult<'appstate'>>;
529511
back: (options?: BackCommandOptions) => Promise<CommandResult<'back'>>;
530512
home: (options?: HomeCommandOptions) => Promise<CommandResult<'home'>>;
531513
rotate: (options: RotateCommandOptions) => Promise<CommandResult<'rotate'>>;
532514
appSwitcher: (options?: AppSwitcherCommandOptions) => Promise<CommandResult<'app-switcher'>>;
533515
keyboard: (options?: KeyboardCommandOptions) => Promise<KeyboardCommandResult>;
534-
clipboard: (options: ClipboardCommandOptions) => Promise<ClipboardCommandResult>;
516+
clipboard: (options: ClipboardCommandOptions) => Promise<CommandResult<'clipboard'>>;
535517
reactNative: (options: ReactNativeCommandOptions) => Promise<CommandRequestResult>;
536518
prepare: (options: PrepareCommandOptions) => Promise<CommandRequestResult>;
537519
viewport: (options: ViewportCommandOptions) => Promise<CommandResult<'viewport'>>;

‎src/client.ts‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -103,14 +103,16 @@ export function createAgentDeviceClient(
103103
command: {
104104
wait: async (options) => await executeCommand('wait', options),
105105
alert: async (options = {}) => await executeCommand('alert', options),
106-
appState: async (options = {}) => await executeCommand('appstate', options),
106+
appState: async (options = {}) =>
107+
await executeCommand<CommandResult<'appstate'>>('appstate', options),
107108
back: async (options = {}) => await executeCommand<CommandResult<'back'>>('back', options),
108109
home: async (options = {}) => await executeCommand<CommandResult<'home'>>('home', options),
109110
rotate: async (options) => await executeCommand<CommandResult<'rotate'>>('rotate', options),
110111
appSwitcher: async (options = {}) =>
111112
await executeCommand<CommandResult<'app-switcher'>>('app-switcher', options),
112113
keyboard: async (options = {}) => await executeCommand('keyboard', options),
113-
clipboard: async (options) => await executeCommand('clipboard', options),
114+
clipboard: async (options) =>
115+
await executeCommand<CommandResult<'clipboard'>>('clipboard', options),
114116
reactNative: async (options) => await executeCommand('react-native', options),
115117
prepare: async (options) => await executeCommand('prepare', options),
116118
viewport: async (options) =>

‎src/contracts/app-state.ts‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
import type { SessionSurface } from '../core/session-surface.ts';
2+
3+
/**
4+
* Closed result of the `appstate` command, grounded in the daemon handler's
5+
* success returns (src/daemon/handlers/session-state.ts `handleAppStateCommand`).
6+
* A discriminated union on `platform`:
7+
* - Apple (`ios` / `macos`) session state, with iOS-only device locators that
8+
* the previous hand-written mirror omitted; and
9+
* - Android foreground `package` / `activity`.
10+
*
11+
* The handler returns one of these fixed objects (errors take the `ok: false`
12+
* path), so each branch is closed.
13+
*/
14+
export type AppStateCommandResult =
15+
| {
16+
platform: 'ios' | 'macos';
17+
appName: string;
18+
appBundleId?: string;
19+
source: 'session';
20+
surface: SessionSurface;
21+
/** iOS only — the session device's UDID. */
22+
device_udid?: string;
23+
/** iOS only — the simulator set path, or `null` when unknown. */
24+
ios_simulator_device_set?: string | null;
25+
}
26+
| {
27+
platform: 'android';
28+
package: string;
29+
activity: string;
30+
};

‎src/contracts/clipboard.ts‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
/**
2+
* Closed result of the `clipboard` command. Mirrors the dispatch handler's
3+
* literal return EXACTLY (src/core/dispatch.ts `handleClipboardCommand`): a
4+
* discriminated union on `action`. `read` returns the clipboard `text`; `write`
5+
* reports the written `textLength` plus the `successText` message. The handler
6+
* spreads nothing else, so each branch is closed.
7+
*/
8+
export type ClipboardCommandResult =
9+
| {
10+
action: 'read';
11+
text: string;
12+
}
13+
| {
14+
action: 'write';
15+
textLength: number;
16+
message: string;
17+
};

‎src/core/command-descriptor/__tests__/command-result.test.ts‎

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,8 @@ import type {
1212
HomeCommandResult,
1313
RotateCommandResult,
1414
} from '../../../contracts/navigation.ts';
15+
import type { ClipboardCommandResult } from '../../../contracts/clipboard.ts';
16+
import type { AppStateCommandResult } from '../../../contracts/app-state.ts';
1517
import type { CommandResult, CommandResultMap } from '../command-result.ts';
1618

1719
/**
@@ -34,6 +36,8 @@ test('seeded CommandResult entries resolve to their existing contract result typ
3436
const back: Equal<CommandResult<'back'>, BackCommandResult> = true;
3537
const rotate: Equal<CommandResult<'rotate'>, RotateCommandResult> = true;
3638
const appSwitcher: Equal<CommandResult<'app-switcher'>, AppSwitcherCommandResult> = true;
39+
const clipboard: Equal<CommandResult<'clipboard'>, ClipboardCommandResult> = true;
40+
const appstate: Equal<CommandResult<'appstate'>, AppStateCommandResult> = true;
3741
expect([
3842
press,
3943
fill,
@@ -45,7 +49,9 @@ test('seeded CommandResult entries resolve to their existing contract result typ
4549
back,
4650
rotate,
4751
appSwitcher,
48-
]).toEqual([true, true, true, true, true, true, true, true, true, true]);
52+
clipboard,
53+
appstate,
54+
]).toEqual([true, true, true, true, true, true, true, true, true, true, true, true]);
4955
});
5056

5157
test('unmigrated commands fall back to the untyped Record bag, keeping the union total', () => {
@@ -68,6 +74,8 @@ test('CommandResultMap is seeded only from already-existing contract result type
6874
| 'back'
6975
| 'rotate'
7076
| 'app-switcher'
77+
| 'clipboard'
78+
| 'appstate'
7179
> = true;
7280
expect(keys).toBe(true);
7381
});

‎src/core/command-descriptor/command-result.ts‎

Lines changed: 10 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,8 @@ import type {
1111
HomeCommandResult,
1212
RotateCommandResult,
1313
} from '../../contracts/navigation.ts';
14+
import type { ClipboardCommandResult } from '../../contracts/clipboard.ts';
15+
import type { AppStateCommandResult } from '../../contracts/app-state.ts';
1416

1517
/**
1618
* The additive typed-result spine (ADR-0008, Phase 1 step 6).
@@ -22,11 +24,12 @@ import type {
2224
* visualization, perf, logs, …) are deliberately omitted rather than given an
2325
* invented shape.
2426
*
25-
* Batch 1 wired `boot` / `shutdown` / `viewport` alongside the seed interaction
26-
* trio (`press` / `fill` / `longpress`). Batch 2 adds the closed navigation/
27-
* action commands `home` / `back` / `rotate` / `app-switcher` (each a fixed
28-
* `{ action, …, message }`). Each entry is grounded in a re-read of the handler's
29-
* literal return; see the per-type docstrings for the file source.
27+
* Batches 1-2 wired `boot` / `shutdown` / `viewport` and the navigation/action
28+
* commands `home` / `back` / `rotate` / `app-switcher` alongside the seed
29+
* interaction trio. Batch 3 adds `clipboard` (a closed `read`/`write` union) and
30+
* `appstate` (a closed `platform` union — Apple session state with the iOS-only
31+
* device locators, or Android package/activity). Each entry is grounded in a
32+
* re-read of the handler's literal return; see the per-type docstrings.
3033
*/
3134
export interface CommandResultMap {
3235
press: PressCommandResult;
@@ -39,6 +42,8 @@ export interface CommandResultMap {
3942
back: BackCommandResult;
4043
rotate: RotateCommandResult;
4144
'app-switcher': AppSwitcherCommandResult;
45+
clipboard: ClipboardCommandResult;
46+
appstate: AppStateCommandResult;
4247
}
4348

4449
/**

‎test/integration/provider-scenarios/android-lifecycle.test.ts‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -533,19 +533,22 @@ async function runAndroidSetupAndInstallWorkflow(
533533
assert.equal(braceFilePush.json.result.data.extrasCount, 1);
534534

535535
const clipboard = await client.command.clipboard({ action: 'read', ...selection });
536+
if (clipboard.action !== 'read') throw new Error('expected clipboard read result');
536537
assert.equal(clipboard.text, 'hello');
537538

538539
const clipboardWrite = await client.command.clipboard({
539540
action: 'write',
540541
text: 'android otp',
541542
...selection,
542543
});
544+
if (clipboardWrite.action !== 'write') throw new Error('expected clipboard write result');
543545
assert.equal(clipboardWrite.textLength, 11);
544546

545547
const clipboardAfterWrite = await client.command.clipboard({
546548
action: 'read',
547549
...selection,
548550
});
551+
if (clipboardAfterWrite.action !== 'read') throw new Error('expected clipboard read result');
549552
assert.equal(clipboardAfterWrite.text, 'android otp');
550553

551554
const keyboard = await client.command.keyboard({ action: 'status', ...selection });

0 commit comments

Comments
 (0)