baychat 0.8.1 → 0.8.2

package/dist/client-config-writer.js

@@ -0,0 +1,149 @@
+"use strict";
+// Writing BayChat into a client's MCP config file, in place, without breaking it.
+//
+// `baychat mcp-config` PRINTS a config and asks the user to paste it. That is not
+// an install: it demands the user know what TOML is, where their client keeps its
+// config, and which half of the printed text is the part to paste. `baychat
+// connect` writes the file itself, and this module is the part that touches it.
+//
+// THE ONE RULE: NEVER DESTROY WHAT IS ALREADY THERE. These files hold the user's
+// other MCP servers, their editor settings, and in Codex's case a lot more
+// besides. A naive write costs someone their whole configuration, and they will
+// discover it later, in another tool, with no idea what did it. Everything below
+// exists to make that impossible:
+//
+//   - The merge is a SPLICE, not a rewrite: exactly the `baychat` server entry is
+//     replaced, byte-for-byte around it.
+//   - It is IDEMPOTENT: running connect twice replaces the block, never appends a
+//     second one (a duplicate `[mcp_servers.baychat]` makes the file invalid TOML,
+//     so an append-only implementation would break the client on the second run).
+//   - JSON is parsed and re-serialised; a file that does not parse is REFUSED
+//     rather than overwritten, because the only safe response to "I do not
+//     understand this file" is to keep your hands off it.
+//   - Callers back up first (`backupPathFor`), so there is always a way back.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.mergeTomlConfig = mergeTomlConfig;
+exports.mergeJsonConfig = mergeJsonConfig;
+exports.mergeClientConfig = mergeClientConfig;
+exports.backupPathFor = backupPathFor;
+exports.expandHome = expandHome;
+/**
+ * The TOML table header this owns, and the only span it may replace.
+ *
+ * Sub-tables (`[mcp_servers.baychat.env]`) belong to the same server and are
+ * replaced with it; a header for any OTHER server ends the span.
+ */
+const TOML_TABLE = "mcp_servers.baychat";
+/** Matches a top-level TOML table header line, capturing its dotted key. */
+const TOML_HEADER = /^\s*\[\s*([^\]]+?)\s*\]\s*$/;
+/**
+ * Splice the BayChat server block into an existing TOML file.
+ *
+ * @param existing current file content, or null when the file does not exist yet
+ * @param body the `[mcp_servers.baychat]` block to install
+ */
+function mergeTomlConfig(existing, body) {
+    const block = body.trimEnd();
+    if (existing === null || existing.trim() === "") {
+        return { content: `${block}\n`, action: "created" };
+    }
+    const lines = existing.split("\n");
+    let start = -1;
+    let end = lines.length;
+    for (let i = 0; i < lines.length; i += 1) {
+        const match = TOML_HEADER.exec(lines[i] ?? "");
+        if (!match)
+            continue;
+        const key = (match[1] ?? "").replace(/\s+/g, "");
+        const ours = key === TOML_TABLE || key.startsWith(`${TOML_TABLE}.`);
+        if (start === -1) {
+            if (ours)
+                start = i;
+            continue;
+        }
+        // Inside our span: a header that is not ours closes it.
+        if (!ours) {
+            end = i;
+            break;
+        }
+    }
+    if (start === -1) {
+        // Not present — append, keeping exactly one blank line as a separator so the
+        // result is readable whether or not the file ended with a newline.
+        const prefix = existing.endsWith("\n") ? existing.replace(/\n+$/, "\n") : `${existing}\n`;
+        return { content: `${prefix}\n${block}\n`, action: "appended" };
+    }
+    const before = lines.slice(0, start);
+    const after = lines.slice(end);
+    const merged = [...before, ...block.split("\n"), ...after].join("\n");
+    return { content: merged.endsWith("\n") ? merged : `${merged}\n`, action: "updated" };
+}
+/**
+ * Merge the BayChat server entry into a JSON MCP config (Cursor, Claude Desktop).
+ *
+ * @throws when the existing file is present but not valid JSON, or is not a JSON
+ * object. Overwriting in that case would silently discard whatever the user had —
+ * including a file that is merely mid-edit. Refusing lets the CLI say which file
+ * to look at.
+ */
+function mergeJsonConfig(existing, body) {
+    // `body` is ours, produced by buildClientConfig — a parse failure here is a bug
+    // in this package, not user input, so it is allowed to throw plainly.
+    const incoming = JSON.parse(body);
+    const entry = incoming.mcpServers?.baychat;
+    if (entry === undefined) {
+        throw new Error("Generated config has no mcpServers.baychat entry — this is a bug.");
+    }
+    if (existing === null || existing.trim() === "") {
+        return { content: `${JSON.stringify(incoming, null, 2)}\n`, action: "created" };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(existing);
+    }
+    catch {
+        throw new Error("Your existing config is not valid JSON, so it was left untouched. Fix or move it, then run this again.");
+    }
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new Error("Your existing config is not a JSON object, so it was left untouched. Fix or move it, then run this again.");
+    }
+    const current = parsed;
+    const servers = { ...(current.mcpServers ?? {}) };
+    const had = Object.prototype.hasOwnProperty.call(servers, "baychat");
+    servers.baychat = entry;
+    const merged = { ...current, mcpServers: servers };
+    return {
+        content: `${JSON.stringify(merged, null, 2)}\n`,
+        action: had ? "updated" : "appended",
+    };
+}
+/** Merge by dialect. Keeps the format decision in one place. */
+function mergeClientConfig(config, existing) {
+    return config.format === "toml"
+        ? mergeTomlConfig(existing, config.body)
+        : mergeJsonConfig(existing, config.body);
+}
+/**
+ * Where to copy a file before rewriting it.
+ *
+ * Deliberately a FIXED name rather than a timestamp: a user who runs connect ten
+ * times should end up with one backup they can find, not ten they have to date.
+ * The pre-edit state is the only one worth keeping.
+ */
+function backupPathFor(path) {
+    return `${path}.baychat-backup`;
+}
+/**
+ * Expand a leading `~` to the given home directory.
+ *
+ * The dialect table stores display paths (`~/.codex/config.toml`) because that is
+ * what a human reads; writing needs a real path. Only a LEADING `~/` is expanded —
+ * a tilde anywhere else is a legitimate filename character.
+ */
+function expandHome(path, home) {
+    if (path === "~")
+        return home;
+    if (path.startsWith("~/"))
+        return `${home}/${path.slice(2)}`;
+    return path;
+}

