blume 1.7.1 → 1.7.2

package/src/components/layout/nav-utils.ts

@@ -151,6 +151,15 @@ const isTabSection = (node: NavNode, tabPaths: Set<string>): boolean => {
  * instead of duplicating each tab as a sidebar group. A container left empty by
  * this pruning is dropped too, so no bare heading is stranded. The root tab
  * spans everything, so it never removes anything.
+ *
+ * A group with no tab section anywhere beneath it is kept as the same object:
+ * the stable group ids (`navGroupIds`) and the build-time subtree cache are
+ * both keyed by node identity, so a copy would lose its id — its collapsed
+ * fragment was then requested by a positional name no route serves — and
+ * re-render on every page. A container that did lose a section is rebuilt,
+ * so it has no id: the deferred fragments render from the full tree, which
+ * would put the section back, so `NavTree` renders such a container in full
+ * instead (its untouched children still defer by their own ids).
  */
 const withoutTabSections = (
   nodes: NavNode[],
@@ -173,10 +182,15 @@ const withoutTabSections = (
         continue;
       }
       if (item.kind === "group") {
-        // A container left empty by pruning is dropped, so no bare heading is
-        // stranded.
         const children = prune(item.children);
-        if (children.length > 0) {
+        if (
+          children.length === item.children.length &&
+          children.every((child, index) => child === item.children[index])
+        ) {
+          kept.push(item);
+        } else if (children.length > 0) {
+          // A container left empty by pruning is dropped, so no bare heading
+          // is stranded.
           kept.push({ ...item, children });
         }
       } else {

package/src/core/adapter.ts

@@ -0,0 +1,61 @@
+import { z } from "zod";
+
+/**
+ * The serializable descriptor an integration factory returns — `posthog({ key })`,
+ * `vercel()`, `script({ src })` and their siblings. A descriptor is plain data:
+ * the CLI evaluates `blume.config.ts` once, validates what came back, and
+ * writes it into the generated project's data snapshot as a JSON literal. That
+ * is where the runtime reads it — nothing generated imports the config at
+ * request time — so a descriptor can't carry functions, class instances, or
+ * anything else JSON drops.
+ *
+ * Every consumer reads the descriptor instead of switching on a provider name:
+ * the head emitter and `blume doctor` branch on `kind`, the generated
+ * `.blume/package.json` declares `runtimeDeps`, and the secrets check warns
+ * when an entry of `requiredSecrets` is unset.
+ *
+ * An adapter's verbatim option passthrough is typed as {@link JsonValue} and
+ * validated with `z.json()`, so a function, `undefined`, a bigint, or a
+ * non-finite number fails config validation with a path instead of vanishing
+ * (or throwing) when the snapshot is serialized.
+ */
+export interface AdapterDescriptor<Kind extends string, Options> {
+  /** Which integration this is. */
+  kind: Kind;
+  /** The options the factory was called with, verbatim. */
+  options: Options;
+  /** Env vars the integration reads at runtime; `blume dev`/`build` warn when one is unset. */
+  requiredSecrets: string[];
+  /** Extra packages the generated `.blume/package.json` must declare. */
+  runtimeDeps: string[];
+}
+
+/**
+ * A value JSON can carry unchanged — what an adapter's passthrough options are
+ * typed as. Structurally identical to what `z.json()` accepts.
+ */
+export type JsonValue =
+  | string
+  | number
+  | boolean
+  | null
+  | JsonValue[]
+  | { [key: string]: JsonValue };
+
+/**
+ * The schema for one descriptor `kind`, validating its `options` with the
+ * adapter's own option schema. Members of a `z.discriminatedUnion("kind", …)`.
+ */
+export const adapterDescriptorSchema = <
+  Kind extends string,
+  Options extends z.ZodType,
+>(
+  kind: Kind,
+  options: Options
+) =>
+  z.strictObject({
+    kind: z.literal(kind),
+    options,
+    requiredSecrets: z.array(z.string()),
+    runtimeDeps: z.array(z.string()),
+  });

package/src/core/config-input.ts

@@ -681,6 +681,8 @@ export interface AskSuggestion {
 /** Backends that can route an Ask AI request. */
 type AskProviderGateway = "gateway" | "openrouter" | "llmgateway";
 type AskProvider = AskProviderGateway | "inkeep" | "openai-compatible";
+/** How much the model reasons before answering (`ai.ask.reasoning`). */
+type AskReasoning = "none" | "minimal" | "low" | "medium" | "high" | "xhigh";
 
 /** How much retrieved documentation each Ask AI question carries. */
 export interface AskRetrievalConfig {
@@ -715,6 +717,18 @@ export interface AskConfig {
    * overrides the built-in preset.
    */
   baseUrl?: string;
+  /**
+   * Origins allowed to call the generated endpoint from another site — a
+   * marketing page that embeds an ask box, for example — or `"*"` to allow
+   * every origin. The route answers preflight requests and names a listed
+   * origin on every response, errors included; every other origin stays
+   * subject to the browser's same-origin rule. Callers must send the body as
+   * JSON with a `content-type: application/json` header, or Astro's cross-site
+   * request check rejects the `POST` before the route runs. Only the generated
+   * route reads this; an external `endpoint` handles its own CORS and can't be
+   * combined with it.
+   */
+  cors?: string[];
   /** Turn Ask AI on. Defaults to `false`. */
   enabled?: boolean;
   /**
@@ -740,6 +754,18 @@ export interface AskConfig {
   model?: string;
   /** Which backend routes the request. Defaults to `gateway`. */
   provider?: AskProvider;
+  /**
+   * How much the model reasons before answering, from `"none"` to `"xhigh"`.
+   * Sent as the backend's own reasoning-effort control: the AI SDK's
+   * `reasoning` option on the gateway, `reasoning.effort` on OpenRouter, and
+   * `reasoning_effort` on OpenAI-compatible endpoints. The model has to
+   * support the level — OpenAI rejects one a model doesn't offer — and the
+   * endpoint has to accept the parameter; Inkeep has no reasoning control,
+   * so the field is rejected there. Omitted keeps the model's default.
+   * `"none"` is the fastest and cheapest for grounded docs Q&A, where the
+   * retrieved excerpts carry the answer.
+   */
+  reasoning?: AskReasoning;
   /**
    * How much documentation each question carries into the model's prompt.
    * Lower values cut time-to-first-token — which dominates on a self-hosted

package/src/core/schema.ts

@@ -767,6 +767,19 @@ const searchConfigSchema = z
     }
   });
 
+/**
+ * The `ai.ask.reasoning` levels: the AI SDK's top-level `reasoning` values
+ * minus `provider-default`, which is what omitting the field means.
+ */
+export const askReasoningLevels = [
+  "none",
+  "minimal",
+  "low",
+  "medium",
+  "high",
+  "xhigh",
+] as const;
+
 /** Ask AI backends. `gateway` (default) routes through the Vercel AI Gateway. */
 export const askAiProviders = [
   "gateway",
@@ -872,6 +885,21 @@ const aiConfigSchema = z.strictObject({
       // Base URL of the backend. Required for `openai-compatible` only when no
       // external endpoint is supplied; for named providers it overrides the preset.
       baseUrl: z.url().optional(),
+      // Origins allowed to call the generated `/api/ask` from another site (a
+      // marketing page that embeds an ask box, say), or `"*"` for every
+      // origin. Each URL is reduced to its origin so a trailing slash or path
+      // can't defeat the exact match the route performs. Read by the
+      // generated route only; an external `endpoint` owns its own CORS.
+      cors: z
+        .array(
+          z.union([
+            z.literal("*"),
+            z
+              .url({ protocol: /^https?$/u })
+              .transform((value) => new URL(value).origin),
+          ])
+        )
+        .optional(),
       enabled: z.boolean().default(false),
       // Optional external endpoint for projects that keep their docs static
       // and host Ask AI in an existing backend. Absolute URLs and root-relative
@@ -888,6 +916,12 @@ const aiConfigSchema = z.strictObject({
       instructions: z.string().trim().min(1).optional(),
       model: z.string().default("openai/gpt-5.5"),
       provider: z.enum(askAiProviders).default("gateway"),
+      // How much the model reasons before answering, sent as the backend's
+      // own reasoning-effort control (see `askEndpointTemplate`). Omitted
+      // keeps the provider's default; `none` is the fastest and cheapest for
+      // grounded docs Q&A, where the excerpts carry the answer. Not for
+      // Inkeep, which has no such control (refined below).
+      reasoning: z.enum(askReasoningLevels).optional(),
       // How much documentation each question carries. Injected characters are
       // the dominant term in time-to-first-token on a self-hosted backend, so
       // these trade recall for latency. No zod defaults here: only what the
@@ -926,6 +960,27 @@ const aiConfigSchema = z.strictObject({
           path: ["baseUrl"],
         });
       }
+      // `cors` configures the generated route, which an external `endpoint`
+      // replaces; accepting both would silently do nothing.
+      if (value.cors && value.endpoint) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          message:
+            "ai.ask.cors only applies to the generated route; with ai.ask.endpoint, CORS is that backend's job.",
+          path: ["cors"],
+        });
+      }
+      // Inkeep runs its own QA pipeline behind an OpenAI-compatible endpoint
+      // with no reasoning control; a level would only reach it as an
+      // unsupported `reasoning_effort`, so refuse it up front.
+      if (value.provider === "inkeep" && value.reasoning) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          message:
+            'ai.ask.reasoning is not supported when provider is "inkeep".',
+          path: ["reasoning"],
+        });
+      }
     })
     .optional(),
   /**
@@ -1078,6 +1133,7 @@ const navigationConfigSchema = z.strictObject({
 });
 
 export type AskAiProvider = (typeof askAiProviders)[number];
+export type AskReasoning = (typeof askReasoningLevels)[number];
 export type AskAiConfig = NonNullable<z.infer<typeof aiConfigSchema>["ask"]>;
 export { openInChatProviders } from "./open-in-chat.ts";
 export type { OpenInChatProvider } from "./open-in-chat.ts";

package/src/registry/eject.ts

@@ -137,7 +137,9 @@ const askFiles = async (
   const files = [
     {
       content: askEndpointTemplate(resolveAskBackend(ask), grounded, {
+        cors: ask.cors,
         instructions: ask.instructions,
+        reasoning: ask.reasoning,
         retrieval: ask.retrieval,
       }),
       path: join(srcDir, "pages", "api", "ask.ts"),

package/dist/cli/chunk-2aj8ddew.js

@@ -1,72 +0,0 @@
-#!/usr/bin/env node
-import { createRequire } from "node:module";
-var __require = /* @__PURE__ */ createRequire(import.meta.url);
-
-// src/cli/command-meta.ts
-var 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"
-  }
-};
-
-export { __require, commandMeta };
-
-//# debugId=3DF60EB79641093164756E2164756E21
-//# sourceMappingURL=chunk-2aj8ddew.js.map

package/dist/cli/chunk-2aj8ddew.js.map

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