@stim-cli/server 0.0.0 → 1.10.1

package/dist/stim-server.mjs

@@ -0,0 +1,1913 @@
+#!/usr/bin/env node
+import { a as MAX_LOG_TAIL, i as LOG_SOURCES, r as LOG_LEVELS, t as CAPABILITIES } from "./protocol-B3k9Ykuu.mjs";
+import { createRequire } from "node:module";
+import { accessSync, constants, existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, renameSync, rmSync, watch, writeFileSync } from "node:fs";
+import { homedir, hostname, tmpdir } from "node:os";
+import { parseArgs } from "node:util";
+import { execFile, execFileSync, spawn, spawnSync } from "node:child_process";
+import { basename, delimiter, dirname, join } from "node:path";
+import { createHash, randomBytes } from "node:crypto";
+import { configDir, withDirLock } from "@stim-cli/core";
+import { compileGrep, isJsonObject, loadConfig, readJsonObject } from "@stim-cli/core/state";
+import { createServer } from "node:http";
+import { isIP } from "node:net";
+import { WebSocketServer } from "ws";
+import { createInterface } from "node:readline";
+import { connect } from "node:http2";
+//#region src/environment.ts
+function parseEnvironment(output) {
+	const environment = {};
+	for (const entry of output.split("\0")) {
+		const equals = entry.indexOf("=");
+		if (equals > 0) environment[entry.slice(0, equals)] = entry.slice(equals + 1);
+	}
+	return environment;
+}
+/**
+* The login shell's environment, as Stim Desktop captures it: a process started by launchd lacks the
+* PATH entries and variables such as ANDROID_HOME that the shell profile sets. The shell writes to a
+* file because a background process started by a profile can keep a pipe open after the shell exits.
+*/
+function loginShellEnvironment() {
+	const dir = mkdtempSync(join(tmpdir(), "stim-server-env-"));
+	const file = join(dir, "env");
+	try {
+		spawnSync(process.env.SHELL || "/bin/zsh", [
+			"-lic",
+			"command env -0 > \"$1\"",
+			"stim-server",
+			file
+		], {
+			stdio: "ignore",
+			timeout: 15e3
+		});
+		const environment = parseEnvironment(readFileSync(file, "utf8"));
+		return Object.keys(environment).length ? environment : null;
+	} catch {
+		return null;
+	} finally {
+		rmSync(dir, {
+			recursive: true,
+			force: true
+		});
+	}
+}
+function bundledStim() {
+	const manifest = createRequire(import.meta.url).resolve("stim/package.json");
+	const pkg = JSON.parse(readFileSync(manifest, "utf8"));
+	return {
+		cli: join(dirname(manifest), pkg.bin.stim),
+		version: pkg.version
+	};
+}
+//#endregion
+//#region src/registry.ts
+const PAIRING_TTL_MS = 3e5;
+function serverDir() {
+	return join(configDir(), "server");
+}
+function devicesFile() {
+	return join(serverDir(), "devices.json");
+}
+function pairingFile() {
+	return join(serverDir(), "pairing.json");
+}
+function hashToken(token) {
+	return createHash("sha256").update(token).digest("hex");
+}
+function newToken() {
+	return randomBytes(32).toString("base64url");
+}
+function parseIdentity(value) {
+	if (!isJsonObject(value)) return null;
+	if (value.kind === "local") return { kind: "local" };
+	const { nodeId, nodeName, user } = value;
+	if (value.kind === "tailnet" && typeof nodeId === "string" && typeof nodeName === "string" && typeof user === "string") return {
+		kind: "tailnet",
+		nodeId,
+		nodeName,
+		user
+	};
+	return null;
+}
+function parseDevice(value) {
+	if (!isJsonObject(value)) return null;
+	const { id, name, tokenHash, pairedAt, lastSeenAt } = value;
+	const identity = parseIdentity(value.identity);
+	if (typeof id !== "string" || typeof name !== "string" || typeof tokenHash !== "string" || !identity) return null;
+	if (typeof pairedAt !== "string") return null;
+	const capabilities = Array.isArray(value.capabilities) ? CAPABILITIES.filter((capability) => value.capabilities.includes(capability)) : [];
+	return {
+		id,
+		name,
+		tokenHash,
+		identity,
+		pairedAt,
+		lastSeenAt: typeof lastSeenAt === "string" ? lastSeenAt : null,
+		capabilities
+	};
+}
+function readDevices() {
+	const devices = readJsonObject(devicesFile())?.devices;
+	return Array.isArray(devices) ? devices.flatMap((entry) => parseDevice(entry) ?? []) : [];
+}
+function readPairings() {
+	const tokens = readJsonObject(pairingFile())?.tokens;
+	if (!Array.isArray(tokens)) return [];
+	return tokens.flatMap((entry) => isJsonObject(entry) && typeof entry.tokenHash === "string" && typeof entry.expiresAt === "string" ? [{
+		tokenHash: entry.tokenHash,
+		expiresAt: entry.expiresAt
+	}] : []);
+}
+function writeJson(file, value) {
+	const temporary = join(dirname(file), `.${basename(file)}.${process.pid}.tmp`);
+	try {
+		writeFileSync(temporary, `${JSON.stringify(value, null, 2)}\n`, { mode: 384 });
+		renameSync(temporary, file);
+	} catch (error) {
+		rmSync(temporary, { force: true });
+		throw error;
+	}
+}
+function transaction(fn) {
+	return withDirLock(join(serverDir(), "registry.lock"), fn, { ensureParent: () => mkdirSync(serverDir(), {
+		recursive: true,
+		mode: 448
+	}) });
+}
+function unexpired(record, now) {
+	return Date.parse(record.expiresAt) > now;
+}
+function createPairingToken(now = Date.now()) {
+	const token = newToken();
+	const expiresAt = new Date(now + PAIRING_TTL_MS).toISOString();
+	transaction(() => {
+		const pending = readPairings().filter((record) => unexpired(record, now));
+		writeJson(pairingFile(), {
+			version: 1,
+			tokens: [...pending, {
+				tokenHash: hashToken(token),
+				expiresAt
+			}]
+		});
+	});
+	return {
+		token,
+		expiresAt
+	};
+}
+function sameNode(a, b) {
+	if (a.kind === "local" || b.kind === "local") return a.kind === b.kind;
+	return a.nodeId === b.nodeId;
+}
+function spendPairingToken(token, name, identity, now = Date.now()) {
+	return transaction(() => {
+		const pairings = readPairings();
+		const tokenHash = hashToken(token);
+		const match = pairings.find((record) => record.tokenHash === tokenHash);
+		const pending = pairings.filter((record) => record !== match && unexpired(record, now));
+		if (pending.length !== pairings.length) writeJson(pairingFile(), {
+			version: 1,
+			tokens: pending
+		});
+		if (!match) return {
+			ok: false,
+			reason: "pairing-unknown"
+		};
+		if (!unexpired(match, now)) return {
+			ok: false,
+			reason: "pairing-expired"
+		};
+		const deviceToken = newToken();
+		const at = new Date(now).toISOString();
+		const device = {
+			id: randomBytes(4).toString("hex"),
+			name,
+			tokenHash: hashToken(deviceToken),
+			identity,
+			pairedAt: at,
+			lastSeenAt: at,
+			capabilities: ["read"]
+		};
+		writeJson(devicesFile(), {
+			version: 1,
+			devices: [...readDevices(), device]
+		});
+		return {
+			ok: true,
+			device,
+			deviceToken
+		};
+	});
+}
+function authenticateDevice(token, identity, now = Date.now()) {
+	return transaction(() => {
+		const devices = readDevices();
+		const tokenHash = hashToken(token);
+		const device = devices.find((entry) => entry.tokenHash === tokenHash);
+		if (!device) return {
+			ok: false,
+			reason: "device-unknown"
+		};
+		if (!sameNode(device.identity, identity)) return {
+			ok: false,
+			reason: "node-mismatch"
+		};
+		device.lastSeenAt = new Date(now).toISOString();
+		writeJson(devicesFile(), {
+			version: 1,
+			devices
+		});
+		return {
+			ok: true,
+			device
+		};
+	});
+}
+function revokeDevice(id) {
+	return transaction(() => {
+		const devices = readDevices();
+		const remaining = devices.filter((device) => device.id !== id);
+		if (remaining.length === devices.length) return false;
+		writeJson(devicesFile(), {
+			version: 1,
+			devices: remaining
+		});
+		return true;
+	});
+}
+//#endregion
+//#region src/stim-command.ts
+const KILL_GRACE_MS = 1e3;
+function terminate(child) {
+	if (child.exitCode !== null || child.signalCode !== null) return Promise.resolve();
+	child.kill("SIGTERM");
+	const timer = setTimeout(() => child.kill("SIGKILL"), KILL_GRACE_MS);
+	return new Promise((resolve) => {
+		const done = () => {
+			clearTimeout(timer);
+			resolve();
+		};
+		child.once("exit", done);
+		child.once("close", done);
+	});
+}
+function runStim(stimCli, env, args, cwd, limits) {
+	const child = spawn(process.execPath, [stimCli, ...args], {
+		cwd,
+		env,
+		stdio: [
+			"ignore",
+			"pipe",
+			"pipe"
+		]
+	});
+	const label = `stim ${args[0]}`;
+	let cancelled = false;
+	let failure = null;
+	const chunks = [];
+	let size = 0;
+	let stderr = "";
+	const fail = (message) => {
+		if (failure) return;
+		failure = message;
+		terminate(child);
+	};
+	const timer = setTimeout(() => fail(`${label} did not finish within ${limits.timeoutMs / 1e3} s.`), limits.timeoutMs);
+	child.stdout.on("data", (chunk) => {
+		size += chunk.length;
+		if (size > limits.maxOutputBytes) return fail(`${label} printed more than ${limits.maxOutputBytes} bytes.`);
+		chunks.push(chunk);
+	});
+	child.stderr.setEncoding("utf8");
+	child.stderr.on("data", (chunk) => {
+		stderr = (stderr + chunk).slice(-2e3);
+	});
+	return {
+		outcome: new Promise((resolve) => {
+			const settle = (result) => {
+				clearTimeout(timer);
+				if (!cancelled) resolve(result);
+			};
+			child.on("error", (error) => settle({
+				ok: false,
+				message: `${label} could not start (${error.message}).`
+			}));
+			child.on("close", (code, signal) => {
+				if (failure) return settle({
+					ok: false,
+					message: failure
+				});
+				if (code === 0) return settle({
+					ok: true,
+					stdout: Buffer.concat(chunks).toString("utf8")
+				});
+				const detail = stderr.trim();
+				settle({
+					ok: false,
+					message: `${label} exited (${signal ?? `code ${code}`})${detail ? `: ${detail}` : ""}`
+				});
+			});
+		}),
+		cancel: () => {
+			cancelled = true;
+			clearTimeout(timer);
+			return terminate(child);
+		}
+	};
+}
+//#endregion
+//#region src/feed.ts
+var Feed = class {
+	listeners = /* @__PURE__ */ new Set();
+	kept = [];
+	child;
+	ended;
+	constructor(spec, stimCli, env, ended) {
+		this.ended = ended;
+		const child = spawn(process.execPath, [stimCli, ...spec.args], {
+			cwd: spec.cwd,
+			env,
+			stdio: [
+				"ignore",
+				"pipe",
+				"pipe"
+			]
+		});
+		this.child = child;
+		let stderr = "";
+		child.stderr?.setEncoding("utf8");
+		child.stderr?.on("data", (chunk) => {
+			stderr = (stderr + chunk).slice(-2e3);
+		});
+		createInterface({ input: child.stdout }).on("line", (line) => {
+			if (this.child !== child) return;
+			let value;
+			try {
+				value = JSON.parse(line);
+			} catch {
+				return;
+			}
+			if (!isJsonObject(value)) return;
+			this.kept.push(value);
+			if (this.kept.length > spec.keep) this.kept.shift();
+			for (const listener of this.listeners) listener.item(value);
+		});
+		const exited = (reason) => {
+			if (this.child !== child) return;
+			this.child = null;
+			this.ended();
+			const message = `${spec.label} ${reason}${stderr.trim() ? `: ${stderr.trim()}` : ""}`;
+			const listeners = [...this.listeners];
+			this.listeners.clear();
+			for (const listener of listeners) listener.failed(message);
+		};
+		child.on("error", (error) => exited(`could not start (${error.message})`));
+		child.on("close", (code, signal) => exited(`exited (${signal ?? `code ${code}`})`));
+	}
+	add(listener) {
+		this.listeners.add(listener);
+		for (const value of this.kept) listener.item(value);
+		return () => {
+			if (this.listeners.delete(listener) && this.listeners.size === 0) this.stop();
+		};
+	}
+	stop() {
+		const child = this.child;
+		if (!child) return Promise.resolve();
+		this.child = null;
+		this.listeners.clear();
+		this.ended();
+		return terminate(child);
+	}
+};
+var FeedPool = class {
+	feeds = /* @__PURE__ */ new Map();
+	stimCli;
+	env;
+	constructor(stimCli, env) {
+		this.stimCli = stimCli;
+		this.env = env;
+	}
+	subscribe(spec, listener) {
+		const key = JSON.stringify([spec.cwd, spec.args]);
+		let feed = this.feeds.get(key);
+		if (!feed) {
+			const created = new Feed(spec, this.stimCli, this.env, () => {
+				if (this.feeds.get(key) === created) this.feeds.delete(key);
+			});
+			this.feeds.set(key, created);
+			feed = created;
+		}
+		return feed.add(listener);
+	}
+	async close() {
+		await Promise.all([...this.feeds.values()].map((feed) => feed.stop()));
+	}
+};
+//#endregion
+//#region src/frames.ts
+const DEFAULT_FRAME_LIMITS = {
+	toolTimeoutMs: 3e4,
+	slowCaptureMs: 3e3,
+	failureBackoffMs: 3e3,
+	maxConsecutiveFailures: 3
+};
+const MIN_INTERVAL_MS = 200;
+const MAX_INTERVAL_MS = 1e3;
+const MAX_CAPTURES = 2;
+const MAX_EDGE = 1280;
+const JPEG_QUALITY = 70;
+function deviceKey(device) {
+	return device.platform === "ios" ? `ios:${device.udid}` : `android:${device.serial}`;
+}
+function ownedDevice(payload, target, attached) {
+	const slot = target.slot ?? "default";
+	if (!Array.isArray(payload.environments)) return "stim status printed a payload without environments.";
+	const environment = payload.environments.find((candidate) => candidate.path === target.workspace);
+	if (!environment) return `${target.workspace} is not a Stim workspace on this Mac.`;
+	const devices = slot === "default" ? {
+		ios: environment.ios,
+		android: environment.android
+	} : environment.slots?.find((candidate) => candidate.slot === slot);
+	const where = `${target.platform} in slot ${slot} of ${target.workspace}`;
+	if (target.platform === "ios") {
+		const sim = devices?.ios;
+		if (!sim?.owned) return `No simulator Stim owns runs ${where}.`;
+		if (sim.state !== "Booted") return `The simulator for ${where} is ${sim.state}, not booted.`;
+		return {
+			platform: "ios",
+			udid: sim.udid
+		};
+	}
+	const emulator = devices?.android;
+	if (!emulator?.owned || emulator.physical) return `No emulator Stim owns runs ${where}.`;
+	if (emulator.state === "unknown" && attached?.startsWith("android:")) return {
+		platform: "android",
+		serial: attached.slice(8)
+	};
+	if (emulator.state !== "detected" || !emulator.serial) return `The emulator for ${where} is not running.`;
+	return {
+		platform: "android",
+		serial: emulator.serial
+	};
+}
+function jpegSize(bytes) {
+	if (bytes[0] !== 255 || bytes[1] !== 216) return null;
+	let offset = 2;
+	while (offset + 9 <= bytes.length) {
+		if (bytes[offset] !== 255) return null;
+		const marker = bytes[offset + 1];
+		if (marker === 255) {
+			offset += 1;
+			continue;
+		}
+		if (marker === 1 || marker >= 208 && marker <= 216) {
+			offset += 2;
+			continue;
+		}
+		if (marker >= 192 && marker <= 207 && marker !== 196 && marker !== 200 && marker !== 204) return {
+			height: bytes.readUInt16BE(offset + 5),
+			width: bytes.readUInt16BE(offset + 7)
+		};
+		offset += 2 + bytes.readUInt16BE(offset + 2);
+	}
+	return null;
+}
+/** A rejection with `transient: true` is a timeout on a machine that is merely busy, not a broken capturer. */
+function timeoutError(message) {
+	return Object.assign(new Error(message), { transient: true });
+}
+function isTransient(error) {
+	return error instanceof Error && error.transient === true;
+}
+function runTool(file, args, env, running, timeoutMs) {
+	return new Promise((resolve, reject) => {
+		const child = spawn(file, args, {
+			env,
+			stdio: [
+				"ignore",
+				"pipe",
+				"pipe"
+			]
+		});
+		running.add(child);
+		child.once("close", () => running.delete(child));
+		const chunks = [];
+		let stderr = "";
+		const timer = setTimeout(() => {
+			terminate(child);
+			reject(timeoutError(`${file} ${args[0]} did not finish within ${timeoutMs / 1e3} s.`));
+		}, timeoutMs);
+		child.stdout.on("data", (chunk) => chunks.push(chunk));
+		child.stderr.setEncoding("utf8");
+		child.stderr.on("data", (chunk) => {
+			stderr = (stderr + chunk).slice(-1e3);
+		});
+		child.on("error", (error) => {
+			clearTimeout(timer);
+			reject(/* @__PURE__ */ new Error(`${file} could not start (${error.message}).`));
+		});
+		child.on("close", (code) => {
+			clearTimeout(timer);
+			if (code === 0) resolve(Buffer.concat(chunks));
+			else reject(Object.assign(/* @__PURE__ */ new Error(`${file} ${args.join(" ")} exited (code ${code}): ${stderr.trim()}`), { stderr }));
+		});
+	});
+}
+async function stopTools(running, tmp) {
+	await Promise.all([...running].map((child) => terminate(child)));
+	if (tmp) rmSync(tmp, {
+		recursive: true,
+		force: true
+	});
+}
+/**
+* Without `--display`, simctl captures the first panel it finds, which on a foldable simulator (iPhone Duo)
+* can be the unlit one and comes back black; `primary` is the panel CoreDevice reports as primary. A simctl
+* that rejects `primary` gets the default display instead.
+*/
+function simulatorCapturer(udid, env, limits) {
+	let tmp = null;
+	let display = ["--display=primary"];
+	let closed = false;
+	const running = /* @__PURE__ */ new Set();
+	const screenshot = (output) => runTool("xcrun", [
+		"simctl",
+		"io",
+		udid,
+		"screenshot",
+		"--type=jpeg",
+		...display,
+		output
+	], env, running, limits.toolTimeoutMs);
+	return {
+		capture: async () => {
+			tmp ??= mkdtempSync(join(serverDir(), "frames-"));
+			const output = join(tmp, "frame.jpg");
+			try {
+				await screenshot(output);
+			} catch (error) {
+				if (closed || !display.length || !/display/i.test(error.stderr ?? "")) throw error;
+				display = [];
+				await screenshot(output);
+			}
+			const jpeg = readFileSync(output);
+			return {
+				raw: jpeg,
+				jpeg: async () => jpeg
+			};
+		},
+		close: () => {
+			closed = true;
+			return stopTools(running, tmp);
+		}
+	};
+}
+/**
+* The emulator writes `pid_<pid>.ini` to this directory on macOS when it was started with `-grpc`, which
+* Stim passes when it boots an owned AVD (#1064).
+*/
+function emulatorEndpoint(env, serial) {
+	const console = /^emulator-(\d+)$/.exec(serial)?.[1];
+	if (!console || !env.HOME) return null;
+	const dir = join(env.HOME, "Library/Caches/TemporaryItems/avd/running");
+	let names;
+	try {
+		names = readdirSync(dir);
+	} catch {
+		return null;
+	}
+	for (const name of names) {
+		const pid = /^pid_(\d+)\.ini$/.exec(name)?.[1];
+		if (!pid) continue;
+		try {
+			process.kill(Number(pid), 0);
+		} catch {
+			continue;
+		}
+		let text;
+		try {
+			text = readFileSync(join(dir, name), "utf8");
+		} catch {
+			continue;
+		}
+		const values = new Map(text.split(/\r?\n/).flatMap((line) => {
+			const at = line.indexOf("=");
+			return at > 0 ? [[line.slice(0, at), line.slice(at + 1)]] : [];
+		}));
+		const grpcPort = Number(values.get("grpc.port"));
+		if (values.get("port.serial") === console && Number.isInteger(grpcPort) && grpcPort > 0) return {
+			grpcPort,
+			token: values.get("grpc.token") ?? null
+		};
+	}
+	return null;
+}
+function varint(value) {
+	const out = [];
+	let rest = value;
+	while (rest >= 128) {
+		out.push(rest & 127 | 128);
+		rest = Math.floor(rest / 128);
+	}
+	out.push(rest);
+	return out;
+}
+function* protoFields(bytes) {
+	let offset = 0;
+	const readVarint = () => {
+		let result = 0;
+		let scale = 1;
+		for (;;) {
+			if (offset >= bytes.length) throw new Error("truncated protobuf");
+			const byte = bytes[offset++];
+			result += (byte & 127) * scale;
+			if (byte < 128) return result;
+			scale *= 128;
+		}
+	};
+	while (offset < bytes.length) {
+		const key = readVarint();
+		const field = Math.floor(key / 8);
+		const type = key % 8;
+		if (type === 0) yield {
+			field,
+			varint: readVarint()
+		};
+		else if (type === 2) {
+			const length = readVarint();
+			if (offset + length > bytes.length) throw new Error("truncated protobuf");
+			yield {
+				field,
+				bytes: bytes.subarray(offset, offset + length)
+			};
+			offset += length;
+		} else if (type === 1) offset += 8;
+		else if (type === 5) offset += 4;
+		else throw new Error(`unsupported protobuf wire type ${type}`);
+	}
+}
+/** `ImageFormat` and `Image` in the emulator's emulator_controller.proto; format 0 is PNG. */
+function screenshotRequest() {
+	const message = Buffer.from([
+		24,
+		...varint(MAX_EDGE),
+		32,
+		...varint(MAX_EDGE)
+	]);
+	const header = Buffer.alloc(5);
+	header.writeUInt32BE(message.length, 1);
+	return Buffer.concat([header, message]);
+}
+function screenshotImage(body) {
+	if (body.length < 5 || body[0] !== 0) throw new Error("getScreenshot returned no message.");
+	const message = body.subarray(5, 5 + body.readUInt32BE(1));
+	for (const entry of protoFields(message)) if (entry.field === 4 && "bytes" in entry) return Buffer.from(entry.bytes);
+	throw new Error("getScreenshot returned no image.");
+}
+function emulatorCapturer(serial, env, limits) {
+	let session = null;
+	let tmp = null;
+	const running = /* @__PURE__ */ new Set();
+	const call = (endpoint) => new Promise((resolve, reject) => {
+		if (!session || session.closed || session.destroyed) {
+			session = connect(`http://127.0.0.1:${endpoint.grpcPort}`);
+			session.on("error", () => {});
+		}
+		const request = session.request({
+			":method": "POST",
+			":path": "/android.emulation.control.EmulatorController/getScreenshot",
+			"content-type": "application/grpc",
+			te: "trailers",
+			...endpoint.token ? { authorization: `Bearer ${endpoint.token}` } : {}
+		});
+		const chunks = [];
+		let status;
+		let message;
+		let timedOut = false;
+		const record = (headers) => {
+			if (headers["grpc-status"] !== void 0) status = String(headers["grpc-status"]);
+			if (headers["grpc-message"] !== void 0) message = String(headers["grpc-message"]);
+		};
+		request.setTimeout(limits.toolTimeoutMs, () => {
+			timedOut = true;
+			request.close();
+		});
+		request.on("response", record);
+		request.on("trailers", record);
+		request.on("data", (chunk) => chunks.push(chunk));
+		request.on("error", (error) => {
+			const text = `getScreenshot failed on ${serial}: ${error.message}`;
+			reject(timedOut ? timeoutError(text) : new Error(text));
+		});
+		request.on("close", () => {
+			if (status === "0") return resolve(Buffer.concat(chunks));
+			const text = `getScreenshot failed on ${serial}: ${message ?? `status ${status ?? "missing"}`}`;
+			reject(timedOut ? timeoutError(text) : new Error(text));
+		});
+		request.end(screenshotRequest());
+	});
+	return {
+		capture: async () => {
+			const endpoint = emulatorEndpoint(env, serial);
+			if (!endpoint) throw new Error(`${serial} has no gRPC endpoint. Frames appear after Stim next boots this emulator.`);
+			const png = screenshotImage(await call(endpoint));
+			return {
+				raw: png,
+				jpeg: async () => {
+					tmp ??= mkdtempSync(join(serverDir(), "frames-"));
+					const input = join(tmp, "frame.png");
+					const output = join(tmp, "frame.jpg");
+					writeFileSync(input, png);
+					await runTool("sips", [
+						...[
+							"-s",
+							"format",
+							"jpeg",
+							"-s",
+							"formatOptions",
+							String(JPEG_QUALITY)
+						],
+						input,
+						"--out",
+						output
+					], env, running, limits.toolTimeoutMs);
+					return readFileSync(output);
+				}
+			};
+		},
+		close: () => {
+			session?.close();
+			return stopTools(running, tmp);
+		}
+	};
+}
+var Limiter = class {
+	active = 0;
+	waiting = [];
+	max;
+	constructor(max) {
+		this.max = max;
+	}
+	async run(task) {
+		if (this.active >= this.max) await new Promise((resolve) => this.waiting.push(resolve));
+		else this.active++;
+		try {
+			return await task();
+		} finally {
+			const next = this.waiting.shift();
+			if (next) next();
+			else this.active--;
+		}
+	}
+};
+var FrameSource = class {
+	listeners = /* @__PURE__ */ new Set();
+	last = null;
+	lastHash = null;
+	interval = MIN_INTERVAL_MS;
+	timer = null;
+	stopped = false;
+	delayed = false;
+	consecutiveFailures = 0;
+	capturer;
+	limiter;
+	limits;
+	ended;
+	constructor(capturer, limiter, limits, ended) {
+		this.capturer = capturer;
+		this.limiter = limiter;
+		this.limits = limits;
+		this.ended = ended;
+		this.tick();
+	}
+	add(listener) {
+		this.listeners.add(listener);
+		if (this.last) listener.frame(this.last);
+		if (this.delayed) listener.delayed(true);
+		return () => {
+			if (this.listeners.delete(listener) && this.listeners.size === 0) this.stop();
+		};
+	}
+	stop() {
+		if (this.stopped) return Promise.resolve();
+		this.stopped = true;
+		if (this.timer) clearTimeout(this.timer);
+		this.listeners.clear();
+		this.ended();
+		return this.capturer.close();
+	}
+	setDelayed(delayed) {
+		if (this.delayed === delayed) return;
+		this.delayed = delayed;
+		for (const listener of this.listeners) listener.delayed(delayed);
+	}
+	async tick() {
+		this.timer = null;
+		let took = 0;
+		try {
+			const changed = await this.limiter.run(async () => {
+				if (this.stopped) return false;
+				const started = Date.now();
+				const capture = await this.capturer.capture();
+				const hash = createHash("sha256").update(capture.raw).digest("hex");
+				took = Date.now() - started;
+				if (hash === this.lastHash || this.stopped) return false;
+				const jpeg = await capture.jpeg();
+				const size = jpegSize(jpeg);
+				if (!size) throw new Error("The screenshot is not a JPEG image.");
+				this.lastHash = hash;
+				this.last = {
+					...size,
+					capturedAt: new Date(started).toISOString(),
+					data: jpeg.toString("base64")
+				};
+				took = Date.now() - started;
+				return true;
+			});
+			if (this.stopped) return;
+			this.consecutiveFailures = 0;
+			this.setDelayed(took > this.limits.slowCaptureMs);
+			if (changed) for (const listener of this.listeners) listener.frame(this.last);
+			this.interval = changed ? MIN_INTERVAL_MS : Math.min(this.interval * 2, MAX_INTERVAL_MS);
+			this.timer = setTimeout(() => void this.tick(), Math.max(this.interval - took, took));
+		} catch (error) {
+			if (this.stopped) return;
+			if (isTransient(error) && this.consecutiveFailures + 1 < this.limits.maxConsecutiveFailures) {
+				this.consecutiveFailures++;
+				this.setDelayed(true);
+				this.timer = setTimeout(() => void this.tick(), this.limits.failureBackoffMs);
+				return;
+			}
+			const listeners = [...this.listeners];
+			this.stop();
+			for (const listener of listeners) listener.failed(error.message);
+		}
+	}
+};
+/**
+* One capture loop per device, shared by its subscribers and stopped with the last of them. A loop sends a
+* frame only when the screen changed; it captures up to 5 times a second while the screen changes and backs
+* off to once a second while it does not, and spends at most half of its time capturing. At most two
+* captures run at once across all devices.
+*/
+var FramePool = class {
+	sources = /* @__PURE__ */ new Map();
+	limiter = new Limiter(MAX_CAPTURES);
+	env;
+	limits;
+	constructor(env, limits = DEFAULT_FRAME_LIMITS) {
+		this.env = env;
+		this.limits = limits;
+	}
+	subscribe(device, listener) {
+		const key = deviceKey(device);
+		let source = this.sources.get(key);
+		if (!source) {
+			const created = new FrameSource(device.platform === "ios" ? simulatorCapturer(device.udid, this.env, this.limits) : emulatorCapturer(device.serial, this.env, this.limits), this.limiter, this.limits, () => {
+				if (this.sources.get(key) === created) this.sources.delete(key);
+			});
+			this.sources.set(key, created);
+			source = created;
+		}
+		return source.add(listener);
+	}
+	async close() {
+		await Promise.all([...this.sources.values()].map((source) => source.stop()));
+	}
+};
+//#endregion
+//#region src/logs.ts
+function parseLogFilter(params) {
+	if (!isJsonObject(params) || typeof params.workspace !== "string") return { error: "params.workspace is required." };
+	const { sources, level, slot, grep, errors, tail } = params;
+	if (sources !== void 0 && (!Array.isArray(sources) || sources.length === 0 || !sources.every((source) => LOG_SOURCES.includes(source)))) return { error: `sources must be a non-empty list of ${LOG_SOURCES.join(", ")}.` };
+	if (level !== void 0 && !LOG_LEVELS.includes(level)) return { error: `level must be one of ${LOG_LEVELS.join(", ")}.` };
+	if (slot !== void 0 && (typeof slot !== "string" || slot === "")) return { error: "slot must be a slot name." };
+	if (grep !== void 0 && (typeof grep !== "string" || compileGrep(grep).error)) return { error: "grep must be a valid regular expression." };
+	if (errors !== void 0 && typeof errors !== "boolean") return { error: "errors must be true or false." };
+	if (tail !== void 0 && (!Number.isInteger(tail) || tail < 1 || tail > 5e3)) return { error: `tail must be an integer from 1 to ${MAX_LOG_TAIL}.` };
+	return { filter: {
+		workspace: params.workspace,
+		...sources ? { sources } : {},
+		...level && level !== "debug" ? { level } : {},
+		...slot ? { slot } : {},
+		...grep ? { grep } : {},
+		...errors ? { errors } : {},
+		tail: tail ?? 5e3
+	} };
+}
+function logArgs(filter, follow) {
+	const args = [
+		"logs",
+		"--json",
+		...follow ? ["--follow"] : [],
+		`--tail=${filter.tail ?? 5e3}`
+	];
+	if (filter.sources) args.push("--source", ...LOG_SOURCES.filter((source) => filter.sources.includes(source)));
+	if (filter.slot) args.push(`--slot=${filter.slot}`);
+	if (filter.level) args.push(`--level=${filter.level}`);
+	if (filter.grep) args.push(`--grep=${filter.grep}`);
+	if (filter.errors) args.push("--errors");
+	return args;
+}
+const BATCH_MS = 100;
+const MAX_BATCH = 500;
+var LogBatcher = class {
+	pending = [];
+	timer = null;
+	stopped = false;
+	sink;
+	limits;
+	constructor(sink, limits) {
+		this.sink = sink;
+		this.limits = limits;
+	}
+	push(record) {
+		if (this.stopped) return;
+		this.pending.push(record);
+		if (this.pending.length > this.limits.maxPendingRecords) {
+			this.stop();
+			queueMicrotask(this.sink.overflow);
+			return;
+		}
+		this.timer ??= setTimeout(() => this.flush(false), BATCH_MS);
+	}
+	flush(force) {
+		if (this.timer) clearTimeout(this.timer);
+		this.timer = null;
+		while (this.pending.length) {
+			if (!force && this.sink.bufferedBytes() >= this.limits.maxBufferedBytes) break;
+			this.sink.send(this.pending.splice(0, MAX_BATCH));
+		}
+		if (this.pending.length && !this.stopped) this.timer = setTimeout(() => this.flush(false), BATCH_MS);
+	}
+	stop() {
+		this.stopped = true;
+		if (this.timer) clearTimeout(this.timer);
+		this.timer = null;
+		this.pending = [];
+	}
+};
+//#endregion
+//#region src/tailscale.ts
+const MAC_APP_BINARY = "/Applications/Tailscale.app/Contents/MacOS/Tailscale";
+const TIMEOUT_MS = 3e3;
+/** The tailnet-only HTTPS port the setup command serves stim-server on. */
+const SERVE_PORT = 7443;
+function executable(path) {
+	try {
+		accessSync(path, constants.X_OK);
+		return true;
+	} catch {
+		return false;
+	}
+}
+function findTailscale(env) {
+	for (const dir of (env.PATH ?? "").split(delimiter)) if (dir && executable(join(dir, "tailscale"))) return join(dir, "tailscale");
+	return executable(MAC_APP_BINARY) ? MAC_APP_BINARY : null;
+}
+function parseTailscaleStatus(value) {
+	if (!isJsonObject(value) || typeof value.BackendState !== "string") return {
+		state: "unavailable",
+		reason: "`tailscale status --json` printed no BackendState"
+	};
+	if (value.BackendState !== "Running") return {
+		state: "not-running",
+		backendState: value.BackendState
+	};
+	const self = isJsonObject(value.Self) ? value.Self : {};
+	return {
+		state: "running",
+		ips: Array.isArray(value.TailscaleIPs) ? value.TailscaleIPs.filter((ip) => typeof ip === "string") : [],
+		dnsName: typeof self.DNSName === "string" && self.DNSName ? self.DNSName.replace(/\.$/, "") : null,
+		hostName: typeof self.HostName === "string" && self.HostName ? self.HostName : null
+	};
+}
+function tailscaleStatus(binary, env) {
+	if (!binary) return {
+		state: "unavailable",
+		reason: "the tailscale command was not found"
+	};
+	try {
+		const output = execFileSync(binary, ["status", "--json"], {
+			env,
+			timeout: TIMEOUT_MS,
+			encoding: "utf8",
+			stdio: [
+				"ignore",
+				"pipe",
+				"ignore"
+			]
+		});
+		return parseTailscaleStatus(JSON.parse(output));
+	} catch (error) {
+		return {
+			state: "unavailable",
+			reason: `\`tailscale status --json\` failed: ${error.message}`
+		};
+	}
+}
+function reaches(address, target, hosts) {
+	if (typeof address !== "string") return null;
+	let url;
+	try {
+		url = new URL(address.includes("://") ? address : `tcp://${address}`);
+	} catch {
+		return null;
+	}
+	return hosts.has(url.hostname) && url.port === String(target) ? url : null;
+}
+function portOf(hostPort) {
+	return Number(hostPort.slice(hostPort.lastIndexOf(":") + 1));
+}
+/**
+* Reads `tailscale serve status --json`, an ipn.ServeConfig: `TCP` maps a port to `{ HTTPS }` or
+* `{ TCPForward }`, `Web` maps `<host>:<port>` to `{ Handlers: { <mount>: { Proxy } } }`,
+* `AllowFunnel` maps `<host>:<port>` to true, and `Foreground` holds the same shape per
+* foreground session. Any handler or TCP forward that reaches the server on a Funnel port exposes
+* it; only a `/` HTTP proxy on an HTTPS port is a route a client can use.
+*/
+function parseServeStatus(value, target, ips) {
+	if (!isJsonObject(value)) return {
+		state: "unknown",
+		reason: "it printed no serve config",
+		port: SERVE_PORT
+	};
+	const hosts = /* @__PURE__ */ new Set([
+		"127.0.0.1",
+		"localhost",
+		"[::1]",
+		"0.0.0.0",
+		"[::]",
+		...ips.map((ip) => ip.includes(":") ? `[${ip}]` : ip)
+	]);
+	const configs = [value, ...isJsonObject(value.Foreground) ? Object.values(value.Foreground) : []].filter(isJsonObject);
+	const used = /* @__PURE__ */ new Set();
+	const funneled = /* @__PURE__ */ new Set();
+	const reaching = /* @__PURE__ */ new Set();
+	const routes = /* @__PURE__ */ new Set();
+	for (const config of configs) {
+		const tcp = isJsonObject(config.TCP) ? config.TCP : {};
+		for (const [port, listener] of Object.entries(tcp)) {
+			used.add(Number(port));
+			if (isJsonObject(listener) && reaches(listener.TCPForward, target, hosts)) reaching.add(Number(port));
+		}
+		for (const [hostPort, allowed] of Object.entries(isJsonObject(config.AllowFunnel) ? config.AllowFunnel : {})) if (allowed === true) funneled.add(portOf(hostPort));
+		for (const [hostPort, web] of Object.entries(isJsonObject(config.Web) ? config.Web : {})) {
+			const port = portOf(hostPort);
+			const listener = tcp[String(port)];
+			const https = isJsonObject(listener) && listener.HTTPS === true;
+			const handlers = isJsonObject(web) && isJsonObject(web.Handlers) ? web.Handlers : {};
+			for (const [mount, handler] of Object.entries(handlers)) {
+				const url = isJsonObject(handler) ? reaches(handler.Proxy, target, hosts) : null;
+				if (!url) continue;
+				reaching.add(port);
+				if (https && mount === "/" && url.protocol === "http:" && url.pathname === "/") routes.add(port);
+			}
+		}
+	}
+	let free = SERVE_PORT;
+	while (used.has(free) || funneled.has(free)) free++;
+	const exposed = [...reaching].filter((port) => funneled.has(port)).toSorted((a, b) => a - b);
+	if (exposed.length) return {
+		state: "funneled",
+		ports: exposed,
+		port: free
+	};
+	const tailnet = [...routes].toSorted((a, b) => a - b);
+	if (tailnet.length) return {
+		state: "routed",
+		port: tailnet.includes(SERVE_PORT) ? SERVE_PORT : tailnet[0]
+	};
+	return {
+		state: "missing",
+		port: free
+	};
+}
+function serveRoute(binary, env, target, ips, timeoutMs = TIMEOUT_MS) {
+	if (!binary) return Promise.resolve({
+		state: "unknown",
+		reason: "the tailscale command was not found",
+		port: SERVE_PORT
+	});
+	return new Promise((resolve) => {
+		execFile(binary, [
+			"serve",
+			"status",
+			"--json"
+		], {
+			env,
+			timeout: timeoutMs,
+			killSignal: "SIGKILL",
+			encoding: "utf8"
+		}, (error, stdout) => {
+			let route;
+			try {
+				route = error ? {
+					state: "unknown",
+					reason: error.killed ? "it timed out" : error.message.split("\n")[0],
+					port: SERVE_PORT
+				} : parseServeStatus(stdout.trim() ? JSON.parse(stdout) : {}, target, ips);
+			} catch {
+				route = {
+					state: "unknown",
+					reason: "it printed output that is not JSON",
+					port: SERVE_PORT
+				};
+			}
+			resolve(route);
+		});
+	});
+}
+function tailnetEndpoint(dnsName, port) {
+	return port === 443 ? `wss://${dnsName}` : `wss://${dnsName}:${port}`;
+}
+function serveCommand(port, target) {
+	return `tailscale serve --bg --https=${port} http://127.0.0.1:${target}`;
+}
+/** Reads `tailscale whois --json`: the peer's node (`Node.StableID`, `Node.Name`) and user (`UserProfile.LoginName`). */
+function parseWhois(value) {
+	if (!isJsonObject(value) || !isJsonObject(value.Node)) return null;
+	const { StableID, Name } = value.Node;
+	const login = isJsonObject(value.UserProfile) ? value.UserProfile.LoginName : void 0;
+	if (typeof StableID !== "string" || !StableID) return null;
+	return {
+		kind: "tailnet",
+		nodeId: StableID,
+		nodeName: typeof Name === "string" ? Name.replace(/\.$/, "") : "",
+		user: typeof login === "string" ? login : ""
+	};
+}
+function whois(binary, env, ip) {
+	if (!binary) return Promise.resolve(null);
+	return new Promise((resolve) => {
+		execFile(binary, [
+			"whois",
+			"--json",
+			ip
+		], {
+			env,
+			timeout: TIMEOUT_MS,
+			encoding: "utf8"
+		}, (error, stdout) => {
+			if (error) return resolve(null);
+			try {
+				resolve(parseWhois(JSON.parse(stdout)));
+			} catch {
+				resolve(null);
+			}
+		});
+	});
+}
+//#endregion
+//#region src/server.ts
+function healthTailscale(tailscale) {
+	if (tailscale.state === "running") return {
+		state: "running",
+		dnsName: tailscale.dnsName
+	};
+	if (tailscale.state === "not-running") return {
+		state: "not-running",
+		backendState: tailscale.backendState
+	};
+	return {
+		state: "unavailable",
+		reason: tailscale.reason
+	};
+}
+/** Only a request made to this Mac's loopback name, so a DNS-rebound web page cannot read the health payload. */
+function localHealthRequest(request) {
+	const host = request.headers.host?.replace(/:\d+$/, "");
+	return request.method === "GET" && request.url === "/health" && (host === "127.0.0.1" || host === "localhost") && peerAddress(request) === null;
+}
+const CLOSE_UNAUTHORIZED = 4401;
+const CLOSE_BAD_REQUEST = 4400;
+const CLOSE_AUTH_TIMEOUT = 4408;
+const MAX_PAYLOAD = 65536;
+const MAX_SUBSCRIPTIONS = 32;
+const MAX_COMMANDS = 4;
+const LOG_LIMITS = {
+	maxBufferedBytes: 4194304,
+	maxPendingRecords: 2e4
+};
+const FRAME_BUFFER_BYTES = 1048576;
+const FRAME_RETRY_MS = 100;
+const STATUS_FEED = {
+	args: [
+		"status",
+		"--watch",
+		"--json"
+	],
+	cwd: homedir(),
+	keep: 1,
+	label: "stim status --watch"
+};
+const HEALTH_ROUTE_TIMEOUT_MS = 1e3;
+const COMMAND_LIMITS = {
+	timeoutMs: 6e4,
+	maxOutputBytes: 33554432
+};
+const AUTH_REFUSALS = {
+	"pairing-unknown": {
+		code: "pairing-expired",
+		message: "This pairing code is unknown or was already used. Pair again."
+	},
+	"pairing-expired": {
+		code: "pairing-expired",
+		message: "This pairing code expired. Pair again."
+	},
+	"device-unknown": {
+		code: "unauthorized",
+		message: "This Mac does not recognize this device token. Pair again."
+	},
+	"node-mismatch": {
+		code: "unauthorized",
+		message: "This device token was paired from a different tailnet node."
+	}
+};
+function isLoopback(address) {
+	return address === "127.0.0.1" || address === "::1" || address === "::ffff:127.0.0.1";
+}
+/**
+* The tailnet address of the peer. `tailscale serve` proxies from loopback and names the peer in
+* X-Forwarded-For; a loopback connection without that header comes from this Mac.
+*/
+function peerAddress(request) {
+	const remote = request.socket.remoteAddress;
+	if (!isLoopback(remote)) return remote ?? null;
+	const forwarded = request.headers["x-forwarded-for"];
+	return (Array.isArray(forwarded) ? forwarded[0] : forwarded)?.split(",")[0]?.trim() || null;
+}
+var FailureLimiter = class {
+	failures = /* @__PURE__ */ new Map();
+	max;
+	windowMs;
+	constructor(max, windowMs) {
+		this.max = max;
+		this.windowMs = windowMs;
+	}
+	recent(key, now) {
+		const kept = (this.failures.get(key) ?? []).filter((at) => now - at < this.windowMs);
+		if (kept.length) this.failures.set(key, kept);
+		else this.failures.delete(key);
+		return kept;
+	}
+	blocked(key, now = Date.now()) {
+		return this.recent(key, now).length >= this.max;
+	}
+	record(key, now = Date.now()) {
+		this.failures.set(key, [...this.recent(key, now), now]);
+	}
+};
+function send(socket, message) {
+	if (socket.readyState === socket.OPEN) socket.send(JSON.stringify(message));
+}
+function requestId(value) {
+	return typeof value === "number" || typeof value === "string" ? value : null;
+}
+async function startServer(options) {
+	const limiter = new FailureLimiter(options.maxAuthFailures ?? 5, options.failureWindowMs ?? 6e4);
+	const authTimeoutMs = options.authTimeoutMs ?? 5e3;
+	const feeds = new FeedPool(options.stimCli, options.env);
+	const frameLimits = {
+		...DEFAULT_FRAME_LIMITS,
+		...options.frameLimits
+	};
+	const frames = new FramePool(options.env, frameLimits);
+	const running = /* @__PURE__ */ new Set();
+	const logLimits = {
+		...LOG_LIMITS,
+		...options.logLimits
+	};
+	const commandLimits = {
+		...COMMAND_LIMITS,
+		...options.commandLimits
+	};
+	const sessions = /* @__PURE__ */ new Map();
+	const wss = new WebSocketServer({
+		noServer: true,
+		maxPayload: MAX_PAYLOAD
+	});
+	mkdirSync(serverDir(), {
+		recursive: true,
+		mode: 448
+	});
+	let revocationCheck = null;
+	const watcher = watch(serverDir(), () => {
+		revocationCheck ??= setTimeout(() => {
+			revocationCheck = null;
+			const paired = new Set(readDevices().map((device) => device.id));
+			for (const [socket, device] of sessions) if (!paired.has(device.id)) socket.close(CLOSE_UNAUTHORIZED, "device revoked");
+		}, 50);
+	});
+	function connection(socket, peer) {
+		const limitKey = peer ?? "local";
+		const subscriptions = /* @__PURE__ */ new Map();
+		const commands = /* @__PURE__ */ new Set();
+		let nextSubscription = 1;
+		let device = null;
+		let queue = Promise.resolve();
+		const refuse = (id, code, message, closeCode) => {
+			if (!device) limiter.record(limitKey);
+			send(socket, {
+				id,
+				error: {
+					code,
+					message
+				}
+			});
+			socket.close(closeCode, code);
+		};
+		const timer = setTimeout(() => {
+			limiter.record(limitKey);
+			socket.close(CLOSE_AUTH_TIMEOUT, "authentication timeout");
+		}, authTimeoutMs);
+		async function identify() {
+			if (peer === null) return { kind: "local" };
+			return isIP(peer) ? whois(options.tailscale, options.env, peer) : null;
+		}
+		async function hello(id, params) {
+			if (device) return send(socket, {
+				id,
+				error: {
+					code: "already-authenticated",
+					message: "hello was already accepted."
+				}
+			});
+			const auth = isJsonObject(params) && isJsonObject(params.auth) ? params.auth : null;
+			if (!isJsonObject(params) || !auth || !isJsonObject(params.client)) return refuse(id, "bad-request", "hello needs params.client and params.auth.", CLOSE_BAD_REQUEST);
+			if (params.protocol !== 1) return refuse(id, "protocol-unsupported", `This server speaks protocol 1.`, CLOSE_BAD_REQUEST);
+			clearTimeout(timer);
+			const identity = await identify();
+			if (socket.readyState !== socket.OPEN) return;
+			if (!identity) return refuse(id, "identity-unavailable", `tailscale whois did not identify ${peer}.`, CLOSE_UNAUTHORIZED);
+			let outcome;
+			if (typeof auth.pairingToken === "string" && typeof auth.deviceName === "string" && auth.deviceName.trim()) outcome = spendPairingToken(auth.pairingToken, auth.deviceName.trim(), identity);
+			else if (typeof auth.deviceToken === "string") outcome = authenticateDevice(auth.deviceToken, identity);
+			else return refuse(id, "bad-request", "auth needs pairingToken and deviceName, or deviceToken.", CLOSE_BAD_REQUEST);
+			if (!outcome.ok) {
+				const { code, message } = AUTH_REFUSALS[outcome.reason];
+				return refuse(id, code, message, CLOSE_UNAUTHORIZED);
+			}
+			device = outcome.device;
+			sessions.set(socket, device);
+			send(socket, {
+				id,
+				result: {
+					protocol: 1,
+					server: {
+						name: options.name,
+						version: options.serverVersion,
+						stim: options.stimVersion
+					},
+					capabilities: device.capabilities,
+					device: {
+						id: device.id,
+						name: device.name
+					},
+					...outcome.deviceToken ? { deviceToken: outcome.deviceToken } : {}
+				}
+			});
+		}
+		function error(id, code, message) {
+			send(socket, {
+				id,
+				error: {
+					code,
+					message
+				}
+			});
+		}
+		function workspaceDir(id, workspace, required) {
+			if (workspace === void 0 && !required) return homedir();
+			if (typeof workspace !== "string") {
+				error(id, "bad-request", "params.workspace must be an environment path from a status payload.");
+				return null;
+			}
+			let registered;
+			try {
+				registered = Object.hasOwn(loadConfig()?.projects ?? {}, workspace);
+			} catch (cause) {
+				error(id, "stim-failed", cause.message);
+				return null;
+			}
+			if (!registered) {
+				error(id, "unknown-workspace", `${workspace} is not a Stim workspace on this Mac.`);
+				return null;
+			}
+			if (!existsSync(workspace)) {
+				error(id, "unknown-workspace", `${workspace} is registered but no longer exists on this Mac.`);
+				return null;
+			}
+			return workspace;
+		}
+		function openSubscription(id) {
+			if (subscriptions.size >= MAX_SUBSCRIPTIONS) {
+				error(id, "limit-exceeded", `A connection can hold ${MAX_SUBSCRIPTIONS} subscriptions.`);
+				return null;
+			}
+			const subscription = `s${nextSubscription++}`;
+			send(socket, {
+				id,
+				result: { subscription }
+			});
+			return subscription;
+		}
+		function subscribeStatus(id) {
+			const subscription = openSubscription(id);
+			if (!subscription) return;
+			const unsubscribe = feeds.subscribe(STATUS_FEED, {
+				item: (payload) => send(socket, {
+					event: "status",
+					subscription,
+					payload
+				}),
+				failed: (message) => {
+					subscriptions.delete(subscription);
+					send(socket, {
+						event: "error",
+						subscription,
+						error: {
+							code: "status-failed",
+							message
+						}
+					});
+				}
+			});
+			subscriptions.set(subscription, unsubscribe);
+		}
+		function subscribeLogs(id, params) {
+			const parsed = parseLogFilter(params);
+			if ("error" in parsed) return error(id, "bad-request", parsed.error);
+			const cwd = workspaceDir(id, parsed.filter.workspace, true);
+			if (!cwd) return;
+			const subscription = openSubscription(id);
+			if (!subscription) return;
+			const end = () => {
+				subscriptions.get(subscription)?.();
+				subscriptions.delete(subscription);
+			};
+			const batcher = new LogBatcher({
+				send: (records) => send(socket, {
+					event: "logs",
+					subscription,
+					records
+				}),
+				bufferedBytes: () => socket.bufferedAmount,
+				overflow: () => {
+					end();
+					send(socket, {
+						event: "error",
+						subscription,
+						error: {
+							code: "slow-client",
+							message: "This client fell behind the log stream. Subscribe again."
+						}
+					});
+				}
+			}, logLimits);
+			const unsubscribe = feeds.subscribe({
+				args: logArgs(parsed.filter, true),
+				cwd,
+				keep: parsed.filter.tail,
+				label: "stim logs --follow"
+			}, {
+				item: (record) => batcher.push(record),
+				failed: (message) => {
+					batcher.flush(true);
+					batcher.stop();
+					subscriptions.delete(subscription);
+					send(socket, {
+						event: "error",
+						subscription,
+						error: {
+							code: "logs-failed",
+							message
+						}
+					});
+				}
+			});
+			subscriptions.set(subscription, () => {
+				batcher.stop();
+				unsubscribe();
+			});
+		}
+		function subscribeFrames(id, params) {
+			const { workspace, platform, slot } = isJsonObject(params) ? params : {};
+			if (typeof workspace !== "string" || platform !== "ios" && platform !== "android") return error(id, "bad-request", "frames.subscribe needs params.workspace and params.platform (ios or android).");
+			if (slot !== void 0 && (typeof slot !== "string" || slot === "")) return error(id, "bad-request", "slot must be a slot name.");
+			if (!workspaceDir(id, workspace, true)) return;
+			const subscription = openSubscription(id);
+			if (!subscription) return;
+			const frameTarget = {
+				workspace,
+				platform,
+				...slot ? { slot } : {}
+			};
+			let attached = null;
+			let detach = null;
+			let pending = null;
+			let retry = null;
+			let ended = false;
+			const flush = () => {
+				retry = null;
+				if (!pending || ended) return;
+				if (socket.bufferedAmount > FRAME_BUFFER_BYTES) {
+					retry = setTimeout(flush, FRAME_RETRY_MS);
+					return;
+				}
+				const frame = pending;
+				pending = null;
+				send(socket, {
+					event: "frame",
+					subscription,
+					platform,
+					slot: slot ?? "default",
+					mime: "image/jpeg",
+					...frame
+				});
+			};
+			const cleanup = () => {
+				ended = true;
+				if (retry) clearTimeout(retry);
+				detach?.();
+				detach = null;
+				unsubscribeStatus?.();
+			};
+			const end = (message) => {
+				if (ended) return;
+				cleanup();
+				subscriptions.delete(subscription);
+				send(socket, {
+					event: "error",
+					subscription,
+					error: {
+						code: "frames-failed",
+						message
+					}
+				});
+			};
+			const listener = {
+				frame: (frame) => {
+					pending = frame;
+					if (!retry) flush();
+				},
+				delayed: (delayed) => {
+					if (!ended) send(socket, {
+						event: "frame-delayed",
+						subscription,
+						delayed
+					});
+				},
+				failed: end
+			};
+			let unsubscribeStatus = null;
+			unsubscribeStatus = feeds.subscribe(STATUS_FEED, {
+				item: (payload) => {
+					if (ended) return;
+					const resolved = ownedDevice(payload, frameTarget, attached);
+					if (typeof resolved === "string") return queueMicrotask(() => end(resolved));
+					if (deviceKey(resolved) === attached) return;
+					detach?.();
+					attached = deviceKey(resolved);
+					detach = frames.subscribe(resolved, listener);
+				},
+				failed: (message) => queueMicrotask(() => end(message))
+			});
+			subscriptions.set(subscription, cleanup);
+		}
+		function command(id, args, cwd, result) {
+			if (commands.size >= MAX_COMMANDS) return error(id, "limit-exceeded", `A connection can run ${MAX_COMMANDS} requests at a time.`);
+			const run = runStim(options.stimCli, options.env, args, cwd, commandLimits);
+			commands.add(run.cancel);
+			running.add(run.cancel);
+			(async () => {
+				const outcome = await run.outcome;
+				commands.delete(run.cancel);
+				running.delete(run.cancel);
+				if (!outcome.ok) return error(id, "stim-failed", outcome.message);
+				let value;
+				try {
+					value = result(outcome.stdout);
+				} catch {
+					return error(id, "stim-failed", `stim ${args[0]} printed output that is not JSON.`);
+				}
+				send(socket, {
+					id,
+					result: value
+				});
+			})();
+		}
+		function queryLogs(id, params) {
+			const parsed = parseLogFilter(params);
+			if ("error" in parsed) return error(id, "bad-request", parsed.error);
+			const cwd = workspaceDir(id, parsed.filter.workspace, true);
+			if (!cwd) return;
+			command(id, logArgs(parsed.filter, false), cwd, (stdout) => ({ records: stdout.split("\n").filter((line) => line.trim()).map((line) => JSON.parse(line)) }));
+		}
+		function workspaceCommand(id, method, params) {
+			if (params !== void 0 && !isJsonObject(params)) return error(id, "bad-request", "params must be an object.");
+			const cwd = workspaceDir(id, params?.workspace, false);
+			if (!cwd) return;
+			command(id, [method === "stats.get" ? "stats" : "settings", "--json"], cwd, (stdout) => {
+				const value = JSON.parse(stdout);
+				if (!isJsonObject(value)) throw new Error("not an object");
+				return value;
+			});
+		}
+		async function handle(raw) {
+			if (socket.readyState !== socket.OPEN) return;
+			let message;
+			try {
+				message = JSON.parse(raw);
+			} catch {
+				message = null;
+			}
+			const id = isJsonObject(message) ? requestId(message.id) : null;
+			if (!isJsonObject(message) || id === null || typeof message.method !== "string") {
+				if (device) return send(socket, {
+					id,
+					error: {
+						code: "bad-request",
+						message: "Expected {id, method, params}."
+					}
+				});
+				return refuse(id, "bad-request", "Expected {id, method, params}.", CLOSE_BAD_REQUEST);
+			}
+			if (message.method === "hello") return hello(id, message.params);
+			if (!device) return refuse(id, "unauthorized", "Send hello first.", CLOSE_UNAUTHORIZED);
+			if (message.method === "status.subscribe") return subscribeStatus(id);
+			if (message.method === "logs.subscribe") return subscribeLogs(id, message.params);
+			if (message.method === "logs.query") return queryLogs(id, message.params);
+			if (message.method === "frames.subscribe") return subscribeFrames(id, message.params);
+			if (message.method === "stats.get" || message.method === "settings.get") return workspaceCommand(id, message.method, message.params);
+			if (message.method === "unsubscribe") {
+				const name = isJsonObject(message.params) ? message.params.subscription : void 0;
+				const unsubscribe = typeof name === "string" ? subscriptions.get(name) : void 0;
+				if (!unsubscribe) return send(socket, {
+					id,
+					error: {
+						code: "unknown-subscription",
+						message: `No subscription ${String(name)}.`
+					}
+				});
+				subscriptions.delete(name);
+				unsubscribe();
+				return send(socket, {
+					id,
+					result: {}
+				});
+			}
+			send(socket, {
+				id,
+				error: {
+					code: "unknown-method",
+					message: `Unknown method ${message.method}.`
+				}
+			});
+		}
+		socket.on("message", (data) => {
+			const raw = data.toString();
+			queue = queue.then(() => handle(raw)).catch(() => socket.close(1011, "internal error"));
+		});
+		socket.on("close", () => {
+			clearTimeout(timer);
+			sessions.delete(socket);
+			for (const unsubscribe of subscriptions.values()) unsubscribe();
+			subscriptions.clear();
+			for (const cancel of commands) {
+				running.delete(cancel);
+				cancel();
+			}
+			commands.clear();
+		});
+	}
+	function upgrade(request, socket, head) {
+		const peer = peerAddress(request);
+		if (limiter.blocked(peer ?? "local")) {
+			socket.end("HTTP/1.1 429 Too Many Requests\r\nConnection: close\r\nContent-Length: 0\r\n\r\n");
+			return;
+		}
+		wss.handleUpgrade(request, socket, head, (ws) => connection(ws, peer));
+	}
+	const health = {
+		server: "stim-server",
+		name: options.name,
+		version: options.serverVersion,
+		stim: options.stimVersion,
+		protocol: 1,
+		stimHome: configDir(),
+		tailscale: healthTailscale(options.tailscaleState)
+	};
+	const answerHealth = async (response) => {
+		const tailscale = options.tailscaleState;
+		const route = tailscale.state === "running" && tailscale.dnsName ? await serveRoute(options.tailscale, options.env, addresses[0].port, tailscale.ips, HEALTH_ROUTE_TIMEOUT_MS) : void 0;
+		response.writeHead(200, { "content-type": "application/json" }).end(JSON.stringify({
+			...health,
+			route
+		}));
+	};
+	const servers = [];
+	const addresses = [];
+	const close = async () => {
+		watcher.close();
+		if (revocationCheck) clearTimeout(revocationCheck);
+		for (const client of wss.clients) client.terminate();
+		await Promise.all([
+			frames.close(),
+			feeds.close(),
+			...[...running].map((cancel) => cancel())
+		]);
+		wss.close();
+		await Promise.all(servers.map((server) => new Promise((resolve) => server.close(resolve))));
+	};
+	try {
+		for (const host of options.hosts) {
+			const server = createServer((request, response) => {
+				if (localHealthRequest(request)) {
+					answerHealth(response);
+					return;
+				}
+				response.writeHead(426, { "content-type": "text/plain" }).end("stim-server speaks WebSocket only.\n");
+			});
+			server.on("upgrade", upgrade);
+			servers.push(server);
+			await new Promise((resolve, reject) => {
+				server.once("error", reject);
+				server.listen(options.port, host, () => {
+					server.off("error", reject);
+					resolve();
+				});
+			});
+			addresses.push({
+				host,
+				port: server.address().port
+			});
+		}
+	} catch (error) {
+		await close();
+		throw error;
+	}
+	return {
+		addresses,
+		close
+	};
+}
+//#endregion
+//#region bin/stim-server.ts
+const DEFAULT_PORT = 7787;
+const USAGE = `Usage:
+  stim-server [--port <n>]          serve paired clients (default port ${DEFAULT_PORT})
+  stim-server pair [--port <n>] [--json]
+                                    print a single-use pairing payload for the QR code
+  stim-server devices [list] [--json]
+                                    list paired devices
+  stim-server devices revoke <id>   revoke a paired device`;
+const pkg = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
+function fail(message) {
+	console.error(`stim-server: ${message}`);
+	process.exit(1);
+}
+function tailscaleNote(tailscale) {
+	const remedy = `Remote clients cannot connect until Tailscale runs; then restart stim-server, which prints the \`tailscale serve\` command to run once.`;
+	if (tailscale.state === "not-running") return `Tailscale is not running (${tailscale.backendState}). ${remedy}`;
+	if (tailscale.state === "unavailable") return `Tailscale is unavailable: ${tailscale.reason}. ${remedy}`;
+	return null;
+}
+function routeNote(route, port) {
+	if (route.state === "missing") return `No \`tailscale serve\` route reaches port ${port}, so phones cannot connect yet. Run this once to serve it on a tailnet-only port: \`${serveCommand(route.port, port)}\``;
+	if (route.state === "unknown") return `Could not read \`tailscale serve status --json\` (${route.reason}); assuming stim-server is served on port ${route.port}.`;
+	if (route.state === "funneled") return `Tailscale Funnel is on for port ${route.ports.join(", ")}, which proxies to stim-server, so the server is reachable from the public internet. Remove that handler (see \`tailscale serve status\`), then serve stim-server on a tailnet-only port: \`${serveCommand(route.port, port)}\``;
+	return null;
+}
+function macName(tailscale) {
+	return tailscale.state === "running" && tailscale.hostName || hostname();
+}
+async function serve(port) {
+	const login = loginShellEnvironment();
+	if (!login) console.error("stim-server: could not read the login shell environment; using this process environment.");
+	const env = { ...login ?? process.env };
+	if (!process.env.STIM_HOME && env.STIM_HOME) process.env.STIM_HOME = env.STIM_HOME;
+	if (process.env.STIM_HOME) env.STIM_HOME = process.env.STIM_HOME;
+	const tailscaleBinary = findTailscale(env);
+	const tailscale = tailscaleStatus(tailscaleBinary, env);
+	const stim = bundledStim();
+	const hosts = ["127.0.0.1", ...tailscale.state === "running" ? tailscale.ips : []];
+	let server;
+	try {
+		server = await startServer({
+			name: macName(tailscale),
+			hosts,
+			port,
+			stimCli: stim.cli,
+			stimVersion: stim.version,
+			serverVersion: pkg.version,
+			env,
+			tailscale: tailscaleBinary,
+			tailscaleState: tailscale
+		});
+	} catch (error) {
+		if (error.code === "EADDRINUSE") fail(`port ${port} is in use; another stim-server may already be running. Pass --port to use another port.`);
+		throw error;
+	}
+	console.log(`stim-server ${pkg.version} (stim ${stim.version}, protocol 1)`);
+	for (const { host, port: bound } of server.addresses) console.log(`listening on ws://${host.includes(":") ? `[${host}]` : host}:${bound}`);
+	let note = tailscaleNote(tailscale);
+	if (tailscale.state === "running" && tailscale.dnsName) {
+		const route = await serveRoute(tailscaleBinary, env, port, tailscale.ips);
+		if (route.state !== "funneled") console.log(`tailnet endpoint: ${tailnetEndpoint(tailscale.dnsName, route.port)}`);
+		note = routeNote(route, port);
+		if (route.state === "funneled") note = `${note} Pairing is refused until then.`;
+	}
+	if (note) console.error(note);
+	const shutdown = () => {
+		server.close().then(() => process.exit(0));
+	};
+	process.on("SIGINT", shutdown);
+	process.on("SIGTERM", shutdown);
+	process.on("SIGHUP", shutdown);
+}
+async function pair(port, json) {
+	const binary = findTailscale(process.env);
+	const tailscale = tailscaleStatus(binary, process.env);
+	let endpoint = `ws://127.0.0.1:${port}`;
+	let note = tailscaleNote(tailscale);
+	if (note) note = `${note} The endpoint above only works on this Mac.`;
+	if (tailscale.state === "running" && tailscale.dnsName) {
+		const route = await serveRoute(binary, process.env, port, tailscale.ips);
+		if (route.state === "funneled") fail(`refusing to pair. ${routeNote(route, port)}`);
+		endpoint = tailnetEndpoint(tailscale.dnsName, route.port);
+		note = routeNote(route, port);
+	}
+	const { token, expiresAt } = createPairingToken();
+	const payload = {
+		v: 1,
+		name: macName(tailscale),
+		endpoint,
+		pairingToken: token
+	};
+	if (json) return void console.log(JSON.stringify({
+		qr: payload,
+		expiresAt
+	}));
+	console.log(JSON.stringify(payload));
+	console.error(`The pairing token is single use and expires at ${expiresAt}.`);
+	if (note) console.error(note);
+}
+function describe(device) {
+	const from = device.identity.kind === "local" ? "this Mac" : `${device.identity.nodeName || device.identity.nodeId}${device.identity.user ? ` (${device.identity.user})` : ""}`;
+	return `${device.id}  ${device.name}  from ${from}  paired ${device.pairedAt}  last seen ${device.lastSeenAt ?? "never"}`;
+}
+async function main() {
+	const { values, positionals } = parseArgs({
+		allowPositionals: true,
+		options: {
+			port: { type: "string" },
+			json: { type: "boolean" },
+			help: {
+				type: "boolean",
+				short: "h"
+			},
+			version: {
+				type: "boolean",
+				short: "V"
+			}
+		}
+	});
+	if (values.help) return void console.log(USAGE);
+	if (values.version) return void console.log(pkg.version);
+	const port = values.port === void 0 ? DEFAULT_PORT : Number(values.port);
+	if (!Number.isInteger(port) || port < 0 || port > 65535) fail(`--port must be a port number, got ${values.port}.`);
+	const [command, sub, arg, ...rest] = positionals;
+	if (command === void 0) return serve(port);
+	if (command === "pair" && sub === void 0) return pair(port, values.json === true);
+	if (command === "devices" && (sub === void 0 || sub === "list") && arg === void 0) {
+		const devices = readDevices();
+		if (values.json) {
+			const listed = devices.map(({ id, name, identity, pairedAt, lastSeenAt, capabilities }) => ({
+				id,
+				name,
+				identity,
+				pairedAt,
+				lastSeenAt,
+				capabilities
+			}));
+			console.log(JSON.stringify({ devices: listed }));
+			return;
+		}
+		if (!devices.length) console.log("No paired devices.");
+		for (const device of devices) console.log(describe(device));
+		return;
+	}
+	if (command === "devices" && sub === "revoke" && arg !== void 0 && rest.length === 0) {
+		if (!revokeDevice(arg)) fail(`no paired device ${arg}. Run \`stim-server devices\` to list them.`);
+		console.log(`Revoked ${arg}.`);
+		return;
+	}
+	fail(`unknown command.\n${USAGE}`);
+}
+await main();
+//#endregion
+export {};