simple-site-generator 0.1.2 → 0.2.0

package/dist/cli.js

@@ -1,3 +1,166 @@
 #!/usr/bin/env node
-"use strict";
-console.log('Placeholder for future CLI');
+import { basename, resolve } from 'node:path';
+import parseArgs from 'minimist';
+import { addPage } from './commands/add-page.js';
+import { build } from './commands/build.js';
+import { check } from './commands/check.js';
+import { TEMPLATES, confirmOverwrite, init } from './commands/init.js';
+import { verify } from './commands/verify.js';
+import { DEFAULT_BUDGETS } from './verify/budgets.js';
+/**
+ * `ssg` — the command surface the agent instructions point at.
+ *
+ * Every command prints a machine-readable result on failure and exits non-zero,
+ * so an agent (or CI) can act on the outcome without parsing prose.
+ */
+const USAGE = `ssg — simple site generator
+
+Usage:
+  ssg init [directory]      Scaffold a new site
+  ssg add-page <id>         Create a page with valid frontmatter
+  ssg check                 Validate every page's frontmatter
+  ssg build                 Build the static site (vitrify build -m ssg)
+  ssg verify                Verify the built site (SEO surface, budgets, Lighthouse)
+
+Options:
+  --template <name>         ${TEMPLATES.join(' | ')} (default: docs)
+  --site-name <name>        Displayed site name
+  --url <origin>            Absolute site origin, e.g. https://example.com
+  --title <title>           add-page: page title
+  --description <text>      add-page: meta description
+  --tags <a,b>              add-page: comma-separated tags (${['menu', 'footer', 'contact'].join(', ')})
+  --page <component>        add-page: template component, e.g. Landing
+  --yes                     Never prompt; use defaults
+  --no-lighthouse           verify: skip Lighthouse (deterministic checks only)
+  --ignore <glob>           verify: skip HTML files matching a glob (repeatable)
+  --js-budget <kb>          verify: JavaScript budget in KB (default 250)
+  --css-budget <kb>         verify: CSS budget in KB (default 60)
+  -h, --help                Show this message
+`;
+async function main(argv) {
+    const [command, positional] = argv;
+    if (!command || command === '--help' || command === '-h') {
+        process.stdout.write(USAGE);
+        return command ? 0 : 1;
+    }
+    const args = parseArgs(argv.slice(1), {
+        string: [
+            'template',
+            'site-name',
+            'url',
+            'title',
+            'description',
+            'tags',
+            'page',
+            'ignore'
+        ],
+        boolean: ['yes', 'lighthouse', 'help'],
+        default: { lighthouse: true, ignore: [] },
+        alias: { h: 'help' }
+    });
+    switch (command) {
+        case 'init': {
+            const directory = resolve(positional ?? args._[0] ?? '.');
+            if (!(await confirmOverwrite(directory))) {
+                process.stdout.write('Aborted.\n');
+                return 1;
+            }
+            const result = await init({
+                directory,
+                template: args.template,
+                name: args['site-name'],
+                productName: args['site-name'],
+                url: args.url,
+                yes: args.yes
+            });
+            process.stdout.write(`Created ${result.template} site in ${result.directory}\n` +
+                `Next: cd ${basename(result.directory)} && pnpm install && pnpm check\n`);
+            return 0;
+        }
+        case 'add-page': {
+            const id = positional;
+            if (!id) {
+                process.stderr.write('add-page requires a page id, e.g. `ssg add-page about`\n');
+                return 1;
+            }
+            const tags = args.tags
+                ? args.tags.split(',').map((tag) => tag.trim())
+                : undefined;
+            const result = await addPage({
+                id,
+                title: args.title,
+                description: args.description,
+                tags,
+                page: args.page
+            });
+            process.stdout.write(`Created ${result.file}\n`);
+            return 0;
+        }
+        case 'check': {
+            const result = await check();
+            if (result.pages === 0) {
+                process.stdout.write('No pages found in src/pages — add one with `ssg add-page home`.\n');
+                return 0;
+            }
+            if (result.ok) {
+                process.stdout.write(`Checked ${result.pages} page(s): OK\n`);
+                return 0;
+            }
+            process.stderr.write(`Checked ${result.pages} page(s): ${result.issues.length} issue(s)\n`);
+            for (const issue of result.issues) {
+                process.stderr.write(`  ${issue.file}: ${issue.message}\n`);
+            }
+            return 1;
+        }
+        case 'build': {
+            const result = await build();
+            if (result.code !== 0) {
+                process.stderr.write(`Build failed (exit ${result.code})\n`);
+                return result.code;
+            }
+            process.stdout.write(`Built to ${result.outputDir}\n`);
+            process.stdout.write('Next: ssg verify\n');
+            return 0;
+        }
+        case 'verify': {
+            const result = await verify({
+                skipLighthouse: args.lighthouse === false,
+                siteUrl: args.url,
+                ignore: [args.ignore].flat().filter(Boolean),
+                budgets: args['js-budget'] || args['css-budget']
+                    ? {
+                        jsBytes: Number(args['js-budget'] ?? DEFAULT_BUDGETS.jsBytes / 1024) *
+                            1024,
+                        cssBytes: Number(args['css-budget'] ?? DEFAULT_BUDGETS.cssBytes / 1024) * 1024
+                    }
+                    : undefined
+            });
+            for (const warning of result.warnings) {
+                process.stdout.write(`  note: ${warning}\n`);
+            }
+            if (!result.ok) {
+                process.stderr.write(`Verification failed: ${result.issues.length} issue(s)\n`);
+                for (const issue of result.issues) {
+                    process.stderr.write(`  ${issue}\n`);
+                }
+                return 1;
+            }
+            process.stdout.write(`Verified ${result.report.pages} page(s): OK${result.report.scores
+                ? ` (${Object.entries(result.report.scores)
+                    .map(([key, value]) => `${key} ${value}`)
+                    .join(', ')})`
+                : ''}\n`);
+            return 0;
+        }
+        default:
+            process.stderr.write(`Unknown command "${command}"\n\n${USAGE}`);
+            return 1;
+    }
+}
+try {
+    process.exitCode = await main(process.argv.slice(2));
+}
+catch (error) {
+    process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+    process.exitCode = 1;
+}

