@mgcrea/mcp-ios-simulator 0.1.0

package/dist/config-C1TH-p-c.js

@@ -0,0 +1,1553 @@
+import { McpServer } from "@modelcontextprotocol/server";
+import { readFileSync } from "node:fs";
+import { CommandError, CommandTimeoutError, IosError, IosError as IosError$1, ToolchainError, WdaClient, WdaError, WdaUnavailableError, assertNoShellMetachars, createArgs, createExec, registerInputTools, registerScreenTools, wrap } from "@mgcrea/mcp-ios-core";
+import { dirname, join } from "node:path";
+import { mkdir, mkdtemp, open, readFile, rm, writeFile } from "node:fs/promises";
+import { homedir, tmpdir } from "node:os";
+import { z } from "zod";
+import { spawn } from "node:child_process";
+import { fileURLToPath } from "node:url";
+//#region src/build-info.ts
+const readPackageJson = () => {
+	try {
+		const pkgUrl = new URL("../package.json", import.meta.url);
+		return JSON.parse(readFileSync(pkgUrl, "utf8"));
+	} catch {
+		return {
+			name: "@mgcrea/mcp-ios-device",
+			version: "0.0.0"
+		};
+	}
+};
+const pkg = readPackageJson();
+const BUILD_INFO = {
+	name: pkg.name,
+	version: pkg.version,
+	gitCommit: "140a684",
+	gitCommitDate: "2026-09-04T23:43:28+02:00"
+};
+//#endregion
+//#region src/client/errors.ts
+/** Raising the budget, or noticing the simulator died mid-call. */
+const TIMEOUT_REMEDY = "Raise IOS_SIMULATOR_TIMEOUT_MS if this is a slow operation (a boot or a large `install` genuinely takes tens of seconds), or check the simulator is still booted.";
+const TOOLCHAIN_REMEDY = "Install Xcode and run `xcode-select --install`, or point IOS_SIMULATOR_XCRUN_PATH at a different xcrun.";
+/**
+* How to get the runner up. Much shorter than the device server's equivalent,
+* and that is the headline difference between the two: a simulator runner needs
+* no Apple team, no signing, no trust prompt and no tunnel.
+*/
+const START_RUNNER_REMEDY = "Build and start the runner with `scripts/wda.sh setup` then `scripts/wda.sh run` (or `npx -p @mgcrea/mcp-ios-simulator ios-simulator-wda run` from an npm install) and leave it open — the HTTP server is the XCTest process, so it stops when that command does. It needs no Apple Developer team: a simulator build is not signed.";
+/** What to do when WebDriverAgent does not answer at all. */
+const WDA_UNAVAILABLE_REMEDY = `${START_RUNNER_REMEDY} Everything except ios_simulator_ui_tree and the input tools works without it — screenshots go through simctl. If something else already forwards the port, set IOS_SIMULATOR_WDA_URL.`;
+/** No simulator matched, or several did and none was named. */
+var SimulatorNotFoundError = class extends IosError {
+	name = "SimulatorNotFoundError";
+	constructor(message, remedy) {
+		super(message, { remedy });
+	}
+};
+/**
+* The simulator exists but is shut down.
+*
+* Its own error class because the fix is a single specific call and nothing
+* else: almost every simctl subcommand fails this way, `listapps` included, so
+* "it is shut down" would otherwise be buried in a CoreSimulator envelope that
+* reads like a lookup bug.
+*/
+var SimulatorNotBootedError = class extends IosError {
+	name = "SimulatorNotBootedError";
+	constructor(name, udid) {
+		super(`${name} is shut down.`, { remedy: `Boot it with ios_simulator_power {"simulator":"${udid}","state":"booted"} — this server never boots a simulator implicitly, because a cold boot takes tens of seconds and puts a window on the user's screen.` });
+	}
+};
+/**
+* The simulator's runtime is not installed, so CoreSimulator cannot service it.
+*
+* Worth its own class because the failure it prevents is not an error message
+* at all: `simctl io` against one of these aborts with an uncaught
+* NSInternalInconsistencyException and a thirty-line stack trace.
+*/
+var RuntimeUnavailableError = class extends IosError {
+	name = "RuntimeUnavailableError";
+	constructor(name, reason) {
+		super(`${name} is unavailable${reason ? `: ${reason}` : "."}`, { remedy: "The iOS runtime this simulator was created against is not installed. Install it in Xcode > Settings > Components, or clear the orphans with `xcrun simctl delete unavailable`." });
+	}
+};
+/** Thrown when a write path is reached while IOS_SIMULATOR_ALLOW_WRITES is off. */
+var WritesDisabledError = class extends IosError {
+	name = "WritesDisabledError";
+	constructor(what) {
+		super(`${what} changes the simulator, but writes are disabled. Unset IOS_SIMULATOR_ALLOW_WRITES (it defaults to on) to enable them again.`);
+	}
+};
+/** A shut-down simulator captures nothing, and that is the usual cause here. */
+const EMPTY_SCREENSHOT_REMEDY = "The simulator produced an empty capture. Check it is actually booted with ios_simulator_diagnostics, and that its runtime is installed.";
+//#endregion
+//#region src/client/display.ts
+/**
+* Screen geometry for a simulator, which has no `devicectl device info displays`.
+*
+* Three sources were measured, and the split between them is the interesting
+* part:
+*
+*  - **`profile.plist`, per device type.** `mainScreenWidth`, `mainScreenHeight`
+*    and `mainScreenScale`, agreeing exactly with both `io enumerate` and the
+*    captured PNG. A pure file read: no simctl call, nothing to boot, and no
+*    crash surface on an unavailable simulator. This is where `pointScale`
+*    comes from.
+*  - **The captured PNG's own header.** This is where *pixels* come from
+*    whenever there is a capture, because `simctl io … screenConfig geometry`
+*    can resize a booted simulator's screen at runtime and the profile would
+*    then be silently wrong — putting every tap coordinate in the wrong space
+*    with nothing looking wrong.
+*  - **`io enumerate`**, which also reports it, but is a text parse of a
+*    150-line dump and aborts on an unavailable device. Not used.
+*/
+const profilePlistPath = (bundlePath) => join(bundlePath, "Contents", "Resources", "profile.plist");
+const readScreenProfile = async (deviceType, opts) => {
+	if (!deviceType.bundlePath) return {};
+	const { stdout } = await opts.exec(opts.plutilPath, [
+		"-convert",
+		"json",
+		"-o",
+		"-",
+		profilePlistPath(deviceType.bundlePath)
+	], opts.timeoutMs);
+	try {
+		return JSON.parse(stdout);
+	} catch {
+		return {};
+	}
+};
+/**
+* Width and height straight out of a PNG's IHDR.
+*
+* Cheaper than shelling to `sips` for the one number that must not be stale,
+* and the bytes are already in hand: the signature is fixed, `IHDR` is always
+* the first chunk, and the two dimensions are big-endian at offsets 16 and 20.
+*/
+const pngDimensions = (png) => {
+	const SIGNATURE = Buffer.from([
+		137,
+		80,
+		78,
+		71,
+		13,
+		10,
+		26,
+		10
+	]);
+	if (png.length < 24 || !png.subarray(0, 8).equals(SIGNATURE)) return void 0;
+	if (png.subarray(12, 16).toString("ascii") !== "IHDR") return void 0;
+	return {
+		width: png.readUInt32BE(16),
+		height: png.readUInt32BE(20)
+	};
+};
+/**
+* Assemble a `DisplayInfo`.
+*
+* `orientation` is derived by comparing the capture's own aspect against the
+* profile's portrait dimensions, and is `"unknown"` when there is no capture to
+* compare — never guessed as `"portrait"`, because the whole point of the field
+* is telling a caller whether the screen they are about to read is rotated.
+*
+* `backlightState` is left undefined: a simulator has no backlight, and
+* `io enumerate`'s `Power state` is about the framebuffer port rather than the
+* screen, so mapping it would be a lie.
+*/
+const toDisplayInfo = (profile, capture) => {
+	const scale = profile.mainScreenScale ?? 1;
+	const pixelWidth = capture?.width ?? profile.mainScreenWidth;
+	const pixelHeight = capture?.height ?? profile.mainScreenHeight;
+	if (!pixelWidth || !pixelHeight) throw new IosError$1("Could not determine the simulator's screen geometry.", { remedy: "The device type's profile.plist could not be read and no screenshot was available. Run ios_simulator_diagnostics — an unavailable runtime is the usual cause." });
+	const landscape = profile.mainScreenWidth !== void 0 && profile.mainScreenHeight !== void 0 ? pixelWidth > pixelHeight && profile.mainScreenWidth < profile.mainScreenHeight : pixelWidth > pixelHeight;
+	return {
+		pixelWidth,
+		pixelHeight,
+		pointWidth: Math.round(pixelWidth / scale),
+		pointHeight: Math.round(pixelHeight / scale),
+		pointScale: scale,
+		orientation: capture ? landscape ? "landscape" : "portrait" : "unknown"
+	};
+};
+//#endregion
+//#region src/client/shape.ts
+/**
+* Flatten the runtime-keyed map `list devices` returns.
+*
+* The key is a runtime *identifier* and identifiers are not unique — a machine
+* carrying both iOS 26.4 and 26.4.1 has two entries under
+* `com.apple.CoreSimulator.SimRuntime.iOS-26-4`. So the key is never used as a
+* primary key: it is joined against `list runtimes` for a display name, 0..n
+* matches tolerated, and carried through verbatim besides.
+*/
+const summarizeDevices = (devices, runtimes, deviceTypes) => {
+	const runtimeName = new Map(runtimes.map((r) => [r.identifier, r.name ?? r.version ?? r.identifier]));
+	const typeName = new Map(deviceTypes.map((t) => [t.identifier, t.name]));
+	return Object.entries(devices).flatMap(([runtimeId, sims]) => (sims ?? []).map((sim) => ({
+		id: sim.udid,
+		name: sim.name,
+		state: sim.state,
+		runtime: runtimeName.get(runtimeId) ?? runtimeId.split(".").pop() ?? runtimeId,
+		deviceType: sim.deviceTypeIdentifier ? typeName.get(sim.deviceTypeIdentifier) : void 0,
+		deviceTypeIdentifier: sim.deviceTypeIdentifier,
+		available: sim.isAvailable !== false,
+		...sim.availabilityError ? { unavailableReason: sim.availabilityError } : {},
+		...sim.lastBootedAt ? { lastBootedAt: sim.lastBootedAt } : {}
+	})));
+};
+/** `file:///Users/…/Foo.app/` → `/Users/…/Foo.app`, which is what a person can use. */
+const toPath = (url) => {
+	if (!url) return void 0;
+	if (!url.startsWith("file://")) return url;
+	try {
+		return decodeURIComponent(new URL(url).pathname).replace(/\/$/, "");
+	} catch {
+		return url;
+	}
+};
+const summarizeApps = (apps, opts = {}) => Object.values(apps).filter((app) => opts.includeAll === true || app.ApplicationType === "User").map((app) => ({
+	bundleId: app.CFBundleIdentifier ?? "",
+	name: app.CFBundleDisplayName ?? app.CFBundleName,
+	version: app.CFBundleShortVersionString,
+	build: app.CFBundleVersion,
+	type: app.ApplicationType,
+	bundlePath: toPath(app.Bundle ?? app.Path),
+	dataContainer: toPath(app.DataContainer)
+})).filter((app) => app.bundleId !== "").toSorted((a, b) => a.bundleId.localeCompare(b.bundleId));
+/** The public shape of one row of `ios_simulator_list`. */
+const toListRow = (sim) => ({
+	udid: sim.id,
+	name: sim.name,
+	state: sim.state,
+	runtime: sim.runtime,
+	...sim.deviceType ? { deviceType: sim.deviceType } : {},
+	...sim.available ? {} : { available: false },
+	...sim.unavailableReason ? { unavailableReason: sim.unavailableReason } : {}
+});
+//#endregion
+//#region src/client/simctl.ts
+/**
+* Pull the human sentence out of a CoreSimulator error envelope.
+*
+*   An error was encountered processing the command (domain=…, code=405):
+*   Unable to lookup in current state: Shutdown
+*
+* Without this the message a caller sees is the first line, which names a
+* numeric code and says nothing about what to do.
+*/
+const parseSimctlError = (stderr) => {
+	const envelope = /\(domain=([^,]+),\s*code=(\d+)\)\s*:?\s*\n?([\s\S]*)/.exec(stderr);
+	if (envelope) return {
+		domain: envelope[1]?.trim(),
+		code: Number(envelope[2]),
+		message: (envelope[3] ?? "").trim().split("\n")[0]?.trim() ?? stderr.trim()
+	};
+	return { message: stderr.trim().split("\n")[0]?.trim() ?? stderr.trim() };
+};
+/**
+* simctl reports its interesting failures in prose, and each has a different
+* fix. Every string here describes something only a simulator has.
+*/
+const remedyFor = (stderr) => {
+	const { message } = parseSimctlError(stderr);
+	const text = `${stderr} ${message}`.toLowerCase();
+	if (text.includes("invalid device")) return "That is not a UDID or a name simctl knows. Run ios_simulator_list to see what exists.";
+	if (text.includes("unable to lookup in current state: shutdown")) return "The simulator is shut down. Boot it with ios_simulator_power {\"state\":\"booted\"}.";
+	if (text.includes("current state: booted")) return "The simulator is already booted, which for most operations means there is nothing to do.";
+	if (text.includes("no such file or directory")) return "Check the path exists and is a `.app` **bundle directory** built for the simulator — an `.ipa` or a device build will not install, and reports exactly this.";
+	if (text.includes("failed to initialize io ports")) return "The simulator's runtime is not installed, so CoreSimulator cannot service it. Install the runtime, or clear the orphans with `xcrun simctl delete unavailable`.";
+};
+/**
+* The one argument that must never reach simctl.
+*
+* `erase`, `delete` and `shutdown` all accept the literal string `all`, and
+* `simctl erase all` wipes every simulator on the machine. A device hint that
+* happens to be the word "all" is the single worst thing this server could
+* forward, so it is refused here as well as in the resolver — the resolver is
+* where it should be caught, and this is where it cannot be missed.
+*/
+const assertNotBulkTarget = (udid) => {
+	if (udid === "all" || udid === "unavailable" || udid === "booted") throw new IosError$1(`Refusing to pass "${udid}" to simctl as a device.`, { remedy: "simctl reads these as *every* matching simulator, so `erase all` would wipe the machine. Resolve to one concrete UDID with ios_simulator_list first." });
+};
+var Simctl = class {
+	opts;
+	exec;
+	/** Device types change only when Xcode is updated; re-reading is pure cost. */
+	deviceTypes;
+	constructor(opts) {
+		this.opts = opts;
+		this.exec = opts.exec ?? createExec({
+			timeout: "Raise IOS_SIMULATOR_TIMEOUT_MS if this is a slow operation (a boot or a large `install` genuinely takes tens of seconds), or check the simulator is still booted.",
+			toolchain: "Install Xcode and run `xcode-select --install`, or point IOS_SIMULATOR_XCRUN_PATH at a different xcrun.",
+			remedyFor
+		});
+	}
+	/** Raw stdout, for the subcommands that answer in prose. */
+	async run(args) {
+		this.opts.logger?.debug?.("simctl", ...args);
+		const { stdout } = await this.exec(this.opts.xcrunPath, ["simctl", ...args], this.opts.timeoutMs);
+		return stdout;
+	}
+	/**
+	* `list` and only `list`. `-e` stops `/` being escaped as `\/`, which matters
+	* only for fixture readability but costs nothing.
+	*/
+	async runJson(args) {
+		const stdout = await this.run([
+			...args,
+			"-j",
+			"-e"
+		]);
+		try {
+			return JSON.parse(stdout);
+		} catch {
+			throw new IosError$1(`simctl ${args.join(" ")} did not return JSON.`, { details: stdout.slice(0, 400) });
+		}
+	}
+	/**
+	* A NeXTSTEP plist, via `plutil` and a temp file.
+	*
+	* The obvious `simctl listapps … | plutil -convert json -o - -` is not
+	* expressible: `ExecImpl` takes argv and no stdin, deliberately, because that
+	* is what keeps every caller value data rather than shell syntax. So simctl's
+	* stdout is written out and handed to plutil by path. A fresh directory per
+	* call rather than a shared one, so two concurrent tools cannot read each
+	* other's answer with nothing looking wrong.
+	*/
+	async runPlist(args) {
+		const stdout = await this.run(args);
+		const dir = await mkdtemp(join(tmpdir(), "simctl-"));
+		const path = join(dir, "out.plist");
+		try {
+			await writeFile(path, stdout);
+			const { stdout: json } = await this.exec(this.opts.plutilPath, [
+				"-convert",
+				"json",
+				"-o",
+				"-",
+				path
+			], this.opts.timeoutMs);
+			return JSON.parse(json);
+		} catch (err) {
+			if (err instanceof IosError$1) throw err;
+			throw new IosError$1(`Could not read simctl ${args[0]} output as a property list.`, { details: stdout.slice(0, 400) });
+		} finally {
+			await rm(dir, {
+				recursive: true,
+				force: true
+			});
+		}
+	}
+	async listDevices() {
+		return (await this.runJson(["list", "devices"])).devices ?? {};
+	}
+	async listRuntimes() {
+		return (await this.runJson(["list", "runtimes"])).runtimes ?? [];
+	}
+	async listDeviceTypes() {
+		this.deviceTypes ??= (await this.runJson(["list", "devicetypes"])).devicetypes ?? [];
+		return this.deviceTypes;
+	}
+	async boot(udid) {
+		assertNotBulkTarget(udid);
+		await this.run(["boot", udid]);
+	}
+	async shutdown(udid) {
+		assertNotBulkTarget(udid);
+		await this.run(["shutdown", udid]);
+	}
+	async erase(udid) {
+		assertNotBulkTarget(udid);
+		await this.run(["erase", udid]);
+	}
+	/** Attach the Simulator UI to whatever is booted. A `boot` alone is headless. */
+	async openApp(openPath) {
+		await this.exec(openPath, ["-a", "Simulator"], this.opts.timeoutMs);
+	}
+	async listApps(udid) {
+		assertNotBulkTarget(udid);
+		return this.runPlist(["listapps", udid]);
+	}
+	async install(udid, appPath) {
+		assertNotBulkTarget(udid);
+		assertNoShellMetachars("path", appPath);
+		await this.run([
+			"install",
+			udid,
+			appPath
+		]);
+	}
+	/**
+	* Launch, optionally replacing a running copy.
+	*
+	* Environment variables do not go on the command line: simctl reads them from
+	* its **own** environment under a `SIMCTL_CHILD_` prefix. `ExecImpl` pins a
+	* minimal environment on purpose, so a caller wanting them has to say so, and
+	* this is where that would be threaded through.
+	*/
+	async launch(udid, bundleId, opts = {}) {
+		assertNotBulkTarget(udid);
+		const flags = [
+			...opts.terminateExisting ? ["--terminate-running-process"] : [],
+			...opts.stdout ? [`--stdout=${opts.stdout}`] : [],
+			...opts.stderr ? [`--stderr=${opts.stderr}`] : []
+		];
+		return this.run([
+			"launch",
+			...flags,
+			udid,
+			bundleId,
+			...opts.args ?? []
+		]);
+	}
+	async terminate(udid, bundleId) {
+		assertNotBulkTarget(udid);
+		await this.run([
+			"terminate",
+			udid,
+			bundleId
+		]);
+	}
+	async openUrl(udid, url) {
+		assertNotBulkTarget(udid);
+		await this.run([
+			"openurl",
+			udid,
+			url
+		]);
+	}
+	/**
+	* A PNG of the screen, base64, with no WebDriverAgent involved.
+	*
+	* The documented `-` for stdout **does not work**: measured on Xcode 26.6, it
+	* writes a file literally named `-` into the current working directory and
+	* leaves stdout empty, exit code 0. So this passes a real path, like the
+	* device lane's `--json-output` does, and for the same reason uses a fresh
+	* directory per call.
+	*
+	* A successful capture also writes a `Note: No display specified…` line to
+	* stderr, so non-empty stderr is not a failure here.
+	*/
+	async screenshotPng(udid) {
+		assertNotBulkTarget(udid);
+		const dir = await mkdtemp(join(tmpdir(), "simshot-"));
+		const path = join(dir, "shot.png");
+		try {
+			await this.run([
+				"io",
+				udid,
+				"screenshot",
+				"--type=png",
+				path
+			]);
+			return (await readFile(path)).toString("base64");
+		} finally {
+			await rm(dir, {
+				recursive: true,
+				force: true
+			});
+		}
+	}
+	/**
+	* Read a `simctl ui` option.
+	*
+	* `unknown` and `unsupported` are passed through rather than normalised: they
+	* mean genuinely different things — the runtime is too old, versus it failed
+	* to read — and collapsing them throws away a distinction a caller can act on.
+	*/
+	async uiGet(udid, option) {
+		assertNotBulkTarget(udid);
+		return (await this.run([
+			"ui",
+			udid,
+			option
+		])).trim();
+	}
+	async uiSet(udid, option, value) {
+		assertNotBulkTarget(udid);
+		await this.run([
+			"ui",
+			udid,
+			option,
+			value
+		]);
+	}
+	async statusBarOverride(udid, flags) {
+		assertNotBulkTarget(udid);
+		await this.run([
+			"status_bar",
+			udid,
+			"override",
+			...flags
+		]);
+	}
+	async statusBarClear(udid) {
+		assertNotBulkTarget(udid);
+		await this.run([
+			"status_bar",
+			udid,
+			"clear"
+		]);
+	}
+	async statusBarList(udid) {
+		assertNotBulkTarget(udid);
+		return (await this.run([
+			"status_bar",
+			udid,
+			"list"
+		])).trim();
+	}
+	async locationSet(udid, latitude, longitude) {
+		assertNotBulkTarget(udid);
+		await this.run([
+			"location",
+			udid,
+			"set",
+			`${latitude},${longitude}`
+		]);
+	}
+	async locationClear(udid) {
+		assertNotBulkTarget(udid);
+		await this.run([
+			"location",
+			udid,
+			"clear"
+		]);
+	}
+	/** `grant` and `revoke` need a bundle id; `reset` does not. */
+	async privacy(udid, action, service, bundleId) {
+		assertNotBulkTarget(udid);
+		await this.run([
+			"privacy",
+			udid,
+			action,
+			service,
+			...bundleId ? [bundleId] : []
+		]);
+	}
+	/**
+	* A simulated remote push. The payload goes through a temp file rather than
+	* stdin, for the same argv-only reason as the plist lane.
+	*/
+	async push(udid, bundleId, payload) {
+		assertNotBulkTarget(udid);
+		const dir = await mkdtemp(join(tmpdir(), "simpush-"));
+		const path = join(dir, "payload.json");
+		try {
+			await writeFile(path, JSON.stringify(payload));
+			await this.run([
+				"push",
+				udid,
+				bundleId,
+				path
+			]);
+		} finally {
+			await rm(dir, {
+				recursive: true,
+				force: true
+			});
+		}
+	}
+};
+//#endregion
+//#region src/client/simulator.ts
+/** What to say when WebDriverAgent fails, on a simulator. */
+const SIMULATOR_WDA_REMEDIES = {
+	unavailable: WDA_UNAVAILABLE_REMEDY,
+	notAuthorized: `WebDriverAgent is running but is refusing to drive the UI. On a simulator there is no Enable UI Automation toggle to blame, so this is nearly always a stale runner. ${START_RUNNER_REMEDY}`,
+	noForegroundApp: "WebDriverAgent can see no foreground application on a session it has just created. Launch the app with ios_simulator_launch, or restart the runner with ios_simulator_restart_wda.",
+	noSuchElement: "Call ios_simulator_ui_tree to see what is actually on screen — the element may not have appeared yet."
+};
+var SimulatorClient = class {
+	simctl;
+	exec;
+	sipsPath;
+	plutilPath;
+	openPath;
+	execTimeoutMs;
+	opts;
+	wdaClients = /* @__PURE__ */ new Map();
+	/** `simctl list` is ~80ms and most tools want it twice; 2s collapses that. */
+	cache;
+	profiles = /* @__PURE__ */ new Map();
+	constructor(opts) {
+		this.opts = opts;
+		this.exec = opts.exec ?? createExec({
+			timeout: "Raise IOS_SIMULATOR_TIMEOUT_MS if this is a slow operation (a boot or a large `install` genuinely takes tens of seconds), or check the simulator is still booted.",
+			toolchain: "Install Xcode and run `xcode-select --install`, or point IOS_SIMULATOR_XCRUN_PATH at a different xcrun."
+		});
+		this.sipsPath = opts.sipsPath;
+		this.plutilPath = opts.plutilPath;
+		this.openPath = opts.openPath;
+		this.execTimeoutMs = opts.execTimeoutMs;
+		this.simctl = new Simctl({
+			xcrunPath: opts.xcrunPath,
+			plutilPath: opts.plutilPath,
+			timeoutMs: opts.execTimeoutMs,
+			...opts.exec ? { exec: opts.exec } : {},
+			...opts.logger ? { logger: opts.logger } : {}
+		});
+	}
+	async listSimulators(opts = {}) {
+		const cached = this.cache;
+		if (!opts.fresh && cached && Date.now() - cached.at < 2e3) return cached.simulators;
+		const [devices, runtimes, deviceTypes] = await Promise.all([
+			this.simctl.listDevices(),
+			this.simctl.listRuntimes(),
+			this.simctl.listDeviceTypes()
+		]);
+		const simulators = summarizeDevices(devices, runtimes, deviceTypes);
+		this.cache = {
+			at: Date.now(),
+			simulators
+		};
+		return simulators;
+	}
+	/**
+	* Resolve a hint to exactly one simulator, or refuse.
+	*
+	* The device server's rule — never guess between two — transfers, but
+	* "connected" has to become the right predicate. A typical machine carries
+	* dozens of simulators, most of them shut down and some of them unavailable,
+	* so the population is mostly non-candidates.
+	*
+	* Three things happen here that cannot happen further down:
+	*
+	*  - `all` and `unavailable` are refused outright. `simctl erase all` wipes
+	*    every simulator on the machine, and a hint is a string from a model.
+	*  - `booted` is resolved *here* rather than passed through. simctl's own
+	*    documentation says that with several booted it "will choose one of
+	*    them", and a coin flip that drives the wrong screen most of the time is
+	*    exactly what the refuse-to-guess rule exists to prevent.
+	*  - availability is checked before the target is returned, because `simctl
+	*    io` against an unavailable simulator aborts with an uncaught
+	*    NSInternalInconsistencyException rather than failing.
+	*
+	* State is deliberately *not* checked: `ios_simulator_list` and
+	* `ios_simulator_diagnostics` are useful against a shut-down simulator, so
+	* requiring booted is each tool's decision, via `requireBooted`.
+	*/
+	async resolveTarget(hint) {
+		const wanted = hint ?? this.opts.defaultSimulatorId;
+		const simulators = await this.listSimulators();
+		if (wanted === "all" || wanted === "unavailable") throw new SimulatorNotFoundError(`"${wanted}" is not a simulator, it is how simctl says *every* simulator.`, "Name one by UDID or by name. `simctl erase all` would wipe the machine, so this server refuses to forward it.");
+		const usable = simulators.filter((sim) => sim.available);
+		if (wanted !== void 0 && wanted !== "booted") {
+			const byUdid = simulators.filter((sim) => sim.id.toLowerCase() === wanted.toLowerCase());
+			const named = simulators.filter((sim) => sim.name === wanted);
+			const byName = named.some((sim) => sim.available) ? named.filter((sim) => sim.available) : named;
+			const matches = byUdid.length > 0 ? byUdid : byName;
+			if (matches.length === 0) throw new SimulatorNotFoundError(`No simulator matches "${wanted}".`, simulators.length === 0 ? "simctl knows about no simulators at all. Install a runtime in Xcode > Settings > Components." : `Run ios_simulator_list to see them. ${usable.length} of ${simulators.length} are available.`);
+			if (matches.length > 1) throw new SimulatorNotFoundError(`${matches.length} simulators are named "${wanted}".`, `Pass a UDID instead: ${matches.map((sim) => `${sim.name} = ${sim.id}`).join(", ")}.`);
+			return this.assertAvailable(matches[0]);
+		}
+		const booted = usable.filter((sim) => sim.state === "Booted");
+		if (booted.length === 1) return this.assertAvailable(booted[0]);
+		if (booted.length === 0) {
+			const candidates = usable.slice(0, 6).map((sim) => `${sim.name} = ${sim.id}`).join(", ");
+			throw new SimulatorNotFoundError("No simulator is booted.", usable.length === 0 ? "No simulator on this machine has an installed runtime. Install one in Xcode > Settings > Components." : `Boot one with ios_simulator_power, e.g. ${candidates}.`);
+		}
+		throw new SimulatorNotFoundError(`${booted.length} simulators are booted, so there is no obvious default.`, `Pass \`simulator\` (or set IOS_SIMULATOR_ID) to one of: ${booted.map((sim) => `${sim.name} = ${sim.id}`).join(", ")}.`);
+	}
+	assertAvailable(sim) {
+		if (!sim.available) throw new RuntimeUnavailableError(sim.name, sim.unavailableReason);
+		return sim;
+	}
+	/** Every tool that needs a running simulator calls this; the resolver does not. */
+	requireBooted(sim) {
+		if (sim.state !== "Booted") throw new SimulatorNotBootedError(sim.name, sim.id);
+		return sim;
+	}
+	/**
+	* Geometry. Cached per device *type* rather than per simulator, since that is
+	* what the profile describes and it changes only when Xcode does.
+	*/
+	async display(target, capturePng) {
+		const id = target.deviceTypeIdentifier;
+		let profile = id ? this.profiles.get(id) : void 0;
+		if (!profile) {
+			const deviceType = (await this.simctl.listDeviceTypes()).find((t) => t.identifier === id);
+			profile = deviceType ? await readScreenProfile(deviceType, {
+				plutilPath: this.plutilPath,
+				exec: this.exec,
+				timeoutMs: this.execTimeoutMs
+			}) : {};
+			if (id) this.profiles.set(id, profile);
+		}
+		const capture = capturePng ? pngDimensions(Buffer.from(capturePng, "base64")) : void 0;
+		return toDisplayInfo(profile, capture);
+	}
+	/** The capture lane that needs no runner — the whole reason this server is cheap to start. */
+	async screenshotPng(target) {
+		this.requireBooted(target);
+		return this.simctl.screenshotPng(target.id);
+	}
+	/**
+	* Where WebDriverAgent is.
+	*
+	* Unlike the device lane there is no tunnel address to derive: a simulator
+	* shares the host's network stack, so the runner's port *is* a host loopback
+	* port. That is also the trap — several booted simulators contend for the
+	* same one, and WebDriverAgent scans 8100-8199 when `USE_PORT` is unset, so a
+	* second runner comes up healthy on 8101 and a server pointed at 8100 drives
+	* the first simulator while reporting success. `ios_simulator_diagnostics`
+	* reports which simulator actually owns the port.
+	*/
+	wdaUrl() {
+		return this.opts.wdaUrl ?? `http://127.0.0.1:${this.opts.wdaPort}`;
+	}
+	get wdaPort() {
+		return this.opts.wdaPort;
+	}
+	wda(_target) {
+		const url = this.wdaUrl();
+		const existing = this.wdaClients.get(url);
+		if (existing) return existing;
+		const client = new WdaClient({
+			baseUrl: async () => url,
+			timeoutMs: this.opts.wdaTimeoutMs,
+			remedies: SIMULATOR_WDA_REMEDIES,
+			...this.opts.fetch ? { fetch: this.opts.fetch } : {},
+			...this.opts.logger ? { logger: this.opts.logger } : {}
+		});
+		this.wdaClients.set(url, client);
+		return client;
+	}
+};
+//#endregion
+//#region src/tools/util.ts
+/**
+* How the shared tools name themselves and each other in this server.
+*
+* `copy.target` is written out rather than derived: a simulator is picked by
+* UDID, by name, or by being the only booted one, and none of those is what the
+* device server's version of this sentence says. `names.listTargets` is
+* overridden for the same reason — `ios_simulator_list_devices` would be a
+* mouthful for a tool that lists simulators.
+*/
+const SIMULATOR_NAMING = {
+	prefix: "ios_simulator",
+	title: "iOS Simulator",
+	noun: "simulator",
+	envPrefix: "IOS_SIMULATOR",
+	names: { listTargets: "ios_simulator_list" },
+	copy: { target: "Which simulator: its UDID or its name as shown by ios_simulator_list. Omit it when exactly one is booted — that is the normal case, and IOS_SIMULATOR_ID pins it when it is not. Unlike simctl's own `booted`, this never picks arbitrarily between two." }
+};
+const args = createArgs(SIMULATOR_NAMING);
+const { bundleIdArg, confirmArg, detailArg, screenshotArg, settleArg, xArg, yArg } = args;
+/**
+* The schema field is `device` in every tool here, shared and local alike.
+*
+* It looks odd next to a server called "simulator" and it is still the right
+* name: `simctl`'s own interface calls a simulator a device — `simctl list
+* devices`, and `<device>` in the usage line of every subcommand — so this is
+* Apple's word for the thing, and the `ios_simulator_` prefix already says
+* which kind. Mixing `simulator` here with the shared tools' `device` would be
+* worse than either alone.
+*/
+const deviceArg = args.targetArg;
+//#endregion
+//#region src/tools/apps.ts
+const registerListAppsTool = (server, client) => {
+	server.registerTool("ios_simulator_list_apps", {
+		title: "iOS Simulator: List Apps",
+		description: "List the apps installed on a simulator, with the bundle id every other tool takes. Defaults to your own apps: a stock simulator carries about thirty, and twenty-five of them are Apple's. Each entry also carries `dataContainer` — an ordinary path on this Mac, so an app's database or logs can be read directly with no copy step.",
+		inputSchema: z.object({
+			device: deviceArg,
+			include_all: z.boolean().default(false).describe("Include Apple's built-in apps as well. Off by default; the list is long.")
+		}),
+		annotations: { readOnlyHint: true }
+	}, async ({ device, include_all }) => wrap(async () => {
+		const target = client.requireBooted(await client.resolveTarget(device));
+		const apps = await client.simctl.listApps(target.id);
+		return { apps: summarizeApps(apps, { includeAll: include_all }) };
+	}));
+};
+const registerAppTools = (server, client, launchArgs, outputDir) => {
+	server.registerTool("ios_simulator_install", {
+		title: "iOS Simulator: Install",
+		description: "Install a build. The path must be a `.app` **bundle directory** built for the simulator — not an `.ipa`, and not a device build, both of which fail with a bare \"No such file or directory\" that reads like a typo. Installing over an existing copy replaces it and keeps its data.",
+		inputSchema: z.object({
+			device: deviceArg,
+			path: z.string().describe("Absolute path to the .app bundle, e.g. ~/Library/Developer/Xcode/DerivedData/…/Build/Products/Debug-iphonesimulator/Foo.app")
+		}),
+		annotations: {
+			readOnlyHint: false,
+			destructiveHint: false,
+			idempotentHint: true
+		}
+	}, async ({ device, path }) => wrap(async () => {
+		if (!path.startsWith("/")) throw new IosError$1(`path must be absolute, got "${path}".`, { remedy: "Pass the full path to the .app bundle." });
+		const target = client.requireBooted(await client.resolveTarget(device));
+		await client.simctl.install(target.id, path);
+		return {
+			installed: path,
+			udid: target.id
+		};
+	}));
+	server.registerTool("ios_simulator_launch", {
+		title: "iOS Simulator: Launch",
+		description: "Launch an installed app. Pass `arguments` to put it into a fixture or demo mode — that is what IOS_SIMULATOR_LAUNCH_ARGS sets as the default for every launch that does not override it. Standard output and error are captured to files under the output directory, so an app that dies on launch leaves something readable behind.",
+		inputSchema: z.object({
+			device: deviceArg,
+			bundle_id: bundleIdArg,
+			arguments: z.array(z.string()).optional().describe("Launch arguments, e.g. [\"-DemoMode\", \"YES\"]. Overrides IOS_SIMULATOR_LAUNCH_ARGS rather than adding to it."),
+			terminate_first: z.boolean().default(true).describe("Replace a running copy rather than attaching to it. On by default so a launch means a fresh process and a predictable first screen.")
+		}),
+		annotations: {
+			readOnlyHint: false,
+			destructiveHint: false,
+			idempotentHint: false
+		}
+	}, async ({ device, bundle_id, arguments: args, terminate_first }) => wrap(async () => {
+		const target = client.requireBooted(await client.resolveTarget(device));
+		const effective = args ?? launchArgs;
+		const stdout = `${outputDir}/${bundle_id}.out.log`;
+		const stderr = `${outputDir}/${bundle_id}.err.log`;
+		const output = await client.simctl.launch(target.id, bundle_id, {
+			args: effective,
+			terminateExisting: terminate_first,
+			stdout,
+			stderr
+		});
+		const pid = /:\s*(\d+)\s*$/.exec(output.trim())?.[1];
+		return {
+			launched: bundle_id,
+			...pid ? { pid: Number(pid) } : {},
+			...effective.length > 0 ? { arguments: effective } : {},
+			...args === void 0 && launchArgs.length > 0 ? { argumentsFrom: "IOS_SIMULATOR_LAUNCH_ARGS" } : {},
+			logs: {
+				stdout,
+				stderr
+			}
+		};
+	}));
+	server.registerTool("ios_simulator_terminate", {
+		title: "iOS Simulator: Terminate",
+		description: "Kill a running app. The app is not uninstalled and its data is untouched — this is how you get back to a cold start without erasing anything.",
+		inputSchema: z.object({
+			device: deviceArg,
+			bundle_id: bundleIdArg
+		}),
+		annotations: {
+			readOnlyHint: false,
+			destructiveHint: false,
+			idempotentHint: true
+		}
+	}, async ({ device, bundle_id }) => wrap(async () => {
+		const target = client.requireBooted(await client.resolveTarget(device));
+		await client.simctl.terminate(target.id, bundle_id);
+		return { terminated: bundle_id };
+	}));
+	server.registerTool("ios_simulator_open_url", {
+		title: "iOS Simulator: Open URL",
+		description: "Open a URL on the simulator, which is how you exercise a deep link or a universal link without finding a way to tap one. An `https://` link opens in Safari unless the app claims it; a custom scheme goes straight to whichever app registered it.",
+		inputSchema: z.object({
+			device: deviceArg,
+			url: z.url().describe("e.g. \"myapp://garden/42\" or \"https://example.com/garden/42\".")
+		}),
+		annotations: {
+			readOnlyHint: false,
+			destructiveHint: false,
+			idempotentHint: false
+		}
+	}, async ({ device, url }) => wrap(async () => {
+		const target = client.requireBooted(await client.resolveTarget(device));
+		await client.simctl.openUrl(target.id, url);
+		return { opened: url };
+	}));
+};
+//#endregion
+//#region src/tools/diagnostics.ts
+/**
+* Which simulator owns the WebDriverAgent port.
+*
+* This check has no device-server equivalent and it is the most valuable one
+* here. A simulator shares the host's network stack, so a runner's port is a
+* *host* port, and WebDriverAgent scans 8100-8199 when `USE_PORT` is unset. Two
+* booted simulators therefore give you a second runner answering healthily on
+* 8101 while a server pointed at 8100 drives the first one and reports success
+* on every call.
+*
+* Every process inside a simulator carries `SIMULATOR_UDID` in its environment,
+* and `ps -Eww` prints it, so the port's real owner is knowable rather than
+* assumed.
+*/
+const portOwner = async (client, port) => {
+	try {
+		const { stdout: pids } = await client.exec("/usr/sbin/lsof", [
+			"-nP",
+			`-iTCP:${port}`,
+			"-sTCP:LISTEN",
+			"-t"
+		], 5e3);
+		const pid = pids.trim().split("\n")[0];
+		if (!pid) return void 0;
+		const { stdout: env } = await client.exec("/bin/ps", [
+			"-Eww",
+			"-p",
+			pid
+		], 5e3);
+		return /SIMULATOR_UDID=([0-9A-Fa-f-]{36})/.exec(env)?.[1];
+	} catch {
+		return;
+	}
+};
+/**
+* The whole point of this tool is that **it never throws**. Every other tool
+* fails when nothing is booted, the runtime is missing or the runner is not up,
+* and each of those looks much like the others from the outside. This one
+* collects all of it as data and names which half is missing.
+*/
+const diagnose = async (client, ctx, deviceHint) => {
+	const problems = [];
+	const nextSteps = [];
+	const writes = ctx.allowWrites ? "enabled" : "disabled";
+	let simulators = [];
+	try {
+		simulators = await client.listSimulators({ fresh: true });
+	} catch (err) {
+		problems.push(`Could not list simulators: ${err instanceof Error ? err.message : String(err)}`);
+		nextSteps.push("Install Xcode and its command line tools, then run `xcrun simctl list devices`.");
+		return {
+			ok: false,
+			writes,
+			simulators: [],
+			counts: {
+				total: 0,
+				booted: 0,
+				unavailable: 0
+			},
+			wda: {
+				url: client.wdaUrl(),
+				port: client.wdaPort,
+				reachable: false
+			},
+			problems,
+			nextSteps
+		};
+	}
+	const booted = simulators.filter((sim) => sim.state === "Booted");
+	const unavailable = simulators.filter((sim) => !sim.available);
+	const counts = {
+		total: simulators.length,
+		booted: booted.length,
+		unavailable: unavailable.length
+	};
+	if (simulators.length === 0) {
+		problems.push("simctl knows about no simulators at all.");
+		nextSteps.push("Install a runtime: Xcode > Settings > Components.");
+	} else if (booted.length === 0) {
+		problems.push("No simulator is booted.");
+		nextSteps.push("Boot one with ios_simulator_power {\"state\":\"booted\"} — this server never boots implicitly.");
+	}
+	let target;
+	try {
+		target = await client.resolveTarget(deviceHint);
+	} catch (err) {
+		if (booted.length > 0) {
+			problems.push(err instanceof Error ? err.message : String(err));
+			const remedy = err.remedy;
+			if (remedy) nextSteps.push(remedy);
+		}
+	}
+	let display;
+	if (target) try {
+		display = await client.display(target);
+	} catch {}
+	const wda = {
+		url: client.wdaUrl(),
+		port: client.wdaPort,
+		reachable: false
+	};
+	try {
+		wda.state = await client.wda(target ?? {
+			id: "",
+			name: ""
+		}).status();
+		wda.reachable = true;
+	} catch (err) {
+		wda.error = err instanceof Error ? err.message : String(err);
+		problems.push("WebDriverAgent is not answering, so the UI tree and the input tools will fail.");
+		nextSteps.push(`${START_RUNNER_REMEDY} Everything else — including screenshots — works without it.`);
+	}
+	if (wda.reachable) {
+		const owner = await portOwner(client, client.wdaPort);
+		if (owner) wda.boundTo = owner;
+		if (owner && target && owner.toLowerCase() !== target.id.toLowerCase()) {
+			const other = simulators.find((sim) => sim.id.toLowerCase() === owner.toLowerCase());
+			problems.push(`Port ${client.wdaPort} is owned by ${other?.name ?? owner}, not ${target.name}. Every tap and every UI tree read would go to the wrong screen.`);
+			nextSteps.push("WebDriverAgent scans 8100-8199 when USE_PORT is unset, so a second simulator's runner takes the next free port and nothing looks wrong. Give this one its own port with IOS_SIMULATOR_WDA_PORT and start its runner with a matching USE_PORT.");
+		}
+	}
+	if (unavailable.length > 0) nextSteps.push(`${unavailable.length} simulators have no installed runtime and cannot be used at all. \`xcrun simctl delete unavailable\` clears them.`);
+	return {
+		ok: problems.length === 0,
+		writes,
+		simulators: [...booted, ...target && target.state !== "Booted" ? [target] : []].map(toListRow),
+		counts,
+		...target ? { target: {
+			udid: target.id,
+			name: target.name,
+			state: target.state,
+			runtime: target.runtime
+		} } : {},
+		...display ? { display } : {},
+		wda,
+		problems,
+		nextSteps
+	};
+};
+const registerDiagnosticsTools = (server, client, ctx) => {
+	server.registerTool("ios_simulator_diagnostics", {
+		title: "iOS Simulator: Diagnostics",
+		description: "Report both lanes separately and never fail: which simulators exist and which are usable, which one this server would drive, its screen geometry, and whether WebDriverAgent is answering — including *which* simulator owns its port, which is the one way to catch a second runner quietly taking your taps. Start here when anything else misbehaves.",
+		inputSchema: z.object({ device: deviceArg }),
+		annotations: { readOnlyHint: true }
+	}, async ({ device }) => wrap(async () => diagnose(client, ctx, device)));
+	server.registerResource("diagnostics", "ios-simulator://diagnostics", {
+		title: "iOS Simulator diagnostics",
+		description: "The same report as ios_simulator_diagnostics, as a resource.",
+		mimeType: "application/json"
+	}, async (uri) => ({ contents: [{
+		uri: uri.href,
+		mimeType: "application/json",
+		text: JSON.stringify(await diagnose(client, ctx))
+	}] }));
+};
+//#endregion
+//#region src/tools/environment.ts
+/** simctl's own list, verbatim — a value it does not accept is not worth guessing at. */
+const PRIVACY_SERVICES = [
+	"all",
+	"calendar",
+	"contacts-limited",
+	"contacts",
+	"location",
+	"location-always",
+	"photos-add",
+	"photos",
+	"media-library",
+	"microphone",
+	"motion",
+	"reminders",
+	"siri"
+];
+/** APNs refuses anything larger, and it is worth saying so before the round trip. */
+const MAX_PUSH_BYTES = 4096;
+const registerEnvironmentTools = (server, client) => {
+	server.registerTool("ios_simulator_set_environment", {
+		title: "iOS Simulator: Set Environment",
+		description: "Stage the simulator before a screenshot or a test: dark mode, Dynamic Type size, increased contrast, a frozen status bar, a simulated location, and app permissions. None of this is possible on a physical device, and it is most of the reason to prefer a simulator for UI work. Every field is optional; those given are applied in order and the result reports the state afterwards. A status bar override survives a reboot, so clear it when you are done or it quietly pollutes later screenshots.",
+		inputSchema: z.object({
+			device: deviceArg,
+			appearance: z.enum(["light", "dark"]).optional().describe("Interface style."),
+			content_size: z.enum([
+				"extra-small",
+				"small",
+				"medium",
+				"large",
+				"extra-large",
+				"extra-extra-large",
+				"extra-extra-extra-large",
+				"accessibility-medium",
+				"accessibility-large",
+				"accessibility-extra-large",
+				"accessibility-extra-extra-large",
+				"accessibility-extra-extra-extra-large"
+			]).optional().describe("Dynamic Type size. The accessibility- sizes are where layouts break."),
+			increase_contrast: z.boolean().optional().describe("Increase Contrast accessibility mode."),
+			status_bar: z.object({
+				time: z.string().optional().describe("Fixed clock, e.g. \"9:41\" — what App Store screenshots use."),
+				wifi_bars: z.number().int().min(0).max(3).optional(),
+				cellular_bars: z.number().int().min(0).max(4).optional(),
+				operator_name: z.string().optional().describe("Carrier name; \"\" hides it."),
+				battery_level: z.number().int().min(0).max(100).optional(),
+				battery_state: z.enum([
+					"charging",
+					"charged",
+					"discharging"
+				]).optional()
+			}).optional().describe("Freeze the status bar. Overrides persist until cleared."),
+			clear_status_bar: z.boolean().default(false).describe("Drop every status bar override, restoring the real one."),
+			location: z.object({
+				latitude: z.number(),
+				longitude: z.number()
+			}).optional().describe("Teleport the device, for location-gated screens."),
+			clear_location: z.boolean().default(false).describe("Stop simulating a location."),
+			permission: z.object({
+				action: z.enum([
+					"grant",
+					"revoke",
+					"reset"
+				]).describe("`grant` and `revoke` answer the prompt without showing it; `reset` makes it appear again on next use."),
+				service: z.enum(PRIVACY_SERVICES),
+				bundle_id: bundleIdArg.optional().describe("Required for grant and revoke; optional for reset.")
+			}).optional().describe("Set an app permission directly. This is how you reach the denied branch of a permission check, which is otherwise a prompt nobody can tap.")
+		}),
+		annotations: {
+			readOnlyHint: false,
+			destructiveHint: false,
+			idempotentHint: true
+		}
+	}, async ({ device, appearance, content_size, increase_contrast, status_bar, clear_status_bar, location, clear_location, permission }) => wrap(async () => {
+		const target = client.requireBooted(await client.resolveTarget(device));
+		const applied = [];
+		if (appearance) {
+			await client.simctl.uiSet(target.id, "appearance", appearance);
+			applied.push(`appearance=${appearance}`);
+		}
+		if (content_size) {
+			await client.simctl.uiSet(target.id, "content_size", content_size);
+			applied.push(`content_size=${content_size}`);
+		}
+		if (increase_contrast !== void 0) {
+			await client.simctl.uiSet(target.id, "increase_contrast", increase_contrast ? "enabled" : "disabled");
+			applied.push(`increase_contrast=${increase_contrast}`);
+		}
+		if (clear_status_bar) {
+			await client.simctl.statusBarClear(target.id);
+			applied.push("status_bar cleared");
+		}
+		if (status_bar) {
+			const flags = [
+				...status_bar.time ? ["--time", status_bar.time] : [],
+				...status_bar.wifi_bars !== void 0 ? [
+					"--wifiMode",
+					"active",
+					"--wifiBars",
+					String(status_bar.wifi_bars)
+				] : [],
+				...status_bar.cellular_bars !== void 0 ? [
+					"--cellularMode",
+					"active",
+					"--cellularBars",
+					String(status_bar.cellular_bars)
+				] : [],
+				...status_bar.operator_name !== void 0 ? ["--operatorName", status_bar.operator_name] : [],
+				...status_bar.battery_level !== void 0 ? ["--batteryLevel", String(status_bar.battery_level)] : [],
+				...status_bar.battery_state ? ["--batteryState", status_bar.battery_state] : []
+			];
+			if (flags.length === 0) throw new IosError$1("`status_bar` was given with no fields to override.", { remedy: "Set at least one field, or use `clear_status_bar` to drop the overrides." });
+			await client.simctl.statusBarOverride(target.id, flags);
+			applied.push("status_bar overridden");
+		}
+		if (clear_location) {
+			await client.simctl.locationClear(target.id);
+			applied.push("location cleared");
+		}
+		if (location) {
+			await client.simctl.locationSet(target.id, location.latitude, location.longitude);
+			applied.push(`location=${location.latitude},${location.longitude}`);
+		}
+		if (permission) {
+			if (permission.action !== "reset" && !permission.bundle_id) throw new IosError$1(`\`${permission.action}\` needs a bundle_id.`, { remedy: "Pass the app's bundle id, or use `reset`, which does not need one." });
+			await client.simctl.privacy(target.id, permission.action, permission.service, permission.bundle_id);
+			applied.push(`permission ${permission.action} ${permission.service}`);
+		}
+		if (applied.length === 0) throw new IosError$1("Nothing to do — no field was given.", { remedy: "Set at least one of appearance, content_size, status_bar, location, permission." });
+		return {
+			applied,
+			state: {
+				appearance: await client.simctl.uiGet(target.id, "appearance"),
+				contentSize: await client.simctl.uiGet(target.id, "content_size"),
+				statusBar: await client.simctl.statusBarList(target.id)
+			}
+		};
+	}));
+	server.registerTool("ios_simulator_push", {
+		title: "iOS Simulator: Push",
+		description: "Deliver a push notification, with no APNs certificate and no server. The payload is a normal remote-notification body and must contain an `aps` key. Only remote pushes are simulated — not VoIP, complications or file-provider. The app must be installed; it does not have to be running.",
+		inputSchema: z.object({
+			device: deviceArg,
+			bundle_id: bundleIdArg,
+			payload: z.record(z.string(), z.unknown()).describe("The APNs payload, e.g. {\"aps\":{\"alert\":{\"title\":\"Watering due\",\"body\":\"Monstera\"},\"sound\":\"default\",\"badge\":1}}. Max 4096 bytes.")
+		}),
+		annotations: {
+			readOnlyHint: false,
+			destructiveHint: false,
+			idempotentHint: false
+		}
+	}, async ({ device, bundle_id, payload }) => wrap(async () => {
+		if (!("aps" in payload)) throw new IosError$1("A push payload must have a top-level `aps` key.", { remedy: "Wrap the notification, e.g. {\"aps\":{\"alert\":\"Hello\"}}." });
+		const bytes = Buffer.byteLength(JSON.stringify(payload));
+		if (bytes > MAX_PUSH_BYTES) throw new IosError$1(`The payload is ${bytes} bytes; APNs allows ${MAX_PUSH_BYTES}.`, { remedy: "Shorten it — this is refused here rather than by simctl, but the cap is real." });
+		const target = client.requireBooted(await client.resolveTarget(device));
+		await client.simctl.push(target.id, bundle_id, payload);
+		return {
+			pushed: bundle_id,
+			bytes
+		};
+	}));
+};
+//#endregion
+//#region src/tools/lifecycle.ts
+/** Booting is slow and visible; this is how long `power` waits to see it land. */
+const BOOT_POLL_MS = 500;
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+const registerListTool = (server, client) => {
+	server.registerTool("ios_simulator_list", {
+		title: "iOS Simulator: List",
+		description: "List the simulators on this machine, with the UDID every other tool takes. Returns all of them by default — booted and shut down, available and not — because \"why can't I use that one\" has to be answerable from this list: a simulator whose runtime is missing shows `available: false` with the reason.",
+		inputSchema: z.object({
+			booted_only: z.boolean().default(false).describe("Only simulators that are currently running."),
+			name_contains: z.string().optional().describe("Case-insensitive substring filter on the name, e.g. \"iPhone 17\".")
+		}),
+		annotations: { readOnlyHint: true }
+	}, async ({ booted_only, name_contains }) => wrap(async () => {
+		const all = await client.listSimulators({ fresh: true });
+		const needle = name_contains?.toLowerCase();
+		const matched = all.filter((sim) => (!booted_only || sim.state === "Booted") && (needle === void 0 || sim.name.toLowerCase().includes(needle)));
+		const unavailable = all.filter((sim) => !sim.available).length;
+		return {
+			simulators: matched.map(toListRow),
+			booted: all.filter((sim) => sim.state === "Booted").length,
+			total: all.length,
+			...unavailable > 0 ? {
+				unavailable,
+				note: `${unavailable} simulators have no installed runtime and cannot be used. \`xcrun simctl delete unavailable\` clears them.`
+			} : {}
+		};
+	}));
+};
+const registerLifecycleTools = (server, client) => {
+	server.registerTool("ios_simulator_power", {
+		title: "iOS Simulator: Power",
+		description: "Boot or shut down a simulator. Booting is the one thing this server will not do for you implicitly — a cold boot takes tens of seconds and puts a window on the user's screen, and it changes which simulator an unqualified call resolves to afterwards. Both directions are idempotent: booting a booted simulator succeeds.",
+		inputSchema: z.object({
+			device: deviceArg,
+			state: z.enum(["booted", "shutdown"]).describe("The state to put it in. `booted` also waits for it to actually get there."),
+			open_window: z.boolean().default(true).describe("Bring up the Simulator app so the screen is visible. A `boot` on its own is headless, which is fine for an agent and confusing for a person watching."),
+			wait_ms: z.number().int().min(0).max(3e5).default(6e4).describe("How long to wait for a boot to complete before reporting what it saw.")
+		}),
+		annotations: {
+			readOnlyHint: false,
+			destructiveHint: false,
+			idempotentHint: true
+		}
+	}, async ({ device, state, open_window, wait_ms }) => wrap(async () => {
+		const target = await client.resolveTarget(device);
+		if (state === "shutdown") {
+			if (target.state !== "Booted") return {
+				udid: target.id,
+				name: target.name,
+				state: "Shutdown",
+				alreadyThere: true
+			};
+			await client.simctl.shutdown(target.id);
+			return {
+				udid: target.id,
+				name: target.name,
+				state: "Shutdown"
+			};
+		}
+		const already = target.state === "Booted";
+		if (!already) await client.simctl.boot(target.id);
+		if (open_window) await client.simctl.openApp(client.openPath);
+		const deadline = Date.now() + wait_ms;
+		let observed = target.state;
+		while (Date.now() < deadline) {
+			observed = (await client.listSimulators({ fresh: true })).find((sim) => sim.id === target.id)?.state ?? observed;
+			if (observed === "Booted") break;
+			await sleep(BOOT_POLL_MS);
+		}
+		return {
+			udid: target.id,
+			name: target.name,
+			state: observed,
+			...already ? { alreadyThere: true } : {},
+			...observed === "Booted" ? {} : { warning: `Still ${observed} after ${wait_ms}ms. Raise wait_ms, or check Xcode.` }
+		};
+	}));
+	server.registerTool("ios_simulator_erase", {
+		title: "iOS Simulator: Erase",
+		description: "Wipe a simulator back to a factory state: installed apps, their data, the keychain and every granted permission. The only irreversible tool here, and the reason it is the only one behind `confirm`. Use it to test a genuine first launch. A booted simulator is shut down first and booted again afterwards, because simctl refuses to erase a running one.",
+		inputSchema: z.object({
+			device: deviceArg,
+			confirm: confirmArg
+		}),
+		annotations: {
+			readOnlyHint: false,
+			destructiveHint: true,
+			idempotentHint: false
+		}
+	}, async ({ device }) => wrap(async () => {
+		const target = await client.resolveTarget(device);
+		const wasBooted = target.state === "Booted";
+		if (wasBooted) await client.simctl.shutdown(target.id);
+		await client.simctl.erase(target.id);
+		if (wasBooted) await client.simctl.boot(target.id);
+		return {
+			udid: target.id,
+			name: target.name,
+			erased: true,
+			rebooted: wasBooted
+		};
+	}));
+};
+//#endregion
+//#region src/tools/runner.ts
+const defaultSpawnRunner = async (command, args, { env, logPath }) => {
+	await mkdir(dirname(logPath), { recursive: true });
+	const log = await open(logPath, "a");
+	const child = spawn(command, args, {
+		detached: true,
+		stdio: [
+			"ignore",
+			log.fd,
+			log.fd
+		],
+		env: {
+			...process.env,
+			...env
+		}
+	});
+	child.unref();
+	await log.close();
+	return child.pid;
+};
+const scriptPath = () => {
+	const here = dirname(fileURLToPath(import.meta.url));
+	for (const candidate of [join(here, "..", "scripts", "wda.sh"), join(here, "..", "..", "scripts", "wda.sh")]) return candidate;
+	throw new IosError$1("Could not find `scripts/wda.sh` beside this module.");
+};
+const registerRunnerTools = (server, client, outputDir, spawnRunner = defaultSpawnRunner) => {
+	server.registerTool("ios_simulator_restart_wda", {
+		title: "iOS Simulator: Restart WebDriverAgent",
+		description: "Start the WebDriverAgent runner, or restart it after it has died. Only the UI tree and the input tools need it — screenshots and everything simctl does keep working without it. The runner is started detached so it outlives this conversation, and its output goes to a log file rather than to you. It does not wait: give it fifteen seconds or so, then check ios_simulator_diagnostics.",
+		inputSchema: z.object({
+			device: deviceArg,
+			port: z.number().int().min(1).max(65535).optional().describe("Port to bind, passed to the runner as USE_PORT. Defaults to IOS_SIMULATOR_WDA_PORT. Two simulators need two ports: they share this Mac's loopback, and a runner with no USE_PORT scans 8100-8199 and silently takes the next free one.")
+		}),
+		annotations: {
+			readOnlyHint: false,
+			destructiveHint: false,
+			idempotentHint: false
+		}
+	}, async ({ device, port }) => wrap(async () => {
+		const target = client.requireBooted(await client.resolveTarget(device));
+		const usePort = port ?? client.wdaPort;
+		const logPath = join(outputDir, "wda.log");
+		const pid = await spawnRunner("/bin/bash", [scriptPath(), "run"], {
+			env: {
+				IOS_SIMULATOR_ID: target.id,
+				IOS_SIMULATOR_WDA_PORT: String(usePort),
+				USE_PORT: String(usePort)
+			},
+			logPath
+		});
+		if (pid === void 0) throw new IosError$1("Could not start the runner — the process had no pid.", { remedy: START_RUNNER_REMEDY });
+		return {
+			started: true,
+			pid,
+			port: usePort,
+			udid: target.id,
+			logPath,
+			note: "Give it ~15s, then check ios_simulator_diagnostics for `wda.reachable`."
+		};
+	}));
+};
+//#endregion
+//#region src/tools/index.ts
+/**
+* All capability decisions in one place, so "why can't I call that" is answered
+* by one file.
+*
+* The split is observe versus drive, exactly as in the device server. What
+* differs is the **default**: writes are on. The convention that keeps the rest
+* of the fleet read-only exists because a mutating tool acts on someone's real
+* account or someone's real phone, and a simulator is neither — it holds no
+* person's data and `ios_simulator_erase` puts it back to factory in seconds.
+* Turning writes off with IOS_SIMULATOR_ALLOW_WRITES=0 restores the device
+* server's posture, and then the driving tools are *absent* rather than
+* refused, because a refusal still lets a model try, retry and reason about a
+* way around it.
+*
+* The observe half is unusually capable here: `screenshot` goes through simctl,
+* so seeing the screen needs no WebDriverAgent and no setup of any kind. Only
+* `ui_tree` does, and that is a runtime fact reported by
+* ios_simulator_diagnostics rather than a registration decision — the runner
+* can start and stop while this server is connected.
+*/
+const registerTools = (server, client, ctx, spawnRunner) => {
+	const shared = {
+		host: client,
+		naming: SIMULATOR_NAMING,
+		maxTreeBytes: ctx.config.maxTreeBytes,
+		capHint: "raise IOS_SIMULATOR_MAX_TREE_BYTES",
+		buttons: ["home"],
+		emptyScreenshotRemedy: EMPTY_SCREENSHOT_REMEDY,
+		includeDisplayInfo: false
+	};
+	registerDiagnosticsTools(server, client, ctx);
+	registerListTool(server, client);
+	registerListAppsTool(server, client);
+	registerScreenTools(server, shared);
+	if (!ctx.allowWrites) return;
+	registerInputTools(server, shared);
+	registerLifecycleTools(server, client);
+	registerAppTools(server, client, ctx.config.launchArgs, ctx.config.outputDir);
+	registerEnvironmentTools(server, client);
+	registerRunnerTools(server, client, ctx.config.outputDir, spawnRunner);
+};
+//#endregion
+//#region src/server.ts
+const SERVER_NAME = BUILD_INFO.name;
+const SERVER_VERSION = BUILD_INFO.version;
+/**
+* A pure factory. The injectable seams — `exec`, `fetch` and `spawnRunner` —
+* are the whole reason the test suite can drive real tools through the real SDK
+* with no simulator, no Xcode, no WebDriverAgent and no process left running.
+* Nothing below `config.ts` reads `process.env`.
+*/
+const createServer = (opts) => {
+	const { config } = opts;
+	const server = new McpServer({
+		name: SERVER_NAME,
+		version: SERVER_VERSION
+	});
+	const client = new SimulatorClient({
+		xcrunPath: config.xcrunPath,
+		sipsPath: config.sipsPath,
+		plutilPath: config.plutilPath,
+		openPath: config.openPath,
+		execTimeoutMs: config.execTimeoutMs,
+		wdaTimeoutMs: config.wdaTimeoutMs,
+		wdaPort: config.wdaPort,
+		...config.wdaUrl ? { wdaUrl: config.wdaUrl } : {},
+		...config.simulatorId ? { defaultSimulatorId: config.simulatorId } : {},
+		...opts.exec ? { exec: opts.exec } : {},
+		...opts.fetch ? { fetch: opts.fetch } : {},
+		...opts.logger ? { logger: opts.logger } : {}
+	});
+	registerTools(server, client, {
+		config,
+		allowWrites: config.allowWrites
+	}, opts.spawnRunner);
+	return {
+		server,
+		client
+	};
+};
+//#endregion
+//#region src/config.ts
+/**
+* There are no credentials here, and unlike the device server there is barely
+* any setup either. Two lanes reach a simulator and both are local:
+*
+*   * `xcrun simctl` — Apple's own tool. It covers app lifecycle, the device's
+*     whole staged environment, and the screen itself: `simctl io screenshot`
+*     needs no runner at all.
+*   * WebDriverAgent — an HTTP server inside the simulator, on the *host's*
+*     loopback since a simulator shares the host network stack. Only the
+*     accessibility tree and synthetic touches go through it.
+*/
+const ConfigSchema = z.object({
+	/**
+	* UDID, name, or the literal `booted`. Left unset, a single booted
+	* simulator is used and two or more is an error that names them, rather
+	* than the coin flip simctl's own `booted` performs.
+	*/
+	simulatorId: z.string().min(1).optional(),
+	wdaUrl: z.url().optional(),
+	/**
+	* Must match the runner's `USE_PORT`. One port per simulator: they all bind
+	* the same host loopback, so two runners on 8100 is a silent wrong-target
+	* bug rather than a collision.
+	*/
+	wdaPort: z.number().int().min(1).max(65535).default(8100),
+	wdaTimeoutMs: z.number().int().min(1e3).max(6e5).default(3e4),
+	/** A cold boot or a large `install` genuinely takes tens of seconds. */
+	execTimeoutMs: z.number().int().min(1e3).max(18e5).default(12e4),
+	/**
+	* **On by default**, which is the one place this server deliberately breaks
+	* the fleet convention. What makes the device server read-only is that a
+	* phone belongs to a real person; a simulator is disposable and holds
+	* nobody's data. `ios_simulator_erase` still requires an explicit `confirm`
+	* because it is the only irreversible tool here.
+	*/
+	allowWrites: z.boolean().default(true),
+	/** Applied by `launch` when the call passes no `arguments` of its own. */
+	launchArgs: z.array(z.string()).default([]),
+	/** Saved screenshots, launch logs and the runner log. */
+	outputDir: z.string().min(1).default(join(tmpdir(), "mcp-ios-simulator")),
+	maxTreeBytes: z.number().int().min(1e3).max(5e5).default(24e3),
+	xcrunPath: z.string().min(1).default("/usr/bin/xcrun"),
+	sipsPath: z.string().min(1).default("/usr/bin/sips"),
+	/** The `listapps` plist lane, and the device-type profile read. */
+	plutilPath: z.string().min(1).default("/usr/bin/plutil"),
+	/** `simctl boot` is headless; this is what attaches a window. */
+	openPath: z.string().min(1).default("/usr/bin/open")
+}).strict().superRefine((_cfg, _ctx) => {});
+const trimmed = (value) => {
+	const t = value?.trim();
+	return t ? t : void 0;
+};
+const parseBool = (value) => {
+	const t = trimmed(value);
+	if (t === void 0) return void 0;
+	return [
+		"1",
+		"true",
+		"yes",
+		"on"
+	].includes(t.toLowerCase());
+};
+const parseIntOpt = (value) => {
+	const t = trimmed(value);
+	if (t === void 0) return void 0;
+	const n = Number(t);
+	return Number.isInteger(n) ? n : void 0;
+};
+/** Whitespace-separated, so `IOS_SIMULATOR_LAUNCH_ARGS="-DemoMode -NoCloud"` works. */
+const parseArgs = (value) => {
+	const t = trimmed(value);
+	return t === void 0 ? void 0 : t.split(/\s+/);
+};
+const defaultConfigPath = (env = process.env) => trimmed(env.IOS_SIMULATOR_CONFIG) ?? join(homedir(), ".config", "ios-simulator-mcp", "config.json");
+/**
+* `.strict()` on purpose: a typo'd `wdaPort` spelled `wda_port` must be an
+* error. Silently ignoring an unknown key looks exactly like "that setting had
+* no effect", which is the worst possible way to learn where your config came
+* from.
+*/
+const readConfigFile = (path) => {
+	let raw;
+	try {
+		raw = readFileSync(path, "utf8");
+	} catch {
+		return {};
+	}
+	return ConfigSchema.partial().strict().parse(JSON.parse(raw));
+};
+/**
+* Environment first, config file second, **per field** — not whole-source.
+* A one-off `IOS_SIMULATOR_ALLOW_WRITES=0` has to beat a file that says `true`,
+* while a file that sets `simulatorId` keeps working when the environment says
+* nothing about it. Merging field by field is the only rule that gives both.
+*/
+const loadConfig = (env = process.env, configPath = defaultConfigPath(env)) => {
+	const file = readConfigFile(configPath);
+	const pick = (fromEnv, key) => fromEnv ?? file[key];
+	return ConfigSchema.parse({
+		simulatorId: pick(trimmed(env.IOS_SIMULATOR_ID), "simulatorId"),
+		wdaUrl: pick(trimmed(env.IOS_SIMULATOR_WDA_URL), "wdaUrl"),
+		wdaPort: pick(parseIntOpt(env.IOS_SIMULATOR_WDA_PORT), "wdaPort"),
+		wdaTimeoutMs: pick(parseIntOpt(env.IOS_SIMULATOR_WDA_TIMEOUT_MS), "wdaTimeoutMs"),
+		execTimeoutMs: pick(parseIntOpt(env.IOS_SIMULATOR_TIMEOUT_MS), "execTimeoutMs"),
+		allowWrites: pick(parseBool(env.IOS_SIMULATOR_ALLOW_WRITES), "allowWrites"),
+		launchArgs: pick(parseArgs(env.IOS_SIMULATOR_LAUNCH_ARGS), "launchArgs"),
+		outputDir: pick(trimmed(env.IOS_SIMULATOR_OUTPUT_DIR), "outputDir"),
+		maxTreeBytes: pick(parseIntOpt(env.IOS_SIMULATOR_MAX_TREE_BYTES), "maxTreeBytes"),
+		xcrunPath: pick(trimmed(env.IOS_SIMULATOR_XCRUN_PATH), "xcrunPath"),
+		sipsPath: pick(trimmed(env.IOS_SIMULATOR_SIPS_PATH), "sipsPath"),
+		plutilPath: pick(trimmed(env.IOS_SIMULATOR_PLUTIL_PATH), "plutilPath"),
+		openPath: pick(trimmed(env.IOS_SIMULATOR_OPEN_PATH), "openPath")
+	});
+};
+//#endregion
+export { WritesDisabledError as A, SimulatorNotFoundError as C, WDA_UNAVAILABLE_REMEDY as D, ToolchainError as E, WdaError as O, SimulatorNotBootedError as S, TOOLCHAIN_REMEDY as T, CommandTimeoutError as _, createServer as a, RuntimeUnavailableError as b, assertNotBulkTarget as c, summarizeDevices as d, toListRow as f, CommandError as g, toDisplayInfo as h, SERVER_VERSION as i, BUILD_INFO as j, WdaUnavailableError as k, parseSimctlError as l, readScreenProfile as m, loadConfig as n, SimulatorClient as o, pngDimensions as p, SERVER_NAME as r, Simctl as s, defaultConfigPath as t, summarizeApps as u, EMPTY_SCREENSHOT_REMEDY as v, TIMEOUT_REMEDY as w, START_RUNNER_REMEDY as x, IosError$1 as y };
+
+//# sourceMappingURL=config-C1TH-p-c.js.map