apex-auditor 0.1.0

package/README.md

@@ -0,0 +1,145 @@
+# ApexAuditor
+
+ApexAuditor is a small, framework-agnostic Lighthouse runner that gives you **fast, structured insights** across multiple pages and devices.
+
+It is designed to:
+
+- **Run anywhere**: attach to an existing Chrome instance (remote debugging) on Windows, macOS, or Linux.
+- **Work with any web stack**: Next.js, Vite, Rails, static sites, etc. – as long as there is an HTTP server.
+- **Summarize multiple pages at once**: homepage, blog, auth, search, and more.
+- **Output developer-friendly reports**: one Markdown table + JSON, ready to paste into PRs or chat.
+
+> V1 focuses on a solid, single-project core. Route auto-detection and monorepo orchestration will land in later versions.
+
+---
+
+## Quick start (single project)
+
+### 1. Install dependencies
+
+From the `apex-auditor` directory:
+
+```bash
+pnpm install
+```
+
+### 2. Start your web app
+
+In your application repo (for example, a Next.js app running on port 3000):
+
+```bash
+pnpm start
+# or: pnpm dev, npm run dev, etc.
+```
+
+Make sure the app is reachable at the `baseUrl` you will configure (default example: `http://localhost:3000`).
+
+### 3. Start Chrome with remote debugging
+
+ApexAuditor connects to an existing Chrome instance instead of launching its own. Start Chrome once with a debugging port (example for Windows):
+
+```bash
+"C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe" \
+  --remote-debugging-port=9222 \
+  --user-data-dir="%LOCALAPPDATA%\\ChromeApex"
+```
+
+On macOS or Linux the flags are the same; only the Chrome path changes.
+
+### 4. Configure pages (wizard-friendly)
+
+Run the guided wizard to scaffold `apex.config.json` and optionally auto-discover routes:
+
+```bash
+pnpm wizard
+```
+
+The wizard asks for the base URL, optional query string, desired Chrome port, run count, and can crawl popular frameworks (Next.js app/pages) to prefill routes before you fine-tune the list. You can still edit the file manually afterwards:
+
+```jsonc
+{
+  "baseUrl": "http://localhost:3000",
+  "query": "?lhci=1",
+  "chromePort": 9222,
+  "runs": 1,
+  "pages": [
+    { "path": "/", "label": "home", "devices": ["mobile", "desktop"] },
+    { "path": "/blog", "label": "blog", "devices": ["mobile", "desktop"] },
+    { "path": "/contact", "label": "contact", "devices": ["mobile"] }
+  ]
+}
+```
+
+> Tip: rerun `pnpm wizard -- --config custom/path.json` to regenerate configs for multiple projects, or pass a different `--project-root` when prompted to detect routes from another app.
+
+- `baseUrl`: root URL of your running app.
+- `query` (optional): query string appended to every URL (for example `?lhci=1` to disable analytics).
+- `chromePort` (optional): remote debugging port (defaults to `9222`).
+- `runs` (optional): how many times to run Lighthouse per page/device (results are averaged).
+- `pages`: list of paths and devices to audit.
+
+### 5. Run an audit
+
+```bash
+pnpm audit
+```
+
+This will:
+
+- Run Lighthouse for every `page × device` defined in `apex.config.json`.
+- Write structured results to `.apex-auditor/summary.json`.
+- Write a human-readable table to `.apex-auditor/summary.md`.
+- Print the same table to the terminal.
+
+Example output:
+
+```text
+| Label | Path | Device  | P  | A  | BP | SEO | LCP (s) | FCP (s) | TBT (ms) | CLS   | Top issues |
+|-------|------|---------|----|----|----|-----|---------|---------|----------|-------|-----------|
+| home  | /    | mobile  | 95 |100 |100 |100  | 2.9     | 0.9     |   160    | 0.002 | render-blocking-resources (140ms); unused-javascript (55KB) |
+| home  | /    | desktop |100 |100 |100 |100  | 0.6     | 0.4     |     0    | 0.016 | unused-javascript (55KB) |
+```
+
+You can paste this table directly into PRs, tickets, or chat to discuss optimizations.
+
+---
+
+## Configuration reference (V1)
+
+```ts
+// apex.config.json (TypeScript shape)
+interface ApexPageConfig {
+  path: string;          // URL path, must start with "/"
+  label: string;         // short label for reports
+  devices: ("mobile" | "desktop")[];
+}
+
+interface ApexConfig {
+  baseUrl: string;       // e.g. "http://localhost:3000"
+  query?: string;        // e.g. "?lhci=1"
+  chromePort?: number;   // default: 9222
+  runs?: number;         // default: 1
+  pages: ApexPageConfig[];
+}
+```
+
+Future versions will add:
+
+- Automatic route discovery (for example, from Next.js `app/` routes or a crawler).
+- Workspace-level configs for monorepos.
+- CI integration recipes and HTML dashboards.
+
+---
+
+## Code structure (V1)
+
+The codebase is intentionally small and modular:
+
+- `src/types.ts` – shared type definitions for config and results.
+- `src/config.ts` – loads and validates `apex.config.json`.
+- `src/lighthouse-runner.ts` – runs Lighthouse for each page/device and normalises results.
+- `src/cli.ts` – CLI entry point; orchestrates config + runner, writes JSON/Markdown.
+
+All public modules use explicit TypeScript types and are written to be reusable in future integrations (route detectors, monorepo orchestration, CI adapters).
+
+See `ROADMAP.md` for planned features and phases.

