cursor-keys 0.0.0-stage → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 L-ubu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,130 @@
-# Temporary Holding Version
+# cursor-keys
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+> Per-project Cursor profiles so every window automatically uses the right BYOK API key. Two windows, two projects, two keys, zero switching.
+
+Cursor stores your OpenAI-compatible API key (Bonzai, LiteLLM, AI Gateway, ...) **once per profile**, not per repo. If you bill five client projects, you either babysit Settings all day or bill the wrong project. `cursor-keys` gives each project its own isolated profile and makes opening, switching, and checking keys automatic.
+
+```
+  ╔═╗┬ ┬┬─┐┌─┐┌─┐┬─┐  ┬┌─┌─┐┬ ┬┌─┐
+  │  │ │├┬┘└─┐│ │├┬┘  ├┴┐├┤ └┬┘└─┐
+  └─┘└─┘┴└─└─┘└─┘┴└─  ┴ ┴└─┘ ┴ └─┘  per-project Cursor API keys
+
+$ cursor-keys status
+
+  Project             | Color    | Windows | Key | Repo
+  --------------------+----------+---------+-----+-------------------------
+  famework-platform-1 | #339af0  | 1       | yes | ~/Projects/famework-platform-1
+  jlr_mss             | #4f8cff  | 0       | no  | ~/Projects/jlr_mss
+  nokia               | #845ef7  | 1       | yes | ~/Projects/nokia-main-cs
+
+$ cursor-keys doctor nokia
+
+  ✓ OpenAI/Bonzai API key row present
+  ✓ Explore subagent overrides present
+  ✓ Base URL (connect.iobonzai.com/cursor) in profile state
+```
+
+## Install
+
+```bash
+npm install -g cursor-keys
+# or from source: git clone https://github.com/L-ubu/cursor-keys && cd cursor-keys && npm link
+```
+
+Requires Node ≥18, the Cursor CLI (`Shell Command: Install 'cursor' in PATH`), and sqlite3 (preinstalled on macOS). Key injection is macOS-only; everything else is cross-platform shaped.
+
+## Quick start
+
+```bash
+# one-time, only if your gateway is not the Bonzai default
+cursor-keys config baseUrl https://your-gateway.example.com/v1
+
+# one-time per project
+cursor-keys add acme --path ~/Projects/acme     # register + create profile
+cursor-keys clone acme                          # inherit sign-in, settings, model config from main Cursor
+cursor-keys set-key acme                        # hidden prompt, key written encrypted (Cursor's own safeStorage)
+
+# daily use (pick your style)
+cursor .                                        # transparent wrapper injects the right profile
+acme                                            # shell alias
+# or Cmd+Shift+P -> "cursor-keys: Open Project..." inside Cursor
+```
+
+One-time extras for the full experience:
+
+```bash
+cursor-keys wrap --install        # plain `cursor <path>` auto-picks the profile
+cursor-keys aliases --install     # per-project shell aliases
+cursor-keys install-extension     # status bar indicator + wrong-window guard
+```
+
+## How it works
+
+One window, one profile, one key. Each project gets an isolated `--user-data-dir` under `~/.cursor-profiles/<name>/`, which is the only way Cursor can hold two API keys at once. Extensions, MCP config, keybindings, and snippets stay shared (symlinked); secrets and sign-in isolate, which is exactly the split you want.
+
+Settings flow one way, main to profiles: `sync` re-copies your main `settings.json` into every profile and re-applies that profile's title bar color on top. `open` does this automatically before every launch, and open windows hot-reload the file, so tweaks in your main Cursor show up everywhere. Changes made inside a profile window are overwritten on the next sync.
+
+`clone` copies your main Cursor state (SQLite backup) so profiles open signed-in with your theme and model config. `set-key` encrypts your project key with Cursor's own safeStorage (Chromium OSCrypt, key from the "Cursor Safe Storage" Keychain item) and writes it into the profile's secret store, round-trip verified. macOS asks for Keychain permission once; click Always Allow.
+
+## "Which key am I on?" in three layers
+
+1. **Title bar color** per project, injected into each profile's settings
+2. **Status bar item** from the companion extension: `$(key) acme` when correct, warning + one-click relaunch when you open a repo in the wrong window
+3. **`cursor-keys status` / `current`** in the terminal
+
+## Commands
+
+| Command                                        | What it does                                                 |
+| ---------------------------------------------- | ------------------------------------------------------------ |
+| `init [--root DIR] [--all]`                    | Discover git repos and register them                         |
+| `add <name> [--path] [--color] [--clone main]` | Create a project profile                                     |
+| `clone <name> [--from main]`                   | Copy sign-in + settings + model config from a donor profile  |
+| `set-key <name> [--key sk-...]`                | Inject the project API key (encrypted, verified)             |
+| `open [name]`                                  | Launch Cursor with the profile (auto-detect from cwd)        |
+| `status`                                       | Projects, colors, running windows, key configured            |
+| `current`                                      | Mapping for the current directory                            |
+| `config [baseUrl [URL]]`                       | Show or set the gateway base URL                             |
+| `sync [name]`                                  | Re-copy main Cursor settings into profiles                   |
+| `doctor [name]`                                | Health checks: key row, base URL, subagent overrides         |
+| `wrap [--install]`                             | zsh function so plain `cursor <path>` auto-picks the profile |
+| `aliases [--install]`                          | Per-project shell aliases                                    |
+| `install-extension`                            | Link the Cursor extension into `~/.cursor/extensions`        |
+| `rm <name> [--delete]`                         | Unregister (optionally delete the profile)                   |
+
+## Config
+
+`~/.config/cursor-keys/config.json`:
+
+```json
+{
+  "profilesRoot": "~/.cursor-profiles",
+  "baseUrl": "https://connect.iobonzai.com/cursor",
+  "projects": {
+    "acme": { "path": "~/Projects/acme", "color": "#4f8cff" }
+  }
+}
+```
+
+`baseUrl` is your gateway's OpenAI-compatible endpoint (Bonzai default; point it at LiteLLM, Vercel AI Gateway, ...). `doctor` verifies it per profile.
+
+## Security
+
+- Keys go **straight into Cursor's own encrypted store** (`secret://cursorAuth/openAIKey`), encrypted with the same safeStorage mechanism Cursor uses. Never in config files, logs, or stdout.
+- `set-key` reads the "Cursor Safe Storage" Keychain item to encrypt, the same key Cursor itself uses. Nothing leaves your machine.
+- `clone` copies `state.vscdb` locally via SQLite backup. The donor can keep running; the target profile window must be closed.
+
+## Known limitations
+
+- A window opened for project A keeps A's key if you open repo B inside it. The extension detects this and offers a one-click relaunch; title bar colors make it visible at a glance.
+- `set-key` is macOS-only (Keychain + OSCrypt). On Windows/Linux, paste the key once in Settings per profile; everything else still works.
+- Explore subagents spawned ad-hoc still use Cursor's built-in model (per Cursor's own limitation), parent agents use your custom models.
+
+## Development
+
+```bash
+npm test    # node --test, zero deps
+```
+
+## License
+
+MIT · [L-ubu](https://github.com/L-ubu)

package/bin/cursor-keys.mjs

@@ -0,0 +1,62 @@
+#!/usr/bin/env node
+
+import { runCommand } from "../src/commands.mjs";
+import { bold, cyan, dim, reset } from "../src/ansi.mjs";
+
+const BANNER = `
+ ${cyan}╔═╗┬ ┬┬─┐┌─┐┌─┐┬─┐  ┬┌─┌─┐┬ ┬┌─┐
+ ${cyan}│  │ │├┬┘└─┐│ │├┬┘  ├┴┐├┤ └┬┘└─┐
+ ${cyan}└─┘└─┘┴└─└─┘└─┘┴└─  ┴ ┴└─┘ ┴ └─┘${dim}  per-project Cursor API keys
+`;
+
+function printHelp() {
+  console.log(BANNER);
+  console.log(`${bold}Usage:${reset} cursor-keys <command> [options]\n`);
+  console.log(`${bold}Commands:${reset}`);
+  console.log(
+    "  init [--root DIR] [--all]   Scan for git repos and register projects",
+  );
+  console.log("  add <name> [options]        Create profile for a project");
+  console.log(
+    "  open [name]                 Open Cursor with this project's profile",
+  );
+  console.log(
+    "  status                      List projects, running windows, key status",
+  );
+  console.log("  current                     Show mapping for cwd");
+  console.log(
+    "  config [baseUrl [URL]]      Show or set config (gateway base URL)",
+  );
+  console.log(
+    "  sync [name]                 Re-copy main Cursor settings into profiles",
+  );
+  console.log(
+    "  doctor [name]               Verify setup for one or all projects",
+  );
+  console.log("  aliases [--install]         Print or install shell aliases");
+  console.log(
+    "  wrap [--install]            Make plain `cursor <path>` auto-pick profile",
+  );
+  console.log(
+    "  install-extension           Link the Cursor extension (status bar + warnings)",
+  );
+  console.log(
+    "  rm <name> [--delete]        Unregister (optionally delete profile dir)",
+  );
+  console.log(
+    "\nRun `cursor-keys <command> --help` for command-specific options.",
+  );
+}
+
+const args = process.argv.slice(2);
+if (args.length === 0 || args[0] === "-h" || args[0] === "--help") {
+  printHelp();
+  process.exit(0);
+}
+
+try {
+  await runCommand(args);
+} catch (e) {
+  console.error(e.message || String(e));
+  process.exit(1);
+}

package/extension/extension.js

@@ -0,0 +1,248 @@
+const vscode = require("vscode");
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+const { spawn } = require("child_process");
+
+const CONFIG_FILE = path.join(
+  os.homedir(),
+  ".config",
+  "cursor-keys",
+  "config.json",
+);
+
+function expandHome(p) {
+  if (!p) return p;
+  if (p === "~") return os.homedir();
+  if (p.startsWith("~/")) return path.join(os.homedir(), p.slice(2));
+  return p;
+}
+
+function loadConfig() {
+  try {
+    return JSON.parse(fs.readFileSync(CONFIG_FILE, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The profile root this window runs in, derived from globalStorageUri:
+ * <profileRoot>/User/globalStorage/<publisher>.<name>
+ */
+function currentProfileRoot(context) {
+  const fsPath = context.globalStorageUri.fsPath;
+  const marker = path.sep + "User" + path.sep + "globalStorage" + path.sep;
+  const idx = fsPath.indexOf(marker);
+  return idx === -1 ? null : fsPath.slice(0, idx);
+}
+
+function projectForFolder(config, folder) {
+  let best = null;
+  let bestLen = 0;
+  for (const [name, entry] of Object.entries(config.projects || {})) {
+    if (!entry || typeof entry.path !== "string") continue;
+    const repo = path.resolve(expandHome(entry.path));
+    if (folder === repo || folder.startsWith(repo + path.sep)) {
+      if (repo.length > bestLen) {
+        best = name;
+        bestLen = repo.length;
+      }
+    }
+  }
+  return best;
+}
+
+function profileDirFor(config, name) {
+  return path.join(expandHome(config.profilesRoot), name);
+}
+
+function findCursorBinary() {
+  // App-bundle CLI first: ~/.local/bin/cursor is a PATH-dependent shim that
+  // fails in the extension host's minimal GUI environment.
+  const candidates = [
+    "/Applications/Cursor.app/Contents/Resources/app/bin/cursor",
+    "/usr/local/bin/cursor",
+    "/opt/homebrew/bin/cursor",
+    path.join(os.homedir(), ".local", "bin", "cursor"),
+  ];
+  for (const c of candidates) {
+    if (fs.existsSync(c)) return c;
+  }
+  return "cursor";
+}
+
+function launch(profileDir, folder) {
+  const bin = findCursorBinary();
+  const child = spawn(
+    bin,
+    ["--user-data-dir", profileDir, "--new-window", folder],
+    { detached: true, stdio: "ignore" },
+  );
+  child.unref();
+}
+
+/** @param {vscode.ExtensionContext} context */
+function activate(context) {
+  const statusBar = vscode.window.createStatusBarItem(
+    vscode.StatusBarAlignment.Left,
+    100,
+  );
+  let warned = false;
+
+  function relaunch(projectName, folder) {
+    const config = loadConfig();
+    if (!config) return;
+    launch(profileDirFor(config, projectName), folder);
+    setTimeout(() => {
+      vscode.commands.executeCommand("workbench.action.closeWindow");
+    }, 1500);
+  }
+
+  function update() {
+    const config = loadConfig();
+    if (!config) {
+      statusBar.hide();
+      return;
+    }
+    const profileRoot = currentProfileRoot(context);
+    if (!profileRoot) {
+      statusBar.hide();
+      return;
+    }
+
+    const folders =
+      vscode.workspace.workspaceFolders?.map((f) => f.uri.fsPath) || [];
+    let expected = null;
+    let expectedFolder = null;
+    for (const f of folders) {
+      const p = projectForFolder(config, f);
+      if (p) {
+        expected = p;
+        expectedFolder = f;
+        break;
+      }
+    }
+
+    const profilesRoot = path.resolve(expandHome(config.profilesRoot));
+    const resolvedRoot = path.resolve(profileRoot);
+    const inManagedProfile =
+      resolvedRoot.startsWith(profilesRoot + path.sep) ||
+      resolvedRoot === profilesRoot;
+    const activeProfileName = inManagedProfile
+      ? path.basename(resolvedRoot)
+      : null;
+
+    if (expected) {
+      const expectedDir = path.resolve(profileDirFor(config, expected));
+      if (resolvedRoot === expectedDir) {
+        statusBar.text = `$(key) ${expected}`;
+        statusBar.tooltip = `cursor-keys: this window bills "${expected}"`;
+        statusBar.backgroundColor = undefined;
+        statusBar.command = "cursor-keys.openProject";
+        statusBar.show();
+        return;
+      }
+
+      statusBar.text = `$(warning) wrong key: expected ${expected}`;
+      statusBar.backgroundColor = new vscode.ThemeColor(
+        "statusBarItem.warningBackground",
+      );
+      statusBar.tooltip = `"${path.basename(expectedFolder)}" belongs to "${expected}", but this window uses ${
+        activeProfileName ? `"${activeProfileName}"` : "the default profile"
+      }. Click to relaunch.`;
+      statusBar.command = "cursor-keys.relaunchHere";
+      statusBar.show();
+
+      if (!warned) {
+        warned = true;
+        vscode.window
+          .showWarningMessage(
+            `cursor-keys: this folder belongs to project "${expected}", but this window uses ${
+              activeProfileName
+                ? `the "${activeProfileName}" profile`
+                : "the default profile"
+            }. API calls would bill the wrong project.`,
+            "Relaunch correctly",
+            "Ignore",
+          )
+          .then((choice) => {
+            if (choice === "Relaunch correctly") {
+              relaunch(expected, expectedFolder);
+            }
+          });
+      }
+      return;
+    }
+
+    if (activeProfileName) {
+      statusBar.text = `$(key) ${activeProfileName}`;
+      statusBar.tooltip = `cursor-keys: window profile "${activeProfileName}" (this folder is not registered)`;
+      statusBar.backgroundColor = undefined;
+      statusBar.command = "cursor-keys.openProject";
+      statusBar.show();
+      return;
+    }
+
+    statusBar.hide();
+  }
+
+  context.subscriptions.push(
+    statusBar,
+    vscode.workspace.onDidChangeWorkspaceFolders(update),
+    vscode.commands.registerCommand("cursor-keys.relaunchHere", () => {
+      const config = loadConfig();
+      if (!config) return;
+      const folders =
+        vscode.workspace.workspaceFolders?.map((f) => f.uri.fsPath) || [];
+      for (const f of folders) {
+        const p = projectForFolder(config, f);
+        if (p) {
+          relaunch(p, f);
+          return;
+        }
+      }
+    }),
+    vscode.commands.registerCommand("cursor-keys.openProject", async () => {
+      const config = loadConfig();
+      if (!config || !config.projects) {
+        vscode.window.showInformationMessage(
+          "cursor-keys: no config found. Run `cursor-keys init` in a terminal.",
+        );
+        return;
+      }
+      const names = Object.keys(config.projects).sort();
+      if (!names.length) {
+        vscode.window.showInformationMessage(
+          "cursor-keys: no projects registered yet.",
+        );
+        return;
+      }
+      const picked = await vscode.window.showQuickPick(
+        names.map((n) => ({
+          label: n,
+          description: config.projects[n].path,
+        })),
+        { placeHolder: "Open project in its own Cursor profile" },
+      );
+      if (!picked) return;
+      launch(
+        profileDirFor(config, picked.label),
+        path.resolve(expandHome(config.projects[picked.label].path)),
+      );
+    }),
+  );
+
+  const watcher = vscode.workspace.createFileSystemWatcher(CONFIG_FILE);
+  context.subscriptions.push(
+    watcher,
+    watcher.onDidChange(update),
+    watcher.onDidCreate(update),
+  );
+
+  update();
+}
+
+function deactivate() {}
+
+module.exports = { activate, deactivate };

package/extension/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "cursor-keys",
+  "displayName": "cursor-keys",
+  "description": "Shows which cursor-keys profile (API key context) this window uses, and warns when a folder is opened in the wrong profile.",
+  "version": "1.0.0",
+  "publisher": "lubu",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/L-ubu/cursor-keys",
+    "directory": "extension"
+  },
+  "engines": {
+    "vscode": "^1.80.0"
+  },
+  "categories": [
+    "Other"
+  ],
+  "activationEvents": [
+    "onStartupFinished"
+  ],
+  "main": "./extension.js",
+  "contributes": {
+    "commands": [
+      {
+        "command": "cursor-keys.openProject",
+        "title": "cursor-keys: Open Project..."
+      },
+      {
+        "command": "cursor-keys.relaunchHere",
+        "title": "cursor-keys: Relaunch This Folder in Its Project Profile"
+      }
+    ]
+  }
+}

package/package.json

@@ -1,6 +1,37 @@
 {
   "name": "cursor-keys",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "description": "Per-project Cursor profiles so each window uses the correct BYOK API key. Zero dependencies.",
+  "type": "module",
+  "bin": {
+    "cursor-keys": "bin/cursor-keys.mjs",
+    "ckeys": "bin/cursor-keys.mjs"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "bin",
+    "src",
+    "extension"
+  ],
+  "keywords": [
+    "cursor",
+    "cli",
+    "api-key",
+    "bonzai",
+    "byok",
+    "developer-tools",
+    "productivity"
+  ],
+  "license": "MIT",
+  "author": "L-ubu (https://github.com/L-ubu)",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/L-ubu/cursor-keys.git"
+  },
+  "scripts": {
+    "test": "node --test",
+    "prepublishOnly": "npm test"
+  }
+}

package/src/ansi.mjs

@@ -0,0 +1,55 @@
+const esc = (n) => `\u001b[${n}m`;
+
+export const reset = esc(0);
+export const bold = esc(1);
+export const dim = esc(2);
+export const red = esc(31);
+export const green = esc(32);
+export const yellow = esc(33);
+export const blue = esc(34);
+export const magenta = esc(35);
+export const cyan = esc(36);
+
+export function colorize(text, code) {
+  return `${code}${text}${reset}`;
+}
+
+export function ok(text) {
+  return colorize(text, green);
+}
+
+export function warn(text) {
+  return colorize(text, yellow);
+}
+
+export function err(text) {
+  return colorize(text, red);
+}
+
+export function padEnd(str, len) {
+  const s = String(str);
+  if (s.length >= len) return s.slice(0, len);
+  return s + " ".repeat(len - s.length);
+}
+
+export function printTable(headers, rows) {
+  const widths = headers.map((h, i) =>
+    Math.max(h.length, ...rows.map((r) => String(r[i] ?? "").length)),
+  );
+  const line = widths.map((w) => "-".repeat(w)).join("-+-");
+  console.log(widths.map((w, i) => padEnd(headers[i], w)).join(" | "));
+  console.log(line);
+  for (const row of rows) {
+    console.log(
+      widths.map((w, i) => padEnd(String(row[i] ?? ""), w)).join(" | "),
+    );
+  }
+}
+
+export function blockSwatch(hex) {
+  if (!hex || !/^#[0-9a-fA-F]{6}$/.test(hex)) return "  ";
+  const r = parseInt(hex.slice(1, 3), 16);
+  const g = parseInt(hex.slice(3, 5), 16);
+  const b = parseInt(hex.slice(5, 7), 16);
+  return `${esc(48)};2;${r};${g};${b}m  ${reset}`;
+}