@docubook/flame 1.2.1 → 1.3.0

package/.docu/node/plugin.ts

@@ -0,0 +1,265 @@
+import type { Pluggable } from "unified";
+import type { DocuConfig } from "./types";
+
+// ─── Config Types ───────────────────────────────────────
+
+/**
+ * Plugin entry in `docu.json` config.
+ * - `string`: plugin package name or relative path (no options)
+ * - `[string, object]`: plugin package name + factory options
+ *
+ * @example "@docubook/plugin-sitemap"
+ * @example ["@docubook/plugin-search-algolia", { appId: "xxx" }]
+ */
+export type PluginEntry = string | [string, Record<string, unknown>];
+
+// ─── Context Types ──────────────────────────────────────
+
+/**
+ * Context passed to content-transform hooks for a single page.
+ */
+export interface PageContext {
+  /** Relative slug path: "getting-started/introduction" */
+  slug: string;
+  /** Absolute file path on disk */
+  filePath: string;
+  /** Parsed frontmatter metadata */
+  frontmatter: Record<string, unknown>;
+  /** Raw MDX/MD content (only available in `transformFrontmatter` when enabled) */
+  content?: string;
+  /** Resolved site configuration */
+  config: DocuConfig;
+}
+
+/**
+ * Metadata for a single built page, aggregated and passed to `onEnd`.
+ */
+export interface PageMeta {
+  /** URL slug: "getting-started/introduction" */
+  slug: string;
+  /** Page title from frontmatter or filename */
+  title: string;
+  /** Absolute source file path */
+  filePath: string;
+  /** Relative output path under dist */
+  outputPath: string;
+}
+
+/**
+ * Context passed to the dev server request handler.
+ */
+export interface DevServerContext {
+  /** Dev server port */
+  port: number;
+  /** Dev server hostname */
+  hostname: string;
+}
+
+// ─── PluginBuilder Interface ────────────────────────────
+
+/**
+ * Builder object passed to each plugin's `setup()` function.
+ *
+ * Follows Bun's `PluginBuilder` convention:
+ * - Plugins register lifecycle callbacks through typed methods
+ * - Callbacks are executed sequentially in registration order
+ * - `config` provides read-only access to the resolved build config
+ */
+export interface PluginBuilder {
+  /** Resolved DocuBook configuration (read-only after setup phase). */
+  config: DocuConfig;
+
+  // ─── Build Lifecycle ───────────────────────────────────
+
+  /**
+   * Register a callback to run once before the build starts.
+   * Use for: validating config, initializing resources, fetching remote data.
+   *
+   * @param callback - Receives the resolved config. May return a Promise.
+   *
+   * @example
+   * build.onStart((config) => {
+   *   if (!config.meta.baseURL) throw new Error("baseURL required");
+   * });
+   */
+  onStart(callback: (config: DocuConfig) => void | Promise<void>): void;
+
+  /**
+   * Register a callback to run once after all pages are built.
+   * Use for: generating sitemaps, RSS feeds, manifests, post-build reports.
+   *
+   * @param callback - Receives config and aggregated page metadata. May return a Promise.
+   *
+   * @example
+   * build.onEnd((config, pages) => {
+   *   const xml = generateSitemap(pages, config.meta.baseURL);
+   *   await Bun.write(join(DIST_DIR, "sitemap.xml"), xml);
+   * });
+   */
+  onEnd(callback: (config: DocuConfig, pages: PageMeta[]) => void | Promise<void>): void;
+
+  // ─── Content Transform ─────────────────────────────────
+
+  /**
+   * Register a callback to transform raw file content before MDX compilation.
+   * Similar to Bun's `build.onLoad()` — filtered by file path pattern.
+   *
+   * Use for: preprocessing MDX/MD, injecting frontmatter, code transformations.
+   *
+   * @param args.filter - RegExp matched against the file's relative path
+   * @param args.namespace - Optional namespace prefix (reserved for future use)
+   * @param callback - Receives file path and raw content. Return new contents or void.
+   *
+   * @example
+   * build.onLoad({ filter: /\.md$/ }, ({ path, content }) => {
+   *   return { contents: `<!-- auto-processed -->\n${content}` };
+   * });
+   */
+  onLoad(
+    args: { filter: RegExp; namespace?: string },
+    callback: (args: {
+      path: string;
+      content: string;
+    }) => { contents?: string; loader?: "js" | "ts" | "mdx" } | void
+  ): void;
+
+  /**
+   * Register a callback to mutate frontmatter before MDX compilation.
+   * Callbacks are chained: the return value of one is passed as input to the next.
+   *
+   * Use for: injecting reading-time, validating fields, adding computed metadata.
+   *
+   * @param callback - Receives frontmatter object and page context. Return mutated frontmatter or void.
+   *
+   * @example
+   * build.transformFrontmatter((fm, ctx) => {
+   *   const wordCount = ctx.content!.split(/\s+/).length;
+   *   return { ...fm, readingTime: `${Math.ceil(wordCount / 200)} min read` };
+   * });
+   */
+  transformFrontmatter(
+    callback: (
+      frontmatter: Record<string, unknown>,
+      context: Pick<PageContext, "slug" | "filePath" | "content">
+    ) => Record<string, unknown> | void
+  ): void;
+
+  /**
+   * Register a callback to transform the final HTML string per page.
+   * This is the **last** hook before the HTML is written to disk.
+   *
+   * Use for: post-processing, minification, link rewriting, custom injection.
+   *
+   * @param callback - Receives HTML string and full page context. Return modified HTML.
+   *
+   * @example
+   * build.transformHtml((html, ctx) => {
+   *   return html.replace(/https?:\/\/old-domain\.com\//g, "/");
+   * });
+   */
+  transformHtml(callback: (html: string, context: PageContext) => string | Promise<string>): void;
+
+  // ─── Head & Script Injection ───────────────────────────
+
+  /**
+   * Register a callback that returns HTML strings to inject inside `<head>`.
+   * Results from all plugins are merged and deduplicated.
+   *
+   * Use for: analytics snippets, meta tags, stylesheet links.
+   *
+   * @param callback - Returns a single HTML string or an array. Called once per page.
+   *
+   * @example
+   * build.injectHead(() => {
+   *   return `<script async src="https://www.googletagmanager.com/gtag/js?id=G-XXX"></script>`;
+   * });
+   */
+  injectHead(callback: (context: PageContext) => string | string[]): void;
+
+  /**
+   * Register a callback that returns HTML strings to inject before `</body>`.
+   * Results from all plugins are merged and deduplicated.
+   *
+   * Use for: chat widgets, live-script loaders, deferred scripts.
+   *
+   * @param callback - Returns a single HTML string or an array. Called once per page.
+   */
+  injectBody(callback: (context: PageContext) => string | string[]): void;
+
+  // ─── MDX Pipeline Extension ────────────────────────────
+
+  /**
+   * Register additional remark (Markdown) plugins for the MDX compilation pipeline.
+   * Plugins from all plugins are merged and applied **after** the default set.
+   *
+   * @example
+   * build.remarkPlugins(() => [require("remark-custom-heading-id")]);
+   */
+  remarkPlugins(callback: () => Pluggable[]): void;
+
+  /**
+   * Register additional rehype (HTML) plugins for the MDX compilation pipeline.
+   * Plugins from all plugins are merged and applied **after** the default set.
+   *
+   * @example
+   * build.rehypePlugins(() => [require("rehype-autolink-headings")]);
+   */
+  rehypePlugins(callback: () => Pluggable[]): void;
+
+  // ─── Dev Server ────────────────────────────────────────
+
+  /**
+   * Register a callback to intercept incoming requests during development.
+   * The **first** callback to return a `Response` short-circuits all subsequent handlers.
+   *
+   * Use for: custom API routes, mock data endpoints, redirects, request logging.
+   *
+   * @param callback - Receives the Request and dev server context. Return Response or void.
+   *
+   * @example
+   * build.handleRequest((req, ctx) => {
+   *   if (new URL(req.url).pathname === "/api/status") {
+   *     return new Response(JSON.stringify({ ok: true }), {
+   *       headers: { "Content-Type": "application/json" },
+   *     });
+   *   }
+   * });
+   */
+  handleRequest(
+    callback: (
+      req: Request,
+      context: DevServerContext
+    ) => Response | void | Promise<Response | void>
+  ): void;
+}
+
+// ─── Plugin Interface ────────────────────────────────────
+
+/**
+ * A DocuBook plugin.
+ *
+ * Follows Bun's `BunPlugin` convention:
+ * - `name`: unique identifier for the plugin
+ * - `setup(build)`: called once to register lifecycle hooks via the provided `PluginBuilder`
+ *
+ * @example
+ * const myPlugin: DocuBookPlugin = {
+ *   name: "analytics",
+ *   setup(build) {
+ *     build.injectHead(() => `<script>...</script>`);
+ *     build.onEnd(() => console.log("build done"));
+ *   },
+ * };
+ */
+export interface DocuBookPlugin {
+  /** Unique plugin name. Used in error messages and logs. */
+  name: string;
+
+  /**
+   * Called once after all plugins are loaded and before the build begins.
+   * Register all lifecycle hooks via the `build` (PluginBuilder) parameter.
+   *
+   * @param build - The PluginBuilder instance for this build session.
+   */
+  setup(build: PluginBuilder): void | Promise<void>;
+}

