@cursorx/cli 0.0.3

package/dist/hooks/loaderHook.js

@@ -0,0 +1,558 @@
+/* global URL, Headers, Request, Response, process */
+// CursorX BYOK fetch monkey-patch — installed by T-304 applyPatch().
+// Runs inside Cursor's own runtime (Node ESM in bootstrap-fork.js + main.js,
+// Electron renderer in workbench.desktop.main.js) at module-init time.
+//
+// Contract:
+//   - Intercepts ONLY requests targeting BYOK_HOSTS (Cursor's chat/Tab/agent endpoints
+//     per spike final §2.2). Rewrites URL to ${CURSORX_ROUTER_URL}/<path> + adds
+//     X-CursorX-Original-Host header. Body, method, and ALL other headers are forwarded
+//     untouched — the Router's adapter layer is responsible for re-signing.
+//   - For every other host (cursor.com auth, api3.cursor.sh metrics, repo42, *.updates,
+//     and any non-Cursor origin) → STRICT PASSTHROUGH. Authorization / X-Api-Key / body
+//     are never read, copied, or logged. (security.md §5 / spike §2.4 red line.)
+//   - If CURSORX_ROUTER_URL is unset AND ~/.cursorx/runtime.json has no port → passthrough.
+//     Fail-open at the patch layer is the SAFE direction here: it preserves Cursor's
+//     normal behavior; intercept-failure is the user-visible signal.
+//   - T-307 BYOK switch: if Router wrote `byok:false` to runtime.json (snapshot of
+//     routes.json), strict passthrough for ALL hosts (including BYOK_HOSTS). Default
+//     (byok absent OR true) ⇒ intercept BYOK_HOSTS normally. v0.1 limitation: hook
+//     reads runtime.json ONCE at first fetch (cached for process lifetime); toggling
+//     BYOK from Extension takes effect on NEXT Cursor restart — consistent with RQ-01
+//     (byok=false ≡ patchStatus=paused).
+//   - T-308 Router URL: falls back to `http://127.0.0.1:${runtime.json.port}` derived
+//     from the Router's startup-time runtime.json snapshot when env / globalThis are unset.
+//
+// Cross-context notes:
+//   - File is plain ESM `.js`; Cursor's package.json declares "type":"module" so this
+//     loads in both Node and renderer contexts. No bundler / transpile step.
+//   - Idempotent install: globalThis.__CURSORX_FETCH_PATCHED__ guards double-wrap.
+//   - All Node built-ins lazy-loaded via dynamic require under try/catch so the hook
+//     never throws into Cursor's stack if a context (e.g. renderer with sandbox on)
+//     forbids fs access.
+
+const BYOK_HOSTS = new Set([
+  // Spike final §2.2 — Cursor BYOK-eligible upstream hosts.
+  // (Minify variable names like XBt/Ssc/CFr/Csc/kFr/Q9p drift across Cursor versions —
+  //  see T-304-P2 spike 2026-05-24 §2; we route by hostname Set, not byte offset.)
+  "api2.cursor.sh", // chat
+  "api4.cursor.sh", // Cursor Tab / autocomplete
+  "agent.api5.cursor.sh", // Agent main
+  "agentn.api5.cursor.sh", // Agent backup
+  "agent-gcpp-uswest.api5.cursor.sh", // Agent region
+]);
+
+// Paths under BYOK hosts that MUST passthrough — Squirrel updates and any future
+// non-BYOK endpoint colocated on a BYOK host.
+const PASSTHROUGH_PATH_PATTERNS = [
+  /^\/updates(\/|$)/, // Squirrel auto-update (spike §2.4)
+];
+
+// T-401 — Path matcher for Cursor's model-list RPC. Phase A grep found
+// `aiserver.v1.AvailableModelsResponse` protobuf + `_setAvailableModels` setter +
+// `refreshAPIKeyModels` caller; Phase B sandbox capture confirmed all aiserver.v1
+// RPCs use POST + application/json (NOT protobuf binary). The actual model-list
+// RPC service/method name is dynamic-concatenated and not statically grep-able;
+// we cover plausible names with a permissive matcher and ALSO fall open if the
+// response body doesn't look like AvailableModelsResponse (§wrapModelListResponse).
+//
+// Patterns covered:
+//   /aiserver.v1.AiSettingsService/GetAvailableModels
+//   /aiserver.v1.AiSettingsService/RefreshAvailableModels
+//   /aiserver.v1.AiSettingsService/ListModels
+//   /aiserver.v1.SettingsService/GetAvailableModels
+//   /aiserver.v1.ModelService/ListModels
+//   /aiserver.v1.ModelService/GetModels
+const MODEL_LIST_PATH_RE =
+  /^\/aiserver\.v1\.[A-Za-z0-9_]*(?:Settings|Model|Ai)[A-Za-z0-9_]*Service\/[A-Za-z0-9_]*(?:Available|List|Get)[A-Za-z0-9_]*Models?$/;
+
+// T-307 / T-308 — lazy-loaded runtime.json reader (async to stay safe across
+// Cursor's three runtime contexts — Node ESM bootstrap-fork.js + main.js, and
+// the Electron renderer workbench.desktop.main.js — using dynamic `import()` so
+// `node:fs/promises` etc. resolve only when the runtime supports them).
+// Cached forever on first call (process-lifetime). Read failure ⇒ null cache.
+// We deliberately do NOT watch the file: Cursor runtime is not a place to
+// install fs.watch; toggling BYOK in Extension requires Cursor restart, which
+// matches RQ-01 (byok=false ≡ patchStatus=paused, an explicit restart paradigm).
+let _runtimeCache; // { port?: number, byok?: boolean } | null | undefined
+async function readRuntimeOnce() {
+  if (_runtimeCache !== undefined) return _runtimeCache;
+  _runtimeCache = null;
+  try {
+    const fs = await import("node:fs/promises");
+    let file;
+    // Test seam: vitest sets this to a fixture path so we can assert read
+    // semantics without touching the user's real ~/.cursorx/runtime.json.
+    if (
+      typeof globalThis !== "undefined" &&
+      typeof globalThis.__CURSORX_RUNTIME_FILE_FOR_TESTS__ === "string"
+    ) {
+      file = globalThis.__CURSORX_RUNTIME_FILE_FOR_TESTS__;
+    } else {
+      const os = await import("node:os");
+      const path = await import("node:path");
+      file = path.join(os.homedir(), ".cursorx", "runtime.json");
+    }
+    const raw = await fs.readFile(file, "utf-8");
+    const parsed = JSON.parse(raw);
+    if (parsed && typeof parsed === "object") {
+      const out = {};
+      if (typeof parsed.port === "number") out.port = parsed.port;
+      if (typeof parsed.byok === "boolean") out.byok = parsed.byok;
+      _runtimeCache = out;
+    }
+  } catch {
+    // ENOENT / parse fail / permission / dynamic-import-failed ⇒ null cache;
+    // getters fall open.
+  }
+  return _runtimeCache;
+}
+
+async function getRouterUrl() {
+  // Cursor's renderer also exposes process.env (Electron contextIsolation off by default
+  // in Cursor 3.2.16; if Cursor flips this on a future version, globalThis fallback fires).
+  try {
+    if (
+      typeof process !== "undefined" &&
+      process &&
+      process.env &&
+      typeof process.env.CURSORX_ROUTER_URL === "string" &&
+      process.env.CURSORX_ROUTER_URL.length > 0
+    ) {
+      return process.env.CURSORX_ROUTER_URL;
+    }
+  } catch {
+    /* renderer-context process access may throw under sandbox; fall through */
+  }
+  try {
+    if (
+      typeof globalThis !== "undefined" &&
+      typeof globalThis.__CURSORX_ROUTER_URL__ === "string" &&
+      globalThis.__CURSORX_ROUTER_URL__.length > 0
+    ) {
+      return globalThis.__CURSORX_ROUTER_URL__;
+    }
+  } catch {
+    /* defensive */
+  }
+  // T-308 — fall back to runtime.json port snapshot written by Router at startup.
+  const runtime = await readRuntimeOnce();
+  if (runtime && typeof runtime.port === "number" && runtime.port > 0) {
+    return `http://127.0.0.1:${runtime.port}`;
+  }
+  return null;
+}
+
+// T-307 — explicit BYOK toggle (false ⇒ strict passthrough; absent / true ⇒ intercept).
+// Fallback chain: env → globalThis → runtime.json. Default = true (fail-open).
+async function isByokEnabled() {
+  try {
+    if (
+      typeof process !== "undefined" &&
+      process &&
+      process.env &&
+      typeof process.env.CURSORX_BYOK_ENABLED === "string"
+    ) {
+      const v = process.env.CURSORX_BYOK_ENABLED.toLowerCase();
+      if (v === "false" || v === "0") return false;
+      if (v === "true" || v === "1") return true;
+    }
+  } catch {
+    /* defensive */
+  }
+  try {
+    if (
+      typeof globalThis !== "undefined" &&
+      typeof globalThis.__CURSORX_BYOK_ENABLED__ === "boolean"
+    ) {
+      return globalThis.__CURSORX_BYOK_ENABLED__;
+    }
+  } catch {
+    /* defensive */
+  }
+  const runtime = await readRuntimeOnce();
+  if (runtime && typeof runtime.byok === "boolean") return runtime.byok;
+  return true; // Fail-open: when unknown, behave as if BYOK is on.
+}
+
+function shouldIntercept(urlObj) {
+  if (!BYOK_HOSTS.has(urlObj.hostname)) return false;
+  for (const pattern of PASSTHROUGH_PATH_PATTERNS) {
+    if (pattern.test(urlObj.pathname)) return false;
+  }
+  return true;
+}
+
+// T-401 — matchesModelListPath: per the spike Phase B finding, model-list RPC
+// returns AvailableModelsResponse over POST + application/json. Static grep
+// can't pin the exact service/method (dynamic-concatenated), so we cover the
+// plausible name space and combine with a response-shape guard downstream.
+function matchesModelListPath(pathname) {
+  if (typeof pathname !== "string") return false;
+  return MODEL_LIST_PATH_RE.test(pathname);
+}
+
+// T-401 / T-402 — cursorXModelToCursorDetails: map a CursorX Model (FR-31 9
+// fields: id / apiModel / displayName / shortName / providerId /
+// contextTokenLimit / autoContextMaxTokens / capabilities / defaultOn) to the
+// Cursor AvailableModels ModelDetails JSON shape. The shape is reverse-engineered
+// from Cursor 3.5.x bundled `tBt` hardcoded fallback array (Phase A §2.3) and
+// `workbench.desktop.main.js` minified ModelDetails class field decls
+// (T-402 Phase A 2026-05-24 read-only grep). Notes:
+//   - `name` ← `id` (Cursor uses `name` as the unique model identifier).
+//   - `serverModelName` ← `apiModel` (string Cursor passes through to upstream).
+//   - `isUserAdded: true` is the keystone — without it Cursor's
+//     getValidatedDefaultModel may treat the injected model as a stale default
+//     and prune it (Phase A grep showed `userAddedModels` is the recognized
+//     extension surface for user-supplied models).
+//   - `supportsMaxMode` defaults false — `maxMode` is Cursor internal and PRD
+//     §7 doesn't declare it for v0.1; `supportsNonMaxMode: true` keeps the
+//     injected model selectable in the model picker.
+//   - T-402 (FR-32 2026-05-24): capability field map (caps.* → Cursor flag):
+//     agent → supportsAgent, cmdK → supportsCmdK, plan → supportsPlanMode,
+//     thinking → supportsThinking, images → supportsImages,
+//     sandboxing → supportsSandboxing. Cursor's bundled defaults (tBt):
+//     supportsAgent/PlanMode/Sandboxing/Images=true, CmdK/Thinking=false. We
+//     always emit explicit booleans (`=== true` gate) so missing fields fall
+//     to false rather than inheriting tBt's "true" defaults — this keeps the
+//     injected model's behavior consistent with what the user declared in
+//     providers.json (UI source of truth).
+//   - RQ-03 decision: thinking/images/sandboxing capabilities are SCHEMA-ONLY
+//     in v0.1 from the Router/Adapter perspective (no special routing); they
+//     still map to Cursor's protocol flags here because Cursor's UI consumes
+//     these flags directly (e.g. supportsCmdK gates the Cmd+K entry visibility
+//     per workbench.desktop.main.js pruning logic). v0.2 work (FR-77) will
+//     extend Router/Adapter behavior, not this mapping.
+function cursorXModelToCursorDetails(model) {
+  const caps =
+    model && typeof model.capabilities === "object" && model.capabilities
+      ? model.capabilities
+      : {};
+  return {
+    name: String(model.id),
+    serverModelName: String(model.apiModel),
+    clientDisplayName: String(model.displayName),
+    inputboxShortModelName: String(model.shortName),
+    defaultOn: model.defaultOn === true,
+    supportsAgent: caps.agent === true,
+    supportsCmdK: caps.cmdK === true,
+    supportsPlanMode: caps.plan === true,
+    supportsSandboxing: caps.sandboxing === true,
+    supportsThinking: caps.thinking === true,
+    supportsImages: caps.images === true,
+    supportsMaxMode: false,
+    supportsNonMaxMode: true,
+    isRecommendedForBackgroundComposer: false,
+    isUserAdded: true,
+    parameterDefinitions: [],
+    variants: [],
+    legacySlugs: [],
+    idAliases: [],
+  };
+}
+
+// T-401 — wrapModelListResponse: take Cursor's upstream AvailableModelsResponse
+// JSON and merge in CursorX-defined models. Fail-open at every step: if the
+// response shape doesn't match what we expect, or any step throws, we return
+// the original response untouched so Cursor's model picker continues working
+// (Cursor will fall back to its hardcoded `tBt` defaults + upstream models).
+async function wrapModelListResponse(response, cursorXModels) {
+  if (
+    !response ||
+    typeof response !== "object" ||
+    typeof response.status !== "number"
+  ) {
+    return response;
+  }
+  if (response.status < 200 || response.status >= 300) return response;
+  if (!Array.isArray(cursorXModels) || cursorXModels.length === 0)
+    return response;
+
+  let contentType;
+  try {
+    contentType = response.headers?.get?.("content-type");
+  } catch {
+    return response;
+  }
+  if (!/application\/json/i.test(contentType || "")) return response;
+
+  let originalBody;
+  try {
+    originalBody = await response.clone().json();
+  } catch {
+    return response;
+  }
+  if (!originalBody || typeof originalBody !== "object") return response;
+
+  // Shape guard: AvailableModelsResponse has models[] and model_names[]
+  // (Phase A §2.2 proto descriptor). If either is missing, this is NOT the
+  // model-list RPC despite the URL match — passthrough.
+  if (
+    !Array.isArray(originalBody.models) ||
+    !Array.isArray(originalBody.model_names)
+  ) {
+    return response;
+  }
+
+  const existingNames = new Set();
+  for (const m of originalBody.models) {
+    if (m && typeof m === "object" && typeof m.name === "string") {
+      existingNames.add(m.name);
+    }
+  }
+
+  const injectedDetails = [];
+  const injectedNames = [];
+  for (const model of cursorXModels) {
+    if (
+      !model ||
+      typeof model !== "object" ||
+      typeof model.id !== "string" ||
+      typeof model.apiModel !== "string" ||
+      typeof model.displayName !== "string" ||
+      typeof model.shortName !== "string"
+    ) {
+      continue;
+    }
+    if (existingNames.has(model.id)) continue;
+    try {
+      const details = cursorXModelToCursorDetails(model);
+      injectedDetails.push(details);
+      injectedNames.push(model.id);
+      existingNames.add(model.id);
+    } catch {
+      // per-model fail-open: skip but keep going.
+    }
+  }
+
+  if (injectedDetails.length === 0) return response;
+
+  const patched = {
+    ...originalBody,
+    models: [...originalBody.models, ...injectedDetails],
+    model_names: [...originalBody.model_names, ...injectedNames],
+  };
+
+  let json;
+  try {
+    json = JSON.stringify(patched);
+  } catch {
+    return response;
+  }
+
+  // Rebuild Response: keep status / preserve other headers; drop
+  // content-length so the runtime recomputes against the new body.
+  let headers;
+  try {
+    headers = new Headers(response.headers);
+    headers.delete("content-length");
+    headers.delete("content-encoding"); // body is now plain JSON, not whatever upstream encoded
+  } catch {
+    return response;
+  }
+
+  try {
+    return new Response(json, {
+      status: response.status,
+      statusText: response.statusText,
+      headers,
+    });
+  } catch {
+    return response;
+  }
+}
+
+// T-401 — fetchCursorXModels: pull the CursorX-defined models from the local
+// Router's GET /models endpoint. Uses `realFetch` (NOT our patched fetch) to
+// avoid recursing into our own interception logic. Fail-open at every step.
+async function fetchCursorXModels(realFetch) {
+  const routerUrl = await getRouterUrl();
+  if (!routerUrl) return null;
+
+  let normalizedRouter;
+  try {
+    normalizedRouter = routerUrl.replace(/\/+$/, "");
+  } catch {
+    return null;
+  }
+
+  let resp;
+  try {
+    resp = await realFetch(normalizedRouter + "/models", {
+      method: "GET",
+      headers: { Accept: "application/json" },
+    });
+  } catch {
+    return null;
+  }
+
+  if (
+    !resp ||
+    typeof resp.status !== "number" ||
+    resp.status < 200 ||
+    resp.status >= 300
+  ) {
+    return null;
+  }
+
+  let body;
+  try {
+    body = await resp.json();
+  } catch {
+    return null;
+  }
+
+  if (!body || !Array.isArray(body.models)) return null;
+  return body.models;
+}
+
+function rewriteUrl(originalUrlString, routerUrlString) {
+  const orig = new URL(originalUrlString);
+  const router = new URL(routerUrlString);
+  // Preserve path + query exactly; router.origin replaces orig.origin.
+  return new URL(orig.pathname + orig.search, router.origin).toString();
+}
+
+function extractUrlString(input) {
+  if (typeof input === "string") return input;
+  if (input && typeof input === "object") {
+    if (typeof input.url === "string") return input.url;
+    if (input instanceof URL) return input.toString();
+  }
+  return null;
+}
+
+function patchFetch(realFetch) {
+  return async function cursorxFetch(input, init) {
+    // T-307 — BYOK off ⇒ strict passthrough for ALL hosts (including BYOK_HOSTS).
+    // Checked FIRST so we never touch URL parsing / header building when paused.
+    if (!(await isByokEnabled())) return realFetch(input, init);
+
+    const routerUrl = await getRouterUrl();
+    if (!routerUrl) return realFetch(input, init);
+
+    const originalUrl = extractUrlString(input);
+    if (!originalUrl) return realFetch(input, init);
+
+    let urlObj;
+    try {
+      urlObj = new URL(originalUrl);
+    } catch {
+      return realFetch(input, init);
+    }
+
+    if (!shouldIntercept(urlObj)) return realFetch(input, init);
+
+    // T-401 — model-list RPC branch: passthrough request, mutate response
+    // to inject CursorX-defined models. Distinct from chat URL rewrite below
+    // because Cursor expects an AvailableModelsResponse shape, NOT the
+    // Router's GET /models shape. Fail-open at every step.
+    if (matchesModelListPath(urlObj.pathname)) {
+      const upstreamResp = await realFetch(input, init);
+      try {
+        const cursorXModels = await fetchCursorXModels(realFetch);
+        if (cursorXModels) {
+          return await wrapModelListResponse(upstreamResp, cursorXModels);
+        }
+      } catch {
+        // Any failure → return original upstream response untouched.
+      }
+      return upstreamResp;
+    }
+
+    let rewritten;
+    try {
+      rewritten = rewriteUrl(originalUrl, routerUrl);
+    } catch {
+      // Malformed CURSORX_ROUTER_URL → fail-open: passthrough untouched.
+      return realFetch(input, init);
+    }
+
+    // Build headers: preserve original (Authorization included; Router decides handling).
+    let headers;
+    try {
+      headers = new Headers();
+      // Copy from init.headers first (init overrides Request defaults per fetch spec).
+      if (init && init.headers) {
+        const initHeaders = new Headers(init.headers);
+        initHeaders.forEach((v, k) => headers.set(k, v));
+      } else if (input && typeof input === "object" && input.headers) {
+        const reqHeaders = new Headers(input.headers);
+        reqHeaders.forEach((v, k) => headers.set(k, v));
+      }
+      headers.set("X-CursorX-Original-Host", urlObj.hostname);
+    } catch {
+      // Header construction failure → passthrough untouched.
+      return realFetch(input, init);
+    }
+
+    const finalInit = { ...(init || {}), headers };
+
+    if (
+      input &&
+      typeof input === "object" &&
+      typeof input.url === "string" &&
+      typeof Request !== "undefined" &&
+      input instanceof Request
+    ) {
+      // Rebuild Request preserving body/method (clone() is required for streaming bodies).
+      const cloned = input.clone();
+      return realFetch(
+        new Request(rewritten, {
+          method: cloned.method,
+          headers,
+          body: cloned.body,
+          mode: cloned.mode,
+          credentials: cloned.credentials,
+          cache: cloned.cache,
+          redirect: cloned.redirect,
+          referrer: cloned.referrer,
+          integrity: cloned.integrity,
+          keepalive: cloned.keepalive,
+          signal: cloned.signal,
+        }),
+      );
+    }
+
+    return realFetch(rewritten, finalInit);
+  };
+}
+
+// Install — idempotent.
+try {
+  if (
+    typeof globalThis !== "undefined" &&
+    typeof globalThis.fetch === "function" &&
+    !globalThis.__CURSORX_FETCH_PATCHED__
+  ) {
+    const real = globalThis.fetch.bind(globalThis);
+    globalThis.fetch = patchFetch(real);
+    globalThis.__CURSORX_FETCH_PATCHED__ = true;
+  }
+} catch {
+  // Never throw out of the hook — fail-open keeps Cursor's existing behavior intact.
+}
+
+// Exported for unit tests (when imported as a module from vitest); harmless side-effect
+// in Cursor runtime since these are property accesses on `export`, which is a no-op when
+// the file is loaded by Cursor for its side-effect only.
+export const __test__ = {
+  BYOK_HOSTS,
+  PASSTHROUGH_PATH_PATTERNS,
+  MODEL_LIST_PATH_RE,
+  shouldIntercept,
+  rewriteUrl,
+  extractUrlString,
+  patchFetch,
+  getRouterUrl,
+  isByokEnabled,
+  matchesModelListPath,
+  cursorXModelToCursorDetails,
+  wrapModelListResponse,
+  fetchCursorXModels,
+  // Test-only: reset the runtime.json cache so suites can re-trigger reads with
+  // different fixtures. Not part of the production contract.
+  _resetRuntimeCacheForTests: () => {
+    _runtimeCache = undefined;
+  },
+};

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@cursorx/cli",
+  "version": "0.0.3",
+  "description": "Local installer for CursorX — custom models in Cursor with your own API keys, via a 127.0.0.1 router. Unofficial; not affiliated with Cursor.",
+  "license": "SEE LICENSE IN LICENSE",
+  "type": "module",
+  "engines": {
+    "node": ">=20"
+  },
+  "bin": {
+    "cursorx": "./dist/cli.js"
+  },
+  "main": "./dist/cli.js",
+  "files": [
+    "dist/",
+    "vsix/",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "cursor",
+    "openai",
+    "anthropic",
+    "router",
+    "custom-model",
+    "unofficial"
+  ],
+  "dependencies": {
+    "@napi-rs/keyring": "^1.3.0"
+  },
+  "devDependencies": {
+    "esbuild": "^0.24.0",
+    "@cursorx/shared": "0.1.0-dev"
+  },
+  "scripts": {
+    "build": "node build.mjs",
+    "build:release": "node build.mjs --release",
+    "typecheck": "tsc --noEmit",
+    "fetch-vsix": "node scripts/fetch-release-vsix.mjs"
+  }
+}

