@getrefino/core 0.1.0-rc.5 → 0.1.0

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",
   "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"