@bridgeline-digital/hawk-app-cli 0.1.0-dev.20261020202308 → 0.1.0

package/src/functions.mjs

@@ -1,313 +1,313 @@
-import { existsSync, readFileSync } from 'node:fs';
-import { readdir, readFile } from 'node:fs/promises';
-import { createRequire } from 'node:module';
-import { dirname, join, relative, resolve, sep } from 'node:path';
-import { zipSync } from 'fflate';
-
-// App functions (`functions:invoke`): functions/<name>.ts (or .js/.mts/.mjs) next to hawk-app.json, declared under
-// "functions" in the manifest, bundled with esbuild into one index.mjs per function and deployed with each version
-// as an AWS Lambda version. Same limits as the platform, which validates again on deploy.
-export const FUNCTIONS_DIR = 'functions';
-export const FUNCTIONS_SCOPE = 'functions:invoke';
-export const BRIDGE_PACKAGE = '@bridgeline-digital/hawk-app-bridge';
-export const MAX_FUNCTIONS = 10;
-export const MAX_NAME_LENGTH = 40;
-export const MAX_SECRETS = 20;
-export const TIMEOUT = { min: 1, max: 25, default: 10 };
-/** Background jobs ("job": true): started with app.functions.start, not called, so they may run longer. */
-export const JOB_TIMEOUT = { min: 1, max: 900, default: 300 };
-export const MEMORY = { min: 128, max: 1024, default: 256 };
-export const MAX_BUNDLE_BYTES = 10 * 1024 * 1024;
-export const MAX_SOURCE_BYTES = 5 * 1024 * 1024;
-export const ENTRY_EXTENSIONS = ['.ts', '.mts', '.js', '.mjs'];
-
-export const FUNCTION_NAME = /^[a-z0-9]+(-[a-z0-9]+)*$/;
-export const SECRET_NAME = /^[A-Z][A-Z0-9_]{0,63}$/;
-const CONFIG_KEYS = ['job', 'timeoutSeconds', 'memoryMb', 'secrets', 'clientSecrets'];
-const MAX_CLIENT_SECRETS = 10;
-/** Fixed zip entry time, so a zip's bytes (and the Lambda codeSha256) only change when the code does. */
-const ZIP_TIME = new Date(1980, 0, 1, 0, 0, 0);
-
-/**
- * Checks the manifest's "functions" block (names, settings, the functions:invoke scope).
- * @returns {string[]} errors
- */
-export function validateFunctionsManifest(manifest) {
-    const errors = [];
-    const functions = manifest?.functions;
-    if (functions === undefined) return errors;
-    if (!functions || typeof functions !== 'object' || Array.isArray(functions)) {
-        errors.push('functions must be an object: { "<name>": { "timeoutSeconds": 10, "memoryMb": 256, "secrets": [] } }.');
-        return errors;
-    }
-    const names = Object.keys(functions);
-    if (names.length > MAX_FUNCTIONS) errors.push(`functions: at most ${MAX_FUNCTIONS} functions per app (found ${names.length}).`);
-    for (const name of names) {
-        const where = `functions.${name}`;
-        if (!FUNCTION_NAME.test(name) || name.length > MAX_NAME_LENGTH) {
-            errors.push(`${where}: function names must be 1-${MAX_NAME_LENGTH} lowercase letters, digits and single dashes (e.g. "sync-feed").`);
-        }
-        const config = functions[name];
-        if (!config || typeof config !== 'object' || Array.isArray(config)) {
-            errors.push(`${where} must be an object, e.g. { "timeoutSeconds": 10, "memoryMb": 256, "secrets": [] } (or {} for the defaults).`);
-            continue;
-        }
-        const unknown = Object.keys(config).filter((key) => !CONFIG_KEYS.includes(key));
-        if (unknown.length) errors.push(`${where}: unknown setting${unknown.length === 1 ? '' : 's'} ${unknown.map((k) => `"${k}"`).join(', ')} (allowed: ${CONFIG_KEYS.join(', ')}).`);
-        if (config.job !== undefined && typeof config.job !== 'boolean') errors.push(`${where}.job must be true or false.`);
-        const timeout = config.job === true ? JOB_TIMEOUT : TIMEOUT;
-        if (config.timeoutSeconds !== undefined && !isIntIn(config.timeoutSeconds, timeout)) {
-            const hint = config.job === true ? '' : `; up to ${JOB_TIMEOUT.max} with "job": true`;
-            errors.push(`${where}.timeoutSeconds must be a whole number from ${timeout.min} to ${timeout.max} (default ${timeout.default}${hint}).`);
-        }
-        if (config.memoryMb !== undefined && !isIntIn(config.memoryMb, MEMORY)) {
-            errors.push(`${where}.memoryMb must be a whole number from ${MEMORY.min} to ${MEMORY.max} (default ${MEMORY.default}).`);
-        }
-        if (config.secrets !== undefined) {
-            const secrets = config.secrets;
-            if (!Array.isArray(secrets)) {
-                errors.push(`${where}.secrets must be a list of names, e.g. ["FEED_API_KEY"].`);
-            } else {
-                const bad = secrets.filter((s) => typeof s !== 'string' || !SECRET_NAME.test(s));
-                if (bad.length) errors.push(`${where}.secrets: ${bad.map((s) => JSON.stringify(s)).join(', ')} must be UPPER_SNAKE_CASE names (a letter, then letters, digits or _; up to 64).`);
-                const duplicates = [...new Set(secrets.filter((s, i) => secrets.indexOf(s) !== i))];
-                if (duplicates.length) errors.push(`${where}.secrets lists ${duplicates.join(', ')} more than once.`);
-                if (secrets.length > MAX_SECRETS) errors.push(`${where}.secrets: at most ${MAX_SECRETS} secrets per function.`);
-            }
-        }
-        if (config.clientSecrets !== undefined) {
-            const names = config.clientSecrets;
-            if (!Array.isArray(names)) {
-                errors.push(`${where}.clientSecrets must be a list of names, e.g. ["MAILCHIMP_API_KEY"].`);
-            } else {
-                const bad = names.filter((s) => typeof s !== 'string' || !SECRET_NAME.test(s));
-                if (bad.length) errors.push(`${where}.clientSecrets: ${bad.map((s) => JSON.stringify(s)).join(', ')} must be UPPER_SNAKE_CASE names (a letter, then letters, digits or _; up to 64).`);
-                const duplicates = [...new Set(names.filter((s, i) => names.indexOf(s) !== i))];
-                if (duplicates.length) errors.push(`${where}.clientSecrets lists ${duplicates.join(', ')} more than once.`);
-                if (names.length > MAX_CLIENT_SECRETS) errors.push(`${where}.clientSecrets: at most ${MAX_CLIENT_SECRETS} client secrets per function.`);
-            }
-        }
-    }
-    if (names.length && !(manifest.scopes ?? []).includes(FUNCTIONS_SCOPE)) {
-        errors.push(`functions need the "${FUNCTIONS_SCOPE}" scope: add it to "scopes" in hawk-app.json.`);
-    }
-    return errors;
-}
-
-const isIntIn = (value, { min, max }) => Number.isInteger(value) && value >= min && value <= max;
-
-/** A function's settings with the defaults filled in, as sent to the platform. */
-export function functionConfig(config = {}) {
-    const job = config.job === true;
-    return {
-        job,
-        timeoutSeconds: config.timeoutSeconds ?? (job ? JOB_TIMEOUT : TIMEOUT).default,
-        memoryMb: config.memoryMb ?? MEMORY.default,
-        secrets: config.secrets ?? [],
-        clientSecrets: config.clientSecrets ?? [],
-    };
-}
-
-/**
- * Matches the manifest's functions with the entry files in `<projectDir>/functions`. Null when the app has neither.
- * Every declared function needs functions/<name>.(ts|mts|js|mjs), and every entry file there needs a manifest entry
- * (shared code goes in subfolders such as functions/lib/).
- * @returns {Promise<{ functions: { name: string, entry: string, config: object }[], errors: string[] } | null>}
- */
-export async function loadFunctions(projectDir, manifest) {
-    const declared = manifest?.functions && typeof manifest.functions === 'object' && !Array.isArray(manifest.functions) ? manifest.functions : {};
-    const dir = join(projectDir, FUNCTIONS_DIR);
-    const hasDir = existsSync(dir);
-    if (!hasDir && !Object.keys(declared).length) return null;
-
-    const errors = [];
-    const entries = new Map();
-    if (hasDir) {
-        for (const entry of await readdir(dir, { withFileTypes: true })) {
-            if (!entry.isFile() || entry.name.startsWith('.') || entry.name.endsWith('.d.ts')) continue;
-            const ext = ENTRY_EXTENSIONS.find((e) => entry.name.endsWith(e));
-            if (!ext) continue;
-            const name = entry.name.slice(0, -ext.length);
-            if (entries.has(name)) {
-                errors.push(`${FUNCTIONS_DIR}/: ${name} has more than one entry file (${entries.get(name).file} and ${entry.name}); keep one.`);
-                continue;
-            }
-            entries.set(name, { file: entry.name, full: join(dir, entry.name) });
-        }
-    }
-
-    const functions = [];
-    for (const name of Object.keys(declared).sort()) {
-        const entry = entries.get(name);
-        if (!entry) {
-            errors.push(`functions.${name} has no entry file: add ${FUNCTIONS_DIR}/${name}.ts (or .js/.mts/.mjs) exporting \`handler\`.`);
-            continue;
-        }
-        functions.push({ name, entry: entry.full, config: functionConfig(declared[name]) });
-    }
-    for (const [name, entry] of entries) {
-        if (!(name in declared)) {
-            errors.push(`${FUNCTIONS_DIR}/${entry.file} is not declared in hawk-app.json: add "${name}": {} under "functions", or move shared code into a subfolder (e.g. ${FUNCTIONS_DIR}/lib/).`);
-        }
-    }
-    if (hasDir && !entries.size && !Object.keys(declared).length) {
-        errors.push(`${FUNCTIONS_DIR}/ has no functions: add ${FUNCTIONS_DIR}/<name>.ts and declare it under "functions" in hawk-app.json, or remove the folder.`);
-    }
-    return { functions, errors };
-}
-
-/**
- * Checks that the app has a bridge with the `/server` entry (the wrapper imports `toLambdaHandler` from it).
- * @returns {string | null} an error message, or null when it's fine
- */
-export function checkBridge(projectDir) {
-    let packageFile;
-    try {
-        packageFile = createRequire(join(projectDir, 'package.json')).resolve(`${BRIDGE_PACKAGE}/package.json`);
-    } catch {
-        return `Functions need ${BRIDGE_PACKAGE} in the app: run \`npm install ${BRIDGE_PACKAGE}\`.`;
-    }
-    const pkg = JSON.parse(readFileSync(packageFile, 'utf8'));
-    if (!pkg.exports?.['./server']) {
-        return `${BRIDGE_PACKAGE} ${pkg.version} has no "/server" entry: update it (\`npm install ${BRIDGE_PACKAGE}@latest\`).`;
-    }
-    return null;
-}
-
-/** The generated entry: the user's module wrapped as the Lambda handler. */
-export function wrapperSource(entry) {
-    const userModule = entry.split(sep).join('/');
-    return [
-        `import { toLambdaHandler } from '${BRIDGE_PACKAGE}/server';`,
-        `import { handler as userHandler } from ${JSON.stringify(userModule)};`,
-        'export const handler = toLambdaHandler(userHandler);',
-        '',
-    ].join('\n');
-}
-
-/**
- * Bundles one function (esbuild: node22, ESM, every dependency included) and packs what the platform needs:
- * `bundle.zip` (index.mjs exporting `handler`), `source.zip` (every file under functions/, for review) and
- * `deps.json` ([{ name, version }] of the packages in the bundle).
- * @returns {Promise<{ name: string, files: { path: string, size: number, data: Uint8Array }[], bundleBytes: number, deps: { name: string, version: string }[] }>}
- */
-export async function buildFunction({ projectDir, name, entry, sourceZip }) {
-    const problem = checkBridge(projectDir);
-    if (problem) throw new Error(problem);
-    const esbuild = await import('esbuild');
-    let result;
-    try {
-        result = await esbuild.build({
-            stdin: { contents: wrapperSource(entry), resolveDir: projectDir, sourcefile: `hawk-function-${name}.mjs`, loader: 'js' },
-            absWorkingDir: projectDir,
-            bundle: true,
-            platform: 'node',
-            target: 'node22',
-            format: 'esm',
-            outfile: 'index.mjs',
-            write: false,
-            metafile: true,
-            logLevel: 'silent',
-            legalComments: 'none',
-            // CommonJS dependencies that call require() need it in an ES module.
-            banner: { js: "import { createRequire as __hawkCreateRequire } from 'node:module';\nconst require = __hawkCreateRequire(import.meta.url);" },
-        });
-    } catch (error) {
-        const messages = (error.errors ?? []).map((e) => `  ${e.location ? `${e.location.file}:${e.location.line}: ` : ''}${e.text}`);
-        const missingHandler = (error.errors ?? []).some((e) => /No matching export .* for import "handler"/.test(e.text));
-        throw new Error(
-            `Could not bundle function "${name}"${missingHandler ? ` (${FUNCTIONS_DIR}/${name} must export \`handler\`)` : ''}:\n${messages.join('\n') || `  ${error.message}`}`,
-        );
-    }
-    const code = result.outputFiles.find((f) => f.path.endsWith('index.mjs')).contents;
-    const bundle = zip({ 'index.mjs': code });
-    if (bundle.length > MAX_BUNDLE_BYTES) {
-        throw new Error(`Function "${name}" is ${formatMb(bundle.length)} zipped; the limit is ${formatMb(MAX_BUNDLE_BYTES)}. Drop large dependencies.`);
-    }
-    const deps = dependencies(result.metafile, projectDir);
-    const depsJson = new TextEncoder().encode(JSON.stringify(deps, null, 2) + '\n');
-    const source = sourceZip ?? (await zipSources(projectDir));
-    const prefix = `${FUNCTIONS_DIR}/${name}`;
-    return {
-        name,
-        bundleBytes: bundle.length,
-        deps,
-        files: [
-            { path: `${prefix}/bundle.zip`, size: bundle.length, data: bundle },
-            { path: `${prefix}/source.zip`, size: source.length, data: source },
-            { path: `${prefix}/deps.json`, size: depsJson.length, data: depsJson },
-        ],
-    };
-}
-
-/** Zips every file under functions/ (no node_modules or hidden files), with paths like functions/lib/feed.ts. */
-export async function zipSources(projectDir) {
-    const root = join(projectDir, FUNCTIONS_DIR);
-    const files = {};
-    async function walk(dir) {
-        for (const entry of await readdir(dir, { withFileTypes: true })) {
-            if (entry.name.startsWith('.') || entry.name === 'node_modules') continue;
-            const full = join(dir, entry.name);
-            if (entry.isDirectory()) await walk(full);
-            else if (entry.isFile()) files[relative(projectDir, full).split(sep).join('/')] = new Uint8Array(await readFile(full));
-        }
-    }
-    if (existsSync(root)) await walk(root);
-    const zipped = zip(files);
-    if (zipped.length > MAX_SOURCE_BYTES) {
-        throw new Error(`${FUNCTIONS_DIR}/ is ${formatMb(zipped.length)} zipped; the limit is ${formatMb(MAX_SOURCE_BYTES)}. Keep data files and builds out of it.`);
-    }
-    return zipped;
-}
-
-/** A zip with sorted entries and fixed timestamps: the same files always give the same bytes. */
-export function zip(files) {
-    const sorted = {};
-    for (const path of Object.keys(files).sort()) sorted[path] = [files[path], { mtime: ZIP_TIME }];
-    return zipSync(sorted, { level: 9, mtime: ZIP_TIME });
-}
-
-/** The packages in the bundle, from the esbuild metafile: every input outside the app's own code, by its package.json. */
-export function dependencies(metafile, projectDir) {
-    const found = new Map();
-    const appModules = join(projectDir, 'node_modules');
-    for (const input of Object.keys(metafile.inputs)) {
-        // <stdin> is the generated wrapper; "ns:…" inputs come from other esbuild namespaces, not files.
-        if (input.startsWith('<') || /^[a-z-]{2,}:/i.test(input)) continue;
-        const full = resolve(projectDir, input);
-        const inApp = !relative(projectDir, full).startsWith('..') && !full.startsWith(appModules + sep);
-        if (inApp) continue;
-        const pkg = nearestPackage(dirname(full));
-        if (pkg?.name && !found.has(pkg.name)) found.set(pkg.name, pkg.version ?? 'unknown');
-    }
-    return [...found].sort(([a], [b]) => a.localeCompare(b)).map(([name, version]) => ({ name, version }));
-}
-
-function nearestPackage(dir) {
-    for (let current = dir; ; current = dirname(current)) {
-        const file = join(current, 'package.json');
-        if (existsSync(file)) {
-            try {
-                const pkg = JSON.parse(readFileSync(file, 'utf8'));
-                // Nested package.json files that only set "type" (e.g. dist/esm/package.json) aren't the package.
-                if (pkg.name) return pkg;
-            } catch {
-                // Unreadable: keep looking up.
-            }
-        }
-        if (dirname(current) === current) return null;
-    }
-}
-
-export function describeFunctions(count) {
-    return `${count} function${count === 1 ? '' : 's'}`;
-}
-
-/** "20 s, 512 MB, secrets FEED_API_KEY" ("job, 300 s, …" for a background job) */
-export function describeConfig(config) {
-    return `${config.job ? 'job, ' : ''}${config.timeoutSeconds} s, ${config.memoryMb} MB${config.secrets.length ? `, secrets ${config.secrets.join(' ')}` : ''}${config.clientSecrets?.length ? `, client secrets ${config.clientSecrets.join(' ')}` : ''}`;
-}
-
-function formatMb(bytes) {
-    return `${(bytes / 1024 / 1024).toFixed(1)} MB`;
-}
+import { existsSync, readFileSync } from 'node:fs';
+import { readdir, readFile } from 'node:fs/promises';
+import { createRequire } from 'node:module';
+import { dirname, join, relative, resolve, sep } from 'node:path';
+import { zipSync } from 'fflate';
+
+// App functions (`functions:invoke`): functions/<name>.ts (or .js/.mts/.mjs) next to hawk-app.json, declared under
+// "functions" in the manifest, bundled with esbuild into one index.mjs per function and deployed with each version
+// as an AWS Lambda version. Same limits as the platform, which validates again on deploy.
+export const FUNCTIONS_DIR = 'functions';
+export const FUNCTIONS_SCOPE = 'functions:invoke';
+export const BRIDGE_PACKAGE = '@bridgeline-digital/hawk-app-bridge';
+export const MAX_FUNCTIONS = 10;
+export const MAX_NAME_LENGTH = 40;
+export const MAX_SECRETS = 20;
+export const TIMEOUT = { min: 1, max: 25, default: 10 };
+/** Background jobs ("job": true): started with app.functions.start, not called, so they may run longer. */
+export const JOB_TIMEOUT = { min: 1, max: 900, default: 300 };
+export const MEMORY = { min: 128, max: 1024, default: 256 };
+export const MAX_BUNDLE_BYTES = 10 * 1024 * 1024;
+export const MAX_SOURCE_BYTES = 5 * 1024 * 1024;
+export const ENTRY_EXTENSIONS = ['.ts', '.mts', '.js', '.mjs'];
+
+export const FUNCTION_NAME = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+export const SECRET_NAME = /^[A-Z][A-Z0-9_]{0,63}$/;
+const CONFIG_KEYS = ['job', 'timeoutSeconds', 'memoryMb', 'secrets', 'clientSecrets'];
+const MAX_CLIENT_SECRETS = 10;
+/** Fixed zip entry time, so a zip's bytes (and the Lambda codeSha256) only change when the code does. */
+const ZIP_TIME = new Date(1980, 0, 1, 0, 0, 0);
+
+/**
+ * Checks the manifest's "functions" block (names, settings, the functions:invoke scope).
+ * @returns {string[]} errors
+ */
+export function validateFunctionsManifest(manifest) {
+    const errors = [];
+    const functions = manifest?.functions;
+    if (functions === undefined) return errors;
+    if (!functions || typeof functions !== 'object' || Array.isArray(functions)) {
+        errors.push('functions must be an object: { "<name>": { "timeoutSeconds": 10, "memoryMb": 256, "secrets": [] } }.');
+        return errors;
+    }
+    const names = Object.keys(functions);
+    if (names.length > MAX_FUNCTIONS) errors.push(`functions: at most ${MAX_FUNCTIONS} functions per app (found ${names.length}).`);
+    for (const name of names) {
+        const where = `functions.${name}`;
+        if (!FUNCTION_NAME.test(name) || name.length > MAX_NAME_LENGTH) {
+            errors.push(`${where}: function names must be 1-${MAX_NAME_LENGTH} lowercase letters, digits and single dashes (e.g. "sync-feed").`);
+        }
+        const config = functions[name];
+        if (!config || typeof config !== 'object' || Array.isArray(config)) {
+            errors.push(`${where} must be an object, e.g. { "timeoutSeconds": 10, "memoryMb": 256, "secrets": [] } (or {} for the defaults).`);
+            continue;
+        }
+        const unknown = Object.keys(config).filter((key) => !CONFIG_KEYS.includes(key));
+        if (unknown.length) errors.push(`${where}: unknown setting${unknown.length === 1 ? '' : 's'} ${unknown.map((k) => `"${k}"`).join(', ')} (allowed: ${CONFIG_KEYS.join(', ')}).`);
+        if (config.job !== undefined && typeof config.job !== 'boolean') errors.push(`${where}.job must be true or false.`);
+        const timeout = config.job === true ? JOB_TIMEOUT : TIMEOUT;
+        if (config.timeoutSeconds !== undefined && !isIntIn(config.timeoutSeconds, timeout)) {
+            const hint = config.job === true ? '' : `; up to ${JOB_TIMEOUT.max} with "job": true`;
+            errors.push(`${where}.timeoutSeconds must be a whole number from ${timeout.min} to ${timeout.max} (default ${timeout.default}${hint}).`);
+        }
+        if (config.memoryMb !== undefined && !isIntIn(config.memoryMb, MEMORY)) {
+            errors.push(`${where}.memoryMb must be a whole number from ${MEMORY.min} to ${MEMORY.max} (default ${MEMORY.default}).`);
+        }
+        if (config.secrets !== undefined) {
+            const secrets = config.secrets;
+            if (!Array.isArray(secrets)) {
+                errors.push(`${where}.secrets must be a list of names, e.g. ["FEED_API_KEY"].`);
+            } else {
+                const bad = secrets.filter((s) => typeof s !== 'string' || !SECRET_NAME.test(s));
+                if (bad.length) errors.push(`${where}.secrets: ${bad.map((s) => JSON.stringify(s)).join(', ')} must be UPPER_SNAKE_CASE names (a letter, then letters, digits or _; up to 64).`);
+                const duplicates = [...new Set(secrets.filter((s, i) => secrets.indexOf(s) !== i))];
+                if (duplicates.length) errors.push(`${where}.secrets lists ${duplicates.join(', ')} more than once.`);
+                if (secrets.length > MAX_SECRETS) errors.push(`${where}.secrets: at most ${MAX_SECRETS} secrets per function.`);
+            }
+        }
+        if (config.clientSecrets !== undefined) {
+            const names = config.clientSecrets;
+            if (!Array.isArray(names)) {
+                errors.push(`${where}.clientSecrets must be a list of names, e.g. ["MAILCHIMP_API_KEY"].`);
+            } else {
+                const bad = names.filter((s) => typeof s !== 'string' || !SECRET_NAME.test(s));
+                if (bad.length) errors.push(`${where}.clientSecrets: ${bad.map((s) => JSON.stringify(s)).join(', ')} must be UPPER_SNAKE_CASE names (a letter, then letters, digits or _; up to 64).`);
+                const duplicates = [...new Set(names.filter((s, i) => names.indexOf(s) !== i))];
+                if (duplicates.length) errors.push(`${where}.clientSecrets lists ${duplicates.join(', ')} more than once.`);
+                if (names.length > MAX_CLIENT_SECRETS) errors.push(`${where}.clientSecrets: at most ${MAX_CLIENT_SECRETS} client secrets per function.`);
+            }
+        }
+    }
+    if (names.length && !(manifest.scopes ?? []).includes(FUNCTIONS_SCOPE)) {
+        errors.push(`functions need the "${FUNCTIONS_SCOPE}" scope: add it to "scopes" in hawk-app.json.`);
+    }
+    return errors;
+}
+
+const isIntIn = (value, { min, max }) => Number.isInteger(value) && value >= min && value <= max;
+
+/** A function's settings with the defaults filled in, as sent to the platform. */
+export function functionConfig(config = {}) {
+    const job = config.job === true;
+    return {
+        job,
+        timeoutSeconds: config.timeoutSeconds ?? (job ? JOB_TIMEOUT : TIMEOUT).default,
+        memoryMb: config.memoryMb ?? MEMORY.default,
+        secrets: config.secrets ?? [],
+        clientSecrets: config.clientSecrets ?? [],
+    };
+}
+
+/**
+ * Matches the manifest's functions with the entry files in `<projectDir>/functions`. Null when the app has neither.
+ * Every declared function needs functions/<name>.(ts|mts|js|mjs), and every entry file there needs a manifest entry
+ * (shared code goes in subfolders such as functions/lib/).
+ * @returns {Promise<{ functions: { name: string, entry: string, config: object }[], errors: string[] } | null>}
+ */
+export async function loadFunctions(projectDir, manifest) {
+    const declared = manifest?.functions && typeof manifest.functions === 'object' && !Array.isArray(manifest.functions) ? manifest.functions : {};
+    const dir = join(projectDir, FUNCTIONS_DIR);
+    const hasDir = existsSync(dir);
+    if (!hasDir && !Object.keys(declared).length) return null;
+
+    const errors = [];
+    const entries = new Map();
+    if (hasDir) {
+        for (const entry of await readdir(dir, { withFileTypes: true })) {
+            if (!entry.isFile() || entry.name.startsWith('.') || entry.name.endsWith('.d.ts')) continue;
+            const ext = ENTRY_EXTENSIONS.find((e) => entry.name.endsWith(e));
+            if (!ext) continue;
+            const name = entry.name.slice(0, -ext.length);
+            if (entries.has(name)) {
+                errors.push(`${FUNCTIONS_DIR}/: ${name} has more than one entry file (${entries.get(name).file} and ${entry.name}); keep one.`);
+                continue;
+            }
+            entries.set(name, { file: entry.name, full: join(dir, entry.name) });
+        }
+    }
+
+    const functions = [];
+    for (const name of Object.keys(declared).sort()) {
+        const entry = entries.get(name);
+        if (!entry) {
+            errors.push(`functions.${name} has no entry file: add ${FUNCTIONS_DIR}/${name}.ts (or .js/.mts/.mjs) exporting \`handler\`.`);
+            continue;
+        }
+        functions.push({ name, entry: entry.full, config: functionConfig(declared[name]) });
+    }
+    for (const [name, entry] of entries) {
+        if (!(name in declared)) {
+            errors.push(`${FUNCTIONS_DIR}/${entry.file} is not declared in hawk-app.json: add "${name}": {} under "functions", or move shared code into a subfolder (e.g. ${FUNCTIONS_DIR}/lib/).`);
+        }
+    }
+    if (hasDir && !entries.size && !Object.keys(declared).length) {
+        errors.push(`${FUNCTIONS_DIR}/ has no functions: add ${FUNCTIONS_DIR}/<name>.ts and declare it under "functions" in hawk-app.json, or remove the folder.`);
+    }
+    return { functions, errors };
+}
+
+/**
+ * Checks that the app has a bridge with the `/server` entry (the wrapper imports `toLambdaHandler` from it).
+ * @returns {string | null} an error message, or null when it's fine
+ */
+export function checkBridge(projectDir) {
+    let packageFile;
+    try {
+        packageFile = createRequire(join(projectDir, 'package.json')).resolve(`${BRIDGE_PACKAGE}/package.json`);
+    } catch {
+        return `Functions need ${BRIDGE_PACKAGE} in the app: run \`npm install ${BRIDGE_PACKAGE}\`.`;
+    }
+    const pkg = JSON.parse(readFileSync(packageFile, 'utf8'));
+    if (!pkg.exports?.['./server']) {
+        return `${BRIDGE_PACKAGE} ${pkg.version} has no "/server" entry: update it (\`npm install ${BRIDGE_PACKAGE}@latest\`).`;
+    }
+    return null;
+}
+
+/** The generated entry: the user's module wrapped as the Lambda handler. */
+export function wrapperSource(entry) {
+    const userModule = entry.split(sep).join('/');
+    return [
+        `import { toLambdaHandler } from '${BRIDGE_PACKAGE}/server';`,
+        `import { handler as userHandler } from ${JSON.stringify(userModule)};`,
+        'export const handler = toLambdaHandler(userHandler);',
+        '',
+    ].join('\n');
+}
+
+/**
+ * Bundles one function (esbuild: node22, ESM, every dependency included) and packs what the platform needs:
+ * `bundle.zip` (index.mjs exporting `handler`), `source.zip` (every file under functions/, for review) and
+ * `deps.json` ([{ name, version }] of the packages in the bundle).
+ * @returns {Promise<{ name: string, files: { path: string, size: number, data: Uint8Array }[], bundleBytes: number, deps: { name: string, version: string }[] }>}
+ */
+export async function buildFunction({ projectDir, name, entry, sourceZip }) {
+    const problem = checkBridge(projectDir);
+    if (problem) throw new Error(problem);
+    const esbuild = await import('esbuild');
+    let result;
+    try {
+        result = await esbuild.build({
+            stdin: { contents: wrapperSource(entry), resolveDir: projectDir, sourcefile: `hawk-function-${name}.mjs`, loader: 'js' },
+            absWorkingDir: projectDir,
+            bundle: true,
+            platform: 'node',
+            target: 'node22',
+            format: 'esm',
+            outfile: 'index.mjs',
+            write: false,
+            metafile: true,
+            logLevel: 'silent',
+            legalComments: 'none',
+            // CommonJS dependencies that call require() need it in an ES module.
+            banner: { js: "import { createRequire as __hawkCreateRequire } from 'node:module';\nconst require = __hawkCreateRequire(import.meta.url);" },
+        });
+    } catch (error) {
+        const messages = (error.errors ?? []).map((e) => `  ${e.location ? `${e.location.file}:${e.location.line}: ` : ''}${e.text}`);
+        const missingHandler = (error.errors ?? []).some((e) => /No matching export .* for import "handler"/.test(e.text));
+        throw new Error(
+            `Could not bundle function "${name}"${missingHandler ? ` (${FUNCTIONS_DIR}/${name} must export \`handler\`)` : ''}:\n${messages.join('\n') || `  ${error.message}`}`,
+        );
+    }
+    const code = result.outputFiles.find((f) => f.path.endsWith('index.mjs')).contents;
+    const bundle = zip({ 'index.mjs': code });
+    if (bundle.length > MAX_BUNDLE_BYTES) {
+        throw new Error(`Function "${name}" is ${formatMb(bundle.length)} zipped; the limit is ${formatMb(MAX_BUNDLE_BYTES)}. Drop large dependencies.`);
+    }
+    const deps = dependencies(result.metafile, projectDir);
+    const depsJson = new TextEncoder().encode(JSON.stringify(deps, null, 2) + '\n');
+    const source = sourceZip ?? (await zipSources(projectDir));
+    const prefix = `${FUNCTIONS_DIR}/${name}`;
+    return {
+        name,
+        bundleBytes: bundle.length,
+        deps,
+        files: [
+            { path: `${prefix}/bundle.zip`, size: bundle.length, data: bundle },
+            { path: `${prefix}/source.zip`, size: source.length, data: source },
+            { path: `${prefix}/deps.json`, size: depsJson.length, data: depsJson },
+        ],
+    };
+}
+
+/** Zips every file under functions/ (no node_modules or hidden files), with paths like functions/lib/feed.ts. */
+export async function zipSources(projectDir) {
+    const root = join(projectDir, FUNCTIONS_DIR);
+    const files = {};
+    async function walk(dir) {
+        for (const entry of await readdir(dir, { withFileTypes: true })) {
+            if (entry.name.startsWith('.') || entry.name === 'node_modules') continue;
+            const full = join(dir, entry.name);
+            if (entry.isDirectory()) await walk(full);
+            else if (entry.isFile()) files[relative(projectDir, full).split(sep).join('/')] = new Uint8Array(await readFile(full));
+        }
+    }
+    if (existsSync(root)) await walk(root);
+    const zipped = zip(files);
+    if (zipped.length > MAX_SOURCE_BYTES) {
+        throw new Error(`${FUNCTIONS_DIR}/ is ${formatMb(zipped.length)} zipped; the limit is ${formatMb(MAX_SOURCE_BYTES)}. Keep data files and builds out of it.`);
+    }
+    return zipped;
+}
+
+/** A zip with sorted entries and fixed timestamps: the same files always give the same bytes. */
+export function zip(files) {
+    const sorted = {};
+    for (const path of Object.keys(files).sort()) sorted[path] = [files[path], { mtime: ZIP_TIME }];
+    return zipSync(sorted, { level: 9, mtime: ZIP_TIME });
+}
+
+/** The packages in the bundle, from the esbuild metafile: every input outside the app's own code, by its package.json. */
+export function dependencies(metafile, projectDir) {
+    const found = new Map();
+    const appModules = join(projectDir, 'node_modules');
+    for (const input of Object.keys(metafile.inputs)) {
+        // <stdin> is the generated wrapper; "ns:…" inputs come from other esbuild namespaces, not files.
+        if (input.startsWith('<') || /^[a-z-]{2,}:/i.test(input)) continue;
+        const full = resolve(projectDir, input);
+        const inApp = !relative(projectDir, full).startsWith('..') && !full.startsWith(appModules + sep);
+        if (inApp) continue;
+        const pkg = nearestPackage(dirname(full));
+        if (pkg?.name && !found.has(pkg.name)) found.set(pkg.name, pkg.version ?? 'unknown');
+    }
+    return [...found].sort(([a], [b]) => a.localeCompare(b)).map(([name, version]) => ({ name, version }));
+}
+
+function nearestPackage(dir) {
+    for (let current = dir; ; current = dirname(current)) {
+        const file = join(current, 'package.json');
+        if (existsSync(file)) {
+            try {
+                const pkg = JSON.parse(readFileSync(file, 'utf8'));
+                // Nested package.json files that only set "type" (e.g. dist/esm/package.json) aren't the package.
+                if (pkg.name) return pkg;
+            } catch {
+                // Unreadable: keep looking up.
+            }
+        }
+        if (dirname(current) === current) return null;
+    }
+}
+
+export function describeFunctions(count) {
+    return `${count} function${count === 1 ? '' : 's'}`;
+}
+
+/** "20 s, 512 MB, secrets FEED_API_KEY" ("job, 300 s, …" for a background job) */
+export function describeConfig(config) {
+    return `${config.job ? 'job, ' : ''}${config.timeoutSeconds} s, ${config.memoryMb} MB${config.secrets.length ? `, secrets ${config.secrets.join(' ')}` : ''}${config.clientSecrets?.length ? `, client secrets ${config.clientSecrets.join(' ')}` : ''}`;
+}
+
+function formatMb(bytes) {
+    return `${(bytes / 1024 / 1024).toFixed(1)} MB`;
+}