stim 1.18.0 → 1.20.0

package/dist/ios-CZuv6gRv.mjs

@@ -0,0 +1,1112 @@
+import { L as deviceSlotFileKey, V as parseDeviceSlotOption, W as validateDeviceSlot } from "./config-D0LhTY3S.mjs";
+import { C as iosSigningIdentitySha1Setting, I as projectSettingsContext, L as publicUrlSetting, N as metroWarmupUrlSetting, S as iosSigningIdentitySettingError, _ as iosLanHostSetting, a as SETTING_SHAPE_REMEDY, g as deviceReclaimIdleMinutesSetting, j as metroPortSetting, tt as tunnelModeSetting, v as iosLanHostSettingError, w as iosSigningIdentitySha1SettingError, x as iosSigningIdentitySetting } from "./settings-Bbztm4oV.mjs";
+import { i as recordWorkspaceUse, w as workspaceLogsDir$1 } from "./workspace-state-CSIFuuDa.mjs";
+import { _ as stepTimer, g as stepClock, i as formatDuration, l as phaseLine } from "./command-output-BjPN99ZB.mjs";
+import { I as workspaceDevServerMode, t as NO_PROJECT_REFUSAL } from "./project-B8_duAzW.mjs";
+import { at as POOL_SETTING_REMEDY, dt as parkedMaxSetting } from "./android-BsYNR81W.mjs";
+import { At as createRunRecorder, It as statsProjectKey$1, Ot as startBuildProgress, kt as tapBuildLog, yt as NO_BUILD_PROGRESS } from "./budget-BONq9vXY.mjs";
+import { S as withNativeBuildRun, b as runCancellation, p as cancelledFailure, x as runCancellationSignal } from "./tailnet-CoJUb2tB.mjs";
+import { d as optimizationBuildProfile, l as artifactCachePolicy } from "./errors-DzkMYh8Q.mjs";
+import { o as exitAfterFlush } from "./remote-cache-Bsts6f6Y.mjs";
+import { d as simulatorRuntime, f as setRemoteLogSink, g as parseBuildMachineOption } from "./client-BLy1Pw2V.mjs";
+import { i as createIosSimSnapshot } from "./ios-CXLIUxXJ.mjs";
+import { r as DEFAULT_METRO_PORT } from "./app-install-0LgaQRT7.mjs";
+import { r as isPhysicalDeviceRequest, t as ensureDevServer } from "./native-runtime-BRmWL7ru.mjs";
+import { _ as COMPILATION_CACHE_NOT_RUN } from "./toolchain-DqyDXs30.mjs";
+import "./dev-client-ClATaJoH.mjs";
+import { f as waitFlagConflict, o as leaseExpiryText } from "./device-lease-run-CvDeHTkG.mjs";
+import { r as hostedMetroSettings } from "./metro-gateway-BBJldOdi.mjs";
+import { i as writeDevicePlacement } from "./ios-state-CjrL2qv-.mjs";
+import { a as refusePlan, i as printPlan, n as planFlagRefusal } from "./build-plan-CP0tckNU.mjs";
+import { r as siblingPlatformSlots, t as launchSlotScope } from "./slot-launch-B9hn96wd.mjs";
+import { S as ownedSessionName, n as binOnPath } from "./device-remote-Bmg42063.mjs";
+import { r as isEasBuildFailure } from "./eas-build-Dw_ec2Km.mjs";
+import { t as didSetUpDevice } from "./device-DVCwAFlX.mjs";
+import { t as unsupportedPlan } from "./project-plan-BPwbLwQu.mjs";
+import { _ as resolveIosWait, a as deviceModelRefusal, b as resolveSimulatorAppFlag, c as iosProjectPathError, d as ownedSimFailure, g as resolveIosBuildSetup, h as resolveDeviceType, i as deviceLabel, m as resolveConfiguration, n as buildLogFile, r as createIosDeviceWaitRun, u as isReleaseConfiguration, v as resolveRuntime, x as simulatorBuildArch, y as resolveSchemeSelection } from "./support-DCco5fut.mjs";
+import { a as lastBuildRecord, o as reportIosResult, s as writeLastBuild } from "./ios-project-B9drt_aY.mjs";
+import { t as acquireIosArtifact } from "./artifact-CnC0mfov.mjs";
+import { a as iosPlacementBudget, i as hostedIosSelectors, n as connectIosTarget, o as selectIosPlacement, r as hostedIosMetroNote, t as connectIosBackend } from "./remote-BU9UyhCJ.mjs";
+import { a as iosPoolCandidates, c as isWirelessIosDevice, f as resolveIosPhysicalDevice, o as iosPoolNoCandidatesRefusal, r as iosDeviceBounds } from "./ios-device-BreZOpM0.mjs";
+import { i as DEFAULT_DEPS, l as lanOriginUrlFor, s as chooseLanAddress, t as finishIosRun } from "./launch-YrbqaIFj.mjs";
+import { basename, join } from "node:path";
+import { hostedIosStatus, parseMachine } from "@stim-cli/core/state";
+import { workspaceId } from "@stim-cli/core";
+import { InvalidArgumentError } from "commander";
+import chalk from "chalk";
+//#region src/commands/ios/hosted.ts
+async function finishHostedIosRun({ target, d, artifact, root, slot, release, appMode, isExpo, metroCheck, metroPort, logsDir, fail, note, enterPhase, selectors, projectBundleId, ...report }) {
+	const bundleId = artifact.bundleId ?? (d.readBundleId(artifact.path) || projectBundleId());
+	if (!bundleId) return fail({
+		code: "STIM_INSTALL_FAILED",
+		message: "The built app has no bundle identifier."
+	});
+	const launchedAt = d.now();
+	let run;
+	try {
+		run = await d.placeHostedIos(target, {
+			root,
+			slot,
+			bundle: artifact.path,
+			handoff: artifact.handoff,
+			bundleId,
+			selectors,
+			release,
+			mode: appMode,
+			...appMode === "development" && isExpo ? { devClientScheme: d.devClientScheme(root, artifact.path) ?? void 0 } : {},
+			reserved: (placement) => d.writeHostedIos(root, slot, placement),
+			note,
+			enterPhase
+		});
+	} catch (error) {
+		return fail({
+			code: error.code ?? "STIM_HOSTING_REFUSED",
+			message: error.message,
+			remedy: error instanceof Error && "remedy" in error && typeof error.remedy === "string" ? error.remedy : `Retry stim ios --remote ${target.host.machine}, or run stim stop to reconcile any recorded placement.`
+		});
+	}
+	d.writeHostedIos(root, slot, run.placement);
+	d.writeWorkspaceLaunch(root, "ios", {
+		appId: bundleId,
+		deviceId: run.placement.session,
+		metroPort,
+		release,
+		...appMode === "process" ? { runtime: "process" } : {},
+		launchedAt: new Date(launchedAt).toISOString()
+	}, slot);
+	let launched = run.launched;
+	if (appMode === "development" && metroCheck) {
+		const evidence = await d.verifyLaunch({
+			requireBundleResponse: true,
+			platform: "ios",
+			logsDir,
+			since: launchedAt,
+			metroPort,
+			mode: workspaceDevServerMode(root, isExpo),
+			slot: launchSlotScope(root, slot),
+			platformShared: siblingPlatformSlots(root, "ios", slot).length > 0
+		});
+		if (evidence.fatal) return fail({
+			code: "STIM_LAUNCH_FAILED",
+			message: "Metro could not deliver the hosted app bundle.",
+			remedy: "Run stim logs --errors and fix the bundle error."
+		});
+		launched = evidence.verified ? true : evidence.requested ? "bundling" : "unverified";
+	}
+	if (launched === "unverified") note(`Launch on ${target.host.machine} is unverified; check the hosted app, then retry stim ios --remote ${target.host.machine}.`);
+	const cache = artifact.cache;
+	const device = run.placement.device;
+	const uploadsAbandoned = await artifact.completeUploads();
+	return {
+		facts: reportIosResult({
+			...report,
+			...appMode === "process" ? { runtimeKind: "process" } : {},
+			root,
+			slot,
+			release,
+			metroCheck,
+			metroPort,
+			logsDir,
+			device: {
+				deviceName: device.deviceType,
+				deviceType: device.deviceType,
+				runtime: device.runtime
+			},
+			udid: "",
+			host: hostedIosStatus(run.placement),
+			appPath: artifact.path,
+			bundleId,
+			installSkipped: false,
+			storeHash: cache.identity?.fingerprint ?? null,
+			storeKey: cache.identity?.key ?? null,
+			cacheHit: cache.hit,
+			missReason: cache.missReason,
+			compilationCache: cache.compilation,
+			useBuildCache: cache.readEnabled,
+			waitedForBuild: cache.waitedForBuild,
+			launchState: launched,
+			providerName: cache.providerName,
+			buildMachine: cache.buildMachine,
+			builtOn: cache.builtOn,
+			offloadedTo: cache.offloadedTo,
+			offloadFallback: cache.offloadFallback,
+			webPreviewUrl: null
+		}),
+		uploadsAbandoned
+	};
+}
+//#endregion
+//#region src/commands/ios/next-build.ts
+function runOnlyFlag(opts) {
+	if (isPhysicalDeviceRequest(opts.device)) return "--device";
+	if (opts.remote) return "--remote";
+	if (opts.wait !== void 0) return opts.wait === false ? "--no-wait" : "--wait";
+	if (opts.simulatorApp !== void 0) return "--simulator-app";
+	if (opts.metroCheck === false) return "--no-metro-check";
+	return null;
+}
+async function planIos(opts, d) {
+	const json = Boolean(opts.json);
+	const flag = runOnlyFlag(opts);
+	if (flag) return refusePlan(planFlagRefusal(flag), json);
+	const root = d.findProjectRoot(process.cwd());
+	if (!root) return refusePlan(NO_PROJECT_REFUSAL, json);
+	const selected = d.projectRegistry.selectIos(root);
+	if ("problem" in selected) return refusePlan({
+		code: "STIM_NO_PROJECT",
+		...selected.problem
+	}, json);
+	const context = projectSettingsContext(root, d);
+	const settings = d.resolveSettings(context);
+	const project = await selected.load(settings);
+	if (!project.plan) return refusePlan(unsupportedPlan("ios"), json);
+	const result = await project.plan(opts, {
+		context,
+		settings
+	});
+	if ("platform" in result) printPlan(result, json);
+	else refusePlan(result.refusal, json, result.lines);
+}
+//#endregion
+//#region src/commands/ios.ts
+function writeNote(line) {
+	console.error(line);
+}
+function writePhase(name, text) {
+	console.error(phaseLine(name, text));
+}
+function iosCommand(program) {
+	registerIos(program);
+}
+function registerIos(program, deps = {}) {
+	program.command("ios").description("Build (or restore from the fingerprint cache), install and launch this workspace's app on its owned simulator. React Native and Expo Debug runs start the dev server when it is not running.").option("--eas-profile <name>", "Download a matching EAS development build; on a miss, print the build command without running it").option("--slot <name>", "Reusable device slot within this workspace (default: default)", parseDeviceSlotOption).option("--remote-build <value>", "Build on auto, local, or one named machine; a name refuses without fallback", parseBuildMachineOption).option("--json", "Emit the facts as a single JSON line on stdout; every other line goes to stderr").option("--plan", "Predict the next build without building, booting or installing: resolve the fingerprint, check the local then remote cache, and print the expected cache result and duration. Writes no Stim state.").option("--scheme <name>", "Shared Xcode app scheme to build; overrides automatic scheme selection, not the app URL scheme").option("--no-metro-check", "Skip the \"is this workspace's dev server running?\" check: do not start it, and build anyway").option("--no-build-cache", "Build fresh, ignoring cached artifacts (local and the project's build-cache provider); the fresh build still replaces the cache entry").option("--configuration <name>", "Xcode configuration to build (e.g. Release). A non-Debug configuration embeds the JS bundle and skips Metro entirely. Overrides the ios.configuration setting. Default: Debug").option("--device-type <name>", "Simulator model to create this workspace's owned sim as, exactly as `xcrun simctl list devicetypes` names it (e.g. \"iPad Pro 13-inch (M5)\"). Overrides the ios.deviceType setting for this invocation. A model no installed runtime can create refuses with STIM_BAD_ARG and prints the models they do offer.").option("--runtime <version>", "Simulator runtime to create this workspace's owned sim on, as a version (\"18.5\") or a runtime's full name (\"iOS 18.5\"); nothing else matches. Overrides the ios.runtime setting for this invocation. An unknown version refuses with STIM_BAD_ARG and prints the installed runtimes.").option("--simulator-app <app>", "Open the owned simulator in xcode, siniulator, or stim-desktop for this run, overriding the machine iosSimulatorApp setting. Also opens an already running simulator; local simulators only.").option("--device [udid]", "Build the iphoneos slice for a connected iPhone, install it, and launch it, instead of using this workspace's owned simulator. The phone can be cabled or paired over Wi-Fi. With no UDID, the first cabled device this workspace can lease is used, waiting for one that is busy; a Wi-Fi device is used only when no cabled one is connected and ready. In Debug the app is wired to this workspace's Metro over the LAN. Stim never creates, boots, or deletes a physical device.").option("--remote <target>", "Run on eas, proxy, or an approved Mac in remote.machines; named Macs never fall back locally. auto places on an approved Mac when this Mac is full or busy. local runs here, whatever ios.remote says.", (value) => {
+		if (parseMachine(value)) return value.trim();
+		throw new InvalidArgumentError("expected eas, proxy, auto, local, or a remote Mac name");
+	}).option("--wait <seconds>", "How long to wait for another workspace to release the phone it leases, before refusing with STIM_DEVICE_BUSY (default 60, 0 refuses at once). Without --device, wait for an owned-device slot (default 600 seconds; --no-wait refuses immediately).").option("--no-wait", "Install on a phone another workspace leases instead of waiting: this run takes no lease and, when both workspaces build the same app id, the install terminates the holder's running app. Without --device, refuse a full device cap or existing slot queue immediately.").action(async (opts) => {
+		if (opts.plan) {
+			await planIos(opts, {
+				...DEFAULT_DEPS,
+				...deps
+			});
+			return;
+		}
+		const completion = await runIosOperation((deps.findProjectRoot ?? DEFAULT_DEPS.findProjectRoot)(process.cwd()), {
+			...opts,
+			waitConflict: waitFlagConflict(process.argv)
+		}, deps);
+		if (!completion) process.exit(runCancellation() ? 130 : 1);
+		else if (completion.uploadsAbandoned) exitAfterFlush(0);
+	});
+}
+function runIosOperation(root, opts = {}, deps = {}, onFailure = () => {}) {
+	const run = (progress) => runIos(root, opts, deps, progress, onFailure);
+	return root ? withNativeBuildRun(root, {
+		command: "ios",
+		platform: "ios",
+		slot: opts.slot ?? "default"
+	}, async (claim) => {
+		recordWorkspaceUse(root);
+		const progress = startBuildProgress({
+			root,
+			platform: "ios",
+			slot: opts.slot ?? "default",
+			claim,
+			note: (line) => writeNote(chalk.dim(line))
+		});
+		try {
+			return await run(progress);
+		} finally {
+			progress.clear();
+		}
+	}, { write: (line) => writeNote(chalk.dim(phaseLine("lock", line))) }) : run();
+}
+function unlessCancelled(result) {
+	if (!result.ok || !runCancellation()) return result;
+	return {
+		ok: false,
+		failure: {
+			code: "STIM_CANCELLED",
+			message: "before install"
+		},
+		compilationCache: result.artifact.cache.compilation
+	};
+}
+function iosProjectTargetRefusal(project, { physical, easProfile, placement }) {
+	const target = physical ? "physical" : placement ? placement.machine ? "hosted" : placement.backend ? "remote" : "simulator" : null;
+	if (target && !project.targets.includes(target)) return {
+		code: "STIM_BAD_ARG",
+		message: `This project integration does not support the ${target} iOS target.`,
+		remedy: "Use a local iOS simulator for this integration."
+	};
+	if (easProfile !== void 0 && !project.eas) return {
+		code: "STIM_BAD_ARG",
+		message: "This project integration does not support EAS builds.",
+		remedy: "Use its local iOS build recipe."
+	};
+	return null;
+}
+function iosArtifactTargetInputs({ udid, physical, remote, hosted, simulatorArch, lanAddress, metroPort, settings }) {
+	return {
+		target: {
+			udid,
+			destination: remote || hosted ? "generic/platform=iOS Simulator" : null,
+			sdk: physical ? "iphoneos" : "iphonesimulator",
+			arch: remote || hosted ? simulatorArch : null,
+			keyArch: simulatorArch,
+			offloadRuntime: () => hosted?.choice.runtimeId ?? (remote ? null : simulatorRuntime(udid)),
+			hostedArchitecture: hosted?.choice.architecture,
+			offloadRefusal: physical ? "device builds build here" : remote ? "--remote builds build here" : null
+		},
+		device: physical ? {
+			udid,
+			lanAddress,
+			metroPort,
+			signingName: iosSigningIdentitySetting(settings),
+			signingSha1: iosSigningIdentitySha1Setting(settings)
+		} : null
+	};
+}
+function iosSlotLogFile(root, slot) {
+	return slot === "default" ? buildLogFile(root) : join(workspaceLogsDir$1(root), `build-${deviceSlotFileKey("ios", slot)}.ndjson`);
+}
+function iosSlotDeps(d, slot) {
+	if (slot !== "default") {
+		const base = d;
+		d = {
+			...base,
+			ensureOwnedDevice: (args) => base.ensureOwnedDevice({
+				...args,
+				slot
+			}),
+			checkDeviceCapacity: (args) => base.checkDeviceCapacity({
+				...args,
+				slot
+			}),
+			selectFromPool: (args) => base.selectFromPool({
+				...args,
+				slot
+			}),
+			acquireRunLease: (args) => base.acquireRunLease({
+				...args,
+				slot
+			}),
+			runLease: (args) => base.runLease({
+				...args,
+				slot
+			}),
+			replaceCollector: (args) => base.replaceCollector({
+				...args,
+				slot
+			}),
+			stopPreviousCollector: (args) => base.stopPreviousCollector({
+				...args,
+				slot
+			}),
+			clearIosAdoptionPending: (root) => base.clearIosAdoptionPending(root, slot),
+			writeWorkspaceLaunch: (root, platform, record) => base.writeWorkspaceLaunch(root, platform, record, slot),
+			createWriter: (file, options) => base.createWriter(file, {
+				...options,
+				fields: { slot }
+			})
+		};
+	}
+	return d;
+}
+async function runIos(projectRoot, opts = {}, overrides = {}, progress = NO_BUILD_PROGRESS, onFailure) {
+	const slot = validateDeviceSlot(opts.slot);
+	let d = iosSlotDeps({
+		...DEFAULT_DEPS,
+		...overrides
+	}, slot);
+	const json = Boolean(opts.json);
+	const metroCheck = opts.metroCheck !== false;
+	const phase = writePhase;
+	const note = writeNote;
+	const started = d.now();
+	const startedAt = new Date(started).toISOString();
+	const elapsed = () => d.now() - started;
+	const refuseProject = ({ message, remedy }) => {
+		note(chalk.red(phaseLine("error", message)));
+		note(chalk.dim(phaseLine("remedy", remedy)));
+		note(chalk.red(phaseLine("failed", "STIM_NO_PROJECT")));
+		if (json) console.log(JSON.stringify({
+			code: "STIM_NO_PROJECT",
+			message,
+			remedy
+		}));
+		onFailure({
+			code: "STIM_NO_PROJECT",
+			message,
+			remedy
+		});
+		return null;
+	};
+	if (!projectRoot) return refuseProject(NO_PROJECT_REFUSAL);
+	const root = projectRoot;
+	const selectedProject = d.projectRegistry.selectIos(root);
+	if ("problem" in selectedProject) return refuseProject(selectedProject.problem);
+	try {
+		await d.ensureWorkspaceStorage(root, { note });
+	} catch (error) {
+		const code = error?.code || "STIM_WORKSPACE_STATE";
+		const message = `Could not prepare this workspace's Stim state: ${error?.message || error}`;
+		note(chalk.red(`${code}: ${message}`));
+		note(chalk.dim("Check that STIM_HOME is writable and has free space. An EPERM on a directory you can write is a sandbox: allow writes to STIM_HOME, or run Stim with the sandbox disabled (`stim guide errors sandbox`)."));
+		if (json) console.log(JSON.stringify({
+			code,
+			message,
+			remedy: "Check that STIM_HOME is writable and has free space."
+		}));
+		onFailure({
+			code,
+			message,
+			remedy: "Check that STIM_HOME is writable and has free space."
+		});
+		return null;
+	}
+	const logsDir = workspaceLogsDir$1(root);
+	const logFile = iosSlotLogFile(root, slot);
+	let writer = null;
+	const logWriter = () => writer ||= tapBuildLog(d.createWriter(logFile, {
+		truncate: true,
+		fields: {
+			platform: "ios",
+			slot
+		}
+	}), progress);
+	setRemoteLogSink((record) => logWriter().write(record));
+	let leaseHandle = null;
+	let stopLeaseSignals = null;
+	const releaseLease = () => {
+		const held = leaseHandle;
+		const stopSignals = stopLeaseSignals;
+		leaseHandle = null;
+		stopLeaseSignals = null;
+		stopSignals?.();
+		try {
+			held?.release();
+		} catch (e) {
+			note(chalk.dim(`Could not release this run's device lease: ${e?.message || e}`));
+		}
+	};
+	const stats = createRunRecorder({
+		platform: "ios",
+		write: (statsRun, at) => d.recordStats(statsRun, at),
+		now: () => d.now(),
+		note: (line) => note(chalk.dim(line)),
+		phases: () => progress.durations(),
+		deviceSetup: () => progress.deviceSetupKnown()
+	});
+	const deviceWaitRun = createIosDeviceWaitRun(stats, progress, runCancellationSignal());
+	const recordRun = deviceWaitRun.record;
+	let compilationCache = COMPILATION_CACHE_NOT_RUN;
+	let reclaimed = [];
+	let buildMachine = "auto";
+	let devicePlacement;
+	let builtConfiguration = null;
+	const fail = ({ code, message, remedy = null, lines = [], logPath = null, build = null, lease, setup = false }) => {
+		({code, message, remedy, lines} = cancelledFailure("ios", {
+			code,
+			message
+		}) ?? {
+			code,
+			message,
+			remedy,
+			lines
+		});
+		releaseLease();
+		if (message) note(chalk.red(phaseLine("error", message)));
+		for (const line of lines) note(chalk.dim(phaseLine("", line)));
+		if (remedy) note(chalk.dim(phaseLine("remedy", remedy)));
+		if (logPath) note(chalk.dim(phaseLine("log", logPath)));
+		if (build) writeLastBuild(root, lastBuildRecord({
+			devicePlacement,
+			buildMachine,
+			...build,
+			configuration: builtConfiguration,
+			startedAt,
+			status: "failed",
+			errorCode: code,
+			durationMs: elapsed()
+		}));
+		note(chalk.red(phaseLine("failed", code)));
+		if (!setup) recordRun({
+			failed: true,
+			durationMs: elapsed()
+		});
+		if (json) console.log(JSON.stringify({
+			code,
+			message: message ?? null,
+			remedy: remedy ?? null,
+			...devicePlacement ? { devicePlacement } : {},
+			...compilationCache.status === "not-run" ? {} : { compilationCache },
+			...lease === void 0 ? {} : { lease },
+			...reclaimed.length ? { reclaimed } : {}
+		}));
+		writer?.close?.();
+		onFailure({
+			code,
+			message,
+			remedy,
+			lines,
+			logPath,
+			build,
+			lease,
+			setup
+		});
+		return null;
+	};
+	const settingsContext = projectSettingsContext(root, d);
+	const projectKey = statsProjectKey$1({
+		root,
+		commonDir: settingsContext.gitCommonDir,
+		repoRoot: settingsContext.repoRoot
+	});
+	stats.setProject(projectKey);
+	progress.estimate(projectKey);
+	let estimatesRead = null;
+	const estimates = () => estimatesRead ??= d.readEstimates({
+		projectKey,
+		platform: "ios"
+	});
+	const settings = d.resolveSettings(settingsContext);
+	const setup = resolveIosBuildSetup(opts.remoteBuild, settings, (label, message) => note(phaseLine(label, chalk.yellow(message))));
+	if (!setup.ok) return fail(setup.failure);
+	buildMachine = setup.buildMachine;
+	const { optimizations } = setup;
+	const buildProfile = optimizationBuildProfile("ios", optimizations);
+	const cacheProviderConfig = d.resolveCacheProviderConfig(settingsContext);
+	const poolError = parkedMaxSetting("ios").error;
+	if (poolError) return fail({
+		code: "STIM_BAD_ARG",
+		message: poolError,
+		remedy: POOL_SETTING_REMEDY
+	});
+	for (const settingError of [
+		iosSigningIdentitySettingError(settings),
+		iosSigningIdentitySha1SettingError(settings),
+		iosLanHostSettingError(settings),
+		iosProjectPathError(settings, root, () => d.detectIsExpo(root))
+	]) if (settingError) return fail({
+		code: "STIM_BAD_ARG",
+		message: settingError,
+		remedy: SETTING_SHAPE_REMEDY
+	});
+	const integration = await selectedProject.load(settings);
+	const configuration = opts.easProfile !== void 0 ? null : resolveConfiguration(opts.configuration, settings);
+	builtConfiguration = configuration ?? "Debug";
+	const buildScheme = resolveSchemeSelection(opts, settings);
+	const release = isReleaseConfiguration(configuration);
+	const appMode = {
+		metro: "development",
+		process: "process",
+		"embedded-js": "release"
+	}[integration.runtimeKind(configuration)];
+	const cachePolicy = artifactCachePolicy(optimizations, opts.buildCache !== false, integration.runtimeKind(configuration) === "embedded-js");
+	const deviceType = resolveDeviceType(opts.deviceType, settings);
+	const runtime = resolveRuntime(opts.runtime, settings);
+	const deviceFlag = opts.device;
+	const physical = isPhysicalDeviceRequest(deviceFlag);
+	if (physical && deviceFlag === "") return fail({
+		code: "STIM_BAD_ARG",
+		message: "--device was given an empty UDID.",
+		remedy: "Pass `--device` on its own to take the first connected device this workspace can lease, or `--device <udid>` to name one."
+	});
+	if (physical && opts.remote) return fail({
+		code: "STIM_BAD_ARG",
+		message: "--device builds for a phone connected to this machine, and --remote installs on a remote one.",
+		remedy: "Pass only one of --device and --remote."
+	});
+	const wait = resolveIosWait(opts, physical);
+	if ("failure" in wait) return fail(wait.failure);
+	const { waitSeconds, noWait, deviceSlotWaitMs, checkCapacity } = wait;
+	const deviceSlotWait = {
+		automatic: false,
+		waitMs: deviceSlotWaitMs,
+		displayName: basename(root),
+		reclaimIdleMinutes: deviceReclaimIdleMinutesSetting(settings),
+		...deviceWaitRun.policy,
+		onWait: (ms) => {
+			deviceWaitRun.policy.onWait?.(ms);
+			if (devicePlacement?.decision === "local" && ms > 0) devicePlacement.decision = "waited-locally";
+		}
+	};
+	const isExpo = integration.isExpo;
+	const schemeRefusal = integration.schemeProblem(buildScheme, configuration);
+	if (schemeRefusal) return fail(schemeRefusal);
+	const capabilityRefusal = iosProjectTargetRefusal(integration, {
+		physical,
+		easProfile: opts.easProfile
+	});
+	if (capabilityRefusal) return fail(capabilityRefusal);
+	const remoteSelection = await selectIosPlacement({
+		root,
+		slot,
+		opts,
+		settings,
+		physical,
+		release,
+		appMode,
+		supportsRemote: integration.targets.includes("remote"),
+		metroCheck,
+		d,
+		deviceType,
+		runtime,
+		validateSelectors: () => deviceModelRefusal({
+			slot,
+			deviceTypeFlag: opts.deviceType,
+			runtimeFlag: opts.runtime,
+			deviceType,
+			runtime,
+			physical,
+			remoteBackend: null,
+			deviceTypeOrigin: d.settingOriginScope(d.settingsLayers(settingsContext), "ios.deviceType"),
+			runtimeOrigin: d.settingOriginScope(d.settingsLayers(settingsContext), "ios.runtime"),
+			listRuntimes: d.listIosRuntimes
+		}),
+		noWait: deviceSlotWaitMs === 0,
+		note,
+		phase,
+		log: (entry) => logWriter().write(entry)
+	});
+	if ("failure" in remoteSelection) return fail(remoteSelection.failure);
+	deviceSlotWait.automatic = Boolean(remoteSelection.auto);
+	const targetRefusal = iosProjectTargetRefusal(integration, {
+		physical,
+		placement: remoteSelection
+	});
+	if (targetRefusal) return fail(targetRefusal);
+	devicePlacement = remoteSelection.devicePlacement;
+	writeDevicePlacement(root, slot, "ios", devicePlacement);
+	const { machine: hostedMachine, backend: remoteBackend } = remoteSelection;
+	const viewer = resolveSimulatorAppFlag(opts.simulatorApp, physical, hostedMachine ?? remoteBackend, Boolean(remoteSelection.auto));
+	if ("refusal" in viewer) return fail(viewer.refusal);
+	const { simulatorApp } = viewer;
+	const settingsLayersForOrigin = d.settingsLayers(settingsContext);
+	const modelRefusal = deviceModelRefusal({
+		slot,
+		deviceTypeFlag: opts.deviceType,
+		runtimeFlag: opts.runtime,
+		deviceType,
+		runtime,
+		deviceTypeOrigin: d.settingOriginScope(settingsLayersForOrigin, "ios.deviceType"),
+		runtimeOrigin: d.settingOriginScope(settingsLayersForOrigin, "ios.runtime"),
+		physical,
+		remoteBackend,
+		hosted: Boolean(hostedMachine),
+		listRuntimes: d.listIosRuntimes
+	});
+	if (modelRefusal) return fail(modelRefusal);
+	const selectors = hostedIosSelectors(deviceType, runtime);
+	const connected = await connectIosTarget(remoteSelection, selectors, d, appMode);
+	if ("failure" in connected) return fail(connected.failure);
+	const hostedTarget = connected.target;
+	try {
+		const simSnapshot = createIosSimSnapshot();
+		const budget = await iosPlacementBudget(d, root, note, Boolean(hostedTarget), remoteSelection.budget, simSnapshot);
+		reclaimed = budget.reclaimed;
+		if (budget.refusal) return fail(budget.refusal);
+		const backendConnection = await connectIosBackend(root, remoteBackend, opts.deviceType, d);
+		if ("failure" in backendConnection) return fail(backendConnection.failure);
+		const remoteDevice = backendConnection.remote;
+		const remoteArch = hostedTarget ? hostedTarget.choice.architecture : backendConnection.arch;
+		if (remoteDevice) d = {
+			...d,
+			checkDeviceCapacity: remoteDevice.checkDeviceCapacity,
+			ensureOwnedDevice: remoteDevice.ensureOwnedDevice,
+			ensureBooted: remoteDevice.ensureBooted,
+			installIosApp: remoteDevice.installIosApp,
+			launchIosApp: remoteDevice.launchIosApp
+		};
+		const easBuild = await d.resolveEasDevelopmentBuild({
+			root,
+			platform: "ios",
+			profile: opts.easProfile,
+			note,
+			isExpo,
+			physical,
+			selectors: [opts.scheme, opts.configuration],
+			buildCache: opts.buildCache
+		});
+		if (isEasBuildFailure(easBuild)) return fail(easBuild);
+		const registerProject = () => d.upsertProject(root, {
+			bundleId: integration.bundleId() ?? void 0,
+			isExpo
+		});
+		if (remoteBackend !== "eas") registerProject();
+		const proj = d.getProject(root);
+		const limits = d.getConcurrencyLimits();
+		let physicalDevice = null;
+		let wireless = false;
+		if (physical && typeof deviceFlag !== "string") {
+			const pooled = await d.selectFromPool({
+				root,
+				platform: "ios",
+				idLabel: "udid",
+				list: () => iosPoolCandidates(d.listIosDevices()).map((entry) => ({
+					id: entry.udid,
+					name: entry.name,
+					fallback: isWirelessIosDevice(entry)
+				})),
+				noCandidates: () => {
+					const resolved = iosPoolNoCandidatesRefusal(d.listIosDevices());
+					return {
+						message: resolved.error,
+						remedy: resolved.remedy
+					};
+				},
+				waitSeconds,
+				noWait,
+				now: d.now,
+				warn: (line) => note(chalk.yellow(phaseLine("lease", line)))
+			});
+			if (pooled.status === "refused") return fail({
+				code: pooled.refusal.code,
+				message: pooled.refusal.message,
+				remedy: pooled.refusal.remedy,
+				...pooled.refusal.lease === null ? {} : { lease: pooled.refusal.lease }
+			});
+			physicalDevice = {
+				udid: pooled.candidate.id,
+				name: pooled.candidate.name ?? pooled.candidate.id
+			};
+			wireless = pooled.candidate.fallback === true;
+		} else if (physical) {
+			const resolved = resolveIosPhysicalDevice(typeof deviceFlag === "string" ? deviceFlag : null, d.listIosDevices());
+			if (!resolved.udid) return fail({
+				code: "STIM_NO_DEVICE",
+				message: resolved.error,
+				remedy: resolved.remedy
+			});
+			physicalDevice = {
+				udid: resolved.udid,
+				name: resolved.name ?? resolved.udid
+			};
+			wireless = resolved.wireless === true;
+		}
+		if (checkCapacity && !hostedTarget) {
+			const capacity = d.checkDeviceCapacity({
+				platform: "ios",
+				project: proj,
+				max: limits.maxDevices,
+				sims: () => simSnapshot.read().filter((sim) => sim.available)
+			});
+			if (capacity) {
+				if (capacity.code === "STIM_AT_CAPACITY") d.recordCapacityRefusal({
+					platform: "ios",
+					max: limits.maxDevices,
+					workspace: workspaceId(root)
+				}, d.now());
+				return fail(capacity);
+			}
+		}
+		let metroPort = proj?.metroPort ?? null;
+		let lanAddress = null;
+		let lanOriginUrl = null;
+		let devServer = null;
+		const appRuntime = composeRuntime();
+		const preparation = await appRuntime.prepare();
+		if (!preparation.ok) return fail(preparation.error);
+		const runtimePreparation = preparation.prepared;
+		metroPort = runtimePreparation.metroPort;
+		let device;
+		if (physicalDevice) device = {
+			deviceUdid: physicalDevice.udid,
+			deviceName: physicalDevice.name,
+			owned: false
+		};
+		else if (hostedTarget) device = {
+			owned: false,
+			deviceName: hostedTarget.choice.deviceType,
+			runtime: hostedTarget.choice.runtime
+		};
+		else {
+			const prepare = stepClock(d.now);
+			try {
+				device = await d.ensureOwnedDevice({
+					platform: "ios",
+					project: proj,
+					projectPath: root,
+					settingsRoot: root,
+					settings,
+					flags: {
+						deviceSlotWait,
+						deviceType,
+						runtime,
+						runtimeFlag: resolveRuntime(opts.runtime, null),
+						simulatorApp
+					},
+					note,
+					out: note,
+					simSnapshot
+				});
+			} catch (e) {
+				return fail(ownedSimFailure(e));
+			}
+			deviceWaitRun.booting(device.booting);
+			progress.deviceSetup(didSetUpDevice(device, Boolean(remoteDevice)));
+			const prepareMs = prepare();
+			if (device.created || prepareMs >= 2e3) phase("device", `${deviceLabel(device, device.deviceUdid)} ${device.created ? "created" : "prepared"} (${formatDuration(prepareMs)})`);
+		}
+		let bootDuration = "";
+		let bootPending = false;
+		let bootPromise;
+		let udid = "";
+		function composeRuntime() {
+			return d.runtimePlan ?? integration.runtime({
+				configuration,
+				prepareMetro,
+				prepareEmbedded: async () => {
+					phase("metro", `skipped (${configuration}: the JS bundle is embedded, no dev server is used)`);
+					hostedIosMetroNote(Boolean(hostedTarget), settings, note, opts.simulatorApp);
+					return {
+						ok: true,
+						prepared: { metroPort: null }
+					};
+				}
+			});
+		}
+		async function prepareMetro() {
+			if (metroCheck) {
+				const gate = await ensureDevServer({
+					root,
+					port: metroPort,
+					settings: hostedMetroSettings(settings, Boolean(hostedTarget)),
+					settingsContext,
+					remote: Boolean(remoteDevice),
+					note,
+					resolve: d.resolveProjectMetro,
+					start: d.startDevServer,
+					readState: d.readWorkspaceState
+				});
+				reclaimed = [...reclaimed, ...gate.reclaimed];
+				if (!gate.ok) return {
+					ok: false,
+					error: {
+						code: gate.code,
+						message: gate.message,
+						remedy: gate.remedy,
+						lines: gate.lines
+					}
+				};
+				metroPort = gate.port;
+				devServer = gate.devServer;
+			} else {
+				const pin = metroPortSetting(settings);
+				if (pin.error) return {
+					ok: false,
+					error: {
+						code: "STIM_BAD_ARG",
+						message: pin.error,
+						remedy: SETTING_SHAPE_REMEDY
+					}
+				};
+				if (pin.port === null && !metroPort) note(chalk.yellow(`No Metro port is reserved for this workspace; wiring the app to ${DEFAULT_METRO_PORT}.`));
+				metroPort = pin.port ?? metroPort ?? 8081;
+			}
+			hostedIosMetroNote(Boolean(hostedTarget), settings, note, opts.simulatorApp);
+			if (physical && metroPort !== null) {
+				const error = await resolveLanOrigin();
+				if (error) return {
+					ok: false,
+					error
+				};
+			}
+			if (remoteDevice && metroPort !== null) {
+				const reachable = await d.ensureMetroReachable({
+					ctx: remoteDevice.ctx,
+					metroPort,
+					isExpo,
+					tunnelMode: tunnelModeSetting(settings) ?? void 0,
+					publicUrl: publicUrlSetting(settings),
+					available: d.detectProviders(binOnPath, tunnelModeSetting(settings) ?? "auto")
+				});
+				if ("failed" in reachable) return {
+					ok: false,
+					error: {
+						code: reachable.code ?? "STIM_NO_REMOTE_SESSION",
+						message: reachable.failed,
+						remedy: reachable.remedy
+					}
+				};
+			}
+			if (metroCheck && optimizations.metroWarmup) d.warmMetro({
+				port: metroPort,
+				platform: "ios",
+				isExpo,
+				appId: proj?.bundleId,
+				bundleUrl: metroWarmupUrlSetting(settings, "ios")
+			});
+			return {
+				ok: true,
+				prepared: { metroPort }
+			};
+		}
+		async function resolveLanOrigin() {
+			const port = metroPort;
+			const pinned = iosLanHostSetting(settings);
+			const candidates = d.hostLanCandidates();
+			const chosen = chooseLanAddress({
+				pinned,
+				candidates
+			});
+			if (!chosen) return {
+				code: "STIM_NO_LAN_ADDRESS",
+				message: "A Debug run on a phone needs an address the phone can reach, and this Mac has no non-internal IPv4 interface.",
+				remedy: "The phone reaches Metro over the network you share, because USB carries no reverse forward. Join a Wi-Fi or Ethernet network, or connect this Mac by cable, then run the command again."
+			};
+			lanAddress = chosen.address;
+			lanOriginUrl = lanOriginUrlFor(chosen.address, port);
+			const source = chosen.pinned ? "ios.lanHost" : `${chosen.interfaceName ?? "interface"}${chosen.candidates > 1 ? ` of ${chosen.candidates} candidates` : ""}`;
+			phase("lan", `${lanOriginUrl} (${source})`);
+			if (publicUrlSetting(settings) || tunnelModeSetting(settings)) note(chalk.dim(phaseLine("lan", "metro.publicUrl and metro.tunnel are ignored on --device: neither channel to a phone carries a URL, only a host and a port. They still apply to --remote.")));
+			if (!metroCheck) return null;
+			const reachable = await d.ensureLanReachable({
+				origin: lanOriginUrl,
+				metroPort: port,
+				root,
+				isExpo,
+				logsDir
+			});
+			if ("failed" in reachable) return {
+				code: "STIM_LAN_METRO_UNREACHABLE",
+				message: reachable.failed,
+				remedy: reachable.remedy
+			};
+			phase("lan", `gated: ${lanOriginUrl} answered as this workspace's Metro`);
+			return null;
+		}
+		let artifact = null;
+		try {
+			const boot = () => physicalDevice ? Promise.resolve({
+				ok: true,
+				udid: physicalDevice.udid
+			}) : Promise.resolve(d.ensureBooted({
+				platform: "ios",
+				device,
+				projectPath: root,
+				deviceSlotWait,
+				simulatorApp,
+				out: note
+			})).catch((e) => ({
+				ok: false,
+				reason: String(e?.message || e)
+			}));
+			const startBoot = () => {
+				const bootTimer = stepTimer(d.now);
+				bootPending = remoteDevice?.ctx.backend !== "eas";
+				bootPromise = (remoteDevice?.ctx.backend === "eas" ? d.ensureRemoteBootOwned({
+					root,
+					platform: "ios",
+					sessionName: ownedSessionName(remoteDevice.ctx.label),
+					startedAt: new Date(d.now()).toISOString(),
+					deviceType: remoteDevice.ctx.deviceType ?? null,
+					boot,
+					createdSessionId: remoteDevice.createdSessionId,
+					abandonCreatedSession: remoteDevice.abandonCreatedSession,
+					webPreviewUrl: remoteDevice.webPreviewUrl,
+					writeState: d.writeWorkspaceState,
+					register: registerProject,
+					notice: (line) => note(chalk.dim(phaseLine("lock", line)))
+				}) : boot()).then((result) => {
+					bootDuration = bootTimer();
+					bootPending = false;
+					return result;
+				});
+				deviceWaitRun.booting({ done: bootPromise });
+				return bootPromise.then((result) => result?.udid ?? "");
+			};
+			const localBoot = remoteDevice || hostedTarget ? null : startBoot();
+			udid = device.deviceUdid ?? await localBoot ?? "";
+			const simulatorArch = simulatorBuildArch({
+				physical,
+				remoteArch,
+				hostArch: d.hostSimulatorArch(),
+				configuration
+			});
+			const acquiredArtifact = unlessCancelled(await acquireIosArtifact({
+				root,
+				logFile,
+				configuration,
+				buildMachine,
+				physical,
+				recipe: integration.artifact({
+					root,
+					logFile,
+					configuration,
+					buildScheme,
+					buildProfile,
+					...iosArtifactTargetInputs({
+						udid,
+						physical,
+						remote: Boolean(remoteDevice),
+						hosted: hostedTarget,
+						simulatorArch,
+						lanAddress,
+						metroPort,
+						settings
+					}),
+					optimizations: optimizations.ios,
+					easProfile: opts.easProfile,
+					cache: cachePolicy,
+					phase,
+					note,
+					logWriter,
+					estimates,
+					step: progress.step,
+					setPodsMs: (ms) => stats.setPodsMs(ms)
+				}),
+				cache: {
+					policy: cachePolicy,
+					providerConfig: cacheProviderConfig,
+					disabledByFlag: opts.buildCache === false
+				},
+				easBuild,
+				maxBuilds: limits.maxBuilds,
+				progress: {
+					phase,
+					note,
+					logWriter,
+					stats,
+					step: progress.step,
+					miss: progress.miss,
+					hit: progress.hit,
+					place: progress.place,
+					waitingOn: progress.waitingOn,
+					waitingFor: progress.waitingFor
+				}
+			}, d));
+			if (!acquiredArtifact.ok) {
+				compilationCache = acquiredArtifact.compilationCache;
+				return fail(acquiredArtifact.failure);
+			}
+			artifact = acquiredArtifact.artifact;
+			compilationCache = artifact.cache.compilation;
+			if (hostedTarget) return await finishHostedIosRun({
+				target: hostedTarget,
+				projectBundleId: integration.bundleId,
+				root,
+				slot,
+				d,
+				artifact,
+				configuration,
+				buildScheme,
+				release,
+				appMode,
+				isExpo,
+				metroCheck,
+				metroPort,
+				logsDir,
+				json,
+				elapsed,
+				startedAt,
+				closeWriter: () => writer?.close(),
+				devicePlacement,
+				recordRun,
+				reclaimed,
+				devServer,
+				fail,
+				note,
+				enterPhase: progress.step,
+				selectors
+			});
+			if (!localBoot) {
+				progress.step("device");
+				udid = await startBoot();
+			}
+			if (physicalDevice) {
+				progress.step("device");
+				const acquired = await d.acquireRunLease({
+					root,
+					platform: "ios",
+					id: physicalDevice.udid,
+					deviceName: physicalDevice.name,
+					idLabel: "udid",
+					waitSeconds,
+					noWait,
+					installBoundMs: iosDeviceBounds(wireless).installMs,
+					appId: artifact.bundleId ?? proj?.bundleId ?? null,
+					holderAppId: (holder) => d.getProject(holder)?.bundleId ?? null,
+					now: d.now,
+					warn: (line) => note(chalk.yellow(phaseLine("lease", line)))
+				});
+				if (acquired.status === "refused") return fail({
+					code: acquired.refusal.code,
+					message: acquired.refusal.message,
+					remedy: acquired.refusal.remedy,
+					lease: acquired.refusal.lease
+				});
+				leaseHandle = d.runLease({
+					root,
+					platform: "ios",
+					kind: acquired.status === "leased" ? acquired.kind : null,
+					expiresAt: acquired.status === "leased" ? acquired.expiresAt : null
+				});
+				if (acquired.status === "leased") {
+					stopLeaseSignals = d.releaseLeaseOnSignal(releaseLease);
+					phase("lease", `${acquired.kind} lease on ${physicalDevice.udid} until ${leaseExpiryText(acquired.expiresAt, d.now())}`);
+				}
+			}
+			try {
+				return await finishIosRun({
+					projectBundleId: integration.bundleId,
+					runtime: appRuntime,
+					runtimePreparation,
+					slot,
+					d,
+					root,
+					json,
+					release,
+					configuration,
+					buildScheme,
+					isExpo,
+					metroCheck,
+					metroPort,
+					logsDir,
+					logFile,
+					device,
+					udid,
+					physical,
+					wireless,
+					lanAddress,
+					lanOriginUrl,
+					remoteDevice,
+					bootPromise,
+					bootDuration: () => bootDuration,
+					bootPending: () => bootPending,
+					artifact,
+					fail,
+					phase,
+					note,
+					logWriter,
+					elapsed,
+					startedAt,
+					closeWriter: () => writer?.close?.(),
+					lease: leaseHandle,
+					releaseLease,
+					devicePlacement,
+					recordRun,
+					reclaimed,
+					devServer,
+					enterPhase: progress.step,
+					enterActivity: progress.activity
+				});
+			} finally {
+				releaseLease();
+			}
+		} catch (error) {
+			recordRun({
+				failed: true,
+				durationMs: elapsed()
+			});
+			throw error;
+		} finally {
+			artifact?.release();
+		}
+	} finally {
+		await deviceWaitRun.finish();
+		hostedTarget?.host.connection.close();
+	}
+}
+//#endregion
+export { registerIos as n, runIosOperation as r, iosCommand as t };