blume 1.4.2 → 1.4.3

package/src/ai/mcp/server.ts

@@ -4,8 +4,15 @@ import {
   CallToolRequestSchema,
   ListToolsRequestSchema,
 } from "@modelcontextprotocol/sdk/types.js";
+import { z } from "zod";
 
-import { stripBasePath, withBasePath } from "../../core/base-path.ts";
+import {
+  normalizeRoute as normalizePageRoute,
+  stripBasePath,
+  withBasePath,
+} from "../../core/base-path.ts";
+import { absoluteUrl } from "../../core/site-url.ts";
+import { trimEnd } from "../../core/trim.ts";
 import { buildOramaIndex, queryOramaIndex } from "../../search/orama-index.ts";
 import type { OramaDoc } from "../../search/orama-index.ts";
 import type { McpData } from "./data.ts";
@@ -15,8 +22,9 @@ import { MCP_TOOLS } from "./tools.ts";
  * The low-level SDK `Server` is used (rather than the high-level `McpServer`)
  * because the latter's `registerTool` is generic over the caller's Zod instance;
  * Blume's zod and the SDK's may resolve to different copies, whose types don't
- * unify. Hand-written JSON Schema and the SDK's own request schemas avoid that
- * entirely.
+ * unify. Each tool's input is defined once in Blume's own zod: the runtime
+ * parse and the JSON Schema advertised by `tools/list` (via `z.toJSONSchema`)
+ * derive from the same definition, so they cannot drift.
  */
 
 /** Default and maximum number of hits returned by `search_docs`. */
@@ -33,88 +41,31 @@ const CORS_HEADERS: Record<string, string> = {
   "Access-Control-Expose-Headers": "Mcp-Session-Id",
 };
 
-/** The optional content-type filter `search_docs` and `list_pages` share. */
-const CONTENT_TYPES_SCHEMA = {
-  description:
-    'Only include pages of these content types (frontmatter `type`, e.g. `["doc", "rfc"]`). `list_pages` shows each page\'s type. Omit to include every type.',
-  items: { type: "string" },
-  type: "array",
-} as const;
-
-/** The optional facet filter `search_docs` and `list_pages` share. */
-const FILTERS_SCHEMA = {
-  additionalProperties: { type: "string" },
-  description:
-    'Only include pages matching every facet, key → required value (e.g. `{"status": "enforced"}`). Facets are metadata the site declares per content type; `list_pages` shows each page\'s facet values. Omit for no facet filtering.',
-  type: "object",
-} as const;
-
-/** JSON Schema for each tool's input, keyed by tool name. */
-const INPUT_SCHEMAS: Record<string, Record<string, unknown>> = {
-  get_navigation: { properties: {}, type: "object" },
-  get_page: {
-    properties: {
-      route: {
-        description: "The page route, e.g. `/guides/install`.",
-        type: "string",
-      },
-    },
-    required: ["route"],
-    type: "object",
-  },
-  list_pages: {
-    properties: {
-      contentTypes: CONTENT_TYPES_SCHEMA,
-      filters: FILTERS_SCHEMA,
-    },
-    type: "object",
-  },
-  search_docs: {
-    properties: {
-      contentTypes: CONTENT_TYPES_SCHEMA,
-      filters: FILTERS_SCHEMA,
-      limit: {
-        description: `Maximum hits to return (default ${DEFAULT_SEARCH_LIMIT}).`,
-        maximum: MAX_SEARCH_LIMIT,
-        minimum: 1,
-        type: "integer",
-      },
-      query: { description: "The search query.", type: "string" },
-    },
-    required: ["query"],
-    type: "object",
-  },
-};
-
-/** The `tools/list` payload, derived from shared metadata + input schemas. */
-const TOOL_DEFINITIONS = MCP_TOOLS.map((tool) => ({
-  annotations: tool.annotations,
-  description: tool.description,
-  inputSchema: INPUT_SCHEMAS[tool.name],
-  name: tool.name,
-  title: tool.title,
-}));
-
-const asString = (value: unknown): string =>
-  typeof value === "string" ? value : "";
+// Each field is a preprocess pipe: the input side accepts the sloppy shapes
+// LLM callers actually send (a bare string for an array field, `[]`/`{}`
+// meaning "no filter", out-of-range limits clamped rather than rejected), and
+// the pipe's *output* side is the clean shape — which is exactly what
+// `z.toJSONSchema` emits for `tools/list`. No coercion can ever fail, so a
+// tool call is never rejected on argument shape, matching the previous
+// hand-rolled coercions.
 
 /**
- * The `contentTypes` filter as a string array, or `undefined` when absent or
- * empty — an agent sending `[]` means "no filter", not "match nothing". A bare
+ * The optional content-type filter `search_docs` and `list_pages` share.
+ * `[]` or no usable strings mean "no filter", not "match nothing"; a bare
  * string is accepted as a one-element list.
  */
