bmad-plus 0.3.3 → 0.4.1

package/oveanet-pack/seo-audit-360/scripts/seo_screenshot.py

@@ -1,202 +0,0 @@
-#!/usr/bin/env python3
-"""
-SEO Screenshot — Viewport screenshot capture for visual SEO analysis.
-
-Features:
-- Mobile and desktop viewport presets
-- Above-the-fold element detection
-- Full-page capture option
-- PNG output with configurable quality
-
-Requires: playwright (pip install playwright && playwright install chromium)
-
-Author: Laurent Rochetta
-License: MIT
-"""
-
-import argparse
-import sys
-
-
-VIEWPORTS = {
-    "mobile": {"width": 375, "height": 812, "device_scale_factor": 3, "is_mobile": True},
-    "tablet": {"width": 768, "height": 1024, "device_scale_factor": 2, "is_mobile": True},
-    "desktop": {"width": 1440, "height": 900, "device_scale_factor": 1, "is_mobile": False},
-    "desktop-hd": {"width": 1920, "height": 1080, "device_scale_factor": 1, "is_mobile": False},
-}
-
-
-def capture_screenshot(
-    url: str,
-    output: str = "screenshot.png",
-    viewport: str = "desktop",
-    full_page: bool = False,
-    wait_ms: int = 2000,
-):
-    """
-    Capture a viewport screenshot of a URL using Playwright.
-
-    Args:
-        url: URL to capture
-        output: Output file path (.png)
-        viewport: Viewport preset (mobile, tablet, desktop, desktop-hd)
-        full_page: Capture full page scroll or just viewport
-        wait_ms: Wait time after page load (ms)
-    """
-    try:
-        from playwright.sync_api import sync_playwright
-    except ImportError:
-        print(
-            "Error: playwright required.\n"
-            "Install: pip install playwright && playwright install chromium",
-            file=sys.stderr,
-        )
-        sys.exit(1)
-
-    vp = VIEWPORTS.get(viewport, VIEWPORTS["desktop"])
-
-    with sync_playwright() as p:
-        browser = p.chromium.launch(headless=True)
-        context = browser.new_context(
-            viewport={"width": vp["width"], "height": vp["height"]},
-            device_scale_factor=vp["device_scale_factor"],
-            is_mobile=vp["is_mobile"],
-            user_agent=(
-                "Mozilla/5.0 (iPhone; CPU iPhone OS 17_0 like Mac OS X) "
-                "AppleWebKit/605.1.15 Mobile/15E148 Safari/604.1"
-                if vp["is_mobile"]
-                else "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 "
-                "(KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36 BMADSEOEngine/2.0"
-            ),
-        )
-
-        page = context.new_page()
-
-        try:
-            page.goto(url, wait_until="networkidle", timeout=30000)
-        except Exception:
-            # Fallback: wait for load event instead
-            page.goto(url, wait_until="load", timeout=30000)
-
-        # Wait for dynamic content
-        page.wait_for_timeout(wait_ms)
-
-        # Capture screenshot
-        page.screenshot(path=output, full_page=full_page)
-
-        # Gather above-the-fold metrics
-        metrics = page.evaluate("""() => {
-            const viewportHeight = window.innerHeight;
-            const viewportWidth = window.innerWidth;
-
-            // Find CTAs above the fold
-            const ctas = [];
-            const buttons = document.querySelectorAll('a, button, [role="button"]');
-            buttons.forEach(el => {
-                const rect = el.getBoundingClientRect();
-                if (rect.top < viewportHeight && rect.bottom > 0) {
-                    const text = el.textContent.trim().substring(0, 50);
-                    if (text && (
-                        /sign.?up|get.?start|try|buy|contact|demo|free|download|subscribe/i.test(text)
-                    )) {
-                        ctas.push({
-                            text: text,
-                            tag: el.tagName,
-                            top: Math.round(rect.top),
-                            visible: rect.width > 0 && rect.height > 0,
-                        });
-                    }
-                }
-            });
-
-            // Find hero/LCP candidate
-            const images = document.querySelectorAll('img');
-            let largestImage = null;
-            let largestArea = 0;
-            images.forEach(img => {
-                const rect = img.getBoundingClientRect();
-                const area = rect.width * rect.height;
-                if (area > largestArea && rect.top < viewportHeight) {
-                    largestArea = area;
-                    largestImage = {
-                        src: img.src.substring(0, 100),
-                        width: Math.round(rect.width),
-                        height: Math.round(rect.height),
-                        top: Math.round(rect.top),
-                    };
-                }
-            });
-
-            // Check for horizontal scroll
-            const hasHorizontalScroll = document.documentElement.scrollWidth > viewportWidth;
-
-            // Font size check
-            const body = document.body;
-            const bodyFontSize = body ? parseFloat(getComputedStyle(body).fontSize) : 16;
-
-            return {
-                viewportWidth,
-                viewportHeight,
-                ctas_above_fold: ctas.length,
-                cta_details: ctas.slice(0, 5),
-                largest_image_above_fold: largestImage,
-                has_horizontal_scroll: hasHorizontalScroll,
-                body_font_size_px: bodyFontSize,
-                dom_element_count: document.querySelectorAll('*').length,
-            };
-        }""")
-
-        browser.close()
-
-    return metrics
-
-
-# ── CLI ────────────────────────────────────────────────────────────
-
-def main():
-    parser = argparse.ArgumentParser(
-        description="SEO Screenshot — Viewport capture (BMAD+ SEO Engine)"
-    )
-    parser.add_argument("url", help="URL to capture")
-    parser.add_argument("--output", "-o", default="screenshot.png", help="Output file path")
-    parser.add_argument(
-        "--viewport", "-v",
-        choices=list(VIEWPORTS.keys()), default="desktop",
-        help="Viewport preset"
-    )
-    parser.add_argument("--full", action="store_true", help="Capture full page (not just viewport)")
-    parser.add_argument("--wait", "-w", type=int, default=2000, help="Wait after load (ms)")
-    parser.add_argument("--json", "-j", action="store_true", help="Output metrics as JSON")
-
-    args = parser.parse_args()
-
-    import json
-
-    metrics = capture_screenshot(
-        url=args.url,
-        output=args.output,
-        viewport=args.viewport,
-        full_page=args.full,
-        wait_ms=args.wait,
-    )
-
-    print(f"Screenshot saved: {args.output}", file=sys.stderr)
-
-    if args.json:
-        print(json.dumps(metrics, indent=2))
-    else:
-        print(f"\nAbove-the-Fold Analysis ({args.viewport}):")
-        print(f"  Viewport: {metrics['viewportWidth']}×{metrics['viewportHeight']}")
-        print(f"  CTAs above fold: {metrics['ctas_above_fold']}")
-        for cta in metrics.get("cta_details", []):
-            print(f"    - \"{cta['text']}\" ({cta['tag']}, top: {cta['top']}px)")
-        if metrics.get("largest_image_above_fold"):
-            img = metrics["largest_image_above_fold"]
-            print(f"  Largest image: {img['width']}×{img['height']} at y={img['top']}px")
-        print(f"  Horizontal scroll: {'⚠️ YES' if metrics['has_horizontal_scroll'] else '✅ No'}")
-        print(f"  Body font size: {metrics['body_font_size_px']}px {'✅' if metrics['body_font_size_px'] >= 16 else '⚠️ <16px'}")
-        print(f"  DOM elements: {metrics['dom_element_count']:,}")
-
-
-if __name__ == "__main__":
-    main()

