antigravity-seo-kit 2.0.0

package/.agent/skills/seo/scripts/capture_screenshot.py

@@ -0,0 +1,181 @@
+#!/usr/bin/env python3
+"""
+Capture screenshots of web pages using Playwright.
+
+Usage:
+    python capture_screenshot.py https://example.com
+    python capture_screenshot.py https://example.com --mobile
+    python capture_screenshot.py https://example.com --output screenshots/
+"""
+
+import argparse
+import ipaddress
+import os
+import socket
+import sys
+from urllib.parse import ParseResult, urlparse
+
+try:
+    from playwright.sync_api import sync_playwright, TimeoutError as PlaywrightTimeout
+except ImportError:
+    print("Error: playwright required. Install with: pip install playwright && playwright install chromium")
+    sys.exit(1)
+
+
+VIEWPORTS = {
+    "desktop": {"width": 1920, "height": 1080},
+    "laptop": {"width": 1366, "height": 768},
+    "tablet": {"width": 768, "height": 1024},
+    "mobile": {"width": 375, "height": 812},
+}
+
+
+def normalize_url(url: str) -> tuple[str, ParseResult]:
+    """Normalize URL and return (url, parsed_url)."""
+    parsed = urlparse(url)
+    if not parsed.scheme:
+        url = f"https://{url}"
+        parsed = urlparse(url)
+
+    if parsed.scheme not in ("http", "https"):
+        raise ValueError(f"Invalid URL scheme: {parsed.scheme}")
+    if not parsed.hostname:
+        raise ValueError("Invalid URL: missing hostname")
+
+    return url, parsed
+
+
+def capture_screenshot(
+    url: str,
+    output_path: str,
+    viewport: str = "desktop",
+    full_page: bool = False,
+    timeout: int = 30000,
+) -> dict:
+    """
+    Capture a screenshot of a web page.
+
+    Args:
+        url: URL to capture
+        output_path: Output file path
+        viewport: Viewport preset (desktop, laptop, tablet, mobile)
+        full_page: Whether to capture full page or just viewport
+        timeout: Page load timeout in milliseconds
+
+    Returns:
+        Dictionary with capture results
+    """
+    result = {
+        "url": url,
+        "output": output_path,
+        "viewport": viewport,
+        "success": False,
+        "error": None,
+    }
+
+    if viewport not in VIEWPORTS:
+        result["error"] = f"Invalid viewport: {viewport}. Choose from: {list(VIEWPORTS.keys())}"
+        return result
+
+    try:
+        url, parsed = normalize_url(url)
+        result["url"] = url
+    except ValueError as e:
+        result["error"] = str(e)
+        return result
+
+    # SSRF prevention: block private/internal IPs
+    try:
+        resolved_ip = socket.gethostbyname(parsed.hostname)
+        ip = ipaddress.ip_address(resolved_ip)
+        if ip.is_private or ip.is_loopback or ip.is_reserved:
+            result["error"] = f"Blocked: URL resolves to private/internal IP ({resolved_ip})"
+            return result
+    except socket.gaierror:
+        pass
+
+    vp = VIEWPORTS[viewport]
+
+    try:
+        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=2 if viewport == "mobile" else 1,
+            )
+            page = context.new_page()
+
+            # Navigate and wait for network idle
+            page.goto(url, wait_until="networkidle", timeout=timeout)
+
+            # Wait a bit more for any lazy-loaded content
+            page.wait_for_timeout(1000)
+
+            # Capture screenshot
+            page.screenshot(path=output_path, full_page=full_page)
+
+            result["success"] = True
+            browser.close()
+
+    except PlaywrightTimeout:
+        result["error"] = f"Page load timed out after {timeout}ms"
+    except Exception as e:
+        result["error"] = str(e)
+
+    return result
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Capture web page screenshots")
+    parser.add_argument("url", help="URL to capture")
+    parser.add_argument("--output", "-o", default="screenshots", help="Output directory")
+    parser.add_argument("--viewport", "-v", default="desktop", choices=VIEWPORTS.keys())
+    parser.add_argument("--all", "-a", action="store_true", help="Capture all viewports")
+    parser.add_argument("--full", "-f", action="store_true", help="Capture full page")
+    parser.add_argument("--timeout", "-t", type=int, default=30000, help="Timeout in ms")
+
+    args = parser.parse_args()
+
+    # Sanitize output path - prevent directory traversal
+    output_dir = os.path.realpath(args.output)
+    cwd = os.getcwd()
+    home = os.path.expanduser("~")
+    if not (output_dir.startswith(cwd) or output_dir.startswith(home)):
+        print("Error: Output path must be within current directory or home directory", file=sys.stderr)
+        sys.exit(1)
+
+    # Create output directory
+    os.makedirs(args.output, exist_ok=True)
+
+    try:
+        normalized_url, parsed_url = normalize_url(args.url)
+    except ValueError as e:
+        print(f"Error: {e}", file=sys.stderr)
+        sys.exit(1)
+
+    # Generate filename from URL
+    base_name = parsed_url.netloc.replace(".", "_")
+
+    viewports = VIEWPORTS.keys() if args.all else [args.viewport]
+
+    for viewport in viewports:
+        filename = f"{base_name}_{viewport}.png"
+        output_path = os.path.join(args.output, filename)
+
+        print(f"Capturing {viewport} screenshot...")
+        result = capture_screenshot(
+            normalized_url,
+            output_path,
+            viewport=viewport,
+            full_page=args.full,
+            timeout=args.timeout,
+        )
+
+        if result["success"]:
+            print(f"  ✓ Saved to {output_path}")
+        else:
+            print(f"  ✗ Failed: {result['error']}")
+
+
+if __name__ == "__main__":
+    main()

