@bridgeline-digital/hawk-app-cli 0.0.0-stage → 0.1.0-dev.20261020205204

package/src/platform.mjs

@@ -0,0 +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)}`),
+    };
+}

package/src/project-checks.mjs

@@ -0,0 +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).`;
+}

package/src/queries.mjs

@@ -0,0 +1,289 @@
+import { existsSync } from 'node:fs';
+import { readdir, readFile, stat } from 'node:fs/promises';
+import { join } from 'node:path';
+
+// App queries (`data:read`): queries/<name>.sql + queries/<name>.json, deployed with each version and run by the
+// platform against the current client's data. Same rules as the platform, which validates again on deploy.
+export const QUERIES_DIR = 'queries';
+export const DATA_SCOPE = 'data:read';
+export const MAX_QUERIES = 50;
+export const MAX_SQL_BYTES = 64 * 1024;
+export const MAX_STRING_LENGTH = 1000;
+export const MAX_LIST_ITEMS = 100;
+export const PARAM_TYPES = ['string', 'int', 'decimal', 'date', 'timestamp', 'boolean', 'string[]'];
+
+const NAME = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+const PARAM_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
+const IDENTIFIER = /^[A-Za-z_][A-Za-z0-9_]*$/;
+const PARAM_KEYS = ['name', 'type', 'required', 'default', 'min', 'max', 'maxItems'];
+const DATE = /^\d{4}-\d{2}-\d{2}$/;
+const TIMESTAMP = /^\d{4}-\d{2}-\d{2}([T ]\d{2}:\d{2}(:\d{2}(\.\d+)?)?(Z|[+-]\d{2}:?\d{2})?)?$/;
+
+/**
+ * Reads and checks `<projectDir>/queries`. `files` are the upload entries (`queries/<name>.sql|.json`, size, full
+ * path); `queries` the parsed definitions by name. Returns null when the folder doesn't exist.
+ * @returns {Promise<{ files: { path: string, size: number, full: string }[], queries: { name: string, sql: string, params: object[] }[], errors: string[] } | null>}
+ */
+export async function loadQueries(projectDir) {
+    const dir = join(projectDir, QUERIES_DIR);
+    if (!existsSync(dir)) return null;
+    const errors = [];
+    const files = [];
+    const byName = new Map();
+
+    for (const entry of await readdir(dir, { withFileTypes: true })) {
+        if (entry.name.startsWith('.')) continue;
+        if (!entry.isFile()) {
+            errors.push(`${QUERIES_DIR}/${entry.name}: queries can't be in subfolders; put <name>.sql and <name>.json straight in ${QUERIES_DIR}/.`);
+            continue;
+        }
+        const match = /^(.*)\.(sql|json)$/.exec(entry.name);
+        if (!match) {
+            errors.push(`${QUERIES_DIR}/${entry.name}: only .sql and .json files belong in ${QUERIES_DIR}/.`);
+            continue;
+        }
+        const [, name, ext] = match;
+        const full = join(dir, entry.name);
+        files.push({ path: `${QUERIES_DIR}/${entry.name}`, size: (await stat(full)).size, full });
+        const pair = byName.get(name) ?? {};
+        pair[ext] = await readFile(full, 'utf8');
+        byName.set(name, pair);
+    }
+
+    const queries = [];
+    for (const [name, pair] of [...byName].sort(([a], [b]) => a.localeCompare(b))) {
+        if (!NAME.test(name) || name.length > 64) {
+            errors.push(`${QUERIES_DIR}/${name}: query names must be 1-64 lowercase letters, digits and single dashes (e.g. "top-searches").`);
+            continue;
+        }
+        if (pair.sql === undefined) {
+            errors.push(`${QUERIES_DIR}/${name}.json has no ${name}.sql.`);
+            continue;
+        }
+        if (pair.json === undefined) {
+            errors.push(`${QUERIES_DIR}/${name}.sql has no ${name}.json (declare its parameters there, e.g. { "params": [] }).`);
+            continue;
+        }
+        let definition;
+        try {
+            definition = JSON.parse(pair.json);
+        } catch (error) {
+            errors.push(`${QUERIES_DIR}/${name}.json is not valid JSON: ${error.message}`);
+            continue;
+        }
+        const queryErrors = validateQuery(name, pair.sql, definition);
+        errors.push(...queryErrors);
+        if (!queryErrors.length) queries.push({ name, sql: pair.sql, params: definition.params ?? [] });
+    }
+    if (byName.size > MAX_QUERIES) errors.push(`${QUERIES_DIR}/: at most ${MAX_QUERIES} queries per app (found ${byName.size}).`);
+    if (!byName.size && !errors.length) errors.push(`${QUERIES_DIR}/ is empty: add <name>.sql and <name>.json, or remove the folder.`);
+
+    files.sort((a, b) => a.path.localeCompare(b.path));
+    return { files, queries, errors };
+}
+
+/**
+ * Checks one query: its SQL text and its parsed .json definition. Error messages start with the file they're about.
+ * @returns {string[]}
+ */
+export function validateQuery(name, sql, definition) {
+    const errors = [];
+    const sqlFile = `${QUERIES_DIR}/${name}.sql`;
+    const jsonFile = `${QUERIES_DIR}/${name}.json`;
+
+    const params = checkParams(definition, jsonFile, errors);
+
+    if (Buffer.byteLength(sql, 'utf8') > MAX_SQL_BYTES) {
+        errors.push(`${sqlFile} is larger than ${MAX_SQL_BYTES / 1024} KB.`);
+        return errors;
+    }
+    const code = stripLiterals(sql);
+    if (code === null) {
+        errors.push(`${sqlFile}: unterminated string, quoted identifier or comment.`);
+        return errors;
+    }
+    if (!code.trim()) {
+        errors.push(`${sqlFile} is empty.`);
+        return errors;
+    }
+    if (code.includes(';')) {
+        errors.push(`${sqlFile}: one statement only, without ";".`);
+    }
+    if (!/^(select|with)\b/i.test(code.trimStart())) {
+        errors.push(`${sqlFile}: must be a SELECT (or WITH … SELECT) statement.`);
+    }
+
+    // Macros: {{partitions(from, to)}} or {{partitions(from, to, alias)}}; the params must be declared dates.
+    const macro = /\{\{([\s\S]*?)\}\}/g;
+    for (const [whole, inner] of code.matchAll(macro)) {
+        const call = /^\s*partitions\s*\(([^()]*)\)\s*$/.exec(inner);
+        if (!call) {
+            errors.push(`${sqlFile}: unknown macro ${whole.trim()}; the only one is {{partitions(fromParam, toParam)}}.`);
+            continue;
+        }
+        const args = call[1].split(',').map((a) => a.trim());
+        if (args.length < 2 || args.length > 3 || args.some((a) => !a)) {
+            errors.push(`${sqlFile}: write {{partitions(fromParam, toParam)}} or {{partitions(fromParam, toParam, tableAlias)}}.`);
+            continue;
+        }
+        for (const arg of args.slice(0, 2)) {
+            const param = params?.find((p) => p.name === arg);
+            if (!param) errors.push(`${sqlFile}: {{partitions(…)}} uses "${arg}", which isn't a parameter in ${jsonFile}.`);
+            else if (param.type !== 'date') errors.push(`${sqlFile}: {{partitions(…)}} parameter "${arg}" must be declared "date" (it is "${param.type}").`);
+        }
+        if (args[2] !== undefined && !IDENTIFIER.test(args[2])) errors.push(`${sqlFile}: {{partitions(…)}} table alias "${args[2]}" is not a plain identifier.`);
+    }
+    const withoutMacros = code.replace(macro, ' ');
+    if (/\{\{|\}\}/.test(withoutMacros)) errors.push(`${sqlFile}: unbalanced {{ }} macro.`);
+
+    if (params) {
+        const placeholders = (withoutMacros.match(/\?/g) ?? []).length;
+        if (placeholders !== params.length) {
+            errors.push(
+                `${sqlFile} has ${placeholders} "?" placeholder${placeholders === 1 ? '' : 's'} but ${jsonFile} declares ${params.length} parameter${params.length === 1 ? '' : 's'}; they must match, in order (a string[] parameter is one "?", written as IN ?).`,
+            );
+        }
+    }
+    return errors;
+}
+
+function checkParams(definition, file, errors) {
+    if (!definition || typeof definition !== 'object' || Array.isArray(definition)) {
+        errors.push(`${file} must be an object: { "params": [ { "name": "from", "type": "date" } ] }.`);
+        return null;
+    }
+    const unknown = Object.keys(definition).filter((k) => k !== 'params');
+    if (unknown.length) errors.push(`${file}: unknown field${unknown.length === 1 ? '' : 's'} ${unknown.join(', ')} (only "params").`);
+    const params = definition.params ?? [];
+    if (!Array.isArray(params)) {
+        errors.push(`${file}: "params" must be a list.`);
+        return null;
+    }
+    const seen = new Set();
+    params.forEach((param, i) => {
+        const at = `${file} params[${i}]`;
+        if (!param || typeof param !== 'object' || Array.isArray(param)) {
+            errors.push(`${at} must be an object with "name" and "type".`);
+            return;
+        }
+        const label = typeof param.name === 'string' ? `${file} "${param.name}"` : at;
+        if (typeof param.name !== 'string' || !PARAM_NAME.test(param.name) || param.name.length > 64) {
+            errors.push(`${at}: "name" must be letters, digits and _ (starting with a letter or _).`);
+        } else if (seen.has(param.name)) {
+            errors.push(`${file}: parameter "${param.name}" is declared more than once.`);
+        } else {
+            seen.add(param.name);
+        }
+        const extra = Object.keys(param).filter((k) => !PARAM_KEYS.includes(k));
+        if (extra.length) errors.push(`${label}: unknown field${extra.length === 1 ? '' : 's'} ${extra.join(', ')} (allowed: ${PARAM_KEYS.join(', ')}).`);
+        if (!PARAM_TYPES.includes(param.type)) {
+            errors.push(`${label}: "type" must be one of ${PARAM_TYPES.join(', ')}.`);
+            return;
+        }
+        if (param.required !== undefined && typeof param.required !== 'boolean') errors.push(`${label}: "required" must be true or false.`);
+        const numeric = param.type === 'int' || param.type === 'decimal';
+        for (const key of ['min', 'max']) {
+            if (param[key] === undefined) continue;
+            if (!numeric) errors.push(`${label}: "${key}" only applies to int and decimal parameters.`);
+            else if (typeof param[key] !== 'number' || !Number.isFinite(param[key]) || (param.type === 'int' && !Number.isInteger(param[key]))) {
+                errors.push(`${label}: "${key}" must be ${param.type === 'int' ? 'an integer' : 'a number'}.`);
+            }
+        }
+        if (typeof param.min === 'number' && typeof param.max === 'number' && param.min > param.max) errors.push(`${label}: "min" is greater than "max".`);
+        if (param.maxItems !== undefined) {
+            if (param.type !== 'string[]') errors.push(`${label}: "maxItems" only applies to string[] parameters.`);
+            else if (!Number.isInteger(param.maxItems) || param.maxItems < 1 || param.maxItems > MAX_LIST_ITEMS) errors.push(`${label}: "maxItems" must be 1-${MAX_LIST_ITEMS}.`);
+        }
+        if (param.default !== undefined) {
+            const problem = checkValue(param, param.default);
+            if (problem) errors.push(`${label}: "default" ${problem}.`);
+        }
+    });
+    return params.filter((p) => p && typeof p === 'object' && typeof p.name === 'string');
+}
+
+/**
+ * Checks a value against a declared parameter. Returns a reason ("must be …") or null when it's fine.
+ */
+export function checkValue(param, value) {
+    if (value === null) return null;
+    switch (param.type) {
+        case 'string':
+            return typeof value === 'string' && value.length <= MAX_STRING_LENGTH ? null : `must be a string of up to ${MAX_STRING_LENGTH} characters`;
+        case 'int':
+        case 'decimal': {
+            if (typeof value !== 'number' || !Number.isFinite(value) || (param.type === 'int' && !Number.isInteger(value))) return `must be ${param.type === 'int' ? 'an integer' : 'a number'}`;
+            if (typeof param.min === 'number' && value < param.min) return `must be at least ${param.min}`;
+            if (typeof param.max === 'number' && value > param.max) return `must be at most ${param.max}`;
+            return null;
+        }
+        case 'date':
+            return typeof value === 'string' && DATE.test(value) && !Number.isNaN(Date.parse(value)) ? null : 'must be a date (YYYY-MM-DD)';
+        case 'timestamp':
+            return typeof value === 'string' && TIMESTAMP.test(value) && !Number.isNaN(Date.parse(value)) ? null : 'must be an ISO 8601 timestamp';
+        case 'boolean':
+            return typeof value === 'boolean' ? null : 'must be true or false';
+        case 'string[]': {
+            const max = param.maxItems ?? MAX_LIST_ITEMS;
+            if (!Array.isArray(value) || value.some((v) => typeof v !== 'string' || v.length > MAX_STRING_LENGTH)) return 'must be a list of strings';
+            return value.length <= max ? null : `must have at most ${max} items`;
+        }
+        default:
+            return 'has an unknown type';
+    }
+}
+
+/** Turns a command-line value (`--param name=value`) into the declared type: numbers, booleans, comma-separated lists. */
+export function parseParamValue(param, text) {
+    switch (param.type) {
+        case 'int':
+        case 'decimal':
+            return text.trim() === '' ? NaN : Number(text);
+        case 'boolean':
+            return text === 'true' ? true : text === 'false' ? false : text;
+        case 'string[]':
+            return text === '' ? [] : text.split(',').map((v) => v.trim());
+        default:
+            return text;
+    }
+}
+
+/**
+ * The SQL with string literals, quoted identifiers and comments blanked out (same length), so `?`, `;`, macros and
+ * the first keyword can be found without being fooled by text. Null when something is left open.
+ */
+export function stripLiterals(sql) {
+    let out = '';
+    let i = 0;
+    while (i < sql.length) {
+        const c = sql[i];
+        const next = sql[i + 1];
+        if (c === '-' && next === '-') {
+            const end = sql.indexOf('\n', i);
+            const stop = end === -1 ? sql.length : end;
+            out += ' '.repeat(stop - i);
+            i = stop;
+        } else if (c === '/' && next === '*') {
+            const end = sql.indexOf('*/', i + 2);
+            if (end === -1) return null;
+            out += ' '.repeat(end + 2 - i);
+            i = end + 2;
+        } else if (c === "'" || c === '"') {
+            // '' and "" escape the quote inside.
+            let j = i + 1;
+            for (;;) {
+                if (j >= sql.length) return null;
+                if (sql[j] === c) {
+                    if (sql[j + 1] === c) j += 2;
+                    else break;
+                } else j++;
+            }
+            out += ' '.repeat(j + 1 - i);
+            i = j + 1;
+        } else {
+            out += c;
+            i++;
+        }
+    }
+    return out;
+}

