@getrefino/core 0.1.0-rc.4 → 0.1.0-rc.6

package/dist/api.d.ts

@@ -1,6 +1,30 @@
-import type { ContentAdapter, SaveResult } from "./adapter.js";
+import type { ContentAdapter, SaveRequest, SaveResult } from "./adapter.js";
 import type { ContentSnapshot } from "./content.js";
+import type { DocumentChangeSet, DocumentId, DocumentSaveResult, DocumentSnapshot } from "./document.js";
 import type { ContentErrorCode } from "./errors.js";
+/**
+ * The document half of the content API.
+ *
+ * `@getrefino/core/documents` provides the implementation; this interface is
+ * all the API layer needs, so the browser-safe entry carries no parser.
+ */
+export interface DocumentSource {
+    load(documentIds: readonly DocumentId[]): Promise<readonly DocumentSnapshot[]>;
+    save(changeSets: readonly DocumentChangeSet[]): Promise<readonly DocumentSaveResult[]>;
+}
+/**
+ * What one save produced.
+ *
+ * `documents` is the copy file untouched: an article-only save must not read
+ * or write `content/copy.json`, or an unrelated copy edit elsewhere would
+ * turn every article save into a spurious conflict.
+ */
+export type ContentSaveResult = (SaveResult & {
+    readonly documents?: readonly DocumentSaveResult[];
+}) | {
+    readonly status: "documents";
+    readonly documents: readonly DocumentSaveResult[];
+};
 /**
  * Wire format between the React editor and the host's authenticated
  * endpoint. Hosts wrap `createContentApi` in their own route handler and
@@ -9,9 +33,11 @@ import type { ContentErrorCode } from "./errors.js";
 export type ContentApiBody = {
     readonly ok: true;
     readonly snapshot: ContentSnapshot;
+    /** Present only when the request asked for articles. */
+    readonly documents?: readonly DocumentSnapshot[];
 } | {
     readonly ok: true;
-    readonly result: SaveResult;
+    readonly result: ContentSaveResult;
 } | {
     readonly ok: false;
     readonly error: {
@@ -25,14 +51,37 @@ export interface ContentApiResponse {
     readonly status: number;
     readonly body: ContentApiBody;
 }
+export interface ContentLoadOptions {
+    /** Articles rendered on the page being edited. Validated here, resolved by the document source. */
+    readonly documents?: readonly string[];
+}
 export interface ContentApi {
-    load(): Promise<ContentApiResponse>;
+    load(options?: ContentLoadOptions): Promise<ContentApiResponse>;
     save(body: unknown): Promise<ContentApiResponse>;
 }
 export interface ContentApiOptions {
     /** Receives unexpected (non-ContentError) failures for logging. */
     readonly onError?: (error: unknown) => void;
+    /** Enables article editing. Without it, `documents` in a request is refused. */
+    readonly documents?: DocumentSource;
 }
+/**
+ * Validate the document ids a request names. Ids are checked against the
+ * grammar here and against the configured sources by the document source;
+ * neither step ever accepts a path.
+ */
+export declare function parseDocumentIds(value: unknown): readonly DocumentId[];
+/** The article half of a save request. Copy is parsed by `parseSaveRequest`, untouched. */
+export declare function parseDocumentChangeSets(value: unknown): readonly DocumentChangeSet[];
+/**
+ * Split a request body into its copy half and its article half. The copy
+ * half is `null` when the body names no copy revision at all, which is how
+ * an article-only save keeps `content/copy.json` out of the transaction.
+ */
+export declare function parseContentSaveRequest(body: unknown): {
+    readonly copy: SaveRequest | null;
+    readonly documents: readonly DocumentChangeSet[];
+};
 /**
  * Framework-agnostic request handling. Returns plain status + JSON body so
  * it can sit behind Next.js, Express, Hono, Remix, or a test harness.

package/dist/api.js

@@ -1,5 +1,6 @@
 import { parseSaveRequest } from "./adapter.js";
-import { isContentConflictError, isContentError } from "./errors.js";
+import { MAX_DOCUMENTS_PER_REQUEST, MAX_FIELDS_PER_DOCUMENT, isDocumentId, isFieldId, maxFieldLength, } from "./document.js";
+import { ContentError, isContentConflictError, isContentError } from "./errors.js";
 const STATUS_BY_CODE = {
     INVALID_ID: 400,
     UNKNOWN_ID: 400,
@@ -7,6 +8,7 @@ const STATUS_BY_CODE = {
     INVALID_CONTENT: 500,
     INVALID_REQUEST: 400,
     CONFLICT: 409,
+    UNSAFE_SOURCE: 422,
     NOT_FOUND: 404,
     NOT_CONFIGURED: 503,
     ADAPTER_ERROR: 502,
@@ -36,16 +38,133 @@ function toErrorResponse(error, options) {
         },
     };
 }
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+ * Article fields and copy ids share one flat id space, which is what lets
+ * the draft, the editor and revert work on both without knowing the
+ * difference. The price is that a copy id must never be an article field id
+ * as well, and the site is told plainly rather than having one silently win.
+ */
+function assertNoIdCollision(snapshot, documents) {
+    for (const document of documents) {
+        for (const field of document.fields) {
+            const id = `${document.documentId}.${field.id}`;
+            if (Object.prototype.hasOwnProperty.call(snapshot.content, id)) {
+                throw new ContentError("INVALID_CONTENT", `"${id}" is both a copy id and a field of article "${document.documentId}". Rename the copy id.`, { id });
+            }
+        }
+    }
+}
+/**
+ * Validate the document ids a request names. Ids are checked against the
+ * grammar here and against the configured sources by the document source;
+ * neither step ever accepts a path.
+ */
+export function parseDocumentIds(value) {
+    if (value === undefined || value === null)
+        return [];
+    // A query string may repeat the parameter, comma-separate the ids, or both.
+    const list = (Array.isArray(value) ? value : [value]).flatMap((entry) => typeof entry === "string" ? entry.split(",") : [entry]);
+    const ids = [];
+    for (const entry of list) {
+        const id = typeof entry === "string" ? entry.trim() : entry;
+        if (id === "")
+            continue;
+        if (!isDocumentId(id)) {
+            throw new ContentError("INVALID_ID", `Invalid article id ${JSON.stringify(id)}.`);
+        }
+        if (!ids.includes(id))
+            ids.push(id);
+    }
+    if (ids.length > MAX_DOCUMENTS_PER_REQUEST) {
+        throw new ContentError("INVALID_REQUEST", `Too many articles in one request (max ${MAX_DOCUMENTS_PER_REQUEST}).`);
+    }
+    return ids;
+}
+/** The article half of a save request. Copy is parsed by `parseSaveRequest`, untouched. */
+export function parseDocumentChangeSets(value) {
+    if (value === undefined || value === null)
+        return [];
+    if (!Array.isArray(value)) {
+        throw new ContentError("INVALID_REQUEST", "Save request: documents must be an array.");
+    }
+    if (value.length > MAX_DOCUMENTS_PER_REQUEST) {
+        throw new ContentError("INVALID_REQUEST", `Too many articles in one save (max ${MAX_DOCUMENTS_PER_REQUEST}).`);
+    }
+    const sets = [];
+    for (const entry of value) {
+        if (!isPlainObject(entry)) {
+            throw new ContentError("INVALID_REQUEST", "Save request: each article must be an object.");
+        }
+        const { documentId, baseRevision, changes } = entry;
+        if (!isDocumentId(documentId)) {
+            throw new ContentError("INVALID_ID", `Invalid article id ${JSON.stringify(documentId)}.`);
+        }
+        if (sets.some((existing) => existing.documentId === documentId)) {
+            throw new ContentError("INVALID_REQUEST", `Article "${documentId}" appears twice in one save.`);
+        }
+        if (typeof baseRevision !== "string" || baseRevision.length === 0 || baseRevision.length > 256) {
+            throw new ContentError("INVALID_REQUEST", `Article "${documentId}" is missing baseRevision.`);
+        }
+        if (!isPlainObject(changes)) {
+            throw new ContentError("INVALID_REQUEST", `Article "${documentId}" is missing changes.`);
+        }
+        const validated = {};
+        const fields = Object.entries(changes);
+        if (fields.length > MAX_FIELDS_PER_DOCUMENT) {
+            throw new ContentError("INVALID_REQUEST", `Too many fields in one article save (max ${MAX_FIELDS_PER_DOCUMENT}).`);
+        }
+        for (const [fieldId, fieldValue] of fields) {
+            if (!isFieldId(fieldId)) {
+                throw new ContentError("INVALID_ID", `Invalid field id ${JSON.stringify(fieldId)}.`);
+            }
+            if (typeof fieldValue !== "string" || fieldValue.length > maxFieldLength(fieldId)) {
+                throw new ContentError("INVALID_VALUE", `Value for "${fieldId}" must be a string within its size limit.`);
+            }
+            validated[fieldId] = fieldValue;
+        }
+        sets.push({ documentId, baseRevision, changes: validated });
+    }
+    return sets;
+}
+/**
+ * Split a request body into its copy half and its article half. The copy
+ * half is `null` when the body names no copy revision at all, which is how
+ * an article-only save keeps `content/copy.json` out of the transaction.
+ */
+export function parseContentSaveRequest(body) {
+    if (!isPlainObject(body)) {
+        throw new ContentError("INVALID_REQUEST", "Save request must be a JSON object.");
+    }
+    const documents = parseDocumentChangeSets(body.documents);
+    if (body.baseRevision === undefined && documents.length > 0) {
+        return { copy: null, documents };
+    }
+    return { copy: parseSaveRequest(body), documents };
+}
 /**
  * Framework-agnostic request handling. Returns plain status + JSON body so
  * it can sit behind Next.js, Express, Hono, Remix, or a test harness.
  */
 export function createContentApi(adapter, options = {}) {
+    function requireDocuments() {
+        if (!options.documents) {
+            throw new ContentError("NOT_CONFIGURED", 'Article editing is not configured for this site. Add a "content" block to refino.config.json.');
+        }
+        return options.documents;
+    }
     return {
-        async load() {
+        async load(loadOptions) {
             try {
+                const documentIds = parseDocumentIds(loadOptions?.documents);
                 const snapshot = await adapter.load();
-                return { status: 200, body: { ok: true, snapshot } };
+                if (documentIds.length === 0)
+                    return { status: 200, body: { ok: true, snapshot } };
+                const documents = await requireDocuments().load(documentIds);
+                assertNoIdCollision(snapshot, documents);
+                return { status: 200, body: { ok: true, snapshot, documents } };
             }
             catch (error) {
                 return toErrorResponse(error, options);
@@ -53,8 +172,20 @@ export function createContentApi(adapter, options = {}) {
         },
         async save(body) {
             try {
-                const request = parseSaveRequest(body);
-                const result = await adapter.save(request);
+                const request = parseContentSaveRequest(body);
+                if (request.documents.length === 0) {
+                    const result = await adapter.save(request.copy ?? parseSaveRequest(body));
+                    return { status: 200, body: { ok: true, result } };
+                }
+                const source = requireDocuments();
+                // Copy first: it is the established path and fails fast on a stale
+                // revision. Articles are planned in full before any of them is
+                // written, so an unsafe source never leaves a half-saved article.
+                const copy = request.copy ? await adapter.save(request.copy) : null;
+                const documents = await source.save(request.documents);
+                const result = copy
+                    ? { ...copy, documents }
+                    : { status: "documents", documents };
                 return { status: 200, body: { ok: true, result } };
             }
             catch (error) {

package/dist/document.d.ts

@@ -0,0 +1,110 @@
+/**
+ * The content-source model: identity and wire types for editable content
+ * that lives in the customer's own source files rather than in the copy
+ * file. Browser-safe and free of parsing, so `@getrefino/react` can hold a
+ * draft of article fields without shipping a Markdown parser.
+ *
+ * The parsing, the registry and the persistence service are server-side and
+ * live in `@getrefino/core/documents`.
+ *
+ * See `docs/content-editing-architecture.md`.
+ */
+import type { ContentId, CopyContent } from "./content.js";
+/** A document id: an ordinary content id with at least two segments, e.g. `blog.hello-world`. */
+export type DocumentId = string;
+/** A field id *inside* a document: `body`, or `meta.<name>`. */
+export type FieldId = string;
+/** Which kind of source file a document was read from. */
+export type ContentSourceType = "markdown" | "mdx";
+/**
+ * What part of the source a field is.
+ *
+ * `frontmatter` a single scalar entry in the document's frontmatter block.
+ * `body`        everything after the frontmatter block, as raw source.
+ */
+export type ContentFieldKind = "frontmatter" | "body";
+/** The field id of a document's body. */
+export declare const BODY_FIELD_ID: FieldId;
+/** Prefix of every frontmatter field id. */
+export declare const META_FIELD_PREFIX = "meta.";
+/** Bodies are whole articles, not sentences, so they get their own ceiling. */
+export declare const MAX_BODY_LENGTH = 400000;
+/** Frontmatter values are metadata; the copy ceiling is generous for them already. */
+export declare const MAX_FRONTMATTER_VALUE_LENGTH = 20000;
+/**
+ * One editable (or deliberately non-editable) field of a document.
+ *
+ * Together with the document's `path`, `sourceType` and `revision` this is
+ * the whole identity of an article field: which file it came from, what kind
+ * of source that is, which field it is, what kind of field, and what its
+ * value was when it was read. The edited value lives in the draft, never
+ * here.
+ */
+export interface DocumentFieldInfo {
+    readonly id: FieldId;
+    readonly kind: ContentFieldKind;
+    /** The frontmatter key this field was read from; null for the body. */
+    readonly key: string | null;
+    /** The value as it is in the file right now. */
+    readonly value: string;
+    /** False when Refino can read this field but cannot safely write it back. */
+    readonly editable: boolean;
+    /** Why it is not editable, in one sentence. Null when it is. */
+    readonly reason: string | null;
+}
+/** A document as the editor sees it: identity, revision and fields. */
+export interface DocumentSnapshot {
+    readonly documentId: DocumentId;
+    readonly sourceType: ContentSourceType;
+    /** Repository-relative path of the source file. Resolved by the server, never sent to it. */
+    readonly path: string;
+    /** Opaque revision of the exact bytes these fields were read from. */
+    readonly revision: string;
+    readonly fields: readonly DocumentFieldInfo[];
+}
+/** Field edits for one document, on top of the revision they were read from. */
+export interface DocumentChangeSet {
+    readonly documentId: DocumentId;
+    readonly baseRevision: string;
+    readonly changes: Readonly<Record<FieldId, string>>;
+}
+export type DocumentSaveStatus = "saved" | "unchanged";
+export interface DocumentSaveResult {
+    readonly documentId: DocumentId;
+    readonly status: DocumentSaveStatus;
+    readonly snapshot: DocumentSnapshot;
+    readonly commit?: {
+        readonly sha: string;
+        readonly message: string;
+        readonly url?: string;
+    };
+}
+export declare const MAX_DOCUMENTS_PER_REQUEST = 8;
+export declare const MAX_FIELDS_PER_DOCUMENT = 64;
+/** A document id is a content id of two or more segments. */
+export declare function isDocumentId(value: unknown): value is DocumentId;
+export declare function assertDocumentId(value: unknown): asserts value is DocumentId;
+/** `body`, or `meta.` followed by one identifier segment. */
+export declare function isFieldId(value: unknown): value is FieldId;
+export declare function assertFieldId(value: unknown): asserts value is FieldId;
+/** The field id for a canonical metadata field name. */
+export declare function metaFieldId(name: string): FieldId;
+export declare function fieldKindOf(fieldId: FieldId): ContentFieldKind;
+/** The global content id a document field is edited under: `<documentId>.<fieldId>`. */
+export declare function documentFieldId(documentId: DocumentId, fieldId: FieldId): ContentId;
+/**
+ * Split a global content id back into a document and a field, using the
+ * documents actually in play. Longest prefix wins, so a source id that is a
+ * prefix of another (`blog` and `blog-archive`) is never confused.
+ * Returns null for a plain copy id.
+ */
+export declare function splitDocumentFieldId(documentIds: readonly DocumentId[], id: ContentId): {
+    readonly documentId: DocumentId;
+    readonly fieldId: FieldId;
+} | null;
+/** A document's fields as a flat copy map, keyed by their global ids. */
+export declare function documentFieldContent(snapshot: DocumentSnapshot): CopyContent;
+/** The same, for the initial values a page renders with (no revision yet). */
+export declare function documentContent(documentId: DocumentId, fields: Readonly<Record<FieldId, string>>): CopyContent;
+/** The ceiling for one field's value, by kind. */
+export declare function maxFieldLength(fieldId: FieldId): number;

package/dist/document.js

@@ -0,0 +1,89 @@
+import { ContentError } from "./errors.js";
+import { isContentId } from "./ids.js";
+/** The field id of a document's body. */
+export const BODY_FIELD_ID = "body";
+/** Prefix of every frontmatter field id. */
+export const META_FIELD_PREFIX = "meta.";
+/** Bodies are whole articles, not sentences, so they get their own ceiling. */
+export const MAX_BODY_LENGTH = 400_000;
+/** Frontmatter values are metadata; the copy ceiling is generous for them already. */
+export const MAX_FRONTMATTER_VALUE_LENGTH = 20_000;
+export const MAX_DOCUMENTS_PER_REQUEST = 8;
+export const MAX_FIELDS_PER_DOCUMENT = 64;
+/** A document id is a content id of two or more segments. */
+export function isDocumentId(value) {
+    return isContentId(value) && value.includes(".");
+}
+export function assertDocumentId(value) {
+    if (!isDocumentId(value)) {
+        throw new ContentError("INVALID_ID", `Invalid document id ${JSON.stringify(value)}. Use "<source>.<slug>", e.g. "blog.hello-world".`, { documentId: value });
+    }
+}
+/** `body`, or `meta.` followed by one identifier segment. */
+export function isFieldId(value) {
+    if (typeof value !== "string")
+        return false;
+    if (value === BODY_FIELD_ID)
+        return true;
+    if (!value.startsWith(META_FIELD_PREFIX))
+        return false;
+    const name = value.slice(META_FIELD_PREFIX.length);
+    return /^[A-Za-z0-9_-]+$/.test(name);
+}
+export function assertFieldId(value) {
+    if (!isFieldId(value)) {
+        throw new ContentError("INVALID_ID", `Invalid field id ${JSON.stringify(value)}. Use "body" or "meta.<name>".`, { fieldId: value });
+    }
+}
+/** The field id for a canonical metadata field name. */
+export function metaFieldId(name) {
+    return `${META_FIELD_PREFIX}${name}`;
+}
+export function fieldKindOf(fieldId) {
+    return fieldId === BODY_FIELD_ID ? "body" : "frontmatter";
+}
+/** The global content id a document field is edited under: `<documentId>.<fieldId>`. */
+export function documentFieldId(documentId, fieldId) {
+    return `${documentId}.${fieldId}`;
+}
+/**
+ * Split a global content id back into a document and a field, using the
+ * documents actually in play. Longest prefix wins, so a source id that is a
+ * prefix of another (`blog` and `blog-archive`) is never confused.
+ * Returns null for a plain copy id.
+ */
+export function splitDocumentFieldId(documentIds, id) {
+    let best = null;
+    for (const documentId of documentIds) {
+        if (!id.startsWith(`${documentId}.`))
+            continue;
+        const fieldId = id.slice(documentId.length + 1);
+        if (!isFieldId(fieldId))
+            continue;
+        if (!best || documentId.length > best.documentId.length)
+            best = { documentId, fieldId };
+    }
+    return best;
+}
+/** A document's fields as a flat copy map, keyed by their global ids. */
+export function documentFieldContent(snapshot) {
+    const content = {};
+    for (const field of snapshot.fields) {
+        content[documentFieldId(snapshot.documentId, field.id)] = field.value;
+    }
+    return content;
+}
+/** The same, for the initial values a page renders with (no revision yet). */
+export function documentContent(documentId, fields) {
+    const content = {};
+    for (const [fieldId, value] of Object.entries(fields)) {
+        if (!isFieldId(fieldId))
+            continue;
+        content[documentFieldId(documentId, fieldId)] = value;
+    }
+    return content;
+}
+/** The ceiling for one field's value, by kind. */
+export function maxFieldLength(fieldId) {
+    return fieldKindOf(fieldId) === "body" ? MAX_BODY_LENGTH : MAX_FRONTMATTER_VALUE_LENGTH;
+}

package/dist/documents/config.d.ts

@@ -0,0 +1,58 @@
+/**
+ * The `content` block of `refino.config.json`: which directories in the
+ * repository hold editable articles.
+ *
+ * This is the allow-list. A document id names a source and a slug, never a
+ * path, and this module is the only thing that turns one into the other.
+ * Because every segment of a document id has already been proven to match
+ * `[A-Za-z0-9_-]+`, traversal and absolute paths are unrepresentable rather
+ * than filtered out.
+ */
+import type { ContentSourceType, DocumentId } from "../document.js";
+export declare const SUPPORTED_EXTENSIONS: readonly [".md", ".mdx"];
+export type SupportedExtension = (typeof SUPPORTED_EXTENSIONS)[number];
+export declare const MAX_CONTENT_SOURCES = 16;
+export interface ContentSourceConfig {
+    /** Identifier used as the first segment of every document id from this source. */
+    readonly id: string;
+    /** Directory holding the articles, relative to the directory `refino.config.json` is in. */
+    readonly dir: string;
+    /** Extensions to try, in order. Defaults to `.md` then `.mdx`. */
+    readonly extensions: readonly SupportedExtension[];
+    /** Canonical metadata field name -> the exact frontmatter key to use. */
+    readonly fields: Readonly<Record<string, string>>;
+}
+export interface ContentConfig {
+    readonly sources: readonly ContentSourceConfig[];
+}
+export declare const EMPTY_CONTENT_CONFIG: ContentConfig;
+/** Read and validate the `content` block. An absent block means no articles, not an error. */
+export declare function parseContentConfig(value: unknown): ContentConfig;
+/**
+ * Move a configuration's directories from being relative to the config file
+ * to being relative to the repository root.
+ *
+ * Sites declare `dir` next to their own `refino.config.json`, which in a
+ * monorepo is not the repository root. The server reads the file from the
+ * repository, so it has to say where it found it.
+ */
+export declare function rebaseContentConfig(config: ContentConfig, baseDir: string): ContentConfig;
+export declare function sourceTypeForPath(path: string): ContentSourceType;
+/** One possible source file for a document id: the same slug under each configured extension. */
+export interface DocumentCandidate {
+    readonly documentId: DocumentId;
+    readonly source: ContentSourceConfig;
+    readonly path: string;
+    readonly sourceType: ContentSourceType;
+}
+/**
+ * Every path a document id could resolve to, in the source's extension
+ * order. Returns an empty list when no configured source claims the id.
+ */
+export declare function documentCandidates(config: ContentConfig, documentId: DocumentId): readonly DocumentCandidate[];
+/**
+ * The document id for a repository-relative source path, or null when no
+ * configured source claims it. This is how an integration turns the file it
+ * just rendered into the id it passes to the editor.
+ */
+export declare function documentIdForPath(config: ContentConfig, path: string): DocumentId | null;

package/dist/documents/config.js

@@ -0,0 +1,152 @@
+import { isDocumentId } from "../document.js";
+import { ContentError } from "../errors.js";
+export const SUPPORTED_EXTENSIONS = [".md", ".mdx"];
+export const MAX_CONTENT_SOURCES = 16;
+export const EMPTY_CONTENT_CONFIG = { sources: [] };
+const SOURCE_ID = /^[A-Za-z0-9_-]+$/;
+const PATH_SEGMENT = /^[A-Za-z0-9_-]+$/;
+function configError(message) {
+    return new ContentError("NOT_CONFIGURED", `refino.config.json: ${message}`);
+}
+function validateDir(value, sourceId) {
+    if (typeof value !== "string" || value.trim().length === 0) {
+        throw configError(`content source "${sourceId}" needs a "dir".`);
+    }
+    const dir = value.trim().replace(/\/+$/, "");
+    if (dir.startsWith("/") || dir.includes("\\") || dir.includes("\0")) {
+        throw configError(`content source "${sourceId}" has a "dir" that is not repository-relative.`);
+    }
+    const segments = dir.split("/");
+    if (segments.some((segment) => segment === "" || segment === "." || segment === "..")) {
+        throw configError(`content source "${sourceId}" has a "dir" with invalid segments.`);
+    }
+    return dir;
+}
+function validateExtensions(value, sourceId) {
+    if (value === undefined)
+        return SUPPORTED_EXTENSIONS;
+    if (!Array.isArray(value) || value.length === 0) {
+        throw configError(`content source "${sourceId}" has an empty "extensions".`);
+    }
+    const extensions = [];
+    for (const entry of value) {
+        if (typeof entry !== "string" || !SUPPORTED_EXTENSIONS.includes(entry)) {
+            throw configError(`content source "${sourceId}" lists extension ${JSON.stringify(entry)}; Refino edits ${SUPPORTED_EXTENSIONS.join(" and ")}.`);
+        }
+        if (!extensions.includes(entry))
+            extensions.push(entry);
+    }
+    return extensions;
+}
+function validateFields(value, sourceId) {
+    if (value === undefined)
+        return {};
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        throw configError(`content source "${sourceId}" has a "fields" that is not an object.`);
+    }
+    const fields = {};
+    for (const [field, key] of Object.entries(value)) {
+        if (typeof key !== "string" || key.length === 0) {
+            throw configError(`content source "${sourceId}" maps "${field}" to something that is not a frontmatter key.`);
+        }
+        fields[field] = key;
+    }
+    return fields;
+}
+/** Read and validate the `content` block. An absent block means no articles, not an error. */
+export function parseContentConfig(value) {
+    if (value === undefined || value === null)
+        return EMPTY_CONTENT_CONFIG;
+    if (typeof value !== "object" || Array.isArray(value)) {
+        throw configError('"content" must be an object with a "sources" array.');
+    }
+    const rawSources = value.sources;
+    if (rawSources === undefined)
+        return EMPTY_CONTENT_CONFIG;
+    if (!Array.isArray(rawSources))
+        throw configError('"content.sources" must be an array.');
+    if (rawSources.length > MAX_CONTENT_SOURCES) {
+        throw configError(`"content.sources" lists more than ${MAX_CONTENT_SOURCES} sources.`);
+    }
+    const sources = [];
+    for (const raw of rawSources) {
+        if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+            throw configError('every entry in "content.sources" must be an object.');
+        }
+        const entry = raw;
+        const id = entry.id;
+        if (typeof id !== "string" || !SOURCE_ID.test(id)) {
+            throw configError(`content source id ${JSON.stringify(id)} must be letters, digits, "-" or "_".`);
+        }
+        if (sources.some((source) => source.id === id)) {
+            throw configError(`content source "${id}" is declared twice.`);
+        }
+        sources.push({
+            id,
+            dir: validateDir(entry.dir, id),
+            extensions: validateExtensions(entry.extensions, id),
+            fields: validateFields(entry.fields, id),
+        });
+    }
+    return { sources };
+}
+/**
+ * Move a configuration's directories from being relative to the config file
+ * to being relative to the repository root.
+ *
+ * Sites declare `dir` next to their own `refino.config.json`, which in a
+ * monorepo is not the repository root. The server reads the file from the
+ * repository, so it has to say where it found it.
+ */
+export function rebaseContentConfig(config, baseDir) {
+    const base = baseDir.replace(/^\/+|\/+$/g, "");
+    if (base === "")
+        return config;
+    return { sources: config.sources.map((source) => ({ ...source, dir: `${base}/${source.dir}` })) };
+}
+export function sourceTypeForPath(path) {
+    return path.endsWith(".mdx") ? "mdx" : "markdown";
+}
+/**
+ * Every path a document id could resolve to, in the source's extension
+ * order. Returns an empty list when no configured source claims the id.
+ */
+export function documentCandidates(config, documentId) {
+    if (!isDocumentId(documentId))
+        return [];
+    const [sourceId, ...segments] = documentId.split(".");
+    const source = config.sources.find((candidate) => candidate.id === sourceId);
+    if (!source || segments.length === 0)
+        return [];
+    if (!segments.every((segment) => PATH_SEGMENT.test(segment)))
+        return [];
+    const stem = `${source.dir}/${segments.join("/")}`;
+    return source.extensions.map((extension) => ({
+        documentId,
+        source,
+        path: `${stem}${extension}`,
+        sourceType: sourceTypeForPath(`${stem}${extension}`),
+    }));
+}
+/**
+ * The document id for a repository-relative source path, or null when no
+ * configured source claims it. This is how an integration turns the file it
+ * just rendered into the id it passes to the editor.
+ */
+export function documentIdForPath(config, path) {
+    const normalized = path.replace(/^\.\//, "").replace(/\\/g, "/");
+    for (const source of config.sources) {
+        const prefix = `${source.dir}/`;
+        if (!normalized.startsWith(prefix))
+            continue;
+        const extension = source.extensions.find((candidate) => normalized.endsWith(candidate));
+        if (!extension)
+            continue;
+        const slug = normalized.slice(prefix.length, normalized.length - extension.length);
+        const segments = slug.split("/");
+        if (segments.length === 0 || !segments.every((segment) => PATH_SEGMENT.test(segment)))
+            continue;
+        return `${source.id}.${segments.join(".")}`;
+    }
+    return null;
+}