@emmaneugene/pi-cursor-sdk 0.3.7

package/scripts/lib/cloud-smoke-shutdown.mjs

@@ -0,0 +1,133 @@
+export function createCloudSmokeShutdownController(terminate) {
+	if (typeof terminate !== "function") throw new TypeError("terminate must be a function");
+	const activeChildren = new Set();
+	const abortController = new AbortController();
+	let shutdownPromise;
+	let reason;
+	let requestedSignal;
+	let terminationFailureReason;
+
+	const terminationFailure = (error) => {
+		if (terminationFailureReason) return terminationFailureReason;
+		terminationFailureReason = new Error(`cloud smoke ${requestedSignal} child termination failed`, { cause: error });
+		terminationFailureReason.signal = requestedSignal;
+		reason = terminationFailureReason;
+		return terminationFailureReason;
+	};
+
+	const track = async (child) => {
+		if (abortController.signal.aborted) {
+			try {
+				await terminate(child);
+			} catch (error) {
+				throw terminationFailure(error);
+			}
+			throw reason;
+		}
+		activeChildren.add(child);
+		const untrack = () => activeChildren.delete(child);
+		child.once?.("close", untrack);
+		return untrack;
+	};
+
+	const request = async (signalName) => {
+		if (!abortController.signal.aborted) {
+			requestedSignal = signalName;
+			const interruptReason = new Error(`cloud smoke interrupted by ${signalName}`);
+			interruptReason.signal = signalName;
+			reason = interruptReason;
+			const terminations = [...activeChildren].map((child) => Promise.resolve().then(() => terminate(child)));
+			shutdownPromise = Promise.allSettled(terminations).then((results) => {
+				const failed = results.find((result) => result.status === "rejected");
+				if (failed) throw terminationFailure(failed.reason);
+			});
+			abortController.abort(interruptReason);
+		}
+		await shutdownPromise;
+		return reason;
+	};
+
+	return {
+		signal: abortController.signal,
+		track,
+		request,
+		get reason() { return reason; },
+		wait: () => shutdownPromise ?? Promise.resolve(),
+		throwIfRequested() {
+			if (abortController.signal.aborted) throw reason;
+		},
+	};
+}
+
+export async function awaitCloudSmokeShutdown(shutdown, tracking = Promise.resolve()) {
+	const results = await Promise.allSettled([shutdown.wait(), tracking]);
+	const failed = results.find((result) => result.status === "rejected");
+	const outcome = failed?.reason ?? shutdown.reason;
+	return outcome instanceof Error ? outcome : new Error("cloud smoke shutdown failed", { cause: outcome });
+}
+
+export async function checkpointCloudSmokeShutdown(shutdown) {
+	await new Promise((resolve) => setImmediate(resolve));
+	shutdown.throwIfRequested();
+}
+
+export function createCloudSmokeTerminalFailureState(rejectPending) {
+	let failure;
+	return {
+		record(error) {
+			failure ??= error;
+			rejectPending(failure);
+		},
+		throwIfFailed() {
+			if (failure) throw failure;
+		},
+	};
+}
+
+export async function stopCloudSmokeTrackedChild(shutdown, tracking, terminateChild) {
+	const termination = Promise.resolve().then(terminateChild);
+	const [terminationResult] = await Promise.allSettled([termination]);
+	if (shutdown.signal.aborted) {
+		const results = await Promise.allSettled([shutdown.wait(), tracking, termination]);
+		const failed = results.find((result) => result.status === "rejected");
+		if (failed) throw failed.reason instanceof Error ? failed.reason : new Error("cloud smoke child termination failed", { cause: failed.reason });
+		return shutdown.reason;
+	}
+	if (terminationResult.status === "rejected") throw terminationResult.reason;
+	return undefined;
+}
+
+export function routeCloudSmokeChildError(shutdown, onShutdown, onError, error) {
+	if (shutdown.signal.aborted) onShutdown();
+	else onError(error);
+}
+
+export function installCloudSmokeChildErrorHandlers(child, shutdown, onShutdown, onError) {
+	const routeError = (error) => routeCloudSmokeChildError(shutdown, onShutdown, onError, error);
+	child.once("error", routeError);
+	child.stdin?.on?.("error", routeError);
+	return routeError;
+}
+
+export function routeCloudSmokeChildClose(shutdown, timedOut, onShutdown, onClose, result) {
+	if (shutdown.signal.aborted) onShutdown();
+	else if (!timedOut) onClose(result);
+}
+
+export function installCloudSmokeSignalHandlers(shutdown, processLike = process, onSignal) {
+	const handlers = new Map();
+	for (const signalName of ["SIGINT", "SIGTERM"]) {
+		const handler = () => {
+			try {
+				onSignal?.(signalName);
+			} finally {
+				void shutdown.request(signalName).catch(() => {});
+			}
+		};
+		handlers.set(signalName, handler);
+		processLike.on(signalName, handler);
+	}
+	return () => {
+		for (const [signalName, handler] of handlers) processLike.off(signalName, handler);
+	};
+}

