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

package/src/clients.mjs

@@ -0,0 +1,221 @@
+import { existsSync } from 'node:fs';
+import { readFile, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { createInterface } from 'node:readline';
+import { DEFAULT_ALIAS, checkAlias, describeClientAlias } from './aliases.mjs';
+
+/** Same rules as the platform: HawkSearch client ids, and the optional label kept with them. */
+export const CLIENT_ID = /^[A-Za-z0-9_.-]{1,100}$/;
+const MAX_CLIENT_NAME = 100;
+
+const USAGE = `Usage:
+  hawk-app clients
+  hawk-app clients search <name or id>
+  hawk-app clients add <id> [<id> …] [--name "<name>"] [--alias <name>]
+  hawk-app clients add --pick "<name or id>" [--alias <name>]
+  hawk-app clients exclude <id> [--name "<name>"]
+  hawk-app clients remove <id>`;
+
+const VISIBILITY = {
+    allowList: 'allowList: only the clients listed with + have the app',
+    all: 'all: every client has the app, except the ones listed with -',
+    internal: 'internal: Bridgeline users only; the client list is ignored',
+};
+
+/**
+ * `hawk-app clients …`: which clients have the app. The platform registry is the only source of truth (not
+ * hawk-app.json); the same list is changed in the Hawk Analytics portal. Changes apply at once, without a deploy or
+ * approval, and are recorded in the app's history. `client` is a factory, so a usage mistake shows before any login check.
+ * `names: false` prints ids only (the MCP server: client names stay out of the assistant's context). `choose` asks the
+ * person at the terminal to pick one of the matches for `add --pick`.
+ */
+export async function clientsCommand({ client, manifest, sub = 'list', args = [], flags = {}, names = true, choose = chooseOnTerminal, log = console.log }) {
+    if (sub === 'search') return searchClients({ client, text: args.join(' ').trim(), log });
+    const slug = manifest.slug;
+    const label = names ? labelOf : (c) => c.id;
+    switch (sub) {
+        case 'list': {
+            const { visibility, clients = [] } = await call(() => client().listClients(slug), slug);
+            log(`${slug}: visibility ${VISIBILITY[visibility] ?? visibility}`);
+            if (!clients.length) {
+                log(visibility === 'allowList' ? '  no client has it yet. Add one with `hawk-app clients add <id>`.' : '  (no clients listed)');
+                return 0;
+            }
+            for (const c of clients) log(`  ${c.enabled ? '+' : '-'} ${label(c)}${describeClientAlias(c)}`);
+            return 0;
+        }
+
+        case 'add':
+        case 'exclude': {
+            const enabled = sub === 'add';
+            if (flags.alias !== undefined && !enabled) throw new Error(`--alias is for \`clients add\`.\n${USAGE}`);
+            const alias = flags.alias === undefined ? undefined : checkAlias(flags.alias, { allowDefault: true });
+            const ids = enabled && flags.pick !== undefined ? [await pickClient({ client, text: flags.pick, slug, choose, log })] : checkIds(args);
+            if (ids[0] === null) {
+                log('Cancelled: no client was added.');
+                return 1;
+            }
+            const name = checkName(flags.name);
+            if (name !== undefined && ids.length > 1) throw new Error('--name labels one client: add the clients one at a time to name them.');
+            // Read first: the warnings below need the registered visibility (it can differ from hawk-app.json until review).
+            const { visibility } = await call(() => client().listClients(slug), slug);
+            // --alias: the version they get. On an alias whose version isn't approved, only Bridgeline staff in them see it.
+            let refused = 0;
+            for (const id of ids) {
+                try {
+                    const saved = await call(() => client().setClient(slug, id, { enabled, ...(alias ? { alias } : {}), ...(name !== undefined ? { name } : {}) }), slug);
+                    const where = saved.alias
+                        ? ` on ${saved.alias}${saved.aliasStatus && saved.aliasStatus !== 'approved' ? ` (${saved.aliasStatus}: only Bridgeline staff in it see the app until its version is approved)` : ''}`
+                        : '';
+                    log(`✔ ${enabled ? 'Added' : 'Excluded'} ${label(saved)} ${enabled ? 'to' : 'from'} ${slug}${where}. It applies now (recorded in the app's history).`);
+                } catch (error) {
+                    if (error.data?.code !== 'approver_required') throw error;
+                    refused++;
+                    log(`✖ ${id}'s users see ${slug} now: only an approver can change what it gets (the app's Rollout tab in the Hawk Analytics portal, or HawkSearch).`);
+                }
+            }
+            if (!enabled && visibility !== 'all') log(`! ${slug} has visibility "${visibility}": excluding a client only has an effect with visibility "all".`);
+            if (enabled && visibility === 'internal') log(`! ${slug} has visibility "internal": only Bridgeline users see it until its visibility changes.`);
+            if (alias && alias !== DEFAULT_ALIAS && refused < ids.length) log(`  Back to the default version: \`hawk-app clients add <id> --alias ${DEFAULT_ALIAS}\`.`);
+            return refused ? 1 : 0;
+        }
+
+        case 'remove': {
+            const id = checkId(args[0]);
+            try {
+                await call(() => client().removeClient(slug, id), slug);
+            } catch (error) {
+                if (error.data?.code === 'client_not_found') throw new Error(`${id} is not in ${slug}'s client list; nothing was changed.`);
+                throw error;
+            }
+            log(`✔ Removed ${id} from ${slug}'s client list. It applies now (recorded in the app's history).`);
+            return 0;
+        }
+
+        default:
+            throw new Error(`Unknown clients command "${sub}".\n${USAGE}`);
+    }
+}
+
+/**
+ * `hawk-app clients search <text>`: the environment's clients whose name or id matches (the Hawk Analytics portal's client
+ * list), to find the id to add. Needs no app: it reads the list, nothing else.
+ */
+async function searchClients({ client, text, log }) {
+    if (text.length < 2) throw new Error(`Search with at least 2 characters of a client's name or id.\n${USAGE}`);
+    const { clients = [], more } = await client().searchClients(text);
+    if (!clients.length) {
+        log(`No client matches "${text}". Try another part of its name, or the id the dashboard shows (e.g. e3141).`);
+        return 0;
+    }
+    log(`Clients matching "${text}"${more ? ' (the best matches; search for more of the name to narrow it down)' : ''}:`);
+    for (const c of clients) log(`  ${labelOf(c)}`);
+    log('Add one with `hawk-app clients add <id>`.');
+    return 0;
+}
+
+/**
+ * `clients add --pick "<text>"`: finds the matching clients and has the person at the terminal pick one. The id, or
+ * null when they cancel. This is where the MCP server sends people whose assistant can't show a picker, so the names are
+ * only ever on their screen.
+ */
+async function pickClient({ client, text, slug, choose, log }) {
+    const wanted = typeof text === 'string' ? text.trim() : '';
+    if (wanted.length < 2) throw new Error(`--pick needs at least 2 characters of a client's name or id, e.g. --pick "outdoor".\n${USAGE}`);
+    const { clients = [], more } = await client().searchClients(wanted);
+    if (!clients.length) throw new Error(`No client matches "${wanted}". Try another part of its name, or the id the dashboard shows (e.g. e3141).`);
+    const picked = await choose(`Which client should get ${slug}?${more ? ' (the best matches; cancel and use more of the name if yours is missing)' : ''}`, clients.map(labelOf));
+    if (picked === undefined) throw new Error('Picking a client needs a terminal. Run `hawk-app clients search` and then `hawk-app clients add <id>` instead.');
+    return picked === null ? null : clients[picked].id;
+}
+
+/**
+ * `hawk-app dev` without a client: asks for part of a client's name, then which of the matches. The id; throws when
+ * there's no terminal or nothing is picked.
+ */
+export async function pickDevClient({ client, slug, ask = askOnTerminal, choose = chooseOnTerminal, log = console.log }) {
+    const noTerminal = 'Which client? Run `hawk-app dev --client <id>` (find the id with `hawk-app clients search <name>`).';
+    for (;;) {
+        const text = await ask(`Run ${slug} with which client's data? Part of its name or id: `);
+        if (text === undefined) throw new Error(noTerminal);
+        if (!text.trim()) throw new Error('No client picked.');
+        if (text.trim().length < 2) {
+            log('  At least 2 characters, please.');
+            continue;
+        }
+        const { clients = [], more } = await client().searchClients(text.trim());
+        if (!clients.length) {
+            log(`  No client matches "${text.trim()}". Try another part of its name, or its id (e.g. e3141).`);
+            continue;
+        }
+        const picked = await choose(`Which client?${more ? ' (the best matches; Enter and use more of the name if yours is missing)' : ''}`, clients.map(labelOf));
+        if (picked === undefined) throw new Error(noTerminal);
+        if (picked !== null) return clients[picked].id;
+    }
+}
+
+/** Saves the dev client in the project's .env.local (git-ignored), replacing an earlier one. */
+export async function rememberDevClient(projectDir, id) {
+    const file = join(projectDir, '.env.local');
+    const text = existsSync(file) ? await readFile(file, 'utf8') : '';
+    const kept = text.split(/\r?\n/).filter((line) => line && !/^\s*(export\s+)?HAWK_APPS_DEV_CLIENT\s*=/.test(line));
+    await writeFile(file, [...kept, `HAWK_APPS_DEV_CLIENT=${id}`, ''].join('\n'));
+}
+
+/** A line of text from the terminal; undefined when there's no terminal. */
+export function askOnTerminal(question, { input = process.stdin, output = process.stdout } = {}) {
+    if (!input.isTTY) return Promise.resolve(undefined);
+    return new Promise((resolve) => {
+        const rl = createInterface({ input, output });
+        rl.question(question, (answer) => {
+            rl.close();
+            resolve(answer);
+        });
+    });
+}
+
+/** Numbered choices on the terminal: the index picked, null for none (Enter), undefined when there's no terminal. */
+export function chooseOnTerminal(question, options, { input = process.stdin, output = process.stdout } = {}) {
+    if (!input.isTTY) return Promise.resolve(undefined);
+    return new Promise((resolve) => {
+        const rl = createInterface({ input, output });
+        output.write(`${question}\n${options.map((o, i) => `  ${i + 1}. ${o}`).join('\n')}\n`);
+        rl.question(`Number (Enter to cancel): `, (answer) => {
+            rl.close();
+            const n = Number(answer.trim());
+            resolve(Number.isInteger(n) && n >= 1 && n <= options.length ? n - 1 : null);
+        });
+    });
+}
+
+/** Platform calls, saying how to add the app when it isn't on the platform yet. */
+async function call(fn, slug) {
+    try {
+        return await fn();
+    } catch (error) {
+        if (error.data?.code === 'app_not_found') throw new Error(`${slug} isn't on the platform yet: \`npm run app:dev\` or \`npm run app:deploy\` adds it.`);
+        throw error;
+    }
+}
+
+const labelOf = (c) => `${c.id}${c.name ? ` (${c.name})` : ''}`;
+
+
+
+function checkIds(ids) {
+    if (!ids.length) throw new Error(USAGE);
+    return [...new Set(ids.map(checkId))];
+}
+
+function checkId(id) {
+    if (!id) throw new Error(USAGE);
+    if (!CLIENT_ID.test(id)) throw new Error(`"${id}" is not a valid client id: 1-100 letters, digits, "_", "." or "-" (e.g. e3141).`);
+    return id;
+}
+
+function checkName(name) {
+    if (name === undefined) return undefined;
+    if (typeof name !== 'string') throw new Error('--name needs a value, e.g. --name "Outdoor Demo".');
+    if (name.length > MAX_CLIENT_NAME) throw new Error(`--name is longer than ${MAX_CLIENT_NAME} characters.`);
+    return name;
+}

package/src/config.mjs

@@ -0,0 +1,148 @@
+import { CLIENT_ID } from './clients.mjs';
+import { CONFIG_KEY, configValueError } from './manifest.mjs';
+
+const USAGE = `Usage:
+  hawk-app config list [--client <id>]
+  hawk-app config set <key> <value> [--client <id>]
+  hawk-app config unset <key> [--client <id>]`;
+
+/**
+ * `hawk-app config …`: the app's config values (declared in "config" in hawk-app.json), set for the whole app (global)
+ * or one client (`--client`). Values apply within about 30 seconds, without a deploy or approval, and are not secret:
+ * they reach the app's browser code. `client` is a factory, so a usage mistake shows before any login check.
+ */
+export async function configCommand({ client, manifest, sub, args = [], flags = {}, log = console.log }) {
+    const slug = manifest.slug;
+    // A bare --client (no id after it) is a mistake, never the global value.
+    const clientId = Object.hasOwn(flags, 'client') ? checkClient(flags.client) : null;
+    const layer = clientId ? `client ${clientId}` : 'global';
+    switch (sub) {
+        case 'list': {
+            const { keys = [] } = await call(() => client().getConfig(slug), slug);
+            const localKeys = declared(manifest);
+            if (!keys.length) {
+                log(`${slug} has no config keys on the platform. Declare them in "config" in hawk-app.json and deploy (or \`hawk-app register\`).`);
+            } else {
+                log(`${keys.length} config key${keys.length === 1 ? '' : 's'} for ${slug}${clientId ? `, client ${clientId}` : ''} (values are not secret: they reach the browser):`);
+                for (const k of keys) {
+                    const head = k.declared === false ? `(not declared: its values are ignored; hawk-app config unset ${k.key} deletes them)` :`${k.type}  ${k.default === null || k.default === undefined ? 'no default' : `default ${formatValue(k.default)}`}`;
+                    log(`  ${k.key}  ${head}`);
+                    const rows = [['global', k.global], ...(k.clients ?? []).filter((c) => !clientId || c.clientId === clientId).map((c) => [c.clientId, c])];
+                    if (clientId && !rows.some(([id]) => id === clientId)) rows.push([clientId, null]);
+                    const width = Math.max(...rows.map(([id]) => id.length));
+                    for (const [id, stored] of rows) log(`    ${id.padEnd(width)}  ${describeStored(stored)}`);
+                }
+            }
+            const missing = [...localKeys.keys()].filter((key) => !keys.some((k) => k.key === key));
+            for (const key of missing) log(`! ${key} is in hawk-app.json but not on the platform yet: deploy (or \`hawk-app register\`) to declare it.`);
+            return 0;
+        }
+
+        case 'set': {
+            const [key, raw] = args;
+            if (!key || raw === undefined) throw new Error(USAGE);
+            const declaration = local(manifest, key);
+            const value = parseValue(key, declaration.type, raw);
+            await write(client, slug, key, value, clientId);
+            log(`✔ Set ${key} for ${slug} (${layer}): ${formatValue(value)}. It applies within about 30 seconds, without a deploy.`);
+            return 0;
+        }
+
+        case 'unset': {
+            const [key] = args;
+            if (!key) throw new Error(USAGE);
+            if (!CONFIG_KEY.test(key)) throw new Error(`"${key}" is not a valid config key: a letter, then letters, digits and "_" (at most 64 characters).`);
+            await write(client, slug, key, null, clientId);
+            log(
+                `✔ Cleared ${key} for ${slug} (${layer}). ${clientId ? `${clientId} now gets the global value, else the default.` : "Clients without their own value now get the default."}`,
+            );
+            return 0;
+        }
+
+        default:
+            throw new Error(sub ? `Unknown config command "${sub}".\n${USAGE}` : USAGE);
+    }
+}
+
+function checkClient(id) {
+    if (typeof id !== 'string' || !id) throw new Error(`--client needs a client id, e.g. --client e3141.\n${USAGE}`);
+    if (!CLIENT_ID.test(id)) throw new Error(`"${id}" is not a valid client id: 1-100 letters, digits, "_", "." or "-" (e.g. e3141).`);
+    return id;
+}
+
+/** Key → declaration, from the local hawk-app.json. */
+function declared(manifest) {
+    const config = manifest.config && typeof manifest.config === 'object' && !Array.isArray(manifest.config) ? manifest.config : {};
+    return new Map(Object.entries(config).filter(([, d]) => d && typeof d === 'object'));
+}
+
+function local(manifest, key) {
+    const declaration = declared(manifest).get(key);
+    if (!declaration) throw new Error(`${key} isn't declared in hawk-app.json: add it to "config" with its type (e.g. "${key}": { "type": "string" }), then deploy.`);
+    return declaration;
+}
+
+/** The command-line text as a value of the key's declared type, checked like the platform checks it. */
+export function parseValue(key, type, raw) {
+    let value;
+    switch (type) {
+        case 'string':
+            value = raw;
+            break;
+        case 'number':
+            value = raw.trim() === '' ? NaN : Number(raw);
+            if (!Number.isFinite(value)) throw new Error(`${key} is a number: "${raw}" isn't one.`);
+            break;
+        case 'boolean':
+            if (raw !== 'true' && raw !== 'false') throw new Error(`${key} is a boolean: use true or false, not "${raw}".`);
+            value = raw === 'true';
+            break;
+        case 'emails':
+            value = raw.split(',').map((a) => a.trim()).filter(Boolean);
+            break;
+        case 'json':
+            try {
+                value = JSON.parse(raw);
+            } catch (error) {
+                throw new Error(`${key} is JSON, but "${raw}" isn't valid JSON (${error.message}). Quote it for your shell, e.g. '{"a":1}'.`);
+            }
+            break;
+        default:
+            throw new Error(`${key} has no valid type in hawk-app.json ("${type}"): run \`hawk-app validate\`.`);
+    }
+    const problem = configValueError(type, value, key);
+    if (problem) throw new Error(problem);
+    return value;
+}
+
+async function write(client, slug, key, value, clientId) {
+    try {
+        return await call(() => client().setConfig(slug, key, value, clientId), slug);
+    } catch (error) {
+        if (error.data?.code === 'config_key_not_declared') {
+            throw new Error(`${key} isn't declared on the platform: deploy (or \`hawk-app register\`) hawk-app.json with it in "config" first.`);
+        }
+        throw error;
+    }
+}
+
+async function call(fn, slug) {
+    try {
+        return await fn();
+    } catch (error) {
+        if (error.data?.code === 'app_not_found') throw new Error(`${slug} isn't on the platform yet: \`npm run app:dev\` or \`npm run app:deploy\` adds it.`);
+        throw error;
+    }
+}
+
+function describeStored(stored) {
+    if (!stored) return 'not set';
+    const when = stored.updatedAt ? `  (${stored.updatedAt.slice(0, 16).replace('T', ' ')}${stored.updatedBy ? ` by ${stored.updatedBy}` : ''})` : '';
+    return `${formatValue(stored.value)}${stored.valid === false ? '  ! invalid for its type: ignored' : ''}${when}`;
+}
+
+/** A value for the terminal: emails as a list, the rest as JSON, cut at 100 characters. */
+function formatValue(value) {
+    const text = Array.isArray(value) && value.every((v) => typeof v === 'string' && v.includes('@')) && value.length ? value.join(', ') : JSON.stringify(value);
+    return text.length > 100 ? `${text.slice(0, 99)}…` : text;
+}

package/src/create.mjs

@@ -0,0 +1,186 @@
+import { spawnSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { mkdir, readdir, readFile, writeFile } from 'node:fs/promises';
+import { basename, join, relative, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { planAgentFiles, writeAgentFiles } from './agents.mjs';
+import { credentialsPath } from './credentials.mjs';
+import { ENV_EXAMPLE, resolveSettings } from './env.mjs';
+import { newManifest } from './manifest.mjs';
+import { DEFAULT_ICON_SVG } from './app-icon.mjs';
+import { applyChannel, CHANNELS, cliChannel, DEV_CHANNEL_NOTE, planChannel, writeCdnFiles } from './channel.mjs';
+
+const TEMPLATES_DIR = fileURLToPath(new URL('../templates', import.meta.url));
+
+export const TEMPLATES = {
+    react: { description: 'React + Vite + TypeScript + the UI kit (Spark\'s stylesheet and elements)', build: 'dist', dev: 'npm run dev', devUrl: (slug) => `http://localhost:3100/${slug}/` },
+    preact: { description: 'Preact + Vite + TypeScript (small bundle) + the UI kit (stylesheet and elements)', build: 'dist', dev: 'npm run dev', devUrl: (slug) => `http://localhost:3100/${slug}/` },
+    next: { description: 'Next.js (static export) + TypeScript + the UI kit (stylesheet and elements)', build: 'out', dev: 'npm run dev', devUrl: (slug) => `http://localhost:3100/${slug}/` },
+    'next-mui': {
+        description: 'Next.js (static export) + Material UI 9 + the UI kit (Spark\'s theme and components)',
+        build: 'out',
+        dev: 'npm run dev',
+        devUrl: (slug) => `http://localhost:3100/${slug}/`,
+    },
+    vanilla: { description: 'Plain HTML + JavaScript, no build step (the bridge and the UI kit from the CDN)', build: 'public', dev: 'npm run dev', devUrl: () => 'http://localhost:3100/' },
+};
+
+export function toSlug(value) {
+    return (
+        String(value)
+            .toLowerCase()
+            .replace(/[^a-z0-9]+/g, '-')
+            .replace(/^-+|-+$/g, '')
+            .slice(0, 64) || 'my-app'
+    );
+}
+
+export function titleCase(slug) {
+    return slug
+        .split('-')
+        .map((w) => w.charAt(0).toUpperCase() + w.slice(1))
+        .join(' ');
+}
+
+/** Scaffolds a new Hawk App project from one of the built-in templates. */
+/** @param checkSlug Refuses a taken slug before anything is written (create's own check: see slug-guard.mjs). */
+/**
+ * @param channel `latest` or `dev`: which builds of the bridge and CLI the app follows. Default: this CLI's own channel,
+ * so `npx …-cli@dev create` makes a dev app (see channel.mjs).
+ */
+export async function createProject({ target, template = 'react', name, install = false, checkSlug, channel = cliChannel(), log = console.log, credentialsFile = credentialsPath() }) {
+    if (!CHANNELS.includes(channel)) throw new Error(`--channel must be latest or dev, not "${channel}".`);
+    if (!target) throw new Error(`Usage: hawk-app create <folder> [--template ${Object.keys(TEMPLATES).join('|')}] [--name "Display Name"] [--install]`);
+    const spec = TEMPLATES[template];
+    if (!spec) throw new Error(`Unknown template "${template}". Choose one of: ${Object.keys(TEMPLATES).join(', ')}.`);
+
+    const dir = resolve(target);
+    if (existsSync(dir) && (await readdir(dir)).length > 0) throw new Error(`"${target}" already exists and is not empty.`);
+    const slug = toSlug(basename(dir));
+    if (checkSlug) await checkSlug(slug);
+    const displayName = name ?? titleCase(slug);
+    const cliVersion = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version;
+    const replacements = { __SLUG__: slug, __NAME__: displayName, __CLI_VERSION__: cliVersion };
+
+    const source = join(TEMPLATES_DIR, template);
+    const written = [];
+    for (const file of await listTemplateFiles(source)) {
+        const content = (await readFile(join(source, file), 'utf8')).replace(/__SLUG__|__NAME__|__CLI_VERSION__/g, (m) => replacements[m]);
+        await writeOut(join(dir, file), content);
+        written.push(file);
+    }
+
+    // A dev app: the Hawk packages (and the vanilla CDN import) on the dev tag, not the release the template pins.
+    if (channel === 'dev') {
+        const pkgFile = join(dir, 'package.json');
+        const appJsFile = join(dir, 'public', 'app.js');
+        const pkg = existsSync(pkgFile) ? JSON.parse(await readFile(pkgFile, 'utf8')) : null;
+        const appJs = existsSync(appJsFile) ? await readFile(appJsFile, 'utf8') : null;
+        const plan = planChannel({ pkg, appJs, channel, latestVersion: () => null });
+        applyChannel(plan, pkg ?? {}, appJs);
+        if (pkg && plan.dependencies.length) await writeOut(pkgFile, JSON.stringify(pkg, null, 2) + '\n');
+        // The bridge and the kit from the CDN (app.js, index.html).
+        if (plan.cdn) await writeCdnFiles(dir, plan.cdn.to);
+    }
+
+    await writeOut(join(dir, 'hawk-app.json'), JSON.stringify(newManifest({ slug, name: displayName, template }), null, 2) + '\n');
+    await writeOut(join(dir, 'icon.svg'), DEFAULT_ICON_SVG);
+    await writeOut(join(dir, '.gitignore'), ['node_modules/', 'dist/', 'out/', '.next/', 'next-env.d.ts', '.env', '.env.local', '.env.*.local', '*.log', ''].join('\n'));
+    await writeOut(join(dir, '.env.example'), ENV_EXAMPLE);
+    await writeOut(join(dir, 'README.md'), readme({ slug, displayName, template, spec }));
+    const agentFiles = await writeAgentFiles(dir, planAgentFiles(dir, { slug, name: displayName, template }));
+
+    log(`✔ Created ${displayName} (${spec.description}) in ${relative(process.cwd(), dir) || '.'}`);
+    log(`  slug: ${slug} → each deploy is served at <apps CDN>/${slug}/v<n>/`);
+    log('  AGENTS.md tells AI coding assistants (Claude Code, Copilot, Cursor, …) how Hawk Apps work.');
+    if (channel === 'dev') DEV_CHANNEL_NOTE.forEach((line) => log(`  ${line}`));
+
+    if (install) {
+        log('  Installing dependencies…');
+        const result = spawnSync('npm', ['install', '--no-audit', '--no-fund'], { cwd: dir, stdio: 'inherit', shell: process.platform === 'win32' });
+        if (result.status !== 0) throw new Error('npm install failed. Run it yourself in the new folder.');
+    }
+
+    log('\nNext steps:');
+    log(`  cd ${relative(process.cwd(), dir) || '.'}`);
+    if (!install) log('  npm install');
+    const { key, url } = resolveSettings({ dir, credentialsFile });
+    if (!key) log('  npx hawk-app sso                          (once per machine: sign in with your Bridgeline account)');
+    log("  npm run app:dev                           (run it locally inside a stand-in for HawkSearch, with a client's data)");
+    log(`  npm run app:deploy                        (${template === 'vanilla' ? 'uploads public/' : 'builds and uploads'} a new version, with hawk-app.json)`);
+    log(key ? `\n  Logged in to ${url}. Check everything any time with \`npx hawk-app doctor\`.` : '');
+    log('  It isn\'t released yet: only Bridgeline staff see it, from the Apps page in HawkSearch (`npx hawk-app open`). Submit it');
+    log('  for approval there; an approver releases it. `npx hawk-app --help` lists everything else.');
+    log('  Docs: https://developers.hawksearchapps.com (npx hawk-app docs), with your Bridgeline account.');
+    return { dir, slug, files: [...written, 'hawk-app.json', 'icon.svg', '.gitignore', '.env.example', 'README.md', ...agentFiles] };
+}
+
+async function listTemplateFiles(root) {
+    const files = [];
+    async function walk(current) {
+        for (const entry of await readdir(current, { withFileTypes: true })) {
+            const full = join(current, entry.name);
+            if (entry.isDirectory()) await walk(full);
+            else files.push(relative(root, full));
+        }
+    }
+    await walk(root);
+    return files.sort();
+}
+
+async function writeOut(path, content) {
+    await mkdir(resolve(path, '..'), { recursive: true });
+    await writeFile(path, content);
+}
+
+function readme({ slug, displayName, template, spec }) {
+    return `# ${displayName}
+
+A Hawk App: a tool that runs inside HawkSearch (today's dashboard, Spark later) and gets its context and data through
+[\`@bridgeline-digital/hawk-app-bridge\`](https://www.npmjs.com/package/@bridgeline-digital/hawk-app-bridge).
+Created with \`hawk-app create --template ${template}\` (${spec.description}).
+
+## Develop
+\`\`\`bash
+npm install
+npx hawk-app sso                           # once per machine: sign in with your Bridgeline account
+npm run app:dev                            # the app inside a local stand-in for HawkSearch, with a client's data
+\`\`\`
+\`app:dev\` runs \`${spec.dev}\` and a stand-in for HawkSearch at http://localhost:3200 with real tokens and data. The
+first time it asks which client (remembered in \`.env.local\`; \`-- --client <id>\` picks another) and registers the
+app (not released). Opened directly in a browser, the app says "Open this app from the Apps page in HawkSearch": it
+needs a host for its context and data. Queries and functions run from the deployed version: deploy after changing them.
+
+To try a local copy inside the real HawkSearch instead, open
+\`<HawkSearch>/admin/apps/${slug}?devUrl=${spec.devUrl(slug)}\` (Bridgeline users, \`http://localhost\` ports 3100-3103).
+
+## Data
+Use the bridge. There are **no API keys in the app**; the platform adds credentials server-side for the current client.
+- \`app.analytics.report('searches' | 'queries' | 'poor-results' | …, { limit })\` needs the \`reports:read\` scope.
+- \`app.dashboard.get('Synonym')\` (HawkSearch dashboard API, read) needs the \`hawksearch:read\` scope.
+- \`app.dashboard.post/put/delete('Synonym', body)\` (writes: synonyms, redirects, banners, landing pages, …) need the \`hawksearch:write\` scope; writes are never retried.
+- \`app.context\` and \`app.onContextChange\` give the client, engine, date range, locale and theme.
+- Own backend? Send \`await app.getToken()\` as \`Authorization: Bearer ...\` and verify it there against the
+  platform's \`/.well-known/jwks.json\`. Don't use cookies: browsers block them inside the host's iframe.
+
+## Ship
+\`\`\`bash
+npm run app:deploy            # ${template === 'vanilla' ? 'upload public/' : `build and upload ${spec.build}/`} as a new version, with hawk-app.json
+npx hawk-app status           # released or not, the newest version, the approval request
+npx hawk-app open             # the app in HawkSearch, to review it and submit it for approval
+npx hawk-app clients add <id> # give a client the app (or manage clients in the Hawk Analytics portal)
+\`\`\`
+Every deploy is a new, numbered version${template === 'vanilla' ? '' : `: \`app:deploy\` builds the app with its base path set to \`/${slug}/v<n>\``},
+with the settings in \`hawk-app.json\` (scopes, origins, views, functions…).
+
+- **Not released at first.** A new app's versions are drafts: only Bridgeline staff see them. Submit a version for
+  approval in HawkSearch; once an approver releases it, the app's clients get it.
+- **Each version is reviewed.** Clients keep the released version until a new one is approved. \`npx hawk-app versions\`
+  lists every version with its status; \`npx hawk-app why <client>\` explains what a client sees.
+- **Test before release.** \`npm run app:deploy -- --alias staging\` deploys a version for an alias (e.g. new clients or a
+  branch) without touching the main line. See versions-and-aliases in the Hawk Apps docs.
+- **Clients any time.** \`npx hawk-app clients add|exclude|remove <id>\` (or the Hawk Analytics portal) applies at once,
+  without a deploy or approval, and is recorded in the app's history.
+- **Something off?** \`npx hawk-app doctor\` checks your login, the platform, the project and the bridge.
+`;
+}

package/src/credentials.mjs

@@ -0,0 +1,56 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { chmod, mkdir, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+
+/**
+ * Per-user credentials, shared by every app on this machine:
+ *   Windows        %APPDATA%\hawk-app\credentials.json
+ *   macOS / Linux  $XDG_CONFIG_HOME/hawk-app/credentials.json (default ~/.config/hawk-app/credentials.json)
+ * HAWK_APPS_CREDENTIALS_FILE overrides the location.
+ */
+export function credentialsPath(env = process.env, platform = process.platform, home = homedir()) {
+    if (env.HAWK_APPS_CREDENTIALS_FILE) return env.HAWK_APPS_CREDENTIALS_FILE;
+    const base = platform === 'win32' ? env.APPDATA ?? join(home, 'AppData', 'Roaming') : env.XDG_CONFIG_HOME ?? join(home, '.config');
+    return join(base, 'hawk-app', 'credentials.json');
+}
+
+export function normalizeUrl(url) {
+    return String(url ?? '').trim().replace(/\/+$/, '');
+}
+
+/** @returns {{ platforms: Record<string, { publisherKey: string, savedAt?: string }> }} */
+export function readCredentials(path) {
+    try {
+        const data = JSON.parse(readFileSync(path, 'utf8'));
+        return { platforms: data.platforms ?? {} };
+    } catch {
+        return { platforms: {} };
+    }
+}
+
+async function writeCredentials(path, data) {
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(path, JSON.stringify(data, null, 2) + '\n', { mode: 0o600 });
+    // Owner-only on macOS/Linux; on Windows the file lives in the user's own profile.
+    await chmod(path, 0o600).catch(() => undefined);
+}
+
+/** Saves the key for a platform. It doesn't choose the platform commands use (see resolveSettings). */
+export async function saveCredential(path, url, publisherKey) {
+    const data = readCredentials(path);
+    const platform = normalizeUrl(url);
+    data.platforms[platform] = { publisherKey, savedAt: new Date().toISOString() };
+    await writeCredentials(path, data);
+}
+
+/** @returns {boolean} whether a key was removed. */
+export async function removeCredential(path, url) {
+    if (!existsSync(path)) return false;
+    const data = readCredentials(path);
+    const platform = normalizeUrl(url);
+    if (!data.platforms[platform]) return false;
+    delete data.platforms[platform];
+    await writeCredentials(path, data);
+    return true;
+}