pombus 0.0.1 → 0.1.1

package/dist/i18n.js

@@ -0,0 +1,141 @@
+// i18n — human-facing error messages in the three mandated locales (AGENTS.md §2): en-US, pt-BR,
+// es-419. Never hardcode a user-visible string; it comes from this dictionary keyed by a stable,
+// locale-free error code. Tool errors returned TO THE MODEL are protocol text and stay en-US fixed;
+// only messages a human reads (e.g. the server refusing to start, printed to stderr) are localized.
+//
+// Locale selection: POMBUS_LOCALE wins, then LANG/LC_ALL, else en-US. We match on the language (and
+// region for the Spanish variant) prefix, so "pt_BR.UTF-8" -> pt-BR and "es_MX" -> es-419.
+const LOCALES = ["en-US", "pt-BR", "es-419"];
+// Every entry here MUST be reachable by a real human path. Two human paths exist:
+//   (1) the server boot failure a person sees on stderr when `pombus mcp` fails to come up, and
+//   (2) the `pombus init` / `pombus doctor` installer, which talks to a human at the terminal.
+// Codes that only ever reach the MODEL (inside a tool call) are NOT human i18n — they stay en-US
+// protocol text in server.ts (`error: <code>`), never in this dict.
+// Boot-reachable codes (path 1):
+//   - no_api_key: the key env var is unset (server.ts, before any request).
+//   - auth_failed: /v0/auth/me rejected the key at boot (invalid/expired).
+//   - network:    the core was unreachable at boot.
+//   - unknown:    the last-resort fallback for a boot error with no mapped code (bin.ts catch).
+// Installer-reachable codes (path 2): see INSTALLER_CODES below.
+const MESSAGES = {
+    no_api_key: {
+        "en-US": "POMBUS_API_KEY is not set. Export your Pombus API key and try again.",
+        "pt-BR": "POMBUS_API_KEY não está definida. Exporte sua chave de API do Pombus e tente de novo.",
+        "es-419": "POMBUS_API_KEY no está definida. Exporta tu clave de API de Pombus e inténtalo de nuevo.",
+    },
+    auth_failed: {
+        "en-US": "Could not authenticate with Pombus. Check that POMBUS_API_KEY is valid.",
+        "pt-BR": "Não foi possível autenticar no Pombus. Verifique se POMBUS_API_KEY é válida.",
+        "es-419": "No se pudo autenticar en Pombus. Verifica que POMBUS_API_KEY sea válida.",
+    },
+    network: {
+        "en-US": "Could not reach the Pombus API. Check your connection and try again.",
+        "pt-BR": "Não foi possível acessar a API do Pombus. Verifique sua conexão e tente de novo.",
+        "es-419": "No se pudo conectar con la API de Pombus. Revisa tu conexión e inténtalo de nuevo.",
+    },
+    unknown: {
+        "en-US": "Something went wrong talking to Pombus.",
+        "pt-BR": "Algo deu errado na comunicação com o Pombus.",
+        "es-419": "Algo salió mal al comunicarse con Pombus.",
+    },
+    // ---- installer: `pombus init` / `pombus doctor` human lines (path 2) ----
+    // init progress / results
+    init_prompt_key: {
+        "en-US": "Paste your Pombus API key (input hidden): ",
+        "pt-BR": "Cole sua chave de API do Pombus (entrada oculta): ",
+        "es-419": "Pega tu clave de API de Pombus (entrada oculta): ",
+    },
+    init_inbox_created: {
+        "en-US": "Created inbox: ",
+        "pt-BR": "Caixa criada: ",
+        "es-419": "Casilla creada: ",
+    },
+    init_config_written: {
+        "en-US": "MCP config written for ",
+        "pt-BR": "Config MCP gravada para ",
+        "es-419": "Configuración MCP guardada para ",
+    },
+    init_restart_client: {
+        "en-US": "Restart your client to load the Pombus MCP server.",
+        "pt-BR": "Reinicie seu cliente para carregar o servidor MCP do Pombus.",
+        "es-419": "Reinicia tu cliente para cargar el servidor MCP de Pombus.",
+    },
+    init_done: {
+        "en-US": "Done. One command and it's running.",
+        "pt-BR": "Pronto. Um comando e tá rodando.",
+        "es-419": "Listo. Un comando y está funcionando.",
+    },
+    // detection / print fallback
+    init_no_client: {
+        "en-US": "No supported client config was found to write safely. Printing the MCP block below — paste it into your client's config yourself.",
+        "pt-BR": "Nenhuma config de cliente compatível foi encontrada para gravar com segurança. Imprimindo o bloco MCP abaixo — cole na config do seu cliente.",
+        "es-419": "No se encontró una configuración de cliente compatible para escribir con seguridad. Imprimiendo el bloque MCP abajo — pégalo en la configuración de tu cliente.",
+    },
+    init_print_only_client: {
+        "en-US": "This client's config format is not written automatically (to avoid corrupting it). Paste the block below into its config file.",
+        "pt-BR": "O formato de config deste cliente não é gravado automaticamente (para não corrompê-lo). Cole o bloco abaixo no arquivo de config dele.",
+        "es-419": "El formato de configuración de este cliente no se escribe automáticamente (para no dañarlo). Pega el bloque de abajo en su archivo de configuración.",
+    },
+    // doctor report lines
+    doctor_ok: {
+        "en-US": "Your Pombus API key is valid. Scope: ",
+        "pt-BR": "Sua chave de API do Pombus é válida. Escopo: ",
+        "es-419": "Tu clave de API de Pombus es válida. Alcance: ",
+    },
+};
+// The installer human codes — the single source the anti-orphan guard unions with the boot-reachable
+// set. A code here with no caller in init.ts/doctor.ts is still dictionary theater; a code used by the
+// installer with no entry here is a missing string. Keeping the list explicit makes the guard
+// mechanical without reparsing TypeScript.
+const INSTALLER_CODES = [
+    "init_prompt_key",
+    "init_inbox_created",
+    "init_config_written",
+    "init_restart_client",
+    "init_done",
+    "init_no_client",
+    "init_print_only_client",
+    "doctor_ok",
+];
+/** The installer-reachable human codes (path 2). Exposed so the anti-orphan contract test can union
+ *  them with the boot-reachable set and prove the dictionary has no orphan and no missing string. */
+export function installerCodes() {
+    return INSTALLER_CODES;
+}
+/** Map a boot-time CoreError code to the human i18n code a person should see. A boot failure is one
+ *  of exactly two things to a human: the key was rejected (any 401/403/404 at /v0/auth/me collapses to
+ *  `not_found`, which at startup means "bad key" -> auth_failed) or the core was unreachable
+ *  (`network`). Anything else is `unknown`. This is the bridge that makes auth_failed/network
+ *  reachable — without it they were dictionary theater. */
+export function humanCodeForBoot(coreErrorCode) {
+    if (coreErrorCode === "network")
+        return "network";
+    if (coreErrorCode === "not_found")
+        return "auth_failed";
+    return "unknown";
+}
+/** Resolve the active locale from the environment. */
+export function resolveLocale(env = process.env) {
+    const raw = (env["POMBUS_LOCALE"] ?? env["LC_ALL"] ?? env["LANG"] ?? "").toLowerCase();
+    if (raw.startsWith("pt"))
+        return "pt-BR";
+    if (raw.startsWith("es"))
+        return "es-419";
+    return "en-US";
+}
+/** The human message for a stable error code, in the active locale. Unknown codes fall back to the
+ *  `unknown` entry — never a missing string. */
+export function humanMessage(code, locale = resolveLocale()) {
+    const entry = MESSAGES[code] ?? MESSAGES["unknown"];
+    return entry[locale];
+}
+/** Exposed for the contract test: the dictionary must cover all three locales for every code. */
+export function allLocales() {
+    return LOCALES;
+}
+export function messageCodes() {
+    return Object.keys(MESSAGES);
+}
+export function messagesForTest() {
+    return MESSAGES;
+}

