bmad-plus 0.3.3 → 0.4.0

package/CHANGELOG.md

@@ -5,6 +5,22 @@ All notable changes to BMAD+ will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.4.0] — 2026-03-19
+
+### 🏢 SEO Engine — Enterprise Extensions (Sprint 4)
+
+### Added
+- **Google Search Console extension** — OAuth2 client for organic search data (queries, pages, coverage, sitemaps)
+- **Google Analytics 4 extension** — GA4 Data API client for organic traffic, landing pages, and engagement metrics
+- Both extensions include setup guides, Python clients, and separate requirements
+
+### Notes
+- Extensions are **optional** and require OAuth2 setup (see `EXTENSION.md` in each directory)
+- Core SEO Engine (SKILL.md + 3 agents + Python toolkit) works without extensions
+- GSC and GA4 share OAuth2 credentials for simplified auth flow
+
+---
+
 ## [0.3.3] — 2026-03-19
 
 ### 🧪 SEO Engine — Quality & Security (Sprint 3)

package/oveanet-pack/seo-audit-360/extensions/google-analytics/EXTENSION.md

@@ -0,0 +1,79 @@
+# Google Analytics 4 Extension — BMAD+ SEO Engine
+
+> Author: Laurent Rochetta | BMAD+ SEO Engine v2.1
+
+## Overview
+
+This extension connects to Google Analytics 4 (GA4) Data API for organic traffic analysis. Uses the same OAuth2 credentials as the Search Console extension.
+
+## Setup Guide
+
+### Prerequisites
+- Google Cloud project with **GA4 Data API** enabled
+- OAuth2 credentials (same `credentials.json` as GSC extension)
+- GA4 property ID (find in GA4 Admin > Property Settings)
+
+### First Run
+```bash
+python ga4_client.py --setup --property 123456789
+```
+
+## Commands
+
+```bash
+# Organic traffic overview
+python ga4_client.py --organic https://example.com --property 123456789 --days 30
+
+# Top organic landing pages
+python ga4_client.py --landing https://example.com --property 123456789 --days 30
+
+# Conversions from organic
+python ga4_client.py --conversions https://example.com --property 123456789 --days 30
+
+# Full export
+python ga4_client.py --all https://example.com --property 123456789 --json > ga4-data.json
+```
+
+## Output Examples
+
+### Organic Traffic
+```
+Organic Traffic (30 days):
+  Sessions:       12,450
+  Users:           8,230
+  New Users:       6,120
+  Engagement Rate: 72.3%
+  Avg Duration:    2m 45s
+  Bounce Rate:     36.1%
+```
+
+### Top Landing Pages
+```
+Top Organic Landing Pages:
+  1. /blog/ai-development    — 2,340 sessions, 78% engagement
+  2. /                        — 1,850 sessions, 65% engagement
+  3. /features               — 1,120 sessions, 82% engagement
+```
+
+## Integration with SEO Engine
+
+When installed, the SEO Engine can:
+- Correlate crawled pages with actual organic traffic
+- Identify high-traffic pages that need SEO optimization
+- Track organic conversion attribution
+- Detect pages with high impressions but low engagement (content quality issues)
+
+## Dependencies
+
+Same Google Auth libraries as GSC extension:
+```
+google-auth>=2.0.0
+google-auth-oauthlib>=1.0.0
+google-analytics-data>=0.18.0
+```
+
+## Security Notes
+
+- Uses same `credentials.json` and `token.json` as GSC extension
+- GA4 property ID is not sensitive but should be stored per-project
+- Add credentials to `.gitignore`

package/oveanet-pack/seo-audit-360/extensions/google-analytics/ga4_client.py

