cursor-keys 1.2.2 → 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
@@ -104,14 +106,14 @@ Settings flow one way, main to profiles: `sync` re-copies your main `settings.js
 | `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`        |
+| `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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cursor-keys",
-  "version": "1.2.2",
+  "version": "1.2.3",
   "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

@@ -16,7 +16,7 @@ import {
   loadConfig,
   pickColorForName,
   pickUnusedColor,
-  saveConfig,
+  updateConfig,
   profileStateDb,
 } from "./config.mjs";
 import {
@@ -238,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}`);
 }
@@ -304,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)`,
   );
@@ -360,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;
@@ -371,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;
     }
@@ -601,10 +603,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,6 +616,22 @@ 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, `'\\''`);
 }
@@ -680,10 +698,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 +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}`));
@@ -900,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
  */