package/.agent/skills/seo/scripts/fetch_page.py

@@ -0,0 +1,196 @@
+#!/usr/bin/env python3
+"""
+Fetch a web page with proper headers and error handling.
+
+Usage:
+    python fetch_page.py https://example.com
+    python fetch_page.py https://example.com --output page.html
+"""
+
+import argparse
+import ipaddress
+import socket
+import sys
+from typing import Optional
+from urllib.parse import urlparse
+
+try:
+    import requests
+except ImportError:
+    print("Error: requests library required. Install with: pip install requests")
+    sys.exit(1)
+
+
+DEFAULT_USER_AGENT = (
+    "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 "
+    "(KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36 ClaudeSEO/1.2"
+)
+
+# Googlebot UA for prerender/dynamic rendering detection.
+# Prerender services (Prerender.io, Rendertron) serve fully rendered HTML to
+# Googlebot but raw JS shells to other UAs. Comparing response sizes between
+# DEFAULT_USER_AGENT and GOOGLEBOT_USER_AGENT reveals whether a site uses
+# dynamic rendering, a key signal for SPA detection.
+GOOGLEBOT_USER_AGENT = (
+    "Mozilla/5.0 (compatible; Googlebot/2.1; +http://www.google.com/bot.html)"
+)
+
+DEFAULT_HEADERS = {
+    "User-Agent": DEFAULT_USER_AGENT,
+    "Accept": "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8",
+    "Accept-Language": "en-US,en;q=0.5",
+    "Accept-Encoding": "gzip, deflate",
+    "Connection": "keep-alive",
+}
+
+
+def fetch_page(
+    url: str,
+    timeout: int = 30,
+    follow_redirects: bool = True,
+    max_redirects: int = 5,
+    user_agent: Optional[str] = None,
+) -> dict:
+    """
+    Fetch a web page and return response details.
+
+    Args:
+        url: The URL to fetch
+        timeout: Request timeout in seconds
+        follow_redirects: Whether to follow redirects
+        max_redirects: Maximum number of redirects to follow
+
+    Returns:
+        Dictionary with:
+            - url: Final URL after redirects
+            - status_code: HTTP status code
+            - content: Response body
+            - headers: Response headers
+            - redirect_chain: List of redirect URLs
+            - error: Error message if failed
+    """
+    result = {
+        "url": url,
+        "status_code": None,
+        "content": None,
+        "headers": {},
+        "redirect_chain": [],
+        "redirect_details": [],
+        "error": None,
+    }
+
+    # Validate 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 prevention: block private/internal IPs
+    try:
+        resolved_ip = socket.gethostbyname(parsed.hostname)
+        ip = ipaddress.ip_address(resolved_ip)
+        if ip.is_private or ip.is_loopback or ip.is_reserved:
+            result["error"] = f"Blocked: URL resolves to private/internal IP ({resolved_ip})"
+            return result
+    except (socket.gaierror, ValueError):
+        pass  # DNS resolution failure handled by requests below
+
+    try:
+        session = requests.Session()
+        session.max_redirects = max_redirects
+
+        headers = dict(DEFAULT_HEADERS)
+        if user_agent:
+            headers["User-Agent"] = user_agent
+
+        response = session.get(
+            url,
+            headers=headers,
+            timeout=timeout,
+            allow_redirects=follow_redirects,
+        )
+
+        result["url"] = response.url
+        result["status_code"] = response.status_code
+        result["content"] = response.text
+        result["headers"] = dict(response.headers)
+
+        # Track redirect chain with status codes
+        if response.history:
+            result["redirect_chain"] = [r.url for r in response.history]
+            result["redirect_details"] = [
+                {"url": r.url, "status_code": r.status_code}
+                for r in response.history
+            ]
+
+    except requests.exceptions.Timeout:
+        result["error"] = f"Request timed out after {timeout} seconds"
+    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
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Fetch a web page for SEO analysis")
+    parser.add_argument("url", help="URL to fetch")
+    parser.add_argument("--output", "-o", help="Output file path")
+    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("--user-agent", help="Custom User-Agent string")
+    parser.add_argument(
+        "--googlebot",
+        action="store_true",
+        help=(
+            "Use Googlebot UA to detect dynamic rendering / prerender services. "
+            "Compare response size with default UA to identify SPA prerender configuration."
+        ),
+    )
+
+    args = parser.parse_args()
+
+    ua = args.user_agent
+    if args.googlebot:
+        ua = GOOGLEBOT_USER_AGENT
+
+    result = fetch_page(
+        args.url,
+        timeout=args.timeout,
+        follow_redirects=not args.no_redirects,
+        user_agent=ua,
+    )
+
+    if result["error"]:
+        print(f"Error: {result['error']}", file=sys.stderr)
+        sys.exit(1)
+
+    if 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"])
+
+    # Print metadata to stderr
+    print(f"\nURL: {result['url']}", file=sys.stderr)
+    print(f"Status: {result['status_code']}", file=sys.stderr)
+    if result["redirect_details"]:
+        for rd in result["redirect_details"]:
+            print(f"  {rd['status_code']} -> {rd['url']}", file=sys.stderr)
+        print(f"  {result['status_code']} -> {result['url']} (final)", file=sys.stderr)
+    elif result["redirect_chain"]:
+        print(f"Redirects: {' -> '.join(result['redirect_chain'])}", file=sys.stderr)
+
+
+if __name__ == "__main__":
+    main()

