obsidian-integration-testing 12.1.2 → 12.3.0

package/dist/lib/cjs/emulator-reclaim.d.cts

@@ -0,0 +1,179 @@
+/**
+ * @file
+ *
+ * Stops the emulators this harness started, and **verifies** each stop — the
+ * marker-driven half of emulator ownership (`emulator-marker.ts`, **L56**).
+ *
+ * It lives apart from `transport-factory.ts` so that a process with no business
+ * loading the whole transport stack can still stop an emulator correctly. That
+ * process is the emulator reaper (`emulator-reaper.ts`): it runs detached from
+ * any test runner, and in this repo's own suites it runs straight from source
+ * under Node's type stripping, where a module reading the build-time
+ * `OBSIDIAN_METADATA` global — which the factory's import graph reaches —
+ * cannot load at all. So nothing this module imports may reach it either.
+ */
+import type { ChildProcess } from 'node:child_process';
+import type { ProcessListEntry } from './emulator-backend.cjs';
+/**
+ * Budget for one quick `adb` call — `adb devices`, a console command.
+ */
+export declare const ADB_DEVICE_CHECK_TIMEOUT_IN_MILLISECONDS = 5000;
+export declare const ADB_DUMPSYS_MAX_BUFFER_IN_BYTES = 8388608;
+export declare const HOST_PROCESS_QUERY_TIMEOUT_IN_MILLISECONDS = 30000;
+/**
+ * A host command and its arguments.
+ */
+export interface HostCommandQuery {
+    /**
+    The executable to run.
+     */
+    readonly command: string;
+    /**
+    The command's arguments.
+     */
+    readonly commandArguments: string[];
+}
+/**
+ * Parameters for {@link EmulatorReclaimer.reclaimLeftoverEmulators}.
+ */
+export interface ReclaimLeftoverEmulatorsParams {
+    /**
+    An AVD whose leftover is left alone — the one a preflight is about to adopt instead.
+     */
+    readonly exceptAvdName?: string | undefined;
+    /**
+     * `'preflight'` spares an emulator another live harness process still owns.
+     * `'end-of-run'` does not: the caller holds the `android` lock with no run in
+     * flight — the run's own global teardown, or the emulator reaper after the
+     * run is gone — so that owner can only be one of the finished run's
+     * processes, which no longer has a turn to stop it.
+     */
+    readonly scope: 'end-of-run' | 'preflight';
+}
+/**
+ * Parameters for {@link EmulatorReclaimer.stopEmulator}.
+ */
+export interface StopEmulatorParams {
+    /**
+    The AVD name, named in the warning so the leftover is identifiable, and the key of its marker.
+     */
+    readonly avdName: string;
+    /**
+     * The device the emulator is serving, shut down over its console and polled
+     * to decide whether it actually stopped. `undefined` when the emulator failed
+     * before any device appeared.
+     */
+    readonly deviceId?: string | undefined;
+    /**
+     * The emulator launcher process this run spawned. `undefined` for a leftover
+     * this run took over, whose launcher belonged to another process.
+     */
+    readonly emulatorProcess?: ChildProcess | undefined;
+    /**
+    The emulator PIDs this run owns, escalated to when the console and the launcher's tree kill leave one behind.
+     */
+    readonly ownedEmulatorPids: readonly number[];
+}
+/**
+ * Finds, stops and verifies the harness's emulators, reporting through the
+ * caller's log so each caller keeps its own prefix.
+ */
+export declare class EmulatorReclaimer {
+    private readonly log;
+    /**
+     * Creates a reclaimer that reports under the caller's own log prefix.
+     *
+     * @param log - Receives every progress and verdict line.
+     */
+    constructor(log: (message: string) => void);
+    /**
+     * Runs `adb devices` and returns its raw stdout.
+     *
+     * The raw listing is what teardown needs: `getConnectedDeviceIds` keeps only
+     * the `device` state, and an emulator on its way out answers `offline` while
+     * still holding the AVD — see `adb-device-list.ts`.
+     *
+     * @returns The raw `adb devices` output.
+     * @throws If adb could not be run at all.
+     */
+    getDevicesOutput(): Promise<string>;
+    /**
+     * Lists every process on the host.
+     *
+     * A host always has processes, so a listing that parses to **zero** rows is a
+     * failed query however it exited, and comes back as `undefined` exactly like
+     * one that did not run — never as an empty list a caller could read as "no
+     * emulator is running".
+     *
+     * @returns The host's processes, or `undefined` when the listing failed.
+     */
+    queryHostProcesses(): Promise<ProcessListEntry[] | undefined>;
+    /**
+     * Stops the emulators this harness started that no live run is responsible
+     * for, and drops the markers that no longer describe a running emulator.
+     *
+     * Only ever acts on a **marker-verified** emulator: one whose marker names a
+     * PID that is still a live emulator process. An emulator without a marker —
+     * booted by hand, by CI, or by another tool — is never touched, which keeps
+     * the L46 line: never a `qemu*` sweep.
+     *
+     * Callers must hold the `android` setup lock (L7), which is what makes a
+     * leftover safe to stop: no other Android run can be mid-flight on it.
+     *
+     * @param params - Which AVD to leave alone, and whether this run is ending.
+     */
+    reclaimLeftoverEmulators(params: ReclaimLeftoverEmulatorsParams): Promise<void>;
+    /**
+     * Stops an emulator this harness owns, and **verifies** it stopped.
+     *
+     * The console shutdown goes first because it is the only path that releases
+     * the AVD's `multiinstance.lock`; a `taskkill` leaves the lock behind, and a
+     * stale lock is what makes the next run fail with `Running multiple emulators
+     * with the same AVD` — a FATAL the emulator writes to its own stdout, where
+     * nobody sees it.
+     *
+     * Works without a launcher handle too: a leftover this run took over has only
+     * its PIDs, which is all the escalation below ever needed. The marker goes
+     * only with a **verified** stop, so an emulator that outlived this attempt
+     * stays convictable by the next one.
+     *
+     * @param params - The emulator process, the device it serves and the PIDs this run owns.
+     */
+    stopEmulator(params: StopEmulatorParams): Promise<void>;
+    /**
+     * Decides whether the emulator this run started is really gone.
+     *
+     * Two independent proofs, cheapest first: none of the PIDs this run owns is
+     * alive, and the device no longer appears in `adb devices` **in any state** (a
+     * dying emulator answers `offline` while it still holds the AVD).
+     *
+     * @param params - The device and the PIDs this run owns.
+     * @returns `true` when nothing of this run's emulator is left.
+     */
+    private checkIsEmulatorGone;
+    /**
+     * Asks the emulator to shut itself down over its console.
+     *
+     * Preferred over killing the process outright because it is the path that
+     * releases the AVD's `multiinstance.lock`. Best-effort: a console that does
+     * not answer is reported and the caller falls through to the kill.
+     *
+     * @param deviceId - The emulator's device ID.
+     */
+    private killEmulatorConsole;
+    /**
+     * Acts on one emulator marker for {@link reclaimLeftoverEmulators}.
+     *
+     * @param marker - The marker to judge.
+     * @param liveEmulatorPids - The emulator processes currently running on the host.
+     * @param scope - Whether an emulator another live harness process owns is spared.
+     */
+    private reclaimLeftoverEmulator;
+    /**
+     * Polls until this run's emulator is gone, or the budget elapses.
+     *
+     * @param params - The device, the PIDs this run owns, and the budget.
+     * @returns `true` when the emulator disappeared within the budget.
+     */
+    private waitForEmulatorStopped;
+}

