@substrio/cli 0.0.0-stage → 0.1.0

package/src/commands/deploy.mjs

@@ -0,0 +1,488 @@
+/**
+ * Substrio CLI: `substrio deploy` command
+ *
+ * Scans functions/ directory and deploys each .js file (function.deploy),
+ * with what substrio.toml declares for it:
+ *
+ *   [functions.api]
+ *   routes = ["ANY /api/*", "POST /emails"]
+ *   main = "handler"               # optional entry point
+ *
+ *   [functions.api.vars]           # the function's env
+ *   API_BASE_URL = "https://api.example.com"
+ *
+ * A declared function without a file fails the deploy. First the collections
+ * the app declares (collections/NAME.json, or substrio.toml's collections_dir;
+ * src/collections.mjs) are made and their schemas set, and the roles ([roles.NAME])
+ * and sign-in providers ([auth.providers.NAME]) it declares are made or updated
+ * (src/identity.mjs), and when it declares a [permissions] table, the tenant's
+ * permission catalog (permissions.set, append only; docs/permissions.md) -
+ * before the functions, whose routes may declare "auth:<name>" against it. Then,
+ * when substrio.toml names a rules_file or a collection declares rules, the tenant's security
+ * rules are set from them together (security.rules.set), and when it names an mcp_file, the tools the tenant
+ * serves to AI agents at /mcp (mcp.tools.set), and when it names a
+ * plans_file, the tenant's plans (plans.set), and when it declares [apps.offer] or [apps.use], the functions
+ * it offers other apps and the ones of other apps it calls (apps.calls.set), and each settings table it declares
+ * ([auth], [login]) by its own operation (auth.settings.set). Then public/ (public_dir) is published
+ * as a site release (site.mjs publishSite). After the collections are applied, a server declaration
+ * (index, aggregate or expiry) the files no longer name is reported
+ * (drift), left in place; --prune drops it with index.drop. --json
+ * prints a typed report: each function, step and total, a failed step
+ * with the server's typed error, and the run exits with the first
+ * failure's exit code.
+ */
+
+import { readdirSync, readFileSync, existsSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+
+import { errorText } from '../api.mjs';
+import { collect, ignoredNames } from '../blobs.mjs';
+import { CliError, ErrorCode, ExitCode, emit, exitCodeFor, fail } from '../cli.mjs';
+import { aggregateCountLabel, applyCollections, collectionDrift, declaredCollections, declaredRules, indexCountLabel, pruneDrift } from '../collections.mjs';
+import { buildFunction } from '../function-build.mjs';
+import { IdentityKind, appliedNames, applyIdentity, declaredIdentity, hasIdentity, unsetLine } from '../identity.mjs';
+import { callOrThrow, loadOperations } from './op.mjs';
+import { publishSite, uploadedLine } from './site.mjs';
+import { declaredFunction, declaredLedger, declaredPermissions, withSiteVars } from '../manifest.mjs';
+import { declaredPlans, declaredSettings } from '../settings.mjs';
+
+const C = {
+    reset: '\x1b[0m', bold: '\x1b[1m', dim: '\x1b[2m',
+    red: '\x1b[91m', green: '\x1b[92m', yellow: '\x1b[93m', cyan: '\x1b[96m',
+};
+
+/**
+ * @param {import('../api.mjs').SubstrioAPI} api
+ * @param {object} config
+ * @param {string[]} args
+ */
+export async function cmdDeploy(api, config, args) {
+    const cwd = process.cwd();
+    const functionsDir = resolve(cwd, config.functions_dir || 'functions');
+    const publicDir = resolve(cwd, config.public_dir || 'public');
+    const dryRun = args.includes('--dry-run');
+    const prune = args.includes('--prune');
+
+    const onlyFunctions = args.includes('--functions') || args.includes('-f');
+    const onlyAssets = args.includes('--assets') || args.includes('-a');
+    // Positional arguments: the function names to replace. With any given,
+    // only those functions are built and sent; no other step runs or reads its file.
+    const names = args.filter((a) => !a.startsWith('-'));
+    const named = names.length > 0;
+    if (named && prune) fail('substrio deploy NAME... --prune: pruning is a whole-project decision, not one for named functions', null, ErrorCode.INVALID_ARGUMENT);
+    if (named && (onlyFunctions || onlyAssets)) fail('substrio deploy NAME... --functions/--assets: ambiguous with named functions', null, ErrorCode.INVALID_ARGUMENT);
+    const deployAll = !onlyFunctions && !onlyAssets && !named;
+
+    console.log(`\n${C.bold}${C.cyan}⚡ Substrio 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`);
+
+    let totalDeployed = 0;
+    let totalFailed = 0;
+    // What --json prints: each function, the rules, MCP tools and plans set,
+    // the static assets counted, and the totals.
+    const report = { dry_run: dryRun, collections: null, identity: null, functions: [], rules: null, mcp_tools: null, app_calls: null, plans: null, permissions: null, ledger: null, assets: null, site: null };
+    const run = new DeployRun(api);
+
+    // What the app declares of its collections and rules, read (and checked) before anything is
+    // sent. Named mode skips this: it reads nothing beyond the named functions' own files.
+    let collections = [];
+    let rules = null;
+    let identity = { roles: [], providers: [], unset: [] };
+    let permissions = null;
+    let ledger = null;
+    let settings = [];
+    if (!named) {
+        try {
+            collections = declaredCollections(config, cwd);
+            rules = declaredRules(config, cwd, collections);
+            identity = declaredIdentity(config);
+            permissions = declaredPermissions(config);
+            ledger = declaredLedger(config);
+            settings = declaredSettings(config);
+        } catch (err) {
+            fail(err);
+        }
+    }
+
+    // Collections: made and their schemas set, before the functions and rules that use them.
+    if ((deployAll || onlyFunctions) && collections.length > 0) {
+        if (dryRun) {
+            console.log(`${C.dim}⦿ collections from ${config.collections_dir || 'collections'}/: would apply ${collections.map((c) => c.name + indexCountLabel(c.indexes?.length ?? 0) + aggregateCountLabel(c.aggregates?.length ?? 0)).join(', ')}${C.reset}\n`);
+        } else {
+            const applied = [];
+            try {
+                report.collections = { ok: true, ...await applyCollections((name, input) => run.call(name, input), collections, applied) };
+                console.log(`${C.green}✓${C.reset} ${C.bold}Collections${C.reset} ${C.dim}(${applied.map((a) => a.collection + indexCountLabel(a.indexes) + aggregateCountLabel(a.aggregates)).join(', ')})${C.reset}`);
+                const drift = await collectionDrift((name, input) => run.call(name, input), collections);
+                if (drift.length === 0) {
+                    console.log(`${C.dim}  up to date: no server declaration the files no longer name${C.reset}`);
+                } else if (prune) {
+                    await pruneDrift((name, input) => run.call(name, input), drift);
+                    report.collections.pruned = drift;
+                    for (const d of drift) console.log(`${C.yellow}⊘${C.reset} ${C.dim}pruned ${d.collection}: ${d.kind} ${d.label}${C.reset}`);
+                } else {
+                    report.collections.drift = drift;
+                    for (const d of drift) console.log(`${C.yellow}⚠${C.reset} ${C.dim}${d.collection}: ${d.kind} ${d.label} is declared on the server but not in the file (substrio deploy --prune drops it)${C.reset}`);
+                }
+            } catch (err) {
+                if (!DeployRun.isStepFailure(err)) throw err;
+                report.collections = { ...run.failed(err), applied };
+                console.log(`${C.red}✗${C.reset} ${C.bold}Collections${C.reset}: ${C.red}${err.message}${C.reset}`);
+                totalFailed++;
+            }
+        }
+        console.log('');
+    }
+
+    // Roles and sign-in providers: before the rules and functions that name them. An optional provider's
+    // variable that is not set is named on a line of its own and in the report, set or dry run alike.
+    if ((deployAll || onlyFunctions) && identity.unset.length > 0) {
+        for (const entry of identity.unset) console.log(`${C.yellow}⦿${C.reset} ${C.dim}${unsetLine(entry)}${C.reset}`);
+        if (!hasIdentity(identity)) {
+            report.identity = { ok: true, applied: [], unset: identity.unset };
+            console.log('');
+        }
+    }
+    if ((deployAll || onlyFunctions) && hasIdentity(identity)) {
+        if (dryRun) {
+            console.log(`${C.dim}⦿ roles and auth providers from substrio.toml: would apply ${[...identity.roles.map((r) => r.name), ...identity.providers.map((p) => p.provider)].join(', ')}${C.reset}\n`);
+        } else {
+            const applied = [];
+            try {
+                report.identity = { ok: true, ...await applyIdentity((name, input) => run.call(name, input), identity, applied), unset: identity.unset };
+                const label = (title, kind) => (appliedNames(applied, kind).length ? `${C.green}✓${C.reset} ${C.bold}${title}${C.reset} ${C.dim}(${appliedNames(applied, kind).join(', ')})${C.reset}` : null);
+                for (const line of [label('Roles', IdentityKind.ROLE), label('Auth providers', IdentityKind.PROVIDER)]) if (line) console.log(line);
+            } catch (err) {
+                if (!DeployRun.isStepFailure(err)) throw err;
+                report.identity = { ...run.failed(err), applied };
+                console.log(`${C.red}✗${C.reset} ${C.bold}Roles and auth providers${C.reset}: ${C.red}${err.message}${C.reset}`);
+                totalFailed++;
+            }
+            console.log('');
+        }
+    }
+
+    // Permission catalog (UM-2a): append only against what the tenant has
+    // stored; a deploy that declares none leaves it exactly as it was. Before
+    // the functions, whose routes may declare "auth:<name>" against it (UM-2c).
+    if ((deployAll || onlyFunctions) && permissions !== null) {
+        totalFailed += await sendDeclared(run, report, {
+            key: 'permissions', operation: 'permissions.set', body: permissions,
+            would: `set ${permissions.names.length} name(s)`, summary: `${permissions.names.length} name(s)`, dryRun,
+        });
+    }
+
+    // Ledger catalog: append only against what the tenant has stored; a
+    // deploy that declares neither list leaves it exactly as it was.
+    if ((deployAll || onlyFunctions) && ledger !== null) {
+        totalFailed += await sendDeclared(run, report, {
+            key: 'ledger', operation: 'ledger.catalog.set', body: ledger,
+            would: `declare ${ledger.kinds?.length ?? 0} kind(s), ${ledger.categories?.length ?? 0} categor(ies)`,
+            summary: `${ledger.kinds?.length ?? 0} kind(s), ${ledger.categories?.length ?? 0} categor(ies)`, dryRun,
+        });
+    }
+
+    // Deploy Functions (or, named, only the functions asked for)
+    if (deployAll || onlyFunctions || named) {
+        if (!existsSync(functionsDir) && !named) {
+            console.log(`${C.yellow}⚠ No functions/ directory found. Skipping function deployment.${C.reset}`);
+        } else {
+            const files = existsSync(functionsDir) ? readdirSync(functionsDir).filter(f => f.endsWith('.js')) : [];
+            const found = new Set(files.map(f => f.replace(/\.js$/, '')));
+
+            if (named) {
+                const known = new Set([...found, ...Object.keys(config.functions)]);
+                const unknown = names.filter((n) => !known.has(n));
+                if (unknown.length > 0) {
+                    fail(`no function ${unknown.join(', ')} in this project (functions: ${[...known].sort().join(', ') || 'none'})`,
+                        null, ErrorCode.FILE_NOT_FOUND);
+                }
+            } else {
+                const missing = Object.keys(config.functions).filter(name => !found.has(name));
+                if (missing.length > 0) {
+                    fail(`substrio.toml declares ${missing.join(', ')} but ${config.functions_dir}/ has no ${missing.map(n => n + '.js').join(', ')}`,
+                        null, ErrorCode.FILE_NOT_FOUND);
+                }
+            }
+
+            const toDeploy = named ? names : files.map(f => f.replace(/\.js$/, ''));
+            if (toDeploy.length === 0) {
+                console.log(`${C.dim}  No .js files in ${config.functions_dir}/. Skipping.${C.reset}`);
+            } else {
+                console.log(`${C.bold}Functions${C.reset} ${C.dim}(${toDeploy.length} file${toDeploy.length > 1 ? 's' : ''})${C.reset}`);
+
+                for (const name of toDeploy) {
+                    const filePath = join(functionsDir, `${name}.js`);
+                    let built;
+                    try {
+                        built = await buildFunction({ entry: filePath, projectDir: cwd });
+                    } catch (err) {
+                        // Its exit code is exitCodeFor's, the same one a server refusal of this
+                        // function would give: run.failed keeps the first failure for that.
+                        report.functions.push({ name, ...(err instanceof CliError ? run.failed(err) : { ok: false, error: { error: String(err.message ?? err) } }) });
+                        console.log(`  ${C.red}✗${C.reset} ${C.bold}${name}${C.reset}: ${C.red}${err.message}${C.reset}`);
+                        totalFailed++;
+                        continue;
+                    }
+                    const sizeKB = (built.bytes / 1024).toFixed(1);
+                    const bundled = built.inputs.length > 1 ? `, ${built.inputs.length} files bundled` : '';
+
+                    if (dryRun) {
+                        console.log(`  ${C.dim}⦿${C.reset} ${C.bold}${name}${C.reset} ${C.dim}(${sizeKB} KB${bundled}): would deploy${C.reset}`);
+                        report.functions.push({ name, size_bytes: built.bytes, inputs: built.inputs, ok: true, dry_run: true });
+                        totalDeployed++;
+                        continue;
+                    }
+
+                    const step = await run.send('function.deploy', deployment(name, built.code, config.functions[name], cwd, publicDir));
+                    report.functions.push({ name, size_bytes: built.bytes, inputs: built.inputs, ...step });
+                    if (step.ok) {
+                        const hash = step.result?.content_hash ? `, content_hash ${step.result.content_hash}` : '';
+                        console.log(`  ${C.green}✓${C.reset} ${C.bold}${name}${C.reset} ${C.dim}(${sizeKB} KB${bundled}${hash})${C.reset}`);
+                        totalDeployed++;
+                    } else {
+                        console.log(`  ${C.red}✗${C.reset} ${C.bold}${name}${C.reset}: ${C.red}${errorText(step.error, step.error.status)}${C.reset}`);
+                        if (esbuildHint(built, step)) console.log(`    ${C.yellow}⚠${C.reset} ${C.dim}this may need bundling: run \`npm install --save-dev esbuild\` and deploy again${C.reset}`);
+                        totalFailed++;
+                    }
+                }
+            }
+        }
+    }
+
+    // Security rules
+    if ((deployAll || onlyFunctions) && rules !== null) {
+        const from = rules.sources.join(' + ');
+        if (dryRun) {
+            console.log(`\n${C.dim}⦿ rules from ${from}: would set${C.reset}`);
+        } else {
+            report.rules = await run.send('security.rules.set', rules.body);
+            if (report.rules.ok) {
+                console.log(`\n${C.green}✓${C.reset} ${C.bold}rules${C.reset} ${C.dim}from ${from}${C.reset}`);
+            } else {
+                console.log(`\n${C.red}✗${C.reset} ${C.bold}rules${C.reset}: ${C.red}${errorText(report.rules.error, report.rules.error.status)}${C.reset}`);
+                totalFailed++;
+            }
+        }
+    }
+
+    // MCP tools: after the functions whose routes they name (docs/mcp.md)
+    if ((deployAll || onlyFunctions) && config.mcp_file) {
+        const mcpPath = resolve(cwd, config.mcp_file);
+        const mcp = JSON.parse(readFileSync(mcpPath, 'utf-8'));
+        if (dryRun) {
+            console.log(`\n${C.dim}⦿ MCP tools from ${config.mcp_file}: would set ${mcp.tools?.length ?? 0}${C.reset}`);
+        } else {
+            report.mcp_tools = await run.send('mcp.tools.set', mcp);
+            if (report.mcp_tools.ok) {
+                console.log(`\n${C.green}✓${C.reset} ${C.bold}MCP tools${C.reset} ${C.dim}(${report.mcp_tools.result?.tools?.length ?? 0}) from ${config.mcp_file}${C.reset}`);
+            } else {
+                console.log(`\n${C.red}✗${C.reset} ${C.bold}MCP tools${C.reset}: ${C.red}${errorText(report.mcp_tools.error, report.mcp_tools.error.status)}${C.reset}`);
+                totalFailed++;
+            }
+        }
+    }
+
+    // Calls between apps: after the functions an offer names (substrio_app_calls.h). The server
+    // validates the whole document and keeps the word in force when it refuses it.
+    if ((deployAll || onlyFunctions) && !named && config.apps) {
+        const word = { offer: config.apps.offer ?? {}, use: config.apps.use ?? {} };
+        // APP-QUERY: the reads it offers ([apps.query.<name>]: collection, where, select, to, limit) and the ones
+        // of other apps it makes ([apps.use_query]); sent only when declared. After the collections, whose
+        // indexes an offered read names (the server refuses a where field that is not declared indexed).
+        if (config.apps.query !== undefined) word.query = config.apps.query;
+        if (config.apps.use_query !== undefined) word.use_query = config.apps.use_query;
+        if (dryRun) {
+            console.log(`\n${C.dim}⦿ App calls: would offer ${Object.keys(word.offer).length}, use ${Object.keys(word.use).length}${C.reset}`);
+        } else {
+            report.app_calls = await run.send('apps.calls.set', word);
+            if (report.app_calls.ok) {
+                console.log(`\n${C.green}✓${C.reset} ${C.bold}app calls${C.reset} ${C.dim}(offer ${Object.keys(word.offer).length}, use ${Object.keys(word.use).length})${C.reset}`);
+                // An app named that does not exist yet: kept (deploy order is free), each call refused until it does.
+                for (const w of report.app_calls.result?.warnings ?? []) {
+                    console.log(`${C.yellow}⚠${C.reset} ${C.dim}${w.code}: app '${w.app}' does not exist yet${C.reset}`);
+                }
+            } else {
+                console.log(`\n${C.red}✗${C.reset} ${C.bold}app calls${C.reset}: ${C.red}${errorText(report.app_calls.error, report.app_calls.error.status)}${C.reset}`);
+                totalFailed++;
+            }
+        }
+    }
+
+    // Plans: the tenant's counters, per-period caps and feature flags (substrio_plans.h).
+    // Named mode reads no file but its own functions', so this is skipped too.
+    let plans = null;
+    try {
+        plans = named ? null : declaredPlans(config, cwd);
+    } catch (err) {
+        console.log(`\n${C.red}✗${C.reset} ${C.bold}Plans${C.reset}: ${C.red}${err.message}${C.reset}`);
+        const error = new CliError(`${config.plans_file}: ${err.message}`);
+        report.plans = run.failed(error);
+        totalFailed++;
+    }
+    if ((deployAll || onlyFunctions) && plans !== null) {
+        if (dryRun) {
+            console.log(`\n${C.dim}⦿ Plans from ${config.plans_file}: would set ${plans.plans?.length ?? 0}${C.reset}`);
+        } else {
+            report.plans = await run.send('plans.set', plans);
+            if (report.plans.ok) {
+                console.log(`\n${C.green}✓${C.reset} ${C.bold}Plans${C.reset} ${C.dim}(${report.plans.result?.plans?.length ?? 0}) from ${config.plans_file}${C.reset}`);
+            } else {
+                console.log(`\n${C.red}✗${C.reset} ${C.bold}Plans${C.reset}: ${C.red}${errorText(report.plans.error, report.plans.error.status)}${C.reset}`);
+                totalFailed++;
+            }
+        }
+    }
+
+    // Settings tables ([auth], [login]; src/settings.mjs): each set by its own operation, as a
+    // pushed version's go live. After the functions, which a setting may name (email_function).
+    // A table the file does not declare leaves the target's settings as they are.
+    if (deployAll || onlyFunctions) totalFailed += await sendSettings(run, report, settings, dryRun);
+
+    // The site: public/ published as a release by site.mjs's publishSite (the one way `substrio site
+    // deploy` publishes too), so the server holds the files and a deploy to any server carries the
+    // site. Only the files the server lacks are uploaded; the switch is one rename on the server.
+    if (deployAll || onlyAssets) {
+        const files = existsSync(publicDir) ? collect(publicDir, ignoredNames(config)) : [];
+        report.assets = files.length;
+        if (files.length > 0) {
+            console.log(`\n${C.bold}Site${C.reset} ${C.dim}(${files.length} file${files.length > 1 ? 's' : ''} in ${config.public_dir || 'public'}/)${C.reset}`);
+            if (dryRun) {
+                console.log(`  ${C.dim}⦿ would publish a release${C.reset}`);
+            } else {
+                report.site = await run.site(files);
+                if (report.site.ok) {
+                    console.log(`  ${C.green}✓${C.reset} release ${C.bold}${report.site.result.release.id}${C.reset} live: ${uploadedLine(report.site.result, files.length)}`);
+                } else {
+                    console.log(`  ${C.red}✗${C.reset} site: ${C.red}${errorText(report.site.error, report.site.error.status)}${C.reset}`);
+                    totalFailed++;
+                }
+            }
+        }
+    }
+
+    // Summary
+    console.log('');
+    if (dryRun) {
+        console.log(`${C.yellow}⦿${C.reset} Dry run: ${totalDeployed} function(s) would be deployed.`);
+    } else if (totalFailed === 0 && totalDeployed > 0) {
+        console.log(`${C.green}${C.bold}✓ Deployed ${totalDeployed} function${totalDeployed > 1 ? 's' : ''} successfully.${C.reset}`);
+    } else if (totalFailed > 0) {
+        console.log(`${C.yellow}⚠ ${totalDeployed} deployed, ${totalFailed} failed.${C.reset}`);
+    } else if (totalDeployed === 0) {
+        console.log(`${C.dim}Nothing to deploy.${C.reset}`);
+    }
+    console.log('');
+    // --json: the typed report. A deploy that left anything undone fails with
+    // its first failure's exit code, so scripts and CI stop on it.
+    emit({ ...report, deployed: totalDeployed, failed: totalFailed }, () => {});
+    if (totalFailed > 0) process.exitCode = run.firstFailure ? exitCodeFor(run.firstFailure) : ExitCode.FAILURE;
+}
+
+/** The deploy's calls: the server's catalog, read once, and the first failure. */
+class DeployRun {
+    constructor(api) {
+        this.api = api;
+        this.ops = null;
+        this.firstFailure = null;
+    }
+
+    /**
+     * The operation `name` with `input`: the server's data, or a thrown CliError
+     * (the server's typed error; a name or input that does not fit).
+     */
+    async call(name, input) {
+        this.ops ??= await loadOperations(this.api);
+        return callOrThrow(this.api, this.ops, name, input);
+    }
+
+    /**
+     * One step: the operation `name` with `input`. Returns {ok, result} or
+     * {ok: false, error} (the server's typed error), the first failure kept.
+     */
+    async send(name, input) {
+        try {
+            return { ok: true, result: await this.call(name, input) };
+        } catch (err) {
+            if (!DeployRun.isStepFailure(err)) throw err;
+            return this.failed(err);
+        }
+    }
+
+    /** The site's release (site.mjs publishSite) as one step: {ok, result} or {ok: false, error}. */
+    async site(files) {
+        this.ops ??= await loadOperations(this.api);
+        try {
+            return { ok: true, result: await publishSite(this.api, this.ops, files) };
+        } catch (err) {
+            if (!DeployRun.isStepFailure(err)) throw err;
+            return this.failed(err);
+        }
+    }
+
+    /** Whether `err` is a step the server or the input refused (a typed CliError), not a connection that could not be made. */
+    static isStepFailure(err) {
+        return err instanceof CliError && err.code !== ErrorCode.NETWORK_ERROR;
+    }
+
+    /** A failed step's report entry; the first one is the run's exit code. */
+    failed(error) {
+        this.firstFailure ??= error;
+        return { ok: false, error: error.toJSON() };
+    }
+}
+
+/**
+ * The settings tables substrio.toml declares (declaredSettings), each sent as its own
+ * operation through sendDeclared, its result on report[member]. Returns how many failed.
+ */
+export async function sendSettings(run, report, settings, dryRun, log = console.log) {
+    let failed = 0;
+    for (const setting of settings) {
+        const count = Object.keys(setting.values).length;
+        failed += await sendDeclared(run, report, {
+            key: setting.member, operation: setting.operation, body: setting.values,
+            would: `set ${count} setting(s)`, summary: `${setting.label}, ${count} setting(s)`, dryRun,
+        }, log);
+    }
+    return failed;
+}
+
+/**
+ * One table of substrio.toml that a deploy sends as one operation (permissions, ledger).
+ * A dry run prints what it would do and sends nothing. Returns 1 when the send failed,
+ * else 0, and leaves the operation's result on report[key].
+ */
+export async function sendDeclared(run, report, { key, operation, body, would, summary, dryRun }, log = console.log) {
+    if (dryRun) {
+        log(`${C.dim}⦿ ${key} from substrio.toml: would ${would}${C.reset}\n`);
+        return 0;
+    }
+    report[key] = await run.send(operation, body);
+    if (report[key].ok) {
+        log(`${C.green}✓${C.reset} ${C.bold}${key}${C.reset} ${C.dim}(${summary}) from substrio.toml${C.reset}\n`);
+        return 0;
+    }
+    log(`${C.red}✗${C.reset} ${C.bold}${key}${C.reset}: ${C.red}${errorText(report[key].error, report[key].error.status)}${C.reset}\n`);
+    return 1;
+}
+
+// The deploy request for one function: its source plus the routes, entry point
+// and vars substrio.toml declares for it. Only what is declared is sent, so a
+// function substrio.toml says nothing about keeps what it had.
+function deployment(name, script, declared = {}, cwd, siteDir) {
+    // VERSION-VALUES: a deploy makes no version, so site_vars are filled here from the site folder this
+    // deploy publishes, as the server fills them from a version's own site.
+    return { name, script, ...withSiteVars(declaredFunction(name, declared, cwd), siteDir) };
+}
+
+// Whether `step`'s failure of `built` looks like the server refusing an import it cannot resolve:
+// no esbuild was ever asked to bundle this function (so an npm import, if any, is still in the
+// source as sent), and the server's refusal is the generic code deploy.mjs's run.send also uses
+// for every other way a source fails to become a handler. The server has no field of its own
+// naming this case; this is the honest best signal without reading the source again to guess.
+function esbuildHint(built, step) {
+    return built.esbuildAvailable === false && step.error.code === ErrorCode.INVALID_ARGUMENT;
+}
+