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

package/src/accessibility.mjs

@@ -0,0 +1,105 @@
+// The accessibility check: axe-core (the standard WCAG rules engine) over the built HTML pages, in jsdom, before a
+// version is completed. `deploy` sends the result with the version for the approvers' review checks, and
+// `validate --build` prints it. It sees each page's HTML as built (what a static export prerenders), not what the app
+// draws later in the browser, and no layout (so no color contrast): it catches missing labels, alt text, landmarks,
+// heading order, lang, duplicate ids and the like.
+import { readdir, readFile } from 'node:fs/promises';
+import { join, relative, sep } from 'node:path';
+
+/** At most this many pages are checked (the first ones by path), so a big build stays quick. */
+export const MAX_PAGES = 10;
+/** At most this many rules are reported, the worst first. */
+export const MAX_RULES = 10;
+const IMPACTS = ['critical', 'serious', 'moderate', 'minor'];
+// Pages that are only there for the static host, not for users.
+const SKIPPED = /(^|\/)(404|_not-found)(\/index)?\.html?$/i;
+
+async function htmlFiles(folder) {
+    const found = [];
+    async function walk(current) {
+        for (const entry of await readdir(current, { withFileTypes: true })) {
+            if (entry.name.startsWith('.') || entry.name === 'node_modules') continue;
+            const full = join(current, entry.name);
+            if (entry.isDirectory()) await walk(full);
+            else if (/\.html?$/i.test(entry.name)) found.push(relative(folder, full).split(sep).join('/'));
+        }
+    }
+    await walk(folder);
+    return found.filter((file) => !SKIPPED.test(file)).sort();
+}
+
+/**
+ * Runs axe over the built pages in `folder`: { status: 'checked', pages, critical, serious, moderate, minor, rules:
+ * [{ id, impact, count, help }] } (count: elements across pages), or { status: 'not_checked', reason }. Never throws.
+ */
+export async function checkAccessibility(folder, { maxPages = MAX_PAGES } = {}) {
+    let files;
+    try {
+        files = await htmlFiles(folder);
+    } catch {
+        return { status: 'not_checked', reason: 'the build folder could not be read' };
+    }
+    if (!files.length) return { status: 'not_checked', reason: 'no HTML pages in the build' };
+
+    let JSDOM, axeSource;
+    try {
+        ({ JSDOM } = await import('jsdom'));
+        axeSource = (await import('axe-core')).default.source;
+    } catch {
+        return { status: 'not_checked', reason: 'axe-core or jsdom is not installed with the CLI' };
+    }
+
+    const counts = { critical: 0, serious: 0, moderate: 0, minor: 0 };
+    const rules = new Map();
+    const pages = files.slice(0, maxPages);
+    try {
+        for (const file of pages) {
+            // The page's own scripts never run ('outside-only'): only axe, injected below.
+            const dom = new JSDOM(await readFile(join(folder, file), 'utf8'), { runScripts: 'outside-only', pretendToBeVisual: true });
+            try {
+                dom.window.eval(axeSource);
+                const result = await dom.window.axe.run(dom.window.document, {
+                    runOnly: { type: 'tag', values: ['wcag2a', 'wcag2aa', 'wcag21a', 'wcag21aa', 'best-practice'] },
+                    // Needs layout, which jsdom doesn't have.
+                    rules: { 'color-contrast': { enabled: false } },
+                    resultTypes: ['violations'],
+                });
+                for (const violation of result.violations) {
+                    const impact = IMPACTS.includes(violation.impact) ? violation.impact : 'minor';
+                    counts[impact] += violation.nodes.length;
+                    const rule = rules.get(violation.id) ?? { id: violation.id, impact, count: 0, help: String(violation.help ?? '').slice(0, 200) };
+                    rule.count += violation.nodes.length;
+                    rules.set(violation.id, rule);
+                }
+            } finally {
+                dom.window.close();
+            }
+        }
+    } catch (error) {
+        return { status: 'not_checked', reason: `axe failed: ${String(error?.message ?? error).slice(0, 120)}` };
+    }
+    const worst = [...rules.values()]
+        .sort((a, b) => IMPACTS.indexOf(a.impact) - IMPACTS.indexOf(b.impact) || b.count - a.count)
+        .slice(0, MAX_RULES);
+    return { status: 'checked', pages: pages.length, ...counts, rules: worst };
+}
+
+/** One line for the terminal, e.g. "2 serious, 1 moderate in 3 pages (label, image-alt)". */
+export function describeAccessibility(report) {
+    if (report.status !== 'checked') return `not checked: ${report.reason}`;
+    const found = IMPACTS.filter((impact) => report[impact]).map((impact) => `${report[impact]} ${impact}`);
+    const pages = `${report.pages} page${report.pages === 1 ? '' : 's'}`;
+    if (!found.length) return `no issues found in ${pages} (axe)`;
+    return `${found.join(', ')} in ${pages} (${report.rules.map((r) => r.id).join(', ')})`;
+}
+
+/** Findings worth fixing before review: critical and serious issues, one line each. */
+export function accessibilityWarnings(report) {
+    if (report.status !== 'checked' || report.critical + report.serious === 0) return [];
+    const worst = report.rules.filter((r) => r.impact === 'critical' || r.impact === 'serious');
+    return [
+        `Accessibility: ${describeAccessibility(report)}. ${report.critical ? 'Critical issues fail the review check (approvers can only force approve). ' : ''}Fix: ${worst
+            .map((r) => `${r.id} (${r.count}): ${r.help}`)
+            .join('; ')}.`,
+    ];
+}

