stim 1.0.0 → 1.2.0

package/dist/reclaim-C5Jmuahx.mjs

@@ -0,0 +1,348 @@
+import { D as sameProcessRecord, O as waitForProcessExit, f as getProject, v as removeProject } from "./config-CMtIaTk9.mjs";
+import { T as workspaceDir, a as clearRemoteSession, c as readMetroTunnel, d as readRemoteSessionId, i as clearManagedMetroTunnel, p as readWorkspaceState } from "./state-CZ-ER-8d.mjs";
+import { i as resolveProjectMetro, n as killMetroTree, r as pidExists } from "./metro-COslRK_F.mjs";
+import { n as verifyCollectorOwnership } from "./ownership-CGPart6T.mjs";
+import { d as resolveEasCliBin, h as teardownOwnedIosSim, m as teardownOwnedAvd, x as parkedMaxSetting } from "./remote-cache-DDmJ1Roq.mjs";
+import { l as releaseWorkspaceLeases } from "./device-lease-Dpik41RY.mjs";
+import { i as endRecordedSession } from "./device-remote-E81KAdXf.mjs";
+import { r as stopTunnel, t as resolveSupervisorTarget } from "./ownership-CYOyqxUo.mjs";
+import { existsSync, rmSync } from "node:fs";
+//#region src/reclaim.ts
+async function reapCollectors(root, { verify = verifyCollectorOwnership, collectors }) {
+	const skippedDevices = [];
+	const failedDevices = [];
+	for (const [platform, record] of Object.entries(collectors)) {
+		const rec = record;
+		const pid = rec?.pid;
+		if (typeof pid !== "number" || pid <= 0 || pid === process.pid || !pidExists(pid)) continue;
+		const ownership = verify({
+			pid,
+			platform,
+			root,
+			expected: rec
+		});
+		if (ownership.status === "gone") continue;
+		if (ownership.status === "unverified") {
+			const name = `${platform} log collector (pid ${pid})`;
+			const entry = {
+				platform: platform === "android" ? "android" : "ios",
+				name,
+				reason: `${ownership.reason}; keeping the record without signalling the process`
+			};
+			skippedDevices.push(entry);
+			failedDevices.push(entry);
+			continue;
+		}
+		try {
+			process.kill(pid, "SIGTERM");
+			if (await waitForProcessExit(rec, 5e3)) continue;
+		} catch (error) {
+			if (error.code === "ESRCH") continue;
+		}
+		const entry = {
+			platform: platform === "android" ? "android" : "ios",
+			name: `${platform} log collector (pid ${pid})`,
+			reason: "Collector exit could not be confirmed; keeping its ownership record."
+		};
+		skippedDevices.push(entry);
+		failedDevices.push(entry);
+	}
+	return {
+		skippedDevices,
+		failedDevices
+	};
+}
+function reclaimRemoteSession(root, { stopSession = defaultStopSession } = {}) {
+	const sessionId = readRemoteSessionId(root);
+	if (!sessionId) return {
+		stopped: null,
+		failed: null
+	};
+	let result;
+	try {
+		result = stopSession(root, sessionId);
+	} catch (err) {
+		result = {
+			status: "failed",
+			reason: String(err?.message ?? err)
+		};
+	}
+	if (result.status === "torn-down") {
+		if (result.reason) return {
+			stopped: sessionId,
+			failed: {
+				platform: "ios",
+				name: `remote session ${sessionId}`,
+				reason: `${result.reason} The session is stopped. Re-run cleanup to reconcile its retained ownership claim.`
+			}
+		};
+		clearRemoteSession(root, sessionId);
+		return {
+			stopped: sessionId,
+			failed: null
+		};
+	}
+	return {
+		stopped: null,
+		failed: {
+			platform: "ios",
+			name: `remote session ${sessionId}`,
+			reason: `${result.reason ?? "stop failed"} -- it keeps billing until its max duration. Stop it by hand from any directory of this project: eas simulator:stop --id ${sessionId}`
+		}
+	};
+}
+function defaultStopSession(root, sessionId) {
+	return endRecordedSession({
+		root,
+		sessionId,
+		easBin: resolveEasCliBin(root)?.file ?? null
+	});
+}
+function defaultStopMetroTunnel(record) {
+	return stopTunnel(record);
+}
+async function reclaimMetroTunnel(root, { stopMetroTunnel = defaultStopMetroTunnel } = {}) {
+	const record = readMetroTunnel(root);
+	if (record?.kind !== "managed") return {
+		stopped: null,
+		failed: null
+	};
+	let result;
+	try {
+		result = await stopMetroTunnel(record);
+	} catch (err) {
+		result = {
+			status: "failed",
+			reason: String(err?.message ?? err)
+		};
+	}
+	if (result.status === "failed") return {
+		stopped: null,
+		failed: {
+			platform: "ios",
+			name: `${record.provider} tunnel (pid ${record.pid})`,
+			reason: `${result.reason ?? "stop failed"} The process identity could not be verified or the stop could not be confirmed. The ownership record is kept. Inspect the process and retry \`stim worktree remove\`.`
+		}
+	};
+	if (!clearManagedMetroTunnel(root, record)) return {
+		stopped: null,
+		failed: {
+			platform: "ios",
+			name: "replacement managed tunnel",
+			reason: "A replacement managed tunnel record appeared during cleanup and is retained for a later stop."
+		}
+	};
+	return {
+		stopped: record.provider,
+		failed: null
+	};
+}
+function describeDereferenced(project) {
+	const devices = [];
+	const ios = project?.platforms?.ios;
+	if (ios?.deviceUdid) devices.push(`ios sim ${ios.deviceUdid}`);
+	const android = project?.platforms?.android;
+	if (android?.avdName) devices.push(`android avd ${android.avdName}`);
+	else if (android?.serial) devices.push(`android device ${android.serial}`);
+	return devices;
+}
+function parkedIosCacheKey(lastBuild) {
+	if (lastBuild === null || typeof lastBuild !== "object" || Array.isArray(lastBuild)) return null;
+	const build = lastBuild;
+	return build.platform === "ios" && typeof build.cacheKey === "string" ? build.cacheKey : null;
+}
+function parkRequest(project, projectPath) {
+	const { max, error } = parkedMaxSetting("ios");
+	if (error || max <= 0) return void 0;
+	const cacheKey = parkedIosCacheKey(readWorkspaceState(projectPath)?.lastBuild);
+	return {
+		projectPath,
+		max,
+		bundleId: typeof project?.bundleId === "string" ? project.bundleId : null,
+		cacheKey,
+		simslimManaged: Boolean(project?.platforms?.ios?.simslimManaged)
+	};
+}
+function reclaimOwnedDevices(project, projectPath, { park = false } = {}) {
+	const deletedDevices = [];
+	const parkedDevices = [];
+	const evictedDevices = [];
+	const poolNotes = [];
+	const skippedDevices = [];
+	const failedDevices = [];
+	const ios = project?.platforms?.ios;
+	if (ios?.owned && ios.deviceUdid) {
+		const udid = ios.deviceUdid;
+		const label = ios.deviceName || udid;
+		const r = teardownOwnedIosSim(udid, {
+			del: true,
+			label,
+			...park ? { park: parkRequest(project, projectPath) } : {}
+		});
+		if (r.parkFallback) poolNotes.push(`could not park ${label}: ${r.parkFallback} -- deleted it instead`);
+		for (const failure of r.evictionFailures ?? []) poolNotes.push(failure);
+		if (r.parked) {
+			parkedDevices.push(r.parked);
+			evictedDevices.push(...r.evicted ?? []);
+		} else if (r.status === "torn-down") deletedDevices.push(r.label);
+		if (r.status === "skipped") skippedDevices.push({
+			platform: "ios",
+			name: label,
+			udid,
+			reason: `${r.reason} -- not touched`
+		});
+		else if (r.status === "failed") {
+			const entry = {
+				platform: "ios",
+				name: label,
+				udid,
+				reason: `teardown failed: ${r.reason}`
+			};
+			skippedDevices.push(entry);
+			failedDevices.push(entry);
+		}
+	}
+	const android = project?.platforms?.android;
+	if (android?.owned && android.avdName) {
+		const bound = parkedMaxSetting("android");
+		const r = teardownOwnedAvd(android.avdName, {
+			del: true,
+			owner: { projectPath },
+			...park && !bound.error && bound.max > 0 ? { park: {
+				projectPath,
+				max: bound.max,
+				configuration: typeof android.poolConfiguration === "string" ? android.poolConfiguration : void 0
+			} } : {}
+		});
+		if (r.parkFallback) poolNotes.push(`could not park ${android.avdName}: ${r.parkFallback} -- deleted it instead`);
+		for (const failure of r.evictionFailures ?? []) poolNotes.push(failure);
+		if (r.parked) {
+			parkedDevices.push(r.parked);
+			evictedDevices.push(...r.evicted ?? []);
+		} else if (r.status === "torn-down") deletedDevices.push(android.avdName);
+		else if (r.status === "skipped") skippedDevices.push({
+			platform: "android",
+			name: android.avdName,
+			reason: `${r.reason} -- not touched`
+		});
+		else if (r.status === "failed") {
+			const entry = {
+				platform: "android",
+				name: android.avdName,
+				reason: `teardown failed: ${r.reason}`
+			};
+			skippedDevices.push(entry);
+			failedDevices.push(entry);
+		}
+	}
+	return {
+		deletedDevices,
+		parkedDevices,
+		evictedDevices,
+		poolNotes,
+		skippedDevices,
+		failedDevices
+	};
+}
+async function reclaimProject(path, { deleteOwnedDevices = false, parkOwnedDevices = false, preserveProjectRecord = false, stopSession = defaultStopSession, stopMetroTunnel = defaultStopMetroTunnel, releaseLeases = releaseWorkspaceLeases, verifyCollector = verifyCollectorOwnership } = {}) {
+	const project = getProject(path);
+	const dereferenced = describeDereferenced(project);
+	const initialState = readWorkspaceState(path);
+	let killedPid = null;
+	let skippedMetro = null;
+	let supervisorHeld = false;
+	const supervisor = resolveSupervisorTarget({
+		state: initialState?.supervisor,
+		record: project?.supervisor,
+		reservedPort: project?.metroPort
+	});
+	if (supervisor.status === "ours") {
+		if (killMetroTree(supervisor.pid, supervisor.processToken) && await waitForProcessExit(supervisor, 1e4)) killedPid = supervisor.pid;
+		else {
+			skippedMetro = `could not confirm supervisor pid ${supervisor.pid} exited`;
+			supervisorHeld = true;
+		}
+	} else if (supervisor.status === "unverified") {
+		skippedMetro = supervisor.reason ?? "supervisor identity could not be verified";
+		supervisorHeld = true;
+	} else if (typeof project?.metroPort === "number") {
+		if (!(await resolveProjectMetro(project.metroPort, path)).missing) skippedMetro = "Externally started server left alone; no verified Stim supervisor owns it";
+	}
+	const { skippedDevices: skippedCollectors, failedDevices: failedCollectors } = await reapCollectors(path, {
+		verify: verifyCollector,
+		collectors: initialState?.collectors ?? {}
+	});
+	function retainReplacementProcesses() {
+		const currentState = readWorkspaceState(path);
+		const currentProject = getProject(path);
+		if (Boolean(currentState?.supervisor && !sameProcessRecord(currentState.supervisor, initialState?.supervisor) || currentProject?.supervisor && !sameProcessRecord(currentProject.supervisor, project?.supervisor) || Object.entries(currentState?.collectors ?? {}).some(([platform, record]) => !sameProcessRecord(record, initialState?.collectors?.[platform])))) {
+			supervisorHeld = true;
+			skippedMetro = "A replacement process appeared during cleanup; its ownership records are retained";
+		}
+	}
+	retainReplacementProcesses();
+	const { deletedDevices, parkedDevices, evictedDevices, poolNotes, skippedDevices, failedDevices } = deleteOwnedDevices && !supervisorHeld && failedCollectors.length === 0 ? reclaimOwnedDevices(project, path, { park: parkOwnedDevices }) : {
+		deletedDevices: [],
+		parkedDevices: [],
+		evictedDevices: [],
+		poolNotes: [],
+		skippedDevices: [],
+		failedDevices: []
+	};
+	skippedDevices.push(...skippedCollectors);
+	failedDevices.push(...failedCollectors);
+	const remote = reclaimRemoteSession(path, { stopSession });
+	if (remote.failed) {
+		skippedDevices.push(remote.failed);
+		failedDevices.push(remote.failed);
+	}
+	const tunnel = await reclaimMetroTunnel(path, { stopMetroTunnel });
+	if (tunnel.failed) {
+		skippedDevices.push(tunnel.failed);
+		failedDevices.push(tunnel.failed);
+	}
+	let releasedLeases = [];
+	try {
+		releasedLeases = releaseLeases(path);
+	} catch {
+		releasedLeases = [];
+	}
+	retainReplacementProcesses();
+	const removedWorkspaceDirs = [];
+	const failedWorkspaceDirs = [];
+	if (failedDevices.length === 0 && !supervisorHeld) {
+		const dir = workspaceDir(path);
+		if (existsSync(dir)) try {
+			rmSync(dir, {
+				recursive: true,
+				force: true
+			});
+			removedWorkspaceDirs.push(dir);
+		} catch {
+			failedWorkspaceDirs.push(dir);
+		}
+	}
+	const keptEntry = supervisorHeld || failedDevices.length > 0 || failedWorkspaceDirs.length > 0;
+	if (project && !keptEntry && !preserveProjectRecord) removeProject(path);
+	return {
+		path,
+		dereferenced,
+		killedPid,
+		skippedMetro,
+		metroPort: project?.metroPort ?? null,
+		deletedDevices,
+		parkedDevices,
+		evictedDevices,
+		poolNotes,
+		skippedDevices,
+		failedDevices,
+		keptEntry,
+		stoppedSession: remote.stopped,
+		stoppedTunnel: tunnel.stopped,
+		releasedLeases,
+		removedWorkspaceDirs,
+		failedWorkspaceDirs
+	};
+}
+//#endregion
+export { reclaimProject as n, describeDereferenced as t };

