@minamocms/framework 0.0.0-stage → 0.10.2

package/dist/migrations/index.js

@@ -0,0 +1,83 @@
+// The current content schema version. Bumping this and adding a new
+// migrations[N] entry is the only way a content shape may change
+// (constraint 4) - never a manual edit convention.
+export const CURRENT_SCHEMA_VERSION = 7;
+// A trivial identity migration, proving the mechanism (per the build
+// plan's Phase 1 scope): no shape change, only the version bump. Safe
+// against page.schema.json's schemaVersion: { minimum: 1 } (not an
+// exact/enum check), so nothing else needs updating for this bump to
+// keep validating.
+function migrateV1ToV2(content) {
+    return { ...content, schemaVersion: 2 };
+}
+// page.schema.json now requires "type" (Phase 2 Group D, backing the
+// GET /v1/content list endpoint's type filter). Every page authored
+// before this migration is a generic page, not any newer distinct
+// kind, so "page" is a safe, honest default for existing content -
+// never invented per-file, always this one fixed value.
+function migrateV2ToV3(content) {
+    return { ...content, schemaVersion: 3, type: 'page' };
+}
+// page.schema.json now requires "layout" (theme layouts group), naming
+// which theme/layouts/*.liquid file wraps this page's rendered
+// content. Every page authored before this migration used the only
+// layout that existed at the time, so "theme" (theme/layouts/theme.liquid)
+// is the correct default, not an invented placeholder - render-page.ts's
+// own read path applies this exact same default defensively too, since
+// migrations aren't wired to run automatically anywhere yet.
+function migrateV3ToV4(content) {
+    return { ...content, schemaVersion: 4, layout: 'theme' };
+}
+// page.schema.json now requires "name" (the admin's own page tree
+// label, distinct from "title" - the same content can now be called
+// "Home Page" in the tree while still rendering a different <title>).
+// Every page authored before this migration has never had a name of
+// its own, so its existing title is the only honest default - not an
+// invented placeholder, and not the file's own path/slug, which is a
+// separate concept again. content-read.ts's listContent applies this
+// exact same title fallback defensively too, since migrations aren't
+// wired to run automatically anywhere yet.
+function migrateV4ToV5(content) {
+    const title = typeof content.title === 'string' ? content.title : '';
+    return { ...content, schemaVersion: 5, name: title };
+}
+// Folds the distinct "post" content type into "page" - author,
+// publishDate, and tags become optional fields any page may carry
+// (page.schema.json), and the post-only schema (which required them,
+// but had no "name" field at all) is retired. Ordinary pages already
+// at v5 already have "name"; this is only ever a genuine backfill for
+// a legacy content/posts/*.json file, which never had one. Mirrors the
+// admin's own backfillPageName (derivePageLabel.ts) precisely: fills
+// name from title only when name is genuinely absent, never overwrites
+// an existing one (a page's name may deliberately differ from its
+// title - migrateV4ToV5's own unconditional set was safe only because
+// no content reaching it could already have a name).
+// migration-runner.ts's runMigrationsJob is what physically relocates
+// a legacy content/posts/<slug>.json file to content/pages/blog/<slug>.json
+// alongside this shape change - this function only ever transforms
+// content, never a path.
+function migrateV5ToV6(content) {
+    if ('name' in content) {
+        return { ...content, schemaVersion: 6 };
+    }
+    const title = typeof content.title === 'string' ? content.title : '';
+    return { ...content, schemaVersion: 6, name: title };
+}
+// menu.schema.json gains an optional "name": the admin's own display
+// label for a menu, editable without touching its filename (which is
+// what themes reference it by, as menus.<filename>, so renaming the
+// file would silently empty every nav that uses it). Optional, so no
+// existing menu needs a value invented for it - the admin falls back
+// to deriving one from the filename, exactly as it always has. No
+// shape change for pages at all; only the version bump.
+function migrateV6ToV7(content) {
+    return { ...content, schemaVersion: 7 };
+}
+export const migrations = {
+    1: migrateV1ToV2,
+    2: migrateV2ToV3,
+    3: migrateV3ToV4,
+    4: migrateV4ToV5,
+    5: migrateV5ToV6,
+    6: migrateV6ToV7,
+};

package/dist/pull-site/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/pull-site/cli.js

