ocx-cursor 0.1.0 → 0.2.0

package/README.md

@@ -3,27 +3,101 @@
 [![npm version](https://img.shields.io/npm/v/ocx-cursor.svg)](https://www.npmjs.com/package/ocx-cursor)
 [![CI](https://github.com/hiddenest/opencodex-cursor-bridge/actions/workflows/ci.yml/badge.svg)](https://github.com/hiddenest/opencodex-cursor-bridge/actions/workflows/ci.yml)
 
-Use active [OpenCodex](https://github.com/lidge-jun/opencodex) models in Cursor through its custom OpenAI endpoint. The package runs a local gateway and keeps Cursor's custom model list in sync.
+Use active [OpenCodex](https://github.com/lidge-jun/opencodex) models in Cursor through its custom OpenAI endpoint. The package runs a local gateway, registers the endpoint in Cursor, and keeps Cursor's custom model list in sync.
 
 ## Requirements
 
 - macOS with Cursor installed at `/Applications/Cursor.app`
 - Node.js 22.5 or newer
-- OpenCodex installed, signed in, and running
-- An HTTPS hostname that forwards to `http://127.0.0.1:10101`
+- A domain using Cloudflare DNS, or another HTTPS reverse proxy
 
 Launch Cursor and sign in once before setup. Cursor creates the Safe Storage key that the installer uses to encrypt the gateway API key.
 
-## Set up an HTTPS endpoint
+## Setup
 
-Cursor's custom OpenAI endpoint must use HTTPS. Point a tunnel or reverse proxy at the local gateway on port `10101`.
+The commands below use `cursor-api.example.com`. Replace it with a hostname under your own Cloudflare-managed domain.
 
-This Cloudflare Tunnel config maps `cursor-api.example.com` to the gateway:
+### 1. Install OpenCodex
+
+[OpenCodex](https://github.com/lidge-jun/opencodex) requires Node.js 18 or newer and bundles its own Bun runtime. This bridge requires Node.js 22.5 or newer, so install Node.js 22 or later before continuing.
+
+Install OpenCodex without `sudo` from a user-owned Node.js installation:
+
+```bash
+npm install --global @bitkyc08/opencodex
+ocx init
+```
+
+The bridge service looks for `ocx` at `~/.local/bin/ocx` and `/opt/homebrew/bin/ocx`. If `command -v ocx` prints another path, link it into `~/.local/bin`:
+
+```bash
+mkdir -p ~/.local/bin
+if [[ "$(command -v ocx)" != "$HOME/.local/bin/ocx" ]]; then
+  ln -sf "$(command -v ocx)" ~/.local/bin/ocx
+fi
+```
+
+`ocx init` opens the interactive provider setup. You can also open the dashboard and add or sign in to a provider there:
+
+```bash
+ocx gui
+```
+
+OAuth-backed providers can also be connected from the terminal:
+
+```bash
+ocx login <provider>
+```
+
+Install OpenCodex as a login service, then check it:
+
+```bash
+ocx service install
+ocx service status
+```
+
+OpenCodex listens on `http://127.0.0.1:10100` by default. Confirm that its model endpoint responds:
+
+```bash
+curl http://127.0.0.1:10100/v1/models
+```
+
+If you configured OpenCodex with a service API token, include that token:
+
+```bash
+curl \
+  --header "Authorization: Bearer $(cat ~/.opencodex/service-api-token)" \
+  http://127.0.0.1:10100/v1/models
+```
+
+See the [OpenCodex documentation](https://lidge-jun.github.io/opencodex/) for provider-specific login and model configuration.
+
+### 2. Create a Cloudflare Tunnel
+
+Cursor requires an HTTPS custom OpenAI endpoint. A [Cloudflare Tunnel](https://developers.cloudflare.com/tunnel/) can publish the bridge on HTTPS without opening an inbound port on your router.
+
+Add your domain to Cloudflare and point its nameservers to Cloudflare. Then install `cloudflared` on the Mac that runs OpenCodex and Cursor:
+
+```bash
+brew install cloudflared
+cloudflared tunnel login
+```
+
+The login command opens Cloudflare in your browser and writes `~/.cloudflared/cert.pem`. Create a [locally-managed named tunnel](https://developers.cloudflare.com/tunnel/advanced/local-management/create-local-tunnel/):
+
+```bash
+cloudflared tunnel create ocx-cursor
+cloudflared tunnel list
+```
+
+Copy the tunnel UUID printed by the command. It also creates a credentials file named `<TUNNEL_UUID>.json` under `~/.cloudflared`.
+
+Create `~/.cloudflared/config.yml`. Replace the UUID, macOS username, and hostname in this example:
 
 ```yaml
 # ~/.cloudflared/config.yml
-tunnel: YOUR_TUNNEL_ID
-credentials-file: /Users/YOU/.cloudflared/YOUR_TUNNEL_ID.json
+tunnel: YOUR_TUNNEL_UUID
+credentials-file: /Users/YOUR_MACOS_USERNAME/.cloudflared/YOUR_TUNNEL_UUID.json
 
 ingress:
   - hostname: cursor-api.example.com
@@ -31,18 +105,54 @@ ingress:
   - service: http_status:404
 ```
 
-Create the DNS route and run the tunnel:
+Create the DNS CNAME for the public hostname. The command adds the record to Cloudflare, so you do not need to create it separately in the dashboard:
 
 ```bash
-cloudflared tunnel route dns YOUR_TUNNEL_NAME cursor-api.example.com
-cloudflared tunnel run YOUR_TUNNEL_NAME
+cloudflared tunnel route dns ocx-cursor cursor-api.example.com
 ```
 
-The package does not install or manage the tunnel.
+Validate the configuration and start the tunnel in the foreground:
 
-## Install
+```bash
+cloudflared tunnel ingress validate
+cloudflared tunnel ingress rule https://cursor-api.example.com
+cloudflared tunnel run ocx-cursor
+```
 
-Quit Cursor, confirm that OpenCodex is running, then run:
+The public hostname returns `502 Bad Gateway` until the bridge is installed in the next step. Keep this terminal open while testing.
+
+For login-time startup on macOS, stop the foreground process and install the `cloudflared` launch agent:
+
+```bash
+cloudflared service install
+```
+
+Use `sudo cloudflared service install` only if you want a system launch daemon that starts at boot. That mode reads its configuration from `/etc/cloudflared`, not your home directory. See Cloudflare's [macOS service guide](https://developers.cloudflare.com/tunnel/advanced/local-management/as-a-service/macos/) for the required file locations.
+
+This package does not create, modify, or remove the Cloudflare Tunnel.
+
+### 3. Install the Cursor bridge
+
+Quit Cursor completely, confirm that OpenCodex is running, then initialize the bridge:
+
+```bash
+npx ocx-cursor init
+```
+
+Enter the Cloudflare Tunnel hostname when prompted. The `https://` prefix and `/v1` suffix are optional:
+
+```text
+Cloudflare Tunnel URL (for example, https://cursor-api.example.com): https://cursor-api.example.com
+```
+
+The installer starts the local bridge and tests two routes through Cloudflare before it changes Cursor:
+
+- `GET /healthz` confirms that the hostname reaches this bridge.
+- Authenticated `GET /v1/models` confirms that request headers reach the bridge and OpenCodex responds.
+
+If either check fails, `init` stops before writing Cursor's API settings. The local bridge stays running so you can fix the tunnel and rerun the command.
+
+For scripts and unattended setup, pass the URL directly:
 
 ```bash
 npx ocx-cursor init \
@@ -52,10 +162,11 @@ npx ocx-cursor init \
 `init` performs these actions:
 
 1. Generates a gateway API key in `~/.opencodex/cursor-bridge/secret`.
-2. Stores the key in Cursor with macOS Safe Storage encryption.
-3. Registers the HTTPS URL as Cursor's OpenAI base URL.
-4. Installs the `com.opencodex.cursor-bridge` LaunchAgent.
-5. Adds active OpenCodex models to Cursor under `opencodex/*`.
+2. Installs the `com.opencodex.cursor-bridge` LaunchAgent.
+3. Tests the Cloudflare Tunnel and OpenCodex model endpoint.
+4. Stores the key in Cursor with macOS Safe Storage encryption.
+5. Registers the HTTPS URL as Cursor's OpenAI base URL.
+6. Adds active OpenCodex models to Cursor under `opencodex/*`.
 
 The installer links `ocx-cursor` into `~/.local/bin`. Add that directory to `PATH` if your shell does not include it:
 
@@ -63,13 +174,35 @@ The installer links `ocx-cursor` into `~/.local/bin`. Add that directory to `PAT
 export PATH="$HOME/.local/bin:$PATH"
 ```
 
-Open Cursor after `init` finishes. Models with known reasoning controls show an effort value in the picker. Use `Shift+Command+/` to cycle it.
+Check the local gateway and public hostname before opening Cursor:
+
+```bash
+ocx-cursor status
+curl https://cursor-api.example.com/healthz
+```
+
+The status output should show `Service: running` and `Gateway: healthy`. The public health endpoint should return JSON with `"status":"ok"`.
+
+Open Cursor after both checks pass. Models with known reasoning controls show an effort value in the picker. Use `Shift+Command+/` to cycle it.
+
+## How requests are routed
+
+```text
+Cursor
+  -> https://cursor-api.example.com/v1
+  -> Cloudflare Tunnel
+  -> OpenCodex Cursor Bridge on 127.0.0.1:10101
+  -> OpenCodex on 127.0.0.1:10100
+  -> configured provider
+```
+
+The gateway API key is generated during `init` and stored in Cursor with macOS Safe Storage encryption. The bridge requires this bearer token on every `/v1/*` request. Keep the bridge bound to `127.0.0.1`; `cloudflared` can reach it without exposing port `10101` to the local network.
 
 ## Commands
 
 | Command | Purpose |
 | --- | --- |
-| `ocx-cursor init --base-url URL` | Configure Cursor, install the service, and sync models. Cursor must be closed. |
+| `ocx-cursor init [--base-url URL]` | Install the service, prompt for and test the tunnel, configure Cursor, and sync models. Cursor must be closed. |
 | `ocx-cursor install` | Reinstall or restart the LaunchAgent without changing Cursor's API settings. |
 | `ocx-cursor sync` | Refresh the active model catalog. The service queues the update while Cursor runs. |
 | `ocx-cursor status` | Show service health, model count, and pending sync state. |
@@ -94,7 +227,7 @@ Cursor removes custom effort metadata from its database during startup. The Laun
 
 | Variable | Default | Purpose |
 | --- | --- | --- |
-| `OCX_CURSOR_BASE_URL` | Stored Cursor URL | HTTPS endpoint used by `init` when `--base-url` is absent. |
+| `OCX_CURSOR_BASE_URL` | Stored Cursor URL | Prompt default, or endpoint for non-interactive `init`, when `--base-url` is absent. |
 | `OCX_CURSOR_HOME` | `~/.opencodex/cursor-bridge` | Service state, API key, catalog, and logs. |
 | `OCX_CURSOR_HOST` | `127.0.0.1` | Local gateway bind address. |
 | `OCX_CURSOR_PORT` | `10101` | Local gateway port. |
@@ -109,6 +242,70 @@ The gateway accepts these routes:
 
 The gateway requires its generated bearer token on each `/v1/*` request. It binds to loopback unless you change `OCX_CURSOR_HOST`.
 
+## Troubleshooting
+
+### The public hostname returns 502
+
+The tunnel is running, but it cannot reach the local bridge. Check the bridge and its logs:
+
+```bash
+ocx-cursor status
+tail -n 100 ~/.opencodex/cursor-bridge/service.error.log
+tail -n 100 ~/.opencodex/cursor-bridge/service.log
+```
+
+Confirm that the tunnel ingress points to `http://127.0.0.1:10101`, then restart the bridge if needed:
+
+```bash
+ocx-cursor install
+```
+
+### Cloudflare returns error 1016
+
+The DNS record exists, but no tunnel connector is online. Check the named tunnel and start it:
+
+```bash
+cloudflared tunnel info ocx-cursor
+cloudflared tunnel run ocx-cursor
+```
+
+If you installed the login service, inspect it with:
+
+```bash
+launchctl print "gui/$(id -u)/com.cloudflare.cloudflared"
+```
+
+### Cursor returns 401
+
+Run `init` again while Cursor is closed. It preserves the bridge key, retests the tunnel, and writes the matching encrypted value back to Cursor:
+
+```bash
+npx ocx-cursor init
+```
+
+### Models or effort options are missing
+
+Cursor must be closed before its local model database can be changed. Quit Cursor and run:
+
+```bash
+ocx-cursor sync
+ocx-cursor status
+```
+
+If the status shows a pending sync, wait until every Cursor Helper process has exited. The service applies the queued catalog automatically.
+
+### OpenCodex models cannot be loaded
+
+Check OpenCodex first:
+
+```bash
+ocx status
+ocx models --json
+curl http://127.0.0.1:10100/v1/models
+```
+
+If `ocx models --json` works in your shell but fails in the bridge, check that `ocx` is available at `~/.local/bin/ocx` or `/opt/homebrew/bin/ocx`. The macOS LaunchAgent does not load your interactive shell profile.
+
 ## Development
 
 ```bash

package/bin/ocx-cursor.mjs

@@ -2,18 +2,21 @@
 
 import { readFile } from "node:fs/promises";
 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 } from "../src/install.mjs";
 import { cursorOpenAIBaseUrl, pendingFile } from "../src/paths.mjs";
 import { runService } from "../src/service.mjs";
+import { normalizeBaseUrl, testTunnel } from "../src/setup.mjs";
 import { loadCatalogSnapshot, syncNow } from "../src/sync.mjs";
 
 const usage = `OpenCodex Cursor Bridge
 
 Usage:
-  ocx-cursor init --base-url <https-url>
-                        Configure Cursor, install the service, and sync models
+  ocx-cursor init [--base-url <https-url>]
+                        Install the service, test the tunnel, configure Cursor,
+                        and sync models
   ocx-cursor install    Install and start the macOS companion service
   ocx-cursor sync       Sync active OpenCodex models into Cursor
   ocx-cursor status     Show service and model-sync status
@@ -26,20 +29,21 @@ function argumentValue(name) {
   return index === -1 ? "" : String(process.argv[index + 1] || "");
 }
 
-function normalizedBaseUrl(value) {
-  if (!value) {
-    throw new Error("Pass --base-url https://your-domain.example/v1 or set OCX_CURSOR_BASE_URL");
-  }
-  let url;
+async function requestedBaseUrl() {
+  const supplied = argumentValue("--base-url");
+  const fallback = cursorOpenAIBaseUrl || storedCursorOpenAIBaseUrl();
+  if (supplied) return normalizeBaseUrl(supplied);
+  if (!process.stdin.isTTY || !process.stdout.isTTY) return normalizeBaseUrl(fallback);
+
+  const prompt = fallback
+    ? `Cloudflare Tunnel URL [${fallback}]: `
+    : "Cloudflare Tunnel URL (for example, https://cursor-api.example.com): ";
+  const readline = createInterface({ input: process.stdin, output: process.stdout });
   try {
-    url = new URL(value);
-  } catch {
-    throw new Error(`Invalid Cursor OpenAI base URL: ${value}`);
+    return normalizeBaseUrl((await readline.question(prompt)).trim() || fallback);
+  } finally {
+    readline.close();
   }
-  if (url.protocol !== "https:") throw new Error("Cursor OpenAI base URL must use HTTPS");
-  url.pathname = url.pathname.replace(/\/$/, "");
-  if (!url.pathname.endsWith("/v1")) throw new Error("Cursor OpenAI base URL must end with /v1");
-  return url.toString().replace(/\/$/, "");
 }
 
 async function pendingCount() {
@@ -83,10 +87,18 @@ async function main() {
     if (cursorIsRunning()) {
       throw new Error("Quit Cursor before running ocx-cursor init so model variants and effort selectors can be applied");
     }
-    const baseUrl = normalizedBaseUrl(
-      argumentValue("--base-url") || cursorOpenAIBaseUrl || storedCursorOpenAIBaseUrl(),
-    );
+    const baseUrl = await requestedBaseUrl();
     const prepared = await prepareInstallSecret();
+    const installed = await installService();
+    process.stdout.write(`Installed ${installed.launchAgentFile} (API key ${prepared.secretStatus}).\nCLI: ${installed.cliLinkFile}\n`);
+    process.stdout.write(`Testing Cloudflare Tunnel: ${new URL(baseUrl).origin}\n`);
+    let tunnel;
+    try {
+      tunnel = await testTunnel(baseUrl, prepared.secret);
+    } catch (error) {
+      throw new Error(`${error.message}\nThe bridge service is running locally. Fix the tunnel and rerun ocx-cursor init.`);
+    }
+    process.stdout.write(`Tunnel is ready (${tunnel.modelCount} models reachable).\n`);
     const configured = await configureCursorOpenAI({
       secret: prepared.secret,
       baseUrl,
@@ -94,8 +106,6 @@ async function main() {
     process.stdout.write(configured.changed
       ? `Configured Cursor OpenAI endpoint: ${baseUrl}\nBackup: ${configured.backupPath}\n`
       : `Cursor OpenAI endpoint is already configured: ${baseUrl}\n`);
-    const installed = await installService();
-    process.stdout.write(`Installed ${installed.launchAgentFile} (API key ${installed.secretStatus}).\nCLI: ${installed.cliLinkFile}\n`);
     printSync(await syncNow());
     return;
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ocx-cursor",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "OpenCodex companion service for Cursor custom models",
   "keywords": [
     "opencodex",

package/src/setup.mjs

@@ -0,0 +1,77 @@
+export function normalizeBaseUrl(value) {
+  if (!value) {
+    throw new Error("Enter your Cloudflare Tunnel URL or pass --base-url https://your-domain.example/v1");
+  }
+
+  const candidate = value.includes("://") ? value : `https://${value}`;
+  let url;
+  try {
+    url = new URL(candidate);
+  } catch {
+    throw new Error(`Invalid Cloudflare Tunnel URL: ${value}`);
+  }
+
+  if (url.protocol !== "https:") throw new Error("Cloudflare Tunnel URL must use HTTPS");
+  if (url.username || url.password || url.search || url.hash) {
+    throw new Error("Cloudflare Tunnel URL cannot contain credentials, a query, or a fragment");
+  }
+
+  const pathname = url.pathname.replace(/\/+$/, "");
+  if (pathname && pathname !== "/v1") {
+    throw new Error("Cloudflare Tunnel URL must be a hostname or end with /v1");
+  }
+  url.pathname = "/v1";
+  return url.toString().replace(/\/$/, "");
+}
+
+async function checkedJson(fetchImpl, url, options, label) {
+  let response;
+  try {
+    response = await fetchImpl(url, {
+      ...options,
+      signal: options?.signal || AbortSignal.timeout(10_000),
+    });
+  } catch (error) {
+    throw new Error(`${label} failed for ${url}: ${error.message}`);
+  }
+
+  if (!response.ok) throw new Error(`${label} returned HTTP ${response.status} for ${url}`);
+  try {
+    return await response.json();
+  } catch {
+    throw new Error(`${label} returned invalid JSON from ${url}`);
+  }
+}
+
+export async function testTunnel(baseUrl, secret, options = {}) {
+  baseUrl = normalizeBaseUrl(baseUrl);
+  const fetchImpl = options.fetchImpl || fetch;
+  const origin = new URL(baseUrl).origin;
+  const attempts = options.healthAttempts || 10;
+  let health;
+  let healthError;
+  for (let attempt = 0; attempt < attempts; attempt += 1) {
+    try {
+      health = await checkedJson(fetchImpl, `${origin}/healthz`, {}, "Tunnel health check");
+      break;
+    } catch (error) {
+      healthError = error;
+      if (attempt + 1 < attempts) {
+        await new Promise((resolve) => setTimeout(resolve, options.retryDelayMs ?? 500));
+      }
+    }
+  }
+  if (!health) throw healthError;
+  if (health?.service !== "opencodex-cursor-bridge" || health?.status !== "ok") {
+    throw new Error(`Tunnel health check reached an unexpected service at ${origin}/healthz`);
+  }
+
+  const models = await checkedJson(fetchImpl, `${baseUrl}/models`, {
+    headers: { authorization: `Bearer ${secret}` },
+  }, "Tunnel model check");
+  if (!Array.isArray(models?.data)) {
+    throw new Error(`Tunnel model check returned an invalid catalog from ${baseUrl}/models`);
+  }
+
+  return { health, modelCount: models.data.length };
+}