blume 0.0.0 → 0.1.1

package/src/search/orama-index.ts

@@ -0,0 +1,66 @@
+import { create, insertMultiple, search } from "@orama/orama";
+import type { AnyOrama } from "@orama/orama";
+
+/**
+ * The minimal document shape both the client-side search dialog and the
+ * server-side MCP `search_docs` tool index. Mirrors the `blume-search.json`
+ * entries built by `buildSearchDocuments`.
+ */
+export interface OramaDoc {
+  content: string;
+  description: string;
+  route: string;
+  title: string;
+  /** Locale code; indexed as an enum so queries can filter to one language. */
+  locale?: string;
+  /** Carried through for the search dialog's breadcrumb + filter pills. Stored
+   * but not indexed, so they ride along on the returned document untouched. */
+  breadcrumb?: string[];
+  section?: string;
+}
+
+const SCHEMA = {
+  content: "string",
+  description: "string",
+  // Enum (not full-text "string") so `where` does an exact-match filter.
+  locale: "enum",
+  route: "string",
+  title: "string",
+} as const;
+
+/** Title and description outrank body text, matching the search dialog. */
+const BOOST = { description: 2, title: 3 };
+
+/**
+ * Build an in-memory Orama full-text index from search documents. Shared by the
+ * Orama client loader (browser) and the MCP server (Node), so ranking is
+ * identical wherever docs are queried.
+ */
+export const buildOramaIndex = async (
+  documents: OramaDoc[]
+): Promise<AnyOrama> => {
+  const db = create({ schema: SCHEMA });
+  await insertMultiple(db, documents);
+  return db;
+};
+
+/**
+ * Query the index, returning the matching documents (highest-ranked first).
+ * When `locale` is given, results are filtered to that language via an exact
+ * `where` match on the `locale` enum.
+ */
+export const queryOramaIndex = async (
+  db: AnyOrama,
+  term: string,
+  limit: number,
+  locale?: string
+): Promise<OramaDoc[]> => {
+  const found = await search(db, {
+    boost: BOOST,
+    limit,
+    properties: ["title", "description", "content"],
+    term,
+    ...(locale ? { where: { locale: { eq: locale } } } : {}),
+  });
+  return found.hits.map((hit) => hit.document as unknown as OramaDoc);
+};

package/src/search/providers.ts

@@ -0,0 +1,91 @@
+import type { SearchProvider } from "../core/schema.ts";
+
+/**
+ * How a search provider integrates with the generated runtime.
+ *
+ * - `static` providers 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 Astro build.
+ * - `hosted` providers are queried directly from the browser against an external
+ *   service, with a build-time sync uploading the index — `algolia`,
+ *   `orama-cloud`, `typesense`.
+ * - `server` providers proxy queries through a generated `/api/search` endpoint
+ *   that holds a secret key, so they require server output — `mixedbread`.
+ */
+export type SearchProviderKind =
+  | "static"
+  | "pagefind"
+  | "hosted"
+  | "server"
+  | "none";
+
+export interface SearchProviderMeta {
+  kind: SearchProviderKind;
+  /** Extra packages the generated `.blume/package.json` must declare. */
+  runtimeDeps: string[];
+  /** Whether the provider needs `deployment.output: "server"`. */
+  requiresServer: boolean;
+  /** Whether a build-time sync uploads the index to an external service. */
+  syncs: boolean;
+}
+
+export const SEARCH_PROVIDERS: Record<SearchProvider, SearchProviderMeta> = {
+  algolia: {
+    kind: "hosted",
+    requiresServer: false,
+    runtimeDeps: ["algoliasearch"],
+    syncs: true,
+  },
+  flexsearch: {
+    kind: "static",
+    requiresServer: false,
+    runtimeDeps: ["flexsearch"],
+    syncs: false,
+  },
+  mixedbread: {
+    // Content is synced to the store out-of-band via the `mxbai` CLI, not by an
+    // in-process build step.
+    kind: "server",
+    requiresServer: true,
+    runtimeDeps: ["@mixedbread/sdk"],
+    syncs: false,
+  },
+  none: {
+    kind: "none",
+    requiresServer: false,
+    runtimeDeps: [],
+    syncs: false,
+  },
+  orama: {
+    kind: "static",
+    requiresServer: false,
+    runtimeDeps: ["@orama/orama"],
+    syncs: false,
+  },
+  "orama-cloud": {
+    kind: "hosted",
+    requiresServer: false,
+    runtimeDeps: ["@oramacloud/client"],
+    syncs: true,
+  },
+  pagefind: {
+    kind: "pagefind",
+    requiresServer: false,
+    runtimeDeps: [],
+    syncs: false,
+  },
+  typesense: {
+    kind: "hosted",
+    requiresServer: false,
+    runtimeDeps: ["typesense"],
+    syncs: true,
+  },
+};
+
+export const searchProviderMeta = (
+  provider: SearchProvider
+): SearchProviderMeta => SEARCH_PROVIDERS[provider];
+
+/** Whether a provider ships a client-loaded `blume-search.json` index. */
+export const servesStaticIndex = (provider: SearchProvider): boolean =>
+  SEARCH_PROVIDERS[provider].kind === "static";