@@ -0,0 +1,78 @@
+#!/usr/bin/env node
+import { resolve } from 'node:path';
+import { loadSiteConfig } from "../config.js";
+import { PromptCancelledError, createPrompter, normaliseSiteUrl } from "./prompts.js";
+import { PullSiteError, checkPullableSite, pullSite } from "./pull-site.js";
+const TOKEN_HELP = 'The token is the live site\'s API token (the same one the admin uses), with the "content" and "media" scopes.';
+const args = process.argv.slice(2);
+const force = args.includes('--force');
+const tokenFlag = args.indexOf('--token');
+const flagToken = tokenFlag === -1 ? undefined : args[tokenFlag + 1];
+const positional = args.filter((arg, index) => !arg.startsWith('--') && (tokenFlag === -1 || index !== tokenFlag + 1));
+// Anything not given on the command line is asked for: the address,
+// then the token (hidden). CMS_TOKEN and --token still work for
+// scripts, but either leaves the token in shell history. Output goes
+// to stderr so stdout carries only the result.
+const prompter = createPrompter(process.stdin, process.stderr);
+async function ask(question, hidden = false) {
+    try {
+        return await prompter.ask(question, { hidden });
+    }
+    catch (error) {
+        if (error instanceof PromptCancelledError) {
+            process.exit(130);
+        }
+        throw error;
+    }
+}
+const givenUrl = positional[0] ?? (await ask('Live site address: '));
+const siteUrl = normaliseSiteUrl(givenUrl);
+if (!siteUrl) {
+    console.error(givenUrl.trim() === '' ? 'No address entered.' : `"${givenUrl}" is not a web address.`);
+    console.error('Usage: npm run pull [-- <live-site-address>] [--force]');
+    process.exit(1);
+}
+// Checked before asking for the token, so a mistyped address is found
+// out without typing a token for nothing.
+try {
+    await checkPullableSite(siteUrl);
+}
+catch (error) {
+    if (error instanceof PullSiteError) {
+        console.error(error.message);
+        process.exit(1);
+    }
+    throw error;
+}
+const token = flagToken ?? process.env.CMS_TOKEN ?? (await ask(`API token for ${siteUrl} (hidden): `, true));
+if (!token) {
+    console.error('No token entered.');
+    console.error(TOKEN_HELP);
+    process.exit(1);
+}
+// Run from vhost/ (the scaffold's own "pull" script), so the site root
+// is one level up - the same relationship check-site relies on.
+const config = loadSiteConfig(resolve(process.cwd(), '..'));
+try {
+    const result = await pullSite(config, { siteUrl, token, force });
+    console.log(`Pulled from ${siteUrl}:`);
+    console.log(`  ${result.pages} pages, ${result.menus} menus, ${result.drafts} drafts, ${result.redirects} redirects`);
+    console.log(`  media: ${result.mediaDownloaded} downloaded, ${result.mediaAlreadyPresent} already here`);
+    if (result.removed.length > 0) {
+        console.log(`  removed ${result.removed.length} local files the live site doesn't have:`);
+        for (const path of result.removed) {
+            console.log(`    content/${path}`);
+        }
+    }
+    console.log('Nothing was committed. Review the changes with "git status" and "git diff" from the site folder.');
+}
+catch (error) {
+    if (error instanceof PullSiteError) {
+        console.error(error.message);
+        if (error.reason === 'unauthorised') {
+            console.error(TOKEN_HELP);
+        }
+        process.exit(1);
+    }
+    throw error;
+}

package/dist/pull-site/prompt-token.d.ts

@@ -0,0 +1,16 @@
+export interface PromptInput {
+    isTTY?: boolean;
+    setRawMode?: (mode: boolean) => unknown;
+    setEncoding: (encoding: BufferEncoding) => unknown;
+    on: (event: 'data' | 'end', listener: (chunk?: string) => void) => unknown;
+    removeAllListeners: (event: 'data' | 'end') => unknown;
+    pause: () => unknown;
+    resume: () => unknown;
+}
+export interface PromptOutput {
+    write: (text: string) => unknown;
+}
+export declare class PromptCancelledError extends Error {
+    constructor();
+}
+export declare function promptHidden(question: string, input: PromptInput, output: PromptOutput): Promise<string>;

package/dist/pull-site/prompt-token.js

