bmad-plus 0.3.2 → 0.4.0

package/oveanet-pack/seo-audit-360/hooks/seo-check.sh

@@ -0,0 +1,95 @@
+#!/bin/bash
+# SEO Pre-Commit Hook — Catches common SEO issues before commit.
+# Install: cp hooks/seo-check.sh .git/hooks/pre-commit && chmod +x .git/hooks/pre-commit
+#
+# Author: Laurent Rochetta | BMAD+ SEO Engine
+
+ERRORS=0
+WARNINGS=0
+
+echo "🔎 BMAD+ SEO Pre-Commit Check..."
+
+# Only check staged HTML files
+HTML_FILES=$(git diff --cached --name-only --diff-filter=ACM | grep -iE '\.(html|htm|php|jsx|tsx)$')
+
+if [ -z "$HTML_FILES" ]; then
+    echo "  No HTML files staged, skipping SEO check."
+    exit 0
+fi
+
+for FILE in $HTML_FILES; do
+    # Skip node_modules and vendor
+    if echo "$FILE" | grep -qE '(node_modules|vendor|dist|build|\.min\.)'; then
+        continue
+    fi
+
+    CONTENT=$(git show ":$FILE" 2>/dev/null)
+    if [ -z "$CONTENT" ]; then
+        continue
+    fi
+
+    # Check 1: Missing <title> tag
+    if ! echo "$CONTENT" | grep -qi '<title'; then
+        echo "  🔴 $FILE — Missing <title> tag"
+        ERRORS=$((ERRORS + 1))
+    fi
+
+    # Check 2: Empty <title> tag
+    if echo "$CONTENT" | grep -qiE '<title>\s*</title>'; then
+        echo "  🔴 $FILE — Empty <title> tag"
+        ERRORS=$((ERRORS + 1))
+    fi
+
+    # Check 3: Missing meta description
+    if ! echo "$CONTENT" | grep -qi 'name="description"'; then
+        echo "  🟠 $FILE — Missing <meta name=\"description\">"
+        WARNINGS=$((WARNINGS + 1))
+    fi
+
+    # Check 4: Images without alt attribute
+    IMG_NO_ALT=$(echo "$CONTENT" | grep -ciE '<img[^>]*(?!alt)[^>]*>' 2>/dev/null || echo "0")
+    # More reliable: count <img> without alt
+    TOTAL_IMGS=$(echo "$CONTENT" | grep -ci '<img' 2>/dev/null || echo "0")
+    IMGS_WITH_ALT=$(echo "$CONTENT" | grep -ci '<img[^>]*alt=' 2>/dev/null || echo "0")
+    MISSING_ALT=$((TOTAL_IMGS - IMGS_WITH_ALT))
+
+    if [ "$MISSING_ALT" -gt 0 ]; then
+        echo "  🟠 $FILE — $MISSING_ALT image(s) without alt attribute"
+        WARNINGS=$((WARNINGS + 1))
+    fi
+
+    # Check 5: Multiple H1 tags
+    H1_COUNT=$(echo "$CONTENT" | grep -ci '<h1' 2>/dev/null || echo "0")
+    if [ "$H1_COUNT" -gt 1 ]; then
+        echo "  🟡 $FILE — Multiple H1 tags ($H1_COUNT found, should be 1)"
+        WARNINGS=$((WARNINGS + 1))
+    fi
+
+    # Check 6: No H1 tag at all
+    if [ "$H1_COUNT" -eq 0 ]; then
+        echo "  🟠 $FILE — No H1 tag found"
+        WARNINGS=$((WARNINGS + 1))
+    fi
+
+    # Check 7: "Click here" or "Learn more" anchor text
+    BAD_ANCHORS=$(echo "$CONTENT" | grep -ciE '>click here<|>learn more<|>read more<|>here<' 2>/dev/null || echo "0")
+    if [ "$BAD_ANCHORS" -gt 0 ]; then
+        echo "  🟡 $FILE — $BAD_ANCHORS link(s) with generic anchor text (\"click here\", \"learn more\")"
+        WARNINGS=$((WARNINGS + 1))
+    fi
+done
+
+echo ""
+echo "  Results: $ERRORS error(s), $WARNINGS warning(s)"
+
+if [ "$ERRORS" -gt 0 ]; then
+    echo "  ❌ Commit blocked — fix critical SEO issues first!"
+    exit 1
+else
+    if [ "$WARNINGS" -gt 0 ]; then
+        echo "  ⚠️ Commit allowed with warnings — consider fixing these issues."
+    else
+        echo "  ✅ All SEO checks passed!"
+    fi
+    exit 0
+fi

