serve.mjs

// Phase 12 SERVE: long-lived dev server with watcher + rebuild queue +
// SSE live-reload. See builder/PLAN-12.md for the full spec.
//
// One entry point: runServe(opts). Composes:
//   §A  HTTP server + static file handler
//   §B  HTML inject middleware (SSE client script)
//   §C  SSE endpoint (/_tbdocs/reload)
//   §D  Watcher loop (node:fs/promises watch, recursive)
//   §E  Rebuild queue (single-flight + one-pending-slot, debounced)
//   §F  Lifecycle (SIGINT → close server + abort watcher + drain SSE)

import { createServer } from "node:http";
import { readFile, stat, watch } from "node:fs/promises";
import { existsSync } from "node:fs";
import path from "node:path";
import { isOutputTree } from "../lib/markdown-files.mjs";
import { runBuild, createWorkerPool } from "./tbdocs.mjs";

const MIME = {
  ".html": "text/html; charset=utf-8",
  ".css":  "text/css; charset=utf-8",
  ".js":   "application/javascript; charset=utf-8",
  ".mjs":  "application/javascript; charset=utf-8",
  ".json": "application/json; charset=utf-8",
  ".xml":  "application/xml; charset=utf-8",
  ".svg":  "image/svg+xml; charset=utf-8",
  ".png":  "image/png",
  ".jpg":  "image/jpeg",
  ".jpeg": "image/jpeg",
  ".gif":  "image/gif",
  ".webp": "image/webp",
  ".ico":  "image/x-icon",
  ".txt":  "text/plain; charset=utf-8",
  ".pdf":  "application/pdf",
  ".woff": "font/woff",
  ".woff2":"font/woff2",
  ".ttf":  "font/ttf",
};

function log(req, status, extra) {
  const reason = extra ? ` -- ${extra}` : "";
  process.stderr.write(`${new Date().toISOString()} ${status} ${req.method ?? "?"} ${req.url ?? "?"}${reason}\n`);
}

// §B — HTML inject middleware
const RELOAD_SCRIPT = `<script>(()=>{const es=new EventSource('/_tbdocs/reload');es.addEventListener('reload',()=>location.reload());})();</script>`;

function injectReloadScript(html) {
  const idx = html.lastIndexOf("</body>");
  if (idx === -1) return html;
  return html.slice(0, idx) + RELOAD_SCRIPT + html.slice(idx);
}

// §C — SSE endpoint
const sseClients = new Set();

function sseHandler(req, res) {
  res.statusCode = 200;
  res.setHeader("content-type", "text/event-stream");
  res.setHeader("cache-control", "no-store");
  res.setHeader("connection", "keep-alive");
  res.write(": connected\n\n");
  sseClients.add(res);

  const keepalive = setInterval(() => {
    try { res.write(": keepalive\n\n"); } catch {}
  }, 30000);

  req.on("close", () => {
    clearInterval(keepalive);
    sseClients.delete(res);
  });
}

function notifyReload() {
  for (const res of sseClients) {
    try { res.write("event: reload\ndata: 1\n\n"); } catch {}
  }
}

