blume 1.4.0 → 1.4.1

package/src/cli/commands/dev.ts

@@ -1,8 +1,6 @@
-import { watch } from "node:fs";
-
 import { dev } from "astro";
+import { watch } from "chokidar";
 import { defineCommand } from "citty";
-import { basename, dirname } from "pathe";
 
 import { generateRuntime } from "../../astro/generate.ts";
 import { showBlumeErrorOverlay } from "../../astro/integration.ts";
@@ -212,26 +210,16 @@ export const devCommand = defineCommand({
       project.context.componentsFile,
     ].filter((target) => target !== null);
 
+    // chokidar handles what raw fs.watch made us hand-roll: recursive
+    // directory watching on every platform, and single files surviving a
+    // rename-replace save (vim and most "atomic save" editors), which orphans
+    // an inode-tracking fs.watch watcher after the first write.
+    const projectWatcher = watch([...dirTargets, ...fileTargets], {
+      ignoreInitial: true,
+    }).on("all", regenerate);
     const disposers = [
       ...project.sources.map((source) => source.watch?.(regenerate)),
-      ...dirTargets.map((target) => {
-        const watcher = watch(target, { recursive: true }, regenerate);
-        return () => watcher.close();
-      }),
-      // Single files are watched via their parent directory: fs.watch on the
-      // file itself tracks the inode, so a rename-replace save (vim and most
-      // "atomic save" editors) orphans the watcher after the first write and
-      // every later edit is silently ignored.
-      ...fileTargets.map((target) => {
-        const name = basename(target);
-        const watcher = watch(dirname(target), (_event, filename) => {
-          // A null filename (some platforms) can't be filtered — regenerate.
-          if (!filename || filename === name) {
-            regenerate();
-          }
-        });
-        return () => watcher.close();
-      }),
+      () => void projectWatcher.close(),
     ].filter((dispose) => dispose !== undefined);
 
     const shutdown = async () => {

package/src/cli/commands/doctor.ts

@@ -2,6 +2,7 @@ import { readFileSync } from "node:fs";
 
 import { defineCommand } from "citty";
 import { join } from "pathe";
+import { satisfies } from "semver";
 
 import { BlumeError } from "../../core/diagnostics.ts";
 import { packageRoot } from "../../core/package-root.ts";
@@ -16,35 +17,21 @@ import {
   reportDiagnosticsJson,
 } from "../log.ts";
 
-const FALLBACK_MIN_NODE = "22.12.0";
-const LEADING_RANGE = /^[^\d]*/u;
+const FALLBACK_NODE_RANGE = ">=22.12.0";
 
-/** The minimum Node version, read from the package's own `engines` field so
+/** The supported Node range, read from the package's own `engines` field so
  * doctor can never drift from what the package actually declares. */
-const minSupportedNode = (): string => {
+const supportedNodeRange = (): string => {
   try {
     const pkg = JSON.parse(
       readFileSync(join(packageRoot(), "package.json"), "utf-8")
     ) as { engines?: { node?: string } };
-    const range = pkg.engines?.node ?? "";
-    return range.replace(LEADING_RANGE, "") || FALLBACK_MIN_NODE;
+    return pkg.engines?.node || FALLBACK_NODE_RANGE;
   } catch {
-    return FALLBACK_MIN_NODE;
+    return FALLBACK_NODE_RANGE;
   }
 };
 
-const versionBelow = (current: string, minimum: string): boolean => {
-  const a = current.split(".").map((part) => Math.trunc(Number(part)));
-  const b = minimum.split(".").map((part) => Math.trunc(Number(part)));
-  for (let i = 0; i < 3; i += 1) {
-    const delta = (a[i] ?? 0) - (b[i] ?? 0);
-    if (delta !== 0) {
-      return delta < 0;
-    }
-  }
-  return false;
-};
-
 export const doctorCommand = defineCommand({
   args: {
     json: {
@@ -60,11 +47,11 @@ export const doctorCommand = defineCommand({
     const root = process.cwd();
     const diagnostics: Diagnostic[] = [];
 
-    const minNode = minSupportedNode();
-    if (versionBelow(process.versions.node, minNode)) {
+    const nodeRange = supportedNodeRange();
+    if (!satisfies(process.versions.node, nodeRange)) {
       diagnostics.push({
         code: "BLUME_NODE_VERSION",
-        message: `Node ${process.versions.node} is below the supported minimum (${minNode}).`,
+        message: `Node ${process.versions.node} is outside the supported range (${nodeRange}).`,
         severity: "warning",
       });
     }

package/src/cli/env.ts

@@ -1,5 +1,6 @@
 import { existsSync, readFileSync } from "node:fs";
 
+import { parse } from "dotenv";
 import { dirname, join, resolve } from "pathe";
 
 // Blume's remote sources (GitHub Releases, mdx-remote, Sanity, Notion…) read
@@ -8,57 +9,6 @@ import { dirname, join, resolve } from "pathe";
 // that gap: it cascades `.env`/`.env.local` from the working dir up to the repo
 // root, so a monorepo can keep one `.env` at the root and every app picks it up.
 
-const ENV_LINE =
-  /^\s*(?:export\s+)?(?<key>[A-Za-z_][A-Za-z0-9_]*)\s*=\s*(?<value>.*?)\s*$/u;
-const DOUBLE_QUOTED = /^"(?<body>[\s\S]*)"$/u;
-const SINGLE_QUOTED = /^'(?<body>[\s\S]*)'$/u;
-
-const ESCAPE = /\\(?<char>[\\nt"])/gu;
-const UNESCAPED: Record<string, string> = {
-  '"': '"',
-  "\\": "\\",
-  n: "\n",
-  t: "\t",
-};
-
-/** Unquote a value, expanding `\n`/`\t`/escapes inside double quotes only. */
-const unquote = (raw: string): string => {
-  const double = raw.match(DOUBLE_QUOTED)?.groups?.body;
-  if (double !== undefined) {
-    // A single pass so each backslash is consumed exactly once — sequential
-    // replaceAll calls would expand the `n` in `\\n` (an escaped backslash
-    // followed by a literal `n`) into a newline.
-    return double.replaceAll(
-      ESCAPE,
-      (match, char: string) => UNESCAPED[char] ?? match
-    );
-  }
-  const single = raw.match(SINGLE_QUOTED)?.groups?.body;
-  if (single !== undefined) {
-    return single;
-  }
-  // dotenv/Vite treat an unquoted `#` as the start of an inline comment (a
-  // value containing `#` must be quoted) — keeping the comment would hand
-  // consumers a silently corrupted value.
-  const hash = raw.indexOf("#");
-  return (hash === -1 ? raw : raw.slice(0, hash)).trim();
-};
-
-/** Parse `.env` text into key/value pairs, skipping blanks and `#` comments. */
-export const parseEnv = (content: string): Record<string, string> => {
-  const env: Record<string, string> = {};
-  for (const line of content.split(/\r?\n/u)) {
-    if (line.trim() === "" || line.trimStart().startsWith("#")) {
-      continue;
-    }
-    const groups = line.match(ENV_LINE)?.groups;
-    if (groups?.key !== undefined && groups.value !== undefined) {
-      env[groups.key] = unquote(groups.value);
-    }
-  }
-  return env;
-};
-
 /** Apply parsed vars without clobbering anything already in `process.env`. */
 const applyEnv = (parsed: Record<string, string>): void => {
   for (const [key, value] of Object.entries(parsed)) {
@@ -71,7 +21,11 @@ const applyEnv = (parsed: Record<string, string>): void => {
 const loadFile = (path: string): void => {
   try {
     if (existsSync(path)) {
-      applyEnv(parseEnv(readFileSync(path, "utf-8")));
+      // dotenv is the same parser Vite runs over these files at build time,
+      // so a value means the same thing to the pre-boot content scan and the
+      // built site — including multi-line double-quoted values (PEM keys),
+      // which a line-based parser silently truncates.
+      applyEnv(parse(readFileSync(path, "utf-8")));
     }
   } catch {
     // Env files are best-effort; a read/parse failure must not abort a build.

package/src/cli/init/scaffold.ts

@@ -195,28 +195,29 @@ const hasRemoteSource = (sources: SourceKind[]): boolean =>
  * Config snippets for each remote source kind, with placeholder values to
  * replace and comments naming the env var each source authenticates with.
  */
-const sourceSnippetFor = (kind: Exclude<SourceKind, "filesystem">): string => {
-  switch (kind) {
-    case "github-releases": {
-      return `      // Changelog entries from GitHub Releases. Private repos read
+const SOURCE_SNIPPETS: Record<Exclude<SourceKind, "filesystem">, string> = {
+  "github-releases": `      // Changelog entries from GitHub Releases. Private repos read
       // GITHUB_TOKEN from the environment.
       {
         type: "github-releases",
         owner: "your-org",
         repo: "your-repo",
         prefix: "changelog",
-      },`;
-    }
-    case "notion": {
-      return `      // Pages from a Notion database. Reads NOTION_TOKEN from the environment.
+      },`,
+  "mdx-remote": `      // MDX fetched from a GitHub repo. Private repos read GITHUB_TOKEN
+      // from the environment.
+      {
+        type: "mdx-remote",
+        github: { owner: "your-org", repo: "your-repo", path: "docs" },
+        prefix: "remote",
+      },`,
+  notion: `      // Pages from a Notion database. Reads NOTION_TOKEN from the environment.
       {
         type: "notion",
         database: "your-database-id",
         prefix: "notion",
-      },`;
-    }
-    case "sanity": {
-      return `      // Documents from a Sanity dataset. Private datasets read SANITY_TOKEN
+      },`,
+  sanity: `      // Documents from a Sanity dataset. Private datasets read SANITY_TOKEN
       // from the environment.
       {
         type: "sanity",
@@ -224,21 +225,7 @@ const sourceSnippetFor = (kind: Exclude<SourceKind, "filesystem">): string => {
         dataset: "production",
         query: \`*[_type == "doc"]\`,
         prefix: "sanity",
-      },`;
-    }
-    case "mdx-remote": {
-      return `      // MDX fetched from a GitHub repo. Private repos read GITHUB_TOKEN
-      // from the environment.
-      {
-        type: "mdx-remote",
-        github: { owner: "your-org", repo: "your-repo", path: "docs" },
-        prefix: "remote",
-      },`;
-    }
-    default: {
-      return kind satisfies never;
-    }
-  }
+      },`,
 };
 
 /**
@@ -263,7 +250,7 @@ const contentBlockFor = (answers: InitAnswers): string => {
     (kind) =>
       kind === "filesystem"
         ? `      { type: "filesystem", root: ${JSON.stringify(answers.contentDir)} },`
-        : sourceSnippetFor(kind)
+        : SOURCE_SNIPPETS[kind]
   );
   return `
   content: {

package/src/cli/internal-error.ts

@@ -1,10 +1,6 @@
-import { getBlumeVersion } from "../core/version.ts";
+import { colors } from "consola/utils";
 
-const ESC = String.fromCodePoint(27);
-const DIM = `${ESC}[2m`;
-const RED = `${ESC}[31m`;
-const BOLD = `${ESC}[1m`;
-const RESET = `${ESC}[0m`;
+import { getBlumeVersion } from "../core/version.ts";
 
 const ISSUES_URL = "https://github.com/haydenbleasel/blume/issues";
 
@@ -40,7 +36,7 @@ export const remapBlumeStack = (stack: string): string =>
 export const reportInternalError = (error: unknown): void => {
   const err = error instanceof Error ? error : new Error(String(error));
   const lines = [
-    `${RED}${BOLD}BLUME_INTERNAL${RESET} An unexpected error occurred.`,
+    `${colors.red(colors.bold("BLUME_INTERNAL"))} An unexpected error occurred.`,
     `  ${err.message}`,
   ];
 
@@ -52,15 +48,19 @@ export const reportInternalError = (error: unknown): void => {
     .map((line) => line.trim())
     .filter(Boolean);
   if (stack.length > 0) {
-    lines.push("", `${DIM}${stack.join("\n")}${RESET}`);
+    lines.push("", colors.dim(stack.join("\n")));
   }
 
   lines.push(
     "",
     "This is likely a bug in Blume. Please report it with the details below:",
-    `  ${DIM}Blume:    ${getBlumeVersion()}`,
-    `  Node:     ${process.version}`,
-    `  Platform: ${process.platform} ${process.arch}${RESET}`,
+    colors.dim(
+      [
+        `  Blume:    ${getBlumeVersion()}`,
+        `  Node:     ${process.version}`,
+        `  Platform: ${process.platform} ${process.arch}`,
+      ].join("\n")
+    ),
     `  ${ISSUES_URL}`
   );
 

package/src/components/islands/ask-ai.tsx

@@ -5,13 +5,8 @@ import type { FormEvent, KeyboardEvent as ReactKeyboardEvent } from "react";
 import { createPortal } from "react-dom";
 
 import type { UIStrings } from "../../core/i18n-ui.ts";
-import { joinBase, prefixBase, stripBase } from "./base-path.ts";
-
-interface ChatMessage {
-  content: string;
-  id: number;
-  role: "assistant" | "user";
-}
+import { joinBase, prefixBase } from "./base-path.ts";
+import { useAskAI } from "./hooks.ts";
 
 /** A resolved empty-state prompt; `icon` is ready-to-inline SVG (or null). */
 interface Suggestion {
@@ -57,20 +52,10 @@ const DEFAULT_ASK: UIStrings["ask"] = {
   you: "You",
 };
 
-let idCounter = 0;
-const nextId = (): number => {
-  idCounter += 1;
-  return idCounter;
-};
-
-// The endpoint and page path both honor the deployment `base` so grounding works
-// under a non-root base path (the server matches base-less document routes).
+// The endpoint honors the deployment `base` so grounding works under a
+// non-root base path (the server matches base-less document routes).
 const DEFAULT_ASK_ENDPOINT = joinBase(import.meta.env.BASE_URL, "api/ask");
 
-/** The current route with the deployment base stripped, for page-context lookup. */
-const currentPath = (): string =>
-  stripBase(import.meta.env.BASE_URL, window.location.pathname);
-
 // GitHub-flavored markdown with soft line breaks, matching how the docs read.
 marked.setOptions({ breaks: true, gfm: true });
 
@@ -149,20 +134,20 @@ const AskAI = ({
   const [mounted, setMounted] = useState(false);
   const [open, setOpen] = useState(false);
   const [input, setInput] = useState("");
-  const [messages, setMessages] = useState<ChatMessage[]>([]);
-  const [busy, setBusy] = useState(false);
+  // The streaming client — request shaping, optimistic assistant bubble,
+  // stale-stream/abort guards, error-body handling — is the public useAskAI
+  // hook, so the built-in panel and custom UIs share one implementation.
+  const {
+    ask,
+    loading: busy,
+    messages,
+    reset,
+  } = useAskAI({ endpoint, errorMessage: t.error });
   const inputRef = useRef<HTMLTextAreaElement>(null);
   const scrollRef = useRef<HTMLDivElement>(null);
   const triggerRef = useRef<HTMLButtonElement>(null);
   // Where focus came from when the panel opened, restored on close.
   const returnFocusRef = useRef<HTMLElement | null>(null);
-  // The stream writes into the conversation via functional updates, so "Clear
-  // conversation" mid-answer must revoke the in-flight stream's right to write
-  // — otherwise its next chunk re-appends the assistant bubble onto the
-  // emptied list as an orphaned answer. Clearing bumps the generation (stale
-  // streams stop writing) and aborts the request (the stream stops arriving).
-  const abortRef = useRef<AbortController | null>(null);
-  const generationRef = useRef(0);
 
   // Portal target (document.body) only exists after mount; guards SSR. The
   // one-time false→true flip is deliberate, so the initial `false` is required.
@@ -245,86 +230,22 @@ const AskAI = ({
     scrollRef.current?.scrollTo({ top: scrollRef.current.scrollHeight });
   }, [messages]);
 
-  const runQuestion = async (raw: string) => {
+  const runQuestion = (raw: string) => {
     const question = raw.trim();
     if (!question || busy) {
       return;
     }
-
-    const userMessage: ChatMessage = {
-      content: question,
-      id: nextId(),
-      role: "user",
-    };
-    const history = [...messages, userMessage];
-    const assistant: ChatMessage = {
-      content: "",
-      id: nextId(),
-      role: "assistant",
-    };
-    setMessages([...history, assistant]);
+    void ask(question);
     setInput("");
-    setBusy(true);
-    const generation = generationRef.current;
-    const controller = new AbortController();
-    abortRef.current = controller;
-
-    try {
-      const response = await fetch(endpoint, {
-        body: JSON.stringify({
-          messages: history.map((m) => ({ content: m.content, role: m.role })),
-          page: { path: currentPath() },
-        }),
-        headers: { "content-type": "application/json" },
-        method: "POST",
-        signal: controller.signal,
-      });
-      // A 4xx/5xx still has a body; without this guard its error text would be
-      // decoded and shown as the assistant's answer instead of the error notice.
-      if (!(response.ok && response.body)) {
-        throw new Error(`Ask AI request failed (${response.status}).`);
-      }
-      const reader = response.body.getReader();
-      const decoder = new TextDecoder();
-      let done = false;
-      while (!done) {
-        // oxlint-disable-next-line no-await-in-loop, react-doctor/async-await-in-loop -- sequential stream consumption; iterations are not independent
-        const chunk = await reader.read();
-        ({ done } = chunk);
-        if (chunk.value) {
-          // Streaming mode: a multi-byte UTF-8 sequence split across chunks
-          // must not flush as U+FFFD garbage.
-          // oxlint-disable-next-line react/react-compiler -- local streaming accumulator, spread into state below
-          assistant.content += decoder.decode(chunk.value, { stream: true });
-          if (generationRef.current === generation) {
-            setMessages((current) => [
-              ...current.slice(0, -1),
-              { ...assistant },
-            ]);
-          }
-        }
-      }
-    } catch {
-      // A cleared (aborted) stream must not resurrect its bubble as an error.
-      if (generationRef.current === generation) {
-        // oxlint-disable-next-line react/react-compiler -- local streaming accumulator, spread into state below
-        assistant.content = t.error;
-        setMessages((current) => [...current.slice(0, -1), { ...assistant }]);
-      }
-    } finally {
-      setBusy(false);
-    }
   };
 
   const clearConversation = () => {
-    generationRef.current += 1;
-    abortRef.current?.abort();
-    setMessages([]);
+    reset();
   };
 
   const onSubmit = (event: FormEvent) => {
     event.preventDefault();
-    void runQuestion(input);
+    runQuestion(input);
   };
 
   const onInputKeyDown = (event: ReactKeyboardEvent<HTMLTextAreaElement>) => {
@@ -336,7 +257,7 @@ const AskAI = ({
       !event.nativeEvent.isComposing
     ) {
       event.preventDefault();
-      void runQuestion(input);
+      runQuestion(input);
     }
   };
 
@@ -398,16 +319,20 @@ const AskAI = ({
       >
         {hasMessages ? (
           <div className="flex flex-col gap-4 p-4">
-            {messages.map((message) =>
+            {/* Index keys are safe here: the list only appends, mutates its
+                last entry while streaming, or clears wholesale on reset. */}
+            {messages.map((message, index) =>
               message.role === "user" ? (
                 <div
                   className="max-w-[85%] self-end whitespace-pre-wrap rounded-blume bg-muted px-3 py-2 text-foreground text-sm"
-                  key={message.id}
+                  // oxlint-disable-next-line react/no-array-index-key -- append-only list, see above
+                  key={index}
                 >
                   {message.content}
                 </div>
               ) : (
-                <div className={ANSWER_CLASS} key={message.id}>
+                // oxlint-disable-next-line react/no-array-index-key -- append-only list, see above
+                <div className={ANSWER_CLASS} key={index}>
                   {message.content ? (
                     // biome-ignore lint/security/noDangerouslySetInnerHtml: sanitized above
                     <div

package/src/components/islands/hooks.ts

@@ -144,6 +144,12 @@ const DEFAULT_ASK_ENDPOINT = joinBase(import.meta.env.BASE_URL, "api/ask");
 export interface UseAskAIOptions {
   /** Existing Ask AI endpoint; defaults to Blume's generated `/api/ask`. */
   endpoint?: string;
+  /**
+   * Shown as the assistant's answer when the request fails or throws.
+   * Defaults to an English notice; the built-in island passes its localized
+   * dictionary string.
+   */
+  errorMessage?: string;
 }
 
 /** Shown as the assistant's answer when the request fails or throws. */
@@ -159,6 +165,7 @@ const currentPath = (): string =>
  */
 export const useAskAI = (options: UseAskAIOptions = {}): UseAskAI => {
   const endpoint = options.endpoint ?? DEFAULT_ASK_ENDPOINT;
+  const errorMessage = options.errorMessage ?? ASK_ERROR;
   const [messages, setMessages] = useState<AskMessage[]>([]);
   const [loading, setLoading] = useState(false);
   // The stream writes into the conversation via state updates, so `reset()`
@@ -205,7 +212,7 @@ export const useAskAI = (options: UseAskAIOptions = {}): UseAskAI => {
           // An error body (JSON, HTML error page) must not stream in as the
           // assistant's answer.
           if (live()) {
-            assistant.content = ASK_ERROR;
+            assistant.content = errorMessage;
             setMessages([...history, { ...assistant }]);
           }
           return;
@@ -236,7 +243,7 @@ export const useAskAI = (options: UseAskAIOptions = {}): UseAskAI => {
         // pre-appended empty assistant message as a stuck placeholder. A
         // reset's abort lands here too — the guard keeps it silent.
         if (live()) {
-          assistant.content = ASK_ERROR;
+          assistant.content = errorMessage;
           setMessages([...history, { ...assistant }]);
         }
       } finally {
@@ -245,7 +252,7 @@ export const useAskAI = (options: UseAskAIOptions = {}): UseAskAI => {
         }
       }
     },
-    [endpoint, loading, messages]
+    [endpoint, errorMessage, loading, messages]
   );
 
   // Retained for the compiler-off opt-out path (`react: { compiler: false }`):