cbrowser 18.53.0 → 18.55.0

package/README.md

@@ -16,6 +16,59 @@ npx cbrowser cognitive-effort --url "https://your-site.com" --persona first-time
 
 ---
 
+## 5-Minute Quickstart
+
+Get from zero to your first cognitive insight in 3 commands:
+
+```bash
+# 1. Install CBrowser
+npm install cbrowser
+
+# 2. Install the browser engine (~150MB)
+npx playwright install chromium
+
+# 3. Run your first cognitive audit
+npx cbrowser cognitive-effort --url "https://your-site.com" --persona first-timer
+```
+
+**What you get:** A cognitive transport score (0-1), abandonment risk percentage, and the UX bottleneck — in under 30 seconds.
+
+**No API key needed** for basic commands (navigate, screenshot, click, extract, explore). Cognitive journeys require an Anthropic API key:
+
+```bash
+npx cbrowser config set-api-key <your-anthropic-key>
+```
+
+**Check your environment:** Run `npx cbrowser doctor` to verify everything is set up correctly.
+
+**Accessibility:** CBrowser supports `--no-color` (or `NO_COLOR` env var), `--plain` (no emoji/decorations), and `--json-output` (structured JSON) for screen readers, CI pipelines, and scripting.
+
+---
+
+## Table of Contents
+
+- [5-Minute Quickstart](#5-minute-quickstart)
+- [Cognitive Transport Chain](#cognitive-transport-chain)
+- [Visual Overlays & Attention Analysis](#visual-overlays--attention-analysis)
+- [AI Friendliness Suite](#ai-friendliness-suite)
+- [Cognitive User Simulation](#cognitive-user-simulation)
+- [Accessibility Empathy Testing](#accessibility-empathy-testing)
+- [Constitutional AI Safety](#constitutional-ai-safety)
+- [Site Knowledge System](#site-knowledge-system)
+- [Natural Language Testing](#natural-language-testing)
+- [Visual Testing](#visual-testing)
+- [Competitive UX Benchmark](#competitive-ux-benchmark)
+- [Geo Proxy](#geo-proxy)
+- [MCP Server Integration](#mcp-server-integration)
+- [CI/CD Integration](#cicd-integration)
+- [API Reference](#api-reference)
+- [Configuration](#configuration)
+- [Enterprise Edition](#enterprise-edition)
+- [Contributing](#contributing)
+- [License](#license)
+
+---
+
 ## Cognitive Transport Chain
 
 The 6-layer Sequential Transport Chain computes exactly how hard your page is for any persona — and predicts whether they'll abandon:
@@ -263,7 +316,7 @@ CBrowser runs as an MCP server for Claude Desktop and claude.ai.
 ### Remote MCP (claude.ai)
 
 **Public Demo Server** (rate-limited):
-```
+```text
 https://demo.cbrowser.ai/mcp
 ```
 

package/dist/cli.js

@@ -30,6 +30,8 @@ import { runCognitiveJourney, getAnthropicApiKey, setAnthropicApiKey, removeAnth
 import { getLightpandaStatus, LIGHTPANDA_SETUP_GUIDE, LIGHTPANDA_SECURITY_WARNING, isLightpandaConfigured, } from "./lightpanda.js";
 // Version from package.json - single source of truth
 import { VERSION } from "./version.js";
+// Accessible output system (v18.54.0)
+import { detectOutputOptions, setOutputOptions, getOutputOptions, installOutputWrappers, emitJson, } from "./output.js";
 // Node readline for interactive input
 import * as readline from "readline";
 /**
@@ -654,6 +656,12 @@ DIAGNOSTICS
   version, -v, --version      Show version number
   status                      Show environment status and diagnostics
                               Displays data directories, browsers, config, heal cache
+  doctor                      Check environment health (Node, Playwright, API key)
+
+ACCESSIBILITY
+  --no-color                  Disable all color output (also respects NO_COLOR env var)
+  --plain                     Disable emoji, box-drawing, and unicode decorations
+  --json-output               Output structured JSON (for scripts and screen readers)
 
 STORAGE & CLEANUP
   storage                     Show storage usage statistics
@@ -1030,6 +1038,121 @@ function generateTestSuiteHtmlReport(result) {
 </body>
 </html>`;
 }
+/**
+ * Doctor command — validates environment health with pass/fail checks.
+ * Checks: Node version, Playwright chromium, API key, data directory.
+ */
+async function runDoctor(outputOpts) {
+    const fs = await import("fs");
+    const { execSync } = await import("child_process");
+    const checks = [];
+    // Check 1: Node.js version
+    const nodeVersion = process.versions.node;
+    const nodeMajor = parseInt(nodeVersion.split(".")[0], 10);
+    if (nodeMajor >= 18) {
+        checks.push({ name: "Node.js", status: "pass", message: `v${nodeVersion} (>= 18 required)` });
+    }
+    else {
+        checks.push({
+            name: "Node.js",
+            status: "fail",
+            message: `v${nodeVersion} (>= 18 required)`,
+            fix: "Install Node.js 18+ from https://nodejs.org",
+        });
+    }
+    // Check 2: Playwright chromium — verify binary exists without launching a full browser
+    try {
+        execSync("npx playwright install --dry-run chromium 2>&1", {
+            encoding: "utf8",
+            timeout: 15000,
+        });
+        checks.push({ name: "Playwright Chromium", status: "pass", message: "Installed" });
+    }
+    catch {
+        checks.push({
+            name: "Playwright Chromium",
+            status: "fail",
+            message: "Not installed or not launchable",
+            fix: "Run: npx playwright install chromium",
+        });
+    }
+    // Check 3: API key
+    const hasApiKey = isApiKeyConfigured();
+    if (hasApiKey) {
+        checks.push({ name: "Anthropic API Key", status: "pass", message: "Configured" });
+    }
+    else {
+        checks.push({
+            name: "Anthropic API Key",
+            status: "warn",
+            message: "Not configured (cognitive features require it, basic commands work without it)",
+            fix: "Run: cbrowser config set-api-key <your-key>",
+        });
+    }
+    // Check 4: Data directory
+    const dataDir = getDataDir();
+    try {
+        await fs.promises.access(dataDir, fs.constants.W_OK);
+        checks.push({ name: "Data Directory", status: "pass", message: dataDir });
+    }
+    catch {
+        checks.push({
+            name: "Data Directory",
+            status: "fail",
+            message: `${dataDir} (not writable)`,
+            fix: process.platform === "win32"
+                ? "Check directory permissions in Properties"
+                : `Run: sudo chown -R $USER:$USER ${dataDir}`,
+        });
+    }
+    // Output results
+    if (outputOpts.json) {
+        const jsonResult = {
+            success: checks.every(c => c.status !== "fail"),
+            command: "doctor",
+            data: { checks },
+            meta: { version: VERSION },
+        };
+        emitJson(jsonResult);
+        return;
+    }
+    const passSymbol = outputOpts.plain ? "[PASS]" : "✅";
+    const failSymbol = outputOpts.plain ? "[FAIL]" : "❌";
+    const warnSymbol = outputOpts.plain ? "[WARN]" : "⚠️";
+    console.log("");
+    console.log(outputOpts.plain
+        ? `CBrowser Doctor v${VERSION}`
+        : `🩺 CBrowser Doctor v${VERSION}`);
+    console.log(outputOpts.plain ? "---" : "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━");
+    for (const check of checks) {
+        const symbol = check.status === "pass" ? passSymbol
+            : check.status === "fail" ? failSymbol
+                : warnSymbol;
+        console.log(`${symbol} ${check.name}: ${check.message}`);
+        if (check.fix) {
+            console.log(`     Fix: ${check.fix}`);
+        }
+    }
+    console.log("");
+    const failCount = checks.filter(c => c.status === "fail").length;
+    const warnCount = checks.filter(c => c.status === "warn").length;
+    if (failCount === 0 && warnCount === 0) {
+        console.log(outputOpts.plain
+            ? "All checks passed. CBrowser is ready."
+            : "🎉 All checks passed. CBrowser is ready!");
+    }
+    else if (failCount === 0) {
+        console.log(outputOpts.plain
+            ? `All critical checks passed. ${warnCount} warning(s).`
+            : `✅ All critical checks passed. ${warnCount} warning(s).`);
+    }
+    else {
+        console.log(outputOpts.plain
+            ? `${failCount} check(s) failed. Fix the issues above to use CBrowser.`
+            : `❌ ${failCount} check(s) failed. Fix the issues above to use CBrowser.`);
+    }
+    console.log("");
+}
 function parseGeoLocation(location) {
     // Check if it's a preset
     if (LOCATION_PRESETS[location]) {
@@ -1048,10 +1171,19 @@ function parseGeoLocation(location) {
 }
 async function main() {
     const { command, args, options } = parseArgs(process.argv.slice(2));
+    // Initialize accessible output system (v18.54.0)
+    const outputOpts = detectOutputOptions(options);
+    setOutputOptions(outputOpts);
+    installOutputWrappers();
     if (command === "help" || options.help) {
         showHelp();
         process.exit(0);
     }
+    // Doctor command - environment health check (v18.54.0)
+    if (command === "doctor") {
+        await runDoctor(outputOpts);
+        process.exit(0);
+    }
     // MCP Server mode - runs before browser instantiation
     if (command === "mcp-server") {
         console.error("🔌 Starting CBrowser MCP Server...");
@@ -5253,7 +5385,36 @@ Examples:
     process.exit(0);
 }
 main().catch((error) => {
-    console.error("Error:", error.message);
+    const opts = getOutputOptions();
+    if (opts.json) {
+        const jsonError = {
+            success: false,
+            command: process.argv[2] || "unknown",
+            error: {
+                code: error.code || "E999",
+                message: error.message,
+                howToFix: error.howToFix,
+                docUrl: error.docUrl,
+            },
+            meta: { version: VERSION },
+        };
+        emitJson(jsonError);
+        process.exit(1);
+    }
+    // Enriched error output with remediation guidance
+    if (error.howToFix) {
+        console.error("");
+        console.error(opts.plain ? `Error [${error.code}]: ${error.message}` : `❌ Error [${error.code}]: ${error.message}`);
+        console.error("");
+        console.error(opts.plain ? `How to fix: ${error.howToFix}` : `💡 How to fix: ${error.howToFix}`);
+        if (error.docUrl) {
+            console.error(opts.plain ? `Docs: ${error.docUrl}` : `📚 Docs: ${error.docUrl}`);
+        }
+        console.error("");
+    }
+    else {
+        console.error("Error:", error.message);
+    }
     process.exit(1);
 });
 //# sourceMappingURL=cli.js.map