memorydetective 1.7.0 → 1.8.1

package/dist/runtime/axe.js

@@ -0,0 +1,249 @@
+/**
+ * Internal infrastructure for driving the iOS Simulator UI from inside leak/perf
+ * workflows (replayScenario, captureScenarioState). NOT a generic UI automation
+ * surface, the public tool contract stays scoped to leak/perf debug.
+ *
+ * Wraps Cameron Cooke's `axe` CLI (https://github.com/cameroncooke/AXe).
+ * `axe` is a soft dependency: we detect it on first use and emit a structured
+ * install hint when missing, instead of hard-failing or bundling it.
+ */
+import { runCommand } from "./exec.js";
+const AXE_INSTALL_HINT = "axe CLI not found in PATH. Install with `brew install cameroncooke/axe/axe` (https://github.com/cameroncooke/AXe). axe is a soft dependency, only required for replayScenario and captureScenarioState.";
+/**
+ * Check whether `axe` is available on the system. Cached at module load via
+ * `which` lookup so callers can skip the call when they already know.
+ */
+export async function checkAxeAvailable() {
+    const result = await runCommand("which", ["axe"], { timeoutMs: 5_000 });
+    if (result.code !== 0) {
+        return { available: false, installHint: AXE_INSTALL_HINT };
+    }
+    const binaryPath = result.stdout.trim();
+    if (!binaryPath) {
+        return { available: false, installHint: AXE_INSTALL_HINT };
+    }
+    return { available: true, binaryPath };
+}
+/**
+ * Run `axe describe-ui --udid <udid>` and parse the tree into normalized
+ * `UIElement` nodes. Returns the root element.
+ */
+export async function describeUI(udid) {
+    const result = await runCommand("axe", ["describe-ui", "--udid", udid], {
+        timeoutMs: 30_000,
+    });
+    if (result.code !== 0) {
+        throw new Error(`axe describe-ui --udid ${udid} failed (code ${result.code}): ${result.stderr || result.stdout}`);
+    }
+    return parseAxeDescribeUI(result.stdout);
+}
+/** Pure: parse `axe describe-ui` JSON output into normalized UIElement tree. */
+export function parseAxeDescribeUI(stdout) {
+    const sliced = sliceJsonValue(stdout);
+    if (!sliced) {
+        throw new Error("axe describe-ui output did not contain a JSON object/array. Stdout begins: " +
+            stdout.slice(0, 200));
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(sliced);
+    }
+    catch (err) {
+        throw new Error(`axe describe-ui output failed JSON.parse: ${err.message}`);
+    }
+    return normalizeAxeNode(parsed);
+}
+function sliceJsonValue(stdout) {
+    const trimmed = stdout.trim();
+    if (!trimmed)
+        return null;
+    // axe emits a JSON object as the root.
+    const objStart = trimmed.indexOf("{");
+    const objEnd = trimmed.lastIndexOf("}");
+    if (objStart !== -1 && objEnd > objStart) {
+        return trimmed.slice(objStart, objEnd + 1);
+    }
+    const arrStart = trimmed.indexOf("[");
+    const arrEnd = trimmed.lastIndexOf("]");
+    if (arrStart !== -1 && arrEnd > arrStart) {
+        return trimmed.slice(arrStart, arrEnd + 1);
+    }
+    return null;
+}
+function normalizeAxeNode(raw) {
+    if (raw == null || typeof raw !== "object") {
+        return { raw: {} };
+    }
+    const obj = raw;
+    const out = { raw: obj };
+    const labelKey = pickFirstString(obj, [
+        "AXLabel",
+        "label",
+        "name",
+        "title",
+    ]);
+    if (labelKey != null)
+        out.label = labelKey;
+    const idKey = pickFirstString(obj, ["AXIdentifier", "identifier", "id"]);
+    if (idKey != null)
+        out.identifier = idKey;
+    const roleKey = pickFirstString(obj, ["AXRole", "role", "type"]);
+    if (roleKey != null)
+        out.role = roleKey;
+    const frame = parseAxFrame(obj);
+    if (frame)
+        out.frame = frame;
+    const childrenRaw = obj.children ??
+        obj.AXChildren ??
+        obj.subviews;
+    if (Array.isArray(childrenRaw)) {
+        out.children = childrenRaw.map((c) => normalizeAxeNode(c));
+    }
+    return out;
+}
+function pickFirstString(obj, keys) {
+    for (const key of keys) {
+        const value = obj[key];
+        if (typeof value === "string" && value.length > 0) {
+            return value;
+        }
+    }
+    return null;
+}
+/**
+ * Pure: parse an `AXFrame`-style frame from a node. Accepts both AppKit-style
+ * dictionaries `{AXX: 0, AXY: 0, AXWidth: 100, AXHeight: 100}` and CGRect
+ * strings `"{{0,0},{100,100}}"`.
+ */
+export function parseAxFrame(obj) {
+    const direct = obj.frame ?? obj.AXFrame;
+    if (typeof direct === "string") {
+        return parseFrameString(direct);
+    }
+    if (direct && typeof direct === "object") {
+        const f = direct;
+        const x = pickFirstNumber(f, ["x", "AXX", "X"]);
+        const y = pickFirstNumber(f, ["y", "AXY", "Y"]);
+        const w = pickFirstNumber(f, ["width", "AXWidth", "Width"]);
+        const h = pickFirstNumber(f, ["height", "AXHeight", "Height"]);
+        if (x != null && y != null && w != null && h != null) {
+            return { x, y, width: w, height: h };
+        }
+    }
+    // Direct top-level keys, AppKit/AX style flat.
+    const x = pickFirstNumber(obj, ["AXX", "frameX"]);
+    const y = pickFirstNumber(obj, ["AXY", "frameY"]);
+    const w = pickFirstNumber(obj, ["AXWidth", "frameWidth"]);
+    const h = pickFirstNumber(obj, ["AXHeight", "frameHeight"]);
+    if (x != null && y != null && w != null && h != null) {
+        return { x, y, width: w, height: h };
+    }
+    return undefined;
+}
+function pickFirstNumber(obj, keys) {
+    for (const key of keys) {
+        const value = obj[key];
+        if (typeof value === "number" && Number.isFinite(value)) {
+            return value;
+        }
+    }
+    return null;
+}
+function parseFrameString(s) {
+    const match = s.match(/\{\{\s*(-?\d+(?:\.\d+)?)\s*,\s*(-?\d+(?:\.\d+)?)\s*\}\s*,\s*\{\s*(-?\d+(?:\.\d+)?)\s*,\s*(-?\d+(?:\.\d+)?)\s*\}\s*\}/);
+    if (!match)
+        return undefined;
+    return {
+        x: parseFloat(match[1]),
+        y: parseFloat(match[2]),
+        width: parseFloat(match[3]),
+        height: parseFloat(match[4]),
+    };
+}
+/**
+ * Pure: find the first descendant whose label or identifier matches `query`
+ * (exact match preferred, falls back to substring). Walks the tree
+ * depth-first.
+ */
+export function findElementByLabel(root, query) {
+    const exact = findFirst(root, (el) => el.label === query || el.identifier === query);
+    if (exact)
+        return exact;
+    return findFirst(root, (el) => (el.label != null && el.label.includes(query)) ||
+        (el.identifier != null && el.identifier.includes(query)));
+}
+function findFirst(root, predicate) {
+    if (predicate(root))
+        return root;
+    if (!root.children)
+        return null;
+    for (const child of root.children) {
+        const hit = findFirst(child, predicate);
+        if (hit)
+            return hit;
+    }
+    return null;
+}
+/** Pure: compute the center point of an `AxFrame` for tap targeting. */
+export function centerOf(frame) {
+    return {
+        x: Math.round(frame.x + frame.width / 2),
+        y: Math.round(frame.y + frame.height / 2),
+    };
+}
+/**
+ * Tap on the simulator. Resolves label/elementId targets via `describe-ui`
+ * before issuing the tap.
+ */
+export async function tap(udid, target) {
+    let coords;
+    if (target.kind === "coords") {
+        coords = { x: target.x, y: target.y };
+    }
+    else {
+        const tree = await describeUI(udid);
+        const query = target.value;
+        const el = findElementByLabel(tree, query);
+        if (!el || !el.frame) {
+            throw new Error(`Could not locate element matching "${query}" in the current UI tree, or the element has no frame metadata.`);
+        }
+        coords = centerOf(el.frame);
+    }
+    const result = await runCommand("axe", [
+        "tap",
+        "--udid",
+        udid,
+        "-x",
+        String(coords.x),
+        "-y",
+        String(coords.y),
+    ], { timeoutMs: 10_000 });
+    if (result.code !== 0) {
+        throw new Error(`axe tap (${coords.x},${coords.y}) failed (code ${result.code}): ${result.stderr || result.stdout}`);
+    }
+}
+/** Swipe between two coordinates with optional duration in milliseconds. */
+export async function swipe(udid, from, to, durationMs = 250) {
+    const result = await runCommand("axe", [
+        "swipe",
+        "--udid",
+        udid,
+        "--from",
+        `${from.x},${from.y}`,
+        "--to",
+        `${to.x},${to.y}`,
+        "--duration",
+        String(durationMs),
+    ], { timeoutMs: 15_000 });
+    if (result.code !== 0) {
+        throw new Error(`axe swipe failed (code ${result.code}): ${result.stderr || result.stdout}`);
+    }
+}
+/** Type a string into the currently focused field. */
+export async function typeText(udid, text) {
+    const result = await runCommand("axe", ["type", "--udid", udid, "--text", text], { timeoutMs: 15_000 });
+    if (result.code !== 0) {
+        throw new Error(`axe type failed (code ${result.code}): ${result.stderr || result.stdout}`);
+    }
+}
+//# sourceMappingURL=axe.js.map

