npm - @micacms/astro - Versions diffs - 0.5.0-rc.2 → 0.6.0-rc.1 - Mend

@micacms/astro 0.5.0-rc.2 → 0.6.0-rc.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (17) hide show

package/README.md +10 -4
package/dist/index.d.ts +5 -7
package/dist/index.d.ts.map +1 -1
package/dist/index.js +41 -13
package/dist/index.js.map +1 -1
package/dist/manifest.d.ts.map +1 -1
package/dist/manifest.js +1 -3
package/dist/manifest.js.map +1 -1
package/package.json +20 -7
package/setup/content-collections.md +5 -4
package/setup/finish.md +30 -12
package/setup/new-project.md +3 -2
package/setup/reference.md +13 -11
package/src/index.ts +457 -0
package/src/manifest.ts +18 -0
package/src/richtext.ts +62 -0
package/src/root.ts +37 -0

package/README.md CHANGED Viewed

@@ -1,7 +1,7 @@
 # @micacms/astro
-> **Experimental.** Pre-1.0: the API and the content format can still change
-> without notice. Use it at your own risk.
+> **Public.** From 1.0, semver covers this package. Pre-1.0: the API and the
+> content format can still change in a minor release.
 Reads a Mica content repository as Astro Content Collections, through the
 Content Layer API — and publishes the content model for Mica to read back.
@@ -68,6 +68,11 @@ Astro hands a loader exactly what they require:
   loader watches its own directory and coalesces the burst of writes that saving
   one entry produces (`debounceMs`, 100 ms by default).
+The loaders also check references: a relation to a missing entry, or a media
+path to a missing file, is a warning in the build log. `strict: true` makes it
+fail the build. An entry in the other layout always fails the build, with the
+files and `npx mica migrate-layout`.
 ## Mixing with your own collections
 The return value is a plain object:
@@ -97,7 +102,8 @@ collections. They ship with the package, so they match the installed version.
 ## Install
 ```bash
-npm install @micacms/astro
+npm install @micacms/astro @micacms/core
 ```
-Astro 6 or 7 is a peer dependency. Requires Node 22.12 or newer. Licence: MIT.
+Astro 7, `@micacms/core` and zod 4 are peer dependencies. npm installs zod. ESM only. Requires Node 24 or newer.
+Licence: MIT.

package/dist/index.d.ts CHANGED Viewed

@@ -45,6 +45,11 @@ export interface MicaCollectionsOptions {
      * 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.
+     */
+    strict?: boolean;
 }
 /**
  * Entry metadata attached to every collection document.
@@ -149,11 +154,4 @@ export type SingletonDocument<S extends Site, K extends keyof S["singletons"]> =
 export { manifestFor } from "./manifest.js";
 export { DEFAULT_CONTENT_ROOT, resolveContentRoot };
 export { renderRichText, transformRichText, validateRichText, type RichTextOptions, } from "./richtext.js";
-/**
- * Re-exported for convenience, so a project that only depends on this package
- * can still build a source or read a collection. They are defined in
- * `@micacms/core`, where the Mica server can reach them too.
- */
-export { ContentReadError, ContentSourceError, ORDER_FILE, memorySource, readCollection, readSingleton, type ContentSource, type DirectoryEntry, } from "@micacms/core";
-export { fileSystemSource } from "@micacms/core/node";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAKH,OAAO,~~EAML~~,KAAK,aAAa,~~EAClB~~,KAAK,eAAe,EACpB,KAAK,cAAc,EAEnB,KAAK,IAAI,EACV,MAAM,eAAe,CAAC;AAEvB,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,OAAO,EAAE,oBAAoB,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAC;AAErE,MAAM,WAAW,sBAAsB;IACrC;;;;;;;OAOG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,gFAAgF;IAChF,MAAM,CAAC,EAAE,aAAa,CAAC;IACvB;;;;;OAKG;IACH,YAAY,CAAC,EAAE,KAAK,CAAC;IACrB;;;;;;OAMG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;~~CACrB~~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~~CAqJpB~~;~~AAuED~~,oEAAoE;AACpE,MAAM,MAAM,kBAAkB,CAC5B,CAAC,SAAS,IAAI,EACd,CAAC,SAAS,MAAM,CAAC,CAAC,aAAa,CAAC,IAC9B,aAAa,CAAC,eAAe,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AAExD,2CAA2C;AAC3C,MAAM,MAAM,iBAAiB,CAC3B,CAAC,SAAS,IAAI,EACd,CAAC,SAAS,MAAM,CAAC,CAAC,YAAY,CAAC,IAC7B,cAAc,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AAEvC,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC5C,OAAO,EAAE,oBAAoB,EAAE,kBAAkB,EAAE,CAAC;AACpD,OAAO,EACL,cAAc,EACd,iBAAiB,EACjB,gBAAgB,EAChB,KAAK,eAAe,GACrB,MAAM,eAAe,CAAC~~;AAEvB;;;;GAIG;AACH,OAAO,EACL,gBAAgB,EAChB,kBAAkB,EAClB,UAAU,EACV,YAAY,EACZ,cAAc,EACd,aAAa,EACb,KAAK,aAAa,EAClB,KAAK,cAAc,GACpB,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC~~"}
1	+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js CHANGED Viewed