package/dist/init.js

@@ -0,0 +1,154 @@
+// `pombus init` — the one command. Reads a key, resolves its scope, optionally creates an inbox, and
+// writes the MCP server block into the detected client's config (merge, atomic, 0600 — clients.ts),
+// persisting EXACTLY the key the user provided. i18n throughout.
+//
+// This module is a THIN orchestrator: every piece with weight (the HTTP, the write) lives elsewhere
+// and is reused. The function takes its side-effects as injected dependencies (key source, fetch,
+// HOME, output sink) so a test drives the whole flow against a fake core and a temp HOME without
+// ever touching real stdin/stdout/disk.
+import { CoreClient } from "./client.js";
+import { ScopeBinding } from "./scope.js";
+import { clientTargets, printableCodexToml, printableJson, writeJsonConfig, ConfigWriteError, } from "./clients.js";
+import { humanMessage, resolveLocale } from "./i18n.js";
+/** A placeholder shown in --print output instead of a real key, so a user can paste the block and fill
+ *  the key in themselves without a secret ever reaching the terminal scrollback. */
+const KEY_PLACEHOLDER = "<YOUR_POMBUS_API_KEY>";
+export async function runInit(opts) {
+    const locale = opts.locale ?? resolveLocale();
+    const out = opts.out ?? ((l) => process.stderr.write(l + "\n"));
+    const say = (code, suffix = "") => out(humanMessage(code, locale) + suffix);
+    // --print with no key: emit the placeholder block for every known client and stop. No network, no
+    // disk. This is the "I just want the snippet" path and the safe landing for uncertain detection.
+    const key = (opts.apiKey ?? "").trim() || (opts.print ? "" : await requireKey(opts));
+    if (opts.print && !key) {
+        printBlocks(KEY_PLACEHOLDER, opts, out, locale);
+        return emptyPrintResult();
+    }
+    const client = new CoreClient({
+        apiKey: key,
+        ...(opts.baseUrl !== undefined ? { baseUrl: opts.baseUrl } : {}),
+        ...(opts.fetchImpl !== undefined ? { fetchImpl: opts.fetchImpl } : {}),
+    });
+    const scope = await ScopeBinding.resolve(client); // throws CoreError on a bad key / unreachable core
+    // Optionally create an inbox and show the address.
+    let inboxId = scope.fixedInboxId;
+    let inboxEmail = null;
+    if (opts.createInbox) {
+        const created = await client.post("/inboxes", {});
+        inboxId = typeof created.inbox_id === "string" ? created.inbox_id : inboxId;
+        inboxEmail = typeof created.email === "string" ? created.email : null;
+        if (inboxEmail)
+            say("init_inbox_created", inboxEmail);
+    }
+    // The key that lands on disk is exactly the one the user provided (env or prompt) — the agent is the
+    // account's full operator, so it runs with the key the user chose to give it.
+    // --print mode: show the real-target block(s) and write nothing.
+    if (opts.print) {
+        printBlocks(key, opts, out, locale);
+        return {
+            printed: true,
+            inboxId,
+            inboxEmail,
+            written: [],
+            printedFor: targetsFor(opts).map((t) => t.id),
+        };
+    }
+    // Write to each targeted client. A write that fails safely (corrupt/outside-home) becomes a print
+    // fallback for THAT client, never an aborted install.
+    const written = [];
+    const printedFor = [];
+    const targets = targetsFor(opts);
+    for (const t of targets) {
+        if (t.mode === "print") {
+            say("init_print_only_client");
+            out(blockFor(t, key));
+            printedFor.push(t.id);
+            continue;
+        }
+        try {
+            writeJsonConfig(t.path, homeOf(opts), key);
+            say("init_config_written", t.label);
+            written.push(t.id);
+        }
+        catch (e) {
+            if (e instanceof ConfigWriteError) {
+                say("init_print_only_client");
+                out(blockFor(t, key));
+                printedFor.push(t.id);
+            }
+            else {
+                throw e;
+            }
+        }
+    }
+    if (written.length > 0) {
+        say("init_restart_client");
+        say("init_done");
+    }
+    else if (printedFor.length === 0) {
+        // No target at all resolved — detection was too uncertain to touch anything: print for everyone.
+        say("init_no_client");
+        out(printableJson(key));
+    }
+    return {
+        printed: false,
+        inboxId,
+        inboxEmail,
+        written,
+        printedFor,
+    };
+}
+/** The client targets for this run: one by id, or all known clients. */
+function targetsFor(opts) {
+    const all = clientTargets(homeOf(opts));
+    if (!opts.client)
+        return all;
+    const one = all.find((t) => t.id === opts.client);
+    return one ? [one] : [];
+}
+function homeOf(opts) {
+    return opts.home ?? "";
+}
+/** Print the MCP block for each targeted client in its own format (JSON for most, TOML for Codex). */
+function printBlocks(key, opts, out, locale) {
+    const targets = targetsFor(opts);
+    if (targets.length === 0) {
+        out(humanMessage("init_no_client", locale));
+        out(printableJson(key));
+        return;
+    }
+    for (const t of targets)
+        out(blockFor(t, key));
+}
+/** The pasteable block for one client in its native format. */
+function blockFor(t, key) {
+    return t.id === "codex" ? printableCodexToml(key) : printableJson(key);
+}
+/** Obtain the key when none was in the environment: the prompt (interactive) must be supplied. */
+async function requireKey(opts) {
+    if (!opts.promptKey) {
+        // No key and no way to ask: fail closed with the same code the server uses for a missing key.
+        const locale = opts.locale ?? resolveLocale();
+        (opts.out ?? ((l) => process.stderr.write(l + "\n")))(humanMessage("no_api_key", locale));
+        throw new InitAbort("no_api_key");
+    }
+    return (await opts.promptKey()).trim();
+}
+function emptyPrintResult() {
+    return {
+        printed: true,
+        inboxId: null,
+        inboxEmail: null,
+        written: [],
+        printedFor: [],
+    };
+}
+/** A clean, key-free abort for a missing prerequisite (the CLI turns it into exit code 1). */
+export class InitAbort extends Error {
+    code;
+    constructor(code) {
+        super(code);
+        this.name = "InitAbort";
+        this.code = code;
+    }
+}

