blume 0.2.0 → 0.4.0

package/src/astro/integration.ts

@@ -1,8 +1,67 @@
 import type { IncomingMessage, ServerResponse } from "node:http";
+import { fileURLToPath } from "node:url";
 
 import type { AstroIntegration } from "astro";
 
+import type { AssetMount } from "../core/assets.ts";
+import { enrichDiagnostic } from "../core/diagnostics.ts";
+import type { Diagnostic } from "../core/types.ts";
 import { markdownVariantUrl, prefersMarkdown } from "./markdown-negotiation.ts";
+import { copyAssetMounts, serveAssetMounts } from "./static-assets.ts";
+
+/** The dev server's HMR channel — either `.ws` (Vite ≤5) or `.hot` (Vite 6+). */
+interface OverlayChannel {
+  send: (payload: unknown) => void;
+}
+interface OverlayServer {
+  hot?: OverlayChannel;
+  ws?: OverlayChannel;
+}
+
+// Set on `astro:server:setup`; read by `showBlumeErrorOverlay` so the CLI's
+// regeneration can push Blume diagnostics into Vite's browser error overlay.
+// Same-process module singleton (dev and the integration share the instance).
+let overlayServer: OverlayServer | null = null;
+
+const overlayChannel = (): OverlayChannel | undefined =>
+  overlayServer?.ws ?? overlayServer?.hot;
+
+/**
+ * Surface Blume's own diagnostics (config/frontmatter/content errors) in the
+ * Vite/Astro browser error overlay during `blume dev`, so they don't hide in the
+ * terminal. A no-op when there are no errors or the dev server isn't up. The
+ * overlay clears itself on the next successful HMR update.
+ */
+export const showBlumeErrorOverlay = (diagnostics: Diagnostic[]): void => {
+  const errors = diagnostics
+    .filter((diagnostic) => diagnostic.severity === "error")
+    .map(enrichDiagnostic);
+  const channel = overlayChannel();
+  if (errors.length === 0 || !channel) {
+    return;
+  }
+  const body = errors
+    .map((diagnostic) => {
+      const where = diagnostic.file
+        ? `\n  at ${diagnostic.file}${diagnostic.line ? `:${diagnostic.line}` : ""}`
+        : "";
+      const fix = diagnostic.suggestion
+        ? `\n  fix: ${diagnostic.suggestion}`
+        : "";
+      const docs = diagnostic.docsUrl ? `\n  docs: ${diagnostic.docsUrl}` : "";
+      return `[${diagnostic.code}] ${diagnostic.message}${where}${fix}${docs}`;
+    })
+    .join("\n\n");
+  channel.send({
+    err: {
+      id: errors[0]?.file,
+      message: `Blume found ${errors.length} error(s):\n\n${body}`,
+      plugin: "blume",
+      stack: "",
+    },
+    type: "error",
+  });
+};
 
 /** A user page mounted into the generated runtime. */
 export interface BlumePageRoute {
@@ -16,6 +75,13 @@ export interface BlumeIntegrationOptions {
   pages: BlumePageRoute[];
   /** Page routes that have a raw-Markdown variant (the content manifest). */
   contentRoutes: string[];
+  /** Configured `deployment.base`, stripped from dev URLs before matching. */
+  base?: string;
+  /**
+   * `content.assets` mounts: top-level dirs served at the site root in dev and
+   * copied into the build output, so root-served assets need no relocation.
+   */
+  assets?: AssetMount[];
 }
 
 /**
@@ -27,13 +93,13 @@ export interface BlumeIntegrationOptions {
  * keep serving HTML.
  */
 const negotiateMarkdown =
-  (routes: ReadonlySet<string>) =>
+  (routes: ReadonlySet<string>, base?: string) =>
   (req: IncomingMessage, res: ServerResponse, next: () => void): void => {
     if (
       (req.method === "GET" || req.method === "HEAD") &&
       prefersMarkdown(req.headers.accept)
     ) {
-      const variant = markdownVariantUrl(req.url, routes);
+      const variant = markdownVariantUrl(req.url, routes, base);
       if (variant) {
         res.setHeader("Vary", "Accept");
         req.url = variant;
@@ -52,6 +118,12 @@ export const blumeIntegration = (
   options: BlumeIntegrationOptions
 ): AstroIntegration => ({
   hooks: {
+    "astro:build:done": async ({ dir }) => {
+      // Copy in-place asset mounts into the build output, mirroring publicDir.
+      if (options.assets?.length) {
+        await copyAssetMounts(options.assets, fileURLToPath(dir));
+      }
+    },
     "astro:config:setup": ({ injectRoute }) => {
       for (const page of options.pages) {
         injectRoute({
@@ -62,12 +134,22 @@ export const blumeIntegration = (
       }
     },
     "astro:server:setup": ({ server }) => {
+      // Keep a handle on the dev server so Blume diagnostics can be pushed to
+      // its browser error overlay (see `showBlumeErrorOverlay`).
+      overlayServer = server as unknown as OverlayServer;
       // Prepend so the rewrite happens before Astro's own request handler,
       // letting the rewritten URL resolve to the `.md` endpoint.
       server.middlewares.stack.unshift({
-        handle: negotiateMarkdown(new Set(options.contentRoutes)),
+        handle: negotiateMarkdown(new Set(options.contentRoutes), options.base),
         route: "",
       });
+      // Serve `content.assets` mounts (Astro only serves publicDir in dev).
+      if (options.assets?.length) {
+        server.middlewares.stack.unshift({
+          handle: serveAssetMounts(options.assets),
+          route: "",
+        });
+      }
     },
   },
   name: "blume",

package/src/astro/islands.ts

@@ -105,9 +105,13 @@ export const discoverIslands = async (
       continue;
     }
     const name = base.replace(ISLAND_FILE, "");
-    if (!/^[A-Z]/u.test(name)) {
+    // The name is used verbatim as both an MDX tag and an unquoted object key
+    // in the generated island map, so it must be a plain PascalCase identifier
+    // — a `-`, `.`, or space (e.g. `Time-Picker.tsx`) would otherwise emit a
+    // syntax-error module and fail the whole build with no pointer to the file.
+    if (!/^[A-Z][A-Za-z0-9_]*$/u.test(name)) {
       warnings.push(
-        `Island "${file}" must have a PascalCase filename to be used in MDX (e.g. Counter.tsx → <Counter />); skipping it.`
+        `Island "${file}" must have a PascalCase identifier filename to be used in MDX (letters, digits, and underscores only, e.g. Counter.tsx → <Counter />); skipping it.`
       );
       continue;
     }

package/src/astro/markdown-negotiation.ts

@@ -50,7 +50,8 @@ export const prefersMarkdown = (accept: string | null | undefined): boolean => {
  */
 export const markdownVariantUrl = (
   rawUrl: string | null | undefined,
-  routes: ReadonlySet<string>
+  routes: ReadonlySet<string>,
+  base?: string
 ): string | null => {
   if (!rawUrl) {
     return null;
@@ -58,11 +59,24 @@ export const markdownVariantUrl = (
   const queryIndex = rawUrl.indexOf("?");
   const query = queryIndex === -1 ? "" : rawUrl.slice(queryIndex);
   const rawPath = queryIndex === -1 ? rawUrl : rawUrl.slice(0, queryIndex);
+
+  // A non-root `deployment.base` prefixes the dev-server URL but not the logical
+  // content routes, so strip it before matching and re-add it to the variant.
+  const prefix = base && base !== "/" ? base.replace(/\/$/u, "") : "";
+  let path = rawPath;
+  if (prefix) {
+    if (path === prefix || path.startsWith(`${prefix}/`)) {
+      path = path.slice(prefix.length) || "/";
+    } else {
+      return null;
+    }
+  }
+
   const pathname =
-    rawPath !== "/" && rawPath.endsWith("/") ? rawPath.slice(0, -1) : rawPath;
+    path !== "/" && path.endsWith("/") ? path.slice(0, -1) : path;
   if (!routes.has(pathname)) {
     return null;
   }
   const target = pathname === "/" ? "/index" : pathname;
-  return `${target}.md${query}`;
+  return `${prefix}${target}.md${query}`;
 };

package/src/astro/pages.ts

@@ -21,7 +21,12 @@ export const discoverPages = async (
   return files.map((file) => {
     const rel = relative(pagesRoot, file);
     const withoutExt = rel.slice(0, rel.length - extname(rel).length);
-    const parts = withoutExt.split("/").filter((part) => part !== "index");
+    const parts = withoutExt.split("/");
+    // Only a trailing `index` maps to its parent dir; a folder literally named
+    // `index` (e.g. `index/foo.astro`) must keep its segment.
+    if (parts.at(-1) === "index") {
+      parts.pop();
+    }
     const pattern = parts.length === 0 ? "/" : `/${parts.join("/")}`;
     return { entrypoint: file, pattern };
   });
@@ -45,10 +50,8 @@ export const routeIsTaken = (
 export interface OgCustomRoute {
   /** `og/<slug>.png` path segment; `index` for the site root. */
   slug: string;
-  /** Card title. */
+  /** Card headline. */
   title: string;
-  /** Small eyebrow line above the title. */
-  eyebrow?: string;
 }
 
 /** Skip private (`_partial`, `.well-known`) and Astro dynamic (`[param]`) parts. */
@@ -68,13 +71,12 @@ const humanizeSegment = (segment: string): string =>
  *
  * Dynamic (`[param]`) routes and private segments (`_partials`, `.well-known`)
  * are skipped: they aren't shareable pages. The home is titled with the site
- * title (eyebrow: the site description); a deeper page is titled from its last
- * path segment.
+ * title; a deeper page is titled from its last path segment. The card's brand
+ * lockup, description, and footer come from the resolved config at render time.
  */
 export const customOgRoutes = (
   pages: BlumePageRoute[],
-  siteTitle: string,
-  siteDescription?: string
+  siteTitle: string
 ): OgCustomRoute[] => {
   const seen = new Set<string>();
   const routes: OgCustomRoute[] = [];
@@ -91,11 +93,7 @@ export const customOgRoutes = (
     }
     seen.add(slug);
     const last = segments.at(-1);
-    routes.push(
-      last
-        ? { eyebrow: siteTitle, slug, title: humanizeSegment(last) }
-        : { eyebrow: siteDescription, slug, title: siteTitle }
-    );
+    routes.push({ slug, title: last ? humanizeSegment(last) : siteTitle });
   }
   return routes;
 };

package/src/astro/static-assets.ts

@@ -0,0 +1,117 @@
+import { createReadStream, existsSync, statSync } from "node:fs";
+import type { Stats } from "node:fs";
+import { cp } from "node:fs/promises";
+import type { IncomingMessage, ServerResponse } from "node:http";
+
+import { extname, join, relative, resolve, sep } from "pathe";
+
+import type { AssetMount } from "../core/assets.ts";
+
+/** Content types for the asset extensions a docs project commonly serves. */
+const MIME_TYPES: Record<string, string> = {
+  ".avif": "image/avif",
+  ".css": "text/css; charset=utf-8",
+  ".gif": "image/gif",
+  ".ico": "image/x-icon",
+  ".jpeg": "image/jpeg",
+  ".jpg": "image/jpeg",
+  ".js": "text/javascript; charset=utf-8",
+  ".json": "application/json; charset=utf-8",
+  ".mp4": "video/mp4",
+  ".otf": "font/otf",
+  ".pdf": "application/pdf",
+  ".png": "image/png",
+  ".svg": "image/svg+xml",
+  ".ttf": "font/ttf",
+  ".txt": "text/plain; charset=utf-8",
+  ".webm": "video/webm",
+  ".webp": "image/webp",
+  ".woff": "font/woff",
+  ".woff2": "font/woff2",
+};
+
+const mimeType = (file: string): string =>
+  MIME_TYPES[extname(file).toLowerCase()] ?? "application/octet-stream";
+
+/** Whether `child` is `parent` itself or a path nested under it. */
+const isContained = (parent: string, child: string): boolean => {
+  const rel = relative(parent, child);
+  return rel === "" || (!rel.startsWith("..") && !rel.startsWith(sep));
+};
+
+/** Resolve a request URL to an on-disk file within one of the mounts, if any. */
+const resolveRequest = (url: string, mounts: AssetMount[]): string | null => {
+  const pathname = decodeURIComponent(
+    (url.split("?")[0] ?? "").split("#")[0] ?? ""
+  );
+  for (const mount of mounts) {
+    if (pathname !== mount.url && !pathname.startsWith(`${mount.url}/`)) {
+      continue;
+    }
+    // `.` + rel keeps the join relative so an absolute-looking suffix can't
+    // escape the mount; the containment check rejects `..` traversal outright.
+    const file = resolve(mount.dir, `.${pathname.slice(mount.url.length)}`);
+    if (isContained(mount.dir, file)) {
+      return file;
+    }
+  }
+  return null;
+};
+
+/** `statSync` that returns null instead of throwing on a missing file. */
+const statFile = (file: string): Stats | null => {
+  try {
+    return statSync(file);
+  } catch {
+    return null;
+  }
+};
+
+/**
+ * A dev-server middleware that serves `content.assets` mounts (top-level dirs
+ * kept in place, e.g. a migrated `images/`) at their site URL. Astro only serves
+ * `publicDir` in dev, so without this those references would 404. Non-matching
+ * requests, and any path that isn't a real file, fall through to Astro. Stat is
+ * synchronous — this is dev-only middleware and mirrors how sirv serves statics.
+ */
+export const serveAssetMounts =
+  (mounts: AssetMount[]) =>
+  (req: IncomingMessage, res: ServerResponse, next: () => void): void => {
+    if ((req.method !== "GET" && req.method !== "HEAD") || !req.url) {
+      next();
+      return;
+    }
+    const file = resolveRequest(req.url, mounts);
+    const stats = file ? statFile(file) : null;
+    if (!(file && stats?.isFile())) {
+      next();
+      return;
+    }
+    res.setHeader("Content-Type", mimeType(file));
+    res.setHeader("Content-Length", String(stats.size));
+    if (req.method === "HEAD") {
+      res.end();
+      return;
+    }
+    createReadStream(file).pipe(res);
+  };
+
+/**
+ * Copy every asset mount into the build output, mirroring what Astro does with
+ * `publicDir`. Runs on `astro:build:done` so in-place asset dirs ship in the
+ * final `dist/`. A missing source dir is skipped (it may be referenced but
+ * absent); `cp` handles both directories and single files.
+ */
+export const copyAssetMounts = async (
+  mounts: AssetMount[],
+  outDir: string
+): Promise<void> => {
+  for (const mount of mounts) {
+    if (!existsSync(mount.dir)) {
+      continue;
+    }
+    const dest = join(outDir, mount.url.replace(/^\/+/u, ""));
+    // oxlint-disable-next-line no-await-in-loop -- sequential fs copies
+    await cp(mount.dir, dest, { recursive: true });
+  }
+};