@emmaneugene/pi-cursor-sdk 0.3.7 → 0.4.0

package/src/cursor-cloud-options.ts

@@ -1,182 +0,0 @@
-import type { AgentModeOption, AgentOptions, ModelSelection } from "@cursor/sdk";
-import { isCursorCloudEnvironmentType, type CursorResolvedSdkConfig } from "./cursor-config.js";
-import {
-	normalizeCursorCloudStartingRef,
-	parseCursorCloudRepositoryUrl,
-	type CursorCloudLocalState,
-	type CursorCloudLocalStateUnknownReason,
-} from "./cursor-cloud-local-state.js";
-
-export interface CursorCloudPreflightIssue {
-	code:
-		| "cloud_ack_required"
-		| "context_handoff_required"
-		| "local_state_not_allowed"
-		| "env_forwarding_not_implemented"
-		| "cloud_environment_type_invalid"
-		| "cloud_environment_type_required"
-		| "cloud_environment_repo_conflict"
-		| "cloud_branch_repo_required"
-		| "cloud_branch_invalid"
-		| "cloud_repo_invalid";
-	message: string;
-}
-
-export interface CursorCloudPreflightResult {
-	ok: boolean;
-	issues: CursorCloudPreflightIssue[];
-}
-
-const CLOUD_REPO_URL_MESSAGE = "Cursor cloud repository must be an HTTPS repository URL without embedded credentials, query parameters, or fragments.";
-const CLOUD_STARTING_REF_MESSAGE = "Cursor cloud branch/ref must be a valid Git branch name, refs/heads/<branch>, or full commit SHA; invalid branch names and other refs/* are unsupported.";
-const CLOUD_LOCAL_STATE_REASON_LABELS: Record<CursorCloudLocalStateUnknownReason["code"], string> = {
-	bare_repo: "the repository is bare",
-	repository_detection_failed: "Git could not determine whether the working directory is a repository",
-	status_failed: "Git could not determine whether the worktree or index is clean",
-	index_failed: "Git index inspection failed",
-	hidden_index_state: "the index hides worktree changes",
-	history_probe_failed: "Git could not inspect replacement or graft history overrides",
-	history_overrides: "replacement refs or graft metadata are present",
-	head_unavailable: "local HEAD is unavailable",
-	unverified_target: "the cloud target has no locally verified tracking ref",
-	target_probe_failed: "Git failed while resolving the cloud target",
-	comparison_failed: "the local HEAD comparison failed",
-};
-
-export function buildCursorCloudAgentOptions(options: {
-	apiKey: string;
-	modelSelection: ModelSelection;
-	agentMode: AgentModeOption;
-	resolvedConfig: CursorResolvedSdkConfig;
-	name?: string;
-}): AgentOptions {
-	const { resolvedConfig } = options;
-	const environment = resolvedConfig.cloud.environment.value;
-	const environmentType = environment?.type;
-	const environmentName = environment?.name;
-	const configuredRepo = resolvedConfig.cloud.repo.value;
-	const repo = parseCursorCloudRepositoryUrl(configuredRepo);
-	if (configuredRepo && !repo) throw new Error(CLOUD_REPO_URL_MESSAGE);
-	const startingRef = normalizeCursorCloudStartingRef(resolvedConfig.cloud.branch.value);
-	if (startingRef.kind === "unsupported") throw new Error(CLOUD_STARTING_REF_MESSAGE);
-	const cloud = {
-		...(isCursorCloudEnvironmentType(environmentType)
-			? {
-					env: {
-						type: environmentType,
-						...(environmentName ? { name: environmentName } : {}),
-					},
-				}
-			: {}),
-		...(repo
-			? {
-					repos: [
-						{
-							url: repo,
-							...(startingRef.kind === "branch" || startingRef.kind === "commit" ? { startingRef: startingRef.value } : {}),
-						},
-					],
-				}
-			: {}),
-		...(resolvedConfig.cloud.directPush.value ? { workOnCurrentBranch: true } : {}),
-		...(resolvedConfig.cloud.autoCreatePR.source !== "builtin"
-			? { autoCreatePR: resolvedConfig.cloud.autoCreatePR.value }
-			: {}),
-		...(resolvedConfig.cloud.skipReviewerRequest.source !== "builtin"
-			? { skipReviewerRequest: resolvedConfig.cloud.skipReviewerRequest.value }
-			: {}),
-	};
-	return {
-		apiKey: options.apiKey,
-		model: options.modelSelection,
-		mode: options.agentMode,
-		...(options.name ? { name: options.name } : {}),
-		cloud,
-	};
-}
-
-export function preflightCursorCloudRuntime(options: {
-	resolvedConfig: CursorResolvedSdkConfig;
-	localState: CursorCloudLocalState;
-	hasPriorContext?: boolean;
-}): CursorCloudPreflightResult {
-	const { resolvedConfig } = options;
-	const issues: CursorCloudPreflightIssue[] = [];
-	if (!resolvedConfig.cloud.acknowledged.value) {
-		issues.push({
-			code: "cloud_ack_required",
-			message: "Cursor cloud runtime requires first-use acknowledgement; run /cursor-runtime cloud in an interactive session or pass --cursor-cloud-ack / PI_CURSOR_CLOUD_ACK=1.",
-		});
-	}
-	if (options.hasPriorContext && resolvedConfig.cloud.contextHandoff.value === "never") {
-		issues.push({
-			code: "context_handoff_required",
-			message: "Cursor cloud runtime needs --cursor-cloud-context=fresh or --cursor-cloud-context=bootstrap for sessions with prior pi context.",
-		});
-	}
-	if (
-		options.localState.insideGitRepo !== false &&
-		(options.localState.dirty !== false || options.localState.comparison !== "contains_head") &&
-		!resolvedConfig.cloud.allowLocalState.value
-	) {
-		const causes: string[] = [];
-		if (options.localState.dirty === true) causes.push("the worktree or index is dirty");
-		if (options.localState.dirty === "unknown") causes.push("Git could not determine whether the worktree or index is clean");
-		if (options.localState.comparison === "unpushed") causes.push("local HEAD contains unpushed commits");
-		if (options.localState.comparison === "unknown") {
-			causes.push(...options.localState.reasons
-				.filter((reason) => reason.code !== "status_failed")
-				.map((reason) => CLOUD_LOCAL_STATE_REASON_LABELS[reason.code]));
-		}
-		issues.push({
-			code: "local_state_not_allowed",
-			message: `Cursor cloud runtime cannot safely omit local state because ${causes.join("; ")}. Configure an explicit repository branch/ref with current local tracking evidence, or pass --cursor-cloud-allow-local-state only after accepting that risk.`,
-		});
-	}
-	if (resolvedConfig.cloud.envNames.value.length > 0 || resolvedConfig.cloud.envFromFiles.value) {
-		issues.push({
-			code: "env_forwarding_not_implemented",
-			message: "Cursor cloud env forwarding is not implemented; use Cursor-native environment setup such as .cursor/environment.json or dashboard-managed secrets.",
-		});
-	}
-	if (resolvedConfig.cloud.repo.value && !parseCursorCloudRepositoryUrl(resolvedConfig.cloud.repo.value)) {
-		issues.push({
-			code: "cloud_repo_invalid",
-			message: CLOUD_REPO_URL_MESSAGE,
-		});
-	}
-	if (resolvedConfig.cloud.branch.value && !resolvedConfig.cloud.repo.value) {
-		issues.push({
-			code: "cloud_branch_repo_required",
-			message: "Cursor cloud branch/ref requires --cursor-cloud-repo because the installed Cursor SDK supports startingRef only on cloud.repos entries.",
-		});
-	}
-	if (normalizeCursorCloudStartingRef(resolvedConfig.cloud.branch.value).kind === "unsupported") {
-		issues.push({ code: "cloud_branch_invalid", message: CLOUD_STARTING_REF_MESSAGE });
-	}
-	const environment = resolvedConfig.cloud.environment.value;
-	if (environment?.type && !isCursorCloudEnvironmentType(environment.type)) {
-		issues.push({
-			code: "cloud_environment_type_invalid",
-			message: `Invalid Cursor cloud environment type "${environment.type}"; expected cloud, pool, or machine.`,
-		});
-	}
-	if (environment?.name && !environment.type) {
-		issues.push({
-			code: "cloud_environment_type_required",
-			message: "Cursor cloud environment name requires --cursor-cloud-env-type=cloud|pool|machine or PI_CURSOR_CLOUD_ENV_TYPE.",
-		});
-	}
-	if (environment?.type === "cloud" && environment.name && resolvedConfig.cloud.repo.value) {
-		issues.push({
-			code: "cloud_environment_repo_conflict",
-			message: "Cursor cloud named environments cannot be combined with --cursor-cloud-repo; omit the repo or use a pool/machine environment.",
-		});
-	}
-	return { ok: issues.length === 0, issues };
-}
-
-export function formatCursorCloudPreflightError(result: CursorCloudPreflightResult): string {
-	const details = result.issues.map((issue) => `- ${issue.message}`).join("\n");
-	return `Cursor cloud runtime is not ready to start.\n${details}\nUse --cursor-runtime local or /cursor-runtime local to run with the local Cursor SDK agent.`;
-}

