@substrio/cli 0.0.0-stage → 0.1.1

package/src/commands/open.mjs

@@ -0,0 +1,35 @@
+/**
+ * Substrio CLI: open command
+ * 
+ * Usage:
+ *   substrio open    Open server URL in default browser
+ */
+
+import { exec } from 'node:child_process';
+
+const C = {
+    reset: '\x1b[0m', dim: '\x1b[2m', green: '\x1b[92m', cyan: '\x1b[96m',
+};
+
+export function cmdOpen(config) {
+    const url = config.url;
+    if (!url) {
+        console.error('\x1b[91m✗ Server URL not configured.\x1b[0m');
+        process.exit(1);
+    }
+
+    console.log(`${C.green}✓${C.reset} Opening ${C.cyan}${url}${C.reset}`);
+
+    // Platform-specific open command
+    const platform = process.platform;
+    let cmd;
+    if (platform === 'darwin') cmd = `open "${url}"`;
+    else if (platform === 'win32') cmd = `start "${url}"`;
+    else cmd = `xdg-open "${url}" 2>/dev/null || sensible-browser "${url}" 2>/dev/null || echo "Open ${url} in your browser"`;
+
+    exec(cmd, (err) => {
+        if (err) {
+            console.log(`${C.dim}Open ${url} in your browser.${C.reset}`);
+        }
+    });
+}

package/src/commands/push.mjs

