@synap-core/cli 1.13.0 → 1.13.1-next.20261102.4b45534

package/dist/lib/targets.js

@@ -17,8 +17,9 @@ import chalk from "chalk";
 import ora from "ora";
 import prompts from "prompts";
 import { log } from "../utils/logger.js";
-import { writeSecretFile, copySecretBackup, ensureSecretDir } from "./atomic-file.js";
-import { redactKey } from "./mcp-snippets.js";
+import { writeSecretFile, ensureSecretDir, readClientConfig, writeClientConfig, clientConfigBackupPath, } from "./atomic-file.js";
+import { redactKey, mcpRemoteArgs, MCP_REMOTE_PACKAGE } from "./mcp-snippets.js";
+import { MANAGED_MCP_URL } from "./auth.js";
 import { installSkills, getDeliverableSkills } from "./skills-installer.js";
 import { TARGET_KEY_MINT, takePreApprovedKey } from "./batch-approval.js";
 import { agentTypeOfSurface, machineInstanceId, machineInstanceLabel } from "./machine-instance.js";
@@ -636,13 +637,10 @@ export async function resolveWorkspaceId(cfg) {
 export async function writeClaudeCodeEnv(cfg, { writeMcp = true } = {}) {
     const settingsPath = path.join(os.homedir(), ".claude", "settings.json");
     const settingsDir = path.dirname(settingsPath);
-    let settings = {};
-    if (fs.existsSync(settingsPath)) {
-        try {
-            settings = JSON.parse(fs.readFileSync(settingsPath, "utf-8"));
-        }
-        catch { /* start fresh */ }
-    }
+    // Throws when the file exists but cannot be parsed: an unreadable
+    // settings.json is never rewritten as `{}` (it holds every hook, permission
+    // and env the person set).
+    const settings = readClientConfig(settingsPath);
     // ── Resolve human user ID and provision an agent-owned API key ──────────
     // SYNAP_USER_ID = human user (for entity attribution)
     // SYNAP_HUB_API_KEY = agent-owned key (identity encoded in the key itself)
@@ -726,7 +724,7 @@ export async function writeClaudeCodeEnv(cfg, { writeMcp = true } = {}) {
     if (!fs.existsSync(settingsDir)) {
         fs.mkdirSync(settingsDir, { recursive: true });
     }
-    writeSecretFile(settingsPath, JSON.stringify(settings, null, 2) + "\n", { mode: 0o600 });
+    writeClientConfig(settingsPath, settings);
     // ── Register the MCP server where Claude Code actually reads it ───────────
     // The official `claude mcp add` writes to the user-scope registry that
     // `claude mcp list` + the runtime consult — unlike settings.json mcpServers,
@@ -751,6 +749,8 @@ export async function writeClaudeCodeEnv(cfg, { writeMcp = true } = {}) {
 export function registerClaudeCodeMcp(mcpUrl, apiKey, serverName) {
     const header = `Authorization: Bearer ${apiKey}`;
     const bridge = claudeCodeMcpTransport() === "bridge";
+    const invocation = bridge ? resolveBridgeInvocation() : null;
+    const bridgeCommand = invocation ? synapBridgeCommand(mcpUrl, invocation) : [];
     try {
         // Remove legacy single-name entry and any prior pod-derived name.
         for (const name of new Set(["synap", serverName])) {
@@ -767,9 +767,12 @@ export function registerClaudeCodeMcp(mcpUrl, apiKey, serverName) {
                 // server's env, as the header does for http.
                 // `-e` is variadic in Claude Code's CLI: the server name must come
                 // BEFORE it, or `-e` swallows it as an env var.
-                ["mcp", "add", "--scope", "user", serverName, "-e", `SYNAP_MCP_API_KEY=${apiKey}`, "--", ...synapBridgeCommand(mcpUrl)]
+                ["mcp", "add", "--scope", "user", serverName, "-e", `SYNAP_MCP_API_KEY=${apiKey}`, "--", ...bridgeCommand]
             : ["mcp", "add", "--transport", "http", serverName, mcpUrl, "--header", header, "--scope", "user"], { stdio: "ignore" });
         log.success(`MCP server '${serverName}' registered with Claude Code (\`claude mcp add\`, user scope${bridge ? ", via the synap stdio bridge" : ""}). Relaunch Claude Code to load the tools.`);
+        const note = invocation && bridgeInvocationNote(invocation);
+        if (note)
+            log.dim(note);
         if (serverName !== "synap") {
             log.dim("Multi-pod: connect each profile separately — server names are derived from the pod host so they don't overwrite:");
             log.dim("  synap connect --target=claude-code --name=perso");
@@ -787,7 +790,7 @@ export function registerClaudeCodeMcp(mcpUrl, apiKey, serverName) {
             log.dim(`Could not run \`claude mcp add\` (is the claude CLI on PATH?). The '${serverName}' MCP server may now be UNREGISTERED in Claude Code. Register it by hand (the key is in a 0600 file, not on this screen):`);
             log.dim(`  source ${keyFile}`);
             log.dim(bridge
-                ? `  claude mcp add --scope user ${serverName} -e SYNAP_MCP_API_KEY="$SYNAP_MCP_KEY" -- ${synapBridgeCommand(mcpUrl).map(shellQuote).join(" ")}`
+                ? `  claude mcp add --scope user ${serverName} -e SYNAP_MCP_API_KEY="$SYNAP_MCP_KEY" -- ${bridgeCommand.map(shellQuote).join(" ")}`
                 : `  claude mcp add --transport http ${serverName} ${mcpUrl} --header 'Authorization: Bearer \${SYNAP_MCP_KEY}' --scope user`);
         }
         catch {
@@ -821,13 +824,8 @@ export function claudeCodeMcpTransport() {
  */
 export function setClaudeCodeMcpTransport(transport) {
     const settingsPath = path.join(os.homedir(), ".claude", "settings.json");
-    let settings;
-    try {
-        settings = JSON.parse(fs.readFileSync(settingsPath, "utf-8"));
-    }
-    catch {
-        return null;
-    }
+    // Missing → `{}` → no stored pod → null. Unreadable → throws (never rewritten).
+    const settings = readClientConfig(settingsPath);
     const env = (settings.env ?? {});
     const podUrl = env["SYNAP_POD_URL"];
     const apiKey = env["SYNAP_HUB_API_KEY"];
@@ -838,24 +836,59 @@ export function setClaudeCodeMcpTransport(transport) {
     else
         delete env["SYNAP_MCP_TRANSPORT"];
     settings.env = env;
-    writeSecretFile(settingsPath, JSON.stringify(settings, null, 2) + "\n", { mode: 0o600 });
+    writeClientConfig(settingsPath, settings);
     const serverName = mcpServerNameFromPodUrl(podUrl);
     registerClaudeCodeMcp(buildMcpUrl(podUrl, env["SYNAP_WORKSPACE_ID"], env["SYNAP_PROJECT_ID"]), apiKey, serverName);
     return serverName;
 }
-/**
- * The command Claude Code spawns for the bridge: THIS CLI by absolute path (the
- * one running `use-bridge` is the one known to have the bridge — a `synap` on
- * PATH may be an older install without it), unless this run is a throwaway
- * `npx` copy, whose cache path can vanish; then the `synap` on PATH.
- */
-function synapBridgeCommand(mcpUrl) {
-    const args = ["mcp", "bridge", "--url", mcpUrl];
-    const self = process.argv[1];
-    if (self && !self.includes(`${path.sep}_npx${path.sep}`)) {
-        return [process.execPath, fs.realpathSync(self), ...args];
+export function resolveBridgeInvocation(self = process.argv[1], execPath = process.execPath) {
+    const nm = `${path.sep}node_modules${path.sep}`;
+    if (!self || self.includes(`${path.sep}_npx${path.sep}`))
+        return { kind: "npx", command: ["synap"] };
+    const entry = path.resolve(self);
+    const realEntry = fs.realpathSync(entry);
+    const isLink = fs.lstatSync(entry).isSymbolicLink();
+    if (!isLink && !entry.includes(nm))
+        return { kind: "checkout", command: [execPath, realEntry], realEntry };
+    // Run through the package path (`<prefix>/lib/node_modules/@synap-core/cli/dist/index.js`):
+    // the bin npm installed next to it, when it leads to this same entry.
+    let installed = entry;
+    const pkgDir = `${nm}@synap-core${path.sep}cli${path.sep}`;
+    const at = entry.lastIndexOf(pkgDir);
+    if (!isLink && at >= 0) {
+        const prefix = entry.slice(0, at);
+        const bins = [
+            path.join(path.dirname(prefix), "bin", "synap"), // global: <prefix>/lib/node_modules → <prefix>/bin
+            path.join(prefix, "node_modules", ".bin", "synap"), // local: <dir>/node_modules → <dir>/node_modules/.bin
+        ];
+        for (const bin of bins) {
+            try {
+                if (fs.realpathSync(bin) === realEntry) {
+                    installed = bin;
+                    break;
+                }
+            }
+            catch {
+                /* no such bin — try the next */
+            }
+        }
+    }
+    return { kind: realEntry.includes(nm) ? "installed" : "linked", command: [execPath, installed], realEntry };
+}
+/** The command Claude Code spawns for the bridge (see `resolveBridgeInvocation`). */
+function synapBridgeCommand(mcpUrl, invocation) {
+    return [...invocation.command, "mcp", "bridge", "--url", mcpUrl];
+}
+/** One line on what the bridge runs, when it is not an installed release. */
+export function bridgeInvocationNote(invocation) {
+    const install = "To run a release instead: `npm install -g @synap-core/cli@next`, then `synap mcp use-bridge`.";
+    if (invocation.kind === "checkout") {
+        return `The MCP bridge runs this checkout build (${invocation.realEntry}), not an installed CLI. ${install}`;
+    }
+    if (invocation.kind === "linked") {
+        return `The MCP bridge runs the installed \`synap\` (${invocation.command[1]}), which is a link to a checkout (${invocation.realEntry}). ${install}`;
     }
-    return ["synap", ...args];
+    return null;
 }
 // ─── Agent key provisioning helper ──────────────────────────────────────────
 /**
@@ -1183,7 +1216,7 @@ async function installClaudeDesktop(info, cfg) {
         command: "npx",
         // The header value rides in env (this file is 0600), never in the
         // mcp-remote process's argv where any local `ps` can read it.
-        args: ["-y", "mcp-remote", desktopMcpUrl, "--header", "Authorization:${SYNAP_AUTH}"],
+        args: mcpRemoteArgs(desktopMcpUrl),
         env: { SYNAP_AUTH: `Bearer ${effectiveApiKey}` },
     });
     if (desktopServerName !== "synap")
@@ -1341,7 +1374,7 @@ async function installOpenWebUI(cfg) {
  *
  * OAuth: ChatGPT also supports OAuth (no header field). The pod's /mcp is
  * Bearer-only, so OAuth for a SINGLE pod isn't available — it lives on the
- * Control Plane (`https://api.synap.live/mcp`), which is an OAuth MCP server
+ * Control Plane (`https://mcp.synap.live`), which is an OAuth MCP server
  * exposing `list_pods` / `connect_pod` / 14 proxied `pod__*` tools. That path
  * is multi-pod and managed; `synap mcp connect-claude` prints it for
  * claude.ai, and the same URL works for ChatGPT's OAuth connector.
@@ -1370,7 +1403,7 @@ async function installChatGpt(cfg) {
             headers: { Authorization: `Bearer ${effectiveApiKey}` },
         },
         oauthAlternative: {
-            url: "https://api.synap.live/mcp",
+            url: MANAGED_MCP_URL,
             note: "ChatGPT OAuth connector (no header field). Multi-pod: list_pods, " +
                 "connect_pod, then proxied pod__* tools. Same URL as claude.ai.",
         },
@@ -1392,7 +1425,7 @@ async function installChatGpt(cfg) {
     log.info("Path 2 — OAuth (multi-pod, no key to paste):");
     log.blank();
     log.info("  ChatGPT → Settings → Connectors → Add custom connector");
-    log.info("  URL:     https://api.synap.live/mcp");
+    log.info(`  URL:     ${MANAGED_MCP_URL}`);
     log.info("  Auth:    OAuth (leave API key blank)");
     log.blank();
     log.dim("  After OAuth, ask ChatGPT to 'list my Synap pods' (list_pods) and connect " +
@@ -1520,19 +1553,10 @@ async function installZed(cfg) {
     if (!fs.existsSync(settingsDir))
         fs.mkdirSync(settingsDir, { recursive: true });
     const { effectiveApiKey, agentUserId, mcpUrl } = await prepareMcpSurface(cfg, "zed");
-    let settings = {};
-    if (fs.existsSync(settingsPath)) {
-        try {
-            const raw = fs.readFileSync(settingsPath, "utf-8");
-            // Zed settings.json is JSONC — strip // line comments and /* block comments */
-            // before parsing. Comments will not be preserved in the rewritten file.
-            const stripped = raw
-                .replace(/\/\*[\s\S]*?\*\//g, "")
-                .replace(/\/\/[^\n]*/g, "");
-            settings = JSON.parse(stripped);
-        }
-        catch { /* malformed — start from scratch */ }
-    }
+    // Zed settings.json is JSONC. The strings-aware reader keeps the `//` of the
+    // URLs inside it (a regex strip ate them and the parse failure wiped the
+    // file); a file that still does not parse is refused, never replaced.
+    const settings = readClientConfig(settingsPath);
     const contextServers = (settings.context_servers ?? {});
     // Pod-derived name — a second pod must not overwrite the first.
     const zedServerName = mcpServerNameFromPodUrl(cfg.podUrl);
@@ -1542,17 +1566,17 @@ async function installZed(cfg) {
         source: "custom",
         command: {
             path: "npx",
-            args: ["-y", "mcp-remote@latest", mcpUrl, "--header", "Authorization:${SYNAP_AUTH}"],
+            args: mcpRemoteArgs(mcpUrl),
             env: { SYNAP_AUTH: `Bearer ${effectiveApiKey}` },
         },
         settings: {},
     };
     settings.context_servers = contextServers;
-    writeSecretFile(settingsPath, JSON.stringify(settings, null, 2) + "\n", { mode: 0o600 });
+    writeClientConfig(settingsPath, settings);
     const { setSurfaceAgentKey: save } = await import("./pod.js");
     save("zed", { hubApiKey: effectiveApiKey, agentUserId, podUrl: cfg.podUrl });
     log.success(`Zed settings updated: ${settingsPath}`);
-    log.dim("Note: Zed settings are JSONC — any existing // comments were removed during rewrite.");
+    log.dim(`Note: Zed settings are JSONC — comments are not kept in the rewrite. The previous file is at ${clientConfigBackupPath(settingsPath)}.`);
     log.dim("Reload Zed to pick up the new context server (mcp-remote bridge).");
     return true;
 }
@@ -1571,13 +1595,8 @@ async function installVSCode(cfg) {
         fs.mkdirSync(mcpDir, { recursive: true });
     const { effectiveApiKey, agentUserId, mcpUrl } = await prepareMcpSurface(cfg, "vscode");
     // VS Code 1.99+ global MCP format uses "servers" (not "mcpServers")
-    let existing = {};
-    if (fs.existsSync(mcpJsonPath)) {
-        try {
-            existing = JSON.parse(fs.readFileSync(mcpJsonPath, "utf-8"));
-        }
-        catch { /* ignore */ }
-    }
+    // VS Code's mcp.json is JSONC (comments, trailing commas). Unreadable → refused.
+    const existing = readClientConfig(mcpJsonPath);
     existing.servers = existing.servers ?? {};
     // Pod-derived name — a second pod must not overwrite the first.
     const vscodeServerName = mcpServerNameFromPodUrl(cfg.podUrl);
@@ -1588,7 +1607,7 @@ async function installVSCode(cfg) {
         url: mcpUrl,
         headers: { Authorization: `Bearer ${effectiveApiKey}` },
     };
-    writeSecretFile(mcpJsonPath, JSON.stringify(existing, null, 2) + "\n", { mode: 0o600 });
+    writeClientConfig(mcpJsonPath, existing);
     const { setSurfaceAgentKey: save } = await import("./pod.js");
     save("vscode", { hubApiKey: effectiveApiKey, agentUserId, podUrl: cfg.podUrl });
     log.success(`VS Code MCP config updated: ${mcpJsonPath}`);
@@ -1703,7 +1722,7 @@ async function installGeneric(cfg) {
     log.dim(`headers = { Authorization = "Bearer ${shown}" }`);
     log.blank();
     log.info("stdio bridge (mcp-remote) — key via env, not argv:");
-    log.dim(`  command: npx -y mcp-remote ${mcpUrl} --header "Authorization:\${SYNAP_AUTH}"`);
+    log.dim(`  command: npx -y ${MCP_REMOTE_PACKAGE} ${mcpUrl} --header "Authorization:\${SYNAP_AUTH}"`);
     log.dim(`  env:     SYNAP_AUTH="Bearer ${shown}"`);
     log.dim("  Real key: ~/.synap/mcp-config.json (0600).");
     log.blank();
@@ -1711,19 +1730,10 @@ async function installGeneric(cfg) {
     ensureSecretDir(synapDir);
     const configFile = path.join(synapDir, "mcp-config.json");
     // Merge with existing so dual-pod generic installs don't clobber each other
-    let existing = {};
-    if (fs.existsSync(configFile)) {
-        try {
-            existing = JSON.parse(fs.readFileSync(configFile, "utf-8"));
-        }
-        catch {
-            /* replace */
-        }
-    }
+    // Unreadable → refused: it may hold another pod's entry.
+    const existing = readClientConfig(configFile);
     const merged = { ...existing, ...httpConfig };
-    writeSecretFile(configFile, JSON.stringify(merged, null, 2) + "\n", {
-        mode: 0o600,
-    });
+    writeClientConfig(configFile, merged);
     const { setSurfaceAgentKey: save } = await import("./pod.js");
     save("generic", {
         hubApiKey: effectiveApiKey,
@@ -1826,8 +1836,15 @@ async function pickProvider(podUrl, apiKey) {
     const spinner = ora("Fetching providers from pod vault...").start();
     let providers;
     try {
-        providers = await fetchCredentials(podUrl, apiKey);
+        const creds = await fetchCredentials(podUrl, apiKey);
         spinner.stop();
+        if (creds.masked) {
+            // A masked key written into a tool's config would fail on its first call.
+            log.warn("This pod gives provider keys only to its own services, not to an agent key.");
+            log.dim("Point the tool at the pod's OpenAI-compatible endpoint instead: synap providers pull --target show");
+            return null;
+        }
+        providers = creds.providers;
     }
     catch (err) {
         spinner.fail(`Could not fetch providers: ${err.message}`);
@@ -1877,16 +1894,8 @@ export async function installOpencode(cfg) {
     if (!fs.existsSync(configDir)) {
         fs.mkdirSync(configDir, { recursive: true });
     }
-    let existing = {};
-    if (fs.existsSync(configPath)) {
-        try {
-            existing = JSON.parse(fs.readFileSync(configPath, "utf-8"));
-        }
-        catch {
-            copySecretBackup(configPath, `${configPath}.bak`);
-            log.warn("Existing opencode.json unreadable — backed up to opencode.json.bak");
-        }
-    }
+    // opencode.json is JSONC. Unreadable → refused, never replaced.
+    const existing = readClientConfig(configPath);
     const providerBlock = (existing.provider ?? {});
     providerBlock[provider.providerId] = {
         npm: "@ai-sdk/openai-compatible",
@@ -1912,7 +1921,7 @@ export async function installOpencode(cfg) {
         mcp: mcpBlock,
         ...(existing.model ? {} : { model: defaultModel }),
     };
-    writeSecretFile(configPath, JSON.stringify(updated, null, 2) + "\n", { mode: 0o600 });
+    writeClientConfig(configPath, updated);
     const { setSurfaceAgentKey: save } = await import("./pod.js");
     save("opencode", { hubApiKey: agentKey, agentUserId, podUrl: cfg.podUrl });
     log.success(`opencode configured: ~/.config/opencode/opencode.json`);
@@ -1961,38 +1970,25 @@ export function writeMcpServerEntry(configPath, serverName, server) {
     if (!fs.existsSync(dir)) {
         fs.mkdirSync(dir, { recursive: true });
     }
-    let config = {};
-    if (fs.existsSync(configPath)) {
-        try {
-            config = JSON.parse(fs.readFileSync(configPath, "utf-8"));
-        }
-        catch {
-            // corrupt or unreadable — back up and start fresh
-            const backup = `${configPath}.bak-${Date.now()}`;
-            copySecretBackup(configPath, backup);
-            log.warn(`Existing config unreadable; backed up to ${path.basename(backup)}`);
-        }
-    }
+    // Unreadable → refused (it holds the person's other MCP servers), never
+    // "backed up and started fresh".
+    const config = readClientConfig(configPath);
     config.mcpServers = config.mcpServers ?? {};
     config.mcpServers[serverName] = server;
-    writeSecretFile(configPath, JSON.stringify(config, null, 2) + "\n", {
-        mode: 0o600,
-    });
+    writeClientConfig(configPath, config);
 }
 /** Best-effort remove of a named MCP server entry (e.g. legacy `"synap"`). */
 function removeMcpServerEntry(configPath, serverName) {
     if (!fs.existsSync(configPath))
         return;
     try {
-        const config = JSON.parse(fs.readFileSync(configPath, "utf-8"));
+        const config = readClientConfig(configPath);
         if (!config.mcpServers?.[serverName])
             return;
         delete config.mcpServers[serverName];
         if (Object.keys(config.mcpServers).length === 0)
             delete config.mcpServers;
-        writeSecretFile(configPath, JSON.stringify(config, null, 2) + "\n", {
-            mode: 0o600,
-        });
+        writeClientConfig(configPath, config);
     }
     catch {
         /* leave config alone if unreadable */