package/dist/runtime/axe.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"axe.js","sourceRoot":"","sources":["../../src/runtime/axe.ts"],"names":[],"mappings":"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"}

package/dist/runtime/buildSettings.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Pure parser for `xcodebuild -showBuildSettings -json` output.
+ *
+ * `xcodebuild` emits a JSON array of `{action, target, buildSettings}` objects
+ * on stdout, but may print non-JSON warnings on stderr/stdout before or after
+ * the array. We slice from the first `[` to the last `]` to extract the JSON
+ * payload defensively.
+ *
+ * When multiple targets exist (e.g. an aggregate target alongside the app
+ * target), we pick the one whose build settings declare `WRAPPER_EXTENSION === "app"`,
+ * which is the actual application bundle.
+ */
+export interface BuildSettings {
+    /** Absolute path to the build products directory (where the .app lands). */
+    builtProductsDir: string;
+    /** Bundle wrapper name, e.g. `MyApp.app`. */
+    wrapperName: string;
+    /** Executable name inside the bundle, e.g. `MyApp`. Used for `pgrep -ax`. */
+    executableName: string;
+    /** App bundle identifier, e.g. `com.example.MyApp`. */
+    productBundleIdentifier: string;
+}
+/**
+ * Parse `xcodebuild -showBuildSettings -json` stdout. Throws when the output
+ * cannot be parsed or when the matched target is missing required keys.
+ */
+export declare function parseBuildSettingsJson(stdout: string): BuildSettings;

