@docubook/flame 1.2.1 → 1.3.1

package/.docu/node/server.ts

@@ -1,22 +1,20 @@
-import { statSync } from "node:fs";
-import { readFile } from "node:fs/promises";
-import { resolve, join } from "node:path";
 import { watch } from "node:fs";
-import React from "react";
-import { renderToString } from "react-dom/server";
-import { getContentType } from "./utils";
-import { compileMdx } from "./mdx";
-import { DOCS_DIR, DIST_DIR, PAGES_DIR, PROJECT_ROOT, loadDocuConfig } from "./paths";
-import DocsPage from "../pages/docs/[[...slug]]";
-import NotFoundPage from "../pages/404";
-import IndexPage from "../pages/index";
-import { DocsLayout } from "../components/DocsLayout";
+import { DOCS_DIR, PAGES_DIR, loadDocuConfig } from "./paths";
+import { loadPlugins } from "./plugin-loader";
+import { BuildPluginBuilder } from "./plugin-builder";
 import { buildClientBundle, computeInlineThemeCss } from "./hydrate";
 import { generateSearchIndex } from "./search-indexer";
 import { logger } from "./logger";
 import { initSentry, captureException } from "./sentry";
-import { SECURITY_HEADERS, generateNonce, isPathSafe, isSlugSafe, htmlResponse } from "./security";
-import { htmlShell as createHtmlShell, hmrScript } from "./html";
+import {
+  serveStatic,
+  handleDocsIndex,
+  handleDocsRoute,
+  handleIndex,
+  handleNotFound,
+  serverErrorResponse,
+  type ServerState,
+} from "./server-routes";
 
 const docuConfig = loadDocuConfig();
 
@@ -40,6 +38,23 @@ logger.indexDone(records, Math.round(performance.now() - t));
 
 logger.routes();
 
