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

package/src/upgrade.mjs

@@ -0,0 +1,406 @@
+// `hawk-app upgrade`: brings an app's template-owned parts up to the template this CLI ships, so apps don't drift
+// behind it (e.g. on a Next.js with a known vulnerability). What it touches, and nothing else:
+//   - package.json: the packages the template itself pins, raised to the template's version (never lowered); the app's
+//     other dependencies are left alone. Packages the template added later that apps need (ADDED_PACKAGES: the UI kit)
+//     are added, with what to change in the app's code.
+//   - The vanilla template's bridge import from the CDN (public/app.js).
+//   - The template's config files (TEMPLATE_CONFIG_FILES), only when the app's copy is one the template has shipped
+//     (src/template-history.json): the developer never edited it. An edited one is left as is, with a diff to look at.
+//   - The CLI's part of AGENTS.md and CLAUDE.md's import of it (agents.mjs), also for apps without a template.
+//   - With --channel latest|dev, first moves the bridge and CLI to that release channel (see channel.mjs).
+// Without --yes it only shows what would change.
+import { spawnSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { readFile, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { describeAgentFile, isAgentChange, planAgentFiles, writeAgentFiles } from './agents.mjs';
+import { appChannel, applyChannel, DEV_CHANNEL_NOTE, HAWK_PACKAGES, isDevSpec, npmLatest, planChannel, UI, writeCdnFiles } from './channel.mjs';
+
+/**
+ * Packages a template gained after apps were made from it, which those apps should have too: `upgrade` adds them (the
+ * app's code still has to start using them: `notes`). Only when the template has them.
+ */
+export const ADDED_PACKAGES = {
+    [UI]: {
+        'next-mui': [
+            'The UI kit gives the app Spark\'s current theme (in the host\'s colors and mode), the provider and shared components.',
+            'Start using it: in src/app/providers.tsx render <HawkAppProvider> (from @bridgeline-digital/hawk-app-ui) instead of',
+            '  the ThemeProvider, read the app with useHawk() instead of src/lib/useHawkApp.ts, and import',
+            '  @bridgeline-digital/hawk-app-ui/fonts in src/app/layout.tsx. Then delete src/theme.ts and src/lib/useHawkApp.ts,',
+            '  and @fontsource/source-sans-3 if nothing else uses it. See the kit\'s README for its components.',
+        ],
+        // react, preact, next: the stylesheet and the custom elements.
+        default: [
+            'The UI kit gives the app Spark\'s look (in the host\'s colors and mode): a stylesheet with hawk-* classes, and elements',
+            '  (<hawk-kpi>, <hawk-data-table>, <hawk-bar-list>, <hawk-column-chart>).',
+            'Start using it: import \'@bridgeline-digital/hawk-app-ui/css\' and \'@bridgeline-digital/hawk-app-ui/elements\' where',
+            '  the app starts (src/main.tsx; Next: the css in src/app/layout.tsx, the elements in a client component), copy',
+            '  src/hawk-elements.d.ts from a new app for the elements\' JSX types, and move your own styles to the hawk-* classes.',
+            '  See the kit\'s README ("Without React and MUI").',
+        ],
+    },
+};
+
+/** What to change in the app's code to start using an added package, for its template. */
+const notesFor = (notes, template) => (Array.isArray(notes) ? notes : (notes[template] ?? notes.default ?? []));
+
+/** Template files `upgrade` may replace: build and compiler configuration, never app code. */
+export const TEMPLATE_CONFIG_FILES = ['next.config.ts', 'vite.config.ts', 'tsconfig.json'];
+
+const TEMPLATES_DIR = fileURLToPath(new URL('../templates', import.meta.url));
+const HISTORY_FILE = fileURLToPath(new URL('./template-history.json', import.meta.url));
+const BRIDGE = '@bridgeline-digital/hawk-app-bridge';
+/** The vanilla template's CDN imports (the bridge, the UI kit), by minor version. */
+const CDN_IMPORT = /(hawk-app-(?:bridge|ui)@)(\d+\.\d+)(\/)/;
+
+/** Line endings and trailing blank lines don't count as an edit. */
+export function normalizeText(text) {
+    return String(text).replace(/\r\n/g, '\n').replace(/\s+$/, '') + '\n';
+}
+
+const cliVersion = () => JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version;
+
+/** A template file as `hawk-app create` writes it for this app. */
+function render(text, { slug, name }) {
+    const values = { __SLUG__: slug, __NAME__: name, __CLI_VERSION__: cliVersion() };
+    return text.replace(/__SLUG__|__NAME__|__CLI_VERSION__/g, (m) => values[m] ?? m);
+}
+
+/** The lowest version a range allows (`^16.4.0`, `~1.2.3`, `>=2.0.0`, `16.4.0`), or null when it isn't a plain range. */
+export function minVersion(range) {
+    const text = String(range ?? '').trim();
+    if (!text || /[|*xX]|\s-\s|^(file|git|http|https|link|workspace|npm):/.test(text)) return null;
+    const match = /^(?:\^|~|>=|=)?\s*v?(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?$/.exec(text);
+    return match ? { parts: match.slice(1, 4).map(Number), pre: match[4] ?? null } : null;
+}
+
+/** Semver order of two minVersion results (a prerelease sorts before its release). */
+export function compareVersions(a, b) {
+    for (let i = 0; i < 3; i++) if (a.parts[i] !== b.parts[i]) return a.parts[i] - b.parts[i];
+    if (a.pre === b.pre) return 0;
+    if (a.pre === null) return 1;
+    if (b.pre === null) return -1;
+    return a.pre < b.pre ? -1 : 1;
+}
+
+/** Which template an app comes from: hawk-app.json's `template`, else a guess from its dependencies. */
+export function detectTemplate(dir, manifest) {
+    if (manifest?.template) return { template: manifest.template, source: 'hawk-app.json' };
+    const pkgFile = join(dir, 'package.json');
+    const pkg = existsSync(pkgFile) ? JSON.parse(readFileSync(pkgFile, 'utf8')) : {};
+    const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+    const guessed = deps.next
+        ? deps['@mui/material'] ? 'next-mui' : 'next'
+        : deps.vite && deps.preact
+          ? 'preact'
+          : deps.vite && deps.react
+            ? 'react'
+            : existsSync(join(dir, 'public', 'app.js')) && CDN_IMPORT.test(readFileSync(join(dir, 'public', 'app.js'), 'utf8'))
+              ? 'vanilla'
+              : null;
+    return guessed ? { template: guessed, source: 'guessed from the dependencies' } : null;
+}
+
+/**
+ * What `upgrade` would change: { template, source, dependencies: [{ name, section, from, to }], upToDate: [names],
+ * cdn: { from, to } | null, files: [{ file, state: 'current' | 'replace' | 'edited' | 'missing', diff? }] }.
+ */
+export function planUpgrade({ dir, manifest, template: forced }) {
+    const found = forced ? { template: forced, source: '--template' } : detectTemplate(dir, manifest);
+    if (!found) throw new Error("Can't tell which template this app comes from. Pass --template <react|preact|next|next-mui|vanilla>.");
+    const { template, source } = found;
+    const templateDir = join(TEMPLATES_DIR, template);
+    if (!existsSync(templateDir)) throw new Error(`Unknown template "${template}". Choose one of: react, preact, next, next-mui, vanilla.`);
+    const values = { slug: manifest?.slug ?? '', name: manifest?.name ?? '' };
+
+    // Dependencies the template pins, raised to the template's version.
+    const templatePkg = JSON.parse(render(readFileSync(join(templateDir, 'package.json'), 'utf8'), values));
+    const pkgFile = join(dir, 'package.json');
+    const pkg = existsSync(pkgFile) ? JSON.parse(readFileSync(pkgFile, 'utf8')) : {};
+    const dependencies = [];
+    const upToDate = [];
+    for (const [name, to] of Object.entries({ ...templatePkg.dependencies, ...templatePkg.devDependencies })) {
+        const section = ['dependencies', 'devDependencies'].find((s) => pkg[s]?.[name] !== undefined);
+        if (!section) continue;
+        const from = pkg[section][name];
+        // The bridge and CLI on dev builds follow the dev channel, not the template (`upgrade --channel latest` moves them).
+        if (HAWK_PACKAGES.includes(name) && isDevSpec(from)) continue;
+        const [have, want] = [minVersion(from), minVersion(to)];
+        if (!have || !want) continue;
+        if (compareVersions(have, want) < 0) dependencies.push({ name, section, from, to, major: have.parts[0] !== want.parts[0] });
+        else upToDate.push(name);
+    }
+
+    // Packages the template gained since: added, with what to change in the app. A Hawk package joins an app whose
+    // bridge is on a dev build on the dev channel too: the template's release wouldn't install next to that bridge (its
+    // peer range). Only the bridge counts: a CLI pinned to a prerelease (an app made by a dev CLI) doesn't clash.
+    const additions = [];
+    const devBridge = isDevSpec(pkg.dependencies?.[BRIDGE] ?? pkg.devDependencies?.[BRIDGE]);
+    for (const [name, notes] of Object.entries(ADDED_PACKAGES)) {
+        const pinned = templatePkg.dependencies?.[name];
+        if (!pinned || pkg.dependencies?.[name] !== undefined || pkg.devDependencies?.[name] !== undefined) continue;
+        additions.push({ name, section: 'dependencies', to: devBridge && HAWK_PACKAGES.includes(name) ? 'dev' : pinned, notes: notesFor(notes, template) });
+    }
+
+    // The vanilla template's bridge comes from the CDN, by minor version.
+    let cdn = null;
+    const appJs = join(dir, 'public', 'app.js');
+    const templateAppJs = join(templateDir, 'public', 'app.js');
+    if (existsSync(appJs) && existsSync(templateAppJs)) {
+        const [have, want] = [CDN_IMPORT.exec(readFileSync(appJs, 'utf8'))?.[2], CDN_IMPORT.exec(readFileSync(templateAppJs, 'utf8'))?.[2]];
+        if (have && want && compareVersions(minVersion(`${have}.0`), minVersion(`${want}.0`)) < 0) cdn = { from: have, to: want };
+    }
+
+    // Config files: replaced only when unedited (one of the versions the template has shipped).
+    const history = JSON.parse(readFileSync(HISTORY_FILE, 'utf8'));
+    const files = [];
+    for (const file of TEMPLATE_CONFIG_FILES) {
+        const templateFile = join(templateDir, file);
+        if (!existsSync(templateFile)) continue;
+        const current = normalizeText(render(readFileSync(templateFile, 'utf8'), values));
+        const appFile = join(dir, file);
+        if (!existsSync(appFile)) {
+            files.push({ file, state: 'missing' });
+            continue;
+        }
+        const mine = normalizeText(readFileSync(appFile, 'utf8'));
+        if (mine === current) {
+            files.push({ file, state: 'current' });
+        } else if ((history[`${template}/${file}`] ?? []).some((shipped) => normalizeText(render(shipped, values)) === mine)) {
+            files.push({ file, state: 'replace', content: current });
+        } else {
+            files.push({ file, state: 'edited', diff: lineDiff(mine, current) });
+        }
+    }
+
+    return { template, source, dependencies, additions, upToDate, cdn, files, recordTemplate: !manifest?.template };
+}
+
+/** Whether the plan changes anything. */
+export const hasChanges = (plan) => plan.dependencies.length > 0 || plan.additions.length > 0 || plan.cdn !== null || plan.files.some((f) => f.state === 'replace') || plan.recordTemplate;
+
+/** A short unified-style diff (- the app's lines, + the template's), for an edited config file. */
+export function lineDiff(before, after, maxLines = 40) {
+    const a = before.replace(/\n$/, '').split('\n');
+    const b = after.replace(/\n$/, '').split('\n');
+    // Longest common subsequence: small files only.
+    const lcs = Array.from({ length: a.length + 1 }, () => new Array(b.length + 1).fill(0));
+    for (let i = a.length - 1; i >= 0; i--) for (let j = b.length - 1; j >= 0; j--) lcs[i][j] = a[i] === b[j] ? lcs[i + 1][j + 1] + 1 : Math.max(lcs[i + 1][j], lcs[i][j + 1]);
+    const out = [];
+    let i = 0;
+    let j = 0;
+    while (i < a.length || j < b.length) {
+        if (i < a.length && j < b.length && a[i] === b[j]) {
+            i++;
+            j++;
+        } else if (j < b.length && (i === a.length || lcs[i][j + 1] >= lcs[i + 1][j])) {
+            out.push(`+ ${b[j++]}`);
+        } else {
+            out.push(`- ${a[i++]}`);
+        }
+    }
+    return out.length > maxLines ? [...out.slice(0, maxLines), `  … ${out.length - maxLines} more lines`] : out;
+}
+
+/** The one-line hint `hawk-app deploy` shows when the app's dependencies are behind its template; null when they aren't. */
+export function upgradeHint(dir, manifest) {
+    const plan = planUpgrade({ dir, manifest });
+    const behind = plan.dependencies.map((d) => `${d.name} ${d.from} → ${d.to}`);
+    if (plan.cdn) behind.push(`bridge and UI kit ${plan.cdn.from} → ${plan.cdn.to} (CDN)`);
+    for (const a of plan.additions) behind.push(`${a.name} (new)`);
+    if (!behind.length) return null;
+    const shown = behind.slice(0, 3).join(', ') + (behind.length > 3 ? `, +${behind.length - 3} more` : '');
+    return `! This app is behind the ${plan.template} template (${shown}). See what would change: npx hawk-app upgrade`;
+}
+
+/**
+ * Runs `npm install` in `cwd`. With `packages` ([{ name, section, to }], a channel switch) it installs them by name
+ * (`npm install <name>@<to>`, `-D` for devDependencies): a plain install keeps what package-lock.json has whenever it
+ * satisfies the spec, and a dist-tag such as `dev` is satisfied by any version, so the packages would never move.
+ */
+export function npmInstall({ cwd, packages = [] }) {
+    const win = process.platform === 'win32';
+    for (const args of installArgs(packages, win)) {
+        const result = spawnSync('npm', args, { cwd, stdio: 'inherit', shell: win });
+        if (result.status !== 0) throw new Error('npm install failed. Fix it, then run `npm install` again.');
+    }
+}
+
+/**
+ * The `npm` runs that install `packages` by name (dependencies, then `-D` devDependencies), or one plain install. On
+ * Windows npm runs through cmd.exe, where `^` is an escape character: the specs are quoted so `^0.7.2` reaches npm.
+ */
+export function installArgs(packages, win = process.platform === 'win32') {
+    const base = ['install', '--no-audit', '--no-fund'];
+    const spec = ({ name, to }) => (win ? `"${name}@${to}"` : `${name}@${to}`);
+    const deps = packages.filter((p) => p.section === 'dependencies').map(spec);
+    const devDeps = packages.filter((p) => p.section === 'devDependencies').map(spec);
+    const runs = [];
+    if (deps.length) runs.push([...base, ...deps]);
+    if (devDeps.length) runs.push([...base, '-D', ...devDeps]);
+    return runs.length ? runs : [base];
+}
+
+/** `hawk-app upgrade [--yes] [--template <name>] [--no-install]`. */
+/**
+ * Moves the app's bridge and CLI to a release channel (`--channel`): `dev` follows the dev tag, `latest` the released
+ * versions (^ npm's latest). Shows the change; applies it with `yes`. Returns the state, 'none', 'pending' (not
+ * applied) or 'applied', and the packages moved (to install by name).
+ */
+async function switchChannel({ dir, channel, yes, log, latestVersion }) {
+    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 from = appChannel(pkg);
+    const plan = planChannel({ pkg, appJs, channel, latestVersion });
+    if (!plan.dependencies.length && !plan.cdn) {
+        log(`Channel: already on ${channel}.`);
+        return { state: 'none', packages: [] };
+    }
+    // Already on dev (a dev build, as npm writes it): `--channel dev` moves to the newest dev builds.
+    log(from === channel ? `Channel: ${channel}, to its newest builds` : `Channel: ${from ?? 'none'} → ${channel}`);
+    for (const d of plan.dependencies) log(`  ${d.name}: ${d.from} → ${d.to}`);
+    if (plan.cdn) log(`  public/app.js, index.html: the bridge and UI kit from the CDN @${plan.cdn.from} → @${plan.cdn.to}`);
+    if (!yes) return { state: 'pending', packages: [] };
+    applyChannel(plan, pkg, appJs);
+    if (plan.dependencies.length) await writeFile(pkgFile, JSON.stringify(pkg, null, 2) + '\n');
+    if (plan.cdn) await writeCdnFiles(dir, plan.cdn.to);
+    log(`✔ Moved to the ${channel} channel.`);
+    if (channel === 'dev') DEV_CHANNEL_NOTE.slice(0, 2).forEach((line) => log(`  ${line}`));
+    return { state: 'applied', packages: plan.dependencies };
+}
+
+export async function upgrade({ dir = process.cwd(), manifestFile = 'hawk-app.json', template, yes = false, install = true, runInstall = npmInstall, log = console.log, channel, latestVersion = npmLatest }) {
+    const { state: channelState, packages: channelPackages } = channel ? await switchChannel({ dir, channel, yes, log, latestVersion }) : { state: 'none', packages: [] };
+    const channelChanged = channelState === 'applied';
+    const applyHint = `\nNothing was changed. Run \`npx hawk-app upgrade${channel ? ` --channel ${channel}` : ''} --yes\` to apply this, then build, test and deploy.`;
+    const manifestPath = join(dir, manifestFile);
+    const manifest = existsSync(manifestPath) ? JSON.parse(await readFile(manifestPath, 'utf8')) : null;
+    // An app set up without a template (hawk-app init) still gets its AI assistant files refreshed.
+    const plan = template || detectTemplate(dir, manifest) ? planUpgrade({ dir, manifest, template }) : null;
+    if (!plan && !manifest) planUpgrade({ dir, manifest, template }); // throws: nothing to upgrade
+    const agents = manifest ? planAgentFiles(dir, { slug: manifest.slug, name: manifest.name, template: plan?.template }) : [];
+    const agentsChanged = agents.some(isAgentChange);
+
+    if (plan) {
+        logTemplatePlan(plan, manifest, manifestFile, log);
+    } else {
+        log('Template: none (this app was set up without one; pass --template <react|preact|next|next-mui|vanilla> if it follows one).');
+    }
+    for (const f of agents) {
+        const line = describeAgentFile(f);
+        if (line) log(`  ${line}`);
+    }
+
+    const templateChanged = !!plan && hasChanges(plan);
+    if (!templateChanged && !agentsChanged) {
+        log(plan ? `✔ Up to date with the ${plan.template} template.` : '✔ Up to date.');
+        if (channelState === 'pending') log(applyHint);
+        if (channelChanged && install) {
+            log('  Installing…');
+            await runInstall({ cwd: dir, packages: channelPackages });
+        }
+        return { plan, agents, applied: channelChanged };
+    }
+    if (!yes) {
+        log(applyHint);
+        return { plan, agents, applied: false };
+    }
+
+    if (templateChanged) await applyTemplatePlan(plan, { dir, manifest, manifestPath, manifestFile, log });
+    if (agentsChanged) {
+        const written = await writeAgentFiles(dir, agents);
+        log(`✔ Updated ${written.join(', ')}.`);
+    }
+
+    if (install && (channelChanged || (templateChanged && (plan.dependencies.length || plan.additions.length || plan.cdn)))) {
+        log('  Installing…');
+        await runInstall({ cwd: dir, packages: channelPackages });
+    }
+    if (templateChanged || channelChanged) log('  Next: build and test the app (npm run build, npm run dev), then deploy.');
+    return { plan, agents, applied: true };
+}
+
+function logTemplatePlan(plan, manifest, manifestFile, log) {
+    log(`Template: ${plan.template} (${plan.source}${plan.source === 'guessed from the dependencies' ? '; pass --template to choose another' : ''})`);
+    if (plan.dependencies.length || plan.additions.length || plan.cdn) {
+        log('Dependencies:');
+        const width = Math.max(...plan.dependencies.map((d) => d.name.length), ...plan.additions.map((a) => a.name.length), 6);
+        for (const d of plan.dependencies) log(`  ${d.name.padEnd(width)}  ${d.from} → ${d.to}${d.major ? '  (major version: check its migration guide)' : ''}`);
+        for (const a of plan.additions) log(`  ${a.name.padEnd(width)}  (new) ${a.to}`);
+        if (plan.cdn) log(`  ${'bridge and UI kit (CDN, public/)'.padEnd(width)}  @${plan.cdn.from} → @${plan.cdn.to}`);
+        const mui = plan.dependencies.find((d) => d.major && d.name === '@mui/material');
+        if (mui) log(`  Material UI ${mui.from} → ${mui.to} is a major upgrade: see https://mui.com/material-ui/migration/ for what changed.`);
+        for (const a of plan.additions) for (const line of a.notes) log(`  ${line}`);
+    } else {
+        log('Dependencies: up to date with the template.');
+    }
+    if (plan.recordTemplate && manifest) log(`  ${manifestFile}: records "template": "${plan.template}", so later upgrades don't guess.`);
+    for (const f of plan.files) {
+        if (f.state === 'replace') log(`  ${f.file}: unchanged since the template created it, so it's replaced with the template's current version.`);
+        if (f.state === 'missing') log(`  ${f.file}: not in this app (not added).`);
+        if (f.state === 'edited') {
+            log(`  ${f.file}: you've changed it, so it's left alone. The template's current version differs (- yours, + template):`);
+            for (const line of f.diff) log(`      ${line}`);
+        }
+    }
+}
+
+async function applyTemplatePlan(plan, { dir, manifest, manifestPath, manifestFile, log }) {
+    // package.json: only the version strings change, so its formatting stays.
+    if (plan.dependencies.length) {
+        const pkgFile = join(dir, 'package.json');
+        let text = await readFile(pkgFile, 'utf8');
+        for (const d of plan.dependencies) {
+            const pattern = new RegExp(`("${d.name.replace(/[/.@-]/g, '\\$&')}"\\s*:\\s*")([^"]*)(")`);
+            text = text.replace(pattern, `$1${d.to}$3`);
+        }
+        await writeFile(pkgFile, text);
+    }
+    if (plan.additions.length) {
+        const pkgFile = join(dir, 'package.json');
+        await writeFile(pkgFile, addDependencies(await readFile(pkgFile, 'utf8'), plan.additions));
+    }
+    if (plan.cdn) await writeCdnFiles(dir, plan.cdn.to);
+    for (const f of plan.files.filter((x) => x.state === 'replace')) {
+        const appFile = join(dir, f.file);
+        const eol = (await readFile(appFile, 'utf8')).includes('\r\n') ? '\r\n' : '\n';
+        await writeFile(appFile, f.content.replace(/\n/g, eol));
+    }
+    if (plan.recordTemplate && manifest) {
+        await writeFile(manifestPath, recordTemplate(await readFile(manifestPath, 'utf8'), plan.template));
+    }
+    log(`✔ Upgraded to the ${plan.template} template.${plan.recordTemplate && manifest ? ` Recorded "template": "${plan.template}" in ${manifestFile}.` : ''}`);
+}
+
+/**
+ * package.json with `additions` ([{ name, section, to }]) as the first entries of their section, in its indentation and
+ * line endings (the section is created when missing; then the JSON is rewritten).
+ */
+export function addDependencies(text, additions) {
+    let out = text;
+    for (const { name, section, to } of additions) {
+        const match = new RegExp(`("${section}"\\s*:\\s*\\{)(\\r?\\n)([ \\t]*)`).exec(out);
+        if (match) {
+            const [all, open, eol, indent] = match;
+            out = out.slice(0, match.index) + `${open}${eol}${indent}"${name}": "${to}",${eol}${indent}` + out.slice(match.index + all.length);
+        } else {
+            const pkg = JSON.parse(out);
+            pkg[section] = { [name]: to, ...pkg[section] };
+            out = JSON.stringify(pkg, null, 2) + '\n';
+        }
+    }
+    return out;
+}
+
+/** hawk-app.json with `"template"` added after `"slug"`, keeping its formatting (falls back to rewriting the JSON). */
+export function recordTemplate(text, template) {
+    const match = /^([ \t]*)"slug"\s*:\s*"[^"]*",?[ \t]*\r?\n/m.exec(text);
+    if (match && match[0].trimEnd().endsWith(',')) {
+        const eol = match[0].endsWith('\r\n') ? '\r\n' : '\n';
+        return text.slice(0, match.index + match[0].length) + `${match[1]}"template": "${template}",${eol}` + text.slice(match.index + match[0].length);
+    }
+    return JSON.stringify({ ...JSON.parse(text), template }, null, 2) + '\n';
+}

package/src/versions.mjs

@@ -0,0 +1,102 @@
+import { DEFAULT_ALIAS, checkAlias } from './aliases.mjs';
+
+/**
+ * Versions, aliases and "why": the developer's view of who sees which version.
+ *   hawk-app versions               each version with its status and the aliases on it
+ *   hawk-app alias set <name> <v>   point an alias at a version that isn't approved (staff only)
+ *   hawk-app alias delete <name>    delete an alias of yours (not approved, no clients on it)
+ *   hawk-app why <client>           what a client's users see, and why
+ */
+
+const STATUS_NOTE = {
+    draft: 'staff only',
+    waiting: 'staff only, waiting for approval',
+    rejected: 'staff only',
+    approved: '',
+};
+
+/** `hawk-app versions`: newest first, with status and aliases. */
+export async function versionsCommand({ client, manifest, log = console.log }) {
+    const { versions = [] } = await client.listVersions(manifest.slug);
+    if (!versions.length) {
+        log(`${manifest.slug} has no versions yet. Deploy one with \`npm run app:deploy\`.`);
+        return 0;
+    }
+    log(`${manifest.slug}: versions, newest first`);
+    for (const v of versions) {
+        const aliases = v.aliases?.length ? `  ${v.aliases.join(', ')}` : '';
+        const note = STATUS_NOTE[v.status] ? `  (${STATUS_NOTE[v.status]})` : '';
+        const branch = v.deployedFor ? `  deployed for ${v.deployedFor}` : '';
+        log(`  v${String(v.version).padEnd(4)} ${v.status.padEnd(9)}${aliases}${note}${branch}`);
+        if (v.status === 'rejected' && v.rejectedReason) log(`         rejected: ${v.rejectedReason}`);
+    }
+    log('Clients get the version of their alias (default without one); users see it only when it\'s approved.');
+    return 0;
+}
+
+/** `hawk-app alias set <name> <version>` / `hawk-app alias delete <name>`. */
+export async function aliasCommand({ client, manifest, sub, args = [], log = console.log }) {
+    const usage = 'Usage:\n  hawk-app alias set <name> <version>   (e.g. hawk-app alias set staging 15)\n  hawk-app alias delete <name>';
+    const slug = manifest.slug;
+    switch (sub) {
+        case 'set': {
+            const name = checkAlias(args[0], { flag: 'alias set' });
+            const version = Number(String(args[1] ?? '').replace(/^v/, ''));
+            if (!Number.isInteger(version) || version < 1) throw new Error(usage);
+            await client.setAlias(slug, name, version);
+            log(`✔ ${name} → v${version}. Clients on ${name}: only Bridgeline staff in them see it until v${version} is approved.`);
+            return 0;
+        }
+        case 'delete': {
+            const name = checkAlias(args[0], { flag: 'alias delete' });
+            await client.deleteAlias(slug, name);
+            log(`✔ Deleted ${name}.`);
+            return 0;
+        }
+        default:
+            throw new Error(usage);
+    }
+}
+
+/**
+ * `hawk-app why <client>`: what the client's users see of the app, and why (the same rules as the platform's catalog):
+ * the app's state and visibility, the client list, the client's alias and that version's status.
+ */
+export async function whyCommand({ client, manifest, clientId, log = console.log }) {
+    if (!clientId) throw new Error('Usage: hawk-app why <client id>   (e.g. hawk-app why e3141)');
+    const app = await client.status(manifest.slug);
+    const row = (app.clients ?? []).find((c) => c.id === clientId);
+    const aliasName = row?.alias ?? DEFAULT_ALIAS;
+    const alias = (app.aliases ?? []).find((a) => a.name === aliasName);
+    const say = (verdict, ...reasons) => {
+        log(`${clientId}: ${verdict}`);
+        for (const reason of reasons) log(`  - ${reason}`);
+        return 0;
+    };
+
+    if (app.adminLocked) return say('nobody sees the app', 'an administrator locked it.');
+    if (app.status === 'Disabled') return say('nobody sees the app', 'it is disabled.');
+    if (app.visibility === 'internal') return say('its users don\'t see the app; Bridgeline staff do', 'visibility is "internal": Bridgeline staff only.');
+    if (app.visibility === 'allowList' && !row?.enabled) {
+        return say("its users don't see the app", `it isn't on the app's client list (visibility "allowList"). Add it: hawk-app clients add ${clientId}`);
+    }
+    if (app.visibility === 'all' && row && !row.enabled) {
+        return say("its users don't see the app", `it's excluded (visibility "all"). Add it back: hawk-app clients add ${clientId}`);
+    }
+    const listed = app.visibility === 'all' ? 'visibility "all": every client that isn\'t excluded' : 'it\'s on the app\'s client list';
+    if (aliasName === DEFAULT_ALIAS) {
+        if (!app.liveVersion || app.status !== 'Live') {
+            return say("its users don't see the app yet", listed, `it follows ${DEFAULT_ALIAS}, and nothing is released to everyone yet: Bridgeline staff in it see the newest version.`);
+        }
+        return say(`its users see v${app.liveVersion}`, listed, `it follows ${DEFAULT_ALIAS} (the version released to everyone).`);
+    }
+    if (!alias) return say('its users see the default version', listed, `its alias "${aliasName}" no longer exists, so it follows ${DEFAULT_ALIAS}.`);
+    if (alias.status !== 'approved') {
+        return say(
+            `its users don't see the app; Bridgeline staff in it see v${alias.version}`,
+            listed,
+            `it's on ${aliasName}, which points at v${alias.version}: ${alias.status ?? 'draft'}, not approved yet.`,
+        );
+    }
+    return say(`its users see v${alias.version}`, listed, `it's on ${aliasName}, which points at v${alias.version} (approved).`);
+}

package/templates/next/next.config.ts

@@ -0,0 +1,13 @@
+import type { NextConfig } from 'next';
+
+// Hawk Apps are static files on the apps CDN, one folder per deploy (/<slug>/v<n>/): static export, no server
+// features (no SSR, API routes or middleware). All data comes through the bridge.
+// `hawk-app deploy` builds with HAWK_APP_BASE_PATH=/<slug>/v<n>; local dev uses /<slug>.
+const nextConfig: NextConfig = {
+    output: 'export',
+    basePath: process.env.HAWK_APP_BASE_PATH ?? '/__SLUG__',
+    trailingSlash: true,
+    images: { unoptimized: true },
+};
+
+export default nextConfig;

package/templates/next/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "__SLUG__",
+  "version": "0.1.0",
+  "private": true,
+  "scripts": {
+    "dev": "next dev -p 3100",
+    "build": "next build",
+    "app:dev": "hawk-app dev",
+    "app:deploy": "hawk-app deploy",
+    "app:audit": "npm audit --omit=dev --audit-level=high"
+  },
+  "dependencies": {
+    "@bridgeline-digital/hawk-app-bridge": "^0.1.0",
+    "@bridgeline-digital/hawk-app-ui": "^0.1.0",
+    "next": "^16.4.0",
+    "react": "^19.1.0",
+    "react-dom": "^19.1.0"
+  },
+  "devDependencies": {
+    "@bridgeline-digital/hawk-app-cli": "^__CLI_VERSION__",
+    "@types/node": "^20",
+    "@types/react": "^19.1.0",
+    "@types/react-dom": "^19.1.0",
+    "typescript": "^5.6.0"
+  }
+}

package/templates/next/src/app/globals.css

@@ -0,0 +1,5 @@
+/*
+ * Your app's own styles. Spark's look comes from the UI kit's stylesheet (imported in layout.tsx): its hawk-* classes
+ * (hawk-section, hawk-button, hawk-notice, hawk-table, …) and --hawk-ui-* variables, which follow the host's colors
+ * and light or dark mode. Use those before adding your own.
+ */

package/templates/next/src/app/layout.tsx

@@ -0,0 +1,14 @@
+import type { Metadata } from 'next';
+// The UI kit's stylesheet: Spark's look (with Montserrat), in the host's colors and mode.
+import '@bridgeline-digital/hawk-app-ui/css';
+import './globals.css';
+
+export const metadata: Metadata = { title: '__NAME__' };
+
+export default function RootLayout({ children }: Readonly<{ children: React.ReactNode }>) {
+    return (
+        <html lang="en">
+            <body>{children}</body>
+        </html>
+    );
+}