package/dist/bin.js

@@ -0,0 +1,47 @@
+#!/usr/bin/env node
+import { runAuditCli } from "./cli.js";
+import { runWizardCli } from "./wizard-cli.js";
+function parseBinArgs(argv) {
+    const rawCommand = argv[2];
+    if (rawCommand === undefined || rawCommand === "help" || rawCommand === "--help" || rawCommand === "-h") {
+        return { command: "help", argv };
+    }
+    if (rawCommand === "audit" || rawCommand === "wizard") {
+        const commandArgv = ["node", "apex-auditor", ...argv.slice(3)];
+        return { command: rawCommand, argv: commandArgv };
+    }
+    return { command: "help", argv };
+}
+function printHelp() {
+    console.log([
+        "ApexAuditor CLI",
+        "",
+        "Usage:",
+        "  apex-auditor wizard [--config <path>]",
+        "  apex-auditor audit [--config <path>]",
+        "",
+        "Commands:",
+        "  wizard   Run interactive config wizard",
+        "  audit    Run Lighthouse audits using apex.config.json",
+        "  help     Show this help message",
+    ].join("\n"));
+}
+export async function runBin(argv) {
+    const parsed = parseBinArgs(argv);
+    if (parsed.command === "help") {
+        printHelp();
+        return;
+    }
+    if (parsed.command === "audit") {
+        await runAuditCli(parsed.argv);
+        return;
+    }
+    if (parsed.command === "wizard") {
+        await runWizardCli(parsed.argv);
+    }
+}
+void runBin(process.argv).catch((error) => {
+    // eslint-disable-next-line no-console
+    console.error("ApexAuditor CLI failed:", error);
+    process.exitCode = 1;
+});

package/dist/cli.js

@@ -0,0 +1,65 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import { loadConfig } from "./config.js";
+import { runAuditsForConfig } from "./lighthouse-runner.js";
+function parseArgs(argv) {
+    let configPath;
+    for (let i = 2; i < argv.length; i += 1) {
+        const arg = argv[i];
+        if ((arg === "--config" || arg === "-c") && i + 1 < argv.length) {
+            configPath = argv[i + 1];
+            i += 1;
+        }
+    }
+    const finalConfigPath = configPath ?? "apex.config.json";
+    return { configPath: finalConfigPath };
+}
+/**
+ * Runs the ApexAuditor audit CLI.
+ *
+ * @param argv - The process arguments array.
+ */
+export async function runAuditCli(argv) {
+    const args = parseArgs(argv);
+    const { configPath, config } = await loadConfig({ configPath: args.configPath });
+    const summary = await runAuditsForConfig({ config, configPath });
+    const outputDir = resolve(".apex-auditor");
+    await mkdir(outputDir, { recursive: true });
+    await writeFile(resolve(outputDir, "summary.json"), JSON.stringify(summary, null, 2), "utf8");
+    const markdown = buildMarkdown(summary.results);
+    await writeFile(resolve(outputDir, "summary.md"), markdown, "utf8");
+    // Also echo a compact table to stdout for quick viewing.
+    // eslint-disable-next-line no-console
+    console.log(markdown);
+}
+function buildMarkdown(results) {
+    const header = [
+        "| Label | Path | Device | P | A | BP | SEO | LCP (s) | FCP (s) | TBT (ms) | CLS | Top issues |",
+        "|-------|------|--------|---|---|----|-----|---------|---------|----------|-----|-----------|",
+    ].join("\n");
+    const lines = results.map((result) => buildRow(result));
+    return `${header}\n${lines.join("\n")}`;
+}
+function buildRow(result) {
+    const scores = result.scores;
+    const metrics = result.metrics;
+    const lcpSeconds = metrics.lcpMs !== undefined ? (metrics.lcpMs / 1000).toFixed(1) : "-";
+    const fcpSeconds = metrics.fcpMs !== undefined ? (metrics.fcpMs / 1000).toFixed(1) : "-";
+    const tbtMs = metrics.tbtMs !== undefined ? Math.round(metrics.tbtMs).toString() : "-";
+    const cls = metrics.cls !== undefined ? metrics.cls.toFixed(3) : "-";
+    const issues = formatTopIssues(result.opportunities);
+    return `| ${result.label} | ${result.path} | ${result.device} | ${scores.performance ?? "-"} | ${scores.accessibility ?? "-"} | ${scores.bestPractices ?? "-"} | ${scores.seo ?? "-"} | ${lcpSeconds} | ${fcpSeconds} | ${tbtMs} | ${cls} | ${issues} |`;
+}
+function formatTopIssues(opportunities) {
+    if (opportunities.length === 0) {
+        return "";
+    }
+    const items = opportunities.map((opp) => {
+        const savingsMs = opp.estimatedSavingsMs !== undefined ? `${Math.round(opp.estimatedSavingsMs)}ms` : "";
+        const savingsBytes = opp.estimatedSavingsBytes !== undefined ? `${Math.round(opp.estimatedSavingsBytes / 1024)}KB` : "";
+        const parts = [savingsMs, savingsBytes].filter((p) => p.length > 0);
+        const suffix = parts.length > 0 ? ` (${parts.join(", ")})` : "";
+        return `${opp.id}${suffix}`;
+    });
+    return items.join("; ");
+}

