@minamocms/framework 0.0.0-stage → 0.10.1

package/dist/site-check/run-check.js

@@ -0,0 +1,188 @@
+import { existsSync } from 'node:fs';
+import { bootSite } from "../boot.js";
+import { renderPage } from "../renderer/render-page.js";
+import { PathSafetyError, sanitisePath } from "../services/path-safety.js";
+import { buildSitemapUrls } from "../routes/sitemap.js";
+import { urlToPagePath } from "../services/urls.js";
+import { ALLOWED_UPLOAD_EXTENSIONS } from "../media/filename.js";
+import { resolveSiteSettings } from "../services/site-settings.js";
+// Link fields declared with format "uri", JSON Schema's word and
+// Minamo's documented name before "url". Both still work, so this is a
+// suggestion, not a problem: themes drift to the one name over time.
+function uriFormatSuggestions(themeSchemas) {
+    const suggestions = [];
+    const visit = (where, schema, path) => {
+        if (!schema || typeof schema !== 'object') {
+            return;
+        }
+        const node = schema;
+        if (node.format === 'uri') {
+            suggestions.push(`${where}: "${path}" uses "format": "uri". "url" is the name to use now (both work).`);
+        }
+        for (const [name, child] of Object.entries(node.properties ?? {})) {
+            visit(where, child, path ? `${path}.${name}` : name);
+        }
+        visit(where, node.items, path ? `${path}[]` : '[]');
+    };
+    for (const [type, schema] of Object.entries(themeSchemas.sections)) {
+        visit(`Section "${type}"`, schema, '');
+    }
+    for (const [type, schema] of Object.entries(themeSchemas.blocks)) {
+        visit(`Block "${type}"`, schema, '');
+    }
+    if (themeSchemas.settings) {
+        visit('Site settings', themeSchemas.settings, '');
+    }
+    return suggestions;
+}
+// A reference this project's own theme conventions actually produce:
+// src="...", srcset="w1 480w, w2 960w" (comma-separated, each entry a
+// url then a space then a width descriptor - strip the descriptor),
+// href="...". Not a full HTML parser - matching SchemaField.tsx's own
+// "the schema surface here is narrow and flat... a library would be
+// heavier than the problem warrants" precedent for the equivalent
+// choice on the admin side.
+// poster is included deliberately: a video's poster is a real content
+// image and was not being checked at all before.
+const ATTR_PATTERN = /\b(src|href|poster|srcset)="([^"]*)"/g;
+function extractReferences(html) {
+    const refs = [];
+    for (const match of html.matchAll(ATTR_PATTERN)) {
+        const attribute = match[1] ?? '';
+        const value = match[2] ?? '';
+        if (attribute !== 'srcset') {
+            refs.push({ url: value, attribute });
+        }
+        else {
+            for (const entry of value.split(',')) {
+                const url = entry.trim().split(/\s+/)[0];
+                if (url) {
+                    refs.push({ url, attribute });
+                }
+            }
+        }
+    }
+    return refs;
+}
+// Any scheme at all that is not http(s). The previous version listed
+// data: explicitly and nothing else, so mailto: (and tel:, and anything
+// future) fell through to the static-file branch below and was reported
+// as a missing file under theme/root/, purely because the text after
+// the "@" contains a dot. One real site produced 39 such findings and
+// not one true one, which is worse than no check: it teaches whoever
+// reads the output to ignore it.
+function hasExternalScheme(ref) {
+    return ref.startsWith('//') || /^[a-z][a-z0-9+.-]*:/i.test(ref);
+}
+// A content photograph or clip, as opposed to a design asset. Keyed off
+// the same extension list the media upload route accepts, so the two
+// cannot drift; .svg is absent from it, which is what keeps an inline
+// logo or icon from being mistaken for misplaced content.
+function isUploadableMedia(path) {
+    const lower = path.toLowerCase();
+    return [...ALLOWED_UPLOAD_EXTENSIONS].some((extension) => lower.endsWith(extension));
+}
+// True for a root-relative static path that looks like a real file
+// (has a "." in its last path segment - /favicon.ico, /robots.txt),
+// as opposed to a page URL like /about or /blog/hello-world, which
+// never do. Doesn't need to be perfect - a page URL with a literal dot
+// in its own slug is vanishingly unlikely and, worst case, just gets
+// checked against the wrong bucket and reported as the wrong kind of
+// finding, never silently skipped.
+function looksLikeStaticFile(path) {
+    const lastSegment = path.split('/').pop() ?? '';
+    return lastSegment.includes('.');
+}
+// A rendered reference is theme/content-derived, not a live HTTP
+// request's own :path - but the same traversal concern still applies
+// (constraint 7), so it still goes through sanitisePath rather than a
+// bare join+existsSync. A reference that fails to sanitise (a "../"
+// escaping root) is exactly as real a finding as one that's simply
+// missing - reported the same way, not silently skipped.
+function checkStaticReference(findings, root, relativePath, originalPath, rootLabel, pageUrl) {
+    // sanitisePath realpaths its root unconditionally, so a site that has
+    // no media/, theme/assets/ or theme/root/ directory at all threw a
+    // raw ENOENT out of the whole check rather than reporting anything -
+    // the check crashing with a stack trace on exactly the sites most
+    // likely to hold a broken reference. A root that does not exist means
+    // the file underneath it does not exist either, which is an ordinary
+    // finding, not an error.
+    if (!existsSync(root)) {
+        findings.push({ kind: 'missing-asset', message: `${originalPath} does not exist under ${rootLabel}`, pageUrl });
+        return;
+    }
+    try {
+        const filePath = sanitisePath(root, relativePath);
+        if (!existsSync(filePath)) {
+            findings.push({ kind: 'missing-asset', message: `${originalPath} does not exist under ${rootLabel}`, pageUrl });
+        }
+    }
+    catch (error) {
+        if (error instanceof PathSafetyError) {
+            findings.push({ kind: 'missing-asset', message: `${originalPath} is not a safe reference under ${rootLabel} (${error.message})`, pageUrl });
+            return;
+        }
+        throw error;
+    }
+}
+// The file exists, so nothing else would ever flag it - which is
+// precisely why this needs saying. A content image outside media/ is
+// invisible to the media library, cannot be replaced by an editor, and
+// is not what the CMS manages.
+function misplacedMessage(path, where) {
+    return `${path} is a content image served from ${where} - it belongs in media/ (run \`npm run seed-media -- .. <file>\` from vhost/ and use the /media/... URL it prints)`;
+}
+export async function runSiteCheck(siteRoot) {
+    const booted = bootSite(siteRoot);
+    const findings = [];
+    for (const warning of booted.themeSchemas.warnings ?? []) {
+        findings.push({ kind: 'schema', message: warning });
+    }
+    const publishedUrls = buildSitemapUrls(booted.config);
+    const publishedUrlSet = new Set(publishedUrls);
+    for (const pageUrl of publishedUrls) {
+        // urlToPagePath's own result is relative to pagesRoot (e.g.
+        // "about.json"), but renderPage's own relativePath is relative to
+        // contentRoot - the same "pages/" prefix routes/public.ts's own
+        // toRenderPath helper adds before every one of its renderPage
+        // calls.
+        const relativePath = `pages/${urlToPagePath(pageUrl)}`;
+        let html;
+        try {
+            html = await renderPage(booted.config, booted.themeTemplates, booted.layouts, booted.engine, relativePath, 'public', resolveSiteSettings(booted.config, booted.themeSchemas));
+        }
+        catch (error) {
+            const detail = error instanceof Error ? error.message : String(error);
+            findings.push({ kind: 'render-error', message: detail, pageUrl });
+            continue;
+        }
+        for (const { url: ref, attribute } of extractReferences(html)) {
+            if (hasExternalScheme(ref)) {
+                continue;
+            }
+            const path = ref.split(/[?#]/)[0] ?? ref;
+            // Only src/srcset/poster can carry a content image. An href is a
+            // link or a favicon, and flagging those would make this useless.
+            const rendersMedia = attribute !== 'href' && isUploadableMedia(path);
+            if (path.startsWith('/media/')) {
+                checkStaticReference(findings, booted.config.mediaRoot, path.slice('/media/'.length), path, 'media/', pageUrl);
+            }
+            else if (path.startsWith('/assets/')) {
+                if (rendersMedia) {
+                    findings.push({ kind: 'misplaced-media', message: misplacedMessage(path, 'theme/assets/'), pageUrl });
+                }
+                checkStaticReference(findings, booted.config.assetsRoot, path.slice('/assets/'.length), path, 'theme/assets/', pageUrl);
+            }
+            else if (looksLikeStaticFile(path)) {
+                if (rendersMedia) {
+                    findings.push({ kind: 'misplaced-media', message: misplacedMessage(path, 'theme/root/'), pageUrl });
+                }
+                checkStaticReference(findings, booted.config.rootMirrorRoot, path.slice(1), path, 'theme/root/', pageUrl);
+            }
+            else if (path !== '' && !publishedUrlSet.has(path)) {
+                findings.push({ kind: 'broken-link', message: `${path} does not point at a published page`, pageUrl });
+            }
+        }
+    }
+    return { ok: findings.length === 0, findings, suggestions: uriFormatSuggestions(booted.themeSchemas) };
+}

package/dist/site-sync/cli-helpers.d.ts

@@ -0,0 +1,23 @@
+export interface SyncArgs {
+    positional: string[];
+    flags: Set<string>;
+    token: string | undefined;
+}
+export declare function parseSyncArgs(argv: string[]): SyncArgs;
+export declare function ask(question: string, hidden?: boolean): Promise<string>;
+export declare const TOKEN_HELP = "The token is the live site's API token (the same one the admin uses), with the \"content\" and \"media\" scopes.";
+export declare function resolveToken(args: SyncArgs, siteUrl: string): Promise<string>;
+export interface PartOption {
+    available: boolean;
+    detail: string;
+    checked: boolean;
+}
+export declare function chooseParts(args: SyncArgs, verb: 'pull' | 'push', options: {
+    content: PartOption;
+    theme: PartOption;
+    cms?: PartOption;
+}): Promise<{
+    content: boolean;
+    theme: boolean;
+    cms: boolean;
+}>;

package/dist/site-sync/cli-helpers.js

@@ -0,0 +1,75 @@
+import { PromptCancelledError, createPrompter } from "./prompts.js";
+export function parseSyncArgs(argv) {
+    const tokenFlag = argv.indexOf('--token');
+    const token = tokenFlag === -1 ? undefined : argv[tokenFlag + 1];
+    const rest = argv.filter((_, index) => tokenFlag === -1 || (index !== tokenFlag && index !== tokenFlag + 1));
+    return {
+        positional: rest.filter((arg) => !arg.startsWith('--')),
+        flags: new Set(rest.filter((arg) => arg.startsWith('--'))),
+        token,
+    };
+}
+// One prompter for the whole run (see createPrompter). Questions and
+// warnings go to stderr, so stdout carries only the result.
+const prompter = createPrompter(process.stdin, process.stderr);
+export async function ask(question, hidden = false) {
+    try {
+        return await prompter.ask(question, { hidden });
+    }
+    catch (error) {
+        if (error instanceof PromptCancelledError) {
+            process.exit(130);
+        }
+        throw error;
+    }
+}
+export const TOKEN_HELP = 'The token is the live site\'s API token (the same one the admin uses), with the "content" and "media" scopes.';
+// CMS_TOKEN and --token still work for scripts, but either leaves the
+// token in shell history; asked for, it goes nowhere.
+export async function resolveToken(args, siteUrl) {
+    const token = args.token ?? 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);
+    }
+    return token;
+}
+// Which of content and theme to include. --content and/or --theme on
+// the command line decide it outright (for scripts); otherwise a
+// checkbox list, showing what each part holds or why it can't be chosen.
+// A CMS upgrade (push only) is offered as a third choice when the CMS
+// here is newer than the live site's; --cms chooses it from a script.
+export async function chooseParts(args, verb, options) {
+    const flagged = { content: args.flags.has('--content'), theme: args.flags.has('--theme'), cms: args.flags.has('--cms') };
+    if (flagged.content || flagged.theme || flagged.cms) {
+        if (flagged.cms && !options.cms?.available) {
+            console.error(`Can't push a CMS upgrade: ${options.cms?.detail ?? 'the CMS here is not newer than the live site\'s'}.`);
+            process.exit(1);
+        }
+        for (const part of ['content', 'theme']) {
+            if (flagged[part] && !options[part].available) {
+                console.error(`Can't ${verb} the ${part}: ${options[part].detail}.`);
+                process.exit(1);
+            }
+        }
+        return flagged;
+    }
+    const choices = [
+        { name: 'content', label: 'Content', detail: options.content.detail, checked: options.content.checked, disabled: !options.content.available },
+        { name: 'theme', label: 'Theme', detail: options.theme.detail, checked: options.theme.checked, disabled: !options.theme.available },
+    ];
+    if (options.cms?.available) {
+        choices.push({ name: 'cms', label: 'CMS upgrade', detail: options.cms.detail, checked: options.cms.checked });
+    }
+    try {
+        const chosen = new Set(await prompter.choose(`What do you want to ${verb}?`, choices));
+        return { content: chosen.has('content'), theme: chosen.has('theme'), cms: chosen.has('cms') };
+    }
+    catch (error) {
+        if (error instanceof PromptCancelledError) {
+            process.exit(130);
+        }
+        throw error;
+    }
+}

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

