blume 0.2.0 → 0.4.0

package/src/astro/templates.ts

@@ -4,6 +4,7 @@ import { dirname, join } from "pathe";
 
 import { askBackendRuntimeDep } from "../ai/ask.ts";
 import type { AskBackend } from "../ai/ask.ts";
+import { resolveAssetMounts } from "../core/assets.ts";
 import type { ResolvedConfig } from "../core/schema.ts";
 import type { ProjectContext } from "../core/types.ts";
 import { searchProviderMeta } from "../search/providers.ts";
@@ -304,10 +305,12 @@ export const astroConfigTemplate = (options: {
   if (needsSvelte) {
     integrations.push("svelte()");
   }
-  // Always mounted: injects user pages (a no-op when there are none) and wires
-  // up dev-server `Accept: text/markdown` negotiation over the content routes.
+  // Always mounted: injects user pages (a no-op when there are none), serves
+  // `content.assets` mounts, and wires up dev-server `Accept: text/markdown`
+  // negotiation over the content routes.
+  const assets = resolveAssetMounts(context.root, config.content.assets);
   integrations.push(
-    `blumeIntegration(${JSON.stringify({ contentRoutes, pages })})`
+    `blumeIntegration(${JSON.stringify({ assets, base: deployment.base, contentRoutes, pages })})`
   );
 
   return `// Generated by Blume. Do not edit; this file is recreated on each run.
@@ -425,7 +428,10 @@ export const collections = { docs${options.staged ? ", staged" : ""} };
 
 /** Generate `.blume/src/pages/[...slug].astro`, the docs catch-all route. */
 /** Generate the Ask AI server endpoint (`.blume/src/pages/api/ask.ts`). */
-export const askEndpointTemplate = (backend: AskBackend): string => {
+export const askEndpointTemplate = (
+  backend: AskBackend,
+  grounded: boolean
+): string => {
   const imports = [
     'import type { APIRoute } from "astro";',
     'import { streamText } from "ai";',
@@ -451,21 +457,61 @@ export const askEndpointTemplate = (backend: AskBackend): string => {
 });\n`;
     modelExpr = `provider(${JSON.stringify(backend.model)})`;
   }
+  // Ground the answer in retrieved docs, except for RAG-native backends (Inkeep),
+  // which run their own retrieval and would conflict with injected context.
+  if (grounded) {
+    imports.push(
+      'import { createAskContext } from "blume/ai/ask-context.ts";',
+      'import askData from "../../generated/ask-data.json";'
+    );
+    setup += "\nconst ground = createAskContext(askData);\n";
+  }
+  // Validate the client-supplied body and cap its size. The endpoint is
+  // unauthenticated, so bounding message count/length limits how much a caller
+  // can spend against the model per request; front it with a rate limiter (or
+  // your provider's limits) for stronger protection.
+  const validate = `  const body = await request.json().catch(() => null);
+  const messages = body?.messages;
+  if (
+    !Array.isArray(messages) ||
+    messages.length === 0 ||
+    messages.length > 40 ||
+    JSON.stringify(messages).length > 24_000
+  ) {
+    return new Response("Invalid request: send 1-40 messages.", {
+      status: 400,
+    });
+  }`;
+  const stream = grounded
+    ? `    const system =
+      (await ground(messages, body.page)) ??
+      "You are a helpful documentation assistant. Answer using the project's documentation.";
+    const result = streamText({
+      model: ${modelExpr},
+      system,
+      messages,
+    });`
+    : `    const result = streamText({
+      model: ${modelExpr},
+      system:
+        "You are a helpful documentation assistant. Answer using the project's documentation.",
+      messages,
+    });`;
+  const handler = `export const POST: APIRoute = async ({ request }) => {
+${validate}
+  try {
+${stream}
+    return result.toTextStreamResponse();
+  } catch {
+    return new Response("Failed to generate a response.", { status: 500 });
+  }
+};`;
   return `// Generated by Blume. Do not edit.
 ${imports.join("\n")}
 
 export const prerender = false;
 ${setup}
-export const POST: APIRoute = async ({ request }) => {
-  const { messages } = await request.json();
-  const result = streamText({
-    model: ${modelExpr},
-    system:
-      "You are a helpful documentation assistant. Answer using the project's documentation.",
-    messages,
-  });
-  return result.toTextStreamResponse();
-};
+${handler}
 `;
 };
 
