gazetta 0.5.0 → 0.6.0

package/dist/history-provider.js

@@ -0,0 +1,226 @@
+/**
+ * HistoryProvider implementation on top of any StorageProvider.
+ *
+ * Layout per target (inside `.gazetta/history/` under the target's
+ * storage root):
+ *
+ *   index.json                     { nextId: N, revisions: ['rev-0001', ...] }
+ *   revisions/rev-NNNN.json        one manifest per revision — metadata +
+ *                                  items map (itemPath → blob hash)
+ *   objects/<hh>/<rest>            content-addressed blobs (SHA-256, sharded
+ *                                  by first 2 hex chars)
+ *
+ * Design-decisions.md #18:
+ *  - One uniform approach across all providers (no native versioning).
+ *  - Content-addressed blobs → unchanged items share storage across
+ *    revisions; storage scales with unique content, not revision count.
+ *  - Soft undo only — every restore writes a new forward revision.
+ *  - Retention default 50; oldest evicted on write.
+ *
+ * SRP: this module owns .gazetta/history/ layout and retention. Nothing
+ * else. The write pipeline (save/publish) calls `recordRevision`; undo/
+ * rollback call `readRevision` + `readBlob`. Restore happens outside —
+ * this module doesn't touch the content tree.
+ */
+import { createHash } from 'node:crypto';
+import { DEFAULT_HISTORY_RETENTION } from './types.js';
+/**
+ * Build a HistoryProvider backed by the given storage. No I/O happens
+ * at construction time — everything is lazy on first call.
+ */
+export function createHistoryProvider(opts) {
+    const { storage } = opts;
+    const root = opts.rootPath ?? '.gazetta/history';
+    const retention = Math.max(1, opts.retention ?? DEFAULT_HISTORY_RETENTION);
+    const indexPath = join(root, 'index.json');
+    /** Read the index or return an empty one if it doesn't exist yet. */
+    async function readIndex() {
+        if (!(await storage.exists(indexPath))) {
+            return { revisions: [] };
+        }
+        const parsed = JSON.parse(await storage.readFile(indexPath));
+        // Forward-compat: tolerate legacy `nextId` by ignoring it. Old indexes
+        // (from the numeric-id era) continue to read cleanly, new writes use
+        // the timestamp scheme. No migration pass needed — retention naturally
+        // evicts the legacy ids over time.
+        return { revisions: parsed.revisions ?? [] };
+    }
+    /**
+     * Ensure the parent directory exists before writing. Object-store
+     * providers (R2, S3) ignore mkdir. Filesystem requires it because
+     * `writeFile` fails on missing parents, and our sharded blob paths
+     * (objects/<hh>/<rest>) plus revisions/rev-NNNN.json live in dirs
+     * that don't exist until the first write.
+     */
+    async function writeWithParents(path, content) {
+        const parent = path.substring(0, path.lastIndexOf('/'));
+        if (parent)
+            await storage.mkdir(parent);
+        await storage.writeFile(path, content);
+    }
+    async function writeIndex(idx) {
+        await writeWithParents(indexPath, JSON.stringify(idx, null, 2) + '\n');
+    }
+    function blobPath(hash) {
+        // Shard by first two hex chars — keeps any one `objects/` subdirectory
+        // from ballooning past a few thousand entries on large sites.
+        return join(root, 'objects', hash.slice(0, 2), hash.slice(2));
+    }
+    function revisionPath(id) {
+        return join(root, 'revisions', `${id}.json`);
+    }
+    /** SHA-256 hex of the content — strong enough that collisions can be
+     *  ignored for practical purposes (blob identity), cheap enough at our
+     *  scale (tens of KB per item, hundreds of items per revision). */
+    function hashContent(content) {
+        return createHash('sha256').update(content).digest('hex');
+    }
+    /**
+     * Allocate a fresh revision id. Scheme: `rev-<unixMillis>`, with a
+     * `-<seq>` suffix on same-millisecond collisions ("rev-1760...050",
+     * "rev-1760...050-2", ...). Collision tracking uses the current
+     * index's revisions list — assumes no concurrent writers against
+     * the same target (already true: Gazetta never has two admins
+     * writing the same target's history simultaneously).
+     *
+     * Why millis + suffix rather than a monotonic counter:
+     *   - Retention evictions leave you with a window of revisions you
+     *     can date-read from the filename alone.
+     *   - No counter to overflow or reset when history is disabled then
+     *     re-enabled.
+     *   - Lex-sort = chrono sort (13-digit ms are fixed-width through
+     *     year 5138 AD).
+     *
+     * `_clock` is injectable for deterministic tests — production uses
+     * Date.now(). Stays private to createHistoryProvider.
+     */
+    function formatId(existing, now) {
+        const base = `rev-${now}`;
+        if (!existing.some(id => id === base || id.startsWith(`${base}-`)))
+            return base;
+        // Same-millisecond collision: bump the suffix. Start from 2 so the
+        // first duplicate gets `-2` (matches the mental model "base, then
+        // the second, then the third").
+        let seq = 2;
+        while (existing.includes(`${base}-${seq}`))
+            seq += 1;
+        return `${base}-${seq}`;
+    }
+    /**
+     * Write any blob that's not already stored. Returns the hash. Dedup
+     * check is a single `exists()` — cheaper than reading the existing
+     * blob to confirm equal content (hashes collide vanishingly).
+     */
+    async function writeBlob(content) {
+        const hash = hashContent(content);
+        const path = blobPath(hash);
+        if (!(await storage.exists(path))) {
+            await writeWithParents(path, content);
+        }
+        return hash;
+    }
+    async function recordRevision(input) {
+        const idx = await readIndex();
+        const id = formatId(idx.revisions, Date.now());
+        // Write blobs (dedup via content-addressing) and build the
+        // path → hash snapshot.
+        const snapshot = {};
+        // Deterministic order so rev manifests diff cleanly on inspection.
+        const sortedEntries = [...input.items.entries()].sort((a, b) => a[0].localeCompare(b[0]));
+        for (const [path, content] of sortedEntries) {
+            snapshot[path] = await writeBlob(content);
+        }
+        const manifest = {
+            id,
+            timestamp: new Date().toISOString(),
+            operation: input.operation,
+            author: input.author,
+            source: input.source,
+            items: [...input.items.keys()].sort(),
+            message: input.message,
+            restoredFrom: input.restoredFrom,
+            snapshot,
+        };
+        await writeWithParents(revisionPath(id), JSON.stringify(manifest, null, 2) + '\n');
+        // Update the index (append) then apply retention. Do the index
+        // write last so a mid-write failure leaves orphan blobs and an
+        // orphan manifest (both harmless) rather than a dangling index
+        // entry pointing at a missing manifest.
+        idx.revisions.push(id);
+        await writeIndex(idx);
+        await applyRetention(idx);
+        // Return the public Revision shape (no snapshot).
+        // eslint-disable-next-line @typescript-eslint/no-unused-vars
+        const { snapshot: _snapshot, ...revision } = manifest;
+        return revision;
+    }
+    /**
+     * Evict oldest revisions to fit `retention`. Deletes manifests; blobs
+     * become eligible for GC if no remaining revision references them.
+     * GC is lazy — blob files stay until an explicit GC pass, which is
+     * fine for v1 (disk is cheap; a future `gazetta gc` command can walk
+     * all manifests and prune orphans).
+     */
+    async function applyRetention(idx) {
+        const excess = idx.revisions.length - retention;
+        if (excess <= 0)
+            return;
+        const toEvict = idx.revisions.slice(0, excess);
+        idx.revisions = idx.revisions.slice(excess);
+        for (const id of toEvict) {
+            const path = revisionPath(id);
+            if (await storage.exists(path))
+                await storage.rm(path);
+        }
+        await writeIndex(idx);
+    }
+    async function listRevisions(limit) {
+        const idx = await readIndex();
+        const ids = [...idx.revisions].reverse(); // newest first
+        const sliced = typeof limit === 'number' ? ids.slice(0, limit) : ids;
+        // Read manifests in parallel; strip snapshot for the summary list.
+        return Promise.all(sliced.map(async (id) => {
+            const m = await readManifest(id);
+            // eslint-disable-next-line @typescript-eslint/no-unused-vars
+            const { snapshot: _snapshot, ...rev } = m;
+            return rev;
+        }));
+    }
+    async function readManifest(id) {
+        return JSON.parse(await storage.readFile(revisionPath(id)));
+    }
+    async function readRevision(id) {
+        return readManifest(id);
+    }
+    async function readBlob(hash) {
+        return storage.readFile(blobPath(hash));
+    }
+    async function deleteRevision(id) {
+        const idx = await readIndex();
+        const at = idx.revisions.indexOf(id);
+        if (at === -1)
+            return;
+        idx.revisions.splice(at, 1);
+        await writeIndex(idx);
+        const path = revisionPath(id);
+        if (await storage.exists(path))
+            await storage.rm(path);
+        // Orphan blobs left for lazy GC — see applyRetention rationale.
+    }
+    return {
+        recordRevision,
+        listRevisions,
+        readRevision,
+        readBlob,
+        deleteRevision,
+    };
+}
+/**
+ * `posix.join` behavior without importing it — keeps the module self-
+ * contained and works identically across platforms. Storage providers
+ * normalize separators internally, but our stored paths are POSIX.
+ */
+function join(...parts) {
+    return parts.filter(Boolean).join('/').replace(/\/+/g, '/');
+}
+//# sourceMappingURL=history-provider.js.map

