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

package/src/secrets.mjs

@@ -0,0 +1,86 @@
+import { SECRET_NAME } from './functions.mjs';
+import { promptHidden } from './login.mjs';
+
+/** The platform keeps each secret in a Standard-tier Parameter Store SecureString: at most 4 KB (UTF-8). */
+export const MAX_SECRET_BYTES = 4 * 1024;
+
+const USAGE = `Usage:
+  hawk-app secrets list
+  hawk-app secrets set <NAME> [--value-from-env <VAR>]
+  hawk-app secrets delete <NAME>`;
+
+/**
+ * `hawk-app secrets …`: the app's function secrets, stored by the platform (never in the app or its versions).
+ * Values are typed with hidden input (or read from an environment variable) and never printed. `client` is a
+ * factory, so a usage mistake shows before any login check.
+ */
+export async function secretsCommand({ client, manifest, sub, args = [], flags = {}, prompt = promptHidden, env = process.env, log = console.log }) {
+    const slug = manifest.slug;
+    switch (sub) {
+        case 'list': {
+            const { secrets = [] } = await client().listSecrets(slug);
+            const declared = declaredSecrets(manifest);
+            if (!secrets.length) log(`${slug} has no secrets yet. Set one with \`hawk-app secrets set <NAME>\`.`);
+            else {
+                log(`${secrets.length} secret${secrets.length === 1 ? '' : 's'} for ${slug} (values are never shown):`);
+                const width = Math.max(...secrets.map((s) => s.name.length));
+                for (const secret of secrets) {
+                    const users = declared.get(secret.name);
+                    log(`  ${secret.name.padEnd(width)}  ${secret.updatedAt ? `updated ${secret.updatedAt.slice(0, 16).replace('T', ' ')}` : ''}${users ? `  used by ${users.join(', ')}` : '  (not used by any function)'}`);
+                }
+            }
+            const missing = [...declared.keys()].filter((name) => !secrets.some((s) => s.name === name));
+            for (const name of missing) log(`! ${name} is declared by ${declared.get(name).join(', ')} but not set: calls fail with secret_missing until you set it.`);
+            return 0;
+        }
+
+        case 'set': {
+            const name = checkName(args[0]);
+            let value;
+            const from = flags['value-from-env'];
+            if (from !== undefined) {
+                if (typeof from !== 'string' || !from) throw new Error('--value-from-env needs the name of an environment variable.');
+                value = env[from];
+                if (value === undefined || value === '') throw new Error(`Environment variable ${from} is not set (or empty).`);
+            } else {
+                value = await prompt(`Value for ${name} (input hidden): `, {
+                    notInteractive: `\`hawk-app secrets set\` needs an interactive terminal to type the value. In CI, pass --value-from-env <VAR>.`,
+                });
+                if (!value) throw new Error('No value entered; nothing was changed.');
+            }
+            if (Buffer.byteLength(value, 'utf8') > MAX_SECRET_BYTES) throw new Error(`The value is larger than ${MAX_SECRET_BYTES / 1024} KB.`);
+            await client().setSecret(slug, name, value);
+            log(`✔ Set ${name} for ${slug}. It applies to every version at once.`);
+            if (!declaredSecrets(manifest).has(name)) log(`! No function in hawk-app.json declares ${name}: add it to a function's "secrets" to receive it as ctx.secrets.${name}.`);
+            return 0;
+        }
+
+        case 'delete': {
+            const name = checkName(args[0]);
+            await client().deleteSecret(slug, name);
+            log(`✔ Deleted ${name} for ${slug}.`);
+            const users = declaredSecrets(manifest).get(name);
+            if (users) log(`! ${users.join(', ')} still declare${users.length === 1 ? 's' : ''} ${name}: calls fail with secret_missing until it's set again.`);
+            return 0;
+        }
+
+        default:
+            throw new Error(sub ? `Unknown secrets command "${sub}".\n${USAGE}` : USAGE);
+    }
+}
+
+function checkName(name) {
+    if (!name) throw new Error(USAGE);
+    if (!SECRET_NAME.test(name)) throw new Error(`"${name}" is not a valid secret name: UPPER_SNAKE_CASE, a letter first, up to 64 characters (e.g. FEED_API_KEY).`);
+    return name;
+}
+
+/** Secret name → the functions in the manifest that declare it. */
+function declaredSecrets(manifest) {
+    const map = new Map();
+    const functions = manifest.functions && typeof manifest.functions === 'object' ? manifest.functions : {};
+    for (const [fn, config] of Object.entries(functions)) {
+        for (const secret of Array.isArray(config?.secrets) ? config.secrets : []) map.set(secret, [...(map.get(secret) ?? []), fn]);
+    }
+    return map;
+}

package/src/slug-guard.mjs

