blume 1.7.2 → 2.0.0

package/src/search/adapters/orama-cloud.ts

@@ -0,0 +1,51 @@
+import { z } from "zod";
+
+import type { JsonValue } from "../../core/adapter.ts";
+import type { SearchAdapter } from "./types.ts";
+
+/**
+ * Public Orama Cloud credentials. The browser queries `endpoint` with the
+ * public `apiKey`; the build-time sync pushes records to `indexId` with
+ * `ORAMA_PRIVATE_API_KEY`, which never enters the config.
+ */
+export interface OramaCloudNamedOptions {
+  /** The public API key (it ships to the browser). */
+  apiKey: string;
+  endpoint: string;
+  /** Index id used by the build-time sync; omit to skip syncing. */
+  indexId?: string;
+}
+
+/**
+ * Options for {@link oramaCloud}: the named options plus any other client
+ * option, forwarded to the browser verbatim. JSON values only.
+ */
+export type OramaCloudOptions = OramaCloudNamedOptions & {
+  [option: string]: JsonValue;
+};
+
+export type OramaCloudAdapter = SearchAdapter<
+  "orama-cloud",
+  "hosted",
+  OramaCloudOptions
+>;
+
+export const oramaCloudOptionsSchema = z
+  .object({
+    apiKey: z.string(),
+    endpoint: z.string(),
+    indexId: z.string().optional(),
+  })
+  .catchall(z.json());
+
+/**
+ * Hosted Orama. The browser queries your index endpoint directly; each
+ * `blume build` snapshots the records into the index and deploys it.
+ */
+export const oramaCloud = (options: OramaCloudOptions): OramaCloudAdapter => ({
+  kind: "orama-cloud",
+  mode: "hosted",
+  options,
+  requiredSecrets: [],
+  runtimeDeps: ["@oramacloud/client"],
+});

package/src/search/adapters/orama.ts

@@ -0,0 +1,24 @@
+import { z } from "zod";
+
+import type { KeylessSearchOptions, SearchAdapter } from "./types.ts";
+
+/** Orama takes no options; unknown keys fail config validation. */
+export type OramaOptions = KeylessSearchOptions;
+
+export type OramaAdapter = SearchAdapter<"orama", "static", OramaOptions>;
+
+export const oramaOptionsSchema = z.strictObject({});
+
+/**
+ * Blume's default search: a JSON index built from the source files, served
+ * at `/blume-search.json` and queried in the browser. Keyless, and live in
+ * `blume dev`. The tokenizer follows `i18n.defaultLocale`, so non-Latin
+ * scripts are word-segmented.
+ */
+export const orama = (options: OramaOptions = {}): OramaAdapter => ({
+  kind: "orama",
+  mode: "static",
+  options,
+  requiredSecrets: [],
+  runtimeDeps: ["@orama/orama"],
+});

package/src/search/adapters/pagefind.ts

@@ -0,0 +1,27 @@
+import { z } from "zod";
+
+import type { KeylessSearchOptions, SearchAdapter } from "./types.ts";
+
+/** Pagefind takes no options; unknown keys fail config validation. */
+export type PagefindOptions = KeylessSearchOptions;
+
+export type PagefindAdapter = SearchAdapter<
+  "pagefind",
+  "pagefind",
+  PagefindOptions
+>;
+
+export const pagefindOptionsSchema = z.strictObject({});
+
+/**
+ * Pagefind indexes the built HTML after `blume build` and loads the index in
+ * shards on demand, so the initial payload stays small on very large sites.
+ * The index only exists in the production build, not in `blume dev`.
+ */
+export const pagefind = (options: PagefindOptions = {}): PagefindAdapter => ({
+  kind: "pagefind",
+  mode: "pagefind",
+  options,
+  requiredSecrets: [],
+  runtimeDeps: [],
+});

package/src/search/adapters/registry.ts