package/src/agents.mjs

@@ -0,0 +1,145 @@
+// Instructions for AI coding assistants, written into each app: AGENTS.md (read by Copilot, Cursor, Codex and others),
+// a CLAUDE.md that imports it (Claude Code), and the CLI's MCP server (`hawk-app mcp`) in .mcp.json (Claude Code) and
+// .vscode/mcp.json (VS Code / Copilot). The CLI owns the part of AGENTS.md between its markers and refreshes
+// it with `hawk-app upgrade`; anything outside the markers is the developer's. Sources: ../agents/AGENTS.md plus one
+// project section per template (../agents/project/), or custom.md for an app set up with `hawk-app init`.
+import { existsSync, readFileSync } from 'node:fs';
+import { mkdir, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const AGENTS_DIR = fileURLToPath(new URL('../agents', import.meta.url));
+const START = '<!-- hawk-app:start: written by the Hawk Apps CLI and refreshed by `npx hawk-app upgrade`. Add your own notes outside these markers. -->';
+const END = '<!-- hawk-app:end -->';
+const BLOCK = /<!-- hawk-app:start[^]*?<!-- hawk-app:end -->/;
+const CLAUDE_IMPORT = '@AGENTS.md';
+
+/**
+ * The MCP server (`hawk-app mcp`) in each assistant's settings file, started with node from the app's own copy of the
+ * CLI (a dev dependency): no npx, which needs a shell wrapper on Windows. Claude Code starts it in the project folder.
+ */
+const CLI_BIN = 'node_modules/@bridgeline-digital/hawk-app-cli/bin/hawk-app.mjs';
+const MCP_CONFIGS = [
+    { file: '.mcp.json', key: 'mcpServers', entry: { command: 'node', args: [CLI_BIN, 'mcp'] } },
+    {
+        file: '.vscode/mcp.json',
+        key: 'servers',
+        entry: { type: 'stdio', command: 'node', args: [`\${workspaceFolder}/${CLI_BIN}`, 'mcp'], cwd: '${workspaceFolder}' },
+    },
+];
+const MCP_SERVER = 'hawk-apps';
+
+/** An assistant's MCP settings with the hawk-apps server: created, added to the developer's own, or left as is. */
+function planMcpConfig(dir, { file, key, entry }) {
+    const full = join(dir, file);
+    if (!existsSync(full)) return { file, state: 'create', content: JSON.stringify({ [key]: { [MCP_SERVER]: entry } }, null, 2) + '\n' };
+    const text = readFileSync(full, 'utf8');
+    let config;
+    try {
+        config = JSON.parse(text);
+    } catch {
+        // JSON with comments (VS Code allows them) or broken: not ours to rewrite.
+        return { file, state: 'skipped', content: text };
+    }
+    if (config?.[key]?.[MCP_SERVER]) return { file, state: 'current', content: text };
+    const updated = { ...config, [key]: { ...config?.[key], [MCP_SERVER]: entry } };
+    return { file, state: 'append', content: JSON.stringify(updated, null, 2) + (text.includes('\r\n') ? '\r\n' : '\n') };
+}
+
+/** The project section each template uses; any other app gets custom.md. */
+const PROJECT_SECTIONS = { react: 'vite', preact: 'vite', next: 'next', 'next-mui': 'next-mui', vanilla: 'vanilla' };
+
+/** The CLI's block of AGENTS.md for an app, markers included (LF line endings). */
+export function renderAgents({ slug, name, template }) {
+    const read = (file) => readFileSync(join(AGENTS_DIR, file), 'utf8').replace(/\r\n/g, '\n').trim();
+    const project = read(`project/${PROJECT_SECTIONS[template] ?? 'custom'}.md`);
+    const values = { __SLUG__: slug || '<slug>', __NAME__: name || slug || 'This app', __TEMPLATE__: template ?? '' };
+    const body = read('AGENTS.md')
+        .replace('__PROJECT__', () => project)
+        .replace(/__SLUG__|__NAME__|__TEMPLATE__/g, (m) => values[m]);
+    return `${START}\n${body}\n${END}`;
+}
+
+/**
+ * What writing the assistant files would do: [{ file, state: 'create' | 'update' | 'append' | 'current', content }].
+ * AGENTS.md: created, its block replaced, or the block appended to the developer's own file. CLAUDE.md: created, or
+ * the import appended when it doesn't have it.
+ */
+export function planAgentFiles(dir, app) {
+    const block = renderAgents(app);
+    const files = [];
+
+    const agentsFile = join(dir, 'AGENTS.md');
+    if (!existsSync(agentsFile)) {
+        files.push({ file: 'AGENTS.md', state: 'create', content: block + '\n' });
+    } else {
+        const text = readFileSync(agentsFile, 'utf8');
+        const eol = text.includes('\r\n') ? '\r\n' : '\n';
+        const ours = block.replace(/\n/g, eol);
+        if (BLOCK.test(text)) {
+            const updated = text.replace(BLOCK, () => ours);
+            files.push({ file: 'AGENTS.md', state: updated === text ? 'current' : 'update', content: updated });
+        } else {
+            files.push({ file: 'AGENTS.md', state: 'append', content: `${text.replace(/\s*$/, '')}${eol}${eol}${ours}${eol}` });
+        }
+    }
+
+    for (const config of MCP_CONFIGS) files.push(planMcpConfig(dir, config));
+
+    const claudeFile = join(dir, 'CLAUDE.md');
+    if (!existsSync(claudeFile)) {
+        files.push({ file: 'CLAUDE.md', state: 'create', content: `${CLAUDE_IMPORT}\n` });
+    } else {
+        const text = readFileSync(claudeFile, 'utf8');
+        const eol = text.includes('\r\n') ? '\r\n' : '\n';
+        files.push(
+            /^@AGENTS\.md\s*$/m.test(text)
+                ? { file: 'CLAUDE.md', state: 'current', content: text }
+                : { file: 'CLAUDE.md', state: 'append', content: `${text.replace(/\s*$/, '')}${eol}${eol}${CLAUDE_IMPORT}${eol}` },
+        );
+    }
+    return files;
+}
+
+/** Writes what planAgentFiles found out of date; returns the files written. */
+/** Whether planAgentFiles found the file out of date (a file it leaves alone isn't). */
+export const isAgentChange = (f) => f.state !== 'current' && f.state !== 'skipped';
+
+export async function writeAgentFiles(dir, plan) {
+    const changed = plan.filter(isAgentChange);
+    for (const f of changed) {
+        await mkdir(dirname(join(dir, f.file)), { recursive: true });
+        await writeFile(join(dir, f.file), f.content);
+    }
+    return changed.map((f) => f.file);
+}
+
+/** One line per file that would change, for create, init and upgrade. */
+export function describeAgentFile({ file, state }) {
+    const mcp = file.endsWith('mcp.json');
+    switch (state) {
+        case 'create':
+            if (mcp) return `${file}: added (the hawk-app MCP server for ${file === '.mcp.json' ? 'Claude Code' : 'VS Code'}).`;
+            return file === 'AGENTS.md' ? 'AGENTS.md: added (instructions for AI coding assistants).' : `${file}: added (points Claude Code at AGENTS.md).`;
+        case 'update':
+            return `${file}: the CLI's part is refreshed (your notes outside its markers are kept).`;
+        case 'append':
+            if (mcp) return `${file}: the hawk-apps MCP server is added to your servers.`;
+            return file === 'AGENTS.md' ? "AGENTS.md: the CLI's part is added after your own." : `${file}: ${CLAUDE_IMPORT} is added, so Claude Code reads AGENTS.md.`;
+        case 'skipped':
+            return `${file}: not plain JSON (comments?), so left alone. Add the "${MCP_SERVER}" server yourself: see the CLI README.`;
+        default:
+            return null;
+    }
+}
+
+/** Plans and writes the assistant files for a new app (create, init), logging each one. */
+export async function addAgentFiles(dir, app, log) {
+    const plan = planAgentFiles(dir, app);
+    await writeAgentFiles(dir, plan);
+    for (const f of plan) {
+        const line = describeAgentFile(f);
+        if (line) log(`  ${line}`);
+    }
+    return plan.filter(isAgentChange).map((f) => f.file);
+}

package/src/aliases.mjs

@@ -0,0 +1,30 @@
+/** Same rules as the platform's alias names: lowercase letters, digits and single dashes, at most 40. */
+export const ALIAS_NAME = /^(?=.{1,40}$)[a-z0-9]+(-[a-z0-9]+)*$/;
+
+/** The built-in alias: the version released to everyone, for every client without another alias. */
+export const DEFAULT_ALIAS = 'default';
+
+/** Names no alias may take (old names for the default alias and for statuses, which come from the version). */
+const RESERVED = ['latest', 'live', 'draft'];
+
+/** The alias name, checked; `allowDefault` for putting a client back on the default. */
+export function checkAlias(name, { allowDefault = false, flag = '--alias' } = {}) {
+    if (typeof name !== 'string' || !name) throw new Error(`${flag} needs an alias name, e.g. ${flag} staging.`);
+    if (name === DEFAULT_ALIAS && allowDefault) return name;
+    if (name === DEFAULT_ALIAS || RESERVED.includes(name)) throw new Error(`"${name}" is reserved: pick another alias name, e.g. staging or review.`);
+    if (!ALIAS_NAME.test(name)) throw new Error(`"${name}" isn't a valid alias: lowercase letters, digits and single dashes (at most 40), e.g. staging.`);
+    return name;
+}
+
+/** "pilot v8 (3 clients)", "staging v9 (draft, 1 client)"; the default's count is null when the app is for every client. */
+export function describeAlias(alias) {
+    const clients = alias.clients === null || alias.clients === undefined ? 'all other clients' : `${alias.clients} client${alias.clients === 1 ? '' : 's'}`;
+    const status = alias.status && alias.status !== 'approved' ? `${alias.status}: Bridgeline staff only, ` : '';
+    return `${alias.name} v${alias.version ?? '?'} (${status}${clients})`;
+}
+
+/** "  [on pilot]", "  [on staging · draft: Bridgeline staff only]" after a client in lists; nothing on the default. */
+export function describeClientAlias(c) {
+    if (!c.alias) return '';
+    return c.aliasStatus && c.aliasStatus !== 'approved' ? `  [on ${c.alias} · ${c.aliasStatus}: Bridgeline staff only]` : `  [on ${c.alias}]`;
+}

package/src/app-icon.mjs

@@ -0,0 +1,82 @@
+import { existsSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import { extname, resolve } from 'node:path';
+
+// The app's icon: an .svg or .png file next to hawk-app.json ("icon": "icon.svg"). Deploy uploads it into every
+// version as _hawk/icon.svg or _hawk/icon.png, so it's reviewed and released with the version. Hosts draw an SVG in
+// their own text color (as a CSS mask: only its shape counts, not its colors) and show a PNG as is. Without one, hosts
+// show their default icon.
+
+/** A relative path to an .svg or .png file: letters, digits, . _ - and /, no "..", at most 200 characters. */
+export const ICON_PATH = /^(?!.*\.\.)[A-Za-z0-9_-][A-Za-z0-9_.-]*(\/[A-Za-z0-9_-][A-Za-z0-9_.-]*)*\.(svg|png)$/i;
+export const ICON_PATH_HINT = 'an .svg or .png file next to hawk-app.json, e.g. "icon.svg"';
+
+export const MAX_SVG_BYTES = 32 * 1024;
+export const MAX_PNG_BYTES = 256 * 1024;
+export const MIN_PNG_SIZE = 64;
+export const MAX_PNG_SIZE = 1024;
+
+/** The icon `create` and `init` add: a neutral app glyph (four rounded squares), one color, square. */
+export const DEFAULT_ICON_SVG = `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="currentColor">
+  <rect x="3" y="3" width="8" height="8" rx="2"/>
+  <rect x="13" y="3" width="8" height="8" rx="2"/>
+  <rect x="3" y="13" width="8" height="8" rx="2"/>
+  <rect x="13" y="13" width="8" height="8" rx="2"/>
+</svg>
+`;
+
+/** Where deploy puts the icon in a version: _hawk/icon.svg or _hawk/icon.png. */
+export function iconUploadPath(icon) {
+    return `_hawk/icon${extname(icon).toLowerCase()}`;
+}
+
+/**
+ * Checks the icon file hawk-app.json names (when it names one): there, the right type and size, square. Returns the
+ * file to upload ({ path: _hawk/icon.*, size, data }), with errors and warnings.
+ */
+export async function checkIcon(projectDir, icon) {
+    const errors = [];
+    const warnings = [];
+    if (icon === undefined || icon === null || icon === '') return { errors, warnings, file: null };
+    if (typeof icon !== 'string' || !ICON_PATH.test(icon)) {
+        return { errors: [`icon must be ${ICON_PATH_HINT}.`], warnings, file: null };
+    }
+    const full = resolve(projectDir, icon);
+    if (!existsSync(full)) {
+        return { errors: [`icon: ${icon} doesn't exist next to hawk-app.json. Add it, or leave "icon" out for the hosts' default icon.`], warnings, file: null };
+    }
+    const data = await readFile(full);
+    if (extname(icon).toLowerCase() === '.svg') {
+        if (data.length > MAX_SVG_BYTES) errors.push(`icon: ${icon} is ${Math.ceil(data.length / 1024)} KB; an SVG icon can be at most ${MAX_SVG_BYTES / 1024} KB.`);
+        const text = data.toString('utf8');
+        const root = /<svg\b[^>]*>/i.exec(text)?.[0];
+        if (!root) {
+            errors.push(`icon: ${icon} isn't an SVG (no <svg> element).`);
+        } else {
+            const box = /\bviewBox\s*=\s*["']\s*[-\d.]+[\s,]+[-\d.]+[\s,]+([\d.]+)[\s,]+([\d.]+)\s*["']/i.exec(root);
+            if (!box) warnings.push(`icon: ${icon} has no viewBox: hosts may draw it at the wrong size. Give it a square one, e.g. viewBox="0 0 24 24".`);
+            else if (Math.abs(Number(box[1]) - Number(box[2])) > 0.001) warnings.push(`icon: ${icon} isn't square (viewBox ${box[1]}×${box[2]}): hosts fit it in a square.`);
+        }
+        if (/<(image|foreignObject)\b/i.test(text)) {
+            warnings.push(`icon: ${icon} contains <image> or <foreignObject>: hosts draw only an SVG icon's shape, in their own color. For a picture, use a .png icon.`);
+        }
+    } else {
+        if (data.length > MAX_PNG_BYTES) errors.push(`icon: ${icon} is ${Math.ceil(data.length / 1024)} KB; a PNG icon can be at most ${MAX_PNG_BYTES / 1024} KB.`);
+        const size = pngSize(data);
+        if (!size) {
+            errors.push(`icon: ${icon} isn't a PNG.`);
+        } else if (size.width !== size.height) {
+            errors.push(`icon: ${icon} is ${size.width}×${size.height}; a PNG icon must be square.`);
+        } else if (size.width < MIN_PNG_SIZE || size.width > MAX_PNG_SIZE) {
+            errors.push(`icon: ${icon} is ${size.width}×${size.height}; a PNG icon must be ${MIN_PNG_SIZE}–${MAX_PNG_SIZE} px (256×256 is a good size).`);
+        }
+    }
+    return { errors, warnings, file: errors.length ? null : { path: iconUploadPath(icon), size: data.length, data } };
+}
+
+/** A PNG's width and height from its IHDR chunk; null when it isn't a PNG. */
+export function pngSize(data) {
+    const signature = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+    if (data.length < 24 || !data.subarray(0, 8).equals(signature) || data.toString('ascii', 12, 16) !== 'IHDR') return null;
+    return { width: data.readUInt32BE(16), height: data.readUInt32BE(20) };
+}

package/src/channel.mjs

@@ -0,0 +1,116 @@
+// Release channels of the Hawk Apps packages. `latest` (from main) is stable and matches the prod platform; `dev`
+// (prereleases from the dev branch, e.g. 0.7.0-dev.20261014…) has features that may need the dev platform.
+//   - `hawk-app create` from a dev CLI (npx …-cli@dev create) makes a dev app: the Hawk packages on the `dev` dist-tag
+//     (the vanilla template's CDN import too), so it gets the dev bridge, not the latest one the template pins.
+//   - `hawk-app upgrade --channel latest|dev` moves an app between channels.
+import { spawnSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { readFile, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+
+export const BRIDGE = '@bridgeline-digital/hawk-app-bridge';
+export const CLI = '@bridgeline-digital/hawk-app-cli';
+/** The UI kit (next-mui apps): released with the bridge and CLI, so it follows the same channel. */
+export const UI = '@bridgeline-digital/hawk-app-ui';
+export const HAWK_PACKAGES = [BRIDGE, UI, CLI];
+export const CHANNELS = ['latest', 'dev'];
+
+/**
+ * The vanilla template's imports from the CDN, the bridge and the UI kit (one version: they're released together): by
+ * minor (`@0.6/`) or by dist-tag (`@dev/`).
+ */
+export const CDN_BRIDGE = /(hawk-app-(?:bridge|ui)@)([0-9]+\.[0-9]+|dev)(\/)/;
+
+/** The vanilla template's files that load from the CDN: the bridge and the kit's elements (app.js), the kit's stylesheet (index.html). */
+export const CDN_FILES = [join('public', 'app.js'), join('public', 'index.html')];
+
+/** `text` with every CDN import of the bridge and the UI kit at `version` (a minor or a dist-tag). */
+export const pointCdn = (text, version) => text.replace(new RegExp(CDN_BRIDGE.source, 'g'), `$1${version}$3`);
+
+/** Points the app's CDN files (those that exist) at `version`; returns the files changed. */
+export async function writeCdnFiles(dir, version) {
+    const changed = [];
+    for (const file of CDN_FILES) {
+        const path = join(dir, file);
+        if (!existsSync(path)) continue;
+        const text = await readFile(path, 'utf8');
+        const next = pointCdn(text, version);
+        if (next !== text) {
+            await writeFile(path, next);
+            changed.push(file);
+        }
+    }
+    return changed;
+}
+
+const isPrerelease = (version) => /^\d+\.\d+\.\d+-/.test(String(version ?? '').trim());
+
+/** This CLI's version, e.g. 0.7.0 or 0.8.0-dev.20261014120000. */
+export const cliVersion = () => JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version;
+
+/** The channel this CLI came from: a prerelease is a dev build. */
+export const cliChannel = (version = cliVersion()) => (isPrerelease(version) ? 'dev' : 'latest');
+
+/** A package.json version spec on the dev channel: the `dev` dist-tag or a prerelease range. */
+export const isDevSpec = (spec) => {
+    const text = String(spec ?? '').trim();
+    return text === 'dev' || isPrerelease(text.replace(/^[\^~>=v\s]+/, ''));
+};
+
+/** The app's channel from its package.json (dev when any Hawk package is on dev), or null without them. */
+export function appChannel(pkg) {
+    const specs = HAWK_PACKAGES.map((name) => pkg?.dependencies?.[name] ?? pkg?.devDependencies?.[name]).filter(Boolean);
+    if (!specs.length) return null;
+    return specs.some(isDevSpec) ? 'dev' : 'latest';
+}
+
+/** The version npm's `latest` tag points at, e.g. "0.6.0"; null when npm can't be asked (offline, no npm). */
+export function npmLatest(name, run = spawnSync) {
+    const result = run('npm', ['view', `${name}@latest`, 'version'], { encoding: 'utf8', shell: process.platform === 'win32' });
+    const version = String(result?.stdout ?? '').trim().split(/\s+/).pop();
+    return result?.status === 0 && /^\d+\.\d+\.\d+$/.test(version) ? version : null;
+}
+
+/**
+ * The changes that put a package.json (and the vanilla CDN import) on `channel`: [{ name, section, from, to }] and
+ * { from, to } for the CDN. `latest` uses npm's latest version (`fallback` when npm can't be asked: the template's).
+ */
+export function planChannel({ pkg, appJs, channel, latestVersion }) {
+    if (!CHANNELS.includes(channel)) throw new Error(`--channel must be latest or dev, not "${channel}".`);
+    const dependencies = [];
+    for (const name of HAWK_PACKAGES) {
+        const section = ['dependencies', 'devDependencies'].find((s) => pkg?.[s]?.[name] !== undefined);
+        if (!section) continue;
+        const from = pkg[section][name];
+        let to;
+        if (channel === 'dev') {
+            to = 'dev';
+        } else {
+            const version = latestVersion(name);
+            if (!version) throw new Error(`Couldn't find the latest version of ${name} on npm. Check your connection and try again.`);
+            to = `^${version}`;
+        }
+        if (from !== to) dependencies.push({ name, section, from, to });
+    }
+    let cdn = null;
+    const current = appJs ? CDN_BRIDGE.exec(appJs)?.[2] : null;
+    if (current) {
+        const version = channel === 'dev' ? 'dev' : latestVersion(BRIDGE)?.split('.').slice(0, 2).join('.');
+        if (!version) throw new Error(`Couldn't find the latest version of ${BRIDGE} on npm. Check your connection and try again.`);
+        if (current !== version) cdn = { from: current, to: version };
+    }
+    return { channel, dependencies, cdn };
+}
+
+/** Applies planChannel's changes to the package.json object and app.js text; returns the new app.js text. */
+export function applyChannel(plan, pkg, appJs) {
+    for (const { name, section, to } of plan.dependencies) pkg[section][name] = to;
+    return plan.cdn && appJs ? pointCdn(appJs, plan.cdn.to) : appJs;
+}
+
+/** What a dev app needs to know (create and upgrade print it). */
+export const DEV_CHANNEL_NOTE = [
+    'This app is on the dev channel: the bridge, the UI kit and the CLI follow their newest dev builds (the `dev` tag on npm).',
+    "Dev features may need the dev platform (the default): don't deploy it to prod until they're released.",
+    'When they are, move it to the released versions: npx hawk-app upgrade --channel latest --yes',
+];