package/oveanet-pack/seo-audit-360/ref/audit-schema.json

@@ -0,0 +1,187 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "BMAD+ SEO Audit Result",
+  "description": "Standardized JSON format for SEO audit results. Compatible with dashboards, MCP Server, and external tools.",
+  "version": "1.0.0",
+  "author": "Laurent Rochetta",
+  "type": "object",
+  "required": ["engine", "version", "domain", "timestamp", "score", "issues"],
+  "properties": {
+    "engine": {
+      "type": "string",
+      "const": "bmad-seo-engine",
+      "description": "Engine identifier"
+    },
+    "version": {
+      "type": "string",
+      "description": "Engine version",
+      "examples": ["2.1.0"]
+    },
+    "domain": {
+      "type": "string",
+      "description": "Audited domain (without protocol)",
+      "examples": ["example.com"]
+    },
+    "url": {
+      "type": "string",
+      "format": "uri",
+      "description": "Full URL audited"
+    },
+    "timestamp": {
+      "type": "string",
+      "format": "date-time",
+      "description": "ISO 8601 timestamp of audit completion"
+    },
+    "business_type": {
+      "type": "string",
+      "enum": ["saas", "ecommerce", "local", "publisher", "agency", "other"],
+      "description": "Detected business type"
+    },
+    "pages_analyzed": {
+      "type": "integer",
+      "minimum": 1,
+      "description": "Number of pages analyzed"
+    },
+    "score": {
+      "type": "object",
+      "required": ["total", "categories"],
+      "properties": {
+        "total": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 100,
+          "description": "Weighted SEO Health Score"
+        },
+        "rating": {
+          "type": "string",
+          "enum": ["excellent", "good", "needs_work", "poor", "critical"],
+          "description": "Score interpretation"
+        },
+        "categories": {
+          "type": "object",
+          "properties": {
+            "technical": { "type": "integer", "minimum": 0, "maximum": 100 },
+            "content_eeat": { "type": "integer", "minimum": 0, "maximum": 100 },
+            "on_page": { "type": "integer", "minimum": 0, "maximum": 100 },
+            "schema": { "type": "integer", "minimum": 0, "maximum": 100 },
+            "performance": { "type": "integer", "minimum": 0, "maximum": 100 },
+            "ai_readiness": { "type": "integer", "minimum": 0, "maximum": 100 },
+            "images": { "type": "integer", "minimum": 0, "maximum": 100 }
+          },
+          "description": "Score per category (0-100)"
+        }
+      }
+    },
+    "issues": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["id", "severity", "category", "title"],
+        "properties": {
+          "id": {
+            "type": "string",
+            "description": "Unique issue identifier",
+            "examples": ["missing-meta-description", "multiple-h1"]
+          },
+          "severity": {
+            "type": "string",
+            "enum": ["critical", "high", "medium", "low"]
+          },
+          "category": {
+            "type": "string",
+            "enum": ["technical", "content", "on_page", "schema", "performance", "geo", "images"]
+          },
+          "title": {
+            "type": "string",
+            "description": "Human-readable issue title"
+          },
+          "description": {
+            "type": "string",
+            "description": "Detailed explanation"
+          },
+          "affected_urls": {
+            "type": "array",
+            "items": { "type": "string", "format": "uri" },
+            "description": "Pages affected by this issue"
+          },
+          "fix": {
+            "type": "string",
+            "description": "Auto-generated fix code (HTML, JSON-LD, etc.)"
+          },
+          "quick_win": {
+            "type": "boolean",
+            "description": "True if high impact / low effort"
+          },
+          "impact": {
+            "type": "string",
+            "enum": ["high", "medium", "low"]
+          },
+          "effort": {
+            "type": "string",
+            "enum": ["high", "medium", "low"]
+          }
+        }
+      }
+    },
+    "pages": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "url": { "type": "string", "format": "uri" },
+          "status": { "type": "integer" },
+          "title": { "type": "string" },
+          "word_count": { "type": "integer" },
+          "schema_types": { "type": "array", "items": { "type": "string" } },
+          "eeat_score": { "type": "integer", "minimum": 0, "maximum": 100 }
+        }
+      },
+      "description": "Per-page analysis data"
+    },
+    "geo": {
+      "type": "object",
+      "properties": {
+        "ai_readiness_score": { "type": "integer", "minimum": 0, "maximum": 100 },
+        "ai_crawlers_allowed": { "type": "array", "items": { "type": "string" } },
+        "has_llms_txt": { "type": "boolean" },
+        "citability_score": { "type": "integer", "minimum": 0, "maximum": 100 }
+      },
+      "description": "GEO / AI search readiness metrics"
+    },
+    "pagespeed": {
+      "type": "object",
+      "properties": {
+        "mobile": {
+          "type": "object",
+          "properties": {
+            "performance": { "type": "integer" },
+            "accessibility": { "type": "integer" },
+            "best_practices": { "type": "integer" },
+            "seo": { "type": "integer" }
+          }
+        },
+        "desktop": {
+          "type": "object",
+          "properties": {
+            "performance": { "type": "integer" },
+            "accessibility": { "type": "integer" },
+            "best_practices": { "type": "integer" },
+            "seo": { "type": "integer" }
+          }
+        }
+      },
+      "description": "PageSpeed Insights scores"
+    },
+    "monitoring": {
+      "type": "object",
+      "properties": {
+        "previous_score": { "type": "integer" },
+        "previous_date": { "type": "string", "format": "date" },
+        "delta": { "type": "integer" },
+        "issues_resolved": { "type": "integer" },
+        "issues_new": { "type": "integer" }
+      },
+      "description": "Comparison with previous audit (if available)"
+    }
+  }
+}

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

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

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

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

