apex-auditor 0.3.7 → 0.3.8

package/README.md

@@ -16,6 +16,8 @@ From your web project root:
 pnpm dlx apex-auditor@latest
 ```
 
+This is the recommended way to run ApexAuditor because it always uses the latest published version.
+
 Notes:
 
 - `init` can auto-detect your stack from `package.json` (Next.js, Nuxt, Remix/React Router, SvelteKit, SPA).
@@ -34,9 +36,15 @@ Inside the interactive shell:
 - **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)
+- **open-triage** (open `.apex-auditor/triage.md`)
+- **open-screenshots** (open `.apex-auditor/screenshots/`)
+- **open-diagnostics** (open `.apex-auditor/lighthouse-artifacts/diagnostics/`)
+- **open-lhr** (open `.apex-auditor/lighthouse-artifacts/lhr/`)
+- **open-artifacts** (open `.apex-auditor/lighthouse-artifacts/`)
 - **pages** / **routes** (print configured pages/routes from the current config)
 - **add-page** (interactive: append a page to `apex.config.json`)
 - **rm-page** (interactive: remove a page from `apex.config.json`)
+- **clear-screenshots** (remove `.apex-auditor/screenshots/`)
 - **init** (launch config wizard)
 - **config <path>** (switch config file)
 
@@ -52,6 +60,10 @@ Install as a dev dependency (recommended):
 pnpm add -D apex-auditor
 ```
 
+Note: `pnpm apex-auditor` runs the version installed in your current project, which may be older than the latest release.
+
+To always run the latest published version without installing:
+
 Or run without installing:
 
 ```bash
@@ -65,8 +77,15 @@ All outputs are written under `.apex-auditor/` in your project.
 ### `audit` outputs
 
 - `summary.json`
+- `summary-lite.json`
 - `summary.md`
+- `triage.md`
+- `issues.json`
 - `report.html`
+- `screenshots/` (when `audit --diagnostics` or `audit --lhr` is used)
+- `lighthouse-artifacts/diagnostics/` (when `audit --diagnostics` or `audit --lhr` is used)
+- `lighthouse-artifacts/diagnostics-lite/` (when `audit --diagnostics` or `audit --lhr` is used)
+- `lighthouse-artifacts/lhr/` (when `audit --lhr` is used)
 - `accessibility-summary.json`
 - `accessibility/` (axe-core artifacts per page/device)
 
@@ -75,10 +94,12 @@ Notes:
 - **Runs-per-combo is always 1**. Re-run the same command to compare results.
 - During an audit you will see a runtime progress line like `page X/Y — /path [device] | ETA ...`.
 - After `audit` completes, type `open` to open the latest HTML report.
+- Large JSON files may also be written as gzip copies (`*.json.gz`) to reduce disk size.
 
 ### `measure` outputs
 
 - `measure-summary.json`
+- `measure-summary-lite.json`
 - `measure/` (screenshots and artifacts)
 
 ### `bundle` outputs
@@ -105,6 +126,19 @@ Notes:
 
 ApexAuditor reads `apex.config.json` by default.
 
+Common fields:
+
+- `baseUrl`
+- `pages` (routes + devices)
+- `throttlingMethod` (`simulate` or `devtools`)
+- `cpuSlowdownMultiplier`
+- `parallel`
+- `warmUp`
+- `auditTimeoutMs`
+- `incremental` + `buildId`
+- `gitIgnoreApexAuditorDir` (auto-add `.apex-auditor/` to `.gitignore`)
+- `budgets`
+
 Example:
 
 ```json