package/dist/scope.js

@@ -0,0 +1,118 @@
+// Scope binding — the core of F4's access rule (strategy doc 4.2/4.3, adoption spec line 104):
+// the model NEVER supplies a raw inbox_id that escapes the API key's scope.
+//
+// On boot the server calls GET /v0/auth/me and learns the key's scope:
+//   - inbox / domain key  -> a single inbox is implied. The inbox_id is DERIVED from the scope and the
+//     tools that need one do NOT accept it as an argument at all. The model cannot address any other
+//     inbox because the parameter does not exist in the tool schema.
+//   - pod / organization key -> the key can see many inboxes. `list_inboxes` enumerates the ones the
+//     key may reach; a tool that needs an inbox_id accepts only an id the server has seen in that
+//     enumeration, validated against the allowed set before any request leaves the process.
+//
+// The core already fences every route by scope (authz_inbox), so this layer is defense in depth plus
+// an honest tool schema: the key's authority — not the model's argument — decides which inbox is read.
+/** The resolved binding the tool layer consults. `fixedInboxId` set => single-inbox key: tools drop
+ *  the inbox_id parameter entirely. Otherwise => multi-inbox key: tools require a listed inbox_id,
+ *  checked via `allows`. `permissions` drives the catalog gate; `podId` lets pod-scoped tools derive
+ *  the pod from the key's own scope instead of taking it as a free model argument. */
+export class ScopeBinding {
+    scopeType;
+    fixedInboxId;
+    // The key's permission set, verbatim from /auth/me. null = master (full access); an object = scoped.
+    permissions;
+    // The pod the key is bound to, when it is pod/inbox/domain-scoped. An org (master) key has none, so a
+    // pod-scoped tool must then take a validated pod_id argument. Pod-scoped tools NEVER take a free
+    // pod_id when this is set — the key's own pod is used, so the model can't address another tenant.
+    podId;
+    // The set of inbox ids the key has been observed to reach, grown lazily by list_inboxes. A pod/org
+    // key can reach ids not yet listed; `allows` therefore also confirms unknown ids against the core
+    // (fail-closed) rather than rejecting them for being unseen.
+    seen = new Set();
+    constructor(scopeType, fixedInboxId, permissions, podId) {
+        this.scopeType = scopeType;
+        this.fixedInboxId = fixedInboxId;
+        this.permissions = permissions;
+        this.podId = podId;
+    }
+    /** True when the key binds exactly one inbox (inbox or domain... no: domain reaches many). Only an
+     *  inbox-scoped key is truly single. A domain key reaches every inbox of its domain, so it is
+     *  multi-inbox like a pod key. */
+    get isSingleInbox() {
+        return this.fixedInboxId !== null;
+    }
+    /** The catalog gate: does the key hold the permission a tool requires? A master key (permissions ===
+     *  null) holds everything. A scoped key holds `perm` when its object has it true — with ONE mirror of
+     *  the core's rule (api.py:1331-1334): message_send satisfies message_reply, so a key that can send
+     *  can also reply. Tools whose gate is false are never REGISTERED (hidden, not registered-then-403). */
+    gateAllows(requiredPerm) {
+        if (this.permissions === null)
+            return true; // master key
+        if (requiredPerm === null)
+            return true; // a tool with no gated route (none scope)
+        if (this.permissions[requiredPerm] === true)
+            return true;
+        if (requiredPerm === "message_reply" && this.permissions["message_send"] === true)
+            return true;
+        return false;
+    }
+    /** Call /v0/auth/me and build the binding. An inbox key yields a fixed inbox_id; every other scope
+     *  is multi-inbox and the inbox_id must be supplied-and-validated per call. Captures the key's
+     *  permissions (catalog gate) and pod_id (pod-scoped tools derive the pod from the scope). */
+    static async resolve(client) {
+        const me = await client.get("/auth/me");
+        const permissions = me.permissions ?? null;
+        const podId = me.pod_id ?? null;
+        if (me.scope_type === "inbox" && me.inbox_id) {
+            return new ScopeBinding("inbox", me.inbox_id, permissions, podId);
+        }
+        // domain / pod / organization: no single implied inbox.
+        return new ScopeBinding(me.scope_type, null, permissions, podId);
+    }
+    /** Record inbox ids returned by list_inboxes so later calls can validate against the enumeration. */
+    remember(ids) {
+        for (const id of ids)
+            this.seen.add(id);
+    }
+    /** Resolve the inbox_id a tool will act on. For a single-inbox key the model's argument (if any) is
+     *  IGNORED and the fixed id is used — the model can never widen past its scope. For a multi-inbox
+     *  key the argument is required and must be an id the key can reach: known from a prior list, or
+     *  confirmed against the core (which fences by scope and 404s an inbox outside it). Returns the id,
+     *  or throws a stable `not_found` (never distinguishing "unknown" from "forbidden"). */
+    async resolveInboxId(client, requested) {
+        if (this.fixedInboxId !== null)
+            return this.fixedInboxId;
+        const id = (requested ?? "").trim();
+        if (!id)
+            throw new ScopeError("inbox_required");
+        if (this.seen.has(id))
+            return id;
+        // Not seen yet. Confirm it against the core: get_inbox 404s (via not_found) for any inbox the key
+        // may not reach, so a hostile id never turns into a cross-tenant read. On success, remember it.
+        await client.get(`/inboxes/${encodeURIComponent(id)}`); // throws CoreError('not_found') if out of scope
+        this.seen.add(id);
+        return id;
+    }
+    /** Resolve the pod_id a pod-scoped tool acts on. Same discipline as resolveInboxId: when the key is
+     *  itself pod/inbox/domain-scoped the model's argument is IGNORED and the key's own pod is used — it
+     *  cannot address another tenant. Only a master (org) key, which binds no single pod, must supply a
+     *  pod_id; it is then validated against the core (get_pod 404s -> not_found for an unknown pod) so a
+     *  forged id never turns into a cross-tenant action. */
+    async resolvePodId(client, requested) {
+        if (this.podId !== null)
+            return this.podId;
+        const id = (requested ?? "").trim();
+        if (!id)
+            throw new ScopeError("pod_required");
+        await client.get(`/pods/${encodeURIComponent(id)}`); // throws CoreError('not_found') if out of scope
+        return id;
+    }
+}
+/** A scope-layer failure the tool layer maps to an i18n message for a human. Locale-free, key-free. */
+export class ScopeError extends Error {
+    code;
+    constructor(code) {
+        super(code);
+        this.name = "ScopeError";
+        this.code = code;
+    }
+}