-const asContentTypes = (value: unknown): string[] | undefined => {
-  const list = Array.isArray(value)
-    ? value.filter((entry): entry is string => typeof entry === "string")
-    : [value].filter((entry): entry is string => typeof entry === "string");
+const contentTypesField = z.preprocess((value) => {
+  const list = (Array.isArray(value) ? value : [value]).filter(
+    (entry): entry is string => typeof entry === "string"
+  );
   return list.length > 0 ? list : undefined;
-};
+}, z.array(z.string()).optional().describe('Only include pages of these content types (frontmatter `type`, e.g. `["doc", "rfc"]`). `list_pages` shows each page\'s type. Omit to include every type.'));
 
 /**
- * The `filters` facet map with only its string-valued entries, or `undefined`
- * when nothing usable remains — an empty `{}` means "no filter".
+ * The optional facet filter `search_docs` and `list_pages` share. Only
+ * string-valued entries survive; an empty `{}` means "no filter".
  */
-const asFacetFilters = (value: unknown): Record<string, string> | undefined => {
+const filtersField = z.preprocess((value) => {
   if (typeof value !== "object" || value === null || Array.isArray(value)) {
     return;
   }
@@ -122,8 +73,75 @@ const asFacetFilters = (value: unknown): Record<string, string> | undefined => {
     (entry): entry is [string, string] => typeof entry[1] === "string"
   );
   return entries.length > 0 ? Object.fromEntries(entries) : undefined;
+}, z.record(z.string(), z.string()).optional().describe('Only include pages matching every facet, key → required value (e.g. `{"status": "enforced"}`). Facets are metadata the site declares per content type; `list_pages` shows each page\'s facet values. Omit for no facet filtering.'));
+
+/** Clamped into range rather than rejected; non-numeric means the default. */
+const limitField = z.preprocess(
+  (value) => {
+    const num = typeof value === "number" ? value : Number(value);
+    return Number.isFinite(num)
+      ? Math.min(Math.max(Math.trunc(num), 1), MAX_SEARCH_LIMIT)
+      : undefined;
+  },
+  z
+    .int()
+    .min(1)
+    .max(MAX_SEARCH_LIMIT)
+    .optional()
+    .describe(`Maximum hits to return (default ${DEFAULT_SEARCH_LIMIT}).`)
+);
+
+/** A required text field; a missing or non-string value coerces to "". */
+const textField = (description: string) =>
+  z.preprocess(
+    (value) => (typeof value === "string" ? value : ""),
+    z.string().describe(description)
+  );
+
+/** Every tool's input schema — the runtime parse and tools/list source. */
+const TOOL_INPUTS = {
+  get_navigation: z.object({}),
+  get_page: z.object({
+    route: textField("The page route, e.g. `/guides/install`."),
+  }),
+  list_pages: z.object({
+    contentTypes: contentTypesField,
+    filters: filtersField,
+  }),
+  search_docs: z.object({
+    contentTypes: contentTypesField,
+    filters: filtersField,
+    limit: limitField,
+    query: textField("The search query."),
+  }),
 };
 
+/**
+ * A tool's advertised JSON Schema. The dialect key is dropped (noise in a
+ * tools/list payload), as is the root `additionalProperties: false` — the
+ * runtime strips unknown keys rather than rejecting them, and the advertised
+ * schema shouldn't promise stricter validation than the server performs.
+ */
+const inputSchemaFor = (schema: z.ZodType): Record<string, unknown> => {
+  const {
+    $schema: _dialect,
+    additionalProperties: _closed,
+    ...rest
+  } = z.toJSONSchema(schema);
+  return rest;
+};
+
+/** The `tools/list` payload, derived from shared metadata + input schemas. */
+const TOOL_DEFINITIONS = MCP_TOOLS.map((tool) => ({
+  annotations: tool.annotations,
+  description: tool.description,
+  inputSchema: inputSchemaFor(
+    TOOL_INPUTS[tool.name as keyof typeof TOOL_INPUTS]
+  ),
+  name: tool.name,
+  title: tool.title,
+}));
+
 /** Whether a page's facet values satisfy every requested filter entry. */
 const matchesFacets = (
   facets: Record<string, string> | undefined,
@@ -131,14 +149,6 @@ const matchesFacets = (
 ): boolean =>
   Object.entries(filters).every(([key, value]) => facets?.[key] === value);
 
-const asLimit = (value: unknown): number => {
-  const num = typeof value === "number" ? value : Number(value);
-  if (!Number.isFinite(num)) {
-    return DEFAULT_SEARCH_LIMIT;
-  }
-  return Math.min(Math.max(Math.trunc(num), 1), MAX_SEARCH_LIMIT);
-};
-
 /**
  * Normalize a user-supplied route to a `pages` key (`/`, `/a/b`, no suffix).
  * Accepts a full URL too — `search_docs` hits and llms.txt entries carry
@@ -160,11 +170,10 @@ const normalizeRoute = (input: string, data: McpData): string => {
   } catch {
     // Malformed percent sequence — compare it as written.
   }
-  const noTrailing = value.replace(/\/+$/u, "");
-  const noSuffix = noTrailing.replace(/\.mdx?$/u, "");
-  const withSlash = noSuffix.startsWith("/") ? noSuffix : `/${noSuffix}`;
-  const based = stripBasePath(data.base, withSlash);
-  return based === "" ? "/" : based;
+  // Trailing slashes come off before the suffix so `/a/b.md/` still loses its
+  // `.md`; normalizePageRoute then settles the leading slash.
+  const noSuffix = trimEnd(value, "/").replace(/\.mdx?$/u, "");
+  return stripBasePath(data.base, normalizePageRoute(noSuffix));
 };
 
 /** Build the absolute (or root-relative) URL for a route. */
@@ -174,7 +183,7 @@ const urlFor = (route: string, data: McpData): string => {
   const path = withBasePath(data.base, route);
   // Concatenate rather than `new URL(path, site)` — a root-absolute path
   // would drop the base path of a subpath deployment (`acme.com/docs`).
-  return data.site ? `${data.site.replace(/\/+$/u, "")}${path}` : path;
+  return data.site ? absoluteUrl(data.site, path) : path;
 };
 
 /** A hit's excerpt: its description, else the head of its content with an
@@ -234,14 +243,15 @@ export const buildServer = (
     const { arguments: args = {}, name } = request.params;
 
     if (name === "search_docs") {
+      const input = TOOL_INPUTS.search_docs.parse(args);
       const db = await index();
       const hits = await queryOramaIndex(
         db,
-        asString(args.query),
-        asLimit(args.limit),
+        input.query,
+        input.limit ?? DEFAULT_SEARCH_LIMIT,
         {
-          contentTypes: asContentTypes(args.contentTypes),
-          facets: asFacetFilters(args.filters),
+          contentTypes: input.contentTypes,
+          facets: input.filters,
         }
       );
       // `route` is the key `get_page` takes (the tool descriptions promise
@@ -258,7 +268,8 @@ export const buildServer = (
     }
 
     if (name === "get_page") {
-      const key = normalizeRoute(asString(args.route), data);
+      const input = TOOL_INPUTS.get_page.parse(args);
+      const key = normalizeRoute(input.route, data);
       const markdown = data.pages[key];
       if (markdown === undefined) {
         return text(
@@ -270,8 +281,7 @@ export const buildServer = (
     }
 
     if (name === "list_pages") {
-      const contentTypes = asContentTypes(args.contentTypes);
-      const filters = asFacetFilters(args.filters);
+      const { contentTypes, filters } = TOOL_INPUTS.list_pages.parse(args);
       const routes = data.routes.filter(
         (route) =>
           (!contentTypes || contentTypes.includes(route.contentType)) &&

package/src/ai/tar.ts

@@ -1,10 +1,15 @@
 import { gzipSync } from "node:zlib";
 
+import { createTar } from "nanotar";
+
 /**
- * Minimal, dependency-free `.tar.gz` writer for agent-skill archives (POSIX
- * ustar). Deterministic by construction — fixed mtime/uid/gid, caller-ordered
- * entries, and Node's gzip header carries no timestamp — so a skill's archive
- * digest only changes when its content does.
+ * `.tar.gz` writer for agent-skill archives, on nanotar's ustar writer.
+ * Deterministic by construction — fixed mtime/uid/gid/owner attrs,
+ * caller-ordered entries, and Node's gzip header carries no timestamp — so a
+ * skill's archive digest only changes when its content does. That holds per
+ * machine: the tar bytes are portable, but zlib's compressed stream differs
+ * across architectures, so gzip-layer digests are not comparable across
+ * platforms.
  */
 
 /** One regular file to archive. Paths are `/`-separated, relative, no `..`. */
@@ -17,67 +22,18 @@ export interface TarEntry {
   path: string;
 }
 
-const BLOCK = 512;
 /** ustar `name` field capacity; skill layouts are shallow, so no `prefix`. */
 const NAME_MAX = 100;
 
 const encoder = new TextEncoder();
 
-/** Write an octal field: zero-padded digits followed by a NUL terminator. */
-const octal = (
-  header: Uint8Array,
-  offset: number,
-  length: number,
-  value: number
-): void => {
-  const text = value.toString(8).padStart(length - 1, "0");
-  header.set(encoder.encode(text), offset);
-  header[offset + length - 1] = 0;
-};
-
-const text = (header: Uint8Array, offset: number, value: string): void => {
-  header.set(encoder.encode(value), offset);
-};
-
-const fileHeader = (entry: TarEntry): Uint8Array => {
-  const header = new Uint8Array(BLOCK);
-  text(header, 0, entry.path);
-  octal(header, 100, 8, entry.executable ? 0o755 : 0o644);
-  // uid and gid: root-owned, fixed for determinism.
-  octal(header, 108, 8, 0);
-  octal(header, 116, 8, 0);
-  octal(header, 124, 12, entry.content.byteLength);
-  // mtime: fixed at the epoch for determinism.
-  octal(header, 136, 12, 0);
-  // typeflag "0": regular file.
-  text(header, 156, "0");
-  text(header, 257, "ustar");
-  header[262] = 0;
-  text(header, 263, "00");
-  // devmajor and devminor.
-  octal(header, 329, 8, 0);
-  octal(header, 337, 8, 0);
-  // Checksum: computed with the checksum field treated as eight spaces, then
-  // written as six octal digits, NUL, space (the historical ustar format).
-  header.fill(0x20, 148, 156);
-  let sum = 0;
-  for (const byte of header) {
-    sum += byte;
-  }
-  text(header, 148, sum.toString(8).padStart(6, "0"));
-  header[154] = 0;
-  header[155] = 0x20;
-  return header;
-};
-
 /**
  * Build a gzipped ustar archive of the given files, in the given order. Paths
- * longer than the ustar `name` field or escaping the archive root are the
- * caller's responsibility to filter — this throws to surface a programming
- * error rather than emitting a corrupt archive.
+ * longer than the ustar `name` field or escaping the archive root throw to
+ * surface a programming error — nanotar would silently truncate an oversized
+ * name into a corrupt archive, so the validation stays here.
  */
 export const buildTarGz = (entries: readonly TarEntry[]): Uint8Array => {
-  const blocks: Uint8Array[] = [];
   for (const entry of entries) {
     if (encoder.encode(entry.path).byteLength > NAME_MAX) {
       throw new Error(`tar path exceeds ${NAME_MAX} bytes: ${entry.path}`);
@@ -85,20 +41,23 @@ export const buildTarGz = (entries: readonly TarEntry[]): Uint8Array => {
     if (entry.path.startsWith("/") || entry.path.split("/").includes("..")) {
       throw new Error(`tar path must be archive-relative: ${entry.path}`);
     }
-    blocks.push(fileHeader(entry), entry.content);
-    const overhang = entry.content.byteLength % BLOCK;
-    if (overhang > 0) {
-      blocks.push(new Uint8Array(BLOCK - overhang));
-    }
-  }
-  // End-of-archive marker: two zero blocks.
-  blocks.push(new Uint8Array(BLOCK * 2));
-  const total = blocks.reduce((sum, block) => sum + block.byteLength, 0);
-  const tar = new Uint8Array(total);
-  let offset = 0;
-  for (const block of blocks) {
-    tar.set(block, offset);
-    offset += block.byteLength;
   }
+  const tar = createTar(
+    entries.map((entry) => ({
+      // Root-owned, epoch-mtime, empty owner names: every field a rebuild
+      // could vary is pinned so the archive bytes are a function of content.
+      attrs: {
+        gid: 0,
+        group: "",
+        mode: entry.executable ? "755" : "644",
+        mtime: 0,
+        uid: 0,
+        user: "",
+      },
+      data: entry.content,
+      name: entry.path,
+    }))
+  );
+  // Sync gzip with a pinned level; Node writes no timestamp into the header.
   return new Uint8Array(gzipSync(tar, { level: 9 }));
 };

package/src/astro/examples.ts

@@ -1,5 +1,6 @@
 import { readFile } from "node:fs/promises";
 
+import pMap from "p-map";
 import { join, relative } from "pathe";
 import { glob } from "tinyglobby";
 
@@ -48,6 +49,9 @@ const EXAMPLE_FILE = /\.(?<ext>astro|jsx|svelte|tsx|vue)$/u;
 // Renderable example files when `examples` names a plain directory.
 const DEFAULT_EXAMPLE_GLOB = "**/*.{astro,jsx,svelte,tsx,vue}";
 
+/** Ceiling on concurrent example-file reads; unbounded fan-out risks EMFILE. */
+const READ_CONCURRENCY = 16;
+
 // Glob magic that turns `examples` from a plain directory into a pattern. `()`,
 // `@`, and `+` are excluded so literal path segments (npm scopes, parens) keep
 // resolving as directories; the extglob leads `*?!` still trigger here.
@@ -102,9 +106,9 @@ export const discoverExamples = async (
     onlyFiles: true,
   });
   const files = matches.toSorted();
-  const sources = await Promise.all(
-    files.map((file) => readFile(file, "utf-8"))
-  );
+  const sources = await pMap(files, (file) => readFile(file, "utf-8"), {
+    concurrency: READ_CONCURRENCY,
+  });
 
   const examples: ExampleSpec[] = [];
   const warnings: string[] = [];

package/src/astro/generate.ts

@@ -12,11 +12,13 @@ import {
 import { createRequire } from "node:module";
 import { pathToFileURL } from "node:url";
 
+import { imageSize } from "image-size";
+import pMap from "p-map";
 import { basename, dirname, join, normalize, relative, resolve } from "pathe";
 import { glob } from "tinyglobby";
 
 import { buildAskData } from "../ai/ask-data.ts";
-import { resolveAskBackend } from "../ai/ask.ts";
+import { askBackendRuntimeDep, resolveAskBackend } from "../ai/ask.ts";
 import { buildRawMarkdown, markdownRoutePaths } from "../ai/markdown.ts";
 import { buildMcpData } from "../ai/mcp/data.ts";
 import { buildMcpDiscovery, buildMcpServerCard } from "../ai/mcp/discovery.ts";
@@ -638,6 +640,33 @@ export const searchProviderWarnings = (
   return warnings;
 };
 
+/**
+ * Warn when the Ask AI backend's provider SDK is missing. Like search provider
+ * SDKs, these are optional peers the project must install (only `gateway`
+ * needs nothing beyond the core `ai` package Blume ships) — warn early with
+ * the package name rather than let Vite fail to resolve the import opaquely.
+ * Same resolution rule as {@link searchProviderWarnings}: available if the
+ * project installed it or Blume can resolve it. `pkgDir` is injectable for
+ * testing.
+ */
+export const askProviderWarnings = (
+  ask: ResolvedConfig["ai"]["ask"],
+  root: string,
+  pkgDir: string = packageRoot()
+): string[] => {
+  // An external `endpoint` means no generated route, so no SDK is imported.
+  if (!ask?.enabled || ask.endpoint) {
+    return [];
+  }
+  const dep = askBackendRuntimeDep(ask);
+  if (!dep || canResolveFrom(root, dep) || canResolveFrom(pkgDir, dep)) {
+    return [];
+  }
+  return [
+    `Ask AI provider "${ask.provider}" needs "${dep}", which isn't installed. Run \`npm install ${dep}\` (or your package manager's equivalent).`,
+  ];
+};
+
 /** Absolute path to the configured `examples.css`, or null when unset. */
 const examplesCssFile = (
   root: string,
@@ -708,6 +737,9 @@ export const detectNeedsReact = async (root: string): Promise<boolean> => {
 const containsMath = (content: string): boolean =>
   content.includes("$$") || content.includes("<Math");
 
+/** Ceiling on concurrent content-file reads; unbounded fan-out risks EMFILE. */
+const READ_CONCURRENCY = 16;
+
 /**
  * Detect whether the project can render math: block math (`$$…$$`) or an
  * explicit `<Math>` tag in any local `.md`/`.mdx`, or in staged (non-filesystem)
@@ -726,9 +758,9 @@ export const detectUsesMath = async (
     ignore: ["**/node_modules/**", "**/.blume/**", "**/dist/**"],
     onlyFiles: true,
   });
-  const contents = await Promise.all(
-    files.map((file) => readOptional(join(root, file)))
-  );
+  const contents = await pMap(files, (file) => readOptional(join(root, file)), {
+    concurrency: READ_CONCURRENCY,
+  });
   return [...contents, ...staged].some(containsMath);
 };
 
@@ -838,33 +870,24 @@ interface LogoDimensions {
   width: number;
 }
 
-const SVG_ROOT = /<svg\b(?<attributes>[^>]*)>/u;
-const SVG_WIDTH = /\bwidth\s*=\s*["'](?<value>[^"']+)["']/u;
-const SVG_HEIGHT = /\bheight\s*=\s*["'](?<value>[^"']+)["']/u;
-const SVG_LENGTH = /^\s*(?<value>[\d.]+)(?:px)?\s*$/u;
-const SVG_VIEW_BOX =
-  /\bviewBox\s*=\s*["'][\d.-]+[\s,]+[\d.-]+[\s,]+(?<width>[\d.]+)[\s,]+(?<height>[\d.]+)["']/u;
-
-const parseSvgLength = (value: string | undefined): number | undefined => {
-  const length = Number(value?.match(SVG_LENGTH)?.groups?.value);
-  return length > 0 ? length : undefined;
-};
-
-/** Read dimensions from an SVG's explicit size or its view box. */
+/**
+ * Read dimensions from an SVG's explicit size or its view box. Measured with
+ * image-size — the same parser og/card.ts uses for the OG brand mark, so the
+ * header and the card can't disagree about one logo — which also tolerates
+ * the spellings the old regex missed (unquoted values, `em`/`pt` lengths, a
+ * `>` inside another attribute). An SVG with no usable size returns partial
+ * dimensions or throws; both collapse to undefined.
+ */
 const svgDimensions = (svg: string | undefined): LogoDimensions | undefined => {
-  const attributes = svg?.match(SVG_ROOT)?.groups?.attributes;
-  const width = parseSvgLength(attributes?.match(SVG_WIDTH)?.groups?.value);
-  const height = parseSvgLength(attributes?.match(SVG_HEIGHT)?.groups?.value);
-  if (width && height) {
-    return { height, width };
+  if (!svg) {
+    return;
+  }
+  try {
+    const { height, width } = imageSize(Buffer.from(svg));
+    return height && width ? { height, width } : undefined;
+  } catch {
+    return undefined;
   }
-
-  const viewBox = attributes?.match(SVG_VIEW_BOX);
-  const viewBoxWidth = Number(viewBox?.groups?.width);
-  const viewBoxHeight = Number(viewBox?.groups?.height);
-  return viewBoxWidth > 0 && viewBoxHeight > 0
-    ? { height: viewBoxHeight, width: viewBoxWidth }
-    : undefined;
 };
 
 /** Read a local SVG logo from the project root or public directory. */
@@ -1370,7 +1393,7 @@ const writeAskFiles = async (
   }
   await write(
     join(srcDir, "pages", "api", "ask.ts"),
-    askEndpointTemplate(resolveAskBackend(ask), grounded)
+    askEndpointTemplate(resolveAskBackend(ask), grounded, ask.instructions)
   );
 };
 
@@ -1878,10 +1901,11 @@ export const generateRuntime = async (
     ...islandDiscovery.islands.map((island) => island.name),
     ...overrideTags,
   ]);
-  // Missing-dependency preflights: the search provider's SDK, the deployment
-  // adapter's package, and — since React ships with Blume while Vue/Svelte
-  // don't — any island framework's Astro integration. Warn early rather than
-  // let Vite fail to resolve them opaquely.
+  // Missing-dependency preflights: the search provider's SDK, the Ask AI
+  // backend's provider SDK, the deployment adapter's package, and — since
+  // React ships with Blume while Vue/Svelte don't — any island framework's
+  // Astro integration. Warn early rather than let Vite fail to resolve them
+  // opaquely.
   warnings.push(
     ...validateUsedComponents(
       project.graph.pages,
@@ -1889,6 +1913,7 @@ export const generateRuntime = async (
       new Set(registry.map((item) => item.name))
     ).map(diagnosticWarning),
     ...searchProviderWarnings(config.search.provider, context.root),
+    ...askProviderWarnings(config.ai.ask, context.root),
     ...deploymentAdapterWarnings(config.deployment, context.root),
     ...islandFrameworkWarnings(frameworks, context.root)
   );

package/src/astro/islands.ts

@@ -1,5 +1,6 @@
 import { readFile } from "node:fs/promises";
 
+import pMap from "p-map";
 import { basename, join } from "pathe";
 import { glob } from "tinyglobby";
 
@@ -29,6 +30,9 @@ export interface IslandDiscovery {
 /** Hydration mode used when an island doesn't declare one. */
 const DEFAULT_CLIENT: IslandClientMode = "visible";
 
+/** Ceiling on concurrent island-file reads; unbounded fan-out risks EMFILE. */
+const READ_CONCURRENCY = 16;
+
 const VALID_MODES = new Set<IslandClientMode>([
   "idle",
   "load",
@@ -92,9 +96,9 @@ export const discoverIslands = async (
     onlyFiles: true,
   });
   const files = matches.toSorted();
-  const sources = await Promise.all(
-    files.map((file) => readFile(file, "utf-8"))
-  );
+  const sources = await pMap(files, (file) => readFile(file, "utf-8"), {
+    concurrency: READ_CONCURRENCY,
+  });
 
   const islands: IslandSpec[] = [];
   const warnings: string[] = [];