// §A — Static file handler factory
function createStaticHandler(destRoot) {
  // A folder's URL with its trailing slash, built from the folder rather
  // than from the request, so that it is always a path on this server.
  function folderUrl(dir) {
    const rel = path.relative(destRoot, dir);
    return "/" + (rel ? rel.split(path.sep).map(encodeURIComponent).join("/") + "/" : "");
  }

  // Returns { file }, { redirect } or null. A folder named without its
  // trailing slash redirects to the slash form, as GitHub Pages does:
  // served in place, its page's relative links resolve one level too high.
  async function resolveFile(urlPath) {
    const url = urlPath.split("#")[0];
    const q = url.indexOf("?");
    let p;
    try { p = decodeURIComponent(q < 0 ? url : url.slice(0, q)); }
    catch { return null; }
    if (!p.startsWith("/")) p = "/" + p;

    const target = path.normalize(path.join(destRoot, p));
    if (target !== destRoot && !target.startsWith(destRoot + path.sep)) return null;

    const index = path.join(target, "index.html");
    const candidates = [];
    if (!p.endsWith("/")) candidates.push(target);
    if (!p.endsWith("/") && !path.extname(target)) candidates.push(target + ".html");
    candidates.push(index);

    for (const c of candidates) {
      try {
        const s = await stat(c);
        if (!s.isFile()) continue;
        if (c === index && !p.endsWith("/")) {
          return { redirect: folderUrl(target) + (q < 0 ? "" : url.slice(q)) };
        }
        return { file: c };
      } catch {}
    }
    return null;
  }

  return async (req, res) => {
    try {
      const found = await resolveFile(req.url ?? "/");
      if (!found) {
        res.statusCode = 404;
        res.setHeader("content-type", "text/plain; charset=utf-8");
        res.end("404 Not Found\n");
        log(req, 404);
        return;
      }
      // Nothing is cached, a redirect included: the tree changes under the
      // browser, and a folder page can become a single-file one.
      res.setHeader("cache-control", "no-store, no-cache, must-revalidate, max-age=0");
      if (found.redirect) {
        res.statusCode = 301;
        res.setHeader("location", found.redirect);
        res.end();
        return;
      }
      const { file } = found;
      const ext = path.extname(file).toLowerCase();
      const isHtml = ext === ".html";
      const isBook = path.basename(file).toLowerCase() === "book.html";

      let data = await readFile(file);
      if (isHtml && !isBook) {
        data = injectReloadScript(data.toString("utf8"));
      }

      res.statusCode = 200;
      res.setHeader("content-type", MIME[ext] ?? "application/octet-stream");
      res.end(data);
    } catch (err) {
      res.statusCode = 500;
      res.setHeader("content-type", "text/plain; charset=utf-8");
      res.end("500 Internal Server Error\n");
      log(req, 500, err?.message ?? String(err));
    }
  };
}

// §D — Watcher filtering
// The build's output trees are skipped by the test every tool that walks
// docs/ uses, isOutputTree. This list used to name them one at a time and
// missed the three a build given --dest docs/_site-basepath writes, so such a
// build started a rebuild here. The two names below are not output trees.
const IGNORED_DIRS = ["node_modules", ".git"];
const IGNORED_BASENAME_RE = /^\.|~$|\.tmp$|\.swp$|^4913$/;

function shouldRebuild(filename, srcRoot) {
  if (!filename) return false;
  const segs = filename.split(/[/\\]/);
  if (isOutputTree(segs[0]) || IGNORED_DIRS.includes(segs[0])) return false;
  if (IGNORED_BASENAME_RE.test(segs.at(-1) ?? "")) return false;
  // Graphviz renders <name>.dot → <name>.svg back under srcRoot, beside the
  // source. The .dot is the source of truth; the .svg is the build artifact.
  // Without this filter, each .dot edit fires the watcher twice -- once on
  // the .dot save, once on the .svg write mid-rebuild -- so the user sees a
  // redundant second reload after the first.
  //
  // Keyed on "has a .dot sibling" rather than on a fixed folder, because a
  // diagram may live beside the page that uses it. That is also strictly
  // more accurate than the path test it replaces: a hand-authored .svg in
  // assets/images/dot/ used to be ignored, and no longer is.
  if (srcRoot && (segs.at(-1) ?? "").endsWith(".svg")
      && existsSync(path.join(srcRoot, filename).replace(/\.svg$/, ".dot"))) {
    return false;
  }
  return true;
}

