blume 0.3.0 → 0.5.0

package/src/cli/commands/preview.ts

@@ -6,6 +6,7 @@ import { join } from "pathe";
 
 import { loadConfig } from "../../core/config.ts";
 import { resolveProjectContext } from "../../core/project.ts";
+import { parsePort } from "../args.ts";
 import { logger } from "../log.ts";
 
 export const previewCommand = defineCommand({
@@ -32,7 +33,7 @@ export const previewCommand = defineCommand({
       root: context.outDir,
       server: {
         host: args.host ?? false,
-        port: args.port ? Number(args.port) : undefined,
+        port: parsePort(args.port),
       },
     });
   },

package/src/cli/commands/validate.ts

@@ -3,12 +3,18 @@ import { existsSync } from "node:fs";
 import { defineCommand } from "citty";
 import { join } from "pathe";
 
+import { resolveAssetMounts } from "../../core/assets.ts";
 import { BlumeError } from "../../core/diagnostics.ts";
 import { validateLinks } from "../../core/links.ts";
 import { scanProject } from "../../core/project-graph.ts";
 import type { Diagnostic } from "../../core/types.ts";
 import { reportInternalError } from "../internal-error.ts";
-import { logger, reportDiagnostics, reportDiagnosticsJson } from "../log.ts";
+import {
+  flushStdout,
+  logger,
+  reportDiagnostics,
+  reportDiagnosticsJson,
+} from "../log.ts";
 
 export const validateCommand = defineCommand({
   args: {
@@ -42,6 +48,7 @@ export const validateCommand = defineCommand({
       const publicDir = join(root, "public");
       diagnostics.push(
         ...(await validateLinks(project.graph, {
+          assetMounts: resolveAssetMounts(root, project.config.content.assets),
           checkExternal: Boolean(args.external),
           publicDir: existsSync(publicDir) ? publicDir : null,
           redirects: project.config.redirects,
@@ -57,8 +64,12 @@ export const validateCommand = defineCommand({
     }
 
     if (args.json) {
+      // Drain stdout before exiting non-zero: `process.exit` would otherwise
+      // truncate the JSON payload mid-write when stdout is a pipe — exactly how
+      // `--json` is consumed in CI/editors.
       const hadErrors = reportDiagnosticsJson(diagnostics, root);
       if (hadErrors || (Boolean(args.strict) && diagnostics.length > 0)) {
+        await flushStdout();
         process.exit(1);
       }
       return;

package/src/cli/dev-lock.ts

@@ -0,0 +1,92 @@
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
+
+import { join } from "pathe";
+
+import { resolveRuntimeDir } from "../core/project.ts";
+import { logger } from "./log.ts";
+
+/**
+ * A best-effort PID lock in the shared `.blume/` runtime dir. `blume dev`
+ * regenerates and serves `.blume` continuously, so a concurrent `build`,
+ * `eject`, or `sync --force` that regenerates or deletes it out from under the
+ * running Vite server corrupts the dev session. The lock lets those commands
+ * detect a live dev server and refuse.
+ */
+
+const lockPath = (outDir: string): string => join(outDir, "dev.lock");
+
+/**
+ * Whether another live `blume dev` holds the lock on `outDir`. A lock left by a
+ * process that has since exited (stale) is treated as absent.
+ */
+export const isDevLocked = (outDir: string): boolean => {
+  const path = lockPath(outDir);
+  if (!existsSync(path)) {
+    return false;
+  }
+  const pid = Number.parseInt(readFileSync(path, "utf-8").trim(), 10);
+  if (!(Number.isInteger(pid) && pid > 0)) {
+    return false;
+  }
+  try {
+    // Signal 0 probes liveness without actually signaling the process.
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+};
+
+/**
+ * Write the current process's dev lock into `outDir` and return a release
+ * function. The release only removes the file if it's still ours, so a newer
+ * dev server's lock is never clobbered.
+ */
+export const acquireDevLock = (outDir: string): (() => void) => {
+  const path = lockPath(outDir);
+  mkdirSync(outDir, { recursive: true });
+  writeFileSync(path, String(process.pid));
+  let released = false;
+  return () => {
+    if (released) {
+      return;
+    }
+    released = true;
+    try {
+      if (
+        existsSync(path) &&
+        readFileSync(path, "utf-8").trim() === String(process.pid)
+      ) {
+        rmSync(path, { force: true });
+      }
+    } catch {
+      // Best-effort cleanup; a stale lock is handled by the liveness check.
+    }
+  };
+};
+
+/**
+ * Exit with an error when a live `blume dev` owns the runtime dir under `root`.
+ * `action` names the operation being refused (e.g. "building"). `runtimeDir`
+ * relocates the checked dir: an isolated verify (`.blume-verify`) targets a dir
+ * dev never locks, so it proceeds; a default or `--runtime-dir .blume` run still
+ * refuses.
+ */
+export const refuseIfDevRunning = (
+  root: string,
+  action: string,
+  runtimeDir?: string
+): void => {
+  if (isDevLocked(resolveRuntimeDir(root, runtimeDir))) {
+    logger.error(
+      `A \`blume dev\` server is running against .blume; ${action} would corrupt it. Stop the dev server, or re-run with --isolated to build/verify against .blume-verify without touching it.`
+    );
+    process.exit(1);
+  }
+};

package/src/cli/log.ts

@@ -11,6 +11,17 @@ import type { Diagnostic } from "../core/types.ts";
 
 export const logger = consola.withTag("blume");
 
+/**
+ * Resolve once stdout has drained. `process.exit` doesn't flush a piped stdout,
+ * so await this before exiting non-zero after writing machine-readable output
+ * (e.g. `--json`), otherwise the payload can be truncated in CI.
+ */
+export const flushStdout = (): Promise<void> =>
+  // oxlint-disable-next-line promise/avoid-new -- adapt stdout's write callback
+  new Promise((resolve) => {
+    process.stdout.write("", () => resolve());
+  });
+
 /**
  * Print diagnostics as a JSON document on stdout for CI and editors: each is
  * enriched with its `docsUrl` and its `file` made root-relative. Returns whether

package/src/cli/prepare.ts

@@ -24,6 +24,8 @@ export interface PrepareOptions {
   refresh?: boolean;
   /** CLI config overrides (e.g. `--output`, `--content-dir`). */
   overrides?: ConfigOverrides;
+  /** Relocate the generated runtime (e.g. `.blume-verify` for `--isolated`). */
+  runtimeDir?: string;
 }
 
 /**
@@ -45,6 +47,7 @@ export const prepareProject = async (
       overrides: options.overrides,
       preview: options.preview,
       refresh: options.refresh,
+      runtimeDir: options.runtimeDir,
     });
   } catch (error) {
     if (error instanceof BlumeError) {

package/src/components/BlumePage.astro

@@ -38,7 +38,10 @@ import FileTree from "./content/FileTree.astro";
 import Frame from "./content/Frame.astro";
 import GithubInfo from "./content/GithubInfo.astro";
 import Panel from "./content/Panel.astro";
+import ParamField from "./content/ParamField.astro";
 import Prompt from "./content/Prompt.astro";
+import RequestField from "./content/RequestField.astro";
+import ResponseField from "./content/ResponseField.astro";
 import Step from "./content/Step.astro";
 import Steps from "./content/Steps.astro";
 import Tab from "./content/Tab.astro";
@@ -50,6 +53,7 @@ import TreeFile from "./content/TreeFile.astro";
 import TreeFolder from "./content/TreeFolder.astro";
 import TypeTable from "./content/TypeTable.astro";
 import Visibility from "./content/Visibility.astro";
+import YouTube from "./content/YouTube.astro";
 
 interface Props {
   /** Astro collection the entry lives in. Defaults to `"docs"`. */
@@ -86,7 +90,10 @@ const components = {
   GithubInfo,
   Icon,
   Panel,
+  ParamField,
   Prompt,
+  RequestField,
+  ResponseField,
   Step,
   Steps,
   Tab,
@@ -96,6 +103,7 @@ const components = {
   Tree,
   TypeTable,
   Visibility,
+  YouTube,
   ...extra,
 };
 

package/src/components/Icon.astro

@@ -1,10 +1,13 @@
 ---
+import data from "blume:data";
 import { resolveIcon } from "../theme/icons.ts";
 
 interface Props {
   name?: unknown;
   icon?: unknown;
   iconType?: string;
+  /** Icon library for a bare name; defaults to the project's `icons.library`. */
+  library?: string;
   size?: number;
   class?: string;
   className?: string;
@@ -16,6 +19,7 @@ const {
   color,
   icon,
   iconType,
+  library,
   name,
   size = 16,
   class: astroClass,
@@ -37,8 +41,12 @@ const isImageIcon = (value: string): boolean =>
   /\.(?:avif|gif|jpe?g|png|svg|webp)$/iu.test(value);
 const imageSrc = iconName && !rawSvg && isImageIcon(iconName) ? iconName : null;
 const resolvedIcon =
-  iconName && !(imageSrc || rawSvg) ? resolveIcon(iconName, iconType) : null;
-const markup = resolvedIcon?.markup;
+  iconName && !(imageSrc || rawSvg)
+    ? resolveIcon(iconName, {
+        iconType,
+        library: library ?? data.config.icons.library,
+      })
+    : null;
 const resolvedClass = astroClass ?? className;
 const customStyle = `display:inline-flex;width:${size}px;height:${size}px;${
   color ? `color:${color}` : ""
@@ -76,21 +84,16 @@ const style = color ? `color:${color}` : undefined;
       width={size}
     />
   ) : (
-    markup && (
+    resolvedIcon && (
     <svg
       aria-hidden={label ? undefined : "true"}
       aria-label={label}
       class={resolvedClass}
-      fill="none"
       height={size}
       role={label ? "img" : undefined}
-      set:html={markup}
-      stroke="currentColor"
-      stroke-linecap="round"
-      stroke-linejoin="round"
-      stroke-width="2"
+      set:html={resolvedIcon.body}
       style={style}
-      viewBox="0 0 24 24"
+      viewBox={resolvedIcon.viewBox}
       width={size}
       xmlns="http://www.w3.org/2000/svg"
     />

package/src/components/content/ApiField.astro

@@ -0,0 +1,75 @@
+---
+// Shared field row behind the Mintlify-compat <ParamField>/<ResponseField>/
+// <RequestField> components: a labeled name + type + badges, with the field's
+// description rendered from the slot (which may hold rich MDX, including nested
+// <Expandable> or further fields). Styled to match the native OpenAPI reference
+// rows (src/components/openapi/), so a migrated site reads consistently.
+interface Props {
+  default?: unknown;
+  deprecated?: unknown;
+  location?: string;
+  name?: string;
+  required?: unknown;
+  type?: string;
+}
+
+const {
+  default: defaultValue,
+  deprecated,
+  location,
+  name,
+  required,
+  type,
+} = Astro.props;
+
+// Booleans arrive as MDX shorthand (`required`) or strings (`required="true"`).
+const isTrue = (value: unknown): boolean => value === true || value === "true";
+const hasDefault =
+  defaultValue !== undefined && defaultValue !== null && defaultValue !== "";
+const hasDescription = Astro.slots.has("default");
+---
+
+<div class="not-prose my-2 rounded-blume border border-border px-4 py-3">
+  <div class="flex flex-wrap items-baseline gap-x-2 gap-y-1">
+    {name && <code class="font-mono text-foreground text-sm">{name}</code>}
+    {
+      location && (
+        <span class="rounded bg-muted px-1.5 py-0.5 font-medium text-[0.625rem] text-muted-foreground uppercase tracking-wide">
+          {location}
+        </span>
+      )
+    }
+    {type && <span class="text-muted-foreground text-xs">{type}</span>}
+    {
+      isTrue(required) && (
+        <span class="font-medium text-[0.625rem] text-red-600 uppercase tracking-wide dark:text-red-400">
+          required
+        </span>
+      )
+    }
+    {
+      isTrue(deprecated) && (
+        <span class="font-medium text-[0.625rem] text-muted-foreground uppercase tracking-wide line-through">
+          deprecated
+        </span>
+      )
+    }
+  </div>
+  {
+    hasDefault && (
+      <div class="mt-1 text-muted-foreground text-xs">
+        Default:{" "}
+        <code class="rounded bg-muted px-1 py-0.5 text-foreground">
+          {String(defaultValue)}
+        </code>
+      </div>
+    )
+  }
+  {
+    hasDescription && (
+      <div class="mt-1.5 text-muted-foreground text-sm [&>:first-child]:mt-0 [&>:last-child]:mb-0">
+        <slot />
+      </div>
+    )
+  }
+</div>

package/src/components/content/ParamField.astro

@@ -0,0 +1,39 @@
+---
+// Mintlify-compat <ParamField>. Mintlify encodes the parameter's location in the
+// attribute name (`<ParamField path="id" />`, `query`, `header`, `body`); the
+// attribute's value is the field name. Falls back to a plain `name` prop.
+import ApiField from "./ApiField.astro";
+
+const {
+  body,
+  default: defaultValue,
+  deprecated,
+  header,
+  name,
+  path,
+  query,
+  required,
+  type,
+} = Astro.props;
+
+const locations = [
+  { key: "path", value: path },
+  { key: "query", value: query },
+  { key: "header", value: header },
+  { key: "body", value: body },
+] as const;
+const located = locations.find((entry) => typeof entry.value === "string");
+const fieldName = located ? located.value : name;
+const location = located?.key;
+---
+
+<ApiField
+  default={defaultValue}
+  deprecated={deprecated}
+  location={location}
+  name={fieldName}
+  required={required}
+  type={type}
+>
+  <slot />
+</ApiField>

package/src/components/content/RequestField.astro

@@ -0,0 +1,23 @@
+---
+// Mintlify-compat <RequestField>: same shape as <ResponseField> — a named field
+// (`name`, `type`, `required`, `default`, `deprecated`) with a slotted body.
+import ApiField from "./ApiField.astro";
+
+const {
+  default: defaultValue,
+  deprecated,
+  name,
+  required,
+  type,
+} = Astro.props;
+---
+
+<ApiField
+  default={defaultValue}
+  deprecated={deprecated}
+  name={name}
+  required={required}
+  type={type}
+>
+  <slot />
+</ApiField>

package/src/components/content/ResponseField.astro

@@ -0,0 +1,23 @@
+---
+// Mintlify-compat <ResponseField>: a named field (`name`, `type`, `required`,
+// `default`, `deprecated`) with its description in the slot.
+import ApiField from "./ApiField.astro";
+
+const {
+  default: defaultValue,
+  deprecated,
+  name,
+  required,
+  type,
+} = Astro.props;
+---
+
+<ApiField
+  default={defaultValue}
+  deprecated={deprecated}
+  name={name}
+  required={required}
+  type={type}
+>
+  <slot />
+</ApiField>

package/src/components/content/Step.astro

@@ -18,7 +18,7 @@ const canRenderIcon =
   icon !== undefined &&
   (/^\s*<svg[\s\S]*<\/svg>\s*$/u.test(icon) ||
     isImageIcon(icon) ||
-    hasIcon(icon, iconType));
+    hasIcon(icon, { iconType }));
 ---
 
 <div

package/src/components/content/YouTube.astro

@@ -0,0 +1,35 @@
+---
+import { parseYouTubeId, youtubeEmbedUrl } from "./youtube.ts";
+
+interface Props {
+  /** A YouTube video id (e.g. `dQw4w9WgXcQ`). */
+  id?: string;
+  /** Start playback this many seconds in. */
+  start?: number;
+  /** Accessible title for the embedded player. */
+  title?: string;
+  /** A full YouTube URL to extract the id from, as an alternative to `id`. */
+  url?: string;
+}
+
+const { id, start, title = "YouTube video player", url } = Astro.props;
+
+const videoId = parseYouTubeId(id ?? url ?? "");
+const src = videoId ? youtubeEmbedUrl(videoId, { start }) : null;
+---
+
+{
+  src && (
+    <div class="not-prose my-6 aspect-video overflow-hidden rounded-blume border border-border bg-muted/30">
+      <iframe
+        allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share"
+        allowfullscreen
+        class="h-full w-full"
+        loading="lazy"
+        referrerpolicy="strict-origin-when-cross-origin"
+        src={src}
+        title={title}
+      />
+    </div>
+  )
+}

package/src/components/content/youtube.ts

@@ -0,0 +1,46 @@
+/**
+ * Helpers for the `<YouTube>` content component. Kept in a sibling `.ts` (like
+ * `diff.ts`/`github-info.ts`) so the id parsing and embed-URL building are pure,
+ * unit-testable functions — the `.astro` file stays a thin presentational shell.
+ */
+
+// A YouTube video id is 11 characters of [A-Za-z0-9_-].
+const BARE_ID = /^[\w-]{11}$/u;
+
+// Pull the id out of any common YouTube URL: youtu.be/<id>, watch?v=<id>,
+// /embed/<id>, /shorts/<id>, /live/<id>.
+const URL_ID =
+  /(?:youtu\.be\/|\/embed\/|\/shorts\/|\/live\/|[?&]v=)(?<id>[\w-]{11})/u;
+
+/**
+ * Resolve a YouTube video id from either a bare id or a full URL. Returns `null`
+ * when nothing that looks like an id can be found, so the component can render
+ * nothing rather than a broken embed.
+ */
+export const parseYouTubeId = (input: string): string | null => {
+  const value = input.trim();
+  if (!value) {
+    return null;
+  }
+  if (BARE_ID.test(value)) {
+    return value;
+  }
+  return URL_ID.exec(value)?.groups?.id ?? null;
+};
+
+/**
+ * Build a privacy-enhanced (`youtube-nocookie.com`) embed URL, optionally
+ * starting at `start` seconds.
+ */
+export const youtubeEmbedUrl = (
+  id: string,
+  options: { start?: number } = {}
+): string => {
+  const base = `https://www.youtube-nocookie.com/embed/${id}`;
+  const { start } = options;
+  if (start && start > 0) {
+    const params = new URLSearchParams({ start: String(Math.floor(start)) });
+    return `${base}?${params.toString()}`;
+  }
+  return base;
+};

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

@@ -93,21 +93,21 @@ const AskAI = ({ strings }: { strings?: UIStrings["ask"] }) => {
         headers: { "content-type": "application/json" },
         method: "POST",
       });
-      const reader = response.body?.getReader();
+      // 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();
-      if (reader) {
-        let done = false;
-        while (!done) {
-          // oxlint-disable-next-line no-await-in-loop -- sequential stream reads
-          const chunk = await reader.read();
-          ({ done } = chunk);
-          if (chunk.value) {
-            assistant.content += decoder.decode(chunk.value);
-            setMessages((current) => [
-              ...current.slice(0, -1),
-              { ...assistant },
-            ]);
-          }
+      let done = false;
+      while (!done) {
+        // oxlint-disable-next-line no-await-in-loop -- sequential stream reads
+        const chunk = await reader.read();
+        ({ done } = chunk);
+        if (chunk.value) {
+          assistant.content += decoder.decode(chunk.value);
+          setMessages((current) => [...current.slice(0, -1), { ...assistant }]);
         }
       }
     } catch {

package/src/components/layout/Breadcrumbs.astro

@@ -4,9 +4,11 @@ import type { Crumb } from "./nav-utils.ts";
 interface Props {
   /** Full breadcrumb trail from the site root to the current page. */
   crumbs: Crumb[];
+  /** Left-align full width (for the wide API layout) instead of the prose measure. */
+  wide?: boolean;
 }
 
-const { crumbs } = Astro.props;
+const { crumbs, wide = false } = Astro.props;
 
 // The built-in shows a single "eyebrow" crumb — the parent group — rather than
 // the whole trail. An override receives the complete list and can render more.
@@ -17,7 +19,10 @@ const eyebrowCrumb = crumbs.length > 1 ? crumbs[crumbs.length - 2] : null;
   eyebrowCrumb && (
     <nav
       aria-label="Breadcrumb"
-      class="mx-auto mb-2 max-w-[42rem] text-muted-foreground text-sm"
+      class:list={[
+        "mb-2 text-muted-foreground text-sm",
+        wide ? "max-w-none" : "mx-auto max-w-[42rem]",
+      ]}
     >
       {eyebrowCrumb.route ? (
         <a class="hover:text-foreground" href={eyebrowCrumb.route}>