package/dist/commands/add-page.js

@@ -0,0 +1,50 @@
+import { promises as fs } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { appDir, pagesDir } from '../paths.js';
+import { PAGE_TAGS } from '../pages/page-schema.js';
+import { renderPage } from '../pages/render-page.js';
+function titleFromId(id) {
+    const last = id.split('/').filter(Boolean).pop() ?? id;
+    return last
+        .replace(/[-_]+/g, ' ')
+        .replace(/\b\w/g, (character) => character.toUpperCase());
+}
+/**
+ * `ssg add-page` — create a page with valid frontmatter.
+ *
+ * Generates the file through the same `renderPage` the schema validates, so a
+ * page created by the CLI cannot fail `ssg check`. It refuses to overwrite: an
+ * agent re-running a command must never silently destroy content.
+ */
+export async function addPage(options) {
+    const app = options.app ?? appDir();
+    const id = options.id.replace(/^\/+/, '').replace(/\.md$/, '');
+    if (!id) {
+        throw new Error('add-page requires a page id, e.g. `ssg add-page about`');
+    }
+    const file = join(pagesDir(app), `${id}.md`);
+    try {
+        await fs.access(file);
+        throw new Error(`Refusing to overwrite ${file} — a page with id "${id}" already exists.`);
+    }
+    catch (error) {
+        // `fs.access` throwing ENOENT is the expected path; anything else is real.
+        if (error instanceof Error && !/ENOENT/.test(error.message))
+            throw error;
+    }
+    const title = options.title ?? titleFromId(id);
+    const source = renderPage({
+        id,
+        title,
+        description: options.description ??
+            `${title} — replace this with a one-sentence summary of the page.`,
+        label: options.label,
+        order: options.order,
+        tags: options.tags,
+        page: options.page
+    });
+    await fs.mkdir(dirname(file), { recursive: true });
+    await fs.writeFile(file, source, 'utf8');
+    return { file, id };
+}
+export { PAGE_TAGS };