package/dist/server.js

@@ -0,0 +1,94 @@
+// The MCP server — a thin stdio adapter over the tool catalog. It registers the tools the scope
+// allows, dispatches CallTool to the matching handler, and translates failures into a tool error the
+// model can read. It never reimplements core logic; every call is one REST request.
+//
+// Log hygiene (AGENTS.md §5, audited by pombus-sec): the stdio stream IS the MCP channel, so nothing
+// but protocol frames may touch stdout. Diagnostics go to stderr, and NOTHING we print ever includes
+// the API key — the key lives only in the client's Authorization header, never in an argument, a URL,
+// or an error message surfaced here.
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { CoreClient, CoreError, readApiKey } from "./client.js";
+import { ScopeBinding, ScopeError } from "./scope.js";
+import { specByName, toolDescriptors, callTool, ToolArgError } from "./tools.js";
+const SERVER_NAME = "pombus";
+const SERVER_VERSION = "0.1.0";
+/** Build and connect the MCP server over stdio. Fails fast (before connecting) when the key is absent,
+ *  so a misconfigured client sees a clear stderr line instead of a server that answers every tool with
+ *  an auth error. */
+export async function runMcpServer() {
+    const { humanMessage, humanCodeForBoot } = await import("./i18n.js");
+    const apiKey = readApiKey();
+    if (!apiKey) {
+        // Human-facing, localized, to stderr — never stdout (would corrupt the MCP stream).
+        process.stderr.write(humanMessage("no_api_key") + "\n");
+        process.exitCode = 1;
+        return;
+    }
+    const client = new CoreClient({ apiKey });
+    let server;
+    try {
+        // buildServer resolves the key's scope (one /v0/auth/me call). A human runs the server, so a boot
+        // failure here is human-facing: localize the REAL cause — a rejected key (auth_failed) or an
+        // unreachable core (network) — instead of a generic line. CoreError already carries only a safe,
+        // key-free code.
+        server = await buildServer(client);
+    }
+    catch (e) {
+        const code = e instanceof CoreError ? humanCodeForBoot(e.code) : "unknown";
+        process.stderr.write(humanMessage(code) + "\n");
+        process.exitCode = 1;
+        return;
+    }
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+/** Build the Server bound to a given core client. Exposed so tests drive it with a fake core and
+ *  without a real stdio transport. Resolves the key's scope up front (one /v0/auth/me call) so the
+ *  tool schemas can omit inbox_id for a single-inbox key. */
+export async function buildServer(client) {
+    const scope = await ScopeBinding.resolve(client);
+    const server = new Server({ name: SERVER_NAME, version: SERVER_VERSION }, { capabilities: { tools: {} } });
+    server.setRequestHandler(ListToolsRequestSchema, async () => ({
+        tools: toolDescriptors(scope),
+    }));
+    server.setRequestHandler(CallToolRequestSchema, async (req) => {
+        // specByName honours the gate: a tool the key may not use is "unknown" here, exactly as it is
+        // absent from ListTools — the model can neither see nor call a tool outside its permissions.
+        const spec = specByName(req.params.name, scope);
+        if (!spec)
+            return toolError(`unknown tool: ${req.params.name}`);
+        const args = (req.params.arguments ?? {});
+        try {
+            const value = await callTool(spec, args, { client, scope });
+            return { content: [{ type: "text", text: toText(value) }] };
+        }
+        catch (e) {
+            return toolError(modelError(e));
+        }
+    });
+    return server;
+}
+/** Serialize a handler result for the model. undefined (e.g. a 204) becomes an explicit ok marker. */
+function toText(value) {
+    if (value === undefined)
+        return JSON.stringify({ ok: true });
+    return JSON.stringify(value);
+}
+/** A CallTool result flagged as an error (isError), carrying model-facing en-US text. */
+function toolError(text) {
+    return { isError: true, content: [{ type: "text", text }] };
+}
+/** Map a thrown error to a stable, locale-free string for the model. Never leaks the key or a URL:
+ *  CoreError/ScopeError/ToolArgError already carry only a safe code; anything else collapses to a
+ *  generic message so an unexpected throw can't smuggle a secret into the tool output. */
+function modelError(e) {
+    if (e instanceof CoreError)
+        return `error: ${e.code}`;
+    if (e instanceof ScopeError)
+        return `error: ${e.code}`;
+    if (e instanceof ToolArgError)
+        return `error: ${e.code}`;
+    return "error: internal";
+}

package/dist/testutil.js

@@ -0,0 +1,117 @@
+// Test doubles — a fake core (a FetchLike that records every request and returns programmed replies)
+// and a captured-request shape the tests assert against. Not a *.test.ts, so the test runner does not
+// execute it as a suite. All fixtures are written from scratch (AGENTS.md §9): invented ids, no real
+// data.
+export class FakeCore {
+    requests = [];
+    routes = [];
+    /** Register a route. Routes are matched in order; the first match wins. */
+    on(method, match, reply) {
+        this.routes.push({ method, match, reply });
+        return this;
+    }
+    /** A FetchLike bound to this fake. Records the request, then returns the first matching route's
+     *  reply, or a 404 when nothing matches (so an unexpected call fails closed, like the real core). */
+    fetch = async (rawUrl, init) => {
+        const url = new URL(rawUrl);
+        const headers = lowerHeaders(init.headers);
+        let body;
+        if (typeof init.body === "string" && init.body.length > 0) {
+            try {
+                body = JSON.parse(init.body);
+            }
+            catch {
+                body = init.body;
+            }
+        }
+        const captured = { method: init.method ?? "GET", url: rawUrl, headers, body };
+        this.requests.push(captured);
+        const route = this.routes.find((r) => r.method === captured.method && r.match(url));
+        const reply = route
+            ? typeof route.reply === "function"
+                ? route.reply(captured, url)
+                : route.reply
+            : { status: 404, json: { code: "not_found" } };
+        return makeResponse(reply);
+    };
+}
+function lowerHeaders(h) {
+    const out = {};
+    if (!h)
+        return out;
+    if (h instanceof Headers) {
+        h.forEach((v, k) => (out[k.toLowerCase()] = v));
+    }
+    else if (Array.isArray(h)) {
+        for (const pair of h) {
+            const k = pair[0];
+            const v = pair[1];
+            if (k !== undefined && v !== undefined)
+                out[k.toLowerCase()] = v;
+        }
+    }
+    else {
+        for (const [k, v] of Object.entries(h))
+            out[k.toLowerCase()] = String(v);
+    }
+    return out;
+}
+function makeResponse(reply) {
+    const status = reply.status ?? 200;
+    const hasBody = reply.json !== undefined;
+    // A 204/205 MUST have a null body (undici throws on any body, even ""), matching the real core's
+    // no-content replies (e.g. a DELETE).
+    const nullBodyStatus = status === 204 || status === 205 || status === 304;
+    const body = hasBody ? JSON.stringify(reply.json) : nullBodyStatus ? null : "";
+    return new Response(body, {
+        status,
+        headers: hasBody ? { "content-type": "application/json" } : {},
+    });
+}
+/** An /auth/me reply for an inbox-scoped key (single implied inbox). */
+export function authMeInbox(inboxId) {
+    return {
+        json: {
+            scope_type: "inbox",
+            scope_id: inboxId,
+            organization_id: "org_test",
+            pod_id: "pod_test",
+            inbox_id: inboxId,
+            api_key_id: "key_test",
+            permissions: null,
+        },
+    };
+}
+/** An /auth/me reply for a pod-scoped key (reaches many inboxes). */
+export function authMePod() {
+    return {
+        json: {
+            scope_type: "pod",
+            scope_id: "pod_test",
+            organization_id: "org_test",
+            pod_id: "pod_test",
+            inbox_id: null,
+            api_key_id: "key_test",
+            permissions: null,
+        },
+    };
+}
+/** A POST /v0/inboxes reply (the shape the core returns: inbox_id + email). Invented ids only (§9). */
+export function createdInbox(inboxId, email) {
+    return { json: { inbox_id: inboxId, email } };
+}
+/** An /auth/me reply for a SCOPED pod key — a real permissions object drives the catalog gate. Pass
+ *  the permissions the human granted the key; everything else uses invented ids (§9). */
+export function authMeScoped(permissions, overrides = {}) {
+    return {
+        json: {
+            scope_type: overrides.scope_type ?? "pod",
+            scope_id: "pod_test",
+            organization_id: "org_test",
+            pod_id: overrides.pod_id === undefined ? "pod_test" : overrides.pod_id,
+            inbox_id: overrides.inbox_id ?? null,
+            api_key_id: "key_test",
+            permissions,
+        },
+    };
+}