@minamocms/framework 0.0.0-stage → 0.10.2

package/dist/site-sync/prompts.js

@@ -0,0 +1,237 @@
+// Asks questions on the terminal - the live site's address, then its
+// access 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;
+    // The end of input is listened for for the prompter's whole life, not
+    // only while a question waits: piped input can end between questions,
+    // and a later question must still find out rather than wait forever.
+    let onEnd = null;
+    input.setEncoding('utf8');
+    input.on('end', () => {
+        ended = true;
+        onEnd?.();
+    });
+    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');
+                onEnd = null;
+                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 ?? '');
+            });
+            onEnd = () => finish();
+            input.resume();
+        });
+    }
+    // A checkbox list. In a terminal: up/down (or k/j) to move, space to
+    // tick, Enter to confirm, Ctrl+C to cancel. Without one (piped), one
+    // line names the choices wanted ("content,theme", or "none"); an
+    // empty line keeps the defaults.
+    async function choose(question, choices) {
+        const state = choices.map((choice) => ({ ...choice, checked: choice.checked && !choice.disabled }));
+        const ticked = () => state.filter((choice) => choice.checked).map((choice) => choice.name);
+        if (!interactive) {
+            const names = state.map((choice) => choice.name).join(', ');
+            const line = (await ask(`${question} (${names}; Enter for the defaults) `)).toLowerCase();
+            if (line === '') {
+                return ticked();
+            }
+            if (line === 'none') {
+                return [];
+            }
+            const wanted = new Set(line.split(/[\s,]+/).filter(Boolean));
+            return state.filter((choice) => wanted.has(choice.name) && !choice.disabled).map((choice) => choice.name);
+        }
+        const width = Math.max(...state.map((choice) => choice.label.length));
+        let cursor = Math.max(0, state.findIndex((choice) => !choice.disabled));
+        let drawn = 0;
+        function draw() {
+            if (drawn > 0) {
+                output.write(`\u001b[${drawn}A`);
+            }
+            const lines = state.map((choice, index) => {
+                const pointer = index === cursor ? '>' : ' ';
+                const box = choice.disabled ? '[-]' : choice.checked ? '[x]' : '[ ]';
+                const detail = choice.detail ? `  (${choice.detail})` : '';
+                return `\u001b[2K${pointer} ${box} ${choice.label.padEnd(width)}${detail}\n`;
+            });
+            output.write(lines.join(''));
+            drawn = lines.length;
+        }
+        output.write(`${question}\n  (up/down to move, space to tick, Enter to go)\n`);
+        input.setRawMode?.(true);
+        output.write('\u001b[?25l');
+        draw();
+        return new Promise((resolve, reject) => {
+            function finish(error) {
+                input.removeAllListeners('data');
+                input.setRawMode?.(false);
+                output.write('\u001b[?25h');
+                input.pause();
+                if (error) {
+                    reject(error);
+                }
+                else {
+                    resolve(ticked());
+                }
+            }
+            function move(step) {
+                for (let tries = 0; tries < state.length; tries += 1) {
+                    cursor = (cursor + step + state.length) % state.length;
+                    if (!state[cursor]?.disabled) {
+                        return;
+                    }
+                }
+            }
+            input.on('data', (chunk) => {
+                const keys = splitKeys(chunk ?? '');
+                for (const key of keys) {
+                    if (key === CTRL_C) {
+                        finish(new PromptCancelledError());
+                        return;
+                    }
+                    if (key === '\r' || key === '\n') {
+                        finish();
+                        return;
+                    }
+                    if (key === '\u001b[A' || key === 'k') {
+                        move(-1);
+                    }
+                    else if (key === '\u001b[B' || key === 'j') {
+                        move(1);
+                    }
+                    else if (key === ' ') {
+                        const choice = state[cursor];
+                        if (choice && !choice.disabled) {
+                            choice.checked = !choice.checked;
+                        }
+                    }
+                }
+                draw();
+            });
+            input.resume();
+        });
+    }
+    return { ask, choose };
+}
+const ESC = '\u001b';
+// One chunk of terminal input can hold several key presses; an arrow
+// key arrives as a three-character escape sequence (ESC [ A).
+function splitKeys(text) {
+    const keys = [];
+    for (let index = 0; index < text.length; index += 1) {
+        if (text[index] === ESC && text[index + 1] === '[' && index + 2 < text.length) {
+            keys.push(text.slice(index, index + 3));
+            index += 2;
+        }
+        else {
+            keys.push(text[index]);
+        }
+    }
+    return keys;
+}
+// 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/site-sync/pull-cli.d.ts

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

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

