@karimsa/mdxserve 0.0.0-stage → 0.2.0

package/dist/render-worker.js

@@ -0,0 +1,145 @@
+// src/rendering/render-worker.ts
+import fs from "node:fs";
+import path from "node:path";
+import { parentPort } from "node:worker_threads";
+import { ESModulesEvaluator, ModuleRunner } from "vite/module-runner";
+if (!parentPort) {
+  throw new Error("render-worker.ts must be run inside a node:worker_threads Worker");
+}
+var port = parentPort;
+function toPosix(filePath) {
+  return filePath.split(path.sep).join("/");
+}
+var nextInvokeId = 0;
+var pendingInvokes = /* @__PURE__ */ new Map();
+var transport = {
+  invoke(data) {
+    const invokeId = nextInvokeId++;
+    return new Promise((resolve) => {
+      pendingInvokes.set(invokeId, { resolve });
+      const message = { type: "invoke", invokeId, payload: data };
+      port.postMessage(message);
+    });
+  }
+};
+var runner = new ModuleRunner(
+  {
+    transport,
+    hmr: false,
+    // Have Node remap `Error.stack` frames through each module's sourcemap
+    // as they're generated, so an error thrown while evaluating a doc
+    // already points at the original .md/.mdx source — no separate
+    // `vite.ssrFixStacktrace()` pass needed (that was a main-thread-only
+    // API tied to the main-thread module graph). "node" is what Vite's own
+    // `createServerModuleRunner` resolves to by default in a real Node
+    // process (see `resolveSourceMapOptions` in dist/node/chunks/node.js);
+    // passing it explicitly here just makes that intentional rather than
+    // incidental.
+    sourcemapInterceptor: "node"
+  },
+  new ESModulesEvaluator()
+);
+var USE_LAYOUT_EFFECT_WARNING = "useLayoutEffect does nothing on the server";
+function withConsoleErrorFilter(fn) {
+  const original = console.error;
+  console.error = (...args) => {
+    const first = args[0];
+    if (typeof first === "string" && first.includes(USE_LAYOUT_EFFECT_WARNING)) return;
+    original.apply(console, args);
+  };
+  try {
+    return fn();
+  } finally {
+    console.error = original;
+  }
+}
+function firstFrameFor(stack, absPath) {
+  const escaped = absPath.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const re = new RegExp(`${escaped}:(\\d+):(\\d+)`);
+  for (const rawLine of stack.split("\n")) {
+    const match = re.exec(rawLine);
+    if (match) {
+      return { line: Number(match[1]), column: Number(match[2]) };
+    }
+  }
+  return {};
+}
+function pathForms(docPath) {
+  let real = docPath;
+  try {
+    real = fs.realpathSync.native(docPath);
+  } catch {
+  }
+  return [.../* @__PURE__ */ new Set([docPath, toPosix(docPath), real, toPosix(real)])];
+}
+function outcomeFromError(err, docPath) {
+  if (!(err instanceof Error)) {
+    return { ok: false, message: String(err) };
+  }
+  const stack = err.stack;
+  let line;
+  let column;
+  if (stack) {
+    for (const form of pathForms(docPath)) {
+      ({ line, column } = firstFrameFor(stack, form));
+      if (line !== void 0) break;
+    }
+  }
+  return { ok: false, message: err.message, stack, line, column };
+}
+async function handleRender(msg) {
+  const { id, ssrEntryPath, docPath } = msg;
+  let outcome;
+  try {
+    invalidateDocModules();
+    const [ssrEntry, docModule] = await Promise.all([
+      runner.import(toPosix(ssrEntryPath)),
+      runner.import(toPosix(docPath))
+    ]);
+    if (!docModule.default) {
+      outcome = { ok: false, message: `${docPath} has no default export.` };
+    } else {
+      withConsoleErrorFilter(() => ssrEntry.renderDoc(docModule.default));
+      outcome = { ok: true };
+    }
+  } catch (err) {
+    outcome = outcomeFromError(err, docPath);
+  }
+  const result = { type: "result", id, outcome };
+  port.postMessage(result);
+}
+var sharedIds;
+function invalidateDocModules() {
+  for (const [id, node] of runner.evaluatedModules.idToModuleMap) {
+    if (sharedIds?.has(id)) continue;
+    runner.evaluatedModules.invalidateModule(node);
+  }
+}
+async function handleWarm(msg) {
+  let outcome;
+  try {
+    await runner.import(toPosix(msg.ssrEntryPath));
+    sharedIds = new Set(runner.evaluatedModules.idToModuleMap.keys());
+    outcome = { ok: true };
+  } catch (err) {
+    outcome = err instanceof Error ? { ok: false, message: err.message, stack: err.stack } : { ok: false, message: String(err) };
+  }
+  const result = { type: "result", id: msg.id, outcome };
+  port.postMessage(result);
+}
+port.on("message", (msg) => {
+  if (msg.type === "invoke-response") {
+    const pending = pendingInvokes.get(msg.invokeId);
+    if (!pending) return;
+    pendingInvokes.delete(msg.invokeId);
+    pending.resolve(msg.response);
+    return;
+  }
+  if (msg.type === "warm") {
+    void handleWarm(msg);
+    return;
+  }
+  if (msg.type === "render") {
+    void handleRender(msg);
+  }
+});

