ocx-cursor 1.0.1 → 1.0.3

package/README.md

@@ -6,7 +6,7 @@
 Use your active [OpenCodex](https://github.com/lidge-jun/opencodex) models in Cursor through an authenticated HTTPS endpoint on your Mac.
 
 > [!WARNING]
-> The installer edits two private workbench files inside `Cursor.app`. This invalidates Cursor's vendor signature. Cursor may report a corrupt installation. The bridge saves the original files under `~/.opencodex/cursor-bridge/cursor-app-backups`. Reinstall Cursor to restore a signed app.
+> The installer edits two private workbench files inside `Cursor.app`. This invalidates Cursor's vendor signature, so the bridge applies a local ad-hoc seal and removes the app's quarantine attribute after each patch to prevent macOS from reporting a corrupt installation. The bridge saves the original files under `~/.opencodex/cursor-bridge/cursor-app-backups`. Reinstall Cursor to restore a vendor-signed app.
 
 ## Requirements
 
@@ -125,14 +125,18 @@ The patch keeps the model metadata that Cursor would discard. It leaves Cursor's
 
 The login service refreshes the catalog every 15 seconds. It waits for Cursor to quit before writing the state database or reapplying a patch after a Cursor update.
 
+On macOS, the patch monitor pauses while Cursor's `ShipIt` updater is running. After Cursor and the updater stop, it waits until all patch targets remain unchanged for five seconds before writing them. This prevents the bridge from modifying `Cursor.app` while an in-app update is replacing it.
+
 ## Commands
 
 | Command | Action |
 | --- | --- |
 | `ocx-cursor init --base-url URL` | Install the service, test the HTTPS endpoint, configure Cursor, and sync models. |
 | `ocx-cursor install` | Reinstall the service and check the two metadata patches. |
+| `ocx-cursor stop` | Stop the service without removing its configuration or state. |
+| `ocx-cursor start` | Start the installed service. |
 | `ocx-cursor update` | Install the current npm release and restart the service. |
-| `ocx-cursor sync` | Read the active OpenCodex catalog and update Cursor. |
+| `ocx-cursor sync` | With Cursor closed, pause the service, verify the app patch, sync the active catalog, and restart the service. |
 | `ocx-cursor status` | Print service, gateway, catalog, and pending-sync status. |
 | `ocx-cursor uninstall` | Remove the service, command link, and bridge state. |
 
@@ -159,7 +163,7 @@ The bridge reads `~/.opencodex/service-api-token` when OpenCodex uses service au
 | Cursor returns 401 | Quit Cursor and rerun `npx ocx-cursor init --base-url https://YOUR_HOST/v1`. |
 | The hostname returns 502 | Run `ocx-cursor status`, then check that the tunnel points to port `10101`. |
 | Cloudflare returns 1016 | Run `cloudflared tunnel info ocx-cursor` and check the service. |
-| Models or controls are missing | Quit Cursor and run `ocx-cursor sync`. |
+| Models or controls are missing | Quit Cursor and run `ocx-cursor sync`. It repairs the foreground app patch before writing model metadata. |
 | A Cursor update removed the patch | Quit Cursor and run `ocx-cursor install`. |
 
 Read the service logs:

package/bin/ocx-cursor.mjs

@@ -5,7 +5,7 @@ import process from "node:process";
 import { createInterface } from "node:readline/promises";
 import { configureCursorOpenAI, storedCursorOpenAIBaseUrl } from "../src/cursor-config.mjs";
 import { cursorIsRunning } from "../src/cursor-state.mjs";
-import { installService, prepareInstallSecret, serviceStatus, uninstallService, updateService } from "../src/install.mjs";
+import { installService, prepareInstallSecret, repairCursorMetadataPatch, serviceStatus, startService, stopService, uninstallService, updateService } from "../src/install.mjs";
 import { cursorOpenAIBaseUrl, pendingFile } from "../src/paths.mjs";
 import { runService } from "../src/service.mjs";
 import { normalizeBaseUrl, testEndpoint } from "../src/setup.mjs";
@@ -19,6 +19,8 @@ Usage:
                         Install the service, test the endpoint, configure Cursor,
                         and sync models
   ocx-cursor install    Install and start the macOS companion service
+  ocx-cursor stop       Stop the companion service without removing its state
+  ocx-cursor start      Start the installed companion service
   ocx-cursor update     Install the latest companion release and restart it
   ocx-cursor sync       Sync active OpenCodex models into Cursor
   ocx-cursor launch [--port <port>]
@@ -71,6 +73,10 @@ function printSync(result) {
 }
 
 function printCursorPatches(result) {
+  if (!result.cursorInstalled) {
+    process.stdout.write("Cursor is not installed; app patches will be applied after it is installed.\n");
+    return;
+  }
   if (result.cursorPatches === null) {
     process.stdout.write("Cursor app patches will be applied after Cursor quits.\n");
     return;
@@ -131,7 +137,29 @@ async function main() {
     await updateService();
     return;
   }
+  if (command === "stop") {
+    stopService();
+    process.stdout.write("Stopped OpenCodex Cursor Bridge.\n");
+    return;
+  }
+  if (command === "start") {
+    await startService();
+    process.stdout.write("Started OpenCodex Cursor Bridge.\n");
+    return;
+  }
   if (command === "sync") {
+    if (!cursorIsRunning()) {
+      stopService();
+      try {
+        const cursorPatches = await repairCursorMetadataPatch();
+        const changed = cursorPatches.filter(({ status }) => status === "patched").length;
+        process.stdout.write(`Verified ${cursorPatches.length} Cursor metadata patches (${changed} changed).\n`);
+        printSync(await syncNow());
+      } finally {
+        await startService();
+      }
+      return;
+    }
     printSync(await syncNow());
     return;
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ocx-cursor",
-  "version": "1.0.1",
+  "version": "1.0.3",
   "description": "Use OpenCodex models in Cursor through an authenticated HTTPS gateway",
   "keywords": [
     "opencodex",

package/src/cursor-patch.mjs

@@ -1,7 +1,9 @@
+import { execFileSync } from "node:child_process";
 import { createHash } from "node:crypto";
 import { chmod, copyFile, mkdir, readFile, rename, stat, writeFile } from "node:fs/promises";
 import { basename, dirname, join } from "node:path";
 import {
+  cursorAppPath,
   cursorBundleFiles,
   cursorGlassWorkbenchFile,
   cursorLocalRuntimeFiles,
@@ -36,6 +38,21 @@ const localRuntimeBuilderExport = /buildBottlerocketPickerModels:\(\)=>(?<builde
 const transientPatchErrorCodes = new Set(["EACCES", "EBUSY", "EPERM"]);
 const directoryPatchQueues = new Map();
 
+export function clearCursorAppQuarantine(options = {}) {
+  const execute = options.execFileSync || execFileSync;
+  execute("/usr/bin/xattr", ["-dr", "com.apple.quarantine", options.appPath || cursorAppPath], {
+    stdio: "ignore",
+  });
+}
+
+export function finalizeCursorAppPatch(options = {}) {
+  const execute = options.execFileSync || execFileSync;
+  const appPath = options.appPath || cursorAppPath;
+  execute("/usr/bin/codesign", ["--force", "--sign", "-", appPath], { stdio: "ignore" });
+  execute("/usr/bin/codesign", ["--verify", "--deep", "--strict", appPath], { stdio: "ignore" });
+  clearCursorAppQuarantine({ ...options, appPath, execFileSync: execute });
+}
+
 function replaceSingleMatch(source, pattern, replacement, label) {
   const matches = [...source.matchAll(pattern)];
   if (matches.length !== 1) throw new Error(`Expected one Cursor ${label}, found ${matches.length}`);
@@ -354,33 +371,86 @@ export function startCursorModelMetadataPatchMonitor(options = {}) {
 
 export function startCursorPatchMonitor(options = {}) {
   const intervalMs = options.intervalMs || 250;
+  const stableMs = options.stableMs || 0;
   const bundleFiles = options.file ? [options.file] : (options.bundleFiles || options.files || cursorBundleFiles);
   const runtimeFiles = options.file ? [] : (options.localRuntimeFiles || cursorLocalRuntimeFiles);
   const files = [...bundleFiles, ...runtimeFiles];
   const localRuntimeFiles = new Set(runtimeFiles);
   const lastSignatures = new Map();
+  let stableFingerprint = null;
+  let stableSince = 0;
   let patchPromise = null;
   let stopped = false;
 
-  const check = async () => {
-    if (stopped || patchPromise || options.shouldPatch?.() === false) return patchPromise;
-    patchPromise = Promise.all(files.map(async (file) => {
-      let signature;
+  const resetStability = () => {
+    stableFingerprint = null;
+    stableSince = 0;
+  };
+
+  const filesAreStable = async () => {
+    if (stableMs === 0) return true;
+    const signatures = await Promise.all(files.map(async (file) => {
       try {
-        signature = await cursorWorkbenchSignature(file);
+        return await cursorWorkbenchSignature(file);
       } catch {
-        return;
+        return null;
       }
-      if (signature === lastSignatures.get(file)) return;
+    }));
+    if (signatures.some((signature) => signature === null)) {
+      resetStability();
+      return false;
+    }
+    const fingerprint = signatures.join("|");
+    const now = (options.now || Date.now)();
+    if (fingerprint !== stableFingerprint) {
+      stableFingerprint = fingerprint;
+      stableSince = now;
+      return false;
+    }
+    return now - stableSince >= stableMs;
+  };
+
+  const check = async () => {
+    if (stopped || patchPromise) return patchPromise;
+    if (options.shouldPatch?.() === false) {
+      resetStability();
+      lastSignatures.clear();
+      return null;
+    }
+    patchPromise = (async () => {
+      if (!await filesAreStable()) return [];
+      let retryAfterStabilityDelay = false;
+      const results = await Promise.all(files.map(async (file) => {
+        let signature;
+        try {
+          signature = await cursorWorkbenchSignature(file);
+        } catch {
+          return;
+        }
+        if (signature === lastSignatures.get(file)) return;
+        try {
+          const result = await ensureCursorPatchFile(file, localRuntimeFiles, options);
+          lastSignatures.set(file, result.signature);
+          options.onResult?.(result);
+          return result;
+        } catch (error) {
+          if (transientPatchErrorCodes.has(error.code)) retryAfterStabilityDelay = true;
+          else lastSignatures.set(file, signature);
+          options.onError?.(error, file);
+        }
+      }));
+      if (retryAfterStabilityDelay) resetStability();
+      const patched = results.filter((result) => result?.status === "patched");
       try {
-        const result = await ensureCursorPatchFile(file, localRuntimeFiles, options);
-        lastSignatures.set(file, result.signature);
-        options.onResult?.(result);
+        if (patched.length > 0) await options.onPatched?.(patched);
+        if (results.length === files.length && results.every(Boolean)) await options.onReady?.(results);
       } catch (error) {
-        if (!transientPatchErrorCodes.has(error.code)) lastSignatures.set(file, signature);
-        options.onError?.(error, file);
+        resetStability();
+        lastSignatures.clear();
+        options.onError?.(error, options.appPath || cursorAppPath);
       }
-    })).finally(() => {
+      return results;
+    })().finally(() => {
       patchPromise = null;
     });
     return patchPromise;

package/src/cursor-state.mjs

@@ -64,6 +64,17 @@ export function cursorIsRunning() {
   }
 }
 
+export function cursorUpdateIsRunning(execute = execFileSync) {
+  try {
+    execute("pgrep", ["-f", "(com\\.todesktop\\.230313mzl4w4u92|co\\.anysphere\\.cursor[^ ]*)\\.ShipIt"], {
+      stdio: "ignore",
+    });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 export function defaultEffort(model) {
   const modelId = model.sourceId.split("/").at(-1);
   if (/^(?:gpt|gemini)-/.test(modelId) && model.reasoningEfforts.includes("medium")) return "medium";

package/src/install.mjs

@@ -4,10 +4,11 @@ import { access, chmod, copyFile, cp, lstat, mkdir, mkdtemp, readFile, readlink,
 import { tmpdir } from "node:os";
 import { dirname, join, relative, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
-import { ensureCursorModelMetadataPatched } from "./cursor-patch.mjs";
+import { ensureCursorModelMetadataPatched, finalizeCursorAppPatch } from "./cursor-patch.mjs";
 import { cursorIsRunning } from "./cursor-state.mjs";
 import {
   cliLinkFile,
+  cursorAppPath,
   installRoot,
   installedPackageRoot,
   launchAgentFile,
@@ -39,16 +40,16 @@ function commandOutput(command, args) {
   }
 }
 
-function bootout(label) {
+function bootout(label, execute = execFileSync) {
   try {
-    execFileSync("launchctl", ["bootout", `${launchDomain}/${label}`], { stdio: "ignore" });
+    execute("launchctl", ["bootout", `${launchDomain}/${label}`], { stdio: "ignore" });
   } catch {}
 }
 
-async function bootstrap(plist) {
+async function bootstrap(plist, execute = execFileSync) {
   for (let attempt = 0; attempt < 5; attempt += 1) {
     try {
-      execFileSync("launchctl", ["bootstrap", launchDomain, plist], { stdio: "ignore" });
+      execute("launchctl", ["bootstrap", launchDomain, plist], { stdio: "ignore" });
       return;
     } catch (error) {
       if (attempt === 4) throw error;
@@ -168,27 +169,50 @@ function launchAgent(nodePath) {
 export async function installService() {
   await mkdir(dirname(launchAgentFile), { recursive: true });
   const { legacyPlist, secretStatus } = await prepareInstallSecret();
-  const cursorPatches = cursorIsRunning()
-    ? null
-    : await Promise.all(cursorModelMetadataFiles.map(async (file) => ({
-      file,
-      ...await ensureCursorModelMetadataPatched({ file }),
-    })));
-  await copyPackage();
-  await installCliLink();
-
-  const nodePath = (await exists("/opt/homebrew/bin/node")) ? "/opt/homebrew/bin/node" : process.execPath;
-  await writeFile(launchAgentFile, launchAgent(nodePath), { mode: 0o644 });
   bootout(serviceLabel);
   bootout(legacyServiceLabel);
-  await bootstrap(launchAgentFile);
+  let cursorInstalled;
+  let cursorPatches;
+  try {
+    cursorInstalled = await exists(cursorAppPath);
+    cursorPatches = cursorIsRunning() || !cursorInstalled
+      ? null
+      : await repairCursorMetadataPatch();
+    await copyPackage();
+    await installCliLink();
+
+    const nodePath = (await exists("/opt/homebrew/bin/node")) ? "/opt/homebrew/bin/node" : process.execPath;
+    await writeFile(launchAgentFile, launchAgent(nodePath), { mode: 0o644 });
+    await bootstrap(launchAgentFile);
+  } catch (error) {
+    if (await exists(launchAgentFile)) await bootstrap(launchAgentFile).catch(() => {});
+    throw error;
+  }
 
   if (legacyPlist.startsWith(dirname(legacyLaunchAgentFile)) && await exists(legacyPlist)) {
     const disabled = `${legacyPlist}.disabled-by-${serviceLabel}`;
     await rm(disabled, { force: true });
     await rename(legacyPlist, disabled);
   }
-  return { installRoot, launchAgentFile, cliLinkFile, secretStatus, cursorPatches };
+  return { installRoot, launchAgentFile, cliLinkFile, secretStatus, cursorInstalled, cursorPatches };
+}
+
+export async function repairCursorMetadataPatch(options = {}) {
+  const running = options.cursorRunning ?? cursorIsRunning();
+  if (running) throw new Error("Quit Cursor before repairing its metadata patch");
+  const appPath = options.cursorAppPath || cursorAppPath;
+  const pathExists = options.exists || exists;
+  if (!await pathExists(appPath)) throw new Error("Cursor is not installed in /Applications");
+
+  const patchFile = options.ensureCursorModelMetadataPatched || ensureCursorModelMetadataPatched;
+  const files = options.files || cursorModelMetadataFiles;
+  const patches = await Promise.all(files.map(async (file) => ({
+    file,
+    ...await patchFile({ file }),
+  })));
+  const finalizePatch = options.finalizeCursorAppPatch || finalizeCursorAppPatch;
+  finalizePatch({ appPath });
+  return patches;
 }
 
 export async function updateService(options = {}) {
@@ -209,6 +233,21 @@ export async function updateService(options = {}) {
   }
 }
 
+export function stopService(options = {}) {
+  bootout(serviceLabel, options.execFileSync || execFileSync);
+}
+
+export async function startService(options = {}) {
+  const plist = options.launchAgentFile || launchAgentFile;
+  const pathExists = options.exists || exists;
+  if (!await pathExists(plist)) {
+    throw new Error("OpenCodex Cursor Bridge is not installed; run ocx-cursor install first");
+  }
+  const execute = options.execFileSync || execFileSync;
+  bootout(serviceLabel, execute);
+  await bootstrap(plist, execute);
+}
+
 export async function uninstallService() {
   bootout(serviceLabel);
   await rm(launchAgentFile, { force: true });

package/src/paths.mjs

@@ -14,7 +14,8 @@ export const stderrFile = join(installRoot, "service.error.log");
 export const launchAgentFile = join(homedir(), "Library", "LaunchAgents", `${serviceLabel}.plist`);
 export const legacyLaunchAgentFile = join(homedir(), "Library", "LaunchAgents", `${legacyServiceLabel}.plist`);
 export const cursorDatabaseFile = join(homedir(), "Library", "Application Support", "Cursor", "User", "globalStorage", "state.vscdb");
-export const cursorAppOutDirectory = "/Applications/Cursor.app/Contents/Resources/app/out";
+export const cursorAppPath = "/Applications/Cursor.app";
+export const cursorAppOutDirectory = join(cursorAppPath, "Contents", "Resources", "app", "out");
 export const cursorWorkbenchFile = join(cursorAppOutDirectory, "vs", "workbench", "workbench.desktop.main.js");
 export const cursorGlassWorkbenchFile = join(cursorAppOutDirectory, "vs", "workbench", "workbench.glass.main.js");
 export const cursorModelMetadataFiles = [cursorWorkbenchFile, cursorGlassWorkbenchFile];

package/src/service.mjs

@@ -1,9 +1,10 @@
 import { randomBytes } from "node:crypto";
 import { chmod, mkdir, readFile, writeFile } from "node:fs/promises";
 import { buildActiveCatalog } from "./catalog.mjs";
-import { startCursorModelMetadataPatchMonitor } from "./cursor-patch.mjs";
+import { finalizeCursorAppPatch, startCursorModelMetadataPatchMonitor } from "./cursor-patch.mjs";
 import {
   cursorIsRunning,
+  cursorUpdateIsRunning,
   readPendingCatalog,
 } from "./cursor-state.mjs";
 import { startGateway } from "./gateway.mjs";
@@ -27,6 +28,7 @@ export async function runService(options = {}) {
   let refreshPromise = null;
   let cursorSyncPromise = null;
   let wasCursorRunning = cursorIsRunning();
+  let cursorPatchReady = false;
   let stopped = false;
 
   const refresh = async () => {
@@ -37,7 +39,10 @@ export async function runService(options = {}) {
         if (JSON.stringify(next) === JSON.stringify(catalog)) return;
         catalog = next;
         await saveCatalogSnapshot(catalog);
-        const result = await applyOrQueueCatalog(catalog, { createBackup: false });
+        const result = await applyOrQueueCatalog(catalog, {
+          createBackup: false,
+          defer: !cursorPatchReady,
+        });
         process.stdout.write(`${result.status === "queued" ? "Queued" : "Synced"} ${result.modelCount} Cursor models\n`);
       } catch (error) {
         process.stderr.write(`Catalog refresh failed: ${error.message}\n`);
@@ -61,19 +66,33 @@ export async function runService(options = {}) {
   const server = startGateway({ secret, getCatalog: () => catalog, host: options.host, port: options.port });
   const patchMonitor = startCursorModelMetadataPatchMonitor({
     intervalMs: options.cursorPatchIntervalMs,
-    shouldPatch: () => !cursorIsRunning(),
+    stableMs: options.cursorPatchStableMs ?? 5_000,
+    shouldPatch: () => !cursorIsRunning() && !cursorUpdateIsRunning(),
     onResult: (result) => {
       if (result.status === "patched") process.stdout.write(`Patched Cursor app file ${result.file} (backup: ${result.backupPath})\n`);
     },
-    onError: (error, file) => process.stderr.write(`Cursor patch failed for ${file}: ${error.message}\n`),
+    onPatched: () => {
+      finalizeCursorAppPatch();
+    },
+    onReady: (results) => {
+      if (results.every(({ status }) => status === "already-patched")) finalizeCursorAppPatch();
+      cursorPatchReady = true;
+      wasCursorRunning = true;
+    },
+    onError: (error, file) => {
+      cursorPatchReady = false;
+      process.stderr.write(`Cursor patch failed for ${file}: ${error.message}\n`);
+    },
   });
   const refreshTimer = setInterval(refresh, options.refreshIntervalMs || 15_000);
   const pendingTimer = setInterval(() => {
     if (cursorSyncPromise) return;
     if (cursorIsRunning()) {
       wasCursorRunning = true;
+      cursorPatchReady = false;
       return;
     }
+    if (!cursorPatchReady) return;
     cursorSyncPromise = (async () => {
       const pending = await readPendingCatalog();
       const next = pending || (wasCursorRunning ? catalog : null);

package/src/sync.mjs

@@ -25,16 +25,20 @@ export async function saveCatalogSnapshot(catalog) {
 }
 
 export async function applyOrQueueCatalog(catalog, options = {}) {
-  if (cursorIsRunning()) {
-    await writePendingCatalog(catalog);
+  const running = options.cursorRunning ?? cursorIsRunning();
+  const queueCatalog = options.writePendingCatalog || writePendingCatalog;
+  if (options.defer || running) {
+    await queueCatalog(catalog);
     return {
       status: "queued",
       modelCount: catalog.length,
       effortCount: catalog.filter(({ reasoningEfforts }) => reasoningEfforts.length > 0).length,
     };
   }
-  const result = await syncCursorDatabase(catalog, options);
-  await clearPendingCatalog();
+  const syncDatabase = options.syncCursorDatabase || syncCursorDatabase;
+  const clearPending = options.clearPendingCatalog || clearPendingCatalog;
+  const result = await syncDatabase(catalog, options);
+  await clearPending();
   return { status: "synced", ...result };
 }