@@ -0,0 +1,121 @@
+"""
+Tests for seo_crawl.py — URL normalization, link extraction, depth limiting.
+
+Author: Laurent Rochetta
+"""
+
+import sys
+import os
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), "..", "scripts"))
+
+from seo_crawl import SEOCrawler
+
+
+class TestURLNormalization:
+    """Test URL normalization for deduplication."""
+
+    def setup_method(self):
+        self.crawler = SEOCrawler("https://example.com", max_depth=2, max_pages=25)
+
+    def test_strips_trailing_slash(self):
+        assert self.crawler.normalize_url("https://example.com/page/") == "https://example.com/page"
+
+    def test_preserves_root(self):
+        assert self.crawler.normalize_url("https://example.com/") == "https://example.com/"
+
+    def test_normalizes_scheme(self):
+        result = self.crawler.normalize_url("https://example.com/page")
+        assert result.startswith("https://")
+
+    def test_deduplicates(self):
+        url1 = self.crawler.normalize_url("https://example.com/page/")
+        url2 = self.crawler.normalize_url("https://example.com/page")
+        assert url1 == url2
+
+
+class TestInternalDetection:
+    def setup_method(self):
+        self.crawler = SEOCrawler("https://example.com", max_depth=2, max_pages=25)
+
+    def test_internal_url(self):
+        assert self.crawler.is_internal("https://example.com/about") is True
+
+    def test_external_url(self):
+        assert self.crawler.is_internal("https://other.com/page") is False
+
+    def test_subdomain_is_external(self):
+        assert self.crawler.is_internal("https://blog.example.com/post") is False
+
+
+class TestLinkExtraction:
+    def setup_method(self):
+        self.crawler = SEOCrawler("https://example.com", max_depth=2, max_pages=25)
+
+    def test_extracts_internal_links(self):
+        html = '''
+        <a href="/about">About</a>
+        <a href="https://example.com/contact">Contact</a>
+        '''
+        links = self.crawler.extract_links(html, "https://example.com/")
+        assert len(links) == 2
+
+    def test_ignores_external_links(self):
+        html = '<a href="https://other.com/page">External</a>'
+        links = self.crawler.extract_links(html, "https://example.com/")
+        assert len(links) == 0
+
+    def test_ignores_anchors(self):
+        html = '<a href="#section">Anchor</a>'
+        links = self.crawler.extract_links(html, "https://example.com/")
+        assert len(links) == 0
+
+    def test_ignores_javascript(self):
+        html = '<a href="javascript:void(0)">JS Link</a>'
+        links = self.crawler.extract_links(html, "https://example.com/")
+        assert len(links) == 0
+
+    def test_ignores_mailto(self):
+        html = '<a href="mailto:test@example.com">Email</a>'
+        links = self.crawler.extract_links(html, "https://example.com/")
+        assert len(links) == 0
+
+
+class TestTitleExtraction:
+    def setup_method(self):
+        self.crawler = SEOCrawler("https://example.com")
+
+    def test_extracts_title(self):
+        html = "<html><head><title>Test Page</title></head><body></body></html>"
+        assert self.crawler.extract_title(html) == "Test Page"
+
+    def test_missing_title(self):
+        html = "<html><body></body></html>"
+        assert self.crawler.extract_title(html) is None
+
+
+class TestWordCount:
+    def setup_method(self):
+        self.crawler = SEOCrawler("https://example.com")
+
+    def test_counts_visible_words(self):
+        html = "<html><body><p>This is a test with seven words.</p></body></html>"
+        assert self.crawler.count_words(html) == 7
+
+    def test_excludes_script_content(self):
+        html = '<html><body><p>Visible</p><script>var hidden = true;</script></body></html>'
+        count = self.crawler.count_words(html)
+        assert count == 1  # Only "Visible"
+
+
+class TestCrawlerConfig:
+    def test_max_pages_respected(self):
+        crawler = SEOCrawler("https://example.com", max_pages=5)
+        assert crawler.max_pages == 5
+
+    def test_max_depth_respected(self):
+        crawler = SEOCrawler("https://example.com", max_depth=1)
+        assert crawler.max_depth == 1
+
+    def test_base_domain_extracted(self):
+        crawler = SEOCrawler("https://www.example.com/page")
+        assert crawler.base_domain == "www.example.com"

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

