apex-auditor 0.2.9 → 0.3.3

package/README.md

@@ -1,151 +1,101 @@
 # ApexAuditor
 
-ApexAuditor is a small, framework-agnostic Lighthouse runner that gives you **fast, structured insights** across multiple pages and devices.
+ApexAuditor is a **measure-first** performance + metrics assistant.
 
-It focuses on:
+Use it to:
 
-- **Multi-page, multi-device audits**: run Lighthouse across your key flows in one shot.
-- **Framework flexibility**: works with any stack that serves HTTP (Next.js, Remix, Vite/React, SvelteKit, Rails, static sites, etc.).
-- **Smart route discovery**: auto-detects routes for Next.js (App/Pages), Remix, SvelteKit, and can crawl generic SPAs.
-- **Developer-friendly reports**: readable console output, Markdown tables, HTML reports, and JSON summaries for CI.
-- **Configurable throttling**: tune CPU/network throttling for accuracy vs speed trade-offs.
-- **Parallel execution**: speed up batch testing with multiple Chrome instances.
+- **Measure fast** (CDP-based): LCP/CLS/INP + screenshot + console errors.
+- **Audit deep** (Lighthouse): Performance + Accessibility + Best Practices + SEO.
+- **Review results** in a clean, structured console output and an HTML report.
 
----
+## Most common commands
 
-## Example output
-
-Terminal summary:
-
-![Example terminal output 1](./public/example_output_1.png)
-
-![Example terminal output 2](./public/example_output_2.png)
-
-Wizard route selection:
-
-![Wizard screenshot](./public/wizard_1.png)
-
----
-
-## Installation
-
-Install as a dev dependency (recommended):
+From your web project root:
 
 ```bash
-pnpm add -D apex-auditor
-# or
-npm install --save-dev apex-auditor
+pnpm dlx apex-auditor@latest
 ```
 
-You can also run it without installing by using your package manager's "dlx"/"npx" style command, for example:
+Inside the interactive shell:
 
-```bash
-pnpm dlx apex-auditor@latest wizard
-```
+- **measure**
+- **audit**
+- **open** (open the latest HTML report)
+- **init** (launch config wizard)
+- **config <path>** (switch config file)
 
----
+Cancel long-running commands:
 
-## Common commands
+- **Esc** (returns you to the shell prompt)
 
-All commands are available as a CLI named `apex-auditor` once installed.
+## Install
 
-### Quickstart (auto-detect routes and run a one-off audit)
+Install as a dev dependency (recommended):
 
 ```bash
-apex-auditor quickstart --base-url http://localhost:3000
+pnpm add -D apex-auditor
 ```
 
-### Wizard (interactive config with route auto-detection)
+Or run without installing:
 
 ```bash
-apex-auditor wizard
+pnpm dlx apex-auditor@latest
 ```
 
-The wizard can detect routes for:
-
-- Next.js (App Router / Pages Router)
-- Remix
-- SvelteKit
-- Single Page Apps (Vite/CRA/etc., via HTML crawl)
-
-### Audit (run using an existing config)
-
-```bash
-apex-auditor audit --config apex.config.json
-```
+## Outputs
 
-**CLI flags:**
+All outputs are written under `.apex-auditor/` in your project.
 
-| Flag | Description |
-|------|-------------|
-| `--ci` | Enable CI mode with budgets and non-zero exit codes |
-| `--no-color` / `--color` | Control ANSI colours in console output |
-| `--log-level <level>` | Override Lighthouse log level (`silent`, `error`, `info`, `verbose`) |
-| `--throttling <method>` | Throttling method: `simulate` (fast) or `devtools` (accurate) |
-| `--cpu-slowdown <n>` | CPU slowdown multiplier (1-20, default: 4) |
-| `--parallel <n>` | Number of pages to audit in parallel (1-10) |
-| `--warm-up` | Perform warm-up requests before auditing |
-| `--open` | Auto-open HTML report in browser after audit |
-| `--json` | Output JSON to stdout (for piping) |
-| `--mobile-only` | Only audit mobile device configurations |
-| `--desktop-only` | Only audit desktop device configurations |
+### `audit` outputs
 
----
+- `summary.json`
+- `summary.md`
+- `report.html`
+- `accessibility-summary.json`
+- `accessibility/` (axe-core artifacts per page/device)
 
-## Output files
+Notes:
 
-After each audit, results are saved to `.apex-auditor/`:
+- **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.
 
