pombus 0.1.0 → 0.1.2

package/LICENSE

@@ -0,0 +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.

package/README.md

@@ -0,0 +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

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,15 +1,27 @@
 {
   "name": "pombus",
-  "version": "0.1.0",
+  "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": "UNLICENSED",
-  "private": false,
+  "license": "MIT",
+  "author": "Runaki",
+  "homepage": "https://pombus.com",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "email",
+    "ai-agent",
+    "agent-email",
+    "inbox"
+  ],
+  "mcpName": "com.pombus/pombus",
   "type": "module",
   "bin": {
     "pombus": "dist/bin.js"
   },
   "files": [
-    "dist"
+    "dist/**/*.js",
+    "!dist/**/*.test.js",
+    "!dist/testutil.js"
   ],
   "engines": {
     "node": ">=20"

package/dist/bin.test.js

@@ -1,33 +0,0 @@
-import { test } from "node:test";
-import assert from "node:assert/strict";
-import { parseArgs } from "./bin.js";
-test("parseArgs: command + flags", () => {
-    const a = parseArgs(["init", "--create-inbox", "--print"]);
-    assert.equal(a.cmd, "init");
-    assert.equal(a.createInbox, true);
-    assert.equal(a.print, true);
-});
-test("parseArgs: --dry-run is an alias for --print", () => {
-    assert.equal(parseArgs(["init", "--dry-run"]).print, true);
-});
-test("parseArgs: --locale with a space or an = ", () => {
-    assert.equal(parseArgs(["init", "--locale", "pt-BR"]).locale, "pt-BR");
-    assert.equal(parseArgs(["init", "--locale=es-419"]).locale, "es-419");
-});
-test("parseArgs: an invalid locale is dropped (falls back to env detection)", () => {
-    assert.equal(parseArgs(["init", "--locale", "klingon"]).locale, undefined);
-});
-test("parseArgs: --client selects one target", () => {
-    assert.equal(parseArgs(["init", "--client", "cursor"]).client, "cursor");
-    assert.equal(parseArgs(["init", "--client=codex"]).client, "codex");
-});
-test("parseArgs: --help, and no command", () => {
-    assert.equal(parseArgs(["--help"]).help, true);
-    assert.equal(parseArgs(["doctor", "-h"]).help, true);
-    assert.equal(parseArgs([]).cmd, undefined);
-});
-test("parseArgs: an unknown flag is ignored, not fatal", () => {
-    const a = parseArgs(["init", "--some-future-flag", "--print"]);
-    assert.equal(a.cmd, "init");
-    assert.equal(a.print, true);
-});

package/dist/i18n.test.js

@@ -1,78 +0,0 @@
-import { test } from "node:test";
-import assert from "node:assert/strict";
-import { allLocales, humanCodeForBoot, humanMessage, installerCodes, messageCodes, messagesForTest, resolveLocale, } from "./i18n.js";
-test("every error code has a non-empty message in all three mandated locales", () => {
-    const locales = allLocales();
-    assert.deepEqual([...locales], ["en-US", "pt-BR", "es-419"]);
-    const dict = messagesForTest();
-    for (const code of messageCodes()) {
-        for (const loc of locales) {
-            const msg = dict[code][loc];
-            assert.equal(typeof msg, "string");
-            assert.ok(msg.trim().length > 0, `empty ${loc} message for ${code}`);
-        }
-    }
-});
-test("locale resolution: POMBUS_LOCALE wins, then LANG, else en-US", () => {
-    assert.equal(resolveLocale({ POMBUS_LOCALE: "pt-BR" }), "pt-BR");
-    assert.equal(resolveLocale({ POMBUS_LOCALE: "es-ar" }), "es-419");
-    assert.equal(resolveLocale({ LANG: "pt_BR.UTF-8" }), "pt-BR");
-    assert.equal(resolveLocale({ LANG: "es_MX" }), "es-419");
-    assert.equal(resolveLocale({ LANG: "en_US.UTF-8" }), "en-US");
-    assert.equal(resolveLocale({}), "en-US");
-    assert.equal(resolveLocale({ POMBUS_LOCALE: "pt", LANG: "en_US" }), "pt-BR"); // POMBUS_LOCALE wins
-});
-test("an unknown code falls back to the localized 'unknown' message, never a missing string", () => {
-    for (const loc of allLocales()) {
-        const msg = humanMessage("no_such_code_42", loc);
-        assert.equal(msg, messagesForTest()["unknown"][loc]);
-        assert.ok(msg.length > 0);
-    }
-});
-test("the three locales are actually distinct for a representative message (not copy-paste English)", () => {
-    const en = humanMessage("no_api_key", "en-US");
-    const pt = humanMessage("no_api_key", "pt-BR");
-    const es = humanMessage("no_api_key", "es-419");
-    assert.notEqual(en, pt);
-    assert.notEqual(en, es);
-    assert.notEqual(pt, es);
-});
-test("the boot-error bridge maps CoreError codes to the human message code", () => {
-    // The only two startup CoreError shapes a human can hit: an unreachable core, or a rejected key
-    // (every 401/403/404 at /v0/auth/me collapses to not_found, which at boot means "bad key").
-    assert.equal(humanCodeForBoot("network"), "network");
-    assert.equal(humanCodeForBoot("not_found"), "auth_failed");
-    // Anything unexpected -> the generic fallback, never a missing/raw code.
-    assert.equal(humanCodeForBoot("core_error"), "unknown");
-    assert.equal(humanCodeForBoot("bad_response"), "unknown");
-});
-test("NO human dictionary entry is orphaned — every code is reachable by a real code path", () => {
-    // The guard the judge asked for: a translated string nobody can display is dictionary theater.
-    // A human message code is reachable through exactly two human paths:
-    //   (1) the server boot path: no_api_key (emitted directly when the key env var is unset) + whatever
-    //       humanCodeForBoot can return (the ONLY bridge from a thrown boot error to a human code —
-    //       server.ts boot catch + bin.ts last-resort catch both go through it); OR
-    //   (2) the installer path: the codes init.ts/doctor.ts reference, enumerated by installerCodes().
-    // We derive the reachable set mechanically from both, so a future dict entry with no caller fails
-    // this test, and an installer code with no dict entry fails it too.
-    const coreErrorCodes = ["network", "not_found", "bad_response", "core_error"];
-    const reachable = new Set(["no_api_key"]);
-    for (const c of coreErrorCodes)
-        reachable.add(humanCodeForBoot(c));
-    for (const c of installerCodes())
-        reachable.add(c);
-    const declared = new Set(messageCodes());
-    assert.deepEqual([...declared].sort(), [...reachable].sort(), "dictionary must contain exactly the human-reachable codes — no orphans, no missing");
-});
-test("every installer code has a real dictionary entry (not just a listed name)", () => {
-    // installerCodes() is the guard's source of truth for path (2). Prove each one resolves to a real,
-    // non-empty, non-fallback string in all three locales — a name in the list with no MESSAGES entry
-    // would otherwise pass the union test only because humanMessage falls back to `unknown`.
-    const dict = messagesForTest();
-    for (const code of installerCodes()) {
-        assert.ok(dict[code], `installer code ${code} has no dictionary entry`);
-        for (const loc of allLocales()) {
-            assert.ok((dict[code][loc] ?? "").trim().length > 0, `empty ${loc} for ${code}`);
-        }
-    }
-});