pi-cursor-sdk 0.1.31 → 0.1.32

package/CHANGELOG.md

@@ -2,6 +2,21 @@
 
 ## Unreleased
 
+## 0.1.32 - 2026-06-02
+
+### Added
+
+- Add a production typing-safety regression test that blocks broad TypeScript escape hatches such as `as unknown as`, `as any`, `as never`, explicit `any`, and production `@ts-ignore` / `@ts-expect-error` usage.
+
+### Changed
+
+- Replace repeated native replay render-test `as never` casts with typed test render fixture helpers.
+- Use the maintained Homebrew Crabbox binary on `PATH` for platform smoke with a `0.24.0` minimum version, keeping `PLATFORM_SMOKE_CRABBOX` as an explicit override only.
+
+### Fixed
+
+- Harden local Cursor cache/config JSON parsing so model-list, context-window, and fast-default files are validated from `unknown` before trusted values are used.
+
 ## 0.1.31 - 2026-06-01
 
 ### Added

package/docs/crabbox-platform-testing-lessons.md

@@ -154,7 +154,7 @@ PLATFORM_SMOKE_WINDOWS_USER=<windows-ssh-user>
 PLATFORM_SMOKE_WINDOWS_WORK_ROOT=C:\crabbox\<project>
 ```
 
-Pin Crabbox deliberately. Exact pins are best for release-critical harnesses whose parsing depends on CLI output. Minimum version checks are fine for simpler gates. Current local baseline is Crabbox `0.24.0`.
+Pin Crabbox deliberately. Exact pins are best for release-critical harnesses whose parsing depends on CLI output. Minimum version checks are fine for simpler gates. Current local baseline is Crabbox `0.24.0` or newer from the Homebrew package.
 
 ## Target setup best practices
 

package/docs/platform-smoke.md

@@ -52,12 +52,12 @@ The runner uses one supported Crabbox build.
 Current baseline:
 
 ```text
-install: brew install crabbox
-version: 0.24.0
-binary: /opt/homebrew/bin/crabbox on Apple Silicon Homebrew installs
+install: brew install openclaw/tap/crabbox
+version: 0.24.0 or newer
+binary: Homebrew `crabbox` on PATH (`/opt/homebrew/bin/crabbox` on Apple Silicon Homebrew installs)
 ```
 
-Keep this exact version or replace it with another exact released Crabbox version when updating the gate. `smoke:platform:doctor` verifies the configured Crabbox binary and fails on mismatch.
+Use the Homebrew Crabbox binary on PATH for normal release gates. `PLATFORM_SMOKE_CRABBOX=/path/to/crabbox` is only an explicit override for testing a non-default binary. `smoke:platform:doctor` verifies the configured binary and fails when it is older than the configured minimum version.
 
 Required Crabbox providers:
 
@@ -188,8 +188,8 @@ export default {
     "cursor-abort-cleanup",
   ],
   requiredCrabbox: {
-    install: "brew install crabbox",
-    version: "0.24.0",
+    install: "Homebrew package or PLATFORM_SMOKE_CRABBOX override",
+    minVersion: "0.24.0",
   },
   ubuntuContainerImage: "cimg/node:24.16",
   nodeValidationMajor: 24,
@@ -203,6 +203,7 @@ export default {
 The doctor fails if any required value is missing.
 
 ```bash
+# Optional override; by default the gate uses Homebrew `crabbox` from PATH.
 PLATFORM_SMOKE_CRABBOX=/opt/homebrew/bin/crabbox
 
 PLATFORM_SMOKE_MAC_HOST=localhost
@@ -313,7 +314,7 @@ tar --version
 Doctor checks:
 
 1. Required env vars exist.
-2. `PLATFORM_SMOKE_CRABBOX` exists and is executable.
+2. Homebrew `crabbox` is available on PATH, or `PLATFORM_SMOKE_CRABBOX` points at an executable override.
 3. Crabbox build matches the configured baseline.
 4. Crabbox provider registry includes `local-container`, `ssh`, and `parallels`.
 5. `crabbox doctor --provider local-container --json` passes.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-cursor-sdk",
-	"version": "0.1.31",
+	"version": "0.1.32",
 	"description": "pi provider extension backed by @cursor/sdk local agents",
 	"author": "Mitch Fultz (https://github.com/fitchmultz)",
 	"license": "MIT",

package/platform-smoke.config.mjs

