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

package/src/deploy.mjs

@@ -1,349 +1,349 @@
-import { spawn, spawnSync } from 'node:child_process';
-import { existsSync } from 'node:fs';
-import { readdir, readFile, stat } from 'node:fs/promises';
-import { dirname, join, relative, sep } from 'node:path';
-import { buildFunction, describeConfig, describeFunctions, zipSources } from './functions.mjs';
-import { checkAccessibility, describeAccessibility } from './accessibility.mjs';
-import { checkBuildUrls, describeBuildUrls } from './project-checks.mjs';
-import { askYesNo } from './slug-guard.mjs';
-
-const CONCURRENCY = 8;
-const RETRIES = 3;
-const AUDIT_TIMEOUT_MS = 60_000;
-
-/** Every file under `dir`, as forward-slash paths relative to it. Hidden files and folders are skipped. */
-export async function listFiles(dir) {
-    const files = [];
-    async function walk(current) {
-        for (const entry of await readdir(current, { withFileTypes: true })) {
-            if (entry.name.startsWith('.')) continue;
-            const full = join(current, entry.name);
-            if (entry.isDirectory()) await walk(full);
-            else if (entry.isFile()) files.push({ path: relative(dir, full).split(sep).join('/'), size: (await stat(full)).size, full });
-        }
-    }
-    await walk(dir);
-    return files.sort((a, b) => a.path.localeCompare(b.path));
-}
-
-/**
- * Deploys a new version of an app. The platform reserves the next version number (v<n>), the app is built for
- * `/<slug>/v<n>` (HAWK_APP_BASE_PATH), the platform hands out one upload URL per file (scoped to that version's
- * folder on the CDN), the files go straight to storage, then the platform verifies them and decides who sees the
- * version: an app not released yet shows it to Bridgeline staff at once; a released app keeps clients on their version until
- * it's approved in HawkSearch (unless the app is set to auto-approve).
- * `serverFiles` (the app's checked queries/ files, from the project root) go to the platform's private server bucket
- * with their own upload URLs, never to the CDN.
- * `functions` (checked `{ name, entry, config }` from loadFunctions) are bundled with esbuild, uploaded to the server
- * bucket (bundle.zip, source.zip, deps.json), deployed one by one as Lambda versions, and listed on complete.
- * `audit` runs `npm audit` of the production dependencies before a version is reserved and sends the result with
- * complete, for reviewers. High or critical findings go to `confirmAudit` first (the CLI asks: confirmVulnerabilities).
- */
-/**
- * @param beforeReserve Runs after the local checks, just before a version number is taken (the slug check: slug-guard.mjs).
- * @param confirmAudit Called with the audit report when it has high or critical vulnerabilities; throws to stop the deploy.
- */
-export async function deploy({ client, slug, dir, alias, manifest, registerSettings, iconFile = null, storeFiles = [], build = true, serverFiles = [], functions = [], projectDir = process.cwd(), audit = true, runBuild = npmRunBuild, runAudit = npmAudit, runAccessibility = checkAccessibility, beforeReserve, confirmAudit, fetchImpl = fetch, log = console.log }) {
-    // Without a build step the folder must already be there: check before reserving a version.
-    if (!build) await checkFolder(dir, false);
-
-    // Bundle the functions first: a function that doesn't build shouldn't cost a version number.
-    const built = [];
-    if (functions.length) {
-        log(`Bundling ${describeFunctions(functions.length)}…`);
-        const sourceZip = await zipSources(projectDir);
-        for (const fn of functions) {
-            const result = await buildFunction({ projectDir, name: fn.name, entry: fn.entry, sourceZip });
-            built.push({ ...result, config: fn.config });
-            log(`  ƒ ${fn.name}  ${formatBytes(result.bundleBytes)} zipped, ${result.deps.length} package${result.deps.length === 1 ? '' : 's'}`);
-        }
-    }
-    const functionFiles = built.flatMap((fn) => fn.files);
-
-    // Dependencies before a version number: a developer can stop and fix them first.
-    const { serious, ...report } = audit ? await auditDependencies({ cwd: projectDir, runAudit }) : { status: 'not_checked', reason: 'skipped (--no-audit)' };
-    log(`  dependencies ${describeAudit(report)}`);
-    if (confirmAudit && report.status === 'checked' && report.critical + report.high > 0) await confirmAudit({ ...report, serious });
-
-    if (beforeReserve) await beforeReserve();
-    // The main line: hawk-app.json goes first (scopes, origins, functions…), so the version carries the settings it's
-    // deployed with. For an alias, the branch's hawk-app.json goes with the version only.
-    if (!alias && registerSettings) await registerSettings();
-    const reserved = await client.reserveVersion(slug);
-    const version = reserved.version;
-
-    if (build) {
-        log(`Building v${version} of ${slug} (HAWK_APP_BASE_PATH=${reserved.basePath})…`);
-        await runBuild({ basePath: reserved.basePath });
-        await checkFolder(dir, true);
-    }
-
-    const files = await listFiles(dir);
-    if (!files.length) throw new Error(`"${dir}" is empty.`);
-    // The icon and the store screenshots go into the version too (_hawk/icon.svg, _hawk/store/1.png…): a folder of the
-    // build can't take their place.
-    if (files.some((f) => f.path.startsWith('_hawk/'))) throw new Error(`"${dir}" has a _hawk/ folder: the platform uses that path for the app's icon and store screenshots. Rename it.`);
-    if (iconFile) files.push(iconFile);
-    files.push(...storeFiles);
-    // The usual mistake of an app set up without a template: never stops the deploy (the version is already reserved).
-    const outside = reserved.basePath ? await checkBuildUrls(dir, reserved.basePath) : [];
-    if (outside.length) log(`! ${describeBuildUrls(outside, reserved.basePath)}`);
-    // axe over the built pages, for the approvers' accessibility check. Never stops the deploy.
-    const accessibility = await runAccessibility(dir);
-    log(`  accessibility ${describeAccessibility(accessibility)}`);
-    const totalBytes = files.reduce((sum, f) => sum + f.size, 0);
-    const queryCount = new Set(serverFiles.map((f) => f.path.replace(/.(sql|json)$/, ''))).size;
-    const queriesNote = `${queryCount ? `, ${describeQueries(queryCount)}` : ''}${built.length ? `, ${describeFunctions(built.length)}` : ''}`;
-    log(`Uploading v${version} of ${slug}: ${files.length} files, ${formatBytes(totalBytes)} from ${dir}${queriesNote}`);
-
-    const started = await client.startUploads(
-        slug,
-        version,
-        files.map(({ path, size }) => ({ path, size })),
-        serverFiles.map(({ path, size }) => ({ path, size })),
-        functionFiles.map(({ path, size }) => ({ path, size })),
-    );
-    const byPath = new Map(files.map((f) => [f.path, f]));
-    const serverByPath = new Map(serverFiles.map((f) => [f.path, f]));
-    const functionByPath = new Map(functionFiles.map((f) => [f.path, f]));
-    if (serverFiles.length && (started.serverUploads?.length ?? 0) !== serverFiles.length) {
-        throw new Error('The platform did not accept the queries/ files. It may not support app queries yet; update it or remove queries/.');
-    }
-    if (functionFiles.length && (started.functionUploads?.length ?? 0) !== functionFiles.length) {
-        throw new Error('The platform did not accept the functions. It may not support app functions yet; update it or remove "functions".');
-    }
-
-    let done = 0;
-    const queue = [
-        ...started.uploads.map((upload) => ({ upload, file: byPath.get(upload.path) })),
-        ...(started.serverUploads ?? []).map((upload) => ({ upload, file: serverByPath.get(upload.path) })),
-        ...(started.functionUploads ?? []).map((upload) => ({ upload, file: functionByPath.get(upload.path) })),
-    ];
-    const total = queue.length;
-    async function worker() {
-        for (let item = queue.shift(); item; item = queue.shift()) {
-            if (!item.file) throw new Error(`The platform returned an upload for an unknown file: ${item.upload.path}`);
-            await uploadWithRetry(item.upload, item.file.data ?? (await readFile(item.file.full)), fetchImpl);
-            done += 1;
-            if (done % 25 === 0 || done === total) log(`  uploaded ${done}/${total}`);
-        }
-    }
-    await Promise.all(Array.from({ length: Math.min(CONCURRENCY, queue.length) }, worker));
-
-    // Each function becomes a Lambda version; the platform waits until it's ready.
-    for (const fn of built) {
-        const deployed = await client.deployFunction(slug, version, fn.name, fn.config);
-        log(`  ✔ function ${fn.name}  (${describeConfig(fn.config)})${deployed?.lambdaVersion ? `  Lambda version ${deployed.lambdaVersion}` : ''}`);
-    }
-
-    const completed = await client.completeVersion(
-        slug,
-        version,
-        files.map((f) => f.path),
-        serverFiles.map((f) => f.path),
-        built.map((fn) => fn.name),
-        report,
-        accessibility,
-        alias ? { alias, manifest } : {},
-    );
-    const n = completed.version ?? version;
-    log(`✔ Deployed v${n} of ${slug} (${completed.files ?? files.length} files${queriesNote}).${describeState(completed)}`);
-    if (completed.entryUrl) log(`  ${completed.entryUrl}`);
-    if (built.length && completed.state === 'pending') log('  (Versions with functions always need review, even on auto-approve apps.)');
-    if (completed.submissionCleared) log(`  ! ${submissionClearedMessage('version')}`);
-    if (completed.removedVersions?.length) log(`  Removed old versions ${completed.removedVersions.map((v) => `v${v}`).join(', ')}.`);
-    if (!alias) await warnAboutScopes({ client, slug, needs: neededScopes(serverFiles, built), log });
-    return completed;
-}
-
-/** Said when a deploy or register replaced what was waiting for approval: the platform cleared the request. */
-export function submissionClearedMessage(what) {
-    return `Your new ${what} cleared the waiting approval request: submit it again in HawkSearch (npx hawk-app open).`;
-}
-
-/** The scopes a version's own files need to run: queries need data:read, functions need functions:invoke. */
-function neededScopes(serverFiles, built) {
-    const needs = [];
-    if (serverFiles.some((f) => f.path.startsWith('queries/'))) needs.push('data:read');
-    if (built.length) needs.push('functions:invoke');
-    return needs;
-}
-
-/**
- * A version that uses queries or functions while hawk-app.json's scopes (granted or waiting for approval) lack the scope
- * gets 403 scope_missing at run time. Say so now. Best effort: a failed status check never fails a deploy that succeeded.
- */
-async function warnAboutScopes({ client, slug, needs, log }) {
-    if (!needs.length || !client.status) return;
-    let app;
-    try {
-        app = await client.status(slug);
-    } catch (error) {
-        if (error?.status === 404) log(`  ! ${slug} isn't on the platform: add ${needs.join(', ')} to "scopes" in hawk-app.json and deploy again.`);
-        return;
-    }
-    const registered = new Set([...(app?.scopes ?? []), ...(app?.pendingScopes ?? [])]);
-    const missing = needs.filter((scope) => !registered.has(scope));
-    if (missing.length) {
-        log(`  ! This version uses ${missing.join(' and ')}, which hawk-app.json's scopes on the platform don't include. Add ${missing.length === 1 ? 'it' : 'them'} to "scopes" in hawk-app.json and deploy again, or calls fail with 403 scope_missing.`);
-    }
-}
-
-function describeQueries(count) {
-    return `${count} quer${count === 1 ? 'y' : 'ies'}`;
-}
-
-function describeState({ state, liveVersion, alias }) {
-    switch (state) {
-        case 'alias':
-            return ` ${alias} → it: only Bridgeline staff in its clients see it until it's approved. The main line (default, and the version under review) is unchanged.`;
-        case 'draft':
-            return ' Not released yet: only Bridgeline staff see it. Review it and submit it for approval in HawkSearch: npx hawk-app open.';
-        case 'pending':
-            return ` A draft: clients stay on ${liveVersion ? `v${liveVersion}` : 'the default version'} until it's approved. Submit it for approval in HawkSearch: npx hawk-app open.`;
-        case 'live':
-            return ' Auto-approved: released to clients.';
-        default:
-            return '';
-    }
-}
-
-async function checkFolder(dir, built) {
-    let info;
-    try {
-        info = await stat(dir);
-    } catch {
-        throw new Error(built ? `The build did not create "${dir}". Check the folder name (dist, out, build, ...).` : `Build folder "${dir}" not found.`);
-    }
-    if (!info.isDirectory()) throw new Error(`"${dir}" is not a folder.`);
-}
-
-/** Runs the project's `npm run build` with the version's base path, so asset URLs point at /<slug>/v<n>/. */
-export async function npmRunBuild({ basePath, cwd = process.cwd() }) {
-    const result = spawnSync('npm', ['run', 'build'], {
-        cwd,
-        stdio: 'inherit',
-        shell: process.platform === 'win32',
-        env: { ...process.env, HAWK_APP_BASE_PATH: basePath },
-    });
-    if (result.error) throw new Error(`Could not run \`npm run build\`: ${result.error.message}`);
-    if (result.status !== 0) {
-        throw new Error(`\`npm run build\` failed (exit code ${result.status}). Fix the build, or pass --no-build to upload the folder as it is.`);
-    }
-}
-
-/**
- * Runs `npm audit --json --omit=dev` in the app folder: { status: 'checked', critical, high, moderate, low,
- * dependencies, serious } or { status: 'not_checked', reason }. `serious` (the packages with high or critical findings)
- * is for the developer only: deploy leaves it out of what it sends. Never throws: a deploy doesn't fail because of it. Reasons are
- * fixed texts (no paths, no npm output) so nothing private reaches the platform.
- */
-export async function auditDependencies({ cwd, runAudit = npmAudit }) {
-    const notChecked = (reason) => ({ status: 'not_checked', reason });
-    if (!hasLockfile(cwd)) return notChecked('no package-lock.json');
-    let stdout;
-    try {
-        // npm audit exits non-zero when it finds vulnerabilities: the JSON decides, not the exit code.
-        ({ stdout } = await runAudit({ cwd }));
-    } catch (error) {
-        return notChecked(error?.code === 'ETIMEDOUT' ? `npm audit timed out after ${AUDIT_TIMEOUT_MS / 1000} s` : 'could not run npm audit');
-    }
-    let result;
-    try {
-        result = JSON.parse(stdout);
-    } catch {
-        return notChecked('npm audit output was not JSON');
-    }
-    if (result?.error) {
-        const code = String(result.error.code ?? '');
-        return notChecked(/^[A-Z0-9_]{1,40}$/.test(code) ? `npm audit failed (${code})` : 'npm audit failed');
-    }
-    const counts = result?.metadata?.vulnerabilities;
-    const levels = ['critical', 'high', 'moderate', 'low'];
-    if (!counts || !levels.every((level) => Number.isInteger(counts[level]) && counts[level] >= 0)) {
-        return notChecked('npm audit output had no vulnerability counts');
-    }
-    const deps = result.metadata.dependencies;
-    const dependencies = [deps?.prod, deps?.total].find((n) => Number.isInteger(n) && n >= 0) ?? 0;
-    const serious = Object.entries(result.vulnerabilities ?? {})
-        .filter(([, v]) => v?.severity === 'critical' || v?.severity === 'high')
-        .map(([name]) => name)
-        .sort();
-    return { status: 'checked', ...Object.fromEntries(levels.map((level) => [level, counts[level]])), dependencies, serious };
-}
-
-/** A package-lock.json in the folder or above it: an npm workspace keeps one lockfile at the repository root, and npm audit finds it from the workspace folder. */
-function hasLockfile(dir) {
-    for (let current = dir; ; current = dirname(current)) {
-        if (existsSync(join(current, 'package-lock.json'))) return true;
-        if (dirname(current) === current) return false;
-    }
-}
-
-/**
- * deploy's confirmAudit in the CLI: high or critical vulnerabilities fail the review's dependencies check (approvers can
- * only force approve), so ask before deploying. --yes goes on with a warning; so does a pipeline (no terminal to ask).
- */
-export async function confirmVulnerabilities(report, { yes = false, confirm = askYesNo, log = console.log } = {}) {
-    const packages = report.serious?.length ? ` (${report.serious.join(', ')})` : '';
-    const message = `npm audit found ${describeAudit(report).replace(' (npm audit)', '')} in the production dependencies${packages}. Approvers can only force approve this version.`;
-    if (yes) {
-        log(`! ${message}`);
-        return;
-    }
-    const answer = await confirm(`${message} Deploy anyway? (Fix with npm audit fix or by updating the packages; npm run app:audit shows the details.)`);
-    if (answer === null) {
-        log(`! ${message} Going on (no terminal to ask; add --yes to silence this).`);
-        return;
-    }
-    if (!answer) throw new Error('Cancelled. Nothing was deployed. `npm run app:audit` (or npm audit --omit=dev) shows the details.');
-}
-
-function describeAudit(report) {
-    if (report.status !== 'checked') return `not checked: ${report.reason}`;
-    const found = ['critical', 'high', 'moderate', 'low'].filter((level) => report[level]).map((level) => `${report[level]} ${level}`);
-    return found.length ? `${found.join(', ')} (npm audit)` : 'no known vulnerabilities';
-}
-
-/** Runs `npm audit --json --omit=dev` in `cwd`: { code, stdout }. Rejects when npm can't start or takes over `timeoutMs`. */
-export function npmAudit({ cwd, timeoutMs = AUDIT_TIMEOUT_MS }) {
-    return new Promise((resolve, reject) => {
-        const child = spawn('npm', ['audit', '--json', '--omit=dev'], { cwd, stdio: ['ignore', 'pipe', 'ignore'], shell: process.platform === 'win32' });
-        const chunks = [];
-        const timer = setTimeout(() => {
-            // With a shell on Windows the child is cmd.exe: end the whole tree, not only the shell.
-            if (process.platform === 'win32') spawnSync('taskkill', ['/pid', String(child.pid), '/T', '/F'], { stdio: 'ignore' });
-            else child.kill();
-            reject(Object.assign(new Error('npm audit timed out'), { code: 'ETIMEDOUT' }));
-        }, timeoutMs);
-        child.stdout.on('data', (chunk) => chunks.push(chunk));
-        child.on('error', (error) => {
-            clearTimeout(timer);
-            reject(error);
-        });
-        child.on('close', (code) => {
-            clearTimeout(timer);
-            resolve({ code, stdout: Buffer.concat(chunks).toString('utf8') });
-        });
-    });
-}
-
-async function uploadWithRetry(upload, body, fetchImpl) {
-    for (let attempt = 1; ; attempt++) {
-        try {
-            const response = await fetchImpl(upload.url, { method: 'PUT', headers: upload.headers, body });
-            if (response.ok) return;
-            const text = await response.text().catch(() => '');
-            if (response.status < 500 || attempt >= RETRIES) {
-                throw new Error(`Upload of ${upload.path} failed (${response.status}). ${response.status === 403 ? 'The upload link may have expired; run deploy again.' : text.slice(0, 200)}`);
-            }
-        } catch (error) {
-            if (attempt >= RETRIES || error.message?.startsWith('Upload of')) throw error;
-        }
-        await new Promise((resolve) => setTimeout(resolve, 500 * attempt));
-    }
-}
-
-function formatBytes(bytes) {
-    return bytes > 1024 * 1024 ? `${(bytes / 1024 / 1024).toFixed(1)} MB` : `${Math.ceil(bytes / 1024)} KB`;
-}
+import { spawn, spawnSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { readdir, readFile, stat } from 'node:fs/promises';
+import { dirname, join, relative, sep } from 'node:path';
+import { buildFunction, describeConfig, describeFunctions, zipSources } from './functions.mjs';
+import { checkAccessibility, describeAccessibility } from './accessibility.mjs';
+import { checkBuildUrls, describeBuildUrls } from './project-checks.mjs';
+import { askYesNo } from './slug-guard.mjs';
+
+const CONCURRENCY = 8;
+const RETRIES = 3;
+const AUDIT_TIMEOUT_MS = 60_000;
+
+/** Every file under `dir`, as forward-slash paths relative to it. Hidden files and folders are skipped. */
+export async function listFiles(dir) {
+    const files = [];
+    async function walk(current) {
+        for (const entry of await readdir(current, { withFileTypes: true })) {
+            if (entry.name.startsWith('.')) continue;
+            const full = join(current, entry.name);
+            if (entry.isDirectory()) await walk(full);
+            else if (entry.isFile()) files.push({ path: relative(dir, full).split(sep).join('/'), size: (await stat(full)).size, full });
+        }
+    }
+    await walk(dir);
+    return files.sort((a, b) => a.path.localeCompare(b.path));
+}
+
+/**
+ * Deploys a new version of an app. The platform reserves the next version number (v<n>), the app is built for
+ * `/<slug>/v<n>` (HAWK_APP_BASE_PATH), the platform hands out one upload URL per file (scoped to that version's
+ * folder on the CDN), the files go straight to storage, then the platform verifies them and decides who sees the
+ * version: an app not released yet shows it to Bridgeline staff at once; a released app keeps clients on their version until
+ * it's approved in HawkSearch (unless the app is set to auto-approve).
+ * `serverFiles` (the app's checked queries/ files, from the project root) go to the platform's private server bucket
+ * with their own upload URLs, never to the CDN.
+ * `functions` (checked `{ name, entry, config }` from loadFunctions) are bundled with esbuild, uploaded to the server
+ * bucket (bundle.zip, source.zip, deps.json), deployed one by one as Lambda versions, and listed on complete.
+ * `audit` runs `npm audit` of the production dependencies before a version is reserved and sends the result with
+ * complete, for reviewers. High or critical findings go to `confirmAudit` first (the CLI asks: confirmVulnerabilities).
+ */
+/**
+ * @param beforeReserve Runs after the local checks, just before a version number is taken (the slug check: slug-guard.mjs).
+ * @param confirmAudit Called with the audit report when it has high or critical vulnerabilities; throws to stop the deploy.
+ */
+export async function deploy({ client, slug, dir, alias, manifest, registerSettings, iconFile = null, storeFiles = [], build = true, serverFiles = [], functions = [], projectDir = process.cwd(), audit = true, runBuild = npmRunBuild, runAudit = npmAudit, runAccessibility = checkAccessibility, beforeReserve, confirmAudit, fetchImpl = fetch, log = console.log }) {
+    // Without a build step the folder must already be there: check before reserving a version.
+    if (!build) await checkFolder(dir, false);
+
+    // Bundle the functions first: a function that doesn't build shouldn't cost a version number.
+    const built = [];
+    if (functions.length) {
+        log(`Bundling ${describeFunctions(functions.length)}…`);
+        const sourceZip = await zipSources(projectDir);
+        for (const fn of functions) {
+            const result = await buildFunction({ projectDir, name: fn.name, entry: fn.entry, sourceZip });
+            built.push({ ...result, config: fn.config });
+            log(`  ƒ ${fn.name}  ${formatBytes(result.bundleBytes)} zipped, ${result.deps.length} package${result.deps.length === 1 ? '' : 's'}`);
+        }
+    }
+    const functionFiles = built.flatMap((fn) => fn.files);
+
+    // Dependencies before a version number: a developer can stop and fix them first.
+    const { serious, ...report } = audit ? await auditDependencies({ cwd: projectDir, runAudit }) : { status: 'not_checked', reason: 'skipped (--no-audit)' };
+    log(`  dependencies ${describeAudit(report)}`);
+    if (confirmAudit && report.status === 'checked' && report.critical + report.high > 0) await confirmAudit({ ...report, serious });
+
+    if (beforeReserve) await beforeReserve();
+    // The main line: hawk-app.json goes first (scopes, origins, functions…), so the version carries the settings it's
+    // deployed with. For an alias, the branch's hawk-app.json goes with the version only.
+    if (!alias && registerSettings) await registerSettings();
+    const reserved = await client.reserveVersion(slug);
+    const version = reserved.version;
+
+    if (build) {
+        log(`Building v${version} of ${slug} (HAWK_APP_BASE_PATH=${reserved.basePath})…`);
+        await runBuild({ basePath: reserved.basePath });
+        await checkFolder(dir, true);
+    }
+
+    const files = await listFiles(dir);
+    if (!files.length) throw new Error(`"${dir}" is empty.`);
+    // The icon and the store screenshots go into the version too (_hawk/icon.svg, _hawk/store/1.png…): a folder of the
+    // build can't take their place.
+    if (files.some((f) => f.path.startsWith('_hawk/'))) throw new Error(`"${dir}" has a _hawk/ folder: the platform uses that path for the app's icon and store screenshots. Rename it.`);
+    if (iconFile) files.push(iconFile);
+    files.push(...storeFiles);
+    // The usual mistake of an app set up without a template: never stops the deploy (the version is already reserved).
+    const outside = reserved.basePath ? await checkBuildUrls(dir, reserved.basePath) : [];
+    if (outside.length) log(`! ${describeBuildUrls(outside, reserved.basePath)}`);
+    // axe over the built pages, for the approvers' accessibility check. Never stops the deploy.
+    const accessibility = await runAccessibility(dir);
+    log(`  accessibility ${describeAccessibility(accessibility)}`);
+    const totalBytes = files.reduce((sum, f) => sum + f.size, 0);
+    const queryCount = new Set(serverFiles.map((f) => f.path.replace(/.(sql|json)$/, ''))).size;
+    const queriesNote = `${queryCount ? `, ${describeQueries(queryCount)}` : ''}${built.length ? `, ${describeFunctions(built.length)}` : ''}`;
+    log(`Uploading v${version} of ${slug}: ${files.length} files, ${formatBytes(totalBytes)} from ${dir}${queriesNote}`);
+
+    const started = await client.startUploads(
+        slug,
+        version,
+        files.map(({ path, size }) => ({ path, size })),
+        serverFiles.map(({ path, size }) => ({ path, size })),
+        functionFiles.map(({ path, size }) => ({ path, size })),
+    );
+    const byPath = new Map(files.map((f) => [f.path, f]));
+    const serverByPath = new Map(serverFiles.map((f) => [f.path, f]));
+    const functionByPath = new Map(functionFiles.map((f) => [f.path, f]));
+    if (serverFiles.length && (started.serverUploads?.length ?? 0) !== serverFiles.length) {
+        throw new Error('The platform did not accept the queries/ files. It may not support app queries yet; update it or remove queries/.');
+    }
+    if (functionFiles.length && (started.functionUploads?.length ?? 0) !== functionFiles.length) {
+        throw new Error('The platform did not accept the functions. It may not support app functions yet; update it or remove "functions".');
+    }
+
+    let done = 0;
+    const queue = [
+        ...started.uploads.map((upload) => ({ upload, file: byPath.get(upload.path) })),
+        ...(started.serverUploads ?? []).map((upload) => ({ upload, file: serverByPath.get(upload.path) })),
+        ...(started.functionUploads ?? []).map((upload) => ({ upload, file: functionByPath.get(upload.path) })),
+    ];
+    const total = queue.length;
+    async function worker() {
+        for (let item = queue.shift(); item; item = queue.shift()) {
+            if (!item.file) throw new Error(`The platform returned an upload for an unknown file: ${item.upload.path}`);
+            await uploadWithRetry(item.upload, item.file.data ?? (await readFile(item.file.full)), fetchImpl);
+            done += 1;
+            if (done % 25 === 0 || done === total) log(`  uploaded ${done}/${total}`);
+        }
+    }
+    await Promise.all(Array.from({ length: Math.min(CONCURRENCY, queue.length) }, worker));
+
+    // Each function becomes a Lambda version; the platform waits until it's ready.
+    for (const fn of built) {
+        const deployed = await client.deployFunction(slug, version, fn.name, fn.config);
+        log(`  ✔ function ${fn.name}  (${describeConfig(fn.config)})${deployed?.lambdaVersion ? `  Lambda version ${deployed.lambdaVersion}` : ''}`);
+    }
+
+    const completed = await client.completeVersion(
+        slug,
+        version,
+        files.map((f) => f.path),
+        serverFiles.map((f) => f.path),
+        built.map((fn) => fn.name),
+        report,
+        accessibility,
+        alias ? { alias, manifest } : {},
+    );
+    const n = completed.version ?? version;
+    log(`✔ Deployed v${n} of ${slug} (${completed.files ?? files.length} files${queriesNote}).${describeState(completed)}`);
+    if (completed.entryUrl) log(`  ${completed.entryUrl}`);
+    if (built.length && completed.state === 'pending') log('  (Versions with functions always need review, even on auto-approve apps.)');
+    if (completed.submissionCleared) log(`  ! ${submissionClearedMessage('version')}`);
+    if (completed.removedVersions?.length) log(`  Removed old versions ${completed.removedVersions.map((v) => `v${v}`).join(', ')}.`);
+    if (!alias) await warnAboutScopes({ client, slug, needs: neededScopes(serverFiles, built), log });
+    return completed;
+}
+
+/** Said when a deploy or register replaced what was waiting for approval: the platform cleared the request. */
+export function submissionClearedMessage(what) {
+    return `Your new ${what} cleared the waiting approval request: submit it again in HawkSearch (npx hawk-app open).`;
+}
+
+/** The scopes a version's own files need to run: queries need data:read, functions need functions:invoke. */
+function neededScopes(serverFiles, built) {
+    const needs = [];
+    if (serverFiles.some((f) => f.path.startsWith('queries/'))) needs.push('data:read');
+    if (built.length) needs.push('functions:invoke');
+    return needs;
+}
+
+/**
+ * A version that uses queries or functions while hawk-app.json's scopes (granted or waiting for approval) lack the scope
+ * gets 403 scope_missing at run time. Say so now. Best effort: a failed status check never fails a deploy that succeeded.
+ */
+async function warnAboutScopes({ client, slug, needs, log }) {
+    if (!needs.length || !client.status) return;
+    let app;
+    try {
+        app = await client.status(slug);
+    } catch (error) {
+        if (error?.status === 404) log(`  ! ${slug} isn't on the platform: add ${needs.join(', ')} to "scopes" in hawk-app.json and deploy again.`);
+        return;
+    }
+    const registered = new Set([...(app?.scopes ?? []), ...(app?.pendingScopes ?? [])]);
+    const missing = needs.filter((scope) => !registered.has(scope));
+    if (missing.length) {
+        log(`  ! This version uses ${missing.join(' and ')}, which hawk-app.json's scopes on the platform don't include. Add ${missing.length === 1 ? 'it' : 'them'} to "scopes" in hawk-app.json and deploy again, or calls fail with 403 scope_missing.`);
+    }
+}
+
+function describeQueries(count) {
+    return `${count} quer${count === 1 ? 'y' : 'ies'}`;
+}
+
+function describeState({ state, liveVersion, alias }) {
+    switch (state) {
+        case 'alias':
+            return ` ${alias} → it: only Bridgeline staff in its clients see it until it's approved. The main line (default, and the version under review) is unchanged.`;
+        case 'draft':
+            return ' Not released yet: only Bridgeline staff see it. Review it and submit it for approval in HawkSearch: npx hawk-app open.';
+        case 'pending':
+            return ` A draft: clients stay on ${liveVersion ? `v${liveVersion}` : 'the default version'} until it's approved. Submit it for approval in HawkSearch: npx hawk-app open.`;
+        case 'live':
+            return ' Auto-approved: released to clients.';
+        default:
+            return '';
+    }
+}
+
+async function checkFolder(dir, built) {
+    let info;
+    try {
+        info = await stat(dir);
+    } catch {
+        throw new Error(built ? `The build did not create "${dir}". Check the folder name (dist, out, build, ...).` : `Build folder "${dir}" not found.`);
+    }
+    if (!info.isDirectory()) throw new Error(`"${dir}" is not a folder.`);
+}
+
+/** Runs the project's `npm run build` with the version's base path, so asset URLs point at /<slug>/v<n>/. */
+export async function npmRunBuild({ basePath, cwd = process.cwd() }) {
+    const result = spawnSync('npm', ['run', 'build'], {
+        cwd,
+        stdio: 'inherit',
+        shell: process.platform === 'win32',
+        env: { ...process.env, HAWK_APP_BASE_PATH: basePath },
+    });
+    if (result.error) throw new Error(`Could not run \`npm run build\`: ${result.error.message}`);
+    if (result.status !== 0) {
+        throw new Error(`\`npm run build\` failed (exit code ${result.status}). Fix the build, or pass --no-build to upload the folder as it is.`);
+    }
+}
+
+/**
+ * Runs `npm audit --json --omit=dev` in the app folder: { status: 'checked', critical, high, moderate, low,
+ * dependencies, serious } or { status: 'not_checked', reason }. `serious` (the packages with high or critical findings)
+ * is for the developer only: deploy leaves it out of what it sends. Never throws: a deploy doesn't fail because of it. Reasons are
+ * fixed texts (no paths, no npm output) so nothing private reaches the platform.
+ */
+export async function auditDependencies({ cwd, runAudit = npmAudit }) {
+    const notChecked = (reason) => ({ status: 'not_checked', reason });
+    if (!hasLockfile(cwd)) return notChecked('no package-lock.json');
+    let stdout;
+    try {
+        // npm audit exits non-zero when it finds vulnerabilities: the JSON decides, not the exit code.
+        ({ stdout } = await runAudit({ cwd }));
+    } catch (error) {
+        return notChecked(error?.code === 'ETIMEDOUT' ? `npm audit timed out after ${AUDIT_TIMEOUT_MS / 1000} s` : 'could not run npm audit');
+    }
+    let result;
+    try {
+        result = JSON.parse(stdout);
+    } catch {
+        return notChecked('npm audit output was not JSON');
+    }
+    if (result?.error) {
+        const code = String(result.error.code ?? '');
+        return notChecked(/^[A-Z0-9_]{1,40}$/.test(code) ? `npm audit failed (${code})` : 'npm audit failed');
+    }
+    const counts = result?.metadata?.vulnerabilities;
+    const levels = ['critical', 'high', 'moderate', 'low'];
+    if (!counts || !levels.every((level) => Number.isInteger(counts[level]) && counts[level] >= 0)) {
+        return notChecked('npm audit output had no vulnerability counts');
+    }
+    const deps = result.metadata.dependencies;
+    const dependencies = [deps?.prod, deps?.total].find((n) => Number.isInteger(n) && n >= 0) ?? 0;
+    const serious = Object.entries(result.vulnerabilities ?? {})
+        .filter(([, v]) => v?.severity === 'critical' || v?.severity === 'high')
+        .map(([name]) => name)
+        .sort();
+    return { status: 'checked', ...Object.fromEntries(levels.map((level) => [level, counts[level]])), dependencies, serious };
+}
+
+/** A package-lock.json in the folder or above it: an npm workspace keeps one lockfile at the repository root, and npm audit finds it from the workspace folder. */
+function hasLockfile(dir) {
+    for (let current = dir; ; current = dirname(current)) {
+        if (existsSync(join(current, 'package-lock.json'))) return true;
+        if (dirname(current) === current) return false;
+    }
+}
+
+/**
+ * deploy's confirmAudit in the CLI: high or critical vulnerabilities fail the review's dependencies check (approvers can
+ * only force approve), so ask before deploying. --yes goes on with a warning; so does a pipeline (no terminal to ask).
+ */
+export async function confirmVulnerabilities(report, { yes = false, confirm = askYesNo, log = console.log } = {}) {
+    const packages = report.serious?.length ? ` (${report.serious.join(', ')})` : '';
+    const message = `npm audit found ${describeAudit(report).replace(' (npm audit)', '')} in the production dependencies${packages}. Approvers can only force approve this version.`;
+    if (yes) {
+        log(`! ${message}`);
+        return;
+    }
+    const answer = await confirm(`${message} Deploy anyway? (Fix with npm audit fix or by updating the packages; npm run app:audit shows the details.)`);
+    if (answer === null) {
+        log(`! ${message} Going on (no terminal to ask; add --yes to silence this).`);
+        return;
+    }
+    if (!answer) throw new Error('Cancelled. Nothing was deployed. `npm run app:audit` (or npm audit --omit=dev) shows the details.');
+}
+
+function describeAudit(report) {
+    if (report.status !== 'checked') return `not checked: ${report.reason}`;
+    const found = ['critical', 'high', 'moderate', 'low'].filter((level) => report[level]).map((level) => `${report[level]} ${level}`);
+    return found.length ? `${found.join(', ')} (npm audit)` : 'no known vulnerabilities';
+}
+
+/** Runs `npm audit --json --omit=dev` in `cwd`: { code, stdout }. Rejects when npm can't start or takes over `timeoutMs`. */
+export function npmAudit({ cwd, timeoutMs = AUDIT_TIMEOUT_MS }) {
+    return new Promise((resolve, reject) => {
+        const child = spawn('npm', ['audit', '--json', '--omit=dev'], { cwd, stdio: ['ignore', 'pipe', 'ignore'], shell: process.platform === 'win32' });
+        const chunks = [];
+        const timer = setTimeout(() => {
+            // With a shell on Windows the child is cmd.exe: end the whole tree, not only the shell.
+            if (process.platform === 'win32') spawnSync('taskkill', ['/pid', String(child.pid), '/T', '/F'], { stdio: 'ignore' });
+            else child.kill();
+            reject(Object.assign(new Error('npm audit timed out'), { code: 'ETIMEDOUT' }));
+        }, timeoutMs);
+        child.stdout.on('data', (chunk) => chunks.push(chunk));
+        child.on('error', (error) => {
+            clearTimeout(timer);
+            reject(error);
+        });
+        child.on('close', (code) => {
+            clearTimeout(timer);
+            resolve({ code, stdout: Buffer.concat(chunks).toString('utf8') });
+        });
+    });
+}
+
+async function uploadWithRetry(upload, body, fetchImpl) {
+    for (let attempt = 1; ; attempt++) {
+        try {
+            const response = await fetchImpl(upload.url, { method: 'PUT', headers: upload.headers, body });
+            if (response.ok) return;
+            const text = await response.text().catch(() => '');
+            if (response.status < 500 || attempt >= RETRIES) {
+                throw new Error(`Upload of ${upload.path} failed (${response.status}). ${response.status === 403 ? 'The upload link may have expired; run deploy again.' : text.slice(0, 200)}`);
+            }
+        } catch (error) {
+            if (attempt >= RETRIES || error.message?.startsWith('Upload of')) throw error;
+        }
+        await new Promise((resolve) => setTimeout(resolve, 500 * attempt));
+    }
+}
+
+function formatBytes(bytes) {
+    return bytes > 1024 * 1024 ? `${(bytes / 1024 / 1024).toFixed(1)} MB` : `${Math.ceil(bytes / 1024)} KB`;
+}