@delacour/warden-e2e 0.4.0 → 0.5.0

package/types/core/src/builds/kinds.d.ts

@@ -0,0 +1,56 @@
+import type { Platform } from "../types";
+import { type BuildConfiguration } from "./builds.defaults";
+import type { Project } from "./config";
+import type { AppFramework } from "./native-ids";
+/**
+ * What a cached build is for:
+ * - `dev`: Debug, JS from Metro at runtime.
+ * - `simulator`: Release for a simulator / emulator with no JS bundle embedded; a repack supplies the JS.
+ * - `release`: Release with the JS bundle embedded at build time (the key also covers the JS sources).
+ */
+export type BuildKind = "dev" | "simulator" | "release";
+export declare const BUILD_KINDS: readonly ["dev", "simulator", "release"];
+/** The kind `warden e2e` installs when the suite's `app` names none. */
+export declare const DEFAULT_E2E_KIND: BuildKind;
+/** The kind `warden ui open` / `warden dev` use when no `--kind` is given. */
+export declare const DEFAULT_UI_KIND: BuildKind;
+/** `projects[].kinds.<kind>`: overrides of one kind's built-in defaults. */
+export type KindConfig = {
+    /** replaces the kind's built-in build command, per platform */
+    build?: {
+        ios?: string | undefined;
+        android?: string | undefined;
+    } | undefined;
+    /** env of the build and of the JS bundle step (`EXPO_PUBLIC_*`, `NODE_ENV`…); part of the JS key */
+    env?: Record<string, string> | undefined;
+    /** globs (relative to the project root, `!` excludes) of the JS sources the key covers; `simulator` / `release` only */
+    jsInputs?: string[] | undefined;
+};
+export type ProjectKinds = Partial<Record<BuildKind, KindConfig | undefined>>;
+/** A kind's effective build settings: the built-in defaults with `projects[].kinds.<kind>` applied. */
+export type KindSettings = {
+    kind: BuildKind;
+    build: Record<Platform, string>;
+    buildConfiguration: BuildConfiguration;
+    /** the app binary carries its JS (`release`); false = Metro or a repack supplies it */
+    embedsJs: boolean;
+    /** `native`: the key is the native fingerprint; `native+js`: also the `jsInputs` content */
+    fingerprint: "native" | "native+js";
+    env: Record<string, string>;
+    /** the JS sources the JS key (`simulator`, `release`) covers; undefined for `dev` */
+    jsInputs?: string[];
+};
+/** The built-in build command of `kind` (the default `projects[].kinds.<kind>.build` replaces). */
+export declare function kindBuildCommand(kind: BuildKind, platform: Platform, framework: AppFramework): string;
+/**
+ * `kind`'s settings for `project`. Precedence: `kinds.<kind>.build` > the built-in default. The project's top-level
+ * `build` / `fingerprint.include` / `fingerprint.jsInputs` belong to the kind-less flow and are not read here
+ * (`fingerprint.command`, `build.cache` and `build.prebuiltReactNative` still apply: they are not about the kind).
+ * JS inputs: `kinds.<kind>.jsInputs`, else `DEFAULT_JS_INPUTS` (all tracked files but `ios/`, `android/`, `node_modules`).
+ */
+export declare function resolveKind(project: Project, kind: BuildKind): KindSettings;
+/**
+ * `project` as `kind` builds it: the build commands, configuration and env of `resolveKind`, and `jsInputs` set only
+ * when the kind's cache key covers the JS (`release`), so `runLocalBuild` / `computeCacheKey` run unchanged.
+ */
+export declare function projectForKind(project: Project, kind: BuildKind): Project;

package/types/core/src/builds/native-ids.d.ts

@@ -0,0 +1,14 @@
+import type { Platform } from "../types";
+/** How an app is run: Expo (`expo start`, a dev client) or bare React Native (`react-native start`, the app itself). */
+export type AppFramework = "expo" | "react-native";
+/**
+ * The app's framework from its `package.json`: `expo` when it depends on `expo`, `react-native` when
+ * only on `react-native`; undefined without either (or without a readable `package.json`).
+ */
+export declare function appFramework(root: string): AppFramework | undefined;
+/**
+ * A bare React Native app's ids, read from its native projects: iOS `PRODUCT_BUNDLE_IDENTIFIER`
+ * (the template's `$(PRODUCT_NAME:rfc1034identifier)` filled in with `appName`), Android
+ * `applicationId`. A platform whose id can't be read (no native dir, a build variable) is left out.
+ */
+export declare function nativeBundleIds(root: string, appName: string): Partial<Record<Platform, string>>;

package/types/core/src/builds/resolve.d.ts

@@ -1,4 +1,5 @@
 import { type AsyncResult } from "../../../types/src/result";
