obsidian-integration-testing 11.0.0 → 12.1.0

package/dist/lib/cjs/wedged-appium-server.d.cts

@@ -0,0 +1,187 @@
+/**
+ * @file
+ *
+ * Pure helpers for recognizing a **wedged** Appium server and deciding what to
+ * do about it. Kept separate from the integration-only `transport-factory` so
+ * the classification, the remedy decision and the message stay unit-testable
+ * (the factory itself needs a real device and is excluded from unit tests).
+ *
+ * A wedged server is one that is still **live** — it listens on its port and
+ * answers `/status` with `ready: true` — but is no longer **usable**: its
+ * `appium-adb` can no longer enumerate devices, so every session creation dies
+ * with `Could not find a connected Android device in <n>ms` while the host's own
+ * `adb devices` lists the device instantly. Liveness is not readiness, and the
+ * error names the wrong subject: it blames a device that is demonstrably
+ * present, which sends whoever reads it to `adb devices` — the one diagnostic
+ * that actively misleads here.
+ *
+ * The wedge develops over time in a long-lived server (one auto-started by an
+ * earlier run and left listening), so the preflight cannot see it coming: it can
+ * only be recognized from the failed session, cross-checked against the host's
+ * adb.
+ */
+/**
+ * Parameters for {@link buildWedgedAppiumServerMessage}.
+ */
+export interface BuildWedgedAppiumServerMessageParams {
+    /**
+    Origin of the Appium server that could not see the device (e.g. `http://localhost:4723`).
+     */
+    readonly appiumOrigin: string;
+    /**
+    The device the host's adb can see but Appium cannot.
+     */
+    readonly deviceId: string;
+    /**
+    Why this run is reporting rather than restarting.
+     */
+    readonly reason: WedgedAppiumServerReportReason;
+    /**
+    How long the server has been running, when known from its marker.
+     */
+    readonly serverAgeInMilliseconds?: number | undefined;
+    /**
+    PID of the server, when known from its marker.
+     */
+    readonly serverPid?: number | undefined;
+}
+/**
+ * The server is not to blame: either the failure was a different error, or the
+ * host's adb cannot see the device either. The original error is rethrown.
+ */
+export interface NotWedgedVerdict {
+    /**
+    Which of the two honest-failure cases this is.
+     */
+    readonly reason: 'device-absent' | 'other-error';
+    /**
+    Discriminant.
+     */
+    readonly remedy: 'not-wedged';
+}
+/**
+ * The server is wedged but must not be touched by this run.
+ */
+export interface ReportServerVerdict {
+    /**
+    Why this run is reporting rather than restarting.
+     */
+    readonly reason: WedgedAppiumServerReportReason;
+    /**
+    Discriminant.
+     */
+    readonly remedy: 'report';
+}
+/**
+ * Parameters for {@link resolveWedgedAppiumServerRemedy}.
+ */
+export interface ResolveWedgedAppiumServerRemedyParams {
+    /**
+    Device IDs the **host's** adb currently lists (the cross-check that convicts the server).
+     */
+    readonly connectedDeviceIds: readonly string[];
+    /**
+    The device the session was requested against.
+     */
+    readonly deviceId: string;
+    /**
+    The error the session attempt failed with.
+     */
+    readonly error: unknown;
+    /**
+    Whether the server was already listening and was adopted, rather than started by this run.
+     */
+    readonly isAdoptedServer: boolean;
+    /**
+    Whether this run may start an Appium server (`shouldAutoStartAppium` is not `false`).
+     */
+    readonly isAutoStartAllowed: boolean;
+    /**
+    Whether the adopted server's marker proves an earlier run of this harness started it.
+     */
+    readonly isHarnessOwnedServer: boolean;
+}
+/**
+ * The server is wedged and an earlier run of this harness started it, so this
+ * run may replace it.
+ */
+export interface RestartServerVerdict {
+    /**
+    Always the harness-owned case.
+     */
+    readonly reason: 'harness-owned';
+    /**
+    Discriminant.
+     */
+    readonly remedy: 'restart';
+}
+/**
+ * The classification of a failed session attempt.
+ *
+ * `'device-absent'` and `'other-error'` are the not-wedged verdicts: the
+ * original error was honest and is rethrown untouched.
+ */
+export type WedgedAppiumServerReason = 'device-absent' | 'harness-owned' | 'other-error' | WedgedAppiumServerReportReason;
+/**
+ * What the factory should do with a failed session attempt.
+ */
+export type WedgedAppiumServerRemedy = 'not-wedged' | 'report' | 'restart';
+/**
+ * Why a wedged server is only reported rather than restarted. Each maps to its
+ * own remedy sentence — the whole point of the rewrite is that the message says
+ * what *this* run can and cannot do about the server it found.
+ */
+export type WedgedAppiumServerReportReason = 'auto-start-disabled' | 'foreign-server' | 'freshly-started' | 'restart-did-not-help';
+/**
+ * The verdict on a failed session attempt, discriminated by `remedy` so a
+ * `'report'` verdict carries a reason {@link buildWedgedAppiumServerMessage} can
+ * turn into advice.
+ */
+export type WedgedAppiumServerVerdict = NotWedgedVerdict | ReportServerVerdict | RestartServerVerdict;
+/**
+ * Builds the error message that replaces `Could not find a connected Android
+ * device`, naming the **server** and stating the evidence — the host's adb can
+ * see the device, so the server is the thing that is stale.
+ *
+ * @param params - The server, the device, and why this run is not restarting it.
+ * @returns The message.
+ */
+export declare function buildWedgedAppiumServerMessage(params: BuildWedgedAppiumServerMessageParams): string;
+/**
+ * Checks whether a failed session attempt is `appium-adb`'s device-enumeration
+ * failure. The whole `cause` chain is searched, so WebdriverIO's wrapping of the
+ * server's error does not hide it.
+ *
+ * @param error - The error the session attempt failed with.
+ * @returns `true` when it is the device-not-found failure.
+ */
+export declare function checkIsAppiumDeviceNotFoundError(error: unknown): boolean;
+/**
+ * Checks whether an Appium `/status` body reports a server that is accepting new
+ * sessions.
+ *
+ * Deliberately **tolerant**: only an explicit `ready: false` (Appium sets it
+ * while shutting down) is treated as not-ready. A body that cannot be parsed, or
+ * that omits the flag, reads as ready — an unrecognized shape must not make a
+ * healthy server look unreachable.
+ *
+ * This does not catch the wedge (a wedged server still answers `ready: true`);
+ * it closes the adjacent hole of adopting a server that is on its way down.
+ *
+ * @param statusBody - The raw `/status` response body.
+ * @returns `false` only when the server explicitly reports itself not ready.
+ */
+export declare function checkIsAppiumStatusReady(statusBody: string): boolean;
+/**
+ * Decides what to do with a failed session attempt.
+ *
+ * The device-not-found error is only evidence against the server when the host's
+ * adb *can* still see the device; otherwise the error was honest and is left
+ * alone. A server this harness started in an earlier run is restarted (the
+ * confirmed remedy); every other wedged server is reported rather than killed,
+ * because terminating a process this run does not own is not its call to make.
+ *
+ * @param params - The failed attempt and what is known about the server.
+ * @returns The verdict.
+ */
+export declare function resolveWedgedAppiumServerRemedy(params: ResolveWedgedAppiumServerRemedyParams): WedgedAppiumServerVerdict;

package/dist/lib/esm/adb-device-list.d.mts

@@ -0,0 +1,72 @@
+/**
+ * @file
+ *
+ * Pure helpers for parsing `adb devices` output.
+ *
+ * Kept separate from the integration-only `transport-factory` (excluded from
+ * unit tests) so the parsing stays unit-testable — the factory itself shells out
+ * to `adb`.
+ *
+ * The listing answers two **different** questions, and conflating them is a
+ * defect rather than a nicety:
+ *
+ * - *Is the device usable?* — only a device in the `device` state is, which is
+ *   what the session preflight asks ({@link listOnlineDeviceIds}).
+ * - *Is the device gone?* — a dying emulator drops to `offline` while it still
+ *   holds the AVD's `multiinstance.lock` and its console port, so teardown must
+ *   treat **any** listed state as "still here" ({@link checkIsDeviceListed}).
+ *   Reading `offline` as gone is what lets the next run collide with a leftover.
+ */
+/**
+ * One row of `adb devices`.
+ */
+export interface AdbDeviceEntry {
+    /**
+    The device UDID, e.g. `emulator-5554`.
+     */
+    readonly deviceId: string;
+    /**
+    The device state adb reports, e.g. `device`, `offline`, `unauthorized`.
+     */
+    readonly state: string;
+}
+/**
+ * Parameters for {@link checkIsDeviceListed}.
+ */
+export interface CheckIsDeviceListedParams {
+    /**
+    The device UDID to look for.
+     */
+    readonly deviceId: string;
+    /**
+    Raw stdout of `adb devices`.
+     */
+    readonly devicesOutput: string;
+}
+/**
+ * Decides whether a device is still listed at all, **in any state**.
+ *
+ * This is teardown's question, not the preflight's: an emulator that answers
+ * `offline` has not released the AVD.
+ *
+ * @param params - The listing output and the device to look for.
+ * @returns `true` when the device appears in the listing, whatever its state.
+ */
+export declare function checkIsDeviceListed(params: CheckIsDeviceListedParams): boolean;
+/**
+ * Lists the devices that are actually usable — those in the `device` state.
+ *
+ * @param devicesOutput - Raw stdout of `adb devices`.
+ * @returns The online device IDs, in listed order.
+ */
+export declare function listOnlineDeviceIds(devicesOutput: string): string[];
+/**
+ * Parses the rows of `adb devices` into device IDs and states.
+ *
+ * Every row is `<id>\t<state>`; the `List of devices attached` header and the
+ * `* daemon … *` banner carry no tab, which is what distinguishes them.
+ *
+ * @param devicesOutput - Raw stdout of `adb devices`.
+ * @returns One entry per listed device, in listed order.
+ */
+export declare function parseAdbDevices(devicesOutput: string): AdbDeviceEntry[];

