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

package/dist/documents/index.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Server-side content sources: reading and writing editable fields that live
+ * in the customer's own Markdown and MDX files.
+ *
+ * Imported as `@getrefino/core/documents` so the browser-safe main entry
+ * carries only the identity and wire types. See
+ * `docs/content-editing-architecture.md`.
+ */
+export { EMPTY_CONTENT_CONFIG, MAX_CONTENT_SOURCES, SUPPORTED_EXTENSIONS, documentCandidates, documentIdForPath, parseContentConfig, rebaseContentConfig, sourceTypeForPath, } from "./config.js";
+export type { ContentConfig, ContentSourceConfig, DocumentCandidate, SupportedExtension, } from "./config.js";
+export { METADATA_ALIASES, METADATA_FIELDS, METADATA_LABELS, matchMetadataFields, normalizeKey, } from "./fields.js";
+export type { MetadataFieldName, MetadataMatch, MetadataMatchResult } from "./fields.js";
+export { encodeDouble, encodeSingle, isPlainSafe, parseFrontmatter, renderScalar, } from "./frontmatter.js";
+export type { FrontmatterBlock, FrontmatterEntry, ScalarStyle } from "./frontmatter.js";
+export { MarkdownEditError, applyMarkdownEdits, findEntry, parseMarkdownSource, } from "./markdown.js";
+export type { AppliedMarkdownEdits, Eol, MarkdownEdits, MarkdownSource } from "./markdown.js";
+export { buildDocumentCommitMessage, createDocumentService } from "./service.js";
+export type { DocumentService, DocumentServiceOptions } from "./service.js";
+export type { SourceFile, SourceFileStore, SourceFileWrite, SourceFileWriteResult, } from "./file-store.js";

package/dist/documents/index.js

@@ -0,0 +1,13 @@
+/**
+ * Server-side content sources: reading and writing editable fields that live
+ * in the customer's own Markdown and MDX files.
+ *
+ * Imported as `@getrefino/core/documents` so the browser-safe main entry
+ * carries only the identity and wire types. See
+ * `docs/content-editing-architecture.md`.
+ */
+export { EMPTY_CONTENT_CONFIG, MAX_CONTENT_SOURCES, SUPPORTED_EXTENSIONS, documentCandidates, documentIdForPath, parseContentConfig, rebaseContentConfig, sourceTypeForPath, } from "./config.js";
+export { METADATA_ALIASES, METADATA_FIELDS, METADATA_LABELS, matchMetadataFields, normalizeKey, } from "./fields.js";
+export { encodeDouble, encodeSingle, isPlainSafe, parseFrontmatter, renderScalar, } from "./frontmatter.js";
+export { MarkdownEditError, applyMarkdownEdits, findEntry, parseMarkdownSource, } from "./markdown.js";
+export { buildDocumentCommitMessage, createDocumentService } from "./service.js";

