@minamocms/framework 0.0.0-stage → 0.10.2

package/dist/site-sync/push-site.js

@@ -0,0 +1,376 @@
+import { execFileSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { CURRENT_SCHEMA_VERSION } from "../migrations/index.js";
+import { listFilesRecursively } from "../services/fs-walk.js";
+import { sanitisePath } from "../services/path-safety.js";
+import { loadRedirects } from "../services/redirects.js";
+import { encodePath, fetchLiveContent, fetchLiveMedia, readCapabilities } from "./live-content.js";
+import { RemoteSite, SiteSyncError } from "./remote-site.js";
+import { hashOf, readSyncRecord, sameRedirects, settingsHash, updateSyncRecord } from "./sync-record.js";
+import { readSiteSettings, siteSettingsPath } from "../services/site-settings.js";
+import { executeThemePush, fetchLiveTheme, planThemePush, readLocalTheme } from "./theme-sync.js";
+import { hashThemeFile } from "../services/theme-files.js";
+// Three versions of every page and menu: as last pulled (the record),
+// here, and on the live site now. Only a local change is pushed:
+//
+//   local same as pulled               -> nothing to push (any live edit is kept)
+//   local same as live                 -> nothing to push (already there)
+//   live changed since the pull too    -> conflict: never overwritten
+//   otherwise                          -> create, update or delete
+//
+// So a page an editor changed on the live site is never overwritten, a
+// page an editor created there is never deleted, and a page is only
+// deleted if it existed at the pull and was deleted here since. A page
+// with an unpublished draft on the live site is a conflict too: writing
+// it would replace that draft. Redirects are compared as one list the
+// same way, then turned into per-redirect operations.
+export function planPush(record, local, live, liveMedia) {
+    const changes = [];
+    const conflicts = [];
+    const paths = new Set([...Object.keys(record.files), ...local.files.keys(), ...live.live.keys()]);
+    for (const path of [...paths].sort()) {
+        const pulled = record.files[path];
+        const here = local.files.has(path) ? hashOf(local.files.get(path)) : undefined;
+        const liveFile = live.live.get(path);
+        const there = liveFile ? hashOf(liveFile.bytes) : undefined;
+        if (here === pulled || here === there) {
+            continue;
+        }
+        if (there !== pulled) {
+            conflicts.push({
+                path,
+                reason: there === undefined
+                    ? 'deleted on the live site since your last pull'
+                    : pulled === undefined
+                        ? 'created on the live site since your last pull'
+                        : 'changed on the live site since your last pull',
+            });
+            continue;
+        }
+        if (live.drafts.has(path)) {
+            conflicts.push({ path, reason: 'has unpublished draft changes on the live site' });
+            continue;
+        }
+        changes.push({ path, action: here === undefined ? 'delete' : there === undefined ? 'create' : 'update' });
+    }
+    const redirectOperations = [];
+    if (!sameRedirects(local.redirects, record.redirects) && !sameRedirects(local.redirects, live.redirects)) {
+        if (!sameRedirects(live.redirects, record.redirects)) {
+            conflicts.push({ path: 'redirects.json', reason: 'redirects changed on the live site since your last pull' });
+        }
+        else {
+            const liveByFrom = new Map(live.redirects.map((entry) => [entry.from, entry]));
+            const localByFrom = new Map(local.redirects.map((entry) => [entry.from, entry]));
+            for (const entry of live.redirects) {
+                if (!localByFrom.has(entry.from)) {
+                    redirectOperations.push({ method: 'DELETE', entry });
+                }
+            }
+            for (const entry of local.redirects) {
+                const existing = liveByFrom.get(entry.from);
+                if (!existing) {
+                    redirectOperations.push({ method: 'POST', entry });
+                }
+                else if (existing.to !== entry.to || (existing.note ?? '') !== (entry.note ?? '')) {
+                    redirectOperations.push({ method: 'PUT', entry });
+                }
+            }
+        }
+    }
+    // Only media the pushed pages actually use: local media/ can hold
+    // uploads nothing refers to, which have no business on the live site.
+    const referenced = new Set();
+    for (const change of changes) {
+        if (change.action === 'delete') {
+            continue;
+        }
+        const text = local.files.get(change.path).toString('utf-8');
+        for (const match of text.matchAll(/\/media\/([A-Za-z0-9_-][A-Za-z0-9._-]*)/g)) {
+            referenced.add(match[1]);
+        }
+    }
+    const mediaToUpload = [];
+    const mediaMissing = [];
+    for (const name of [...referenced].sort()) {
+        if (liveMedia.has(name)) {
+            continue;
+        }
+        (local.mediaNames.has(name) ? mediaToUpload : mediaMissing).push(name);
+    }
+    // Site settings: the same three-way rule, as one unit. Only ever
+    // pushed from a copy that has its own settings.json - with none, the
+    // live site's settings are left alone, never cleared - and not at all
+    // to a CMS without site settings.
+    let settings = false;
+    if (local.settings !== null && live.settings !== null) {
+        const pulledSettings = record.settings;
+        const here = settingsHash(local.settings);
+        const there = live.settings.etag === null ? undefined : settingsHash(live.settings.values);
+        if (here !== pulledSettings && here !== there) {
+            if (there !== pulledSettings) {
+                conflicts.push({ path: 'settings.json', reason: 'site settings changed on the live site since your last pull' });
+            }
+            else {
+                settings = true;
+            }
+        }
+    }
+    return { changes, conflicts, redirectOperations, mediaToUpload, mediaMissing, settings };
+}
+// --- Reading this site, and the live one ---
+function readLocalContent(config) {
+    const files = new Map();
+    for (const path of [
+        ...listFilesRecursively(config.pagesRoot, config.contentRoot, '.json'),
+        ...listFilesRecursively(config.menusRoot, config.contentRoot, '.json'),
+    ]) {
+        files.set(path, readFileSync(sanitisePath(config.contentRoot, path)));
+    }
+    const mediaNames = new Set(existsSync(config.mediaRoot) ? listFilesRecursively(config.mediaRoot, config.mediaRoot, '') : []);
+    const settings = existsSync(siteSettingsPath(config)) ? readSiteSettings(config).settings : null;
+    return { files, redirects: loadRedirects(config).entries, mediaNames, settings };
+}
+// The live site's history should say who pushed, so the author is this
+// copy's own git identity rather than anything invented.
+function readGitAuthor(config) {
+    const read = (key) => {
+        try {
+            return execFileSync('git', ['config', key], { cwd: config.siteRoot }).toString('utf-8').trim();
+        }
+        catch {
+            return '';
+        }
+    };
+    const name = read('user.name');
+    const email = read('user.email');
+    if (!name || !email) {
+        throw new SiteSyncError('no-author', 'Push records who made the change in the live site\'s history, from git: set user.name and user.email (git config --global user.name "Your Name").');
+    }
+    return { name, email };
+}
+// A first push - no pull record for a part - can't tell a change made
+// here from one made on the live site, so the live site as it is now
+// stands in for the pull: everything that differs locally is listed as
+// a create or update for the developer to check. Deletes are left out
+// entirely, since a live page (or redirect, or theme file) missing here
+// may be one an editor created. Once pushed, the record describes the
+// live site, and every later push is protected as usual.
+function withoutDeletes(plan) {
+    return {
+        ...plan,
+        changes: plan.changes.filter((change) => change.action !== 'delete'),
+        redirectOperations: plan.redirectOperations.filter((operation) => operation.method !== 'DELETE'),
+    };
+}
+export async function preparePush(config, options) {
+    const record = readSyncRecord(config);
+    if (record && record.siteUrl !== options.siteUrl) {
+        throw new SiteSyncError('different-site', `This copy was last pulled from ${record.siteUrl}, not ${options.siteUrl}. Push only goes back to the site it came from.`);
+    }
+    const capabilities = await readCapabilities(options.siteUrl, options.fetchImpl);
+    const author = readGitAuthor(config);
+    const remote = new RemoteSite(options.siteUrl, options.token, {
+        fetchImpl: options.fetchImpl,
+        sleep: options.sleep,
+        onWait: options.onWait,
+    });
+    const live = await fetchLiveContent(remote);
+    const liveMedia = new Set((await fetchLiveMedia(remote)).map((item) => item.name));
+    const local = readLocalContent(config);
+    const contentRecord = record?.content ?? {
+        syncedAt: '',
+        files: Object.fromEntries([...live.live].map(([path, file]) => [path, hashOf(file.bytes)])),
+        redirects: live.redirects,
+        ...(live.settings?.etag ? { settings: settingsHash(live.settings.values) } : {}),
+    };
+    const contentPlan = planPush(contentRecord, local, live, liveMedia);
+    const content = {
+        ready: true,
+        value: {
+            plan: record?.content ? contentPlan : withoutDeletes(contentPlan),
+            record: contentRecord,
+            firstPush: !record?.content,
+            local,
+            live,
+        },
+    };
+    let theme;
+    const fetchedTheme = await fetchLiveTheme(remote);
+    if ('unavailable' in fetchedTheme) {
+        theme = { ready: false, reason: fetchedTheme.unavailable };
+    }
+    else {
+        const localTheme = readLocalTheme(config);
+        const liveTheme = fetchedTheme.theme;
+        const pulled = record?.theme?.files ?? Object.fromEntries(liveTheme);
+        const plan = planThemePush(pulled, localTheme, liveTheme);
+        theme = {
+            ready: true,
+            value: {
+                plan: record?.theme ? plan : { ...plan, changes: plan.changes.filter((change) => change.action !== 'delete') },
+                pulled,
+                firstPush: !record?.theme,
+                local: localTheme,
+                live: liveTheme,
+            },
+        };
+    }
+    return {
+        config,
+        remote,
+        siteUrl: options.siteUrl,
+        author,
+        liveVersion: capabilities.agentVersion,
+        liveSchemaOlder: capabilities.contentSchemaVersion < CURRENT_SCHEMA_VERSION,
+        content,
+        theme,
+    };
+}
+// --- Executing a confirmed plan ---
+// An uploaded file is named "<slug>-<hash of its bytes>.<ext>" by the
+// site. Sent under its local name, the site would slug that whole name
+// and add a second hash. Sent as "<slug>.<ext>", it gets back exactly
+// the local name - same slug, same bytes, same hash - which is checked.
+function uploadName(name) {
+    return name.replace(/-[0-9a-f]{12}(\.[A-Za-z0-9]+)$/, '$1');
+}
+// What the record says about site settings after a push: what was just
+// sent; otherwise, as pulled - except on a first push, when only
+// settings this copy and the live site already agree on are recorded.
+function recordedSettings(plan, record, local, live, firstPush) {
+    if (plan.settings && local.settings !== null) {
+        return { settings: settingsHash(local.settings) };
+    }
+    if (firstPush) {
+        const agreed = local.settings !== null && live.settings?.etag && settingsHash(local.settings) === settingsHash(live.settings.values);
+        return agreed ? { settings: settingsHash(local.settings) } : {};
+    }
+    return record.settings === undefined ? {} : { settings: record.settings };
+}
+// The theme goes first: a page using a new section type can only be
+// accepted once the theme that defines it is live. Nothing at all is
+// sent while any chosen part has a conflict or missing media.
+export async function executePush(prepared, parts) {
+    const content = parts.content && prepared.content.ready ? prepared.content.value : null;
+    const theme = parts.theme && prepared.theme.ready ? prepared.theme.value : null;
+    if ((content || theme) && prepared.liveSchemaOlder) {
+        throw new SiteSyncError('older-live-schema', `The live site's CMS (${prepared.liveVersion}) uses an older content format than this copy's, and could reject what it's sent. Push the CMS upgrade first.`);
+    }
+    if ((content && (content.plan.conflicts.length > 0 || content.plan.mediaMissing.length > 0)) || (theme && theme.plan.conflicts.length > 0)) {
+        throw new SiteSyncError('conflicts', 'This push has conflicts or missing media and cannot go ahead.');
+    }
+    const result = {};
+    if (theme && theme.plan.changes.length > 0) {
+        const { warnings } = await executeThemePush(prepared.remote, theme.plan, theme.local, theme.live, prepared.author);
+        // The site stores theme files exactly as sent, so a pushed file's
+        // hash is its local one. Only pushed files move on; anything else
+        // keeps its pulled state, so a live-only edit is still recognised as
+        // one next time.
+        // As for content: on a first push, only files this copy has and the
+        // live site matches, never live-only ones.
+        const merged = theme.firstPush
+            ? Object.fromEntries(Object.entries(theme.pulled).filter(([path, hash]) => theme.local.has(path) && hashThemeFile(theme.local.get(path)) === hash))
+            : { ...theme.pulled };
+        for (const change of theme.plan.changes) {
+            if (change.action === 'delete') {
+                delete merged[change.path];
+            }
+            else {
+                merged[change.path] = hashThemeFile(theme.local.get(change.path));
+            }
+        }
+        updateSyncRecord(prepared.config, prepared.siteUrl, { theme: { syncedAt: new Date().toISOString(), files: merged } });
+        result.theme = { files: theme.plan.changes.length, warnings };
+    }
+    if (content) {
+        result.content = await executeContentPush(prepared, content);
+    }
+    return result;
+}
+// Order: media first (additive, and pages need it to exist), then every
+// page and menu change as ONE batch - draft writes, deletes and a
+// publish, which the site applies as a single commit or rolls back
+// entirely - then redirects, one commit each. Each draft write carries
+// the ETag fetched while planning, so a page an editor saves in the
+// meantime fails the whole batch rather than being overwritten.
+async function executeContentPush(prepared, prepContent) {
+    const { config, remote, author } = prepared;
+    const { plan, record, local, live, firstPush } = prepContent;
+    for (const name of plan.mediaToUpload) {
+        const bytes = readFileSync(sanitisePath(config.mediaRoot, name));
+        const result = (await remote.upload('/v1/media', uploadName(name), bytes));
+        if (result?.name !== name) {
+            throw new SiteSyncError('rejected', `The live site stored ${name} as ${String(result?.name)}, so pages referring to it would break. Nothing else was pushed.`);
+        }
+    }
+    const written = plan.changes.filter((change) => change.action !== 'delete');
+    if (plan.changes.length > 0) {
+        const operations = plan.changes.map((change) => change.action === 'delete'
+            ? { type: 'content-delete', path: change.path }
+            : {
+                type: 'draft-write',
+                path: change.path,
+                content: JSON.parse(local.files.get(change.path).toString('utf-8')),
+                expectedEtag: live.live.get(change.path)?.etag ?? 'new',
+            });
+        await remote.sendJson('POST', '/v1/batch', {
+            operations,
+            ...(written.length > 0 ? { publish: { paths: written.map((change) => change.path) } } : {}),
+            message: `Push ${plan.changes.length} change${plan.changes.length === 1 ? '' : 's'} from a local copy`,
+            author,
+        });
+    }
+    for (const operation of plan.redirectOperations) {
+        const { from, to, note } = operation.entry;
+        const verb = operation.method === 'DELETE' ? 'Remove' : operation.method === 'POST' ? 'Add' : 'Update';
+        await remote.sendJson(operation.method, '/v1/redirects', {
+            from,
+            ...(operation.method === 'DELETE' ? {} : { to, ...(note === undefined ? {} : { note }) }),
+            message: `${verb} redirect ${from} (pushed from a local copy)`,
+            author,
+        });
+    }
+    // Site settings last, one commit, against the ETag seen while
+    // planning ("*" while the live site has none saved yet).
+    if (plan.settings && local.settings !== null) {
+        await remote.sendJson('PUT', '/v1/settings', { settings: local.settings, message: 'Update site settings (pushed from a local copy)', author }, { 'if-match': live.settings?.etag ?? '*' });
+    }
+    // The record now reflects the live site for everything pushed: the
+    // bytes the site actually stored (it re-serialises a draft write),
+    // not what was sent. Anything not pushed keeps its pulled state, so a
+    // live-only edit is still recognised as one next time.
+    // On a first push, only what this copy and the live site now agree on
+    // is recorded: a live page this copy never had must stay unrecorded,
+    // or the next push would read it as deleted here and delete it there.
+    const files = firstPush
+        ? Object.fromEntries(Object.entries(record.files).filter(([path, hash]) => local.files.has(path) && hashOf(local.files.get(path)) === hash))
+        : { ...record.files };
+    for (const change of plan.changes) {
+        if (change.action === 'delete') {
+            delete files[change.path];
+            continue;
+        }
+        const stored = await remote.getBytes(`/v1/content/${encodePath(change.path)}`, { allow404: true });
+        if (stored !== null) {
+            files[change.path] = hashOf(stored);
+        }
+    }
+    updateSyncRecord(config, prepared.siteUrl, {
+        content: {
+            syncedAt: new Date().toISOString(),
+            files,
+            // On a first push, this copy's own list: live-only redirects then
+            // never read as removed here.
+            redirects: firstPush || plan.redirectOperations.length > 0 ? local.redirects : record.redirects,
+            ...recordedSettings(plan, record, local, live, firstPush),
+        },
+    });
+    return {
+        created: plan.changes.filter((change) => change.action === 'create').length,
+        updated: plan.changes.filter((change) => change.action === 'update').length,
+        deleted: plan.changes.filter((change) => change.action === 'delete').length,
+        redirects: plan.redirectOperations.length,
+        mediaUploaded: plan.mediaToUpload.length,
+        settings: plan.settings,
+    };
+}

package/dist/site-sync/remote-site.d.ts

@@ -0,0 +1,38 @@
+export type SiteSyncReason = 'not-a-site' | 'unauthorised' | 'newer-schema' | 'older-live-schema' | 'uncommitted-changes' | 'fetch-failed' | 'unsafe-path' | 'no-sync-record' | 'different-site' | 'conflicts' | 'missing-media' | 'rejected' | 'no-author';
+export declare class SiteSyncError extends Error {
+    readonly reason: SiteSyncReason;
+    constructor(reason: SiteSyncReason, message: string);
+}
+export interface RemoteSiteOptions {
+    fetchImpl?: typeof fetch;
+    sleep?: (ms: number) => Promise<void>;
+    onWait?: (seconds: number) => void;
+}
+export declare class RemoteSite {
+    readonly siteUrl: string;
+    private readonly token;
+    private readonly fetchImpl;
+    private readonly sleep;
+    private readonly onWait;
+    constructor(siteUrl: string, token: string, options?: RemoteSiteOptions);
+    private url;
+    private request;
+    get(path: string, { auth, allow404 }?: {
+        auth?: boolean | undefined;
+        allow404?: boolean | undefined;
+    }): Promise<Response | null>;
+    getJson(path: string, options?: {
+        auth?: boolean;
+    }): Promise<unknown>;
+    getBytes(path: string, options?: {
+        auth?: boolean;
+        allow404?: boolean;
+    }): Promise<Buffer | null>;
+    getFile(path: string): Promise<{
+        bytes: Buffer;
+        etag: string;
+    } | null>;
+    sendJson(method: 'POST' | 'PUT' | 'DELETE', path: string, body: unknown, headers?: Record<string, string>): Promise<unknown>;
+    upload(path: string, filename: string, bytes: Buffer): Promise<unknown>;
+    private readWriteResult;
+}

package/dist/site-sync/remote-site.js

@@ -0,0 +1,122 @@
+// A running site's /v1/ API, as pull-site and push-site talk to it.
+export class SiteSyncError extends Error {
+    reason;
+    constructor(reason, message) {
+        super(message);
+        this.name = 'SiteSyncError';
+        this.reason = reason;
+    }
+}
+// Write routes on a site are rate limited (60 a minute by default), and
+// a push can make more requests than that - one per image. A 429 is
+// waited out, not treated as a failure.
+const MAX_RATE_LIMIT_WAITS = 20;
+export class RemoteSite {
+    siteUrl;
+    token;
+    fetchImpl;
+    sleep;
+    onWait;
+    constructor(siteUrl, token, options = {}) {
+        this.siteUrl = siteUrl;
+        this.token = token;
+        this.fetchImpl = options.fetchImpl ?? fetch;
+        this.sleep = options.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+        this.onWait = options.onWait ?? (() => { });
+    }
+    url(path) {
+        return new URL(path, this.siteUrl);
+    }
+    async request(method, path, { auth = true, body, headers = {} } = {}) {
+        for (let attempt = 0;; attempt += 1) {
+            let response;
+            try {
+                response = await this.fetchImpl(this.url(path), {
+                    method,
+                    headers: { ...(auth ? { authorization: `Bearer ${this.token}` } : {}), ...headers },
+                    body,
+                    signal: AbortSignal.timeout(60_000),
+                });
+            }
+            catch (error) {
+                const detail = error instanceof Error ? error.message : String(error);
+                throw new SiteSyncError('fetch-failed', `Could not reach ${this.url(path).toString()}: ${detail}`);
+            }
+            if (response.status === 429 && attempt < MAX_RATE_LIMIT_WAITS) {
+                const seconds = Math.max(1, Number(response.headers.get('retry-after')) || 5);
+                this.onWait(seconds);
+                await this.sleep(seconds * 1000);
+                continue;
+            }
+            if (response.status === 401 || response.status === 403) {
+                throw new SiteSyncError('unauthorised', `The live site rejected the token (${response.status}). It needs the "content" and "media" scopes.`);
+            }
+            return response;
+        }
+    }
+    async get(path, { auth = true, allow404 = false } = {}) {
+        const response = await this.request('GET', path, { auth });
+        if (allow404 && response.status === 404) {
+            return null;
+        }
+        if (!response.ok) {
+            throw new SiteSyncError('fetch-failed', `GET ${path} returned ${response.status}`);
+        }
+        return response;
+    }
+    async getJson(path, options = {}) {
+        const response = await this.get(path, options);
+        try {
+            return await response.json();
+        }
+        catch {
+            throw new SiteSyncError('fetch-failed', `GET ${path} did not return JSON`);
+        }
+    }
+    async getBytes(path, options = {}) {
+        const response = await this.get(path, options);
+        return response === null ? null : Buffer.from(await response.arrayBuffer());
+    }
+    // Like getBytes, plus the ETag a later write must present as If-Match
+    // (or as a batch draft-write's expectedEtag).
+    async getFile(path) {
+        const response = await this.get(path, { allow404: true });
+        if (response === null) {
+            return null;
+        }
+        return { bytes: Buffer.from(await response.arrayBuffer()), etag: response.headers.get('etag') ?? '' };
+    }
+    // A JSON write. A refusal from the site (4xx) is reported with the
+    // site's own message: a validation failure or conflict is something
+    // the person pushing needs to read, not a status code.
+    async sendJson(method, path, body, headers = {}) {
+        const response = await this.request(method, path, {
+            body: JSON.stringify(body),
+            headers: { 'content-type': 'application/json', ...headers },
+        });
+        return this.readWriteResult(method, path, response);
+    }
+    async upload(path, filename, bytes) {
+        const form = new FormData();
+        form.append('file', new Blob([new Uint8Array(bytes)]), filename);
+        const response = await this.request('POST', path, { body: form });
+        return this.readWriteResult('POST', path, response);
+    }
+    async readWriteResult(method, path, response) {
+        const text = await response.text();
+        let parsed = null;
+        try {
+            parsed = text === '' ? null : JSON.parse(text);
+        }
+        catch {
+            parsed = null;
+        }
+        if (!response.ok) {
+            const message = parsed !== null && typeof parsed === 'object' && typeof parsed.message === 'string'
+                ? parsed.message
+                : `${method} ${path} returned ${response.status}`;
+            throw new SiteSyncError('rejected', message);
+        }
+        return parsed;
+    }
+}

package/dist/site-sync/sync-record.d.ts

@@ -0,0 +1,26 @@
+import type { SiteConfig } from '../config.ts';
+import type { RedirectEntry } from '../services/redirects.ts';
+export interface ContentRecord {
+    syncedAt: string;
+    files: Record<string, string>;
+    redirects: RedirectEntry[];
+    settings?: string;
+}
+export interface ThemeRecord {
+    syncedAt: string;
+    files: Record<string, string>;
+}
+export interface SyncRecord {
+    siteUrl: string;
+    content?: ContentRecord;
+    theme?: ThemeRecord;
+}
+export declare function hashOf(bytes: Buffer): string;
+export declare function settingsHash(values: Record<string, unknown>): string;
+export declare function readSyncRecord(config: SiteConfig): SyncRecord | null;
+export declare function updateSyncRecord(config: SiteConfig, siteUrl: string, part: {
+    content: ContentRecord;
+} | {
+    theme: ThemeRecord;
+}): void;
+export declare function sameRedirects(a: RedirectEntry[], b: RedirectEntry[]): boolean;

package/dist/site-sync/sync-record.js

@@ -0,0 +1,76 @@
+import { createHash } from 'node:crypto';
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+// Compares content, not formatting: the live site re-serialises a page
+// it is sent, so the same page reads back with different whitespace.
+// Hashing the raw bytes would make every page pushed once look changed
+// locally forever after. Anything that isn't JSON is hashed as-is.
+export function hashOf(bytes) {
+    let canonical;
+    try {
+        canonical = JSON.stringify(JSON.parse(bytes.toString('utf-8')));
+    }
+    catch {
+        return createHash('sha256').update(bytes).digest('hex');
+    }
+    return createHash('sha256').update(canonical).digest('hex');
+}
+function recordPath(config) {
+    return join(config.dataRoot, 'sync-record.json');
+}
+function isFileMap(value) {
+    return typeof value === 'object' && value !== null && Object.values(value).every((hash) => typeof hash === 'string');
+}
+// Site settings compared by content, keys in any order.
+export function settingsHash(values) {
+    const sorted = (value) => Array.isArray(value)
+        ? value.map(sorted)
+        : value !== null && typeof value === 'object'
+            ? Object.fromEntries(Object.keys(value).sort().map((key) => [key, sorted(value[key])]))
+            : value;
+    return createHash('sha256').update(JSON.stringify(sorted(values))).digest('hex');
+}
+export function readSyncRecord(config) {
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(recordPath(config), 'utf-8'));
+    }
+    catch {
+        return null;
+    }
+    if (typeof parsed.siteUrl !== 'string') {
+        return null;
+    }
+    const record = { siteUrl: parsed.siteUrl };
+    // 0.5.5 wrote content only, at the top level.
+    const content = (parsed.content ?? (parsed.files ? parsed : undefined));
+    if (content && isFileMap(content.files) && Array.isArray(content.redirects)) {
+        record.content = {
+            syncedAt: typeof content.syncedAt === 'string' ? content.syncedAt : '',
+            files: content.files,
+            redirects: content.redirects,
+            ...(typeof content.settings === 'string' ? { settings: content.settings } : {}),
+        };
+    }
+    const theme = parsed.theme;
+    if (theme && isFileMap(theme.files)) {
+        record.theme = { syncedAt: typeof theme.syncedAt === 'string' ? theme.syncedAt : '', files: theme.files };
+    }
+    return record;
+}
+// Replaces one part of the record and keeps the other - unless the
+// record is for a different site, which starts it afresh.
+export function updateSyncRecord(config, siteUrl, part) {
+    const existing = readSyncRecord(config);
+    const base = existing && existing.siteUrl === siteUrl ? existing : { siteUrl };
+    const record = { ...base, ...part };
+    mkdirSync(config.dataRoot, { recursive: true });
+    writeFileSync(recordPath(config), `${JSON.stringify(record, null, 2)}\n`);
+}
+// A redirects list compared by content, not order.
+export function sameRedirects(a, b) {
+    const key = (entries) => JSON.stringify([...entries]
+        .map((entry) => ({ from: entry.from, to: entry.to, note: entry.note ?? null }))
+        .sort((x, y) => (x.from < y.from ? -1 : x.from > y.from ? 1 : 0)));
+    return key(a) === key(b);
+}

