@substrio/cli 0.0.0-stage → 0.1.0

package/src/commands/versions.mjs

@@ -0,0 +1,293 @@
+/**
+ * Substrio CLI: the app's versions and which one is live.
+ *
+ *   substrio versions [--json]       List versions; live and sandbox markers, the
+ *                                backup taken when each was made live, and any
+ *                                function deployed outside a version
+ *   substrio promote [N] [--no-backup] [--replace-direct | --keep-direct]
+ *                                 Make N live (default: what dev runs); the
+ *                                 app's data is backed up first. A function
+ *                                 deployed directly (outside a version) that
+ *                                 this would overwrite or delete refuses
+ *                                 (409) unless one of the two flags is given
+ *   substrio rollback [--no-backup] [--replace-direct | --keep-direct]
+ *                                 Make the version before live live again
+ *   substrio restore [ID] [--yes] [--wait S]  Put the data back from the backup a
+ *                                promote took (default: the latest) and make
+ *                                the version live then live again
+ *   substrio diff [A] [B]            What changed from A to B (default: live to dev)
+ *
+ * A and B are version numbers, "live", or a sandbox name (the version it runs).
+ */
+
+import { CliError, ErrorCode, confirmDestructive, emit, fail, globals } from '../cli.mjs';
+import { cmdRegistry } from './groups-runtime.mjs';
+import { errorText } from '../api.mjs';
+import { callOperation, failResult, invokeOperation, loadOperations } from './op.mjs';
+import { DEFAULT_SANDBOX, directMode } from './push.mjs';
+
+const C = {
+    reset: '\x1b[0m', bold: '\x1b[1m', dim: '\x1b[2m',
+    red: '\x1b[91m', green: '\x1b[92m', yellow: '\x1b[93m', cyan: '\x1b[96m',
+};
+
+
+// version.list: {live, rollback_to, versions, sandboxes: [{name, live}],
+// history: [{version, backup_id}] newest first, history[0] live}.
+const listing = (api) => invokeOperation(api, 'version.list', undefined);
+
+/**
+ * A version reference as a number: digits name a version, "live" the live
+ * one, anything else a sandbox (the version it runs). Pure over a listing.
+ */
+export function resolveVersion(ref, listed) {
+    if (/^\d+$/.test(String(ref))) return parseInt(ref, 10);
+    if (ref === 'live') {
+        if (!listed.live) throw new Error('No version is live yet');
+        return listed.live;
+    }
+    const sandbox = (listed.sandboxes || []).find((s) => s.name === ref);
+    if (!sandbox) throw new Error(`"${ref}" is not a version number, "live" or a sandbox of this app`);
+    if (!sandbox.live) throw new CliError(`Sandbox ${ref} runs no version yet (substrio push runs one there)`, { code: ErrorCode.UNKNOWN });
+    return sandbox.live;
+}
+
+function resolveOrFail(ref, listed) {
+    try {
+        return resolveVersion(ref, listed);
+    } catch (err) {
+        return fail(err);
+    }
+}
+
+const when = (seconds) => new Date(seconds * 1000).toISOString().replace('T', ' ').slice(0, 16);
+
+/**
+ * The rows `substrio versions` shows, newest version first (pure over a
+ * GET /v1/_versions listing): each version with where it runs and, when it
+ * is in the live history, the backup taken when it was last made live
+ * (history is newest first, so the first entry for a version wins; null when
+ * that promote took none, undefined when the version was never live).
+ */
+export function versionRows(listed) {
+    const runsIn = new Map();
+    const mark = (n, label) => { if (n) runsIn.set(n, [...(runsIn.get(n) || []), label]); };
+    mark(listed.live, 'live');
+    for (const s of listed.sandboxes || []) mark(s.live, s.name);
+    const backups = new Map();
+    for (const entry of listed.history || []) {
+        if (!backups.has(entry.version)) backups.set(entry.version, entry.backup_id ?? null);
+    }
+    return [...(listed.versions || [])].sort((a, b) => b.number - a.number).map((v) => ({
+        ...v,
+        live: v.number === listed.live,
+        runs: runsIn.get(v.number) || [],
+        backup_id: backups.has(v.number) ? backups.get(v.number) : undefined,
+    }));
+}
+
+// One line per target (the app, each sandbox) with a function deployed
+// directly (outside a version): its name and the kind of change. Pure over a
+// listing; [] when none.
+export function directChangeSummaryLines(listed) {
+    const line = (target, entries) => entries.length
+        ? [`direct changes on ${target}: ${entries.map((c) => `${c.name} (${c.change})`).join(', ')}`]
+        : [];
+    return [
+        ...line('the app', listed.direct_changes || []),
+        ...(listed.sandboxes || []).flatMap((s) => line(s.name, s.direct_changes || [])),
+    ];
+}
+
+export async function cmdVersions(api, args = []) {
+    // A version.* operation by its words (substrio versions get 3).
+    if (args[0] && !args[0].startsWith('-')) return cmdRegistry(api, 'versions', args);
+    const listed = await listing(api);
+    if (globals.json) return emit(listed);
+    const rows = versionRows(listed);
+    if (rows.length === 0) {
+        console.log(`${C.dim}No versions yet. Make one with: substrio push -m "..."${C.reset}`);
+        return;
+    }
+    // The backup column, sized to the ids it shows; "-" for a live entry
+    // whose promote took none.
+    const backupText = (row) => (row.backup_id === undefined ? '' : row.backup_id ?? '-');
+    const backupWidth = Math.max('BACKUP'.length, ...rows.map((r) => backupText(r).length)) + 2;
+
+    console.log(`\n${C.bold}Versions (${rows.length})${C.reset}\n`);
+    console.log(`  ${'VERSION'.padEnd(9)}${'CREATED (UTC)'.padEnd(18)}${'FUNCS'.padEnd(7)}${'SITE'.padEnd(8)}${'RUNS IN'.padEnd(16)}` +
+        `${'BACKUP'.padEnd(backupWidth)}MESSAGE`);
+    for (const v of rows) {
+        const marker = v.live ? `${C.green}● ` : '  ';
+        console.log(`${marker}${String(v.number).padEnd(9)}${v.live ? C.reset : ''}${when(v.created_at).padEnd(18)}` +
+            // A commit not yet read as a version (manifest pending) has no counts until it is.
+            `${String(v.functions ?? '-').padEnd(7)}${String(v.site_files ?? '-').padEnd(8)}${v.runs.join(', ').padEnd(16)}` +
+            `${backupText(v).padEnd(backupWidth)}${v.message || ''}`);
+    }
+    if (listed.rollback_to) console.log(`\n${C.dim}  substrio rollback makes version ${listed.rollback_to} live${C.reset}`);
+    for (const line of directChangeSummaryLines(listed)) console.log(`${C.yellow}⚠ ${line}${C.reset}`);
+    console.log('');
+}
+
+// POST /v1/_live's body: the version, "backup": false for --no-backup (a
+// promote otherwise backs the app's data up first), and "direct" for
+// --replace-direct/--keep-direct (over the server's default "refuse").
+export function liveBody(version, args) {
+    const body = args.includes('--no-backup') ? { version, backup: false } : { version };
+    const direct = directMode(args);
+    if (direct) body.direct = direct;
+    return body;
+}
+
+// What a promote or rollback says about the backup it took.
+function backupNote(set) {
+    return set.backup_id
+        ? `\n${C.dim}  Backup ${set.backup_id} taken first; undo the data with: substrio restore ${set.backup_id}${C.reset}`
+        : `\n${C.dim}  No backup taken.${C.reset}`;
+}
+
+// One direct_changes entry as "name (change: parts)".
+function directChangeLine(c) {
+    return `${c.name} ${C.dim}(${c.change}${c.parts?.length ? `: ${c.parts.join(', ')}` : ''})${C.reset}`;
+}
+
+// version.live.set's 409 DIRECT_CHANGES: the functions deployed directly
+// that this promote or rollback would overwrite or delete, as a table, with
+// how to proceed. Prints nothing under --json (the error body carries
+// direct_changes already, through the normal failResult/CliError path).
+function printDirectConflicts(body) {
+    const entries = body.direct_changes || [];
+    console.error(`${C.red}✗ ${entries.length} function${entries.length === 1 ? '' : 's'} deployed outside a version would be overwritten or deleted:${C.reset}`);
+    for (const c of entries) console.error(`  ${directChangeLine(c)}`);
+    console.error(`${C.dim}  Rerun with --replace-direct to apply the version anyway, or --keep-direct to leave ${entries.length === 1 ? 'it' : 'them'} as deployed.${C.reset}`);
+}
+
+// version.live.set, with a readable conflict table on 409 DIRECT_CHANGES
+// in place of the raw error body (any other failure: the normal failResult).
+async function liveSet(api, body) {
+    const result = await callOperation(api, await loadOperations(api), 'version.live.set', body);
+    if (!result.ok) {
+        if (result.status === 409 && result.data?.code === 'DIRECT_CHANGES') {
+            if (!globals.json) printDirectConflicts(result.data);
+            fail(CliError.fromResponse(`${result.request.method} ${result.request.path}: ${errorText(result.data, result.status)}`,
+                result.data, result.status));
+        }
+        failResult(result);
+    }
+    return result.data;
+}
+
+export async function cmdPromote(api, args) {
+    const ref = args.find((a) => !a.startsWith('-'));
+    let number;
+    if (ref) {
+        number = /^\d+$/.test(ref) ? parseInt(ref, 10) : resolveOrFail(ref, await listing(api));
+    } else {
+        const listed = await listing(api);
+        const dev = (listed.sandboxes || []).find((s) => s.name === DEFAULT_SANDBOX);
+        if (!dev?.live) fail(`The ${DEFAULT_SANDBOX} sandbox runs no version`, 'Run substrio push first, or name one: substrio promote N', ErrorCode.UNKNOWN);
+        number = dev.live;
+    }
+    const set = await liveSet(api, liveBody(number, args));
+    emit(set, () => console.log(`${C.green}✓${C.reset} Version ${C.bold}${set.live}${C.reset} is live` +
+        `${set.previous ? ` ${C.dim}(was ${set.previous}; undo with: substrio rollback)${C.reset}` : ''}.` +
+        backupNote(set)));
+}
+
+export async function cmdRollback(api, args = []) {
+    const set = await liveSet(api, liveBody('previous', args));
+    emit(set, () => console.log(`${C.green}✓${C.reset} Rolled back: version ${C.bold}${set.live}${C.reset} is live` +
+        `${set.previous ? ` ${C.dim}(was ${set.previous})${C.reset}` : ''}.` + backupNote(set)));
+}
+
+// How long `substrio restore` waits for a busy database (409), in seconds, and
+// the first and longest pause between tries, in milliseconds.
+export const RESTORE_WAIT_SECONDS = 15;
+const RESTORE_FIRST_PAUSE_MS = 100;
+const RESTORE_LONGEST_PAUSE_MS = 2000;
+
+/**
+ * Runs version.restore until it is not busy (409) or `waitSeconds` pass, the
+ * pause doubling from RESTORE_FIRST_PAUSE_MS. `ops` is the server's catalog.
+ * Returns the last callOperation result.
+ */
+export async function restoreWithRetry(api, ops, input, waitSeconds = RESTORE_WAIT_SECONDS, sleep = (ms) => new Promise((r) => setTimeout(r, ms))) {
+    const deadline = Date.now() + waitSeconds * 1000;
+    let pause = RESTORE_FIRST_PAUSE_MS;
+    for (;;) {
+        const result = await callOperation(api, ops, 'version.restore', input);
+        if (result.status !== 409 || Date.now() + pause > deadline) return result;
+        await sleep(pause);
+        pause = Math.min(pause * 2, RESTORE_LONGEST_PAUSE_MS);
+    }
+}
+
+export async function cmdRestore(api, args) {
+    const id = args.find((a, i) => !a.startsWith('-') && args[i - 1] !== '--wait');
+    const waitAt = args.indexOf('--wait');
+    const wait = waitAt >= 0 ? Number(args[waitAt + 1]) : RESTORE_WAIT_SECONDS;
+    if (!Number.isFinite(wait) || wait < 0) fail('--wait takes a number of seconds');
+    const what = id ? `backup ${id}` : 'the backup the latest promote took';
+
+    await confirmDestructive(`Replacing the app's live data with ${what}`, `substrio restore${id ? ` ${id}` : ''} --yes`);
+
+    const result = await restoreWithRetry(api, await loadOperations(api), id ? { backup_id: id } : {}, wait);
+    if (!result.ok) {
+        if (result.status === 409) {
+            fail(CliError.fromResponse(errorText(result.data, result.status), result.data, result.status),
+                `The database stayed busy for ${wait}s; try again, or wait longer with --wait N`);
+        }
+        failResult(result);
+    }
+    const data = result.data;
+    emit(data, () => {
+        console.log(`${C.green}✓${C.reset} Restored the app's data from backup ${C.bold}${data.backup_id}${C.reset}.`);
+        console.log(data.live
+            ? `  Version ${C.bold}${data.live}${C.reset} is live${data.previous && data.previous !== data.live ? ` ${C.dim}(was ${data.previous})${C.reset}` : ''}.`
+            : `  ${C.dim}The backup came before the first promote; the live version is unchanged${data.previous ? ` (${data.previous})` : ''}.${C.reset}`);
+    });
+}
+
+function names(list, item = (x) => x) {
+    return list.map(item).join(', ');
+}
+
+export async function cmdDiff(api, args) {
+    const refs = args.filter((a) => !a.startsWith('-'));
+    const listed = await listing(api);
+    const [fromRef, toRef] = refs.length >= 2 ? refs : ['live', refs[0] || DEFAULT_SANDBOX];
+    const from = resolveOrFail(fromRef, listed);
+    const to = resolveOrFail(toRef, listed);
+    const d = await invokeOperation(api, 'version.diff', { from, to });
+    if (globals.json) return emit(d);
+
+    console.log(`\n${C.bold}Version ${d.from} → ${d.to}${C.reset} ${C.dim}(${fromRef} → ${toRef})${C.reset}\n`);
+    const lines = [];
+    const add = (sign, label, text) => lines.push(`  ${sign === '+' ? C.green : sign === '-' ? C.red : C.yellow}${sign}${C.reset} ${label} ${text}`);
+    const fns = d.functions || {};
+    for (const n of fns.added || []) add('+', 'function', n);
+    for (const n of fns.removed || []) add('-', 'function', n);
+    for (const c of fns.changed || []) {
+        const what = ['source', 'main', 'routes', 'vars'].filter((k) => c[k]);
+        add('~', 'function', `${c.name} (${what.join(', ')})`);
+    }
+    if (d.rules) add('~', 'rules', '');
+    if (d.mcp) add('~', 'MCP tools', '');
+    const site = d.site || {};
+    for (const [sign, key] of [['+', 'added'], ['-', 'removed'], ['~', 'changed']]) {
+        const paths = site[key] || [];
+        if (paths.length === 0) continue;
+        const shown = paths.slice(0, 10).join(', ');
+        add(sign, `site (${paths.length})`, paths.length > 10 ? `${shown} and ${paths.length - 10} more` : shown);
+    }
+    const schedule = (c) => `${c.function} at "${c.expression}"`;
+    const trigger = (t) => `${t.function} on ${t.type} in ${t.collection}`;
+    if (d.cron?.added?.length) add('+', 'cron', names(d.cron.added, schedule));
+    if (d.cron?.removed?.length) add('-', 'cron', names(d.cron.removed, schedule));
+    if (d.triggers?.added?.length) add('+', 'triggers', names(d.triggers.added, trigger));
+    if (d.triggers?.removed?.length) add('-', 'triggers', names(d.triggers.removed, trigger));
+
+    if (lines.length === 0) console.log(`  ${C.dim}No changes.${C.reset}`);
+    for (const line of lines) console.log(line);
+    console.log('');
+}