cbrowser 2.2.0

package/docs/INSTALL.md

@@ -0,0 +1,237 @@
+# CBrowser Installation Guide
+
+## Quick Install
+
+```bash
+# npm
+npm install cbrowser
+
+# yarn
+yarn add cbrowser
+
+# bun
+bun add cbrowser
+
+# pnpm
+pnpm add cbrowser
+```
+
+## Browser Setup
+
+CBrowser uses Playwright for browser automation. After installing, you need to install the browser binaries:
+
+```bash
+npx playwright install chromium
+```
+
+This downloads Chromium (~150MB). For full browser support:
+
+```bash
+npx playwright install  # Installs Chromium, Firefox, and WebKit
+```
+
+## Verify Installation
+
+```bash
+npx cbrowser help
+```
+
+You should see the help text with all available commands.
+
+## Configuration
+
+### Data Directory
+
+By default, CBrowser stores data in `~/.cbrowser/`. To change this:
+
+```bash
+# Set environment variable
+export CBROWSER_DATA_DIR="/path/to/custom/dir"
+
+# Or per-command
+CBROWSER_DATA_DIR="./data" npx cbrowser navigate "https://example.com"
+```
+
+### Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `CBROWSER_DATA_DIR` | `~/.cbrowser` | Data storage directory |
+| `CBROWSER_HEADLESS` | `false` | Run headless by default |
+| `CBROWSER_TIMEOUT` | `30000` | Default timeout (ms) |
+| `CBROWSER_VIEWPORT_WIDTH` | `1280` | Default viewport width |
+| `CBROWSER_VIEWPORT_HEIGHT` | `800` | Default viewport height |
+| `CBROWSER_VERBOSE` | `false` | Enable verbose logging |
+
+### Persistent Configuration
+
+Create a `.cbrowserrc` file in your project or home directory:
+
+```json
+{
+  "headless": true,
+  "timeout": 60000,
+  "viewportWidth": 1920,
+  "viewportHeight": 1080
+}
+```
+
+## Platform-Specific Notes
+
+### Linux
+
+If running on a headless server, you may need additional dependencies:
+
+```bash
+# Ubuntu/Debian
+sudo apt-get install libnss3 libatk1.0-0 libatk-bridge2.0-0 libcups2 libdrm2 libxkbcommon0 libxcomposite1 libxdamage1 libxfixes3 libxrandr2 libgbm1 libpango-1.0-0 libcairo2 libasound2
+
+# Or use Playwright's helper
+npx playwright install-deps chromium
+```
+
+### macOS
+
+No additional setup required. Works out of the box.
+
+### Windows
+
+No additional setup required. Works out of the box.
+
+### Docker
+
+```dockerfile
+FROM node:20-slim
+
+# Install Playwright dependencies
+RUN apt-get update && apt-get install -y \
+    libnss3 libatk1.0-0 libatk-bridge2.0-0 libcups2 libdrm2 \
+    libxkbcommon0 libxcomposite1 libxdamage1 libxfixes3 libxrandr2 \
+    libgbm1 libpango-1.0-0 libcairo2 libasound2 \
+    && rm -rf /var/lib/apt/lists/*
+
+WORKDIR /app
+COPY package*.json ./
+RUN npm install
+
+# Install browser
+RUN npx playwright install chromium
+
+COPY . .
+
+# Run in headless mode
+ENV CBROWSER_HEADLESS=true
+
+CMD ["npx", "cbrowser", "help"]
+```
+
+## CI/CD Integration
+
+### GitHub Actions
+
+```yaml
+name: Browser Tests
+
+on: [push, pull_request]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      - run: npm install
+      - run: npx playwright install chromium
+
+      - name: Run CBrowser tests
+        run: npm test
+        env:
+          CBROWSER_HEADLESS: true
+```
+
+### GitLab CI
+
+```yaml
+test:
+  image: mcr.microsoft.com/playwright:v1.40.0
+  script:
+    - npm install
+    - npm test
+  variables:
+    CBROWSER_HEADLESS: "true"
+```
+
+## Troubleshooting
+
+### "Browser not found" Error
+
+```bash
+# Reinstall browser
+npx playwright install chromium --force
+```
+
+### Permission Denied on Linux
+
+```bash
+# Make data directory writable
+sudo chown -R $USER:$USER ~/.cbrowser
+chmod -R 755 ~/.cbrowser
+```
+
+### Timeout Errors
+
+Increase the default timeout:
+
+```bash
+CBROWSER_TIMEOUT=60000 npx cbrowser navigate "https://slow-site.com"
+```
+
+### Display Issues (Linux Server)
+
+Use headless mode:
+
+```bash
+CBROWSER_HEADLESS=true npx cbrowser navigate "https://example.com"
+```
+
+Or set up a virtual display:
+
+```bash
+# Install Xvfb
+sudo apt-get install xvfb
+
+# Run with virtual display
+xvfb-run npx cbrowser navigate "https://example.com"
+```
+
+## Upgrading
+
+```bash
+# npm
+npm update cbrowser
+
+# Check version
+npx cbrowser --version
+```
+
+## Uninstalling
+
+```bash
+# Remove package
+npm uninstall cbrowser
+
+# Remove data directory (optional)
+rm -rf ~/.cbrowser
+
+# Remove Playwright browsers (optional)
+rm -rf ~/.cache/ms-playwright
+```
+
+## Getting Help
+
+- Check [README.md](../README.md) for usage examples
+- Open an issue on GitHub for bugs
+- See [CONTRIBUTING.md](../CONTRIBUTING.md) for development setup