package/dist/documents/markdown.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Markdown and MDX source handling.
+ *
+ * A source file is two spans: an optional leading frontmatter block, and
+ * everything after it. Refino reads fields by slicing those spans and writes
+ * them by replacing one span at a time, so a save touches exactly the bytes
+ * the owner changed.
+ *
+ * Nothing here parses Markdown or MDX. The body is a string that goes out to
+ * the editor and comes back; JSX, imports, exports, expressions, fenced
+ * code, tables, links and raw HTML survive because they are never
+ * interpreted. That is the whole MDX safety strategy, and it is why it does
+ * not decay as MDX grows.
+ *
+ * Every write is re-parsed and checked against what was intended before it
+ * is returned. A file Refino cannot round-trip is refused, never rewritten.
+ */
+import type { FrontmatterBlock, FrontmatterEntry } from "./frontmatter.js";
+export type Eol = "\n" | "\r\n";
+export interface MarkdownSource {
+    /** The file exactly as it is on disk. */
+    readonly text: string;
+    readonly eol: Eol;
+    readonly frontmatter: FrontmatterBlock | null;
+    /** The body span, with line endings normalized to `\n` for the editor. */
+    readonly body: string;
+    readonly bodyStart: number;
+    readonly bodyEnd: number;
+    /** Null when the body can be written back safely; a reason when it cannot. */
+    readonly bodyUneditableReason: string | null;
+}
+export interface MarkdownEdits {
+    /** Frontmatter values by key, already resolved from field ids. */
+    readonly frontmatter?: Readonly<Record<string, string>>;
+    /** The whole body, with `\n` line endings. */
+    readonly body?: string;
+}
+export interface AppliedMarkdownEdits {
+    readonly text: string;
+    /** What the file now holds for each edited field, after normalization. */
+    readonly frontmatter: Readonly<Record<string, string>>;
+    readonly body: string | null;
+}
+export declare class MarkdownEditError extends Error {
+    readonly key: string | null;
+    constructor(message: string, key?: string | null);
+}
+export declare function parseMarkdownSource(text: string): MarkdownSource;
+export declare function findEntry(source: MarkdownSource, key: string): FrontmatterEntry | null;
+/**
+ * Apply field edits to the source text and prove the result reads back as
+ * intended. The proof, not the parser, is what makes this safe:
+ *
+ * - the frontmatter keys are the same, in the same order;
+ * - every entry that was not edited is byte-identical;
+ * - every entry that was edited reads back exactly the value that was sent;
+ * - the body reads back exactly the body that was sent.
+ */
+export declare function applyMarkdownEdits(text: string, edits: MarkdownEdits): AppliedMarkdownEdits;

package/dist/documents/markdown.js

