cursor-keys 1.2.0 → 1.2.2

package/README.md

@@ -102,10 +102,13 @@ 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                                    |
+| `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)                   |
 
+`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`:

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.0",
+  "version": "1.2.2",
   "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,22 @@
+// Postinstall hint: prints once on global install, never breaks the install.
+// Quiet installs: CURSOR_KEYS_NO_POSTINSTALL=1
+try {
+  if (process.env.CURSOR_KEYS_NO_POSTINSTALL) process.exit(0);
+  const yellow = "\x1b[33m";
+  const dim = "\x1b[2m";
+  const reset = "\x1b[0m";
+  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).
+
+${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

@@ -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`);
   }
@@ -569,7 +573,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,6 +601,13 @@ async function cmdAliases(args) {
   }
   fs.writeFileSync(zshrc, content, "utf8");
   console.log(ok(`Updated ${zshrc}`));
+  if (!content.includes("compinit")) {
+    console.log(
+      warn(
+        "Note: `compinit` not found in ~/.zshrc. Tab completion needs it; add this line: autoload -Uz compinit && compinit",
+      ),
+    );
+  }
 }
 
 function sanitizeAlias(name) {
@@ -601,6 +618,54 @@ 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 +680,13 @@ function installZshrcBlock(startMarker, endMarker, block) {
     content = content.trimEnd() + "\n\n" + block + "\n";
   }
   fs.writeFileSync(zshrc, content, "utf8");
+  if (!content.includes("compinit")) {
+    console.log(
+      warn(
+        "Note: `compinit` not found in ~/.zshrc. Tab completion needs it; add this line: autoload -Uz compinit && compinit",
+      ),
+    );
+  }
   return zshrc;
 }
 

package/src/profile.mjs

@@ -143,21 +143,50 @@ export function needsFirstRunChecklist(profileDir) {
   return !fs.existsSync(path.join(profileDir, SETUP_MARKER));
 }
 
-export function printFirstRunChecklist(
+/**
+ * @param {string} projectName
+ * @param {string} baseUrl
+ * @param {string} platform Node process.platform
+ */
+export function buildFirstRunChecklist(
   projectName,
   baseUrl = "https://gateway.example.com/v1",
+  platform = process.platform,
 ) {
-  console.log(`
-First-time setup for "${projectName}" in this Cursor profile:
+  if (platform === "darwin") {
+    return `
+First-time setup for "${projectName}" · copy-paste in order:
+
+  cursor-keys clone ${projectName}    # inherit sign-in, settings, model config from main Cursor
+  cursor-keys set-key ${projectName}  # inject the project API key (encrypted, hidden prompt)
+  cursor-keys doctor ${projectName}   # verify the profile
+
+Manual alternative: Cursor Settings → Models → API keys, paste the key under
+OpenAI API Key, enable "Override OpenAI Base URL" with: ${baseUrl}
+
+Already inside this profile's window? Close it before running clone or set-key.
+`;
+  }
 
-  1. Cursor Settings → Models → API keys
-  2. Paste your project API key under OpenAI API Key (or run: cursor-keys set-key ${projectName})
-  3. Enable "Use OpenAI API Key" and "Override OpenAI Base URL"
-  4. Base URL: ${baseUrl}
-  5. Add your gateway models and disable models you do not use
+  return `
+First-time setup for "${projectName}" · copy-paste in order:
 
-Then run: cursor-keys doctor ${projectName}
-`);
+  cursor-keys clone ${projectName}    # inherit sign-in, settings, model config from main Cursor
+  cursor-keys open ${projectName}     # open once so Cursor creates its state
+  cursor-keys doctor ${projectName}   # verify the profile
+
+Then in that window: Cursor Settings → Models → API keys, paste the key under
+OpenAI API Key, enable "Override OpenAI Base URL" with: ${baseUrl}
+
+Already inside this profile's window? Close it before running clone.
+`;
+}
+
+export function printFirstRunChecklist(
+  projectName,
+  baseUrl = "https://gateway.example.com/v1",
+) {
+  console.log(buildFirstRunChecklist(projectName, baseUrl, process.platform));
 }
 
 export function createProfile({ profileDir, projectName, color, cloneFrom }) {