apex-auditor 0.3.3 → 0.3.6

package/README.md

@@ -16,10 +16,23 @@ From your web project root:
 pnpm dlx apex-auditor@latest
 ```
 
+Notes:
+
+- `init` can auto-detect your stack from `package.json` (Next.js, Nuxt, Remix/React Router, SvelteKit, SPA).
+- In monorepos, `init` can prompt you to pick an app/package under `apps/` or `packages/`.
+- `init` can auto-discover routes from the filesystem and top-up from `robots.txt`/`sitemap.xml`. You can optionally filter detected routes with include/exclude patterns and still add manual routes.
+- For static sites, `init` can discover routes from HTML files under `dist/`, `build/`, `out/`, `public/`, and `src/`.
+- When using a localhost base URL (e.g. `http://localhost:3000`), make sure the dev server port matches the project you’re configuring (important when multiple projects are running).
+
 Inside the interactive shell:
 
 - **measure**
 - **audit**
+- **bundle** (scan build output sizes; writes `.apex-auditor/bundle-audit.json`)
+- **health** (HTTP status/latency checks; writes `.apex-auditor/health.json`)
+- **links** (broken links crawl; writes `.apex-auditor/links.json`)
+- **headers** (security headers check; writes `.apex-auditor/headers.json`)
+- **console** (console errors + runtime exceptions; writes `.apex-auditor/console.json`)
 - **open** (open the latest HTML report)
 - **init** (launch config wizard)
 - **config <path>** (switch config file)
@@ -65,6 +78,26 @@ Notes:
 - `measure-summary.json`
 - `measure/` (screenshots and artifacts)
 
+### `bundle` outputs
+
+- `bundle-audit.json`
+
+### `health` outputs
+
+- `health.json`
+
+### `links` outputs
+
+- `links.json`
+
+### `headers` outputs
+
+- `headers.json`
+
+### `console` outputs
+
+- `console.json`
+
 ## Configuration
 
 ApexAuditor reads `apex.config.json` by default.
@@ -97,6 +130,13 @@ The docs in `docs/` reflect the current shell-based workflow:
 - `docs/configuration-and-routes.md`
 - `docs/cli-and-ci.md`
 
+## Known issues
+
+- **Shell exits after init wizard**: in some environments, the process may exit after completing `init` in shell mode. Workaround: run `apex-auditor init` outside the shell, then re-run `apex-auditor shell`.
+- **Large-run Lighthouse stability**: very large audits (many page/device combinations) may show higher score variance than manual Lighthouse runs and can intermittently hit worker/Chrome disconnects. Workaround: reduce parallelism (e.g. `--stable`) and retry.
+
+The target for a truly stable release is after v0.3.7.
+
 ## License
 
 MIT

package/dist/bin.js

@@ -4,6 +4,13 @@ import { runWizardCli } from "./wizard-cli.js";
 import { runQuickstartCli } from "./quickstart-cli.js";
 import { runShellCli } from "./shell-cli.js";
 import { runMeasureCli } from "./measure-cli.js";
