blume 0.5.4 → 0.6.0

package/src/astro/templates.ts

@@ -5,6 +5,7 @@ import { dirname, isAbsolute, join, relative } from "pathe";
 import { askBackendRuntimeDep } from "../ai/ask.ts";
 import type { AskBackend } from "../ai/ask.ts";
 import type { ResolvedConfig } from "../core/schema.ts";
+import { BLUME_IGNORE_DIRS } from "../core/sources/watch.ts";
 import type { ProjectContext } from "../core/types.ts";
 import { hasScalarReferences } from "../openapi/references.ts";
 import { searchProviderMeta } from "../search/providers.ts";
@@ -354,9 +355,17 @@ export default defineConfig({
     // native bindings resolve at runtime and isolated linkers don't bundle
     // symlinked store copies (which would surface their children as unresolvable
     // imports). See RENDER_EXTERNAL_DEPS / prerenderDepsPlugin.
+    //
+    // The SSR externals go through the legacy \`ssr.external\` key rather than
+    // \`environments.ssr\`: defining a user-owned \`environments.ssr\` block
+    // collides with the internal environment Astro 7 builds the server under and
+    // detaches the adapter's server entrypoint from the rolldown input, so the
+    // SSR entry is emitted as \`index.mjs\` instead of the \`entry.mjs\` the
+    // Vercel adapter's \`astro:build:done\` hook then fails to find. \`prerender\`
+    // is Astro-only and has no legacy equivalent, so it stays under \`environments\`.
+    ssr: { external: ${JSON.stringify(RENDER_EXTERNAL_DEPS)} },
     environments: {
       prerender: { resolve: { external: ${JSON.stringify(RENDER_EXTERNAL_DEPS)} } },
-      ssr: { resolve: { external: ${JSON.stringify(RENDER_EXTERNAL_DEPS)} } },
     },
     resolve: {
       alias: {
@@ -432,7 +441,15 @@ export const contentConfigTemplate = (options: {
     ? [
         ...config.content.include,
         ...(config.content.exclude ?? []).map((pattern) => `!${pattern}`),
-        "!**/node_modules/**",
+        // Mirror the filesystem scan's baseline ignores (see BLUME_IGNORE_DIRS):
+        // Astro's content layer roots at the project dir, so a `.`-wide content
+        // root would otherwise re-ingest dependency trees and build output —
+        // e.g. a prior `dist/*.mdx` render — and crash the content-module graph.
+        // The runtime dir (`.blume`, or a custom distDir) is excluded precisely
+        // by `outDirIgnore` instead, so it's left out of this baseline.
+        ...BLUME_IGNORE_DIRS.filter((dir) => dir !== ".blume").map(
+          (dir) => `!**/${dir}/**`
+        ),
         ...outDirIgnore,
       ]
     : [];
@@ -866,7 +883,7 @@ const siteHost = (() => {
 
 export async function GET({ props }) {
   const png = await renderOgImage({
-    accent: data.config.theme.accent,
+    accent: data.config.theme.accent.light,
     brand: data.config.title,
     description: data.config.description,
     logo: data.config.logo?.svg,
@@ -939,7 +956,7 @@ export const catchAllPageTemplate = (options: {
     ? 'import AskAI from "blume/components/islands/AskAI.astro";\n'
     : "";
   const askSlot = options.askEnabled
-    ? '\n  <AskAI slot="ask" strings={ui.ask} />'
+    ? '\n  <AskAI slot="ask" strings={ui.ask} suggestions={data.config.ask?.suggestions ?? []} />'
     : "";
   const mathImport = options.mathEnabled
     ? 'import Math from "blume/components/content/Math.astro";\n'
@@ -1210,7 +1227,9 @@ export const changelogIndexTemplate = (options: {
   const askImport = options.askEnabled
     ? 'import AskAI from "blume/components/islands/AskAI.astro";\n'
     : "";
-  const askSlot = options.askEnabled ? '\n  <AskAI slot="ask" />' : "";
+  const askSlot = options.askEnabled
+    ? '\n  <AskAI slot="ask" strings={data.ui.ask} suggestions={data.config.ask?.suggestions ?? []} />'
+    : "";
   const clientData = options.needsReact
     ? '\n  clientData={{ config: data.config, navigation: data.navigation, page: { route: "/changelog", title: data.config.title + " changelog" } }}'
     : "";

package/src/cli/commands/build.ts

@@ -5,6 +5,7 @@ import { build } from "astro";
 import { defineCommand } from "citty";
 import { join } from "pathe";
 
+import { buildAgentReadability } from "../../ai/agent-readability.ts";
 import { buildLlmsFiles } from "../../ai/llms.ts";
 import { ensureGitignore } from "../../core/gitignore.ts";
 import type { BlumeProject } from "../../core/project-graph.ts";
@@ -218,6 +219,19 @@ const publishBuildArtifacts = async (
     logger.success("Generated robots.txt");
   }
 
+  const agentReadability = buildAgentReadability(project);
+  if (
+    agentReadability &&
+    !existsSync(join(distDir, "agent-readability.json"))
+  ) {
+    await writeFile(
+      join(distDir, "agent-readability.json"),
+      `${JSON.stringify(agentReadability, null, 2)}\n`,
+      "utf-8"
+    );
+    logger.success("Generated agent-readability.json");
+  }
+
   await emitRedirectFiles(project.config, distDir);
 
   const { config } = project;
@@ -231,6 +245,7 @@ const publishBuildArtifacts = async (
       `Redirects  ${config.redirects.length}`,
       `Sitemap    ${sitemap ? "yes" : "no (set deployment.site)"}`,
       `Robots     ${robots ? "yes" : "no"}`,
+      `Agent JSON ${agentReadability ? "yes" : "no"}`,
       `LLM files  ${config.ai.llmsTxt ? "yes" : "no"}`,
       `Server features  ${features.length > 0 ? features.join(", ") : "none"}`,
     ].join("\n")

package/src/cli/commands/dev.ts

@@ -6,9 +6,15 @@ import { defineCommand } from "citty";
 import { generateRuntime } from "../../astro/generate.ts";
 import { showBlumeErrorOverlay } from "../../astro/integration.ts";
 import { scanProject } from "../../core/project-graph.ts";
+import { resolveRuntimeDir } from "../../core/project.ts";
 import { parsePort } from "../args.ts";
 import { coalescedRunner } from "../coalesce.ts";
-import { acquireDevLock, isDevLocked } from "../dev-lock.ts";
+import {
+  acquireDevLock,
+  describeDevLock,
+  readDevLock,
+  updateDevLockPort,
+} from "../dev-lock.ts";
 import { logger } from "../log.ts";
 import { prepareProject } from "../prepare.ts";
 
@@ -47,6 +53,23 @@ export const devCommand = defineCommand({
     const explicitPort = parsePort(args.port);
     const port = explicitPort ?? 4321;
     const devServerUrl = `http://localhost:${port}`;
+
+    // Claim the shared `.blume` dir BEFORE preparing: `prepareProject`
+    // regenerates the runtime, so even a refused second dev server would
+    // otherwise clobber the running one's generated tree (with this
+    // invocation's port baked in) on its way out. Dev never relocates the
+    // runtime dir, so the lock always lives at `<root>/.blume`.
+    const outDir = resolveRuntimeDir(root);
+    const running = readDevLock(outDir);
+    if (running) {
+      logger.error(
+        `A \`blume dev\` server is already running${describeDevLock(running)} in this project. Reuse that server instead of starting a second one — two dev servers would corrupt the shared .blume dir. If it crashed, delete .blume/dev.lock.`
+      );
+      process.exit(1);
+    }
+    const releaseLock = acquireDevLock(outDir, port);
+    process.on("exit", releaseLock);
+
     const project = await prepareProject({
       devServerUrl,
       mode: "dev",
@@ -56,19 +79,6 @@ export const devCommand = defineCommand({
       strict: args.strict,
     });
 
-    // Claim the shared `.blume` dir so a concurrent build/eject/sync refuses
-    // rather than regenerating or deleting it out from under this server. A
-    // second dev server would fight over the same generated tree the same
-    // way, so it must refuse too instead of silently clobbering the lock.
-    if (isDevLocked(project.context.outDir)) {
-      logger.error(
-        "Another `blume dev` is already running in this project; two dev servers would corrupt the shared .blume dir. Stop the other one first (or delete .blume/dev.lock if it crashed)."
-      );
-      process.exit(1);
-    }
-    const releaseLock = acquireDevLock(project.context.outDir);
-    process.on("exit", releaseLock);
-
     const server = await dev({
       logLevel: args.debug ? "debug" : "info",
       root: project.context.outDir,
@@ -79,6 +89,13 @@ export const devCommand = defineCommand({
       },
     });
 
+    // Vite bumps to the next free port when the default is taken, so record
+    // the port the server actually bound — the lock's URL is what a refused
+    // second invocation tells its caller to reuse.
+    if (server.address.port !== port) {
+      updateDevLockPort(outDir, server.address.port);
+    }
+
     // Mirror any initial diagnostics into the browser overlay now the server
     // (and its HMR channel) is up.
     showBlumeErrorOverlay(project.diagnostics);

package/src/cli/dev-lock.ts

@@ -14,26 +14,48 @@ 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
+ * `eject`, or second `dev` 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.
+ * detect a live dev server and refuse — and, because it records the server's
+ * port, point the caller (often an agent that just tried to start its own
+ * server) at the URL to reuse instead.
  */
 
+export interface DevLockInfo {
+  pid: number;
+  /** Port the dev server is bound to, when known. */
+  port?: number;
+}
+
 const lockPath = (outDir: string): string => join(outDir, "dev.lock");
 
+const isValidPid = (pid: unknown): pid is number =>
+  typeof pid === "number" && Number.isInteger(pid) && pid > 0;
+
 /**
- * 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.
+ * Parse a lock file body. Current locks are JSON (`{"pid":123,"port":3001}`);
+ * a bare integer (the pre-port format) still parses as a pid-only lock.
  */
-export const isDevLocked = (outDir: string): boolean => {
-  const path = lockPath(outDir);
-  if (!existsSync(path)) {
-    return false;
+const parseLock = (raw: string): DevLockInfo | null => {
+  let data: unknown;
+  try {
+    data = JSON.parse(raw.trim());
+  } catch {
+    return null;
   }
-  const pid = Number.parseInt(readFileSync(path, "utf-8").trim(), 10);
-  if (!(Number.isInteger(pid) && pid > 0)) {
-    return false;
+  if (isValidPid(data)) {
+    return { pid: data };
   }
+  if (typeof data === "object" && data !== null) {
+    const { pid, port } = data as { pid?: unknown; port?: unknown };
+    if (isValidPid(pid)) {
+      return typeof port === "number" ? { pid, port } : { pid };
+    }
+  }
+  return null;
+};
+
+const isProcessAlive = (pid: number): boolean => {
   try {
     // Signal 0 probes liveness without actually signaling the process.
     process.kill(pid, 0);
@@ -45,15 +67,53 @@ export const isDevLocked = (outDir: string): boolean => {
   }
 };
 
+/**
+ * Read the lock on `outDir` held by a live `blume dev`, or null. A lock left
+ * by a process that has since exited (stale) is treated as absent.
+ */
+export const readDevLock = (outDir: string): DevLockInfo | null => {
+  const path = lockPath(outDir);
+  if (!existsSync(path)) {
+    return null;
+  }
+  const lock = parseLock(readFileSync(path, "utf-8"));
+  return lock && isProcessAlive(lock.pid) ? lock : null;
+};
+
+/** Whether another live `blume dev` holds the lock on `outDir`. */
+export const isDevLocked = (outDir: string): boolean =>
+  readDevLock(outDir) !== null;
+
+const writeLock = (outDir: string, port?: number): void => {
+  writeFileSync(
+    lockPath(outDir),
+    JSON.stringify({
+      pid: process.pid,
+      ...(port === undefined ? {} : { port }),
+    })
+  );
+};
+
+const ownsLock = (outDir: string): boolean => {
+  const path = lockPath(outDir);
+  if (!existsSync(path)) {
+    return false;
+  }
+  try {
+    return parseLock(readFileSync(path, "utf-8"))?.pid === process.pid;
+  } 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);
+export const acquireDevLock = (outDir: string, port?: number): (() => void) => {
   mkdirSync(outDir, { recursive: true });
-  writeFileSync(path, String(process.pid));
+  writeLock(outDir, port);
   let released = false;
   return () => {
     if (released) {
@@ -61,11 +121,8 @@ export const acquireDevLock = (outDir: string): (() => void) => {
     }
     released = true;
     try {
-      if (
-        existsSync(path) &&
-        readFileSync(path, "utf-8").trim() === String(process.pid)
-      ) {
-        rmSync(path, { force: true });
+      if (ownsLock(outDir)) {
+        rmSync(lockPath(outDir), { force: true });
       }
     } catch {
       // Best-effort cleanup; a stale lock is handled by the liveness check.
@@ -73,6 +130,21 @@ export const acquireDevLock = (outDir: string): (() => void) => {
   };
 };
 
+/**
+ * Rewrite this process's lock with the port the server actually bound (the
+ * lock is acquired before the server starts, and Vite may bump a busy port).
+ * A lock owned by another process is left alone.
+ */
+export const updateDevLockPort = (outDir: string, port: number): void => {
+  if (ownsLock(outDir)) {
+    writeLock(outDir, port);
+  }
+};
+
+/** Human-readable location of a locked dev server, e.g. " at http://localhost:3001". */
+export const describeDevLock = (lock: DevLockInfo): string =>
+  lock.port === undefined ? "" : ` at http://localhost:${lock.port}`;
+
 /**
  * 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`
@@ -85,9 +157,10 @@ export const refuseIfDevRunning = (
   action: string,
   runtimeDir?: string
 ): void => {
-  if (isDevLocked(resolveRuntimeDir(root, runtimeDir))) {
+  const lock = readDevLock(resolveRuntimeDir(root, runtimeDir));
+  if (lock) {
     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.`
+      `A \`blume dev\` server is running${describeDevLock(lock)}; ${action} would corrupt its .blume runtime. Reuse that server, stop it first, or re-run with --isolated to build/verify against .blume-verify without touching it.`
     );
     process.exit(1);
   }

package/src/components/content/GithubInfo.astro

@@ -3,10 +3,17 @@
 // at build time (no client JS). Pass `owner`/`repo`, or omit them to use the
 // repo from blume.config. A `GITHUB_TOKEN` env var lifts the API rate limit.
 // If the API is unreachable the card still renders, just without counts.
+import { resolveIcon } from "../../theme/icons.ts";
 import data from "blume:data";
 import { GITHUB_MARK } from "../github-mark.ts";
 import { fetchRepositoryInfo } from "./github-info.ts";
 
+// Star/fork glyphs resolve from Lucide at build time; the `<svg>` wrappers below
+// supply size and the shared `statIcon` class. (The GitHub octocat above is a
+// brand mark, not a Lucide icon, so it stays as GITHUB_MARK.)
+const starIcon = resolveIcon("star")?.body ?? "";
+const forkIcon = resolveIcon("git-fork")?.body ?? "";
+
 interface Props {
   owner?: string;
   repo?: string;
@@ -77,9 +84,8 @@ const statIcon =
               stroke-width="2"
               viewBox="0 0 24 24"
               width="14"
-            >
-              <path d="M11.525 2.295a.53.53 0 0 1 .95 0l2.31 4.679a2.123 2.123 0 0 0 1.595 1.16l5.166.756a.53.53 0 0 1 .294.904l-3.736 3.638a2.123 2.123 0 0 0-.611 1.878l.882 5.14a.53.53 0 0 1-.771.56l-4.618-2.428a2.122 2.122 0 0 0-1.973 0L6.396 21.01a.53.53 0 0 1-.77-.56l.881-5.139a2.122 2.122 0 0 0-.611-1.879L2.16 9.795a.53.53 0 0 1 .294-.906l5.165-.755a2.122 2.122 0 0 0 1.597-1.16z" />
-            </svg>
+              set:html={starIcon}
+            />
             <span>{numbers.format(info.stars)}</span>
           </span>
           <span class="flex items-center gap-1.5">
@@ -94,13 +100,8 @@ const statIcon =
               stroke-width="2"
               viewBox="0 0 24 24"
               width="14"
-            >
-              <circle cx="12" cy="18" r="3" />
-              <circle cx="6" cy="6" r="3" />
-              <circle cx="18" cy="6" r="3" />
-              <path d="M18 9v2c0 .6-.4 1-1 1H7c-.6 0-1-.4-1-1V9" />
-              <path d="M12 12v3" />
-            </svg>
+              set:html={forkIcon}
+            />
             <span>{numbers.format(info.forks)}</span>
           </span>
         </span>

package/src/components/content/TypeTable.astro

@@ -4,6 +4,12 @@
 // the accent-colored prop name (with a `?` suffix when optional) and its type;
 // expanded, the row lifts into a card showing the description and a Type/Default
 // detail grid. Uses native <details>/<summary> so the core stays React-free.
+import { resolveIcon } from "../../theme/icons.ts";
+
+// The row disclosure caret; resolved from Lucide at build time and injected into
+// the summary's `<svg>` (which supplies size and the rotate-on-open transition).
+const chevronDown = resolveIcon("chevron-down")?.body ?? "";
+
 interface TypeEntry {
   default?: string;
   description?: string;
@@ -64,9 +70,8 @@ const columns = "grid grid-cols-[1fr_2fr_auto] items-center gap-4";
               stroke-width="2"
               viewBox="0 0 24 24"
               width="16"
-            >
-              <path d="m6 9 6 6 6-6" />
-            </svg>
+              set:html={chevronDown}
+            />
           </summary>
 
           <div class="border-border border-t px-3 py-3 text-xs">

package/src/components/islands/AskAI.astro

@@ -1,12 +1,76 @@
 ---
 import type { UIStrings } from "../../core/i18n-ui.ts";
+import { resolveIcon } from "../../theme/icons.ts";
 import AskAI from "./ask-ai.tsx";
 
+interface Suggestion {
+  icon?: string;
+  label: string;
+}
+
 interface Props {
   strings?: UIStrings["ask"];
+  suggestions?: Suggestion[];
 }
 
-const { strings } = Astro.props;
+const { strings, suggestions = [] } = Astro.props;
+
+// Icons resolve to inline SVG here (server-only module), so the client island
+// gets ready-to-render markup rather than a name it can't resolve. Bare Lucide
+// bodies carry no styling, so wrap them in a stroke-styled root like Icon.astro.
+const svgFor = (name: string | undefined): string | null => {
+  const resolved = resolveIcon(name ?? "sparkles") ?? resolveIcon("sparkles");
+  return resolved
+    ? `<svg xmlns="http://www.w3.org/2000/svg" viewBox="${resolved.viewBox}" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">${resolved.body}</svg>`
+    : null;
+};
+
+const items = suggestions.map((suggestion) => ({
+  icon: svgFor(suggestion.icon),
+  label: suggestion.label,
+}));
+
+// The panel's own chrome glyphs resolve here too, so the client island carries
+// no icon data. Each value is the bare Lucide body; the island's <Glyph> wraps
+// it in a sized, stroke-styled <svg>. Keyed by role → Lucide icon name.
+const bodyFor = (name: string): string => resolveIcon(name)?.body ?? "";
+const icons = {
+  arrowUp: bodyFor("arrow-up"),
+  chat: bodyFor("message-circle"),
+  clear: bodyFor("trash-2"),
+  close: bodyFor("chevrons-right"),
+  copy: bodyFor("copy"),
+};
 ---
 
-<AskAI client:load strings={strings} />
+<AskAI client:load icons={icons} strings={strings} suggestions={items} />
+
+<style is:global>
+  :root {
+    --blume-ask-width: min(30rem, 100vw);
+  }
+
+  /* Desktop docks the panel and shrinks the page to fit, like vercel.com/docs.
+     On smaller screens the panel is a full-width overlay (no push). */
+  @media (min-width: 1024px) {
+    body {
+      transition: padding-inline-end 0.2s ease-out;
+    }
+
+    body[data-blume-ask="open"] {
+      padding-inline-end: var(--blume-ask-width);
+    }
+  }
+
+  /* The table of contents only shows at xl; reclaim its column for the article
+     while the panel is open so the shrunken content still has room to breathe. */
+  @media (min-width: 1280px) {
+    body[data-blume-ask="open"] [data-blume-toc] {
+      display: none;
+    }
+
+    body[data-blume-ask="open"] [data-blume-doc-grid] {
+      grid-template-columns: 17.5rem minmax(0, 1fr);
+    }
+  }
+</style>