pi-cursor-sdk 0.1.27 → 0.1.29

package/scripts/platform-smoke/crabbox-runner.mjs

@@ -0,0 +1,215 @@
+/**
+ * Crabbox runner — thin wrapper around the Crabbox CLI.
+ *
+ * Handles warmup, sync-aware run, stop, and artifact collection.
+ * Never prints CURSOR_API_KEY.
+ */
+
+import { spawn } from "node:child_process";
+
+const CRABBOX_BIN = process.env.PLATFORM_SMOKE_CRABBOX || "crabbox";
+
+function env(name) { return process.env[name] ?? ""; }
+
+function buildCrabboxEnv(opts = {}) {
+	const env = { ...process.env, CRABBOX_SYNC_GIT_SEED: "false", ...opts.env };
+	const allowed = new Set(opts.allowEnv ?? []);
+	if (!allowed.has("CURSOR_API_KEY")) delete env.CURSOR_API_KEY;
+	return env;
+}
+
+/** Run a crabbox command, returning stdout+stderr+exit+signal. */
+export function execCrabbox(args, opts = {}) {
+	return new Promise((resolvePromise) => {
+		const timeoutMs = opts.timeout ?? 0;
+		const child = spawn(CRABBOX_BIN, args, {
+			stdio: ["pipe", "pipe", "pipe"],
+			env: buildCrabboxEnv(opts),
+			...opts.spawnOpts,
+		});
+
+		const stdoutChunks = [];
+		const stderrChunks = [];
+		let timeout;
+		let killTimeout;
+		if (timeoutMs > 0) {
+			timeout = setTimeout(() => {
+				stderrChunks.push(Buffer.from(`\n[platform-smoke] crabbox command timed out after ${timeoutMs}ms\n`));
+				try { child.kill("SIGTERM"); } catch {}
+				killTimeout = setTimeout(() => {
+					try { child.kill("SIGKILL"); } catch {}
+				}, 10_000);
+			}, timeoutMs);
+		}
+
+		child.stdout.on("data", (d) => stdoutChunks.push(d));
+		child.stderr.on("data", (d) => stderrChunks.push(d));
+
+		child.on("close", (code, signal) => {
+			if (timeout) clearTimeout(timeout);
+			if (killTimeout) clearTimeout(killTimeout);
+			resolvePromise({
+				stdout: Buffer.concat(stdoutChunks).toString(),
+				stderr: Buffer.concat(stderrChunks).toString(),
+				code: code ?? (signal ? 1 : 0),
+				signal,
+			});
+		});
+
+		child.on("error", (err) => {
+			if (timeout) clearTimeout(timeout);
+			if (killTimeout) clearTimeout(killTimeout);
+			resolvePromise({
+				stdout: Buffer.concat(stdoutChunks).toString(),
+				stderr: (Buffer.concat(stderrChunks).toString() + "\n" + err.message).trim(),
+				code: 1,
+				signal: null,
+			});
+		});
+	});
+}
+
+/**
+ * Build the base crabbox args for a target (used for warmup, run, stop).
+ * These include provider, connection details, and work root.
+ * Callers should append command-specific flags/args.
+ */
+export function buildTargetBaseArgs(targetName, config = {}) {
+	switch (targetName) {
+		case "macos": {
+			const host = env("PLATFORM_SMOKE_MAC_HOST") || "localhost";
+			const user = env("PLATFORM_SMOKE_MAC_USER") || env("USER");
+			const workRoot = env("PLATFORM_SMOKE_MAC_WORK_ROOT") || `/Users/${env("USER")}/crabbox/pi-cursor-sdk`;
+			return [
+				"--provider", "ssh",
+				"--target", "macos",
+				"--static-host", host,
+				"--static-user", user,
+				"--static-port", "22",
+				"--static-work-root", workRoot,
+			];
+		}
+		case "ubuntu": {
+			const image = env("PLATFORM_SMOKE_UBUNTU_IMAGE") || config.ubuntuContainerImage || "cimg/node:24.16";
+			return [
+				"--provider", "local-container",
+				"--target", "linux",
+				"--local-container-image", image,
+			];
+		}
+		case "windows-native": {
+			const vm = env("PLATFORM_SMOKE_WINDOWS_VM") || "pi-extension-windows-template";
+			const snap = env("PLATFORM_SMOKE_WINDOWS_SNAPSHOT") || "crabbox-ready";
+			const user = env("PLATFORM_SMOKE_WINDOWS_USER") || env("USER");
+			const workRoot = env("PLATFORM_SMOKE_WINDOWS_NATIVE_WORK_ROOT") || "C:\\crabbox\\pi-cursor-sdk";
+			return [
+				"--provider", "parallels",
+				"--target", "windows",
+				"--windows-mode", "normal",
+				"--parallels-source", vm,
+				"--parallels-source-snapshot", snap,
+				"--parallels-user", user,
+				"--parallels-work-root", workRoot,
+			];
+		}
+		default:
+			throw new Error(`unknown target: ${targetName}`);
+	}
+}
+
+/**
+ * Get the internal lease ID for a target.
+ * For static SSH, this is "static_localhost".
+ * For local-container, it's the slug (pi-cursor-sdk-ubuntu).
+ * For parallels, it's the slug used during warmup.
+ */
+export function leaseIdFor(targetName) {
+	switch (targetName) {
+		case "macos": return "static_localhost";
+		case "ubuntu": return "pi-cursor-sdk-ubuntu";
+		default: return `pi-cursor-sdk-${targetName}`;
+	}
+}
+
+function parseLeaseId(output) {
+	return output.match(/\bleased\s+(\S+)/)?.[1]
+		?? output.match(/\blease=(\S+)/)?.[1]
+		?? null;
+}
+
+/**
+ * Warm up a Crabbox target lease.
+ * Returns { ok, stdout, stderr, leaseId }.
+ * The lease will be kept until explicitly stopped.
+ */
+export async function warmupLease(targetName, slug, config = {}) {
+	const fullArgs = ["warmup", ...buildTargetBaseArgs(targetName, config), "--slug", slug, "--keep"];
+	if (targetName === "macos") fullArgs.push("--reclaim");
+	console.log(`  [crabbox] ${fullArgs.join(" ")}`);
+	const result = await execCrabbox(fullArgs, { timeout: 300_000 });
+	return {
+		ok: result.code === 0,
+		...result,
+		leaseId: parseLeaseId(result.stdout) ?? parseLeaseId(result.stderr) ?? leaseIdFor(targetName),
+	};
+}
+
+/**
+ * Run a command on a warmed-up lease.
+ * The lease must already exist from a prior warmup. By default this performs
+ * one fresh sync so platform smoke always tests the current local checkout.
+ */
+export async function runOnLease(targetName, leaseId, command, opts = {}) {
+	const args = [
+		"run",
+		...buildTargetBaseArgs(targetName, opts.config),
+		"--id", leaseId,
+	];
+	for (const name of opts.allowEnv ?? []) {
+		args.push("--allow-env", name);
+	}
+	if (opts.sync === false) {
+		args.push("--no-sync");
+	} else if (opts.freshSync !== false) {
+		args.push("--fresh-sync");
+	}
+	if (opts.shell) {
+		args.push("--shell", command);
+	} else {
+		args.push("--", ...(Array.isArray(command) ? command : command.split(" ")));
+	}
+	console.log(`  [crabbox] run ${args.slice(1, 6).join(" ")} ...`);
+	return execCrabbox(args, {
+		timeout: opts.timeout ?? 600_000,
+		env: opts.env,
+		allowEnv: opts.allowEnv,
+	});
+}
+
+/**
+ * Stop/release a warmed-up lease.
+ */
+export async function stopLease(targetName, leaseId, config = {}) {
+	const args = ["stop", ...buildTargetBaseArgs(targetName, config), "--id", leaseId];
+	console.log(`  [crabbox] ${args.join(" ")}`);
+	return execCrabbox(args, { timeout: 60_000 });
+}
+
+/**
+ * One-shot: run a command through Crabbox without warmup.
+ * Crabbox syncs the checkout, executes, and releases the lease.
+ */
+export async function runOneShot(targetName, command, opts = {}) {
+	const args = ["run", ...buildTargetBaseArgs(targetName, opts.config)];
+	if (opts.shell) {
+		args.push("--shell", command);
+	} else {
+		args.push("--", ...(Array.isArray(command) ? command : command.split(" ")));
+	}
+	console.log(`  [crabbox] run (one-shot) ${args.slice(1, 6).join(" ")} ...`);
+	return execCrabbox(args, {
+		timeout: opts.timeout ?? 600_000,
+		env: opts.env,
+		allowEnv: opts.allowEnv,
+	});
+}