@@ -0,0 +1,36 @@
+export type DeployMethod = {
+    kind: 'command';
+    command: string;
+} | {
+    kind: 'railway';
+} | {
+    kind: 'fly';
+} | {
+    kind: 'manual';
+};
+export interface DeployDeps {
+    succeeds: (program: string, args: string[], cwd: string) => boolean;
+    exists: (path: string) => boolean;
+    readText: (path: string) => string;
+}
+export declare const defaultDeployDeps: DeployDeps;
+export declare function detectDeployMethod(siteRoot: string, deps?: DeployDeps): DeployMethod;
+export declare function deployedVersionProblem(siteRoot: string, installedVersion: string, deps?: Pick<DeployDeps, 'readText'>): string | null;
+export declare function describeDeployMethod(method: DeployMethod): string;
+export declare function runDeploy(method: Exclude<DeployMethod, {
+    kind: 'manual';
+}>, siteRoot: string): boolean;
+export interface WaitOptions {
+    fetchImpl?: typeof fetch;
+    sleep?: (ms: number) => Promise<void>;
+    intervalMs?: number;
+    timeoutMs?: number;
+    onPoll?: (seen: string | null) => void;
+}
+export declare function waitForLiveVersion(siteUrl: string, version: string, options?: WaitOptions): Promise<{
+    ok: true;
+} | {
+    ok: false;
+    lastSeen: string | null;
+    reason: string;
+}>;

