Open History to see the last commit
1// @effect-diagnostics nodeBuiltinImport:off globalJsonInEffect:off - drives agent-device and the Hermes inspector; the probe types its own JSON.
2/**
3 * One simulator, driven two ways: T3's `agent-device` CLI for real touches and system actions,
4 * and the dev-only behavior probe (`apps/mobile/src/features/development/behavior-probe.ts`)
5 * through Metro's Hermes inspector for exact app state.
6 */
7import * as NodeChildProcess from "node:child_process";
8import * as NodeOS from "node:os";
9import * as NodePath from "node:path";
10import * as NodeWS from "@effect/platform-node/NodeWS";
11import * as Clock from "effect/Clock";
12import * as Effect from "effect/Effect";
13import * as Schedule from "effect/Schedule";
14import * as Schema from "effect/Schema";
15import { FetchHttpClient, HttpClient, HttpClientResponse } from "effect/http";
16import { Socket } from "effect/socket";
17
18import { poolError } from "../mobile-e2e/device.ts";
19
20const InspectorTargets = Schema.Array(
21 Schema.Struct({
22 appId: Schema.String,
23 deviceName: Schema.optional(Schema.String),
24 webSocketDebuggerUrl: Schema.String,
25 }),
26);
27
28export class DeviceError extends Schema.TaggedError<DeviceError>()("DeviceError", {
29 message: Schema.String,
30}) {}
31
32export const APP_ID = "com.t3tools.t3code.dev";
33export const SCHEME = "t3code-dev";
34
35export interface ProbeState {
36 readonly route: {
37 readonly name: string | null;
38 readonly params: Record<string, unknown>;
39 readonly columns: boolean;
40 } | null;
41 readonly feed: FeedSample | null;
42 readonly composer: {
43 readonly key: string | null;
44 readonly draft: string | null;
45 readonly drafts: Record<string, string>;
46 readonly editors: ReadonlyArray<{ readonly value: string; readonly expanded: boolean }>;
47 readonly error: string | null;
48 readonly keyboard: boolean;
49 };
50 readonly floatingStatus: string | null;
51 readonly environments: ReadonlyArray<string>;
52 /** The app's status for every thread it knows, by thread id. */
53 readonly threads: Record<string, string>;
54 readonly homeList: ReadonlyArray<{
55 readonly type: string;
56 readonly threadId?: string;
57 readonly status?: string;
58 readonly pinned?: boolean;
59 readonly count?: number;
60 readonly expanded?: boolean;
61 }> | null;
62}
63
64export interface FeedSample {
65 readonly at?: number;
66 readonly threadId: string;
67 readonly ready: boolean;
68 readonly scroll?: number;
69 readonly viewport?: number;
70 readonly content?: number;
71 readonly fromEnd?: number;
72 readonly atEnd?: boolean;
73 readonly following?: boolean | null;
74 readonly count?: number;
75 readonly rows?: Record<string, number>;
76}
77
78export interface Recording {
79 readonly js: ReadonlyArray<number>;
80 readonly ui: ReadonlyArray<number>;
81 readonly feed: ReadonlyArray<FeedSample>;
82}
83
84export interface AxNode {
85 readonly type?: string;
86 readonly label?: string;
87 readonly value?: string;
88 readonly kind?: string;
89 readonly editable?: boolean;
90 readonly enabled?: boolean;
91 readonly rect?: {
92 readonly x: number;
93 readonly y: number;
94 readonly width: number;
95 readonly height: number;
96 };
97}
98
99export interface DeviceOptions {
100 /** `agent-device` executable and the target args `device_open` returned. */
101 readonly agentDevice: string;
102 readonly targetArgs: ReadonlyArray<string>;
103 readonly metro: string;
104 /** Simulator name as Metro's inspector lists it; empty for the only app on this run's Metro. */
105 readonly deviceName: string;
106}
107
108export function makeDevice(options: DeviceOptions) {
109 const run = (args: ReadonlyArray<string>, timeoutMs = 90_000) =>
110 Effect.try({
111 try: () =>
112 NodeChildProcess.execFileSync(options.agentDevice, [...args, ...options.targetArgs], {
113 encoding: "utf8",
114 timeout: timeoutMs,
115 stdio: ["ignore", "pipe", "pipe"],
116 }),
117 catch: (cause) => {
118 // The thrown message starts with the full command line; the reason is in its output.
119 const output = cause as { readonly stdout?: string; readonly stderr?: string };
120 const reason = `${output.stderr ?? ""}${output.stdout ?? ""}`.trim() || String(cause);
121 return new DeviceError({
122 message: `agent-device ${args.join(" ")} failed: ${reason.slice(-400)}`,
123 });
124 },
125 }).pipe(
126 // A shared pool's workers drop off the gateway for seconds at a time.
127 Effect.retry({
128 times: 4,
129 while: (error) => poolError(error.message),
130 schedule: Schedule.spaced("5 seconds"),
131 }),
132 Effect.withSpan("device.agentDevice", { attributes: { command: args[0] } }),
133 );
134
135 const evaluate = Effect.fn("device.evaluate")(
136 function* (expression: string) {
137 const targets = yield* HttpClient.get(`${options.metro}/json/list`).pipe(
138 Effect.flatMap(HttpClientResponse.schemaBodyJson(InspectorTargets)),
139 Effect.provide(FetchHttpClient.layer),
140 Effect.mapError(
141 () => new DeviceError({ message: `Metro at ${options.metro} did not answer.` }),
142 ),
143 );
144 // Pool simulators carry generated names; a run's own Metro then serves only its device.
145 const target = targets.findLast(
146 (entry) =>
147 entry.appId === APP_ID &&
148 (!options.deviceName || entry.deviceName === options.deviceName),
149 );
150 if (!target)
151 return yield* new DeviceError({
152 message: `No app on ${options.deviceName} is attached to Metro.`,
153 });
154 // Expo drops inspector sockets whose Origin is not the URL Metro advertises.
155 const socket = yield* Socket.makeWebSocket(target.webSocketDebuggerUrl, {
156 headers: { origin: new URL(options.metro).origin },
157 openTimeout: "10 seconds",
158 });
159 const writer = yield* socket.writer;
160 const reader = yield* socket.reader;
161 yield* writer.write(
162 JSON.stringify({
163 id: 1,
164 method: "Runtime.evaluate",
165 params: { expression, returnByValue: true, awaitPromise: true },
166 }),
167 );
168 while (true) {
169 for (const frame of yield* reader.pull) {
170 const reply = JSON.parse(
171 typeof frame === "string" ? frame : new TextDecoder().decode(frame),
172 ) as {
173 id?: number;
174 result?: { result?: { value?: unknown }; exceptionDetails?: unknown };
175 };
176 if (reply.id !== 1) continue;
177 if (reply.result?.exceptionDetails)
178 return yield* new DeviceError({
179 message: `${expression} threw ${JSON.stringify(reply.result.exceptionDetails).slice(0, 400)}`,
180 });
181 return reply.result?.result?.value;
182 }
183 }
184 },
185 Effect.scoped,
186 Effect.provide(NodeWS.layerWebSocketConstructor),
187 Effect.timeoutOrElse({
188 duration: "20 seconds",
189 orElse: () => Effect.fail(new DeviceError({ message: "The inspector did not answer." })),
190 }),
191 Effect.mapError((error) =>
192 error._tag === "DeviceError"
193 ? error
194 : new DeviceError({ message: `Inspector: ${error.message}` }),
195 ),
196 );
197
198 const state = evaluate("__t3Behavior.state()").pipe(
199 Effect.map((value) => JSON.parse(String(value)) as ProbeState),
200 );
201
202 /** Polls the probe until `predicate` holds; fails with the last state after `timeoutMs`. */
203 const waitFor = Effect.fn("device.waitFor")(function* (
204 description: string,
205 predicate: (state: ProbeState) => boolean,
206 timeoutMs = 15_000,
207 ) {
208 const deadline = (yield* Clock.currentTimeMillis) + timeoutMs;
209 let last: ProbeState | null = null;
210 while ((yield* Clock.currentTimeMillis) < deadline) {
211 last = yield* state.pipe(Effect.orElseSucceed(() => null));
212 if (last && predicate(last)) return last;
213 yield* Effect.sleep("250 millis");
214 }
215 return yield* new DeviceError({
216 message: `Timed out waiting for ${description}. Last route: ${JSON.stringify(last?.route ?? null)}`,
217 });
218 });
219
220 const nodes = run(["snapshot", "--json"]).pipe(
221 Effect.map((out) => (JSON.parse(out) as { data: { nodes: ReadonlyArray<AxNode> } }).data.nodes),
222 );
223
224 const center = (node: AxNode) => ({
225 x: Math.round(node.rect!.x + node.rect!.width / 2),
226 y: Math.round(node.rect!.y + node.rect!.height / 2),
227 });
228
229 const screenSize = run([
230 "screenshot",
231 NodePath.join(NodeOS.tmpdir(), "t3-mobile-behavior-screen.png"),
232 "--json",
233 ]).pipe(
234 Effect.map((out) => {
235 const { data } = JSON.parse(out) as { data: { logicalWidth: number; logicalHeight: number } };
236 return { width: data.logicalWidth, height: data.logicalHeight };
237 }),
238 );
239
240 return {
241 options,
242 run,
243 evaluate,
244 state,
245 waitFor,
246 nodes,
247 center,
248 open: (path: string) =>
249 evaluate(`__t3Behavior.open(${JSON.stringify(`${SCHEME}://${path.replace(/^\//, "")}`)})`),
250 openUrl: (url: string) => evaluate(`__t3Behavior.open(${JSON.stringify(url)})`),
251 /** Reloads JS, then opens Home; the app restores the last thread, and split layouts keep one open. */
252 reload: Effect.fn("device.reload")(function* (ready: (state: ProbeState) => boolean) {
253 yield* evaluate("__t3Behavior.reload()").pipe(Effect.ignore);
254 yield* Effect.sleep("2 seconds");
255 yield* waitFor("the thread list after reload", ready, 60_000);
256 yield* evaluate(`__t3Behavior.open(${JSON.stringify(`${SCHEME}://`)})`);
257 // Split layouts may keep a thread beside Home, so they get a short wait for the Home route.
258 const home = (value: ProbeState) => ready(value) && value.route?.name === "Home";
259 const state = yield* waitFor("Home", home, 5_000).pipe(Effect.option);
260 if (state._tag === "Some") return state.value;
261 return yield* waitFor(
262 "the split layout",
263 (value) => ready(value) && value.route?.columns === true,
264 );
265 }),
266 recordStart: (withFeed: boolean) => evaluate(`__t3Behavior.recordStart(${withFeed})`),
267 recordStop: evaluate("__t3Behavior.recordStop()").pipe(
268 Effect.map((value) => JSON.parse(String(value)) as Recording),
269 ),
270 press: (selector: string) => run(["press", selector]),
271 pressAt: (x: number, y: number) => run(["press", String(x), String(y)]),
272 longPress: (selector: string) => run(["longpress", selector, "800"]),
273 type: (text: string) => run(["type", text]),
274 /** Drags from y1 to y2 at x; a downward drag scrolls the content up. */
275 swipe: (x: number, y1: number, y2: number) =>
276 run(["swipe", String(x), String(y1), String(x), String(y2)]),
277 /**
278 * Answers iOS's "Open in" prompt. XCTest cannot see the iOS 27.1 prompt, so when `alert` fails
279 * this taps where its Open button sits, just right of and below the screen's center.
280 */
281 acceptOpenPrompt: run(["alert", "accept"], 60_000).pipe(
282 Effect.catch(() =>
283 screenSize.pipe(
284 Effect.flatMap(({ width, height }) =>
285 run(["press", String(Math.round(width / 2 + 76)), String(Math.round(height / 2 + 8))]),
286 ),
287 ),
288 ),
289 ),
290 home: run(["home"]),
291 /** The Duo simulator often follows a fold without a hinge reading, so the screen's shape confirms it. */
292 fold: (pose: "closed" | "open") =>
293 run(["fold", pose]).pipe(
294 Effect.catch((error) =>
295 screenSize.pipe(
296 Effect.filterOrFail(
297 ({ width, height }) => (pose === "closed") === width < height,
298 () => error,
299 ),
300 ),
301 ),
302 ),
303 back: run(["back"]),
304 };
305}
306
307export type Device = ReturnType<typeof makeDevice>;