@@ -0,0 +1,162 @@
+import { parseFrontmatter, renderScalar } from "./frontmatter.js";
+export class MarkdownEditError extends Error {
+    key;
+    constructor(message, key = null) {
+        super(message);
+        this.name = "MarkdownEditError";
+        this.key = key;
+    }
+}
+const BOM = "";
+function detectEol(text) {
+    const index = text.indexOf("\n");
+    return index > 0 && text[index - 1] === "\r" ? "\r\n" : "\n";
+}
+/**
+ * Line endings Refino will not touch: a file that mixes them, or uses a lone
+ * carriage return, cannot have its body rewritten without also rewriting
+ * lines nobody edited.
+ */
+function bodyEolProblem(body, eol) {
+    if (/\r(?!\n)/.test(body))
+        return "the file uses carriage returns on their own";
+    const newlines = (body.match(/\n/g) ?? []).length;
+    const crlf = (body.match(/\r\n/g) ?? []).length;
+    if (crlf > 0 && crlf < newlines)
+        return "the file mixes Windows and Unix line endings";
+    if (eol === "\r\n" && crlf === 0 && newlines > 0)
+        return "the file mixes Windows and Unix line endings";
+    return null;
+}
+export function parseMarkdownSource(text) {
+    const eol = detectEol(text);
+    if (text.startsWith(BOM)) {
+        return {
+            text,
+            eol,
+            frontmatter: null,
+            body: text,
+            bodyStart: 0,
+            bodyEnd: text.length,
+            bodyUneditableReason: "the file begins with a byte order mark",
+        };
+    }
+    const frontmatter = parseFrontmatter(text);
+    const bodyStart = frontmatter ? frontmatter.end : 0;
+    const raw = text.slice(bodyStart);
+    const problem = bodyEolProblem(raw, eol);
+    return {
+        text,
+        eol,
+        frontmatter,
+        body: problem === null && eol === "\r\n" ? raw.replace(/\r\n/g, "\n") : raw,
+        bodyStart,
+        bodyEnd: text.length,
+        bodyUneditableReason: problem,
+    };
+}
+export function findEntry(source, key) {
+    return source.frontmatter?.entries.find((entry) => entry.key === key) ?? null;
+}
+function splice(text, replacements) {
+    const ordered = [...replacements].sort((a, b) => a.start - b.start);
+    let out = "";
+    let cursor = 0;
+    for (const replacement of ordered) {
+        if (replacement.start < cursor) {
+            throw new MarkdownEditError("Two edits in this article overlap in the source file.");
+        }
+        out += text.slice(cursor, replacement.start) + replacement.text;
+        cursor = replacement.end;
+    }
+    return out + text.slice(cursor);
+}
+/**
+ * Apply field edits to the source text and prove the result reads back as
+ * intended. The proof, not the parser, is what makes this safe:
+ *
+ * - the frontmatter keys are the same, in the same order;
+ * - every entry that was not edited is byte-identical;
+ * - every entry that was edited reads back exactly the value that was sent;
+ * - the body reads back exactly the body that was sent.
+ */
+export function applyMarkdownEdits(text, edits) {
+    const source = parseMarkdownSource(text);
+    const replacements = [];
+    const intendedFrontmatter = {};
+    for (const [key, value] of Object.entries(edits.frontmatter ?? {})) {
+        const entry = findEntry(source, key);
+        if (!entry) {
+            throw new MarkdownEditError(`The article has no frontmatter field "${key}".`, key);
+        }
+        if (entry.style === "unsupported") {
+            throw new MarkdownEditError(`Refino cannot edit "${key}" in this article: ${entry.reason}.`, key);
+        }
+        let rendered;
+        try {
+            rendered = renderScalar(text, entry, value);
+        }
+        catch (error) {
+            throw new MarkdownEditError(`Refino cannot write "${key}" in this article: ${error instanceof Error ? error.message : String(error)}.`, key);
+        }
+        replacements.push({ start: entry.valueStart, end: entry.valueEnd, text: rendered });
+        intendedFrontmatter[key] = value;
+    }
+    let intendedBody = null;
+    if (edits.body !== undefined) {
+        if (source.bodyUneditableReason !== null) {
+            throw new MarkdownEditError(`Refino cannot edit this article's body: ${source.bodyUneditableReason}.`);
+        }
+        let body = edits.body;
+        // Keep the file's own habit about a final newline rather than letting a
+        // textarea decide it.
+        const hadTrailingNewline = source.body.endsWith("\n");
+        if (hadTrailingNewline && body.length > 0 && !body.endsWith("\n"))
+            body += "\n";
+        if (!source.frontmatter && /^---[ \t]*\n/.test(body)) {
+            throw new MarkdownEditError("The body cannot start with a `---` line in an article that has no frontmatter: it would become frontmatter.");
+        }
+        intendedBody = body;
+        replacements.push({
+            start: source.bodyStart,
+            end: source.bodyEnd,
+            text: source.eol === "\r\n" ? body.replace(/\n/g, "\r\n") : body,
+        });
+    }
+    const next = splice(text, replacements);
+    verify(source, next, intendedFrontmatter, intendedBody);
+    return { text: next, frontmatter: intendedFrontmatter, body: intendedBody };
+}
+function verify(source, next, intendedFrontmatter, intendedBody) {
+    const reparsed = parseMarkdownSource(next);
+    const before = source.frontmatter?.entries ?? [];
+    const after = reparsed.frontmatter?.entries ?? [];
+    if (before.length !== after.length || before.some((entry, index) => entry.key !== after[index].key)) {
+        throw new MarkdownEditError("Saving would have changed this article's frontmatter structure, so nothing was written.");
+    }
+    for (let index = 0; index < before.length; index += 1) {
+        const original = before[index];
+        const written = after[index];
+        const intended = intendedFrontmatter[original.key];
+        if (intended === undefined) {
+            const originalText = source.text.slice(original.entryStart, original.entryEnd);
+            const writtenText = next.slice(written.entryStart, written.entryEnd);
+            if (originalText !== writtenText) {
+                throw new MarkdownEditError(`Saving would have rewritten the untouched frontmatter field "${original.key}", so nothing was written.`, original.key);
+            }
+            continue;
+        }
+        if (written.value !== intended) {
+            throw new MarkdownEditError(`Saving "${original.key}" would not have read back as it was written, so nothing was written.`, original.key);
+        }
+    }
+    if (intendedBody === null) {
+        if (reparsed.body !== source.body) {
+            throw new MarkdownEditError("Saving would have changed this article's body, so nothing was written.");
+        }
+        return;
+    }
+    if (reparsed.bodyUneditableReason !== null || reparsed.body !== intendedBody) {
+        throw new MarkdownEditError("Saving the body would not have read back as it was written, so nothing was written.");
+    }
+}

