bmad-plus 0.2.0 → 0.3.0

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

@@ -0,0 +1,231 @@
+#!/usr/bin/env python3
+"""
+SEO Fetch — Secure HTTP page fetcher for SEO analysis.
+
+Features:
+- SSRF protection (blocks private/loopback/reserved IPs)
+- Multi-UA support (standard, Googlebot, GPTBot, ClaudeBot)
+- Redirect chain tracking
+- Cookie handling
+- Configurable timeout
+
+Author: Laurent Rochetta
+License: MIT
+"""
+
+import argparse
+import ipaddress
+import json
+import socket
+import sys
+from typing import Optional
+from urllib.parse import urlparse
+
+try:
+    import requests
+except ImportError:
+    print("Error: requests library required. Install: pip install requests", file=sys.stderr)
+    sys.exit(1)
+
+
+# ── User-Agent Presets ──────────────────────────────────────────────
+
+USER_AGENTS = {
+    "default": (
+        "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 "
+        "(KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36 BMADSEOEngine/2.0"
+    ),
+    "googlebot": (
+        "Mozilla/5.0 (compatible; Googlebot/2.1; +http://www.google.com/bot.html)"
+    ),
+    "gptbot": (
+        "Mozilla/5.0 AppleWebKit/537.36 (KHTML, like Gecko; compatible; GPTBot/1.2; "
+        "+https://openai.com/gptbot)"
+    ),
+    "claudebot": (
+        "Mozilla/5.0 (compatible; ClaudeBot/1.0; +https://www.anthropic.com/claudebot)"
+    ),
+    "mobile": (
+        "Mozilla/5.0 (iPhone; CPU iPhone OS 17_0 like Mac OS X) "
+        "AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.0 Mobile/15E148 Safari/604.1"
+    ),
+}
+
+DEFAULT_HEADERS = {
+    "Accept": "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8",
+    "Accept-Language": "en-US,en;q=0.9,fr;q=0.8",
+    "Accept-Encoding": "gzip, deflate, br",
+    "Connection": "keep-alive",
+    "Cache-Control": "no-cache",
+}
+
+
+# ── Security: SSRF Prevention ──────────────────────────────────────
+
+def is_safe_url(url: str) -> bool:
+    """Block requests to private, loopback, and reserved IP addresses."""
+    parsed = urlparse(url)
+    hostname = parsed.hostname
+
+    if not hostname:
+        return False
+
+    try:
+        resolved_ip = socket.gethostbyname(hostname)
+        ip = ipaddress.ip_address(resolved_ip)
+        if ip.is_private or ip.is_loopback or ip.is_reserved or ip.is_link_local:
+            return False
+    except (socket.gaierror, ValueError):
+        pass  # DNS failure handled by requests
+
+    return True
+
+
+# ── Core Fetcher ───────────────────────────────────────────────────
+
+def fetch_page(
+    url: str,
+    timeout: int = 30,
+    follow_redirects: bool = True,
+    max_redirects: int = 5,
+    user_agent: str = "default",
+) -> dict:
+    """
+    Fetch a web page with security checks and detailed response tracking.
+
+    Returns dict with: url, status_code, content, headers, redirect_chain,
+    content_length, response_time_ms, error
+    """
+    result = {
+        "url": url,
+        "final_url": None,
+        "status_code": None,
+        "content": None,
+        "headers": {},
+        "redirect_chain": [],
+        "content_length": 0,
+        "response_time_ms": 0,
+        "error": None,
+    }
+
+    # Normalize URL
+    parsed = urlparse(url)
+    if not parsed.scheme:
+        url = f"https://{url}"
+        parsed = urlparse(url)
+
+    if parsed.scheme not in ("http", "https"):
+        result["error"] = f"Invalid URL scheme: {parsed.scheme}"
+        return result
+
+    # SSRF check
+    if not is_safe_url(url):
+        resolved = "unknown"
+        try:
+            resolved = socket.gethostbyname(parsed.hostname)
+        except Exception:
+            pass
+        result["error"] = f"Blocked: URL resolves to private/internal IP ({resolved})"
+        return result
+
+    try:
+        session = requests.Session()
+        session.max_redirects = max_redirects
+
+        headers = dict(DEFAULT_HEADERS)
+        ua_string = USER_AGENTS.get(user_agent, user_agent)
+        headers["User-Agent"] = ua_string
+
+        import time
+        start = time.monotonic()
+
+        response = session.get(
+            url,
+            headers=headers,
+            timeout=timeout,
+            allow_redirects=follow_redirects,
+        )
+
+        elapsed_ms = round((time.monotonic() - start) * 1000)
+
+        result["final_url"] = response.url
+        result["status_code"] = response.status_code
+        result["content"] = response.text
+        result["headers"] = dict(response.headers)
+        result["content_length"] = len(response.content)
+        result["response_time_ms"] = elapsed_ms
+
+        if response.history:
+            result["redirect_chain"] = [
+                {"url": r.url, "status": r.status_code}
+                for r in response.history
+            ]
+
+    except requests.exceptions.Timeout:
+        result["error"] = f"Request timed out after {timeout}s"
+    except requests.exceptions.TooManyRedirects:
+        result["error"] = f"Too many redirects (max {max_redirects})"
+    except requests.exceptions.SSLError as e:
+        result["error"] = f"SSL error: {e}"
+    except requests.exceptions.ConnectionError as e:
+        result["error"] = f"Connection error: {e}"
+    except requests.exceptions.RequestException as e:
+        result["error"] = f"Request failed: {e}"
+
+    return result
+
+
+# ── CLI ────────────────────────────────────────────────────────────
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="SEO Fetch — Secure HTTP fetcher for SEO analysis (BMAD+ SEO Engine)"
+    )
+    parser.add_argument("url", help="URL to fetch")
+    parser.add_argument("--output", "-o", help="Save HTML to file")
+    parser.add_argument("--timeout", "-t", type=int, default=30, help="Timeout in seconds")
+    parser.add_argument("--no-redirects", action="store_true", help="Don't follow redirects")
+    parser.add_argument(
+        "--ua", choices=list(USER_AGENTS.keys()), default="default",
+        help="User-Agent preset (default, googlebot, gptbot, claudebot, mobile)"
+    )
+    parser.add_argument("--json", "-j", action="store_true", help="Output full result as JSON")
+
+    args = parser.parse_args()
+
+    result = fetch_page(
+        args.url,
+        timeout=args.timeout,
+        follow_redirects=not args.no_redirects,
+        user_agent=args.ua,
+    )
+
+    if result["error"]:
+        print(f"Error: {result['error']}", file=sys.stderr)
+        sys.exit(1)
+
+    if args.json:
+        # Output metadata as JSON (without full HTML content for readability)
+        output = {k: v for k, v in result.items() if k != "content"}
+        output["content_preview"] = result["content"][:500] if result["content"] else None
+        print(json.dumps(output, indent=2))
+    elif args.output:
+        with open(args.output, "w", encoding="utf-8") as f:
+            f.write(result["content"])
+        print(f"Saved to {args.output}")
+    else:
+        print(result["content"])
+
+    # Metadata to stderr
+    print(f"\n--- Fetch Summary ---", file=sys.stderr)
+    print(f"Final URL: {result['final_url']}", file=sys.stderr)
+    print(f"Status: {result['status_code']}", file=sys.stderr)
+    print(f"Size: {result['content_length']:,} bytes", file=sys.stderr)
+    print(f"Time: {result['response_time_ms']}ms", file=sys.stderr)
+    if result["redirect_chain"]:
+        chain = " → ".join(r["url"] for r in result["redirect_chain"])
+        print(f"Redirects: {chain}", file=sys.stderr)
+
+
+if __name__ == "__main__":
+    main()

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

