aidevops 2.52.1 → 2.53.2

package/.agent/tools/browser/browser-automation.md

@@ -1,400 +0,0 @@
----
-description: Browser automation tool selection and usage guide
-mode: subagent
-tools:
-  read: true
-  write: false
-  edit: false
-  bash: true
-  glob: true
-  grep: true
-  webfetch: true
-  task: true
----
-
-# Browser Automation - Tool Selection Guide
-
-<!-- AI-CONTEXT-START -->
-
-## Default Tool: Agent-Browser
-
-**ALWAYS use agent-browser first** for any browser automation task. It's CLI-first, AI-optimized, and requires no server setup.
-
-```bash
-# Setup (one-time)
-~/.aidevops/agents/scripts/agent-browser-helper.sh setup
-
-# Basic workflow
-agent-browser open example.com
-agent-browser snapshot -i              # Get interactive elements with refs
-agent-browser click @e2                # Click by ref
-agent-browser close
-```
-
-**Why agent-browser is default**:
-- **Zero setup**: No daemon to start, just run commands
-- **AI-optimized**: Snapshot + ref pattern for deterministic element targeting
-- **Multi-session**: Isolated browser instances with `--session`
-- **Visual debugging**: Screenshots and DevTools for self-diagnosis
-
-## Visual Debugging (Don't Ask User - Check Yourself)
-
-**CRITICAL**: Before asking the user what they see, use these tools to check yourself:
-
-```bash
-# Take screenshot to see current state
-agent-browser screenshot /tmp/current-state.png
-
-# Get page info
-agent-browser get title
-agent-browser get url
-
-# Check for errors
-agent-browser errors
-
-# View console messages
-agent-browser console
-
-# Get element state
-agent-browser is visible @e5
-agent-browser is enabled @e5
-
-# Headed mode for complex debugging
-agent-browser open example.com --headed
-```
-
-**Self-diagnosis workflow**:
-1. Action fails or unexpected result
-2. Take screenshot: `agent-browser screenshot /tmp/debug.png`
-3. Check errors: `agent-browser errors`
-4. Get snapshot: `agent-browser snapshot -i`
-5. Analyze and retry - only ask user if truly stuck
-
-## Tool Selection Decision Tree
-
-```text
-Need browser automation?
-    │
-    ├─► Default choice ──► agent-browser (CLI-first, AI-optimized)
-    │
-    ├─► Need TypeScript API / stateful pages? ──► dev-browser
-    │
-    ├─► Need existing browser session/cookies? ──► Playwriter
-    │
-    ├─► Need natural language control? ──► Stagehand
-    │
-    └─► Need web crawling/extraction? ──► Crawl4AI
-```
-
-## Quick Reference
-
-| Tool | Best For | Setup |
-|------|----------|-------|
-| **agent-browser** (DEFAULT) | CLI automation, AI agents, CI/CD, multi-session | `agent-browser-helper.sh setup` |
-| **dev-browser** | TypeScript API, stateful pages, dev testing | `dev-browser-helper.sh setup` |
-| **playwriter** | Existing sessions, bypass detection | Chrome extension + MCP |
-| **stagehand** | Natural language automation | `stagehand-helper.sh setup` |
-| **crawl4ai** | Web scraping, content extraction | `crawl4ai-helper.sh setup` |
-| **playwright** | Cross-browser testing | MCP integration |
-
-**Full docs**: `tools/browser/agent-browser.md` (default), `tools/browser/dev-browser.md`, `tools/browser/playwriter.md`, etc.
-
-**Ethical Rules**: Respect ToS, rate limit (2-5s delays), no spam, legitimate use only
-<!-- AI-CONTEXT-END -->
-
-## Session Persistence (Cookies, Storage, Auth State)
-
-### Why Persist Sessions?
-
-- **Avoid repeated logins**: Save auth state once, reuse across sessions
-- **Maintain context**: Keep shopping carts, preferences, form data
-- **Faster automation**: Skip login flows in subsequent runs
-
-### Saving Auth State
-
-After logging in, save the complete browser state:
-
-```bash
-# Login to a site
-agent-browser open https://app.example.com/login
-agent-browser snapshot -i
-agent-browser fill @e3 "user@example.com"
-agent-browser fill @e4 "password"
-agent-browser click @e5
-agent-browser wait --url "**/dashboard"
-
-# Save auth state (cookies + localStorage + sessionStorage)
-agent-browser state save ~/.aidevops/.agent-workspace/auth/example-com.json
-agent-browser close
-```
-
-### Loading Auth State
-
-Restore saved state in new sessions:
-
-```bash
-# Start new session with saved auth
-agent-browser open https://app.example.com
-agent-browser state load ~/.aidevops/.agent-workspace/auth/example-com.json
-agent-browser reload  # Apply loaded state
-# Now logged in without re-entering credentials
-```
-
-### Cookie Management
-
-```bash
-# View all cookies
-agent-browser cookies
-
-# Set a specific cookie
-agent-browser cookies set "session_id" "abc123"
-
-# Set cookie with options
-agent-browser cookies set "auth_token" "xyz789" --domain ".example.com" --path "/" --secure
-
-# Clear all cookies
-agent-browser cookies clear
-```
-
-### LocalStorage & SessionStorage
-
-```bash
-# View all localStorage
-agent-browser storage local
-
-# Get specific key
-agent-browser storage local "user_preferences"
-
-# Set value
-agent-browser storage local set "theme" "dark"
-agent-browser storage local set "api_token" "bearer_xyz123"
-
-# Clear localStorage
-agent-browser storage local clear
-
-# Same commands work for sessionStorage
-agent-browser storage session
-agent-browser storage session set "temp_data" "value"
-agent-browser storage session clear
-```
-
-### Multi-Session with Shared Auth
-
-```bash
-# Session 1: Login and save state
-agent-browser --session login open https://app.example.com/login
-# ... perform login ...
-agent-browser --session login state save ~/.aidevops/.agent-workspace/auth/app.json
-agent-browser --session login close
-
-# Session 2: Use saved auth for task A
-agent-browser --session taskA open https://app.example.com
-agent-browser --session taskA state load ~/.aidevops/.agent-workspace/auth/app.json
-agent-browser --session taskA reload
-# ... perform task A ...
-
-# Session 3: Use same auth for task B (parallel)
-agent-browser --session taskB open https://app.example.com
-agent-browser --session taskB state load ~/.aidevops/.agent-workspace/auth/app.json
-agent-browser --session taskB reload
-# ... perform task B ...
-```
-
-### Auth State Best Practices
-
-| Practice | Why |
-|----------|-----|
-| Store in `~/.aidevops/.agent-workspace/auth/` | Gitignored, secure location |
-| Name by domain | `github-com.json`, `app-example-com.json` |
-| Refresh periodically | Sessions expire, re-login and re-save |
-| Don't commit auth files | Contains sensitive tokens |
-| Use `--session` for isolation | Prevent cross-contamination |
-
-### Injecting Cookies/Tokens Programmatically
-
-For CI/CD or scripts where you have tokens from environment:
-
-```bash
-# Set auth cookie from environment variable
-agent-browser open https://api.example.com
-agent-browser cookies set "auth_token" "$AUTH_TOKEN" --domain ".example.com" --secure --httponly
-agent-browser reload
-
-# Or inject into localStorage
-agent-browser storage local set "access_token" "$ACCESS_TOKEN"
-agent-browser storage local set "refresh_token" "$REFRESH_TOKEN"
-agent-browser reload
-```
-
-## Agent-Browser Usage (Default)
-
-### Quick Start
-
-```bash
-# 1. Setup (one-time)
-~/.aidevops/agents/scripts/agent-browser-helper.sh setup
-
-# 2. Basic workflow
-agent-browser open https://example.com
-agent-browser snapshot -i                 # Interactive elements only
-agent-browser click @e1                   # Click by ref
-agent-browser screenshot page.png
-agent-browser close
-```
-
-### Snapshot + Ref Pattern (AI-Optimized)
-
-This is the **recommended workflow for AI agents**:
-
-```bash
-# 1. Navigate and get snapshot
-agent-browser open https://news.ycombinator.com
-agent-browser snapshot -i --json
-
-# Output includes refs:
-# - link "Hacker News" [ref=e2]
-# - link "new" [ref=e3]
-# - textbox [ref=e224]
-
-# 2. Use refs for deterministic interaction
-agent-browser click @e3                   # Click "new" link
-agent-browser fill @e224 "search term"    # Fill search box
-
-# 3. Get new snapshot after page change
-agent-browser snapshot -i
-```
-
-### Common Patterns
-
-**Form submission**:
-
-```bash
-agent-browser open https://example.com/contact
-agent-browser snapshot -i
-agent-browser fill @e1 "John Doe"
-agent-browser fill @e2 "john@example.com"
-agent-browser fill @e3 "Hello, this is my message"
-agent-browser click @e4  # Submit button
-agent-browser wait --text "Thank you"
-agent-browser screenshot /tmp/success.png
-```
-
-**Multi-page workflow**:
-
-```bash
-agent-browser open https://shop.example.com
-agent-browser snapshot -i
-agent-browser click @e5  # Product link
-agent-browser wait --load networkidle
-agent-browser snapshot -i
-agent-browser click @e3  # Add to cart
-agent-browser click @e8  # Checkout
-agent-browser state save ~/.aidevops/.agent-workspace/auth/shop-cart.json
-```
-
-**Full documentation**: `tools/browser/agent-browser.md`
-
-## Alternative Tools
-
-Use these when agent-browser doesn't fit the use case:
-
-### Dev-Browser - TypeScript API
-
-**Stateful browser automation with persistent Playwright server**
-
-```bash
-# Setup and start
-bash ~/.aidevops/agents/scripts/dev-browser-helper.sh setup
-bash ~/.aidevops/agents/scripts/dev-browser-helper.sh start
-
-# Use TypeScript API
-cd ~/.aidevops/dev-browser/skills/dev-browser && bun x tsx <<'EOF'
-import { connect, waitForPageLoad } from "@/client.js";
-const client = await connect("http://localhost:9222");
-const page = await client.page("main");
-await page.goto("http://localhost:3000");
-await waitForPageLoad(page);
-console.log({ title: await page.title(), url: page.url() });
-await client.disconnect();
-EOF
-```
-
-**When to use**: TypeScript projects, stateful page interactions, dev testing with hot reload.
-
-See `tools/browser/dev-browser.md` for full documentation.
-
-### Playwriter - Chrome Extension MCP
-
-**Browser automation via Chrome extension with full Playwright API**
-
-```bash
-# 1. Install Chrome extension
-# https://chromewebstore.google.com/detail/playwriter-mcp/jfeammnjpkecdekppnclgkkffahnhfhe
-
-# 2. Add to MCP config (OpenCode)
-# "playwriter": { "type": "local", "command": ["npx", "playwriter@latest"] }
-
-# 3. Click extension icon on tabs to control (turns green)
-```
-
-**When to use**: Reuse existing browser sessions, bypass automation detection, work alongside AI with your extensions.
-
-See `tools/browser/playwriter.md` for full documentation.
-
-### Stagehand - Natural Language Automation
-
-**AI-powered browser automation with natural language control**
-
-```bash
-# Setup
-bash ~/.aidevops/agents/scripts/stagehand-helper.sh setup
-
-# Natural language actions
-await stagehand.act("click the login button")
-await stagehand.act("fill in the email field with user@example.com")
-
-# Structured extraction
-const data = await stagehand.extract("get product prices", z.array(z.number()))
-```
-
-**When to use**: Natural language control, self-healing automation, unknown page structures.
-
-See `tools/browser/stagehand.md` for full documentation.
-
-### Crawl4AI - Web Scraping
-
-**AI-powered web crawling and content extraction**
-
-```bash
-# Setup
-bash ~/.aidevops/agents/scripts/crawl4ai-helper.sh setup
-
-# Crawl and extract
-crawl4ai https://example.com --extract "main content"
-```
-
-**When to use**: Web scraping, content extraction, bulk data collection.
-
-See `tools/browser/crawl4ai.md` for full documentation.
-
-## Debugging Checklist
-
-When automation fails, check in this order:
-
-1. **Screenshot**: `agent-browser screenshot /tmp/debug.png`
-2. **Errors**: `agent-browser errors`
-3. **Console**: `agent-browser console`
-4. **URL**: `agent-browser get url` (redirected?)
-5. **Snapshot**: `agent-browser snapshot -i` (elements changed?)
-6. **Visibility**: `agent-browser is visible @eX`
-7. **Headed mode**: `agent-browser open url --headed` (watch it happen)
-
-**Only ask the user after exhausting these self-diagnosis steps.**
-
-## Ethical Guidelines
-
-- **Respect ToS**: Check site terms before automating
-- **Rate limit**: 2-5 second delays between actions
-- **No spam**: Don't automate mass messaging or fake engagement
-- **Legitimate use**: Focus on genuine value, not manipulation
-- **Privacy**: Don't scrape personal data without consent

