@stim-cli/core 1.9.0 → 1.10.1

package/dist/state.mjs

@@ -0,0 +1,1269 @@
+import { E as withDirLock, S as workspaceStateDir, b as workspaceName, l as configDir, m as rotatedLogPath } from "./core-CJWLJIr6.mjs";
+import { closeSync, existsSync, mkdirSync, openSync, readFileSync, readSync, readdirSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { isAbsolute, join, relative, resolve, sep } from "node:path";
+import { StringDecoder } from "node:string_decoder";
+//#region state/json-file.ts
+function readJsonFile(path) {
+	return JSON.parse(readFileSync(path, "utf-8"));
+}
+function isJsonObject(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function readJsonObject(path) {
+	try {
+		const value = readJsonFile(path);
+		return isJsonObject(value) ? value : null;
+	} catch {
+		return null;
+	}
+}
+//#endregion
+//#region state/paths.ts
+function getConfigPath() {
+	return join(configDir(), "config.json");
+}
+function configLockPath() {
+	return join(configDir(), "config.lock");
+}
+function workspaceMetadataFile(projectRoot) {
+	return join(workspaceStateDir(projectRoot), "workspace.json");
+}
+function workspaceLogsDir(projectRoot) {
+	return join(workspaceStateDir(projectRoot), "logs");
+}
+function workspaceLogErrorIndex(projectRoot) {
+	return join(workspaceStateDir(projectRoot), "log-error-index.json");
+}
+function workspaceDerivedData(projectRoot) {
+	return join(workspaceStateDir(projectRoot), "derived-data");
+}
+function workspaceGradleBuild(projectRoot) {
+	return join(workspaceStateDir(projectRoot), "gradle-build");
+}
+function supervisorPidFile(projectRoot) {
+	return join(workspaceStateDir(projectRoot), "supervisor.pid");
+}
+function workspaceStateFile(projectRoot) {
+	return join(workspaceStateDir(projectRoot), "state.json");
+}
+function workspaceStateLock(projectRoot) {
+	return join(workspaceStateDir(projectRoot), "state.lock");
+}
+function supervisorLogFile(projectRoot) {
+	return join(workspaceLogsDir(projectRoot), "supervisor.log");
+}
+function emulatorLogFile(projectRoot) {
+	return join(workspaceLogsDir(projectRoot), "emulator.log");
+}
+function sharedCompilationCache() {
+	return join(configDir(), "compilation-cache");
+}
+function sharedCcache() {
+	return join(configDir(), "ccache");
+}
+function sharedGradle() {
+	return join(configDir(), "gradle");
+}
+function sharedPods() {
+	return join(configDir(), "pods");
+}
+function createdDevicesFile() {
+	return join(configDir(), "created-devices.json");
+}
+function createdDevicesLock() {
+	return join(configDir(), "created-devices.lock");
+}
+/** The EAS session ledger lives under the real home directory, never under STIM_HOME. */
+function easMachineStateRoot() {
+	return join(homedir(), ".stim", "machine", "eas");
+}
+function easSessionLedgerFile(root = easMachineStateRoot()) {
+	return join(root, "sessions.json");
+}
+function easSessionLedgerLock(root = easMachineStateRoot()) {
+	return join(root, "ledger.lock");
+}
+//#endregion
+//#region state/config.ts
+function withConfigLock(fn) {
+	return withDirLock(configLockPath(), fn, { ensureParent: () => {
+		const dir = configDir();
+		if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+	} });
+}
+function configCorruptRepair(path = getConfigPath()) {
+	return `Repair the file, or move it aside to start over: mv "${path}" "${path}.broken"`;
+}
+function configCorrupt(reason, path = getConfigPath()) {
+	const corrupt = /* @__PURE__ */ new Error(`Stim config at ${path} ${reason}\nIt holds the records of the simulators and emulators Stim owns, so it is never reset automatically.
+` + configCorruptRepair(path));
+	corrupt.code = "STIM_CONFIG_CORRUPT";
+	return corrupt;
+}
+function loadConfig() {
+	const p = getConfigPath();
+	if (!existsSync(p)) return null;
+	let parsed;
+	try {
+		parsed = readJsonFile(p);
+	} catch (err) {
+		if (!(err instanceof SyntaxError)) throw err;
+		throw configCorrupt(`is not valid JSON: ${err.message}`, p);
+	}
+	return configFromJson(parsed, p);
+}
+function configFromJson(value, path) {
+	if (!isJsonObject(value)) throw configCorrupt(`is not a JSON object: ${JSON.stringify(value)}`, path);
+	return {
+		...value,
+		projects: registryFromJson(value, "projects", path),
+		repos: registryFromJson(value, "repos", path)
+	};
+}
+/**
+* An array or scalar container swallows every write silently: `JSON.stringify` drops a string key set on
+* an array, so the record is gone by the time the file is written. Absent or null is read as empty; an
+* unusable container or entry is refused.
+*/
+function registryFromJson(config, key, path) {
+	const value = config[key];
+	if (value === void 0 || value === null) return {};
+	if (!isJsonObject(value)) throw configCorrupt(`has a ${key} that is not an object: ${JSON.stringify(value)}`, path);
+	const registry = {};
+	for (const [name, entry] of Object.entries(value)) {
+		if (!isJsonObject(entry)) throw configCorrupt(`has a ${key} entry ${JSON.stringify(name)} that is not an object: ${JSON.stringify(entry)}`, path);
+		registry[name] = entry;
+	}
+	return registry;
+}
+function getProject(projectPath) {
+	return loadConfig()?.projects?.[projectPath] || null;
+}
+function getConcurrencyLimits({ env = process.env } = {}) {
+	const c = loadConfig()?.concurrency || {};
+	return {
+		maxBuilds: resolveLimit(env.STIM_MAX_BUILDS, c.maxBuilds),
+		maxDevices: resolveLimit(env.STIM_MAX_DEVICES, c.maxDevices)
+	};
+}
+function resolveLimit(envVal, cfgVal) {
+	const raw = envVal !== void 0 && envVal !== null && envVal !== "" ? Number(envVal) : typeof cfgVal === "number" ? cfgVal : NaN;
+	if (!Number.isFinite(raw) || raw <= 0) return 0;
+	return Math.floor(raw);
+}
+function getProjectSettings(projectPath) {
+	return getProject(projectPath)?.settings || {};
+}
+function getProjectSetting(projectPath, dottedKey) {
+	return readNested(getProjectSettings(projectPath), dottedKey);
+}
+function getRepoSettings(gitCommonDir) {
+	return loadConfig()?.repos?.[gitCommonDir]?.settings || {};
+}
+function readNested(obj, dottedKey) {
+	if (!obj) return void 0;
+	const keys = dottedKey.split(".");
+	let cur = obj;
+	for (const k of keys) {
+		if (cur == null || typeof cur !== "object") return void 0;
+		cur = cur[k];
+	}
+	return cur;
+}
+function isPathPrefix(prefix, path) {
+	const head = comparablePath(prefix);
+	const candidate = comparablePath(path);
+	if (head === candidate) return true;
+	return candidate.startsWith(head.endsWith("/") ? head : `${head}/`);
+}
+function comparablePath(path) {
+	return sep === "/" ? path : path.replaceAll(sep, "/");
+}
+function findEnclosingWorktreeRoot(projectPath) {
+	const cfg = loadConfig();
+	if (!cfg?.projects) return null;
+	let best = null;
+	for (const [path, proj] of Object.entries(cfg.projects)) {
+		if (!proj?.worktreeRoot) continue;
+		if (!isPathPrefix(path, projectPath)) continue;
+		if (!best || path.length > best.length) best = path;
+	}
+	return best;
+}
+function allMetroPorts() {
+	const cfg = loadConfig();
+	if (!cfg?.projects) return [];
+	return Object.values(cfg.projects).map((p) => p.metroPort).filter((p) => typeof p === "number");
+}
+function findProjectByMetroPort(port) {
+	const cfg = loadConfig();
+	for (const [path, proj] of Object.entries(cfg?.projects || {})) if (proj.metroPort === port) return path;
+	return null;
+}
+//#endregion
+//#region state/ledgers.ts
+function ids(value) {
+	return Array.isArray(value) ? value.filter((entry) => typeof entry === "string" && entry !== "") : [];
+}
+function readCreatedDevices() {
+	try {
+		const parsed = JSON.parse(readFileSync(createdDevicesFile(), "utf8"));
+		return {
+			ios: new Set(ids(parsed?.ios)),
+			android: new Set(ids(parsed?.android))
+		};
+	} catch {
+		return {
+			ios: /* @__PURE__ */ new Set(),
+			android: /* @__PURE__ */ new Set()
+		};
+	}
+}
+/** Returns the claim normalized to canonical paths, or null when it is not a valid claim for `id`. */
+function validEasSessionClaim(id, value) {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+	const claim = value;
+	if (claim.sessionId !== id) return null;
+	if (typeof claim.name !== "string" || !claim.name.startsWith("stim-")) return null;
+	if (claim.platform !== "ios" && claim.platform !== "android") return null;
+	if (typeof claim.workspaceRoot !== "string" || !isAbsolute(claim.workspaceRoot)) return null;
+	if (typeof claim.workspaceHome !== "string" || !isAbsolute(claim.workspaceHome)) return null;
+	if (typeof claim.stateFile !== "string" || !isAbsolute(claim.stateFile)) return null;
+	const workspaceRoot = resolve(claim.workspaceRoot);
+	const workspaceHome = resolve(claim.workspaceHome);
+	const stateFile = resolve(claim.stateFile);
+	const stateRelative = relative(workspaceHome, stateFile);
+	if (!stateRelative || stateRelative.startsWith("..") || isAbsolute(stateRelative)) return null;
+	if (stateFile !== join(workspaceHome, "workspaces", workspaceName(workspaceRoot), "state.json")) return null;
+	return {
+		sessionId: id,
+		name: claim.name,
+		platform: claim.platform,
+		workspaceRoot,
+		workspaceHome,
+		stateFile
+	};
+}
+function readEasSessionLedger(root = easMachineStateRoot()) {
+	const file = easSessionLedgerFile(root);
+	if (!existsSync(file)) return {
+		claims: /* @__PURE__ */ new Map(),
+		notice: null,
+		safe: true
+	};
+	let parsed;
+	try {
+		parsed = JSON.parse(readFileSync(file, "utf-8"));
+	} catch (error) {
+		return {
+			claims: /* @__PURE__ */ new Map(),
+			notice: `EAS ownership ledger ${file} is unreadable: ${error.message}`,
+			safe: false
+		};
+	}
+	if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return {
+		claims: /* @__PURE__ */ new Map(),
+		notice: `EAS ownership ledger ${file} is malformed.`,
+		safe: false
+	};
+	const ledger = parsed;
+	if (ledger.version !== 1 || !ledger.claims || typeof ledger.claims !== "object" || Array.isArray(ledger.claims)) return {
+		claims: /* @__PURE__ */ new Map(),
+		notice: `EAS ownership ledger ${file} is malformed.`,
+		safe: false
+	};
+	const claims = /* @__PURE__ */ new Map();
+	for (const [id, value] of Object.entries(ledger.claims)) {
+		const claim = validEasSessionClaim(id, value);
+		if (!claim) return {
+			claims: /* @__PURE__ */ new Map(),
+			notice: `EAS ownership ledger ${file} is malformed.`,
+			safe: false
+		};
+		claims.set(id, claim);
+	}
+	return {
+		claims,
+		notice: null,
+		safe: true
+	};
+}
+//#endregion
+//#region state/ndjson.ts
+const LEVELS = [
+	"debug",
+	"info",
+	"warn",
+	"error",
+	"fatal"
+];
+const SOURCES = [
+	"metro",
+	"client",
+	"device",
+	"build"
+];
+function levelRank(level) {
+	const i = LEVELS.indexOf(level);
+	return i < 0 ? 0 : i;
+}
+function parseNdjsonLine(line) {
+	if (typeof line !== "string") return null;
+	const trimmed = line.trim();
+	if (!trimmed) return null;
+	let value;
+	try {
+		value = JSON.parse(trimmed);
+	} catch {
+		return null;
+	}
+	if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+	return value;
+}
+function parseNdjsonText(text) {
+	if (typeof text !== "string" || text === "") return [];
+	const out = [];
+	const lines = text.split("\n");
+	lines.pop();
+	for (const line of lines) {
+		const record = parseNdjsonLine(line);
+		if (record) out.push(record);
+	}
+	return out;
+}
+function readNdjsonGenerations(file) {
+	const out = [];
+	for (const path of [rotatedLogPath(file), file]) {
+		let text;
+		try {
+			text = readFileSync(path, "utf-8");
+		} catch {
+			continue;
+		}
+		for (const record of parseNdjsonText(text)) out.push(record);
+	}
+	return out;
+}
+//#endregion
+//#region state/logs-query.ts
+const SINCE_UNITS = {
+	s: 1e3,
+	m: 6e4,
+	h: 36e5
+};
+const SINCE_FORMS = "30s, 5m, 2h";
+function parseSince(text) {
+	if (typeof text !== "string") return { error: `Invalid --since value ${JSON.stringify(text)}. Use a count and a unit, e.g. ${SINCE_FORMS}.` };
+	const m = /^(\d+)\s*([smh])$/i.exec(text.trim());
+	if (!m) return { error: `Invalid --since value "${text}". Use a count and a unit, e.g. ${SINCE_FORMS}.` };
+	const unit = (m[2] ?? "").toLowerCase();
+	return { ms: parseInt(m[1] ?? "", 10) * SINCE_UNITS[unit] };
+}
+function compileGrep(pattern) {
+	if (pattern instanceof RegExp) return { re: pattern };
+	try {
+		return { re: new RegExp(String(pattern)) };
+	} catch (err) {
+		return { error: `Invalid --grep pattern "${pattern}": ${err.message}` };
+	}
+}
+const ERROR_SOURCES = [
+	"metro",
+	"client",
+	"build"
+];
+function markerWindow(records) {
+	let launchTs = null;
+	let bundleTs = null;
+	for (const r of records) {
+		if (r?.marker !== true) continue;
+		const ts = tsOf(r);
+		if (ts === null) continue;
+		if (r.src === "metro") {
+			if (bundleTs === null || ts > bundleTs) bundleTs = ts;
+		} else if (launchTs === null || ts > launchTs) launchTs = ts;
+	}
+	return {
+		launchTs,
+		bundleTs
+	};
+}
+function recordMatches(record, criteria = {}) {
+	if (!record) return false;
+	if (criteria.slot !== void 0 && (record.slot ?? "default") !== criteria.slot) return false;
+	const { sources, minLevel, grep, sinceTs, errorsOnly, markerTs, bundleMarkerTs } = criteria;
+	if (sources && sources.length > 0 && !sources.includes(record.src) && !(criteria.includeNativeCrashes && record.src === "device" && record.event === "native_crash")) return false;
+	if (minLevel && levelRank(record.level) < levelRank(minLevel)) return false;
+	if (errorsOnly) {
+		if (record.level !== "error" && record.level !== "fatal") return false;
+		if (typeof markerTs === "number") {
+			const ts = tsOf(record);
+			if (ts === null || ts <= markerTs) return false;
+		}
+		if (typeof bundleMarkerTs === "number" && record.src === "metro") {
+			const ts = tsOf(record);
+			if (ts === null || ts < bundleMarkerTs) return false;
+		}
+	}
+	if (typeof sinceTs === "number") {
+		const ts = tsOf(record);
+		if (ts === null || ts < sinceTs) return false;
+	}
+	if (grep) {
+		const re = grep instanceof RegExp ? grep : compileGrep(grep).re;
+		if (!re || String(record.msg ?? "").search(re) === -1) return false;
+	}
+	return true;
+}
+function buildCriteria({ slot, sources, minLevel, since, grep, errorsOnly, markerTs, bundleMarkerTs, now } = {}) {
+	const criteria = {
+		...slot === void 0 ? {} : { slot },
+		errorsOnly: Boolean(errorsOnly),
+		includeNativeCrashes: Boolean(errorsOnly && !sources?.length)
+	};
+	if (sources && sources.length > 0) criteria.sources = sources;
+	else if (criteria.errorsOnly) criteria.sources = ERROR_SOURCES;
+	if (minLevel) criteria.minLevel = minLevel;
+	if (typeof markerTs === "number") criteria.markerTs = markerTs;
+	if (typeof bundleMarkerTs === "number") criteria.bundleMarkerTs = bundleMarkerTs;
+	if (since !== void 0 && since !== null && since !== "") {
+		const parsed = parseSince(since);
+		if (parsed.error) throw new Error(parsed.error);
+		criteria.sinceTs = (typeof now === "number" ? now : Date.now()) - parsed.ms;
+	}
+	if (grep !== void 0 && grep !== null && grep !== "") {
+		const compiled = compileGrep(grep);
+		if (compiled.error) throw new Error(compiled.error);
+		criteria.grep = compiled.re;
+	}
+	return criteria;
+}
+function logFiles(dir) {
+	let entries;
+	try {
+		entries = readdirSync(dir, { withFileTypes: true });
+	} catch {
+		return [];
+	}
+	return entries.filter((e) => e.isFile() && e.name.endsWith(".ndjson")).map((e) => e.name).toSorted();
+}
+function fileSizes(dir) {
+	const sizes = {};
+	for (const name of logFiles(dir)) try {
+		sizes[name] = statSync(join(dir, name)).size;
+	} catch {}
+	return sizes;
+}
+function readLogRecords(dir, include = () => true) {
+	const all = [];
+	for (const name of logFiles(dir).filter(include)) for (const record of readNdjsonGenerations(join(dir, name))) all.push(record);
+	return sortByTs(all);
+}
+function isExpoErrorContext(record, event) {
+	if (record.src !== "metro" || record.raw !== true || record.event !== event || typeof record.msg !== "string") return false;
+	return /^Code: \S/.test(record.msg) || /^\s*>?\s*\d+\s*\|/.test(record.msg) || /^\s*\|\s*\^/.test(record.msg) || /^Call Stack$/.test(record.msg) || /^\s+.+\([^()]+:\d+:\d+\)\s*$/.test(record.msg) || /^\s+at\s+\S+:\d+:\d+\s*$/.test(record.msg);
+}
+function attachExpoErrorContext(all, matched) {
+	return matched.map((record) => {
+		if (record.src !== "metro" || record.raw !== true || record.level !== "error" && record.level !== "fatal" || typeof record.msg !== "string") return record;
+		const index = all.findIndex((entry) => entry.ts === record.ts && entry.src === record.src && entry.msg === record.msg && entry.event === record.event);
+		if (index === -1) return record;
+		const context = [];
+		for (let i = index + 1; i < all.length; i += 1) {
+			const next = all[i];
+			if (next.src !== "metro") continue;
+			if (!isExpoErrorContext(next, record.event)) break;
+			context.push(next.msg);
+		}
+		return context.length > 0 ? {
+			...record,
+			msg: [record.msg, ...context].join("\n")
+		} : record;
+	});
+}
+function includeBareErrorContext(all, matched, launchTs, sinceTs) {
+	if (!matched.some((record) => record.src === "client" && (record.level === "error" || record.level === "fatal"))) return matched;
+	const renderedContext = [];
+	for (const record of all) {
+		if (record.src !== "client" || record.event !== "client_symbolication") continue;
+		const ts = tsOf(record);
+		if (launchTs !== null && (ts === null || ts <= launchTs)) continue;
+		if (sinceTs !== void 0 && (ts === null || ts < sinceTs)) continue;
+		renderedContext.push({
+			...record,
+			msg: `Metro symbolication context (not correlated to a specific client error)\n${String(record.msg ?? "")}`,
+			errorContext: true
+		});
+	}
+	return sortByTs([...matched, ...renderedContext]);
+}
+function launchMarkersBySlot(records) {
+	const markers = /* @__PURE__ */ new Map();
+	for (const record of records) {
+		if (record.marker !== true || record.src === "metro") continue;
+		const ts = tsOf(record);
+		const slot = record.slot ?? "default";
+		if (ts !== null && ts > (markers.get(slot) ?? -Infinity)) markers.set(slot, ts);
+	}
+	return markers;
+}
+function queryLogs({ slot, dir, records, sources, minLevel, since, grep, tail, errorsOnly, errorContext, now } = {}) {
+	const all = (records ?? readLogRecords(dir)).filter((record) => slot === void 0 || (record.slot ?? "default") === slot);
+	if (all.length === 0) return [];
+	const { launchTs, bundleTs } = errorsOnly ? markerWindow(all) : {
+		launchTs: null,
+		bundleTs: null
+	};
+	const criteria = buildCriteria({
+		slot,
+		sources,
+		minLevel,
+		since,
+		grep,
+		errorsOnly,
+		now,
+		markerTs: launchTs === null ? void 0 : launchTs,
+		bundleMarkerTs: bundleTs === null ? void 0 : bundleTs
+	});
+	const slotMarkers = launchMarkersBySlot(all);
+	let matched = all.filter((record) => recordMatches(record, {
+		...criteria,
+		markerTs: record.src === "metro" || record.src === "client" ? criteria.markerTs : slotMarkers.get(record.slot ?? "default")
+	}));
+	if (typeof tail === "number" && tail >= 0 && matched.length > tail) matched = matched.slice(matched.length - tail);
+	return errorContext ? includeBareErrorContext(all, attachExpoErrorContext(all, matched), launchTs, criteria.sinceTs) : matched;
+}
+function tailRead(prev, size) {
+	const state = prev && typeof prev.offset === "number" ? prev : {
+		offset: 0,
+		partial: ""
+	};
+	if (size < state.offset) return {
+		start: 0,
+		prev: {
+			offset: 0,
+			partial: ""
+		}
+	};
+	return {
+		start: state.offset,
+		prev: state
+	};
+}
+function advanceTail(prev, chunk, size) {
+	const lines = ((prev && typeof prev.partial === "string" ? prev.partial : "") + (chunk || "")).split("\n");
+	const partial = lines.pop();
+	const records = [];
+	for (const line of lines) {
+		const record = parseNdjsonLine(line);
+		if (record) records.push(record);
+	}
+	return {
+		state: {
+			offset: size,
+			partial
+		},
+		records
+	};
+}
+function followLogs({ dir, onRecord, criteria = {}, intervalMs = 500, offsets = null }) {
+	const state = /* @__PURE__ */ new Map();
+	const decoders = /* @__PURE__ */ new Map();
+	for (const [name, size] of Object.entries(offsets || fileSizes(dir))) {
+		state.set(name, {
+			offset: size,
+			partial: ""
+		});
+		decoders.set(name, new StringDecoder("utf8"));
+	}
+	function emit(records) {
+		for (const record of records) if (recordMatches(record, criteria)) onRecord(record);
+	}
+	function drainRotated(name, entry) {
+		const path = rotatedLogPath(join(dir, name));
+		let size;
+		try {
+			size = statSync(path).size;
+		} catch {
+			return;
+		}
+		const decoder = decoders.get(name) ?? new StringDecoder("utf8");
+		emit(advanceTail(entry, readChunk(path, decoder, entry.offset, size) + decoder.end(), size).records);
+	}
+	function pollFile(name) {
+		const path = join(dir, name);
+		const size = statSync(path).size;
+		const entry = state.get(name);
+		if (entry && size < entry.offset) drainRotated(name, entry);
+		const { start, prev } = tailRead(entry, size);
+		if (prev !== entry) decoders.set(name, new StringDecoder("utf8"));
+		if (!decoders.has(name)) decoders.set(name, new StringDecoder("utf8"));
+		const next = advanceTail(prev, readChunk(path, decoders.get(name), start, size), size);
+		state.set(name, next.state);
+		emit(next.records);
+	}
+	function poll() {
+		for (const name of logFiles(dir)) try {
+			pollFile(name);
+		} catch {}
+	}
+	const timer = setInterval(poll, intervalMs);
+	return function stop() {
+		clearInterval(timer);
+	};
+}
+function readChunk(path, decoder, start, size) {
+	if (size <= start) return "";
+	const fd = openSync(path, "r");
+	try {
+		const buf = Buffer.allocUnsafe(size - start);
+		const read = readSync(fd, buf, 0, size - start, start);
+		return decoder.write(buf.subarray(0, read));
+	} finally {
+		closeSync(fd);
+	}
+}
+function tsOf(record) {
+	return typeof record?.ts === "number" && Number.isFinite(record.ts) ? record.ts : null;
+}
+function sortByTs(records) {
+	return records.toSorted((a, b) => {
+		const ta = tsOf(a);
+		const tb = tsOf(b);
+		if (ta === null && tb === null) return 0;
+		if (ta === null) return 1;
+		if (tb === null) return -1;
+		return ta - tb;
+	});
+}
+//#endregion
+//#region state/settings-registry.ts
+const ANDROID_COMPILER_CACHE_CHOICES = [
+	"auto",
+	"ccache",
+	"cas",
+	"none"
+];
+const ANDROID_PCH_CHOICES = [
+	"auto",
+	"on",
+	"off"
+];
+const TUNNEL_MODES = [
+	"auto",
+	"off",
+	"expo",
+	"cloudflared",
+	"ngrok"
+];
+const SETTING_SCOPES = [
+	"machine",
+	"workspace",
+	"repo",
+	"committed"
+];
+const REMOTE_DEVICE_BACKENDS = ["proxy", "eas"];
+const IOS_SIMULATOR_APPS = [
+	"xcode",
+	"siniulator",
+	"stim-desktop"
+];
+const PROJECT = [
+	"workspace",
+	"repo",
+	"committed"
+];
+const EVERY = [
+	"machine",
+	"workspace",
+	"repo",
+	"committed"
+];
+const MACHINE = ["machine"];
+const STRING = { kind: "string" };
+const PATH = { kind: "path" };
+const ABSOLUTE_PATH = {
+	kind: "path",
+	absolute: true
+};
+const RELATIVE_PATH = {
+	kind: "path",
+	relative: true
+};
+const BOOLEAN = { kind: "boolean" };
+const OBJECT = { kind: "object" };
+const REMOTE = {
+	kind: "choice",
+	choices: REMOTE_DEVICE_BACKENDS
+};
+const PARKED_MAX = {
+	kind: "number",
+	integer: true,
+	minimum: 0
+};
+const CAPACITY = {
+	kind: "number",
+	integer: true,
+	minimum: 0
+};
+const GIGABYTES = {
+	kind: "number",
+	minimum: 0
+};
+function optimization(key, description, type = BOOLEAN) {
+	return {
+		key: `optimizations.${key}`,
+		type,
+		scopes: EVERY,
+		description,
+		...type.kind === "boolean" ? { default: true } : {}
+	};
+}
+const SETTINGS = [
+	optimization("buildCache", "Read and write native build artifacts"),
+	optimization("remoteBuildCache", "Use remote artifact providers"),
+	optimization("releaseBundleSwap", "Swap current JS into cached release builds"),
+	optimization("metroSharedCache", "Append Stim's shared Metro cache store"),
+	optimization("metroWarmup", "Prefetch the development bundle during ios and android"),
+	optimization("ios.compilationCache", "Xcode compilation caching"),
+	{
+		key: "optimizations.ios.swiftCompilationCache",
+		type: BOOLEAN,
+		scopes: EVERY,
+		description: "Swift compilation caching; unset detects toolchain support"
+	},
+	optimization("ios.prefixMapping", "Clang source and DerivedData prefix mapping"),
+	{
+		...optimization("android.compilerCache", "Android compiler cache backend", {
+			kind: "choice",
+			choices: ANDROID_COMPILER_CACHE_CHOICES
+		}),
+		default: "auto"
+	},
+	{
+		...optimization("android.casToolchain", "Absolute path to the Android CAS toolchain manifest", ABSOLUTE_PATH),
+		env: "STIM_ANDROID_CAS_TOOLCHAIN"
+	},
+	{
+		...optimization("android.pch", "Android precompiled headers", {
+			kind: "choice",
+			choices: ANDROID_PCH_CHOICES
+		}),
+		default: "auto"
+	},
+	optimization("android.gradleBuildCache", "Gradle build cache"),
+	optimization("android.targetAbiOnly", "Narrow Debug builds to the device ABI"),
+	{
+		key: "ios.deviceType",
+		type: STRING,
+		scopes: PROJECT,
+		description: "Simulator model for owned simulators"
+	},
+	{
+		key: "ios.runtime",
+		type: STRING,
+		scopes: PROJECT,
+		description: "iOS runtime owned simulators are created on"
+	},
+	{
+		key: "ios.configuration",
+		type: STRING,
+		scopes: PROJECT,
+		default: "Debug",
+		description: "Xcode configuration to build, such as Debug or Release"
+	},
+	{
+		key: "ios.remote",
+		type: REMOTE,
+		scopes: PROJECT,
+		description: "Default remote backend for iOS"
+	},
+	{
+		key: "ios.simslimProfile",
+		type: RELATIVE_PATH,
+		scopes: PROJECT,
+		description: "SimSlim JSON profile under the app"
+	},
+	{
+		key: "ios.signingIdentity",
+		type: STRING,
+		scopes: PROJECT,
+		description: "Keychain identity used to re-seal a device build"
+	},
+	{
+		key: "ios.signingIdentitySha1",
+		type: {
+			kind: "string",
+			pattern: "^[0-9A-Fa-f]{40}$",
+			patternHelp: "a 40-character hex SHA-1 hash"
+		},
+		scopes: PROJECT,
+		description: "SHA-1 of the signing identity, when two share a name"
+	},
+	{
+		key: "ios.lanHost",
+		type: {
+			kind: "string",
+			pattern: "^(?!-)[A-Za-z0-9-]+(?:\\.(?!-)[A-Za-z0-9-]+)*$",
+			patternHelp: "a bare address or hostname, never a URL, scheme, or port"
+		},
+		scopes: PROJECT,
+		description: "Address a phone uses to reach this workspace's Metro"
+	},
+	{
+		key: "android.systemImage",
+		type: STRING,
+		scopes: PROJECT,
+		description: "SDK system image for owned AVDs"
+	},
+	{
+		key: "android.dataPartitionSizeGb",
+		type: {
+			kind: "number",
+			integer: true,
+			minimum: 6,
+			maximum: 16384
+		},
+		scopes: PROJECT,
+		default: 8,
+		description: "Data partition size of a new owned AVD, in GiB"
+	},
+	{
+		key: "android.avdConfigFile",
+		type: RELATIVE_PATH,
+		scopes: PROJECT,
+		description: "AVD config.ini fragment under the app"
+	},
+	{
+		key: "android.avdConfig",
+		type: OBJECT,
+		scopes: PROJECT,
+		description: "Validated AVD config values"
+	},
+	{
+		key: "android.variant",
+		type: STRING,
+		scopes: PROJECT,
+		description: "Gradle build variant"
+	},
+	{
+		key: "android.keystore",
+		type: PATH,
+		scopes: PROJECT,
+		description: "Keystore a re-packed release APK is signed with"
+	},
+	{
+		key: "android.keystorePassword",
+		type: STRING,
+		scopes: PROJECT,
+		sensitive: true,
+		description: "Keystore password, or an apksigner env: or file: reference"
+	},
+	{
+		key: "android.remote",
+		type: REMOTE,
+		scopes: PROJECT,
+		description: "Default remote backend for Android"
+	},
+	{
+		key: "metro.tunnel",
+		type: {
+			kind: "choice",
+			choices: TUNNEL_MODES
+		},
+		scopes: PROJECT,
+		default: "auto",
+		description: "How a remote device reaches Metro"
+	},
+	{
+		key: "metro.ngrokUrl",
+		type: STRING,
+		scopes: PROJECT,
+		description: "Stable ngrok URL for the managed tunnel"
+	},
+	{
+		key: "metro.publicUrl",
+		type: STRING,
+		scopes: PROJECT,
+		description: "Existing public Metro URL"
+	},
+	{
+		key: "metro.warmupUrl.ios",
+		type: { kind: "bundle-url" },
+		scopes: PROJECT,
+		description: "Bundle URL `stim ios` prefetches to warm Metro"
+	},
+	{
+		key: "metro.warmupUrl.android",
+		type: { kind: "bundle-url" },
+		scopes: PROJECT,
+		description: "Bundle URL `stim android` prefetches to warm Metro"
+	},
+	{
+		key: "metro.idleStopMinutes",
+		type: {
+			kind: "number",
+			integer: true,
+			minimum: 0
+		},
+		scopes: PROJECT,
+		default: 60,
+		description: "Minutes without a bundle request, client log or Stim command before the dev server stops; 0 never"
+	},
+	{
+		key: "worktree.exclude",
+		type: { kind: "strings" },
+		scopes: ["repo", "committed"],
+		committedAt: "repository",
+		description: "Ignored paths `worktree warm` skips"
+	},
+	{
+		key: "worktree.defaultBranch",
+		type: STRING,
+		scopes: ["repo", "committed"],
+		committedAt: "repository",
+		description: "Branch `worktree warm --refresh` expects the source checkout on"
+	},
+	{
+		key: "cache.provider",
+		type: STRING,
+		scopes: PROJECT,
+		description: "Second-tier cache provider module"
+	},
+	{
+		key: "cache.options",
+		type: OBJECT,
+		scopes: PROJECT,
+		description: "Options passed to the cache provider"
+	},
+	{
+		key: "iosSimulatorApp",
+		type: {
+			kind: "choice",
+			choices: IOS_SIMULATOR_APPS
+		},
+		scopes: MACHINE,
+		default: "xcode",
+		description: "App that displays an owned iOS simulator"
+	},
+	{
+		key: "concurrency.maxBuilds",
+		type: CAPACITY,
+		scopes: MACHINE,
+		default: 0,
+		env: "STIM_MAX_BUILDS",
+		description: "Concurrent native builds; 0 means no limit"
+	},
+	{
+		key: "concurrency.maxDevices",
+		type: CAPACITY,
+		scopes: MACHINE,
+		default: 0,
+		env: "STIM_MAX_DEVICES",
+		description: "Booted owned devices; 0 means no limit"
+	},
+	{
+		key: "budget.minFreeDiskGb",
+		type: GIGABYTES,
+		scopes: MACHINE,
+		default: 20,
+		env: "STIM_BUDGET_MIN_FREE_DISK_GB",
+		scopedHomeValue: 0,
+		description: "Free disk, in GB, ios, android and start reclaim toward; 0 reclaims only below the hard floor"
+	},
+	{
+		key: "budget.hardFloorDiskGb",
+		type: GIGABYTES,
+		scopes: MACHINE,
+		default: 5,
+		env: "STIM_BUDGET_HARD_FLOOR_DISK_GB",
+		scopedHomeValue: 0,
+		description: "Free disk, in GB, below which ios, android and start refuse with STIM_LOW_DISK; 0 never refuses"
+	},
+	{
+		key: "budget.maxCommittedMemoryGb",
+		type: GIGABYTES,
+		scopes: MACHINE,
+		env: "STIM_BUDGET_MAX_COMMITTED_MEMORY_GB",
+		scopedHomeValue: 0,
+		description: "Estimated memory, in GB, of live environments before idle ones are reclaimed; unset is 60% of RAM, 0 is off"
+	},
+	{
+		key: "budget.maxLiveWorkspaces",
+		type: CAPACITY,
+		scopes: MACHINE,
+		env: "STIM_BUDGET_MAX_LIVE_WORKSPACES",
+		scopedHomeValue: 0,
+		description: "Live workspaces before idle ones are reclaimed; unset or 0 means no limit"
+	},
+	{
+		key: "pool.iosParkedMax",
+		type: PARKED_MAX,
+		scopes: MACHINE,
+		default: 3,
+		env: "STIM_POOL_IOS_PARKED_MAX",
+		scopedHomeValue: 0,
+		description: "Parked simulators kept for adoption; 0 turns parking off"
+	},
+	{
+		key: "pool.androidParkedMax",
+		type: PARKED_MAX,
+		scopes: MACHINE,
+		default: 3,
+		env: "STIM_POOL_ANDROID_PARKED_MAX",
+		scopedHomeValue: 0,
+		description: "Parked emulators kept for adoption; 0 turns parking off"
+	},
+	{
+		key: "caches.buildCache",
+		type: ABSOLUTE_PATH,
+		scopes: MACHINE,
+		env: "STIM_BUILD_CACHE",
+		description: "Absolute path of the shared build cache"
+	},
+	{
+		key: "caches.metroCache",
+		type: ABSOLUTE_PATH,
+		scopes: MACHINE,
+		env: "STIM_METRO_CACHE",
+		description: "Absolute parent path of the Metro transform caches"
+	},
+	{
+		key: "tempDir",
+		type: ABSOLUTE_PATH,
+		scopes: MACHINE,
+		env: "STIM_TMPDIR",
+		description: "Absolute directory for large temporary copies"
+	}
+];
+const BY_KEY = new Map(SETTINGS.map((setting) => [setting.key, setting]));
+function settingDefinition(key) {
+	return BY_KEY.get(key) ?? null;
+}
+function isLayeredSetting(setting) {
+	return setting.scopes.some((scope) => scope !== "machine");
+}
+const SETTING_GROUPS = [...new Set(SETTINGS.filter(isLayeredSetting).flatMap((setting) => setting.key.split(".").slice(0, -1).map((_, index, parts) => parts.slice(0, index + 1).join("."))))];
+function isPlainObject(value) {
+	return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function bundleUrlAccepts(value, key) {
+	if (typeof value !== "string" || !/^(https?:\/\/|\/(?!\/))/.test(value) || /[\s\\#]/.test(value)) return false;
+	try {
+		const url = new URL(value, "http://localhost");
+		return /\.bundle\/*$/.test(url.pathname) && url.searchParams.get("platform") === key.split(".").at(-1);
+	} catch {
+		return false;
+	}
+}
+function expectedShape(type) {
+	switch (type.kind) {
+		case "boolean": return "true or false";
+		case "string": return "a string";
+		case "path": return "a string path";
+		case "strings": return "an array of strings";
+		case "number": return "a number";
+		case "choice": return `one of: ${type.choices.join(", ")}`;
+		case "object": return "an object";
+		case "bundle-url": return "an HTTP(S) URL or /path ending in .bundle with a matching platform query and no fragment";
+	}
+}
+function acceptsShape(setting, value) {
+	const { type } = setting;
+	switch (type.kind) {
+		case "boolean": return typeof value === "boolean";
+		case "string":
+		case "path": return typeof value === "string";
+		case "strings": return Array.isArray(value) && value.every((entry) => typeof entry === "string");
+		case "number": return typeof value === "number";
+		case "choice": return typeof value === "string" && type.choices.includes(value);
+		case "object": return isPlainObject(value);
+		case "bundle-url": return bundleUrlAccepts(value, setting.key);
+	}
+}
+function numberBounds(type) {
+	const noun = type.integer ? "a whole number" : "a number";
+	if (type.minimum !== void 0 && type.maximum !== void 0) return `${noun} from ${type.minimum} through ${type.maximum}`;
+	if (type.minimum !== void 0) return `${noun}, ${type.minimum} or more`;
+	return noun;
+}
+function settingValueError(setting, value) {
+	const { type } = setting;
+	if (!acceptsShape(setting, value)) return type.kind === "number" ? numberBounds(type) : expectedShape(type);
+	if (type.kind === "number") {
+		const number = value;
+		if (!Number.isFinite(number) || type.integer && !Number.isSafeInteger(number) || type.minimum !== void 0 && number < type.minimum || type.maximum !== void 0 && number > type.maximum) return numberBounds(type);
+	}
+	if (type.kind === "path") {
+		const path = value;
+		if (type.absolute && !isAbsolute(path)) return "an absolute path";
+		if (type.relative && (path.trim() === "" || isAbsolute(path))) return "a relative path inside the app directory";
+	}
+	if (type.kind === "string" && type.pattern && !new RegExp(type.pattern).test(value)) return type.patternHelp ?? `a string matching ${type.pattern}`;
+	return null;
+}
+const SENSITIVE_REFERENCE = /^(env|file):\S/;
+function isSensitiveReference(value) {
+	return typeof value === "string" && SENSITIVE_REFERENCE.test(value);
+}
+const JSON_ENCODED_KINDS = [
+	"boolean",
+	"number",
+	"strings",
+	"object"
+];
+/**
+* Coerces raw text (a CLI argument or an environment variable) through a setting's
+* registry type, the same way for both sources. Types whose values are not written
+* as bare text (boolean, number, strings, object) are read as JSON; a value that
+* fails to parse is left as the original string so `settingValueError` reports it.
+*/
+function coerceSettingText(setting, raw) {
+	if (!JSON_ENCODED_KINDS.includes(setting.type.kind)) return raw;
+	try {
+		return JSON.parse(raw);
+	} catch {
+		return raw;
+	}
+}
+//#endregion
+//#region state/settings-schema.ts
+const SETTINGS_SCHEMA_FILE = "settings.schema.json";
+const SETTINGS_SCHEMA_URL = `https://unpkg.com/stim/dist/${SETTINGS_SCHEMA_FILE}`;
+function leafSchema(setting, scope) {
+	const { type } = setting;
+	const schema = { description: setting.description };
+	switch (type.kind) {
+		case "string":
+			schema.type = "string";
+			if (type.pattern) schema.pattern = type.pattern;
+			break;
+		case "path":
+		case "bundle-url":
+			schema.type = "string";
+			break;
+		case "strings":
+			schema.type = "array";
+			schema.items = { type: "string" };
+			break;
+		case "number":
+			schema.type = type.integer ? "integer" : "number";
+			if (type.minimum !== void 0) schema.minimum = type.minimum;
+			if (type.maximum !== void 0) schema.maximum = type.maximum;
+			break;
+		case "boolean":
+			schema.type = "boolean";
+			break;
+		case "choice":
+			schema.type = "string";
+			schema.enum = [...type.choices];
+			break;
+		case "object": schema.type = "object";
+	}
+	if (setting.sensitive && scope === "committed") schema.pattern = "^(env|file):\\S";
+	if (setting.default !== void 0) schema.default = setting.default;
+	schema["x-stim"] = {
+		key: setting.key,
+		kind: type.kind,
+		scopes: [...setting.scopes],
+		...type.kind === "path" && type.absolute ? { absolute: true } : {},
+		...type.kind === "path" && type.relative ? { relative: true } : {},
+		...setting.env ? { env: setting.env } : {},
+		...setting.sensitive ? { sensitive: true } : {},
+		...setting.committedAt ? { committedAt: setting.committedAt } : {}
+	};
+	return schema;
+}
+function objectSchema(settings, scope, closed) {
+	const root = {
+		type: "object",
+		properties: {},
+		additionalProperties: !closed
+	};
+	for (const setting of settings) {
+		const parts = setting.key.split(".");
+		let node = root;
+		for (const part of parts.slice(0, -1)) {
+			const properties = node.properties;
+			properties[part] ??= {
+				type: "object",
+				properties: {},
+				additionalProperties: false
+			};
+			node = properties[part];
+		}
+		node.properties[parts.at(-1)] = leafSchema(setting, scope);
+	}
+	return root;
+}
+/**
+* The published settings schema. The root describes a committed `.stim.json`;
+* `$defs.machine` describes the settings keys of `$STIM_HOME/config.json`.
+* Every leaf carries `x-stim` with its dotted key, kind, writable scopes,
+* environment override, and sensitivity.
+*/
+function settingsJsonSchema() {
+	const committed = objectSchema(SETTINGS.filter((setting) => setting.scopes.includes("committed")), "committed", true);
+	committed.properties.$schema = { type: "string" };
+	return {
+		$schema: "https://json-schema.org/draft/2020-12/schema",
+		$id: SETTINGS_SCHEMA_URL,
+		title: "Stim settings",
+		description: "Settings in a committed .stim.json. $defs.machine lists the machine settings in $STIM_HOME/config.json.",
+		...committed,
+		$defs: { machine: objectSchema(SETTINGS.filter((setting) => setting.scopes.includes("machine")), "machine", false) }
+	};
+}
+//#endregion
+//#region state/status.ts
+const BUILD_PHASES = [
+	"prepare",
+	"cache-lookup",
+	"wait",
+	"prebuild",
+	"pods",
+	"compile",
+	"install",
+	"launch"
+];
+//#endregion
+//#region state/workspace-state.ts
+const IDLE_STOP_KEY = "devServerStop";
+function readIdleStop(state) {
+	const record = state?.[IDLE_STOP_KEY];
+	if (record?.reason !== "idle" || typeof record.at !== "string" || typeof record.idleMinutes !== "number") return null;
+	return {
+		reason: "idle",
+		at: record.at,
+		idleMinutes: record.idleMinutes
+	};
+}
+function readWorkspaceState(root) {
+	return readJsonObject(workspaceStateFile(root));
+}
+function lastUseFrom(state, logMtimes) {
+	const candidates = [
+		Date.parse(String(state?.lastUsedAt ?? "")),
+		Date.parse(String(state?.lastBuild?.startedAt ?? "")),
+		Date.parse(String(state?.supervisor?.startedAt ?? "")),
+		...logMtimes
+	].filter(Number.isFinite);
+	return candidates.length ? Math.max(...candidates) : NaN;
+}
+function workspaceLastUsed(root) {
+	const logs = workspaceLogsDir(root);
+	let mtimes = [];
+	try {
+		mtimes = readdirSync(logs).flatMap((name) => {
+			try {
+				return [statSync(join(logs, name)).mtimeMs];
+			} catch {
+				return [];
+			}
+		});
+	} catch {}
+	return lastUseFrom(readWorkspaceState(root), mtimes);
+}
+//#endregion
+export { ANDROID_COMPILER_CACHE_CHOICES, ANDROID_PCH_CHOICES, BUILD_PHASES, ERROR_SOURCES, IDLE_STOP_KEY, IOS_SIMULATOR_APPS, LEVELS, REMOTE_DEVICE_BACKENDS, SETTINGS, SETTINGS_SCHEMA_FILE, SETTINGS_SCHEMA_URL, SETTING_GROUPS, SETTING_SCOPES, SOURCES, TUNNEL_MODES, acceptsShape, advanceTail, allMetroPorts, attachExpoErrorContext, buildCriteria, coerceSettingText, compileGrep, configCorruptRepair, configLockPath, createdDevicesFile, createdDevicesLock, easMachineStateRoot, easSessionLedgerFile, easSessionLedgerLock, emulatorLogFile, expectedShape, fileSizes, findEnclosingWorktreeRoot, findProjectByMetroPort, followLogs, getConcurrencyLimits, getConfigPath, getProject, getProjectSetting, getProjectSettings, getRepoSettings, isJsonObject, isLayeredSetting, isPathPrefix, isSensitiveReference, lastUseFrom, levelRank, loadConfig, logFiles, markerWindow, parseNdjsonLine, parseNdjsonText, parseSince, queryLogs, readCreatedDevices, readEasSessionLedger, readIdleStop, readJsonFile, readJsonObject, readLogRecords, readNdjsonGenerations, readWorkspaceState, recordMatches, settingDefinition, settingValueError, settingsJsonSchema, sharedCcache, sharedCompilationCache, sharedGradle, sharedPods, sortByTs, supervisorLogFile, supervisorPidFile, tailRead, validEasSessionClaim, withConfigLock, workspaceDerivedData, workspaceGradleBuild, workspaceLastUsed, workspaceLogErrorIndex, workspaceLogsDir, workspaceMetadataFile, workspaceStateFile, workspaceStateLock };