srvmd 0.1.0

package/src/server/routes/index.ts

@@ -0,0 +1,91 @@
+import type { Server } from "bun";
+import { API_PAGE_PATH, APP_ASSET_PREFIX, LIVE_PATH, MERMAID_RUNTIME_PATH } from "../../shared/constants.ts";
+import { respondMermaidRuntime } from "../assets/mermaid.ts";
+import { respondWebAsset } from "../assets/web.ts";
+import { MAX_HTML_INJECTION_BYTES } from "../constants.ts";
+import type { ServerContext } from "../context.ts";
+import {
+  fileResponse,
+  htmlResponse,
+  methodNotAllowedResponse,
+  preflightResponse,
+  redirectResponse,
+  textResponse,
+} from "../http/respond.ts";
+import { resolveResource } from "../resolve/resource.ts";
+import { injectLiveReload } from "../services/live/index.ts";
+import { respondPageApi } from "./page-api.ts";
+import { respondShell } from "./shell.ts";
+
+export type RequestHandler = (request: Request, server: Server<undefined>) => Promise<Response | undefined>;
+
+/** Convert `/__api/page/<path>` back into the user-facing URL it describes. */
+function pageUrlFromApi(url: URL): URL {
+  const pageUrl = new URL(url);
+  const suffix = url.pathname.slice(API_PAGE_PATH.length);
+  pageUrl.pathname = suffix === "" ? "/" : suffix;
+  pageUrl.search = "";
+  return pageUrl;
+}
+
+/**
+ * HTTP entry point:
+ * live socket -> CORS preflight -> method guard -> internal routes -> resolve.
+ */
+export function createRequestHandler(context: ServerContext): RequestHandler {
+  return async (request, server) => {
+    const url = new URL(request.url);
+
+    if (url.pathname === LIVE_PATH) {
+      if (!context.live?.upgrade(request, server)) {
+        return new Response("WebSocket upgrade required", { status: 426 });
+      }
+      return undefined;
+    }
+
+    const method = request.method.toUpperCase();
+    if (context.config.cors && method === "OPTIONS") return preflightResponse(true);
+    if (method !== "GET" && method !== "HEAD") return methodNotAllowedResponse(context.config.cors);
+
+    if (url.pathname === MERMAID_RUNTIME_PATH && context.config.mermaid) {
+      return respondMermaidRuntime(request, context.config.cors);
+    }
+
+    if (url.pathname === APP_ASSET_PREFIX || url.pathname.startsWith(`${APP_ASSET_PREFIX}/`)) {
+      return respondWebAsset(context.config.webRoot, url, request, context.config.cors);
+    }
+
+    if (url.pathname === API_PAGE_PATH || url.pathname.startsWith(`${API_PAGE_PATH}/`)) {
+      const pageUrl = pageUrlFromApi(url);
+      const resource = await resolveResource(context.config, pageUrl);
+      return respondPageApi(context, resource, request, pageUrl);
+    }
+
+    const resource = await resolveResource(context.config, url);
+
+    if (resource.kind === "markdown" && url.searchParams.has("raw")) {
+      return fileResponse(resource.file, request, context.config.cors, "text/markdown; charset=utf-8");
+    }
+
+    switch (resource.kind) {
+      case "markdown":
+      case "directory":
+        return respondShell(context.config, 200, request);
+      case "html": {
+        if (!context.config.live || resource.file.stats.size > MAX_HTML_INJECTION_BYTES) {
+          return fileResponse(resource.file, request, context.config.cors);
+        }
+        const source = await Bun.file(resource.file.path).text();
+        return htmlResponse(injectLiveReload(source), 200, request.method, context.config.cors);
+      }
+      case "file":
+        return fileResponse(resource.file, request, context.config.cors);
+      case "redirect":
+        return redirectResponse(resource.location, request.method, context.config.cors);
+      case "error":
+        return respondShell(context.config, resource.status, request);
+      default:
+        return textResponse("Unhandled resource", 500, request.method, context.config.cors);
+    }
+  };
+}

package/src/server/routes/page-api.ts

