@substrio/cli 0.0.0-stage → 0.1.1

package/src/manifest.mjs

@@ -0,0 +1,591 @@
+/**
+ * Substrio CLI: what `substrio push` ships, read from substrio.toml.
+ *
+ *   [[build.steps]]                 # run in order, each in its dir, by sh
+ *   dir = "functions"
+ *   run = "npm ci && npm run build"
+ *
+ *   [site]
+ *   ignore = [".DS_Store"]          # file names left out (default: OS metadata)
+ *   # .br/.gz beside each compressible file of the merged site, made in
+ *   # memory; true, or a table overriding PRECOMPRESS_DEFAULTS. Before the
+ *   # first [[site.parts]], or it lands in that part.
+ *   precompress = { brotli = true, gzip = true, min_bytes = 1024 }
+ *   [[site.parts]]                  # merged in order; a later part's file
+ *   from = "web/dist"               # replaces an earlier one at the same path
+ *   to = "/"
+ *
+ *   [[cron]]
+ *   function = "cleanup"
+ *   expression = "0 3 * * *"
+ *
+ *   [[triggers]]
+ *   type = "insert"
+ *   collection = "users"
+ *   function = "onUser"
+ *
+ *   [queues.emails]                 # a durable queue (docs/runtime/queues.md): the
+ *   consumer = "sendEmail"          # manifest's queue entry, named by its table
+ *   dead_letter_queue = "emails_dead"
+ *   max_retries = 5
+ *
+ * Functions, rules and MCP tools come from what `substrio deploy` already reads:
+ * every .js file in functions_dir, [functions.<name>] routes, main and vars,
+ * rules_file and mcp_file, and the collections_dir (src/collections.mjs), whose
+ * collections' own rules join the rules. The functions here are pure (no network), so the
+ * version body a push sends can be checked without a server.
+ */
+
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { extname, join, relative, resolve } from 'node:path';
+import { brotliCompressSync, constants as zlib, gzipSync } from 'node:zlib';
+
+import { collect, hashFile, ignoredNames, sha256 } from './blobs.mjs';
+import { CliError } from './cli.mjs';
+import { DEFAULT_PUBLIC_DIR } from './config.mjs';
+import { declaredCollections, declaredRules, rulesBlob } from './collections.mjs';
+import { buildFunction } from './function-build.mjs';
+import { readJsonFile } from './jsonfile.mjs';
+
+function table(value, what) {
+    if (value === undefined || value === null) return {};
+    if (typeof value !== 'object' || Array.isArray(value)) throw new Error(`${what} must be a table`);
+    return value;
+}
+
+function list(value, what) {
+    if (value === undefined || value === null) return [];
+    if (!Array.isArray(value)) throw new Error(`${what} must be an array of tables ([[${what}]])`);
+    return value.map((entry, i) => table(entry, `${what}[${i}]`));
+}
+
+function text(entry, key, what, fallback) {
+    const value = entry[key];
+    if (value === undefined && fallback !== undefined) return fallback;
+    if (typeof value !== 'string' || value === '') throw new Error(`${what} needs a string ${key}`);
+    return value;
+}
+
+// A site mount point as a relative posix prefix: "" for the root, else
+// "dir/sub/". No ".." or "." segments.
+// An app that declares no [site] ships public_dir as its site, one part at the root: the folder
+// substrio deploy publishes, so a version (substrio push) carries the same site a deploy does.
+// None when the folder is not there.
+export function publicSiteOf(config, cwd) {
+    const from = config.public_dir || DEFAULT_PUBLIC_DIR;
+    let isDir = false;
+    try { isDir = statSync(resolve(cwd, from)).isDirectory(); } catch { /* no folder: no site */ }
+    return isDir ? { parts: [{ from, to: '/', prefix: '' }], precompress: null } : null;
+}
+
+function mountPrefix(to, what) {
+    const segments = to.split('/').filter(Boolean);
+    if (segments.some((s) => s === '..' || s === '.')) throw new Error(`${what} to must not hold "." or ".." segments`);
+    return segments.length ? `${segments.join('/')}/` : '';
+}
+
+// [site] precompress: the settings scripts/precompress.ts used. Extensions
+// worth compressing (fonts and images already are), files under min_bytes
+// left alone, and a compressed copy kept only when it saves at least
+// min_saving_percent of the file.
+export const PRECOMPRESS_DEFAULTS = Object.freeze({
+    brotli: true,
+    gzip: true,
+    min_bytes: 1024,
+    min_saving_percent: 10,
+    types: ['.html', '.css', '.js', '.mjs', '.json', '.svg', '.xml', '.txt', '.map', '.webmanifest'],
+});
+
+// `precompress = true`, or a table overriding some defaults; absent or false
+// means none. Returns null or {brotli, gzip, min_bytes, min_saving_percent,
+// types: Set}.
+function precompressOf(value) {
+    if (value === undefined || value === false) return null;
+    const given = value === true ? {} : table(value, 'site.precompress');
+    const known = Object.keys(PRECOMPRESS_DEFAULTS);
+    const unknown = Object.keys(given).filter((k) => !known.includes(k));
+    if (unknown.length) throw new Error(`site.precompress has no ${unknown.join(', ')} (it takes ${known.join(', ')})`);
+    const out = { ...PRECOMPRESS_DEFAULTS, ...given };
+    for (const k of ['brotli', 'gzip']) {
+        if (typeof out[k] !== 'boolean') throw new Error(`site.precompress.${k} must be true or false`);
+    }
+    for (const k of ['min_bytes', 'min_saving_percent']) {
+        if (!Number.isInteger(out[k]) || out[k] < 0) throw new Error(`site.precompress.${k} must be a whole number`);
+    }
+    if (out.min_saving_percent > 100) throw new Error('site.precompress.min_saving_percent must be at most 100');
+    if (!Array.isArray(out.types) || out.types.some((t) => typeof t !== 'string' || !t.startsWith('.'))) {
+        throw new Error('site.precompress.types must be an array of extensions such as ".html"');
+    }
+    return { ...out, types: new Set(out.types.map((t) => t.toLowerCase())) };
+}
+
+// The encodings precompress writes, as [suffix, compress].
+const ENCODINGS = [
+    ['brotli', '.br', (body) => brotliCompressSync(body, {
+        params: {
+            [zlib.BROTLI_PARAM_QUALITY]: zlib.BROTLI_MAX_QUALITY,
+            [zlib.BROTLI_PARAM_SIZE_HINT]: body.length,
+        },
+    })],
+    ['gzip', '.gz', (body) => gzipSync(body, { level: zlib.Z_BEST_COMPRESSION })],
+];
+
+/**
+ * The .br and .gz sidecars of a merged site, made in memory, with the site's
+ * own files. Any .br or .gz a part shipped beside a file of the site is
+ * dropped first, so a sidecar always belongs to the file that won the merge.
+ * Returns {files (sorted by path), sidecars: count}.
+ */
+export function precompressSite(files, settings) {
+    const encodingSuffixes = ENCODINGS.map(([, suffix]) => suffix);
+    const paths = new Set(files.map((f) => f.path));
+    const kept = files.filter((f) => {
+        const suffix = encodingSuffixes.find((s) => f.path.endsWith(s));
+        return !suffix || !paths.has(f.path.slice(0, -suffix.length));
+    });
+    const out = [...kept];
+    let sidecars = 0;
+    for (const file of kept) {
+        if (!settings.types.has(extname(file.path).toLowerCase()) || file.size < settings.min_bytes) continue;
+        const body = file.data ?? readFileSync(file.abs);
+        for (const [name, suffix, compress] of ENCODINGS) {
+            if (!settings[name]) continue;
+            const data = compress(body);
+            if (data.length * 100 > body.length * (100 - settings.min_saving_percent)) continue;
+            out.push({ path: file.path + suffix, data, size: data.length, hash: sha256(data) });
+            sidecars++;
+        }
+    }
+    out.sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+    return { files: out, sidecars };
+}
+
+/**
+ * The push tables of a loaded config (src/config.mjs), checked and normalized:
+ * { build: [{dir, run}], site: {parts: [{from, to, prefix}]} | null,
+ *   cron: [{function, expression}], triggers: [{type, collection, function}],
+ *   queues: [{name, consumer?, dead_letter_queue?, <settings>}] }.
+ * Throws with the table at fault.
+ */
+export function manifestOf(config) {
+    // [build] steps = [...], [[build.steps]], or [[build]] tables alike.
+    const build = Array.isArray(config.build)
+        ? list(config.build, 'build')
+        : list(table(config.build, 'build').steps, 'build.steps');
+    const steps = build.map((step, i) => ({
+        dir: text(step, 'dir', `build step ${i + 1}`, '.'),
+        run: text(step, 'run', `build step ${i + 1}`),
+    }));
+
+    let site = null;
+    if (config.site !== undefined && config.site !== null) {
+        const declared = table(config.site, 'site');
+        const parts = list(declared.parts, 'site.parts').map((part, i) => {
+            const what = `site part ${i + 1}`;
+            const extra = Object.keys(part).filter((k) => k !== 'from' && k !== 'to');
+            if (extra.length) {
+                throw new Error(`${what} takes from and to, not ${extra.join(', ')} (a [site] key goes before the first [[site.parts]])`);
+            }
+            const to = text(part, 'to', what, '/');
+            return { from: text(part, 'from', what), to, prefix: mountPrefix(to, what) };
+        });
+        if (parts.length === 0) throw new Error('[site] needs at least one [[site.parts]] with a from directory');
+        if (declared.ignore !== undefined && !Array.isArray(declared.ignore)) {
+            throw new Error('site.ignore must be an array of file names');
+        }
+        site = { parts, precompress: precompressOf(declared.precompress) };
+    }
+
+    const cron = list(config.cron, 'cron').map((entry, i) => ({
+        function: text(entry, 'function', `cron ${i + 1}`),
+        expression: text(entry, 'expression', `cron ${i + 1}`),
+    }));
+    const triggers = list(config.triggers, 'triggers').map((entry, i) => ({
+        type: text(entry, 'type', `trigger ${i + 1}`),
+        collection: text(entry, 'collection', `trigger ${i + 1}`),
+        function: text(entry, 'function', `trigger ${i + 1}`),
+    }));
+
+    return { build: steps, site, cron, triggers, queues: queuesOf(config.queues) };
+}
+
+/**
+ * [queues.<name>] tables as the version manifest's `queues` array
+ * ([{name, consumer, dead_letter_queue, <settings>}], declaration order). The
+ * fields are the manifest's own; the server (substrio_queue.h) owns which exist and
+ * their ranges, so each is passed as written and refused there with its name.
+ * A name with a "." cannot be a table header: it would nest.
+ */
+function queuesOf(declared) {
+    return Object.entries(table(declared, 'queues')).map(([name, entry]) => {
+        const what = `queues.${name}`;
+        const fields = table(entry, what);
+        if ('name' in fields) throw new Error(`${what} is named by its table; remove its name`);
+        for (const [key, value] of Object.entries(fields)) {
+            if (typeof value !== 'string' && !Number.isInteger(value)) {
+                throw new Error(`${what}.${key} must be a string or a whole number`);
+            }
+        }
+        return { name, ...fields };
+    });
+}
+
+/**
+ * functions.<name>.routes_file: a JSON file, relative to the project file, of
+ * the function's route specs (the same strings `routes` takes), read and
+ * parsed once so the request carries the resolved array and the server never
+ * knows a routes_file existed. An entry already resolved (no routes_file left)
+ * comes back as it is, with no file read. `routes` and `routes_file` both
+ * given is refused, naming the function; a bad file is refused naming the
+ * file, and, for one entry, its position.
+ * Called by declaredFunction, the one place a function's declaration becomes
+ * a request, so no command can send a function without its routes file
+ * (`substrio deploy` once did: every route answered 404); collectApp calls it
+ * first so one apply reads the file once.
+ */
+function resolveDeclaredRoutes(cwd, name, declared) {
+    if (declared.routes_file === undefined) return declared;
+    if (declared.routes !== undefined) {
+        throw new Error(`functions.${name} declares both routes and routes_file; remove one`);
+    }
+    const file = declared.routes_file;
+    const parsed = readJsonFile(resolve(cwd, file), 'routes_file', file);
+    if (!Array.isArray(parsed)) throw new Error(`routes_file ${file} must be an array of strings`);
+    parsed.forEach((route, i) => {
+        if (typeof route !== 'string') throw new Error(`routes_file ${file}[${i}] must be a string`);
+    });
+    const { routes_file, ...rest } = declared;
+    return { ...rest, routes: parsed };
+}
+
+// A path prefix: a leading slash, no trailing slash, no whitespace, query or fragment.
+const ROUTE_PREFIX = /^\/[^\s?#]*[^\s/?#]$/;
+
+/**
+ * functions.<name>.route_prefix: one path every route of the function is served under (an app
+ * whose clients call `/api/v1/...` while its route table names `/users/me`). Applied here, once
+ * per route at deploy, so the server only ever sees whole routes: nothing per request. A route is
+ * `METHOD /path[ GATE]`; the prefix goes between the method and the path (`GET /` becomes
+ * `GET /api/v1`). An entry with no space is left as it is, for the server to refuse by name.
+ */
+function prefixedRoutes(name, prefix, routes) {
+    if (typeof prefix !== 'string' || !ROUTE_PREFIX.test(prefix)) {
+        throw new Error(`functions.${name}.route_prefix must be a path like "/api/v1" (a leading slash, no trailing slash)`);
+    }
+    return routes.map((route) => {
+        const space = route.indexOf(' ');
+        if (space === -1) return route;
+        const path = route.slice(space + 1);
+        const bare = path === '/' || path.startsWith('/ ');
+        return route.slice(0, space + 1) + prefix + (bare ? path.slice(1) : path);
+    });
+}
+
+/**
+ * What substrio.toml declares for one function beyond its source: routes
+ * (given inline or through routes_file, relative to `cwd`, under route_prefix
+ * when one is declared), main and vars, only those given, checked. Shared with
+ * `substrio deploy`. vars_env (VERSION-VALUES): names whose values are read from
+ * this run's environment into vars, so a value that differs per place an app is
+ * deployed to is still the version's own (promote carries it, nothing is set
+ * outside the version); a name the environment does not hold is refused, by
+ * name, and a name in both vars and vars_env is refused (one owner a value).
+ */
+export function declaredFunction(name, declared = {}, cwd = process.cwd(), env = process.env) {
+    declared = resolveDeclaredRoutes(cwd, name, declared);
+    const out = {};
+    if (declared.routes !== undefined) {
+        if (!Array.isArray(declared.routes) || declared.routes.some((r) => typeof r !== 'string')) {
+            throw new Error(`functions.${name}.routes must be an array of strings`);
+        }
+        out.routes = declared.route_prefix === undefined
+            ? declared.routes : prefixedRoutes(name, declared.route_prefix, declared.routes);
+    } else if (declared.route_prefix !== undefined) {
+        throw new Error(`functions.${name}.route_prefix needs routes or routes_file`);
+    }
+    if (declared.main !== undefined) out.main = String(declared.main);
+    if (declared.vars !== undefined) {
+        if (typeof declared.vars !== 'object' || Array.isArray(declared.vars)) {
+            throw new Error(`functions.${name}.vars must be a table`);
+        }
+        out.vars = Object.fromEntries(
+            Object.entries(declared.vars).map(([key, value]) => [key, String(value)]));
+    }
+    if (declared.vars_env !== undefined) {
+        if (!Array.isArray(declared.vars_env) || declared.vars_env.some((k) => typeof k !== 'string' || k === '')) {
+            throw new Error(`functions.${name}.vars_env must be an array of variable names`);
+        }
+        out.vars ??= {};
+        for (const key of declared.vars_env) {
+            if (Object.hasOwn(out.vars, key)) throw new Error(`functions.${name}: ${key} is in both vars and vars_env`);
+            const value = env[key];
+            if (value === undefined) throw new Error(`functions.${name}.vars_env: ${key} is not set in the environment`);
+            out.vars[key] = value;
+        }
+    }
+    // VERSION-VALUES: {NAME: site path}, filled on the server from the version's own site (NAME and NAME_HASH).
+    if (declared.site_vars !== undefined) {
+        const entries = typeof declared.site_vars === 'object' && !Array.isArray(declared.site_vars)
+            ? Object.entries(declared.site_vars) : null;
+        if (!entries || entries.some(([, path]) => typeof path !== 'string' || path === '')) {
+            throw new Error(`functions.${name}.site_vars must be a table of names to site paths`);
+        }
+        for (const [key] of entries) {
+            if (out.vars && (Object.hasOwn(out.vars, key) || Object.hasOwn(out.vars, `${key}${SITE_VAR_HASH_SUFFIX}`))) {
+                throw new Error(`functions.${name}: site var ${key} is also in vars`);
+            }
+        }
+        out.site_vars = Object.fromEntries(entries);
+    }
+    // APP-MCP: which routes are the app's MCP tools (every one when absent): false, or a table keyed by the
+    // route as declared, each false or {name, description, inputSchema, ...}. The server checks the entries.
+    if (declared.tools !== undefined) {
+        const table = typeof declared.tools === 'object' && declared.tools !== null && !Array.isArray(declared.tools);
+        if (declared.tools !== false && declared.tools !== true && !table) {
+            throw new Error(`functions.${name}.tools must be false or a table keyed by a declared route`);
+        }
+        out.tools = declared.tools;
+    }
+    return out;
+}
+
+// A site var's hash value: NAME + this, the file's SHA-256 in its first 16 hex (substrio_versions.h's
+// SITE_VAR_HASH_SUFFIX and SITE_VAR_HASH_HEX).
+export const SITE_VAR_HASH_SUFFIX = '_HASH';
+const SITE_VAR_HASH_HEX = 16;
+
+/**
+ * A declared function for a deploy that makes no version (`substrio deploy`, a local stack): its site_vars
+ * filled from the site folder on disk as the server fills them from a version's own site (NAME the file's
+ * text, NAME_HASH its SHA-256's first 16 hex), so a function reads the same values either way.
+ */
+export function withSiteVars(declared, siteDir) {
+    if (!declared.site_vars) return declared;
+    const { site_vars: siteVars, ...rest } = declared;
+    const vars = { ...(rest.vars ?? {}) };
+    for (const [key, path] of Object.entries(siteVars)) {
+        const file = resolve(siteDir, path);
+        if (!existsSync(file)) throw new Error(`site var ${key}: ${path} is not in the site (${siteDir})`);
+        const bytes = readFileSync(file);
+        vars[key] = bytes.toString('utf8');
+        vars[`${key}${SITE_VAR_HASH_SUFFIX}`] = sha256(bytes).slice(0, SITE_VAR_HASH_HEX);
+    }
+    return { ...rest, vars };
+}
+
+/**
+ * substrio.toml's [permissions] table, as permissions.set's body:
+ * {names, all?, implies?}. null when the project declares none. Only the
+ * shape is checked here (names and implies values are string arrays, all a
+ * string); compile_permission_catalog on the server makes every declaration
+ * error (a bad name, too many names, an unknown implies name, append-only
+ * against the stored names).
+ *
+ *   [permissions]
+ *   names = ["VIEW_EVENTS", "EDIT_EVENTS", "FULL_ACCESS"]
+ *   all = "FULL_ACCESS"
+ *   [permissions.implies]
+ *   EDIT_EVENTS = ["VIEW_EVENTS"]
+ *
+ * The ONE loader `substrio deploy` and `substrio push` both read, so a table
+ * resolved for one is resolved the same way for the other (EV-SX4).
+ */
+export function declaredPermissions(config) {
+    if (config.permissions === undefined || config.permissions === null) return null;
+    const declared = table(config.permissions, 'permissions');
+    const extra = Object.keys(declared).filter((k) => k !== 'names' && k !== 'all' && k !== 'implies');
+    if (extra.length) throw new Error(`permissions takes names, all, implies, not ${extra.join(', ')}`);
+    if (!Array.isArray(declared.names) || declared.names.some((n) => typeof n !== 'string')) {
+        throw new Error('permissions.names must be an array of strings');
+    }
+    const body = { names: declared.names };
+    if (declared.all !== undefined) body.all = text(declared, 'all', 'permissions');
+    if (declared.implies !== undefined) {
+        const implies = table(declared.implies, 'permissions.implies');
+        for (const [key, value] of Object.entries(implies)) {
+            if (!Array.isArray(value) || value.some((v) => typeof v !== 'string')) {
+                throw new Error(`permissions.implies.${key} must be an array of strings`);
+            }
+        }
+        body.implies = implies;
+    }
+    return body;
+}
+
+/**
+ * substrio.toml's [ledger] table, as ledger.catalog.set's body: {kinds?,
+ * categories?}. null when the project declares none, or declares neither
+ * list. A list left out of the body is read by the operation as "stands"
+ * (the stored list for that part of the catalog is unchanged).
+ *
+ *   [ledger]
+ *   kinds = ["HOST", "AGENT"]
+ *   categories = ["SALE", "REFUND"]
+ *
+ * The ONE loader `substrio deploy` and `substrio push` both read, so a table
+ * resolved for one is resolved the same way for the other (EV-SX4).
+ */
+export function declaredLedger(config) {
+    if (config.ledger === undefined || config.ledger === null) return null;
+    const declared = table(config.ledger, 'ledger');
+    const extra = Object.keys(declared).filter((k) => k !== 'kinds' && k !== 'categories');
+    if (extra.length) throw new Error(`ledger takes kinds, categories, not ${extra.join(', ')}`);
+    const body = {};
+    if (declared.kinds !== undefined) {
+        if (!Array.isArray(declared.kinds) || declared.kinds.some((k) => typeof k !== 'string')) {
+            throw new Error('ledger.kinds must be an array of strings');
+        }
+        body.kinds = declared.kinds;
+    }
+    if (declared.categories !== undefined) {
+        if (!Array.isArray(declared.categories) || declared.categories.some((c) => typeof c !== 'string')) {
+            throw new Error('ledger.categories must be an array of strings');
+        }
+        body.categories = declared.categories;
+    }
+    if (body.kinds === undefined && body.categories === undefined) return null;
+    return body;
+}
+
+// A JSON file as a blob; it must parse, so a broken file stops the push here.
+function jsonBlob(cwd, file, what) {
+    const abs = resolve(cwd, file);
+    readJsonFile(abs, what, file);
+    return { path: file, ...hashFile(abs) };
+}
+
+/**
+ * Every file of the app, from disk, hashed:
+ * { functions: [{name, path, data, inputs, size, hash, esbuildAvailable, declared, buildError?}],
+ *   rules, mcp, collections: [{name, file, schema, rules, indexes}],
+ *   site: {files: [{path, abs, size, hash}], replaced: [path]} | null }.
+ * A function's `data` is what buildFunction (function-build.mjs, the one
+ * owner of a function's bytes) sent back for it, already bundled where
+ * bundling was needed; `hash` and `size` are of those bytes, not the file's.
+ * A function whose build failed locally (a syntax error, an unresolvable
+ * import) is not left out and does not fail the other functions: `data` is
+ * its entry file's own bytes (what every path sent before a bundler existed),
+ * and `buildError` is the thrown CliError (its `diagnostics`, in function.check's
+ * shape, are the caller's to report instead of sending function.check at all;
+ * manifest.mjs never calls the server itself).
+ * `inputs` are every file (relative to `cwd`) the upload was built from, the
+ * entry included: what a change to any of them invalidates.
+ * `rules` is rules_file as it is, or, when collections declare rules of their
+ * own, the merged rules made in memory.
+ * Site parts are merged by target path in order: a later part's file replaces
+ * an earlier one at the same path, and `replaced` names each such path.
+ *
+ * @param {Map<string, object>} [functionCache] forwarded to buildFunction for
+ *   every function (substrio dev's Reloader keeps one across applies).
+ * @param {(projectDir: string) => string | null} [resolveEsbuild] forwarded to
+ *   buildFunction (its own default is the real resolution); tests state their own.
+ */
+export async function collectApp(config, manifest, cwd = process.cwd(), functionCache, resolveEsbuild) {
+    const functionsDir = resolve(cwd, config.functions_dir || 'functions');
+    const declared = config.functions || {};
+    const files = existsSync(functionsDir)
+        ? readdirSync(functionsDir).filter((f) => f.endsWith('.js')).sort()
+        : [];
+    const found = new Set(files.map((f) => f.replace(/\.js$/, '')));
+    const missing = Object.keys(declared).filter((name) => !found.has(name));
+    if (missing.length > 0) {
+        throw new Error(`substrio.toml declares ${missing.join(', ')} but ${config.functions_dir}/ has no ` +
+            `${missing.map((n) => `${n}.js`).join(', ')} (did the build run?)`);
+    }
+    const functions = await Promise.all(files.map(async (file) => {
+        const name = file.replace(/\.js$/, '');
+        const entry = join(functionsDir, file);
+        // routes_file is read and parsed once here, whether or not the build below
+        // fails, so a function's declared routes are always the resolved array.
+        const fnDeclared = resolveDeclaredRoutes(cwd, name, declared[name] || {});
+        let built;
+        try {
+            built = await buildFunction({ entry, projectDir: cwd, cache: functionCache, resolveEsbuild });
+        } catch (err) {
+            if (!(err instanceof CliError)) throw err;
+            // A function that does not build locally still gets to the rest of the app: the bytes
+            // sent on its behalf are its own, exactly what every path sent before a bundler existed
+            // (the server, or the caller here, is the one to refuse it; collectApp never does).
+            const data = readFileSync(entry);
+            return {
+                name, path: `${config.functions_dir}/${file}`,
+                data, size: data.length, hash: sha256(data), inputs: [relative(cwd, entry)],
+                esbuildAvailable: true, declared: fnDeclared, buildError: err,
+            };
+        }
+        const data = Buffer.from(built.code, 'utf-8');
+        return {
+            name, path: `${config.functions_dir}/${file}`,
+            data, size: built.bytes, hash: sha256(data), inputs: built.inputs,
+            esbuildAvailable: built.esbuildAvailable, declared: fnDeclared,
+        };
+    }));
+
+    const collections = declaredCollections(config, cwd);
+    const declaredRulesOf = declaredRules(config, cwd, collections);
+    let rules = null;
+    if (declaredRulesOf !== null) {
+        rules = declaredRulesOf.merged ? rulesBlob(declaredRulesOf) : jsonBlob(cwd, config.rules_file, 'rules_file');
+    }
+    const mcp = config.mcp_file ? jsonBlob(cwd, config.mcp_file, 'mcp_file') : null;
+
+    let site = null;
+    const declaredSite = manifest.site ?? publicSiteOf(config, cwd);
+    if (declaredSite) {
+        const ignore = ignoredNames(config);
+        const byPath = new Map();
+        const replaced = [];
+        for (const part of declaredSite.parts) {
+            const root = resolve(cwd, part.from);
+            let isDir = false;
+            try { isDir = statSync(root).isDirectory(); } catch { /* reported below */ }
+            if (!isDir) throw new Error(`site part ${part.from} is not a directory (did the build run?)`);
+            for (const file of collect(root, ignore)) {
+                const path = part.prefix + file.path;
+                if (byPath.has(path)) replaced.push(path);
+                byPath.set(path, { ...file, path });
+            }
+        }
+        let merged = [...byPath.values()].sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+        let sidecars = 0;
+        if (declaredSite.precompress) ({ files: merged, sidecars } = precompressSite(merged, declaredSite.precompress));
+        site = { files: merged, replaced, sidecars };
+    }
+
+    return { functions, rules, mcp, collections, site };
+}
+
+/**
+ * The POST /v1/_versions body for a collected app (pure):
+ * {message?, functions: [{name, hash, size, main?, routes?, vars?}],
+ *  rules, mcp, site: {files: [{path, hash, size}]} | null, cron, triggers, queues}.
+ */
+export function versionBody(app, manifest, message) {
+    const blob = (b) => (b ? { hash: b.hash, size: b.size } : null);
+    const body = {};
+    if (message !== undefined && message !== null) body.message = String(message);
+    // A function names its source by hash and size on itself
+    // (substrio_versions.cpp parse_function).
+    body.functions = app.functions.map((f) => ({
+        name: f.name,
+        ...blob(f),
+        ...declaredFunction(f.name, f.declared),
+    }));
+    body.rules = blob(app.rules);
+    body.mcp = blob(app.mcp);
+    body.site = app.site ? { files: app.site.files.map(({ path, hash, size }) => ({ path, hash, size })) } : null;
+    body.cron = manifest.cron.map((c) => ({ function: c.function, expression: c.expression }));
+    body.triggers = manifest.triggers.map((t) => ({ type: t.type, collection: t.collection, function: t.function }));
+    body.queues = manifest.queues.map((q) => ({ ...q }));
+    return body;
+}
+
+// Every blob of a collected app by hash, for the uploader.
+export function blobsByHash(app) {
+    const byHash = new Map();
+    for (const f of app.functions) byHash.set(f.hash, f);
+    if (app.rules) byHash.set(app.rules.hash, app.rules);
+    if (app.mcp) byHash.set(app.mcp.hash, app.mcp);
+    for (const f of app.site?.files || []) byHash.set(f.hash, f);
+    return byHash;
+}