blume 1.7.3 → 2.0.1

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: [

package/src/sources/contentful.ts

@@ -0,0 +1,63 @@
+import { z } from "zod";
+
+import type { AdapterDescriptor } from "../core/adapter.ts";
+import { adapterDescriptorSchema } from "../core/adapter.ts";
+import type { SharedSourceOptions, SourceFieldMap } from "./shared.ts";
+import {
+  queryParamsSchema,
+  sharedSourceOptionsSchema,
+  sourceFieldMapSchema,
+} from "./shared.ts";
+
+/** Options for {@link contentful}. */
+export interface ContentfulOptions extends SharedSourceOptions {
+  /** The content type id whose entries become pages. */
+  contentType: string;
+  /** Environment id. Defaults to `master`. */
+  environment?: string;
+  /**
+   * Field ids mapping an entry onto Blume meta + body; `sys.<key>` reaches
+   * the entry's `sys`. Defaults to `title` / `description` / `slug` / `body`
+   * / `sys.updatedAt`.
+   */
+  fields?: SourceFieldMap;
+  /** 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>;
+  /** Space id. */
+  space: string;
+}
+
+export const contentfulOptionsSchema = sharedSourceOptionsSchema.extend({
+  contentType: z.string(),
+  environment: z.string().optional(),
+  fields: sourceFieldMapSchema.optional(),
+  locale: z.string().optional(),
+  params: queryParamsSchema.optional(),
+  space: z.string(),
+});
+
+export type ContentfulAdapter = AdapterDescriptor<
+  "contentful",
+  ContentfulOptions
+>;
+
+export const contentfulAdapterSchema = adapterDescriptorSchema(
+  "contentful",
+  contentfulOptionsSchema
+);
+
+/**
+ * A Contentful content type read through the Delivery API; rich text bodies
+ * become Markdown. The Delivery token comes from `CONTENTFUL_ACCESS_TOKEN`,
+ * and `--preview` reads drafts through the Preview API with
+ * `CONTENTFUL_PREVIEW_TOKEN`. Nothing to install: the adapter speaks the
+ * REST API directly.
+ */
+export const contentful = (options: ContentfulOptions): ContentfulAdapter => ({
+  kind: "contentful",
+  options,
+  requiredSecrets: ["CONTENTFUL_ACCESS_TOKEN"],
+  runtimeDeps: [],
+});

package/src/sources/custom.ts

@@ -0,0 +1,38 @@
+import { z } from "zod";
+
+import type { AdapterDescriptor } from "../core/adapter.ts";
+import { adapterDescriptorSchema } from "../core/adapter.ts";
+import type { ContentSource } from "../core/sources/types.ts";
+
+/** A user-provided {@link ContentSource} instance, validated for `name` + `load`. */
+export const customOptionsSchema = z.custom<ContentSource>(
+  (value): value is ContentSource =>
+    typeof value === "object" &&
+    value !== null &&
+    "load" in value &&
+    typeof value.load === "function" &&
+    "name" in value &&
+    typeof value.name === "string",
+  { message: "custom() takes a ContentSource (an object with name + load)" }
+);
+
+export type CustomAdapter = AdapterDescriptor<"custom", ContentSource>;
+
+export const customAdapterSchema = adapterDescriptorSchema(
+  "custom",
+  customOptionsSchema
+);
+
+/**
+ * Any object implementing the {@link ContentSource} interface, passed straight
+ * through. This is the extension point for adapters with custom serializers or
+ * any other backend, without their SDKs touching core. Unlike the built-in
+ * adapters the descriptor carries a live instance, so it never travels through
+ * the generated project's data snapshot — the CLI consumes it at scan time.
+ */
+export const custom = (source: ContentSource): CustomAdapter => ({
+  kind: "custom",
+  options: source,
+  requiredSecrets: [],
+  runtimeDeps: [],
+});

package/src/sources/filesystem.ts

@@ -0,0 +1,51 @@
+import { z } from "zod";
+
+import type { AdapterDescriptor } from "../core/adapter.ts";
+import { adapterDescriptorSchema } from "../core/adapter.ts";
+import type { SharedSourceOptions } from "./shared.ts";
+import { DEFAULT_CONTENT_GLOB, sharedSourceOptionsSchema } from "./shared.ts";
+
+/** What `include` defaults to: every Markdown/MDX file under the root. */
+export const DEFAULT_CONTENT_INCLUDE = [DEFAULT_CONTENT_GLOB];
+/** What `exclude` defaults to: underscore- and dot-prefixed paths. */
+export const DEFAULT_CONTENT_EXCLUDE = ["**/_*", "**/.*"];
+
+/** Options for {@link filesystem}. */
+export interface FilesystemOptions extends SharedSourceOptions {
+  /** Glob patterns to ignore. Defaults to `["**\/_*", "**\/.*"]`. */
+  exclude?: string[];
+  /** Glob patterns to include. Defaults to `["**\/*.{md,mdx}"]`. */
+  include?: string[];
+  /** Directory to read from, relative to the project root. Defaults to `docs`. */
+  root?: string;
+}
+
+export const filesystemOptionsSchema = sharedSourceOptionsSchema.extend({
+  exclude: z.array(z.string()).default(DEFAULT_CONTENT_EXCLUDE),
+  include: z.array(z.string()).default(DEFAULT_CONTENT_INCLUDE),
+  root: z.string().default("docs"),
+});
+
+export type FilesystemAdapter = AdapterDescriptor<
+  "filesystem",
+  FilesystemOptions
+>;
+
+export const filesystemAdapterSchema = adapterDescriptorSchema(
+  "filesystem",
+  filesystemOptionsSchema
+);
+
+/**
+ * Local Markdown/MDX read from a directory. The zero-config default: with no
+ * `content.sources`, the top-level `content.root`/`include`/`exclude` desugar
+ * to exactly one of these.
+ */
+export const filesystem = (
+  options: FilesystemOptions = {}
+): FilesystemAdapter => ({
+  kind: "filesystem",
+  options,
+  requiredSecrets: [],
+  runtimeDeps: [],
+});

package/src/sources/github-releases.ts

@@ -0,0 +1,52 @@
+import { z } from "zod";
+
+import type { AdapterDescriptor } from "../core/adapter.ts";
+import { adapterDescriptorSchema } from "../core/adapter.ts";
+import type { SharedSourceOptions } from "./shared.ts";
+import { sharedSourceOptionsSchema } from "./shared.ts";
+
+/** Options for {@link githubReleases}. */
+export interface GithubReleasesOptions extends SharedSourceOptions {
+  /** Include draft releases (needs a token with repo write access). */
+  drafts?: boolean;
+  /** Cap the number of releases materialized, newest-first. Defaults to 100. */
+  limit?: number;
+  /** Repository owner (user or org). */
+  owner: string;
+  /** Include prereleases. */
+  prereleases?: boolean;
+  /** Repository name. */
+  repo: string;
+}
+
+export const githubReleasesOptionsSchema = sharedSourceOptionsSchema.extend({
+  drafts: z.boolean().optional(),
+  limit: z.number().positive().optional(),
+  owner: z.string(),
+  prereleases: z.boolean().optional(),
+  repo: z.string(),
+});
+
+export type GithubReleasesAdapter = AdapterDescriptor<
+  "github-releases",
+  GithubReleasesOptions
+>;
+
+export const githubReleasesAdapterSchema = adapterDescriptorSchema(
+  "github-releases",
+  githubReleasesOptionsSchema
+);
+
+/**
+ * A repo's GitHub Releases, materialized as `type: changelog` entries — release
+ * notes become the changelog with no files to maintain. A private repo reads a
+ * token from `GITHUB_TOKEN`; it is never inlined here.
+ */
+export const githubReleases = (
+  options: GithubReleasesOptions
+): GithubReleasesAdapter => ({
+  kind: "github-releases",
+  options,
+  requiredSecrets: ["GITHUB_TOKEN"],
+  runtimeDeps: [],
+});

package/src/sources/index.ts

@@ -0,0 +1,60 @@
+/**
+ * Content source adapters for `blume.config.ts`:
+ *
+ * ```ts
+ * import { defineConfig } from "blume";
+ * import { filesystem, githubReleases } from "blume/sources";
+ *
+ * export default defineConfig({
+ *   content: {
+ *     sources: [
+ *       filesystem({ root: "docs" }),
+ *       githubReleases({ owner: "acme", repo: "sdk", prefix: "changelog" }),
+ *     ],
+ *   },
+ * });
+ * ```
+ *
+ * Each factory returns a plain descriptor (see `core/adapter.ts`) that the
+ * schema validates and the CLI reads at scan time; every consumer — the
+ * generated `.blume/package.json`, the secrets check, `blume doctor` — reads
+ * the descriptor's `runtimeDeps` and `requiredSecrets` instead of switching
+ * on a source name. `custom()` is the exception that carries a live
+ * {@link ContentSource} instance rather than JSON.
+ */
+export type { AdapterDescriptor } from "../core/adapter.ts";
+export type {
+  ContentSource,
+  SourceContext,
+  SourceEntry,
+  SourceLoadResult,
+} from "../core/sources/types.ts";
+export { contentful } from "./contentful.ts";
+export type { ContentfulAdapter, ContentfulOptions } from "./contentful.ts";
+export { custom } from "./custom.ts";
+export type { CustomAdapter } from "./custom.ts";
+export { filesystem } from "./filesystem.ts";
+export type { FilesystemAdapter, FilesystemOptions } from "./filesystem.ts";
+export { githubReleases } from "./github-releases.ts";
+export type {
+  GithubReleasesAdapter,
+  GithubReleasesOptions,
+} from "./github-releases.ts";
+export { mdxRemote } from "./mdx-remote.ts";
+export type { MdxRemoteAdapter, MdxRemoteOptions } from "./mdx-remote.ts";
+export { notion } from "./notion.ts";
+export type { NotionAdapter, NotionOptions } from "./notion.ts";
+export { obsidian } from "./obsidian.ts";
+export type { ObsidianAdapter, ObsidianOptions } from "./obsidian.ts";
+export { payload } from "./payload.ts";
+export type { PayloadAdapter, PayloadOptions } from "./payload.ts";
+export type {
+  AnySourceAdapter,
+  ContentSourceAdapter,
+  SourceAdapterKind,
+} from "./registry.ts";
+export { sanity } from "./sanity.ts";
+export type { SanityAdapter, SanityOptions } from "./sanity.ts";
+export type { SharedSourceOptions, SourceFieldMap } from "./shared.ts";
+export { strapi } from "./strapi.ts";
+export type { StrapiAdapter, StrapiOptions } from "./strapi.ts";

package/src/sources/mdx-remote.ts

@@ -0,0 +1,76 @@
+import { z } from "zod";
+
+import type { AdapterDescriptor } from "../core/adapter.ts";
+import { adapterDescriptorSchema } from "../core/adapter.ts";
+import type { SharedSourceOptions } from "./shared.ts";
+import { DEFAULT_CONTENT_GLOB, sharedSourceOptionsSchema } from "./shared.ts";
+
+/** Options for {@link mdxRemote}. */
+export interface MdxRemoteOptions extends SharedSourceOptions {
+  /** Explicit list of source-relative file paths to fetch from `url`. */
+  files?: string[];
+  /** Enumerate a GitHub repo subtree via the git-trees API. */
+  github?: {
+    /** Repository owner (user or org). */
+    owner: string;
+    /** Subpath within the repo. Defaults to the repo root. */
+    path?: string;
+    /** Git ref (branch, tag, or SHA). Defaults to `main`. */
+    ref?: string;
+    /** Repository name. */
+    repo: string;
+  };
+  /** Glob patterns applied to enumerated refs. Defaults to `["**\/*.{md,mdx}"]`. */
+  include?: string[];
+  /** Raw base URL, e.g. `https://raw.githubusercontent.com/acme/sdk/main/docs`. */
+  url?: string;
+}
+
+export const mdxRemoteOptionsSchema = sharedSourceOptionsSchema.extend({
+  files: z.array(z.string()).optional(),
+  github: z
+    .strictObject({
+      owner: z.string(),
+      path: z.string().default(""),
+      ref: z.string().default("main"),
+      repo: z.string(),
+    })
+    .optional(),
+  include: z.array(z.string()).default([DEFAULT_CONTENT_GLOB]),
+  url: z.string().optional(),
+});
+
+export type MdxRemoteAdapter = AdapterDescriptor<
+  "mdx-remote",
+  MdxRemoteOptions
+>;
+
+export const mdxRemoteAdapterSchema = adapterDescriptorSchema(
+  "mdx-remote",
+  mdxRemoteOptionsSchema
+);
+
+// The hosts the source ever sends `GITHUB_TOKEN` to (the same set the fetch
+// in core/sources/mdx-remote.ts checks), so only an adapter reading from
+// GitHub declares the variable.
+const GITHUB_HOSTS = new Set(["api.github.com", "raw.githubusercontent.com"]);
+
+const readsFromGithub = (options: MdxRemoteOptions): boolean =>
+  options.github !== undefined ||
+  (options.url !== undefined &&
+    URL.canParse(options.url) &&
+    GITHUB_HOSTS.has(new URL(options.url).hostname));
+
+/**
+ * Remote Markdown/MDX fetched over HTTP. Enumerate files explicitly against a
+ * raw `url` base, or from a GitHub repo subtree via `github`. A private repo's
+ * token comes from `GITHUB_TOKEN` — never inline it here. The adapter declares
+ * the variable only when it reads from GitHub, since a `url` on any other host
+ * is never sent the token.
+ */
+export const mdxRemote = (options: MdxRemoteOptions): MdxRemoteAdapter => ({
+  kind: "mdx-remote",
+  options,
+  requiredSecrets: readsFromGithub(options) ? ["GITHUB_TOKEN"] : [],
+  runtimeDeps: [],
+});

package/src/sources/notion.ts

@@ -0,0 +1,63 @@
+import { z } from "zod";
+
+import type { AdapterDescriptor } from "../core/adapter.ts";
+import { adapterDescriptorSchema } from "../core/adapter.ts";
+import type { SharedSourceOptions } from "./shared.ts";
+import { sharedSourceOptionsSchema } from "./shared.ts";
+
+/** Options for {@link notion}. */
+export interface NotionOptions extends SharedSourceOptions {
+  /** Max concurrent Notion API requests; default 3 (Notion's per-integration pace). */
+  concurrency?: number;
+  /** Notion database id. */
+  database: string;
+  /** Notion property names mapped onto Blume meta. */
+  properties?: {
+    /** Property holding the page description. */
+    description?: string;
+    /** Property holding the sort order. */
+    order?: string;
+    /** Property holding the page slug. */
+    slug?: string;
+    /** Property holding the publish status. */
+    status?: string;
+    /** Property holding the page title. */
+    title?: string;
+  };
+  /** Status value treated as published; others map to `draft`. Defaults to `Published`. */
+  publishedValue?: string;
+}
+
+export const notionOptionsSchema = sharedSourceOptionsSchema.extend({
+  concurrency: z.number().positive().optional(),
+  database: z.string(),
+  properties: z
+    .strictObject({
+      description: z.string().optional(),
+      order: z.string().optional(),
+      slug: z.string().optional(),
+      status: z.string().optional(),
+      title: z.string().optional(),
+    })
+    .optional(),
+  publishedValue: z.string().optional(),
+});
+
+export type NotionAdapter = AdapterDescriptor<"notion", NotionOptions>;
+
+export const notionAdapterSchema = adapterDescriptorSchema(
+  "notion",
+  notionOptionsSchema
+);
+
+/**
+ * A Notion database; pages become entries, blocks become MDX. `@notionhq/client`
+ * is the declared runtime dependency, and the integration token comes from
+ * `NOTION_TOKEN`.
+ */
+export const notion = (options: NotionOptions): NotionAdapter => ({
+  kind: "notion",
+  options,
+  requiredSecrets: ["NOTION_TOKEN"],
+  runtimeDeps: ["@notionhq/client"],
+});

package/src/sources/obsidian.ts

@@ -0,0 +1,38 @@
+import { z } from "zod";
+
+import type { AdapterDescriptor } from "../core/adapter.ts";
+import { adapterDescriptorSchema } from "../core/adapter.ts";
+import type { SharedSourceOptions } from "./shared.ts";
+import { sharedSourceOptionsSchema } from "./shared.ts";
+
+/** Options for {@link obsidian}. */
+export interface ObsidianOptions extends SharedSourceOptions {
+  /** Vault folder names to skip at any depth, in addition to dot-folders. */
+  exclude?: string[];
+  /** Vault directory, absolute or relative to the project root. */
+  vault: string;
+}
+
+export const obsidianOptionsSchema = sharedSourceOptionsSchema.extend({
+  exclude: z.array(z.string()).optional(),
+  vault: z.string().min(1),
+});
+
+export type ObsidianAdapter = AdapterDescriptor<"obsidian", ObsidianOptions>;
+
+export const obsidianAdapterSchema = adapterDescriptorSchema(
+  "obsidian",
+  obsidianOptionsSchema
+);
+
+/**
+ * An Obsidian vault, read in place. Wikilinks become route links and
+ * `%%comments%%` are stripped at load time, so the vault stays the source of
+ * truth — no export step and no generated notes in the repo.
+ */
+export const obsidian = (options: ObsidianOptions): ObsidianAdapter => ({
+  kind: "obsidian",
+  options,
+  requiredSecrets: [],
+  runtimeDeps: [],
+});

package/src/sources/payload.ts

@@ -0,0 +1,60 @@
+import { z } from "zod";
+
+import type { AdapterDescriptor } from "../core/adapter.ts";
+import { adapterDescriptorSchema } from "../core/adapter.ts";
+import type { SharedSourceOptions, SourceFieldMap } from "./shared.ts";
+import {
+  queryParamsSchema,
+  sharedSourceOptionsSchema,
+  sourceFieldMapSchema,
+} from "./shared.ts";
+
+/** Options for {@link payload}. */
+export interface PayloadOptions extends SharedSourceOptions {
+  /**
+   * The auth-enabled collection the API key belongs to. Defaults to `users`;
+   * it names the scheme in the `Authorization` header (`users API-Key <key>`).
+   */
+  authCollection?: string;
+  /** The collection slug whose documents become pages. */
+  collection: string;
+  /** Relationship depth to populate. Defaults to `1`, enough for upload URLs. */
+  depth?: number;
+  /**
+   * Field paths mapping a document onto Blume meta + body. Defaults to
+   * `title` / `description` / `slug` / `content` / `updatedAt`.
+   */
+  fields?: SourceFieldMap;
+  /** Extra query parameters for the collection request (`"where[status][equals]": "live"`). */
+  params?: Record<string, string>;
+  /** The Payload app's origin (`https://cms.acme.dev`); its REST API is at `/api`. */
+  url: string;
+}
+
+export const payloadOptionsSchema = sharedSourceOptionsSchema.extend({
+  authCollection: z.string().optional(),
+  collection: z.string(),
+  depth: z.number().int().nonnegative().optional(),
+  fields: sourceFieldMapSchema.optional(),
+  params: queryParamsSchema.optional(),
+  url: z.string(),
+});
+
+export type PayloadAdapter = AdapterDescriptor<"payload", PayloadOptions>;
+
+export const payloadAdapterSchema = adapterDescriptorSchema(
+  "payload",
+  payloadOptionsSchema
+);
+
+/**
+ * A Payload collection read through its REST API; Lexical bodies become
+ * Markdown. The API key comes from `PAYLOAD_API_KEY`, and `--preview` reads
+ * drafts. Nothing to install: the adapter speaks the REST API directly.
+ */
+export const payload = (options: PayloadOptions): PayloadAdapter => ({
+  kind: "payload",
+  options,
+  requiredSecrets: ["PAYLOAD_API_KEY"],
+  runtimeDeps: [],
+});