@getrefino/core 0.1.0-rc.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Refino contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,15 @@
+# @getrefino/core
+
+Content model, draft state and persistence contracts for **Refino** — in-browser
+editing of an existing website's copy, with the repository as the source of
+truth. Framework-independent.
+
+Installed for you by `npx @getrefino/cli init`.
+
+Browser-safe main entry: content ids, `parseCopy` / `serializeCopy`,
+`applyChanges`, draft helpers, `ContentAdapter`, `planSave`, `createContentApi`.
+
+Node-only entry `@getrefino/core/local-file`: `createLocalFileContentAdapter`
+for development.
+
+<https://refino.dev>

package/dist/adapter.d.ts

@@ -0,0 +1,80 @@
+import type { ContentChanges, ContentId, ContentSnapshot } from "./content.js";
+/** What the browser sends when the user presses Save. */
+export interface SaveRequest {
+    /** Revision the draft was based on. Must match the current revision. */
+    readonly baseRevision: string;
+    /** Only the IDs the user changed, with their new plain-text values. */
+    readonly changes: ContentChanges;
+}
+export interface CommitInfo {
+    readonly sha: string;
+    readonly message: string;
+    readonly url?: string;
+}
+export type SaveResult = {
+    readonly status: "saved";
+    readonly snapshot: ContentSnapshot;
+    readonly commit?: CommitInfo;
+} | {
+    readonly status: "unchanged";
+    readonly snapshot: ContentSnapshot;
+};
+/**
+ * The persistence boundary. The React layer only ever talks to an HTTP
+ * endpoint that wraps one of these; it never knows where content lives.
+ */
+export interface ContentAdapter {
+    /** Human-readable adapter name for logs and UI, e.g. "github" or "local-file". */
+    readonly name: string;
+    /** Read the canonical content and its current revision. */
+    load(): Promise<ContentSnapshot>;
+    /**
+     * Persist changes on top of `baseRevision`.
+     * Must throw ContentConflictError if the current revision differs.
+     * Must not write anything when the resulting file would be byte-identical.
+     */
+    save(request: SaveRequest): Promise<SaveResult>;
+}
+export declare const MAX_CHANGES_PER_SAVE = 500;
+/**
+ * Validate an untrusted request body (for example `await request.json()`).
+ * Anything the browser sends beyond `baseRevision` and `changes` is ignored;
+ * there is deliberately no way to name a file path or repository.
+ */
+export declare function parseSaveRequest(body: unknown): SaveRequest;
+/** The current state of the stored file, as an adapter sees it. */
+export interface CurrentFile extends ContentSnapshot {
+    /** Exact text of the stored file, used to detect no-op writes. */
+    readonly text: string;
+}
+export type SavePlan = {
+    readonly kind: "unchanged";
+} | {
+    readonly kind: "write";
+    readonly text: string;
+    readonly content: ContentSnapshot["content"];
+    readonly changedIds: readonly ContentId[];
+};
+/**
+ * Shared save logic for every adapter:
+ * 1. refuse if the stored revision moved (conflict),
+ * 2. validate and apply changes (unknown IDs rejected, unrelated keys kept),
+ * 3. serialize deterministically,
+ * 4. report "unchanged" when bytes are identical so no commit is made.
+ */
+export declare function planSave(current: CurrentFile, request: SaveRequest): SavePlan;
+export interface CommitMessageOptions {
+    /** Subject prefix; defaults to "Edit copy". */
+    readonly prefix?: string;
+    /** Text appended to the body, e.g. who made the edit. */
+    readonly trailer?: string;
+}
+/**
+ * Build a git commit message that reads well in `git log`:
+ *
+ *   Edit copy: home.hero.title
+ *
+ *   Updated via inline copy editor.
+ *   - home.hero.title
+ */
+export declare function buildCommitMessage(changedIds: readonly ContentId[], options?: CommitMessageOptions): string;

package/dist/adapter.js

