@cursorpool-dev/cli 0.5.6

package/src/installRecord.ts

@@ -0,0 +1,105 @@
+import { createHash } from 'node:crypto';
+import { mkdir, readFile, rm, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { dirname, join, normalize } from 'node:path';
+import type { CompatibilityManifestEntry } from '@cursor-pool/shared/manifest';
+import type { ExtensionState } from './trial';
+
+export type InstallMode = 'real' | 'disposable';
+
+export type InstallRecord = {
+  installId: string;
+  mode: InstallMode;
+  appPath: string;
+  cursorVersion: string;
+  cursorCommit: string;
+  targetRelativePath: string;
+  originalSha256: string;
+  compatSupportStatus: CompatibilityManifestEntry['supportStatus'];
+  runtimeFile: string;
+  backupDir: string;
+  extensionInstallPath: string;
+  extensionLinkedPath?: string;
+  extensionState: ExtensionState;
+  cliVersion: string;
+  extensionVersion: string;
+  serviceVersion: string;
+  lastOperation: 'install' | 'repair' | 'restore' | 'uninstall';
+  lastOperationStatus: 'ok' | 'failed' | 'rolled-back';
+  createdAt: string;
+  updatedAt: string;
+};
+
+export type InstallRecordOptions = {
+  installRecordFile?: string;
+};
+
+export const DEFAULT_INSTALL_RECORD_FILE = '~/.cursor-pool/install.json';
+
+function resolveHomePath(path: string) {
+  return path.startsWith('~/') ? join(homedir(), path.slice(2)) : path;
+}
+
+export function installRecordPath(options: InstallRecordOptions = {}) {
+  return resolveHomePath(options.installRecordFile ?? DEFAULT_INSTALL_RECORD_FILE);
+}
+
+export function installIdForAppPath(appPath: string) {
+  return createHash('sha256').update(normalize(appPath)).digest('hex').slice(0, 16);
+}
+
+export async function writeInstallRecord(
+  record: InstallRecord,
+  options: InstallRecordOptions = {},
+) {
+  const expectedInstallId = installIdForAppPath(record.appPath);
+  if (record.installId !== expectedInstallId) {
+    throw new Error(
+      `Install record id does not match app path. Expected ${expectedInstallId} for ${record.appPath}.`,
+    );
+  }
+
+  const recordPath = installRecordPath(options);
+  await mkdir(dirname(recordPath), { recursive: true });
+  await writeFile(recordPath, `${JSON.stringify(record, null, 2)}\n`, 'utf8');
+}
+
+export async function readInstallRecord(
+  options: InstallRecordOptions = {},
+): Promise<InstallRecord | null> {
+  try {
+    return JSON.parse(await readFile(installRecordPath(options), 'utf8')) as InstallRecord;
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') {
+      return null;
+    }
+    throw error;
+  }
+}
+
+export async function deleteInstallRecord(options: InstallRecordOptions = {}) {
+  await rm(installRecordPath(options), { force: true });
+}
+
+export function isInstallRecordStale(record: InstallRecord | null, actual: InstallRecord | null) {
+  if (!record || !actual) {
+    return Boolean(record) !== Boolean(actual);
+  }
+
+  const trackedFields: Array<keyof InstallRecord> = [
+    'mode',
+    'appPath',
+    'cursorVersion',
+    'cursorCommit',
+    'targetRelativePath',
+    'originalSha256',
+    'compatSupportStatus',
+    'runtimeFile',
+    'backupDir',
+    'extensionInstallPath',
+    'extensionLinkedPath',
+    'extensionState',
+  ];
+
+  return trackedFields.some((field) => record[field] !== actual[field]);
+}

package/src/launch.ts

