getclaros 0.0.0-stage → 0.1.1

package/dist/clients.js

@@ -0,0 +1,428 @@
+// Agent clients' MCP configs: where they live, which servers they hold, and minimal edits to them.
+// Formats (checked against the official docs on 2026-10-22):
+// - Claude Code  https://code.claude.com/docs/en/mcp
+//     project `.mcp.json` {mcpServers: {name: {type?, command, args, env} | {type: "http", url, headers}}};
+//     `~/.claude.json` user scope at top-level `mcpServers`, local scope at `projects["<abs path>"].mcpServers`.
+//     No `type` means stdio.
+// - Claude Desktop  https://modelcontextprotocol.io/docs/develop/connect-local-servers
+//     macOS ~/Library/Application Support/Claude/claude_desktop_config.json, Windows %APPDATA%\Claude\…;
+//     {mcpServers: {name: {command, args, env}}}. Linux: ~/.config/Claude/… (community builds; not in the docs).
+// - Cursor  https://cursor.com/docs/context/mcp
+//     ~/.cursor/mcp.json and <project>/.cursor/mcp.json; {mcpServers: {name: {command, args, env, envFile} | {url, headers}}}.
+// - VS Code  https://code.visualstudio.com/docs/agents/reference/mcp-configuration
+//     <project>/.vscode/mcp.json and the profile's mcp.json (macOS ~/Library/Application Support/Code/User/mcp.json);
+//     JSONC {servers: {name: {type: "stdio", command, args, env, envFile} | {type: "http"|"sse", url, headers}}, inputs}.
+//     The old settings.json "mcp" key is migrated into mcp.json by VS Code itself
+//     (https://code.visualstudio.com/updates/v1_102), so settings.json is not edited.
+// - Codex  https://learn.chatgpt.com/docs/extend/mcp?surface=cli
+//     ~/.codex/config.toml ($CODEX_HOME) and trusted <project>/.codex/config.toml;
+//     [mcp_servers.<name>] command, args, env (table), cwd, enabled | url, bearer_token_env_var, http_headers.
+// JSON/JSONC files are edited with jsonc-parser (VS Code's own; zero deps): only the touched values change, comments
+// and formatting stay. TOML is edited by a small scanner below: only `command` / `args` values of the touched table
+// are replaced (or our own table appended / removed); every other byte, comments included, stays.
+// A remote (url) entry is rewritten into a stdio one running `guard --remote <url> --header "K: V"…`: its static
+// headers move into args (they stay in the same file; ${VAR} / ${input:…} substitution works in args too), and undo
+// rebuilds the url entry from them. No static header means OAuth (or a token from elsewhere): not guarded yet.
+import { createHash } from "node:crypto";
+import { chmodSync, existsSync, readFileSync, realpathSync, renameSync, statSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { applyEdits, findNodeAtLocation, modify, parse, parseTree } from "jsonc-parser";
+export const CLAROS = "claros"; // the name of the Claros MCP server entry init adds
+// how the configs launch us; overridable to dogfood an unpublished build (e.g. "node /path/to/dist/cli.js")
+export const launcher = () => (process.env.GETCLAROS_LAUNCHER || "npx -y getclaros").trim().split(/\s+/);
+export function locations(project) {
+    const h = homedir(), plat = process.platform;
+    const appData = process.env.APPDATA || join(h, "AppData", "Roaming"), xdg = process.env.XDG_CONFIG_HOME || join(h, ".config");
+    const support = (app) => plat === "darwin" ? join(h, "Library", "Application Support", app)
+        : plat === "win32" ? join(appData, app) : join(xdg, app);
+    const all = [
+        { client: "Claude Code", path: join(project, ".mcp.json"), key: "mcpServers", user: false },
+        { client: "Claude Code", path: join(h, ".claude.json"), key: "mcpServers", user: true, perProject: true },
+        { client: "Claude Desktop", path: join(support("Claude"), "claude_desktop_config.json"), key: "mcpServers", user: true },
+        { client: "Cursor", path: join(h, ".cursor", "mcp.json"), key: "mcpServers", user: true },
+        { client: "Cursor", path: join(project, ".cursor", "mcp.json"), key: "mcpServers", user: false },
+        { client: "VS Code", path: join(support("Code"), "User", "mcp.json"), key: "servers", user: true },
+        { client: "VS Code", path: join(project, ".vscode", "mcp.json"), key: "servers", user: false },
+        { client: "Codex", path: join(process.env.CODEX_HOME || join(h, ".codex"), "config.toml"), key: "mcp_servers", user: true, toml: true },
+        { client: "Codex", path: join(project, ".codex", "config.toml"), key: "mcp_servers", user: false, toml: true },
+    ];
+    return all.filter((l, i) => all.findIndex((x) => x.path === l.path) === i); // project = home → one entry
+}
+/** Every existing config file with its servers. Never writes. */
+export function detect(project) {
+    return locations(project).filter((l) => existsSync(l.path)).map((l) => load({ toml: false, perProject: false, ...l, text: readFileSync(l.path, "utf8"), servers: [] }));
+}
+/** (Re)parses f.text into f.servers. */
+export function load(f) {
+    f.servers = [];
+    f.error = undefined;
+    const add = (scope, name, entry) => {
+        if (!entry || typeof entry !== "object")
+            return;
+        const argv = argvOf(entry);
+        const remote = !entry.command && !!entry.url;
+        f.servers.push({ file: f, scope, name, entry, remote, guarded: guardAt(argv) > 0,
+            ours: name === CLAROS && isClarosEntry(argv), gap: remote ? remoteGap(entry) : "" });
+    };
+    if (f.toml) {
+        try {
+            const ts = tomlScan(f.text);
+            for (const t of ts.filter((x) => !x.array && x.path.length === 2 && x.path[0] === f.key)) {
+                const h = ts.find((x) => isHeaders(x, f.key, t.path[1])); // [mcp_servers.<name>.http_headers]
+                add([f.key], t.path[1], { ...Object.fromEntries(t.keys.map((k) => [k.key, k.value])),
+                    ...(h ? { http_headers: Object.fromEntries(h.keys.map((k) => [k.key, k.value])) } : {}) });
+            }
+        }
+        catch (e) {
+            f.error = e.message;
+        }
+        return f;
+    }
+    const errors = [];
+    const doc = parse(f.text, errors, { allowTrailingComma: true }) ?? {};
+    if (errors.length || typeof doc !== "object") {
+        f.error = "not valid JSON";
+        return f;
+    }
+    const scopes = [[f.key], ...(f.perProject ? Object.keys(doc.projects ?? {}).map((p) => ["projects", p, f.key]) : [])];
+    for (const s of scopes) {
+        const obj = s.reduce((o, k) => o?.[k], doc);
+        if (obj && typeof obj === "object")
+            for (const [n, e] of Object.entries(obj))
+                add(s, n, e);
+    }
+    return f;
+}
+// ---- wrapping ----
+export const argvOf = (e) => e?.command ? [String(e.command), ...(Array.isArray(e.args) ? e.args.map(String) : [])] : [];
+/** index of "guard" in a guarded command line (`… getclaros guard --server x -- original`), else -1 */
+export function guardAt(argv) {
+    for (let i = 1; i < argv.length; i++) {
+        if (argv[i] === "guard" && /getclaros|[\\/]dist[\\/]cli\.js$/.test(argv[i - 1]) &&
+            (argv.indexOf("--", i) > i || argv.indexOf("--remote", i) > i))
+            return i;
+    }
+    return -1;
+}
+/** A remote entry's static headers: `headers` (JSON clients), `http_headers` (Codex). */
+const headersOf = (e) => Object.entries(e.headers ?? e.http_headers ?? {}).map(([k, v]) => [k, String(v)]);
+export function remoteGap(e) {
+    if (/sse/i.test(String(e.type ?? "")))
+        return "legacy SSE – not guarded yet";
+    if (e.bearer_token_env_var || e.env_http_headers || e.headersHelper)
+        return "token from an env var or helper – not guarded yet";
+    return headersOf(e).length ? "" : "needs OAuth – not guarded yet";
+}
+/** The url and headers a remote guard command line carries. */
+function remoteOf(argv) {
+    const g = guardAt(argv), headers = [];
+    for (let i = g; i < argv.length; i++) {
+        if (argv[i] !== "--header")
+            continue;
+        const h = argv[++i] ?? "", c = h.indexOf(":");
+        headers.push([h.slice(0, c).trim(), h.slice(c + 1).trim()]);
+    }
+    return { url: argv[argv.indexOf("--remote", g) + 1], headers };
+}
+const isClarosEntry = (argv) => guardAt(argv) < 0 && argv.at(-1) === "mcp" && /getclaros|[\\/]dist[\\/]cli\.js$/.test(argv.at(-2) ?? "");
+export const clarosEntry = (f) => {
+    const [command, ...args] = [...launcher(), "mcp"];
+    return f.client === "VS Code" ? { type: "stdio", command, args } : { command, args };
+};
+// ---- edits: each returns the new text; call load(f) after changing f.text ----
+const fmt = (text) => {
+    const ind = text.match(/^([ \t]+)\S/m)?.[1] ?? "  ";
+    return { insertSpaces: !ind.startsWith("\t"), tabSize: ind.startsWith("\t") ? 1 : ind.length, eol: text.includes("\r\n") ? "\r\n" : "\n" };
+};
+const jset = (text, path, value) => applyEdits(text, modify(text, path, value, { formattingOptions: fmt(text) }));
+const apply = (text, edits) => edits.sort((a, b) => b[0] - a[0]).reduce((t, [a, b, r]) => t.slice(0, a) + r + t.slice(b), text);
+const q = (x) => JSON.stringify(x); // a JSON string is also a TOML basic string
+/** Where a server's command value and args array sit in the file text. */
+function spans(f, s) {
+    if (f.toml) {
+        const keys = tomlTable(f.text, f.key, s.name)?.keys;
+        const c = keys?.find((k) => k.key === "command"), a = keys?.find((k) => k.key === "args");
+        if (!c)
+            throw new Error(`[${f.key}.${s.name}] has no command to edit`);
+        return { cmd: [c.from, c.to], args: a?.items && { open: a.from, items: a.items },
+            addArgs: (text, args) => {
+                const c2 = tomlTable(text, f.key, s.name).keys.find((k) => k.key === "command"), eol = text.indexOf("\n", c2.to);
+                return eol < 0 ? `${text}\nargs = ${tomlArray(args)}\n` : apply(text, [[eol + 1, eol + 1, `args = ${tomlArray(args)}\n`]]);
+            } };
+    }
+    const root = parseTree(f.text), at = (k) => findNodeAtLocation(root, [...s.scope, s.name, k]);
+    const c = at("command"), a = at("args");
+    if (!c)
+        throw new Error(`${s.name} has no command to edit`);
+    return { cmd: [c.offset, c.offset + c.length], args: a?.type === "array" ? { open: a.offset,
+            items: (a.children ?? []).map((n) => [n.offset, n.offset + n.length]) } : undefined,
+        addArgs: (text, args) => jset(text, [...s.scope, s.name, "args"], args) };
+}
+/** command → the launcher; the launcher's args, `guard --server <name> --` and the original command go in front of
+ *  the original args. Only inserts: the original args array keeps its layout and comments, the entry its env. */
+export function wrapServer(f, s) {
+    if (s.remote)
+        return wrapRemote(f, s);
+    const L = launcher(), sp = spans(f, s), front = [...L.slice(1), "guard", "--server", s.name, "--", argvOf(s.entry)[0]];
+    if (!sp.args)
+        return sp.addArgs(apply(f.text, [[sp.cmd[0], sp.cmd[1], q(L[0])]]), front);
+    const at = sp.args.open + 1, sep = sp.args.items.length ? (/\s/.test(f.text[at]) ? "," : ", ") : "";
+    return apply(f.text, [[sp.cmd[0], sp.cmd[1], q(L[0])], [at, at, front.map(q).join(", ") + sep]]);
+}
+/** The inverse, from whatever the entry holds now: drops everything up to the original command. */
+export function unwrapServer(f, s) {
+    if (argvOf(s.entry).indexOf("--remote", guardAt(argvOf(s.entry))) > 0)
+        return unwrapRemote(f, s);
+    const argv = argvOf(s.entry), d = argv.indexOf("--", guardAt(argv)), sp = spans(f, s); // args[d] = the original command
+    const it = sp.args?.items;
+    if (!it || it.length <= d)
+        throw new Error(`${s.name}: not a guard command line`);
+    let end = it[d][1];
+    if (it.length > d + 1) {
+        end = f.text.indexOf(",", end) + 1;
+        if (f.text[end] === " ")
+            end++;
+    }
+    return apply(f.text, [[sp.cmd[0], sp.cmd[1], q(argv[d + 1])], [it[0][0], end, ""]]);
+}
+const lineOf = (t, from, to) => {
+    const e = t.indexOf("\n", to);
+    return [t.lastIndexOf("\n", from - 1) + 1, e < 0 ? t.length : e + 1];
+};
+/** url (+ headers) → command + args running the guard against that url; other keys (env, timeouts) stay. */
+function wrapRemote(f, s) {
+    if (s.gap)
+        throw new Error(`${s.name}: ${s.gap}`);
+    const L = launcher(), args = [...L.slice(1), "guard", "--server", s.name, "--remote", String(s.entry.url),
+        ...headersOf(s.entry).flatMap(([k, v]) => ["--header", `${k}: ${v}`])];
+    if (f.toml) {
+        const ts = tomlScan(f.text), t = ts.find((x) => isTable(x, f.key, s.name)), eol = fmt(f.text).eol;
+        const url = t.keys.find((k) => k.key === "url"), h = t.keys.find((k) => k.key === "http_headers");
+        const sub = ts.find((x) => isHeaders(x, f.key, s.name));
+        const [from, end] = lineOf(f.text, url.from, url.to); // `url = …` → `command = …`, a comment after it stays
+        return apply(f.text, [[from, url.to, `command = ${q(L[0])}`], // the header line's removal goes before args' insert
+            ...(h ? [[...lineOf(f.text, h.from, h.to), ""]] : []), ...(sub ? [[sub.start, sub.end, ""]] : []),
+            [end, end, `${f.text[end - 1] === "\n" ? "" : eol}args = ${tomlArray(args)}${eol}`]]);
+    }
+    const at = [...s.scope, s.name];
+    let t = f.text;
+    for (const k of ["url", "headers"])
+        t = jset(t, [...at, k], undefined);
+    t = jset(t, [...at, "type"], f.client === "VS Code" ? "stdio" : undefined);
+    return jset(jset(t, [...at, "command"], L[0]), [...at, "args"], args);
+}
+/** The inverse: the url entry back from the guard's command line (the backup restores it byte for byte). */
+function unwrapRemote(f, s) {
+    const { url, headers } = remoteOf(argvOf(s.entry));
+    if (f.toml) {
+        const keys = tomlTable(f.text, f.key, s.name).keys, eol = fmt(f.text).eol;
+        const c = keys.find((k) => k.key === "command"), a = keys.find((k) => k.key === "args");
+        const h = headers.length ? `http_headers = { ${headers.map(([k, v]) => `${q(k)} = ${q(v)}`).join(", ")} }${eol}` : "";
+        return apply(f.text, [[lineOf(f.text, c.from, c.to)[0], c.to, `url = ${q(url)}${a || !h ? "" : eol + h.trimEnd()}`],
+            ...(a ? [[...lineOf(f.text, a.from, a.to), h]] : [])]);
+    }
+    const at = [...s.scope, s.name];
+    let t = jset(jset(f.text, [...at, "command"], undefined), [...at, "args"], undefined);
+    t = jset(t, [...at, "type"], ["VS Code", "Claude Code"].includes(f.client) ? "http" : undefined);
+    t = jset(t, [...at, "url"], url);
+    return headers.length ? jset(t, [...at, "headers"], Object.fromEntries(headers)) : t;
+}
+/** Adds our Claros entry at the file's top-level server map. */
+export function addClaros(f) {
+    if (!f.toml) { // after the last server, on its own line; jsonc's modify would reformat the neighbours
+        const obj = findNodeAtLocation(parseTree(f.text), [f.key]), last = obj?.children?.at(-1);
+        if (obj?.type !== "object" || !last)
+            return jset(f.text, [f.key, CLAROS], clarosEntry(f));
+        const at = last.offset + last.length, indent = /^[ \t]*/.exec(f.text.slice(f.text.lastIndexOf("\n", last.offset) + 1))[0];
+        return apply(f.text, [[at, at, `,${fmt(f.text).eol}${indent}${q(CLAROS)}: ${JSON.stringify(clarosEntry(f))}`]]);
+    }
+    const [command, ...args] = [...launcher(), "mcp"];
+    const sep = f.text === "" || f.text.endsWith("\n\n") ? "" : f.text.endsWith("\n") ? "\n" : "\n\n";
+    return `${f.text}${sep}[${f.key}.${CLAROS}]\ncommand = ${JSON.stringify(command)}\nargs = ${tomlArray(args)}\n`;
+}
+export function removeEntry(f, s) {
+    if (!f.toml) { // the property and the comma before it (or after it, when first): the inverse of addClaros
+        const props = findNodeAtLocation(parseTree(f.text), s.scope)?.children ?? [];
+        const k = props.findIndex((p) => p.children?.[0]?.value === s.name), p = props[k];
+        if (k < 0)
+            return f.text;
+        if (k > 0)
+            return apply(f.text, [[props[k - 1].offset + props[k - 1].length, p.offset + p.length, ""]]);
+        return props.length > 1 ? apply(f.text, [[p.offset, props[1].offset, ""]]) : jset(f.text, [...s.scope, s.name], undefined);
+    }
+    const ts = tomlScan(f.text), i = ts.findIndex((x) => isTable(x, f.key, s.name));
+    if (i < 0)
+        return f.text;
+    // its own sub-tables ([mcp_servers.claros.env]) go too; the blank line we added before it as well
+    let end = i + 1;
+    while (end < ts.length && ts[end].path[0] === f.key && ts[end].path[1] === s.name)
+        end++;
+    const from = ts[i].start, to = ts[end - 1].end; // comments after its last key stay
+    const before = f.text.slice(0, from).replace(/\n\n$/, "\n");
+    return before + f.text.slice(to);
+}
+// ---- files ----
+export const sha = (s) => createHash("sha256").update(s).digest("hex");
+/** Write via a temp file + rename in the same directory, keeping the file's mode; follows a symlinked config. */
+export function writeAtomic(path, text) {
+    const real = realpathSync(path), mode = statSync(real).mode & 0o777, tmp = `${real}.getclaros-${process.pid}.tmp`;
+    writeFileSync(tmp, text, { mode });
+    chmodSync(tmp, mode);
+    renameSync(tmp, real);
+}
+const isTable = (x, key, name) => !x.array && x.path.length === 2 && x.path[0] === key && x.path[1] === name;
+const isHeaders = (x, key, name) => !x.array && x.path.length === 3 && x.path[0] === key && x.path[1] === name && x.path[2] === "http_headers";
+const tomlTable = (t, key, name) => tomlScan(t).find((x) => isTable(x, key, name));
+const tomlArray = (a) => `[${a.map((x) => JSON.stringify(x)).join(", ")}]`; // JSON strings are TOML basic strings
+export function tomlScan(t) {
+    const tables = [{ path: [], array: false, start: 0, end: 0, keys: [] }];
+    let i = 0, items = []; // element spans of the array value() read last
+    const ws = () => { while (t[i] === " " || t[i] === "\t")
+        i++; };
+    const eol = () => {
+        ws();
+        if (t[i] === "#")
+            while (i < t.length && t[i] !== "\n")
+                i++;
+        if (t[i] === "\r")
+            i++;
+        if (i < t.length && t[i] !== "\n")
+            throw new Error(`TOML: unexpected "${t[i]}" at ${i}`);
+        i++;
+    };
+    const keyPath = (stop) => {
+        const parts = [];
+        for (;;) {
+            ws();
+            if (t[i] === '"' || t[i] === "'")
+                parts.push(value());
+            else {
+                const m = /^[A-Za-z0-9_-]+/.exec(t.slice(i, i + 256));
+                if (!m)
+                    throw new Error(`TOML: bad key at ${i}`);
+                parts.push(m[0]);
+                i += m[0].length;
+            }
+            ws();
+            if (t[i] === ".") {
+                i++;
+                continue;
+            }
+            if (!stop.includes(t[i]))
+                throw new Error(`TOML: expected ${stop} at ${i}`);
+            return parts;
+        }
+    };
+    const gap = () => {
+        for (;;) {
+            while (/\s/.test(t[i] ?? ""))
+                i++;
+            if (t[i] !== "#")
+                return;
+            while (i < t.length && t[i] !== "\n")
+                i++;
+        }
+    };
+    function value() {
+        const c = t[i];
+        if (t.startsWith('"""', i) || t.startsWith("'''", i)) {
+            const q = t.slice(i, i + 3), end = t.indexOf(q, i + 3);
+            if (end < 0)
+                throw new Error("TOML: unterminated string");
+            let e = end + 3;
+            while (t[e] === q[0])
+                e++; // up to two quotes may end the content
+            const raw = t.slice(i + 3, e - 3).replace(/^\r?\n/, "");
+            i = e;
+            return q === "'''" ? raw : unescape(raw.replace(/\\\r?\n\s*/g, ""));
+        }
+        if (c === "'") {
+            const end = t.indexOf("'", i + 1);
+            const v = t.slice(i + 1, end);
+            i = end + 1;
+            return v;
+        }
+        if (c === '"') {
+            let j = i + 1;
+            while (j < t.length && t[j] !== '"')
+                j += t[j] === "\\" ? 2 : 1;
+            const v = unescape(t.slice(i + 1, j));
+            i = j + 1;
+            return v;
+        }
+        if (c === "[") {
+            i++;
+            const out = [], spans = [];
+            for (;;) {
+                gap();
+                if (t[i] === "]") {
+                    i++;
+                    items = spans;
+                    return out;
+                }
+                const from = i;
+                out.push(value());
+                spans.push([from, i]);
+                gap();
+                if (t[i] === ",")
+                    i++;
+                else if (t[i] !== "]")
+                    throw new Error(`TOML: bad array at ${i}`);
+            }
+        }
+        if (c === "{") {
+            i++;
+            const out = {};
+            for (;;) {
+                gap();
+                if (t[i] === "}") {
+                    i++;
+                    return out;
+                }
+                const k = keyPath("=");
+                i++;
+                ws();
+                out[k.join(".")] = value();
+                gap();
+                if (t[i] === ",")
+                    i++;
+            }
+        }
+        const m = /^[^\s,\]}#]+/.exec(t.slice(i, i + 256));
+        if (!m)
+            throw new Error(`TOML: bad value at ${i}`);
+        i += m[0].length;
+        return m[0] === "true" ? true : m[0] === "false" ? false : Number.isNaN(Number(m[0].replace(/_/g, ""))) ? m[0] : Number(m[0].replace(/_/g, ""));
+    }
+    while (i < t.length) {
+        const lineStart = i;
+        ws();
+        if (t[i] === "\n" || t[i] === "\r" || t[i] === "#" || i >= t.length) {
+            eol();
+            continue;
+        }
+        if (t[i] === "[") {
+            const array = t[i + 1] === "[";
+            i += array ? 2 : 1;
+            const path = keyPath("]");
+            i += array ? 2 : 1;
+            tables.push({ path, array, start: lineStart, end: 0, keys: [] });
+            eol();
+            tables.at(-1).end = Math.min(i, t.length);
+            continue;
+        }
+        const k = keyPath("=");
+        i++;
+        ws();
+        const from = i, v = value();
+        tables.at(-1).keys.push({ key: k.join("."), value: v, from, to: i, ...(Array.isArray(v) ? { items } : {}) });
+        eol();
+        tables.at(-1).end = Math.min(i, t.length);
+    }
+    return tables;
+}
+function unescape(s) {
+    const map = { b: "\b", t: "\t", n: "\n", f: "\f", r: "\r", e: "\x1b", '"': '"', "\\": "\\" };
+    return s.replace(/\\(u[0-9a-fA-F]{4}|U[0-9a-fA-F]{8}|x[0-9a-fA-F]{2}|.)/g, (_, e) => e.length > 1 ? String.fromCodePoint(parseInt(e.slice(1), 16)) : map[e] ?? e);
+}

