@upturtle/wizard 0.1.2 → 0.2.1

package/README.md

@@ -8,23 +8,33 @@ npx @upturtle/wizard
 
 The installer:
 
-1. Opens UpTurtle in your browser to authenticate and mint a scoped personal access token.
-2. Detects which coding agent(s) you have installed (Claude Code, Cursor, Antigravity, OpenCode, Zed, Claude Desktop).
-3. Writes the MCP server entry into each agent's native config file.
-4. Verifies the connection.
+1. Detects which coding agent(s) you have installed (Claude Code, Cursor, Antigravity, OpenCode, Zed, Claude Desktop).
+2. Shows a checkbox list — `↑`/`↓` to move, space to toggle, `a` to toggle all, enter to confirm.
+3. Opens UpTurtle in your browser to authenticate and mint a scoped personal access token.
+4. Writes the MCP server entry into each selected agent's config.
 
 Once it's done, ask your AI: _"deploy this project to UpTurtle."_
 
+## Scope
+
+By default the wizard writes to your **user-wide** config — the MCP server is available in every project that agent opens. To install into the **current project** instead (so it's checked into git and shared with the team), pass `--project`:
+
+```bash
+npx @upturtle/wizard --project
+```
+
+Project scope is supported for `claude-code`, `cursor`, `opencode`, and `zed`. Antigravity and Claude Desktop don't have a project-level config format.
+
 ## Flags
 
 | Flag | Description |
 |---|---|
-| `--host=<url>` | Override the UpTurtle host. Defaults to `https://what.upturtle.com`. |
-| `--agent=<id,...>` | Skip auto-detection and target specific agent(s). |
+| `--host=<url>` | Override the UpTurtle host. Defaults to `https://what.upturtle.com`. Also `UPTURTLE_HOST=<url>`. |
+| `--scope=<scope>` | `user` (default) or `project`. Shorthands: `--user`, `--project`. |
+| `--agent=<id,...>` | Skip auto-detection and the prompt; install into specific agent(s). Comma-separated. |
+| `--yes`, `-y` | Skip the prompt; install into every detected agent. Implied when stdin is not a TTY (e.g. CI). |
 | `--help`, `-h` | Show usage. |
 
-The host can also be supplied via the `UPTURTLE_HOST` environment variable.
-
 ## License
 
 Proprietary.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@upturtle/wizard",
-  "version": "0.1.2",
+  "version": "0.2.1",
   "description": "Connects your coding agent to UpTurtle's MCP server. Detects the agent, mints a scoped PAT via browser handshake, and writes the right MCP config.",
   "type": "module",
   "bin": {

package/src/agents.mjs

@@ -3,42 +3,51 @@ import { homedir, platform } from "node:os";
 import { join } from "node:path";
 import { spawnSync } from "node:child_process";
 
+// `scopes` lists the install scopes the agent's writer supports. Agents whose
+// native config formats have no project-level alternative (Antigravity, Claude
+// Desktop) are user-only.
 export const AGENTS = [
   {
     id: "claude-code",
     label: "Claude Code",
     detect: () => isOnPath("claude"),
     writer: "claude-code",
+    scopes: ["user", "project"],
   },
   {
     id: "cursor",
     label: "Cursor",
     detect: () => existsSync(cursorAppDataDir()),
     writer: "cursor",
+    scopes: ["user", "project"],
   },
   {
     id: "antigravity",
     label: "Google Antigravity",
     detect: () => existsSync(antigravityConfigPath()),
     writer: "antigravity",
+    scopes: ["user"],
   },
   {
     id: "opencode",
     label: "OpenCode",
     detect: () => isOnPath("opencode") || existsSync(opencodeConfigPath()),
     writer: "opencode",
+    scopes: ["user", "project"],
   },
   {
     id: "zed",
     label: "Zed",
     detect: () => existsSync(zedConfigPath()) || existsSync("/Applications/Zed.app"),
     writer: "zed",
+    scopes: ["user", "project"],
   },
   {
     id: "claude-desktop",
     label: "Claude Desktop",
     detect: () => existsSync(claudeDesktopConfigPath()),
     writer: "claude-desktop",
+    scopes: ["user"],
   },
 ];
 

package/src/index.mjs

@@ -15,25 +15,43 @@ export async function run(argv) {
   const log = console.log;
 
   log("UpTurtle install");
-  log("  host: " + host);
+  log("  host:  " + host);
+  log("  scope: " + flags.scope + (flags.scope === "project" ? `  (cwd: ${process.cwd()})` : ""));
 
   const detected = detectInstalledAgents();
-  if (detected.length === 0) {
+  if (detected.length === 0 && !flags.agent) {
     log("");
     log("Couldn't detect any supported coding agents on this machine.");
     log("Supported: " + AGENTS.map((a) => a.label).join(", "));
     log("");
     log("If your agent is installed but not detected, re-run with --agent=<id>:");
     log("  " + AGENTS.map((a) => a.id).join(", "));
-    if (!flags.agent) {
-      process.exitCode = 1;
-      return;
-    }
+    process.exitCode = 1;
+    return;
+  }
+
+  let targets;
+  try {
+    targets = await pickTargets(detected, flags);
+  } catch (err) {
+    log(err.message);
+    process.exitCode = 1;
+    return;
   }
 
-  const targets = resolveTargets(detected, flags);
   if (targets.length === 0) {
-    log("No matching agents to install into. Exiting.");
+    log("No agents selected. Exiting.");
+    process.exitCode = 1;
+    return;
+  }
+
+  // Validate scope compatibility BEFORE minting a token — no point burning a
+  // PAT just to discover the chosen scope is unsupported.
+  const incompatible = targets.filter((a) => !a.scopes.includes(flags.scope));
+  if (incompatible.length > 0) {
+    log("");
+    log(`Scope "${flags.scope}" isn't supported by: ${incompatible.map((a) => a.label).join(", ")}`);
+    log("Re-run with --scope=user, or pick different agent(s) via --agent= or the prompt.");
     process.exitCode = 1;
     return;
   }
@@ -55,7 +73,7 @@ export async function run(argv) {
       continue;
     }
     try {
-      const out = writer({ host, secret });
+      const out = writer({ host, secret, scope: flags.scope });
       log(`  ✓ ${agent.label}  → ${out.configPath}`);
       results.push({ agent, ok: true });
     } catch (err) {
@@ -79,12 +97,21 @@ function parseFlags(argv) {
   const flags = {
     host: process.env.UPTURTLE_HOST ?? DEFAULT_HOST,
     agent: null,
+    scope: "user",
+    yes: false,
     help: false,
   };
   for (const a of argv) {
     if (a === "--help" || a === "-h") flags.help = true;
+    else if (a === "--yes" || a === "-y") flags.yes = true;
     else if (a.startsWith("--host=")) flags.host = a.slice("--host=".length);
     else if (a.startsWith("--agent=")) flags.agent = a.slice("--agent=".length);
+    else if (a.startsWith("--scope=")) flags.scope = a.slice("--scope=".length);
+    else if (a === "--project") flags.scope = "project";
+    else if (a === "--user") flags.scope = "user";
+  }
+  if (!["user", "project"].includes(flags.scope)) {
+    throw new Error(`--scope must be "user" or "project" (got "${flags.scope}")`);
   }
   flags.host = stripTrailingSlash(flags.host);
   return flags;
@@ -94,19 +121,134 @@ function stripTrailingSlash(s) {
   return s.endsWith("/") ? s.slice(0, -1) : s;
 }
 
-function resolveTargets(detected, flags) {
+// Decides which agents to install for. Order of precedence:
+//   1. Explicit --agent=id,id (skips prompt; honored even if not in detected)
+//   2. Non-interactive (--yes or non-TTY): every detected agent
+//   3. Interactive: prompt the user
+async function pickTargets(detected, flags) {
   if (flags.agent) {
-    const ids = flags.agent.split(",").map((s) => s.trim()).filter(Boolean);
-    const matched = ids
-      .map((id) => AGENTS.find((a) => a.id === id))
-      .filter(Boolean);
-    if (matched.length !== ids.length) {
-      const known = AGENTS.map((a) => a.id).join(", ");
-      throw new Error(`Unknown --agent value. Known ids: ${known}`);
-    }
-    return matched;
+    return resolveExplicitAgents(flags.agent);
+  }
+
+  if (flags.yes || !process.stdin.isTTY) {
+    return detected;
   }
-  return detected;
+
+  return await promptForAgents(detected);
+}
+
+function resolveExplicitAgents(value) {
+  const ids = value.split(",").map((s) => s.trim()).filter(Boolean);
+  const matched = ids
+    .map((id) => AGENTS.find((a) => a.id === id))
+    .filter(Boolean);
+  if (matched.length !== ids.length) {
+    const known = AGENTS.map((a) => a.id).join(", ");
+    throw new Error(`Unknown --agent value. Known ids: ${known}`);
+  }
+  return matched;
+}
+
+// Inquirer-style checkbox prompt. ↑/↓ moves the cursor, space toggles the
+// current row, `a` toggles all, enter confirms, q or Ctrl-C aborts. Falls back
+// to "install all detected" when the terminal doesn't support raw-mode input
+// (rare; only relevant if some host fakes a TTY without keystroke capture).
+async function promptForAgents(detected) {
+  const stdin = process.stdin;
+  const stdout = process.stdout;
+
+  if (typeof stdin.setRawMode !== "function") {
+    return detected;
+  }
+
+  return await new Promise((resolve, reject) => {
+    let cursor = 0;
+    const selected = new Set();
+    let linesWritten = 0;
+
+    const render = () => {
+      if (linesWritten > 0) {
+        // Move up to start of last render and clear from there to end of screen.
+        stdout.write(`\x1b[${linesWritten}A\x1b[0J`);
+      }
+      let buf = "";
+      buf += "Set up MCP for which agents?\n";
+      buf += "  ↑/↓ move · space toggle · a toggle-all · enter confirm · q quit\n";
+      detected.forEach((agent, i) => {
+        const cursorMark = i === cursor ? "\x1b[36m❯\x1b[0m" : " ";
+        const checkbox = selected.has(i) ? "\x1b[32m[x]\x1b[0m" : "[ ]";
+        buf += `  ${cursorMark} ${checkbox} ${agent.label}\n`;
+      });
+      stdout.write(buf);
+      linesWritten = (buf.match(/\n/g) || []).length;
+    };
+
+    const cleanup = () => {
+      try { stdin.setRawMode(false); } catch { /* ignore */ }
+      stdin.pause();
+      stdout.write("\x1b[?25h"); // restore cursor
+      stdin.removeListener("data", onData);
+    };
+
+    const finalize = () => {
+      if (linesWritten > 0) {
+        stdout.write(`\x1b[${linesWritten}A\x1b[0J`);
+      }
+      const result = [...selected].sort((a, b) => a - b).map((i) => detected[i]);
+      stdout.write(
+        `Selected: ${result.length > 0 ? result.map((a) => a.label).join(", ") : "(none)"}\n`,
+      );
+      cleanup();
+      if (result.length === 0) {
+        reject(new Error("No agents selected. Aborted."));
+      } else {
+        resolve(result);
+      }
+    };
+
+    const abort = (exitCode) => {
+      cleanup();
+      stdout.write("\n");
+      if (exitCode !== undefined) {
+        process.exit(exitCode);
+      }
+      reject(new Error("Aborted."));
+    };
+
+    const onData = (key) => {
+      if (key === "\x03") return abort(130);                 // Ctrl-C
+      if (key === "q" || key === "Q") return abort();
+      if (key === "\x1b[A" || key === "k") {                  // ↑
+        cursor = (cursor - 1 + detected.length) % detected.length;
+        return render();
+      }
+      if (key === "\x1b[B" || key === "j") {                  // ↓
+        cursor = (cursor + 1) % detected.length;
+        return render();
+      }
+      if (key === " ") {
+        if (selected.has(cursor)) selected.delete(cursor);
+        else selected.add(cursor);
+        return render();
+      }
+      if (key === "a" || key === "A") {
+        if (selected.size === detected.length) {
+          selected.clear();
+        } else {
+          for (let i = 0; i < detected.length; i++) selected.add(i);
+        }
+        return render();
+      }
+      if (key === "\r" || key === "\n") return finalize();
+    };
+
+    stdout.write("\x1b[?25l"); // hide cursor
+    stdin.setRawMode(true);
+    stdin.resume();
+    stdin.setEncoding("utf8");
+    stdin.on("data", onData);
+    render();
+  });
 }
 
 function printHelp() {
@@ -115,10 +257,21 @@ function printHelp() {
   npx @upturtle/wizard [options]
 
 Options:
-  --host=<url>      Override the UpTurtle host. Defaults to https://what.upturtle.com.
+  --host=<url>      Override the UpTurtle host. Defaults to ${DEFAULT_HOST}.
                     Also: UPTURTLE_HOST=<url>.
-  --agent=<id,...>  Skip auto-detection and install into specific agent(s).
+  --scope=<scope>   Where to write the MCP config:
+                      user     — your home dir; available in every project (default).
+                      project  — the current working directory; checked into git,
+                                 shareable across the team.
+                    Shorthand flags: --user, --project.
+  --agent=<id,...>  Skip auto-detection and the prompt; install into specific agent(s).
                     Known ids: ${AGENTS.map((a) => a.id).join(", ")}
+  --yes, -y         Skip the agent prompt and install into every detected agent.
+                    Implied when stdin is not a TTY (e.g. CI).
   --help, -h        Show this message.
+
+Project scope is supported for: claude-code, cursor, opencode, zed.
+Antigravity and Claude Desktop only support user scope (their config formats
+don't have a project-level alternative).
 `);
 }

package/src/writers.mjs

@@ -1,5 +1,5 @@
 import { mkdirSync, readFileSync, writeFileSync, existsSync } from "node:fs";
-import { dirname } from "node:path";
+import { dirname, join } from "node:path";
 import { spawnSync } from "node:child_process";
 
 import {
@@ -20,26 +20,49 @@ export const WRITERS = {
   "claude-desktop": writeClaudeDesktop,
 };
 
-function writeClaudeCode({ host, secret }) {
-  removeClaudeCodeServer();
+function writeClaudeCode({ host, secret, scope }) {
+  removeClaudeCodeServer(scope);
   const args = [
     "mcp", "add", SERVER_KEY, host + "/mcp",
     "--transport", "http",
     "--header", `Authorization: Bearer ${secret}`,
   ];
+  if (scope === "project") args.push("--scope", "project");
   const result = spawnSync("claude", args, { stdio: "pipe", encoding: "utf8" });
   if (result.status !== 0) {
     const detail = (result.stderr || result.stdout || "").trim();
     throw new Error(`claude mcp add failed: ${detail || `exit ${result.status}`}`);
   }
-  return { configPath: "(managed by `claude mcp`)" };
+  return {
+    configPath: scope === "project"
+      ? "./.mcp.json (managed by `claude mcp`)"
+      : "(managed by `claude mcp`)",
+  };
 }
 
-function removeClaudeCodeServer() {
-  spawnSync("claude", ["mcp", "remove", SERVER_KEY], { stdio: "ignore" });
+function removeClaudeCodeServer(scope) {
+  const args = ["mcp", "remove", SERVER_KEY];
+  if (scope === "project") args.push("--scope", "project");
+  spawnSync("claude", args, { stdio: "ignore" });
 }
 
-function writeCursor({ host, secret }) {
+function writeCursor({ host, secret, scope }) {
+  if (scope === "project") {
+    // Project: write .cursor/mcp.json directly. The deep link only handles
+    // user-scope; project config lives in the repo and is meant to be checked
+    // in.
+    const path = join(process.cwd(), ".cursor", "mcp.json");
+    return mergeJson(path, (cfg) => {
+      cfg.mcpServers ??= {};
+      cfg.mcpServers[SERVER_KEY] = {
+        url: host + "/mcp",
+        headers: { Authorization: `Bearer ${secret}` },
+      };
+      return cfg;
+    });
+  }
+
+  // User scope: open the Cursor deep link.
   const config = {
     url: host + "/mcp",
     headers: { Authorization: `Bearer ${secret}` },
@@ -59,7 +82,12 @@ function writeCursor({ host, secret }) {
   return { configPath: "(installed via Cursor deep link)" };
 }
 
-function writeAntigravity({ host, secret }) {
+function writeAntigravity({ host, secret, scope }) {
+  if (scope === "project") {
+    throw new Error(
+      "Antigravity doesn't have a project-scoped MCP config (only user-wide). " +
+        "Re-run without --scope=project for this agent.");
+  }
   const path = antigravityConfigPath();
   return mergeJson(path, (cfg) => {
     cfg.mcpServers ??= {};
@@ -71,8 +99,10 @@ function writeAntigravity({ host, secret }) {
   });
 }
 
-function writeOpenCode({ host, secret }) {
-  const path = opencodeConfigPath();
+function writeOpenCode({ host, secret, scope }) {
+  const path = scope === "project"
+    ? join(process.cwd(), "opencode.json")
+    : opencodeConfigPath();
   return mergeJson(path, (cfg) => {
     cfg.mcp ??= {};
     cfg.mcp[SERVER_KEY] = {
@@ -84,8 +114,10 @@ function writeOpenCode({ host, secret }) {
   });
 }
 
-function writeZed({ host, secret }) {
-  const path = zedConfigPath();
+function writeZed({ host, secret, scope }) {
+  const path = scope === "project"
+    ? join(process.cwd(), ".zed", "settings.json")
+    : zedConfigPath();
   return mergeJson(path, (cfg) => {
     cfg.context_servers ??= {};
     cfg.context_servers[SERVER_KEY] = {
@@ -103,14 +135,26 @@ function writeZed({ host, secret }) {
   });
 }
 
-function writeClaudeDesktop({ host, secret }) {
+function writeClaudeDesktop({ host, secret, scope }) {
+  if (scope === "project") {
+    throw new Error(
+      "Claude Desktop has only one global config file — there's no project " +
+        "scope. Re-run without --scope=project for this agent.");
+  }
   const path = claudeDesktopConfigPath();
   return mergeJson(path, (cfg) => {
     cfg.mcpServers ??= {};
+    // Claude Desktop's config only honors stdio MCP servers (command + args).
+    // Bridge the remote HTTP server through `mcp-remote`, same as the Zed entry.
     cfg.mcpServers[SERVER_KEY] = {
-      type: "streamable-http",
-      url: host + "/mcp",
-      headers: { Authorization: `Bearer ${secret}` },
+      command: "npx",
+      args: [
+        "-y",
+        "mcp-remote",
+        host + "/mcp",
+        "--header",
+        `Authorization: Bearer ${secret}`,
+      ],
     };
     return cfg;
   });