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

package/src/accessibility.mjs

@@ -1,105 +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('; ')}.`,
-    ];
-}
+// 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

@@ -1,145 +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);
-}
+// 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

@@ -1,30 +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}]`;
-}
+/** 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}]`;
+}