@@ -0,0 +1,70 @@
+"""
+Tests for seo_fetch.py — SSRF protection, URL handling, error cases.
+
+Author: Laurent Rochetta
+"""
+
+import sys
+import os
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), "..", "scripts"))
+
+from seo_fetch import is_safe_url, fetch_page
+
+
+class TestSSRFProtection:
+    """Test SSRF prevention blocks private/loopback/reserved IPs."""
+
+    def test_blocks_localhost(self):
+        assert is_safe_url("http://127.0.0.1/admin") is False
+
+    def test_blocks_private_10(self):
+        assert is_safe_url("http://10.0.0.1/secret") is False
+
+    def test_blocks_private_192(self):
+        assert is_safe_url("http://192.168.1.1/") is False
+
+    def test_blocks_private_172(self):
+        assert is_safe_url("http://172.16.0.1/") is False
+
+    def test_allows_public_ip(self):
+        assert is_safe_url("https://93.184.216.34/") is True
+
+    def test_allows_public_domain(self):
+        assert is_safe_url("https://example.com/") is True
+
+    def test_blocks_empty_hostname(self):
+        assert is_safe_url("http:///nohost") is False
+
+    def test_blocks_zero_ip(self):
+        assert is_safe_url("http://0.0.0.0/") is False
+
+
+class TestFetchPage:
+    """Test fetch_page function behavior."""
+
+    def test_normalizes_url_without_scheme(self):
+        result = fetch_page("example.com", timeout=5)
+        assert result["url"] == "example.com"
+        # Should have attempted https://example.com
+
+    def test_blocks_invalid_scheme(self):
+        result = fetch_page("ftp://example.com/file")
+        assert result["error"] is not None
+        assert "Invalid URL scheme" in result["error"]
+
+    def test_blocks_ssrf(self):
+        result = fetch_page("http://127.0.0.1/admin")
+        assert result["error"] is not None
+        assert "Blocked" in result["error"]
+
+    def test_result_structure(self):
+        """Verify the result dict has all expected keys."""
+        result = fetch_page("https://example.com", timeout=5)
+        expected_keys = {"url", "final_url", "status_code", "content", "headers",
+                         "redirect_chain", "content_length", "response_time_ms", "error"}
+        assert expected_keys == set(result.keys())
+
+    def test_timeout_returns_error(self):
+        # Use a non-routable IP to force timeout
+        result = fetch_page("http://192.0.2.1/", timeout=1)
+        assert result["error"] is not None