@@ -0,0 +1,75 @@
+#!/usr/bin/env node
+import { resolve } from 'node:path';
+import { loadSiteConfig } from "../config.js";
+import { ask, chooseParts, parseSyncArgs, resolveToken, TOKEN_HELP } from "./cli-helpers.js";
+import { normaliseSiteUrl } from "./prompts.js";
+import { checkPullableSite, pullSite } from "./pull-site.js";
+import { RemoteSite, SiteSyncError } from "./remote-site.js";
+import { fetchLiveTheme } from "./theme-sync.js";
+const args = parseSyncArgs(process.argv.slice(2));
+const force = args.flags.has('--force');
+const givenUrl = args.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>] [--content] [--theme] [--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 SiteSyncError) {
+        console.error(error.message);
+        process.exit(1);
+    }
+    throw error;
+}
+const token = await resolveToken(args, siteUrl);
+// 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(), '..'));
+// Asked before anything is changed: the theme needs a token with the
+// "theme" scope, found out here with one read rather than part way in.
+const liveTheme = await fetchLiveTheme(new RemoteSite(siteUrl, token)).catch((error) => ({ unavailable: error instanceof Error ? error.message : String(error) }));
+const parts = await chooseParts(args, 'pull', {
+    content: { available: true, detail: 'pages, menus, redirects, images', checked: true },
+    theme: 'theme' in liveTheme
+        ? { available: true, detail: 'templates, styles, scripts', checked: true }
+        : { available: false, detail: liveTheme.unavailable, checked: false },
+});
+if (!parts.content && !parts.theme) {
+    console.error('Nothing chosen. Nothing was pulled.');
+    process.exit(0);
+}
+try {
+    const result = await pullSite(config, { siteUrl, token, force, parts });
+    console.log(`Pulled from ${siteUrl}:`);
+    if (result.theme) {
+        console.log(`  theme: ${result.theme.files} files, ${result.theme.downloaded} downloaded`);
+        for (const path of result.theme.removed) {
+            console.log(`    removed theme/${path} (not on the live site)`);
+        }
+    }
+    if (result.content) {
+        const content = result.content;
+        console.log(`  content: ${content.pages} pages, ${content.menus} menus, ${content.drafts} drafts, ${content.redirects} redirects`);
+        console.log(`  images: ${content.mediaDownloaded} downloaded, ${content.mediaAlreadyPresent} already here`);
+        for (const path of content.removed) {
+            console.log(`    removed content/${path} (not on the live site)`);
+        }
+    }
+    console.log('Nothing was committed. Review the changes with "git status" and "git diff" from the site folder.');
+}
+catch (error) {
+    if (error instanceof SiteSyncError) {
+        console.error(error.message);
+        if (error.reason === 'unauthorised') {
+            console.error(TOKEN_HELP);
+        }
+        process.exit(1);
+    }
+    throw error;
+}

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

@@ -0,0 +1,28 @@
+import type { SiteConfig } from '../config.ts';
+import { type ThemePullResult } from './theme-sync.ts';
+export interface SyncParts {
+    content: boolean;
+    theme: boolean;
+}
+export interface PullSiteOptions {
+    siteUrl: string;
+    token: string;
+    parts: SyncParts;
+    force?: boolean;
+    fetchImpl?: typeof fetch;
+}
+export interface PullContentResult {
+    pages: number;
+    menus: number;
+    drafts: number;
+    redirects: number;
+    removed: string[];
+    mediaDownloaded: number;
+    mediaAlreadyPresent: number;
+}
+export interface PullSiteResult {
+    content?: PullContentResult;
+    theme?: ThemePullResult;
+}
+export declare function checkPullableSite(siteUrl: string, fetchImpl?: typeof fetch): Promise<void>;
+export declare function pullSite(config: SiteConfig, options: PullSiteOptions): Promise<PullSiteResult>;

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