package/dist/documents/service.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Reading and writing article documents.
+ *
+ * The shape mirrors `planSave` deliberately: refuse if the revision moved,
+ * validate and apply, report `unchanged` when the bytes are identical so no
+ * commit is made. What is different is that a document is one of many files,
+ * so every save is planned for every document *before* any of them is
+ * written. A stale revision or a source Refino cannot round-trip stops the
+ * save while the repository is still untouched.
+ */
+import type { DocumentChangeSet, DocumentId, DocumentSaveResult, DocumentSnapshot, FieldId } from "../document.js";
+import type { ContentConfig } from "./config.js";
+import type { SourceFileStore } from "./file-store.js";
+export interface DocumentServiceOptions {
+    readonly store: SourceFileStore;
+    /**
+     * The content configuration for this request. Read per request: Refino
+     * never holds a cache of a customer's repository that outlives one call.
+     */
+    readonly loadConfig: () => ContentConfig | Promise<ContentConfig>;
+    /** Override the commit message. Receives the path and the field ids that changed. */
+    readonly commitMessage?: (context: {
+        readonly path: string;
+        readonly changedFields: readonly FieldId[];
+    }) => string;
+}
+export interface DocumentService {
+    load(documentIds: readonly DocumentId[]): Promise<readonly DocumentSnapshot[]>;
+    save(changeSets: readonly DocumentChangeSet[]): Promise<readonly DocumentSaveResult[]>;
+}
+/** The commit a document save makes: one file, named, with the fields that changed. */
+export declare function buildDocumentCommitMessage(path: string, changedFields: readonly FieldId[]): string;
+export declare function createDocumentService(options: DocumentServiceOptions): DocumentService;

package/dist/documents/service.js

