Skip to content

Commit 6fcae4a

Browse files
committed
feat: typed command results, batch 2 (home/back/rotate/app-switcher) — Phase 2
Wire four more commands into the CommandResultMap spine, narrowing their public client return types from the open DaemonResponseData bag to closed shapes. Each shape is grounded in a re-read of the dispatch handler's literal return (src/core/dispatch.ts DISPATCH_HANDLERS) — a fixed `action` discriminant plus the always-present successText `message`: - home -> { action: 'home'; message } - back -> { action: 'back'; mode: BackMode; message } - rotate -> { action: 'rotate'; orientation: DeviceRotation; message } - app-switcher -> { action: 'app-switcher'; message } The handlers spread nothing else, so the shapes are closed (consistent with the viewport contract, the generic-dispatch Android dialog-recovery `warning` annotation is intentionally not part of the contract). The result types move from the client-types.ts mirror into a new src/contracts/navigation.ts; the now-unused CommandActionResult helper is deleted. Public export names are preserved (re-exported via client-types.ts -> index.ts), so no API break. The exact-equality parity test pins CommandResult<name> === the contract type for all ten migrated commands; the public-root export test gains back/rotate samples. Verified: tsc --noEmit, oxfmt + oxlint --deny-warnings, fallow audit clean, Layering Guard empty, 791 tests across core/contracts/client/commands pass (the lone failure was the known-flaky daemon-client mid-stream-abort test, which passes in isolation).
1 parent 0be806c commit 6fcae4a

6 files changed

Lines changed: 118 additions & 38 deletions

File tree

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

Lines changed: 18 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 BackCommandResult,
78
type BootCommandResult,
89
type CommandResult,
10+
type RotateCommandResult,
911
type ShutdownCommandResult,
1012
type ViewportCommandResult,
1113
} from '../index.ts';
@@ -126,9 +128,25 @@ test('public root exports typed command result contracts', () => {
126128
} satisfies ViewportCommandResult;
127129
const viewportFromMap: CommandResult<'viewport'> = viewport;
128130

131+
const back = {
132+
action: 'back',
133+
mode: 'in-app',
134+
message: 'Back',
135+
} satisfies BackCommandResult;
136+
const backFromMap: CommandResult<'back'> = back;
137+
138+
const rotate = {
139+
action: 'rotate',
140+
orientation: 'portrait',
141+
message: 'Rotated to portrait',
142+
} satisfies RotateCommandResult;
143+
const rotateFromMap: CommandResult<'rotate'> = rotate;
144+
129145
assert.equal(bootFromMap.booted, true);
130146
assert.equal(shutdownFromMap.shutdown.success, true);
131147
assert.equal(viewportFromMap.width, 390);
148+
assert.equal(backFromMap.mode, 'in-app');
149+
assert.equal(rotateFromMap.orientation, 'portrait');
132150
});
133151

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

‎src/client-types.ts‎

Lines changed: 10 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -53,6 +53,12 @@ export type { AlertAction, AlertInfo, AlertPlatform, AlertSource } from './alert
5353
export type { DebugSymbolsOptions, DebugSymbolsResult } from './contracts/debug-symbols.ts';
5454
export type { BootCommandResult, ShutdownCommandResult } from './contracts/device.ts';
5555
export type { ViewportCommandResult } from './contracts/viewport.ts';
56+
export type {
57+
AppSwitcherCommandResult,
58+
BackCommandResult,
59+
HomeCommandResult,
60+
RotateCommandResult,
61+
} from './contracts/navigation.ts';
5662