+import { runBundleCli } from "./bundle-cli.js";
+import { runHealthCli } from "./health-cli.js";
+import { runLinksCli } from "./links-cli.js";
+import { runHeadersCli } from "./headers-cli.js";
+import { runConsoleCli } from "./console-cli.js";
+import { runCleanCli } from "./clean-cli.js";
+import { runUninstallCli } from "./uninstall-cli.js";
 function parseBinArgs(argv) {
     const rawCommand = argv[2];
     if (rawCommand === undefined) {
@@ -18,6 +25,13 @@ function parseBinArgs(argv) {
     }
     if (rawCommand === "audit" ||
         rawCommand === "measure" ||
+        rawCommand === "bundle" ||
+        rawCommand === "health" ||
+        rawCommand === "links" ||
+        rawCommand === "headers" ||
+        rawCommand === "console" ||
+        rawCommand === "clean" ||
+        rawCommand === "uninstall" ||
         rawCommand === "wizard" ||
         rawCommand === "quickstart" ||
         rawCommand === "guide" ||
@@ -108,6 +122,13 @@ function printHelp(topic) {
         "  guide      Same as wizard, with inline tips for non-technical users",
         "  audit      Run Lighthouse audits using apex.config.json",
         "  measure    Fast batch metrics (CDP-based, non-Lighthouse)",
+        "  bundle     Bundle size audit (Next.js .next/ or dist/ build output)",
+        "  health     HTTP status + latency checks for configured routes",
+        "  links      Broken links audit (sitemap + HTML link extraction)",
+        "  headers    Security headers audit",
+        "  console    Console errors + runtime exceptions audit (headless Chrome)",
+        "  clean      Remove ApexAuditor artifacts (reports/cache and optionally config)",
+        "  uninstall  One-click uninstall (removes .apex-auditor/ and apex.config.json)",
         "  help       Show this help message",
         "",
         "Options (audit):",
@@ -127,7 +148,7 @@ function printHelp(topic) {
         "  --yes, -y          Auto-confirm large runs (bypass safety prompt)",
         "  --changed-only     Run only pages whose paths match files in git diff --name-only (working tree diff)",
         "  --rerun-failing    Re-run only combos that failed in the previous summary (runtime errors or perf<90)",
-        "  --accessibility-pass  Run a fast axe-core accessibility sweep after audits (lightweight, CDP-based)",
+        "  --accessibility-pass  Opt-in: run a fast axe-core accessibility sweep after audits (lightweight, CDP-based)",
         "  --webhook-url <url> Send a JSON webhook with regressions/budgets/accessibility (regressions-only summary)",
         "  --show-parallel    Print the resolved parallel workers before running.",
         "  --incremental      Reuse cached results for unchanged combos (requires --build-id). Opt-in; off by default.",
@@ -138,6 +159,64 @@ function printHelp(topic) {
         "  --accurate         Preset: devtools throttling + warm-up + stability-first (parallel=1 unless overridden)",
         "  --open             Open the HTML report after the run.",
         "",
+        "Options (measure):",
+        "  --mobile-only      Run measure only for 'mobile' devices defined in the config",
+        "  --desktop-only     Run measure only for 'desktop' devices defined in the config",
+        "  --parallel <n>     Override parallel workers (1-10).",
+        "  --timeout-ms <ms>  Per-navigation timeout in milliseconds (default 60000)",
+        "  --screenshots      Opt-in: save a screenshot per combo (slower; writes .apex-auditor/measure/*.png)",
+        "  --json             Print JSON summary to stdout",
+        "",
+        "Options (bundle):",
+        "  --project-root <path>  Project root to scan (default cwd)",
+        "  --top <n>              Show top N largest files (default 15)",
+        "  --json                 Print JSON report to stdout",
+        "",
+        "Options (health):",
+        "  --config <path>        Config path (default apex.config.json)",
+        "  --parallel <n>         Parallel requests (default auto)",
+        "  --timeout-ms <ms>      Per-request timeout (default 20000)",
+        "  --json                 Print JSON report to stdout",
+        "",
+        "Options (links):",
+        "  --config <path>        Config path (default apex.config.json)",
+        "  --sitemap <url>        Override sitemap URL (default <baseUrl>/sitemap.xml)",
+        "  --parallel <n>         Parallel requests (default auto)",
+        "  --timeout-ms <ms>      Per-request timeout (default 20000)",
+        "  --max-urls <n>         Limit total URLs checked (default 200)",
+        "  --json                 Print JSON report to stdout",
+        "",
+        "Options (headers):",
+        "  --config <path>        Config path (default apex.config.json)",
+        "  --parallel <n>         Parallel requests (default auto)",
+        "  --timeout-ms <ms>      Per-request timeout (default 20000)",
+        "  --json                 Print JSON report to stdout",
+        "",
+        "Options (console):",
+        "  --config <path>        Config path (default apex.config.json)",
+        "  --parallel <n>         Parallel workers (default auto)",
+        "  --timeout-ms <ms>      Per-navigation timeout (default 60000)",
+        "  --max-events <n>       Cap captured events per combo (default 50)",
+        "  --json                 Print JSON report to stdout",
+        "",
+        "Options (clean):",
+        "  --project-root <path>  Project root (default cwd)",
+        "  --config-path <path>   Config file path relative to project root (default apex.config.json)",
+        "  --reports              Remove .apex-auditor/ (default)",
+        "  --no-reports           Keep .apex-auditor/",
+        "  --remove-config        Remove config file",
+        "  --all                  Remove reports and config",
+        "  --dry-run              Print planned removals without deleting",
+        "  --yes, -y              Skip confirmation prompt",
+        "  --json                 Print JSON report to stdout",
+        "",
+        "Options (uninstall):",
+        "  --project-root <path>  Project root (default cwd)",
+        "  --config-path <path>   Config file path relative to project root (default apex.config.json)",
+        "  --dry-run              Print planned removals without deleting",
+        "  --yes, -y              Skip confirmation prompt",
+        "  --json                 Print JSON report to stdout",
+        "",
         "Outputs:",
         "  - Writes .apex-auditor/summary.json, summary.md, report.html",
         "  - Prints a file:// link to the HTML report after completion",
@@ -159,6 +238,9 @@ function printHelp(topic) {
         "  apex-auditor help budgets",
     ].join("\n"));
 }
+function isInteractiveTty() {
+    return Boolean(process.stdin.isTTY && process.stdout.isTTY);
+}
 export async function runBin(argv) {
     const parsed = parseBinArgs(argv);
     if (parsed.command === "help") {
@@ -172,63 +254,67 @@ export async function runBin(argv) {
     }
     if (parsed.command === "quickstart") {
         await runQuickstartCli(parsed.argv);
+        if (isInteractiveTty()) {
+            await runShellCli(["node", "apex-auditor"]);
+        }
         return;
     }
-    if (parsed.command === "audit") {
-        try {
+    const runOnce = async () => {
+        if (parsed.command === "audit") {
             await runAuditCli(parsed.argv);
+            return;
         }
-        catch (error) {
-            const message = error instanceof Error ? error.message : String(error);
-            if (message.includes("ENOENT")) {
-                // eslint-disable-next-line no-console
-                console.error("Config file not found. Run `apex-auditor init` to create a config or set one with `config <path>`.");
-                return;
-            }
-            throw error;
+        if (parsed.command === "measure") {
+            await runMeasureCli(parsed.argv);
+            return;
         }
-        if (process.stdin.isTTY && process.stdout.isTTY) {
-            // eslint-disable-next-line no-console
-            console.log("\nAudit completed. Press Ctrl+C to exit, or enter another command (type help for options).");
-            await runShellCli(["node", "apex-auditor"]);
+        if (parsed.command === "bundle") {
+            await runBundleCli(parsed.argv);
+            return;
         }
-        return;
-    }
-    if (parsed.command === "measure") {
-        try {
-            await runMeasureCli(parsed.argv);
+        if (parsed.command === "health") {
+            await runHealthCli(parsed.argv);
+            return;
         }
-        catch (error) {
-            const message = error instanceof Error ? error.message : String(error);
-            if (message.includes("ENOENT")) {
-                // eslint-disable-next-line no-console
-                console.error("Config file not found. Run `apex-auditor init` to create a config or set one with `config <path>`.");
-                return;
-            }
-            throw error;
+        if (parsed.command === "links") {
+            await runLinksCli(parsed.argv);
+            return;
         }
-        if (process.stdin.isTTY && process.stdout.isTTY) {
-            // eslint-disable-next-line no-console
-            console.log("\nMeasure run completed. Press Ctrl+C to exit, or enter another command (type help for options).");
-            await runShellCli(["node", "apex-auditor"]);
+        if (parsed.command === "headers") {
+            await runHeadersCli(parsed.argv);
+            return;
         }
-        return;
+        if (parsed.command === "console") {
+            await runConsoleCli(parsed.argv);
+            return;
+        }
+        if (parsed.command === "clean") {
+            await runCleanCli(parsed.argv);
+            return;
+        }
+        if (parsed.command === "uninstall") {
+            await runUninstallCli(parsed.argv);
+            return;
+        }
+        if (parsed.command === "init" || parsed.command === "wizard" || parsed.command === "guide") {
+            await runWizardCli(parsed.argv);
+            return;
+        }
+    };
+    try {
+        await runOnce();
     }
-    if (parsed.command === "init") {
-        await runWizardCli(parsed.argv);
-        if (process.stdin.isTTY && process.stdout.isTTY) {
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        if (message.includes("ENOENT")) {
             // eslint-disable-next-line no-console
-            console.log("\nConfig initialized. Press Ctrl+C to exit, or enter another command (type help for options).");
-            await runShellCli(["node", "apex-auditor"]);
+            console.error("Config file not found. Run `apex-auditor init` to create a config or set one with `config <path>`.");
+            return;
         }
-        return;
+        throw error;
     }
-    if (parsed.command === "wizard" || parsed.command === "guide") {
-        await runWizardCli(parsed.argv);
-        if (process.stdin.isTTY && process.stdout.isTTY) {
-            await runShellCli(["node", "apex-auditor"]);
-        }
-        return;
+    if (isInteractiveTty()) {
+        await runShellCli(["node", "apex-auditor"]);
     }
 }
 void runBin(process.argv).catch((error) => {

package/dist/bundle-cli.js

@@ -0,0 +1,158 @@
+import { mkdir, readdir, stat, writeFile } from "node:fs/promises";
+import { join, relative, resolve } from "node:path";
+import { renderPanel } from "./ui/render-panel.js";
+import { renderTable } from "./ui/render-table.js";
+import { UiTheme } from "./ui/ui-theme.js";
+import { stopSpinner } from "./spinner.js";
+const NO_COLOR = Boolean(process.env.NO_COLOR) || process.env.CI === "true";
+const theme = new UiTheme({ noColor: NO_COLOR });
+function formatBytes(bytes) {
+    const kb = bytes / 1024;
+    if (kb < 1024) {
+        return `${Math.round(kb)}KB`;
+    }
+    const mb = kb / 1024;
+    return `${mb.toFixed(1)}MB`;
+}
+async function pathExists(path) {
+    try {
+        await stat(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function walkFiles(params) {
+    const entries = [];
+    const visitDir = async (dir) => {
+        if (params.signal?.aborted) {
+            throw new Error("Aborted");
+        }
+        const children = await readdir(dir);
+        for (const name of children) {
+            if (params.signal?.aborted) {
+                throw new Error("Aborted");
+            }
+            const absolute = join(dir, name);
+            const s = await stat(absolute);
+            if (s.isDirectory()) {
+                await visitDir(absolute);
+                continue;
+            }
+            const matchedExt = params.extensions.find((ext) => name.endsWith(ext));
+            if (!matchedExt) {
+                continue;
+            }
+            const kind = matchedExt === ".css" ? "css" : "js";
+            const rel = relative(params.base, absolute).replace(/\\/g, "/");
+            entries.push({ kind, relativePath: rel, bytes: s.size });
+        }
+    };
+    await visitDir(params.root);
+    return entries;
+}
+function parseArgs(argv) {
+    let projectRoot = process.cwd();
+    let jsonOutput = false;
+    let top = 15;
+    for (let i = 2; i < argv.length; i += 1) {
+        const arg = argv[i];
+        if ((arg === "--project-root" || arg === "--root") && i + 1 < argv.length) {
+            projectRoot = argv[i + 1] ?? projectRoot;
+            i += 1;
+        }
+        else if (arg === "--json") {
+            jsonOutput = true;
+        }
+        else if (arg === "--top" && i + 1 < argv.length) {
+            const value = parseInt(argv[i + 1] ?? "", 10);
+            if (!Number.isFinite(value) || value <= 0 || value > 100) {
+                throw new Error(`Invalid --top value: ${argv[i + 1]}. Expected 1-100.`);
+            }
+            top = value;
+            i += 1;
+        }
+    }
+    return { projectRoot, jsonOutput, top };
+}
+function buildTopFilesTable(entries, top) {
+    const rows = [...entries]
+        .sort((a, b) => b.bytes - a.bytes)
+        .slice(0, top)
+        .map((f) => [f.kind, formatBytes(f.bytes), f.relativePath]);
+    if (rows.length === 0) {
+        return "";
+    }
+    return renderTable({ headers: ["Type", "Size", "File"], rows });
+}
+export async function runBundleCli(argv, options) {
+    stopSpinner();
+    const args = parseArgs(argv);
+    const projectRoot = resolve(args.projectRoot);
+    const nextDir = resolve(projectRoot, ".next");
+    const distDir = resolve(projectRoot, "dist");
+    const hasNext = await pathExists(nextDir);
+    const hasDist = await pathExists(distDir);
+    const scanTargets = [
+        hasNext ? resolve(nextDir, "static") : "",
+        hasDist ? distDir : "",
+    ].filter((p) => p.length > 0);
+    const allEntries = [];
+    for (const target of scanTargets) {
+        if (options?.signal?.aborted) {
+            throw new Error("Aborted");
+        }
+        const entries = await walkFiles({
+            root: target,
+            base: projectRoot,
+            extensions: [".js", ".css"],
+            signal: options?.signal,
+        });
+        allEntries.push(...entries);
+    }
+    const jsBytes = allEntries.filter((e) => e.kind === "js").reduce((sum, e) => sum + e.bytes, 0);
+    const cssBytes = allEntries.filter((e) => e.kind === "css").reduce((sum, e) => sum + e.bytes, 0);
+    const topFiles = [...allEntries].sort((a, b) => b.bytes - a.bytes).slice(0, args.top);
+    const report = {
+        meta: {
+            projectRoot,
+            scannedAt: new Date().toISOString(),
+            detected: { nextDir: hasNext, distDir: hasDist },
+        },
+        totals: {
+            jsBytes,
+            cssBytes,
+            fileCount: allEntries.length,
+        },
+        topFiles,
+        files: allEntries,
+    };
+    const outputDir = resolve(projectRoot, ".apex-auditor");
+    const outputPath = resolve(outputDir, "bundle-audit.json");
+    await mkdir(outputDir, { recursive: true });
+    await writeFile(outputPath, JSON.stringify(report, null, 2), "utf8");
+    if (args.jsonOutput) {
+        // eslint-disable-next-line no-console
+        console.log(JSON.stringify(report, null, 2));
+        return;
+    }
+    const detectedText = [hasNext ? ".next" : "", hasDist ? "dist" : ""].filter((v) => v.length > 0).join(", ") || "(none)";
+    const lines = [
+        `Project: ${projectRoot}`,
+        `Detected: ${detectedText}`,
+        `Files: ${report.totals.fileCount}`,
+        `JS: ${formatBytes(report.totals.jsBytes)}`,
+        `CSS: ${formatBytes(report.totals.cssBytes)}`,
+        `Output: ${relative(projectRoot, outputPath).replace(/\\/g, "/")}`,
+    ];
+    // eslint-disable-next-line no-console
+    console.log(renderPanel({ title: theme.bold("Bundle"), lines }));
+    const table = buildTopFilesTable(allEntries, args.top);
+    if (table.length > 0) {
+        // eslint-disable-next-line no-console
+        console.log(`\n${theme.bold(`Largest files (top ${args.top})`)}`);
+        // eslint-disable-next-line no-console
+        console.log(table);
+    }
+}

package/dist/clean-cli.js

@@ -0,0 +1,159 @@
+import { rm } from "node:fs/promises";
+import { resolve } from "node:path";
+import readline from "node:readline";
+function parseArgs(argv) {
+    let projectRoot = process.cwd();
+    let configPath = "apex.config.json";
+    let removeReports = true;
+    let removeConfig = false;
+    let dryRun = false;
+    let yes = false;
+    let jsonOutput = false;
+    for (let i = 2; i < argv.length; i += 1) {
+        const arg = argv[i] ?? "";
+        if (arg === "--project-root" && i + 1 < argv.length) {
+            projectRoot = argv[i + 1] ?? projectRoot;
+            i += 1;
+            continue;
+        }
+        if ((arg === "--config-path" || arg === "--config") && i + 1 < argv.length) {
+            configPath = argv[i + 1] ?? configPath;
+            i += 1;
+            continue;
+        }
+        if (arg === "--reports") {
+            removeReports = true;
+            continue;
+        }
+        if (arg === "--no-reports") {
+            removeReports = false;
+            continue;
+        }
+        if (arg === "--remove-config") {
+            removeConfig = true;
+            continue;
+        }
+        if (arg === "--all") {
+            removeReports = true;
+            removeConfig = true;
+            continue;
+        }
+        if (arg === "--dry-run") {
+            dryRun = true;
+            continue;
+        }
+        if (arg === "--yes" || arg === "-y") {
+            yes = true;
+            continue;
+        }
+        if (arg === "--json") {
+            jsonOutput = true;
+            continue;
+        }
+    }
+    return {
+        projectRoot: resolve(projectRoot),
+        configPath: resolve(projectRoot, configPath),
+        removeReports,
+        removeConfig,
+        dryRun,
+        yes,
+        jsonOutput,
+    };
+}
+async function confirmPrompt(question) {
+    if (!process.stdin.isTTY) {
+        return false;
+    }
+    process.stdin.resume();
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    try {
+        const answer = await new Promise((resolvePromise) => {
+            rl.question(question, (value) => resolvePromise(value));
+        });
+        const text = answer.trim().toLowerCase();
+        return text === "y" || text === "yes";
+    }
+    finally {
+        rl.close();
+    }
+}
+function buildPlan(args) {
+    const actions = [];
+    if (args.removeReports) {
+        actions.push({ kind: "rm", path: resolve(args.projectRoot, ".apex-auditor"), existsByAssumption: true });
+    }
+    if (args.removeConfig) {
+        actions.push({ kind: "rm", path: args.configPath, existsByAssumption: true });
+    }
+    return actions;
+}
+async function executePlan(plan, dryRun) {
+    if (dryRun) {
+        return [];
+    }
+    const executed = [];
+    for (const action of plan) {
+        if (action.kind === "rm") {
+            await rm(action.path, { recursive: true, force: true });
+            executed.push(action);
+        }
+    }
+    return executed;
+}
+export async function runCleanCli(argv) {
+    const startedAtMs = Date.now();
+    const args = parseArgs(argv);
+    const planned = buildPlan(args);
+    if (planned.length === 0) {
+        const empty = {
+            meta: {
+                projectRoot: args.projectRoot,
+                configPath: args.configPath,
+                dryRun: args.dryRun,
+                startedAt: new Date(startedAtMs).toISOString(),
+                completedAt: new Date(startedAtMs).toISOString(),
+                elapsedMs: 0,
+            },
+            planned: [],
+            executed: [],
+        };
+        if (args.jsonOutput) {
+            console.log(JSON.stringify(empty, null, 2));
+            return;
+        }
+        console.log("Nothing to clean.");
+        return;
+    }
+    if (!args.yes && process.stdin.isTTY) {
+        const targets = planned.map((p) => p.path).join("\n");
+        const ok = await confirmPrompt(`This will remove:\n${targets}\nContinue? (y/N) `);
+        if (!ok) {
+            console.log("Cancelled.");
+            return;
+        }
+    }
+    const executed = await executePlan(planned, args.dryRun);
+    const completedAtMs = Date.now();
+    const report = {
+        meta: {
+            projectRoot: args.projectRoot,
+            configPath: args.configPath,
+            dryRun: args.dryRun,
+            startedAt: new Date(startedAtMs).toISOString(),
+            completedAt: new Date(completedAtMs).toISOString(),
+            elapsedMs: completedAtMs - startedAtMs,
+        },
+        planned,
+        executed,
+    };
+    if (args.jsonOutput) {
+        console.log(JSON.stringify(report, null, 2));
+        return;
+    }
+    if (args.dryRun) {
+        console.log(`Planned removals: ${planned.length} (dry-run).`);
+        return;
+    }
+    console.log(`Removed: ${executed.length}/${planned.length}.`);
+}