package/scripts/lib/cursor-child-process.d.mts

@@ -0,0 +1,11 @@
+import type { ChildProcess } from "node:child_process";
+
+export declare const DEFAULT_CHILD_SHUTDOWN_GRACE_MS: number;
+export declare const CHILD_PROCESS_TREE_SPAWN_OPTIONS: Readonly<{ detached: boolean }>;
+export declare function waitForChildClose(child: ChildProcess): Promise<number>;
+export declare function signalChild(child: ChildProcess, signal: NodeJS.Signals): void;
+export declare function terminateChild(
+	child: ChildProcess,
+	options?: { graceMs?: number },
+): Promise<void>;
+export declare function parseJsonLines(stdout: string): unknown[];

package/scripts/lib/cursor-child-process.mjs

@@ -0,0 +1,180 @@
+import { execFile } from "node:child_process";
+
+export const DEFAULT_CHILD_SHUTDOWN_GRACE_MS = 2_000;
+export const CHILD_PROCESS_TREE_SPAWN_OPTIONS = Object.freeze({
+	detached: process.platform !== "win32",
+});
+
+export function waitForChildClose(child) {
+	if (child.exitCode !== null || child.signalCode !== null) return Promise.resolve(child.exitCode ?? 1);
+	return new Promise((resolve) => {
+		child.once("close", (code) => resolve(code ?? 1));
+	});
+}
+
+export function signalChild(child, signal) {
+	if (!child.pid) return;
+	try {
+		if (process.platform === "win32") {
+			child.kill(signal);
+		} else {
+			process.kill(-child.pid, signal);
+		}
+	} catch {
+		try {
+			child.kill(signal);
+		} catch {
+			// child already exited
+		}
+	}
+}
+
+function runHiddenWindowsCommand(command, args, timeoutMs) {
+	return new Promise((resolve) => {
+		let settled = false;
+		let timer;
+		const finish = (succeeded) => {
+			if (settled) return;
+			settled = true;
+			clearTimeout(timer);
+			resolve(succeeded);
+		};
+		const child = execFile(
+			command,
+			args,
+			{ maxBuffer: 64 * 1024, timeout: timeoutMs, windowsHide: true },
+			(error) => finish(error === null),
+		);
+		timer = setTimeout(() => {
+			child.kill("SIGKILL");
+			finish(false);
+		}, timeoutMs);
+	});
+}
+
+async function terminateWindowsProcessTree(pid, timeoutMs) {
+	if (await runHiddenWindowsCommand("taskkill", ["/PID", String(pid), "/T", "/F"], timeoutMs)) return true;
+
+	const script = `
+$ErrorActionPreference = "Stop"
+$rootPid = [uint32]${pid}
+$deadline = [DateTime]::UtcNow.AddMilliseconds(${timeoutMs})
+try {
+	$processes = @(Get-CimInstance -ClassName Win32_Process -Property ProcessId,ParentProcessId)
+	$queue = [Collections.Generic.Queue[uint32]]::new()
+	$descendants = [Collections.Generic.List[uint32]]::new()
+	$seen = [Collections.Generic.HashSet[uint32]]::new()
+	$queue.Enqueue($rootPid)
+	while ($queue.Count -gt 0) {
+		$parentPid = $queue.Dequeue()
+		foreach ($process in $processes) {
+			$childPid = [uint32]$process.ProcessId
+			if ([uint32]$process.ParentProcessId -eq $parentPid -and $seen.Add($childPid)) {
+				$descendants.Add($childPid)
+				$queue.Enqueue($childPid)
+			}
+		}
+	}
+	for ($index = $descendants.Count - 1; $index -ge 0; $index--) {
+		Stop-Process -Id $descendants[$index] -Force -ErrorAction SilentlyContinue
+	}
+	Stop-Process -Id $rootPid -Force -ErrorAction SilentlyContinue
+	$targets = @($rootPid) + @($descendants)
+	do {
+		$alive = @(Get-Process -Id $targets -ErrorAction SilentlyContinue)
+		if ($alive.Count -eq 0) { exit 0 }
+		Start-Sleep -Milliseconds 25
+	} while ([DateTime]::UtcNow -lt $deadline)
+} catch {}
+exit 1
+`;
+	return runHiddenWindowsCommand(
+		"powershell.exe",
+		["-NoLogo", "-NoProfile", "-NonInteractive", "-ExecutionPolicy", "Bypass", "-Command", script],
+		timeoutMs,
+	);
+}
+
+function waitForChildCloseWithin(child, timeoutMs) {
+	if (child.exitCode !== null || child.signalCode !== null) return Promise.resolve(true);
+	return new Promise((resolve) => {
+		const finish = (closed) => {
+			clearTimeout(timer);
+			child.off("close", onClose);
+			resolve(closed);
+		};
+		const onClose = () => finish(true);
+		const timer = setTimeout(() => finish(false), timeoutMs);
+		child.once("close", onClose);
+	});
+}
+
+function posixProcessGroupExists(pid) {
+	try {
+		process.kill(-pid, 0);
+		return true;
+	} catch (error) {
+		return error?.code !== "ESRCH";
+	}
+}
+
+async function waitForPosixProcessGroupExit(pid, timeoutMs) {
+	const deadline = Date.now() + timeoutMs;
+	while (posixProcessGroupExists(pid) && Date.now() < deadline) {
+		await new Promise((resolve) => setTimeout(resolve, Math.min(25, deadline - Date.now())));
+	}
+	return !posixProcessGroupExists(pid);
+}
+
+export async function terminateChild(child, { graceMs = DEFAULT_CHILD_SHUTDOWN_GRACE_MS } = {}) {
+	const pid = child.pid;
+	if (!pid) return;
+	const timeoutMs = Number.isFinite(graceMs) ? Math.max(1, Math.trunc(graceMs)) : DEFAULT_CHILD_SHUTDOWN_GRACE_MS;
+	try {
+		child.stdin?.end?.();
+	} catch {
+		child.stdin?.destroy?.();
+	}
+	await waitForChildCloseWithin(child, timeoutMs);
+	if (process.platform === "win32") {
+		// CIM enumeration can exceed a short graceful-shutdown window on a busy Windows VM;
+		// keep the process-tree discovery bounded but give orphan lookup a stable floor.
+		const treeTimeoutMs = Math.max(timeoutMs, 15_000);
+		if (!(await terminateWindowsProcessTree(pid, treeTimeoutMs))) {
+			signalChild(child, "SIGTERM");
+			if (!(await waitForChildCloseWithin(child, timeoutMs))) {
+				signalChild(child, "SIGKILL");
+				await waitForChildCloseWithin(child, timeoutMs);
+			}
+			throw new Error(`failed to verify termination of Windows process tree rooted at ${pid}`);
+		}
+		if (!(await waitForChildCloseWithin(child, timeoutMs))) {
+			throw new Error(`Windows process tree exited but child ${pid} did not close`);
+		}
+		return;
+	}
+
+	if (posixProcessGroupExists(pid)) signalChild(child, "SIGTERM");
+	let groupExited = await waitForPosixProcessGroupExit(pid, timeoutMs);
+	if (!groupExited) {
+		signalChild(child, "SIGKILL");
+		groupExited = await waitForPosixProcessGroupExit(pid, timeoutMs);
+	}
+	const childClosed = await waitForChildCloseWithin(child, timeoutMs);
+	if (!groupExited || !childClosed) {
+		throw new Error(`failed to verify termination of POSIX process tree rooted at ${pid}`);
+	}
+}
+
+export function parseJsonLines(stdout) {
+	const events = [];
+	for (const line of stdout.split("\n")) {
+		if (!line.trim()) continue;
+		try {
+			events.push(JSON.parse(line));
+		} catch {
+			// ignore partial lines
+		}
+	}
+	return events;
+}

