Repository navigation
Expand file tree
/
Copy pathapp.ts
More file actions
234 lines (218 loc) · 10.2 KB
/
Copy pathapp.ts
File metadata and controls
234 lines (218 loc) · 10.2 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
import { PUBLIC_COMMANDS } from '@agent-device/command-registry/catalog';
import type { AppCloseOptions, AppOpenOptions } from '@agent-device/contracts/client';
import { SESSION_SURFACES } from '@agent-device/contracts/session';
import type { CommandSchemaOverride } from '@agent-device/command-registry/command-schema';
import { assertResolvedAppsFilter } from './app-inventory-contract.ts';
import {
booleanField,
booleanSchema,
enumField,
integerField,
jsonSchemaField,
optionField,
stringArrayField,
stringField,
stringSchema,
} from '../command-input.ts';
import { commonInputFromFlags, direct, optionalString } from '../cli-grammar/common.ts';
import type { CliReader, CommandInput, DaemonWriter } from '../cli-grammar/types.ts';
import { METRO_RELOAD_FLAGS } from '@agent-device/command-registry/flag-groups';
import { defineCommandFacet } from '../family/types.ts';
import { defineFieldCommandMetadata } from '../field-command-contract.ts';
import { withCommandRuntimeHints } from '../runtime-hints.ts';
import { managementCliOutputFormatters } from './output.ts';
const appsCommandMetadata = defineFieldCommandMetadata(
'apps',
'List the apps installed on the selected device. Include system or OEM apps only when they are needed as automation targets.',
{
appsFilter: enumField(
['user-installed', 'all'],
'Restrict the listing to user-installed apps, or include system and OEM apps.',
),
},
);
const openCommandMetadata = defineFieldCommandMetadata(
'open',
'Boot the selected device when needed, then open an app, deep link, or URL in a session. Use the app or URL inputs to choose what becomes the foreground automation target.',
{
app: stringField('App name, bundle id, package, or URL.'),
url: stringField('Optional URL passed with an app shell.'),
surface: enumField(
SESSION_SURFACES,
'macOS presentation surface to open: the app itself, the frontmost app, the desktop, or the menu bar.',
),
activity: stringField('Android activity name.'),
launchConsole: stringField('Launch console mode.'),
launchArgs: stringArrayField(
'Launch arguments forwarded verbatim to the platform launch command.',
),
relaunch: booleanField('Force relaunch.'),
timeoutMs: integerField(
'Startup budget in milliseconds. Bounds the Simulator boot wait, so a never-booted Simulator can finish its first-boot migration; omit for the default startup behavior.',
{ min: 1 },
),
waitMs: optionField('waitMs'),
foreground: optionField('foreground'),
saveScript: jsonSchemaField<boolean | string>({
oneOf: [booleanSchema(), stringSchema()],
}),
force: booleanField(
'Overwrite an existing --save-script target instead of refusing (alias: --overwrite).',
),
testIme: booleanField(
'Activate the headless Android test IME for deterministic Unicode text entry (default on for emulators; opt-in on real devices).',
),
noRecord: booleanField('Do not record this action.'),
metroHost: stringField('Session-scoped Metro/debug host hint applied to the opened app.'),
metroPort: integerField(
'Session-scoped Metro/debug port hint applied to the opened app. On an emulator/simulator the host defaults to the loopback alias (Android 10.0.2.2, iOS 127.0.0.1) when --metro-host is omitted; physical devices still require an explicit --metro-host.',
{
min: 1,
max: 65535,
},
),
bundleUrl: stringField('Session-scoped bundle URL hint applied to the opened app.'),
launchUrl: stringField('Session-scoped launch URL hint applied to the opened app.'),
},
);
const closeCommandMetadata = defineFieldCommandMetadata(
'close',
'Close the named app, or close the active session app when app is omitted. Use shutdown only when the selected simulator or emulator should also stop.',
{
app: stringField('Optional app to close.'),
shutdown: booleanField('Shutdown the session/device where supported.'),
saveScript: jsonSchemaField<boolean | string>({
oneOf: [booleanSchema(), stringSchema()],
}),
force: booleanField(
'Overwrite an existing --save-script target instead of refusing (alias: --overwrite).',
),
},
);
// The flat metro hint flags fold into the `runtime` object open already accepts.
function toAppOpenOptions(
input: AppOpenOptions & {
metroHost?: string;
metroPort?: number;
bundleUrl?: string;
launchUrl?: string;
},
): AppOpenOptions {
return withCommandRuntimeHints(input);
}
const appsCliSchema = {
allowedFlags: ['appsFilter'],
} as const satisfies CommandSchemaOverride;
const openCliSchema = {
positionalArgs: ['appOrUrl?', 'url?'],
allowedFlags: [
'activity',
'launchConsole',
'launchArgs',
'testIme',
'saveScript',
'force',
'noRecord',
'relaunch',
'foreground',
'timeoutMs',
'waitMs',
'surface',
...METRO_RELOAD_FLAGS,
'launchUrl',
],
} as const satisfies CommandSchemaOverride;
const closeCliSchema = {
positionalArgs: ['app?'],
allowedFlags: ['saveScript', 'force', 'shutdown'],
} as const satisfies CommandSchemaOverride;
const appsCliReader: CliReader = (_positionals, flags) => ({
...commonInputFromFlags(flags),
appsFilter: assertResolvedAppsFilter(flags.appsFilter),
});
const openCliReader: CliReader = (positionals, flags) => ({
...commonInputFromFlags(flags),
app: positionals[0],
url: positionals[1],
surface: flags.surface,
activity: flags.activity,
launchConsole: flags.launchConsole,
launchArgs: flags.launchArgs,
relaunch: flags.relaunch,
foreground: flags.foreground,
timeoutMs: flags.timeoutMs,
waitMs: flags.waitMs,
saveScript: flags.saveScript,
force: flags.force,
testIme: flags.testIme,
noRecord: flags.noRecord,
metroHost: flags.metroHost,
metroPort: flags.metroPort,
bundleUrl: flags.bundleUrl,
launchUrl: flags.launchUrl,
});
const closeCliReader: CliReader = (positionals, flags) => ({
...commonInputFromFlags(flags),
app: positionals[0],
shutdown: flags.shutdown,
saveScript: flags.saveScript,
force: flags.force,
});
const appsDaemonWriter: DaemonWriter = direct(PUBLIC_COMMANDS.apps);
const openDaemonWriter: DaemonWriter = direct(PUBLIC_COMMANDS.open, openPositionals);
const closeDaemonWriter: DaemonWriter = direct(PUBLIC_COMMANDS.close, (input) =>
optionalString(input.app),
);
export const appsCommandFacet = defineCommandFacet({
name: 'apps',
text: {
summary: 'List installed apps or deferred provider app assets',
cliDetail:
'Before provider allocation, lists uploaded app assets when the selected provider exposes a catalog. On a live device, defaults to user-installed apps; use --all to include system/OEM apps.',
},
metadata: appsCommandMetadata,
run: (client, input) => client.apps.list(input),
cliSchema: appsCliSchema,
cliReader: appsCliReader,
daemonWriter: appsDaemonWriter,
cliOutputFormatter: managementCliOutputFormatters.apps,
});
export const openCommandFacet = defineCommandFacet({
name: 'open',
text: {
summary: 'Open an app, deep link or URL, save replays',
cliDetail:
'Use --platform to bind URL/deep-link opens to the target platform. For iOS simulator initial stdout/stderr, put --launch-console <path> on this open command, for example agent-device open "Agent Device Tester" --platform ios --launch-console artifacts/launch-console.log. Expo Go/dev-client shells accept host + URL, for example agent-device open "Expo Go" exp://127.0.0.1:8081 --platform ios. macOS also supports --surface app|frontmost-app|desktop|menubar. --metro-host/--metro-port/--bundle-url/--launch-url set this session\'s Metro/debug runtime hints as part of open itself (applied to the app\'s dev-server prefs and recorded as the session\'s dev-server binding), so a fresh session has them before its first reload instead of needing a throwaway reload-first call just to seed hints; a later plain metro reload in the same session reuses whichever of these were set. A fresh open without these flags clears any leftover binding from a previous same-name session; close also clears it. On an iOS Simulator, simctl openurl is bounded to 20s; if CoreSimulator stalls, open fails with details.reason ios-simulator-openurl-timeout and details.dispatched unknown because the URL may already have landed. On an iOS simulator, when --launch-url raises an "Open in <App>?" prompt that keeps open from seeing the app, open accepts it if the URL scheme belongs to the session app (data.launchConfirmation: "accepted"); if the scheme belongs to another installed app, the prompt stays on screen and open fails with details.reason launch_confirmation_foreign_app; if no single installed app owns the scheme, the prompt stays on screen and open returns as usual. Only the English prompt title is recognized, so on a Simulator set to another language the prompt stays on screen. A prompt that appears after open has already seen the app is not answered; use alert accept. A device another session is holding refuses at once; add --wait <ms> to block up to that budget for it and only then fail with DEVICE_IN_USE naming the owning session.',
mcpDetail:
"Metro and debug runtime hints given here are recorded as the session's dev-server binding, so a later reload reuses them; a fresh open without them clears any binding left by a previous same-name session.",
},
metadata: openCommandMetadata,
run: (client, input) => client.apps.open(toAppOpenOptions(input)),
cliSchema: openCliSchema,
cliReader: openCliReader,
daemonWriter: openDaemonWriter,
cliOutputFormatter: managementCliOutputFormatters.open,
});
export const closeCommandFacet = defineCommandFacet({
name: 'close',
text: {
summary: 'Close an app or end the session',
},
metadata: closeCommandMetadata,
run: (client, input) =>
input.app ? client.apps.close(input) : client.sessions.close(withoutApp(input)),
cliSchema: closeCliSchema,
cliReader: closeCliReader,
daemonWriter: closeDaemonWriter,
cliOutputFormatter: managementCliOutputFormatters.close,
});
function withoutApp(input: AppCloseOptions & { shutdown?: boolean }): {
shutdown?: boolean;
} {
const { app: _app, ...rest } = input;
return rest;
}
function openPositionals(input: CommandInput): string[] {
if (!input.app) return [];
return input.url ? [input.app, input.url] : [input.app];
}