aidevops 2.52.1 → 2.53.2

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

@@ -1,341 +0,0 @@
----
-description: Stateful browser automation with persistent Playwright server
-mode: subagent
-tools:
-  read: true
-  write: false
-  edit: false
-  bash: true
-  glob: true
-  grep: true
-  webfetch: true
-  task: true
----
-
-# Dev-Browser - Stateful Browser Automation
-
-<!-- AI-CONTEXT-START -->
-
-## Quick Reference
-
-- **Purpose**: Stateful browser automation with persistent page state AND browser profile
-- **Runtime**: Bun + Playwright (pages survive script executions)
-- **Server**: `~/.aidevops/dev-browser/server.sh` (port 9222)
-- **Profile**: `~/.aidevops/dev-browser/skills/dev-browser/profiles/browser-data/`
-- **Scripts**: Execute via `bun x tsx` inline scripts
-- **Install**: `bash ~/.aidevops/agents/scripts/dev-browser-helper.sh setup`
-
-**Key Advantages**:
-- **14% faster, 39% cheaper** than Playwright MCP (fewer round-trips)
-- **Persistent profile**: Cookies, localStorage, extensions survive server restarts
-- **Stateful pages**: Pages persist across script executions within a session
-- **Codebase-aware**: Read source code to write selectors directly
-- **LLM-friendly**: ARIA snapshots for element discovery
-
-**Profile Persistence** (survives server restarts):
-- Cookies (stay logged into sites)
-- localStorage and sessionStorage
-- Browser cache
-- Extension data (install extensions manually in the browser window)
-
-**When to Use**:
-- Testing local dev servers (localhost:3000, etc.)
-- Multi-step workflows (login -> navigate -> action)
-- Iterative debugging with visual feedback
-- When you need to stay logged into sites across sessions
-- When you have source code access for selectors
-
-**When NOT to Use**:
-- Need to use YOUR existing Chrome profile -> use Playwriter
-- Natural language automation -> use Stagehand
-
-<!-- AI-CONTEXT-END -->
-
-## Setup
-
-```bash
-# Complete setup (installs Bun if needed, clones repo, installs deps)
-bash ~/.aidevops/agents/scripts/dev-browser-helper.sh setup
-
-# Start server (reuses existing browser profile - stays logged in!)
-bash ~/.aidevops/agents/scripts/dev-browser-helper.sh start
-
-# Start with fresh profile (no cookies, clean slate)
-bash ~/.aidevops/agents/scripts/dev-browser-helper.sh start-clean
-
-# Check status (shows profile info)
-bash ~/.aidevops/agents/scripts/dev-browser-helper.sh status
-
-# View profile details
-bash ~/.aidevops/agents/scripts/dev-browser-helper.sh profile
-
-# Reset profile (delete all browser data)
-bash ~/.aidevops/agents/scripts/dev-browser-helper.sh reset-profile
-
-# Stop server
-bash ~/.aidevops/agents/scripts/dev-browser-helper.sh stop
-```
-
-## Usage Pattern
-
-### 1. Start Server First
-
-The server must be running before executing scripts:
-
-```bash
-bash ~/.aidevops/agents/scripts/dev-browser-helper.sh start
-# Or for headless mode:
-bash ~/.aidevops/agents/scripts/dev-browser-helper.sh start-headless
-```
-
-### 2. Execute Scripts Inline
-
-Scripts are executed via `bun x tsx` with heredoc:
-
-```bash
-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
-```
-
-### 3. Key Principles
-
-1. **Small scripts**: Each script does ONE thing
-2. **Evaluate state**: Always log state at the end
-3. **Use page names**: `"main"`, `"checkout"`, `"login"` - pages persist by name
-4. **Disconnect to exit**: `await client.disconnect()` at the end
-5. **Plain JS in evaluate**: No TypeScript inside `page.evaluate()`
-
-## Element Discovery
-
-### ARIA Snapshot (Unknown Pages)
-
-When you don't know the page structure, get an ARIA snapshot:
-
-```bash
-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("https://example.com");
-await waitForPageLoad(page);
-
-const snapshot = await client.getAISnapshot("main");
-console.log(snapshot);
-
-await client.disconnect();
-EOF
-```
-
-The snapshot returns elements with refs like `e1`, `e2`, etc.
-
-### Interact with Refs
-
-Use refs from the snapshot to interact:
-
-```bash
-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");
-
-// Click element by ref from snapshot
-const element = await client.selectSnapshotRef("main", "e5");
-await element.click();
-await waitForPageLoad(page);
-
-await client.disconnect();
-EOF
-```
-
-### Use Source Code Selectors
-
-When you have access to the source code, use selectors directly:
-
-```bash
-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");
-
-// Use selectors from source code
-await page.click('[data-testid="submit-button"]');
-await page.fill('input[name="email"]', 'test@example.com');
-
-await client.disconnect();
-EOF
-```
-
-## Common Operations
-
-### Navigate and Screenshot
-
-```bash
-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/dashboard");
-await waitForPageLoad(page);
-
-await page.screenshot({ path: "tmp/dashboard.png" });
-await page.screenshot({ path: "tmp/full.png", fullPage: true });
-
-console.log("Screenshots saved to tmp/");
-await client.disconnect();
-EOF
-```
-
-### Fill Form and Submit
-
-```bash
-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.fill('input[name="username"]', 'testuser');
-await page.fill('input[name="password"]', 'testpass');
-await page.click('button[type="submit"]');
-
-await waitForPageLoad(page);
-console.log({ url: page.url(), title: await page.title() });
-
-await client.disconnect();
-EOF
-```
-
-### Extract Data
-
-```bash
-cd ~/.aidevops/dev-browser/skills/dev-browser && bun x tsx <<'EOF'
-import { connect } from "@/client.js";
-
-const client = await connect("http://localhost:9222");
-const page = await client.page("main");
-
-// Extract text content
-const heading = await page.textContent('h1');
-const items = await page.$$eval('.item', els => els.map(e => e.textContent));
-
-console.log({ heading, items });
-await client.disconnect();
-EOF
-```
-
-### Multi-Page Workflow
-
-Pages persist by name, enabling multi-step workflows:
-
-```bash
-# Step 1: Login
-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("app");  // Named "app"
-
-await page.goto("http://localhost:3000/login");
-await page.fill('input[name="email"]', 'user@example.com');
-await page.fill('input[name="password"]', 'password');
-await page.click('button[type="submit"]');
-await waitForPageLoad(page);
-
-console.log("Logged in:", page.url());
-await client.disconnect();
-EOF
-
-# Step 2: Navigate (same page persists!)
-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("app");  // Same "app" page, still logged in!
-
-await page.goto("http://localhost:3000/settings");
-await waitForPageLoad(page);
-
-console.log("Settings page:", await page.title());
-await client.disconnect();
-EOF
-```
-
-## Comparison with Other Browser Tools
-
-| Feature | Dev-Browser | Playwriter | Playwright MCP | Stagehand |
-|---------|-------------|------------|----------------|-----------|
-| **State** | Persistent | Per-tab | Fresh each call | Fresh |
-| **Speed** | Fast (batched) | Medium | Slow (round-trips) | Medium |
-| **Context** | Low | Minimal | High (17+ tools) | Low |
-| **Approach** | Scripts | Single tool | Tool calls | Natural language |
-| **Best for** | Dev testing | Existing sessions | Cross-browser | AI automation |
-| **Requires** | Bun + server | Chrome extension | Nothing | API key |
-
-## Troubleshooting
-
-### Server Not Running
-
-```bash
-# Check if server is running
-bash ~/.aidevops/agents/scripts/dev-browser-helper.sh status
-
-# Start server
-bash ~/.aidevops/agents/scripts/dev-browser-helper.sh start
-```
-
-### Port 9222 In Use
-
-```bash
-# Find process using port
-lsof -i :9222
-
-# Kill if needed
-kill $(lsof -t -i :9222)
-
-# Restart server
-bash ~/.aidevops/agents/scripts/dev-browser-helper.sh restart
-```
-
-### Script Errors
-
-```bash
-# Debug with screenshot
-cd ~/.aidevops/dev-browser/skills/dev-browser && bun x tsx <<'EOF'
-import { connect } from "@/client.js";
-const client = await connect("http://localhost:9222");
-const page = await client.page("main");
-await page.screenshot({ path: "tmp/debug.png" });
-console.log({ url: page.url(), title: await page.title() });
-await client.disconnect();
-EOF
-```
-
-### Bun Not Found
-
-```bash
-# Install Bun
-curl -fsSL https://bun.sh/install | bash
-
-# Reload shell
-source ~/.bashrc  # or ~/.zshrc
-```
-
-## Resources
-
-- **GitHub**: https://github.com/SawyerHood/dev-browser
-- **Benchmarks**: 14% faster, 39% cheaper, 43% fewer turns than Playwright MCP
-- **License**: MIT