@@ -721,31 +767,47 @@ const customRoutes = ${JSON.stringify(customRoutes)};
 export function getStaticPaths() {
   const seen = new Set();
   const paths = [];
-  const add = (slug, title, eyebrow) => {
+  const add = (slug, title) => {
     if (seen.has(slug)) {
       return;
     }
     seen.add(slug);
-    paths.push({ params: { slug }, props: { eyebrow, title } });
+    paths.push({ params: { slug }, props: { title } });
   };
   // A custom page wins over a content route sharing its path, so add it first.
   for (const route of customRoutes) {
-    add(route.slug, route.title, route.eyebrow);
+    add(route.slug, route.title);
   }
   for (const route of data.routes) {
-    add(
-      route.path === "/" ? "index" : route.path.slice(1),
-      route.title,
-      data.config.title
-    );
+    add(route.path === "/" ? "index" : route.path.slice(1), route.title);
   }
   return paths;
 }
 
+// Footer branding shared by every card, derived once from the resolved config.
+// The repo slug reuses the header link URL; the host comes from the site URL.
+const repoSlug = data.config.repoUrl
+  ? data.config.repoUrl.split("github.com/")[1]
+  : undefined;
+const siteHost = (() => {
+  if (!data.config.site) {
+    return undefined;
+  }
+  try {
+    return new URL(data.config.site).host;
+  } catch {
+    return undefined;
+  }
+})();
+
 export async function GET({ props }) {
   const png = await renderOgImage({
     accent: data.config.theme.accent,
-    eyebrow: props.eyebrow,
+    brand: data.config.title,
+    description: data.config.description,
+    logo: data.config.logo?.svg,
+    repo: repoSlug,
+    site: siteHost,
     title: props.title,
   });
   return new Response(png, {
@@ -806,6 +868,8 @@ export const catchAllPageTemplate = (options: {
   exportEpub: boolean;
   exportPdf: boolean;
   mathEnabled: boolean;
+  /** Serialize the island-hooks snapshot; only needed when React is enabled. */
+  needsReact: boolean;
 }): string => {
   const askImport = options.askEnabled
     ? 'import AskAI from "blume/components/islands/AskAI.astro";\n'
@@ -817,11 +881,16 @@ export const catchAllPageTemplate = (options: {
     ? 'import Math from "blume/components/content/Math.astro";\n'
     : "";
   const mathEntry = options.mathEnabled ? "Math,\n  " : "";
+  // The island-hooks snapshot (config + navigation + page) for `blume/hooks`.
+  const clientData = options.needsReact
+    ? "\n  clientData={{ config: data.config, navigation, page: { route, title: seo.title ?? title } }}"
+    : "";
 
   return `---
 // Generated by Blume. Do not edit.
 import { getEntry, render } from "astro:content";
 import RootLayout from "blume/components/layout/RootLayout.astro";
+import { resolveSlot } from "blume/components/layout/overrides.ts";
 ${askImport}
 import Accordion from "blume/components/content/Accordion.astro";
 import AccordionItem from "blume/components/content/AccordionItem.astro";
@@ -856,6 +925,7 @@ import TreeFile from "blume/components/content/TreeFile.astro";
 import TreeFolder from "blume/components/content/TreeFolder.astro";
 import TypeTable from "blume/components/content/TypeTable.astro";
 import Visibility from "blume/components/content/Visibility.astro";
+import YouTube from "blume/components/content/YouTube.astro";
 import Icon from "blume/components/Icon.astro";
 ${mathImport}import { mdxComponents as userMdx, layoutOverrides } from "../generated/components.ts";
 import { islandComponents } from "../generated/islands.ts";
@@ -901,6 +971,7 @@ const components = {
   Tree,
   TypeTable,
   Visibility,
+  YouTube,
   ${mathEntry}...islandComponents,
   ...userMdx,
 };
@@ -997,11 +1068,15 @@ const localeSwitch = i18n
       };
     })
   : [];
+
+// The whole page shell is overridable via \`layout.Layout\`; it receives the same
+// props as the built-in RootLayout, plus the \`layout\` map for its inner slots.
+const LayoutComponent = resolveSlot(layoutOverrides.Layout, RootLayout);
 ---
 
-<RootLayout
+<LayoutComponent
   site={{ title: data.config.title, description: data.config.description }}
-  layout={layoutOverrides}
+  layout={layoutOverrides}${clientData}
   logo={data.config.logo}
   mcp={data.config.mcp}
   favicon={data.config.favicon}
@@ -1020,6 +1095,7 @@ const localeSwitch = i18n
   localeSwitch={localeSwitch}
   page={{ title: seo.title ?? title, description: seo.description ?? frontmatter.description, route }}
   headings={headings}
+  toc={data.config.toc}
   themeMode={data.config.theme.mode}
   fontCssVars={data.fontCssVars}
   searchEnabled={data.config.search.enabled}
@@ -1042,7 +1118,7 @@ const localeSwitch = i18n
   <h1>{title}</h1>
   {frontmatter.description && <p class="text-lg text-muted-foreground">{frontmatter.description}</p>}
   <Content components={components} />
-</RootLayout>
+</LayoutComponent>
 `;
 };
 
@@ -1056,6 +1132,8 @@ export const changelogIndexTemplate = (options: {
   askEnabled: boolean;
   exportEpub: boolean;
   exportPdf: boolean;
+  /** Serialize the island-hooks snapshot; only needed when React is enabled. */
+  needsReact: boolean;
   /** Whether a `staged` collection exists (non-filesystem changelog sources). */
   staged: boolean;
 }): string => {
@@ -1063,6 +1141,9 @@ export const changelogIndexTemplate = (options: {
     ? 'import AskAI from "blume/components/islands/AskAI.astro";\n'
     : "";
   const askSlot = options.askEnabled ? '\n  <AskAI slot="ask" />' : "";
+  const clientData = options.needsReact
+    ? '\n  clientData={{ config: data.config, navigation: data.navigation, page: { route: "/changelog", title: data.config.title + " changelog" } }}'
+    : "";
   // Staged sources (e.g. GitHub Releases) render through a parallel collection,
   // so fold them in alongside filesystem entries when one exists.
   const stagedSpread = options.staged
@@ -1074,6 +1155,7 @@ export const changelogIndexTemplate = (options: {
 import { getCollection, render } from "astro:content";
 import RootLayout from "blume/components/layout/RootLayout.astro";
 import Update from "blume/components/content/Update.astro";
+import { resolveSlot } from "blume/components/layout/overrides.ts";
 import { layoutOverrides } from "../generated/components.ts";
 ${askImport}import data from "../generated/data.json";
 
@@ -1145,11 +1227,13 @@ const headings = items.map((item) => ({
 
 const base = data.config.site ? data.config.site.replace(/\\/$/, "") : null;
 const canonical = base ? base + "/changelog" : null;
+
+const LayoutComponent = resolveSlot(layoutOverrides.Layout, RootLayout);
 ---
 
-<RootLayout
+<LayoutComponent
   site={{ title: data.config.title, description: data.config.description }}
-  layout={layoutOverrides}
+  layout={layoutOverrides}${clientData}
   logo={data.config.logo}
   mcp={data.config.mcp}
   favicon={data.config.favicon}
@@ -1165,6 +1249,7 @@ const canonical = base ? base + "/changelog" : null;
     route: "/changelog",
   }}
   headings={headings}
+  toc={data.config.toc}
   themeMode={data.config.theme.mode}
   fontCssVars={data.fontCssVars}
   searchEnabled={data.config.search.enabled}
@@ -1193,7 +1278,7 @@ const canonical = base ? base + "/changelog" : null;
       </div>
     )
   }
-</RootLayout>
+</LayoutComponent>
 `;
 };
 
@@ -1245,27 +1330,6 @@ const nf = data.ui.notFound;
 </PageLayout>
 `;
 
-/**
- * Generate `.blume/src/generated/components.ts`, which re-exports the user's
- * component overrides (or empty maps when no `components.ts` exists). Importing
- * the user file here lets Astro/Vite compile any `.astro`/`.tsx` it references.
- */
-export const userComponentsTemplate = (
-  componentsFile: string | null
-): string => {
-  if (!componentsFile) {
-    return `// Generated by Blume. Do not edit.
-export const mdxComponents = {};
-export const layoutOverrides = {};
-`;
-  }
-  return `// Generated by Blume. Do not edit.
-import overrides from ${JSON.stringify(componentsFile)};
-export const mdxComponents = overrides.mdx ?? {};
-export const layoutOverrides = overrides.layout ?? {};
-`;
-};
-
 /** The literal Astro hydration directive for an island's client mode. */
 const islandDirective = (spec: IslandSpec): string =>
   spec.client === "only"
@@ -1383,6 +1447,12 @@ declare module "blume:data" {
   const data: import("blume").BlumeData;
   export default data;
 }
+
+declare module "blume:search-client" {
+  export const createSearch: () =>
+    | import("blume/components/layout/search/types.ts").SearchFn
+    | Promise<import("blume/components/layout/search/types.ts").SearchFn>;
+}
 `;
 
 /** Generate `.blume/package.json`. */

package/src/blume-modules.d.ts

@@ -0,0 +1,25 @@
+// Ambient types for Blume's generated virtual modules, so package sources that
+// consume them (e.g. the island hooks importing `blume:search-client`) typecheck.
+// This file is not part of the published `dist/types` (which is emitted only from
+// the public entry points), so it can't leak into a consumer's typecheck; the
+// generated `.blume/src/env.d.ts` declares the same module for that context.
+//
+// `import()` types (not a top-level `import`) keep this a global script, so the
+// `declare module` stays an ambient declaration visible across the package.
+
+declare module "blume:search-client" {
+  /** Create the configured provider's query function (may be async to build). */
+  // biome-ignore lint/style/useImportType: ambient module must stay a global script
+  // oxlint-disable-next-line typescript/consistent-type-imports
+  type Fn = import("./components/layout/search/types.ts").SearchFn;
+  export const createSearch: () => Fn | Promise<Fn>;
+}
+
+// Package-only shim so `components/props.ts` can extract `.astro` prop types with
+// `ComponentProps<typeof import("./X.astro").default>` under the package's own
+// `tsc` (where the Astro TS plugin isn't active). Not shipped in `dist/types`, so
+// consumers keep Astro's real `.astro` types and get the true prop shapes.
+declare module "*.astro" {
+  const component: (props: Record<string, unknown>) => unknown;
+  export default component;
+}

package/src/cli/args.ts

@@ -0,0 +1,23 @@
+import { logger } from "./log.ts";
+
+const MAX_PORT = 65_535;
+
+/**
+ * Parse a `--port` value into a valid port number, or `undefined` when unset.
+ * A non-integer or out-of-range value (`--port abc` → `NaN`) exits with an
+ * error rather than propagating `localhost:NaN` into the dev server and the
+ * `deployment.site` fallback.
+ */
+export const parsePort = (value?: string): number | undefined => {
+  if (value === undefined) {
+    return;
+  }
+  const port = Number(value);
+  if (!(Number.isInteger(port) && port >= 1 && port <= MAX_PORT)) {
+    logger.error(
+      `Invalid --port "${value}" (expected an integer 1-${MAX_PORT}).`
+    );
+    process.exit(1);
+  }
+  return port;
+};

package/src/cli/commands/build.ts

@@ -1,21 +1,200 @@
 import { existsSync } from "node:fs";
-import { writeFile } from "node:fs/promises";
+import { readdir, stat, writeFile } from "node:fs/promises";
 
 import { build } from "astro";
 import { defineCommand } from "citty";
 import { join } from "pathe";
 
 import { buildLlmsFiles } from "../../ai/llms.ts";
+import type { ResolvedConfig } from "../../core/schema.ts";
 import { serverFeatures } from "../../core/server-features.ts";
+import {
+  buildNetlifyRedirects,
+  buildRedirectManifest,
+  buildVercelConfig,
+} from "../../deploy/redirects.ts";
 import { buildRobots } from "../../deploy/robots.ts";
 import { buildSitemap } from "../../deploy/sitemap.ts";
 import { buildSearchIndex } from "../../search/build.ts";
 import { syncSearchProvider } from "../../search/sync/index.ts";
+import { refuseIfDevRunning } from "../dev-lock.ts";
 import { logger } from "../log.ts";
 import { prepareProject } from "../prepare.ts";
 
+const ADAPTERS = ["vercel", "node", "netlify", "cloudflare"] as const;
+
+/**
+ * Reject a non-numeric performance budget. `Number("250kb")` is `NaN` and
+ * `total > NaN` is always false, so a typo'd flag would silently pass the gate;
+ * fail up front instead.
+ */
+const validateBudgetFlags = (args: {
+  "budget-css"?: string;
+  "budget-js"?: string;
+}): void => {
+  for (const flag of ["budget-js", "budget-css"] as const) {
+    const value = args[flag];
+    if (value !== undefined && !(Number(value) > 0)) {
+      logger.error(
+        `Invalid --${flag} "${value}" (expected a positive number of kB).`
+      );
+      process.exit(1);
+    }
+  }
+};
+
+/**
+ * Emit platform redirect files for a static build (adapters wire redirects
+ * natively). Always writes the manifest; writes `_redirects`/`vercel.json` only
+ * when the user hasn't shipped one via public/.
+ */
+const emitRedirectFiles = async (
+  config: ResolvedConfig,
+  distDir: string
+): Promise<void> => {
+  const { redirects } = config;
+  if (redirects.length === 0 || config.deployment.output !== "static") {
+    return;
+  }
+  await writeFile(
+    join(distDir, "blume-redirects.json"),
+    buildRedirectManifest(redirects),
+    "utf-8"
+  );
+  const platformFiles = [
+    { content: buildNetlifyRedirects(redirects), name: "_redirects" },
+    { content: buildVercelConfig(redirects), name: "vercel.json" },
+  ];
+  await Promise.all(
+    platformFiles.map((file) =>
+      existsSync(join(distDir, file.name))
+        ? Promise.resolve()
+        : writeFile(join(distDir, file.name), file.content, "utf-8")
+    )
+  );
+  logger.success(`Emitted redirect files for ${redirects.length} redirect(s)`);
+};
+
+const formatBytes = (bytes: number): string =>
+  bytes < 1024
+    ? `${bytes} B`
+    : `${(bytes / 1024).toFixed(bytes < 1024 * 100 ? 1 : 0)} kB`;
+
+/** Sizes of `dist/_astro/*.<ext>`, largest first (empty when none exist). */
+const astroAssets = async (
+  distDir: string,
+  ext: string
+): Promise<{ name: string; size: number }[]> => {
+  const astroDir = join(distDir, "_astro");
+  if (!existsSync(astroDir)) {
+    return [];
+  }
+  const entries = await readdir(astroDir);
+  const files = entries.filter((name) => name.endsWith(`.${ext}`));
+  const sized = await Promise.all(
+    files.map(async (name) => {
+      const info = await stat(join(astroDir, name));
+      return { name, size: info.size };
+    })
+  );
+  return sized.toSorted((a, b) => b.size - a.size);
+};
+
+const totalSize = (assets: { size: number }[]): number =>
+  assets.reduce((sum, asset) => sum + asset.size, 0);
+
+/**
+ * Print the client JavaScript Astro shipped, largest first, plus the total. A
+ * dependency-free bundle report — the interactive weight of a docs site is its
+ * `_astro/*.js`, so this surfaces regressions without a visualizer.
+ */
+const reportBundleSizes = async (distDir: string): Promise<void> => {
+  const sized = await astroAssets(distDir, "js");
+  if (sized.length === 0) {
+    logger.info("No client JavaScript emitted — the site ships zero JS.");
+    return;
+  }
+  const rows = sized
+    .slice(0, 15)
+    .map((file) => `  ${formatBytes(file.size).padStart(8)}  ${file.name}`);
+  logger.box(
+    [
+      `Client JavaScript — ${sized.length} file(s), ${formatBytes(totalSize(sized))} total`,
+      "",
+      ...rows,
+      sized.length > 15 ? `  … and ${sized.length - 15} more` : null,
+    ]
+      .filter((line) => line !== null)
+      .join("\n")
+  );
+};
+
+/**
+ * Enforce a performance budget on the built client assets: fail the build when
+ * total `_astro/*.js` (or `*.css`) exceeds the given kB cap. Budgets that would
+ * otherwise be "documented, not measured" become a real CI gate. Returns whether
+ * every budget passed.
+ */
+const enforceBudget = async (
+  distDir: string,
+  args: { "budget-css"?: string; "budget-js"?: string }
+): Promise<"fail" | "pass" | "skip"> => {
+  const checks: { ext: string; limitKb: number; name: string }[] = [
+    ...(args["budget-js"]
+      ? [{ ext: "js", limitKb: Number(args["budget-js"]), name: "JavaScript" }]
+      : []),
+    ...(args["budget-css"]
+      ? [{ ext: "css", limitKb: Number(args["budget-css"]), name: "CSS" }]
+      : []),
+  ];
+  if (checks.length === 0) {
+    return "skip";
+  }
+  let passed = true;
+  for (const check of checks) {
+    // oxlint-disable-next-line no-await-in-loop -- a couple of sequential reads
+    const total = totalSize(await astroAssets(distDir, check.ext));
+    const limit = check.limitKb * 1024;
+    if (total > limit) {
+      passed = false;
+      logger.error(
+        `${check.name} budget exceeded: ${formatBytes(total)} > ${check.limitKb} kB`
+      );
+    } else {
+      logger.success(
+        `${check.name} budget: ${formatBytes(total)} / ${check.limitKb} kB`
+      );
+    }
+  }
+  return passed ? "pass" : "fail";
+};
+
 export const buildCommand = defineCommand({
   args: {
+    adapter: {
+      description: "Server adapter: vercel | node | netlify | cloudflare.",
+      type: "string",
+    },
+    analyze: {
+      description: "Report client JavaScript bundle sizes after the build.",
+      type: "boolean",
+    },
+    base: {
+      description: "Base path the site is served under (e.g. /docs).",
+      type: "string",
+    },
+    "budget-css": {
+      description: "Fail if total client CSS exceeds this many kB.",
+      type: "string",
+    },
+    "budget-js": {
+      description: "Fail if total client JavaScript exceeds this many kB.",
+      type: "string",
+    },
+    output: {
+      description: "Output mode: static | server.",
+      type: "string",
+    },
     preview: {
       description: "Include drafts and unpublished CMS content.",
       type: "boolean",
@@ -28,8 +207,27 @@ export const buildCommand = defineCommand({
   },
   async run({ args }) {
     const root = process.cwd();
+    refuseIfDevRunning(root, "building");
+
+    if (args.output && args.output !== "static" && args.output !== "server") {
+      logger.error(`Invalid --output "${args.output}" (use static | server).`);
+      process.exit(1);
+    }
+    if (args.adapter && !ADAPTERS.includes(args.adapter as never)) {
+      logger.error(
+        `Invalid --adapter "${args.adapter}" (use ${ADAPTERS.join(" | ")}).`
+      );
+      process.exit(1);
+    }
+    validateBudgetFlags(args);
+
     const project = await prepareProject({
       mode: "build",
+      overrides: {
+        adapter: args.adapter as (typeof ADAPTERS)[number] | undefined,
+        base: args.base,
+        output: args.output as "server" | "static" | undefined,
+      },
       preview: args.preview,
       root,
       strict: args.strict,
@@ -82,6 +280,8 @@ export const buildCommand = defineCommand({
       logger.success("Generated robots.txt");
     }
 
+    await emitRedirectFiles(project.config, distDir);
+
     const { config } = project;
     const features = serverFeatures(config);
     logger.box(
@@ -98,6 +298,14 @@ export const buildCommand = defineCommand({
       ].join("\n")
     );
 
+    if (args.analyze) {
+      await reportBundleSizes(distDir);
+    }
+
+    if ((await enforceBudget(distDir, args)) === "fail") {
+      process.exit(1);
+    }
+
     logger.success(`Built to ${distDir}`);
   },
 });