@@ -0,0 +1,199 @@
+import { BODY_FIELD_ID, MAX_DOCUMENTS_PER_REQUEST, MAX_FIELDS_PER_DOCUMENT, assertDocumentId, assertFieldId, fieldKindOf, maxFieldLength, metaFieldId, } from "../document.js";
+import { normalizeValue } from "../content.js";
+import { ContentError } from "../errors.js";
+import { documentCandidates } from "./config.js";
+import { matchMetadataFields } from "./fields.js";
+import { MarkdownEditError, applyMarkdownEdits, findEntry, parseMarkdownSource } from "./markdown.js";
+/** Newline, carriage return and tab are content; nothing else below a space is. */
+function hasControlCharacters(value) {
+    for (let index = 0; index < value.length; index += 1) {
+        const code = value.charCodeAt(index);
+        if (code === 0x0a || code === 0x0d || code === 0x09)
+            continue;
+        if (code < 0x20 || code === 0x7f)
+            return true;
+    }
+    return false;
+}
+function unsafeSource(message, details = {}) {
+    return new ContentError("UNSAFE_SOURCE", message, details);
+}
+/** The commit a document save makes: one file, named, with the fields that changed. */
+export function buildDocumentCommitMessage(path, changedFields) {
+    const subject = `Edit article: ${path}`;
+    const body = ["Updated via Refino.", ...changedFields.map((field) => `- ${field}`)];
+    return `${subject.length <= 72 ? subject : "Edit article"}\n\n${body.join("\n")}\n`;
+}
+function fieldsOf(file) {
+    const fields = [];
+    for (const match of file.matches) {
+        const entry = findEntry(file.source, match.key);
+        const editable = entry.style !== "unsupported";
+        fields.push({
+            id: metaFieldId(match.field),
+            kind: "frontmatter",
+            key: match.key,
+            value: entry.value ?? file.text.slice(entry.valueStart, entry.valueEnd).trim(),
+            editable,
+            reason: editable ? null : entry.reason,
+        });
+    }
+    fields.push({
+        id: BODY_FIELD_ID,
+        kind: "body",
+        key: null,
+        value: file.source.body,
+        editable: file.source.bodyUneditableReason === null,
+        reason: file.source.bodyUneditableReason,
+    });
+    return fields;
+}
+function snapshotOf(file) {
+    return {
+        documentId: file.documentId,
+        sourceType: file.sourceType,
+        path: file.path,
+        revision: file.revision,
+        fields: fieldsOf(file),
+    };
+}
+export function createDocumentService(options) {
+    const { store } = options;
+    async function resolve(documentId, config) {
+        assertDocumentId(documentId);
+        const candidates = documentCandidates(config, documentId);
+        if (candidates.length === 0) {
+            throw new ContentError("NOT_FOUND", `No content source in refino.config.json claims "${documentId}".`, { documentId });
+        }
+        for (const candidate of candidates) {
+            const file = await store.readFile(candidate.path);
+            if (!file)
+                continue;
+            const source = parseMarkdownSource(file.text);
+            const keys = source.frontmatter?.entries.map((entry) => entry.key) ?? [];
+            return {
+                documentId,
+                path: candidate.path,
+                sourceType: candidate.sourceType,
+                text: file.text,
+                revision: file.revision,
+                source,
+                matches: matchMetadataFields(keys, candidate.source.fields).matches,
+            };
+        }
+        throw new ContentError("NOT_FOUND", `Article "${documentId}" was not found at ${candidates.map((candidate) => candidate.path).join(" or ")}.`, { documentId });
+    }
+    function assertValue(documentId, fieldId, value) {
+        if (typeof value !== "string") {
+            throw new ContentError("INVALID_VALUE", `Value for "${fieldId}" must be a string.`, { documentId, fieldId });
+        }
+        const limit = maxFieldLength(fieldId);
+        if (value.length > limit) {
+            throw new ContentError("INVALID_VALUE", `Value for "${fieldId}" is longer than ${limit} characters.`, { documentId, fieldId });
+        }
+        if (hasControlCharacters(value)) {
+            throw new ContentError("INVALID_VALUE", `Value for "${fieldId}" contains control characters.`, { documentId, fieldId });
+        }
+        return normalizeValue(value);
+    }
+    function plan(file, changeSet) {
+        if (file.revision !== changeSet.baseRevision) {
+            throw new ContentError("CONFLICT", `${file.path} changed in the repository while you were editing. Reload the latest content and reapply your edits.`, { documentId: file.documentId });
+        }
+        const entries = Object.entries(changeSet.changes);
+        if (entries.length > MAX_FIELDS_PER_DOCUMENT) {
+            throw new ContentError("INVALID_REQUEST", `Too many fields in one article save (max ${MAX_FIELDS_PER_DOCUMENT}).`);
+        }
+        const fields = fieldsOf(file);
+        const frontmatter = {};
+        const changedFields = [];
+        let body;
+        for (const [fieldId, rawValue] of entries) {
+            assertFieldId(fieldId);
+            const info = fields.find((candidate) => candidate.id === fieldId);
+            if (!info) {
+                throw new ContentError("UNKNOWN_ID", `Article "${file.documentId}" has no field "${fieldId}".`, { documentId: file.documentId, fieldId });
+            }
+            if (!info.editable) {
+                throw unsafeSource(`Refino cannot edit "${fieldId}" in ${file.path}: ${info.reason}.`, { documentId: file.documentId, fieldId });
+            }
+            const value = assertValue(file.documentId, fieldId, rawValue);
+            if (value === info.value)
+                continue;
+            changedFields.push(fieldId);
+            if (fieldKindOf(fieldId) === "body")
+                body = value;
+            else
+                frontmatter[info.key] = value;
+        }
+        if (changedFields.length === 0)
+            return null;
+        let applied;
+        try {
+            applied = applyMarkdownEdits(file.text, body === undefined ? { frontmatter } : { frontmatter, body });
+        }
+        catch (error) {
+            if (error instanceof MarkdownEditError) {
+                throw unsafeSource(`${error.message} (${file.path})`, {
+                    documentId: file.documentId,
+                    ...(error.key ? { key: error.key } : {}),
+                });
+            }
+            throw error;
+        }
+        if (applied.text === file.text)
+            return null;
+        return { file, text: applied.text, changedFields };
+    }
+    return {
+        async load(documentIds) {
+            if (documentIds.length > MAX_DOCUMENTS_PER_REQUEST) {
+                throw new ContentError("INVALID_REQUEST", `Too many articles in one request (max ${MAX_DOCUMENTS_PER_REQUEST}).`);
+            }
+            const config = await options.loadConfig();
+            const snapshots = [];
+            for (const documentId of documentIds) {
+                snapshots.push(snapshotOf(await resolve(documentId, config)));
+            }
+            return snapshots;
+        },
+        async save(changeSets) {
+            if (changeSets.length > MAX_DOCUMENTS_PER_REQUEST) {
+                throw new ContentError("INVALID_REQUEST", `Too many articles in one save (max ${MAX_DOCUMENTS_PER_REQUEST}).`);
+            }
+            const config = await options.loadConfig();
+            // Plan everything first. A stale revision or an article Refino cannot
+            // round-trip stops the save before a single byte has been written.
+            const planned = [];
+            for (const changeSet of changeSets) {
+                const file = await resolve(changeSet.documentId, config);
+                planned.push({ file, write: plan(file, changeSet) });
+            }
+            const results = [];
+            for (const { file, write } of planned) {
+                if (!write) {
+                    results.push({ documentId: file.documentId, status: "unchanged", snapshot: snapshotOf(file) });
+                    continue;
+                }
+                const message = options.commitMessage
+                    ? options.commitMessage({ path: file.path, changedFields: write.changedFields })
+                    : buildDocumentCommitMessage(file.path, write.changedFields);
+                const written = await store.writeFile({
+                    path: file.path,
+                    text: write.text,
+                    baseRevision: file.revision,
+                    message,
+                });
+                const source = parseMarkdownSource(write.text);
+                const next = { ...file, text: write.text, revision: written.revision, source };
+                results.push({
+                    documentId: file.documentId,
+                    status: "saved",
+                    snapshot: snapshotOf(next),
+                    ...(written.commit ? { commit: written.commit } : {}),
+                });
+            }
+            return results;
+        },
+    };
+}