package/dist/client-paths.js

@@ -0,0 +1,84 @@
+"use strict";
+// Where each MCP client actually keeps its config on disk.
+//
+// WHY THIS IS NOT `CLIENT_FILES`. That table in `mcp-dialects.ts` holds strings
+// written for a human to read — `"~/.cursor/mcp.json (or a project
+// .cursor/mcp.json)"`, `"claude_desktop_config.json (Settings → Developer → Edit
+// Config)"`. Perfect for a printed instruction, useless for `writeFileSync`: one
+// carries a parenthetical, the other is not a path at all. Treating them as paths
+// would have created a file literally named `claude_desktop_config.json (Settings
+// → Developer → Edit Config)` in the working directory, and the user's real
+// config would never have been touched — an install that reports success and
+// changes nothing.
+//
+// So writing gets its own table, resolved per platform, and returns null when we
+// genuinely do not know. Guessing a path is worse than declining: a wrong guess
+// writes a file no client reads, and the user is left debugging a config that
+// looks correct.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.configPathFor = configPathFor;
+exports.currentPathEnv = currentPathEnv;
+exports.needsRestart = needsRestart;
+/**
+ * Claude Desktop's config location, which is the only genuinely
+ * platform-dependent one of the three.
+ *
+ * Returns null on an unrecognised platform, and on Windows without `APPDATA` —
+ * there is no sound fallback for either, and inventing one writes a file nothing
+ * will read.
+ */
+function claudeDesktopPath(env) {
+    if (env.platform === "darwin") {
+        return `${env.home}/Library/Application Support/Claude/claude_desktop_config.json`;
+    }
+    if (env.platform === "win32") {
+        if (!env.appData)
+            return null;
+        return `${env.appData}\\Claude\\claude_desktop_config.json`;
+    }
+    if (env.platform === "linux") {
+        const base = env.xdgConfigHome && env.xdgConfigHome.trim() !== ""
+            ? env.xdgConfigHome
+            : `${env.home}/.config`;
+        return `${base}/Claude/claude_desktop_config.json`;
+    }
+    return null;
+}
+/**
+ * The absolute config path to write for a client, or null when it cannot be
+ * determined on this platform.
+ *
+ * Codex and Cursor keep theirs in the home directory on every platform. Cursor
+ * also supports a per-project `.cursor/mcp.json`; the global file is chosen
+ * deliberately, because `connect` is establishing this machine's identity, not
+ * one repository's.
+ */
+function configPathFor(client, env) {
+    switch (client) {
+        case "codex":
+            return `${env.home}/.codex/config.toml`;
+        case "cursor":
+            return `${env.home}/.cursor/mcp.json`;
+        case "desktop":
+            return claudeDesktopPath(env);
+    }
+}
+/** Read the path environment from the current process. */
+function currentPathEnv() {
+    return {
+        home: process.env.HOME || process.env.USERPROFILE || "",
+        platform: process.platform,
+        appData: process.env.APPDATA,
+        xdgConfigHome: process.env.XDG_CONFIG_HOME,
+    };
+}
+/**
+ * Whether this client needs a restart to pick up a changed config.
+ *
+ * Only stated where it is true, so the instruction carries weight. A CLI that
+ * tells everyone to restart trains them to ignore it — and Codex and Cursor read
+ * their MCP config per session, so most users need nothing.
+ */
+function needsRestart(client) {
+    return client === "desktop";
+}

package/dist/commands.js

@@ -651,8 +651,10 @@ async function cmdLogin(opts = {}) {
             expiresAt: me.expiresAt,
         });
         console.log(`✓ Logged in as ${me.user.name} (${me.tenant.name})`);
-        registerWithClaude(base, opts.token);
-        console.log("\n  Run /baychat <name> in any session.");
+        if (opts.registerClaude !== false)
+            registerWithClaude(base, opts.token);
+        if (opts.hint !== false)
+            console.log("\n  Run /baychat <name> in any session.");
         return true;
     }
     // The hostname labels this laptop in the approve UI; the server caps the field
@@ -704,8 +706,10 @@ async function cmdLogin(opts = {}) {
                 expiresAt: status.expiresAt,
             });
             console.log(`✓ Logged in as ${status.user.name}`);