package/scripts/lib/cursor-cli-args.d.mts

@@ -0,0 +1,63 @@
+export interface CursorCliValueFlagSpec<TValue = string> {
+	[key: string]: unknown;
+	names: readonly string[];
+	takesValue?: true;
+	repeat?: boolean;
+	allowDashValue?: boolean;
+	assign?: (value: string, flagName: string) => TValue;
+}
+
+export interface CursorCliBooleanFlagSpec<TValue = boolean> {
+	[key: string]: unknown;
+	names: readonly string[];
+	takesValue: false;
+	repeat?: boolean;
+	assign?: (value: true, flagName: string) => TValue;
+}
+
+export type CursorCliFlagSpec<TValue = string> = CursorCliValueFlagSpec<TValue> | CursorCliBooleanFlagSpec<TValue>;
+
+export type CursorCliFlagSpecMap<TArgs extends Record<string, unknown>> = {
+	[K in keyof TArgs]?: CursorCliFlagSpec<unknown>;
+};
+
+export type ParsedCursorCliArgs<TDefaults extends Record<string, unknown>> = TDefaults & { help: boolean };
+
+export declare function readArgvValue(
+	argv: readonly string[],
+	index: number,
+	flagName: string,
+	fail: (message: string) => never,
+	options?: { allowDashValue?: boolean },
+): string;
+export declare function parseArgv<TDefaults extends Record<string, unknown>>(
+	argv: readonly string[],
+	options: { defaults: TDefaults; flags: CursorCliFlagSpecMap<TDefaults>; fail: (message: string) => never },
+): ParsedCursorCliArgs<TDefaults>;
+export declare function defaultSettingSourcesFromEnv(env?: NodeJS.ProcessEnv): string[] | undefined;
+export declare function defaultApiKeyFromEnv(env?: NodeJS.ProcessEnv): string | undefined;
+export declare function readArgvApiKey(argv: readonly string[]): string | undefined;
+export declare function apiKeySecretsFromProcess(
+	argv?: readonly string[],
+	env?: NodeJS.ProcessEnv,
+): Array<string | undefined>;
+export declare function requireApiKey(
+	args: { apiKey?: string },
+	env: NodeJS.ProcessEnv,
+	fail: (message: string) => never,
+): string;
+export declare function defaultTimestampedDir(prefix: string, baseDir?: string): string;
+export declare const commonProbePathFlag: <TKey extends string>(key: TKey) => CursorCliValueFlagSpec<string>;
+export declare const commonProbeStringFlag: <TKey extends string>(key: TKey) => CursorCliValueFlagSpec<string>;
+export declare const commonBooleanFlag: (...names: string[]) => CursorCliBooleanFlagSpec<boolean>;
+export declare const commonRepeatStringFlag: (...names: string[]) => CursorCliValueFlagSpec<string>;
+export declare const commonProbeFlags: {
+	readonly cwd: CursorCliValueFlagSpec<string>;
+	readonly model: CursorCliValueFlagSpec<string>;
+	readonly prompt: CursorCliValueFlagSpec<string>;
+	readonly out: CursorCliValueFlagSpec<string>;
+	readonly sessionDir: CursorCliValueFlagSpec<string>;
+	readonly promptFile: CursorCliValueFlagSpec<string>;
+	readonly apiKey: CursorCliValueFlagSpec<string>;
+	readonly settingSources: CursorCliValueFlagSpec<string[] | undefined>;
+};