export async function runServe(opts) {
  const srcRoot = path.resolve(process.cwd(), opts.src ?? "docs");
  // Serve writes to a tree disjoint from build.bat's `_site/` so a one-off
  // build.bat run (for the PDF, an offline-mirror check, ...) doesn't clobber
  // the running serve session's output mid-watch. The HTTP server and both
  // runBuild calls below key off this path. The watcher does not: it skips
  // output trees by name (isOutputTree), which covers this path because
  // runBuild refuses a --dest inside docs/ that is not in an output tree
  // directly under it (assertDestinationClearOfSource).
  const destRoot = path.resolve(opts.dest ?? path.join(srcRoot, "_serve"));
  const port = opts.port ?? 4000;

  // Pool persists across rebuilds: skips ~100--200 ms of worker cold boot
  // per rebuild and lets warmInit's survives_reset short-circuit on builds
  // after the first.
  let pool = createWorkerPool();

  // A stalled build means a worker is still inside a handler that never
  // returned. The pool outlives a rebuild here, so that worker stays
  // wedged: it will not pick up the next build's sendInit, and the
  // per-worker tasks (warmInit, renderEnvInit) wait on every lane, so
  // the next rebuild would stall too -- for a reason that has nothing
  // to do with whatever the author just edited. Replace the pool
  // wholesale; it costs one cold boot and is certainly correct,
  // whereas replacing only the wedged lane means identifying it, and
  // the SAB records the lane a task completed on, not the one that
  // claimed it.
  async function replacePool(oldPool) {
    console.error("serve: a worker is wedged; restarting the worker pool.");
    pool = createWorkerPool();
    try { await oldPool.destroy(); } catch {}
  }

  // Initial build
  try {
    await runBuild({ ...opts, dest: destRoot, skipOffline: true, skipPdf: true, pool });
  } catch (err) {
    console.error("serve: initial build failed:", describeBuildError(err));
    await pool.destroy();
    // A --dest the build refuses is a command-line error, as in tbdocs's main().
    process.exit(err?.commandLine ? 4 : 1);
  }

  const staticHandler = createStaticHandler(destRoot);

  const server = createServer(async (req, res) => {
    const url = req.url ?? "/";
    if (url === "/_tbdocs/reload" || url.startsWith("/_tbdocs/reload?")) {
      sseHandler(req, res);
      return;
    }
    await staticHandler(req, res);
  });

  server.on("error", (err) => {
    if (err.code === "EADDRINUSE") {
      console.error(`serve: port ${port} already in use. Pass --port <other> to choose another, or stop the process bound to ${port}.`);
      process.exit(1);
    }
    throw err;
  });

  // §E — Rebuild queue (single-flight + one-pending-slot, debounced)
  let running = false;
  let pending = false;
  let debounceTimer = null;
  const changedFiles = new Set();

  function schedule() {
    clearTimeout(debounceTimer);
    debounceTimer = setTimeout(fire, 300);
  }

  async function fire() {
    if (running) { pending = true; return; }
    running = true;
    const files = [...changedFiles].sort();
    changedFiles.clear();
    console.log(`\nChanged: ${files.join(", ")}`);
    try {
      await runBuild({ ...opts, dest: destRoot, skipOffline: true, skipPdf: true, pool });
      notifyReload();
    } catch (err) {
      console.error("rebuild failed:", describeBuildError(err));
      if (err?.stalled) await replacePool(pool);
    } finally {
      running = false;
      if (pending) { pending = false; schedule(); }
    }
  }

  // §D — Watcher loop
  const ac = new AbortController();
  const watcher = watch(srcRoot, { recursive: true, signal: ac.signal });

  (async () => {
    try {
      for await (const event of watcher) {
        if (!shouldRebuild(event.filename, srcRoot)) continue;
        changedFiles.add(event.filename.replaceAll("\\", "/"));
        schedule();
      }
    } catch (err) {
      if (err.name !== "AbortError") throw err;
    }
  })();

  // §F — Lifecycle (SIGINT)
  process.on("SIGINT", () => {
    console.log("serve: shutting down.");
    ac.abort();
    for (const res of sseClients) {
      try { res.end(); } catch {}
    }
    sseClients.clear();
    pool.destroy();
    server.close(() => process.exit(0));
    setTimeout(() => process.exit(0), 100).unref();
  });

  server.listen(port, () => {
    console.log(`Serving ${destRoot} at http://localhost:${port}/`);
    console.log(`Watching ${srcRoot} for changes.`);
  });
}

// A scheduler abort's own message is only "task <name> failed"; what it
// was actually refusing sits in `cause`. Printing just `err.message` in
// the serve loop therefore turns a build gate's carefully-worded refusal
// -- the publish allowlist naming four stray files, say -- into four
// words that say nothing. Walk the chain.
function describeBuildError(err) {
  const seen = new Set();
  const parts = [];
  for (let e = err; e && !seen.has(e); e = e.cause) {
    seen.add(e);
    if (e.message) parts.push(e.message);
  }
  return parts.join("\n  caused by: ");
}