package/dist/lib/cjs/eval-cap-exceeded-error.cjs

@@ -0,0 +1,61 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var eval_cap_exceeded_error_exports = {};
+__export(eval_cap_exceeded_error_exports, {
+  EvalCapExceededError: () => EvalCapExceededError,
+  isScriptTimeoutError: () => isScriptTimeoutError
+});
+module.exports = __toCommonJS(eval_cap_exceeded_error_exports);
+const SCRIPT_TIMEOUT_PATTERN = /script\s*timeout/i;
+class EvalCapExceededError extends Error {
+  /**
+  The per-eval cap the closure outran, in milliseconds.
+   */
+  capInMilliseconds;
+  /**
+  How the transport that enforced the cap was named in the message.
+   */
+  transportName;
+  /**
+   * Creates the error from the cap, the transport, and the raw error it replaces.
+   *
+   * @param params - The cap, the transport, the option that sets the cap, and the underlying error.
+   */
+  constructor(params) {
+    super(buildMessage(params), { cause: params.cause });
+    this.name = "EvalCapExceededError";
+    this.capInMilliseconds = params.capInMilliseconds;
+    this.transportName = params.transportName;
+  }
+}
+function isScriptTimeoutError(error) {
+  if (!(error instanceof Error)) {
+    return false;
+  }
+  return SCRIPT_TIMEOUT_PATTERN.test(error.message) || SCRIPT_TIMEOUT_PATTERN.test(error.name);
+}
+function buildMessage(params) {
+  return `A single evalInObsidian closure ran longer than the ${params.transportName} per-eval cap of ${String(params.capInMilliseconds)}ms, so it was killed mid-flight. This is a property of the closure, not of the device or the app: everything awaited inside one closure shares that one budget, including every \`lib.waitUntil\` timeout and every settle \`sleep\`. Do the waiting from Node instead \u2014 \`pollInObsidian\` runs a short \`poll\` closure repeatedly until a Node-side \`until\` accepts, so no single eval is ever long. Raise \`${params.optionName}\` only for a closure that genuinely cannot be split.`;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  EvalCapExceededError,
+  isScriptTimeoutError
+});
+//# sourceMappingURL=data:application/json;base64,ewogICJ2ZXJzaW9uIjogMywKICAic291cmNlcyI6IFsiLi4vLi4vLi4vc3JjL2V2YWwtY2FwLWV4Y2VlZGVkLWVycm9yLnRzIl0sCiAgInNvdXJjZXNDb250ZW50IjogWyIvKipcbiAqIEBmaWxlXG4gKlxuICogVGhlIG9uZSBlcnJvciBib3RoIHRyYW5zcG9ydHMgcmFpc2Ugd2hlbiBhIHNpbmdsZSBgZXZhbEluT2JzaWRpYW5gIGNsb3N1cmVcbiAqIG91dHJ1bnMgdGhlIHBlci1ldmFsIGNhcCwgYW5kIHRoZSBwcmVkaWNhdGUgdGhhdCByZWNvZ25pemVzIHRoZSByYXcgdHJhbnNwb3J0XG4gKiBlcnJvciBpdCByZXBsYWNlcy5cbiAqXG4gKiBUaGUgY2FwIGl0c2VsZiBpcyBub3QgdGhlIHByb2JsZW0gdGhpcyBtb2R1bGUgc29sdmVzIFx1MjAxNCB0aGUgZGlhZ25vc2lzIGlzLlxuICogRGVza3RvcCBzdXJmYWNlcyB0aGUgb3ZlcnJ1biBhcyBhIGdlbmVyaWNcbiAqIGBDRFAgY29tbWFuZCB0aW1lZCBvdXQgLi4uIDogUnVudGltZS5ldmFsdWF0ZWAsIHdoaWNoIG5ldmVyIG5hbWVzIHRoZSB0ZXN0J3NcbiAqIG93biB3YWl0IGFuZCBzbyByZWFkcyBhcyBhIGJyb2tlbiBkZXZpY2Ugb3IgYSB3ZWRnZWQgYXBwIFx1MjAxNCBhIHBsdWdpbiByZWxlYXNlIHdhc1xuICogb25jZSBoZWxkIGZvciB0d28gZGF5cyBieSB0aGF0IHJlYWRpbmcsIHdpdGggYSBoZWFsdGh5IGVtdWxhdG9yIGJsYW1lZCBmb3JcbiAqIGhhdmluZyBubyBuZXR3b3JrLlxuICpcbiAqIEFuZHJvaWQgaXMgd29yc2UsIGJlY2F1c2UgaXQgc3VyZmFjZXMgTk9USElORy4gT24gYSBsaXZlIGVtdWxhdG9yIHRoZSBjbG9zdXJlXG4gKiB3YXMgbWVhc3VyZWQgY29tcGxldGluZyBpbiB0aGUgZ3Vlc3Qgb24gc2NoZWR1bGUgXHUyMDE0IHRpbWVycyBhcm1lZCBhdCAzMHMgYW5kIDQwcyBmaXJlZCB3aXRoaW5cbiAqIH4xM21zIG9mIG5vbWluYWwgb24gYSB2aXNpYmxlLCBmb2N1c2VkIHBhZ2UgXHUyMDE0IHdoaWxlIGl0cyBFeGVjdXRlIFNjcmlwdCByZXNwb25zZVxuICogbmV2ZXIgcmVhY2hlZCB0aGUgY2xpZW50LCBzbyB0aGUgY2FsbCBodW5nIHVudGlsIHdoaWNoZXZlciBvdXRlciBidWRnZXQgZ2F2ZSB1cFxuICogZmlyc3QuIEEgaGFuZyBuYW1lcyBub3RoaW5nIGF0IGFsbCwgd2hpY2ggaXMgd2h5IHRoZSBBbmRyb2lkIGNhcCBpcyBlbmZvcmNlZCBieVxuICogdGhlIHRyYW5zcG9ydCBvbiB0aGUgTm9kZSBzaWRlIHJhdGhlciB0aGFuIGJ5IHRoZSBgdGltZW91dHMuc2NyaXB0YCBjYXBhYmlsaXR5XG4gKiBpdCBhbHNvIGRlY2xhcmVzIGFuZCB0aGF0IG5vdGhpbmcgYWN0cyBvbi5cbiAqXG4gKiBCb3RoIHRyYW5zcG9ydHMgdGhlcmVmb3JlIGZ1bm5lbCBpbnRvIHRoZSBtZXNzYWdlIGJlbG93LCB3aGljaCBzYXlzIHdoYXQgdGhlIGNhcFxuICogaXMsIHdoaWNoIHRyYW5zcG9ydCBlbmZvcmNlZCBpdCwgYW5kIHdoYXQgdG8gZG8gaW5zdGVhZC5cbiAqXG4gKiBBIGNsb3N1cmUgdGhhdCBuZWVkcyB0byB3YWl0IGxvbmdlciB0aGFuIHRoZSBjYXAgc2hvdWxkIG5vdCBiZSB3YWl0aW5nIGluc2lkZVxuICogT2JzaWRpYW4gYXQgYWxsLiBgcG9sbEluT2JzaWRpYW5gIGlzIHRoZSBzYW5jdGlvbmVkIHNoYXBlOiBzaG9ydCBjbG9zdXJlcywgYW5kXG4gKiB0aGUgd2FpdGluZyBkb25lIGZyb20gTm9kZS5cbiAqL1xuXG4vKlxuICogVGhlIFczQyBlcnJvciBjb2RlIGlzIHRoZSBzcGFjZWQgYHNjcmlwdCB0aW1lb3V0YCwgd2hpbGUgYSBjbGllbnQgdGhhdCB0dXJucyBpdCBpbnRvIGEgdHlwZSBzcGVsbHMgdGhlXG4gKiBTYW1lIHRoaW5nIGFzIGBTY3JpcHRUaW1lb3V0RXJyb3JgIFx1MjAxNCBoZW5jZSB0aGUgb3B0aW9uYWwgd2hpdGVzcGFjZSwgd2hpY2ggbGV0cyBvbmUgcGF0dGVybiByZWFkIGJvdGguXG4gKi9cbmNvbnN0IFNDUklQVF9USU1FT1VUX1BBVFRFUk4gPSAvc2NyaXB0XFxzKnRpbWVvdXQvaTtcblxuLyoqXG4gKiBQYXJhbWV0ZXJzIGZvciB7QGxpbmsgRXZhbENhcEV4Y2VlZGVkRXJyb3J9J3MgY29uc3RydWN0b3IuXG4gKi9cbmV4cG9ydCBpbnRlcmZhY2UgRXZhbENhcEV4Y2VlZGVkRXJyb3JDb25zdHJ1Y3RvclBhcmFtcyB7XG4gIC8qKlxuICBUaGUgcGVyLWV2YWwgY2FwIHRoZSBjbG9zdXJlIG91dHJhbiwgaW4gbWlsbGlzZWNvbmRzLlxuICAgKi9cbiAgcmVhZG9ubHkgY2FwSW5NaWxsaXNlY29uZHM6IG51bWJlcjtcblxuICAvKipcbiAgVGhlIHVuZGVybHlpbmcgdHJhbnNwb3J0IGVycm9yLCBrZXB0IGFzIHRoZSBgY2F1c2VgIHNvIHRoZSByYXcgZGlhZ25vc2lzIGlzIG5vdCBsb3N0LlxuICAgKi9cbiAgcmVhZG9ubHkgY2F1c2U6IHVua25vd247XG5cbiAgLyoqXG4gIFRoZSBuYW1lIG9mIHRoZSBvcHRpb24gdGhhdCBzZXRzIHRoZSBjYXAgb24gdGhpcyB0cmFuc3BvcnQsIHNvIHRoZSBtZXNzYWdlIGNhbiBuYW1lIHRoZSByZWFsIGtub2IuXG4gICAqL1xuICByZWFkb25seSBvcHRpb25OYW1lOiBzdHJpbmc7XG5cbiAgLyoqXG4gIEhvdyB0byByZWZlciB0byB0aGUgdHJhbnNwb3J0IHRoYXQgZW5mb3JjZWQgdGhlIGNhcCwgZS5nLiBgJ0FuZHJvaWQgKEFwcGl1bSknYC5cbiAgICovXG4gIHJlYWRvbmx5IHRyYW5zcG9ydE5hbWU6IHN0cmluZztcbn1cblxuLyoqXG4gKiBUaHJvd24gd2hlbiBvbmUgYGV2YWxJbk9ic2lkaWFuYCBjbG9zdXJlIHJhbiBsb25nZXIgdGhhbiB0aGUgdHJhbnNwb3J0J3NcbiAqIHBlci1ldmFsIGNhcC5cbiAqXG4gKiBDYXJyaWVzIHRoZSBjYXAgYW5kIHRoZSB0cmFuc3BvcnQgc28gYSBjYWxsZXIgY2FuIGBpbnN0YW5jZW9mYC1tYXRjaCwgYW5kIHRoZVxuICogb3JpZ2luYWwgdHJhbnNwb3J0IGVycm9yIGFzIGBjYXVzZWAuXG4gKi9cbmV4cG9ydCBjbGFzcyBFdmFsQ2FwRXhjZWVkZWRFcnJvciBleHRlbmRzIEVycm9yIHtcbiAgLyoqXG4gIFRoZSBwZXItZXZhbCBjYXAgdGhlIGNsb3N1cmUgb3V0cmFuLCBpbiBtaWxsaXNlY29uZHMuXG4gICAqL1xuICBwdWJsaWMgcmVhZG9ubHkgY2FwSW5NaWxsaXNlY29uZHM6IG51bWJlcjtcblxuICAvKipcbiAgSG93IHRoZSB0cmFuc3BvcnQgdGhhdCBlbmZvcmNlZCB0aGUgY2FwIHdhcyBuYW1lZCBpbiB0aGUgbWVzc2FnZS5cbiAgICovXG4gIHB1YmxpYyByZWFkb25seSB0cmFuc3BvcnROYW1lOiBzdHJpbmc7XG5cbiAgLyoqXG4gICAqIENyZWF0ZXMgdGhlIGVycm9yIGZyb20gdGhlIGNhcCwgdGhlIHRyYW5zcG9ydCwgYW5kIHRoZSByYXcgZXJyb3IgaXQgcmVwbGFjZXMuXG4gICAqXG4gICAqIEBwYXJhbSBwYXJhbXMgLSBUaGUgY2FwLCB0aGUgdHJhbnNwb3J0LCB0aGUgb3B0aW9uIHRoYXQgc2V0cyB0aGUgY2FwLCBhbmQgdGhlIHVuZGVybHlpbmcgZXJyb3IuXG4gICAqL1xuICBwdWJsaWMgY29uc3RydWN0b3IocGFyYW1zOiBFdmFsQ2FwRXhjZWVkZWRFcnJvckNvbnN0cnVjdG9yUGFyYW1zKSB7XG4gICAgc3VwZXIoYnVpbGRNZXNzYWdlKHBhcmFtcyksIHsgY2F1c2U6IHBhcmFtcy5jYXVzZSB9KTtcbiAgICB0aGlzLm5hbWUgPSAnRXZhbENhcEV4Y2VlZGVkRXJyb3InO1xuICAgIHRoaXMuY2FwSW5NaWxsaXNlY29uZHMgPSBwYXJhbXMuY2FwSW5NaWxsaXNlY29uZHM7XG4gICAgdGhpcy50cmFuc3BvcnROYW1lID0gcGFyYW1zLnRyYW5zcG9ydE5hbWU7XG4gIH1cbn1cblxuLyoqXG4gKiBXaGV0aGVyIGFuIGVycm9yIGlzIGEgV2ViRHJpdmVyIHNjcmlwdCB0aW1lb3V0IFx1MjAxNCB0aGUgVzNDIGVycm9yIGEgZHJpdmVyIHdvdWxkXG4gKiByYWlzZSBpZiBpdCBlbmZvcmNlZCBgdGltZW91dHMuc2NyaXB0YC5cbiAqXG4gKiBNYXRjaGVkIG9uIHRoZSBtZXNzYWdlIHJhdGhlciB0aGFuIG9uIGEgdHlwZSwgYmVjYXVzZSB0aGUgZXJyb3IgYXJyaXZlcyBhcyBhXG4gKiBnZW5lcmljIGBXZWJEcml2ZXJFcnJvcmAgd2hvc2Ugb25seSBkaXN0aW5ndWlzaGluZyBtYXJrIGlzIHRoZSBXM0MgZXJyb3IgY29kZVxuICogaW4gaXRzIHRleHQuXG4gKlxuICogKipUaGlzIGRyaXZlciBuZXZlciByYWlzZXMgaXQuKiogVWlBdXRvbWF0b3IyIHdhcyBtZWFzdXJlZCBhY2NlcHRpbmcgdGhlXG4gKiBjYXBhYmlsaXR5LCByZXBvcnRpbmcgaXQgYmFjaywgYW5kIGVuZm9yY2luZyBub3RoaW5nLiBUaGUgcHJlZGljYXRlIGlzIGtlcHRcbiAqIGJlY2F1c2UgaXQgY29zdHMgbm90aGluZywgaXQgaXMgdGhlIHJpZ2h0IHRyYW5zbGF0aW9uIGlmIGEgZnV0dXJlIGRyaXZlciBkb2VzXG4gKiBlbmZvcmNlIHRoZSBjYXBhYmlsaXR5LCBhbmQgaXQga2VlcHMgb25lIGVycm9yIGNvdmVyaW5nIG9uZSBjb25kaXRpb24gb24gYm90aFxuICogdHJhbnNwb3J0cyBcdTIwMTQgYnV0IHRoZSBBbmRyb2lkIGNhcCBpcyBlbmZvcmNlZCBOb2RlLXNpZGUsIGFuZCB0aGlzIGlzIG5vdCB3aGF0XG4gKiBlbmZvcmNlcyBpdC5cbiAqXG4gKiBAcGFyYW0gZXJyb3IgLSBUaGUgZXJyb3IgdGhyb3duIGJ5IHRoZSB0cmFuc3BvcnQuXG4gKiBAcmV0dXJucyBgdHJ1ZWAgd2hlbiB0aGUgZXJyb3IgaXMgYSBzY3JpcHQgdGltZW91dC5cbiAqL1xuZXhwb3J0IGZ1bmN0aW9uIGlzU2NyaXB0VGltZW91dEVycm9yKGVycm9yOiB1bmtub3duKTogYm9vbGVhbiB7XG4gIGlmICghKGVycm9yIGluc3RhbmNlb2YgRXJyb3IpKSB7XG4gICAgcmV0dXJuIGZhbHNlO1xuICB9XG5cbiAgcmV0dXJuIFNDUklQVF9USU1FT1VUX1BBVFRFUk4udGVzdChlcnJvci5tZXNzYWdlKSB8fCBTQ1JJUFRfVElNRU9VVF9QQVRURVJOLnRlc3QoZXJyb3IubmFtZSk7XG59XG5cbi8qKlxuICogQnVpbGRzIHRoZSBzaGFyZWQgbWVzc2FnZSBib3RoIHRyYW5zcG9ydHMgcmVwb3J0LlxuICpcbiAqIEBwYXJhbSBwYXJhbXMgLSBUaGUgY2FwLCB0aGUgdHJhbnNwb3J0LCBhbmQgdGhlIG9wdGlvbiB0aGF0IHNldHMgdGhlIGNhcC5cbiAqIEByZXR1cm5zIFRoZSBtZXNzYWdlLlxuICovXG5mdW5jdGlvbiBidWlsZE1lc3NhZ2UocGFyYW1zOiBFdmFsQ2FwRXhjZWVkZWRFcnJvckNvbnN0cnVjdG9yUGFyYW1zKTogc3RyaW5nIHtcbiAgcmV0dXJuIGBBIHNpbmdsZSBldmFsSW5PYnNpZGlhbiBjbG9zdXJlIHJhbiBsb25nZXIgdGhhbiB0aGUgJHtwYXJhbXMudHJhbnNwb3J0TmFtZX0gcGVyLWV2YWwgY2FwIG9mICR7U3RyaW5nKHBhcmFtcy5jYXBJbk1pbGxpc2Vjb25kcyl9bXMsIHNvIGl0IHdhcyBraWxsZWQgbWlkLWZsaWdodC4gVGhpcyBpcyBhIHByb3BlcnR5IG9mIHRoZSBjbG9zdXJlLCBub3Qgb2YgdGhlIGRldmljZSBvciB0aGUgYXBwOiBgXG4gICAgKyAnZXZlcnl0aGluZyBhd2FpdGVkIGluc2lkZSBvbmUgY2xvc3VyZSBzaGFyZXMgdGhhdCBvbmUgYnVkZ2V0LCBpbmNsdWRpbmcgZXZlcnkgYGxpYi53YWl0VW50aWxgIHRpbWVvdXQgJ1xuICAgICsgJ2FuZCBldmVyeSBzZXR0bGUgYHNsZWVwYC4gRG8gdGhlIHdhaXRpbmcgZnJvbSBOb2RlIGluc3RlYWQgXHUyMDE0IGBwb2xsSW5PYnNpZGlhbmAgcnVucyBhIHNob3J0IGBwb2xsYCAnXG4gICAgKyAnY2xvc3VyZSByZXBlYXRlZGx5IHVudGlsIGEgTm9kZS1zaWRlIGB1bnRpbGAgYWNjZXB0cywgc28gbm8gc2luZ2xlIGV2YWwgaXMgZXZlciBsb25nLiBSYWlzZSAnXG4gICAgKyBgXFxgJHtwYXJhbXMub3B0aW9uTmFtZX1cXGAgb25seSBmb3IgYSBjbG9zdXJlIHRoYXQgZ2VudWluZWx5IGNhbm5vdCBiZSBzcGxpdC5gO1xufVxuIl0sCiAgIm1hcHBpbmdzIjogIjs7Ozs7Ozs7Ozs7Ozs7Ozs7O0FBQUE7QUFBQTtBQUFBO0FBQUE7QUFBQTtBQUFBO0FBa0NBLE1BQU0seUJBQXlCO0FBa0N4QixNQUFNLDZCQUE2QixNQUFNO0FBQUE7QUFBQTtBQUFBO0FBQUEsRUFJOUI7QUFBQTtBQUFBO0FBQUE7QUFBQSxFQUtBO0FBQUE7QUFBQTtBQUFBO0FBQUE7QUFBQTtBQUFBLEVBT1QsWUFBWSxRQUErQztBQUNoRSxVQUFNLGFBQWEsTUFBTSxHQUFHLEVBQUUsT0FBTyxPQUFPLE1BQU0sQ0FBQztBQUNuRCxTQUFLLE9BQU87QUFDWixTQUFLLG9CQUFvQixPQUFPO0FBQ2hDLFNBQUssZ0JBQWdCLE9BQU87QUFBQSxFQUM5QjtBQUNGO0FBb0JPLFNBQVMscUJBQXFCLE9BQXlCO0FBQzVELE1BQUksRUFBRSxpQkFBaUIsUUFBUTtBQUM3QixXQUFPO0FBQUEsRUFDVDtBQUVBLFNBQU8sdUJBQXVCLEtBQUssTUFBTSxPQUFPLEtBQUssdUJBQXVCLEtBQUssTUFBTSxJQUFJO0FBQzdGO0FBUUEsU0FBUyxhQUFhLFFBQXVEO0FBQzNFLFNBQU8sdURBQXVELE9BQU8sYUFBYSxvQkFBb0IsT0FBTyxPQUFPLGlCQUFpQixDQUFDLDBaQUk3SCxPQUFPLFVBQVU7QUFDNUI7IiwKICAibmFtZXMiOiBbXQp9Cg==