package/oveanet-pack/seo-audit-360/templates/seo-audit-workflow.md

@@ -1,241 +0,0 @@
-# SEO Audit Workflow — BMAD+ SEO Engine v2.0
-
-> Author: Laurent Rochetta | By Oveanet × Laurent Rochetta
-
-## Overview
-
-This workflow orchestrates the 3 SEO Engine agents (Scout, Judge, Chief) through 6 phases to produce a comprehensive audit with scored results and actionable fixes.
-
----
-
-## Phase 1 — Reconnaissance (Scout solo)
-
-**Duration**: ~2 min | **Agent**: Scout (Crawler role)
-
-1. Fetch homepage + `/robots.txt` + `/sitemap.xml`
-2. Detect business type (SaaS, e-commerce, local, publisher, agency)
-3. Mini-crawl: discover 10–25 pages via sitemap + internal links
-4. Detect rendering architecture (SSR / CSR / hybrid)
-5. Check for `/llms.txt` and `/llms-full.txt`
-
-**Checkpoint**: "Identified a [type] site with [N] pages. Continue full audit?"
-
-**Tools**:
-```bash
-python scripts/seo_fetch.py [URL] --json
-python scripts/seo_crawl.py [URL] --depth 2 --max 25 --json
-```
-
----
-
-## Phase 2 — Deep Scan (Scout + Judge in PARALLEL)
-
-**Duration**: ~5 min | **Agents**: Scout (Inspector) + Judge (Content Expert + Schema Master)
-
-### Scout inspects (9 categories):
-1. Crawlability (robots.txt, noindex, crawl depth)
-2. Indexability (canonicals, duplicates, pagination)
-3. Security (HTTPS, HSTS, CSP, X-Frame-Options)
-4. URL Structure (clean URLs, redirects, trailing slashes)
-5. Mobile (viewport, touch targets, font size)
-6. Core Web Vitals signals from source HTML
-7. Structured Data detection (pass to Judge)
-8. JavaScript rendering (CSR/SSR, SPA detection)
-9. IndexNow protocol
-
-### Judge analyzes (in parallel):
-1. E-E-A-T evaluation (Experience, Expertise, Authority, Trust)
-2. Content quality (word count, readability, keyword optimization)
-3. Schema validation (JSON-LD, types, deprecation status)
-4. Image audit (alt text, dimensions, format, lazy loading)
-5. Internal/external link analysis
-6. AI content detection markers
-
-**Tools**:
-```bash
-python scripts/seo_parse.py page.html --url [URL] --json
-python scripts/seo_screenshot.py [URL] --viewport mobile --json
-python scripts/seo_screenshot.py [URL] --viewport desktop --json
-```
-
----
-
-## Phase 3 — AI Readiness & GEO (Judge solo)
-
-**Duration**: ~3 min | **Agent**: Judge (GEO Analyst role)
-
-1. Check AI crawler access (GPTBot, ClaudeBot, PerplexityBot, OAI-SearchBot)
-2. Verify llms.txt compliance
-3. Check RSL 1.0 licensing
-4. Score passage-level citability (134–167 word blocks)
-5. Analyze brand mention signals
-6. Compute **AI Readiness Score (0–100)**
-
-Reference: `ref/geo-signals.md`
-
----
-
-## Phase 4 — Scoring & Synthesis (Chief solo)
-
-**Duration**: ~2 min | **Agent**: Chief (Scorer role)
-
-Compute **SEO Health Score (0–100)** from weighted categories:
-
-| Category | Weight |
-|----------|--------|
-| Technical SEO | 20% |
-| Content & E-E-A-T | 22% |
-| On-Page SEO | 18% |
-| Schema | 10% |
-| Performance (CWV) | 12% |
-| AI Readiness (GEO) | 12% |
-| Images | 6% |
-
-Output: Score breakdown with visual indicators per category.
-
----
-
-## Phase 5 — Action Plan & Auto-Fixes (Chief solo)
-
-**Duration**: ~3 min | **Agent**: Chief (Strategist role)
-
-1. Classify all issues: 🔴 Critical → 🟠 High → 🟡 Medium → 🟢 Low
-2. Identify Quick Wins (high impact / low effort)
-3. Generate 30/60/90-day roadmap
-4. **Auto-generate code fixes** for:
-   - Missing/broken meta tags (title, description)
-   - Schema JSON-LD blocks (from templates)
-   - robots.txt improvements (AI crawler access)
-   - llms.txt file generation
-   - Image alt text suggestions
-5. **Checkpoint**: "Here's the plan. Want me to apply the fixes automatically?"
-
----
-
-## Phase 5b — PageSpeed Perfection Loop (Scout + Chief iterative)
-
-> **This is the battle-tested loop from our oveanet.ch optimization.**
-> Goal: Achieve **100% on all 4 PageSpeed Insights categories** (Performance, Accessibility, Best Practices, SEO).
-
-### The Loop
-
-```
-┌─────────────────────────────────────┐
-│  1. Run PageSpeed Insights audit    │
-│     (via API or manual)             │
-│           │                         │
-│           ▼                         │
-│  2. Parse failing audits            │
-│     Group by category + priority    │
-│           │                         │
-│           ▼                         │
-│  3. Apply top-priority fix          │
-│     (one fix at a time)             │
-│           │                         │
-│           ▼                         │
-│  4. Re-run PageSpeed                │
-│     Verify fix + no regressions     │
-│           │                         │
-│           ▼                         │
-│  5. Score improved?                 │
-│     YES → Continue to next fix      │
-│     NO → Revert and try different   │
-│           approach                  │
-│           │                         │
-│           ▼                         │
-│  6. All 4 categories = 100%?        │
-│     YES → Done ✅                   │
-│     NO → Go to step 2              │
-└─────────────────────────────────────┘
-```
-
-### PageSpeed Fix Priority Order
-1. **Performance** (hardest — tackle first):
-   - Eliminate render-blocking resources
-   - Properly size images (WebP/AVIF + responsive)
-   - Reduce unused CSS/JS
-   - Defer offscreen images
-   - Minimize main-thread work
-   - Reduce server response time (TTFB)
-   - Preload LCP image
-
-2. **Accessibility** (usually quick wins):
-   - Add alt text to all images
-   - Fix color contrast ratios (4.5:1 minimum)
-   - Add ARIA labels to interactive elements
-   - Ensure heading hierarchy
-   - Add lang attribute to HTML
-   - Ensure form labels
-
-3. **Best Practices**:
-   - HTTPS + no mixed content
-   - No browser errors in console
-   - Remove deprecated APIs
-   - Add proper CSP headers
-
-4. **SEO** (usually easiest):
-   - Add meta description
-   - Ensure crawlable links
-   - Valid robots.txt
-   - Proper viewport meta
-   - Descriptive link text
-
-### Key Rules
-- **One fix at a time** — never batch multiple changes, you need to isolate impact
-- **Always re-test** — PageSpeed scores can regress with seemingly unrelated changes
-- **Mobile first** — always test mobile viewport (Google uses mobile for indexing)
-- **Field vs Lab** — Lab scores (Lighthouse) can differ from field data (CrUX). Target lab 100% first
-
----
-
-## Phase 6 — Monitoring (Scout, optional)
-
-**Duration**: ongoing | **Agent**: Scout (Crawler role)
-
-1. Save audit results to `.bmad-seo/history/[domain]-[date].json`
-2. On re-audit: compare with previous results
-3. Track: issues resolved, new issues, score evolution
-4. Generate progress report with deltas
-
----
-
-## Command Quick Reference
-
-```bash
-# Full audit (all 6 phases)
-/seo full https://example.com
-
-# Quick audit (Phases 1-4 only)
-/seo quick https://example.com
-
-# Individual commands
-/seo technical https://example.com
-/seo content https://example.com
-/seo geo https://example.com
-/seo schema https://example.com
-/seo images https://example.com
-/seo hreflang https://example.com
-
-# PageSpeed perfection loop
-/seo pagespeed https://example.com
-
-# Strategic planning
-/seo plan saas|ecommerce|local|publisher|agency
-
-# Auto-fix generation
-/seo fix
-
-# Monitoring
-/seo history
-/seo compare
-```
-
----
-
-## Tips for Best Results
-
-1. **Start with `/seo full`** for the first audit — it gives you the complete picture
-2. **Use `/seo pagespeed`** after fixing major issues to chase 100% scores
-3. **Re-run monthly** with `/seo compare` to track progress
-4. **Feed the AI crawlers**: Allow GPTBot + ClaudeBot + PerplexityBot in robots.txt
-5. **Check GEO separately**: AI search visibility evolves fast, audit quarterly with `/seo geo`