package/dist/runtime/buildSettings.js

@@ -0,0 +1,88 @@
+/**
+ * Pure parser for `xcodebuild -showBuildSettings -json` output.
+ *
+ * `xcodebuild` emits a JSON array of `{action, target, buildSettings}` objects
+ * on stdout, but may print non-JSON warnings on stderr/stdout before or after
+ * the array. We slice from the first `[` to the last `]` to extract the JSON
+ * payload defensively.
+ *
+ * When multiple targets exist (e.g. an aggregate target alongside the app
+ * target), we pick the one whose build settings declare `WRAPPER_EXTENSION === "app"`,
+ * which is the actual application bundle.
+ */
+const REQUIRED_KEYS = [
+    "builtProductsDir",
+    "wrapperName",
+    "executableName",
+    "productBundleIdentifier",
+];
+const KEY_MAP = {
+    builtProductsDir: "BUILT_PRODUCTS_DIR",
+    wrapperName: "WRAPPER_NAME",
+    executableName: "EXECUTABLE_NAME",
+    productBundleIdentifier: "PRODUCT_BUNDLE_IDENTIFIER",
+};
+/**
+ * Parse `xcodebuild -showBuildSettings -json` stdout. Throws when the output
+ * cannot be parsed or when the matched target is missing required keys.
+ */
+export function parseBuildSettingsJson(stdout) {
+    const sliced = sliceJsonArray(stdout);
+    if (!sliced) {
+        throw new Error("xcodebuild -showBuildSettings -json output did not contain a JSON array. Stdout begins: " +
+            stdout.slice(0, 200));
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(sliced);
+    }
+    catch (err) {
+        throw new Error(`xcodebuild -showBuildSettings -json output failed JSON.parse: ${err.message}`);
+    }
+    if (!Array.isArray(parsed) || parsed.length === 0) {
+        throw new Error("xcodebuild -showBuildSettings -json returned an empty array — no targets found for the given scheme/destination.");
+    }
+    const entries = parsed;
+    const appEntry = pickAppTarget(entries);
+    if (!appEntry || !appEntry.buildSettings) {
+        throw new Error("Could not find a target with WRAPPER_EXTENSION=app in -showBuildSettings output. Verify the scheme builds an iOS application bundle.");
+    }
+    const settings = appEntry.buildSettings;
+    const result = {};
+    for (const key of REQUIRED_KEYS) {
+        const xcodeKey = KEY_MAP[key];
+        const value = settings[xcodeKey];
+        if (!value || value.length === 0) {
+            throw new Error(`xcodebuild -showBuildSettings missing required key '${xcodeKey}' for target '${appEntry.target ?? "<unknown>"}'. Cannot proceed without this value.`);
+        }
+        result[key] = value;
+    }
+    return result;
+}
+/**
+ * Locate the JSON array within stdout. Returns the substring `[...]` or null
+ * when no balanced array is found.
+ */
+function sliceJsonArray(stdout) {
+    const start = stdout.indexOf("[");
+    if (start === -1)
+        return null;
+    const end = stdout.lastIndexOf("]");
+    if (end === -1 || end <= start)
+        return null;
+    return stdout.slice(start, end + 1);
+}
+/**
+ * Pick the entry whose build settings indicate an application bundle. When
+ * multiple match, the first wins — this is rare in practice and the caller
+ * can always pass a more specific scheme to disambiguate.
+ */
+function pickAppTarget(entries) {
+    for (const entry of entries) {
+        if (entry.buildSettings?.WRAPPER_EXTENSION === "app") {
+            return entry;
+        }
+    }
+    return null;
+}
+//# sourceMappingURL=buildSettings.js.map

