srvmd 0.1.0

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "srvmd",
+  "version": "0.1.0",
+  "description": "Static file server with live-reloading Markdown rendering, built on Bun",
+  "type": "module",
+  "bin": {
+    "srvmd": "src/cli/index.ts"
+  },
+  "files": [
+    "src",
+    "web/dist",
+    "!src/**/*.test.ts",
+    "README.md",
+    "README_CN.md",
+    "ARCHITECTURE.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "dev": "bun --watch src/cli/index.ts",
+    "dev:web": "vite build --watch --config web/vite.config.ts",
+    "build": "vite build --config web/vite.config.ts",
+    "start": "bun src/cli/index.ts",
+    "test": "bun run test:server && bun run test:web",
+    "test:server": "bun test",
+    "test:web": "vitest run --config web/vitest.config.ts",
+    "test:watch": "vitest --config web/vitest.config.ts",
+    "typecheck": "tsc --noEmit && svelte-check --tsconfig web/tsconfig.json",
+    "check": "biome check . && prettier --check \"web/**/*.svelte\"",
+    "check:fix": "biome check --write . && prettier --write \"web/**/*.svelte\"",
+    "lint": "biome lint .",
+    "format": "biome format --write . && prettier --write \"web/**/*.svelte\"",
+    "prepack": "bun run build",
+    "test:e2e": "playwright test"
+  },
+  "keywords": [
+    "bun",
+    "markdown",
+    "static-server",
+    "live-reload",
+    "preview",
+    "serve-markdown",
+    "md"
+  ],
+  "license": "MIT",
+  "engines": {
+    "bun": ">=1.3.8"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "2.5.15",
+    "@playwright/test": "^1.64.1",
+    "@sveltejs/vite-plugin-svelte": "^7.3.1",
+    "@testing-library/svelte": "^5.4.2",
+    "@types/bun": "latest",
+    "jsdom": "^30.1.3",
+    "prettier": "^3.9.10",
+    "prettier-plugin-svelte": "^4.1.1",
+    "svelte": "^5.57.2",
+    "svelte-check": "^4.7.7",
+    "typescript": "6.0.3",
+    "vite": "^8.3.5",
+    "vitest": "^5.0.5"
+  },
+  "dependencies": {
+    "commander": "^15.0.0",
+    "mermaid": "^12.2.0",
+    "shiki": "^4.5.0"
+  }
+}

package/src/cli/browser.ts

@@ -0,0 +1,14 @@
+export async function openInBrowser(url: string): Promise<void> {
+  const command =
+    process.platform === "darwin"
+      ? ["open", url]
+      : process.platform === "win32"
+        ? ["cmd", "/c", "start", "", url]
+        : ["xdg-open", url];
+
+  try {
+    Bun.spawn({ cmd: command, stdout: "ignore", stderr: "ignore" }).unref();
+  } catch {
+    // Opening the browser is best-effort.
+  }
+}

package/src/cli/command.ts