package/src/cursor-cloud-reporting.ts

@@ -1,267 +0,0 @@
-import type { Run, RunResult, SDKAgent, SDKArtifact, TokenUsage } from "@cursor/sdk";
-import { truncateCursorDisplayLine } from "./cursor-display-text.js";
-import { scrubSensitiveText } from "./cursor-sensitive-text.js";
-import { asRecord, getArray, getNumber, getRecord, getString } from "./cursor-record-utils.js";
-
-const DEFAULT_CURSOR_CLOUD_API_BASE_URL = "https://api.cursor.com";
-const CLOUD_REPORT_TIMEOUT_MS = 5000;
-const MAX_CLOUD_ID_DISPLAY_LENGTH = 160;
-const MAX_CLOUD_REPO_DISPLAY_LENGTH = 240;
-const MAX_CLOUD_BRANCH_DISPLAY_LENGTH = 160;
-const MAX_CLOUD_ARTIFACT_DISPLAY_LENGTH = 240;
-export const MAX_CLOUD_REPORT_BRANCHES = 5;
-export const MAX_CLOUD_REPORT_ARTIFACTS = 10;
-
-export interface CursorCloudUsageReport {
-	totalUsage?: TokenUsage;
-	runUsage?: TokenUsage;
-}
-
-export interface CursorCloudRunBranch {
-	repoUrl: string;
-	branch?: string;
-	prUrl?: string;
-}
-
-export interface CursorCloudRunReport {
-	agentId: string;
-	runId: string;
-	branches: CursorCloudRunBranch[];
-	artifacts?: SDKArtifact[];
-	usage?: CursorCloudUsageReport;
-}
-
-export interface FetchCursorCloudRawUsageOptions {
-	agentId: string;
-	runId?: string;
-	apiKey: string | undefined;
-	baseUrl?: string;
-	fetchImpl?: typeof fetch;
-	timeoutMs?: number;
-}
-
-function withTimeout<T>(promise: Promise<T>, timeoutMs = CLOUD_REPORT_TIMEOUT_MS): Promise<T | undefined> {
-	let timer: ReturnType<typeof setTimeout> | undefined;
-	const timeout = new Promise<undefined>((resolve) => {
-		timer = setTimeout(() => resolve(undefined), timeoutMs);
-		timer.unref?.();
-	});
-	return Promise.race([promise.catch(() => undefined), timeout]).finally(() => {
-		if (timer) clearTimeout(timer);
-	});
-}
-
-function fetchJsonWithAbortTimeout(
-	fetchImpl: typeof fetch,
-	url: URL,
-	init: RequestInit,
-	timeoutMs = CLOUD_REPORT_TIMEOUT_MS,
-): Promise<unknown> {
-	const controller = new AbortController();
-	let timer: ReturnType<typeof setTimeout> | undefined;
-	const request = (async () => {
-		const response = await fetchImpl(url, { ...init, signal: controller.signal });
-		if (!response.ok) return undefined;
-		return response.json();
-	})().catch(() => undefined);
-	const timeout = new Promise<undefined>((resolve) => {
-		timer = setTimeout(() => {
-			controller.abort();
-			resolve(undefined);
-		}, timeoutMs);
-		timer.unref?.();
-	});
-	return Promise.race([request, timeout]).finally(() => {
-		if (timer) clearTimeout(timer);
-	});
-}
-
-function readNonnegativeNumber(record: Record<string, unknown> | undefined, key: string): number | undefined {
-	const value = getNumber(record, key);
-	return value !== undefined && Number.isFinite(value) && value >= 0 ? value : undefined;
-}
-
-function readTokenUsage(value: unknown): TokenUsage | undefined {
-	const record = asRecord(value);
-	const inputTokens = readNonnegativeNumber(record, "inputTokens");
-	const outputTokens = readNonnegativeNumber(record, "outputTokens");
-	const cacheReadTokens = readNonnegativeNumber(record, "cacheReadTokens");
-	const cacheWriteTokens = readNonnegativeNumber(record, "cacheWriteTokens");
-	const totalTokens = readNonnegativeNumber(record, "totalTokens");
-	if (
-		inputTokens === undefined ||
-		outputTokens === undefined ||
-		cacheReadTokens === undefined ||
-		cacheWriteTokens === undefined ||
-		totalTokens === undefined
-	) return undefined;
-	const reasoningTokens = readNonnegativeNumber(record, "reasoningTokens");
-	return {
-		inputTokens,
-		outputTokens,
-		cacheReadTokens,
-		cacheWriteTokens,
-		totalTokens,
-		...(reasoningTokens === undefined ? {} : { reasoningTokens }),
-	};
-}
-
-function readNonemptyString(record: Record<string, unknown> | undefined, key: string): string | undefined {
-	const value = getString(record, key);
-	return value && truncateCursorDisplayLine(value) ? value : undefined;
-}
-
-function normalizeBranches(value: unknown): CursorCloudRunBranch[] {
-	if (!Array.isArray(value)) return [];
-	return value.flatMap((item) => {
-		const record = asRecord(item);
-		const repoUrl = readNonemptyString(record, "repoUrl");
-		if (!repoUrl) return [];
-		const branch = readNonemptyString(record, "branch");
-		const prUrl = readNonemptyString(record, "prUrl");
-		return branch || prUrl ? [{ repoUrl, ...(branch ? { branch } : {}), ...(prUrl ? { prUrl } : {}) }] : [];
-	});
-}
-
-function normalizeArtifacts(value: unknown): SDKArtifact[] | undefined {
-	if (value === undefined) return undefined;
-	if (!Array.isArray(value)) return undefined;
-	return value.flatMap((item) => {
-		const record = asRecord(item);
-		const path = readNonemptyString(record, "path");
-		const sizeBytes = readNonnegativeNumber(record, "sizeBytes");
-		const updatedAt = readNonemptyString(record, "updatedAt");
-		return path && sizeBytes !== undefined && updatedAt ? [{ path, sizeBytes, updatedAt }] : [];
-	});
-}
-
-function normalizeUsage(value: unknown): CursorCloudUsageReport | undefined {
-	const record = asRecord(value);
-	const totalUsage = readTokenUsage(getRecord(record, "totalUsage"));
-	const runUsage = readTokenUsage(getRecord(record, "runUsage"));
-	return totalUsage || runUsage ? { ...(totalUsage ? { totalUsage } : {}), ...(runUsage ? { runUsage } : {}) } : undefined;
-}
-
-export async function fetchCursorCloudRawUsage(
-	options: FetchCursorCloudRawUsageOptions,
-): Promise<CursorCloudUsageReport | undefined> {
-	if (!options.apiKey || typeof options.fetchImpl !== "function" && typeof fetch !== "function") return undefined;
-	try {
-		const baseUrl = options.baseUrl ?? DEFAULT_CURSOR_CLOUD_API_BASE_URL;
-		const url = new URL(`/v1/agents/${encodeURIComponent(options.agentId)}/usage`, baseUrl);
-		if (options.runId) url.searchParams.set("runId", options.runId);
-		const fetchImpl = options.fetchImpl ?? fetch;
-		const body = asRecord(await fetchJsonWithAbortTimeout(fetchImpl, url, {
-			headers: {
-				Authorization: `Bearer ${options.apiKey}`,
-				"x-cursor-client-type": "sdk",
-			},
-		}, options.timeoutMs));
-		const runs = getArray(body, "runs") ?? [];
-		const matchingRun = options.runId
-			? runs.map(asRecord).find((run) => getString(run, "id") === options.runId)
-			: undefined;
-		return normalizeUsage({
-			totalUsage: getRecord(body, "totalUsage"),
-			runUsage: getRecord(matchingRun, "usage"),
-		});
-	} catch {
-		return undefined;
-	}
-}
-
-function mapCursorSdkAgentUsageToCloudReport(value: unknown, runId?: string): CursorCloudUsageReport | undefined {
-	const record = asRecord(value);
-	const runs = (getArray(record, "runs") ?? []).map(asRecord);
-	const matchingRun = runId ? runs.find((run) => getString(run, "runId") === runId) : undefined;
-	return normalizeUsage({
-		totalUsage: getRecord(record, "usage"),
-		runUsage: getRecord(matchingRun, "usage"),
-	});
-}
-
-export async function collectCursorCloudRunReport(options: {
-	agent: SDKAgent;
-	run: Run;
-	waitResult: RunResult;
-	apiKey: string | undefined;
-	agentUsage?: unknown;
-}): Promise<CursorCloudRunReport> {
-	const listArtifacts = options.agent.listArtifacts;
-	const sdkUsage =
-		options.agentUsage !== undefined
-			? mapCursorSdkAgentUsageToCloudReport(options.agentUsage, options.run.id)
-			: typeof options.agent.getUsage === "function"
-				? mapCursorSdkAgentUsageToCloudReport(
-					await withTimeout(Promise.resolve(options.agent.getUsage({ runId: options.run.id }))),
-					options.run.id,
-				)
-				: undefined;
-	const [artifactResult, restUsage] = await Promise.all([
-		typeof listArtifacts === "function" ? withTimeout(listArtifacts.call(options.agent)) : undefined,
-		sdkUsage ? undefined : fetchCursorCloudRawUsage({ agentId: options.run.agentId, runId: options.run.id, apiKey: options.apiKey }),
-	]);
-	const usage = sdkUsage ?? restUsage;
-	const waitBranches = getArray(getRecord(asRecord(options.waitResult), "git"), "branches");
-	const runBranches = getArray(getRecord(asRecord(options.run), "git"), "branches");
-	return {
-		agentId: options.run.agentId,
-		runId: options.run.id,
-		branches: normalizeBranches(waitBranches ?? runBranches),
-		artifacts: normalizeArtifacts(artifactResult),
-		usage: normalizeUsage(usage),
-	};
-}
-
-function formatTokenUsage(usage: TokenUsage): string {
-	const parts = [
-		`input ${usage.inputTokens.toLocaleString("en-US")}`,
-		`output ${usage.outputTokens.toLocaleString("en-US")}`,
-		`cache read ${usage.cacheReadTokens.toLocaleString("en-US")}`,
-		`cache write ${usage.cacheWriteTokens.toLocaleString("en-US")}`,
-		`total ${usage.totalTokens.toLocaleString("en-US")}`,
-	];
-	if (usage.reasoningTokens !== undefined) parts.splice(2, 0, `reasoning ${usage.reasoningTokens.toLocaleString("en-US")}`);
-	return parts.join(", ");
-}
-
-function remoteDisplayString(value: unknown, maxLength: number, apiKey: string | undefined): string {
-	return typeof value === "string" ? truncateCursorDisplayLine(scrubSensitiveText(value, apiKey), maxLength) : "";
-}
-
-function formatBranchLine(branch: CursorCloudRunBranch, apiKey: string | undefined): string[] {
-	const lines: string[] = [];
-	const branchName = remoteDisplayString(branch.branch, MAX_CLOUD_BRANCH_DISPLAY_LENGTH, apiKey);
-	const repoUrl = remoteDisplayString(branch.repoUrl, MAX_CLOUD_REPO_DISPLAY_LENGTH, apiKey);
-	const prUrl = remoteDisplayString(branch.prUrl, MAX_CLOUD_REPO_DISPLAY_LENGTH, apiKey);
-	if (branchName) lines.push(`- branch: ${branchName}${repoUrl ? ` (${repoUrl})` : ""}`);
-	if (prUrl) lines.push(`- PR: ${prUrl}`);
-	return lines;
-}
-
-export function formatCursorCloudRunReport(report: CursorCloudRunReport, options: { apiKey?: string } = {}): string {
-	const agentId = remoteDisplayString(report.agentId, MAX_CLOUD_ID_DISPLAY_LENGTH, options.apiKey) || "unknown";
-	const runId = remoteDisplayString(report.runId, MAX_CLOUD_ID_DISPLAY_LENGTH, options.apiKey) || "unknown";
-	const branches = normalizeBranches(report.branches);
-	const artifacts = normalizeArtifacts(report.artifacts);
-	const lines = ["Cursor cloud run:", `- agent: ${agentId}`, `- run: ${runId}`];
-	for (const branch of branches.slice(0, MAX_CLOUD_REPORT_BRANCHES)) lines.push(...formatBranchLine(branch, options.apiKey));
-	if (branches.length > MAX_CLOUD_REPORT_BRANCHES) lines.push(`- branches: +${branches.length - MAX_CLOUD_REPORT_BRANCHES} more`);
-	if (artifacts) {
-		if (artifacts.length === 0) {
-			lines.push("- artifacts: none");
-		} else {
-			lines.push("- artifacts:");
-			for (const artifact of artifacts.slice(0, MAX_CLOUD_REPORT_ARTIFACTS)) {
-				const path = remoteDisplayString(artifact.path, MAX_CLOUD_ARTIFACT_DISPLAY_LENGTH, options.apiKey);
-				const updatedAt = remoteDisplayString(artifact.updatedAt, MAX_CLOUD_ARTIFACT_DISPLAY_LENGTH, options.apiKey);
-				lines.push(`  - ${path} (${artifact.sizeBytes.toLocaleString("en-US")} bytes, updated ${updatedAt})`);
-			}
-			if (artifacts.length > MAX_CLOUD_REPORT_ARTIFACTS) lines.push(`  - +${artifacts.length - MAX_CLOUD_REPORT_ARTIFACTS} more`);
-		}
-	}
-	const normalizedUsage = normalizeUsage(report.usage);
-	const usage = normalizedUsage?.runUsage ?? normalizedUsage?.totalUsage;
-	if (usage) lines.push(`- raw usage (display only): ${formatTokenUsage(usage)}`);
-	return scrubSensitiveText(`${lines.join("\n")}\n`, options.apiKey);
-}