package/scripts/lib/cursor-cli-args.mjs

@@ -0,0 +1,129 @@
+import { resolve } from "node:path";
+import { CURSOR_SETTING_SOURCES_ENV, resolveCursorSettingSources } from "../../shared/cursor-setting-sources.mjs";
+
+export function readArgvValue(argv, index, flagName, fail, options = {}) {
+	const current = argv[index];
+	if (!current || (!options.allowDashValue && current.startsWith("--"))) {
+		fail(`${flagName} requires a value`);
+	}
+	return current;
+}
+
+function assignParsedArg(args, key, spec, raw, flagName) {
+	const value = spec.assign ? spec.assign(raw, flagName) : raw;
+	if (spec.repeat) {
+		args[key] = [...(Array.isArray(args[key]) ? args[key] : []), value];
+		return;
+	}
+	args[key] = value;
+}
+
+export function parseArgv(argv, { defaults, flags, fail }) {
+	const args = { ...defaults, help: false };
+	for (let index = 0; index < argv.length; index++) {
+		const arg = argv[index];
+		if (arg === "-h" || arg === "--help") {
+			args.help = true;
+			continue;
+		}
+
+		let matched = false;
+		for (const [key, spec] of Object.entries(flags)) {
+			for (const flagName of spec.names) {
+				if (arg === flagName) {
+					if (spec.takesValue === false) {
+						assignParsedArg(args, key, spec, true, flagName);
+					} else {
+						const raw = readArgvValue(argv, ++index, flagName, fail, { allowDashValue: spec.allowDashValue === true });
+						assignParsedArg(args, key, spec, raw, flagName);
+					}
+					matched = true;
+					break;
+				}
+				if (arg.startsWith(`${flagName}=`)) {
+					if (spec.takesValue === false) fail(`${flagName} does not accept a value`);
+					const raw = arg.slice(flagName.length + 1);
+					assignParsedArg(args, key, spec, raw, flagName);
+					matched = true;
+					break;
+				}
+			}
+			if (matched) break;
+		}
+		if (!matched) fail(`unknown argument: ${arg}`);
+	}
+	return args;
+}
+
+export function defaultSettingSourcesFromEnv(env = process.env) {
+	return resolveCursorSettingSources(env[CURSOR_SETTING_SOURCES_ENV]);
+}
+
+export function defaultApiKeyFromEnv(env = process.env) {
+	return env.CURSOR_API_KEY?.trim() || undefined;
+}
+
+export function readArgvApiKey(argv) {
+	for (let index = 0; index < argv.length; index++) {
+		const arg = argv[index];
+		if (arg === "--api-key") {
+			const value = argv[index + 1];
+			return typeof value === "string" ? value.trim() : undefined;
+		}
+		if (arg.startsWith("--api-key=")) return arg.slice("--api-key=".length).trim();
+	}
+	return undefined;
+}
+
+export function apiKeySecretsFromProcess(argv = process.argv.slice(2), env = process.env) {
+	return [defaultApiKeyFromEnv(env), readArgvApiKey(argv)];
+}
+
+export function requireApiKey(args, env, fail) {
+	const apiKey = args.apiKey ?? defaultApiKeyFromEnv(env);
+	if (!apiKey) {
+		fail("Cursor API key is required. Set CURSOR_API_KEY or pass --api-key.");
+	}
+	return apiKey;
+}
+
+export function defaultTimestampedDir(prefix, baseDir = "/tmp") {
+	const stamp = new Date().toISOString().replace(/[:.]/g, "-");
+	return resolve(baseDir, `${prefix}-${stamp}`);
+}
+
+export const commonProbePathFlag = (key) => ({
+	names: [`--${key}`],
+	assign: (value) => resolve(value),
+});
+
+export const commonProbeStringFlag = (key) => ({
+	names: [`--${key}`],
+});
+
+export const commonBooleanFlag = (...names) => ({
+	names,
+	takesValue: false,
+});
+
+export const commonRepeatStringFlag = (...names) => ({
+	names,
+	repeat: true,
+});
+
+export const commonProbeFlags = {
+	cwd: commonProbePathFlag("cwd"),
+	model: commonProbeStringFlag("model"),
+	prompt: commonProbeStringFlag("prompt"),
+	out: commonProbePathFlag("out"),
+	sessionDir: { names: ["--session-dir"], assign: (value) => resolve(value) },
+	promptFile: { names: ["--prompt-file"], assign: (value) => resolve(value) },
+	apiKey: {
+		names: ["--api-key"],
+		assign: (value) => value.trim(),
+	},
+	settingSources: {
+		names: ["--setting-sources"],
+		assign: (value) => resolveCursorSettingSources(value),
+	},
+};

