@materializecms/cli 0.0.0-stage → 0.1.0

package/src/supervisor.d.ts

@@ -0,0 +1,29 @@
+/** Exit code with which the server asks to be started again (and to apply a pending swap). */
+export declare const RESTART = 75;
+export declare const updatesDir: (site: string) => string;
+/** Written by the server before it exits with RESTART. */
+export interface Pending {
+    kind: 'install' | 'rollback';
+    from: string;
+    to: string;
+    at: string;
+}
+/** What the last swap did, read by the panel after the restart. */
+export interface SwapResult {
+    ok: boolean;
+    kind: Pending['kind'];
+    from: string;
+    to: string;
+    at: string;
+    message?: string;
+}
+/** Exchanges node_modules and the package files of the site with those kept in `other`. */
+export declare function exchange(site: string, other: string): Promise<void>;
+/**
+ * Applies a pending swap. An install moves the new version in and keeps the current one as
+ * "previous"; a rollback exchanges current and previous, so it can itself be undone.
+ */
+export declare function applyPending(site: string, pending: Pending): Promise<void>;
+/** Undoes `applyPending` after a failed start. */
+export declare function revertPending(site: string, pending: Pending): Promise<void>;
+export declare function supervise(script: string, args: string[], site?: string): Promise<never>;

package/src/supervisor.js