package/src/cursor-ripgrep-path.ts

@@ -1,32 +0,0 @@
-import { accessSync, constants } from "node:fs";
-import { createRequire } from "node:module";
-import { dirname, isAbsolute, join } from "node:path";
-
-const RIPGREP_ENV = "CURSOR_RIPGREP_PATH";
-
-export function resolveBundledCursorRipgrepPath(
-	fromModuleUrl: string | URL = import.meta.url,
-): string | undefined {
-	try {
-		const require = createRequire(fromModuleUrl);
-		const platformPackage = `@cursor/sdk-${process.platform}-${process.arch}`;
-		const sdkEntry = require.resolve("@cursor/sdk");
-		const packageDirectory = dirname(
-			require.resolve(`${platformPackage}/package.json`, { paths: [dirname(sdkEntry)] }),
-		);
-		const ripgrepPath = join(packageDirectory, "bin", process.platform === "win32" ? "rg.exe" : "rg");
-		accessSync(ripgrepPath, constants.X_OK);
-		return ripgrepPath;
-	} catch {
-		return undefined;
-	}
-}
-
-export function ensureCursorRipgrepPath(): string | undefined {
-	const configuredPath = process.env[RIPGREP_ENV];
-	if (configuredPath && isAbsolute(configuredPath)) return configuredPath;
-
-	const bundledPath = resolveBundledCursorRipgrepPath();
-	if (bundledPath) process.env[RIPGREP_ENV] = bundledPath;
-	return bundledPath;
-}