package/dist/errors.d.ts

@@ -3,7 +3,13 @@ import type { ContentSnapshot } from "./content.js";
  * Every failure the editor can surface has one of these codes.
  * They are stable strings so hosts and UIs can branch on them.
  */
-export type ContentErrorCode = "INVALID_ID" | "UNKNOWN_ID" | "INVALID_VALUE" | "INVALID_CONTENT" | "INVALID_REQUEST" | "CONFLICT" | "NOT_FOUND" | "NOT_CONFIGURED" | "ADAPTER_ERROR";
+export type ContentErrorCode = "INVALID_ID" | "UNKNOWN_ID" | "INVALID_VALUE" | "INVALID_CONTENT" | "INVALID_REQUEST" | "CONFLICT"
+/**
+ * The source file cannot be edited safely: a frontmatter value Refino
+ * does not round-trip, or a write that would not have read back as it was
+ * written. The file is never touched when this is raised.
+ */
+ | "UNSAFE_SOURCE" | "NOT_FOUND" | "NOT_CONFIGURED" | "ADAPTER_ERROR";
 export declare class ContentError extends Error {
     readonly code: ContentErrorCode;
     readonly details: Readonly<Record<string, unknown>>;

package/dist/index.d.ts

@@ -5,7 +5,9 @@ export { createDraft, getDirtyIds, getDraftContent, getDraftValue, isDraftDirty,
 export type { DraftState, RebaseResult } from "./draft.js";
 export { MAX_CHANGES_PER_SAVE, buildCommitMessage, parseSaveRequest, planSave, } from "./adapter.js";
 export type { CommitInfo, CommitMessageOptions, ContentAdapter, CurrentFile, SavePlan, SaveRequest, SaveResult, } from "./adapter.js";
-export { createContentApi } from "./api.js";
-export type { ContentApi, ContentApiBody, ContentApiOptions, ContentApiResponse, } from "./api.js";
+export { createContentApi, parseContentSaveRequest, parseDocumentChangeSets, parseDocumentIds, } from "./api.js";
+export type { ContentApi, ContentApiBody, ContentApiOptions, ContentApiResponse, ContentLoadOptions, ContentSaveResult, DocumentSource, } from "./api.js";
+export { BODY_FIELD_ID, MAX_BODY_LENGTH, MAX_DOCUMENTS_PER_REQUEST, MAX_FIELDS_PER_DOCUMENT, MAX_FRONTMATTER_VALUE_LENGTH, META_FIELD_PREFIX, assertDocumentId, assertFieldId, documentContent, documentFieldContent, documentFieldId, fieldKindOf, isDocumentId, isFieldId, maxFieldLength, metaFieldId, splitDocumentFieldId, } from "./document.js";
+export type { ContentFieldKind, ContentSourceType, DocumentChangeSet, DocumentFieldInfo, DocumentId, DocumentSaveResult, DocumentSaveStatus, DocumentSnapshot, FieldId, } from "./document.js";
 export { ContentConflictError, ContentError, isContentConflictError, isContentError, } from "./errors.js";
 export type { ContentErrorCode } from "./errors.js";

package/dist/index.js

@@ -2,5 +2,6 @@ export { CONTENT_ID_PATTERN, MAX_CONTENT_ID_LENGTH, assertContentId, isContentId
 export { MAX_VALUE_LENGTH, applyChanges, assertValidValue, contentEquals, diffContent, getCopy, hasCopy, isValidValue, normalizeValue, parseCopy, serializeCopy, validateCopy, } from "./content.js";
 export { createDraft, getDirtyIds, getDraftContent, getDraftValue, isDraftDirty, isDraftValueDirty, rebaseDraft, revertAllDraft, revertDraftValue, setDraftValue, } from "./draft.js";
 export { MAX_CHANGES_PER_SAVE, buildCommitMessage, parseSaveRequest, planSave, } from "./adapter.js";
-export { createContentApi } from "./api.js";
+export { createContentApi, parseContentSaveRequest, parseDocumentChangeSets, parseDocumentIds, } from "./api.js";
+export { BODY_FIELD_ID, MAX_BODY_LENGTH, MAX_DOCUMENTS_PER_REQUEST, MAX_FIELDS_PER_DOCUMENT, MAX_FRONTMATTER_VALUE_LENGTH, META_FIELD_PREFIX, assertDocumentId, assertFieldId, documentContent, documentFieldContent, documentFieldId, fieldKindOf, isDocumentId, isFieldId, maxFieldLength, metaFieldId, splitDocumentFieldId, } from "./document.js";
 export { ContentConflictError, ContentError, isContentConflictError, isContentError, } from "./errors.js";

package/dist/local-file.d.ts

@@ -1,4 +1,5 @@
 import type { ContentAdapter } from "./adapter.js";
+import type { SourceFileStore } from "./documents/file-store.js";
 export interface LocalFileContentAdapterOptions {
     /** Absolute path to the copy file, e.g. `path.join(process.cwd(), "content/copy.json")`. */
     readonly filePath: string;
@@ -6,3 +7,14 @@ export interface LocalFileContentAdapterOptions {
 /** Revision for local files: a hash of the exact bytes on disk. */
 export declare function computeTextRevision(text: string): string;
 export declare function createLocalFileContentAdapter(options: LocalFileContentAdapterOptions): ContentAdapter;
+/**
+ * A `SourceFileStore` over a directory on disk: the development counterpart
+ * of the GitHub store, used for article documents. Paths are
+ * repository-relative and are resolved inside `root`; anything that escapes
+ * it is refused rather than normalized.
+ */
+export interface LocalFileStoreOptions {
+    /** Absolute path of the repository (or app) root that paths are relative to. */
+    readonly root: string;
+}
+export declare function createLocalFileStore(options: LocalFileStoreOptions): SourceFileStore;

package/dist/local-file.js

@@ -70,3 +70,62 @@ export function createLocalFileContentAdapter(options) {
         },
     };
 }
+const SAFE_SEGMENT = /^[A-Za-z0-9_.-]+$/;
+function resolveInside(root, path) {
+    if (!path || path.startsWith("/") || path.includes("\\") || path.includes("\0")) {
+        throw new ContentError("NOT_CONFIGURED", `Source path must be repository-relative: ${path}`);
+    }
+    const segments = path.split("/");
+    if (segments.some((segment) => segment === "" || segment === "." || segment === ".." || !SAFE_SEGMENT.test(segment))) {
+        throw new ContentError("NOT_CONFIGURED", `Source path contains invalid segments: ${path}`);
+    }
+    return join(root, ...segments);
+}
+export function createLocalFileStore(options) {
+    const { root } = options;
+    if (!root) {
+        throw new ContentError("NOT_CONFIGURED", "Local file store needs a root.");
+    }
+    return {
+        name: "local-file",
+        async readFile(path) {
+            const absolute = resolveInside(root, path);
+            let text;
+            try {
+                text = await readFile(absolute, "utf8");
+            }
+            catch (error) {
+                if (error.code === "ENOENT")
+                    return null;
+                throw new ContentError("ADAPTER_ERROR", `Could not read ${path}: ${String(error)}`);
+            }
+            return { text, revision: computeTextRevision(text) };
+        },
+        async writeFile(write) {
+            const absolute = resolveInside(root, write.path);
+            let current;
+            try {
+                current = await readFile(absolute, "utf8");
+            }
+            catch (error) {
+                if (error.code === "ENOENT") {
+                    throw new ContentError("NOT_FOUND", `${write.path} no longer exists.`);
+                }
+                throw new ContentError("ADAPTER_ERROR", `Could not read ${write.path}: ${String(error)}`);
+            }
+            if (computeTextRevision(current) !== write.baseRevision) {
+                throw new ContentError("CONFLICT", `${write.path} changed on disk while you were editing. Reload the latest content and reapply your edits.`);
+            }
+            const tempPath = join(dirname(absolute), `.${process.pid}-${Date.now()}.source.tmp`);
+            try {
+                await writeFile(tempPath, write.text, "utf8");
+                await rename(tempPath, absolute);
+            }
+            catch (error) {
+                await rm(tempPath, { force: true });
+                throw new ContentError("ADAPTER_ERROR", `Could not write ${write.path}: ${String(error)}`);
+            }
+            return { revision: computeTextRevision(write.text) };
+        },
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@getrefino/core",
-  "version": "0.1.0-rc.5",
+  "version": "0.1.0-rc.6",
   "description": "Core content model, draft state and persistence contracts for Refino, the in-browser editor for existing website copy. Framework-independent; the repository stays the source of truth.",
   "keywords": [
     "refino",
@@ -34,6 +34,10 @@
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
     },
+    "./documents": {
+      "types": "./dist/documents/index.d.ts",
+      "default": "./dist/documents/index.js"
+    },
     "./local-file": {
       "types": "./dist/local-file.d.ts",
       "default": "./dist/local-file.js"