@@ -0,0 +1,69 @@
+// Asks for a secret without showing it. A token typed on the command
+// line (or in CMS_TOKEN=... before it) ends up in shell history; typed
+// here, it goes nowhere but this process.
+export class PromptCancelledError extends Error {
+    constructor() {
+        super('Cancelled');
+        this.name = 'PromptCancelledError';
+    }
+}
+const CTRL_C = '\u0003';
+const CTRL_D = '\u0004';
+const BACKSPACE = new Set(['\u007f', '\b']);
+// In a terminal: raw mode, so keystrokes aren't echoed; Enter finishes,
+// Backspace deletes, Ctrl+C cancels. A pasted token arrives as one chunk
+// and is handled the same way. Without a terminal (input piped in), the
+// first line is the answer, so `echo $TOKEN | npm run pull -- <url>`
+// still works.
+export function promptHidden(question, input, output) {
+    input.setEncoding('utf8');
+    const interactive = input.isTTY === true && typeof input.setRawMode === 'function';
+    // Echo goes off before the question appears, never after: anything
+    // typed or pasted the instant the prompt shows would otherwise be
+    // echoed by the terminal in the gap (seen for real in a pty test).
+    if (interactive) {
+        input.setRawMode?.(true);
+    }
+    output.write(question);
+    return new Promise((resolve, reject) => {
+        let answer = '';
+        function finish(error) {
+            input.removeAllListeners('data');
+            input.removeAllListeners('end');
+            if (interactive) {
+                input.setRawMode?.(false);
+            }
+            input.pause();
+            output.write('\n');
+            if (error) {
+                reject(error);
+            }
+            else {
+                resolve(answer.trim());
+            }
+        }
+        input.resume();
+        input.on('data', (chunk) => {
+            for (const char of chunk ?? '') {
+                if (char === '\r' || char === '\n') {
+                    finish();
+                    return;
+                }
+                if (interactive && char === CTRL_C) {
+                    finish(new PromptCancelledError());
+                    return;
+                }
+                if (interactive && char === CTRL_D) {
+                    finish();
+                    return;
+                }
+                if (interactive && BACKSPACE.has(char)) {
+                    answer = answer.slice(0, -1);
+                    continue;
+                }
+                answer += char;
+            }
+        });
+        input.on('end', () => finish());
+    });
+}

package/dist/pull-site/prompts.d.ts

@@ -0,0 +1,22 @@
+export interface PromptInput {
+    isTTY?: boolean;
+    setRawMode?: (mode: boolean) => unknown;
+    setEncoding: (encoding: BufferEncoding) => unknown;
+    on: (event: 'data' | 'end', listener: (chunk?: string) => void) => unknown;
+    removeAllListeners: (event: 'data' | 'end') => unknown;
+    pause: () => unknown;
+    resume: () => unknown;
+}
+export interface PromptOutput {
+    write: (text: string) => unknown;
+}
+export declare class PromptCancelledError extends Error {
+    constructor();
+}
+export interface Prompter {
+    ask: (question: string, options?: {
+        hidden?: boolean;
+    }) => Promise<string>;
+}
+export declare function createPrompter(input: PromptInput, output: PromptOutput): Prompter;
+export declare function normaliseSiteUrl(value: string): string | null;

package/dist/pull-site/prompts.js

