@docubook/flame 1.3.4 → 1.3.6

package/.docu/node/build.ts

@@ -112,8 +112,8 @@ async function renderDocsPage(
     });
   }
 
-  const title = (frontmatter.title as string) || slug || "Docs";
-  const description = (frontmatter.description as string) || "";
+  const title = (typeof frontmatter.title === "string" ? frontmatter.title : "") || slug || "Docs";
+  const description = typeof frontmatter.description === "string" ? frontmatter.description : "";
   const slugParts = slug ? slug.split("/") : [];
 
   const page = React.createElement(

package/.docu/node/plugin-builder.ts

@@ -365,6 +365,8 @@ export class BuildPluginBuilder implements PluginBuilder {
    * Each callback receives the **previous** callback's return value (or the
    * original frontmatter for the first). Callbacks that return `undefined` or
    * `null` pass the current value through unchanged.
+   * Callbacks that return a non-object (string, number, array) are skipped
+   * with a console warning — only plain objects are accepted.
    * Errors inside individual callbacks are caught and logged — the current
    * frontmatter passes through unchanged for that step.
    *
@@ -381,7 +383,13 @@ export class BuildPluginBuilder implements PluginBuilder {
       try {
         const next = await this._transformFrontmatter[i](result, context);
         if (next !== undefined && next !== null) {
-          result = next;
+          if (typeof next === "object" && !Array.isArray(next)) {
+            result = next;
+          } else {
+            console.warn(
+              `[plugin] transformFrontmatter callback #${i + 1} returned invalid type (expected a plain object), skipping`
+            );
+          }
         }
       } catch (err) {
         console.error(
@@ -422,6 +430,10 @@ export class BuildPluginBuilder implements PluginBuilder {
    * Callbacks are chained in a waterfall: the return value of one is passed
    * as input to the next. Return `undefined` to pass through unchanged.
    *
+   * **Note:** Only plain objects are accepted as return values. Returning
+   * a string, number, or array will be silently skipped with a warning.
+   * Plugin authors should validate their return values before returning.
+   *
    * @param callback - Receives frontmatter object and page context.
    *
    * @example

package/.docu/node/plugin-loader.ts

@@ -2,13 +2,15 @@ import { resolve } from "node:path";
 import { PROJECT_ROOT } from "./paths";
 import type { DocuBookPlugin, PluginEntry } from "./plugin";
 
+const NPM_PACKAGE_RE = /^(?:@[a-z0-9-~][a-z0-9-._~]*\/)?[a-z0-9-~][a-z0-9-._~]*$/;
+
 /**
  * Resolve a plugin specifier to an absolute path or npm package name.
  *
  * Resolution rules:
  * 1. Relative path (starts with `.`) → resolve from project root, guard traversal
  * 2. Absolute path (starts with `/`) → guard traversal
- * 3. Anything else → treat as npm package name (handled by Bun's import)
+ * 3. Anything else → validate as npm package name, then pass to Bun's import
  *
  * Path traversal protection:
  * - All file-system paths (relative & absolute) must resolve within PROJECT_ROOT.
@@ -25,7 +27,12 @@ export function resolveSpecifier(specifier: string): string {
     // Absolute path → use as-is
     resolved = specifier;
   } else {
-    // npm package name → handled by Bun's import
+    // npm package name → validate format, then handled by Bun's import
+    if (!NPM_PACKAGE_RE.test(specifier)) {
+      throw new Error(
+        `[plugin-loader] Invalid plugin specifier "${specifier}": must be a valid npm package name, relative path, or absolute path`
+      );
+    }
     return specifier;
   }
 

package/.docu/node/plugin.ts

@@ -198,7 +198,7 @@ export interface PluginBuilder {
 
   /**
    * Register additional remark (Markdown) plugins for the MDX compilation pipeline.
-   * Plugins from all plugins are merged and applied **after** the default set.
+   * Plugins from all registered callbacks are merged and applied **after** the default set.
    *
    * @example
    * build.remarkPlugins(() => [require("remark-custom-heading-id")]);
@@ -207,7 +207,7 @@ export interface PluginBuilder {
 
   /**
    * Register additional rehype (HTML) plugins for the MDX compilation pipeline.
-   * Plugins from all plugins are merged and applied **after** the default set.
+   * Plugins from all registered callbacks are merged and applied **after** the default set.
    *
    * @example
    * build.rehypePlugins(() => [require("rehype-autolink-headings")]);

package/.docu/node/security.ts

@@ -89,6 +89,40 @@ export function injectNonce(html: string, nonce: string): string {
   });
 }
 
+export interface PluginResponseLike {
+  status: number;
+  statusText?: string;
+  headers: Headers;
+  body: BodyInit | null;
+}
+
+/**
+ * Wrap a plugin response with security headers.
+ * - Fills in SECURITY_HEADERS defaults where plugin hasn't set a value
+ * - Adds Content-Security-Policy for HTML responses (with optional unsafe-eval)
+ * - Preserves plugin body, status, statusText unchanged
+ */
+export function wrapPluginResponse(
+  pluginResponse: PluginResponseLike,
+  allowEval = false
+): Response {
+  const securedHeaders = new Headers(pluginResponse.headers);
+  for (const [key, value] of Object.entries(SECURITY_HEADERS)) {
+    if (!securedHeaders.has(key)) {
+      securedHeaders.set(key, value);
+    }
+  }
+  const contentType = securedHeaders.get("Content-Type") || "";
+  if (contentType.includes("text/html") && !securedHeaders.has("Content-Security-Policy")) {
+    securedHeaders.set("Content-Security-Policy", cspHeader(generateNonce(), allowEval));
+  }
+  return new Response(pluginResponse.body, {
+    status: pluginResponse.status,
+    statusText: pluginResponse.statusText,
+    headers: securedHeaders,
+  });
+}
+
 export function htmlResponse(
   html: string,
   nonce: string,

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

@@ -1,5 +1,5 @@
 import { readFile } from "node:fs/promises";
-import { resolve, join } from "node:path";
+import { resolve } from "node:path";
 import { statSync } from "node:fs";
 import React, { type ReactNode } from "react";
 import { renderToString } from "react-dom/server";
@@ -62,19 +62,26 @@ async function getDocsForSlug(
   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`),
+    resolve(DOCS_DIR, slug, "index.mdx"),
+    resolve(DOCS_DIR, `${slug}.mdx`),
+    resolve(DOCS_DIR, slug, "index.md"),
+    resolve(DOCS_DIR, `${slug}.md`),
   ];
 
+  const resolvedDocsDir = resolve(DOCS_DIR);
   let filePath: string | null = null;
   let raw: string | null = null;
   for (const p of paths) {
-    if (!p.startsWith(DOCS_DIR)) continue;
+    const resolvedCandidate = resolve(p);
+    if (
+      resolvedCandidate !== resolvedDocsDir &&
+      !resolvedCandidate.startsWith(resolvedDocsDir + "/")
+    ) {
+      continue;
+    }
     try {
-      raw = await readFile(p, "utf-8");
-      filePath = p;
+      raw = await readFile(resolvedCandidate, "utf-8");
+      filePath = resolvedCandidate;
       break;
     } catch (err) {
       if ((err as NodeJS.ErrnoException).code !== "ENOENT") throw err;
@@ -121,8 +128,12 @@ async function renderDocsServerPage(
   pathname: string,
   state: ServerState
 ): Promise<Response> {
-  const title = (doc.frontmatter.title as string) || slug.join("/") || "Docs";
-  const description = (doc.frontmatter.description as string) || "";
+  const title =
+    (typeof doc.frontmatter.title === "string" ? doc.frontmatter.title : "") ||
+    slug.join("/") ||
+    "Docs";
+  const description =
+    typeof doc.frontmatter.description === "string" ? doc.frontmatter.description : "";
 
   const page = React.createElement(
     DocsLayout,
@@ -227,8 +238,13 @@ export function handleNotFound(state: ServerState, depth = 0): Response {
 }
 
 export function serveStatic(pathname: string): Response | null {
+  let decoded: string;
+  try {
+    decoded = decodeURIComponent(pathname);
+  } catch {
+    return 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);
@@ -242,10 +258,11 @@ export function serveStatic(pathname: string): Response | null {
   }
 
   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;
+    const requestedRelative = decoded.slice("/docs/assets/".length);
+    const docsAsset = resolve(docsAssetsDir, requestedRelative);
+    const docsAssetsDirWithSep = docsAssetsDir.endsWith("/") ? docsAssetsDir : docsAssetsDir + "/";
+    if (docsAsset !== docsAssetsDir && !docsAsset.startsWith(docsAssetsDirWithSep)) return null;
     try {
       const s = statSync(docsAsset);
       if (s.isFile()) {

package/.docu/node/server.ts

@@ -15,11 +15,11 @@ import {
   serverErrorResponse,
   type ServerState,
 } from "./server-routes";
-import { SECURITY_HEADERS, cspHeader, generateNonce } from "./security";
+import { wrapPluginResponse } from "./security";
 
 const docuConfig = loadDocuConfig();
 
-const PORT = process.env.PORT ?? "3000";
+const PORT = Number(process.env.PORT ?? 3000);
 
 logger.buildStart();
 
@@ -103,28 +103,14 @@ const server = Bun.serve({
     const startTime = performance.now();
 
     if (builder) {
+      const serverPort = server.port ?? PORT;
+      const serverHostname = server.hostname ?? "localhost";
       const pluginResponse = await builder.runHandleRequest(req, {
-        port: server.port!,
-        hostname: server.hostname!,
+        port: serverPort,
+        hostname: serverHostname,
       });
       if (pluginResponse) {
-        // Wrap plugin response with security headers.
-        // Plugin's own headers take precedence over defaults.
-        const securedHeaders = new Headers(pluginResponse.headers);
-        for (const [key, value] of Object.entries(SECURITY_HEADERS)) {
-          if (!securedHeaders.has(key)) {
-            securedHeaders.set(key, value);
-          }
-        }
-        const contentType = securedHeaders.get("Content-Type") || "";
-        if (contentType.includes("text/html") && !securedHeaders.has("Content-Security-Policy")) {
-          securedHeaders.set("Content-Security-Policy", cspHeader(generateNonce(), true));
-        }
-        const securedResponse = new Response(pluginResponse.body, {
-          status: pluginResponse.status,
-          statusText: pluginResponse.statusText,
-          headers: securedHeaders,
-        });
+        const securedResponse = wrapPluginResponse(pluginResponse, true);
         logger.request(
           req.method,
           pathname,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docubook/flame",
-  "version": "1.3.4",
+  "version": "1.3.6",
   "description": "A blazing-fast React + MDX framework powered by Bun, built for modern documentation experiences.",
   "type": "module",
   "bin": {
@@ -53,9 +53,9 @@
     "react-dom": "^19.2.7",
     "unified": "^11.0.0",
     "@docubook/core": "^1.7.2",
-    "@docubook/themes-colors": "^0.10.2",
+    "@docubook/mdx-content": "^3.2.2",
     "@docubook/ui-react": "^0.1.4",
-    "@docubook/mdx-content": "^3.2.2"
+    "@docubook/themes-colors": "^0.10.2"
   },
   "peerDependencies": {
     "@sentry/bun": "^10.0.0"