@@ -0,0 +1,56 @@
+import { Command } from "commander";
+import pkg from "../../package.json";
+import { startServer } from "../server/create-server.ts";
+import { openInBrowser } from "./browser.ts";
+import { installSignalHandlers } from "./lifecycle.ts";
+import { type RawCliOptions, toServerOptions } from "./options.ts";
+import { printStartupReport } from "./report.ts";
+
+function collect(value: string, previous: string[] = []): string[] {
+  return [...previous, value];
+}
+
+export function createCommand(): Command {
+  return new Command()
+    .name("srvmd")
+    .description("A static file server that renders Markdown, with live reload.")
+    .usage("[directory] [options]")
+    .argument("[directory]", "directory to serve", ".")
+    .option("-l, --listen <value>", "port or interface to listen on", "3000")
+    .option("-o, --open", "open the served URL in the default browser")
+    .option("-s, --single", "serve index.html (or index.md) for unmatched routes")
+    .option("-c, --cors", "send permissive CORS headers")
+    .option("--theme <theme>", "default theme: auto, light or dark", "auto")
+    .option("--html <mode>", "raw HTML handling: filter, allow or off", "filter")
+    .option("--math", "enable $inline$ and $$display$$ math")
+    .option("--ignore <name>", "extra names the watcher should ignore (repeatable)", collect, [])
+    .option("--no-live", "disable live reload over WebSocket")
+    .option("--no-highlight", "disable syntax highlighting")
+    .option("--no-mermaid", "disable Mermaid diagram rendering")
+    .option("--no-clean-urls", "disable resolving /page to page.md")
+    .option("--no-directory-listing", "disable generated directory indexes")
+    .version(pkg.version, "-v, --version", "print the version")
+    .helpOption("-h, --help", "display help for command")
+    .showHelpAfterError()
+    .action(async (directory: string, raw: RawCliOptions) => {
+      const options = toServerOptions(directory, raw);
+      const running = await startServer(options);
+
+      printStartupReport({
+        root: running.root,
+        url: running.url,
+        port: running.port,
+        features: [
+          options.live !== false ? "live reload" : null,
+          options.highlight !== false ? "highlight" : null,
+          options.mermaid !== false ? "mermaid" : null,
+          options.cleanUrls !== false ? "clean urls" : null,
+          options.directoryListing !== false ? "directory listing" : null,
+          options.single ? "single page" : null,
+        ].filter((feature): feature is string => feature !== null),
+      });
+
+      if (raw.open) await openInBrowser(running.url);
+      installSignalHandlers(() => running.close());
+    });
+}

package/src/cli/index.ts

@@ -0,0 +1,16 @@
+#!/usr/bin/env bun
+import { createCommand } from "./command.ts";
+
+async function main(): Promise<void> {
+  const program = createCommand();
+  await program.parseAsync(Bun.argv.slice(2), { from: "user" });
+}
+
+main().catch(error => {
+  const message = error instanceof Error ? error.message : String(error);
+  process.stderr.write(`srvmd: ${message}\n`);
+  if (/EADDRINUSE|address already in use/i.test(message)) {
+    process.stderr.write("Hint: choose another port with --listen.\n");
+  }
+  process.exit(1);
+});

package/src/cli/lifecycle.ts

@@ -0,0 +1,13 @@
+export function installSignalHandlers(close: () => void): void {
+  let stopping = false;
+
+  const shutdown = () => {
+    if (stopping) return;
+    stopping = true;
+    close();
+    process.exit(0);
+  };
+
+  process.on("SIGINT", shutdown);
+  process.on("SIGTERM", shutdown);
+}

package/src/cli/listen.ts

@@ -0,0 +1,27 @@
+export type ListenOptions = {
+  hostname?: string;
+  port: number;
+};
+
+function assertPort(port: number, source: string): number {
+  if (!Number.isInteger(port) || port < 0 || port > 65535) {
+    throw new Error(`Invalid port in --listen value: ${source}`);
+  }
+  return port;
+}
+
+/** Parse `3000`, `host:3000`, or `[::1]:3000`. */
+export function parseListen(value: string | undefined): ListenOptions {
+  if (!value) return { port: 3000 };
+  if (/^\d+$/.test(value)) return { port: assertPort(Number(value), value) };
+
+  const bracketed = /^\[([^\]]+)\]:(\d+)$/.exec(value);
+  if (bracketed) return { hostname: bracketed[1], port: assertPort(Number(bracketed[2]), value) };
+
+  const separator = value.lastIndexOf(":");
+  if (separator === -1) throw new Error(`Invalid --listen value: ${value}`);
+
+  const hostname = value.slice(0, separator) || undefined;
+  const port = assertPort(Number(value.slice(separator + 1)), value);
+  return { hostname, port };
+}

package/src/cli/options.ts

