@100xprompt/brain 0.0.0-stage → 0.1.0

package/src/gateway/connect.ts

@@ -0,0 +1,845 @@
+// `brain gateway login | connect | disconnect | status | tools`: point an AI coding tool at the 100xprompt gateway, and back.
+//
+// One command per tool, run by the person: `brain gateway connect --tool codex`. Nothing happens on install. Connecting
+// a tool changes which model it uses (100xprompt's models, billed to a 100xprompt account),
+// so it is always an explicit act, shown before it is done with --dry-run, and undone exactly by `disconnect`.
+//
+// How each change is made safe, as `brain mcp install` does it:
+//   - only the keys this command owns are written; everything else in the tool's file is left as it was;
+//   - the value each key had before is recorded (in <home>/.brain/gateway.json), and `disconnect` puts it back, or removes
+//     the key when there was none; a value the person changed since is left alone and reported;
+//   - the whole file is also copied once to <home>/.brain/backups/ before the first change;
+//   - writes are atomic and keep the file's mode; a file that cannot be parsed is left alone and reported.
+//
+// The key: `brain gateway login` signs in to 100xprompt in the browser, as `100xprompt auth login` does (signin.ts), and
+// stores the key that comes back in <home>/.brain/gateway.key (0600). For scripts and CI, --key-env VAR takes it from an
+// environment variable instead; --from-cli reuses the 100xprompt CLI's sign-in. It is never printed. Tools read it at run time where they can (Claude Code's apiKeyHelper,
+// OpenCode's {file:...}); Codex and Gemini CLI can only take it in their own config, which is then made private (0600).
+import { chmodSync, copyFileSync, existsSync, mkdirSync, readFileSync, realpathSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs"
+import { basename, dirname, join, resolve } from "node:path"
+import { askHidden, browserSignIn, type SignInDeps } from "./signin.ts"
+
+type Json = Record<string, any>
+
+export const DEFAULT_URL = "https://proxy.100xprompt.com"
+export const DEFAULT_ROUTE = "flash"
+export const DEFAULT_MODEL = "gemini-3.8-flash"
+
+/**
+ * What 100xprompt calls the models brain may connect a tool to, as the 100xprompt CLI shows them: tools are given the
+ * gateway's model id (that is what the gateway serves), and everything brain prints uses the product name.
+ */
+const MODEL_NAMES: Record<string, string> = { "gemini-3.8-flash": "100xprompt Pro", "gemini-3.7-flash": "100xprompt Flash", "gemini-3.6-flash": "100xprompt Flash" }
+/** `--model pro` / `--model flash`: the product names, turned into the gateway's model ids. */
+const MODEL_ALIASES: Record<string, string> = { pro: "gemini-3.8-flash", flash: "gemini-3.7-flash" }
+export const modelName = (id: string) => MODEL_NAMES[id] ?? id
+export const modelId = (given: string) => MODEL_ALIASES[given.trim().toLowerCase()] ?? given.trim()
+/** A value as connect and its dry run show it: the model ids in it by their product names. */
+const shownValue = (v: unknown) => Object.entries(MODEL_NAMES).reduce((t, [id, name]) => t.replaceAll(id, name), JSON.stringify(v))
+export const EDIT_HEADER = "x-100x-context-edit"
+
+export interface GatewaySettings {
+  url: string
+  route: string
+  model: string
+  /** Send `x-100x-context-edit: on` (the gateway clears old tool results when that saves money). */
+  contextEdit: boolean
+}
+
+/** What one connect changed in one file: the key (JSON path with "/", TOML or .env key) and the value it had before (undefined: absent). */
+interface Change {
+  file: string
+  format: Format
+  key: string
+  before: unknown
+  after: unknown
+}
+
+type Format = "json" | "toml" | "dotenv"
+
+/** One file a connector changes, and the values it sets there. */
+export interface FileEdit {
+  path: string
+  format: Format
+  values: Record<string, unknown>
+  /** The file holds the key: make it private (0600). */
+  holdsKey?: boolean
+}
+
+interface State {
+  settings?: GatewaySettings
+  keySource?: string
+  /** Who signed in (from the sign-in page), shown by status. */
+  email?: string
+  tools: Record<string, { at: string; changes: Change[]; created?: string[] }>
+}
+
+const brainDir = (home: string) => join(home, ".brain")
+export const statePath = (home: string) => join(brainDir(home), "gateway.json")
+export const keyPath = (home: string) => join(brainDir(home), "gateway.key")
+
+function loadState(home: string): State {
+  try {
+    const s = JSON.parse(readFileSync(statePath(home), "utf8"))
+    return { tools: {}, ...s }
+  } catch {
+    return { tools: {} }
+  }
+}
+
+function saveState(home: string, s: State) {
+  mkdirSync(brainDir(home), { recursive: true, mode: 0o700 })
+  writePrivate(statePath(home), `${JSON.stringify(s, null, 2)}\n`)
+}
+
+/** Atomic write with mode 0600 (the key and the record of what was changed). */
+function writePrivate(path: string, text: string) {
+  const tmp = `${path}.brain-tmp`
+  rmSync(tmp, { force: true })
+  writeFileSync(tmp, text, { mode: 0o600 })
+  chmodSync(tmp, 0o600)
+  renameSync(tmp, path)
+}
+
+/**
+ * Atomic write through a symlink, keeping the file's mode (or `mode` when given). With `backup`, the file as it was is
+ * first copied once to backups/: only on a tool's first connect, so a backup never holds the gateway key (a file that
+ * already has the key in it, at disconnect or a key refresh, is never copied).
+ */
+function writeToolFile(home: string, tool: string, path: string, text: string, mode: number | undefined, backup: boolean) {
+  const real = existsSync(path) ? realpathSync(path) : path
+  mkdirSync(dirname(real), { recursive: true })
+  const copy = join(brainDir(home), "backups", `gateway-${tool}-${basename(path)}`)
+  if (backup && existsSync(real) && !existsSync(copy)) {
+    mkdirSync(dirname(copy), { recursive: true, mode: 0o700 })
+    copyFileSync(real, copy)
+    chmodSync(copy, 0o600)
+  }
+  let keep: number | undefined = mode
+  if (keep === undefined) {
+    try {
+      keep = statSync(real).mode & 0o777
+    } catch {}
+  }
+  const tmp = `${real}.brain-tmp`
+  rmSync(tmp, { force: true })
+  writeFileSync(tmp, text, keep === undefined ? {} : { mode: keep })
+  if (keep !== undefined) chmodSync(tmp, keep)
+  renameSync(tmp, real)
+}
+
+// ---- the key ----------------------------------------------------------------------------------------------------------
+
+/**
+ * Where the 100xprompt CLI keeps its sign-in, resolved as the CLI does: under $HUNDREDXPROMPT_HOME (its isolated home,
+ * XDG ignored) when set, else $XDG_DATA_HOME, else ~/.local/share. XDG_DATA_HOME describes the person's real home, so it is
+ * followed only when brain works in that home (a throwaway BRAIN_HOME never reaches the real sign-in).
+ */
+export function cliAuthPath(home: string, env: Record<string, string | undefined> = process.env): string {
+  const iso = env.HUNDREDXPROMPT_HOME?.trim()
+  const xdg = env.XDG_DATA_HOME
+  const data = iso ? join(resolve(iso), ".local", "share") : xdg?.startsWith("/") && env.HOME && resolve(home) === resolve(env.HOME) ? xdg : join(home, ".local", "share")
+  return join(data, "100xprompt", "auth.json")
+}
+
+function keyFromCli(home: string, env: Record<string, string | undefined>): string | undefined {
+  try {
+    const a = JSON.parse(readFileSync(cliAuthPath(home, env), "utf8"))
+    const k = a?.["100xprompt"]?.key
+    return typeof k === "string" && k.trim() ? k.trim() : undefined
+  } catch {
+    return undefined
+  }
+}
+
+export function hasKey(home: string): boolean {
+  try {
+    return readFileSync(keyPath(home), "utf8").trim().length > 0
+  } catch {
+    return false
+  }
+}
+
+/** The stored key ("" when there is none: a dry run shows what would change without one). */
+const readKey = (home: string) => {
+  try {
+    return readFileSync(keyPath(home), "utf8").trim()
+  } catch {
+    return ""
+  }
+}
+
+/**
+ * Writes the key (0600, never printed) and where it came from. Tools that keep their own copy of the key (Codex, Gemini
+ * CLI) get the new one too, where their copy is still the old key: otherwise a sign-in to another account would leave them
+ * on the old one while status names the new. Returns the tools whose copy was replaced.
+ */
+export function storeKey(home: string, key: string, source: string, email?: string): string[] {
+  const old = readKey(home)
+  mkdirSync(brainDir(home), { recursive: true, mode: 0o700 })
+  writePrivate(keyPath(home), `${key}\n`)
+  const s = loadState(home)
+  s.keySource = source
+  if (email) s.email = email
+  else delete s.email
+  saveState(home, s)
+  return refreshKeyCopies(home, old, key)
+}
+
+/** Replaces `old` with `key` in the key copies connect wrote (only where the copy is still `old`: a changed one is left). */
+function refreshKeyCopies(home: string, old: string, key: string): string[] {
+  if (!old || old === key) return []
+  const st = loadState(home)
+  const done = new Set<string>()
+  for (const c of CONNECTORS) {
+    const rec = st.tools[c.id]
+    if (!rec) continue
+    for (const x of rec.changes.filter((y) => SECRET_KEYS.has(y.key))) {
+      const d = load(x.format, x.file)
+      if ("error" in d) continue
+      const cur = getKey(d, x.key)
+      if (x.key === "GEMINI_API_KEY") {
+        if (cur !== old) continue
+        setKey(d, x.key, key)
+      } else {
+        if (!cur || typeof cur !== "object" || (cur as Json).experimental_bearer_token !== old) continue
+        setKey(d, x.key, { ...(cur as Json), experimental_bearer_token: key })
+      }
+      writeToolFile(home, c.id, x.file, render(d), 0o600, false)
+      done.add(c.label)
+    }
+  }
+  return [...done]
+}
+
+/**
+ * Stores a key that is already on this machine: from `env[keyEnv]` (scripts, CI), or with `fromCli` from the 100xprompt
+ * CLI's sign-in. Signing in in the browser is `signIn` below.
+ */
+export function login(home: string, opts: { keyEnv?: string; fromCli?: boolean; env?: Record<string, string | undefined> } = {}): { ok: true; source: string; refreshed: string[] } | { ok: false; why: string } {
+  const env = opts.env ?? process.env
+  let key: string | undefined
+  let source: string
+  if (opts.keyEnv !== undefined && opts.fromCli) return { ok: false, why: "use --key-env or --from-cli, not both" }
+  if (opts.keyEnv !== undefined) {
+    // A key passed where its variable's name belongs (`--key-env "$KEY"`) must not be echoed back in the error.
+    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(opts.keyEnv)) return { ok: false, why: "--key-env takes the NAME of an environment variable (for example --key-env GATEWAY_KEY), not the key itself" }
+    key = env[opts.keyEnv]?.trim()
+    source = `the ${opts.keyEnv} environment variable`
+    if (!key) return { ok: false, why: `${opts.keyEnv} is empty or not set` }
+  } else if (opts.fromCli) {
+    key = keyFromCli(home, env)
+    source = "the 100xprompt CLI's sign-in"
+    if (!key) return { ok: false, why: "the 100xprompt CLI is not signed in here; run `brain gateway login` to sign in in the browser" }
+  } else return { ok: false, why: "say where the key comes from (--key-env VAR or --from-cli), or run `brain gateway login` to sign in in the browser" }
+  if (/\s/.test(key) || key.length < 8) return { ok: false, why: "that does not look like a gateway key" }
+  return { ok: true, source, refreshed: storeKey(home, key, source) }
+}
+
+/** Signs in in the browser (signin.ts) and stores the key that comes back. */
+export async function signIn(home: string, d: SignInDeps): Promise<{ ok: true; source: string; email?: string; refreshed: string[] } | { ok: false; why: string }> {
+  const r = await browserSignIn(d)
+  if (!r.ok) return r
+  const source = r.via === "browser" ? "signing in in the browser" : "a pasted key"
+  const refreshed = storeKey(home, r.key, source, r.email)
+  return { ok: true, source, ...(r.email ? { email: r.email } : {}), refreshed }
+}
+
+/** Forgets the key. Tools still connected stop working until the next login, which is said. */
+export function logout(home: string, env: Record<string, string | undefined> = process.env): string[] {
+  const had = hasKey(home)
+  rmSync(keyPath(home), { force: true })
+  const s = loadState(home)
+  delete s.keySource
+  delete s.email
+  if (existsSync(statePath(home))) saveState(home, s)
+  const out = [had ? `signed out: removed ${keyPath(home)}` : "not signed in; nothing to remove"]
+  const settings = s.settings ?? { url: DEFAULT_URL, route: DEFAULT_ROUTE, model: DEFAULT_MODEL, contextEdit: true }
+  const connected = CONNECTORS.filter((c) => s.tools[c.id])
+  const copies = connected.filter((c) => c.edits(home, settings, env).some((e) => e.holdsKey))
+  const readers = connected.filter((c) => !copies.includes(c))
+  const names = (cs: Connector[]) => cs.map((c) => c.label).join(" and ")
+  if (readers.length)
+    out.push(`${names(readers)} ${readers.length === 1 ? "reads" : "read"} the key from that file, so ${readers.length === 1 ? "it" : "they"} cannot reach the gateway until you sign in again (brain gateway login); brain gateway disconnect --tool <id> puts ${readers.length === 1 ? "it" : "them"} back as before.`)
+  if (copies.length)
+    out.push(`${names(copies)} ${copies.length === 1 ? "keeps its" : "keep their"} own copy of the key and still ${copies.length === 1 ? "reaches" : "reach"} the gateway with it (signing out here does not revoke a key): brain gateway disconnect --tool <id> removes the copy.`)
+  return out
+}
+
+// ---- connectors -------------------------------------------------------------------------------------------------------
+
+/** Dotted-path get/set/delete on JSON objects (keys never contain dots here except where quoted with a slash). */
+const split = (k: string) => k.split("/")
+function getAt(o: Json, key: string): unknown {
+  let cur: any = o
+  for (const p of split(key)) {
+    if (!cur || typeof cur !== "object" || !(p in cur)) return undefined
+    cur = cur[p]
+  }
+  return cur
+}
+function setAt(o: Json, key: string, v: unknown) {
+  const ps = split(key)
+  let cur: any = o
+  for (const p of ps.slice(0, -1)) {
+    if (!cur[p] || typeof cur[p] !== "object" || Array.isArray(cur[p])) cur[p] = {}
+    cur = cur[p]
+  }
+  cur[ps[ps.length - 1]!] = v
+}
+function deleteAt(o: Json, key: string) {
+  const ps = split(key)
+  const parents: any[] = [o]
+  let cur: any = o
+  for (const p of ps.slice(0, -1)) {
+    if (!cur || typeof cur !== "object") return
+    cur = cur[p]
+    parents.push(cur)
+  }
+  if (cur && typeof cur === "object") delete cur[ps[ps.length - 1]!]
+  // Drop objects this left empty (env: {} after the last key went), never the root.
+  for (let i = ps.length - 1; i >= 1; i--) {
+    const parent = parents[i - 1]
+    const child = parent?.[ps[i - 1]!]
+    if (child && typeof child === "object" && !Array.isArray(child) && !Object.keys(child).length) delete parent[ps[i - 1]!]
+  }
+}
+const same = (a: unknown, b: unknown) => JSON.stringify(a) === JSON.stringify(b)
+const shellQuote = (s: string) => `'${s.replace(/'/g, `'\\''`)}'`
+
+export interface Connector {
+  id: string
+  label: string
+  /** The main file it edits (shown in status), absolute. */
+  file(home: string, env: Record<string, string | undefined>): string
+  /** Folder or file that shows the tool has run here (relative to home), besides the main file or its folder. */
+  probe: string[]
+  /** Every file it changes, with the values to set. */
+  edits(home: string, s: GatewaySettings, env: Record<string, string | undefined>): FileEdit[]
+  /** How the key reaches the gateway from this tool, for the key check: header name. */
+  authHeader: "x-api-key" | "authorization" | "x-goog-api-key"
+  /** What the person should know (shown on connect). */
+  notes: string[]
+}
+
+const routeUrl = (s: GatewaySettings) => `${s.url.replace(/\/+$/, "")}/${s.route}`
+const claudeDir = (home: string, env: Record<string, string | undefined>) => (env.CLAUDE_CONFIG_DIR && existsSync(env.CLAUDE_CONFIG_DIR) ? env.CLAUDE_CONFIG_DIR : join(home, ".claude"))
+const codexDir = (home: string, env: Record<string, string | undefined>) => (env.CODEX_HOME && existsSync(env.CODEX_HOME) ? env.CODEX_HOME : join(home, ".codex"))
+const geminiDir = (home: string, env: Record<string, string | undefined>) => join(env.GEMINI_CLI_HOME && existsSync(env.GEMINI_CLI_HOME) ? env.GEMINI_CLI_HOME : home, ".gemini")
+
+export const CONNECTORS: Connector[] = [
+  {
+    id: "claude-code",
+    label: "Claude Code",
+    file: (home, env) => join(claudeDir(home, env), "settings.json"),
+    probe: [".claude", ".claude.json"],
+    authHeader: "x-api-key",
+    edits: (home, s, env) => [
+      {
+        path: join(claudeDir(home, env), "settings.json"),
+        format: "json",
+        values: {
+          "env/ANTHROPIC_BASE_URL": routeUrl(s),
+          "env/ANTHROPIC_MODEL": s.model,
+          "env/ANTHROPIC_DEFAULT_HAIKU_MODEL": s.model,
+          ...(s.contextEdit ? { "env/ANTHROPIC_CUSTOM_HEADERS": `${EDIT_HEADER}: on` } : {}),
+          apiKeyHelper: `cat ${shellQuote(keyPath(home))}`,
+        },
+      },
+    ],
+    notes: [
+      "Claude Code now runs on the gateway's model, not on Claude; its key is read from the brain's key file at each start (apiKeyHelper).",
+      "An ANTHROPIC_API_KEY or ANTHROPIC_AUTH_TOKEN exported in your shell takes precedence over the helper: unset it for Claude Code.",
+    ],
+  },
+  {
+    id: "codex",
+    label: "Codex",
+    file: (home, env) => join(codexDir(home, env), "config.toml"),
+    probe: [".codex"],
+    authHeader: "authorization",
+    edits: (home, s, env) => [
+      {
+        path: join(codexDir(home, env), "config.toml"),
+        format: "toml",
+        holdsKey: true,
+        values: {
+          model_provider: "brain-gateway",
+          model: s.model,
+          "model_providers/brain-gateway": {
+            name: "100xprompt gateway",
+            base_url: routeUrl(s),
+            wire_api: "responses",
+            experimental_bearer_token: readKey(home),
+            ...(s.contextEdit ? { http_headers: { [EDIT_HEADER]: "on" } } : {}),
+          },
+        },
+      },
+    ],
+    notes: ["Codex keeps the key in its config.toml (Codex has no key-file option), so the file is now readable by you only (0600)."],
+  },
+  {
+    id: "opencode",
+    label: "OpenCode",
+    file: (home) => join(home, ".config", "opencode", "opencode.json"),
+    probe: [".config/opencode"],
+    authHeader: "authorization",
+    edits: (home, s) => [
+      {
+        path: join(home, ".config", "opencode", "opencode.json"),
+        format: "json",
+        values: {
+          "provider/brain-gateway": {
+            npm: "@ai-sdk/openai-compatible",
+            name: "100xprompt gateway",
+            options: { baseURL: `${routeUrl(s)}/v1`, apiKey: `{file:${keyPath(home)}}`, ...(s.contextEdit ? { headers: { [EDIT_HEADER]: "on" } } : {}) },
+            models: { [s.model]: { name: modelName(s.model) } },
+          },
+          model: `brain-gateway/${s.model}`,
+        },
+      },
+    ],
+    notes: ["OpenCode reads the key from the brain's key file each time it starts."],
+  },
+  {
+    id: "gemini-cli",
+    label: "Gemini CLI",
+    file: (home, env) => join(geminiDir(home, env), ".env"),
+    probe: [".gemini"],
+    authHeader: "x-goog-api-key",
+    edits: (home, s, env) => [
+      { path: join(geminiDir(home, env), ".env"), format: "dotenv", holdsKey: true, values: { GOOGLE_GEMINI_BASE_URL: routeUrl(s), GEMINI_API_KEY: readKey(home), GEMINI_MODEL: s.model } },
+      { path: join(geminiDir(home, env), "settings.json"), format: "json", values: { "security/auth/selectedType": "gemini-api-key" } },
+    ],
+    notes: [
+      "Gemini CLI reads ~/.gemini/.env at start; the key is kept there, so the file is now readable by you only (0600). Its sign-in is set to API key.",
+      "Gemini CLI cannot send extra headers: context editing applies only when the gateway turns it on for everyone.",
+    ],
+  },
+]
+
+/** Keys whose value contains the key: recorded and shown without it. */
+const SECRET_KEYS = new Set(["GEMINI_API_KEY", "model_providers/brain-gateway"])
+
+export const connectorFor = (id: string) => CONNECTORS.find((c) => c.id === id || c.label.toLowerCase() === id.toLowerCase())
+
+// ---- reading and writing each format ---------------------------------------------------------------------------------
+
+type Doc = { kind: "json"; obj: Json; indent: string } | { kind: "toml"; text: string } | { kind: "dotenv"; lines: string[] }
+
+function load(format: Format, path: string): Doc | { error: string } {
+  let text = ""
+  if (existsSync(path)) {
+    try {
+      text = readFileSync(path, "utf8")
+    } catch (e) {
+      return { error: `cannot read it (${(e as Error).message})` }
+    }
+  }
+  if (format === "json") {
+    if (!text.trim()) return { kind: "json", obj: {}, indent: "  " }
+    try {
+      const v = JSON.parse(text)
+      if (!v || typeof v !== "object" || Array.isArray(v)) return { error: "it is not a JSON object; left as it is" }
+      return { kind: "json", obj: v, indent: text.match(/\n([ \t]+)"/)?.[1] ?? "  " }
+    } catch {
+      return { error: "it is not plain JSON (comments?); left as it is" }
+    }
+  }
+  if (format === "toml") {
+    if (text.trim()) {
+      try {
+        Bun.TOML.parse(text)
+      } catch {
+        return { error: "it is not valid TOML; left as it is" }
+      }
+    }
+    return { kind: "toml", text }
+  }
+  return { kind: "dotenv", lines: text ? text.replace(/\n$/, "").split("\n") : [] }
+}
+
+function render(d: Doc): string {
+  if (d.kind === "json") return `${JSON.stringify(d.obj, null, d.indent)}\n`
+  if (d.kind === "toml") return d.text.endsWith("\n") || !d.text ? d.text : `${d.text}\n`
+  return d.lines.length ? `${d.lines.join("\n")}\n` : ""
+}
+
+// TOML: top-level keys live before the first [table]; our table is [model_providers.brain-gateway].
+const tomlValue = (v: unknown): string =>
+  typeof v === "string" ? JSON.stringify(v) : typeof v === "number" || typeof v === "boolean" ? String(v) : `{ ${Object.entries(v as Json).map(([k, x]) => `${JSON.stringify(k)} = ${tomlValue(x)}`).join(", ")} }`
+const TABLE = "model_providers.brain-gateway"
+function tomlGet(text: string, key: string): unknown {
+  const parsed = text.trim() ? (Bun.TOML.parse(text) as Json) : {}
+  if (key === `model_providers/brain-gateway`) return parsed.model_providers?.["brain-gateway"]
+  return parsed[key]
+}
+function tomlTableRange(text: string): { start: number; end: number } | undefined {
+  const m = /^[ \t]*\[model_providers\.brain-gateway\][ \t]*(#.*)?$/m.exec(text)
+  if (!m) return undefined
+  const after = m.index + m[0].length
+  const n = /^[ \t]*\[/m.exec(text.slice(after))
+  return { start: m.index, end: n ? after + n.index : text.length }
+}
+function tomlSet(text: string, key: string, v: unknown): string {
+  if (key === "model_providers/brain-gateway") {
+    const r = tomlTableRange(text)
+    const cleaned = r ? text.slice(0, r.start) + text.slice(r.end) : text
+    if (v === undefined) return cleaned.replace(/\n{2,}$/, "\n")
+    const body = Object.entries(v as Json).map(([k, x]) => `${k} = ${tomlValue(x)}`).join("\n")
+    return `${cleaned.replace(/\n*$/, "")}${cleaned.trim() ? "\n\n" : ""}[${TABLE}]\n${body}\n`
+  }
+  // A top-level key: replace its line in the preamble (before the first table), or add it at the top.
+  const firstTable = /^[ \t]*\[/m.exec(text)
+  const pre = firstTable ? text.slice(0, firstTable.index) : text
+  const rest = firstTable ? text.slice(firstTable.index) : ""
+  const line = new RegExp(`^[ \\t]*${key.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}[ \\t]*=.*(?:\\n|$)`, "m")
+  let out: string
+  // A line that is replaced keeps its trailing comment (`model = "x"  # mine`), so disconnect gives the line back as it was.
+  if (line.test(pre)) out = v === undefined ? pre.replace(line, "") : pre.replace(line, (m) => `${key} = ${tomlValue(v)}${trailingComment(m.replace(/\n$/, ""))}\n`)
+  else out = v === undefined ? pre : `${key} = ${tomlValue(v)}\n${pre}`
+  return out + rest
+}
+
+/** The ` # comment` at the end of a TOML `key = value` line (a # outside any quoted string), with the spaces before it. */
+export function trailingComment(line: string): string {
+  let quote: string | undefined
+  for (let i = line.indexOf("=") + 1; i > 0 && i < line.length; i++) {
+    const c = line[i]
+    if (quote) {
+      if (c === "\\" && quote === '"') i++
+      else if (c === quote) quote = undefined
+    } else if (c === '"' || c === "'") quote = c
+    else if (c === "#") {
+      let j = i
+      while (j > 0 && /[ \t]/.test(line[j - 1]!)) j--
+      return line.slice(j).trimEnd()
+    }
+  }
+  return ""
+}
+
+// dotenv: KEY=value lines; ours are plain assignments (values quoted when needed).
+const dotenvLine = (k: string, v: string) => `${k}=${/[\s#"'$]/.test(v) ? JSON.stringify(v) : v}`
+function dotenvGet(lines: string[], key: string): string | undefined {
+  for (const l of lines) {
+    const m = new RegExp(`^\\s*(?:export\\s+)?${key}\\s*=\\s*(.*)$`).exec(l)
+    if (m) {
+      const raw = m[1]!.trim()
+      return /^".*"$/.test(raw) ? JSON.parse(raw) : /^'.*'$/.test(raw) ? raw.slice(1, -1) : raw
+    }
+  }
+  return undefined
+}
+function dotenvSet(lines: string[], key: string, v: string | undefined): string[] {
+  const re = new RegExp(`^\\s*(?:export\\s+)?${key}\\s*=`)
+  const i = lines.findIndex((l) => re.test(l))
+  const out = lines.slice()
+  if (v === undefined) {
+    if (i >= 0) out.splice(i, 1)
+    return out
+  }
+  if (i >= 0) out[i] = dotenvLine(key, v)
+  else out.push(dotenvLine(key, v))
+  return out
+}
+
+function getKey(d: Doc, key: string): unknown {
+  if (d.kind === "json") return getAt(d.obj, key)
+  if (d.kind === "toml") return tomlGet(d.text, key)
+  return dotenvGet(d.lines, key)
+}
+function setKey(d: Doc, key: string, v: unknown) {
+  if (d.kind === "json") return v === undefined ? deleteAt(d.obj, key) : setAt(d.obj, key, v)
+  if (d.kind === "toml") d.text = tomlSet(d.text, key, v)
+  else d.lines = dotenvSet(d.lines, key, v === undefined ? undefined : String(v))
+}
+
+// ---- the free key check ---------------------------------------------------------------------------------------------
+
+export interface Probe {
+  verdict: "accepted" | "rejected" | "unreachable"
+  /** The key is accepted but the account cannot use it now (quota or allowance used up): the gateway's own words. */
+  limit?: string
+}
+
+/**
+ * Asks the gateway whether it accepts this key the way the tool will send it (a model-list call: no model, no tokens).
+ * A key that is accepted on an account whose quota is used up is still accepted, with `limit` saying so: connecting is
+ * fine, but every request will fail until it resets, which the person should hear now and not from the tool later.
+ */
+export async function probeKey(home: string, c: Connector, s: GatewaySettings, fetchImpl: typeof fetch = fetch): Promise<Probe> {
+  const key = readKey(home)
+  const headers: Record<string, string> = c.authHeader === "authorization" ? { authorization: `Bearer ${key}` } : { [c.authHeader]: key }
+  const ctl = new AbortController()
+  const t = setTimeout(() => ctl.abort(), 8_000)
+  try {
+    const r = await fetchImpl(`${routeUrl(s)}/v1/models`, { headers, signal: ctl.signal, redirect: "error" })
+    // 401 is the gateway refusing the key. Anything else means the key got past authentication: the model list itself is
+    // not served (403 "models.list is not served"), which is fine, since nothing is generated.
+    if (r.status === 401) {
+      void r.body?.cancel().catch(() => {})
+      return { verdict: "rejected" }
+    }
+    // 402: monthly quota or daily free allowance used up; 429: weekly or 5-hour quota, or the per-minute rate limit
+    // (gone within a minute, so not worth a warning).
+    if (r.status === 402 || r.status === 429) {
+      let err: { type?: unknown; message?: unknown } | undefined
+      try {
+        err = JSON.parse((await r.text()).slice(0, 8_000))?.error
+      } catch {}
+      if (err?.type === "rate_limit_exceeded") return { verdict: "accepted" }
+      const said = typeof err?.message === "string" && err.message.trim() ? err.message : `the gateway answered HTTP ${r.status}`
+      const clean = (key ? said.replaceAll(key, "<key>") : said).replace(/[\u0000-\u001f\u007f]+/g, " ").trim()
+      return { verdict: "accepted", limit: clean.length > 300 ? `${clean.slice(0, 299)}…` : clean }
+    }
+    void r.body?.cancel().catch(() => {})
+    return { verdict: "accepted" }
+  } catch {
+    return { verdict: "unreachable" }
+  } finally {
+    clearTimeout(t)
+  }
+}
+
+// ---- connect / disconnect / status ------------------------------------------------------------------------------------
+
+export interface Result {
+  ok: boolean
+  lines: string[]
+}
+
+export function installedHere(c: Connector, home: string, env: Record<string, string | undefined>): boolean {
+  const f = c.file(home, env)
+  return existsSync(f) || existsSync(dirname(f)) || c.probe.some((p) => existsSync(join(home, p)))
+}
+
+export async function connect(
+  home: string,
+  toolId: string,
+  o: { settings?: Partial<GatewaySettings>; dryRun?: boolean; probe?: boolean; env?: Record<string, string | undefined>; fetchImpl?: typeof fetch } = {},
+): Promise<Result> {
+  const env = o.env ?? process.env
+  const c = connectorFor(toolId)
+  if (!c) return { ok: false, lines: [`unknown tool "${toolId}"; \`brain gateway tools\` lists the ones that can be connected`] }
+  if (!hasKey(home) && !o.dryRun) return { ok: false, lines: ["not signed in to the gateway yet: run `brain gateway login`"] }
+  const st = loadState(home)
+  const s: GatewaySettings = {
+    url: o.settings?.url ?? st.settings?.url ?? DEFAULT_URL,
+    route: o.settings?.route ?? st.settings?.route ?? DEFAULT_ROUTE,
+    model: o.settings?.model !== undefined ? modelId(o.settings.model) : (st.settings?.model ?? DEFAULT_MODEL),
+    contextEdit: o.settings?.contextEdit ?? st.settings?.contextEdit ?? true,
+  }
+  if (!/^https?:\/\/[^\s]+$/.test(s.url) || (/^http:/.test(s.url) && !/^http:\/\/(127\.0\.0\.1|localhost)(:|\/|$)/.test(s.url))) return { ok: false, lines: ["--url must be https:// (http:// only for a gateway on this machine)"] }
+  if (!/^[a-z0-9-]{1,40}$/.test(s.route)) return { ok: false, lines: ["--route must be a gateway route name such as flash or pro"] }
+  if (!/^[\w.:/-]{1,80}$/.test(s.model)) return { ok: false, lines: ["--model must be pro, flash or a plain model name"] }
+  const main = c.file(home, env)
+  if (!installedHere(c, home, env)) return { ok: false, lines: [`${c.label} has not been run on this machine (nothing at ${main}); run it once, then connect it`] }
+  let limit: string | undefined
+  if (o.probe !== false && !o.dryRun) {
+    const p = await probeKey(home, c, s, o.fetchImpl)
+    limit = p.limit
+    if (p.verdict === "rejected") return { ok: false, lines: [`the gateway at ${routeUrl(s)} refused the key the way ${c.label} sends it (${c.authHeader}); nothing was changed`] }
+    if (p.verdict === "unreachable") return { ok: false, lines: [`could not reach ${routeUrl(s)}; nothing was changed (pass --no-probe to connect anyway)`] }
+  }
+  // Read and check every file first: nothing is written unless all of them can be changed.
+  const edits = c.edits(home, s, env)
+  const docs: Array<{ e: FileEdit; d: Doc }> = []
+  for (const e of edits) {
+    const d = load(e.format, e.path)
+    if ("error" in d) return { ok: false, lines: [`${e.path}: ${d.error}; nothing was changed`] }
+    docs.push({ e, d })
+  }
+  const prior = st.tools[c.id]?.changes ?? []
+  const changes: Change[] = []
+  const shown: string[] = []
+  for (const { e, d } of docs) {
+    for (const [key, after] of Object.entries(e.values)) {
+      const current = getKey(d, key)
+      // A reconnect keeps the value from before the FIRST connect, so disconnect still restores the person's own.
+      const was = prior.find((x) => x.file === e.path && x.key === key)
+      changes.push({ file: e.path, format: e.format, key, before: was ? was.before : current, after: SECRET_KEYS.has(key) ? "(contains the key)" : after })
+      if (!same(current, after)) setKey(d, key, after)
+      shown.push(`  ${basename(e.path)}: ${key.replace(/\//g, ".")} = ${SECRET_KEYS.has(key) ? "(gateway settings and key)" : shownValue(after)}`)
+    }
+    // A key an earlier connect set that this one no longer wants (--no-context-edit after a connect with it): put it back now.
+    for (const x of prior) {
+      if (x.file !== e.path || x.key in e.values) continue
+      const current = getKey(d, x.key)
+      if (x.after === "(contains the key)" ? current !== undefined : same(current, x.after)) setKey(d, x.key, x.before)
+    }
+  }
+  const named = MODEL_NAMES[s.model] ? [`note: models are shown by their 100xprompt names; the files get the gateway's id for ${modelName(s.model)}`] : []
+  if (o.dryRun) return { ok: true, lines: [`would change:`, ...shown, ...named, ...c.notes.map((n) => `note: ${n}`)] }
+  const created = new Set(st.tools[c.id]?.created ?? [])
+  for (const { e } of docs) if (!existsSync(e.path)) created.add(e.path)
+  const first = !st.tools[c.id]
+  for (const { e, d } of docs) writeToolFile(home, c.id, e.path, render(d), e.holdsKey ? 0o600 : undefined, first)
+  st.settings = s
+  st.tools[c.id] = { at: new Date().toISOString(), changes, ...(created.size ? { created: [...created] } : {}) }
+  saveState(home, st)
+  return {
+    ok: true,
+    lines: [
+      `connected ${c.label} to ${routeUrl(s)} (${modelName(s.model)}${s.contextEdit ? ", context editing on" : ""})`,
+      ...(limit ? [`warning: the gateway accepts the key, but this account cannot use it right now: ${limit}`, `warning: ${c.label} will get that error on every request until the limit resets (or brain gateway disconnect --tool ${c.id} puts it back).`] : []),
+      "changed:",
+      ...shown,
+      ...c.notes.map((n) => `note: ${n}`),
+      `undo: brain gateway disconnect --tool ${c.id}`,
+    ],
+  }
+}
+
+export function disconnect(home: string, toolId: string, o: { dryRun?: boolean } = {}): Result {
+  const c = connectorFor(toolId)
+  if (!c) return { ok: false, lines: [`unknown tool "${toolId}"`] }
+  const st = loadState(home)
+  const rec = st.tools[c.id]
+  if (!rec) return { ok: true, lines: [`${c.label} is not connected by brain; nothing to undo`] }
+  const lines: string[] = []
+  for (const path of [...new Set(rec.changes.map((x) => x.file))]) {
+    const d = load(rec.changes.find((x) => x.file === path)!.format ?? "json", path)
+    if ("error" in d) {
+      lines.push(`${path}: ${d.error}`)
+      continue
+    }
+    for (const x of rec.changes.filter((y) => y.file === path)) {
+      const current = getKey(d, x.key)
+      // Our own value (or, for entries holding the key, still our provider/key entry): put back what was there before.
+      const ours = x.after === "(contains the key)" ? current !== undefined : same(current, x.after)
+      if (!ours) {
+        lines.push(`  ${basename(path)}: ${x.key.replace(/\//g, ".")} changed since connect; left as it is`)
+        continue
+      }
+      setKey(d, x.key, x.before)
+      lines.push(`  ${basename(path)}: ${x.key.replace(/\//g, ".")} ${x.before === undefined ? "removed" : "restored"}`)
+    }
+    if (o.dryRun) continue
+    const text = render(d)
+    // A file connect created and that holds nothing else now is removed, not left behind empty.
+    if (rec.created?.includes(path) && /^(\{\}\n?|\s*)$/.test(text)) rmSync(path, { force: true })
+    else writeToolFile(home, c.id, path, text, undefined, false)
+  }
+  if (!o.dryRun) {
+    delete st.tools[c.id]
+    saveState(home, st)
+  }
+  return { ok: true, lines: [`${o.dryRun ? "would disconnect" : "disconnected"} ${c.label}:`, ...lines] }
+}
+
+export function status(home: string, env: Record<string, string | undefined> = process.env): string[] {
+  const st = loadState(home)
+  const s = st.settings
+  const out = [
+    `gateway: ${s ? `${routeUrl(s)}, ${modelName(s.model)}, context editing ${s.contextEdit ? "on" : "off"}` : `${DEFAULT_URL}/${DEFAULT_ROUTE}, ${modelName(DEFAULT_MODEL)} (defaults; nothing connected yet)`}`,
+    `key: ${hasKey(home) ? `${st.email ? `signed in as ${st.email}; ` : ""}stored (from ${st.keySource ?? "an earlier login"}) in ${keyPath(home)}` : "not signed in (brain gateway login)"}`,
+    "",
+  ]
+  for (const c of CONNECTORS) {
+    const rec = st.tools[c.id]
+    const here = installedHere(c, home, env)
+    out.push(`${c.label.padEnd(12)} ${rec ? `connected since ${rec.at.slice(0, 10)}` : here ? "not connected" : "not installed here"}  (${c.file(home, env)})`)
+  }
+  return out
+}
+
+// ---- the command --------------------------------------------------------------------------------------------------------
+
+const USAGE = [
+  "brain gateway login [--no-browser]        sign in to 100xprompt in your browser, as `100xprompt auth login` does",
+  "brain gateway login --key-env VAR | --from-cli   take the key from VAR (scripts, CI) or from the 100xprompt CLI's sign-in",
+  "brain gateway logout                      forget the key",
+  "brain gateway connect --tool <id> [--model pro|flash] [--route flash] [--url https://...] [--no-context-edit | --context-edit] [--dry-run] [--no-probe]",
+  "brain gateway disconnect --tool <id> [--dry-run]",
+  "brain gateway status | tools",
+]
+
+export async function gatewayCommand(
+  args: string[],
+  home: string,
+  io: { out(l: string): void } = { out: (l) => console.log(l) },
+  deps: { env?: Record<string, string | undefined>; fetchImpl?: typeof fetch; signIn?: Partial<SignInDeps> } = {},
+): Promise<number> {
+  const [sub, ...rest] = args
+  // A value flag takes the word after it; a flag there instead (`--key-env --from-cli`) is a missing value, not the value.
+  const VALUE_FLAGS = ["key-env", "tool", "route", "model", "url"]
+  const flag = (n: string) => {
+    const i = rest.indexOf(`--${n}`)
+    const v = i >= 0 ? rest[i + 1] : undefined
+    return v === undefined || v.startsWith("--") ? undefined : v
+  }
+  const has = (n: string) => rest.includes(`--${n}`)
+  const env = deps.env ?? process.env
+  const print = (r: Result) => {
+    r.lines.forEach((l) => io.out(l))
+    return r.ok ? 0 : 1
+  }
+  const usageFor: Record<string, number[]> = { login: [0, 1], logout: [2], connect: [3], disconnect: [4] }
+  const missing = VALUE_FLAGS.find((n) => has(n) && flag(n) === undefined)
+  if (missing) {
+    io.out(`--${missing} needs a value`)
+    for (const i of usageFor[sub ?? ""] ?? []) io.out(`usage: ${USAGE[i]}`)
+    return 2
+  }
+  const refreshedNote = (labels: string[]) => {
+    if (labels.length) io.out(`the new key also replaced the old one in ${labels.join(" and ")}'s own config`)
+  }
+  // The browser sign-in, with a hidden paste prompt when there is a terminal to ask in.
+  const browserLogin = async () => {
+    const r = await signIn(home, { say: io.out, ask: process.stdin.isTTY ? askHidden : undefined, browser: !has("no-browser"), ...deps.signIn })
+    io.out(r.ok ? `signed in${r.email ? ` as ${r.email}` : ""}; gateway key stored in ${keyPath(home)} (mode 0600)` : `brain gateway login: ${r.why}`)
+    if (r.ok) refreshedNote(r.refreshed)
+    return r.ok
+  }
+  switch (sub) {
+    case "login": {
+      if (has("key-env") || has("from-cli")) {
+        const r = login(home, { ...(has("key-env") ? { keyEnv: flag("key-env") } : {}), fromCli: has("from-cli"), env })
+        io.out(r.ok ? `gateway key stored in ${keyPath(home)} (mode 0600), from ${r.source}` : `brain gateway login: ${r.why}`)
+        if (r.ok) refreshedNote(r.refreshed)
+        return r.ok ? 0 : 1
+      }
+      return (await browserLogin()) ? 0 : 1
+    }
+    case "logout":
+      logout(home, env).forEach((l) => io.out(l))
+      return 0
+    case "connect":
+    case "disconnect": {
+      const tool = flag("tool")
+      if (!tool) {
+        io.out(`usage: ${USAGE[sub === "connect" ? 3 : 4]}`)
+        return 2
+      }
+      if (sub === "disconnect") return print(disconnect(home, tool, { dryRun: has("dry-run") }))
+      const settings = { ...(flag("url") ? { url: flag("url")! } : {}), ...(flag("route") ? { route: flag("route")! } : {}), ...(flag("model") ? { model: flag("model")! } : {}), ...(has("no-context-edit") ? { contextEdit: false } : has("context-edit") ? { contextEdit: true } : {}) }
+      // Not signed in yet: sign in first, as the 100xprompt CLI would, then connect. Everything that can be checked here
+      // (the tool, its files, the flags) is checked first, so nobody signs in for a connect that was bound to fail.
+      if (!hasKey(home) && !has("dry-run")) {
+        const pre = await connect(home, tool, { settings, dryRun: true, env })
+        if (!pre.ok) return print(pre)
+        io.out("not signed in to the gateway yet; signing in first")
+        if (!(await browserLogin())) return 1
+      }
+      return print(
+        await connect(home, tool, {
+          settings,
+          dryRun: has("dry-run"),
+          probe: !has("no-probe"),
+          env,
+          ...(deps.fetchImpl ? { fetchImpl: deps.fetchImpl } : {}),
+        }),
+      )
+    }
+    case "status":
+      status(home, env).forEach((l) => io.out(l))
+      return 0
+    case "tools":
+      for (const c of CONNECTORS) io.out(`${c.id.padEnd(12)} ${c.label}: ${c.file(home, env)}`)
+      return 0
+    default:
+      USAGE.forEach((l) => io.out(l))
+      return sub ? 2 : 0
+  }
+}