stim 1.20.2 → 1.22.0

package/dist/api.mjs

@@ -1,2 +1,783 @@
-import { n as createStim, t as StimError } from "./api-qvOzWyfO.mjs";
+import { m as operationState, r as WorkspaceProcessCleanupError, v as runReport, x as ownership_claim_exports, y as trackReportResource } from "./exec-DEoAhcze.mjs";
+import { d as workspaceDir, m as workspaceLogsDir$1, n as ensureWorkspaceStorage, r as ensureWorkspaceStorageAsync } from "./paths-DQtTgsBf.mjs";
+import { E as upsertProject, p as getProject, q as validateDeviceSlot, y as refuseRelativeStimPaths } from "./config-DlrsduwG.mjs";
+import { l as phaseLine } from "./command-output-gwpm28fu.mjs";
+import { d as cancelledError, f as throwIfCancelled } from "./operation-exec-BW0em61G.mjs";
+import { a as recordWorkspaceUseAsync, i as recordWorkspaceUse } from "./workspace-state-U08dEzhG.mjs";
+import { J as resolveProjectSettingsAsync, Nt as repoRootAsync, a as SETTING_SHAPE_REMEDY, et as settingShapeErrors, it as unknownSettingKeys, p as cacheProviderSettingError } from "./settings-C7O8A6ZI.mjs";
+import { c as projectProblem, f as projectRegistry, i as findProjectRoot$1, r as findCommandWorkspaceAsync, t as NO_PROJECT_REFUSAL } from "./project-wM_XFTvE.mjs";
+import { n as macosDir } from "./state-08I3hw3_.mjs";
+import { r as createNdjsonWriter } from "./ndjson-CgE_o3Dl.mjs";
+import { B as recordFinishedBuild, H as tapBuildLog, V as startBuildProgress } from "./budget-Cvwn54qV.mjs";
+import { d as runCancellationSignal, f as withNativeBuildRun } from "./native-run-NwUuxbkg.mjs";
+import { c as ensureHomeIdentity, s as workspaceShareURL } from "./stim-desktop-D5OGpYZM.mjs";
+import { s as resolveBuildPlacement } from "./selection-DSMbWEX2.mjs";
+import { c as stopWorkspaceNow } from "./stop-Mv6W9FAk.mjs";
+import { r as runReload } from "./reload-BzkYabB-.mjs";
+import { c as startDevServer } from "./start-EojN4WFz.mjs";
+import { s as recordDoctorCheck } from "./doctor-watchman-N2wDotwQ.mjs";
+import { a as readDoctorReport } from "./doctor-D5_EzwfA.mjs";
+import { h as warmWorktreeTarget, m as removeWorktreeTarget } from "./worktree-CHecZ4Oq.mjs";
+import { i as readGcReport, n as executeGc, o as withGcMaintenanceClaim } from "./gc-CXxN-4SE.mjs";
+import { r as readWorkspaceLogs, t as followWorkspaceLogs } from "./logs-BfwwadsZ.mjs";
+import { t as readProjectStats } from "./stats-report-BzaPrRm6.mjs";
+import { n as buildAndroidOperation, t as buildIosOperation } from "./build-CabC3G23.mjs";
+import { a as readAndroidBuildPlan, i as runAndroidOperation } from "./android-ByRMUoiJ.mjs";
+import { i as readIosBuildPlan, r as runIosOperation } from "./ios-pm4nL6By.mjs";
+import { a as buildMacosBundle, i as planMacos, n as runMacos } from "./macos-NfV2D7dO.mjs";
+import { t as runWeb } from "./web-DKx6yoFA.mjs";
+import { i as SettingsRefusal, o as readSettingsContext, s as readSettingsPayload, t as mutateSetting } from "./settings-write-CzD60rOD.mjs";
+import { randomBytes } from "node:crypto";
+import { mkdirSync, mkdtempSync, readFileSync, realpathSync, rmSync } from "node:fs";
+import { stripVTControlCharacters } from "node:util";
+import { homedir } from "node:os";
+import { isAbsolute, join, resolve } from "node:path";
+import { withAmbientContext } from "@stim-cli/core";
+import { RUN_ID_ENV, findProjectRoot, openLogDir, validRunId } from "@stim-cli/core/state";
+import { decodeSecret } from "@stim-cli/core/noise-session";
+//#region src/commands/macos-build.ts
+async function buildMacosOperation(context, root, options) {
+	const note = (line) => context.output("stderr", `${line}\n`);
+	if (process.platform !== "darwin") throw new Error("Building a macOS app requires a Mac with Swift installed.");
+	root = realpathSync(root);
+	const selected = projectRegistry.selectMacos(root);
+	if ("problem" in selected) throw Object.assign(new Error(selected.problem.message), {
+		code: "STIM_NO_PROJECT",
+		remedy: selected.problem.remedy
+	});
+	const { settings } = await resolveProjectSettingsAsync(root, {
+		env: context.env,
+		signal: runCancellationSignal(context) ?? context.signal
+	});
+	const [shape] = settingShapeErrors(settings);
+	if (shape) throw Object.assign(/* @__PURE__ */ new Error(`${shape} ${SETTING_SHAPE_REMEDY}`), { code: "STIM_BAD_ARG" });
+	const placement = resolveBuildPlacement(options.remoteBuild);
+	if (placement.failure) throw Object.assign(new Error(placement.failure.message), placement.failure);
+	const recipe = await (await selected.load()).prepare(context, settings);
+	ensureWorkspaceStorage(root);
+	return withNativeBuildRun(context, root, {
+		command: "build",
+		platform: "macos"
+	}, async (claim) => {
+		if (!getProject(root)) upsertProject(root, {});
+		recordWorkspaceUse(root, /* @__PURE__ */ new Date(), context.env, context.cwd);
+		const started = Date.now();
+		const progress = startBuildProgress({
+			root,
+			platform: "macos",
+			slot: "default",
+			claim,
+			note
+		});
+		const logs = workspaceLogsDir$1(root);
+		const writer = tapBuildLog(createNdjsonWriter(join(logs, "build-artifact-macos.ndjson"), { truncate: true }), progress);
+		const build = {
+			state: "running",
+			startedAt: new Date(started).toISOString(),
+			buildMachine: placement.selected
+		};
+		let directory;
+		let succeeded = false;
+		try {
+			const artifacts = join(workspaceDir(root), "artifacts");
+			mkdirSync(artifacts, { recursive: true });
+			directory = mkdtempSync(join(artifacts, "macos-"));
+			const bundle = join(directory, `${recipe.product}.app`);
+			await buildMacosBundle({
+				context,
+				root,
+				recipe,
+				bundle,
+				bundleId: recipe.bundleId,
+				scratch: join(macosDir(root), "build"),
+				writer,
+				note,
+				progress,
+				record: build,
+				buildMachine: placement.selected
+			});
+			throwIfCancelled(runCancellationSignal(context), "macOS build");
+			const executable = realpathSync(join(bundle, "Contents", "MacOS", recipe.product));
+			const links = { workspace: await workspaceShareURL(root, { platform: "macos" }, runCancellationSignal(context) ?? context.signal) };
+			throwIfCancelled(runCancellationSignal(context), "macOS build");
+			build.state = "ok";
+			succeeded = true;
+			return {
+				product: recipe.product,
+				bundle,
+				bundleId: recipe.bundleId,
+				executable,
+				build,
+				logs: { dir: logs },
+				links
+			};
+		} catch (error) {
+			const failure = runCancellationSignal(context)?.aborted ? cancelledError("macOS build", error) : error;
+			build.state = "failed";
+			build.error = failure instanceof Error ? failure.message : String(failure);
+			build.errorCode = failure.code;
+			throw failure;
+		} finally {
+			build.finishedAt = (/* @__PURE__ */ new Date()).toISOString();
+			build.durationMs = Date.now() - started;
+			try {
+				recordFinishedBuild(root, {
+					platform: "macos",
+					status: build.state,
+					configuration: "Debug",
+					fingerprint: build.fingerprint ?? null,
+					cacheKey: build.cacheKey ?? null,
+					cacheHit: build.cacheHit ? build.cacheSource === "provider" ? "remote" : "local" : false,
+					cacheSkipped: !build.cacheKey,
+					durationMs: build.durationMs,
+					startedAt: build.startedAt,
+					errorCode: build.errorCode,
+					buildMachine: build.buildMachine,
+					builtOn: build.builtOn,
+					offloadedTo: build.offloadedTo,
+					offloadFallback: build.offloadFallback,
+					compileSteps: progress.steps()
+				}, { artifactOnly: true });
+			} catch (error) {
+				note(phaseLine("state", `could not record the build: ${error?.message || error}`));
+			} finally {
+				if (!succeeded && directory) rmSync(directory, {
+					recursive: true,
+					force: true
+				});
+				writer.close();
+				progress.clear();
+			}
+		}
+	}, { write: note });
+}
+//#endregion
+//#region src/api.ts
+const version = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
+var StimError = class extends Error {
+	code;
+	remedy;
+	details;
+	constructor({ code, message, remedy = null, details }, options) {
+		super(message, options);
+		this.name = "StimError";
+		this.code = code;
+		this.remedy = remedy;
+		this.details = details;
+	}
+};
+/**
+* Creates a client without starting processes or changing the caller's cwd, environment, or signal handlers.
+* The Stim home is fixed when the client is created: `home`, else STIM_HOME from `env`, else the default home.
+* Operations run in the calling process against the client's home and project, so clients for different
+* homes can share a process.
+* Resources remain workspace-owned until stop() is called.
+*/
+function createStim(options) {
+	let projectRoot;
+	try {
+		projectRoot = realpathSync(options.projectRoot);
+	} catch (error) {
+		throw new StimError({
+			code: "STIM_NO_PROJECT",
+			message: `Could not resolve projectRoot ${options.projectRoot}: ${error instanceof Error ? error.message : String(error)}`,
+			remedy: "Pass the path to an existing, readable app directory."
+		});
+	}
+	for (const [name, path] of [["home", options.home], ["buildCache", options.buildCache]]) if (path !== void 0 && !isAbsolute(path)) throw new StimError({
+		code: "STIM_BAD_ARG",
+		message: `${name} must be an absolute path.`
+	});
+	const base = options.env ?? process.env;
+	const home = options.home ?? (base.STIM_HOME || join(base.HOME || base.USERPROFILE || homedir(), ".stim"));
+	const clientContext = {
+		...options,
+		projectRoot,
+		env: {
+			...base,
+			...options.home === void 0 ? {} : { STIM_HOME: options.home },
+			...options.buildCache === void 0 ? {} : { STIM_BUILD_CACHE: options.buildCache },
+			FORCE_COLOR: "0"
+		}
+	};
+	const begin = (signal, cancelOnProgress = false) => {
+		const controller = cancelOnProgress ? new AbortController() : void 0;
+		const abort = () => controller?.abort();
+		if (controller) {
+			signal?.addEventListener("abort", abort, { once: true });
+			if (signal?.aborted) abort();
+		}
+		const callback = {};
+		const output = (stream, message) => {
+			if ("error" in callback) return;
+			try {
+				options.onProgress?.({
+					stream,
+					message: stripVTControlCharacters(message)
+				});
+			} catch (error) {
+				callback.error = error;
+				controller?.abort();
+			}
+		};
+		const operation = operationContext(clientContext, home, output, controller?.signal ?? signal);
+		if (controller) operationState(operation).abortOperation = abort;
+		return {
+			context: operation,
+			callback,
+			dispose: () => signal?.removeEventListener("abort", abort)
+		};
+	};
+	const beginReport = (signal) => {
+		const operation = begin(signal, true);
+		operation.context.env.STIM_HOME = clientContext.env.STIM_HOME;
+		for (const name of [
+			"AGENT_DEVICE_STATE_DIR",
+			"AGENT_DEVICE_CLAIMS_DIR",
+			"AGENT_DEVICE_IOS_RUNNER_LEASE_DIR"
+		]) {
+			const directory = operation.context.env[name]?.trim();
+			if (directory) operation.context.env[name] = resolve(operation.context.cwd, directory);
+		}
+		return operation;
+	};
+	const report = async (signal, work, timeoutMs) => {
+		const operation = beginReport(signal);
+		try {
+			return await read(operation, (context) => runReport(context, (request) => withAmbientContext(request, () => work(request)), timeoutMs));
+		} finally {
+			operation.dispose();
+		}
+	};
+	return {
+		projectRoot,
+		start: ({ signal, ...request } = {}) => {
+			const operation = begin(signal, true);
+			operation.context.env.STIM_HOME = clientContext.env.STIM_HOME;
+			return lifecycle(operation, (context) => start(context, request));
+		},
+		identity: ({ signal } = {}) => read(begin(signal), (operation) => ensureHomeIdentity(operation.signal)),
+		doctor: async ({ signal, platform, record } = {}) => {
+			if (platform !== void 0 && platform !== "ios" && platform !== "android") return Promise.reject(new StimError({
+				code: "STIM_BAD_ARG",
+				message: "platform must be ios or android."
+			}));
+			const result = await report(signal, (context) => readDoctorReport(context, platform, version));
+			if (record !== true) return result;
+			return read(begin(signal), async (context) => {
+				await recordDoctorCheck(result.project, platform, version, context.signal);
+				return result;
+			});
+		},
+		requestMachineAccess: async ({ signal, ticket } = {}) => {
+			if (ticket !== void 0 && (typeof ticket !== "string" || !decodeSecret(ticket.trim()))) throw new StimError({
+				code: "STIM_BAD_ARG",
+				message: "The setup ticket must encode 32 random bytes."
+			});
+			const result = await report(signal, (context) => {
+				context.env.STIM_ACCESS_TICKET = ticket?.trim();
+				return readDoctorReport(context, "ios", version, true);
+			}, 12e4);
+			return read(begin(signal), async (context) => {
+				await recordDoctorCheck(result.project, "ios", version, context.signal);
+				return result;
+			});
+		},
+		plan: ({ signal, ...request }) => report(signal, (context) => {
+			const task = Promise.resolve().then(async () => {
+				if (request.platform === "macos") try {
+					return await planMacos(context, findProjectRoot$1(context.projectRoot) ?? context.projectRoot);
+				} catch (cause) {
+					if (cause instanceof Error && "reportCleanup" in cause) throw cause;
+					context.signal.throwIfAborted();
+					const code = cause instanceof Error && "code" in cause && typeof cause.code === "string" ? cause.code : "STIM_BAD_ARG";
+					const remedy = cause instanceof Error && "remedy" in cause && typeof cause.remedy === "string" ? cause.remedy : "Check the macOS project settings in stim guide macos.";
+					throw new StimError({
+						code,
+						message: cause instanceof Error ? cause.message : String(cause),
+						remedy
+					});
+				}
+				if (request.platform !== "ios" && request.platform !== "android") throw new StimError({
+					code: "STIM_BAD_ARG",
+					message: "platform must be ios, android or macos."
+				});
+				const selectors = { slot: validateDeviceSlot(request.slot) };
+				const result = request.platform === "ios" ? await readIosBuildPlan(context, selectors) : await readAndroidBuildPlan(context, selectors);
+				context.signal.throwIfAborted();
+				if ("platform" in result) return result;
+				throw new StimError({
+					...result.refusal,
+					details: { lines: result.lines }
+				});
+			});
+			trackReportResource(context, task.then(() => void 0, (cause) => {
+				if (cause instanceof Error && "reportCleanup" in cause) throw cause;
+			}), () => {});
+			return task;
+		}),
+		gc: ({ signal, olderThan, cache, worktrees } = {}) => {
+			if (olderThan !== void 0 && !Number.isSafeInteger(olderThan)) return Promise.reject(new StimError({
+				code: "STIM_BAD_ARG",
+				message: "olderThan must be a whole number of days."
+			}));
+			return report(signal, async (context) => {
+				const result = await readGcReport({
+					olderThan,
+					cache,
+					worktrees
+				}, {
+					operation: context,
+					easLedgerRoot: join(context.env.HOME || context.env.USERPROFILE || homedir(), ".stim", "machine", "eas")
+				});
+				if ("code" in result) throw new StimError(result);
+				return result;
+			});
+		},
+		collectGarbage: ({ signal, olderThan, cache, worktrees, delete: deleting, idleMs } = {}) => {
+			const invalid = olderThan !== void 0 && !Number.isSafeInteger(olderThan) ? "olderThan must be a whole number of days." : cache !== void 0 && (typeof cache !== "string" || !cache.trim()) ? "cache must name a cache." : worktrees !== void 0 && typeof worktrees !== "boolean" ? "worktrees must be a boolean." : deleting !== void 0 && typeof deleting !== "boolean" ? "delete must be a boolean." : idleMs !== void 0 && (!Number.isSafeInteger(idleMs) || idleMs <= 0) ? "idleMs must be a positive whole number of milliseconds." : null;
+			if (invalid) return Promise.reject(new StimError({
+				code: "STIM_BAD_ARG",
+				message: invalid
+			}));
+			const operation = beginReport(signal);
+			const request = {
+				olderThan,
+				cache,
+				worktrees,
+				delete: deleting,
+				idle: idleMs,
+				json: true
+			};
+			return lifecycle(operation, (context) => withGcMaintenanceClaim(request, (claim) => runReport(context, (bounded) => withAmbientContext(bounded, () => {
+				const task = executeGc(request, {
+					operation: bounded,
+					easLedgerRoot: join(bounded.env.HOME || bounded.env.USERPROFILE || homedir(), ".stim", "machine", "eas")
+				}, (_stream, line) => bounded.output("stderr", `${line}\n`), claim).then(({ payload, exitCode }) => {
+					if ("code" in payload) throw new StimError(payload);
+					return {
+						report: payload,
+						exitCode
+					};
+				});
+				trackReportResource(bounded, task.then(() => void 0, (cause) => {
+					if (cause instanceof WorkspaceProcessCleanupError || cause instanceof Error && "reportCleanup" in cause) throw cause;
+				}), () => {});
+				return task;
+			}))).catch((cause) => {
+				if (cause instanceof WorkspaceProcessCleanupError) throw cause;
+				const failure = (0, ownership_claim_exports.claimFailure)(cause, null);
+				if (failure) throw new StimError(failure);
+				throw cause;
+			}));
+		},
+		warmWorktree: ({ signal, beforeWarm } = {}) => lifecycle(beginReport(signal), (context) => runReport(context, (bounded) => withAmbientContext(bounded, () => {
+			const task = warmWorktreeTarget({
+				cwd: bounded.cwd,
+				operation: bounded,
+				beforeWarm
+			});
+			trackReportResource(bounded, task.then(() => void 0, (cause) => {
+				if (cause instanceof WorkspaceProcessCleanupError || cause instanceof Error && "reportCleanup" in cause) throw cause;
+			}), () => {});
+			return task;
+		}), 54e5)),
+		removeWorktree: ({ signal, target, force, beforeRemove } = {}) => {
+			const invalid = target !== void 0 && (typeof target !== "string" || target.length === 0) ? "target must be a nonempty path." : force !== void 0 && typeof force !== "boolean" ? "force must be a boolean." : null;
+			if (invalid) return Promise.reject(new StimError({
+				code: "STIM_BAD_ARG",
+				message: invalid
+			}));
+			return lifecycle(beginReport(signal), (context) => runReport(context, (bounded) => withAmbientContext(bounded, () => {
+				let exitCode = 0;
+				const task = removeWorktreeTarget(resolve(bounded.cwd, target ?? "."), {
+					force,
+					beforeRemove,
+					operation: bounded,
+					output: {
+						error: (line) => bounded.output("stderr", `${line}\n`),
+						fail: () => {
+							exitCode = 1;
+						}
+					}
+				}).then((removed) => ({
+					removed,
+					exitCode
+				}));
+				trackReportResource(bounded, task.then(() => void 0, (cause) => {
+					if (cause instanceof WorkspaceProcessCleanupError || cause instanceof Error && "reportCleanup" in cause) throw cause;
+				}), () => {});
+				return task;
+			})));
+		},
+		settings: ({ signal } = {}) => read(begin(signal), async (operation) => readSettingsPayload(await readSettingsContext(operation.projectRoot, {
+			...operation.env,
+			STIM_HOME: clientContext.env.STIM_HOME
+		}, note(operation), operation.signal), operation.signal)),
+		setSetting: (key, value, { signal, scope, beforeWrite } = {}) => read(begin(signal), (operation) => mutateSetting({
+			action: "set",
+			key,
+			value,
+			scope
+		}, {
+			cwd: operation.projectRoot,
+			env: {
+				...operation.env,
+				STIM_HOME: clientContext.env.STIM_HOME
+			},
+			note: note(operation),
+			signal: operation.signal,
+			beforeWrite
+		})),
+		unsetSetting: (key, { signal, scope, beforeWrite } = {}) => read(begin(signal), (operation) => mutateSetting({
+			action: "unset",
+			key,
+			scope
+		}, {
+			cwd: operation.projectRoot,
+			env: {
+				...operation.env,
+				STIM_HOME: clientContext.env.STIM_HOME
+			},
+			note: note(operation),
+			signal: operation.signal,
+			beforeWrite
+		})),
+		stats: ({ signal } = {}) => read(begin(signal), async (operation) => (await readProjectStats(findProjectRoot(operation.projectRoot), operation.env, operation.signal)).report),
+		logs: ({ signal, ...request } = {}) => read(begin(signal), (operation) => readWorkspaceLogs(operation, request)),
+		followLogs: ({ signal, ...request }, onRecord, onBackfill) => {
+			const operation = begin(signal);
+			return read(operation, async (readContext) => {
+				const stop = await followWorkspaceLogs(readContext, request, onRecord, onBackfill);
+				if ("error" in operation.callback) stop();
+				return stop;
+			});
+		},
+		build: (({ signal, ...request }) => lifecycle(begin(signal, true), (operation) => build(operation, request))),
+		run: (({ signal, ...request }) => lifecycle(begin(signal, true), (operation) => run(operation, request))),
+		stop: ({ signal, ...request } = {}) => read(begin(signal), async (operation) => {
+			const root = findProjectRoot$1(operation.projectRoot) ?? operation.projectRoot;
+			request.beforeStop?.(root);
+			const logs = workspaceLogsDir$1(root);
+			let result;
+			try {
+				result = await stopWorkspaceNow({
+					root,
+					slot: request.slot,
+					report: note(operation),
+					operation
+				});
+			} catch (error) {
+				if (operation.signal.aborted) throw error;
+				const failure = error;
+				throw new StimError({
+					code: failure.code ?? "STIM_RUN_FAILED",
+					message: error instanceof Error ? error.message : String(error),
+					remedy: failure.remedy ?? null,
+					details: {
+						logs,
+						cause: failure.details
+					}
+				});
+			}
+			if ("refusal" in result) throw new StimError({
+				...result.refusal,
+				details: {
+					logs,
+					cause: result.remote
+				}
+			});
+			return result;
+		}),
+		reload: async ({ signal, ...request } = {}) => {
+			const requestOperation = begin(signal, true);
+			try {
+				return await read(requestOperation, (context) => runReport(context, (operation) => withAmbientContext(operation, () => {
+					const result = reload(operation, request);
+					trackReportResource(operation, result.then(() => void 0, () => void 0), () => {});
+					return result;
+				})));
+			} finally {
+				requestOperation.dispose();
+			}
+		},
+		diagnostics({ signal, ...request } = {}) {
+			if (request.tail !== void 0 && (!Number.isSafeInteger(request.tail) || request.tail < 0)) return Promise.reject(new StimError({
+				code: "STIM_BAD_ARG",
+				message: "tail must be a non-negative integer."
+			}));
+			return read(begin(signal), async (operation) => {
+				const directory = workspaceLogsDir$1(operation.projectRoot);
+				if (request.tail === 0) return {
+					directory,
+					records: []
+				};
+				const view = await openLogDir(directory, { signal: operation.signal });
+				try {
+					return {
+						directory,
+						records: await view.query({
+							tail: request.tail ?? 200,
+							errorsOnly: request.errors ?? false
+						})
+					};
+				} finally {
+					await view.close();
+				}
+			});
+		}
+	};
+}
+function operationContext(client, home, output, signal) {
+	const runId = validRunId(client.env[RUN_ID_ENV]) ?? randomBytes(6).toString("hex");
+	return {
+		home,
+		buildCache: client.buildCache ?? null,
+		projectRoot: client.projectRoot,
+		cwd: client.projectRoot,
+		runId,
+		env: {
+			...client.env,
+			STIM_HOME: home,
+			[RUN_ID_ENV]: runId
+		},
+		signal: signal ?? new AbortController().signal,
+		output
+	};
+}
+async function read({ context, callback }, operation) {
+	const { signal } = context;
+	if (signal.aborted) throw cancelled();
+	let result;
+	try {
+		refuseRelativeStimPaths(context.env);
+		result = await withAmbientContext(context, () => operation(context));
+	} catch (error) {
+		const cleanupUnresolved = error instanceof Error && ("reportCleanup" in error || "code" in error && error.code === "STIM_CLAIM_UNAVAILABLE");
+		if ("error" in callback && !cleanupUnresolved) throw callback.error;
+		if (signal.aborted && !cleanupUnresolved) throw cancelled();
+		if (error instanceof StimError) throw error;
+		if (error instanceof Error && "code" in error && typeof error.code === "string" && error.code.startsWith("STIM_")) {
+			const remedy = error instanceof SettingsRefusal ? error.remedy : cleanupUnresolved && "remedy" in error && typeof error.remedy === "string" ? error.remedy : null;
+			throw new StimError({
+				code: error.code,
+				message: error.message,
+				remedy
+			}, cleanupUnresolved ? { cause: error } : void 0);
+		}
+		throw error;
+	}
+	if ("error" in callback) throw callback.error;
+	if (signal.aborted) throw cancelled();
+	return result;
+}
+function note(operation) {
+	return (line) => operation.output("stderr", `${line}\n`);
+}
+function cancelled() {
+	return new StimError({
+		code: "STIM_CANCELLED",
+		message: "The Stim operation was cancelled."
+	});
+}
+async function lifecycle(operation, work) {
+	try {
+		return await read(operation, async (context) => {
+			const logs = workspaceLogsDir$1(context.projectRoot);
+			try {
+				return await work(context);
+			} catch (error) {
+				const failure = error;
+				throw new StimError({
+					code: failure?.code ?? "STIM_RUN_FAILED",
+					message: error instanceof Error ? error.message : String(error),
+					remedy: failure?.remedy ?? null,
+					details: {
+						logs,
+						cause: error instanceof WorkspaceProcessCleanupError ? { retainedClaimRoots: [...new Set(error.claims.map((claim) => claim.root))] } : failure?.details
+					}
+				});
+			}
+		});
+	} finally {
+		operation.dispose();
+	}
+}
+async function start(context, options) {
+	if (options.waitSeconds !== void 0 && (!Number.isSafeInteger(options.waitSeconds) || options.waitSeconds <= 0)) throw new StimError({
+		code: "STIM_BAD_ARG",
+		message: "waitSeconds must be a positive whole number."
+	});
+	const root = findProjectRoot$1(context.projectRoot);
+	if (!root) throw new StimError(NO_PROJECT_REFUSAL);
+	const problem = projectProblem(root, "dev-server");
+	if (problem) throw new StimError({
+		code: "STIM_NO_PROJECT",
+		...problem
+	});
+	options.beforeStart?.(root);
+	context.signal.throwIfAborted();
+	return withAmbientContext({
+		...context,
+		projectRoot: root
+	}, async () => {
+		const { context: settingsContext, settings } = await resolveProjectSettingsAsync(root, {
+			env: context.env,
+			signal: context.signal
+		});
+		const shapeErrors = settingShapeErrors(settings);
+		if (shapeErrors.length) throw new StimError({
+			code: "STIM_BAD_ARG",
+			message: shapeErrors.join("\n"),
+			remedy: SETTING_SHAPE_REMEDY
+		});
+		for (const key of unknownSettingKeys(settings)) note(context)(`Warning: setting "${key}" is not read by Stim and will be ignored.`);
+		const cacheError = cacheProviderSettingError(settings);
+		if (cacheError) note(context)(`Warning: ${cacheError} No cache provider is used.`);
+		await ensureWorkspaceStorageAsync(root, context.signal);
+		await recordWorkspaceUseAsync(root, /* @__PURE__ */ new Date(), context.env, context.cwd, context.signal);
+		const result = await startDevServer({
+			root,
+			settings,
+			settingsContext,
+			waitSeconds: options.waitSeconds,
+			remote: options.remote,
+			resetCache: options.resetCache,
+			out: (line) => context.output("stdout", `${line}\n`),
+			note: note(context)
+		});
+		if (!result.ok) {
+			for (const line of result.lines) note(context)(line);
+			throw new StimError({
+				...result.error,
+				details: {
+					lines: result.lines,
+					reclaimed: result.reclaimed,
+					...result.retainedClaimRoots ? { retainedClaimRoots: result.retainedClaimRoots } : {}
+				}
+			});
+		}
+		return result.facts;
+	});
+}
+async function reload(context, options) {
+	if (options.platform !== void 0 && ![
+		"ios",
+		"android",
+		"web"
+	].includes(options.platform)) throw new StimError({
+		code: "STIM_BAD_ARG",
+		message: "platform must be ios, android or web."
+	});
+	const root = await findCommandWorkspaceAsync(context.projectRoot, (cwd) => repoRootAsync(cwd, {
+		env: context.env,
+		signal: context.signal
+	}), note(context));
+	context.signal.throwIfAborted();
+	if (!root) throw new StimError({
+		code: "STIM_NO_PROJECT",
+		message: `No Stim environment is registered for ${context.projectRoot}.`,
+		remedy: "Run stim start first."
+	});
+	options.beforeReload?.(root);
+	context.signal.throwIfAborted();
+	await recordWorkspaceUseAsync(root, /* @__PURE__ */ new Date(), context.env, context.projectRoot, context.signal);
+	const result = await runReload({
+		root,
+		platform: options.platform,
+		signal: context.signal
+	});
+	if (!result.ok) throw new StimError(result.error);
+	return result.facts;
+}
+async function build(context, options) {
+	const root = context.projectRoot;
+	switch (options.platform) {
+		case "ios": return {
+			platform: "ios",
+			facts: await buildIosOperation(context, root, options)
+		};
+		case "android": return {
+			platform: "android",
+			facts: await buildAndroidOperation(context, root, options)
+		};
+		case "macos": return {
+			platform: "macos",
+			facts: await buildMacosOperation(context, root, options)
+		};
+		default: throw new StimError({
+			code: "STIM_BAD_ARG",
+			message: "Unknown Stim build platform."
+		});
+	}
+}
+async function run(context, options) {
+	const root = context.projectRoot;
+	switch (options.platform) {
+		case "ios": {
+			let error;
+			const result = await runIosOperation(context, root, options, {}, (failure) => {
+				error = failure;
+			});
+			if (!result) throw new StimError({
+				code: error?.code ?? "STIM_RUN_FAILED",
+				message: error?.message ?? "The iOS run failed.",
+				remedy: error?.remedy,
+				details: error
+			});
+			return {
+				platform: "ios",
+				facts: result.facts
+			};
+		}
+		case "android": {
+			const result = await runAndroidOperation(context, root, options);
+			if (!result.ok || !result.facts) throw new StimError({
+				code: result.error?.code ?? "STIM_RUN_FAILED",
+				message: result.error?.message ?? "The Android run failed.",
+				remedy: result.error?.remedy,
+				details: result.error
+			});
+			return {
+				platform: "android",
+				facts: result.facts
+			};
+		}
+		case "macos": {
+			const record = await runMacos(context, root, note(context), options.remote, options.remoteBuild);
+			return {
+				platform: "macos",
+				facts: {
+					product: record.product,
+					bundle: record.bundle,
+					bundleId: record.bundleId,
+					executable: record.executable,
+					pid: record.app?.pid ?? null,
+					launched: record.hostLaunched ?? record.app !== void 0,
+					build: record.build,
+					logs: { dir: workspaceLogsDir$1(root) }
+				}
+			};
+		}
+		case "web": {
+			const result = await runWeb({
+				root,
+				headed: options.headed ?? false,
+				note: note(context),
+				context
+			});
+			if (!result.ok) throw new StimError(result.error);
+			if (result.remedy) note(context)(result.remedy);
+			return {
+				platform: "web",
+				facts: result.facts
+			};
+		}
+		default: throw new StimError({
+			code: "STIM_BAD_ARG",
+			message: "Unknown Stim platform."
+		});
+	}
+}
+//#endregion
 export { StimError, createStim };