package/.agent/skills/seo/scripts/parse_html.py

@@ -0,0 +1,201 @@
+#!/usr/bin/env python3
+"""
+Parse HTML and extract SEO-relevant elements.
+
+Usage:
+    python parse_html.py page.html
+    python parse_html.py --url https://example.com
+"""
+
+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 with: pip install beautifulsoup4")
+    sys.exit(1)
+
+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 SEO-relevant elements.
+
+    Args:
+        html: HTML content to parse
+        base_url: Base URL for resolving relative links
+
+    Returns:
+        Dictionary with extracted SEO data
+    """
+    soup = BeautifulSoup(html, _HTML_PARSER)
+
+    result = {
+        "title": None,
+        "meta_description": None,
+        "meta_robots": None,
+        "canonical": None,
+        "h1": [],
+        "h2": [],
+        "h3": [],
+        "images": [],
+        "links": {
+            "internal": [],
+            "external": [],
+        },
+        "schema": [],
+        "open_graph": {},
+        "twitter_card": {},
+        "word_count": 0,
+        "hreflang": [],
+    }
+
+    # Title
+    title_tag = soup.find("title")
+    if title_tag:
+        result["title"] = title_tag.get_text(strip=True)
+
+    # Meta tags
+    for meta in soup.find_all("meta"):
+        name = meta.get("name", "").lower()
+        property_attr = meta.get("property", "").lower()
+        content = meta.get("content", "")
+
+        if name == "description":
+            result["meta_description"] = content
+        elif name == "robots":
+            result["meta_robots"] = 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
+
+    # 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 tag in ["h1", "h2", "h3"]:
+        for heading in soup.find_all(tag):
+            text = heading.get_text(strip=True)
+            if text:
+                result[tag].append(text)
+
+    # Images
+    for img in soup.find_all("img"):
+        src = img.get("src", "")
+        if base_url and src:
+            src = urljoin(base_url, src)
+
+        result["images"].append({
+            "src": src,
+            "alt": img.get("alt"),
+            "width": img.get("width"),
+            "height": img.get("height"),
+            "loading": img.get("loading"),
+        })
+
+    # 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", []),
+            }
+
+            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)
+            result["schema"].append(schema_data)
+        except (json.JSONDecodeError, TypeError):
+            pass
+
+    # Word count (visible text only)
+    for element in soup(["script", "style", "nav", "footer", "header"]):
+        element.decompose()
+
+    text = soup.get_text(separator=" ", strip=True)
+    words = re.findall(r"\b\w+\b", text)
+    result["word_count"] = len(words)
+
+    return result
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Parse HTML for SEO analysis")
+    parser.add_argument("file", nargs="?", help="HTML file to parse")
+    parser.add_argument("--url", "-u", help="Base URL for resolving 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))
+    else:
+        print(f"Title: {result['title']}")
+        print(f"Meta Description: {result['meta_description']}")
+        print(f"Canonical: {result['canonical']}")
+        print(f"H1 Tags: {len(result['h1'])}")
+        print(f"H2 Tags: {len(result['h2'])}")
+        print(f"Images: {len(result['images'])}")
+        print(f"Internal Links: {len(result['links']['internal'])}")
+        print(f"External Links: {len(result['links']['external'])}")
+        print(f"Schema Blocks: {len(result['schema'])}")
+        print(f"Word Count: {result['word_count']}")
+
+
+if __name__ == "__main__":
+    main()