aidevops 2.52.1

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

@@ -0,0 +1,341 @@
+---
+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

@@ -0,0 +1,260 @@
+---
+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.