apex-auditor 0.3.6 → 0.3.7

package/README.md

@@ -20,7 +20,7 @@ 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.
+- `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).
 
@@ -34,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)
 
@@ -132,11 +135,8 @@ The docs in `docs/` reflect the current shell-based workflow:
 
 ## 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/cli.js

@@ -1140,15 +1140,17 @@ export async function runAuditCli(argv, options) {
     const plannedRuns = overviewSample.config.runs ?? 1;
     const plannedSteps = plannedCombos * plannedRuns;
     const LARGE_RUN_COMBOS_THRESHOLD = 76;
-    const LARGE_RUN_PARALLEL_CAP = 2;
+    const LARGE_RUN_PARALLEL_CAP = 4;
     const usingDefaultParallel = args.parallelOverride === undefined && presetParallel === undefined && config.parallel === undefined;
-    const autoStableLargeRun = plannedCombos >= LARGE_RUN_COMBOS_THRESHOLD && !args.stable && usingDefaultParallel;
+    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) {
@@ -1165,15 +1167,9 @@ 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
@@ -1249,17 +1245,14 @@ export async function runAuditCli(argv, options) {
             showParallel: args.showParallel,
             onlyCategories,
             signal: abortController.signal,
-            onAfterWarmUp: stopSpinner,
+            onAfterWarmUp: startAuditSpinner,
             onProgress: ({ completed, total, path, device, etaMs }) => {
                 if (!process.stdout.isTTY) {
                     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 {
@@ -213,6 +225,7 @@ function send(message) {
 }
 async function main() {
     const maxRetries = 3;
+    // Recycle Chrome periodically to prevent memory leaks
     const maxTasksPerChrome = 10;
     const sessionRef = { session: await createChromeSession() };
     let tasksSinceChromeStart = 0;
@@ -238,7 +251,7 @@ async function main() {
                 await sessionRef.session.close();
             }
             catch {
-                return;
+                // Ignore close errors
             }
             sessionRef.session = await createChromeSession();
             tasksSinceChromeStart = 0;

package/dist/shell-cli.js

@@ -13,8 +13,10 @@ 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";
@@ -124,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);
@@ -364,6 +508,10 @@ 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)`);
@@ -431,6 +579,10 @@ function createCompleter() {
         "links",
         "headers",
         "console",
+        "pages",
+        "routes",
+        "add-page",
+        "rm-page",
         "clean",
         "uninstall",
         "open",
@@ -690,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 };
@@ -857,6 +1013,28 @@ export async function runShellCli(argv) {
                 return;
             }
             let command = parseShellCommand(line);
+            const isEditCommand = command.id === "add-page" || command.id === "rm-page";
+            if (isEditCommand && process.stdin.isTTY) {
+                suppressInput = true;
+                rl.pause();
+                try {
+                    if (command.id === "add-page") {
+                        await addPageInteractive(rl, session);
+                    }
+                    else {
+                        await removePageInteractive(rl, session, command.args);
+                    }
+                }
+                finally {
+                    if (!rlClosed) {
+                        rl.resume();
+                        suppressInput = false;
+                        rl.setPrompt(buildPrompt(session));
+                        rl.prompt();
+                    }
+                }
+                return;
+            }
             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 });
@@ -908,12 +1086,11 @@ export async function runShellCli(argv) {
                 // eslint-disable-next-line no-console
                 console.log("Starting config wizard...");
                 await runWizardInShell();
-                if (!rlClosed) {
-                    // eslint-disable-next-line no-console
-                    console.log(`Ready. Next: ${theme.cyan("measure")} or ${theme.cyan("audit")}.`);
-                    rl.setPrompt(buildPrompt(session));
-                    rl.prompt();
-                }
+                // 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();

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 = {
@@ -130,6 +130,39 @@ const routeFilterQuestions = [
         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");
@@ -415,6 +448,10 @@ async function collectSinglePage() {
 }
 async function collectPages(initialPages) {
     const pages = [...initialPages];
+    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) {
         const shouldAdd = await confirmAddPage(pages.length > 0);
         if (!shouldAdd) {
@@ -452,8 +489,13 @@ async function maybeDetectPages(params) {
         return [];
     }
     console.log(`Detected ${combined.length} route(s) using auto-discovery.`);
-    const shouldFilter = await ask(routeFilterConfirmQuestion);
-    const filtered = shouldFilter.value ? await filterDetectedRoutes(combined) : combined;
+    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 [];
@@ -463,13 +505,14 @@ async function maybeDetectPages(params) {
     }
     return selectDetectedRoutes(filtered);
 }
-async function filterDetectedRoutes(routes) {
-    const answers = await ask(routeFilterQuestions);
+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 routes.filter((route) => {
+    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;

package/package.json

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