@@ -0,0 +1,84 @@
+import { applyChanges, isValidValue, serializeCopy } from "./content.js";
+import { ContentConflictError, ContentError } from "./errors.js";
+import { isContentId } from "./ids.js";
+export const MAX_CHANGES_PER_SAVE = 500;
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+ * Validate an untrusted request body (for example `await request.json()`).
+ * Anything the browser sends beyond `baseRevision` and `changes` is ignored;
+ * there is deliberately no way to name a file path or repository.
+ */
+export function parseSaveRequest(body) {
+    if (!isPlainObject(body)) {
+        throw new ContentError("INVALID_REQUEST", "Save request must be a JSON object.");
+    }
+    const { baseRevision, changes } = body;
+    if (typeof baseRevision !== "string" || baseRevision.length === 0 || baseRevision.length > 256) {
+        throw new ContentError("INVALID_REQUEST", "Save request is missing baseRevision.");
+    }
+    if (!isPlainObject(changes)) {
+        throw new ContentError("INVALID_REQUEST", "Save request is missing changes.");
+    }
+    const entries = Object.entries(changes);
+    if (entries.length > MAX_CHANGES_PER_SAVE) {
+        throw new ContentError("INVALID_REQUEST", `Too many changes in one save (max ${MAX_CHANGES_PER_SAVE}).`);
+    }
+    const validated = {};
+    for (const [id, value] of entries) {
+        if (!isContentId(id)) {
+            throw new ContentError("INVALID_ID", `Invalid content ID "${id}".`, { id });
+        }
+        if (!isValidValue(value)) {
+            throw new ContentError("INVALID_VALUE", `Value for "${id}" must be a plain string.`, { id });
+        }
+        validated[id] = value;
+    }
+    return { baseRevision, changes: validated };
+}
+/**
+ * Shared save logic for every adapter:
+ * 1. refuse if the stored revision moved (conflict),
+ * 2. validate and apply changes (unknown IDs rejected, unrelated keys kept),
+ * 3. serialize deterministically,
+ * 4. report "unchanged" when bytes are identical so no commit is made.
+ */
+export function planSave(current, request) {
+    if (current.revision !== request.baseRevision) {
+        throw new ContentConflictError("The copy file changed since you started editing. Reload the latest copy and reapply your edits.", { content: current.content, revision: current.revision });
+    }
+    const applied = applyChanges(current.content, request.changes);
+    const text = serializeCopy(applied.content);
+    if (text === current.text) {
+        return { kind: "unchanged" };
+    }
+    return { kind: "write", text, content: applied.content, changedIds: applied.changedIds };
+}
+/**
+ * Build a git commit message that reads well in `git log`:
+ *
+ *   Edit copy: home.hero.title
+ *
+ *   Updated via inline copy editor.
+ *   - home.hero.title
+ */
+export function buildCommitMessage(changedIds, options = {}) {
+    const prefix = options.prefix ?? "Edit copy";
+    const ids = [...changedIds];
+    const joined = ids.join(", ");
+    let subject;
+    if (ids.length === 0) {
+        subject = prefix;
+    }
+    else if (ids.length <= 3 && `${prefix}: ${joined}`.length <= 72) {
+        subject = `${prefix}: ${joined}`;
+    }
+    else {
+        subject = `${prefix} (${ids.length} fields)`;
+    }
+    const bodyLines = ["Updated via inline copy editor.", ...ids.map((id) => `- ${id}`)];
+    if (options.trailer)
+        bodyLines.push("", options.trailer);
+    return `${subject}\n\n${bodyLines.join("\n")}\n`;
+}

package/dist/api.d.ts

@@ -0,0 +1,40 @@
+import type { ContentAdapter, SaveResult } from "./adapter.js";
+import type { ContentSnapshot } from "./content.js";
+import type { ContentErrorCode } from "./errors.js";
+/**
+ * Wire format between the React editor and the host's authenticated
+ * endpoint. Hosts wrap `createContentApi` in their own route handler and
+ * are responsible for authentication; this layer never sees credentials.
+ */
+export type ContentApiBody = {
+    readonly ok: true;
+    readonly snapshot: ContentSnapshot;
+} | {
+    readonly ok: true;
+    readonly result: SaveResult;
+} | {
+    readonly ok: false;
+    readonly error: {
+        readonly code: ContentErrorCode | "INTERNAL";
+        readonly message: string;
+        /** Present on CONFLICT so the editor can rebase without another request. */
+        readonly current?: ContentSnapshot;
+    };
+};
+export interface ContentApiResponse {
+    readonly status: number;
+    readonly body: ContentApiBody;
+}
+export interface ContentApi {
+    load(): Promise<ContentApiResponse>;
+    save(body: unknown): Promise<ContentApiResponse>;
+}
+export interface ContentApiOptions {
+    /** Receives unexpected (non-ContentError) failures for logging. */
+    readonly onError?: (error: unknown) => void;
+}
+/**
+ * Framework-agnostic request handling. Returns plain status + JSON body so
+ * it can sit behind Next.js, Express, Hono, Remix, or a test harness.
+ */
+export declare function createContentApi(adapter: ContentAdapter, options?: ContentApiOptions): ContentApi;