package/dist/history-provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"history-provider.js","sourceRoot":"","sources":["../src/history-provider.ts"],"names":[],"mappings":"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"}

package/dist/history-recorder.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Higher-level helper for recording revisions on a target.
+ *
+ * The bare `HistoryProvider.recordRevision` takes a full
+ * `items: Map<path, content>` snapshot. That's fine for testing but
+ * wasteful at runtime: every save of one page would re-hash and
+ * re-list every page + fragment on the target. This helper does the
+ * right thing:
+ *
+ *   - First revision on a target: walks the content tree once to
+ *     snapshot every manifest (page.json, fragment.json, site.yaml).
+ *   - Subsequent revisions: reads the previous snapshot and overlays
+ *     the delta (changed items the caller passes in). `readBlob` for
+ *     each carried-over path gives us the content for the new
+ *     revision's items map — at which point `recordRevision` dedupes
+ *     the unchanged blobs via content-addressing, so no new storage.
+ *
+ * SRP: this module owns the "what goes in a revision snapshot"
+ * decision. `HistoryProvider` owns layout. Callers (admin-api save /
+ * admin-api publish / CLI publish) just describe *what they wrote*
+ * and we construct the revision.
+ */
+import type { HistoryProvider, RevisionOperation } from './history.js';
+import type { ContentRoot } from './content-root.js';
+/** A single item that was written in this save/publish. */
+export interface WrittenItem {
+    /** Path relative to the content root, e.g. `pages/home/page.json`. */
+    path: string;
+    /** Current content as stored. `null` marks a deletion. */
+    content: string | null;
+}
+/**
+ * Location to scan when building the first revision's baseline
+ * snapshot. Each entry names a directory under the content root and
+ * the manifest filename to capture from every subdirectory.
+ */
+export interface ScanLocation {
+    /** Directory relative to the content root, e.g. `pages` or `fragments`. */
+    dir: string;
+    /** Manifest filename to capture, e.g. `page.json` or `fragment.json`. */
+    manifest: string;
+}
+/**
+ * Built-in content locations Gazetta knows about today. Callers can
+ * pass a superset (e.g. for future data/*, templates/*) — the list is
+ * part of `RecordWriteOptions` so this module stays open for extension
+ * without changes when new content kinds land.
+ */
+export declare const DEFAULT_SCAN_LOCATIONS: readonly ScanLocation[];
+/**
+ * Flat files at the content root to capture in the baseline snapshot
+ * (no per-subdirectory recursion). `site.yaml` is the only one today.
+ */
+export declare const DEFAULT_SCAN_ROOT_FILES: readonly string[];
+export interface RecordWriteOptions {
+    /** HistoryProvider for the target we're recording on. */
+    history: HistoryProvider;
+    /** Content root of the target — used to scan on first revision. */
+    contentRoot: ContentRoot;
+    operation: RevisionOperation;
+    /** Items the save/publish wrote (and optionally deleted). */
+    items: WrittenItem[];
+    /** Author identifier passed through to the manifest. */
+    author?: string;
+    /** Source target name (for publish). */
+    source?: string;
+    /** Optional human-readable note. */
+    message?: string;
+    /** For rollback/restore: the revision id this one restored from. */
+    restoredFrom?: string;
+    /**
+     * Override the directories walked during the first-revision baseline
+     * scan. Defaults to `DEFAULT_SCAN_LOCATIONS` (pages + fragments).
+     * Pass a superset if the site has extra authored content (e.g.
+     * custom `data/*.json` dirs); pass `[]` to skip directory scanning
+     * entirely (only root files + explicit items are captured).
+     */
+    scanLocations?: readonly ScanLocation[];
+    /**
+     * Override the flat files captured from the content root. Defaults
+     * to `DEFAULT_SCAN_ROOT_FILES` (`site.yaml`). Missing files are
+     * silently skipped so empty publish-targets still record cleanly.
+     */
+    scanRootFiles?: readonly string[];
+}
+/**
+ * Build + record a revision for the given write. Reads the previous
+ * snapshot (if any), overlays the delta, and calls
+ * `history.recordRevision`. Returns the recorded Revision.
+ *
+ * Callers are expected to have already written the items to the
+ * target's storage before invoking this; the recorder reads back via
+ * the HistoryProvider's dedup path (blobs it has already seen just
+ * `exists()` and skip) so the happy path is cheap on repeated saves
+ * of the same item.
+ */
+export declare function recordWrite(opts: RecordWriteOptions): Promise<import("./history.js").Revision>;
+//# sourceMappingURL=history-recorder.d.ts.map

