@cli4ai/chrome 1.0.9 → 1.1.0

package/README.md

@@ -2,7 +2,7 @@
 
 > Official @cli4ai package • https://cli4ai.com • Install cli4ai: `npm i -g cli4ai`
 
-Chrome profile automation via Puppeteer (connects to a running Chrome with remote debugging enabled).
+Chrome browser automation via Puppeteer. Launches a managed browser instance with persistent profile - no need to quit your existing browser or enable remote debugging.
 
 ## Setup
 
@@ -11,28 +11,97 @@ npm i -g cli4ai
 cli4ai add -g chrome
 ```
 
-1) Quit all running Chrome instances.
+## Usage
 
-2) Start Chrome with remote debugging enabled (port `9222`):
+```bash
+# Navigate to a URL (auto-launches browser if not running)
+cli4ai run chrome navigate https://example.com
+
+# Run in headless mode (no visible window)
+cli4ai run chrome --headless navigate https://example.com
 
-- macOS: `open -na "Google Chrome" --args --remote-debugging-port=9222`
-- Linux: `google-chrome --remote-debugging-port=9222`
+# Screenshot
+cli4ai run chrome screenshot output.png --full-page
 
-3) Connect:
+# Get page text
+cli4ai run chrome text
+```
+
+## Commands
+
+### Browser Management
 
 ```bash
-cli4ai run chrome connect        # default port 9222
-# or
-cli4ai run chrome connect 9222
+cli4ai run chrome launch              # Explicitly launch browser
+cli4ai run chrome --headless launch   # Launch in headless mode
+cli4ai run chrome close               # Close managed browser
+cli4ai run chrome status              # Check if browser is running
+cli4ai run chrome tabs                # List open tabs
 ```
 
-Other browser tools (e.g. `@cli4ai/twitter`, `@cli4ai/linkedin`) reuse this connection.
+### Navigation
 
-## Commands
+```bash
+cli4ai run chrome navigate <url>              # Open URL
+cli4ai run chrome navigate <url> --new-tab    # Open in new tab
+cli4ai run chrome navigate <url> --wait load  # Wait for: load, domcontentloaded, networkidle0, networkidle2
+```
+
+### Interaction
+
+```bash
+cli4ai run chrome click <selector>                    # Click element
+cli4ai run chrome type <selector> "text"              # Type into input
+cli4ai run chrome type <selector> "text" --clear      # Clear first, then type
+cli4ai run chrome wait <selector>                     # Wait for element
+cli4ai run chrome wait <selector> --timeout 5000      # With timeout (ms)
+```
+
+### Content Extraction
 
 ```bash