+import type { Platform } from "../types";
 import type { InstallMode } from "./app-option.schema";
 /** Where `ensure` found the app. */
 export type ResolveSource = "installed" | "cache" | "eas" | "build";
@@ -10,6 +11,29 @@ export type EnsureResult = {
     /** the app is on the device at `hash` (false when no device was given) */
     installed: boolean;
 };
+/**
+ * What a resolve is doing right now, for a progress display: `fetching` the EAS build, `waiting` on another device's
+ * (or process's) fetch / build of the same hash, `building` locally, `repacking` JS into the simulator base,
+ * `installing` on a device (only while an install really runs), `ready` when the resolve is done.
+ */
+export type AppPhase = {
+    phase: "fetching";
+    source: "eas";
+} | {
+    phase: "waiting";
+} | {
+    phase: "building";
+    platform: Platform;
+    hash: string;
+} | {
+    phase: "repacking";
+    platform: Platform;
+    jsKey: string;
+} | {
+    phase: "installing";
+} | {
+    phase: "ready";
+};
 export type EasStepOutcome = {
     kind: "hit";
     path: string;
@@ -63,6 +87,8 @@ export type ResolveSteps = {
     /** local build into the cache; path */
     build?: () => AsyncResult<string>;
     log: (line: string) => void;
+    /** progress: where this resolve is (see `AppPhase`) */
+    onPhase?: (phase: AppPhase) => void;
 };
 /**
  * The 5-step resolver, first hit wins: (1) already installed at this hash → nothing to do;

package/types/core/src/duration.d.ts

@@ -0,0 +1,5 @@
+import type { Result } from "../../types/src/result";
+/** `10m` / `30s` / `2h` / `500ms` / bare seconds → milliseconds. */
+export declare function parseDuration(input: string): Result<number>;
+/** 125000 → `2m5s`. */
+export declare function formatDuration(ms: number): string;

package/types/core/src/ports.d.ts

@@ -0,0 +1,76 @@
+import type { AsyncResult, Result } from "../../types/src/result";
+import { type PidAlive } from "./liveness";
+import type { Store } from "./store";
+import type { Lease, Owner } from "./types";
+/** Span used when a spec has no `:span` (mirrors salient's `pickPort` 20-port scan). */
+export declare const DEFAULT_PORT_SPAN = 20;
+export type PortRange = {
+    from: number;
+    span: number;
+};
+/** `8091:20` → `{ from: 8091, span: 20 }`; bare `8091` → span `DEFAULT_PORT_SPAN`. */
+export declare function parsePortSpec(spec: string): Result<PortRange>;
+export type ProbeOutcome = "free" | "busy" | "unsupported";
+/**
+ * A failed probe bind → outcome. In use / forbidden is busy anywhere; a missing address or family is
+ * unsupported; any other error on the IPv6 wildcard is unsupported too (Bun reports a code-less
+ * "Failed to listen at ::" on hosts without IPv6), while on an IPv4 host it stays busy.
+ */
+export declare function classifyBindError(error: {
+    code?: string;
+}, host: string): Exclude<ProbeOutcome, "free">;
+/**
+ * Bind probe: listen on `port` and close immediately. With `host`, probes only that address;
+ * otherwise the port must bind on 127.0.0.1, 0.0.0.0 and `::` (hosts without IPv6 are skipped).
+ */
+export declare function isPortFree(port: number, host?: string): Promise<boolean>;
+export type ClaimPortsRequest = {
+    owner: Owner;
+    from: number;
+    span: number;
+    /** ports wanted (default 1) */
+    count?: number;
+    /** candidate stride inside the range (default 1; 2 for emulator console ports) */
+    step?: number;
+    ttlMs: number;
+    label?: string;
+    pid?: number;
+};
+export type ClaimPortsDeps = {
+    now: () => number;
+    pidAlive: PidAlive;
+    isPortFree: (port: number) => Promise<boolean>;
+};
+/**
+ * Lease `count` ports from `[from, from + span)` (stride `step`). Bind probes run outside the
+ * transaction (async); then, under `BEGIN IMMEDIATE`: reclaim stale leases, pick the first probed-free
+ * ports with no live lease, insert them. Retries when another process wins the race.
+ */
+export declare function claimPorts(store: Store, req: ClaimPortsRequest, deps: ClaimPortsDeps): AsyncResult<Lease[]>;
+/** Which port leases to release. */
+export type PortReleaseSelector = {
+    by: "port";
+    ports: readonly number[];
+} | {
+    by: "lease";
+    ids: readonly string[];
+} | {
+    by: "owner";
+    owner: Owner;
+};
+export type PortReleaseResult = {
+    released: Lease[];
+    /** matched but held by someone other than `onlyOwner` — left in place */
+    denied: Lease[];
+    /** ports / lease ids with no matching port lease */
+    missing: string[];
+};
+/**
+ * Release port leases by port number, lease id, or owner. With `onlyOwner`, leases held by anyone
+ * else are reported in `denied` and kept. Non-port lease ids count as `missing` (never deleted here).
+ */
+export declare function releasePorts(store: Store, selector: PortReleaseSelector, opts?: {
+    onlyOwner?: Owner;
+}): PortReleaseResult;
+/** All port leases (live or stale), ordered by port. */
+export declare function listPortLeases(store: Store): Lease[];

package/types/core/src/sims/slim.profile.d.ts

@@ -0,0 +1,54 @@
+import { type Result } from "../../../types/src/result";
+/**
+ * What `warden sim slim` may switch off inside an iOS simulator: 15 categories of `launchd_sim`
+ * jobs, each a coherent feature area (widgets, Siri, iCloud…) so a suite can keep one with
+ * `slim: { except: ["store"] }`. Labels the e2e stack depends on live in `slim.ts` `NEVER_DISABLE`
+ * and are left out here; labels that break boot are in `FORBIDDEN_LABELS` and never touched.
+ */
+/** A label a category must leave enabled because something common breaks without it. */
+export type AlwaysEnabled = {
+    label: string;
+    reason: string;
+};
+export type SlimCategory = {
+    id: string;
+    name: string;
+    labels: readonly string[];
+    alwaysEnabled?: readonly AlwaysEnabled[];
+};
+export declare const SLIM_CATEGORIES: readonly SlimCategory[];
+/** Jobs whose absence breaks boot or the home screen (observed): never disabled, whatever a profile says. */
+export declare const FORBIDDEN_LABELS: readonly string[];
+/**
+ * Which categories stay on (`except`, by id) and which single labels stay on (`keep`, full launchd
+ * labels). A label listed by any excepted category stays on even when another category lists it too.
+ */
+export type SlimProfile = {
+    except: readonly string[];
+    keep: readonly string[];
+};
+export declare const DEFAULT_SLIM_PROFILE: SlimProfile;
+/** Every label some category may switch off. */
+export declare function slimmableSet(): Set<string>;
+/** Slimmable labels plus the `alwaysEnabled` ones: the labels warden is allowed to write an override for. */
+export declare function managedSet(): Set<string>;
+/** The labels to have disabled under `profile`, in category order. */
+export declare function desiredLabels(profile: SlimProfile): Set<string>;
+/**
+ * What to change to reach `desired`: disable the wanted labels not yet disabled, enable the managed
+ * labels that are disabled but not wanted. A disabled label outside `managed` is not ours, so it is
+ * never re-enabled. `current` is `print-disabled` (label → disabled) or just the disabled labels.
+ */
+export declare function delta(current: ReadonlyMap<string, boolean> | ReadonlySet<string>, desired: ReadonlySet<string>, managed: ReadonlySet<string>): {
+    toDisable: string[];
+    toEnable: string[];
+};
+/** Reject category ids that do not exist and `keep` labels warden does not manage; messages name the culprit. */
+export declare function validateProfile(profile: SlimProfile): Result<SlimProfile>;
+/** The categories for `warden sim profiles`. */
+export declare function describeCategories(): {
+    id: string;
+    name: string;
+    labelCount: number;
+    labels: readonly string[];
+}[];

package/types/e2e/src/devtools/facet.d.ts

@@ -19,6 +19,8 @@ export type OpenDevtoolsFacetOptions = {
     /** called with each console line / network entry as it is recorded (the collector's files) */
     consoleSink?: (line: ConsoleLine) => void;
     networkSink?: (entry: NetworkEntry) => void;
+    /** keep React Native's LogBox (toasts and the error inspector) off in the app, across reloads (default false) */
+    muteLogBox?: boolean;
 };
 /**
  * Attach to the running dev client and start capturing its console and `fetch` traffic. This is what

package/types/e2e/src/devtools/logbox.d.ts

@@ -0,0 +1,27 @@
+import type { Sleep } from "./devtools.types";
+import type { DevtoolsSession } from "./session";
+/** What {@link muteLogBox} needs of a devtools session (or facet). */
+export type LogBoxSession = {
+    evaluate: DevtoolsSession["evaluate"];
+    on: (event: "reconnected", handler: () => void) => () => void;
+};
+export type MuteLogBoxOptions = {
+    /** injectable for tests; defaults to a timer */
+    sleep?: Sleep;
+    /** pause between tries while the bundle is still loading (default 250 ms) */
+    intervalMs?: number;
+    /** tries per JS context before LogBox is left on (default 80: 20 s at the default interval) */
+    attempts?: number;
+    log?: (line: string) => void;
+};
+export type LogBoxMute = {
+    /** resolves when the current JS context's tries end (LogBox off, given up, or stopped) */
+    readonly settled: Promise<void>;
+    stop(): void;
+};
+/**
+ * Keeps React Native's LogBox off in the attached app (see `logbox.script.ts`): now, and again in every new JS context
+ * (`reconnected` after a relaunch or JS reload). A context whose bundle has not run yet is tried again every
+ * `intervalMs`; a newer context or `stop()` ends the older context's tries.
+ */
+export declare function muteLogBox(session: LogBoxSession, options?: MuteLogBoxOptions): LogBoxMute;

package/types/e2e/src/devtools/logbox.script.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Page-side expression that turns React Native's LogBox off for good in this JS context: no warning/error toasts and
+ * no full-screen inspector, even for a fatal error. Every log still reaches the console (and so `console.jsonl` and
+ * Metro's terminal); only the overlay that covers the app and steals taps is gone.
+ *
+ * LogBox is not on a global: the script finds `react-native/Libraries/LogBox/Data/LogBoxData.js` in Metro's dev
+ * module registry (`__r.getModules()`, a `Map` of id → module with a `verboseName` path) and, once it is initialized,
+ * adds an ignore pattern that matches every message (`appendNewLog` drops ignored logs before they are stored, which
+ * is what keeps a fatal's inspector shut too, and the logs already shown are filtered out), disables notifications
+ * (`LogBox.ignoreAllLogs()`) and closes an open inspector. Re-running it is harmless (the pattern is de-duplicated).
+ *
+ * Synchronous: `"off"`, `"no-require"` (no dev Metro require yet: the bundle has not run, or a release build) or
+ * `"not-ready"` (LogBoxData not loaded yet). Plain ES5 (Hermes), no backticks or interpolation.
+ */
+export declare const LOGBOX_SCRIPT = "function (g) {\n  var req = g.__r;\n  if (typeof req !== \"function\" || typeof req.getModules !== \"function\") return \"no-require\";\n  var modules = req.getModules();\n  if (!modules || typeof modules.forEach !== \"function\") return \"no-require\";\n  var data = null;\n  modules.forEach(function (mod) {\n    if (data || !mod || typeof mod.verboseName !== \"string\" || !mod.isInitialized) return;\n    var name = mod.verboseName.replace(/\\\\/g, \"/\");\n    if (!/(^|\\/)react-native\\/Libraries\\/LogBox\\/Data\\/LogBoxData\\.js$/.test(name)) return;\n    var exports = mod.publicModule && mod.publicModule.exports;\n    if (exports && typeof exports.addIgnorePatterns === \"function\") data = exports;\n  });\n  if (!data) return \"not-ready\";\n  data.addIgnorePatterns([/[\\s\\S]*/]);\n  if (typeof data.setDisabled === \"function\") data.setDisabled(true);\n  if (typeof data.setSelectedLog === \"function\") data.setSelectedLog(-1);\n  return \"off\";\n}";
+/** Expression that runs `LOGBOX_SCRIPT` against the page's global object. */
+export declare const LOGBOX_EXPRESSION = "(function (g) {\n  var req = g.__r;\n  if (typeof req !== \"function\" || typeof req.getModules !== \"function\") return \"no-require\";\n  var modules = req.getModules();\n  if (!modules || typeof modules.forEach !== \"function\") return \"no-require\";\n  var data = null;\n  modules.forEach(function (mod) {\n    if (data || !mod || typeof mod.verboseName !== \"string\" || !mod.isInitialized) return;\n    var name = mod.verboseName.replace(/\\\\/g, \"/\");\n    if (!/(^|\\/)react-native\\/Libraries\\/LogBox\\/Data\\/LogBoxData\\.js$/.test(name)) return;\n    var exports = mod.publicModule && mod.publicModule.exports;\n    if (exports && typeof exports.addIgnorePatterns === \"function\") data = exports;\n  });\n  if (!data) return \"not-ready\";\n  data.addIgnorePatterns([/[\\s\\S]*/]);\n  if (typeof data.setDisabled === \"function\") data.setDisabled(true);\n  if (typeof data.setSelectedLog === \"function\") data.setSelectedLog(-1);\n  return \"off\";\n})(typeof globalThis !== \"undefined\" ? globalThis : (typeof global !== \"undefined\" ? global : this))";

package/types/e2e/src/session.d.ts

@@ -18,7 +18,10 @@ export declare function devtoolsTarget(env: E2eEnv): {
     appId: string;
     deviceName?: string;
 };
-/** Metro's inspector for this env's app (`WARDEN_METRO_URL`), pinned by {@link devtoolsTarget}. */
+/**
+ * Metro's inspector for this env's app (`WARDEN_METRO_URL`), pinned by {@link devtoolsTarget}. LogBox is kept off:
+ * its toasts and inspector cover the app and take taps, while the logs still reach the console capture.
+ */
 export declare const openDevtools: DevtoolsOpener;
 export type Session = {
     readonly env: E2eEnv;