package/dist/config.js

@@ -0,0 +1,63 @@
+import { readFile } from "node:fs/promises";
+import { resolve } from "node:path";
+/**
+ * Load and minimally validate the ApexAuditor configuration file.
+ */
+export async function loadConfig({ configPath }) {
+    const absolutePath = resolve(configPath);
+    const raw = await readFile(absolutePath, "utf8");
+    const parsed = JSON.parse(raw);
+    const config = normaliseConfig(parsed, absolutePath);
+    return { configPath: absolutePath, config };
+}
+function normaliseConfig(input, absolutePath) {
+    if (!input || typeof input !== "object") {
+        throw new Error(`Invalid config at ${absolutePath}: expected object`);
+    }
+    const maybeConfig = input;
+    if (typeof maybeConfig.baseUrl !== "string" || maybeConfig.baseUrl.length === 0) {
+        throw new Error(`Invalid config at ${absolutePath}: baseUrl must be a non-empty string`);
+    }
+    const pagesInput = maybeConfig.pages;
+    if (!Array.isArray(pagesInput) || pagesInput.length === 0) {
+        throw new Error(`Invalid config at ${absolutePath}: pages must be a non-empty array`);
+    }
+    const pages = pagesInput.map((page, index) => normalisePage(page, index, absolutePath));
+    const baseUrl = maybeConfig.baseUrl.replace(/\/$/, "");
+    const query = typeof maybeConfig.query === "string" ? maybeConfig.query : undefined;
+    const chromePort = typeof maybeConfig.chromePort === "number" ? maybeConfig.chromePort : undefined;
+    const runs = typeof maybeConfig.runs === "number" && maybeConfig.runs > 0 ? maybeConfig.runs : undefined;
+    return {
+        baseUrl,
+        query,
+        chromePort,
+        runs,
+        pages,
+    };
+}
+function normalisePage(page, index, absolutePath) {
+    if (!page || typeof page !== "object") {
+        throw new Error(`Invalid page at index ${index} in ${absolutePath}: expected object`);
+    }
+    const maybePage = page;
+    if (typeof maybePage.path !== "string" || !maybePage.path.startsWith("/")) {
+        throw new Error(`Invalid page at index ${index} in ${absolutePath}: path must start with '/'`);
+    }
+    const label = typeof maybePage.label === "string" && maybePage.label.length > 0
+        ? maybePage.label
+        : maybePage.path;
+    const devicesInput = maybePage.devices;
+    const devices = Array.isArray(devicesInput) && devicesInput.length > 0
+        ? devicesInput.map((d, deviceIndex) => {
+            if (d !== "mobile" && d !== "desktop") {
+                throw new Error(`Invalid device at pages[${index}].devices[${deviceIndex}] in ${absolutePath}`);
+            }
+            return d;
+        })
+        : ["mobile"];
+    return {
+        path: maybePage.path,
+        label,
+        devices,
+    };
+}

package/dist/fs-utils.js

