@cursorpool-dev/cli 0.5.6

package/src/compat.ts

@@ -0,0 +1,282 @@
+import { createHmac, timingSafeEqual } from 'node:crypto';
+import { readFile } from 'node:fs/promises';
+import { fileURLToPath } from 'node:url';
+import type {
+  CompatibilityManifestEntry,
+  CompatibilityManifestEnvelope,
+} from '@cursor-pool/shared/manifest';
+import { CURSOR_AGENT_EXEC_RELATIVE_PATH } from '@cursor-pool/patcher';
+import type { CliEnvironment } from './environment';
+import type { CursorInfo } from './cursor';
+
+export const DEFAULT_COMPAT_ENTRIES: CompatibilityManifestEntry[] = [
+  {
+    platform: 'darwin',
+    arch: 'arm64',
+    cursorVersion: '3.5.38',
+    cursorCommit: '009bb5a3600dd98fe1c1f25798f767f686e14750',
+    supportStatus: 'supported',
+    targetRelativePath: CURSOR_AGENT_EXEC_RELATIVE_PATH,
+    expectedSha256: 'cb18f0237278884a39e2ce2b8664255e12689ad0803c20096c38e86c36acc51f',
+    structureSignature: 'ep1-verified-current',
+    patchStrategy: 'cursor-agent-exec-snippet',
+    verifyMarker: 'cursor-pool',
+    restoreStrategy: 'external-backup',
+    minCliVersion: '0.5.6',
+    minExtensionVersion: '0.5.6',
+    minServiceVersion: '0.5.6',
+    requiresWritableAppBundle: true,
+    requiresAdHocResign: true,
+    userMessage: 'Cursor 3.5.38 is supported for MVP-0.',
+  },
+  {
+    platform: 'darwin',
+    arch: 'x64',
+    cursorVersion: '3.5.38',
+    cursorCommit: '009bb5a3600dd98fe1c1f25798f767f686e14750',
+    supportStatus: 'supported',
+    targetRelativePath: CURSOR_AGENT_EXEC_RELATIVE_PATH,
+    expectedSha256: 'cb18f0237278884a39e2ce2b8664255e12689ad0803c20096c38e86c36acc51f',
+    structureSignature: 'ep1-verified-current',
+    patchStrategy: 'cursor-agent-exec-snippet',
+    verifyMarker: 'cursor-pool',
+    restoreStrategy: 'external-backup',
+    minCliVersion: '0.5.6',
+    minExtensionVersion: '0.5.6',
+    minServiceVersion: '0.5.6',
+    requiresWritableAppBundle: true,
+    requiresAdHocResign: true,
+    userMessage: 'Cursor 3.5.38 is supported for MVP-0 under Rosetta-launched installers.',
+  },
+  {
+    platform: 'darwin',
+    arch: 'arm64',
+    cursorVersion: '3.6.21',
+    cursorCommit: 'e7a7e93f4d75f8272503ecf33cedbaae10114a10',
+    supportStatus: 'supported',
+    targetRelativePath: CURSOR_AGENT_EXEC_RELATIVE_PATH,
+    expectedSha256: '222512631b78fddcdca3fa76c0dd458a7a86751dde19c998ceb31b3fe1905ebf',
+    structureSignature: 'ep1-verified-cursor-3-6-21',
+    patchStrategy: 'cursor-agent-exec-snippet',
+    verifyMarker: 'cursor-pool',
+    restoreStrategy: 'external-backup',
+    minCliVersion: '0.5.6',
+    minExtensionVersion: '0.5.6',
+    minServiceVersion: '0.5.6',
+    requiresWritableAppBundle: true,
+    requiresAdHocResign: true,
+    userMessage: 'Cursor 3.6.21 is supported for MVP-0.',
+  },
+];
+
+export type ResolveCompatOptions = {
+  entries?: CompatibilityManifestEntry[];
+};
+
+export type CompatManifestFetchResponse = {
+  ok: boolean;
+  json: () => Promise<unknown>;
+};
+
+export type LoadCompatEntriesOptions = {
+  compatEntries?: CompatibilityManifestEntry[];
+  apiBaseUrl?: string;
+  compatManifestUrl?: string;
+  fetchManifest?: (url: string) => Promise<CompatManifestFetchResponse>;
+};
+
+type RemoteCompatibilityManifestRule = CompatibilityManifestEntry & {
+  revision?: number;
+};
+
+const DEV_COMPAT_SIGNATURE_KEY = 'cursor-pool-compatibility-dev-signing-key';
+const DEV_COMPAT_SIGNATURE_ALGORITHM = 'hmac-sha256-dev';
+const DEV_COMPAT_SIGNATURE_KEY_ID = 'dev-compatibility-key';
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function isCompatibilityStatus(value: unknown): value is CompatibilityManifestEntry['supportStatus'] {
+  return (
+    value === 'supported' ||
+    value === 'canary' ||
+    value === 'warning' ||
+    value === 'blocked' ||
+    value === 'unknown'
+  );
+}
+
+function asString(value: unknown, field: string) {
+  if (typeof value !== 'string' || value.length === 0) {
+    throw new Error(`compat manifest ${field} invalid`);
+  }
+  return value;
+}
+
+function asBoolean(value: unknown, field: string) {
+  if (typeof value !== 'boolean') {
+    throw new Error(`compat manifest ${field} invalid`);
+  }
+  return value;
+}
+
+function normalizeRule(value: unknown): RemoteCompatibilityManifestRule {
+  if (!isRecord(value)) {
+    throw new Error('compat manifest rule invalid');
+  }
+  const supportStatus = value.supportStatus;
+  if (!isCompatibilityStatus(supportStatus)) {
+    throw new Error('compat manifest supportStatus invalid');
+  }
+  const revision = value.revision;
+  if (
+    revision !== undefined &&
+    (!Number.isInteger(revision) || typeof revision !== 'number' || revision < 1)
+  ) {
+    throw new Error('compat manifest revision invalid');
+  }
+  return {
+    platform: asString(value.platform, 'platform'),
+    arch: asString(value.arch, 'arch'),
+    cursorVersion: asString(value.cursorVersion, 'cursorVersion'),
+    cursorCommit: asString(value.cursorCommit, 'cursorCommit'),
+    supportStatus,
+    targetRelativePath: asString(value.targetRelativePath, 'targetRelativePath'),
+    expectedSha256: asString(value.expectedSha256, 'expectedSha256'),
+    structureSignature: asString(value.structureSignature, 'structureSignature'),
+    patchStrategy: asString(value.patchStrategy, 'patchStrategy'),
+    verifyMarker: asString(value.verifyMarker, 'verifyMarker'),
+    restoreStrategy: asString(value.restoreStrategy, 'restoreStrategy'),
+    minCliVersion: asString(value.minCliVersion, 'minCliVersion'),
+    minExtensionVersion: asString(value.minExtensionVersion, 'minExtensionVersion'),
+    minServiceVersion: asString(value.minServiceVersion, 'minServiceVersion'),
+    requiresWritableAppBundle: asBoolean(value.requiresWritableAppBundle, 'requiresWritableAppBundle'),
+    requiresAdHocResign: asBoolean(value.requiresAdHocResign, 'requiresAdHocResign'),
+    userMessage: asString(value.userMessage, 'userMessage'),
+    ...(revision === undefined ? {} : { revision }),
+  };
+}
+
+function canonicalRuleSegment(rule: RemoteCompatibilityManifestRule) {
+  return [
+    rule.platform,
+    rule.arch,
+    rule.cursorVersion,
+    rule.cursorCommit,
+    rule.supportStatus,
+    String(rule.revision ?? 1),
+  ].join(':');
+}
+
+function safeEqualHex(left: string, right: string) {
+  const leftBuffer = Buffer.from(left, 'hex');
+  const rightBuffer = Buffer.from(right, 'hex');
+  if (leftBuffer.length === 0 || leftBuffer.length !== rightBuffer.length) {
+    return false;
+  }
+  return timingSafeEqual(leftBuffer, rightBuffer);
+}
+
+export function buildCompatManifestSignature(
+  version: number,
+  rules: RemoteCompatibilityManifestRule[],
+) {
+  const canonical = [String(version), ...[...rules].sort((a, b) => canonicalRuleSegment(a).localeCompare(canonicalRuleSegment(b))).map(canonicalRuleSegment)].join('|');
+  return createHmac('sha256', DEV_COMPAT_SIGNATURE_KEY).update(canonical).digest('hex');
+}
+
+export function verifyCompatManifestEnvelope(
+  envelope: unknown,
+): CompatibilityManifestEntry[] {
+  if (!isRecord(envelope)) {
+    throw new Error('compat manifest envelope invalid');
+  }
+  const version = envelope.version;
+  if (!Number.isInteger(version) || typeof version !== 'number' || version < 1) {
+    throw new Error('compat manifest version invalid');
+  }
+  if (envelope.signatureAlgorithm !== DEV_COMPAT_SIGNATURE_ALGORITHM) {
+    throw new Error('compat manifest signature algorithm unsupported');
+  }
+  if (envelope.signatureKeyId !== DEV_COMPAT_SIGNATURE_KEY_ID) {
+    throw new Error('compat manifest signature key unsupported');
+  }
+  if (typeof envelope.signature !== 'string') {
+    throw new Error('compat manifest signature invalid');
+  }
+  if (!Array.isArray(envelope.rules) || envelope.rules.length === 0) {
+    throw new Error('compat manifest rules invalid');
+  }
+  const rules = envelope.rules.map(normalizeRule);
+  const expected = buildCompatManifestSignature(version, rules);
+  if (!safeEqualHex(envelope.signature, expected)) {
+    throw new Error('compat manifest signature invalid');
+  }
+  return rules.map(({ revision, ...rule }) => rule);
+}
+
+export function compatManifestUrlFromApiBaseUrl(apiBaseUrl: string) {
+  return `${apiBaseUrl.replace(/\/+$/, '')}/api/client/compatibility/manifest`;
+}
+
+export async function loadCompatEntries(
+  options: LoadCompatEntriesOptions = {},
+): Promise<CompatibilityManifestEntry[]> {
+  if (options.compatEntries) {
+    return options.compatEntries;
+  }
+
+  const manifestUrl =
+    options.compatManifestUrl ??
+    (options.apiBaseUrl ? compatManifestUrlFromApiBaseUrl(options.apiBaseUrl) : undefined);
+  if (!manifestUrl) {
+    return DEFAULT_COMPAT_ENTRIES;
+  }
+
+  if (manifestUrl.startsWith('file://')) {
+    try {
+      const body = await readFile(fileURLToPath(manifestUrl), 'utf8');
+      return verifyCompatManifestEnvelope(JSON.parse(body));
+    } catch {
+      return DEFAULT_COMPAT_ENTRIES;
+    }
+  }
+
+  const fetchManifest = options.fetchManifest ?? fetch;
+  try {
+    const response = await fetchManifest(manifestUrl);
+    if (!response.ok) {
+      return DEFAULT_COMPAT_ENTRIES;
+    }
+    return verifyCompatManifestEnvelope(await response.json());
+  } catch {
+    return DEFAULT_COMPAT_ENTRIES;
+  }
+}
+
+export function resolveCompatEntry(
+  cursor: CursorInfo,
+  environment: CliEnvironment,
+  options: ResolveCompatOptions = {},
+) {
+  const entries = options.entries ?? DEFAULT_COMPAT_ENTRIES;
+  const entry = entries.find(
+    (candidate) =>
+      candidate.platform === environment.platform &&
+      candidate.arch === environment.arch &&
+      candidate.cursorVersion === cursor.version &&
+      candidate.cursorCommit === cursor.commit,
+  );
+
+  if (!entry) {
+    throw new Error(
+      `No compatibility entry for Cursor ${cursor.version} ${cursor.commit} on ${environment.platform}/${environment.arch}`,
+    );
+  }
+  if (entry.supportStatus === 'blocked') {
+    throw new Error(`Cursor ${cursor.version} is blocked: ${entry.userMessage}`);
+  }
+
+  return entry;
+}