package/dist/lib/esm/adb-device-list.mjs

@@ -0,0 +1,28 @@
+const ONLINE_DEVICE_STATE = "device";
+function checkIsDeviceListed(params) {
+  return parseAdbDevices(params.devicesOutput).some((entry) => entry.deviceId === params.deviceId);
+}
+function listOnlineDeviceIds(devicesOutput) {
+  return parseAdbDevices(devicesOutput).filter((entry) => entry.state === ONLINE_DEVICE_STATE).map((entry) => entry.deviceId);
+}
+function parseAdbDevices(devicesOutput) {
+  const entries = [];
+  for (const rawLine of devicesOutput.split("\n")) {
+    const line = rawLine.trim();
+    const separatorIndex = line.indexOf("	");
+    if (separatorIndex === -1) {
+      continue;
+    }
+    entries.push({
+      deviceId: line.slice(0, separatorIndex).trim(),
+      state: line.slice(separatorIndex + 1).trim()
+    });
+  }
+  return entries;
+}
+export {
+  checkIsDeviceListed,
+  listOnlineDeviceIds,
+  parseAdbDevices
+};
+//# sourceMappingURL=data:application/json;base64,ewogICJ2ZXJzaW9uIjogMywKICAic291cmNlcyI6IFsiLi4vLi4vLi4vc3JjL2FkYi1kZXZpY2UtbGlzdC50cyJdLAogICJzb3VyY2VzQ29udGVudCI6IFsiLyoqXG4gKiBAZmlsZVxuICpcbiAqIFB1cmUgaGVscGVycyBmb3IgcGFyc2luZyBgYWRiIGRldmljZXNgIG91dHB1dC5cbiAqXG4gKiBLZXB0IHNlcGFyYXRlIGZyb20gdGhlIGludGVncmF0aW9uLW9ubHkgYHRyYW5zcG9ydC1mYWN0b3J5YCAoZXhjbHVkZWQgZnJvbVxuICogdW5pdCB0ZXN0cykgc28gdGhlIHBhcnNpbmcgc3RheXMgdW5pdC10ZXN0YWJsZSBcdTIwMTQgdGhlIGZhY3RvcnkgaXRzZWxmIHNoZWxscyBvdXRcbiAqIHRvIGBhZGJgLlxuICpcbiAqIFRoZSBsaXN0aW5nIGFuc3dlcnMgdHdvICoqZGlmZmVyZW50KiogcXVlc3Rpb25zLCBhbmQgY29uZmxhdGluZyB0aGVtIGlzIGFcbiAqIGRlZmVjdCByYXRoZXIgdGhhbiBhIG5pY2V0eTpcbiAqXG4gKiAtICpJcyB0aGUgZGV2aWNlIHVzYWJsZT8qIFx1MjAxNCBvbmx5IGEgZGV2aWNlIGluIHRoZSBgZGV2aWNlYCBzdGF0ZSBpcywgd2hpY2ggaXNcbiAqICAgd2hhdCB0aGUgc2Vzc2lvbiBwcmVmbGlnaHQgYXNrcyAoe0BsaW5rIGxpc3RPbmxpbmVEZXZpY2VJZHN9KS5cbiAqIC0gKklzIHRoZSBkZXZpY2UgZ29uZT8qIFx1MjAxNCBhIGR5aW5nIGVtdWxhdG9yIGRyb3BzIHRvIGBvZmZsaW5lYCB3aGlsZSBpdCBzdGlsbFxuICogICBob2xkcyB0aGUgQVZEJ3MgYG11bHRpaW5zdGFuY2UubG9ja2AgYW5kIGl0cyBjb25zb2xlIHBvcnQsIHNvIHRlYXJkb3duIG11c3RcbiAqICAgdHJlYXQgKiphbnkqKiBsaXN0ZWQgc3RhdGUgYXMgXCJzdGlsbCBoZXJlXCIgKHtAbGluayBjaGVja0lzRGV2aWNlTGlzdGVkfSkuXG4gKiAgIFJlYWRpbmcgYG9mZmxpbmVgIGFzIGdvbmUgaXMgd2hhdCBsZXRzIHRoZSBuZXh0IHJ1biBjb2xsaWRlIHdpdGggYSBsZWZ0b3Zlci5cbiAqL1xuXG4vKipcbiAqIE9uZSByb3cgb2YgYGFkYiBkZXZpY2VzYC5cbiAqL1xuZXhwb3J0IGludGVyZmFjZSBBZGJEZXZpY2VFbnRyeSB7XG4gIC8qKlxuICBUaGUgZGV2aWNlIFVESUQsIGUuZy4gYGVtdWxhdG9yLTU1NTRgLlxuICAgKi9cbiAgcmVhZG9ubHkgZGV2aWNlSWQ6IHN0cmluZztcblxuICAvKipcbiAgVGhlIGRldmljZSBzdGF0ZSBhZGIgcmVwb3J0cywgZS5nLiBgZGV2aWNlYCwgYG9mZmxpbmVgLCBgdW5hdXRob3JpemVkYC5cbiAgICovXG4gIHJlYWRvbmx5IHN0YXRlOiBzdHJpbmc7XG59XG5cbi8qKlxuICogUGFyYW1ldGVycyBmb3Ige0BsaW5rIGNoZWNrSXNEZXZpY2VMaXN0ZWR9LlxuICovXG5leHBvcnQgaW50ZXJmYWNlIENoZWNrSXNEZXZpY2VMaXN0ZWRQYXJhbXMge1xuICAvKipcbiAgVGhlIGRldmljZSBVRElEIHRvIGxvb2sgZm9yLlxuICAgKi9cbiAgcmVhZG9ubHkgZGV2aWNlSWQ6IHN0cmluZztcblxuICAvKipcbiAgUmF3IHN0ZG91dCBvZiBgYWRiIGRldmljZXNgLlxuICAgKi9cbiAgcmVhZG9ubHkgZGV2aWNlc091dHB1dDogc3RyaW5nO1xufVxuXG5jb25zdCBPTkxJTkVfREVWSUNFX1NUQVRFID0gJ2RldmljZSc7XG5cbi8qKlxuICogRGVjaWRlcyB3aGV0aGVyIGEgZGV2aWNlIGlzIHN0aWxsIGxpc3RlZCBhdCBhbGwsICoqaW4gYW55IHN0YXRlKiouXG4gKlxuICogVGhpcyBpcyB0ZWFyZG93bidzIHF1ZXN0aW9uLCBub3QgdGhlIHByZWZsaWdodCdzOiBhbiBlbXVsYXRvciB0aGF0IGFuc3dlcnNcbiAqIGBvZmZsaW5lYCBoYXMgbm90IHJlbGVhc2VkIHRoZSBBVkQuXG4gKlxuICogQHBhcmFtIHBhcmFtcyAtIFRoZSBsaXN0aW5nIG91dHB1dCBhbmQgdGhlIGRldmljZSB0byBsb29rIGZvci5cbiAqIEByZXR1cm5zIGB0cnVlYCB3aGVuIHRoZSBkZXZpY2UgYXBwZWFycyBpbiB0aGUgbGlzdGluZywgd2hhdGV2ZXIgaXRzIHN0YXRlLlxuICovXG5leHBvcnQgZnVuY3Rpb24gY2hlY2tJc0RldmljZUxpc3RlZChwYXJhbXM6IENoZWNrSXNEZXZpY2VMaXN0ZWRQYXJhbXMpOiBib29sZWFuIHtcbiAgcmV0dXJuIHBhcnNlQWRiRGV2aWNlcyhwYXJhbXMuZGV2aWNlc091dHB1dCkuc29tZSgoZW50cnkpID0+IGVudHJ5LmRldmljZUlkID09PSBwYXJhbXMuZGV2aWNlSWQpO1xufVxuXG4vKipcbiAqIExpc3RzIHRoZSBkZXZpY2VzIHRoYXQgYXJlIGFjdHVhbGx5IHVzYWJsZSBcdTIwMTQgdGhvc2UgaW4gdGhlIGBkZXZpY2VgIHN0YXRlLlxuICpcbiAqIEBwYXJhbSBkZXZpY2VzT3V0cHV0IC0gUmF3IHN0ZG91dCBvZiBgYWRiIGRldmljZXNgLlxuICogQHJldHVybnMgVGhlIG9ubGluZSBkZXZpY2UgSURzLCBpbiBsaXN0ZWQgb3JkZXIuXG4gKi9cbmV4cG9ydCBmdW5jdGlvbiBsaXN0T25saW5lRGV2aWNlSWRzKGRldmljZXNPdXRwdXQ6IHN0cmluZyk6IHN0cmluZ1tdIHtcbiAgcmV0dXJuIHBhcnNlQWRiRGV2aWNlcyhkZXZpY2VzT3V0cHV0KVxuICAgIC5maWx0ZXIoKGVudHJ5KSA9PiBlbnRyeS5zdGF0ZSA9PT0gT05MSU5FX0RFVklDRV9TVEFURSlcbiAgICAubWFwKChlbnRyeSkgPT4gZW50cnkuZGV2aWNlSWQpO1xufVxuXG4vKipcbiAqIFBhcnNlcyB0aGUgcm93cyBvZiBgYWRiIGRldmljZXNgIGludG8gZGV2aWNlIElEcyBhbmQgc3RhdGVzLlxuICpcbiAqIEV2ZXJ5IHJvdyBpcyBgPGlkPlxcdDxzdGF0ZT5gOyB0aGUgYExpc3Qgb2YgZGV2aWNlcyBhdHRhY2hlZGAgaGVhZGVyIGFuZCB0aGVcbiAqIGAqIGRhZW1vbiBcdTIwMjYgKmAgYmFubmVyIGNhcnJ5IG5vIHRhYiwgd2hpY2ggaXMgd2hhdCBkaXN0aW5ndWlzaGVzIHRoZW0uXG4gKlxuICogQHBhcmFtIGRldmljZXNPdXRwdXQgLSBSYXcgc3Rkb3V0IG9mIGBhZGIgZGV2aWNlc2AuXG4gKiBAcmV0dXJucyBPbmUgZW50cnkgcGVyIGxpc3RlZCBkZXZpY2UsIGluIGxpc3RlZCBvcmRlci5cbiAqL1xuZXhwb3J0IGZ1bmN0aW9uIHBhcnNlQWRiRGV2aWNlcyhkZXZpY2VzT3V0cHV0OiBzdHJpbmcpOiBBZGJEZXZpY2VFbnRyeVtdIHtcbiAgY29uc3QgZW50cmllczogQWRiRGV2aWNlRW50cnlbXSA9IFtdO1xuXG4gIGZvciAoY29uc3QgcmF3TGluZSBvZiBkZXZpY2VzT3V0cHV0LnNwbGl0KCdcXG4nKSkge1xuICAgIGNvbnN0IGxpbmUgPSByYXdMaW5lLnRyaW0oKTtcbiAgICBjb25zdCBzZXBhcmF0b3JJbmRleCA9IGxpbmUuaW5kZXhPZignXFx0Jyk7XG4gICAgaWYgKHNlcGFyYXRvckluZGV4ID09PSAtMSkge1xuICAgICAgY29udGludWU7XG4gICAgfVxuXG4gICAgZW50cmllcy5wdXNoKHtcbiAgICAgIGRldmljZUlkOiBsaW5lLnNsaWNlKDAsIHNlcGFyYXRvckluZGV4KS50cmltKCksXG4gICAgICBzdGF0ZTogbGluZS5zbGljZShzZXBhcmF0b3JJbmRleCArIDEpLnRyaW0oKVxuICAgIH0pO1xuICB9XG5cbiAgcmV0dXJuIGVudHJpZXM7XG59XG4iXSwKICAibWFwcGluZ3MiOiAiQUFrREEsTUFBTSxzQkFBc0I7QUFXckIsU0FBUyxvQkFBb0IsUUFBNEM7QUFDOUUsU0FBTyxnQkFBZ0IsT0FBTyxhQUFhLEVBQUUsS0FBSyxDQUFDLFVBQVUsTUFBTSxhQUFhLE9BQU8sUUFBUTtBQUNqRztBQVFPLFNBQVMsb0JBQW9CLGVBQWlDO0FBQ25FLFNBQU8sZ0JBQWdCLGFBQWEsRUFDakMsT0FBTyxDQUFDLFVBQVUsTUFBTSxVQUFVLG1CQUFtQixFQUNyRCxJQUFJLENBQUMsVUFBVSxNQUFNLFFBQVE7QUFDbEM7QUFXTyxTQUFTLGdCQUFnQixlQUF5QztBQUN2RSxRQUFNLFVBQTRCLENBQUM7QUFFbkMsYUFBVyxXQUFXLGNBQWMsTUFBTSxJQUFJLEdBQUc7QUFDL0MsVUFBTSxPQUFPLFFBQVEsS0FBSztBQUMxQixVQUFNLGlCQUFpQixLQUFLLFFBQVEsR0FBSTtBQUN4QyxRQUFJLG1CQUFtQixJQUFJO0FBQ3pCO0FBQUEsSUFDRjtBQUVBLFlBQVEsS0FBSztBQUFBLE1BQ1gsVUFBVSxLQUFLLE1BQU0sR0FBRyxjQUFjLEVBQUUsS0FBSztBQUFBLE1BQzdDLE9BQU8sS0FBSyxNQUFNLGlCQUFpQixDQUFDLEVBQUUsS0FBSztBQUFBLElBQzdDLENBQUM7QUFBQSxFQUNIO0FBRUEsU0FBTztBQUNUOyIsCiAgIm5hbWVzIjogW10KfQo=