package/dist/lib/cjs/eval-cap-exceeded-error.d.cts

@@ -0,0 +1,92 @@
+/**
+ * @file
+ *
+ * The one error both transports raise when a single `evalInObsidian` closure
+ * outruns the per-eval cap, and the predicate that recognizes the raw transport
+ * error it replaces.
+ *
+ * The cap itself is not the problem this module solves — the diagnosis is.
+ * Desktop surfaces the overrun as a generic
+ * `CDP command timed out ... : Runtime.evaluate`, which never names the test's
+ * own wait and so reads as a broken device or a wedged app — a plugin release was
+ * once held for two days by that reading, with a healthy emulator blamed for
+ * having no network.
+ *
+ * Android is worse, because it surfaces NOTHING. On a live emulator the closure
+ * was measured completing in the guest on schedule — timers armed at 30s and 40s fired within
+ * ~13ms of nominal on a visible, focused page — while its Execute Script response
+ * never reached the client, so the call hung until whichever outer budget gave up
+ * first. A hang names nothing at all, which is why the Android cap is enforced by
+ * the transport on the Node side rather than by the `timeouts.script` capability
+ * it also declares and that nothing acts on.
+ *
+ * Both transports therefore funnel into the message below, which says what the cap
+ * is, which transport enforced it, and what to do instead.
+ *
+ * A closure that needs to wait longer than the cap should not be waiting inside
+ * Obsidian at all. `pollInObsidian` is the sanctioned shape: short closures, and
+ * the waiting done from Node.
+ */
+/**
+ * Parameters for {@link EvalCapExceededError}'s constructor.
+ */
+export interface EvalCapExceededErrorConstructorParams {
+    /**
+    The per-eval cap the closure outran, in milliseconds.
+     */
+    readonly capInMilliseconds: number;
+    /**
+    The underlying transport error, kept as the `cause` so the raw diagnosis is not lost.
+     */
+    readonly cause: unknown;
+    /**
+    The name of the option that sets the cap on this transport, so the message can name the real knob.
+     */
+    readonly optionName: string;
+    /**
+    How to refer to the transport that enforced the cap, e.g. `'Android (Appium)'`.
+     */
+    readonly transportName: string;
+}
+/**
+ * Thrown when one `evalInObsidian` closure ran longer than the transport's
+ * per-eval cap.
+ *
+ * Carries the cap and the transport so a caller can `instanceof`-match, and the
+ * original transport error as `cause`.
+ */
+export declare class EvalCapExceededError extends Error {
+    /**
+    The per-eval cap the closure outran, in milliseconds.
+     */
+    readonly capInMilliseconds: number;
+    /**
+    How the transport that enforced the cap was named in the message.
+     */
+    readonly transportName: string;
+    /**
+     * Creates the error from the cap, the transport, and the raw error it replaces.
+     *
+     * @param params - The cap, the transport, the option that sets the cap, and the underlying error.
+     */
+    constructor(params: EvalCapExceededErrorConstructorParams);
+}
+/**
+ * Whether an error is a WebDriver script timeout — the W3C error a driver would
+ * raise if it enforced `timeouts.script`.
+ *
+ * Matched on the message rather than on a type, because the error arrives as a
+ * generic `WebDriverError` whose only distinguishing mark is the W3C error code
+ * in its text.
+ *
+ * **This driver never raises it.** UiAutomator2 was measured accepting the
+ * capability, reporting it back, and enforcing nothing. The predicate is kept
+ * because it costs nothing, it is the right translation if a future driver does
+ * enforce the capability, and it keeps one error covering one condition on both
+ * transports — but the Android cap is enforced Node-side, and this is not what
+ * enforces it.
+ *
+ * @param error - The error thrown by the transport.
+ * @returns `true` when the error is a script timeout.
+ */
+export declare function isScriptTimeoutError(error: unknown): boolean;

