@roamcode.ai/server 1.0.0

package/dist/managed-runtime.js

@@ -0,0 +1,411 @@
+import { spawn } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { chmodSync, existsSync, lstatSync, mkdirSync, openSync, closeSync, readdirSync, readFileSync, realpathSync, renameSync, rmSync, symlinkSync, unlinkSync, writeFileSync, } from "node:fs";
+import { homedir, tmpdir } from "node:os";
+import { basename, dirname, join, relative, resolve } from "node:path";
+import { migrateServiceToLauncher, readServiceRecord, restartService } from "./service-install.js";
+const VERSION_RE = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/;
+const LOCK_STALE_MS = 30 * 60_000;
+export function resolveInstallRoot(env = process.env, home = homedir()) {
+    return env.ROAMCODE_INSTALL_ROOT || join(home, ".local", "share", "roamcode");
+}
+export function managedPaths(root) {
+    return {
+        root,
+        releases: join(root, "releases"),
+        staging: join(root, "staging"),
+        current: join(root, "current"),
+        previous: join(root, "previous"),
+        bin: join(root, "bin"),
+        launcher: join(root, "bin", "roamcode"),
+        lock: join(root, "update.lock"),
+    };
+}
+export function isStableVersion(value) {
+    return VERSION_RE.test(value);
+}
+export function compareVersions(a, b) {
+    if (!isStableVersion(a) || !isStableVersion(b))
+        throw new Error(`invalid stable version: ${a} / ${b}`);
+    const av = a.split(".").map(Number);
+    const bv = b.split(".").map(Number);
+    for (let i = 0; i < 3; i += 1) {
+        if (av[i] !== bv[i])
+            return av[i] < bv[i] ? -1 : 1;
+    }
+    return 0;
+}
+function atomicWrite(path, value, mode = 0o600) {
+    mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+    const temp = `${path}.${process.pid}.${randomUUID()}.tmp`;
+    writeFileSync(temp, value, { mode });
+    chmodSync(temp, mode);
+    renameSync(temp, path);
+}
+export function renderManagedLauncher(root, nodePath) {
+    const q = (value) => `'${value.replace(/'/g, `'\\''`)}'`;
+    return [
+        "#!/bin/sh",
+        "set -eu",
+        `ROOT=${q(root)}`,
+        `NODE=${q(nodePath)}`,
+        'if [ ! -x "$NODE" ]; then NODE="$(command -v node || true)"; fi',
+        'if [ -z "$NODE" ]; then echo "Node.js >= 24 is required" >&2; exit 1; fi',
+        'ENTRY="$ROOT/current/node_modules/roamcode/dist/index.js"',
+        'if [ ! -f "$ENTRY" ]; then',
+        '  echo "roamcode managed runtime is missing; run: npx roamcode@latest install" >&2',
+        "  exit 1",
+        "fi",
+        'export ROAMCODE_INSTALL_ROOT="$ROOT"',
+        'export ROAMCODE_MANAGED_EXEC="1"',
+        'exec "$NODE" "$ENTRY" "$@"',
+        "",
+    ].join("\n");
+}
+export function writeManagedLauncher(root, nodePath = process.execPath) {
+    const paths = managedPaths(root);
+    mkdirSync(paths.bin, { recursive: true, mode: 0o700 });
+    atomicWrite(paths.launcher, renderManagedLauncher(root, nodePath), 0o700);
+    return paths.launcher;
+}
+function versionFromReleaseDir(dir) {
+    try {
+        const manifest = JSON.parse(readFileSync(join(dir, "release.json"), "utf8"));
+        if (typeof manifest.version === "string" && isStableVersion(manifest.version))
+            return manifest.version;
+    }
+    catch {
+        // Older managed installs may not have release.json; fall back to the npm package manifest.
+    }
+    try {
+        const pkg = JSON.parse(readFileSync(join(dir, "node_modules", "roamcode", "package.json"), "utf8"));
+        return typeof pkg.version === "string" && isStableVersion(pkg.version) ? pkg.version : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function integrityFromReleaseDir(dir) {
+    try {
+        const manifest = JSON.parse(readFileSync(join(dir, "release.json"), "utf8"));
+        return typeof manifest.integrity === "string" ? manifest.integrity : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+export function readActiveVersion(root) {
+    const current = managedPaths(root).current;
+    try {
+        return versionFromReleaseDir(realpathSync(current));
+    }
+    catch {
+        return undefined;
+    }
+}
+export function readPreviousVersion(root) {
+    try {
+        return versionFromReleaseDir(realpathSync(managedPaths(root).previous));
+    }
+    catch {
+        return undefined;
+    }
+}
+function acquireLock(path, now) {
+    mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+    try {
+        const fd = openSync(path, "wx", 0o600);
+        writeFileSync(fd, JSON.stringify({ pid: process.pid, at: now }) + "\n");
+        closeSync(fd);
+    }
+    catch {
+        try {
+            if (now - lstatSync(path).mtimeMs > LOCK_STALE_MS) {
+                unlinkSync(path);
+                return acquireLock(path, now);
+            }
+        }
+        catch {
+            // The competing process may have removed it; the retry below will either acquire or report busy.
+            try {
+                return acquireLock(path, now);
+            }
+            catch {
+                // handled by the stable error below
+            }
+        }
+        throw new Error("an update is already in progress");
+    }
+    return () => {
+        try {
+            unlinkSync(path);
+        }
+        catch {
+            // best effort
+        }
+    };
+}
+async function runLogged(command, args, opts) {
+    await new Promise((resolvePromise, reject) => {
+        const child = spawn(command, args, {
+            cwd: opts.cwd,
+            env: opts.env ?? process.env,
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+        child.stdout?.on("data", (chunk) => opts.log(chunk.toString()));
+        child.stderr?.on("data", (chunk) => opts.log(chunk.toString()));
+        child.on("error", reject);
+        child.on("close", (code) => code === 0 ? resolvePromise() : reject(new Error(`${basename(command)} exited ${code}`)));
+    });
+}
+function npmInvocation(npmCommand, args, nodePath) {
+    if (npmCommand.endsWith(".js") || npmCommand.endsWith(".cjs"))
+        return { command: nodePath, args: [npmCommand, ...args] };
+    return { command: npmCommand, args };
+}
+async function npmIntegrity(npmCommand, packageName, version, nodePath, log) {
+    let output = "";
+    const invocation = npmInvocation(npmCommand, ["view", `${packageName}@${version}`, "dist.integrity", "--json"], nodePath);
+    await new Promise((resolvePromise, reject) => {
+        const child = spawn(invocation.command, invocation.args, { stdio: ["ignore", "pipe", "pipe"] });
+        child.stdout?.on("data", (chunk) => (output += chunk.toString()));
+        child.stderr?.on("data", (chunk) => log(chunk.toString()));
+        child.on("error", reject);
+        child.on("close", (code) => (code === 0 ? resolvePromise() : reject(new Error(`npm view exited ${code}`))));
+    });
+    const parsed = JSON.parse(output);
+    if (typeof parsed !== "string" || !parsed.startsWith("sha512-"))
+        throw new Error("npm returned no package integrity");
+    return parsed;
+}
+async function smokeServer(serverEntry, dataDir, nodePath, log) {
+    const smokeDir = join(tmpdir(), `roamcode-smoke-${process.pid}-${randomUUID()}`);
+    mkdirSync(smokeDir, { recursive: true, mode: 0o700 });
+    let output = "";
+    const child = spawn(nodePath, [serverEntry], {
+        env: {
+            ...process.env,
+            PORT: "0",
+            BIND_ADDRESS: "127.0.0.1",
+            ACCESS_TOKEN: `rc-smoke-${randomUUID()}`,
+            ROAMCODE_DATA_DIR: smokeDir,
+            RC_TMUX_SOCKET: `rc-smoke-${process.pid}`,
+            ROAMCODE_INSTALL_ROOT: "",
+        },
+        stdio: ["ignore", "pipe", "pipe"],
+    });
+    const collect = (chunk) => {
+        const text = chunk.toString();
+        output += text;
+        log(text);
+    };
+    child.stdout?.on("data", collect);
+    child.stderr?.on("data", collect);
+    try {
+        const url = await new Promise((resolveUrl, reject) => {
+            const deadline = setTimeout(() => reject(new Error("new release did not start within 25s")), 25_000);
+            const poll = setInterval(() => {
+                const match = output.match(/listening on (http:\/\/127\.0\.0\.1:\d+)/);
+                if (match?.[1]) {
+                    clearInterval(poll);
+                    clearTimeout(deadline);
+                    resolveUrl(match[1]);
+                }
+            }, 100);
+            child.once("exit", (code) => {
+                clearInterval(poll);
+                clearTimeout(deadline);
+                reject(new Error(`new release exited before health check (${code})`));
+            });
+        });
+        const healthy = await fetch(`${url}/health`, { signal: AbortSignal.timeout(5_000) });
+        if (!healthy.ok)
+            throw new Error(`new release health check returned ${healthy.status}`);
+    }
+    finally {
+        child.kill("SIGTERM");
+        rmSync(smokeDir, { recursive: true, force: true });
+        // dataDir is intentionally part of the signature: callers cannot accidentally smoke with production data.
+        void dataDir;
+    }
+}
+function replaceSymlink(link, target) {
+    const temp = `${link}.${process.pid}.${randomUUID()}.new`;
+    try {
+        unlinkSync(temp);
+    }
+    catch {
+        // absent
+    }
+    // Canonicalize both sides before computing a relative link. On macOS `/var` resolves to
+    // `/private/var`; mixing one spelling from mkdtemp with the other from realpath creates a broken link.
+    const parent = realpathSync(dirname(link));
+    const canonicalTarget = realpathSync(target);
+    symlinkSync(relative(parent, canonicalTarget), temp, "dir");
+    renameSync(temp, link);
+}
+function trimLog(log) {
+    return log.split("\n").slice(-20).join("\n").slice(-8_000);
+}
+export async function installManagedRelease(opts) {
+    if (!isStableVersion(opts.version))
+        throw new Error(`invalid release version: ${opts.version}`);
+    const now = opts.now ?? Date.now;
+    const operationId = opts.operationId ?? randomUUID();
+    const nodePath = opts.nodePath ?? process.execPath;
+    const npmCommand = opts.npmCommand ?? process.env.npm_execpath ?? "npm";
+    const expectedIntegrities = opts.expectedIntegrities ?? (opts.expectedIntegrity ? { roamcode: opts.expectedIntegrity } : {});
+    const rootIntegrity = expectedIntegrities.roamcode;
+    const paths = managedPaths(opts.installRoot);
+    mkdirSync(paths.releases, { recursive: true, mode: 0o700 });
+    mkdirSync(paths.staging, { recursive: true, mode: 0o700 });
+    const release = join(paths.releases, opts.version);
+    const stage = join(paths.staging, `${opts.version}-${process.pid}-${randomUUID()}`);
+    let logText = "";
+    const log = (line) => {
+        logText += line.endsWith("\n") ? line : `${line}\n`;
+        mkdirSync(opts.dataDir, { recursive: true, mode: 0o700 });
+        writeFileSync(join(opts.dataDir, "update.log"), line.endsWith("\n") ? line : `${line}\n`, { flag: "a" });
+    };
+    const fromVersion = readActiveVersion(opts.installRoot);
+    const status = (state, phase, error) => {
+        opts.onStatus?.({
+            operationId,
+            state,
+            phase,
+            target: opts.version,
+            ...(fromVersion ? { fromVersion } : {}),
+            ...(error ? { error } : {}),
+            log: trimLog(logText),
+            updatedAt: now(),
+        });
+    };
+    const releaseLock = acquireLock(paths.lock, now());
+    let activated = false;
+    try {
+        status("starting", "preparing");
+        const reusableRelease = existsSync(release) &&
+            versionFromReleaseDir(release) === opts.version &&
+            (!rootIntegrity || integrityFromReleaseDir(release) === rootIntegrity);
+        if (!reusableRelease) {
+            if (Object.keys(expectedIntegrities).length > 0) {
+                status("downloading", "checking package integrity");
+                for (const [packageName, expected] of Object.entries(expectedIntegrities)) {
+                    const actual = await npmIntegrity(npmCommand, packageName, opts.version, nodePath, log);
+                    if (actual !== expected)
+                        throw new Error(`GitHub release and npm integrity do not match for ${packageName}`);
+                }
+            }
+            status("installing", "installing package");
+            mkdirSync(stage, { recursive: true, mode: 0o700 });
+            const invocation = npmInvocation(npmCommand, [
+                "install",
+                "--prefix",
+                stage,
+                "--omit=dev",
+                "--no-audit",
+                "--no-fund",
+                "--package-lock=false",
+                `roamcode@${opts.version}`,
+            ], nodePath);
+            await runLogged(invocation.command, invocation.args, { log });
+            const installed = versionFromReleaseDir(stage);
+            if (installed !== opts.version)
+                throw new Error(`installed roamcode ${installed ?? "unknown"}, expected ${opts.version}`);
+            const serverEntry = join(stage, "node_modules", "@roamcode.ai", "server", "dist", "start.js");
+            if (!existsSync(serverEntry))
+                throw new Error("published package is missing @roamcode.ai/server/dist/start.js");
+            status("verifying", "boot smoke");
+            await smokeServer(serverEntry, opts.dataDir, nodePath, log);
+            atomicWrite(join(stage, "release.json"), JSON.stringify({
+                version: opts.version,
+                installedAt: now(),
+                package: `roamcode@${opts.version}`,
+                ...(rootIntegrity ? { integrity: rootIntegrity } : {}),
+            }, null, 2) + "\n");
+            if (existsSync(release))
+                rmSync(release, { recursive: true, force: true });
+            renameSync(stage, release);
+        }
+        else {
+            const serverEntry = join(release, "node_modules", "@roamcode.ai", "server", "dist", "start.js");
+            if (!existsSync(serverEntry))
+                throw new Error(`managed release ${opts.version} is incomplete`);
+            status("verifying", "verifying installed release");
+            await smokeServer(serverEntry, opts.dataDir, nodePath, log);
+        }
+        status("activating", "activating release");
+        let oldTarget;
+        try {
+            oldTarget = realpathSync(paths.current);
+        }
+        catch {
+            oldTarget = undefined;
+        }
+        if (oldTarget && resolve(oldTarget) !== resolve(release))
+            replaceSymlink(paths.previous, oldTarget);
+        replaceSymlink(paths.current, release);
+        activated = true;
+        const launcherPath = writeManagedLauncher(opts.installRoot, nodePath);
+        const existingService = readServiceRecord(opts.dataDir);
+        const record = existingService
+            ? migrateServiceToLauncher({
+                dataDir: opts.dataDir,
+                installRoot: opts.installRoot,
+                launcherPath,
+                nodePath,
+            })
+            : undefined;
+        if (opts.restart && record) {
+            status("restarting", "restarting service");
+            const restarted = restartService(record);
+            if (!restarted.ok)
+                throw new Error(restarted.error ?? "service restart failed");
+        }
+        status("done", "done");
+        // Keep only the active release and its rollback target. A failed/staged release is cleaned in finally.
+        const keep = new Set([opts.version, fromVersion].filter((value) => !!value));
+        for (const name of readdirSync(paths.releases)) {
+            if (isStableVersion(name) && !keep.has(name))
+                rmSync(join(paths.releases, name), { recursive: true, force: true });
+        }
+        return {
+            version: opts.version,
+            ...(fromVersion ? { previousVersion: fromVersion } : {}),
+            releaseDir: release,
+            launcherPath,
+        };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        log(`FAILED: ${message}`);
+        // If activation happened but restart failed, restore the previous pointer when available.
+        if (activated) {
+            try {
+                const previous = realpathSync(paths.previous);
+                replaceSymlink(paths.current, previous);
+            }
+            catch {
+                // no previous managed release (first migration); the new release already passed boot-smoke
+            }
+        }
+        status("failed", "failed", message);
+        throw error;
+    }
+    finally {
+        rmSync(stage, { recursive: true, force: true });
+        releaseLock();
+    }
+}
+export function writeManagedStatus(dataDir, status) {
+    atomicWrite(join(dataDir, "update-status.json"), JSON.stringify(status, null, 2) + "\n", 0o600);
+}
+export function readManagedStatus(dataDir) {
+    try {
+        const parsed = JSON.parse(readFileSync(join(dataDir, "update-status.json"), "utf8"));
+        return parsed && typeof parsed.operationId === "string" && typeof parsed.state === "string" ? parsed : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/managed-update-helper.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/managed-update-helper.js

@@ -0,0 +1,34 @@
+#!/usr/bin/env node
+import { readFileSync, unlinkSync } from "node:fs";
+import { installManagedRelease, writeManagedStatus } from "./managed-runtime.js";
+async function main() {
+    const configPath = process.argv[2];
+    if (!configPath)
+        throw new Error("managed updater config path is required");
+    const config = JSON.parse(readFileSync(configPath, "utf8"));
+    try {
+        await installManagedRelease({
+            version: config.version,
+            installRoot: config.installRoot,
+            dataDir: config.dataDir,
+            operationId: config.operationId,
+            expectedIntegrity: config.expectedIntegrity,
+            expectedIntegrities: config.expectedIntegrities,
+            nodePath: config.nodePath,
+            restart: config.restart,
+            onStatus: (status) => writeManagedStatus(config.dataDir, status),
+        });
+    }
+    finally {
+        try {
+            unlinkSync(configPath);
+        }
+        catch {
+            // best effort; config contains no secret, but should not accumulate
+        }
+    }
+}
+void main().catch((error) => {
+    process.stderr.write(`roamcode updater failed: ${error instanceof Error ? (error.stack ?? error.message) : String(error)}\n`);
+    process.exitCode = 1;
+});

package/dist/mcp-send.d.ts

@@ -0,0 +1,33 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export interface McpEnv {
+    RC_BASE_URL?: string;
+    RC_SESSION_ID?: string;
+    RC_TOKEN?: string;
+    RC_TOKEN_FILE?: string;
+}
+export interface DeliverArgs {
+    path: string;
+    caption?: string;
+    kind: "image" | "file";
+}
+/**
+ * A minimal MCP tool-result shape (content blocks + optional isError), enough for our two tools. The
+ * index signature keeps it assignable to the SDK's `Result` (`{ [x: string]: unknown }`) tool-callback
+ * return type without casting at the call sites.
+ */
+export interface ToolResult {
+    [key: string]: unknown;
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    isError?: boolean;
+}
+/**
+ * Pure, unit-testable core: POST the attachment to roamcode and map the response to a tool-result.
+ * NEVER throws — a bad path, a down server, or a network error all return an `isError` tool-result so
+ * Claude learns it failed and can tell the user. `fetchImpl` is injectable for tests (defaults to fetch).
+ */
+export declare function deliver(env: McpEnv, args: DeliverArgs, fetchImpl?: typeof fetch): Promise<ToolResult>;
+/** Build the MCP server with the two send tools wired to `deliver`. Reads env lazily per call. */
+export declare function createMcpSendServer(env?: McpEnv): McpServer;

package/dist/mcp-send.js

@@ -0,0 +1,107 @@
+/**
+ * mcp-send — a stdio MCP server that lets Claude proactively SEND a file or image to the user's chat.
+ *
+ * roamcode spawns this as `claude`'s MCP subprocess (via --mcp-config). It exposes two tools
+ * (send_image / send_file); on a call it POSTs the file PATH to roamcode's
+ * `POST /sessions/:id/attach`, which validates the path (fsRoot+realpath) and pushes an `attachment`
+ * frame over the session's WebSocket so the web renders it (image inline, file as a download).
+ *
+ * The connection params arrive via env, with Claude supplying RC_TOKEN directly and Codex supplying a
+ * provider-owned RC_TOKEN_FILE. No ANTHROPIC_API_KEY, no @anthropic-ai dependency — only the MCP SDK + zod.
+ */
+import { lstatSync, readFileSync } from "node:fs";
+import { basename, isAbsolute } from "node:path";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+function readTokenFile(path) {
+    try {
+        if (!isAbsolute(path))
+            return undefined;
+        const info = lstatSync(path);
+        if (!info.isFile() || info.isSymbolicLink() || (info.mode & 0o077) !== 0 || info.size < 1 || info.size > 4096) {
+            return undefined;
+        }
+        if (typeof process.getuid === "function" && info.uid !== process.getuid())
+            return undefined;
+        const token = readFileSync(path, "utf8");
+        return token.length <= 4096 && !/[\p{Cc}\p{Zl}\p{Zp}]/u.test(token) ? token : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function textResult(text, isError = false) {
+    return isError ? { content: [{ type: "text", text }], isError: true } : { content: [{ type: "text", text }] };
+}
+/**
+ * Pure, unit-testable core: POST the attachment to roamcode and map the response to a tool-result.
+ * NEVER throws — a bad path, a down server, or a network error all return an `isError` tool-result so
+ * Claude learns it failed and can tell the user. `fetchImpl` is injectable for tests (defaults to fetch).
+ */
+export async function deliver(env, args, fetchImpl = fetch) {
+    const { RC_BASE_URL, RC_SESSION_ID } = env;
+    const token = env.RC_TOKEN || (env.RC_TOKEN_FILE ? readTokenFile(env.RC_TOKEN_FILE) : undefined);
+    if (!RC_BASE_URL || !RC_SESSION_ID || !token) {
+        return textResult("Attachment delivery is not configured (RC_BASE_URL / RC_SESSION_ID / RC_TOKEN missing).", true);
+    }
+    const url = `${RC_BASE_URL}/sessions/${RC_SESSION_ID}/attach`;
+    let res;
+    try {
+        res = await fetchImpl(url, {
+            method: "POST",
+            headers: { authorization: `Bearer ${token}`, "content-type": "application/json" },
+            body: JSON.stringify({ path: args.path, caption: args.caption, kind: args.kind }),
+        });
+    }
+    catch (err) {
+        return textResult(`Could not reach roamcode to send the file: ${err.message}`, true);
+    }
+    if (!res.ok) {
+        // Surface the server's error body (e.g. "path is outside the allowed root") so Claude can explain it.
+        let detail = `HTTP ${res.status}`;
+        try {
+            const body = (await res.json());
+            if (typeof body.error === "string")
+                detail = body.error;
+        }
+        catch {
+            // non-JSON error body — keep the status code detail
+        }
+        return textResult(`Failed to send ${basename(args.path)}: ${detail}`, true);
+    }
+    return textResult(`Sent ${basename(args.path)} to the user.`);
+}
+const SEND_PARAMS = {
+    path: z.string().describe("Absolute path to the file to send."),
+    caption: z.string().optional().describe("Optional caption shown with the file in the chat."),
+};
+/** Build the MCP server with the two send tools wired to `deliver`. Reads env lazily per call. */
+export function createMcpSendServer(env = process.env) {
+    const server = new McpServer({ name: "roamcode-send", version: "0.0.0" });
+    server.registerTool("send_image", {
+        description: "Send an IMAGE to the user's chat so they can see it inline. Use when the user asks you to " +
+            "show/send an image, or to deliver a generated image. `path` must be an absolute path to the file.",
+        inputSchema: SEND_PARAMS,
+    }, async ({ path, caption }) => deliver(env, { path, caption, kind: "image" }));
+    server.registerTool("send_file", {
+        description: "Send a FILE to the user's chat as a download. Use when the user asks you to send/deliver a " +
+            "file. `path` must be an absolute path.",
+        inputSchema: SEND_PARAMS,
+    }, async ({ path, caption }) => deliver(env, { path, caption, kind: "file" }));
+    return server;
+}
+/** Run the stdio server when executed directly (node dist/mcp-send.js). */
+async function main() {
+    const server = createMcpSendServer();
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+// Only run when invoked as the entry script, not when imported by a test.
+if (process.argv[1] && import.meta.url === new URL(`file://${process.argv[1]}`).href) {
+    main().catch((err) => {
+        // A stdio MCP server must keep stdout clean (it is the JSON-RPC channel) — log to stderr.
+        process.stderr.write(`mcp-send failed to start: ${err.message}\n`);
+        process.exit(1);
+    });
+}