@@ -0,0 +1,171 @@
+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 { loadRedirects, serialiseRedirects } from "../services/redirects.js";
+import { rebuildIndex } from "../search/rebuild-index.js";
+import { PACKAGE_NAME } from "../upgrade/package-names.js";
+import { fetchLiveContent, fetchLiveMedia, readCapabilities } from "./live-content.js";
+import { RemoteSite, SiteSyncError } from "./remote-site.js";
+import { hashOf, sameRedirects, settingsHash, updateSyncRecord } from "./sync-record.js";
+import { readSiteSettings, siteSettingsPath } from "../services/site-settings.js";
+import { fetchLiveTheme, pullTheme } from "./theme-sync.js";
+function hasUncommittedChanges(config, folder) {
+    try {
+        const status = execFileSync('git', ['status', '--porcelain', '--', folder], { 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);
+}
+// Whether an address is a site this agent can pull from, checked
+// without a token - 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 readCapabilities(siteUrl, fetchImpl);
+    if (capabilities.contentSchemaVersion > CURRENT_SCHEMA_VERSION) {
+        throw new SiteSyncError('newer-schema', `The live site uses content schema ${capabilities.contentSchemaVersion} (agent ${capabilities.agentVersion}), newer than this site's ${CURRENT_SCHEMA_VERSION}. Upgrade ${PACKAGE_NAME} here first.`);
+    }
+}
+// Makes this local site a copy of a running site's, for the parts
+// chosen. Content: 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. Theme: theme/ is mirrored the same
+// way (theme-sync.ts), which needs a token with the "theme" scope.
+// 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.
+//
+// Records what was pulled (sync-record.ts), which is what lets a later
+// push tell local changes apart from ones made on the live site since.
+export async function pullSite(config, options) {
+    const remote = new RemoteSite(options.siteUrl, options.token, { fetchImpl: options.fetchImpl });
+    await checkPullableSite(options.siteUrl, options.fetchImpl);
+    const folders = ['content', 'theme'].filter((part) => options.parts[part]);
+    const dirty = options.force ? [] : folders.filter((folder) => hasUncommittedChanges(config, folder));
+    if (dirty.length > 0) {
+        throw new SiteSyncError('uncommitted-changes', `${dirty.map((folder) => `${folder}/`).join(' and ')} ${dirty.length === 1 ? 'has' : 'have'} uncommitted changes, which pulling would overwrite. Commit them first, or pass --force.`);
+    }
+    const result = {};
+    // Theme first: fetched and checked before any content is touched, so
+    // a token without the "theme" scope fails before anything changes.
+    if (options.parts.theme) {
+        const fetched = await fetchLiveTheme(remote);
+        if ('unavailable' in fetched) {
+            throw new SiteSyncError('unauthorised', `Can't pull the theme: ${fetched.unavailable}.`);
+        }
+        const live = fetched.theme;
+        result.theme = await pullTheme(config, remote, live);
+        updateSyncRecord(config, options.siteUrl, { theme: { syncedAt: new Date().toISOString(), files: Object.fromEntries(live) } });
+    }
+    if (options.parts.content) {
+        result.content = await pullContent(config, remote, options.siteUrl);
+    }
+    return result;
+}
+async function pullContent(config, remote, siteUrl) {
+    // --- Fetch everything ---
+    const { live, drafts, redirects, settings } = await fetchLiveContent(remote);
+    // --- Write content (mirror) ---
+    const removed = [];
+    for (const local of [
+        ...listFilesRecursively(config.pagesRoot, config.contentRoot, '.json'),
+        ...listFilesRecursively(config.menusRoot, config.contentRoot, '.json'),
+    ]) {
+        if (!live.has(local)) {
+            unlinkSync(sanitisePath(config.contentRoot, local));
+            removed.push(local);
+        }
+    }
+    for (const local of listFilesRecursively(config.draftsRoot, config.draftsRoot, '.json')) {
+        if (!drafts.has(local)) {
+            unlinkSync(sanitisePath(config.draftsRoot, local));
+            removed.push(`drafts/${local}`);
+        }
+    }
+    for (const [path, file] of live) {
+        writeUnder(config.contentRoot, path, file.bytes);
+    }
+    for (const [path, bytes] of drafts) {
+        writeUnder(config.draftsRoot, path, bytes);
+    }
+    // Only when they differ: rewriting identical redirects would still
+    // show as a change (the file's formatting), seen on a real pull.
+    const localRedirects = existsSync(config.redirectsPath) ? loadRedirects(config).entries : [];
+    if (!sameRedirects(localRedirects, redirects)) {
+        writeFileSync(config.redirectsPath, serialiseRedirects(redirects));
+    }
+    // Site settings, mirrored like everything else: the live site's saved
+    // values, or no settings.json when it has none saved. Left alone
+    // entirely for a live CMS older than site settings, and only rewritten
+    // when the values actually differ.
+    const settingsPath = siteSettingsPath(config);
+    if (settings !== null) {
+        if (settings.etag === null) {
+            if (existsSync(settingsPath)) {
+                unlinkSync(settingsPath);
+                removed.push('settings.json');
+            }
+        }
+        else {
+            const local = existsSync(settingsPath) ? readSiteSettings(config).settings : null;
+            if (local === null || settingsHash(local) !== settingsHash(settings.values)) {
+                writeFileSync(settingsPath, `${JSON.stringify({ schemaVersion: CURRENT_SCHEMA_VERSION, settings: settings.values }, null, 2)}\n`);
+            }
+        }
+    }
+    updateSyncRecord(config, siteUrl, {
+        content: {
+            syncedAt: new Date().toISOString(),
+            files: Object.fromEntries([...live].map(([path, file]) => [path, hashOf(file.bytes)])),
+            redirects,
+            ...(settings?.etag ? { settings: settingsHash(settings.values) } : {}),
+        },
+    });
+    // --- 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.
+    let mediaDownloaded = 0;
+    let mediaAlreadyPresent = 0;
+    mkdirSync(config.mediaRoot, { recursive: true });
+    for (const { name, size } of await fetchLiveMedia(remote)) {
+        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);
+    const paths = [...live.keys()];
+    return {
+        pages: paths.filter((path) => path.startsWith('pages/')).length,
+        menus: paths.filter((path) => path.startsWith('menus/')).length,
+        drafts: drafts.size,
+        redirects: redirects.length,
+        removed: removed.sort(),
+        mediaDownloaded,
+        mediaAlreadyPresent,
+    };
+}

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

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