@cursorpool-dev/cli 0.5.6

package/src/serviceProcess.ts

@@ -0,0 +1,188 @@
+import { spawn } from 'node:child_process';
+import { mkdir, open, rm } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { createRequire } from 'node:module';
+import { readRuntimeInfo, resolveRuntimeFile, type RuntimeInfo } from '@cursor-pool/service';
+
+export type StartDetachedServiceOptions = {
+  runtimeFile: string;
+  logFile: string;
+  apiBaseUrl?: string;
+  configFile?: string;
+  serviceEntry?: string;
+  command?: string;
+  startupTimeoutMs?: number;
+};
+
+const require = createRequire(import.meta.url);
+const DEFAULT_SERVICE_ENTRY = require.resolve('@cursor-pool/service/entry');
+const TSX_ESM_LOADER = require.resolve('tsx/esm');
+function resolveTildePath(path: string) {
+  if (path.startsWith('~/')) {
+    return join(homedir(), path.slice(2));
+  }
+  return path;
+}
+
+async function fetchRuntimeHealth(runtime: RuntimeInfo | null) {
+  if (!runtime) {
+    return false;
+  }
+
+  try {
+    const response = await fetch(`http://${runtime.host}:${runtime.port}/health`);
+    const health = (await response.json()) as { ok?: unknown; runtimeId?: unknown };
+    return response.ok && health.ok === true && health.runtimeId === runtime.runtimeId;
+  } catch {
+    return false;
+  }
+}
+
+function delay(ms: number) {
+  return new Promise((resolveDelay) => setTimeout(resolveDelay, ms));
+}
+
+async function stopDetachedProcessGroup(pid: number | undefined) {
+  if (!pid) {
+    return;
+  }
+
+  try {
+    process.kill(-pid, 'SIGTERM');
+  } catch {
+    return;
+  }
+
+  for (let attempt = 0; attempt < 10; attempt += 1) {
+    await delay(50);
+    try {
+      process.kill(-pid, 0);
+    } catch {
+      return;
+    }
+  }
+
+  try {
+    process.kill(-pid, 'SIGKILL');
+  } catch {
+    return;
+  }
+}
+
+export async function waitForRuntimeHealth(
+  runtimeFile: string,
+  timeoutMs = 5000,
+) {
+  const resolvedRuntimeFile = resolveRuntimeFile(runtimeFile);
+  const startedAt = Date.now();
+  while (Date.now() - startedAt < timeoutMs) {
+    const runtime = await readRuntimeInfo({ runtimeFile: resolvedRuntimeFile });
+    if (await fetchRuntimeHealth(runtime)) {
+      return true;
+    }
+    await new Promise((resolveDelay) => setTimeout(resolveDelay, 50));
+  }
+  return false;
+}
+
+export async function startDetachedService(
+  options: StartDetachedServiceOptions,
+): Promise<RuntimeInfo> {
+  const runtimeFile = resolveRuntimeFile(options.runtimeFile);
+  const logFile = resolveTildePath(options.logFile);
+  const existingRuntime = await readRuntimeInfo({ runtimeFile });
+  if (await fetchRuntimeHealth(existingRuntime)) {
+    return existingRuntime!;
+  }
+  await rm(runtimeFile, { force: true });
+  await mkdir(dirname(logFile), { recursive: true });
+  const logHandle = await open(logFile, 'a');
+  const serviceEntry = options.serviceEntry ?? DEFAULT_SERVICE_ENTRY;
+  const command = options.command ?? process.execPath;
+  const args = ['--import', TSX_ESM_LOADER, serviceEntry, '--runtime-file', runtimeFile];
+  if (options.configFile) {
+    args.push('--config-file', options.configFile);
+  }
+  const child = spawn(
+    command,
+    args,
+    {
+      cwd: process.cwd(),
+      env: {
+        ...process.env,
+        ...(options.apiBaseUrl ? { CURSOR_POOL_API_BASE_URL: options.apiBaseUrl } : {}),
+      },
+      detached: true,
+      stdio: ['ignore', logHandle.fd, logHandle.fd],
+    },
+  );
+  let exited = false;
+  let startupError: Error | undefined;
+  child.once('exit', () => {
+    exited = true;
+  });
+  child.once('error', (error) => {
+    startupError = new Error(`Failed to start detached service process: ${(error as Error).message}`);
+  });
+
+  child.unref();
+  await logHandle.close();
+
+  let healthy = false;
+  try {
+    const startedAt = Date.now();
+    const timeoutMs = options.startupTimeoutMs ?? 5000;
+    while (Date.now() - startedAt < timeoutMs) {
+      if (startupError) {
+        throw startupError;
+      }
+
+      const runtime = await readRuntimeInfo({ runtimeFile });
+      if (await fetchRuntimeHealth(runtime)) {
+        healthy = true;
+        break;
+      }
+      await delay(50);
+    }
+
+    if (startupError) {
+      throw startupError;
+    }
+  } catch (error) {
+    if (!exited) {
+      await stopDetachedProcessGroup(child.pid);
+    }
+    throw error;
+  }
+
+  if (!healthy) {
+    if (!exited) {
+      await stopDetachedProcessGroup(child.pid);
+    }
+    throw new Error('Detached service failed to become healthy');
+  }
+
+  const runtime = await readRuntimeInfo({ runtimeFile });
+  if (!runtime) {
+    throw new Error('Detached service did not write runtime file');
+  }
+  return runtime;
+}
+
+export async function stopRuntimeService(runtimeFile: string) {
+  const resolvedRuntimeFile = resolveRuntimeFile(runtimeFile);
+  const runtime = await readRuntimeInfo({ runtimeFile: resolvedRuntimeFile });
+  if (!(await fetchRuntimeHealth(runtime))) {
+    return false;
+  }
+
+  try {
+    const response = await fetch(`http://${runtime.host}:${runtime.port}/shutdown`, {
+      method: 'POST',
+    });
+    return response.ok;
+  } catch {
+    return false;
+  }
+}