package/dist/api.js

@@ -0,0 +1,65 @@
+import { parseSaveRequest } from "./adapter.js";
+import { isContentConflictError, isContentError } from "./errors.js";
+const STATUS_BY_CODE = {
+    INVALID_ID: 400,
+    UNKNOWN_ID: 400,
+    INVALID_VALUE: 400,
+    INVALID_CONTENT: 500,
+    INVALID_REQUEST: 400,
+    CONFLICT: 409,
+    NOT_FOUND: 404,
+    NOT_CONFIGURED: 503,
+    ADAPTER_ERROR: 502,
+};
+function toErrorResponse(error, options) {
+    if (isContentConflictError(error)) {
+        return {
+            status: 409,
+            body: {
+                ok: false,
+                error: { code: "CONFLICT", message: error.message, current: error.current },
+            },
+        };
+    }
+    if (isContentError(error)) {
+        return {
+            status: STATUS_BY_CODE[error.code],
+            body: { ok: false, error: { code: error.code, message: error.message } },
+        };
+    }
+    options.onError?.(error);
+    return {
+        status: 500,
+        body: {
+            ok: false,
+            error: { code: "INTERNAL", message: "Unexpected error while handling copy request." },
+        },
+    };
+}
+/**
+ * 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 = {}) {
+    return {
+        async load() {
+            try {
+                const snapshot = await adapter.load();
+                return { status: 200, body: { ok: true, snapshot } };
+            }
+            catch (error) {
+                return toErrorResponse(error, options);
+            }
+        },
+        async save(body) {
+            try {
+                const request = parseSaveRequest(body);
+                const result = await adapter.save(request);
+                return { status: 200, body: { ok: true, result } };
+            }
+            catch (error) {
+                return toErrorResponse(error, options);
+            }
+        },
+    };
+}

package/dist/content.d.ts

@@ -0,0 +1,51 @@
+/** A stable semantic identifier such as `home.hero.title`. */
+export type ContentId = string;
+/**
+ * The canonical copy: a flat map from content ID to plain-text value.
+ * This is exactly the shape of `content/copy.json` in a host repository.
+ */
+export type CopyContent = Readonly<Record<ContentId, string>>;
+/** A partial map of IDs to new values. */
+export type ContentChanges = Readonly<Record<ContentId, string>>;
+/**
+ * The content together with an opaque revision string that identifies the
+ * exact bytes it was loaded from (a git blob SHA, a content hash, ...).
+ */
+export interface ContentSnapshot {
+    readonly content: CopyContent;
+    readonly revision: string;
+}
+export declare const MAX_VALUE_LENGTH = 20000;
+export declare function isValidValue(value: unknown): value is string;
+export declare function assertValidValue(id: ContentId, value: unknown): asserts value is string;
+/** Normalize line endings; everything else is kept byte-for-byte. */
+export declare function normalizeValue(value: string): string;
+/**
+ * Parse the text of a copy file. Accepts only a flat JSON object whose keys
+ * are valid content IDs and whose values are strings. Key order is preserved.
+ */
+export declare function parseCopy(text: string): CopyContent;
+/** Validate an already-parsed value as copy content. */
+export declare function validateCopy(value: unknown): CopyContent;
+/**
+ * Serialize copy content deterministically: two-space indent, one key per
+ * line, keys in their existing order, trailing newline. Same input always
+ * produces the same bytes, so a one-word edit is a one-line diff.
+ */
+export declare function serializeCopy(content: CopyContent): string;
+export declare function getCopy(content: CopyContent, id: ContentId): string | undefined;
+export declare function hasCopy(content: CopyContent, id: ContentId): boolean;
+export interface ApplyChangesResult {
+    readonly content: CopyContent;
+    /** IDs whose value actually differs from the input content. */
+    readonly changedIds: readonly ContentId[];
+}
+/**
+ * Apply a set of changes to content. Every ID must already exist (the editor
+ * changes words; it never adds or removes keys). Key order and unrelated
+ * values are preserved exactly.
+ */
+export declare function applyChanges(content: CopyContent, changes: ContentChanges): ApplyChangesResult;
+/** IDs present in both objects whose values differ, as a changes map. */
+export declare function diffContent(base: CopyContent, next: CopyContent): ContentChanges;
+export declare function contentEquals(a: CopyContent, b: CopyContent): boolean;