package/package.json

@@ -1,6 +1,114 @@
 {
-  "name": "@karimsa/mdxserve",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+	"name": "@karimsa/mdxserve",
+	"version": "0.2.0",
+	"description": "Serve a directory of Markdown/MDX files, like `serve` but for docs",
+	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/karimsa/mdxserve.git"
+	},
+	"homepage": "https://github.com/karimsa/mdxserve#readme",
+	"bugs": "https://github.com/karimsa/mdxserve/issues",
+	"keywords": [
+		"markdown",
+		"mdx",
+		"docs",
+		"cli"
+	],
+	"type": "module",
+	"bin": "dist/cli.js",
+	"files": [
+		"dist",
+		"client",
+		"!client/design-ref",
+		"skills"
+	],
+	"scripts": {
+		"build": "tsx scripts/build.ts",
+		"registry": "tsx scripts/build-registry.ts",
+		"dev": "tsx scripts/build-registry.ts && tsx src/index.ts serve -w example",
+		"typecheck": "tsc --noEmit",
+		"format": "prettier --write .",
+		"format:check": "prettier --check .",
+		"lint": "oxlint",
+		"test": "vitest run",
+		"prepack": "yarn build",
+		"smoke": "bash scripts/smoke-pack.sh"
+	},
+	"packageManager": "yarn@4.18.0",
+	"engines": {
+		"node": ">=22.12"
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"dependencies": {
+		"@fontsource-variable/jetbrains-mono": "5.3.0",
+		"@fontsource-variable/manrope": "5.3.0",
+		"@mdx-js/mdx": "3.1.1",
+		"@mdx-js/react": "3.1.1",
+		"@mdx-js/rollup": "3.1.1",
+		"@tailwindcss/vite": "4.3.3",
+		"@tanstack/react-query": "5.101.4",
+		"@tippyjs/react": "4.2.6",
+		"@tiptap/core": "3.29.2",
+		"@tiptap/extension-image": "3.29.2",
+		"@tiptap/extension-list": "3.29.2",
+		"@tiptap/extension-table": "3.29.2",
+		"@tiptap/markdown": "3.29.2",
+		"@tiptap/pm": "3.29.2",
+		"@tiptap/react": "3.29.2",
+		"@tiptap/starter-kit": "3.29.2",
+		"@trpc/client": "11.18.0",
+		"@trpc/server": "11.18.0",
+		"@trpc/tanstack-react-query": "11.18.0",
+		"@vitejs/plugin-react": "6.0.5",
+		"commander": "15.0.0",
+		"date-fns": "4.4.0",
+		"diff": "9.0.0",
+		"framer-motion": "13.0.0",
+		"hast-util-to-html": "9.0.5",
+		"jotai": "2.20.2",
+		"lockfile": "1.0.4",
+		"lucide-react": "1.30.0",
+		"mdast-util-from-markdown": "2.0.3",
+		"mdast-util-mdx": "3.0.0",
+		"mdast-util-to-hast": "13.2.1",
+		"mdast-util-to-string": "4.0.0",
+		"mermaid": "10.9.8",
+		"micromark-extension-mdxjs": "3.0.0",
+		"minisearch": "7.2.0",
+		"node-sqlite3-wasm": "0.8.60",
+		"react": "19.2.8",
+		"react-dom": "19.2.8",
+		"react-hot-toast": "2.6.0",
+		"rehype-pretty-code": "0.14.5",
+		"rehype-slug": "6.0.0",
+		"remark-gfm": "4.0.1",
+		"shiki": "4.4.2",
+		"svg-pan-zoom": "3.6.2",
+		"tailwindcss": "4.3.3",
+		"tippy.js": "6.3.7",
+		"trash": "10.1.1",
+		"vfile-message": "4.0.3",
+		"vite": "8.2.1",
+		"zod": "4.4.3",
+		"zx": "8.8.5"
+	},
+	"devDependencies": {
+		"@types/lockfile": "1.0.4",
+		"@types/mdast": "4.0.4",
+		"@types/node": "26.2.0",
+		"@types/react": "19.2.18",
+		"@types/react-dom": "19.2.4",
+		"@types/svg-pan-zoom": "3.4.0",
+		"@yarnpkg/types": "4.0.1",
+		"esbuild": "0.28.2",
+		"fast-check": "4.9.0",
+		"oxlint": "1.77.0",
+		"prettier": "3.9.6",
+		"tsx": "4.23.12",
+		"typescript": "7.0.2",
+		"vitest": "4.1.10"
+	}
+}

