blume 1.6.5 → 1.6.6

package/src/astro/templates.ts

@@ -19,7 +19,7 @@ import { hasScalarReferences } from "../openapi/references.ts";
 import { searchProviderMeta } from "../search/providers.ts";
 import { buildFontEntries, fontLocaleCodes } from "../theme/fonts.ts";
 import type { ExampleSpec } from "./examples.ts";
-import type { BlumePageRoute } from "./integration.ts";
+import type { BlumeIntegrationOptions, BlumePageRoute } from "./integration.ts";
 import type { IslandSpec } from "./islands.ts";
 import type { OgCustomRoute } from "./pages.ts";
 import { RUNTIME_MODULE_FILES } from "./runtime-modules.ts";
@@ -125,30 +125,24 @@ const resolveCloudflareAdapterArgs = (context: ProjectContext): string => {
  * Without a configured driver, `@astrojs/cloudflare` force-enables KV-backed
  * sessions and declares a `SESSION` kv_namespaces entry in the generated
  * wrangler config — which `wrangler deploy` then requires a real KV namespace
- * for, even though Blume never reads `Astro.session`. An explicit in-memory
- * driver keeps the binding out. Swap for Astro's session opt-out once
- * withastro/astro#16871 ships in the supported range.
+ * for, even though Blume never reads `Astro.session`. Astro's `session: false`
+ * opts the project out, and the adapter checks for it before adding the
+ * binding. (An in-memory driver used to stand in before the opt-out existed.)
  */
 const resolveSessionOption = (deployment: {
   adapter: string | null;
   output: string;
 }): string =>
   deployment.output === "server" && deployment.adapter === "cloudflare"
-    ? "\n  session: { driver: sessionDrivers.memory() },"
+    ? "\n  session: false,"
     : "";
 
 /** The named imports the generated config pulls from `astro/config`. */
-const astroConfigImportLine = (options: {
-  hasFonts: boolean;
-  hasSession: boolean;
-}): string => {
+const astroConfigImportLine = (options: { hasFonts: boolean }): string => {
   const names = ["defineConfig"];
   if (options.hasFonts) {
     names.push("fontProviders");
   }
-  if (options.hasSession) {
-    names.push("sessionDrivers");
-  }
   return `import { ${names.join(", ")} } from "astro/config";`;
 };
 
@@ -458,6 +452,33 @@ const renderRuntimeModuleWiring = (
   return { aliasLines, imports: [], pluginEntry: "" };
 };
 
+/**
+ * The options baked into the generated config's `blumeIntegration(...)` call.
+ * The hidden runtime gets the content routes and homepage `Link` header from
+ * the CLI in memory (`publishDevNegotiation`, republished on every
+ * regeneration), so a content-route change never rewrites the config — Astro
+ * restarts the dev server in place on a config change — and its scanned
+ * project from `blume build` for the deploy artifacts. An ejected project has
+ * no CLI, so the negotiation inputs are baked in and `astro:build:done` scans
+ * the project root (the Astro root, after eject) for the artifacts.
+ */
+const blumeIntegrationOptions = (options: {
+  config: ResolvedConfig;
+  contentRoutes: string[];
+  ejected: boolean;
+  pages: BlumePageRoute[];
+}): BlumeIntegrationOptions =>
+  options.ejected
+    ? {
+        buildArtifactsRoot: ".",
+        contentRoutes: options.contentRoutes,
+        homeLinkHeader:
+          buildHomeLinkHeader(options.config, options.contentRoutes) ??
+          undefined,
+        pages: options.pages,
+      }
+    : { pages: options.pages };
+
 export const astroConfigTemplate = (options: {
   context: ProjectContext;
   config: ResolvedConfig;
@@ -567,7 +588,9 @@ export const astroConfigTemplate = (options: {
     : "";
   const imageOption = renderImageOption(config);
 
-  // Astro's native i18n gives locale-aware helpers + `<html lang>` correctness.
+  // Astro's native i18n resolves `Astro.currentLocale` from the URL, which the
+  // document shells fall back to for `<html lang>`/`dir` on pages the content
+  // catch-all doesn't drive (custom pages, the 404, the reference shell).
   // Blume owns getStaticPaths and materializes fallback routes in the manifest,
   // so we deliberately omit Astro's `fallback` to keep one source of routing.
   const i18nOption = config.i18n
@@ -653,7 +676,6 @@ export const astroConfigTemplate = (options: {
     : "";
   const defineConfigImport = astroConfigImportLine({
     hasFonts: fontEntries.length > 0,
-    hasSession: sessionOption.length > 0,
   });
 
   // Framework renderers are only wired in when an island (or Ask AI, for React)
@@ -710,12 +732,14 @@ export const astroConfigTemplate = (options: {
   // up dev-server `Accept: text/markdown` negotiation over the content routes,
   // plus the homepage agent-discovery `Link` header.
   integrations.push(
-    `blumeIntegration(${JSON.stringify({
-      base: deployment.base,
-      contentRoutes,
-      homeLinkHeader: buildHomeLinkHeader(config, contentRoutes) ?? undefined,
-      pages,
-    })})`
+    `blumeIntegration(${JSON.stringify(
+      blumeIntegrationOptions({
+        config,
+        contentRoutes,
+        ejected: generatedModulesDir !== undefined,
+        pages,
+      })
+    )})`
   );
 
   const {
@@ -758,6 +782,14 @@ ${userConfigSetup}export default defineConfig({
     },
   },
   devToolbar: { enabled: false },
+  // One canonical URL per page: canonicals, the sitemap, and hreflang all use
+  // the slashless form, so the slashed spelling is not a second address. Astro
+  // applies this itself — its dev server answers a slashed URL with a 404 that
+  // names the setting, an on-demand route redirects — and the Vercel adapter
+  // turns it into the platform's 308 route, so the Build Output config needs
+  // no hand-spliced redirect (see deploy/vercel-negotiation.ts). Static hosts
+  // serve the \`index.html\` directory layout as they always did.
+  trailingSlash: "never",
   // The layouts render Astro's <ClientRouter />, and its in-place swaps read
   // from the prefetch cache — fetching every link on hover/viewport hides the
   // request latency behind the user's intent, so most navigations swap
@@ -924,6 +956,7 @@ const staged = defineCollection({
     base: ${JSON.stringify(astroGlobBase(stagedBase))},
     generateId: ({ entry }) => entry,
   }),
+  schema: pageCollectionSchema,
 });
 `
     : "";
@@ -932,16 +965,22 @@ const staged = defineCollection({
 import { defineCollection } from "astro:content";
 import { glob } from "astro/loaders";
 import { withIncludeRefresh } from "blume/astro";
+import { pageCollectionSchema } from "blume/core/schema.ts";
 
 // withIncludeRefresh keeps <include>-bearing pages fresh: plain .md entries
 // are rendered at sync time and digest-cached on the page file alone, so a
 // partial edit (or a warm-cache rebuild after one) would serve stale HTML.
+//
+// pageCollectionSchema is the scan's page front-matter schema, so entry.data
+// is typed and normalized the same way; it passes custom keys through and
+// falls back to defaults for a page the scan already dropped as invalid.
 const docs = defineCollection({
   loader: withIncludeRefresh(glob({
     pattern: ${JSON.stringify(docsPattern)},
     base: ${JSON.stringify(astroGlobBase(collectionBase))},
     generateId: ({ entry }) => entry,
   }), ${JSON.stringify(`${context.outDir}/src/generated/includes.json`)}),
+  schema: pageCollectionSchema,
 });
 ${stagedBlock}
 export const collections = { docs${options.staged ? ", staged" : ""} };
@@ -980,26 +1019,38 @@ export const askEndpointTemplate = (
   const fallbackPrompt = instructions
     ? `${ASK_FALLBACK_PROMPT}\n\n${instructions}`
     : ASK_FALLBACK_PROMPT;
+  // Secrets go through Astro's `getSecret` rather than `process.env`, so each
+  // adapter supplies them its own way (Cloudflare from the Worker's bindings,
+  // Node and Vercel from the environment).
   const imports = [
     'import type { APIRoute } from "astro";',
-    'import { streamText } from "ai";',
+    'import { getSecret } from "astro:env/server";',
+    // The gateway provider reads the key (or Vercel's OIDC token) from the
+    // environment itself; passing the key explicitly lets a binding-backed
+    // secret store reach it too.
+    backend.kind === "gateway"
+      ? 'import { createGateway, streamText } from "ai";'
+      : 'import { streamText } from "ai";',
   ];
   let setup = "";
   let modelExpr = JSON.stringify(backend.model);
-  if (backend.kind === "openrouter") {
+  if (backend.kind === "gateway") {
+    setup = `\nconst gateway = createGateway({ apiKey: getSecret("AI_GATEWAY_API_KEY") });\n`;
+    modelExpr = `gateway(${JSON.stringify(backend.model)})`;
+  } else if (backend.kind === "openrouter") {
     imports.push(
       'import { createOpenRouter } from "@openrouter/ai-sdk-provider";'
     );
-    setup = `\nconst openrouter = createOpenRouter({ apiKey: process.env[${JSON.stringify(
+    setup = `\nconst openrouter = createOpenRouter({ apiKey: getSecret(${JSON.stringify(
       backend.apiKeyEnv
-    )}] });\n`;
+    )}) });\n`;
     modelExpr = `openrouter(${JSON.stringify(backend.model)})`;
   } else if (backend.kind === "openai-compatible") {
     imports.push(
       'import { createOpenAICompatible } from "@ai-sdk/openai-compatible";'
     );
     setup = `\nconst provider = createOpenAICompatible({
-  apiKey: process.env[${JSON.stringify(backend.apiKeyEnv)}],
+  apiKey: getSecret(${JSON.stringify(backend.apiKeyEnv)}),
   baseURL: ${JSON.stringify(backend.baseUrl)},
   name: ${JSON.stringify(backend.name)},
 });\n`;
@@ -1062,13 +1113,13 @@ export const askEndpointTemplate = (
   const keyCheck =
     backend.kind === "gateway"
       ? `  // The AI Gateway authenticates with an API key or Vercel's OIDC token.
-  if (!(process.env.AI_GATEWAY_API_KEY || process.env.VERCEL_OIDC_TOKEN)) {
+  if (!(getSecret("AI_GATEWAY_API_KEY") || getSecret("VERCEL_OIDC_TOKEN"))) {
     return new Response(
       "Ask AI is not configured: set AI_GATEWAY_API_KEY (or deploy on Vercel with OIDC).",
       { status: 500 }
     );
   }`
-      : `  if (!process.env[${JSON.stringify(backend.apiKeyEnv)}]) {
+      : `  if (!getSecret(${JSON.stringify(backend.apiKeyEnv)})) {
     return new Response(
       ${JSON.stringify(`Ask AI is not configured: set ${backend.apiKeyEnv}.`)},
       { status: 500 }
@@ -1176,8 +1227,9 @@ const searchClientImport = (module: string): string =>
   `import { createSearch as create } from "blume/components/layout/search/${module}.ts";\n`;
 
 // Joins a base-relative path onto BASE_URL, which arrives with or without a
-// trailing slash (Astro's default trailingSlash: "ignore" passes `/docs`
-// through bare — naive concatenation would yield `/docsblume-search.json`).
+// trailing slash (Astro normalizes `base` by `trailingSlash`, which the
+// generated config pins to "never" but an owned config may set either way —
+// naive concatenation of a bare `/docs` would yield `/docsblume-search.json`).
 const SEARCH_BASE_IMPORT =
   'import { joinBase } from "blume/components/islands/base-path.ts";\n';
 
@@ -1291,11 +1343,12 @@ export const createSearch = () => create({ url });
 export const mixedbreadSearchEndpointTemplate = (storeId: string): string =>
   `// Generated by Blume. Do not edit.
 import type { APIRoute } from "astro";
+import { getSecret } from "astro:env/server";
 import Mixedbread from "@mixedbread/sdk";
 
 export const prerender = false;
 
-const client = new Mixedbread({ apiKey: process.env.MIXEDBREAD_API_KEY ?? "" });
+const client = new Mixedbread({ apiKey: getSecret("MIXEDBREAD_API_KEY") ?? "" });
 const STORE_ID = ${JSON.stringify(storeId)};
 
 export const POST: APIRoute = async ({ request }) => {
@@ -1883,9 +1936,9 @@ const headings =
   tocHidden.size > 0
     ? allHeadings.filter((heading) => !tocHidden.has(heading.slug))
     : allHeadings;
-const frontmatter = entry.data ?? {};
+const frontmatter = entry.data;
 
-const seo = frontmatter.seo ?? {};
+const seo = frontmatter.seo;
 const base = data.config.site ? data.config.site.replace(/\\/$/, "") : null;
 
 // Percent-encode the route-derived path (the sitemap convention): a Unicode
@@ -3037,71 +3090,6 @@ const Example = entry.Component;
 </html>
 `;
 
-/** Generate `.blume/src/env.d.ts`. */
-export const envTemplate =
-  (): string => `/// <reference path="../.astro/types.d.ts" />
-/// <reference types="astro/client" />
-
-declare module "blume:ask" {
-  const Ask: typeof import("blume/components/islands/AskAI.astro").default;
-  export default Ask;
-}
-
-declare module "blume:data" {
-  const data: import("blume").BlumeData;
-  export default data;
-}
-
-declare module "blume:ask-data" {
-  const askData: import("blume/ai/ask-context.ts").AskData;
-  export default askData;
-}
-
-declare module "blume:content-assets" {
-  const assets: Record<string, string>;
-  export default assets;
-}
-
-declare module "blume:mcp-data" {
-  const data: import("blume/ai/mcp/data.ts").McpData;
-  export default data;
-}
-
-declare module "blume:raw-markdown" {
-  const raw: Record<string, import("blume/ai/markdown.ts").RawMarkdownEntry>;
-  export default raw;
-}
-
-declare module "blume:rss" {
-  const feeds: Record<string, string>;
-  export default feeds;
-}
-
-declare module "blume:search-index" {
-  const documents: import("blume/search/documents.ts").SearchDocument[];
-  export default documents;
-}
-
-declare module "blume:examples" {
-  type Examples = typeof import("./generated/examples.ts").examples;
-  export const examples: Record<string, Examples[keyof Examples]>;
-  export const examplesBase: string;
-}
-
-declare module "blume:examples-theme";
-
-declare module "blume:openapi" {
-  const specs: import("blume/openapi/model.ts").OpenApiData;
-  export default specs;
-}
-
-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`. */
 export const runtimePackageTemplate = (dependencies: string[] = []): string =>
   `${JSON.stringify(

package/src/audit/image-size.ts

@@ -1,11 +1,13 @@
-import { imageSize as measureImage } from "image-size";
+import sharp from "sharp";
 
 /**
- * Pixel dimensions read from an image header via the image-size package,
- * which covers the formats a modern pipeline actually emits — WebP and AVIF
- * included, where the previous hand parser (PNG/JPEG/GIF only) went silent
- * and the dimension checks never ran. An unrecognized or truncated buffer
- * yields null and its checks simply don't run.
+ * Pixel dimensions read from an image header via sharp, which is already the
+ * build's image optimizer and so covers every format the pipeline can emit —
+ * WebP and AVIF included. libvips reads only the header and rejects malformed
+ * input with an error rather than looping on it, which is why the previous
+ * pure-JS parser was retired: it could be driven into an infinite loop by a
+ * crafted ICNS, HEIF, or JXL file and hang the build. An unrecognized or
+ * truncated buffer yields null and its checks simply don't run.
  */
 export interface ImageSize {
   width: number;
@@ -13,9 +15,9 @@ export interface ImageSize {
 }
 
 /** The image's pixel dimensions, or null when the format isn't recognized. */
-export const imageSize = (bytes: Buffer): ImageSize | null => {
+export const imageSize = async (bytes: Buffer): Promise<ImageSize | null> => {
   try {
-    const { width, height } = measureImage(bytes);
+    const { width, height } = await sharp(bytes).metadata();
     return width > 0 && height > 0 ? { height, width } : null;
   } catch {
     return null;

package/src/cli/command-meta.ts

@@ -0,0 +1,77 @@
+import type { CommandMeta } from "citty";
+
+/**
+ * Every command's `meta`, held apart from the command modules themselves.
+ *
+ * The CLI entry loads each command lazily (see `lazy-command.ts`), but citty
+ * still reads every subcommand's `meta` to render `blume --help` and to match
+ * an unknown name against aliases. Keeping that table here lets those paths
+ * run without importing a single command module — `dev` alone drags in Astro,
+ * `mcp-stdio` the MCP SDK. The command modules read their `meta` from this
+ * table too, so the entry and the command can't drift.
+ */
+export const commandMeta = {
+  add: {
+    description: "Install a source component or template from the registry.",
+    name: "add",
+  },
+  audit: {
+    description: "Audit the built site for SEO and site-health issues.",
+    name: "audit",
+  },
+  build: {
+    description: "Build the docs site for production.",
+    name: "build",
+  },
+  check: {
+    description: "Type-check the docs site with astro check.",
+    name: "check",
+  },
+  dev: {
+    description: "Start the Blume development server.",
+    name: "dev",
+  },
+  doctor: {
+    description: "Diagnose common configuration and content problems.",
+    name: "doctor",
+  },
+  eject: {
+    description: "Promote the generated runtime into an owned Astro project.",
+    name: "eject",
+  },
+  eval: {
+    description:
+      "Test the docs: an agent answers your questions using only the documentation.",
+    name: "eval",
+  },
+  init: {
+    description: "Scaffold a minimal Blume project.",
+    name: "init",
+  },
+  "mcp-stdio": {
+    description:
+      "Serve an MCP data snapshot over stdio (internal, used by `blume eval`).",
+    name: "mcp-stdio",
+  },
+  preview: {
+    description: "Preview the last production build.",
+    name: "preview",
+  },
+  sync: {
+    description: "Re-fetch remote content sources and regenerate the runtime.",
+    name: "sync",
+  },
+  translate: {
+    description:
+      "Translate docs into the configured locales with a local agent CLI.",
+    name: "translate",
+  },
+  validate: {
+    description: "Validate internal, anchor, asset, and external links.",
+    name: "validate",
+  },
+  version: {
+    description: "Freeze the current docs as an archived version.",
+    name: "version",
+  },
+} satisfies Record<string, CommandMeta>;

package/src/cli/commands/add.ts

@@ -6,6 +6,7 @@ import { dirname, join } from "pathe";
 
 import { findItem, packageSrc, registry } from "../../registry/registry.ts";
 import { rewriteImports } from "../../registry/rewrite-imports.ts";
+import { commandMeta } from "../command-meta.ts";
 import { logger } from "../log.ts";
 
 export const addCommand = defineCommand({
@@ -17,10 +18,7 @@ export const addCommand = defineCommand({
       type: "positional",
     },
   },
-  meta: {
-    description: "Install a source component or template from the registry.",
-    name: "add",
-  },
+  meta: commandMeta.add,
   async run({ args }) {
     const root = process.cwd();
 

package/src/cli/commands/audit.ts

@@ -13,6 +13,7 @@ import type { AuditResult } from "../../audit/run.ts";
 import { BlumeError } from "../../core/diagnostics.ts";
 import { scanProject } from "../../core/project-graph.ts";
 import type { DiagnosticSeverity } from "../../core/types.ts";
+import { commandMeta } from "../command-meta.ts";
 import { reportInternalError } from "../internal-error.ts";
 import { flushStdout, logger } from "../log.ts";
 
@@ -115,10 +116,7 @@ export const auditCommand = defineCommand({
       type: "boolean",
     },
   },
-  meta: {
-    description: "Audit the built site for SEO and site-health issues.",
-    name: "audit",
-  },
+  meta: commandMeta.audit,
   async run({ args }) {
     if (args["list-checks"]) {
       process.stdout.write(formatCatalog());