@@ -0,0 +1,13 @@
+import { access, readFile } from "node:fs/promises";
+export async function readTextFile(path) {
+    return readFile(path, "utf8");
+}
+export async function pathExists(path) {
+    try {
+        await access(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/lighthouse-runner.js

@@ -0,0 +1,149 @@
+import lighthouse from "lighthouse";
+/**
+ * Run audits for all pages defined in the config and return a structured summary.
+ */
+export async function runAuditsForConfig({ config, configPath, }) {
+    const port = config.chromePort ?? 9222;
+    const runs = config.runs ?? 1;
+    const results = [];
+    for (const page of config.pages) {
+        for (const device of page.devices) {
+            const url = buildUrl({ baseUrl: config.baseUrl, path: page.path, query: config.query });
+            const summaries = [];
+            for (let i = 0; i < runs; i += 1) {
+                const summary = await runSingleAudit({
+                    url,
+                    path: page.path,
+                    label: page.label,
+                    device,
+                    port,
+                });
+                summaries.push(summary);
+            }
+            results.push(aggregateSummaries(summaries));
+        }
+    }
+    return { configPath, results };
+}
+function buildUrl({ baseUrl, path, query }) {
+    const cleanBase = baseUrl.replace(/\/$/, "");
+    const cleanPath = path.startsWith("/") ? path : `/${path}`;
+    const queryPart = query && query.length > 0 ? query : "";
+    return `${cleanBase}${cleanPath}${queryPart}`;
+}
+async function runSingleAudit(params) {
+    const options = {
+        port: params.port,
+        output: "json",
+        logLevel: "error",
+        onlyCategories: ["performance", "accessibility", "best-practices", "seo"],
+        emulatedFormFactor: params.device,
+    };
+    const runnerResult = await lighthouse(params.url, options);
+    const lhrUnknown = runnerResult.lhr;
+    if (!lhrUnknown || typeof lhrUnknown !== "object") {
+        throw new Error("Lighthouse did not return a valid result");
+    }
+    const lhr = lhrUnknown;
+    const scores = extractScores(lhr);
+    const metrics = extractMetrics(lhr);
+    const opportunities = extractTopOpportunities(lhr, 3);
+    return {
+        url: lhr.finalDisplayedUrl ?? params.url,
+        path: params.path,
+        label: params.label,
+        device: params.device,
+        scores,
+        metrics,
+        opportunities,
+    };
+}
+function extractScores(lhr) {
+    const performanceScore = lhr.categories.performance?.score;
+    const accessibilityScore = lhr.categories.accessibility?.score;
+    const bestPracticesScore = lhr.categories["best-practices"]?.score;
+    const seoScore = lhr.categories.seo?.score;
+    return {
+        performance: normaliseScore(performanceScore),
+        accessibility: normaliseScore(accessibilityScore),
+        bestPractices: normaliseScore(bestPracticesScore),
+        seo: normaliseScore(seoScore),
+    };
+}
+function normaliseScore(score) {
+    if (typeof score !== "number") {
+        return undefined;
+    }
+    return Math.round(score * 100);
+}
+function extractMetrics(lhr) {
+    const audits = lhr.audits;
+    const lcpAudit = audits["largest-contentful-paint"];
+    const fcpAudit = audits["first-contentful-paint"];
+    const tbtAudit = audits["total-blocking-time"];
+    const clsAudit = audits["cumulative-layout-shift"];
+    const lcpMs = typeof lcpAudit?.numericValue === "number" ? lcpAudit.numericValue : undefined;
+    const fcpMs = typeof fcpAudit?.numericValue === "number" ? fcpAudit.numericValue : undefined;
+    const tbtMs = typeof tbtAudit?.numericValue === "number" ? tbtAudit.numericValue : undefined;
+    const cls = typeof clsAudit?.numericValue === "number" ? clsAudit.numericValue : undefined;
+    return {
+        lcpMs,
+        fcpMs,
+        tbtMs,
+        cls,
+    };
+}
+function extractTopOpportunities(lhr, limit) {
+    const audits = Object.values(lhr.audits);
+    const candidates = audits
+        .filter((audit) => audit.details?.type === "opportunity")
+        .map((audit) => {
+        const savingsMs = audit.details?.overallSavingsMs;
+        const savingsBytes = audit.details?.overallSavingsBytes;
+        return {
+            id: audit.id ?? "unknown",
+            title: audit.title ?? (audit.id ?? "Unknown"),
+            estimatedSavingsMs: typeof savingsMs === "number" ? savingsMs : undefined,
+            estimatedSavingsBytes: typeof savingsBytes === "number" ? savingsBytes : undefined,
+        };
+    });
+    candidates.sort((a, b) => (b.estimatedSavingsMs ?? 0) - (a.estimatedSavingsMs ?? 0));
+    return candidates.slice(0, limit);
+}
+function aggregateSummaries(summaries) {
+    if (summaries.length === 1) {
+        return summaries[0];
+    }
+    const base = summaries[0];
+    const count = summaries.length;
+    const aggregateScores = {
+        performance: averageOf(summaries.map((s) => s.scores.performance)),
+        accessibility: averageOf(summaries.map((s) => s.scores.accessibility)),
+        bestPractices: averageOf(summaries.map((s) => s.scores.bestPractices)),
+        seo: averageOf(summaries.map((s) => s.scores.seo)),
+    };
+    const aggregateMetrics = {
+        lcpMs: averageOf(summaries.map((s) => s.metrics.lcpMs)),
+        fcpMs: averageOf(summaries.map((s) => s.metrics.fcpMs)),
+        tbtMs: averageOf(summaries.map((s) => s.metrics.tbtMs)),
+        cls: averageOf(summaries.map((s) => s.metrics.cls)),
+    };
+    const opportunities = summaries[0].opportunities;
+    return {
+        url: base.url,
+        path: base.path,
+        label: base.label,
+        device: base.device,
+        scores: aggregateScores,
+        metrics: aggregateMetrics,
+        opportunities,
+    };
+}
+function averageOf(values) {
+    const defined = values.filter((v) => typeof v === "number");
+    if (defined.length === 0) {
+        return undefined;
+    }
+    const total = defined.reduce((sum, value) => sum + value, 0);
+    return total / defined.length;
+}

package/dist/route-detectors.js

@@ -0,0 +1,306 @@
+import { readdir } from "node:fs/promises";
+import { join, relative, sep } from "node:path";
+import { pathExists, readTextFile } from "./fs-utils.js";
+const PAGE_EXTENSIONS = [".tsx", ".ts", ".jsx", ".js"];
+const DEFAULT_LIMIT = 25;
+const SOURCE_NEXT_APP = "next-app";
+const SOURCE_NEXT_PAGES = "next-pages";
+const SOURCE_REMIX = "remix-routes";
+const SOURCE_SPA = "spa-html";
+const ROUTE_DETECTORS = [
+    createNextAppDetector(),
+    createNextPagesDetector(),
+    createRemixRoutesDetector(),
+    createSpaHtmlDetector(),
+];
+export async function detectRoutes(options) {
+    const limit = options.limit ?? DEFAULT_LIMIT;
+    const orderedDetectors = orderDetectors(options.preferredDetectorId);
+    for (const detector of orderedDetectors) {
+        const detectorOptions = { ...options, limit };
+        if (!(await detector.canDetect(detectorOptions))) {
+            logDetection(options, detector.id, "skipped");
+            continue;
+        }
+        const routes = await detector.detect(detectorOptions);
+        if (routes.length === 0) {
+            logDetection(options, detector.id, "no-routes", { limit });
+            continue;
+        }
+        const selected = takeTopRoutes(routes, limit);
+        logDetection(options, detector.id, "routes-found", {
+            limit,
+            candidateCount: routes.length,
+            selectedCount: selected.length,
+            root: detectorOptions.projectRoot,
+        });
+        return selected;
+    }
+    logDetection(options, "none", "no-detectors", { limit });
+    return [];
+}
+function createNextAppDetector() {
+    return {
+        id: SOURCE_NEXT_APP,
+        canDetect: async (options) => pathExists(join(options.projectRoot, "app")),
+        detect: async (options) => detectAppRoutes(join(options.projectRoot, "app"), options.limit),
+    };
+}
+function createNextPagesDetector() {
+    return {
+        id: SOURCE_NEXT_PAGES,
+        canDetect: async (options) => pathExists(join(options.projectRoot, "pages")),
+        detect: async (options) => detectPagesRoutes(join(options.projectRoot, "pages"), options.limit),
+    };
+}
+function createRemixRoutesDetector() {
+    return {
+        id: SOURCE_REMIX,
+        canDetect: async (options) => pathExists(join(options.projectRoot, "app", "routes")),
+        detect: async (options) => detectRemixRoutes(join(options.projectRoot, "app", "routes"), options.limit),
+    };
+}
+function createSpaHtmlDetector() {
+    return {
+        id: SOURCE_SPA,
+        canDetect: async (options) => Boolean(await findSpaHtml(options.projectRoot)),
+        detect: async (options) => detectSpaRoutes(options.projectRoot, options.limit),
+    };
+}
+async function detectAppRoutes(appRoot, limit) {
+    const files = await collectRouteFiles(appRoot, limit, isAppPageFile);
+    return files.map((file) => buildRoute(file, appRoot, formatAppRoutePath, SOURCE_NEXT_APP));
+}
+async function detectPagesRoutes(pagesRoot, limit) {
+    const files = await collectRouteFiles(pagesRoot, limit, isPagesFileAllowed);
+    return files.map((file) => buildRoute(file, pagesRoot, formatPagesRoutePath, SOURCE_NEXT_PAGES));
+}
+async function detectRemixRoutes(routesRoot, limit) {
+    const files = await collectRouteFiles(routesRoot, limit, isRemixRouteFile);
+    return files.map((file) => buildRoute(file, routesRoot, formatRemixRoutePath, SOURCE_REMIX));
+}
+async function detectSpaRoutes(projectRoot, limit) {
+    const htmlPath = await findSpaHtml(projectRoot);
+    if (!htmlPath) {
+        return [];
+    }
+    const html = await readTextFile(htmlPath);
+    const routes = extractRoutesFromHtml(html).slice(0, limit);
+    return routes.map((routePath) => ({ path: routePath, label: buildLabel(routePath), source: SOURCE_SPA }));
+}
+async function collectRouteFiles(root, limit, matcher) {
+    const stack = [root];
+    const files = [];
+    while (stack.length > 0 && files.length < limit) {
+        const current = stack.pop();
+        const entries = await readdir(current, { withFileTypes: true });
+        for (const entry of entries) {
+            const entryPath = join(current, entry.name);
+            const relativePath = relative(root, entryPath);
+            if (entry.isDirectory()) {
+                if (shouldRecurseDirectory(relativePath)) {
+                    stack.push(entryPath);
+                }
+            }
+            else if (matcher(entry, relativePath)) {
+                files.push(entryPath);
+            }
+            if (files.length >= limit) {
+                break;
+            }
+        }
+    }
+    return files;
+}
+function shouldRecurseDirectory(relativePath) {
+    const posixPath = normalisePath(relativePath);
+    if (posixPath.startsWith("api/")) {
+        return false;
+    }
+    return true;
+}
+function isAppPageFile(entry, relativePath) {
+    if (!entry.isFile()) {
+        return false;
+    }
+    const posixPath = normalisePath(relativePath);
+    if (!hasAllowedExtension(posixPath)) {
+        return false;
+    }
+    return posixPath.includes("/page.") || posixPath.startsWith("page.");
+}
+function isPagesFileAllowed(entry, relativePath) {
+    if (!entry.isFile()) {
+        return false;
+    }
+    const posixPath = normalisePath(relativePath);
+    if (!hasAllowedExtension(posixPath)) {
+        return false;
+    }
+    if (posixPath.startsWith("api/")) {
+        return false;
+    }
+    if (posixPath.startsWith("_")) {
+        return false;
+    }
+    return true;
+}
+function isRemixRouteFile(entry, relativePath) {
+    if (!entry.isFile()) {
+        return false;
+    }
+    if (!hasAllowedExtension(relativePath)) {
+        return false;
+    }
+    const posixPath = normalisePath(relativePath);
+    if (posixPath.includes(".server")) {
+        return false;
+    }
+    return !posixPath.split("/").some((segment) => segment.startsWith("__"));
+}
+function hasAllowedExtension(path) {
+    return PAGE_EXTENSIONS.some((extension) => path.endsWith(extension));
+}
+function buildRoute(filePath, root, formatter, source) {
+    const relativePath = normalisePath(relative(root, filePath));
+    const routePath = formatter(relativePath);
+    return {
+        path: routePath,
+        label: buildLabel(routePath),
+        source,
+    };
+}
+function formatAppRoutePath(relativePath) {
+    const posixPath = relativePath.replace(/\\/g, "/");
+    const withoutFile = posixPath.replace(/\/?page\.[^/]+$/, "");
+    const cleaned = withoutFile.replace(/\([^/]+\)/g, "").replace(/^\/+/, "");
+    return cleaned.length === 0 ? "/" : normaliseRoute(cleaned);
+}
+function formatPagesRoutePath(relativePath) {
+    const cleanPath = relativePath.replace(/\\/g, "/").replace(/\.[^/.]+$/, "");
+    if (cleanPath === "index") {
+        return "/";
+    }
+    if (cleanPath.endsWith("/index")) {
+        return normaliseRoute(cleanPath.slice(0, -6));
+    }
+    return normaliseRoute(cleanPath);
+}
+function formatRemixRoutePath(relativePath) {
+    const cleanPath = relativePath.replace(/\\/g, "/").replace(/\.[^/.]+$/, "");
+    const tokens = cleanPath
+        .split("/")
+        .flatMap((segment) => segment.split("."))
+        .map((segment) => segment.trim())
+        .filter((segment) => segment.length > 0);
+    const parts = tokens
+        .map((segment) => (segment.startsWith("_") ? segment.slice(1) : segment))
+        .map((segment) => {
+        if (segment === "index") {
+            return "";
+        }
+        if (segment === "$") {
+            return ":param";
+        }
+        if (segment.startsWith("$")) {
+            return `:${segment.slice(1)}`;
+        }
+        if (segment.includes("$")) {
+            return segment
+                .split("$")
+                .filter((piece) => piece.length > 0)
+                .map((piece, index) => (index === 0 ? piece : `:${piece}`))
+                .join("/");
+        }
+        return segment.replace(/\$([a-zA-Z0-9]+)/g, ":$1").replace(/\$/g, "");
+    })
+        .filter((segment) => segment.length > 0);
+    return parts.length === 0 ? "/" : normaliseRoute(parts.join("/"));
+}
+function normaliseRoute(path) {
+    const trimmed = path.replace(/^\/+/, "");
+    if (trimmed.length === 0) {
+        return "/";
+    }
+    return `/${trimmed}`.replace(/\/+/g, "/");
+}
+function buildLabel(routePath) {
+    if (routePath === "/") {
+        return "home";
+    }
+    const segments = routePath.split("/").filter(Boolean);
+    const lastSegment = segments[segments.length - 1] ?? "page";
+    return lastSegment.replace(/\[\[(.+?)\]\]/g, "$1").replace(/^:/, "");
+}
+function normalisePath(path) {
+    return path.split(sep).join("/");
+}
+function takeTopRoutes(routes, limit) {
+    return routes.slice(0, limit);
+}
+function orderDetectors(preferredId) {
+    if (!preferredId) {
+        return ROUTE_DETECTORS;
+    }
+    const preferred = ROUTE_DETECTORS.find((detector) => detector.id === preferredId);
+    if (!preferred) {
+        return ROUTE_DETECTORS;
+    }
+    const others = ROUTE_DETECTORS.filter((detector) => detector.id !== preferredId);
+    return [preferred, ...others];
+}
+function logDetection(options, detectorId, message, context) {
+    if (!options.logger) {
+        return;
+    }
+    options.logger.log({
+        detectorId,
+        message,
+        context: {
+            root: context?.root ?? options.projectRoot,
+            limit: context?.limit,
+            candidateCount: context?.candidateCount,
+            selectedCount: context?.selectedCount,
+        },
+    });
+}
+async function findSpaHtml(projectRoot) {
+    const candidates = [
+        "dist/index.html",
+        "build/index.html",
+        "public/index.html",
+        "index.html",
+    ];
+    for (const candidate of candidates) {
+        const absolute = join(projectRoot, candidate);
+        if (await pathExists(absolute)) {
+            return absolute;
+        }
+    }
+    return undefined;
+}
+function extractRoutesFromHtml(html) {
+    const routes = [];
+    const seen = new Set();
+    const hrefPattern = /href\s*=\s*"(\/[^"]*)"/gi;
+    const dataRoutePattern = /data-route\s*=\s*"(\/[^"]*)"/gi;
+    const addRoute = (raw) => {
+        const base = raw.split(/[?#]/)[0];
+        if (!base || base.length === 0) {
+            return;
+        }
+        const normalized = normaliseRoute(base);
+        if (!seen.has(normalized)) {
+            seen.add(normalized);
+            routes.push(normalized);
+        }
+    };
+    let match;
+    while ((match = hrefPattern.exec(html)) !== null) {
+        addRoute(match[1]);
+    }
+    while ((match = dataRoutePattern.exec(html)) !== null) {
+        addRoute(match[1]);
+    }
+    return routes;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/wizard-cli.js

@@ -0,0 +1,276 @@
+import { access, writeFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import prompts from "prompts";
+import { detectRoutes } from "./route-detectors.js";
+import { pathExists } from "./fs-utils.js";
+const PROFILE_TO_DETECTOR = {
+    "next-app": "next-app",
+    "next-pages": "next-pages",
+    spa: "spa-html",
+    remix: "remix-routes",
+    custom: undefined,
+};
+const DEFAULT_BASE_URL = "http://localhost:3000";
+const DEFAULT_CHROME_PORT = 9222;
+const DEFAULT_RUNS = 1;
+const DEFAULT_PROJECT_ROOT = "..";
+const DEFAULT_PRESELECT_COUNT = 5;
+const DEFAULT_DEVICES = ["mobile", "desktop"];
+const PROMPT_OPTIONS = { onCancel: handleCancel };
+const profileQuestion = {
+    type: "select",
+    name: "profile",
+    message: "Which project type are you configuring?",
+    choices: [
+        { title: "Next.js (App Router)", value: "next-app" },
+        { title: "Next.js (Pages Router)", value: "next-pages" },
+        { title: "Remix", value: "remix" },
+        { title: "Single Page App (Vite/CRA/etc.)", value: "spa" },
+        { title: "Custom/manual", value: "custom" },
+    ],
+};
+const overwriteQuestion = {
+    type: "confirm",
+    name: "value",
+    message: "Found existing config. Overwrite?",
+    initial: false,
+};
+const baseQuestions = [
+    {
+        type: "text",
+        name: "baseUrl",
+        message: "Base URL of the running app",
+        initial: DEFAULT_BASE_URL,
+        validate: (value) => (value.startsWith("http") ? true : "Enter a full http(s) URL."),
+    },
+    {
+        type: "text",
+        name: "query",
+        message: "Query string appended to every route (optional)",
+        initial: "",
+    },
+    {
+        type: "number",
+        name: "chromePort",
+        message: "Chrome remote debugging port",
+        initial: DEFAULT_CHROME_PORT,
+        min: 1,
+    },
+    {
+        type: "number",
+        name: "runs",
+        message: "Number of Lighthouse runs per page/device",
+        initial: DEFAULT_RUNS,
+        min: 1,
+    },
+];
+const pageQuestions = [
+    {
+        type: "text",
+        name: "path",
+        message: "Page path (must start with /)",
+        validate: (value) => (value.startsWith("/") ? true : "Path must start with '/'."),
+    },
+    {
+        type: "text",
+        name: "label",
+        message: "Short label for reports",
+    },
+    {
+        type: "multiselect",
+        name: "devices",
+        message: "Devices to audit",
+        instructions: false,
+        min: 1,
+        choices: [
+            { title: "Mobile", value: "mobile", selected: true },
+            { title: "Desktop", value: "desktop", selected: true },
+        ],
+    },
+];
+const addFirstPageQuestion = {
+    type: "confirm",
+    name: "value",
+    message: "Add your first page to audit?",
+    initial: true,
+};
+const addMorePagesQuestion = {
+    type: "confirm",
+    name: "value",
+    message: "Add another page to audit?",
+    initial: false,
+};
+const detectRoutesQuestion = {
+    type: "confirm",
+    name: "value",
+    message: "Attempt to auto-detect routes from your project?",
+    initial: true,
+};
+const projectRootQuestion = {
+    type: "text",
+    name: "projectRoot",
+    message: "Path to your web project root (relative or absolute)",
+    initial: DEFAULT_PROJECT_ROOT,
+};
+const detectorChoiceQuestion = {
+    type: "select",
+    name: "detector",
+    message: "Choose a detector to guide auto-discovery",
+    choices: [
+        { title: "Next.js (App Router)", value: "next-app" },
+        { title: "Next.js (Pages Router)", value: "next-pages" },
+        { title: "Remix", value: "remix-routes" },
+        { title: "SPA Crawl", value: "spa-html" },
+    ],
+};
+function handleCancel() {
+    console.log("Wizard cancelled. No config written.");
+    process.exit(1);
+    return true;
+}
+async function ask(question) {
+    const answers = await prompts(question, PROMPT_OPTIONS);
+    return answers;
+}
+function parseArgs(argv) {
+    let configPath;
+    for (let index = 2; index < argv.length; index += 1) {
+        const arg = argv[index];
+        if ((arg === "--config" || arg === "-c") && index + 1 < argv.length) {
+            configPath = argv[index + 1];
+            index += 1;
+        }
+    }
+    return { configPath: configPath ?? "apex.config.json" };
+}
+async function fileExists(path) {
+    try {
+        await access(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function ensureWritable(path) {
+    if (!(await fileExists(path))) {
+        return;
+    }
+    const response = await ask(overwriteQuestion);
+    if (response.value) {
+        return;
+    }
+    console.log("Aborted. Existing config preserved.");
+    process.exit(0);
+}
+async function collectBaseAnswers() {
+    const answers = await ask(baseQuestions);
+    return {
+        baseUrl: answers.baseUrl.trim(),
+        query: answers.query && answers.query.length > 0 ? answers.query : undefined,
+        chromePort: answers.chromePort,
+        runs: answers.runs,
+    };
+}
+async function confirmAddPage(hasPages) {
+    const question = hasPages ? addMorePagesQuestion : addFirstPageQuestion;
+    const response = await ask(question);
+    return response.value;
+}
+async function collectSinglePage() {
+    const answers = await ask(pageQuestions);
+    const label = answers.label && answers.label.length > 0 ? answers.label : answers.path;
+    return { path: answers.path, label, devices: answers.devices };
+}
+async function collectPages(initialPages) {
+    const pages = [...initialPages];
+    while (true) {
+        const shouldAdd = await confirmAddPage(pages.length > 0);
+        if (!shouldAdd) {
+            if (pages.length === 0) {
+                console.log("At least one page is required.");
+                continue;
+            }
+            return pages;
+        }
+        pages.push(await collectSinglePage());
+    }
+}
+async function maybeDetectPages(profile) {
+    const shouldDetect = await ask(detectRoutesQuestion);
+    if (!shouldDetect.value) {
+        return [];
+    }
+    const preferredDetector = await selectDetector(profile);
+    const projectRootAnswer = await ask(projectRootQuestion);
+    const absoluteRoot = resolve(projectRootAnswer.projectRoot);
+    if (!(await pathExists(absoluteRoot))) {
+        console.log(`No project found at ${absoluteRoot}. Skipping auto-detection.`);
+        return [];
+    }
+    const routes = await detectRoutes({ projectRoot: absoluteRoot, preferredDetectorId: preferredDetector });
+    if (routes.length === 0) {
+        console.log("No routes detected. Add pages manually.");
+        return [];
+    }
+    return selectDetectedRoutes(routes);
+}
+async function selectDetector(profile) {
+    const preset = PROFILE_TO_DETECTOR[profile];
+    if (preset) {
+        return preset;
+    }
+    const choice = await ask(detectorChoiceQuestion);
+    return choice.detector;
+}
+async function selectDetectedRoutes(routes) {
+    const response = await ask({
+        type: "multiselect",
+        name: "indexes",
+        message: "Select routes to include",
+        instructions: false,
+        min: 1,
+        choices: buildRouteChoices(routes),
+    });
+    const indexes = response.indexes ?? [];
+    if (indexes.length === 0) {
+        console.log("No routes selected. Add pages manually.");
+        return [];
+    }
+    return indexes.map((index) => convertRouteToPage(routes[index]));
+}
+function buildRouteChoices(routes) {
+    return routes.map((route, index) => ({
+        title: `${route.path} (${route.source})`,
+        value: index,
+        selected: index < DEFAULT_PRESELECT_COUNT,
+    }));
+}
+function convertRouteToPage(route) {
+    return {
+        path: route.path,
+        label: route.label,
+        devices: DEFAULT_DEVICES,
+    };
+}
+async function buildConfig() {
+    const profileAnswer = await ask(profileQuestion);
+    const baseAnswers = await collectBaseAnswers();
+    const detectedPages = await maybeDetectPages(profileAnswer.profile);
+    const pages = await collectPages(detectedPages);
+    return {
+        baseUrl: baseAnswers.baseUrl,
+        query: baseAnswers.query,
+        chromePort: baseAnswers.chromePort,
+        runs: baseAnswers.runs,
+        pages,
+    };
+}
+export async function runWizardCli(argv) {
+    const args = parseArgs(argv);
+    const absolutePath = resolve(args.configPath);
+    await ensureWritable(absolutePath);
+    const config = await buildConfig();
+    await writeFile(absolutePath, `${JSON.stringify(config, null, 2)}\n`, "utf8");
+    console.log(`Saved ApexAuditor config to ${absolutePath}`);
+}

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "apex-auditor",
+  "version": "0.1.0",
+  "private": false,
+  "description": "CLI to run structured Lighthouse audits (Performance, Accessibility, Best Practices, SEO) across routes.",
+  "type": "module",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "bin": {
+    "apex-auditor": "./dist/bin.js"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "audit": "tsx src/bin.ts audit",
+    "wizard": "tsx src/bin.ts wizard",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "lighthouse": "^12.6.1",
+    "prompts": "^2.4.2"
+  },
+  "devDependencies": {
+    "tsx": "^4.20.6",
+    "typescript": "^5.9.3",
+    "@types/node": "^22.0.0",
+    "@types/prompts": "^2.4.9",
+    "vitest": "^1.3.1"
+  }
+}