@@ -0,0 +1,80 @@
+// Keeps two developers from working on one app by accident. Apps belong to a publisher (a team), and every person on
+// the team can register and deploy any of its apps, so a reused slug would silently mix two codebases into one app.
+//   - create / init: refuse a slug that's already taken (unless --yes).
+//   - register / deploy: when someone else's key made the app's last change, ask before going on (--yes skips it; a
+//     pipeline, with no terminal to ask in, gets a warning and goes on).
+import { createInterface } from 'node:readline';
+
+/**
+ * What the platform says about a slug for the caller's key: free (404), another publisher's (409 slug_owned), or this
+ * publisher's app with its last change. Null when it can't tell (not logged in, platform unreachable, other errors).
+ */
+export async function slugStatus(client, slug) {
+    try {
+        const app = await client.status(slug);
+        return { state: 'taken', app };
+    } catch (error) {
+        if (error.status === 404) return { state: 'free' };
+        if (error.status === 409) return { state: 'other' };
+        return null;
+    }
+}
+
+const describeChange = (last) => {
+    const who = last.name || last.keyId || 'a shared key';
+    const when = last.at ? new Date(last.at).toLocaleString() : 'earlier';
+    return `${last.kind === 'deploy' ? 'deployed' : 'registered'} by ${who} on ${when}`;
+};
+
+/** create / init: throws when the slug is taken; logs a note when it couldn't check. */
+export async function checkNewSlug({ client, slug, yes = false, log = console.log }) {
+    if (!client) {
+        log(`  (Not logged in, so "${slug}" wasn't checked. \`hawk-app register\` will tell you if it's taken.)`);
+        return;
+    }
+    const status = await slugStatus(client, slug);
+    if (!status) {
+        log(`  (Couldn't check whether "${slug}" is free; \`hawk-app register\` will tell you if it's taken.)`);
+        return;
+    }
+    if (status.state === 'other') {
+        throw new Error(`"${slug}" belongs to another publisher. Pick another name (the folder name, or --slug).`);
+    }
+    if (status.state === 'taken' && !yes) {
+        const last = status.app.lastChange;
+        throw new Error(
+            `"${slug}" is already an app${last ? `, last ${describeChange(last)}` : ''}. Pick another name, or work in that app's own repository.\n` +
+                '  To set up this folder for that existing app anyway, add --yes.',
+        );
+    }
+}
+
+/** Asks a yes/no question on the terminal; null when there is no terminal to ask in. */
+export function askYesNo(question, { input = process.stdin, output = process.stdout } = {}) {
+    if (!input.isTTY) return Promise.resolve(null);
+    return new Promise((resolve) => {
+        const rl = createInterface({ input, output });
+        rl.question(`${question} (y/N) `, (answer) => {
+            rl.close();
+            resolve(/^y(es)?$/i.test(answer.trim()));
+        });
+    });
+}
+
+/**
+ * register / deploy: when the app's last change was made with someone else's key, asks before going on. Throws
+ * "Cancelled." on no; with no terminal (CI) it warns and goes on; --yes goes on quietly.
+ */
+export async function confirmTakeover({ client, slug, action, yes = false, confirm = askYesNo, log = console.log }) {
+    const status = await slugStatus(client, slug);
+    const last = status?.state === 'taken' ? status.app.lastChange : null;
+    if (!last || last.yours || yes) return;
+
+    const message = `"${slug}" was last ${describeChange(last)}.`;
+    const answer = await confirm(`${message} ${action === 'deploy' ? 'Deploy a new version of it' : 'Register your hawk-app.json over it'}?`);
+    if (answer === null) {
+        log(`! ${message} Going on (no terminal to ask; add --yes to silence this).`);
+        return;
+    }
+    if (!answer) throw new Error('Cancelled. Nothing was changed.');
+}

package/src/sso.mjs