@@ -0,0 +1,131 @@
+import { z } from "zod";
+
+import { adapterDescriptorSchema } from "../../core/adapter.ts";
+import { algolia, algoliaOptionsSchema } from "./algolia.ts";
+import type { AlgoliaAdapter } from "./algolia.ts";
+import { flexsearch, flexsearchOptionsSchema } from "./flexsearch.ts";
+import type { FlexsearchAdapter } from "./flexsearch.ts";
+import { mixedbread, mixedbreadOptionsSchema } from "./mixedbread.ts";
+import type { MixedbreadAdapter } from "./mixedbread.ts";
+import { oramaCloud, oramaCloudOptionsSchema } from "./orama-cloud.ts";
+import type { OramaCloudAdapter } from "./orama-cloud.ts";
+import { orama, oramaOptionsSchema } from "./orama.ts";
+import type { OramaAdapter } from "./orama.ts";
+import { pagefind, pagefindOptionsSchema } from "./pagefind.ts";
+import type { PagefindAdapter } from "./pagefind.ts";
+import type {
+  KeylessSearchOptions,
+  SearchAdapter,
+  SearchAdapterMode,
+} from "./types.ts";
+import { typesense, typesenseOptionsSchema } from "./typesense.ts";
+import type { TypesenseAdapter } from "./typesense.ts";
+
+/** Every descriptor a factory can return. */
+export type AnySearchAdapter =
+  | AlgoliaAdapter
+  | FlexsearchAdapter
+  | MixedbreadAdapter
+  | OramaAdapter
+  | OramaCloudAdapter
+  | PagefindAdapter
+  | TypesenseAdapter;
+
+/** The resolved form of `search: false`: search is disabled. */
+export type NoneSearchAdapter = SearchAdapter<
+  "none",
+  "none",
+  KeylessSearchOptions
+>;
+
+/** What `config.search.provider` resolves to: an adapter, or `none`. */
+export type ResolvedSearchAdapter = AnySearchAdapter | NoneSearchAdapter;
+
+/** Every adapter identity, including the resolved `none`. */
+export type SearchAdapterKind = ResolvedSearchAdapter["kind"];
+
+export const NONE_SEARCH_ADAPTER: NoneSearchAdapter = {
+  kind: "none",
+  mode: "none",
+  options: {},
+  requiredSecrets: [],
+  runtimeDeps: [],
+};
+
+/**
+ * The descriptor shape a factory returns: the shared adapter contract plus
+ * the search-specific `mode`. Only `kind` and `options` carry information —
+ * the metadata lists are validated for shape, then re-derived from the
+ * factory below so a descriptor that went through JSON resolves to the same
+ * canonical metadata Blume ships.
+ */
+const descriptor = <
+  Kind extends string,
+  Mode extends SearchAdapterMode,
+  Options extends z.ZodType,
+>(
+  kind: Kind,
+  mode: Mode,
+  options: Options
+) => adapterDescriptorSchema(kind, options).extend({ mode: z.literal(mode) });
+
+/** One variant per public adapter factory. */
+const adapterVariants = [
+  descriptor("algolia", "hosted", algoliaOptionsSchema),
+  descriptor("flexsearch", "static", flexsearchOptionsSchema),
+  descriptor("mixedbread", "server", mixedbreadOptionsSchema),
+  descriptor("orama", "static", oramaOptionsSchema),
+  descriptor("orama-cloud", "hosted", oramaCloudOptionsSchema),
+  descriptor("pagefind", "pagefind", pagefindOptionsSchema),
+  descriptor("typesense", "hosted", typesenseOptionsSchema),
+] as const;
+
+/** What a public factory returns, as the config schema accepts it. */
+export type SearchAdapterInput = z.input<(typeof adapterVariants)[number]>;
+
+/**
+ * Validates a descriptor — one a factory returned, or the `none` descriptor
+ * the config schema substitutes for `false` — and resolves it to the
+ * canonical form, so every consumer reads `mode`, `runtimeDeps`, and
+ * `requiredSecrets` straight off the descriptor. `none` is internal: it is
+ * not part of {@link SearchAdapterInput}, so `search: { kind: "none" }` is a
+ * type error even though the runtime schema admits it.
+ */
+export const resolvedSearchAdapterSchema = z
+  .discriminatedUnion("kind", [
+    ...adapterVariants,
+    descriptor("none", "none", z.strictObject({})),
+  ])
+  .transform((value): ResolvedSearchAdapter => {
+    switch (value.kind) {
+      case "algolia": {
+        return algolia(value.options);
+      }
+      case "flexsearch": {
+        return flexsearch(value.options);
+      }
+      case "mixedbread": {
+        return mixedbread(value.options);
+      }
+      case "none": {
+        return NONE_SEARCH_ADAPTER;
+      }
+      case "orama": {
+        return orama(value.options);
+      }
+      case "orama-cloud": {
+        return oramaCloud(value.options);
+      }
+      case "pagefind": {
+        return pagefind(value.options);
+      }
+      default: {
+        // Only Typesense is left, and TypeScript has narrowed `value` to it.
+        // It returns after the switch rather than from a last case block:
+        // Bun 1.4.0's line coverage never credits the closing brace of a
+        // switch's final block, which would fail the 100% gate in CI.
+        break;
+      }
+    }
+    return typesense(value.options);
+  });