package/dist/lib/esm/android-sdk.d.mts

@@ -0,0 +1,29 @@
+/**
+ * @file
+ *
+ * Resolves the Android SDK binaries the harness shells out to.
+ *
+ * Lives here rather than as a private method on the integration-only
+ * `transport-factory` because it is an **agreement**, not an implementation
+ * detail: `scripts/emulator-wedge-probe.ts` exists to reproduce a host fault by
+ * booting the emulator exactly as a run would, and a probe that resolved a
+ * different binary than the harness would quietly measure something else. One
+ * function, one answer, both callers.
+ *
+ * The lookup itself is the SDK's own convention — `ANDROID_HOME` first, then the
+ * older `ANDROID_SDK_ROOT` — and it deliberately does **not** fall back to a
+ * platform-default install path. A wrong guess would boot some other SDK's
+ * emulator and report on it as though it were the configured one; an error that
+ * names both variables is the shorter route to a working setup.
+ */
+/**
+ * Resolves the `emulator` binary from the Android SDK root.
+ *
+ * No extension is appended: Node's process spawning resolves `emulator.exe` on
+ * Windows on its own, and the same path string is what the SDK's own tooling
+ * documents.
+ *
+ * @returns The absolute path to the `emulator` binary.
+ * @throws When neither `ANDROID_HOME` nor `ANDROID_SDK_ROOT` is set.
+ */
+export declare function resolveEmulatorBinaryPath(): string;

package/dist/lib/esm/android-sdk.mjs

