driggsby 0.1.41 → 0.2.0

package/dist/dev/dev-servers.js

@@ -0,0 +1,274 @@
+// The two local servers behind `driggsby dev`, mirroring production's
+// topology: the host origin (the page a person opens; serves the host page
+// and the CLI's tool-call endpoint) and the app origin (the app's own
+// files, plus the Driggsby SDK at /-/driggsby-sdk.js). Both bind loopback
+// only. The app token never appears here — the broker callback holds it in
+// the CLI process.
+import { createServer } from "node:http";
+import { hostPageHtml, HOST_PAGE_JS } from "./host-page.js";
+import { serveStaticFile } from "./static-files.js";
+import { APP_TOOL_ALLOWLIST } from "./tool-allowlist.js";
+// The one wording for "this call didn't happen" cases the app can't fix by
+// changing its code (overload, network trouble). Tool-specific refusals get
+// their own messages.
+export const GENERIC_TOOL_TROUBLE = "We couldn't run that just now. Try again in a moment.";
+export const TOOL_NOT_ALLOWED_MESSAGE = "That tool isn't available to Driggsby apps. Apps can use read-only tools like get_overview and list_accounts.";
+const MAX_TOOL_CALL_BODY_BYTES = 65_536;
+export async function startDevServers(options) {
+    // Both origins bind and advertise 127.0.0.1: advertising "localhost"
+    // while binding only the IPv4 loopback breaks on machines whose browser
+    // resolves localhost to ::1 first.
+    let appPortForGuard = 0;
+    // Filled in once the host server binds; app responses embed it in their
+    // frame-ancestors policy so only the real host page can frame the app.
+    let hostOriginForFraming = "";
+    const appServer = createServer((request, response) => {
+        void handleAppRequest(options, appPortForGuard, hostOriginForFraming, request, response);
+    });
+    await listenLoopback(appServer, options.appPort);
+    const appPort = boundPort(appServer);
+    appPortForGuard = appPort;
+    const appOrigin = `http://127.0.0.1:${String(appPort)}`;
+    const sseClients = new Set();
+    let hostPort = 0;
+    const hostServer = createServer((request, response) => {
+        void handleHostRequest(options, hostPort, appOrigin, sseClients, request, response);
+    });
+    try {
+        await listenLoopback(hostServer, options.hostPort);
+    }
+    catch (error) {
+        // The app server is already listening; a failed host bind must not
+        // leave it squatting its port while the command reports failure.
+        await closeServer(appServer);
+        throw error;
+    }
+    hostPort = boundPort(hostServer);
+    hostOriginForFraming = `http://127.0.0.1:${String(hostPort)}`;
+    return {
+        hostOrigin: hostOriginForFraming,
+        appOrigin,
+        hostPort,
+        appPort,
+        notifyChange: () => {
+            for (const client of sseClients) {
+                client.write("event: change\ndata: files-changed\n\n");
+            }
+        },
+        close: async () => {
+            for (const client of sseClients) {
+                client.end();
+            }
+            sseClients.clear();
+            await Promise.all([closeServer(hostServer), closeServer(appServer)]);
+        },
+    };
+}
+// ---------------------------------------------------------------------------
+// The app origin: the SDK path, then the project's own files.
+// ---------------------------------------------------------------------------
+async function handleAppRequest(options, appPort, hostOrigin, request, response) {
+    // Only the real host page may frame the app: without this, any other
+    // loopback-served page could embed the app origin, pin itself as the
+    // app's host, and feed it fabricated numbers. Until the host server has
+    // bound (a startup race measured in milliseconds), nothing may frame it.
+    // nosniff keeps the browser honest about the served content types.
+    const appHeaders = {
+        "Content-Security-Policy": `frame-ancestors ${hostOrigin === "" ? "'none'" : hostOrigin};`,
+        "X-Content-Type-Options": "nosniff",
+    };
+    // Same rebinding guard as the host origin: a page on another site that
+    // tricked DNS into pointing here carries its own Host, and fails.
+    if (!hostHeaderIsLocal(request.headers.host, appPort)) {
+        sendText(response, 403, "text/plain; charset=utf-8", "Forbidden.", appHeaders);
+        return;
+    }
+    const path = requestPath(request);
+    if (request.method !== "GET" && request.method !== "HEAD") {
+        sendText(response, 405, "text/plain; charset=utf-8", "Method not allowed.", appHeaders);
+        return;
+    }
+    if (path === "/-/driggsby-sdk.js") {
+        sendText(response, 200, "text/javascript; charset=utf-8", options.sdkBundle, appHeaders);
+        return;
+    }
+    const file = await serveStaticFile(options.serveDirectory, path);
+    if (file === null) {
+        sendText(response, 404, "text/plain; charset=utf-8", "Not found.", appHeaders);
+        return;
+    }
+    response.writeHead(file.status, {
+        "Content-Type": file.contentType,
+        "Cache-Control": "no-store",
+        ...appHeaders,
+    });
+    response.end(file.body);
+}
+// ---------------------------------------------------------------------------
+// The host origin: page, script, change events, tool calls.
+// ---------------------------------------------------------------------------
+async function handleHostRequest(options, hostPort, appOrigin, sseClients, request, response) {
+    // Rebinding guard: every host-origin route answers only when the browser
+    // thinks it is talking to this local origin. A page on some other site
+    // that tricked DNS into pointing here carries its own Host, and fails.
+    if (!hostHeaderIsLocal(request.headers.host, hostPort)) {
+        sendJson(response, 403, { ok: false, error: { message: "Forbidden." } });
+        return;
+    }
+    const path = requestPath(request);
+    if (request.method === "GET" && path === "/") {
+        sendHostPage(response, hostPageHtml(options.slug, appOrigin), appOrigin);
+        return;
+    }
+    if (request.method === "GET" && path === "/host.js") {
+        sendText(response, 200, "text/javascript; charset=utf-8", HOST_PAGE_JS);
+        return;
+    }
+    if (request.method === "GET" && path === "/events") {
+        response.writeHead(200, {
+            "Content-Type": "text/event-stream",
+            "Cache-Control": "no-store",
+            "X-Content-Type-Options": "nosniff",
+            Connection: "keep-alive",
+        });
+        response.write(": connected\n\n");
+        sseClients.add(response);
+        request.on("close", () => {
+            sseClients.delete(response);
+        });
+        return;
+    }
+    if (request.method === "POST" && path === "/tool-calls") {
+        await handleToolCall(options, hostPort, request, response);
+        return;
+    }
+    sendText(response, 404, "text/plain; charset=utf-8", "Not found.");
+    return;
+}
+async function handleToolCall(options, hostPort, request, response) {
+    // Cross-site guard: the browser stamps a page's own origin onto
+    // cross-origin POSTs. Only the host page itself (same-origin fetch: no
+    // Origin header, or the host origin) may run tools.
+    const origin = request.headers.origin;
+    if (origin !== undefined && !originIsLocalHost(origin, hostPort)) {
+        sendJson(response, 403, { ok: false, error: { message: "Forbidden." } });
+        return;
+    }
+    // Defense in depth for callers that carry no Origin at all: a cross-site
+    // "simple" POST (text/plain or form-encoded) never has this content type,
+    // and a cross-origin JSON POST triggers a preflight this server never
+    // grants (no CORS headers, OPTIONS is a 404). The host page always sends
+    // JSON, so nothing legitimate is refused.
+    const contentType = request.headers["content-type"] ?? "";
+    if (!contentType.toLowerCase().startsWith("application/json")) {
+        sendJson(response, 415, { ok: false, error: { message: GENERIC_TOOL_TROUBLE } });
+        return;
+    }
+    const body = await readBody(request, MAX_TOOL_CALL_BODY_BYTES);
+    if (body === null) {
+        sendJson(response, 413, { ok: false, error: { message: GENERIC_TOOL_TROUBLE } });
+        return;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(body);
+    }
+    catch {
+        sendJson(response, 400, { ok: false, error: { message: GENERIC_TOOL_TROUBLE } });
+        return;
+    }
+    const record = typeof parsed === "object" && parsed !== null ? parsed : {};
+    const tool = record.tool;
+    if (typeof tool !== "string" || tool.length === 0 || tool.length > 128) {
+        sendJson(response, 400, { ok: false, error: { message: GENERIC_TOOL_TROUBLE } });
+        return;
+    }
+    if (!APP_TOOL_ALLOWLIST.has(tool)) {
+        sendJson(response, 200, { ok: false, error: { message: TOOL_NOT_ALLOWED_MESSAGE } });
+        return;
+    }
+    const argumentsObject = typeof record.arguments === "object" && record.arguments !== null && !Array.isArray(record.arguments)
+        ? record.arguments
+        : {};
+    const result = await options.runToolCall(tool, argumentsObject);
+    sendJson(response, 200, result);
+}
+// ---------------------------------------------------------------------------
+// Small pieces.
+// ---------------------------------------------------------------------------
+function requestPath(request) {
+    const url = request.url ?? "/";
+    const queryStart = url.indexOf("?");
+    return queryStart === -1 ? url : url.slice(0, queryStart);
+}
+function hostHeaderIsLocal(host, port) {
+    return host === `localhost:${String(port)}` || host === `127.0.0.1:${String(port)}`;
+}
+function originIsLocalHost(origin, port) {
+    return (origin === `http://localhost:${String(port)}` || origin === `http://127.0.0.1:${String(port)}`);
+}
+async function readBody(request, maxBytes) {
+    const chunks = [];
+    let total = 0;
+    for await (const chunk of request) {
+        const buffer = chunk;
+        total += buffer.length;
+        if (total > maxBytes) {
+            return null;
+        }
+        chunks.push(buffer);
+    }
+    return Buffer.concat(chunks).toString("utf8");
+}
+function sendText(response, status, contentType, body, extraHeaders = {}) {
+    // nosniff on every response from either origin: the served content types
+    // are always explicit, so the browser never needs to guess.
+    response.writeHead(status, {
+        "Content-Type": contentType,
+        "Cache-Control": "no-store",
+        "X-Content-Type-Options": "nosniff",
+        ...extraHeaders,
+    });
+    response.end(body);
+}
+function sendJson(response, status, payload) {
+    sendText(response, status, "application/json; charset=utf-8", JSON.stringify(payload));
+}
+function sendHostPage(response, html, appOrigin) {
+    response.writeHead(200, {
+        "Content-Type": "text/html; charset=utf-8",
+        "Cache-Control": "no-store",
+        "X-Content-Type-Options": "nosniff",
+        "Content-Security-Policy": "default-src 'none'; script-src 'self'; style-src 'unsafe-inline'; " +
+            `connect-src 'self'; frame-src ${appOrigin}; frame-ancestors 'none';`,
+    });
+    response.end(html);
+}
+async function listenLoopback(server, port) {
+    await new Promise((resolvePromise, rejectPromise) => {
+        server.once("error", rejectPromise);
+        server.listen(port, "127.0.0.1", () => {
+            server.removeListener("error", rejectPromise);
+            // A server-level error after listening (EMFILE, a connection reset
+            // mid-accept) affects one connection; without a handler it would be
+            // an unhandled 'error' event that crashes the whole dev session.
+            server.on("error", () => undefined);
+            resolvePromise();
+        });
+    });
+}
+function boundPort(server) {
+    const address = server.address();
+    if (address === null || typeof address === "string") {
+        throw new Error("dev server has no bound port");
+    }
+    return address.port;
+}
+async function closeServer(server) {
+    server.closeAllConnections();
+    await new Promise((resolvePromise) => {
+        server.close(() => {
+            resolvePromise();
+        });
+    });
+}