package/dist/content.js

@@ -0,0 +1,126 @@
+import { ContentError } from "./errors.js";
+import { assertContentId, isContentId } from "./ids.js";
+export const MAX_VALUE_LENGTH = 20_000;
+/** Disallow ASCII control characters except newline, carriage return and tab. */
+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;
+}
+export function isValidValue(value) {
+    return (typeof value === "string" &&
+        value.length <= MAX_VALUE_LENGTH &&
+        !hasControlCharacters(value));
+}
+export function assertValidValue(id, value) {
+    if (typeof value !== "string") {
+        throw new ContentError("INVALID_VALUE", `Value for "${id}" must be a string.`, { id });
+    }
+    if (value.length > MAX_VALUE_LENGTH) {
+        throw new ContentError("INVALID_VALUE", `Value for "${id}" is longer than ${MAX_VALUE_LENGTH} characters.`, { id });
+    }
+    if (hasControlCharacters(value)) {
+        throw new ContentError("INVALID_VALUE", `Value for "${id}" contains control characters.`, { id });
+    }
+}
+/** Normalize line endings; everything else is kept byte-for-byte. */
+export function normalizeValue(value) {
+    return value.replace(/\r\n?/g, "\n");
+}
+function isPlainObject(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        !Array.isArray(value) &&
+        Object.getPrototypeOf(value) === Object.prototype);
+}
+/**
+ * Parse the text of a copy file. Accepts only a flat JSON object whose keys
+ * are valid content IDs and whose values are strings. Key order is preserved.
+ */
+export function parseCopy(text) {
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch (error) {
+        throw new ContentError("INVALID_CONTENT", "Copy file is not valid JSON.", {
+            cause: error instanceof Error ? error.message : String(error),
+        });
+    }
+    return validateCopy(parsed);
+}
+/** Validate an already-parsed value as copy content. */
+export function validateCopy(value) {
+    if (!isPlainObject(value)) {
+        throw new ContentError("INVALID_CONTENT", "Copy content must be a JSON object mapping IDs to strings.");
+    }
+    const result = {};
+    for (const [id, entry] of Object.entries(value)) {
+        if (!isContentId(id)) {
+            throw new ContentError("INVALID_CONTENT", `Copy file contains an invalid ID "${id}".`, { id });
+        }
+        if (!isValidValue(entry)) {
+            throw new ContentError("INVALID_CONTENT", `Copy file value for "${id}" must be a plain string without control characters.`, { id });
+        }
+        result[id] = entry;
+    }
+    return result;
+}
+/**
+ * Serialize copy content deterministically: two-space indent, one key per
+ * line, keys in their existing order, trailing newline. Same input always
+ * produces the same bytes, so a one-word edit is a one-line diff.
+ */
+export function serializeCopy(content) {
+    return `${JSON.stringify(content, null, 2)}\n`;
+}
+export function getCopy(content, id) {
+    return Object.prototype.hasOwnProperty.call(content, id) ? content[id] : undefined;
+}
+export function hasCopy(content, id) {
+    return Object.prototype.hasOwnProperty.call(content, id);
+}
+/**
+ * Apply a set of changes to content. Every ID must already exist (the editor
+ * changes words; it never adds or removes keys). Key order and unrelated
+ * values are preserved exactly.
+ */
+export function applyChanges(content, changes) {
+    const next = { ...content };
+    const changedIds = [];
+    for (const [id, rawValue] of Object.entries(changes)) {
+        assertContentId(id);
+        if (!hasCopy(content, id)) {
+            throw new ContentError("UNKNOWN_ID", `Unknown content ID "${id}".`, { id });
+        }
+        assertValidValue(id, rawValue);
+        const value = normalizeValue(rawValue);
+        if (value !== content[id]) {
+            next[id] = value;
+            changedIds.push(id);
+        }
+    }
+    return { content: next, changedIds };
+}
+/** IDs present in both objects whose values differ, as a changes map. */
+export function diffContent(base, next) {
+    const changes = {};
+    for (const [id, value] of Object.entries(next)) {
+        if (hasCopy(base, id) && base[id] !== value) {
+            changes[id] = value;
+        }
+    }
+    return changes;
+}
+export function contentEquals(a, b) {
+    const aKeys = Object.keys(a);
+    const bKeys = Object.keys(b);
+    if (aKeys.length !== bKeys.length)
+        return false;
+    return aKeys.every((id) => hasCopy(b, id) && a[id] === b[id]);
+}

