pi-cursor-sdk 0.1.19 → 0.1.21

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,5 @@
+export declare const CURSOR_SDK_STARTUP_NOISE_PATTERNS: readonly string[];
+export declare function isCursorSdkOutputSuppressed(): boolean;
+export declare function suppressCursorSdkOutput<T>(operation: () => T): T;
+export declare function isCursorSdkStartupNoise(text: string): boolean;
+export declare function installCursorSdkOutputFilter(): () => void;

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,
+	};
+}

package/scripts/lib/cursor-smoke-shell.sh

@@ -0,0 +1,174 @@
+# Shared maintainer smoke shell helpers (timeout, logging, auth seeding).
+# Source from top-level smoke scripts: . "$(dirname "$0")/lib/cursor-smoke-shell.sh"
+
+: "${SMOKE_LOG_PREFIX:=smoke}"
+SMOKE_KILL_GRACE_SECS="${SMOKE_KILL_GRACE_SECS:-2}"
+SMOKE_CURSOR_SDK_EVENT_DEBUG_ENV_NAMES=()
+SMOKE_CURSOR_SDK_EVENT_DEBUG_ENV_UNSETS=()
+
+smoke_log() {
+	printf '[%s] %s\n' "$SMOKE_LOG_PREFIX" "$*"
+}
+
+smoke_fail() {
+	printf '[%s] FAIL: %s\n' "$SMOKE_LOG_PREFIX" "$*" >&2
+	exit 1
+}
+
+smoke_require_cmd() {
+	command -v "$1" >/dev/null 2>&1 || smoke_fail "missing required command: $1"
+}
+
+smoke_resolve_cmd() {
+	local name="$1"
+	local path
+	if ! path="$(command -v -- "$name" 2>/dev/null)" || [[ -z "$path" ]]; then
+		smoke_fail "missing required command: $name"
+	fi
+	if [[ "$path" != /* ]]; then
+		smoke_fail "required command $name did not resolve to an absolute path: $path"
+	fi
+	printf '%s\n' "$path"
+}
+
+smoke_build_sealed_node_path() {
+	local node_bin="$1"
+	local base_path
+	if (( $# >= 2 )); then
+		base_path="$2"
+	else
+		base_path="$PATH"
+	fi
+	if [[ -n "$base_path" ]]; then
+		printf '%s:%s\n' "$(dirname "$node_bin")" "$base_path"
+	else
+		printf '%s\n' "$(dirname "$node_bin")"
+	fi
+}
+
+smoke_load_cursor_sdk_event_debug_env_names() {
+	local node_bin="$1"
+	local module_path="$2"
+	local name
+	SMOKE_CURSOR_SDK_EVENT_DEBUG_ENV_NAMES=()
+	while IFS= read -r name; do
+		[[ -n "$name" ]] || continue
+		SMOKE_CURSOR_SDK_EVENT_DEBUG_ENV_NAMES+=( "$name" )
+	done < <("$node_bin" --input-type=module -e 'import { pathToFileURL } from "node:url"; const mod = await import(pathToFileURL(process.argv[1]).href); for (const name of mod.CURSOR_SDK_EVENT_DEBUG_ENV_NAMES) console.log(name);' "$module_path")
+	if [[ "${#SMOKE_CURSOR_SDK_EVENT_DEBUG_ENV_NAMES[@]}" -eq 0 ]]; then
+		smoke_fail "failed to load Cursor SDK event-debug env names from $module_path"
+	fi
+}
+
+smoke_build_cursor_sdk_event_debug_unsets() {
+	local name
+	SMOKE_CURSOR_SDK_EVENT_DEBUG_ENV_UNSETS=()
+	for name in "${SMOKE_CURSOR_SDK_EVENT_DEBUG_ENV_NAMES[@]}"; do
+		SMOKE_CURSOR_SDK_EVENT_DEBUG_ENV_UNSETS+=( -u "$name" )
+	done
+}
+
+# Run a command with a wall-clock timeout. Prefer GNU/BSD timeout; fall back to a
+# process-group kill watcher with TERM then KILL (same semantics as tmux live smoke).
+smoke_run_with_timeout() {
+	local timeout_secs="$1"
+	shift
+	if command -v timeout >/dev/null 2>&1; then
+		timeout "$timeout_secs" "$@"
+		return $?
+	fi
+	if command -v gtimeout >/dev/null 2>&1; then
+		gtimeout "$timeout_secs" "$@"
+		return $?
+	fi
+
+	local restore_monitor=0
+	case $- in
+		*m*) ;;
+		*)
+			restore_monitor=1
+			set -m
+			;;
+	esac
+
+	"$@" &
+	local pid=$!
+	(
+		sleep "$timeout_secs"
+		kill -TERM "-$pid" 2>/dev/null || kill -TERM "$pid" 2>/dev/null || true
+		sleep "$SMOKE_KILL_GRACE_SECS"
+		kill -KILL "-$pid" 2>/dev/null || kill -KILL "$pid" 2>/dev/null || true
+	) &
+	local watcher=$!
+	local code=0
+	if wait "$pid"; then
+		code=0
+	else
+		code=$?
+	fi
+	kill "$watcher" 2>/dev/null || true
+	wait "$watcher" 2>/dev/null || true
+	if (( restore_monitor )); then
+		set +m
+	fi
+	return "$code"
+}
+
+# Run with timeout; map exit 124/137/143 to a smoke_fail timeout message.
+smoke_run_with_timeout_or_fail() {
+	local label="$1"
+	local timeout_secs="$2"
+	shift 2
+	smoke_log "$label (timeout ${timeout_secs}s)"
+	local restore_errexit=0
+	case $- in
+		*e*)
+			restore_errexit=1
+			set +e
+			;;
+	esac
+	local rc=0
+	smoke_run_with_timeout "$timeout_secs" "$@"
+	rc=$?
+	if (( restore_errexit )); then
+		set -e
+	fi
+	if [[ "$rc" -eq 0 ]]; then
+		return 0
+	fi
+	case "$rc" in
+		124|137|143) smoke_fail "$label timed out after ${timeout_secs}s" ;;
+		*) smoke_fail "$label exited $rc" ;;
+	esac
+}
+
+smoke_seed_pi_agent_home() {
+	local home="$1"
+	local auth_json="${2:-${AUTH_JSON:-${REAL_HOME:-$HOME}/.pi/agent/auth.json}}"
+	local models_src="${3:-${PI_AGENT_DIR:-${REAL_HOME:-$HOME}/.pi/agent}/models.json}"
+	mkdir -p "$home/.pi/agent"
+	if [[ -f "$auth_json" ]]; then
+		cp "$auth_json" "$home/.pi/agent/auth.json"
+		chmod 600 "$home/.pi/agent/auth.json"
+		smoke_log "seeded $home/.pi/agent/auth.json"
+	else
+		smoke_log "WARN: no auth.json at $auth_json"
+	fi
+	if [[ -f "$models_src" ]]; then
+		cp "$models_src" "$home/.pi/agent/models.json"
+	fi
+}
+
+smoke_has_auth_provider() {
+	local provider="$1"
+	local auth_path="$2"
+	python3 - "$provider" "$auth_path" <<'PY'
+import json, sys
+provider, path = sys.argv[1], sys.argv[2]
+try:
+    data = json.load(open(path))
+except FileNotFoundError:
+    sys.exit(1)
+sys.exit(0 if provider in data and data[provider] else 1)
+PY
+}

package/scripts/lib/cursor-visual-render.d.mts

@@ -0,0 +1,15 @@
+export declare function buildTerminalHtml(args: {
+	ansi: string;
+	plain: string;
+	options: {
+		label: string;
+		model: string;
+		mode: string;
+		cwd: string;
+		sessionId: string;
+		width: number;
+		height: number;
+		historyLines: number;
+	};
+}): string;
+export declare function writeTerminalScreenshot(htmlPath: string, pngPath: string, width: number, height: number): Promise<void>;

package/scripts/lib/cursor-visual-render.mjs

@@ -0,0 +1,131 @@
+import { readFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { pathToFileURL } from "node:url";
+
+function escapeHtml(text) {
+	return text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+
+function htmlJson(value) {
+	return JSON.stringify(value).replace(/</g, "\\u003c");
+}
+
+function loadXtermAssets() {
+	const require = createRequire(import.meta.url);
+	try {
+		return {
+			css: readFileSync(require.resolve("@xterm/xterm/css/xterm.css"), "utf8"),
+			js: readFileSync(require.resolve("@xterm/xterm/lib/xterm.js"), "utf8"),
+		};
+	} catch (error) {
+		throw new Error(`failed to load @xterm/xterm assets; run npm install: ${error instanceof Error ? error.message : String(error)}`);
+	}
+}
+
+export function buildTerminalHtml({ ansi, plain, options }) {
+	const assets = loadXtermAssets();
+	return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<title>pi-cursor-sdk visual smoke: ${escapeHtml(options.label)}</title>
+<style>
+${assets.css}
+:root { color-scheme: dark; }
+body {
+	margin: 0;
+	padding: 16px;
+	background: #0b0f14;
+	color: #d8dee9;
+	font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+}
+header {
+	margin: 0 0 12px;
+	font-size: 13px;
+	line-height: 1.4;
+	color: #9aa4b2;
+}
+header code { color: #d8dee9; }
+#terminal {
+	display: inline-block;
+	padding: 12px;
+	border: 1px solid #303846;
+	border-radius: 8px;
+	background: #0b0f14;
+	box-shadow: 0 12px 40px rgba(0, 0, 0, 0.35);
+}
+.fallback {
+	white-space: pre-wrap;
+	font-family: Menlo, Monaco, Consolas, "Liberation Mono", monospace;
+	font-size: 12px;
+}
+</style>
+<script>${assets.js}</script>
+</head>
+<body>
+<header>
+	<div><strong>pi-cursor-sdk visual smoke</strong> <code>${escapeHtml(options.label)}</code></div>
+	<div>model <code>${escapeHtml(options.model)}</code> · mode <code>${escapeHtml(options.mode)}</code> · cwd <code>${escapeHtml(options.cwd)}</code></div>
+	<div>session <code>${escapeHtml(options.sessionId)}</code> · captured ${new Date().toISOString()}</div>
+</header>
+<div id="terminal"></div>
+<noscript><pre class="fallback">${escapeHtml(plain)}</pre></noscript>
+<script>
+const ansi = ${htmlJson(ansi)};
+const fallbackText = ${htmlJson(plain)};
+const terminalElement = document.getElementById("terminal");
+try {
+	const term = new Terminal({
+		cols: ${options.width},
+		rows: ${options.height},
+		convertEol: true,
+		fontFamily: 'Menlo, Monaco, Consolas, "Liberation Mono", monospace',
+		fontSize: 13,
+		lineHeight: 1.18,
+		scrollback: ${options.historyLines},
+		theme: {
+			background: '#0b0f14',
+			foreground: '#d8dee9',
+			cursor: '#d8dee9'
+		}
+	});
+	term.open(terminalElement);
+	term.resize(${options.width}, ${options.height});
+	term.write(ansi, () => {
+		document.body.setAttribute("data-render-ready", "true");
+	});
+} catch (error) {
+	const pre = document.createElement("pre");
+	pre.className = "fallback";
+	pre.textContent = fallbackText + "\\n\\n[xterm render failed: " + String(error) + "]";
+	terminalElement.replaceChildren(pre);
+	document.body.setAttribute("data-render-ready", "true");
+}
+</script>
+</body>
+</html>
+`;
+}
+
+export async function writeTerminalScreenshot(htmlPath, pngPath, width, height) {
+	let browser;
+	try {
+		const { chromium } = await import("playwright");
+		browser = await chromium.launch();
+		const page = await browser.newPage({
+			viewport: {
+				width: Math.max(1_200, width * 10),
+				height: Math.max(800, height * 22),
+			},
+			deviceScaleFactor: 1,
+		});
+		await page.goto(pathToFileURL(htmlPath).href);
+		await page.waitForSelector('body[data-render-ready="true"]', { timeout: 30_000 });
+		await page.locator("#terminal").screenshot({ path: pngPath });
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		throw new Error(`failed to capture PNG with Playwright: ${message}\nInstall Chromium with: npx playwright install chromium\nOr rerun with --no-screenshot and capture ${htmlPath} with agent_browser.`);
+	} finally {
+		if (browser) await browser.close();
+	}
+}