@micacms/astro 0.5.0 → 0.6.0-rc.2

package/src/index.ts

@@ -0,0 +1,495 @@
+/**
+ * @micacms/astro — a Git repository as an Astro content source.
+ *
+ *   // src/content.config.ts — the model is in src/mica.ts
+ *   import { micaCollections } from "@micacms/astro";
+ *   import { site } from "./mica";
+ *
+ *   export const collections = micaCollections(site);
+ *
+ * From there the website uses ordinary Astro APIs — `getCollection("projects")`
+ * — and knows nothing about how the content arrived.
+ *
+ * There is no CMS in this path. The loaders read files that are already in the
+ * working tree, so a build needs a checkout and nothing else: no running
+ * server, no token, no network. That is the point of the Git-native design.
+ * Publishing is a commit, and CI builds the commit.
+ */
+
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, join, relative, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import {
+  collectionEntryPath,
+  createReferenceCheck,
+  entryLayout,
+  fieldsSchema,
+  INDEX_FILE,
+  singletonPath,
+  isFieldKind,
+  MANIFEST_PATH,
+  readCollection,
+  readSingleton,
+  type Collection,
+  type ContentSource,
+  type FieldMap,
+  type InferCollection,
+  type InferSingleton,
+  type Singleton,
+  type Site,
+} from "@micacms/core";
+import { fileSystemSource } from "@micacms/core/node";
+import type { ImageMetadata } from "astro";
+import { z } from "zod";
+
+import { imagePathsFromEntry } from "./images.js";
+import { manifestFor } from "./manifest.js";
+import { DEFAULT_CONTENT_ROOT, resolveContentRoot } from "./root.js";
+
+export interface MicaCollectionsOptions {
+  /**
+   * Overrides `defineSite({ root })`, which is where the content root belongs.
+   *
+   * Relative paths resolve against the Astro project root, like Astro's own
+   * `glob({ base })`. An absolute path is used as given — which is what a
+   * project whose content is a separate repository, checked out by CI
+   * somewhere else, wants.
+   */
+  root?: string;
+  /** Overrides `root` entirely. Used by tests, and by a non-filesystem source. */
+  source?: ContentSource;
+  /**
+   * Turns off publishing the model to `<root>/.mica/schema.json`.
+   *
+   * Only for a project that is not edited through Mica at all: without that
+   * file in the repository, Mica has no model and refuses to start.
+   */
+  publishModel?: false;
+  /**
+   * How long to wait after a content change before reloading, in dev.
+   *
+   * Saving one entry touches several files — `index.json` and every `.mdoc`
+   * beside it — and a Git checkout touches all of them at once. One reload
+   * after the burst is both faster and less confusing than one per file.
+   */
+  debounceMs?: number;
+  /**
+   * Fails the build on a relation to a missing entry or a missing media file.
+   * Without it, the build logs a warning for each and goes on; a missing image
+   * file fails the build either way, because Astro cannot import it.
+   */
+  strict?: boolean;
+}
+
+/**
+ * Entry metadata attached to every collection document.
+ *
+ * No timestamps: in Git they are commit metadata, which a static build cannot
+ * read cheaply. A date an editor cares about belongs in the model as a `date()` field.
+ *
+ * Namespaced because these keys share a namespace with the customer's own
+ * fields, and `position` is a plausible field name.
+ */
+export interface MicaMeta {
+  /** The entry slug, which is its identity in the repository. */
+  id: string;
+  slug: string;
+  collection: string;
+  /** Index in the collection's order, manual when `_order.json` says so. */
+  position: number;
+}
+
+const metaSchema = z.object({
+  id: z.string(),
+  slug: z.string(),
+  collection: z.string(),
+  position: z.number(),
+});
+
+/** What a document looks like inside Astro: the payload plus `_mica`. */
+export type AstroDocument<T> = T & { _mica: MicaMeta };
+
+/**
+ * The shape Astro's config loader expects.
+ *
+ * Deliberately not built with `defineCollection` from `astro:content`: that is a
+ * virtual module, resolvable only inside an Astro app's module graph, and this
+ * package is pre-compiled. `defineCollection` does nothing more than stamp this
+ * `type`, so producing the object directly keeps the package importable
+ * anywhere — including from a plain unit test.
+ */
+export interface AstroCollectionConfig<T = unknown> {
+  type: "content_layer";
+  loader: ContentLoader;
+  /**
+   * A function, so that Astro hands in its `image()`. Its result is typed as
+   * `ZodType<T>` because Astro derives `CollectionEntry<"projects">["data"]`
+   * from it: left generic, every field in every template would degrade to
+   * `any`, and the point of the shared model is that renaming a field breaks
+   * the build.
+   */
+  schema: (context: { image: () => z.ZodType }) => z.ZodType<T>;
+}
+
+/** The subset of Astro's `Loader` contract this package uses. */
+export interface ContentLoader {
+  name: string;
+  load(context: LoaderContext): Promise<void>;
+}
+
+export interface LoaderContext {
+  store: {
+    clear(): void;
+    set(entry: { id: string; data: Record<string, unknown>; digest?: string; filePath?: string }): boolean;
+    keys(): string[];
+  };
+  logger: {
+    info(message: string): void;
+    warn(message: string): void;
+    error(message: string): void;
+    debug(message: string): void;
+  };
+  meta: { get(key: string): string | undefined; set(key: string, value: string): void };
+  /**
+   * Astro's resolved config. Optional because this interface is a hand-written
+   * subset and the tests build a context by hand; `config.root` is what turns a
+   * relative content root into a path.
+   */
+  config?: { root: URL };
+  /**
+   * Present only while `astro dev` runs. Astro's watcher follows the module
+   * graph, and content files are not in it — no page imports
+   * `projects/haus-a/index.json` — so each loader watches its own directory
+   * here, exactly as Astro's own `glob` loader does.
+   */
+  watcher?: {
+    add(path: string): void;
+    on(event: "add" | "change" | "unlink", handler: (path: string) => void): void;
+  };
+  parseData(input: {
+    id: string;
+    data: Record<string, unknown>;
+    /** The entry's file, from the project root: Astro's `image()` resolves paths against it. */
+    filePath?: string;
+  }): Promise<Record<string, unknown>>;
+  generateDigest(data: Record<string, unknown> | string): string;
+}
+
+export type MicaCollections<S extends Site> = {
+  [K in keyof S["collections"]]: AstroCollectionConfig<CollectionDocument<S, K>>;
+} & {
+  [K in keyof S["singletons"]]: AstroCollectionConfig<SingletonDocument<S, K>>;
+};
+
+export function micaCollections<S extends Site>(
+  site: S,
+  options: MicaCollectionsOptions = {},
+): MicaCollections<S> {
+  assertKnownKinds(site);
+
+  /**
+   * Everything below is resolved on first load rather than here, because the
+   * Astro project root is something only a loader is told — and it is what
+   * turns `./content` into a directory. Memoised: one root and one source,
+   * however many collections and however many reloads.
+   */
+  let root: string | undefined;
+  let source: ContentSource | undefined;
+
+  const rootFor = (context: LoaderContext): string =>
+    (root ??= resolveContentRoot(options.root ?? site.root, context.config?.root));
+
+  const sourceFor = (context: LoaderContext): ContentSource =>
+    (source ??= options.source ?? fileSystemSource(rootFor(context)));
+
+  /** Published once per process; a model change restarts the dev server. */
+  let publishing: Promise<void> | undefined;
+
+  const publish = (context: LoaderContext): Promise<void> =>
+    (publishing ??=
+      options.publishModel === false || options.source
+        ? Promise.resolve()
+        : publishModel(site, rootFor(context), context.logger));
+
+  /** An entry's data file, from the content root and, outside tests, from the project root. */
+  const entryFile = (context: LoaderContext, fields: FieldMap, name: string, slug?: string) => {
+    const base = slug === undefined ? singletonPath(fields, name) : collectionEntryPath(fields, name, slug);
+    const inContent = entryLayout(fields) === "directory" ? `${base}/${INDEX_FILE}` : base;
+    const project = context.config?.root;
+    const inProject =
+      project && !options.source
+        ? relative(fileURLToPath(project), join(rootFor(context), inContent)).split(sep).join("/")
+        : undefined;
+    return { inContent, inProject };
+  };
+
+  /** Warns about broken relations and missing files, or fails the build with `strict`. */
+  const checkReferences = async (
+    context: LoaderContext,
+    source: ContentSource,
+    documents: Array<{ label: string; fields: FieldMap; data: Record<string, unknown> }>,
+  ): Promise<void> => {
+    const check = createReferenceCheck(site, source);
+    const problems: string[] = [];
+    for (const { label, fields, data } of documents) {
+      for (const issue of await check.issues(fields, data)) problems.push(`${label}: ${issue.path}: ${issue.message}`);
+    }
+    if (problems.length === 0) return;
+    if (options.strict) throw new Error(`Broken references:\n  ${problems.join("\n  ")}`);
+    for (const problem of problems) context.logger.warn(problem);
+  };
+
+  /** Collections whose watcher is already registered, so a reload adds none. */
+  const watching = new Set<string>();
+
+  const watch = (context: LoaderContext, name: string, reload: () => Promise<void>): void => {
+    const watcher = context.watcher;
+    if (!watcher || options.source || watching.has(name)) return;
+    watching.add(name);
+
+    const base = rootFor(context);
+    watcher.add(base);
+
+    // A collection lives in `<root>/<name>/`; a singleton is either
+    // `<root>/<name>.json` or `<root>/<name>/…`. Both are covered by this
+    // prefix, and nothing outside it can concern this loader — which is what
+    // keeps one collection's save from re-reading every other one.
+    const prefix = join(base, name);
+    const mine = (path: string): boolean =>
+      path === `${prefix}.json` || path.startsWith(prefix + sep);
+
+    let timer: ReturnType<typeof setTimeout> | undefined;
+
+    const onChange = (path: string): void => {
+      // The manifest is this package's own output; reloading content because
+      // the model was written is a loop waiting to happen.
+      if (path.endsWith(MANIFEST_PATH) || !mine(path)) return;
+
+      if (timer) clearTimeout(timer);
+      timer = setTimeout(() => {
+        // Content that fails its own schema lands here. The dev server has to
+        // survive it: the next save is very likely the fix.
+        void reload().catch((error: unknown) => {
+          context.logger.error(`Could not reload content: ${describe(error)}`);
+        });
+      }, options.debounceMs ?? 100);
+      // A pending reload is never a reason to keep the process alive.
+      timer.unref?.();
+    };
+
+    watcher.on("change", onChange);
+    watcher.on("add", onChange);
+    watcher.on("unlink", onChange);
+  };
+
+  const collections = {} as Record<string, AstroCollectionConfig<unknown>>;
+
+  for (const [name, def] of Object.entries(site.collections) as [string, Collection][]) {
+    collections[name] = {
+      type: "content_layer",
+      schema: ({ image }) => fieldsSchema(def.fields, { image }).extend({ _mica: metaSchema }),
+      loader: {
+        name: `mica:${name}`,
+        load: async (context) => {
+          const read = async (): Promise<void> => {
+            const source = sourceFor(context);
+            const entries = await guard(context, source, () => readCollection(source, def, name));
+
+            // A full replace, not a merge: an entry deleted from the repository
+            // has to disappear from the build.
+            context.store.clear();
+
+            for (const entry of entries) {
+              const meta: MicaMeta = {
+                id: entry.slug,
+                slug: entry.slug,
+                collection: name,
+                position: entry.position,
+              };
+
+              const file = entryFile(context, def.fields, name, entry.slug);
+              const data = await context.parseData({
+                id: entry.slug,
+                data: { ...imagePathsFromEntry(def.fields, entry.data, file.inContent), _mica: meta },
+                ...(file.inProject ? { filePath: file.inProject } : {}),
+              });
+              context.store.set({
+                id: entry.slug,
+                data,
+                digest: context.generateDigest(data),
+                ...(file.inProject ? { filePath: file.inProject } : {}),
+              });
+            }
+
+            await checkReferences(
+              context,
+              source,
+              entries.map((entry) => ({ label: `${name}/${entry.slug}`, fields: def.fields, data: entry.data })),
+            );
+            context.logger.info(`Loaded ${entries.length} ${entries.length === 1 ? "entry" : "entries"} of "${def.label}"`);
+          };
+
+          await publish(context);
+          await read();
+          watch(context, name, read);
+        },
+      },
+    };
+  }
+
+  // A singleton becomes a one-entry collection whose id is its name, so the
+  // website reaches it with the same `getEntry` it uses for everything else.
+  for (const [name, def] of Object.entries(site.singletons) as [string, Singleton][]) {
+    collections[name] = {
+      type: "content_layer",
+      schema: ({ image }) => fieldsSchema(def.fields, { image }),
+      loader: {
+        name: `mica:${name}`,
+        load: async (context) => {
+          const read = async (): Promise<void> => {
+            const source = sourceFor(context);
+            const data = await guard(context, source, () => readSingleton(source, def, name));
+
+            context.store.clear();
+            if (data === null) {
+              // Not fatal. A site is normally deployed before every settings
+              // form has been filled in, and the page that reads this singleton
+              // reports the absence far better than the loader can.
+              context.logger.warn(`No content for "${def.label}" yet.`);
+              return;
+            }
+
+            await checkReferences(context, source, [{ label: name, fields: def.fields, data }]);
+            const file = entryFile(context, def.fields, name);
+            const parsed = await context.parseData({
+              id: name,
+              data: imagePathsFromEntry(def.fields, data, file.inContent),
+              ...(file.inProject ? { filePath: file.inProject } : {}),
+            });
+            context.store.set({
+              id: name,
+              data: parsed,
+              digest: context.generateDigest(parsed),
+              ...(file.inProject ? { filePath: file.inProject } : {}),
+            });
+          };
+
+          await publish(context);
+          await read();
+          watch(context, name, read);
+        },
+      },
+    };
+  }
+
+  return collections as MicaCollections<S>;
+}
+
+/**
+ * The site's own model must use only kinds this package knows. Mica reads an
+ * unknown kind as one from a newer version and makes its collection read-only,
+ * so a typo would otherwise pass the build and lock the collection.
+ */
+function assertKnownKinds(site: Site): void {
+  const check = (fields: FieldMap, at: string) => {
+    for (const [key, field] of Object.entries(fields)) {
+      if (!isFieldKind(field.kind)) {
+        throw new Error(`Field "${at}.${key}" has the unknown kind "${String(field.kind)}". Use the field functions from @micacms/core.`);
+      }
+      if (field.kind === "object" || field.kind === "repeater") check(field.fields, `${at}.${key}`);
+    }
+  };
+  for (const [name, def] of Object.entries(site.collections)) check(def.fields, `collections.${name}`);
+  for (const [name, def] of Object.entries(site.singletons)) check(def.fields, `singletons.${name}`);
+}
+
+/**
+ * Writes the model into the content root, for Mica to read back.
+ *
+ * Mica holds no content model: the Astro project is the only place a collection
+ * is defined, and this is how it says so. The file goes *inside the content
+ * root* so that it travels to Mica the way content does — through Git and the
+ * repository connector — with nothing to mount and no second channel to keep in
+ * step. Commit it.
+ *
+ * Done from a loader rather than an integration because this is the moment both
+ * facts are in hand: the model, and the project root that turns `./content`
+ * into a directory. It also means `astro.config` needs no Mica in it, which is
+ * what lets a project define Mica collections and ordinary Astro ones in the
+ * same `content.config.ts`.
+ */
+async function publishModel(
+  site: Site,
+  root: string,
+  logger: LoaderContext["logger"],
+): Promise<void> {
+  const target = join(root, MANIFEST_PATH);
+  const contents = `${JSON.stringify(manifestFor(site), null, 2)}\n`;
+
+  try {
+    // Only when it differs. The content root is watched in dev, and rewriting
+    // an identical file on every start would ask for a reload for no reason.
+    if ((await readFile(target, "utf8").catch(() => null)) === contents) return;
+
+    await mkdir(dirname(target), { recursive: true });
+    await writeFile(target, contents, "utf8");
+    logger.info(`Wrote the content model to ${relative(process.cwd(), target)} — commit it for Mica to read.`);
+  } catch (error) {
+    // A site that builds correctly should not fail over this, and a read-only
+    // checkout is a normal way to build one in CI. Mica reports a missing model
+    // itself, and far more usefully.
+    logger.warn(`Could not write the content model: ${describe(error)}`);
+  }
+}
+
+function describe(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+/**
+ * Reports a read failure against the content root that produced it.
+ *
+ * A build failing on unreadable content is correct — publishing a half-empty
+ * site would be worse — but the message has to name the directory that was
+ * read, because the usual cause is a content root pointing at the wrong place.
+ */
+async function guard<T>(
+  context: LoaderContext,
+  source: ContentSource,
+  read: () => Promise<T>,
+): Promise<T> {
+  try {
+    return await read();
+  } catch (error) {
+    const detail = error instanceof Error ? error.message : String(error);
+    context.logger.error(detail);
+
+    throw new Error(`Could not read content from ${source.origin}.\n  ${detail}`, { cause: error });
+  }
+}
+
+/* ------------------------------------------------------------------ *
+ * Types for the website
+ * ------------------------------------------------------------------ */
+
+/** The document type for one collection, as it appears in Astro. */
+export type CollectionDocument<
+  S extends Site,
+  K extends keyof S["collections"],
+> = AstroDocument<InferCollection<S["collections"][K], ImageMetadata>>;
+
+/** The document type for one singleton. */
+export type SingletonDocument<
+  S extends Site,
+  K extends keyof S["singletons"],
+> = InferSingleton<S["singletons"][K], ImageMetadata>;
+
+export { manifestFor } from "./manifest.js";
+export { DEFAULT_CONTENT_ROOT, resolveContentRoot };
+export {
+  renderRichText,
+  transformRichText,
+  validateRichText,
+  type RichTextOptions,
+} from "./richtext.js";

package/src/manifest.ts

@@ -0,0 +1,18 @@
+/**
+ * The protocol manifest this project publishes.
+ *
+ * Its own module rather than a function in `index.ts`, so that the integration
+ * can emit a manifest without importing the loaders, and the loaders can be
+ * imported without pulling in the integration. The two files would otherwise
+ * import each other.
+ */
+
+import { createManifest, type ProtocolManifest, type Site } from "@micacms/core";
+
+/**
+ * Mica holds no model of its own. The Astro project is the only place a
+ * collection is defined, and this is how it says so.
+ */
+export function manifestFor(site: Site): ProtocolManifest {
+  return createManifest(site, "@micacms/astro");
+}

package/src/richtext.ts

@@ -0,0 +1,62 @@
+/**
+ * Rendering a rich-text field.
+ *
+ * A `richText()` field is persisted as Markdoc, and this is what turns it into
+ * HTML at build time. It runs during `astro build` only; the deployed page is
+ * static, and no visitor's browser ever sees Markdoc.
+ *
+ * Markdoc rather than Markdown-with-HTML for one reason that matters: a Markdoc
+ * document can only produce what the configuration allows. An undeclared
+ * `{% tag %}` renders as nothing rather than as itself, and raw HTML is inert
+ * unless it is explicitly permitted — which it is not here. So the canonical
+ * content format cannot carry markup that escapes the site's own styling, and a
+ * compromised or careless editor session cannot inject script into a build.
+ */
+
+import Markdoc, { type Config, type RenderableTreeNode } from "@markdoc/markdoc";
+
+export interface RichTextOptions {
+  /**
+   * Extra Markdoc configuration: custom tags, nodes or variables.
+   *
+   * The place a project adds a callout or a gallery block without giving up the
+   * closed set that makes the format safe. A tag must be declared here to
+   * render at all.
+   */
+  config?: Config;
+}
+
+/**
+ * Markdoc source to an HTML string.
+ *
+ * Returns an empty string for empty input, so a caller can render the result
+ * directly without a null check ahead of it.
+ */
+export function renderRichText(source: string | null | undefined, options: RichTextOptions = {}): string {
+  if (!source || source.trim() === "") return "";
+
+  const tree = transformRichText(source, options);
+  return Markdoc.renderers.html(tree);
+}
+
+/**
+ * The intermediate renderable tree, for a project that wants to render with
+ * its own components rather than to an HTML string.
+ */
+export function transformRichText(
+  source: string,
+  options: RichTextOptions = {},
+): RenderableTreeNode {
+  return Markdoc.transform(Markdoc.parse(source), options.config ?? {});
+}
+
+/**
+ * Problems Markdoc found in a document, for a build that wants to be strict.
+ *
+ * Not called by `renderRichText`: a malformed heading should not stop a site
+ * from deploying, and Markdoc degrades to plain text rather than to nothing.
+ * Exposed so a project can decide otherwise.
+ */
+export function validateRichText(source: string, options: RichTextOptions = {}) {
+  return Markdoc.validate(Markdoc.parse(source), options.config ?? {});
+}

package/src/root.ts

@@ -0,0 +1,37 @@
+/**
+ * Where the content root is, said once.
+ *
+ * The collections, the dev integration and the manifest writer all have to
+ * agree on this directory, and a disagreement between them produces an empty
+ * build rather than an error — the worst kind of failure. So the project states
+ * it once, in `defineSite({ root })`, and everything here resolves that one
+ * string the same way.
+ *
+ * Resolved against the **Astro project root**, not the working directory, which
+ * is what Astro's own `glob({ base })` does. A relative root therefore means
+ * the same thing whether the build was started from the project, from a
+ * workspace root, or by an editor extension. Absolute paths are left alone, for
+ * content that lives outside the project.
+ */
+
+import { isAbsolute, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+export const DEFAULT_CONTENT_ROOT = "./content";
+
+export function resolveContentRoot(root: string | undefined, projectRoot?: URL): string {
+  const configured = root ?? DEFAULT_CONTENT_ROOT;
+
+  if (isAbsolute(configured)) return configured;
+
+  // Only outside a loader or a hook — a plain unit test, or an Astro version
+  // that stops passing its config. The working directory is the best guess
+  // left, and it is right whenever the build was started from the project.
+  if (!projectRoot) return resolve(configured);
+
+  // A base without a trailing slash would have its last segment replaced
+  // rather than appended to. Astro's `config.root` has one; nothing else is
+  // guaranteed to.
+  const base = projectRoot.href.endsWith("/") ? projectRoot.href : `${projectRoot.href}/`;
+  return fileURLToPath(new URL(configured, base));
+}