blume 2.1.0 → 2.1.2

package/src/cli/commands/eval.ts

@@ -104,12 +104,37 @@ const parseFlags = (args: EvalFlags) => {
   return { agent: args.agent, threshold, timeoutS };
 };
 
+/** A shell word for the rerun command, single-quoted only when it has to be. */
+const shellWord = (value: string): string =>
+  /^[\w./:@%+=,-]+$/u.test(value)
+    ? value
+    : `'${value.replaceAll("'", String.raw`'\''`)}'`;
+
+/**
+ * The command a `--fix` agent reruns to verify its edits. It carries the run's
+ * own flags: a bare `blume eval` would fall back to Codex and `evals.yaml`,
+ * grading a different file with a different agent than the run it's fixing.
+ */
+const rerunCommand = (
+  args: EvalFlags,
+  { agent, threshold, timeoutS }: ReturnType<typeof parseFlags>
+): string =>
+  [
+    `blume eval --agent ${agent}`,
+    args.file === DEFAULT_FILE ? "" : `--file ${shellWord(args.file)}`,
+    args.threshold === undefined ? "" : `--threshold ${threshold}`,
+    args.timeout === undefined ? "" : `--timeout ${timeoutS}`,
+  ]
+    .filter((part) => part !== "")
+    .join(" ");
+
 /** `blume eval --fix`: hand the failing report to the interactive agent. */
 const runFixHandoff = async (
   agent: AgentKind,
   result: EvalResult,
   root: string,
-  threshold: number
+  threshold: number,
+  command: string
 ): Promise<void> => {
   const count = result.counts.fail + result.counts.error;
   if (count === 0) {
@@ -120,7 +145,7 @@ const runFixHandoff = async (
   process.stderr.write(
     `  Handing ${count} failed question${count === 1 ? "" : "s"} to ${cli.name}…\n\n`
   );
-  const code = await launchAgentCode(agent, evalFixPrompt(report));
+  const code = await launchAgentCode(agent, evalFixPrompt(report, command));
   if (code !== 0) {
     process.exit(code);
   }
@@ -184,7 +209,8 @@ export const evalCommand = defineCommand({
   meta: commandMeta.eval,
   async run({ args }) {
     const root = process.cwd();
-    const { agent, threshold, timeoutS } = parseFlags(args);
+    const flags = parseFlags(args);
+    const { agent, threshold, timeoutS } = flags;
     if (args.action === "init") {
       await runInit(agent, args.file);
       return;
@@ -259,7 +285,13 @@ export const evalCommand = defineCommand({
     if (args.fix) {
       // The gate is a CI concern; a handoff run succeeds when the agent
       // session does, not when the docs already passed.
-      await runFixHandoff(agent, result, root, threshold);
+      await runFixHandoff(
+        agent,
+        result,
+        root,
+        threshold,
+        rerunCommand(args, flags)
+      );
       return;
     }
 

package/src/cli/commands/init.ts

@@ -272,14 +272,16 @@ export const initCommand = defineCommand({
     // which `init` leaves alone; say what it still needs before installing.
     const note = workspaceNote(root, answers, env);
 
-    // Keep installed dependencies, Blume's generated runtime (`.blume/`), and
-    // build output (`dist/`) out of version control. Idempotent: creates
-    // `.gitignore` when absent and skips entries already present
-    // (trailing-slash agnostic).
+    // Keep installed dependencies, Blume's generated runtime (`.blume/`),
+    // build output (`dist/`), and local secrets (`.env.local`, where every
+    // missing-secret warning says to put them) out of version control.
+    // Idempotent: creates `.gitignore` when absent and skips entries already
+    // present (trailing-slash agnostic).
     const ignored = await ensureGitignore(root, [
       "node_modules/",
       ".blume/",
       "dist/",
+      ".env.local",
     ]);
     if (ignored.length > 0) {
       sink.success(`Added ${ignored.join(", ")} to .gitignore`);

package/src/cli/commands/validate.ts

@@ -13,6 +13,7 @@ import { validateLinks } from "../../core/links.ts";
 import { buildManifest } from "../../core/manifest.ts";
 import { scanProject } from "../../core/project-graph.ts";
 import type { Diagnostic } from "../../core/types.ts";
+import { parseIgnoreFlag } from "../args.ts";
 import { commandMeta } from "../command-meta.ts";
 import { reportInternalError } from "../internal-error.ts";
 import {
@@ -28,6 +29,12 @@ export const validateCommand = defineCommand({
       description: "Check external (HTTP) links over the network.",
       type: "boolean",
     },
+    ignore: {
+      description:
+        'With --external, skip external links whose URL matches this glob (e.g. "https://example.com/**"). Repeat it for more; internal links are always checked.',
+      type: "string",
+      valueHint: "glob",
+    },
     json: {
       description: "Emit diagnostics as JSON on stdout (for CI/editors).",
       type: "boolean",
@@ -38,8 +45,9 @@ export const validateCommand = defineCommand({
     },
   },
   meta: commandMeta.validate,
-  async run({ args }) {
+  async run({ args, rawArgs }) {
     const root = process.cwd();
+    const ignore = parseIgnoreFlag(rawArgs);
     const diagnostics: Diagnostic[] = [];
 
     try {
@@ -83,6 +91,7 @@ export const validateCommand = defineCommand({
           checkExternal: Boolean(args.external),
           extraRoutes,
           i18n: project.config.i18n,
+          ignore,
           publicDir: existsSync(publicDir) ? publicDir : null,
           redirects: project.config.redirects,
         }))

package/src/cli/init/scaffold.ts

@@ -557,6 +557,8 @@ const pnpmWorkspaceSchema = z.looseObject({
 // A glob's leading `./` and trailing `/`, which pnpm ignores.
 const GLOB_EDGES = /^\.\/|\/+$/gu;
 
+const globPattern = (glob: string): string => glob.replaceAll(GLOB_EDGES, "");
+
 /** Whether any of `globs` matches the workspace-relative path `at`. */
 const matchesAny = (globs: string[], at: string): boolean =>
   globs.length > 0 && picomatch(globs)(at);
@@ -589,11 +591,12 @@ const listsPackage = (workspace: string, root: string): boolean => {
     return true;
   }
   const globs = parsed.data.packages;
-  const pattern = (glob: string): string => glob.replaceAll(GLOB_EDGES, "");
-  const included = globs.filter((glob) => !glob.startsWith("!")).map(pattern);
+  const included = globs
+    .filter((glob) => !glob.startsWith("!"))
+    .map(globPattern);
   const excluded = globs
     .filter((glob) => glob.startsWith("!"))
-    .map((glob) => pattern(glob.slice(1)));
+    .map((glob) => globPattern(glob.slice(1)));
   return matchesAny(included, at) && !matchesAny(excluded, at);
 };
 
@@ -679,7 +682,7 @@ const ESBUILD_APPROVAL = "  allowBuilds:\n    esbuild: true";
  * What the project still needs from a workspace it sits in, when `init` left
  * that workspace's config alone: a place in a pnpm workspace's `packages`
  * (pnpm skips a folder it doesn't list), pnpm's approval for esbuild's build
- * script (pnpm 10 and later fail the install without it), or Yarn Berry's
+ * script (pnpm 11 and later fail the install without it), or Yarn Berry's
  * `node_modules` linker. Undefined when the workspace already has it, or the
  * project doesn't sit in one.
  */
@@ -699,12 +702,12 @@ export const workspaceNote = (
       const entry = `  packages:\n    - ${relative(workspace, root)}`;
       return approved
         ? `This folder sits inside the pnpm workspace at ${file}, which doesn't list it under packages, so pnpm won't install it. Add it there before installing:\n\n${entry}`
-        : `This folder sits inside the pnpm workspace at ${file}, which doesn't list it under packages, so pnpm won't install it. Add it there before installing, and approve esbuild's build script, or pnpm 10 and later stop the install:\n\n${entry}\n${ESBUILD_APPROVAL}`;
+        : `This folder sits inside the pnpm workspace at ${file}, which doesn't list it under packages, so pnpm won't install it. Add it there before installing, and approve esbuild's build script, or pnpm 11 and later stop the install:\n\n${entry}\n${ESBUILD_APPROVAL}`;
     }
     if (approved) {
       return;
     }
-    return `This project joins the pnpm workspace at ${file}. Approve esbuild's build script there before installing, or pnpm 10 and later stop the install:\n\n${ESBUILD_APPROVAL}`;
+    return `This project joins the pnpm workspace at ${file}. Approve esbuild's build script there before installing, or pnpm 11 and later stop the install:\n\n${ESBUILD_APPROVAL}`;
   }
   if (answers.packageManager !== "yarn" || yarnMajor(env.userAgent) === 1) {
     return;

package/src/cli/prepare.ts

@@ -59,6 +59,12 @@ export const prepareProject = async (
   let project: BlumeProject;
   try {
     project = await scanProject(options.root, {
+      // Fail-fast on missing secrets: warn now, not at the first request, and
+      // before the sources fetch, so a source that can't authenticate on a
+      // fresh build still gets its variable named.
+      beforeSources: (config) => {
+        reportDiagnostics(checkRequiredSecrets(config), options.root);
+      },
       devServerUrl: options.devServerUrl,
       mode: options.mode,
       overrides: options.overrides,
@@ -138,8 +144,5 @@ export const prepareProject = async (
     logger.warn(warning);
   }
 
-  // Fail-fast on missing runtime secrets: warn now, not at the first request.
-  reportDiagnostics(checkRequiredSecrets(project.config), options.root);
-
   return project;
 };

package/src/cli/required-secrets.ts

@@ -61,7 +61,7 @@ const adapterSecretOwners = (config: ResolvedConfig): SecretOwner[] => {
  * the failure surfaces at `blume dev`/`build` instead of at the first request in
  * production. These are runtime secrets (the endpoint reads them on the server),
  * so this warns rather than hard-fails — the value may live only in the deploy
- * environment. Build-time secrets (search-index sync) already warn during sync.
+ * environment. Build-time secrets (search-index sync) are checked by the sync.
  */
 export const checkRequiredSecrets = (config: ResolvedConfig): Diagnostic[] => {
   const diagnostics: Diagnostic[] = [];
@@ -92,7 +92,8 @@ export const checkRequiredSecrets = (config: ResolvedConfig): Diagnostic[] => {
   }
 
   // Generated narration reads its key at build, not at runtime; without it the
-  // build skips the audio and pages read with browser voices.
+  // build skips the audio and pages read with browser voices. `openai()` with
+  // a `baseUrl` requires only a key it names (see `narrationProviderSchema`).
   const { narration } = config;
   if (narration.enabled && narration.provider) {
     for (const env of narration.provider.requiredSecrets) {

package/src/components/content/ApiPlayground.astro

@@ -11,7 +11,10 @@ import { operationModel } from "../openapi/operation-model.ts";
 import Playground from "../openapi/Playground.astro";
 import { buildRequest, defaultValues } from "../openapi/request.ts";
 import RequestPanel from "../openapi/RequestPanel.astro";
-import { sampleLanguages } from "../openapi/snippets.ts";
+import {
+  DEFAULT_SAMPLE_LANGUAGES,
+  sampleLanguages,
+} from "../openapi/snippets.ts";
 import {
   endpointBody,
   endpointParameters,
@@ -46,6 +49,7 @@ const tryIt = spec.playground !== "simple" && api.playground.enabled;
       model={model}
       operation={`${spec.method} ${spec.target}`}
       proxy={api.playground.proxy}
+      proxyConfig="api"
       slug="api-pages"
     />
   )
@@ -53,7 +57,7 @@ const tryIt = spec.playground !== "simple" && api.playground.enabled;
 {
   !spec.requestExample && (
     <RequestPanel
-      languages={sampleLanguages([])}
+      languages={sampleLanguages(DEFAULT_SAMPLE_LANGUAGES)}
       responses={{}}
       sample={buildRequest(model, defaultValues(model))}
       schemas={{}}

package/src/components/content/api-field.ts

@@ -43,7 +43,10 @@ export interface ParamFieldProps extends FieldProps {
   /** The name, for a field with no location attribute. */
   name?: string;
   path?: string;
-  /** Placeholder text for the parameter's playground input. */
+  /**
+   * An example value: the one the playground and request samples start
+   * with, not an input's placeholder hint (see `fieldSchema`).
+   */
   placeholder?: string;
   query?: string;
 }

package/src/components/content/api-page.ts

@@ -1,3 +1,4 @@
+import { exampleValue } from "../openapi/helpers.ts";
 import type { ParameterLike, SchemaLike } from "../openapi/helpers.ts";
 import { resolveSecurity } from "../openapi/security.ts";
 import type { OperationSecurity } from "../openapi/security.ts";
@@ -168,19 +169,42 @@ export const endpointParameters = (fields: EndpointField[]): ParameterLike[] =>
         ]
   );
 
-/** The body fields as a JSON request body, or `undefined` when there are none. */
+/** Whether a field, or one nested in it, has a `default` or `placeholder`. */
+const hasValue = (field: EndpointField): boolean =>
+  field.default !== undefined ||
+  Boolean(field.placeholder) ||
+  (field.fields ?? []).some(hasValue);
+
+/**
+ * The fields a request starts with: required ones, and ones with a value to
+ * send. An optional field with neither is left for the reader to fill,
+ * rather than sent as the sampler's `"string"`, `0`, or `true`.
+ */
+const sentFields = (fields: EndpointField[]): EndpointField[] =>
+  fields
+    .filter((field) => field.required === true || hasValue(field))
+    .map((field) => ({ ...field, fields: sentFields(field.fields ?? []) }));
+
+/**
+ * The body fields as a JSON request body, or `undefined` when there are none.
+ * Its example, which the playground and samples start from, holds only the
+ * {@link sentFields}.
+ */
 export const endpointBody = (fields: EndpointField[]) => {
   const body = fields.filter((field) => field.location === "body");
+  const object = (members: EndpointField[]): SchemaLike =>
+    fieldSchema({
+      fields: members,
+      location: "body",
+      name: "",
+      type: "object",
+    });
   return body.length > 0
     ? {
         content: {
           "application/json": {
-            schema: fieldSchema({
-              fields: body,
-              location: "body",
-              name: "",
-              type: "object",
-            }),
+            example: exampleValue(object(sentFields(body)), {}),
+            schema: object(body),
           },
         },
       }

package/src/components/content/mermaid-element.ts

@@ -55,6 +55,9 @@ export class BlumeMermaid extends HTMLElement {
         look: "classic",
         securityLevel: "strict",
         startOnLoad: false,
+        // Without this, a diagram that fails to parse leaves Mermaid's own
+        // "Syntax error in text" graphic appended to <body>, below the page.
+        suppressErrorRendering: true,
         theme: prefersDark() ? "dark" : "default",
       });
       try {
@@ -71,13 +74,24 @@ export class BlumeMermaid extends HTMLElement {
           // oxlint-disable-next-line github/no-inner-html -- Mermaid-generated SVG must be injected as HTML
           output.innerHTML = svg;
         }
-      } catch {
+      } catch (error) {
         // Localized message stamped on <body> by RootLayout's markup (the
         // data-attribute channel); English fallback when the attribute is
         // missing (a stale snapshot or a custom layout).
         output.textContent =
           document.body.dataset.i18nDiagramError ||
           "Could not render this diagram.";
+        // Readers get only the message above; the writer needs Mermaid's
+        // parser error (line and expected token) to fix the source. It goes
+        // to the console, and `blume dev` also shows it under the message.
+        console.error("[blume] Mermaid could not render a diagram:", error);
+        if (import.meta.env.DEV) {
+          const detail = document.createElement("pre");
+          detail.className =
+            "mt-2 overflow-x-auto text-muted-foreground text-xs";
+          detail.textContent = String(error);
+          output.append(detail);
+        }
       }
       output.removeAttribute("aria-busy");
     };

package/src/components/content/view-switcher.ts

@@ -42,6 +42,10 @@ const cssString = (value: string): string =>
     .replaceAll("<", String.raw`\3c `)
     .replaceAll(/[\n\r\f]/gu, " ")}"`;
 
+/** Everything tagged with a view other than `title`. */
+const otherViews = (title: string): string =>
+  `[data-blume-view]:not([data-blume-view=${cssString(title)}])`;
+
 /**
  * The page's view CSS: with a view chosen on `<body>`, everything tagged with
  * another is hidden; before a choice, everything but the first view is.
@@ -51,12 +55,11 @@ export const viewStyle = (titles: readonly string[]): string => {
   if (first === undefined) {
     return "";
   }
-  const other = (title: string): string =>
-    `[data-blume-view]:not([data-blume-view=${cssString(title)}])`;
   const selectors = [
-    `body:not([data-blume-view]) ${other(first)}`,
+    `body:not([data-blume-view]) ${otherViews(first)}`,
     ...titles.map(
-      (title) => `body[data-blume-view=${cssString(title)}] ${other(title)}`
+      (title) =>
+        `body[data-blume-view=${cssString(title)}] ${otherViews(title)}`
     ),
   ];
   return `${selectors.join(",")}{display:none!important}`;

package/src/components/islands/hooks.ts

@@ -1,5 +1,9 @@
 import { useCallback, useEffect, useRef, useState } from "react";
 
+import {
+  ASK_MAX_MESSAGES,
+  ASK_MAX_MESSAGES_CHARS,
+} from "../../ai/ask-limits.ts";
 import { captchaToken } from "../../captcha/client.ts";
 import type { CaptchaSettings } from "../../captcha/schema.ts";
 import type { BlumeClientData } from "../../core/data.ts";
@@ -264,6 +268,28 @@ const refusalNotice = (
 const currentPath = (): string =>
   stripBase(import.meta.env.BASE_URL, window.location.pathname);
 
+/**
+ * The conversation as the route is sent it: all of it while it fits the
+ * route's limits (`ai/ask-limits.ts`), else the latest turns that do, the
+ * oldest dropped first, so a long chat keeps working instead of answering
+ * `400`. The kept turns open with a question, not an answer cut from its
+ * own, and the question being asked always goes, even alone over the limit.
+ */
+const withinAskLimits = (history: AskMessage[]): AskMessage[] => {
+  const last = history.length - 1;
+  let start = Math.max(0, history.length - ASK_MAX_MESSAGES);
+  while (
+    start < last &&
+    JSON.stringify(history.slice(start)).length > ASK_MAX_MESSAGES_CHARS
+  ) {
+    start += 1;
+  }
+  while (start < last && history[start]?.role !== "user") {
+    start += 1;
+  }
+  return history.slice(start);
+};
+
 /**
  * Stream answers from the assistant endpoint. Mirrors the built-in assistant island so
  * a custom chat UI shares the same grounded, page-aware backend.
@@ -366,7 +392,7 @@ export const useAssistant = (
         }
         const payload: AskPayload = {
           captcha: token,
-          messages: history,
+          messages: withinAskLimits(history),
           page: { path },
         };
         const response = await fetch(endpoint, {

package/src/components/layout/NavTree.astro

@@ -307,15 +307,59 @@ const initialId =
         const spacing =
           index === 0 ? "mt-0" : display === "flat" ? "mt-6" : "mt-0.5";
 
-        // `page`: a single row that drills into this group's panel. It
-        // controls that panel; NavTreeScript keeps `aria-expanded` in step
-        // with the panel shown (static markup, since cached subtrees and
-        // fragments can't carry per-page state).
+        // `page`: a single row that drills into this group's panel. Its drill
+        // button controls that panel; NavTreeScript keeps `aria-expanded` in
+        // step with the panel shown (static markup, since cached subtrees and
+        // fragments can't carry per-page state). A group with an index page
+        // splits the row, like the `group` summary: the label links that page
+        // (which renders with the panel open), so the row opens the section
+        // even when the index hides its own row, and the chevron stays a
+        // button that slides the panel in without leaving the page. Without
+        // one, the whole row is the drill button, so it never links a missing
+        // page. `aria-current` marks the row whose panel holds the current
+        // page (`page` on the section's own page), so the parent panel still
+        // shows where the reader is after the back arrow. Only rows on the
+        // active path carry it, and those always render live, never from a
+        // cache.
         if (display === "page") {
-          return (
+          const current = hasActivePage(item)
+            ? isGroupRowCurrent(item, currentRoute)
+              ? "page"
+              : "true"
+            : undefined;
+          return item.route ? (
+            <li class={`flex items-center gap-0.5 ${spacing}`}>
+              <a
+                aria-current={current}
+                class="blume-nav-drill-link"
+                href={withMountedBase(item.route)}
+              >
+                {item.icon && (
+                  <Icon
+                    class="shrink-0 text-muted-foreground"
+                    name={item.icon}
+                    size={14}
+                  />
+                )}
+                <span class="flex-1 truncate">{item.label}</span>
+                {item.badge && <span class={badgeClassFor(item.badge)}>{item.badge}</span>}
+              </a>
+              <button
+                aria-controls={navPanelId(id)}
+                aria-expanded="false"
+                aria-label={item.label}
+                class="blume-nav-drill-toggle"
+                data-nav-to={id}
+                type="button"
+              >
+                <Icon class="rtl:-scale-x-100" name="chevron-right" size={14} />
+              </button>
+            </li>
+          ) : (
             <li class={spacing}>
               <button
                 aria-controls={navPanelId(id)}
+                aria-current={current}
                 aria-expanded="false"
                 class="blume-nav-drill"
                 data-nav-to={id}

package/src/components/layout/NavTreeScript.astro

@@ -146,6 +146,24 @@
           }
           return;
         }
+        // After the back arrow, the current section's name links the page
+        // already on screen, so a plain click slides its panel back in rather
+        // than reloading that page. Modified clicks stay the browser's.
+        const own = target.closest('.blume-nav-drill-link[aria-current="page"]');
+        const ownId = own?.parentElement
+          ?.querySelector("[data-nav-to]")
+          ?.getAttribute("data-nav-to");
+        if (
+          own &&
+          ownId &&
+          this.contains(own) &&
+          this.panel(ownId) &&
+          !(event.metaKey || event.ctrlKey || event.shiftKey || event.altKey)
+        ) {
+          event.preventDefault();
+          void this.show(ownId, true);
+          return;
+        }
         const back = target.closest("[data-nav-back]");
         if (back && this.contains(back)) {
           event.preventDefault();