stim 1.0.0 → 1.2.0

package/dist/device-pool-B5pEVa3t.mjs

@@ -0,0 +1,408 @@
+import { a as formatElapsed, r as clockTime } from "./command-output-8wHMEde0.mjs";
+import { A as APP_READINESS_TIMEOUT_MS, l as VERIFY_TIMEOUT_MS } from "./app-install-NFxUahnH.mjs";
+import { a as parseLease, c as releaseRunLease, d as selectPoolDevice, f as takeLease, n as fileLeaseIo, r as leaseIsExpired, s as raiseLease, t as deviceLeasePath } from "./device-lease-Dpik41RY.mjs";
+//#region src/engine/device-lease-run.ts
+const LEASE_STEP_FLOOR_MS = 6e4;
+const DEBUG_VERIFY_STEP_MS = VERIFY_TIMEOUT_MS + APP_READINESS_TIMEOUT_MS;
+const DEVICE_WAIT_POLL_MS = 2e3;
+const DEVICE_BUSY = "STIM_DEVICE_BUSY";
+const DEVICE_LOST = "STIM_DEVICE_LOST";
+function leaseStepMs(boundMs = 0) {
+	return Math.max(LEASE_STEP_FLOOR_MS, boundMs);
+}
+function parseDeviceWait(value) {
+	if (value === void 0 || value === null) return { seconds: 60 };
+	const seconds = String(value).trim() === "" ? NaN : Number(value);
+	if (!Number.isInteger(seconds) || seconds < 0) return { error: `Invalid --wait value ${JSON.stringify(value)}. Pass a whole number of seconds, e.g. --wait 90.` };
+	return { seconds };
+}
+function waitFlagConflict(argv) {
+	return argv.some((arg) => arg === "--wait" || arg.startsWith("--wait=")) && argv.includes("--no-wait");
+}
+function leaseExpiryText(expiresAt, now) {
+	const remaining = Date.parse(expiresAt) - now;
+	return `${clockTime(expiresAt)} (${formatElapsed(Math.max(0, remaining))} from now)`;
+}
+function describeDevice(lease) {
+	return lease.deviceName ? `${lease.deviceName} (${lease.id})` : lease.id;
+}
+function facts(lease) {
+	return {
+		platform: lease.platform,
+		id: lease.id,
+		deviceName: lease.deviceName,
+		holder: lease.holder,
+		expiresAt: lease.expiresAt
+	};
+}
+function waitingLine(lease, now) {
+	return `waiting for ${lease.holder} to release ${describeDevice(lease)}; its lease runs until ${leaseExpiryText(lease.expiresAt, now)} -- stim guide lifecycle lease`;
+}
+function appIdMatch(ours, theirs) {
+	if (!ours || !theirs) return "unknown";
+	return ours === theirs ? "same" : "different";
+}
+function bypassLines(lease, now, match) {
+	const consequence = {
+		same: "Both workspaces build the same app id, so this install terminates the app that workspace is running.",
+		different: "The other workspace's app id differs, so the launch below backgrounds it rather than ending it.",
+		unknown: "Stim cannot tell whether the two workspaces build the same app id; if they do, this install terminates the holder's running app."
+	}[match];
+	return [`--no-wait: ${lease.holder} holds ${describeDevice(lease)} until ${leaseExpiryText(lease.expiresAt, now)}, and this run is proceeding without a lease.`, consequence];
+}
+function busyRefusal({ lease, now, idLabel, waitSeconds }) {
+	return {
+		code: DEVICE_BUSY,
+		message: `${lease.holder} holds ${describeDevice(lease)} until ${leaseExpiryText(lease.expiresAt, now)}` + (waitSeconds > 0 ? `, and this command waited ${waitSeconds}s for it.` : "."),
+		remedy: `Wait longer with \`--wait <seconds>\`, pick another device with \`--device <${idLabel}>\`, or pass \`--no-wait\` to install anyway -- which takes no lease and, when both workspaces build the same app id, terminates the holder's running app.`,
+		lease: facts(lease)
+	};
+}
+function unreadableRefusal(path) {
+	return {
+		code: DEVICE_BUSY,
+		message: `The lease file at ${path} does not parse, so Stim cannot tell who holds that device.`,
+		remedy: `Read ${path} and, once you know no run depends on it, delete it. \`stim gc\` reports it on every run.`,
+		lease: {
+			platform: null,
+			id: null,
+			deviceName: null,
+			holder: null,
+			expiresAt: null
+		}
+	};
+}
+function untokenedRefusal(lease, now) {
+	return {
+		code: DEVICE_BUSY,
+		message: `This workspace holds ${describeDevice(lease)} until ${leaseExpiryText(lease.expiresAt, now)}, but its own record of that lease is gone, so this run cannot prove the lease is still its own.`,
+		remedy: "Run `stim device unlock`, which releases by holder, then run this command again.",
+		lease: facts(lease)
+	};
+}
+function otherDeviceRefusal(leasedId, requestedId) {
+	return {
+		code: "STIM_NO_DEVICE",
+		message: `This workspace already leases ${leasedId}, and this run asked for ${requestedId}.`,
+		remedy: `Run \`stim device unlock\` to give up ${leasedId}, or use it with \`--device ${leasedId}\`.`,
+		lease: null
+	};
+}
+function lostLine(holder, expiresAt, now) {
+	return `${holder ?? "another workspace"} took this device's lease${expiresAt ? ` until ${leaseExpiryText(expiresAt, now)}` : ""}. The app is already installed, so this run continues without one.`;
+}
+function lostRefusal(holder, expiresAt, now) {
+	const who = holder ?? "another workspace";
+	const until = expiresAt ? ` until ${leaseExpiryText(expiresAt, now)}` : "";
+	return {
+		code: DEVICE_LOST,
+		message: `${who} took this device's lease${until} before this run could install.`,
+		remedy: "Run this command again; it waits for that lease with `--wait <seconds>`.",
+		lease: null
+	};
+}
+function runLease({ root, platform, kind, expiresAt, io = fileLeaseIo }) {
+	const handle = {
+		kind,
+		expiresAt,
+		lost: false,
+		raise(boundMs) {
+			if (handle.kind === null || handle.lost) return {
+				ok: !handle.lost,
+				holder: null,
+				expiresAt: handle.expiresAt
+			};
+			const result = raiseLease({
+				root,
+				platform,
+				minMs: leaseStepMs(boundMs)
+			}, io);
+			if (result.status === "raised") {
+				handle.expiresAt = result.lease.expiresAt;
+				return {
+					ok: true,
+					holder: result.lease.holder,
+					expiresAt: result.lease.expiresAt
+				};
+			}
+			handle.lost = true;
+			const taken = result.status === "lost" ? result.lease : null;
+			return {
+				ok: false,
+				holder: taken?.holder ?? null,
+				expiresAt: taken?.expiresAt ?? null
+			};
+		},
+		release() {
+			if (handle.kind === null) return;
+			releaseRunLease({
+				root,
+				platform
+			}, io);
+		},
+		facts() {
+			if (handle.kind === null || handle.lost || handle.expiresAt === null) return null;
+			return {
+				kind: handle.kind,
+				expiresAt: handle.expiresAt
+			};
+		}
+	};
+	return handle;
+}
+const SIGNAL_EXIT_CODES = {
+	SIGINT: 130,
+	SIGTERM: 143
+};
+function releaseLeaseOnSignal(release, { on = (signal, handler) => {
+	process.once(signal, handler);
+}, off = (signal, handler) => {
+	process.off(signal, handler);
+}, exit = (code) => process.exit(code) } = {}) {
+	const installed = [];
+	for (const signal of Object.keys(SIGNAL_EXIT_CODES)) {
+		const handler = () => {
+			release();
+			exit(SIGNAL_EXIT_CODES[signal]);
+		};
+		installed.push([signal, handler]);
+		on(signal, handler);
+	}
+	return () => {
+		for (const [signal, handler] of installed) off(signal, handler);
+		installed.length = 0;
+	};
+}
+async function waitForDevice({ root, platform, id, idLabel, waitSeconds, noWait = false, appId = null, holderAppId = () => null, now = Date.now, sleep = (ms) => new Promise((r) => setTimeout(r, ms)), warn = () => {}, io = fileLeaseIo, deadline, lastLine }) {
+	const path = deviceLeasePath(platform, id);
+	for (;;) {
+		const raw = io.readLease(path);
+		const current = parseLease(raw);
+		if (raw !== null && !current) return {
+			status: "refused",
+			refusal: unreadableRefusal(path)
+		};
+		if (!current || leaseIsExpired(current, now())) return { status: "free" };
+		if (current.holder === root) return {
+			status: "ours",
+			lease: current
+		};
+		if (noWait) {
+			for (const line of bypassLines(current, now(), appIdMatch(appId, holderAppId(current.holder)))) warn(line);
+			return {
+				status: "bypassed",
+				lease: current
+			};
+		}
+		if (now() >= deadline) return {
+			status: "refused",
+			refusal: busyRefusal({
+				lease: current,
+				now: now(),
+				idLabel,
+				waitSeconds
+			})
+		};
+		if (lastLine.at === null || now() - lastLine.at >= 3e4) {
+			lastLine.at = now();
+			warn(waitingLine(current, now()));
+		}
+		await sleep(DEVICE_WAIT_POLL_MS);
+	}
+}
+async function acquireRunLease({ root, platform, id, deviceName = null, idLabel, waitSeconds, noWait, installBoundMs, appId = null, holderAppId = () => null, now = Date.now, sleep = (ms) => new Promise((r) => setTimeout(r, ms)), warn = () => {}, io = fileLeaseIo }) {
+	const recorded = io.readHolder(root)[platform];
+	let held = recorded;
+	if (recorded && recorded.id !== id) {
+		const other = parseLease(io.readLease(deviceLeasePath(platform, recorded.id)));
+		if (other && other.token === recorded.token && !leaseIsExpired(other, now())) return {
+			status: "refused",
+			refusal: otherDeviceRefusal(recorded.id, id)
+		};
+		held = void 0;
+	}
+	const path = deviceLeasePath(platform, id);
+	const deadline = now() + waitSeconds * 1e3;
+	const lastLine = { at: null };
+	for (;;) {
+		const current = parseLease(io.readLease(path));
+		const mine = current && held && current.token === held.token ? {
+			lease: current,
+			record: held
+		} : null;
+		if (mine && (mine.record.kind === "run" || !leaseIsExpired(mine.lease, now()))) {
+			const raised = raiseLease({
+				root,
+				platform,
+				minMs: leaseStepMs(installBoundMs)
+			}, io);
+			if (raised.status === "raised") return {
+				status: "leased",
+				kind: mine.record.kind,
+				expiresAt: raised.lease.expiresAt
+			};
+		}
+		const outcome = await waitForDevice({
+			root,
+			platform,
+			id,
+			idLabel,
+			waitSeconds,
+			noWait,
+			appId,
+			holderAppId,
+			now,
+			sleep,
+			warn,
+			io,
+			deadline,
+			lastLine
+		});
+		if (outcome.status === "refused") return outcome;
+		if (outcome.status === "bypassed") return { status: "unleased" };
+		if (outcome.status === "ours") return {
+			status: "refused",
+			refusal: untokenedRefusal(outcome.lease, now())
+		};
+		const taken = takeLease({
+			root,
+			platform,
+			id,
+			deviceName,
+			kind: "run",
+			durationMs: leaseStepMs(installBoundMs)
+		}, io);
+		if (taken.status === "unreadable") return {
+			status: "refused",
+			refusal: unreadableRefusal(taken.path)
+		};
+		if (taken.status === "taken" || taken.status === "set") return {
+			status: "leased",
+			kind: taken.status === "set" ? held?.kind ?? "run" : "run",
+			expiresAt: taken.lease.expiresAt
+		};
+	}
+}
+//#endregion
+//#region src/engine/device-pool.ts
+function heldPoolId(root, platform, now, io = fileLeaseIo) {
+	const record = io.readHolder(root)[platform];
+	if (!record) return null;
+	const lease = parseLease(io.readLease(deviceLeasePath(platform, record.id)));
+	if (!lease || lease.token !== record.token || leaseIsExpired(lease, now)) return null;
+	return record.id;
+}
+function readPool(platform, candidates, io) {
+	const reading = {
+		usable: [],
+		leases: [],
+		unreadable: []
+	};
+	for (const candidate of candidates) {
+		const path = deviceLeasePath(platform, candidate.id);
+		const raw = io.readLease(path);
+		const lease = parseLease(raw);
+		if (raw !== null && !lease) {
+			reading.unreadable.push(path);
+			continue;
+		}
+		reading.usable.push(candidate);
+		if (lease) reading.leases.push(lease);
+	}
+	return reading;
+}
+function disconnectedHeldRefusal(id, idLabel) {
+	return {
+		code: "STIM_NO_DEVICE",
+		message: `This workspace leases ${id}, and it is not connected.`,
+		remedy: `Run \`stim device unlock\` to give it up, then run this command again. Naming another \`--device <${idLabel}>\` refuses the same way while this lease is held.`,
+		lease: null
+	};
+}
+const NO_LEASE_FACTS = {
+	platform: null,
+	id: null,
+	deviceName: null,
+	holder: null,
+	expiresAt: null
+};
+function unreadableSentence(unreadable) {
+	return unreadable.length ? ` Unreadable lease file, so no run may take that device around it: ${unreadable.join("; ")}.` : "";
+}
+function poolBusyRefusal(holders, leases, unreadable, now, waitSeconds) {
+	const named = holders.map((holder) => `${holder.id} (${holder.holder}, until ${leaseExpiryText(holder.expiresAt, now)})`);
+	const first = holders[0];
+	const lease = first ? leases.find((entry) => entry.id === first.id) : void 0;
+	if (!first) return {
+		code: DEVICE_BUSY,
+		message: `Every connected device has an unreadable lease file, so Stim cannot tell who holds them: ${unreadable.join("; ")}.`,
+		remedy: "Read each file and, once you know no run depends on it, delete it. `stim gc` reports them on every run.",
+		lease: NO_LEASE_FACTS
+	};
+	return {
+		code: DEVICE_BUSY,
+		message: `Every connected device is leased by another workspace${waitSeconds > 0 ? `, and this run waited ${waitSeconds}s for one` : ""}: ${named.join("; ")}.${unreadableSentence(unreadable)}`,
+		remedy: "Wait longer with `--wait <seconds>`, connect another device, or pass `--no-wait` to install anyway -- which takes no lease and, when both workspaces build the same app id, terminates the holder's running app.",
+		lease: {
+			platform: lease?.platform ?? null,
+			id: first.id,
+			deviceName: lease?.deviceName ?? null,
+			holder: first.holder,
+			expiresAt: first.expiresAt
+		}
+	};
+}
+async function selectFromPool({ root, platform, idLabel, list, noCandidates, waitSeconds, deadline, noWait = false, now = Date.now, sleep = (ms) => new Promise((r) => setTimeout(r, ms)), warn = () => {}, io = fileLeaseIo }) {
+	const held = heldPoolId(root, platform, now(), io);
+	const until = deadline ?? now() + waitSeconds * 1e3;
+	let lastLine = null;
+	for (;;) {
+		const { usable, leases, unreadable } = readPool(platform, list(), io);
+		const selection = selectPoolDevice({
+			candidates: usable,
+			leases,
+			held,
+			now: now()
+		});
+		if (selection.status === "selected") return selection;
+		if (selection.status === "held-disconnected") return {
+			status: "refused",
+			refusal: disconnectedHeldRefusal(selection.id, idLabel)
+		};
+		if (selection.status === "none") {
+			if (unreadable.length) return {
+				status: "refused",
+				refusal: poolBusyRefusal([], leases, unreadable, now(), waitSeconds)
+			};
+			const { message, remedy } = noCandidates();
+			return {
+				status: "refused",
+				refusal: {
+					code: "STIM_NO_DEVICE",
+					message,
+					remedy,
+					lease: null
+				}
+			};
+		}
+		const first = selection.holders[0];
+		if (noWait && first) {
+			const candidate = usable.find((entry) => entry.id === first.id);
+			if (candidate) return {
+				status: "selected",
+				candidate
+			};
+		}
+		if (now() >= until) return {
+			status: "refused",
+			refusal: poolBusyRefusal(selection.holders, leases, unreadable, now(), waitSeconds)
+		};
+		if (lastLine === null || now() - lastLine >= 3e4) {
+			lastLine = now();
+			warn(`waiting for a free device; every connected one is leased: ${selection.holders.map((holder) => `${holder.id} (${holder.holder}, until ${leaseExpiryText(holder.expiresAt, now())})`).join("; ")}`);
+		}
+		await sleep(DEVICE_WAIT_POLL_MS);
+	}
+}
+//#endregion
+export { lostLine as a, releaseLeaseOnSignal as c, waitForDevice as d, leaseExpiryText as i, runLease as l, DEBUG_VERIFY_STEP_MS as n, lostRefusal as o, acquireRunLease as r, parseDeviceWait as s, selectFromPool as t, waitFlagConflict as u };