package/scripts/lib/cursor-script-fail.d.mts

@@ -0,0 +1 @@
+export declare function createScriptFail(prefix: string): (message: string, secrets?: string | string[]) => never;

package/scripts/lib/cursor-script-fail.mjs

@@ -0,0 +1,13 @@
+import { scrubSensitiveText } from "../../shared/cursor-sensitive-text.mjs";
+
+export function createScriptFail(prefix) {
+	return (message, secrets = []) => {
+		const secretList = Array.isArray(secrets) ? secrets : [secrets];
+		let scrubbed = scrubSensitiveText(message);
+		for (const secret of secretList) {
+			if (secret) scrubbed = scrubSensitiveText(scrubbed, secret);
+		}
+		console.error(`${prefix}: ${scrubbed}`);
+		process.exit(1);
+	};
+}

package/scripts/lib/cursor-sdk-output-filter.d.mts

@@ -0,0 +1,7 @@
+export {
+	CURSOR_SDK_STARTUP_NOISE_PATTERNS,
+	installCursorSdkOutputFilter,
+	isCursorSdkOutputSuppressed,
+	isCursorSdkStartupNoise,
+	suppressCursorSdkOutput,
+} from "../../shared/cursor-sdk-output-filter.mjs";

package/scripts/lib/cursor-sdk-output-filter.mjs

