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

package/src/platform.mjs

@@ -1,116 +1,116 @@
-/** Talks to the Hawk Apps Platform with the publisher key (from the environment or .env.local, never a command-line flag). */
-export function platformClient({ url = process.env.HAWK_APPS_PLATFORM_URL, key = process.env.HAWK_APPS_PUBLISHER_KEY, fetchImpl = fetch } = {}) {
-    if (!url) throw new Error('No platform URL. Run `npx hawk-app sso` once on this machine, or set HAWK_APPS_PLATFORM_URL.');
-    if (!key || !key.includes('.')) throw new Error('Not logged in. Run `npx hawk-app sso` (Bridgeline account) or `npx hawk-app login` (publisher key) once on this machine (in CI, set HAWK_APPS_PUBLISHER_KEY).');
-    const base = url.replace(/\/+$/, '');
-
-    /** Sends a request and returns the HTTP status with the parsed body; throws a readable error for failures. */
-    async function request(method, path, body) {
-        let response;
-        try {
-            response = await fetchImpl(`${base}${path}`, {
-                method,
-                headers: { Authorization: `PublisherKey ${key}`, Accept: 'application/json', ...(body ? { 'Content-Type': 'application/json' } : {}) },
-                body: body ? JSON.stringify(body) : undefined,
-            });
-        } catch (error) {
-            throw new Error(`Could not reach ${base}: ${error.message}`);
-        }
-        const text = await response.text();
-        let data = {};
-        try {
-            data = text ? JSON.parse(text) : {};
-        } catch {
-            data = { detail: text.slice(0, 300) };
-        }
-        if (!response.ok) {
-            const lines = [`${response.status} ${data.title ?? response.statusText}${data.detail ? `: ${data.detail}` : ''}`];
-            for (const error of data.errors ?? []) lines.push(`  - ${error}`);
-            for (const missing of data.missing ?? []) lines.push(`  - missing: ${missing}`);
-            if (response.status === 401) lines.push('  The key was refused (revoked, or expired: keys from `hawk-app sso` last 90 days). Run `npx hawk-app sso` or `npx hawk-app login` again; in CI, check HAWK_APPS_PUBLISHER_KEY.');
-            const err = new Error(lines.join('\n'));
-            err.status = response.status;
-            err.data = data;
-            const retryAfter = Number(response.headers.get('Retry-After'));
-            if (response.headers.has('Retry-After') && Number.isFinite(retryAfter) && retryAfter >= 0) err.retryAfterMs = retryAfter * 1000;
-            throw err;
-        }
-        return { status: response.status, data };
-    }
-
-    const call = async (method, path, body) => (await request(method, path, body)).data;
-
-    return {
-        base,
-        reserveVersion: (slug) => call('POST', `/publish/apps/${encodeURIComponent(slug)}/versions`, {}),
-        // serverFiles: the app's queries/ files, for the private server bucket; functionFiles: each function's
-        // bundle.zip, source.zip and deps.json (both left out when there are none).
-        startUploads: (slug, version, files, serverFiles = [], functionFiles = []) =>
-            call('POST', `/publish/apps/${encodeURIComponent(slug)}/versions/${version}/uploads`, {
-                files,
-                ...(serverFiles.length ? { serverFiles } : {}),
-                ...(functionFiles.length ? { functionFiles } : {}),
-            }),
-        /** Creates or updates the function's Lambda from the uploaded bundle: { name, lambdaVersion, codeSha256 }. */
-        deployFunction: (slug, version, name, config) =>
-            call('POST', `/publish/apps/${encodeURIComponent(slug)}/versions/${version}/functions/${encodeURIComponent(name)}`, config),
-        /** `extra`: `{ alias, manifest }` for a deploy for an alias (the branch's hawk-app.json goes with it). */
-        completeVersion: (slug, version, files, serverFiles = [], functions = [], audit, accessibility, extra = {}) =>
-            call('POST', `/publish/apps/${encodeURIComponent(slug)}/versions/${version}/complete`, {
-                files,
-                ...(extra.alias ? { alias: extra.alias } : {}),
-                ...(extra.manifest ? { manifest: extra.manifest } : {}),
-                ...(serverFiles.length ? { serverFiles } : {}),
-                ...(functions.length ? { functions } : {}),
-                ...(audit ? { audit } : {}),
-                ...(accessibility ? { accessibility } : {}),
-            }),
-        /** The app's secrets: { secrets: [{ name, updatedAt }] } (never values). */
-        listSecrets: (slug) => call('GET', `/publish/apps/${encodeURIComponent(slug)}/secrets`),
-        setSecret: (slug, name, value) => call('PUT', `/publish/apps/${encodeURIComponent(slug)}/secrets/${encodeURIComponent(name)}`, { value }),
-        /** The app's config keys and stored values (ConfigView): { keys: [{ key, declared, type, label, description, default, global, clients }] }. */
-        getConfig: (slug) => call('GET', `/publish/apps/${encodeURIComponent(slug)}/config`),
-        /** Sets (or, with value null, clears) a config value, global or for one client; resolves to the ConfigView. */
-        setConfig: (slug, key, value, clientId = null) =>
-            call('PUT', `/publish/apps/${encodeURIComponent(slug)}/config/${encodeURIComponent(key)}`, { value, clientId: clientId ?? null }),
-        deleteSecret: (slug, name) => call('DELETE', `/publish/apps/${encodeURIComponent(slug)}/secrets/${encodeURIComponent(name)}`),
-        /** The app's errors over `days`: { days, total, groups: [{ fingerprint, kind, message, stack, source, count, versions, clients, firstDay, lastDay }] }. */
-        appErrors: (slug, days) => call('GET', `/publish/apps/${encodeURIComponent(slug)}/errors?days=${days}`),
-        /** The app's opens over `days`: { opens, viewOpens, staffOpens, users, clients, perDay, perClient }. */
-        appUsage: (slug, days) => call('GET', `/publish/apps/${encodeURIComponent(slug)}/usage?days=${days}`),
-        /** One page of a function's logs: { events: [{ timestamp, message }], nextToken }. */
-        functionLogs: (slug, name, { since, nextToken } = {}) => {
-            const query = new URLSearchParams();
-            if (since) query.set('since', since);
-            if (nextToken) query.set('nextToken', nextToken);
-            const qs = query.toString();
-            return call('GET', `/publish/apps/${encodeURIComponent(slug)}/functions/${encodeURIComponent(name)}/logs${qs ? `?${qs}` : ''}`);
-        },
-        register: (slug, manifest, dryRun) => call('PUT', `/publish/apps/${encodeURIComponent(slug)}${dryRun ? '?dryRun=true' : ''}`, manifest),
-        status: (slug) => call('GET', `/publish/apps/${encodeURIComponent(slug)}`),
-        /** Which clients have the app (the registry, not hawk-app.json): { visibility, clients: [{ id, name, enabled }] }. */
-        listClients: (slug) => call('GET', `/publish/apps/${encodeURIComponent(slug)}/clients`),
-        /** Gives a client the app (enabled true) or opts it out (false), at once: { id, name, enabled }. */
-        setClient: (slug, clientId, body) => call('PUT', `/publish/apps/${encodeURIComponent(slug)}/clients/${encodeURIComponent(clientId)}`, body),
-        /**
-         * Points an alias at a version that isn't approved (developers; approvers do the rest): only Bridgeline staff in its
-         * clients see it. The app's aliases: [{ name, version, status, … }].
-         */
-        setAlias: (slug, name, version) => call('PUT', `/publish/apps/${encodeURIComponent(slug)}/aliases/${encodeURIComponent(name)}`, { version }),
-        /** Deletes an alias of the developer's: not approved, no clients on it. */
-        deleteAlias: (slug, name) => call('DELETE', `/publish/apps/${encodeURIComponent(slug)}/aliases/${encodeURIComponent(name)}`),
-        /** The app's versions, newest first: { versions: [{ version, status, aliases, deployedFor, createdAt, … }] }. */
-        listVersions: (slug) => call('GET', `/publish/apps/${encodeURIComponent(slug)}/versions`),
-        /** The environment's clients matching a name or id, best first: { clients: [{ id, name }], more }. */
-        searchClients: (text) => call('GET', `/publish/clients?search=${encodeURIComponent(text)}`),
-        removeClient: (slug, clientId) =>call('DELETE', `/publish/apps/${encodeURIComponent(slug)}/clients/${encodeURIComponent(clientId)}`),
-        /** An app token for local development (hawk-app dev): { token, expiresAt, version, scopes, apiBaseUrl, user, hawkSearch }. */
-        devToken: (slug, body) => call('POST', `/publish/apps/${encodeURIComponent(slug)}/dev-token`, body),
-        /** Lists the tables; with an app slug, its sensitive tables are available if Engineering opted the app in. */
-        dataTables: (app) => call('GET', `/publish/data/tables${app ? `?app=${encodeURIComponent(app)}` : ''}`),
-
-        /** Runs SQL against a client's data (dev platform only). Resolves to { status: 200 | 202, data }. */
-        dataRun: (body) => request('POST', '/publish/data/run', body),
-        dataExecution: (executionId) => request('GET', `/publish/data/executions/${encodeURIComponent(executionId)}`),
-    };
-}
+/** Talks to the Hawk Apps Platform with the publisher key (from the environment or .env.local, never a command-line flag). */
+export function platformClient({ url = process.env.HAWK_APPS_PLATFORM_URL, key = process.env.HAWK_APPS_PUBLISHER_KEY, fetchImpl = fetch } = {}) {
+    if (!url) throw new Error('No platform URL. Run `npx hawk-app sso` once on this machine, or set HAWK_APPS_PLATFORM_URL.');
+    if (!key || !key.includes('.')) throw new Error('Not logged in. Run `npx hawk-app sso` (Bridgeline account) or `npx hawk-app login` (publisher key) once on this machine (in CI, set HAWK_APPS_PUBLISHER_KEY).');
+    const base = url.replace(/\/+$/, '');
+
+    /** Sends a request and returns the HTTP status with the parsed body; throws a readable error for failures. */
+    async function request(method, path, body) {
+        let response;
+        try {
+            response = await fetchImpl(`${base}${path}`, {
+                method,
+                headers: { Authorization: `PublisherKey ${key}`, Accept: 'application/json', ...(body ? { 'Content-Type': 'application/json' } : {}) },
+                body: body ? JSON.stringify(body) : undefined,
+            });
+        } catch (error) {
+            throw new Error(`Could not reach ${base}: ${error.message}`);
+        }
+        const text = await response.text();
+        let data = {};
+        try {
+            data = text ? JSON.parse(text) : {};
+        } catch {
+            data = { detail: text.slice(0, 300) };
+        }
+        if (!response.ok) {
+            const lines = [`${response.status} ${data.title ?? response.statusText}${data.detail ? `: ${data.detail}` : ''}`];
+            for (const error of data.errors ?? []) lines.push(`  - ${error}`);
+            for (const missing of data.missing ?? []) lines.push(`  - missing: ${missing}`);
+            if (response.status === 401) lines.push('  The key was refused (revoked, or expired: keys from `hawk-app sso` last 90 days). Run `npx hawk-app sso` or `npx hawk-app login` again; in CI, check HAWK_APPS_PUBLISHER_KEY.');
+            const err = new Error(lines.join('\n'));
+            err.status = response.status;
+            err.data = data;
+            const retryAfter = Number(response.headers.get('Retry-After'));
+            if (response.headers.has('Retry-After') && Number.isFinite(retryAfter) && retryAfter >= 0) err.retryAfterMs = retryAfter * 1000;
+            throw err;
+        }
+        return { status: response.status, data };
+    }
+
+    const call = async (method, path, body) => (await request(method, path, body)).data;
+
+    return {
+        base,
+        reserveVersion: (slug) => call('POST', `/publish/apps/${encodeURIComponent(slug)}/versions`, {}),
+        // serverFiles: the app's queries/ files, for the private server bucket; functionFiles: each function's
+        // bundle.zip, source.zip and deps.json (both left out when there are none).
+        startUploads: (slug, version, files, serverFiles = [], functionFiles = []) =>
+            call('POST', `/publish/apps/${encodeURIComponent(slug)}/versions/${version}/uploads`, {
+                files,
+                ...(serverFiles.length ? { serverFiles } : {}),
+                ...(functionFiles.length ? { functionFiles } : {}),
+            }),
+        /** Creates or updates the function's Lambda from the uploaded bundle: { name, lambdaVersion, codeSha256 }. */
+        deployFunction: (slug, version, name, config) =>
+            call('POST', `/publish/apps/${encodeURIComponent(slug)}/versions/${version}/functions/${encodeURIComponent(name)}`, config),
+        /** `extra`: `{ alias, manifest }` for a deploy for an alias (the branch's hawk-app.json goes with it). */
+        completeVersion: (slug, version, files, serverFiles = [], functions = [], audit, accessibility, extra = {}) =>
+            call('POST', `/publish/apps/${encodeURIComponent(slug)}/versions/${version}/complete`, {
+                files,
+                ...(extra.alias ? { alias: extra.alias } : {}),
+                ...(extra.manifest ? { manifest: extra.manifest } : {}),
+                ...(serverFiles.length ? { serverFiles } : {}),
+                ...(functions.length ? { functions } : {}),
+                ...(audit ? { audit } : {}),
+                ...(accessibility ? { accessibility } : {}),
+            }),
+        /** The app's secrets: { secrets: [{ name, updatedAt }] } (never values). */
+        listSecrets: (slug) => call('GET', `/publish/apps/${encodeURIComponent(slug)}/secrets`),
+        setSecret: (slug, name, value) => call('PUT', `/publish/apps/${encodeURIComponent(slug)}/secrets/${encodeURIComponent(name)}`, { value }),
+        /** The app's config keys and stored values (ConfigView): { keys: [{ key, declared, type, label, description, default, global, clients }] }. */
+        getConfig: (slug) => call('GET', `/publish/apps/${encodeURIComponent(slug)}/config`),
+        /** Sets (or, with value null, clears) a config value, global or for one client; resolves to the ConfigView. */
+        setConfig: (slug, key, value, clientId = null) =>
+            call('PUT', `/publish/apps/${encodeURIComponent(slug)}/config/${encodeURIComponent(key)}`, { value, clientId: clientId ?? null }),
+        deleteSecret: (slug, name) => call('DELETE', `/publish/apps/${encodeURIComponent(slug)}/secrets/${encodeURIComponent(name)}`),
+        /** The app's errors over `days`: { days, total, groups: [{ fingerprint, kind, message, stack, source, count, versions, clients, firstDay, lastDay }] }. */
+        appErrors: (slug, days) => call('GET', `/publish/apps/${encodeURIComponent(slug)}/errors?days=${days}`),
+        /** The app's opens over `days`: { opens, viewOpens, staffOpens, users, clients, perDay, perClient }. */
+        appUsage: (slug, days) => call('GET', `/publish/apps/${encodeURIComponent(slug)}/usage?days=${days}`),
+        /** One page of a function's logs: { events: [{ timestamp, message }], nextToken }. */
+        functionLogs: (slug, name, { since, nextToken } = {}) => {
+            const query = new URLSearchParams();
+            if (since) query.set('since', since);
+            if (nextToken) query.set('nextToken', nextToken);
+            const qs = query.toString();
+            return call('GET', `/publish/apps/${encodeURIComponent(slug)}/functions/${encodeURIComponent(name)}/logs${qs ? `?${qs}` : ''}`);
+        },
+        register: (slug, manifest, dryRun) => call('PUT', `/publish/apps/${encodeURIComponent(slug)}${dryRun ? '?dryRun=true' : ''}`, manifest),
+        status: (slug) => call('GET', `/publish/apps/${encodeURIComponent(slug)}`),
+        /** Which clients have the app (the registry, not hawk-app.json): { visibility, clients: [{ id, name, enabled }] }. */
+        listClients: (slug) => call('GET', `/publish/apps/${encodeURIComponent(slug)}/clients`),
+        /** Gives a client the app (enabled true) or opts it out (false), at once: { id, name, enabled }. */
+        setClient: (slug, clientId, body) => call('PUT', `/publish/apps/${encodeURIComponent(slug)}/clients/${encodeURIComponent(clientId)}`, body),
+        /**
+         * Points an alias at a version that isn't approved (developers; approvers do the rest): only Bridgeline staff in its
+         * clients see it. The app's aliases: [{ name, version, status, … }].
+         */
+        setAlias: (slug, name, version) => call('PUT', `/publish/apps/${encodeURIComponent(slug)}/aliases/${encodeURIComponent(name)}`, { version }),
+        /** Deletes an alias of the developer's: not approved, no clients on it. */
+        deleteAlias: (slug, name) => call('DELETE', `/publish/apps/${encodeURIComponent(slug)}/aliases/${encodeURIComponent(name)}`),
+        /** The app's versions, newest first: { versions: [{ version, status, aliases, deployedFor, createdAt, … }] }. */
+        listVersions: (slug) => call('GET', `/publish/apps/${encodeURIComponent(slug)}/versions`),
+        /** The environment's clients matching a name or id, best first: { clients: [{ id, name }], more }. */
+        searchClients: (text) => call('GET', `/publish/clients?search=${encodeURIComponent(text)}`),
+        removeClient: (slug, clientId) =>call('DELETE', `/publish/apps/${encodeURIComponent(slug)}/clients/${encodeURIComponent(clientId)}`),
+        /** An app token for local development (hawk-app dev): { token, expiresAt, version, scopes, apiBaseUrl, user, hawkSearch }. */
+        devToken: (slug, body) => call('POST', `/publish/apps/${encodeURIComponent(slug)}/dev-token`, body),
+        /** Lists the tables; with an app slug, its sensitive tables are available if Engineering opted the app in. */
+        dataTables: (app) => call('GET', `/publish/data/tables${app ? `?app=${encodeURIComponent(app)}` : ''}`),
+
+        /** Runs SQL against a client's data (dev platform only). Resolves to { status: 200 | 202, data }. */
+        dataRun: (body) => request('POST', '/publish/data/run', body),
+        dataExecution: (executionId) => request('GET', `/publish/data/executions/${encodeURIComponent(executionId)}`),
+    };
+}