package/examples/basic-usage.ts

@@ -0,0 +1,96 @@
+/**
+ * CBrowser Basic Usage Examples
+ *
+ * Run with: npx ts-node examples/basic-usage.ts
+ */
+
+import { CBrowser } from "../src/index.js";
+
+async function basicNavigation() {
+  console.log("=== Basic Navigation ===\n");
+
+  const browser = new CBrowser({ headless: true });
+
+  try {
+    // Navigate to a page
+    const result = await browser.navigate("https://example.com");
+    console.log(`Navigated to: ${result.url}`);
+    console.log(`Page title: ${result.title}`);
+    console.log(`Load time: ${result.loadTime}ms`);
+
+    // Extract headings
+    const headings = await browser.extract("headings");
+    console.log("\nHeadings found:", JSON.stringify(headings.data, null, 2));
+
+    // Take a screenshot
+    const screenshot = await browser.screenshot("./example-screenshot.png");
+    console.log(`\nScreenshot saved: ${screenshot}`);
+  } finally {
+    await browser.close();
+  }
+}
+
+async function sessionPersistence() {
+  console.log("\n=== Session Persistence ===\n");
+
+  const browser = new CBrowser({ headless: true });
+
+  try {
+    // Navigate and save session
+    await browser.navigate("https://example.com");
+    await browser.saveSession("example-session");
+    console.log("Session saved: example-session");
+
+    // List sessions
+    const sessions = browser.listSessions();
+    console.log("Available sessions:", sessions);
+  } finally {
+    await browser.close();
+  }
+
+  // New browser instance, load session
+  const browser2 = new CBrowser({ headless: true });
+
+  try {
+    const loaded = await browser2.loadSession("example-session");
+    console.log(`Session loaded: ${loaded}`);
+  } finally {
+    await browser2.close();
+  }
+}
+
+async function personaJourney() {
+  console.log("\n=== Persona Journey ===\n");
+
+  const browser = new CBrowser({ headless: true });
+
+  try {
+    const result = await browser.journey({
+      persona: "first-timer",
+      startUrl: "https://example.com",
+      goal: "Find more information",
+      maxSteps: 5,
+    });
+
+    console.log(`Journey completed: ${result.success}`);
+    console.log(`Steps taken: ${result.steps.length}`);
+    console.log(`Total time: ${result.totalTime}ms`);
+
+    if (result.frictionPoints.length > 0) {
+      console.log("\nFriction points found:");
+      for (const point of result.frictionPoints) {
+        console.log(`  - ${point}`);
+      }
+    }
+  } finally {
+    await browser.close();
+  }
+}
+
+async function main() {
+  await basicNavigation();
+  await sessionPersistence();
+  await personaJourney();
+}
+
+main().catch(console.error);