package/dist/reload-Z8nKifAk.mjs

@@ -0,0 +1,332 @@
+import { f as getProject } from "./config-CMtIaTk9.mjs";
+import { f as readWorkspaceLaunches } from "./state-CZ-ER-8d.mjs";
+import { a as findProjectRoot } from "./project-BBTVABUz.mjs";
+import { i as resolveProjectMetro } from "./metro-COslRK_F.mjs";
+import { l as phaseLine } from "./command-output-8wHMEde0.mjs";
+import { u as androidAppProcess, y as iosAppProcess } from "./app-install-NFxUahnH.mjs";
+import { x as resolveOwnedIosSim } from "./ios-D1h1Di39.mjs";
+import { N as resolveOwnedAvdSerial } from "./android-K63_0UfF.mjs";
+import chalk from "chalk";
+import { WebSocket } from "ws";
+//#region src/engine/reload.ts
+const METRO_TIMEOUT_MS = 2e3;
+function describe$1(error) {
+	return error instanceof Error ? error.message : String(error);
+}
+const ROLE_NAMES = {
+	ios: "iOS",
+	android: "Android"
+};
+function peerQuery(metadata) {
+	if (typeof metadata === "string") return new URLSearchParams(metadata);
+	if (!metadata || typeof metadata !== "object") return null;
+	const query = new URLSearchParams();
+	for (const [key, value] of Object.entries(metadata)) if (typeof value === "string") query.set(key, value);
+	return query;
+}
+function peerMatches(query, role, appId) {
+	if (role === "ios") return query.get("role")?.toLowerCase() === "ios";
+	return query.get("app") === appId;
+}
+function reloadThroughMetro(port, { role, appId, timeoutMs = METRO_TIMEOUT_MS }) {
+	const roleName = ROLE_NAMES[role];
+	return new Promise((resolve) => {
+		const requestId = `stim-reload-${process.pid}-${Date.now()}`;
+		const socket = new WebSocket(`ws://127.0.0.1:${port}/message`);
+		let settled = false;
+		const finish = (result) => {
+			if (settled) return;
+			settled = true;
+			clearTimeout(timer);
+			socket.close();
+			resolve(result);
+		};
+		const timer = setTimeout(() => finish({
+			failed: true,
+			unreachable: true,
+			reason: `Metro did not answer on port ${port}.`
+		}), timeoutMs);
+		socket.once("open", () => {
+			socket.send(JSON.stringify({
+				version: 2,
+				method: "getpeers",
+				target: "server",
+				id: requestId
+			}));
+		});
+		socket.on("message", (data) => {
+			let message;
+			try {
+				message = JSON.parse(data.toString());
+			} catch {
+				return;
+			}
+			if (message.id !== requestId) return;
+			if (message.result && typeof message.result === "object") {
+				const entries = Object.entries(message.result);
+				const peers = entries.length;
+				const rolePeers = entries.filter(([, metadata]) => {
+					const query = peerQuery(metadata);
+					return query ? peerMatches(query, role, appId) : false;
+				});
+				if (rolePeers.length === 0) {
+					socket.send(JSON.stringify({
+						version: 2,
+						method: "reload"
+					}));
+					const others = peers === 0 ? " Nothing at all is connected to it, so the broadcast Stim sent anyway reached nothing." : ` Metro has ${peers} other connected client${peers === 1 ? "" : "s"}, and Stim broadcast a reload to them in case one is this app unmatched.`;
+					finish({
+						failed: true,
+						noPeer: true,
+						peers,
+						reason: `No ${roleName} React Native app is connected to Metro on port ${port}.${others}`
+					});
+					return;
+				}
+				for (const [id] of rolePeers) socket.send(JSON.stringify({
+					version: 2,
+					method: "reload",
+					target: id
+				}));
+				finish({
+					ok: true,
+					peers,
+					targets: rolePeers.length
+				});
+				return;
+			}
+			socket.send(JSON.stringify({
+				version: 2,
+				method: "reload"
+			}));
+			finish({
+				ok: true,
+				broadcast: true
+			});
+		});
+		socket.once("error", (error) => finish({
+			failed: true,
+			unreachable: true,
+			reason: `Metro reload failed: ${describe$1(error)}`
+		}));
+	});
+}
+//#endregion
+//#region src/commands/reload.ts
+const DEFAULT_DEPS = {
+	findProjectRoot,
+	getProject,
+	readLaunches: readWorkspaceLaunches,
+	resolveIos: resolveOwnedIosSim,
+	resolveAndroid: resolveOwnedAvdSerial,
+	iosProcess: iosAppProcess,
+	androidProcess: androidAppProcess,
+	resolveMetro: resolveProjectMetro,
+	reloadMetro: reloadThroughMetro
+};
+function failure(code, message, remedy) {
+	return {
+		code,
+		message,
+		remedy
+	};
+}
+function describe(error) {
+	return error instanceof Error ? error.message : String(error);
+}
+function processFailure(platform, record, d) {
+	const process = platform === "ios" ? d.iosProcess(record.deviceId, record.appId) : d.androidProcess(record.deviceId, record.appId);
+	if (process === void 0) {
+		const probe = platform === "ios" ? `xcrun simctl spawn ${record.deviceId} launchctl list` : `adb -s ${record.deviceId} shell pidof ${record.appId}`;
+		return failure("STIM_RELOAD_PROBE_FAILED", `Stim could not determine whether ${record.appId} is running on ${record.deviceId}.`, `Run \`${probe}\` and retry when the device tool responds.`);
+	}
+	if (process === null) return failure("STIM_RELOAD_STOPPED", `${record.appId} is not running on ${record.deviceId}.`, `Run \`stim ${platform}\` to launch it.`);
+	return null;
+}
+function inspectTarget(platform, record, project, d) {
+	if (platform === "ios") {
+		const configured = project.platforms?.ios;
+		if (!configured?.owned || configured.deviceUdid !== record.deviceId) return {
+			platform,
+			error: failure("STIM_RELOAD_UNOWNED", `The recorded iOS launch on ${record.deviceId} is not this workspace's current owned simulator.`, "Run `stim ios` to launch the app on this workspace's owned simulator.")
+		};
+		let resolved;
+		try {
+			resolved = d.resolveIos(record.deviceId);
+		} catch (error) {
+			return {
+				platform,
+				error: failure("STIM_RELOAD_PROBE_FAILED", `Stim could not inspect iOS simulator ${record.deviceId}: ${describe(error)}`, "Run `xcrun simctl list devices` and retry when simctl responds.")
+			};
+		}
+		if (!resolved.sim || resolved.sim.state !== "Booted") return {
+			platform,
+			error: failure("STIM_RELOAD_STOPPED", `The recorded iOS app is not running on a booted owned simulator.`, "Run `stim ios` to boot, install, and launch it.")
+		};
+		const stopped = processFailure(platform, record, d);
+		if (stopped) return {
+			platform,
+			error: stopped
+		};
+		return {
+			platform,
+			record,
+			deviceName: resolved.sim.name
+		};
+	}
+	const configured = project.platforms?.android;
+	if (!configured?.owned || !configured.avdName) return {
+		platform,
+		error: failure("STIM_RELOAD_UNOWNED", `The recorded Android launch on ${record.deviceId} is not this workspace's current owned emulator.`, "Run `stim android` to launch the app on this workspace's owned emulator.")
+	};
+	let resolved;
+	try {
+		resolved = d.resolveAndroid(configured.avdName);
+	} catch (error) {
+		return {
+			platform,
+			error: failure("STIM_RELOAD_PROBE_FAILED", `Stim could not inspect Android emulator ${configured.avdName}: ${describe(error)}`, "Run `adb devices` and retry when adb responds.")
+		};
+	}
+	if (!resolved.serial || resolved.serial !== record.deviceId) return {
+		platform,
+		error: failure("STIM_RELOAD_STOPPED", `The recorded Android app is not running on this workspace's owned emulator.`, "Run `stim android` to boot, install, and launch it.")
+	};
+	const stopped = processFailure(platform, record, d);
+	if (stopped) return {
+		platform,
+		error: stopped
+	};
+	return {
+		platform,
+		record,
+		deviceName: configured.avdName
+	};
+}
+function isTargetFailure(value) {
+	return "error" in value;
+}
+async function runReload({ root, platform = null, deps = {} }) {
+	const d = {
+		...DEFAULT_DEPS,
+		...deps
+	};
+	const project = d.getProject(root);
+	if (!project) return {
+		ok: false,
+		error: failure("STIM_NO_PROJECT", `No Stim environment is registered for ${root}.`, "Run `stim start` first.")
+	};
+	const launches = d.readLaunches(root);
+	const inspected = (platform ? [platform] : ["ios", "android"]).flatMap((candidate) => {
+		const record = launches[candidate];
+		return record ? [inspectTarget(candidate, record, project, d)] : [];
+	});
+	const live = inspected.filter((target) => !isTargetFailure(target));
+	if (live.length > 1) return {
+		ok: false,
+		error: failure("STIM_RELOAD_AMBIGUOUS", "Both the iOS and Android apps are running.", "Choose one with `stim reload ios` or `stim reload android`.")
+	};
+	if (live.length === 0) return {
+		ok: false,
+		error: inspected.find(isTargetFailure)?.error ?? failure("STIM_RELOAD_STOPPED", platform ? `No ${platform} app launch is recorded for this workspace.` : "No live app launch is recorded.", platform ? `Run \`stim ${platform}\` first.` : "Run `stim ios` or `stim android` first.")
+	};
+	const target = live[0];
+	if (target.record.release) return {
+		ok: false,
+		error: failure("STIM_RELOAD_RELEASE", `${target.record.appId} was launched with an embedded release bundle.`, `Run \`stim ${target.platform}\` with a Debug configuration or variant before reloading JavaScript.`)
+	};
+	const port = target.record.metroPort;
+	if (!port || project.metroPort !== port) return {
+		ok: false,
+		error: failure("STIM_NO_METRO", `The launch does not point at this workspace's current Metro reservation.`, "Run `stim start`, then launch the app again.")
+	};
+	if (!(await d.resolveMetro(port, root)).metro) return {
+		ok: false,
+		error: failure("STIM_NO_METRO", `Port ${port} is not serving this workspace's Metro.`, "Run `stim start`, then retry.")
+	};
+	const stopped = processFailure(target.platform, target.record, d);
+	if (stopped) return {
+		ok: false,
+		error: stopped
+	};
+	const reloaded = await d.reloadMetro(port, {
+		role: target.platform,
+		appId: target.record.appId
+	});
+	if (!reloaded.ok) {
+		const stoppedAfterMetro = processFailure(target.platform, target.record, d);
+		if (stoppedAfterMetro) return {
+			ok: false,
+			error: stoppedAfterMetro
+		};
+		const snapshot = `agent-device snapshot -i --platform ${target.platform} --${target.platform === "ios" ? "udid" : "serial"} ${target.record.deviceId}`;
+		const relaunch = `agent-device open ${target.record.appId} --platform ${target.platform} --${target.platform === "ios" ? "udid" : "serial"} ${target.record.deviceId} --metro-port ${port} --relaunch`;
+		const firstBundle = target.platform === "ios" ? " If it stays unreachable, an error in the first bundle leaves iOS without a packager connection at all, and no retry will make it a peer." : "";
+		const device = `reload from the device in your existing automation session: run \`${snapshot}\`, then press the error screen's Reload button, or open the dev menu and press Reload when no error screen is showing. Only when neither is reachable, run \`${relaunch}\`; that restarts the app and loses in-memory state. Keep your existing --session flag, verify the expected UI afterward, and do not create another session.`;
+		const remedy = reloaded.unreachable ? `Metro is registered for this workspace but did not answer on port ${port}, so nothing is known about ${target.record.appId}. Run \`stim reload ${target.platform}\` again. If it keeps timing out, run \`stim doctor\` to check the dev server before touching the app.` : `Metro reports no peer for ${target.record.appId} right now. Stim broadcast a reload anyway, so check the expected UI on ${target.record.deviceId} first -- it may already have recovered. If not, the app reconnects every 2 seconds, so run \`stim reload ${target.platform}\` once more.${firstBundle} Then ${device}`;
+		return {
+			ok: false,
+			error: failure("STIM_RELOAD_FAILED", reloaded.reason, remedy)
+		};
+	}
+	const strategy = reloaded.broadcast ? "metro-broadcast" : "metro-websocket";
+	return {
+		ok: true,
+		facts: {
+			platform: target.platform,
+			deviceId: target.record.deviceId,
+			deviceName: target.deviceName,
+			appId: target.record.appId,
+			metroPort: port,
+			strategy,
+			targets: reloaded.targets ?? null
+		}
+	};
+}
+function registerReload(program, deps = {}) {
+	program.command("reload [platform]").description("Request a JavaScript reload in this workspace's live app without observing completion. Specify ios or android when both are live.").option("--json", "Emit the reload facts as one JSON line").action(async (value, opts) => {
+		if (value !== void 0 && value !== "ios" && value !== "android") {
+			const error = failure("STIM_BAD_ARG", `Unknown reload platform ${JSON.stringify(value)}.`, "Use ios or android.");
+			if (opts.json) console.log(JSON.stringify(error));
+			else {
+				console.error(chalk.red(phaseLine("error", `${error.code}: ${error.message}`)));
+				if (error.remedy) console.error(phaseLine("remedy", error.remedy));
+			}
+			process.exitCode = 1;
+			return;
+		}
+		const root = (deps.findProjectRoot ?? DEFAULT_DEPS.findProjectRoot)(process.cwd());
+		if (!root) {
+			const error = failure("STIM_NO_PROJECT", "Not inside a project (no package.json found above the current directory).", null);
+			if (opts.json) console.log(JSON.stringify(error));
+			else console.error(chalk.red(phaseLine("error", `${error.code}: ${error.message}`)));
+			process.exitCode = 1;
+			return;
+		}
+		const result = await runReload({
+			root,
+			platform: value ?? null,
+			deps
+		});
+		if (!result.ok) {
+			if (opts.json) console.log(JSON.stringify(result.error));
+			else {
+				console.error(chalk.red(phaseLine("error", `${result.error.code}: ${result.error.message}`)));
+				if (result.error.remedy) console.error(phaseLine("remedy", result.error.remedy));
+			}
+			process.exitCode = 1;
+			return;
+		}
+		if (opts.json) console.log(JSON.stringify(result.facts));
+		else {
+			const facts = result.facts;
+			const scope = facts.strategy === "metro-broadcast" ? ` This Metro cannot name its connected apps, so the reload request was broadcast to all of them and Stim cannot confirm ${facts.appId} was one. Check the expected UI on ${facts.deviceId}; if nothing changed, reload from the app's own error screen or dev menu.` : facts.targets && facts.targets > 1 ? ` ${facts.targets} devices are running this app on that Metro and the reload request addressed all of them, not only ${facts.deviceId}.` : "";
+			console.log(`Reload requested for ${facts.appId} on ${facts.deviceName} (${facts.deviceId}) via ${facts.strategy}; ${facts.platform} Metro port ${facts.metroPort}.${scope} Completion is not observed; verify the expected UI and run stim logs --errors.`);
+		}
+	});
+}
+function reloadCommand(program) {
+	registerReload(program);
+}
+//#endregion
+export { reloadCommand as default, registerReload, runReload };