package/dist/history-recorder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"history-recorder.d.ts","sourceRoot":"","sources":["../src/history-recorder.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAIH,OAAO,KAAK,EAAE,eAAe,EAAiB,iBAAiB,EAAE,MAAM,cAAc,CAAA;AACrF,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAA;AAEpD,2DAA2D;AAC3D,MAAM,WAAW,WAAW;IAC1B,sEAAsE;IACtE,IAAI,EAAE,MAAM,CAAA;IACZ,0DAA0D;IAC1D,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;CACvB;AAED;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B,2EAA2E;IAC3E,GAAG,EAAE,MAAM,CAAA;IACX,yEAAyE;IACzE,QAAQ,EAAE,MAAM,CAAA;CACjB;AAED;;;;;GAKG;AACH,eAAO,MAAM,sBAAsB,EAAE,SAAS,YAAY,EAGzD,CAAA;AAED;;;GAGG;AACH,eAAO,MAAM,uBAAuB,EAAE,SAAS,MAAM,EAAkB,CAAA;AAEvE,MAAM,WAAW,kBAAkB;IACjC,yDAAyD;IACzD,OAAO,EAAE,eAAe,CAAA;IACxB,mEAAmE;IACnE,WAAW,EAAE,WAAW,CAAA;IACxB,SAAS,EAAE,iBAAiB,CAAA;IAC5B,6DAA6D;IAC7D,KAAK,EAAE,WAAW,EAAE,CAAA;IACpB,wDAAwD;IACxD,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,wCAAwC;IACxC,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,oCAAoC;IACpC,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,oEAAoE;IACpE,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB;;;;;;OAMG;IACH,aAAa,CAAC,EAAE,SAAS,YAAY,EAAE,CAAA;IACvC;;;;OAIG;IACH,aAAa,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;CAClC;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,WAAW,CAAC,IAAI,EAAE,kBAAkB,4CAmCzD"}