5763
export type AgentDeviceDaemonTransport = (
5864
req: Omit<DaemonRequest, 'token'>,
@@ -467,10 +473,6 @@ export type AlertCommandResult = DaemonResponseData & {
467473
items?: string[];
468474
};
469475

470-
type CommandActionResult<T extends string> = DaemonResponseData & {
471-
action?: T;
472-
};
473-
474476
export type AppStateCommandResult = DaemonResponseData & {
475477
platform?: Platform;
476478
appName?: string;
@@ -481,18 +483,6 @@ export type AppStateCommandResult = DaemonResponseData & {
481483
surface?: SessionSurface;
482484
};
483485

484-
export type BackCommandResult = CommandActionResult<'back'> & {
485-
mode?: BackMode;
486-
};
487-
488-
export type HomeCommandResult = CommandActionResult<'home'>;
489-
490-
export type RotateCommandResult = CommandActionResult<'rotate'> & {
491-
orientation?: RotateCommandOptions['orientation'];
492-
};
493-
494-
export type AppSwitcherCommandResult = CommandActionResult<'app-switcher'>;
495-
496486
export type KeyboardCommandResult = DaemonResponseData & {
497487
platform?: 'android' | 'ios';
498488
action?: 'status' | 'dismiss' | 'enter';
@@ -536,10 +526,10 @@ export type AgentDeviceCommandClient = {
536526
wait: (options: WaitCommandOptions) => Promise<WaitCommandResult>;
537527
alert: (options?: AlertCommandOptions) => Promise<AlertCommandResult>;
538528
appState: (options?: AppStateCommandOptions) => Promise<AppStateCommandResult>;
539-
back: (options?: BackCommandOptions) => Promise<BackCommandResult>;
540-
home: (options?: HomeCommandOptions) => Promise<HomeCommandResult>;
541-
rotate: (options: RotateCommandOptions) => Promise<RotateCommandResult>;
542-
appSwitcher: (options?: AppSwitcherCommandOptions) => Promise<AppSwitcherCommandResult>;
529+
back: (options?: BackCommandOptions) => Promise<CommandResult<'back'>>;
530+
home: (options?: HomeCommandOptions) => Promise<CommandResult<'home'>>;
531+
rotate: (options: RotateCommandOptions) => Promise<CommandResult<'rotate'>>;
532+
appSwitcher: (options?: AppSwitcherCommandOptions) => Promise<CommandResult<'app-switcher'>>;
543533
keyboard: (options?: KeyboardCommandOptions) => Promise<KeyboardCommandResult>;
544534
clipboard: (options: ClipboardCommandOptions) => Promise<ClipboardCommandResult>;
545535
reactNative: (options: ReactNativeCommandOptions) => Promise<CommandRequestResult>;

‎src/client.ts‎

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -104,10 +104,11 @@ export function createAgentDeviceClient(
104104
wait: async (options) => await executeCommand('wait', options),
105105
alert: async (options = {}) => await executeCommand('alert', options),
106106
appState: async (options = {}) => await executeCommand('appstate', options),
107-
back: async (options = {}) => await executeCommand('back', options),
108-
home: async (options = {}) => await executeCommand('home', options),
109-
rotate: async (options) => await executeCommand('rotate', options),
110-
appSwitcher: async (options = {}) => await executeCommand('app-switcher', options),
107+
back: async (options = {}) => await executeCommand<CommandResult<'back'>>('back', options),
108+
home: async (options = {}) => await executeCommand<CommandResult<'home'>>('home', options),
109+
rotate: async (options) => await executeCommand<CommandResult<'rotate'>>('rotate', options),
110+
appSwitcher: async (options = {}) =>
111+
await executeCommand<CommandResult<'app-switcher'>>('app-switcher', options),
111112
keyboard: async (options = {}) => await executeCommand('keyboard', options),
112113
clipboard: async (options) => await executeCommand('clipboard', options),
113114
reactNative: async (options) => await executeCommand('react-native', options),

‎src/contracts/navigation.ts‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
import type { BackMode } from '../core/back-mode.ts';
2+
import type { DeviceRotation } from '../core/device-rotation.ts';
3+
4+
/**
5+
* Closed results of the navigation/global action commands. Each mirrors the
6+
* dispatch handler's literal return EXACTLY (src/core/dispatch.ts
7+
* `DISPATCH_HANDLERS`): a fixed `action` discriminant plus the always-present
8+
* `successText` message (the handlers always pass a non-empty message, so it is
9+
* required here). The handlers spread nothing else, so the shapes are closed —
10+
* consistent with the `viewport` contract, the generic-dispatch Android
11+
* dialog-recovery `warning` annotation is intentionally not part of the contract.
12+
*/
13+
14+
/** `home` — `{ action: 'home', message: 'Home' }`. */
15+
export type HomeCommandResult = {
16+
action: 'home';
17+
message: string;
18+
};
19+
20+
/** `back` — `{ action: 'back', mode, message: 'Back' }`; `mode` defaults to `'in-app'`. */
21+
export type BackCommandResult = {
22+
action: 'back';
23+
mode: BackMode;
24+
message: string;
25+
};
26+
27+
/** `rotate` — `{ action: 'rotate', orientation, message: 'Rotated to <orientation>' }`. */
28+
export type RotateCommandResult = {
29+
action: 'rotate';
30+
orientation: DeviceRotation;
31+
message: string;
32+
};
33+
34+
/** `app-switcher` — `{ action: 'app-switcher', message: 'Opened app switcher' }`. */
35+
export type AppSwitcherCommandResult = {
36+
action: 'app-switcher';
37+
message: string;
38+
};

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

Lines changed: 32 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,12 @@ import type {
66
} from '../../../contracts/interaction.ts';
77
import type { BootCommandResult, ShutdownCommandResult } from '../../../contracts/device.ts';
88
import type { ViewportCommandResult } from '../../../contracts/viewport.ts';
9+
import type {
10+
AppSwitcherCommandResult,
11+
BackCommandResult,
12+
HomeCommandResult,
13+
RotateCommandResult,
14+
} from '../../../contracts/navigation.ts';
915
import type { CommandResult, CommandResultMap } from '../command-result.ts';
1016

1117
/**
@@ -24,14 +30,22 @@ test('seeded CommandResult entries resolve to their existing contract result typ
2430
const boot: Equal<CommandResult<'boot'>, BootCommandResult> = true;
2531
const shutdown: Equal<CommandResult<'shutdown'>, ShutdownCommandResult> = true;
2632
const viewport: Equal<CommandResult<'viewport'>, ViewportCommandResult> = true;
27-
expect([press, fill, longPress, boot, shutdown, viewport]).toEqual([
28-
true,
29-
true,
30-
true,
31-
true,
32-
true,
33-
true,
34-
]);
33+
const home: Equal<CommandResult<'home'>, HomeCommandResult> = true;
34+
const back: Equal<CommandResult<'back'>, BackCommandResult> = true;
35+
const rotate: Equal<CommandResult<'rotate'>, RotateCommandResult> = true;
36+
const appSwitcher: Equal<CommandResult<'app-switcher'>, AppSwitcherCommandResult> = true;
37+
expect([
38+
press,
39+
fill,
40+
longPress,
41+
boot,
42+
shutdown,
43+
viewport,
44+
home,
45+
back,
46+
rotate,
47+
appSwitcher,
48+
]).toEqual([true, true, true, true, true, true, true, true, true, true]);
3549
});
3650

3751
test('unmigrated commands fall back to the untyped Record bag, keeping the union total', () => {
@@ -44,7 +58,16 @@ test('unmigrated commands fall back to the untyped Record bag, keeping the union
4458
test('CommandResultMap is seeded only from already-existing contract result types', () => {
4559
const keys: Equal<
4660
keyof CommandResultMap,
47-
'press' | 'fill' | 'longpress' | 'boot' | 'shutdown' | 'viewport'
61+
| 'press'
62+
| 'fill'
63+
| 'longpress'
64+
| 'boot'
65+
| 'shutdown'
66+
| 'viewport'
67+
| 'home'
68+
| 'back'
69+
| 'rotate'
70+
| 'app-switcher'
4871
> = true;
4972
expect(keys).toBe(true);
5073
});

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

Lines changed: 15 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,12 @@ import type {
55
} from '../../contracts/interaction.ts';
66
import type { BootCommandResult, ShutdownCommandResult } from '../../contracts/device.ts';
77
import type { ViewportCommandResult } from '../../contracts/viewport.ts';
8+
import type {
9+
AppSwitcherCommandResult,
10+
BackCommandResult,
11+
HomeCommandResult,
12+
RotateCommandResult,
13+
} from '../../contracts/navigation.ts';
814

915
/**
1016
* The additive typed-result spine (ADR-0008, Phase 1 step 6).
@@ -16,11 +22,11 @@ import type { ViewportCommandResult } from '../../contracts/viewport.ts';
1622
* visualization, perf, logs, …) are deliberately omitted rather than given an
1723
* invented shape.
1824
*
19-
* Phase 2 batch 1 wires the first map entries into the public client return
20-
* types: `boot` / `shutdown` (closed device-lifecycle results) and `viewport`
21-
* (closed `{ width, height, message }`) join the seed interaction trio
22-
* (`press` / `fill` / `longpress`). Each entry is grounded in a re-read of the
23-
* handler's literal return; see the per-type docstrings for the file source.
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.
2430
*/
2531
export interface CommandResultMap {
2632
press: PressCommandResult;
@@ -29,6 +35,10 @@ export interface CommandResultMap {
2935
boot: BootCommandResult;
3036
shutdown: ShutdownCommandResult;
3137
viewport: ViewportCommandResult;
38+
home: HomeCommandResult;
39+
back: BackCommandResult;
40+
rotate: RotateCommandResult;
41+
'app-switcher': AppSwitcherCommandResult;
3242
}
3343

3444
/**

0 commit comments

Comments
 (0)