apex-auditor 0.3.5 → 0.3.7

package/README.md

@@ -20,6 +20,9 @@ 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 larger route sets, the wizard may default filtering to **Yes** and prefill common excludes (framework-specific).
+- 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:
 
@@ -31,6 +34,9 @@ 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)
+- **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`)
 - **init** (launch config wizard)
 - **config <path>** (switch config file)
 
@@ -127,6 +133,10 @@ The docs in `docs/` reflect the current shell-based workflow:
 - `docs/configuration-and-routes.md`
 - `docs/cli-and-ci.md`
 
+## Known issues
+
+- **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.
+
 ## License
 
 MIT

package/dist/bin.js

@@ -10,6 +10,7 @@ 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) {
@@ -30,6 +31,7 @@ function parseBinArgs(argv) {
         rawCommand === "headers" ||
         rawCommand === "console" ||
         rawCommand === "clean" ||
+        rawCommand === "uninstall" ||
         rawCommand === "wizard" ||
         rawCommand === "quickstart" ||
         rawCommand === "guide" ||
@@ -126,6 +128,7 @@ function printHelp(topic) {
         "  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):",
@@ -207,6 +210,13 @@ function printHelp(topic) {
         "  --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",
@@ -282,6 +292,10 @@ export async function runBin(argv) {
             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;

package/dist/cli.js

@@ -1139,15 +1139,24 @@ export async function runAuditCli(argv, options) {
     const plannedCombos = overviewSample.config.pages.reduce((acc, p) => acc + p.devices.length, 0);
     const plannedRuns = overviewSample.config.runs ?? 1;
     const plannedSteps = plannedCombos * plannedRuns;
+    const LARGE_RUN_COMBOS_THRESHOLD = 76;
+    const LARGE_RUN_PARALLEL_CAP = 4;
+    const usingDefaultParallel = args.parallelOverride === undefined && presetParallel === undefined && config.parallel === undefined;
+    const isLargeRun = plannedCombos >= LARGE_RUN_COMBOS_THRESHOLD;
+    const autoStableLargeRun = isLargeRun && !args.stable && usingDefaultParallel;
+    const resolvedConfigForRun = autoStableLargeRun
+        ? { ...overviewSample.config, parallel: Math.min(overviewSample.config.parallel ?? DEFAULT_PARALLEL, LARGE_RUN_PARALLEL_CAP) }
+        : overviewSample.config;
     const maxSteps = args.maxSteps ?? DEFAULT_MAX_STEPS;
     const maxCombos = args.maxCombos ?? DEFAULT_MAX_COMBOS;
     const isTty = typeof process !== "undefined" && process.stdout?.isTTY === true;
+    const LARGE_RUN_HINT_COMBOS_THRESHOLD = 40;
     const exceeds = plannedSteps > maxSteps || plannedCombos > maxCombos;
     const useColor = shouldUseColor(args.ci, args.colorMode);
     if (args.plan) {
         printPlan({
             configPath,
-            resolvedConfig: overviewSample.config,
+            resolvedConfig: resolvedConfigForRun,
             plannedCombos,
             plannedSteps,
             sampled: overviewSample.sampled,
@@ -1158,15 +1167,13 @@ export async function runAuditCli(argv, options) {
         });
         return;
     }
-    if (isTty && !args.ci && !args.jsonOutput) {
-        const tipLines = [
-            "Tip: use --plan to preview run size before starting.",
-            "Note: runs-per-combo is always 1; rerun the same command to compare results.",
-            "If parallel mode flakes (worker disconnects), retry with --stable (forces parallel=1).",
-        ];
+    if (isTty && !args.ci && !args.jsonOutput && plannedCombos >= LARGE_RUN_HINT_COMBOS_THRESHOLD) {
         // eslint-disable-next-line no-console
-        console.log(boxifyWithSeparators(tipLines));
-        printDivider();
+        console.log(`Tip: large run (${plannedCombos} combos). Use --plan to preview, and retry with --stable if parallel mode flakes.`);
+    }
+    if (autoStableLargeRun && isTty && !args.ci && !args.jsonOutput) {
+        // eslint-disable-next-line no-console
+        console.log(`Large run detected (${plannedCombos} combos). Using stability mode: parallel capped to ${resolvedConfigForRun.parallel}. Override with --parallel <n> or --stable (parallel=1).`);
     }
     if (overviewSample.sampled) {
         // eslint-disable-next-line no-console
@@ -1233,7 +1240,7 @@ export async function runAuditCli(argv, options) {
     }
     try {
         summary = await runAuditsForConfig({
-            config: overviewSample.config,
+            config: resolvedConfigForRun,
             configPath,
             showParallel: args.showParallel,
             onlyCategories,
@@ -1244,11 +1251,8 @@ export async function runAuditCli(argv, options) {
                     return;
                 }
                 const etaText = etaMs !== undefined ? ` | ETA ${formatEtaText(etaMs)}` : "";
-                const message = `* Running audit (Lighthouse) page ${completed}/${total} — ${path} [${device}]${etaText}`;
-                const padded = message.padEnd(lastProgressLine?.length ?? message.length, " ");
-                process.stdout.write(`\r${padded}`);
-                lastProgressLine = padded;
-                updateSpinnerMessage(`Running audit (Lighthouse) page ${completed}/${total}`);
+                startAuditSpinner();
+                updateSpinnerMessage(`Running audit (Lighthouse) page ${completed}/${total} — ${path} [${device}]${etaText}`);
             },
         });
     }

package/dist/lighthouse-runner.js

@@ -347,6 +347,11 @@ async function createChromeSession(chromePort) {
             "--safebrowsing-disable-auto-update",
             "--password-store=basic",
             "--use-mock-keychain",
+            // Stability flags for parallel runs
+            "--disable-hang-monitor",
+            "--disable-ipc-flooding-protection",
+            "--disable-domain-reliability",
+            "--disable-component-update",
         ],
     });
     return {
@@ -741,7 +746,14 @@ function isTransientLighthouseError(error) {
         message.includes("LanternError") ||
         message.includes("top level events") ||
         message.includes("CDP") ||
-        message.includes("disconnected"));
+        message.includes("disconnected") ||
+        // Additional transient errors for better retry handling
+        message.includes("WebSocket") ||
+        message.includes("webSocket") ||
+        message.includes("fetch failed") ||
+        message.includes("ECONNREFUSED") ||
+        message.includes("ECONNRESET") ||
+        message.includes("socket hang up"));
 }
 async function runSingleAuditWithRetry({ task, sessionRef, updateProgress, maxRetries, }) {
     let attempt = 0;

package/dist/lighthouse-worker.js

@@ -13,7 +13,14 @@ function isTransientLighthouseError(error) {
         message.includes("top level events") ||
         message.includes("CDP") ||
         message.includes("disconnected") ||
-        message.includes("ApexAuditor timeout"));
+        message.includes("ApexAuditor timeout") ||
+        // Additional transient errors for better retry handling
+        message.includes("WebSocket") ||
+        message.includes("webSocket") ||
+        message.includes("fetch failed") ||
+        message.includes("ECONNREFUSED") ||
+        message.includes("ECONNRESET") ||
+        message.includes("socket hang up"));
 }
 async function createChromeSession() {
     const userDataDir = await mkdtemp(join(tmpdir(), "apex-auditor-chrome-"));
@@ -39,6 +46,11 @@ async function createChromeSession() {
             "--safebrowsing-disable-auto-update",
             "--password-store=basic",
             "--use-mock-keychain",
+            // Stability flags for parallel runs
+            "--disable-hang-monitor",
+            "--disable-ipc-flooding-protection",
+            "--disable-domain-reliability",
+            "--disable-component-update",
         ],
     });
     return {
@@ -212,8 +224,9 @@ function send(message) {
     }
 }
 async function main() {
-    const maxRetries = 2;
-    const maxTasksPerChrome = 20;
+    const maxRetries = 3;
+    // Recycle Chrome periodically to prevent memory leaks
+    const maxTasksPerChrome = 10;
     const sessionRef = { session: await createChromeSession() };
     let tasksSinceChromeStart = 0;
     process.on("message", async (raw) => {
@@ -238,7 +251,7 @@ async function main() {
                 await sessionRef.session.close();
             }
             catch {
-                return;
+                // Ignore close errors
             }
             sessionRef.session = await createChromeSession();
             tasksSinceChromeStart = 0;

package/dist/route-detectors.js

@@ -10,6 +10,7 @@ const SOURCE_NUXT_PAGES = "nuxt-pages";
 const SOURCE_REMIX = "remix-routes";
 const SOURCE_SVELTEKIT = "sveltekit-routes";
 const SOURCE_SPA = "spa-html";
+const SOURCE_STATIC_HTML = "static-html";
 const ROUTE_DETECTORS = [
     createNextAppDetector(),
     createNextPagesDetector(),
@@ -17,6 +18,7 @@ const ROUTE_DETECTORS = [
     createRemixRoutesDetector(),
     createSvelteKitRoutesDetector(),
     createSpaHtmlDetector(),
+    createStaticHtmlDetector(),
 ];
 export async function detectRoutes(options) {
     const limit = options.limit ?? DEFAULT_LIMIT;
@@ -134,6 +136,37 @@ function createSpaHtmlDetector() {
         detect: async (options) => detectSpaRoutes(options.projectRoot, options.limit),
     };
 }
+function createStaticHtmlDetector() {
+    return {
+        id: SOURCE_STATIC_HTML,
+        canDetect: async (options) => {
+            const roots = await findStaticHtmlRoots(options.projectRoot);
+            return roots.length > 0;
+        },
+        detect: async (options) => {
+            const roots = await findStaticHtmlRoots(options.projectRoot);
+            const allRoutes = [];
+            const seenPaths = new Set();
+            for (const root of roots) {
+                const routes = await detectStaticHtmlRoutes(root, options.limit - allRoutes.length);
+                for (const route of routes) {
+                    if (allRoutes.length >= options.limit) {
+                        break;
+                    }
+                    if (seenPaths.has(route.path)) {
+                        continue;
+                    }
+                    seenPaths.add(route.path);
+                    allRoutes.push(route);
+                }
+                if (allRoutes.length >= options.limit) {
+                    break;
+                }
+            }
+            return allRoutes;
+        },
+    };
+}
 async function findNextAppRoots(projectRoot) {
     const roots = [];
     const seen = new Set();
@@ -293,6 +326,28 @@ async function detectSpaRoutes(projectRoot, limit) {
     const routes = extractRoutesFromHtml(html).slice(0, limit);
     return routes.map((routePath) => ({ path: routePath, label: buildLabel(routePath), source: SOURCE_SPA }));
 }
+async function findStaticHtmlRoots(projectRoot) {
+    const candidates = [
+        join(projectRoot, "dist"),
+        join(projectRoot, "build"),
+        join(projectRoot, "out"),
+        join(projectRoot, "public"),
+        join(projectRoot, "src"),
+    ];
+    const existing = [];
+    for (const candidate of candidates) {
+        if (await pathExists(candidate)) {
+            existing.push(candidate);
+        }
+    }
+    return existing;
+}
+async function detectStaticHtmlRoutes(root, limit) {
+    const files = await collectRouteFiles(root, limit, isStaticHtmlFile);
+    return files
+        .map((filePath) => buildRoute(filePath, root, formatStaticHtmlRoutePath, SOURCE_STATIC_HTML))
+        .filter((route) => !shouldSkipStaticHtmlRoute(route.path));
+}
 async function collectRouteFiles(root, limit, matcher) {
     const stack = [root];
     const files = [];
@@ -399,6 +454,16 @@ function hasAllowedExtension(path) {
 function hasAllowedNuxtExtension(path) {
     return NUXT_PAGE_EXTENSIONS.some((extension) => path.endsWith(extension));
 }
+function isStaticHtmlFile(entry, relativePath) {
+    if (!entry.isFile()) {
+        return false;
+    }
+    const posixPath = normalisePath(relativePath);
+    if (!posixPath.toLowerCase().endsWith(".html")) {
+        return false;
+    }
+    return !posixPath.split("/").some((segment) => segment.startsWith("."));
+}
 function buildRoute(filePath, root, formatter, source) {
     const relativePath = normalisePath(relative(root, filePath));
     const routePath = formatter(relativePath);
@@ -505,6 +570,18 @@ function formatSvelteKitRoutePath(relativePath) {
     }
     return normaliseRoute(parts.join("/"));
 }
+function formatStaticHtmlRoutePath(relativePath) {
+    const cleanPath = relativePath.replace(/\\/g, "/");
+    const withoutExt = cleanPath.replace(/\.html$/i, "");
+    const withoutIndex = withoutExt.endsWith("/index") ? withoutExt.slice(0, -6) : withoutExt;
+    const normalized = withoutIndex.replace(/^\/+/, "");
+    return normalized.length === 0 ? "/" : normaliseRoute(normalized);
+}
+function shouldSkipStaticHtmlRoute(routePath) {
+    const normalized = routePath.toLowerCase();
+    const banned = ["/404", "/500", "/_error"];
+    return banned.includes(normalized);
+}
 function normaliseRoute(path) {
     const trimmed = path.replace(/^\/+/, "");
     if (trimmed.length === 0) {

package/dist/shell-cli.js

@@ -12,8 +12,11 @@ import { runLinksCli } from "./links-cli.js";
 import { runMeasureCli } from "./measure-cli.js";
 import { runWizardCli } from "./wizard-cli.js";
 import { runCleanCli } from "./clean-cli.js";
+import { runUninstallCli } from "./uninstall-cli.js";
+import { loadConfig } from "./config.js";
 import { pathExists } from "./fs-utils.js";
 import { renderPanel } from "./ui/render-panel.js";
+import { renderTable } from "./ui/render-table.js";
 import { startSpinner, stopSpinner } from "./spinner.js";
 import { UiTheme } from "./ui/ui-theme.js";
 const SESSION_DIR_NAME = ".apex-auditor";
@@ -123,6 +126,148 @@ async function runConsoleAuditFromShell(session, args) {
 async function writeJsonFile(absolutePath, value) {
     await writeFile(absolutePath, `${JSON.stringify(value, null, 2)}\n`, "utf8");
 }
+async function loadCurrentConfig(configPath) {
+    const loaded = await loadConfig({ configPath });
+    return { absolutePath: loaded.configPath, config: loaded.config };
+}
+function formatPagesTable(pages) {
+    const headers = ["#", "path", "label", "devices"];
+    const rows = pages.map((p, index) => {
+        return [String(index + 1), p.path, p.label, p.devices.join(",")];
+    });
+    return renderTable({ headers, rows });
+}
+async function printConfiguredPages(session) {
+    const exists = await pathExists(session.configPath);
+    if (!exists) {
+        // eslint-disable-next-line no-console
+        console.log(`Config not found at ${session.configPath}. Run 'init' to create a config, or use 'config <path>' to point to one.`);
+        return;
+    }
+    const { absolutePath, config } = await loadCurrentConfig(session.configPath);
+    const lines = [];
+    lines.push(`${theme.dim("Config")}: ${absolutePath}`);
+    lines.push(`${theme.dim("Base URL")}: ${config.baseUrl}`);
+    lines.push("");
+    lines.push(formatPagesTable(config.pages));
+    // eslint-disable-next-line no-console
+    console.log(renderPanel({ title: theme.bold("Pages"), lines }));
+}
+function parseDevices(raw) {
+    const parts = raw
+        .split(",")
+        .map((p) => p.trim().toLowerCase())
+        .filter((p) => p.length > 0);
+    if (parts.length === 0) {
+        return undefined;
+    }
+    const devices = [];
+    for (const part of parts) {
+        if (part === "mobile" || part === "desktop") {
+            devices.push(part);
+            continue;
+        }
+        return undefined;
+    }
+    return [...new Set(devices)];
+}
+function askLine(rl, question) {
+    return new Promise((resolvePromise) => {
+        rl.question(question, (value) => resolvePromise(value));
+    });
+}
+async function addPageInteractive(rl, session) {
+    const exists = await pathExists(session.configPath);
+    if (!exists) {
+        // eslint-disable-next-line no-console
+        console.log(`Config not found at ${session.configPath}. Run 'init' first.`);
+        return;
+    }
+    const { absolutePath, config } = await loadCurrentConfig(session.configPath);
+    // eslint-disable-next-line no-console
+    console.log(formatPagesTable(config.pages));
+    const rawPath = (await askLine(rl, "New page path (must start with /): ")).trim();
+    if (!rawPath.startsWith("/")) {
+        // eslint-disable-next-line no-console
+        console.log("Cancelled: path must start with '/'.");
+        return;
+    }
+    const label = (await askLine(rl, "Label (optional): ")).trim() || rawPath;
+    const rawDevices = (await askLine(rl, "Devices (comma-separated: mobile,desktop) [mobile,desktop]: ")).trim();
+    const devices = parseDevices(rawDevices.length > 0 ? rawDevices : "mobile,desktop") ?? ["mobile", "desktop"];
+    const nextPages = [...config.pages, { path: rawPath, label, devices }];
+    const nextConfig = { ...config, pages: nextPages };
+    await writeJsonFile(absolutePath, nextConfig);
+    // eslint-disable-next-line no-console
+    console.log(`Added page ${rawPath}.`);
+}
+async function removePageInteractive(rl, session, args) {
+    const exists = await pathExists(session.configPath);
+    if (!exists) {
+        // eslint-disable-next-line no-console
+        console.log(`Config not found at ${session.configPath}. Run 'init' first.`);
+        return;
+    }
+    const { absolutePath, config } = await loadCurrentConfig(session.configPath);
+    if (config.pages.length === 0) {
+        // eslint-disable-next-line no-console
+        console.log("No pages configured.");
+        return;
+    }
+    const byPath = args[0]?.trim();
+    const resolvedIndex = (() => {
+        if (byPath && byPath.startsWith("/")) {
+            const index = config.pages.findIndex((p) => p.path === byPath);
+            return index >= 0 ? index : undefined;
+        }
+        if (byPath && /^\d+$/.test(byPath)) {
+            const idx = parseInt(byPath, 10) - 1;
+            return idx >= 0 && idx < config.pages.length ? idx : undefined;
+        }
+        return undefined;
+    })();
+    const indexToRemove = resolvedIndex ?? (() => {
+        // eslint-disable-next-line no-console
+        console.log(formatPagesTable(config.pages));
+        return undefined;
+    })();
+    const finalIndex = indexToRemove ?? (() => {
+        return undefined;
+    })();
+    let resolvedFinalIndex = finalIndex;
+    if (resolvedFinalIndex === undefined) {
+        const answer = (await askLine(rl, "Remove which page? Enter # or /path (blank to cancel): ")).trim();
+        if (answer.length === 0) {
+            // eslint-disable-next-line no-console
+            console.log("Cancelled.");
+            return;
+        }
+        if (answer.startsWith("/")) {
+            const idx = config.pages.findIndex((p) => p.path === answer);
+            resolvedFinalIndex = idx >= 0 ? idx : undefined;
+        }
+        else if (/^\d+$/.test(answer)) {
+            const idx = parseInt(answer, 10) - 1;
+            resolvedFinalIndex = idx >= 0 && idx < config.pages.length ? idx : undefined;
+        }
+    }
+    if (resolvedFinalIndex === undefined) {
+        // eslint-disable-next-line no-console
+        console.log("No matching page.");
+        return;
+    }
+    if (config.pages.length <= 1) {
+        // eslint-disable-next-line no-console
+        console.log("Cancelled: config must contain at least one page.");
+        return;
+    }
+    const removed = config.pages[resolvedFinalIndex];
+    const nextPages = config.pages.filter((_p, i) => i !== resolvedFinalIndex);
+    const nextConfig = { ...config, pages: nextPages };
+    await writeJsonFile(absolutePath, nextConfig);
+    // eslint-disable-next-line no-console
+    console.log(`Removed page ${removed.path}.`);
+}
 function getSessionPaths(projectRoot) {
     const dir = resolve(projectRoot, SESSION_DIR_NAME);
     const file = join(dir, SESSION_FILE_NAME);
@@ -363,7 +508,12 @@ function printHelp() {
     lines.push(`${theme.cyan("console")} Console errors + runtime exceptions audit (headless Chrome)`);
     lines.push("");
     lines.push(theme.bold("Other commands"));
+    lines.push(`${theme.cyan("pages")} Print configured pages/routes from the current config`);
+    lines.push(`${theme.cyan("routes")} Alias for pages`);
+    lines.push(`${theme.cyan("add-page")} Add a page to apex.config.json (interactive)`);
+    lines.push(`${theme.cyan("rm-page [#|/path]")} Remove a page from apex.config.json (interactive)`);
     lines.push(`${theme.cyan("clean")} Remove ApexAuditor artifacts (reports/cache and optionally config)`);
+    lines.push(`${theme.cyan("uninstall")} Remove .apex-auditor and the current config file`);
     lines.push(`${theme.cyan("open")} Open the last HTML report (or .apex-auditor/report.html)`);
     lines.push(`${theme.cyan("diff")} Compare last run vs previous run (from this shell session)`);
     lines.push(`${theme.cyan("preset <id>")} Set preset: default|overview|quick|accurate|fast`);
@@ -429,7 +579,12 @@ function createCompleter() {
         "links",
         "headers",
         "console",
+        "pages",
+        "routes",
+        "add-page",
+        "rm-page",
         "clean",
+        "uninstall",
         "open",
         "diff",
         "preset",
@@ -440,6 +595,7 @@ function createCompleter() {
         "exit",
         "quit",
     ];
+    const uninstallFlags = ["--project-root", "--config-path", "--config", "--dry-run", "--yes", "-y", "--json"];
     const presets = ["default", "overview", "quick", "accurate", "fast"];
     const onOff = ["on", "off"];
     const buildIdModes = ["auto", "manual"];
@@ -501,6 +657,9 @@ function createCompleter() {
         if (command === "clean") {
             return [filterStartsWith(cleanFlags, fragment), rawLine];
         }
+        if (command === "uninstall") {
+            return [filterStartsWith(uninstallFlags, fragment), rawLine];
+        }
         return [[], rawLine];
     };
     return (line) => {
@@ -683,6 +842,10 @@ async function handleShellCommand(projectRoot, session, command) {
     if (command.id === "exit" || command.id === "quit") {
         return { session, shouldExit: true };
     }
+    if (command.id === "pages" || command.id === "routes") {
+        await printConfiguredPages(session);
+        return { session, shouldExit: false };
+    }
     if (command.id === "audit") {
         const nextSession = await runAuditFromShell(projectRoot, session, command.args);
         return { session: nextSession, shouldExit: false };
@@ -716,6 +879,11 @@ async function handleShellCommand(projectRoot, session, command) {
         await runCleanCli(argv);
         return { session, shouldExit: false };
     }
+    if (command.id === "uninstall") {
+        const argv = ["node", "apex-auditor", "--project-root", projectRoot, "--config-path", session.configPath, ...command.args];
+        await runUninstallCli(argv);
+        return { session, shouldExit: false };
+    }
     if (command.id === "init") {
         // eslint-disable-next-line no-console
         console.log("Starting config wizard...");
@@ -788,127 +956,170 @@ export async function runShellCli(argv) {
     void argv;
     const projectRoot = process.cwd();
     let session = await loadSession(projectRoot);
-    const rl = readline.createInterface({ input: process.stdin, output: process.stdout, completer: createCompleter() });
-    let rlClosed = false;
-    rl.on("close", () => {
-        rlClosed = true;
-    });
-    const onSigint = () => {
-        rl.close();
-    };
-    rl.on("SIGINT", onSigint);
-    let suppressInput = false;
-    const version = await readCliVersion();
-    printHomeScreen({ version, session });
-    rl.setPrompt(buildPrompt(session));
-    rl.prompt();
-    let onLine;
-    const runWizardInShell = async () => {
-        const previousPrompt = buildPrompt(session);
-        rl.pause();
-        rl.setPrompt("");
-        rl.off("SIGINT", onSigint);
-        try {
-            rl.prompt(true);
-        }
-        catch {
-            // ignore
-        }
-        if (typeof onLine === "function") {
-            rl.off("line", onLine);
-        }
-        try {
-            await runWizardCli(["node", "apex-auditor"]);
+    let printedHome = false;
+    let shouldExitShell = false;
+    while (!shouldExitShell) {
+        const rl = readline.createInterface({ input: process.stdin, output: process.stdout, completer: createCompleter() });
+        let rlClosed = false;
+        let shouldExit = false;
+        let suppressInput = false;
+        rl.on("close", () => {
+            rlClosed = true;
+        });
+        const onSigint = () => {
+            shouldExit = true;
+            rl.close();
+        };
+        rl.on("SIGINT", onSigint);
+        if (!printedHome) {
+            const version = await readCliVersion();
+            printHomeScreen({ version, session });
+            printedHome = true;
         }
-        finally {
-            rl.on("SIGINT", onSigint);
-            if (rlClosed) {
-                return;
+        rl.setPrompt(buildPrompt(session));
+        rl.prompt();
+        let onLine;
+        const runWizardInShell = async () => {
+            const previousPrompt = buildPrompt(session);
+            rl.pause();
+            rl.setPrompt("");
+            rl.off("SIGINT", onSigint);
+            try {
+                rl.prompt(true);
+            }
+            catch {
+                // ignore
             }
             if (typeof onLine === "function") {
-                rl.on("line", onLine);
+                rl.off("line", onLine);
             }
-            rl.setPrompt(previousPrompt);
-            rl.resume();
-        }
-    };
-    onLine = async (line) => {
-        if (suppressInput) {
-            return;
-        }
-        let command = parseShellCommand(line);
-        if (command.id === "clean" && !command.args.includes("--yes") && !command.args.includes("-y") && process.stdin.isTTY) {
-            const targets = resolveCleanTargets({ projectRoot, session, args: command.args });
-            const ok = await confirmCleanInShell({ rl, targets });
-            if (!ok) {
-                // eslint-disable-next-line no-console
-                console.log("Cancelled.");
-                rl.setPrompt(buildPrompt(session));
-                rl.prompt();
+            try {
+                await runWizardCli(["node", "apex-auditor"]);
+            }
+            finally {
+                rl.on("SIGINT", onSigint);
+                if (rlClosed) {
+                    return;
+                }
+                if (typeof onLine === "function") {
+                    rl.on("line", onLine);
+                }
+                rl.setPrompt(previousPrompt);
+                rl.resume();
+            }
+        };
+        onLine = async (line) => {
+            if (suppressInput) {
                 return;
             }
-            command = { ...command, args: [...command.args, "--yes"] };
-        }
-        if (command.id === "audit" && process.stdin.isTTY) {
-            const exists = await pathExists(session.configPath);
-            if (!exists) {
+            let command = parseShellCommand(line);
+            const isEditCommand = command.id === "add-page" || command.id === "rm-page";
+            if (isEditCommand && process.stdin.isTTY) {
                 suppressInput = true;
                 rl.pause();
-                const answer = await new Promise((resolvePromise) => {
-                    rl.question(`Config not found at ${session.configPath}. Run the init wizard now? (Y/n) `, (value) => resolvePromise(value));
-                });
-                const text = answer.trim().toLowerCase();
-                const accepted = text.length === 0 || text === "y" || text === "yes";
-                if (accepted) {
-                    // eslint-disable-next-line no-console
-                    console.log("Starting config wizard...");
-                    try {
-                        await runWizardInShell();
-                        // eslint-disable-next-line no-console
-                        console.log(`Ready. Next: ${theme.cyan("audit")}.`);
+                try {
+                    if (command.id === "add-page") {
+                        await addPageInteractive(rl, session);
                     }
-                    finally {
-                        // no-op
+                    else {
+                        await removePageInteractive(rl, session, command.args);
                     }
                 }
-                else {
-                    // eslint-disable-next-line no-console
-                    console.log(`Config required. Create one with ${theme.cyan("init")} or point to an existing file with ${theme.cyan("config <path>")}.`);
+                finally {
+                    if (!rlClosed) {
+                        rl.resume();
+                        suppressInput = false;
+                        rl.setPrompt(buildPrompt(session));
+                        rl.prompt();
+                    }
                 }
-                rl.resume();
-                suppressInput = false;
-                rl.setPrompt(buildPrompt(session));
-                rl.prompt();
                 return;
             }
-        }
-        if (command.id === "init") {
-            // eslint-disable-next-line no-console
-            console.log("Starting config wizard...");
-            await runWizardInShell();
-            // eslint-disable-next-line no-console
-            console.log(`Ready. Next: ${theme.cyan("measure")} or ${theme.cyan("audit")}.`);
-            rl.setPrompt(buildPrompt(session));
-            rl.prompt();
-            return;
-        }
-        rl.pause();
-        try {
-            const result = await handleShellCommand(projectRoot, session, command);
-            session = result.session;
-            if (result.shouldExit) {
+            if (command.id === "clean" && !command.args.includes("--yes") && !command.args.includes("-y") && process.stdin.isTTY) {
+                const targets = resolveCleanTargets({ projectRoot, session, args: command.args });
+                const ok = await confirmCleanInShell({ rl, targets });
+                if (!ok) {
+                    // eslint-disable-next-line no-console
+                    console.log("Cancelled.");
+                    rl.setPrompt(buildPrompt(session));
+                    rl.prompt();
+                    return;
+                }
+                command = { ...command, args: [...command.args, "--yes"] };
+            }
+            if (command.id === "audit" && process.stdin.isTTY) {
+                const exists = await pathExists(session.configPath);
+                if (!exists) {
+                    suppressInput = true;
+                    rl.pause();
+                    const answer = await new Promise((resolvePromise) => {
+                        rl.question(`Config not found at ${session.configPath}. Run the init wizard now? (Y/n) `, (value) => resolvePromise(value));
+                    });
+                    const text = answer.trim().toLowerCase();
+                    const accepted = text.length === 0 || text === "y" || text === "yes";
+                    if (accepted) {
+                        // eslint-disable-next-line no-console
+                        console.log("Starting config wizard...");
+                        try {
+                            await runWizardInShell();
+                            // eslint-disable-next-line no-console
+                            console.log(`Ready. Next: ${theme.cyan("audit")}.`);
+                        }
+                        finally {
+                            // no-op
+                        }
+                    }
+                    else {
+                        // eslint-disable-next-line no-console
+                        console.log(`Config required. Create one with ${theme.cyan("init")} or point to an existing file with ${theme.cyan("config <path>")}.`);
+                    }
+                    if (!rlClosed) {
+                        rl.resume();
+                        suppressInput = false;
+                        rl.setPrompt(buildPrompt(session));
+                        rl.prompt();
+                    }
+                    return;
+                }
+            }
+            if (command.id === "init") {
+                // eslint-disable-next-line no-console
+                console.log("Starting config wizard...");
+                await runWizardInShell();
+                // eslint-disable-next-line no-console
+                console.log(`Ready. Next: ${theme.cyan("measure")} or ${theme.cyan("audit")}.`);
+                // Force readline recreation by closing current instance - this ensures
+                // the shell stays alive after the wizard completes even if prompts closed stdin
                 rl.close();
                 return;
             }
+            rl.pause();
+            try {
+                const result = await handleShellCommand(projectRoot, session, command);
+                session = result.session;
+                if (result.shouldExit) {
+                    shouldExit = true;
+                    rl.close();
+                    return;
+                }
+            }
+            finally {
+                if (!rlClosed) {
+                    rl.resume();
+                }
+            }
+            if (!rlClosed) {
+                rl.setPrompt(buildPrompt(session));
+                rl.prompt();
+            }
+        };
+        rl.on("line", onLine);
+        await new Promise((resolvePromise) => {
+            rl.on("close", () => resolvePromise());
+        });
+        if (shouldExit) {
+            shouldExitShell = true;
+            continue;
         }
-        finally {
-            rl.resume();
-        }
-        rl.setPrompt(buildPrompt(session));
-        rl.prompt();
-    };
-    rl.on("line", onLine);
-    await new Promise((resolvePromise) => {
-        rl.on("close", () => resolvePromise());
-    });
+    }
 }

package/dist/uninstall-cli.js

@@ -0,0 +1,156 @@
+import { rm } from "node:fs/promises";
+import { resolve } from "node:path";
+import readline from "node:readline";
+import { pathExists } from "./fs-utils.js";
+function parseArgs(argv) {
+    let projectRoot = process.cwd();
+    let configPath = "apex.config.json";
+    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 === "--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),
+        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();
+    }
+}
+async function detectPackageManager(projectRoot) {
+    const pnpmLock = await pathExists(resolve(projectRoot, "pnpm-lock.yaml"));
+    if (pnpmLock) {
+        return "pnpm";
+    }
+    const bunLock = await pathExists(resolve(projectRoot, "bun.lockb"));
+    if (bunLock) {
+        return "bun";
+    }
+    const yarnLock = await pathExists(resolve(projectRoot, "yarn.lock"));
+    if (yarnLock) {
+        return "yarn";
+    }
+    const npmLock = await pathExists(resolve(projectRoot, "package-lock.json"));
+    if (npmLock) {
+        return "npm";
+    }
+    return "unknown";
+}
+function buildDependencyUninstallCommand(packageManager) {
+    const packageName = "apex-auditor";
+    if (packageManager === "pnpm") {
+        return `pnpm remove ${packageName}`;
+    }
+    if (packageManager === "yarn") {
+        return `yarn remove ${packageName}`;
+    }
+    if (packageManager === "bun") {
+        return `bun remove ${packageName}`;
+    }
+    if (packageManager === "npm") {
+        return `npm uninstall ${packageName}`;
+    }
+    return `npm uninstall ${packageName}`;
+}
+function buildPlan(args) {
+    const actions = [];
+    actions.push({ kind: "rm", path: resolve(args.projectRoot, ".apex-auditor"), existsByAssumption: true });
+    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 runUninstallCli(argv) {
+    const startedAtMs = Date.now();
+    const args = parseArgs(argv);
+    const planned = buildPlan(args);
+    const packageManager = await detectPackageManager(args.projectRoot);
+    const dependencyUninstallCommand = buildDependencyUninstallCommand(packageManager);
+    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,
+        packageManager,
+        dependencyUninstallCommand,
+    };
+    if (args.jsonOutput) {
+        console.log(JSON.stringify(report, null, 2));
+        return;
+    }
+    if (args.dryRun) {
+        console.log(`Planned removals: ${planned.length} (dry-run).`);
+        console.log(`Dependency uninstall (optional): ${dependencyUninstallCommand}`);
+        return;
+    }
+    console.log(`Removed: ${executed.length}/${planned.length}.`);
+    console.log(`Dependency uninstall (optional): ${dependencyUninstallCommand}`);
+}

package/dist/wizard-cli.js

@@ -82,13 +82,13 @@ const pageQuestions = [
 const addFirstPageQuestion = {
     type: "confirm",
     name: "value",
-    message: "Add your first page to audit?",
+    message: "No pages were auto-detected. Add a page to audit now? (You can always edit apex.config.json later)",
     initial: true,
 };
 const addMorePagesQuestion = {
     type: "confirm",
     name: "value",
-    message: "Add another page to audit?",
+    message: "Add another page to audit? (Optional — you can edit apex.config.json later)",
     initial: false,
 };
 const projectRootQuestion = {
@@ -107,8 +107,62 @@ const detectorChoiceQuestion = {
         { title: "Remix", value: "remix-routes" },
         { title: "SvelteKit", value: "sveltekit-routes" },
         { title: "SPA Crawl", value: "spa-html" },
+        { title: "Static HTML (dist/build/out/public/src)", value: "static-html" },
     ],
 };
+const routeFilterConfirmQuestion = {
+    type: "confirm",
+    name: "value",
+    message: "Filter detected routes with include/exclude patterns?",
+    initial: false,
+};
+const routeFilterQuestions = [
+    {
+        type: "text",
+        name: "include",
+        message: "Include patterns (comma-separated, optional)",
+        initial: "",
+    },
+    {
+        type: "text",
+        name: "exclude",
+        message: "Exclude patterns (comma-separated, optional)",
+        initial: "",
+    },
+];
+const ROUTE_FILTER_DEFAULT_ON_THRESHOLD = 15;
+function buildSuggestedExcludePatterns(profile) {
+    if (profile === "next") {
+        return ["/_next/*", "/api/*"];
+    }
+    if (profile === "nuxt") {
+        return ["/__nuxt/*", "/api/*"];
+    }
+    if (profile === "sveltekit") {
+        return ["/__data.json*", "/api/*"];
+    }
+    if (profile === "remix") {
+        return ["/api/*"];
+    }
+    return [];
+}
+function buildRouteFilterQuestions(params) {
+    const excludeInitial = params.suggestedExclude.join(",");
+    return [
+        {
+            type: "text",
+            name: "include",
+            message: "Include patterns (comma-separated, optional)",
+            initial: "",
+        },
+        {
+            type: "text",
+            name: "exclude",
+            message: "Exclude patterns (comma-separated, optional)",
+            initial: excludeInitial,
+        },
+    ];
+}
 function handleCancel() {
     console.log("Wizard cancelled. No config written.");
     throw new WizardAbortError("cancelled");
@@ -124,6 +178,42 @@ async function collectBaseAnswers() {
         query: answers.query,
     };
 }
+function tryParseLocalDevServer(baseUrl) {
+    let parsed;
+    try {
+        parsed = new URL(baseUrl);
+    }
+    catch {
+        return undefined;
+    }
+    const host = parsed.hostname;
+    if (host !== "localhost" && host !== "127.0.0.1") {
+        return undefined;
+    }
+    const port = parsed.port.length > 0 ? Number(parsed.port) : NaN;
+    if (!Number.isFinite(port) || port <= 0) {
+        return undefined;
+    }
+    return { host, port };
+}
+async function collectBaseAnswersWithSafety() {
+    while (true) {
+        const answers = await collectBaseAnswers();
+        const info = tryParseLocalDevServer(answers.baseUrl);
+        if (!info) {
+            return answers;
+        }
+        const confirmed = await ask({
+            type: "confirm",
+            name: "value",
+            message: `Base URL is ${answers.baseUrl}. Make sure the dev server is running for this project on port ${info.port} to avoid config conflicts when multiple projects are open. Continue?`,
+            initial: true,
+        });
+        if (confirmed.value) {
+            return answers;
+        }
+    }
+}
 function profileDisplayName(profile) {
     switch (profile) {
         case "next":
@@ -358,8 +448,8 @@ async function collectSinglePage() {
 }
 async function collectPages(initialPages) {
     const pages = [...initialPages];
-    // If we already detected pages, return them immediately for speed.
     if (pages.length > 0) {
+        console.log("Tip: You can add/remove pages later by editing apex.config.json or re-running init.");
         return pages;
     }
     while (true) {
@@ -398,32 +488,91 @@ async function maybeDetectPages(params) {
         console.log("No routes detected. Add pages manually.");
         return [];
     }
-    return selectDetectedRoutes(combined);
+    console.log(`Detected ${combined.length} route(s) using auto-discovery.`);
+    const suggestedExclude = buildSuggestedExcludePatterns(params.profile);
+    const initialFilter = combined.length >= ROUTE_FILTER_DEFAULT_ON_THRESHOLD || suggestedExclude.length > 0;
+    const confirmQuestion = { ...routeFilterConfirmQuestion, initial: initialFilter };
+    const shouldFilter = await ask(confirmQuestion);
+    const filtered = shouldFilter.value
+        ? await filterDetectedRoutes({ routes: combined, profile: params.profile, suggestedExclude })
+        : combined;
+    if (filtered.length === 0) {
+        console.log("No routes remain after filtering. Add pages manually.");
+        return [];
+    }
+    if (filtered.length !== combined.length) {
+        console.log(`Filtered routes: ${filtered.length}/${combined.length}.`);
+    }
+    return selectDetectedRoutes(filtered);
+}
+async function filterDetectedRoutes(params) {
+    const questions = buildRouteFilterQuestions({ profile: params.profile, suggestedExclude: params.suggestedExclude });
+    const answers = await ask(questions);
+    const includePatterns = splitPatterns(answers.include);
+    const excludePatterns = splitPatterns(answers.exclude);
+    const includeRegexes = includePatterns.map((pattern) => compileGlob(pattern));
+    const excludeRegexes = excludePatterns.map((pattern) => compileGlob(pattern));
+    return params.routes.filter((route) => {
+        const included = includeRegexes.length === 0 ? true : includeRegexes.some((regex) => regex.test(route.path));
+        const excluded = excludeRegexes.some((regex) => regex.test(route.path));
+        return included && !excluded;
+    });
+}
+function splitPatterns(raw) {
+    return raw
+        .split(",")
+        .map((part) => part.trim())
+        .filter((part) => part.length > 0);
+}
+function compileGlob(pattern) {
+    const escaped = pattern.replace(/[.+^${}()|[\]\\]/g, "\\$&");
+    const wildcarded = escaped.replace(/\*/g, ".*").replace(/\?/g, ".");
+    return new RegExp(`^${wildcarded}$`);
 }
 async function chooseDetectionRoot({ profile, repoRoot, }) {
-    if (profile !== "next") {
-        return repoRoot;
-    }
-    const projects = await discoverNextProjects({ repoRoot });
-    if (projects.length === 0) {
-        return repoRoot;
+    const candidates = await findMonorepoCandidates(repoRoot);
+    const matching = candidates.filter((candidate) => candidate.profile === profile);
+    if (matching.length === 0) {
+        if (profile !== "next") {
+            return repoRoot;
+        }
+        const projects = await discoverNextProjects({ repoRoot });
+        if (projects.length === 0) {
+            return repoRoot;
+        }
+        if (projects.length === 1) {
+            const onlyProject = projects[0];
+            console.log(`Detected Next.js app at ${onlyProject.root}.`);
+            return onlyProject.root;
+        }
+        const choices = projects.map((project) => ({
+            title: `${project.name} (${project.root})`,
+            value: project.root,
+        }));
+        const answer = await ask({
+            type: "select",
+            name: "projectRoot",
+            message: "Multiple Next.js apps found. Which one do you want to audit?",
+            choices,
+        });
+        return answer.projectRoot ?? repoRoot;
     }
-    if (projects.length === 1) {
-        const onlyProject = projects[0];
-        console.log(`Detected Next.js app at ${onlyProject.root}.`);
-        return onlyProject.root;
+    if (matching.length === 1) {
+        const only = matching[0];
+        console.log(`Detected ${profileDisplayName(profile)} app at ${only.root}.`);
+        return only.root;
     }
-    const choices = projects.map((project) => ({
-        title: `${project.name} (${project.root})`,
-        value: project.root,
+    const choices = matching.map((candidate) => ({
+        title: `${candidate.name} (${candidate.root}) - ${profileDisplayName(candidate.profile)}`,
+        value: candidate.root,
     }));
     const answer = await ask({
         type: "select",
         name: "projectRoot",
-        message: "Multiple Next.js apps found. Which one do you want to audit?",
+        message: `Multiple ${profileDisplayName(profile)} apps found. Which one do you want to audit?`,
         choices,
     });
-    return answer.projectRoot ?? repoRoot;
+    return answer.projectRoot ?? matching[0]?.root ?? repoRoot;
 }
 async function selectDetector(profile) {
     const preset = PROFILE_TO_DETECTOR[profile];
@@ -466,7 +615,7 @@ function convertRouteToPage(route) {
     };
 }
 async function buildConfig() {
-    const baseAnswers = await collectBaseAnswers();
+    const baseAnswers = await collectBaseAnswersWithSafety();
     const projectRootAnswer = await ask(projectRootQuestion);
     const initialRepoRoot = resolve(projectRootAnswer.projectRoot);
     const resolved = await resolveWizardProjectRoot(initialRepoRoot);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "apex-auditor",
-  "version": "0.3.5",
+  "version": "0.3.7",
   "private": false,
   "description": "CLI to run structured Lighthouse audits (Performance, Accessibility, Best Practices, SEO) across routes.",
   "type": "module",