package/src/search/adapters/types.ts

@@ -0,0 +1,46 @@
+import type { AdapterDescriptor } from "../../core/adapter.ts";
+
+/**
+ * How a search adapter integrates with the generated runtime.
+ *
+ * - `static` adapters ship a client-side index (`blume-search.json`) that the
+ *   browser loads and queries — Orama, FlexSearch.
+ * - `pagefind` builds its own index from the rendered HTML after the build.
+ * - `hosted` adapters are queried directly from the browser against an
+ *   external service, with a build-time sync uploading the index — Algolia,
+ *   Orama Cloud, Typesense.
+ * - `server` adapters proxy queries through a generated `/api/search` endpoint
+ *   that holds a secret key, so they require server output — Mixedbread.
+ * - `none` is the resolved form of `search: false`: search is disabled.
+ */
+export type SearchAdapterMode =
+  | "static"
+  | "pagefind"
+  | "hosted"
+  | "server"
+  | "none";
+
+/**
+ * Options for an adapter that takes none. The generated client never reads
+ * them — the static engines are configured from `i18n`, and Pagefind indexes
+ * the built HTML — so unknown keys fail config validation instead of passing
+ * silently. Adding a real option later is then additive, never a behavior
+ * change for a key that used to be ignored.
+ */
+export type KeylessSearchOptions = Record<string, never>;
+
+/**
+ * The descriptor a search adapter factory returns and `blume.config.ts`
+ * carries under `search`: the shared {@link AdapterDescriptor} contract plus
+ * the adapter's integration `mode`. It is plain data, never a live client —
+ * the runtime templates inline it as a literal into `.blume/` and ejected
+ * files, so every field must survive a JSON round-trip.
+ */
+export interface SearchAdapter<
+  Kind extends string = string,
+  Mode extends SearchAdapterMode = SearchAdapterMode,
+  Options = object,
+> extends AdapterDescriptor<Kind, Options> {
+  /** How the generated runtime queries this adapter. */
+  mode: Mode;
+}

package/src/search/adapters/typesense.ts

@@ -0,0 +1,57 @@
+import { z } from "zod";
+
+import type { JsonValue } from "../../core/adapter.ts";
+import type { SearchAdapter } from "./types.ts";
+
+/**
+ * Connection details for a self-hosted or cloud Typesense node. The browser
+ * queries the collection with the search-only `apiKey`; the build-time sync
+ * recreates the collection with `TYPESENSE_ADMIN_API_KEY`, which never enters
+ * the config.
+ */
+export interface TypesenseNamedOptions {
+  /** The search-only API key (public — it ships to the browser). */
+  apiKey: string;
+  collection: string;
+  host: string;
+  /** Defaults to 443. */
+  port?: number;
+  /** Defaults to `https`. */
+  protocol?: "http" | "https";
+}
+
+/**
+ * Options for {@link typesense}: the named options plus any other client
+ * option, forwarded to the browser verbatim. JSON values only.
+ */
+export type TypesenseOptions = TypesenseNamedOptions & {
+  [option: string]: JsonValue;
+};
+
+export type TypesenseAdapter = SearchAdapter<
+  "typesense",
+  "hosted",
+  TypesenseOptions
+>;
+
+export const typesenseOptionsSchema = z
+  .object({
+    apiKey: z.string(),
+    collection: z.string(),
+    host: z.string(),
+    port: z.number().int().positive().optional(),
+    protocol: z.enum(["http", "https"]).optional(),
+  })
+  .catchall(z.json());
+
+/**
+ * Hosted search on Typesense. Each `blume build` drops and recreates the
+ * collection so deleted or renamed pages don't linger as stale hits.
+ */
+export const typesense = (options: TypesenseOptions): TypesenseAdapter => ({
+  kind: "typesense",
+  mode: "hosted",
+  options,
+  requiredSecrets: [],
+  runtimeDeps: ["typesense"],
+});

