blume 2.0.3 → 2.1.1

package/src/search/sync/index.ts

@@ -1,3 +1,4 @@
+import { BlumeError } from "../../core/diagnostics.ts";
 import type { BlumeProject } from "../../core/project-graph.ts";
 import type { ResolvedSearchAdapter } from "../adapters/registry.ts";
 import { buildSearchDocuments, toSearchRecords } from "../documents.ts";
@@ -13,23 +14,49 @@ export interface SyncReporter {
   warn: (message: string) => void;
 }
 
+/** A hosted adapter's build-time sync. */
+interface HostedSync {
+  /** The env var holding the admin key the sync reads. */
+  key: string;
+  /**
+   * Whether the sync is set up to run: its admin key is set, and for Orama
+   * Cloud, the `indexId` that turns the sync on.
+   */
+  ready: boolean;
+  /** The upload, closed over the adapter's options. */
+  run: (records: SearchRecord[]) => Promise<void>;
+}
+
 /**
- * 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).
+ * The sync a hosted adapter runs after a build, 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 => {
+const searchSync = (provider: ResolvedSearchAdapter): HostedSync | null => {
   switch (provider.kind) {
     case "algolia": {
-      return (records) => syncAlgolia(records, provider.options);
+      const key = "ALGOLIA_ADMIN_API_KEY";
+      return {
+        key,
+        ready: Boolean(process.env[key]),
+        run: (records) => syncAlgolia(records, provider.options),
+      };
     }
     case "orama-cloud": {
-      return (records) => syncOramaCloud(records, provider.options);
+      const key = "ORAMA_PRIVATE_API_KEY";
+      return {
+        key,
+        ready: Boolean(process.env[key] && provider.options.indexId),
+        run: (records) => syncOramaCloud(records, provider.options),
+      };
     }
     case "typesense": {
-      return (records) => syncTypesense(records, provider.options);
+      const key = "TYPESENSE_ADMIN_API_KEY";
+      return {
+        key,
+        ready: Boolean(process.env[key]),
+        run: (records) => syncTypesense(records, provider.options),
+      };
     }
     default: {
       return null;
@@ -41,7 +68,9 @@ const searchSync = (
  * 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.
+ * a local build has no secrets, and CI may sync in a separate step. Once the
+ * sync is set up, a failure fails the build (`BLUME_SEARCH_SYNC_FAILED`):
+ * the site would otherwise deploy against an index this build didn't update.
  */
 export const syncSearchProvider = async (
   project: BlumeProject,
@@ -57,11 +86,21 @@ export const syncSearchProvider = async (
   reporter.start(`Syncing ${records.length} record(s) to ${provider.kind}`);
 
   try {
-    await sync(records);
+    await sync.run(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.
-    reporter.warn(`Search sync skipped: ${(error as Error).message}`);
+    // instances; the message is read only to annotate the warning or error.
+    const { message } = error as Error;
+    if (!sync.ready) {
+      reporter.warn(`Search sync skipped: ${message}`);
+      return;
+    }
+    throw new BlumeError({
+      code: "BLUME_SEARCH_SYNC_FAILED",
+      message: `Search sync to ${provider.kind} failed: ${message}`,
+      severity: "error",
+      suggestion: `Check ${sync.key} and the adapter's options, or unset ${sync.key} to build without syncing.`,
+    });
   }
 };

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

@@ -31,9 +31,12 @@ export const syncOramaCloud = async (
   const index = manager.index(config.indexId);
   await index.snapshot(
     records.map((record) => ({
+      // The dialog multiplies each hit's score by it (search.boost).
+      boost: record.boost,
       content: record.content,
       description: record.description,
       id: record._id,
+      keywords: record.keywords ?? [],
       // Carried so an i18n site can filter hosted results per language.
       locale: record.locale,
       tag: record.tag,

package/src/search/sync/typesense.ts

@@ -7,17 +7,44 @@ import type { SearchRecord } from "../documents.ts";
 /** The adapter options the sync reads (the public `apiKey` is never used). */
 export type TypesenseSyncConfig = Pick<
   TypesenseOptions,
-  "collection" | "host" | "port" | "protocol"
+  "collection" | "host" | "locale" | "port" | "protocol"
 >;
 
+type TypesenseClient = InstanceType<typeof TypesenseSdk.Client>;
+
+/**
+ * The collection an alias points at, or `undefined` when there is no such
+ * alias. Only a 404 means that: any other failure (a key that can't read
+ * aliases, an outage) throws before the sync has touched anything.
+ */
+const aliasTarget = async (
+  client: TypesenseClient,
+  alias: string,
+  errors: typeof TypesenseSdk.Errors
+): Promise<string | undefined> => {
+  try {
+    const { collection_name: target } = await client.aliases(alias).retrieve();
+    return target;
+  } catch (error) {
+    if (error instanceof errors.ObjectNotFound) {
+      return undefined;
+    }
+    throw error;
+  }
+};
+
 /**
- * Import the search records into a Typesense collection. Uses the admin key
- * from `TYPESENSE_ADMIN_API_KEY`. Throws on a missing key so the caller can
- * warn.
+ * Import the search records into Typesense. Uses the admin key 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
- * clicked (an upsert alone never removes them).
+ * `collection` names an alias. Each sync imports every record into a new
+ * collection (`<collection>_<timestamp>`), points the alias at it, then drops
+ * the collection it replaced: searches keep reading the previous collection
+ * until the new one is complete, pages deleted or renamed since the last sync
+ * don't linger as stale hits that 404 when clicked, and a sync that fails
+ * leaves the previous collection serving. A collection named `collection`
+ * itself, from a sync before the alias existed, is dropped just before the
+ * alias takes its name, since Typesense won't let the two share one.
  */
 export const syncTypesense = async (
   records: SearchRecord[],
@@ -29,7 +56,7 @@ export const syncTypesense = async (
   }
   // `require`, not `import()`: this runs in `astro:build:done` (see
   // `core/node-require.ts`).
-  const { Client }: typeof TypesenseSdk = nodeRequire("typesense");
+  const { Client, Errors }: typeof TypesenseSdk = nodeRequire("typesense");
   const client = new Client({
     apiKey: adminKey,
     nodes: [
@@ -41,43 +68,66 @@ export const syncTypesense = async (
     ],
   });
 
-  const collection = client.collections(config.collection);
-  let exists = true;
-  try {
-    await collection.retrieve();
-  } catch {
-    exists = false;
-  }
-  if (exists) {
-    await collection.delete();
-  }
+  const alias = config.collection;
+  const previous = await aliasTarget(client, alias, Errors);
+  const name = `${alias}_${Date.now()}`;
+  // The searched text fields, tokenized for `locale` when the site sets one.
+  const text = config.locale ? { locale: config.locale } : {};
   await client.collections().create({
     fields: [
-      { name: "title", type: "string" },
-      { name: "description", optional: true, type: "string" },
-      { name: "content", type: "string" },
+      { name: "title", type: "string", ...text },
+      { name: "description", optional: true, type: "string", ...text },
+      { name: "content", type: "string", ...text },
       { name: "url", type: "string" },
+      { name: "keywords", optional: true, type: "string[]", ...text },
+      // The dialog sorts close matches by it (search.boost, 1 by default).
+      { name: "boost", type: "float" },
       { facet: true, name: "tag", optional: true, type: "string" },
       // Carried as facets so hosted results can filter per language and per
       // docs version (the SearchRecord contract; current docs = "current").
       { facet: true, name: "locale", optional: true, type: "string" },
       { facet: true, name: "version", optional: true, type: "string" },
     ],
-    name: config.collection,
+    name,
   });
 
   const documents = records.map((record) => ({
+    boost: record.boost,
     content: record.content,
     description: record.description,
     id: record._id,
+    keywords: record.keywords ?? [],
     locale: record.locale,
     tag: record.tag,
     title: record.title,
     url: record.url,
     version: record.version,
   }));
-  await client
-    .collections(config.collection)
-    .documents()
-    .import(documents, { action: "upsert" });
+  try {
+    await client
+      .collections(name)
+      .documents()
+      .import(documents, { action: "upsert" });
+  } catch (error) {
+    // Nothing reads the new collection yet: drop it, and the alias keeps
+    // serving the last complete sync.
+    await client.collections(name).delete();
+    throw error;
+  }
+
+  if (previous === undefined) {
+    let legacy = true;
+    try {
+      await client.collections(alias).retrieve();
+    } catch {
+      legacy = false;
+    }
+    if (legacy) {
+      await client.collections(alias).delete();
+    }
+  }
+  await client.aliases().upsert(alias, { collection_name: name });
+  if (previous !== undefined) {
+    await client.collections(previous).delete();
+  }
 };

package/src/seo/metatags.ts

@@ -0,0 +1,67 @@
+/**
+ * Site-wide meta tags (`seo.metatags`): tags written into every page's head,
+ * for what Blume has no setting of its own for, such as site-verification
+ * tokens, `theme-color`, or an app banner. The tags Blume writes itself are
+ * refused, each pointing at the setting that controls it, so a page never
+ * carries two values for one tag.
+ */
+
+const IMAGE =
+  "`seo.og` for the generated cards, or `seo.image` in a page's frontmatter";
+const TITLE = "`title`, or `seo.title` in a page's frontmatter";
+const DESCRIPTION =
+  "`description` in a page's frontmatter or the config, or a page's `seo.description`";
+const FROM_PAGE = "Blume sets it from each page's type and dates";
+
+/** The tags Blume writes itself, by lowercase name, and what sets each. */
+const OWNED = new Map([
+  ["article:modified_time", FROM_PAGE],
+  ["article:published_time", FROM_PAGE],
+  ["description", DESCRIPTION],
+  ["og:description", DESCRIPTION],
+  ["og:site_name", "the config's `title`"],
+  ["og:title", TITLE],
+  ["og:type", FROM_PAGE],
+  ["og:url", "`deployment.site`, which sets each page's canonical URL"],
+  ["robots", "`seo.noindex` in a page's frontmatter"],
+  ["twitter:card", "Blume sets it from each page's image"],
+  ["twitter:creator", "`seo.x.creator` in the config or a page's frontmatter"],
+  ["twitter:description", DESCRIPTION],
+  ["twitter:site", "`seo.x.handle`"],
+  ["twitter:title", TITLE],
+  ["viewport", "Blume sets it for every page"],
+]);
+
+/** `og:image` and `twitter:image`, and their sub-properties. */
+const IMAGE_TAG = /^(?:og|twitter):image(?::|$)/u;
+
+/**
+ * What sets a tag Blume writes itself, or `undefined` for a tag the site can
+ * add.
+ */
+export const ownedMetatag = (name: string): string | undefined => {
+  const key = name.trim().toLowerCase();
+  return IMAGE_TAG.test(key) ? IMAGE : OWNED.get(key);
+};
+
+/**
+ * The Open Graph families, which the protocol names with `property`; every
+ * other tag takes `name`.
+ */
+const PROPERTY_TAG =
+  /^(?:og|fb|article|book|profile|music|video|al|product):/iu;
+
+/** One site-wide tag, as its `<meta>` element's attributes. */
+export interface MetatagAttributes {
+  content: string;
+  name?: string;
+  property?: string;
+}
+
+/** The site's `seo.metatags` as `<meta>` attributes, in the order written. */
+export const metatagAttributes = (
+  tags?: Readonly<Record<string, string>> | null
+): MetatagAttributes[] =>
+  Object.entries(tags ?? {}).map(([name, content]) =>
+    PROPERTY_TAG.test(name) ? { content, property: name } : { content, name }
+  );

package/src/sources/contentful.ts

@@ -21,10 +21,20 @@ export interface ContentfulOptions extends SharedSourceOptions {
    * / `sys.updatedAt`.
    */
   fields?: SourceFieldMap;
+  /**
+   * Delivery API host name. Defaults to `cdn.contentful.com`; a space with
+   * EU data residency reads from `cdn.eu.contentful.com`.
+   */
+  host?: string;
   /** Locale code to fetch; omit for the space's default locale. */
   locale?: string;
   /** Extra query parameters for the entries request (`"fields.section": "sdk"`). */
   params?: Record<string, string>;
+  /**
+   * Preview API host name for `--preview`. Defaults to
+   * `preview.contentful.com` (`preview.eu.contentful.com` in the EU).
+   */
+  previewHost?: string;
   /** Space id. */
   space: string;
 }
@@ -33,8 +43,10 @@ export const contentfulOptionsSchema = sharedSourceOptionsSchema.extend({
   contentType: z.string(),
   environment: z.string().optional(),
   fields: sourceFieldMapSchema.optional(),
+  host: z.string().optional(),
   locale: z.string().optional(),
   params: queryParamsSchema.optional(),
+  previewHost: z.string().optional(),
   space: z.string(),
 });
 

package/src/sources/github-releases.ts

@@ -7,7 +7,12 @@ import { sharedSourceOptionsSchema } from "./shared.ts";
 
 /** Options for {@link githubReleases}. */
 export interface GithubReleasesOptions extends SharedSourceOptions {
-  /** Include draft releases (needs a token with repo write access). */
+  /**
+   * The GitHub REST API base URL. Defaults to `https://api.github.com`; a
+   * GitHub Enterprise Server's is `https://<host>/api/v3`.
+   */
+  baseUrl?: string;
+  /** Include draft releases, tagged `Draft` (needs a token with repo write access). */
   drafts?: boolean;
   /** Cap the number of releases materialized, newest-first. Defaults to 100. */
   limit?: number;
@@ -20,6 +25,7 @@ export interface GithubReleasesOptions extends SharedSourceOptions {
 }
 
 export const githubReleasesOptionsSchema = sharedSourceOptionsSchema.extend({
+  baseUrl: z.string().optional(),
   drafts: z.boolean().optional(),
   limit: z.number().positive().optional(),
   owner: z.string(),

package/src/sources/shared.ts

@@ -33,6 +33,8 @@ export interface SourceFieldMap {
   description?: string;
   /** Field holding the last-modified date. */
   lastModified?: string;
+  /** Field holding the sidebar order (a number). No default: unset, none is read. */
+  order?: string;
   /** Field holding the page slug. */
   slug?: string;
   /** Field holding the page title. */
@@ -44,6 +46,7 @@ export const sourceFieldMapSchema = z.strictObject({
   body: z.string().optional(),
   description: z.string().optional(),
   lastModified: z.string().optional(),
+  order: z.string().optional(),
   slug: z.string().optional(),
   title: z.string().optional(),
 });

package/src/theme/chrome-icons.ts

@@ -19,6 +19,7 @@ interface ChromeIconSet {
 
 export const chromeIcons: ChromeIconSet = {
   check: '<path d="M20 6 9 17l-5-5"/>',
+  "chevron-down": '<path d="m6 9 6 6 6-6"/>',
   copy: '<rect width="14" height="14" x="8" y="8" rx="2" ry="2"/><path d="M4 16c-1.1 0-2-.9-2-2V4c0-1.1.9-2 2-2h10c1.1 0 2 .9 2 2"/>',
   file: '<path d="M15 2H6a2 2 0 0 0-2 2v16a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V7Z"/><path d="M14 2v4a2 2 0 0 0 2 2h4"/>',
   search: '<circle cx="11" cy="11" r="8"/><path d="m21 21-4.3-4.3"/>',