stim 1.25.0 → 1.26.0

package/dist/{config-BZhXY15H.mjs → config-BktkY_zC.mjs}

@@ -4,6 +4,7 @@ import { join } from "node:path";
 import { ambientEnv, configDir, ensurePrivateDir } from "@stim-cli/core";
 import { allMetroPorts, cannotHost, clientIdentity, configCorruptRepair, endpoint, findEnclosingWorktreeRoot, findPeer as findPeer$1, getConcurrencyLimits, getConfigPath, getConfigPath as getConfigPath$1, getProject, getProjectSettings, getRepoSettings, isJsonObject, isPathPrefix, loadConfig, loadConfig as loadConfig$1, machineEndpoint, parseMachine, parseMachine as parseMachine$1, validateAutomaticPool, withConfigLock, withConfigLock as withConfigLock$1, withConfigLockAsync, withConfigLockAsync as withConfigLockAsync$1 } from "@stim-cli/core/state";
 import { dirname as dirname$1, isAbsolute as isAbsolute$1, join as join$1, normalize, parse, sep as sep$1 } from "path";
+import { request } from "node:https";
 import { WebSocket } from "ws";
 import { HandshakeRefusal, MAX_SERVER_MESSAGE_BYTES, TRANSPORT_OVERHEAD_BYTES, decodeSecret, initiateNoise, newSecret } from "@stim-cli/core/noise-session";
 import { existsSync, lstatSync, readdirSync, readlinkSync, renameSync, statSync, unlinkSync, writeFileSync } from "fs";
@@ -23,19 +24,246 @@ function readHostPermissions(value) {
 	} : void 0;
 }
 //#endregion
