Function serve

design/src/serve.ts:55–239

(options: ServeOptions)

type ServerState = "serving" | "regenerating" | "done";

export async function serve(options: ServeOptions): Promise<void> {
  const { html, port = 0, hostname = "127.0.0.1", timeout = 600 } = options;

  // Validate HTML file exists
  if (!fs.existsSync(html)) {
    console.error(`SERVE_ERROR: HTML file not found: ${html}`);
    process.exit(1);
  }

  // Security: anchor all file reads to the initial HTML's directory.
  // Prevents /api/reload from reading arbitrary files via path traversal.
  const allowedDir = fs.realpathSync(path.dirname(path.resolve(html)));

  let htmlContent = fs.readFileSync(html, "utf-8");
  let state: ServerState = "serving";
  let timeoutTimer: ReturnType<typeof setTimeout> | null = null;

  const server = Bun.serve({
    port,
    hostname,
    fetch(req) {
      const url = new URL(req.url);

      // Serve the comparison board HTML. The board JS uses relative paths
      // (./api/feedback, ./api/progress) and a location.protocol
      // feature-detect, so no per-request injection is needed.
      if (
        req.method === "GET" &&
        (url.pathname === "/" || url.pathname === "/index.html")
      ) {
        return new Response(htmlContent, {
          headers: { "Content-Type": "text/html; charset=utf-8" },
        });
      }

      // Progress polling endpoint (used by board during regeneration)
      if (req.method === "GET" && url.pathname === "/api/progress") {
        return Response.json({ status: state });
      }

      // Feedback submission from the board
      if (req.method === "POST" && url.pathname === "/api/feedback") {
        return handleFeedback(req);
      }

      // Reload endpoint (used by the agent to swap in new board HTML)
      if (req.method === "POST" && url.pathname === "/api/reload") {
        return handleReload(req);
      }

      return new Response("Not found", { status: 404 });
    },
  });

  const actualPort = server.port;
  const boardUrl = `http://127.0.0.1:${actualPort}`;

  console.error(`SERVE_STARTED: port=${actualPort} html=${html}`);