package/src/confirm.ts

@@ -0,0 +1,76 @@
+import { createInterface } from 'node:readline/promises';
+import { stdin as input, stdout as output } from 'node:process';
+
+export type RealOperation = 'install' | 'repair' | 'restore' | 'uninstall';
+
+export type RealOperationSummary = {
+  operation: RealOperation;
+  appPath: string;
+  targetPath: string;
+  backupPath?: string;
+  runtimeFile?: string;
+  extensionInstallPath?: string;
+  extensionLinkedPath?: string;
+  restorePath?: string;
+};
+
+export type ConfirmRealOperationOptions = {
+  summary: RealOperationSummary;
+  yes?: boolean;
+  isInteractive?: boolean;
+  askConfirmation?: (prompt: string) => boolean | Promise<boolean>;
+};
+
+export function formatRealOperationSummary(summary: RealOperationSummary) {
+  const lines = [
+    `operation: ${summary.operation}`,
+    `app: ${summary.appPath}`,
+    `target: ${summary.targetPath}`,
+  ];
+
+  if (summary.backupPath) {
+    lines.push(`backup: ${summary.backupPath}`);
+  }
+  if (summary.runtimeFile) {
+    lines.push(`runtime: ${summary.runtimeFile}`);
+  }
+  if (summary.extensionInstallPath) {
+    lines.push(`extension-install: ${summary.extensionInstallPath}`);
+  }
+  if (summary.extensionLinkedPath) {
+    lines.push(`extension-linked: ${summary.extensionLinkedPath}`);
+  }
+  if (summary.restorePath) {
+    lines.push(`restore: ${summary.restorePath}`);
+  }
+
+  return lines.join('\n');
+}
+
+async function askWithReadline(prompt: string) {
+  const rl = createInterface({ input, output });
+  try {
+    const answer = await rl.question(prompt);
+    return ['y', 'yes'].includes(answer.trim().toLowerCase());
+  } finally {
+    rl.close();
+  }
+}
+
+export async function confirmRealOperation(options: ConfirmRealOperationOptions) {
+  const { operation } = options.summary;
+  if (options.yes) {
+    return;
+  }
+
+  const isInteractive = options.isInteractive ?? Boolean(input.isTTY && output.isTTY);
+  if (!isInteractive) {
+    throw new Error(`Pass --yes to confirm ${operation} for real Cursor`);
+  }
+
+  const prompt = `${formatRealOperationSummary(options.summary)}\nProceed? [y/N] `;
+  const confirmed = await (options.askConfirmation ?? askWithReadline)(prompt);
+  if (!confirmed) {
+    throw new Error(`${operation} cancelled`);
+  }
+}