package/.agent/tools/browser/pagespeed.md

@@ -1,260 +0,0 @@
----
-description: PageSpeed Insights and Lighthouse performance testing
-mode: subagent
-tools:
-  read: true
-  write: false
-  edit: false
-  bash: true
-  glob: true
-  grep: true
-  webfetch: true
-  task: true
----
-
-# PageSpeed Insights & Lighthouse Integration Guide
-
-<!-- AI-CONTEXT-START -->
-
-## Quick Reference
-
-- **Helper**: `.agent/scripts/pagespeed-helper.sh`
-- **Commands**: `audit [url]` | `lighthouse [url] [format]` | `wordpress [url]` | `bulk [file]` | `report [json]`
-- **Install**: `brew install lighthouse jq bc` or `.agent/scripts/pagespeed-helper.sh install-deps`
-- **API Key**: Optional but recommended - https://console.cloud.google.com/ → Enable PageSpeed Insights API
-- **Core Web Vitals**: FCP (<1.8s), LCP (<2.5s), CLS (<0.1), FID (<100ms)
-- **Reports**: `~/.ai-devops/reports/pagespeed/`
-- **Rate Limits**: 25 req/100s (no key), 25,000/day (with key)
-- **WordPress**: Plugin audits, image optimization, caching recommendations
-<!-- AI-CONTEXT-END -->
-
-Comprehensive website performance auditing and optimization guidance for AI-assisted DevOps.
-
-## Overview
-
-This integration provides your AI assistant with powerful website performance auditing capabilities using:
-
-- **Google PageSpeed Insights API**: Real-time performance metrics and optimization suggestions
-- **Lighthouse CLI**: Comprehensive auditing for performance, accessibility, SEO, and best practices
-- **WordPress-specific analysis**: Tailored recommendations for WordPress websites
-- **Bulk auditing**: Analyze multiple websites efficiently
-- **MCP Integration**: Real-time performance data access for AI assistants
-
-## Setup & Installation
-
-### **Prerequisites**
-
-```bash
-# Install required dependencies
-cd ~/Git/aidevops
-./.agent/scripts/pagespeed-helper.sh install-deps
-
-# This will install:
-# - jq (JSON parsing)
-# - Lighthouse CLI (npm install -g lighthouse)
-# - bc (calculations)
-```
-
-### **Google API Key (Optional but Recommended)**
-
-1. **Get API Key**:
-   - Visit [Google Cloud Console](https://console.cloud.google.com/)
-   - Enable PageSpeed Insights API
-   - Create API key
-
-2. **Configure API Key**:
-
-   ```bash
-   export GOOGLE_API_KEY="your-api-key-here"
-   # Add to your shell profile for persistence
-   echo 'export GOOGLE_API_KEY="your-api-key-here"' >> ~/.bashrc
-   ```
-
-### **MCP Server Setup**
-
-```bash
-# Install PageSpeed MCP server
-npm install -g mcp-pagespeed-server
-
-# Install Lighthouse MCP server (if available)
-npm install -g lighthouse-mcp-server
-```
-
-## Usage Examples
-
-### **Basic Website Audit**
-
-```bash
-# Audit a website (desktop & mobile)
-./.agent/scripts/pagespeed-helper.sh audit https://example.com
-
-# Lighthouse comprehensive audit
-./.agent/scripts/pagespeed-helper.sh lighthouse https://example.com html
-```
-
-### **WordPress-Specific Analysis**
-
-```bash
-# WordPress performance analysis with specific recommendations
-./.agent/scripts/pagespeed-helper.sh wordpress https://myblog.com
-```
-
-### **Bulk Website Auditing**
-
-```bash
-# Create URLs file
-cat > websites.txt << EOF
-https://site1.com
-https://site2.com
-https://site3.com
-EOF
-
-# Run bulk audit
-./.agent/scripts/pagespeed-helper.sh bulk websites.txt
-```
-
-### **Generate Actionable Reports**
-
-```bash
-# Generate actionable recommendations from JSON report
-./.agent/scripts/pagespeed-helper.sh report ~/.ai-devops/reports/pagespeed/lighthouse_20241110_143022.json
-```
-
-## AI Assistant Integration
-
-### **System Prompt Addition**
-
-Add this to your AI assistant's system prompt:
-
-```text
-For website performance optimization, use the PageSpeed and Lighthouse tools available in
-~/Git/aidevops/.agent/scripts/pagespeed-helper.sh. Always provide specific,
-actionable recommendations focusing on Core Web Vitals and user experience.
-```
-
-### **Common AI Assistant Tasks**
-
-1. **Performance Audit**:
-
-   ```text
-   "Audit the performance of https://example.com and provide actionable recommendations"
-   ```
-
-2. **WordPress Optimization**:
-
-   ```text
-   "Analyze my WordPress site performance and suggest specific optimizations"
-   ```
-
-3. **Bulk Analysis**:
-
-   ```text
-   "Audit all websites in my portfolio and identify the top performance issues"
-   ```
-
-## Key Metrics Explained
-
-### **Core Web Vitals**
-
-- **First Contentful Paint (FCP)**: Time until first content appears
-  - Good: < 1.8s | Needs Improvement: 1.8s - 3.0s | Poor: > 3.0s
-
-- **Largest Contentful Paint (LCP)**: Time until largest content element loads
-  - Good: < 2.5s | Needs Improvement: 2.5s - 4.0s | Poor: > 4.0s
-
-- **Cumulative Layout Shift (CLS)**: Visual stability measure
-  - Good: < 0.1 | Needs Improvement: 0.1 - 0.25 | Poor: > 0.25
-
-- **First Input Delay (FID)**: Interactivity responsiveness
-  - Good: < 100ms | Needs Improvement: 100ms - 300ms | Poor: > 300ms
-
-### **Additional Metrics**
-
-- **Time to First Byte (TTFB)**: Server response time
-- **Speed Index**: How quickly content is visually displayed
-- **Total Blocking Time**: Time when main thread is blocked
-
-## WordPress-Specific Optimizations
-
-### **Common Issues & Solutions**
-
-1. **Plugin Performance**:
-   - Audit active plugins with Query Monitor
-   - Disable unnecessary plugins
-   - Use lightweight alternatives
-
-2. **Image Optimization**:
-   - Convert to WebP format
-   - Implement lazy loading
-   - Use proper image dimensions
-
-3. **Caching Implementation**:
-   - Page caching: WP Rocket, W3 Total Cache
-   - Object caching: Redis, Memcached
-   - CDN integration: Cloudflare, MaxCDN
-
-4. **Database Optimization**:
-   - Clean up post revisions
-   - Remove spam comments
-   - Optimize database tables
-
-5. **Theme & Code Optimization**:
-   - Use lightweight themes
-   - Minimize CSS/JS files
-   - Remove unused code
-
-## Report Storage
-
-All reports are saved to: `~/.ai-devops/reports/pagespeed/`
-
-### **Report Types**
-
-- **PageSpeed JSON**: `pagespeed_YYYYMMDD_HHMMSS_desktop.json`
-- **Lighthouse HTML**: `lighthouse_YYYYMMDD_HHMMSS.html`
-- **Lighthouse JSON**: `lighthouse_YYYYMMDD_HHMMSS.json`
-
-## Advanced Usage
-
-### **Custom Lighthouse Configuration**
-
-```bash
-# Run Lighthouse with specific categories
-lighthouse https://example.com \
-  --only-categories=performance,accessibility \
-  --output=json \
-  --output-path=custom-report.json
-```
-
-### **API Rate Limits**
-
-- **Without API Key**: 25 requests per 100 seconds
-- **With API Key**: 25,000 requests per day
-
-### **Automation Integration**
-
-```bash
-# Add to cron for regular monitoring
-0 9 * * 1 /path/to/pagespeed-helper.sh bulk /path/to/websites.txt
-```
-
-## Related Resources
-
-- **[Google PageSpeed Insights](https://pagespeed.web.dev/)**
-- **[Lighthouse Documentation](https://developers.google.com/web/tools/lighthouse)**
-- **[Core Web Vitals](https://web.dev/vitals/)**
-- **[WordPress Performance Guide](https://wordpress.org/support/article/optimization/)**
-
-## MCP Integration
-
-The PageSpeed MCP server provides real-time access to performance data for AI assistants:
-
-```json
-{
-  "pagespeed_audit": "Audit website performance",
-  "lighthouse_analysis": "Comprehensive website analysis",
-  "performance_metrics": "Get Core Web Vitals",
-  "optimization_recommendations": "Get actionable improvements"
-}
-```
-
-This enables AI assistants to provide immediate, data-driven performance optimization guidance.