humanish 0.104.3 → 0.106.0

package/dist/comms/catch-host.js

@@ -0,0 +1,192 @@
+// `humanish comms catch` (#328): run the email catch on the OPERATOR's own host.
+//
+// Why this exists. The in-sandbox catch only works when humanish provisions the subject itself —
+// it clones the app into a sandbox, injects the email-API base URL at boot, and hosts the catch
+// alongside it. An adopter whose study runs against their OWN deployed environment (an app-url or
+// operator-provisioned plane) hands humanish a URL instead, so humanish never boots the app and
+// has nowhere to put a catch. Before this, a `comms:` block on that route was warned inert and the
+// personas simply stalled at the verification screen.
+//
+// The fix is to let the adopter host the same catch and declare it (`comms.email.external`).
+// Shipping it as a COMMAND rather than a spec matters: the adopter runs the identical
+// implementation humanish deploys in-sandbox, so the capture shape, the inbox surface, and the
+// drain contract cannot drift between the two planes. Point the app's email-API base URL at this
+// server and point the lab's `catchBaseUrl` at it too.
+//
+// Runtime: the catch is a python3 stdlib server with no dependencies (that was the 0.29.0 lesson —
+// a co-located catcher must use a runtime the environment guarantees). This command writes the
+// same script and runs it in the foreground until interrupted.
+import { spawn } from "node:child_process";
+import { mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { capturedRecipientAddresses, inboxMessagesFrom, parseDeliveriesNdjson, } from "./sandbox-catch.js";
+import { SANDBOX_CATCH_SCRIPT } from "./sandbox-catch-script.js";
+import { buildInboxSurface } from "./capture-surface.js";
+/** How often the host re-renders the inbox surface from the deliveries file. */
+const DEFAULT_RENDER_INTERVAL_MS = 3_000;
+/**
+ * Render the persona-facing inbox surface from the catch's own deliveries file into `surfaceDir`.
+ *
+ * This is the half that was missing on an adopter-hosted plane (#380). The catch serves /inbox and
+ * /api/inbox as STATIC FILES; in-sandbox, humanish-as-host renders those files on a cadence. On a
+ * plane humanish does not provision there is no such host, so nothing wrote them and every persona
+ * that reached /inbox got `message not found` against a catch whose /health was green — the funnel
+ * dead-ended at a technically-healthy service.
+ *
+ * Rebuilding from scratch each pass is deliberate and matches refreshInboxSurface: a fresh channel per
+ * pass means a send is never routed twice, so the persona never sees duplicates, and a failed write
+ * simply retries next tick.
+ */
+export async function renderInboxSurfaceLocally(args) {
+    let text = "";
+    try {
+        text = await readFile(args.deliveriesPath, "utf8");
+    }
+    catch {
+        text = ""; // no mail captured yet — still render, so /inbox answers "No messages yet."
+    }
+    const sends = parseDeliveriesNdjson(text);
+    const addresses = args.recipients && args.recipients.length > 0
+        ? args.recipients
+        : capturedRecipientAddresses(sends);
+    const recipients = addresses.map((address, index) => ({
+        participantId: `catch-${String(index + 1).padStart(2, "0")}`,
+        address,
+    }));
+    const messages = await inboxMessagesFrom(sends, recipients);
+    const files = buildInboxSurface(messages, { recipients: addresses });
+    // A reused catch directory can change recipients or truncate its delivery log. Remove ONLY files
+    // recorded as generated routes, so old recipient/message URLs cannot survive that change.
+    const manifestPath = path.join(args.surfaceDir, ".inbox-files.json");
+    let previous = [];
+    try {
+        previous = JSON.parse(await readFile(manifestPath, "utf8"));
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+    }
+    const generatedPath = /^(?:api\/)?inbox\/(?:for\/[a-f0-9]{64}\/)?(?:index|(?:comms-[0-9]+|latest)(?:\/index|\/synth)?)$/;
+    const oldPaths = Array.isArray(previous)
+        ? previous.filter((value) => typeof value === "string" && generatedPath.test(value))
+        : [];
+    const currentPaths = new Set(files.map((file) => file.path));
+    const dirs = new Set([args.surfaceDir]);
+    for (const file of files) {
+        const slash = file.path.lastIndexOf("/");
+        if (slash > 0)
+            dirs.add(path.join(args.surfaceDir, file.path.slice(0, slash)));
+    }
+    for (const dir of dirs)
+        await mkdir(dir, { recursive: true });
+    const saveManifest = async (paths) => {
+        await writeFile(manifestPath + ".next", JSON.stringify(paths), "utf8");
+        await rename(manifestPath + ".next", manifestPath);
+    };
+    // Record the union first: a partial write is retryable and its new files remain tracked.
+    await saveManifest([...new Set([...oldPaths, ...currentPaths])]);
+    for (const obsolete of oldPaths)
+        if (!currentPaths.has(obsolete))
+            await rm(path.join(args.surfaceDir, obsolete), { force: true });
+    for (const file of files)
+        await writeFile(path.join(args.surfaceDir, file.path), file.body, "utf8");
+    await saveManifest([...currentPaths]);
+    return { sends: sends.length, messages: messages.length, files: files.length };
+}
+/**
+ * Write the catch script and run it in the foreground. Resolves when the child exits; the caller's
+ * Ctrl-C reaches the child through the shared process group, so the normal way to stop it is the
+ * normal way to stop any foreground server.
+ */
+export async function runCommsCatchHost(options, io) {
+    const dir = path.resolve(options.dir);
+    const scriptPath = path.join(dir, "catch.py");
+    const deliveriesPath = path.join(dir, "deliveries.ndjson");
+    const surfaceDir = path.join(dir, "surface");
+    await mkdir(surfaceDir, { recursive: true });
+    await writeFile(scriptPath, SANDBOX_CATCH_SCRIPT, "utf8");
+    // Render the EMPTY inbox before the server is announced, so /inbox resolves to the "No messages
+    // yet." page from the first request instead of a bare `message not found` (#380) — a persona reads
+    // that 404 as a broken product and reports a blocker that is really just an empty mailbox.
+    await renderInboxSurfaceLocally({
+        deliveriesPath,
+        surfaceDir,
+        ...(options.recipients === undefined ? {} : { recipients: options.recipients }),
+    });
+    const inboxPort = options.inboxPort;
+    const args = [
+        scriptPath,
+        String(options.port),
+        deliveriesPath,
+        surfaceDir,
+        String(inboxPort ?? 0),
+        options.token ?? "",
+        String(options.smtpPort ?? 0),
+    ];
+    io.writeOut([
+        `Starting humanish comms catch on http://127.0.0.1:${options.port}`,
+        ...(options.smtpPort === undefined
+            ? []
+            : [`  SMTP 127.0.0.1:${options.smtpPort} <- point your app's SMTP transport here`]),
+        ...(inboxPort === undefined
+            ? []
+            : [
+                `  read-only inbox listener on http://0.0.0.0:${inboxPort} (GET only; expose THIS to personas)`,
+            ]),
+        `  POST /emails        <- point your app's email-API base URL here`,
+        `  GET  /inbox         <- shared operator inbox${inboxPort === undefined ? " (loopback only without --inbox-port)" : ""}`,
+        `  GET  /inbox/for/... <- assigned participant inbox (linked by the lab)`,
+        `  GET  /deliveries    <- humanish drains this${options.token ? " (bearer token required)" : ""}`,
+        `  GET  /health        <- readiness marker humanish probes before a run`,
+        ``,
+        `Declare it in the lab:`,
+        `  comms:`,
+        `    email:`,
+        `      external:`,
+        `        catchBaseUrl: http://<this-host>:${options.port}`,
+        ...(inboxPort === undefined ? [] : [`        inboxBaseUrl: http://<this-host>:${inboxPort}`]),
+        ...(options.token
+            ? [`        authTokenEnv: HUMANISH_COMMS_TOKEN   # value read at runtime, never persisted`]
+            : []),
+        ``,
+        `Captured mail is written to ${deliveriesPath}. Raw bodies stay on THIS host: the run bundle`,
+        `only ever receives digests (from/to/subject/link) and an OTP count.`,
+        ``,
+    ].join("\n") + "\n");
+    await new Promise((resolve) => {
+        const child = spawn("python3", args, { stdio: ["ignore", "inherit", "inherit"] });
+        // Keep the inbox current while the catch runs. Failures are swallowed on purpose: a transient
+        // render error must never take down a server that is still capturing mail correctly, and the
+        // next tick rebuilds from scratch anyway.
+        let rendering = false;
+        const renderTimer = setInterval(() => {
+            if (rendering)
+                return;
+            rendering = true;
+            void renderInboxSurfaceLocally({
+                deliveriesPath,
+                surfaceDir,
+                ...(options.recipients === undefined ? {} : { recipients: options.recipients }),
+            })
+                .catch(() => { })
+                .finally(() => {
+                rendering = false;
+            });
+        }, options.renderIntervalMs ?? DEFAULT_RENDER_INTERVAL_MS);
+        renderTimer.unref?.();
+        const stopRendering = () => clearInterval(renderTimer);
+        child.on("error", (error) => {
+            stopRendering();
+            io.writeErr(`comms catch failed to start (python3 is required): ${error.message}\n`);
+            io.setExitCode(2);
+            resolve();
+        });
+        child.on("exit", (code) => {
+            stopRendering();
+            if (code !== 0 && code !== null) {
+                io.setExitCode(2);
+            }
+            resolve();
+        });
+    });
+}

package/dist/comms/connections.d.ts

@@ -0,0 +1,20 @@
+import { COMMS_PROVIDERS, type ReceivingProviderId } from "./providers.js";
+declare const COMMS_CONNECTIONS_SCHEMA = "humanish.comms-connections.v1";
+export declare const COMMS_CONFIG_PATH = ".humanish/local/comms.yaml";
+export { COMMS_PROVIDERS };
+export interface CommsConnection {
+    provider: ReceivingProviderId;
+    apiKeyEnv: string;
+}
+export interface CommsConnections {
+    schema: typeof COMMS_CONNECTIONS_SCHEMA;
+    connections: Record<string, CommsConnection>;
+}
+export interface CommsSetupResult {
+    ok: boolean;
+    message: string;
+}
+/** Offline and non-mutating. Unsafe storage is an error, never an empty configuration. */
+export declare function readCommsConnections(cwd: string): Promise<CommsConnections>;
+/** Add one exact profile. No lab mutation, network, provider resources or credential values. */
+export declare function saveCommsConnection(cwd: string, name?: string, apiKeyEnv?: string): Promise<CommsSetupResult>;

package/dist/comms/connections.js

@@ -0,0 +1,116 @@
+import { constants } from "node:fs";
+import { lstat, open, unlink } from "node:fs/promises";
+import path from "node:path";
+import { parse, stringify } from "yaml";
+import { COMMS_PROVIDERS, DEFAULT_COMMS_PROVIDER, isReceivingProviderId, } from "./providers.js";
+import { assertPreparedSelectedOutputDirectory, bindExistingManagedHumanishOutputDirectory, prepareManagedHumanishOutputDirectory, readContainedRegularFile, writeContainedOutputFile, } from "../run/contained-output.js";
+const COMMS_CONNECTIONS_SCHEMA = "humanish.comms-connections.v1";
+export const COMMS_CONFIG_PATH = ".humanish/local/comms.yaml";
+export { COMMS_PROVIDERS };
+const record = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const validName = (name) => /^[a-z][a-z0-9-]{0,47}$/.test(name) && name !== "constructor" && name !== "prototype";
+const empty = () => ({ schema: COMMS_CONNECTIONS_SCHEMA, connections: {} });
+async function exists(file) {
+    try {
+        await lstat(file);
+        return true;
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return false;
+        throw error;
+    }
+}
+function parseConnections(raw) {
+    if (!record(raw) ||
+        raw.schema !== COMMS_CONNECTIONS_SCHEMA ||
+        !record(raw.connections) ||
+        Object.keys(raw).some((key) => key !== "schema" && key !== "connections") ||
+        Object.keys(raw.connections).length > 32)
+        throw new Error("Invalid connection configuration.");
+    const connections = {};
+    for (const [name, value] of Object.entries(raw.connections)) {
+        if (!validName(name) ||
+            !record(value) ||
+            !isReceivingProviderId(value.provider) ||
+            typeof value.apiKeyEnv !== "string" ||
+            !/^[A-Z][A-Z0-9_]{0,99}$/.test(value.apiKeyEnv) ||
+            Object.keys(value).some((key) => key !== "provider" && key !== "apiKeyEnv"))
+            throw new Error("Invalid connection configuration.");
+        connections[name] = { provider: value.provider, apiKeyEnv: value.apiKeyEnv };
+    }
+    return { schema: COMMS_CONNECTIONS_SCHEMA, connections };
+}
+/** Offline and non-mutating. Unsafe storage is an error, never an empty configuration. */
+export async function readCommsConnections(cwd) {
+    const root = await bindExistingManagedHumanishOutputDirectory(cwd, "local");
+    if (!root) {
+        if (await exists(path.resolve(cwd, ".humanish", "local")))
+            throw new Error("Unsafe connection directory.");
+        return empty();
+    }
+    const file = path.join(root.physicalPath, "comms.yaml");
+    if (!(await exists(file)))
+        return empty();
+    if ((await lstat(file)).size > 65_536)
+        throw new Error("Connection configuration is too large.");
+    const bytes = await readContainedRegularFile(root, "comms.yaml");
+    if (!bytes || bytes.length > 65_536)
+        throw new Error("Cannot safely read connection configuration.");
+    // YAML diagnostics may echo the offending value; do not let them reach a status or frame.
+    try {
+        return parseConnections(parse(bytes.toString("utf8"), { maxAliasCount: 0 }));
+    }
+    catch {
+        throw new Error("Invalid connection configuration.");
+    }
+}
+/** Add one exact profile. No lab mutation, network, provider resources or credential values. */
+export async function saveCommsConnection(cwd, name = DEFAULT_COMMS_PROVIDER.id, apiKeyEnv = DEFAULT_COMMS_PROVIDER.keyEnv) {
+    const provider = DEFAULT_COMMS_PROVIDER.id;
+    try {
+        parseConnections({
+            schema: COMMS_CONNECTIONS_SCHEMA,
+            connections: { [name]: { provider, apiKeyEnv } },
+        });
+        // Read before creating storage, so malformed or redirected existing configuration fails first.
+        await readCommsConnections(cwd);
+        const root = await prepareManagedHumanishOutputDirectory(cwd, "local");
+        const lockPath = path.join(root.physicalPath, ".comms-setup.lock");
+        const lock = await open(lockPath, constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY | constants.O_NOFOLLOW, 0o600);
+        const identity = await lock.stat();
+        try {
+            await assertPreparedSelectedOutputDirectory(root);
+            const config = await readCommsConnections(cwd);
+            const previous = config.connections[name];
+            if (previous && (previous.provider !== provider || previous.apiKeyEnv !== apiKeyEnv)) {
+                return {
+                    ok: false,
+                    message: "That connection name already uses different settings. Choose another name.",
+                };
+            }
+            config.connections[name] = { provider, apiKeyEnv };
+            parseConnections(config);
+            await writeContainedOutputFile(root, "comms.yaml", stringify(config), "utf8");
+            return {
+                ok: true,
+                message: "Connection saved for this project. Select it in a supported lab to use fresh real inboxes.",
+            };
+        }
+        finally {
+            await lock.close();
+            await assertPreparedSelectedOutputDirectory(root);
+            const current = await lstat(lockPath);
+            if (current.dev === identity.dev && current.ino === identity.ino)
+                await unlink(lockPath);
+        }
+    }
+    catch (error) {
+        return {
+            ok: false,
+            message: error.code === "EEXIST"
+                ? "Connection setup is locked. Close another setup session; after an interrupted save, remove .humanish/local/.comms-setup.lock and retry."
+                : "Could not save the connection. Inspect .humanish/local/comms.yaml and its directory permissions before retrying.",
+        };
+    }
+}

package/dist/comms/email-catch.d.ts

@@ -0,0 +1,49 @@
+import { type ServerResponse } from "node:http";
+import type { CommsChannel, CommsInlineImage } from "./types.js";
+/** One send, normalized across providers. `body` is html-preferred, else text. */
+interface NormalizedSend {
+    from: string;
+    to: string[];
+    subject?: string;
+    body: string;
+    inlineImages?: CommsInlineImage[];
+}
+/**
+ * A provider wire-shape adapter. Vendor-neutral seam: the server owns the HTTP + routing + bus
+ * delivery; a profile only knows how ONE provider (or a custom app) shapes its send request.
+ */
+export interface EmailSendProfile {
+    /** Descriptive name (e.g. "generic", "sendgrid"). Not a dependency — just a label. */
+    name: string;
+    /** Request paths (method POST) this profile accepts a send on. */
+    sendPaths: string[];
+    /** Parse a POST body (already JSON-parsed) into zero+ normalized sends (a batch yields many). */
+    parse(path: string, body: unknown): NormalizedSend[];
+    /** Optional provider-faithful success response. Default: 200 `{ id }` (single) / `{ data:[{id}] }`. */
+    respond?: (res: ServerResponse, ids: string[], batch: boolean) => void;
+}
+export interface EmailCatchServer {
+    /** Point the app's email-API base URL here (loopback only). */
+    readonly url: string;
+    readonly port: number;
+    /** Every normalized send accepted this run (runtime-only; for inspection/tests). */
+    readonly received: NormalizedSend[];
+    close(): Promise<void>;
+}
+export interface EmailCatchOptions {
+    /** Bind host. Default 127.0.0.1 (loopback ONLY). */
+    host?: string;
+    /** Port. Default 0 (ephemeral). */
+    port?: number;
+    /** Wire-shape profiles, tried in order by path. Default [genericEmailProfile, sendgridEmailProfile]. */
+    profiles?: EmailSendProfile[];
+    /** Deterministic id for responses (tests). Default a zero-padded counter. */
+    idFor?: (n: number) => string;
+}
+export declare const DEFAULT_EMAIL_PROFILES: EmailSendProfile[];
+/**
+ * Start the vendor-neutral email catch, routing accepted sends into `channel`. Returns the loopback
+ * URL to hand the app as its email-API base URL. `close()` in a finally (mirror by-id teardown).
+ */
+export declare function startEmailCatchServer(channel: CommsChannel, options?: EmailCatchOptions): Promise<EmailCatchServer>;
+export {};

package/dist/comms/email-catch.js

@@ -0,0 +1,236 @@
+// A VENDOR-NEUTRAL loopback catch server for email-send APIs (#297). An app hardwired to a hosted
+// email provider is redirected into the fake bus with ONE env var and no code change: point the app's
+// API base URL at this server. The catch does not depend on, or name itself after, any one vendor —
+// it normalizes each provider's distinct wire shape (Resend's flat body, SendGrid's nested
+// personalizations, Postmark's TitleCase, a custom app's own JSON) to one shape via pluggable
+// PROFILES, and routes the result into a CommsChannel. Resend-compatible and SendGrid-compatible out
+// of the box; extend with a custom profile for anything else. (There is no standardized email-send
+// request shape across vendors, so normalization is by design, not a shortcut.)
+//
+// 127.0.0.1 only; request bodies are never logged; request size is capped.
+import { createServer } from "node:http";
+import { capturedInlineImages } from "./images.js";
+// ---------------------------------------------------------------- shared parse helpers
+function str(value) {
+    return typeof value === "string" ? value : "";
+}
+function optStr(value) {
+    return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+/** "Name <email@host>" → "email@host"; a bare address passes through. */
+function bareEmail(value) {
+    const angle = value.match(/<([^>]+)>/);
+    return (angle ? (angle[1] ?? value) : value).trim();
+}
+/** A recipient field → address strings: an array, a single, or a comma-separated string (Postmark). */
+function toAddresses(value) {
+    if (Array.isArray(value))
+        return value.map((entry) => bareEmail(String(entry)));
+    if (typeof value === "string")
+        return value
+            .split(",")
+            .map((part) => bareEmail(part))
+            .filter((part) => part.length > 0);
+    return [];
+}
+// ---------------------------------------------------------------- built-in profiles
+/** The flat-JSON shape: `{ from, to, subject, html, text }`. Matches Resend (POST /emails) AND a
+ *  custom app that sends the common shape AND Postmark's TitleCase keys (From/To/HtmlBody/…). */
+const genericEmailProfile = {
+    name: "generic",
+    sendPaths: ["/emails", "/emails/batch", "/email", "/email/batch", "/send"],
+    parse(_path, body) {
+        const items = Array.isArray(body) ? body : [body];
+        const out = [];
+        for (const item of items) {
+            if (typeof item !== "object" || item === null)
+                continue;
+            const rec = item;
+            const from = str(rec.from ?? rec.From);
+            const to = toAddresses(rec.to ?? rec.To);
+            const subject = optStr(rec.subject ?? rec.Subject);
+            const bodyValue = str(rec.html ?? rec.HtmlBody ?? rec.text ?? rec.TextBody);
+            if (to.length === 0 && from === "" && bodyValue === "")
+                continue;
+            const inlineImages = capturedInlineImages(rec.inlineImages);
+            out.push({
+                from,
+                to,
+                ...(subject === undefined ? {} : { subject }),
+                body: bodyValue,
+                ...(inlineImages.length ? { inlineImages } : {}),
+            });
+        }
+        return out;
+    },
+};
+/** SendGrid's nested shape: `from.email`, `personalizations[].to[].email`, `content[].value`. Proves
+ *  the seam handles a structurally different vendor, not just a field-name rename. */
+const sendgridEmailProfile = {
+    name: "sendgrid",
+    sendPaths: ["/v3/mail/send"],
+    parse(_path, body) {
+        if (typeof body !== "object" || body === null)
+            return [];
+        const rec = body;
+        const fromObj = rec.from;
+        const from = typeof fromObj === "object" && fromObj !== null
+            ? str(fromObj.email)
+            : str(fromObj);
+        const subject = optStr(rec.subject);
+        const content = Array.isArray(rec.content) ? rec.content : [];
+        const isPart = (part) => typeof part === "object" && part !== null;
+        const chosen = content.find((part) => isPart(part) && part.type === "text/html") ??
+            content.find((part) => isPart(part) && part.type === "text/plain");
+        const bodyValue = isPart(chosen) ? str(chosen.value) : "";
+        const personalizations = Array.isArray(rec.personalizations)
+            ? rec.personalizations
+            : [];
+        const to = [];
+        for (const personalization of personalizations) {
+            if (!isPart(personalization))
+                continue;
+            const recipients = Array.isArray(personalization.to) ? personalization.to : [];
+            for (const recipient of recipients) {
+                if (!isPart(recipient))
+                    continue;
+                const email = str(recipient.email);
+                if (email.length > 0)
+                    to.push(email);
+            }
+        }
+        if (to.length === 0)
+            return [];
+        return [{ from, to, ...(subject === undefined ? {} : { subject }), body: bodyValue }];
+    },
+    respond(res, ids, _batch) {
+        // SendGrid answers 202 with the id in a header and an empty body.
+        res.statusCode = 202;
+        if (ids[0] !== undefined)
+            res.setHeader("x-message-id", ids[0]);
+        res.end();
+    },
+};
+export const DEFAULT_EMAIL_PROFILES = [
+    genericEmailProfile,
+    sendgridEmailProfile,
+];
+// ---------------------------------------------------------------- server
+class BodyTooLargeError extends Error {
+}
+function readBody(req, limit) {
+    return new Promise((resolve, reject) => {
+        let size = 0;
+        const chunks = [];
+        req.on("data", (chunk) => {
+            size += chunk.length;
+            if (size > limit) {
+                // Reject WITHOUT destroying the socket here: the handler responds 413 cleanly first (a
+                // write-after-destroy would otherwise reset the connection), then tears the request down.
+                reject(new BodyTooLargeError("request body too large"));
+                return;
+            }
+            chunks.push(chunk);
+        });
+        req.on("end", () => resolve(Buffer.concat(chunks).toString("utf8")));
+        req.on("error", reject);
+    });
+}
+const MAX_BODY_BYTES = 5 * 1024 * 1024;
+/**
+ * Start the vendor-neutral email catch, routing accepted sends into `channel`. Returns the loopback
+ * URL to hand the app as its email-API base URL. `close()` in a finally (mirror by-id teardown).
+ */
+export async function startEmailCatchServer(channel, options = {}) {
+    const host = options.host ?? "127.0.0.1";
+    const profiles = options.profiles ?? DEFAULT_EMAIL_PROFILES;
+    const received = [];
+    let idCounter = 0;
+    const idFor = options.idFor ?? ((n) => `humanish-catch-${n.toString().padStart(6, "0")}`);
+    const respondJson = (res, status, value) => {
+        res.statusCode = status;
+        res.setHeader("content-type", "application/json");
+        res.end(JSON.stringify(value));
+    };
+    const handle = async (req, res) => {
+        const path = (req.url ?? "/").split("?")[0] ?? "/";
+        if (req.method === "GET" && (path === "/" || path === "/health")) {
+            respondJson(res, 200, {
+                ok: true,
+                service: "humanish-email-catch",
+                channel: channel.channel,
+                profiles: profiles.map((p) => p.name),
+            });
+            return;
+        }
+        const profile = req.method === "POST"
+            ? profiles.find((candidate) => candidate.sendPaths.includes(path))
+            : undefined;
+        if (profile === undefined) {
+            respondJson(res, 404, { error: "not found" });
+            return;
+        }
+        let raw;
+        try {
+            raw = await readBody(req, MAX_BODY_BYTES);
+        }
+        catch (error) {
+            if (!res.headersSent)
+                respondJson(res, error instanceof BodyTooLargeError ? 413 : 400, {
+                    error: "request body could not be read",
+                });
+            req.destroy();
+            return;
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(raw.length > 0 ? raw : "{}");
+        }
+        catch {
+            respondJson(res, 422, { error: "invalid JSON body" });
+            return;
+        }
+        const sends = profile.parse(path, parsed);
+        if (sends.length === 0) {
+            // A well-formed request that names no deliverable recipient (empty body, or a shape the profile
+            // could not resolve to a send) — return a bad-request rather than a fabricated success id.
+            respondJson(res, 422, { error: "no deliverable message in request" });
+            return;
+        }
+        const ids = [];
+        for (const send of sends) {
+            received.push(send);
+            const inbound = {
+                from: send.from,
+                to: send.to,
+                ...(send.subject === undefined ? {} : { subject: send.subject }),
+                body: send.body,
+                ...(send.inlineImages ? { inlineImages: send.inlineImages } : {}),
+            };
+            await channel.deliverRaw(inbound);
+            idCounter += 1;
+            ids.push(idFor(idCounter));
+        }
+        const batch = Array.isArray(parsed) || path.endsWith("/batch");
+        if (profile.respond)
+            profile.respond(res, ids, batch);
+        else if (batch)
+            respondJson(res, 200, { data: ids.map((id) => ({ id })) });
+        else
+            respondJson(res, 200, { id: ids[0] ?? idFor(idCounter) });
+    };
+    const server = createServer((req, res) => {
+        void handle(req, res).catch(() => {
+            if (!res.headersSent)
+                respondJson(res, 500, { error: "catch server error" });
+        });
+    });
+    await new Promise((resolve) => server.listen(options.port ?? 0, host, () => resolve()));
+    const port = server.address().port;
+    return {
+        url: `http://${host}:${port}`,
+        port,
+        received,
+        close: () => new Promise((resolve) => server.close(() => resolve())),
+    };
+}

package/dist/comms/extract.d.ts

@@ -0,0 +1,7 @@
+/** Extract actionable http(s) links from a message body (href="…" and bare URLs), de-duped, in order.
+ *  The verification magic-link the persona would tap. Pure; body is runtime-only. */
+export declare function extractLinks(body: string): string[];
+/** Extract OTP-shaped tokens from a message body. Labeled codes ("your code is 481920",
+ *  "verification code 8A3F2K") are high-precision and preferred; if none are labeled, fall back to an
+ *  isolated 4–8 digit run (a bare OTP). Pure; tokens are runtime-only literal-scrub targets. */
+export declare function extractOtpCodes(body: string): string[];