package/src/scope-check.mjs

@@ -0,0 +1,91 @@
+import { readdir, readFile, stat } from 'node:fs/promises';
+import { extname, join, relative } from 'node:path';
+
+/**
+ * Which scopes the app's code needs: the bridge (and function) calls it makes, matched in its source files. A call whose
+ * scope hawk-app.json lacks fails at run time with 403 scope_missing; `validate` and `deploy` say so first. Matching is
+ * by the call's shape (`.ai.generate(`, `.storage.put(`…), so it works whatever the app calls its bridge object, and it
+ * only warns: a false hit costs a line, a miss is no worse than today.
+ */
+const RULES = [
+    { scope: 'reports:read', pattern: /\.analytics\.report\s*\(/ },
+    { scope: 'hawksearch:read', pattern: /\.dashboard\.get\s*\(/ },
+    { scope: 'hawksearch:write', pattern: /\.dashboard\.(post|put|delete)\s*\(/ },
+    { scope: 'data:read', pattern: /\.data\.query\s*\(/ },
+    { scope: 'functions:invoke', pattern: /\.functions\.(call|start|job|wait)\s*\(/ },
+    { scope: 'email:send', pattern: /\.email\.send\s*\(/ },
+    { scope: 'hawksearch:search', pattern: /\.hawksearch\.(search|autocomplete)\s*\(/ },
+    { scope: 'hawksearch:sysparams:write', pattern: /\.hawksearch\.systemParameters\.(list|get|set)\s*\(/ },
+    { scope: 'hawksearch:features:write', pattern: /\.hawksearch\.features\.(list|set|setFacet)\s*\(/ },
+    { scope: 'hawksearch:index:items', pattern: /\.hawksearch\.index\.items\.\w+\s*\(/ },
+    { scope: 'hawksearch:index', pattern: /\.hawksearch\.index\.(rebuild|status|wait|indexes|current)\s*\(/ },
+    { scope: 'hawksearch:index:manage', pattern: /\.hawksearch\.index\.(create|setCurrent|deleteIndex|rebuildAll)\s*\(/ },
+    { scope: 'hawksearch:recommendations', pattern: /\.hawksearch\.recommendations\s*\(/ },
+    { scope: 'storage', pattern: /\.storage\.(get|put|delete|list|batch|usage)\s*\(|\.storage\.files\.\w+\s*\(/ },
+    { scope: 'lambdas:invoke', pattern: /\.lambdas\.invoke\s*\(/ },
+    { scope: 'ai:invoke', pattern: /\.ai\.(generate|stream|info)\s*\(/ },
+    { scope: 'assistant', pattern: /\.assistant\.(ask|setContext)\s*\(/ },
+];
+
+const SOURCE = new Set(['.js', '.jsx', '.ts', '.tsx', '.mjs', '.cjs', '.vue', '.svelte', '.html']);
+const SKIP = new Set(['node_modules', '.git', '.next', 'dist', 'out', 'build', 'coverage', '.turbo', '.vercel']);
+const MAX_FILES = 3000;
+const MAX_BYTES = 1024 * 1024;
+
+/** Source files of the project (not dependencies or build output), at most MAX_FILES. */
+async function sourceFiles(dir, found = []) {
+    let entries;
+    try {
+        entries = await readdir(dir, { withFileTypes: true });
+    } catch {
+        return found;
+    }
+    for (const entry of entries) {
+        if (found.length >= MAX_FILES) break;
+        if (entry.name.startsWith('.') && entry.name !== '.') continue;
+        const full = join(dir, entry.name);
+        if (entry.isDirectory()) {
+            if (!SKIP.has(entry.name)) await sourceFiles(full, found);
+        } else if (SOURCE.has(extname(entry.name))) {
+            found.push(full);
+        }
+    }
+    return found;
+}
+
+/**
+ * The scopes the code uses that `scopes` lacks: [{ scope, file, line }] (the first place each one is used), relative to
+ * `projectDir`.
+ */
+export async function missingScopes(projectDir, scopes = []) {
+    const declared = new Set(scopes);
+    const wanted = RULES.filter((rule) => !declared.has(rule.scope));
+    if (!wanted.length) return [];
+    const found = new Map();
+    for (const file of await sourceFiles(projectDir)) {
+        if (found.size === wanted.length) break;
+        let text;
+        try {
+            if ((await stat(file)).size > MAX_BYTES) continue;
+            text = await readFile(file, 'utf8');
+        } catch {
+            continue;
+        }
+        for (const rule of wanted) {
+            if (found.has(rule.scope)) continue;
+            const match = rule.pattern.exec(text);
+            if (match) {
+                const line = text.slice(0, match.index).split('\n').length;
+                found.set(rule.scope, { scope: rule.scope, file: relative(projectDir, file).split('\\').join('/'), line });
+            }
+        }
+    }
+    return [...found.values()];
+}
+
+/** The warning for what's missing (null: nothing). */
+export function describeMissingScopes(missing) {
+    if (!missing.length) return null;
+    const where = missing.map((m) => `${m.scope} (${m.file}:${m.line})`).join(', ');
+    return `The code uses ${where}, which "scopes" in hawk-app.json doesn't have: add ${missing.length === 1 ? 'it' : 'them'}, or those calls fail with 403 scope_missing.`;
+}