package/src/search/build.ts

@@ -1,4 +1,7 @@
-import { join } from "pathe";
+import { mkdir, writeFile } from "node:fs/promises";
+
+import { close, createIndex } from "pagefind";
+import { dirname, join } from "pathe";
 
 /**
  * Build a local Pagefind search index over the built site. Pagefind indexes
@@ -6,22 +9,45 @@ import { join } from "pathe";
  * `data-pagefind-ignore`, which Blume stamps on non-indexable pages
  * (search-excluded, or hidden without the opt-in), so those stay out.
  *
+ * Pagefind is imported statically, not with `import()`: this runs in the
+ * `astro:build:done` hook, after Astro has closed the module runner an
+ * installed Blume's config was evaluated in (see `core/node-require.ts`), and
+ * Pagefind ships only an `import` export, so `require` can't load it either.
+ *
+ * The index files are fetched with `getFiles()` and written here rather than
+ * with Pagefind's `writeFiles()`: in service mode Pagefind acknowledges
+ * `writeFiles()` once tokio has buffered the writes, not once they are on
+ * disk, and `close()` kills the backend, so a loaded CI host can ship a
+ * truncated `pagefind-entry.json` (Pagefind/pagefind#1271). Writing the bytes
+ * ourselves puts them on disk before the backend goes away. Fixed upstream in
+ * Pagefind/pagefind#1272; switch back to `writeFiles()` once a release ships
+ * that fix.
+ *
  * Returns the number of pages indexed.
  */
 export const buildSearchIndex = async (outDir: string): Promise<number> => {
-  const pagefind = await import("pagefind");
-
-  const { index } = await pagefind.createIndex({});
+  const { index } = await createIndex({});
   if (!index) {
     throw new Error("Failed to create Pagefind index.");
   }
 
   // These awaits are strictly ordered, not independent: the directory must be
-  // indexed before its files are written, and the index closed only after.
+  // indexed before its files are read, and the index closed only after.
   // oxlint-disable-next-line react-doctor/async-parallel
   const result = await index.addDirectory({ path: outDir });
-  await index.writeFiles({ outputPath: join(outDir, "pagefind") });
-  await pagefind.close();
+  const { files } = await index.getFiles();
+  await close();
+
+  const searchDir = join(outDir, "pagefind");
+  const directories = new Set(
+    files.map((file) => dirname(join(searchDir, file.path)))
+  );
+  await Promise.all(
+    [...directories].map((directory) => mkdir(directory, { recursive: true }))
+  );
+  await Promise.all(
+    files.map((file) => writeFile(join(searchDir, file.path), file.content))
+  );
 
   return result.page_count;
 };

package/src/search/documents.ts

@@ -433,6 +433,12 @@ export const buildSearchDocuments = async (
     if (!options?.includeWhenDisabled) {
       return route.indexable;
     }
+    // A fallback route renders the fallback locale's page at another locale's
+    // URL, so indexing it would only repeat that page as a second hit — the
+    // reason site search leaves it out too.
+    if (route.fallback) {
+      return false;
+    }
     const page = pageById.get(route.id);
     return page ? contentIndexable(page, project.config) : false;
   });

package/src/search/sync/algolia.ts

@@ -1,14 +1,16 @@
+import type * as AlgoliaSdk from "algoliasearch";
+
+import { nodeRequire } from "../../core/node-require.ts";
+import type { AlgoliaOptions } from "../adapters/algolia.ts";
 import type { SearchRecord } from "../documents.ts";
 