@@ -0,0 +1,88 @@
+import { basename } from "node:path";
+import { buildBreadcrumbs } from "../../shared/breadcrumbs.ts";
+import type { DirectoryPayload, DocumentPayload, RedirectPayload } from "../../shared/contracts.ts";
+import type { ServerContext } from "../context.ts";
+import { stripMarkdownExtension } from "../file-kinds.ts";
+import { jsonError, jsonResponse } from "../http/respond.ts";
+import type { RenderedDocument } from "../markdown/index.ts";
+import type { Resource } from "../resolve/resource.ts";
+import { listDirectory } from "../services/directories.ts";
+import type { DirectoryEntry, ResolvedPath } from "../types.ts";
+
+function documentPayload(
+  context: ServerContext,
+  file: ResolvedPath,
+  document: RenderedDocument,
+  url: URL,
+): DocumentPayload {
+  const directory = file.relative.includes("/") ? file.relative.slice(0, file.relative.lastIndexOf("/")) : "";
+  const lang = document.frontmatter.lang;
+
+  return {
+    kind: "document",
+    path: url.pathname,
+    title: document.title ?? stripMarkdownExtension(basename(file.path)),
+    html: document.html,
+    toc: document.toc,
+    mermaid: document.mermaid,
+    breadcrumbs: buildBreadcrumbs(context.config.rootLabel, directory),
+    rawHref: `${url.pathname}?raw`,
+    warning: document.warning,
+    lang: typeof lang === "string" ? lang : undefined,
+  };
+}
+
+function directoryPayload(
+  context: ServerContext,
+  directory: ResolvedPath,
+  entries: DirectoryEntry[],
+): DirectoryPayload {
+  const displayPath = directory.relative ? `/${directory.relative}/` : "/";
+
+  return {
+    kind: "directory",
+    path: displayPath,
+    heading: `Index of ${displayPath}`,
+    parentHref: directory.relative ? "../" : undefined,
+    entries: entries.map(entry => ({
+      name: entry.name,
+      kind: entry.kind,
+      size: entry.size,
+      mtime: entry.mtime?.toISOString(),
+    })),
+    breadcrumbs: buildBreadcrumbs(context.config.rootLabel, directory.relative),
+  };
+}
+
+/** Turn the resolver's Resource into the JSON contract consumed by the Svelte app. */
+export async function respondPageApi(
+  context: ServerContext,
+  resource: Resource,
+  request: Request,
+  url: URL,
+): Promise<Response> {
+  const { config } = context;
+  const method = request.method.toUpperCase();
+
+  switch (resource.kind) {
+    case "markdown": {
+      const document = await context.documents.get(resource.file.path);
+      return jsonResponse(documentPayload(context, resource.file, document, url), 200, method, config.cors);
+    }
+    case "directory": {
+      const entries = await listDirectory(resource.directory.path, config.root);
+      return jsonResponse(directoryPayload(context, resource.directory, entries), 200, method, config.cors);
+    }
+    case "redirect": {
+      const payload: RedirectPayload = { kind: "redirect", location: resource.location };
+      return jsonResponse(payload, 200, method, config.cors);
+    }
+    case "error":
+      return jsonError(resource.status, resource.reason, method, config.cors);
+    case "html":
+    case "file":
+      return jsonError(404, "Not a page", method, config.cors);
+    default:
+      return jsonError(500, "Unhandled resource", method, config.cors);
+  }
+}

package/src/server/routes/shell.ts

