pi-cursor-sdk 0.1.56 → 0.1.57

package/scripts/platform-smoke/target-runtime.mjs

@@ -0,0 +1,206 @@
+import { createHash } from "node:crypto";
+import { writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import {
+	decodeCanonicalBase64,
+	MAX_COMPRESSED_BUNDLE_BYTES,
+	PLATFORM_ARTIFACT_BUNDLE_END,
+	PLATFORM_ARTIFACT_BUNDLE_FILE_MARKER,
+	PLATFORM_ARTIFACT_BUNDLE_PATH,
+	PLATFORM_ARTIFACT_BUNDLE_START,
+} from "./artifact-bundle-contract.mjs";
+import { redactSecrets } from "./artifact-secrets.mjs";
+import {
+	writeCommand,
+	writeExitCode,
+	writeManifest,
+	writeSummary,
+} from "./artifacts.mjs";
+import { runAssertions } from "./assertions.mjs";
+import { runOnLease } from "./crabbox-runner.mjs";
+
+export function platformFor(targetName) {
+	return targetName === "windows-native" ? "powershell" : "posix";
+}
+
+export function finalizeSuiteArtifacts(
+	suiteDir,
+	checks,
+	summaryData,
+	expectedFiles,
+) {
+	const assertions = runAssertions(suiteDir, checks);
+	writeSummary(suiteDir, { ...summaryData, ok: assertions.ok });
+	const expected = assertions.ok
+		? expectedFiles
+		: [...expectedFiles, "failures.md"];
+	const manifest = writeManifest(suiteDir, expected);
+	if (manifest.missing.length === 0) return { assertions, manifest };
+
+	const finalAssertions = runAssertions(suiteDir, [
+		...checks,
+		{
+			id: "artifact-manifest-complete",
+			fn: () => false,
+			error: `missing required artifact(s): ${manifest.missing.join(", ")}`,
+		},
+	]);
+	writeSummary(suiteDir, { ...summaryData, ok: false });
+	const finalManifest = writeManifest(suiteDir, [
+		...expectedFiles,
+		"failures.md",
+	]);
+	return { assertions: finalAssertions, manifest: finalManifest };
+}
+
+export function writeRedactedFile(path, content) {
+	writeFileSync(path, redactSecrets(content ?? ""));
+}
+
+export function writeStopLeaseArtifacts(suiteDir, stopResult) {
+	writeRedactedFile(
+		resolve(suiteDir, "crabbox.stop.stdout.txt"),
+		stopResult.stdout ?? "",
+	);
+	writeRedactedFile(
+		resolve(suiteDir, "crabbox.stop.stderr.txt"),
+		stopResult.stderr ?? "",
+	);
+	writeFileSync(
+		resolve(suiteDir, "crabbox.stop.exit-code.txt"),
+		`code=${stopResult.code}\nsignal=${stopResult.signal ?? "none"}\n`,
+	);
+}
+
+export function stopLeaseCheck(stopResult) {
+	return {
+		id: "lease-stop",
+		fn: () => stopResult?.code === 0,
+		error: `Crabbox stop failed (exit ${stopResult?.code ?? "unknown"}); check crabbox.stop.stderr.txt`,
+	};
+}
+
+export async function runOnLeaseWithTransientRetry(
+	suiteDir,
+	targetName,
+	leaseId,
+	command,
+	options,
+	run = runOnLease,
+) {
+	const first = await run(targetName, leaseId, command, options);
+	if (!isTransientCrabboxSshFailure(first)) return first;
+	writeRedactedFile(
+		resolve(suiteDir, "crabbox.retry1.stdout.txt"),
+		first.stdout,
+	);
+	writeRedactedFile(
+		resolve(suiteDir, "crabbox.retry1.stderr.txt"),
+		first.stderr,
+	);
+	await new Promise((resolveRetry) => setTimeout(resolveRetry, 10_000));
+	return await run(targetName, leaseId, command, { ...options, sync: false });
+}
+
+const ARTIFACT_CHUNK_BYTES = 32 * 1024;
+
+export async function fetchPlatformArtifactBundle(targetName, leaseId, stdout, config, run = runOnLease) {
+	const markerLine = stdout.split(/\r?\n/).find((line) => line.startsWith(PLATFORM_ARTIFACT_BUNDLE_FILE_MARKER));
+	if (!markerLine) return { ok: true, stdout };
+	let metadata;
+	try {
+		metadata = JSON.parse(markerLine.slice(PLATFORM_ARTIFACT_BUNDLE_FILE_MARKER.length));
+	} catch {
+		return { ok: false, stdout, error: "invalid platform artifact bundle file marker" };
+	}
+	if (
+		metadata?.encoding !== "gzip" ||
+		metadata.path !== PLATFORM_ARTIFACT_BUNDLE_PATH ||
+		!Number.isSafeInteger(metadata.size) ||
+		metadata.size < 1 ||
+		metadata.size > MAX_COMPRESSED_BUNDLE_BYTES ||
+		!/^[0-9a-f]{64}$/i.test(metadata.sha256)
+	) {
+		return { ok: false, stdout, error: "unsafe platform artifact bundle file metadata" };
+	}
+	const chunks = [];
+	for (let offset = 0; offset < metadata.size; offset += ARTIFACT_CHUNK_BYTES) {
+		const length = Math.min(ARTIFACT_CHUNK_BYTES, metadata.size - offset);
+		const result = await run(
+			targetName,
+			leaseId,
+			[
+				"node",
+				"scripts/platform-smoke/artifact-bundle-chunk.mjs",
+				"--path", metadata.path,
+				"--offset", String(offset),
+				"--length", String(length),
+			],
+			{ timeout: 120_000, sync: false, config },
+		);
+		if (result.code !== 0) return { ok: false, stdout, error: `artifact chunk ${offset} failed: ${result.stderr || result.stdout}` };
+		const chunkLine = result.stdout.split(/\r?\n/).find((line) => line.startsWith("PLATFORM_BUNDLE_CHUNK_JSON="));
+		try {
+			const chunk = JSON.parse(chunkLine?.slice("PLATFORM_BUNDLE_CHUNK_JSON=".length));
+			if (chunk.offset !== offset || chunk.total !== metadata.size || chunk.bytes !== length) {
+				return { ok: false, stdout, error: `artifact chunk ${offset} failed validation` };
+			}
+			const content = decodeCanonicalBase64(chunk.contentBase64, length);
+			if (!content) {
+				return { ok: false, stdout, error: `artifact chunk ${offset} failed validation` };
+			}
+			chunks.push(content);
+		} catch {
+			return { ok: false, stdout, error: `artifact chunk ${offset} was malformed` };
+		}
+	}
+	const compressed = Buffer.concat(chunks);
+	if (createHash("sha256").update(compressed).digest("hex") !== metadata.sha256) {
+		return { ok: false, stdout, error: "platform artifact bundle checksum mismatch" };
+	}
+	const envelope = {
+		encoding: "gzip-base64",
+		size: compressed.length,
+		sha256: metadata.sha256,
+		contentBase64: compressed.toString("base64"),
+	};
+	return {
+		ok: true,
+		stdout: `${PLATFORM_ARTIFACT_BUNDLE_START}\n${JSON.stringify(envelope)}\n${PLATFORM_ARTIFACT_BUNDLE_END}\n`,
+	};
+}
+
+function isTransientCrabboxSshFailure(result) {
+	const text = `${result.stdout}\n${result.stderr}`;
+	return (
+		result.code === 255 &&
+		/ssh: connect to host .*\b(Operation timed out|Connection timed out)\b/i.test(
+			text,
+		)
+	);
+}
+
+export function failSuite(suiteDir, targetName, suiteName, message) {
+	const safeMessage = redactSecrets(message);
+	console.log(`  FAIL ${suiteName} on ${targetName}: ${safeMessage}`);
+
+	writeCommand(suiteDir, `# ${suiteName} — ${safeMessage}`);
+	writeExitCode(suiteDir, 1, null);
+
+	const checks = [{ id: "execution", fn: () => false, error: safeMessage }];
+	const { assertions } = finalizeSuiteArtifacts(
+		suiteDir,
+		checks,
+		{ target: targetName, suite: suiteName, exitCode: 1, error: safeMessage },
+		[
+			"summary.json",
+			"target.json",
+			"suite.json",
+			"command.txt",
+			"exit-code.txt",
+			"assertions.json",
+		],
+	);
+
+	return { ok: false, suiteDir, assertions };
+}

package/scripts/platform-smoke/targets.mjs

@@ -6,63 +6,44 @@
  */
 
 import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
-import { dirname, isAbsolute, relative, resolve } from "node:path";
-
-import { createSuiteDir, writeManifest, writeSummary, writeCommand, writeExitCode, scanArtifacts, scanForSecrets, redactSecrets } from "./artifacts.mjs";
-import { runAssertions } from "./assertions.mjs";
+import { resolve } from "node:path";
+
+import {
+	createSuiteDir,
+	extractPlatformArtifactBundle,
+	writeCommand,
+	writeExitCode,
+	scanArtifacts,
+	scanForSecrets,
+	redactSecrets,
+} from "./artifacts.mjs";
+
+export { isSafePlatformBundlePath as isSafeBundlePath } from "./artifacts.mjs";
 import { getScenario } from "./scenarios.mjs";
 import { warmupLease, runOnLease, stopLease } from "./crabbox-runner.mjs";
 import { renderAll } from "./render-ansi.mjs";
 import { assertRequiredCards, detectCards, writeCardArtifacts } from "./card-detect.mjs";
 import { collectVisualEvidence } from "./visual-evidence.mjs";
 import { extractContentText, extractFinalTextContent } from "./jsonl-text.mjs";
-
-export function platformFor(targetName) {
-	return targetName === "windows-native" ? "powershell" : "posix";
-}
+import { executeLocalResumeSuite } from "./local-resume-runner.mjs";
+import { LOCAL_RESUME_SUITE_BY_NAME } from "./local-resume-suites.mjs";
+import {
+	failSuite,
+	fetchPlatformArtifactBundle,
+	finalizeSuiteArtifacts,
+	platformFor,
+	runOnLeaseWithTransientRetry,
+	stopLeaseCheck,
+	writeRedactedFile,
+	writeStopLeaseArtifacts,
+} from "./target-runtime.mjs";
+
+export { finalizeSuiteArtifacts, platformFor };
 
 function makeRunId() {
 	return `run-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
 }
 
-export function finalizeSuiteArtifacts(suiteDir, checks, summaryData, expectedFiles) {
-	const assertions = runAssertions(suiteDir, checks);
-	writeSummary(suiteDir, { ...summaryData, ok: assertions.ok });
-	const expected = assertions.ok ? expectedFiles : [...expectedFiles, "failures.md"];
-	const manifest = writeManifest(suiteDir, expected);
-	if (manifest.missing.length === 0) return { assertions, manifest };
-
-	const finalAssertions = runAssertions(suiteDir, [
-		...checks,
-		{
-			id: "artifact-manifest-complete",
-			fn: () => false,
-			error: `missing required artifact(s): ${manifest.missing.join(", ")}`,
-		},
-	]);
-	writeSummary(suiteDir, { ...summaryData, ok: false });
-	const finalManifest = writeManifest(suiteDir, [...expectedFiles, "failures.md"]);
-	return { assertions: finalAssertions, manifest: finalManifest };
-}
-
-function writeRedactedFile(path, content) {
-	writeFileSync(path, redactSecrets(content ?? ""));
-}
-
-function writeStopLeaseArtifacts(suiteDir, stopResult) {
-	writeRedactedFile(resolve(suiteDir, "crabbox.stop.stdout.txt"), stopResult.stdout ?? "");
-	writeRedactedFile(resolve(suiteDir, "crabbox.stop.stderr.txt"), stopResult.stderr ?? "");
-	writeFileSync(resolve(suiteDir, "crabbox.stop.exit-code.txt"), `code=${stopResult.code}\nsignal=${stopResult.signal ?? "none"}\n`);
-}
-
-function stopLeaseCheck(stopResult) {
-	return {
-		id: "lease-stop",
-		fn: () => stopResult?.code === 0,
-		error: `Crabbox stop failed (exit ${stopResult?.code ?? "unknown"}); check crabbox.stop.stderr.txt`,
-	};
-}
-
 export function createLeaseCleanupResult(config, targetName, leaseId, stopResult, runId = makeRunId()) {
 	const suiteName = "lease-cleanup";
 	const suiteDir = createSuiteDir(config.artifactRoot, runId, targetName, suiteName);
@@ -131,6 +112,8 @@ export async function runTargetSuite(config, targetName, suiteName, leaseSession
 		return result;
 	}
 
+	if (LOCAL_RESUME_SUITE_BY_NAME.has(suiteName)) return await executeLocalResumeSuite(config, targetName, suiteName, suiteDir, slug, leaseSession);
+
 	// Route to suite-specific executor
 	switch (suiteName) {
 		case "platform-build":
@@ -516,9 +499,12 @@ async function executeLiveSuite(config, targetName, suiteName, suiteDir, slug, l
 		shell: true,
 		timeout: 900_000,
 		allowEnv: ["CURSOR_API_KEY"],
+		captureStdoutPath: resolve(suiteDir, ".crabbox.remote.stdout.raw"),
 		sync: leaseSession?.sync,
 		config,
 	});
+	const bundleTransport = await fetchPlatformArtifactBundle(targetName, warmup.leaseId, result.stdout, config);
+	if (!bundleTransport.ok) result.stderr = `${result.stderr}\n[platform-smoke] ${bundleTransport.error}`.trim();
 	const elapsed = Date.now() - startedAt;
 	writeRedactedFile(resolve(suiteDir, "crabbox.stdout.txt"), result.stdout);
 	writeRedactedFile(resolve(suiteDir, "crabbox.stderr.txt"), result.stderr);
@@ -537,7 +523,7 @@ async function executeLiveSuite(config, targetName, suiteName, suiteDir, slug, l
 		writeStopLeaseArtifacts(suiteDir, stopResult);
 	}
 
-	const bundle = extractLiveBundle(suiteDir, result.stdout);
+	const bundle = extractPlatformArtifactBundle(suiteDir, bundleTransport.stdout);
 	const liveArtifactDir = resolve(suiteDir, "artifacts");
 	mkdirSync(liveArtifactDir, { recursive: true });
 	const terminalAnsi = resolve(liveArtifactDir, "terminal.ansi");
@@ -674,20 +660,6 @@ async function executeLiveSuite(config, targetName, suiteName, suiteDir, slug, l
 	return { ok: assertions.ok, suiteDir, assertions };
 }
 
-async function runOnLeaseWithTransientRetry(suiteDir, targetName, leaseId, command, options) {
-	const first = await runOnLease(targetName, leaseId, command, options);
-	if (!isTransientCrabboxSshFailure(first)) return first;
-	writeRedactedFile(resolve(suiteDir, "crabbox.retry1.stdout.txt"), first.stdout);
-	writeRedactedFile(resolve(suiteDir, "crabbox.retry1.stderr.txt"), first.stderr);
-	await new Promise((resolveRetry) => setTimeout(resolveRetry, 10_000));
-	return await runOnLease(targetName, leaseId, command, { ...options, sync: false });
-}
-
-function isTransientCrabboxSshFailure(result) {
-	const text = `${result.stdout}\n${result.stderr}`;
-	return result.code === 255 && /ssh: connect to host .*\b(Operation timed out|Connection timed out)\b/i.test(text);
-}
-
 function buildLiveSuiteCommand(config, targetName, suiteName, prepDir) {
 	const model = config.cursorModel ?? "cursor/composer-2-5";
 	const packageName = config.packageName ?? "pi-cursor-sdk";
@@ -698,60 +670,6 @@ function buildLiveSuiteCommand(config, targetName, suiteName, prepDir) {
 	return `node scripts/platform-smoke/live-suite-runner.mjs --suite ${shellQuote(suiteName)} --target ${shellQuote(targetName)} --model ${shellQuote(model)} --package-name ${shellQuote(packageName)}${prepArgs}`;
 }
 
-function extractLiveBundle(suiteDir, stdout) {
-	const start = stdout.indexOf("PLATFORM_LIVE_BUNDLE_JSON_START");
-	const end = stdout.indexOf("PLATFORM_LIVE_BUNDLE_JSON_END", start);
-	if (start === -1 || end === -1) return { ok: false, violations: [] };
-	const jsonText = stdout.slice(start + "PLATFORM_LIVE_BUNDLE_JSON_START".length, end).trim();
-	let bundle;
-	try { bundle = JSON.parse(jsonText); } catch { return { ok: false, violations: [] }; }
-	if (!Array.isArray(bundle.files)) return { ok: false, violations: [] };
-	const violations = [];
-	for (const file of bundle.files) {
-		if (!file?.path || typeof file.contentBase64 !== "string") continue;
-		if (!isSafeBundlePath(suiteDir, file.path)) return { ok: false, violations };
-		const outPath = resolve(suiteDir, file.path);
-		mkdirSync(dirname(outPath), { recursive: true });
-		const content = Buffer.from(file.contentBase64, "base64");
-		if (isTextArtifactPath(file.path)) {
-			const text = content.toString("utf8");
-			violations.push(...scanForSecrets(text).map((violation) => ({ file: file.path, violation })));
-			if (file.path.endsWith("redaction-violations.json")) {
-				violations.push(...readRedactionViolationList(text, file.path));
-			}
-			writeFileSync(outPath, redactSecrets(text));
-		} else {
-			writeFileSync(outPath, content);
-		}
-	}
-	return { ok: true, violations };
-}
-
-function readRedactionViolationList(text, fallbackFile) {
-	try {
-		const parsed = JSON.parse(text);
-		if (!Array.isArray(parsed)) return [];
-		return parsed
-			.filter((item) => typeof item?.violation === "string")
-			.map((item) => ({ file: typeof item.file === "string" ? item.file : fallbackFile, violation: item.violation }));
-	} catch {
-		return [];
-	}
-}
-
-function isTextArtifactPath(path) {
-	const ext = path.split(".").pop()?.toLowerCase() ?? "";
-	return ["txt", "json", "jsonl", "md", "log", "ansi", "html", "yml", "yaml", "js", "mjs", "ts"].includes(ext);
-}
-
-export function isSafeBundlePath(suiteDir, bundlePath) {
-	if (typeof bundlePath !== "string" || bundlePath.length === 0) return false;
-	if (isAbsolute(bundlePath) || /^[A-Za-z]:[\\/]/.test(bundlePath)) return false;
-	const outPath = resolve(suiteDir, bundlePath);
-	const rel = relative(suiteDir, outPath);
-	return rel.length > 0 && !rel.startsWith("..") && !isAbsolute(rel);
-}
-
 function readJson(path) {
 	try { return JSON.parse(readFileSync(path, "utf8")); } catch { return undefined; }
 }
@@ -876,29 +794,3 @@ function matchesJsonlResult(result, requirement) {
 function shellQuote(value) {
 	return `'${String(value).replace(/'/g, `'\\''`)}'`;
 }
