cursor-keys 1.2.1 → 1.2.3

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
@@ -102,13 +104,16 @@ Settings flow one way, main to profiles: `sync` re-copies your main `settings.js
 | `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`        |
+| `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 (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

@@ -9,12 +9,13 @@ const BANNER = `
  ${yellow}██║     ██║   ██║██████╔╝███████╗██║   ██║██████╔╝    █████╔╝ █████╗   ╚████╔╝ ███████╗
  ${yellow}██║     ██║   ██║██╔══██╗╚════██║██║   ██║██╔══██╗    ██╔═██╗ ██╔══╝    ╚██╔╝  ╚════██║
  ${yellow}╚██████╗╚██████╔╝██║  ██║███████║╚██████╔╝██║  ██║    ██║  ██╗███████╗   ██║   ███████║
- ${yellow} ╚═════╝ ╚═════╝ ╚═╝  ╚═╝╚══════╝ ╚═════╝ ╚═╝  ╚═╝    ╚═╝  ╚═╝╚══════╝   ╚═╝   ╚══════╝${reset}${dim}  per-project Cursor API keys
+ ${yellow} ╚═════╝ ╚═════╝ ╚═╝  ╚═╝╚══════╝ ╚═════╝ ╚═╝  ╚═╝    ╚═╝  ╚═╝╚══════╝   ╚═╝   ╚══════╝${reset}
+  ${dim}per-project Cursor API keys${reset}
 `;
 
 function printHelp() {
   console.log(BANNER);
-  console.log(`${bold}Usage:${reset} cursor-keys <command> [options]\n`);
+  console.log(`${bold}Usage:${reset} cursor-keys (or ck, ckeys) <command> [options]\n`);
   console.log(`${bold}Commands:${reset}`);
   console.log(
     "  init [--root DIR] [--all]   Scan for git repos and register projects",
@@ -42,7 +43,10 @@ function printHelp() {
   console.log(
     "  doctor [name]               Verify setup for one or all projects",
   );
-  console.log("  aliases [--install]         Print or install shell aliases");
+  console.log("  aliases [--install]         Shell aliases (incl. 'ck' + tab completion)");
+  console.log(
+    "  completion                  Print zsh tab completion (auto-sourced by aliases)",
+  );
   console.log(
     "  wrap [--install]            Make plain `cursor <path>` auto-pick profile",
   );

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cursor-keys",
-  "version": "1.2.1",
+  "version": "1.2.3",
   "description": "Per-project Cursor profiles so each window uses the correct BYOK API key. Zero dependencies.",
   "type": "module",
   "bin": {
@@ -13,7 +13,8 @@
   "files": [
     "bin",
     "src",
-    "extension"
+    "extension",
+    "scripts"
   ],
   "keywords": [
     "cursor",
@@ -31,6 +32,7 @@
   },
   "scripts": {
     "test": "node --test",
+    "postinstall": "node scripts/postinstall.mjs",
     "prepublishOnly": "npm test"
   }
 }

package/scripts/postinstall.mjs

@@ -0,0 +1,58 @@
+// 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
+${extLine}
+${dim}Quiet installs: CURSOR_KEYS_NO_POSTINSTALL=1${reset}
+`);
+} catch {
+  /* postinstall must never break install */
+}

package/src/ansi.mjs

@@ -26,15 +26,25 @@ export function err(text) {
   return colorize(text, red);
 }
 
+const ANSI_RE = /\x1b\[[0-9;]*m/g;
+
+export function stripAnsi(s) {
+  return String(s).replace(ANSI_RE, "");
+}
+
 export function padEnd(str, len) {
   const s = String(str);
-  if (s.length >= len) return s.slice(0, len);
-  return s + " ".repeat(len - s.length);
+  const vis = stripAnsi(s).length;
+  if (vis >= len) return s;
+  return s + " ".repeat(len - vis);
 }
 
 export function printTable(headers, rows) {
   const widths = headers.map((h, i) =>
-    Math.max(h.length, ...rows.map((r) => String(r[i] ?? "").length)),
+    Math.max(
+      h.length,
+      ...rows.map((r) => stripAnsi(String(r[i] ?? "")).length),
+    ),
   );
   const line = widths.map((w) => "-".repeat(w)).join("-+-");
   console.log(widths.map((w, i) => padEnd(headers[i], w)).join(" | "));
@@ -51,5 +61,5 @@ export function blockSwatch(hex) {
   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}`;
+  return `\x1b[48;2;${r};${g};${b}m  ${reset}`;
 }

package/src/commands.mjs

@@ -16,7 +16,7 @@ import {
   loadConfig,
   pickColorForName,
   pickUnusedColor,
-  saveConfig,
+  updateConfig,
   profileStateDb,
 } from "./config.mjs";
 import {
@@ -93,6 +93,10 @@ export async function runCommand(argv) {
       return cmdClone(rest);
     case "rm":
       return cmdRm(rest);
+    case "ls":
+      return cmdLs(rest);
+    case "completion":
+      return cmdCompletion(rest);
     default:
       throw new Error(`Unknown command: ${cmd}. Run cursor-keys --help`);
   }
@@ -234,8 +238,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}`);
 }
@@ -300,20 +305,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)`,
   );
@@ -356,10 +361,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;
@@ -367,7 +373,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;
     }
@@ -569,7 +575,13 @@ async function cmdAliases(args) {
   const lines = names.map(
     (n) => `alias ${sanitizeAlias(n)}='cursor-keys open ${shellEscapeName(n)}'`,
   );
-  const block = [ZSHRC_MARKER_START, ...lines, ZSHRC_MARKER_END].join("\n");
+  const block = [
+    ZSHRC_MARKER_START,
+    "alias ck='cursor-keys'",
+    'eval "$(cursor-keys completion)"   # tab completion',
+    ...lines,
+    ZSHRC_MARKER_END,
+  ].join("\n");
 
   if (!flags.install) {
     console.log(block);
@@ -591,16 +603,87 @@ async function cmdAliases(args) {
   }
   fs.writeFileSync(zshrc, content, "utf8");
   console.log(ok(`Updated ${zshrc}`));
+  if (!compinitLikelyConfigured(content)) {
+    console.log(
+      warn(
+        "Note: tab completion needs compinit. If `cursor-keys open <TAB>` does nothing after sourcing ~/.zshrc, add: autoload -Uz compinit && compinit",
+      ),
+    );
+  }
 }
 
 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";
+
+/**
+ * Pure builder for the zsh completion script. Sourced via
+ * `eval "$(cursor-keys completion)"` from the aliases/wrap zshrc blocks,
+ * so updates ship with `npm update` and never go stale on disk.
+ */
+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
+    projects=(\${(f)"$(cursor-keys ls 2>/dev/null)"})
+    _describe 'project' projects
+  else
+    _arguments '1:command:(${COMPLETION_COMMANDS})'
+  fi
+}
+compdef _cursor_keys cursor-keys ckeys ck
+`;
+}
+
+function cmdCompletion(args) {
+  const { flags } = parseFlags(args);
+  if (flags.help) {
+    console.log("Usage: cursor-keys completion");
+    console.log("Prints the zsh tab completion script to stdout.");
+    console.log("Auto-sourced by `cursor-keys aliases --install`; no separate install needed.");
+    return;
+  }
+  process.stdout.write(completionScript());
+}
+
+/**
+ * Hidden command: bare project names, one per line, for completion/scripts.
+ */
+function cmdLs(args) {
+  const { flags } = parseFlags(args);
+  if (flags.help) {
+    console.log("Usage: cursor-keys ls");
+    console.log("Prints registered project names, one per line (for scripts and tab completion).");
+    return;
+  }
+  const config = loadConfig();
+  console.log(Object.keys(config.projects).sort().join("\n"));
+}
+
 function installZshrcBlock(startMarker, endMarker, block) {
   const zshrc = path.join(os.homedir(), ".zshrc");
   let content = fs.existsSync(zshrc) ? fs.readFileSync(zshrc, "utf8") : "";
@@ -615,6 +698,13 @@ function installZshrcBlock(startMarker, endMarker, block) {
     content = content.trimEnd() + "\n\n" + block + "\n";
   }
   fs.writeFileSync(zshrc, content, "utf8");
+  if (!compinitLikelyConfigured(content)) {
+    console.log(
+      warn(
+        "Note: tab completion needs compinit. If `cursor-keys open <TAB>` does nothing after sourcing ~/.zshrc, add: autoload -Uz compinit && compinit",
+      ),
+    );
+  }
   return zshrc;
 }
 
@@ -735,12 +825,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}`));
@@ -828,8 +923,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",
@@ -40,25 +49,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
  */