@@ -0,0 +1,169 @@
+/**
+ * `materialize start` runs the server as a child of this small process, which keeps it alive:
+ * it restarts the server if it stops unexpectedly, and swaps the installed version when the
+ * panel asks for an update (or to go back to the previous one).
+ *
+ * The swap: an update is installed beside the site in .materialize/updates/next, then the server
+ * exits with RESTART. Here the current node_modules moves to .materialize/updates/previous, the
+ * new one takes its place, and the server starts again. If it does not report ready in time,
+ * the old version comes back.
+ *
+ * Only Node's own modules here: this code stays loaded while the packages under it change.
+ */
+import { fork } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { mkdir, readFile, rename, rm, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+/** Exit code with which the server asks to be started again (and to apply a pending swap). */
+export const RESTART = 75;
+/** How long a freshly swapped version has to report ready before it is rolled back. */
+const READY_TIMEOUT = 180_000;
+export const updatesDir = (site) => join(site, '.materialize', 'updates');
+const FILES = ['package.json', 'package-lock.json'];
+/** Exchanges node_modules and the package files of the site with those kept in `other`. */
+export async function exchange(site, other) {
+    const tmp = join(updatesDir(site), 'swap');
+    await rm(tmp, { recursive: true, force: true });
+    await mkdir(tmp, { recursive: true });
+    // site → tmp, other → site, tmp → other: each step is a rename on the same disk.
+    for (const name of ['node_modules', ...FILES]) {
+        if (existsSync(join(site, name)))
+            await rename(join(site, name), join(tmp, name));
+    }
+    for (const name of ['node_modules', ...FILES]) {
+        if (existsSync(join(other, name)))
+            await rename(join(other, name), join(site, name));
+    }
+    await rm(other, { recursive: true, force: true });
+    await rename(tmp, other);
+}
+/**
+ * Applies a pending swap. An install moves the new version in and keeps the current one as
+ * "previous"; a rollback exchanges current and previous, so it can itself be undone.
+ */
+export async function applyPending(site, pending) {
+    const dir = updatesDir(site);
+    if (pending.kind === 'install') {
+        const next = join(dir, 'next');
+        if (!existsSync(join(next, 'node_modules')))
+            throw new Error('La nuova versione non è stata scaricata');
+        await exchange(site, next);
+        await rm(join(dir, 'previous'), { recursive: true, force: true });
+        await rename(next, join(dir, 'previous'));
+    }
+    else {
+        const previous = join(dir, 'previous');
+        if (!existsSync(join(previous, 'node_modules')))
+            throw new Error('Non c’è una versione precedente');
+        await exchange(site, previous);
+    }
+}
+/** Undoes `applyPending` after a failed start. */
+export async function revertPending(site, pending) {
+    const dir = updatesDir(site);
+    // Either way the version that was running before sits in "previous" now.
+    await exchange(site, join(dir, 'previous'));
+    // A failed new version is not one to go back to.
+    if (pending.kind === 'install')
+        await rm(join(dir, 'previous'), { recursive: true, force: true });
+}
+async function readJson(file) {
+    try {
+        return JSON.parse(await readFile(file, 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+export async function supervise(script, args, site = process.cwd()) {
+    const dir = updatesDir(site);
+    let child = null;
+    let stopping = false;
+    let failures = 0;
+    /** Starts the server; resolves with its exit code, and calls `onReady` when it reports ready. */
+    const start = (onReady, onFailed, update) => new Promise((resolve) => {
+        const proc = fork(script, ['start', ...args], {
+            stdio: 'inherit',
+            // A server started for an update says so in the panel until it is ready, then records the result.
+            env: { ...process.env, MATERIALIZE_SUPERVISED: '1', MATERIALIZE_UPDATE: update ? JSON.stringify(update) : '' },
+        });
+        child = proc;
+        proc.on('message', (message) => {
+            if (message === 'ready')
+                onReady?.();
+            else if (message === 'failed')
+                onFailed?.();
+        });
+        proc.on('exit', (code, signal) => {
+            child = null;
+            resolve(code ?? (signal ? 1 : 0));
+        });
+    });
+    const stop = (signal) => {
+        stopping = true;
+        if (child)
+            child.kill(signal);
+        else
+            process.exit(0);
+    };
+    process.on('SIGINT', () => stop('SIGINT'));
+    process.on('SIGTERM', () => stop('SIGTERM'));
+    for (;;) {
+        const pendingFile = join(dir, 'pending.json');
+        const pending = await readJson(pendingFile);
+        let code;
+        if (pending) {
+            await rm(pendingFile, { force: true });
+            const result = { ok: false, kind: pending.kind, from: pending.from, to: pending.to, at: pending.at };
+            try {
+                await applyPending(site, pending);
+            }
+            catch (error) {
+                result.message = error instanceof Error ? error.message : String(error);
+                await writeFile(join(dir, 'result.json'), JSON.stringify(result));
+                continue;
+            }
+            console.log(`  Materialize ${pending.from} → ${pending.to}: avvio la ${pending.to}…`);
+            // The new version must report ready in time; otherwise the old one comes back.
+            let ready = false;
+            let timer;
+            const running = start(() => {
+                ready = true;
+                clearTimeout(timer);
+            }, () => {
+                result.message = 'Con la nuova versione il sito non si compila';
+                child?.kill('SIGTERM');
+            }, pending);
+            timer = setTimeout(() => {
+                result.message = 'La nuova versione non è partita in tempo';
+                child?.kill('SIGTERM');
+            }, READY_TIMEOUT);
+            code = await running;
+            clearTimeout(timer);
+            if (!ready && !stopping) {
+                result.message ??= `La nuova versione si è fermata all’avvio (codice ${code})`;
+                await revertPending(site, pending);
+                await writeFile(join(dir, 'result.json'), JSON.stringify(result));
+                console.log(`  ✗ ${result.message}: torno alla ${pending.from}`);
+                continue;
+            }
+        }
+        else {
+            const started = Date.now();
+            code = await start(() => {
+                failures = 0;
+            });
+            if (Date.now() - started > 60_000)
+                failures = 0;
+        }
+        if (stopping || code === 0)
+            process.exit(code);
+        if (code === RESTART)
+            continue;
+        // An unexpected stop: start again, waiting a little longer each time (up to half a minute).
+        failures++;
+        const wait = Math.min(30, 2 ** Math.min(failures, 5));
+        console.log(`  ✗ Il server si è fermato (codice ${code}): riparto tra ${wait} s`);
+        await new Promise((r) => setTimeout(r, wait * 1000));
+    }
+}

package/src/updates.d.ts

@@ -0,0 +1,14 @@
+import { type Updates } from '@materializecms/server';
+/**
+ * Updates for a site run by `materialize start`: the new version is installed in
+ * .materialize/updates/next while the site keeps running; then the server exits and the
+ * supervisor swaps it in (see supervisor.ts).
+ */
+export declare function createUpdates(options: {
+    site: string;
+    mode: 'dev' | 'start';
+    /** Closes the server and exits with RESTART. */
+    restart: () => Promise<void>;
+}): Updates & {
+    ready: () => Promise<void>;
+};

package/src/updates.js

@@ -0,0 +1,169 @@
+import { spawn } from 'node:child_process';
+import { constants, existsSync, realpathSync } from 'node:fs';
+import { access, copyFile, mkdir, readFile, rm, writeFile } from 'node:fs/promises';
+import { createRequire } from 'node:module';
+import { join, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { newer } from '@materializecms/server';
+import { updatesDir } from './supervisor.js';
+const CURRENT = createRequire(import.meta.url)('../package.json').version;
+const CLI = '@materializecms/cli';
+/** Runs the site's package manager; resolves with its output, rejects with the end of it. */
+function npm(args, cwd, timeout = 600_000) {
+    return new Promise((resolve, reject) => {
+        const child = spawn(process.platform === 'win32' ? 'npm.cmd' : 'npm', args, {
+            cwd,
+            env: { ...process.env, npm_config_update_notifier: 'false', npm_config_fund: 'false' },
+            stdio: ['ignore', 'pipe', 'pipe'],
+            timeout,
+        });
+        let out = '';
+        child.stdout.on('data', (d) => (out += d));
+        child.stderr.on('data', (d) => (out += d));
+        child.on('error', (error) => reject(Object.assign(new Error(`npm non si avvia: ${error.message}`), { log: out.slice(-4000) })));
+        child.on('close', (code) => {
+            if (code === 0)
+                resolve(out);
+            else
+                reject(Object.assign(new Error(`npm si è fermato con un errore (codice ${code})`), { log: out.slice(-4000) }));
+        });
+    });
+}
+const readJson = async (file) => JSON.parse(await readFile(file, 'utf8').catch(() => 'null'));
+/**
+ * Updates for a site run by `materialize start`: the new version is installed in
+ * .materialize/updates/next while the site keeps running; then the server exits and the
+ * supervisor swaps it in (see supervisor.ts).
+ */
+export function createUpdates(options) {
+    const { site } = options;
+    const dir = updatesDir(site);
+    // Started by the supervisor right after a swap: not done until the site is built on it.
+    let swapping = process.env.MATERIALIZE_UPDATE ? JSON.parse(process.env.MATERIALIZE_UPDATE) : null;
+    let latest = null;
+    let notes = [];
+    let checkedAt = null;
+    let checkError;
+    let job = { state: 'idle' };
+    const unavailable = async () => {
+        if (options.mode === 'dev')
+            return 'In sviluppo (materialize dev) si aggiorna da terminale: gli aggiornamenti dal pannello funzionano con materialize start.';
+        if (!process.env.MATERIALIZE_SUPERVISED)
+            return 'Il server è avviato senza il suo supervisore: aggiorna da terminale, oppure avvialo con materialize start.';
+        // Linked from a source checkout (like the example in the repository): git updates it.
+        const here = realpathSync(fileURLToPath(import.meta.url));
+        if (!here.startsWith(realpathSync(join(site, 'node_modules')) + sep))
+            return 'Materialize è collegato dal codice sorgente: si aggiorna con git.';
+        const pkg = await readJson(join(site, 'package.json'));
+        if (!pkg?.dependencies?.[CLI])
+            return `Il package.json del sito non ha ${CLI} tra le dipendenze.`;
+        try {
+            await access(site, constants.W_OK);
+            await access(join(site, 'node_modules'), constants.W_OK);
+        }
+        catch {
+            return 'Il programma non può scrivere nella cartella del sito: aggiorna da terminale, con l’utente che la possiede.';
+        }
+        return undefined;
+    };
+    const previous = async () => {
+        const pkg = await readJson(join(dir, 'previous', 'package.json'));
+        return existsSync(join(dir, 'previous', 'node_modules')) ? (pkg?.dependencies?.[CLI] ?? null) : null;
+    };
+    const status = async () => ({
+        current: CURRENT,
+        latest,
+        notes,
+        checkedAt,
+        checkError,
+        unavailable: await unavailable(),
+        previous: await previous(),
+        job: swapping ? { state: 'restarting', step: 'Preparo il sito con la nuova versione' } : job,
+        last: await readJson(join(dir, 'result.json')),
+    });
+    const restartWith = async (pending) => {
+        await writeFile(join(dir, 'pending.json'), JSON.stringify(pending));
+        job = { state: 'restarting', step: 'Riavvio' };
+        // A moment for the panel to hear back before the server goes away.
+        setTimeout(() => void options.restart(), 300);
+    };
+    return {
+        status,
+        /** The server is up and the site built: a swap that brought it here went well. */
+        async ready() {
+            if (!swapping)
+                return;
+            const result = { ok: true, ...swapping };
+            await writeFile(join(dir, 'result.json'), JSON.stringify(result));
+            swapping = null;
+        },
+        async check() {
+            try {
+                const out = await npm(['view', `${CLI}@latest`, 'version', 'changelog', '--json'], site, 30_000);
+                const info = JSON.parse(out);
+                latest = typeof info === 'string' ? info : (info.version ?? null);
+                notes = (typeof info === 'string' ? [] : (info.changelog ?? [])).filter((r) => newer(r.version, CURRENT));
+                checkError = undefined;
+            }
+            catch (error) {
+                const log = error.log ?? '';
+                checkError = /E404|404 Not Found/.test(log)
+                    ? 'Nessuna versione pubblicata da controllare.'
+                    : 'Non riesco a raggiungere il registro dei pacchetti: riprova più tardi.';
+            }
+            checkedAt = new Date().toISOString();
+            return status();
+        },
+        async install(version, backup) {
+            const reason = await unavailable();
+            if (reason)
+                throw new Error(reason);
+            if (job.state === 'working' || job.state === 'restarting')
+                throw new Error('C’è già un aggiornamento in corso');
+            if (!/^\d+\.\d+\.\d+$/.test(version))
+                throw new Error('Versione non valida');
+            job = { state: 'working', step: 'Backup del database e dei media' };
+            void (async () => {
+                try {
+                    await backup();
+                    job = { state: 'working', step: `Scarico Materialize ${version}` };
+                    const next = join(dir, 'next');
+                    await rm(next, { recursive: true, force: true });
+                    await mkdir(next, { recursive: true });
+                    // The site's own package files, with every Materialize package at the new version.
+                    const pkg = JSON.parse(await readFile(join(site, 'package.json'), 'utf8'));
+                    for (const name of Object.keys(pkg.dependencies ?? {}))
+                        if (name.startsWith('@materializecms/'))
+                            pkg.dependencies[name] = version;
+                    await writeFile(join(next, 'package.json'), `${JSON.stringify(pkg, null, 2)}\n`);
+                    for (const name of ['package-lock.json', '.npmrc'])
+                        if (existsSync(join(site, name)))
+                            await copyFile(join(site, name), join(next, name));
+                    await npm(['install', '--no-audit', '--no-fund'], next);
+                    job = { state: 'working', step: 'Controllo la nuova versione' };
+                    const installed = await readJson(join(next, 'node_modules', CLI, 'package.json'));
+                    if (installed?.version !== version)
+                        throw new Error(`Installata la ${installed?.version ?? '?'} invece della ${version}`);
+                    await restartWith({ kind: 'install', from: CURRENT, to: version, at: new Date().toISOString() });
+                }
+                catch (error) {
+                    job = {
+                        state: 'failed',
+                        message: error instanceof Error ? error.message : String(error),
+                        log: error.log,
+                    };
+                    await rm(join(dir, 'next'), { recursive: true, force: true });
+                }
+            })();
+        },
+        async rollback() {
+            const reason = await unavailable();
+            if (reason)
+                throw new Error(reason);
+            const to = await previous();
+            if (!to)
+                throw new Error('Non c’è una versione precedente a cui tornare');
+            await restartWith({ kind: 'rollback', from: CURRENT, to, at: new Date().toISOString() });
+        },
+    };
+}