package/dist/origin-check.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Origin / CSWSH (cross-site WebSocket hijacking) guard for the WS upgrade and state-changing HTTP.
+ *
+ * The token is the only auth boundary, and it can leak into a URL (`?token=` connect link, push deep
+ * link, browser history). The WS handshake (and any browser-driven HTTP) carries an `Origin` header the
+ * page CANNOT forge — so a malicious cross-origin page that somehow holds the token still can't make the
+ * BROWSER attach to our WS / drive our API, because the browser stamps its OWN origin on the request and
+ * we reject it. Without this check, a leaked-in-URL token is enough for a foreign page to puppet the host.
+ *
+ * SAFE DEFAULT (must never reject the real app): a request is allowed when
+ *   - the `Origin` header is ABSENT (native/non-browser clients, same-origin navigations + most
+ *     same-origin GETs omit it — the PWA's own fetches are same-origin), OR
+ *   - the Origin's host:port equals the request `Host` (same-origin — the PWA always is), OR
+ *   - the Origin matches the configured public URL (ROAMCODE_PUBLIC_URL), OR
+ *   - the Origin is a loopback/localhost origin (local dev), OR
+ *   - the Origin is in the explicit ROAMCODE_ALLOWED_ORIGINS allow-list.
+ * Only a PRESENT, cross-origin, non-allow-listed Origin is rejected (403).
+ */
+/** Normalize a URL/origin string to a comparable `scheme://host[:port]` origin (lowercased). Returns
+ *  undefined for anything that isn't a parseable absolute URL (so it can never match by accident). */
+export declare function normalizeOrigin(value: string | undefined): string | undefined;
+export interface OriginCheckOptions {
+    /** The configured public-facing origin (from ROAMCODE_PUBLIC_URL). May be a full URL. */
+    publicUrl?: string;
+    /** Extra allow-listed origins (ROAMCODE_ALLOWED_ORIGINS, comma-separated → array). */
+    allowedOrigins?: string[];
+}
+/**
+ * Decide whether a request's Origin is allowed. PURE / I/O-free so it is unit-testable; the transport
+ * preHandler passes `origin` (the header) and `host` (the request Host header).
+ *
+ * @param origin the request's `Origin` header (may be undefined)
+ * @param host   the request's `Host` header (e.g. `remotecode.example.com` or `127.0.0.1:4280`)
+ */
+export declare function isOriginAllowed(origin: string | undefined, host: string | undefined, opts?: OriginCheckOptions): boolean;
+/** Parse a comma-separated ROAMCODE_ALLOWED_ORIGINS value into a trimmed, non-empty list. */
+export declare function parseAllowedOrigins(raw: string | undefined): string[];