+// Plugin setup — all hooks active (onLoad, remark/rehype, frontmatter, head/body, html transform, handleRequest)
+const hasPlugins = !!docuConfig.plugins?.length;
+const builder = hasPlugins ? new BuildPluginBuilder(docuConfig) : null;
+if (hasPlugins && builder) {
+  const plugins = await loadPlugins(docuConfig.plugins!);
+  for (const plugin of plugins) {
+    await plugin.setup(builder);
+  }
+}
+
+const state: ServerState = {
+  docuConfig,
+  assetManifest,
+  inlineThemeCss,
+  builder,
+};
+
 let router: InstanceType<typeof Bun.FileSystemRouter> | null = null;
 try {
   router = new Bun.FileSystemRouter({
@@ -76,180 +91,6 @@ process.on("SIGTERM", () => {
   process.exit(0);
 });
 
-function createHtmlResponse(
-  title: string,
-  description: string,
-  body: string,
-  status = 200
-): Response {
-  const nonce = generateNonce();
-  const favicon = docuConfig.meta?.favicon || "/favicon.ico";
-  const html = createHtmlShell({
-    title,
-    description,
-    body,
-    favicon,
-    css: assetManifest.css,
-    js: assetManifest.js,
-    nonce,
-    extraScripts: hmrScript(nonce),
-    themeCss: inlineThemeCss,
-  });
-  return htmlResponse(html, nonce, status, process.env.NODE_ENV !== "production");
-}
-
-async function getDocsForSlug(slug: string) {
-  if (!isSlugSafe(slug, DOCS_DIR)) return null;
-
-  const paths = [
-    join(DOCS_DIR, slug, "index.mdx"),
-    join(DOCS_DIR, `${slug}.mdx`),
-    join(DOCS_DIR, slug, "index.md"),
-    join(DOCS_DIR, `${slug}.md`),
-  ];
-
-  let filePath: string | null = null;
-  let raw: string | null = null;
-  for (const p of paths) {
-    if (!p.startsWith(DOCS_DIR)) continue;
-    try {
-      raw = await readFile(p, "utf-8");
-      filePath = p;
-      break;
-    } catch (err) {
-      if ((err as NodeJS.ErrnoException).code !== "ENOENT") throw err;
-    }
-  }
-  if (!filePath || !raw) return null;
-
-  const relPath = filePath.replace(PROJECT_ROOT + "/", "");
-  const result = await compileMdx(raw, relPath);
-
-  return {
-    content: result.content,
-    compiledSource: result.compiledSource,
-    frontmatter: result.frontmatter,
-    tocs: result.tocs,
-    filePath: relPath,
-  };
-}
-
-async function handleDocsIndex(): Promise<Response> {
-  const doc = await getDocsForSlug("");
-  if (!doc) return renderPage(NotFoundPage, "404 - Not Found", "", 404);
-
-  const title = doc.frontmatter.title || "Docs";
-  const description = doc.frontmatter.description || "";
-
-  const page = React.createElement(
-    DocsLayout,
-    { repoUrl: docuConfig.repo?.url, pathname: "/docs" },
-    React.createElement(DocsPage, {
-      slug: [],
-      title,
-      description,
-      date: doc.frontmatter.date,
-      content: doc.content,
-      tocs: doc.tocs,
-      filePath: doc.filePath,
-      repoUrl: docuConfig.repo?.url,
-      compiledSource: doc.compiledSource,
-    })
-  );
-
-  const body = renderToString(page);
-  return createHtmlResponse(title, description, body);
-}
-
-async function handleDocsRoute(slug: string[]): Promise<Response> {
-  const path = slug.join("/");
-
-  const doc = await getDocsForSlug(path);
-  if (!doc) return renderPage(NotFoundPage, "404 - Not Found", "", 404);
-
-  const title = doc.frontmatter.title || path;
-  const description = doc.frontmatter.description || "";
-
-  const page = React.createElement(
-    DocsLayout,
-    { repoUrl: docuConfig.repo?.url, pathname: `/docs/${path}` },
-    React.createElement(DocsPage, {
-      slug,
-      title,
-      description,
-      date: doc.frontmatter.date,
-      content: doc.content,
-      tocs: doc.tocs,
-      filePath: doc.filePath,
-      repoUrl: docuConfig.repo?.url,
-      compiledSource: doc.compiledSource,
-    })
-  );
-
-  const body = renderToString(page);
-  return createHtmlResponse(title, description, body);
-}
-
-function renderPage(
-  Component: React.ComponentType<Record<string, unknown>>,
-  title: string,
-  description: string,
-  status: number,
-  props: Record<string, unknown> = {}
-): Response {
-  const page = React.createElement(
-    DocsLayout,
-    { repoUrl: docuConfig.repo?.url, pathname: "/docs" },
-    React.createElement(Component, props)
-  );
-  const body = renderToString(page);
-  return createHtmlResponse(title, description, body, status);
-}
-
-function handleIndex(): Response {
-  const page = React.createElement(IndexPage);
-  const body = renderToString(page);
-  return createHtmlResponse(
-    docuConfig.meta?.title || "DocuBook",
-    docuConfig.meta?.description || "",
-    body
-  );
-}
-
-function serveStatic(pathname: string): Response | null {
-  if (!isPathSafe(pathname, DIST_DIR)) return null;
-  const decoded = decodeURIComponent(pathname);
-  const assetPath = resolve(DIST_DIR, decoded.slice(1));
-  try {
-    const s = statSync(assetPath);
-    if (s.isFile()) {
-      return new Response(Bun.file(assetPath), {
-        headers: { "Content-Type": getContentType(pathname) },
-      });
-    }
-  } catch (err) {
-    if ((err as NodeJS.ErrnoException).code !== "ENOENT") throw err;
-  }
-
-  if (decoded.startsWith("/docs/assets/")) {
-    const docsAsset = resolve(DOCS_DIR, "assets", decoded.replace("/docs/assets/", ""));
-    const docsAssetsDir = resolve(DOCS_DIR, "assets");
-    const docsAssetsDirSlash = docsAssetsDir.endsWith("/") ? docsAssetsDir : docsAssetsDir + "/";
-    if (docsAsset !== docsAssetsDir && !docsAsset.startsWith(docsAssetsDirSlash)) return null;
-    try {
-      const s = statSync(docsAsset);
-      if (s.isFile()) {
-        return new Response(Bun.file(docsAsset), {
-          headers: { "Content-Type": getContentType(pathname) },
-        });
-      }
-    } catch (err) {
-      if ((err as NodeJS.ErrnoException).code !== "ENOENT") throw err;
-    }
-  }
-  return null;
-}
-
 const server = Bun.serve({
   port: PORT,
   development: true,
@@ -260,6 +101,22 @@ const server = Bun.serve({
     const pathname = url.pathname;
     const startTime = performance.now();
 
+    if (builder) {
+      const pluginResponse = await builder.runHandleRequest(req, {
+        port: server.port,
+        hostname: server.hostname,
+      });
+      if (pluginResponse) {
+        logger.request(
+          req.method,
+          pathname,
+          pluginResponse.status,
+          Math.round(performance.now() - startTime)
+        );
+        return pluginResponse;
+      }
+    }
+
     try {
       if (pathname === "/__hmr") {
         const stream = new ReadableStream({
@@ -296,19 +153,19 @@ const server = Bun.serve({
           const slug = slugParam ? slugParam.split("/") : [];
 
           if (slug.length === 0) {
-            response = await handleDocsIndex();
+            response = await handleDocsIndex(state);
           } else {
-            response = await handleDocsRoute(slug);
+            response = await handleDocsRoute(slug, state);
           }
         } else if (routeName === "/404") {
-          response = renderPage(NotFoundPage, "404 - Not Found", "", 404);
+          response = handleNotFound(state);
         } else if (routeName === "/") {
-          response = handleIndex();
+          response = handleIndex(state);
         } else {
-          response = renderPage(NotFoundPage, "404 - Not Found", "", 404);
+          response = handleNotFound(state);
         }
       } else {
-        response = renderPage(NotFoundPage, "404 - Not Found", "", 404);
+        response = handleNotFound(state);
       }
 
       logger.request(
@@ -320,45 +177,15 @@ const server = Bun.serve({
       return response;
     } catch (err) {
       captureException(err, { method: req.method, pathname });
-      const message = err instanceof Error ? err.message : String(err);
-      const stack = err instanceof Error ? err.stack || "" : "";
       logger.request(req.method, pathname, 500, Math.round(performance.now() - startTime));
-      const html = `<!DOCTYPE html><html><head><meta charset="utf-8"><title>Error</title>
-<style>body{margin:0;padding:2rem;font-family:ui-monospace,monospace;background:#1a1a2e;color:#e0e0e0}
-h1{color:#ff6b6b}pre{background:#0d0d1a;border:1px solid #333;border-radius:8px;padding:1.5rem;overflow-x:auto;font-size:14px;line-height:1.6;white-space:pre-wrap;word-break:break-word}
-.msg{color:#ff6b6b;font-weight:bold}</style></head><body>
-<h1>🔥 Server Error</h1>
-<pre><span class="msg">${Bun.escapeHTML(message)}</span>\n\n${Bun.escapeHTML(stack)}</pre></body></html>`;
-      return new Response(html, {
-        status: 500,
-        headers: {
-          "Content-Type": "text/html",
-          ...SECURITY_HEADERS,
-          "Content-Security-Policy": "default-src 'none'; style-src 'unsafe-inline'",
-        },
-      });
+      return serverErrorResponse(err);
     }
   },
 
   error(error) {
     console.error(error);
     captureException(error);
-    const msg = Bun.escapeHTML(error?.message || "Unknown error");
-    const stack = Bun.escapeHTML(error?.stack || "");
-    const html = `<!DOCTYPE html><html><head><meta charset="utf-8"><title>Error</title>
-<style>body{margin:0;padding:2rem;font-family:ui-monospace,monospace;background:#1a1a2e;color:#e0e0e0}
-h1{color:#ff6b6b}pre{background:#0d0d1a;border:1px solid #333;border-radius:8px;padding:1.5rem;overflow-x:auto;font-size:14px;line-height:1.6;white-space:pre-wrap;word-break:break-word}
-.msg{color:#ff6b6b;font-weight:bold}</style></head><body>
-<h1>🔥 Server Error</h1>
-<pre><span class="msg">${msg}</span>\n\n${stack}</pre></body></html>`;
-    return new Response(html, {
-      status: 500,
-      headers: {
-        "Content-Type": "text/html",
-        ...SECURITY_HEADERS,
-        "Content-Security-Policy": "default-src 'none'; style-src 'unsafe-inline'",
-      },
-    });
+    return serverErrorResponse(error);
   },
 });
 

package/.docu/node/types.ts

@@ -67,6 +67,7 @@ export interface HomeConfig {
 }
 
 import type { ThemeConfig } from "@docubook/themes-colors";
+import type { PluginEntry } from "./plugin";
 
 export interface DocuConfig {
   meta: DocuMeta;
@@ -78,6 +79,8 @@ export interface DocuConfig {
   themes?: {
     colors: ThemeConfig;
   };
+  /** List of DocuBook plugins to load. Empty by default — no-op when absent. */
+  plugins?: PluginEntry[];
 }
 
 export interface BuildCache {

package/.docu/node/utils.ts

@@ -1,5 +1,45 @@
 export { cn, parseDate, formatDate, formatDate2 } from "@docubook/core";
 
+import { readdir, stat } from "node:fs/promises";
+import { join } from "node:path";
+
+export interface ScannedMdxFile {
+  path: string;
+  absPath: string;
+  mtime: number;
+}
+
+/**
+ * Scan a directory recursively for MDX/MD files.
+ * Skips "assets" directories, hidden directories (dot-prefixed), and root-level index.mdx.
+ * Shared between build.ts and search-indexer.ts.
+ */
+export async function scanMdxFiles(dir: string, baseDir = ""): Promise<ScannedMdxFile[]> {
+  const files: ScannedMdxFile[] = [];
+  const entries = await readdir(dir, { withFileTypes: true });
+
+  for (const entry of entries) {
+    const fullPath = join(dir, entry.name);
+    const relativePath = baseDir ? `${baseDir}/${entry.name}` : entry.name;
+
+    if (entry.isDirectory()) {
+      if (entry.name === "assets" || entry.name.startsWith(".")) continue;
+      files.push(...(await scanMdxFiles(fullPath, relativePath)));
+    } else if (entry.name.endsWith(".mdx") || entry.name.endsWith(".md")) {
+      if (entry.name === "index.mdx" && !baseDir) continue;
+      const stats = await stat(fullPath);
+      let path = relativePath.replace(/\.(mdx|md)$/, "");
+
+      if (/\/index$/.test(path)) {
+        path = path.replace(/\/index$/, "");
+      }
+      files.push({ path, absPath: fullPath, mtime: stats.mtimeMs });
+    }
+  }
+
+  return files;
+}
+
 export function isExternalUrl(url: string): boolean {
   return /^(https?:\/\/|\/\/)/.test(url);
 }
@@ -40,9 +80,26 @@ export async function getGitLastModifiedBatch(filePaths: string[]): Promise<Map<
   const result = new Map<string, string>();
   if (filePaths.length === 0) return result;
 
+  // Filter and validate paths — same guard as getGitLastModified
+  const safePaths: string[] = [];
+  for (const fp of filePaths) {
+    const cleanPath = fp.replace(/^\//, "");
+    if (
+      !cleanPath ||
+      !/^[a-zA-Z0-9\-_/.\s]+$/.test(cleanPath) ||
+      /(^|\/)\.\.($|\/)/.test(cleanPath)
+    ) {
+      console.warn(`[utils] getGitLastModifiedBatch: skipping invalid path "${fp}"`);
+      continue;
+    }
+    safePaths.push(cleanPath);
+  }
+
+  if (safePaths.length === 0) return result;
+
   try {
     const proc = Bun.spawn(
-      ["git", "log", "--format=%cI", "--name-only", "--diff-filter=ACMR", ...filePaths],
+      ["git", "log", "--format=%cI", "--name-only", "--diff-filter=ACMR", ...safePaths],
       { stderr: "ignore" }
     );
     const text = await new Response(proc.stdout).text();

package/.docu/pages/docs/[[...slug]].tsx

@@ -62,7 +62,9 @@ export default function DocsPage({
               <script
                 id="mdx-compiled-source"
                 type="application/json"
-                dangerouslySetInnerHTML={{ __html: JSON.stringify(compiledSource) }}
+                dangerouslySetInnerHTML={{
+                  __html: JSON.stringify(compiledSource).replace(/<\//g, "\\u003C/"),
+                }}
               />
             )}
             <div className="border-base-300 my-8 flex items-center border-b-2 border-dashed">

package/README.md

@@ -282,6 +282,54 @@ Reference in MDX:
 
 ---
 
+## Plugins
+
+Flame supports a plugin system to extend the build pipeline and dev server. Plugins can inject head/body HTML, transform content, add remark/rehype plugins, intercept API requests, and more.
+
+### Usage in `docu.json`
+
+```json
+{
+  "plugins": [
+    "@docubook/plugin-sitemap",
+    ["./plugins/analytics", { "id": "G-XXXXXXX" }]
+  ]
+}
+```
+
+String = npm package or relative path. Tuple `["name", opts]` = factory with options.
+
+### Available Hooks
+
+|               Hook                |                      Purpose                      |
+| --------------------------------- | ------------------------------------------------- |
+| `onStart`                         | Validate config before build                      |
+| `onEnd`                           | Generate files after build (sitemap, RSS)         |
+| `onLoad`                          | Transform raw file content before MDX compilation |
+| `transformFrontmatter`            | Mutate frontmatter (reading time, SEO)            |
+| `transformHtml`                   | Modify final HTML before writing to disk          |
+| `injectHead` / `injectBody`       | Inject HTML into `<head>` or before `</body>`     |
+| `remarkPlugins` / `rehypePlugins` | Add remark/rehype plugins to the MDX pipeline     |
+| `handleRequest`                   | Intercept dev server requests (custom API)        |
+
+### Quick Example
+
+```typescript
+import type { DocuBookPlugin } from "@docubook/flame";
+
+export default {
+  name: "reading-time",
+  setup(build) {
+    build.transformFrontmatter((fm, ctx) => ({
+      ...fm,
+      readingTime: `${Math.ceil((ctx.content ?? "").split(/\s+/).length / 200)} min read`,
+    }));
+  },
+} satisfies DocuBookPlugin;
+```
+
+See the [full plugin guide](docs/getting-started/plugins.mdx) for step-by-step instructions.
+
 ## Architecture
 
 - **Bun** — runtime, bundler, file watcher

package/docu.schema.json

@@ -118,6 +118,34 @@
       "description": "Documentation navigation routes. Leave empty for auto-detection from docs/ folder.",
       "items": { "$ref": "#/$defs/route" }
     },
+    "plugins": {
+      "type": "array",
+      "description": "List of DocuBook plugins to load",
+      "items": {
+        "oneOf": [
+          {
+            "type": "string",
+            "description": "Plugin package name or relative path (e.g. @docubook/plugin-sitemap)"
+          },
+          {
+            "type": "array",
+            "description": "Plugin package name with factory options",
+            "items": [
+              {
+                "type": "string",
+                "description": "Plugin package name"
+              },
+              {
+                "type": "object",
+                "description": "Plugin factory options"
+              }
+            ],
+            "minItems": 2,
+            "maxItems": 2
+          }
+        ]
+      }
+    },
     "themes": {
       "type": "object",
       "description": "Color themes configuration. Use preset name or custom hex values.",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docubook/flame",
-  "version": "1.2.1",
+  "version": "1.3.1",
   "description": "A blazing-fast React + MDX framework powered by Bun, built for modern documentation experiences.",
   "type": "module",
   "bin": {
@@ -34,7 +34,7 @@
     "react",
     "react-dom"
   ],
-  "homepage": "https://docubook.pro/",
+  "homepage": "https://github.com/DocuBook/docubook/tree/main/packages/flame",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/DocuBook/docubook.git",
@@ -51,13 +51,13 @@
     "lucide-react": "^1.14.0",
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
-    "@docubook/mdx-content": "^3.2.1",
-    "@docubook/core": "^1.7.0",
-    "@docubook/themes-colors": "^0.10.1",
-    "@docubook/ui-react": "^0.1.3"
+    "@docubook/mdx-content": "^3.2.2",
+    "@docubook/core": "^1.7.2",
+    "@docubook/themes-colors": "^0.10.2",
+    "@docubook/ui-react": "^0.1.4"
   },
   "peerDependencies": {
-    "@sentry/bun": "^9.0.0"
+    "@sentry/bun": "^10.0.0"
   },
   "peerDependenciesMeta": {
     "@sentry/bun": {