-            registerWithClaude(base, status.token);
-            console.log("\n  Run /baychat <name> in any session.");
+            if (opts.registerClaude !== false)
+                registerWithClaude(base, status.token);
+            if (opts.hint !== false)
+                console.log("\n  Run /baychat <name> in any session.");
             return true;
         }
     }

package/dist/connect-plan.js

@@ -0,0 +1,122 @@
+"use strict";
+// What `baychat connect <client>` should DO, decided before anything is done.
+//
+// ONE LOGIN PER LAPTOP, THEN NOTHING. `connect` shows the device-link QR once,
+// writes the DEVICE credential into the client's MCP config, and stops. Every
+// coding session afterwards joins a room by itself:
+//
+//     /baychat <name>      -> join_session({ session: "<name>" })
+//
+// which mints (or reattaches) that session's own agent and puts it in a chat.
+// Same name, same agent, same history.
+//
+// WHY THE DEVICE CREDENTIAL AND NOT AN AGENT TOKEN. An agent token pins the
+// client to ONE pre-made agent in ONE room, so every new session would need
+// another trip to the phone for another code — a recurring chore dressed up as an
+// install. The device credential represents the PERSON, and the session tools it
+// unlocks let each session create its own identity on demand. That is the whole
+// difference between setting something up once and setting it up forever.
+//
+// Agent tokens and pairing codes are not gone; they are the path for EXTERNAL and
+// LEGACY runtimes (a self-hosted gateway, anything driving the Agent API itself),
+// which have no MCP client to configure and no session concept. `baychat pair`
+// still serves them.
+//
+// The two halves people conflate remain distinct, and this module keeps them so:
+//
+//   1. CONNECT THIS LAPTOP - a device credential. Authorising a machine to act as
+//      you, the way WhatsApp Web authorises a browser. Creates NO agent and puts
+//      nobody in a room. Lives under Account -> Devices in the app.
+//   2. JOIN A SESSION - `/baychat <name>` inside the client, per session. This is
+//      what actually ends with something able to speak, and it needs no QR, no
+//      code, and no pre-created agent.
+//
+// Steps are computed from observed state here, as data, and the executor only
+// carries them out - so the sequencing is testable without a network, a terminal,
+// or a phone.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.deviceStateFrom = deviceStateFrom;
+exports.planConnect = planConnect;
+exports.planNeedsPhoneApproval = planNeedsPhoneApproval;
+exports.expiryNudge = expiryNudge;
+exports.describeConnection = describeConnection;
+const THREE_DAYS_MS = 3 * 86_400_000;
+/** Read the on-disk credential into a state, without judging what to do about it. */
+function deviceStateFrom(device, now = Date.now()) {
+    if (!device)
+        return { kind: "absent" };
+    const expires = new Date(device.expiresAt).getTime();
+    // An unparseable expiry is treated as expired. Treating it as live would send
+    // the user into a flow that fails at the first authenticated call, with an
+    // error that points at the server rather than at their credential.
+    if (Number.isNaN(expires) || expires <= now) {
+        return { kind: "expired", userName: device.user.name };
+    }
+    return { kind: "live", userName: device.user.name, msLeft: expires - now };
+}
+/**
+ * The ordered steps for one `connect` run.
+ *
+ * `needsRestart` is injected rather than imported so the sequencing can be tested
+ * against both answers without reaching for a specific client.
+ */
+function planConnect(input) {
+    const { client, device, needsRestart } = input;
+    const steps = [];
+    if (device.kind === "absent" || device.kind === "expired") {
+        steps.push({ kind: "device-login", reason: device.kind });
+    }
+    else {
+        steps.push({ kind: "device-ok", userName: device.userName, msLeft: device.msLeft });
+    }
+    // No code, no room, no agent. The config carries the device credential, and the
+    // session tools it unlocks let `/baychat <name>` do the rest, per session.
+    steps.push({ kind: "write-config", client });
+    if (needsRestart)
+        steps.push({ kind: "restart-note", client });
+    return steps;
+}
+/** Whether the plan will ask the user to approve a QR on their phone. */
+function planNeedsPhoneApproval(steps) {
+    return steps.some((s) => s.kind === "device-login");
+}
+/** The expiry nudge for a live credential, or null when it is not due yet. */
+function expiryNudge(device) {
+    if (device.kind !== "live")
+        return null;
+    if (device.msLeft >= THREE_DAYS_MS)
+        return null;
+    const hours = Math.max(1, Math.round(device.msLeft / 3_600_000));
+    return `Your laptop login expires in about ${hours}h — run \`npx baychat login\` to renew.`;
+}
+/**
+ * Describe the finished state.
+ *
+ * The note is the one thing a user cannot infer from a successful install: the
+ * command connected a LAPTOP, and nothing is in a room yet. Without that line the
+ * obvious reading of "✓ done" is that an agent is now listening somewhere, and the
+ * user waits for a reply that was never going to come.
+ *
+ * Revocation is coherent under this design, which is a reason to prefer it:
+ * revoking the laptop under Account → Devices cuts every session it opened,
+ * because they all speak through its credential.
+ */
+function describeConnection(input) {
+    const { device, agentName, groupTitle } = input;
+    const laptop = device.kind === "live"
+        ? `connected as ${device.userName} (${Math.floor(device.msLeft / 86_400_000)}d left)`
+        : device.kind === "expired"
+            ? `login expired — run \`npx baychat connect\` again`
+            : "not connected";
+    const agent = agentName === null
+        ? "none yet — run /baychat <name> in a session"
+        : groupTitle
+            ? `${agentName} in ${groupTitle}`
+            : agentName;
+    return {
+        laptop,
+        agent,
+        note: "Each session makes its own agent: run /baychat <name> inside the client. " +
+            "The same name always reattaches to the same agent and history.",
+    };
+}

