cursor-keys 1.2.2 → 1.2.4

package/README.md

@@ -48,6 +48,8 @@ npm install -g cursor-keys
 
 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.
 
+On global install, the companion Cursor extension is linked into `~/.cursor/extensions` automatically and a one-time hint prints (opt out of both: `CURSOR_KEYS_NO_POSTINSTALL=1`). Restart Cursor, then `Cmd+Shift+P` → "cursor-keys: Open Project...".
+
 ## Quick start
 
 ```bash
@@ -69,8 +71,8 @@ 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
+cursor-keys aliases --install     # per-project aliases, `ck` shortcut, zsh tab completion
+cursor-keys install-extension     # status bar + wrong-window guard (auto-linked on global npm install)
 ```
 
 ## How it works
@@ -89,29 +91,30 @@ Settings flow one way, main to profiles: `sync` re-copies your main `settings.js
 
 ## 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 [get <key> · baseUrl [URL]]`           | Show summary, print one value, 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 |
+| 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)                |
+| `color <name> [#hex]`                          | Show or set the project title bar color                         |
+| `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 [get <key> · baseUrl [URL]]`           | Show summary, print one value, 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 (also `ck` shortcut + tab completion) |
-| `completion`                                   | Print zsh tab completion (auto-sourced by `aliases --install`) |
-| `install-extension`                            | Link the Cursor extension into `~/.cursor/extensions`        |
-| `rm <name> [--delete]`                         | Unregister (optionally delete the profile)                   |
+| `completion`                                   | Print zsh tab completion (auto-sourced by `aliases --install`)  |
+| `install-extension`                            | Link the Cursor extension (auto-linked on global npm install)   |
+| `rm <name> [--delete]`                         | Unregister (optionally delete the profile)                      |
 
 `cursor-keys ls` prints registered project names one per line for scripts and tab completion; it is hidden from `--help`.
 
 ## Config
 
-`~/.config/cursor-keys/config.json`:
+`~/.config/cursor-keys/config.json` (writes are atomic and merge-on-save, so overlapping runs never clobber registrations):
 
 ```json
 {

package/bin/cursor-keys.mjs

@@ -27,6 +27,9 @@ function printHelp() {
   console.log(
     "  set-key <name>              Inject the project API key (encrypted)",
   );
+  console.log(
+    "  color <name> [#hex]         Show or set the project title bar color",
+  );
   console.log(
     "  open [name]                 Open Cursor with this project's profile",
   );

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cursor-keys",
-  "version": "1.2.2",
+  "version": "1.2.4",
   "description": "Per-project Cursor profiles so each window uses the correct BYOK API key. Zero dependencies.",
   "type": "module",
   "bin": {

package/scripts/postinstall.mjs

@@ -1,20 +1,56 @@
-// Postinstall hint: prints once on global install, never breaks the install.
+// Postinstall: one-time hint + best-effort companion extension install.
+// Never breaks the install: the whole body is guarded and exits 0.
 // Quiet installs: CURSOR_KEYS_NO_POSTINSTALL=1
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
 try {
   if (process.env.CURSOR_KEYS_NO_POSTINSTALL) process.exit(0);
   const yellow = "\x1b[33m";
   const dim = "\x1b[2m";
   const reset = "\x1b[0m";
+
+  const pkgRoot = path.join(
+    path.dirname(fileURLToPath(import.meta.url)),
+    "..",
+  );
+  const extSrc = path.join(pkgRoot, "extension");
+  const extPkgPath = path.join(extSrc, "package.json");
+  const cursorDir = path.join(os.homedir(), ".cursor");
+
+  // Auto-link the companion extension on global installs when Cursor exists.
+  let extLine = "";
+  const isGlobal = process.env.npm_config_global === "true";
+  if (isGlobal && fs.existsSync(cursorDir) && fs.existsSync(extPkgPath)) {
+    try {
+      const extPkg = JSON.parse(fs.readFileSync(extPkgPath, "utf8"));
+      const extDir = path.join(cursorDir, "extensions");
+      fs.mkdirSync(extDir, { recursive: true });
+      const target = path.join(
+        extDir,
+        `${extPkg.publisher || "lubu"}.${extPkg.name}-${extPkg.version}`,
+      );
+      fs.rmSync(target, { recursive: true, force: true });
+      try {
+        fs.symlinkSync(extSrc, target, "dir");
+      } catch {
+        fs.cpSync(extSrc, target, { recursive: true });
+      }
+      extLine = `\n  Cursor extension linked ${dim}· restart Cursor, then Cmd+Shift+P: "cursor-keys: Open Project..."${reset}`;
+    } catch {
+      extLine = `\n  cursor-keys install-extension   link the Cursor extension (status bar + warnings)`;
+    }
+  }
+
   console.log(`
 ${yellow}cursor-keys installed${reset}
 
   cursor-keys --help              commands
   cursor-keys aliases --install   aliases, 'ck' shortcut, tab completion
   cursor-keys wrap --install      plain 'cursor <path>' picks the profile
