blume 1.7.2 → 2.0.0

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: [],
+});

package/src/sources/registry.ts

@@ -0,0 +1,182 @@
+import { z } from "zod";
+
+import { contentful, contentfulAdapterSchema } from "./contentful.ts";
+import type { ContentfulAdapter } from "./contentful.ts";
+import { custom, customAdapterSchema } from "./custom.ts";
+import type { CustomAdapter } from "./custom.ts";
+import { filesystem, filesystemAdapterSchema } from "./filesystem.ts";
+import type { FilesystemAdapter } from "./filesystem.ts";
+import {
+  githubReleases,
+  githubReleasesAdapterSchema,
+} from "./github-releases.ts";
+import type { GithubReleasesAdapter } from "./github-releases.ts";
+import { mdxRemote, mdxRemoteAdapterSchema } from "./mdx-remote.ts";
+import type { MdxRemoteAdapter } from "./mdx-remote.ts";
+import { notion, notionAdapterSchema } from "./notion.ts";
+import type { NotionAdapter } from "./notion.ts";
+import { obsidian, obsidianAdapterSchema } from "./obsidian.ts";
+import type { ObsidianAdapter } from "./obsidian.ts";
+import { payload, payloadAdapterSchema } from "./payload.ts";
+import type { PayloadAdapter } from "./payload.ts";
+import { sanity, sanityAdapterSchema } from "./sanity.ts";
+import type { SanityAdapter } from "./sanity.ts";
+import { strapi, strapiAdapterSchema } from "./strapi.ts";
+import type { StrapiAdapter } from "./strapi.ts";
+
+/** Every descriptor a `blume/sources` factory can return. */
+export type AnySourceAdapter =
+  | FilesystemAdapter
+  | MdxRemoteAdapter
+  | GithubReleasesAdapter
+  | SanityAdapter
+  | NotionAdapter
+  | ContentfulAdapter
+  | PayloadAdapter
+  | StrapiAdapter
+  | ObsidianAdapter
+  | CustomAdapter;
+
+/** Every adapter identity. */
+export type SourceAdapterKind = AnySourceAdapter["kind"];
+
+/** One variant per public adapter factory. */
+const adapterVariants = [
+  filesystemAdapterSchema,
+  mdxRemoteAdapterSchema,
+  githubReleasesAdapterSchema,
+  sanityAdapterSchema,
+  notionAdapterSchema,
+  contentfulAdapterSchema,
+  payloadAdapterSchema,
+  strapiAdapterSchema,
+  obsidianAdapterSchema,
+  customAdapterSchema,
+] as const;
+
+const sourceAdapterUnion = z.discriminatedUnion("kind", adapterVariants);
+
+/** What a public factory returns, as the config schema accepts it. */
+export type SourceAdapterInput = z.input<typeof sourceAdapterUnion>;
+
+/**
+ * A validated descriptor: the adapter's options with their defaults applied
+ * (a `filesystem()` entry always carries `root`/`include`/`exclude`), and the
+ * metadata lists re-derived from the factory so every consumer reads the
+ * `runtimeDeps` and `requiredSecrets` this version of Blume ships.
+ */
+export type ContentSourceAdapter = z.output<typeof sourceAdapterUnion>;
+
+/** The factory name the 1.x `type` discriminator maps to, for the hint below. */
+const FACTORY_FOR_TYPE = new Map([
+  ["custom", "custom"],
+  ["filesystem", "filesystem"],
+  ["github-releases", "githubReleases"],
+  ["mdx-remote", "mdxRemote"],
+  ["notion", "notion"],
+  ["obsidian", "obsidian"],
+  ["sanity", "sanity"],
+]);
+
+const FACTORIES_HINT =
+  'content.sources takes adapters imported from "blume/sources" — filesystem({ root }), mdxRemote({ github }), githubReleases({ owner, repo }), sanity({ projectId, dataset, query }), notion({ database }), contentful({ space, contentType }), payload({ url, collection }), strapi({ url, contentType }), obsidian({ vault }), or custom(source).';
+
+const ARRAY_HINT = `content.sources is a list of adapters — e.g. \`sources: [filesystem({ root: "docs" }), githubReleases({ owner, repo, prefix: "changelog" })]\`, imported from "blume/sources".`;
+
+const isObjectLike = (value: unknown): value is object =>
+  typeof value === "object" && value !== null;
+
+/** The 1.x object form's discriminator, when an entry carries one. */
+const legacyEntrySchema = z.looseObject({ type: z.string() });
+
+/**
+ * The message for an entry that is not a descriptor. A 1.x `{ type: "…" }`
+ * object names the factory that replaces it, so the fix is a rename plus
+ * moving the remaining fields into the call.
+ */
+const entryHint = (type: string | undefined): string => {
+  if (type === undefined) {
+    return FACTORIES_HINT;
+  }
+  const factory = FACTORY_FOR_TYPE.get(type);
+  if (!factory) {
+    return `${FACTORIES_HINT} The 1.x { type: "${type}" } object form was removed.`;
+  }
+  const call =
+    type === "custom"
+      ? "custom(source) with the source you passed as `source`"
+      : `${factory}({ … }) with the other fields as its options`;
+  return `${FACTORIES_HINT} The 1.x { type: "${type}", … } object was removed: replace it with ${call}.`;
+};
+
+/**
+ * Validates a descriptor a factory returned and resolves it to the canonical
+ * form, so a descriptor that went through JSON (or was edited by hand)
+ * resolves to the same metadata Blume ships.
+ */
+export const resolvedSourceAdapterSchema = sourceAdapterUnion.transform(
+  (value): ContentSourceAdapter => {
+    switch (value.kind) {
+      case "filesystem": {
+        return { ...filesystem(value.options), options: value.options };
+      }
+      case "github-releases": {
+        return { ...githubReleases(value.options), options: value.options };
+      }
+      case "mdx-remote": {
+        return { ...mdxRemote(value.options), options: value.options };
+      }
+      case "notion": {
+        return { ...notion(value.options), options: value.options };
+      }
+      case "contentful": {
+        return { ...contentful(value.options), options: value.options };
+      }
+      case "payload": {
+        return { ...payload(value.options), options: value.options };
+      }
+      case "strapi": {
+        return { ...strapi(value.options), options: value.options };
+      }
+      case "obsidian": {
+        return { ...obsidian(value.options), options: value.options };
+      }
+      case "sanity": {
+        return { ...sanity(value.options), options: value.options };
+      }
+      default: {
+        // Only `custom` 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 custom(value.options);
+  }
+);
+
+/**
+ * One `content.sources` entry. Anything without a `kind` — the 1.x `{ type }`
+ * object, a string, `null` — fails here with the factory hint instead of the
+ * union's opaque "invalid discriminator" message.
+ */
+const sourceEntrySchema = z
+  .custom<SourceAdapterInput>(
+    (value) => isObjectLike(value) && "kind" in value,
+    {
+      error: (issue) => {
+        const legacy = legacyEntrySchema.safeParse(issue.input);
+        return entryHint(legacy.success ? legacy.data.type : undefined);
+      },
+    }
+  )
+  .pipe(resolvedSourceAdapterSchema);
+
+/**
+ * `content.sources`: the adapters to read, in order. A non-array (the 1.x
+ * object form, say) fails with the list hint; entry errors keep their own.
+ */
+export const contentSourcesSchema = z.array(sourceEntrySchema, {
+  error: (issue) => (issue.code === "invalid_type" ? ARRAY_HINT : undefined),
+});