blodemd 0.0.4 → 0.0.6

package/README.md

@@ -31,6 +31,9 @@ Requires Node.js 18+.
 # Scaffold a new docs folder
 blodemd init
 
+# Preview locally
+blodemd dev
+
 # Authenticate
 blodemd login
 
@@ -47,7 +50,7 @@ blodemd logout            Remove stored credentials
 blodemd whoami            Show current authentication
 blodemd validate [dir]    Validate docs.json
 blodemd push [dir]        Deploy docs
-blodemd dev               Show instructions for the local dev server
+blodemd dev [dir]         Start the local docs preview server
 ```
 
 ### `push` Options
@@ -62,6 +65,14 @@ blodemd dev               Show instructions for the local dev server
 
 The CLI reads the project slug from the `name` field in `docs.json` when `--project` is not set.
 
+### `dev` Options
+
+```bash
+--dir <dir>       Docs directory
+--port <port>     Local preview port (default: 3030)
+--no-open         Don't open the browser automatically
+```
+
 ## CI / GitHub Actions
 
 Use the `mblode/blodemd/packages/deploy-action` composite action to deploy on every push:

package/dev-server/app/[[...slug]]/page.tsx

@@ -0,0 +1,139 @@
+import { getDocPageContent, getDocShellData } from "@dev/lib/local-runtime";
+import type { Metadata } from "next";
+import { notFound } from "next/navigation";
+
+import { ApiReference } from "@/components/api/api-reference";
+import { CollectionIndex } from "@/components/content/collection-index";
+import { DocShell } from "@/components/docs/doc-shell";
+
+const buildTitle = (pageTitle?: string, baseTitle = "Docs") =>
+  pageTitle ? `${pageTitle} · ${baseTitle}` : baseTitle;
+
+export const generateMetadata = async ({
+  params,
+}: {
+  params: Promise<{ slug?: string[] }>;
+}): Promise<Metadata> => {
+  const { slug = [] } = await params;
+  const data = await getDocShellData(slug.join("/"));
+
+  if (!data || "configErrors" in data) {
+    return {
+      description: "Documentation",
+      title: "Docs",
+    };
+  }
+
+  const { config } = data;
+  const title = buildTitle(data.pageTitle, config.name ?? "Docs");
+  const noindex =
+    data.noindex || (data.hidden && config.seo?.indexing !== "all");
+  const ogImage = config.metadata?.ogImage;
+  const { favicon } = config;
+
+  return {
+    description: data.pageDescription ?? config.description,
+    icons: favicon ? { icon: favicon } : undefined,
+    openGraph: ogImage
+      ? {
+          images: [ogImage],
+        }
+      : undefined,
+    robots: noindex ? { index: false } : undefined,
+    title,
+    twitter: ogImage
+      ? {
+          card: "summary_large_image",
+          images: [ogImage],
+        }
+      : undefined,
+  };
+};
+
+const PreviewPage = async ({
+  params,
+}: {
+  params: Promise<{ slug?: string[] }>;
+}) => {
+  const { slug = [] } = await params;
+  const slugKey = slug.join("/");
+  const shell = await getDocShellData(slugKey);
+
+  if (!shell) {
+    return notFound();
+  }
+
+  if ("configErrors" in shell) {
+    const errors = shell.configErrors ?? [];
+    const warnings = shell.configWarnings ?? [];
+
+    return (
+      <div className="p-10">
+        <h1>Invalid docs.json</h1>
+        {warnings.length ? (
+          <>
+            <h2>Warnings</h2>
+            <ul>
+              {warnings.map((warning) => (
+                <li key={warning}>{warning}</li>
+              ))}
+            </ul>
+          </>
+        ) : null}
+        <ul>
+          {errors.map((error) => (
+            <li key={error}>{error}</li>
+          ))}
+        </ul>
+      </div>
+    );
+  }
+
+  let content: React.ReactNode;
+  let rawContent: string | undefined;
+  let toc: { id: string; level: number; title: string }[] = [];
+
+  if (shell.kind === "openapi") {
+    content = (
+      <ApiReference
+        entry={shell.openApiEntry}
+        proxyEnabled={shell.openapiProxyEnabled}
+      />
+    );
+    rawContent = shell.openApiEntry.operation.description ?? "";
+  } else if (shell.kind === "index") {
+    content = (
+      <CollectionIndex basePath="" entries={shell.collectionIndex.entries} />
+    );
+  } else {
+    ({ rawContent } = shell);
+    ({ toc } = shell);
+    const rendered = await getDocPageContent(slugKey);
+    content = rendered?.content ?? null;
+  }
+
+  return (
+    <DocShell
+      activeTabIndex={shell.activeTabIndex}
+      anchors={shell.anchors}
+      basePath=""
+      breadcrumbs={shell.breadcrumbs}
+      config={shell.config}
+      content={content}
+      currentPath={shell.currentPath}
+      deprecated={shell.deprecated}
+      hideFooterPagination={shell.hideFooterPagination}
+      mode={shell.mode}
+      nav={shell.nav}
+      nextPage={shell.nextPage}
+      pageDescription={shell.pageDescription}
+      pageTitle={shell.pageTitle}
+      prevPage={shell.prevPage}
+      rawContent={rawContent}
+      tabs={shell.tabs}
+      toc={toc}
+    />
+  );
+};
+
+export default PreviewPage;

package/dev-server/app/blodemd-dev/invalidate/route.ts

@@ -0,0 +1,12 @@
+import { bumpDevVersion } from "@dev/lib/dev-state";
+import { clearLocalRuntimeCaches } from "@dev/lib/local-runtime";
+import { NextResponse } from "next/server";
+
+export const dynamic = "force-dynamic";
+
+export const POST = () => {
+  clearLocalRuntimeCaches();
+  const version = bumpDevVersion();
+
+  return NextResponse.json({ ok: true, version });
+};

package/dev-server/app/blodemd-dev/static/[...path]/route.ts

@@ -0,0 +1,32 @@
+import {
+  getStaticAssetContentType,
+  readStaticAsset,
+} from "@dev/lib/local-content-source";
+import { NextResponse } from "next/server";
+
+export const dynamic = "force-dynamic";
+
+export const GET = async (
+  _request: Request,
+  {
+    params,
+  }: {
+    params: Promise<{ path: string[] }>;
+  }
+) => {
+  const { path = [] } = await params;
+  const relativePath = path.join("/");
+
+  try {
+    const data = await readStaticAsset(relativePath);
+
+    return new NextResponse(data, {
+      headers: {
+        "Cache-Control": "no-store",
+        "Content-Type": getStaticAssetContentType(relativePath),
+      },
+    });
+  } catch {
+    return new NextResponse("Not found", { status: 404 });
+  }
+};

package/dev-server/app/blodemd-dev/version/route.ts

@@ -0,0 +1,14 @@
+import { getDevVersion } from "@dev/lib/dev-state";
+import { NextResponse } from "next/server";
+
+export const dynamic = "force-dynamic";
+
+export const GET = () =>
+  NextResponse.json(
+    { version: getDevVersion() },
+    {
+      headers: {
+        "Cache-Control": "no-store",
+      },
+    }
+  );

package/dev-server/app/blodemd-internal/proxy/route.ts

@@ -0,0 +1,86 @@
+import { getOpenApiProxyContext } from "@dev/lib/local-runtime";
+import { NextResponse } from "next/server";
+
+interface ProxyPayload {
+  body?: string;
+  headers?: Record<string, string>;
+  method: string;
+  url: string;
+}
+
+const jsonError = (error: string, status: number) =>
+  NextResponse.json({ error }, { status });
+
+const resolveAllowedHosts = async () => {
+  const context = await getOpenApiProxyContext();
+
+  if (!context) {
+    return null;
+  }
+
+  const configuredHosts = context.config.openapiProxy?.allowedHosts ?? [];
+  if (configuredHosts.length) {
+    return configuredHosts;
+  }
+
+  const derivedHosts = context.registry.entries.flatMap((entry) =>
+    (entry.spec.servers ?? []).flatMap((server) => {
+      try {
+        return [new URL(server.url).hostname];
+      } catch {
+        return [];
+      }
+    })
+  );
+
+  return [...new Set(derivedHosts)];
+};
+
+export const POST = async (request: Request) => {
+  const payload = (await request.json()) as ProxyPayload;
+
+  if (!(payload?.url && payload?.method)) {
+    return jsonError("Invalid payload", 400);
+  }
+
+  const context = await getOpenApiProxyContext();
+  if (!context) {
+    return jsonError("Invalid docs configuration", 400);
+  }
+
+  if (!context.config.openapiProxy?.enabled) {
+    return jsonError("Proxy disabled", 403);
+  }
+
+  const url = new URL(payload.url);
+  if (!["http:", "https:"].includes(url.protocol)) {
+    return jsonError("Invalid protocol", 400);
+  }
+
+  const allowedHosts = await resolveAllowedHosts();
+  if (!allowedHosts?.length) {
+    return jsonError(
+      "No proxy allowlist is configured for this docs.json.",
+      403
+    );
+  }
+
+  if (!allowedHosts.includes(url.hostname)) {
+    return jsonError("Host not allowed", 403);
+  }
+
+  const method = payload.method.toUpperCase();
+  const response = await fetch(payload.url, {
+    body: method === "GET" ? undefined : payload.body,
+    headers: payload.headers,
+    method,
+  });
+
+  const text = await response.text();
+  return new NextResponse(text, {
+    headers: {
+      "content-type": response.headers.get("content-type") ?? "text/plain",
+    },
+    status: response.status,
+  });
+};

package/dev-server/app/error.tsx

@@ -0,0 +1,24 @@
+"use client";
+
+const Error = ({
+  reset,
+}: {
+  error: Error & { digest?: string };
+  reset: () => void;
+}) => (
+  <div className="flex min-h-[60vh] flex-col items-center justify-center gap-4 px-4 text-center">
+    <h1 className="text-4xl font-bold tracking-tight">Something went wrong</h1>
+    <p className="max-w-md text-muted-foreground">
+      An error occurred while loading this page.
+    </p>
+    <button
+      className="mt-2 rounded-lg bg-primary px-4 py-2 text-sm font-medium text-primary-foreground transition-colors hover:bg-primary/90"
+      onClick={reset}
+      type="button"
+    >
+      Try again
+    </button>
+  </div>
+);
+
+export default Error;

package/dev-server/app/globals.css

@@ -0,0 +1,4 @@
+@import "../../docs/app/globals.css";
+
+@source "../";
+@source "../../docs";

package/dev-server/app/layout.tsx

@@ -0,0 +1,38 @@
+import { DevReloadScript } from "@dev/components/dev-reload-script";
+import { Providers } from "@dev/components/providers";
+import { GeistMono } from "geist/font/mono";
+import type { Metadata } from "next";
+import localFont from "next/font/local";
+
+import "./globals.css";
+
+const glide = localFont({
+  display: "swap",
+  src: [{ path: "../public/glide-variable.woff2" }],
+  variable: "--font-glide",
+  weight: "400 900",
+});
+
+export const metadata: Metadata = {
+  description: "Local docs preview for blodemd dev.",
+  title: "blodemd dev",
+};
+
+export default function RootLayout({
+  children,
+}: Readonly<{
+  children: React.ReactNode;
+}>) {
+  return (
+    <html
+      lang="en"
+      className={`${glide.variable} ${GeistMono.variable}`}
+      suppressHydrationWarning
+    >
+      <body className="relative flex w-full flex-col justify-center overflow-x-hidden scroll-smooth bg-background font-sans antialiased [--header-height:calc(var(--spacing)*14)]">
+        <DevReloadScript />
+        <Providers>{children}</Providers>
+      </body>
+    </html>
+  );
+}

package/dev-server/app/not-found.tsx

@@ -0,0 +1,18 @@
+import Link from "next/link";
+
+const NotFound = () => (
+  <div className="flex min-h-[60vh] flex-col items-center justify-center gap-4 px-4 text-center">
+    <h1 className="text-4xl font-bold tracking-tight">Page not found</h1>
+    <p className="max-w-md text-muted-foreground">
+      The page you are looking for does not exist or has been moved.
+    </p>
+    <Link
+      className="mt-2 rounded-lg bg-primary px-4 py-2 text-sm font-medium text-primary-foreground transition-colors hover:bg-primary/90"
+      href="/"
+    >
+      Go home
+    </Link>
+  </div>
+);
+
+export default NotFound;

package/dev-server/app/search/route.ts

@@ -0,0 +1,17 @@
+import { getSearchItems } from "@dev/lib/local-runtime";
+import { NextResponse } from "next/server";
+
+export const dynamic = "force-dynamic";
+
+export const GET = async (): Promise<Response> => {
+  const items = await getSearchItems();
+
+  return NextResponse.json(
+    { items },
+    {
+      headers: {
+        "Cache-Control": "no-store",
+      },
+    }
+  );
+};

package/dev-server/components/dev-reload-script.tsx

@@ -0,0 +1,86 @@
+"use client";
+
+import { useRouter } from "next/navigation";
+import { startTransition, useEffect, useRef } from "react";
+
+const POLL_INTERVAL_MS = 1000;
+
+const readVersion = async (): Promise<number | null> => {
+  try {
+    const response = await fetch("/blodemd-dev/version", {
+      cache: "no-store",
+      headers: {
+        accept: "application/json",
+      },
+    });
+
+    if (!response.ok) {
+      return null;
+    }
+
+    const payload = (await response.json()) as { version?: number };
+    return typeof payload.version === "number" ? payload.version : null;
+  } catch {
+    return null;
+  }
+};
+
+export const DevReloadScript = () => {
+  const router = useRouter();
+  const currentVersionRef = useRef<number | null>(null);
+  const refreshInFlightRef = useRef(false);
+
+  useEffect(() => {
+    let cancelled = false;
+
+    const poll = async () => {
+      if (document.visibilityState !== "visible") {
+        return;
+      }
+
+      const version = await readVersion();
+      if (cancelled || version === null) {
+        return;
+      }
+
+      if (currentVersionRef.current === null) {
+        currentVersionRef.current = version;
+        return;
+      }
+
+      if (version === currentVersionRef.current || refreshInFlightRef.current) {
+        return;
+      }
+
+      currentVersionRef.current = version;
+      refreshInFlightRef.current = true;
+
+      startTransition(() => {
+        router.refresh();
+        window.setTimeout(() => {
+          refreshInFlightRef.current = false;
+        }, 150);
+      });
+    };
+
+    const pollSafely = async () => {
+      try {
+        await poll();
+      } catch {
+        // Ignore transient polling errors during local dev.
+      }
+    };
+
+    pollSafely();
+    const interval = window.setInterval(() => {
+      pollSafely();
+    }, POLL_INTERVAL_MS);
+
+    return () => {
+      cancelled = true;
+      window.clearInterval(interval);
+    };
+  }, [router]);
+
+  return null;
+};

package/dev-server/components/providers.tsx

@@ -0,0 +1,15 @@
+"use client";
+
+import { ThemeProvider } from "next-themes";
+
+export const Providers = ({ children }: { children: React.ReactNode }) => (
+  <ThemeProvider
+    attribute="class"
+    defaultTheme="system"
+    disableTransitionOnChange
+    enableColorScheme
+    storageKey="theme"
+  >
+    {children}
+  </ThemeProvider>
+);

package/dev-server/lib/dev-state.ts

@@ -0,0 +1,8 @@
+let version = 0;
+
+export const getDevVersion = () => version;
+
+export const bumpDevVersion = () => {
+  version += 1;
+  return version;
+};

package/dev-server/lib/local-content-source.ts

@@ -0,0 +1,103 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+
+import { normalizePath } from "@repo/common";
+import type { ContentSource } from "@repo/previewing";
+import { createFsSource } from "@repo/previewing";
+
+const BINARY_CONTENT_TYPES: Record<string, string> = {
+  ".avif": "image/avif",
+  ".gif": "image/gif",
+  ".ico": "image/x-icon",
+  ".jpeg": "image/jpeg",
+  ".jpg": "image/jpeg",
+  ".otf": "font/otf",
+  ".png": "image/png",
+  ".svg": "image/svg+xml",
+  ".ttf": "font/ttf",
+  ".webp": "image/webp",
+  ".woff": "font/woff",
+  ".woff2": "font/woff2",
+};
+
+const TEXT_CONTENT_TYPES: Record<string, string> = {
+  ".css": "text/css; charset=utf-8",
+  ".html": "text/html; charset=utf-8",
+  ".js": "text/javascript; charset=utf-8",
+  ".json": "application/json; charset=utf-8",
+  ".md": "text/markdown; charset=utf-8",
+  ".mdx": "text/markdown; charset=utf-8",
+  ".txt": "text/plain; charset=utf-8",
+  ".yaml": "application/yaml; charset=utf-8",
+  ".yml": "application/yaml; charset=utf-8",
+};
+
+const isWithinRoot = (root: string, candidate: string) =>
+  candidate === root || candidate.startsWith(`${root}${path.sep}`);
+
+const getDocsRoot = () => {
+  const root = process.env.DOCS_ROOT?.trim();
+
+  if (!root) {
+    throw new Error("DOCS_ROOT is required for the local dev server.");
+  }
+
+  return path.resolve(root);
+};
+
+const resolveDocsPath = (relativePath: string) => {
+  const root = getDocsRoot();
+  const normalized = normalizePath(relativePath);
+  const absolutePath = path.resolve(root, normalized);
+
+  if (!isWithinRoot(root, absolutePath)) {
+    throw new Error(`Path "${relativePath}" escapes DOCS_ROOT.`);
+  }
+
+  return absolutePath;
+};
+
+const toStaticAssetUrl = (relativePath: string) => {
+  const normalized = normalizePath(relativePath);
+
+  if (!normalized || normalized === ".") {
+    return "/blodemd-dev/static";
+  }
+
+  return `/blodemd-dev/static/${normalized
+    .split("/")
+    .map((segment) => encodeURIComponent(segment))
+    .join("/")}`;
+};
+
+export const createPreviewContentSource = (): ContentSource => {
+  const source = createFsSource(getDocsRoot());
+
+  return {
+    exists(relativePath) {
+      return source.exists(relativePath);
+    },
+    listFiles(directory) {
+      return source.listFiles(directory);
+    },
+    readFile(relativePath) {
+      return source.readFile(relativePath);
+    },
+    resolveUrl(relativePath) {
+      return toStaticAssetUrl(relativePath);
+    },
+  };
+};
+
+export const readStaticAsset = async (relativePath: string) =>
+  await fs.readFile(resolveDocsPath(relativePath));
+
+export const getStaticAssetContentType = (relativePath: string) => {
+  const extension = path.extname(relativePath).toLowerCase();
+
+  return (
+    TEXT_CONTENT_TYPES[extension] ??
+    BINARY_CONTENT_TYPES[extension] ??
+    "application/octet-stream"
+  );
+};