package/examples/journeys/checkout-flow.json

@@ -0,0 +1,35 @@
+{
+  "name": "checkout-flow",
+  "description": "Test the complete checkout process",
+  "persona": "first-timer",
+  "startUrl": "https://example-shop.com",
+  "goal": "Complete a purchase from product selection to confirmation",
+  "maxSteps": 30,
+  "expectedSteps": [
+    {
+      "description": "Find a product",
+      "successIndicators": ["product page", "add to cart button"]
+    },
+    {
+      "description": "Add to cart",
+      "successIndicators": ["cart updated", "item added"]
+    },
+    {
+      "description": "View cart",
+      "successIndicators": ["cart page", "checkout button"]
+    },
+    {
+      "description": "Begin checkout",
+      "successIndicators": ["checkout form", "shipping address"]
+    },
+    {
+      "description": "Complete purchase",
+      "successIndicators": ["confirmation", "order number", "thank you"]
+    }
+  ],
+  "frictionThresholds": {
+    "maxTimePerStep": 30000,
+    "maxErrorsPerStep": 2,
+    "maxBacktracks": 3
+  }
+}

package/examples/personas/custom-persona.json

@@ -0,0 +1,45 @@
+{
+  "name": "qa-tester",
+  "description": "QA tester systematically checking functionality",
+  "demographics": {
+    "age_range": "25-40",
+    "tech_level": "expert",
+    "device": "desktop"
+  },
+  "behaviors": {
+    "methodical": true,
+    "checks_edge_cases": true,
+    "documents_issues": true,
+    "follows_test_plans": true
+  },
+  "humanBehavior": {
+    "timing": {
+      "reactionTime": { "min": 200, "max": 500 },
+      "clickDelay": { "min": 100, "max": 300 },
+      "typeSpeed": { "min": 50, "max": 100 },
+      "readingSpeed": 300,
+      "scrollPauseTime": { "min": 200, "max": 500 }
+    },
+    "errors": {
+      "misClickRate": 0.03,
+      "doubleClickAccidental": 0.02,
+      "typoRate": 0.03,
+      "backtrackRate": 0.1
+    },
+    "mouse": {
+      "curvature": 0.3,
+      "jitter": 3,
+      "overshoot": 0.08,
+      "speed": "normal"
+    },
+    "attention": {
+      "pattern": "thorough",
+      "scrollBehavior": "chunked",
+      "focusAreas": ["cta", "text", "images"],
+      "distractionRate": 0.05
+    }
+  },
+  "context": {
+    "viewport": [1920, 1080]
+  }
+}

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "cbrowser",
+  "version": "2.2.0",
+  "description": "AI-powered browser automation with constitutional safety, personas, session persistence, and autonomous journeys",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "cbrowser": "./dist/cli.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "start": "bun run src/cli.ts",
+    "test": "bun test",
+    "lint": "eslint src/",
+    "clean": "rm -rf dist/",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "browser-automation",
+    "playwright",
+    "ai-testing",
+    "web-scraping",
+    "e2e-testing",
+    "persona-testing",
+    "session-management",
+    "constitutional-ai",
+    "autonomous-agent"
+  ],
+  "author": "Your Name",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/yourusername/cbrowser.git"
+  },
+  "bugs": {
+    "url": "https://github.com/yourusername/cbrowser/issues"
+  },
+  "homepage": "https://github.com/yourusername/cbrowser#readme",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "playwright": "^1.40.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.10.0",
+    "typescript": "^5.3.0",
+    "eslint": "^8.55.0",
+    "@typescript-eslint/eslint-plugin": "^6.13.0",
+    "@typescript-eslint/parser": "^6.13.0"
+  },
+  "files": [
+    "dist/",
+    "examples/",
+    "docs/",
+    "README.md",
+    "LICENSE"
+  ]
+}