browser-pilot 0.0.3 → 0.0.5

package/dist/cli.cjs

@@ -214,6 +214,142 @@ async function actionsCommand() {
   console.log(ACTIONS_HELP);
 }
 
+// src/cli/session.ts
+var import_node_os = require("os");
+var import_node_path = require("path");
+var SESSION_DIR = (0, import_node_path.join)((0, import_node_os.homedir)(), ".browser-pilot", "sessions");
+async function ensureSessionDir() {
+  const fs = await import("fs/promises");
+  await fs.mkdir(SESSION_DIR, { recursive: true });
+}
+async function saveSession(session) {
+  await ensureSessionDir();
+  const fs = await import("fs/promises");
+  const filePath = (0, import_node_path.join)(SESSION_DIR, `${session.id}.json`);
+  await fs.writeFile(filePath, JSON.stringify(session, null, 2));
+}
+async function loadSession(id) {
+  const fs = await import("fs/promises");
+  const filePath = (0, import_node_path.join)(SESSION_DIR, `${id}.json`);
+  try {
+    const content = await fs.readFile(filePath, "utf-8");
+    return JSON.parse(content);
+  } catch (error) {
+    if (error.code === "ENOENT") {
+      throw new Error(`Session not found: ${id}`);
+    }
+    throw error;
+  }
+}
+async function updateSession(id, updates) {
+  const session = await loadSession(id);
+  const mergedMetadata = updates.metadata !== void 0 ? { ...session.metadata ?? {}, ...updates.metadata ?? {} } : session.metadata;
+  const updated = {
+    ...session,
+    ...updates,
+    metadata: mergedMetadata,
+    lastActivity: (/* @__PURE__ */ new Date()).toISOString()
+  };
+  await saveSession(updated);
+  return updated;
+}
+async function deleteSession(id) {
+  const fs = await import("fs/promises");
+  const filePath = (0, import_node_path.join)(SESSION_DIR, `${id}.json`);
+  try {
+    await fs.unlink(filePath);
+  } catch (error) {
+    if (error.code !== "ENOENT") {
+      throw error;
+    }
+  }
+}
+async function listSessions() {
+  await ensureSessionDir();
+  const fs = await import("fs/promises");
+  try {
+    const files = await fs.readdir(SESSION_DIR);
+    const sessions = [];
+    for (const file of files) {
+      if (file.endsWith(".json")) {
+        try {
+          const content = await fs.readFile((0, import_node_path.join)(SESSION_DIR, file), "utf-8");
+          sessions.push(JSON.parse(content));
+        } catch {
+        }
+      }
+    }
+    return sessions.sort(
+      (a, b) => new Date(b.lastActivity).getTime() - new Date(a.lastActivity).getTime()
+    );
+  } catch {
+    return [];
+  }
+}
+function generateSessionId() {
+  const timestamp = Date.now().toString(36);
+  const random = Math.random().toString(36).slice(2, 8);
+  return `${timestamp}-${random}`;
+}
+async function getDefaultSession() {
+  const sessions = await listSessions();
+  return sessions[0] ?? null;
+}
+
+// src/cli/commands/clean.ts
+function parseCleanArgs(args) {
+  const options = {};
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === "--max-age") {
+      const value = args[++i];
+      options.maxAge = parseInt(value ?? "24", 10);
+    } else if (arg === "--dry-run") {
+      options.dryRun = true;
+    } else if (arg === "--all") {
+      options.all = true;
+    }
+  }
+  return options;
+}
+async function cleanCommand(args, globalOptions) {
+  const options = parseCleanArgs(args);
+  const maxAgeMs = (options.maxAge ?? 24) * 60 * 60 * 1e3;
+  const now = Date.now();
+  const sessions = await listSessions();
+  const stale = sessions.filter((s) => {
+    if (options.all) return true;
+    const age = now - new Date(s.lastActivity).getTime();
+    return age > maxAgeMs;
+  });
+  if (stale.length === 0) {
+    output({ message: "No stale sessions found", cleaned: 0 }, globalOptions.output);
+    return;
+  }
+  if (options.dryRun) {
+    output(
+      {
+        message: `Would clean ${stale.length} session(s)`,
+        sessions: stale.map((s) => s.id),
+        dryRun: true
+      },
+      globalOptions.output
+    );
+    return;
+  }
+  for (const session of stale) {
+    await deleteSession(session.id);
+  }
+  output(
+    {
+      message: `Cleaned ${stale.length} session(s)`,
+      cleaned: stale.length,
+      sessions: stale.map((s) => s.id)
+    },
+    globalOptions.output
+  );
+}
+
 // src/actions/executor.ts
 var DEFAULT_TIMEOUT = 3e4;
 var BatchExecutor = class {
@@ -299,7 +435,8 @@ var BatchExecutor = class {
         await this.page.fill(step.selector, step.value, {
           timeout,
           optional,
-          clear: step.clear ?? true
+          clear: step.clear ?? true,
+          blur: step.blur
         });
         return { selectorUsed: this.getUsedSelector(step.selector) };
       }
@@ -1477,7 +1614,7 @@ var Page = class {
    * Fill an input field (clears first by default)
    */
   async fill(selector, value, options = {}) {
-    const { clear = true } = options;
+    const { clear = true, blur = false } = options;
     return this.withStaleNodeRetry(async () => {
       const element = await this.findElement(selector, options);
       if (!element) {
@@ -1491,7 +1628,11 @@ var Page = class {
             const el = document.querySelector(${JSON.stringify(element.selector)});
             if (el) {
               el.value = '';
-              el.dispatchEvent(new Event('input', { bubbles: true }));
+              el.dispatchEvent(new InputEvent('input', {
+                bubbles: true,
+                cancelable: true,
+                inputType: 'deleteContent'
+              }));
             }
           })()`
         );
@@ -1501,11 +1642,21 @@ var Page = class {
         `(() => {
           const el = document.querySelector(${JSON.stringify(element.selector)});
           if (el) {
-            el.dispatchEvent(new Event('input', { bubbles: true }));
+            el.dispatchEvent(new InputEvent('input', {
+              bubbles: true,
+              cancelable: true,
+              inputType: 'insertText',
+              data: ${JSON.stringify(value)}
+            }));
             el.dispatchEvent(new Event('change', { bubbles: true }));
           }
         })()`
       );
+      if (blur) {
+        await this.evaluateInFrame(
+          `document.querySelector(${JSON.stringify(element.selector)})?.blur()`
+        );
+      }
       return true;
     });
   }
@@ -2974,88 +3125,6 @@ function connect(options) {
   return Browser.connect(options);
 }
 
-// src/cli/session.ts
-var import_node_os = require("os");
-var import_node_path = require("path");
-var SESSION_DIR = (0, import_node_path.join)((0, import_node_os.homedir)(), ".browser-pilot", "sessions");
-async function ensureSessionDir() {
-  const fs = await import("fs/promises");
-  await fs.mkdir(SESSION_DIR, { recursive: true });
-}
-async function saveSession(session) {
-  await ensureSessionDir();
-  const fs = await import("fs/promises");
-  const filePath = (0, import_node_path.join)(SESSION_DIR, `${session.id}.json`);
-  await fs.writeFile(filePath, JSON.stringify(session, null, 2));
-}
-async function loadSession(id) {
-  const fs = await import("fs/promises");
-  const filePath = (0, import_node_path.join)(SESSION_DIR, `${id}.json`);
-  try {
-    const content = await fs.readFile(filePath, "utf-8");
-    return JSON.parse(content);
-  } catch (error) {
-    if (error.code === "ENOENT") {
-      throw new Error(`Session not found: ${id}`);
-    }
-    throw error;
-  }
-}
-async function updateSession(id, updates) {
-  const session = await loadSession(id);
-  const mergedMetadata = updates.metadata !== void 0 ? { ...session.metadata ?? {}, ...updates.metadata ?? {} } : session.metadata;
-  const updated = {
-    ...session,
-    ...updates,
-    metadata: mergedMetadata,
-    lastActivity: (/* @__PURE__ */ new Date()).toISOString()
-  };
-  await saveSession(updated);
-  return updated;
-}
-async function deleteSession(id) {
-  const fs = await import("fs/promises");
-  const filePath = (0, import_node_path.join)(SESSION_DIR, `${id}.json`);
-  try {
-    await fs.unlink(filePath);
-  } catch (error) {
-    if (error.code !== "ENOENT") {
-      throw error;
-    }
-  }
-}
-async function listSessions() {
-  await ensureSessionDir();
-  const fs = await import("fs/promises");
-  try {
-    const files = await fs.readdir(SESSION_DIR);
-    const sessions = [];
-    for (const file of files) {
-      if (file.endsWith(".json")) {
-        try {
-          const content = await fs.readFile((0, import_node_path.join)(SESSION_DIR, file), "utf-8");
-          sessions.push(JSON.parse(content));
-        } catch {
-        }
-      }
-    }
-    return sessions.sort(
-      (a, b) => new Date(b.lastActivity).getTime() - new Date(a.lastActivity).getTime()
-    );
-  } catch {
-    return [];
-  }
-}
-function generateSessionId() {
-  const timestamp = Date.now().toString(36);
-  const random = Math.random().toString(36).slice(2, 8);
-  return `${timestamp}-${random}`;
-}
-async function getDefaultSession() {
-  const sessions = await listSessions();
-  return sessions[0] ?? null;
-}
-
 // src/cli/commands/close.ts
 async function closeCommand(args, globalOptions) {
   let session;
@@ -3174,6 +3243,17 @@ async function connectCommand(args, globalOptions) {
 }
 
 // src/cli/commands/exec.ts
+async function validateSession(session) {
+  try {
+    const wsUrl = new URL(session.wsUrl);
+    const protocol = wsUrl.protocol === "wss:" ? "https:" : "http:";
+    const httpUrl = `${protocol}//${wsUrl.host}/json/version`;
+    const response = await fetch(httpUrl, { signal: AbortSignal.timeout(3e3) });
+    return response.ok;
+  } catch {
+    return false;
+  }
+}
 function parseExecArgs(args) {
   const options = {};
   let actionsJson;
@@ -3194,15 +3274,6 @@ function parseExecArgs(args) {
 }
 async function execCommand(args, globalOptions) {
   const { actionsJson, options: execOptions } = parseExecArgs(args);
-  let session;
-  if (globalOptions.session) {
-    session = await loadSession(globalOptions.session);
-  } else {
-    session = await getDefaultSession();
-    if (!session) {
-      throw new Error('No session found. Run "bp connect" first.');
-    }
-  }
   if (!actionsJson) {
     throw new Error(
       `No actions provided. Usage: bp exec '{"action":"goto","url":"..."}'
@@ -3218,6 +3289,23 @@ Run 'bp actions' for complete action reference.`
       "Invalid JSON. Actions must be valid JSON.\n\nRun 'bp actions' for complete action reference."
     );
   }
+  let session;
+  if (globalOptions.session) {
+    session = await loadSession(globalOptions.session);
+  } else {
+    session = await getDefaultSession();
+    if (!session) {
+      throw new Error('No session found. Run "bp connect" first.');
+    }
+  }
+  const isValid = await validateSession(session);
+  if (!isValid) {
+    await deleteSession(session.id);
+    throw new Error(
+      `Session "${session.id}" is no longer valid (browser may have closed).
+Session file has been cleaned up. Run "bp connect" to create a new session.`
+    );
+  }
   const browser = await connect({
     provider: session.provider,
     wsUrl: session.wsUrl,
@@ -3317,67 +3405,62 @@ function getAge(date) {
 
 // src/cli/commands/quickstart.ts
 var QUICKSTART = `
-browser-pilot - CDP-based browser automation for AI agents
-
-Zero production dependencies. Works in Node.js, Bun, and Cloudflare Workers.
-
-RUNNING
-  npx browser-pilot ...     # Node.js projects
-  bunx browser-pilot ...    # Bun projects (faster)
-
-CONNECTING
-  npx browser-pilot connect <wsUrl>     Connect to existing browser
-  npx browser-pilot connect --provider browserbase --api-key <key>
-
-BASIC USAGE (Code)
-  import { Browser } from 'browser-pilot';
-
-  const browser = await Browser.connect({ wsUrl: '...' });
-  const page = await browser.newPage();
-  await page.goto('https://example.com');
-  await page.click('#button');
-  await page.fill('#input', 'text');
-  await browser.close();
-
-KEY PATTERNS
-  Multi-Selector    await page.click(['#primary', '.fallback', 'button']);
-  Smart Waiting     Every action waits for visibility automatically
-  Optional Actions  await page.click('#banner', { optional: true });
-
-BATCH EXECUTION
-  await page.batch([
-    { action: 'goto', url: 'https://example.com' },
-    { action: 'fill', selector: '#email', value: 'test@test.com' },
-    { action: 'submit', selector: 'form' },
-  ]);
-
-SNAPSHOTS (FOR AI AGENTS)
-  const snapshot = await page.snapshot();
-  // Returns accessibility tree with refs: e1, e2, e3...
-  await page.click({ ref: 'e5' });
-
-PROVIDERS
-  BrowserBase     Browser.connect({ provider: 'browserbase', apiKey })
-  Browserless     Browser.connect({ provider: 'browserless', apiKey })
-  Generic         Browser.connect({ wsUrl: 'ws://...' })
+browser-pilot CLI - Quick Start Guide
+
+STEP 1: CONNECT TO A BROWSER
+  bp connect --provider generic --name mysite
+
+  This creates a session. The CLI remembers it for subsequent commands.
+
+STEP 2: NAVIGATE
+  bp exec '{"action":"goto","url":"https://example.com"}'
+
+STEP 3: GET PAGE SNAPSHOT
+  bp snapshot --format text
+
+  Output shows the page as an accessibility tree with element refs:
+    - heading "Welcome" [ref=e1]
+    - button "Sign In" [ref=e2]
+    - textbox "Email" [ref=e3]
+
+STEP 4: INTERACT USING REFS
+  bp exec '{"action":"fill","selector":"ref:e3","value":"test@example.com"}'
+  bp exec '{"action":"click","selector":"ref:e2"}'
+
+STEP 5: BATCH MULTIPLE ACTIONS
+  bp exec '[
+    {"action":"fill","selector":"ref:e3","value":"user@test.com"},
+    {"action":"click","selector":"ref:e2"},
+    {"action":"snapshot"}
+  ]'
+
+FOR AI AGENTS
+  Use -o json for machine-readable output:
+    bp snapshot --format text -o json
+    bp exec '{"action":"click","selector":"ref:e3"}' -o json
+
+TIPS
+  \u2022 Refs (e1, e2...) are stable within a page - prefer them over CSS selectors
+  \u2022 After navigation, take a new snapshot to get updated refs
+  \u2022 Use multi-selectors for resilience: ["ref:e3", "#email", "input[type=email]"]
+  \u2022 Add "optional":true to skip elements that may not exist
+
+SELECTOR PRIORITY
+  1. ref:e5         From snapshot - most reliable
+  2. #id            CSS ID selector
+  3. [data-testid]  Test attributes
+  4. .class         CSS class (less stable)
 
 COMMON ACTIONS
-  page.goto(url)              Navigate to URL
-  page.click(selector)        Click element
-  page.fill(selector, value)  Fill input field
-  page.submit(selector)       Submit form
-  page.select(selector, val)  Select dropdown option
-  page.screenshot()           Capture screenshot
-  page.snapshot()             Get accessibility tree
-
-AGENT INTEGRATION
-  - Use snapshot() to get page state as accessibility tree
-  - Refs (e1, e2...) identify elements without fragile selectors
-  - Multi-selector arrays handle UI variations
-  - optional: true prevents failures on transient elements
-
-Ready to automate!
-Run: npx browser-pilot connect <wsUrl>
+  goto        {"action":"goto","url":"https://..."}
+  click       {"action":"click","selector":"ref:e3"}
+  fill        {"action":"fill","selector":"ref:e3","value":"text"}
+  submit      {"action":"submit","selector":"form"}
+  select      {"action":"select","selector":"ref:e5","value":"option"}
+  snapshot    {"action":"snapshot"}
+  screenshot  {"action":"screenshot"}
+
+Run 'bp actions' for the complete action reference.
 `;
 async function quickstartCommand() {
   console.log(QUICKSTART);
@@ -3553,56 +3636,31 @@ Usage:
   bp <command> [options]
 
 Commands:
-  quickstart  Show getting started guide
-  connect     Create or resume browser session
-  exec        Execute actions on current session
-  snapshot    Get page accessibility snapshot (includes element refs)
-  text        Extract text content from page
+  quickstart  Getting started guide (start here!)
+  connect     Create browser session
+  exec        Execute actions
+  snapshot    Get page with element refs
+  text        Extract text content
   screenshot  Take screenshot
   close       Close session
-  list        List all sessions
-  actions     Show all available actions with examples
-
-Global Options:
-  -s, --session <id>    Session ID to use
-  -o, --output <fmt>    Output format: json | pretty (default: pretty)
-  --trace               Enable execution tracing
-  -h, --help            Show this help message
+  list        List sessions
+  clean       Clean up old sessions
+  actions     Complete action reference
 
-Exec Options:
-  --dialog <mode>       Auto-handle dialogs: accept | dismiss
-
-Ref Selectors (Recommended for AI Agents):
-  1. Navigate + snapshot: bp exec '[{"action":"goto","url":"..."},{"action":"snapshot"}]'
-     Output shows:        button "Submit" [ref=e4], textbox "Email" [ref=e5]
-  2. Use refs (snapshot cached for same session+URL):
-     bp exec '[{"action":"click","selector":"ref:e4"}]'
-
-  Refs are cached per session+URL after snapshot. Use new snapshot after navigation.
-  Combine with CSS fallbacks:
-    {"selector": ["ref:e4", "#submit", "button[type=submit]"]}
+Options:
+  -s, --session <id>    Session ID
+  -o, --output <fmt>    json | pretty (default: pretty)
+  --trace               Enable debug tracing
+  --dialog <mode>       Handle dialogs: accept | dismiss
+  -h, --help            Show help
 
 Examples:
-  # Connect to browser
   bp connect --provider generic --name dev
+  bp exec '{"action":"goto","url":"https://example.com"}'
+  bp snapshot --format text
+  bp exec '{"action":"click","selector":"ref:e3"}'
 
-  # Navigate and get snapshot with refs
-  bp exec '[{"action":"goto","url":"https://example.com"},{"action":"snapshot"}]'
-
-  # Use refs (snapshot cached for same session+URL)
-  bp exec '[{"action":"fill","selector":"ref:e5","value":"test@example.com"},{"action":"click","selector":"ref:e4"}]'
-
-  # Handle native dialogs (alert/confirm/prompt)
-  bp exec --dialog accept '{"action":"click","selector":"#delete-btn"}'
-
-  # Batch multiple actions (snapshot optional if already cached)
-  bp exec '[
-    {"action":"snapshot"},
-    {"action":"fill","selector":"ref:e5","value":"user@example.com"},
-    {"action":"click","selector":"ref:e4"},
-    {"action":"snapshot"}
-  ]'
-
+Run 'bp quickstart' for CLI workflow guide.
 Run 'bp actions' for complete action reference.
 `;
 function parseGlobalOptions(args) {
@@ -3633,7 +3691,10 @@ function output(data, format = "pretty") {
     if (typeof data === "string") {
       console.log(data);
     } else if (typeof data === "object" && data !== null) {
-      prettyPrint(data);
+      const { truncated } = prettyPrint(data);
+      if (truncated) {
+        console.log("\n(Output truncated. Use -o json for full data)");
+      }
     } else {
       console.log(data);
     }
@@ -3641,16 +3702,20 @@ function output(data, format = "pretty") {
 }
 function prettyPrint(obj, indent = 0) {
   const prefix = "  ".repeat(indent);
+  let truncated = false;
   for (const [key, value] of Object.entries(obj)) {
     if (typeof value === "object" && value !== null && !Array.isArray(value)) {
       console.log(`${prefix}${key}:`);
-      prettyPrint(value, indent + 1);
+      const result = prettyPrint(value, indent + 1);
+      if (result.truncated) truncated = true;
     } else if (Array.isArray(value)) {
       console.log(`${prefix}${key}: [${value.length} items]`);
+      truncated = true;
     } else {
       console.log(`${prefix}${key}: ${value}`);
     }
   }
+  return { truncated };
 }
 async function main() {
   const args = process.argv.slice(2);
@@ -3690,6 +3755,9 @@ async function main() {
       case "list":
         await listCommand(remaining, options);
         break;
+      case "clean":
+        await cleanCommand(remaining, options);
+        break;
       case "actions":
         await actionsCommand();
         break;

package/dist/cli.d.cts

@@ -15,6 +15,7 @@
  *   screenshot  Take screenshot
  *   close       Close session
  *   list        List sessions
+ *   clean       Clean up old sessions
  *   actions     Complete action reference
  *
  * Run 'bp quickstart' for getting started guide.

package/dist/cli.d.ts

@@ -15,6 +15,7 @@
  *   screenshot  Take screenshot
  *   close       Close session
  *   list        List sessions
+ *   clean       Clean up old sessions
  *   actions     Complete action reference
  *
  * Run 'bp quickstart' for getting started guide.