package/dist/connect.js

@@ -0,0 +1,214 @@
+"use strict";
+// `baychat connect <client>` — one command, once per laptop.
+//
+// WHAT IT DOES. Shows the device-link QR, waits for the phone to approve it, and
+// writes the DEVICE credential into the client's MCP config. Then it stops.
+//
+// WHAT IT DELIBERATELY DOES NOT DO. Ask for a code. Ask which room. Create an
+// agent. All three used to be here, and all three were the same mistake: they
+// bound the client to one pre-made agent in one conversation, so every new
+// coding session needed another trip to the phone. Setup you repeat is not setup.
+//
+// Instead, each session names itself, inside the client:
+//
+//     /baychat <name>     ->  join_session({ session: "<name>" })
+//
+// which mints or reattaches that session's own agent and puts it in a chat. The
+// session tools that make this possible are exactly what a device credential
+// unlocks — which is why the config carries that credential and not an agent
+// token.
+//
+// Pairing codes still exist, for EXTERNAL and LEGACY runtimes: a self-hosted
+// gateway, or anything driving the Agent API directly. Those have no MCP client
+// to configure and no session concept, so `baychat pair <code>` remains their
+// path. It is not this one.
+//
+// FILE SAFETY. This edits config a user already has, so the merge is a splice
+// rather than a rewrite, it is idempotent, unparseable JSON is refused rather
+// than overwritten, the previous file is backed up first, and the result is 0600
+// because it holds a bearer token. See client-config-writer.ts.
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.renderConnectMenu = renderConnectMenu;
+exports.parseConnectClient = parseConnectClient;
+exports.writeClientConfig = writeClientConfig;
+exports.cmdConnect = cmdConnect;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const client_config_writer_1 = require("./client-config-writer");
+const client_paths_1 = require("./client-paths");
+const commands_1 = require("./commands");
+const config_1 = require("./config");
+const connect_plan_1 = require("./connect-plan");
+const mcp_dialects_1 = require("./mcp-dialects");
+/** Clients `connect` can configure. `claude` is an alias users reach for. */
+const CLIENT_ALIASES = {
+    codex: "codex",
+    cursor: "cursor",
+    desktop: "desktop",
+    "claude-desktop": "desktop",
+};
+/** What `baychat connect` prints with no client: the menu. Names no credential. */
+function renderConnectMenu() {
+    const rows = mcp_dialects_1.MCP_CLIENTS.map((c) => `  npx baychat connect ${c.padEnd(8)}→ ${mcp_dialects_1.CLIENT_LABELS[c]}`);
+    return [
+        "Connect this laptop to BayChat, once, and configure your client:",
+        "",
+        ...rows,
+        "",
+        "You approve a QR on your phone. After that, in any coding session:",
+        "",
+        "  /baychat <name>        join BayChat as a session called <name>",
+        "",
+        "Claude Code needs no config — `npx baychat login` sets it up for you.",
+    ].join("\n");
+}
+/**
+ * Narrow a client argument.
+ *
+ * @throws on anything unsupported, listing what is supported. A typo must not
+ * fall through to a default and configure the wrong client.
+ */
+function parseConnectClient(value) {
+    const match = CLIENT_ALIASES[value.trim().toLowerCase()];
+    if (!match) {
+        throw new Error(`Unknown client "${value}" — supported: ${mcp_dialects_1.MCP_CLIENTS.join(", ")}. ` +
+            "Claude Code is registered automatically by `npx baychat login`.");
+    }
+    return match;
+}
+/** Write the client config, backing up whatever was there first. */
+function writeClientConfig(client, endpoint, io, env = (0, client_paths_1.currentPathEnv)()) {
+    const target = (0, client_paths_1.configPathFor)(client, env);
+    if (target === null) {
+        throw new Error(`Could not work out where ${mcp_dialects_1.CLIENT_LABELS[client]} keeps its config on this platform. ` +
+            "Run `npx baychat mcp-config --client " +
+            client +
+            "` and paste it yourself.");
+    }
+    const config = (0, mcp_dialects_1.buildClientConfig)(client, endpoint);
+    const existing = io.readFile(target);
+    const merged = (0, client_config_writer_1.mergeClientConfig)(config, existing);
+    // Back up BEFORE writing, and only when there was something to lose. A user who
+    // discovers a surprise in their config later needs a way back that does not
+    // depend on them having made one.
+    if (existing !== null && existing.trim() !== "") {
+        io.copyFile(target, (0, client_config_writer_1.backupPathFor)(target));
+    }
+    io.mkdirp(node_path_1.default.dirname(target));
+    io.writeFile(target, merged.content);
+    return { path: target, action: merged.action };
+}
+/** Real filesystem IO for `writeClientConfig`. */
+const realIo = {
+    readFile: (p) => {
+        try {
+            return node_fs_1.default.readFileSync(p, "utf8");
+        }
+        catch (err) {
+            // ENOENT is the ordinary "first run" case. Anything else — a permission
+            // problem, a directory where a file should be — must not be silently read
+            // as "no config", because that would overwrite a file we simply could not
+            // open.
+            if (err.code === "ENOENT")
+                return null;
+            throw err;
+        }
+    },
+    writeFile: (p, content) => {
+        // 0600: the file holds a bearer token.
+        node_fs_1.default.writeFileSync(p, content, { mode: 0o600 });
+    },
+    copyFile: (from, to) => node_fs_1.default.copyFileSync(from, to),
+    mkdirp: (dir) => {
+        node_fs_1.default.mkdirSync(dir, { recursive: true, mode: 0o700 });
+    },
+};
+/**
+ * `baychat connect <client>`.
+ *
+ * @returns 0 on success, 2 when the laptop login expired without approval.
+ */
+async function cmdConnect(clientArg, opts = {}) {
+    if (clientArg === undefined) {
+        console.log(renderConnectMenu());
+        return 0;
+    }
+    const client = parseConnectClient(clientArg);
+    const base = (opts.base || process.env.BAYCHAT_API_URL || config_1.DEFAULT_API_URL).replace(/\/$/, "");
+    const steps = (0, connect_plan_1.planConnect)({
+        client,
+        device: (0, connect_plan_1.deviceStateFrom)((0, config_1.loadDeviceCredentials)()),
+        needsRestart: (0, client_paths_1.needsRestart)(client),
+    });
+    for (const step of steps) {
+        const outcome = await runStep(step, { base, client });
+        if (outcome.kind === "abort")
+            return outcome.code;
+    }
+    const summary = (0, connect_plan_1.describeConnection)({
+        device: (0, connect_plan_1.deviceStateFrom)((0, config_1.loadDeviceCredentials)()),
+        agentName: null,
+        groupTitle: null,
+    });
+    console.log("");
+    console.log(`  Laptop:  ${summary.laptop}`);
+    console.log(`  Sessions: ${summary.agent}`);
+    console.log("");
+    console.log(`  ${summary.note}`);
+    return 0;
+}
+async function runStep(step, ctx) {
+    switch (step.kind) {
+        case "device-login": {
+            console.log(step.reason === "expired"
+                ? "Your laptop login has expired. Reconnecting this laptop…\n"
+                : "Connecting this laptop — approve the QR on your phone.\n");
+            // registerClaude is left ON only for the desktop/claude clients; for any
+            // other client, editing Claude's config unasked is a surprise.
+            const ok = await (0, commands_1.cmdLogin)({
+                base: ctx.base,
+                registerClaude: ctx.client === "desktop",
+                hint: false,
+            });
+            if (!ok) {
+                console.log("\nLaptop not connected — run `npx baychat connect` again when ready.");
+                return { kind: "abort", code: 2 };
+            }
+            console.log("✓ Laptop connected.\n");
+            return { kind: "ok" };
+        }
+        case "device-ok": {
+            console.log(`✓ Laptop already connected as ${step.userName}.`);
+            const nudge = (0, connect_plan_1.expiryNudge)({ kind: "live", userName: step.userName, msLeft: step.msLeft });
+            if (nudge)
+                console.log(`  ${nudge}`);
+            console.log("");
+            return { kind: "ok" };
+        }
+        case "write-config": {
+            // The DEVICE credential, deliberately — it is what unlocks the session tools
+            // (`join_session`, `list_sessions`, `end_session`) that let each session
+            // create its own identity. An agent token would pin this client to one
+            // agent in one room forever.
+            const device = (0, config_1.loadDeviceCredentials)();
+            if (!device) {
+                // Unreachable via planConnect, which logs in first; a guard rather than a
+                // comment because writing an empty bearer fails silently inside a client.
+                throw new Error("Internal: no device credential to write — login must run first.");
+            }
+            const { path: written, action } = writeClientConfig(step.client, { url: `${ctx.base}/api/mcp`, token: device.token }, realIo);
+            const verb = action === "created" ? "Created" : action === "updated" ? "Updated" : "Added to";
+            console.log(`✓ ${verb} ${written}`);
+            if (action !== "created") {
+                console.log(`  A copy of the previous file is at ${(0, client_config_writer_1.backupPathFor)(written)}`);
+            }
+            return { kind: "ok" };
+        }
+        case "restart-note":
+            console.log(`\n  Quit and reopen ${mcp_dialects_1.CLIENT_LABELS[step.client]} — it reads its config at startup.`);
+            return { kind: "ok" };
+    }
+}