package/skills/mdxserve/SKILL.md

@@ -0,0 +1,178 @@
+---
+name: mdxserve
+description: Use when writing or editing Markdown the user will read — docs, reports, plan files, notes — so the content renders as richly as possible in mdxserve while staying plain, portable Markdown.
+allowed-tools: Bash, Read, Grep, Glob
+---
+
+# Writing Markdown for mdxserve
+
+mdxserve serves a folder of `.md` / `.mdx` files as a browsable site: a file listing,
+rendered pages with syntax highlighting, mermaid diagrams, and a small library of builtin
+components. `.md` and `.mdx` are treated identically — both go through MDX, so the builtin
+components work in either.
+
+Markdown files have many readers besides mdxserve (GitHub, editors, other tools). The goal
+is the **simplest Markdown that is still visual**: reach for richer features only when they
+add clarity, and prefer features that degrade gracefully everywhere else.
+
+## The ladder — prefer lower rungs
+
+1. **Plain GitHub-flavored Markdown.** Headings, short paragraphs, lists, task lists, tables,
+   links, bold for the one thing that matters. Works everywhere. Most content should stop here.
+2. **Fenced code with a language tag.** Always tag the language (`ts`, `bash`, `json`, …). Add
+   fence meta when it helps the reader: `title="path/to/file.ts"`, `showLineNumbers`,
+   `{3-5}` to highlight lines. mdxserve renders these richly; other tools ignore the meta.
+3. **Mermaid diagrams** for flows, sequences, states, and architecture. mdxserve renders them as
+   pan/zoomable diagrams (with a toggle to the source); GitHub renders them too; everywhere else
+   they are still readable text. Prefer `flowchart` and `sequenceDiagram`; keep a diagram to
+   roughly 15 nodes or fewer — split larger ones. Never use mermaid's `pie`, `xychart-beta`,
+   `quadrantChart`, or `sankey-beta` — mdxserve doesn't render them, `mdxserve validate` reports an
+   error on them, and they draw data, which is `<Chart>`'s job (or a table). Mermaid is for a
+   flow or a shape, not a dataset.
+4. **Builtin components** (`<Callout>`, `<Tabs>`, `<Badge>`, `<Tooltip>`, `<Button>`, `<Diff>`, `<Card>`,
+   `<Kbd>`, `<FileTree>`, `<Chart>` (bar, line, area, histogram), `<Sparkline>`, `<Screenshot>`) only when they make
+   the content clearer: a warning the reader must not miss, per-OS or per-language variants of the
+   same instructions, a status label, a small dataset that's clearer as a shape than a table.
+   Outside mdxserve these show as raw tags, so use them sparingly and never for decoration.
+
+Don't: write raw HTML or inline styles; import or create custom components; use emoji as
+icons where a `Badge` or `Callout` would do; nest components for layout; put a component in a
+file the user will mainly read elsewhere (e.g. a README on GitHub) unless they asked.
+
+MDX is stricter than Markdown: a bare `{`, `}` or an unclosed `<tag>` in prose is a compile
+error, not literal text. Put such characters in backticks or escape them (`\{`).
+
+## Quick reference
+
+A table beats a list of "X: Y" lines:
+
+```md
+| Option   | Default | Effect                    |
+| -------- | ------- | ------------------------- |
+| `--port` | `4040`  | Port to listen on         |
+| `--host` | `127.0.0.1` | Interface to bind (`0.0.0.0` for LAN) |
+```
+
+Code with a title, line numbers, and highlighted lines:
+
+````md
+```ts title="src/server.ts" showLineNumbers {3-4}
+const server = http.createServer(handler);
+server.listen(port);
+// highlighted:
+console.log(`http://localhost:${port}`);
+```
+````
+
+A flow and a sequence:
+
+````md
+```mermaid
+flowchart LR
+  Browser -->|GET /docs/intro.md| Server
+  Server -->|compile via Vite| Page[Rendered page]
+```
+````
+
+````md
+```mermaid
+sequenceDiagram
+  participant U as User
+  participant S as Server
+  U->>S: click file
+  S-->>U: rendered page
+```
+````
+
+Task lists for progress; keep them flat:
+
+```md
+- [x] Read the existing router
+- [ ] Add the listing endpoint
+- [ ] Verify in the browser
+```
+
+## Builtin components
+
+Available in any `.md` or `.mdx` with no import. The registry — not this file — is the
+authoritative list of components and props. Before using a component for the first time in a
+session, check it:
+
+```bash
+mdxserve components search           # list every builtin with a one-line description
+mdxserve components search tab       # search by name, description, or prop name
+mdxserve components show Callout     # props table (types, defaults) + when to use
+mdxserve components show Callout --json
+```
+
+If `mdxserve` is not on your PATH, install it with `npm install -g @karimsa/mdxserve`.
+
+Minimal usage:
+
+```mdx
+<Callout tone="warn" title="Before you deploy">
+  Rotate the key first; the old one stops working immediately.
+</Callout>
+
+<Tabs>
+  <Tab label="macOS">`brew install foo`</Tab>
+  <Tab label="Linux">`apt install foo`</Tab>
+</Tabs>
+
+Status: <Badge tone="ok" dot>Online</Badge>
+
+The <Tooltip content="Mean time to recovery">MTTR</Tooltip> improved.
+
+<Button href="./setup.md">Continue to setup</Button>
+
+<Diff before={`port: 3000`} after={`port: 4000`} />
+
+Press <Kbd>⌘</Kbd><Kbd>K</Kbd> to open search.
+```
+
+Components contain ordinary Markdown: a `Tab` can hold lists, paragraphs, and code fences.
+Leave a blank line between a component tag and a Markdown block inside it so the block is
+parsed as Markdown.
+
+## Plan files
+
+Plans are read in mdxserve and in plain text. Use headings for phases, a task list per phase,
+a table for files-to-change, and at most one mermaid diagram (the architecture or the main
+flow, never a chart). Skip components in plans unless the user views plans only in mdxserve.
+
+## After writing
+
+After saving any `.md`/`.mdx` file, run `mdxserve validate <absolute path>`. It works even when
+no `mdxserve serve` is running. Read the first line and every diagnostic under it: it is
+`OK: <path>`, `OK with N warnings: <path>`, or a list of problems. Fix every `error` (MDX
+compile errors, unknown components, `render-error`) and any `unknown-prop` warning where a real
+prop was intended, then re-run until the first line is `OK` with only intended warnings. The
+exit code is 1 when any error was reported. Compile errors and unknown components blank the
+page or throw at render time — invisible until a human opens it — so this is not optional.
+
+`validate` also renders the doc server-side and reports any throw as a `render-error` — this is
+what catches a component that compiles fine but blanks the page (e.g. a stray identifier that
+only breaks at render time). Read the line after the diagnostics: `Rendered OK`, or
+`Not rendered (…)` when no `mdxserve serve` is reachable, meaning only the static checks
+(compile, unknown component/prop) ran. Treat that as a weaker pass and mention it to the user
+rather than treating `OK` alone as a full clean bill of health. Even with `Rendered OK`, errors
+thrown inside a `useEffect`/`useLayoutEffect` and hydration mismatches are never caught — those
+stay browser-only. `hint:` lines are advisory and never affect the result. When scripting, use
+`--json` and check the `rendered` field.
+
+If `validate` says the file is outside every served directory, or `mdxserve search` /
+`mdxserve docs` report that no folders are served, run `mdxserve roots list`, then
+`mdxserve roots add <absolute dir>` with the doc's folder.
+
+If `mdxserve` is not installed, tell the user the file was not validated; don't skip this
+silently.
+
+## Before saving
+
+- Every code fence has a language tag; titles and highlights only where they help.
+- Any diagram is a mermaid fence, small enough to read at a glance, and none of them draws a
+  chart (no `pie`, `xychart-beta`, `quadrantChart`, `sankey-beta` — use `<Chart>` or a table).
+- No raw HTML, styles, imports, or custom components.
+- Any builtin component used was checked with `components show` and genuinely clarifies.
+- The file still reads well as plain text.
+- `mdxserve validate` printed `OK`, ideally `Rendered OK`.