@@ -0,0 +1,182 @@
+import { execFile } from 'node:child_process';
+import { homedir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { promisify } from 'node:util';
+import { assertDisposableCursorAppPath } from './trial';
+
+const execFileAsync = promisify(execFile);
+
+export type LaunchOptions = {
+  appPath?: string;
+  userDataDir?: string;
+  cursorExtensionsDir?: string;
+};
+
+export type LaunchStatusOptions = LaunchOptions & {
+  psOutput?: string;
+  execFile?: typeof execFileAsync;
+};
+
+function expandHome(path: string) {
+  if (path === '~') {
+    return homedir();
+  }
+  if (path.startsWith('~/')) {
+    return join(homedir(), path.slice(2));
+  }
+  return path;
+}
+
+function quoteShell(value: string) {
+  return JSON.stringify(value);
+}
+
+function requirePath(value: string | undefined, flag: string) {
+  if (!value) {
+    throw new Error(`Missing required ${flag}`);
+  }
+  return resolve(expandHome(value));
+}
+
+export function buildLaunchCommand(options: {
+  appPath: string;
+  userDataDir: string;
+  cursorExtensionsDir: string;
+}) {
+  const executable = join(options.appPath, 'Contents/MacOS/Cursor');
+  return [
+    `${quoteShell(executable)} \\`,
+    `  --user-data-dir ${quoteShell(options.userDataDir)} \\`,
+    `  --extensions-dir ${quoteShell(options.cursorExtensionsDir)} \\`,
+    '  --new-window',
+  ].join('\n');
+}
+
+export async function launchCommand(options: LaunchOptions = {}) {
+  const appPath = assertDisposableCursorAppPath(options.appPath);
+  const userDataDir = requirePath(options.userDataDir, '--user-data-dir');
+  const cursorExtensionsDir = requirePath(
+    options.cursorExtensionsDir,
+    '--cursor-extensions-dir',
+  );
+
+  return buildLaunchCommand({ appPath, userDataDir, cursorExtensionsDir });
+}
+
+type LaunchInspectionInput = {
+  psOutput: string;
+  appPath: string;
+  userDataDir: string;
+  cursorExtensionsDir: string;
+  homeDir?: string;
+};
+
+export type LaunchInspection = {
+  launch: 'running' | 'not-running';
+  app: 'matched' | 'missing';
+  userData: 'isolated' | 'real-cursor' | 'unknown';
+  extensions: 'isolated' | 'unknown';
+  realUserData: 'present' | 'absent';
+  realExtensions: 'present' | 'absent';
+};
+
+function normalizePath(path: string) {
+  return resolve(expandHome(path));
+}
+
+function realUserDataDir(homeDir = homedir()) {
+  return join(homeDir, 'Library/Application Support/Cursor');
+}
+
+function realExtensionsDir(homeDir = homedir()) {
+  return join(homeDir, '.cursor/extensions');
+}
+
+function commandHasPath(command: string, path: string) {
+  return command.includes(path);
+}
+
+function commandHasArgPath(command: string, flag: string, path: string) {
+  return command.includes(`${flag} ${path}`) || command.includes(`${flag}=${path}`);
+}
+
+export function inspectLaunchProcesses(input: LaunchInspectionInput): LaunchInspection {
+  const appPath = normalizePath(input.appPath);
+  const userDataDir = normalizePath(input.userDataDir);
+  const cursorExtensionsDir = normalizePath(input.cursorExtensionsDir);
+  const targetCommands = input.psOutput
+    .split('\n')
+    .map((line) => line.trim())
+    .filter((line) => commandHasPath(line, `${appPath}/Contents/`));
+
+  if (targetCommands.length === 0) {
+    return {
+      launch: 'not-running',
+      app: 'missing',
+      userData: 'unknown',
+      extensions: 'unknown',
+      realUserData: 'absent',
+      realExtensions: 'absent',
+    };
+  }
+
+  const realUserDataPath = realUserDataDir(input.homeDir);
+  const realExtensionsPath = realExtensionsDir(input.homeDir);
+  const hasIsolatedUserData = targetCommands.some((command) =>
+    commandHasArgPath(command, '--user-data-dir', userDataDir),
+  );
+  const hasIsolatedExtensions = targetCommands.some((command) =>
+    commandHasArgPath(command, '--extensions-dir', cursorExtensionsDir),
+  );
+  const hasRealUserData = targetCommands.some((command) =>
+    commandHasArgPath(command, '--user-data-dir', realUserDataPath),
+  );
+  const hasRealExtensions = targetCommands.some((command) =>
+    commandHasPath(command, realExtensionsPath),
+  );
+
+  return {
+    launch: 'running',
+    app: 'matched',
+    userData: hasRealUserData
+      ? 'real-cursor'
+      : hasIsolatedUserData
+        ? 'isolated'
+        : 'unknown',
+    extensions: hasIsolatedExtensions ? 'isolated' : 'unknown',
+    realUserData: hasRealUserData ? 'present' : 'absent',
+    realExtensions: hasRealExtensions ? 'present' : 'absent',
+  };
+}
+
+export function formatLaunchStatus(status: LaunchInspection) {
+  return [
+    `launch: ${status.launch}`,
+    `app: ${status.app}`,
+    `user-data: ${status.userData}`,
+    `extensions: ${status.extensions}`,
+    `real-user-data: ${status.realUserData}`,
+    `real-extensions: ${status.realExtensions}`,
+  ].join('\n');
+}
+
+export async function launchStatus(options: LaunchStatusOptions = {}) {
+  const appPath = assertDisposableCursorAppPath(options.appPath);
+  const userDataDir = requirePath(options.userDataDir, '--user-data-dir');
+  const cursorExtensionsDir = requirePath(
+    options.cursorExtensionsDir,
+    '--cursor-extensions-dir',
+  );
+  const psOutput =
+    options.psOutput ??
+    (await (options.execFile ?? execFileAsync)('ps', ['-axo', 'pid,ppid,command'])).stdout;
+
+  return formatLaunchStatus(
+    inspectLaunchProcesses({
+      psOutput,
+      appPath,
+      userDataDir,
+      cursorExtensionsDir,
+    }),
+  );
+}

package/src/patchSet.ts

@@ -0,0 +1,182 @@
+import { readFile } from 'node:fs/promises';
+import {
+  CURSOR_AGENT_EXEC_RELATIVE_PATH,
+  CURSOR_WORKBENCH_RELATIVE_PATH,
+  patchCursorAgentExec,
+  patchCursorWorkbenchAuthGate,
+  restoreCursorAgentExec,
+  restoreCursorAlwaysLocal,
+  restoreCursorWorkbenchAuthGate,
+  resolveCursorAgentExecPath,
+  resolveCursorAlwaysLocalPath,
+  resolveCursorWorkbenchPath,
+  containsCursorAlwaysLocalTakeoverMarker,
+  containsCursorWorkbenchAuthGateMarker,
+  CURSOR_ALWAYS_LOCAL_RELATIVE_PATH,
+} from '@cursor-pool/patcher';
+import { containsCursorPoolMarker } from '@cursor-pool/patcher/marker';
+
+export type CursorPatchName = 'agent-exec' | 'workbench';
+
+export type CursorPatchState = {
+  name: CursorPatchName;
+  markerPresent: boolean;
+  targetPath: string;
+};
+
+export type CursorPatchSetState = {
+  allApplied: boolean;
+  appliedCount: number;
+  patches: CursorPatchState[];
+};
+
+export type PatchCursorSetOptions = {
+  backupDir?: string;
+  platform?: NodeJS.Platform;
+  agentExecTargetRelativePath?: string;
+  alwaysLocalTargetRelativePath?: string;
+  workbenchTargetRelativePath?: string;
+  patchCursorAgentExec?: typeof patchCursorAgentExec;
+  patchCursorWorkbenchAuthGate?: typeof patchCursorWorkbenchAuthGate;
+};
+
+export type RestoreCursorSetOptions = {
+  backupDir?: string;
+  platform?: NodeJS.Platform;
+  alwaysLocalTargetRelativePath?: string;
+  workbenchTargetRelativePath?: string;
+  restoreCursorAgentExec?: typeof restoreCursorAgentExec;
+  restoreCursorAlwaysLocal?: typeof restoreCursorAlwaysLocal;
+  restoreCursorWorkbenchAuthGate?: typeof restoreCursorWorkbenchAuthGate;
+};
+
+const LINUX_WORKBENCH_RELATIVE_PATH =
+  'usr/share/cursor/resources/app/out/vs/workbench/workbench.desktop.main.js';
+const LINUX_ALWAYS_LOCAL_RELATIVE_PATH =
+  'usr/share/cursor/resources/app/extensions/cursor-always-local/dist/main.js';
+
+function workbenchRelativePath(options: { platform?: NodeJS.Platform; workbenchTargetRelativePath?: string }) {
+  return options.workbenchTargetRelativePath ?? (options.platform === 'linux' ? LINUX_WORKBENCH_RELATIVE_PATH : CURSOR_WORKBENCH_RELATIVE_PATH);
+}
+
+function alwaysLocalRelativePath(options: { platform?: NodeJS.Platform; alwaysLocalTargetRelativePath?: string }) {
+  return options.alwaysLocalTargetRelativePath ?? (options.platform === 'linux' ? LINUX_ALWAYS_LOCAL_RELATIVE_PATH : CURSOR_ALWAYS_LOCAL_RELATIVE_PATH);
+}
+
+async function fileContainsMarker(
+  targetPath: string,
+  predicate: (content: string) => boolean,
+) {
+  try {
+    return predicate(await readFile(targetPath, 'utf8'));
+  } catch {
+    return false;
+  }
+}
+
+export async function readCursorPatchSetState(
+  appPath: string,
+  options: { agentExecTargetRelativePath?: string; platform?: NodeJS.Platform; workbenchTargetRelativePath?: string } = {},
+): Promise<CursorPatchSetState> {
+  const agentExecPath = resolveCursorAgentExecPath(
+    appPath,
+    options.agentExecTargetRelativePath ?? CURSOR_AGENT_EXEC_RELATIVE_PATH,
+  );
+  const workbenchPath = resolveCursorWorkbenchPath(appPath, workbenchRelativePath(options));
+  const patches: CursorPatchState[] = [
+    {
+      name: 'agent-exec',
+      targetPath: agentExecPath,
+      markerPresent: await fileContainsMarker(agentExecPath, containsCursorPoolMarker),
+    },
+    {
+      name: 'workbench',
+      targetPath: workbenchPath,
+      markerPresent: await fileContainsMarker(
+        workbenchPath,
+        containsCursorWorkbenchAuthGateMarker,
+      ),
+    },
+  ];
+  const appliedCount = patches.filter((patch) => patch.markerPresent).length;
+  return {
+    allApplied: appliedCount === patches.length,
+    appliedCount,
+    patches,
+  };
+}
+
+export function formatCursorPatchSetState(state: CursorPatchSetState) {
+  if (state.allApplied) {
+    return 'applied';
+  }
+  if (state.appliedCount === 0) {
+    return 'missing';
+  }
+  const missing = state.patches
+    .filter((patch) => !patch.markerPresent)
+    .map((patch) => patch.name)
+    .join(',');
+  return `partial missing=${missing}`;
+}
+
+export async function patchCursorSet(appPath: string, options: PatchCursorSetOptions = {}) {
+  const before = await readCursorPatchSetState(appPath, {
+    agentExecTargetRelativePath: options.agentExecTargetRelativePath,
+    platform: options.platform,
+    workbenchTargetRelativePath: options.workbenchTargetRelativePath,
+  });
+  await (options.patchCursorAgentExec ?? patchCursorAgentExec)(appPath, {
+    backupDir: options.backupDir,
+    targetRelativePath: options.agentExecTargetRelativePath,
+  });
+  await (options.patchCursorWorkbenchAuthGate ?? patchCursorWorkbenchAuthGate)(appPath, {
+    backupDir: options.backupDir,
+    targetRelativePath: workbenchRelativePath(options),
+  });
+  const after = await readCursorPatchSetState(appPath, {
+    agentExecTargetRelativePath: options.agentExecTargetRelativePath,
+    platform: options.platform,
+    workbenchTargetRelativePath: options.workbenchTargetRelativePath,
+  });
+  return { before, after };
+}
+
+export async function restoreCursorSet(appPath: string, options: RestoreCursorSetOptions = {}) {
+  const restoreErrors: unknown[] = [];
+  const restore = async (operation: () => Promise<unknown>) => {
+    try {
+      await operation();
+    } catch (error) {
+      restoreErrors.push(error);
+    }
+  };
+
+  await restore(() =>
+    (options.restoreCursorWorkbenchAuthGate ?? restoreCursorWorkbenchAuthGate)(appPath, {
+      backupDir: options.backupDir,
+      targetRelativePath: workbenchRelativePath(options),
+    }),
+  );
+  const alwaysLocalPath = resolveCursorAlwaysLocalPath(appPath, alwaysLocalRelativePath(options));
+  const shouldRestoreAlwaysLocal =
+    Boolean(options.restoreCursorAlwaysLocal) ||
+    await fileContainsMarker(alwaysLocalPath, containsCursorAlwaysLocalTakeoverMarker);
+  if (shouldRestoreAlwaysLocal) {
+    await restore(() =>
+      (options.restoreCursorAlwaysLocal ?? restoreCursorAlwaysLocal)(appPath, {
+        backupDir: options.backupDir,
+        targetRelativePath: alwaysLocalRelativePath(options),
+      }),
+    );
+  }
+  await restore(() =>
+    (options.restoreCursorAgentExec ?? restoreCursorAgentExec)(appPath, {
+      backupDir: options.backupDir,
+    }),
+  );
+
+  if (restoreErrors.length > 0) {
+    throw new AggregateError(restoreErrors, 'Failed to restore one or more Cursor patches.');
+  }
+}

package/src/platform.ts

@@ -0,0 +1,132 @@
+import { arch, hostname, platform as osPlatform } from 'node:os';
+import { readRuntimeInfo } from '@cursor-pool/service';
+import type { PlatformStatus } from '@cursor-pool/service/platformSession';
+
+export type PlatformCommandOptions = {
+  runtimeFile?: string;
+  sessionFile?: string;
+};
+
+export type PlatformLoginOptions = PlatformCommandOptions & {
+  code?: string;
+  apiBaseUrl?: string;
+};
+
+function formatUser(status: Extract<PlatformStatus, { state: 'logged-in' | 'offline' | 'invalid-token' }>) {
+  return status.user ? [`user: ${status.user.email}`] : [];
+}
+
+function formatDevice(status: Extract<PlatformStatus, { state: 'logged-in' | 'offline' | 'invalid-token' }>) {
+  if (!status.device) {
+    return [];
+  }
+
+  return [
+    `device: ${status.device.status} ${status.device.id}`,
+    `heartbeat: ${status.device.lastHeartbeatAt}`,
+  ];
+}
+
+function assertNoSessionFileOverride(options: PlatformCommandOptions) {
+  if (options.sessionFile) {
+    throw new Error('--session-file is managed by the local service; restart the service with a platform session file instead');
+  }
+}
+
+export function formatPlatformStatus(status: PlatformStatus) {
+  if (status.state === 'logged-out') {
+    return 'platform: logged-out';
+  }
+
+  return [
+    `platform: ${status.state}`,
+    ...formatUser(status),
+    ...formatDevice(status),
+  ].join('\n');
+}
+
+export function formatPlatformLogin(status: PlatformStatus) {
+  return formatPlatformStatus(status);
+}
+
+async function serviceBaseUrl(options: PlatformCommandOptions) {
+  const runtime = await readRuntimeInfo({ runtimeFile: options.runtimeFile });
+  if (!runtime) {
+    throw new Error('Cursor Pool service runtime is unavailable');
+  }
+
+  return `http://${runtime.host}:${runtime.port}`;
+}
+
+async function requestPlatform(
+  options: PlatformCommandOptions,
+  path: string,
+  requestOptions: { method?: string; body?: Record<string, unknown> } = {},
+) {
+  const baseUrl = await serviceBaseUrl(options);
+  const response = await fetch(`${baseUrl}${path}`, {
+    method: requestOptions.method ?? 'GET',
+    headers: requestOptions.body ? { 'content-type': 'application/json' } : undefined,
+    body: requestOptions.body ? JSON.stringify(requestOptions.body) : undefined,
+  });
+
+  if (!response.ok) {
+    throw new Error(`Cursor Pool service request failed with status ${response.status}`);
+  }
+
+  return (await response.json()) as PlatformStatus;
+}
+
+function buildDeviceInfo() {
+  return {
+    name: hostname(),
+    os: osPlatform(),
+    arch: arch(),
+    cliVersion: '0.5.6',
+    serviceVersion: '0.5.6',
+    extensionVersion: '0.5.6',
+  };
+}
+
+export async function login(options: PlatformLoginOptions = {}) {
+  assertNoSessionFileOverride(options);
+  if (!options.code) {
+    throw new Error('--code is required');
+  }
+  if (!options.apiBaseUrl) {
+    throw new Error('--api-base-url is required');
+  }
+
+  const status = await requestPlatform(options, '/platform/login', {
+    method: 'POST',
+    body: {
+      code: options.code,
+      apiBaseUrl: options.apiBaseUrl,
+      device: buildDeviceInfo(),
+    },
+  });
+
+  return formatPlatformLogin(status);
+}
+
+export async function whoami(options: PlatformCommandOptions = {}) {
+  assertNoSessionFileOverride(options);
+  return formatPlatformStatus(await requestPlatform(options, '/platform/status'));
+}
+
+export async function heartbeat(options: PlatformCommandOptions = {}) {
+  assertNoSessionFileOverride(options);
+  return formatPlatformStatus(
+    await requestPlatform(options, '/platform/heartbeat', {
+      method: 'POST',
+      body: { serviceStatus: 'running' },
+    }),
+  );
+}
+
+export async function logout(options: PlatformCommandOptions = {}) {
+  assertNoSessionFileOverride(options);
+  return formatPlatformStatus(
+    await requestPlatform(options, '/platform/logout', { method: 'POST' }),
+  );
+}