@@ -0,0 +1,7 @@
+export {
+	CURSOR_SDK_STARTUP_NOISE_PATTERNS,
+	installCursorSdkOutputFilter,
+	isCursorSdkOutputSuppressed,
+	isCursorSdkStartupNoise,
+	suppressCursorSdkOutput,
+} from "../../shared/cursor-sdk-output-filter.mjs";

package/scripts/lib/cursor-smoke-env.d.mts

@@ -0,0 +1,38 @@
+export {
+	CURSOR_SDK_EVENT_DEBUG_DIR_ENV,
+	CURSOR_SDK_EVENT_DEBUG_ENV,
+	CURSOR_SDK_EVENT_DEBUG_ENV_NAMES,
+	CURSOR_SDK_EVENT_DEBUG_RUN_DIR_ENV,
+	CURSOR_SDK_EVENT_DEBUG_SESSION_DIR_ENV,
+	CURSOR_SDK_EVENT_DEBUG_STDERR_ENV,
+} from "../../shared/cursor-sdk-event-debug-env.mjs";
+
+export declare function sealedNodePath(nodePath?: string, envPath?: string): string;
+export declare function clearCursorSdkEventDebugEnv<TEnv extends Record<string, string | undefined>>(env: TEnv): TEnv;
+export declare function buildCursorSmokeEnv(options?: {
+	baseEnv?: Record<string, string | undefined>;
+	nodePath?: string;
+	settingSources?: string | null;
+	nativeToolDisplay?: boolean;
+	registerNativeTools?: boolean;
+	bridge?: boolean;
+	exposeBuiltinTools?: boolean;
+	term?: string;
+	eventDebugDir?: string;
+}): Record<string, string | undefined>;
+export declare function buildCursorSmokeEnvPlan(options?: {
+	baseEnv?: Record<string, string | undefined>;
+	nodePath?: string;
+	settingSources?: string | null;
+	nativeToolDisplay?: boolean;
+	registerNativeTools?: boolean;
+	bridge?: boolean;
+	exposeBuiltinTools?: boolean;
+	term?: string;
+	eventDebugDir?: string;
+}): {
+	env: Record<string, string | undefined>;
+	sealedPath: string;
+	clearEnvNames: string[];
+	envEntries: Array<[string, string]>;
+};

package/scripts/lib/cursor-smoke-env.mjs