package/dist/history-recorder.js

@@ -0,0 +1,160 @@
+/**
+ * Higher-level helper for recording revisions on a target.
+ *
+ * The bare `HistoryProvider.recordRevision` takes a full
+ * `items: Map<path, content>` snapshot. That's fine for testing but
+ * wasteful at runtime: every save of one page would re-hash and
+ * re-list every page + fragment on the target. This helper does the
+ * right thing:
+ *
+ *   - First revision on a target: walks the content tree once to
+ *     snapshot every manifest (page.json, fragment.json, site.yaml).
+ *   - Subsequent revisions: reads the previous snapshot and overlays
+ *     the delta (changed items the caller passes in). `readBlob` for
+ *     each carried-over path gives us the content for the new
+ *     revision's items map — at which point `recordRevision` dedupes
+ *     the unchanged blobs via content-addressing, so no new storage.
+ *
+ * SRP: this module owns the "what goes in a revision snapshot"
+ * decision. `HistoryProvider` owns layout. Callers (admin-api save /
+ * admin-api publish / CLI publish) just describe *what they wrote*
+ * and we construct the revision.
+ */
+import { join } from 'node:path';
+/**
+ * Built-in content locations Gazetta knows about today. Callers can
+ * pass a superset (e.g. for future data/*, templates/*) — the list is
+ * part of `RecordWriteOptions` so this module stays open for extension
+ * without changes when new content kinds land.
+ */
+export const DEFAULT_SCAN_LOCATIONS = [
+    { dir: 'pages', manifest: 'page.json' },
+    { dir: 'fragments', manifest: 'fragment.json' },
+];
+/**
+ * Flat files at the content root to capture in the baseline snapshot
+ * (no per-subdirectory recursion). `site.yaml` is the only one today.
+ */
+export const DEFAULT_SCAN_ROOT_FILES = ['site.yaml'];
+/**
+ * Build + record a revision for the given write. Reads the previous
+ * snapshot (if any), overlays the delta, and calls
+ * `history.recordRevision`. Returns the recorded Revision.
+ *
+ * Callers are expected to have already written the items to the
+ * target's storage before invoking this; the recorder reads back via
+ * the HistoryProvider's dedup path (blobs it has already seen just
+ * `exists()` and skip) so the happy path is cheap on repeated saves
+ * of the same item.
+ */
+export async function recordWrite(opts) {
+    const scanLocations = opts.scanLocations ?? DEFAULT_SCAN_LOCATIONS;
+    const scanRootFiles = opts.scanRootFiles ?? DEFAULT_SCAN_ROOT_FILES;
+    // On the very first write, record a baseline revision capturing the
+    // pre-write state — so "undo my first save" has something to revert
+    // to (the tree as it was before the CMS touched it). Subsequent
+    // writes overlay deltas onto the previous revision. Without this,
+    // rev-0001 would be post-save state and undo would have no earlier
+    // revision to restore.
+    const existing = await opts.history.listRevisions(1);
+    if (existing.length === 0) {
+        const baseline = await scanContentTree(opts.contentRoot, scanLocations, scanRootFiles);
+        await opts.history.recordRevision({
+            operation: 'save',
+            message: 'Initial baseline',
+            items: baseline,
+        });
+    }
+    const prevItems = await loadPreviousSnapshot(opts.history, opts.contentRoot, scanLocations, scanRootFiles);
+    const nextItems = new Map(prevItems);
+    for (const it of opts.items) {
+        if (it.content === null)
+            nextItems.delete(it.path);
+        else
+            nextItems.set(it.path, it.content);
+    }
+    const input = {
+        operation: opts.operation,
+        author: opts.author,
+        source: opts.source,
+        message: opts.message,
+        restoredFrom: opts.restoredFrom,
+        items: nextItems,
+    };
+    return opts.history.recordRevision(input);
+}
+/**
+ * Materialize the previous revision's full content snapshot as
+ * `path → content`. If there is no previous revision, fall back to a
+ * one-time scan of the target's content tree (pages, fragments,
+ * site.yaml). That makes the first revision a proper baseline even
+ * when history was turned on after content already existed.
+ */
+async function loadPreviousSnapshot(history, contentRoot, scanLocations, scanRootFiles) {
+    const [head] = await history.listRevisions(1);
+    if (head) {
+        const manifest = await history.readRevision(head.id);
+        const items = new Map();
+        // Read blobs in parallel to avoid a big serial chain on large snapshots.
+        const entries = Object.entries(manifest.snapshot);
+        const contents = await Promise.all(entries.map(([, hash]) => history.readBlob(hash)));
+        entries.forEach(([path], i) => items.set(path, contents[i]));
+        return items;
+    }
+    return scanContentTree(contentRoot, scanLocations, scanRootFiles);
+}
+/**
+ * One-time walk of a content root, capturing every content-defining
+ * manifest. Used only for the first revision on a target; subsequent
+ * revisions overlay deltas onto the previous snapshot.
+ *
+ * Locations walked come from `scanLocations` and `scanRootFiles` (see
+ * RecordWriteOptions) so this module stays open for extension: adding
+ * a new content kind is a caller-side change, not an edit here.
+ */
+async function scanContentTree(root, scanLocations, scanRootFiles) {
+    const items = new Map();
+    const { storage } = root;
+    for (const rel of scanRootFiles) {
+        const abs = root.path(rel);
+        if (await storage.exists(abs)) {
+            items.set(rel, await storage.readFile(abs));
+        }
+    }
+    for (const loc of scanLocations) {
+        await scanManifestsInto(storage, root.path(loc.dir), loc.dir, loc.manifest, items);
+    }
+    return items;
+}
+/**
+ * Walk a `pages/` or `fragments/` tree, reading every matching manifest
+ * into `items` with relative-path keys. Recurses so nested dynamic
+ * routes (e.g. `blog/[slug]/page.json`) are captured.
+ *
+ * Cloud object stores (R2/S3/Azure Blob) have no "directory" concept —
+ * `exists()` on a prefix-only path returns false. Rely on `readDir`
+ * returning an empty array for missing paths instead of probing via
+ * `exists` first.
+ */
+async function scanManifestsInto(storage, absDir, relPrefix, manifestName, items) {
+    let entries;
+    try {
+        entries = await storage.readDir(absDir);
+    }
+    catch {
+        return; // Directory doesn't exist (or provider threw) — nothing to scan.
+    }
+    for (const e of entries) {
+        if (!e.isDirectory)
+            continue;
+        const sub = join(absDir, e.name);
+        const relSub = `${relPrefix}/${e.name}`;
+        const manifestPath = join(sub, manifestName);
+        if (await storage.exists(manifestPath)) {
+            items.set(`${relSub}/${manifestName}`, await storage.readFile(manifestPath));
+        }
+        // Recurse for nested routes (pages/blog/[slug]/page.json).
+        await scanManifestsInto(storage, sub, relSub, manifestName, items);
+    }
+}
+//# sourceMappingURL=history-recorder.js.map