@@ -0,0 +1,127 @@
+// Asks questions on the terminal - the live site's address, then its
+// API token without showing it. A token typed on the command line (or
+// in CMS_TOKEN=... before it) ends up in shell history; typed here, it
+// goes nowhere but this process.
+export class PromptCancelledError extends Error {
+    constructor() {
+        super('Cancelled');
+        this.name = 'PromptCancelledError';
+    }
+}
+const CTRL_C = '\u0003';
+const CTRL_D = '\u0004';
+const BACKSPACE = new Set(['\u007f', '\b']);
+// One prompter per input, shared by every question, because input that
+// arrives faster than it is asked for (two piped lines in one chunk, or
+// a line typed ahead) has to be kept for the next question rather than
+// thrown away with the first answer.
+//
+// In a terminal, a hidden question switches echo off (raw mode) before
+// it is shown - never after, or anything typed or pasted the instant it
+// appears is echoed in the gap (seen for real in a pty test) - and
+// handles Enter, Backspace and Ctrl+C itself. A visible question leaves
+// the terminal's own line editing alone. Without a terminal (input
+// piped in), each line answers the next question.
+export function createPrompter(input, output) {
+    const interactive = input.isTTY === true && typeof input.setRawMode === 'function';
+    let buffered = '';
+    let ended = false;
+    input.setEncoding('utf8');
+    function ask(question, { hidden = false } = {}) {
+        const raw = interactive && hidden;
+        if (raw) {
+            input.setRawMode?.(true);
+        }
+        output.write(question);
+        return new Promise((resolve, reject) => {
+            let answer = '';
+            function finish(error) {
+                input.removeAllListeners('data');
+                input.removeAllListeners('end');
+                if (raw) {
+                    input.setRawMode?.(false);
+                    // Raw mode swallowed the Enter the terminal would have echoed.
+                    output.write('\n');
+                }
+                input.pause();
+                if (error) {
+                    reject(error);
+                }
+                else {
+                    resolve(answer.trim());
+                }
+            }
+            // Consumes characters up to the end of this answer; returns true
+            // once the answer is complete, leaving the rest buffered.
+            function consume(text) {
+                for (let index = 0; index < text.length; index += 1) {
+                    const char = text[index];
+                    if (char === '\r' || char === '\n') {
+                        // A \r\n pair ends one answer, not two.
+                        const next = index + 1;
+                        buffered = text.slice(char === '\r' && text[next] === '\n' ? next + 1 : next);
+                        finish();
+                        return true;
+                    }
+                    if (raw && char === CTRL_C) {
+                        buffered = '';
+                        finish(new PromptCancelledError());
+                        return true;
+                    }
+                    if (raw && char === CTRL_D) {
+                        buffered = text.slice(index + 1);
+                        finish();
+                        return true;
+                    }
+                    if (raw && BACKSPACE.has(char)) {
+                        answer = answer.slice(0, -1);
+                        continue;
+                    }
+                    answer += char;
+                }
+                buffered = '';
+                return false;
+            }
+            if (consume(buffered)) {
+                return;
+            }
+            if (ended) {
+                finish();
+                return;
+            }
+            input.on('data', (chunk) => {
+                consume(chunk ?? '');
+            });
+            input.on('end', () => {
+                ended = true;
+                finish();
+            });
+            input.resume();
+        });
+    }
+    return { ask };
+}
+// Accepts an address as someone would type it: "my-site.example" is
+// taken to mean https://my-site.example, but a site on this machine
+// ("localhost:3600", "127.0.0.1:3600") http://, since a local site has
+// no certificate. Returns null for anything that still isn't an http(s)
+// address.
+const LOCAL_HOST = /^(localhost|127(?:\.\d{1,3}){3}|\[::1\])(?::\d+)?(?:\/|$)/i;
+export function normaliseSiteUrl(value) {
+    const trimmed = value.trim();
+    if (trimmed === '') {
+        return null;
+    }
+    const hasScheme = /^[a-z][a-z0-9+.-]*:\/\//i.test(trimmed);
+    const withScheme = hasScheme ? trimmed : `${LOCAL_HOST.test(trimmed) ? 'http' : 'https'}://${trimmed}`;
+    try {
+        const url = new URL(withScheme);
+        if ((url.protocol !== 'https:' && url.protocol !== 'http:') || url.hostname === '') {
+            return null;
+        }
+        return url.origin;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/pull-site/pull-site.d.ts

@@ -0,0 +1,23 @@
+import type { SiteConfig } from '../config.ts';
+export type PullSiteReason = 'not-a-site' | 'unauthorised' | 'newer-schema' | 'uncommitted-changes' | 'fetch-failed' | 'unsafe-path';
+export declare class PullSiteError extends Error {
+    readonly reason: PullSiteReason;
+    constructor(reason: PullSiteReason, message: string);
+}
+export interface PullSiteOptions {
+    siteUrl: string;
+    token: string;
+    force?: boolean;
+    fetchImpl?: typeof fetch;
+}
+export interface PullSiteResult {
+    pages: number;
+    menus: number;
+    drafts: number;
+    redirects: number;
+    removed: string[];
+    mediaDownloaded: number;
+    mediaAlreadyPresent: number;
+}
+export declare function checkPullableSite(siteUrl: string, fetchImpl?: typeof fetch): Promise<void>;
+export declare function pullSite(config: SiteConfig, options: PullSiteOptions): Promise<PullSiteResult>;

package/dist/pull-site/pull-site.js

@@ -0,0 +1,211 @@
+import { execFileSync } from 'node:child_process';
+import { existsSync, mkdirSync, statSync, unlinkSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { CURRENT_SCHEMA_VERSION } from "../migrations/index.js";
+import { listFilesRecursively } from "../services/fs-walk.js";
+import { sanitisePath } from "../services/path-safety.js";
+import { serialiseRedirects } from "../services/redirects.js";
+import { rebuildIndex } from "../search/rebuild-index.js";
+export class PullSiteError extends Error {
+    reason;
+    constructor(reason, message) {
+        super(message);
+        this.name = 'PullSiteError';
+        this.reason = reason;
+    }
+}
+// Every path from the server is untrusted input that becomes a local
+// file path. Checked here for shape (a pages/ or menus/ JSON file, no
+// dot segments), then again by sanitisePath before any write.
+const CONTENT_PATH = /^(pages|menus)\/(?:[A-Za-z0-9_-][A-Za-z0-9._-]*\/)*[A-Za-z0-9_-][A-Za-z0-9._-]*\.json$/;
+const MEDIA_NAME = /^[A-Za-z0-9_-][A-Za-z0-9._-]*$/;
+function encodePath(path) {
+    return path.split('/').map(encodeURIComponent).join('/');
+}
+class RemoteSite {
+    siteUrl;
+    token;
+    fetchImpl;
+    constructor(siteUrl, token, fetchImpl) {
+        this.siteUrl = siteUrl;
+        this.token = token;
+        this.fetchImpl = fetchImpl ?? fetch;
+    }
+    url(path) {
+        return new URL(path, this.siteUrl);
+    }
+    async get(path, { auth = true, allow404 = false } = {}) {
+        let response;
+        try {
+            response = await this.fetchImpl(this.url(path), {
+                headers: auth ? { authorization: `Bearer ${this.token}` } : {},
+                signal: AbortSignal.timeout(30_000),
+            });
+        }
+        catch (error) {
+            const detail = error instanceof Error ? error.message : String(error);
+            throw new PullSiteError('fetch-failed', `Could not reach ${this.url(path).toString()}: ${detail}`);
+        }
+        if (response.status === 401 || response.status === 403) {
+            throw new PullSiteError('unauthorised', `The live site rejected the token (${response.status}). It needs the "content" and "media" scopes.`);
+        }
+        if (allow404 && response.status === 404) {
+            return null;
+        }
+        if (!response.ok) {
+            throw new PullSiteError('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 PullSiteError('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());
+    }
+}
+function hasUncommittedContentChanges(config) {
+    try {
+        const status = execFileSync('git', ['status', '--porcelain', '--', 'content'], { cwd: config.siteRoot });
+        return status.toString('utf-8').trim() !== '';
+    }
+    catch {
+        // Not a git repository (or no git): nothing to protect via git, and
+        // no way to recover what a pull overwrites - treat as changed.
+        return true;
+    }
+}
+function writeUnder(root, relativePath, bytes) {
+    mkdirSync(root, { recursive: true });
+    const target = sanitisePath(root, relativePath);
+    mkdirSync(dirname(target), { recursive: true });
+    writeFileSync(target, bytes);
+}
+// Makes this local site's content a copy of a running site's: pages,
+// menus, drafts and redirects are mirrored (local files the live site
+// doesn't have are removed), and any media file missing locally is
+// downloaded. The theme is never touched - the API doesn't serve it,
+// and it's the developer's code rather than the site's content. Nothing
+// is committed: the result is left in the working tree to review.
+//
+// Everything is fetched before anything is written, so a failure part
+// way through the content leaves the local site exactly as it was.
+// Media is downloaded last and only ever adds files, so a failure there
+// leaves the content pulled and some images still to fetch on a re-run.
+// Whether an address is a site this agent can pull from, checked
+// without a token (GET /v1/capabilities is public) - so the CLI can say
+// the address is wrong before asking for a token at all.
+export async function checkPullableSite(siteUrl, fetchImpl) {
+    const capabilities = (await new RemoteSite(siteUrl, '', fetchImpl).getJson('/v1/capabilities', { auth: false }));
+    if (typeof capabilities.agentVersion !== 'string' || typeof capabilities.contentSchemaVersion !== 'number') {
+        throw new PullSiteError('not-a-site', `${siteUrl} is not a Granite site`);
+    }
+    if (capabilities.contentSchemaVersion > CURRENT_SCHEMA_VERSION) {
+        throw new PullSiteError('newer-schema', `The live site uses content schema ${capabilities.contentSchemaVersion} (agent ${capabilities.agentVersion}), newer than this site's ${CURRENT_SCHEMA_VERSION}. Upgrade @o-a/cms-agent here first.`);
+    }
+}
+export async function pullSite(config, options) {
+    const remote = new RemoteSite(options.siteUrl, options.token, options.fetchImpl);
+    await checkPullableSite(options.siteUrl, options.fetchImpl);
+    if (!options.force && hasUncommittedContentChanges(config)) {
+        throw new PullSiteError('uncommitted-changes', 'content/ has uncommitted changes, which pulling would overwrite. Commit them first, or pass --force.');
+    }
+    // --- Fetch everything ---
+    const listed = await remote.getJson('/v1/content');
+    if (!Array.isArray(listed)) {
+        throw new PullSiteError('fetch-failed', 'GET /v1/content did not return a list');
+    }
+    const live = [];
+    const drafts = [];
+    for (const entry of listed) {
+        const path = entry.path;
+        if (typeof path !== 'string' || !CONTENT_PATH.test(path)) {
+            throw new PullSiteError('unsafe-path', `The live site listed an unexpected content path: ${JSON.stringify(path)}`);
+        }
+        const liveBytes = await remote.getBytes(`/v1/content/${encodePath(path)}`, { allow404: true });
+        if (liveBytes !== null) {
+            live.push({ path, bytes: liveBytes });
+        }
+        if (entry.hasDraft === true) {
+            const draftBytes = await remote.getBytes(`/v1/drafts/${encodePath(path)}`, { allow404: true });
+            if (draftBytes !== null) {
+                drafts.push({ path, bytes: draftBytes });
+            }
+        }
+    }
+    const redirectsBody = (await remote.getJson('/v1/redirects'));
+    const redirectEntries = Array.isArray(redirectsBody.entries) ? redirectsBody.entries : [];
+    // --- Write content (mirror) ---
+    const remoteLive = new Set(live.map((file) => file.path));
+    const remoteDrafts = new Set(drafts.map((file) => file.path));
+    const removed = [];
+    for (const local of [
+        ...listFilesRecursively(config.pagesRoot, config.contentRoot, '.json'),
+        ...listFilesRecursively(config.menusRoot, config.contentRoot, '.json'),
+    ]) {
+        if (!remoteLive.has(local)) {
+            unlinkSync(sanitisePath(config.contentRoot, local));
+            removed.push(local);
+        }
+    }
+    for (const local of listFilesRecursively(config.draftsRoot, config.draftsRoot, '.json')) {
+        if (!remoteDrafts.has(local)) {
+            unlinkSync(sanitisePath(config.draftsRoot, local));
+            removed.push(`drafts/${local}`);
+        }
+    }
+    for (const file of live) {
+        writeUnder(config.contentRoot, file.path, file.bytes);
+    }
+    for (const file of drafts) {
+        writeUnder(config.draftsRoot, file.path, file.bytes);
+    }
+    if (redirectEntries.length > 0 || existsSync(config.redirectsPath)) {
+        writeFileSync(config.redirectsPath, serialiseRedirects(redirectEntries));
+    }
+    // --- Media: download what's missing ---
+    // Names are content-addressed (a hash of the bytes), so a file that
+    // already exists locally under the same name and size is the same
+    // file. Local extras are kept: unreferenced media is harmless, and a
+    // local upload not yet on the live site shouldn't vanish.
+    const mediaList = await remote.getJson('/v1/media');
+    if (!Array.isArray(mediaList)) {
+        throw new PullSiteError('fetch-failed', 'GET /v1/media did not return a list');
+    }
+    let mediaDownloaded = 0;
+    let mediaAlreadyPresent = 0;
+    mkdirSync(config.mediaRoot, { recursive: true });
+    for (const item of mediaList) {
+        const { name, size } = item;
+        if (typeof name !== 'string' || !MEDIA_NAME.test(name)) {
+            throw new PullSiteError('unsafe-path', `The live site listed an unexpected media name: ${JSON.stringify(name)}`);
+        }
+        const target = sanitisePath(config.mediaRoot, name);
+        if (existsSync(target) && statSync(target).size === size) {
+            mediaAlreadyPresent += 1;
+            continue;
+        }
+        const bytes = await remote.getBytes(`/media/${encodeURIComponent(name)}`, { auth: false });
+        writeFileSync(target, bytes);
+        mediaDownloaded += 1;
+    }
+    // The local search index describes the content that was just
+    // replaced; rebuild it from what's on disk now.
+    await rebuildIndex(config);
+    return {
+        pages: live.filter((file) => file.path.startsWith('pages/')).length,
+        menus: live.filter((file) => file.path.startsWith('menus/')).length,
+        drafts: drafts.length,
+        redirects: redirectEntries.length,
+        removed: removed.sort(),
+        mediaDownloaded,
+        mediaAlreadyPresent,
+    };
+}

package/dist/renderer/engine.d.ts

@@ -0,0 +1,2 @@
+import { Liquid } from 'liquidjs';
+export declare function createEngine(snippets: Record<string, string>): Liquid;