@docubook/flame 1.2.0 → 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/preview.ts

@@ -3,19 +3,10 @@ import { resolve } from "node:path";
 import { logger } from "./logger";
 import { DIST_DIR } from "./paths";
 import { getContentType } from "./utils";
+import { SECURITY_HEADERS, generateNonce, cspHeader, injectNonce } from "./security";
 
 const PORT = process.env.PORT || "4173";
 
-const SECURITY_HEADERS: Record<string, string> = {
-  "Strict-Transport-Security": "max-age=63072000; includeSubDomains; preload",
-  "X-Frame-Options": "DENY",
-  "X-Content-Type-Options": "nosniff",
-  "Referrer-Policy": "strict-origin-when-cross-origin",
-  "Permissions-Policy": "camera=(), microphone=(), geolocation=()",
-  "Content-Security-Policy":
-    "default-src 'self'; script-src 'self' 'sha256-4XrQ+xtH2goQdpEv7dRmUWACF3uhF9KRPpgayFex7QU=' 'unsafe-eval'; style-src 'self' 'unsafe-inline'; img-src 'self' https: data:; font-src 'self' data:; connect-src 'self' https:; frame-src https://www.youtube-nocookie.com; frame-ancestors 'none'",
-};
-
 logger.buildStart();
 
 if (!existsSync(DIST_DIR)) {
@@ -50,22 +41,42 @@ const notFoundPath = resolve(DIST_DIR, "404.html");
 const server = Bun.serve({
   port: PORT,
 
-  fetch(req) {
+  async fetch(req) {
     const url = new URL(req.url);
     const pathname = decodeURIComponent(url.pathname);
 
     const filePath = resolveFile(pathname);
+
     if (filePath) {
       const contentType = getContentType(filePath);
-      const headers: Record<string, string> = { "Content-Type": contentType };
-      if (contentType === "text/html") Object.assign(headers, SECURITY_HEADERS);
-      return new Response(Bun.file(filePath), { headers });
+      if (contentType === "text/html") {
+        const nonce = generateNonce();
+        const html = await Bun.file(filePath).text();
+        const modified = injectNonce(html, nonce);
+        return new Response(modified, {
+          headers: {
+            "Content-Type": "text/html",
+            ...SECURITY_HEADERS,
+            "Content-Security-Policy": cspHeader(nonce, true),
+          },
+        });
+      }
+      return new Response(Bun.file(filePath), {
+        headers: { "Content-Type": contentType },
+      });
     }
 
     if (existsSync(notFoundPath)) {
-      return new Response(Bun.file(notFoundPath), {
+      const nonce = generateNonce();
+      const html = await Bun.file(notFoundPath).text();
+      const modified = injectNonce(html, nonce);
+      return new Response(modified, {
         status: 404,
-        headers: { "Content-Type": "text/html", ...SECURITY_HEADERS },
+        headers: {
+          "Content-Type": "text/html",
+          ...SECURITY_HEADERS,
+          "Content-Security-Policy": cspHeader(nonce, true),
+        },
       });
     }
 

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,3 +1,6 @@
+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",
   "X-Frame-Options": "DENY",
@@ -10,10 +13,13 @@ export function generateNonce(): string {
   return crypto.randomUUID();
 }
 
-export function cspHeader(nonce: string): string {
+export function cspHeader(nonce: string, allowEval = false): string {
+  const scriptSrc = allowEval
+    ? `script-src 'self' 'nonce-${nonce}' 'unsafe-eval'`
+    : `script-src 'self' 'nonce-${nonce}'`;
   return [
     "default-src 'self'",
-    `script-src 'self' 'nonce-${nonce}' 'unsafe-eval'`,
+    scriptSrc,
     "style-src 'self' 'unsafe-inline'",
     "img-src 'self' https: data:",
     "font-src 'self' data:",
@@ -23,13 +29,78 @@ export function cspHeader(nonce: string): string {
   ].join("; ");
 }
 
-export function htmlResponse(html: string, nonce: string, status = 200): Response {
+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 + "/";
+  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 + "/";
+  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.replace(/nonce="[^"]*"/i, `nonce="${nonce}"`);
+    }
+    return match.replace(/>$/, ` nonce="${nonce}">`);
+  });
+}
+
+export function htmlResponse(
+  html: string,
+  nonce: string,
+  status = 200,
+  allowEval = false
+): Response {
   return new Response(html, {
     status,
     headers: {
       "Content-Type": "text/html",
       ...SECURITY_HEADERS,
-      "Content-Security-Policy": cspHeader(nonce),
+      "Content-Security-Policy": cspHeader(nonce, allowEval),
     },
   });
 }