package/scripts/platform-smoke/doctor.mjs

@@ -0,0 +1,446 @@
+/**
+ * Platform smoke doctor — preflight checks before any Cursor token spend.
+ *
+ * Implements doctor checks from docs/platform-smoke.md:
+ * env vars, Crabbox, providers, Docker, SSH, Parallels, Node, tools,
+ * artifacts, git status, forbidden files, Cursor auth, node-pty.
+ */
+
+import { execSync, execFileSync } from "node:child_process";
+import { accessSync, constants, existsSync, mkdirSync, writeFileSync, unlinkSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+
+let failures = 0;
+
+function ok(label) { console.log(`  \u2713 ${label}`); }
+function warn(label) { console.log(`  \u26a0 ${label}`); }
+function fail(label) { console.error(`  \u2717 ${label}`); failures++; }
+function env(name) { return process.env[name] ?? ""; }
+
+function versionAtLeast(actual, minimum) {
+	const actualParts = String(actual ?? "").split(".").map((part) => Number.parseInt(part, 10));
+	const minimumParts = String(minimum ?? "").split(".").map((part) => Number.parseInt(part, 10));
+	for (let index = 0; index < Math.max(actualParts.length, minimumParts.length); index++) {
+		const actualPart = Number.isFinite(actualParts[index]) ? actualParts[index] : 0;
+		const minimumPart = Number.isFinite(minimumParts[index]) ? minimumParts[index] : 0;
+		if (actualPart > minimumPart) return true;
+		if (actualPart < minimumPart) return false;
+	}
+	return true;
+}
+
+function safeChildEnv(extra = {}) {
+	const childEnv = { ...process.env, ...extra };
+	delete childEnv.CURSOR_API_KEY;
+	return childEnv;
+}
+
+function silent(cmd, args, opts = {}) {
+	try { return execFileSync(cmd, args, { timeout: 15_000, stdio: "pipe", ...opts, env: safeChildEnv(opts.env) }).toString().trim(); }
+	catch { return null; }
+}
+
+function shell(cmd, opts = {}) {
+	try { return execSync(cmd, { timeout: 15_000, stdio: "pipe", ...opts, env: safeChildEnv(opts.env) }).toString().trim(); }
+	catch { return null; }
+}
+
+function parseLeaseId(output) {
+	return output.match(/\bleased\s+(\S+)/)?.[1]
+		?? output.match(/\blease=(\S+)/)?.[1]
+		?? null;
+}
+
+function windowsCrabboxBaseArgs() {
+	const vm = env("PLATFORM_SMOKE_WINDOWS_VM") || "pi-extension-windows-template";
+	const snap = env("PLATFORM_SMOKE_WINDOWS_SNAPSHOT") || "crabbox-ready";
+	const user = env("PLATFORM_SMOKE_WINDOWS_USER") || env("USER");
+	const workRoot = env("PLATFORM_SMOKE_WINDOWS_NATIVE_WORK_ROOT") || "C:\\crabbox\\pi-cursor-sdk";
+	return [
+		"--provider", "parallels",
+		"--target", "windows",
+		"--windows-mode", "normal",
+		"--parallels-source", vm,
+		"--parallels-source-snapshot", snap,
+		"--parallels-user", user,
+		"--parallels-work-root", workRoot,
+	];
+}
+
+function crabbox(cbox, args, timeout = 300_000) {
+	try {
+		return {
+			ok: true,
+			stdout: execFileSync(cbox, args, {
+				timeout,
+				stdio: "pipe",
+				env: safeChildEnv({ CRABBOX_SYNC_GIT_SEED: "false" }),
+			}).toString(),
+			stderr: "",
+		};
+	} catch (error) {
+		return {
+			ok: false,
+			stdout: error.stdout?.toString?.() ?? "",
+			stderr: error.stderr?.toString?.() ?? error.message,
+		};
+	}
+}
+
+function disposableWindowsSshProbe(cbox) {
+	const slug = "pi-cursor-sdk-doctor-windows";
+	const baseArgs = windowsCrabboxBaseArgs();
+	const warm = crabbox(cbox, ["warmup", ...baseArgs, "--slug", slug, "--keep", "--reclaim"], 300_000);
+	const leaseId = parseLeaseId(warm.stdout) ?? parseLeaseId(warm.stderr) ?? slug;
+	try {
+		if (!warm.ok) return { ok: false, message: `disposable Windows warmup failed: ${(warm.stderr || warm.stdout).slice(-500)}` };
+		const probeCommand = "powershell.exe -NoLogo -NoProfile -ExecutionPolicy Bypass -Command 'Get-Command node,npm,git,tar -ErrorAction Stop | Out-Null; node --version; npm --version; git --version; tar --version | Select-Object -First 1; whoami'";
+		const run = crabbox(cbox, ["run", ...baseArgs, "--id", leaseId, "--no-sync", "--shell", probeCommand], 120_000);
+		if (!run.ok) return { ok: false, message: `disposable Windows probe failed: ${(run.stderr || run.stdout).slice(-500)}` };
+		const lines = run.stdout.trim().split(/\r?\n/).slice(-5);
+		if (!/^v\d+\./.test(lines[0] ?? "")) return { ok: false, message: `disposable Windows node probe missing or invalid: ${lines.join(" | ")}` };
+		if (!/^\d+\.\d+\./.test(lines[1] ?? "")) return { ok: false, message: `disposable Windows npm probe missing or invalid: ${lines.join(" | ")}` };
+		if (!/^git version/i.test(lines[2] ?? "")) return { ok: false, message: `disposable Windows git probe missing or invalid: ${lines.join(" | ")}` };
+		if (!/tar/i.test(lines[3] ?? "")) return { ok: false, message: `disposable Windows tar probe missing or invalid: ${lines.join(" | ")}` };
+		if (!(lines[4] ?? "").trim()) return { ok: false, message: `disposable Windows whoami probe missing: ${lines.join(" | ")}` };
+		return { ok: true, message: lines.join(" | ") };
+	} finally {
+		crabbox(cbox, ["stop", ...baseArgs, "--id", leaseId], 60_000);
+	}
+}
+
+function hasBin(name) { return silent("which", [name]) !== null; }
+
+function findGitRoot(startPath) {
+	let dir = startPath;
+	for (let i = 0; i < 8; i++) {
+		if (existsSync(resolve(dir, ".git"))) return dir;
+		const parent = dirname(dir);
+		if (parent === dir) return null;
+		dir = parent;
+	}
+	return null;
+}
+
+function runChecks(config) {
+	// ── Phase 1: environment variables ──
+	console.log("\n── Environment variables ──");
+	const requiredVars = [
+		"PLATFORM_SMOKE_CRABBOX",
+		"CURSOR_API_KEY",
+		"PLATFORM_SMOKE_WINDOWS_VM",
+		"PLATFORM_SMOKE_WINDOWS_SNAPSHOT",
+		"PLATFORM_SMOKE_WINDOWS_USER",
+		"PLATFORM_SMOKE_WINDOWS_NATIVE_WORK_ROOT",
+	];
+	const optionalVars = [
+		"PLATFORM_SMOKE_MAC_HOST",
+		"PLATFORM_SMOKE_MAC_USER",
+		"PLATFORM_SMOKE_MAC_WORK_ROOT",
+		"PLATFORM_SMOKE_UBUNTU_IMAGE",
+	];
+	for (const name of requiredVars) {
+		const v = env(name);
+		v ? ok(`${name} = ${name === "CURSOR_API_KEY" ? "(present, redacted)" : (v.length > 50 ? v.slice(0, 50) + "..." : v)}`)
+			: fail(`${name} missing`);
+	}
+	for (const name of optionalVars) {
+		const v = env(name);
+		ok(`${name} = ${v || "(default)"}`);
+	}
+
+	// ── Phase 2: Crabbox binary ──
+	console.log("\n── Crabbox binary ──");
+	const cbox = env("PLATFORM_SMOKE_CRABBOX");
+	if (!cbox) {
+		fail("PLATFORM_SMOKE_CRABBOX not set");
+	} else {
+		try { accessSync(cbox, constants.X_OK); ok(`binary: ${cbox}`); }
+		catch { fail(`${cbox} not executable`); }
+		const ver = silent(cbox, ["--version"]);
+		const actualVersion = ver?.split("\n")[0]?.trim();
+		if (actualVersion) ok(`version: ${actualVersion}`);
+		const requiredVersion = config.requiredCrabbox?.version;
+		const minimumVersion = config.requiredCrabbox?.minVersion;
+		if (requiredVersion) {
+			if (!actualVersion) fail(`could not verify Crabbox version for ${cbox}`);
+			else if (actualVersion !== requiredVersion) fail(`Crabbox version mismatch: expected ${requiredVersion}, got ${actualVersion}`);
+			else ok(`required version: ${actualVersion}`);
+		}
+		if (!requiredVersion && minimumVersion) {
+			if (!actualVersion) fail(`could not verify Crabbox version for ${cbox}`);
+			else if (!versionAtLeast(actualVersion, minimumVersion)) fail(`Crabbox version ${actualVersion} is below required minimum ${minimumVersion}`);
+			else ok(`minimum version: ${actualVersion} >= ${minimumVersion}`);
+		}
+		const requiredCommit = config.requiredCrabbox?.commit;
+		if (!requiredVersion && !minimumVersion && requiredCommit) {
+			const gitRoot = findGitRoot(dirname(cbox));
+			const actualCommit = gitRoot ? silent("git", ["-C", gitRoot, "rev-parse", "HEAD"]) : null;
+			if (!actualCommit) fail(`could not verify Crabbox source commit for ${cbox}`);
+			else if (actualCommit !== requiredCommit) fail(`Crabbox commit mismatch: expected ${requiredCommit}, got ${actualCommit}`);
+			else ok(`commit: ${actualCommit}`);
+		}
+	}
+
+	// ── Phase 3: Crabbox providers ──
+	console.log("\n── Crabbox providers ──");
+	if (cbox) {
+		const providerList = silent(cbox, ["providers"]);
+		if (providerList) {
+			for (const provider of ["ssh", "local-container", "parallels"]) {
+				new RegExp(`^${provider}$`, "m").test(providerList)
+					? ok(`provider listed: ${provider}`)
+					: fail(`crabbox providers missing required provider: ${provider}`);
+			}
+		} else {
+			fail("crabbox providers failed");
+		}
+		const ubuntuImage = env("PLATFORM_SMOKE_UBUNTU_IMAGE") || config?.ubuntuContainerImage || "cimg/node:24.16";
+		const lcDoc = silent(cbox, ["doctor", "--provider", "local-container", "--local-container-image", ubuntuImage, "--json"]);
+		if (lcDoc) {
+			try {
+				const d = JSON.parse(lcDoc);
+				d.ok ? ok("local-container provider OK") : fail(`local-container: ${d.error ?? "not ok"}`);
+			} catch {
+				fail("could not parse crabbox doctor --json for local-container");
+			}
+		} else {
+			fail("crabbox doctor --provider local-container --json failed");
+		}
+		const sshHost = env("PLATFORM_SMOKE_MAC_HOST") || "localhost";
+		const sshUser = env("PLATFORM_SMOKE_MAC_USER") || env("USER");
+		const sshRoot = env("PLATFORM_SMOKE_MAC_WORK_ROOT") || `/Users/${env("USER")}/crabbox/pi-cursor-sdk`;
+		const sshDoc = silent(cbox, [
+			"doctor", "--provider", "ssh", "--target", "macos",
+			"--static-host", sshHost, "--static-user", sshUser,
+			"--static-port", "22", "--static-work-root", sshRoot,
+			"--json",
+		]);
+		if (sshDoc) {
+			try {
+				const d = JSON.parse(sshDoc);
+				d.ok ? ok("ssh (static) provider OK") : fail(`ssh doctor: ${d.checks?.find(c => c.status !== "ok")?.check ?? "some checks not ok"}`);
+			} catch {
+				fail("could not parse crabbox ssh doctor JSON");
+			}
+		} else {
+			fail("crabbox doctor --provider ssh --target macos --json failed");
+		}
+	}
+
+	// ── Phase 4: Docker ──
+	console.log("\n── Docker ──");
+	const dockerVer = shell("docker info --format '{{.ServerVersion}}'");
+	dockerVer ? ok(`Docker ${dockerVer}`) : fail("Docker not running or not available");
+
+	// ── Phase 5: macOS SSH ──
+	console.log("\n── macOS SSH ──");
+	const host = env("PLATFORM_SMOKE_MAC_HOST") || "localhost";
+	const user = env("PLATFORM_SMOKE_MAC_USER") || env("USER");
+	const sshOut = shell(`ssh -o BatchMode=yes -o ConnectTimeout=5 -o StrictHostKeyChecking=no ${user}@${host} 'whoami && node --version && npm --version && git --version && rsync --version | head -1 && tar --version | head -1'`);
+	if (sshOut) {
+		const lines = sshOut.trim().split("\n");
+		ok(`SSH to ${host}: ${lines[0]}`);
+		if (lines[1]) ok(`remote Node ${lines[1]}`); else fail("remote node probe missing output");
+		if (lines[2]) ok(`remote npm ${lines[2]}`); else fail("remote npm probe missing output");
+		if (lines[3]) ok(`remote ${lines[3]}`); else fail("remote git probe missing output");
+		if (lines[4]) ok(`remote ${lines[4]}`); else fail("remote rsync probe missing output");
+		if (lines[5]) ok(`remote ${lines[5]}`); else fail("remote tar probe missing output");
+	} else {
+		fail(`SSH to ${host} failed`);
+	}
+
+	// ── Phase 6: Parallels ──
+	console.log("\n── Parallels ──");
+	if (!hasBin("prlctl")) {
+		fail("prlctl not found");
+	} else {
+		ok("prlctl found");
+		const vmName = env("PLATFORM_SMOKE_WINDOWS_VM") || "pi-extension-windows-template";
+		const list = shell("prlctl list -a --no-header 2>/dev/null");
+		if (list) {
+			const vms = list.split("\n").filter(Boolean);
+			const tpl = vms.find(l => l.includes(vmName));
+			if (tpl) {
+				ok(`template VM "${vmName}" found`);
+				const status = tpl.split(/\s+/)[1];
+				if (status === "stopped") {
+					ok(`VM "${vmName}" is stopped — ready for linked clones`);
+				} else {
+					fail(`VM "${vmName}" state: ${status} — source VM must be stopped for linked clones`);
+				}
+
+				const snapName = env("PLATFORM_SMOKE_WINDOWS_SNAPSHOT") || "crabbox-ready";
+				const snapsJson = shell(`prlctl snapshot-list "${vmName}" -j 2>/dev/null`);
+				let snapshotFound = false;
+				let snapshotPowerOff = false;
+				if (snapsJson) {
+					try {
+						const snapshots = JSON.parse(snapsJson);
+						const matches = Object.values(snapshots).filter((item) => item?.name === snapName);
+						if (matches.length > 1) fail(`snapshot "${snapName}" is ambiguous (${matches.length} snapshots); keep exactly one named release snapshot`);
+						const snapshot = matches[0];
+						snapshotFound = Boolean(snapshot);
+						snapshotPowerOff = snapshot?.state === "poweroff";
+					} catch {
+						fail(`could not parse snapshot JSON for "${vmName}"`);
+					}
+				}
+				if (!snapshotFound) {
+					const snapsText = shell(`prlctl snapshot-list "${vmName}" 2>/dev/null`);
+					snapshotFound = Boolean(snapsText && snapsText.includes(snapName));
+				}
+				if (snapshotFound) {
+					ok(`snapshot "${snapName}" exists`);
+					if (snapshotPowerOff) ok(`snapshot "${snapName}" state is poweroff — forkable for linked clones`);
+					else fail(`snapshot "${snapName}" is not poweroff — linked clone baseline must be powered off`);
+				} else {
+					fail(`snapshot "${snapName}" not found — run: prlctl snapshot "${vmName}" --name "${snapName}"`);
+				}
+
+				// SSH probe on Windows VM. Do not let a stopped template hide missing Windows prep.
+				const ipLine = shell(`prlctl list -f --no-header "${vmName}" 2>/dev/null`);
+				if (ipLine) {
+					const parts = ipLine.trim().split(/\s+/);
+					const ip = parts.length >= 3 ? parts[2] : null;
+					if (ip && ip !== "-") {
+						ok(`VM IP: ${ip}`);
+						const portCheck = shell(`nc -z -w 3 ${ip} 22 2>/dev/null && echo open || echo closed`);
+						if (portCheck?.includes("open")) {
+							ok(`SSH open on ${ip}:22`);
+						} else {
+							fail(`SSH not open on ${ip}:22 — enable OpenSSH Server in Windows template VM`);
+						}
+					} else {
+						ok(`template "${vmName}" has no IP; verifying Windows SSH/tools through a disposable Crabbox clone`);
+						if (cbox && snapshotFound && snapshotPowerOff) {
+							const probe = disposableWindowsSshProbe(cbox);
+							probe.ok ? ok(`disposable Windows clone SSH/tool probe OK: ${probe.message}`) : fail(probe.message);
+						} else {
+							fail(`Windows SSH probe could not run because "${vmName}" has no IP and no verified snapshot was available`);
+						}
+					}
+				} else {
+					fail(`could not inspect Windows VM IP for "${vmName}"`);
+				}
+			} else {
+				fail(`VM "${vmName}" not found. Available: ${vms.map(v => v.split(/\s+/).pop()).join(", ")}`);
+			}
+		} else {
+			fail("prlctl list returned no output");
+		}
+	}
+
+	// ── Phase 7: Node.js ──
+	console.log("\n── Node.js ──");
+	const nv = shell("node --version");
+	if (nv) {
+		const major = parseInt(nv.replace("v", "").split(".")[0], 10);
+		major >= (config?.nodeValidationMajor ?? 24)
+			? ok(`Node ${nv} (>= ${config?.nodeValidationMajor ?? 24})`)
+			: fail(`Node ${nv} — need ${config?.nodeValidationMajor ?? 24}+`);
+	} else {
+		fail("node not found");
+	}
+
+	// ── Phase 8: Tools ──
+	console.log("\n── Tools ──");
+	for (const [name, command] of [
+		["npm", "npm --version"],
+		["git", "git --version"],
+		["rsync", "rsync --version"],
+		["tar", "tar --version"],
+	]) {
+		const out = shell(command);
+		out ? ok(`${name}: ${out.split("\n")[0]}`) : fail(`${name} not found`);
+	}
+
+	// ── Phase 9: Artifact root ──
+	console.log("\n── Artifact root ──");
+	const artRoot = resolve(process.cwd(), config?.artifactRoot ?? ".artifacts/platform-smoke");
+	try {
+		mkdirSync(artRoot, { recursive: true });
+		const tf = resolve(artRoot, ".doctor-write-test");
+		writeFileSync(tf, "doctor-test");
+		unlinkSync(tf);
+		ok(`writable: ${artRoot}`);
+	} catch (e) {
+		fail(`cannot write to ${artRoot}: ${e.message}`);
+	}
+
+	// ── Phase 10: Git status ──
+	console.log("\n── Git status ──");
+	const branch = shell("git branch --show-current");
+	branch ? ok(`branch: ${branch}`) : warn("could not determine branch");
+	const st = shell("git status --short");
+	if (st) {
+		const changed = st.trim().split("\n").length;
+		warn(`${changed} uncommitted change(s)`);
+	} else {
+		ok("clean worktree");
+	}
+
+	// ── Phase 11: Forbidden files ──
+	console.log("\n── Forbidden files ──");
+	let anyForbidden = false;
+	for (const pat of [".env", "*.tgz"]) {
+		const found = shell(`find . -maxdepth 2 -name "${pat}" 2>/dev/null`);
+		if (found) {
+			fail(`found: ${found.trim()}`);
+			anyForbidden = true;
+		}
+	}
+	if (!anyForbidden) ok("no .env, .tgz");
+
+	// Check for tracked .env.*
+	for (const f of [".env.production", ".env.local"]) {
+		if (existsSync(resolve(process.cwd(), f))) {
+			fail(`tracked forbidden: ${f}`);
+		}
+	}
+	ok("no tracked .env.*");
+
+	// ── Phase 12: Cursor auth ──
+	console.log("\n── Cursor auth ──");
+	const key = env("CURSOR_API_KEY");
+	if (key && key.length > 10) {
+		ok(`CURSOR_API_KEY present (${key.length} chars, redacted)`);
+	} else if (key) {
+		fail("CURSOR_API_KEY too short (likely invalid)");
+	} else {
+		fail("CURSOR_API_KEY missing — live Cursor suites will not run");
+	}
+
+	// ── Phase 13: node-pty self-test ──
+	console.log("\n── node-pty self-test ──");
+	const ptyPath = resolve(process.cwd(), "node_modules", "node-pty");
+	if (existsSync(ptyPath)) {
+		try {
+			// node-pty can hang with mismatched Node ABI; use timeout
+			const ptyResult = shell("node -e \"try { require('node-pty'); console.log('node-pty ok') } catch(e) { console.error(e.message); process.exit(1) }\"", { timeout: 15_000 });
+			if (ptyResult && ptyResult.includes("node-pty ok")) {
+				ok("node-pty loads successfully");
+			} else {
+				fail(`node-pty not functional: ${ptyResult?.slice(0, 200) || 'null'}. This blocks live PTY suites but not platform-build.`);
+			}
+		} catch (e) {
+			fail(`node-pty self-test error: ${e.message}. This blocks live PTY suites but not platform-build.`);
+		}
+	} else {
+		warn("node-pty not installed — live PTY suites will not run. Run: npm ci");
+	}
+
+	// ── Phase 14: Summary ──
+	console.log(`\n=== Results: ${failures} failure(s) ===`);
+	if (failures > 0) {
+		console.log("Fix failures above before running live Cursor suites.");
+		console.log("Use `npm run smoke:platform:doctor` to re-validate.");
+		process.exitCode = 1;
+	} else {
+		console.log("All checks passed. Ready for platform smoke.");
+	}
+}
+
+export async function runDoctor(config) {
+	runChecks(config);
+}

package/scripts/platform-smoke/jsonl-text.mjs

@@ -0,0 +1,31 @@
+export function extractContentText(content) {
+	if (typeof content === "string") return content;
+	if (!Array.isArray(content)) return "";
+	return content.map((block) => typeof block?.text === "string" ? block.text : JSON.stringify(block)).join("\n");
+}
+
+export function extractFinalTextContent(content) {
+	if (typeof content === "string") return content.trim().length > 0 ? content : "";
+	if (!Array.isArray(content)) return "";
+	for (let index = content.length - 1; index >= 0; index--) {
+		const block = content[index];
+		const text = typeof block?.text === "string" ? block.text : undefined;
+		if (text?.trim()) return text;
+	}
+	return "";
+}
+
+export function getAssistantFinalText(message) {
+	return message?.role === "assistant" ? extractFinalTextContent(message.content) : "";
+}
+
+export function jsonlHasAssistantFinalTextMarker(jsonlRaw, finalMarker) {
+	if (!finalMarker) return true;
+	for (const line of jsonlRaw.split(/\r?\n/)) {
+		if (!line.trim()) continue;
+		let event;
+		try { event = JSON.parse(line); } catch { continue; }
+		if (getAssistantFinalText(event?.message).includes(finalMarker)) return true;
+	}
+	return false;
+}