@@ -0,0 +1,200 @@
+#!/usr/bin/env python3
+"""
+Google Analytics 4 Client — GA4 Data API client for organic traffic analysis.
+
+Features:
+- Organic traffic metrics (sessions, users, engagement)
+- Landing page performance
+- Conversion attribution
+- Custom date ranges
+
+Author: Laurent Rochetta
+License: MIT
+"""
+
+import argparse
+import json
+import os
+import sys
+from datetime import datetime, timedelta
+
+SCOPES = ["https://www.googleapis.com/auth/analytics.readonly"]
+CREDENTIALS_FILE = os.path.join(os.path.dirname(__file__), "..", "google-search-console", "credentials.json")
+TOKEN_FILE = os.path.join(os.path.dirname(__file__), "..", "google-search-console", "token.json")
+
+
+def get_client(property_id: str):
+    """Authenticate and return a GA4 BetaAnalyticsData client."""
+    try:
+        from google.oauth2.credentials import Credentials
+        from google_auth_oauthlib.flow import InstalledAppFlow
+        from google.auth.transport.requests import Request
+        from google.analytics.data_v1beta import BetaAnalyticsDataClient
+        from google.analytics.data_v1beta.types import (
+            DateRange, Dimension, Metric, RunReportRequest, FilterExpression,
+            Filter,
+        )
+    except ImportError:
+        print(
+            "Error: Missing dependencies. Install:\n"
+            "  pip install google-auth google-auth-oauthlib google-analytics-data",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+
+    creds = None
+    if os.path.exists(TOKEN_FILE):
+        creds = Credentials.from_authorized_user_file(TOKEN_FILE, SCOPES)
+
+    if not creds or not creds.valid:
+        if creds and creds.expired and creds.refresh_token:
+            creds.refresh(Request())
+        else:
+            if not os.path.exists(CREDENTIALS_FILE):
+                print(f"Error: credentials.json not found. See EXTENSION.md for setup.", file=sys.stderr)
+                sys.exit(1)
+            flow = InstalledAppFlow.from_client_secrets_file(CREDENTIALS_FILE, SCOPES)
+            creds = flow.run_local_server(port=0)
+
+        with open(TOKEN_FILE, "w") as f:
+            f.write(creds.to_json())
+
+    return BetaAnalyticsDataClient(credentials=creds), property_id
+
+
+def run_organic_report(client, property_id: str, days: int = 30) -> dict:
+    """Get organic traffic overview."""
+    from google.analytics.data_v1beta.types import (
+        DateRange, Metric, RunReportRequest, FilterExpression, Filter,
+    )
+
+    end_date = datetime.now().date()
+    start_date = end_date - timedelta(days=days)
+
+    request = RunReportRequest(
+        property=f"properties/{property_id}",
+        date_ranges=[DateRange(start_date=start_date.isoformat(), end_date=end_date.isoformat())],
+        metrics=[
+            Metric(name="sessions"),
+            Metric(name="totalUsers"),
+            Metric(name="newUsers"),
+            Metric(name="engagementRate"),
+            Metric(name="averageSessionDuration"),
+            Metric(name="bounceRate"),
+        ],
+        dimension_filter=FilterExpression(
+            filter=Filter(
+                field_name="sessionDefaultChannelGroup",
+                string_filter=Filter.StringFilter(value="Organic Search"),
+            )
+        ),
+    )
+
+    response = client.run_report(request)
+
+    if not response.rows:
+        return {"error": "No organic data available for this period"}
+
+    row = response.rows[0]
+    return {
+        "sessions": int(row.metric_values[0].value),
+        "users": int(row.metric_values[1].value),
+        "new_users": int(row.metric_values[2].value),
+        "engagement_rate": round(float(row.metric_values[3].value) * 100, 1),
+        "avg_duration_seconds": round(float(row.metric_values[4].value)),
+        "bounce_rate": round(float(row.metric_values[5].value) * 100, 1),
+    }
+
+
+def run_landing_page_report(client, property_id: str, days: int = 30, limit: int = 20) -> list:
+    """Get top organic landing pages."""
+    from google.analytics.data_v1beta.types import (
+        DateRange, Dimension, Metric, RunReportRequest, FilterExpression, Filter,
+        OrderBy,
+    )
+
+    end_date = datetime.now().date()
+    start_date = end_date - timedelta(days=days)
+
+    request = RunReportRequest(
+        property=f"properties/{property_id}",
+        date_ranges=[DateRange(start_date=start_date.isoformat(), end_date=end_date.isoformat())],
+        dimensions=[Dimension(name="landingPage")],
+        metrics=[
+            Metric(name="sessions"),
+            Metric(name="engagementRate"),
+            Metric(name="averageSessionDuration"),
+        ],
+        dimension_filter=FilterExpression(
+            filter=Filter(
+                field_name="sessionDefaultChannelGroup",
+                string_filter=Filter.StringFilter(value="Organic Search"),
+            )
+        ),
+        order_bys=[OrderBy(metric=OrderBy.MetricOrderBy(metric_name="sessions"), desc=True)],
+        limit=limit,
+    )
+
+    response = client.run_report(request)
+
+    return [{
+        "page": row.dimension_values[0].value,
+        "sessions": int(row.metric_values[0].value),
+        "engagement_rate": round(float(row.metric_values[1].value) * 100, 1),
+        "avg_duration": round(float(row.metric_values[2].value)),
+    } for row in response.rows]
+
+
+# ── CLI ────────────────────────────────────────────────────────────
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Google Analytics 4 Client (BMAD+ SEO Engine)"
+    )
+    parser.add_argument("--property", "-p", required=True, help="GA4 Property ID")
+    parser.add_argument("--organic", action="store_true", help="Organic traffic overview")
+    parser.add_argument("--landing", action="store_true", help="Top landing pages")
+    parser.add_argument("--all", action="store_true", help="All reports")
+    parser.add_argument("--days", type=int, default=30, help="Days lookback (default: 30)")
+    parser.add_argument("--limit", type=int, default=20, help="Max rows (default: 20)")
+    parser.add_argument("--json", "-j", action="store_true", help="Output as JSON")
+    parser.add_argument("--setup", action="store_true", help="Run OAuth2 setup")
+
+    args = parser.parse_args()
+
+    client, property_id = get_client(args.property)
+
+    if args.setup:
+        print("✅ OAuth2 setup complete for GA4.")
+        return
+
+    if args.organic or args.all:
+        data = run_organic_report(client, property_id, args.days)
+        if args.json:
+            print(json.dumps({"organic": data}, indent=2))
+        else:
+            print(f"\nOrganic Traffic ({args.days} days):")
+            if "error" in data:
+                print(f"  {data['error']}")
+            else:
+                mins = data["avg_duration_seconds"] // 60
+                secs = data["avg_duration_seconds"] % 60
+                print(f"  Sessions:       {data['sessions']:,}")
+                print(f"  Users:          {data['users']:,}")
+                print(f"  New Users:      {data['new_users']:,}")
+                print(f"  Engagement:     {data['engagement_rate']}%")
+                print(f"  Avg Duration:   {mins}m {secs}s")
+                print(f"  Bounce Rate:    {data['bounce_rate']}%")
+
+    if args.landing or args.all:
+        pages = run_landing_page_report(client, property_id, args.days, args.limit)
+        if args.json:
+            print(json.dumps({"landing_pages": pages}, indent=2))
+        else:
+            print(f"\nTop Organic Landing Pages:")
+            for i, p in enumerate(pages, 1):
+                print(f"  {i:2}. {p['page'][:55]} — {p['sessions']:,} sessions, {p['engagement_rate']}% engagement")
+
+
+if __name__ == "__main__":
+    main()