@@ -17,7 +17,7 @@
  */
 import { mkdir, readFile, writeFile } from "node:fs/promises";
 import { dirname, join, relative, sep } from "node:path";
-import { fieldsSchema, MANIFEST_PATH, readCollection, readSingleton, } from "@micacms/core";
+import { createReferenceCheck, fieldsSchema, isFieldKind, MANIFEST_PATH, readCollection, readSingleton, } from "@micacms/core";
 import { fileSystemSource } from "@micacms/core/node";
 import { z } from "zod";
 import { manifestFor } from "./manifest.js";
@@ -29,6 +29,7 @@ const metaSchema = z.object({
     position: z.number(),
 });
 export function micaCollections(site, options = {}) {
+    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
@@ -45,6 +46,21 @@ export function micaCollections(site, options = {}) {
         options.publishModel === false || options.source
             ? Promise.resolve()
             : publishModel(site, rootFor(context), context.logger));
+    /** Warns about broken relations and missing files, or fails the build with `strict`. */
+    const checkReferences = async (context, source, documents) => {
+        const check = createReferenceCheck(site, source);
+        const problems = [];
+        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();
     const watch = (context, name, reload) => {
@@ -86,10 +102,7 @@ export function micaCollections(site, options = {}) {
     for (const [name, def] of Object.entries(site.collections)) {
         collections[name] = {
             type: "content_layer",
-            // `storage` rather than `output`: a media reference is a path into the
-            // repository at rest and a path into the repository once loaded. There
-            // is no expansion step left to tell the two apart.
-            schema: fieldsSchema(def.fields, "storage").extend({ _mica: metaSchema }),
+            schema: fieldsSchema(def.fields).extend({ _mica: metaSchema }),
             loader: {
                 name: `mica:${name}`,
                 load: async (context) => {
@@ -112,6 +125,7 @@ export function micaCollections(site, options = {}) {
                             });
                             context.store.set({ id: entry.slug, data, digest: context.generateDigest(data) });
                         }
+                        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);
@@ -126,7 +140,7 @@ export function micaCollections(site, options = {}) {
     for (const [name, def] of Object.entries(site.singletons)) {
         collections[name] = {
             type: "content_layer",
-            schema: fieldsSchema(def.fields, "storage"),
+            schema: fieldsSchema(def.fields),
             loader: {
                 name: `mica:${name}`,
                 load: async (context) => {
@@ -141,6 +155,7 @@ export function micaCollections(site, options = {}) {
                             context.logger.warn(`No content for "${def.label}" yet.`);
                             return;
                         }
+                        await checkReferences(context, source, [{ label: name, fields: def.fields, data }]);
                         const parsed = await context.parseData({ id: name, data });
                         context.store.set({ id: name, data: parsed, digest: context.generateDigest(parsed) });
                     };
@@ -153,6 +168,26 @@ export function micaCollections(site, options = {}) {
     }
     return collections;
 }
+/**
+ * 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) {
+    const check = (fields, at) => {
+        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.
  *
@@ -210,11 +245,4 @@ async function guard(context, source, read) {
 export { manifestFor } from "./manifest.js";
 export { DEFAULT_CONTENT_ROOT, resolveContentRoot };
 export { renderRichText, transformRichText, validateRichText, } from "./richtext.js";
-/**
- * Re-exported for convenience, so a project that only depends on this package
- * can still build a source or read a collection. They are defined in
- * `@micacms/core`, where the Mica server can reach them too.
- */
-export { ContentReadError, ContentSourceError, ORDER_FILE, memorySource, readCollection, readSingleton, } from "@micacms/core";
-export { fileSystemSource } from "@micacms/core/node";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map CHANGED Viewed

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

package/dist/manifest.d.ts.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"manifest.d.ts","sourceRoot":"","sources":["../src/manifest.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAkB,KAAK,gBAAgB,EAAE,KAAK,IAAI,EAAE,MAAM,eAAe,CAAC;~~AAKjF~~;;;GAGG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,IAAI,GAAG,gBAAgB,CAExD"}
1	+ {"version":3,"file":"manifest.d.ts","sourceRoot":"","sources":["../src/manifest.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAkB,KAAK,gBAAgB,EAAE,KAAK,IAAI,EAAE,MAAM,eAAe,CAAC;AAEjF;;;GAGG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,IAAI,GAAG,gBAAgB,CAExD"}

package/dist/manifest.js CHANGED Viewed

@@ -7,13 +7,11 @@
  * import each other.
  */
 import { createManifest } from "@micacms/core";
-/** Replaced at publish time; the fallback keeps a workspace build honest. */
-const PACKAGE_VERSION = "0.0.1";
 /**
  * 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) {
-    return createManifest(site, `@micacms/astro@${PACKAGE_VERSION}`);
+    return createManifest(site, "@micacms/astro");
 }
 //# sourceMappingURL=manifest.js.map

package/dist/manifest.js.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"manifest.js","sourceRoot":"","sources":["../src/manifest.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,cAAc,EAAoC,MAAM,eAAe,CAAC;AAEjF~~,6EAA6E;AAC7E,MAAM,eAAe,GAAG,OAAO,CAAC;AAEhC~~;;;GAGG;AACH,MAAM,UAAU,WAAW,CAAC,IAAU;IACpC,OAAO,cAAc,CAAC,IAAI,EAAE,~~kBAAkB~~,~~eAAe,EAAE,~~CAAC,CAAC;~~AACnE~~,CAAC","sourcesContent":["/*\n The protocol manifest this project publishes.\n \n Its own module rather than a function in `index.ts`, so that the integration\n * can emit a manifest without importing the loaders, and the loaders can be\n * imported without pulling in the integration. The two files would otherwise\n * import each other.\n /\n\nimport { createManifest, type ProtocolManifest, type Site } from \"@micacms/core\";\n\n~~/* Replaced at publish time; the fallback keeps a workspace build honest. /\nconst PACKAGE_VERSION = \"0.0.1\";\n\n~~/\n Mica holds no model of its own. The Astro project is the only place a\n * collection is defined, and this is how it says so.\n */\nexport function manifestFor(site: Site): ProtocolManifest {\n return createManifest(site, `@micacms/astro~~@${PACKAGE_VERSION}`~~);\n}\n"]}
1	+ {"version":3,"file":"manifest.js","sourceRoot":"","sources":["../src/manifest.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,cAAc,EAAoC,MAAM,eAAe,CAAC;AAEjF;;;GAGG;AACH,MAAM,UAAU,WAAW,CAAC,IAAU;IACpC,OAAO,cAAc,CAAC,IAAI,EAAE,gBAAgB,CAAC,CAAC;AAChD,CAAC","sourcesContent":["/*\n The protocol manifest this project publishes.\n \n Its own module rather than a function in `index.ts`, so that the integration\n * can emit a manifest without importing the loaders, and the loaders can be\n * imported without pulling in the integration. The two files would otherwise\n * import each other.\n /\n\nimport { createManifest, type ProtocolManifest, type Site } from \"@micacms/core\";\n\n/\n Mica holds no model of its own. The Astro project is the only place a\n * collection is defined, and this is how it says so.\n */\nexport function manifestFor(site: Site): ProtocolManifest {\n return createManifest(site, \"@micacms/astro\");\n}\n"]}

package/package.json CHANGED Viewed

@@ -1,9 +1,19 @@
 {
   "name": "@micacms/astro",
-  "version": "0.5.0-rc.2",
+  "version": "0.6.0-rc.1",
   "type": "module",
   "description": "Reads a Mica content repository as Astro Content Collections via the Content Layer API.",
   "license": "MIT",
+  "homepage": "https://micacms.com",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/micacms/mica.git",
+    "directory": "packages/astro"
+  },
+  "bugs": "https://github.com/micacms/mica/issues",
+  "engines": {
+    "node": ">=24"
+  },
   "author": "Alexander Müdespacher",
   "keywords": [
     "mica",
@@ -25,20 +35,23 @@
   },
   "files": [
     "dist",
-    "setup"
+    "setup",
+    "src"
   ],
   "dependencies": {
-    "@markdoc/markdoc": "^0.5.9",
-    "zod": "^4.3.6",
-    "@micacms/core": "0.5.0-rc.2"
+    "@markdoc/markdoc": "^0.5.9"
   },
   "peerDependencies": {
-    "astro": "^6.0.0 || ^7.0.0"
+    "astro": "^7.0.0",
+    "zod": "^4.3.6",
+    "@micacms/core": "^0.6.0-rc.1"
   },
   "devDependencies": {
     "@types/node": "^22.20.1",
     "astro": "^7.2.2",
-    "typescript": "^5.7.3"
+    "typescript": "^5.7.3",
+    "zod": "^4.3.6",
+    "@micacms/core": "0.6.0-rc.1"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",

package/setup/content-collections.md CHANGED Viewed

@@ -79,7 +79,7 @@ Wait for the answers.
 | `z.date()`, `z.coerce.date()` | `date()` (stored as `"YYYY-MM-DD"`) |
 | `z.enum([...])` | `select({ options })` |
 | `z.array(z.enum([...]))` | `select({ multiple: true, options })` |
-| `image()` | `media({ accept: "image" })` |
+| `image()` | `media({ accept: "image", alt: "required" })`, or `media({ accept: "image" })` for a decorative image |
 | `reference("authors")` | `relation({ collection: "authors" })` |
 | `z.object({...})` | `object({ fields })` |
 | `z.array(z.object({...}))` | `repeater({ fields })` |
@@ -161,9 +161,10 @@ endpoints such as `rss.xml.js`. See
     strings gives `NaN`, and the list is then not sorted, with no error.
   - Where an API needs a `Date`, such as the RSS `pubDate`, pass
     `new Date(entry.data.pubDate)`.
-- An image was `ImageMetadata` and is now a path from the content root. Create
-  `src/lib/media.ts` from [reference.md](./reference.md#images), and use
-  `mediaImage()`.
+- An image was `ImageMetadata` and is now `{ path, alt }` (or a path, without
+  `alt`). Create `src/lib/media.ts` from [reference.md](./reference.md#images),
+  and use `mediaImage(value.path)`. Move alt text from the old frontmatter, such
+  as `coverAlt`, into `alt`.
 - A reference was `{ collection, id }` and is now a slug:
   `getEntry("authors", entry.data.author)`.
 - `entry.id` is the slug. If ids had folders, update the links, and add

package/setup/finish.md CHANGED Viewed

@@ -1,22 +1,39 @@
 # Finish the setup
-## 1. Check
+## 1. Add scripts
+Add two scripts to `package.json`, so that the user has short commands:
+```json
+"mica": "mica",
+"check": "mica check && astro check"
+```
+- If the project has no `@astrojs/check`, use `"check": "mica check"`. Do not
+  install it only for this: without it, `astro check` asks to install it, and a
+  script cannot answer. Tell the user that nothing checks the types in
+  `.astro` files.
+- If the project already has a `mica` script, keep it. If it has a `check`
+  script without `mica check`, ask the user whether to add `mica check &&` in
+  front of it. If the user says no, use `npx mica check` in place of
+  `npm run check` in the steps below and in the notes.
+## 2. Check
 All three must pass:
 ```bash
 npx astro sync
-npx mica check     # 0 errors
+npm run check      # mica check: 0 errors; then astro check, if it is there
 npx astro build
 ```
-If the project has `@astrojs/check`, run `npx astro check` too. Do not install
-it only for this. Without it, nothing checks the types in `.astro` files: tell
-the user.
+If `astro check` reports errors that were there before you started, tell the
+user. Do not fix them unless the user asks.
 Explain each warning of `mica check` to the user, or fix it.
-## 2. Add notes for the next agent
+## 3. Add notes for the next agent
 Add this section to the project's agent instructions: `AGENTS.md`,
 `CLAUDE.md` or the file the project already uses. If `CLAUDE.md` is a link to
@@ -27,23 +44,24 @@ paths if the project uses others.
 ## Content (Mica)
 - The content model is `src/mica.ts`. The content is JSON and Markdoc in
-  `content/`; editors change it with `npx mica`.
-- After a change to `src/mica.ts`, run `npx astro sync` and `npx mica check`,
+  `content/`; editors change it with `npm run mica`.
+- After a change to `src/mica.ts`, run `npx astro sync` and `npm run check`,
   and commit `content/.mica/schema.json` with the change.
 - Renaming or removing a field or a collection does not move the stored
   content. Change the content files in the same commit, or ask first.
-- Before a commit that changes `content/`, `npx mica check` must report 0 errors.
+- Before a commit that changes `content/`, `npm run check` must pass.
 ```
-## 3. Tell the user
+## 4. Tell the user
 - What you added and changed, file by file.
 - The decisions they made, and what was not converted, if anything.
 - What to commit: every file that `git status` shows as new or changed,
   including `content/.mica/schema.json`, `package.json` and the lock file. Do
   not commit for them unless they asked.
-- How to edit: `npx mica` opens the editor on this computer. A save writes
-  files in `content/`; Publish commits them. `@micacms/editor` is a dev
+- How to edit: `npm run mica` opens the editor on this computer. A save writes
+  files in `content/`; Publish commits them. `npm run check` checks the content
+  (and the types, if `@astrojs/check` is there). `@micacms/editor` is a dev
   dependency, so on another clone, run `npm install` first.
 - That a self-hosted editor for other people is described at
   https://micacms.com/docs/self-hosting/.

package/setup/new-project.md CHANGED Viewed

@@ -17,8 +17,9 @@ Ask these questions, and wait for the answers:
 3. Do entries refer to other entries? For example, an article has an author
    from the team.
 4. Should editors put a collection in a manual order?
-5. Do images need alt text that editors write? A media field has none, so
-   each image that carries meaning needs a `text()` field beside it.
+5. Which images carry meaning, and which are decorative? An image that
+   carries meaning gets `media({ alt: "required" })`, so that editors write
+   its alt text. A decorative image gets `media()`.
 6. Do they want example content, so that the pages show something at once?
 Suggest a model from the answers, as a short list of collections, singletons

package/setup/reference.md CHANGED Viewed

@@ -9,6 +9,7 @@ The guides link here. Read the section that a step names.
 | `npx mica init` | Writes a starter `src/mica.ts` and `src/content.config.ts`. Never overwrites a file |
 | `npx astro sync` | Runs the Mica loaders, which write the model to `content/.mica/schema.json` |
 | `npx mica check` | Checks every entry against `content/.mica/schema.json`. Exit code 1 on an error |
+| `npx mica migrate-layout` | Moves entries into the layout of the model, after the first or the last rich-text or media field of a collection was added or removed |
 | `npx mica` | Opens the editor in the browser. Only for the user; do not run it yourself |
 `mica check` reads the model from `content/.mica/schema.json`. After every
@@ -61,7 +62,7 @@ in the entry list), `readonly`, `hidden`, `group`, `width` (`"full"`, `"half"`,
 | Field | Stored as | Other options |
 | --- | --- | --- |
-| `text()` | string | `minLength`, `maxLength`, `pattern`, `placeholder`, `default` |
+| `text()` | string | `minLength`, `maxLength`, `pattern` (must match the whole value), `placeholder`, `default` |
 | `textarea()` | string | `minLength`, `maxLength`, `rows`, `placeholder`, `default` |
 | `richText()` | Markdoc in its own `.mdoc` file | `toolbar`, `maxLength`, `default` |
 | `number()` | number | `min`, `max`, `step`, `integer`, `unit`, `default` |
@@ -74,7 +75,7 @@ in the entry list), `readonly`, `hidden`, `group`, `width` (`"full"`, `"half"`,
 | `object()` | object | `fields` (required), `collapsible`, `collapsed` |
 | `repeater()` | array of objects | `fields` (required), `min`, `max`, `itemLabel`, `addLabel` |
 | `relation()` | the slug of an entry | `collection` (required), `multiple` |
-| `media()` | a file path | `accept: "image" \| "document" \| "any"`, `multiple`, `max` |
+| `media()` | a file path, or `{ path, alt }` with `alt` | `accept: "image" \| "document" \| "any"`, `multiple`, `max`, `alt: "required" \| "optional"` |
 | `color()` | `"#rrggbb"` | `presets`, `default` |
 | `coordinates()` | `{ "lat": 47.37, "lng": 8.54 }` | `defaultCenter`, `defaultZoom` |
@@ -152,12 +153,13 @@ export async function writeOrder(collection, slugs) {
   await writeFile(join(ROOT, collection, "_order.json"), `${JSON.stringify(slugs, null, 2)}\n`);
 }
-// Example: `data` has every field, rich text as a Markdoc string, media as `media/<file>`.
+// Example: `data` has every field, rich text as a Markdoc string, and media as
+// `media/<file>`, or `{ path, alt }` for a `media({ alt })` field.
 // await writeEntry("news", "hello-world", {
 //   title: "Hello, world",
 //   slug: "hello-world",
 //   publishedOn: "2026-01-15",
-//   cover: "media/cover.jpg",
+//   cover: { path: "media/cover.jpg", alt: "The team at the opening" },
 //   body: "The first article.",
 // });
 ```
@@ -229,16 +231,16 @@ export function mediaImage(path: string | null | undefined): ImageMetadata | und
 ---
 import { Image } from "astro:assets";
 import { mediaImage } from "../../lib/media";
-const cover = mediaImage(article.data.cover);
+const cover = article.data.cover; // media({ alt: "required" }): { path, alt }
+const image = mediaImage(cover?.path);
 ---
-{cover && <Image src={cover} alt={article.data.title} />}
+{image && <Image src={image} alt={cover.alt} />}
 ```
-A `media({ multiple: true })` field is an array of paths:
-`project.data.gallery.map(mediaImage)`.
-A media field has no alt text. Add a `text()` field for it where the image
-carries meaning. For documents such as PDF files, use
+A `media({ multiple: true })` field is an array:
+`project.data.gallery.map((item) => mediaImage(item.path))`. A `media()`
+without `alt` is a path only: use it for a decorative image, with `alt=""`. For
+documents such as PDF files, use
 `import.meta.glob("../../content/**/*.pdf", { query: "?url", import: "default", eager: true })`
 and link to the URL.

package/src/index.ts ADDED Viewed

@@ -0,0 +1,457 @@
+/**
+ * @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 {
+  createReferenceCheck,
+  fieldsSchema,
+  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 { z } from "zod";
+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.
+   */
+  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;
+  /**
+   * Typed as `ZodType<T>` rather than a bare `ZodObject`, because Astro derives
+   * `CollectionEntry<"projects">["data"]` from `z.infer` of whatever this is.
+   * 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: 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 }): 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>;
+  }): Promise<Record<string, unknown>>;
+  generateDigest(data: Record<string, unknown> | string): string;
+}
+export type MicaCollections<S extends Site> = {
+  [K in keyof S["collections"]]: AstroCollectionConfig<
+    AstroDocument<InferCollection<S["collections"][K]>>
+  >;
+} & {
+  [K in keyof S["singletons"]]: AstroCollectionConfig<InferSingleton<S["singletons"][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));
+  /** 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: fieldsSchema(def.fields).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 data = await context.parseData({
+                id: entry.slug,
+                data: { ...entry.data, _mica: meta },
+              });
+              context.store.set({ id: entry.slug, data, digest: context.generateDigest(data) });
+            }
+            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: fieldsSchema(def.fields),
+      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 parsed = await context.parseData({ id: name, data });
+            context.store.set({ id: name, data: parsed, digest: context.generateDigest(parsed) });
+          };
+          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]>>;
+/** The document type for one singleton. */
+export type SingletonDocument<
+  S extends Site,
+  K extends keyof S["singletons"],
+> = InferSingleton<S["singletons"][K]>;
+export { manifestFor } from "./manifest.js";
+export { DEFAULT_CONTENT_ROOT, resolveContentRoot };
+export {
+  renderRichText,
+  transformRichText,
+  validateRichText,
+  type RichTextOptions,
+} from "./richtext.js";

package/src/manifest.ts ADDED Viewed

@@ -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 ADDED Viewed

@@ -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 ADDED Viewed

@@ -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));
+}