package/src/status.ts

@@ -0,0 +1,241 @@
+import { readRuntimeInfo, resolveRuntimeFile } from '@cursor-pool/service';
+import { cachedPlatformStatus } from '@cursor-pool/service/platformSession';
+import type { CompatibilityManifestEntry } from '@cursor-pool/shared/manifest';
+import { detectEnvironment, type DetectEnvironmentOptions } from './environment';
+import { findCursor, type FindCursorOptions } from './cursor';
+import { loadCompatEntries, resolveCompatEntry, type CompatManifestFetchResponse } from './compat';
+import { getExtensionState } from './extensionBundle';
+import { getLinkedExtensionState, linkedExtensionPathForDir } from './extensionLink';
+import {
+  assertDisposableCursorAppPath,
+  readTrialRecord,
+  type TrialRecordOptions,
+} from './trial';
+import { resolveCursorTarget, type CursorTargetOptions } from './target';
+import {
+  isInstallRecordStale,
+  readInstallRecord,
+  type InstallRecord,
+  type InstallRecordOptions,
+} from './installRecord';
+import { formatPlatformStatus } from './platform';
+import { whoami } from './platform';
+import { formatCursorPatchSetState, readCursorPatchSetState } from './patchSet';
+
+export type StatusOptions = FindCursorOptions &
+  DetectEnvironmentOptions &
+  CursorTargetOptions &
+  TrialRecordOptions &
+  InstallRecordOptions & {
+    runtimeFile?: string;
+    platformSessionFile?: string;
+    extensionInstallPath?: string;
+    cursorExtensionsDir?: string;
+    compatEntries?: CompatibilityManifestEntry[];
+    apiBaseUrl?: string;
+    compatManifestUrl?: string;
+    fetchCompatManifest?: (url: string) => Promise<CompatManifestFetchResponse>;
+  };
+
+type LatestTakeoverResponse = {
+  ok?: unknown;
+  takeover?: null | {
+    state?: unknown;
+    requestId?: unknown;
+    source?: unknown;
+    model?: unknown;
+    content?: unknown;
+    reason?: unknown;
+  };
+};
+
+const MAX_CANARY_FIELD_LENGTH = 256;
+
+function isSafeCanaryString(value: unknown): value is string {
+  return (
+    typeof value === 'string' &&
+    value.length > 0 &&
+    value.length <= MAX_CANARY_FIELD_LENGTH &&
+    !/[\u0000-\u001f\u007f]/.test(value)
+  );
+}
+
+function isSafeCanaryToken(value: unknown): value is string {
+  return isSafeCanaryString(value) && !/[\s=]/.test(value);
+}
+
+function isSecretLike(value: string) {
+  return (
+    /^sk-/i.test(value) ||
+    /apikey|apiKey|secret|token|authorization|bearer|cursorAuth/i.test(value)
+  );
+}
+
+function formatCanarySource(value: unknown) {
+  return value === 'cursor-agent-exec' || value === 'cursor-always-local' ? value : 'unknown';
+}
+
+function formatCanaryModel(value: unknown) {
+  if (!isSafeCanaryToken(value) || isSecretLike(value)) {
+    return 'unknown';
+  }
+
+  return value;
+}
+
+async function isRuntimeHealthy(runtime: Awaited<ReturnType<typeof readRuntimeInfo>>) {
+  if (!runtime) {
+    return false;
+  }
+
+  try {
+    const response = await fetch(`http://${runtime.host}:${runtime.port}/health`);
+    const health = (await response.json()) as { ok?: unknown; runtimeId?: unknown };
+    return response.ok && health.ok === true && health.runtimeId === runtime.runtimeId;
+  } catch {
+    return false;
+  }
+}
+
+function formatTakeoverReason(value: unknown) {
+  return isSafeCanaryToken(value) ? value : 'unknown';
+}
+
+async function getTakeoverStatus(
+  runtime: Awaited<ReturnType<typeof readRuntimeInfo>>,
+  serviceRunning: boolean,
+) {
+  if (!runtime || !serviceRunning) {
+    return 'takeover: unavailable';
+  }
+
+  try {
+    const response = await fetch(`http://${runtime.host}:${runtime.port}/agent/takeover/latest`);
+    const latest = (await response.json()) as LatestTakeoverResponse;
+
+    if (!response.ok || latest.ok !== true) {
+      return 'takeover: unavailable';
+    }
+
+    if (latest.takeover === null) {
+      return 'takeover: missing';
+    }
+
+    if (latest.takeover?.state === 'answered') {
+      return [
+        'takeover: answered',
+        `requestId=${isSafeCanaryToken(latest.takeover.requestId) ? latest.takeover.requestId : 'unknown'}`,
+        `source=${formatCanarySource(latest.takeover.source)}`,
+        `model=${formatCanaryModel(latest.takeover.model)}`,
+        `content=${typeof latest.takeover.content === 'string' && latest.takeover.content.length > 0 ? 'present' : 'missing'}`,
+      ].join(' ');
+    }
+
+    if (latest.takeover?.state === 'rejected') {
+      return [
+        'takeover: rejected',
+        `requestId=${isSafeCanaryToken(latest.takeover.requestId) ? latest.takeover.requestId : 'unknown'}`,
+        `reason=${formatTakeoverReason(latest.takeover.reason)}`,
+      ].join(' ');
+    }
+
+    return 'takeover: unavailable';
+  } catch {
+    return 'takeover: unavailable';
+  }
+}
+
+export async function status(options: StatusOptions = {}) {
+  const target = resolveCursorTarget(options);
+  const appPath =
+    target.mode === 'disposable' ? assertDisposableCursorAppPath(target.appPath) : target.appPath;
+  const environment = detectEnvironment(options);
+  const cursor = await findCursor({ ...options, appPath });
+  const compatEntries = await loadCompatEntries({
+    compatEntries: options.compatEntries,
+    apiBaseUrl: options.apiBaseUrl,
+    compatManifestUrl: options.compatManifestUrl,
+    fetchManifest: options.fetchCompatManifest,
+  });
+  const compat = resolveCompatEntry(cursor, environment, { entries: compatEntries });
+  const installRecord =
+    target.mode === 'real'
+      ? await readInstallRecord({ installRecordFile: options.installRecordFile })
+      : null;
+  const trialRecord =
+    target.mode === 'disposable'
+      ? await readTrialRecord(cursor.appPath, {
+          trialRecordDir: options.trialRecordDir,
+        })
+      : null;
+  const runtimeFile =
+    target.mode === 'real'
+      ? options.runtimeFile ?? installRecord?.runtimeFile
+      : options.runtimeFile ?? trialRecord?.runtimeFile;
+  const extensionInstallPath =
+    target.mode === 'real'
+      ? installRecord?.extensionInstallPath ?? options.extensionInstallPath
+      : options.extensionInstallPath ?? trialRecord?.extensionInstallPath;
+  const linkedPath =
+    target.mode === 'real'
+      ? installRecord?.extensionLinkedPath ??
+        (options.cursorExtensionsDir
+          ? linkedExtensionPathForDir(options.cursorExtensionsDir)
+          : undefined)
+      : options.cursorExtensionsDir
+        ? linkedExtensionPathForDir(options.cursorExtensionsDir)
+        : trialRecord?.extensionLinkedPath;
+  const runtime = await readRuntimeInfo({ runtimeFile });
+  const patchSetState = await readCursorPatchSetState(cursor.appPath, {
+    agentExecTargetRelativePath: compat.targetRelativePath,
+    platform: environment.platform,
+  });
+  const serviceRunning = await isRuntimeHealthy(runtime);
+  const takeoverStatus = await getTakeoverStatus(runtime, serviceRunning);
+  const platformSummary = serviceRunning
+    ? await whoami({ runtimeFile })
+    : formatPlatformStatus(await cachedPlatformStatus({ sessionFile: options.platformSessionFile }));
+  const sourceExtensionState = await getExtensionState(extensionInstallPath);
+  const linkedExtensionState = await getLinkedExtensionState(linkedPath);
+  const extensionState =
+    linkedExtensionState === 'linked' ? 'linked' : sourceExtensionState;
+  const actualInstallRecord: InstallRecord | null =
+    target.mode === 'real' && installRecord
+      ? {
+          ...installRecord,
+          mode: 'real',
+          appPath: cursor.appPath,
+          cursorVersion: cursor.version,
+          cursorCommit: cursor.commit,
+          targetRelativePath: compat.targetRelativePath,
+          originalSha256: installRecord.originalSha256,
+          compatSupportStatus: compat.supportStatus,
+          runtimeFile: runtimeFile ?? installRecord.runtimeFile,
+          backupDir: installRecord.backupDir,
+          extensionInstallPath: extensionInstallPath ?? installRecord.extensionInstallPath,
+          extensionLinkedPath: linkedPath,
+          extensionState,
+        }
+      : null;
+  const installRecordState = installRecord
+    ? isInstallRecordStale(installRecord, actualInstallRecord)
+      ? 'stale'
+      : 'recorded'
+    : 'missing';
+
+  return [
+    `Cursor ${cursor.version} (${cursor.commit})`,
+    `mode: ${target.mode}`,
+    `app: ${cursor.appPath}`,
+    `compat: ${compat.supportStatus}`,
+    `patch: ${formatCursorPatchSetState(patchSetState)}`,
+    `service: ${serviceRunning ? 'running' : 'stopped'}`,
+    `extension: ${extensionState}`,
+    `runtime: ${resolveRuntimeFile(runtimeFile)}`,
+    platformSummary,
+    target.mode === 'real'
+      ? `install-record: ${installRecordState}`
+      : `trial: ${trialRecord ? 'recorded' : 'missing'}`,
+    takeoverStatus,
+  ].join('\n');
+}