@@ -125,6 +159,13 @@ Example:
 }
 ```
 
+## CLI tips
+
+- Use `pnpm dlx apex-auditor@latest` to avoid running an older installed version.
+- Use `audit --flags` to print all audit flags/options.
+- Use `audit --diagnostics` or `audit --lhr` when you want per-combo JSON artifacts and screenshots.
+- Start with `triage.md` and `issues.json` when the suite is large.
+
 ## Documentation
 
 The docs in `docs/` reflect the current shell-based workflow:

package/dist/bin.js

@@ -11,6 +11,7 @@ import { runHeadersCli } from "./headers-cli.js";
 import { runConsoleCli } from "./console-cli.js";
 import { runCleanCli } from "./clean-cli.js";
 import { runUninstallCli } from "./uninstall-cli.js";
+import { runClearScreenshotsCli } from "./clear-screenshots-cli.js";
 function parseBinArgs(argv) {
     const rawCommand = argv[2];
     if (rawCommand === undefined) {
@@ -32,6 +33,7 @@ function parseBinArgs(argv) {
         rawCommand === "console" ||
         rawCommand === "clean" ||
         rawCommand === "uninstall" ||
+        rawCommand === "clear-screenshots" ||
         rawCommand === "wizard" ||
         rawCommand === "quickstart" ||
         rawCommand === "guide" ||
@@ -107,31 +109,47 @@ function printHelp(topic) {
     console.log([
         "ApexAuditor CLI",
         "",
+        "Recommended run (always latest):",
+        "  pnpm dlx apex-auditor@latest",
+        "",
+        "Note:",
+        "  pnpm apex-auditor runs the version installed in the current project, which may be older.",
+        "",
         "Usage:",
         "  apex-auditor                 # interactive shell (default)",
         "  apex-auditor quickstart --base-url <url> [--project-root <path>]",
         "  apex-auditor wizard [--config <path>]",
         "  apex-auditor audit [--config <path>] [--ci] [--no-color|--color] [--log-level <level>]",
+        "  apex-auditor audit --flags    # print audit flags/options and exit",
         "  apex-auditor guide  (alias of wizard) interactive flow with tips for non-technical users",
         "  apex-auditor shell           # same as default entrypoint",
         "",
         "Commands:",
-        "  shell      Start interactive shell (audit/open/diff/preset/help/exit)",
-        "  quickstart  Detect routes and run a one-off audit with sensible defaults",
-        "  wizard     Run interactive config wizard",
-        "  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",
+        "  Interactive:",
+        "    shell      Start interactive shell (default)",
+        "    wizard     Run interactive config wizard",
+        "    guide      Same as wizard, with inline tips for non-technical users",
+        "    quickstart Detect routes and run a one-off audit with sensible defaults",
+        "",
+        "  Audits and checks:",
+        "    measure    Fast batch metrics (CDP-based, non-Lighthouse)",
+        "    audit      Run Lighthouse audits using apex.config.json",
+        "    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)",
+        "",
+        "  Maintenance:",
+        "    clean      Remove ApexAuditor artifacts (reports/cache and optionally config)",
+        "    uninstall  One-click uninstall (removes .apex-auditor/ and apex.config.json)",
+        "    clear-screenshots  Remove .apex-auditor/screenshots/",
+        "",
+        "  Help:",
+        "    help       Show this help message",
         "",
         "Options (audit):",
+        "  --flags            Print audit flags/options and exit",
         "  --ci               Enable CI mode with budgets and non-zero exit code on failure",
         "  --fail-on-budget   Exit non-zero if budgets fail even outside CI",
         "  --no-color         Disable ANSI colours in console output (default in CI mode)",
@@ -142,6 +160,8 @@ function printHelp(topic) {
         "  --desktop-only     Run audits only for 'desktop' devices defined in the config",
         "  --parallel <n>     Override parallel workers (1-10). Default auto-tunes from CPU/memory.",
         "  --audit-timeout-ms <ms>  Per-audit timeout in milliseconds (prevents hung runs from stalling)",
+        "  --diagnostics      Capture DevTools-like Lighthouse tables + screenshots (writes .apex-auditor/...)",
+        "  --lhr              Also capture full Lighthouse result JSON per combo (implies --diagnostics)",
         "  --plan             Print resolved settings + run size estimate and exit without auditing",
         "  --max-steps <n>    Safety limit: refuse/prompt if planned Lighthouse runs exceed this (default 120)",
         "  --max-combos <n>   Safety limit: refuse/prompt if planned page/device combos exceed this (default 60)",
@@ -217,6 +237,12 @@ function printHelp(topic) {
         "  --yes, -y              Skip confirmation prompt",
         "  --json                 Print JSON report to stdout",
         "",
+        "Options (clear-screenshots):",
+        "  --project-root <path>  Project root (default cwd)",
+        "  --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",
@@ -296,6 +322,10 @@ export async function runBin(argv) {
             await runUninstallCli(parsed.argv);
             return;
         }
+        if (parsed.command === "clear-screenshots") {
+            await runClearScreenshotsCli(parsed.argv);
+            return;
+        }
         if (parsed.command === "init" || parsed.command === "wizard" || parsed.command === "guide") {
             await runWizardCli(parsed.argv);
             return;

package/dist/clear-screenshots-cli.js

@@ -0,0 +1,97 @@
+import { rm } from "node:fs/promises";
+import { resolve } from "node:path";
+import readline from "node:readline";
+function parseArgs(argv) {
+    let projectRoot = process.cwd();
+    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 === "--dry-run") {
+            dryRun = true;
+            continue;
+        }
+        if (arg === "--yes" || arg === "-y") {
+            yes = true;
+            continue;
+        }
+        if (arg === "--json") {
+            jsonOutput = true;
+            continue;
+        }
+    }
+    return { projectRoot: resolve(projectRoot), 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 screenshotsDir = resolve(args.projectRoot, ".apex-auditor", "screenshots");
+    return [{ kind: "rm", path: screenshotsDir, existsByAssumption: true }];
+}
+async function executePlan(plan, dryRun) {
+    if (dryRun) {
+        return [];
+    }
+    const executed = [];
+    for (const action of plan) {
+        await rm(action.path, { recursive: true, force: true });
+        executed.push(action);
+    }
+    return executed;
+}
+export async function runClearScreenshotsCli(argv) {
+    const startedAtMs = Date.now();
+    const args = parseArgs(argv);
+    const planned = buildPlan(args);
+    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,
+            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}.`);
+}