-cli4ai run chrome navigate <url> [--new-tab]
-cli4ai run chrome eval "<js>"
-cli4ai run chrome screenshot [file] [--full-page]
-cli4ai run chrome cookies [domain]
+cli4ai run chrome html                    # Get full page HTML
+cli4ai run chrome html <selector>         # Get element HTML
+cli4ai run chrome text                    # Get page text content
+cli4ai run chrome text <selector>         # Get element text
+cli4ai run chrome cookies                 # Get all cookies
+cli4ai run chrome cookies example.com     # Filter by domain
+cli4ai run chrome eval "document.title"   # Run JavaScript
 ```
+
+### Screenshots & PDF
+
+```bash
+cli4ai run chrome screenshot                      # Save screenshot.png
+cli4ai run chrome screenshot output.png           # Custom filename
+cli4ai run chrome screenshot --full-page          # Full page capture
+cli4ai run chrome screenshot --selector "#hero"   # Element screenshot
+cli4ai run chrome pdf                             # Save page.pdf (headless)
+cli4ai run chrome pdf output.pdf                  # Custom filename
+```
+
+## Headless Mode
+
+Add `--headless` before any command to run without a visible browser window:
+
+```bash
+cli4ai run chrome --headless navigate https://example.com
+cli4ai run chrome --headless screenshot
+cli4ai run chrome --headless text
+```
+
+Headless mode is useful for:
+- Automated scraping
+- CI/CD pipelines
+- Background tasks
+
+## Profile Persistence
+
+Browser data (cookies, localStorage, logins) persists in `~/.cli4ai/chrome/profile/`. This means:
+- You stay logged into websites between sessions
+- Browser extensions are preserved
+- History and settings persist
+
+## Related
+
+Other browser-dependent tools like `@cli4ai/twitter` and `@cli4ai/linkedin` can use the managed browser.

package/cli4ai.json

@@ -1,63 +1,95 @@
 {
   "name": "chrome",
-  "version": "1.0.9",
-  "description": "Chrome browser automation (foundation for browser tools)",
+  "version": "1.1.0",
+  "description": "Chrome browser automation with managed browser instance",
   "author": "cliforai",
-  "license": "MIT",
+  "license": "BUSL-1.1",
   "entry": "run.ts",
   "runtime": "node",
   "keywords": [
     "chrome",
     "browser",
     "puppeteer",
-    "automation"
+    "automation",
+    "headless"
   ],
   "commands": {
-    "connect": {
-      "description": "Connect to Chrome",
+    "launch": {
+      "description": "Launch managed browser",
+      "args": []
+    },
+    "close": {
+      "description": "Close managed browser",
+      "args": []
+    },
+    "status": {
+      "description": "Check browser status",
+      "args": []
+    },
+    "navigate": {
+      "description": "Open URL in browser",
       "args": [
-        {
-          "name": "port",
-          "description": "Default: 9222",
-          "required": false
-        }
+        { "name": "url", "required": true }
       ]
     },
-    "navigate": {
-      "description": "Open URL",
+    "click": {
+      "description": "Click an element",
       "args": [
-        {
-          "name": "url",
-          "required": true
-        }
+        { "name": "selector", "required": true }
+      ]
+    },
+    "type": {
+      "description": "Type text into an input",
+      "args": [
+        { "name": "selector", "required": true },
+        { "name": "text", "required": true }
       ]
     },
     "eval": {
-      "description": "Run JavaScript",
+      "description": "Run JavaScript in page context",
       "args": [
-        {
-          "name": "script",
-          "required": true
-        }
+        { "name": "script", "required": true }
       ]
     },
     "screenshot": {
-      "description": "Capture viewport",
+      "description": "Capture screenshot",
+      "args": [
+        { "name": "output", "required": false }
+      ]
+    },
+    "pdf": {
+      "description": "Save page as PDF",
       "args": [
-        {
-          "name": "output",
-          "required": false
-        }
+        { "name": "output", "required": false }
       ]
     },
     "cookies": {
       "description": "Get cookies",
       "args": [
-        {
-          "name": "domain",
-          "required": false
-        }
+        { "name": "domain", "required": false }
       ]
+    },
+    "html": {
+      "description": "Get page HTML",
+      "args": [
+        { "name": "selector", "required": false }
+      ]
+    },
+    "text": {
+      "description": "Get text content",
+      "args": [
+        { "name": "selector", "required": false }
+      ]
+    },
+    "wait": {
+      "description": "Wait for element",
+      "args": [
+        { "name": "selector", "required": true }
+      ]
+    },
+    "tabs": {
+      "description": "List open tabs",
+      "args": []
     }
   },
   "dependencies": {

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "@cli4ai/chrome",
-  "version": "1.0.9",
-  "description": "Chrome browser automation (foundation for browser tools)",
+  "version": "1.1.0",
+  "description": "Chrome browser automation with managed browser instance",
   "author": "cliforai",
-  "license": "MIT",
+  "license": "BUSL-1.1",
   "main": "run.ts",
   "bin": {
     "chrome": "./run.ts"
@@ -16,7 +16,8 @@
     "chrome",
     "browser",
     "puppeteer",
-    "automation"
+    "automation",
+    "headless"
   ],
   "repository": {
     "type": "git",

package/run.ts

@@ -1,93 +1,367 @@
 #!/usr/bin/env npx tsx
-import puppeteer from 'puppeteer';
-import { readFileSync, writeFileSync } from 'fs';
+import puppeteer, { Browser, Page } from 'puppeteer';
+import { readFileSync, writeFileSync, existsSync, unlinkSync, mkdirSync } from 'fs';
 import { join, resolve } from 'path';
+import { homedir } from 'os';
 import { cli, log, output, outputError, withErrorHandling } from '@cli4ai/lib/cli.ts';
 
-const WS_FILE = join(new URL('.', import.meta.url).pathname, '.ws-endpoint');
+// Persistent storage paths
+const CLI4AI_DIR = join(homedir(), '.cli4ai');
+const CHROME_DIR = join(CLI4AI_DIR, 'chrome');
+const PROFILE_DIR = join(CHROME_DIR, 'profile');
+const WS_FILE = join(CHROME_DIR, 'ws-endpoint');
+const PID_FILE = join(CHROME_DIR, 'pid');
 
-async function getPage(newTab = false) {
-  let ws: string;
+// Ensure directories exist
+function ensureDirs() {
+  if (!existsSync(CLI4AI_DIR)) mkdirSync(CLI4AI_DIR, { recursive: true });
+  if (!existsSync(CHROME_DIR)) mkdirSync(CHROME_DIR, { recursive: true });
+}
+
+// Check if browser process is still running
+function isBrowserRunning(): boolean {
+  if (!existsSync(PID_FILE)) return false;
+  const pid = parseInt(readFileSync(PID_FILE, 'utf-8').trim(), 10);
   try {
-    ws = readFileSync(WS_FILE, 'utf-8');
+    process.kill(pid, 0); // Check if process exists
+    return true;
   } catch {
-    outputError('NOT_FOUND', 'Not connected to Chrome', {
-      hint: 'Run: chrome connect'
-    });
+    // Process not running, clean up stale files
+    cleanup();
+    return false;
+  }
+}
+
+// Clean up state files
+function cleanup() {
+  if (existsSync(WS_FILE)) unlinkSync(WS_FILE);
+  if (existsSync(PID_FILE)) unlinkSync(PID_FILE);
+}
+
+// Launch a new browser instance
+async function launchBrowser(headless: boolean): Promise<Browser> {
+  ensureDirs();
+
+  const browser = await puppeteer.launch({
+    headless: headless ? 'shell' : false,
+    userDataDir: PROFILE_DIR,
+    args: [
+      '--no-first-run',
+      '--no-default-browser-check',
+      '--disable-infobars',
+    ],
+    defaultViewport: null, // Use full window size
+  });
+
+  // Save connection info
+  const wsEndpoint = browser.wsEndpoint();
+  writeFileSync(WS_FILE, wsEndpoint);
+
+  // Get browser process PID
+  const browserProcess = browser.process();
+  if (browserProcess?.pid) {
+    writeFileSync(PID_FILE, String(browserProcess.pid));
   }
 
-  const browser = await puppeteer.connect({ browserWSEndpoint: ws });
+  return browser;
+}
+
+// Get or create browser instance
+async function getBrowser(headless: boolean): Promise<Browser> {
+  // Try to connect to existing browser
+  if (isBrowserRunning() && existsSync(WS_FILE)) {
+    try {
+      const ws = readFileSync(WS_FILE, 'utf-8').trim();
+      return await puppeteer.connect({ browserWSEndpoint: ws });
+    } catch {
+      // Connection failed, clean up and launch new
+      cleanup();
+    }
+  }
+
+  // Launch new browser
+  return launchBrowser(headless);
+}
+
+// Get a page from the browser
+async function getPage(browser: Browser, newTab = false): Promise<Page> {
+  if (newTab) {
+    return browser.newPage();
+  }
   const pages = await browser.pages();
-  const page = newTab ? await browser.newPage() : (pages[pages.length - 1] || await browser.newPage());
-  return { page, browser };
+  return pages[pages.length - 1] || browser.newPage();
 }
 
-const program = cli('chrome', '1.0.0', 'Chrome browser automation');
+// Helper to run commands with browser
+async function withBrowser<T>(
+  fn: (browser: Browser, page: Page) => Promise<T>,
+  options: { headless?: boolean; newTab?: boolean } = {}
+): Promise<T> {
+  const browser = await getBrowser(options.headless ?? false);
+  const page = await getPage(browser, options.newTab);
+  try {
+    return await fn(browser, page);
+  } finally {
+    browser.disconnect(); // Disconnect but keep browser running
+  }
+}
+
+const program = cli('chrome', '1.0.9', 'Chrome browser automation');
+
+// Global headless option
+program.option('--headless', 'Run in headless mode');
 
 program
-  .command('connect [port]')
-  .description('Connect to Chrome (default: 9222)')
-  .action(withErrorHandling(async (port = '9222') => {
-    const browser = await puppeteer.connect({ browserURL: `http://127.0.0.1:${port}` });
-    const wsEndpoint = browser.wsEndpoint();
-    writeFileSync(WS_FILE, wsEndpoint);
-    log(`Connected on port ${port}`);
-    output({ connected: true, port, wsEndpoint });
+  .command('launch')
+  .description('Launch managed browser')
+  .action(withErrorHandling(async () => {
+    const headless = program.opts().headless ?? false;
+
+    if (isBrowserRunning()) {
+      log('Browser already running');
+      const ws = readFileSync(WS_FILE, 'utf-8').trim();
+      output({ running: true, wsEndpoint: ws, profileDir: PROFILE_DIR });
+      return;
+    }
+
+    const browser = await launchBrowser(headless);
+    log(`Browser launched ${headless ? '(headless)' : ''}`);
+    output({
+      launched: true,
+      headless,
+      wsEndpoint: browser.wsEndpoint(),
+      profileDir: PROFILE_DIR
+    });
     browser.disconnect();
   }));
 