@@ -0,0 +1,18 @@
+import { join } from "node:path";
+import process from "node:process";
+function resolveEmulatorBinaryPath() {
+  return join(resolveAndroidSdkRoot(), "emulator", "emulator");
+}
+function resolveAndroidSdkRoot() {
+  const sdkRoot = process.env["ANDROID_HOME"] ?? process.env["ANDROID_SDK_ROOT"];
+  if (!sdkRoot) {
+    throw new Error(
+      "Cannot find Android emulator: neither ANDROID_HOME nor ANDROID_SDK_ROOT environment variable is set."
+    );
+  }
+  return sdkRoot;
+}
+export {
+  resolveEmulatorBinaryPath
+};
+//# sourceMappingURL=data:application/json;base64,ewogICJ2ZXJzaW9uIjogMywKICAic291cmNlcyI6IFsiLi4vLi4vLi4vc3JjL2FuZHJvaWQtc2RrLnRzIl0sCiAgInNvdXJjZXNDb250ZW50IjogWyIvKipcbiAqIEBmaWxlXG4gKlxuICogUmVzb2x2ZXMgdGhlIEFuZHJvaWQgU0RLIGJpbmFyaWVzIHRoZSBoYXJuZXNzIHNoZWxscyBvdXQgdG8uXG4gKlxuICogTGl2ZXMgaGVyZSByYXRoZXIgdGhhbiBhcyBhIHByaXZhdGUgbWV0aG9kIG9uIHRoZSBpbnRlZ3JhdGlvbi1vbmx5XG4gKiBgdHJhbnNwb3J0LWZhY3RvcnlgIGJlY2F1c2UgaXQgaXMgYW4gKiphZ3JlZW1lbnQqKiwgbm90IGFuIGltcGxlbWVudGF0aW9uXG4gKiBkZXRhaWw6IGBzY3JpcHRzL2VtdWxhdG9yLXdlZGdlLXByb2JlLnRzYCBleGlzdHMgdG8gcmVwcm9kdWNlIGEgaG9zdCBmYXVsdCBieVxuICogYm9vdGluZyB0aGUgZW11bGF0b3IgZXhhY3RseSBhcyBhIHJ1biB3b3VsZCwgYW5kIGEgcHJvYmUgdGhhdCByZXNvbHZlZCBhXG4gKiBkaWZmZXJlbnQgYmluYXJ5IHRoYW4gdGhlIGhhcm5lc3Mgd291bGQgcXVpZXRseSBtZWFzdXJlIHNvbWV0aGluZyBlbHNlLiBPbmVcbiAqIGZ1bmN0aW9uLCBvbmUgYW5zd2VyLCBib3RoIGNhbGxlcnMuXG4gKlxuICogVGhlIGxvb2t1cCBpdHNlbGYgaXMgdGhlIFNESydzIG93biBjb252ZW50aW9uIFx1MjAxNCBgQU5EUk9JRF9IT01FYCBmaXJzdCwgdGhlbiB0aGVcbiAqIG9sZGVyIGBBTkRST0lEX1NES19ST09UYCBcdTIwMTQgYW5kIGl0IGRlbGliZXJhdGVseSBkb2VzICoqbm90KiogZmFsbCBiYWNrIHRvIGFcbiAqIHBsYXRmb3JtLWRlZmF1bHQgaW5zdGFsbCBwYXRoLiBBIHdyb25nIGd1ZXNzIHdvdWxkIGJvb3Qgc29tZSBvdGhlciBTREsnc1xuICogZW11bGF0b3IgYW5kIHJlcG9ydCBvbiBpdCBhcyB0aG91Z2ggaXQgd2VyZSB0aGUgY29uZmlndXJlZCBvbmU7IGFuIGVycm9yIHRoYXRcbiAqIG5hbWVzIGJvdGggdmFyaWFibGVzIGlzIHRoZSBzaG9ydGVyIHJvdXRlIHRvIGEgd29ya2luZyBzZXR1cC5cbiAqL1xuXG5pbXBvcnQgeyBqb2luIH0gZnJvbSAnbm9kZTpwYXRoJztcbmltcG9ydCBwcm9jZXNzIGZyb20gJ25vZGU6cHJvY2Vzcyc7XG5cbi8qKlxuICogUmVzb2x2ZXMgdGhlIGBlbXVsYXRvcmAgYmluYXJ5IGZyb20gdGhlIEFuZHJvaWQgU0RLIHJvb3QuXG4gKlxuICogTm8gZXh0ZW5zaW9uIGlzIGFwcGVuZGVkOiBOb2RlJ3MgcHJvY2VzcyBzcGF3bmluZyByZXNvbHZlcyBgZW11bGF0b3IuZXhlYCBvblxuICogV2luZG93cyBvbiBpdHMgb3duLCBhbmQgdGhlIHNhbWUgcGF0aCBzdHJpbmcgaXMgd2hhdCB0aGUgU0RLJ3Mgb3duIHRvb2xpbmdcbiAqIGRvY3VtZW50cy5cbiAqXG4gKiBAcmV0dXJucyBUaGUgYWJzb2x1dGUgcGF0aCB0byB0aGUgYGVtdWxhdG9yYCBiaW5hcnkuXG4gKiBAdGhyb3dzIFdoZW4gbmVpdGhlciBgQU5EUk9JRF9IT01FYCBub3IgYEFORFJPSURfU0RLX1JPT1RgIGlzIHNldC5cbiAqL1xuZXhwb3J0IGZ1bmN0aW9uIHJlc29sdmVFbXVsYXRvckJpbmFyeVBhdGgoKTogc3RyaW5nIHtcbiAgcmV0dXJuIGpvaW4ocmVzb2x2ZUFuZHJvaWRTZGtSb290KCksICdlbXVsYXRvcicsICdlbXVsYXRvcicpO1xufVxuXG5mdW5jdGlvbiByZXNvbHZlQW5kcm9pZFNka1Jvb3QoKTogc3RyaW5nIHtcbiAgY29uc3Qgc2RrUm9vdCA9IHByb2Nlc3MuZW52WydBTkRST0lEX0hPTUUnXSA/PyBwcm9jZXNzLmVudlsnQU5EUk9JRF9TREtfUk9PVCddO1xuICBpZiAoIXNka1Jvb3QpIHtcbiAgICB0aHJvdyBuZXcgRXJyb3IoXG4gICAgICAnQ2Fubm90IGZpbmQgQW5kcm9pZCBlbXVsYXRvcjogbmVpdGhlciBBTkRST0lEX0hPTUUgbm9yIEFORFJPSURfU0RLX1JPT1QgZW52aXJvbm1lbnQgdmFyaWFibGUgaXMgc2V0LidcbiAgICApO1xuICB9XG5cbiAgcmV0dXJuIHNka1Jvb3Q7XG59XG4iXSwKICAibWFwcGluZ3MiOiAiQUFtQkEsU0FBUyxZQUFZO0FBQ3JCLE9BQU8sYUFBYTtBQVliLFNBQVMsNEJBQW9DO0FBQ2xELFNBQU8sS0FBSyxzQkFBc0IsR0FBRyxZQUFZLFVBQVU7QUFDN0Q7QUFFQSxTQUFTLHdCQUFnQztBQUN2QyxRQUFNLFVBQVUsUUFBUSxJQUFJLGNBQWMsS0FBSyxRQUFRLElBQUksa0JBQWtCO0FBQzdFLE1BQUksQ0FBQyxTQUFTO0FBQ1osVUFBTSxJQUFJO0FBQUEsTUFDUjtBQUFBLElBQ0Y7QUFBQSxFQUNGO0FBRUEsU0FBTztBQUNUOyIsCiAgIm5hbWVzIjogW10KfQo=

package/dist/lib/esm/app-startup-progress.d.mts

@@ -0,0 +1,128 @@
+/**
+ * @file
+ *
+ * Pure helpers for tracking how far Obsidian Mobile has got through its startup
+ * after `location.reload()`, and for describing where it stalled when a budget
+ * runs out.
+ *
+ * Startup is watched as a **ladder of milestones**, not a single boolean,
+ * because the two halves of it cost wildly different amounts of time and only
+ * one of them is Obsidian's fault. Reaching `globalThis.app` is the app cold
+ * start — the WebView reloading, the guest still churning — and on a cold or
+ * contended emulator it can take minutes. Everything after it is Obsidian
+ * opening the vault and loading plugins, which **L19** measured at ~1s (≤8.4s
+ * under 12-core + disk + memory stress). Charging both to one 90s wall clock is
+ * what made a first run after a machine restart fail by design, so the transport
+ * runs them as two budgets and uses these helpers to tell them apart.
+ *
+ * Kept separate from the integration-only `transport-appium` (excluded from unit
+ * tests) so the classification and message formatting stay unit-testable — the
+ * polling itself needs a real device.
+ */
+/**
+ * How far Obsidian has got through its startup, as seen from one WebView probe.
+ *
+ * Ordered from least to most advanced; {@link compareAppStartupMilestones}
+ * relies on that order.
+ */
+export type AppStartupMilestone = 'layout-ready' | 'no-app' | 'no-webview' | 'no-workspace' | 'workspace-not-ready';
+/**
+ * Which of the two startup budgets was being spent when it ran out.
+ */
+export type AppStartupPhase = 'app-start' | 'layout-ready';
+/**
+ * Parameters for {@link buildStartupTimeoutMessage}.
+ */
+export interface BuildStartupTimeoutMessageParams {
+    /**
+    How long this phase's budget had been spent when it ran out.
+     */
+    readonly elapsedInMilliseconds: number;
+    /**
+    The furthest milestone reached before the budget ran out.
+     */
+    readonly milestone: AppStartupMilestone;
+    /**
+    The phase whose budget ran out.
+     */
+    readonly phase: AppStartupPhase;
+    /**
+    How many probes were made during the phase.
+     */
+    readonly pollCount: number;
+    /**
+    The slowest single probe round-trip observed during the phase.
+     */
+    readonly slowestRoundTripInMilliseconds: number;
+    /**
+    The budget that ran out.
+     */
+    readonly timeoutInMilliseconds: number;
+}
+/**
+ * The raw shape a WebView startup probe reports back.
+ *
+ * Mirrors what the injected probe function can observe without importing
+ * anything: whether the global `app` object exists yet, whether its `workspace`
+ * does, and whether that workspace has finished laying out.
+ */
+export interface StartupProbeResult {
+    /**
+    Whether `globalThis.app` is defined.
+     */
+    readonly hasApp: boolean;
+    /**
+    Whether `app.workspace` is defined.
+     */
+    readonly hasWorkspace: boolean;
+    /**
+    Whether `app.workspace.layoutReady` is truthy.
+     */
+    readonly isLayoutReady: boolean;
+}
+/**
+ * Builds the diagnostic message for a startup budget that ran out.
+ *
+ * It names the milestone actually reached, the poll count and the slowest probe
+ * round-trip, because those three together separate the failure modes **L19**
+ * could not tell apart from the old message: a genuine Obsidian slowdown shows
+ * many fast polls stalled at one milestone, whereas a contended guest shows a
+ * handful of polls each taking tens of seconds.
+ *
+ * @param params - The phase, the milestone reached, and the timing evidence.
+ * @returns A human-readable error message.
+ */
+export declare function buildStartupTimeoutMessage(params: BuildStartupTimeoutMessageParams): string;
+/**
+ * Reports whether the app-start phase is satisfied at this milestone.
+ *
+ * @param milestone - The milestone the latest probe reported.
+ * @returns `true` once `globalThis.app` exists, so the layout-ready budget may start.
+ */
+export declare function checkAppStarted(milestone: AppStartupMilestone): boolean;
+/**
+ * Reports whether the layout-ready phase is satisfied at this milestone.
+ *
+ * @param milestone - The milestone the latest probe reported.
+ * @returns `true` once the workspace has finished laying out.
+ */
+export declare function checkLayoutReady(milestone: AppStartupMilestone): boolean;
+/**
+ * Turns a WebView probe into a milestone.
+ *
+ * A probe that could not run at all — `undefined`, because `browser.execute()`
+ * threw while the page was mid-reload — is the least advanced milestone rather
+ * than an error: during a reload it is the expected reading.
+ *
+ * @param probeResult - What the probe reported, or `undefined` when it threw.
+ * @returns The milestone that reading represents.
+ */
+export declare function classifyAppStartupProbe(probeResult: StartupProbeResult | undefined): AppStartupMilestone;
+/**
+ * Orders two milestones on the startup ladder.
+ *
+ * @param left - The first milestone.
+ * @param right - The second milestone.
+ * @returns A negative number when `left` is less advanced, `0` when equal, a positive number when more advanced.
+ */
+export declare function compareAppStartupMilestones(left: AppStartupMilestone, right: AppStartupMilestone): number;