@@ -0,0 +1,50 @@
+import { join } from "node:path";
+import { CONFIG_TOKEN } from "../../shared/constants.ts";
+import type { AppConfig } from "../../shared/contracts.ts";
+import type { ResolvedConfig } from "../config.ts";
+import { htmlResponse, textResponse } from "../http/respond.ts";
+
+function escapeForScript(json: string): string {
+  return json
+    .replace(/</g, "\\u003c")
+    .replace(/>/g, "\\u003e")
+    .replace(/&/g, "\\u0026")
+    .replace(/\u2028/g, "\\u2028")
+    .replace(/\u2029/g, "\\u2029");
+}
+
+export function appConfig(config: ResolvedConfig): AppConfig {
+  return {
+    rootLabel: config.rootLabel,
+    version: config.version,
+    theme: config.theme,
+    live: config.live,
+    mermaid: config.mermaid,
+  };
+}
+
+async function readShell(webRoot: string): Promise<string | null> {
+  const file = Bun.file(join(webRoot, "index.html"));
+  if (!(await file.exists())) return null;
+  return file.text();
+}
+
+/**
+ * Serve the Svelte shell for an app route. The only server-injected value is a
+ * JSON config object; all page structure and content rendering lives in the
+ * web app.
+ */
+export async function respondShell(config: ResolvedConfig, status: number, request: Request): Promise<Response> {
+  const template = await readShell(config.webRoot);
+  if (!template) {
+    return textResponse(
+      `srvmd: web build not found at ${join(config.webRoot, "index.html")}.\nRun \`bun run build\` first.`,
+      503,
+      request.method,
+      config.cors,
+    );
+  }
+
+  const json = escapeForScript(JSON.stringify(appConfig(config)));
+  return htmlResponse(template.split(CONFIG_TOKEN).join(json), status, request.method, config.cors);
+}

package/src/server/services/directories.ts

@@ -0,0 +1,41 @@
+import { readdir, realpath, stat } from "node:fs/promises";
+import { join } from "node:path";
+import { IGNORED_NAMES } from "../constants.ts";
+import { isMarkdownFile } from "../file-kinds.ts";
+import { isInside } from "../path.ts";
+import type { DirectoryEntry } from "../types.ts";
+
+/** Read a directory and return a sorted, filtered listing. */
+export async function listDirectory(dir: string, root: string): Promise<DirectoryEntry[]> {
+  const dirents = await readdir(dir, { withFileTypes: true }).catch(() => []);
+  const entries: DirectoryEntry[] = [];
+
+  await Promise.all(
+    dirents.map(async dirent => {
+      if (dirent.name.startsWith(".") || IGNORED_NAMES.has(dirent.name)) return;
+
+      const full = join(dir, dirent.name);
+      const stats = await stat(full).catch(() => null);
+      if (!stats) return;
+
+      if (dirent.isSymbolicLink()) {
+        const real = await realpath(full).catch(() => null);
+        if (!real || !isInside(root, real)) return;
+      }
+
+      entries.push({
+        name: dirent.name,
+        kind: stats.isDirectory() ? "dir" : isMarkdownFile(dirent.name) ? "markdown" : "file",
+        size: stats.isDirectory() ? undefined : stats.size,
+        mtime: stats.mtime,
+      });
+    }),
+  );
+
+  entries.sort((a, b) => {
+    if ((a.kind === "dir") !== (b.kind === "dir")) return a.kind === "dir" ? -1 : 1;
+    return a.name.localeCompare(b.name, undefined, { numeric: true, sensitivity: "base" });
+  });
+
+  return entries;
+}

package/src/server/services/documents.ts

@@ -0,0 +1,43 @@
+import { stat } from "node:fs/promises";
+import { MAX_CACHED_DOCUMENTS } from "../constants.ts";
+import type { RenderedDocument, Renderer } from "../markdown/render.ts";
+
+type CachedDocument = {
+  mtimeMs: number;
+  size: number;
+  document: RenderedDocument;
+};
+
+export type DocumentStore = {
+  get(path: string): Promise<RenderedDocument>;
+  clear(): void;
+};
+
+/** Read + render Markdown, cached by (mtime, size) and invalidated by the watcher. */
+export function createDocumentStore(renderer: Renderer): DocumentStore {
+  const cache = new Map<string, CachedDocument>();
+
+  return {
+    async get(path) {
+      const info = await stat(path);
+      const cached = cache.get(path);
+      if (cached && cached.mtimeMs === info.mtimeMs && cached.size === info.size) {
+        return cached.document;
+      }
+
+      const source = await Bun.file(path).text();
+      const document = await renderer.render(source);
+      cache.set(path, { mtimeMs: info.mtimeMs, size: info.size, document });
+
+      if (cache.size > MAX_CACHED_DOCUMENTS) {
+        const oldest = cache.keys().next().value;
+        if (oldest) cache.delete(oldest);
+      }
+
+      return document;
+    },
+    clear() {
+      cache.clear();
+    },
+  };
+}

