Compare commits

..
Author SHA1 Message Date
Brent Vatne c919c42cac Explorer: judge a tap by the control under it and by its identifier, and name --allow-destructive in a refusal
- riskOf splits identifiers into words before matching, so btn_delete, deleteAccount and
  sign-out read as destructive; \b does not split them.
- A coordinate tap is judged by the smallest hittable control under the point, by its own
  label and identifier, as well as by the target the model wrote. A tap over no control is
  still allowed and recorded as unknown.
- A control allowed by its label stays allowed however it is targeted, even when its
  identifier reads as risky.
- A refusal tells whoever runs Explore that --allow-destructive allows a safe control; it
  reaches them through flow and replay results.
- The README and the explore-binary skill say that a secret is recognised in the
  accessibility tree only, so one drawn without an accessible label is not.
2026-10-24 14:00:32 -07:00
14 changed files with 93 additions and 193 deletions

No files matched your search

+3 -3
View File
@@ -155,7 +155,7 @@ npx @expo/explore capture --base v1.3.0 --head v1.4.0 --scope all --upload
- Your checkout, index and branches are never touched. Your uncommitted changes, untracked files included, are reviewed as `eas build` would upload them; `--committed`, or `cli.requireCommit: true` in `eas.json`, leaves them out.
- Installs run without credential environment variables, which keeps tokens out of reach of a registry a commit's `.npmrc` names; that is not a sandbox. A registry that needs `${NPM_TOKEN}` in the project's `.npmrc` must be authenticated in your own `~/.npmrc`.
- Captures are cached in `~/.cache/expo-explore`, so the same base is not captured twice (`--no-cache` skips it); a capture unused for 30 days goes, and the cache stays under 2 GB. Ctrl+C stops the run's simulator sessions and local devices; when a run is stopped harder than that, the next local run stops what it left running.
- Like a CI review, it builds on EAS (reusing a matching build) and, unless it captures on a local simulator, runs EAS Simulator sessions: expect several minutes and EAS usage. A terminal that supports [OSC 7501](https://superlogical.com/rex/docs/build/program-status) shows whether the run is working, done or failed while you are in another tab; `explore:binary`, `report:upload` and `doctor --capture` report it too.
- Like a CI review, it builds on EAS (reusing a matching build) and, unless it captures on a local simulator, runs EAS Simulator sessions: expect several minutes and EAS usage.
- Saved runs take up to 2 GB in all, the oldest going first. `reports add <report.zip>` keeps a report you downloaded, such as a PR's `explore-review` artifact.
</details>
@@ -174,7 +174,7 @@ Pointed to a build, the [quick start](#quick-start) maps every screen of it, wit
- A simulator build. A device `.ipa`, an `.aab`, an unsigned APK, or an APK without native libraries for the emulator (x86_64 on EAS Simulator, `arm64-v8a` locally on Apple silicon; a universal APK has both) is rejected before a device starts.
- Platform, bundle id, name, and version are read from the build; you pass nothing else.
- A run stops after 15 minutes, 40 screens, or 150 actions (`--max-duration-minutes`, `--max-screens`, `--max-actions`).
- Buttons that delete, pay, sign out, send, or leave the app are never tapped. `--allow-destructive "Reset filters"` allows one by its exact label.
- Buttons that delete, pay, sign out, send, or leave the app are never tapped. Explore judges a control by its label and its identifier (`btn_delete`, `deleteAccount`), including one tapped by position. `--allow-destructive "Reset filters"` allows one by its exact label.
- `--hints "…"` tells the model what to focus on or how to sign in ([details](#sign-in-and-other-app-state)).
- On EAS Simulator the report is hosted, and the link lasts as long as its EAS Hosting deployment (see [report access](docs/private-review.md#hosted-previews)); `--no-upload` keeps it local. On a local simulator it opens in the local Viewer (`--no-open` or `--json` skips that; `view --dir <folder>` opens it later), and `--upload` hosts it, which needs an EAS login. `--json` prints the result for scripts.
- For a link that stays the same from run to run, pass `--alias NAME` and set `EXPLORE_PREVIEW_TOKEN` to a fixed token of 32 characters from a–z and 2–7 (`LC_ALL=C tr -dc a-z2-7 </dev/urandom | head -c 32`).
@@ -508,7 +508,7 @@ npx @expo/explore explore:binary ./my-app.app \
--hints "Sign in as [email protected] with {{secret:APP_TEST_PASSWORD}}"
```
The model only sees the reference, and Explore types the value. The value is redacted everywhere, and a screen that shows it gets no screenshot, so keep non-sensitive values like a test email as plain text. In CI, store the value as a repository secret instead.
The model only sees the reference, and Explore types the value. The value is redacted everywhere, and a screen that shows it gets no screenshot, so keep non-sensitive values like a test email as plain text. Explore finds the value in the screen's accessibility tree; a screen that draws it without exposing it there (in a canvas or an image) is not recognised. In CI, store the value as a repository secret instead.
If the sign-in can't be typed (one-time codes, email links, Sign in with Apple or Google), sign in by hand on a session and run `explore:session`. Explore never taps Sign out.
+2 -2
View File
@@ -1,12 +1,12 @@
{
"name": "@expo/explore",
"version": "0.23.0",
"version": "0.22.1",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "@expo/explore",
"version": "0.23.0",
"version": "0.22.1",
"license": "MIT",
"dependencies": {
"@expo/repack-app": "0.10.1",
+1 -1
View File
@@ -1,6 +1,6 @@
{
"name": "@expo/explore",
"version": "0.23.0",
"version": "0.22.1",
"description": "Source-driven mobile app maps, deterministic CI capture, and visual reviews",
"license": "MIT",
"type": "module",
+2 -2
View File
@@ -55,7 +55,7 @@ set -a && . ./.env.explore && set +a && npx @expo/explore explore:binary ./app.a
--hints "Sign in with {{secret:APP_TEST_EMAIL}} and {{secret:APP_TEST_PASSWORD}}, then explore the signed-in app"
```
The model only ever sees the reference; Explore types the value into the field. The value is redacted from the map, the report and errors, and a frame that shows it (the filled-in form, or a profile screen that displays the email) is kept without a screenshot. So make only what is sensitive a secret: a dedicated test email can go in the hints as plain text, and then the account screen keeps its picture. A reference to a variable that is not set fails before a session starts (`EXPLORATION_SECRET_MISSING`); provider keys, `EXPO_TOKEN` and CI variables cannot be referenced.
The model only ever sees the reference; Explore types the value into the field. The value is redacted from the map, the report and errors, and a frame that shows it (the filled-in form, or a profile screen that displays the email) is kept without a screenshot. Explore finds the value in the accessibility tree, so a value drawn without an accessible label (in a canvas or an image) is not recognised. So make only what is sensitive a secret: a dedicated test email can go in the hints as plain text, and then the account screen keeps its picture. A reference to a variable that is not set fails before a session starts (`EXPLORATION_SECRET_MISSING`); provider keys, `EXPO_TOKEN` and CI variables cannot be referenced.
**When a sign-in cannot be typed** (a one-time code, an email link, Sign in with Apple or Google, a captcha): sign in by hand on a session and use `explore:session`. Sign out is never tapped, so the run stays signed in.
@@ -64,7 +64,7 @@ The model only ever sees the reference; Explore types the value into the field.
- Onboarding: `--launch-url` to a screen past it, or hints such as "skip the tour with Skip".
- Screens that need data: a test account that already has it, and hints naming where it is ("open the first project").
- Permission prompts are denied. To explore what is behind one, allow it by hand on a session first, then `explore:session`.
- Purchases, deletes, sends and sign out are blocked. `--allow-destructive "Label"` allows one control by label; a paywall needs an account that already has the entitlement.
- Purchases, deletes, sends and sign out are blocked, judged by a control's label and its identifier, including a control tapped by position. `--allow-destructive "Label"` allows one control by label; a paywall needs an account that already has the entitlement.
- A large app: raise the budgets (`--max-duration-minutes`, `--max-screens`, `--max-actions`; see [What happens](#what-happens)) and use the hints to say what to cover first.
## Already have a session? `explore:session`
+30 -11
View File
@@ -69,6 +69,8 @@ export type BlackBoxExplorerResult = {
const DESTRUCTIVE = /\b(delete|remove|erase|reset|wipe|clear all|sign ?out|log ?out|unsubscribe|cancel subscription|deactivate|close account|purchase|buy|subscribe|pay|checkout|send|post|publish|report|block|submit order|confirm order|place order)\b/i;
// A bare "Map" is usually the app's own map tab or screen; only a named maps app or directions leave the app.
const EXTERNAL = /\b(open in|safari|chrome|browser|app store|play store|share|mail|call|sms|(apple|google) maps|directions)\b/i;
/** For the person running Explore, who sees blocked steps in flow and replay results; the model cannot pass it. */
const ALLOW_HINT = "(Whoever runs Explore can allow a safe control with --allow-destructive and its exact label.)";
const VOLATILE = /\d|[:%$€£]|\b(am|pm)\b/gi;
const INTERACTIVE = new Set(["button", "link", "cell", "switch", "tab", "menuitem", "textfield", "securetextfield", "searchfield", "textview", "edittext", "slider", "checkbox", "radiobutton", "segmentedcontrol", "toggle"]);
@@ -185,13 +187,20 @@ function isInteractive(node: Record<string, unknown>): boolean {
return traits.some(trait => /button|link|tab|adjustable/i.test(trait));
}
const allowed = (label: string, allow: readonly string[]) => allow.some(item => item.toLowerCase() === label.toLowerCase());
export function riskOf(label: string, allow: readonly string[]): ActionRisk {
if (allow.some(allowed => allowed.toLowerCase() === label.toLowerCase())) return "safe";
if (DESTRUCTIVE.test(label)) return "destructive";
if (EXTERNAL.test(label)) return "external";
if (allowed(label, allow)) return "safe";
// Identifiers join their words (btn_delete, deleteAccount, sign-out), which \b does not split.
const words = label.replace(/(\p{Ll}|\d)(\p{Lu})/gu, "$1 $2").replace(/[_.-]+/g, " ");
if (DESTRUCTIVE.test(words)) return "destructive";
if (EXTERNAL.test(words)) return "external";
return "safe";
}
const RISK_ORDER: readonly ActionRisk[] = ["safe", "unknown", "external", "destructive"];
const worstRisk = (...risks: ActionRisk[]): ActionRisk => risks.reduce((worst, risk) => RISK_ORDER.indexOf(risk) > RISK_ORDER.indexOf(worst) ? risk : worst, "safe");
/** Structure plus stable text, with values and numerals masked, so a clock tick or a counter does not create a new screen. */
/**
* A text field's label is whatever it shows: its placeholder while empty (Android sets `hintShowing`), then the typed text.
@@ -660,7 +669,11 @@ export async function runBlackBoxExploration(options: BlackBoxExplorerOptions):
if (input.frameId !== undefined) {
const point = { action: "tap" as const, frameId: text(input.frameId, "frameId", 256), x: Number(input.x), y: Number(input.y) };
const target = input.target !== undefined ? cleanLabel(text(input.target, "target", 80)) : "";
return { action: point, kind: "press", label: target || placeUnder(point) || `tap ${point.x.toFixed(2)},${point.y.toFixed(2)}`, risk: target ? riskOf(target, allow) : "unknown" };
// The control under the point is judged by its own label and identifier too, not only by the model's description of it.
const under = nodeUnder(point), underLabel = str(under?.label);
const risk = underLabel && allowed(underLabel, allow) ? "safe"
: worstRisk(target ? riskOf(target, allow) : "unknown", ...[underLabel, str(under?.identifier)].flatMap(name => name ? [riskOf(name, allow)] : []));
return { action: point, kind: "press", label: target || placeUnder(point) || `tap ${point.x.toFixed(2)},${point.y.toFixed(2)}`, risk };
}
if (!selector) throw failure("AGENT_ACTION_INVALID", "tap needs a label, an identifier, or frame coordinates.");
return { action: { action: "tap", ...selector } as BlackBoxAction, kind: "press", label, risk };
@@ -714,13 +727,12 @@ export async function runBlackBoxExploration(options: BlackBoxExplorerOptions):
return { action: "tap", frameId: latest.frameId ?? "current", x: (bounds.x + bounds.width / 2) / extent.width, y: (bounds.y + bounds.height / 2) / extent.height };
};
/** A coordinate tap the model did not describe, on a node the map has no name for (an icon-font button in a header), is
* named by what it is and where it sits: "icon button, top right" says more than the coordinates did. */
const placeUnder = (point: { x: number; y: number }): string | undefined => {
/** The smallest hittable control at a frame point in the latest tree, whether or not the map has recorded it. */
const nodeUnder = (point: { x: number; y: number }): Record<string, unknown> | undefined => {
const extent = latest ? frameExtent(latest.nodes) : undefined;
if (!extent) return undefined;
const x = point.x * extent.width, y = point.y * extent.height;
const under = latest!.nodes
return latest!.nodes
.filter(node => {
const rect = node.rect as { x: number; y: number; width: number; height: number } | undefined;
return !!rect && node.hittable === true && x >= rect.x && x <= rect.x + rect.width && y >= rect.y && y <= rect.y + rect.height
@@ -730,6 +742,12 @@ export async function runBlackBoxExploration(options: BlackBoxExplorerOptions):
const ra = a.rect as { width: number; height: number }, rb = b.rect as { width: number; height: number };
return ra.width * ra.height - rb.width * rb.height;
})[0];
};
/** A coordinate tap the model did not describe, on a node the map has no name for (an icon-font button in a header), is
* named by what it is and where it sits: "icon button, top right" says more than the coordinates did. */
const placeUnder = (point: { x: number; y: number }): string | undefined => {
const under = nodeUnder(point);
if (!under) return undefined;
const role = roleOf(under);
const label = str(under.label) ?? "";
@@ -805,7 +823,8 @@ export async function runBlackBoxExploration(options: BlackBoxExplorerOptions):
: elementUnder(chosen.action, fromScreenId);
const { action, kind } = chosen;
const label = named ? named.label : chosen.label;
const risk = named && chosen.risk !== "destructive" && chosen.risk !== "external" ? riskOf(named.label, allow) : chosen.risk;
// A control allowed by its label is allowed however it is targeted, even when its identifier reads as risky.
const risk = named && allowed(named.label, allow) ? "safe" : named && chosen.risk !== "destructive" && chosen.risk !== "external" ? riskOf(named.label, allow) : chosen.risk;
const startedAt = timestamp();
const attemptId = `att_${randomUUID().slice(0, 12)}`;
const matched = map.frontier.find(item => item.status === "pending" && item.screenId === fromScreenId && item.actionKind === kind
@@ -817,8 +836,8 @@ export async function runBlackBoxExploration(options: BlackBoxExplorerOptions):
startedAt, completedAt: timestamp(), reason });
await persist();
return toolResult({ ok: false, blocked: true, reason: risk === "destructive"
? `"${label}" looks destructive (delete/reset/sign out/purchase/send). Explore does not activate such controls. Choose another control.`
: `"${label}" looks like it opens another app (browser/store/share/mail/maps). Explore does not activate such controls. Choose another control.` });
? `"${label}" looks destructive (delete/reset/sign out/purchase/send). Explore does not activate such controls. Choose another control. ${ALLOW_HINT}`
: `"${label}" looks like it opens another app (browser/store/share/mail/maps). Explore does not activate such controls. Choose another control. ${ALLOW_HINT}` });
}
// The map keeps the reference the model typed; only the device gets the value.
const typed = action.action === "fill" || action.action === "type" ? { ...action, text: inputs.resolve(action.text) } : action;
-11
View File
@@ -5,7 +5,6 @@ import { resolve } from "node:path";
import { ExploreStore } from "./map/store.js";
import { QUERY_CONTRACT } from "./types.js";
import { EXPLORE_VERSION } from "./shared/package-paths.js";
import { enableProgramStatus, lastReportedStatus, reportFinished, reportStatus } from "./shared/program-status.js";
import { isTargetId } from "./config/explore-config.js";
import { command, resultContract, argumentError, validateCommandArguments, flag, has, setStore } from "./cli/args.js";
import { help } from "./cli/help.js";
@@ -70,11 +69,6 @@ const handlers: Record<string, () => Promise<void> | void> = {
/** Commands people type at a terminal; everything else answers agents and scripts in JSON. */
const HUMAN_COMMANDS = new Set(["setup", "doctor", "view", "help", "explore:binary", "explore:session", "report:upload", "reports"]);
/** Commands that run for minutes, so the terminal hears whether they are working, done or failed (see program-status). */
const LONG_COMMANDS = new Set(["capture:review", "capture:baseline", "explore:binary", "explore:session", "report:upload"]);
/** Stopped with Ctrl+C at the terminal: the person already knows, so the status is cleared rather than left as an error. */
const CANCELLED = new Set(["LOCAL_REVIEW_INTERRUPTED", "CAPTURE_CANCELLED"]);
function version(): void {
console.log(EXPLORE_VERSION);
}
@@ -83,15 +77,10 @@ try {
const handler = handlers[command];
if (!handler) argumentError(`Unknown command: ${command}`, undefined, "Run expo-explore help and choose a supported command.");
validateCommandArguments();
// Not with --json: under a pseudo-terminal the sequence would share a line with the JSON an agent parses.
if ((LONG_COMMANDS.has(command) || (command === "doctor" && has("capture"))) && !has("json")) { enableProgramStatus(); reportStatus("working"); }
const workspace = resolve(process.cwd(), flag("dir") ?? ".explore");
setStore(new ExploreStore(workspace));
await handler();
if (lastReportedStatus() === "working") reportFinished();
} catch (error) {
if (error instanceof CiError && CANCELLED.has(error.code)) reportStatus("clear");
else reportStatus("error", { message: error instanceof Error ? error.message : String(error) });
if (command.startsWith("capture:") || command.startsWith("source:") || command.startsWith("ci:") || command.startsWith("config:")) {
// The failure comment names the target from this: a capture, report or publication of one matrix target.
const target = (() => { try { return flag("target"); } catch { return undefined; } })();
+2 -5
View File
@@ -8,7 +8,6 @@ import { keepReports } from "./report-commands.js";
import { warnIgnoredExpiry } from "../config/explore-config.js";
import { argumentError, flag, flags, has, nonNegativeInteger, oneOf, output, positional, positiveInteger } from "./args.js";
import { readReplayPlan } from "../binary/replay.js";
import { reportFinished, reportStatus } from "../shared/program-status.js";
/** `--alias NAME` plus a fixed token from EXPLORE_PREVIEW_TOKEN: the hosted link stays the same from one run to the next (validated by the deploy). */
@@ -38,7 +37,7 @@ export async function exploreBinary(): Promise<void> {
const upload = simulator === "local" ? has("upload") : !has("no-upload");
const port = flag("port") === undefined ? undefined : nonNegativeInteger("port");
const started = Date.now();
const say = (message: string) => { reportStatus("working", { message }); process.stderr.write(`[explore ${Math.round((Date.now() - started) / 1000)}s] ${message}\n`); };
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 (upload) await assertHostingExport();
const result = await runBinaryExploration({
@@ -78,7 +77,6 @@ export async function exploreBinary(): Promise<void> {
if (simulator === "eas" || hosted || has("no-open")) { console.log(`Next: ${summary.next.join(" | ")}`); return; }
const viewer = await startViewerServer({ root: outputDirectory, ...(port === undefined ? {} : { port }) });
console.log(`Viewer: ${viewer.url} (Ctrl+C to stop)`);
reportFinished();
openViewerInBrowser(viewer.url);
await waitForViewerShutdown(viewer);
}
@@ -102,7 +100,7 @@ export async function exploreSession(): Promise<void> {
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) => { reportStatus("working", { message }); process.stderr.write(`[explore ${Math.round((Date.now() - started) / 1000)}s] ${message}\n`); };
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);
const envFile = await defaultSessionEnvFile(flag("env-file"));
if (has("upload")) await assertHostingExport();
@@ -142,7 +140,6 @@ export async function exploreSession(): Promise<void> {
if (hosted || has("no-open")) { console.log(`Next: ${summary.next.join(" | ")}`); return; }
const viewer = await startViewerServer({ root: outputDirectory, ...(port === undefined ? {} : { port }) });
console.log(`Viewer: ${viewer.url} (Ctrl+C to stop)`);
reportFinished();
openViewerInBrowser(viewer.url);
await waitForViewerShutdown(viewer);
}
+1 -9
View File
@@ -21,7 +21,6 @@ import { help } from "./help.js";
import { CiError } from "../shared/ci-errors.js";
import { cleanupAfterCapture, findOptionalBaseline, resolveCompareRefs, resolvePullRequest, writeCaptureOutputs, writeStepOutputs } from "../ci/workflow-steps.js";
import { stderrProgress } from "../shared/progress.js";
import { reportFinished, reportStatus } from "../shared/program-status.js";
import { appendTimingsSummary, timingsPathFor } from "../shared/timings.js";
import { maxParallelTargets } from "../ci/session-plan.js";
@@ -48,12 +47,10 @@ Fix the problems in steps 1–5 before a capture check.`);
}
if (!has("yes")) {
if (!process.stdin.isTTY || has("json")) argumentError("A capture check starts an EAS build and simulator session; pass --yes to confirm.", "yes");
reportStatus("blocked", { kind: "question", message: "Start a capture check on EAS?" });
const terminal = createInterface({ input: process.stdin, output: process.stderr });
const answer = await terminal.question(`This builds the app on EAS and runs an EAS Simulator session (EAS usage applies${report.mode === "agent" ? "; agent mode also uses your model API key or local claude/codex login" : ""}). Continue? (yes/no) `);
terminal.close();
if (!/^(y|yes)$/i.test(answer.trim())) { reportStatus("clear"); return; }
reportStatus("working");
if (!/^(y|yes)$/i.test(answer.trim())) return;
}
let result: Awaited<ReturnType<typeof runCaptureCheck>>;
try {
@@ -313,8 +310,6 @@ async function localReview(): Promise<void> {
}
// A target that failed outright has no report; the others still open, save and upload, and the command exits 1.
if (result.failures.length) process.exitCode = 1;
// The terminal keeps this record after the run, so it names what failed rather than what was open.
const finished = () => reportFinished(result.failures.length ? `No report for ${result.failures.map(({ target }) => target.id).join(", ")}` : undefined);
const summary = { ok: result.failures.length === 0, runId: result.runId, base: result.base, head: result.head,
...(result.failures.length ? { failures: result.failures.map(({ target, error }) => ({ target: target.id, code: error.code, message: error.message })) } : {}),
reports: result.reports.map(({ platform, target, directory, zip, changes, device }) => ({ platform, target: target.id, label: target.label, directory, zip,
@@ -336,18 +331,15 @@ async function localReview(): Promise<void> {
if (has("json")) output({ ...summary, ...(copied ? {} : { reports: summary.reports.map(({ directory: _directory, zip: _zip, ...report }) => report) }),
url: hosted.previewUrl, expiresAt: hosted.expiresAt });
else console.log(`Report: ${hosted.previewUrl}${hosted.expiresAt ? ` (until ${hosted.expiresAt.slice(0, 10)})` : ""}`);
finished();
return;
}
if (has("json") || has("no-open")) {
if (has("json")) output(summary);
else for (const report of result.reports) console.log(`${report.target.id}: ${report.zip}`);
finished();
return;
}
const server = await startLocalReportServer({ reports: zips, ...(has("port") ? { port: nonNegativeInteger("port") } : {}) });
console.log(`Viewer: ${server.url} (Ctrl+C to stop)`);
finished();
if (saved) console.log(`Saved as ${saved.id}: expo-explore reports reopens it, and reports upload ${saved.id} hosts it.`);
openViewerInBrowser(server.url);
await new Promise<void>(done => { process.once("SIGINT", () => done()); process.once("SIGTERM", () => done()); });
+1 -1
View File
@@ -57,7 +57,7 @@ export type CiErrorRenderOptions = { secrets?: readonly string[] };
/** The values of every variable that names a secret (a token, secret, password or API key), to redact from what Explore writes. */
export function environmentSecrets(environment: NodeJS.ProcessEnv): string[] {
return Object.entries(environment).filter(([key]) => /(?:TOKEN|SECRET|PASSWORD|API_KEY|PRIVATE_KEY)/i.test(key)).flatMap(([, value]) => value ? [value] : []);
return Object.entries(environment).filter(([key]) => /(?:TOKEN|SECRET|PASSWORD|API_KEY)/i.test(key)).flatMap(([, value]) => value ? [value] : []);
}
/** Redacts secret values, bearer and provider tokens, credentials in URLs, and signed-URL parameters from any text Explore writes. */
-63
View File
@@ -1,63 +0,0 @@
import { environmentSecrets, redactSecrets } from "./ci-errors.js";
/**
* Tells the terminal what a long command is doing with OSC 7501
* (https://superlogical.com/rex/docs/build/program-status), so a tab left in the background can show that a review is
* working, waiting on an answer, done or failed. Only an interactive stderr gets the sequence; a terminal that does not
* know it ignores it, as it does any unknown OSC (ECMA-48 §8.3.89). The spec's feature query is not sent: reading its
* reply would put stdin in raw mode under the command's own prompts.
*
* The terminal drops a `working` or `blocked` record when the process exits and keeps `done` and `error`, so an exit
* without a final report (a second Ctrl+C) leaves nothing behind.
*/
export type ProgramState = "working" | "blocked" | "done" | "error" | "clear";
export type BlockedKind = "permission" | "question" | "auth";
const APP = "expo-explore";
/** The spec allows 2048 bytes of decoded `msg`; 512 code points stay under it in any script. */
const MESSAGE_LIMIT = 512;
let write: ((text: string) => void) | undefined;
let last: ProgramState | undefined;
/**
* A message is redacted as stderr's diagnostics are, since a kept record outlives the process. Redacting comes first,
* so truncation cannot leave a partial secret the patterns no longer match.
*/
export function programStatusSequence(state: ProgramState, details: { message?: string; kind?: BlockedKind } = {}, environment: NodeJS.ProcessEnv = process.env): string {
const pairs = [`state=${state}`, `app=${APP}`];
if (state === "blocked" && details.kind) pairs.push(`kind=${details.kind}`);
const redacted = details.message === undefined ? undefined : redactSecrets(details.message, environmentSecrets(environment));
// The terminal discards a report whose message holds control characters, and shows one line.
const message = redacted?.replace(/[\p{Cc}\u2028\u2029]+/gu, " ").trim();
// By code points, so an emoji is not split; the first cut keeps Array.from off a long git stderr.
const shown = message && Array.from(message.slice(0, MESSAGE_LIMIT * 2)).slice(0, MESSAGE_LIMIT).join("");
if (shown) pairs.push(`msg=${Buffer.from(shown, "utf8").toString("base64")}`);
return `\x1b]7501;${pairs.join(":")}\x1b\\`;
}
/** CI is left out even under a pseudo-terminal (Buildkite, `docker run -t`), whose log would keep the raw sequences. */
export function terminalReportsStatus(stream: { isTTY?: boolean } = process.stderr, environment: NodeJS.ProcessEnv = process.env): boolean {
return stream.isTTY === true && environment.TERM !== "dumb" && !environment.CI;
}
/** Turns reports on for this process when stderr is a terminal; until then `reportStatus` writes nothing. */
export function enableProgramStatus(options: { write?: (text: string) => void } = {}): void {
if (options.write) write = options.write;
else if (terminalReportsStatus()) write = text => { process.stderr.write(text); };
}
export function reportStatus(state: ProgramState, details: { message?: string; kind?: BlockedKind } = {}): void {
last = state;
write?.(programStatusSequence(state, details));
}
/** `done`, or `error` when the command has already set a failing exit code (a review with a failed target). */
export function reportFinished(message?: string): void {
reportStatus(process.exitCode ? "error" : "done", message ? { message } : {});
}
/** The last state reported, so the command's end reports `done` only when nothing more specific came before it. */
export function lastReportedStatus(): ProgramState | undefined {
return last;
}
+2 -6
View File
@@ -1,10 +1,7 @@
import { reportStatus } from "./program-status.js";
/**
* One line per capture step on stderr, so a CI log or a terminal shows what Explore is doing while
* a build or a simulator session runs for minutes; the same line becomes the terminal's status
* message (see program-status). Messages carry plan, route, and EAS identifiers only; never setup
* text, which can hold app-test secrets.
* a build or a simulator session runs for minutes. Messages carry plan, route, and EAS identifiers
* only; never setup text, which can hold app-test secrets.
*/
export type Progress = (message: string) => void;
@@ -15,7 +12,6 @@ export function stderrProgress(options: { now?: () => number; write?: (text: str
const write = options.write ?? (text => { process.stderr.write(text); });
const started = now();
return message => {
reportStatus("working", { message });
const seconds = Math.max(0, Math.floor((now() - started) / 1000));
const elapsed = `${String(Math.floor(seconds / 60)).padStart(2, "0")}:${String(seconds % 60).padStart(2, "0")}`;
write(`[explore ${elapsed}] ${message}\n`);
+49
View File
@@ -1207,3 +1207,52 @@ test("a replay plan's {{secret:NAME}} inputs are read before any device starts a
assert.equal(map.actionAttempts[0].action.input.value, "{{secret:APP_TEST_PASSWORD}}");
assert.ok(!JSON.stringify(map).includes("hunter2-test"));
});
test("risk words are found inside identifiers that join them", async () => {
const { riskOf } = await tsImport("../../src/binary/explorer.ts", import.meta.url);
for (const label of ["btn_delete", "deleteAccount", "sign-out", "logOutButton", "settings.reset"]) assert.equal(riskOf(label, []), "destructive", label);
assert.equal(riskOf("openInSafari", []), "external");
for (const label of ["postsTab", "settings_button", "Profile", "MapView"]) assert.equal(riskOf(label, []), "safe", label);
assert.equal(riskOf("resetFilters", ["resetFilters"]), "safe", "an allowed identifier");
});
/**
* A screen whose only control is a hittable custom view the map does not record as a control (type Other, as many
* custom pressables are): its risk is in its own label and identifier.
*/
function iconScreen(icon) {
return [{ type: "Window", rect: { x: 0, y: 0, width: 400, height: 800 } }, { type: "StaticText", label: "Inbox" },
{ type: "Other", hittable: true, rect: { x: 340, y: 40, width: 44, height: 44 }, ...icon }];
}
test("a coordinate tap is judged by the control under the point, whatever the model calls it", async () => {
for (const icon of [{ identifier: "btn_delete" }, { label: "Delete conversation" }]) {
const { calls, acted, map } = await harness([["observe", { includeImage: true }], ["act", { action: "tap", frameId: "frame-0", x: 0.9, y: 0.075, target: "Profile" }], ["finish", { summary: "x" }]],
{ observe: async includeImage => ({ nodes: iconScreen(icon), capturedAt: new Date().toISOString(), ...(includeImage ? { frameId: "frame-0", png: PNG, imageSha256: "d".repeat(64) } : {}) }) });
assert.equal(acted.length, 0, JSON.stringify(icon));
assert.equal(calls[1].result.blocked, true);
assert.match(calls[1].result.reason, /looks destructive.*--allow-destructive/);
assert.equal(map.actionAttempts.at(-1).risk, "destructive");
}
});
test("a coordinate tap on a control allowed by its label goes through, even when its identifier reads as risky", async () => {
const { acted } = await harness([["observe", { includeImage: true }], ["act", { action: "tap", frameId: "frame-0", x: 0.9, y: 0.075 }], ["finish", { summary: "x" }]],
{ allowDestructive: ["Reset filters"],
observe: async includeImage => ({ nodes: iconScreen({ label: "Reset filters", identifier: "resetFilters" }), capturedAt: new Date().toISOString(), ...(includeImage ? { frameId: "frame-0", png: PNG, imageSha256: "d".repeat(64) } : {}) }) });
assert.equal(acted.length, 1);
});
test("a coordinate tap with no control under the point is still recorded as unknown, not refused", async () => {
const { acted, map } = await harness([["observe", { includeImage: true }], ["act", { action: "tap", frameId: "frame-0", x: 0.5, y: 0.5 }], ["finish", { summary: "x" }]],
{ observe: async includeImage => ({ nodes: iconScreen({ identifier: "btn_delete" }), capturedAt: new Date().toISOString(), ...(includeImage ? { frameId: "frame-0", png: PNG, imageSha256: "d".repeat(64) } : {}) }) });
assert.equal(acted.length, 1);
assert.equal(map.actionAttempts.at(-1).risk, "unknown");
});
test("a tap by identifier on a control allowed by its label goes through", async () => {
const screen = [{ type: "StaticText", label: "Filters" }, { type: "Button", label: "Reset filters", identifier: "resetFilters" }];
const { acted } = await harness([["observe", { includeImage: true }], ["act", { action: "tap", identifier: "resetFilters" }], ["finish", { summary: "x" }]],
{ allowDestructive: ["Reset filters"], observe: async includeImage => ({ nodes: screen, capturedAt: new Date().toISOString(), ...(includeImage ? { frameId: "frame-0", png: PNG, imageSha256: "e".repeat(64) } : {}) }) });
assert.equal(acted.length, 1);
});
-76
View File
@@ -1,76 +0,0 @@
import assert from "node:assert/strict";
import test from "node:test";
import { enableProgramStatus, lastReportedStatus, programStatusSequence, reportFinished, reportStatus, terminalReportsStatus } from "../../dist/shared/program-status.js";
import { stderrProgress } from "../../dist/shared/progress.js";
const decode = sequence => {
assert.match(sequence, /^\x1b\]7501;.*\x1b\\$/);
return Object.fromEntries(sequence.slice(7, -2).split(":").map(pair => [pair.slice(0, pair.indexOf("=")), pair.slice(pair.indexOf("=") + 1)]));
};
const message = sequence => {
const { msg } = decode(sequence);
return msg === undefined ? undefined : Buffer.from(msg, "base64").toString("utf8");
};
test("a report names the state and the app, and carries its message as base64", () => {
assert.equal(programStatusSequence("done"), "\x1b]7501;state=done:app=expo-explore\x1b\\");
const pairs = decode(programStatusSequence("working", { message: "capturing Home — ✓" }));
assert.equal(pairs.state, "working");
assert.equal(Buffer.from(pairs.msg, "base64").toString("utf8"), "capturing Home — ✓");
});
test("only a blocked report carries its kind", () => {
assert.equal(decode(programStatusSequence("blocked", { kind: "question" })).kind, "question");
assert.equal(decode(programStatusSequence("working", { kind: "question" })).kind, undefined);
});
test("a message becomes one line without control characters, within the spec's size", () => {
const pairs = decode(programStatusSequence("error", { message: "build failed\n\x1b[31mexit 1\x1b[0m\t" }));
assert.equal(Buffer.from(pairs.msg, "base64").toString("utf8"), "build failed [31mexit 1 [0m");
assert.ok(Buffer.from(decode(programStatusSequence("working", { message: "あ".repeat(5000) })).msg, "base64").byteLength <= 2048);
// Cut by code points: an emoji at the limit is kept whole or dropped, never halved.
assert.equal(message(programStatusSequence("working", { message: `${"a".repeat(511)}😀😀` })), `${"a".repeat(511)}😀`);
assert.ok(Buffer.from(decode(programStatusSequence("working", { message: "😀".repeat(5000) })).msg, "base64").byteLength <= 2048);
assert.equal(decode(programStatusSequence("working", { message: " \n " })).msg, undefined);
assert.ok(programStatusSequence("working", { message: "x".repeat(5000) }).length <= 4096);
});
test("a message is redacted as stderr's diagnostics are", () => {
const environment = { EXPO_TOKEN: "expo-secret-value", SIGNING_PRIVATE_KEY: "private-key-value" };
const text = message(programStatusSequence("error", {
message: "git failed: https://user:[email protected]/o/r expo-secret-value private-key-value",
}, environment));
assert.doesNotMatch(text, /ghp_|expo-secret-value|private-key-value/);
assert.match(text, /\[REDACTED\]/);
});
test("only an interactive stderr that is not a dumb terminal or CI gets reports", () => {
assert.equal(terminalReportsStatus({ isTTY: true }, { TERM: "xterm-ghostty" }), true);
assert.equal(terminalReportsStatus({ isTTY: true }, { TERM: "dumb" }), false);
assert.equal(terminalReportsStatus({ isTTY: true }, { TERM: "xterm-256color", CI: "true" }), false);
assert.equal(terminalReportsStatus({ isTTY: false }, {}), false);
assert.equal(terminalReportsStatus({}, {}), false);
});
test("progress lines become the working status once reports are on", () => {
const written = [];
stderrProgress({ write: () => {} })("before");
enableProgramStatus({ write: text => written.push(text) });
stderrProgress({ write: () => {} })("planning routes");
reportStatus("done");
assert.deepEqual(written.map(decode).map(({ state, msg }) => [state, msg && Buffer.from(msg, "base64").toString("utf8")]),
[["working", "planning routes"], ["done", undefined]]);
assert.equal(lastReportedStatus(), "done");
});
test("a finished command reports done, or error once it has set a failing exit code", t => {
const written = [];
enableProgramStatus({ write: text => written.push(text) });
const exitCode = process.exitCode;
t.after(() => { process.exitCode = exitCode; });
process.exitCode = undefined;
reportFinished();
process.exitCode = 1;
reportFinished("No report for ios");
assert.deepEqual(written.map(text => [decode(text).state, message(text)]), [["done", undefined], ["error", "No report for ios"]]);
});
@@ -9,9 +9,6 @@
background: var(--canvas-minimap-background);
box-shadow: var(--shadow-md);
contain: layout paint;
/* iOS WebKit lifts the minimap above freshly composited cards (a screenshot's reveal fade, as a
fast pan mounts them) a frame late, so they flicker over it. Its own layer keeps it on top. */
will-change: transform;
pointer-events: none;
view-transition-name: canvas-minimap;
--canvas-minimap-background: color-mix(in srgb, var(--surface) 94%, transparent);