package/dist/dev/host-page.js

@@ -0,0 +1,147 @@
+// The dev host page: what a browser shows at the host origin. It embeds the
+// app from the app origin in a cross-origin iframe and speaks the host side
+// of the frozen driggsby-sdk/1 protocol — exactly the topology the deployed
+// app lives in, so an app that works under `driggsby dev` works identically
+// inside Driggsby. The page carries no token and no data; every tool call
+// goes to the CLI's own /tool-calls endpoint, which holds the token and
+// enforces the allowlist and bounds.
+// The page's script is served as its own file so the page can carry a
+// Content-Security-Policy with no inline scripts.
+//
+// Both interpolations below are HTML-safe by construction, not by escaping:
+// `slug` has passed readProjectConfig's strict slug rules (lowercase
+// alphanumerics and dashes only) before runDev ever calls this, and
+// `appOrigin` is built by startDevServers from a literal plus a bound port
+// number. Anything looser than those two sources must not be passed here.
+export function hostPageHtml(slug, appOrigin) {
+    return `<!doctype html>
+<html lang="en" data-app-origin="${appOrigin}">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>${slug} — driggsby dev</title>
+  <style>
+    * { box-sizing: border-box; }
+    body {
+      margin: 0;
+      display: flex;
+      flex-direction: column;
+      height: 100vh;
+      background: #ffffff;
+      color: #1f2430;
+      font-family: system-ui, -apple-system, "Segoe UI", sans-serif;
+      font-size: 14px;
+    }
+    header {
+      display: flex;
+      align-items: baseline;
+      justify-content: space-between;
+      padding: 10px 16px;
+      border-bottom: 1px solid #e6e8ec;
+    }
+    header .slug { font-weight: 600; }
+    header .mode { color: #6d7280; font-size: 13px; }
+    iframe {
+      flex: 1;
+      width: 100%;
+      border: none;
+    }
+  </style>
+</head>
+<body>
+  <header>
+    <span class="slug">${slug}</span>
+    <span class="mode">driggsby dev — your live data</span>
+  </header>
+  <iframe id="app" src="${appOrigin}/" sandbox="allow-scripts allow-same-origin allow-forms"></iframe>
+  <script type="module" src="/host.js"></script>
+</body>
+</html>
+`;
+}
+// The host-side protocol runtime. Kept dependency-free and template-free so
+// nothing needs escaping: this string is served verbatim as /host.js.
+export const HOST_PAGE_JS = [
+    'const PROTOCOL = "driggsby-sdk/1";',
+    "const APP_ORIGIN = document.documentElement.dataset.appOrigin;",
+    'const frame = document.getElementById("app");',
+    "",
+    "function postToApp(message) {",
+    "  if (frame.contentWindow) {",
+    "    frame.contentWindow.postMessage(message, APP_ORIGIN);",
+    "  }",
+    "}",
+    "",
+    "// Only the embedded app may speak: right window, right origin, our",
+    "// protocol marker.",
+    "function messageFromApp(event) {",
+    "  return (",
+    "    event.origin === APP_ORIGIN &&",
+    "    event.source === frame.contentWindow &&",
+    "    typeof event.data === \"object\" &&",
+    "    event.data !== null &&",
+    "    event.data.protocol === PROTOCOL",
+    "  );",
+    "}",
+    "",
+    "async function runToolCall(id, tool, params) {",
+    "  const body = JSON.stringify({ tool: tool, arguments: params });",
+    "  let payload = null;",
+    "  try {",
+    '    const response = await fetch("/tool-calls", {',
+    '      method: "POST",',
+    '      headers: { "Content-Type": "application/json" },',
+    "      body: body,",
+    "    });",
+    "    payload = await response.json();",
+    "  } catch (error) {",
+    "    payload = null;",
+    "  }",
+    "  if (payload && payload.ok === true) {",
+    '    postToApp({ protocol: PROTOCOL, type: "result", id: id, result: payload.result });',
+    "    return;",
+    "  }",
+    "  const message =",
+    "    payload && payload.error && typeof payload.error.message === \"string\"",
+    "      ? payload.error.message",
+    '      : "We couldn\'t run that just now. Try again in a moment.";',
+    '  postToApp({ protocol: PROTOCOL, type: "result", id: id, error: { message: message } });',
+    "}",
+    "",
+    'window.addEventListener("message", (event) => {',
+    "  if (!messageFromApp(event)) {",
+    "    return;",
+    "  }",
+    "  const data = event.data;",
+    '  if (data.type === "ready") {',
+    '    postToApp({ protocol: PROTOCOL, type: "hello" });',
+    "    return;",
+    "  }",
+    '  if (data.type !== "call") {',
+    "    return;",
+    "  }",
+    "  // Same shape rules as the production host: a bounded string id, a",
+    "  // bounded string tool name, and params degrading to an empty object.",
+    "  const id = data.id;",
+    "  const tool = data.tool;",
+    '  if (typeof id !== "string" || id.length === 0 || id.length > 64) {',
+    "    return;",
+    "  }",
+    '  if (typeof tool !== "string" || tool.length === 0 || tool.length > 128) {',
+    "    return;",
+    "  }",
+    "  const params =",
+    '    typeof data.params === "object" && data.params !== null && !Array.isArray(data.params)',
+    "      ? data.params",
+    "      : {};",
+    "  runToolCall(id, tool, params);",
+    "});",
+    "",
+    "// The CLI announces served-file changes; the app reloads itself on",
+    "// new-version, exactly as it would after a deploy.",
+    'const events = new EventSource("/events");',
+    'events.addEventListener("change", () => {',
+    '  postToApp({ protocol: PROTOCOL, type: "new-version" });',
+    "});",
+    "",
+].join("\n");