@@ -0,0 +1,199 @@
+/**
+ * Substrio CLI: `substrio push`, a new version of the app, run in a sandbox.
+ *
+ *   substrio push [-m "message"] [--branch NAME] [--no-build] [--dry-run] [--sandbox NAME]
+ *             [--concurrency N] [--replace-direct | --keep-direct]
+ *
+ * --dry-run builds (unless --no-build), shows what the version would hold
+ * and stops without contacting the server.
+ *
+ * 1. Runs substrio.toml's [build] steps in order, their output streamed; the
+ *    first that fails stops the push.
+ * 2. Collects the functions, rules, MCP tools and the site (its parts merged
+ *    by path, later parts winning), and hashes every file. The collections
+ *    the app declares (collections_dir, src/collections.mjs) go in the version
+ *    too: their rules join the rules, their schemas ride as its "collections"
+ *    member (a server whose versions do not take it refuses the push, naming
+ *    that, before anything is sent).
+ * 3. POST /v1/_versions; uploads only the blobs the server lacks.
+ * 4. Runs the version in the sandbox (default dev), creating it if missing,
+ *    and prints its address. `substrio promote` then makes it live. A function
+ *    deployed directly in the sandbox (outside a version) that this would
+ *    overwrite or delete refuses (409) unless --replace-direct or
+ *    --keep-direct was given.
+ * The version carries the app's settings substrio.toml declares ([auth],
+ * plans_file; src/settings.mjs), so they go live with it: in the sandbox on
+ * push, in the app on promote. Their keys are checked against the server's
+ * operation schemas before step 3, so an unknown key sends nothing.
+ */
+
+import { loadApp, makeLive, publishVersion, readManifest, runBuild } from '../apply.mjs';
+import { DEFAULT_CONCURRENCY, formatSize } from '../blobs.mjs';
+import { invokeOperation, loadOperations } from './op.mjs';
+import { emit, fail } from '../cli.mjs';
+
+const C = {
+    reset: '\x1b[0m', bold: '\x1b[1m', dim: '\x1b[2m',
+    red: '\x1b[91m', green: '\x1b[92m', yellow: '\x1b[93m', cyan: '\x1b[96m',
+};
+
+export const DEFAULT_SANDBOX = 'dev';
+
+
+export function flag(args, names, fallback) {
+    for (const name of [].concat(names)) {
+        const i = args.indexOf(name);
+        if (i >= 0 && i + 1 < args.length) return args[i + 1];
+    }
+    return fallback;
+}
+
+/**
+ * --replace-direct / --keep-direct, as version.live.set's `direct`: replace
+ * or keep a function deployed directly (outside a version) since the target's
+ * live version was recorded, instead of refusing (the server's default).
+ * Only one may be given. Shared by push, promote and rollback.
+ */
+export function directMode(args) {
+    const replace = args.includes('--replace-direct');
+    const keep = args.includes('--keep-direct');
+    if (replace && keep) fail('--replace-direct and --keep-direct cannot both be given');
+    return replace ? 'replace' : keep ? 'keep' : undefined;
+}
+
+// What a dry run shows of the version body: every function with its routes,
+// the rules and tools, cron, triggers, queues and the site's size.
+function printBody(body, app, collections) {
+    console.log(`\n${C.bold}Functions${C.reset}`);
+    if (body.functions.length === 0) console.log(`  ${C.dim}none${C.reset}`);
+    for (const f of body.functions) {
+        const vars = f.vars ? Object.keys(f.vars).length : 0;
+        console.log(`  ${C.bold}${f.name}${C.reset} ${C.dim}(${formatSize(f.size)}${f.main ? `, main ${f.main}` : ''}` +
+            `${vars ? `, ${vars} var${vars === 1 ? '' : 's'}` : ''})${C.reset}`);
+        for (const route of f.routes || []) console.log(`    ${route}`);
+    }
+    if (app.rules) console.log(`${C.bold}Rules${C.reset} ${app.rules.path} ${C.dim}(${formatSize(app.rules.size)})${C.reset}`);
+    if (app.mcp) console.log(`${C.bold}MCP tools${C.reset} ${app.mcp.path} ${C.dim}(${formatSize(app.mcp.size)})${C.reset}`);
+    if (collections.length) {
+        console.log(`${C.bold}Collections${C.reset}`);
+        for (const c of collections) {
+            console.log(`  ${c.name} ${C.dim}(${c.file}${c.schema ? ', schema' : ''}${c.rules ? ', rules' : ''}${c.indexes ? `, ${c.indexes.length} indexes` : ''}${c.aggregates ? `, ${c.aggregates.length} aggregates` : ''})${C.reset}`);
+        }
+    }
+    if (body.cron.length) {
+        console.log(`${C.bold}Cron${C.reset}`);
+        for (const c of body.cron) console.log(`  ${c.function} at "${c.expression}"`);
+    }
+    if (body.triggers.length) {
+        console.log(`${C.bold}Triggers${C.reset}`);
+        for (const t of body.triggers) console.log(`  ${t.function} on ${t.type} in ${t.collection}`);
+    }
+    if (body.queues.length) {
+        console.log(`${C.bold}Queues${C.reset}`);
+        for (const q of body.queues) console.log(`  ${q.name}${q.consumer ? ` consumed by ${q.consumer}` : ''}`);
+    }
+    if (app.site) {
+        const bytes = app.site.files.reduce((sum, f) => sum + f.size, 0);
+        console.log(`${C.bold}Site${C.reset} ${app.site.files.length} files, ${formatSize(bytes)}` +
+            `${app.site.sidecars ? ` ${C.dim}(${app.site.sidecars} precompressed sidecars)${C.reset}` : ''}` +
+            `${app.site.replaced.length ? `, ${app.site.replaced.length} replaced by a later part` : ''}`);
+    }
+}
+
+/**
+ * The sandbox `name`, made if the app does not have it yet:
+ * {name, slug, hosts, live, pin}. A sandbox push makes is a dev environment:
+ * the app but for its own secrets, its outbound requests sent as the app's
+ * are ("outbound": "live"), so every part of a version is tried there.
+ */
+export async function ensureSandbox(api, name, ops = null) {
+    const data = await invokeOperation(api, 'sandbox.list', undefined, { ops });
+    const found = (data.sandboxes || []).find((s) => s.name === name);
+    if (found) return found;
+    const made = await invokeOperation(api, 'sandbox.create', { name, outbound: 'live' }, { ops });
+    console.log(`  ${C.dim}created sandbox ${name}${C.reset}`);
+    return made.sandbox;
+}
+
+export async function cmdPush(api, config, args) {
+    const cwd = process.cwd();
+    const message = flag(args, ['-m', '--message']);
+    const branch = flag(args, '--branch');
+    const sandbox = flag(args, '--sandbox', DEFAULT_SANDBOX);
+    const concurrency = Math.max(1, parseInt(flag(args, '--concurrency', DEFAULT_CONCURRENCY), 10));
+    const dryRun = args.includes('--dry-run');
+    const direct = directMode(args);
+
+    console.log(`\n${C.bold}${C.cyan}⚡ Substrio Push${C.reset}${dryRun ? ` ${C.yellow}(dry run)${C.reset}` : ''}`);
+    console.log(`${C.dim}  Server: ${config.url}${C.reset}`);
+    console.log(`${C.dim}  Tenant: ${config.tenant}${C.reset}\n`);
+
+    let loaded;
+    try {
+        const manifest = readManifest(config);
+        if (!args.includes('--no-build') && manifest.build.length > 0) {
+            runBuild(manifest.build, cwd, (step) =>
+                console.log(`${C.bold}== build${C.reset} ${C.dim}(${step.dir})${C.reset} ${step.run}`));
+            console.log('');
+        }
+        loaded = await loadApp(config, manifest, cwd, message);
+    } catch (err) {
+        fail(err);
+    }
+    // --branch is a request option of version.create, not a part of the app
+    // the manifest describes: the version's content (and so its hash) is the
+    // same whichever branch it is committed on.
+    if (branch) loaded.body.branch = branch;
+    const { app, settings, plans, collections, body, byHash } = loaded;
+    const total = [...byHash.values()].reduce((sum, f) => sum + f.size, 0);
+    const siteFiles = app.site?.files.length ?? 0;
+    console.log(`  ${app.functions.length} function${app.functions.length === 1 ? '' : 's'}` +
+        `${app.rules ? ', rules' : ''}${app.mcp ? ', MCP tools' : ''}` +
+        `${collections.length ? `, ${collections.length} collection${collections.length === 1 ? '' : 's'}` : ''}` +
+        `, ${siteFiles} site file${siteFiles === 1 ? '' : 's'}` +
+        `, ${body.cron.length} cron, ${body.triggers.length} trigger${body.triggers.length === 1 ? '' : 's'}` +
+        `${body.queues.length ? `, ${body.queues.length} queue${body.queues.length === 1 ? '' : 's'}` : ''}` +
+        ` ${C.dim}(${byHash.size} blobs, ${formatSize(total)})${C.reset}`);
+    for (const s of settings) console.log(`  ${s.label} [${s.table}] ${Object.keys(s.values).join(', ')}`);
+    if (plans !== null) console.log(`  Plans from ${config.plans_file} (${plans.plans?.length ?? 0})`);
+    if (app.site?.replaced.length) {
+        const shown = app.site.replaced.slice(0, 5).join(', ');
+        const more = app.site.replaced.length > 5 ? ` and ${app.site.replaced.length - 5} more` : '';
+        console.log(`  ${C.yellow}⚠ ${app.site.replaced.length} site path${app.site.replaced.length === 1 ? '' : 's'} given by more than one part; the later part wins: ${shown}${more}${C.reset}`);
+    }
+    if (app.site?.sidecars) console.log(`  ${C.dim}precompressed: ${app.site.sidecars} .br/.gz sidecars made from the merged site${C.reset}`);
+
+    if (dryRun) {
+        printBody(body, app, collections);
+        console.log(`\n${C.yellow}⦿${C.reset} Dry run: nothing was sent to the server.\n`);
+        return;
+    }
+
+    // 1. The settings tables' keys, checked against the server's schemas; the
+    // version, the server answering with the blobs it lacks; only those uploaded.
+    const ops = await loadOperations(api);
+    const invoke = (name, input) => invokeOperation(api, name, input, { ops });
+    let published;
+    try {
+        published = await publishVersion(api, ops, loaded, invoke, concurrency, { carryCollections: true });
+    } catch (err) {
+        fail(err);
+    }
+    const { result, number, missing, uploaded } = published;
+    console.log(`  uploaded ${uploaded.count} new file${uploaded.count === 1 ? '' : 's'} (${formatSize(uploaded.bytes)}), ` +
+        `${byHash.size - uploaded.count} already on the server`);
+    console.log(`\n${C.green}${C.bold}✓ Version ${number}${C.reset}` +
+        `${result.existed ? ` ${C.dim}(existed: the same content was already version ${number})${C.reset}` : ''}`);
+
+    // 3. Run it in the sandbox.
+    const box = await ensureSandbox(api, sandbox, ops);
+    const set = await makeLive(invoke, number, { sandbox, direct });
+    console.log(`${C.green}✓${C.reset} ${C.bold}${sandbox}${C.reset} runs version ${number}` +
+        `${set.previous ? ` ${C.dim}(was ${set.previous})${C.reset}` : ''}`);
+    for (const host of box.hosts || []) console.log(`  ${C.cyan}${host}${C.reset}`);
+    if (!box.hosts?.length) console.log(`  ${C.dim}(no address yet: the server has no domain for sandboxes)${C.reset}`);
+
+    console.log(`${C.dim}  Make it live with: substrio promote${sandbox === DEFAULT_SANDBOX ? '' : ` ${number}`}${C.reset}\n`);
+    // --json: the version the server made, what was uploaded, the sandbox and what it runs.
+    emit({ version: result.version, existed: Boolean(result.existed), missing, uploaded, sandbox: box, live: set }, () => {});
+}