-
-/**
- * Write a failure suite result. Used for live suite hard failures during
- * warmup/execution and for unknown suites.
- */
-function failSuite(suiteDir, targetName, suiteName, message) {
-	const safeMessage = redactSecrets(message);
-	console.log(`  FAIL ${suiteName} on ${targetName}: ${safeMessage}`);
-
-	writeCommand(suiteDir, `# ${suiteName} — ${safeMessage}`);
-	writeExitCode(suiteDir, 1, null);
-
-	const checks = [{ id: "execution", fn: () => false, error: safeMessage }];
-	const { assertions } = finalizeSuiteArtifacts(
-		suiteDir,
-		checks,
-		{ target: targetName, suite: suiteName, exitCode: 1, error: safeMessage },
-		[
-			"summary.json", "target.json", "suite.json",
-			"command.txt", "exit-code.txt",
-			"assertions.json",
-		],
-	);
-
-	return { ok: false, suiteDir, assertions };
-}

package/scripts/platform-smoke/visual-evidence.mjs

@@ -1,6 +1,7 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { resolve } from "node:path";
 import { pathToFileURL } from "node:url";
+import { matchesWrappedLineAt } from "./wrapped-line-match.mjs";
 
 function pngSize(path) {
 	try {
@@ -16,10 +17,10 @@ function safeFileName(id) {
 	return String(id).replace(/[^A-Za-z0-9_.-]+/g, "-");
 }
 
-function makeRegex(spec) {
-	if (!spec?.pattern) return undefined;
+function makeRegex(spec, key = "pattern") {
+	if (!spec?.[key]) return undefined;
 	try {
-		return new RegExp(spec.pattern, spec.flags ?? "i");
+		return new RegExp(spec[key], spec.flags ?? "i");
 	} catch {
 		return undefined;
 	}
@@ -28,11 +29,9 @@ function makeRegex(spec) {
 export function findVisualEvidenceItems(lines, specs = []) {
 	return specs.map((spec) => {
 		const regex = makeRegex(spec);
+		const wrappedRegex = makeRegex(spec, "wrappedPattern");
 		if (!regex) return { id: spec.id, ok: false, error: `invalid regex: ${spec.pattern}` };
-		const lineIndex = lines.findIndex((line) => {
-			regex.lastIndex = 0;
-			return regex.test(line);
-		});
+		const lineIndex = lines.findIndex((_line, index) => matchesWrappedLineAt(lines, index, regex, wrappedRegex));
 		if (lineIndex === -1) return { id: spec.id, ok: false, pattern: spec.pattern };
 		return { id: spec.id, ok: true, pattern: spec.pattern, lineIndex, line: lines[lineIndex] };
 	});

package/scripts/platform-smoke/wrapped-line-match.mjs

@@ -0,0 +1,9 @@
+/** Match a regex directly against a line, or against up to 3 lines joined with a space when the
+ * terminal wrapped the token across lines and a wrappedPattern was supplied. */
+export function matchesWrappedLineAt(lines, index, pattern, wrappedPattern) {
+	pattern.lastIndex = 0;
+	if (pattern.test(lines[index])) return true;
+	if (!wrappedPattern) return false;
+	wrappedPattern.lastIndex = 0;
+	return wrappedPattern.test(lines.slice(index, index + 3).join(" "));
+}

package/scripts/platform-smoke.mjs

@@ -22,6 +22,8 @@ try {
 }
 
 function printHelp() {
+	const targetList = (config?.requiredTargets ?? ["macos", "ubuntu", "windows-native"]).join(",");
+	const suiteList = (config?.requiredSuites ?? []).join(",");
 	console.log(`Usage: node scripts/platform-smoke.mjs <command> [options]
 
 Commands:
@@ -31,8 +33,8 @@ Commands:
   run --target <n> --suite <n>
 
 Options:
-  --target       Comma-separated target names: macos,ubuntu,windows-native
-  --suite        Suite name: platform-build,cursor-native-visual-matrix,cursor-bridge-visual-matrix,cursor-abort-cleanup
+  --target       Comma-separated target names: ${targetList}
+  --suite        Suite name: ${suiteList}
   --help, -h     Show this help
 
 Examples:
@@ -40,6 +42,7 @@ Examples:
   node scripts/platform-smoke.mjs run --target macos
   node scripts/platform-smoke.mjs run --target macos,ubuntu
   node scripts/platform-smoke.mjs run --suite platform-build
+  node scripts/platform-smoke.mjs run --target macos --suite cursor-local-resume-restart
   node scripts/platform-smoke.mjs run --target macos --suite cursor-native-visual-matrix
 
 Environment:
@@ -57,41 +60,45 @@ Environment:
 }
 
 function parseArgs(argv) {
-	const args = { _: [], target: null, suite: null, command: null };
+	const args = { target: null, suite: null, command: null };
 	let i = 2;
 	while (i < argv.length) {
-		const a = argv[i];
-		if (a === "--help" || a === "-h") {
-			args.command = "help";
-			return args;
-		}
-		if (a === "doctor") {
-			args.command = "doctor";
-			i++;
-			continue;
-		}
-		if (a === "run") {
-			args.command = "run";
+		const arg = argv[i];
+		if (arg === "--help" || arg === "-h") return { ...args, command: "help" };
+		if (arg === "doctor" || arg === "run") {
+			if (args.command) {
+				throw new Error(`${args.command === arg ? "duplicate" : "conflicting"} command token: ${arg}`);
+			}
+			args.command = arg;
 			i++;
 			continue;
 		}
-		if (a === "--target" && i + 1 < argv.length) {
-			args.target = argv[i + 1];
-			i += 2;
-			continue;
-		}
-		if (a === "--suite" && i + 1 < argv.length) {
-			args.suite = argv[i + 1];
+		if (arg === "--target" || arg === "--suite") {
+			const key = arg.slice(2);
+			if (args[key] !== null) throw new Error(`duplicate ${arg}`);
+			const value = argv[i + 1];
+			if (!value?.trim() || value.startsWith("-") || value === "doctor" || value === "run") {
+				throw new Error(`${arg} requires a value`);
+			}
+			args[key] = value;
 			i += 2;
 			continue;
 		}
-		args._.push(a);
-		i++;
+		throw new Error(`${arg.startsWith("-") ? "unknown option" : "unknown positional argument"}: ${arg}`);
+	}
+	if (args.command === "doctor" && (args.target !== null || args.suite !== null)) {
+		throw new Error("doctor does not accept --target or --suite");
+	}
+	if (!args.command && (args.target !== null || args.suite !== null)) {
+		throw new Error("--target and --suite require the run command");
 	}
 	return args;
 }
 
 function validateSelections(targets, suites) {
+	if (targets.length === 0 || targets.some((target) => !target)) throw new Error("--target requires nonempty target names");
+	if (new Set(targets).size !== targets.length) throw new Error("--target contains duplicate target names");
+	if (suites.length === 0 || suites.some((suite) => !suite)) throw new Error("--suite requires a suite name");
 	const allowedTargets = new Set(config.requiredTargets ?? []);
 	const allowedSuites = new Set(config.requiredSuites ?? []);
 	const badTargets = targets.filter((target) => !allowedTargets.has(target));
@@ -190,7 +197,13 @@ async function runTarget(targetName, suites) {
 }
 
 async function main() {
-	const args = parseArgs(process.argv);
+	let args;
+	try {
+		args = parseArgs(process.argv);
+	} catch (err) {
+		console.error(`usage error: ${err.message}`);
+		process.exit(2);
+	}
 
 	if (!args.command || args.command === "help") {
 		printHelp();
@@ -209,7 +222,7 @@ async function main() {
 
 	if (args.command === "run") {
 		const targets = args.target
-			? args.target.split(",").map((s) => s.trim()).filter(Boolean)
+			? args.target.split(",").map((s) => s.trim())
 			: config.requiredTargets;
 
 		const suites = args.suite
@@ -219,7 +232,7 @@ async function main() {
 		try {
 			validateSelections(targets, suites);
 		} catch (err) {
-			console.error(err.message);
+			console.error(`usage error: ${err.message}`);
 			process.exit(2);
 		}
 

package/scripts/refresh-cursor-model-snapshots.mjs

@@ -13,10 +13,13 @@ function printHelp() {
 	console.log(`Refresh reviewable Cursor model fallback snapshots.
 
 Usage:
+  npm run check:cursor-snapshots
   npm run refresh:cursor-snapshots -- --write [options]
   node scripts/refresh-cursor-model-snapshots.mjs [options]
 
 Options:
+  --check                       Fetch the live catalog and byte-compare
+                                ${FALLBACK_MODELS_PATH} without writing.
   --write                       Write ${FALLBACK_MODELS_PATH}. Also write
                                 ${CONTEXT_WINDOWS_PATH} when --context-windows is supplied.
                                 Without --write, print a summary only.
@@ -47,10 +50,13 @@ function parseRefreshArgs(argv) {
 		printHelp();
 		process.exit(0);
 	}
+	const check = argv.includes("--check");
 	const write = argv.includes("--write");
-	const filteredArgv = argv.filter((arg) => arg !== "--write");
+	if (check && write) fail("--check and --write cannot be used together");
+	const filteredArgv = argv.filter((arg) => arg !== "--check" && arg !== "--write");
 	const args = parseArgv(filteredArgv, {
 		defaults: {
+			check,
 			write,
 			apiKey: defaultApiKeyFromEnv(),
 			contextWindowsPath: undefined,
@@ -114,8 +120,8 @@ function stableStringify(value) {
 	return JSON.stringify(value, null, "\t").replace(/"([^"\\]+)":/g, "$1:");
 }
 
-function formatFallbackModels(models) {
-	return `import type { ModelListItem } from "@cursor/sdk";\n\n// Generated/maintained fallback Cursor catalog snapshot.\n// Refresh with: npm run refresh:cursor-snapshots -- --write\n// Do not add secrets; this file stores public model metadata only.\nexport const FALLBACK_MODEL_ITEMS = ${stableStringify(models)} satisfies ModelListItem[];\n`;
+function formatFallbackModels(models, sdkVersion) {
+	return `import type { ModelListItem } from "@cursor/sdk";\n\n// Generated with @cursor/sdk@${sdkVersion} from ${models.length} Cursor models.\n// Refresh with: npm run refresh:cursor-snapshots -- --write\n// Do not add secrets; this file stores public model metadata only.\nexport const FALLBACK_MODEL_ITEMS = ${stableStringify(models)} satisfies ModelListItem[];\n`;
 }
 
 function parseExistingContextWindows() {
@@ -165,6 +171,7 @@ function formatContextWindows(models, checkpointWindows, fallbackContextWindow)
 }
 
 const args = parseRefreshArgs(process.argv.slice(2));
+const sdkVersion = JSON.parse(readFileSync(new URL("../node_modules/@cursor/sdk/package.json", import.meta.url), "utf8")).version;
 let rawModels;
 try {
 	rawModels = await Cursor.models.list({ apiKey: args.apiKey });
@@ -176,15 +183,20 @@ if (!Array.isArray(rawModels) || rawModels.length === 0) fail("Cursor.models.lis
 
 const models = rawModels.map(sanitizeModelItem).sort((a, b) => a.id.localeCompare(b.id));
 const checkpointWindows = parseContextWindowsFile(args.contextWindowsPath);
-const fallbackSource = formatFallbackModels(models);
+const fallbackSource = formatFallbackModels(models, sdkVersion);
 const contextWindowSource = args.contextWindowsPath ? formatContextWindows(models, checkpointWindows, args.fallbackContextWindow) : undefined;
 const existingContextWindowCount = parseExistingContextWindows().size;
 
-console.log(`Fetched ${models.length} Cursor models.`);
+console.log(`Fetched ${models.length} Cursor models with @cursor/sdk@${sdkVersion}.`);
 console.log(`Context windows: ${checkpointWindows.size} checkpoint override(s), ${existingContextWindowCount} existing bundled entr${existingContextWindowCount === 1 ? "y" : "ies"}.`);
 console.log(`First models: ${models.slice(0, 8).map((model) => model.id).join(", ")}${models.length > 8 ? ", ..." : ""}`);
 
-if (args.write) {
+if (args.check) {
+	if (!existsSync(FALLBACK_MODELS_PATH) || !readFileSync(FALLBACK_MODELS_PATH).equals(Buffer.from(fallbackSource))) {
+		fail(`${FALLBACK_MODELS_PATH} is stale; refresh it with: npm run refresh:cursor-snapshots -- --write`);
+	}
+	console.log(`${FALLBACK_MODELS_PATH} is current (${models.length} models, @cursor/sdk@${sdkVersion}).`);
+} else if (args.write) {
 	writeFileSync(FALLBACK_MODELS_PATH, fallbackSource);
 	console.log(`Wrote ${FALLBACK_MODELS_PATH}`);
 	if (contextWindowSource) {