-- `summary.json` – structured JSON results
-- `summary.md` – Markdown table
-- `report.html` – visual HTML report with score circles and metrics
+### `measure` outputs
 
----
+- `measure-summary.json`
+- `measure/` (screenshots and artifacts)
 
 ## Configuration
 
-Example `apex.config.json`:
+ApexAuditor reads `apex.config.json` by default.
+
+Example:
 
 ```json
 {
   "baseUrl": "http://localhost:3000",
-  "runs": 3,
-  "throttlingMethod": "devtools",
+  "throttlingMethod": "simulate",
   "cpuSlowdownMultiplier": 4,
-  "parallel": 2,
+  "parallel": 4,
   "warmUp": true,
   "pages": [
     { "path": "/", "label": "home", "devices": ["mobile", "desktop"] },
-    { "path": "/docs", "label": "docs", "devices": ["mobile"] }
+    { "path": "/docs", "label": "docs", "devices": ["desktop"] }
   ],
   "budgets": {
-    "categories": { "performance": 80, "accessibility": 90 },
-    "metrics": { "lcpMs": 2500, "inpMs": 200 }
+    "categories": { "performance": 80, "accessibility": 90, "bestPractices": 90, "seo": 90 },
+    "metrics": { "lcpMs": 2500, "inpMs": 200, "cls": 0.1 }
   }
 }
 ```
 
----
-
-## Metrics tracked
-
-- **LCP** (Largest Contentful Paint)
-- **FCP** (First Contentful Paint)
-- **TBT** (Total Blocking Time)
-- **CLS** (Cumulative Layout Shift)
-- **INP** (Interaction to Next Paint) - Core Web Vital
-
----
-
-## Further documentation
-
-For detailed guides, configuration options, and CI examples, see the `docs/` directory:
+## Documentation
 
-- `docs/getting-started.md` – installation, quickstart, wizard, and audit flows.
-- `docs/configuration-and-routes.md` – `apex.config.json` schema and route detection details.
-- `docs/cli-and-ci.md` – CLI flags, CI mode, budgets, and example workflows.
+The docs in `docs/` reflect the current shell-based workflow:
 
----
+- `docs/getting-started.md`
+- `docs/configuration-and-routes.md`
+- `docs/cli-and-ci.md`
 
 ## License
 

package/dist/accessibility-types.js

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

package/dist/accessibility.js