-
-Inside Cursor: Cmd+Shift+P then "cursor-keys: Open Project..." after
-'cursor-keys install-extension' (or install 'cursor-keys' from Open VSX).
-
+${extLine}
 ${dim}Quiet installs: CURSOR_KEYS_NO_POSTINSTALL=1${reset}
 `);
 } catch {

package/src/commands.mjs

@@ -13,10 +13,11 @@ import {
   findProjectByPath,
   getConfigValue,
   getProject,
+  isHexColor,
   loadConfig,
   pickColorForName,
   pickUnusedColor,
-  saveConfig,
+  updateConfig,
   profileStateDb,
 } from "./config.mjs";
 import {
@@ -89,6 +90,8 @@ export async function runCommand(argv) {
       return cmdInstallExtension(rest);
     case "set-key":
       return cmdSetKey(rest);
+    case "color":
+      return cmdColor(rest);
     case "clone":
       return cmdClone(rest);
     case "rm":
@@ -238,8 +241,9 @@ async function cmdConfig(args) {
   if (parsed.protocol !== "https:" && parsed.protocol !== "http:") {
     throw new Error(`baseUrl must start with http(s)://: ${value}`);
   }
-  config.baseUrl = value;
-  saveConfig(config);
+  updateConfig((c) => {
+    c.baseUrl = value;
+  });
   console.log(ok(`baseUrl set: ${value}`));
   console.log(`${dim}doctor verifies this per profile.${reset}`);
 }
@@ -304,20 +308,20 @@ async function cmdInit(args) {
     }
   }
 
