memorydetective 1.7.0 → 1.8.0

package/dist/runtime/simctl.js

@@ -0,0 +1,194 @@
+/**
+ * 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.
+ */
+import { runCommand } from "./exec.js";
+/**
+ * Find the first booted simulator. Returns null when none are booted.
+ * Used as a fallback when the caller doesn't specify a simulator.
+ */
+export async function findBootedSimulator() {
+    const result = await runCommand("xcrun", ["simctl", "list", "devices", "booted", "--json"], { timeoutMs: 15_000 });
+    if (result.code !== 0) {
+        throw new Error(`xcrun simctl list failed (code ${result.code}): ${result.stderr || result.stdout}`);
+    }
+    const devices = parseSimctlDevices(result.stdout);
+    return devices.find((d) => d.state === "Booted") ?? 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 async function findSimulatorByName(name, os) {
+    const result = await runCommand("xcrun", ["simctl", "list", "devices", "--json"], { timeoutMs: 15_000 });
+    if (result.code !== 0) {
+        throw new Error(`xcrun simctl list failed (code ${result.code}): ${result.stderr || result.stdout}`);
+    }
+    const devices = parseSimctlDevices(result.stdout);
+    const matches = devices.filter((d) => d.name === name);
+    if (matches.length === 0)
+        return null;
+    if (!os)
+        return matches[0];
+    if (os === "latest") {
+        return pickLatestByRuntime(matches);
+    }
+    // Runtime keys come back like "com.apple.CoreSimulator.SimRuntime.iOS-17-5".
+    // Match either "17.5" or "iOS 17.5" from the user.
+    const normalized = os.replace(/^iOS\s+/i, "").replace(/\./g, "-");
+    return matches.find((d) => d.runtime.includes(normalized)) ?? 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 async function bootSimulator(udid) {
+    const boot = await runCommand("xcrun", ["simctl", "boot", udid], {
+        timeoutMs: 60_000,
+    });
+    // CoreSimulator returns non-zero with "Unable to boot device in current state: Booted"
+    // when already booted. Treat that as success.
+    const alreadyBooted = /current state:\s*Booted/i.test(boot.stderr + boot.stdout);
+    if (boot.code !== 0 && !alreadyBooted) {
+        throw new Error(`simctl boot ${udid} failed (code ${boot.code}): ${boot.stderr || boot.stdout}`);
+    }
+    // -b blocks until the system is fully booted (SpringBoard up).
+    const status = await runCommand("xcrun", ["simctl", "bootstatus", udid, "-b"], { timeoutMs: 120_000 });
+    if (status.code !== 0) {
+        throw new Error(`simctl bootstatus ${udid} -b failed (code ${status.code}): ${status.stderr || status.stdout}`);
+    }
+}
+/**
+ * Install (or reinstall) an app bundle on a simulator. Idempotent by design;
+ * simctl overwrites a prior install at the same bundle identifier.
+ */
+export async function installApp(udid, appPath) {
+    const result = await runCommand("xcrun", ["simctl", "install", udid, appPath], { timeoutMs: 120_000 });
+    if (result.code !== 0) {
+        throw new Error(`simctl install ${udid} ${appPath} failed (code ${result.code}): ${result.stderr || result.stdout}`);
+    }
+}
+/**
+ * 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 async function launchApp(udid, bundleId, env = {}, launchArgs = []) {
+    const args = [
+        "simctl",
+        "launch",
+        "--terminate-running-process",
+        udid,
+        bundleId,
+        ...launchArgs,
+    ];
+    const prefixedEnv = {};
+    for (const [k, v] of Object.entries(env)) {
+        prefixedEnv[`SIMCTL_CHILD_${k}`] = v;
+    }
+    const result = await runCommand("xcrun", args, {
+        timeoutMs: 60_000,
+        env: prefixedEnv,
+    });
+    if (result.code !== 0) {
+        throw new Error(`simctl launch ${bundleId} on ${udid} failed (code ${result.code}): ${result.stderr || result.stdout}`);
+    }
+    // simctl prints "<bundleId>: <pid>" on success.
+    const simPid = parseLaunchPid(result.stdout, bundleId);
+    if (simPid === null) {
+        throw new Error(`simctl launch succeeded but PID line was not parseable. stdout: ${result.stdout}`);
+    }
+    return { simPid, bundleId };
+}
+/**
+ * Take a screenshot of the simulator's screen and write it to `outputPath`.
+ * Wraps `xcrun simctl io <udid> screenshot <path>`.
+ */
+export async function takeScreenshot(udid, outputPath) {
+    const result = await runCommand("xcrun", ["simctl", "io", udid, "screenshot", outputPath], { timeoutMs: 30_000 });
+    if (result.code !== 0) {
+        throw new Error(`simctl io ${udid} screenshot failed (code ${result.code}): ${result.stderr || result.stdout}`);
+    }
+}
+/** Pure: parse the simulator-internal PID from `simctl launch` stdout. Exposed for tests. */
+export function parseLaunchPid(stdout, bundleId) {
+    const escaped = bundleId.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    const re = new RegExp(`${escaped}\\s*:\\s*(\\d+)`);
+    const match = stdout.match(re);
+    if (!match)
+        return null;
+    const pid = parseInt(match[1], 10);
+    return Number.isInteger(pid) && pid > 0 ? pid : null;
+}
+/** Pure: parse a `simctl list devices --json` payload into a flat list. Exposed for tests. */
+export function parseSimctlDevices(stdout) {
+    let parsed;
+    try {
+        parsed = JSON.parse(stdout);
+    }
+    catch (err) {
+        throw new Error(`simctl list devices --json output failed JSON.parse: ${err.message}`);
+    }
+    const out = [];
+    if (!parsed.devices || typeof parsed.devices !== "object") {
+        return out;
+    }
+    for (const [runtime, list] of Object.entries(parsed.devices)) {
+        if (!Array.isArray(list))
+            continue;
+        for (const dev of list) {
+            const udid = typeof dev.udid === "string" ? dev.udid : null;
+            const name = typeof dev.name === "string" ? dev.name : null;
+            const state = typeof dev.state === "string" ? dev.state : "Unknown";
+            if (!udid || !name)
+                continue;
+            out.push({ udid, name, state, runtime });
+        }
+    }
+    return out;
+}
+/**
+ * Pick the simulator with the highest runtime version. Used when the caller
+ * asks for `os: "latest"`. Comparison is on the digits inside the runtime
+ * key (e.g. "iOS-17-5" → 17.5).
+ */
+function pickLatestByRuntime(devices) {
+    if (devices.length === 0)
+        return null;
+    let best = devices[0];
+    let bestKey = runtimeSortKey(best.runtime);
+    for (const dev of devices.slice(1)) {
+        const key = runtimeSortKey(dev.runtime);
+        if (key > bestKey) {
+            best = dev;
+            bestKey = key;
+        }
+    }
+    return best;
+}
+/** Pure: produce a sortable numeric key from a runtime identifier. */
+export function runtimeSortKey(runtime) {
+    const match = runtime.match(/(\d+)[-.](\d+)(?:[-.](\d+))?/);
+    if (!match)
+        return 0;
+    const major = parseInt(match[1], 10);
+    const minor = parseInt(match[2], 10);
+    const patch = match[3] ? parseInt(match[3], 10) : 0;
+    return major * 10_000 + minor * 100 + patch;
+}
+//# sourceMappingURL=simctl.js.map

package/dist/runtime/simctl.js.map

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

package/dist/tools/bootAndLaunchForLeakInvestigation.d.ts

@@ -0,0 +1,166 @@
+/**
+ * Build, boot, install, and launch an iOS app on the iOS Simulator with
+ * `MallocStackLogging=1` (and any caller-supplied env vars) applied. Returns
+ * the host PID + simulator UDID + bundle id ready to chain into
+ * `captureMemgraph`.
+ *
+ * Why this exists: `leaks --outputGraph` regressed on macOS 26.x and aborts
+ * with `Failed to get DYLD info for task` when the target was not launched
+ * with malloc-stack-logging in its environment. Capturing a memgraph after
+ * the fact does not work; the env vars must be set at launch. This tool
+ * gives users a single MCP call that produces a leak-investigable process
+ * without requiring them to wire up xcodebuild + simctl manually.
+ *
+ * Out of scope: UI driving (Phase 3), composite snapshots (Phase 3), physical
+ * iOS devices (`leaks --outputGraph` does not support them).
+ */
+import { z } from "zod";
+import type { NextCallSuggestion } from "../types.js";
+export declare const bootAndLaunchForLeakInvestigationShape: {
+    readonly workspace: z.ZodOptional<z.ZodString>;
+    readonly project: z.ZodOptional<z.ZodString>;
+    readonly scheme: z.ZodString;
+    readonly configuration: z.ZodDefault<z.ZodString>;
+    readonly bundleId: z.ZodOptional<z.ZodString>;
+    readonly derivedDataPath: z.ZodOptional<z.ZodString>;
+    readonly simulator: z.ZodOptional<z.ZodObject<{
+        udid: z.ZodOptional<z.ZodString>;
+        name: z.ZodOptional<z.ZodString>;
+        os: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        name?: string | undefined;
+        udid?: string | undefined;
+        os?: string | undefined;
+    }, {
+        name?: string | undefined;
+        udid?: string | undefined;
+        os?: string | undefined;
+    }>>;
+    readonly envVars: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    readonly launchArgs: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    readonly buildBeforeLaunch: z.ZodDefault<z.ZodBoolean>;
+    readonly warmupSeconds: z.ZodDefault<z.ZodNumber>;
+};
+export declare const bootAndLaunchForLeakInvestigationSchema: z.ZodEffects<z.ZodObject<{
+    readonly workspace: z.ZodOptional<z.ZodString>;
+    readonly project: z.ZodOptional<z.ZodString>;
+    readonly scheme: z.ZodString;
+    readonly configuration: z.ZodDefault<z.ZodString>;
+    readonly bundleId: z.ZodOptional<z.ZodString>;
+    readonly derivedDataPath: z.ZodOptional<z.ZodString>;
+    readonly simulator: z.ZodOptional<z.ZodObject<{
+        udid: z.ZodOptional<z.ZodString>;
+        name: z.ZodOptional<z.ZodString>;
+        os: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        name?: string | undefined;
+        udid?: string | undefined;
+        os?: string | undefined;
+    }, {
+        name?: string | undefined;
+        udid?: string | undefined;
+        os?: string | undefined;
+    }>>;
+    readonly envVars: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    readonly launchArgs: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    readonly buildBeforeLaunch: z.ZodDefault<z.ZodBoolean>;
+    readonly warmupSeconds: z.ZodDefault<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    scheme: string;
+    configuration: string;
+    launchArgs: string[];
+    buildBeforeLaunch: boolean;
+    warmupSeconds: number;
+    simulator?: {
+        name?: string | undefined;
+        udid?: string | undefined;
+        os?: string | undefined;
+    } | undefined;
+    bundleId?: string | undefined;
+    workspace?: string | undefined;
+    project?: string | undefined;
+    derivedDataPath?: string | undefined;
+    envVars?: Record<string, string> | undefined;
+}, {
+    scheme: string;
+    simulator?: {
+        name?: string | undefined;
+        udid?: string | undefined;
+        os?: string | undefined;
+    } | undefined;
+    bundleId?: string | undefined;
+    workspace?: string | undefined;
+    project?: string | undefined;
+    configuration?: string | undefined;
+    derivedDataPath?: string | undefined;
+    envVars?: Record<string, string> | undefined;
+    launchArgs?: string[] | undefined;
+    buildBeforeLaunch?: boolean | undefined;
+    warmupSeconds?: number | undefined;
+}>, {
+    scheme: string;
+    configuration: string;
+    launchArgs: string[];
+    buildBeforeLaunch: boolean;
+    warmupSeconds: number;
+    simulator?: {
+        name?: string | undefined;
+        udid?: string | undefined;
+        os?: string | undefined;
+    } | undefined;
+    bundleId?: string | undefined;
+    workspace?: string | undefined;
+    project?: string | undefined;
+    derivedDataPath?: string | undefined;
+    envVars?: Record<string, string> | undefined;
+}, {
+    scheme: string;
+    simulator?: {
+        name?: string | undefined;
+        udid?: string | undefined;
+        os?: string | undefined;
+    } | undefined;
+    bundleId?: string | undefined;
+    workspace?: string | undefined;
+    project?: string | undefined;
+    configuration?: string | undefined;
+    derivedDataPath?: string | undefined;
+    envVars?: Record<string, string> | undefined;
+    launchArgs?: string[] | undefined;
+    buildBeforeLaunch?: boolean | undefined;
+    warmupSeconds?: number | undefined;
+}>;
+export type BootAndLaunchForLeakInvestigationInput = z.infer<typeof bootAndLaunchForLeakInvestigationSchema>;
+export type LaunchState = "launched" | "buildFailed" | "installFailed" | "launchFailed" | "pidNotFound" | "noSimulatorAvailable";
+export interface BootAndLaunchForLeakInvestigationResult {
+    ok: boolean;
+    state: LaunchState;
+    simulatorUDID?: string;
+    pid?: number;
+    bundleId?: string;
+    appName?: string;
+    appPath?: string;
+    appliedEnvVars: Record<string, string>;
+    steps: string[];
+    warnings?: string[];
+    failureReason?: string;
+    suggestedNextCalls?: NextCallSuggestion[];
+}
+export declare function bootAndLaunchForLeakInvestigation(input: BootAndLaunchForLeakInvestigationInput): Promise<BootAndLaunchForLeakInvestigationResult>;
+/**
+ * Resolve the host-side PID for an app running inside the target simulator.
+ *
+ * Strategy: list every host process with `ps -Ao pid,command`, then pick lines
+ * whose command path includes the simulator UDID (i.e. lives under
+ * `~/Library/Developer/CoreSimulator/Devices/<UDID>/...`) AND whose path ends
+ * with `/<EXECUTABLE_NAME>`. This handles two cases natively:
+ *   1. Multi-simulator: filtering by UDID disambiguates from same-named apps in other simulators.
+ *   2. Long executable names: we match on full path, so the 15-char `comm` truncation that breaks `pgrep -x` is irrelevant.
+ *
+ * Returns the PID, or null when nothing matched (the typical reasons: app
+ * still launching, or executable name does not appear in the path because
+ * the user passed a custom override).
+ */
+export declare function resolveHostPid(udid: string, executableName: string): Promise<number | null>;
+/** Pure: filter `ps` output for the simulator's app process. Exposed for tests. */
+export declare function pickHostPidFromPs(psOutput: string, udid: string, executableName: string): number | null;