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

package/src/upgrade.mjs

@@ -1,406 +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';
-}
+// `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';
+}