package/dist/lib/esm/app-startup-progress.mjs

@@ -0,0 +1,59 @@
+const MILESTONE_ORDER = [
+  "no-webview",
+  "no-app",
+  "no-workspace",
+  "workspace-not-ready",
+  "layout-ready"
+];
+const APP_STARTED_MILESTONE = "no-workspace";
+const MILESTONE_DESCRIPTIONS = {
+  "layout-ready": "the workspace finished laying out",
+  "no-app": "the WebView answered, but `globalThis.app` never appeared",
+  "no-webview": "the WebView never answered a single probe",
+  "no-workspace": "`globalThis.app` appeared, but `app.workspace` never did",
+  "workspace-not-ready": "`app.workspace` exists, but `layoutReady` never became true"
+};
+const PHASE_DESCRIPTIONS = {
+  "app-start": "Obsidian Mobile did not finish starting",
+  "layout-ready": "Obsidian layout did not become ready"
+};
+function buildStartupTimeoutMessage(params) {
+  const {
+    elapsedInMilliseconds,
+    milestone,
+    phase,
+    pollCount,
+    slowestRoundTripInMilliseconds,
+    timeoutInMilliseconds
+  } = params;
+  return `${PHASE_DESCRIPTIONS[phase]} within ${String(timeoutInMilliseconds)}ms (elapsed ${String(elapsedInMilliseconds)}ms). Furthest progress: ${MILESTONE_DESCRIPTIONS[milestone]}. Probed ${String(pollCount)} time(s), slowest round-trip ${String(slowestRoundTripInMilliseconds)}ms. A handful of probes each taking tens of seconds means a contended guest, not a slow Obsidian \u2014 let the emulator go idle before the run, or raise \`deviceIdleTimeoutInMilliseconds\`.`;
+}
+function checkAppStarted(milestone) {
+  return compareAppStartupMilestones(milestone, APP_STARTED_MILESTONE) >= 0;
+}
+function checkLayoutReady(milestone) {
+  return milestone === "layout-ready";
+}
+function classifyAppStartupProbe(probeResult) {
+  if (!probeResult) {
+    return "no-webview";
+  }
+  if (!probeResult.hasApp) {
+    return "no-app";
+  }
+  if (!probeResult.hasWorkspace) {
+    return "no-workspace";
+  }
+  return probeResult.isLayoutReady ? "layout-ready" : "workspace-not-ready";
+}
+function compareAppStartupMilestones(left, right) {
+  return MILESTONE_ORDER.indexOf(left) - MILESTONE_ORDER.indexOf(right);
+}
+export {
+  buildStartupTimeoutMessage,
+  checkAppStarted,
+  checkLayoutReady,
+  classifyAppStartupProbe,
+  compareAppStartupMilestones
+};
+//# sourceMappingURL=data:application/json;base64,ewogICJ2ZXJzaW9uIjogMywKICAic291cmNlcyI6IFsiLi4vLi4vLi4vc3JjL2FwcC1zdGFydHVwLXByb2dyZXNzLnRzIl0sCiAgInNvdXJjZXNDb250ZW50IjogWyIvKipcbiAqIEBmaWxlXG4gKlxuICogUHVyZSBoZWxwZXJzIGZvciB0cmFja2luZyBob3cgZmFyIE9ic2lkaWFuIE1vYmlsZSBoYXMgZ290IHRocm91Z2ggaXRzIHN0YXJ0dXBcbiAqIGFmdGVyIGBsb2NhdGlvbi5yZWxvYWQoKWAsIGFuZCBmb3IgZGVzY3JpYmluZyB3aGVyZSBpdCBzdGFsbGVkIHdoZW4gYSBidWRnZXRcbiAqIHJ1bnMgb3V0LlxuICpcbiAqIFN0YXJ0dXAgaXMgd2F0Y2hlZCBhcyBhICoqbGFkZGVyIG9mIG1pbGVzdG9uZXMqKiwgbm90IGEgc2luZ2xlIGJvb2xlYW4sXG4gKiBiZWNhdXNlIHRoZSB0d28gaGFsdmVzIG9mIGl0IGNvc3Qgd2lsZGx5IGRpZmZlcmVudCBhbW91bnRzIG9mIHRpbWUgYW5kIG9ubHlcbiAqIG9uZSBvZiB0aGVtIGlzIE9ic2lkaWFuJ3MgZmF1bHQuIFJlYWNoaW5nIGBnbG9iYWxUaGlzLmFwcGAgaXMgdGhlIGFwcCBjb2xkXG4gKiBzdGFydCBcdTIwMTQgdGhlIFdlYlZpZXcgcmVsb2FkaW5nLCB0aGUgZ3Vlc3Qgc3RpbGwgY2h1cm5pbmcgXHUyMDE0IGFuZCBvbiBhIGNvbGQgb3JcbiAqIGNvbnRlbmRlZCBlbXVsYXRvciBpdCBjYW4gdGFrZSBtaW51dGVzLiBFdmVyeXRoaW5nIGFmdGVyIGl0IGlzIE9ic2lkaWFuXG4gKiBvcGVuaW5nIHRoZSB2YXVsdCBhbmQgbG9hZGluZyBwbHVnaW5zLCB3aGljaCAqKkwxOSoqIG1lYXN1cmVkIGF0IH4xcyAoXHUyMjY0OC40c1xuICogdW5kZXIgMTItY29yZSArIGRpc2sgKyBtZW1vcnkgc3RyZXNzKS4gQ2hhcmdpbmcgYm90aCB0byBvbmUgOTBzIHdhbGwgY2xvY2sgaXNcbiAqIHdoYXQgbWFkZSBhIGZpcnN0IHJ1biBhZnRlciBhIG1hY2hpbmUgcmVzdGFydCBmYWlsIGJ5IGRlc2lnbiwgc28gdGhlIHRyYW5zcG9ydFxuICogcnVucyB0aGVtIGFzIHR3byBidWRnZXRzIGFuZCB1c2VzIHRoZXNlIGhlbHBlcnMgdG8gdGVsbCB0aGVtIGFwYXJ0LlxuICpcbiAqIEtlcHQgc2VwYXJhdGUgZnJvbSB0aGUgaW50ZWdyYXRpb24tb25seSBgdHJhbnNwb3J0LWFwcGl1bWAgKGV4Y2x1ZGVkIGZyb20gdW5pdFxuICogdGVzdHMpIHNvIHRoZSBjbGFzc2lmaWNhdGlvbiBhbmQgbWVzc2FnZSBmb3JtYXR0aW5nIHN0YXkgdW5pdC10ZXN0YWJsZSBcdTIwMTQgdGhlXG4gKiBwb2xsaW5nIGl0c2VsZiBuZWVkcyBhIHJlYWwgZGV2aWNlLlxuICovXG5cbi8qKlxuICogSG93IGZhciBPYnNpZGlhbiBoYXMgZ290IHRocm91Z2ggaXRzIHN0YXJ0dXAsIGFzIHNlZW4gZnJvbSBvbmUgV2ViVmlldyBwcm9iZS5cbiAqXG4gKiBPcmRlcmVkIGZyb20gbGVhc3QgdG8gbW9zdCBhZHZhbmNlZDsge0BsaW5rIGNvbXBhcmVBcHBTdGFydHVwTWlsZXN0b25lc31cbiAqIHJlbGllcyBvbiB0aGF0IG9yZGVyLlxuICovXG5leHBvcnQgdHlwZSBBcHBTdGFydHVwTWlsZXN0b25lID1cbiAgfCAnbGF5b3V0LXJlYWR5J1xuICB8ICduby1hcHAnXG4gIHwgJ25vLXdlYnZpZXcnXG4gIHwgJ25vLXdvcmtzcGFjZSdcbiAgfCAnd29ya3NwYWNlLW5vdC1yZWFkeSc7XG5cbi8qKlxuICogV2hpY2ggb2YgdGhlIHR3byBzdGFydHVwIGJ1ZGdldHMgd2FzIGJlaW5nIHNwZW50IHdoZW4gaXQgcmFuIG91dC5cbiAqL1xuZXhwb3J0IHR5cGUgQXBwU3RhcnR1cFBoYXNlID0gJ2FwcC1zdGFydCcgfCAnbGF5b3V0LXJlYWR5JztcblxuLyoqXG4gKiBQYXJhbWV0ZXJzIGZvciB7QGxpbmsgYnVpbGRTdGFydHVwVGltZW91dE1lc3NhZ2V9LlxuICovXG5leHBvcnQgaW50ZXJmYWNlIEJ1aWxkU3RhcnR1cFRpbWVvdXRNZXNzYWdlUGFyYW1zIHtcbiAgLyoqXG4gIEhvdyBsb25nIHRoaXMgcGhhc2UncyBidWRnZXQgaGFkIGJlZW4gc3BlbnQgd2hlbiBpdCByYW4gb3V0LlxuICAgKi9cbiAgcmVhZG9ubHkgZWxhcHNlZEluTWlsbGlzZWNvbmRzOiBudW1iZXI7XG5cbiAgLyoqXG4gIFRoZSBmdXJ0aGVzdCBtaWxlc3RvbmUgcmVhY2hlZCBiZWZvcmUgdGhlIGJ1ZGdldCByYW4gb3V0LlxuICAgKi9cbiAgcmVhZG9ubHkgbWlsZXN0b25lOiBBcHBTdGFydHVwTWlsZXN0b25lO1xuXG4gIC8qKlxuICBUaGUgcGhhc2Ugd2hvc2UgYnVkZ2V0IHJhbiBvdXQuXG4gICAqL1xuICByZWFkb25seSBwaGFzZTogQXBwU3RhcnR1cFBoYXNlO1xuXG4gIC8qKlxuICBIb3cgbWFueSBwcm9iZXMgd2VyZSBtYWRlIGR1cmluZyB0aGUgcGhhc2UuXG4gICAqL1xuICByZWFkb25seSBwb2xsQ291bnQ6IG51bWJlcjtcblxuICAvKipcbiAgVGhlIHNsb3dlc3Qgc2luZ2xlIHByb2JlIHJvdW5kLXRyaXAgb2JzZXJ2ZWQgZHVyaW5nIHRoZSBwaGFzZS5cbiAgICovXG4gIHJlYWRvbmx5IHNsb3dlc3RSb3VuZFRyaXBJbk1pbGxpc2Vjb25kczogbnVtYmVyO1xuXG4gIC8qKlxuICBUaGUgYnVkZ2V0IHRoYXQgcmFuIG91dC5cbiAgICovXG4gIHJlYWRvbmx5IHRpbWVvdXRJbk1pbGxpc2Vjb25kczogbnVtYmVyO1xufVxuXG4vKipcbiAqIFRoZSByYXcgc2hhcGUgYSBXZWJWaWV3IHN0YXJ0dXAgcHJvYmUgcmVwb3J0cyBiYWNrLlxuICpcbiAqIE1pcnJvcnMgd2hhdCB0aGUgaW5qZWN0ZWQgcHJvYmUgZnVuY3Rpb24gY2FuIG9ic2VydmUgd2l0aG91dCBpbXBvcnRpbmdcbiAqIGFueXRoaW5nOiB3aGV0aGVyIHRoZSBnbG9iYWwgYGFwcGAgb2JqZWN0IGV4aXN0cyB5ZXQsIHdoZXRoZXIgaXRzIGB3b3Jrc3BhY2VgXG4gKiBkb2VzLCBhbmQgd2hldGhlciB0aGF0IHdvcmtzcGFjZSBoYXMgZmluaXNoZWQgbGF5aW5nIG91dC5cbiAqL1xuZXhwb3J0IGludGVyZmFjZSBTdGFydHVwUHJvYmVSZXN1bHQge1xuICAvKipcbiAgV2hldGhlciBgZ2xvYmFsVGhpcy5hcHBgIGlzIGRlZmluZWQuXG4gICAqL1xuICByZWFkb25seSBoYXNBcHA6IGJvb2xlYW47XG5cbiAgLyoqXG4gIFdoZXRoZXIgYGFwcC53b3Jrc3BhY2VgIGlzIGRlZmluZWQuXG4gICAqL1xuICByZWFkb25seSBoYXNXb3Jrc3BhY2U6IGJvb2xlYW47XG5cbiAgLyoqXG4gIFdoZXRoZXIgYGFwcC53b3Jrc3BhY2UubGF5b3V0UmVhZHlgIGlzIHRydXRoeS5cbiAgICovXG4gIHJlYWRvbmx5IGlzTGF5b3V0UmVhZHk6IGJvb2xlYW47XG59XG5cbi8qKlxuICogVGhlIG1pbGVzdG9uZSBsYWRkZXIsIGxlYXN0IHRvIG1vc3QgYWR2YW5jZWQuIFRoZSBpbmRleCBpbiB0aGlzIGFycmF5ICppcypcbiAqIHRoZSBvcmRlcmluZyB1c2VkIGJ5IHtAbGluayBjb21wYXJlQXBwU3RhcnR1cE1pbGVzdG9uZXN9LlxuICovXG5jb25zdCBNSUxFU1RPTkVfT1JERVI6IHJlYWRvbmx5IEFwcFN0YXJ0dXBNaWxlc3RvbmVbXSA9IFtcbiAgJ25vLXdlYnZpZXcnLFxuICAnbm8tYXBwJyxcbiAgJ25vLXdvcmtzcGFjZScsXG4gICd3b3Jrc3BhY2Utbm90LXJlYWR5JyxcbiAgJ2xheW91dC1yZWFkeSdcbl07XG5cbi8qKlxuICogVGhlIG1pbGVzdG9uZSBhdCB3aGljaCB0aGUgYXBwLXN0YXJ0IHBoYXNlIGlzIHNhdGlzZmllZDogYGdsb2JhbFRoaXMuYXBwYFxuICogZXhpc3RzLCBzbyB0aGUgV2ViVmlldyBoYXMgcmVsb2FkZWQgYW5kIE9ic2lkaWFuJ3Mgb3duIGJvb3QgaGFzIGJlZ3VuLiBXaGF0XG4gKiByZW1haW5zIGZyb20gaGVyZSBpcyBPYnNpZGlhbiB3b3JrLCB3aGljaCB0aGUgdGlnaHQgbGF5b3V0LXJlYWR5IGJ1ZGdldFxuICogY292ZXJzLlxuICovXG5jb25zdCBBUFBfU1RBUlRFRF9NSUxFU1RPTkU6IEFwcFN0YXJ0dXBNaWxlc3RvbmUgPSAnbm8td29ya3NwYWNlJztcblxuLyoqXG4gKiBIdW1hbi1yZWFkYWJsZSBkZXNjcmlwdGlvbnMgb2YgZWFjaCBtaWxlc3RvbmUsIHVzZWQgaW4gdGhlIHRpbWVvdXQgbWVzc2FnZSBzb1xuICogdGhlIGZhaWx1cmUgbmFtZXMgd2hhdCBuZXZlciBoYXBwZW5lZCBpbnN0ZWFkIG9mIG9ubHkgd2hhdCB3YXMgaG9wZWQgZm9yLlxuICovXG5jb25zdCBNSUxFU1RPTkVfREVTQ1JJUFRJT05TOiBSZWNvcmQ8QXBwU3RhcnR1cE1pbGVzdG9uZSwgc3RyaW5nPiA9IHtcbiAgJ2xheW91dC1yZWFkeSc6ICd0aGUgd29ya3NwYWNlIGZpbmlzaGVkIGxheWluZyBvdXQnLFxuICAnbm8tYXBwJzogJ3RoZSBXZWJWaWV3IGFuc3dlcmVkLCBidXQgYGdsb2JhbFRoaXMuYXBwYCBuZXZlciBhcHBlYXJlZCcsXG4gICduby13ZWJ2aWV3JzogJ3RoZSBXZWJWaWV3IG5ldmVyIGFuc3dlcmVkIGEgc2luZ2xlIHByb2JlJyxcbiAgJ25vLXdvcmtzcGFjZSc6ICdgZ2xvYmFsVGhpcy5hcHBgIGFwcGVhcmVkLCBidXQgYGFwcC53b3Jrc3BhY2VgIG5ldmVyIGRpZCcsXG4gICd3b3Jrc3BhY2Utbm90LXJlYWR5JzogJ2BhcHAud29ya3NwYWNlYCBleGlzdHMsIGJ1dCBgbGF5b3V0UmVhZHlgIG5ldmVyIGJlY2FtZSB0cnVlJ1xufTtcblxuLyoqXG4gKiBXaGF0IGVhY2ggcGhhc2Ugd2FzIHdhaXRpbmcgZm9yLCB1c2VkIGluIHRoZSB0aW1lb3V0IG1lc3NhZ2UuXG4gKi9cbmNvbnN0IFBIQVNFX0RFU0NSSVBUSU9OUzogUmVjb3JkPEFwcFN0YXJ0dXBQaGFzZSwgc3RyaW5nPiA9IHtcbiAgJ2FwcC1zdGFydCc6ICdPYnNpZGlhbiBNb2JpbGUgZGlkIG5vdCBmaW5pc2ggc3RhcnRpbmcnLFxuICAnbGF5b3V0LXJlYWR5JzogJ09ic2lkaWFuIGxheW91dCBkaWQgbm90IGJlY29tZSByZWFkeSdcbn07XG5cbi8qKlxuICogQnVpbGRzIHRoZSBkaWFnbm9zdGljIG1lc3NhZ2UgZm9yIGEgc3RhcnR1cCBidWRnZXQgdGhhdCByYW4gb3V0LlxuICpcbiAqIEl0IG5hbWVzIHRoZSBtaWxlc3RvbmUgYWN0dWFsbHkgcmVhY2hlZCwgdGhlIHBvbGwgY291bnQgYW5kIHRoZSBzbG93ZXN0IHByb2JlXG4gKiByb3VuZC10cmlwLCBiZWNhdXNlIHRob3NlIHRocmVlIHRvZ2V0aGVyIHNlcGFyYXRlIHRoZSBmYWlsdXJlIG1vZGVzICoqTDE5KipcbiAqIGNvdWxkIG5vdCB0ZWxsIGFwYXJ0IGZyb20gdGhlIG9sZCBtZXNzYWdlOiBhIGdlbnVpbmUgT2JzaWRpYW4gc2xvd2Rvd24gc2hvd3NcbiAqIG1hbnkgZmFzdCBwb2xscyBzdGFsbGVkIGF0IG9uZSBtaWxlc3RvbmUsIHdoZXJlYXMgYSBjb250ZW5kZWQgZ3Vlc3Qgc2hvd3MgYVxuICogaGFuZGZ1bCBvZiBwb2xscyBlYWNoIHRha2luZyB0ZW5zIG9mIHNlY29uZHMuXG4gKlxuICogQHBhcmFtIHBhcmFtcyAtIFRoZSBwaGFzZSwgdGhlIG1pbGVzdG9uZSByZWFjaGVkLCBhbmQgdGhlIHRpbWluZyBldmlkZW5jZS5cbiAqIEByZXR1cm5zIEEgaHVtYW4tcmVhZGFibGUgZXJyb3IgbWVzc2FnZS5cbiAqL1xuZXhwb3J0IGZ1bmN0aW9uIGJ1aWxkU3RhcnR1cFRpbWVvdXRNZXNzYWdlKHBhcmFtczogQnVpbGRTdGFydHVwVGltZW91dE1lc3NhZ2VQYXJhbXMpOiBzdHJpbmcge1xuICBjb25zdCB7XG4gICAgZWxhcHNlZEluTWlsbGlzZWNvbmRzLFxuICAgIG1pbGVzdG9uZSxcbiAgICBwaGFzZSxcbiAgICBwb2xsQ291bnQsXG4gICAgc2xvd2VzdFJvdW5kVHJpcEluTWlsbGlzZWNvbmRzLFxuICAgIHRpbWVvdXRJbk1pbGxpc2Vjb25kc1xuICB9ID0gcGFyYW1zO1xuXG4gIHJldHVybiBgJHtQSEFTRV9ERVNDUklQVElPTlNbcGhhc2VdfSB3aXRoaW4gJHtTdHJpbmcodGltZW91dEluTWlsbGlzZWNvbmRzKX1tcyBgXG4gICAgKyBgKGVsYXBzZWQgJHtTdHJpbmcoZWxhcHNlZEluTWlsbGlzZWNvbmRzKX1tcykuIEZ1cnRoZXN0IHByb2dyZXNzOiAke01JTEVTVE9ORV9ERVNDUklQVElPTlNbbWlsZXN0b25lXX0uIGBcbiAgICArIGBQcm9iZWQgJHtTdHJpbmcocG9sbENvdW50KX0gdGltZShzKSwgc2xvd2VzdCByb3VuZC10cmlwICR7U3RyaW5nKHNsb3dlc3RSb3VuZFRyaXBJbk1pbGxpc2Vjb25kcyl9bXMuIGBcbiAgICArICdBIGhhbmRmdWwgb2YgcHJvYmVzIGVhY2ggdGFraW5nIHRlbnMgb2Ygc2Vjb25kcyBtZWFucyBhIGNvbnRlbmRlZCBndWVzdCwgbm90IGEgc2xvdyBPYnNpZGlhbiBcdTIwMTQgJ1xuICAgICsgJ2xldCB0aGUgZW11bGF0b3IgZ28gaWRsZSBiZWZvcmUgdGhlIHJ1biwgb3IgcmFpc2UgYGRldmljZUlkbGVUaW1lb3V0SW5NaWxsaXNlY29uZHNgLic7XG59XG5cbi8qKlxuICogUmVwb3J0cyB3aGV0aGVyIHRoZSBhcHAtc3RhcnQgcGhhc2UgaXMgc2F0aXNmaWVkIGF0IHRoaXMgbWlsZXN0b25lLlxuICpcbiAqIEBwYXJhbSBtaWxlc3RvbmUgLSBUaGUgbWlsZXN0b25lIHRoZSBsYXRlc3QgcHJvYmUgcmVwb3J0ZWQuXG4gKiBAcmV0dXJucyBgdHJ1ZWAgb25jZSBgZ2xvYmFsVGhpcy5hcHBgIGV4aXN0cywgc28gdGhlIGxheW91dC1yZWFkeSBidWRnZXQgbWF5IHN0YXJ0LlxuICovXG5leHBvcnQgZnVuY3Rpb24gY2hlY2tBcHBTdGFydGVkKG1pbGVzdG9uZTogQXBwU3RhcnR1cE1pbGVzdG9uZSk6IGJvb2xlYW4ge1xuICByZXR1cm4gY29tcGFyZUFwcFN0YXJ0dXBNaWxlc3RvbmVzKG1pbGVzdG9uZSwgQVBQX1NUQVJURURfTUlMRVNUT05FKSA+PSAwO1xufVxuXG4vKipcbiAqIFJlcG9ydHMgd2hldGhlciB0aGUgbGF5b3V0LXJlYWR5IHBoYXNlIGlzIHNhdGlzZmllZCBhdCB0aGlzIG1pbGVzdG9uZS5cbiAqXG4gKiBAcGFyYW0gbWlsZXN0b25lIC0gVGhlIG1pbGVzdG9uZSB0aGUgbGF0ZXN0IHByb2JlIHJlcG9ydGVkLlxuICogQHJldHVybnMgYHRydWVgIG9uY2UgdGhlIHdvcmtzcGFjZSBoYXMgZmluaXNoZWQgbGF5aW5nIG91dC5cbiAqL1xuZXhwb3J0IGZ1bmN0aW9uIGNoZWNrTGF5b3V0UmVhZHkobWlsZXN0b25lOiBBcHBTdGFydHVwTWlsZXN0b25lKTogYm9vbGVhbiB7XG4gIHJldHVybiBtaWxlc3RvbmUgPT09ICdsYXlvdXQtcmVhZHknO1xufVxuXG4vKipcbiAqIFR1cm5zIGEgV2ViVmlldyBwcm9iZSBpbnRvIGEgbWlsZXN0b25lLlxuICpcbiAqIEEgcHJvYmUgdGhhdCBjb3VsZCBub3QgcnVuIGF0IGFsbCBcdTIwMTQgYHVuZGVmaW5lZGAsIGJlY2F1c2UgYGJyb3dzZXIuZXhlY3V0ZSgpYFxuICogdGhyZXcgd2hpbGUgdGhlIHBhZ2Ugd2FzIG1pZC1yZWxvYWQgXHUyMDE0IGlzIHRoZSBsZWFzdCBhZHZhbmNlZCBtaWxlc3RvbmUgcmF0aGVyXG4gKiB0aGFuIGFuIGVycm9yOiBkdXJpbmcgYSByZWxvYWQgaXQgaXMgdGhlIGV4cGVjdGVkIHJlYWRpbmcuXG4gKlxuICogQHBhcmFtIHByb2JlUmVzdWx0IC0gV2hhdCB0aGUgcHJvYmUgcmVwb3J0ZWQsIG9yIGB1bmRlZmluZWRgIHdoZW4gaXQgdGhyZXcuXG4gKiBAcmV0dXJucyBUaGUgbWlsZXN0b25lIHRoYXQgcmVhZGluZyByZXByZXNlbnRzLlxuICovXG5leHBvcnQgZnVuY3Rpb24gY2xhc3NpZnlBcHBTdGFydHVwUHJvYmUocHJvYmVSZXN1bHQ6IFN0YXJ0dXBQcm9iZVJlc3VsdCB8IHVuZGVmaW5lZCk6IEFwcFN0YXJ0dXBNaWxlc3RvbmUge1xuICBpZiAoIXByb2JlUmVzdWx0KSB7XG4gICAgcmV0dXJuICduby13ZWJ2aWV3JztcbiAgfVxuICBpZiAoIXByb2JlUmVzdWx0Lmhhc0FwcCkge1xuICAgIHJldHVybiAnbm8tYXBwJztcbiAgfVxuICBpZiAoIXByb2JlUmVzdWx0Lmhhc1dvcmtzcGFjZSkge1xuICAgIHJldHVybiAnbm8td29ya3NwYWNlJztcbiAgfVxuICByZXR1cm4gcHJvYmVSZXN1bHQuaXNMYXlvdXRSZWFkeSA/ICdsYXlvdXQtcmVhZHknIDogJ3dvcmtzcGFjZS1ub3QtcmVhZHknO1xufVxuXG4vKipcbiAqIE9yZGVycyB0d28gbWlsZXN0b25lcyBvbiB0aGUgc3RhcnR1cCBsYWRkZXIuXG4gKlxuICogQHBhcmFtIGxlZnQgLSBUaGUgZmlyc3QgbWlsZXN0b25lLlxuICogQHBhcmFtIHJpZ2h0IC0gVGhlIHNlY29uZCBtaWxlc3RvbmUuXG4gKiBAcmV0dXJucyBBIG5lZ2F0aXZlIG51bWJlciB3aGVuIGBsZWZ0YCBpcyBsZXNzIGFkdmFuY2VkLCBgMGAgd2hlbiBlcXVhbCwgYSBwb3NpdGl2ZSBudW1iZXIgd2hlbiBtb3JlIGFkdmFuY2VkLlxuICovXG5leHBvcnQgZnVuY3Rpb24gY29tcGFyZUFwcFN0YXJ0dXBNaWxlc3RvbmVzKGxlZnQ6IEFwcFN0YXJ0dXBNaWxlc3RvbmUsIHJpZ2h0OiBBcHBTdGFydHVwTWlsZXN0b25lKTogbnVtYmVyIHtcbiAgcmV0dXJuIE1JTEVTVE9ORV9PUkRFUi5pbmRleE9mKGxlZnQpIC0gTUlMRVNUT05FX09SREVSLmluZGV4T2YocmlnaHQpO1xufVxuIl0sCiAgIm1hcHBpbmdzIjogIkFBdUdBLE1BQU0sa0JBQWtEO0FBQUEsRUFDdEQ7QUFBQSxFQUNBO0FBQUEsRUFDQTtBQUFBLEVBQ0E7QUFBQSxFQUNBO0FBQ0Y7QUFRQSxNQUFNLHdCQUE2QztBQU1uRCxNQUFNLHlCQUE4RDtBQUFBLEVBQ2xFLGdCQUFnQjtBQUFBLEVBQ2hCLFVBQVU7QUFBQSxFQUNWLGNBQWM7QUFBQSxFQUNkLGdCQUFnQjtBQUFBLEVBQ2hCLHVCQUF1QjtBQUN6QjtBQUtBLE1BQU0scUJBQXNEO0FBQUEsRUFDMUQsYUFBYTtBQUFBLEVBQ2IsZ0JBQWdCO0FBQ2xCO0FBY08sU0FBUywyQkFBMkIsUUFBa0Q7QUFDM0YsUUFBTTtBQUFBLElBQ0o7QUFBQSxJQUNBO0FBQUEsSUFDQTtBQUFBLElBQ0E7QUFBQSxJQUNBO0FBQUEsSUFDQTtBQUFBLEVBQ0YsSUFBSTtBQUVKLFNBQU8sR0FBRyxtQkFBbUIsS0FBSyxDQUFDLFdBQVcsT0FBTyxxQkFBcUIsQ0FBQyxlQUMzRCxPQUFPLHFCQUFxQixDQUFDLDJCQUEyQix1QkFBdUIsU0FBUyxDQUFDLFlBQzNGLE9BQU8sU0FBUyxDQUFDLGdDQUFnQyxPQUFPLDhCQUE4QixDQUFDO0FBR3ZHO0FBUU8sU0FBUyxnQkFBZ0IsV0FBeUM7QUFDdkUsU0FBTyw0QkFBNEIsV0FBVyxxQkFBcUIsS0FBSztBQUMxRTtBQVFPLFNBQVMsaUJBQWlCLFdBQXlDO0FBQ3hFLFNBQU8sY0FBYztBQUN2QjtBQVlPLFNBQVMsd0JBQXdCLGFBQWtFO0FBQ3hHLE1BQUksQ0FBQyxhQUFhO0FBQ2hCLFdBQU87QUFBQSxFQUNUO0FBQ0EsTUFBSSxDQUFDLFlBQVksUUFBUTtBQUN2QixXQUFPO0FBQUEsRUFDVDtBQUNBLE1BQUksQ0FBQyxZQUFZLGNBQWM7QUFDN0IsV0FBTztBQUFBLEVBQ1Q7QUFDQSxTQUFPLFlBQVksZ0JBQWdCLGlCQUFpQjtBQUN0RDtBQVNPLFNBQVMsNEJBQTRCLE1BQTJCLE9BQW9DO0FBQ3pHLFNBQU8sZ0JBQWdCLFFBQVEsSUFBSSxJQUFJLGdCQUFnQixRQUFRLEtBQUs7QUFDdEU7IiwKICAibmFtZXMiOiBbXQp9Cg==