package/dist/runtime/buildSettings.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"buildSettings.js","sourceRoot":"","sources":["../../src/runtime/buildSettings.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAmBH,MAAM,aAAa,GAA+B;IAChD,kBAAkB;IAClB,aAAa;IACb,gBAAgB;IAChB,yBAAyB;CAC1B,CAAC;AAEF,MAAM,OAAO,GAAwC;IACnD,gBAAgB,EAAE,oBAAoB;IACtC,WAAW,EAAE,cAAc;IAC3B,cAAc,EAAE,iBAAiB;IACjC,uBAAuB,EAAE,2BAA2B;CACrD,CAAC;AAEF;;;GAGG;AACH,MAAM,UAAU,sBAAsB,CAAC,MAAc;IACnD,MAAM,MAAM,GAAG,cAAc,CAAC,MAAM,CAAC,CAAC;IACtC,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,MAAM,IAAI,KAAK,CACb,0FAA0F;YACxF,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,CACvB,CAAC;IACJ,CAAC;IACD,IAAI,MAAe,CAAC;IACpB,IAAI,CAAC;QACH,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;IAC9B,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,IAAI,KAAK,CACb,iEAAkE,GAAa,CAAC,OAAO,EAAE,CAC1F,CAAC;IACJ,CAAC;IACD,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAClD,MAAM,IAAI,KAAK,CACb,kHAAkH,CACnH,CAAC;IACJ,CAAC;IACD,MAAM,OAAO,GAAG,MAAmC,CAAC;IACpD,MAAM,QAAQ,GAAG,aAAa,CAAC,OAAO,CAAC,CAAC;IACxC,IAAI,CAAC,QAAQ,IAAI,CAAC,QAAQ,CAAC,aAAa,EAAE,CAAC;QACzC,MAAM,IAAI,KAAK,CACb,sIAAsI,CACvI,CAAC;IACJ,CAAC;IACD,MAAM,QAAQ,GAAG,QAAQ,CAAC,aAAa,CAAC;IACxC,MAAM,MAAM,GAA2B,EAAE,CAAC;IAC1C,KAAK,MAAM,GAAG,IAAI,aAAa,EAAE,CAAC;QAChC,MAAM,QAAQ,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;QAC9B,MAAM,KAAK,GAAG,QAAQ,CAAC,QAAQ,CAAC,CAAC;QACjC,IAAI,CAAC,KAAK,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACjC,MAAM,IAAI,KAAK,CACb,uDAAuD,QAAQ,iBAAiB,QAAQ,CAAC,MAAM,IAAI,WAAW,uCAAuC,CACtJ,CAAC;QACJ,CAAC;QACD,MAAM,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;IACtB,CAAC;IACD,OAAO,MAAuB,CAAC;AACjC,CAAC;AAED;;;GAGG;AACH,SAAS,cAAc,CAAC,MAAc;IACpC,MAAM,KAAK,GAAG,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IAClC,IAAI,KAAK,KAAK,CAAC,CAAC;QAAE,OAAO,IAAI,CAAC;IAC9B,MAAM,GAAG,GAAG,MAAM,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;IACpC,IAAI,GAAG,KAAK,CAAC,CAAC,IAAI,GAAG,IAAI,KAAK;QAAE,OAAO,IAAI,CAAC;IAC5C,OAAO,MAAM,CAAC,KAAK,CAAC,KAAK,EAAE,GAAG,GAAG,CAAC,CAAC,CAAC;AACtC,CAAC;AAED;;;;GAIG;AACH,SAAS,aAAa,CACpB,OAAkC;IAElC,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;QAC5B,IAAI,KAAK,CAAC,aAAa,EAAE,iBAAiB,KAAK,KAAK,EAAE,CAAC;YACrD,OAAO,KAAK,CAAC;QACf,CAAC;IACH,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/runtime/exec.d.ts

@@ -8,9 +8,16 @@ export interface RunCommandOptions {
     cwd?: string;
     /** Timeout in ms (kill the child if it exceeds this). */
     timeoutMs?: number;
+    /**
+     * Extra environment variables to expose to the child process. When provided,
+     * these are MERGED on top of `process.env` (PATH, DEVELOPER_DIR, HOME and
+     * other inherited vars are preserved). Pass an empty object to inherit
+     * unchanged; pass `undefined` (or omit) for the same default.
+     */
+    env?: Record<string, string>;
 }
 /**
- * Run a command and collect stdout/stderr. Does not throw on non-zero exit code —
+ * Run a command and collect stdout/stderr. Does not throw on non-zero exit code,
  * the caller decides what's acceptable (e.g. `leaks` exits 1 when leaks are found,
  * which is normal).
  */

package/dist/runtime/exec.js

@@ -1,12 +1,18 @@
 import { spawn } from "node:child_process";
 /**
- * Run a command and collect stdout/stderr. Does not throw on non-zero exit code —
+ * Run a command and collect stdout/stderr. Does not throw on non-zero exit code,
  * the caller decides what's acceptable (e.g. `leaks` exits 1 when leaks are found,
  * which is normal).
  */
 export function runCommand(cmd, args, opts = {}) {
     return new Promise((resolve, reject) => {
-        const child = spawn(cmd, args, { cwd: opts.cwd });
+        const env = opts.env
+            ? { ...process.env, ...opts.env }
+            : undefined;
+        const child = spawn(cmd, args, {
+            cwd: opts.cwd,
+            ...(env ? { env } : {}),
+        });
         let stdout = "";
         let stderr = "";
         let killedByTimeout = false;

package/dist/runtime/exec.js.map

@@ -1 +1 @@
-{"version":3,"file":"exec.js","sourceRoot":"","sources":["../../src/runtime/exec.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAe3C;;;;GAIG;AACH,MAAM,UAAU,UAAU,CACxB,GAAW,EACX,IAAc,EACd,OAA0B,EAAE;IAE5B,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QACrC,MAAM,KAAK,GAAG,KAAK,CAAC,GAAG,EAAE,IAAI,EAAE,EAAE,GAAG,EAAE,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC;QAClD,IAAI,MAAM,GAAG,EAAE,CAAC;QAChB,IAAI,MAAM,GAAG,EAAE,CAAC;QAChB,IAAI,eAAe,GAAG,KAAK,CAAC;QAC5B,IAAI,KAAiC,CAAC;QAEtC,IAAI,IAAI,CAAC,SAAS,IAAI,IAAI,CAAC,SAAS,GAAG,CAAC,EAAE,CAAC;YACzC,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE;gBACtB,eAAe,GAAG,IAAI,CAAC;gBACvB,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;YACxB,CAAC,EAAE,IAAI,CAAC,SAAS,CAAC,CAAC;QACrB,CAAC;QAED,KAAK,CAAC,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,KAAa,EAAE,EAAE;YACxC,MAAM,IAAI,KAAK,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;QACnC,CAAC,CAAC,CAAC;QACH,KAAK,CAAC,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,KAAa,EAAE,EAAE;YACxC,MAAM,IAAI,KAAK,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;QACnC,CAAC,CAAC,CAAC;QACH,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,GAAG,EAAE,EAAE;YACxB,IAAI,KAAK;gBAAE,YAAY,CAAC,KAAK,CAAC,CAAC;YAC/B,MAAM,CAAC,GAAG,CAAC,CAAC;QACd,CAAC,CAAC,CAAC;QACH,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,IAAI,EAAE,EAAE;YACzB,IAAI,KAAK;gBAAE,YAAY,CAAC,KAAK,CAAC,CAAC;YAC/B,IAAI,eAAe,EAAE,CAAC;gBACpB,MAAM,CACJ,IAAI,KAAK,CACP,2BAA2B,IAAI,CAAC,SAAS,OAAO,GAAG,IAAI,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CACxE,CACF,CAAC;gBACF,OAAO;YACT,CAAC;YACD,OAAO,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,IAAI,CAAC,CAAC,EAAE,CAAC,CAAC;QAChD,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;AACL,CAAC"}
+{"version":3,"file":"exec.js","sourceRoot":"","sources":["../../src/runtime/exec.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAsB3C;;;;GAIG;AACH,MAAM,UAAU,UAAU,CACxB,GAAW,EACX,IAAc,EACd,OAA0B,EAAE;IAE5B,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QACrC,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG;YAClB,CAAC,CAAC,EAAE,GAAG,OAAO,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,GAAG,EAAE;YACjC,CAAC,CAAC,SAAS,CAAC;QACd,MAAM,KAAK,GAAG,KAAK,CAAC,GAAG,EAAE,IAAI,EAAE;YAC7B,GAAG,EAAE,IAAI,CAAC,GAAG;YACb,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SACxB,CAAC,CAAC;QACH,IAAI,MAAM,GAAG,EAAE,CAAC;QAChB,IAAI,MAAM,GAAG,EAAE,CAAC;QAChB,IAAI,eAAe,GAAG,KAAK,CAAC;QAC5B,IAAI,KAAiC,CAAC;QAEtC,IAAI,IAAI,CAAC,SAAS,IAAI,IAAI,CAAC,SAAS,GAAG,CAAC,EAAE,CAAC;YACzC,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE;gBACtB,eAAe,GAAG,IAAI,CAAC;gBACvB,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;YACxB,CAAC,EAAE,IAAI,CAAC,SAAS,CAAC,CAAC;QACrB,CAAC;QAED,KAAK,CAAC,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,KAAa,EAAE,EAAE;YACxC,MAAM,IAAI,KAAK,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;QACnC,CAAC,CAAC,CAAC;QACH,KAAK,CAAC,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,KAAa,EAAE,EAAE;YACxC,MAAM,IAAI,KAAK,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;QACnC,CAAC,CAAC,CAAC;QACH,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,GAAG,EAAE,EAAE;YACxB,IAAI,KAAK;gBAAE,YAAY,CAAC,KAAK,CAAC,CAAC;YAC/B,MAAM,CAAC,GAAG,CAAC,CAAC;QACd,CAAC,CAAC,CAAC;QACH,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,IAAI,EAAE,EAAE;YACzB,IAAI,KAAK;gBAAE,YAAY,CAAC,KAAK,CAAC,CAAC;YAC/B,IAAI,eAAe,EAAE,CAAC;gBACpB,MAAM,CACJ,IAAI,KAAK,CACP,2BAA2B,IAAI,CAAC,SAAS,OAAO,GAAG,IAAI,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CACxE,CACF,CAAC;gBACF,OAAO;YACT,CAAC;YACD,OAAO,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,IAAI,CAAC,CAAC,EAAE,CAAC,CAAC;QAChD,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/runtime/simctl.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Thin wrappers around `xcrun simctl` for booting, installing, and launching
+ * iOS apps on the iOS Simulator. Used by `bootAndLaunchForLeakInvestigation`
+ * to set up a leak-investigation environment with `MallocStackLogging=1`.
+ *
+ * Design notes:
+ * - All operations are idempotent where possible (boot ignores "already booted",
+ *   launch uses --terminate-running-process to atomically replace any prior instance).
+ * - Env vars are propagated to the child via the `SIMCTL_CHILD_*` prefix
+ *   convention enforced by simctl. The caller passes plain `MallocStackLogging=1`
+ *   and we prefix it before invoking simctl.
+ */
+export interface SimulatorDevice {
+    udid: string;
+    name: string;
+    state: "Booted" | "Shutdown" | string;
+    /** OS runtime, e.g. "iOS 17.5" or "iOS-17-5". */
+    runtime: string;
+}
+/**
+ * Find the first booted simulator. Returns null when none are booted.
+ * Used as a fallback when the caller doesn't specify a simulator.
+ */
+export declare function findBootedSimulator(): Promise<SimulatorDevice | null>;
+/**
+ * Find a simulator by display name (e.g. "iPhone 15"), optionally constrained
+ * to a runtime version. Returns null when no match.
+ *
+ * @param os Either "latest" (highest available runtime), an explicit version
+ *           like "17.5", or undefined (any runtime).
+ */
+export declare function findSimulatorByName(name: string, os?: string): Promise<SimulatorDevice | null>;
+/**
+ * Boot a simulator. Idempotent: if the device is already booted, returns
+ * cleanly. Then waits via `simctl bootstatus -b` until SpringBoard is ready,
+ * which prevents flaky `install` calls right after boot.
+ */
+export declare function bootSimulator(udid: string): Promise<void>;
+/**
+ * Install (or reinstall) an app bundle on a simulator. Idempotent by design;
+ * simctl overwrites a prior install at the same bundle identifier.
+ */
+export declare function installApp(udid: string, appPath: string): Promise<void>;
+export interface LaunchAppResult {
+    /** Simulator-internal PID printed by simctl (NOT the host PID). */
+    simPid: number;
+    bundleId: string;
+}
+/**
+ * Launch an app on a booted simulator with the given env vars and launch args.
+ * Uses `--terminate-running-process` so any existing instance is replaced
+ * atomically (no race where stale env vars persist).
+ *
+ * Env vars are propagated to the child via the `SIMCTL_CHILD_*` prefix that
+ * simctl honors. Pass plain keys (e.g. `MallocStackLogging`); we prefix.
+ */
+export declare function launchApp(udid: string, bundleId: string, env?: Record<string, string>, launchArgs?: string[]): Promise<LaunchAppResult>;
+/**
+ * Take a screenshot of the simulator's screen and write it to `outputPath`.
+ * Wraps `xcrun simctl io <udid> screenshot <path>`.
+ */
+export declare function takeScreenshot(udid: string, outputPath: string): Promise<void>;
+/** Pure: parse the simulator-internal PID from `simctl launch` stdout. Exposed for tests. */
+export declare function parseLaunchPid(stdout: string, bundleId: string): number | null;
+/** Pure: parse a `simctl list devices --json` payload into a flat list. Exposed for tests. */
+export declare function parseSimctlDevices(stdout: string): SimulatorDevice[];
+/** Pure: produce a sortable numeric key from a runtime identifier. */
+export declare function runtimeSortKey(runtime: string): number;