package/dist/index.js

@@ -2,6 +2,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 const commands_1 = require("./commands");
+const connect_1 = require("./connect");
 const mcp_1 = require("./mcp");
 const mcp_config_1 = require("./mcp-config");
 const HELP = `baychat — BayChat connector CLI for agent sessions (Claude Code, Codex)
@@ -12,9 +13,15 @@ Usage:
                                         live identity, conversations, and room context.
                                         --catch-up also appends the rolling summary +
                                         the messages after its boundary
+  baychat connect [codex|cursor|desktop] [--base <url>]
+                                        START HERE, once per laptop. Approve a QR on your
+                                        phone, and your client's MCP config is written for
+                                        you. Then run /baychat <name> in any session to
+                                        join as that session. No config blocks, no editing
   baychat login [--token <PAT>] [--base <url>]
                                         Log this laptop in to BayChat (QR) and add the
-                                        BayChat MCP server to Claude Code
+                                        BayChat MCP server to Claude Code. Creates a
+                                        device credential only — no agent, no room
   baychat pair <code> [--base <url>]   Redeem a pairing code from the BayChat app
   baychat link [--name <n>] [--base <url>]
                                         Link this session via a QR you scan with your phone
@@ -150,6 +157,11 @@ async function main() {
             });
             return got ? 0 : 2;
         }
+        case "connect": {
+            // A bare `connect` prints the client menu; positional() skips a leading flag
+            // so `connect --base x codex` still finds the client.
+            return await (0, connect_1.cmdConnect)(positional(args), { base: flag(args, "--base") });
+        }
         case "mcp-config": {
             // `--client` with no value is a typo, not a request for the menu: pass the
             // empty string so it is rejected by name rather than silently listing.

package/dist/mcp-config.js

@@ -6,6 +6,13 @@
 // their client's config dialect, and dig the device token out of
 // ~/.baychat/credentials.json by hand. This module turns that into one command.
 //
+// THE DIALECTS LIVE IN `./mcp-dialects`, not here — the mobile app renders the
+// same configs on its "Connect an MCP client" screen, and a second hand-written
+// copy would drift silently. That module imports no Node built-ins so it can be
+// bundled by React Native. THIS file is the impure half: reading the credentials
+// file, resolving the base url, and printing. Everything from `mcp-dialects` is
+// re-exported below, so importers of this module see no difference.
+//
 // Two rules shape everything below.
 //
 //   1. THE TOKEN IS A PASSWORD. It is read only when a config is actually being
@@ -17,23 +24,19 @@
 //      usable token must produce an actionable error, not a config with an empty
 //      bearer that fails later inside a GUI client with no visible reason.
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.MCP_CLIENTS = void 0;
+exports.renderClientList = exports.parseClient = exports.buildClientConfig = exports.MCP_CLIENTS = exports.CLIENT_LABELS = exports.CLIENT_FILES = exports.AUTH_ENV = void 0;
 exports.resolveMcpEndpoint = resolveMcpEndpoint;
-exports.parseClient = parseClient;
-exports.buildClientConfig = buildClientConfig;
-exports.renderClientList = renderClientList;
 exports.cmdMcpConfig = cmdMcpConfig;
 const config_1 = require("./config");
-exports.MCP_CLIENTS = ["codex", "cursor", "desktop"];
-/** The env var the stdio bridge expands the Authorization header from. */
-const AUTH_ENV = "BAYCHAT_AUTH_HEADER";
-/** Where each client keeps its MCP config. Named once so the menu and the
- * generated config can never disagree about where the paste goes. */
-const CLIENT_FILES = {
-    codex: "~/.codex/config.toml",
-    cursor: "~/.cursor/mcp.json (or a project .cursor/mcp.json)",
-    desktop: "claude_desktop_config.json (Settings → Developer → Edit Config)",
-};
+const mcp_dialects_1 = require("./mcp-dialects");
+var mcp_dialects_2 = require("./mcp-dialects");
+Object.defineProperty(exports, "AUTH_ENV", { enumerable: true, get: function () { return mcp_dialects_2.AUTH_ENV; } });
+Object.defineProperty(exports, "CLIENT_FILES", { enumerable: true, get: function () { return mcp_dialects_2.CLIENT_FILES; } });
+Object.defineProperty(exports, "CLIENT_LABELS", { enumerable: true, get: function () { return mcp_dialects_2.CLIENT_LABELS; } });
+Object.defineProperty(exports, "MCP_CLIENTS", { enumerable: true, get: function () { return mcp_dialects_2.MCP_CLIENTS; } });
+Object.defineProperty(exports, "buildClientConfig", { enumerable: true, get: function () { return mcp_dialects_2.buildClientConfig; } });
+Object.defineProperty(exports, "parseClient", { enumerable: true, get: function () { return mcp_dialects_2.parseClient; } });
+Object.defineProperty(exports, "renderClientList", { enumerable: true, get: function () { return mcp_dialects_2.renderClientList; } });
 const LOGIN_HINT = "run `baychat login` first";
 /**
  * The endpoint + token for the logged-in device.
@@ -86,105 +89,6 @@ function resolveBaseUrl(raw) {
     }
     return parsed.toString().replace(/\/+$/, "");
 }
-/**
- * Narrow a `--client` value.
- *
- * @throws on anything unsupported, listing what IS supported — a typo must not
- * silently fall through to a default client and produce a config for the wrong
- * one.
- */
-function parseClient(value) {
-    const match = exports.MCP_CLIENTS.find((c) => c === value);
-    if (!match) {
-        throw new Error(`Unknown --client "${value}" — supported: ${exports.MCP_CLIENTS.join(", ")}. ` +
-            "Claude Code is registered automatically by `baychat login`.");
-    }
-    return match;
-}
-/** A TOML basic string. Backslash first, then quote — the other order would
- * double-escape the backslashes it just introduced. */
-function tomlString(value) {
-    return `"${value.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
-}
-/** The mcp-remote argv, used by stdio-only clients.
- *
- * `Authorization:${VAR}` with NO space is deliberate: mcp-remote expands the
- * `${VAR}` from its own environment, and Claude Desktop mangles a header
- * argument that contains a space. Passing the value by env rather than inline
- * also keeps the credential out of the process listing. */
-function bridgeArgs(url) {
-    return ["-y", "mcp-remote", url, "--header", `Authorization:\${${AUTH_ENV}}`];
-}
-/** The config for one client, ready to paste. Pure — no I/O, no logging. */
-function buildClientConfig(client, endpoint) {
-    const header = `Bearer ${endpoint.token}`;
-    if (client === "cursor") {
-        // Cursor speaks Streamable HTTP natively — no bridge needed.
-        const body = JSON.stringify({ mcpServers: { baychat: { url: endpoint.url, headers: { Authorization: header } } } }, null, 2);
-        return {
-            client,
-            file: CLIENT_FILES[client],
-            format: "json",
-            body,
-            notes: ["Cursor connects to the remote server directly — restart Cursor after saving."],
-        };
-    }
-    if (client === "desktop") {
-        // Claude Desktop's config file launches stdio servers only, so the remote
-        // endpoint is fronted by the community mcp-remote bridge.
-        const body = JSON.stringify({
-            mcpServers: {
-                baychat: {
-                    command: "npx",
-                    args: bridgeArgs(endpoint.url),
-                    env: { [AUTH_ENV]: header },
-                },
-            },
-        }, null, 2);
-        return {
-            client,
-            file: CLIENT_FILES[client],
-            format: "json",
-            body,
-            notes: [
-                "Claude Desktop launches stdio servers, so this bridges through `npx mcp-remote`.",
-                "Quit and reopen Claude Desktop after saving — it only reads the file at startup.",
-            ],
-        };
-    }
-    // Codex speaks Streamable HTTP natively. Keep this paste-ready by storing the
-    // bearer as a static header, matching Cursor's native configuration. The
-    // command already warns that the generated config contains a live secret.
-    const body = [
-        "[mcp_servers.baychat]",
-        `url = ${tomlString(endpoint.url)}`,
-        `http_headers = { Authorization = ${tomlString(header)} }`,
-    ].join("\n");
-    return {
-        client,
-        file: CLIENT_FILES[client],
-        format: "toml",
-        body,
-        notes: [
-            "Codex reads TOML — append this to the file, do not replace it.",
-            "Codex connects to the remote Streamable HTTP server directly.",
-        ],
-    };
-}
-/** What `baychat mcp-config` prints with no `--client`: the menu. It names no
- * credential, so it works — and is safe — when logged out. */
-function renderClientList() {
-    const rows = exports.MCP_CLIENTS.map((client) => `  baychat mcp-config --client ${client.padEnd(8)}→ ${CLIENT_FILES[client]}`);
-    return [
-        "BayChat exposes a remote MCP server (Streamable HTTP + a bearer header).",
-        "Pick your client and paste the config it prints:",
-        "",
-        ...rows,
-        "",
-        "Claude Code needs nothing — `baychat login` registers it for you.",
-        "The printed config embeds your device token: treat it like a password.",
-    ].join("\n");
-}
 /**
  * `baychat mcp-config [--client codex|cursor|desktop]`.
  *
@@ -199,11 +103,11 @@ function cmdMcpConfig(client) {
     if (client === undefined) {
         // The menu IS the requested output here (like `--help`), so it goes to
         // stdout — unlike the guidance that accompanies a generated config.
-        console.log(renderClientList());
+        console.log((0, mcp_dialects_1.renderClientList)());
         return;
     }
-    const target = parseClient(client);
-    const config = buildClientConfig(target, resolveMcpEndpoint());
+    const target = (0, mcp_dialects_1.parseClient)(client);
+    const config = (0, mcp_dialects_1.buildClientConfig)(target, resolveMcpEndpoint());
     console.error(`Add to ${config.file}:`);
     for (const note of config.notes)
         console.error(`  ${note}`);

package/dist/mcp-dialects.js

@@ -0,0 +1,143 @@
+"use strict";
+// MCP client config dialects — the PURE half of `baychat mcp-config`.
+//
+// WHY THIS FILE EXISTS SEPARATELY. Three surfaces need to know how each MCP
+// client spells its configuration: the CLI (`baychat mcp-config`), the mobile
+// app's "Connect an MCP client" screen, and any future web parity screen. Three
+// hand-written copies would drift the first time a client changed its dialect,
+// and the failure mode is silent — a user pastes a config that no longer works
+// and has no way to tell whose fault it is.
+//
+// So this module is the single source of truth, and it imports NOTHING: no
+// `fs`, no `./config`, no Node built-ins. That is a hard constraint, not a
+// style preference. `apps/mobile/scripts/sync-mcp-dialects.mjs` copies this
+// file verbatim into the React Native bundle, where a `node:fs` import would
+// fail the build. The impure half — reading the credentials file, resolving the
+// base url, printing to stdout — stays in `mcp-config.ts`, which re-exports
+// everything here so existing importers are unaffected.
+//
+// THE TOKEN IS A PASSWORD. Every config below embeds a live bearer credential.
+// It must never reach a child process's argv, where `ps` shows it to every user
+// on the box — hence the `${VAR}` + env form for the stdio clients.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CLIENT_LABELS = exports.CLIENT_FILES = exports.AUTH_ENV = exports.MCP_CLIENTS = void 0;
+exports.parseClient = parseClient;
+exports.buildClientConfig = buildClientConfig;
+exports.renderClientList = renderClientList;
+/** Clients `mcp-config` can generate for. Claude Code is absent on purpose:
+ * `baychat login` registers it automatically via `claude mcp add`. */
+exports.MCP_CLIENTS = ["codex", "cursor", "desktop"];
+/** The env var the stdio bridge expands the Authorization header from. */
+exports.AUTH_ENV = "BAYCHAT_AUTH_HEADER";
+/** Where each client keeps its MCP config. Named once so the menu and the
+ * generated config can never disagree about where the paste goes. */
+exports.CLIENT_FILES = {
+    codex: "~/.codex/config.toml",
+    cursor: "~/.cursor/mcp.json (or a project .cursor/mcp.json)",
+    desktop: "claude_desktop_config.json (Settings → Developer → Edit Config)",
+};
+/** Human-facing label per client, for a UI that lists them. */
+exports.CLIENT_LABELS = {
+    codex: "Codex",
+    cursor: "Cursor",
+    desktop: "Claude Desktop",
+};
+/**
+ * Narrow a `--client` value.
+ *
+ * @throws on anything unsupported, listing what IS supported — a typo must not
+ * silently fall through to a default client and produce a config for the wrong
+ * one.
+ */
+function parseClient(value) {
+    const match = exports.MCP_CLIENTS.find((c) => c === value);
+    if (!match) {
+        throw new Error(`Unknown --client "${value}" — supported: ${exports.MCP_CLIENTS.join(", ")}. ` +
+            "Claude Code is registered automatically by `baychat login`.");
+    }
+    return match;
+}
+/** A TOML basic string. Backslash first, then quote — the other order would
+ * double-escape the backslashes it just introduced. */
+function tomlString(value) {
+    return `"${value.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
+}
+/** The mcp-remote argv, used by stdio-only clients.
+ *
+ * `Authorization:${VAR}` with NO space is deliberate: mcp-remote expands the
+ * `${VAR}` from its own environment, and Claude Desktop mangles a header
+ * argument that contains a space. Passing the value by env rather than inline
+ * also keeps the credential out of the process listing. */
+function bridgeArgs(url) {
+    return ["-y", "mcp-remote", url, "--header", `Authorization:\${${exports.AUTH_ENV}}`];
+}
+/** The config for one client, ready to paste. Pure — no I/O, no logging. */
+function buildClientConfig(client, endpoint) {
+    const header = `Bearer ${endpoint.token}`;
+    if (client === "cursor") {
+        // Cursor speaks Streamable HTTP natively — no bridge needed.
+        const body = JSON.stringify({ mcpServers: { baychat: { url: endpoint.url, headers: { Authorization: header } } } }, null, 2);
+        return {
+            client,
+            file: exports.CLIENT_FILES[client],
+            format: "json",
+            body,
+            notes: ["Cursor connects to the remote server directly — restart Cursor after saving."],
+        };
+    }
+    if (client === "desktop") {
+        // Claude Desktop's config file launches stdio servers only, so the remote
+        // endpoint is fronted by the community mcp-remote bridge.
+        const body = JSON.stringify({
+            mcpServers: {
+                baychat: {
+                    command: "npx",
+                    args: bridgeArgs(endpoint.url),
+                    env: { [exports.AUTH_ENV]: header },
+                },
+            },
+        }, null, 2);
+        return {
+            client,
+            file: exports.CLIENT_FILES[client],
+            format: "json",
+            body,
+            notes: [
+                "Claude Desktop launches stdio servers, so this bridges through `npx mcp-remote`.",
+                "Quit and reopen Claude Desktop after saving — it only reads the file at startup.",
+            ],
+        };
+    }
+    // Codex speaks Streamable HTTP natively. Keep this paste-ready by storing the
+    // bearer as a static header, matching Cursor's native configuration. The
+    // command already warns that the generated config contains a live secret.
+    const body = [
+        "[mcp_servers.baychat]",
+        `url = ${tomlString(endpoint.url)}`,
+        `http_headers = { Authorization = ${tomlString(header)} }`,
+    ].join("\n");
+    return {
+        client,
+        file: exports.CLIENT_FILES[client],
+        format: "toml",
+        body,
+        notes: [
+            "Codex reads TOML — append this to the file, do not replace it.",
+            "Codex connects to the remote Streamable HTTP server directly.",
+        ],
+    };
+}
+/** What `baychat mcp-config` prints with no `--client`: the menu. It names no
+ * credential, so it works — and is safe — when logged out. */
+function renderClientList() {
+    const rows = exports.MCP_CLIENTS.map((client) => `  baychat mcp-config --client ${client.padEnd(8)}→ ${exports.CLIENT_FILES[client]}`);
+    return [
+        "BayChat exposes a remote MCP server (Streamable HTTP + a bearer header).",
+        "Pick your client and paste the config it prints:",
+        "",
+        ...rows,
+        "",
+        "Claude Code needs nothing — `baychat login` registers it for you.",
+        "The printed config embeds your device token: treat it like a password.",
+    ].join("\n");
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "baychat",
-  "version": "0.8.1",
-  "description": "BayChat connector CLI — pair an agent session (Claude Code, Codex) with BayChat and chat in groups",
+  "version": "0.8.2",
+  "description": "BayChat connector CLI \u2014 pair an agent session (Claude Code, Codex) with BayChat and chat in groups",
   "bin": {
     "baychat": "dist/index.js"
   },