package/dist/lib/cjs/eval-cap.cjs

@@ -0,0 +1,29 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var eval_cap_exports = {};
+__export(eval_cap_exports, {
+  DEFAULT_EVAL_CAP_IN_MILLISECONDS: () => DEFAULT_EVAL_CAP_IN_MILLISECONDS
+});
+module.exports = __toCommonJS(eval_cap_exports);
+const DEFAULT_EVAL_CAP_IN_MILLISECONDS = 3e4;
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  DEFAULT_EVAL_CAP_IN_MILLISECONDS
+});
+//# sourceMappingURL=data:application/json;base64,ewogICJ2ZXJzaW9uIjogMywKICAic291cmNlcyI6IFsiLi4vLi4vLi4vc3JjL2V2YWwtY2FwLnRzIl0sCiAgInNvdXJjZXNDb250ZW50IjogWyIvKipcbiAqIEBmaWxlXG4gKlxuICogVGhlIHBlci1ldmFsIGNhcDogaG93IGxvbmcgYSBzaW5nbGUgYGV2YWxJbk9ic2lkaWFuYCBjbG9zdXJlIG1heSBydW4gYmVmb3JlXG4gKiB0aGUgdHJhbnNwb3J0IGNhcnJ5aW5nIGl0IGdpdmVzIHVwLlxuICpcbiAqIEl0IGxpdmVzIGluIGl0cyBvd24gbW9kdWxlLCBhbmQgaXMgcmUtZXhwb3J0ZWQgZnJvbSB0aGUgcGFja2FnZSByb290LCBiZWNhdXNlXG4gKiBpdCBpcyB0aGUgc2luZ2xlIG1vc3QgbG9hZC1iZWFyaW5nIG51bWJlciBhIHRlc3QgYXV0aG9yIGhhcyB0byByZXNwZWN0IFx1MjAxNCBhbmRcbiAqIHVudGlsIHRoaXMgbW9kdWxlIGV4aXN0ZWQgdGhlcmUgd2FzIG5vdGhpbmcgdG8gaW1wb3J0LiBCb3RoIHRyYW5zcG9ydHMgaGVsZFxuICogdGhlIHNhbWUgMzBzIHByaXZhdGVseSwgc28gZXZlcnkgY29uc3VtZXIgdGhhdCBuZWVkZWQgdG8gc2l6ZSBhIGNsb3N1cmVcbiAqIHJlc3RhdGVkIGl0IGFzIGEgbGl0ZXJhbCB3aXRoIGEgY29tbWVudCBzYXlpbmcgd2hlcmUgdGhlIG51bWJlciBjYW1lIGZyb20uXG4gKiBUaGF0IGlzIGEgbWlycm9yIG5vdGhpbmcgbWFpbnRhaW5zOiByYWlzZSBhIGNhcCBoZXJlIGFuZCBldmVyeSByZXN0YXRlbWVudCBpc1xuICogc2lsZW50bHkgd3JvbmcgaW4gdGhlIGRpcmVjdGlvbiB0aGF0IHByb2R1Y2VzIHRoZSB1bnJlYWRhYmxlIGZhaWx1cmUsIGJlY2F1c2VcbiAqIHRoZSBjb25zdW1lciBnb2VzIG9uIGJlbGlldmluZyBpdCBoYXMgaGVhZHJvb20gaXQgbm8gbG9uZ2VyIGhhcy5cbiAqXG4gKiAqKlRoZSB0d28gdHJhbnNwb3J0cyBzaGFyZSB0aGlzIE9ORSBjb25zdGFudCByYXRoZXIgdGhhbiBhZ3JlZWluZyBieVxuICogY29pbmNpZGVuY2UuKiogVGhleSBlbmZvcmNlIGl0IHRocm91Z2ggZGlmZmVyZW50IGtub2JzIFx1MjAxNCBkZXNrdG9wIGJvdW5kcyB0aGVcbiAqIGBSdW50aW1lLmV2YWx1YXRlYCBDRFAgY29tbWFuZCAoYGNvbW1hbmRUaW1lb3V0SW5NaWxsaXNlY29uZHNgKSwgQW5kcm9pZFxuICogYm91bmRzIHRoZSBFeGVjdXRlIFNjcmlwdCBjYWxsIE5vZGUtc2lkZSAoYHNjcmlwdFRpbWVvdXRJbk1pbGxpc2Vjb25kc2ApIFx1MjAxNFxuICogYnV0IHRoZSBrbm9icyBhcmUgdHdvIGltcGxlbWVudGF0aW9ucyBvZiBvbmUgcG9saWN5LCBub3QgdHdvIHBvbGljaWVzIHRoYXRcbiAqIGhhcHBlbiB0byBhZ3JlZS4gQSByZWFkZXIgb2YgZWl0aGVyIGRlZmF1bHQgbm93IHNlZXMgd2hpY2ggaXQgaXMuXG4gKi9cblxuLyoqXG4gKiBUaGUgZGVmYXVsdCBwZXItZXZhbCBjYXAsIGluIG1pbGxpc2Vjb25kczogdGhlIGJ1ZGdldCBvbmUgYGV2YWxJbk9ic2lkaWFuYFxuICogY2xvc3VyZSBoYXMgdG8gZml0IGluc2lkZS5cbiAqXG4gKiBFdmVyeXRoaW5nIGF3YWl0ZWQgaW5zaWRlIGEgc2luZ2xlIGNsb3N1cmUgc2hhcmVzIHRoaXMgb25lIGJ1ZGdldCBcdTIwMTQgZXZlcnlcbiAqIGBsaWIud2FpdFVudGlsYCB0aW1lb3V0IGFuZCBldmVyeSBzZXR0bGUgYHNsZWVwYCBcdTIwMTQgc28gYSBjbG9zdXJlJ3MgZGVjbGFyZWRcbiAqIHdhaXRzIGhhdmUgdG8gc3VtIHRvIGxlc3MgdGhhbiB0aGlzLCBub3QgbWVyZWx5IGJlIGluZGl2aWR1YWxseSBzaG9ydGVyLlxuICpcbiAqIEFuIG92ZXJydW4gaXMgcmVwb3J0ZWQgYXMgYEV2YWxDYXBFeGNlZWRlZEVycm9yYCwgd2hpY2ggbmFtZXMgdGhlIGNhcCwgdGhlXG4gKiB0cmFuc3BvcnQgdGhhdCBlbmZvcmNlZCBpdCwgYW5kIHRoZSBvcHRpb24gdGhhdCBzZXRzIGl0LiBSYWlzaW5nIHRoYXQgb3B0aW9uXG4gKiBpcyBhbG1vc3QgbmV2ZXIgdGhlIHJpZ2h0IGFuc3dlcjogYSBjbG9zdXJlIHRoYXQgbmVlZHMgdG8gd2FpdCBsb25nZXIgdGhhblxuICogdGhpcyBzaG91bGQgbm90IGJlIHdhaXRpbmcgaW5zaWRlIE9ic2lkaWFuIGF0IGFsbC4gYHBvbGxJbk9ic2lkaWFuYCBpcyB0aGVcbiAqIHNhbmN0aW9uZWQgc2hhcGUgXHUyMDE0IHNob3J0IGNsb3N1cmVzLCB3aXRoIHRoZSB3YWl0aW5nIGRvbmUgZnJvbSBOb2RlIFx1MjAxNCBhbmQgaXRcbiAqIGV4aXN0cyBwcmVjaXNlbHkgc28gbm8gc2luZ2xlIGV2YWwgaXMgZXZlciBsb25nLlxuICpcbiAqIEJvdGggdHJhbnNwb3J0cyBkZWZhdWx0IHRvIHRoaXMgdmFsdWU6IGl0IGlzIHdoYXRcbiAqIGBPYnNpZGlhbkNkcFRyYW5zcG9ydE9wdGlvbnMuY29tbWFuZFRpbWVvdXRJbk1pbGxpc2Vjb25kc2AgYW5kXG4gKiBgT2JzaWRpYW5BbmRyb2lkQXBwaXVtVHJhbnNwb3J0T3B0aW9ucy5zY3JpcHRUaW1lb3V0SW5NaWxsaXNlY29uZHNgIGZhbGwgYmFja1xuICogdG8gd2hlbiB0aGV5IGFyZSBvbWl0dGVkLlxuICovXG5leHBvcnQgY29uc3QgREVGQVVMVF9FVkFMX0NBUF9JTl9NSUxMSVNFQ09ORFMgPSAzMF8wMDA7XG4iXSwKICAibWFwcGluZ3MiOiAiOzs7Ozs7Ozs7Ozs7Ozs7Ozs7QUFBQTtBQUFBO0FBQUE7QUFBQTtBQUFBO0FBMkNPLE1BQU0sbUNBQW1DOyIsCiAgIm5hbWVzIjogW10KfQo=