@@ -13,8 +13,8 @@ export default {
 		"cursor-abort-cleanup",
 	],
 	requiredCrabbox: {
-		install: "brew install crabbox",
-		version: "0.24.0",
+		install: "Homebrew package or PLATFORM_SMOKE_CRABBOX override",
+		minVersion: "0.24.0",
 	},
 	ubuntuContainerImage: "cimg/node:24.16",
 	nodeValidationMajor: 24,

package/scripts/platform-smoke/doctor.mjs

@@ -45,6 +45,10 @@ function shell(cmd, opts = {}) {
 	catch { return null; }
 }
 
+function commandPath(command) {
+	return shell(`command -v ${command}`);
+}
+
 function parseLeaseId(output) {
 	return output.match(/\bleased\s+(\S+)/)?.[1]
 		?? output.match(/\blease=(\S+)/)?.[1]
@@ -126,7 +130,6 @@ 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",
@@ -134,6 +137,7 @@ function runChecks(config) {
 		"PLATFORM_SMOKE_WINDOWS_NATIVE_WORK_ROOT",
 	];
 	const optionalVars = [
+		"PLATFORM_SMOKE_CRABBOX",
 		"PLATFORM_SMOKE_MAC_HOST",
 		"PLATFORM_SMOKE_MAC_USER",
 		"PLATFORM_SMOKE_MAC_WORK_ROOT",
@@ -151,12 +155,17 @@ function runChecks(config) {
 
 	// ── Phase 2: Crabbox binary ──
 	console.log("\n── Crabbox binary ──");
-	const cbox = env("PLATFORM_SMOKE_CRABBOX");
-	if (!cbox) {
-		fail("PLATFORM_SMOKE_CRABBOX not set");
+	const cbox = env("PLATFORM_SMOKE_CRABBOX") || "crabbox";
+	const cboxPath = env("PLATFORM_SMOKE_CRABBOX") || commandPath("crabbox");
+	if (!cboxPath) {
+		fail(`crabbox not found on PATH; install with ${config.requiredCrabbox?.install ?? "Homebrew"} or set PLATFORM_SMOKE_CRABBOX`);
 	} else {
-		try { accessSync(cbox, constants.X_OK); ok(`binary: ${cbox}`); }
-		catch { fail(`${cbox} not executable`); }
+		if (env("PLATFORM_SMOKE_CRABBOX")) {
+			try { accessSync(cboxPath, constants.X_OK); ok(`binary: ${cboxPath} (env override)`); }
+			catch { fail(`${cboxPath} not executable`); }
+		} else {
+			ok(`binary: ${cboxPath} (PATH)`);
+		}
 		const ver = silent(cbox, ["--version"]);
 		const actualVersion = ver?.split("\n")[0]?.trim();
 		if (actualVersion) ok(`version: ${actualVersion}`);
@@ -174,9 +183,9 @@ function runChecks(config) {
 		}
 		const requiredCommit = config.requiredCrabbox?.commit;
 		if (!requiredVersion && !minimumVersion && requiredCommit) {
-			const gitRoot = findGitRoot(dirname(cbox));
+			const gitRoot = findGitRoot(dirname(cboxPath));
 			const actualCommit = gitRoot ? silent("git", ["-C", gitRoot, "rev-parse", "HEAD"]) : null;
-			if (!actualCommit) fail(`could not verify Crabbox source commit for ${cbox}`);
+			if (!actualCommit) fail(`could not verify Crabbox source commit for ${cboxPath}`);
 			else if (actualCommit !== requiredCommit) fail(`Crabbox commit mismatch: expected ${requiredCommit}, got ${actualCommit}`);
 			else ok(`commit: ${actualCommit}`);
 		}
@@ -184,7 +193,7 @@ function runChecks(config) {
 
 	// ── Phase 3: Crabbox providers ──
 	console.log("\n── Crabbox providers ──");
-	if (cbox) {
+	if (cboxPath) {
 		const providerList = silent(cbox, ["providers"]);
 		if (providerList) {
 			for (const provider of ["ssh", "local-container", "parallels"]) {

package/src/context-window-cache.ts

@@ -18,15 +18,31 @@ function isPositiveInteger(value: unknown): value is number {
 	return typeof value === "number" && Number.isInteger(value) && value > 0;
 }
 
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
+function parseContextWindowCacheFile(value: unknown): ContextWindowCacheFile | undefined {
+	if (!isRecord(value)) return undefined;
+	const { contextWindows } = value;
+	if (contextWindows === undefined) return {};
+	if (!isRecord(contextWindows)) return undefined;
+	return {
+		contextWindows: Object.fromEntries(
+			Object.entries(contextWindows).filter((entry): entry is [string, number] => isPositiveInteger(entry[1])),
+		),
+	};
+}
+
 function loadUserContextWindowOverrides(): Map<string, number> {
 	userContextWindowOverrideLoadCount += 1;
 	const path = getCachePath();
 	const overrides = new Map<string, number>();
 	if (!existsSync(path)) return overrides;
 	try {
-		const parsed = JSON.parse(readFileSync(path, "utf-8")) as ContextWindowCacheFile;
-		for (const [modelId, contextWindow] of Object.entries(parsed.contextWindows ?? {})) {
-			if (isPositiveInteger(contextWindow)) overrides.set(modelId, contextWindow);
+		const parsed = parseContextWindowCacheFile(JSON.parse(readFileSync(path, "utf-8")));
+		for (const [modelId, contextWindow] of Object.entries(parsed?.contextWindows ?? {})) {
+			overrides.set(modelId, contextWindow);
 		}
 	} catch {
 		return overrides;
@@ -52,10 +68,10 @@ export function getCachedContextWindow(modelId: string): number | undefined {
 }
 
 export function getCheckpointContextWindow(checkpoint: unknown): number | undefined {
-	if (checkpoint === null || typeof checkpoint !== "object") return undefined;
-	const tokenDetails = (checkpoint as Record<PropertyKey, unknown>).tokenDetails;
-	if (tokenDetails === null || typeof tokenDetails !== "object") return undefined;
-	const maxTokens = (tokenDetails as Record<PropertyKey, unknown>).maxTokens;
+	if (!isRecord(checkpoint)) return undefined;
+	const { tokenDetails } = checkpoint;
+	if (!isRecord(tokenDetails)) return undefined;
+	const { maxTokens } = tokenDetails;
 	if (!isPositiveInteger(maxTokens)) return undefined;
 	return maxTokens;
 }

package/src/cursor-state.ts

@@ -69,10 +69,13 @@ export function parseCursorAgentMode(raw: unknown): AgentModeOption | undefined
 	return isCursorAgentMode(mode) ? mode : undefined;
 }
 
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
 function isCursorFastEntryData(value: unknown): value is CursorFastEntryData {
-	if (!value || typeof value !== "object") return false;
-	const data = value as Record<string, unknown>;
-	return (typeof data.modelId === "string" || typeof data.baseModelId === "string") && typeof data.fast === "boolean";
+	if (!isRecord(value)) return false;
+	return (typeof value.modelId === "string" || typeof value.baseModelId === "string") && typeof value.fast === "boolean";
 }
 
 function getCursorFastEntryModelId(data: CursorFastEntryData): string {
@@ -80,9 +83,19 @@ function getCursorFastEntryModelId(data: CursorFastEntryData): string {
 }
 
 function isCursorModeEntryData(value: unknown): value is CursorModeEntryData {
-	if (!value || typeof value !== "object") return false;
-	const data = value as Record<string, unknown>;
-	return isCursorAgentMode(data.mode);
+	return isRecord(value) && isCursorAgentMode(value.mode);
+}
+
+function parseCursorGlobalConfig(value: unknown): CursorGlobalConfig | undefined {
+	if (!isRecord(value)) return undefined;
+	const { fastDefaults } = value;
+	if (fastDefaults === undefined) return {};
+	if (!isRecord(fastDefaults)) return undefined;
+	return {
+		fastDefaults: Object.fromEntries(
+			Object.entries(fastDefaults).filter((entry): entry is [string, boolean] => typeof entry[1] === "boolean"),
+		),
+	};
 }
 
 function getConfigPath(): string {
@@ -93,12 +106,8 @@ function loadGlobalFastPreferences(): Map<string, boolean> {
 	const path = getConfigPath();
 	if (!existsSync(path)) return new Map();
 	try {
-		const parsed = JSON.parse(readFileSync(path, "utf-8")) as CursorGlobalConfig;
-		return new Map(
-			Object.entries(parsed.fastDefaults ?? {}).filter(
-				(entry): entry is [string, boolean] => typeof entry[1] === "boolean",
-			),
-		);
+		const parsed = parseCursorGlobalConfig(JSON.parse(readFileSync(path, "utf-8")));
+		return new Map(Object.entries(parsed?.fastDefaults ?? {}));
 	} catch {
 		return new Map();
 	}

package/src/model-list-cache.ts

@@ -8,6 +8,7 @@ import { parseEnvBoolean } from "./cursor-env-boolean.js";
 const MODEL_LIST_CACHE_FILE = "cursor-sdk-model-list.json";
 const MODEL_LIST_CACHE_VERSION = 1;
 const DEFAULT_TTL_MS = 24 * 60 * 60 * 1000;
+const MAX_CACHE_CLOCK_SKEW_MS = 5 * 60 * 1000;
 const DISABLE_ENV_VAR = "PI_CURSOR_SDK_DISABLE_MODEL_CACHE";
 const TTL_ENV_VAR = "PI_CURSOR_SDK_MODEL_CACHE_TTL_MS";
 
@@ -45,20 +46,83 @@ export function fingerprintApiKey(apiKey: string): string {
 	return createHash("sha256").update(apiKey).digest("hex").slice(0, 16);
 }
 
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
+function isStringArray(value: unknown): value is string[] {
+	return Array.isArray(value) && value.every((entry) => typeof entry === "string");
+}
+
+function isModelParameterValue(value: unknown): value is NonNullable<ModelListItem["variants"]>[number]["params"][number] {
+	return isRecord(value) && typeof value.id === "string" && typeof value.value === "string";
+}
+
+function isModelParameterDefinitionValue(value: unknown): value is NonNullable<ModelListItem["parameters"]>[number]["values"][number] {
+	return isRecord(value) && typeof value.value === "string" && (value.displayName === undefined || typeof value.displayName === "string");
+}
+
+function isModelParameterDefinition(value: unknown): value is NonNullable<ModelListItem["parameters"]>[number] {
+	if (!isRecord(value)) return false;
+	return (
+		typeof value.id === "string" &&
+		(value.displayName === undefined || typeof value.displayName === "string") &&
+		Array.isArray(value.values) &&
+		value.values.every(isModelParameterDefinitionValue)
+	);
+}
+
+function isModelVariant(value: unknown): value is NonNullable<ModelListItem["variants"]>[number] {
+	if (!isRecord(value)) return false;
+	return (
+		Array.isArray(value.params) &&
+		value.params.every(isModelParameterValue) &&
+		typeof value.displayName === "string" &&
+		(value.description === undefined || typeof value.description === "string") &&
+		(value.isDefault === undefined || typeof value.isDefault === "boolean")
+	);
+}
+
+function isModelListItem(value: unknown): value is ModelListItem {
+	if (!isRecord(value)) return false;
+	return (
+		typeof value.id === "string" &&
+		typeof value.displayName === "string" &&
+		(value.description === undefined || typeof value.description === "string") &&
+		(value.aliases === undefined || isStringArray(value.aliases)) &&
+		(value.parameters === undefined || (Array.isArray(value.parameters) && value.parameters.every(isModelParameterDefinition))) &&
+		(value.variants === undefined || (Array.isArray(value.variants) && value.variants.every(isModelVariant)))
+	);
+}
+
+function isValidFetchedAt(value: unknown): value is number {
+	return typeof value === "number" && Number.isSafeInteger(value) && value >= 0 && value <= Date.now() + MAX_CACHE_CLOCK_SKEW_MS;
+}
+
+function parseModelListCacheFile(value: unknown): ModelListCacheFile | undefined {
+	if (!isRecord(value)) return undefined;
+	if (
+		value.version !== MODEL_LIST_CACHE_VERSION ||
+		!isValidFetchedAt(value.fetchedAt) ||
+		typeof value.keyFingerprint !== "string" ||
+		!Array.isArray(value.models) ||
+		!value.models.every(isModelListItem)
+	) {
+		return undefined;
+	}
+	return {
+		version: value.version,
+		fetchedAt: value.fetchedAt,
+		keyFingerprint: value.keyFingerprint,
+		models: value.models,
+	};
+}
+
 function readCacheFile(): ModelListCacheFile | undefined {
 	const path = getCachePath();
 	if (!existsSync(path)) return undefined;
 	try {
-		const parsed = JSON.parse(readFileSync(path, "utf-8")) as ModelListCacheFile;
-		if (
-			parsed.version !== MODEL_LIST_CACHE_VERSION ||
-			typeof parsed.fetchedAt !== "number" ||
-			typeof parsed.keyFingerprint !== "string" ||
-			!Array.isArray(parsed.models)
-		) {
-			return undefined;
-		}
-		return parsed;
+		return parseModelListCacheFile(JSON.parse(readFileSync(path, "utf-8")));
 	} catch {
 		return undefined;
 	}