package/dist/config.js

@@ -0,0 +1,77 @@
+// Where `getclaros init` keeps the Claros URL and key: one file, 0600, in a 0700 directory
+// ($XDG_CONFIG_HOME or ~/.config)/getclaros/config.json. The guard and the Claros MCP bridge read it, so the key never
+// lands in an agent client's config (project files like .mcp.json are often committed).
+import { chmodSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+// The web app says where its server is (GET <web>/.well-known/claros.json → {"api": …}), so a moved server needs no
+// new package: the CLI asks the web origin when it has no URL, and asks again when the saved one stops answering.
+export const DEFAULT_WEB = "https://claros-eta.vercel.app";
+const LEGACY_URL = "https://claros-server.onrender.com"; // configs from before discovery: follow the web app
+const trim = (u) => u.replace(/\/+$/, "");
+export const cfgDir = () => join(process.env.XDG_CONFIG_HOME || join(homedir(), ".config"), "getclaros");
+export function loadConfig() {
+    try {
+        return JSON.parse(readFileSync(join(cfgDir(), "config.json"), "utf8"));
+    }
+    catch {
+        return {};
+    }
+}
+export function saveConfig(c) {
+    const dir = cfgDir(), file = join(dir, "config.json"), tmp = `${file}.${process.pid}.tmp`;
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    chmodSync(dir, 0o700);
+    writeFileSync(tmp, JSON.stringify(c, null, 2) + "\n", { mode: 0o600 });
+    renameSync(tmp, file);
+    return file;
+}
+/** <web>/.well-known/claros.json → the server URL. Throws why not. */
+export async function discover(web) {
+    const r = await fetch(`${web}/.well-known/claros.json`, { signal: AbortSignal.timeout(10_000) });
+    if (!r.ok)
+        throw new Error(`HTTP ${r.status}`);
+    const api = (await r.json().catch(() => null))?.api;
+    if (typeof api !== "string" || !/^https?:\/\/\S+$/.test(api))
+        throw new Error("no server URL in it");
+    return trim(api);
+}
+/** --url / CLAROS_URL → saved (unless --web / CLAROS_WEB names another web origin) → discovered from the web origin
+ *  (--web / CLAROS_WEB / saved / DEFAULT_WEB) → throws. A discovered URL replaces the saved one. */
+export async function resolve(flags = {}) {
+    const s = loadConfig();
+    const key = flags.key ?? process.env.CLAROS_KEY ?? s.key ?? "";
+    const asked = flags.web ?? process.env.CLAROS_WEB;
+    const web = trim(asked ?? s.web ?? DEFAULT_WEB);
+    const fixed = flags.url ?? process.env.CLAROS_URL;
+    if (fixed)
+        return { url: trim(fixed), key, web, source: "pinned" };
+    if (s.url && (!asked || trim(asked) === s.web)) {
+        return { url: trim(s.url), key, web, source: s.web || trim(s.url) === LEGACY_URL ? "saved" : "pinned" };
+    }
+    let url;
+    try {
+        url = await discover(web);
+    }
+    catch (e) {
+        throw new Error(`couldn't find the Claros server: ${web}/.well-known/claros.json: ${e.message}. ` +
+            "Pass --url <claros server> or set CLAROS_URL (or --web / CLAROS_WEB for another web app).");
+    }
+    if (s.key || s.url)
+        saveConfig({ ...s, url, web });
+    return { url, key, web, source: "discovered" };
+}
+/** After a connection failure: asks the web origin again. true = the server moved (r.url and the saved config are
+ *  updated); false = same URL, discovery failed, or the URL is pinned. */
+export async function relocate(r) {
+    if (r.source === "pinned")
+        return false;
+    const url = await discover(r.web).catch(() => r.url);
+    if (url === r.url)
+        return false;
+    r.url = url;
+    const s = loadConfig();
+    if (s.key || s.url)
+        saveConfig({ ...s, url, web: r.web });
+    return true;
+}

package/dist/peers.js

@@ -0,0 +1,104 @@
+// Cross-server lookups: a rule may need a fact another guarded server holds (an order total read by a shop server's
+// read tool while the agent calls a refund tool). Each guard serves its wrapped server's read tools to the user's other
+// guards on a Unix socket, <cfgDir>/run/<hash of server name>.sock (0600, in a 0700 dir). A peer must present the same
+// Claros key (its sha256), so only guards of the same user and workspace ask, and only read tools are ever called.
+// One JSON line per connection: {auth, tool, arguments} → {result: <the server's JSON-RPC answer>} | {error}.
+import { createHash } from "node:crypto";
+import { chmodSync, mkdirSync, unlinkSync } from "node:fs";
+import { createConnection, createServer } from "node:net";
+import { tmpdir, userInfo } from "node:os";
+import { join } from "node:path";
+import { cfgDir } from "./config.js";
+const sha = (s) => createHash("sha256").update(s).digest("hex");
+// macOS caps a socket path at 104 bytes; a long HOME falls back to a per-user dir under the temp dir
+const runDir = () => join(cfgDir(), "run").length < 80 ? join(cfgDir(), "run") : join(tmpdir(), `getclaros-${userInfo().uid}`);
+export const sockPath = (server) => join(runDir(), sha(server).slice(0, 16) + ".sock");
+function oneLine(sock, onLine) {
+    let buf = "", done = false;
+    sock.on("data", (c) => {
+        buf += c;
+        const i = buf.indexOf("\n");
+        if (i >= 0 && !done) {
+            done = true;
+            onLine(buf.slice(0, i));
+        }
+    });
+}
+/** Serve `server`'s read tools to peers. `call` runs one tool on the wrapped server. Returns a stop function. */
+export function serve(server, key, isRead, call, log) {
+    // ponytail: Unix sockets only; Windows named pipes when someone guards there
+    if (process.platform === "win32" || !key)
+        return () => { };
+    const path = sockPath(server), auth = sha(key);
+    const srv = createServer((sock) => {
+        sock.setEncoding("utf8");
+        oneLine(sock, async (line) => {
+            let req, out;
+            try {
+                req = JSON.parse(line);
+                if (req?.auth !== auth)
+                    throw new Error("not the same Claros key");
+                if (!isRead(String(req.tool)))
+                    throw new Error(`${req.tool} isn't a read tool of ${server}`);
+                out = { result: await call(String(req.tool), req.arguments ?? {}) };
+                log(`${server} ${req.tool} → read for another guard`);
+            }
+            catch (e) {
+                out = { error: e.message };
+            }
+            sock.end(JSON.stringify(out) + "\n");
+        });
+        sock.on("error", () => { });
+    });
+    const listen = () => srv.listen(path, () => { try {
+        chmodSync(path, 0o600);
+    }
+    catch { /* gone */ } });
+    srv.on("error", (e) => {
+        if (e.code !== "EADDRINUSE")
+            return log(`lookups for other guards unavailable (${e.message})`);
+        // a live guard of the same server answers there already; a dead one left its socket behind
+        const probe = createConnection(path);
+        probe.on("connect", () => { probe.destroy(); log(`another guard of ${server} answers lookups for it`); });
+        probe.on("error", () => {
+            try {
+                unlinkSync(path);
+            }
+            catch { /* raced */ }
+            listen();
+        });
+    });
+    mkdirSync(runDir(), { recursive: true, mode: 0o700 });
+    listen();
+    const stop = () => { if (srv.listening) {
+        srv.close();
+        try {
+            unlinkSync(path);
+        }
+        catch { /* gone */ }
+    } };
+    process.on("exit", stop);
+    return stop;
+}
+/** Ask the guard of `server` to run its read tool. Throws when no guard serves it or it refuses. */
+export function ask(server, key, tool, args, timeout) {
+    return new Promise((ok, no) => {
+        const sock = createConnection(sockPath(server));
+        sock.setEncoding("utf8");
+        const t = setTimeout(() => { sock.destroy(); no(new Error(`reading ${tool} on ${server} timed out after ${timeout}ms`)); }, timeout);
+        sock.on("connect", () => sock.write(JSON.stringify({ auth: sha(key), tool, arguments: args }) + "\n"));
+        sock.on("error", () => { clearTimeout(t); no(new Error(`couldn't read with ${tool}: ${server} isn't running under getclaros guard here`)); });
+        oneLine(sock, (line) => {
+            clearTimeout(t);
+            sock.destroy();
+            let r;
+            try {
+                r = JSON.parse(line);
+            }
+            catch {
+                return no(new Error(`bad answer from the ${server} guard`));
+            }
+            return r.error ? no(new Error(`${server}: ${r.error}`)) : ok(r.result);
+        });
+    });
+}

package/dist/query.js

@@ -0,0 +1,39 @@
+const get = (o, path) => path.split(".").reduce((v, k) => (v && typeof v === "object" ? v[k] : undefined), o);
+const same = (a, b) => a === b || (a != null && b != null && String(a) === String(b));
+/** A read tool's result → its rows: structuredContent, else the JSON text; `rows` is the array's path in an object. */
+export function rowsOf(tool, m, rows) {
+    if (m?.error || m?.result?.isError)
+        throw new Error(`couldn't read the records: ${tool} returned an error`);
+    let v = m.result?.structuredContent;
+    if (v === undefined) {
+        const text = (m.result?.content ?? []).filter((c) => c?.type === "text").map((c) => c.text).join("\n");
+        try {
+            v = JSON.parse(text);
+        }
+        catch { /* below */ }
+    }
+    if (rows)
+        v = get(v, rows);
+    if (!Array.isArray(v))
+        throw new Error(`couldn't read the records: ${tool} returned no rows`);
+    return v;
+}
+/** Keep the rows matching every `where` field (a list = any of its values), then count / first / last / min / max
+ *  of `field`. min/max compare numbers when every value is one, else strings (ISO dates sort right). */
+export function reduceRows(rows, r) {
+    const kept = rows.filter((row) => Object.entries(r.where ?? {}).every(([k, want]) => (Array.isArray(want) ? want : [want]).some((w) => same(get(row, k), w))));
+    if (r.op === "count")
+        return kept.length;
+    const vals = kept.map((row) => get(row, r.field)).filter((v) => v != null && v !== "");
+    if (r.op === "first" || r.op === "last") {
+        const row = r.op === "first" ? kept[0] : kept.at(-1);
+        return row === undefined ? null : get(row, r.field) ?? null;
+    }
+    if (!vals.length)
+        return null;
+    const num = vals.every((v) => typeof v === "number");
+    return vals.reduce((a, b) => {
+        const gt = num ? b > a : String(b) > String(a);
+        return (r.op === "max" ? gt : !gt && !same(a, b)) ? b : a;
+    });
+}