@@ -0,0 +1,52 @@
+import { resolve } from "node:path";
+import type { ServeMarkdownOptions } from "../server/config.ts";
+import type { HtmlMode } from "../server/types.ts";
+import type { Theme } from "../shared/types.ts";
+import { parseListen } from "./listen.ts";
+
+export type RawCliOptions = {
+  listen: string;
+  open?: boolean;
+  single?: boolean;
+  cors?: boolean;
+  theme: string;
+  html: string;
+  math?: boolean;
+  ignore?: string[];
+  live: boolean;
+  highlight: boolean;
+  mermaid: boolean;
+  cleanUrls: boolean;
+  directoryListing: boolean;
+};
+
+const THEMES: Theme[] = ["auto", "light", "dark"];
+const HTML_MODES: HtmlMode[] = ["filter", "allow", "off"];
+
+/** Map Commander's raw values onto the public server options contract. */
+export function toServerOptions(directory: string, raw: RawCliOptions): ServeMarkdownOptions {
+  const theme = raw.theme as Theme;
+  if (!THEMES.includes(theme)) throw new Error(`Invalid --theme value: ${raw.theme}`);
+
+  const html = raw.html as HtmlMode;
+  if (!HTML_MODES.includes(html)) throw new Error(`Invalid --html value: ${raw.html}`);
+
+  const { hostname, port } = parseListen(raw.listen);
+
+  return {
+    root: resolve(directory),
+    port,
+    hostname,
+    live: raw.live !== false,
+    highlight: raw.highlight !== false,
+    cleanUrls: raw.cleanUrls !== false,
+    directoryListing: raw.directoryListing !== false,
+    single: raw.single === true,
+    cors: raw.cors === true,
+    theme,
+    html,
+    math: raw.math === true,
+    mermaid: raw.mermaid !== false,
+    ignore: raw.ignore,
+  };
+}

package/src/cli/report.ts

@@ -0,0 +1,40 @@
+import { networkInterfaces } from "node:os";
+
+export type StartupReport = {
+  root: string;
+  url: string;
+  port: number;
+  features: string[];
+};
+
+function color(enabled: boolean, code: string, text: string): string {
+  return enabled ? `\u001b[${code}m${text}\u001b[0m` : text;
+}
+
+function localNetworkUrls(port: number): string[] {
+  const urls: string[] = [];
+  for (const addresses of Object.values(networkInterfaces())) {
+    for (const address of addresses ?? []) {
+      const family = String(address.family);
+      if ((family === "IPv4" || family === "4") && !address.internal) {
+        urls.push(`http://${address.address}:${port}`);
+      }
+    }
+  }
+  return urls;
+}
+
+export function printStartupReport(report: StartupReport): void {
+  const useColor = process.stdout.isTTY && !process.env.NO_COLOR;
+  const lines = [
+    color(useColor, "1", "srvmd"),
+    `  Serving   ${report.root}`,
+    `  Local     ${color(useColor, "36", report.url)}`,
+  ];
+
+  for (const networkUrl of localNetworkUrls(report.port)) lines.push(`  Network   ${networkUrl}`);
+  lines.push(`  Features  ${report.features.join(", ")}`);
+  lines.push("  Watched   markdown, html and css files (Ctrl+C to stop)");
+
+  process.stdout.write(`${lines.join("\n")}\n`);
+}

package/src/server/assets/mermaid.ts

@@ -0,0 +1,38 @@
+import { stat } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+import { baseHeaders } from "../http/headers.ts";
+import { fileResponse } from "../http/respond.ts";
+
+let bundlePath: string | null | undefined;
+
+/** Resolve Mermaid's prebuilt browser bundle once, from the local dependency. */
+function resolveBundle(): string | null {
+  if (bundlePath !== undefined) return bundlePath;
+  try {
+    bundlePath = fileURLToPath(import.meta.resolve("mermaid/dist/mermaid.min.js"));
+  } catch {
+    bundlePath = null;
+  }
+  return bundlePath;
+}
+
+function unavailable(cors: boolean): Response {
+  return new Response("Mermaid bundle is unavailable", { status: 503, headers: baseHeaders(cors) });
+}
+
+export async function respondMermaidRuntime(request: Request, cors: boolean): Promise<Response> {
+  const path = resolveBundle();
+  if (!path) return unavailable(cors);
+
+  const stats = await stat(path).catch(() => null);
+  if (!stats?.isFile()) return unavailable(cors);
+
+  const response = fileResponse(
+    { path, stats, relative: "mermaid.min.js" },
+    request,
+    cors,
+    "text/javascript; charset=utf-8",
+  );
+  response.headers.set("Cache-Control", "public, max-age=3600");
+  return response;
+}