package/dist/history-recorder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"history-recorder.js","sourceRoot":"","sources":["../src/history-recorder.ts"],"names":[],"mappings":"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"}

package/dist/history-restorer.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Apply a past revision's snapshot to a target's content tree.
+ *
+ * This is the write side of undo / rollback. Design-publishing.md:
+ *   "Undo and rollback restore a prior revision — both are soft
+ *    (forward-only; create a new revision reverting to the past state,
+ *    never destroy history)."
+ *
+ * Algorithm:
+ *   1. Load the target revision's snapshot (itemPath → blob hash).
+ *   2. Diff against the current on-disk content (via the HistoryProvider's
+ *      most-recent revision). Anything present now but absent from the
+ *      target snapshot is deleted; everything in the snapshot is written
+ *      from its blob.
+ *   3. Record a new revision with operation='rollback' and
+ *      restoredFrom=<targetRevId>, so the audit trail shows where the
+ *      state came from and history stays forward-only.
+ *
+ * The caller (admin-api / CLI) owns orchestration — picking which
+ * revision to restore (head-1 for undo, arbitrary for rollback) and
+ * any side effects beyond the content tree (e.g., sidecar writer
+ * invalidation).
+ */
+import type { ContentRoot } from './content-root.js';
+import type { HistoryProvider, Revision } from './history.js';
+export interface RestoreRevisionOptions {
+    /** HistoryProvider for the target being restored. */
+    history: HistoryProvider;
+    /** Content root of the target — destination for the restore writes. */
+    contentRoot: ContentRoot;
+    /** Id of the revision to restore to (rev-NNNN). */
+    revisionId: string;
+    /** Free-form author identifier passed to the forward revision. */
+    author?: string;
+    /** Human-readable note ("Undo publish from local"). */
+    message?: string;
+}
+/**
+ * Restore `revisionId`'s content onto the target. Writes any items
+ * present in the snapshot (content fetched via `readBlob`); deletes
+ * items that exist today but aren't in the restored snapshot. Returns
+ * the new forward revision — always operation='rollback' so audit
+ * consumers can distinguish restores from normal saves/publishes.
+ */
+export declare function restoreRevision(opts: RestoreRevisionOptions): Promise<Revision>;
+//# sourceMappingURL=history-restorer.d.ts.map