package/oveanet-pack/seo-audit-360/extensions/google-analytics/requirements.txt

@@ -0,0 +1,4 @@
+# Google Analytics 4 Extension — Dependencies
+google-auth>=2.0.0
+google-auth-oauthlib>=1.0.0
+google-analytics-data>=0.18.0

package/oveanet-pack/seo-audit-360/extensions/google-search-console/EXTENSION.md

@@ -0,0 +1,109 @@
+# Google Search Console Extension — BMAD+ SEO Engine
+
+> Author: Laurent Rochetta | BMAD+ SEO Engine v2.1
+
+## Overview
+
+This extension connects the SEO Engine to Google Search Console API v3 for accessing real organic search performance data. Requires OAuth2 authentication with a Google Cloud project.
+
+## Setup Guide
+
+### 1. Create Google Cloud Project
+1. Go to [Google Cloud Console](https://console.cloud.google.com)
+2. Create a new project or select existing
+3. Enable **Google Search Console API**
+
+### 2. Create OAuth2 Credentials
+1. Go to **APIs & Services > Credentials**
+2. Click **Create Credentials > OAuth 2.0 Client ID**
+3. Application type: **Desktop app**
+4. Download the JSON → save as `credentials.json` in this directory
+
+### 3. First Run
+```bash
+python gsc_client.py --setup
+```
+This opens a browser for OAuth consent. The refresh token is saved to `token.json` for subsequent runs.
+
+### 4. Verify Access
+```bash
+python gsc_client.py --sites
+```
+Should list all verified Search Console properties.
+
+## Commands
+
+```bash
+# List verified sites
+python gsc_client.py --sites
+
+# Top queries (default: 28 days)
+python gsc_client.py --queries https://example.com --days 28
+
+# Top pages by organic traffic
+python gsc_client.py --pages https://example.com --days 28
+
+# Index coverage (errors, valid, excluded)
+python gsc_client.py --coverage https://example.com
+
+# Sitemap status
+python gsc_client.py --sitemaps https://example.com
+
+# Full export (all data, JSON)
+python gsc_client.py --all https://example.com --json > gsc-data.json
+```
+
+## Output Examples
+
+### Queries
+```
+Top Organic Queries (28 days):
+  1. "bmad framework"      — Pos: 3.2, Clicks: 450, CTR: 12.3%, Imp: 3,658
+  2. "ai development tool"  — Pos: 8.1, Clicks: 120, CTR:  3.5%, Imp: 3,428
+  3. "multi-agent coding"   — Pos: 5.4, Clicks:  95, CTR:  7.8%, Imp: 1,218
+```
+
+### Coverage
+```
+Index Coverage:
+  ✅ Valid: 142 pages
+  ⚠️ Valid with warnings: 8 pages
+  ❌ Error: 3 pages
+  ⛔ Excluded: 45 pages (noindex, canonical, etc.)
+```
+
+## Integration with SEO Engine
+
+When this extension is installed, the SKILL.md orchestrator can:
+- Include real organic data in Phase 4 scoring
+- Compare GSC impressions with crawled pages to find content gaps
+- Detect indexed pages with declining CTR → priority optimization targets
+- Cross-reference sitemap URLs with actually indexed pages
+
+## Files
+
+| File | Purpose |
+|------|---------|
+| `EXTENSION.md` | This documentation |
+| `gsc_client.py` | OAuth2 flow + API calls |
+| `requirements.txt` | Python dependencies |
+
+## Dependencies SUPPLÉMENTAIRES
+
+```
+google-auth>=2.0.0
+google-auth-oauthlib>=1.0.0
+google-api-python-client>=2.0.0
+```
+
+## Security Notes
+
+- `credentials.json` — Contains client ID/secret. **Do not commit to Git.**
+- `token.json` — Contains refresh token. **Do not commit to Git.**
+- Add both to `.gitignore`
+
+## Rate Limits
+
+- 1,200 queries per minute per project
+- 25,000 rows per request maximum
+- Data typically 2-3 days delayed

package/oveanet-pack/seo-audit-360/extensions/google-search-console/gsc_client.py

@@ -0,0 +1,186 @@
+#!/usr/bin/env python3
+"""
+Google Search Console Client — OAuth2 API client for organic search data.
+
+Features:
+- OAuth2 flow with credential persistence
+- Query performance data (queries, pages, devices, countries)
+- Index coverage status
+- Sitemap submissions
+
+Author: Laurent Rochetta
+License: MIT
+"""
+
+import argparse
+import json
+import os
+import sys
+from datetime import datetime, timedelta
+
+SCOPES = ["https://www.googleapis.com/auth/webmasters.readonly"]
+CREDENTIALS_FILE = os.path.join(os.path.dirname(__file__), "credentials.json")
+TOKEN_FILE = os.path.join(os.path.dirname(__file__), "token.json")
+
+
+def get_service():
+    """Authenticate and return a Search Console service object."""
+    try:
+        from google.oauth2.credentials import Credentials
+        from google_auth_oauthlib.flow import InstalledAppFlow
+        from googleapiclient.discovery import build
+        from google.auth.transport.requests import Request
+    except ImportError:
+        print(
+            "Error: Missing dependencies. Install:\n"
+            "  pip install google-auth google-auth-oauthlib google-api-python-client",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+
+    creds = None
+    if os.path.exists(TOKEN_FILE):
+        creds = Credentials.from_authorized_user_file(TOKEN_FILE, SCOPES)
+
+    if not creds or not creds.valid:
+        if creds and creds.expired and creds.refresh_token:
+            creds.refresh(Request())
+        else:
+            if not os.path.exists(CREDENTIALS_FILE):
+                print(
+                    f"Error: {CREDENTIALS_FILE} not found.\n"
+                    "Download OAuth2 credentials from Google Cloud Console.\n"
+                    "See EXTENSION.md for setup guide.",
+                    file=sys.stderr,
+                )
+                sys.exit(1)
+            flow = InstalledAppFlow.from_client_secrets_file(CREDENTIALS_FILE, SCOPES)
+            creds = flow.run_local_server(port=0)
+
+        with open(TOKEN_FILE, "w") as f:
+            f.write(creds.to_json())
+
+    return build("searchconsole", "v1", credentials=creds)
+
+
+def list_sites(service):
+    """List all verified Search Console properties."""
+    result = service.sites().list().execute()
+    sites = result.get("siteEntry", [])
+    return [{"url": s["siteUrl"], "level": s["permissionLevel"]} for s in sites]
+
+
+def query_performance(service, site_url: str, days: int = 28, dimensions: list = None, row_limit: int = 25):
+    """Query Search Analytics for organic performance data."""
+    if dimensions is None:
+        dimensions = ["query"]
+
+    end_date = datetime.now().date()
+    start_date = end_date - timedelta(days=days)
+
+    body = {
+        "startDate": start_date.isoformat(),
+        "endDate": end_date.isoformat(),
+        "dimensions": dimensions,
+        "rowLimit": row_limit,
+        "dataState": "all",
+    }
+
+    result = service.searchanalytics().query(siteUrl=site_url, body=body).execute()
+    rows = result.get("rows", [])
+
+    return [{
+        "keys": row["keys"],
+        "clicks": row["clicks"],
+        "impressions": row["impressions"],
+        "ctr": round(row["ctr"] * 100, 1),
+        "position": round(row["position"], 1),
+    } for row in rows]
+
+
+def get_sitemaps(service, site_url: str):
+    """Get sitemap submission status."""
+    result = service.sitemaps().list(siteUrl=site_url).execute()
+    sitemaps = result.get("sitemap", [])
+    return [{
+        "path": s["path"],
+        "type": s.get("type", ""),
+        "submitted": s.get("lastSubmitted", ""),
+        "warnings": s.get("warnings", 0),
+        "errors": s.get("errors", 0),
+    } for s in sitemaps]
+
+
+# ── CLI ────────────────────────────────────────────────────────────
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Google Search Console Client (BMAD+ SEO Engine)"
+    )
+    parser.add_argument("site", nargs="?", help="Site URL (e.g. https://example.com)")
+    parser.add_argument("--setup", action="store_true", help="Run OAuth2 setup flow")
+    parser.add_argument("--sites", action="store_true", help="List verified sites")
+    parser.add_argument("--queries", action="store_true", help="Top queries")
+    parser.add_argument("--pages", action="store_true", help="Top pages")
+    parser.add_argument("--sitemaps", action="store_true", help="Sitemap status")
+    parser.add_argument("--all", action="store_true", help="All data")
+    parser.add_argument("--days", type=int, default=28, help="Days lookback (default: 28)")
+    parser.add_argument("--limit", type=int, default=25, help="Max rows (default: 25)")
+    parser.add_argument("--json", "-j", action="store_true", help="Output as JSON")
+
+    args = parser.parse_args()
+
+    service = get_service()
+
+    if args.setup:
+        print("✅ OAuth2 setup complete. Token saved.")
+        return
+
+    if args.sites:
+        sites = list_sites(service)
+        if args.json:
+            print(json.dumps(sites, indent=2))
+        else:
+            print("\nVerified Sites:")
+            for s in sites:
+                print(f"  {s['url']} ({s['level']})")
+        return
+
+    if not args.site:
+        parser.print_help()
+        return
+
+    if args.queries or args.all:
+        data = query_performance(service, args.site, args.days, ["query"], args.limit)
+        if args.json:
+            print(json.dumps({"queries": data}, indent=2))
+        else:
+            print(f"\nTop Queries ({args.days} days):")
+            for i, row in enumerate(data, 1):
+                q = row["keys"][0]
+                print(f"  {i:2}. \"{q[:50]}\" — Pos: {row['position']}, "
+                      f"Clicks: {row['clicks']:,}, CTR: {row['ctr']}%, Imp: {row['impressions']:,}")
+
+    if args.pages or args.all:
+        data = query_performance(service, args.site, args.days, ["page"], args.limit)
+        if args.json:
+            print(json.dumps({"pages": data}, indent=2))
+        else:
+            print(f"\nTop Pages ({args.days} days):")
+            for i, row in enumerate(data, 1):
+                page = row["keys"][0]
+                print(f"  {i:2}. {page[:60]} — Clicks: {row['clicks']:,}, CTR: {row['ctr']}%")
+
+    if args.sitemaps or args.all:
+        data = get_sitemaps(service, args.site)
+        if args.json:
+            print(json.dumps({"sitemaps": data}, indent=2))
+        else:
+            print(f"\nSitemaps:")
+            for s in data:
+                status = "✅" if s["errors"] == 0 else "❌"
+                print(f"  {status} {s['path']} (type: {s['type']}, errors: {s['errors']})")
+
+
+if __name__ == "__main__":
+    main()

package/oveanet-pack/seo-audit-360/extensions/google-search-console/requirements.txt

@@ -0,0 +1,4 @@
+# Google Search Console Extension — Dependencies
+google-auth>=2.0.0
+google-auth-oauthlib>=1.0.0
+google-api-python-client>=2.0.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "bmad-plus",
-  "version": "0.3.3",
+  "version": "0.4.0",
   "description": "BMAD+ — Augmented AI-Driven Development Framework with multi-role agents, autopilot, and parallel execution",
   "keywords": [
     "bmad",