package/src/server/assets/web.ts

@@ -0,0 +1,34 @@
+import { stat } from "node:fs/promises";
+import { resolve } from "node:path";
+import { APP_ASSET_PREFIX } from "../../shared/constants.ts";
+import { fileResponse, textResponse } from "../http/respond.ts";
+import { isInside } from "../path.ts";
+
+/** Serve the Vite build under `/__app/*`, outside user-controlled static paths. */
+export async function respondWebAsset(webRoot: string, url: URL, request: Request, cors: boolean): Promise<Response> {
+  let pathname: string;
+  try {
+    pathname = decodeURIComponent(url.pathname);
+  } catch {
+    return textResponse("Malformed URL", 400, request.method, cors);
+  }
+
+  const relative = pathname.slice(APP_ASSET_PREFIX.length).replace(/^\/+/, "");
+  if (!relative || relative.includes("\0")) {
+    return textResponse("Not found", 404, request.method, cors);
+  }
+
+  const filePath = resolve(webRoot, relative);
+  if (!isInside(webRoot, filePath)) {
+    return textResponse("Forbidden", 403, request.method, cors);
+  }
+
+  const stats = await stat(filePath).catch(() => null);
+  if (!stats?.isFile()) {
+    return textResponse("Not found", 404, request.method, cors);
+  }
+
+  const response = fileResponse({ path: filePath, stats, relative }, request, cors);
+  response.headers.set("Cache-Control", "public, max-age=3600");
+  return response;
+}

package/src/server/config.ts