@@ -0,0 +1,152 @@
+import { request as httpRequest } from "node:http";
+import { mkdir, writeFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import { launch as launchChrome } from "chrome-launcher";
+import { createAxeScript } from "./axe-script.js";
+import { CdpClient } from "./cdp-client.js";
+import { buildUrl } from "./url.js";
+const DEFAULT_PARALLEL = 2;
+const DEFAULT_TIMEOUT_MS = 30_000;
+const CHROME_FLAGS = [
+    "--headless=new",
+    "--disable-gpu",
+    "--no-sandbox",
+    "--disable-dev-shm-usage",
+    "--disable-extensions",
+    "--disable-default-apps",
+    "--no-first-run",
+    "--no-default-browser-check",
+];
+async function launchChromeSession() {
+    const chrome = await launchChrome({
+        chromeFlags: [...CHROME_FLAGS],
+        logLevel: "silent",
+    });
+    const close = async () => {
+        try {
+            await chrome.kill();
+        }
+        catch {
+            /* noop */
+        }
+    };
+    return { port: chrome.port, close };
+}
+async function fetchJsonVersion(port) {
+    return await new Promise((resolveVersion, rejectVersion) => {
+        const req = httpRequest({ host: "localhost", port, path: "/json/version", method: "GET" }, (res) => {
+            let data = "";
+            res.on("data", (chunk) => {
+                data += chunk.toString();
+            });
+            res.on("end", () => {
+                try {
+                    const parsed = JSON.parse(data);
+                    resolveVersion(parsed);
+                }
+                catch (error) {
+                    rejectVersion(error instanceof Error ? error : new Error("Failed to parse json/version"));
+                }
+            });
+        });
+        req.on("error", (error) => rejectVersion(error));
+        req.end();
+    });
+}
+async function createTargetSession(client) {
+    const created = await client.send("Target.createTarget", { url: "about:blank" });
+    const attached = await client.send("Target.attachToTarget", { targetId: created.targetId, flatten: true });
+    return { targetId: created.targetId, sessionId: attached.sessionId };
+}
+async function applyDevice(client, sessionId, device) {
+    if (device === "mobile") {
+        await client.send("Emulation.setDeviceMetricsOverride", { width: 375, height: 667, deviceScaleFactor: 2, mobile: true }, sessionId);
+        await client.send("Emulation.setUserAgentOverride", {
+            userAgent: "Mozilla/5.0 (Linux; Android 12; Pixel 6 Pro) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/115.0.0.0 Mobile Safari/537.36",
+        }, sessionId);
+        return;
+    }
+    await client.send("Emulation.setDeviceMetricsOverride", { width: 1440, height: 900, deviceScaleFactor: 1, mobile: false }, sessionId);
+}
+async function runAxeForPage(params) {
+    const { baseUrl, path, label, device, query, timeoutMs, artifactsDir, client } = params;
+    const url = buildUrl({ baseUrl, path, query });
+    const axeScript = createAxeScript();
+    let runtimeErrorMessage;
+    const session = await createTargetSession(client);
+    try {
+        await applyDevice(client, session.sessionId, device);
+        await client.send("Page.enable", {}, session.sessionId);
+        await client.send("Runtime.enable", {}, session.sessionId);
+        const navResponse = await client.send("Page.navigate", { url }, session.sessionId);
+        if (navResponse.errorText) {
+            throw new Error(navResponse.errorText);
+        }
+        await client.waitForEventForSession("Page.loadEventFired", session.sessionId, timeoutMs);
+        await client.send("Runtime.evaluate", { expression: axeScript, awaitPromise: false }, session.sessionId);
+        const evaluation = await client.send("Runtime.evaluate", {
+            expression: "(() => { return (globalThis.__axeCore && globalThis.__axeCore.run) ? globalThis.__axeCore.run() : { violations: [] }; })()",
+            awaitPromise: true,
+            returnByValue: true,
+        }, session.sessionId);
+        const value = evaluation.result?.value;
+        const violations = value && typeof value === "object" && Array.isArray(value.violations)
+            ? value.violations
+            : [];
+        const baseName = path.replace(/\//g, "_").replace(/^_/, "") || "page";
+        const artifactPath = resolve(artifactsDir, `${baseName}_${device}_axe.json`);
+        await writeFile(artifactPath, JSON.stringify({ url, violations }, null, 2), "utf8");
+        return { url, path, label, device, violations };
+    }
+    catch (error) {
+        runtimeErrorMessage = error instanceof Error ? error.message : String(error);
+        return { url, path, label, device, violations: [], runtimeErrorMessage };
+    }
+    finally {
+        try {
+            await client.send("Target.closeTarget", { targetId: session.targetId });
+        }
+        catch {
+            /* noop */
+        }
+    }
+}
+export async function runAccessibilityAudit(params) {
+    const { config, configPath, parallelOverride, timeoutMs, artifactsDir } = params;
+    await mkdir(artifactsDir, { recursive: true });
+    const tasks = config.pages.flatMap((page) => page.devices.map((device) => ({ ...page, device })));
+    const startedAt = new Date().toISOString();
+    const comboCount = tasks.length;
+    const resolvedParallel = Math.max(1, Math.min(parallelOverride ?? DEFAULT_PARALLEL, 4));
+    const timeout = timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const chrome = await launchChromeSession();
+    try {
+        const version = await fetchJsonVersion(chrome.port);
+        const client = new CdpClient(version.webSocketDebuggerUrl);
+        await client.connect();
+        const results = [];
+        for (let i = 0; i < tasks.length; i += resolvedParallel) {
+            const slice = tasks.slice(i, i + resolvedParallel);
+            const batchResults = await Promise.all(slice.map((task) => runAxeForPage({
+                baseUrl: config.baseUrl,
+                path: task.path,
+                label: task.label,
+                device: task.device,
+                query: config.query,
+                timeoutMs: timeout,
+                artifactsDir,
+                client,
+            })));
+            results.push(...batchResults);
+        }
+        const completedAt = new Date().toISOString();
+        const elapsedMs = Date.parse(completedAt) - Date.parse(startedAt);
+        return {
+            meta: { configPath, comboCount, startedAt, completedAt, elapsedMs },
+            results,
+        };
+    }
+    finally {
+        await chrome.close();
+    }
+}

package/dist/axe-script.js

@@ -0,0 +1,26 @@
+const AXE_CDN_URL = "https://cdn.jsdelivr.net/npm/axe-core@4.8.4/axe.min.js";
+export function createAxeScript() {
+    return `(function() {
+    return new Promise((resolve) => {
+      const runAxe = () => {
+        const axe = (globalThis).axe;
+        if (axe && axe.run) {
+          (globalThis).__axeCore = axe;
+          axe.run().then(resolve).catch(() => resolve({ violations: [] }));
+          return;
+        }
+        resolve({ violations: [] });
+      };
+      if ((globalThis).axe) {
+        runAxe();
+        return;
+      }
+      const script = document.createElement('script');
+      script.src = '${AXE_CDN_URL}';
+      script.async = true;
+      script.onload = runAxe;
+      script.onerror = () => resolve({ violations: [] });
+      document.head.appendChild(script);
+    });
+  })();`;
+}

package/dist/bin.js

@@ -2,45 +2,172 @@
 import { runAuditCli } from "./cli.js";
 import { runWizardCli } from "./wizard-cli.js";
 import { runQuickstartCli } from "./quickstart-cli.js";
+import { runShellCli } from "./shell-cli.js";
+import { runMeasureCli } from "./measure-cli.js";
 function parseBinArgs(argv) {
     const rawCommand = argv[2];
-    if (rawCommand === undefined || rawCommand === "help" || rawCommand === "--help" || rawCommand === "-h") {
+    if (rawCommand === undefined) {
+        return { command: "shell", argv };
+    }
+    if (rawCommand === "help" || rawCommand === "--help" || rawCommand === "-h") {
         return { command: "help", argv };
     }
-    if (rawCommand === "audit" || rawCommand === "wizard" || rawCommand === "quickstart") {
+    if (rawCommand === "shell") {
+        const commandArgv = ["node", "apex-auditor", ...argv.slice(3)];
+        return { command: "shell", argv: commandArgv };
+    }
+    if (rawCommand === "audit" ||
+        rawCommand === "measure" ||
+        rawCommand === "wizard" ||
+        rawCommand === "quickstart" ||
+        rawCommand === "guide" ||
+        rawCommand === "init") {
         const commandArgv = ["node", "apex-auditor", ...argv.slice(3)];
         return { command: rawCommand, argv: commandArgv };
     }
     return { command: "help", argv };
 }
-function printHelp() {
+function printHelp(topic) {
+    if (topic === "topics") {
+        console.log([
+            "Help topics:",
+            "  budgets   Budget schema and CI behaviour",
+            "  configs   apex.config.json fields and defaults",
+            "  ci        CI mode, exit codes, budgets",
+            "  topics    This list",
+            "Examples:",
+            "  apex-auditor help budgets",
+            "  apex-auditor help configs",
+            "  apex-auditor help ci",
+        ].join("\n"));
+        return;
+    }
+    if (topic === "budgets") {
+        console.log([
+            "Budgets:",
+            "  - categories: performance, accessibility, bestPractices, seo (0-100 scores)",
+            "  - metrics: lcpMs, fcpMs, tbtMs, cls, inpMs (numeric thresholds)",
+            "Example apex.config.json budget:",
+            '  "budgets": {',
+            '    "categories": { "performance": 80, "accessibility": 90 },',
+            '    "metrics": { "lcpMs": 2500, "inpMs": 200 }',
+            "  }",
+            "",
+            "CI behaviour:",
+            "  - --ci exits non-zero if any budget is under/over its limit",
+            "  - Summary prints violations; JSON includes full results",
+        ].join("\n"));
+        return;
+    }
+    if (topic === "configs") {
+        console.log([
+            "Config (apex.config.json):",
+            "  baseUrl (required)     Base URL of your running site",
+            "  query                  Query string appended to every path (e.g., ?lhci=1)",
+            "  buildId                Build identifier used for incremental cache keys",
+            "  runs                   Runs per page/device (must be 1; rerun command to compare)",
+            "  auditTimeoutMs         Per-audit timeout in milliseconds (prevents hung runs from stalling)",
+            "  throttlingMethod       simulate | devtools (default simulate)",
+            "  cpuSlowdownMultiplier  CPU slowdown (default 4)",
+            "  parallel               Workers (default auto up to 4, respects CPU/memory)",
+            "  warmUp                 true/false to warm cache before auditing (bounded concurrency)",
+            "  incremental            (deprecated default) Set in config but only active when --incremental is passed",
+            "  pages                  Array of { path, label, devices: [mobile|desktop] }",
+            "  budgets                Optional { categories, metrics } thresholds",
+            "",
+            "Tip:",
+            "  For best accuracy and stable throughput, run audits against a production server (e.g., Next.js: next build && next start)",
+        ].join("\n"));
+        return;
+    }
+    if (topic === "ci") {
+        console.log([
+            "CI mode:",
+            "  - Use --ci to enable budgets and non-zero exit codes on failures",
+            "  - Exit code 1 if any budget fails or a runtime error occurs",
+            "  - Use --json to pipe results to other tools",
+            "  - Combine with --parallel and --throttling for speed/accuracy trade-offs",
+        ].join("\n"));
+        return;
+    }
     console.log([
         "ApexAuditor CLI",
         "",
         "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 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",
-        "  audit    Run Lighthouse audits using apex.config.json",
-        "  help     Show this help message",
+        "  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)",
+        "  help       Show this help message",
         "",
         "Options (audit):",
         "  --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)",
         "  --color            Force ANSI colours in console output",
         "  --log-level <lvl>  Override Lighthouse log level: silent|error|info|verbose",
+        "  --stable           Flake-resistant mode: forces parallel=1, good for big suites or flaky runners",
         "  --mobile-only      Run audits only for 'mobile' devices defined in the config",
         "  --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)",
+        "  --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)",
+        "  --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)",
+        "  --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.",
+        "  --build-id <id>    Build identifier used as the cache key boundary for --incremental",
+        "  --overview         Preset: quick overview (runs=1) and samples a small set of combos unless --yes.",
+        "  --overview-combos <n>  Overview sampling size (default 10).",
+        "  --quick            Preset: fast feedback (runs=1) without changing throttling defaults",
+        "  --accurate         Preset: devtools throttling + warm-up + stability-first (parallel=1 unless overridden)",
+        "  --open             Open the HTML report after the run.",
+        "",
+        "Outputs:",
+        "  - Writes .apex-auditor/summary.json, summary.md, report.html",
+        "  - Prints a file:// link to the HTML report after completion",
+        "",
+        "Quick start:",
+        "  pnpm dlx apex-auditor@latest wizard      # guided setup",
+        "  pnpm dlx apex-auditor@latest audit       # run with apex.config.json",
+        "",
+        "Defaults:",
+        "  - Parallel auto-tunes from CPU/memory (up to 4 by default)",
+        "  - Throttling: simulate, CPU slowdown: 4, Runs: 1",
+        "  - Stable: use --stable to force serial runs when parallel flakes (e.g., TargetClose/Lantern errors)",
+        "  - Accuracy tip: run against a production server (e.g., Next.js: next build && next start)",
+        "  - Incremental: use --incremental --build-id <id> to skip unchanged audits between runs",
+        "  - Presets: choose only one of --fast, --quick, --accurate",
+        "",
+        "More help:",
+        "  apex-auditor help topics",
+        "  apex-auditor help budgets",
     ].join("\n"));
 }
 export async function runBin(argv) {
     const parsed = parseBinArgs(argv);
     if (parsed.command === "help") {
-        printHelp();
+        const topic = argv[3];
+        printHelp(topic);
+        return;
+    }
+    if (parsed.command === "shell") {
+        await runShellCli(parsed.argv);
         return;
     }
     if (parsed.command === "quickstart") {
@@ -48,11 +175,60 @@ export async function runBin(argv) {
         return;
     }
     if (parsed.command === "audit") {
-        await runAuditCli(parsed.argv);
+        try {
+            await runAuditCli(parsed.argv);
+        }
+        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 (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"]);
+        }
         return;
     }
-    if (parsed.command === "wizard") {
+    if (parsed.command === "measure") {
+        try {
+            await runMeasureCli(parsed.argv);
+        }
+        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 (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"]);
+        }
+        return;
+    }
+    if (parsed.command === "init") {
         await runWizardCli(parsed.argv);
+        if (process.stdin.isTTY && process.stdout.isTTY) {
+            // 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"]);
+        }
+        return;
+    }
+    if (parsed.command === "wizard" || parsed.command === "guide") {
+        await runWizardCli(parsed.argv);
+        if (process.stdin.isTTY && process.stdout.isTTY) {
+            await runShellCli(["node", "apex-auditor"]);
+        }
+        return;
     }
 }
 void runBin(process.argv).catch((error) => {