blume 2.0.1 → 2.0.3

package/src/components/openapi/snippets.ts

@@ -11,9 +11,18 @@ export interface RequestSample {
   method: string;
   url: string;
   headers: Record<string, string>;
-  /** JSON-stringified request body, when the operation takes one. */
+  /**
+   * The request body as sent, when the operation takes one: JSON text,
+   * form-urlencoded pairs, or a raw media type's text.
+   */
   body?: string;
   bodyValue?: unknown;
+  /**
+   * A `multipart/form-data` body's parts as `[name, value]` pairs, set
+   * instead of `body`. The request carries no Content-Type of its own for
+   * them: the client writes one with the parts' boundary.
+   */
+  formData?: [string, string][];
 }
 
 const headerLines = (
@@ -22,26 +31,73 @@ const headerLines = (
 ): string[] =>
   Object.entries(headers).map(([key, value]) => format(key, value));
 
+/**
+ * A single-quoted POSIX shell word. Nothing expands inside single quotes — no
+ * `$`, backtick, `!`, or `\` — so a value reaches curl byte for byte; a
+ * literal `'` closes the quote, adds an escaped one, and reopens it.
+ */
+const shellQuote = (value: string): string =>
+  `'${value.replaceAll("'", String.raw`'\''`)}'`;
+
+/**
+ * A double-quoted string literal for the JavaScript and Python samples. JSON's
+ * string escapes are a subset of both languages' — a quote in a header value
+ * (`If-Match: "33a64df5"`) or a backslash becomes an escape rather than
+ * ending the literal early.
+ */
+const stringLiteral = (value: string): string => JSON.stringify(value);
+
 const curlSnippet = (sample: RequestSample): string => {
   const lines = [
-    `curl -X ${sample.method} "${sample.url}"`,
-    ...headerLines(sample.headers, (key, value) => `  -H "${key}: ${value}"`),
+    // `-X HEAD` sends a HEAD but still waits for the body the response
+    // announces, so the command hangs; `--head` knows there is none.
+    sample.method === "HEAD"
+      ? `curl --head ${shellQuote(sample.url)}`
+      : `curl -X ${sample.method} ${shellQuote(sample.url)}`,
+    ...headerLines(
+      sample.headers,
+      (key, value) => `  -H ${shellQuote(`${key}: ${value}`)}`
+    ),
   ];
   if (sample.body) {
-    // Close-quote/escaped-quote/reopen: the POSIX way to put a literal ' in a
-    // single-quoted string, so an example like "it's" doesn't break the shell.
-    const escapedBody = sample.body.replaceAll("'", String.raw`'\''`);
-    lines.push(`  -d '${escapedBody}'`);
+    lines.push(`  -d ${shellQuote(sample.body)}`);
+  }
+  // `--form-string`, not `-F`: `-F` reads a value starting with `@` or `<` as
+  // a file to upload.
+  for (const [name, value] of sample.formData ?? []) {
+    lines.push(`  --form-string ${shellQuote(`${name}=${value}`)}`);
   }
   return lines.join(" \\\n");
 };
 
+/**
+ * Whether fetch refuses to send `method` (an upper-case HTTP method). TRACE is
+ * one of the Fetch standard's forbidden methods, and the only one an OpenAPI
+ * spec can declare: browsers and Node's fetch alike throw a TypeError before
+ * any request goes out.
+ */
+export const fetchRefusesMethod = (method: string): boolean =>
+  method === "TRACE";
+
+/**
+ * The JavaScript sample for a method fetch refuses: a note in place of a call
+ * that could only throw.
+ */
+const FETCH_REFUSED_NOTE = [
+  "// fetch() refuses the TRACE method: browsers and Node both throw before",
+  "// sending, so there's no fetch sample for this operation. Send it with",
+  "// curl or another HTTP client instead.",
+].join("\n");
+
 const fetchSnippet = (sample: RequestSample): string => {
-  const options = [`  method: "${sample.method}"`];
+  if (fetchRefusesMethod(sample.method)) {
+    return FETCH_REFUSED_NOTE;
+  }
+  const options = [`  method: ${stringLiteral(sample.method)}`];
   if (Object.keys(sample.headers).length > 0) {
     const headers = headerLines(
       sample.headers,
-      (key, value) => `    "${key}": "${value}"`
+      (key, value) => `    ${stringLiteral(key)}: ${stringLiteral(value)}`
     ).join(",\n");
     options.push(`  headers: {\n${headers}\n  }`);
   }
@@ -53,32 +109,70 @@ const fetchSnippet = (sample: RequestSample): string => {
     // and an id past 2^53 loses digits through a JS number. The string
     // literal also stays syntactically valid while the editor holds mid-edit
     // text that isn't JSON yet.
-    options.push(`  body: ${JSON.stringify(sample.body)}`);
+    options.push(`  body: ${stringLiteral(sample.body)}`);
+  }
+  // A FormData body: fetch writes the multipart Content-Type and boundary.
+  let form = "";
+  if (sample.formData) {
+    form = [
+      "const form = new FormData();\n",
+      ...sample.formData.map(
+        ([name, value]) =>
+          `form.append(${stringLiteral(name)}, ${stringLiteral(value)});\n`
+      ),
+      "\n",
+    ].join("");
+    options.push("  body: form");
   }
-  return `const response = await fetch("${sample.url}", {\n${options.join(
+  return `${form}const response = await fetch(${stringLiteral(sample.url)}, {\n${options.join(
     ",\n"
   )}\n});`;
 };
 
+/** The methods `requests` has a module-level helper for. */
+const PYTHON_METHODS = new Set([
+  "delete",
+  "get",
+  "head",
+  "options",
+  "patch",
+  "post",
+  "put",
+]);
+
 const pythonSnippet = (sample: RequestSample): string => {
-  const args = [`    "${sample.url}"`];
+  const args = [`    ${stringLiteral(sample.url)}`];
   if (Object.keys(sample.headers).length > 0) {
     const headers = headerLines(
       sample.headers,
-      (key, value) => `        "${key}": "${value}"`
+      (key, value) => `        ${stringLiteral(key)}: ${stringLiteral(value)}`
     ).join(",\n");
     args.push(`    headers={\n${headers}\n    }`);
   }
   if (sample.body) {
     // Same rule as the fetch snippet: the raw text travels as a string via
-    // `data=` (JSON string escapes are a subset of Python's, so the literal is
-    // valid) rather than a `json=` dict — a Python literal re-serializes
+    // `data=` rather than a `json=` dict — a Python literal re-serializes
     // `1e400` as `Infinity` and would otherwise diverge from the live send.
-    args.push(`    data=${JSON.stringify(sample.body)}`);
+    args.push(`    data=${stringLiteral(sample.body)}`);
   }
-  return `import requests\n\nresponse = requests.${sample.method.toLowerCase()}(\n${args.join(
-    ",\n"
-  )},\n)`;
+  if (sample.formData) {
+    // `files=` is what makes requests encode multipart; a `(None, value)`
+    // tuple is a plain field rather than an upload.
+    const parts = sample.formData.map(
+      ([name, value]) =>
+        `        (${stringLiteral(name)}, (None, ${stringLiteral(value)})),\n`
+    );
+    args.push(`    files=[\n${parts.join("")}    ]`);
+  }
+  // requests has a helper per common method; anything else (TRACE) goes
+  // through `requests.request` with the method named.
+  const method = sample.method.toLowerCase();
+  let call = `requests.${method}`;
+  if (!PYTHON_METHODS.has(method)) {
+    call = "requests.request";
+    args.unshift(`    ${stringLiteral(sample.method)}`);
+  }
+  return `import requests\n\nresponse = ${call}(\n${args.join(",\n")},\n)`;
 };
 
 /** A code-sample language: config id -> label, Shiki lang, and builder. */

package/src/components/openapi/validate-json.ts

@@ -74,7 +74,7 @@ const walk = (
   path: string,
   errors: string[]
 ): void => {
-  if (!schema) {
+  if (!schema || (value === null && schema.nullable === true)) {
     return;
   }
   if (schema.type !== undefined && !matchesType(value, schema.type)) {

package/src/components/openapi/ws-client.ts

@@ -57,7 +57,10 @@ export interface WsClientOptions {
   /** Clock for frame timestamps; defaults to `Date.now`. */
   now?: () => number;
   onFrame: (frame: WsFrame) => void;
-  /** State transitions, with an optional human detail (close reason/code). */
+  /**
+   * State transitions, with an optional human detail: the close reason/code,
+   * or why a URL couldn't be dialed at all.
+   */
   onState: (state: WsState, detail?: string) => void;
 }
 
@@ -125,7 +128,20 @@ export const createWsClient = (options: WsClientOptions): WsClient => {
       return;
     }
     transition("connecting");
-    const next = create(url);
+    let next: SocketLike;
+    try {
+      next = create(url);
+    } catch (error) {
+      // `new WebSocket` throws synchronously on a URL it can't dial (a bad
+      // scheme, a malformed host), before any event could settle the state:
+      // left alone, the panel would say "Connecting…" forever with nothing to
+      // disconnect.
+      transition(
+        "error",
+        error instanceof Error ? error.message : String(error)
+      );
+      return;
+    }
     socket = next;
     // Every listener below is scoped to the socket it was wired for: a browser
     // can deliver a discarded socket's error/close/message after `disconnect`

package/src/core/base-path.ts

@@ -73,16 +73,49 @@ export const isInternalPath = (target: string): boolean =>
 export const isExternalUrl = (target: string): boolean =>
   /^https?:\/\//iu.test(target) || target.startsWith("//");
 
+/**
+ * The path part of a root-relative target, before any `?query` or `#fragment`
+ * (`/docs#install` -> `/docs`).
+ */
+const pathPart = (target: string): string => {
+  const at = target.search(/[#?]/u);
+  return at === -1 ? target : target.slice(0, at);
+};
+
+/**
+ * Whether `route`'s path already equals or sits under `base`. Only the path
+ * part is compared, so a fragment or query (`/docs#install`) doesn't hide a
+ * base written by hand.
+ */
+const isUnderBase = (base: string, route: string): boolean => {
+  const path = pathPart(route);
+  return path === base || path.startsWith(`${base}/`);
+};
+
 /**
  * Idempotently prepend `basePath` to a root-relative route. A route already
  * equal to or nested under the base is returned unchanged, so authors who write
- * the base by hand (`/docs/x`) aren't double-prefixed to `/docs/docs/x`.
+ * the base by hand (`/docs/x`, `/docs#install`) aren't double-prefixed to
+ * `/docs/docs/x`.
  */
 export const withBasePath = (basePath: string, route: string): string => {
-  if (!basePath || !isInternalPath(route)) {
+  if (!basePath || !isInternalPath(route) || isUnderBase(basePath, route)) {
     return route;
   }
-  if (route === basePath || route.startsWith(`${basePath}/`)) {
+  return route === "/" ? basePath : `${basePath}${route}`;
+};
+
+/**
+ * Mount a route Blume generates under a base, unconditionally: `basePath` for
+ * a content route, `deployment.base` for any generated URL (a sitemap entry,
+ * a feed item). {@link withBasePath} leaves a route that already starts with
+ * the base alone, which is right for a link an author based by hand but wrong
+ * for a generated route: with `basePath: "/docs"`, `docs/guide.md` routes to
+ * `/docs/guide` before the base and publishes at `/docs/docs/guide`, not on
+ * top of the root `guide.md` — and likewise under `deployment.base: "/docs"`.
+ */
+export const mountBasePath = (basePath: string, route: string): string => {
+  if (!basePath) {
     return route;
   }
   return route === "/" ? basePath : `${basePath}${route}`;
@@ -102,16 +135,44 @@ export const withComposedBasePath = (
   route: string
 ): string => {
   const composed = `${deployBase}${basePath}`;
-  if (
-    composed &&
-    isInternalPath(route) &&
-    (route === composed || route.startsWith(`${composed}/`))
-  ) {
+  if (composed && isInternalPath(route) && isUnderBase(composed, route)) {
     return route;
   }
   return withBasePath(deployBase, withBasePath(basePath, route));
 };
 
+/**
+ * A path whose final segment carries a file extension (`/spec.pdf`,
+ * `/logo.svg`) — a public asset, unless a page is served there.
+ */
+const DOTTED_PATH = /\.[a-z0-9]+$/iu;
+
+/**
+ * Base a root-relative link an author wrote as if mounted at root — a content
+ * link (`markdown/base-links.ts`, `components/content/base-href.ts`) or a
+ * redirect target (`deploy/redirects.ts`) — by what it names. A page gains the
+ * composed stack ({@link withComposedBasePath}). A public asset — a path whose
+ * final segment carries a file extension, with no page served there (a dotted
+ * route like `/releases/v1.2` is still a page) — gains the deployment base
+ * alone: Astro serves `public/` under `deployment.base`, but never under
+ * `basePath`. `servesPage` answers whether a page is served at a
+ * `basePath`-prefixed, fragment-less path. Other targets pass through.
+ */
+export const withAuthoredBasePath = (
+  deployBase: string,
+  basePath: string,
+  target: string,
+  servesPage: (route: string) => boolean
+): string => {
+  if (!isInternalPath(target)) {
+    return target;
+  }
+  const path = pathPart(target);
+  return DOTTED_PATH.test(path) && !servesPage(withBasePath(basePath, path))
+    ? withBasePath(deployBase, target)
+    : withComposedBasePath(deployBase, basePath, target);
+};
+
 /**
  * Remove `basePath` from the front of a route (`/docs/guide` -> `/guide`,
  * `/docs` -> `/`). A route not under the base is returned unchanged. Inverse of

package/src/core/config-input.ts

@@ -596,14 +596,14 @@ export interface LlmsTxtConfig {
   /**
    * Markdown placed after the title and summary in `llms.txt`, before the
    * page sections — the llms.txt spec's "details" block. Use it to tell
-   * agents when to reach for the product and how to call it (a "When to use"
-   * heading, the install command, the package name). Blank values are
-   * dropped.
+   * agents when to reach for the product and how to call it (the install
+   * command, the package name). The spec allows any Markdown there but
+   * headings. Blank values are dropped.
    *
    * ```ts
    * agents: {
    *   llmsTxt: {
-   *     details: "## When to use Acme\n\nUse Acme when…",
+   *     details: "Use Acme when…",
    *   },
    * }
    * ```
@@ -958,13 +958,15 @@ export interface OgConfig {
    */
   enabled?: boolean;
   /**
-   * Fonts for the generated card, extending Takumi's Latin-only default so
-   * non-Latin titles (CJK, and so on) render instead of tofu. A bare string is
-   * a Google Fonts family fetched at build; the name-only object form pins
-   * weights (`700`, `[400, 700]`, or a `"100..900"` variable range) and
-   * styles; the `src` form reads a local font file from the project instead.
-   * When omitted and `theme.fonts` is explicitly configured, the theme's
-   * display and body fonts are used automatically — pass `[]` to opt out.
+   * Fonts for the generated card, replacing the default stack: Takumi's
+   * Latin-only built-in font plus a Noto fallback per script, which a card
+   * fetches only when its text needs one. A bare string is a Google Fonts
+   * family fetched at build; the name-only object form pins weights (`700`,
+   * `[400, 700]`, or a `"100..900"` variable range) and styles; the `src`
+   * form reads a local font file from the project instead. When omitted and
+   * `theme.fonts` is explicitly configured, the theme's display and body
+   * fonts are used automatically, ahead of the fallbacks — pass `[]` to opt
+   * out of both.
    */
   fonts?: (
     | string

package/src/core/config.ts

@@ -1,5 +1,6 @@
 import { existsSync, readFileSync } from "node:fs";
 
+import { basename } from "pathe";
 import { z } from "zod";
 
 import type { BlumeConfig } from "./config-input.ts";
@@ -9,7 +10,7 @@ import {
   diagnosticsFromIssues,
   diagnosticsFromZod,
 } from "./diagnostics.ts";
-import { createModuleLoader } from "./load-module.ts";
+import { createDefaultExportLoader } from "./load-module.ts";
 import { findConfigFile } from "./project.ts";
 import { blumeConfigSchema } from "./schema.ts";
 import type { ResolvedConfig } from "./schema.ts";
@@ -68,8 +69,8 @@ import type { Diagnostic } from "./types.ts";
  * - `theme` — `accent` color, `fonts` (curated slugs, any provider family, or
  *   local font files), `radius`,
  *   `mode` (`system`/`light`/`dark`), and `background`.
- * - `markdown` — `code` (language icons, inline highlighting, line wrap),
- *   `headingAnchors`, `imageZoom`, and opt-in KaTeX `math`.
+ * - `markdown` — `code` (language icons, light/dark Shiki `theme`, line
+ *   `wrap`), `externalLinks`, `headingAnchors`, and `imageZoom`.
  * - `toc` — on-page table of contents; `true`/`false` or a heading-level range.
  * - `lastModified` — "Last updated" stamps from `git` history or frontmatter.
  * - `feedback` — the per-page "Was this helpful?" widget (on by default).
@@ -199,7 +200,7 @@ export interface ConfigLoadResult {
   themeFontsConfigured: boolean;
 }
 
-const importConfigModule = createModuleLoader();
+const importConfigModule = createDefaultExportLoader();
 
 /**
  * The slice of a user config module probed before schema defaults apply:
@@ -290,6 +291,19 @@ export const loadConfig = async (
         severity: "error",
       });
     }
+    // Validating whatever else the module holds would build a silent default
+    // site (a bare `defineConfig({…})` call) or reject a named `config` export
+    // as an unknown key, neither of which names the actual mistake.
+    if (raw === undefined) {
+      throw new BlumeError({
+        code: "BLUME_CONFIG_INVALID",
+        file: configFile,
+        message: `${basename(configFile)} has no default export, so Blume can't read its config.`,
+        severity: "error",
+        suggestion:
+          "Export the config as the file's default: `export default defineConfig({ … })`.",
+      });
+    }
   }
 
   // Read before parsing: schema defaults erase the set-vs-defaulted distinction.