@minamocms/framework 0.0.0-stage → 0.10.2

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

@@ -0,0 +1,128 @@
+import { mkdirSync, readFileSync, unlinkSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { listFilesRecursively } from "../services/fs-walk.js";
+import { sanitisePath } from "../services/path-safety.js";
+import { hashThemeFile, isValidThemePath } from "../services/theme-files.js";
+import { encodePath } from "./live-content.js";
+import { SiteSyncError } from "./remote-site.js";
+export async function fetchLiveTheme(remote) {
+    let response;
+    try {
+        response = await remote.get('/v1/theme/files', { allow404: true });
+    }
+    catch (error) {
+        if (error instanceof SiteSyncError && error.reason === 'unauthorised') {
+            return { unavailable: 'the token doesn\'t have the "theme" scope' };
+        }
+        throw error;
+    }
+    // A live site on a CMS older than 0.6.0 has no theme endpoints.
+    if (response === null) {
+        return { unavailable: 'the live site\'s CMS is too old to sync its theme; upgrade it first' };
+    }
+    const listed = await response.json().catch(() => null);
+    if (!Array.isArray(listed)) {
+        throw new SiteSyncError('fetch-failed', 'GET /v1/theme/files did not return a list');
+    }
+    const theme = new Map();
+    for (const entry of listed) {
+        const { path, hash } = entry;
+        if (typeof path !== 'string' || !isValidThemePath(path) || typeof hash !== 'string') {
+            throw new SiteSyncError('unsafe-path', `The live site listed an unexpected theme file: ${JSON.stringify(path)}`);
+        }
+        theme.set(path, hash);
+    }
+    return { theme };
+}
+export function readLocalTheme(config) {
+    const files = new Map();
+    for (const path of listFilesRecursively(config.themeRoot, config.themeRoot, '').filter(isValidThemePath)) {
+        files.set(path, readFileSync(sanitisePath(config.themeRoot, path)));
+    }
+    return files;
+}
+// Makes theme/ a copy of the live site's theme. Only files that differ
+// are downloaded; all of them before anything is written, so a failure
+// part way leaves theme/ as it was.
+export async function pullTheme(config, remote, live) {
+    const local = readLocalTheme(config);
+    const downloads = new Map();
+    for (const [path, hash] of live) {
+        const here = local.get(path);
+        if (here && hashThemeFile(here) === hash) {
+            continue;
+        }
+        const bytes = await remote.getBytes(`/v1/theme/files/${encodePath(path)}`);
+        if (bytes === null || hashThemeFile(bytes) !== hash) {
+            throw new SiteSyncError('fetch-failed', `theme/${path} changed on the live site while it was being pulled; pull again`);
+        }
+        downloads.set(path, bytes);
+    }
+    const removed = [];
+    for (const path of local.keys()) {
+        if (!live.has(path)) {
+            unlinkSync(sanitisePath(config.themeRoot, path));
+            removed.push(path);
+        }
+    }
+    mkdirSync(config.themeRoot, { recursive: true });
+    for (const [path, bytes] of downloads) {
+        const target = sanitisePath(config.themeRoot, path);
+        mkdirSync(dirname(target), { recursive: true });
+        writeFileSync(target, bytes);
+    }
+    return { files: live.size, downloaded: downloads.size, removed: removed.sort() };
+}
+// The same three-way rule as pages (see planPush): only a file changed
+// here since the pull is pushed, and never over one changed on the live
+// site since.
+export function planThemePush(pulled, local, live) {
+    const changes = [];
+    const conflicts = [];
+    const paths = new Set([...Object.keys(pulled), ...local.keys(), ...live.keys()]);
+    for (const path of [...paths].sort()) {
+        const was = pulled[path];
+        const here = local.has(path) ? hashThemeFile(local.get(path)) : undefined;
+        const there = live.get(path);
+        if (here === was || here === there) {
+            continue;
+        }
+        if (there !== was) {
+            conflicts.push({
+                path,
+                reason: there === undefined
+                    ? 'deleted on the live site since your last pull'
+                    : was === undefined
+                        ? 'created on the live site since your last pull'
+                        : 'changed on the live site since your last pull',
+            });
+            continue;
+        }
+        changes.push({ path, action: here === undefined ? 'delete' : there === undefined ? 'create' : 'update' });
+    }
+    return { changes, conflicts };
+}
+// Sends the whole theme change as one request: the site checks every
+// file against what was expected, writes, commits once and switches to
+// the new theme, or changes nothing. Returns the files pushed, with the
+// hashes the live site now has for them.
+export async function executeThemePush(remote, plan, local, live, author) {
+    const writes = plan.changes
+        .filter((change) => change.action !== 'delete')
+        .map((change) => ({
+        path: change.path,
+        content: local.get(change.path).toString('base64'),
+        expected: live.get(change.path) ?? null,
+    }));
+    const deletes = plan.changes
+        .filter((change) => change.action === 'delete')
+        .map((change) => ({ path: change.path, expected: live.get(change.path) }));
+    const result = (await remote.sendJson('POST', '/v1/theme/push', {
+        writes,
+        deletes,
+        message: `Push ${plan.changes.length} theme file${plan.changes.length === 1 ? '' : 's'} from a local copy`,
+        author,
+    }));
+    const warnings = Array.isArray(result?.warnings) ? result.warnings.filter((entry) => typeof entry === 'string') : [];
+    return { warnings };
+}

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

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

package/dist/stop-site/cli.js

@@ -0,0 +1,28 @@
+#!/usr/bin/env node
+import { resolve } from 'node:path';
+import { loadSiteConfig } from "../config.js";
+import { stopSite } from "./stop-site.js";
+// Run from vhost/ (the scaffold's own "stop" script), so the site root
+// is one level up - the same relationship check-site relies on.
+const config = loadSiteConfig(resolve(process.cwd(), '..'));
+const result = await stopSite(config);
+switch (result.outcome) {
+    case 'not-running':
+        console.log("The site isn't running.");
+        break;
+    case 'removed-stale':
+        console.log(`The site isn't running. Removed a leftover record of process ${result.pid}, which has already ended.`);
+        break;
+    case 'not-a-site':
+        console.error(`Process ${result.pid} is recorded as this site, but no site is answering on port ${result.port}, so nothing was stopped.`);
+        console.error('If you are sure the site is not running, delete vhost/data/server.pid.');
+        process.exit(1);
+        break;
+    case 'stopped':
+        console.log(`Stopped the site (was on port ${result.port}).`);
+        break;
+    case 'still-stopping':
+        console.error(`Asked the site to stop (process ${result.pid}), but it is still shutting down.`);
+        process.exit(1);
+        break;
+}

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

@@ -0,0 +1,26 @@
+import type { SiteConfig } from '../config.ts';
+export type StopSiteResult = {
+    outcome: 'not-running';
+} | {
+    outcome: 'removed-stale';
+    pid: number;
+} | {
+    outcome: 'not-a-site';
+    pid: number;
+    port: number;
+} | {
+    outcome: 'stopped';
+    port: number;
+} | {
+    outcome: 'still-stopping';
+    pid: number;
+};
+export interface StopSiteDeps {
+    isAlive: (pid: number) => boolean;
+    signal: (pid: number) => void;
+    isSiteListening: (port: number) => Promise<boolean>;
+    sleep: (ms: number) => Promise<void>;
+    timeoutMs: number;
+}
+export declare const defaultStopSiteDeps: StopSiteDeps;
+export declare function stopSite(config: SiteConfig, deps?: StopSiteDeps): Promise<StopSiteResult>;

package/dist/stop-site/stop-site.js

@@ -0,0 +1,56 @@
+import { isProcessAlive, readPidFile, removePidFile } from "../services/pid-file.js";
+// GET /v1/capabilities is unauthenticated and always answers with the
+// agent's own version, so it's the check that something on the recorded
+// port really is a site - not just any process that happens to have
+// been given the recorded id after the site's own ended.
+async function capabilitiesAnswer(port) {
+    try {
+        const response = await fetch(new URL('/v1/capabilities', `http://127.0.0.1:${port}`), {
+            signal: AbortSignal.timeout(2_000),
+        });
+        const body = (await response.json());
+        return response.ok && typeof body.agentVersion === 'string';
+    }
+    catch {
+        return false;
+    }
+}
+export const defaultStopSiteDeps = {
+    isAlive: isProcessAlive,
+    signal: (pid) => process.kill(pid, 'SIGTERM'),
+    isSiteListening: capabilitiesAnswer,
+    sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+    // Long enough for the final draft checkpoint a graceful shutdown runs.
+    timeoutMs: 15_000,
+};
+// Stops the site recorded in vhost/data/server.pid with SIGTERM - the
+// same graceful shutdown as Ctrl+C (the server closes and runs its
+// final draft checkpoint) - then waits for it to exit. It only ever
+// signals a process that is both alive and answering as a site on the
+// recorded port, so a leftover file from a crash never gets an
+// unrelated process that has since been given the same id killed.
+export async function stopSite(config, deps = defaultStopSiteDeps) {
+    const record = readPidFile(config);
+    if (!record) {
+        return { outcome: 'not-running' };
+    }
+    if (!deps.isAlive(record.pid)) {
+        removePidFile(config);
+        return { outcome: 'removed-stale', pid: record.pid };
+    }
+    if (!(await deps.isSiteListening(record.port))) {
+        return { outcome: 'not-a-site', pid: record.pid, port: record.port };
+    }
+    deps.signal(record.pid);
+    const pollMs = 200;
+    for (let waited = 0; waited < deps.timeoutMs; waited += pollMs) {
+        if (!deps.isAlive(record.pid) && !deps.isAlive(record.serverPid)) {
+            // The server removes its own record on a graceful shutdown; this
+            // covers one that exited without getting that far.
+            removePidFile(config);
+            return { outcome: 'stopped', port: record.port };
+        }
+        await deps.sleep(pollMs);
+    }
+    return { outcome: 'still-stopping', pid: record.pid };
+}

package/dist/theme-state.d.ts

@@ -0,0 +1,20 @@
+import type { Liquid } from 'liquidjs';
+import type { SiteConfig } from './config.ts';
+import type { ThemeTemplates } from './renderer/theme-templates.ts';
+import type { PageTemplate } from './services/theme-page-templates.ts';
+import type { ThemeSchemas } from './services/validation.ts';
+export interface LoadedTheme {
+    themeSchemas: ThemeSchemas;
+    themeTemplates: ThemeTemplates;
+    layouts: Record<string, string>;
+    pageTemplates: PageTemplate[];
+    engine: Liquid;
+    generation: number;
+}
+export declare function loadTheme(config: SiteConfig, generation?: number): LoadedTheme;
+export declare class ThemeState {
+    current: LoadedTheme;
+    private readonly config;
+    constructor(config: SiteConfig, initial: LoadedTheme);
+    reload(): LoadedTheme;
+}

package/dist/theme-state.js

@@ -0,0 +1,33 @@
+import { createEngine } from "./renderer/engine.js";
+import { loadLayouts, loadSnippets, loadThemeTemplates } from "./renderer/theme-templates.js";
+import { loadPageTemplates } from "./services/theme-page-templates.js";
+import { loadThemeSchemas } from "./services/theme-schemas.js";
+export function loadTheme(config, generation = 0) {
+    const themeSchemas = loadThemeSchemas(config.themeRoot);
+    return {
+        themeSchemas,
+        themeTemplates: loadThemeTemplates(config.themeRoot),
+        layouts: loadLayouts(config.themeRoot),
+        pageTemplates: loadPageTemplates(config.templatesRoot, themeSchemas),
+        engine: createEngine(loadSnippets(config.themeRoot)),
+        generation,
+    };
+}
+// The theme a running server is using right now. Routes hold this one
+// object and read `current` on every request, rather than a copy of the
+// theme taken at start-up, so a theme pushed to a live site
+// (POST /v1/theme/push) takes effect straight away, with no restart.
+// Replaced whole, never mutated in place: a request already rendering
+// keeps the theme it started with.
+export class ThemeState {
+    current;
+    config;
+    constructor(config, initial) {
+        this.config = config;
+        this.current = initial;
+    }
+    reload() {
+        this.current = loadTheme(this.config, this.current.generation + 1);
+        return this.current;
+    }
+}

package/dist/upgrade/changelog.d.ts

@@ -0,0 +1,8 @@
+export declare function parseVersion(version: string): [number, number, number] | null;
+export declare function compareVersions(a: string, b: string): number;
+export declare function mayBreak(from: string, to: string): boolean;
+export interface ChangelogSection {
+    version: string;
+    text: string;
+}
+export declare function changesBetween(changelog: string, from: string, to: string): ChangelogSection[];

package/dist/upgrade/changelog.js

@@ -0,0 +1,46 @@
+// Versions are plain x.y.z here: the package never publishes
+// pre-releases, and anything else is treated as not comparable.
+export function parseVersion(version) {
+    const match = /^(\d+)\.(\d+)\.(\d+)$/.exec(version.trim());
+    return match ? [Number(match[1]), Number(match[2]), Number(match[3])] : null;
+}
+export function compareVersions(a, b) {
+    const x = parseVersion(a);
+    const y = parseVersion(b);
+    if (!x || !y) {
+        return a.localeCompare(b);
+    }
+    for (let index = 0; index < 3; index += 1) {
+        const difference = x[index] - y[index];
+        if (difference !== 0) {
+            return Math.sign(difference);
+        }
+    }
+    return 0;
+}
+// Below 1.0.0, a minor bump (0.5 -> 0.6) may break things, as a major
+// bump would above it.
+export function mayBreak(from, to) {
+    const x = parseVersion(from);
+    const y = parseVersion(to);
+    if (!x || !y) {
+        return true;
+    }
+    return x[0] !== y[0] || (x[0] === 0 && x[1] !== y[1]);
+}
+// The CHANGELOG.md sections after `from`, up to and including `to`,
+// newest first - what an upgrade from one to the other brings.
+export function changesBetween(changelog, from, to) {
+    const sections = [];
+    const headings = [...changelog.matchAll(/^## \[(\d+\.\d+\.\d+)\][^\n]*$/gm)];
+    headings.forEach((heading, index) => {
+        const version = heading[1];
+        if (compareVersions(version, from) <= 0 || compareVersions(version, to) > 0) {
+            return;
+        }
+        const start = heading.index + heading[0].length;
+        const end = index + 1 < headings.length ? headings[index + 1]?.index : changelog.length;
+        sections.push({ version, text: changelog.slice(start, end).trim() });
+    });
+    return sections;
+}

package/dist/upgrade/finish.d.ts

@@ -0,0 +1,9 @@
+import { type CheckResult } from '../site-check/run-check.ts';
+import { type OwnedFileResult } from './owned-files.ts';
+export interface FinishUpgradeResult {
+    files: OwnedFileResult[];
+    migrated: string[];
+    migrationProblem: string | null;
+    check: CheckResult;
+}
+export declare function finishUpgrade(siteRoot: string): Promise<FinishUpgradeResult>;

package/dist/upgrade/finish.js

@@ -0,0 +1,30 @@
+import { loadSiteConfig } from "../config.js";
+import { SCAFFOLD_SCRIPTS, SERVER_JS, TEMPLATE_ROOT } from "../create-site/generate-site.js";
+import { CURRENT_SCHEMA_VERSION, migrations } from "../migrations/index.js";
+import { readAgentVersion } from "../routes/capabilities.js";
+import { CHECKPOINT_AUTHOR } from "../services/checkpoint.js";
+import { MigrationError, runMigrations } from "../services/migration-runner.js";
+import { loadThemeSchemas } from "../services/theme-schemas.js";
+import { runSiteCheck } from "../site-check/run-check.js";
+import { refreshOwnedFiles } from "./owned-files.js";
+// The second half of npm run upgrade, always run by the version just
+// installed - so each version brings its own files and content changes,
+// which the version upgraded from couldn't have known about. Nothing is
+// committed: the developer reviews and commits, as after a pull.
+export async function finishUpgrade(siteRoot) {
+    const files = refreshOwnedFiles(siteRoot, { templateRoot: TEMPLATE_ROOT, serverJs: SERVER_JS, scripts: SCAFFOLD_SCRIPTS, version: readAgentVersion() });
+    const config = loadSiteConfig(siteRoot);
+    let migrated = [];
+    let migrationProblem = null;
+    try {
+        migrated = await runMigrations(config, loadThemeSchemas(config.themeRoot), migrations, CURRENT_SCHEMA_VERSION, CHECKPOINT_AUTHOR, { commit: false });
+    }
+    catch (error) {
+        if (!(error instanceof MigrationError)) {
+            throw error;
+        }
+        migrationProblem = error.message;
+    }
+    const check = await runSiteCheck(siteRoot);
+    return { files, migrated, migrationProblem, check };
+}

package/dist/upgrade/owned-files.d.ts

@@ -0,0 +1,11 @@
+export interface OwnedFileResult {
+    path: string;
+    status: 'updated' | 'created' | 'unchanged';
+}
+export interface OwnedFilesSource {
+    templateRoot: string;
+    serverJs: string;
+    scripts: Record<string, string>;
+    version: string;
+}
+export declare function refreshOwnedFiles(siteRoot: string, source: OwnedFilesSource): OwnedFileResult[];

package/dist/upgrade/owned-files.js

@@ -0,0 +1,42 @@
+import { chmodSync, existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { upgradedDependencies } from "./package-names.js";
+function place(siteRoot, path, contents, mode) {
+    const full = join(siteRoot, path);
+    const before = existsSync(full) ? readFileSync(full, 'utf-8') : null;
+    if (before === contents) {
+        return { path, status: 'unchanged' };
+    }
+    writeFileSync(full, contents);
+    if (mode !== undefined) {
+        chmodSync(full, mode);
+    }
+    return { path, status: before === null ? 'created' : 'updated' };
+}
+// The files in a site that belong to the CMS rather than to the site,
+// put back exactly as the installed version ships them - so an upgrade
+// brings its own Dockerfile, start-up script and scripts along, instead
+// of every release needing them copied in by hand. vhost/package.json is
+// merged, not replaced: the CMS's own scripts are set, the dependency is
+// the installed version under the CMS's current name (never the name
+// before, @o-a/cms-agent), and the developer's own scripts and
+// dependencies are kept.
+// Nothing outside this list is ever touched: not the theme, content,
+// site.config.json (tokens), or AGENTS.md.
+export function refreshOwnedFiles(siteRoot, source) {
+    const read = (path) => readFileSync(join(source.templateRoot, path), 'utf-8');
+    const results = [
+        place(siteRoot, 'vhost/Dockerfile', read('vhost/Dockerfile')),
+        place(siteRoot, 'vhost/docker-entrypoint.sh', read('vhost/docker-entrypoint.sh'), 0o755),
+        place(siteRoot, 'vhost/server.js', source.serverJs),
+        place(siteRoot, '.dockerignore', read('dockerignore')),
+    ];
+    const packagePath = join(siteRoot, 'vhost', 'package.json');
+    const raw = readFileSync(packagePath, 'utf-8');
+    const pkg = JSON.parse(raw);
+    const theirs = Object.fromEntries(Object.entries(pkg.scripts ?? {}).filter(([name]) => !(name in source.scripts)));
+    pkg.scripts = { ...source.scripts, ...theirs };
+    pkg.dependencies = upgradedDependencies(pkg.dependencies, source.version);
+    results.push(place(siteRoot, 'vhost/package.json', `${JSON.stringify(pkg, null, 2)}\n`));
+    return results;
+}

package/dist/upgrade/package-names.d.ts

@@ -0,0 +1,4 @@
+export declare const PACKAGE_NAME = "@minamocms/framework";
+export declare const FORMER_PACKAGE_NAMES: string[];
+export declare function upgradedDependencies(dependencies: Record<string, string> | undefined, version: string): Record<string, string>;
+export declare function requestedVersion(dependencies: Record<string, unknown> | undefined): unknown;

package/dist/upgrade/package-names.js

@@ -0,0 +1,26 @@
+// The CMS is published as @minamocms/framework from 0.10.1, and was
+// @o-a/cms-agent up to 0.9.x (0.10.0 was never published: npm refused
+// the unscoped name "minamo"). From 0.9.3, @o-a/cms-agent's npm run
+// upgrade moves a site over; what's here makes sure the old name
+// doesn't linger in vhost/package.json once it has.
+export const PACKAGE_NAME = '@minamocms/framework';
+export const FORMER_PACKAGE_NAMES = ['@o-a/cms-agent'];
+// vhost/package.json's dependencies with the CMS at the given version,
+// under its current name only. The site's own dependencies are kept.
+export function upgradedDependencies(dependencies, version) {
+    const next = { ...dependencies };
+    for (const name of FORMER_PACKAGE_NAMES) {
+        delete next[name];
+    }
+    next[PACKAGE_NAME] = version;
+    return next;
+}
+// The exact CMS version vhost/package.json asks for, under either name.
+export function requestedVersion(dependencies) {
+    for (const name of [PACKAGE_NAME, ...FORMER_PACKAGE_NAMES]) {
+        if (dependencies?.[name] !== undefined) {
+            return dependencies[name];
+        }
+    }
+    return undefined;
+}

package/dist/upgrade/upgrade-cli.d.ts

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

package/dist/upgrade/upgrade-cli.js

@@ -0,0 +1,170 @@
+#!/usr/bin/env node
+import { execFileSync, spawnSync } from 'node:child_process';
+import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { ask, parseSyncArgs } from "../site-sync/cli-helpers.js";
+import { changesBetween, compareVersions, mayBreak } from "./changelog.js";
+import { finishUpgrade } from "./finish.js";
+import { PACKAGE_NAME, upgradedDependencies } from "./package-names.js";
+// npm run upgrade [-- <version>] [--yes] [--force]
+//
+// In two halves. This version (the one installed now) picks the new
+// version, shows what's new, asks, and installs it. Then it hands over
+// to the NEW version's own copy of this command (--finish), which puts
+// back the CMS's own files, updates content to the new format, and
+// checks the site: only the new version knows what it changed.
+// Nothing is committed, and the live site is not touched - npm run
+// push offers the upgrade once it has been tested here.
+const args = parseSyncArgs(process.argv.slice(2));
+const vhostDir = process.cwd();
+const siteRoot = resolve(vhostDir, '..');
+function fail(message) {
+    console.error(message);
+    process.exit(1);
+}
+function installedVersion() {
+    try {
+        const pkg = JSON.parse(readFileSync(join(vhostDir, 'node_modules', ...PACKAGE_NAME.split('/'), 'package.json'), 'utf-8'));
+        return pkg.version;
+    }
+    catch {
+        return fail('The CMS isn\'t installed here. Run npm run upgrade from your site\'s vhost/ folder, after npm install.');
+    }
+}
+function npm(npmArgs, cwd = vhostDir) {
+    return execFileSync('npm', npmArgs, { cwd, stdio: ['ignore', 'pipe', 'pipe'] }).toString('utf-8');
+}
+// The CHANGELOG.md inside the version about to be installed, fetched
+// the same way npm install will fetch it - so it's the real thing, from
+// the same registry.
+function changelogOf(name, version) {
+    const scratch = mkdtempSync(join(tmpdir(), 'cms-upgrade-'));
+    try {
+        const packed = JSON.parse(npm(['pack', `${name}@${version}`, '--pack-destination', scratch, '--json'], scratch));
+        const tarball = join(scratch, packed[0]?.filename);
+        execFileSync('tar', ['-xzf', tarball, '-C', scratch, 'package/CHANGELOG.md'], { stdio: 'ignore' });
+        return readFileSync(join(scratch, 'package', 'CHANGELOG.md'), 'utf-8');
+    }
+    catch {
+        return null;
+    }
+    finally {
+        rmSync(scratch, { recursive: true, force: true });
+    }
+}
+function hasUncommittedChanges() {
+    try {
+        const status = execFileSync('git', ['status', '--porcelain', '--untracked-files=no', '--', 'vhost', 'content', 'theme'], {
+            cwd: siteRoot,
+        });
+        return status.toString('utf-8').trim() !== '';
+    }
+    catch {
+        return false;
+    }
+}
+async function start() {
+    const from = installedVersion();
+    let latest;
+    let versions;
+    try {
+        const info = JSON.parse(npm(['view', PACKAGE_NAME, 'versions', 'dist-tags', '--json']));
+        versions = Array.isArray(info.versions) ? info.versions : [info.versions];
+        latest = info['dist-tags'].latest;
+    }
+    catch {
+        return fail(`Couldn't ask npm which versions of ${PACKAGE_NAME} exist. Check your internet connection and try again.`);
+    }
+    const to = args.positional[0] ?? latest;
+    if (!versions.includes(to)) {
+        fail(`${PACKAGE_NAME} has no version ${to}. The latest is ${latest}.`);
+    }
+    if (compareVersions(to, from) === 0) {
+        console.log(`Already on ${from}${to === latest ? ', the latest' : ''}. Nothing to upgrade.`);
+        return;
+    }
+    if (compareVersions(to, from) < 0) {
+        fail(`${to} is older than the ${from} installed here. npm run upgrade only goes forward.`);
+    }
+    if (!args.flags.has('--force') && hasUncommittedChanges()) {
+        fail('vhost/, content/ or theme/ has uncommitted changes. Commit them first, so the upgrade\'s own changes are easy to review (or pass --force).');
+    }
+    console.log(`Upgrading the CMS from ${from} to ${to}.\n`);
+    const changelog = changelogOf(PACKAGE_NAME, to);
+    if (changelog) {
+        for (const section of changesBetween(changelog, from, to)) {
+            console.log(`--- ${section.version} ---\n${section.text}\n`);
+        }
+    }
+    else {
+        console.log(`(Couldn't read the changelog for ${to}.)\n`);
+    }
+    if (mayBreak(from, to)) {
+        console.log(`Note: ${from} to ${to} is a bigger step, which can include breaking changes. Read the notes above before going ahead.\n`);
+    }
+    if (!args.flags.has('--yes')) {
+        const answer = (await ask(`Upgrade from ${from} to ${to}? (y/N) `)).toLowerCase();
+        if (answer !== 'y' && answer !== 'yes') {
+            console.log('Cancelled. Nothing was changed.');
+            return;
+        }
+    }
+    const packagePath = join(vhostDir, 'package.json');
+    const lockPath = join(vhostDir, 'package-lock.json');
+    const packageBefore = readFileSync(packagePath, 'utf-8');
+    const lockBefore = existsSync(lockPath) ? readFileSync(lockPath, 'utf-8') : null;
+    const pkg = JSON.parse(packageBefore);
+    pkg.dependencies = upgradedDependencies(pkg.dependencies, to);
+    writeFileSync(packagePath, `${JSON.stringify(pkg, null, 2)}\n`);
+    console.log(`Installing ${PACKAGE_NAME}@${to}...`);
+    try {
+        execFileSync('npm', ['install', '--no-audit', '--no-fund'], { cwd: vhostDir, stdio: 'inherit' });
+    }
+    catch {
+        writeFileSync(packagePath, packageBefore);
+        if (lockBefore !== null) {
+            writeFileSync(lockPath, lockBefore);
+        }
+        fail(`Installing ${to} failed; package.json and package-lock.json are back as they were. Run npm install to restore ${from}.`);
+    }
+    // Hand over to the version just installed.
+    const next = join(vhostDir, 'node_modules', ...PACKAGE_NAME.split('/'), 'dist', 'upgrade', 'upgrade-cli.js');
+    if (!existsSync(next)) {
+        fail(`${to} is installed, but has no upgrade step of its own to finish with.`);
+    }
+    const finished = spawnSync(process.execPath, [next, '--finish'], { cwd: vhostDir, stdio: 'inherit' });
+    process.exit(finished.status ?? 1);
+}
+async function finish() {
+    const version = installedVersion();
+    console.log(`\nFinishing the upgrade to ${version}...`);
+    const result = await finishUpgrade(siteRoot);
+    const changed = result.files.filter((file) => file.status !== 'unchanged');
+    if (changed.length > 0) {
+        console.log('The CMS\'s own files:');
+        for (const file of changed) {
+            console.log(`  ${file.status.padEnd(8)} ${file.path}`);
+        }
+    }
+    if (result.migrated.length > 0) {
+        console.log(`Updated ${result.migrated.length} content file${result.migrated.length === 1 ? '' : 's'} to the new content format.`);
+    }
+    if (result.migrationProblem) {
+        console.log(`Content couldn't be updated to the new format, so none of it was changed:\n  ${result.migrationProblem}\nFix that file, then run npm run upgrade -- --finish again.`);
+    }
+    if (result.check.ok) {
+        console.log('Site check: no problems found.');
+    }
+    else {
+        // Reported, but not a failed upgrade: the check covers the whole
+        // site, so these can be problems it already had.
+        const count = result.check.findings.length;
+        console.log(`Site check: ${count} problem${count === 1 ? '' : 's'} (some may be from before the upgrade). Run npm run check to see them.`);
+    }
+    console.log(`\nThe CMS here is now ${version}. Nothing was committed, and the live site hasn't changed.\nTest it with npm run dev, review with git diff, then put it live with npm run push.`);
+    if (result.migrationProblem) {
+        process.exit(1);
+    }
+}
+await (args.flags.has('--finish') ? finish() : start());