package/dist/lib/cjs/eval-cap.d.cts

@@ -0,0 +1,43 @@
+/**
+ * @file
+ *
+ * The per-eval cap: how long a single `evalInObsidian` closure may run before
+ * the transport carrying it gives up.
+ *
+ * It lives in its own module, and is re-exported from the package root, because
+ * it is the single most load-bearing number a test author has to respect — and
+ * until this module existed there was nothing to import. Both transports held
+ * the same 30s privately, so every consumer that needed to size a closure
+ * restated it as a literal with a comment saying where the number came from.
+ * That is a mirror nothing maintains: raise a cap here and every restatement is
+ * silently wrong in the direction that produces the unreadable failure, because
+ * the consumer goes on believing it has headroom it no longer has.
+ *
+ * **The two transports share this ONE constant rather than agreeing by
+ * coincidence.** They enforce it through different knobs — desktop bounds the
+ * `Runtime.evaluate` CDP command (`commandTimeoutInMilliseconds`), Android
+ * bounds the Execute Script call Node-side (`scriptTimeoutInMilliseconds`) —
+ * but the knobs are two implementations of one policy, not two policies that
+ * happen to agree. A reader of either default now sees which it is.
+ */
+/**
+ * The default per-eval cap, in milliseconds: the budget one `evalInObsidian`
+ * closure has to fit inside.
+ *
+ * Everything awaited inside a single closure shares this one budget — every
+ * `lib.waitUntil` timeout and every settle `sleep` — so a closure's declared
+ * waits have to sum to less than this, not merely be individually shorter.
+ *
+ * An overrun is reported as `EvalCapExceededError`, which names the cap, the
+ * transport that enforced it, and the option that sets it. Raising that option
+ * is almost never the right answer: a closure that needs to wait longer than
+ * this should not be waiting inside Obsidian at all. `pollInObsidian` is the
+ * sanctioned shape — short closures, with the waiting done from Node — and it
+ * exists precisely so no single eval is ever long.
+ *
+ * Both transports default to this value: it is what
+ * `ObsidianCdpTransportOptions.commandTimeoutInMilliseconds` and
+ * `ObsidianAndroidAppiumTransportOptions.scriptTimeoutInMilliseconds` fall back
+ * to when they are omitted.
+ */
+export declare const DEFAULT_EVAL_CAP_IN_MILLISECONDS = 30000;