package/dist/dev/mcp-broker.js

@@ -0,0 +1,149 @@
+// The tool-call broker: the only place `driggsby dev` talks to Driggsby.
+// It holds the app token in the CLI process (never in page HTML), calls the
+// Driggsby MCP endpoint, and hands the host page a plain
+// { ok, result | error } envelope. Bounds mirror the production host: a few
+// calls in flight, a bounded queue, and a hard per-call timeout, so a
+// buggy app can hammer its own laptop but never Driggsby.
+import { GENERIC_TOOL_TROUBLE } from "./dev-servers.js";
+export const MAX_IN_FLIGHT_CALLS = 4;
+export const MAX_QUEUED_CALLS = 64;
+export const TOOL_CALL_TIMEOUT_MS = 30_000;
+// Server-supplied error text is untrusted; it reaches the page's console,
+// so it gets a hard length cap like every other untrusted string we relay.
+export const MAX_ERROR_MESSAGE_CHARS = 500;
+export const SIGN_IN_AGAIN_MESSAGE = "Your sign-in on this machine isn't valid anymore. In this app's folder, run: npx driggsby@latest login — then reload this page.";
+// Sent when an app doesn't provide its own reason. The Driggsby MCP
+// endpoint requires a short reason on most read tools; a locally previewed
+// dashboard has exactly one.
+const DEFAULT_REASON = "Rendering this data in the developer's own Driggsby app preview.";
+// One broker per `driggsby dev` run. runToolCall never rejects — every
+// failure becomes an { ok: false } envelope with a person-readable message.
+export class McpBroker {
+    options;
+    queue = [];
+    inFlight = 0;
+    nextRequestId = 1;
+    constructor(options) {
+        this.options = options;
+    }
+    async runToolCall(tool, argumentsObject) {
+        if (this.queue.length >= MAX_QUEUED_CALLS) {
+            return { ok: false, error: { message: GENERIC_TOOL_TROUBLE } };
+        }
+        return await new Promise((resolve) => {
+            this.queue.push({ tool, argumentsObject, resolve });
+            this.pump();
+        });
+    }
+    pump() {
+        while (this.inFlight < MAX_IN_FLIGHT_CALLS) {
+            const call = this.queue.shift();
+            if (call === undefined) {
+                return;
+            }
+            this.inFlight += 1;
+            void this.execute(call).finally(() => {
+                this.inFlight -= 1;
+                this.pump();
+            });
+        }
+    }
+    async execute(call) {
+        let result;
+        try {
+            result = await this.callMcp(call.tool, call.argumentsObject);
+        }
+        catch {
+            result = { ok: false, error: { message: GENERIC_TOOL_TROUBLE } };
+        }
+        call.resolve(result);
+    }
+    async callMcp(tool, argumentsObject) {
+        const toolArguments = { ...argumentsObject };
+        if (typeof toolArguments.reason !== "string" || toolArguments.reason.trim() === "") {
+            toolArguments.reason = DEFAULT_REASON;
+        }
+        const requestId = this.nextRequestId;
+        this.nextRequestId += 1;
+        const doFetch = this.options.fetchImplementation ?? fetch;
+        // Bare headers on purpose: the Driggsby endpoint refuses anything that
+        // looks like a browser call (an Origin or Sec-Fetch-Site header), and
+        // Node's fetch sends neither on its own.
+        const response = await doFetch(new URL("/mcp", this.options.baseUrl), {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                Authorization: `Bearer ${this.options.token}`,
+            },
+            body: JSON.stringify({
+                jsonrpc: "2.0",
+                id: requestId,
+                method: "tools/call",
+                params: { name: tool, arguments: toolArguments },
+            }),
+            // The bearer token must never travel to a redirect target, and tool
+            // results must never come from one either.
+            redirect: "error",
+            signal: AbortSignal.timeout(this.options.timeoutMs ?? TOOL_CALL_TIMEOUT_MS),
+        });
+        if (response.status === 401) {
+            return { ok: false, error: { message: SIGN_IN_AGAIN_MESSAGE } };
+        }
+        if (!response.ok) {
+            return { ok: false, error: { message: GENERIC_TOOL_TROUBLE } };
+        }
+        let payload;
+        try {
+            payload = await response.json();
+        }
+        catch {
+            return { ok: false, error: { message: GENERIC_TOOL_TROUBLE } };
+        }
+        return interpretJsonRpc(payload);
+    }
+}
+// The Driggsby MCP endpoint answers in JSON-RPC 2.0. Three shapes matter:
+// a protocol-level error ({ error: { message } }), a tool-level refusal
+// (result.isError true, message in content[0].text), and success
+// (result.structuredContent is the data the app's watch callback gets).
+function interpretJsonRpc(payload) {
+    if (typeof payload !== "object" || payload === null) {
+        return { ok: false, error: { message: GENERIC_TOOL_TROUBLE } };
+    }
+    const envelope = payload;
+    const error = envelope.error;
+    if (typeof error === "object" && error !== null) {
+        const message = error.message;
+        return {
+            ok: false,
+            error: { message: typeof message === "string" ? capMessage(message) : GENERIC_TOOL_TROUBLE },
+        };
+    }
+    const result = envelope.result;
+    if (typeof result !== "object" || result === null) {
+        return { ok: false, error: { message: GENERIC_TOOL_TROUBLE } };
+    }
+    const resultRecord = result;
+    if (resultRecord.isError === true) {
+        return { ok: false, error: { message: toolRefusalMessage(resultRecord) } };
+    }
+    return { ok: true, result: resultRecord.structuredContent ?? null };
+}
+function toolRefusalMessage(resultRecord) {
+    const content = resultRecord.content;
+    if (Array.isArray(content)) {
+        const first = content[0];
+        if (typeof first === "object" && first !== null) {
+            const text = first.text;
+            if (typeof text === "string" && text.trim() !== "") {
+                return capMessage(text);
+            }
+        }
+    }
+    return GENERIC_TOOL_TROUBLE;
+}
+function capMessage(message) {
+    return message.length > MAX_ERROR_MESSAGE_CHARS
+        ? `${message.slice(0, MAX_ERROR_MESSAGE_CHARS)}…`
+        : message;
+}