package/.docu/node/search-indexer.ts

@@ -11,10 +11,11 @@
  *   content = first paragraph/list items after each heading
  */
 
-import { readFile, writeFile, readdir, mkdir } from "node:fs/promises";
+import { readFile, writeFile, mkdir } from "node:fs/promises";
 import { resolve, join } from "node:path";
 import { extractFrontmatterWithContent } from "@docubook/core";
 import { DOCS_DIR, ASSETS_DIR, loadDocuConfig } from "./paths";
+import { scanMdxFiles } from "./utils";
 
 const docuConfig = loadDocuConfig();
 
@@ -183,29 +184,6 @@ export function extractRecords(filePath: string, raw: string): SearchRecord[] {
   return records;
 }
 
-async function scanMdxFiles(dir: string, base = ""): Promise<{ path: string; absPath: string }[]> {
-  const files: { path: string; absPath: string }[] = [];
-  const entries = await readdir(dir, { withFileTypes: true });
-
-  for (const entry of entries) {
-    const fullPath = join(dir, entry.name);
-    const relPath = base ? `${base}/${entry.name}` : entry.name;
-
-    if (entry.isDirectory()) {
-      if (entry.name === "assets" || entry.name.startsWith(".")) continue;
-      files.push(...(await scanMdxFiles(fullPath, relPath)));
-    } else if (entry.name.endsWith(".mdx") || entry.name.endsWith(".md")) {
-      if (entry.name === "index.mdx" && !base) continue;
-      let path = relPath.replace(/\.(mdx|md)$/, "");
-      if (/\/index$/.test(path)) {
-        path = path.replace(/\/index$/, "");
-      }
-      files.push({ path, absPath: fullPath });
-    }
-  }
-  return files;
-}
-
 export async function generateSearchIndex(docsDir?: string, outputDir?: string): Promise<number> {
   const docs = resolve(docsDir || DOCS_DIR);
   const dist = resolve(outputDir || ASSETS_DIR);

package/.docu/node/security.ts

@@ -1,4 +1,5 @@
 import { resolve } from "node:path";
+import { realpathSync } from "node:fs";
 
 export const SECURITY_HEADERS: Record<string, string> = {
   "Strict-Transport-Security": "max-age=63072000; includeSubDomains; preload",
@@ -32,18 +33,58 @@ export function isPathSafe(pathname: string, baseDir: string): boolean {
   const decoded = decodeURIComponent(pathname);
   const resolved = resolve(baseDir, decoded.slice(1));
   const baseDirSlash = baseDir.endsWith("/") ? baseDir : baseDir + "/";
-  return resolved === baseDir || resolved.startsWith(baseDirSlash);
+  if (!(resolved === baseDir || resolved.startsWith(baseDirSlash))) {
+    return false;
+  }
+
+  if (resolved === baseDir) return true;
+  try {
+    const real = realpathSync(resolved);
+    const realBase = realpathSync(baseDir);
+    const realBaseDirSlash = realBase.endsWith("/") ? realBase : realBase + "/";
+    return real.startsWith(realBaseDirSlash);
+  } catch (err) {
+    const nodeErr = err as NodeJS.ErrnoException;
+    if (nodeErr.code === "ENOENT") {
+      return true;
+    }
+    console.error(
+      `[security] isPathSafe error for pathname="${pathname}": ${nodeErr.message} (code=${nodeErr.code})`
+    );
+    return false;
+  }
 }
 
 export function isSlugSafe(slug: string, docsDir: string): boolean {
   const resolved = resolve(docsDir, slug);
   const docsDirSlash = docsDir.endsWith("/") ? docsDir : docsDir + "/";
-  return resolved === docsDir || resolved.startsWith(docsDirSlash);
+  if (!(resolved === docsDir || resolved.startsWith(docsDirSlash))) {
+    return false;
+  }
+
+  if (resolved === docsDir) return true;
+  try {
+    const real = realpathSync(resolved);
+    const realDocsDir = realpathSync(docsDir);
+    const realDocsDirSlash = realDocsDir.endsWith("/") ? realDocsDir : realDocsDir + "/";
+    return real.startsWith(realDocsDirSlash);
+  } catch (err) {
+    const nodeErr = err as NodeJS.ErrnoException;
+    if (nodeErr.code === "ENOENT") {
+      return true;
+    }
+    console.error(
+      `[security] isSlugSafe error for slug="${slug}": ${nodeErr.message} (code=${nodeErr.code})`
+    );
+    return false;
+  }
 }
 
 export function injectNonce(html: string, nonce: string): string {
   return html.replace(/<script\b(?![^>]*\bsrc\s*=)([^>]*)>/gi, (match) => {
-    if (/nonce\s*=/i.test(match)) return match;
+    if (/nonce\s*=/i.test(match)) {
+      return match.replace(/nonce="[^"]*"/i, `nonce="${nonce}"`);
+    }
     return match.replace(/>$/, ` nonce="${nonce}">`);
   });
 }

package/.docu/node/server-routes.ts

@@ -0,0 +1,266 @@
+import { readFile } from "node:fs/promises";
+import { resolve, join } from "node:path";
+import { statSync } from "node:fs";
+import React, { type ReactNode } from "react";
+import { renderToString } from "react-dom/server";
+import { compileMdx } from "./mdx";
+import { getContentType } from "./utils";
+import { DOCS_DIR, DIST_DIR, PROJECT_ROOT } from "./paths";
+import { BuildPluginBuilder } from "./plugin-builder";
+import type { PageContext } from "./plugin";
+import type { DocuConfig, TocItem } from "./types";
+import DocsPage from "../pages/docs/[[...slug]]";
+import NotFoundPage from "../pages/404";
+import IndexPage from "../pages/index";
+import { DocsLayout } from "../components/DocsLayout";
+import { generateNonce, isPathSafe, isSlugSafe, htmlResponse, SECURITY_HEADERS } from "./security";
+import { htmlShell as createHtmlShell, hmrScript, errorHtml } from "./html";
+
+export interface ServerState {
+  docuConfig: DocuConfig;
+  assetManifest: { css: string; js: string };
+  inlineThemeCss: string;
+  builder: BuildPluginBuilder | null;
+}
+
+function createHtmlResponse(
+  title: string,
+  description: string,
+  body: string,
+  status: number,
+  state: ServerState
+): Response {
+  const nonce = generateNonce();
+  const favicon = state.docuConfig.meta?.favicon || "/favicon.ico";
+  const html = createHtmlShell({
+    title,
+    description,
+    body,
+    favicon,
+    css: state.assetManifest.css,
+    js: state.assetManifest.js,
+    nonce,
+    extraScripts: hmrScript(nonce),
+    themeCss: state.inlineThemeCss,
+  });
+  return htmlResponse(html, nonce, status, process.env.NODE_ENV !== "production");
+}
+
+async function getDocsForSlug(
+  slug: string,
+  state: ServerState
+): Promise<{
+  content: ReactNode;
+  compiledSource: string;
+  frontmatter: Record<string, unknown>;
+  tocs: TocItem[];
+  filePath: string;
+  resolvedContent: string;
+} | null> {
+  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 + "/", "");
+
+  let content = raw;
+  if (state.builder) {
+    const transformed = await state.builder.runOnLoad(relPath, content);
+    if (transformed?.contents) {
+      content = transformed.contents;
+    }
+  }
+
+  const remarkPlugins = state.builder?.collectRemarkPlugins();
+  const rehypePlugins = state.builder?.collectRehypePlugins();
+  const result = await compileMdx(content, relPath, undefined, remarkPlugins, rehypePlugins);
+
+  let frontmatter = result.frontmatter as Record<string, unknown>;
+  if (state.builder) {
+    frontmatter = await state.builder.runTransformFrontmatterChain(frontmatter, {
+      slug: slug || "/",
+      filePath: relPath,
+      content,
+    });
+  }
+
+  return {
+    content: result.content,
+    compiledSource: result.compiledSource,
+    frontmatter,
+    tocs: result.tocs,
+    filePath: relPath,
+    resolvedContent: content,
+  };
+}
+
+async function renderDocsServerPage(
+  doc: NonNullable<Awaited<ReturnType<typeof getDocsForSlug>>>,
+  slug: string[],
+  pathname: string,
+  state: ServerState
+): Promise<Response> {
+  const title = (doc.frontmatter.title as string) || slug.join("/") || "Docs";
+  const description = (doc.frontmatter.description as string) || "";
+
+  const page = React.createElement(
+    DocsLayout,
+    { repoUrl: state.docuConfig.repo?.url, pathname },
+    React.createElement(DocsPage, {
+      slug,
+      title,
+      description,
+      date: doc.frontmatter.date as string | undefined,
+      content: doc.content,
+      tocs: doc.tocs,
+      filePath: doc.filePath,
+      repoUrl: state.docuConfig.repo?.url,
+      compiledSource: doc.compiledSource,
+    })
+  );
+
+  const body = renderToString(page);
+
+  if (state.builder) {
+    const ctx: PageContext = {
+      slug: slug.join("/") || "/",
+      filePath: doc.filePath,
+      frontmatter: doc.frontmatter,
+      content: doc.resolvedContent,
+      config: state.docuConfig,
+    };
+    const headExtra = state.builder.collectHead(ctx);
+    const bodyExtra = state.builder.collectBody(ctx);
+    const nonce = generateNonce();
+    const favicon = state.docuConfig.meta?.favicon || "/favicon.ico";
+    let html = createHtmlShell({
+      title,
+      description,
+      body,
+      favicon,
+      css: state.assetManifest.css,
+      js: state.assetManifest.js,
+      nonce,
+      extraScripts: hmrScript(nonce),
+      themeCss: state.inlineThemeCss,
+      headExtra,
+      bodyExtra,
+    });
+    html = await state.builder.runTransformHtmlChain(html, ctx);
+    return htmlResponse(html, nonce, 200, process.env.NODE_ENV !== "production");
+  }
+
+  return createHtmlResponse(title, description, body, 200, state);
+}
+
+function renderPage(
+  Component: React.ComponentType<Record<string, unknown>>,
+  title: string,
+  description: string,
+  status: number,
+  state: ServerState,
+  props: Record<string, unknown> = {}
+): Response {
+  const page = React.createElement(
+    DocsLayout,
+    { repoUrl: state.docuConfig.repo?.url, pathname: "/docs" },
+    React.createElement(Component, props)
+  );
+  const body = renderToString(page);
+  return createHtmlResponse(title, description, body, status, state);
+}
+
+export async function handleDocsIndex(state: ServerState): Promise<Response> {
+  const doc = await getDocsForSlug("", state);
+  if (!doc) return renderPage(NotFoundPage, "404 - Not Found", "", 404, state);
+  return renderDocsServerPage(doc, [], "/docs", state);
+}
+
+export async function handleDocsRoute(slug: string[], state: ServerState): Promise<Response> {
+  const path = slug.join("/");
+  const doc = await getDocsForSlug(path, state);
+  if (!doc) return renderPage(NotFoundPage, "404 - Not Found", "", 404, state);
+  return renderDocsServerPage(doc, slug, `/docs/${path}`, state);
+}
+
+export function handleIndex(state: ServerState): Response {
+  const page = React.createElement(IndexPage);
+  const body = renderToString(page);
+  return createHtmlResponse(
+    state.docuConfig.meta?.title || "DocuBook",
+    state.docuConfig.meta?.description || "",
+    body,
+    200,
+    state
+  );
+}
+
+export function handleNotFound(state: ServerState): Response {
+  return renderPage(NotFoundPage, "404 - Not Found", "", 404, state);
+}
+
+export 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;
+}
+
+export function serverErrorResponse(error: unknown): Response {
+  const msg = error instanceof Error ? error.message : "Unknown error";
+  const st = error instanceof Error ? error.stack : undefined;
+  return new Response(errorHtml(msg, st), {
+    status: 500,
+    headers: {
+      "Content-Type": "text/html",
+      ...SECURITY_HEADERS,
+      "Content-Security-Policy": "default-src 'none'; style-src 'unsafe-inline'",
+    },
+  });
+}