package/dist/draft.d.ts

@@ -0,0 +1,33 @@
+import type { ContentChanges, ContentId, CopyContent } from "./content.js";
+/**
+ * Client-side draft state: the base content the session started from plus
+ * the set of IDs the user has changed. Nothing is persisted until save.
+ * All functions are pure and return new objects.
+ */
+export interface DraftState {
+    readonly base: CopyContent;
+    readonly changes: ContentChanges;
+}
+export declare function createDraft(base: CopyContent): DraftState;
+export declare function setDraftValue(draft: DraftState, id: ContentId, rawValue: string): DraftState;
+export declare function revertDraftValue(draft: DraftState, id: ContentId): DraftState;
+export declare function revertAllDraft(draft: DraftState): DraftState;
+export declare function getDraftValue(draft: DraftState, id: ContentId): string | undefined;
+export declare function isDraftValueDirty(draft: DraftState, id: ContentId): boolean;
+export declare function getDirtyIds(draft: DraftState): ContentId[];
+export declare function isDraftDirty(draft: DraftState): boolean;
+/** The base content with the draft changes applied. */
+export declare function getDraftContent(draft: DraftState): CopyContent;
+export interface RebaseResult {
+    readonly draft: DraftState;
+    /** Dirty IDs whose base value also changed upstream. Worth a human look. */
+    readonly overlapping: readonly ContentId[];
+    /** Dirty IDs that no longer exist upstream; their edits were dropped. */
+    readonly dropped: readonly ContentId[];
+}
+/**
+ * Move a draft onto newer base content, keeping the user's unsaved edits.
+ * This is the v1 conflict workflow: reload the latest copy, reapply edits,
+ * tell the user which fields changed on both sides, let them decide.
+ */
+export declare function rebaseDraft(draft: DraftState, newBase: CopyContent): RebaseResult;

package/dist/draft.js

@@ -0,0 +1,68 @@
+import { ContentError } from "./errors.js";
+import { hasCopy, normalizeValue } from "./content.js";
+export function createDraft(base) {
+    return { base, changes: {} };
+}
+export function setDraftValue(draft, id, rawValue) {
+    if (!hasCopy(draft.base, id)) {
+        throw new ContentError("UNKNOWN_ID", `Unknown content ID "${id}".`, { id });
+    }
+    const value = normalizeValue(rawValue);
+    if (value === draft.base[id]) {
+        return revertDraftValue(draft, id);
+    }
+    if (draft.changes[id] === value)
+        return draft;
+    return { base: draft.base, changes: { ...draft.changes, [id]: value } };
+}
+export function revertDraftValue(draft, id) {
+    if (!hasCopy(draft.changes, id))
+        return draft;
+    const changes = { ...draft.changes };
+    delete changes[id];
+    return { base: draft.base, changes };
+}
+export function revertAllDraft(draft) {
+    return createDraft(draft.base);
+}
+export function getDraftValue(draft, id) {
+    if (hasCopy(draft.changes, id))
+        return draft.changes[id];
+    return hasCopy(draft.base, id) ? draft.base[id] : undefined;
+}
+export function isDraftValueDirty(draft, id) {
+    return hasCopy(draft.changes, id);
+}
+export function getDirtyIds(draft) {
+    return Object.keys(draft.changes);
+}
+export function isDraftDirty(draft) {
+    return Object.keys(draft.changes).length > 0;
+}
+/** The base content with the draft changes applied. */
+export function getDraftContent(draft) {
+    return { ...draft.base, ...draft.changes };
+}
+/**
+ * Move a draft onto newer base content, keeping the user's unsaved edits.
+ * This is the v1 conflict workflow: reload the latest copy, reapply edits,
+ * tell the user which fields changed on both sides, let them decide.
+ */
+export function rebaseDraft(draft, newBase) {
+    const changes = {};
+    const overlapping = [];
+    const dropped = [];
+    for (const [id, value] of Object.entries(draft.changes)) {
+        if (!hasCopy(newBase, id)) {
+            dropped.push(id);
+            continue;
+        }
+        if (newBase[id] !== draft.base[id]) {
+            overlapping.push(id);
+        }
+        if (newBase[id] !== value) {
+            changes[id] = value;
+        }
+    }
+    return { draft: { base: newBase, changes }, overlapping, dropped };
+}