@@ -0,0 +1,81 @@
+import { delimiter, dirname } from "node:path";
+import {
+	CURSOR_SDK_EVENT_DEBUG_DIR_ENV,
+	CURSOR_SDK_EVENT_DEBUG_ENV,
+	CURSOR_SDK_EVENT_DEBUG_ENV_NAMES,
+	CURSOR_SDK_EVENT_DEBUG_RUN_DIR_ENV,
+	CURSOR_SDK_EVENT_DEBUG_SESSION_DIR_ENV,
+	CURSOR_SDK_EVENT_DEBUG_STDERR_ENV,
+} from "../../shared/cursor-sdk-event-debug-env.mjs";
+
+export {
+	CURSOR_SDK_EVENT_DEBUG_DIR_ENV,
+	CURSOR_SDK_EVENT_DEBUG_ENV,
+	CURSOR_SDK_EVENT_DEBUG_ENV_NAMES,
+	CURSOR_SDK_EVENT_DEBUG_RUN_DIR_ENV,
+	CURSOR_SDK_EVENT_DEBUG_SESSION_DIR_ENV,
+	CURSOR_SDK_EVENT_DEBUG_STDERR_ENV,
+};
+
+export function sealedNodePath(nodePath = process.execPath, envPath = process.env.PATH ?? "") {
+	return [dirname(nodePath), envPath].filter(Boolean).join(delimiter);
+}
+
+export function clearCursorSdkEventDebugEnv(env) {
+	for (const name of CURSOR_SDK_EVENT_DEBUG_ENV_NAMES) delete env[name];
+	return env;
+}
+
+function boolEnv(value) {
+	return value ? "1" : "0";
+}
+
+function pushIfDefined(entries, name, value) {
+	if (value !== undefined) entries.push([name, value]);
+}
+
+export function buildCursorSmokeEnv({
+	baseEnv = process.env,
+	nodePath = process.execPath,
+	settingSources,
+	nativeToolDisplay,
+	registerNativeTools,
+	bridge,
+	exposeBuiltinTools,
+	term,
+	eventDebugDir,
+} = {}) {
+	const env = clearCursorSdkEventDebugEnv({ ...baseEnv });
+	env.PATH = sealedNodePath(nodePath, baseEnv.PATH ?? "");
+	if (settingSources === null) delete env.PI_CURSOR_SETTING_SOURCES;
+	else if (settingSources !== undefined) env.PI_CURSOR_SETTING_SOURCES = settingSources;
+	if (nativeToolDisplay !== undefined) env.PI_CURSOR_NATIVE_TOOL_DISPLAY = boolEnv(nativeToolDisplay);
+	if (registerNativeTools !== undefined) env.PI_CURSOR_REGISTER_NATIVE_TOOLS = boolEnv(registerNativeTools);
+	if (bridge !== undefined) env.PI_CURSOR_PI_TOOL_BRIDGE = boolEnv(bridge);
+	if (exposeBuiltinTools !== undefined) env.PI_CURSOR_EXPOSE_BUILTIN_TOOLS = boolEnv(exposeBuiltinTools);
+	if (term !== undefined) env.TERM = term;
+	if (eventDebugDir !== undefined) {
+		env[CURSOR_SDK_EVENT_DEBUG_ENV] = "1";
+		env[CURSOR_SDK_EVENT_DEBUG_DIR_ENV] = eventDebugDir;
+	}
+	return env;
+}
+
+export function buildCursorSmokeEnvPlan(options = {}) {
+	const env = buildCursorSmokeEnv(options);
+	const envEntries = [];
+	pushIfDefined(envEntries, "PI_CURSOR_SETTING_SOURCES", options.settingSources === null ? undefined : options.settingSources);
+	pushIfDefined(envEntries, "PI_CURSOR_NATIVE_TOOL_DISPLAY", options.nativeToolDisplay === undefined ? undefined : boolEnv(options.nativeToolDisplay));
+	pushIfDefined(envEntries, "PI_CURSOR_REGISTER_NATIVE_TOOLS", options.registerNativeTools === undefined ? undefined : boolEnv(options.registerNativeTools));
+	pushIfDefined(envEntries, "PI_CURSOR_PI_TOOL_BRIDGE", options.bridge === undefined ? undefined : boolEnv(options.bridge));
+	pushIfDefined(envEntries, "PI_CURSOR_EXPOSE_BUILTIN_TOOLS", options.exposeBuiltinTools === undefined ? undefined : boolEnv(options.exposeBuiltinTools));
+	pushIfDefined(envEntries, "TERM", options.term);
+	pushIfDefined(envEntries, CURSOR_SDK_EVENT_DEBUG_ENV, options.eventDebugDir === undefined ? undefined : "1");
+	pushIfDefined(envEntries, CURSOR_SDK_EVENT_DEBUG_DIR_ENV, options.eventDebugDir);
+	return {
+		env,
+		sealedPath: env.PATH,
+		clearEnvNames: [...CURSOR_SDK_EVENT_DEBUG_ENV_NAMES],
+		envEntries,
+	};
+}