@@ -0,0 +1,182 @@
+// `hawk-app sso`: Bridgeline staff sign in with their AD account in the browser, and the platform issues them their own
+// publisher key (it expires; sign in again then). No key is handed from person to person. `hawk-app login` with a key
+// from the portal keeps working, and pipelines keep using portal keys.
+//
+// The standard flow for command-line tools: OAuth 2.0 authorization code with PKCE (RFC 7636) against the HawkSearch
+// user pool, sent straight to the Bridgeline identity provider, with the browser returning to a one-time server on
+// localhost (RFC 8252). The ID token goes to the platform, which verifies it and answers with the key.
+import { spawn } from 'node:child_process';
+import { createHash, randomBytes } from 'node:crypto';
+import { createServer } from 'node:http';
+import { hostname } from 'node:os';
+import { credentialsPath, readCredentials, saveCredential } from './credentials.mjs';
+import { describePlatform, resolveSettings } from './env.mjs';
+
+const SIGN_IN_TIMEOUT_MS = 5 * 60_000;
+
+const base64url = (buffer) => buffer.toString('base64').replace(/=+$/, '').replace(/\+/g, '-').replace(/\//g, '_');
+
+/** Opens a URL in the default browser, without a shell (the URL has & in it). Best effort: the URL is printed too. */
+export function openBrowser(url) {
+    const [command, args] =
+        process.platform === 'win32' ? ['rundll32', ['url.dll,FileProtocolHandler', url]] : process.platform === 'darwin' ? ['open', [url]] : ['xdg-open', [url]];
+    try {
+        const child = spawn(command, args, { stdio: 'ignore', detached: true });
+        child.on('error', () => {});
+        child.unref();
+    } catch {
+        // The printed address still works.
+    }
+}
+
+const PAGE = (title, text) =>
+    `<!doctype html><meta charset="utf-8"><title>${title}</title><body style="font-family:system-ui,sans-serif;max-width:32rem;margin:4rem auto;padding:0 1rem;line-height:1.5"><h1 style="font-size:1.4rem">${title}</h1><p>${text}</p></body>`;
+
+/**
+ * Listens on the first free port of `ports` for the browser's return to /callback. Resolves to { port, redirectUri,
+ * result, close }: `result` settles with the query of the first /callback request.
+ */
+async function callbackServer(ports, expectedState) {
+    let settle;
+    const result = new Promise((resolve, reject) => (settle = { resolve, reject }));
+    const server = createServer((req, res) => {
+        const url = new URL(req.url ?? '/', 'http://localhost');
+        if (url.pathname !== '/callback') {
+            res.writeHead(404).end();
+            return;
+        }
+        const query = Object.fromEntries(url.searchParams);
+        if (query.state !== expectedState) {
+            res.writeHead(400, { 'Content-Type': 'text/html; charset=utf-8' }).end(PAGE('Sign-in failed', 'This sign-in was not started by this terminal. Run <code>hawk-app sso</code> again.'));
+            settle.reject(new Error('The sign-in came back with the wrong state (not this attempt). Nothing was saved.'));
+            return;
+        }
+        const failed = Boolean(query.error);
+        res.writeHead(failed ? 400 : 200, { 'Content-Type': 'text/html; charset=utf-8', 'Cache-Control': 'no-store' }).end(
+            failed ? PAGE('Sign-in failed', 'Go back to the terminal for the details.') : PAGE('Signed in', 'You can close this tab and go back to the terminal.'),
+        );
+        settle.resolve(query);
+    });
+    for (const port of ports) {
+        try {
+            await new Promise((resolve, reject) => {
+                server.once('error', reject);
+                server.listen(port, 'localhost', () => {
+                    server.off('error', reject);
+                    resolve();
+                });
+            });
+            return { port, redirectUri: `http://localhost:${port}/callback`, result, close: () => server.close() };
+        } catch (error) {
+            if (error.code !== 'EADDRINUSE') throw error;
+        }
+    }
+    throw new Error(`Ports ${ports.join(', ')} are all in use, so the sign-in can't come back to this terminal. Close what uses them and try again.`);
+}
+
+async function json(response) {
+    const text = await response.text();
+    try {
+        return text ? JSON.parse(text) : {};
+    } catch {
+        return { detail: text.slice(0, 200) };
+    }
+}
+
+/**
+ * Signs in with Bridgeline AD and saves the issued key for this machine and platform, like `hawk-app login`.
+ * `openUrl` opens the browser (tests stand in for it); `machine` names this computer's key.
+ */
+export async function sso({
+    dir = process.cwd(),
+    platform,
+    env,
+    publisher,
+    fetchImpl = fetch,
+    openUrl = openBrowser,
+    log = console.log,
+    machine = hostname(),
+    timeoutMs = SIGN_IN_TIMEOUT_MS,
+    credentialsFile = credentialsPath(),
+}) {
+    const { url } = resolveSettings({ flagPlatform: platform, flagEnv: env, dir, credentialsFile });
+    log(`Platform: ${describePlatform(url)}`);
+
+    let response;
+    try {
+        response = await fetchImpl(`${url}/publish/sso`);
+    } catch (error) {
+        throw new Error(`Could not reach ${url}: ${error.message}.`);
+    }
+    if (response.status === 404) throw new Error(`Sign-in isn't available on ${describePlatform(url)}. Use \`hawk-app login\` with a publisher key from Engineering.`);
+    if (!response.ok) throw new Error(`The platform answered ${response.status} for the sign-in settings.`);
+    const settings = await json(response);
+    // The team to work in: its apps are the ones the key can change. Checked before the browser opens.
+    const publishers = settings.publishers ?? [];
+    if (publisher && publishers.length && !publishers.includes(publisher)) {
+        throw new Error(`Sign-in can't issue keys for publisher "${publisher}". Choose one of: ${publishers.join(', ')} (default ${publishers[0]}).`);
+    }
+
+    const verifier = base64url(randomBytes(32));
+    const state = base64url(randomBytes(16));
+    const server = await callbackServer(settings.redirectPorts, state);
+    try {
+        const authorize = new URL(settings.authorizeUrl);
+        for (const [name, value] of Object.entries({
+            response_type: 'code',
+            client_id: settings.clientId,
+            redirect_uri: server.redirectUri,
+            identity_provider: settings.identityProvider,
+            scope: settings.scopes,
+            state,
+            code_challenge: base64url(createHash('sha256').update(verifier).digest()),
+            code_challenge_method: 'S256',
+        })) {
+            authorize.searchParams.set(name, value);
+        }
+        log('Opening your browser to sign in with your Bridgeline account…');
+        log(`  If it doesn't open, go to: ${authorize.href}`);
+        openUrl(authorize.href);
+
+        let timer;
+        const query = await Promise.race([
+            server.result,
+            new Promise((_, reject) => {
+                timer = setTimeout(() => reject(new Error('No sign-in within 5 minutes. Run `hawk-app sso` again.')), timeoutMs);
+            }),
+        ]).finally(() => clearTimeout(timer));
+        if (query.error) throw new Error(`The sign-in failed: ${query.error_description ?? query.error}. Nothing was saved.`);
+        if (!query.code) throw new Error('The sign-in came back without a code. Nothing was saved.');
+
+        // The code, for the ID token: a public client proves it started the sign-in with the PKCE verifier.
+        const token = await fetchImpl(settings.tokenUrl, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+            body: new URLSearchParams({ grant_type: 'authorization_code', client_id: settings.clientId, code: query.code, redirect_uri: server.redirectUri, code_verifier: verifier }).toString(),
+        });
+        const tokens = await json(token);
+        if (!token.ok || !tokens.id_token) throw new Error(`The sign-in couldn't be completed (${tokens.error_description ?? tokens.error ?? token.status}). Nothing was saved.`);
+
+        const issued = await fetchImpl(`${url}/publish/sso`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ idToken: tokens.id_token, machine, ...(publisher ? { publisherId: publisher } : {}) }),
+        });
+        const key = await json(issued);
+        if (!issued.ok || !key.key) throw new Error(`${key.detail ?? key.title ?? `The platform answered ${issued.status}.`} Nothing was saved.`);
+
+        // One saved key per platform: say so when it was another team's.
+        const previous = (await readCredentials(credentialsFile)).platforms[url]?.publisherKey;
+        await saveCredential(credentialsFile, url, key.key);
+        if (previous && previous.split('.')[0] !== key.publisherId) {
+            log(`  (This replaces your saved key for publisher "${previous.split('.')[0]}" on this platform. Switch back with \`hawk-app sso --publisher ${previous.split('.')[0]}\` or \`hawk-app login\`.)`);
+        }
+        log(`✔ Signed in as ${key.label} (${key.email}) on ${describePlatform(url)}, publisher "${key.publisherId}".`);
+        log(`  Your key ${key.publisherId}/${key.keyId} is saved for every app on this machine and works until ${String(key.expiresAt).slice(0, 10)}; run \`hawk-app sso\` again then.`);
+        if (key.developerGroup === 'added') log('  You are in Hawk-App-Developers, so you can submit apps for approval in HawkSearch.');
+        if (key.developerGroup === 'failed') log("  ! Couldn't add you to Hawk-App-Developers (needed to submit apps for approval in HawkSearch). Ask Engineering, or run `hawk-app sso` again later.");
+        return key;
+    } finally {
+        server.close();
+    }
+}