@@ -0,0 +1,99 @@
+import { realpath, stat } from "node:fs/promises";
+import { basename, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import pkg from "../../package.json";
+import type { Theme } from "../shared/types.ts";
+import type { HtmlMode } from "./types.ts";
+
+export type ServeMarkdownOptions = {
+  /** Directory to serve. Default: process.cwd() */
+  root?: string;
+  /** Listening port. Use 0 for a random free port. Default: 3000 */
+  port?: number;
+  /** Interface to bind. Default: 0.0.0.0 */
+  hostname?: string;
+  /** Push reload events over WebSocket. Default: true */
+  live?: boolean;
+  /** Highlight fenced code blocks. Default: true */
+  highlight?: boolean;
+  /** Resolve /page to page.md / page.html. Default: true */
+  cleanUrls?: boolean;
+  /** Render directory indexes. Default: true */
+  directoryListing?: boolean;
+  /** Serve index.html (or index.md) for unmatched routes. Default: false */
+  single?: boolean;
+  /** Send permissive CORS headers. Default: false */
+  cors?: boolean;
+  /** Default color theme. Default: "auto" */
+  theme?: Theme;
+  /** Raw HTML handling: "filter" (GFM tag filter), "allow", or "off". Default: "filter" */
+  html?: HtmlMode;
+  /** Enable LaTeX math. Default: false */
+  math?: boolean;
+  /** Render ```mermaid fences as interactive diagrams. Default: true */
+  mermaid?: boolean;
+  /** Extra directory/file names the watcher should ignore. */
+  ignore?: string[];
+  /** Built Svelte assets. Defaults to `<package>/web/dist`. */
+  webRoot?: string;
+};
+
+export type ResolvedConfig = {
+  root: string;
+  rootLabel: string;
+  port: number;
+  hostname: string;
+  live: boolean;
+  highlight: boolean;
+  cleanUrls: boolean;
+  directoryListing: boolean;
+  single: boolean;
+  cors: boolean;
+  theme: Theme;
+  html: HtmlMode;
+  math: boolean;
+  mermaid: boolean;
+  ignore: string[];
+  webRoot: string;
+  version: string;
+};
+
+const THEMES: Theme[] = ["auto", "light", "dark"];
+const HTML_MODES: HtmlMode[] = ["filter", "allow", "off"];
+const DEFAULT_WEB_ROOT = fileURLToPath(new URL("../../web/dist", import.meta.url));
+
+/** Normalize user options into a fully resolved, validated config. */
+export async function resolveConfig(options: ServeMarkdownOptions = {}): Promise<ResolvedConfig> {
+  const requestedRoot = resolve(options.root ?? process.cwd());
+  const root = await realpath(requestedRoot).catch(() => null);
+  if (!root) throw new Error(`Directory not found: ${requestedRoot}`);
+
+  const info = await stat(root);
+  if (!info.isDirectory()) throw new Error(`Not a directory: ${requestedRoot}`);
+
+  const theme = options.theme ?? "auto";
+  if (!THEMES.includes(theme)) throw new Error(`Invalid theme: ${theme}. Use auto, light or dark.`);
+
+  const html = options.html ?? "filter";
+  if (!HTML_MODES.includes(html)) throw new Error(`Invalid html mode: ${html}. Use filter, allow or off.`);
+
+  return {
+    root,
+    rootLabel: basename(root) || "/",
+    port: options.port ?? 3000,
+    hostname: options.hostname ?? "0.0.0.0",
+    live: options.live !== false,
+    highlight: options.highlight !== false,
+    cleanUrls: options.cleanUrls !== false,
+    directoryListing: options.directoryListing !== false,
+    single: options.single === true,
+    cors: options.cors === true,
+    theme,
+    html,
+    math: options.math === true,
+    mermaid: options.mermaid !== false,
+    ignore: options.ignore ?? [],
+    webRoot: resolve(options.webRoot ?? DEFAULT_WEB_ROOT),
+    version: pkg.version,
+  };
+}

package/src/server/constants.ts

@@ -0,0 +1,33 @@
+/** Constants used by the Bun server. Protocol paths live in `shared/constants.ts`. */
+
+/** Fenced code language rendered in the browser by Mermaid. */
+export const MERMAID_LANGUAGE = "mermaid";
+
+/** Directories that are never watched, listed, or served implicitly. */
+export const IGNORED_NAMES = new Set([
+  "node_modules",
+  ".git",
+  ".hg",
+  ".svn",
+  ".cache",
+  ".next",
+  ".nuxt",
+  ".svelte-kit",
+  ".venv",
+  "__pycache__",
+]);
+
+export const MARKDOWN_EXTENSIONS = new Set([".md", ".markdown", ".mdown", ".mkd"]);
+
+export const MARKDOWN_EXTENSION_RE = /\.(md|markdown|mdown|mkd)$/i;
+
+export const WATCHED_EXTENSIONS = /\.(md|markdown|mdown|mkd|html?|css)$/i;
+
+export const MAX_CACHED_DOCUMENTS = 64;
+
+export const MAX_HTML_INJECTION_BYTES = 5 * 1024 * 1024;
+
+export const WATCH_DEBOUNCE_MS = 80;
+
+/** Suffixes tried when resolving extensionless (clean) URLs, in order. */
+export const CLEAN_URL_SUFFIXES = [".md", ".markdown", ".html", ".htm"] as const;

package/src/server/context.ts

@@ -0,0 +1,40 @@
+import type { Highlighter } from "shiki";
+import type { ResolvedConfig } from "./config.ts";
+import { createHighlighterService, createRenderer, type Renderer } from "./markdown/index.ts";
+import { createDocumentStore, type DocumentStore } from "./services/documents.ts";
+import { createLiveReload, type LiveReload } from "./services/live/index.ts";
+
+export type ServerContext = {
+  config: ResolvedConfig;
+  renderer: Renderer;
+  documents: DocumentStore;
+  highlighter: Highlighter | null;
+  live: LiveReload | null;
+};
+
+/** Build the long-lived services a server needs (highlighter, cache, watcher). */
+export async function createContext(config: ResolvedConfig): Promise<ServerContext> {
+  const highlighter = config.highlight ? await createHighlighterService() : null;
+  const renderer = createRenderer({
+    highlighter,
+    html: config.html,
+    math: config.math,
+    mermaid: config.mermaid,
+  });
+  const documents = createDocumentStore(renderer);
+
+  const live = config.live
+    ? await createLiveReload({
+        root: config.root,
+        ignore: config.ignore,
+        onChange: () => documents.clear(),
+      })
+    : null;
+
+  return { config, renderer, documents, highlighter, live };
+}
+
+export function disposeContext(context: ServerContext): void {
+  context.live?.closeAll();
+  context.highlighter?.dispose();
+}

package/src/server/create-server.ts

@@ -0,0 +1,69 @@
+import type { Server } from "bun";
+import { resolveConfig, type ServeMarkdownOptions } from "./config.ts";
+import { createContext, disposeContext } from "./context.ts";
+import { textResponse } from "./http/respond.ts";
+import { createRequestHandler } from "./routes/index.ts";
+
+export type { ServeMarkdownOptions } from "./config.ts";
+
+export type RunningServer = {
+  server: Server<undefined>;
+  port: number;
+  url: string;
+  root: string;
+  close(): void;
+};
+
+export async function startServer(options: ServeMarkdownOptions = {}): Promise<RunningServer> {
+  if (typeof Bun.markdown?.html !== "function") {
+    throw new Error("Bun 1.3.8 or newer is required (Bun.markdown is unavailable). Run `bun upgrade`.");
+  }
+
+  const config = await resolveConfig(options);
+  const context = await createContext(config);
+  const handler = createRequestHandler(context);
+  const live = context.live;
+
+  const listenOptions = {
+    port: config.port,
+    hostname: config.hostname,
+    development: true,
+    idleTimeout: 255,
+    error: (cause: Error) => {
+      console.error("[srvmd]", cause);
+      return textResponse(cause.message, 500, "GET", config.cors);
+    },
+  } as const;
+
+  let server: Server<undefined>;
+  if (live) {
+    server = Bun.serve({
+      ...listenOptions,
+      fetch: handler,
+      websocket: {
+        open: socket => live.open(socket),
+        close: socket => live.close(socket),
+        message: (socket, message) => live.message(socket, message),
+      },
+    });
+  } else {
+    server = Bun.serve({
+      ...listenOptions,
+      fetch: async (request, bunServer) =>
+        (await handler(request, bunServer)) ?? new Response("Not found", { status: 404 }),
+    });
+  }
+
+  const port = server.port ?? config.port;
+
+  return {
+    server,
+    port,
+    root: config.root,
+    url: `http://localhost:${port}`,
+    close() {
+      disposeContext(context);
+      server.stop(true);
+    },
+  };
+}

package/src/server/file-kinds.ts

@@ -0,0 +1,15 @@
+import { MARKDOWN_EXTENSION_RE, MARKDOWN_EXTENSIONS } from "./constants.ts";
+
+export function isMarkdownFile(path: string): boolean {
+  const index = path.lastIndexOf(".");
+  return index !== -1 && MARKDOWN_EXTENSIONS.has(path.slice(index).toLowerCase());
+}
+
+export function isHtmlFile(path: string): boolean {
+  const lower = path.toLowerCase();
+  return lower.endsWith(".html") || lower.endsWith(".htm");
+}
+
+export function stripMarkdownExtension(name: string): string {
+  return name.replace(MARKDOWN_EXTENSION_RE, "");
+}

package/src/server/http/headers.ts

@@ -0,0 +1,11 @@
+/** Common response headers for every response this server produces. */
+export function baseHeaders(cors: boolean): Headers {
+  const headers = new Headers();
+  headers.set("X-Content-Type-Options", "nosniff");
+  if (cors) {
+    headers.set("Access-Control-Allow-Origin", "*");
+    headers.set("Access-Control-Allow-Methods", "GET, HEAD, OPTIONS");
+    headers.set("Access-Control-Allow-Headers", "*");
+  }
+  return headers;
+}