package/dist/site-sync/deploy.js

@@ -0,0 +1,124 @@
+import { execFileSync, spawnSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { PACKAGE_NAME, requestedVersion } from "../upgrade/package-names.js";
+import { readCapabilities } from "./live-content.js";
+export const defaultDeployDeps = {
+    succeeds: (program, args, cwd) => {
+        try {
+            execFileSync(program, args, { cwd, stdio: 'ignore' });
+            return true;
+        }
+        catch {
+            return false;
+        }
+    },
+    exists: existsSync,
+    readText: (path) => readFileSync(path, 'utf-8'),
+};
+// In order: the site's own vhost/deploy.json (set once, for any host -
+// "git push", an ssh command...), then a site linked to Railway, then
+// one set up for Fly, and otherwise the developer deploys by hand.
+export function detectDeployMethod(siteRoot, deps = defaultDeployDeps) {
+    const deployJson = join(siteRoot, 'vhost', 'deploy.json');
+    if (deps.exists(deployJson)) {
+        let parsed;
+        try {
+            parsed = JSON.parse(deps.readText(deployJson));
+        }
+        catch {
+            throw new Error('vhost/deploy.json is not valid JSON. It should look like { "command": "git push" }.');
+        }
+        const command = parsed?.command;
+        if (typeof command !== 'string' || command.trim() === '') {
+            throw new Error('vhost/deploy.json needs a "command", for example { "command": "git push" }.');
+        }
+        return { kind: 'command', command };
+    }
+    if (deps.succeeds('railway', ['status'], siteRoot)) {
+        return { kind: 'railway' };
+    }
+    if (deps.exists(join(siteRoot, 'fly.toml')) && deps.succeeds('fly', ['version'], siteRoot)) {
+        return { kind: 'fly' };
+    }
+    return { kind: 'manual' };
+}
+// A deploy builds the CMS version vhost/package.json names, not the one
+// installed here - so if the two disagree (package.json put back after
+// an upgrade, seen on a real site), the live site comes back on the old
+// version and push waits in vain. Returns what's wrong, or null. Only an
+// exact version is checked: a range or a local link can't be judged
+// from here, and the scaffold always pins one.
+export function deployedVersionProblem(siteRoot, installedVersion, deps = defaultDeployDeps) {
+    let wanted;
+    try {
+        wanted = requestedVersion(JSON.parse(deps.readText(join(siteRoot, 'vhost', 'package.json'))).dependencies);
+    }
+    catch {
+        return null;
+    }
+    if (typeof wanted !== 'string' || !/^\d+\.\d+\.\d+$/.test(wanted) || wanted === installedVersion) {
+        return null;
+    }
+    return `vhost/package.json asks for CMS ${wanted}, but ${installedVersion} is installed here. A deploy builds what package.json asks for, so the live site would stay on ${wanted}. Set "${PACKAGE_NAME}" to "${installedVersion}" in vhost/package.json (or run npm run upgrade again), then push.`;
+}
+export function describeDeployMethod(method) {
+    switch (method.kind) {
+        case 'command':
+            return `the command in vhost/deploy.json (${method.command})`;
+        case 'railway':
+            return 'Railway (railway up)';
+        case 'fly':
+            return 'Fly.io (fly deploy)';
+        case 'manual':
+            return 'you, with your host\'s usual deploy command';
+    }
+}
+// Runs the deploy, showing its own output. Returns false if it failed.
+// Manual deploys are handled by the caller (it has to ask).
+export function runDeploy(method, siteRoot) {
+    const result = method.kind === 'command'
+        ? spawnSync(method.command, { cwd: siteRoot, stdio: 'inherit', shell: true })
+        : method.kind === 'railway'
+            ? spawnSync('railway', ['up', '--no-gitignore', '--ci'], { cwd: siteRoot, stdio: 'inherit' })
+            : spawnSync('fly', ['deploy', '--dockerfile', 'vhost/Dockerfile'], { cwd: siteRoot, stdio: 'inherit' });
+    return result.status === 0;
+}
+// Waits for the live site to report the new version, then checks its
+// home page loads. Returns what was last seen if it never got there.
+export async function waitForLiveVersion(siteUrl, version, options = {}) {
+    const sleep = options.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+    const intervalMs = options.intervalMs ?? 5_000;
+    const timeoutMs = options.timeoutMs ?? 10 * 60_000;
+    const fetchImpl = options.fetchImpl ?? fetch;
+    let lastSeen = null;
+    for (let waited = 0; waited <= timeoutMs; waited += intervalMs) {
+        try {
+            lastSeen = (await readCapabilities(siteUrl, fetchImpl)).agentVersion;
+        }
+        catch {
+            // Restarting: not answering yet is expected.
+            lastSeen = null;
+        }
+        options.onPoll?.(lastSeen);
+        if (lastSeen === version) {
+            try {
+                const home = await fetchImpl(new URL('/', siteUrl), { signal: AbortSignal.timeout(30_000) });
+                if (home.ok) {
+                    return { ok: true };
+                }
+                return { ok: false, lastSeen, reason: `the live site is on ${version}, but its home page returned ${home.status}` };
+            }
+            catch (error) {
+                const detail = error instanceof Error ? error.message : String(error);
+                return { ok: false, lastSeen, reason: `the live site is on ${version}, but its home page didn't load (${detail})` };
+            }
+        }
+        await sleep(intervalMs);
+    }
+    return {
+        ok: false,
+        lastSeen,
+        reason: lastSeen === null ? 'the live site stopped answering' : `the live site is still on ${lastSeen}`,
+    };
+}

package/dist/site-sync/live-content.d.ts

@@ -0,0 +1,30 @@
+import type { RedirectEntry } from '../services/redirects.ts';
+import { RemoteSite } from './remote-site.ts';
+export declare const CONTENT_PATH: RegExp;
+export declare const MEDIA_NAME: RegExp;
+export declare function encodePath(path: string): string;
+export interface SiteCapabilities {
+    agentVersion: string;
+    contentSchemaVersion: number;
+}
+export declare function readCapabilities(siteUrl: string, fetchImpl?: typeof fetch): Promise<SiteCapabilities>;
+export interface LiveFile {
+    bytes: Buffer;
+    etag: string;
+}
+export interface LiveSettings {
+    values: Record<string, unknown>;
+    etag: string | null;
+}
+export interface LiveContent {
+    live: Map<string, LiveFile>;
+    drafts: Map<string, Buffer>;
+    redirects: RedirectEntry[];
+    settings: LiveSettings | null;
+}
+export declare function fetchLiveContent(remote: RemoteSite): Promise<LiveContent>;
+export interface LiveMediaItem {
+    name: string;
+    size: number;
+}
+export declare function fetchLiveMedia(remote: RemoteSite): Promise<LiveMediaItem[]>;

package/dist/site-sync/live-content.js

@@ -0,0 +1,68 @@
+import { RemoteSite, SiteSyncError } from "./remote-site.js";
+// Every path from the server is untrusted input that becomes a local
+// file path (pull) or is compared against one (push). Checked here for
+// shape - a pages/ or menus/ JSON file, no dot segments; a flat media
+// name - and again by sanitisePath before any local write.
+export const CONTENT_PATH = /^(pages|menus)\/(?:[A-Za-z0-9_-][A-Za-z0-9._-]*\/)*[A-Za-z0-9_-][A-Za-z0-9._-]*\.json$/;
+export const MEDIA_NAME = /^[A-Za-z0-9_-][A-Za-z0-9._-]*$/;
+export function encodePath(path) {
+    return path.split('/').map(encodeURIComponent).join('/');
+}
+// GET /v1/capabilities is public, so an address can be checked before a
+// token is asked for.
+export async function readCapabilities(siteUrl, fetchImpl) {
+    const body = (await new RemoteSite(siteUrl, '', { fetchImpl }).getJson('/v1/capabilities', { auth: false }));
+    if (typeof body.agentVersion !== 'string' || typeof body.contentSchemaVersion !== 'number') {
+        throw new SiteSyncError('not-a-site', `${siteUrl} is not a Minamo site`);
+    }
+    return { agentVersion: body.agentVersion, contentSchemaVersion: body.contentSchemaVersion };
+}
+export async function fetchLiveContent(remote) {
+    const listed = await remote.getJson('/v1/content');
+    if (!Array.isArray(listed)) {
+        throw new SiteSyncError('fetch-failed', 'GET /v1/content did not return a list');
+    }
+    const live = new Map();
+    const drafts = new Map();
+    for (const entry of listed) {
+        const path = entry.path;
+        if (typeof path !== 'string' || !CONTENT_PATH.test(path)) {
+            throw new SiteSyncError('unsafe-path', `The live site listed an unexpected content path: ${JSON.stringify(path)}`);
+        }
+        const file = await remote.getFile(`/v1/content/${encodePath(path)}`);
+        if (file !== null) {
+            live.set(path, file);
+        }
+        if (entry.hasDraft === true) {
+            const draft = await remote.getBytes(`/v1/drafts/${encodePath(path)}`, { allow404: true });
+            if (draft !== null) {
+                drafts.set(path, draft);
+            }
+        }
+    }
+    const redirectsBody = (await remote.getJson('/v1/redirects'));
+    const redirects = Array.isArray(redirectsBody.entries) ? redirectsBody.entries : [];
+    let settings = null;
+    const settingsResponse = await remote.get('/v1/settings', { allow404: true });
+    if (settingsResponse !== null) {
+        const body = (await settingsResponse.json().catch(() => null));
+        if (!body || typeof body.settings !== 'object' || body.settings === null || Array.isArray(body.settings)) {
+            throw new SiteSyncError('fetch-failed', 'GET /v1/settings did not return settings');
+        }
+        settings = { values: body.settings, etag: settingsResponse.headers.get('etag') };
+    }
+    return { live, drafts, redirects, settings };
+}
+export async function fetchLiveMedia(remote) {
+    const listed = await remote.getJson('/v1/media');
+    if (!Array.isArray(listed)) {
+        throw new SiteSyncError('fetch-failed', 'GET /v1/media did not return a list');
+    }
+    return listed.map((item) => {
+        const { name, size } = item;
+        if (typeof name !== 'string' || !MEDIA_NAME.test(name)) {
+            throw new SiteSyncError('unsafe-path', `The live site listed an unexpected media name: ${JSON.stringify(name)}`);
+        }
+        return { name, size: typeof size === 'number' ? size : -1 };
+    });
+}

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

@@ -0,0 +1,30 @@
+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 Choice {
+    name: string;
+    label: string;
+    detail?: string;
+    checked: boolean;
+    disabled?: boolean;
+}
+export interface Prompter {
+    ask: (question: string, options?: {
+        hidden?: boolean;
+    }) => Promise<string>;
+    choose: (question: string, choices: Choice[]) => Promise<string[]>;
+}
+export declare function createPrompter(input: PromptInput, output: PromptOutput): Prompter;
+export declare function normaliseSiteUrl(value: string): string | null;