package/dist/site-sync/theme-sync.d.ts

@@ -0,0 +1,34 @@
+import type { SiteConfig } from '../config.ts';
+import { type RemoteSite } from './remote-site.ts';
+export type LiveTheme = Map<string, string>;
+export type LiveThemeResult = {
+    theme: LiveTheme;
+} | {
+    unavailable: string;
+};
+export declare function fetchLiveTheme(remote: RemoteSite): Promise<LiveThemeResult>;
+export declare function readLocalTheme(config: SiteConfig): Map<string, Buffer>;
+export interface ThemePullResult {
+    files: number;
+    downloaded: number;
+    removed: string[];
+}
+export declare function pullTheme(config: SiteConfig, remote: RemoteSite, live: LiveTheme): Promise<ThemePullResult>;
+export interface ThemeChange {
+    path: string;
+    action: 'create' | 'update' | 'delete';
+}
+export interface ThemePlan {
+    changes: ThemeChange[];
+    conflicts: Array<{
+        path: string;
+        reason: string;
+    }>;
+}
+export declare function planThemePush(pulled: Record<string, string>, local: Map<string, Buffer>, live: LiveTheme): ThemePlan;
+export declare function executeThemePush(remote: RemoteSite, plan: ThemePlan, local: Map<string, Buffer>, live: LiveTheme, author: {
+    name: string;
+    email: string;
+}): Promise<{
+    warnings: string[];
+}>;