package/dist/dev/static-files.js

@@ -0,0 +1,104 @@
+// The static file half of the local app origin: what `driggsby dev` serves
+// from the project's serve folder. It serves what a deploy would publish —
+// dotfiles at any depth, the top-level driggsby.json, node_modules, and
+// symlinks are never served, just as the deploy walk never uploads them —
+// so the local preview and the deployed app agree on what exists. The
+// exclusions here match case-insensitively (stricter than the deploy walk):
+// most local filesystems are case-insensitive, so /DRIGGSBY.JSON must not
+// reach the file the exact-case check would have refused.
+import { lstat, readFile, realpath } from "node:fs/promises";
+import { extname, join, normalize, relative, isAbsolute, sep } from "node:path";
+const CONTENT_TYPES = {
+    ".avif": "image/avif",
+    ".css": "text/css; charset=utf-8",
+    ".gif": "image/gif",
+    ".html": "text/html; charset=utf-8",
+    ".ico": "image/x-icon",
+    ".jpeg": "image/jpeg",
+    ".jpg": "image/jpeg",
+    ".js": "text/javascript; charset=utf-8",
+    ".json": "application/json; charset=utf-8",
+    ".map": "application/json; charset=utf-8",
+    ".mjs": "text/javascript; charset=utf-8",
+    ".png": "image/png",
+    ".svg": "image/svg+xml; charset=utf-8",
+    ".txt": "text/plain; charset=utf-8",
+    ".webp": "image/webp",
+    ".woff": "font/woff",
+    ".woff2": "font/woff2",
+};
+// Resolves a request path to a file under the serve folder, or null when the
+// path is outside what dev serves (bad encoding, traversal, an excluded
+// file, a symlink, or a missing file). "/" serves index.html, like the
+// deployed app.
+export async function serveStaticFile(serveDirectory, rawPath) {
+    const relativePath = safeRelativePath(rawPath);
+    if (relativePath === null) {
+        return null;
+    }
+    const filePath = join(serveDirectory, relativePath);
+    if (!(await isRegularFileInside(serveDirectory, filePath))) {
+        return null;
+    }
+    let body;
+    try {
+        body = await readFile(filePath);
+    }
+    catch {
+        return null;
+    }
+    const contentType = CONTENT_TYPES[extname(relativePath).toLowerCase()] ?? "application/octet-stream";
+    return { status: 200, contentType, body };
+}
+// Request path -> a safe relative file path, or null. Everything that could
+// step outside the serve folder or reach an unpublished file fails closed.
+// The exclusions mirror the deploy walk: dotfiles and node_modules at any
+// depth, driggsby.json only at the top level (a nested one is an ordinary
+// file there too) — refused in any casing, per the header note.
+function safeRelativePath(rawPath) {
+    let decoded;
+    try {
+        decoded = decodeURIComponent(rawPath);
+    }
+    catch {
+        return null;
+    }
+    if (decoded.includes("\0")) {
+        return null;
+    }
+    const withoutLeadingSlash = decoded.replace(/^\/+/, "");
+    const relativePath = withoutLeadingSlash === "" ? "index.html" : withoutLeadingSlash;
+    const normalized = normalize(relativePath);
+    if (normalized.startsWith("..") || isAbsolute(normalized) || /^[A-Za-z]:/.test(normalized)) {
+        return null;
+    }
+    const segments = normalized.split(sep);
+    for (const segment of segments) {
+        const lowered = segment.toLowerCase();
+        if (segment === "" || lowered === ".." || lowered === "node_modules" || segment.startsWith(".")) {
+            return null;
+        }
+    }
+    if (normalized.toLowerCase() === "driggsby.json") {
+        return null;
+    }
+    return normalized;
+}
+// The deploy walk skips symlinks, so dev refuses them too — locally that
+// also stops a link from serving files outside the project. The realpath
+// containment check backs the segment checks with the filesystem's own view.
+async function isRegularFileInside(serveDirectory, filePath) {
+    try {
+        const stats = await lstat(filePath);
+        if (!stats.isFile()) {
+            return false;
+        }
+        const realRoot = await realpath(serveDirectory);
+        const realFile = await realpath(filePath);
+        const relativePath = relative(realRoot, realFile);
+        return relativePath !== "" && !relativePath.startsWith("..") && !isAbsolute(relativePath);
+    }
+    catch {
+        return false;
+    }
+}