package/src/project-checks.mjs

@@ -1,153 +1,153 @@
-// Checks of the app's project (not hawk-app.json) that hold for any app, from a template or not: `hawk-app validate`
-// runs them, and deploy runs checkBuildUrls on what it's about to upload.
-import { existsSync, readFileSync } from 'node:fs';
-import { readdir, readFile } from 'node:fs/promises';
-import { join, relative, sep } from 'node:path';
-import { fileURLToPath } from 'node:url';
-import { compareVersions, minVersion } from './upgrade.mjs';
-import { TEMPLATES } from './create.mjs';
-
-const BRIDGE = '@bridgeline-digital/hawk-app-bridge';
-const CLI = '@bridgeline-digital/hawk-app-cli';
-const CDN_IMPORT = /hawk-app-bridge@(\d+)\.(\d+)/;
-const SOURCE_FILE = /\.(html?|m?[jt]sx?|vue|svelte)$/;
-const SKIP_DIRS = new Set(['node_modules', 'dist', 'out', 'build', '.next', 'coverage', 'functions', 'queries']);
-const MAX_SCANNED = 2000;
-
-/** The bridge version the CLI's templates use, e.g. { parts: [0, 5, 0] }. */
-function supportedBridge() {
-    const pkg = JSON.parse(readFileSync(fileURLToPath(new URL('../templates/react/package.json', import.meta.url)), 'utf8'));
-    return minVersion(pkg.dependencies[BRIDGE]);
-}
-
-const minor = (v) => `${v.parts[0]}.${v.parts[1]}`;
-
-/** Files under `dir` worth scanning for the bridge (sources and HTML), skipping dependencies and build output. */
-async function sourceFiles(dir) {
-    const files = [];
-    async function walk(current) {
-        for (const entry of await readdir(current, { withFileTypes: true })) {
-            if (files.length >= MAX_SCANNED) return;
-            if (entry.name.startsWith('.')) continue;
-            const full = join(current, entry.name);
-            if (entry.isDirectory()) {
-                if (!SKIP_DIRS.has(entry.name)) await walk(full);
-            } else if (SOURCE_FILE.test(entry.name)) {
-                files.push(full);
-            }
-        }
-    }
-    await walk(dir);
-    return files;
-}
-
-/**
- * The project checks: the bridge is used and on a supported version, and there's a way to build (or the app deploys
- * as plain files). Only warnings: an app can be right in ways these can't see. { warnings }.
- */
-export async function checkProject(dir) {
-    const warnings = [];
-    const supported = supportedBridge();
-    const pkgFile = join(dir, 'package.json');
-    const pkg = existsSync(pkgFile) ? JSON.parse(readFileSync(pkgFile, 'utf8')) : null;
-
-    const range = pkg?.dependencies?.[BRIDGE] ?? pkg?.devDependencies?.[BRIDGE];
-    if (range) {
-        const have = minVersion(range);
-        if (have && compareVersions({ parts: [...have.parts.slice(0, 2), 0], pre: null }, { parts: [...supported.parts.slice(0, 2), 0], pre: null }) < 0) {
-            warnings.push(`${BRIDGE} is ${range}, older than the ${minor(supported)} this CLI's templates use: npm install ${BRIDGE}@^${supported.parts.join('.')}.`);
-        }
-    } else {
-        let cdn = null;
-        for (const file of await sourceFiles(dir)) {
-            const match = CDN_IMPORT.exec(await readFile(file, 'utf8'));
-            if (match) {
-                cdn = { file: relative(dir, file).split(sep).join('/'), parts: [Number(match[1]), Number(match[2]), 0] };
-                break;
-            }
-        }
-        if (!cdn) {
-            warnings.push(`The app doesn't use the bridge (${BRIDGE}): install it, or import it from the CDN. See AGENTS.md.`);
-        } else if (compareVersions({ parts: cdn.parts, pre: null }, { parts: [...supported.parts.slice(0, 2), 0], pre: null }) < 0) {
-            warnings.push(`${cdn.file} imports the bridge ${cdn.parts[0]}.${cdn.parts[1]} from the CDN, older than the ${minor(supported)} this CLI's templates use.`);
-        }
-    }
-
-    if (pkg && !pkg.devDependencies?.[CLI] && !pkg.dependencies?.[CLI] && (existsSync(join(dir, '.mcp.json')) || existsSync(join(dir, '.vscode', 'mcp.json')))) {
-        warnings.push(`${CLI} isn't a dev dependency, but the MCP settings start it from node_modules: npm install -D ${CLI}.`);
-    }
-    if (!pkg) {
-        warnings.push('No package.json: deploy uploads the folder as it is, and npm audit cannot run, so the review\'s dependencies check fails.');
-    } else if (!pkg.scripts?.build) {
-        // Without a build script, deploy uploads the folder as it is: fine for plain files, not for a bundler's app.
-        const bundler = ['next', 'vite', 'react-scripts', 'webpack', 'parcel'].find((name) => pkg.dependencies?.[name] || pkg.devDependencies?.[name]);
-        if (bundler) warnings.push(`No "build" script in package.json, but the app uses ${bundler}: \`hawk-app deploy\` would upload the folder unbuilt. Add a build script.`);
-    }
-    return { warnings };
-}
-
-/** The build folder and whether it's built, from package.json's app:deploy script (`hawk-app deploy <folder> [--no-build]`). */
-export function deployScript(dir) {
-    const pkgFile = join(dir, 'package.json');
-    if (!existsSync(pkgFile)) return null;
-    const script = JSON.parse(readFileSync(pkgFile, 'utf8')).scripts?.['app:deploy'] ?? '';
-    const match = /hawk-app\s+deploy\s+([^\s-][^\s]*)/.exec(script);
-    return match ? { folder: match[1], build: !/--no-build/.test(script) } : null;
-}
-
-/**
- * Where deploy finds the build and whether it builds first: the folder given, else the one in the app:deploy script,
- * else the template's (hawk-app.json `template`), else the framework's (Next.js `out`, Vite `dist`, plain `public`).
- * It builds when package.json has a `build` script and app:deploy doesn't say --no-build. Null when it can't tell.
- */
-export function buildTarget(dir, manifest, folder) {
-    const pkgFile = join(dir, 'package.json');
-    const pkg = existsSync(pkgFile) ? JSON.parse(readFileSync(pkgFile, 'utf8')) : {};
-    const deps = { ...pkg.dependencies, ...pkg.devDependencies };
-    const script = deployScript(dir);
-    const hasBuild = !!pkg.scripts?.build;
-    const found =
-        folder ??
-        script?.folder ??
-        TEMPLATES[manifest?.template]?.build ??
-        (deps.next ? 'out' : deps.vite ? 'dist' : !hasBuild && existsSync(join(dir, 'public')) ? 'public' : null);
-    return found ? { folder: found, build: hasBuild && script?.build !== false } : null;
-}
-
-const URL_ATTRIBUTE = /\s(?:src|href|srcset|poster|data-src)\s*=\s*["']?(\/[^"'\s>]*)/gi;
-// Connection hints load nothing: Next.js adds <link rel="preconnect" href="/"> when a page's CSS has fonts not loaded
-// through next/font (e.g. Fontsource).
-const RESOURCE_HINT = /<link\b[^>]*\brel\s*=\s*["']?(?:preconnect|dns-prefetch)\b[^>]*>/gi;
-
-/**
- * Absolute URLs in the built HTML that fall outside `basePath` (`/<slug>/v<n>`): they load nothing once deployed,
- * because each version is served from its own folder. [{ file, url }], at most `limit`.
- */
-export async function checkBuildUrls(folder, basePath, limit = 5) {
-    const found = [];
-    async function walk(current) {
-        for (const entry of await readdir(current, { withFileTypes: true })) {
-            if (found.length >= limit || entry.name.startsWith('.')) continue;
-            const full = join(current, entry.name);
-            if (entry.isDirectory()) {
-                await walk(full);
-            } else if (/\.html?$/i.test(entry.name)) {
-                const text = (await readFile(full, 'utf8')).replace(RESOURCE_HINT, '');
-                for (const match of text.matchAll(URL_ATTRIBUTE)) {
-                    const url = match[1];
-                    if (url.startsWith('//') || url === basePath || url.startsWith(`${basePath}/`)) continue;
-                    found.push({ file: relative(folder, full).split(sep).join('/'), url });
-                    if (found.length >= limit) break;
-                }
-            }
-        }
-    }
-    if (existsSync(folder)) await walk(folder);
-    return found;
-}
-
-/** The message for checkBuildUrls' findings. */
-export function describeBuildUrls(found, basePath) {
-    const list = found.map((f) => `${f.file}: ${f.url}`).join(', ');
-    return `Absolute URLs outside ${basePath}/ (${list}) won't load once deployed: each version is served from its own folder. Read HAWK_APP_BASE_PATH in the build config, or use relative URLs (see AGENTS.md).`;
-}
+// Checks of the app's project (not hawk-app.json) that hold for any app, from a template or not: `hawk-app validate`
+// runs them, and deploy runs checkBuildUrls on what it's about to upload.
+import { existsSync, readFileSync } from 'node:fs';
+import { readdir, readFile } from 'node:fs/promises';
+import { join, relative, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { compareVersions, minVersion } from './upgrade.mjs';
+import { TEMPLATES } from './create.mjs';
+
+const BRIDGE = '@bridgeline-digital/hawk-app-bridge';
+const CLI = '@bridgeline-digital/hawk-app-cli';
+const CDN_IMPORT = /hawk-app-bridge@(\d+)\.(\d+)/;
+const SOURCE_FILE = /\.(html?|m?[jt]sx?|vue|svelte)$/;
+const SKIP_DIRS = new Set(['node_modules', 'dist', 'out', 'build', '.next', 'coverage', 'functions', 'queries']);
+const MAX_SCANNED = 2000;
+
+/** The bridge version the CLI's templates use, e.g. { parts: [0, 5, 0] }. */
+function supportedBridge() {
+    const pkg = JSON.parse(readFileSync(fileURLToPath(new URL('../templates/react/package.json', import.meta.url)), 'utf8'));
+    return minVersion(pkg.dependencies[BRIDGE]);
+}
+
+const minor = (v) => `${v.parts[0]}.${v.parts[1]}`;
+
+/** Files under `dir` worth scanning for the bridge (sources and HTML), skipping dependencies and build output. */
+async function sourceFiles(dir) {
+    const files = [];
+    async function walk(current) {
+        for (const entry of await readdir(current, { withFileTypes: true })) {
+            if (files.length >= MAX_SCANNED) return;
+            if (entry.name.startsWith('.')) continue;
+            const full = join(current, entry.name);
+            if (entry.isDirectory()) {
+                if (!SKIP_DIRS.has(entry.name)) await walk(full);
+            } else if (SOURCE_FILE.test(entry.name)) {
+                files.push(full);
+            }
+        }
+    }
+    await walk(dir);
+    return files;
+}
+
+/**
+ * The project checks: the bridge is used and on a supported version, and there's a way to build (or the app deploys
+ * as plain files). Only warnings: an app can be right in ways these can't see. { warnings }.
+ */
+export async function checkProject(dir) {
+    const warnings = [];
+    const supported = supportedBridge();
+    const pkgFile = join(dir, 'package.json');
+    const pkg = existsSync(pkgFile) ? JSON.parse(readFileSync(pkgFile, 'utf8')) : null;
+
+    const range = pkg?.dependencies?.[BRIDGE] ?? pkg?.devDependencies?.[BRIDGE];
+    if (range) {
+        const have = minVersion(range);
+        if (have && compareVersions({ parts: [...have.parts.slice(0, 2), 0], pre: null }, { parts: [...supported.parts.slice(0, 2), 0], pre: null }) < 0) {
+            warnings.push(`${BRIDGE} is ${range}, older than the ${minor(supported)} this CLI's templates use: npm install ${BRIDGE}@^${supported.parts.join('.')}.`);
+        }
+    } else {
+        let cdn = null;
+        for (const file of await sourceFiles(dir)) {
+            const match = CDN_IMPORT.exec(await readFile(file, 'utf8'));
+            if (match) {
+                cdn = { file: relative(dir, file).split(sep).join('/'), parts: [Number(match[1]), Number(match[2]), 0] };
+                break;
+            }
+        }
+        if (!cdn) {
+            warnings.push(`The app doesn't use the bridge (${BRIDGE}): install it, or import it from the CDN. See AGENTS.md.`);
+        } else if (compareVersions({ parts: cdn.parts, pre: null }, { parts: [...supported.parts.slice(0, 2), 0], pre: null }) < 0) {
+            warnings.push(`${cdn.file} imports the bridge ${cdn.parts[0]}.${cdn.parts[1]} from the CDN, older than the ${minor(supported)} this CLI's templates use.`);
+        }
+    }
+
+    if (pkg && !pkg.devDependencies?.[CLI] && !pkg.dependencies?.[CLI] && (existsSync(join(dir, '.mcp.json')) || existsSync(join(dir, '.vscode', 'mcp.json')))) {
+        warnings.push(`${CLI} isn't a dev dependency, but the MCP settings start it from node_modules: npm install -D ${CLI}.`);
+    }
+    if (!pkg) {
+        warnings.push('No package.json: deploy uploads the folder as it is, and npm audit cannot run, so the review\'s dependencies check fails.');
+    } else if (!pkg.scripts?.build) {
+        // Without a build script, deploy uploads the folder as it is: fine for plain files, not for a bundler's app.
+        const bundler = ['next', 'vite', 'react-scripts', 'webpack', 'parcel'].find((name) => pkg.dependencies?.[name] || pkg.devDependencies?.[name]);
+        if (bundler) warnings.push(`No "build" script in package.json, but the app uses ${bundler}: \`hawk-app deploy\` would upload the folder unbuilt. Add a build script.`);
+    }
+    return { warnings };
+}
+
+/** The build folder and whether it's built, from package.json's app:deploy script (`hawk-app deploy <folder> [--no-build]`). */
+export function deployScript(dir) {
+    const pkgFile = join(dir, 'package.json');
+    if (!existsSync(pkgFile)) return null;
+    const script = JSON.parse(readFileSync(pkgFile, 'utf8')).scripts?.['app:deploy'] ?? '';
+    const match = /hawk-app\s+deploy\s+([^\s-][^\s]*)/.exec(script);
+    return match ? { folder: match[1], build: !/--no-build/.test(script) } : null;
+}
+
+/**
+ * Where deploy finds the build and whether it builds first: the folder given, else the one in the app:deploy script,
+ * else the template's (hawk-app.json `template`), else the framework's (Next.js `out`, Vite `dist`, plain `public`).
+ * It builds when package.json has a `build` script and app:deploy doesn't say --no-build. Null when it can't tell.
+ */
+export function buildTarget(dir, manifest, folder) {
+    const pkgFile = join(dir, 'package.json');
+    const pkg = existsSync(pkgFile) ? JSON.parse(readFileSync(pkgFile, 'utf8')) : {};
+    const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+    const script = deployScript(dir);
+    const hasBuild = !!pkg.scripts?.build;
+    const found =
+        folder ??
+        script?.folder ??
+        TEMPLATES[manifest?.template]?.build ??
+        (deps.next ? 'out' : deps.vite ? 'dist' : !hasBuild && existsSync(join(dir, 'public')) ? 'public' : null);
+    return found ? { folder: found, build: hasBuild && script?.build !== false } : null;
+}
+
+const URL_ATTRIBUTE = /\s(?:src|href|srcset|poster|data-src)\s*=\s*["']?(\/[^"'\s>]*)/gi;
+// Connection hints load nothing: Next.js adds <link rel="preconnect" href="/"> when a page's CSS has fonts not loaded
+// through next/font (e.g. Fontsource).
+const RESOURCE_HINT = /<link\b[^>]*\brel\s*=\s*["']?(?:preconnect|dns-prefetch)\b[^>]*>/gi;
+
+/**
+ * Absolute URLs in the built HTML that fall outside `basePath` (`/<slug>/v<n>`): they load nothing once deployed,
+ * because each version is served from its own folder. [{ file, url }], at most `limit`.
+ */
+export async function checkBuildUrls(folder, basePath, limit = 5) {
+    const found = [];
+    async function walk(current) {
+        for (const entry of await readdir(current, { withFileTypes: true })) {
+            if (found.length >= limit || entry.name.startsWith('.')) continue;
+            const full = join(current, entry.name);
+            if (entry.isDirectory()) {
+                await walk(full);
+            } else if (/\.html?$/i.test(entry.name)) {
+                const text = (await readFile(full, 'utf8')).replace(RESOURCE_HINT, '');
+                for (const match of text.matchAll(URL_ATTRIBUTE)) {
+                    const url = match[1];
+                    if (url.startsWith('//') || url === basePath || url.startsWith(`${basePath}/`)) continue;
+                    found.push({ file: relative(folder, full).split(sep).join('/'), url });
+                    if (found.length >= limit) break;
+                }
+            }
+        }
+    }
+    if (existsSync(folder)) await walk(folder);
+    return found;
+}
+
+/** The message for checkBuildUrls' findings. */
+export function describeBuildUrls(found, basePath) {
+    const list = found.map((f) => `${f.file}: ${f.url}`).join(', ');
+    return `Absolute URLs outside ${basePath}/ (${list}) won't load once deployed: each version is served from its own folder. Read HAWK_APP_BASE_PATH in the build config, or use relative URLs (see AGENTS.md).`;
+}