blume 1.7.3 → 2.0.1

package/src/search/adapters/index.ts

@@ -0,0 +1,39 @@
+/**
+ * Search adapters for `blume.config.ts`:
+ *
+ * ```ts
+ * import { defineConfig } from "blume";
+ * import { algolia } from "blume/search";
+ *
+ * export default defineConfig({
+ *   search: algolia({ appId: "…", apiKey: "…", indexName: "docs" }),
+ * });
+ * ```
+ *
+ * Each factory returns a plain, JSON-serializable descriptor — never a live
+ * client — that the generated runtime inlines as a literal.
+ */
+export { algolia } from "./algolia.ts";
+export type { AlgoliaAdapter, AlgoliaOptions } from "./algolia.ts";
+export { flexsearch } from "./flexsearch.ts";
+export type { FlexsearchAdapter, FlexsearchOptions } from "./flexsearch.ts";
+export { mixedbread } from "./mixedbread.ts";
+export type { MixedbreadAdapter, MixedbreadOptions } from "./mixedbread.ts";
+export { orama } from "./orama.ts";
+export type { OramaAdapter, OramaOptions } from "./orama.ts";
+export { oramaCloud } from "./orama-cloud.ts";
+export type { OramaCloudAdapter, OramaCloudOptions } from "./orama-cloud.ts";
+export { pagefind } from "./pagefind.ts";
+export type { PagefindAdapter, PagefindOptions } from "./pagefind.ts";
+export type {
+  AnySearchAdapter,
+  ResolvedSearchAdapter,
+  SearchAdapterKind,
+} from "./registry.ts";
+export type {
+  KeylessSearchOptions,
+  SearchAdapter,
+  SearchAdapterMode,
+} from "./types.ts";
+export { typesense } from "./typesense.ts";
+export type { TypesenseAdapter, TypesenseOptions } from "./typesense.ts";

package/src/search/adapters/mixedbread.ts

@@ -0,0 +1,39 @@
+import { z } from "zod";
+
+import type { JsonValue } from "../../core/adapter.ts";
+import type { SearchAdapter } from "./types.ts";
+
+/**
+ * The Mixedbread store the generated `/api/search` endpoint queries, plus any
+ * other option, forwarded to the endpoint verbatim. JSON values only.
+ */
+export interface MixedbreadOptions {
+  storeId: string;
+  [option: string]: JsonValue;
+}
+
+export type MixedbreadAdapter = SearchAdapter<
+  "mixedbread",
+  "server",
+  MixedbreadOptions
+>;
+
+export const mixedbreadOptionsSchema = z
+  .object({
+    storeId: z.string(),
+  })
+  .catchall(z.json());
+
+/**
+ * Semantic search on Mixedbread. Queries go through a generated `/api/search`
+ * endpoint that holds `MIXEDBREAD_API_KEY`, so the adapter requires server
+ * output. Content is synced to the store out-of-band with the `mxbai` CLI,
+ * not by the build.
+ */
+export const mixedbread = (options: MixedbreadOptions): MixedbreadAdapter => ({
+  kind: "mixedbread",
+  mode: "server",
+  options,
+  requiredSecrets: ["MIXEDBREAD_API_KEY"],
+  runtimeDeps: ["@mixedbread/sdk"],
+});

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,5 +1,6 @@
 import { mkdir, writeFile } from "node:fs/promises";
 
+import { close, createIndex } from "pagefind";
 import { dirname, join } from "pathe";
 
 /**
@@ -8,6 +9,11 @@ import { dirname, 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
@@ -20,9 +26,7 @@ import { dirname, join } from "pathe";
  * 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.");
   }
@@ -32,7 +36,7 @@ export const buildSearchIndex = async (outDir: string): Promise<number> => {
   // oxlint-disable-next-line react-doctor/async-parallel
   const result = await index.addDirectory({ path: outDir });
   const { files } = await index.getFiles();
-  await pagefind.close();
+  await close();
 
   const searchDir = join(outDir, "pagefind");
   const directories = new Set(

package/src/search/documents.ts

@@ -149,7 +149,7 @@ const parseMarkdown = (
   format === "mdx" ? parseMdx(markdown) : markdownToMdast(markdown, MD_PARSE);
 
 // Fenced code is excluded from the plain index by default (ranking noise) —
-// the "markdown" extraction keeps it for Ask AI grounding. Code-heavy docs opt
+// the "markdown" extraction keeps it for assistant grounding. Code-heavy docs opt
 // in via `search.indexing.includeCodeBlocks`, which indexes the fence body and
 // its rendered title (```ts blume.config.ts) but never the fence markers,
 // language, or other meta keywords.
@@ -383,7 +383,7 @@ const pageBody = async (
  *
  * `content` selects the extraction: `"plain"` (default) strips Markdown to bare
  * searchable text; `"markdown"` keeps the body's Markdown — code blocks, lists,
- * headings — for Ask AI grounding, where fenced examples are often the answer
+ * headings — for assistant grounding, where fenced examples are often the answer
  * and stripping them makes the model unable to cite content the docs do contain.
  * The `"markdown"` body is agent-facing, so components are downleveled with the
  * same serializers the `.md` mirror, llms-full.txt and MCP `get_page` use: a
@@ -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/orama-index.ts

@@ -298,7 +298,7 @@ const segmentingTokenizer = (locale?: string): Tokenizer | undefined => {
 
 /**
  * Build an in-memory Orama full-text index from search documents. Shared by the
- * Orama client loader (browser), the MCP server, and Ask AI grounding (Node),
+ * Orama client loader (browser), the MCP server, and assistant grounding (Node),
  * so ranking is identical wherever docs are queried. `locale` — the site's
  * `i18n.defaultLocale` — swaps in a word-segmenting tokenizer for every
  * non-Latin script, all of which Orama's default tokenizer reduces to zero

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(