package/dist/history-restorer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"history-restorer.d.ts","sourceRoot":"","sources":["../src/history-restorer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAA;AACpD,OAAO,KAAK,EAAE,eAAe,EAAE,QAAQ,EAAuC,MAAM,cAAc,CAAA;AAElG,MAAM,WAAW,sBAAsB;IACrC,qDAAqD;IACrD,OAAO,EAAE,eAAe,CAAA;IACxB,uEAAuE;IACvE,WAAW,EAAE,WAAW,CAAA;IACxB,mDAAmD;IACnD,UAAU,EAAE,MAAM,CAAA;IAClB,kEAAkE;IAClE,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,uDAAuD;IACvD,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB;AAED;;;;;;GAMG;AACH,wBAAsB,eAAe,CAAC,IAAI,EAAE,sBAAsB,GAAG,OAAO,CAAC,QAAQ,CAAC,CA6CrF"}

package/dist/history-restorer.js

@@ -0,0 +1,105 @@
+/**
+ * Apply a past revision's snapshot to a target's content tree.
+ *
+ * This is the write side of undo / rollback. Design-publishing.md:
+ *   "Undo and rollback restore a prior revision — both are soft
+ *    (forward-only; create a new revision reverting to the past state,
+ *    never destroy history)."
+ *
+ * Algorithm:
+ *   1. Load the target revision's snapshot (itemPath → blob hash).
+ *   2. Diff against the current on-disk content (via the HistoryProvider's
+ *      most-recent revision). Anything present now but absent from the
+ *      target snapshot is deleted; everything in the snapshot is written
+ *      from its blob.
+ *   3. Record a new revision with operation='rollback' and
+ *      restoredFrom=<targetRevId>, so the audit trail shows where the
+ *      state came from and history stays forward-only.
+ *
+ * The caller (admin-api / CLI) owns orchestration — picking which
+ * revision to restore (head-1 for undo, arbitrary for rollback) and
+ * any side effects beyond the content tree (e.g., sidecar writer
+ * invalidation).
+ */
+/**
+ * Restore `revisionId`'s content onto the target. Writes any items
+ * present in the snapshot (content fetched via `readBlob`); deletes
+ * items that exist today but aren't in the restored snapshot. Returns
+ * the new forward revision — always operation='rollback' so audit
+ * consumers can distinguish restores from normal saves/publishes.
+ */
+export async function restoreRevision(opts) {
+    const { history, contentRoot, revisionId } = opts;
+    const target = await history.readRevision(revisionId);
+    // Current state = the most recent revision's snapshot. If none
+    // exists yet we're restoring onto an empty tree — nothing to delete
+    // and no "unchanged" entries to skip.
+    const currentSnapshot = await loadHeadSnapshot(history);
+    const toDelete = Object.keys(currentSnapshot).filter(p => !(p in target.snapshot));
+    // Only write items whose blob hash differs from what's currently on
+    // disk (per head snapshot). Without this, restoring typically rewrites
+    // every item in the snapshot — an undo of a single-page edit would
+    // touch every page + fragment manifest, triggering a storm of file-
+    // watch events and SSE reloads in the dev server. Equal hashes →
+    // same content → skip the write.
+    const toWrite = Object.entries(target.snapshot).filter(([path, hash]) => currentSnapshot[path] !== hash);
+    // Delete first: rolling back a "delete" in the old revision means the
+    // item came back; rolling back an "add" means the item goes away.
+    // Delete-before-write keeps storage from briefly holding both.
+    for (const path of toDelete) {
+        const abs = contentRoot.path(path);
+        try {
+            await contentRoot.storage.rm(abs);
+        }
+        catch {
+            // Best-effort: a missing path at rm time is fine (already gone).
+        }
+    }
+    for (const [path, hash] of toWrite) {
+        const content = await history.readBlob(hash);
+        const abs = contentRoot.path(path);
+        const parent = abs.substring(0, abs.lastIndexOf('/'));
+        if (parent)
+            await contentRoot.storage.mkdir(parent);
+        await contentRoot.storage.writeFile(abs, content);
+    }
+    // Record a new forward revision capturing the restored state. Uses
+    // the same snapshot we just wrote — no need to re-read from disk.
+    return recordFromSnapshot(history, target, {
+        operation: 'rollback',
+        restoredFrom: revisionId,
+        author: opts.author,
+        message: opts.message,
+    });
+}
+/**
+ * Re-record an existing snapshot as a forward revision. Blobs already
+ * exist (they're the same content), so the HistoryProvider's exists()
+ * check skips the writes — cheap.
+ */
+async function recordFromSnapshot(history, target, meta) {
+    const items = new Map();
+    for (const [path, hash] of Object.entries(target.snapshot)) {
+        items.set(path, await history.readBlob(hash));
+    }
+    return history.recordRevision({
+        operation: meta.operation,
+        author: meta.author,
+        message: meta.message,
+        restoredFrom: meta.restoredFrom,
+        items,
+    });
+}
+/**
+ * Head revision's snapshot, or `{}` if there are no revisions yet.
+ * Used by restore to figure out what's currently on-disk and needs
+ * deleting when the restored revision doesn't include it.
+ */
+async function loadHeadSnapshot(history) {
+    const [head] = await history.listRevisions(1);
+    if (!head)
+        return {};
+    const m = await history.readRevision(head.id);
+    return m.snapshot;
+}
+//# sourceMappingURL=history-restorer.js.map