+program
+  .command('close')
+  .description('Close managed browser')
+  .action(withErrorHandling(async () => {
+    if (!isBrowserRunning()) {
+      log('No browser running');
+      output({ closed: false, reason: 'not_running' });
+      return;
+    }
+
+    try {
+      const ws = readFileSync(WS_FILE, 'utf-8').trim();
+      const browser = await puppeteer.connect({ browserWSEndpoint: ws });
+      await browser.close();
+      cleanup();
+      log('Browser closed');
+      output({ closed: true });
+    } catch (err) {
+      cleanup();
+      output({ closed: true, note: 'force_cleaned' });
+    }
+  }));
+
+program
+  .command('status')
+  .description('Check browser status')
+  .action(withErrorHandling(async () => {
+    const running = isBrowserRunning();
+    output({
+      running,
+      profileDir: PROFILE_DIR,
+      wsEndpoint: running && existsSync(WS_FILE) ? readFileSync(WS_FILE, 'utf-8').trim() : null,
+    });
+  }));
+
 program
   .command('navigate <url>')
-  .description('Open URL')
+  .description('Open URL in browser')
   .option('--new-tab', 'Open in new tab')
-  .action(withErrorHandling(async (url: string, options: { newTab?: boolean }) => {
-    const { page, browser } = await getPage(options.newTab);
-    await page.goto(url, { waitUntil: 'networkidle2' });
-    output({ title: await page.title(), url: page.url() });
-    if (options.newTab) await page.close();
-    browser.disconnect();
+  .option('--wait <event>', 'Wait for: load, domcontentloaded, networkidle0, networkidle2', 'networkidle2')
+  .action(withErrorHandling(async (url: string, options: { newTab?: boolean; wait?: string }) => {
+    const headless = program.opts().headless ?? false;
+    const waitUntil = options.wait as 'load' | 'domcontentloaded' | 'networkidle0' | 'networkidle2';
+
+    await withBrowser(async (browser, page) => {
+      await page.goto(url, { waitUntil });
+      const title = await page.title();
+      log(`Navigated to: ${title}`);
+      output({ title, url: page.url() });
+    }, { headless, newTab: options.newTab });
+  }));
+
+program
+  .command('click <selector>')
+  .description('Click an element')
+  .action(withErrorHandling(async (selector: string) => {
+    const headless = program.opts().headless ?? false;
+
+    await withBrowser(async (browser, page) => {
+      await page.waitForSelector(selector, { timeout: 5000 });
+      await page.click(selector);
+      log(`Clicked: ${selector}`);
+      output({ clicked: true, selector });
+    }, { headless });
+  }));
+
+program
+  .command('type <selector> <text>')
+  .description('Type text into an input')
+  .option('--clear', 'Clear field first')
+  .action(withErrorHandling(async (selector: string, text: string, options: { clear?: boolean }) => {
+    const headless = program.opts().headless ?? false;
+
+    await withBrowser(async (browser, page) => {
+      await page.waitForSelector(selector, { timeout: 5000 });
+      if (options.clear) {
+        await page.click(selector, { clickCount: 3 });
+      }
+      await page.type(selector, text);
+      log(`Typed into: ${selector}`);
+      output({ typed: true, selector, length: text.length });
+    }, { headless });
   }));
 
 program
   .command('eval <script>')
-  .description('Run JavaScript (WARNING: executes arbitrary code in browser context)')
+  .description('Run JavaScript in page context')
   .action(withErrorHandling(async (script: string) => {
-    // SECURITY WARNING: This command executes arbitrary JavaScript in the browser.
-    // Only use with trusted input. Malicious scripts can access cookies, localStorage,
-    // and perform actions as the logged-in user.
-    log('⚠️  WARNING: Executing arbitrary JavaScript in browser context');
-    const { page, browser } = await getPage();
-    const result = await page.evaluate((code: string) => eval(code), script);
-    if (result !== undefined) output(result);
-    browser.disconnect();
+    const headless = program.opts().headless ?? false;
+    log('Executing JavaScript in browser context');
+
+    await withBrowser(async (browser, page) => {
+      const result = await page.evaluate((code: string) => {
+        return eval(code);
+      }, script);
+      if (result !== undefined) output(result);
+    }, { headless });
   }));
 
 program
   .command('screenshot [output]')
-  .description('Capture viewport')
+  .description('Capture screenshot')
   .option('--full-page', 'Capture full page')
-  .action(withErrorHandling(async (outputFile = 'screenshot.png', options: { fullPage?: boolean }) => {
-    const { page, browser } = await getPage();
+  .option('--selector <sel>', 'Screenshot specific element')
+  .action(withErrorHandling(async (outputFile = 'screenshot.png', options: { fullPage?: boolean; selector?: string }) => {
+    const headless = program.opts().headless ?? false;
     const outputPath = resolve(outputFile);
-    await page.screenshot({ path: outputPath, fullPage: options.fullPage });
-    log(`Saved: ${outputPath}`);
-    output({ path: outputPath });
-    browser.disconnect();
+
+    await withBrowser(async (browser, page) => {
+      if (options.selector) {
+        const element = await page.$(options.selector);
+        if (!element) {
+          outputError('NOT_FOUND', `Element not found: ${options.selector}`);
+        }
+        await element!.screenshot({ path: outputPath });
+      } else {
+        await page.screenshot({ path: outputPath, fullPage: options.fullPage });
+      }
+      log(`Saved: ${outputPath}`);
+      output({ path: outputPath });
+    }, { headless });
+  }));
+
+program
+  .command('pdf [output]')
+  .description('Save page as PDF (headless only)')
+  .action(withErrorHandling(async (outputFile = 'page.pdf') => {
+    const outputPath = resolve(outputFile);
+
+    // PDF requires headless mode
+    await withBrowser(async (browser, page) => {
+      await page.pdf({ path: outputPath, format: 'A4' });
+      log(`Saved: ${outputPath}`);
+      output({ path: outputPath });
+    }, { headless: true });
   }));
 
 program
   .command('cookies [domain]')
   .description('Get cookies')
   .action(withErrorHandling(async (domain?: string) => {
-    const { page, browser } = await getPage();
-    const client = await page.createCDPSession();
-    const { cookies } = await client.send('Network.getAllCookies');
-    const filtered = domain && domain !== '--all'
-      ? cookies.filter((c: { domain: string }) => c.domain.includes(domain))
-      : cookies;
-    output(filtered);
-    log(`\n${filtered.length} cookies`);
-    browser.disconnect();
+    const headless = program.opts().headless ?? false;
+
+    await withBrowser(async (browser, page) => {
+      const client = await page.createCDPSession();
+      const { cookies } = await client.send('Network.getAllCookies');
+      const filtered = domain
+        ? cookies.filter((c: { domain: string }) => c.domain.includes(domain))
+        : cookies;
+      output(filtered);
+      log(`${filtered.length} cookies`);
+    }, { headless });
+  }));
+
+program
+  .command('html [selector]')
+  .description('Get page HTML or element HTML')
+  .action(withErrorHandling(async (selector?: string) => {
+    const headless = program.opts().headless ?? false;
+
+    await withBrowser(async (browser, page) => {
+      let html: string;
+      if (selector) {
+        const element = await page.$(selector);
+        if (!element) {
+          outputError('NOT_FOUND', `Element not found: ${selector}`);
+        }
+        html = await page.evaluate(el => el!.outerHTML, element);
+      } else {
+        html = await page.content();
+      }
+      output({ html, length: html.length });
+    }, { headless });
+  }));
+
+program
+  .command('text [selector]')
+  .description('Get text content')
+  .action(withErrorHandling(async (selector?: string) => {
+    const headless = program.opts().headless ?? false;
+
+    await withBrowser(async (browser, page) => {
+      let text: string;
+      if (selector) {
+        const element = await page.$(selector);
+        if (!element) {
+          outputError('NOT_FOUND', `Element not found: ${selector}`);
+        }
+        text = await page.evaluate(el => el!.textContent || '', element);
+      } else {
+        text = await page.evaluate(() => document.body.innerText);
+      }
+      output({ text: text.trim(), length: text.trim().length });
+    }, { headless });
+  }));
+
+program
+  .command('wait <selector>')
+  .description('Wait for element to appear')
+  .option('--timeout <ms>', 'Timeout in milliseconds', '30000')
+  .action(withErrorHandling(async (selector: string, options: { timeout: string }) => {
+    const headless = program.opts().headless ?? false;
+    const timeout = parseInt(options.timeout, 10);
+
+    await withBrowser(async (browser, page) => {
+      await page.waitForSelector(selector, { timeout });
+      log(`Found: ${selector}`);
+      output({ found: true, selector });
+    }, { headless });
+  }));
+
+program
+  .command('tabs')
+  .description('List open tabs')
+  .action(withErrorHandling(async () => {
+    const headless = program.opts().headless ?? false;
+
+    await withBrowser(async (browser, page) => {
+      const pages = await browser.pages();
+      const tabs = await Promise.all(pages.map(async (p, i) => ({
+        index: i,
+        url: p.url(),
+        title: await p.title(),
+      })));
+      output(tabs);
+      log(`${tabs.length} tabs`);
+    }, { headless });
   }));
 
 program.parse();