package/src/store-listing.mjs

@@ -0,0 +1,106 @@
+import { existsSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import { extname, resolve } from 'node:path';
+
+// The store listing ("store" in hawk-app.json, for "visibility": "store"): what clients that don't have the app see on
+// the Store tab of the Apps page in HawkSearch. Deploy uploads its screenshots into every version as _hawk/store/1.png,
+// 2.jpg…, so they're reviewed and released with the version. The price label isn't here: Bridgeline sets it.
+
+// Same rules and messages as the platform (AppStoreRules).
+export const MAX_TAGLINE = 120;
+export const MAX_HIGHLIGHTS = 5;
+export const MAX_HIGHLIGHT = 120;
+export const MAX_SCREENSHOTS = 5;
+export const MAX_SCREENSHOT_BYTES = 1024 * 1024;
+const STORE_FIELDS = ['tagline', 'highlights', 'screenshots'];
+export const SCREENSHOT_PATH = /^(?!.*\.\.)[A-Za-z0-9_-][A-Za-z0-9_.-]*(\/[A-Za-z0-9_-][A-Za-z0-9_.-]*)*\.(png|jpg|jpeg|webp)$/i;
+
+/** Where deploy puts screenshot `index` (0-based) in a version, e.g. _hawk/store/1.png. */
+export function screenshotUploadPath(index, screenshot) {
+    return `_hawk/store/${index + 1}${extname(screenshot).toLowerCase()}`;
+}
+
+/** The "store" section's errors and warnings (the files themselves: checkScreenshots). */
+export function validateStore(m) {
+    const errors = [];
+    const warnings = [];
+    const store = m.store;
+    if (store === undefined || store === null) {
+        if (m.visibility === 'store') errors.push('visibility "store" needs a store section: { "tagline": "…", "screenshots": ["store/overview.png"] }.');
+        return { errors, warnings };
+    }
+    if (typeof store !== 'object' || Array.isArray(store)) {
+        return { errors: ['store must be an object: { "tagline": "…", "highlights": ["…"], "screenshots": ["store/overview.png"] }.'], warnings };
+    }
+    const unknown = Object.keys(store).filter((k) => !STORE_FIELDS.includes(k));
+    if (unknown.length) errors.push(`store: unknown setting${unknown.length === 1 ? '' : 's'} ${unknown.map((k) => `"${k}"`).join(', ')} (allowed: ${STORE_FIELDS.join(', ')}).`);
+    if (typeof store.tagline !== 'string' || !store.tagline.trim() || store.tagline.trim().length > MAX_TAGLINE) {
+        errors.push(`store.tagline is required: one line of at most ${MAX_TAGLINE} characters.`);
+    }
+    const strings = (name) => {
+        const value = store[name];
+        if (value === undefined || value === null) return [];
+        if (!Array.isArray(value) || value.some((v) => typeof v !== 'string')) {
+            errors.push(`store.${name} must be an array of strings.`);
+            return [];
+        }
+        return value.map((v) => v.trim());
+    };
+    const highlights = strings('highlights');
+    if (highlights.length > MAX_HIGHLIGHTS) errors.push(`store.highlights has at most ${MAX_HIGHLIGHTS} items.`);
+    if (highlights.some((h) => !h.length || h.length > MAX_HIGHLIGHT)) errors.push(`store.highlights: each is 1-${MAX_HIGHLIGHT} characters.`);
+    const screenshots = strings('screenshots');
+    if (!screenshots.length || screenshots.length > MAX_SCREENSHOTS) {
+        errors.push(`store.screenshots needs 1-${MAX_SCREENSHOTS} images (the card shows them when there's no trial).`);
+    }
+    for (const bad of screenshots.filter((s) => !SCREENSHOT_PATH.test(s) || s.length > 200)) {
+        errors.push(`store.screenshots: "${bad}" must be a .png, .jpg or .webp file next to hawk-app.json, e.g. "store/overview.png".`);
+    }
+    if (m.visibility !== 'store') warnings.push('store is only shown for visibility "store": clients won\'t see this listing.');
+    return { errors, warnings };
+}
+
+/**
+ * Checks the screenshot files the store section names (when it names valid ones): there, an image of its type, at most
+ * 1 MB. Returns the files to upload ({ path: _hawk/store/<n>.<ext>, size, data }), with errors.
+ */
+export async function checkScreenshots(projectDir, store) {
+    const errors = [];
+    const files = [];
+    const screenshots = Array.isArray(store?.screenshots) ? store.screenshots : [];
+    if (screenshots.some((s) => typeof s !== 'string' || !SCREENSHOT_PATH.test(s.trim()))) return { errors, files };
+    for (const [index, raw] of screenshots.entries()) {
+        const screenshot = raw.trim();
+        const full = resolve(projectDir, screenshot);
+        if (!existsSync(full)) {
+            errors.push(`store.screenshots: ${screenshot} doesn't exist next to hawk-app.json.`);
+            continue;
+        }
+        const data = await readFile(full);
+        if (data.length > MAX_SCREENSHOT_BYTES) {
+            errors.push(`store.screenshots: ${screenshot} is ${Math.ceil(data.length / 1024)} KB; a screenshot can be at most ${MAX_SCREENSHOT_BYTES / 1024 / 1024} MB.`);
+            continue;
+        }
+        if (!isImageOfType(data, extname(screenshot).toLowerCase())) {
+            errors.push(`store.screenshots: ${screenshot} isn't a ${extname(screenshot).slice(1).toUpperCase()} image.`);
+            continue;
+        }
+        files.push({ path: screenshotUploadPath(index, screenshot), size: data.length, data });
+    }
+    return { errors, files: errors.length ? [] : files };
+}
+
+/** True when `data` starts like an image of the extension's type. */
+function isImageOfType(data, extension) {
+    switch (extension) {
+        case '.png':
+            return data.length > 8 && data.subarray(0, 8).equals(Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]));
+        case '.jpg':
+        case '.jpeg':
+            return data.length > 3 && data[0] === 0xff && data[1] === 0xd8 && data[2] === 0xff;
+        case '.webp':
+            return data.length > 12 && data.toString('ascii', 0, 4) === 'RIFF' && data.toString('ascii', 8, 12) === 'WEBP';
+        default:
+            return false;
+    }
+}