@@ -0,0 +1,255 @@
+#!/usr/bin/env python3
+"""
+SEO Parse — HTML parser for SEO element extraction.
+
+Extracts: title, meta tags, canonicals, headings, images, links (internal/external),
+schema (JSON-LD), Open Graph, Twitter Cards, hreflang, word count, text/code ratio.
+
+Author: Laurent Rochetta
+License: MIT
+"""
+
+import argparse
+import json
+import os
+import re
+import sys
+from typing import Optional
+from urllib.parse import urljoin, urlparse
+
+try:
+    from bs4 import BeautifulSoup
+except ImportError:
+    print("Error: beautifulsoup4 required. Install: pip install beautifulsoup4", file=sys.stderr)
+    sys.exit(1)
+
+# Use lxml if available for speed, fallback to html.parser
+try:
+    import lxml  # noqa: F401
+    HTML_PARSER = "lxml"
+except ImportError:
+    HTML_PARSER = "html.parser"
+
+
+def parse_html(html: str, base_url: Optional[str] = None) -> dict:
+    """
+    Parse HTML and extract all SEO-relevant elements.
+
+    Args:
+        html: Raw HTML content
+        base_url: Base URL for resolving relative links
+
+    Returns:
+        Comprehensive dictionary of SEO data
+    """
+    soup = BeautifulSoup(html, HTML_PARSER)
+
+    result = {
+        "title": None,
+        "title_length": 0,
+        "meta_description": None,
+        "meta_description_length": 0,
+        "meta_robots": None,
+        "meta_viewport": None,
+        "canonical": None,
+        "headings": {"h1": [], "h2": [], "h3": [], "h4": []},
+        "images": [],
+        "links": {"internal": [], "external": [], "broken_candidates": []},
+        "schema_blocks": [],
+        "open_graph": {},
+        "twitter_card": {},
+        "hreflang": [],
+        "word_count": 0,
+        "html_size_bytes": len(html.encode("utf-8")),
+        "text_ratio": 0.0,
+        "has_lang_attr": False,
+        "lang": None,
+        "scripts_count": 0,
+        "stylesheets_count": 0,
+        "dom_depth_estimate": 0,
+        "security_headers_hints": {},
+    }
+
+    # ── Title ──
+    title_tag = soup.find("title")
+    if title_tag:
+        result["title"] = title_tag.get_text(strip=True)
+        result["title_length"] = len(result["title"])
+
+    # ── Meta Tags ──
+    for meta in soup.find_all("meta"):
+        name = (meta.get("name") or "").lower()
+        property_attr = (meta.get("property") or "").lower()
+        content = meta.get("content", "")
+
+        if name == "description":
+            result["meta_description"] = content
+            result["meta_description_length"] = len(content)
+        elif name == "robots":
+            result["meta_robots"] = content
+        elif name == "viewport":
+            result["meta_viewport"] = content
+
+        # Open Graph
+        if property_attr.startswith("og:"):
+            result["open_graph"][property_attr] = content
+
+        # Twitter Card
+        if name.startswith("twitter:"):
+            result["twitter_card"][name] = content
+
+    # ── Language ──
+    html_tag = soup.find("html")
+    if html_tag and html_tag.get("lang"):
+        result["has_lang_attr"] = True
+        result["lang"] = html_tag.get("lang")
+
+    # ── Canonical ──
+    canonical = soup.find("link", rel="canonical")
+    if canonical:
+        result["canonical"] = canonical.get("href")
+
+    # ── Hreflang ──
+    for link in soup.find_all("link", rel="alternate"):
+        hreflang = link.get("hreflang")
+        if hreflang:
+            result["hreflang"].append({
+                "lang": hreflang,
+                "href": link.get("href"),
+            })
+
+    # ── Headings ──
+    for level in ["h1", "h2", "h3", "h4"]:
+        for tag in soup.find_all(level):
+            text = tag.get_text(strip=True)
+            if text:
+                result["headings"][level].append(text)
+
+    # ── Images ──
+    for img in soup.find_all("img"):
+        src = img.get("src", "")
+        if base_url and src:
+            src = urljoin(base_url, src)
+
+        has_alt = img.get("alt") is not None
+        alt_text = img.get("alt", "")
+        has_dimensions = bool(img.get("width") and img.get("height"))
+
+        result["images"].append({
+            "src": src,
+            "alt": alt_text,
+            "has_alt": has_alt,
+            "alt_empty": has_alt and alt_text.strip() == "",
+            "width": img.get("width"),
+            "height": img.get("height"),
+            "has_dimensions": has_dimensions,
+            "loading": img.get("loading"),
+            "srcset": img.get("srcset") is not None,
+        })
+
+    # ── Links ──
+    if base_url:
+        base_domain = urlparse(base_url).netloc
+
+        for a in soup.find_all("a", href=True):
+            href = a.get("href", "")
+            if not href or href.startswith("#") or href.startswith("javascript:"):
+                continue
+
+            full_url = urljoin(base_url, href)
+            parsed = urlparse(full_url)
+
+            link_data = {
+                "href": full_url,
+                "text": a.get_text(strip=True)[:100],
+                "rel": a.get("rel", []),
+                "is_nofollow": "nofollow" in (a.get("rel") or []),
+                "target": a.get("target"),
+            }
+
+            if parsed.netloc == base_domain:
+                result["links"]["internal"].append(link_data)
+            else:
+                result["links"]["external"].append(link_data)
+
+    # ── Schema (JSON-LD) ──
+    for script in soup.find_all("script", type="application/ld+json"):
+        try:
+            schema_data = json.loads(script.string)
+            if isinstance(schema_data, dict):
+                result["schema_blocks"].append({
+                    "type": schema_data.get("@type", "unknown"),
+                    "data": schema_data,
+                })
+            elif isinstance(schema_data, list):
+                for item in schema_data:
+                    if isinstance(item, dict):
+                        result["schema_blocks"].append({
+                            "type": item.get("@type", "unknown"),
+                            "data": item,
+                        })
+        except (json.JSONDecodeError, TypeError):
+            result["schema_blocks"].append({"type": "PARSE_ERROR", "data": None})
+
+    # ── Resource Counts ──
+    result["scripts_count"] = len(soup.find_all("script"))
+    result["stylesheets_count"] = len(soup.find_all("link", rel="stylesheet"))
+
+    # ── Word Count & Text Ratio ──
+    text_soup = BeautifulSoup(html, HTML_PARSER)
+    for element in text_soup(["script", "style", "nav", "footer", "header", "noscript"]):
+        element.decompose()
+
+    visible_text = text_soup.get_text(separator=" ", strip=True)
+    words = re.findall(r"\b\w+\b", visible_text)
+    result["word_count"] = len(words)
+
+    text_bytes = len(visible_text.encode("utf-8"))
+    if result["html_size_bytes"] > 0:
+        result["text_ratio"] = round(text_bytes / result["html_size_bytes"], 3)
+
+    return result
+
+
+# ── CLI ────────────────────────────────────────────────────────────
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="SEO Parse — HTML parser for SEO analysis (BMAD+ SEO Engine)"
+    )
+    parser.add_argument("file", nargs="?", help="HTML file to parse")
+    parser.add_argument("--url", "-u", help="Base URL for resolving relative links")
+    parser.add_argument("--json", "-j", action="store_true", help="Output as JSON")
+
+    args = parser.parse_args()
+
+    if args.file:
+        real_path = os.path.realpath(args.file)
+        if not os.path.isfile(real_path):
+            print(f"Error: File not found: {args.file}", file=sys.stderr)
+            sys.exit(1)
+        with open(real_path, "r", encoding="utf-8") as f:
+            html = f.read()
+    else:
+        html = sys.stdin.read()
+
+    result = parse_html(html, args.url)
+
+    if args.json:
+        print(json.dumps(result, indent=2, ensure_ascii=False))
+    else:
+        print(f"Title: {result['title']} ({result['title_length']} chars)")
+        print(f"Meta Description: {result['meta_description'][:80] + '...' if result['meta_description'] and len(result['meta_description']) > 80 else result['meta_description']}")
+        print(f"Canonical: {result['canonical']}")
+        print(f"Language: {result['lang']}")
+        print(f"H1: {len(result['headings']['h1'])} | H2: {len(result['headings']['h2'])} | H3: {len(result['headings']['h3'])}")
+        print(f"Images: {len(result['images'])} (missing alt: {sum(1 for i in result['images'] if not i['has_alt'])})")
+        print(f"Internal Links: {len(result['links']['internal'])} | External: {len(result['links']['external'])}")
+        print(f"Schema Blocks: {len(result['schema_blocks'])} ({', '.join(s['type'] for s in result['schema_blocks'])})")
+        print(f"Word Count: {result['word_count']:,}")
+        print(f"Text/HTML Ratio: {result['text_ratio']:.1%}")
+        print(f"Scripts: {result['scripts_count']} | Stylesheets: {result['stylesheets_count']}")
+
+
+if __name__ == "__main__":
+    main()

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

@@ -0,0 +1,202 @@
+#!/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()