package/src/server/services/live/client-script.ts

@@ -0,0 +1,12 @@
+import { APP_ASSET_PREFIX } from "../../../shared/constants.ts";
+
+/** Prebuilt static-page live-reload module, emitted by the Vite build. */
+export const LIVE_CLIENT_SCRIPT_PATH = `${APP_ASSET_PREFIX}/live-static.js`;
+
+/** Append the live-reload module to a static HTML document. */
+export function injectLiveReload(html: string): string {
+  const snippet = `<script type="module" src="${LIVE_CLIENT_SCRIPT_PATH}"></script>`;
+  const match = /<\/body\s*>/i.exec(html);
+  if (!match || match.index === undefined) return html + snippet;
+  return html.slice(0, match.index) + snippet + html.slice(match.index);
+}

package/src/server/services/live/hub.ts

@@ -0,0 +1,50 @@
+import type { Server, ServerWebSocket } from "bun";
+
+type Socket = ServerWebSocket<undefined>;
+
+export type LiveHub = {
+  upgrade(request: Request, server: Server<undefined>): boolean;
+  open(socket: Socket): void;
+  close(socket: Socket): void;
+  message(socket: Socket, message: string | Buffer): void;
+  broadcast(files: string[]): void;
+  closeAll(): void;
+};
+
+/** Tracks connected browsers and pushes reload events. */
+export function createLiveHub(): LiveHub {
+  const sockets = new Set<Socket>();
+
+  return {
+    upgrade(request, server) {
+      return server.upgrade(request);
+    },
+    open(socket) {
+      sockets.add(socket);
+    },
+    close(socket) {
+      sockets.delete(socket);
+    },
+    message() {
+      // Clients are read-only; ignore inbound messages.
+    },
+    broadcast(files) {
+      const payload = JSON.stringify({ type: "reload", files });
+      for (const socket of sockets) {
+        try {
+          socket.send(payload);
+        } catch {
+          sockets.delete(socket);
+        }
+      }
+    },
+    closeAll() {
+      for (const socket of sockets) {
+        try {
+          socket.close(1001, "Server shutting down");
+        } catch {}
+      }
+      sockets.clear();
+    },
+  };
+}

package/src/server/services/live/index.ts

@@ -0,0 +1,33 @@
+import { createLiveHub, type LiveHub } from "./hub.ts";
+import { createWatcher } from "./watcher.ts";
+
+export type LiveReload = LiveHub;
+
+export type LiveReloadOptions = {
+  root: string;
+  ignore?: string[];
+  onChange?: (files: string[]) => void;
+};
+
+/** Compose the filesystem watcher with the WebSocket hub. */
+export async function createLiveReload(options: LiveReloadOptions): Promise<LiveReload> {
+  const hub = createLiveHub();
+  const watcher = await createWatcher({
+    root: options.root,
+    ignore: options.ignore,
+    onChange(files) {
+      options.onChange?.(files);
+      hub.broadcast(files);
+    },
+  });
+
+  return {
+    ...hub,
+    closeAll() {
+      watcher.close();
+      hub.closeAll();
+    },
+  };
+}
+
+export { injectLiveReload, LIVE_CLIENT_SCRIPT_PATH } from "./client-script.ts";

package/src/server/services/live/watcher.ts

