blume 0.2.0 → 0.3.0

package/src/astro/templates.ts

@@ -425,7 +425,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,12 +454,29 @@ export const askEndpointTemplate = (backend: AskBackend): string => {
 });\n`;
     modelExpr = `provider(${JSON.stringify(backend.model)})`;
   }
-  return `// Generated by Blume. Do not edit.
-${imports.join("\n")}
-
-export const prerender = false;
-${setup}
-export const POST: APIRoute = async ({ request }) => {
+  // 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";
+  }
+  const handler = grounded
+    ? `export const POST: APIRoute = async ({ request }) => {
+  const { messages, page } = await request.json();
+  const system =
+    (await ground(messages, page)) ??
+    "You are a helpful documentation assistant. Answer using the project's documentation.";
+  const result = streamText({
+    model: ${modelExpr},
+    system,
+    messages,
+  });
+  return result.toTextStreamResponse();
+};`
+    : `export const POST: APIRoute = async ({ request }) => {
   const { messages } = await request.json();
   const result = streamText({
     model: ${modelExpr},
@@ -465,7 +485,13 @@ export const POST: APIRoute = async ({ request }) => {
     messages,
   });
   return result.toTextStreamResponse();
-};
+};`;
+  return `// Generated by Blume. Do not edit.
+${imports.join("\n")}
+
+export const prerender = false;
+${setup}
+${handler}
 `;
 };
 
@@ -721,31 +747,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 +848,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 +861,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";
@@ -997,11 +1046,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 +1073,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 +1096,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 +1110,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 +1119,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 +1133,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 +1205,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 +1227,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 +1256,7 @@ const canonical = base ? base + "/changelog" : null;
       </div>
     )
   }
-</RootLayout>
+</LayoutComponent>
 `;
 };
 
@@ -1245,27 +1308,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 +1425,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/commands/build.ts

@@ -1,12 +1,18 @@
 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";
@@ -14,8 +20,160 @@ import { syncSearchProvider } from "../../search/sync/index.ts";
 import { logger } from "../log.ts";
 import { prepareProject } from "../prepare.ts";
 
+const ADAPTERS = ["vercel", "node", "netlify", "cloudflare"] as const;
+
+/**
+ * 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 +186,25 @@ export const buildCommand = defineCommand({
   },
   async run({ args }) {
     const root = process.cwd();
+
+    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);
+    }
+
     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 +257,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 +275,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}`);
   },
 });

package/src/cli/commands/check.ts

@@ -0,0 +1,62 @@
+import { existsSync } from "node:fs";
+
+import { check } from "@astrojs/check";
+import { sync } from "astro";
+import { defineCommand } from "citty";
+import { join } from "pathe";
+
+import { logger } from "../log.ts";
+import { prepareProject } from "../prepare.ts";
+
+export const checkCommand = defineCommand({
+  args: {
+    preview: {
+      description: "Include drafts and unpublished CMS content.",
+      type: "boolean",
+    },
+    strict: {
+      description: "Fail on content diagnostics as well as type errors.",
+      type: "boolean",
+    },
+  },
+  meta: {
+    description: "Type-check the docs site with astro check.",
+    name: "check",
+  },
+  async run({ args }) {
+    const root = process.cwd();
+    const project = await prepareProject({
+      mode: "build",
+      preview: args.preview,
+      root,
+      strict: args.strict,
+    });
+
+    const { outDir } = project.context;
+
+    // Generate Astro's content/collection and font types into `.blume/.astro`
+    // so `astro:*` virtual modules resolve during the check.
+    await sync({ logLevel: "warn", root: outDir });
+
+    // The project-root tsconfig is what covers the authored `pages/` and config;
+    // without it astro check only sees the generated `.blume` project. Falls back
+    // to the generated project's own tsconfig when the project has none.
+    const tsconfig = join(root, "tsconfig.json");
+
+    logger.start(`Type-checking ${project.graph.pages.length} page(s)`);
+    const failed = await check({
+      minimumFailingSeverity: "error",
+      minimumSeverity: "hint",
+      root: outDir,
+      tsconfig: existsSync(tsconfig) ? tsconfig : undefined,
+      watch: false,
+    });
+
+    if (failed) {
+      logger.error("Type check failed.");
+      process.exit(1);
+    }
+
+    logger.success("No type errors.");
+  },
+});

package/src/cli/commands/dev.ts

@@ -4,12 +4,21 @@ import { dev } from "astro";
 import { defineCommand } from "citty";
 
 import { generateRuntime } from "../../astro/generate.ts";
+import { showBlumeErrorOverlay } from "../../astro/integration.ts";
 import { scanProject } from "../../core/project-graph.ts";
 import { logger } from "../log.ts";
 import { prepareProject } from "../prepare.ts";
 
 export const devCommand = defineCommand({
   args: {
+    "content-dir": {
+      description: "Content folder to scan, overriding config (content.root).",
+      type: "string",
+    },
+    debug: {
+      description: "Verbose Astro/Vite logging for troubleshooting.",
+      type: "boolean",
+    },
     host: { description: "Network host to bind.", type: "string" },
     open: { description: "Open the browser on start.", type: "boolean" },
     port: { description: "Port to listen on.", type: "string" },
@@ -26,6 +35,9 @@ export const devCommand = defineCommand({
   async run({ args }) {
     const root = process.cwd();
     const preview = args.preview ?? false;
+    const overrides = args["content-dir"]
+      ? { contentRoot: args["content-dir"] }
+      : undefined;
     // Astro's dev server defaults to 4321 when no port is passed. Feeding the
     // resolved URL in as the `deployment.site` fallback lets site-gated features
     // (OG images, canonicals, sitemap) work locally without configuring a site.
@@ -34,6 +46,7 @@ export const devCommand = defineCommand({
     const project = await prepareProject({
       devServerUrl,
       mode: "dev",
+      overrides,
       preview,
       root,
       strict: args.strict,
@@ -46,7 +59,7 @@ export const devCommand = defineCommand({
     }
 
     const server = await dev({
-      logLevel: "info",
+      logLevel: args.debug ? "debug" : "info",
       root: project.context.outDir,
       server: {
         host: args.host ?? false,
@@ -55,6 +68,10 @@ export const devCommand = defineCommand({
       },
     });
 
+    // Mirror any initial diagnostics into the browser overlay now the server
+    // (and its HMR channel) is up.
+    showBlumeErrorOverlay(project.diagnostics);
+
     // Watch user inputs and regenerate the runtime data on change. Astro/Vite
     // hot-reloads the generated data module so nav and routes stay in sync.
     let timer: ReturnType<typeof setTimeout> | null = null;
@@ -67,9 +84,12 @@ export const devCommand = defineCommand({
           const next = await scanProject(root, {
             devServerUrl,
             mode: "dev",
+            overrides,
             preview,
           });
           await generateRuntime(next);
+          // Surface any content/config errors in the browser overlay too.
+          showBlumeErrorOverlay(next.diagnostics);
         } catch (error) {
           logger.error(`Regeneration failed: ${(error as Error).message}`);
         }