+//#region src/offload/diagnosis.ts
+const SILENT_ERRORS = /* @__PURE__ */ new Set([
+	"ETIMEDOUT",
+	"EHOSTUNREACH",
+	"ENETUNREACH",
+	"EHOSTDOWN"
+]);
+function classifyTransport(error, status) {
+	if (status !== void 0) return {
+		kind: "http",
+		status
+	};
+	const code = error.code ?? "";
+	if (code === "ECONNREFUSED") return { kind: "refused" };
+	if (SILENT_ERRORS.has(code) || /handshake has timed out/i.test(error.message)) return { kind: "silent" };
+	if (/^(ERR_TLS_|CERT_|UNABLE_TO_|DEPTH_ZERO|SELF_SIGNED|ERR_SSL_)/.test(code) || /certificate|SSL|TLS/i.test(error.message)) return {
+		kind: "tls",
+		message: error.message
+	};
+	return {
+		kind: "other",
+		message: error.message
+	};
+}
+/** The `startup` a 503 `/health` body from a peer carries, when it is the shape stim-server sends. */
+function parsePeerStartup(body) {
+	const startup = isJsonObject(body) && isJsonObject(body.startup) ? body.startup : null;
+	if (!startup || startup.state !== "pending" && startup.state !== "degraded") return null;
+	const cause = startup.cause === "home-unreadable" || startup.cause === "start-failed" ? startup.cause : void 0;
+	return {
+		state: startup.state,
+		...cause ? { cause } : {}
+	};
+}
+function readTailscale(status) {
+	if (!isJsonObject(status)) return {
+		running: false,
+		code: "tailscale-unavailable"
+	};
+	switch (status.BackendState) {
+		case "Running": return { running: true };
+		case "NeedsLogin":
+		case "NeedsMachineAuth": return {
+			running: false,
+			code: "tailscale-logged-out"
+		};
+		default: return {
+			running: false,
+			code: "tailscale-stopped"
+		};
+	}
+}
+function tailscaleDiagnosis(code) {
+	switch (code) {
+		case "tailscale-logged-out": return {
+			layer: "tailscale",
+			code,
+			title: "Tailscale signed out",
+			message: "Tailscale on this Mac is signed out, so it cannot reach any remote machine.",
+			remedy: "Sign in to Tailscale on this Mac (its menu bar app, or `tailscale up`), then run `stim doctor` again."
+		};
+		case "tailscale-stopped": return {
+			layer: "tailscale",
+			code,
+			title: "Tailscale is off",
+			message: "Tailscale is turned off on this Mac, so it cannot reach any remote machine.",
+			remedy: "Turn on Tailscale on this Mac (its menu bar app, or `tailscale up`), then run `stim doctor` again."
+		};
+		case "tailscale-unavailable": return {
+			layer: "tailscale",
+			code,
+			title: "Tailscale is off",
+			message: "Tailscale is not running on this Mac or is not installed, so it cannot reach any remote machine.",
+			remedy: "Install Tailscale or open it on this Mac and sign in, then run `stim doctor` again."
+		};
+	}
+}
+function notOnTailnetDiagnosis(entry, ambiguous) {
+	return {
+		layer: "peer",
+		code: ambiguous ? "peer-ambiguous" : "peer-not-found",
+		title: ambiguous ? "Name is ambiguous" : "Not on the tailnet",
+		message: ambiguous ? `Several peers on this tailnet match ${entry}.` : `No peer on this tailnet is named ${entry}.`,
+		remedy: ambiguous ? `Use the full MagicDNS name in remote.machines (see \`tailscale status\`).` : `Check the name in \`tailscale status\`, or sign in to Tailscale on ${entry} with the same account.`
+	};
+}
+function ago(iso, now) {
+	const then = iso ? Date.parse(iso) : NaN;
+	if (!Number.isFinite(then) || then <= 0) return null;
+	const minutes = Math.max(0, Math.round((now - then) / 6e4));
+	if (minutes < 1) return "less than a minute ago";
+	if (minutes < 60) return `${minutes} min ago`;
+	const hours = Math.round(minutes / 60);
+	if (hours < 48) return `${hours} h ago`;
+	return `${Math.round(hours / 24)} days ago`;
+}
+const sentence = (text) => text.replace(/\s+$/, "").replace(/([^.!?])$/, "$1.");
+/**
+* Tailscale's `Online` lags a reachable peer, so `peer-offline` needs a silent connection; any other outcome,
+* including one past the transport (no `transport`), shows the peer answered.
+*/
+function diagnoseUnreachable(input) {
+	const { entry, peer, port, transport, now = Date.now() } = input;
+	const route = `https port ${port}`;
+	if (transport?.kind === "silent" && input.pinged === true) return {
+		layer: "server",
+		code: "server-no-answer",
+		title: "Server not answering",
+		message: `${entry} answers on Tailscale, but its serve route and stim-server sent no reply in time. stim-server may be starting, stalled or restarting.`,
+		remedy: `On ${entry}, run \`stim-server service status\`; it reports a restart loop or a Stim home it is still reading, and the log file to read.`
+	};
+	if (peer.online === false && transport?.kind === "silent") {
+		const seen = ago(peer.lastSeen, now);
+		return {
+			layer: "peer",
+			code: "peer-offline",
+			title: "Mac is offline",
+			message: `${entry} is offline on Tailscale${seen ? ` (last seen ${seen})` : ""}.`,
+			remedy: `Wake ${entry} or check that it is powered on, connected to a network and signed in to Tailscale, then run \`stim doctor\` again.`
+		};
+	}
+	if (transport?.kind === "refused") return {
+		layer: "route",
+		code: "route-missing",
+		title: "No serve route",
+		message: `${entry} answers on the tailnet, but nothing accepts connections on ${route}, so it has no tailscale serve route for stim-server.`,
+		remedy: `On ${entry}, run \`stim-server service status\`; \`stim-server service install --serve\` creates the route.`
+	};
+	if (transport?.kind === "silent") return {
+		layer: "peer",
+		code: "peer-no-answer",
+		title: "Mac not answering",
+		message: `${entry} did not answer the connection, and Tailscale does not list it as offline.`,
+		remedy: `Check that ${entry} is awake and its network is up; \`tailscale ping ${entry}\` on this Mac tests the path.`
+	};
+	if (transport?.kind === "tls") return {
+		layer: "route",
+		code: "route-tls",
+		title: "Route certificate",
+		message: `The tailscale serve route on ${entry} (${route}) did not present a certificate this Mac accepts: ${sentence(transport.message)}`,
+		remedy: `On ${entry}, run \`tailscale serve status\`, then \`stim-server service install --serve\` to recreate the route.`
+	};
+	if (transport?.kind === "http") {
+		const { status } = transport;
+		if (status === 502) return {
+			layer: "server",
+			code: "server-not-running",
+			title: "Server not running",
+			message: `Tailscale and the serve route on ${entry} work, but nothing listens behind the route: stim-server is not running there (HTTP 502).`,
+			remedy: `On ${entry}, run \`stim-server service status\`; \`stim-server service install --serve\` starts it and keeps it running.`
+		};
+		if (status === 503) {
+			const startup = input.startup;
+			const why = startup?.cause === "home-unreadable" ? " It cannot read its Stim home, usually because the disk holding ~/.stim is disconnected or not responding." : startup?.cause === "start-failed" ? " It failed while starting." : startup?.state === "pending" ? " It is still starting." : "";
+			const check = startup?.cause === "home-unreadable" ? `Check the disk that holds the Stim home on ${entry} (reconnect or wake an external drive); stim-server serves again by itself once it answers. \`stim-server service status\` there shows the exact reason.` : startup?.state === "pending" ? `Wait a few seconds and run \`stim doctor\` again.` : `On ${entry}, run \`stim-server service status\` for the reason; the log file it prints has the rest.`;
+			return {
+				layer: "server",
+				code: "server-not-ready",
+				title: "Server not ready",
+				message: `stim-server on ${entry} is running but is not serving clients (HTTP 503).${why}`,
+				remedy: check
+			};
+		}
+		return {
+			layer: "route",
+			code: "route-http-error",
+			title: `Route answers ${status}`,
+			message: `The tailscale serve route on ${entry} (${route}) answered HTTP ${status}, which stim-server does not send for a connection.`,
+			remedy: `On ${entry}, run \`tailscale serve status\` and check what the route on port ${port} points to.`
+		};
+	}
+	return {
+		layer: "server",
+		code: "connect-failed",
+		title: "Not answering",
+		message: `Could not connect to stim-server on ${entry}: ${sentence(input.reason)}`,
+		remedy: `On ${entry}, run \`stim-server service status\`. To keep it running there, run \`stim-server service install --serve\`.`
+	};
+}
+function diagnosisFinding(code, entry, diagnosis) {
+	return {
+		code,
+		level: "note",
+		title: `Remote machine ${entry}: ${diagnosis.title}`,
+		detail: diagnosis.message,
+		fix: diagnosis.remedy
+	};
+}
+//#endregion
 //#region src/offload/tailnet.ts
 const MAC_APP_TAILSCALE = "/Applications/Tailscale.app/Contents/MacOS/Tailscale";
 const HELLO_TIMEOUT_MS = 1e4;