-  const config = loadConfig();
-  for (const repo of selected) {
-    const name = path.basename(repo);
-    if (config.projects[name]) {
-      console.log(warn(`Skip ${name} (already registered)`));
-      continue;
+  updateConfig((config) => {
+    for (const repo of selected) {
+      const name = path.basename(repo);
+      if (config.projects[name]) {
+        console.log(warn(`Skip ${name} (already registered)`));
+        continue;
+      }
+      config.projects[name] = {
+        path: collapseHome(repo),
+        color: pickColorForName(name),
+      };
+      console.log(ok(`Registered ${name}`));
     }
-    config.projects[name] = {
-      path: collapseHome(repo),
-      color: pickColorForName(name),
-    };
-    console.log(ok(`Registered ${name}`));
-  }
-  saveConfig(config);
+  });
   console.log(
     `\nNext: cursor-keys add <name> --clone main   (creates profile + copies main Cursor settings)`,
   );
@@ -360,10 +364,11 @@ async function cmdAdd(args) {
     flags.color ||
     config.projects[name]?.color ||
     pickUnusedColor(name, usedColors);
-  config.projects[name] = { path: collapseHome(repoPath), color };
-  saveConfig(config);
+  const saved = updateConfig((c) => {
+    c.projects[name] = { path: collapseHome(repoPath), color };
+  });
 
-  const project = getProject(config, name);
+  const project = getProject(saved, name);
   if (!project) throw new Error("Failed to resolve project");
 
   let cloneFrom = null;
@@ -371,7 +376,7 @@ async function cmdAdd(args) {
     if (flags.clone === "main") {
       cloneFrom = mainCursorProfileRoot();
     } else {
-      const donor = getProject(config, flags.clone);
+      const donor = getProject(saved, flags.clone);
       if (!donor) throw new Error(`Unknown clone donor: ${flags.clone}`);
       cloneFrom = donor.profileDir;
     }
@@ -601,10 +606,10 @@ async function cmdAliases(args) {
   }
   fs.writeFileSync(zshrc, content, "utf8");
   console.log(ok(`Updated ${zshrc}`));
-  if (!content.includes("compinit")) {
+  if (!compinitLikelyConfigured(content)) {
     console.log(
       warn(
-        "Note: `compinit` not found in ~/.zshrc. Tab completion needs it; add this line: autoload -Uz compinit && compinit",
+        "Note: tab completion needs compinit. If `cursor-keys open <TAB>` does nothing after sourcing ~/.zshrc, add: autoload -Uz compinit && compinit",
       ),
     );
   }
@@ -614,12 +619,28 @@ function sanitizeAlias(name) {
   return name.replace(/[^a-zA-Z0-9_-]/g, "_");
 }
 
+const COMPINIT_HINT_RE = /compinit|oh-my-zsh|prezto|zinit|antigen|zplug|zimfw/;
+
+/**
+ * Best-effort check that the user's zsh setup loads compinit. Frameworks
+ * (oh-my-zsh, prezto, zinit, ...) run it from sourced files rather than
+ * ~/.zshrc itself, and Warp injects it via shell integration, so a plain
+ * text grep of ~/.zshrc alone gives false positives. Exported for tests.
+ */
+export function compinitLikelyConfigured(
+  zshrcContent,
+  termProgram = process.env.TERM_PROGRAM,
+) {
+  if (COMPINIT_HINT_RE.test(zshrcContent)) return true;
+  return termProgram === "WarpTerminal";
+}
+
 function shellEscapeName(name) {
   return name.replace(/'/g, `'\\''`);
 }
 
 const COMPLETION_COMMANDS =
-  "init add clone set-key open status current config sync doctor aliases wrap install-extension completion ls rm";
+  "init add clone set-key color open status current config sync doctor aliases wrap install-extension completion ls rm";
 
 /**
  * Pure builder for the zsh completion script. Sourced via
@@ -630,7 +651,7 @@ export function completionScript() {
   return `#compdef cursor-keys ckeys ck
 _cursor_keys() {
   local -a projects
-  if (( CURRENT == 3 )) && [[ \${words[2]} == (open|clone|set-key|doctor|sync|rm) ]]; then
+  if (( CURRENT == 3 )) && [[ \${words[2]} == (open|clone|set-key|color|doctor|sync|rm) ]]; then
     projects=(\${(f)"$(cursor-keys ls 2>/dev/null)"})
     _describe 'project' projects
   else
@@ -680,10 +701,10 @@ function installZshrcBlock(startMarker, endMarker, block) {
     content = content.trimEnd() + "\n\n" + block + "\n";
   }
   fs.writeFileSync(zshrc, content, "utf8");
-  if (!content.includes("compinit")) {
+  if (!compinitLikelyConfigured(content)) {
     console.log(
       warn(
-        "Note: `compinit` not found in ~/.zshrc. Tab completion needs it; add this line: autoload -Uz compinit && compinit",
+        "Note: tab completion needs compinit. If `cursor-keys open <TAB>` does nothing after sourcing ~/.zshrc, add: autoload -Uz compinit && compinit",
       ),
     );
   }
@@ -807,12 +828,17 @@ async function cmdInstallExtension() {
     "..",
   );
   const src = path.join(repoRoot, "extension");
-  if (!fs.existsSync(path.join(src, "package.json"))) {
+  const extPkgPath = path.join(src, "package.json");
+  if (!fs.existsSync(extPkgPath)) {
     throw new Error(`Extension source missing: ${src}`);
   }
+  const extPkg = JSON.parse(fs.readFileSync(extPkgPath, "utf8"));
   const extDir = path.join(os.homedir(), ".cursor", "extensions");
   fs.mkdirSync(extDir, { recursive: true });
-  const target = path.join(extDir, "lubu.cursor-keys-1.0.0");
+  const target = path.join(
+    extDir,
+    `${extPkg.publisher || "lubu"}.${extPkg.name}-${extPkg.version}`,
+  );
   fs.rmSync(target, { recursive: true, force: true });
   fs.symlinkSync(src, target, "dir");
   console.log(ok(`Extension linked: ${target}`));
@@ -820,6 +846,39 @@ async function cmdInstallExtension() {
   console.log(`Look for ${bold}$(key) <project>${reset} in the status bar.`);
 }
 
+async function cmdColor(args) {
+  const { flags, positional } = parseFlags(args);
+  if (flags.help) {
+    console.log("Usage: cursor-keys color <name> [#RRGGBB]");
+    console.log("Show or set the project's title bar color.");
+    return;
+  }
+  const name = positional[0];
+  if (!name) throw new Error("Usage: cursor-keys color <name> [#RRGGBB]");
+  const config = loadConfig();
+  const project = getProject(config, name);
+  if (!project) throw new Error(`Unknown project: ${name}. Run cursor-keys init or add.`);
+
+  const hex = positional[1];
+  if (!hex) {
+    console.log(`${blockSwatch(project.color)} ${project.color}`);
+    return;
+  }
+  if (!isHexColor(hex)) {
+    throw new Error(`Invalid color: ${hex} (expected #RRGGBB, e.g. #852e00)`);
+  }
+
+  updateConfig((c) => {
+    if (!c.projects[name]) throw new Error(`Unknown project: ${name}`);
+    c.projects[name].color = hex;
+  });
+  if (fs.existsSync(project.profileDir)) {
+    writeProfileSettings(project.profileDir, name, hex);
+  }
+  console.log(ok(`Color for ${name}: `) + `${blockSwatch(hex)} ${hex}`);
+  console.log(`${dim}Open Cursor windows reload settings automatically.${reset}`);
+}
+
 function promptHidden(question) {
   return new Promise((resolve) => {
     const rl = readline.createInterface({
@@ -900,8 +959,9 @@ async function cmdRm(args) {
   if (!config.projects[name]) throw new Error(`Unknown project: ${name}`);
 
   const p = getProject(config, name);
-  delete config.projects[name];
-  saveConfig(config);
+  updateConfig((c) => {
+    delete c.projects[name];
+  });
   console.log(ok(`Removed ${name} from config`));
 
   if (flags.delete && p) {

package/src/config.mjs

@@ -8,6 +8,15 @@ export const DEFAULT_CONFIG_DIR = path.join(
   "cursor-keys",
 );
 export const CONFIG_FILE = path.join(DEFAULT_CONFIG_DIR, "config.json");
+
+/**
+ * Resolved at call time so tests and scripts can point cursor-keys at a
+ * scratch config via CURSOR_KEYS_CONFIG_FILE.
+ */
+function configFilePath() {
+  const override = process.env.CURSOR_KEYS_CONFIG_FILE;
+  return override ? expandHome(override) : CONFIG_FILE;
+}
 export const DEFAULT_PROFILES_ROOT = path.join(
   os.homedir(),
   ".cursor-profiles",
@@ -15,6 +24,11 @@ export const DEFAULT_PROFILES_ROOT = path.join(
 
 const HEX_COLOR = /^#[0-9a-fA-F]{6}$/;
 
+/** @param {unknown} s */
+export function isHexColor(s) {
+  return typeof s === "string" && HEX_COLOR.test(s);
+}
+
 /** @param {string} p */
 export function expandHome(p) {
   if (!p || typeof p !== "string") return p;
@@ -40,25 +54,38 @@ export function defaultConfig() {
 }
 
 export function loadConfig() {
-  if (!fs.existsSync(CONFIG_FILE)) {
+  const file = configFilePath();
+  if (!fs.existsSync(file)) {
     return defaultConfig();
   }
-  const raw = fs.readFileSync(CONFIG_FILE, "utf8");
+  const raw = fs.readFileSync(file, "utf8");
   const data = JSON.parse(raw);
   return validateConfig(data);
 }
 
 export function saveConfig(config) {
   const validated = validateConfig(config);
-  fs.mkdirSync(DEFAULT_CONFIG_DIR, { recursive: true });
-  fs.writeFileSync(
-    CONFIG_FILE,
-    JSON.stringify(validated, null, 2) + "\n",
-    "utf8",
-  );
+  const file = configFilePath();
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  // Atomic write: a crash or concurrent reader never sees a torn file.
+  const tmp = `${file}.tmp-${process.pid}`;
+  fs.writeFileSync(tmp, JSON.stringify(validated, null, 2) + "\n", "utf8");
+  fs.renameSync(tmp, file);
   return validated;
 }
 
+/**
+ * Load fresh, mutate, save: the only safe way to change config. Keeps the
+ * lost-update window (two concurrent runs dropping each other's projects)
+ * down to the few ms inside this function instead of a whole command run.
+ * @param {(config: ReturnType<typeof loadConfig>) => void} mutate
+ */
+export function updateConfig(mutate) {
+  const config = loadConfig();
+  mutate(config);
+  return saveConfig(config);
+}
+
 /**
  * @param {unknown} data
  */