package/dist/errors.d.ts

@@ -0,0 +1,21 @@
+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 declare class ContentError extends Error {
+    readonly code: ContentErrorCode;
+    readonly details: Readonly<Record<string, unknown>>;
+    constructor(code: ContentErrorCode, message: string, details?: Record<string, unknown>);
+}
+/**
+ * Raised when the content file changed underneath an editing session.
+ * `current` is the newest snapshot so the editor can rebase the draft on it.
+ */
+export declare class ContentConflictError extends ContentError {
+    readonly current: ContentSnapshot;
+    constructor(message: string, current: ContentSnapshot);
+}
+export declare function isContentError(value: unknown): value is ContentError;
+export declare function isContentConflictError(value: unknown): value is ContentConflictError;

package/dist/errors.js

@@ -0,0 +1,28 @@
+export class ContentError extends Error {
+    code;
+    details;
+    constructor(code, message, details = {}) {
+        super(message);
+        this.name = "ContentError";
+        this.code = code;
+        this.details = details;
+    }
+}
+/**
+ * Raised when the content file changed underneath an editing session.
+ * `current` is the newest snapshot so the editor can rebase the draft on it.
+ */
+export class ContentConflictError extends ContentError {
+    current;
+    constructor(message, current) {
+        super("CONFLICT", message, { currentRevision: current.revision });
+        this.name = "ContentConflictError";
+        this.current = current;
+    }
+}
+export function isContentError(value) {
+    return value instanceof ContentError;
+}
+export function isContentConflictError(value) {
+    return value instanceof ContentConflictError;
+}

package/dist/ids.d.ts

@@ -0,0 +1,11 @@
+/**
+ * A content ID is a dotted path of short segments, for example
+ * `home.hero.title` or `faq.items.1.question`.
+ *
+ * Segments may contain letters, digits, `-` and `_`.
+ * IDs are stable identifiers: rename them deliberately, never automatically.
+ */
+export declare const CONTENT_ID_PATTERN: RegExp;
+export declare const MAX_CONTENT_ID_LENGTH = 200;
+export declare function isContentId(value: unknown): value is string;
+export declare function assertContentId(value: unknown): asserts value is string;

package/dist/ids.js