-export interface AlgoliaSyncConfig {
-  appId: string;
-  indexName: string;
-}
+/** The adapter options the sync reads (the public `apiKey` is never used). */
+export type AlgoliaSyncConfig = Pick<AlgoliaOptions, "appId" | "indexName">;
 
 /**
  * Upload the search records to Algolia. Uses the admin key from
- * `ALGOLIA_ADMIN_API_KEY` (never the config, which holds only the public,
- * search-only key). Throws on a missing key/config so the caller can warn.
+ * `ALGOLIA_ADMIN_API_KEY` (never the adapter options, which hold only the
+ * public, search-only key). Throws on a missing key so the caller can warn.
  *
  * Uses `replaceAllObjects`, which atomically replaces the index contents, so
  * pages deleted or renamed since the last sync don't linger as stale search
@@ -16,16 +18,15 @@ export interface AlgoliaSyncConfig {
  */
 export const syncAlgolia = async (
   records: SearchRecord[],
-  config: AlgoliaSyncConfig | undefined
+  config: AlgoliaSyncConfig
 ): Promise<void> => {
-  if (!config) {
-    throw new Error("search.algolia config is missing.");
-  }
   const adminKey = process.env.ALGOLIA_ADMIN_API_KEY;
   if (!adminKey) {
     throw new Error("ALGOLIA_ADMIN_API_KEY is not set.");
   }
-  const { algoliasearch } = await import("algoliasearch");
+  // `require`, not `import()`: this runs in `astro:build:done` (see
+  // `core/node-require.ts`).
+  const { algoliasearch }: typeof AlgoliaSdk = nodeRequire("algoliasearch");
   const client = algoliasearch(config.appId, adminKey);
   await client.replaceAllObjects({
     indexName: config.indexName,

package/src/search/sync/index.ts

@@ -1,6 +1,7 @@
 import type { BlumeProject } from "../../core/project-graph.ts";
+import type { ResolvedSearchAdapter } from "../adapters/registry.ts";
 import { buildSearchDocuments, toSearchRecords } from "../documents.ts";
-import { searchProviderMeta } from "../providers.ts";
+import type { SearchRecord } from "../documents.ts";
 import { syncAlgolia } from "./algolia.ts";
 import { syncOramaCloud } from "./orama-cloud.ts";
 import { syncTypesense } from "./typesense.ts";
@@ -13,37 +14,51 @@ export interface SyncReporter {
 }
 
 /**
- * After a build, upload the per-page records to the configured hosted provider.
- * Reads secret admin keys from the environment; if a key (or config) is
+ * The sync a hosted adapter runs after a build, closed over its options, or
+ * `null` for adapters with no in-process sync (static and Pagefind indexes are
+ * built locally; Mixedbread syncs out-of-band via the `mxbai` CLI).
+ */
+const searchSync = (
+  provider: ResolvedSearchAdapter
+): ((records: SearchRecord[]) => Promise<void>) | null => {
+  switch (provider.kind) {
+    case "algolia": {
+      return (records) => syncAlgolia(records, provider.options);
+    }
+    case "orama-cloud": {
+      return (records) => syncOramaCloud(records, provider.options);
+    }
+    case "typesense": {
+      return (records) => syncTypesense(records, provider.options);
+    }
+    default: {
+      return null;
+    }
+  }
+};
+
+/**
+ * After a build, upload the per-page records to the configured hosted adapter.
+ * Reads secret admin keys from the environment; if a key (or option) is
  * missing the sync is skipped with a warning rather than failing the build —
- * CI may sync in a separate step. Providers without an in-process sync
- * (Mixedbread, which uses the `mxbai` CLI) are no-ops here.
+ * CI may sync in a separate step.
  */
 export const syncSearchProvider = async (
   project: BlumeProject,
   reporter: SyncReporter
 ): Promise<void> => {
-  const { search } = project.config;
-  if (!searchProviderMeta(search.provider).syncs) {
+  const { provider } = project.config.search;
+  const sync = searchSync(provider);
+  if (!sync) {
     return;
   }
 
   const records = toSearchRecords(await buildSearchDocuments(project));
-  reporter.start(`Syncing ${records.length} record(s) to ${search.provider}`);
+  reporter.start(`Syncing ${records.length} record(s) to ${provider.kind}`);
 
   try {
-    // The `syncs` guard above admits only these three hosted providers, so an
-    // if-chain stays exhaustive without a dead `default` branch.
-    if (search.provider === "algolia") {
-      await syncAlgolia(records, search.algolia);
-    } else if (search.provider === "orama-cloud") {
-      await syncOramaCloud(records, search.oramaCloud);
-    } else if (search.provider === "typesense") {
-      await syncTypesense(records, search.typesense);
-    }
-    reporter.success(
-      `Synced ${records.length} record(s) to ${search.provider}`
-    );
+    await sync(records);
+    reporter.success(`Synced ${records.length} record(s) to ${provider.kind}`);
   } catch (error) {
     // SAFETY: the three sync clients surface network/auth failures as Error
     // instances; the message is read only to annotate the skip warning.

package/src/search/sync/orama-cloud.ts

@@ -1,8 +1,11 @@
+import type * as OramaCloudSdk from "@oramacloud/client";
+
+import { nodeRequire } from "../../core/node-require.ts";
+import type { OramaCloudOptions } from "../adapters/orama-cloud.ts";
 import type { SearchRecord } from "../documents.ts";
 
-export interface OramaCloudSyncConfig {
-  indexId?: string;
-}
+/** The adapter options the sync reads (the public credentials are never used). */
+export type OramaCloudSyncConfig = Pick<OramaCloudOptions, "indexId">;
 
 /**
  * Push the search records to an Orama Cloud index via `CloudManager`, using the
@@ -11,19 +14,19 @@ export interface OramaCloudSyncConfig {
  */
 export const syncOramaCloud = async (
   records: SearchRecord[],
-  config: OramaCloudSyncConfig | undefined
+  config: OramaCloudSyncConfig
 ): Promise<void> => {
-  if (!config) {
-    throw new Error("search.oramaCloud config is missing.");
-  }
   if (!config.indexId) {
-    throw new Error("search.oramaCloud.indexId is required to sync.");
+    throw new Error("oramaCloud({ indexId }) is required to sync.");
   }
   const privateKey = process.env.ORAMA_PRIVATE_API_KEY;
   if (!privateKey) {
     throw new Error("ORAMA_PRIVATE_API_KEY is not set.");
   }
-  const { CloudManager } = await import("@oramacloud/client");
+  // `require`, not `import()`: this runs in `astro:build:done` (see
+  // `core/node-require.ts`).
+  const { CloudManager }: typeof OramaCloudSdk =
+    nodeRequire("@oramacloud/client");
   const manager = new CloudManager({ api_key: privateKey });
   const index = manager.index(config.indexId);
   await index.snapshot(

package/src/search/sync/typesense.ts

@@ -1,16 +1,19 @@
+import type * as TypesenseSdk from "typesense";
+
+import { nodeRequire } from "../../core/node-require.ts";
+import type { TypesenseOptions } from "../adapters/typesense.ts";
 import type { SearchRecord } from "../documents.ts";
 
-export interface TypesenseSyncConfig {
-  collection: string;
-  host: string;
-  port?: number;
-  protocol?: string;
-}
+/** The adapter options the sync reads (the public `apiKey` is never used). */
+export type TypesenseSyncConfig = Pick<
+  TypesenseOptions,
+  "collection" | "host" | "port" | "protocol"
+>;
 
 /**
  * Import the search records into a Typesense collection. Uses the admin key
- * from `TYPESENSE_ADMIN_API_KEY`. Throws on a missing key/config so the caller
- * can warn.
+ * from `TYPESENSE_ADMIN_API_KEY`. Throws on a missing key so the caller can
+ * warn.
  *
  * The collection is dropped and recreated on each sync so that pages deleted or
  * renamed since the last sync don't linger as stale search hits that 404 when
@@ -18,16 +21,15 @@ export interface TypesenseSyncConfig {
  */
 export const syncTypesense = async (
   records: SearchRecord[],
-  config: TypesenseSyncConfig | undefined
+  config: TypesenseSyncConfig
 ): Promise<void> => {
-  if (!config) {
-    throw new Error("search.typesense config is missing.");
-  }
   const adminKey = process.env.TYPESENSE_ADMIN_API_KEY;
   if (!adminKey) {
     throw new Error("TYPESENSE_ADMIN_API_KEY is not set.");
   }
-  const { Client } = await import("typesense");
+  // `require`, not `import()`: this runs in `astro:build:done` (see
+  // `core/node-require.ts`).
+  const { Client }: typeof TypesenseSdk = nodeRequire("typesense");
   const client = new Client({
     apiKey: adminKey,
     nodes: [