package/oveanet-pack/seo-audit-360/tests/fixtures/sample_page.html

@@ -1,62 +0,0 @@
-<!DOCTYPE html>
-<html lang="en">
-<head>
-    <meta charset="UTF-8">
-    <title>SEO Test Page — BMAD+ Fixture</title>
-    <meta name="description" content="A test page for validating the SEO parse module with known elements.">
-    <meta name="robots" content="index, follow">
-    <meta name="viewport" content="width=device-width, initial-scale=1.0">
-    <meta property="og:title" content="SEO Test Page">
-    <meta property="og:type" content="website">
-    <meta property="og:url" content="https://example.com/test">
-    <meta name="twitter:card" content="summary_large_image">
-    <meta name="twitter:title" content="SEO Test Page">
-    <link rel="canonical" href="https://example.com/test">
-    <link rel="alternate" hreflang="en" href="https://example.com/en/test">
-    <link rel="alternate" hreflang="fr" href="https://example.com/fr/test">
-    <link rel="alternate" hreflang="x-default" href="https://example.com/test">
-</head>
-<body>
-    <h1>Main Heading of the Page</h1>
-    <p>This is a test paragraph with enough words to verify word count functionality in the parser module. We need at least a few sentences to make the test meaningful and realistic.</p>
-
-    <h2>Second Level Heading One</h2>
-    <p>Content under the first H2. This paragraph adds more text to increase the word count.</p>
-
-    <h2>Second Level Heading Two</h2>
-    <p>Another section with different content about SEO analysis and testing.</p>
-
-    <h3>Third Level Heading</h3>
-    <p>Detailed information under the H3 heading for testing hierarchy detection.</p>
-
-    <img src="/images/hero.jpg" alt="Hero image for testing" width="800" height="400" loading="lazy">
-    <img src="/images/no-alt.jpg" width="200" height="200">
-    <img src="/images/empty-alt.jpg" alt="" width="100" height="100">
-
-    <a href="https://example.com/about">About Us</a>
-    <a href="https://example.com/services">Our Services</a>
-    <a href="https://external.com/partner" rel="nofollow" target="_blank">Partner Link</a>
-    <a href="/relative-link">Relative Link</a>
-
-    <script type="application/ld+json">
-    {
-        "@context": "https://schema.org",
-        "@type": "Organization",
-        "name": "Test Company",
-        "url": "https://example.com",
-        "logo": "https://example.com/logo.png"
-    }
-    </script>
-
-    <script type="application/ld+json">
-    {
-        "@context": "https://schema.org",
-        "@type": "BreadcrumbList",
-        "itemListElement": [
-            {"@type": "ListItem", "position": 1, "name": "Home", "item": "https://example.com"},
-            {"@type": "ListItem", "position": 2, "name": "Test", "item": "https://example.com/test"}
-        ]
-    }
-    </script>
-</body>
-</html>

