@100xprompt/brain 0.1.0 → 0.1.1

package/src/gateway/common.ts

@@ -0,0 +1,232 @@
+// What every gateway connector shares: the settings, the shape of a connector, where the key lives, and the helpers a
+// connector needs to describe its edits. connect.ts does the reading, writing, recording and undoing; a connector only
+// says which files it changes and to what (src/gateway/connectors/<tool>.ts).
+import { existsSync, readFileSync } from "node:fs"
+import { join } from "node:path"
+
+export type Json = Record<string, any>
+export type Env = Record<string, string | undefined>
+
+export const DEFAULT_URL = "https://proxy.100xprompt.com"
+export const DEFAULT_ROUTE = "flash"
+export const DEFAULT_MODEL = "gemini-3.8-flash"
+export const EDIT_HEADER = "x-100x-context-edit"
+
+/**
+ * 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.
+ */
+export 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. */
+export 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()
+
+export interface GatewaySettings {
+  url: string
+  route: string
+  /** The gateway's model id (gemini-3.8-flash for 100xprompt Pro). Show it to people with modelName(). */
+  model: string
+  /** Send `x-100x-context-edit: on` (the gateway clears old tool results when that saves money). */
+  contextEdit: boolean
+}
+
+export const brainDir = (home: string) => join(home, ".brain")
+export const statePath = (home: string) => join(brainDir(home), "gateway.json")
+/** The gateway key, 0600, one line. A tool that can read a key from a file, a command or an env file should read it here. */
+export const keyPath = (home: string) => join(brainDir(home), "gateway.key")
+
+/** The stored key ("" when there is none: a dry run shows what would change without one). Never print it. */
+export function readKey(home: string): string {
+  try {
+    return readFileSync(keyPath(home), "utf8").trim()
+  } catch {
+    return ""
+  }
+}
+
+/**
+ * The gateway route's base address, e.g. https://proxy.100xprompt.com/flash. Under it the gateway serves, for every model:
+ *   /v1/chat/completions   OpenAI Chat Completions (Authorization: Bearer <key>)
+ *   /v1/responses          OpenAI Responses (Authorization: Bearer <key>)
+ *   /v1/messages           Anthropic Messages (x-api-key: <key>, or Authorization: Bearer)
+ *   /v1beta/models/<id>:generateContent and :streamGenerateContent   Gemini (x-goog-api-key: <key>)
+ * /v1/models answers 403 ("not served"), so a tool that insists on listing models first needs the model named in its config.
+ */
+export const routeUrl = (s: GatewaySettings) => `${s.url.replace(/\/+$/, "")}/${s.route}`
+
+/** Single-quoted for a POSIX shell. */
+export const shellQuote = (s: string) => `'${s.replace(/'/g, `'\\''`)}'`
+
+/** An env-overridable folder that only counts when it exists (CLAUDE_CONFIG_DIR, CODEX_HOME and the like). */
+export const dirFromEnv = (env: Env, name: string, fallback: string) => (env[name] && existsSync(env[name]!) ? env[name]! : fallback)
+
+/**
+ * A file format the core does not read itself (YAML, JSON with comments, a tool's own format): the connector reads and
+ * writes it. Keys are whatever the codec understands (for yamlTopLevel: a top-level key).
+ */
+export interface Codec {
+  /** undefined when the file can be changed safely; otherwise why not (the file is then left alone and nothing changes). */
+  check?(text: string): string | undefined
+  /** The value at `key` (undefined when absent), compared with what was written to tell whether it is still brain's. */
+  get(text: string, key: string): unknown
+  /** The whole text with `key` set to `value`, or removed when `value` is undefined. Everything else stays as it was. */
+  set(text: string, key: string, value: unknown): string
+}
+
+/**
+ *   json     plain JSON object; keys are paths with "/" (env/ANTHROPIC_BASE_URL). A file with comments is left alone.
+ *   toml     Codex's config.toml handling (top-level keys and the [model_providers.brain-gateway] table only).
+ *   dotenv   KEY=value lines.
+ *   custom   the edit's `codec` reads and writes it.
+ */
+export type Format = "json" | "toml" | "dotenv" | "custom"
+
+/** One file a connector changes, and the values it sets there. */
+export interface FileEdit {
+  path: string
+  format: Format
+  /** Required with format "custom". */
+  codec?: Codec
+  values: Record<string, unknown>
+  /** The file holds the key: it is made private (0600). */
+  holdsKey?: boolean
+  /** Keys among `values` whose value contains the key: never shown or recorded, and replaced when the person signs in again. */
+  secretKeys?: string[]
+}
+
+export interface Connector {
+  /** The id people pass to --tool, the same id brain uses for the tool's sessions where it has one. */
+  id: string
+  label: string
+  /** The main file it edits (shown in status), absolute. */
+  file(home: string, env: Env): string
+  /** Folders or files (relative to home) whose presence shows the tool has run here, besides the main file or its folder. */
+  probe: string[]
+  /** Every file it changes, with the values to set. Called often (status, dry runs, disconnect): no side effects. */
+  edits(home: string, s: GatewaySettings, env: Env): FileEdit[]
+  /** How this tool sends the key, for the free key check before connecting. */
+  authHeader: "x-api-key" | "authorization" | "x-goog-api-key"
+  /** What the person should know (shown on connect). */
+  notes: string[]
+}
+
+// ---- JSON paths --------------------------------------------------------------------------------------------------------
+
+const split = (k: string) => k.split("/")
+export 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
+}
+export 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
+}
+export 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]!]
+  }
+}
+
+// ---- YAML, top-level keys only ------------------------------------------------------------------------------------------
+
+/**
+ * A YAML scalar or flow collection. A plain string is written as it is when YAML reads it back as the same string
+ * (`local-model`, `https://host/v1`); anything else is JSON (valid YAML), which keeps "on", "no" and "1.0" strings.
+ */
+// Words and numbers YAML 1.1 readers (PyYAML: Aider, Hermes) take for booleans, null or numbers, though Bun's YAML 1.2
+// reads them as strings: they are always quoted.
+const YAML11_SPECIAL = /^(?:y|n|yes|no|on|off|true|false|null|~|[-+]?\.?(?:inf|nan)|[-+]?(?:0x[0-9a-f_]+|0o?[0-7_]+|0b[01_]+|[0-9][0-9_:]*(?:\.[0-9_]*)?(?:e[-+]?[0-9]+)?))$/i
+
+function yamlValue(v: unknown): string {
+  if (typeof v === "string" && /^[A-Za-z0-9_./@-][A-Za-z0-9_./:@+=-]*$/.test(v) && !YAML11_SPECIAL.test(v)) {
+    try {
+      if ((Bun.YAML.parse(`k: ${v}`) as Json).k === v) return v
+    } catch {}
+  }
+  return JSON.stringify(v)
+}
+
+/** The ` # comment` at the end of a one-line YAML entry (a # after a space, outside quotes), with the spaces before it. */
+function yamlComment(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 === "#" && /[ \t]/.test(line[i - 1]!)) {
+      let j = i
+      while (j > 0 && /[ \t]/.test(line[j - 1]!)) j--
+      return line.slice(j).trimEnd()
+    }
+  }
+  return ""
+}
+
+/**
+ * Edits top-level `key: value` entries of a YAML file and leaves every other line (comments included) exactly as it was.
+ * A value is written on one line (strings quoted; objects and lists in flow style, which YAML reads like block style). An
+ * existing entry is replaced together with its indented block, if it had one; an entry that is not there is added at the
+ * end. Keys are top-level names only (no paths).
+ */
+export const yamlTopLevel: Codec = {
+  check(text) {
+    if (!text.trim()) return undefined
+    if (/^---\s*$/m.test(text.replace(/^---\s*\n/, ""))) return "it holds more than one YAML document; left as it is"
+    try {
+      const v = Bun.YAML.parse(text)
+      if (v !== null && (typeof v !== "object" || Array.isArray(v))) return "it is not a YAML mapping; left as it is"
+    } catch {
+      return "it is not valid YAML; left as it is"
+    }
+    return undefined
+  },
+  get(text, key) {
+    if (!text.trim()) return undefined
+    const v = Bun.YAML.parse(text) as Json | null
+    return v && typeof v === "object" ? v[key] : undefined
+  },
+  set(text, key, value) {
+    const lines = text ? text.replace(/\n$/, "").split("\n") : []
+    const esc = key.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")
+    const head = new RegExp(`^(?:${esc}|"${esc}"|'${esc}')\\s*:(?:\\s|$)`)
+    const at = lines.findIndex((l) => head.test(l))
+    let end = at + 1
+    // The entry's block: the indented (or blank, or comment) lines that follow it, up to the next top-level line.
+    if (at >= 0) {
+      while (end < lines.length && (/^[ \t]/.test(lines[end]!) || lines[end]!.trim() === "" || /^[ \t]*-\s/.test(lines[end]!))) end++
+      // Blank lines and comments at the end of that run belong to whatever comes next, not to this entry.
+      while (end > at + 1 && (lines[end - 1]!.trim() === "" || /^\s*#/.test(lines[end - 1]!))) end--
+    }
+    // A one-line entry keeps its trailing comment, so a later restore gives the line back as it was.
+    const line = `${key}: ${yamlValue(value)}${at >= 0 && end === at + 1 ? yamlComment(lines[at]!) : ""}`
+    if (value === undefined) {
+      if (at >= 0) lines.splice(at, end - at)
+    } else if (at >= 0) lines.splice(at, end - at, line)
+    else lines.push(line)
+    return lines.length ? `${lines.join("\n")}\n` : ""
+  },
+}