package/src/commands/signup.mjs

@@ -0,0 +1,164 @@
+/**
+ * Substrio CLI: `substrio signup` — an outside developer or an AI agent with the
+ * CLI alone, no master key.
+ *
+ * Usage:
+ *   substrio signup --url URL [--tenant SLUG] [--email E] [--code CODE | --password -]
+ *               [--account NAME] [--save-profile NAME] [--print]
+ *
+ * SLUG is the identity app: an operator sets one up once (a tenant, then
+ * `platform.setting.set identity_tenant=SLUG`) and tells developers its
+ * slug; without it there is no self-serve signup (ask your operator, or pass
+ * the slug you were given).
+ *
+ * The email proves the person (NIGHT-ONBOARD): with no --code the server mails a
+ * six-digit code to E (auth.email.code_request). With a terminal the code is asked for
+ * at once; with none (an AI agent) the command says the exact next command, and
+ * `--code CODE` (or SUBSTRIO_SIGNUP_CODE) finishes: auth.email.code_verify proves the
+ * mailbox and signs the person in, account.create makes their account,
+ * account.key.create its first key. Reading the code from the mail is the one
+ * human step. --password - (the password read from stdin, never a plain argument,
+ * which a `ps` or the shell history would show) also sets a password (auth.register
+ * first); the email is proven by the code all the same. SUBSTRIO_SIGNUP_EMAIL, SUBSTRIO_SIGNUP_PASSWORD and
+ * SUBSTRIO_SIGNUP_ACCOUNT fill in the same fields for a run with no terminal.
+ *
+ * The key is saved to a profile exactly as `substrio login` saves one (same
+ * owner-only file, same writeProfile); "substrio app create" and "substrio key ..."
+ * take it from there. The key is shown only with --print; otherwise the
+ * command says where it went. A person with a second factor signs in with
+ * `substrio login`, never by a code alone.
+ */
+
+import { CliError, Prompter, emitIssuedKey, emitLine, fail, globals } from '../cli.mjs';
+import { listProfiles, writeProfile } from '../config.mjs';
+import { SubstrioAPI, errorText } from '../api.mjs';
+import { OpError, callOperation, loadOperations } from './op.mjs';
+
+const C = {
+    reset: '\x1b[0m', bold: '\x1b[1m', dim: '\x1b[2m', red: '\x1b[91m', green: '\x1b[92m', cyan: '\x1b[96m',
+};
+
+const USAGE = 'substrio signup --url URL --tenant SLUG [--email E] [--code CODE | --password -] [--account NAME] [--save-profile NAME] [--print]';
+
+// The whole of stdin, one trailing newline trimmed (never printed, never logged).
+async function readStdin() {
+    const chunks = [];
+    for await (const chunk of process.stdin) chunks.push(chunk);
+    return Buffer.concat(chunks).toString('utf-8').replace(/\r?\n$/, '');
+}
+
+// A sharper hint than the server's own message, for the signup flow's three
+// calls; null falls back to a generic one.
+function hintFor(step, result) {
+    const message = errorText(result.data, result.status);
+    if (step === 'auth.register' && /already registered/i.test(message)) {
+        return 'an account with this email exists already; run "substrio login" instead';
+    }
+    if (step === 'auth.register' && /password/i.test(message)) {
+        return message; // the server's message is the rule itself
+    }
+    if ((step === 'account.create' || step === 'account.key.create') && result.status === 401) {
+        return 'the server has no identity app configured (an operator runs: substrio op platform.setting.set key=identity_tenant value=SLUG, on a tenant that exists), or --tenant named the wrong one';
+    }
+    if (step === 'account.app.create' && result.status === 409) {
+        return 'that app name is taken; choose another';
+    }
+    return null;
+}
+
+async function step(api, ops, name, input, headers) {
+    let result;
+    try {
+        result = await callOperation(api, ops, name, input, null, { headers });
+    } catch (err) {
+        if (err instanceof OpError) return fail(err, `substrio op ${name} --help shows its input`);
+        throw err;
+    }
+    if (!result.ok) {
+        fail(CliError.fromResponse(`${name}: ${errorText(result.data, result.status)}`, result.data, result.status), hintFor(name, result));
+    }
+    return result.data;
+}
+
+export async function cmdSignup(args) {
+    let url = null, tenant = globals.tenant || process.env.SUBSTRIO_TENANT || null;
+    let email = null, password = null, code = null, accountName = null, profileName = null;
+    const print = args.includes('--print');
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === '--print') continue;
+        else if (arg === '--url' && args[i + 1]) url = args[++i];
+        else if (arg === '--email' && args[i + 1]) email = args[++i];
+        else if (arg === '--code' && args[i + 1]) code = args[++i];
+        else if (arg === '--password' && args[i + 1]) password = args[++i];
+        else if (arg === '--account' && args[i + 1]) accountName = args[++i];
+        else if (arg === '--save-profile' && args[i + 1]) profileName = args[++i];
+        else fail(`unexpected argument "${arg}"`, USAGE);
+    }
+    if (password !== null && password !== '-') {
+        fail('--password takes "-" (the password read from stdin), never a plain argument', `substrio signup --password - < password.txt, or SUBSTRIO_SIGNUP_PASSWORD`);
+    }
+    if (password === '-') password = await readStdin();
+    password = password ?? process.env.SUBSTRIO_SIGNUP_PASSWORD ?? null;
+    code = code ?? process.env.SUBSTRIO_SIGNUP_CODE ?? null;
+    email = email ?? process.env.SUBSTRIO_SIGNUP_EMAIL ?? null;
+    accountName = accountName ?? process.env.SUBSTRIO_SIGNUP_ACCOUNT ?? null;
+    if (password && code) fail('--code and --password are two ways in; pass one', USAGE);
+
+    const prompter = new Prompter();
+    try {
+        try {
+            if (!url) url = await prompter.ask('  Server URL (e.g. http://localhost:9000)', '', '--url');
+            if (!tenant) tenant = await prompter.ask('  Identity app (ask your operator for its slug)', '', '--tenant');
+            if (!email) email = await prompter.ask('  Email', '', '--email');
+            if (!accountName) accountName = await prompter.ask('  Account name', (email.split('@')[0] || 'account'));
+        } catch (err) {
+            fail(err, 'substrio signup --url URL --tenant SLUG --email E');
+        }
+        if (!url || !tenant || !email) fail(`Usage: ${USAGE}`);
+        url = url.replace(/\/+$/, '');
+        profileName = profileName || accountName;
+        if (listProfiles().some((p) => p.name === profileName)) {
+            fail(`A profile named "${profileName}" already exists; pass --save-profile with another name.`);
+        }
+        const api = new SubstrioAPI({ url, tenant, master_key: null });
+        let ops;
+        try {
+            ops = await loadOperations(api);
+        } catch (err) {
+            return fail(err, `nothing was created; check the server first: substrio status --url ${url}`);
+        }
+
+        // A password registers the person; either way the email is proven by the mailed code
+        // before an account is made (the server refuses account.create until it is).
+        if (password) await step(api, ops, 'auth.register', { email, password }, {});
+        let session;
+        {
+            if (!code) {
+                await step(api, ops, 'auth.email.code_request', { email }, {});
+                const next = `substrio signup --url ${url} --tenant ${tenant} --email ${email} --account ${JSON.stringify(accountName)} --code CODE`;
+                if (!prompter.interactive) {
+                    emitLine({ sent: true, email, next }, () => {
+                        console.error(`${C.green}✓${C.reset} A code is on its way to ${C.bold}${email}${C.reset}.`);
+                        console.error(`${C.dim}  Finish with: ${next}${C.reset}`);
+                    });
+                    return;
+                }
+                code = await prompter.ask(`  The code mailed to ${email}`, '', '--code');
+            }
+            session = await step(api, ops, 'auth.email.code_verify', { email, code }, {});
+            if (!session.token) {
+                fail(`${email} has a second factor: a code alone signs no one in past it`, `substrio login --url ${url} --tenant ${tenant}`);
+            }
+        }
+        const bearer = { Authorization: `Bearer ${session.token}` };
+        const account = await step(api, ops, 'account.create', { name: accountName }, bearer);
+        const key = await step(api, ops, 'account.key.create', { id: account.id, name: 'cli', mode: 'live' }, bearer);
+        writeProfile(profileName, url, key.key, null);
+        emitIssuedKey({ account_id: account.id, account: account.name, profile: profileName, url, key: key.key }, print);
+        console.error(`${C.green}✓${C.reset} Account ${C.bold}${account.name}${C.reset} (id ${account.id}) created; its key is saved to profile ${C.bold}${profileName}${C.reset}.`);
+        console.error(`${C.dim}  "substrio app create NAME" makes your first app; "substrio whoami" shows this profile.${C.reset}`);
+    } finally {
+        prompter.close();
+    }
+}