+const HEALTH_TIMEOUT_MS = 3e3;
 /** How long a setup ticket `stim doctor --fix` generates stays valid; `stim-server setup` takes at most 2 hours. */
 const GENERATED_TICKET_MS = 714e4;
-function parseTailscaleStatus(output) {
+function parseJson(output) {
 	try {
-		const status = JSON.parse(output);
-		return isJsonObject(status) && status.BackendState === "Running" ? status : null;
+		return JSON.parse(output);
 	} catch {
 		return null;
 	}
 }
+function parseTailscaleStatus(output) {
+	const status = parseJson(output);
+	return isJsonObject(status) && status.BackendState === "Running" ? status : null;
+}
+function rawTailscaleStatus() {
+	for (const binary of ["tailscale", MAC_APP_TAILSCALE]) {
+		const output = getExecutor().runFileQuiet(binary, ["status", "--json"], { timeoutMs: 5e3 });
+		if (output !== null) return parseJson(output);
+	}
+	return null;
+}
+/** Reads the `startup` of a peer's `/health`, which stim-server answers with 503 while it is not serving clients. */
+function peerStartup({ url, servername, host }) {
+	return new Promise((resolve) => {
+		const base = new URL(url);
+		const request$1 = request({
+			host: base.hostname.replace(/^\[|\]$/g, ""),
+			port: base.port || 443,
+			path: "/health",
+			servername,
+			headers: { Host: host },
+			timeout: HEALTH_TIMEOUT_MS
+		}, (response) => {
+			const chunks = [];
+			let size = 0;
+			response.on("data", (chunk) => {
+				size += chunk.length;
+				if (size > 4096) request$1.destroy();
+				else chunks.push(chunk);
+			});
+			response.on("end", () => resolve(parsePeerStartup(parseJson(Buffer.concat(chunks).toString("utf8")))));
+			response.on("error", () => resolve(null));
+		});
+		request$1.on("timeout", () => request$1.destroy());
+		request$1.on("error", () => resolve(null));
+		request$1.end();
+	});
+}
 function tailscaleStatus() {
 	for (const binary of ["tailscale", MAC_APP_TAILSCALE]) {
 		const output = getExecutor().runFileQuiet(binary, ["status", "--json"], { timeoutMs: 5e3 });
@@ -43,7 +271,7 @@ function tailscaleStatus() {
 	}
 	return null;
 }
-async function tailscaleStatusAsync(signal) {
+async function tailscaleOutputAsync(signal) {
 	for (const binary of ["tailscale", MAC_APP_TAILSCALE]) {
 		signal?.throwIfAborted();
 		let output;
@@ -57,10 +285,42 @@ async function tailscaleStatusAsync(signal) {
 			continue;
 		}
 		signal?.throwIfAborted();
-		return parseTailscaleStatus(output);
+		return output;
 	}
 	return null;
 }
+async function tailscaleStatusAsync(signal) {
+	const output = await tailscaleOutputAsync(signal);
+	return output === null ? null : parseTailscaleStatus(output);
+}
+async function pingPeer(address, signal) {
+	for (const binary of ["tailscale", MAC_APP_TAILSCALE]) {
+		signal?.throwIfAborted();
+		try {
+			await getExecutor().runFileAsync(binary, [
+				"ping",
+				"--c",
+				"1",
+				"--until-direct=false",
+				"--timeout",
+				"4s",
+				address
+			], {
+				timeoutMs: 6e3,
+				signal
+			});
+			return true;
+		} catch (error) {
+			signal?.throwIfAborted();
+			if (!/ENOENT|not found/i.test(String(error))) return false;
+		}
+	}
+	return false;
+}
+async function rawTailscaleStatusAsync(signal) {
+	const output = await tailscaleOutputAsync(signal);
+	return output === null ? null : parseJson(output);
+}
 const TURNED_AWAY = /* @__PURE__ */ new Set([
 	"unauthorized",
 	"forbidden",
@@ -106,6 +366,7 @@ function openAuthenticated(target, auth, timeoutMs, signal, operation) {
 				socket.removeAllListeners("open");
 				socket.removeAllListeners("message");
 				socket.removeAllListeners("error");
+				socket.removeAllListeners("unexpected-response");
 				socket.on("error", () => {});
 				socket.terminate();
 			}
@@ -116,18 +377,33 @@ function openAuthenticated(target, auth, timeoutMs, signal, operation) {
 			refused: false,
 			code: "STIM_CANCELLED"
 		});
+		let opened = false;
 		const timer = setTimeout(() => finish({
 			failure: "no reply in time",
-			refused: false
+			refused: false,
+			transport: opened ? {
+				kind: "other",
+				message: "the handshake got no reply"
+			} : { kind: "silent" }
 		}), timeoutMs);
 		signal?.addEventListener("abort", cancel, { once: true });
 		if (signal?.aborted) return cancel();
-		const failed = (error) => finish({
-			failure: /Unexpected server response: 502/.test(error.message) ? "no stim-server answers behind its tailscale serve route (HTTP 502)" : error.message,
-			refused: false
+		const failed = (error, status) => finish({
+			failure: status === 502 ? "no stim-server answers behind its tailscale serve route (HTTP 502)" : status === 503 ? "stim-server answers behind its tailscale serve route but is not serving clients (HTTP 503)" : status !== void 0 ? `its tailscale serve route answered HTTP ${status}` : error.message,
+			refused: false,
+			transport: opened && status === void 0 ? {
+				kind: "other",
+				message: error.message
+			} : classifyTransport(error, status)
+		});
+		socket.once("unexpected-response", (request, response) => {
+			response.resume();
+			request.destroy();
+			failed(/* @__PURE__ */ new Error(`Unexpected server response: ${response.statusCode}`), response.statusCode);
 		});
 		socket.once("error", failed);
 		socket.once("open", () => {
+			opened = true;
 			const secret = "ticket" in auth ? decodeSecret(auth.ticket) : null;
 			let keyPair;
 			try {
@@ -215,7 +491,10 @@ async function hello(target, auth, operation) {
 	if (!("send" in socket)) return socket.code ? { error: {
 		code: socket.code,
 		message: socket.failure
-	} } : { failed: socket.failure };
+	} } : {
+		failed: socket.failure,
+		...socket.transport ? { transport: socket.transport } : {}
+	};
 	try {
 		if ("onServerKey" in auth) await auth.onServerKey?.(socket.remoteKey.toString("base64url"));
 	} catch (error) {
@@ -241,14 +520,39 @@ async function hello(target, auth, operation) {
 }
 const realIo = {
 	status: tailscaleStatus,
-	hello
+	hello,
+	rawStatus: rawTailscaleStatus,
+	startup: peerStartup,
+	ping: (address) => pingPeer(address)
 };
 function doctorIo(operation) {
 	return {
 		status: () => tailscaleStatusAsync(operation?.signal),
-		hello: (target, auth) => hello(target, auth, operation)
+		hello: (target, auth) => hello(target, auth, operation),
+		rawStatus: () => rawTailscaleStatusAsync(operation?.signal),
+		startup: peerStartup,
+		ping: (address) => pingPeer(address, operation?.signal)
 	};
 }
+/**
+* Names the layer an unreachable `entry` stopped at. A 503 reads the peer's `/health` for why the server is not
+* serving; an older stim-server answers without it, and the diagnosis then says only that it is not ready.
+*/
+async function diagnoseOutcome(io, input) {
+	const { target, ...rest } = input;
+	const startup = rest.transport?.kind === "http" && rest.transport.status === 503 ? await io.startup?.(target) : null;
+	const pinged = rest.transport?.kind === "silent" ? await io.ping?.(rest.peer.address) : void 0;
+	return diagnoseUnreachable({
+		...rest,
+		startup,
+		pinged
+	});
+}
+/** Why `status` is null, as a diagnosis of the Tailscale layer; falls back to the daemon being unavailable. */
+async function diagnoseTailscale(io) {
+	const reading = readTailscale(io.rawStatus ? await io.rawStatus() : null);
+	return tailscaleDiagnosis(reading.running ? "tailscale-unavailable" : reading.code);
+}
 /** Where to reach a paired machine now, or why Stim cannot; the handshake then checks its pinned key. */
 async function resolveEndpoint(credential, status = () => tailscaleStatusAsync(signal), signal) {
 	return machineEndpoint(credential.machine, parseMachine(credential.machine) ? await status() : null);
@@ -357,7 +661,8 @@ async function reachMachine(input) {
 		return {
 			state: "unreachable",
 			credential: pending,
-			reason: "failed" in reply ? reply.failed : "error" in reply ? reply.error.message : "it did not grant this access"
+			reason: "failed" in reply ? reply.failed : "error" in reply ? reply.error.message : "it did not grant this access",
+			..."failed" in reply && reply.transport ? { transport: reply.transport } : {}
 		};
 	};
 	if (!credential) return input.fix ? ask() : { state: "not-asked" };
@@ -389,7 +694,8 @@ async function reachMachine(input) {
 		return {
 			state: "unreachable",
 			credential,
-			reason: "failed" in reply ? reply.failed : reply.error.message
+			reason: "failed" in reply ? reply.failed : reply.error.message,
+			..."failed" in reply && reply.transport ? { transport: reply.transport } : {}
 		};
 	}
 	if (input.fix && given && given !== credential.ticket) return ask();
@@ -952,4 +1258,4 @@ function allConsolePortsAndSerials({ isMounted = isOnMountedVolume } = {}) {
 	return result;
 }
 //#endregion
-export { outdatedServer as $, writeConfigSettingAsync as A, deviceSlotFileKey as B, saveConfig as C, withConfigLock$1 as D, upsertProject as E, isOnMountedVolume as F, projectDeviceSlots as G, deviceSlotPlatforms as H, listMountedVolumes as I, SERVER_OUTDATED as J, removeSlotDevice as K, measuredDirectorySizeAsync as L, directorySize as M, directorySizeAsync as N, withConfigLockAsync$1 as O, formatBytes as P, openAuthenticated as Q, volumeRootFor as R, removeProject as S, setSupervisor as T, parseDeviceSlotKey as U, deviceSlotKey as V, parseDeviceSlotOption as W, endpoint as X, doctorIo as Y, findPeer$1 as Z, loadConfig$1 as _, clearDevice as a, setupRemedy as at, releaseAndroidConsolePort as b, ensureConfig as c, getConfigDir as d, parseMachine$1 as et, getConfigPath$1 as f, isPathPrefix as g, getRepoSettings as h, clearAndroidBootPending as i, sayHello as it, acquireAvdClaim as j, writeConfigSetting as k, findEnclosingWorktreeRoot as l, getProjectSettings as m, allMetroPorts as n, realIo as nt, clearSupervisor as o, tailscaleStatusAsync as ot, getProject as p, validateDeviceSlot as q, claimMetroPort as r, resolveEndpoint as rt, configCorruptRepair as s, readHostPermissions as st, allConsolePortsAndSerials as t, reachMachine as tt, getConcurrencyLimits as u, recordIosSchemeApprovals as v, setDevice as w, releaseMetroPort as x, refuseRelativeStimPaths as y, assignSlotDevice as z };
+export { findPeer$1 as $, writeConfigSettingAsync as A, deviceSlotFileKey as B, saveConfig as C, withConfigLock$1 as D, upsertProject as E, isOnMountedVolume as F, projectDeviceSlots as G, deviceSlotPlatforms as H, listMountedVolumes as I, SERVER_OUTDATED as J, removeSlotDevice as K, measuredDirectorySizeAsync as L, directorySize as M, directorySizeAsync as N, withConfigLockAsync$1 as O, formatBytes as P, endpoint as Q, volumeRootFor as R, removeProject as S, setSupervisor as T, parseDeviceSlotKey as U, deviceSlotKey as V, parseDeviceSlotOption as W, diagnoseTailscale as X, diagnoseOutcome as Y, doctorIo as Z, loadConfig$1 as _, clearDevice as a, resolveEndpoint as at, releaseAndroidConsolePort as b, ensureConfig as c, tailscaleStatusAsync as ct, getConfigDir as d, readHostPermissions as dt, openAuthenticated as et, getConfigPath$1 as f, isPathPrefix as g, getRepoSettings as h, clearAndroidBootPending as i, realIo as it, acquireAvdClaim as j, writeConfigSetting as k, findEnclosingWorktreeRoot as l, diagnosisFinding as lt, getProjectSettings as m, allMetroPorts as n, parseMachine$1 as nt, clearSupervisor as o, sayHello as ot, getProject as p, validateDeviceSlot as q, claimMetroPort as r, reachMachine as rt, configCorruptRepair as s, setupRemedy as st, allConsolePortsAndSerials as t, outdatedServer as tt, getConcurrencyLimits as u, notOnTailnetDiagnosis as ut, recordIosSchemeApprovals as v, setDevice as w, releaseMetroPort as x, refuseRelativeStimPaths as y, assignSlotDevice as z };