@@ -0,0 +1,126 @@
+import { type Dirent, type FSWatcher, watch } from "node:fs";
+import { readdir } from "node:fs/promises";
+import { dirname, join, sep } from "node:path";
+import { IGNORED_NAMES, WATCH_DEBOUNCE_MS, WATCHED_EXTENSIONS } from "../../constants.ts";
+
+export type Watcher = {
+  close(): void;
+};
+
+export type WatcherOptions = {
+  root: string;
+  ignore?: string[];
+  onChange: (files: string[]) => void;
+};
+
+/**
+ * Watch every non-ignored directory under root (one inotify watcher per
+ * directory) and report debounced file changes.
+ *
+ * Watching directories individually avoids putting recursive watchers on
+ * node_modules/.git, which is expensive and can hit inotify limits.
+ */
+export async function createWatcher(options: WatcherOptions): Promise<Watcher> {
+  const ignored = new Set([...IGNORED_NAMES, ...(options.ignore ?? [])]);
+  const watchers = new Map<string, FSWatcher>();
+  const pending = new Set<string>();
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  let closed = false;
+
+  const shouldIgnore = (name: string) => name.startsWith(".") || ignored.has(name);
+
+  function flush(): void {
+    timer = undefined;
+    if (pending.size === 0) return;
+    const files = [...pending];
+    pending.clear();
+    options.onChange(files);
+  }
+
+  function schedule(): void {
+    if (timer) clearTimeout(timer);
+    timer = setTimeout(flush, WATCH_DEBOUNCE_MS);
+  }
+
+  async function addDirectory(directory: string): Promise<void> {
+    if (closed || watchers.has(directory)) return;
+    let dirents: Dirent[];
+    try {
+      dirents = await readdir(directory, { withFileTypes: true });
+    } catch {
+      return;
+    }
+
+    try {
+      const watcher = watch(directory, (event, filename) => {
+        if (closed) return;
+        const name = filename?.toString();
+        if (event === "rename") void reconcile(directory);
+        if (!name || shouldIgnore(name) || !WATCHED_EXTENSIONS.test(name)) return;
+        pending.add(join(directory, name));
+        schedule();
+      });
+      watcher.on("error", () => {
+        watcher.close();
+        watchers.delete(directory);
+      });
+      watchers.set(directory, watcher);
+    } catch {
+      return;
+    }
+
+    for (const dirent of dirents) {
+      if (dirent.isDirectory() && !shouldIgnore(dirent.name)) {
+        await addDirectory(join(directory, dirent.name));
+      }
+    }
+  }
+
+  function removeWatcherTree(target: string): void {
+    for (const [watched, watcher] of [...watchers]) {
+      if (watched === target || watched.startsWith(target + sep)) {
+        watcher.close();
+        watchers.delete(watched);
+      }
+    }
+  }
+
+  /** Add watchers for newly-created dirs and drop watchers for deleted ones. */
+  async function reconcile(directory: string): Promise<void> {
+    if (closed) return;
+    const dirents = await readdir(directory, { withFileTypes: true }).catch(() => null);
+    if (!dirents) {
+      removeWatcherTree(directory);
+      return;
+    }
+
+    const childDirs = new Set(
+      dirents
+        .filter(dirent => dirent.isDirectory() && !shouldIgnore(dirent.name))
+        .map(dirent => join(directory, dirent.name)),
+    );
+
+    for (const child of childDirs) {
+      if (!watchers.has(child)) await addDirectory(child);
+    }
+
+    for (const watched of [...watchers.keys()]) {
+      if (watched === directory) continue;
+      if (dirname(watched) === directory && !childDirs.has(watched)) {
+        removeWatcherTree(watched);
+      }
+    }
+  }
+
+  await addDirectory(options.root);
+
+  return {
+    close() {
+      closed = true;
+      if (timer) clearTimeout(timer);
+      timer = undefined;
+      for (const watcher of watchers.values()) watcher.close();
+      watchers.clear();
+    },
+  };
+}

package/src/server/types.ts

@@ -0,0 +1,20 @@
+import type { Stats } from "node:fs";
+import type { DirEntryKind } from "../shared/types.ts";
+
+export type HtmlMode = "filter" | "allow" | "off";
+
+/** A filesystem path that has been validated to live inside the served root. */
+export type ResolvedPath = {
+  path: string;
+  stats: Stats;
+  relative: string;
+};
+
+export type DirectoryEntry = {
+  name: string;
+  kind: DirEntryKind;
+  size?: number;
+  mtime?: Date;
+};
+
+export type FrontmatterData = Record<string, unknown>;