package/dist/lib/esm/appium-server-marker.d.mts

@@ -0,0 +1,103 @@
+/**
+ * @file
+ *
+ * Records which Appium server on a port this harness started, so a later run
+ * that finds a server already listening can tell **provenance**: one of our own
+ * servers left over from an earlier run, or a foreign one the user manages.
+ *
+ * The preflight adopts any server that answers `/status`, and adoption is the
+ * right default — starting a second server on an occupied port cannot work. But
+ * adopting silently means a wedged leftover (see `wedged-appium-server.ts`) is
+ * indistinguishable from a healthy server, and the harness has no basis on which
+ * to decide whether restarting it is its call to make. The marker supplies that
+ * basis: a server we started may be restarted, a foreign one is only ever
+ * reported.
+ *
+ * The marker is a small JSON sentinel next to the setup lock (`setup-lock.ts`),
+ * keyed by port, and is deliberately tolerant — a missing, unreadable, or
+ * mismatched marker simply reads as "not ours".
+ */
+/**
+ * Identifies the Appium server this harness started on a port.
+ */
+export interface AppiumServerMarker {
+    /**
+    PID of the spawned server process (the shell wrapper that owns the server's process tree).
+     */
+    readonly pid: number;
+    /**
+    The port the server was started on.
+     */
+    readonly port: number;
+    /**
+    When the server was started (`Date.now()` epoch milliseconds).
+     */
+    readonly startedAtInMilliseconds: number;
+    /**
+     * When a run tried to stop this server and could not verify it exited
+     * (`Date.now()` epoch milliseconds), or `undefined` when no stop has failed.
+     *
+     * Its presence means the server is a **known-doomed leftover**: it was ours,
+     * we asked it to die, and it did not. See {@link recordAppiumServerStopAttempt}.
+     */
+    readonly stopAttemptedAtInMilliseconds?: number | undefined;
+}
+/**
+ * Parameters for {@link writeAppiumServerMarker}.
+ */
+export interface WriteAppiumServerMarkerParams {
+    /**
+    PID of the spawned server process.
+     */
+    readonly pid: number;
+    /**
+    The port the server was started on.
+     */
+    readonly port: number;
+}
+/**
+ * Checks whether the marked server is still running, which is what makes an
+ * adopted server ours to restart.
+ *
+ * A dead PID means the marker outlived its server, so whatever answers on that
+ * port now is somebody else's — the marker proves nothing about it.
+ *
+ * @param marker - The marker read for the port, or `undefined` when there is none.
+ * @returns `true` when an earlier run of this harness started the server now listening.
+ */
+export declare function checkIsHarnessOwnedAppiumServer(marker: AppiumServerMarker | undefined): boolean;
+/**
+ * Removes the marker for a port. Called once the marked server has been stopped,
+ * so a later run does not mistake a recycled PID for our server.
+ *
+ * @param port - The Appium server port.
+ */
+export declare function clearAppiumServerMarker(port: number): void;
+/**
+ * Reads the marker for a port.
+ *
+ * @param port - The Appium server port.
+ * @returns The marker, or `undefined` when there is none, it is unreadable, or it does not describe this port.
+ */
+export declare function readAppiumServerMarker(port: number): AppiumServerMarker | undefined;
+/**
+ * Records that a run tried to stop the marked server and could not verify it
+ * exited — **instead of** clearing the marker.
+ *
+ * Clearing it would be the worst of both worlds: the leftover keeps serving, and
+ * the next run reads it as a foreign, user-managed server it must never touch
+ * (`checkIsHarnessOwnedAppiumServer` needs the marker to convict it). Keeping
+ * the marker, stamped, says exactly what is true — this is ours, and it outlived
+ * our teardown — which is what lets the next run refuse to adopt it and replace
+ * it instead.
+ *
+ * @param port - The Appium server port.
+ */
+export declare function recordAppiumServerStopAttempt(port: number): void;
+/**
+ * Records the server this run just started, stamping it with the current time so
+ * a later run can report how long it has been up.
+ *
+ * @param params - The started server's PID and port.
+ */
+export declare function writeAppiumServerMarker(params: WriteAppiumServerMarkerParams): void;