package/dist/commands/build.js

@@ -0,0 +1,20 @@
+import { spawn } from 'node:child_process';
+import { appDir, distDir } from '../paths.js';
+/**
+ * `ssg build` — delegate to `vitrify build -m ssg`.
+ *
+ * Deliberately a thin wrapper: the build belongs to vitrify, and reimplementing
+ * it here would fork the build pipeline from the one the dev server uses. The
+ * value this command adds is the fixed SSG mode, the resolved output path, and a
+ * single place for the agent-facing instructions to point at.
+ */
+export async function build(options = {}) {
+    const app = options.app ?? appDir();
+    const args = ['vitrify', 'build', '-m', 'ssg', ...(options.passthrough ?? [])];
+    const code = await new Promise((done, fail) => {
+        const child = spawn('npx', args, { cwd: app, stdio: 'inherit' });
+        child.once('error', fail);
+        child.once('close', (exitCode) => done(exitCode ?? 1));
+    });
+    return { code, outputDir: distDir(app) };
+}

package/dist/commands/check.js

@@ -0,0 +1,53 @@
+import { promises as fs } from 'node:fs';
+import { join, relative } from 'node:path';
+import matter from 'gray-matter';
+import { appDir, pagesDir } from '../paths.js';
+import { validateCollection, validatePage } from '../pages/page-schema.js';
+import { idFromPath } from '../pages/render-page.js';
+async function collectMarkdown(dir) {
+    let entries;
+    try {
+        entries = await fs.readdir(dir, { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+    const files = [];
+    for (const entry of entries) {
+        const full = join(dir, entry.name);
+        if (entry.isDirectory())
+            files.push(...(await collectMarkdown(full)));
+        else if (entry.name.endsWith('.md'))
+            files.push(full);
+    }
+    return files;
+}
+/**
+ * `ssg check` — validate every page against the frontmatter contract.
+ *
+ * This is the guard that stops the defect class the old template suffered from:
+ * frontmatter that is subtly wrong still builds, and the damage only shows on the
+ * live site. Running it before a build turns that into a terminal error.
+ *
+ * An empty pages directory is a warning, not a failure — a brand new project has
+ * no pages yet, and failing there would be hostile.
+ */
+export async function check(options = {}) {
+    const app = options.app ?? appDir();
+    const root = pagesDir(app);
+    const files = await collectMarkdown(root);
+    const issues = [];
+    const pages = [];
+    for (const file of [...files].sort((a, b) => a.localeCompare(b))) {
+        const relativePath = relative(root, file);
+        const source = await fs.readFile(file, 'utf8');
+        const { data } = matter(source);
+        // `id` defaults to the path so a page that omits it still gets a useful
+        // error against the id the router would actually generate.
+        const dataWithId = { id: idFromPath(relativePath), ...data };
+        pages.push({ file: relativePath, data: dataWithId });
+        issues.push(...validatePage(relativePath, dataWithId));
+    }
+    issues.push(...validateCollection(pages));
+    return { ok: issues.length === 0, pages: pages.length, issues };
+}

package/dist/commands/init.js

@@ -0,0 +1,229 @@
+import { promises as fs } from 'node:fs';
+import { basename, resolve } from 'node:path';
+import { renderDirectory, renderPackageJson, renderTsconfigJson } from '@vitrify/tools/render';
+import { confirm, input, rawlist } from '@inquirer/prompts';
+/**
+ * `ssg init` — scaffold a new site from the app template.
+ *
+ * Replaces the old `create-simple-site-generator` package. Prompts only when the
+ * process is attached to a TTY **and** `--yes` was not passed, so an agent can
+ * run it non-interactively and get the same project every time.
+ */
+export const TEMPLATES = ['docs', 'landing', 'business', 'plain'];
+/** The template tree, shipped inside this package (`files: ["dist","templates"]`). */
+const APP_TEMPLATE_URL = new URL('../../templates/app/', import.meta.url);
+/**
+ * Versions are pinned rather than looked up over the network.
+ *
+ * The old CLI called `latest-version` for every dependency, which made
+ * scaffolding slow, network-dependent and non-reproducible. A static map means
+ * `ssg init` works offline and two runs a month apart produce the same project.
+ */
+const DEPENDENCIES = {
+    '@fastify/middie': '^9.0.1',
+    '@fastify/static': '^8.0.3',
+    '@quasar/extras': '^1.16.13',
+    // No `@quasar/quasar-ui-qmarkdown`: the templates render the HTML that
+    // `vite-plugin-markdown` produced at build time, so the application never
+    // needs a Markdown parser in the browser. The prose styles still come from
+    // the preset's ported selectors, which `appExtensions: ['qmarkdown']` in
+    // `vitrify.config.ts` declares — that entry is a style name, not a package.
+    '@quasar/quasar-ui-qmediaplayer': '^3.0.1',
+    '@simple-site-generator/templates': '^0.1.19',
+    quasar: '^2.32.3',
+    'unocss-preset-quasar': '^0.7.0',
+    'vite-plugin-pwa': '^1.0.0',
+    vue: '^3.5.42',
+    // Must match the ^5 range the templates package is built against, otherwise
+    // the app installs a second, incompatible vue-router.
+    'vue-router': '^5.3.1'
+};
+const DEV_DEPENDENCIES = {
+    '@iconify-json/mdi': '^1.2.3',
+    '@types/node': '^26.5.1',
+    '@unocss/preset-icons': '^66.10.2',
+    '@unocss/preset-web-fonts': '^66.10.2',
+    '@vitejs/plugin-vue': '^6.0.9',
+    '@vue/reactivity': '^3.5.42',
+    '@vue/runtime-core': '^3.5.42',
+    '@vue/runtime-dom': '^3.5.42',
+    '@vue/server-renderer': '^3.5.42',
+    '@vue/shared': '^3.5.42',
+    beasties: '^0.3.0',
+    devcert: '^1.2.2',
+    fastify: '^5.2.1',
+    'gray-matter': '^4.0.3',
+    'icon-gen': '^5.0.0',
+    'npm-run-all': '^4.1.5',
+    oxfmt: '^0.68.0',
+    oxlint: '^1.83.0',
+    // TypeScript 7 is the native port and dropped the JS API that
+    // @vue/compiler-sfc needs to resolve imported types in defineProps().
+    typescript: '^6.0.3',
+    unocss: '^66.10.2',
+    vite: '^8.3.0',
+    'vite-plugin-markdown': '^2.2.0',
+    vitrify: '^0.28.1',
+    'workbox-window': '^7.3.0'
+};
+const SCRIPTS = {
+    dev: 'vitrify dev',
+    'dev:ssr': 'vitrify dev -m ssr',
+    build: 'run-s build:ssg',
+    'build:csr': 'vitrify build',
+    'build:ssr': 'vitrify build -m ssr',
+    'build:ssg': 'vitrify build -m ssg',
+    check: 'ssg check',
+    // Build, then serve the result the way production does — extensionless URLs
+    // and a real 404 — rather than `caddy file-server`, which has no `try_files`
+    // and answers 404 for every page URL.
+    preview: 'pnpm run build && caddy run --config build/Caddyfile.preview --adapter caddyfile',
+    verify: 'ssg verify',
+    test: 'vitrify test',
+    lint: 'oxlint src',
+    'lint:fix': 'oxlint --fix src',
+    'format:check': 'oxfmt --check .',
+    'format:write': 'oxfmt --write .'
+};
+const TSCONFIG = {
+    paths: { src: ['./src'] },
+    types: ['vite/client', 'vitrify/client'],
+    include: [
+        'vitrify.config.ts',
+        'src/**/*.ts',
+        'src/**/*.d.ts',
+        'src/**/*.tsx',
+        'src/**/*.vue'
+    ]
+};
+function assertTemplate(value) {
+    if (TEMPLATES.includes(value)) {
+        return value;
+    }
+    throw new Error(`Unknown template "${value}". Valid templates: ${TEMPLATES.join(', ')}.`);
+}
+/**
+ * Resolve options, prompting only when it is safe and wanted.
+ *
+ * A non-interactive run must never hang waiting on stdin, which is why the
+ * `isTTY` check comes before any prompt.
+ */
+export async function resolveInitOptions(options) {
+    const directory = resolve(options.directory ?? '.');
+    let template;
+    if (options.template) {
+        template = assertTemplate(options.template);
+    }
+    else if (options.yes || !process.stdin.isTTY) {
+        template = 'docs';
+    }
+    else {
+        template = assertTemplate(await rawlist({
+            message: 'Which template would you like to use?',
+            choices: [
+                { name: 'Documentation', value: 'docs' },
+                { name: 'Landing page', value: 'landing' },
+                { name: 'Local business', value: 'business' },
+                { name: 'Plain service', value: 'plain' }
+            ]
+        }));
+    }
+    const fallbackName = basename(directory) || 'site';
+    const interactive = !options.yes && process.stdin.isTTY;
+    const name = options.name ??
+        (interactive
+            ? await input({
+                message: 'Package name',
+                default: fallbackName,
+                validate: (value) => Boolean(value?.length)
+            })
+            : fallbackName);
+    const productName = options.productName ??
+        (interactive
+            ? await input({
+                message: 'Site name',
+                default: name,
+                validate: (value) => Boolean(value?.length)
+            })
+            : name);
+    const url = options.url ??
+        (interactive
+            ? await input({
+                message: 'Website URL',
+                default: 'https://example.com',
+                validate: (value) => Boolean(value?.length)
+            })
+            : 'https://example.com');
+    const description = options.description ??
+        (interactive
+            ? await input({
+                message: 'Description',
+                default: `${productName} website`
+            })
+            : `${productName} website`);
+    const author = options.author ?? (interactive ? await input({ message: 'Author' }) : '');
+    return { directory, template, name, productName, url, description, author };
+}
+export async function init(options = {}) {
+    const resolved = await resolveInitOptions(options);
+    const outputDir = new URL(`./${basename(resolved.directory)}/`, new URL('', `file://${resolve(resolved.directory, '..')}/`));
+    const templateVariables = {
+        template: resolved.template,
+        // Only the `landing` module exports a `Landing` component, so only a landing
+        // site's home page may name it. This used to be hardcoded in the scaffold's
+        // `Index.md`, which meant a `business` or `docs` site shipped `page: Landing`
+        // too -- and the router, having no such component, fell back to the generic
+        // `Page` and rendered the wrong home page with no warning. Once an unknown
+        // `page:` became a build failure, that scaffold could not build at all.
+        landingPage: resolved.template === 'landing',
+        name: resolved.name,
+        productName: resolved.productName,
+        url: resolved.url,
+        description: resolved.description,
+        author: resolved.author
+    };
+    await renderDirectory({
+        directoryUrl: APP_TEMPLATE_URL,
+        templateVariables,
+        outputDir
+    });
+    await fs.writeFile(new URL('./package.json', outputDir), renderPackageJson({
+        ...templateVariables,
+        version: '0.1.0',
+        license: 'UNLICENSED',
+        scripts: SCRIPTS,
+        dependencies: DEPENDENCIES,
+        devDependencies: DEV_DEPENDENCIES,
+        exports: {
+            '.': {
+                types: './dist/types/index.d.ts',
+                import: './dist/index.js'
+            }
+        }
+    }));
+    await fs.writeFile(new URL('./tsconfig.json', outputDir), 
+    // `renderTsconfigJson` emits library defaults, including a `rootDir` of
+    // `./src` — which the very same tsconfig includes `vitrify.config.ts`
+    // outside of, so `tsc` fails every generated project with TS6059. A
+    // generated app has no reason to pin a `rootDir`, so strip it.
+    renderTsconfigJson(TSCONFIG).replace(/^\s*"rootDir": "\.\/src",\n/m, ''));
+    return { directory: resolved.directory, template: resolved.template };
+}
+/** Confirm overwriting a non-empty directory (interactive runs only). */
+export async function confirmOverwrite(directory) {
+    try {
+        const entries = await fs.readdir(directory);
+        if (entries.length === 0)
+            return true;
+    }
+    catch {
+        return true;
+    }
+    if (!process.stdin.isTTY) {
+        throw new Error(`${directory} is not empty. Refusing to overwrite a non-empty directory.`);
+    }
+    return confirm({
+        message: `${directory} is not empty. Continue anyway?`,
+        default: false
+    });
+}

package/dist/commands/verify.js

@@ -0,0 +1,150 @@
+import { promises as fs } from 'node:fs';
+import { join, relative } from 'node:path';
+import { appDir, distDir } from '../paths.js';
+import { DEFAULT_BUDGETS, budgetHeadroomWarnings, evaluateScores, evaluateTotals, formatBytes, measureBuildAssets } from '../verify/budgets.js';
+import { runLighthouse } from '../verify/lighthouse.js';
+import { isIgnored } from '../verify/ignore.js';
+import { checkSeoSurface } from '../verify/seo-surface.js';
+import { checkClassCoverage } from '../verify/class-coverage.js';
+import { startStaticServer } from '../verify/serve.js';
+async function collectHtml(dir) {
+    let entries;
+    try {
+        entries = await fs.readdir(dir, { withFileTypes: true });
+    }
+    catch {
+        throw new Error(`No build output at ${dir}. Run \`ssg build\` before \`ssg verify\`.`);
+    }
+    const files = [];
+    for (const entry of entries) {
+        const full = join(dir, entry.name);
+        if (entry.isDirectory())
+            files.push(...(await collectHtml(full)));
+        else if (entry.name.endsWith('.html'))
+            files.push(full);
+    }
+    return files;
+}
+/**
+ * `ssg verify` — prove the built site is correct and fast.
+ *
+ * Two tiers by design: the SEO surface and the byte budgets are deterministic
+ * and **fail** the run; Lighthouse performance only **warns**, because it varies
+ * with the measuring machine and a gate that fails randomly gets switched off.
+ *
+ * It does not build. `verify` measures what is on disk, so it can be run against
+ * a deployed artifact as well as a local build.
+ */
+export async function verify(options = {}) {
+    const app = options.app ?? appDir();
+    const outputDir = distDir(app);
+    const budgets = options.budgets ?? DEFAULT_BUDGETS;
+    const issues = [];
+    const warnings = [];
+    /** Measured transferred bytes, filled in below. */
+    let budgetTotals = { js: 0, css: 0 };
+    // --- SEO surface (deterministic, hard failure) --------------------------
+    const ignore = options.ignore ?? [];
+    const htmlFiles = (await collectHtml(outputDir)).filter((file) => {
+        const page = relative(outputDir, file).replace(/\\/g, '/');
+        return !isIgnored(page, ignore);
+    });
+    if (htmlFiles.length === 0) {
+        issues.push(`No HTML files found in ${outputDir}`);
+    }
+    for (const file of [...htmlFiles].sort((a, b) => a.localeCompare(b))) {
+        const page = relative(outputDir, file);
+        const html = await fs.readFile(file, 'utf8');
+        for (const issue of checkSeoSurface(html, page, {
+            siteUrl: options.siteUrl
+        })) {
+            issues.push(`${issue.page}: ${issue.message}`);
+        }
+    }
+    // --- Byte budgets (deterministic, measured from the built files) -------
+    // Measured from disk rather than from Lighthouse: the audit reports zero
+    // bytes when its trace captures no network activity, and a budget that
+    // measures nothing is a gate that cannot fail.
+    const assets = await measureBuildAssets(outputDir);
+    // --- Markup ↔ stylesheet coverage (deterministic, hard failure) ----------
+    //
+    // `ssg-*` classes come from the design system's UnoCSS configuration, and a
+    // class that resolves to nothing is invisible everywhere else: the build
+    // passes, the class is present in the markup, and the element is unstyled.
+    // This is the gate for that.
+    const stylesheets = assets.files.filter((file) => file.type === 'css');
+    if (stylesheets.length) {
+        const css = (await Promise.all(stylesheets.map((file) => fs.readFile(join(outputDir, file.file), 'utf8')))).join('\n');
+        const pages = await Promise.all(htmlFiles.map(async (file) => ({
+            page: relative(outputDir, file),
+            html: await fs.readFile(file, 'utf8')
+        })));
+        for (const issue of checkClassCoverage(pages, css)) {
+            issues.push(`${issue.page}: "${issue.className}" is used in the markup but no stylesheet styles it — either the design system lost it or the class is a typo`);
+        }
+    }
+    const budgetResult = evaluateTotals({ js: assets.js, css: assets.css }, budgets);
+    budgetTotals = budgetResult.totals;
+    if (!budgetResult.ok) {
+        issues.push(...budgetResult.issues);
+    }
+    else {
+        warnings.push(`Byte budgets OK: JS ${formatBytes(budgetTotals.js)} / ${formatBytes(budgets.jsBytes)}, CSS ${formatBytes(budgetTotals.css)} / ${formatBytes(budgets.cssBytes)}`);
+        // A budget a site is always near is a cliff (KI-1 in docs/known-issues.md).
+        // Inside the budget is not a defect, so this informs rather than blocks.
+        warnings.push(...budgetHeadroomWarnings(budgetTotals, budgets));
+    }
+    if (assets.files.length) {
+        const largest = assets.files
+            .slice(0, 3)
+            .map((file) => `${file.file} ${formatBytes(file.bytes)}`)
+            .join(', ');
+        warnings.push(`Largest assets: ${largest}`);
+    }
+    // --- Lighthouse scores (advisory for performance) ---------------------
+    let scores;
+    if (htmlFiles.length > 0) {
+        const server = await startStaticServer(outputDir);
+        try {
+            if (options.skipLighthouse) {
+                warnings.push('Lighthouse skipped (--no-lighthouse): scores not measured');
+            }
+            else {
+                const result = await runLighthouse(server.url, {
+                    chromePath: options.chromePath,
+                    formFactor: 'mobile'
+                });
+                scores = result.scores;
+                const scoreResult = evaluateScores(result.scores);
+                for (const issue of scoreResult.issues) {
+                    const category = issue.split(' ')[0];
+                    const failing = result.failures?.[category];
+                    const detail = failing
+                        ?.map((id) => result.details?.[id]?.length
+                        ? `${id} [${result.details[id].join(' | ')}]`
+                        : id)
+                        .join(', ');
+                    issues.push(detail ? `${issue} (failing audits: ${detail})` : issue);
+                }
+                warnings.push(...scoreResult.warnings);
+            }
+        }
+        finally {
+            await server.close();
+        }
+    }
+    const ok = issues.length === 0;
+    // The report is written next to the build so CI can annotate it — a
+    // terminal-only result is invisible to a pipeline.
+    await fs
+        .writeFile(join(outputDir, 'verify-report.json'), `${JSON.stringify({ ok, issues, warnings, pages: htmlFiles.length, budgets: budgetTotals, scores }, null, 2)}\n`, 'utf8')
+        .catch(() => {
+        // The report is a convenience; failing to write it must not fail verify.
+    });
+    return {
+        ok,
+        issues,
+        warnings,
+        report: { pages: htmlFiles.length, budgets: budgetTotals, scores }
+    };
+}