@shunyasasaki/mkserve 0.1.1

package/dist/cli.mjs

@@ -0,0 +1,613 @@
+#!/usr/bin/env node
+import { basename, isAbsolute, join, posix, relative, resolve, sep } from "node:path";
+import { defineCommand, runMain } from "citty";
+import { existsSync, readFileSync, realpathSync } from "node:fs";
+import { readFile, readdir, stat } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+import fastifyStatic from "@fastify/static";
+import { consola } from "consola";
+import Fastify from "fastify";
+import getPort from "get-port";
+import open from "open";
+import rehypeShikiFromHighlighter from "@shikijs/rehype/core";
+import { toString } from "hast-util-to-string";
+import rehypeAutolinkHeadings from "rehype-autolink-headings";
+import rehypeKatex from "rehype-katex";
+import rehypeRaw from "rehype-raw";
+import rehypeSlug from "rehype-slug";
+import rehypeStringify from "rehype-stringify";
+import remarkFrontmatter from "remark-frontmatter";
+import remarkGfm from "remark-gfm";
+import { remarkAlert } from "remark-github-blockquote-alert";
+import remarkMath from "remark-math";
+import remarkParse from "remark-parse";
+import remarkRehype from "remark-rehype";
+import { createHighlighter } from "shiki";
+import { unified } from "unified";
+import { visit } from "unist-util-visit";
+import { watch } from "chokidar";
+import ignore from "ignore";
+//#region package.json
+var version = "0.1.1";
+var description = "Serve a workspace of Markdown files with a live-reloading preview.";
+//#endregion
+//#region src/shared/paths.ts
+/** URL-encodes each segment of a POSIX path, keeping the slashes. */
+function encodePath(path) {
+	return path.split("/").map(encodeURIComponent).join("/");
+}
+/** Inverse of {@link encodePath}; returns the input if it is malformed. */
+function decodePath(path) {
+	try {
+		return decodeURIComponent(path);
+	} catch {
+		return path;
+	}
+}
+//#endregion
+//#region src/shared/types.ts
+/** Extensions treated as Markdown documents. */
+const MARKDOWN_EXTENSIONS = [".md", ".markdown"];
+/** Returns whether `path` names a Markdown document. */
+function isMarkdownPath(path) {
+	const lower = path.toLowerCase();
+	return MARKDOWN_EXTENSIONS.some((ext) => lower.endsWith(ext));
+}
+//#endregion
+//#region src/server/render.ts
+/** Languages loaded up front; others are loaded on first use. */
+const PRELOADED_LANGUAGES = [
+	"bash",
+	"css",
+	"diff",
+	"html",
+	"javascript",
+	"json",
+	"jsx",
+	"markdown",
+	"python",
+	"shell",
+	"sql",
+	"toml",
+	"tsx",
+	"typescript",
+	"yaml"
+];
+const THEMES = {
+	light: "github-light",
+	dark: "github-dark"
+};
+const AUTOLINK_OPTIONS = {
+	behavior: "append",
+	properties: {
+		className: ["heading-anchor"],
+		ariaHidden: "true"
+	},
+	content: {
+		type: "text",
+		value: "#"
+	}
+};
+/** Elements whose URL attributes point at workspace files. */
+const URL_ATTRIBUTES = {
+	a: ["href"],
+	img: ["src"],
+	source: ["src"],
+	video: ["src", "poster"],
+	audio: ["src"]
+};
+/**
+* Creates the unified pipeline (CommonMark + GFM, math, alerts, Mermaid,
+* Shiki). The Shiki highlighter is created once and shared by all renders.
+*/
+async function createRenderer() {
+	const highlighter = await createHighlighter({
+		themes: Object.values(THEMES),
+		langs: PRELOADED_LANGUAGES
+	});
+	const processor = unified().use(remarkParse).use(remarkFrontmatter).use(remarkGfm).use(remarkMath).use(remarkAlert).use(remarkRehype, { allowDangerousHtml: true }).use(rehypeRaw).use(rehypeSlug).use(rehypeAutolinkHeadings, AUTOLINK_OPTIONS).use(rehypeKatex, { strict: "ignore" }).use(rehypeMermaid).use(rehypeShikiFromHighlighter, highlighter, {
+		themes: THEMES,
+		lazy: true,
+		fallbackLanguage: "text"
+	}).use(rehypeRewriteUrls).use(rehypeExtractTitle).use(rehypeStringify);
+	return { async render(markdown, docPath) {
+		const file = await processor.process({
+			value: markdown,
+			data: { docPath }
+		});
+		return {
+			html: String(file),
+			title: file.data.title
+		};
+	} };
+}
+/**
+* Turns ```` ```mermaid ```` code blocks into `<pre class="mermaid">` so the
+* client can render them (and Shiki leaves them alone).
+*/
+function rehypeMermaid() {
+	return (tree) => {
+		visit(tree, "element", (node) => {
+			const code = node.children[0];
+			if (node.tagName === "pre" && code?.type === "element" && code.tagName === "code" && classNames(code).includes("language-mermaid")) {
+				node.properties = { className: ["mermaid"] };
+				node.children = [{
+					type: "text",
+					value: toString(code)
+				}];
+			}
+		});
+	};
+}
+/**
+* Rewrites relative links: Markdown links become SPA routes, other files are
+* served through `/@ws/`, and external links open in a new tab.
+*/
+function rehypeRewriteUrls() {
+	return (tree, file) => {
+		const docDir = posix.dirname(file.data.docPath ?? "");
+		visit(tree, "element", (node) => {
+			for (const attr of URL_ATTRIBUTES[node.tagName] ?? []) {
+				const value = node.properties[attr];
+				if (typeof value !== "string") continue;
+				if (isExternal(value)) {
+					if (node.tagName === "a") {
+						node.properties.target = "_blank";
+						node.properties.rel = ["noopener", "noreferrer"];
+					}
+					continue;
+				}
+				node.properties[attr] = rewriteUrl(value, docDir, node.tagName === "a");
+			}
+		});
+	};
+}
+function rehypeExtractTitle() {
+	return (tree, file) => {
+		visit(tree, "element", (node) => {
+			if (node.tagName === "h1" && file.data.title === void 0) file.data.title = toString(node).replace(/#$/, "").trim();
+		});
+	};
+}
+function isExternal(url) {
+	return /^[a-z][a-z0-9+.-]*:/i.test(url) || url.startsWith("//");
+}
+/** Exported for tests. */
+function rewriteUrl(url, docDir, isLink) {
+	if (url === "" || url.startsWith("#")) return url;
+	const cut = url.search(/[?#]/);
+	const pathPart = cut === -1 ? url : url.slice(0, cut);
+	const suffix = cut === -1 ? "" : url.slice(cut);
+	let decoded;
+	try {
+		decoded = decodeURI(pathPart);
+	} catch {
+		return url;
+	}
+	const resolved = decoded.startsWith("/") ? posix.normalize(decoded.slice(1)) : posix.join(docDir, decoded);
+	if (resolved.startsWith("..")) return url;
+	return (isLink && isMarkdownPath(resolved) ? "/" : "/@ws/") + encodePath(resolved) + suffix;
+}
+function classNames(node) {
+	const value = node.properties.className;
+	return Array.isArray(value) ? value.map(String) : [];
+}
+//#endregion
+//#region src/server/safe_path.ts
+/**
+* Resolves a workspace-relative path to an absolute one, or returns
+* `undefined` when it would escape `root` (including through symlinks).
+*/
+function resolveInRoot(root, relPath) {
+	if (relPath.includes("\0")) return;
+	const abs = resolve(root, relPath.replace(/^\/+/, ""));
+	if (!isInside(root, abs)) return;
+	try {
+		if (!isInside(realpathSync(root), realpathSync(abs))) return;
+	} catch {}
+	return abs;
+}
+/** Converts an absolute path inside `root` to a POSIX relative path. */
+function toRelPosix(root, abs) {
+	return relative(root, abs).split(sep).join("/");
+}
+function isInside(root, abs) {
+	const rel = relative(root, abs);
+	return rel === "" || !rel.startsWith("..") && !isAbsolute(rel);
+}
+//#endregion
+//#region src/server/sse.ts
+const PING_INTERVAL_MS = 3e4;
+/** Registry of connected `EventSource` clients. */
+var EventHub = class {
+	clients = /* @__PURE__ */ new Set();
+	pingTimer;
+	constructor() {
+		this.pingTimer = setInterval(() => this.write("ping", {}), PING_INTERVAL_MS);
+		this.pingTimer.unref();
+	}
+	/** Number of connected clients. */
+	get size() {
+		return this.clients.size;
+	}
+	/** Starts an SSE stream on `res` and keeps it until the client leaves. */
+	add(res) {
+		res.writeHead(200, {
+			"content-type": "text/event-stream; charset=utf-8",
+			"cache-control": "no-cache",
+			connection: "keep-alive",
+			"x-accel-buffering": "no"
+		});
+		res.write("retry: 1000\n\n");
+		this.clients.add(res);
+		res.on("close", () => this.clients.delete(res));
+	}
+	/** Sends an event to every client. */
+	broadcast(event, data) {
+		this.write(event, data);
+	}
+	/** Ends all streams so the HTTP server can shut down. */
+	close() {
+		clearInterval(this.pingTimer);
+		for (const res of this.clients) res.end();
+		this.clients.clear();
+	}
+	write(event, data) {
+		const message = `event: ${event}\ndata: ${JSON.stringify(data)}\n\n`;
+		for (const res of this.clients) res.write(message);
+	}
+};
+//#endregion
+//#region src/server/tree.ts
+/**
+* Builds the Markdown-only tree of `root`. Directories without Markdown
+* files (recursively) are pruned; ignored and hidden entries are skipped.
+*/
+async function buildTree(root, ignore) {
+	const children = await readDir(root, "", ignore);
+	return {
+		name: basename(root),
+		path: "",
+		type: "dir",
+		children
+	};
+}
+async function readDir(root, relDir, ignore) {
+	let entries;
+	try {
+		entries = await readdir(join(root, relDir), { withFileTypes: true });
+	} catch {
+		return [];
+	}
+	const nodes = [];
+	for (const entry of entries) {
+		const path = relDir === "" ? entry.name : `${relDir}/${entry.name}`;
+		let isDir = entry.isDirectory();
+		let isFile = entry.isFile();
+		if (entry.isSymbolicLink()) {
+			const target = await stat(join(root, path)).catch(() => void 0);
+			isDir = false;
+			isFile = target?.isFile() ?? false;
+		}
+		if (!isDir && !isFile || ignore.isIgnored(path, isDir)) continue;
+		if (isDir) {
+			const children = await readDir(root, path, ignore);
+			if (children.length > 0) nodes.push({
+				name: entry.name,
+				path,
+				type: "dir",
+				children
+			});
+		} else if (isMarkdownPath(entry.name)) nodes.push({
+			name: entry.name,
+			path,
+			type: "file"
+		});
+	}
+	return nodes.sort(compareNodes);
+}
+function compareNodes(a, b) {
+	if (a.type !== b.type) return a.type === "dir" ? -1 : 1;
+	return a.name.localeCompare(b.name, void 0, { sensitivity: "base" });
+}
+//#endregion
+//#region src/server/watcher.ts
+const DEBOUNCE_MS = 50;
+/**
+* Watches the workspace and broadcasts `change` (Markdown edited, added, or
+* removed), `tree` (structure changed), and `asset` (other file edited).
+*/
+function startWatcher(options) {
+	const { root, ignore, hub } = options;
+	const timers = /* @__PURE__ */ new Map();
+	function debounced(key, fn) {
+		clearTimeout(timers.get(key));
+		timers.set(key, setTimeout(() => {
+			timers.delete(key);
+			fn();
+		}, DEBOUNCE_MS));
+	}
+	function treeChanged() {
+		debounced("\0tree", () => {
+			options.onTreeChange();
+			hub.broadcast("tree", {});
+		});
+	}
+	const watcher = watch(root, {
+		ignoreInitial: true,
+		awaitWriteFinish: {
+			stabilityThreshold: 100,
+			pollInterval: 20
+		},
+		ignored: (absPath, stats) => {
+			const rel = toRelPosix(root, absPath);
+			if (rel === "") return false;
+			if (basename(rel) === ".gitignore") {
+				const dir = posix.dirname(rel);
+				return dir !== "." && ignore.isIgnored(dir, true);
+			}
+			return ignore.isIgnored(rel, stats?.isDirectory() ?? false);
+		}
+	});
+	watcher.on("all", (event, absPath) => {
+		const path = toRelPosix(root, absPath);
+		if (basename(path) === ".gitignore") {
+			ignore.invalidate();
+			treeChanged();
+			return;
+		}
+		if (event === "addDir" || event === "unlinkDir") {
+			treeChanged();
+			return;
+		}
+		if (!isMarkdownPath(path)) {
+			debounced(`asset:${path}`, () => hub.broadcast("asset", { path }));
+			return;
+		}
+		if (event === "add" || event === "unlink") treeChanged();
+		debounced(`change:${path}`, () => hub.broadcast("change", { path }));
+	});
+	return watcher;
+}
+//#endregion
+//#region src/server/workspace_ignore.ts
+/** Directory names that are never part of the workspace view. */
+const ALWAYS_IGNORED = /* @__PURE__ */ new Set([".git", "node_modules"]);
+/**
+* Decides whether workspace paths are hidden, honoring `.gitignore` files at
+* every directory level. Rules are loaded lazily and cached until
+* {@link WorkspaceIgnore.invalidate} is called.
+*/
+var WorkspaceIgnore = class {
+	root;
+	rules = /* @__PURE__ */ new Map();
+	constructor(root) {
+		this.root = root;
+	}
+	/** Drops cached rules, e.g. after a `.gitignore` changed. */
+	invalidate() {
+		this.rules.clear();
+	}
+	/**
+	* Returns whether the POSIX relative path is hidden: a dot-entry, an
+	* always-ignored directory, or matched by a `.gitignore` (or inside a
+	* directory that is).
+	*/
+	isIgnored(relPath, isDir) {
+		const segments = relPath.split("/").filter((s) => s !== "" && s !== ".");
+		for (let i = 0; i < segments.length; i++) {
+			const name = segments[i];
+			if (name.startsWith(".") || ALWAYS_IGNORED.has(name)) return true;
+			const entryIsDir = i < segments.length - 1 || isDir;
+			if (this.matchesGitignore(segments, i, entryIsDir)) return true;
+		}
+		return false;
+	}
+	/** Checks segments[0..=index] against every ancestor `.gitignore`. */
+	matchesGitignore(segments, index, isDir) {
+		for (let base = 0; base <= index; base++) {
+			const rules = this.load(segments.slice(0, base).join("/"));
+			if (!rules) continue;
+			const sub = segments.slice(base, index + 1).join("/");
+			if (rules.ignores(isDir ? `${sub}/` : sub)) return true;
+		}
+		return false;
+	}
+	load(dir) {
+		const cached = this.rules.get(dir);
+		if (cached !== void 0) return cached;
+		let rules = null;
+		try {
+			const text = readFileSync(join(this.root, dir, ".gitignore"), "utf8");
+			rules = ignore().add(text);
+		} catch {}
+		this.rules.set(dir, rules);
+		return rules;
+	}
+};
+//#endregion
+//#region src/server/app.ts
+/** Built client, located next to the bundled `dist/cli.mjs`. */
+const CLIENT_DIR = fileURLToPath(new URL("./client/", import.meta.url));
+const CLIENT_NOT_BUILT_HTML = "<!doctype html><title>mkserve</title><p>The client is not built. Run <code>pnpm build</code>.</p>";
+/** Creates the Fastify app (routes, static files, watcher) without listening. */
+async function buildApp(options) {
+	const { root } = options;
+	const clientDir = options.clientDir ?? CLIENT_DIR;
+	const renderer = options.renderer ?? await createRenderer();
+	const ignore = new WorkspaceIgnore(root);
+	const hub = new EventHub();
+	const app = Fastify({ forceCloseConnections: true });
+	let treeCache;
+	function getTree() {
+		if (!options.watch) return buildTree(root, ignore);
+		treeCache ??= buildTree(root, ignore);
+		return treeCache;
+	}
+	if (options.watch) {
+		const watcher = startWatcher({
+			root,
+			ignore,
+			hub,
+			onTreeChange: () => {
+				treeCache = void 0;
+			}
+		});
+		app.addHook("onClose", async () => {
+			await watcher.close();
+		});
+	}
+	app.addHook("preClose", async () => hub.close());
+	await app.register(fastifyStatic, {
+		root,
+		serve: false
+	});
+	const indexHtml = existsSync(join(clientDir, "index.html")) ? readFileSync(join(clientDir, "index.html"), "utf8") : CLIENT_NOT_BUILT_HTML;
+	if (existsSync(clientDir)) await app.register(fastifyStatic, {
+		root: clientDir,
+		prefix: "/",
+		index: false,
+		wildcard: false,
+		decorateReply: false
+	});
+	app.get("/api/info", async () => {
+		return {
+			name: basename(root),
+			version,
+			watch: options.watch
+		};
+	});
+	app.get("/api/tree", () => getTree());
+	app.get("/api/render", async (request, reply) => {
+		const relPath = request.query.path;
+		if (!relPath || !isMarkdownPath(relPath)) return sendError(reply, 400, "A Markdown path is required");
+		const abs = resolveInRoot(root, relPath);
+		if (abs === void 0) return sendError(reply, 400, "Path is outside the workspace");
+		const path = toRelPosix(root, abs);
+		if (ignore.isIgnored(path, false)) return sendError(reply, 404, "Not found");
+		let source;
+		let mtime;
+		try {
+			[source, mtime] = await Promise.all([readFile(abs, "utf8"), stat(abs).then((s) => s.mtimeMs)]);
+		} catch {
+			return sendError(reply, 404, "Not found");
+		}
+		const { html, title } = await renderer.render(source, path);
+		return {
+			path,
+			html,
+			title: title ?? basename(path),
+			mtime
+		};
+	});
+	app.get("/api/events", (request, reply) => {
+		if (!options.watch) return sendError(reply, 404, "Live reload is disabled");
+		reply.hijack();
+		hub.add(reply.raw);
+		return reply;
+	});
+	app.get("/@ws/*", (request, reply) => {
+		const abs = resolveInRoot(root, decodePath(request.params["*"]));
+		if (abs === void 0) return sendError(reply, 400, "Path is outside the workspace");
+		const path = toRelPosix(root, abs);
+		if (path === "" || ignore.isIgnored(path, false)) return sendError(reply, 404, "Not found");
+		return reply.header("cache-control", "no-cache").sendFile(path);
+	});
+	app.setNotFoundHandler((request, reply) => {
+		const wantsHtml = request.headers.accept?.includes("text/html") ?? false;
+		const isApi = /^\/(api|@ws)\//.test(request.url);
+		if (request.method === "GET" && wantsHtml && !isApi) return reply.type("text/html; charset=utf-8").send(indexHtml);
+		return sendError(reply, 404, "Not found");
+	});
+	return app;
+}
+function sendError(reply, statusCode, message) {
+	return reply.code(statusCode).send({ error: message });
+}
+/** Builds the app, listens, and wires graceful shutdown. */
+async function startServer(options) {
+	if (!existsSync(options.root)) {
+		consola.error(`Directory not found: ${options.root}`);
+		process.exit(1);
+	}
+	const app = await buildApp({
+		root: options.root,
+		watch: options.watch
+	});
+	const port = options.port ?? await getPort({ port: options.defaultPort });
+	try {
+		await app.listen({
+			port,
+			host: options.host
+		});
+	} catch (err) {
+		consola.error(err instanceof Error ? err.message : err);
+		process.exit(1);
+	}
+	const url = `http://${options.host}:${port}`;
+	consola.success(`mkserve v${version} → ${url} (root: ${options.root})`);
+	if (options.open) await open(url);
+	const shutdown = async () => {
+		await app.close();
+		process.exit(0);
+	};
+	process.once("SIGINT", shutdown);
+	process.once("SIGTERM", shutdown);
+}
+//#endregion
+//#region src/cli.ts
+const DEFAULT_PORT = 3e3;
+const main = defineCommand({
+	meta: {
+		name: "mkserve",
+		version,
+		description
+	},
+	args: {
+		dir: {
+			type: "positional",
+			description: "Workspace root",
+			required: false,
+			default: "."
+		},
+		port: {
+			type: "string",
+			alias: "p",
+			description: `Port to listen on (default: ${DEFAULT_PORT})`
+		},
+		host: {
+			type: "string",
+			description: "Bind address",
+			default: "127.0.0.1"
+		},
+		open: {
+			type: "boolean",
+			alias: "o",
+			description: "Open the browser after start",
+			default: false
+		},
+		watch: {
+			type: "boolean",
+			description: "Reload pages on file changes (use --no-watch to disable)",
+			default: true
+		}
+	},
+	async run({ args }) {
+		await startServer({
+			root: resolve(args.dir),
+			port: args.port === void 0 ? void 0 : parsePort(args.port),
+			defaultPort: DEFAULT_PORT,
+			host: args.host,
+			open: args.open,
+			watch: args.watch
+		});
+	}
+});
+function parsePort(value) {
+	const port = Number(value);
+	if (!Number.isInteger(port) || port < 1 || port > 65535) throw new Error(`Invalid port: ${value}`);
+	return port;
+}
+runMain(main);
+//#endregion
+export {};