package/src/commands/site.mjs

@@ -0,0 +1,129 @@
+/**
+ * Substrio CLI: site command: deploy a tenant's website as a release
+ *
+ * Usage:
+ *   substrio site deploy <dir> [--dry-run] [--concurrency N]
+ *   substrio site releases
+ *   substrio site activate <release-id>      (also rolls back)
+ *
+ * deploy hashes every file under <dir>, sends the manifest, uploads only the
+ * files the server does not already hold, then activates the release. The
+ * server switches the site in one step, so visitors see the old site or the
+ * new one, never a mix.
+ */
+
+import { statSync } from 'node:fs';
+
+import { DEFAULT_CONCURRENCY, collect, formatSize, ignoredNames, uploadBlobs } from '../blobs.mjs';
+import { ErrorCode, emit, fail } from '../cli.mjs';
+import { cmdRegistry } from './groups-runtime.mjs';
+import { callOrThrow, invokeOperation, loadOperations, runOperation } from './op.mjs';
+
+const C = {
+    reset: '\x1b[0m', bold: '\x1b[1m', dim: '\x1b[2m',
+    red: '\x1b[91m', green: '\x1b[92m', yellow: '\x1b[93m', cyan: '\x1b[96m',
+};
+
+export async function cmdSite(api, config, args) {
+    const sub = args[0];
+    switch (sub) {
+        case 'deploy': return siteDeploy(api, config, args.slice(1));
+        case 'releases': case 'list': return runOperation(api, 'site.release.list', args.slice(1), { render: printReleases });
+        case 'activate': case 'rollback': return siteActivate(api, args[1]);
+        default:
+            // Any other site.* operation by its words (substrio site release create).
+            if (sub && !sub.startsWith('-')) return cmdRegistry(api, 'site', args);
+            fail(`Unknown subcommand: ${sub || '(none)'}`,
+                 'Usage: substrio site deploy <dir> | releases | activate <release-id>');
+    }
+}
+
+
+function flag(args, name, fallback) {
+    const i = args.indexOf(name);
+    return i >= 0 && i + 1 < args.length ? args[i + 1] : fallback;
+}
+
+async function siteDeploy(api, config, args) {
+    const dir = args.find((a) => !a.startsWith('--') && a !== flag(args, '--concurrency'));
+    if (!dir) fail('Site directory required.', 'Usage: substrio site deploy <dir>');
+    let isDir = false;
+    try { isDir = statSync(dir).isDirectory(); } catch { /* reported below */ }
+    if (!isDir) fail(`Not a directory: ${dir}`, null, ErrorCode.FILE_NOT_FOUND);
+
+    const dryRun = args.includes('--dry-run');
+    const concurrency = Math.max(1, parseInt(flag(args, '--concurrency', DEFAULT_CONCURRENCY), 10));
+
+    console.log(`\n${C.bold}${C.cyan}⚡ Substrio Site Deploy${C.reset}${dryRun ? ` ${C.yellow}(dry run)${C.reset}` : ''}`);
+    console.log(`${C.dim}  Server: ${config.url}${C.reset}`);
+    console.log(`${C.dim}  Tenant: ${config.tenant}${C.reset}\n`);
+
+    const files = collect(dir, ignoredNames(config));
+    if (files.length === 0) fail(`No files in ${dir}`);
+    const total = files.reduce((sum, f) => sum + f.size, 0);
+    console.log(`  ${files.length} files, ${formatSize(total)}`);
+    if (dryRun) {
+        for (const f of files.slice(0, 20)) console.log(`  ${C.dim}${f.path} (${formatSize(f.size)})${C.reset}`);
+        if (files.length > 20) console.log(`  ${C.dim}... and ${files.length - 20} more${C.reset}`);
+        return;
+    }
+
+    let published;
+    try {
+        published = await publishSite(api, await loadOperations(api), files, concurrency);
+    } catch (err) {
+        fail(err);
+    }
+    const { release, activated } = published;
+    const id = release.id;
+    console.log(`  ${uploadedLine(published, files.length)}`);
+
+    // --json prints the release, what was uploaded and the activation.
+    emit(published, () => {
+        console.log(`\n${C.green}${C.bold}✓ Release ${id} is live.${C.reset}`);
+        if (activated.previous) {
+            console.log(`${C.dim}  Previous release: ${activated.previous} (roll back with: substrio site activate ${activated.previous})${C.reset}`);
+        }
+        console.log('');
+    });
+}
+
+/**
+ * A site release from collected files (blobs.mjs collect), the one way both `substrio site
+ * deploy` and `substrio deploy` publish a site: the manifest (the server answers with the
+ * hashes it lacks), only those blobs uploaded `concurrency` at a time, then the one switch.
+ * Throws the first refusal (a CliError, never the end of the run); prints nothing.
+ */
+export async function publishSite(api, ops, files, concurrency = DEFAULT_CONCURRENCY) {
+    const manifest = { files: files.map(({ path, hash, size }) => ({ path, hash, size })) };
+    const release = await callOrThrow(api, ops, 'site.release.create', manifest);
+    const missing = new Set(release.missing);
+    const uploaded = await uploadBlobs(api, ops, missing, new Map(files.map((f) => [f.hash, f])), concurrency);
+    const activated = await callOrThrow(api, ops, 'site.release.activate', { id: release.release.id });
+    return { release: release.release, missing: release.missing, uploaded, activated };
+}
+
+export const uploadedLine = ({ missing, uploaded }, fileCount) =>
+    `uploaded ${missing.length} new file${missing.length === 1 ? '' : 's'} (${formatSize(uploaded.bytes)}), ${fileCount - missing.length} already on the server`;
+
+// site.release.list answers { releases: [...] } (--json prints it whole).
+function printReleases(data) {
+    if (!data.releases?.length) {
+        console.log(`${C.dim}No site releases yet.${C.reset}`);
+        return;
+    }
+    console.log(`\n${C.bold}Site releases (${data.releases.length})${C.reset}\n`);
+    console.log(`  ${'RELEASE'.padEnd(34)}${'CREATED'.padEnd(22)}${'FILES'.padEnd(8)}SIZE`);
+    for (const r of data.releases) {
+        const created = new Date(r.created_at * 1000).toISOString().replace('T', ' ').slice(0, 19);
+        const marker = r.active ? `${C.green}● ` : '  ';
+        console.log(`${marker}${r.id.padEnd(34)}${C.reset}${created.padEnd(22)}${String(r.files).padEnd(8)}${formatSize(r.bytes)}`);
+    }
+    console.log('');
+}
+
+async function siteActivate(api, id) {
+    if (!id) fail('Release ID required.', 'Usage: substrio site activate <release-id>');
+    const data = await invokeOperation(api, 'site.release.activate', { id });
+    emit(data, () => console.log(`${C.green}✓${C.reset} Release ${C.bold}${data.active}${C.reset} is live${data.previous ? ` ${C.dim}(was ${data.previous})${C.reset}` : ''}.`));
+}