package/src/telemetry.mjs

@@ -0,0 +1,50 @@
+// `hawk-app errors` and `hawk-app usage`: what the bridge reports from the app's pages (uncaught errors and rejections,
+// and one open per page load), as the platform groups them. Read-only.
+
+const plural = (n, one, many = `${one}s`) => `${n} ${n === 1 ? one : many}`;
+
+function parseDays(value, fallback, max) {
+    if (value === undefined || value === true) return fallback;
+    const days = Number(value);
+    if (!Number.isInteger(days) || days < 1 || days > max) throw new Error(`--days must be a whole number from 1 to ${max}.`);
+    return days;
+}
+
+/** `hawk-app errors [--days 7]`: the app's errors, the most frequent first. */
+export async function errorsCommand({ client, manifest, flags = {}, log = console.log }) {
+    const days = parseDays(flags.days, 7, 30);
+    const { total, groups } = await client.appErrors(manifest.slug, days);
+    if (!groups.length) {
+        log(`No errors reported for ${manifest.slug} in the last ${plural(days, 'day')}.`);
+        return 0;
+    }
+    log(`${plural(total, 'error')} in ${plural(groups.length, 'group')}, the last ${plural(days, 'day')} (${manifest.slug}):`);
+    for (const group of groups) {
+        const versions = group.versions.length ? ` · ${group.versions.map((v) => `v${v}`).join(', ')}` : '';
+        const when = group.firstDay === group.lastDay ? group.lastDay : `${group.firstDay} – ${group.lastDay}`;
+        log('');
+        log(`${group.count}× ${group.kind === 'rejection' ? 'unhandled rejection' : 'error'}: ${group.message}`);
+        log(`   ${plural(group.clients, 'client')}${versions} · ${when}${group.source ? ` · ${group.source}` : ''}`);
+        const frames = (group.stack ?? '').split('\n').map((l) => l.trim()).filter((l) => l.startsWith('at ') || l.includes('@')).slice(0, 3);
+        for (const frame of frames) log(`   ${frame}`);
+    }
+    return 0;
+}
+
+/** `hawk-app usage [--days 30]`: opens and users per day and client. */
+export async function usageCommand({ client, manifest, flags = {}, log = console.log }) {
+    const days = parseDays(flags.days, 30, 400);
+    const usage = await client.appUsage(manifest.slug, days);
+    log(`${manifest.slug}, the last ${plural(days, 'day')}:`);
+    log(`  ${plural(usage.opens, 'open')} of the app and ${plural(usage.viewOpens, 'view open')} (previews, slots) by ${plural(usage.users, 'user')} at ${plural(usage.clients, 'client')}`);
+    log(`  ${plural(usage.staffOpens, 'open')} by Bridgeline staff (not counted above)`);
+    if (usage.perClient.length) {
+        log('');
+        log('  Client             Opens   Views   Users   Last day');
+        for (const c of usage.perClient.slice(0, 20)) {
+            log(`  ${c.clientId.padEnd(18)} ${String(c.opens).padStart(5)}   ${String(c.viewOpens).padStart(5)}   ${String(c.users).padStart(5)}   ${c.lastDay}`);
+        }
+        if (usage.perClient.length > 20) log(`  … and ${usage.perClient.length - 20} more`);
+    }
+    return 0;
+}