package/src/cursor.ts

@@ -0,0 +1,94 @@
+import { readFile } from 'node:fs/promises';
+import { join, win32 } from 'node:path';
+
+export const DEFAULT_MACOS_CURSOR_APP_PATH = '/Applications/Cursor.app';
+
+export type CursorInfo = {
+  appPath: string;
+  version: string;
+  commit: string;
+};
+
+export type FindCursorOptions = {
+  appPath?: string;
+  productRelativePath?: string;
+  platform?: NodeJS.Platform;
+  env?: NodeJS.ProcessEnv;
+};
+
+type CursorProductJson = {
+  version?: unknown;
+  commit?: unknown;
+  commitHash?: unknown;
+  cursorCommit?: unknown;
+};
+
+export function defaultCursorAppPath(options: Pick<FindCursorOptions, 'platform' | 'env'> = {}) {
+  const platform = options.platform ?? process.platform;
+  if (platform === 'darwin') {
+    return DEFAULT_MACOS_CURSOR_APP_PATH;
+  }
+  if (platform === 'win32') {
+    const localAppData = options.env?.LOCALAPPDATA ?? process.env.LOCALAPPDATA;
+    if (!localAppData) {
+      throw new Error('LOCALAPPDATA is required to auto-detect Cursor on Windows');
+    }
+    return win32.join(localAppData, 'Programs', 'Cursor');
+  }
+  throw new Error(`Cursor app auto-detection is not supported on ${platform}`);
+}
+
+function readString(value: unknown) {
+  return typeof value === 'string' && value.length > 0 ? value : undefined;
+}
+
+export async function findCursor(options: FindCursorOptions = {}): Promise<CursorInfo> {
+  const appPath = options.appPath ?? defaultCursorAppPath(options);
+  const productJsonPath = await resolveProductJsonPath(appPath, options);
+  const product = JSON.parse(await readFile(productJsonPath, 'utf8')) as CursorProductJson;
+  const version = readString(product.version);
+  const commit =
+    readString(product.commit) ??
+    readString(product.cursorCommit) ??
+    readString(product.commitHash);
+
+  if (!version) {
+    throw new Error(`Cursor product.json is missing version: ${productJsonPath}`);
+  }
+  if (!commit) {
+    throw new Error(`Cursor product.json is missing commit: ${productJsonPath}`);
+  }
+
+  return {
+    appPath,
+    version,
+    commit,
+  };
+}
+
+async function resolveProductJsonPath(appPath: string, options: FindCursorOptions) {
+  if (options.productRelativePath) {
+    return join(appPath, options.productRelativePath);
+  }
+
+  const candidates = [
+    'Contents/Resources/app/product.json',
+    'usr/share/cursor/resources/app/product.json',
+    'resources/app/product.json',
+    'opt/Cursor/resources/app/product.json',
+  ];
+
+  for (const candidate of candidates) {
+    const path = join(appPath, candidate);
+    try {
+      await readFile(path, 'utf8');
+      return path;
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== 'ENOENT') {
+        throw error;
+      }
+    }
+  }
+
+  return join(appPath, candidates[0] ?? 'Contents/Resources/app/product.json');
+}