package/oveanet-pack/seo-audit-360/tests/test_apis.py

@@ -1,75 +0,0 @@
-"""
-Tests for seo_apis.py — API response parsing and error handling.
-
-Author: Laurent Rochetta
-"""
-
-import sys
-import os
-sys.path.insert(0, os.path.join(os.path.dirname(__file__), "..", "scripts"))
-
-# Temporarily unset API key for error tests
-original_key = os.environ.get("GOOGLE_API_KEY", "")
-
-
-class TestAPIKeyMissing:
-    """Test behavior when GOOGLE_API_KEY is not set."""
-
-    def setup_method(self):
-        os.environ.pop("GOOGLE_API_KEY", None)
-        # Reimport to pick up empty key
-        import importlib
-        import seo_apis
-        importlib.reload(seo_apis)
-        self.seo_apis = seo_apis
-
-    def teardown_method(self):
-        if original_key:
-            os.environ["GOOGLE_API_KEY"] = original_key
-
-    def test_pagespeed_without_key(self):
-        # Force the module to use an empty key
-        self.seo_apis.API_KEY = ""
-        result = self.seo_apis.run_pagespeed("https://example.com")
-        assert result.get("error") is not None
-        assert "GOOGLE_API_KEY" in result["error"]
-
-    def test_crux_without_key(self):
-        self.seo_apis.API_KEY = ""
-        result = self.seo_apis.run_crux("https://example.com")
-        assert result.get("error") is not None
-
-    def test_rich_results_without_key(self):
-        self.seo_apis.API_KEY = ""
-        result = self.seo_apis.run_rich_results_test("https://example.com")
-        assert result.get("error") is not None
-
-
-class TestResultStructure:
-    """Test that API functions return expected structures."""
-
-    def setup_method(self):
-        import importlib
-        import seo_apis
-        importlib.reload(seo_apis)
-        self.seo_apis = seo_apis
-
-    def test_pagespeed_result_keys(self):
-        self.seo_apis.API_KEY = ""
-        result = self.seo_apis.run_pagespeed("https://example.com")
-        # Even on error, should have expected structure
-        assert "error" in result
-
-    def test_crux_result_keys(self):
-        self.seo_apis.API_KEY = ""
-        result = self.seo_apis.run_crux("https://example.com")
-        assert "error" in result
-
-    def test_run_all_structure(self):
-        self.seo_apis.API_KEY = ""
-        result = self.seo_apis.run_all("https://example.com")
-        assert "pagespeed" in result
-        assert "crux" in result
-        assert "mobile_friendly" in result
-        assert "url" in result
-        assert "timestamp" in result