package/src/template-history.json

@@ -0,0 +1,34 @@
+{
+  "next/next.config.ts": [
+    "import type { NextConfig } from 'next';\n\n// Hawk Apps are static files on the apps CDN under /<slug>/: static export, no server features\n// (no SSR, API routes or middleware). All data comes through the bridge.\nconst nextConfig: NextConfig = {\n    output: 'export',\n    basePath: '/__SLUG__',\n    trailingSlash: true,\n    images: { unoptimized: true },\n};\n\nexport default nextConfig;\n",
+    "import type { NextConfig } from 'next';\n\n// Hawk Apps are static files on the apps CDN, one folder per deploy (/<slug>/v<n>/): static export, no server\n// features (no SSR, API routes or middleware). All data comes through the bridge.\n// `hawk-app deploy` builds with HAWK_APP_BASE_PATH=/<slug>/v<n>; local dev uses /<slug>.\nconst nextConfig: NextConfig = {\n    output: 'export',\n    basePath: process.env.HAWK_APP_BASE_PATH ?? '/__SLUG__',\n    trailingSlash: true,\n    images: { unoptimized: true },\n};\n\nexport default nextConfig;\n"
+  ],
+  "next/tsconfig.json": [
+    "{\n  \"compilerOptions\": {\n    \"target\": \"ES2022\",\n    \"lib\": [\"dom\", \"dom.iterable\", \"esnext\"],\n    \"allowJs\": false,\n    \"skipLibCheck\": true,\n    \"strict\": true,\n    \"noEmit\": true,\n    \"esModuleInterop\": true,\n    \"module\": \"esnext\",\n    \"moduleResolution\": \"bundler\",\n    \"resolveJsonModule\": true,\n    \"isolatedModules\": true,\n    \"jsx\": \"preserve\",\n    \"incremental\": true,\n    \"plugins\": [{ \"name\": \"next\" }],\n    \"paths\": { \"@/*\": [\"./src/*\"] }\n  },\n  \"include\": [\"next-env.d.ts\", \"**/*.ts\", \"**/*.tsx\", \".next/types/**/*.ts\"],\n  \"exclude\": [\"node_modules\"]\n}\n"
+  ],
+  "next-mui/next.config.ts": [
+    "import type { NextConfig } from 'next';\n\n// Hawk Apps are static files on the apps CDN under /<slug>/: static export, no server features\n// (no SSR, API routes or middleware). All data comes through the bridge.\nconst nextConfig: NextConfig = {\n    output: 'export',\n    basePath: '/__SLUG__',\n    trailingSlash: true,\n    images: { unoptimized: true },\n};\n\nexport default nextConfig;\n",
+    "import type { NextConfig } from 'next';\n\n// Hawk Apps are static files on the apps CDN, one folder per deploy (/<slug>/v<n>/): static export, no server\n// features (no SSR, API routes or middleware). All data comes through the bridge.\n// `hawk-app deploy` builds with HAWK_APP_BASE_PATH=/<slug>/v<n>; local dev uses /<slug>.\nconst nextConfig: NextConfig = {\n    output: 'export',\n    basePath: process.env.HAWK_APP_BASE_PATH ?? '/__SLUG__',\n    trailingSlash: true,\n    images: { unoptimized: true },\n};\n\nexport default nextConfig;\n"
+  ],
+  "next-mui/tsconfig.json": [
+    "{\n  \"compilerOptions\": {\n    \"target\": \"ES2022\",\n    \"lib\": [\"dom\", \"dom.iterable\", \"esnext\"],\n    \"allowJs\": false,\n    \"skipLibCheck\": true,\n    \"strict\": true,\n    \"noEmit\": true,\n    \"esModuleInterop\": true,\n    \"module\": \"esnext\",\n    \"moduleResolution\": \"bundler\",\n    \"resolveJsonModule\": true,\n    \"isolatedModules\": true,\n    \"jsx\": \"preserve\",\n    \"incremental\": true,\n    \"plugins\": [{ \"name\": \"next\" }],\n    \"paths\": { \"@/*\": [\"./src/*\"] }\n  },\n  \"include\": [\"next-env.d.ts\", \"**/*.ts\", \"**/*.tsx\", \".next/types/**/*.ts\"],\n  \"exclude\": [\"node_modules\"]\n}\n"
+  ],
+  "preact/vite.config.ts": [
+    "import preact from '@preact/preset-vite';\nimport { defineConfig } from 'vite';\n\n// Hawk Apps are served from the apps CDN at /<slug>/, so every asset URL needs that prefix.\nexport default defineConfig({\n    base: '/__SLUG__/',\n    plugins: [preact()],\n    // Port 3100: the dev platform accepts data calls from localhost:3100-3103 (E360 dev mode, ?devUrl=).\n    server: { port: 3100, strictPort: true },\n});\n",
+    "import preact from '@preact/preset-vite';\nimport { defineConfig } from 'vite';\n\n// Each deploy is served from the apps CDN at /<slug>/v<n>/, so every asset URL needs that prefix.\n// `hawk-app deploy` builds with HAWK_APP_BASE_PATH=/<slug>/v<n>; local dev uses /<slug>/.\nexport default defineConfig({\n    base: `${process.env.HAWK_APP_BASE_PATH ?? '/__SLUG__'}/`,\n    plugins: [preact()],\n    // Port 3100: the dev platform accepts data calls from localhost:3100-3103 (E360 dev mode, ?devUrl=).\n    server: { port: 3100, strictPort: true },\n});\n",
+    "import preact from '@preact/preset-vite';\nimport { defineConfig } from 'vite';\n\n// Each deploy is served from the apps CDN at /<slug>/v<n>/, so every asset URL needs that prefix.\n// `hawk-app deploy` builds with HAWK_APP_BASE_PATH=/<slug>/v<n>; local dev uses /<slug>/.\nexport default defineConfig({\n    base: `${process.env.HAWK_APP_BASE_PATH ?? '/__SLUG__'}/`,\n    plugins: [preact()],\n    // Port 3100: the dev platform accepts data calls from localhost:3100-3103 (HawkSearch dev mode, ?devUrl=).\n    server: { port: 3100, strictPort: true },\n});\n"
+  ],
+  "preact/tsconfig.json": [
+    "{\n  \"compilerOptions\": {\n    \"target\": \"ES2022\",\n    \"lib\": [\"ES2022\", \"DOM\", \"DOM.Iterable\"],\n    \"module\": \"ESNext\",\n    \"moduleResolution\": \"Bundler\",\n    \"jsx\": \"react-jsx\",\n    \"jsxImportSource\": \"preact\",\n    \"strict\": true,\n    \"noUnusedLocals\": true,\n    \"skipLibCheck\": true,\n    \"isolatedModules\": true,\n    \"noEmit\": true,\n    \"types\": [\"vite/client\"]\n  },\n  \"include\": [\"src\", \"vite.config.ts\"]\n}\n",
+    "{\n  \"compilerOptions\": {\n    \"target\": \"ES2022\",\n    \"lib\": [\"ES2022\", \"DOM\", \"DOM.Iterable\"],\n    \"module\": \"ESNext\",\n    \"moduleResolution\": \"Bundler\",\n    \"jsx\": \"react-jsx\",\n    \"jsxImportSource\": \"preact\",\n    \"strict\": true,\n    \"noUnusedLocals\": true,\n    \"skipLibCheck\": true,\n    \"isolatedModules\": true,\n    \"noEmit\": true,\n    \"types\": [\"vite/client\", \"node\"]\n  },\n  \"include\": [\"src\", \"vite.config.ts\"]\n}\n"
+  ],
+  "react/vite.config.ts": [
+    "import react from '@vitejs/plugin-react';\nimport { defineConfig } from 'vite';\n\n// Hawk Apps are served from the apps CDN at /<slug>/, so every asset URL needs that prefix.\nexport default defineConfig({\n    base: '/__SLUG__/',\n    plugins: [react()],\n    // Port 3100: the dev platform accepts data calls from localhost:3100-3103 (E360 dev mode, ?devUrl=).\n    server: { port: 3100, strictPort: true },\n});\n",
+    "import react from '@vitejs/plugin-react';\nimport { defineConfig } from 'vite';\n\n// Each deploy is served from the apps CDN at /<slug>/v<n>/, so every asset URL needs that prefix.\n// `hawk-app deploy` builds with HAWK_APP_BASE_PATH=/<slug>/v<n>; local dev uses /<slug>/.\nexport default defineConfig({\n    base: `${process.env.HAWK_APP_BASE_PATH ?? '/__SLUG__'}/`,\n    plugins: [react()],\n    // Port 3100: the dev platform accepts data calls from localhost:3100-3103 (E360 dev mode, ?devUrl=).\n    server: { port: 3100, strictPort: true },\n});\n",
+    "import react from '@vitejs/plugin-react';\nimport { defineConfig } from 'vite';\n\n// Each deploy is served from the apps CDN at /<slug>/v<n>/, so every asset URL needs that prefix.\n// `hawk-app deploy` builds with HAWK_APP_BASE_PATH=/<slug>/v<n>; local dev uses /<slug>/.\nexport default defineConfig({\n    base: `${process.env.HAWK_APP_BASE_PATH ?? '/__SLUG__'}/`,\n    plugins: [react()],\n    // Port 3100: the dev platform accepts data calls from localhost:3100-3103 (HawkSearch dev mode, ?devUrl=).\n    server: { port: 3100, strictPort: true },\n});\n"
+  ],
+  "react/tsconfig.json": [
+    "{\n  \"compilerOptions\": {\n    \"target\": \"ES2022\",\n    \"lib\": [\"ES2022\", \"DOM\", \"DOM.Iterable\"],\n    \"module\": \"ESNext\",\n    \"moduleResolution\": \"Bundler\",\n    \"jsx\": \"react-jsx\",\n    \"strict\": true,\n    \"noUnusedLocals\": true,\n    \"skipLibCheck\": true,\n    \"isolatedModules\": true,\n    \"noEmit\": true,\n    \"types\": [\"vite/client\"]\n  },\n  \"include\": [\"src\", \"vite.config.ts\"]\n}\n",
+    "{\n  \"compilerOptions\": {\n    \"target\": \"ES2022\",\n    \"lib\": [\"ES2022\", \"DOM\", \"DOM.Iterable\"],\n    \"module\": \"ESNext\",\n    \"moduleResolution\": \"Bundler\",\n    \"jsx\": \"react-jsx\",\n    \"strict\": true,\n    \"noUnusedLocals\": true,\n    \"skipLibCheck\": true,\n    \"isolatedModules\": true,\n    \"noEmit\": true,\n    \"types\": [\"vite/client\", \"node\"]\n  },\n  \"include\": [\"src\", \"vite.config.ts\"]\n}\n"
+  ]
+}