pombus 0.1.1 → 0.1.2

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 Runaki
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 Runaki
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,79 +1,79 @@
-# Pombus MCP server
-
-Email boxes for AI agents — the opposite of a webmail client. Pombus gives a
-person and their AI agents their own mailboxes; the agent operates the mailbox
-over the [Model Context Protocol](https://modelcontextprotocol.io) while the
-human stays in the loop.
-
-This package is the MCP server: a thin stdio translator between a client's MCP
-tool calls and the Pombus REST API. It holds no mail and no logic of its own —
-every read, draft and send is a call to the Pombus core. Learn more at
-[pombus.com](https://pombus.com).
-
-<!-- mcp-name: com.pombus/pombus -->
-
-## Install
-
-One command wires Pombus into your MCP client:
-
-```sh
-npx pombus init
-```
-
-`init` reads your API key, detects your client, and writes the MCP server block
-into its config (merging, never clobbering the rest of the file). Detected
-clients: **Claude Code**, **Cursor**, **Gemini CLI**, and **Codex CLI** (Codex
-uses TOML, so `init` prints the block for you to paste).
-
-```sh
-npx pombus init --print                 # print the config block, write nothing
-npx pombus init --client cursor         # target one client
-npx pombus init --create-inbox          # create an inbox during setup
-```
-
-## Commands
-
-| Command         | What it does                                                        |
-| --------------- | ------------------------------------------------------------------- |
-| `pombus mcp`    | Run the stdio MCP server. Your client invokes this; you rarely do.  |
-| `pombus init`   | Write the Pombus MCP config into your client.                       |
-| `pombus doctor` | Validate your API key and report its scope. Read-only, one request. |
-
-## Authentication
-
-Set `POMBUS_API_KEY` in the environment. `init` writes it into the MCP server
-block for you; the key never lands in your terminal scrollback. Get a key at
-[pombus.com](https://pombus.com).
-
-```json
-{
-  "mcpServers": {
-    "pombus": {
-      "command": "npx",
-      "args": ["-y", "pombus", "mcp"],
-      "env": { "POMBUS_API_KEY": "<YOUR_POMBUS_API_KEY>" }
-    }
-  }
-}
-```
-
-## The tools are gated by your key
-
-The server exposes a catalog of 53 tools — list and read threads, search, label,
-compose and send drafts, manage lists, read metrics. But **your API key decides
-what the agent actually sees.** A tool is only registered when the key holds the
-permission that tool needs; a key without send permission never sees a send
-tool, so the agent cannot call it. The same key also fixes the scope: an
-inbox-scoped key binds a single inbox, and tools drop the `inbox_id` argument
-entirely — the agent physically cannot address another inbox.
-
-**Draft-first is the default write path.** Composing a message creates a draft
-(`create_draft`) for a human to review; sending is a separate, explicit step
-(`send_draft`). Direct, unreviewed send exists only for keys that explicitly
-hold send permission — most keys stay draft-only.
-
-Run `pombus doctor` to see exactly which scope your key resolves to.
-
-## License
-
-[MIT](./LICENSE) © Runaki
+# Pombus MCP server
+
+Email boxes for AI agents — the opposite of a webmail client. Pombus gives a
+person and their AI agents their own mailboxes; the agent operates the mailbox
+over the [Model Context Protocol](https://modelcontextprotocol.io) while the
+human stays in the loop.
+
+This package is the MCP server: a thin stdio translator between a client's MCP
+tool calls and the Pombus REST API. It holds no mail and no logic of its own —
+every read, draft and send is a call to the Pombus core. Learn more at
+[pombus.com](https://pombus.com).
+
+<!-- mcp-name: com.pombus/pombus -->
+
+## Install
+
+One command wires Pombus into your MCP client:
+
+```sh
+npx pombus init
+```
+
+`init` reads your API key, detects your client, and writes the MCP server block
+into its config (merging, never clobbering the rest of the file). Detected
+clients: **Claude Code**, **Cursor**, **Gemini CLI**, and **Codex CLI** (Codex
+uses TOML, so `init` prints the block for you to paste).
+
+```sh
+npx pombus init --print                 # print the config block, write nothing
+npx pombus init --client cursor         # target one client
+npx pombus init --create-inbox          # create an inbox during setup
+```
+
+## Commands
+
+| Command         | What it does                                                        |
+| --------------- | ------------------------------------------------------------------- |
+| `pombus mcp`    | Run the stdio MCP server. Your client invokes this; you rarely do.  |
+| `pombus init`   | Write the Pombus MCP config into your client.                       |
+| `pombus doctor` | Validate your API key and report its scope. Read-only, one request. |
+
+## Authentication
+
+Set `POMBUS_API_KEY` in the environment. `init` writes it into the MCP server
+block for you; the key never lands in your terminal scrollback. Get a key at
+[pombus.com](https://pombus.com).
+
+```json
+{
+  "mcpServers": {
+    "pombus": {
+      "command": "npx",
+      "args": ["-y", "pombus", "mcp"],
+      "env": { "POMBUS_API_KEY": "<YOUR_POMBUS_API_KEY>" }
+    }
+  }
+}
+```
+
+## The tools are gated by your key
+
+The server exposes a catalog of 53 tools — list and read threads, search, label,
+compose and send drafts, manage lists, read metrics. But **your API key decides
+what the agent actually sees.** A tool is only registered when the key holds the
+permission that tool needs; a key without send permission never sees a send
+tool, so the agent cannot call it. The same key also fixes the scope: an
+inbox-scoped key binds a single inbox, and tools drop the `inbox_id` argument
+entirely — the agent physically cannot address another inbox.
+
+**Draft-first is the default write path.** Composing a message creates a draft
+(`create_draft`) for a human to review; sending is a separate, explicit step
+(`send_draft`). Direct, unreviewed send exists only for keys that explicitly
+hold send permission — most keys stay draft-only.
+
+Run `pombus doctor` to see exactly which scope your key resolves to.
+
+## License
+
+[MIT](./LICENSE) © Runaki

package/dist/bin.js

@@ -85,7 +85,7 @@ async function main() {
             print: args.print,
             ...(args.client !== undefined ? { client: args.client } : {}),
             ...(args.locale !== undefined ? { locale: args.locale } : {}),
-            home: undefined, // defaults to os.homedir() inside clients.ts
+            home: undefined, // init.ts homeOf() falls back to os.homedir(); clients.ts refuses an unsafe HOME
             promptKey: promptKeyHidden,
         });
         return;

package/dist/clients.js

@@ -15,9 +15,9 @@
 //   - PRINT fallback: a client whose format we will not write by hand (Codex: TOML, which we will not
 //     serialize without a parser — ponytail forbids the dep, and a half-escaped TOML path is a known
 //     way to wedge the client) is PRINT-only. So is any client whose config dir we cannot resolve.
-import { mkdirSync, readFileSync, writeFileSync, renameSync, chmodSync, rmSync } from "node:fs";
+import { mkdirSync, readFileSync, writeFileSync, renameSync, chmodSync, rmSync, existsSync } from "node:fs";
 import { homedir } from "node:os";
-import { join, dirname, resolve, sep } from "node:path";
+import { join, dirname, resolve, sep, isAbsolute } from "node:path";
 /** Resolve the table of known clients for a given HOME. Taking `home` as an argument (not calling
  *  os.homedir() inline) is what lets a test point the whole table at a temp dir. */
 export function clientTargets(home = homedir()) {
@@ -98,6 +98,12 @@ export class ConfigWriteError extends Error {
 /** True when `target` is inside `home` (defense against a client table — or a tampered HOME env — that
  *  would place a write in the project repo or elsewhere). Path-prefix check after resolving both. */
 export function isInsideHome(target, home) {
+    // A HOME that is empty or relative ("", ".") resolves against the cwd, and a HOME that is itself a git
+    // repo (a container with HOME=/app=WORKDIR) is a project: either way the key would land in a repo.
+    // The caller falls back to --print. (Target and home derive from the same string, so this guard — not
+    // the prefix check below — is what catches a misconfigured HOME.)
+    if (!home.trim() || !isAbsolute(home) || existsSync(join(home, ".git")))
+        return false;
     const h = resolve(home);
     const t = resolve(target);
     return t === h || t.startsWith(h + sep);

package/dist/i18n.js

@@ -55,6 +55,11 @@ const MESSAGES = {
         "pt-BR": "Config MCP gravada para ",
         "es-419": "Configuración MCP guardada para ",
     },
+    init_key_power: {
+        "en-US": "Heads up: your agent can do everything this key can — read, send and delete mail, and manage keys and webhooks. The key is stored in plain text in that config file; revoke it in Pombus › Keys if it leaks.",
+        "pt-BR": "Atenção: seu agente pode fazer tudo que esta chave permite — ler, enviar e apagar e-mails, e gerenciar chaves e webhooks. A chave fica em texto puro nesse arquivo de config; revogue em Pombus › Chaves se ela vazar.",
+        "es-419": "Atención: tu agente puede hacer todo lo que esta clave permite — leer, enviar y borrar correos, y administrar claves y webhooks. La clave queda en texto plano en ese archivo de configuración; revócala en Pombus › Claves si se filtra.",
+    },
     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.",
@@ -91,6 +96,7 @@ const INSTALLER_CODES = [
     "init_prompt_key",
     "init_inbox_created",
     "init_config_written",
+    "init_key_power",
     "init_restart_client",
     "init_done",
     "init_no_client",

package/dist/init.js

@@ -10,6 +10,7 @@ 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";
+import { homedir } from "node:os";
 /** 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>";
@@ -45,6 +46,7 @@ export async function runInit(opts) {
     // --print mode: show the real-target block(s) and write nothing.
     if (opts.print) {
         printBlocks(key, opts, out, locale);
+        say("init_key_power"); // the REAL key was just printed for paste (the placeholder path above isn't)
         return {
             printed: true,
             inboxId,
@@ -81,15 +83,17 @@ export async function runInit(opts) {
             }
         }
     }
-    if (written.length > 0) {
-        say("init_restart_client");
-        say("init_done");
-    }
-    else if (printedFor.length === 0) {
+    if (written.length === 0 && 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));
     }
+    // Whether written or printed for paste, the real key now sits in a config: say what it can do.
+    say("init_key_power");
+    if (written.length > 0) {
+        say("init_restart_client");
+        say("init_done");
+    }
     return {
         printed: false,
         inboxId,
@@ -106,8 +110,10 @@ function targetsFor(opts) {
     const one = all.find((t) => t.id === opts.client);
     return one ? [one] : [];
 }
+// The CLI passes no home: it MUST be the user's real HOME. An empty string here resolved every client
+// path against the cwd and wrote the key in plain text into the project the user ran init from (0.1.0).
 function homeOf(opts) {
-    return opts.home ?? "";
+    return opts.home || homedir();
 }
 /** Print the MCP block for each targeted client in its own format (JSON for most, TOML for Codex). */
 function printBlocks(key, opts, out, locale) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pombus",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Pombus MCP server — email boxes for AI agents. A thin stdio translator between MCP tool calls and the Pombus REST core.",
   "license": "MIT",
   "author": "Runaki",
@@ -20,7 +20,8 @@
   },
   "files": [
     "dist/**/*.js",
-    "!dist/**/*.test.js"
+    "!dist/**/*.test.js",
+    "!dist/testutil.js"
   ],
   "engines": {
     "node": ">=20"

package/dist/testutil.js

@@ -1,117 +0,0 @@
-// 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,
-        },
-    };
-}