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

package/src/cli.mjs

@@ -1,825 +1,825 @@
-import { existsSync, readFileSync } from 'node:fs';
-import { writeFile } from 'node:fs/promises';
-import { basename, dirname, join, resolve } from 'node:path';
-import { TEMPLATES, createProject, titleCase, toSlug } from './create.mjs';
-import { addAgentFiles } from './agents.mjs';
-import { confirmVulnerabilities, deploy, npmRunBuild, submissionClearedMessage } from './deploy.mjs';
-import { buildTarget, checkBuildUrls, checkProject, describeBuildUrls } from './project-checks.mjs';
-import { loadEnv, PLATFORMS, resolveSettings } from './env.mjs';
-import { upgrade, upgradeHint } from './upgrade.mjs';
-import { login, logout, whoami } from './login.mjs';
-import { sso } from './sso.mjs';
-import { checkNewSlug, confirmTakeover } from './slug-guard.mjs';
-import { MANIFEST_FILE, loadManifest, newManifest, validateManifest } from './manifest.mjs';
-import { DEFAULT_ICON_SVG, checkIcon } from './app-icon.mjs';
-import { checkScreenshots } from './store-listing.mjs';
-import { platformClient } from './platform.mjs';
-import { dataCommand } from './data.mjs';
-import { DATA_SCOPE, QUERIES_DIR, loadQueries } from './queries.mjs';
-import { FUNCTIONS_DIR, checkBridge, describeFunctions, loadFunctions } from './functions.mjs';
-import { secretsCommand } from './secrets.mjs';
-import { configCommand } from './config.mjs';
-import { clientsCommand, pickDevClient, rememberDevClient } from './clients.mjs';
-import { DEFAULT_ALIAS, checkAlias, describeAlias, describeClientAlias } from './aliases.mjs';
-import { aliasCommand, versionsCommand, whyCommand } from './versions.mjs';
-import { describeMissingScopes, missingScopes } from './scope-check.mjs';
-import { docsCommand, doctorCommand, openCommand } from './doctor.mjs';
-import { logsCommand } from './logs.mjs';
-import { devCommand } from './dev.mjs';
-import { appChannel } from './channel.mjs';
-import { accessibilityWarnings, checkAccessibility } from './accessibility.mjs';
-import { errorsCommand, usageCommand } from './telemetry.mjs';
-
-/** The short help: what each command is for, by task. `hawk-app help <command>` shows a command's details. */
-const HELP = `hawk-app: build, run and release Hawk Apps
-
-Start
-  create <folder>         Start a new app from a template (react, preact, next, next-mui, vanilla)
-  init                    Make an existing project a Hawk App
-  sso                     Sign in with your Bridgeline account (once per machine; CI: login with a publisher key)
-  doctor                  Check everything: Node, login, hawk-app.json, project, scopes, template, MCP
-  docs [topic]            The developer docs: guides, the bridge API, every command (Bridgeline sign-in)
-
-Develop
-  dev                     Run the app locally inside a stand-in for HawkSearch, with a client's real data
-  validate                Check hawk-app.json, queries/, functions/ and the project (--build: the build too)
-  upgrade                 Bring the app up to the template this CLI ships
-
-Release
-  deploy                  Build and upload a new version, with hawk-app.json (--alias staging: off the main line;
-                          --dry-run: only show what hawk-app.json would change)
-  status                  Released or not, the newest version, the approval request, the aliases
-  versions                Every version with its status (draft, waiting, approved, rejected) and aliases
-  open                    The app in HawkSearch, to review it and submit it for approval (--alias: as its clients)
-  alias set|delete        Point an alias at a version that isn't approved, or delete one of yours
-  why <client id>         What a client's users see of the app, and why
-
-Clients
-  clients                 Who has the app: add, exclude, remove, search (also in the Hawk Analytics portal)
-  config                  The app's config values, global or per client: list, set, unset (no deploy)
-
-Data and functions
-  data                    The tables app queries can use, and running a query
-  secrets, logs           Function secrets and logs
-
-Monitor
-  errors, usage           The app's page errors, and its opens, users and clients per day
-
-Account
-  login, whoami, logout   A publisher key (for CI), and which key and platform apply here
-  templates               The templates create can use
-  mcp                     The MCP server for AI coding assistants
-
-hawk-app help <command> shows a command's details; hawk-app help all, everything.
-Options: --env dev|prod (default dev), --manifest <file>, --platform <url>.
-Docs: https://developers.hawksearchapps.com (hawk-app docs).
-`;
-
-/** Every command's details (hawk-app help <command>, hawk-app help all). */
-const DETAILS = `hawk-app: build, run and release Hawk Apps
-
-Usage:
-  hawk-app create <folder> [--template react|preact|next|next-mui|vanilla] [--name "<name>"] [--install]
-                [--channel latest|dev]
-                                                    Start a new app from a template (default: react).
-                                                    Refuses a slug that's already an app (--yes: use it anyway).
-                                                    --channel: the bridge and CLI builds it follows; default this
-                                                    CLI's own (npx @bridgeline-digital/hawk-app-cli@dev create
-                                                    makes a dev app, on the dev tag)
-  hawk-app login [--local]                          Save your publisher key once for this machine (input hidden;
-                                                    --local: this project's .env.local only)
-  hawk-app sso [--publisher <id>]                   Sign in with your Bridgeline account in the browser instead: the
-                                                    platform issues your own key (it expires; sign in again then)
-                                                    and saves it like login. Bridgeline AD accounts only.
-                                                    --publisher: the team whose apps you work on (default: services)
-  hawk-app whoami                                   Show whether you're logged in, and which key/platform apply here
-  hawk-app logout                                   Remove this machine's saved key
-  hawk-app init [--slug <slug>] [--name "<name>"] [--yes]
-                                                    Make an existing project (no template) a Hawk App: writes
-                                                    hawk-app.json and AGENTS.md (refuses a slug that's already an
-                                                    app unless --yes)
-  hawk-app templates                                List the templates create can use
-  hawk-app validate [--build [<build-folder>]]      Check hawk-app.json, queries/ and functions/ (if any) and the
-                                                    project (bridge, build script) locally. --build also builds
-                                                    the app as deploy does and checks its URLs use the base path
-  hawk-app upgrade [--yes] [--template <name>] [--no-install] [--channel latest|dev]
-                                                    Bring the app up to the template this CLI ships: the
-                                                    template's package versions (never lowered), config files
-                                                    you haven't edited, and the CLI's part of AGENTS.md (also for
-                                                    apps without a template). Shows the changes; --yes applies them.
-                                                    --channel first moves the bridge and CLI to the dev tag (dev) or
-                                                    to the released versions (latest: ^ npm's latest)
-  hawk-app deploy [<build-folder>] [--no-build] [--no-audit] [--alias <name>] [--dry-run]
-                                                    Build the app and upload it as a new version (v1, v2, …),
-                                                    with hawk-app.json. The folder comes from the template (dist,
-                                                    out, public) unless given. Runs \`npm run build\` with
-                                                    HAWK_APP_BASE_PATH=/<slug>/v<n> when package.json has a build
-                                                    script; --no-build uploads the folder as it is.
-                                                    queries/ and functions/ next to hawk-app.json are checked and
-                                                    deployed with it (functions are bundled with esbuild).
-                                                    Reports \`npm audit\` of the production dependencies to
-                                                    reviewers (never blocks; --no-audit skips it).
-                                                    Asks first when a teammate made the app's last change
-                                                    (--yes skips the question; CI only warns). --alias points
-                                                    an alias (e.g. staging) at the new version: only Bridgeline
-                                                    staff in its clients see it until it's approved.
-                                                    --dry-run shows what hawk-app.json would change, and deploys
-                                                    nothing (use it on pull requests)
-  hawk-app register                                 Send hawk-app.json without a new version (scripts; deploy
-                                                    already sends it). Changes wait for review in HawkSearch
-  hawk-app status                                   Show what is released, the newest version, the approval request,
-                                                    the aliases and the automated checks approvers will see
-  hawk-app open [--alias <name>]                    Open the app's page in HawkSearch (dev or prod): review it and
-                                                    submit it for approval there; --alias shows it as that alias's
-                                                    clients see it
-  hawk-app docs [<topic>]                           Open the developer docs (developers.hawksearchapps.com, Bridgeline
-                                                    sign-in), or a topic's page: start, concepts, versions, bridge,
-                                                    api, cli, commands, manifest, platform, data, functions, email,
-                                                    storage, ai, search, review, whats-new
-  hawk-app doctor                                   Check everything a developer needs: Node, login and platform,
-                                                    hawk-app.json, the project, scopes the code uses, the template,
-                                                    the app on the platform and the MCP config
-  hawk-app versions                                 Every version with its status (draft, waiting, approved,
-                                                    rejected) and the aliases on it
-  hawk-app alias set <name> <version>               Point an alias at a version that isn't approved (Bridgeline
-                                                    staff only); approvers do the rest. alias delete <name>
-                                                    deletes one of yours (no clients on it)
-  hawk-app why <client id>                          What a client's users see of the app, and why
-  hawk-app mcp                                      Run the MCP server for AI coding assistants (stdio; dev platform
-                                                    only). create and init add it to .mcp.json and .vscode/mcp.json
-  hawk-app dev [--client <id>] [--engine <id>] [--url <app dev URL>] [--port 3200] [--client-user] [--no-start]
-                                                    Run the app locally in a stand-in for HawkSearch, with real
-                                                    tokens and data for any client (runs \`npm run dev\` unless
-                                                    --url/--no-start; HAWKSEARCH_API_KEY adds the dashboard API).
-                                                    Without --client it asks which client and remembers it in
-                                                    .env.local (HAWK_APPS_DEV_CLIENT). Queries and functions run
-                                                    from the deployed version: deploy after changing them
-
-Clients (who has the app; also managed in the Hawk Analytics portal, not in hawk-app.json):
-  hawk-app clients                                  Show the app's visibility and its clients
-  hawk-app clients search <name or id>              Find a client's id by its name (e.g. "outdoor")
-  hawk-app clients add <id> [<id> …] [--name "<name>"] [--alias <name>]
-                                                    Give clients the app (visibility allowList). --alias: the
-                                                    version they get (an alias; default: the default one). On an
-                                                    alias whose version isn't approved, only Bridgeline staff in
-                                                    them see the app
-  hawk-app clients add --pick "<name or id>"        The same, picking the client from the matches by name
-  hawk-app clients exclude <id> [--name "<name>"]   Opt a client out (visibility all)
-  hawk-app clients remove <id>                      Remove a client from the list
-  Changes apply at once, without a deploy or approval, and are recorded in the app's history.
-
-App config (values for the keys declared in "config" in hawk-app.json; also in the Hawk Analytics portal):
-  hawk-app config list [--client <id>]              Each key: its type, default, global value and client values
-                                                    (--client: only that client's), marking invalid and undeclared ones
-  hawk-app config set <key> <value> [--client <id>] Set the global value, or one client's. The value is read as the
-                                                    key's type: emails comma-separated, json as JSON
-  hawk-app config unset <key> [--client <id>]       Clear the global value, or one client's
-  Values apply within about 30 seconds, without a deploy or approval. They are not secret: they reach the browser
-  (app.config.get / ctx.config); keep keys in secrets.
-
-Monitor:
-  hawk-app errors [--days 7]                        The app's errors in its pages (uncaught errors, rejections and
-                                                    app.reportError), grouped, the most frequent first (up to 30 days)
-  hawk-app usage [--days 30]                        Opens of the app and its views, users and clients per day (up to
-                                                    400 days; Bridgeline staff counted apart)
-
-Custom data (app queries, scope data:read):
-  hawk-app data tables [--app <slug>]               List the tables queries can use (--app: is the app
-                                                    opted in to the sensitive tables?)
-  hawk-app data describe <table>                    Show a table's columns and types
-  hawk-app data run <queries/name.sql> --client <id> [--param name=value …]
-                                                    Run a query against a client's data (dev platform only);
-                                                    string[] values are comma-separated
-
-Functions (server-side code, scope functions:invoke):
-  hawk-app secrets list                             List the app's secrets (names only, never values)
-  hawk-app secrets set <NAME> [--value-from-env <VAR>]
-                                                    Set a secret: type the value (hidden), or read it from an
-                                                    environment variable (CI). Applies to every version at once
-  hawk-app secrets delete <NAME>                    Delete a secret
-  hawk-app logs <function> [--since 1h] [--follow]  Show a function's logs (--since 15m|1h|1d|<ISO time>;
-                                                    --follow keeps polling every 2 s)
-  Background jobs: "job": true on a function (up to 900 s), started with app.functions.start. "schedules" in
-  hawk-app.json run job functions on an EventBridge cron (at most hourly) for clients where a user turns them on.
-
-Email (scope email:send, no commands): app.email.send / ctx.platform.email.send from the bridge.
-HawkSearch system parameters (scope hawksearch:sysparams:write + "systemParameters" in hawk-app.json, no commands):
-  app.hawksearch.systemParameters.list/get/set from the bridge, for the user's current engine.
-HawkSearch features (scope hawksearch:features:write, no commands): app.hawksearch.features.list/set/setFacet from the
-  bridge, HawkSearch's Feature Configuration for the user's current engine, one feature code at a time.
-HawkSearch index (scope hawksearch:index, no commands): app.hawksearch.index.rebuild/status/wait from the bridge, a full
-  rebuild of the user's engine's index from its feed, where the engine has EnableRebuildIndex on; one at a time; and
-  the Indexing API's reads (indexes, current). Item writes: scope hawksearch:index:items (app.hawksearch.index.items).
-  Creating, switching and deleting indexes, hierarchy and mappings: scope hawksearch:index:manage.
-HawkSearch recommendations (scope hawksearch:recommendations, no commands): app.hawksearch.recommendations from the
-  bridge, the engine's recommendation widgets, never tracked in the client's recommendation reports.
-Storage (scope storage, no commands): app.storage / ctx.platform.storage get, put, delete, list, batch and usage from
-  the bridge, the app's own key-value data per client (JSON values up to 350 KB, optional expiry, version checks), and
-  storage.files upload, url, download, list and delete for its files (up to 100 MB each).
-AI (scope ai:invoke, no commands): app.ai / ctx.platform.ai generate, stream and info from the bridge.
-External Lambdas (scope lambdas:invoke + "lambdas" in hawk-app.json, no commands): app.lambdas.invoke /
-  ctx.platform.lambdas.invoke from the bridge, for Lambdas Bridgeline Engineering allows on the platform.
-
-Options:
-  --manifest <file>    Manifest to use (default: hawk-app.json)
-  --env <dev|prod>     The environment to use (default: dev). hawk-app sso --env prod signs you in to prod.
-  --platform <url>     A platform URL instead of --env (e.g. a local platform)
-
-Which environment (first match wins): --env / --platform, then HAWK_APPS_ENV / HAWK_APPS_PLATFORM_URL in the
-environment (CI) or the project's .env.local / .env, else dev. Logging in never changes it, so prod is always chosen
-on purpose.
-Which key (first match wins):
-  1. Environment variable HAWK_APPS_PUBLISHER_KEY (CI secrets)
-  2. The project's .env.local / .env (git-ignored)
-  3. hawk-app login (saved once per machine in your user profile, per environment)
-
-Typical pipeline:
-  hawk-app deploy --dry-run                   (pull requests: what hawk-app.json would change)
-  hawk-app deploy                             (main branch: a new version, with hawk-app.json)
-  hawk-app deploy --alias preview-<branch>    (other branches: off the main line, Bridgeline staff only)
-
-Review: every deploy is a new version, a draft that only Bridgeline staff see. Bridgeline staff submit a version for
-approval in HawkSearch (hawk-app open), and members of the Approvers group approve or reject it (unless the app is set
-to auto-approve); a newer main-line deploy clears a waiting request. Once a version is approved and released, clients
-get it (their alias's version; default without one). Client changes (hawk-app clients or the Hawk Analytics portal) apply straight away.
-`;
-
-/**
- * The details of one command: its lines in DETAILS (the usage line and its continuation lines), plus the section of
- * its group when it has one (e.g. Clients). Null for an unknown command.
- */
-function commandHelp(name) {
-    const lines = DETAILS.split('\n');
-    const picked = [];
-    for (let i = 0; i < lines.length; i++) {
-        if (!new RegExp(`^  hawk-app ${name}(\\s|$)`).test(lines[i])) continue;
-        picked.push(lines[i]);
-        for (let j = i + 1; j < lines.length && /^ {4,}\S/.test(lines[j]); j++) picked.push(lines[j]);
-    }
-    return picked.length ? picked.join('\n') : null;
-}
-
-// clientNames: false prints client ids without their names (the MCP server, whose output goes to an AI assistant).
-/** A dev-channel app (bridge or CLI on dev builds) set to use the prod platform: its dev features may not be there yet. */
-export function devAppOnProd(projectDir, url) {
-    if (url !== PLATFORMS.prod) return null;
-    const pkgFile = join(projectDir, 'package.json');
-    const pkg = existsSync(pkgFile) ? JSON.parse(readFileSync(pkgFile, 'utf8')) : null;
-    return appChannel(pkg) === 'dev'
-        ? 'This app is on the dev channel (dev builds of the bridge or CLI) but set to use the prod platform: their features may not be on prod yet. Move it to the released versions first: npx hawk-app upgrade --channel latest --yes.'
-        : null;
-}
-
-export async function main(argv, { fetchImpl = fetch, log = console.log, runBuild, runAudit, runInstall, sleep, prompt, ask, confirm, choose, clientNames = true, env, signal, openUrl } = {}) {
-    const { command, positional, flags } = parse(argv);
-    if (['deploy', 'register', 'status', 'versions', 'alias', 'why', 'open', 'doctor', 'clients', 'data', 'secrets', 'config', 'logs', 'dev'].includes(command)) {
-        for (const warning of loadEnv().warnings) log(`! ${warning}`);
-    }
-    const manifestFile = flags.manifest ?? MANIFEST_FILE;
-    const client = () => {
-        const { url, key } = resolveSettings({ flagPlatform: flags.platform, flagEnv: flags.env });
-        return platformClient({ url, key, fetchImpl });
-    };
-    // For the slug checks of create / init, which also work without a key (they just can't check then).
-    const clientIfLoggedIn = () => {
-        const { url, key } = resolveSettings({ flagPlatform: flags.platform, flagEnv: flags.env });
-        return url && key ? platformClient({ url, key, fetchImpl }) : null;
-    };
-    // Deploys and registers say when they go to prod (only ever on purpose: see resolveSettings).
-    const notePlatform = () => {
-        const { url, urlSource } = resolveSettings({ flagPlatform: flags.platform, flagEnv: flags.env });
-        if (url === PLATFORMS.prod) log(`! Platform: prod (${url}, from ${urlSource})`);
-    };
-    const guard = { yes: !!flags.yes, log, ...(confirm ? { confirm } : {}) };
-
-    switch (command) {
-        case undefined:
-        case 'help':
-        case '--help':
-        case '-h': {
-            const topic = command === 'help' ? positional[0] : undefined;
-            if (!topic) {
-                log(HELP);
-                return 0;
-            }
-            if (topic === 'all') {
-                log(DETAILS);
-                return 0;
-            }
-            const details = commandHelp(topic);
-            if (!details) throw new Error(`No command "${topic}". \`hawk-app help\` lists them.`);
-            log(details);
-            return 0;
-        }
-
-        case 'open':
-            return openCommand({ manifestFile, flags, ...(openUrl ? { openUrl } : {}), log });
-
-        case 'doctor':
-            return doctorCommand({ manifestFile, flags, fetchImpl, log });
-
-        case 'docs':
-            return docsCommand({ topic: positional[0], ...(openUrl ? { openUrl } : {}), log });
-
-        case '--version':
-        case '-v':
-            log(JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version);
-            return 0;
-
-        case 'create': {
-            await createProject({
-                target: positional[0],
-                template: flags.template ?? 'react',
-                name: flags.name,
-                install: !!flags.install,
-                channel: flags.channel,
-                checkSlug: (slug) => checkNewSlug({ client: clientIfLoggedIn(), slug, ...guard }),
-                log,
-            });
-            return 0;
-        }
-
-        case 'login':
-            await login({ platform: flags.platform, env: flags.env, local: !!flags.local, fetchImpl, log });
-            return 0;
-
-        case 'sso':
-            await sso({ platform: flags.platform, env: flags.env, publisher: flags.publisher, fetchImpl, log, ...(openUrl ? { openUrl } : {}) });
-            return 0;
-
-        case 'whoami':
-            return whoami({ platform: flags.platform, env: flags.env, fetchImpl, log });
-
-        case 'logout':
-            return logout({ platform: flags.platform, env: flags.env, log });
-
-        case 'mcp': {
-            // Loaded only here: the MCP SDK isn't needed by any other command.
-            const { serveMcp } = await import('./mcp.mjs');
-            return serveMcp({ version: JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version });
-        }
-
-        case 'templates':
-            for (const [key, spec] of Object.entries(TEMPLATES)) log(`  ${key.padEnd(8)} ${spec.description}`);
-            return 0;
-
-        case 'init': {
-            if (existsSync(manifestFile)) throw new Error(`${manifestFile} already exists.`);
-            const slug = flags.slug ?? toSlug(packageName() ?? basename(process.cwd()));
-            await checkNewSlug({ client: clientIfLoggedIn(), slug, ...guard });
-            const manifest = newManifest({ slug, name: flags.name ?? titleCase(slug) });
-            await writeFile(manifestFile, JSON.stringify(manifest, null, 2) + '\n');
-            log(`✔ Created ${manifestFile} for "${slug}".`);
-            const iconFile = join(dirname(resolve(manifestFile)), manifest.icon);
-            if (!existsSync(iconFile)) {
-                await writeFile(iconFile, DEFAULT_ICON_SVG);
-                log(`✔ Added a default ${manifest.icon} (replace it with your app's icon: an .svg in one color, or a square .png).`);
-            }
-            await addAgentFiles(dirname(resolve(manifestFile)), { slug, name: manifest.name }, log);
-            for (const warning of (await checkProject(dirname(resolve(manifestFile)))).warnings) log(`! ${warning}`);
-            log('  Next: `npx hawk-app dev` (run it locally inside a stand-in for HawkSearch) and `npx hawk-app deploy` (a new version).');
-            log('  Versions are drafts that only Bridgeline staff see until an approver releases one (`npx hawk-app open`).');
-            log('  (First time on this machine? Run `npx hawk-app sso` once. `npx hawk-app doctor` checks the setup.)');
-            return 0;
-        }
-
-        case 'validate': {
-            const manifest = await loadManifest(manifestFile);
-            const result = validateManifest(manifest);
-            const queries = await checkQueries(manifest, manifestFile);
-            const functions = await checkFunctions(manifest, manifestFile);
-            const projectDir = dirname(resolve(manifestFile));
-            const project = await checkProject(projectDir);
-            const { url } = resolveSettings({ flagPlatform: flags.platform, flagEnv: flags.env });
-            const channelWarning = devAppOnProd(projectDir, url);
-            if (channelWarning) project.warnings.push(channelWarning);
-            // Bridge calls whose scope hawk-app.json lacks (they'd fail with 403 scope_missing).
-            const scopeWarning = describeMissingScopes(await missingScopes(projectDir, manifest.scopes));
-            if (scopeWarning) project.warnings.push(scopeWarning);
-            const icon = result.errors.length ? { errors: [], warnings: [] } : await checkIcon(projectDir, manifest.icon);
-            project.warnings.push(...icon.warnings);
-            const screenshots = result.errors.length ? { errors: [] } : await checkScreenshots(projectDir, manifest.store);
-            const { errors: buildErrors, warnings: buildWarnings } = flags.build
-                ? await checkBuild({ projectDir, manifest, folder: positional[0], runBuild, log })
-                : { errors: [], warnings: [] };
-            const ok = `✔ ${manifestFile} looks good.${queries ? ` ${QUERIES_DIR}/: ${describeQueryCount(queries.queries.length)}.` : ''}${functions ? ` ${FUNCTIONS_DIR}/: ${describeFunctions(functions.functions.length)}.` : ''}${flags.build ? ' The build\'s URLs are under its base path.' : ''}`;
-            return report(
-                { errors: [...result.errors, ...icon.errors, ...screenshots.errors, ...(queries?.errors ?? []), ...(functions?.errors ?? []), ...buildErrors], warnings: [...result.warnings, ...project.warnings, ...buildWarnings] },
-                ok,
-                log,
-            );
-        }
-
-        case 'deploy': {
-            notePlatform();
-            const manifest = await loadManifest(manifestFile);
-            const projectDir = dirname(resolve(manifestFile));
-            // A nudge when the app's dependencies are behind its template (never stops a deploy).
-            try {
-                const hint = upgradeHint(dirname(resolve(manifestFile)), manifest);
-                if (hint) log(hint);
-            } catch {
-                // An app the CLI can't match to a template: no hint.
-            }
-            const checked = validateManifest(manifest);
-            failOnErrors(checked, log);
-            for (const warning of checked.warnings) log(`! ${warning}`);
-            const icon = await checkIcon(projectDir, manifest.icon);
-            for (const warning of icon.warnings) log(`! ${warning}`);
-            if (icon.errors.length) {
-                for (const error of icon.errors) log(`✖ ${error}`);
-                throw new Error('Fix the icon first.');
-            }
-            const screenshots = await checkScreenshots(projectDir, manifest.store);
-            if (screenshots.errors.length) {
-                for (const error of screenshots.errors) log(`✖ ${error}`);
-                throw new Error('Fix the store screenshots first.');
-            }
-            const scopeWarning = describeMissingScopes(await missingScopes(dirname(resolve(manifestFile)), manifest.scopes));
-            if (scopeWarning) log(`! ${scopeWarning}`);
-            const queries = await checkQueries(manifest, manifestFile);
-            if (queries?.errors.length) {
-                for (const error of queries.errors) log(`✖ ${error}`);
-                throw new Error(`Fix ${QUERIES_DIR}/ first.`);
-            }
-            const functions = await checkFunctions(manifest, manifestFile);
-            if (functions?.errors.length) {
-                for (const error of functions.errors) log(`✖ ${error}`);
-                throw new Error(`Fix the functions first.`);
-            }
-            const alias = flags.alias === undefined ? undefined : checkAlias(flags.alias);
-            // hawk-app.json as the platform takes it ($schema and template are for local tools).
-            const { $schema: _schema, template: _template, ...settings } = manifest;
-            if (flags['dry-run']) {
-                // Pull requests: what hawk-app.json would change, without a version.
-                printRegister(await client().register(manifest.slug, settings, true), log);
-                return 0;
-            }
-            const target = buildTarget(projectDir, manifest, positional[0]);
-            if (!target) throw new Error('Which folder does the build go to? hawk-app deploy <build-folder>   (e.g. dist, out, build)');
-            await deploy({
-                client: client(),
-                alias,
-                manifest: settings,
-                registerSettings: async () => printRegisterBrief(await client().register(manifest.slug, settings, false), log),
-                beforeReserve: () => confirmTakeover({ client: client(), slug: manifest.slug, action: 'deploy', ...guard }),
-                confirmAudit: (report) => confirmVulnerabilities(report, guard),
-                slug: manifest.slug,
-                iconFile: icon.file,
-                storeFiles: screenshots.files,
-                dir: positional[0] ?? resolve(projectDir, target.folder),
-                build: target.build && !flags['no-build'],
-                serverFiles: queries?.files ?? [],
-                functions: functions?.functions ?? [],
-                projectDir,
-                audit: !flags['no-audit'],
-                ...(runBuild ? { runBuild } : {}),
-                ...(runAudit ? { runAudit } : {}),
-                fetchImpl,
-                log,
-            });
-            return 0;
-        }
-
-        case 'register': {
-            notePlatform();
-            const manifest = await loadManifest(manifestFile);
-            failOnErrors(validateManifest(manifest), log);
-            // $schema and template are for local tools (the editor, hawk-app upgrade), not the platform.
-            const { $schema, template, ...body } = manifest;
-            if (!flags['dry-run']) await confirmTakeover({ client: client(), slug: manifest.slug, action: 'register', ...guard });
-            const result = await client().register(manifest.slug, body, !!flags['dry-run']);
-            printRegister(result, log);
-            return 0;
-        }
-
-        case 'upgrade': {
-            await upgrade({ manifestFile, template: flags.template, channel: flags.channel, yes: !!flags.yes, install: !flags['no-install'], ...(runInstall ? { runInstall } : {}), log });
-            return 0;
-        }
-
-        case 'status': {
-            const manifest = await loadManifest(manifestFile);
-            const app = await client().status(manifest.slug).catch((error) => {
-                if (error.status === 404) return null;
-                throw error;
-            });
-            if (!app) {
-                log(`${manifest.slug} isn't on the platform yet: \`npm run app:dev\` or \`npm run app:deploy\` adds it.`);
-                return 0;
-            }
-            log(`${app.slug}: ${app.name}`);
-            if (app.adminLocked) log('  LOCKED      by an administrator: nobody sees it');
-            else if (app.status === 'Disabled') log('  disabled    nobody sees it');
-            // Released: the default alias, what every client without another alias gets.
-            log(`  released    ${app.status === 'Live' && app.liveVersion ? `v${app.liveVersion}  (default: every client without another alias)` : 'not yet  (only Bridgeline staff see it; an approver releases it)'}`);
-            const newest = app.pendingVersion ?? (app.status !== 'Live' ? app.currentVersion : undefined);
-            if (newest) log(`  newest      v${newest}  ${describeNewest(app)}`);
-            if (app.pending?.length) log(`  settings    waiting for review: ${app.pending.join(', ')}`);
-            const review = describeReview(app);
-            if (review) log(`  request     ${review}`);
-            const staged = (app.aliases ?? []).filter((a) => a.name !== DEFAULT_ALIAS);
-            if (staged.length) log(`  aliases     ${(app.aliases ?? []).map(describeAlias).join(' · ')}`);
-            log('  (hawk-app versions lists every version with its status; hawk-app why <client> explains what a client sees.)');
-            if (app.checks?.length) {
-                log('  checks      what approvers will see (a failed one needs a force approve):');
-                for (const c of app.checks) log(`    ${CHECK_MARKS[c.level] ?? '·'} ${c.title}: ${c.detail}`);
-            }
-            if (typeof app.autoApprove === 'boolean') log(`  auto-approve ${app.autoApprove ? 'on (new versions and changes are released without review)' : 'off'}`);
-            if (app.reviewEmails === false) log('  review emails off (approval requests, approvals and rejections aren\'t emailed; approvers change it in the Hawk Analytics portal)');
-            if (app.viewCacheMinutes === 0) log('  view cache  off (Engineering stopped it in the Hawk Analytics portal; the views\' cacheMinutes are ignored)');
-            else if (Number.isInteger(app.viewCacheMinutes)) log(`  view cache  ${app.viewCacheMinutes} min for views that declare cacheMinutes (set by Engineering in the Hawk Analytics portal)`);
-            log(`  visibility  ${app.visibility}`);
-            if (app.listed === false) log('  listed      no  (not on the Apps landing page; opens by its direct URL)');
-            if (app.store) log(`  store       ${describeStore(app.store)}`);
-            if (app.hosting) log(`  hosting     ${app.hosting}`);
-            log(`  entry URL   ${app.entryUrl}`);
-            if (app.publishedAt) log(`  published   ${app.publishedAt.slice(0, 10)} by ${app.publishedByName ?? app.publishedBy ?? 'unknown'}`);
-            log(`  scopes      ${app.scopes.join(' ') || '(none)'}`);
-            log(`  origins     ${describeOrigins(app.externalOrigins)}`);
-            if (app.systemParameters?.length) log(`  sysparams   ${app.systemParameters.join(' ')}`);
-            if (app.lambdas?.length) log(`  lambdas     ${app.lambdas.join(' ')}`);
-            const configKeys = Object.keys(app.config ?? {});
-            if (configKeys.length) log(`  config      ${configKeys.join(' ')}`);
-            const schedules = Object.entries(app.schedules ?? {});
-            if (schedules.length) {
-                log(`  schedules   ${schedules.length}  (each runs only for clients where a user turns it on in the app)`);
-                for (const [name, s] of schedules) log(`    ${name}  ${s.function}  "${s.cron}"  ${s.timezone ?? 'UTC'}`);
-            }
-            log(`  clients     ${app.clients.length}`);
-            for (const c of app.clients) {
-                const alias = c.alias ? (app.aliases ?? []).find((a) => a.name === c.alias) : undefined;
-                log(`    ${c.enabled ? '+' : '-'} ${c.id}${c.name && clientNames ? ` (${c.name})` : ''}${describeClientAlias({ alias: c.alias, aliasStatus: alias?.status })}`);
-            }
-            return 0;
-        }
-
-        case 'dev': {
-            const manifest = await loadManifest(manifestFile);
-            const projectDir = dirname(resolve(manifestFile));
-            if (!flags.client && !(env ?? process.env).HAWK_APPS_DEV_CLIENT) {
-                // No client yet: ask which one (by name), and remember it in .env.local for next time.
-                const id = await pickDevClient({ client, slug: manifest.slug, ...(choose ? { choose } : {}), ...(ask ? { ask } : {}), log });
-                await rememberDevClient(projectDir, id);
-                log(`✔ Using client ${id} (saved as HAWK_APPS_DEV_CLIENT in .env.local; --client <id> uses another).`);
-                flags.client = id;
-            }
-            // A new app isn't on the platform yet: register it (a draft, so only Bridgeline staff see it) to run it.
-            const known = await client().status(manifest.slug).then(() => true, (error) => (error.status === 404 ? false : true));
-            if (!known) {
-                const { $schema: _schema, template: _template, ...settings } = manifest;
-                await client().register(manifest.slug, settings, false);
-                log(`✔ Registered ${manifest.slug} on the platform (not released: only Bridgeline staff see it).`);
-            }
-            return devCommand({ client: client(), manifest, flags, projectDir, ...(env ? { env } : {}), signal, log });
-        }
-
-        case 'data':
-            return dataCommand({ client, sub: positional[0], args: positional.slice(1), flags, ...(sleep ? { sleep } : {}), log });
-
-        case 'secrets': {
-            const manifest = await loadManifest(manifestFile);
-            return secretsCommand({ client, manifest, sub: positional[0], args: positional.slice(1), flags, ...(prompt ? { prompt } : {}), ...(env ? { env } : {}), log });
-        }
-
-        case 'config': {
-            const manifest = await loadManifest(manifestFile);
-            return configCommand({ client, manifest, sub: positional[0], args: positional.slice(1), flags, log });
-        }
-
-        case 'clients': {
-            // search reads the environment's client list: no app needed.
-            if (positional[0] === 'search') return clientsCommand({ client, sub: 'search', args: positional.slice(1), log });
-            const manifest = await loadManifest(manifestFile);
-            return clientsCommand({ client, manifest, sub: positional[0], args: positional.slice(1), flags, names: clientNames, ...(choose ? { choose } : {}), log });
-        }
-
-        case 'versions':
-            return versionsCommand({ client: client(), manifest: await loadManifest(manifestFile), log });
-
-        case 'alias':
-            return aliasCommand({ client: client(), manifest: await loadManifest(manifestFile), sub: positional[0], args: positional.slice(1), log });
-
-        case 'why':
-            return whyCommand({ client: client(), manifest: await loadManifest(manifestFile), clientId: positional[0], log });
-
-        case 'errors': {
-            return errorsCommand({ client: client(), manifest: await loadManifest(manifestFile), flags, log });
-        }
-
-        case 'usage': {
-            return usageCommand({ client: client(), manifest: await loadManifest(manifestFile), flags, log });
-        }
-
-        case 'logs': {
-            const manifest = await loadManifest(manifestFile);
-            const controller = new AbortController();
-            const stop = () => controller.abort();
-            signal?.addEventListener('abort', stop, { once: true });
-            if (flags.follow) process.once('SIGINT', stop);
-            try {
-                return await logsCommand({ client, manifest, name: positional[0], flags, ...(sleep ? { sleep } : {}), signal: controller.signal, log });
-            } finally {
-                process.off('SIGINT', stop);
-                signal?.removeEventListener('abort', stop);
-            }
-        }
-
-        default:
-            log(HELP);
-            throw new Error(`Unknown command "${command}".`);
-    }
-}
-
-/** What `hawk-app deploy` says about the hawk-app.json it sent first (the full summary is `hawk-app register`'s). */
-function printRegisterBrief(result, log) {
-    log(`✔ hawk-app.json sent${result.pending?.length ? `: ${result.pending.join(', ')} waiting for review` : ''}`);
-    for (const warning of result.warnings ?? []) log(`  ! ${warning}`);
-    if (result.submissionCleared) log(`  ! ${submissionClearedMessage('settings')}`);
-}
-
-function printRegister(result, log) {
-    log(`${result.dryRun ? 'Dry run, nothing was changed:' : '✔ Sent hawk-app.json for'} ${result.slug}`);
-    log(`  status      ${result.status}${result.adminLocked ? '  (LOCKED by an administrator: hidden from everyone)' : ''}`);
-    log(`  visibility  ${result.visibility}`);
-    if (result.hosting) log(`  hosting     ${result.hosting}`);
-    log(`  entry URL   ${result.entryUrl}`);
-    log(`  scopes      ${result.scopes.join(' ') || '(none)'}`);
-    if (result.pending?.length) {
-        log(`  settings    waiting for review: ${result.pending.join(', ')}`);
-        log('    (approvers approve them in HawkSearch, with the next version)');
-    }
-    if (typeof result.autoApprove === 'boolean') log(`  auto-approve ${result.autoApprove ? 'on (changes are released without review)' : 'off'}`);
-    if (result.externalOrigins) {
-        const o = result.externalOrigins;
-        log(`  origins     ${describeOrigins(o.current)}${o.restamped ? `  (applied to ${o.restamped} deployed page${o.restamped === 1 ? '' : 's'})` : ''}`);
-        for (const origin of o.added) log(`    + ${origin}  (added)`);
-        for (const origin of o.removed) log(`    - ${origin}  (removed)`);
-    }
-    log('  clients     manage with `hawk-app clients` or in the Hawk Analytics portal');
-    for (const warning of result.warnings ?? []) log(`  ! ${warning}`);
-    if (result.submissionCleared && !result.dryRun) log(`  ! ${submissionClearedMessage('settings')}`);
-}
-
-const CHECK_MARKS = { pass: '✔', fail: '✖', info: 'i' };
-
-/** The newest version's status, from the approval request: waiting, rejected, or a draft. */
-function describeNewest({ reviewState }) {
-    if (reviewState === 'waiting_for_approval') return 'waiting for approval';
-    if (reviewState === 'rejected') return 'rejected (see request)';
-    return "draft: only Bridgeline staff see it until it's approved";
-}
-
-const day = (iso) => (typeof iso === 'string' ? iso.slice(0, 10) : 'unknown date');
-const person = (user) => user?.name ?? user?.email ?? 'unknown';
-
-/**
- * The app's place in the approval workflow (null when the platform doesn't say):
- * "waiting for approval (submitted by Jane Doe, 2026-10-08: <note>)", "rejected by Jane Doe on 2026-10-08: <reason>".
- */
-export function describeReview({ reviewState, submission, lastDecision }) {
-    switch (reviewState) {
-        case 'waiting_for_approval': {
-            if (!submission) return 'waiting for approval';
-            const note = submission.note ? `: ${submission.note}` : '';
-            return `waiting for approval (submitted by ${person(submission.submittedBy)}, ${day(submission.submittedAt)}${note})`;
-        }
-        case 'rejected': {
-            if (!lastDecision) return 'rejected';
-            return `rejected by ${person(lastDecision.by)} on ${day(lastDecision.at)}${lastDecision.reason ? `: ${lastDecision.reason}` : ''}`;
-        }
-        case 'pending':
-            return 'not submitted yet (Bridgeline staff submit it for approval in HawkSearch)';
-        case 'draft':
-            return 'draft (Bridgeline staff submit it for approval in HawkSearch)';
-        case 'live':
-            return 'nothing waiting for approval';
-        default:
-            return null;
-    }
-}
-
-/** What the app may load from and call, as the CDN's CSP will allow it. */
-/** A store app's line in `status`: "in the store, $99/month; requests 2 open, 5 approved, 1 declined". */
-function describeStore(store) {
-    const where = store.offered
-        ? 'in the store'
-        : store.listed === false
-          ? 'out of the store (a Hawk-App-Manager took it out)'
-          : 'not in the store yet (clients see it once it\'s released)';
-    const price = store.price ? `, ${store.price}` : '';
-    return `${where}${price}; requests ${store.openRequests} open, ${store.approvedRequests} approved, ${store.declinedRequests} declined`;
-}
-
-function describeOrigins(origins) {
-    if (!origins) return 'any https origin';
-    if (origins.length === 1 && origins[0] === '*') return 'any https origin (*)';
-    return origins.length ? origins.join(' ') : 'none (own files and the platform only)';
-}
-
-/**
- * Checks queries/ next to the manifest (not in the build folder). Null when the app has none. Queries need the
- * data:read scope.
- */
-async function checkQueries(manifest, manifestFile) {
-    const result = await loadQueries(dirname(resolve(manifestFile)));
-    if (!result) return null;
-    if (!(manifest.scopes ?? []).includes(DATA_SCOPE)) {
-        result.errors.unshift(`${QUERIES_DIR}/ needs the "${DATA_SCOPE}" scope: add it to "scopes" in hawk-app.json (or remove ${QUERIES_DIR}/).`);
-    }
-    return result;
-}
-
-/**
- * Checks functions/ next to the manifest against its "functions" block. Null when the app has neither. Also checks
- * that the app has a bridge with the /server entry, which the bundles are built with.
- */
-async function checkFunctions(manifest, manifestFile) {
-    const projectDir = dirname(resolve(manifestFile));
-    const result = await loadFunctions(projectDir, manifest);
-    if (!result) return null;
-    if (result.functions.length) {
-        const problem = checkBridge(projectDir);
-        if (problem) result.errors.push(problem);
-    }
-    return result;
-}
-
-/**
- * `validate --build [<folder>]`: builds the app as deploy would (with a stand-in base path, /<slug>/v0) and checks
- * that its HTML only loads URLs under it. The folder comes from the argument or the app:deploy script.
- */
-async function checkBuild({ projectDir, manifest, folder, runBuild = npmRunBuild, log }) {
-    const found = buildTarget(projectDir, manifest, folder);
-    if (!found) return { errors: ['--build needs the build folder: hawk-app validate --build <folder> (e.g. dist, out).'], warnings: [] };
-    const target = found.folder;
-    const basePath = `/${manifest.slug}/v0`;
-    if (found.build) {
-        log(`Building with HAWK_APP_BASE_PATH=${basePath}…`);
-        await runBuild({ basePath, cwd: projectDir });
-    }
-    const dir = resolve(projectDir, target);
-    if (!existsSync(dir)) return { errors: [`The build folder "${target}" doesn't exist.`], warnings: [] };
-    const outside = await checkBuildUrls(dir, basePath);
-    // The accessibility check approvers will see (critical and serious issues).
-    const warnings = accessibilityWarnings(await checkAccessibility(dir));
-    return { errors: outside.length ? [describeBuildUrls(outside, basePath)] : [], warnings };
-}
-
-
-function describeQueryCount(count) {
-    return `${count} quer${count === 1 ? 'y' : 'ies'}`;
-}
-
-function report({ errors, warnings }, ok, log) {
-    for (const warning of warnings) log(`! ${warning}`);
-    if (errors.length) {
-        for (const error of errors) log(`✖ ${error}`);
-        return 1;
-    }
-    log(ok);
-    return 0;
-}
-
-function failOnErrors(result, log) {
-    if (result.errors.length) {
-        report(result, '', log);
-        throw new Error('Fix hawk-app.json first.');
-    }
-}
-
-export function parse(argv) {
-    const flags = {};
-    const positional = [];
-    let command;
-    for (let i = 0; i < argv.length; i++) {
-        const arg = argv[i];
-        if (arg.startsWith('--') && arg.length > 2 && command !== undefined) {
-            const eq = arg.indexOf('=');
-            const name = eq === -1 ? arg.slice(2) : arg.slice(2, eq);
-            const inline = eq === -1 ? undefined : arg.slice(eq + 1);
-            if (name === 'param') {
-                // Repeatable, and the value keeps its own "=": --param from=2026-09-01 --param to=2026-09-30
-                flags.param = [...(flags.param ?? []), inline ?? argv[++i]];
-                continue;
-            }
-            const takesValue = ['manifest', 'platform', 'slug', 'name', 'template', 'client', 'app', 'since', 'value-from-env', 'engine', 'url', 'port', 'env', 'publisher', 'pick', 'channel', 'days', 'alias'].includes(name);
-            flags[name] = takesValue ? inline ?? argv[++i] : true;
-        } else if (command === undefined) {
-            command = arg;
-        } else {
-            positional.push(arg);
-        }
-    }
-    return { command, positional, flags };
-}
-
-function packageName() {
-    try {
-        return JSON.parse(readFileSync('package.json', 'utf8')).name?.replace(/^@[^/]+\//, '');
-    } catch {
-        return undefined;
-    }
-}
-
-
+import { existsSync, readFileSync } from 'node:fs';
+import { writeFile } from 'node:fs/promises';
+import { basename, dirname, join, resolve } from 'node:path';
+import { TEMPLATES, createProject, titleCase, toSlug } from './create.mjs';
+import { addAgentFiles } from './agents.mjs';
+import { confirmVulnerabilities, deploy, npmRunBuild, submissionClearedMessage } from './deploy.mjs';
+import { buildTarget, checkBuildUrls, checkProject, describeBuildUrls } from './project-checks.mjs';
+import { loadEnv, PLATFORMS, resolveSettings } from './env.mjs';
+import { upgrade, upgradeHint } from './upgrade.mjs';
+import { login, logout, whoami } from './login.mjs';
+import { sso } from './sso.mjs';
+import { checkNewSlug, confirmTakeover } from './slug-guard.mjs';
+import { MANIFEST_FILE, loadManifest, newManifest, validateManifest } from './manifest.mjs';
+import { DEFAULT_ICON_SVG, checkIcon } from './app-icon.mjs';
+import { checkScreenshots } from './store-listing.mjs';
+import { platformClient } from './platform.mjs';
+import { dataCommand } from './data.mjs';
+import { DATA_SCOPE, QUERIES_DIR, loadQueries } from './queries.mjs';
+import { FUNCTIONS_DIR, checkBridge, describeFunctions, loadFunctions } from './functions.mjs';
+import { secretsCommand } from './secrets.mjs';
+import { configCommand } from './config.mjs';
+import { clientsCommand, pickDevClient, rememberDevClient } from './clients.mjs';
+import { DEFAULT_ALIAS, checkAlias, describeAlias, describeClientAlias } from './aliases.mjs';
+import { aliasCommand, versionsCommand, whyCommand } from './versions.mjs';
+import { describeMissingScopes, missingScopes } from './scope-check.mjs';
+import { docsCommand, doctorCommand, openCommand } from './doctor.mjs';
+import { logsCommand } from './logs.mjs';
+import { devCommand } from './dev.mjs';
+import { appChannel } from './channel.mjs';
+import { accessibilityWarnings, checkAccessibility } from './accessibility.mjs';
+import { errorsCommand, usageCommand } from './telemetry.mjs';
+
+/** The short help: what each command is for, by task. `hawk-app help <command>` shows a command's details. */
+const HELP = `hawk-app: build, run and release Hawk Apps
+
+Start
+  create <folder>         Start a new app from a template (react, preact, next, next-mui, vanilla)
+  init                    Make an existing project a Hawk App
+  sso                     Sign in with your Bridgeline account (once per machine; CI: login with a publisher key)
+  doctor                  Check everything: Node, login, hawk-app.json, project, scopes, template, MCP
+  docs [topic]            The developer docs: guides, the bridge API, every command (Bridgeline sign-in)
+
+Develop
+  dev                     Run the app locally inside a stand-in for HawkSearch, with a client's real data
+  validate                Check hawk-app.json, queries/, functions/ and the project (--build: the build too)
+  upgrade                 Bring the app up to the template this CLI ships
+
+Release
+  deploy                  Build and upload a new version, with hawk-app.json (--alias staging: off the main line;
+                          --dry-run: only show what hawk-app.json would change)
+  status                  Released or not, the newest version, the approval request, the aliases
+  versions                Every version with its status (draft, waiting, approved, rejected) and aliases
+  open                    The app in HawkSearch, to review it and submit it for approval (--alias: as its clients)
+  alias set|delete        Point an alias at a version that isn't approved, or delete one of yours
+  why <client id>         What a client's users see of the app, and why
+
+Clients
+  clients                 Who has the app: add, exclude, remove, search (also in the Hawk Analytics portal)
+  config                  The app's config values, global or per client: list, set, unset (no deploy)
+
+Data and functions
+  data                    The tables app queries can use, and running a query
+  secrets, logs           Function secrets and logs
+
+Monitor
+  errors, usage           The app's page errors, and its opens, users and clients per day
+
+Account
+  login, whoami, logout   A publisher key (for CI), and which key and platform apply here
+  templates               The templates create can use
+  mcp                     The MCP server for AI coding assistants
+
+hawk-app help <command> shows a command's details; hawk-app help all, everything.
+Options: --env dev|prod (default dev), --manifest <file>, --platform <url>.
+Docs: https://developers.hawksearchapps.com (hawk-app docs).
+`;
+
+/** Every command's details (hawk-app help <command>, hawk-app help all). */
+const DETAILS = `hawk-app: build, run and release Hawk Apps
+
+Usage:
+  hawk-app create <folder> [--template react|preact|next|next-mui|vanilla] [--name "<name>"] [--install]
+                [--channel latest|dev]
+                                                    Start a new app from a template (default: react).
+                                                    Refuses a slug that's already an app (--yes: use it anyway).
+                                                    --channel: the bridge and CLI builds it follows; default this
+                                                    CLI's own (npx @bridgeline-digital/hawk-app-cli@dev create
+                                                    makes a dev app, on the dev tag)
+  hawk-app login [--local]                          Save your publisher key once for this machine (input hidden;
+                                                    --local: this project's .env.local only)
+  hawk-app sso [--publisher <id>]                   Sign in with your Bridgeline account in the browser instead: the
+                                                    platform issues your own key (it expires; sign in again then)
+                                                    and saves it like login. Bridgeline AD accounts only.
+                                                    --publisher: the team whose apps you work on (default: services)
+  hawk-app whoami                                   Show whether you're logged in, and which key/platform apply here
+  hawk-app logout                                   Remove this machine's saved key
+  hawk-app init [--slug <slug>] [--name "<name>"] [--yes]
+                                                    Make an existing project (no template) a Hawk App: writes
+                                                    hawk-app.json and AGENTS.md (refuses a slug that's already an
+                                                    app unless --yes)
+  hawk-app templates                                List the templates create can use
+  hawk-app validate [--build [<build-folder>]]      Check hawk-app.json, queries/ and functions/ (if any) and the
+                                                    project (bridge, build script) locally. --build also builds
+                                                    the app as deploy does and checks its URLs use the base path
+  hawk-app upgrade [--yes] [--template <name>] [--no-install] [--channel latest|dev]
+                                                    Bring the app up to the template this CLI ships: the
+                                                    template's package versions (never lowered), config files
+                                                    you haven't edited, and the CLI's part of AGENTS.md (also for
+                                                    apps without a template). Shows the changes; --yes applies them.
+                                                    --channel first moves the bridge and CLI to the dev tag (dev) or
+                                                    to the released versions (latest: ^ npm's latest)
+  hawk-app deploy [<build-folder>] [--no-build] [--no-audit] [--alias <name>] [--dry-run]
+                                                    Build the app and upload it as a new version (v1, v2, …),
+                                                    with hawk-app.json. The folder comes from the template (dist,
+                                                    out, public) unless given. Runs \`npm run build\` with
+                                                    HAWK_APP_BASE_PATH=/<slug>/v<n> when package.json has a build
+                                                    script; --no-build uploads the folder as it is.
+                                                    queries/ and functions/ next to hawk-app.json are checked and
+                                                    deployed with it (functions are bundled with esbuild).
+                                                    Reports \`npm audit\` of the production dependencies to
+                                                    reviewers (never blocks; --no-audit skips it).
+                                                    Asks first when a teammate made the app's last change
+                                                    (--yes skips the question; CI only warns). --alias points
+                                                    an alias (e.g. staging) at the new version: only Bridgeline
+                                                    staff in its clients see it until it's approved.
+                                                    --dry-run shows what hawk-app.json would change, and deploys
+                                                    nothing (use it on pull requests)
+  hawk-app register                                 Send hawk-app.json without a new version (scripts; deploy
+                                                    already sends it). Changes wait for review in HawkSearch
+  hawk-app status                                   Show what is released, the newest version, the approval request,
+                                                    the aliases and the automated checks approvers will see
+  hawk-app open [--alias <name>]                    Open the app's page in HawkSearch (dev or prod): review it and
+                                                    submit it for approval there; --alias shows it as that alias's
+                                                    clients see it
+  hawk-app docs [<topic>]                           Open the developer docs (developers.hawksearchapps.com, Bridgeline
+                                                    sign-in), or a topic's page: start, concepts, versions, bridge,
+                                                    api, cli, commands, manifest, platform, data, functions, email,
+                                                    storage, ai, search, review, whats-new
+  hawk-app doctor                                   Check everything a developer needs: Node, login and platform,
+                                                    hawk-app.json, the project, scopes the code uses, the template,
+                                                    the app on the platform and the MCP config
+  hawk-app versions                                 Every version with its status (draft, waiting, approved,
+                                                    rejected) and the aliases on it
+  hawk-app alias set <name> <version>               Point an alias at a version that isn't approved (Bridgeline
+                                                    staff only); approvers do the rest. alias delete <name>
+                                                    deletes one of yours (no clients on it)
+  hawk-app why <client id>                          What a client's users see of the app, and why
+  hawk-app mcp                                      Run the MCP server for AI coding assistants (stdio; dev platform
+                                                    only). create and init add it to .mcp.json and .vscode/mcp.json
+  hawk-app dev [--client <id>] [--engine <id>] [--url <app dev URL>] [--port 3200] [--client-user] [--no-start]
+                                                    Run the app locally in a stand-in for HawkSearch, with real
+                                                    tokens and data for any client (runs \`npm run dev\` unless
+                                                    --url/--no-start; HAWKSEARCH_API_KEY adds the dashboard API).
+                                                    Without --client it asks which client and remembers it in
+                                                    .env.local (HAWK_APPS_DEV_CLIENT). Queries and functions run
+                                                    from the deployed version: deploy after changing them
+
+Clients (who has the app; also managed in the Hawk Analytics portal, not in hawk-app.json):
+  hawk-app clients                                  Show the app's visibility and its clients
+  hawk-app clients search <name or id>              Find a client's id by its name (e.g. "outdoor")
+  hawk-app clients add <id> [<id> …] [--name "<name>"] [--alias <name>]
+                                                    Give clients the app (visibility allowList). --alias: the
+                                                    version they get (an alias; default: the default one). On an
+                                                    alias whose version isn't approved, only Bridgeline staff in
+                                                    them see the app
+  hawk-app clients add --pick "<name or id>"        The same, picking the client from the matches by name
+  hawk-app clients exclude <id> [--name "<name>"]   Opt a client out (visibility all)
+  hawk-app clients remove <id>                      Remove a client from the list
+  Changes apply at once, without a deploy or approval, and are recorded in the app's history.
+
+App config (values for the keys declared in "config" in hawk-app.json; also in the Hawk Analytics portal):
+  hawk-app config list [--client <id>]              Each key: its type, default, global value and client values
+                                                    (--client: only that client's), marking invalid and undeclared ones
+  hawk-app config set <key> <value> [--client <id>] Set the global value, or one client's. The value is read as the
+                                                    key's type: emails comma-separated, json as JSON
+  hawk-app config unset <key> [--client <id>]       Clear the global value, or one client's
+  Values apply within about 30 seconds, without a deploy or approval. They are not secret: they reach the browser
+  (app.config.get / ctx.config); keep keys in secrets.
+
+Monitor:
+  hawk-app errors [--days 7]                        The app's errors in its pages (uncaught errors, rejections and
+                                                    app.reportError), grouped, the most frequent first (up to 30 days)
+  hawk-app usage [--days 30]                        Opens of the app and its views, users and clients per day (up to
+                                                    400 days; Bridgeline staff counted apart)
+
+Custom data (app queries, scope data:read):
+  hawk-app data tables [--app <slug>]               List the tables queries can use (--app: is the app
+                                                    opted in to the sensitive tables?)
+  hawk-app data describe <table>                    Show a table's columns and types
+  hawk-app data run <queries/name.sql> --client <id> [--param name=value …]
+                                                    Run a query against a client's data (dev platform only);
+                                                    string[] values are comma-separated
+
+Functions (server-side code, scope functions:invoke):
+  hawk-app secrets list                             List the app's secrets (names only, never values)
+  hawk-app secrets set <NAME> [--value-from-env <VAR>]
+                                                    Set a secret: type the value (hidden), or read it from an
+                                                    environment variable (CI). Applies to every version at once
+  hawk-app secrets delete <NAME>                    Delete a secret
+  hawk-app logs <function> [--since 1h] [--follow]  Show a function's logs (--since 15m|1h|1d|<ISO time>;
+                                                    --follow keeps polling every 2 s)
+  Background jobs: "job": true on a function (up to 900 s), started with app.functions.start. "schedules" in
+  hawk-app.json run job functions on an EventBridge cron (at most hourly) for clients where a user turns them on.
+
+Email (scope email:send, no commands): app.email.send / ctx.platform.email.send from the bridge.
+HawkSearch system parameters (scope hawksearch:sysparams:write + "systemParameters" in hawk-app.json, no commands):
+  app.hawksearch.systemParameters.list/get/set from the bridge, for the user's current engine.
+HawkSearch features (scope hawksearch:features:write, no commands): app.hawksearch.features.list/set/setFacet from the
+  bridge, HawkSearch's Feature Configuration for the user's current engine, one feature code at a time.
+HawkSearch index (scope hawksearch:index, no commands): app.hawksearch.index.rebuild/status/wait from the bridge, a full
+  rebuild of the user's engine's index from its feed, where the engine has EnableRebuildIndex on; one at a time; and
+  the Indexing API's reads (indexes, current). Item writes: scope hawksearch:index:items (app.hawksearch.index.items).
+  Creating, switching and deleting indexes, hierarchy and mappings: scope hawksearch:index:manage.
+HawkSearch recommendations (scope hawksearch:recommendations, no commands): app.hawksearch.recommendations from the
+  bridge, the engine's recommendation widgets, never tracked in the client's recommendation reports.
+Storage (scope storage, no commands): app.storage / ctx.platform.storage get, put, delete, list, batch and usage from
+  the bridge, the app's own key-value data per client (JSON values up to 350 KB, optional expiry, version checks), and
+  storage.files upload, url, download, list and delete for its files (up to 100 MB each).
+AI (scope ai:invoke, no commands): app.ai / ctx.platform.ai generate, stream and info from the bridge.
+External Lambdas (scope lambdas:invoke + "lambdas" in hawk-app.json, no commands): app.lambdas.invoke /
+  ctx.platform.lambdas.invoke from the bridge, for Lambdas Bridgeline Engineering allows on the platform.
+
+Options:
+  --manifest <file>    Manifest to use (default: hawk-app.json)
+  --env <dev|prod>     The environment to use (default: dev). hawk-app sso --env prod signs you in to prod.
+  --platform <url>     A platform URL instead of --env (e.g. a local platform)
+
+Which environment (first match wins): --env / --platform, then HAWK_APPS_ENV / HAWK_APPS_PLATFORM_URL in the
+environment (CI) or the project's .env.local / .env, else dev. Logging in never changes it, so prod is always chosen
+on purpose.
+Which key (first match wins):
+  1. Environment variable HAWK_APPS_PUBLISHER_KEY (CI secrets)
+  2. The project's .env.local / .env (git-ignored)
+  3. hawk-app login (saved once per machine in your user profile, per environment)
+
+Typical pipeline:
+  hawk-app deploy --dry-run                   (pull requests: what hawk-app.json would change)
+  hawk-app deploy                             (main branch: a new version, with hawk-app.json)
+  hawk-app deploy --alias preview-<branch>    (other branches: off the main line, Bridgeline staff only)
+
+Review: every deploy is a new version, a draft that only Bridgeline staff see. Bridgeline staff submit a version for
+approval in HawkSearch (hawk-app open), and members of the Approvers group approve or reject it (unless the app is set
+to auto-approve); a newer main-line deploy clears a waiting request. Once a version is approved and released, clients
+get it (their alias's version; default without one). Client changes (hawk-app clients or the Hawk Analytics portal) apply straight away.
+`;
+
+/**
+ * The details of one command: its lines in DETAILS (the usage line and its continuation lines), plus the section of
+ * its group when it has one (e.g. Clients). Null for an unknown command.
+ */
+function commandHelp(name) {
+    const lines = DETAILS.split('\n');
+    const picked = [];
+    for (let i = 0; i < lines.length; i++) {
+        if (!new RegExp(`^  hawk-app ${name}(\\s|$)`).test(lines[i])) continue;
+        picked.push(lines[i]);
+        for (let j = i + 1; j < lines.length && /^ {4,}\S/.test(lines[j]); j++) picked.push(lines[j]);
+    }
+    return picked.length ? picked.join('\n') : null;
+}
+
+// clientNames: false prints client ids without their names (the MCP server, whose output goes to an AI assistant).
+/** A dev-channel app (bridge or CLI on dev builds) set to use the prod platform: its dev features may not be there yet. */
+export function devAppOnProd(projectDir, url) {
+    if (url !== PLATFORMS.prod) return null;
+    const pkgFile = join(projectDir, 'package.json');
+    const pkg = existsSync(pkgFile) ? JSON.parse(readFileSync(pkgFile, 'utf8')) : null;
+    return appChannel(pkg) === 'dev'
+        ? 'This app is on the dev channel (dev builds of the bridge or CLI) but set to use the prod platform: their features may not be on prod yet. Move it to the released versions first: npx hawk-app upgrade --channel latest --yes.'
+        : null;
+}
+
+export async function main(argv, { fetchImpl = fetch, log = console.log, runBuild, runAudit, runInstall, sleep, prompt, ask, confirm, choose, clientNames = true, env, signal, openUrl } = {}) {
+    const { command, positional, flags } = parse(argv);
+    if (['deploy', 'register', 'status', 'versions', 'alias', 'why', 'open', 'doctor', 'clients', 'data', 'secrets', 'config', 'logs', 'dev'].includes(command)) {
+        for (const warning of loadEnv().warnings) log(`! ${warning}`);
+    }
+    const manifestFile = flags.manifest ?? MANIFEST_FILE;
+    const client = () => {
+        const { url, key } = resolveSettings({ flagPlatform: flags.platform, flagEnv: flags.env });
+        return platformClient({ url, key, fetchImpl });
+    };
+    // For the slug checks of create / init, which also work without a key (they just can't check then).
+    const clientIfLoggedIn = () => {
+        const { url, key } = resolveSettings({ flagPlatform: flags.platform, flagEnv: flags.env });
+        return url && key ? platformClient({ url, key, fetchImpl }) : null;
+    };
+    // Deploys and registers say when they go to prod (only ever on purpose: see resolveSettings).
+    const notePlatform = () => {
+        const { url, urlSource } = resolveSettings({ flagPlatform: flags.platform, flagEnv: flags.env });
+        if (url === PLATFORMS.prod) log(`! Platform: prod (${url}, from ${urlSource})`);
+    };
+    const guard = { yes: !!flags.yes, log, ...(confirm ? { confirm } : {}) };
+
+    switch (command) {
+        case undefined:
+        case 'help':
+        case '--help':
+        case '-h': {
+            const topic = command === 'help' ? positional[0] : undefined;
+            if (!topic) {
+                log(HELP);
+                return 0;
+            }
+            if (topic === 'all') {
+                log(DETAILS);
+                return 0;
+            }
+            const details = commandHelp(topic);
+            if (!details) throw new Error(`No command "${topic}". \`hawk-app help\` lists them.`);
+            log(details);
+            return 0;
+        }
+
+        case 'open':
+            return openCommand({ manifestFile, flags, ...(openUrl ? { openUrl } : {}), log });
+
+        case 'doctor':
+            return doctorCommand({ manifestFile, flags, fetchImpl, log });
+
+        case 'docs':
+            return docsCommand({ topic: positional[0], ...(openUrl ? { openUrl } : {}), log });
+
+        case '--version':
+        case '-v':
+            log(JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version);
+            return 0;
+
+        case 'create': {
+            await createProject({
+                target: positional[0],
+                template: flags.template ?? 'react',
+                name: flags.name,
+                install: !!flags.install,
+                channel: flags.channel,
+                checkSlug: (slug) => checkNewSlug({ client: clientIfLoggedIn(), slug, ...guard }),
+                log,
+            });
+            return 0;
+        }
+
+        case 'login':
+            await login({ platform: flags.platform, env: flags.env, local: !!flags.local, fetchImpl, log });
+            return 0;
+
+        case 'sso':
+            await sso({ platform: flags.platform, env: flags.env, publisher: flags.publisher, fetchImpl, log, ...(openUrl ? { openUrl } : {}) });
+            return 0;
+
+        case 'whoami':
+            return whoami({ platform: flags.platform, env: flags.env, fetchImpl, log });
+
+        case 'logout':
+            return logout({ platform: flags.platform, env: flags.env, log });
+
+        case 'mcp': {
+            // Loaded only here: the MCP SDK isn't needed by any other command.
+            const { serveMcp } = await import('./mcp.mjs');
+            return serveMcp({ version: JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version });
+        }
+
+        case 'templates':
+            for (const [key, spec] of Object.entries(TEMPLATES)) log(`  ${key.padEnd(8)} ${spec.description}`);
+            return 0;
+
+        case 'init': {
+            if (existsSync(manifestFile)) throw new Error(`${manifestFile} already exists.`);
+            const slug = flags.slug ?? toSlug(packageName() ?? basename(process.cwd()));
+            await checkNewSlug({ client: clientIfLoggedIn(), slug, ...guard });
+            const manifest = newManifest({ slug, name: flags.name ?? titleCase(slug) });
+            await writeFile(manifestFile, JSON.stringify(manifest, null, 2) + '\n');
+            log(`✔ Created ${manifestFile} for "${slug}".`);
+            const iconFile = join(dirname(resolve(manifestFile)), manifest.icon);
+            if (!existsSync(iconFile)) {
+                await writeFile(iconFile, DEFAULT_ICON_SVG);
+                log(`✔ Added a default ${manifest.icon} (replace it with your app's icon: an .svg in one color, or a square .png).`);
+            }
+            await addAgentFiles(dirname(resolve(manifestFile)), { slug, name: manifest.name }, log);
+            for (const warning of (await checkProject(dirname(resolve(manifestFile)))).warnings) log(`! ${warning}`);
+            log('  Next: `npx hawk-app dev` (run it locally inside a stand-in for HawkSearch) and `npx hawk-app deploy` (a new version).');
+            log('  Versions are drafts that only Bridgeline staff see until an approver releases one (`npx hawk-app open`).');
+            log('  (First time on this machine? Run `npx hawk-app sso` once. `npx hawk-app doctor` checks the setup.)');
+            return 0;
+        }
+
+        case 'validate': {
+            const manifest = await loadManifest(manifestFile);
+            const result = validateManifest(manifest);
+            const queries = await checkQueries(manifest, manifestFile);
+            const functions = await checkFunctions(manifest, manifestFile);
+            const projectDir = dirname(resolve(manifestFile));
+            const project = await checkProject(projectDir);
+            const { url } = resolveSettings({ flagPlatform: flags.platform, flagEnv: flags.env });
+            const channelWarning = devAppOnProd(projectDir, url);
+            if (channelWarning) project.warnings.push(channelWarning);
+            // Bridge calls whose scope hawk-app.json lacks (they'd fail with 403 scope_missing).
+            const scopeWarning = describeMissingScopes(await missingScopes(projectDir, manifest.scopes));
+            if (scopeWarning) project.warnings.push(scopeWarning);
+            const icon = result.errors.length ? { errors: [], warnings: [] } : await checkIcon(projectDir, manifest.icon);
+            project.warnings.push(...icon.warnings);
+            const screenshots = result.errors.length ? { errors: [] } : await checkScreenshots(projectDir, manifest.store);
+            const { errors: buildErrors, warnings: buildWarnings } = flags.build
+                ? await checkBuild({ projectDir, manifest, folder: positional[0], runBuild, log })
+                : { errors: [], warnings: [] };
+            const ok = `✔ ${manifestFile} looks good.${queries ? ` ${QUERIES_DIR}/: ${describeQueryCount(queries.queries.length)}.` : ''}${functions ? ` ${FUNCTIONS_DIR}/: ${describeFunctions(functions.functions.length)}.` : ''}${flags.build ? ' The build\'s URLs are under its base path.' : ''}`;
+            return report(
+                { errors: [...result.errors, ...icon.errors, ...screenshots.errors, ...(queries?.errors ?? []), ...(functions?.errors ?? []), ...buildErrors], warnings: [...result.warnings, ...project.warnings, ...buildWarnings] },
+                ok,
+                log,
+            );
+        }
+
+        case 'deploy': {
+            notePlatform();
+            const manifest = await loadManifest(manifestFile);
+            const projectDir = dirname(resolve(manifestFile));
+            // A nudge when the app's dependencies are behind its template (never stops a deploy).
+            try {
+                const hint = upgradeHint(dirname(resolve(manifestFile)), manifest);
+                if (hint) log(hint);
+            } catch {
+                // An app the CLI can't match to a template: no hint.
+            }
+            const checked = validateManifest(manifest);
+            failOnErrors(checked, log);
+            for (const warning of checked.warnings) log(`! ${warning}`);
+            const icon = await checkIcon(projectDir, manifest.icon);
+            for (const warning of icon.warnings) log(`! ${warning}`);
+            if (icon.errors.length) {
+                for (const error of icon.errors) log(`✖ ${error}`);
+                throw new Error('Fix the icon first.');
+            }
+            const screenshots = await checkScreenshots(projectDir, manifest.store);
+            if (screenshots.errors.length) {
+                for (const error of screenshots.errors) log(`✖ ${error}`);
+                throw new Error('Fix the store screenshots first.');
+            }
+            const scopeWarning = describeMissingScopes(await missingScopes(dirname(resolve(manifestFile)), manifest.scopes));
+            if (scopeWarning) log(`! ${scopeWarning}`);
+            const queries = await checkQueries(manifest, manifestFile);
+            if (queries?.errors.length) {
+                for (const error of queries.errors) log(`✖ ${error}`);
+                throw new Error(`Fix ${QUERIES_DIR}/ first.`);
+            }
+            const functions = await checkFunctions(manifest, manifestFile);
+            if (functions?.errors.length) {
+                for (const error of functions.errors) log(`✖ ${error}`);
+                throw new Error(`Fix the functions first.`);
+            }
+            const alias = flags.alias === undefined ? undefined : checkAlias(flags.alias);
+            // hawk-app.json as the platform takes it ($schema and template are for local tools).
+            const { $schema: _schema, template: _template, ...settings } = manifest;
+            if (flags['dry-run']) {
+                // Pull requests: what hawk-app.json would change, without a version.
+                printRegister(await client().register(manifest.slug, settings, true), log);
+                return 0;
+            }
+            const target = buildTarget(projectDir, manifest, positional[0]);
+            if (!target) throw new Error('Which folder does the build go to? hawk-app deploy <build-folder>   (e.g. dist, out, build)');
+            await deploy({
+                client: client(),
+                alias,
+                manifest: settings,
+                registerSettings: async () => printRegisterBrief(await client().register(manifest.slug, settings, false), log),
+                beforeReserve: () => confirmTakeover({ client: client(), slug: manifest.slug, action: 'deploy', ...guard }),
+                confirmAudit: (report) => confirmVulnerabilities(report, guard),
+                slug: manifest.slug,
+                iconFile: icon.file,
+                storeFiles: screenshots.files,
+                dir: positional[0] ?? resolve(projectDir, target.folder),
+                build: target.build && !flags['no-build'],
+                serverFiles: queries?.files ?? [],
+                functions: functions?.functions ?? [],
+                projectDir,
+                audit: !flags['no-audit'],
+                ...(runBuild ? { runBuild } : {}),
+                ...(runAudit ? { runAudit } : {}),
+                fetchImpl,
+                log,
+            });
+            return 0;
+        }
+
+        case 'register': {
+            notePlatform();
+            const manifest = await loadManifest(manifestFile);
+            failOnErrors(validateManifest(manifest), log);
+            // $schema and template are for local tools (the editor, hawk-app upgrade), not the platform.
+            const { $schema, template, ...body } = manifest;
+            if (!flags['dry-run']) await confirmTakeover({ client: client(), slug: manifest.slug, action: 'register', ...guard });
+            const result = await client().register(manifest.slug, body, !!flags['dry-run']);
+            printRegister(result, log);
+            return 0;
+        }
+
+        case 'upgrade': {
+            await upgrade({ manifestFile, template: flags.template, channel: flags.channel, yes: !!flags.yes, install: !flags['no-install'], ...(runInstall ? { runInstall } : {}), log });
+            return 0;
+        }
+
+        case 'status': {
+            const manifest = await loadManifest(manifestFile);
+            const app = await client().status(manifest.slug).catch((error) => {
+                if (error.status === 404) return null;
+                throw error;
+            });
+            if (!app) {
+                log(`${manifest.slug} isn't on the platform yet: \`npm run app:dev\` or \`npm run app:deploy\` adds it.`);
+                return 0;
+            }
+            log(`${app.slug}: ${app.name}`);
+            if (app.adminLocked) log('  LOCKED      by an administrator: nobody sees it');
+            else if (app.status === 'Disabled') log('  disabled    nobody sees it');
+            // Released: the default alias, what every client without another alias gets.
+            log(`  released    ${app.status === 'Live' && app.liveVersion ? `v${app.liveVersion}  (default: every client without another alias)` : 'not yet  (only Bridgeline staff see it; an approver releases it)'}`);
+            const newest = app.pendingVersion ?? (app.status !== 'Live' ? app.currentVersion : undefined);
+            if (newest) log(`  newest      v${newest}  ${describeNewest(app)}`);
+            if (app.pending?.length) log(`  settings    waiting for review: ${app.pending.join(', ')}`);
+            const review = describeReview(app);
+            if (review) log(`  request     ${review}`);
+            const staged = (app.aliases ?? []).filter((a) => a.name !== DEFAULT_ALIAS);
+            if (staged.length) log(`  aliases     ${(app.aliases ?? []).map(describeAlias).join(' · ')}`);
+            log('  (hawk-app versions lists every version with its status; hawk-app why <client> explains what a client sees.)');
+            if (app.checks?.length) {
+                log('  checks      what approvers will see (a failed one needs a force approve):');
+                for (const c of app.checks) log(`    ${CHECK_MARKS[c.level] ?? '·'} ${c.title}: ${c.detail}`);
+            }
+            if (typeof app.autoApprove === 'boolean') log(`  auto-approve ${app.autoApprove ? 'on (new versions and changes are released without review)' : 'off'}`);
+            if (app.reviewEmails === false) log('  review emails off (approval requests, approvals and rejections aren\'t emailed; approvers change it in the Hawk Analytics portal)');
+            if (app.viewCacheMinutes === 0) log('  view cache  off (Engineering stopped it in the Hawk Analytics portal; the views\' cacheMinutes are ignored)');
+            else if (Number.isInteger(app.viewCacheMinutes)) log(`  view cache  ${app.viewCacheMinutes} min for views that declare cacheMinutes (set by Engineering in the Hawk Analytics portal)`);
+            log(`  visibility  ${app.visibility}`);
+            if (app.listed === false) log('  listed      no  (not on the Apps landing page; opens by its direct URL)');
+            if (app.store) log(`  store       ${describeStore(app.store)}`);
+            if (app.hosting) log(`  hosting     ${app.hosting}`);
+            log(`  entry URL   ${app.entryUrl}`);
+            if (app.publishedAt) log(`  published   ${app.publishedAt.slice(0, 10)} by ${app.publishedByName ?? app.publishedBy ?? 'unknown'}`);
+            log(`  scopes      ${app.scopes.join(' ') || '(none)'}`);
+            log(`  origins     ${describeOrigins(app.externalOrigins)}`);
+            if (app.systemParameters?.length) log(`  sysparams   ${app.systemParameters.join(' ')}`);
+            if (app.lambdas?.length) log(`  lambdas     ${app.lambdas.join(' ')}`);
+            const configKeys = Object.keys(app.config ?? {});
+            if (configKeys.length) log(`  config      ${configKeys.join(' ')}`);
+            const schedules = Object.entries(app.schedules ?? {});
+            if (schedules.length) {
+                log(`  schedules   ${schedules.length}  (each runs only for clients where a user turns it on in the app)`);
+                for (const [name, s] of schedules) log(`    ${name}  ${s.function}  "${s.cron}"  ${s.timezone ?? 'UTC'}`);
+            }
+            log(`  clients     ${app.clients.length}`);
+            for (const c of app.clients) {
+                const alias = c.alias ? (app.aliases ?? []).find((a) => a.name === c.alias) : undefined;
+                log(`    ${c.enabled ? '+' : '-'} ${c.id}${c.name && clientNames ? ` (${c.name})` : ''}${describeClientAlias({ alias: c.alias, aliasStatus: alias?.status })}`);
+            }
+            return 0;
+        }
+
+        case 'dev': {
+            const manifest = await loadManifest(manifestFile);
+            const projectDir = dirname(resolve(manifestFile));
+            if (!flags.client && !(env ?? process.env).HAWK_APPS_DEV_CLIENT) {
+                // No client yet: ask which one (by name), and remember it in .env.local for next time.
+                const id = await pickDevClient({ client, slug: manifest.slug, ...(choose ? { choose } : {}), ...(ask ? { ask } : {}), log });
+                await rememberDevClient(projectDir, id);
+                log(`✔ Using client ${id} (saved as HAWK_APPS_DEV_CLIENT in .env.local; --client <id> uses another).`);
+                flags.client = id;
+            }
+            // A new app isn't on the platform yet: register it (a draft, so only Bridgeline staff see it) to run it.
+            const known = await client().status(manifest.slug).then(() => true, (error) => (error.status === 404 ? false : true));
+            if (!known) {
+                const { $schema: _schema, template: _template, ...settings } = manifest;
+                await client().register(manifest.slug, settings, false);
+                log(`✔ Registered ${manifest.slug} on the platform (not released: only Bridgeline staff see it).`);
+            }
+            return devCommand({ client: client(), manifest, flags, projectDir, ...(env ? { env } : {}), signal, log });
+        }
+
+        case 'data':
+            return dataCommand({ client, sub: positional[0], args: positional.slice(1), flags, ...(sleep ? { sleep } : {}), log });
+
+        case 'secrets': {
+            const manifest = await loadManifest(manifestFile);
+            return secretsCommand({ client, manifest, sub: positional[0], args: positional.slice(1), flags, ...(prompt ? { prompt } : {}), ...(env ? { env } : {}), log });
+        }
+
+        case 'config': {
+            const manifest = await loadManifest(manifestFile);
+            return configCommand({ client, manifest, sub: positional[0], args: positional.slice(1), flags, log });
+        }
+
+        case 'clients': {
+            // search reads the environment's client list: no app needed.
+            if (positional[0] === 'search') return clientsCommand({ client, sub: 'search', args: positional.slice(1), log });
+            const manifest = await loadManifest(manifestFile);
+            return clientsCommand({ client, manifest, sub: positional[0], args: positional.slice(1), flags, names: clientNames, ...(choose ? { choose } : {}), log });
+        }
+
+        case 'versions':
+            return versionsCommand({ client: client(), manifest: await loadManifest(manifestFile), log });
+
+        case 'alias':
+            return aliasCommand({ client: client(), manifest: await loadManifest(manifestFile), sub: positional[0], args: positional.slice(1), log });
+
+        case 'why':
+            return whyCommand({ client: client(), manifest: await loadManifest(manifestFile), clientId: positional[0], log });
+
+        case 'errors': {
+            return errorsCommand({ client: client(), manifest: await loadManifest(manifestFile), flags, log });
+        }
+
+        case 'usage': {
+            return usageCommand({ client: client(), manifest: await loadManifest(manifestFile), flags, log });
+        }
+
+        case 'logs': {
+            const manifest = await loadManifest(manifestFile);
+            const controller = new AbortController();
+            const stop = () => controller.abort();
+            signal?.addEventListener('abort', stop, { once: true });
+            if (flags.follow) process.once('SIGINT', stop);
+            try {
+                return await logsCommand({ client, manifest, name: positional[0], flags, ...(sleep ? { sleep } : {}), signal: controller.signal, log });
+            } finally {
+                process.off('SIGINT', stop);
+                signal?.removeEventListener('abort', stop);
+            }
+        }
+
+        default:
+            log(HELP);
+            throw new Error(`Unknown command "${command}".`);
+    }
+}
+
+/** What `hawk-app deploy` says about the hawk-app.json it sent first (the full summary is `hawk-app register`'s). */
+function printRegisterBrief(result, log) {
+    log(`✔ hawk-app.json sent${result.pending?.length ? `: ${result.pending.join(', ')} waiting for review` : ''}`);
+    for (const warning of result.warnings ?? []) log(`  ! ${warning}`);
+    if (result.submissionCleared) log(`  ! ${submissionClearedMessage('settings')}`);
+}
+
+function printRegister(result, log) {
+    log(`${result.dryRun ? 'Dry run, nothing was changed:' : '✔ Sent hawk-app.json for'} ${result.slug}`);
+    log(`  status      ${result.status}${result.adminLocked ? '  (LOCKED by an administrator: hidden from everyone)' : ''}`);
+    log(`  visibility  ${result.visibility}`);
+    if (result.hosting) log(`  hosting     ${result.hosting}`);
+    log(`  entry URL   ${result.entryUrl}`);
+    log(`  scopes      ${result.scopes.join(' ') || '(none)'}`);
+    if (result.pending?.length) {
+        log(`  settings    waiting for review: ${result.pending.join(', ')}`);
+        log('    (approvers approve them in HawkSearch, with the next version)');
+    }
+    if (typeof result.autoApprove === 'boolean') log(`  auto-approve ${result.autoApprove ? 'on (changes are released without review)' : 'off'}`);
+    if (result.externalOrigins) {
+        const o = result.externalOrigins;
+        log(`  origins     ${describeOrigins(o.current)}${o.restamped ? `  (applied to ${o.restamped} deployed page${o.restamped === 1 ? '' : 's'})` : ''}`);
+        for (const origin of o.added) log(`    + ${origin}  (added)`);
+        for (const origin of o.removed) log(`    - ${origin}  (removed)`);
+    }
+    log('  clients     manage with `hawk-app clients` or in the Hawk Analytics portal');
+    for (const warning of result.warnings ?? []) log(`  ! ${warning}`);
+    if (result.submissionCleared && !result.dryRun) log(`  ! ${submissionClearedMessage('settings')}`);
+}
+
+const CHECK_MARKS = { pass: '✔', fail: '✖', info: 'i' };
+
+/** The newest version's status, from the approval request: waiting, rejected, or a draft. */
+function describeNewest({ reviewState }) {
+    if (reviewState === 'waiting_for_approval') return 'waiting for approval';
+    if (reviewState === 'rejected') return 'rejected (see request)';
+    return "draft: only Bridgeline staff see it until it's approved";
+}
+
+const day = (iso) => (typeof iso === 'string' ? iso.slice(0, 10) : 'unknown date');
+const person = (user) => user?.name ?? user?.email ?? 'unknown';
+
+/**
+ * The app's place in the approval workflow (null when the platform doesn't say):
+ * "waiting for approval (submitted by Jane Doe, 2026-10-08: <note>)", "rejected by Jane Doe on 2026-10-08: <reason>".
+ */
+export function describeReview({ reviewState, submission, lastDecision }) {
+    switch (reviewState) {
+        case 'waiting_for_approval': {
+            if (!submission) return 'waiting for approval';
+            const note = submission.note ? `: ${submission.note}` : '';
+            return `waiting for approval (submitted by ${person(submission.submittedBy)}, ${day(submission.submittedAt)}${note})`;
+        }
+        case 'rejected': {
+            if (!lastDecision) return 'rejected';
+            return `rejected by ${person(lastDecision.by)} on ${day(lastDecision.at)}${lastDecision.reason ? `: ${lastDecision.reason}` : ''}`;
+        }
+        case 'pending':
+            return 'not submitted yet (Bridgeline staff submit it for approval in HawkSearch)';
+        case 'draft':
+            return 'draft (Bridgeline staff submit it for approval in HawkSearch)';
+        case 'live':
+            return 'nothing waiting for approval';
+        default:
+            return null;
+    }
+}
+
+/** What the app may load from and call, as the CDN's CSP will allow it. */
+/** A store app's line in `status`: "in the store, $99/month; requests 2 open, 5 approved, 1 declined". */
+function describeStore(store) {
+    const where = store.offered
+        ? 'in the store'
+        : store.listed === false
+          ? 'out of the store (a Hawk-App-Manager took it out)'
+          : 'not in the store yet (clients see it once it\'s released)';
+    const price = store.price ? `, ${store.price}` : '';
+    return `${where}${price}; requests ${store.openRequests} open, ${store.approvedRequests} approved, ${store.declinedRequests} declined`;
+}
+
+function describeOrigins(origins) {
+    if (!origins) return 'any https origin';
+    if (origins.length === 1 && origins[0] === '*') return 'any https origin (*)';
+    return origins.length ? origins.join(' ') : 'none (own files and the platform only)';
+}
+
+/**
+ * Checks queries/ next to the manifest (not in the build folder). Null when the app has none. Queries need the
+ * data:read scope.
+ */
+async function checkQueries(manifest, manifestFile) {
+    const result = await loadQueries(dirname(resolve(manifestFile)));
+    if (!result) return null;
+    if (!(manifest.scopes ?? []).includes(DATA_SCOPE)) {
+        result.errors.unshift(`${QUERIES_DIR}/ needs the "${DATA_SCOPE}" scope: add it to "scopes" in hawk-app.json (or remove ${QUERIES_DIR}/).`);
+    }
+    return result;
+}
+
+/**
+ * Checks functions/ next to the manifest against its "functions" block. Null when the app has neither. Also checks
+ * that the app has a bridge with the /server entry, which the bundles are built with.
+ */
+async function checkFunctions(manifest, manifestFile) {
+    const projectDir = dirname(resolve(manifestFile));
+    const result = await loadFunctions(projectDir, manifest);
+    if (!result) return null;
+    if (result.functions.length) {
+        const problem = checkBridge(projectDir);
+        if (problem) result.errors.push(problem);
+    }
+    return result;
+}
+
+/**
+ * `validate --build [<folder>]`: builds the app as deploy would (with a stand-in base path, /<slug>/v0) and checks
+ * that its HTML only loads URLs under it. The folder comes from the argument or the app:deploy script.
+ */
+async function checkBuild({ projectDir, manifest, folder, runBuild = npmRunBuild, log }) {
+    const found = buildTarget(projectDir, manifest, folder);
+    if (!found) return { errors: ['--build needs the build folder: hawk-app validate --build <folder> (e.g. dist, out).'], warnings: [] };
+    const target = found.folder;
+    const basePath = `/${manifest.slug}/v0`;
+    if (found.build) {
+        log(`Building with HAWK_APP_BASE_PATH=${basePath}…`);
+        await runBuild({ basePath, cwd: projectDir });
+    }
+    const dir = resolve(projectDir, target);
+    if (!existsSync(dir)) return { errors: [`The build folder "${target}" doesn't exist.`], warnings: [] };
+    const outside = await checkBuildUrls(dir, basePath);
+    // The accessibility check approvers will see (critical and serious issues).
+    const warnings = accessibilityWarnings(await checkAccessibility(dir));
+    return { errors: outside.length ? [describeBuildUrls(outside, basePath)] : [], warnings };
+}
+
+
+function describeQueryCount(count) {
+    return `${count} quer${count === 1 ? 'y' : 'ies'}`;
+}
+
+function report({ errors, warnings }, ok, log) {
+    for (const warning of warnings) log(`! ${warning}`);
+    if (errors.length) {
+        for (const error of errors) log(`✖ ${error}`);
+        return 1;
+    }
+    log(ok);
+    return 0;
+}
+
+function failOnErrors(result, log) {
+    if (result.errors.length) {
+        report(result, '', log);
+        throw new Error('Fix hawk-app.json first.');
+    }
+}
+
+export function parse(argv) {
+    const flags = {};
+    const positional = [];
+    let command;
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (arg.startsWith('--') && arg.length > 2 && command !== undefined) {
+            const eq = arg.indexOf('=');
+            const name = eq === -1 ? arg.slice(2) : arg.slice(2, eq);
+            const inline = eq === -1 ? undefined : arg.slice(eq + 1);
+            if (name === 'param') {
+                // Repeatable, and the value keeps its own "=": --param from=2026-09-01 --param to=2026-09-30
+                flags.param = [...(flags.param ?? []), inline ?? argv[++i]];
+                continue;
+            }
+            const takesValue = ['manifest', 'platform', 'slug', 'name', 'template', 'client', 'app', 'since', 'value-from-env', 'engine', 'url', 'port', 'env', 'publisher', 'pick', 'channel', 'days', 'alias'].includes(name);
+            flags[name] = takesValue ? inline ?? argv[++i] : true;
+        } else if (command === undefined) {
+            command = arg;
+        } else {
+            positional.push(arg);
+        }
+    }
+    return { command, positional, flags };
+}
+
+function packageName() {
+    try {
+        return JSON.parse(readFileSync('package.json', 'utf8')).name?.replace(/^@[^/]+\//, '');
+    } catch {
+        return undefined;
+    }
+}
+
+