package/vsix/README.md

@@ -0,0 +1,32 @@
+# Bundled CursorX extension VSIX (T-909 / FR-128~130, plan A)
+
+`cursorx install` installs the CursorX control-panel extension by picking the vsix
+here that matches the user's platform and running
+`<resourcesAppPath>/bin/cursor{.cmd} --install-extension <vsix> --force`.
+
+The extension bundles a native module (`@napi-rs/keyring` → a per-platform `.node`
+binary), so each vsix only works on the OS/arch it was packaged on. CI
+(`.github/workflows/package-vsix.yml`) builds one vsix per platform on a real
+runner of that platform.
+
+**This directory ships inside the npm package** (`package.json` → `files: ["vsix/"]`)
+so install never reaches the network for the extension (security.md §1: zero new
+outbound). It is populated at release time — NOT committed with binaries — by:
+
+```
+pnpm --filter @cursorx/cli fetch-vsix            # latest successful "Package VSIX" run
+pnpm --filter @cursorx/cli fetch-vsix -- --tag v0.0.1   # from a release
+```
+
+Expected files after fetch (3 bundled targets):
+
+- `cursorx-<version>-win32-x64.vsix`
+- `cursorx-<version>-darwin-arm64.vsix`
+- `cursorx-<version>-darwin-x64.vsix`
+
+`darwin-x64` (Intel macOS) is **cross-built** on the arm64 macOS runner — the hosted
+Intel macOS (`macos-13`) runner is unavailable, so CI fetches the official
+`@napi-rs/keyring-darwin-x64` prebuilt via `npm install --os=darwin --cpu=x64`
+(pending Intel real-machine load confirmation). Linux is not bundled — Linux users
+install the vsix manually (Cursor → Install from VSIX). Any platform without a
+bundled vsix degrades to a best-effort warning, never an install failure (FR-129).