package/src/target.ts

@@ -0,0 +1,37 @@
+import { defaultCursorAppPath } from './cursor';
+import { assertDisposableCursorAppPath } from './trial';
+
+export type CursorTargetOptions = {
+  appPath?: string;
+  realAppPath?: string;
+  defaultRealAppPath?: string;
+  platform?: NodeJS.Platform;
+};
+
+export type CursorTarget =
+  | {
+      mode: 'disposable';
+      appPath: string;
+      requiresConfirmation: false;
+    }
+  | {
+      mode: 'real';
+      appPath: string;
+      requiresConfirmation: true;
+    };
+
+export function resolveCursorTarget(options: CursorTargetOptions = {}): CursorTarget {
+  if (options.appPath) {
+    return {
+      mode: 'disposable',
+      appPath: assertDisposableCursorAppPath(options.appPath, { platform: options.platform }),
+      requiresConfirmation: false,
+    };
+  }
+
+  return {
+    mode: 'real',
+    appPath: options.realAppPath ?? options.defaultRealAppPath ?? defaultCursorAppPath(options),
+    requiresConfirmation: true,
+  };
+}

package/src/trial.ts

@@ -0,0 +1,133 @@
+import { createHash } from 'node:crypto';
+import { mkdir, readFile, rm, writeFile } from 'node:fs/promises';
+import { realpathSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join, normalize } from 'node:path';
+import { DEFAULT_MACOS_CURSOR_APP_PATH } from './cursor';
+
+export type ExtensionState = 'bundled' | 'linked' | 'manual-step-required' | 'missing';
+
+export type TrialRecord = {
+  trialId: string;
+  appPath: string;
+  cursorVersion: string;
+  cursorCommit: string;
+  targetRelativePath: string;
+  originalSha256: string;
+  compatSupportStatus: 'supported' | 'canary' | 'warning' | 'blocked' | 'unknown';
+  runtimeFile: string;
+  backupDir: string;
+  extensionInstallPath: string;
+  extensionLinkedPath?: string;
+  extensionState: ExtensionState;
+  createdAt: string;
+  updatedAt: string;
+};
+
+export type TrialRecordOptions = {
+  trialRecordDir?: string;
+};
+
+export type DisposableCursorAppPathOptions = {
+  platform?: NodeJS.Platform;
+};
+
+export const DEFAULT_TRIAL_RECORD_DIR = '~/.cursor-pool/trials';
+
+function resolveHomePath(path: string) {
+  return path.startsWith('~/') ? join(homedir(), path.slice(2)) : path;
+}
+
+function normalizeAppPath(path: string) {
+  return normalize(path).replace(/\/+$/, '');
+}
+
+function isRealCursorAppPath(path: string) {
+  return normalizeAppPath(path).toLowerCase() === DEFAULT_MACOS_CURSOR_APP_PATH.toLowerCase();
+}
+
+function resolveExistingRealPathSync(path: string) {
+  try {
+    return realpathSync(path);
+  } catch {
+    return path;
+  }
+}
+
+export function resolveTrialRecordDir(trialRecordDir = DEFAULT_TRIAL_RECORD_DIR) {
+  return resolveHomePath(trialRecordDir);
+}
+
+export function assertDisposableCursorAppPath(
+  appPath: string | undefined,
+  options: DisposableCursorAppPathOptions = {},
+) {
+  if (!appPath) {
+    throw new Error('MVP-0.1 requires --app-path to point at a disposable Cursor.app copy');
+  }
+
+  const normalized = normalizeAppPath(appPath);
+  const realPath = normalizeAppPath(resolveExistingRealPathSync(normalized));
+  if (isRealCursorAppPath(normalized) || isRealCursorAppPath(realPath)) {
+    throw new Error(
+      'Refusing to install into real Cursor app. Copy /Applications/Cursor.app to a disposable .app path and pass --app-path.',
+    );
+  }
+
+  const platform = options.platform ?? process.platform;
+  if (platform === 'darwin' && !normalized.endsWith('.app')) {
+    throw new Error(`MVP-0.1 trial install path must point at a .app bundle: ${appPath}`);
+  }
+
+  return normalized;
+}
+
+export function trialIdForAppPath(appPath: string) {
+  return createHash('sha256').update(normalize(appPath)).digest('hex').slice(0, 16);
+}
+
+export function trialRecordPathForAppPath(
+  appPath: string,
+  options: TrialRecordOptions = {},
+) {
+  return join(resolveTrialRecordDir(options.trialRecordDir), `${trialIdForAppPath(appPath)}.json`);
+}
+
+export async function writeTrialRecord(
+  record: TrialRecord,
+  options: TrialRecordOptions = {},
+) {
+  const expectedTrialId = trialIdForAppPath(record.appPath);
+  if (record.trialId !== expectedTrialId) {
+    throw new Error(
+      `Trial record id does not match app path. Expected ${expectedTrialId} for ${record.appPath}.`,
+    );
+  }
+
+  const recordPath = trialRecordPathForAppPath(record.appPath, options);
+  await mkdir(dirname(recordPath), { recursive: true });
+  await writeFile(recordPath, `${JSON.stringify(record, null, 2)}\n`, 'utf8');
+}
+
+export async function readTrialRecord(
+  appPath: string,
+  options: TrialRecordOptions = {},
+): Promise<TrialRecord | null> {
+  try {
+    return JSON.parse(
+      await readFile(trialRecordPathForAppPath(appPath, options), 'utf8'),
+    ) as TrialRecord;
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') {
+      return null;
+    }
+    throw error;
+  }
+}
+
+export async function deleteTrialRecord(
+  appPath: string,
+  options: TrialRecordOptions = {},
+) {
+  await rm(trialRecordPathForAppPath(appPath, options), { force: true });
+}