mirror of
https://github.com/expo/explore.git
synced 2026-11-15 17:32:23 -10:00
Compare commits
9
Commits
v0.23.0
...
@brent/argent
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
ee0e86fe56 | ||
|
|
8bb985a9d2 | ||
|
|
766f268ea6 | ||
|
|
01f32fdb33 | ||
|
|
43aed26c80 | ||
|
|
e84a4a19d0 | ||
|
|
a40ef9e9a5 | ||
|
|
0beef676a9 | ||
|
|
f90ab1f480 |
No files matched your search
@@ -173,7 +173,7 @@ Explore starts an EAS Simulator, installs the build, taps through the app with y
|
||||
<details>
|
||||
<summary><strong>Explore a simulator session you already started</strong></summary>
|
||||
|
||||
If the app is already running on an `agent-device` EAS Simulator session, Explore can start from there. It leaves your session running.
|
||||
If the app is already running on an EAS Simulator session (`--type agent-device` or `--type argent`), Explore can start from there, with the session's controller. It leaves your session running.
|
||||
|
||||
```sh
|
||||
eas simulator:start --type agent-device --out-config-type dotenv # then agent-device install / open
|
||||
@@ -298,6 +298,29 @@ platforms:
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary id="controller"><strong>Device controller: agent-device or Argent</strong></summary>
|
||||
|
||||
Explore drives EAS Simulator with [agent-device](https://github.com/callstackincubator/agent-device) by default. To use [Argent](https://github.com/software-mansion/argent) instead, set it in the config or pass it for one run:
|
||||
|
||||
```yaml
|
||||
capture:
|
||||
controller: argent # agent-device (default) | argent
|
||||
```
|
||||
|
||||
```sh
|
||||
npx @expo/explore capture --controller argent
|
||||
npx @expo/explore explore:binary ./app.apk --controller argent
|
||||
```
|
||||
|
||||
Explore pins each controller's version and starts the EAS session with it. Reports and baselines record the controller, and a review compares captures made with the same one.
|
||||
|
||||
Neither controller is installed with Explore. The first run that needs one downloads its pinned npm release (agent-device 1.4 MB, Argent 27 MB), checks it against the integrity hash Explore pins, and keeps it in `~/.cache/expo-explore/controllers` (`EXPLORE_CONTROLLER_CACHE` moves it). Behind a private registry, set `EXPLORE_NPM_REGISTRY` to a mirror of it.
|
||||
|
||||
Argent cannot switch the simulator's appearance yet ([software-mansion/argent#1509](https://github.com/software-mansion/argent/pull/1509)), so an Argent capture records one appearance: the one the app forces, else light. Explore warns when it skips one.
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><strong>Keep your setup current</strong></summary>
|
||||
|
||||
@@ -453,6 +476,7 @@ Reports and baselines are kept for 30 days and diagnostics for 7. Hosted deploym
|
||||
- The launch is captured once per appearance and compared like any screen. The comment says how long the splash stayed as it first appeared, when it first changed (a native launch screen handing over to an app-drawn one, an animation starting on it), and when the first screen settled. `capture.launch: video` adds a recording; a launch too fast to observe is reported as "no splash observed".
|
||||
- On Android the splash usually shows only in the recording, which needs `ffmpeg`. The generated workflows install it.
|
||||
- Hosted acceptance of agent mode with an API key is incomplete.
|
||||
- With `capture.controller: argent`, each capture records one appearance (see [device controller](#controller)).
|
||||
|
||||
</details>
|
||||
|
||||
|
||||
@@ -101,9 +101,11 @@ navigation:
|
||||
# entry: src/navigation/RootNavigator.tsx
|
||||
device:
|
||||
name: iPhone 17 # Android: an AVD profile id such as pixel_7
|
||||
# pose: open # a foldable (iPhone Duo): closed (the outer display, how a session starts) | half-open | open (the inner display)
|
||||
exploration:
|
||||
scope: changes # changes | all
|
||||
capture:
|
||||
# controller: agent-device # agent-device (default) | argent (one appearance per capture until Argent can switch it; --controller overrides it for one run)
|
||||
maxMinutes: 30
|
||||
maxActions: 500
|
||||
repack: eas # eas (hosted EAS workflow job, default) | local (repack-app + eas upload on the runner)
|
||||
|
||||
Generated
+2
-2
@@ -12,9 +12,7 @@
|
||||
"@expo/repack-app": "0.10.1",
|
||||
"@types/node": "^22.19.19",
|
||||
"@zip.js/zip.js": "2.16.0",
|
||||
"agent-device": "0.21.15",
|
||||
"ajv": "^8.17.1",
|
||||
"eas-cli": "25.0.0",
|
||||
"pngjs": "7.0.0",
|
||||
"typescript": "^5.9.3",
|
||||
"yaml": "^2.9.0",
|
||||
@@ -31,6 +29,7 @@
|
||||
"@types/react-dom": "^19.2.4",
|
||||
"@vitejs/plugin-react": "^4.7.0",
|
||||
"@xyflow/react": "^12.11.3",
|
||||
"agent-device": "0.21.15",
|
||||
"babel-plugin-react-compiler": "^1.0.0",
|
||||
"eslint": "^10.12.0",
|
||||
"eslint-plugin-react-hooks": "^7.1.1",
|
||||
@@ -4584,6 +4583,7 @@
|
||||
"version": "0.21.15",
|
||||
"resolved": "https://registry.npmjs.org/agent-device/-/agent-device-0.21.15.tgz",
|
||||
"integrity": "sha512-Om1j6oNJkeKlkk8lBM+0V9bKwpxUXLMf/PDDSvAt3RFquBRqAiM58J81E0rvPQNxs6GCjhABYpwVvIAXptxjjA==",
|
||||
"dev": true,
|
||||
"license": "MIT",
|
||||
"bin": {
|
||||
"agent-device": "bin/agent-device.mjs"
|
||||
|
||||
+1
-1
@@ -63,7 +63,6 @@
|
||||
"@expo/repack-app": "0.10.1",
|
||||
"@types/node": "^22.19.19",
|
||||
"@zip.js/zip.js": "2.16.0",
|
||||
"agent-device": "0.21.15",
|
||||
"ajv": "^8.17.1",
|
||||
"pngjs": "7.0.0",
|
||||
"typescript": "^5.9.3",
|
||||
@@ -83,6 +82,7 @@
|
||||
"@types/react-dom": "^19.2.4",
|
||||
"@vitejs/plugin-react": "^4.7.0",
|
||||
"@xyflow/react": "^12.11.3",
|
||||
"agent-device": "0.21.15",
|
||||
"babel-plugin-react-compiler": "^1.0.0",
|
||||
"eslint": "^10.12.0",
|
||||
"eslint-plugin-react-hooks": "^7.1.1",
|
||||
|
||||
@@ -24,8 +24,8 @@ Platform, bundle id, app name and version are read from the archive; do not pass
|
||||
## What happens
|
||||
|
||||
1. Archive inspection and compatibility checks (size, simulator build, emulator ABI, sha256).
|
||||
2. `eas simulator:start` of an empty agent-device session, verified by exact session id before use.
|
||||
3. `agent-device install` of the archive straight into the session, then `open <bundle id>`.
|
||||
2. `eas simulator:start` of an empty agent-device session (an `argent` one with `--controller argent`), verified by exact session id before use.
|
||||
3. `agent-device install` of the archive straight into the session (Argent: `reinstall-app`), then `open <bundle id>`.
|
||||
4. The model explores through a small tool set (observe, act, capture, finish); app text is treated as untrusted and destructive controls (delete, reset, sign out, purchase, send, share) are blocked outside the model.
|
||||
5. The map and screenshots are written under `--output` (default `./explore-<archive>-<timestamp>`), plus `report/` for the Viewer.
|
||||
6. The report is sealed and deployed to EAS Hosting (`--no-upload` skips this; `--expires-in 7d|30d|never`).
|
||||
@@ -65,14 +65,14 @@ The model only ever sees the reference; Explore types the value into the field.
|
||||
|
||||
## Already have a session? `explore:session`
|
||||
|
||||
When the app is already installed on an agent-device EAS Simulator session you started (for example after `eas simulator:start --type agent-device --out-config-type dotenv`, `agent-device install ...`, `agent-device open ...`), skip intake and install:
|
||||
When the app is already installed on an EAS Simulator session you started (for example after `eas simulator:start --type agent-device --out-config-type dotenv`, `agent-device install ...`, `agent-device open ...`; an `--type argent` session works the same way, with Argent's tools), skip intake and install:
|
||||
|
||||
```sh
|
||||
npx @expo/explore explore:session # session from ./.env.eas-simulator or EAS_SIMULATOR_SESSION_ID; explores the app in the foreground
|
||||
npx @expo/explore explore:session <session-id> --env-file path/.env.eas-simulator --bundle-id dev.brent.euxy --json
|
||||
```
|
||||
|
||||
The app is whatever is in the foreground, else the only user-installed app; pass `--bundle-id` when neither is clear (`BUNDLE_ID_REQUIRED` lists what is installed); `--app-name`/`--app-version` label the report. The session is checked with `eas simulator:get` (must be agent-device, in progress, and the same daemon as the connection you passed), your existing `agent-device` session on the device is reused, and the same model, budgets, hints and destructive-action flags apply. The map and `report/` are written under `--output` and opened in the local Viewer (`--port N`); `--no-open` skips that and `--upload` hosts the report instead. The session is never stopped: the output ends with the `eas simulator:stop --id ...` command for when you are done.
|
||||
The app is whatever is in the foreground, else the only user-installed app; pass `--bundle-id` when neither is clear (`BUNDLE_ID_REQUIRED` lists what is installed); `--app-name`/`--app-version` label the report. The session is checked with `eas simulator:get` (must be the controller type its connection names, agent-device or argent, in progress, and the same endpoint as the connection you passed; `--controller` must agree with it), your existing `agent-device` session on the device is reused, and the same model, budgets, hints and destructive-action flags apply. The map and `report/` are written under `--output` and opened in the local Viewer (`--port N`); `--no-open` skips that and `--upload` hosts the report instead. The session is never stopped: the output ends with the `eas simulator:stop --id ...` command for when you are done.
|
||||
|
||||
## An Expo project and no build: run it from source
|
||||
|
||||
|
||||
@@ -233,7 +233,7 @@ async function hashDirectory(root: string, maxBytes: number): Promise<{ sha256:
|
||||
type TarVisitor = (entry: { name: string; type: string; size: number; mode: number }, contents: () => Promise<Buffer>, skip: () => Promise<void>) => Promise<boolean | void>;
|
||||
|
||||
/** Walk a gzip tarball once; `visit` returns true to stop. Long GNU names are honoured; nothing is written. */
|
||||
async function walkTar(path: string, visit: TarVisitor): Promise<void> {
|
||||
export async function walkTar(path: string, visit: TarVisitor): Promise<void> {
|
||||
const stream = createReadStream(path).pipe(createGunzip());
|
||||
const iterator = stream[Symbol.asyncIterator]();
|
||||
let buffer = Buffer.alloc(0);
|
||||
@@ -296,7 +296,7 @@ async function tarEntry(path: string, match: (name: string) => boolean): Promise
|
||||
return found;
|
||||
}
|
||||
|
||||
function safeRelativePath(name: string): string | undefined {
|
||||
export function safeRelativePath(name: string): string | undefined {
|
||||
const parts = name.replace(/^\.\//, "").split("/").filter(part => part.length);
|
||||
if (!parts.length || parts.some(part => part === "." || part === ".." || part.includes("\\") || part.includes("\0"))) return undefined;
|
||||
return parts.join("/");
|
||||
|
||||
@@ -7,7 +7,7 @@ import type { CaptureSetupAction } from "../config/explore-config.js";
|
||||
import { createExplorationInputs, explorationSecretNames } from "../config/exploration-inputs.js";
|
||||
import type { ExploreStore, PreparedArtifact } from "../map/store.js";
|
||||
import { CiError } from "../shared/ci-errors.js";
|
||||
import type { ActionKind, ActionRisk, Artifact, ElementRole, ExploreMap, ObservedElement, Observation, Screen } from "../types.js";
|
||||
import type { ActionKind, ActionRisk, Artifact, Controller, ElementRole, ExploreMap, ObservedElement, Observation, Screen } from "../types.js";
|
||||
|
||||
/** One look at the device: accessibility always, a PNG when the host could take a safe one. */
|
||||
export type BlackBoxFrame = {
|
||||
@@ -278,7 +278,7 @@ function markPressableGroups(nodes: readonly Record<string, unknown>[]): void {
|
||||
}
|
||||
}
|
||||
|
||||
export function elementsOf(nodes: readonly Record<string, unknown>[], allow: readonly string[]): Array<Omit<ObservedElement, "elementId">> {
|
||||
export function elementsOf(nodes: readonly Record<string, unknown>[], allow: readonly string[], controller: Controller = "agent-device"): Array<Omit<ObservedElement, "elementId">> {
|
||||
markPressableGroups(nodes);
|
||||
const occurrences = new Map<string, number>();
|
||||
const out: Array<Omit<ObservedElement, "elementId">> = [];
|
||||
@@ -306,7 +306,7 @@ export function elementsOf(nodes: readonly Record<string, unknown>[], allow: rea
|
||||
const occurrence = (occurrences.get(key) ?? 0) + 1;
|
||||
occurrences.set(key, occurrence);
|
||||
const rect = node.rect && typeof node.rect === "object" ? node.rect as Record<string, unknown> : undefined;
|
||||
out.push({ role, label, ...(identifier ? { identifier } : {}), occurrence, controller: "agent-device",
|
||||
out.push({ role, label, ...(identifier ? { identifier } : {}), occurrence, controller,
|
||||
actions: role === "field" ? ["fill"] : role === "toggle" ? ["press"] : ["press"],
|
||||
risk: riskOf(label, allow), actionable: true, enabled: node.enabled !== false, visible: true,
|
||||
...(rect && typeof rect.x === "number" && typeof rect.y === "number" && typeof rect.width === "number" && typeof rect.height === "number"
|
||||
@@ -497,7 +497,7 @@ export async function runBlackBoxExploration(options: BlackBoxExplorerOptions):
|
||||
for (const part of loose) seen.parts.add(part);
|
||||
seen.loadingOnly &&= loading;
|
||||
evidence.set(screen.id, seen);
|
||||
for (const element of elementsOf(frame.nodes, allow)) {
|
||||
for (const element of elementsOf(frame.nodes, allow, map.run.controller)) {
|
||||
const id = elementId(screen.id, element);
|
||||
if (!screen.elementIds.includes(id)) {
|
||||
screen.elementIds.push(id);
|
||||
@@ -538,7 +538,7 @@ export async function runBlackBoxExploration(options: BlackBoxExplorerOptions):
|
||||
}
|
||||
screenshotArtifactId = artifact.id;
|
||||
}
|
||||
const elements = elementsOf(frame.nodes, allow).map(element => ({ elementId: elementId(screen.id, element), ...element }));
|
||||
const elements = elementsOf(frame.nodes, allow, map.run.controller).map(element => ({ elementId: elementId(screen.id, element), ...element }));
|
||||
const observation: Observation = { id: observationId, screenId: screen.id, variantId: variant.id, capturedAt: frame.capturedAt, surfaceScope: "app",
|
||||
fingerprints: { combined: screenEvidenceKey(frame.nodes), accessibility: accessibilitySha, ...(screenshotArtifactId ? { visual: map.artifacts.find(item => item.id === screenshotArtifactId)!.sha256 } : {}) },
|
||||
elementIds: elements.map(element => element.elementId), elements, accessibilityArtifactId: accessibilityArtifact.id, ...(screenshotArtifactId ? { screenshotArtifactId } : {}) };
|
||||
|
||||
+54
-21
@@ -6,12 +6,14 @@ import { join } from "node:path";
|
||||
import { createCiAgentSession, type CiAgentSession, type CiAgentSessionConfig } from "../capture/agent/session.js";
|
||||
import { createLocalCiAgentSession } from "../capture/agent/session-local.js";
|
||||
import type { CiAgentProviderName } from "../capture/agent/provider.js";
|
||||
import { AGENT_DEVICE_VERSION, CONTROLLER_SESSION, baseEnvironment, isRecord } from "../capture/common.js";
|
||||
import { CONTROLLER_SESSION, baseEnvironment, isRecord } from "../capture/common.js";
|
||||
import { controllerData, defaultRunner, openedSimulatorDevice } from "../capture/controller.js";
|
||||
import type { CommandRequest, CommandResult } from "../capture/run.js";
|
||||
import { executeCaptureSetup } from "../capture/setup-actions.js";
|
||||
import { SIMULATOR_DOTENV_FILE_NAME, SIMULATOR_DOTENV_HEADER, assertSimulatorSessionIdentity, assertSimulatorStopped, readSimulatorDotenvHandoff,
|
||||
assertAttachedSimulatorSession, resolveAttachedSimulatorSession, simulatorOsVersion, simulatorStartFailure, type ActiveSimulatorRuntime, type SimulatorConnection } from "../capture/simulator.js";
|
||||
assertAttachedSimulatorSession, connectionController, controllerVersion, resolveAttachedSimulatorSession, simulatorOsVersion, simulatorStartFailure, type ActiveSimulatorRuntime, type SimulatorConnection } from "../capture/simulator.js";
|
||||
import { argentControllerInvocation } from "../capture/controller-invocation.js";
|
||||
import { agentDeviceLauncher, ensureController } from "../shared/controller-cache.js";
|
||||
import { DEFAULT_ANDROID_DEVICE } from "../config/explore-config.js";
|
||||
import { createExplorationInputs } from "../config/exploration-inputs.js";
|
||||
import { ExploreStore, getCoverage } from "../map/store.js";
|
||||
@@ -46,6 +48,8 @@ export type BinaryExploreOptions = {
|
||||
owner?: string;
|
||||
/** EAS project slug the sessions run under; created on first use. */
|
||||
project?: string;
|
||||
/** The session's device controller; agent-device unless Argent is chosen. explore:session takes it from the session. */
|
||||
controller?: "agent-device" | "argent";
|
||||
environment?: NodeJS.ProcessEnv;
|
||||
runner?: typeof defaultRunner;
|
||||
createSession?: (config: CiAgentSessionConfig, options: { env: NodeJS.ProcessEnv; auth: ModelAuth }) => CiAgentSession;
|
||||
@@ -64,10 +68,19 @@ export type BinaryExploreResult = {
|
||||
durationMs: number;
|
||||
};
|
||||
|
||||
/** The command and environment that reach a session's controller: agent-device's CLI with its daemon, or the Argent bridge. */
|
||||
type ControllerInvocation = { command: string; environment: NodeJS.ProcessEnv };
|
||||
|
||||
async function argentInvocation(connection: SimulatorConnection, work: string, platform: Platform, environment: NodeJS.ProcessEnv, bundleId?: string): Promise<ControllerInvocation> {
|
||||
return argentControllerInvocation({ directory: work, connection, platform, environment: baseEnvironment(environment), sourceEnvironment: environment, ...(bundleId ? { bundleId } : {}) });
|
||||
}
|
||||
|
||||
/** The daemon refuses a second session on a busy device; the caller's own `agent-device` session (from install/open) is reused instead. */
|
||||
function daemonSessions(runner: typeof defaultRunner, connection: SimulatorConnection, work: string, platform: Platform, environment: NodeJS.ProcessEnv): { name: string; device: string }[] {
|
||||
// Argent has no named sessions to share; its tool-server serves every caller.
|
||||
if (connectionController(connection) === "argent") return [];
|
||||
try {
|
||||
const result = runner({ command: packageBin("agent-device", "agent-device"), args: ["session", "list", "--json"], cwd: work, timeoutMs: 60_000,
|
||||
const result = runner({ command: agentDeviceLauncher(environment), args: ["session", "list", "--json"], cwd: work, timeoutMs: 60_000,
|
||||
environment: { ...baseEnvironment(environment), AGENT_DEVICE_DAEMON_BASE_URL: connection.daemonBaseUrl, AGENT_DEVICE_DAEMON_AUTH_TOKEN: connection.daemonAuthToken } });
|
||||
const data = controllerData(result.stdout, "session list");
|
||||
const sessions = Array.isArray(data.sessions) ? data.sessions : [];
|
||||
@@ -119,11 +132,11 @@ const named = (apps: { bundleId: string | undefined; name: string | undefined }[
|
||||
};
|
||||
|
||||
/** Finds the app to explore when the caller named none: the one the session has in the foreground, else the only user-installed app. */
|
||||
export function resolveSessionApp(runner: typeof defaultRunner, connection: SimulatorConnection, work: string, platform: Platform, device: string, controllerSession: string | undefined, environment: NodeJS.ProcessEnv): { bundleId: string; name?: string } {
|
||||
export function resolveSessionApp(runner: typeof defaultRunner, connection: SimulatorConnection, work: string, platform: Platform, device: string, controllerSession: string | undefined, environment: NodeJS.ProcessEnv, invocation?: ControllerInvocation): { bundleId: string; name?: string } {
|
||||
const run = (args: string[]): Record<string, unknown> | undefined => {
|
||||
try {
|
||||
const result = runner({ command: packageBin("agent-device", "agent-device"), args: [...args, ...(platform === "ios" ? ["--device", device] : []), "--platform", platform, "--json"], cwd: work, timeoutMs: 60_000,
|
||||
environment: { ...baseEnvironment(environment), AGENT_DEVICE_DAEMON_BASE_URL: connection.daemonBaseUrl, AGENT_DEVICE_DAEMON_AUTH_TOKEN: connection.daemonAuthToken } });
|
||||
const result = runner({ command: invocation?.command ?? agentDeviceLauncher(environment), args: [...args, ...(platform === "ios" ? ["--device", device] : []), "--platform", platform, "--json"], cwd: work, timeoutMs: 60_000,
|
||||
environment: invocation?.environment ?? { ...baseEnvironment(environment), AGENT_DEVICE_DAEMON_BASE_URL: connection.daemonBaseUrl, AGENT_DEVICE_DAEMON_AUTH_TOKEN: connection.daemonAuthToken } });
|
||||
return controllerData(result.stdout, args[0]!);
|
||||
} catch { return undefined; }
|
||||
};
|
||||
@@ -260,11 +273,20 @@ export type ConnectedSessionExploration = {
|
||||
export async function exploreConnectedSession(ctx: ConnectedSessionExploration): Promise<{ runtime: ActiveSimulatorRuntime; exploration: BlackBoxExplorerResult }> {
|
||||
const { connection, platform, device, bundleId, app, install, work, runner, environment, secrets, inputs, say, now, limits, store, map, model, sessionJson, launchUrl, hints, allowDestructive } = ctx;
|
||||
const controllerSession = ctx.controllerSession ?? CONTROLLER_SESSION;
|
||||
const controllerConfig = join(work, "agent-device.json");
|
||||
await writeFile(controllerConfig, "{}\n", { flag: "wx", mode: 0o400 });
|
||||
const controllerEnvironment = { ...baseEnvironment(environment), AGENT_DEVICE_CONFIG: controllerConfig, AGENT_DEVICE_DAEMON_BASE_URL: connection.daemonBaseUrl,
|
||||
AGENT_DEVICE_DAEMON_AUTH_TOKEN: connection.daemonAuthToken, AGENT_DEVICE_SESSION: controllerSession, AGENT_DEVICE_SESSION_LOCK: "reject", AGENT_DEVICE_PLATFORM: platform };
|
||||
const agentDevice = packageBin("agent-device", "agent-device");
|
||||
const controllerKind = connectionController(connection);
|
||||
const controllerName = controllerKind === "argent" ? "Argent" : "agent-device";
|
||||
if (controllerKind === "argent") await ensureController("argent", { environment, progress: say });
|
||||
let agentDevice: string;
|
||||
let controllerEnvironment: NodeJS.ProcessEnv;
|
||||
if (controllerKind === "argent") {
|
||||
({ command: agentDevice, environment: controllerEnvironment } = await argentInvocation(connection, work, platform, environment, bundleId));
|
||||
} else {
|
||||
const controllerConfig = join(work, "agent-device.json");
|
||||
await writeFile(controllerConfig, "{}\n", { flag: "wx", mode: 0o400 });
|
||||
controllerEnvironment = { ...baseEnvironment(environment), AGENT_DEVICE_CONFIG: controllerConfig, AGENT_DEVICE_DAEMON_BASE_URL: connection.daemonBaseUrl,
|
||||
AGENT_DEVICE_DAEMON_AUTH_TOKEN: connection.daemonAuthToken, AGENT_DEVICE_SESSION: controllerSession, AGENT_DEVICE_SESSION_LOCK: "reject", AGENT_DEVICE_PLATFORM: platform };
|
||||
agentDevice = agentDeviceLauncher(environment);
|
||||
}
|
||||
const deviceArgs = platform === "ios" ? ["--device", device] : [];
|
||||
const controller = (args: string[], timeoutMs = 90_000): CommandResult => {
|
||||
// Session flags go before a `--` separator so model-chosen text (`type -h`, a URL, a label) is never read as a flag.
|
||||
@@ -275,22 +297,23 @@ export async function exploreConnectedSession(ctx: ConnectedSessionExploration):
|
||||
};
|
||||
const failureText = (error: unknown): string => lastLine(redactSecrets(error instanceof Error ? error.message : String(error), secrets)).slice(0, 400);
|
||||
const version = runner({ command: agentDevice, args: ["--version"], cwd: work, environment: controllerEnvironment, timeoutMs: 30_000 }).stdout.trim();
|
||||
if (version !== AGENT_DEVICE_VERSION) throw binaryError("EXPLORE_TOOLS_MISSING", `agent-device ${AGENT_DEVICE_VERSION} is required (found ${version || "none"}).`, "Reinstall @expo/explore.");
|
||||
if (version !== controllerVersion(controllerKind)) throw binaryError("EXPLORE_TOOLS_MISSING", `${controllerName} ${controllerVersion(controllerKind)} is required (found ${version || "none"}).`, "Reinstall @expo/explore.");
|
||||
|
||||
if (install) {
|
||||
say(`installing ${install.kind === "android-apk" ? "the APK" : "the app"} on session ${connection.sessionId}`);
|
||||
try { controller(["install", install.path, "--json"], 15 * 60_000); }
|
||||
catch (error) { throw binaryError("APP_INSTALL_FAILED", `agent-device could not install the app: ${failureText(error)}`, "Check that the archive is a simulator build for this platform and under the size limit, then rerun.", { sessionId: connection.sessionId }); }
|
||||
catch (error) { throw binaryError("APP_INSTALL_FAILED", `${controllerName} could not install the app: ${failureText(error)}`, "Check that the archive is a simulator build for this platform and under the size limit, then rerun.", { sessionId: connection.sessionId }); }
|
||||
}
|
||||
const opened = controller(["open", bundleId, "--level", "full", "--json"], 2 * 60_000);
|
||||
const openedDevice = openedSimulatorDevice(opened.stdout, bundleId, "initial app open", platform, controllerSession);
|
||||
const data = controllerData(opened.stdout, "initial app open");
|
||||
const deviceData = data.device && typeof data.device === "object" ? data.device as Record<string, unknown> : {};
|
||||
const observed = (key: string): string => { const value = deviceData[key] ?? data[key]; return typeof value === "string" && value.trim() ? value : "unknown"; };
|
||||
const runtime = { provider: "eas-simulator", controller: "agent-device", controllerPackageVersion: AGENT_DEVICE_VERSION, easCliVersion: "unknown", platform, controllerDeviceId: openedDevice.deviceId,
|
||||
const runtime = { provider: "eas-simulator", controller: controllerKind, controllerPackageVersion: controllerVersion(controllerKind), easCliVersion: "unknown", platform, controllerDeviceId: openedDevice.deviceId,
|
||||
deviceModel: openedDevice.deviceModel, osVersion: observed("osVersion"), locale: observed("locale"), orientation: observed("orientation") === "landscape" ? "landscape" : "portrait",
|
||||
colorScheme: observed("colorScheme") === "dark" ? "dark" : "light" } as ActiveSimulatorRuntime;
|
||||
try { runtime.osVersion = await simulatorOsVersion(sessionJson(), runtime.controllerDeviceId, fetch, platform); } catch { /* descriptive only */ }
|
||||
// Argent's `open` reports the OS version itself (list-devices); agent-device's comes from the session's preview.
|
||||
if (runtime.osVersion === "unknown" || controllerKind !== "argent") try { runtime.osVersion = await simulatorOsVersion(sessionJson(), runtime.controllerDeviceId, fetch, platform); } catch { /* descriptive only */ }
|
||||
map.run.deviceId = runtime.controllerDeviceId;
|
||||
map.run.environment = { deviceModel: runtime.deviceModel, osVersion: runtime.osVersion, locale: runtime.locale, orientation: runtime.orientation, colorScheme: runtime.colorScheme };
|
||||
map.run.status = "exploring";
|
||||
@@ -474,7 +497,13 @@ export async function runSessionExploration(options: SessionExploreOptions): Pro
|
||||
try { connection = await resolveAttachedSimulatorSession(environment, options.envFile, options.session); }
|
||||
catch (error) {
|
||||
throw binaryError("SESSION_NOT_PROVIDED", `No EAS Simulator session connection was found: ${error instanceof Error ? error.message : String(error)}`,
|
||||
"Start one with `eas simulator:start --type agent-device --out-config-type dotenv` and run explore:session in that directory (or pass --env-file / set EAS_SIMULATOR_SESSION_ID, AGENT_DEVICE_DAEMON_BASE_URL and AGENT_DEVICE_DAEMON_AUTH_TOKEN).");
|
||||
"Start one with `eas simulator:start --type agent-device --out-config-type dotenv` (or `--type argent`) and run explore:session in that directory (or pass --env-file / set EAS_SIMULATOR_SESSION_ID with AGENT_DEVICE_DAEMON_BASE_URL and AGENT_DEVICE_DAEMON_AUTH_TOKEN, or ARGENT_TOOLS_URL).");
|
||||
}
|
||||
const sessionController = connectionController(connection);
|
||||
if (!options.runner) await ensureController(sessionController, { environment, progress: say });
|
||||
if (options.controller && options.controller !== sessionController) {
|
||||
throw binaryError("CONTROLLER_MISMATCH", `--controller ${options.controller} was passed, but the session is driven by ${sessionController}.`,
|
||||
`Drop --controller, or start a session with \`eas simulator:start --type ${options.controller}\`.`, { sessionId: connection.sessionId });
|
||||
}
|
||||
if (!environment.EXPO_TOKEN?.trim() && !environment.EXPO_SESSION_SECRET?.trim() && !(await easLoggedIn(runner, environment))) {
|
||||
throw binaryError("EXPO_LOGIN_REQUIRED", "No EAS login was found.", "Run `eas login` or set EXPO_TOKEN, then rerun explore:session.");
|
||||
@@ -495,7 +524,7 @@ export async function runSessionExploration(options: SessionExploreOptions): Pro
|
||||
let device = options.device ?? "";
|
||||
const app = { name: options.appName ?? options.bundleId ?? "app", bundleId: options.bundleId ?? "app", ...(options.version ? { version: options.version } : {}) };
|
||||
const secrets = [environment.EXPO_TOKEN ?? "", connection.daemonAuthToken, ...inputs.values].filter(Boolean);
|
||||
const map: ExploreMap = { contract: CONTRACT, revision: 0, run: { id: randomUUID(), name: app.name, platform, controller: "agent-device", exploration: "black-box", bundleId: app.bundleId, status: "draft",
|
||||
const map: ExploreMap = { contract: CONTRACT, revision: 0, run: { id: randomUUID(), name: app.name, platform, controller: sessionController, exploration: "black-box", bundleId: app.bundleId, status: "draft",
|
||||
createdAt: new Date(now()).toISOString(), updatedAt: new Date(now()).toISOString(), build: { ...(app.version ? { version: app.version } : {}), source: "unknown" }, environment: {}, limits },
|
||||
artifacts: [], screens: [], variants: [], observations: [], elements: [], actionAttempts: [], transitions: [], journeys: [], frontier: [], gaps: [] };
|
||||
try {
|
||||
@@ -504,7 +533,7 @@ export async function runSessionExploration(options: SessionExploreOptions): Pro
|
||||
try { info = assertAttachedSimulatorSession(sessionJson(), connection, options.platform); }
|
||||
catch (error) {
|
||||
throw binaryError("SESSION_UNAVAILABLE", `EAS Simulator session ${connection.sessionId} cannot be explored: ${lastLine(redactSecrets(error instanceof Error ? error.message : String(error), secrets))}`,
|
||||
"Check `eas simulator:list`; the session must be in progress, of type agent-device, and match the connection you passed.", { sessionId: connection.sessionId });
|
||||
`Check \`eas simulator:list\`; the session must be in progress, of type ${sessionController}, and match the connection you passed.`, { sessionId: connection.sessionId });
|
||||
}
|
||||
platform = info.platform;
|
||||
const candidates = daemonSessions(runner, connection, work, platform, environment).filter(item => !device || item.device === device);
|
||||
@@ -514,7 +543,8 @@ export async function runSessionExploration(options: SessionExploreOptions): Pro
|
||||
if (existing) say(`reusing agent-device session "${existing.name}" on ${existing.device}`);
|
||||
device = device || existing?.device || (platform === "ios" ? DEFAULT_IOS_DEVICE : DEFAULT_ANDROID_DEVICE);
|
||||
if (!options.bundleId) {
|
||||
const resolved = resolveSessionApp(runner, connection, work, platform, device, existing?.name, environment);
|
||||
const resolved = resolveSessionApp(runner, connection, work, platform, device, existing?.name, environment,
|
||||
sessionController === "argent" ? await argentInvocation(connection, work, platform, environment) : undefined);
|
||||
app.bundleId = resolved.bundleId;
|
||||
if (!options.appName) app.name = resolved.name ?? app.bundleId;
|
||||
map.run.bundleId = app.bundleId;
|
||||
@@ -582,7 +612,10 @@ export async function runBinaryExploration(options: BinaryExploreOptions): Promi
|
||||
let exploration: BlackBoxExplorerResult | undefined;
|
||||
let owner = options.owner ?? "";
|
||||
const project = options.project ?? DEFAULT_BINARY_PROJECT;
|
||||
const map: ExploreMap = { contract: CONTRACT, revision: 0, run: { id: randomUUID(), name: archive.appName, platform, controller: "agent-device", exploration: "black-box", bundleId, status: "draft",
|
||||
const controller = options.controller ?? "agent-device";
|
||||
// Fetched before the paid session starts, so a blocked download costs nothing.
|
||||
if (!options.runner) await ensureController(controller, { environment, progress: say });
|
||||
const map: ExploreMap = { contract: CONTRACT, revision: 0, run: { id: randomUUID(), name: archive.appName, platform, controller, exploration: "black-box", bundleId, status: "draft",
|
||||
createdAt: new Date(now()).toISOString(), updatedAt: new Date(now()).toISOString(),
|
||||
build: { ...(archive.version ? { version: archive.version } : {}), ...(archive.buildNumber ? { number: archive.buildNumber } : {}), hash: archive.sha256, source: "local" },
|
||||
environment: { deviceModel: device }, limits }, artifacts: [], screens: [], variants: [], observations: [], elements: [], actionAttempts: [], transitions: [], journeys: [], frontier: [], gaps: [] };
|
||||
@@ -610,7 +643,7 @@ export async function runBinaryExploration(options: BinaryExploreOptions): Promi
|
||||
await writeFile(dotenvPath, SIMULATOR_DOTENV_HEADER, { flag: "wx", mode: 0o600 });
|
||||
let startError: unknown;
|
||||
try {
|
||||
const started = eas(["simulator:start", "--name", sessionName, "--platform", platform, "--device", device, "--type", "agent-device", "--package-version", AGENT_DEVICE_VERSION, "--public-link",
|
||||
const started = eas(["simulator:start", "--name", sessionName, "--platform", platform, "--device", device, "--type", controller, "--package-version", controllerVersion(controller), "--public-link",
|
||||
"--max-duration-minutes", String(limits.maxDurationMinutes + 5), "--out-config-type", "dotenv", "--non-interactive"], 20 * 60_000);
|
||||
if (started.status !== 0) throw new Error(started.stderr || started.stdout || "eas simulator:start failed");
|
||||
} catch (error) { startError = error; }
|
||||
|
||||
@@ -18,6 +18,19 @@ export function resolveColorSchemes(appearance: AppearanceSetting, appConfig: Re
|
||||
return ["light"];
|
||||
}
|
||||
|
||||
/**
|
||||
* What an Argent capture renders: one pass, since Argent cannot switch the device's appearance yet
|
||||
* (software-mansion/argent#1509). An app that forces a style renders it on any device; any other app renders as the
|
||||
* fresh simulator starts, light. Requested schemes that pass cannot show are reported as skipped.
|
||||
*/
|
||||
export function argentColorSchemes(requested: readonly ColorScheme[], appConfig: Record<string, unknown> | undefined, platform: string): { schemes: ColorScheme[]; skipped: ColorScheme[] } {
|
||||
const platformConfig = appConfig?.[platform];
|
||||
const declared = (platformConfig && typeof platformConfig === "object" ? (platformConfig as Record<string, unknown>).userInterfaceStyle : undefined)
|
||||
?? appConfig?.userInterfaceStyle;
|
||||
const scheme: ColorScheme = declared === "dark" ? "dark" : "light";
|
||||
return { schemes: [scheme], skipped: requested.filter(item => item !== scheme) };
|
||||
}
|
||||
|
||||
export function parseAppearance(value: unknown, path: string): AppearanceSetting {
|
||||
if (value === undefined || value === "auto") return "auto";
|
||||
const list = Array.isArray(value) ? value : [value];
|
||||
|
||||
@@ -0,0 +1,143 @@
|
||||
/**
|
||||
* The Argent controller's command line: Explore runs it where it would run agent-device, with the same
|
||||
* arguments. Each command becomes `argent run <tool> --args <json>` calls, as EAS Simulator recommends
|
||||
* driving an `argent` session, with the session's ARGENT_TOOLS_URL and ARGENT_AUTH_TOKEN in the environment.
|
||||
*/
|
||||
import { spawnSync } from "node:child_process";
|
||||
import { appendFile, copyFile, mkdir, readFile, realpath, rename, rm, stat, writeFile } from "node:fs/promises";
|
||||
import { dirname, join } from "node:path";
|
||||
import { createRequire } from "node:module";
|
||||
import type { DecodedFrame } from "../shared/png-evidence.js";
|
||||
import { ArgentCallError, runBridgeCommand, type ArgentBridgeState, type ArgentPlatform, type ArgentTree } from "./argent-driver.js";
|
||||
import { ARGENT_VERSION } from "../shared/argent-version.js";
|
||||
import { ensureController } from "../shared/controller-cache.js";
|
||||
|
||||
const ARGENT_CALL_TIMEOUT_MS = 180_000;
|
||||
|
||||
async function readState(path: string): Promise<ArgentBridgeState> {
|
||||
try { return JSON.parse(await readFile(path, "utf8")) as ArgentBridgeState; }
|
||||
catch { return { generation: 0 }; }
|
||||
}
|
||||
|
||||
/** Written whole and renamed into place, so a command stopped mid-write never leaves a torn state. */
|
||||
async function writeState(path: string, state: ArgentBridgeState): Promise<void> {
|
||||
const temporary = `${path}.${process.pid}.tmp`;
|
||||
await writeFile(temporary, JSON.stringify(state), { mode: 0o600 });
|
||||
await rename(temporary, path);
|
||||
}
|
||||
|
||||
/** A call's arguments for the debug log: text that could be typed into a field is logged by length only. */
|
||||
function loggedArgs(args: Record<string, unknown>): Record<string, unknown> {
|
||||
return Object.fromEntries(Object.entries(args).map(([key, value]) => key === "text" && typeof value === "string" ? [key, `<${value.length} characters>`]
|
||||
: key === "steps" && Array.isArray(value) ? [key, `<${value.length} steps>`] : [key, value]));
|
||||
}
|
||||
|
||||
/** What a call answered, for the debug log: a tree's shape, not its contents. */
|
||||
function summarize(tool: string, value: unknown): unknown {
|
||||
if (!value || typeof value !== "object") return value;
|
||||
if (tool !== "ui-tree") return Object.keys(value);
|
||||
const tree = value as ArgentTree;
|
||||
let nodes = 0;
|
||||
const walk = (node: { children?: unknown[] }) => { nodes++; (node.children ?? []).forEach(child => walk(child as { children?: unknown[] })); };
|
||||
(tree.roots ?? []).forEach(walk);
|
||||
return { foregroundApp: tree.foregroundApp, alertVisible: tree.alertVisible, keyboardVisible: tree.keyboardVisible, truncated: tree.truncated,
|
||||
screen: tree.screen, nodes, roots: (tree.roots ?? []).map(root => [root.type ?? null, root.bundleId ?? null, (root.children ?? []).length]) };
|
||||
}
|
||||
|
||||
async function main(): Promise<number> {
|
||||
const environment = process.env;
|
||||
const statePath = environment.EXPLORE_ARGENT_STATE;
|
||||
const platform = environment.EXPLORE_ARGENT_PLATFORM as ArgentPlatform | undefined;
|
||||
const toolsUrl = environment.ARGENT_TOOLS_URL;
|
||||
if (!statePath || (platform !== "ios" && platform !== "android")) {
|
||||
process.stdout.write(JSON.stringify({ success: false, error: { code: "INVALID_ARGS", message: "The Argent controller needs EXPLORE_ARGENT_STATE and EXPLORE_ARGENT_PLATFORM." } }));
|
||||
return 1;
|
||||
}
|
||||
const argv = process.argv.slice(2);
|
||||
if (argv[0] !== "--version" && !toolsUrl) {
|
||||
// Without a URL the Argent client would start a local tool-server; Explore only drives the session's own.
|
||||
process.stdout.write(JSON.stringify({ success: false, error: { code: "INVALID_ARGS", message: "ARGENT_TOOLS_URL is not set for the Argent controller." } }));
|
||||
return 1;
|
||||
}
|
||||
// EXPLORE_ARGENT_LOG_DIR (opt-in): every Argent call this bridge makes, how long it took, and the shape of what it read.
|
||||
const logPath = environment.EXPLORE_ARGENT_LOG_DIR
|
||||
? join(environment.EXPLORE_ARGENT_LOG_DIR, `argent-${platform}-${environment.EXPLORE_ARGENT_LOG_NAME ?? "bridge"}.jsonl`) : undefined;
|
||||
const log = async (entry: Record<string, unknown>) => {
|
||||
if (!logPath) return;
|
||||
await appendFile(logPath, `${JSON.stringify({ at: new Date().toISOString(), command: argv[0], ...entry })}\n`, { mode: 0o600 }).catch(() => undefined);
|
||||
};
|
||||
const state = await readState(statePath);
|
||||
let cli: string;
|
||||
try { cli = argv[0] === "--version" ? "" : await ensureController("argent", { environment, progress: message => process.stderr.write(`[explore] ${message}\n`) }); }
|
||||
catch (error) {
|
||||
const failure = error as { code?: string; message?: string };
|
||||
process.stdout.write(JSON.stringify({ success: false, error: { code: failure.code ?? "CONTROLLER_DOWNLOAD_FAILED", message: failure.message ?? String(error) } }));
|
||||
return 1;
|
||||
}
|
||||
|
||||
const callArgent = async (tool: string, args: Record<string, unknown>, options?: { out?: string }): Promise<unknown> => {
|
||||
const run = spawnSync(process.execPath, [cli, "run", tool, "--args", JSON.stringify(args), ...(options?.out ? ["--out", options.out] : [])],
|
||||
{ env: environment, encoding: "utf8", maxBuffer: 64 * 1024 * 1024, timeout: ARGENT_CALL_TIMEOUT_MS });
|
||||
if (run.error) throw new ArgentCallError(`argent run ${tool}: ${run.error.message}`, true);
|
||||
if (run.status !== 0) {
|
||||
const detail = `${run.stderr ?? ""}\n${run.stdout ?? ""}`.trim().split("\n").filter(Boolean).slice(-4).join(" | ").slice(0, 800);
|
||||
throw new ArgentCallError(`argent run ${tool} failed: ${detail}`, true);
|
||||
}
|
||||
// With --out the client saves the tool's file and prints where ("Wrote: <path>"), not the tool's JSON.
|
||||
if (options?.out) {
|
||||
const written = await stat(options.out).catch(() => undefined);
|
||||
if (!written?.isFile() || written.size === 0) throw new ArgentCallError(`argent run ${tool} did not write ${options.out}`, true);
|
||||
return { path: options.out };
|
||||
}
|
||||
try { return JSON.parse(run.stdout); }
|
||||
catch { throw new ArgentCallError(`argent run ${tool} did not answer with JSON`, true); }
|
||||
};
|
||||
|
||||
const result = await runBridgeCommand(argv, {
|
||||
state, platform, version: ARGENT_VERSION,
|
||||
...(environment.EXPLORE_ARGENT_BUNDLE_ID ? { bundleId: environment.EXPLORE_ARGENT_BUNDLE_ID } : {}),
|
||||
call: async (tool, args, options) => {
|
||||
const started = Date.now();
|
||||
try {
|
||||
const value = await callArgent(tool, args, options);
|
||||
await log({ tool, args: loggedArgs(args), ms: Date.now() - started, summary: summarize(tool, value) });
|
||||
return value;
|
||||
} catch (error) {
|
||||
await log({ tool, args: loggedArgs(args), ms: Date.now() - started, error: (error instanceof Error ? error.message : String(error)).slice(0, 400) });
|
||||
throw error;
|
||||
}
|
||||
},
|
||||
reachable: async () => {
|
||||
let ok = false;
|
||||
try {
|
||||
const token = environment.ARGENT_AUTH_TOKEN;
|
||||
// The same URL Argent's own client checks: ARGENT_TOOLS_URL may carry a path, which /tools is appended to.
|
||||
const response = await fetch(`${(toolsUrl ?? "").replace(/\/+$/, "")}/tools`, { headers: token ? { authorization: `Bearer ${token}` } : {}, signal: AbortSignal.timeout(5_000) });
|
||||
await response.body?.cancel();
|
||||
ok = response.status < 500;
|
||||
} catch { ok = false; }
|
||||
if (!ok) await log({ tool: "reachable", ok });
|
||||
return ok;
|
||||
},
|
||||
sleep: milliseconds => new Promise(resolve => setTimeout(resolve, milliseconds)),
|
||||
scratchImage: { path: join(dirname(statePath), "argent-scratch.png"), read: async path => {
|
||||
const { PNG } = createRequire(import.meta.url)("pngjs") as { PNG: { sync: { read(bytes: Buffer, options: { checkCRC: boolean }): DecodedFrame } } };
|
||||
return PNG.sync.read(await readFile(path), { checkCRC: false });
|
||||
} },
|
||||
moveFile: async (from, to) => {
|
||||
// Argent's client downloads a recording under its HOME or the working directory; nothing else is moved.
|
||||
const source = await realpath(from);
|
||||
const roots = await Promise.all([environment.HOME, process.cwd()].filter((root): root is string => !!root).map(root => realpath(root).catch(() => root)));
|
||||
if (!roots.some(root => source.startsWith(`${root}/`))) throw new Error(`Argent returned a recording outside its own directories: ${from}`);
|
||||
await mkdir(dirname(to), { recursive: true });
|
||||
try { await rename(from, to); }
|
||||
catch { await copyFile(from, to); await rm(from, { force: true }); }
|
||||
},
|
||||
});
|
||||
await writeState(statePath, state);
|
||||
await log({ result: result.exitCode === 0 ? "ok" : result.stdout.slice(0, 300) });
|
||||
process.stdout.write(result.stdout);
|
||||
return result.exitCode;
|
||||
}
|
||||
|
||||
process.exitCode = await main();
|
||||
@@ -0,0 +1,721 @@
|
||||
/**
|
||||
* Translates the agent-device commands Explore sends into Argent tool calls, and Argent's answers into
|
||||
* agent-device's JSON envelopes, so capture, setup, the agent tool host and black-box exploration drive
|
||||
* either controller without knowing which one runs. Pure: the Argent call, the clock and file moves are
|
||||
* injected, so the translation is tested against recorded Argent output.
|
||||
*/
|
||||
import { CONTROLLER_SESSION } from "./common.js";
|
||||
import type { DecodedFrame } from "../shared/png-evidence.js";
|
||||
|
||||
export type ArgentPlatform = "ios" | "android";
|
||||
|
||||
/** One `argent run <tool>` call. `sent: false` means the request provably never reached the tool-server. */
|
||||
export class ArgentCallError extends Error {
|
||||
constructor(message: string, readonly sent: boolean) { super(message); }
|
||||
}
|
||||
|
||||
export type ArgentCall = (tool: string, args: Record<string, unknown>, options?: { out?: string }) => Promise<unknown>;
|
||||
|
||||
type Rect = { x: number; y: number; width: number; height: number };
|
||||
|
||||
/** What the bridge keeps between commands, in the per-run state file. */
|
||||
export type ArgentBridgeState = {
|
||||
udid?: string;
|
||||
model?: string;
|
||||
osVersion?: string;
|
||||
/** The coordinate space of the last tree: points on iOS, pixels on Android, as agent-device reports them. */
|
||||
screen?: { width: number; height: number };
|
||||
generation: number;
|
||||
refs?: Record<string, { rect: Rect; type?: string; value?: string; secure?: boolean }>;
|
||||
/** iOS asks "Open in “<app>”?" for the first custom-scheme link of a session; later links open directly. */
|
||||
deepLinkPromptAccepted?: boolean;
|
||||
recording?: string;
|
||||
};
|
||||
|
||||
export type ArgentBridgeContext = {
|
||||
call: ArgentCall;
|
||||
state: ArgentBridgeState;
|
||||
platform: ArgentPlatform;
|
||||
/** The app under test when the caller names it outside the command (explore:binary's `install`). */
|
||||
bundleId?: string;
|
||||
version: string;
|
||||
sleep: (milliseconds: number) => Promise<void>;
|
||||
/** Moves a file the Argent client downloaded (a screen recording) to where Explore asked for it. */
|
||||
moveFile: (from: string, to: string) => Promise<void>;
|
||||
/** Whether the tool-server answers, checked before a UI action is sent (see `remoteUnavailable`). */
|
||||
reachable: () => Promise<boolean>;
|
||||
/** A file the bridge may overwrite with a screenshot, and a reader for it (the link-prompt fallback). */
|
||||
scratchImage?: { path: string; read: (path: string) => Promise<DecodedFrame> };
|
||||
};
|
||||
|
||||
export type BridgeResult = { exitCode: number; stdout: string };
|
||||
|
||||
const success = (data: Record<string, unknown>): BridgeResult => ({ exitCode: 0, stdout: JSON.stringify({ success: true, data }) });
|
||||
const failure = (code: string, message: string, details?: Record<string, unknown>): BridgeResult =>
|
||||
({ exitCode: 1, stdout: JSON.stringify({ success: false, error: { code, message, ...(details ? { details } : {}) } }) });
|
||||
|
||||
/**
|
||||
* agent-device's answer when its pre-flight health check fails, which Explore resends because the command was
|
||||
* provably never sent (controller.ts remoteDaemonUnavailable). The bridge gives it only on the same proof.
|
||||
*/
|
||||
const remoteUnavailable = () => failure("COMMAND_FAILED", "Remote daemon is unavailable");
|
||||
|
||||
/** Flags agent-device takes after a command; the bridge needs the platform only from its own context. */
|
||||
const VALUE_FLAGS = new Set(["--session", "--device", "--platform", "--level", "--udid", "--scope", "--bundle-id", "--serial", "--timeout"]);
|
||||
const BOOLEAN_FLAGS = new Set(["--json", "--relaunch", "--normalize-status-bar", "--force-full", "--in-app", "--system"]);
|
||||
|
||||
export function parseCommand(argv: readonly string[]): { positional: string[]; flags: Record<string, string | true> } {
|
||||
const positional: string[] = [];
|
||||
const flags: Record<string, string | true> = {};
|
||||
for (let index = 0; index < argv.length; index++) {
|
||||
const value = argv[index]!;
|
||||
if (value === "--") { positional.push(...argv.slice(index + 1)); break; }
|
||||
if (VALUE_FLAGS.has(value)) { flags[value.slice(2)] = argv[index + 1] ?? ""; index++; continue; }
|
||||
if (BOOLEAN_FLAGS.has(value)) { flags[value.slice(2)] = true; continue; }
|
||||
positional.push(value);
|
||||
}
|
||||
return { positional, flags };
|
||||
}
|
||||
|
||||
type ArgentNode = { role?: string; type?: string; label?: string; identifier?: string; value?: string; contentDescription?: string; disabled?: boolean;
|
||||
frame?: Rect; traits?: string[]; hidden?: boolean; selected?: boolean; password?: boolean; bundleId?: string; children?: ArgentNode[] };
|
||||
export type ArgentTree = { schemaVersion?: number; source?: string; screen?: { width: number; height: number }; roots?: ArgentNode[];
|
||||
truncated?: boolean; alertVisible?: boolean; keyboardVisible?: boolean; foregroundApp?: string };
|
||||
|
||||
const record = (value: unknown): Record<string, unknown> => (value && typeof value === "object" && !Array.isArray(value) ? value as Record<string, unknown> : {});
|
||||
const finite = (value: unknown): value is number => typeof value === "number" && Number.isFinite(value);
|
||||
|
||||
/** Android widget classes as agent-device names their element types. */
|
||||
function agentDeviceType(node: ArgentNode, platform: ArgentPlatform): string {
|
||||
const type = node.type ?? node.role ?? "Other";
|
||||
if (node.password) return "SecureTextField";
|
||||
if (platform === "ios") return type;
|
||||
const simple = type.split(".").pop() ?? type;
|
||||
if (/EditText|TextInput/.test(simple)) return "TextField";
|
||||
if (/Button$|ImageButton|CheckBox|Switch|RadioButton/.test(simple)) return simple.endsWith("Button") ? "Button" : simple;
|
||||
if (/TextView/.test(simple)) return "StaticText";
|
||||
if (/ImageView/.test(simple)) return "Image";
|
||||
if (/ScrollView|RecyclerView|ListView/.test(simple)) return "ScrollView";
|
||||
return simple || "Other";
|
||||
}
|
||||
|
||||
/**
|
||||
* The tree as agent-device's snapshot: the app's root (an `Application` node sized to the screen) and every
|
||||
* element on or near the screen, in the units agent-device uses (points on iOS, pixels on Android), with
|
||||
* refs pinned to this snapshot's generation. Elements Argent lists twice (iOS AX does) appear once.
|
||||
*/
|
||||
export function snapshotFromTree(tree: ArgentTree, platform: ArgentPlatform, generation: number, bundleId?: string) {
|
||||
const screen = tree.screen;
|
||||
if (!screen || !finite(screen.width) || !finite(screen.height) || screen.width <= 0 || screen.height <= 0) {
|
||||
throw new Error("ui-tree did not report the screen size");
|
||||
}
|
||||
const app = bundleId ?? tree.foregroundApp;
|
||||
// Android's status bar and navigation (com.android.systemui) are not part of the app; a dialog another package draws
|
||||
// over it (a runtime permission prompt) is, because it covers the app and setup has to answer it.
|
||||
const roots = (tree.roots ?? []).filter(root => platform === "ios" || root.bundleId !== ANDROID_SYSTEM_UI);
|
||||
const nodes: Record<string, unknown>[] = [];
|
||||
const refs: NonNullable<ArgentBridgeState["refs"]> = {};
|
||||
const seen = new Set<string>();
|
||||
const toPoints = (frame: Rect): Rect => ({ x: frame.x * screen.width, y: frame.y * screen.height, width: frame.width * screen.width, height: frame.height * screen.height });
|
||||
/**
|
||||
* iOS visibility, as Argent computes it (a node is hidden when its frame misses every ancestor's frame), except that a
|
||||
* root clips to the whole screen. On iPhone Duo's inner display Argent 0.29 reports the app root as the top-left third
|
||||
* of the screen ([0, 0, 0.333, 0.333], its 3x scale applied twice), which hid everything outside that third: a sheet's
|
||||
* title and its Cancel button among them. Android's `hidden` is the system's own visible-to-user flag and is kept.
|
||||
*/
|
||||
const clipOf = (node: ArgentNode, clip: Rect | undefined, root: boolean): Rect | undefined => {
|
||||
if (root || !node.frame || ![node.frame.x, node.frame.y, node.frame.width, node.frame.height].every(finite)) return clip;
|
||||
return clip && intersect(node.frame, clip);
|
||||
};
|
||||
const visit = (node: ArgentNode, depth: number, parentIndex: number | undefined, appRoot: boolean, clip: Rect | undefined, root: boolean) => {
|
||||
const frame = node.frame;
|
||||
const inner = clipOf(node, clip, root);
|
||||
const rect = frame && [frame.x, frame.y, frame.width, frame.height].every(finite) ? toPoints(frame) : undefined;
|
||||
const onScreen = !!rect && rect.x < screen.width && rect.y < screen.height && rect.x + rect.width > 0 && rect.y + rect.height > 0;
|
||||
const type = appRoot ? "Application" : agentDeviceType(node, platform);
|
||||
const label = node.label ?? node.contentDescription;
|
||||
const key = JSON.stringify([type, label, node.identifier, node.value, rect && [Math.round(rect.x), Math.round(rect.y), Math.round(rect.width), Math.round(rect.height)]]);
|
||||
let index = parentIndex;
|
||||
// Off-screen content stays out, as agent-device leaves it out; its parents still come through for depth.
|
||||
if (rect && (onScreen || appRoot) && !seen.has(key)) {
|
||||
seen.add(key);
|
||||
index = nodes.length;
|
||||
const ref = `e${index + 1}`;
|
||||
const traits = node.traits ?? [];
|
||||
// iOS marks a disabled element with the notEnabled trait, Android with disabled.
|
||||
const enabled = !traits.includes("notEnabled") && node.disabled !== true;
|
||||
const visible = platform === "ios" ? !!inner : node.hidden !== true;
|
||||
nodes.push({ depth, index, ...(parentIndex === undefined ? {} : { parentIndex }), type, ref,
|
||||
rect: appRoot ? { x: 0, y: 0, width: screen.width, height: screen.height } : rect,
|
||||
...(label ? { label } : {}), ...(node.identifier ? { identifier: node.identifier } : {}),
|
||||
...(node.value !== undefined ? { value: node.value } : {}), enabled, hittable: enabled && visible && !appRoot,
|
||||
...(visible ? {} : { visible: false }), ...(node.selected || traits.includes("selected") ? { selected: true } : {}) });
|
||||
refs[ref] = { rect: appRoot ? { x: 0, y: 0, width: screen.width, height: screen.height } : rect, type,
|
||||
...(node.value !== undefined ? { value: node.value } : {}), ...(type === "SecureTextField" ? { secure: true } : {}) };
|
||||
}
|
||||
for (const child of node.children ?? []) visit(child, depth + 1, index, false, inner, false);
|
||||
};
|
||||
for (const root of roots) {
|
||||
const isAppRoot = platform === "ios" ? root.type === "Application" || nodes.length === 0 : root.bundleId === app;
|
||||
visit(root, 0, undefined, isAppRoot, { x: 0, y: 0, width: 1, height: 1 }, true);
|
||||
}
|
||||
return { nodes, refs, screen: { width: screen.width, height: screen.height } };
|
||||
}
|
||||
|
||||
function intersect(a: Rect, b: Rect): Rect | undefined {
|
||||
const x = Math.max(a.x, b.x), y = Math.max(a.y, b.y);
|
||||
const right = Math.min(a.x + a.width, b.x + b.width), bottom = Math.min(a.y + a.height, b.y + b.height);
|
||||
return right > x && bottom > y ? { x, y, width: right - x, height: bottom - y } : undefined;
|
||||
}
|
||||
|
||||
const centre = (rect: Rect, screen: { width: number; height: number }) =>
|
||||
({ x: (rect.x + rect.width / 2) / screen.width, y: (rect.y + rect.height / 2) / screen.height });
|
||||
|
||||
/**
|
||||
* Argent read nothing: exactly one bare root and no foreground app, which is what iOS 27.1 gives while the link prompt
|
||||
* is up. A read that returned no roots at all is a failed read, not this state.
|
||||
*/
|
||||
function blindTree(tree: ArgentTree): boolean {
|
||||
const roots = tree.roots ?? [];
|
||||
return !tree.foregroundApp && roots.length === 1 && (roots[0]!.children ?? []).length === 0 && !roots[0]!.label && !roots[0]!.type;
|
||||
}
|
||||
|
||||
/** A tree with the app's root and something in it: what a relaunch must reach before the app is usable. */
|
||||
function appReady(tree: ArgentTree, bundleId: string): boolean {
|
||||
if (tree.foregroundApp !== bundleId) return false;
|
||||
const count = (node: ArgentNode): number => 1 + (node.children ?? []).reduce((sum, child) => sum + count(child), 0);
|
||||
return (tree.roots ?? []).some(root => count(root) > 1);
|
||||
}
|
||||
|
||||
function flatten(tree: ArgentTree): ArgentNode[] {
|
||||
const nodes: ArgentNode[] = [];
|
||||
const walk = (node: ArgentNode) => { nodes.push(node); (node.children ?? []).forEach(walk); };
|
||||
(tree.roots ?? []).forEach(walk);
|
||||
return nodes;
|
||||
}
|
||||
|
||||
/** iOS: `com.apple.CoreSimulator.SimRuntime.iOS-26-5` → `26.5`. */
|
||||
export function iosRuntimeVersion(runtime: unknown): string | undefined {
|
||||
const match = typeof runtime === "string" ? /iOS-(\d+)-(\d+)(?:-(\d+))?$/.exec(runtime) : null;
|
||||
return match ? [match[1], match[2], match[3]].filter(Boolean).join(".") : undefined;
|
||||
}
|
||||
|
||||
const DEEP_LINK_PROMPT_CONFIRM = { dxPoints: 74, dyPoints: 37 };
|
||||
const KEYBOARD_DISMISS_LABELS = ["Hide keyboard", "Dismiss keyboard", "Done"];
|
||||
// A keyboard covers the lower part of the screen; its keys start below this share of the height.
|
||||
const KEYBOARD_TOP = 0.4;
|
||||
const ALERT_PREFERRED_BUTTONS = ["Open", "OK", "Allow", "Allow While Using App", "Continue"];
|
||||
const READ_TOOLS = new Set(["ui-tree", "list-devices", "screenshot", "foreground-app", "await-screen-idle", "describe"]);
|
||||
const SPRINGBOARD = "com.apple.springboard";
|
||||
const ANDROID_SYSTEM_UI = "com.android.systemui";
|
||||
const OPEN_IN_APP_PROMPT = /^Open in “.+”\?$/;
|
||||
|
||||
/**
|
||||
* iOS's "Open in “<app>”?" link prompt, recognized by its own text. Argent 0.29 does not always flag it as an alert
|
||||
* (on iOS 27.1, iPhone Duo, `alertVisible` stays false while SpringBoard shows it), and another alert must never be
|
||||
* taken for it: the bridge presses this prompt's Open on its own.
|
||||
*/
|
||||
export function openInAppPromptShowing(tree: ArgentTree): boolean {
|
||||
return flatten(tree).some(node => OPEN_IN_APP_PROMPT.test(node.label ?? ""));
|
||||
}
|
||||
|
||||
/** Any system alert in front of the app: one Argent flags, or the link prompt it does not. */
|
||||
function alertShowing(tree: ArgentTree): boolean {
|
||||
return tree.alertVisible === true || (tree.foregroundApp === SPRINGBOARD && openInAppPromptShowing(tree));
|
||||
}
|
||||
|
||||
/**
|
||||
* The link prompt's Open button found in a screenshot: the largest wide, filled system-blue shape in the middle of the
|
||||
* screen, as iOS 26 and 27 draw it. Used only when Argent cannot read the screen at all while the prompt is up.
|
||||
*/
|
||||
export function findOpenButton(frame: DecodedFrame): { x: number; y: number } | undefined {
|
||||
const step = Math.max(1, Math.round(frame.width / 200));
|
||||
const columns = Math.floor(frame.width / step), rows = Math.floor(frame.height / step);
|
||||
const top = Math.floor(rows * 0.2), bottom = Math.ceil(rows * 0.8);
|
||||
const blue = new Uint8Array(columns * rows);
|
||||
for (let row = top; row < bottom; row++) for (let column = 0; column < columns; column++) {
|
||||
const offset = (row * step * frame.width + column * step) * 4;
|
||||
const [red, green, blueValue] = [frame.data[offset]!, frame.data[offset + 1]!, frame.data[offset + 2]!];
|
||||
if (red < 70 && green > 90 && green < 170 && blueValue > 200) blue[row * columns + column] = 1;
|
||||
}
|
||||
let best: { cells: number; left: number; right: number; top: number; bottom: number } | undefined;
|
||||
const seen = new Uint8Array(columns * rows);
|
||||
for (let start = 0; start < blue.length; start++) {
|
||||
if (!blue[start] || seen[start]) continue;
|
||||
const shape = { cells: 0, left: columns, right: 0, top: rows, bottom: 0 };
|
||||
const queue = [start];
|
||||
seen[start] = 1;
|
||||
while (queue.length) {
|
||||
const cell = queue.pop()!;
|
||||
const row = Math.floor(cell / columns), column = cell % columns;
|
||||
shape.cells++;
|
||||
shape.left = Math.min(shape.left, column); shape.right = Math.max(shape.right, column);
|
||||
shape.top = Math.min(shape.top, row); shape.bottom = Math.max(shape.bottom, row);
|
||||
for (const next of [cell - 1, cell + 1, cell - columns, cell + columns]) {
|
||||
if (next < 0 || next >= blue.length || seen[next] || !blue[next]) continue;
|
||||
if (Math.abs((next % columns) - column) > 1) continue;
|
||||
seen[next] = 1;
|
||||
queue.push(next);
|
||||
}
|
||||
}
|
||||
const width = shape.right - shape.left + 1, height = shape.bottom - shape.top + 1;
|
||||
// A dialog button: wide, a few percent of the screen tall, and well under its full width.
|
||||
if (width < columns * 0.15 || width > columns * 0.6 || width < height * 1.5 || height < rows * 0.03 || height > rows * 0.12) continue;
|
||||
if (!best || shape.cells > best.cells) best = shape;
|
||||
}
|
||||
if (!best) return undefined;
|
||||
return { x: ((best.left + best.right + 1) / 2) / columns, y: ((best.top + best.bottom + 1) / 2) / rows };
|
||||
}
|
||||
|
||||
/**
|
||||
* The prompt's Open button from `describe`. On iOS 27.1 (iPhone Duo) `ui-tree` reports SpringBoard's frames with
|
||||
* x and y swapped, while `describe` reads them correctly, so the button is located there.
|
||||
*/
|
||||
export function describedButton(description: unknown, label: string): Rect | undefined {
|
||||
if (typeof description !== "string") return undefined;
|
||||
const escaped = label.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
|
||||
// Only a whole line Argent printed counts, so an app label that spells out a button line cannot be picked.
|
||||
const match = new RegExp(`^\\s*AXButton "${escaped}"\\s+\\(([\\d.]+), ([\\d.]+), ([\\d.]+), ([\\d.]+)\\)\\s*$`, "m").exec(description);
|
||||
if (!match) return undefined;
|
||||
const [x, y, width, height] = match.slice(1).map(Number) as [number, number, number, number];
|
||||
return [x, y, width, height].every(finite) && width > 0 && height > 0 ? { x, y, width, height } : undefined;
|
||||
}
|
||||
|
||||
/** Runs one agent-device command against Argent and answers as agent-device would. */
|
||||
export async function runBridgeCommand(argv: readonly string[], context: ArgentBridgeContext): Promise<BridgeResult> {
|
||||
const { state, platform } = context;
|
||||
if (argv[0] === "--version") return { exitCode: 0, stdout: `${context.version}\n` };
|
||||
const [command, ...rest] = argv;
|
||||
const { positional, flags } = parseCommand(rest);
|
||||
const bundleFlag = typeof flags["bundle-id"] === "string" ? flags["bundle-id"] : context.bundleId;
|
||||
|
||||
/** Reads are resent after a transport failure (they change nothing); a UI action is sent once, after a health check. */
|
||||
const call = async (tool: string, args: Record<string, unknown> = {}, options?: { out?: string }): Promise<Record<string, unknown>> => {
|
||||
const withDevice = tool === "list-devices" ? args : { udid: state.udid, ...args };
|
||||
for (let attempt = 0; ; attempt++) {
|
||||
try { return record(await context.call(tool, withDevice, options)); }
|
||||
catch (error) {
|
||||
if (READ_TOOLS.has(tool) && attempt < 2) { await context.sleep(1_000 * (attempt + 1)); continue; }
|
||||
throw error;
|
||||
}
|
||||
}
|
||||
};
|
||||
const tree = async (): Promise<ArgentTree> => (await call("ui-tree")) as ArgentTree;
|
||||
const ensureDevice = async () => {
|
||||
if (state.udid) return;
|
||||
let devices: Record<string, unknown>[] = [];
|
||||
// A tool-server that has just started can list no devices at all for its first call; that is not an answer.
|
||||
for (let attempt = 0; attempt < 3; attempt++) {
|
||||
const listed = await call("list-devices");
|
||||
const all = Array.isArray(listed.devices) ? listed.devices : [];
|
||||
devices = all.map(record).filter(device => device.platform === platform
|
||||
&& (platform === "ios" ? device.state === "Booted" && device.runtimeKind !== "tv" : device.state === "device" && device.runtimeKind !== "tv"));
|
||||
if (all.length) break;
|
||||
await context.sleep(2_000);
|
||||
}
|
||||
if (devices.length !== 1) throw new BridgeFailure("DEVICE_UNAVAILABLE", `Argent lists ${devices.length} booted ${platform} devices on this session; Explore drives exactly one.`);
|
||||
const device = devices[0]!;
|
||||
const udid = platform === "ios" ? device.udid : device.serial;
|
||||
if (typeof udid !== "string" || !udid) throw new BridgeFailure("DEVICE_UNAVAILABLE", "Argent did not name the booted device.");
|
||||
state.udid = udid;
|
||||
state.model = String(platform === "ios" ? device.name : device.model ?? device.avdName ?? udid);
|
||||
const version = platform === "ios" ? iosRuntimeVersion(device.runtime) : undefined;
|
||||
if (version) state.osVersion = version;
|
||||
};
|
||||
/** Relaunches until the app's tree is readable: an EAS simulator Argent did not boot needs a relaunch first. */
|
||||
const relaunch = async (bundleId: string) => {
|
||||
for (let restart = 0; restart < 2; restart++) {
|
||||
await call("restart-app", { bundleId });
|
||||
for (let poll = 0; poll < 12; poll++) {
|
||||
await context.sleep(1_000);
|
||||
if (appReady(await tree(), bundleId)) return;
|
||||
}
|
||||
}
|
||||
throw new BridgeFailure("APP_NOT_READY", `${bundleId} did not come up with a readable accessibility tree after relaunching.`);
|
||||
};
|
||||
const deviceEnvelope = (bundleId: string) => ({ session: CONTROLLER_SESSION, appBundleId: bundleId, platform, target: "mobile",
|
||||
device: { platform, target: "mobile", name: state.model, id: state.udid, ...(state.osVersion ? { osVersion: state.osVersion } : {}) },
|
||||
identifiers: { session: CONTROLLER_SESSION, appBundleId: bundleId, deviceName: state.model, deviceId: state.udid } });
|
||||
const screen = async () => {
|
||||
if (!state.screen) { const current = await tree(); if (current.screen) state.screen = { ...current.screen }; }
|
||||
if (!state.screen) throw new BridgeFailure("COMMAND_FAILED", "The screen size is not known yet.");
|
||||
return state.screen;
|
||||
};
|
||||
const tap = async (x: number, y: number) => { await call("gesture-tap", { x, y }); };
|
||||
const resolveRef = (value: string) => {
|
||||
const match = /^@?(e\d+)(?:~s(\d+))?$/.exec(value);
|
||||
if (!match) throw new BridgeFailure("INVALID_ARGS", `Not an element reference: ${value}`);
|
||||
if (match[2] && Number(match[2]) !== state.generation) throw new BridgeFailure("COMMAND_FAILED", `Element reference ${value} is stale; take a new snapshot.`);
|
||||
const target = state.refs?.[match[1]!];
|
||||
if (!target) throw new BridgeFailure("COMMAND_FAILED", `Element reference ${value} is not in the last snapshot.`);
|
||||
return target;
|
||||
};
|
||||
/**
|
||||
* A UI action is only sent when the tool-server answers first, so a failure after this point is never resent. A
|
||||
* session's tool-server can still be starting when EAS reports the session ready, so it is given about 25 s to answer.
|
||||
*/
|
||||
const beforeAction = async () => {
|
||||
for (const delay of [1_000, 2_000, 3_000, 4_000, 5_000, 5_000, 5_000]) {
|
||||
if (await context.reachable()) return;
|
||||
await context.sleep(delay);
|
||||
}
|
||||
if (!await context.reachable()) throw new UnsentFailure();
|
||||
};
|
||||
|
||||
try {
|
||||
switch (command) {
|
||||
case "open": {
|
||||
await ensureDevice();
|
||||
const target = positional.length === 2 ? { bundleId: positional[0]!, url: positional[1]! }
|
||||
: positional.length === 1 && /^[A-Za-z][A-Za-z0-9+.-]*:/.test(positional[0]!) ? { url: positional[0]! } : { bundleId: positional[0] };
|
||||
if (target.url) {
|
||||
await beforeAction();
|
||||
await call("open-url", { url: target.url });
|
||||
if (platform === "ios" && !state.deepLinkPromptAccepted) await acceptDeepLinkPrompt(target.bundleId ?? bundleFlag);
|
||||
return success({ ...(target.bundleId ? deviceEnvelope(target.bundleId) : { session: CONTROLLER_SESSION }), url: target.url });
|
||||
}
|
||||
const bundleId = target.bundleId ?? bundleFlag;
|
||||
if (!bundleId) throw new BridgeFailure("INVALID_ARGS", "open needs a bundle identifier or a URL.");
|
||||
// agent-device's plain open brings a running app forward and keeps its state; only --relaunch restarts it.
|
||||
if (flags.relaunch !== true && appReady(await tree(), bundleId)) return success({ ...deviceEnvelope(bundleId), appName: bundleId });
|
||||
await beforeAction();
|
||||
await relaunch(bundleId);
|
||||
return success({ ...deviceEnvelope(bundleId), appName: bundleId });
|
||||
}
|
||||
case "snapshot": {
|
||||
await ensureDevice();
|
||||
const current = await tree();
|
||||
state.generation += 1;
|
||||
const converted = snapshotFromTree(current, platform, state.generation, bundleFlag);
|
||||
state.refs = converted.refs;
|
||||
state.screen = converted.screen;
|
||||
const dialog = platform === "android" ? readAlert(current) : undefined;
|
||||
if (dialog && !converted.nodes.some(node => node.type === "Alert")) {
|
||||
// An Android dialog from another package covers the app: report it as agent-device does, as an Alert.
|
||||
converted.nodes.push({ depth: 1, index: converted.nodes.length, parentIndex: 0, type: "Alert", ref: `e${converted.nodes.length + 1}`,
|
||||
rect: { x: 0, y: 0, width: converted.screen.width, height: converted.screen.height }, label: dialog.message || "System dialog", enabled: true, hittable: false });
|
||||
} else if (platform === "ios" && alertShowing(current) && !converted.nodes.some(node => node.type === "Alert")
|
||||
&& !(bundleFlag && appReady(current, bundleFlag))) {
|
||||
// A system alert (SpringBoard's) hides the app's tree; report it the way agent-device does, as an Alert node.
|
||||
converted.nodes.push({ depth: 1, index: converted.nodes.length, parentIndex: 0, type: "Alert", ref: `e${converted.nodes.length + 1}`,
|
||||
rect: { x: 0, y: 0, width: converted.screen.width, height: converted.screen.height }, label: "System alert", enabled: true, hittable: false });
|
||||
}
|
||||
return success({ nodes: converted.nodes, truncated: current.truncated === true, refsGeneration: state.generation,
|
||||
...(current.foregroundApp ? { appBundleId: current.foregroundApp, appName: current.foregroundApp } : {}),
|
||||
snapshotQuality: { state: "healthy", backend: "argent" } });
|
||||
}
|
||||
case "appstate": {
|
||||
await ensureDevice();
|
||||
const current = await tree();
|
||||
const foreground = current.foregroundApp;
|
||||
return success({ ...(foreground ? { appBundleId: foreground, ...(platform === "android" ? { package: foreground } : {}) } : {}),
|
||||
session: CONTROLLER_SESSION, state: foreground ? "runningForeground" : "unknown", surface: foreground ? "app" : "home",
|
||||
device: { id: state.udid, name: state.model } });
|
||||
}
|
||||
case "alert": {
|
||||
await ensureDevice();
|
||||
const current = await tree();
|
||||
const alert = readAlert(current);
|
||||
if (positional[0] === "get") {
|
||||
if (!alert) return platform === "android" ? success({ platform: "android", alert: null }) : failure("COMMAND_FAILED", "alert not found");
|
||||
return platform === "android" ? success({ platform: "android", alert: { title: alert.message, buttons: alert.items } })
|
||||
: success({ message: alert.message, items: alert.items });
|
||||
}
|
||||
if (positional[0] === "accept" || positional[0] === "dismiss") {
|
||||
if (!alert) return failure("COMMAND_FAILED", "alert not found");
|
||||
const preferred = positional[0] === "dismiss"
|
||||
? alert.buttons.find(button => /^(Cancel|Not Now|Don.t Allow|Dismiss)$/.test(button.label)) ?? alert.buttons[0]
|
||||
: ALERT_PREFERRED_BUTTONS.map(label => alert.buttons.find(button => button.label === label)).find(Boolean) ?? alert.buttons.at(-1);
|
||||
if (!preferred) return failure("COMMAND_FAILED", "The alert has no button to press.");
|
||||
await beforeAction();
|
||||
const size = current.screen ?? await screen();
|
||||
// describe places SpringBoard's buttons correctly where ui-tree may not (iOS 27.1); the tree is the fallback.
|
||||
const described = describedButton(await call("describe").then(value => value.description, () => undefined), preferred.label);
|
||||
await tap(...Object.values(described ? centre(described, { width: 1, height: 1 }) : centre(preferred.rect, size)) as [number, number]);
|
||||
await context.sleep(800);
|
||||
if (readAlert(await tree())) return failure("COMMAND_FAILED", "The alert is still showing after its button was pressed.");
|
||||
return success({ action: positional[0], button: preferred.label });
|
||||
}
|
||||
return failure("INVALID_ARGS", `Unsupported alert command: ${positional[0] ?? ""}`);
|
||||
}
|
||||
case "press": {
|
||||
await ensureDevice();
|
||||
const size = await screen();
|
||||
let point: { x: number; y: number };
|
||||
if (positional[0]?.startsWith("@") || /^e\d+/.test(positional[0] ?? "")) point = centre(resolveRef(positional[0]!).rect, size);
|
||||
else {
|
||||
const x = Number(positional[0]), y = Number(positional[1]);
|
||||
if (!finite(x) || !finite(y)) throw new BridgeFailure("INVALID_ARGS", "press needs an element reference or x and y.");
|
||||
point = { x: x / size.width, y: y / size.height };
|
||||
}
|
||||
await beforeAction();
|
||||
await tap(point.x, point.y);
|
||||
return success({ action: "press", x: point.x, y: point.y });
|
||||
}
|
||||
case "fill": {
|
||||
await ensureDevice();
|
||||
const target = resolveRef(positional[0] ?? "");
|
||||
const text = positional.slice(1).join(" ");
|
||||
rejectSecretPlaceholder(text);
|
||||
const size = await screen();
|
||||
await beforeAction();
|
||||
await tap(...Object.values(centre(target.rect, size)) as [number, number]);
|
||||
await context.sleep(400);
|
||||
if (platform === "android") {
|
||||
const filled = await call("fill", { text });
|
||||
if (filled.verified !== true) return failure("COMMAND_FAILED", "Argent could not verify the field's new text.");
|
||||
return success({ action: "fill" });
|
||||
}
|
||||
// Argent's iOS `fill` cannot see React Native's focused field, so the old text is erased and the new one typed.
|
||||
const erase = target.secure ? 64 : (target.value ?? "").length;
|
||||
if (erase > 0) {
|
||||
const erased = await call("run-sequence", { steps: Array.from({ length: erase }, () => ({ tool: "keyboard", args: { udid: state.udid, key: "backspace" } })) });
|
||||
// run-sequence answers normally when it stops partway; typing over half-erased text would leave a wrong value.
|
||||
if (erased.completed !== erased.total) return failure("COMMAND_FAILED", `Erasing the field stopped after ${String(erased.completed)} of ${String(erased.total)} keys; nothing was typed.`);
|
||||
}
|
||||
if (text) await call("keyboard", { text });
|
||||
if (!target.secure) {
|
||||
const after = flatten(await tree()).find(node => node.frame && Math.abs(node.frame.x * size.width - target.rect.x) < 2
|
||||
&& Math.abs(node.frame.y * size.height - target.rect.y) < 2 && /TextField|EditText/.test(node.type ?? ""));
|
||||
if (after && (after.value ?? "") !== text) return failure("COMMAND_FAILED", "The field does not hold the requested text after typing it.");
|
||||
}
|
||||
return success({ action: "fill" });
|
||||
}
|
||||
case "type": {
|
||||
await ensureDevice();
|
||||
const text = positional.join(" ");
|
||||
rejectSecretPlaceholder(text);
|
||||
await beforeAction();
|
||||
await call("keyboard", { text });
|
||||
return success({ action: "type" });
|
||||
}
|
||||
case "keyboard": {
|
||||
if (positional[0] !== "dismiss") return failure("INVALID_ARGS", `Unsupported keyboard command: ${positional[0] ?? ""}`);
|
||||
await ensureDevice();
|
||||
const current = await tree();
|
||||
if (!current.keyboardVisible) return success({ platform, action: "dismiss", wasVisible: false, dismissed: false, visible: false });
|
||||
await beforeAction();
|
||||
if (platform === "android") await call("button", { button: "back" });
|
||||
else {
|
||||
// agent-device taps the keyboard's own dismiss control, and fails with this message when there is none, which
|
||||
// callers answer with the return key. Only a key in the keyboard's area counts: an app's "Done" above it is not one.
|
||||
const key = flatten(current).find(node => KEYBOARD_DISMISS_LABELS.includes(node.label ?? "") && node.frame && node.frame.y >= KEYBOARD_TOP);
|
||||
if (!key) return failure("COMMAND_FAILED", "Unable to dismiss the iOS keyboard: the keyboard exposes no dismiss control.");
|
||||
const size = current.screen ?? await screen();
|
||||
await tap(...Object.values(centre({ x: key.frame!.x * size.width, y: key.frame!.y * size.height,
|
||||
width: key.frame!.width * size.width, height: key.frame!.height * size.height }, size)) as [number, number]);
|
||||
}
|
||||
await context.sleep(500);
|
||||
const visible = (await tree()).keyboardVisible === true;
|
||||
if (visible && platform === "ios") return failure("COMMAND_FAILED", "Unable to dismiss the iOS keyboard: it is still showing after its dismiss key was pressed.");
|
||||
return success({ platform, action: "dismiss", wasVisible: true, dismissed: !visible, visible });
|
||||
}
|
||||
case "scroll": {
|
||||
await ensureDevice();
|
||||
const direction = positional[0] ?? "down";
|
||||
const vertical = direction === "down" || direction === "up";
|
||||
const [from, to] = direction === "down" || direction === "right" ? [0.7, 0.3] : [0.3, 0.7];
|
||||
await beforeAction();
|
||||
await call("gesture-swipe", vertical ? { fromX: 0.5, fromY: from, toX: 0.5, toY: to, momentum: false } : { fromX: from, fromY: 0.5, toX: to, toY: 0.5, momentum: false });
|
||||
return success({ action: "scroll", direction });
|
||||
}
|
||||
case "swipe": {
|
||||
await ensureDevice();
|
||||
const [x1, y1, x2, y2] = positional.slice(0, 4).map(Number);
|
||||
if (![x1, y1, x2, y2].every(finite)) throw new BridgeFailure("INVALID_ARGS", "swipe needs x1 y1 x2 y2.");
|
||||
const size = await screen();
|
||||
await beforeAction();
|
||||
await call("gesture-swipe", { fromX: x1! / size.width, fromY: y1! / size.height, toX: x2! / size.width, toY: y2! / size.height, momentum: false });
|
||||
return success({ action: "swipe" });
|
||||
}
|
||||
case "back": {
|
||||
await ensureDevice();
|
||||
await beforeAction();
|
||||
if (flags.system === true) {
|
||||
// agent-device's system back: the hardware button on Android, the edge swipe on iOS.
|
||||
if (platform === "android") await call("button", { button: "back" });
|
||||
else await call("gesture-swipe", { fromX: 0.05, fromY: 0.5, toX: 0.8, toY: 0.5, momentum: false });
|
||||
return success({ action: "back", mode: "system" });
|
||||
}
|
||||
const current = await tree();
|
||||
const nodes = flatten(current);
|
||||
const button = platform === "android"
|
||||
? nodes.find(node => /^(Navigate up|Back)$/i.test(node.contentDescription ?? node.label ?? "") && node.frame)
|
||||
: (() => {
|
||||
const bar = nodes.find(node => node.type === "NavigationBar" && node.frame);
|
||||
return bar && (bar.children ?? []).flatMap(function all(node: ArgentNode): ArgentNode[] { return [node, ...(node.children ?? []).flatMap(all)]; })
|
||||
.find(node => node.type === "Button" && node.frame && node.frame.x < 1 / 3);
|
||||
})();
|
||||
if (button?.frame) {
|
||||
await tap(button.frame.x + button.frame.width / 2, button.frame.y + button.frame.height / 2);
|
||||
return success({ action: "back", mode: "in-app" });
|
||||
}
|
||||
if (flags["in-app"] === true || platform === "ios") return failure("COMMAND_FAILED", "in-app back control is not available");
|
||||
await call("button", { button: "back" });
|
||||
return success({ action: "back", mode: "system" });
|
||||
}
|
||||
case "wait": {
|
||||
if (positional[0] === "stable") {
|
||||
await ensureDevice();
|
||||
const minStableMs = Number(positional[1] ?? 500), timeoutMs = Number(positional[2] ?? 8000);
|
||||
const idle = await call("await-screen-idle", { minStableMs: finite(minStableMs) ? minStableMs : 500, timeoutMs: finite(timeoutMs) ? timeoutMs : 8000 });
|
||||
return success({ stable: idle.settled === true });
|
||||
}
|
||||
const milliseconds = Number(positional[0]);
|
||||
if (!finite(milliseconds) || milliseconds < 0) throw new BridgeFailure("INVALID_ARGS", "wait needs a number of milliseconds or `stable`.");
|
||||
await context.sleep(milliseconds);
|
||||
return success({ waitedMs: milliseconds });
|
||||
}
|
||||
case "screenshot": {
|
||||
await ensureDevice();
|
||||
const path = positional[0];
|
||||
if (!path) throw new BridgeFailure("INVALID_ARGS", "screenshot needs a path.");
|
||||
await call("screenshot", { scale: 1 }, { out: path });
|
||||
return success({ path });
|
||||
}
|
||||
case "record": {
|
||||
await ensureDevice();
|
||||
if (positional[0] === "start") {
|
||||
if (!positional[1]) throw new BridgeFailure("INVALID_ARGS", "record start needs a path.");
|
||||
await call("screen-recording-start", { timeLimitSeconds: 300, trimStatic: false, showTouches: false });
|
||||
state.recording = positional[1];
|
||||
return success({ recording: true, outPath: positional[1] });
|
||||
}
|
||||
if (positional[0] === "stop") {
|
||||
const stopped = await call("screen-recording-stop");
|
||||
const target = state.recording;
|
||||
delete state.recording;
|
||||
if (typeof stopped.video !== "string") return failure("COMMAND_FAILED", "Argent did not return the recording.");
|
||||
if (target) await context.moveFile(stopped.video, target);
|
||||
return success({ outPath: target ?? stopped.video, ...(finite(stopped.durationMs) ? { durationMs: stopped.durationMs } : {}) });
|
||||
}
|
||||
return failure("INVALID_ARGS", `Unsupported record command: ${positional[0] ?? ""}`);
|
||||
}
|
||||
case "install": {
|
||||
await ensureDevice();
|
||||
const path = positional[0];
|
||||
if (!path || !bundleFlag) throw new BridgeFailure("INVALID_ARGS", "install needs an archive path and the app's bundle identifier.");
|
||||
await beforeAction();
|
||||
await call("reinstall-app", { bundleId: bundleFlag, appPath: path });
|
||||
return success({ installed: true, appBundleId: bundleFlag });
|
||||
}
|
||||
case "fold": {
|
||||
await ensureDevice();
|
||||
const posture = positional[0];
|
||||
if (posture !== "closed" && posture !== "half-open" && posture !== "open") throw new BridgeFailure("INVALID_ARGS", "fold needs closed, half-open or open.");
|
||||
await beforeAction();
|
||||
const folded = await call("fold", { posture });
|
||||
// The other panel lights at another size: every stored coordinate and element reference is stale.
|
||||
delete state.screen;
|
||||
delete state.refs;
|
||||
state.generation += 1;
|
||||
// Argent's accessibility reader can keep reading the panel that went dark (seen on iPhone Duo when it had read
|
||||
// the outer panel before the fold): its tree keeps the old panel's shape and comes back bare. Nothing is read
|
||||
// before the fold, and the tree must take the shape of the panel the fold lit before the bridge answers.
|
||||
const lit = record(folded.screen);
|
||||
if (finite(lit.width) && finite(lit.height) && lit.height > 0) {
|
||||
const litRatio = lit.width / lit.height;
|
||||
let followed = false;
|
||||
for (let poll = 0; poll < 10 && !followed; poll++) {
|
||||
const shape = (await tree()).screen;
|
||||
followed = !!shape && shape.height > 0 && Math.abs(shape.width / shape.height - litRatio) < 0.004;
|
||||
if (!followed) await context.sleep(1_000);
|
||||
}
|
||||
if (!followed) throw new BridgeFailure("CONTROLLER_FOLD_UNVERIFIED", `Argent kept reading the other panel after folding the device ${posture}.`);
|
||||
}
|
||||
return success({ action: "fold", pose: posture, ...(folded.panel !== undefined ? { panel: folded.panel } : {}) });
|
||||
}
|
||||
case "apps": return success({ apps: [] });
|
||||
case "session": return success({ sessions: [] });
|
||||
// TODO(argent#1509): map `settings appearance <scheme>` to Argent's `set-appearance` once a release with it is pinned.
|
||||
case "settings": return failure("CONTROLLER_UNSUPPORTED", "Argent cannot change the device's appearance yet.");
|
||||
case "logs": return failure("CONTROLLER_UNSUPPORTED", "Argent does not provide device logs to Explore.");
|
||||
default: return failure("INVALID_ARGS", `Unsupported command for the Argent controller: ${command ?? ""}`);
|
||||
}
|
||||
} catch (error) {
|
||||
if (error instanceof UnsentFailure) return remoteUnavailable();
|
||||
if (error instanceof BridgeFailure) return failure(error.code, error.message);
|
||||
if (error instanceof ArgentCallError) {
|
||||
// Never "Remote daemon is unavailable" here: the request may have run, so Explore must not resend it.
|
||||
return failure(error.sent ? "ARGENT_TOOL_FAILED" : "COMMAND_FAILED", error.sent ? error.message : "Remote daemon is unavailable");
|
||||
}
|
||||
return failure("ARGENT_BRIDGE_FAILED", error instanceof Error ? error.message : String(error));
|
||||
}
|
||||
|
||||
/** Accepts iOS's "Open in “<app>”?" once per session; later links in the same session open without it. */
|
||||
async function acceptDeepLinkPrompt(bundleId: string | undefined) {
|
||||
for (let poll = 0; poll < 6; poll++) {
|
||||
await context.sleep(700);
|
||||
const current = await tree();
|
||||
// Argent can read nothing while iOS 27.1 shows the prompt; find Open in a screenshot instead.
|
||||
if (blindTree(current) && poll >= 1 && context.scratchImage) {
|
||||
if (await pressOpenFromScreenshot(context.scratchImage)) { state.deepLinkPromptAccepted = true; return; }
|
||||
continue;
|
||||
}
|
||||
if (!openInAppPromptShowing(current)) {
|
||||
if (bundleId && appReady(current, bundleId)) { state.deepLinkPromptAccepted = true; return; }
|
||||
// Another alert is the app's or the system's own business; capture answers it, the bridge does not.
|
||||
if (current.alertVisible) return;
|
||||
continue;
|
||||
}
|
||||
const size = current.screen;
|
||||
if (!size) break;
|
||||
const open = describedButton(await call("describe").then(described => described.description, () => undefined), "Open");
|
||||
// Without a described button, the prompt's Open button sits at a fixed offset from the centre on iPhone 17.
|
||||
await tap(...(open ? Object.values(centre(open, { width: 1, height: 1 })) as [number, number]
|
||||
: [0.5 + DEEP_LINK_PROMPT_CONFIRM.dxPoints / size.width, 0.5 + DEEP_LINK_PROMPT_CONFIRM.dyPoints / size.height] as [number, number]));
|
||||
if (await promptCleared()) { state.deepLinkPromptAccepted = true; return; }
|
||||
throw new BridgeFailure("CONTROLLER_DEEP_LINK_PROMPT", "iOS kept asking to open the link in the app after Open was pressed.");
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* After Open is pressed, the prompt can stay in the tree for a second or two while the app comes forward (observed on
|
||||
* iPhone Duo's inner display), so the bridge reads again for a few seconds before it calls the press a failure.
|
||||
*/
|
||||
async function promptCleared(): Promise<boolean> {
|
||||
for (let poll = 0; poll < 6; poll++) {
|
||||
await context.sleep(1_000);
|
||||
if (!openInAppPromptShowing(await tree())) return true;
|
||||
}
|
||||
return false;
|
||||
}
|
||||
|
||||
/** Taps the Open button found in a screenshot, then confirms it is gone. */
|
||||
async function pressOpenFromScreenshot(scratch: NonNullable<ArgentBridgeContext["scratchImage"]>): Promise<boolean> {
|
||||
await call("screenshot", { scale: 1 }, { out: scratch.path });
|
||||
const open = findOpenButton(await scratch.read(scratch.path));
|
||||
if (!open) return false;
|
||||
await tap(open.x, open.y);
|
||||
await context.sleep(1_000);
|
||||
const after = await tree();
|
||||
if (!blindTree(after)) return !openInAppPromptShowing(after);
|
||||
await call("screenshot", { scale: 1 }, { out: scratch.path });
|
||||
return !findOpenButton(await scratch.read(scratch.path));
|
||||
}
|
||||
|
||||
function readAlert(current: ArgentTree) {
|
||||
const androidDialog = platform === "android"
|
||||
? (current.roots ?? []).find(root => root.bundleId && root.bundleId !== ANDROID_SYSTEM_UI && root.bundleId !== (bundleFlag ?? current.foregroundApp))
|
||||
: undefined;
|
||||
if (!androidDialog && !alertShowing(current)) return undefined;
|
||||
const size = current.screen ?? state.screen ?? { width: 1, height: 1 };
|
||||
const nodes = flatten(current);
|
||||
const container = nodes.find(node => node.type === "Alert")
|
||||
?? nodes.find(node => (node.children ?? []).length > 0 && OPEN_IN_APP_PROMPT.test(node.label ?? "")) ?? androidDialog;
|
||||
if (!container) return undefined;
|
||||
const inside = flatten({ roots: [container] });
|
||||
const buttons = inside.filter(node => /Button/.test(node.type ?? node.role ?? "") && node.label && node.frame)
|
||||
.map(node => ({ label: node.label!, rect: { x: node.frame!.x * size.width, y: node.frame!.y * size.height, width: node.frame!.width * size.width, height: node.frame!.height * size.height } }));
|
||||
const text = inside.filter(node => /StaticText|TextView/.test(node.type ?? node.role ?? "") && node.label).map(node => node.label!);
|
||||
return buttons.length ? { message: text.join(" ") || container.label || "", items: buttons.map(button => button.label), buttons } : undefined;
|
||||
}
|
||||
}
|
||||
|
||||
class BridgeFailure extends Error { constructor(readonly code: string, message: string) { super(message); } }
|
||||
class UnsentFailure extends Error {}
|
||||
|
||||
/** Argent's `fill` and `keyboard` would expand `{{secret:NAME}}` from Argent's own secret store; Explore resolves its own. */
|
||||
function rejectSecretPlaceholder(text: string) {
|
||||
if (/\{\{\s*secret\s*:/i.test(text)) throw new BridgeFailure("INVALID_ARGS", "Text for the device must not contain a {{secret:…}} placeholder.");
|
||||
}
|
||||
@@ -0,0 +1,43 @@
|
||||
import { mkdir, writeFile } from "node:fs/promises";
|
||||
import { join } from "node:path";
|
||||
import { fileURLToPath } from "node:url";
|
||||
import type { SimulatorConnection } from "./simulator.js";
|
||||
import { controllerCacheRoot } from "../shared/controller-cache.js";
|
||||
|
||||
/** The Argent bridge's entry, run where agent-device's CLI would be. */
|
||||
export const ARGENT_CONTROLLER_WORKER = fileURLToPath(new URL("./argent-controller-worker.js", import.meta.url));
|
||||
|
||||
const shellQuote = (value: string) => `'${value.replace(/'/g, `'\\''`)}'`;
|
||||
|
||||
/**
|
||||
* The command and environment that drive an Argent session the way agent-device's are run: a small executable in
|
||||
* the run's private directory runs the bridge with this Node, so every caller keeps passing one command and its
|
||||
* arguments. The bridge gets only the session's tool-server variables, telemetry off, and a HOME of its own, so
|
||||
* Argent's state (links, downloaded recordings) is never shared between runs or sides of a review.
|
||||
*/
|
||||
export async function argentControllerInvocation(options: {
|
||||
directory: string; connection: SimulatorConnection; platform: "ios" | "android"; environment: NodeJS.ProcessEnv; bundleId?: string;
|
||||
/** The caller's full environment, which names the controller cache and npm registry the narrowed one drops. */
|
||||
sourceEnvironment?: NodeJS.ProcessEnv;
|
||||
}): Promise<{ command: string; environment: NodeJS.ProcessEnv }> {
|
||||
const source = options.sourceEnvironment ?? options.environment;
|
||||
const home = join(options.directory, "argent-home");
|
||||
await mkdir(home, { recursive: true, mode: 0o700 });
|
||||
const command = join(options.directory, "argent-controller");
|
||||
await writeFile(command, `#!/bin/sh\nexec ${shellQuote(process.execPath)} ${shellQuote(ARGENT_CONTROLLER_WORKER)} "$@"\n`, { mode: 0o700 });
|
||||
// agent-device's variables never reach Argent's bridge, and Argent's never reach agent-device.
|
||||
const environment = Object.fromEntries(Object.entries(options.environment).filter(([name]) => !/^(AGENT_DEVICE_|ARGENT_)/.test(name)));
|
||||
return {
|
||||
command,
|
||||
environment: { ...environment, HOME: home, DO_NOT_TRACK: "1",
|
||||
ARGENT_TOOLS_URL: options.connection.daemonBaseUrl,
|
||||
...(options.connection.daemonAuthToken ? { ARGENT_AUTH_TOKEN: options.connection.daemonAuthToken } : {}),
|
||||
EXPLORE_ARGENT_STATE: join(options.directory, "argent-state.json"), EXPLORE_ARGENT_PLATFORM: options.platform,
|
||||
// The bridge runs with a HOME of its own, so it is told where the fetched Argent release is cached.
|
||||
EXPLORE_CONTROLLER_CACHE: controllerCacheRoot(source),
|
||||
...(source.EXPLORE_NPM_REGISTRY ? { EXPLORE_NPM_REGISTRY: source.EXPLORE_NPM_REGISTRY } : {}),
|
||||
// Opt-in: each Argent call to a JSON-lines log, one file per session, for debugging a controller run.
|
||||
...(source.EXPLORE_ARGENT_LOG_DIR ? { EXPLORE_ARGENT_LOG_DIR: source.EXPLORE_ARGENT_LOG_DIR, EXPLORE_ARGENT_LOG_NAME: options.connection.sessionId } : {}),
|
||||
...(options.bundleId ? { EXPLORE_ARGENT_BUNDLE_ID: options.bundleId } : {}) },
|
||||
};
|
||||
}
|
||||
@@ -0,0 +1,32 @@
|
||||
/**
|
||||
* Runs a device controller Explore fetches on first use: `controller-launcher.js <controller> <args...>` makes sure
|
||||
* the pinned release is in the cache, then runs it with the arguments, passing its output and exit code through.
|
||||
* A failed fetch answers in agent-device's JSON envelope, so callers report it like any controller failure.
|
||||
*/
|
||||
import { spawn } from "node:child_process";
|
||||
import { ensureController, type ControllerName } from "../shared/controller-cache.js";
|
||||
|
||||
async function main(): Promise<number> {
|
||||
const [controller, ...args] = process.argv.slice(2);
|
||||
if (controller !== "agent-device") {
|
||||
process.stdout.write(JSON.stringify({ success: false, error: { code: "INVALID_ARGS", message: `Unknown controller: ${controller ?? ""}` } }));
|
||||
return 1;
|
||||
}
|
||||
let bin: string;
|
||||
try { bin = await ensureController(controller as ControllerName, { progress: message => process.stderr.write(`[explore] ${message}\n`) }); }
|
||||
catch (error) {
|
||||
const failure = error as { code?: string; message?: string; nextAction?: string };
|
||||
process.stdout.write(JSON.stringify({ success: false, error: { code: failure.code ?? "CONTROLLER_DOWNLOAD_FAILED",
|
||||
message: failure.message ?? String(error), ...(failure.nextAction ? { hint: failure.nextAction } : {}) } }));
|
||||
return 1;
|
||||
}
|
||||
return new Promise(resolve => {
|
||||
const child = spawn(process.execPath, [bin, ...args], { stdio: "inherit" });
|
||||
// A capture that stops the launcher stops the controller with it.
|
||||
for (const signal of ["SIGINT", "SIGTERM"] as const) process.on(signal, () => child.kill(signal));
|
||||
child.on("exit", (code, signal) => resolve(code ?? (signal ? 1 : 0)));
|
||||
child.on("error", () => resolve(1));
|
||||
});
|
||||
}
|
||||
|
||||
process.exitCode = await main();
|
||||
+43
-17
@@ -1,4 +1,4 @@
|
||||
import { appearanceArgs, bundleColorSchemes, mergeSchemeOutcomes, resolveColorSchemes, routeIdOfScreen, type AppearanceSetting, type ColorScheme } from "./appearance.js";
|
||||
import { appearanceArgs, argentColorSchemes, bundleColorSchemes, mergeSchemeOutcomes, resolveColorSchemes, routeIdOfScreen, type AppearanceSetting, type ColorScheme } from "./appearance.js";
|
||||
import { assertNoCaptureHealthIssues, captureHealthIssues, partitionCaptureHealthIssues } from "./health.js";
|
||||
import { type RouteResetSetting } from "./route-reset.js";
|
||||
import { defaultReadinessSeconds } from "./readiness.js";
|
||||
@@ -14,15 +14,16 @@ import type { SourceCapturePlan } from "../source/capture-plan.js";
|
||||
import { CONTRACT, type ExploreMap, type Platform, type RunStatus } from "../types.js";
|
||||
import { ExploreStore, validateMap } from "../map/store.js";
|
||||
import { CiError, serializeCiError, toCiError } from "../shared/ci-errors.js";
|
||||
import type { CaptureSetupAction } from "../config/explore-config.js";
|
||||
import type { CaptureSetupAction, DevicePose } from "../config/explore-config.js";
|
||||
import { type CiAgentRuntimeOptions } from "./agent/runtime.js";
|
||||
import { EAS_CLI_VERSION, AGENT_DEVICE_VERSION, CONTROLLER_SESSION, isRecord, parseJson, baseEnvironment, nonEmpty } from "./common.js";
|
||||
import { EAS_CLI_VERSION, CONTROLLER_SESSION, isRecord, parseJson, baseEnvironment, nonEmpty } from "./common.js";
|
||||
import { lstatIfExists, isWithin, temporaryCaptureDirectory, absoluteContractFile, readContractJson, assertNoSymlinkAncestors } from "./fs-safety.js";
|
||||
import { loadAppIcon, loadCachedAppIcon, storeAppIcon } from "./app-icon.js";
|
||||
import { defaultRunner } from "./controller.js";
|
||||
import { silentProgress, type Progress } from "../shared/progress.js";
|
||||
import { assertCaptureEasProfile, assertSimulatorAvailable, fingerprintFrom, hasEasEnvironmentFetchFailure, nativeBuildFrom, existingBuild, repackProfileFrom, prepareExactSourceBuild, type RepackMode } from "./eas-build.js";
|
||||
import { SIMULATOR_DOTENV_FILE_NAME, SIMULATOR_DOTENV_HEADER, simulatorSessionName, simulatorStartFailure, readSimulatorDotenvHandoff, assertSimulatorSessionIdentity, assertSimulatorStopped, collectRuntime, simulatorOsVersion, type ActiveSimulatorRuntime } from "./simulator.js";
|
||||
import { SIMULATOR_DOTENV_FILE_NAME, SIMULATOR_DOTENV_HEADER, simulatorSessionName, simulatorStartFailure, readSimulatorDotenvHandoff, assertSimulatorSessionIdentity, assertSimulatorStopped, collectRuntime, controllerVersion, simulatorOsVersion, type ActiveSimulatorRuntime } from "./simulator.js";
|
||||
import { argentControllerInvocation } from "./controller-invocation.js";
|
||||
import { type UnattributedSetting } from "./unattributed.js";
|
||||
import { appScheme, hasConcreteRoutePath, unavailableRoute, capturePlannedRoutes, deviceArgs } from "./route-capture.js";
|
||||
|
||||
@@ -51,6 +52,10 @@ export type CiMapOptions = {
|
||||
/** Host-side pause used while a controller read is resent; tests pair it with `now` so recovery waits are not real time. */
|
||||
sleep?: (milliseconds: number) => void;
|
||||
easCommand: string; repackCommand: string; agentDeviceCommand: string;
|
||||
/** The device controller EAS starts on the session; agent-device unless the config chose Argent. */
|
||||
controller?: "agent-device" | "argent";
|
||||
/** A foldable's pose (device.pose), set with the controller's `fold` before anything is captured. */
|
||||
devicePose?: DevicePose;
|
||||
/** Where the route observer is bundled into the app: a hosted EAS repack job (default) or repack-app on this machine. */
|
||||
repack?: RepackMode;
|
||||
/** Which appearances to capture; `auto` (default) follows the app's `userInterfaceStyle`. */
|
||||
@@ -69,7 +74,7 @@ export type CiMapOptions = {
|
||||
signal?: AbortSignal;
|
||||
};
|
||||
export type SimulatorRuntimeMetadata = {
|
||||
provider: "eas-simulator"; controller: "agent-device"; controllerPackageVersion: string;
|
||||
provider: "eas-simulator"; controller: "agent-device" | "argent"; controllerPackageVersion: string;
|
||||
easCliVersion: string; platform: Platform; deviceModel: string; osVersion: string; locale: string;
|
||||
orientation: "portrait" | "landscape"; colorScheme: "light" | "dark" | "system"; colorSchemes?: ColorScheme[];
|
||||
sessionLifecycle: "stopped";
|
||||
@@ -94,7 +99,7 @@ function newCaptureMap(options: CiMapOptions, runtime?: ActiveSimulatorRuntime,
|
||||
const timestamp = new Date((options.now ?? Date.now)()).toISOString();
|
||||
return {
|
||||
contract: CONTRACT, revision: 0,
|
||||
run: { id: options.buildId, name: options.name, platform: options.platform, controller: "agent-device", status: "draft",
|
||||
run: { id: options.buildId, name: options.name, platform: options.platform, controller: options.controller ?? "agent-device", status: "draft",
|
||||
bundleId: options.bundleId, ...(runtime ? { deviceId: runtime.controllerDeviceId } : {}),
|
||||
createdAt: timestamp, updatedAt: timestamp,
|
||||
build: { id: options.buildId, version: options.buildVersion, gitCommit: options.gitCommit, source: "eas", ...(fingerprint ? { hash: fingerprint } : {}) },
|
||||
@@ -163,6 +168,7 @@ async function executeCiMap(options: CiMapOptions, setStage: (stage: string) =>
|
||||
const setup = revisionSetup(options.setup ?? [], plan, side);
|
||||
const runner = options.runner ?? defaultRunner;
|
||||
const sourceEnvironment = options.environment ?? process.env;
|
||||
const controller = options.controller ?? "agent-device";
|
||||
const restrictedEnvironment = baseEnvironment(sourceEnvironment);
|
||||
const easEnvironment = { ...restrictedEnvironment, ...(options.expoToken ? { EXPO_TOKEN: options.expoToken } : {}) };
|
||||
const assertCheckout = () => {
|
||||
@@ -279,7 +285,7 @@ async function executeCiMap(options: CiMapOptions, setStage: (stage: string) =>
|
||||
app = { name: cachedBundle.appName ?? options.name };
|
||||
appIcon = await loadCachedAppIcon(cacheRoot, cachedBundle.appIcon);
|
||||
const cachedProfile = cachedBundle.runtimeProfile!;
|
||||
runtime = { provider: "eas-simulator", controller: "agent-device", controllerPackageVersion: AGENT_DEVICE_VERSION,
|
||||
runtime = { provider: "eas-simulator", controller, controllerPackageVersion: controllerVersion(controller),
|
||||
easCliVersion: EAS_CLI_VERSION, platform: options.platform, controllerDeviceId: cachedDeviceId ?? "cached",
|
||||
deviceModel: cachedProfile.deviceModel, osVersion: cachedProfile.osVersion, locale: cachedProfile.locale,
|
||||
orientation: cachedProfile.orientation === "landscape" ? "landscape" : "portrait",
|
||||
@@ -349,7 +355,7 @@ async function executeCiMap(options: CiMapOptions, setStage: (stage: string) =>
|
||||
await rm(launchWorkDirectory, { recursive: true, force: true });
|
||||
const storedIcon = appIcon ? await storeAppIcon(outputDirectory, appIcon) : undefined;
|
||||
const bundle: CaptureBundle = { contract: "explore.bundle", side, gitCommit: options.gitCommit, easBuildId, completedAt: map.run.completedAt,
|
||||
easProjectId: projectId, platform: options.platform, profile: options.easProfile, appName: app.name, ...(storedIcon ? { appIcon: storedIcon } : {}),
|
||||
easProjectId: projectId, platform: options.platform, profile: options.easProfile, appName: app.name, ...(controller === "argent" ? { controller } : {}), ...(storedIcon ? { appIcon: storedIcon } : {}),
|
||||
selectedSurfaceIds: selectedIds,
|
||||
runtimeProfile: metadata ? { deviceModel: metadata.deviceModel, osVersion: metadata.osVersion, locale: metadata.locale,
|
||||
orientation: metadata.orientation, colorScheme: metadata.colorScheme, ...(metadata.colorSchemes ? { colorSchemes: metadata.colorSchemes.join(",") } : {}) } : null, images, outcomes, procedure: { reset: options.reset ?? "root-link", readinessSeconds: options.readinessSeconds ?? defaultReadinessSeconds(options.platform) },
|
||||
@@ -381,6 +387,11 @@ async function executeCiMap(options: CiMapOptions, setStage: (stage: string) =>
|
||||
const configValue = parseJson(configResult.stdout, "eas config") as { appConfig: Record<string, unknown>; buildProfile: Record<string, unknown> };
|
||||
scheme ??= appScheme(configValue.appConfig.scheme);
|
||||
colorSchemes = resolveColorSchemes(options.appearance ?? "auto", configValue.appConfig, options.platform);
|
||||
if (controller === "argent") {
|
||||
const single = argentColorSchemes(colorSchemes, configValue.appConfig, options.platform);
|
||||
if (single.skipped.length) say(`Argent cannot switch appearance yet (software-mansion/argent#1509); capturing ${single.schemes[0]} only, skipped ${single.skipped.join(", ")}`);
|
||||
colorSchemes = single.schemes;
|
||||
}
|
||||
app = { name: profile.projectIdentity.name, ...(profile.projectIdentity.version ? { version: profile.projectIdentity.version } : {}),
|
||||
...(profile.projectIdentity.buildNumber ? { buildNumber: profile.projectIdentity.buildNumber } : {}) };
|
||||
projectId = profile.projectIdentity.projectId;
|
||||
@@ -446,7 +457,7 @@ async function executeCiMap(options: CiMapOptions, setStage: (stage: string) =>
|
||||
await writeFile(dotenvPath, SIMULATOR_DOTENV_HEADER, { flag: "wx", mode: 0o600 });
|
||||
let startError: unknown;
|
||||
try { eas(["simulator:start", "--name", sessionName, "--platform", options.platform, "--device", options.device,
|
||||
"--type", "agent-device", "--package-version", AGENT_DEVICE_VERSION, "--build-id", easBuildId, "--public-link",
|
||||
"--type", controller, "--package-version", controllerVersion(controller), "--build-id", easBuildId, "--public-link",
|
||||
"--max-duration-minutes", String(options.maxDurationMinutes), "--out-config-type", "dotenv", "--non-interactive"], 20 * 60_000, simulatorProject); }
|
||||
catch (error) { startError = error; }
|
||||
const handoff = await readSimulatorDotenvHandoff(dotenvPath);
|
||||
@@ -480,15 +491,29 @@ async function executeCiMap(options: CiMapOptions, setStage: (stage: string) =>
|
||||
await rm(dotenvPath, { force: true });
|
||||
const controllerConfig = join(simulatorProject, "agent-device.json");
|
||||
await writeFile(controllerConfig, "{}\n", { flag: "wx", mode: 0o400 });
|
||||
const controllerEnvironment = { ...restrictedEnvironment, AGENT_DEVICE_CONFIG: controllerConfig,
|
||||
const argent = controller === "argent"
|
||||
? await argentControllerInvocation({ directory: simulatorProject, connection: handoff.connection, platform: options.platform, environment: restrictedEnvironment, sourceEnvironment, bundleId: options.bundleId })
|
||||
: undefined;
|
||||
const controllerEnvironment = argent?.environment ?? { ...restrictedEnvironment, AGENT_DEVICE_CONFIG: controllerConfig,
|
||||
AGENT_DEVICE_DAEMON_BASE_URL: handoff.connection.daemonBaseUrl, AGENT_DEVICE_DAEMON_AUTH_TOKEN: handoff.connection.daemonAuthToken,
|
||||
AGENT_DEVICE_SESSION: CONTROLLER_SESSION, AGENT_DEVICE_SESSION_LOCK: "reject", AGENT_DEVICE_PLATFORM: options.platform };
|
||||
// Every controller call below goes to the session's controller; for Argent that is the bridge.
|
||||
const controllerCommand = argent?.command ?? options.agentDeviceCommand;
|
||||
if (options.devicePose) {
|
||||
// A fold relights the other panel and resizes the window. It comes before the app is first opened or read, so the
|
||||
// controller's accessibility reader starts on the lit panel: Argent's, started on the outer panel, can stay there.
|
||||
say(`folding ${options.device} ${options.devicePose}`);
|
||||
runner({ command: controllerCommand, args: ["fold", options.devicePose, "--session", CONTROLLER_SESSION,
|
||||
...deviceArgs({ platform: options.platform, deviceModel: options.device }), "--platform", options.platform, "--json"],
|
||||
cwd: simulatorProject, environment: controllerEnvironment, timeoutMs: 2 * 60_000 });
|
||||
}
|
||||
runtimeStage = "runtime";
|
||||
setStage(runtimeStage);
|
||||
runtime = collectRuntime(options, controllerEnvironment);
|
||||
runtime = collectRuntime({ ...options, agentDeviceCommand: controllerCommand }, controllerEnvironment);
|
||||
runtime.colorScheme = colorSchemes[0]!;
|
||||
// The version is descriptive; a capture proceeds without it and records "unknown".
|
||||
try {
|
||||
// The version is descriptive; a capture proceeds without it and records "unknown". Argent names it with the device;
|
||||
// agent-device's is always taken from the session, as before.
|
||||
if (runtime.osVersion === "unknown" || controller !== "argent") try {
|
||||
runtime.osVersion = await simulatorOsVersion(eas(["simulator:get", "--id", sessionId, "--json", "--non-interactive"], 2 * 60_000).stdout,
|
||||
runtime.controllerDeviceId, options.fetch ?? fetch, options.platform);
|
||||
} catch (error) {
|
||||
@@ -504,7 +529,8 @@ async function executeCiMap(options: CiMapOptions, setStage: (stage: string) =>
|
||||
const passes: CaptureBundle["outcomes"][] = [];
|
||||
const recordingTools = launchSetting === "off" ? undefined : options.recordingTools === undefined ? ffmpegRecordingTools() : options.recordingTools ?? undefined;
|
||||
for (const [index, colorScheme] of colorSchemes.entries()) {
|
||||
runner({ command: options.agentDeviceCommand, args: [...appearanceArgs(colorScheme), "--session", CONTROLLER_SESSION, ...deviceArgs(runtime), "--platform", options.platform],
|
||||
// Argent cannot switch the appearance yet (software-mansion/argent#1509); its single pass runs as the device starts.
|
||||
if (controller !== "argent") runner({ command: controllerCommand, args: [...appearanceArgs(colorScheme), "--session", CONTROLLER_SESSION, ...deviceArgs(runtime), "--platform", options.platform],
|
||||
cwd: simulatorProject, environment: controllerEnvironment, timeoutMs: 60_000 });
|
||||
// A scheme change recreates the Android activity in place, and the sheets it re-presents lose their inset; a
|
||||
// relaunch starts the app in the new scheme, the same way the first pass did.
|
||||
@@ -516,7 +542,7 @@ async function executeCiMap(options: CiMapOptions, setStage: (stage: string) =>
|
||||
const record = await captureLaunch({ bundleId: options.bundleId, keepVideo: launchSetting === "video", platform: options.platform,
|
||||
directory: join(launchWorkDirectory, launchDirectory(colorScheme)), relativeDirectory: launchDirectory(colorScheme), ...(options.now ? { now: options.now } : {}),
|
||||
...(recordingTools ? { recordingTools } : {}),
|
||||
controller: (args, controllerOptions) => runner({ command: options.agentDeviceCommand, args: [...args, "--session", CONTROLLER_SESSION, ...deviceArgs(runtime!), "--platform", options.platform],
|
||||
controller: (args, controllerOptions) => runner({ command: controllerCommand, args: [...args, "--session", CONTROLLER_SESSION, ...deviceArgs(runtime!), "--platform", options.platform],
|
||||
cwd: simulatorProject, environment: controllerEnvironment, timeoutMs: controllerOptions?.timeoutMs ?? 60_000, ...(controllerOptions?.allowFailure ? { allowFailure: true } : {}) }) });
|
||||
launch[colorScheme] = { root: launchWorkDirectory, record };
|
||||
} catch (error) {
|
||||
@@ -524,11 +550,11 @@ async function executeCiMap(options: CiMapOptions, setStage: (stage: string) =>
|
||||
say(`the app launch could not be observed (${(error as Error).message}); the report has no launch evidence for ${colorScheme}`);
|
||||
await rm(join(launchWorkDirectory, launchDirectory(colorScheme)), { recursive: true, force: true });
|
||||
}
|
||||
} else if (index > 0) runner({ command: options.agentDeviceCommand, args: ["open", options.bundleId, "--relaunch", "--session", CONTROLLER_SESSION,
|
||||
} else if (index > 0) runner({ command: controllerCommand, args: ["open", options.bundleId, "--relaunch", "--session", CONTROLLER_SESSION,
|
||||
...deviceArgs(runtime), "--platform", options.platform, "--level", "full", "--json"], cwd: simulatorProject, environment: controllerEnvironment, timeoutMs: 60_000 });
|
||||
runtime.colorScheme = colorScheme;
|
||||
if (colorSchemes.length > 1) say(`appearance ${colorScheme} (${index + 1}/${colorSchemes.length})`);
|
||||
passes.push(await capturePlannedRoutes({ capture: { ...options, setup, progress: say }, routes: missingRoutes, inventory, scheme, appName: app.name, runtime,
|
||||
passes.push(await capturePlannedRoutes({ capture: { ...options, agentDeviceCommand: controllerCommand, setup, progress: say }, routes: missingRoutes, inventory, scheme, appName: app.name, runtime,
|
||||
connection: handoff.connection, environment: controllerEnvironment, store, map, acceptedFrames, outcomes: index === 0 ? outcomes : {},
|
||||
...(colorSchemes.length > 1 ? { appearance: { scheme: colorScheme, primary: index === 0 } } : {}) }));
|
||||
}
|
||||
|
||||
+62
-35
@@ -2,6 +2,7 @@ import { createHash } from "node:crypto";
|
||||
import { readFile } from "node:fs/promises";
|
||||
import { toCiError, serializeCiError, CiError } from "../shared/ci-errors.js";
|
||||
import { isRecord, parseJson, baseEnvironment, AGENT_DEVICE_VERSION, CONTROLLER_SESSION, EAS_CLI_VERSION } from "./common.js";
|
||||
import { ARGENT_VERSION } from "../shared/argent-version.js";
|
||||
import { SIMULATOR_PREVIEW_HOST, framedSimulatorPreviewServer } from "../shared/simulator-preview.js";
|
||||
import { lstatIfExists } from "./fs-safety.js";
|
||||
import { defaultRunner, openedSimulatorDevice, controllerData } from "./controller.js";
|
||||
@@ -9,7 +10,21 @@ import type { RepackProfile } from "./eas-build.js";
|
||||
import type { SimulatorRuntimeMetadata, CiMapOptions } from "./run.js";
|
||||
import type { Platform } from "../types.js";
|
||||
|
||||
export type SimulatorConnection = { sessionId: string; daemonBaseUrl: string; daemonAuthToken: string };
|
||||
/**
|
||||
* How Explore reaches a session's device controller. For agent-device (no `controller`) these are the daemon's URL and
|
||||
* token; for Argent they are the tool-server's `ARGENT_TOOLS_URL` and `ARGENT_AUTH_TOKEN`, whose token may be empty.
|
||||
*/
|
||||
export type SimulatorConnection = { sessionId: string; daemonBaseUrl: string; daemonAuthToken: string; controller?: "argent" };
|
||||
|
||||
/** The controller a connection reaches: the session `--type` EAS started. */
|
||||
export function connectionController(connection: Pick<SimulatorConnection, "controller">): "agent-device" | "argent" {
|
||||
return connection.controller ?? "agent-device";
|
||||
}
|
||||
|
||||
/** The controller's pinned version: what EAS installs on the session (`--package-version`) and what runs here. */
|
||||
export function controllerVersion(controller: "agent-device" | "argent"): string {
|
||||
return controller === "argent" ? ARGENT_VERSION : AGENT_DEVICE_VERSION;
|
||||
}
|
||||
export type ActiveSimulatorRuntime = Omit<SimulatorRuntimeMetadata, "sessionLifecycle"> & { controllerDeviceId: string };
|
||||
const SIMULATOR_SESSION_NAME_MAX_CHARACTERS = 50;
|
||||
const SIMULATOR_SESSION_DIGEST_CHARACTERS = 20;
|
||||
@@ -64,24 +79,28 @@ function simulatorConnection(
|
||||
sessionId: string,
|
||||
daemonBaseUrl: unknown,
|
||||
daemonAuthToken: unknown,
|
||||
controller: "agent-device" | "argent" = "agent-device",
|
||||
): SimulatorConnection {
|
||||
// An Argent tool-server may run without a token (ARGENT_AUTH_TOKEN is only set when it needs one).
|
||||
if (controller === "argent" && daemonAuthToken === undefined) daemonAuthToken = "";
|
||||
if (
|
||||
typeof daemonBaseUrl !== "string"
|
||||
|| typeof daemonAuthToken !== "string"
|
||||
|| !daemonBaseUrl
|
||||
|| !daemonAuthToken
|
||||
|| (!daemonAuthToken && controller !== "argent")
|
||||
|| daemonBaseUrl.length > 2_048
|
||||
|| daemonAuthToken.length > 8_192
|
||||
|| /[\u0000-\u001f\u007f]/.test(daemonBaseUrl)
|
||||
|| /[\u0000-\u001f\u007f]/.test(daemonAuthToken)
|
||||
) {
|
||||
throw new Error("eas simulator:start returned an unsafe agent-device connection");
|
||||
throw new Error(`eas simulator:start returned an unsafe ${controller} connection`);
|
||||
}
|
||||
remoteDaemonDomain(daemonBaseUrl);
|
||||
remoteDaemonDomain(daemonBaseUrl, controller);
|
||||
return {
|
||||
sessionId,
|
||||
daemonBaseUrl,
|
||||
daemonAuthToken,
|
||||
...(controller === "argent" ? { controller } : {}),
|
||||
};
|
||||
}
|
||||
|
||||
@@ -100,7 +119,7 @@ export function simulatorStartFailure(error: unknown, secrets: readonly string[]
|
||||
message: source.message.replace(/\\+(["'/])/g, "$1"),
|
||||
nextAction: "Inspect the EAS simulator start failure." }), { secrets });
|
||||
const message = failure.message
|
||||
.replace(/\b(?:AGENT_DEVICE_[A-Z_]+|EAS_SIMULATOR_[A-Z_]+|EXPO_TOKEN|agentDeviceRemoteSession(?:Token|Url)|webPreviewUrl|previewApiUrl)["']?\s*[:=][^\r\n]*/g, "[REDACTED_HANDOFF]")
|
||||
.replace(/\b(?:AGENT_DEVICE_[A-Z_]+|ARGENT_[A-Z_]+|EAS_SIMULATOR_[A-Z_]+|EXPO_TOKEN|agentDeviceRemoteSession(?:Token|Url)|toolsUrl|toolsAuthToken|webPreviewUrl|previewApiUrl)["']?\s*[:=][^\r\n]*/g, "[REDACTED_HANDOFF]")
|
||||
.replace(/\b[A-Za-z][A-Za-z0-9+.-]*:\/\/[^\s<>"']+/g, "[REDACTED_URL]")
|
||||
.slice(0, 1600);
|
||||
return { code: failure.code, stage: "session", message,
|
||||
@@ -149,6 +168,8 @@ export async function readSimulatorDotenvHandoff(path: string): Promise<Simulato
|
||||
"EAS_SIMULATOR_SESSION_ID",
|
||||
"AGENT_DEVICE_DAEMON_BASE_URL",
|
||||
"AGENT_DEVICE_DAEMON_AUTH_TOKEN",
|
||||
"ARGENT_TOOLS_URL",
|
||||
"ARGENT_AUTH_TOKEN",
|
||||
].includes(name)) {
|
||||
validationError ??= new Error("EAS Simulator dotenv handoff contains an unexpected assignment");
|
||||
continue;
|
||||
@@ -177,11 +198,14 @@ export async function readSimulatorDotenvHandoff(path: string): Promise<Simulato
|
||||
let connection: SimulatorConnection | undefined;
|
||||
if (sessionId) {
|
||||
try {
|
||||
connection = simulatorConnection(
|
||||
sessionId,
|
||||
assignments.AGENT_DEVICE_DAEMON_BASE_URL,
|
||||
assignments.AGENT_DEVICE_DAEMON_AUTH_TOKEN,
|
||||
);
|
||||
// An `argent` session writes the Argent tool-server's variables instead of agent-device's.
|
||||
connection = assignments.ARGENT_TOOLS_URL !== undefined
|
||||
? simulatorConnection(sessionId, assignments.ARGENT_TOOLS_URL, assignments.ARGENT_AUTH_TOKEN, "argent")
|
||||
: simulatorConnection(
|
||||
sessionId,
|
||||
assignments.AGENT_DEVICE_DAEMON_BASE_URL,
|
||||
assignments.AGENT_DEVICE_DAEMON_AUTH_TOKEN,
|
||||
);
|
||||
} catch (error) {
|
||||
validationError ??= error instanceof Error ? error : new Error(String(error));
|
||||
}
|
||||
@@ -207,7 +231,7 @@ export function assertSimulatorSessionIdentity(
|
||||
sessionId !== expectedSessionId
|
||||
|| !isRecord(value)
|
||||
|| value.name !== expectedSessionName
|
||||
|| value.type !== "agent-device"
|
||||
|| value.type !== (expectedConnection ? connectionController(expectedConnection) : "agent-device")
|
||||
|| value.platform !== expectedPlatform.toUpperCase()
|
||||
|| value.status !== "IN_PROGRESS"
|
||||
) {
|
||||
@@ -226,17 +250,19 @@ export function assertSimulatorSessionIdentity(
|
||||
if (!projectProven) {
|
||||
throw new Error("eas simulator:get did not prove the exact expected simulator session");
|
||||
}
|
||||
if (expectedConnection) {
|
||||
if (
|
||||
!isRecord(value.remoteConfig)
|
||||
|| value.remoteConfig.agentDeviceRemoteSessionUrl !== expectedConnection.daemonBaseUrl
|
||||
|| value.remoteConfig.agentDeviceRemoteSessionToken !== expectedConnection.daemonAuthToken
|
||||
) {
|
||||
throw new Error("eas simulator:get returned a different agent-device connection");
|
||||
}
|
||||
if (expectedConnection && !remoteConfigMatches(value.remoteConfig, expectedConnection)) {
|
||||
throw new Error(`eas simulator:get returned a different ${connectionController(expectedConnection)} connection`);
|
||||
}
|
||||
}
|
||||
|
||||
/** The session's published controller endpoint is the one Explore holds: agent-device's daemon, or Argent's tool-server. */
|
||||
function remoteConfigMatches(remoteConfig: unknown, connection: SimulatorConnection): boolean {
|
||||
if (!isRecord(remoteConfig)) return false;
|
||||
return connectionController(connection) === "argent"
|
||||
? remoteConfig.toolsUrl === connection.daemonBaseUrl && (remoteConfig.toolsAuthToken ?? "") === connection.daemonAuthToken
|
||||
: remoteConfig.agentDeviceRemoteSessionUrl === connection.daemonBaseUrl && remoteConfig.agentDeviceRemoteSessionToken === connection.daemonAuthToken;
|
||||
}
|
||||
|
||||
/**
|
||||
* A session Explore did not start: the connection comes from `eas simulator:start --out-config-type dotenv`
|
||||
* (`.env.eas-simulator`) or from the `EAS_SIMULATOR_SESSION_ID` / `AGENT_DEVICE_DAEMON_*` variables that
|
||||
@@ -263,7 +289,9 @@ export async function resolveAttachedSimulatorSession(
|
||||
if (requestedSessionId && environment.EAS_SIMULATOR_SESSION_ID && environment.EAS_SIMULATOR_SESSION_ID !== requestedSessionId) {
|
||||
throw new Error(`EAS_SIMULATOR_SESSION_ID is ${environment.EAS_SIMULATOR_SESSION_ID}, not ${requestedSessionId}`);
|
||||
}
|
||||
return simulatorConnection(sessionId, environment.AGENT_DEVICE_DAEMON_BASE_URL, environment.AGENT_DEVICE_DAEMON_AUTH_TOKEN);
|
||||
return environment.ARGENT_TOOLS_URL !== undefined && environment.AGENT_DEVICE_DAEMON_BASE_URL === undefined
|
||||
? simulatorConnection(sessionId, environment.ARGENT_TOOLS_URL, environment.ARGENT_AUTH_TOKEN, "argent")
|
||||
: simulatorConnection(sessionId, environment.AGENT_DEVICE_DAEMON_BASE_URL, environment.AGENT_DEVICE_DAEMON_AUTH_TOKEN);
|
||||
}
|
||||
|
||||
/** Proves an attached session is live, agent-device typed, and served by the connection we hold; returns its platform. */
|
||||
@@ -274,8 +302,8 @@ export function assertAttachedSimulatorSession(
|
||||
): { platform: Platform; name: string; deviceRunSessionUrl?: string } {
|
||||
const value = parseJson(stdout, "eas simulator:get");
|
||||
const sessionId = simulatorSessionId(value, "eas simulator:get");
|
||||
if (sessionId !== connection.sessionId || !isRecord(value) || value.type !== "agent-device") {
|
||||
throw new Error("eas simulator:get did not describe the attached agent-device session");
|
||||
if (sessionId !== connection.sessionId || !isRecord(value) || value.type !== connectionController(connection)) {
|
||||
throw new Error(`eas simulator:get did not describe the attached ${connectionController(connection)} session`);
|
||||
}
|
||||
if (value.status !== "IN_PROGRESS") {
|
||||
throw new Error(`EAS Simulator session ${sessionId} is ${String(value.status).toLowerCase()}, not in progress`);
|
||||
@@ -284,12 +312,8 @@ export function assertAttachedSimulatorSession(
|
||||
if (!platform || (expectedPlatform && platform !== expectedPlatform)) {
|
||||
throw new Error(`EAS Simulator session ${sessionId} is ${String(value.platform).toLowerCase()}${expectedPlatform ? `, not ${expectedPlatform}` : ""}`);
|
||||
}
|
||||
if (
|
||||
!isRecord(value.remoteConfig)
|
||||
|| value.remoteConfig.agentDeviceRemoteSessionUrl !== connection.daemonBaseUrl
|
||||
|| value.remoteConfig.agentDeviceRemoteSessionToken !== connection.daemonAuthToken
|
||||
) {
|
||||
throw new Error("eas simulator:get returned a different agent-device connection than the one provided");
|
||||
if (!remoteConfigMatches(value.remoteConfig, connection)) {
|
||||
throw new Error(`eas simulator:get returned a different ${connectionController(connection)} connection than the one provided`);
|
||||
}
|
||||
return {
|
||||
platform,
|
||||
@@ -309,12 +333,12 @@ export function assertSimulatorStopped(stdout: string, expectedSessionId: string
|
||||
}
|
||||
}
|
||||
|
||||
function remoteDaemonDomain(value: string): string {
|
||||
function remoteDaemonDomain(value: string, controller: "agent-device" | "argent" = "agent-device"): string {
|
||||
let url: URL;
|
||||
try {
|
||||
url = new URL(value);
|
||||
} catch {
|
||||
throw new Error("eas simulator returned an invalid agent-device URL");
|
||||
throw new Error(`eas simulator returned an invalid ${controller} URL`);
|
||||
}
|
||||
if (
|
||||
url.protocol !== "https:"
|
||||
@@ -322,19 +346,22 @@ function remoteDaemonDomain(value: string): string {
|
||||
|| url.password
|
||||
|| !url.hostname
|
||||
) {
|
||||
throw new Error("eas simulator returned an unsafe agent-device URL");
|
||||
throw new Error(`eas simulator returned an unsafe ${controller} URL`);
|
||||
}
|
||||
return url.hostname;
|
||||
}
|
||||
|
||||
export function collectRuntime(options: CiMapOptions & { platform: NonNullable<CiMapOptions["platform"]> }, environment: NodeJS.ProcessEnv): ActiveSimulatorRuntime {
|
||||
const runner = options.runner ?? defaultRunner;
|
||||
const controller = options.controller ?? "agent-device";
|
||||
const version = runner({ command: options.agentDeviceCommand, args: ["--version"], cwd: options.project,
|
||||
environment: baseEnvironment(options.environment ?? process.env), timeoutMs: 30_000 }).stdout.trim();
|
||||
if (version !== AGENT_DEVICE_VERSION) throw new Error(`agent-device version must be ${AGENT_DEVICE_VERSION}`);
|
||||
environment: controller === "argent" ? environment : baseEnvironment(options.environment ?? process.env), timeoutMs: 30_000 }).stdout.trim();
|
||||
if (version !== controllerVersion(controller)) throw new Error(`${controller} version must be ${controllerVersion(controller)}`);
|
||||
const opened = runner({ command: options.agentDeviceCommand,
|
||||
args: ["open", options.bundleId, "--session", CONTROLLER_SESSION, ...(options.platform === "ios" ? ["--device", options.device] : []),
|
||||
"--platform", options.platform, "--level", "full", "--json"], cwd: options.project, environment, timeoutMs: 60_000 });
|
||||
"--platform", options.platform, "--level", "full", "--json"], cwd: options.project, environment,
|
||||
// Argent's first call can wait for a tool-server that is still starting, then relaunch the app until it is readable.
|
||||
timeoutMs: controller === "argent" ? 180_000 : 60_000 });
|
||||
const device = openedSimulatorDevice(opened.stdout, options.bundleId, "initial app open", options.platform);
|
||||
if (options.platform === "ios" && device.deviceModel !== options.device) throw new CiError({ code: "DEVICE_MISMATCH", stage: "runtime",
|
||||
message: `EAS opened ${device.deviceModel} instead of the configured ${options.device}.`,
|
||||
@@ -345,7 +372,7 @@ export function collectRuntime(options: CiMapOptions & { platform: NonNullable<C
|
||||
const value = deviceData[key] ?? data[key];
|
||||
return typeof value === "string" && value.trim() ? value : "unknown";
|
||||
};
|
||||
return { provider: "eas-simulator", controller: "agent-device", controllerPackageVersion: AGENT_DEVICE_VERSION,
|
||||
return { provider: "eas-simulator", controller, controllerPackageVersion: controllerVersion(controller),
|
||||
easCliVersion: EAS_CLI_VERSION, platform: options.platform, controllerDeviceId: device.deviceId, deviceModel: device.deviceModel,
|
||||
osVersion: observed("osVersion"), locale: observed("locale"),
|
||||
orientation: observed("orientation") === "landscape" ? "landscape" : "portrait",
|
||||
|
||||
@@ -11,6 +11,7 @@ import { canonicalJson } from "../shared/canonical-json.js";
|
||||
import type { ExploreConfig } from "../config/explore-config.js";
|
||||
import { hasVerifiedCapture } from "../capture/health.js";
|
||||
import { CAPTURE_OBSERVER_HASH } from "../capture/observer.js";
|
||||
import { ARGENT_VERSION } from "../shared/argent-version.js";
|
||||
|
||||
const METADATA = "cache-metadata.json";
|
||||
const CONTRACT = "explore.capture-cache";
|
||||
@@ -34,6 +35,8 @@ export function captureRecipeConfig(config: ExploreConfig, instructionsSha256?:
|
||||
app: { platform: config.app.platform, bundleId: config.app.bundleId, easProfile: config.app.easProfile,
|
||||
...(config.app.scheme === undefined ? {} : { scheme: config.app.scheme }) },
|
||||
device: config.device, parameters: config.parameters, setup: config.setup ?? [], capture: config.capture,
|
||||
// agent-device recipes stay as they were; an Argent capture is keyed to the Argent release that drove it.
|
||||
...(config.capture.controller === "argent" ? { controllerVersion: ARGENT_VERSION } : {}),
|
||||
});
|
||||
}
|
||||
|
||||
|
||||
+18
-4
@@ -8,8 +8,10 @@ import type { CaptureBundle } from "../contracts/capture.js";
|
||||
import type { SourceCapturePlan } from "../source/capture-plan.js";
|
||||
import type { CommandRunner } from "../capture/run.js";
|
||||
import { runBaselineCi } from "./pipeline.js";
|
||||
import { DEFAULT_EXPLORE_CONFIG_PATH, configPlatforms, readExploreConfig, readExploreInstructions, resolvePlatformConfig, type ExploreConfig, type ExplorePlatform } from "../config/explore-config.js";
|
||||
import { DEFAULT_EXPLORE_CONFIG_PATH, configPlatforms, readExploreConfig, readExploreInstructions, resolvePlatformConfig, withRunOverrides, type ExploreConfig, type ExplorePlatform } from "../config/explore-config.js";
|
||||
import { explorationSecretNames } from "../config/exploration-inputs.js";
|
||||
import { controllerCached } from "../shared/controller-cache.js";
|
||||
import { ARGENT_VERSION } from "../shared/argent-version.js";
|
||||
import { AGENT_PROVIDERS as PROVIDERS, DRAFT_INSTRUCTIONS_MARKER, EXPO_TOKENS_URL as TOKENS, appConfig, simulatorProfiles } from "../config/setup.js";
|
||||
import { captureCompatibility } from "../capture/observer.js";
|
||||
import { assertCaptureEasProfile, assertSimulatorAvailable, repackProfileFrom, unreproducibleEasVariables } from "../capture/eas-build.js";
|
||||
@@ -46,6 +48,8 @@ export type DoctorOptions = {
|
||||
github?: boolean;
|
||||
/** One small model request with the local provider key. */
|
||||
checkModel?: boolean;
|
||||
/** `--controller`: the device controller to check, over the config's `capture.controller`. */
|
||||
controller?: string | undefined;
|
||||
run?: DoctorRun;
|
||||
environment?: NodeJS.ProcessEnv;
|
||||
nodeVersion?: string;
|
||||
@@ -383,7 +387,7 @@ export async function runDoctor(options: DoctorOptions): Promise<DoctorReport> {
|
||||
return { ok: false, mode: null, checks, ...(routes ? { routes } : {}) };
|
||||
}
|
||||
let config: ExploreConfig;
|
||||
try { config = await readExploreConfig(project); }
|
||||
try { config = withRunOverrides(await readExploreConfig(project), { controller: options.controller }); }
|
||||
catch (error) {
|
||||
checks.push(fromError(4, "config", error, { code: "CONFIG_INVALID", nextAction: `Correct ${DEFAULT_EXPLORE_CONFIG_PATH} and rerun doctor.` }));
|
||||
return { ok: false, mode: null, checks };
|
||||
@@ -392,6 +396,7 @@ export async function runDoctor(options: DoctorOptions): Promise<DoctorReport> {
|
||||
checks.push(config.mode === "agent"
|
||||
? { step: 3, id: "mode", status: "pass", message: `Agent mode with ${config.agent!.provider} ${config.agent!.model}. Capture navigation uses the model and is billed to your ${config.agent!.provider} account.` }
|
||||
: { step: 3, id: "mode", status: "pass", message: "Deterministic mode: capture replays config.yaml without a model, so it needs no API key and has no AI charges." });
|
||||
if (config.capture.controller === "argent") checks.push(argentCheck(environment));
|
||||
if (config.capture.launch !== "off") {
|
||||
const ffmpeg = run("ffmpeg", ["-version"], project);
|
||||
checks.push(ffmpeg.status === 0
|
||||
@@ -547,7 +552,16 @@ export function summarizeCaptureCheck(plan: SourceCapturePlan, bundle: CaptureBu
|
||||
* Capture the committed HEAD the way the baseline workflow does, with the local EAS login. This is
|
||||
* the only doctor step that starts an EAS build and a simulator session.
|
||||
*/
|
||||
export async function runCaptureCheck(options: { project: string; output: string; platform?: ExplorePlatform; environment?: NodeJS.ProcessEnv; runner?: CommandRunner; progress?: Progress }): Promise<CaptureCheckResult> {
|
||||
/** An Argent capture records one appearance, and fetches the pinned Argent release on first use. agent-device, the default, is not reported. */
|
||||
function argentCheck(environment: NodeJS.ProcessEnv): DoctorCheck {
|
||||
const cached = controllerCached("argent", environment);
|
||||
return { step: 3, id: "controller", status: "warn", code: "CONTROLLER_APPEARANCE_FIXED",
|
||||
message: `Device controller: Argent ${ARGENT_VERSION} (${cached ? "cached on this machine" : "fetched from npm on the first capture, about 27 MB"}). `
|
||||
+ "Argent cannot switch the simulator's appearance yet (software-mansion/argent#1509), so each capture records one appearance: the app's forced one, else light.",
|
||||
nextAction: "Nothing to do unless you need dark-mode screenshots; use agent-device (the default) for those." };
|
||||
}
|
||||
|
||||
export async function runCaptureCheck(options: { project: string; output: string; platform?: ExplorePlatform; controller?: string | undefined; environment?: NodeJS.ProcessEnv; runner?: CommandRunner; progress?: Progress }): Promise<CaptureCheckResult> {
|
||||
const project = await realpath(options.project);
|
||||
const git = (...args: string[]) => spawnSync("git", ["-C", project, ...args], { encoding: "utf8", timeout: 10_000 });
|
||||
const head = git("rev-parse", "HEAD");
|
||||
@@ -559,7 +573,7 @@ export async function runCaptureCheck(options: { project: string; output: string
|
||||
nextAction: "Commit your changes, including .expo-explore (a local commit is enough; nothing is pushed), then rerun. "
|
||||
+ "To keep unrelated files, run it from a clean checkout instead: git worktree add --detach ../app-capture HEAD, install the app's dependencies there, and run doctor --capture in it." });
|
||||
const commit = head.stdout.trim();
|
||||
const config = resolvePlatformConfig(await readExploreConfig(project), options.platform);
|
||||
const config = withRunOverrides(resolvePlatformConfig(await readExploreConfig(project), options.platform), { controller: options.controller });
|
||||
// Capture keeps its working directories in the system temporary directory, outside the app.
|
||||
await mkdir(options.output, { recursive: true });
|
||||
const output = await realpath(options.output);
|
||||
|
||||
@@ -39,6 +39,8 @@ export type LocalReviewOptions = {
|
||||
platform?: ExplorePlatform | undefined;
|
||||
scope?: string | undefined;
|
||||
expiresIn?: string | undefined;
|
||||
/** `--controller`: the device controller for both sides, over the config's `capture.controller`. */
|
||||
controller?: string | undefined;
|
||||
/** Reuse and keep captures in the local capture cache (default true). */
|
||||
cache?: boolean | undefined;
|
||||
configPath?: string | undefined;
|
||||
@@ -398,7 +400,7 @@ export async function runLocalReview(options: LocalReviewOptions): Promise<Local
|
||||
});
|
||||
const reports: LocalReviewReport[] = [];
|
||||
for (const platform of platforms) {
|
||||
const config = withRunOverrides(resolvePlatformConfig(rawConfig, platform), { scope: options.scope, expiresIn: options.expiresIn });
|
||||
const config = withRunOverrides(resolvePlatformConfig(rawConfig, platform), { scope: options.scope, expiresIn: options.expiresIn, controller: options.controller });
|
||||
const output = join(work, platform); await mkdir(output);
|
||||
outputs.push(output);
|
||||
const platformEnvironment = { ...environment };
|
||||
|
||||
+15
-4
@@ -26,6 +26,7 @@ import type { SourceCapturePlan } from "../source/capture-plan.js";
|
||||
import { createSourceChangeSummaries } from "../source/change-summary.js";
|
||||
import { assertNoCaptureHealthIssues, partitionCaptureHealthIssues, renderCaptureIssueAnnotation, renderComparisonDiagnosticAnnotation, renderNotesUnavailableAnnotation, renderReviewGapAnnotation, sortedCaptureHealthIssues } from "../capture/health.js";
|
||||
import { EXPLORE_PACKAGE, packageBin } from "../shared/package-paths.js";
|
||||
import { agentDeviceLauncher, ensureController } from "../shared/controller-cache.js";
|
||||
import { silentProgress, type Progress } from "../shared/progress.js";
|
||||
|
||||
|
||||
@@ -63,16 +64,22 @@ type CaptureClock = { now?: (() => number) | undefined; sleep?: ((milliseconds:
|
||||
|
||||
function captureOptions(config: ExploreConfig, environment: NodeJS.ProcessEnv, runner?: CommandRunner, clock: CaptureClock = {}) {
|
||||
return { ...(runner && clock.now ? { now: clock.now } : {}), ...(runner && clock.sleep ? { sleep: clock.sleep } : {}), platform: config.app.platform, bundleId: config.app.bundleId,
|
||||
...(config.app.scheme ? { scheme: config.app.scheme } : {}), device: config.device.name,
|
||||
...(config.app.scheme ? { scheme: config.app.scheme } : {}), device: config.device.name, ...(config.device.pose ? { devicePose: config.device.pose } : {}),
|
||||
easProfile: config.app.easProfile, expoToken: environment.EXPO_TOKEN ?? "",
|
||||
maxScreens: 5000, maxActions: config.capture.maxActions, maxDurationMinutes: config.capture.maxMinutes,
|
||||
setup: config.setup ?? [], forceFreshBuild: false, confirmExternalRun: true, confirmTrustedSource: true, repack: config.capture.repack, appearance: config.capture.appearance, launch: config.capture.launch, reset: config.capture.reset, unattributed: config.capture.unattributed, ...(config.capture.readinessSeconds !== undefined ? { readinessSeconds: config.capture.readinessSeconds } : {}),
|
||||
environment, ...(runner ? { runner } : {}), easCommand: packageBin("eas-cli", "eas"), agentDeviceCommand: packageBin("agent-device", "agent-device"), repackCommand: packageBin("@expo/repack-app", "repack-app") };
|
||||
setup: config.setup ?? [], forceFreshBuild: false, confirmExternalRun: true, confirmTrustedSource: true, repack: config.capture.repack, appearance: config.capture.appearance, launch: config.capture.launch, reset: config.capture.reset, unattributed: config.capture.unattributed, ...(config.capture.readinessSeconds !== undefined ? { readinessSeconds: config.capture.readinessSeconds } : {}), ...(config.capture.controller ? { controller: config.capture.controller } : {}),
|
||||
environment, ...(runner ? { runner } : {}), easCommand: packageBin("eas-cli", "eas"), agentDeviceCommand: agentDeviceLauncher(environment), repackCommand: packageBin("@expo/repack-app", "repack-app") };
|
||||
}
|
||||
/**
|
||||
* Head and base run in parallel worker threads when nothing ties them together: an agent session is
|
||||
* shared, an injected runner belongs to this thread, and a plausible baseline needs head's runtime profile.
|
||||
*/
|
||||
/** The controllers a capture of this config runs: agent-device always (it also compares screenshots), Argent when chosen. */
|
||||
async function prefetchControllers(config: ExploreConfig, environment: NodeJS.ProcessEnv, progress: Progress): Promise<void> {
|
||||
await ensureController("agent-device", { environment, progress });
|
||||
if (config.capture.controller === "argent") await ensureController("argent", { environment, progress });
|
||||
}
|
||||
|
||||
export function captureSidesConcurrently(input: { plan: SourceCapturePlan; agent: boolean; injectedRunner: boolean; baselineMayExist: boolean }): boolean {
|
||||
return !input.agent && !input.injectedRunner && !input.baselineMayExist
|
||||
&& input.plan.headCaptureSurfaceIds.length > 0 && input.plan.baseCaptureSurfaceIds.length > 0;
|
||||
@@ -246,6 +253,9 @@ export async function runCiReview(options: {
|
||||
}) {
|
||||
const { projects, output, config, environment, state, assertCurrentHead, postComment } = options;
|
||||
const progress = options.progress ?? silentProgress;
|
||||
// The controllers are fetched before any EAS work, so a blocked download fails before a session is paid for. agent-device
|
||||
// also compares the screenshots. An injected runner (tests) runs no real controller.
|
||||
if (!options.runner) await prefetchControllers(config, environment, progress);
|
||||
const pr = options.presentation;
|
||||
const now = options.now ?? Date.now;
|
||||
const secretValues = Object.entries(environment).filter(([key]) => /(?:TOKEN|SECRET|PASSWORD|API_KEY)/i.test(key)).flatMap(([, value]) => value ? [value] : []);
|
||||
@@ -344,7 +354,7 @@ export async function runCiReview(options: {
|
||||
stage = "compare";
|
||||
progress("comparing base and head captures");
|
||||
const sides = { base: await evidenceSide(join(output, "base-export")), head: await evidenceSide(join(output, "head-export")) };
|
||||
const evidence = await assessPublicEvidence({ platform: config.app.platform, plan, ...sides, ...(options.measure ? { measure: options.measure } : {}), profile: `${config.app.easProfile}:${config.app.bundleId}`, agentDeviceCommand: packageBin("agent-device", "agent-device") });
|
||||
const evidence = await assessPublicEvidence({ platform: config.app.platform, plan, ...sides, ...(options.measure ? { measure: options.measure } : {}), profile: `${config.app.easProfile}:${config.app.bundleId}`, agentDeviceCommand: agentDeviceLauncher(options.environment) });
|
||||
const result = await prepareCaptureReview({ plan, pullRequest: pr, baseDirectory: sides.base.directory, headDirectory: sides.head.directory,
|
||||
runId: options.runId, runAttempt: options.runAttempt, assertCurrentHead, assessments: evidence.surfaces,
|
||||
...(options.platforms ? { platforms: options.platforms } : {}),
|
||||
@@ -444,6 +454,7 @@ export async function runBaselineCi(options: { platform?: ExplorePlatform; proje
|
||||
subscription?: boolean }) {
|
||||
const environment = options.environment ?? process.env;
|
||||
assertCheckout(options.project, options.sha);
|
||||
if (!options.runner) await prefetchControllers(options.config, environment, options.progress ?? silentProgress);
|
||||
const output = resolve(options.output);
|
||||
const relativeOutput = relative(await realpath(options.project), output);
|
||||
if (!relativeOutput.startsWith("..") || isAbsolute(relativeOutput)) throw new Error("Baseline output must be outside the source checkout");
|
||||
|
||||
+5
-5
@@ -50,8 +50,8 @@ const flagKinds: Record<string, Record<string, "value" | "boolean">> = {
|
||||
setup: { project: "value", platform: "value", device: "value", scope: "value", profile: "value", "bundle-id": "value", scheme: "value", navigation: "value",
|
||||
mode: "value", provider: "value", model: "value", param: "value", "app-state": "value", workflows: "boolean", "no-workflows": "boolean",
|
||||
"non-interactive": "boolean", check: "boolean", force: "boolean", help: "boolean" },
|
||||
doctor: { project: "value", offline: "boolean", "no-github": "boolean", "check-model": "boolean", capture: "boolean", output: "value", platform: "value", yes: "boolean", help: "boolean" },
|
||||
"capture:baseline": { project:"value", sha:"value", output:"value", config:"value", platform:"value" },
|
||||
doctor: { project: "value", offline: "boolean", "no-github": "boolean", "check-model": "boolean", capture: "boolean", output: "value", platform: "value", controller: "value", yes: "boolean", help: "boolean" },
|
||||
"capture:baseline": { project:"value", sha:"value", output:"value", config:"value", platform:"value", controller:"value" },
|
||||
"source:verify": { "base-project":"value", "head-project":"value", "base-sha":"value", "head-sha":"value", output:"value", config:"value", scope:"value", platform:"value" },
|
||||
"config:platforms": { project:"value", config:"value" },
|
||||
"screen:list": { limit: "value", cursor: "value", unexplored: "boolean" },
|
||||
@@ -83,15 +83,15 @@ const flagKinds: Record<string, Record<string, "value" | "boolean">> = {
|
||||
validate: {},
|
||||
export: { output: "value" },
|
||||
"export:web": {catalog:"value",output:"value"},
|
||||
"capture:review": { "base-project":"value", "head-project":"value", "pull-request":"value", compare:"value", output:"value", config:"value", platform:"value", scope:"value", "expires-in":"value",
|
||||
"capture:review": { "base-project":"value", "head-project":"value", "pull-request":"value", compare:"value", output:"value", config:"value", platform:"value", controller:"value", scope:"value", "expires-in":"value",
|
||||
base:"value", head:"value", project:"value", committed:"boolean", uncommitted:"boolean", "include-untracked":"boolean", upload:"boolean", "no-open":"boolean", "no-cache":"boolean", port:"value" },
|
||||
|
||||
|
||||
|
||||
"explore:binary": { archive:"value", output:"value", platform:"value", device:"value", "bundle-id":"value", "launch-url":"value", hints:"value", "allow-destructive":"value",
|
||||
"explore:binary": { archive:"value", output:"value", platform:"value", controller:"value", device:"value", "bundle-id":"value", "launch-url":"value", hints:"value", "allow-destructive":"value",
|
||||
"max-duration-minutes":"value", "max-screens":"value", "max-actions":"value", provider:"value", model:"value", owner:"value", project:"value",
|
||||
upload:"boolean", "no-upload":"boolean", "expires-in":"value", alias:"value" },
|
||||
"explore:session": { session:"value", "env-file":"value", "bundle-id":"value", "app-name":"value", "app-version":"value", output:"value", platform:"value", device:"value", "launch-url":"value", hints:"value",
|
||||
"explore:session": { session:"value", "env-file":"value", "bundle-id":"value", "app-name":"value", "app-version":"value", output:"value", platform:"value", controller:"value", device:"value", "launch-url":"value", hints:"value",
|
||||
"allow-destructive":"value", "max-duration-minutes":"value", "max-screens":"value", "max-actions":"value", provider:"value", model:"value", owner:"value", project:"value",
|
||||
upload:"boolean", "expires-in":"value", alias:"value", "no-open":"boolean", port:"value" },
|
||||
"ci:report": { input:"value", output:"value", platform:"value" },
|
||||
|
||||
@@ -38,13 +38,14 @@ export async function exploreBinary(): Promise<void> {
|
||||
const expiresAfterDays = expiresInDays(flag("expires-in") ?? "7d");
|
||||
const platform = flag("platform") === undefined ? undefined : oneOf("platform", ["ios", "android"] as const);
|
||||
const provider = flag("provider") === undefined ? undefined : oneOf("provider", ["anthropic", "openai"] as const);
|
||||
const controller = flag("controller") === undefined ? undefined : oneOf("controller", ["agent-device", "argent"] as const);
|
||||
const started = Date.now();
|
||||
const say = (message: string) => { process.stderr.write(`[explore ${Math.round((Date.now() - started) / 1000)}s] ${message}\n`); };
|
||||
const allowDestructive = flags("allow-destructive").flatMap(value => value.split(",")).map(value => value.trim()).filter(Boolean);
|
||||
if (!has("no-upload")) await assertHostingExport();
|
||||
const result = await runBinaryExploration({
|
||||
archive: resolve(process.cwd(), archive), output: outputDirectory, progress: say,
|
||||
...(platform ? { platform } : {}), ...(provider ? { provider } : {}),
|
||||
...(platform ? { platform } : {}), ...(provider ? { provider } : {}), ...(controller ? { controller } : {}),
|
||||
...(flag("device") ? { device: flag("device")! } : {}), ...(flag("bundle-id") ? { bundleId: flag("bundle-id")! } : {}),
|
||||
...(flag("launch-url") ? { launchUrl: flag("launch-url")! } : {}), ...(flag("hints") ? { hints: flag("hints")! } : {}),
|
||||
...(allowDestructive.length ? { allowDestructive } : {}), ...(flag("model") ? { model: flag("model")! } : {}),
|
||||
@@ -93,6 +94,7 @@ export async function exploreSession(): Promise<void> {
|
||||
const expiresAfterDays = expiresInDays(flag("expires-in") ?? "7d");
|
||||
const platform = flag("platform") === undefined ? undefined : oneOf("platform", ["ios", "android"] as const);
|
||||
const provider = flag("provider") === undefined ? undefined : oneOf("provider", ["anthropic", "openai"] as const);
|
||||
const controller = flag("controller") === undefined ? undefined : oneOf("controller", ["agent-device", "argent"] as const);
|
||||
const port = flag("port") === undefined ? undefined : nonNegativeInteger("port");
|
||||
const started = Date.now();
|
||||
const say = (message: string) => { process.stderr.write(`[explore ${Math.round((Date.now() - started) / 1000)}s] ${message}\n`); };
|
||||
@@ -103,7 +105,7 @@ export async function exploreSession(): Promise<void> {
|
||||
output: outputDirectory, progress: say,
|
||||
...(bundleId ? { bundleId } : {}), ...(session ? { session } : {}), ...(envFile ? { envFile } : {}),
|
||||
...(flag("app-name") ? { appName: flag("app-name")! } : {}), ...(flag("app-version") ? { version: flag("app-version")! } : {}),
|
||||
...(platform ? { platform } : {}), ...(provider ? { provider } : {}),
|
||||
...(platform ? { platform } : {}), ...(provider ? { provider } : {}), ...(controller ? { controller } : {}),
|
||||
...(flag("device") ? { device: flag("device")! } : {}),
|
||||
...(flag("launch-url") ? { launchUrl: flag("launch-url")! } : {}), ...(flag("hints") ? { hints: flag("hints")! } : {}),
|
||||
...(allowDestructive.length ? { allowDestructive } : {}), ...(flag("model") ? { model: flag("model")! } : {}),
|
||||
|
||||
@@ -26,7 +26,7 @@ export async function doctor(): Promise<void> {
|
||||
if (has("help")) return help();
|
||||
const project = flag("project") ?? process.cwd();
|
||||
const report = await runDoctor({ project, online: !has("offline"), github: !has("no-github") && !has("offline"),
|
||||
checkModel: has("check-model") });
|
||||
checkModel: has("check-model"), controller: flag("controller") });
|
||||
if (!has("capture")) {
|
||||
if (has("json")) output({ ...report });
|
||||
else console.log(formatDoctorReport(report));
|
||||
@@ -53,7 +53,7 @@ Fix the problems in steps 1–5 before a capture check.`);
|
||||
let result: Awaited<ReturnType<typeof runCaptureCheck>>;
|
||||
try {
|
||||
const platform = platformFlag();
|
||||
result = await runCaptureCheck({ project, ...(platform ? { platform } : {}), output: resolve(flag("output") ?? await mkdtemp(join(tmpdir(), "expo-explore-capture-"))), progress: stderrProgress() });
|
||||
result = await runCaptureCheck({ project, ...(platform ? { platform } : {}), controller: flag("controller"), output: resolve(flag("output") ?? await mkdtemp(join(tmpdir(), "expo-explore-capture-"))), progress: stderrProgress() });
|
||||
} catch (error) {
|
||||
// A refusal before any EAS work: show it with its next action next to the static report.
|
||||
if (!(error instanceof CiError)) throw error;
|
||||
@@ -203,7 +203,7 @@ export async function captureReview(): Promise<void> {
|
||||
const configPath = flag("config") ?? DEFAULT_EXPLORE_CONFIG_PATH;
|
||||
const platform = platformFlag();
|
||||
const rawConfig = await readExploreConfig(headProject, configPath);
|
||||
const config = withRunOverrides(resolvePlatformConfig(rawConfig, platform), { scope: flag("scope"), expiresIn: flag("expires-in") });
|
||||
const config = withRunOverrides(resolvePlatformConfig(rawConfig, platform), { scope: flag("scope"), expiresIn: flag("expires-in"), controller: flag("controller") });
|
||||
if (has("pull-request") === has("compare")) argumentError("Pass --pull-request FILE for a pull request, or --compare FILE for any two commits.", has("compare") ? "compare" : "pull-request");
|
||||
const common = { ...(platform ? { platform } : {}), platforms: listPlatforms(rawConfig), baseProject: required("base-project"), headProject,
|
||||
output: required("output"), config, configPath, progress: stderrProgress() };
|
||||
@@ -217,7 +217,7 @@ export async function captureReview(): Promise<void> {
|
||||
export async function captureBaseline(): Promise<void> {
|
||||
const project = required("project");
|
||||
const platform = platformFlag();
|
||||
const config = resolvePlatformConfig(await readExploreConfig(project, flag("config") ?? DEFAULT_EXPLORE_CONFIG_PATH), platform);
|
||||
const config = withRunOverrides(resolvePlatformConfig(await readExploreConfig(project, flag("config") ?? DEFAULT_EXPLORE_CONFIG_PATH), platform), { controller: flag("controller") });
|
||||
output({ ok: true, ...await runBaselineCi({ ...(platform ? { platform } : {}), project, sha: required("sha"), output: required("output"), config, progress: stderrProgress() }) });
|
||||
}
|
||||
|
||||
@@ -227,7 +227,7 @@ async function localReview(): Promise<void> {
|
||||
const result = await runLocalReview({ project: flag("project") ?? process.cwd(), base: flag("base"), head: flag("head"),
|
||||
// --include-untracked is accepted from before untracked files were included by default.
|
||||
committed: has("committed"), uncommitted: has("uncommitted"), ...(platform ? { platform } : {}),
|
||||
scope: flag("scope"), expiresIn: flag("expires-in"), cache: !has("no-cache"), configPath: flag("config"), progress: stderrProgress() });
|
||||
scope: flag("scope"), expiresIn: flag("expires-in"), controller: flag("controller"), cache: !has("no-cache"), configPath: flag("config"), progress: stderrProgress() });
|
||||
if (has("output")) {
|
||||
for (const report of result.reports) {
|
||||
const target = resolve(required("output"), report.platform);
|
||||
|
||||
+13
-9
@@ -15,16 +15,18 @@ const GET_STARTED = `Get started (run these in the Expo app's directory):
|
||||
doctor [--project DIRECTORY] [--offline] [--no-github] [--check-model] [--json]
|
||||
(checks every setup step and prints the next action for each problem; exits 1 until ready)
|
||||
(--offline skips EAS and GitHub; --check-model sends one small request with the local provider key)
|
||||
doctor --capture [--project DIRECTORY] [--output DIRECTORY] [--platform ios|android] [--yes]
|
||||
doctor --capture [--project DIRECTORY] [--output DIRECTORY] [--platform ios|android] [--controller agent-device|argent] [--yes]
|
||||
(captures the committed HEAD like the baseline workflow, with your eas login, and reports each route)
|
||||
capture [--base REF] [--head REF | --committed] [--platform ios|android] [--scope all|changes]
|
||||
[--upload [--expires-in 7d|30d|never]] [--no-open] [--no-cache] [--output DIRECTORY] [--project DIRECTORY]
|
||||
[--controller agent-device|argent] [--upload [--expires-in 7d|30d|never]] [--no-open] [--no-cache] [--output DIRECTORY] [--project DIRECTORY]
|
||||
(on this machine: checks out both commits in temporary worktrees, captures them with your eas login and your
|
||||
local claude or codex login, and opens the report; the head is HEAD with your uncommitted changes, as eas build
|
||||
uploads them (--committed, or cli.requireCommit in eas.json, leaves them out); the base defaults to where HEAD
|
||||
left the default branch;
|
||||
without .expo-explore/config.yaml it uses the defaults setup would write;
|
||||
it runs both commits' code as you, so review only commits you would run; capture:review is the same command)
|
||||
it runs both commits' code as you, so review only commits you would run; capture:review is the same command;
|
||||
--controller argent drives the simulator with Argent instead of agent-device, the default (or set
|
||||
capture.controller in config.yaml); Argent cannot switch appearance yet, so it captures one appearance)
|
||||
view [--catalog FILE] [--port N] [--no-open]
|
||||
(opens a report in the Viewer)
|
||||
reports [list | open ID | add REPORT... | upload ID | rm ID | prune] [--all] [--json]
|
||||
@@ -40,6 +42,7 @@ const BINARY = `Prebuilt apps (no source needed; runs on EAS Simulator with your
|
||||
(installs the archive in a fresh EAS Simulator session, lets the model explore it, writes a map
|
||||
and report under --output, hosts the report on EAS Hosting, and prints the link)
|
||||
Flags, all optional: --device NAME --bundle-id ID --launch-url URL --hints "what to focus on"
|
||||
--controller agent-device|argent (the session's device controller; agent-device by default)
|
||||
(a sign-in in --hints is written as {{secret:NAME}}: Explore types the value of the environment variable NAME,
|
||||
and the model and the report only see the reference)
|
||||
--max-duration-minutes N --max-screens N --max-actions N --provider anthropic|openai --model ID
|
||||
@@ -49,11 +52,12 @@ const BINARY = `Prebuilt apps (no source needed; runs on EAS Simulator with your
|
||||
(iOS needs a simulator build; a device .ipa and Android .aab are rejected before any session starts)
|
||||
explore:session [SESSION_ID] [--bundle-id ID] [--output DIRECTORY] [--upload] [--json]
|
||||
(explores an app that is already installed on an EAS Simulator session you started — run it where
|
||||
"eas simulator:start --type agent-device --out-config-type dotenv" wrote .env.eas-simulator, or pass
|
||||
--env-file FILE, or export EAS_SIMULATOR_SESSION_ID, AGENT_DEVICE_DAEMON_BASE_URL and
|
||||
AGENT_DEVICE_DAEMON_AUTH_TOKEN; writes the map and report, then opens them in the local Viewer;
|
||||
"eas simulator:start --type agent-device --out-config-type dotenv" (or --type argent) wrote .env.eas-simulator,
|
||||
or pass --env-file FILE, or export EAS_SIMULATOR_SESSION_ID with AGENT_DEVICE_DAEMON_BASE_URL and
|
||||
AGENT_DEVICE_DAEMON_AUTH_TOKEN, or with ARGENT_TOOLS_URL and ARGENT_AUTH_TOKEN; writes the map and report, then opens them in the local Viewer;
|
||||
--upload hosts the report instead, --no-open skips the Viewer; the session is left running;
|
||||
the app is the one in the foreground, else the only installed one; --bundle-id picks it otherwise)
|
||||
the app is the one in the foreground, else the only installed one; --bundle-id picks it otherwise;
|
||||
the controller follows the session's type, and --controller must match it)
|
||||
Extra flags: --app-name NAME --app-version X.Y --port N, plus the explore:binary budget/model flags
|
||||
Afterwards: view --dir DIRECTORY, screen:list --dir DIRECTORY, gap:list --dir DIRECTORY`;
|
||||
|
||||
@@ -61,9 +65,9 @@ const CI = `CI (the installed workflows run these; they manage remote EAS Simula
|
||||
config:platforms [--project DIRECTORY] [--config FILE]
|
||||
(lists the platforms config.yaml captures; the review workflow's matrix)
|
||||
capture:review --base-project DIRECTORY --head-project DIRECTORY (--pull-request FILE | --compare FILE)
|
||||
--output TEMP_DIRECTORY [--config .expo-explore/config.yaml] [--platform ios|android]
|
||||
--output TEMP_DIRECTORY [--config .expo-explore/config.yaml] [--platform ios|android] [--controller agent-device|argent]
|
||||
(--compare reviews any two commits without a PR: {"origin":"compare","repositoryId","repository","base":{ref,sha},"head":{ref,sha}})
|
||||
capture:baseline --project DIRECTORY --sha COMMIT --output TEMP_DIRECTORY [--config FILE] [--platform ios|android]
|
||||
capture:baseline --project DIRECTORY --sha COMMIT --output TEMP_DIRECTORY [--config FILE] [--platform ios|android] [--controller agent-device|argent]
|
||||
source:verify --base-project DIRECTORY --head-project DIRECTORY
|
||||
--base-sha COMMIT --head-sha COMMIT --output DIRECTORY [--config FILE] [--scope all|changes] [--platform ios|android]
|
||||
compare --baseline DIRECTORY --current DIRECTORY --output FILE
|
||||
|
||||
@@ -2,7 +2,7 @@ import { CiError } from "../shared/ci-errors.js";
|
||||
import type { CaptureSetupAction } from "./explore-config.js";
|
||||
|
||||
const TOKEN = /\{\{secret:([A-Z][A-Z0-9_]{0,127})\}\}/g;
|
||||
const RESERVED = /^(?:GITHUB_|RUNNER_|ACTIONS_|AGENT_DEVICE_|OPENAI_|ANTHROPIC_|EXPO_TOKEN$)/;
|
||||
const RESERVED = /^(?:GITHUB_|RUNNER_|ACTIONS_|AGENT_DEVICE_|ARGENT_|OPENAI_|ANTHROPIC_|EXPO_TOKEN$)/;
|
||||
|
||||
/** References are data, never shell expressions or arbitrary environment access. */
|
||||
export function explorationSecretNames(text: string): string[] {
|
||||
|
||||
@@ -43,6 +43,10 @@ export const DEFAULT_ANDROID_DEVICE = "pixel_7";
|
||||
* One platform's capture target. `platforms.ios` fields default to the flat `app`/`device` fields;
|
||||
* `platforms.android` needs its own package and EAS profile (an `android.buildType: apk` profile).
|
||||
*/
|
||||
/** The poses a foldable device can be captured in (`fold` in agent-device and Argent). */
|
||||
export const DEVICE_POSES = ["closed", "half-open", "open"] as const;
|
||||
export type DevicePose = typeof DEVICE_POSES[number];
|
||||
|
||||
export type PlatformConfig = { device?: string; bundleId?: string; easProfile?: string };
|
||||
|
||||
/** Source discovery never consumes a user-authored screen inventory. */
|
||||
@@ -50,7 +54,11 @@ export type ExploreConfig = {
|
||||
mode: "deterministic" | "agent";
|
||||
app: { name?: string; platform: ExplorePlatform; bundleId: string; easProfile: string; scheme?: string };
|
||||
navigation: { provider: "auto" | "expo-router" | "react-navigation"; entry?: string };
|
||||
device: { name: string };
|
||||
/**
|
||||
* `pose` folds a foldable (iPhone Duo) before capture: closed lights the outer display, open the inner one.
|
||||
* Absent leaves the device as it starts (closed). It applies to the primary platform's device.
|
||||
*/
|
||||
device: { name: string; pose?: DevicePose };
|
||||
/**
|
||||
* Each platform Explore captures, in CI as one matrix job each. Absent: the single platform the
|
||||
* flat fields describe. Capture code never reads this map; resolvePlatformConfig flattens it.
|
||||
@@ -58,7 +66,9 @@ export type ExploreConfig = {
|
||||
platforms?: Partial<Record<ExplorePlatform, PlatformConfig>>;
|
||||
/** `exclude` names routes, as `requiresRoute` does, that stay in the map but are never captured. */
|
||||
exploration: { scope: "changes" | "all"; exclude?: string[] };
|
||||
capture: { maxMinutes: number; maxActions: number; repack: "eas" | "local"; appearance: AppearanceSetting; launch: LaunchSetting; reset: RouteResetSetting; unattributed: UnattributedSetting; readinessSeconds?: number };
|
||||
capture: { maxMinutes: number; maxActions: number; repack: "eas" | "local"; appearance: AppearanceSetting; launch: LaunchSetting; reset: RouteResetSetting; unattributed: UnattributedSetting; readinessSeconds?: number;
|
||||
/** The device controller; absent means agent-device, so configs that never chose one keep their cache recipes. */
|
||||
controller?: "argent" };
|
||||
parameters?: Record<string, Record<string, string>>;
|
||||
setup?: ExploreSetupAction[];
|
||||
agent?: { provider: "openai" | "anthropic"; model: string; instructions?: string };
|
||||
@@ -237,13 +247,15 @@ export function validateExploreConfig(value: unknown): ExploreConfig {
|
||||
const app = record(root.app, "app");
|
||||
exactKeys(app, ["name", "platform", "bundleId", "easProfile", "scheme"], "app");
|
||||
const device = record(root.device, "device");
|
||||
exactKeys(device, ["name"], "device");
|
||||
exactKeys(device, ["name", "pose"], "device");
|
||||
const pose = device.pose === undefined ? undefined : literal(device.pose, DEVICE_POSES, "device.pose", "closed");
|
||||
const navigation = optionalRecord(root.navigation, "navigation");
|
||||
exactKeys(navigation, ["provider", "entry"], "navigation");
|
||||
const exploration = optionalRecord(root.exploration, "exploration");
|
||||
exactKeys(exploration, ["scope", "exclude"], "exploration");
|
||||
const capture = optionalRecord(root.capture, "capture");
|
||||
exactKeys(capture, ["maxMinutes", "maxActions", "repack", "appearance", "launch", "reset", "unattributed", "readinessSeconds"], "capture");
|
||||
exactKeys(capture, ["maxMinutes", "maxActions", "repack", "appearance", "launch", "reset", "unattributed", "readinessSeconds", "controller"], "capture");
|
||||
const controller = literal(capture.controller, ["agent-device", "argent"] as const, "capture.controller", "agent-device");
|
||||
const mode = literal(root.mode, ["deterministic", "agent"] as const, "mode", "deterministic");
|
||||
const name = optionalText(app.name, "app.name", 128);
|
||||
const scheme = app.scheme === undefined ? undefined : customScheme(app.scheme, "app.scheme");
|
||||
@@ -276,7 +288,7 @@ export function validateExploreConfig(value: unknown): ExploreConfig {
|
||||
provider: literal(navigation.provider, ["auto", "expo-router", "react-navigation"] as const, "navigation.provider", "auto"),
|
||||
...(navigation.entry === undefined ? {} : { entry: repoPath(navigation.entry, "navigation.entry") }),
|
||||
},
|
||||
device: { name: text(device.name, "device.name", 128) },
|
||||
device: { name: text(device.name, "device.name", 128), ...(pose === undefined ? {} : { pose }) },
|
||||
...(platforms === undefined ? {} : { platforms }),
|
||||
exploration: {
|
||||
scope: literal(exploration.scope, ["changes", "all"] as const, "exploration.scope", "changes"),
|
||||
@@ -291,6 +303,7 @@ export function validateExploreConfig(value: unknown): ExploreConfig {
|
||||
reset: parseRouteResetSetting(capture.reset, "capture.reset"),
|
||||
unattributed: parseUnattributedSetting(capture.unattributed, "capture.unattributed"),
|
||||
...(capture.readinessSeconds !== undefined ? { readinessSeconds: positiveInteger(capture.readinessSeconds, "capture.readinessSeconds") } : {}),
|
||||
...(controller === "argent" ? { controller } : {}),
|
||||
},
|
||||
...(root.parameters === undefined ? {} : { parameters: parameters(root.parameters) }),
|
||||
...(root.setup === undefined ? {} : { setup: setupActions(root.setup, scheme) }),
|
||||
@@ -362,7 +375,9 @@ export function resolvePlatformConfig(config: ExploreConfig, platform: ExplorePl
|
||||
return { ...rest,
|
||||
app: { ...config.app, platform, bundleId: entry.bundleId ?? (primary ? config.app.bundleId : fail(`platforms.${platform}.bundleId is required`)),
|
||||
easProfile: entry.easProfile ?? (primary ? config.app.easProfile : fail(`platforms.${platform}.easProfile is required`)) },
|
||||
device: { name: entry.device ?? (primary ? config.device.name : platform === "android" ? DEFAULT_ANDROID_DEVICE : config.device.name) } };
|
||||
device: { name: entry.device ?? (primary ? config.device.name : platform === "android" ? DEFAULT_ANDROID_DEVICE : config.device.name),
|
||||
// A pose belongs to the primary platform's device; the other platform's device starts as it is.
|
||||
...(primary && config.device.pose ? { pose: config.device.pose } : {}) } };
|
||||
}
|
||||
|
||||
/**
|
||||
@@ -370,8 +385,13 @@ export function resolvePlatformConfig(config: ExploreConfig, platform: ExplorePl
|
||||
* every screen (`scope: all`) and keep its hosted link (`expiresIn: never`). `expiresIn` changes nothing when the
|
||||
* config hosts no report.
|
||||
*/
|
||||
export function withRunOverrides(config: ExploreConfig, overrides: { scope?: string | undefined; expiresIn?: string | undefined }): ExploreConfig {
|
||||
export function withRunOverrides(config: ExploreConfig, overrides: { scope?: string | undefined; expiresIn?: string | undefined; controller?: string | undefined }): ExploreConfig {
|
||||
let result = config;
|
||||
if (overrides.controller !== undefined) {
|
||||
if (overrides.controller !== "agent-device" && overrides.controller !== "argent") fail("--controller must be agent-device or argent", "--controller");
|
||||
const { controller: _previous, ...capture } = result.capture;
|
||||
result = { ...result, capture: { ...capture, ...(overrides.controller === "argent" ? { controller: "argent" as const } : {}) } };
|
||||
}
|
||||
if (overrides.scope !== undefined) {
|
||||
if (overrides.scope !== "changes" && overrides.scope !== "all") fail("--scope must be changes or all", "--scope");
|
||||
result = { ...result, exploration: { ...result.exploration, scope: overrides.scope } };
|
||||
|
||||
@@ -73,6 +73,8 @@ export type CaptureBundle = {
|
||||
/** Execution completion time, recorded even when no routes require screenshots. */
|
||||
completedAt?: string;
|
||||
appName?: string;
|
||||
/** The device controller that drove the capture; absent for agent-device, the default. */
|
||||
controller?: "argent";
|
||||
/** The icon the app config declares, shrunk to at most 128 pixels; absent when unavailable. */
|
||||
appIcon?: Omit<AppIconImage, "url"> & { path: string };
|
||||
profile: string; selectedSurfaceIds: string[];
|
||||
@@ -238,6 +240,8 @@ export type PublicReview = {
|
||||
appIcon?: AppIconImage;
|
||||
/** Absent in reports published before Android support: iOS. */
|
||||
platform?: "ios" | "android";
|
||||
/** The device controller that drove the head capture; absent for agent-device, the default. */
|
||||
controller?: "argent";
|
||||
device?: { model: string; osVersion: string };
|
||||
/** The share of each screenshot's height the verdict ignored as the status bar. */
|
||||
statusBarBandPercent?: number;
|
||||
|
||||
@@ -284,6 +284,10 @@ async function constructCaptureReview(options: CaptureReviewOptions, store: Scre
|
||||
? sourceImpactKinds(surface.sourceChange.files.map((file) => file.relation))
|
||||
: []
|
||||
);
|
||||
// Each controller reads and drives the device its own way; a review compares captures made the same way.
|
||||
if ((head.bundle.controller ?? "agent-device") !== (base.bundle.controller ?? "agent-device")) {
|
||||
throw new Error(`The base was captured with ${base.bundle.controller ?? "agent-device"} and the head with ${head.bundle.controller ?? "agent-device"}; capture both sides with the same controller.`);
|
||||
}
|
||||
const colorSchemes = bundleColorSchemes(head.bundle);
|
||||
const baseColorSchemes = bundleColorSchemes(base.bundle);
|
||||
const review: PublicReview = {
|
||||
@@ -291,7 +295,7 @@ async function constructCaptureReview(options: CaptureReviewOptions, store: Scre
|
||||
runId: options.runId, runAttempt: options.runAttempt,
|
||||
...(plan.navigation ? { navigation: plan.navigation } : {}),
|
||||
runtime: { projectId: head.bundle.easProjectId ?? "", buildId: head.bundle.easBuildId ?? "", gitCommit: plan.headSha,
|
||||
platform: head.bundle.platform ?? "ios", statusBarBandPercent: statusBarBandPercent(head.bundle.platform),
|
||||
platform: head.bundle.platform ?? "ios", ...(head.bundle.controller === "argent" ? { controller: "argent" as const } : {}), statusBarBandPercent: statusBarBandPercent(head.bundle.platform),
|
||||
...(homeIndicatorBandPercent(head.bundle.platform) > 0 ? { homeIndicatorBandPercent: homeIndicatorBandPercent(head.bundle.platform) } : {}),
|
||||
...(options.platforms && options.platforms.length > 1 ? { platforms: [...options.platforms] } : {}),
|
||||
...(colorSchemes.length > 1 ? { colorSchemes: [...colorSchemes] } : {}),
|
||||
|
||||
@@ -11,12 +11,14 @@ import type {
|
||||
} from "./runtime-evidence.js";
|
||||
import type { ExploreMap, Observation, Screen } from "../types.js";
|
||||
import { CAPTURE_OBSERVER_IDENTIFIER } from "../capture/observer.js";
|
||||
import { ARGENT_VERSION } from "../shared/argent-version.js";
|
||||
|
||||
/** Strict, non-secret subset written after a successful EAS Simulator cleanup. */
|
||||
export type RuntimeExecutionContext = {
|
||||
provider: "eas-simulator";
|
||||
controller: "agent-device";
|
||||
controllerPackageVersion: typeof AGENT_DEVICE_VERSION;
|
||||
controller: "agent-device" | "argent";
|
||||
/** The pinned package of the controller that drove the session. */
|
||||
controllerPackageVersion: typeof AGENT_DEVICE_VERSION | typeof ARGENT_VERSION;
|
||||
easCliVersion: typeof EAS_CLI_VERSION;
|
||||
platform: "ios" | "android";
|
||||
deviceModel: string;
|
||||
@@ -107,12 +109,13 @@ export function parseRuntimeExecutionContext(value: unknown): RuntimeExecutionCo
|
||||
}
|
||||
return context.colorSchemes.map((entry) => literal(entry, ["light", "dark"], "Runtime color schemes"));
|
||||
})();
|
||||
const controller = literal(context.controller, ["agent-device", "argent"], "Runtime controller");
|
||||
return {
|
||||
provider: literal(context.provider, ["eas-simulator"], "Runtime provider"),
|
||||
controller: literal(context.controller, ["agent-device"], "Runtime controller"),
|
||||
controller,
|
||||
controllerPackageVersion: literal(
|
||||
context.controllerPackageVersion,
|
||||
[AGENT_DEVICE_VERSION],
|
||||
[controller === "argent" ? ARGENT_VERSION : AGENT_DEVICE_VERSION],
|
||||
"Controller package version",
|
||||
),
|
||||
easCliVersion: literal(context.easCliVersion, [EAS_CLI_VERSION], "EAS CLI version"),
|
||||
|
||||
@@ -93,7 +93,7 @@ export type RawCaptureSample = {
|
||||
|
||||
export type RawSimulatorEnvironment = {
|
||||
provider: "eas-simulator";
|
||||
controller: "agent-device";
|
||||
controller: "agent-device" | "argent";
|
||||
platform: Platform;
|
||||
deviceModel: string;
|
||||
osVersion: string;
|
||||
@@ -247,7 +247,7 @@ export type RuntimeEnvironmentEvidence = {
|
||||
profile: EvidenceField<"capture-context", string>;
|
||||
fixturePersona?: EvidenceField<"capture-context", string>;
|
||||
provider: EvidenceField<"eas-agent-device", "eas-simulator">;
|
||||
controller: EvidenceField<"eas-agent-device", "agent-device">;
|
||||
controller: EvidenceField<"eas-agent-device", "agent-device" | "argent">;
|
||||
controllerPackageVersion?: EvidenceField<"capture-context", string>;
|
||||
easCliVersion?: EvidenceField<"capture-context", string>;
|
||||
platform: EvidenceField<"eas-agent-device", Platform>;
|
||||
@@ -785,7 +785,7 @@ function parseEnvironment(value: unknown): RawSimulatorEnvironment {
|
||||
);
|
||||
return {
|
||||
provider: literal(environment.provider, ["eas-simulator"], "Runtime provider"),
|
||||
controller: literal(environment.controller, ["agent-device"], "Runtime controller"),
|
||||
controller: literal(environment.controller, ["agent-device", "argent"], "Runtime controller"),
|
||||
platform: literal(environment.platform, PLATFORMS, "Runtime platform"),
|
||||
deviceModel: safeString(environment.deviceModel, "Device model", 256),
|
||||
osVersion: safeString(environment.osVersion, "OS version", 256),
|
||||
|
||||
@@ -0,0 +1,5 @@
|
||||
/**
|
||||
* The one Argent version Explore runs. The local CLI (`package.json`) and the EAS Simulator controller
|
||||
* (`--package-version` for an `argent` session) must both be this version.
|
||||
*/
|
||||
export const ARGENT_VERSION = "0.29.0";
|
||||
@@ -0,0 +1,170 @@
|
||||
/**
|
||||
* The device controllers Explore drives, fetched on first use instead of installed with Explore. Each is pinned to
|
||||
* an exact npm release and its sha512 integrity; the tarball is checked before anything in it is written, nothing in
|
||||
* it runs at install time, and neither controller needs other packages at run time.
|
||||
*/
|
||||
import { createHash, randomUUID } from "node:crypto";
|
||||
import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
|
||||
import { chmod, mkdir, open, readdir, rename, rm, stat, writeFile } from "node:fs/promises";
|
||||
import { homedir } from "node:os";
|
||||
import { dirname, join, resolve, sep } from "node:path";
|
||||
import { fileURLToPath } from "node:url";
|
||||
import { safeRelativePath, walkTar } from "../binary/archive.js";
|
||||
import { CiError } from "./ci-errors.js";
|
||||
import { AGENT_DEVICE_VERSION } from "./agent-device-version.js";
|
||||
import { ARGENT_VERSION } from "./argent-version.js";
|
||||
|
||||
export type ControllerName = "agent-device" | "argent";
|
||||
|
||||
/** Each controller's npm release, the file Explore runs from it, and the integrity npm publishes for it. */
|
||||
export const CONTROLLER_PACKAGES: Record<ControllerName, { name: string; version: string; bin: string; integrity: string }> = {
|
||||
"agent-device": { name: "agent-device", version: AGENT_DEVICE_VERSION, bin: "bin/agent-device.mjs",
|
||||
integrity: "sha512-Om1j6oNJkeKlkk8lBM+0V9bKwpxUXLMf/PDDSvAt3RFquBRqAiM58J81E0rvPQNxs6GCjhABYpwVvIAXptxjjA==" },
|
||||
argent: { name: "@swmansion/argent", version: ARGENT_VERSION, bin: "dist/cli.js",
|
||||
integrity: "sha512-XXWlWZJlHKqnAvNx3RDhuiVFQOPqh5EDB76+mFAyqC2mutC6irzw03+M/6S/WQ+Dzz2IYOkEfOzQnOOdhrGgJg==" },
|
||||
};
|
||||
|
||||
const COMPLETE = ".explore-controller.json";
|
||||
const MAX_CONTROLLER_BYTES = 256 * 1024 * 1024;
|
||||
const LAUNCHER = fileURLToPath(new URL("../capture/controller-launcher.js", import.meta.url));
|
||||
|
||||
/** Where fetched controllers live: EXPLORE_CONTROLLER_CACHE, else the user's cache directory. */
|
||||
export function controllerCacheRoot(environment: NodeJS.ProcessEnv = process.env): string {
|
||||
if (environment.EXPLORE_CONTROLLER_CACHE) return resolve(environment.EXPLORE_CONTROLLER_CACHE);
|
||||
const base = environment.XDG_CACHE_HOME || join(environment.HOME || homedir(), ".cache");
|
||||
return join(base, "expo-explore", "controllers");
|
||||
}
|
||||
|
||||
export function controllerDirectory(controller: ControllerName, environment: NodeJS.ProcessEnv = process.env): string {
|
||||
const { name, version } = CONTROLLER_PACKAGES[controller];
|
||||
return join(controllerCacheRoot(environment), `${name.replace("/", "+")}@${version}`);
|
||||
}
|
||||
|
||||
/** The controller's entry file in the cache; it exists once `ensureController` has run. */
|
||||
export function controllerBin(controller: ControllerName, environment: NodeJS.ProcessEnv = process.env): string {
|
||||
return join(controllerDirectory(controller, environment), CONTROLLER_PACKAGES[controller].bin);
|
||||
}
|
||||
|
||||
export function controllerCached(controller: ControllerName, environment: NodeJS.ProcessEnv = process.env): boolean {
|
||||
return existsSync(join(controllerDirectory(controller, environment), COMPLETE));
|
||||
}
|
||||
|
||||
/** The registry tarball for a release, from EXPLORE_NPM_REGISTRY (a mirror) or the public npm registry. */
|
||||
export function controllerTarballUrl(controller: ControllerName, environment: NodeJS.ProcessEnv = process.env): string {
|
||||
const { name, version } = CONTROLLER_PACKAGES[controller];
|
||||
const registry = (environment.EXPLORE_NPM_REGISTRY || "https://registry.npmjs.org").replace(/\/+$/, "");
|
||||
return `${registry}/${name}/-/${name.split("/").pop()}-${version}.tgz`;
|
||||
}
|
||||
|
||||
/**
|
||||
* The command that runs agent-device: a small script in the cache that fetches the pinned release on first use and
|
||||
* then runs it with the same arguments. It names the cache, so a caller that narrows the environment (no HOME) still
|
||||
* finds it. Written synchronously, so capture options can name it before any controller call.
|
||||
*/
|
||||
export function agentDeviceLauncher(environment: NodeJS.ProcessEnv = process.env): string {
|
||||
const root = controllerCacheRoot(environment);
|
||||
const quote = (value: string) => `'${value.replace(/'/g, `'\\''`)}'`;
|
||||
// The registry is part of the command too: controller calls run with a narrowed environment that drops it.
|
||||
const registry = environment.EXPLORE_NPM_REGISTRY ? ` EXPLORE_NPM_REGISTRY=${quote(environment.EXPLORE_NPM_REGISTRY)}` : "";
|
||||
const script = `#!/bin/sh\nEXPLORE_CONTROLLER_CACHE=${quote(root)}${registry} exec ${quote(process.execPath)} ${quote(LAUNCHER)} agent-device "$@"\n`;
|
||||
// One command per pinned release and installation, so two Explore installs on a machine never swap each other's
|
||||
// controller in the middle of a capture.
|
||||
const digest = createHash("sha256").update(script).digest("hex").slice(0, 12);
|
||||
const command = join(root, "bin", `agent-device-${CONTROLLER_PACKAGES["agent-device"].version}-${digest}`);
|
||||
if (existsSync(command) && readFileSync(command, "utf8") === script) return command;
|
||||
mkdirSync(dirname(command), { recursive: true, mode: 0o700 });
|
||||
const temporary = `${command}.${process.pid}.${randomUUID()}`;
|
||||
writeFileSync(temporary, script, { mode: 0o755 });
|
||||
renameSync(temporary, command);
|
||||
return command;
|
||||
}
|
||||
|
||||
/** A fetch killed mid-download (a timed-out controller call) leaves its staging files; clear any over an hour old. */
|
||||
async function removeAbandonedStaging(root: string): Promise<void> {
|
||||
const cutoff = Date.now() - 60 * 60_000;
|
||||
for (const name of await readdir(root).catch(() => [] as string[])) {
|
||||
if (!name.startsWith(".staging-")) continue;
|
||||
const path = join(root, name);
|
||||
const info = await stat(path).catch(() => undefined);
|
||||
if (info && info.mtimeMs < cutoff) await rm(path, { recursive: true, force: true });
|
||||
}
|
||||
}
|
||||
|
||||
function downloadFailed(controller: ControllerName, message: string): CiError {
|
||||
const { name, version } = CONTROLLER_PACKAGES[controller];
|
||||
return new CiError({ code: "CONTROLLER_DOWNLOAD_FAILED", stage: "preflight", message: `${name}@${version} could not be fetched: ${message}`,
|
||||
nextAction: "Check that this machine can reach the npm registry (or set EXPLORE_NPM_REGISTRY to a mirror that serves it), then rerun." });
|
||||
}
|
||||
|
||||
/**
|
||||
* Fetches the pinned controller into the cache once and returns its entry file. The download is hashed while it
|
||||
* streams and must match the pinned integrity before it is unpacked; only regular files and directories inside the
|
||||
* package are written, and the finished directory is renamed into place, so concurrent runs never see half of it.
|
||||
*/
|
||||
export async function ensureController(controller: ControllerName, options: {
|
||||
environment?: NodeJS.ProcessEnv; fetch?: typeof fetch; progress?: (message: string) => void;
|
||||
/** Tests: releases built on the spot instead of the pinned npm ones. */
|
||||
packages?: typeof CONTROLLER_PACKAGES;
|
||||
} = {}): Promise<string> {
|
||||
const environment = options.environment ?? process.env;
|
||||
const pinned = (options.packages ?? CONTROLLER_PACKAGES)[controller];
|
||||
const directory = controllerDirectory(controller, environment);
|
||||
const bin = join(directory, pinned.bin);
|
||||
if (controllerCached(controller, environment)) return bin;
|
||||
const root = controllerCacheRoot(environment);
|
||||
await mkdir(root, { recursive: true, mode: 0o700 });
|
||||
await removeAbandonedStaging(root);
|
||||
const staging = join(root, `.staging-${process.pid}-${randomUUID()}`);
|
||||
const tarball = `${staging}.tgz`;
|
||||
try {
|
||||
options.progress?.(`fetching ${pinned.name}@${pinned.version}`);
|
||||
let response: Response;
|
||||
try { response = await (options.fetch ?? fetch)(controllerTarballUrl(controller, environment)); }
|
||||
catch (error) { throw downloadFailed(controller, error instanceof Error ? error.message : String(error)); }
|
||||
if (!response.ok || !response.body) throw downloadFailed(controller, `the registry answered ${response.status}`);
|
||||
const hash = createHash("sha512");
|
||||
const file = await open(tarball, "wx", 0o600);
|
||||
let bytes = 0;
|
||||
try {
|
||||
for await (const chunk of response.body as unknown as AsyncIterable<Uint8Array>) {
|
||||
bytes += chunk.length;
|
||||
if (bytes > MAX_CONTROLLER_BYTES) throw downloadFailed(controller, "the tarball is larger than expected");
|
||||
hash.update(chunk);
|
||||
await file.write(chunk);
|
||||
}
|
||||
} finally { await file.close(); }
|
||||
const integrity = `sha512-${hash.digest("base64")}`;
|
||||
if (integrity !== pinned.integrity) {
|
||||
throw new CiError({ code: "CONTROLLER_INTEGRITY_MISMATCH", stage: "preflight",
|
||||
message: `${pinned.name}@${pinned.version} from the registry does not match the release Explore pins (${integrity}).`,
|
||||
nextAction: "Do not use this registry for Explore's controllers; unset EXPLORE_NPM_REGISTRY or point it at a faithful mirror." });
|
||||
}
|
||||
await mkdir(staging, { mode: 0o700 });
|
||||
let written = 0;
|
||||
await walkTar(tarball, async (entry, contents) => {
|
||||
const relative = safeRelativePath(entry.name);
|
||||
if (relative === "package" && entry.type === "5") return;
|
||||
if (!relative || !relative.startsWith("package/")) throw downloadFailed(controller, `the tarball has an entry outside the package (${entry.name})`);
|
||||
const target = join(staging, relative.slice("package/".length));
|
||||
if (!target.startsWith(`${staging}${sep}`)) throw downloadFailed(controller, `the tarball has an unsafe entry (${entry.name})`);
|
||||
if (entry.type === "5") { await mkdir(target, { recursive: true }); return; }
|
||||
if (entry.type !== "0") throw downloadFailed(controller, `the tarball has a link or special file (${entry.name})`);
|
||||
written += entry.size;
|
||||
if (written > MAX_CONTROLLER_BYTES) throw downloadFailed(controller, "the package is larger than expected");
|
||||
await mkdir(dirname(target), { recursive: true });
|
||||
await writeFile(target, await contents(), { mode: entry.mode & 0o111 ? 0o755 : 0o644 });
|
||||
});
|
||||
if (!existsSync(join(staging, pinned.bin))) throw downloadFailed(controller, `the package has no ${pinned.bin}`);
|
||||
await chmod(join(staging, pinned.bin), 0o755);
|
||||
await writeFile(join(staging, COMPLETE), `${JSON.stringify({ name: pinned.name, version: pinned.version, integrity })}\n`);
|
||||
try { await rename(staging, directory); }
|
||||
catch (error) {
|
||||
// Another run finished first; its copy is the same verified release.
|
||||
if (!controllerCached(controller, environment)) throw error;
|
||||
}
|
||||
return bin;
|
||||
} finally {
|
||||
await rm(tarball, { force: true });
|
||||
await rm(staging, { recursive: true, force: true });
|
||||
}
|
||||
}
|
||||
File diff suppressed because it is too large.
Load diff
File diff suppressed because it is too large.
Load diff
+2252
File diff suppressed because it is too large.
Load diff
File diff suppressed because it is too large.
Load diff
File diff suppressed because it is too large.
Load diff
File diff suppressed because it is too large.
Load diff
@@ -0,0 +1,5 @@
|
||||
{
|
||||
"description": "Source: ax-service\nMode: flat\nCoordinates are normalized [0,1] fractions of the screen (x, y, width, height), not pixels.\nPass them straight to gesture-tap / gesture-swipe / gesture-pinch, which expect this same space.\nTo tap an element, use its centre: tap_x = frame.x + frame.width / 2, tap_y = frame.y + frame.height / 2.\n\nROOT AXGroup (0.000, 0.000, 1.000, 1.000)\n\n AXGroup \"Open in “euxy”?\" (0.067, 0.382, 0.687, 0.186)\n AXAdjustable \"Vertical scroll bar, 2 pages\" value=\"0%\" (0.682, 0.382, 0.064, 0.068)\n AXAdjustable \"Horizontal scroll bar, 1 page\" value=\"0%\" (0.067, 0.412, 0.687, 0.034)\n AXStaticText \"Open in “euxy”?\" (0.131, 0.414, 0.558, 0.030)\n AXAdjustable \"Vertical scroll bar, 1 page\" value=\"0%\" (0.682, 0.450, 0.064, 0.118)\n AXButton \"Cancel\" (0.101, 0.473, 0.300, 0.071)\n AXButton \"Open\" (0.418, 0.473, 0.300, 0.071)\n AXAdjustable \"Horizontal scroll bar, 1 page\" value=\"0%\" (0.067, 0.519, 0.687, 0.044)",
|
||||
"source": "ax-service",
|
||||
"hint": "This simulator was not booted through argent, so system dialogs and native modals may not appear in this tree; everything else reads normally. If something you expect is missing, boot-device with force=true reboots the simulator with the full accessibility settings"
|
||||
}
|
||||
File diff suppressed because it is too large.
Load diff
+117
@@ -0,0 +1,117 @@
|
||||
{
|
||||
"devices": [
|
||||
{
|
||||
"platform": "ios",
|
||||
"udid": "404F2659-7202-4450-8465-912BD2AB744B",
|
||||
"name": "iPhone 17",
|
||||
"state": "Booted",
|
||||
"runtime": "com.apple.CoreSimulator.SimRuntime.iOS-26-5",
|
||||
"runtimeKind": "mobile"
|
||||
},
|
||||
{
|
||||
"platform": "ios",
|
||||
"udid": "13145DF8-2591-4879-8B4E-0EE52E38B9DC",
|
||||
"name": "Apple TV 4K (3rd generation)",
|
||||
"state": "Shutdown",
|
||||
"runtime": "com.apple.CoreSimulator.SimRuntime.tvOS-26-5",
|
||||
"runtimeKind": "tv"
|
||||
},
|
||||
{
|
||||
"platform": "ios",
|
||||
"udid": "9F874416-F37E-49D4-BE9F-D03A61447F37",
|
||||
"name": "Apple TV 4K (3rd generation) (at 1080p)",
|
||||
"state": "Shutdown",
|
||||
"runtime": "com.apple.CoreSimulator.SimRuntime.tvOS-26-5",
|
||||
"runtimeKind": "tv"
|
||||
},
|
||||
{
|
||||
"platform": "ios",
|
||||
"udid": "AA581E94-E134-4DEC-8D68-A80C02932E86",
|
||||
"name": "Apple TV",
|
||||
"state": "Shutdown",
|
||||
"runtime": "com.apple.CoreSimulator.SimRuntime.tvOS-26-5",
|
||||
"runtimeKind": "tv"
|
||||
},
|
||||
{
|
||||
"platform": "ios",
|
||||
"udid": "7166D6B3-15EA-485E-B233-D4CF5AA1A9E6",
|
||||
"name": "iPhone 17 Pro",
|
||||
"state": "Shutdown",
|
||||
"runtime": "com.apple.CoreSimulator.SimRuntime.iOS-26-5",
|
||||
"runtimeKind": "mobile"
|
||||
},
|
||||
{
|
||||
"platform": "ios",
|
||||
"udid": "65AF775B-D9DC-4293-88B6-7862868B66BC",
|
||||
"name": "iPhone 17 Pro Max",
|
||||
"state": "Shutdown",
|
||||
"runtime": "com.apple.CoreSimulator.SimRuntime.iOS-26-5",
|
||||
"runtimeKind": "mobile"
|
||||
},
|
||||
{
|
||||
"platform": "ios",
|
||||
"udid": "65D86638-6B23-47AB-A60B-B152A3E5FBEC",
|
||||
"name": "iPhone 17e",
|
||||
"state": "Shutdown",
|
||||
"runtime": "com.apple.CoreSimulator.SimRuntime.iOS-26-5",
|
||||
"runtimeKind": "mobile"
|
||||
},
|
||||
{
|
||||
"platform": "ios",
|
||||
"udid": "A690C59A-DE62-467C-9A93-6B9C81BE7859",
|
||||
"name": "iPhone Air",
|
||||
"state": "Shutdown",
|
||||
"runtime": "com.apple.CoreSimulator.SimRuntime.iOS-26-5",
|
||||
"runtimeKind": "mobile"
|
||||
},
|
||||
{
|
||||
"platform": "ios",
|
||||
"udid": "9D7FC73C-7A12-4BCF-83C2-9B52ACF9859D",
|
||||
"name": "iPad Pro 13-inch (M5)",
|
||||
"state": "Shutdown",
|
||||
"runtime": "com.apple.CoreSimulator.SimRuntime.iOS-26-5",
|
||||
"runtimeKind": "mobile"
|
||||
},
|
||||
{
|
||||
"platform": "ios",
|
||||
"udid": "E71C61D3-8D9F-4591-8511-8FE65229C790",
|
||||
"name": "iPad Pro 11-inch (M5)",
|
||||
"state": "Shutdown",
|
||||
"runtime": "com.apple.CoreSimulator.SimRuntime.iOS-26-5",
|
||||
"runtimeKind": "mobile"
|
||||
},
|
||||
{
|
||||
"platform": "ios",
|
||||
"udid": "ED9D983B-1AA4-4648-8EED-CDCD5327B8D6",
|
||||
"name": "iPad mini (A17 Pro)",
|
||||
"state": "Shutdown",
|
||||
"runtime": "com.apple.CoreSimulator.SimRuntime.iOS-26-5",
|
||||
"runtimeKind": "mobile"
|
||||
},
|
||||
{
|
||||
"platform": "ios",
|
||||
"udid": "9C0DF431-D699-4862-8CF3-264CA044F515",
|
||||
"name": "iPad Air 13-inch (M4)",
|
||||
"state": "Shutdown",
|
||||
"runtime": "com.apple.CoreSimulator.SimRuntime.iOS-26-5",
|
||||
"runtimeKind": "mobile"
|
||||
},
|
||||
{
|
||||
"platform": "ios",
|
||||
"udid": "B92DDF42-5EB6-47F1-A1E7-2B3F2CE2CA84",
|
||||
"name": "iPad Air 11-inch (M4)",
|
||||
"state": "Shutdown",
|
||||
"runtime": "com.apple.CoreSimulator.SimRuntime.iOS-26-5",
|
||||
"runtimeKind": "mobile"
|
||||
},
|
||||
{
|
||||
"platform": "ios",
|
||||
"udid": "44804797-154C-40DB-8559-342C3F95477A",
|
||||
"name": "iPad (A16)",
|
||||
"state": "Shutdown",
|
||||
"runtime": "com.apple.CoreSimulator.SimRuntime.iOS-26-5",
|
||||
"runtimeKind": "mobile"
|
||||
}
|
||||
],
|
||||
"avds": []
|
||||
}
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 215 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 167 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 131 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 619 KiB |
@@ -67,6 +67,7 @@ export async function fixture(t, provider, { docsOnly = false, unresolvedParamet
|
||||
await put('eas.json', JSON.stringify({ build: { capture: { ios: { simulator: true }, android: { buildType: 'apk', distribution: 'internal' } } } }));
|
||||
const registration = names => `import {createNativeStackNavigator} from '@react-navigation/native-stack';
|
||||
import {createStaticNavigation} from '@react-navigation/native';
|
||||
|
||||
${names.map(name => `import ${name} from './${name}';`).join('\n')}
|
||||
const Root=createNativeStackNavigator({screens:{${names.map(name => `${name}:{screen:${name},linking:'${name.toLowerCase()}'}`).join(',')}}});
|
||||
const Navigation=createStaticNavigation(Root); export default function App(){return <Navigation/>;}`;
|
||||
@@ -114,7 +115,7 @@ const Navigation=createStaticNavigation(Root); export default function App(){ret
|
||||
const sleep = milliseconds => { clockMs += milliseconds; };
|
||||
const runner = request => {
|
||||
requests.push(request);
|
||||
if (basename(request.command) === 'agent-device') clockMs += 600;
|
||||
if (/^agent-device(-|$)/.test(basename(request.command))) clockMs += 600;
|
||||
if (request.command === 'git') { const result = spawnSync('git', request.args, { cwd: request.cwd, encoding: 'utf8', env: request.environment }); assert.equal(result.status, 0); return { stdout: result.stdout, stderr: result.stderr }; }
|
||||
const command = request.args[0];
|
||||
if (basename(request.command) === 'eas') {
|
||||
@@ -154,7 +155,7 @@ const Navigation=createStaticNavigation(Root); export default function App(){ret
|
||||
mkdirSync(value(request, '--output'));
|
||||
return { stdout: '', stderr: '' };
|
||||
}
|
||||
if (basename(request.command) === 'agent-device') {
|
||||
if (/^agent-device(-|$)/.test(basename(request.command))) {
|
||||
// Base and head capture in parallel, each on its own simulator: a request names its session in the daemon URL,
|
||||
// so the route, appearance and build it sees are that session's, not whichever session started last.
|
||||
const device = sessions.get(/\/([^/]+)$/.exec(request.environment?.AGENT_DEVICE_DAEMON_BASE_URL ?? '')?.[1]) ?? sessions.get(currentSession) ?? idleDevice;
|
||||
|
||||
@@ -0,0 +1,543 @@
|
||||
import assert from "node:assert/strict";
|
||||
import { readFileSync } from "node:fs";
|
||||
import test from "node:test";
|
||||
import { tsImport } from "tsx/esm/api";
|
||||
|
||||
const { PNG } = await import("pngjs");
|
||||
const { ArgentCallError, describedButton, findOpenButton, iosRuntimeVersion, openInAppPromptShowing, parseCommand, runBridgeCommand, snapshotFromTree } = await tsImport("../../src/capture/argent-driver.ts", import.meta.url);
|
||||
|
||||
const fixture = name => JSON.parse(readFileSync(new URL(`../fixtures/argent-0.29/${name}`, import.meta.url), "utf8"));
|
||||
const IOS_HOME = fixture("fixture-ios-ui-tree-home.json");
|
||||
const IOS_RENAME = fixture("fixture-ios-ui-tree-rename.json");
|
||||
const ANDROID_HOME = fixture("fixture-android-ui-tree-home.json");
|
||||
const ANDROID_RENAME = fixture("fixture-android-ui-tree-rename.json");
|
||||
const IOS_DEVICES = fixture("list-devices.out");
|
||||
// iOS 27.1 on iPhone Duo: the link prompt is up, SpringBoard is in front, and alertVisible is false.
|
||||
const DUO_PROMPT = fixture("fixture-ios27-duo-open-prompt-ui-tree.json");
|
||||
const DUO_PROMPT_DESCRIBE = fixture("fixture-ios27-duo-open-prompt-describe.json");
|
||||
const DUO_HOME = fixture("fixture-ios27-duo-home-ui-tree.json");
|
||||
// iPhone Duo opened (the inner display), Edit Lane sheet up: Argent reports the app root as the screen's top-left third.
|
||||
const DUO_OPEN_EDIT_LANE = fixture("fixture-ios27-duo-open-edit-lane-ui-tree.json");
|
||||
const DUO_DEVICES = { devices: [{ platform: "ios", udid: "74195B53-4DBC-4EAA-9991-F98E5BB86BA8", name: "iPhone Duo", state: "Booted", runtime: "com.apple.CoreSimulator.SimRuntime.iOS-27-1", runtimeKind: "mobile" }] };
|
||||
const ANDROID_DEVICES = { devices: [{ platform: "android", serial: "emulator-5554", state: "device", isEmulator: true, model: "sdk_gphone64_x86_64", avdName: "pixel_7", sdkLevel: 36, runtimeKind: "mobile" }], avds: [] };
|
||||
const BUNDLE = "dev.brent.euxy";
|
||||
const UDID = "404F2659-7202-4450-8465-912BD2AB744B";
|
||||
|
||||
/** A scripted tool-server: each tool answers from `answers` (a value, a function of the args, or a queue of either). */
|
||||
function harness(platform, answers, options = {}) {
|
||||
const calls = [];
|
||||
const moves = [];
|
||||
const queues = Object.fromEntries(Object.entries(answers).map(([tool, answer]) => [tool, Array.isArray(answer) ? [...answer] : answer]));
|
||||
const context = {
|
||||
platform, version: "0.29.0", state: options.state ?? { generation: 0 }, ...(options.bundleId ? { bundleId: options.bundleId } : {}),
|
||||
sleep: async () => {},
|
||||
reachable: async () => options.reachable ?? true,
|
||||
moveFile: async (from, to) => { moves.push([from, to]); },
|
||||
call: async (tool, args, callOptions) => {
|
||||
calls.push({ tool, args, ...(callOptions ? { options: callOptions } : {}) });
|
||||
let answer = queues[tool];
|
||||
if (Array.isArray(answer)) answer = answer.length > 1 ? answer.shift() : answer[0];
|
||||
if (answer === undefined) throw new Error(`unexpected tool ${tool}`);
|
||||
const value = typeof answer === "function" ? answer(args) : answer;
|
||||
if (value instanceof Error) throw value;
|
||||
return structuredClone(value);
|
||||
},
|
||||
};
|
||||
return { calls, moves, context, run: argv => runBridgeCommand(argv, context).then(result => ({ ...result, json: result.stdout.trim().startsWith("{") ? JSON.parse(result.stdout) : result.stdout })) };
|
||||
}
|
||||
|
||||
const flags = (platform, extra = []) => [...extra, "--session", "expo-explore-runtime", ...(platform === "ios" ? ["--device", "iPhone 17"] : []), "--platform", platform, "--json"];
|
||||
const flatten = tree => { const out = []; const walk = node => { out.push(node); (node.children ?? []).forEach(walk); }; (tree.roots ?? []).forEach(walk); return out; };
|
||||
|
||||
test("parseCommand separates agent-device's trailing flags from positionals and keeps text after --", () => {
|
||||
assert.deepEqual(parseCommand(["e3", "--session", "s", "--device", "iPhone 17", "--platform", "ios", "--json", "--", "-h", "--json"]),
|
||||
{ positional: ["e3", "-h", "--json"], flags: { session: "s", device: "iPhone 17", platform: "ios", json: true } });
|
||||
});
|
||||
|
||||
test("iosRuntimeVersion reads the OS version from a CoreSimulator runtime id", () => {
|
||||
assert.equal(iosRuntimeVersion("com.apple.CoreSimulator.SimRuntime.iOS-26-5"), "26.5");
|
||||
assert.equal(iosRuntimeVersion("com.apple.CoreSimulator.SimRuntime.iOS-18-0-1"), "18.0.1");
|
||||
assert.equal(iosRuntimeVersion("com.apple.CoreSimulator.SimRuntime.tvOS-26-5"), undefined);
|
||||
});
|
||||
|
||||
test("--version answers with the pinned Argent version without calling Argent", async () => {
|
||||
const { run, calls } = harness("ios", {});
|
||||
assert.equal((await run(["--version"])).stdout, "0.29.0\n");
|
||||
assert.equal(calls.length, 0);
|
||||
});
|
||||
|
||||
test("an iOS snapshot is agent-device's shape: points, the app root, the observer, and no duplicate nodes", () => {
|
||||
const { nodes, refs, screen } = snapshotFromTree(IOS_HOME, "ios", 1, BUNDLE);
|
||||
assert.deepEqual(screen, { width: 402, height: 874 });
|
||||
assert.equal(nodes[0].type, "Application");
|
||||
assert.deepEqual(nodes[0].rect, { x: 0, y: 0, width: 402, height: 874 });
|
||||
assert.equal(nodes[0].hittable, false);
|
||||
for (const [index, node] of nodes.entries()) {
|
||||
assert.equal(node.index, index);
|
||||
assert.equal(node.ref, `e${index + 1}`);
|
||||
assert.ok(refs[node.ref]);
|
||||
if (index > 0) assert.ok(node.parentIndex < index, "a parent comes before its children");
|
||||
assert.ok(node.rect.x < 402 && node.rect.y < 874 && node.rect.x + node.rect.width > 0 && node.rect.y + node.rect.height > 0, "only on-screen nodes");
|
||||
}
|
||||
const observer = nodes.find(node => node.identifier === "expo-explore-observer");
|
||||
assert.ok(observer, "the capture observer is in the tree");
|
||||
assert.equal(JSON.parse(observer.label).pathname, "/");
|
||||
const keys = nodes.map(node => JSON.stringify([node.type, node.label, node.identifier, node.value, Object.values(node.rect).map(Math.round)]));
|
||||
assert.equal(new Set(keys).size, keys.length, "iOS AX duplicates appear once");
|
||||
assert.ok(nodes.length < flatten(IOS_HOME).length);
|
||||
assert.ok(nodes.some(node => node.type === "Button" && node.identifier === "lane-row-title-0"));
|
||||
});
|
||||
|
||||
test("an Android snapshot keeps pixels, drops the system UI root, and names widgets as agent-device does", () => {
|
||||
const { nodes, screen } = snapshotFromTree(ANDROID_HOME, "android", 1, BUNDLE);
|
||||
assert.deepEqual(screen, { width: 720, height: 1600 });
|
||||
assert.equal(nodes[0].type, "Application");
|
||||
assert.deepEqual(nodes[0].rect, { x: 0, y: 0, width: 720, height: 1600 });
|
||||
assert.ok(!nodes.some(node => /^android\.widget\./.test(node.type)), "widget classes are simplified");
|
||||
assert.ok(nodes.some(node => node.identifier === "expo-explore-observer"));
|
||||
const systemUi = flatten({ roots: ANDROID_HOME.roots.filter(root => root.bundleId === "com.android.systemui") })
|
||||
.map(node => node.label ?? node.contentDescription).filter(Boolean);
|
||||
for (const label of systemUi) assert.ok(!nodes.some(node => node.label === label && node.depth === 0), `system UI root is left out (${label})`);
|
||||
assert.ok(nodes.filter(node => node.depth === 0).length === 1);
|
||||
});
|
||||
|
||||
test("snapshot pins refs to its generation and reports the foreground app; press resolves a ref to the element's centre", async () => {
|
||||
const { run, calls, context } = harness("ios", { "list-devices": IOS_DEVICES, "ui-tree": IOS_HOME, "gesture-tap": {} });
|
||||
const snapshot = await run(["snapshot", ...flags("ios", ["--force-full", "--level", "full"])]);
|
||||
assert.equal(snapshot.exitCode, 0);
|
||||
assert.equal(snapshot.json.data.refsGeneration, 1);
|
||||
assert.equal(snapshot.json.data.appBundleId, BUNDLE);
|
||||
assert.equal(snapshot.json.data.truncated, false);
|
||||
assert.equal(context.state.udid, UDID);
|
||||
assert.equal(context.state.model, "iPhone 17");
|
||||
assert.equal(context.state.osVersion, "26.5");
|
||||
const target = snapshot.json.data.nodes.find(node => node.identifier === "lane-row-title-0");
|
||||
const pressed = await run(["press", `@${target.ref}`, ...flags("ios")]);
|
||||
assert.equal(pressed.exitCode, 0);
|
||||
const tap = calls.at(-1);
|
||||
assert.equal(tap.tool, "gesture-tap");
|
||||
assert.equal(tap.args.udid, UDID);
|
||||
assert.ok(Math.abs(tap.args.x - (target.rect.x + target.rect.width / 2) / 402) < 1e-9);
|
||||
assert.ok(Math.abs(tap.args.y - (target.rect.y + target.rect.height / 2) / 874) < 1e-9);
|
||||
|
||||
const stale = await run(["press", `${target.ref}~s0`, ...flags("ios")]);
|
||||
assert.equal(stale.exitCode, 1);
|
||||
assert.match(stale.json.error.message, /stale/);
|
||||
});
|
||||
|
||||
test("press with coordinates normalizes Android pixels", async () => {
|
||||
const { run, calls } = harness("android", { "list-devices": ANDROID_DEVICES, "ui-tree": ANDROID_HOME, "gesture-tap": {} });
|
||||
assert.equal((await run(["press", "360", "400", ...flags("android")])).exitCode, 0);
|
||||
assert.deepEqual(calls.at(-1), { tool: "gesture-tap", args: { udid: "emulator-5554", x: 0.5, y: 0.25 } });
|
||||
});
|
||||
|
||||
test("open relaunches the app until its tree is readable and answers with agent-device's open envelope", async () => {
|
||||
const empty = { ...IOS_HOME, roots: [{ type: "Other", frame: { x: 0, y: 0, width: 1, height: 1 } }] };
|
||||
const { run, calls } = harness("ios", { "list-devices": IOS_DEVICES, "restart-app": {}, "ui-tree": [empty, empty, IOS_HOME] });
|
||||
const opened = await run(["open", BUNDLE, ...flags("ios", ["--level", "full"])]);
|
||||
assert.equal(opened.exitCode, 0);
|
||||
assert.deepEqual(opened.json.data.device, { platform: "ios", target: "mobile", name: "iPhone 17", id: UDID, osVersion: "26.5" });
|
||||
assert.equal(opened.json.data.appBundleId, BUNDLE);
|
||||
assert.equal(opened.json.data.session, "expo-explore-runtime");
|
||||
assert.deepEqual(opened.json.data.identifiers, { session: "expo-explore-runtime", appBundleId: BUNDLE, deviceName: "iPhone 17", deviceId: UDID });
|
||||
assert.deepEqual(calls.filter(call => call.tool === "restart-app").map(call => call.args), [{ udid: UDID, bundleId: BUNDLE }]);
|
||||
});
|
||||
|
||||
test("open fails clearly when the app never shows a tree", async () => {
|
||||
const empty = { ...IOS_HOME, roots: [] };
|
||||
const { run, calls } = harness("ios", { "list-devices": IOS_DEVICES, "restart-app": {}, "ui-tree": empty });
|
||||
const opened = await run(["open", BUNDLE, ...flags("ios")]);
|
||||
assert.equal(opened.exitCode, 1);
|
||||
assert.equal(opened.json.error.code, "APP_NOT_READY");
|
||||
assert.equal(calls.filter(call => call.tool === "restart-app").length, 2);
|
||||
});
|
||||
|
||||
test("a session with no single booted device is refused", async () => {
|
||||
const none = { devices: IOS_DEVICES.devices.map(device => ({ ...device, state: "Shutdown" })) };
|
||||
const { run } = harness("ios", { "list-devices": none });
|
||||
const result = await run(["snapshot", ...flags("ios")]);
|
||||
assert.equal(result.json.error.code, "DEVICE_UNAVAILABLE");
|
||||
});
|
||||
|
||||
test("the first iOS deep link accepts the Open prompt once; later links open directly", async () => {
|
||||
// iOS 26.5 flags the prompt as an alert; its text is what identifies it as the link prompt.
|
||||
const prompt = { ...IOS_HOME, alertVisible: true, foregroundApp: "com.apple.springboard",
|
||||
roots: [...IOS_HOME.roots, { type: "Alert", label: "Open in “euxy”?", frame: { x: 0.1, y: 0.4, width: 0.8, height: 0.2 }, children: [] }] };
|
||||
const { run, calls, context } = harness("ios", { "list-devices": IOS_DEVICES, "open-url": {}, "gesture-tap": {}, "ui-tree": [prompt, IOS_HOME] });
|
||||
const first = await run(["open", BUNDLE, "euxy://settings", ...flags("ios")]);
|
||||
assert.equal(first.exitCode, 0);
|
||||
const tap = calls.find(call => call.tool === "gesture-tap");
|
||||
assert.ok(Math.abs(tap.args.x - (0.5 + 74 / 402)) < 1e-9 && Math.abs(tap.args.y - (0.5 + 37 / 874)) < 1e-9);
|
||||
assert.equal(context.state.deepLinkPromptAccepted, true);
|
||||
const before = calls.length;
|
||||
assert.equal((await run(["open", "euxy://patterns", ...flags("ios")])).exitCode, 0);
|
||||
assert.deepEqual(calls.slice(before).map(call => call.tool), ["open-url"]);
|
||||
});
|
||||
|
||||
test("iOS fill taps the field, erases its text with backspaces, types, and checks the result", async () => {
|
||||
const field = flatten(IOS_RENAME).find(node => node.type === "TextField" && node.frame);
|
||||
assert.ok(field, "the rename fixture has a text field");
|
||||
const typed = structuredClone(IOS_RENAME);
|
||||
flatten(typed).find(node => node.type === "TextField" && node.frame).value = "Groove";
|
||||
const { run, calls } = harness("ios", { "list-devices": IOS_DEVICES, "ui-tree": [IOS_RENAME, typed], "gesture-tap": {}, "run-sequence": {}, keyboard: {} });
|
||||
const snapshot = await run(["snapshot", ...flags("ios")]);
|
||||
const node = snapshot.json.data.nodes.find(item => item.type === "TextField");
|
||||
const filled = await run(["fill", node.ref, ...flags("ios"), "--", "Groove"]);
|
||||
assert.equal(filled.exitCode, 0, filled.stdout);
|
||||
const tools = calls.slice(2).map(call => call.tool);
|
||||
assert.equal(tools[0], "gesture-tap");
|
||||
const erase = (field.value ?? "").length;
|
||||
if (erase) {
|
||||
const sequence = calls.find(call => call.tool === "run-sequence");
|
||||
assert.equal(sequence.args.steps.length, erase);
|
||||
assert.deepEqual(sequence.args.steps[0], { tool: "keyboard", args: { udid: UDID, key: "backspace" } });
|
||||
}
|
||||
assert.deepEqual(calls.find(call => call.tool === "keyboard").args, { udid: UDID, text: "Groove" });
|
||||
assert.ok(!calls.some(call => call.tool === "fill"), "Argent's iOS fill is not used");
|
||||
});
|
||||
|
||||
test("Android fill uses Argent's fill and requires it to verify the text", async () => {
|
||||
const { run, calls } = harness("android", { "list-devices": ANDROID_DEVICES, "ui-tree": ANDROID_RENAME, "gesture-tap": {}, fill: [{ verified: true }, { verified: false }] });
|
||||
const snapshot = await run(["snapshot", ...flags("android")]);
|
||||
const node = snapshot.json.data.nodes.find(item => item.type === "TextField");
|
||||
assert.ok(node, "the rename fixture has an EditText");
|
||||
assert.equal((await run(["fill", node.ref, ...flags("android"), "--", "Groove"])).exitCode, 0);
|
||||
assert.deepEqual(calls.find(call => call.tool === "fill").args, { udid: "emulator-5554", text: "Groove" });
|
||||
const unverified = await run(["fill", node.ref, ...flags("android"), "--", "Groove"]);
|
||||
assert.equal(unverified.exitCode, 1);
|
||||
});
|
||||
|
||||
test("text with a {{secret:…}} placeholder never reaches Argent", async () => {
|
||||
const { run, calls } = harness("ios", { "list-devices": IOS_DEVICES, keyboard: {} });
|
||||
const typed = await run(["type", ...flags("ios"), "--", "{{secret:PASSWORD}}"]);
|
||||
assert.equal(typed.json.error.code, "INVALID_ARGS");
|
||||
assert.ok(!calls.some(call => call.tool === "keyboard"));
|
||||
});
|
||||
|
||||
test("keyboard dismiss matches agent-device: Android presses back; iOS taps a dismiss key or reports it could not", async () => {
|
||||
const android = harness("android", { "list-devices": ANDROID_DEVICES, "ui-tree": [{ ...ANDROID_RENAME, keyboardVisible: true }, { ...ANDROID_RENAME, keyboardVisible: false }], button: {} });
|
||||
const dismissed = await android.run(["keyboard", "dismiss", ...flags("android")]);
|
||||
assert.deepEqual(dismissed.json.data, { platform: "android", action: "dismiss", wasVisible: true, dismissed: true, visible: false });
|
||||
assert.deepEqual(android.calls.find(call => call.tool === "button").args, { udid: "emulator-5554", button: "back" });
|
||||
|
||||
// agent-device fails with this message when the keyboard has no dismiss key, and callers fall back to the return key.
|
||||
const noKey = harness("ios", { "list-devices": IOS_DEVICES, "ui-tree": { ...IOS_HOME, keyboardVisible: true } });
|
||||
const failed = await noKey.run(["keyboard", "dismiss", ...flags("ios")]);
|
||||
assert.equal(failed.exitCode, 1);
|
||||
assert.match(failed.json.error.message, /^Unable to dismiss the iOS keyboard/);
|
||||
|
||||
const hidden = harness("ios", { "list-devices": IOS_DEVICES, "ui-tree": IOS_HOME });
|
||||
assert.equal((await hidden.run(["keyboard", "dismiss", ...flags("ios")])).json.data.wasVisible, false);
|
||||
});
|
||||
|
||||
test("iOS back with no navigation bar back control fails with agent-device's message", async () => {
|
||||
const { run } = harness("ios", { "list-devices": IOS_DEVICES, "ui-tree": IOS_HOME });
|
||||
const back = await run(["back", ...flags("ios")]);
|
||||
assert.equal(back.exitCode, 1);
|
||||
assert.equal(back.json.error.message, "in-app back control is not available");
|
||||
});
|
||||
|
||||
test("alerts read and answer in each platform's agent-device shape", async () => {
|
||||
const noAlert = harness("ios", { "list-devices": IOS_DEVICES, "ui-tree": IOS_HOME });
|
||||
assert.equal((await noAlert.run(["alert", "get", ...flags("ios")])).json.error.message, "alert not found");
|
||||
const androidNone = harness("android", { "list-devices": ANDROID_DEVICES, "ui-tree": ANDROID_HOME });
|
||||
assert.deepEqual((await androidNone.run(["alert", "get", ...flags("android")])).json.data, { platform: "android", alert: null });
|
||||
|
||||
const alertTree = { ...IOS_HOME, alertVisible: true, roots: [{ type: "Alert", label: "Allow?", frame: { x: 0.1, y: 0.4, width: 0.8, height: 0.2 }, children: [
|
||||
{ type: "StaticText", label: "Allow notifications?", frame: { x: 0.1, y: 0.4, width: 0.8, height: 0.05 } },
|
||||
{ type: "Button", label: "Don’t Allow", frame: { x: 0.1, y: 0.55, width: 0.4, height: 0.05 } },
|
||||
{ type: "Button", label: "Allow", frame: { x: 0.5, y: 0.55, width: 0.4, height: 0.05 } }] }] };
|
||||
const ios = harness("ios", { "list-devices": IOS_DEVICES, "ui-tree": [alertTree, alertTree, IOS_HOME], "gesture-tap": {} });
|
||||
assert.deepEqual((await ios.run(["alert", "get", ...flags("ios")])).json.data, { message: "Allow notifications?", items: ["Don’t Allow", "Allow"] });
|
||||
const accepted = await ios.run(["alert", "accept", ...flags("ios")]);
|
||||
assert.deepEqual(accepted.json.data, { action: "accept", button: "Allow" });
|
||||
const tap = ios.calls.find(call => call.tool === "gesture-tap");
|
||||
assert.ok(Math.abs(tap.args.x - 0.7) < 1e-9 && Math.abs(tap.args.y - 0.575) < 1e-9);
|
||||
});
|
||||
|
||||
test("screenshots download at full resolution to the requested path", async () => {
|
||||
const { run, calls } = harness("ios", { "list-devices": IOS_DEVICES, screenshot: {} });
|
||||
assert.deepEqual((await run(["screenshot", "/tmp/out.png", ...flags("ios")])).json.data, { path: "/tmp/out.png" });
|
||||
assert.deepEqual(calls.at(-1), { tool: "screenshot", args: { udid: UDID, scale: 1 }, options: { out: "/tmp/out.png" } });
|
||||
});
|
||||
|
||||
test("a recording is moved from where the Argent client downloaded it to the path Explore asked for", async () => {
|
||||
const { run, moves, context } = harness("android", { "list-devices": ANDROID_DEVICES, "screen-recording-start": {}, "screen-recording-stop": { video: "/home/.argent/recordings/r.mp4", durationMs: 4200 } });
|
||||
assert.equal((await run(["record", "start", "/work/launch.mp4", ...flags("android")])).exitCode, 0);
|
||||
assert.equal(context.state.recording, "/work/launch.mp4");
|
||||
const stopped = await run(["record", "stop", ...flags("android")]);
|
||||
assert.deepEqual(stopped.json.data, { outPath: "/work/launch.mp4", durationMs: 4200 });
|
||||
assert.deepEqual(moves, [["/home/.argent/recordings/r.mp4", "/work/launch.mp4"]]);
|
||||
assert.equal(context.state.recording, undefined);
|
||||
});
|
||||
|
||||
test("install reinstalls the archive under the bundle id the caller names", async () => {
|
||||
const { run, calls } = harness("ios", { "list-devices": IOS_DEVICES, "reinstall-app": {} }, { bundleId: BUNDLE });
|
||||
assert.deepEqual((await run(["install", "/work/bundle/euxy.app", ...flags("ios")])).json.data, { installed: true, appBundleId: BUNDLE });
|
||||
assert.deepEqual(calls.at(-1).args, { udid: UDID, bundleId: BUNDLE, appPath: "/work/bundle/euxy.app" });
|
||||
const missing = harness("ios", { "list-devices": IOS_DEVICES, "reinstall-app": {} });
|
||||
assert.equal((await missing.run(["install", "/work/a.app", ...flags("ios")])).json.error.code, "INVALID_ARGS");
|
||||
});
|
||||
|
||||
test("appearance and logs are reported as unsupported, not silently ignored", async () => {
|
||||
const { run } = harness("ios", {});
|
||||
assert.equal((await run(["settings", "appearance", "dark", ...flags("ios")])).json.error.code, "CONTROLLER_UNSUPPORTED");
|
||||
assert.equal((await run(["logs", "path", ...flags("ios")])).json.error.code, "CONTROLLER_UNSUPPORTED");
|
||||
});
|
||||
|
||||
test("a tool-server that is still starting is waited for before the action is sent", async () => {
|
||||
const { run, calls, context } = harness("ios", { "list-devices": IOS_DEVICES, "ui-tree": IOS_HOME, "gesture-tap": {} });
|
||||
const answers = [false, false, false, true];
|
||||
context.reachable = async () => answers.shift() ?? true;
|
||||
assert.equal((await run(["press", "10", "10", ...flags("ios")])).exitCode, 0);
|
||||
assert.equal(calls.filter(call => call.tool === "gesture-tap").length, 1);
|
||||
});
|
||||
|
||||
test("an unreachable tool-server before a UI action is the retryable 'Remote daemon is unavailable'", async () => {
|
||||
const { run, calls } = harness("ios", { "list-devices": IOS_DEVICES, "ui-tree": IOS_HOME, "gesture-tap": {} }, { reachable: false });
|
||||
const pressed = await run(["press", "10", "10", ...flags("ios")]);
|
||||
assert.deepEqual(pressed.json.error, { code: "COMMAND_FAILED", message: "Remote daemon is unavailable" });
|
||||
assert.ok(!calls.some(call => call.tool === "gesture-tap"));
|
||||
});
|
||||
|
||||
test("a UI action whose answer is lost is reported once and never retried", async () => {
|
||||
const { run, calls } = harness("ios", { "list-devices": IOS_DEVICES, "ui-tree": IOS_HOME, "gesture-tap": new ArgentCallError("argent run gesture-tap failed: socket hang up", true) });
|
||||
const pressed = await run(["press", "10", "10", ...flags("ios")]);
|
||||
assert.equal(pressed.json.error.code, "ARGENT_TOOL_FAILED");
|
||||
assert.notEqual(pressed.json.error.message, "Remote daemon is unavailable");
|
||||
assert.equal(calls.filter(call => call.tool === "gesture-tap").length, 1);
|
||||
});
|
||||
|
||||
test("reads are retried after a transport failure", async () => {
|
||||
const { run, calls } = harness("ios", { "list-devices": IOS_DEVICES, "ui-tree": [new ArgentCallError("timeout", true), IOS_HOME] });
|
||||
assert.equal((await run(["snapshot", ...flags("ios")])).exitCode, 0);
|
||||
assert.equal(calls.filter(call => call.tool === "ui-tree").length, 2);
|
||||
});
|
||||
|
||||
test("wait stable maps to await-screen-idle", async () => {
|
||||
const { run, calls } = harness("android", { "list-devices": ANDROID_DEVICES, "await-screen-idle": { settled: true } });
|
||||
assert.deepEqual((await run(["wait", "stable", "700", "5000", ...flags("android")])).json.data, { stable: true });
|
||||
assert.deepEqual(calls.at(-1).args, { udid: "emulator-5554", minStableMs: 700, timeoutMs: 5000 });
|
||||
});
|
||||
|
||||
test("iOS 27.1's link prompt is recognized by its text when Argent does not flag it as an alert", () => {
|
||||
assert.equal(DUO_PROMPT.alertVisible, false);
|
||||
assert.equal(openInAppPromptShowing(DUO_PROMPT), true);
|
||||
assert.equal(openInAppPromptShowing(DUO_HOME), false);
|
||||
assert.equal(openInAppPromptShowing(IOS_HOME), false);
|
||||
});
|
||||
|
||||
test("describe locates the prompt's Open button where it is on screen", () => {
|
||||
assert.deepEqual(describedButton(DUO_PROMPT_DESCRIBE.description, "Open"), { x: 0.418, y: 0.473, width: 0.3, height: 0.071 });
|
||||
assert.equal(describedButton(DUO_PROMPT_DESCRIBE.description, "Allow"), undefined);
|
||||
assert.equal(describedButton(undefined, "Open"), undefined);
|
||||
});
|
||||
|
||||
test("on iPhone Duo the first link taps Open where describe puts it, not at iPhone 17's offset", async () => {
|
||||
const { run, calls, context } = harness("ios", { "list-devices": DUO_DEVICES, "open-url": {}, "gesture-tap": {}, describe: DUO_PROMPT_DESCRIBE, "ui-tree": [DUO_PROMPT, DUO_HOME] });
|
||||
const opened = await run(["open", "dev.brent.euxy", "euxy://", ...flags("ios")]);
|
||||
assert.equal(opened.exitCode, 0, opened.stdout);
|
||||
const tap = calls.find(call => call.tool === "gesture-tap");
|
||||
assert.ok(Math.abs(tap.args.x - (0.418 + 0.15)) < 1e-9 && Math.abs(tap.args.y - (0.473 + 0.0355)) < 1e-9, JSON.stringify(tap.args));
|
||||
assert.equal(context.state.deepLinkPromptAccepted, true);
|
||||
});
|
||||
|
||||
test("a snapshot taken while iOS 27.1's link prompt is up reports it as an alert", async () => {
|
||||
const { run } = harness("ios", { "list-devices": DUO_DEVICES, "ui-tree": DUO_PROMPT });
|
||||
const snapshot = await run(["snapshot", ...flags("ios")]);
|
||||
assert.ok(snapshot.json.data.nodes.some(node => node.type === "Alert"));
|
||||
});
|
||||
|
||||
test("a tool-server that lists no devices on its first call is asked again", async () => {
|
||||
const { run, calls, context } = harness("ios", { "list-devices": [{ devices: [], avds: [] }, DUO_DEVICES], "ui-tree": DUO_HOME });
|
||||
assert.equal((await run(["snapshot", ...flags("ios")])).exitCode, 0);
|
||||
assert.equal(calls.filter(call => call.tool === "list-devices").length, 2);
|
||||
assert.equal(context.state.model, "iPhone Duo");
|
||||
assert.equal(context.state.osVersion, "27.1");
|
||||
});
|
||||
|
||||
test("alert get and accept read iOS 27.1's link prompt and press Open where describe puts it", async () => {
|
||||
const { run, calls } = harness("ios", { "list-devices": DUO_DEVICES, "gesture-tap": {}, describe: DUO_PROMPT_DESCRIBE, "ui-tree": [DUO_PROMPT, DUO_PROMPT, DUO_HOME] });
|
||||
const read = await run(["alert", "get", ...flags("ios")]);
|
||||
assert.deepEqual(read.json.data, { message: "Open in “euxy”?", items: ["Cancel", "Open"] });
|
||||
const accepted = await run(["alert", "accept", ...flags("ios")]);
|
||||
assert.deepEqual(accepted.json.data, { action: "accept", button: "Open" });
|
||||
const tap = calls.find(call => call.tool === "gesture-tap");
|
||||
assert.ok(Math.abs(tap.args.x - 0.568) < 1e-9 && Math.abs(tap.args.y - 0.5085) < 1e-9, JSON.stringify(tap.args));
|
||||
});
|
||||
|
||||
const image = name => PNG.sync.read(readFileSync(new URL(`../fixtures/argent-0.29/${name}`, import.meta.url)));
|
||||
const near = (actual, expected, tolerance = 0.02) => Math.abs(actual - expected) <= tolerance;
|
||||
|
||||
test("the link prompt's Open button is found in iOS 26 and iOS 27.1 screenshots", () => {
|
||||
// iPhone Duo: describe puts Open at (0.418, 0.473, 0.3 × 0.071).
|
||||
const duo = findOpenButton(image("screenshot-ios27-duo-open-prompt.png"));
|
||||
assert.ok(duo && near(duo.x, 0.568) && near(duo.y, 0.5085), JSON.stringify(duo));
|
||||
const iphone17 = findOpenButton(image("screenshot-ios26-iphone17-open-prompt.png"));
|
||||
assert.ok(iphone17 && iphone17.x > 0.5 && iphone17.x < 0.85 && iphone17.y > 0.48 && iphone17.y < 0.6, JSON.stringify(iphone17));
|
||||
});
|
||||
|
||||
test("no Open button is found without the prompt, even with a blue key on screen", () => {
|
||||
assert.equal(findOpenButton(image("screenshot-ios27-duo-no-prompt-small.png")), undefined);
|
||||
assert.equal(findOpenButton(image("screenshot-ios26-keyboard.png")), undefined);
|
||||
});
|
||||
|
||||
test("when Argent reads nothing while the prompt is up, Open is tapped from a screenshot", async () => {
|
||||
const blind = { schemaVersion: 1, source: "ax-service", screen: { width: 466, height: 678 }, roots: [{ role: "AXGroup", children: [] }], truncated: false, alertVisible: false };
|
||||
const frames = [image("screenshot-ios27-duo-open-prompt.png"), image("screenshot-ios27-duo-no-prompt-small.png")];
|
||||
const { run, calls, context } = harness("ios", { "list-devices": DUO_DEVICES, "open-url": {}, "gesture-tap": {}, screenshot: {}, "ui-tree": blind });
|
||||
context.scratchImage = { path: "/work/argent-scratch.png", read: async () => frames.shift() };
|
||||
const opened = await run(["open", "dev.brent.euxy", "euxy://", ...flags("ios")]);
|
||||
assert.equal(opened.exitCode, 0, opened.stdout);
|
||||
const tap = calls.find(call => call.tool === "gesture-tap");
|
||||
assert.ok(near(tap.args.x, 0.568) && near(tap.args.y, 0.5085), JSON.stringify(tap.args));
|
||||
assert.deepEqual(calls.filter(call => call.tool === "screenshot").map(call => call.options), [{ out: "/work/argent-scratch.png" }, { out: "/work/argent-scratch.png" }]);
|
||||
assert.equal(context.state.deepLinkPromptAccepted, true);
|
||||
});
|
||||
|
||||
test("fold moves a foldable to a pose and forgets the old panel's geometry", async () => {
|
||||
// Argent's fold answers with the panel it lit, in pixels; the inner panel is 2007 × 2853 (669 × 951 points).
|
||||
const { run, calls, context } = harness("ios", { "list-devices": DUO_DEVICES, "ui-tree": [DUO_HOME, DUO_OPEN_EDIT_LANE],
|
||||
fold: { activeScreen: 3, screen: { id: 3, panel: "inner panel", width: 2007, height: 2853 }, posture: "open", hingeAngle: 180 } });
|
||||
await run(["snapshot", ...flags("ios")]);
|
||||
const generation = context.state.generation;
|
||||
const reads = calls.filter(call => call.tool === "ui-tree").length;
|
||||
const folded = await run(["fold", "open", ...flags("ios")]);
|
||||
assert.deepEqual(folded.json.data, { action: "fold", pose: "open" });
|
||||
const fold = calls.findIndex(call => call.tool === "fold");
|
||||
assert.equal(calls.slice(0, fold).filter(call => call.tool === "ui-tree").length, reads, "nothing is read between the command and the fold");
|
||||
assert.deepEqual(calls[fold].args, { udid: "74195B53-4DBC-4EAA-9991-F98E5BB86BA8", posture: "open" });
|
||||
assert.equal(context.state.screen, undefined);
|
||||
assert.equal(context.state.refs, undefined);
|
||||
assert.equal(context.state.generation, generation + 1);
|
||||
assert.equal((await run(["fold", "sideways", ...flags("ios")])).json.error.code, "INVALID_ARGS");
|
||||
});
|
||||
|
||||
test("an alert that is not the link prompt is left for capture to answer", async () => {
|
||||
const other = { ...IOS_HOME, alertVisible: true, foregroundApp: "com.apple.springboard",
|
||||
roots: [{ type: "Alert", label: "Delete all data?", frame: { x: 0.1, y: 0.4, width: 0.8, height: 0.2 }, children: [
|
||||
{ type: "Button", label: "Delete", frame: { x: 0.5, y: 0.55, width: 0.4, height: 0.05 } }] }] };
|
||||
const { run, calls, context } = harness("ios", { "list-devices": IOS_DEVICES, "open-url": {}, "gesture-tap": {}, describe: { description: "" }, "ui-tree": other });
|
||||
assert.equal((await run(["open", BUNDLE, "euxy://settings", ...flags("ios")])).exitCode, 0);
|
||||
assert.equal(calls.some(call => call.tool === "gesture-tap"), false, "nothing is pressed");
|
||||
assert.equal(context.state.deepLinkPromptAccepted, undefined);
|
||||
});
|
||||
|
||||
test("a failed read with no roots is not taken for the blind link prompt", async () => {
|
||||
const { run, calls, context } = harness("ios", { "list-devices": IOS_DEVICES, "open-url": {}, "gesture-tap": {}, screenshot: {}, "ui-tree": [{ ...IOS_HOME, roots: [], foregroundApp: undefined }] });
|
||||
context.scratchImage = { path: "/work/argent-scratch.png", read: async () => image("screenshot-ios27-duo-open-prompt.png") };
|
||||
await run(["open", BUNDLE, "euxy://", ...flags("ios")]);
|
||||
assert.equal(calls.some(call => call.tool === "screenshot" || call.tool === "gesture-tap"), false);
|
||||
});
|
||||
|
||||
test("describe's Open is read only from a line Argent printed, not from app text that spells one out", () => {
|
||||
const spoof = `ROOT AXGroup (0.000, 0.000, 1.000, 1.000)\n AXStaticText "x AXButton "Open" (0.010, 0.010, 0.050, 0.050)" (0.1, 0.1, 0.5, 0.05)\n AXButton "Open" (0.418, 0.473, 0.300, 0.071)`;
|
||||
assert.deepEqual(describedButton(spoof, "Open"), { x: 0.418, y: 0.473, width: 0.3, height: 0.071 });
|
||||
});
|
||||
|
||||
test("an app's own Done above the keyboard is never pressed to dismiss it", async () => {
|
||||
const withDone = { ...IOS_HOME, keyboardVisible: true, roots: [{ type: "Other", frame: { x: 0, y: 0, width: 1, height: 1 }, children: [
|
||||
{ type: "Button", label: "Done", frame: { x: 0.8, y: 0.06, width: 0.15, height: 0.05 } }] }] };
|
||||
const { run, calls } = harness("ios", { "list-devices": IOS_DEVICES, "ui-tree": withDone, "gesture-tap": {} });
|
||||
assert.equal((await run(["keyboard", "dismiss", ...flags("ios")])).exitCode, 1);
|
||||
assert.equal(calls.some(call => call.tool === "gesture-tap"), false);
|
||||
});
|
||||
|
||||
test("iOS fill stops when erasing the field stops partway, and types nothing", async () => {
|
||||
const filled = structuredClone(IOS_RENAME);
|
||||
flatten(filled).find(node => node.type === "TextField" && node.frame).value = "Old";
|
||||
const { run, calls } = harness("ios", { "list-devices": IOS_DEVICES, "ui-tree": filled, "gesture-tap": {}, "run-sequence": { completed: 1, total: 3, steps: [] }, keyboard: {} });
|
||||
const snapshot = await run(["snapshot", ...flags("ios")]);
|
||||
const field = snapshot.json.data.nodes.find(node => node.type === "TextField");
|
||||
const result = await run(["fill", field.ref, ...flags("ios"), "--", "New"]);
|
||||
assert.equal(result.exitCode, 1);
|
||||
assert.match(result.json.error.message, /after 1 of 3 keys/);
|
||||
assert.equal(calls.some(call => call.tool === "keyboard"), false);
|
||||
});
|
||||
|
||||
test("a truncated tree is reported as truncated", async () => {
|
||||
const { run } = harness("ios", { "list-devices": IOS_DEVICES, "ui-tree": { ...IOS_HOME, truncated: true } });
|
||||
assert.equal((await run(["snapshot", ...flags("ios")])).json.data.truncated, true);
|
||||
});
|
||||
|
||||
test("Android disabled controls are reported disabled (the recorded rename screen has four)", () => {
|
||||
const { nodes } = snapshotFromTree(ANDROID_RENAME, "android", 1, BUNDLE);
|
||||
const rename = nodes.find(node => node.label === "Rename" && node.type === "Button");
|
||||
assert.ok(rename, "the rename fixture has its Rename button");
|
||||
assert.equal(rename.enabled, false);
|
||||
assert.equal(rename.hittable, false);
|
||||
});
|
||||
|
||||
test("an Android permission dialog from another package stays in the snapshot as an alert", async () => {
|
||||
const dialog = { ...ANDROID_HOME, roots: [...ANDROID_HOME.roots, { type: "android.widget.FrameLayout", bundleId: "com.google.android.permissioncontroller",
|
||||
frame: { x: 0.1, y: 0.35, width: 0.8, height: 0.3 }, children: [
|
||||
{ type: "android.widget.TextView", label: "Allow euxy to send you notifications?", frame: { x: 0.15, y: 0.4, width: 0.7, height: 0.05 } },
|
||||
{ type: "android.widget.Button", label: "Allow", frame: { x: 0.15, y: 0.55, width: 0.7, height: 0.05 } }] }] };
|
||||
const { run } = harness("android", { "list-devices": ANDROID_DEVICES, "ui-tree": dialog });
|
||||
const snapshot = (await run(["snapshot", ...flags("android")])).json.data;
|
||||
assert.ok(snapshot.nodes.some(node => node.type === "Button" && node.label === "Allow"), "the dialog's buttons can be found");
|
||||
assert.ok(snapshot.nodes.some(node => node.type === "Alert"), "capture sees an alert covering the app");
|
||||
assert.ok(!snapshot.nodes.some(node => /systemui/.test(JSON.stringify(node))), "the system UI is still left out");
|
||||
assert.deepEqual((await run(["alert", "get", ...flags("android")])).json.data.alert.buttons, ["Allow"]);
|
||||
});
|
||||
|
||||
test("system back swipes from the iOS edge; Android prefers an in-app back control", async () => {
|
||||
const ios = harness("ios", { "list-devices": IOS_DEVICES, "ui-tree": IOS_HOME, "gesture-swipe": {} });
|
||||
assert.equal((await ios.run(["back", "--system", ...flags("ios")])).exitCode, 0);
|
||||
assert.deepEqual(ios.calls.at(-1).args, { udid: UDID, fromX: 0.05, fromY: 0.5, toX: 0.8, toY: 0.5, momentum: false });
|
||||
|
||||
const up = { ...ANDROID_HOME, roots: [...ANDROID_HOME.roots.filter(root => root.bundleId !== BUNDLE), { type: "android.widget.FrameLayout", bundleId: BUNDLE,
|
||||
frame: { x: 0, y: 0, width: 1, height: 1 }, children: [{ type: "android.widget.ImageButton", contentDescription: "Navigate up", frame: { x: 0, y: 0.05, width: 0.1, height: 0.05 } }] }] };
|
||||
const android = harness("android", { "list-devices": ANDROID_DEVICES, "ui-tree": up, "gesture-tap": {}, button: {} });
|
||||
assert.deepEqual((await android.run(["back", "--in-app", ...flags("android")])).json.data, { action: "back", mode: "in-app" });
|
||||
assert.equal(android.calls.some(call => call.tool === "button"), false);
|
||||
const none = harness("android", { "list-devices": ANDROID_DEVICES, "ui-tree": ANDROID_HOME, button: {} });
|
||||
assert.equal((await none.run(["back", "--in-app", ...flags("android")])).json.error.message, "in-app back control is not available");
|
||||
assert.deepEqual((await none.run(["back", ...flags("android")])).json.data, { action: "back", mode: "system" });
|
||||
});
|
||||
|
||||
test("open without --relaunch keeps a running app as it is", async () => {
|
||||
const { run, calls } = harness("ios", { "list-devices": IOS_DEVICES, "ui-tree": IOS_HOME, "restart-app": {} });
|
||||
assert.equal((await run(["open", BUNDLE, ...flags("ios")])).exitCode, 0);
|
||||
assert.equal(calls.some(call => call.tool === "restart-app"), false);
|
||||
});
|
||||
|
||||
test("a link prompt that lingers a moment after Open is pressed is not a failure", async () => {
|
||||
const prompt = { ...IOS_HOME, alertVisible: true, foregroundApp: "com.apple.springboard",
|
||||
roots: [...IOS_HOME.roots, { type: "Alert", label: "Open in “euxy”?", frame: { x: 0.1, y: 0.4, width: 0.8, height: 0.2 }, children: [] }] };
|
||||
// Read once before the press, twice more while the app comes forward, then the app.
|
||||
const { run, context } = harness("ios", { "list-devices": IOS_DEVICES, "open-url": {}, "gesture-tap": {}, describe: { description: "" }, "ui-tree": [prompt, prompt, prompt, IOS_HOME] });
|
||||
assert.equal((await run(["open", BUNDLE, "euxy://", ...flags("ios")])).exitCode, 0);
|
||||
assert.equal(context.state.deepLinkPromptAccepted, true);
|
||||
});
|
||||
|
||||
test("on iPhone Duo's inner display, a sheet's title outside Argent's shrunken root frame is visible", () => {
|
||||
assert.deepEqual(DUO_OPEN_EDIT_LANE.roots[0].frame, { x: 0, y: 0, width: 0.3333333333333333, height: 0.3333333333333333 }, "the recorded Argent quirk");
|
||||
const { nodes } = snapshotFromTree(DUO_OPEN_EDIT_LANE, "ios", 1, BUNDLE);
|
||||
for (const label of ["Edit Lane", "Cancel", "Done"]) {
|
||||
const node = nodes.find(item => item.label === label);
|
||||
assert.ok(node, label);
|
||||
assert.notEqual(node.visible, false, `${label} is visible`);
|
||||
}
|
||||
});
|
||||
|
||||
test("a node its ancestor clips away is still reported hidden on iOS", () => {
|
||||
const clipped = { screen: { width: 400, height: 800 }, foregroundApp: BUNDLE, roots: [{ type: "Application", frame: { x: 0, y: 0, width: 1, height: 1 }, children: [
|
||||
{ type: "ScrollView", frame: { x: 0, y: 0, width: 1, height: 0.5 }, children: [
|
||||
{ type: "Button", label: "In view", frame: { x: 0.1, y: 0.1, width: 0.3, height: 0.05 } },
|
||||
{ type: "Button", label: "Scrolled away", frame: { x: 0.1, y: 0.7, width: 0.3, height: 0.05 } }] }] }] };
|
||||
const { nodes } = snapshotFromTree(clipped, "ios", 1, BUNDLE);
|
||||
assert.notEqual(nodes.find(node => node.label === "In view").visible, false);
|
||||
assert.equal(nodes.find(node => node.label === "Scrolled away").visible, false);
|
||||
});
|
||||
|
||||
test("a fold whose panel Argent never reads fails clearly instead of capturing the dark panel", async () => {
|
||||
const lit = { activeScreen: 3, screen: { id: 3, panel: "inner panel", width: 2007, height: 2853 }, posture: "open", hingeAngle: 180 };
|
||||
const blindClosed = { ...DUO_HOME, foregroundApp: undefined, roots: [{ role: "AXGroup", children: [] }] };
|
||||
const late = harness("ios", { "list-devices": DUO_DEVICES, fold: lit, "ui-tree": [blindClosed, blindClosed, DUO_OPEN_EDIT_LANE] });
|
||||
assert.equal((await late.run(["fold", "open", ...flags("ios")])).exitCode, 0, "a reader that catches up within the wait is fine");
|
||||
const stuck = harness("ios", { "list-devices": DUO_DEVICES, fold: lit, "ui-tree": blindClosed });
|
||||
const failed = await stuck.run(["fold", "open", ...flags("ios")]);
|
||||
assert.equal(failed.json.error.code, "CONTROLLER_FOLD_UNVERIFIED");
|
||||
assert.equal(stuck.calls.filter(call => call.tool === "fold").length, 1, "the session is not folded back and forth");
|
||||
});
|
||||
@@ -101,3 +101,27 @@ test("attached sessions are proven live, agent-device typed, and served by the g
|
||||
await assert.rejects(resolveAttachedSimulatorSession({}, undefined), /EAS_SIMULATOR_SESSION_ID did not return a session id/);
|
||||
await assert.rejects(resolveAttachedSimulatorSession({ ...env, AGENT_DEVICE_DAEMON_AUTH_TOKEN: "" }, undefined), /unsafe agent-device connection/);
|
||||
});
|
||||
|
||||
test("an attached argent session is found from ARGENT_* and proven against the session's tool-server", async () => {
|
||||
const { assertAttachedSimulatorSession, readSimulatorDotenvHandoff, resolveAttachedSimulatorSession } = await import(join(root, "dist", "capture", "simulator.js"));
|
||||
const connection = { sessionId: "01a1-mine", daemonBaseUrl: "https://tools.example.eas.dev", daemonAuthToken: "secret", controller: "argent" };
|
||||
const env = { EAS_SIMULATOR_SESSION_ID: "01a1-mine", ARGENT_TOOLS_URL: connection.daemonBaseUrl, ARGENT_AUTH_TOKEN: "secret" };
|
||||
assert.deepEqual(await resolveAttachedSimulatorSession(env, undefined), connection);
|
||||
// A tool-server that needs no token is still an argent session.
|
||||
assert.deepEqual(await resolveAttachedSimulatorSession({ ...env, ARGENT_AUTH_TOKEN: undefined }, undefined), { ...connection, daemonAuthToken: "" });
|
||||
await assert.rejects(resolveAttachedSimulatorSession({ ...env, ARGENT_TOOLS_URL: "http://tools.example.eas.dev" }, undefined), /unsafe argent/);
|
||||
const session = (overrides = {}) => JSON.stringify({ id: "01a1-mine", name: "mine", type: "argent", status: "IN_PROGRESS", platform: "ANDROID",
|
||||
remoteConfig: { toolsUrl: connection.daemonBaseUrl, toolsAuthToken: "secret" }, ...overrides });
|
||||
assert.equal(assertAttachedSimulatorSession(session(), connection).platform, "android");
|
||||
assert.throws(() => assertAttachedSimulatorSession(session({ type: "agent-device" }), connection), /attached argent session/);
|
||||
assert.throws(() => assertAttachedSimulatorSession(session({ remoteConfig: { toolsUrl: connection.daemonBaseUrl, toolsAuthToken: "other" } }), connection), /different argent connection/);
|
||||
const dir = await mkdtemp(join(tmpdir(), "explore-argent-dotenv-"));
|
||||
try {
|
||||
const path = join(dir, ".env.eas-simulator");
|
||||
await writeFile(path, "# Do not commit this file.\n# Do not modify these values manually. They are managed by eas-cli.\n# It holds configuration only for the current simulator session.\n\nEAS_SIMULATOR_SESSION_ID='01a1-mine'\nARGENT_TOOLS_URL='https://tools.example.eas.dev'\nARGENT_AUTH_TOKEN='secret'\n");
|
||||
const handoff = await readSimulatorDotenvHandoff(path);
|
||||
assert.equal(handoff.validationError, undefined);
|
||||
assert.deepEqual(handoff.connection, connection);
|
||||
assert.deepEqual(await resolveAttachedSimulatorSession({}, path), connection);
|
||||
} finally { await rm(dir, { recursive: true, force: true }); }
|
||||
});
|
||||
@@ -135,6 +135,11 @@ test("capture recipes exclude display settings but bind agent instructions and c
|
||||
assert.equal(JSON.parse(key).observer, CAPTURE_OBSERVER_HASH);
|
||||
assert.match(JSON.parse(key).observer, /^[a-f0-9]{64}$/);
|
||||
assert.equal(key,captureRecipeConfig({...config,app:{...config.app,name:"Renamed display"}}));
|
||||
// agent-device recipes are unchanged by Argent support; an Argent capture is keyed to Argent and its version.
|
||||
assert.equal(JSON.parse(key).controllerVersion, undefined);
|
||||
const argent = JSON.parse(captureRecipeConfig({...config,capture:{...config.capture,controller:"argent"}}));
|
||||
assert.equal(argent.capture.controller, "argent");
|
||||
assert.match(argent.controllerVersion, /^\d+\.\d+\.\d+$/);
|
||||
const agent = {...config,mode:"agent",agent:{provider:"openai",model:"another-model",instructions:".expo-explore/instructions.md"}};
|
||||
assert.notEqual(key,captureRecipeConfig(agent,"a".repeat(64)));
|
||||
assert.equal(JSON.parse(captureRecipeConfig(agent,"a".repeat(64))).agent.acceptancePolicy, AGENT_ACCEPTANCE_POLICY);
|
||||
|
||||
+79
-13
@@ -142,13 +142,16 @@ async function fixture(t, settings = {}) {
|
||||
}
|
||||
if (command === 'simulator:start') {
|
||||
sessionName = value(request, '--name');
|
||||
writeFileSync(join(request.cwd, '.env.eas-simulator'), HEADER + "EAS_SIMULATOR_SESSION_ID='session-1'\nAGENT_DEVICE_DAEMON_BASE_URL='https://controller.example/session'\nAGENT_DEVICE_DAEMON_AUTH_TOKEN='" + DAEMON_TOKEN + "'\n");
|
||||
writeFileSync(join(request.cwd, '.env.eas-simulator'), HEADER + "EAS_SIMULATOR_SESSION_ID='session-1'\n" + (settings.argent
|
||||
? "ARGENT_TOOLS_URL='https://controller.example/session'\nARGENT_AUTH_TOKEN='" + DAEMON_TOKEN + "'\n"
|
||||
: "AGENT_DEVICE_DAEMON_BASE_URL='https://controller.example/session'\nAGENT_DEVICE_DAEMON_AUTH_TOKEN='" + DAEMON_TOKEN + "'\n"));
|
||||
if (settings.startFailure) throw new Error('start reported failure after allocation');
|
||||
return { stdout: 'ready', stderr: '' };
|
||||
}
|
||||
if (command === 'simulator:get') return json({ id: 'session-1', name: sessionName, type: 'agent-device', platform: settings.android ? 'ANDROID' : 'IOS', status: 'IN_PROGRESS',
|
||||
if (command === 'simulator:get') return json({ id: 'session-1', name: sessionName, type: settings.argent ? 'argent' : 'agent-device', platform: settings.android ? 'ANDROID' : 'IOS', status: 'IN_PROGRESS',
|
||||
app: { id: settings.wrongProject ? 'foreign-project' : PROJECT_ID, slug: 'example', ownerAccount: { name: 'acme' } },
|
||||
remoteConfig: { agentDeviceRemoteSessionUrl: 'https://controller.example/session', agentDeviceRemoteSessionToken: DAEMON_TOKEN,
|
||||
remoteConfig: { ...(settings.argent ? { toolsUrl: 'https://controller.example/session', toolsAuthToken: DAEMON_TOKEN }
|
||||
: { agentDeviceRemoteSessionUrl: 'https://controller.example/session', agentDeviceRemoteSessionToken: DAEMON_TOKEN }),
|
||||
// eas-cli --json folds the preview token into an expo.dev page that frames the preview server.
|
||||
webPreviewUrl: settings.webPreviewUrl ?? `https://expo.dev/simulator-preview/${PREVIEW_ID}?token=${PREVIEW_TOKEN}`,
|
||||
...(settings.previewApiUrl ? { previewApiUrl: settings.previewApiUrl } : {}) } });
|
||||
@@ -165,8 +168,9 @@ async function fixture(t, settings = {}) {
|
||||
if (settings.android) writeFileSync(value(request, '--output'), 'apk'); else mkdirSync(value(request, '--output'));
|
||||
return { stdout: '', stderr: '' };
|
||||
}
|
||||
if (request.command === 'fake-controller') {
|
||||
if (command === '--version') return { stdout: AGENT_DEVICE_VERSION, stderr: '' };
|
||||
// An Argent capture runs its per-run bridge in place of agent-device; the bridge answers in agent-device's envelopes.
|
||||
if (request.command === 'fake-controller' || (settings.argent && request.command.endsWith('/argent-controller'))) {
|
||||
if (command === '--version') return { stdout: settings.argent ? '0.29.0' : AGENT_DEVICE_VERSION, stderr: '' };
|
||||
if (command === 'open') {
|
||||
if (request.args.includes('--relaunch')) splashLeft = settings.splashFrames ?? 0;
|
||||
if (request.args[2]?.startsWith('sample://')) {
|
||||
@@ -185,6 +189,7 @@ async function fixture(t, settings = {}) {
|
||||
return ok(settings.wrongForeground ? { appBundleId: 'com.foreign.app' } : identity());
|
||||
}
|
||||
if (command === 'wait') return ok({});
|
||||
if (command === 'fold') return ok({ action: 'fold', pose: request.args[1] });
|
||||
if (command === 'record' && settings.recording) {
|
||||
if (request.args[1] === 'start') { recordingPath = request.args[2]; return ok({ path: recordingPath }); }
|
||||
writeFileSync(recordingPath, 'mp4-bytes'); return ok({ path: recordingPath });
|
||||
@@ -283,7 +288,7 @@ async function fixture(t, settings = {}) {
|
||||
buildId: 'source-capture', buildVersion: '1', gitCommit: SHA, bundleId: 'com.example.app',
|
||||
...(settings.noScheme ? {} : { scheme: 'sample' }), device: deviceName, easProfile: 'capture', expoToken: 'expo-private', ...(settings.android ? { platform: 'android' } : {}),
|
||||
planPath, maxScreens: 120, maxActions: 500, maxDurationMinutes: 30, forceFreshBuild: false,
|
||||
confirmExternalRun: true, confirmTrustedSource: true, easCommand: 'fake-eas', repackCommand: 'fake-repack', agentDeviceCommand: 'fake-controller', ...(settings.launch ? { launch: settings.launch, recordingTools: settings.recordingTools ?? null } : {}), ...(settings.repack ? { repack: settings.repack } : {}),
|
||||
confirmExternalRun: true, confirmTrustedSource: true, easCommand: 'fake-eas', repackCommand: 'fake-repack', agentDeviceCommand: 'fake-controller', ...(settings.argent ? { controller: 'argent' } : {}), ...(settings.devicePose ? { devicePose: settings.devicePose } : {}), ...(settings.launch ? { launch: settings.launch, recordingTools: settings.recordingTools ?? null } : {}), ...(settings.repack ? { repack: settings.repack } : {}),
|
||||
environment: { PATH: process.env.PATH, HOME: root, GITHUB_TOKEN: 'github-private', ANTHROPIC_API_KEY: 'must-not-be-used', AGENT_DEVICE_DAEMON_AUTH_TOKEN: 'wrong-token', ...settings.environment },
|
||||
// Every controller round trip advances the fixture clock by one poll interval, as a device snapshot would.
|
||||
runner: request => { clockMs += 600; return runner(request); }, now: () => clockMs, sleep: milliseconds => { clockMs += milliseconds; }, fetch: catalog };
|
||||
@@ -350,6 +355,74 @@ test('an app pinned to one appearance is captured once, in that appearance', asy
|
||||
assert.deepEqual(map.screens.map(screen => [screen.id, screen.colorScheme]), [[f.ids.home, undefined], [f.ids.settings, undefined]]);
|
||||
});
|
||||
|
||||
test('an Argent capture starts an argent session, drives it through the bridge, and records Argent as the controller', async t => {
|
||||
const f = await fixture(t, { argent: true, userInterfaceStyle: 'automatic', environment: { AGENT_DEVICE_DAEMON_BASE_URL: 'https://wrong.example', ARGENT_TOOLS_URL: 'https://wrong.example' } });
|
||||
const lines = [];
|
||||
const result = await runCiMap({ ...f.options, progress: line => lines.push(line) });
|
||||
assert.equal(result.runStatus, 'complete');
|
||||
const start = f.requests.find(request => request.args[0] === 'simulator:start');
|
||||
assert.equal(value(start, '--type'), 'argent');
|
||||
assert.equal(value(start, '--package-version'), '0.29.0');
|
||||
assert.ok(start.args.includes('--public-link'));
|
||||
const controller = f.requests.filter(request => request.command.endsWith('/argent-controller'));
|
||||
assert.ok(controller.length > 0);
|
||||
assert.ok(!f.requests.some(request => request.command === 'fake-controller'), 'every controller call goes through the bridge');
|
||||
for (const request of controller) {
|
||||
assert.equal(request.environment.ARGENT_TOOLS_URL, 'https://controller.example/session');
|
||||
assert.equal(request.environment.ARGENT_AUTH_TOKEN, DAEMON_TOKEN);
|
||||
assert.equal(request.environment.DO_NOT_TRACK, '1');
|
||||
assert.equal(request.environment.EXPLORE_ARGENT_PLATFORM, 'ios');
|
||||
assert.equal(request.environment.EXPLORE_ARGENT_BUNDLE_ID, 'com.example.app');
|
||||
assert.ok(request.environment.HOME.endsWith('/argent-home') && request.environment.HOME !== f.options.environment.HOME, 'Argent gets a HOME of its own');
|
||||
assert.deepEqual(Object.keys(request.environment).filter(name => name.startsWith('AGENT_DEVICE_')), []);
|
||||
}
|
||||
// Argent cannot switch appearance yet: one pass, no `settings appearance`, and a warning naming what was skipped.
|
||||
assert.equal(f.requests.some(request => request.args[0] === 'settings'), false);
|
||||
assert.ok(lines.some(line => /Argent cannot switch appearance yet .*capturing light only, skipped dark/.test(line)), lines.join('\n'));
|
||||
const map = JSON.parse(await readFile(join(f.options.outputDirectory, 'screen-map.json'), 'utf8'));
|
||||
assert.equal(map.run.controller, 'argent');
|
||||
assert.equal(map.run.environment.colorSchemes, undefined);
|
||||
assert.deepEqual(map.screens.map(screen => screen.id), [f.ids.home, f.ids.settings]);
|
||||
const bundle = JSON.parse(await readFile(join(f.options.outputDirectory, 'bundle.json'), 'utf8'));
|
||||
assert.equal(bundle.controller, 'argent');
|
||||
const execution = parseRuntimeExecutionContext(JSON.parse(await readFile(join(f.options.outputDirectory, 'execution.json'), 'utf8')));
|
||||
assert.equal(execution.controller, 'argent');
|
||||
assert.equal(execution.controllerPackageVersion, '0.29.0');
|
||||
});
|
||||
|
||||
test('an Argent capture of an app pinned to dark is labelled dark and is not warned about', async t => {
|
||||
const f = await fixture(t, { argent: true, userInterfaceStyle: 'dark' });
|
||||
const lines = [];
|
||||
await runCiMap({ ...f.options, progress: line => lines.push(line) });
|
||||
assert.equal(lines.some(line => /Argent cannot switch appearance/.test(line)), false);
|
||||
const execution = parseRuntimeExecutionContext(JSON.parse(await readFile(join(f.options.outputDirectory, 'execution.json'), 'utf8')));
|
||||
assert.equal(execution.colorScheme, 'dark');
|
||||
});
|
||||
|
||||
test('device.pose folds the device first, before the app is opened, read or captured', async t => {
|
||||
for (const argent of [false, true]) {
|
||||
const f = await fixture(t, { devicePose: 'open', argent });
|
||||
assert.equal((await runCiMap(f.options)).runStatus, 'complete');
|
||||
const controller = f.requests.filter(request => request.command === 'fake-controller' || request.command.endsWith('/argent-controller'));
|
||||
const folds = controller.filter(request => request.args[0] === 'fold');
|
||||
assert.equal(folds.length, 1);
|
||||
assert.deepEqual(folds[0].args.slice(0, 2), ['fold', 'open']);
|
||||
const foldAt = controller.indexOf(folds[0]);
|
||||
// The fold comes first: the app is not opened, read or captured before it, so the controller starts on the lit panel.
|
||||
assert.deepEqual(controller.slice(0, foldAt).map(request => request.args[0]).filter(command => command !== '--version'), []);
|
||||
}
|
||||
});
|
||||
|
||||
test('an agent-device capture writes no controller into its bundle', async t => {
|
||||
const f = await fixture(t);
|
||||
await runCiMap(f.options);
|
||||
const bundle = JSON.parse(await readFile(join(f.options.outputDirectory, 'bundle.json'), 'utf8'));
|
||||
assert.equal('controller' in bundle, false);
|
||||
const start = f.requests.find(request => request.args[0] === 'simulator:start');
|
||||
assert.equal(value(start, '--type'), 'agent-device');
|
||||
assert.equal(value(start, '--package-version'), AGENT_DEVICE_VERSION);
|
||||
});
|
||||
|
||||
test('a preview URL that names the preview server directly reads its catalog', async t => {
|
||||
const f = await fixture(t, { webPreviewUrl: `https://web-preview-${PREVIEW_ID}.eas-simulator.ngrok.dev/?token=${PREVIEW_TOKEN}` });
|
||||
const result = await runCiMap(f.options);
|
||||
@@ -2550,13 +2623,6 @@ test('a timed-out native alert query is unknown: the snapshot decides, and it is
|
||||
assert.equal(blocked.operations().includes('screenshot'), false);
|
||||
});
|
||||
|
||||
test('the installed agent-device dependency is the version every controller check uses', async () => {
|
||||
const manifest = JSON.parse(await readFile(new URL('../../package.json', import.meta.url), 'utf8'));
|
||||
const lock = JSON.parse(await readFile(new URL('../../package-lock.json', import.meta.url), 'utf8'));
|
||||
assert.equal(manifest.dependencies['agent-device'], AGENT_DEVICE_VERSION);
|
||||
assert.equal(lock.packages['node_modules/agent-device'].version, AGENT_DEVICE_VERSION);
|
||||
});
|
||||
|
||||
test('agent observation waits out a deferred system-surface snapshot instead of failing', async t => {
|
||||
const f = await fixture(t, { routes: [route('home')] });
|
||||
let refusals = 1, snapshots = 0;
|
||||
|
||||
@@ -0,0 +1,124 @@
|
||||
import assert from "node:assert/strict";
|
||||
import { spawnSync } from "node:child_process";
|
||||
import { createHash } from "node:crypto";
|
||||
import { existsSync, statSync } from "node:fs";
|
||||
import { mkdir, mkdtemp, readFile, readdir, rm, writeFile } from "node:fs/promises";
|
||||
import { tmpdir } from "node:os";
|
||||
import { join } from "node:path";
|
||||
import test from "node:test";
|
||||
import { gzipSync } from "node:zlib";
|
||||
import { AGENT_DEVICE_VERSION } from "../../dist/shared/agent-device-version.js";
|
||||
import { ARGENT_VERSION } from "../../dist/shared/argent-version.js";
|
||||
import { CONTROLLER_PACKAGES, agentDeviceLauncher, controllerBin, controllerCacheRoot, controllerCached, controllerDirectory, controllerTarballUrl, ensureController } from "../../dist/shared/controller-cache.js";
|
||||
|
||||
/** A gzip tarball of `entries` ({ name, contents?, type?, mode?, link? }), laid out as npm publishes one. */
|
||||
function tarball(entries) {
|
||||
const blocks = [];
|
||||
for (const entry of entries) {
|
||||
const contents = Buffer.from(entry.contents ?? "");
|
||||
const header = Buffer.alloc(512);
|
||||
header.write(entry.name, 0, 100);
|
||||
header.write(`${(entry.mode ?? 0o644).toString(8).padStart(7, "0")}\0`, 100);
|
||||
header.write("0000000\0", 108); header.write("0000000\0", 116);
|
||||
header.write(`${(entry.type === "0" || !entry.type ? contents.length : 0).toString(8).padStart(11, "0")}\0`, 124);
|
||||
header.write("00000000000\0", 136);
|
||||
header.write(" ", 148);
|
||||
header.write(entry.type ?? "0", 156);
|
||||
if (entry.link) header.write(entry.link, 157, 100);
|
||||
header.write("ustar\0", 257); header.write("00", 263);
|
||||
const sum = header.reduce((total, byte) => total + byte, 0);
|
||||
header.write(`${sum.toString(8).padStart(6, "0")}\0 `, 148);
|
||||
blocks.push(header);
|
||||
if (!entry.type || entry.type === "0") blocks.push(contents, Buffer.alloc((512 - (contents.length % 512)) % 512));
|
||||
}
|
||||
blocks.push(Buffer.alloc(1024));
|
||||
return gzipSync(Buffer.concat(blocks));
|
||||
}
|
||||
|
||||
const integrity = bytes => `sha512-${createHash("sha512").update(bytes).digest("base64")}`;
|
||||
|
||||
async function harness(t, entries, options = {}) {
|
||||
const root = await mkdtemp(join(tmpdir(), "explore-controller-cache-"));
|
||||
t.after(() => rm(root, { recursive: true, force: true }));
|
||||
const bytes = tarball(entries);
|
||||
const environment = { EXPLORE_CONTROLLER_CACHE: join(root, "cache") };
|
||||
const packages = { ...CONTROLLER_PACKAGES, "agent-device": { ...CONTROLLER_PACKAGES["agent-device"], integrity: options.integrity ?? integrity(bytes) } };
|
||||
const requests = [];
|
||||
const fetch = async url => { requests.push(String(url)); return new Response(bytes); };
|
||||
return { root, environment, requests, ensure: () => ensureController("agent-device", { environment, fetch, packages }) };
|
||||
}
|
||||
|
||||
const CLI = { name: "package/bin/agent-device.mjs", contents: "#!/usr/bin/env node\nconsole.log(JSON.stringify(process.argv.slice(2)));\n" };
|
||||
|
||||
test("the pinned controllers are the versions Explore drives, and agent-device matches the lockfile Explore tests with", async () => {
|
||||
assert.equal(CONTROLLER_PACKAGES["agent-device"].version, AGENT_DEVICE_VERSION);
|
||||
assert.equal(CONTROLLER_PACKAGES.argent.version, ARGENT_VERSION);
|
||||
const manifest = JSON.parse(await readFile(new URL("../../package.json", import.meta.url), "utf8"));
|
||||
const lock = JSON.parse(await readFile(new URL("../../package-lock.json", import.meta.url), "utf8"));
|
||||
assert.equal(manifest.dependencies["agent-device"], undefined, "agent-device is fetched on use, not installed with Explore");
|
||||
assert.equal(manifest.dependencies["@swmansion/argent"], undefined, "Argent is fetched on use, not installed with Explore");
|
||||
assert.equal(manifest.devDependencies["agent-device"], AGENT_DEVICE_VERSION);
|
||||
assert.equal(lock.packages["node_modules/agent-device"].integrity, CONTROLLER_PACKAGES["agent-device"].integrity);
|
||||
});
|
||||
|
||||
test("tarballs come from the npm registry, or a mirror, at the pinned version", () => {
|
||||
assert.equal(controllerTarballUrl("argent", {}), `https://registry.npmjs.org/@swmansion/argent/-/argent-${ARGENT_VERSION}.tgz`);
|
||||
assert.equal(controllerTarballUrl("agent-device", { EXPLORE_NPM_REGISTRY: "https://npm.example.com/" }),
|
||||
`https://npm.example.com/agent-device/-/agent-device-${AGENT_DEVICE_VERSION}.tgz`);
|
||||
assert.equal(controllerCacheRoot({ HOME: "/home/me" }), "/home/me/.cache/expo-explore/controllers");
|
||||
assert.equal(controllerCacheRoot({ HOME: "/home/me", XDG_CACHE_HOME: "/cache" }), "/cache/expo-explore/controllers");
|
||||
assert.match(controllerDirectory("argent", { EXPLORE_CONTROLLER_CACHE: "/c" }), new RegExp(`^/c/@swmansion\\+argent@${ARGENT_VERSION}$`));
|
||||
});
|
||||
|
||||
test("a controller is fetched once, verified, unpacked, and its entry made executable", async t => {
|
||||
const f = await harness(t, [{ name: "package/", type: "5", mode: 0o755 }, CLI, { name: "package/package.json", contents: "{}" }]);
|
||||
const bin = await f.ensure();
|
||||
assert.equal(bin, controllerBin("agent-device", f.environment));
|
||||
assert.equal(statSync(bin).mode & 0o111, 0o111);
|
||||
assert.ok(controllerCached("agent-device", f.environment));
|
||||
assert.equal(await f.ensure(), bin);
|
||||
assert.equal(f.requests.length, 1, "a cached controller is not fetched again");
|
||||
assert.deepEqual((await readdir(join(f.root, "cache"))).filter(name => name.startsWith(".staging")), [], "no staging files are left");
|
||||
});
|
||||
|
||||
test("a tarball that does not match the pinned integrity is never unpacked", async t => {
|
||||
const f = await harness(t, [CLI], { integrity: "sha512-not-the-release" });
|
||||
await assert.rejects(f.ensure(), error => error.code === "CONTROLLER_INTEGRITY_MISMATCH");
|
||||
assert.equal(controllerCached("agent-device", f.environment), false);
|
||||
assert.equal(existsSync(controllerDirectory("agent-device", f.environment)), false);
|
||||
});
|
||||
|
||||
test("links and paths outside the package are refused", async t => {
|
||||
for (const entry of [{ name: "package/evil", type: "2", link: "/etc/passwd" }, { name: "package/../escape.js", contents: "x" }, { name: "other/file.js", contents: "x" }]) {
|
||||
const f = await harness(t, [CLI, entry]);
|
||||
await assert.rejects(f.ensure(), error => error.code === "CONTROLLER_DOWNLOAD_FAILED", entry.name);
|
||||
assert.equal(controllerCached("agent-device", f.environment), false);
|
||||
}
|
||||
});
|
||||
|
||||
test("a registry failure names the release and the mirror setting", async t => {
|
||||
const root = await mkdtemp(join(tmpdir(), "explore-controller-cache-"));
|
||||
t.after(() => rm(root, { recursive: true, force: true }));
|
||||
await assert.rejects(ensureController("agent-device", { environment: { EXPLORE_CONTROLLER_CACHE: root }, fetch: async () => new Response("no", { status: 404 }) }),
|
||||
error => error.code === "CONTROLLER_DOWNLOAD_FAILED" && /agent-device@/.test(error.message) && /EXPLORE_NPM_REGISTRY/.test(error.nextAction));
|
||||
});
|
||||
|
||||
test("the agent-device command runs the cached release with the caller's arguments, without a network", async t => {
|
||||
const root = await mkdtemp(join(tmpdir(), "explore-controller-cache-"));
|
||||
t.after(() => rm(root, { recursive: true, force: true }));
|
||||
const environment = { EXPLORE_CONTROLLER_CACHE: join(root, "cache") };
|
||||
const directory = controllerDirectory("agent-device", environment);
|
||||
await mkdir(join(directory, "bin"), { recursive: true });
|
||||
await writeFile(join(directory, "bin/agent-device.mjs"), CLI.contents, { mode: 0o755 });
|
||||
await writeFile(join(directory, ".explore-controller.json"), "{}\n");
|
||||
const command = agentDeviceLauncher(environment);
|
||||
assert.equal(agentDeviceLauncher(environment), command, "the command is stable");
|
||||
assert.match(command, new RegExp(`/bin/agent-device-${AGENT_DEVICE_VERSION}-[0-9a-f]{12}$`), "the command names its release");
|
||||
const mirrored = agentDeviceLauncher({ ...environment, EXPLORE_NPM_REGISTRY: "https://npm.example.com" });
|
||||
assert.notEqual(mirrored, command, "another setup gets a command of its own instead of rewriting this one");
|
||||
assert.match(await readFile(mirrored, "utf8"), /EXPLORE_NPM_REGISTRY='https:\/\/npm\.example\.com'/, "the mirror reaches the narrowed controller environment");
|
||||
// The command names its cache, so a caller that narrows the environment still reaches it.
|
||||
const run = spawnSync(command, ["snapshot", "--json", "--", "-h"], { encoding: "utf8", env: { PATH: process.env.PATH } });
|
||||
assert.equal(run.status, 0, run.stderr);
|
||||
assert.deepEqual(JSON.parse(run.stdout), ["snapshot", "--json", "--", "-h"]);
|
||||
});
|
||||
@@ -5,7 +5,7 @@ import { join } from "node:path";
|
||||
import test from "node:test";
|
||||
import { tsImport } from "tsx/esm/api";
|
||||
|
||||
const { DEFAULT_EXPLORE_CONFIG_PATH, assertExecutionMode, parseExploreConfig, readExploreConfig, validateExploreConfig, configPlatforms, resolvePlatformConfig } =
|
||||
const { DEFAULT_EXPLORE_CONFIG_PATH, assertExecutionMode, parseExploreConfig, readExploreConfig, validateExploreConfig, configPlatforms, resolvePlatformConfig, withRunOverrides } =
|
||||
await tsImport("../../src/config/explore-config.ts", import.meta.url);
|
||||
|
||||
const SOURCE = `app:
|
||||
@@ -241,3 +241,31 @@ test("capture.reset accepts root-link or none, defaults to root-link, and reject
|
||||
assert.equal(validateExploreConfig({ ...base(), capture: { reset: "none" } }).capture.reset, "none");
|
||||
assert.throws(() => validateExploreConfig({ ...base(), capture: { reset: "relaunch" } }), /capture\.reset must be "root-link" or "none"/);
|
||||
});
|
||||
|
||||
test("capture.controller chooses Argent; agent-device, the default, leaves the config as it was", () => {
|
||||
const plain = validateExploreConfig(base());
|
||||
assert.equal("controller" in plain.capture, false);
|
||||
assert.deepEqual(validateExploreConfig({ ...base(), capture: { controller: "agent-device" } }), plain);
|
||||
assert.equal(validateExploreConfig({ ...base(), capture: { controller: "argent" } }).capture.controller, "argent");
|
||||
assert.throws(() => validateExploreConfig({ ...base(), capture: { controller: "maestro" } }), error => error.code === "CONFIG_INVALID");
|
||||
});
|
||||
|
||||
test("--controller overrides the config's controller for one run and is validated", () => {
|
||||
const plain = validateExploreConfig(base());
|
||||
const argent = withRunOverrides(plain, { controller: "argent" });
|
||||
assert.equal(argent.capture.controller, "argent");
|
||||
assert.deepEqual(withRunOverrides(argent, { controller: "agent-device" }), plain);
|
||||
assert.deepEqual(withRunOverrides(plain, {}), plain);
|
||||
assert.throws(() => withRunOverrides(plain, { controller: "appium" }), /--controller must be agent-device or argent/);
|
||||
});
|
||||
|
||||
test("device.pose folds the primary platform's device and is validated", () => {
|
||||
const open = validateExploreConfig({ ...base(), device: { name: "iPhone Duo", pose: "open" } });
|
||||
assert.deepEqual(open.device, { name: "iPhone Duo", pose: "open" });
|
||||
assert.equal("pose" in validateExploreConfig(base()).device, false);
|
||||
assert.throws(() => validateExploreConfig({ ...base(), device: { name: "iPhone Duo", pose: "flat" } }), error => error.code === "CONFIG_INVALID");
|
||||
const both = validateExploreConfig({ ...base(), app: { ...base().app, platform: "ios" }, device: { name: "iPhone Duo", pose: "open" },
|
||||
platforms: { ios: {}, android: { device: "pixel_7", bundleId: "com.example.app", easProfile: "explore" } } });
|
||||
assert.deepEqual(resolvePlatformConfig(both, "ios").device, { name: "iPhone Duo", pose: "open" });
|
||||
assert.deepEqual(resolvePlatformConfig(both, "android").device, { name: "pixel_7" });
|
||||
});
|
||||
@@ -271,7 +271,7 @@ test('Ctrl+C during a deterministic capture stops it before the next route and s
|
||||
const name = request.command.split('/').at(-1);
|
||||
calls.push({ name, command: request.args[0], afterCtrlC: ctrlC.signal.aborted });
|
||||
// The first route link is opened: the person presses Ctrl+C while it loads.
|
||||
if (name === 'agent-device' && request.args[0] === 'open' && /sample:\/\//.test(request.args[2] ?? '') && !ctrlC.signal.aborted) ctrlC.abort();
|
||||
if (/^agent-device(-|$)/.test(name) && request.args[0] === 'open' && /sample:\/\//.test(request.args[2] ?? '') && !ctrlC.signal.aborted) ctrlC.abort();
|
||||
return f.runner(request);
|
||||
};
|
||||
let kept;
|
||||
@@ -284,7 +284,7 @@ test('Ctrl+C during a deterministic capture stops it before the next route and s
|
||||
const after = calls.filter(call => call.afterCtrlC);
|
||||
assert.ok(after.some(call => call.command === 'simulator:stop'), 'its session is stopped');
|
||||
assert.equal(after.filter(call => call.command === 'simulator:start').length, 0, 'no other session starts');
|
||||
assert.ok(after.filter(call => call.name === 'agent-device' && call.command === 'open').length <= 1, 'no further route is opened');
|
||||
assert.ok(after.filter(call => /^agent-device(-|$)/.test(call.name) && call.command === 'open').length <= 1, 'no further route is opened');
|
||||
});
|
||||
|
||||
test('Ctrl+C stops the review, and the checkouts are removed while its files are kept', async t => {
|
||||
|
||||
@@ -0,0 +1,35 @@
|
||||
import assert from "node:assert/strict";
|
||||
import test from "node:test";
|
||||
import { tsImport } from "tsx/esm/api";
|
||||
|
||||
const { mapFrame, MAP_SCREEN_WIDTH, MAP_SCREEN_HEIGHT } = await tsImport("../../viewer/src/utils/map-frame.ts", import.meta.url);
|
||||
const { typicalScreenshotSize } = await tsImport("../../viewer/src/utils/screen-images.ts", import.meta.url);
|
||||
|
||||
const size = (imageWidth, imageHeight) => ({ imageWidth, imageHeight });
|
||||
|
||||
test("phone screenshots keep the map's default card", () => {
|
||||
for (const phone of [size(402, 874), size(1206, 2622), size(720, 1600), undefined]) {
|
||||
const frame = mapFrame(phone);
|
||||
assert.equal(frame.width, MAP_SCREEN_WIDTH);
|
||||
assert.equal(frame.height, MAP_SCREEN_HEIGHT);
|
||||
}
|
||||
assert.deepEqual(mapFrame(size(720, 1600)).screen, { width: 390, height: 845 }, "a missing screenshot keeps the default phone frame");
|
||||
assert.deepEqual(mapFrame(size(1398, 2034)).screen, { width: 1398, height: 2034 }, "a missing screenshot on a wider screen is framed like the run's");
|
||||
});
|
||||
|
||||
test("a wider screen gets a card in its own shape with about the same screen area", () => {
|
||||
// iPhone Duo screenshots are 1398 × 2034 pixels.
|
||||
const duo = mapFrame(size(1398, 2034));
|
||||
const slotHeight = duo.height - 34;
|
||||
assert.ok(Math.abs(duo.width / slotHeight - 1398 / 2034) < 0.01, JSON.stringify(duo));
|
||||
const phoneArea = mapFrame(size(402, 874));
|
||||
const area = duo.width * slotHeight, defaultArea = (phoneArea.height - 34) ** 2 * (9 / 19.5);
|
||||
assert.ok(Math.abs(area / defaultArea - 1) < 0.02, `${area} vs ${defaultArea}`);
|
||||
assert.ok(duo.width > MAP_SCREEN_WIDTH && duo.height < MAP_SCREEN_HEIGHT);
|
||||
});
|
||||
|
||||
test("a run's screenshot shape is its median one, and unknown sizes do not count", () => {
|
||||
const duo = size(1398, 2034);
|
||||
assert.deepEqual(typicalScreenshotSize([duo, undefined, duo, size(1398, 3000), duo]), duo);
|
||||
assert.equal(typicalScreenshotSize([undefined, undefined]), undefined);
|
||||
});
|
||||
@@ -7,6 +7,7 @@ import {
|
||||
} from "../../dist/review/runtime-adapter.js";
|
||||
import { projectRuntimeEvidence } from "../../dist/review/runtime-evidence.js";
|
||||
import { AGENT_DEVICE_VERSION } from "../../dist/capture/run.js";
|
||||
import { ARGENT_VERSION } from "../../dist/shared/argent-version.js";
|
||||
|
||||
const sha = "a".repeat(40);
|
||||
|
||||
@@ -288,3 +289,11 @@ test("fails closed on provenance, environment, surface, and capture mismatches",
|
||||
/visual fingerprint is missing/,
|
||||
);
|
||||
});
|
||||
|
||||
test("an Argent capture's execution context names Argent and its pinned version, never another pairing", () => {
|
||||
const argent = execution({ controller: "argent", controllerPackageVersion: ARGENT_VERSION });
|
||||
assert.deepEqual(parseRuntimeExecutionContext(argent), argent);
|
||||
assert.throws(() => parseRuntimeExecutionContext(execution({ controller: "argent" })), /Controller package version.*invalid/i);
|
||||
assert.throws(() => parseRuntimeExecutionContext(execution({ controllerPackageVersion: ARGENT_VERSION })), /Controller package version.*invalid/i);
|
||||
assert.throws(() => parseRuntimeExecutionContext(execution({ controller: "appium" })), /Runtime controller.*invalid/i);
|
||||
});
|
||||
@@ -25,6 +25,8 @@ export type ScreenScreenshotCardProps = {
|
||||
ariaPressed?: boolean;
|
||||
imageWidth?: number;
|
||||
imageHeight?: number;
|
||||
/** The frame of a screen without a screenshot: its run's screenshots, so it lines up beside them. */
|
||||
placeholderSize?: { width: number; height: number };
|
||||
loading?: "eager" | "lazy";
|
||||
leading?: ReactNode;
|
||||
trailing?: ReactNode;
|
||||
@@ -42,7 +44,7 @@ export function ScreenScreenshotCard(props: ScreenScreenshotCardProps) {
|
||||
// frame it waited in, and a screen without one is framed like a phone screenshot beside it.
|
||||
const frame = props.screenshot && props.imageWidth && props.imageHeight
|
||||
? { width: props.imageWidth, height: props.imageHeight }
|
||||
: DEFAULT_SCREENSHOT_SIZE;
|
||||
: props.placeholderSize ?? DEFAULT_SCREENSHOT_SIZE;
|
||||
const missing = (
|
||||
<span
|
||||
className="image-placeholder"
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
import { useEffect, useMemo, useRef, useState, type CSSProperties, type KeyboardEvent, type ReactNode } from "react";
|
||||
import { ChevronRight, ChevronsDownUp, ChevronsUpDown, ListTree } from "lucide-react";
|
||||
import { artifactUrl, isLaunchScreen, type ExploreMap, type MapIndex, type Screen } from "../../utils/model";
|
||||
import { primaryScreenshotForScreen, screenshotSize } from "../../utils/screen-images";
|
||||
import { primaryScreenshotForScreen, screenshotSize, typicalScreenshotSize, type ScreenshotSize } from "../../utils/screen-images";
|
||||
import { diffClass, type BuildDiff, type DiffStatus } from "../../utils/build-diff";
|
||||
import { focusStatusOf, isCapturedChange } from "../../utils/changed-screens";
|
||||
import { displayPathForScreen, screenLabel } from "../../utils/screen-path";
|
||||
@@ -10,6 +10,7 @@ import type { Appearance } from "../../utils/appearance";
|
||||
import type { FocusRequest, FocusStatus } from "../../utils/navigation";
|
||||
import { shortcutsLive } from "../../utils/shortcuts";
|
||||
import { HOLD_INITIAL_DELAY_MS, holdIntervalMs } from "../../utils/key-hold";
|
||||
import { placeholderScreen } from "../../utils/map-frame";
|
||||
import { ScreenScreenshotCard } from "../canvas/screen-screenshot-card";
|
||||
import { useCanvasVisibleFrame } from "../canvas/visible-frame-provider";
|
||||
import { PhoneSheet } from "../phone/phone-chrome";
|
||||
@@ -114,6 +115,8 @@ function ScreenCell(props: {
|
||||
via?: string | undefined;
|
||||
selected: boolean;
|
||||
dimmed: boolean;
|
||||
/** The run's screenshot shape, which a screen without a screenshot is framed in. */
|
||||
typicalSize?: ScreenshotSize | undefined;
|
||||
onSelect: () => void;
|
||||
}) {
|
||||
const artifact = primaryScreenshotForScreen(props.screen, props.index);
|
||||
@@ -130,6 +133,7 @@ function ScreenCell(props: {
|
||||
{...(props.index.plainTitles ? { plainTitle: true } : {})}
|
||||
{...(url ? { screenshot: url } : {})}
|
||||
{...(size ? size : {})}
|
||||
placeholderSize={placeholderScreen(props.typicalSize)}
|
||||
{...(status ? { diff: status } : {})}
|
||||
{...(props.diff?.screens.get(props.screen.id)?.accessibilityOnly ? { accessibilityOnly: true } : {})}
|
||||
selected={props.selected}
|
||||
@@ -233,6 +237,10 @@ export function ScreensView(props: ScreensViewProps) {
|
||||
() => screenTree(props.map.screens, props.index, props.routeFiles),
|
||||
[props.index, props.map.screens, props.routeFiles],
|
||||
);
|
||||
const typicalSize = useMemo(
|
||||
() => typicalScreenshotSize(props.map.screens.map(screen => screenshotSize(primaryScreenshotForScreen(screen, props.index)))),
|
||||
[props.index, props.map.screens],
|
||||
);
|
||||
const changedIds = useMemo(
|
||||
() => new Set(props.map.screens
|
||||
.filter(screen => isChanged(props.diff, screen.id) || (props.changedElsewhere?.get(screen.id)?.length ?? 0) > 0)
|
||||
@@ -453,6 +461,7 @@ export function ScreensView(props: ScreensViewProps) {
|
||||
<ScreenCell key={id} screen={screen} index={props.index} diff={props.diff}
|
||||
elsewhere={isChanged(props.diff, id) ? undefined : props.changedElsewhere?.get(id)}
|
||||
via={tree.via.get(id)}
|
||||
typicalSize={typicalSize}
|
||||
selected={props.selectedScreenId === id}
|
||||
dimmed={Boolean(props.focus?.length) && !props.focus!.some((state) => state === focusStatusOf(props.diff?.screens.get(id)))}
|
||||
onSelect={() => props.onSelectScreen(id)} />
|
||||
|
||||
@@ -18,7 +18,8 @@ import {
|
||||
type ProjectionNode,
|
||||
} from "../../utils/graph-model";
|
||||
import { artifactUrl, isLaunchScreen, type ExploreMap, type MapIndex, type Screen } from "../../utils/model";
|
||||
import { primaryScreenshotForScreen, screenshotSize, type ScreenshotSize } from "../../utils/screen-images";
|
||||
import { primaryScreenshotForScreen, screenshotSize, typicalScreenshotSize, type ScreenshotSize } from "../../utils/screen-images";
|
||||
import { mapFrame, type MapFrame } from "../../utils/map-frame";
|
||||
import type { BuildDiff, DiffStatus } from "../../utils/build-diff";
|
||||
import { CANVAS_MAX_ZOOM } from "../../utils/canvas-zoom";
|
||||
import { usePhoneLayout } from "../../utils/phone-layout";
|
||||
@@ -28,10 +29,6 @@ import { displayPathForScreen } from "../../utils/screen-path";
|
||||
import { shortcutsLive } from "../../utils/shortcuts";
|
||||
import { mapKeyDirection, mapKeyTarget } from "../../utils/map-keyboard";
|
||||
|
||||
// The map is an inspection surface, not a thumbnail cloud. These dimensions preserve the
|
||||
// original phone aspect and leave enough vertical room for a wrapped title.
|
||||
const MAP_SCREEN_WIDTH = 184;
|
||||
const MAP_SCREEN_HEIGHT = 420;
|
||||
const HOVER_CLEAR_DELAY = 180;
|
||||
const MAP_LAYOUT_REVISION = "flat-v1";
|
||||
const MAP_FIT_VIEW_OPTIONS = {
|
||||
@@ -58,6 +55,7 @@ type ScreenNodeData = {
|
||||
missingReason?: string;
|
||||
highlighted: boolean;
|
||||
direction: MapDirection;
|
||||
frame: MapFrame;
|
||||
diff?: DiffStatus;
|
||||
accessibilityOnly?: boolean;
|
||||
projectionDelayMs?: number;
|
||||
@@ -74,6 +72,8 @@ type ProjectedStructure = {
|
||||
groups: ConnectionGroup[];
|
||||
positions: Map<string, Point>;
|
||||
screenshots: Map<string, MapScreenshot | undefined>;
|
||||
/** Every card's size, from the shape of the run's screenshots. */
|
||||
frame: MapFrame;
|
||||
screenNotes: Map<string, string>;
|
||||
hoverPaths: Map<string, { nodeIds: Set<string>; edgeIds: Set<string> }>;
|
||||
primaryEdgeKeys: Set<string>;
|
||||
@@ -98,6 +98,8 @@ function ScreenNodeCard({ data, selected }: NodeProps<ScreenGraphNode>) {
|
||||
selected={selected}
|
||||
highlighted={data.highlighted}
|
||||
style={{
|
||||
"--map-screen-width": `${data.frame.width}px`,
|
||||
"--map-screen-height": `${data.frame.height}px`,
|
||||
"--projection-delay": `${data.projectionDelayMs ?? 0}ms`,
|
||||
"--projection-scale": data.projectionScreenScale ?? 1,
|
||||
...(data.projectionScreenScale !== undefined
|
||||
@@ -107,8 +109,10 @@ function ScreenNodeCard({ data, selected }: NodeProps<ScreenGraphNode>) {
|
||||
ariaLabel={`Open ${data.screen.title}`}
|
||||
ariaPressed={selected}
|
||||
// The slot's own proportions stand in only when the screenshot's size is not recorded.
|
||||
imageWidth={data.screenshotSize?.imageWidth ?? MAP_SCREEN_WIDTH - 2}
|
||||
imageHeight={data.screenshotSize?.imageHeight ?? MAP_SCREEN_HEIGHT - 48}
|
||||
// A screenshot of unrecorded size, or none, is framed like the run's other screenshots.
|
||||
imageWidth={data.screenshotSize?.imageWidth ?? data.frame.screen.width}
|
||||
imageHeight={data.screenshotSize?.imageHeight ?? data.frame.screen.height}
|
||||
placeholderSize={data.frame.screen}
|
||||
loading="lazy"
|
||||
leading={<Handle type="target" position={horizontal ? Position.Left : Position.Top} className="graph-handle" />}
|
||||
trailing={<Handle type="source" position={horizontal ? Position.Right : Position.Bottom} className="graph-handle" />}
|
||||
@@ -128,8 +132,8 @@ function conciseActionLabel(label: string): string | undefined {
|
||||
return /^(continue|next|open)$/i.test(concise) ? undefined : concise;
|
||||
}
|
||||
|
||||
function nodeDimensions(_node: ProjectionNode) {
|
||||
return { width: MAP_SCREEN_WIDTH, height: MAP_SCREEN_HEIGHT };
|
||||
function nodeDimensions(frame: MapFrame) {
|
||||
return { width: frame.width, height: frame.height };
|
||||
}
|
||||
|
||||
function adjacency(groups: readonly ConnectionGroup[]) {
|
||||
@@ -195,7 +199,7 @@ function hoverNeighborhood(nodes: readonly ProjectionNode[], groups: readonly Co
|
||||
* One card per screen, layered by how many transitions it took to reach it from the start screen;
|
||||
* a screen never reached by a recorded transition joins the last layer. Edges are the transitions.
|
||||
*/
|
||||
function flatPositions(projection: GraphProjection): { positions: Map<string, Point>; horizontal: boolean } {
|
||||
function flatPositions(projection: GraphProjection, frame: MapFrame): { positions: Map<string, Point>; horizontal: boolean } {
|
||||
const screenNodes = projection.nodes.filter((node): node is Extract<ProjectionNode, { kind: "screen" }> => node.kind === "screen");
|
||||
const ids = new Set(screenNodes.map((node) => node.id));
|
||||
const outgoing = new Map<string, string[]>();
|
||||
@@ -225,8 +229,8 @@ function flatPositions(projection: GraphProjection): { positions: Map<string, Po
|
||||
}
|
||||
// Lay the deeper axis along the wider screen axis: a long chain of taps reads left to right.
|
||||
const horizontal = layers.size > Math.max(...[...layers.values()].map((members) => members.length));
|
||||
const alongPitch = (horizontal ? MAP_SCREEN_WIDTH : MAP_SCREEN_HEIGHT) + 160;
|
||||
const acrossPitch = (horizontal ? MAP_SCREEN_HEIGHT : MAP_SCREEN_WIDTH) + 56;
|
||||
const alongPitch = (horizontal ? frame.width : frame.height) + 160;
|
||||
const acrossPitch = (horizontal ? frame.height : frame.width) + 56;
|
||||
const positions = new Map<string, Point>();
|
||||
// Order each layer by where its parents sit in the previous one so edges cross as little as possible.
|
||||
const incoming = new Map<string, string[]>();
|
||||
@@ -252,18 +256,21 @@ function flatPositions(projection: GraphProjection): { positions: Map<string, Po
|
||||
}
|
||||
|
||||
function projectedStructure(projection: GraphProjection, index: MapIndex, plainTitles: boolean): ProjectedStructure {
|
||||
const { positions, horizontal } = flatPositions(projection);
|
||||
const screenshots = new Map(projection.nodes.map((node) => {
|
||||
const artifact = primaryScreenshotForScreen(node.screen, index);
|
||||
const url = artifactUrl(artifact);
|
||||
const size = screenshotSize(artifact);
|
||||
return [node.id, url ? { url, ...(size ? { size } : {}) } : undefined] as const;
|
||||
}));
|
||||
const frame = mapFrame(typicalScreenshotSize([...screenshots.values()].map((screenshot) => screenshot?.size)));
|
||||
const { positions, horizontal } = flatPositions(projection, frame);
|
||||
return {
|
||||
screenNotes: index.screenNotes,
|
||||
projectionNodes: projection.nodes,
|
||||
groups: projection.groups,
|
||||
positions,
|
||||
screenshots: new Map(projection.nodes.map((node) => {
|
||||
const artifact = primaryScreenshotForScreen(node.screen, index);
|
||||
const url = artifactUrl(artifact);
|
||||
const size = screenshotSize(artifact);
|
||||
return [node.id, url ? { url, ...(size ? { size } : {}) } : undefined] as const;
|
||||
})),
|
||||
frame,
|
||||
screenshots,
|
||||
hoverPaths: hoverNeighborhood(projection.nodes, projection.groups),
|
||||
primaryEdgeKeys: spanningEdges(projection.nodes, projection.groups),
|
||||
horizontal,
|
||||
@@ -282,7 +289,7 @@ function projectionElements(
|
||||
): { nodes: CanvasGraphNode[]; edges: TransitionGraphEdge[] } {
|
||||
const nodes: CanvasGraphNode[] = structure.projectionNodes.map((projectionNode) => {
|
||||
const point = structure.positions.get(projectionNode.id) ?? { x: 0, y: 0 };
|
||||
const size = nodeDimensions(projectionNode);
|
||||
const size = nodeDimensions(structure.frame);
|
||||
const position = { x: point.x - size.width / 2, y: point.y - size.height / 2 };
|
||||
const screen = projectionNode.screen;
|
||||
const screenshot = structure.screenshots.get(screen.id);
|
||||
@@ -319,6 +326,7 @@ function projectionElements(
|
||||
...(!screenshot && structure.screenNotes.get(screen.id) ? { missingReason: structure.screenNotes.get(screen.id)! } : {}),
|
||||
highlighted,
|
||||
direction: structure.horizontal ? "LR" : "TB",
|
||||
frame: structure.frame,
|
||||
...(status ? { diff: status } : {}),
|
||||
...(diff?.screens.get(screen.id)?.accessibilityOnly ? { accessibilityOnly: true } : {}),
|
||||
projectionMotion,
|
||||
|
||||
@@ -258,7 +258,8 @@ function sidePayload(review: PublicReview, side: Side): { map: ExploreMap; cover
|
||||
// Reports published before Android support carry no platform: they are iOS.
|
||||
platform: review.runtime.platform ?? "ios",
|
||||
...(review.runtime.platforms && review.runtime.platforms.length > 1 ? { platforms: [...review.runtime.platforms] } : {}),
|
||||
controller: "agent-device",
|
||||
// Reviews name the controller only when it is not agent-device.
|
||||
controller: review.runtime.controller ?? "agent-device",
|
||||
status: "complete",
|
||||
createdAt: times[0] ?? review.createdAt,
|
||||
updatedAt: review.createdAt,
|
||||
|
||||
@@ -565,9 +565,10 @@ code {
|
||||
background: transparent;
|
||||
text-align: inherit;
|
||||
}
|
||||
/* A map sizes its cards to the shape of the run's screenshots (semantic-map.tsx mapFrame). */
|
||||
.screen-node {
|
||||
width: 184px;
|
||||
height: 420px;
|
||||
width: var(--map-screen-width, 184px);
|
||||
height: var(--map-screen-height, 420px);
|
||||
cursor: grab;
|
||||
}
|
||||
.screen-node:active { cursor: grabbing; }
|
||||
@@ -846,8 +847,8 @@ code {
|
||||
/* Map screens retain the original inspectable phone frame. Semantic hierarchy reduces how many
|
||||
screens are present; it must not make the screens themselves unreadable. */
|
||||
.map-surface .screen-node {
|
||||
width: 184px;
|
||||
height: 420px;
|
||||
width: var(--map-screen-width, 184px);
|
||||
height: var(--map-screen-height, 420px);
|
||||
gap: 14px;
|
||||
}
|
||||
.map-surface .screen-node-heading { min-height: 20px; padding: 0 4px; }
|
||||
|
||||
@@ -0,0 +1,40 @@
|
||||
import { DEFAULT_SCREENSHOT_RATIO, DEFAULT_SCREENSHOT_SIZE } from "../components/shared/screenshot-image";
|
||||
import type { ScreenshotSize } from "./screen-images";
|
||||
|
||||
// The map is an inspection surface, not a thumbnail cloud. A card is a phone-shaped screenshot
|
||||
// under its route heading, with enough vertical room for a wrapped title.
|
||||
export const MAP_SCREEN_WIDTH = 184;
|
||||
export const MAP_SCREEN_HEIGHT = 420;
|
||||
// The route heading (20px) and the gap under it (14px) sit above the screenshot slot.
|
||||
const MAP_HEADING_HEIGHT = 34;
|
||||
// A phone screenshot fills the slot at its default proportions; a screen of another shape keeps that area.
|
||||
const MAP_SLOT_AREA = (MAP_SCREEN_HEIGHT - MAP_HEADING_HEIGHT) ** 2 * DEFAULT_SCREENSHOT_RATIO;
|
||||
|
||||
/** A map card's size, and the screenshot size a card frames when its own is not known (or missing). */
|
||||
export type MapFrame = { width: number; height: number; screen: { width: number; height: number } };
|
||||
|
||||
/**
|
||||
* Cards take the shape of the run's screenshots, so a screenshot fills its slot and the connection ports
|
||||
* on the slot's edges sit on the screenshot's border. Phones within a tenth of the default proportions keep
|
||||
* the default card; a wider screen, such as a foldable's, gets a card of the same screen area in its shape.
|
||||
*/
|
||||
export function mapFrame(size: ScreenshotSize | undefined): MapFrame {
|
||||
const screen = placeholderScreen(size);
|
||||
if (phoneShaped(size)) return { width: MAP_SCREEN_WIDTH, height: MAP_SCREEN_HEIGHT, screen };
|
||||
const ratio = screen.width / screen.height;
|
||||
const slotWidth = Math.round(Math.sqrt(MAP_SLOT_AREA * ratio));
|
||||
return { width: slotWidth, height: Math.round(slotWidth / ratio) + MAP_HEADING_HEIGHT, screen };
|
||||
}
|
||||
|
||||
function phoneShaped(size: ScreenshotSize | undefined): boolean {
|
||||
return !size || Math.abs(size.imageWidth / size.imageHeight / DEFAULT_SCREENSHOT_RATIO - 1) <= 0.1;
|
||||
}
|
||||
|
||||
/**
|
||||
* The frame of a screen without a screenshot, given its run's typical screenshot size: the default phone
|
||||
* frame in a phone-shaped run, as before, so it lines up with phone screenshots of any exact size; the run's
|
||||
* own shape otherwise.
|
||||
*/
|
||||
export function placeholderScreen(size: ScreenshotSize | undefined): { width: number; height: number } {
|
||||
return size && !phoneShaped(size) ? { width: size.imageWidth, height: size.imageHeight } : { ...DEFAULT_SCREENSHOT_SIZE };
|
||||
}
|
||||
@@ -4,6 +4,16 @@ import type { MapIndex } from "./model";
|
||||
/** The pixel size a screenshot was captured at, in the canvas card's prop names. */
|
||||
export type ScreenshotSize = { imageWidth: number; imageHeight: number };
|
||||
|
||||
/**
|
||||
* The shape a run's screenshots share: the median one, so a stray size (a launch frame, a failed read)
|
||||
* does not decide it. One device captures every screenshot of a run, so they are normally all alike.
|
||||
*/
|
||||
export function typicalScreenshotSize(sizes: readonly (ScreenshotSize | undefined)[]): ScreenshotSize | undefined {
|
||||
const known = sizes.filter((size): size is ScreenshotSize => !!size)
|
||||
.sort((left, right) => left.imageWidth / left.imageHeight - right.imageWidth / right.imageHeight);
|
||||
return known[Math.floor((known.length - 1) / 2)];
|
||||
}
|
||||
|
||||
/**
|
||||
* A screenshot's recorded size, when the map has one. A canvas frame waiting for the image takes
|
||||
* this shape, so it stays put when the pixels arrive.
|
||||
|
||||
Reference in new issue
Block a user