@@ -0,0 +1,21 @@
+import { ContentError } from "./errors.js";
+/**
+ * A content ID is a dotted path of short segments, for example
+ * `home.hero.title` or `faq.items.1.question`.
+ *
+ * Segments may contain letters, digits, `-` and `_`.
+ * IDs are stable identifiers: rename them deliberately, never automatically.
+ */
+export const CONTENT_ID_PATTERN = /^[A-Za-z0-9_-]+(?:\.[A-Za-z0-9_-]+)*$/;
+export const MAX_CONTENT_ID_LENGTH = 200;
+export function isContentId(value) {
+    return (typeof value === "string" &&
+        value.length > 0 &&
+        value.length <= MAX_CONTENT_ID_LENGTH &&
+        CONTENT_ID_PATTERN.test(value));
+}
+export function assertContentId(value) {
+    if (!isContentId(value)) {
+        throw new ContentError("INVALID_ID", `Invalid content ID ${JSON.stringify(value)}. Use dotted segments like "home.hero.title".`, { id: value });
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+export { CONTENT_ID_PATTERN, MAX_CONTENT_ID_LENGTH, assertContentId, isContentId, } from "./ids.js";
+export { MAX_VALUE_LENGTH, applyChanges, assertValidValue, contentEquals, diffContent, getCopy, hasCopy, isValidValue, normalizeValue, parseCopy, serializeCopy, validateCopy, } from "./content.js";
+export type { ApplyChangesResult, ContentChanges, ContentId, ContentSnapshot, CopyContent, } from "./content.js";
+export { createDraft, getDirtyIds, getDraftContent, getDraftValue, isDraftDirty, isDraftValueDirty, rebaseDraft, revertAllDraft, revertDraftValue, setDraftValue, } from "./draft.js";
+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 { ContentConflictError, ContentError, isContentConflictError, isContentError, } from "./errors.js";
+export type { ContentErrorCode } from "./errors.js";

package/dist/index.js

@@ -0,0 +1,6 @@
+export { CONTENT_ID_PATTERN, MAX_CONTENT_ID_LENGTH, assertContentId, isContentId, } from "./ids.js";
+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 { ContentConflictError, ContentError, isContentConflictError, isContentError, } from "./errors.js";

package/dist/local-file.d.ts

@@ -0,0 +1,8 @@
+import type { ContentAdapter } from "./adapter.js";
+export interface LocalFileContentAdapterOptions {
+    /** Absolute path to the copy file, e.g. `path.join(process.cwd(), "content/copy.json")`. */
+    readonly filePath: string;
+}
+/** 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;

package/dist/local-file.js

@@ -0,0 +1,72 @@
+/**
+ * Local filesystem adapter (Node.js only). Imported as
+ * `@getrefino/core/local-file` so the browser-safe main entry never
+ * touches `node:fs`.
+ *
+ * Reads and writes the canonical copy file in place, so the development
+ * loop is: edit in the browser, save, see the JSON diff in git.
+ */
+import { createHash } from "node:crypto";
+import { readFile, rename, rm, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { planSave } from "./adapter.js";
+import { parseCopy } from "./content.js";
+import { ContentError } from "./errors.js";
+/** Revision for local files: a hash of the exact bytes on disk. */
+export function computeTextRevision(text) {
+    return createHash("sha256").update(text, "utf8").digest("hex");
+}
+export function createLocalFileContentAdapter(options) {
+    const { filePath } = options;
+    if (!filePath) {
+        throw new ContentError("NOT_CONFIGURED", "Local file adapter needs a filePath.");
+    }
+    async function readCurrent() {
+        let text;
+        try {
+            text = await readFile(filePath, "utf8");
+        }
+        catch (error) {
+            const code = error.code;
+            if (code === "ENOENT") {
+                throw new ContentError("NOT_FOUND", `Copy file not found at ${filePath}.`, { filePath });
+            }
+            throw new ContentError("ADAPTER_ERROR", `Could not read copy file: ${String(error)}`);
+        }
+        return { text, content: parseCopy(text), revision: computeTextRevision(text) };
+    }
+    /** Write to a sibling temp file and rename so readers never see a partial file. */
+    async function writeAtomically(text) {
+        const tempPath = join(dirname(filePath), `.${process.pid}-${Date.now()}.copy.tmp`);
+        try {
+            await writeFile(tempPath, text, "utf8");
+            await rename(tempPath, filePath);
+        }
+        catch (error) {
+            await rm(tempPath, { force: true });
+            throw new ContentError("ADAPTER_ERROR", `Could not write copy file: ${String(error)}`);
+        }
+    }
+    return {
+        name: "local-file",
+        async load() {
+            const { content, revision } = await readCurrent();
+            return { content, revision };
+        },
+        async save(request) {
+            const current = await readCurrent();
+            const plan = planSave(current, request);
+            if (plan.kind === "unchanged") {
+                return {
+                    status: "unchanged",
+                    snapshot: { content: current.content, revision: current.revision },
+                };
+            }
+            await writeAtomically(plan.text);
+            return {
+                status: "saved",
+                snapshot: { content: plan.content, revision: computeTextRevision(plan.text) },
+            };
+        },
+    };
+}

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@getrefino/core",
+  "version": "0.1.0-rc.1",
+  "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",
+    "copy",
+    "content",
+    "editing",
+    "cms-alternative",
+    "git"
+  ],
+  "license": "MIT",
+  "homepage": "https://refino.dev",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/forant/inline-copy.git",
+    "directory": "packages/core"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": false
+  },
+  "type": "module",
+  "sideEffects": false,
+  "files": [
+    "dist/**/*.js",
+    "dist/**/*.d.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./local-file": {
+      "types": "./dist/local-file.d.ts",
+      "default": "./dist/local-file.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "devDependencies": {
+    "@types/node": "22.20.2",
+    "typescript": "6.0.3",
+    "vitest": "5.0.0"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.build.json",
+    "dev": "tsc -p tsconfig.build.json --watch --preserveWatchOutput",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run",
+    "clean": "rm -rf dist"
+  }
+}