package/.agent/tools/browser/chrome-devtools.md

@@ -1,282 +0,0 @@
----
-description: Chrome DevTools MCP for debugging and inspection
-mode: subagent
-tools:
-  read: true
-  write: false
-  edit: false
-  bash: true
-  glob: true
-  grep: true
-  webfetch: true
-  task: true
----
-
-# Chrome DevTools MCP Usage Examples
-
-<!-- AI-CONTEXT-START -->
-
-## Quick Reference
-
-- Chrome DevTools examples for browser debugging and analysis
-- Performance: `lighthouse()`, `measureWebVitals()` (LCP, FID, CLS, TTFB)
-- Scraping: `extractData()`, `screenshot()` (fullPage, element)
-- Debug: `captureConsole()`, `monitorNetwork()` (xhr, fetch, document)
-- Throttling: `throttleRequest()`, `throttleRequests()` (individual request throttling - Chrome 136+)
-- Mobile: `emulateDevice()`, `simulateTouch()` (tap, swipe)
-- SEO: `extractSEO()`, `validateStructuredData()`
-- Visual: `visualRegression()`, `analyzeCSSCoverage()`
-- Automation: `comprehensiveAnalysis()`, `comparePages()` (A/B testing)
-- Devices: iPhone 12 Pro, custom viewports
-- Metrics: domContentLoaded, load, FCP, LCP
-<!-- AI-CONTEXT-END -->
-
-## Performance Analysis
-
-### **Lighthouse Performance Audit**
-
-```javascript
-// Request a Lighthouse audit for performance optimization
-await chromeDevTools.lighthouse({
-  url: "https://your-website.com",
-  categories: ["performance", "accessibility", "best-practices", "seo"],
-  device: "desktop"
-});
-```
-
-### **Core Web Vitals Monitoring**
-
-```javascript
-// Monitor Core Web Vitals in real-time
-await chromeDevTools.measureWebVitals({
-  url: "https://your-website.com",
-  metrics: ["LCP", "FID", "CLS", "TTFB"],
-  iterations: 5
-});
-```
-
-## 🕷️ **Web Scraping & Data Extraction**
-
-### **Extract Page Content**
-
-```javascript
-// Extract structured data from a webpage
-await chromeDevTools.extractData({
-  url: "https://example.com",
-  selectors: {
-    title: "h1",
-    description: ".description",
-    links: "a[href]"
-  }
-});
-```
-
-### **Screenshot Generation**
-
-```javascript
-// Generate full-page screenshots
-await chromeDevTools.screenshot({
-  url: "https://your-website.com",
-  fullPage: true,
-  format: "png",
-  quality: 90
-});
-```
-
-## 🐛 **Debugging & Testing**
-
-### **Console Log Analysis**
-
-```javascript
-// Capture and analyze console errors
-await chromeDevTools.captureConsole({
-  url: "https://your-website.com",
-  logLevel: "error",
-  duration: 30000
-});
-```
-
-### **Network Request Monitoring**
-
-```javascript
-// Monitor network requests and responses
-await chromeDevTools.monitorNetwork({
-  url: "https://your-website.com",
-  filters: ["xhr", "fetch", "document"],
-  captureHeaders: true,
-  captureBody: true
-});
-```
-
-## **Network Conditions & Throttling**
-
-### **Individual Request Throttling** (New in Chrome 136+)
-
-Chrome DevTools now supports throttling individual network requests rather than the entire page. This enables precise testing of how your application handles slow-loading specific resources.
-
-**Use cases:**
-- Test lazy-loading behavior when specific images load slowly
-- Simulate slow API responses without affecting other requests
-- Debug race conditions when certain scripts load out of order
-- Test error handling for slow third-party resources
-
-```javascript
-// Throttle a specific API endpoint
-await chromeDevTools.throttleRequest({
-  url: "https://your-website.com",
-  requestPattern: "**/api/slow-endpoint",
-  latency: 3000,  // Add 3 second delay
-  downloadThroughput: 50 * 1024  // 50 KB/s
-});
-
-// Throttle specific image requests
-await chromeDevTools.throttleRequest({
-  url: "https://your-website.com",
-  requestPattern: "*.jpg",
-  latency: 2000,
-  downloadThroughput: 100 * 1024  // 100 KB/s
-});
-
-// Throttle multiple patterns with different conditions
-await chromeDevTools.throttleRequests({
-  url: "https://your-website.com",
-  rules: [
-    {
-      pattern: "**/api/critical",
-      latency: 0,
-      downloadThroughput: -1  // No throttling (priority)
-    },
-    {
-      pattern: "**/api/*",
-      latency: 1500,
-      downloadThroughput: 200 * 1024
-    },
-    {
-      pattern: "*.woff2",
-      latency: 500,
-      downloadThroughput: 50 * 1024
-    }
-  ]
-});
-```
-
-**Manual DevTools usage:**
-1. Open DevTools (F12) → Network panel
-2. Right-click any request → "Throttle request"
-3. Choose preset (Slow 3G, Fast 3G) or custom values
-4. Request-specific throttling persists until cleared
-
-**Comparison with page-level throttling:**
-
-| Feature | Page-Level | Individual Request |
-|---------|------------|-------------------|
-| Scope | All requests | Specific URL patterns |
-| Use case | General slow network testing | Targeted resource testing |
-| Precision | Low | High |
-| Real-world simulation | Broad conditions | Specific failure scenarios |
-
-## 📱 **Mobile Testing**
-
-### **Device Emulation**
-
-```javascript
-// Test mobile responsiveness
-await chromeDevTools.emulateDevice({
-  url: "https://your-website.com",
-  device: "iPhone 12 Pro",
-  orientation: "portrait"
-});
-```
-
-### **Touch Event Testing**
-
-```javascript
-// Simulate touch interactions
-await chromeDevTools.simulateTouch({
-  url: "https://your-website.com",
-  actions: [
-    { type: "tap", x: 100, y: 200 },
-    { type: "swipe", startX: 100, startY: 300, endX: 300, endY: 300 }
-  ]
-});
-```
-
-## 🔍 **SEO Analysis**
-
-### **Meta Tag Extraction**
-
-```javascript
-// Extract SEO-relevant meta tags
-await chromeDevTools.extractSEO({
-  url: "https://your-website.com",
-  elements: ["title", "meta[name='description']", "meta[property^='og:']", "link[rel='canonical']"]
-});
-```
-
-### **Structured Data Validation**
-
-```javascript
-// Validate structured data markup
-await chromeDevTools.validateStructuredData({
-  url: "https://your-website.com",
-  schemas: ["Organization", "WebSite", "Article"]
-});
-```
-
-## 🚀 **Automation Workflows**
-
-### **Multi-Page Analysis**
-
-```javascript
-// Analyze multiple pages in sequence
-const urls = [
-  "https://your-website.com",
-  "https://your-website.com/about",
-  "https://your-website.com/contact"
-];
-
-for (const url of urls) {
-  await chromeDevTools.comprehensiveAnalysis({
-    url: url,
-    includePerformance: true,
-    includeSEO: true,
-    includeAccessibility: true
-  });
-}
-```
-
-### **A/B Testing Support**
-
-```javascript
-// Compare two versions of a page
-await chromeDevTools.comparePages({
-  urlA: "https://your-website.com/version-a",
-  urlB: "https://your-website.com/version-b",
-  metrics: ["performance", "visual-diff", "accessibility"]
-});
-```
-
-## 🎨 **Visual Testing**
-
-### **Visual Regression Testing**
-
-```javascript
-// Capture baseline and compare screenshots
-await chromeDevTools.visualRegression({
-  url: "https://your-website.com",
-  baseline: "/path/to/baseline.png",
-  threshold: 0.1,
-  highlightDifferences: true
-});
-```
-
-### **CSS Coverage Analysis**
-
-```javascript
-// Analyze unused CSS
-await chromeDevTools.analyzeCSSCoverage({
-  url: "https://your-website.com",
-  reportUnused: true,
-  minifyRecommendations: true
-});
-```