package/src/search/sync/algolia.ts

@@ -0,0 +1,30 @@
+import type { SearchRecord } from "../documents.ts";
+
+export interface AlgoliaSyncConfig {
+  appId: string;
+  indexName: string;
+}
+
+/**
+ * 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.
+ */
+export const syncAlgolia = async (
+  records: SearchRecord[],
+  config: AlgoliaSyncConfig | undefined
+): 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");
+  const client = algoliasearch(config.appId, adminKey);
+  await client.saveObjects({
+    indexName: config.indexName,
+    objects: records.map((record) => ({ ...record, objectID: record._id })),
+  });
+};

package/src/search/sync/index.ts

@@ -0,0 +1,50 @@
+import type { BlumeProject } from "../../core/project-graph.ts";
+import { buildSearchDocuments, toSearchRecords } from "../documents.ts";
+import { searchProviderMeta } from "../providers.ts";
+import { syncAlgolia } from "./algolia.ts";
+import { syncOramaCloud } from "./orama-cloud.ts";
+import { syncTypesense } from "./typesense.ts";
+
+/** Minimal logger surface the build command provides. */
+export interface SyncReporter {
+  start: (message: string) => void;
+  success: (message: string) => void;
+  warn: (message: string) => void;
+}
+
+/**
+ * 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
+ * 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.
+ */
+export const syncSearchProvider = async (
+  project: BlumeProject,
+  reporter: SyncReporter
+): Promise<void> => {
+  const { search } = project.config;
+  if (!searchProviderMeta(search.provider).syncs) {
+    return;
+  }
+
+  const records = toSearchRecords(await buildSearchDocuments(project));
+  reporter.start(`Syncing ${records.length} record(s) to ${search.provider}`);
+
+  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}`
+    );
+  } catch (error) {
+    reporter.warn(`Search sync skipped: ${(error as Error).message}`);
+  }
+};

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

@@ -0,0 +1,40 @@
+import type { SearchRecord } from "../documents.ts";
+
+export interface OramaCloudSyncConfig {
+  indexId?: string;
+}
+
+/**
+ * Push the search records to an Orama Cloud index via `CloudManager`, using the
+ * private key from `ORAMA_PRIVATE_API_KEY`. Snapshots the full record set, then
+ * deploys. Throws on a missing key/index so the caller can warn.
+ */
+export const syncOramaCloud = async (
+  records: SearchRecord[],
+  config: OramaCloudSyncConfig | undefined
+): 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.");
+  }
+  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");
+  const manager = new CloudManager({ api_key: privateKey });
+  const index = manager.index(config.indexId);
+  await index.snapshot(
+    records.map((record) => ({
+      content: record.content,
+      description: record.description,
+      id: record._id,
+      tag: record.tag,
+      title: record.title,
+      url: record.url,
+    }))
+  );
+  await index.deploy();
+};

package/src/search/sync/typesense.ts

@@ -0,0 +1,65 @@
+import type { SearchRecord } from "../documents.ts";
+
+export interface TypesenseSyncConfig {
+  collection: string;
+  host: string;
+  port?: number;
+  protocol?: string;
+}
+
+/**
+ * Import the search records into a Typesense collection, creating the
+ * collection on first run. Uses the admin key from `TYPESENSE_ADMIN_API_KEY`.
+ * Throws on a missing key/config so the caller can warn.
+ */
+export const syncTypesense = async (
+  records: SearchRecord[],
+  config: TypesenseSyncConfig | undefined
+): 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");
+  const client = new Client({
+    apiKey: adminKey,
+    nodes: [
+      {
+        host: config.host,
+        port: config.port ?? 443,
+        protocol: config.protocol ?? "https",
+      },
+    ],
+  });
+
+  try {
+    await client.collections(config.collection).retrieve();
+  } catch {
+    await client.collections().create({
+      fields: [
+        { name: "title", type: "string" },
+        { name: "description", optional: true, type: "string" },
+        { name: "content", type: "string" },
+        { name: "url", type: "string" },
+        { facet: true, name: "tag", optional: true, type: "string" },
+      ],
+      name: config.collection,
+    });
+  }
+
+  const documents = records.map((record) => ({
+    content: record.content,
+    description: record.description,
+    id: record._id,
+    tag: record.tag,
+    title: record.title,
+    url: record.url,
+  }));
+  await client
+    .collections(config.collection)
+    .documents()
+    .import(documents, { action: "upsert" });
+};

package/src/seo/jsonld.ts

@@ -0,0 +1,113 @@
+import type { Crumb } from "../components/layout/nav-utils.ts";
+
+/** Inputs for a page's JSON-LD, all known at render time in RootLayout. */
+export interface StructuredDataInput {
+  siteName: string;
+  /** Absolute site origin, or null when `deployment.site` is unset. */
+  siteUrl: string | null;
+  title: string;
+  description?: string;
+  /** Page route, e.g. `/blog/post`. */
+  route: string;
+  /** Content type — `blog` and `changelog` map to richer article types. */
+  pageType?: string;
+  /** Publish date (string or YAML Date); emitted as ISO `datePublished`. */
+  published?: string | Date | null;
+  /** Last-modified date; emitted as ISO `dateModified`. */
+  modified?: string | Date | null;
+  /** BCP-47 language tag for `inLanguage`; defaults to `en`. */
+  locale?: string;
+  breadcrumbs: Crumb[];
+}
+
+/** schema.org `@type` for each content type; defaults to TechArticle. */
+const ARTICLE_TYPES: Record<string, string> = {
+  blog: "BlogPosting",
+  changelog: "TechArticle",
+};
+
+const trimSlash = (value: string): string => value.replace(/\/$/u, "");
+
+const absolute = (base: string | null, path: string): string =>
+  base ? `${base}${path}` : path;
+
+const toIso = (value: string | Date | null | undefined): string | undefined => {
+  if (!value) {
+    return;
+  }
+  const date = new Date(value);
+  return Number.isNaN(date.getTime()) ? undefined : date.toISOString();
+};
+
+/**
+ * Build a schema.org JSON-LD `@graph` for a page: site identity, the page as an
+ * article, and its breadcrumb trail. Returns null when there is nothing useful
+ * to emit (e.g. the homepage without a configured site). URLs are absolute when
+ * `siteUrl` is set, otherwise route-relative.
+ */
+export const buildStructuredData = (
+  input: StructuredDataInput
+): Record<string, unknown> | null => {
+  const base = input.siteUrl ? trimSlash(input.siteUrl) : null;
+  const pageUrl = absolute(base, input.route);
+  const graph: Record<string, unknown>[] = [];
+
+  if (base) {
+    graph.push({
+      "@id": `${base}#website`,
+      "@type": "WebSite",
+      name: input.siteName,
+      url: base,
+    });
+  }
+
+  // The homepage is fully described by the WebSite node; deeper pages get an
+  // article node plus a breadcrumb trail.
+  if (input.route !== "/") {
+    const node: Record<string, unknown> = {
+      "@id": `${pageUrl}#page`,
+      "@type": ARTICLE_TYPES[input.pageType ?? ""] ?? "TechArticle",
+      headline: input.title,
+      inLanguage: input.locale || "en",
+      name: input.title,
+      url: pageUrl,
+    };
+    if (input.description) {
+      node.description = input.description;
+    }
+    const published = toIso(input.published);
+    if (published) {
+      node.datePublished = published;
+    }
+    const modified = toIso(input.modified);
+    if (modified) {
+      node.dateModified = modified;
+    }
+    if (base) {
+      node.isPartOf = { "@id": `${base}#website` };
+    }
+    graph.push(node);
+
+    if (input.breadcrumbs.length > 1) {
+      graph.push({
+        "@type": "BreadcrumbList",
+        itemListElement: input.breadcrumbs.map((crumb, index) => {
+          const item: Record<string, unknown> = {
+            "@type": "ListItem",
+            name: crumb.label,
+            position: index + 1,
+          };
+          if (crumb.route) {
+            item.item = absolute(base, crumb.route);
+          }
+          return item;
+        }),
+      });
+    }
+  }
+
+  if (graph.length === 0) {
+    return null;
+  }
+  return { "@context": "https://schema.org", "@graph": graph };
+};