site-agent-pro 1.0.6 → 1.0.8

package/README.md

@@ -62,66 +62,34 @@ User submits URL + tasks
 
 ## Quick Start
 
-> **Using site-agent-pro in your own project?** Install it as a devDependency instead of cloning:
-> ```bash
-> npm install --save-dev site-agent-pro
-> 
-> # Run a quick audit
-> site-agent-pro --url http://localhost:3000 --task "Check the homepage"
-> 
-> # OR launch the web UI to enter tasks visually
-> site-agent-pro ui
-> ```
-> See [Programmatic API](#programmatic-api) for scripted and CI usage.
-
-### 1. Install (self-hosted / contributor setup)
+> **Site Agent Pro** is a zero-config AI visitor. Install it, initialize your identity, and run your first audit in seconds.
 
-```bash
-npm install
-npm run browser:install
-```
-
-### 2. Configure
-
-```bash
-cp .env.example .env
-```
-
-Set your LLM provider in `.env`:
+### 1. Install & Initialize
 
 ```bash
-# Option A: OpenAI (recommended for production)
-LLM_PROVIDER=openai
-OPENAI_API_KEY=your_key_here
+# Install globally
+npm install -g site-agent-pro
 
-LLM_PROVIDER=ollama
-OLLAMA_MODEL=llama3.1:8b
+# Set up your identity (OpenAI Key, Wallet, etc.)
+site-agent-pro init
 ```
 
-#### Sensitive Data & CLI Overrides
-If you prefer not to save sensitive credentials in your `.env` file, you can pass them directly via the CLI:
+### 2. Run an Audit
 
-```bash
-npx site-agent-pro --url https://example.com \
-  --openai-api-key "sk-..." \
-  --imap-password "your-app-password" \
-  --auth-password "test-user-password" \
-  --private-key "0x..."
-```
-CLI flags always take precedence over values in `.env`.
-
-### 3. Run
+The agent handles everything else, including **automatically installing its own browser** on the first run.
 
 ```bash
-# Run the agent against a site
-npm run dev -- --url https://example.com \
-  --task "Open pricing and compare the visible plans before signup"
+# Run a quick audit
+site-agent-pro --url https://google.com --task "Check the homepage"
 
-# Start the web dashboard
-npm run dashboard
-# → http://localhost:4173
+# OR launch the web UI to enter tasks visually
+site-agent-pro ui
 ```
 
+### 3. View Results
+
+Artifacts are saved to `data/runs/<run-id>/` (or your current directory if using the local `.env`):
+
 ### 4. View Results
 
 Artifacts are saved to `runs/<run-id>/`:
@@ -264,7 +232,7 @@ For full control, import the lower-level API directly:
 import { runAuditJob, buildCustomTaskSuite, normalizeCustomTasks } from "site-agent-pro";
 ```
 
-> **Note:** site-agent-pro requires Playwright's Chromium browser. Run `npx playwright install chromium` once after installing the package.
+> **Note:** site-agent-pro requires Playwright's Chromium browser. Run `` once after installing the package.
 
 ---
 
@@ -608,7 +576,7 @@ This repo now targets a standard Render web service deployment:
 The repo root includes a Render Blueprint with:
 
 - `runtime: node`
-- `buildCommand: npm ci && npm run build && npm run browser:install`
+- `buildCommand: npm ci && npm run build && `
 - `startCommand: npm run render:start`
 - `healthCheckPath: /health`
 - a persistent disk mounted at `/opt/render/project/src/data`

package/dist/cli/run.js

@@ -15,6 +15,25 @@ import { resolveRunDir } from "../utils/files.js";
 import { info, warn } from "../utils/log.js";
 import { startDashboard } from "../dashboard/server.js";
 import { updateWalletSettings } from "../wallet/wallet.js";
+import fs from "node:fs";
+import { fileURLToPath } from "node:url";
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+let pkgVersion = "1.0.0";
+try {
+    let pkgDir = __dirname;
+    for (let i = 0; i < 5; i++) {
+        const pkgPath = path.join(pkgDir, "package.json");
+        if (fs.existsSync(pkgPath)) {
+            pkgVersion = JSON.parse(fs.readFileSync(pkgPath, "utf8")).version;
+            break;
+        }
+        pkgDir = path.dirname(pkgDir);
+    }
+}
+catch (e) {
+    // Ignored fallback
+}
 const program = new Command();
 function summarizeCliPath(filePath) {
     const relativePath = path.relative(process.cwd(), filePath);
@@ -62,21 +81,8 @@ function openUrl(url) {
 }
 program
     .name("site-agent-pro")
-    .description("AI-powered browser agent for website auditing and side-by-side development");
-program
-    .command("install-browsers")
-    .description("Download the necessary browser binaries (Playwright Chromium)")
-    .action(async () => {
-    const { execSync } = await import("node:child_process");
-    console.log("Downloading browsers... this may take a minute.");
-    try {
-        execSync("npx playwright install chromium", { stdio: "inherit" });
-        console.log("✅ Browsers installed successfully!");
-    }
-    catch (err) {
-        console.error(`❌ Failed to install browsers: ${err.message}`);
-    }
-});
+    .description("AI-powered browser agent for website auditing and side-by-side development")
+    .version(pkgVersion);
 program
     .command("init")
     .description("Initialize global configuration at ~/.site-agent-pro/.env")

package/dist/core/runner.js

@@ -1,6 +1,6 @@
 import fs from "node:fs";
 import path from "node:path";
-import { chromium, devices } from "playwright";
+import { devices } from "playwright";
 import { captureInboxCheckpoint, waitForVerificationEmail } from "../auth/inbox.js";
 import { getMailboxConfig, getPreferredAccessIdentity, isAuthBootstrapConfigured } from "../auth/profile.js";
 import { detectAuthWall, runAuthFlowInContext } from "../auth/runner.js";
@@ -1695,14 +1695,16 @@ export async function runTaskSuite(options) {
                     ? `Launching MetaMask with persistent Chromium user data from '${summarizeLocalPath(userDataDir)}'.`
                     : `Launching MetaMask with the default persistent Chromium user data at '${summarizeLocalPath(userDataDir)}'. Set WALLET_METAMASK_USER_DATA_DIR to reuse a specific unlocked MetaMask profile.`
             });
-            context = await chromium.launchPersistentContext(userDataDir, {
+            const { launchPersistentWithSelfHealing } = await import("../utils/browser.js");
+            context = await launchPersistentWithSelfHealing(userDataDir, {
                 ...(await resolveLaunchOptions({ headed: options.headed })),
                 ...contextOptions
             });
             browser = context.browser();
         }
         else {
-            browser = await chromium.launch(await resolveLaunchOptions({ headed: options.headed }));
+            const { launchWithSelfHealing } = await import("../utils/browser.js");
+            browser = await launchWithSelfHealing(await resolveLaunchOptions({ headed: options.headed }));
             context = await browser.newContext(contextOptions);
         }
         await installPlaywrightPageCompat(context);

package/dist/dashboard/server.js

@@ -34,6 +34,28 @@ function resolveDashboardHost() {
     }
     return process.env.RENDER === "true" ? RENDER_HOST : DEFAULT_HOST;
 }
+function resolveDashboardDistDir() {
+    // __dirname may point to src/dashboard (tsx dev) or dist/dashboard (node prod).
+    // Walk up until we find the project root (contains package.json), then use dist/dashboard.
+    let dir = __dirname;
+    for (let i = 0; i < 5; i++) {
+        if (fs.existsSync(path.join(dir, "package.json"))) {
+            return path.join(dir, "dist", "dashboard");
+        }
+        dir = path.dirname(dir);
+    }
+    // Fallback: assume __dirname IS dist/dashboard already
+    return __dirname;
+}
+const DASHBOARD_DIST_DIR = resolveDashboardDistDir();
+function readDashboardScript(fileName) {
+    const filePath = path.join(DASHBOARD_DIST_DIR, fileName);
+    if (fs.existsSync(filePath)) {
+        return fs.readFileSync(filePath, "utf8");
+    }
+    warn(`Dashboard script not found: ${filePath} — run 'npm run build' first.`);
+    return "";
+}
 function renderDashboardHtml() {
     return `<!doctype html>
 <html lang="en">
@@ -198,7 +220,7 @@ async function handleRequest(req, res, args) {
     if (dashboardScripts.includes(pathParts[0] || "")) {
         const requestedName = pathParts[0];
         const diskName = requestedName === "app.js" ? "client.js" : requestedName;
-        const distPath = path.join(__dirname, diskName);
+        const distPath = path.join(DASHBOARD_DIST_DIR, diskName);
         if (fs.existsSync(distPath)) {
             sendText(res, 200, fs.readFileSync(distPath, "utf8"), "application/javascript");
             return;
@@ -436,6 +458,22 @@ export async function startDashboard(options = {}) {
     // Patch appBaseUrl into the request handler closure via a shared ref
     server.__appBaseUrl = appBaseUrl;
     info(`Dashboard ready at ${url}`);
+    // Auto-open browser in non-CI environments
+    if (process.env.NODE_ENV !== "test" && process.env.CI !== "true" && options.open !== false) {
+        import("node:child_process").then(({ exec }) => {
+            const command = process.platform === "win32" ? "start" : process.platform === "darwin" ? "open" : "xdg-open";
+            exec(`${command} ${url}`);
+        }).catch(() => {
+            // Ignore if opening fails
+        });
+    }
     submissionService.resumePendingSubmissions();
     return { server, port: boundPort, host, url };
 }
+// Support standalone execution via 'tsx src/dashboard/server.ts' or 'node dist/dashboard/server.js'
+if (import.meta.url === `file://${process.argv[1]}` || process.argv[1]?.endsWith("server.ts") || process.argv[1]?.endsWith("server.js")) {
+    startDashboard().catch((error) => {
+        console.error(`\n[ERROR] Dashboard failed to start: ${error instanceof Error ? error.message : String(error)}\n`);
+        process.exit(1);
+    });
+}

package/dist/utils/browser.js

@@ -0,0 +1,112 @@
+import { execSync } from "node:child_process";
+import fs from "node:fs";
+import { chromium } from "playwright";
+import { info, warn } from "./log.js";
+/**
+ * Discovers a system-installed Chrome/Chromium/Edge browser path.
+ */
+export function findSystemChrome() {
+    const envPaths = [
+        process.env.CHROME_PATH,
+        process.env.PUPPETEER_EXECUTABLE_PATH,
+        process.env.PLAYWRIGHT_CHROMIUM_EXECUTABLE_PATH
+    ];
+    for (const p of envPaths) {
+        if (p && fs.existsSync(p))
+            return p;
+    }
+    const isMac = process.platform === "darwin";
+    const isWin = process.platform === "win32";
+    const isLinux = process.platform === "linux";
+    let standardPaths = [];
+    if (isMac) {
+        standardPaths = [
+            "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
+            "/Applications/Chromium.app/Contents/MacOS/Chromium",
+            "/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge"
+        ];
+    }
+    else if (isWin) {
+        const prefixes = [
+            process.env.LOCALAPPDATA,
+            process.env.PROGRAMFILES,
+            process.env["PROGRAMFILES(X86)"]
+        ].filter(Boolean);
+        for (const prefix of prefixes) {
+            standardPaths.push(`${prefix}\\Google\\Chrome\\Application\\chrome.exe`, `${prefix}\\Chromium\\Application\\chrome.exe`, `${prefix}\\Microsoft\\Edge\\Application\\msedge.exe`);
+        }
+    }
+    else if (isLinux) {
+        standardPaths = [
+            "/usr/bin/google-chrome",
+            "/usr/bin/google-chrome-stable",
+            "/usr/bin/chromium-browser",
+            "/usr/bin/chromium",
+            "/usr/bin/microsoft-edge-stable"
+        ];
+    }
+    return standardPaths.find((p) => fs.existsSync(p));
+}
+/**
+ * Professional self-healing browser launcher.
+ * Tries system Chromium -> Playwright bundled -> Auto-installs if missing.
+ */
+export async function launchWithSelfHealing(launchOptions) {
+    const sysPath = findSystemChrome();
+    if (sysPath) {
+        try {
+            return await chromium.launch({ ...launchOptions, executablePath: sysPath });
+        }
+        catch (err) {
+            warn(`System browser at ${sysPath} failed to launch: ${err.message}. Falling back to bundled Chromium.`);
+        }
+    }
+    try {
+        return await chromium.launch(launchOptions);
+    }
+    catch (err) {
+        if (err.message.includes("Executable doesn't exist") || err.message.includes("playwright install")) {
+            info("🚀 Bundled Playwright browser missing. Automatically installing Chromium...");
+            try {
+                execSync("npx playwright install chromium", { stdio: "inherit" });
+                info("✅ Browser installed successfully! Retrying launch...");
+                return await chromium.launch(launchOptions);
+            }
+            catch (installErr) {
+                throw new Error(`Failed to auto-install Playwright browser: ${installErr.message}`);
+            }
+        }
+        throw err;
+    }
+}
+/**
+ * Self-healing launcher for persistent context (e.g. for MetaMask/Web3 flows).
+ */
+export async function launchPersistentWithSelfHealing(userDataDir, options) {
+    const sysPath = findSystemChrome();
+    if (sysPath) {
+        try {
+            return await chromium.launchPersistentContext(userDataDir, { ...options, executablePath: sysPath });
+        }
+        catch (err) {
+            warn(`System browser at ${sysPath} failed to launch: ${err.message}. Falling back to bundled Chromium.`);
+        }
+    }
+    try {
+        return await chromium.launchPersistentContext(userDataDir, options);
+    }
+    catch (err) {
+        if (err.message.includes("Executable doesn't exist") || err.message.includes("playwright install")) {
+            info("🚀 Bundled Playwright browser missing. Automatically installing Chromium...");
+            try {
+                execSync("npx playwright install chromium", { stdio: "inherit" });
+                info("✅ Browser installed successfully! Retrying launch...");
+                return await chromium.launchPersistentContext(userDataDir, options);
+            }
+            catch (installErr) {
+                throw new Error(`Failed to auto-install Playwright browser: ${installErr.message}`);
+            }
+        }
+        throw err;
+    }
+}

package/docs/01-installation.md

@@ -1,134 +1,62 @@
 # 01 - Installation
 
-There are two ways to use site-agent-pro. Choose the one that fits your workflow.
+**Site Agent Pro** is designed to be a zero-config experience. Choose the path that fits your workflow.
 
 ---
 
-## Track A — devDependency (recommended for most developers)
+## Track A — Global CLI (Recommended for most users)
 
-This is the right choice if you want to audit your own product as you build it, run audits in CI, or call site-agent-pro from scripts and test files.
+This is the fastest way to get started. Run it from any folder on your machine.
 
-### 1. Prerequisites
-
-- Node.js 20.10 or newer
-- npm 10 or newer
+### 1. Install Globally
 
 ```bash
-node -v
-npm -v
+npm install -g site-agent-pro
 ```
 
-### 2. Install in your project
-
-```bash
-npm install --save-dev site-agent-pro
-```
+### 2. Initialize Your Identity
 
-### 3. Install the Playwright browser
+Run the `init` command to set up your global configuration (~/.site-agent-pro/.env). This includes your OpenAI API Key and optionally your Paystack and Wallet details.
 
 ```bash
-npx playwright install chromium
+site-agent-pro init
 ```
 
-This only needs to be done once per machine or CI environment.
-
-### 4. Set your API key
-
-Create a `.env` file (or set environment variables) in your project root:
-
-```bash
-OPENAI_API_KEY=your_real_key_here
-```
+### 3. Run Your First Audit
 
-Or use Ollama for local/offline development (no API key needed):
+The agent handles everything else, including **automatically installing the required browser binaries** on the first run.
 
 ```bash
-LLM_PROVIDER=ollama
-OLLAMA_MODEL=llama3.1:8b
-```
-
-### 5. Run your first audit
-
-```bash
-# Against your running dev server
-site-agent-pro --url http://localhost:3000 --task "Check the homepage CTA"
-
-# Or add it to your package.json scripts
-# "audit": "site-agent-pro --url http://localhost:3000 --task 'Check the homepage'"
-# npm run audit
-```
-
-### 6. Or use it programmatically
-
-```ts
-import { runAudit } from "site-agent-pro";
-
-const result = await runAudit({
-  url: "http://localhost:3000",
-  tasks: ["Check the homepage CTA", "Try the signup flow"],
-});
-
-console.log(`Score: ${result.report.overall_score}/10`);
-
-if (result.report.overall_score < 7) {
-  process.exit(1); // Fail CI
-}
+site-agent-pro --url https://google.com --task "Verify the page loads correctly"
 ```
 
 ---
 
-## Track B — Clone and run (for contributors and self-hosting)
-
-Use this if you want to run the full web dashboard, modify the source, or self-host the submission server.
-
-### 1. Prerequisites
-
-- Node.js 20.10 or newer
-- npm 10 or newer
-- Git
-
-```bash
-node -v
-npm -v
-```
-
-### 2. Clone the repository
+## Track B — devDependency (For CI/CD and scripted usage)
 
-```bash
-git clone https://github.com/your-org/site-agent-pro.git
-cd site-agent-pro
-```
+Ideal for auditing your own products during development or as part of a build pipeline.
 
-### 3. Install dependencies
+### 1. Install in your project
 
 ```bash
-npm install
+npm install --save-dev site-agent-pro
 ```
 
-### 4. Install the Playwright browser
+### 2. Run with npx
 
-```bash
-npm run browser:install
-```
-
-### 5. Create your environment file
+Since it's a local dependency, use `npx` to run it. It will still use your global identity if found, or a local `.env`.
 
 ```bash
-cp .env.example .env
+npx site-agent-pro --url http://localhost:3000 --task "Check homepage"
 ```
 
-### 6. Add your OpenAI API key
-
-Open `.env` and set:
+---
 
-```bash
-OPENAI_API_KEY=your_real_key_here
-```
+## Troubleshooting
 
-### 7. Confirm TypeScript builds cleanly
+### "Executable doesn't exist"
+If for any reason the automatic installation fails (e.g., restricted network), you can force a browser install manually:
 
 ```bash
-npm run check
+npx playwright install chromium
 ```
-
-If this fails, do not keep going and pretend everything is fine. Fix the error first.

package/docs/02-running-your-first-audit.md

@@ -4,10 +4,13 @@
 
 | Setup | Command |
 |---|---|
-| Installed as npm devDependency | `site-agent-pro --url ... --task "..."` |
-| Cloned from source | `npm run dev -- --url ... --task "..."` |
+| Global CLI (Installed via -g) | `site-agent-pro --url ... --task "..."` |
+| devDependency (npx) | `npx site-agent-pro --url ... --task "..."` |
+| Contributor (npm run dev) | `npm run dev -- --url ... --task "..."` |
 
-All examples below use the `site-agent-pro` command. If you cloned the repo, replace it with `npm run dev --`.
+All examples below use the `site-agent-pro` command.
+
+> **Important**: Before running your first audit, make sure you've run `site-agent-pro init` to set up your API keys globally.
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "site-agent-pro",
-  "version": "1.0.6",
+  "version": "1.0.8",
   "type": "module",
   "description": "AI-powered browser agent that tests websites like a real user and produces evidence-based, scored reports.",
   "bin": {
@@ -23,9 +23,9 @@
     "dev": "tsx src/cli/run.ts",
     "trade:run": "tsx src/cli/trade.ts",
     "backfill:site-checks": "tsx src/cli/backfillSiteChecks.ts",
-    "dashboard": "tsx src/dashboard/server.ts",
-    "dashboard:start": "node dist/dashboard/server.js",
-    "render:start": "node dist/dashboard/server.js",
+    "dashboard": "tsx src/cli/run.ts ui",
+    "dashboard:start": "node dist/cli/run.js ui",
+    "render:start": "node dist/cli/run.js ui",
     "format": "prettier --write .",
     "lint": "eslint .",
     "browser:install": "playwright install chromium",