package/src/shared/breadcrumbs.ts

@@ -0,0 +1,14 @@
+import type { Breadcrumb } from "./types.ts";
+
+/** Build root -> ... -> directory breadcrumbs from a relative directory path. */
+export function buildBreadcrumbs(rootLabel: string, relativeDirectory: string): Breadcrumb[] {
+  const crumbs: Breadcrumb[] = [{ label: rootLabel, href: "/" }];
+  let href = "/";
+
+  for (const segment of relativeDirectory.split("/").filter(Boolean)) {
+    href += `${encodeURIComponent(segment)}/`;
+    crumbs.push({ label: segment, href });
+  }
+
+  return crumbs;
+}

package/src/shared/constants.ts

@@ -0,0 +1,20 @@
+/** Protocol constants shared by the server and the browser. */
+
+/** Internal page-data endpoint. The original URL path is appended verbatim. */
+export const API_PAGE_PATH = "/__api/page";
+
+/** Built Svelte assets (Vite `base`). Kept out of user-controlled `/assets`. */
+export const APP_ASSET_PREFIX = "/__app";
+
+/** WebSocket live-reload endpoint. */
+export const LIVE_PATH = "/__serve_md_live";
+
+/** Prebuilt Mermaid browser runtime, loaded lazily. */
+export const MERMAID_RUNTIME_PATH = "/__serve_md_mermaid.js";
+
+/** The shell contains this JSON string token; the server replaces it with a JSON config object. */
+export const CONFIG_TOKEN = '"__SERVE_MD_CONFIG__"';
+
+export const CONFIG_ELEMENT_ID = "serve-md-config";
+
+export const THEME_STORAGE_KEY = "serve-md-theme";

package/src/shared/contracts.ts

@@ -0,0 +1,49 @@
+import type { Breadcrumb, DirEntry, MermaidSource, Theme, TocItem } from "./types.ts";
+
+/** Response of `GET /__api/page/<url path>`. */
+export type DocumentPayload = {
+  kind: "document";
+  path: string;
+  title: string;
+  /** Rendered Markdown content. This is content, not a page shell. */
+  html: string;
+  toc: TocItem[];
+  mermaid: MermaidSource[];
+  breadcrumbs: Breadcrumb[];
+  rawHref: string;
+  warning?: string;
+  lang?: string;
+};
+
+export type DirectoryPayload = {
+  kind: "directory";
+  path: string;
+  heading: string;
+  parentHref?: string;
+  entries: DirEntry[];
+  breadcrumbs: Breadcrumb[];
+};
+
+/** A page that the server wants the browser to visit at another URL. */
+export type RedirectPayload = {
+  kind: "redirect";
+  location: string;
+};
+
+export type PagePayload = DocumentPayload | DirectoryPayload | RedirectPayload;
+
+export type ApiErrorPayload = {
+  error: {
+    status: number;
+    message: string;
+  };
+};
+
+/** Injected into the Svelte shell so the web app does not need a second config request. */
+export type AppConfig = {
+  rootLabel: string;
+  version: string;
+  theme: Theme;
+  live: boolean;
+  mermaid: boolean;
+};

package/src/shared/types.ts

@@ -0,0 +1,33 @@
+/** Types shared by the Bun server and the Svelte web app. Keep this file runtime-free. */
+
+export type Theme = "auto" | "light" | "dark";
+
+/** The concrete theme applied to the document after "auto" has been resolved. */
+export type ResolvedTheme = "light" | "dark";
+
+export type TocItem = {
+  level: number;
+  id: string;
+  text: string;
+};
+
+export type Breadcrumb = {
+  label: string;
+  href: string;
+};
+
+/** A Mermaid diagram extracted from a Markdown document. */
+export type MermaidSource = {
+  id: string;
+  source: string;
+};
+
+export type DirEntryKind = "dir" | "file" | "markdown";
+
+export type DirEntry = {
+  name: string;
+  kind: DirEntryKind;
+  size?: number;
+  /** ISO 8601 timestamp. Formatting belongs to the web app. */
+  mtime?: string;
+};