@topy-ai/maggie 0.7.47 → 0.7.49

package/bundled-tools/runtime/google_ads.py

@@ -0,0 +1,306 @@
+"""Read-only Google Ads preflight and Keyword Planner adapter.
+
+Every request goes through an injectable transport so tests run offline. The
+default transport uses urllib and is only exercised when an operator runs the
+CLI with credentials. The adapter refuses any request that is not one of the
+three read-only calls below, so it cannot mutate Ads state.
+
+Credential values are read from environment variables named by the caller and
+are never returned, logged, or written to a report.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import urllib.error
+import urllib.parse
+import urllib.request
+from typing import Any, Callable
+
+from google_remediation import classify
+
+
+ADS_SCOPE = "https://www.googleapis.com/auth/adwords"
+ADS_HOST = "googleads.googleapis.com"
+TOKENINFO_URL = "https://oauth2.googleapis.com/tokeninfo"
+DEFAULT_API_VERSION = os.environ.get("MAGGIE_GOOGLE_ADS_API_VERSION", "v21")
+COMPETITION = {"UNSPECIFIED": "unknown", "UNKNOWN": "unknown", "LOW": "low", "MEDIUM": "medium", "HIGH": "high"}
+
+# (method, path regex relative to https://googleads.googleapis.com/<version>/)
+READ_ONLY_ROUTES = (
+    ("GET", r"customers:listAccessibleCustomers"),
+    ("POST", r"customers/\d{10}/googleAds:search"),
+    ("POST", r"customers/\d{10}:generateKeywordIdeas"),
+)
+
+Transport = Callable[[str, str, dict[str, str], Any], tuple[int, Any]]
+
+
+class AdsRequestRefused(ValueError):
+    """Raised when a request is not on the read-only allowlist."""
+
+
+def normalize_customer_id(value: Any) -> str | None:
+    """Return a 10-digit customer ID without hyphens, or None when invalid."""
+    if not isinstance(value, str):
+        return None
+    digits = value.replace("-", "").strip()
+    return digits if re.fullmatch(r"\d{10}", digits) else None
+
+
+def urllib_transport(method: str, url: str, headers: dict[str, str], body: Any) -> tuple[int, Any]:
+    data = None
+    if body is not None:
+        if headers.get("content-type") == "application/x-www-form-urlencoded":
+            data = urllib.parse.urlencode(body).encode()
+        else:
+            data = json.dumps(body).encode()
+            headers = {**headers, "content-type": "application/json"}
+    request = urllib.request.Request(url, data=data, headers=headers, method=method)
+    try:
+        with urllib.request.urlopen(request, timeout=30) as response:
+            return response.status, json.loads(response.read() or b"{}")
+    except urllib.error.HTTPError as error:
+        try:
+            payload = json.loads(error.read() or b"{}")
+        except json.JSONDecodeError:
+            payload = {}
+        return error.code, payload
+
+
+def _error_signal(payload: Any) -> dict[str, Any]:
+    """Extract only error codes/reasons from a provider payload for classification."""
+    signal: list[str] = []
+    if isinstance(payload, dict):
+        error = payload.get("error")
+        if isinstance(error, str):
+            signal.append(error)
+        if isinstance(error, dict):
+            signal.append(str(error.get("status") or ""))
+            signal.append(str(error.get("message") or "")[:300])
+            for detail in error.get("details") or []:
+                if not isinstance(detail, dict):
+                    continue
+                signal.append(str(detail.get("reason") or ""))
+                for item in detail.get("errors") or []:
+                    if isinstance(item, dict) and isinstance(item.get("errorCode"), dict):
+                        signal.extend(f"{value}" for value in item["errorCode"].values())
+        if isinstance(payload.get("error_description"), str):
+            signal.append(payload["error_description"][:300])
+    return {"reason": " ".join(part for part in signal if part)[:300]}
+
+
+class AdsClient:
+    def __init__(self, *, access_token: str, developer_token: str | None, login_customer_id: str | None = None,
+                 api_version: str = DEFAULT_API_VERSION, transport: Transport | None = None) -> None:
+        self._access_token = access_token
+        self._developer_token = developer_token
+        self._login_customer_id = login_customer_id
+        self.api_version = api_version
+        self._transport = transport or urllib_transport
+
+    def _headers(self) -> dict[str, str]:
+        headers = {"authorization": f"Bearer {self._access_token}"}
+        if self._developer_token:
+            headers["developer-token"] = self._developer_token
+        if self._login_customer_id:
+            headers["login-customer-id"] = self._login_customer_id
+        return headers
+
+    def request(self, method: str, path: str, body: Any = None) -> tuple[int, Any]:
+        if not any(method == allowed and re.fullmatch(pattern, path) for allowed, pattern in READ_ONLY_ROUTES):
+            raise AdsRequestRefused(f"refused non-allowlisted Google Ads request: {method} {path.split('/')[-1].split(':')[-1]}")
+        return self._transport(method, f"https://{ADS_HOST}/{self.api_version}/{path}", self._headers(), body)
+
+    def token_scopes(self) -> tuple[int, list[str]]:
+        # POST body keeps the token out of URLs and access logs.
+        status, payload = self._transport("POST", TOKENINFO_URL, {"content-type": "application/x-www-form-urlencoded"}, {"access_token": self._access_token})
+        scopes = str(payload.get("scope") or "").split() if isinstance(payload, dict) else []
+        return status, scopes
+
+
+def _check(checks: list[dict[str, Any]], name: str, status: str, detail: str, remediation: dict[str, Any] | None = None) -> None:
+    item = {"check": name, "status": status, "detail": detail}
+    if remediation:
+        item["remediation"] = {key: remediation[key] for key in ("code", "prerequisite", "nextAction", "httpStatus")}
+    checks.append(item)
+
+
+def _failure(status: int, payload: Any) -> dict[str, Any]:
+    return classify(_error_signal(payload), status=status, provider="google-ads")
+
+
+def preflight(*, customer_id: str | None, login_customer_id: str | None, access_token: str | None,
+              developer_token: str | None, api_version: str = DEFAULT_API_VERSION,
+              transport: Transport | None = None, probe_keyword_planner: bool = False) -> dict[str, Any]:
+    """Run ordered, independent read-only checks and return a redacted report."""
+    checks: list[dict[str, Any]] = []
+    customer = normalize_customer_id(customer_id)
+    login = normalize_customer_id(login_customer_id) if login_customer_id else None
+    if customer:
+        _check(checks, "customer_id_format", "passed", "customer ID is 10 digits")
+    else:
+        _check(checks, "customer_id_format", "failed", "customer ID must be 10 digits (hyphens allowed in input)",
+               {"code": "customer_id_format", "prerequisite": "ads-customer-id", "nextAction": "Pass the target Ads customer ID as 10 digits, e.g. 123-456-7890.", "httpStatus": None})
+    if login_customer_id is None:
+        _check(checks, "login_customer_id_format", "skipped", "no manager login-customer-id supplied")
+    elif login:
+        _check(checks, "login_customer_id_format", "passed", "login-customer-id is 10 digits")
+    else:
+        _check(checks, "login_customer_id_format", "failed", "login-customer-id must be 10 digits",
+               {"code": "login_customer_mismatch", "prerequisite": "ads-login-customer-id", "nextAction": "Pass the manager account ID as 10 digits, or omit it for direct access.", "httpStatus": None})
+    if developer_token:
+        _check(checks, "developer_token_present", "passed", "developer token is present (value not recorded)")
+    else:
+        _check(checks, "developer_token_present", "failed", "developer token environment variable is empty", classify("DEVELOPER_TOKEN_PARAMETER_MISSING", provider="google-ads"))
+    if not access_token:
+        _check(checks, "oauth_scope", "failed", "access token environment variable is empty", classify("invalid_grant", provider="google-ads"))
+        return _report(checks, customer, login, api_version)
+
+    client = AdsClient(access_token=access_token, developer_token=developer_token, login_customer_id=login, api_version=api_version, transport=transport)
+    status, scopes = client.token_scopes()
+    if status != 200:
+        _check(checks, "oauth_scope", "failed", "token introspection failed", classify("invalid_grant", status=status, provider="google-ads"))
+        return _report(checks, customer, login, api_version)
+    if ADS_SCOPE in scopes:
+        _check(checks, "oauth_scope", "passed", "token carries the adwords scope")
+    else:
+        _check(checks, "oauth_scope", "failed", "token lacks the adwords scope", classify("ACCESS_TOKEN_SCOPE_INSUFFICIENT", provider="google-ads"))
+        return _report(checks, customer, login, api_version)
+    if not developer_token or not customer:
+        return _report(checks, customer, login, api_version)
+
+    status, payload = client.request("GET", "customers:listAccessibleCustomers")
+    accessible = sorted(name.split("/")[-1] for name in (payload.get("resourceNames") or [])) if status == 200 and isinstance(payload, dict) else []
+    if status != 200:
+        _check(checks, "accessible_customers", "failed", "listAccessibleCustomers was rejected", _failure(status, payload))
+        return _report(checks, customer, login, api_version)
+    direct = customer in accessible
+    via_manager = bool(login and login in accessible)
+    if direct or via_manager:
+        _check(checks, "accessible_customers", "passed", f"{len(accessible)} accessible customer(s); target reachable {'directly' if direct else 'via manager'}")
+    else:
+        _check(checks, "accessible_customers", "failed", f"{len(accessible)} accessible customer(s); target not among them",
+               classify("USER_PERMISSION_DENIED" if not login else "USER_PERMISSION_DENIED manager", provider="google-ads"))
+        return _report(checks, customer, login, api_version)
+
+    currency = None
+    if via_manager and not direct:
+        query = f"SELECT customer_client.id, customer_client.manager, customer_client.status FROM customer_client WHERE customer_client.id = {customer}"
+        status, payload = client.request("POST", f"customers/{login}/googleAds:search", {"query": query})
+        rows = (payload.get("results") or []) if status == 200 and isinstance(payload, dict) else []
+        if status == 200 and rows:
+            _check(checks, "account_hierarchy", "passed", "target is linked under the manager account")
+        else:
+            _check(checks, "account_hierarchy", "failed", "target is not linked under the manager account",
+                   _failure(status, payload) if status != 200 else classify("login-customer-id", provider="google-ads"))
+            return _report(checks, customer, login, api_version)
+    else:
+        _check(checks, "account_hierarchy", "skipped", "direct access; no manager hierarchy needed")
+    status, payload = client.request("POST", f"customers/{customer}/googleAds:search",
+                                     {"query": "SELECT customer.id, customer.currency_code, customer.manager, customer.test_account FROM customer LIMIT 1"})
+    if status == 200 and isinstance(payload, dict) and payload.get("results"):
+        info = payload["results"][0].get("customer") or {}
+        currency = info.get("currencyCode")
+        if info.get("manager"):
+            _check(checks, "customer_readable", "failed", "target is a manager account; Keyword Planner needs a client account",
+                   {"code": "manager_account_target", "prerequisite": "ads-client-account", "nextAction": "Select a client (non-manager) customer ID as the Keyword Planner target.", "httpStatus": None})
+            return _report(checks, customer, login, api_version, currency)
+        _check(checks, "customer_readable", "passed", "customer row readable" + (" (test account)" if info.get("testAccount") else ""))
+    else:
+        _check(checks, "customer_readable", "failed", "customer query was rejected", _failure(status, payload))
+        return _report(checks, customer, login, api_version)
+
+    if probe_keyword_planner:
+        status, payload = client.request("POST", f"customers/{customer}:generateKeywordIdeas",
+                                         {"keywordSeed": {"keywords": ["test"]}, "pageSize": 1, "includeAdultKeywords": False})
+        if status == 200:
+            _check(checks, "keyword_planner", "passed", "one-result KeywordPlanIdeaService probe succeeded")
+        else:
+            _check(checks, "keyword_planner", "failed", "KeywordPlanIdeaService probe was rejected", _failure(status, payload))
+    else:
+        _check(checks, "keyword_planner", "ready", "all prerequisites passed; pass --probe-keyword-planner to spend one read-only request")
+    return _report(checks, customer, login, api_version, currency)
+
+
+def _report(checks: list[dict[str, Any]], customer: str | None, login: str | None, api_version: str, currency: str | None = None) -> dict[str, Any]:
+    failed = [item for item in checks if item["status"] == "failed"]
+    return {
+        "schemaVersion": "maggie-google-ads-preflight.v1",
+        "passed": not failed,
+        "apiVersion": api_version,
+        "customerId": customer,
+        "loginCustomerId": login,
+        "currency": currency,
+        "checks": checks,
+        "firstFailure": failed[0]["check"] if failed else None,
+        "nextAction": failed[0]["remediation"]["nextAction"] if failed and failed[0].get("remediation") else None,
+        "mutationsAllowed": False,
+    }
+
+
+def _micros(value: Any) -> float | None:
+    try:
+        return round(int(value) / 1_000_000, 2)
+    except (TypeError, ValueError):
+        return None
+
+
+def normalize_ideas(results: list[Any], currency: str | None) -> list[dict[str, Any]]:
+    ideas = []
+    for item in results:
+        if not isinstance(item, dict) or not isinstance(item.get("text"), str):
+            continue
+        metrics = item.get("keywordIdeaMetrics") or {}
+        searches = metrics.get("avgMonthlySearches")
+        ideas.append({
+            "text": item["text"],
+            "avgMonthlySearches": int(searches) if str(searches or "").isdigit() else None,
+            "competition": COMPETITION.get(str(metrics.get("competition") or "UNKNOWN"), "unknown"),
+            "competitionIndex": int(metrics["competitionIndex"]) if str(metrics.get("competitionIndex") or "").isdigit() else None,
+            "lowTopOfPageBid": _micros(metrics.get("lowTopOfPageBidMicros")),
+            "highTopOfPageBid": _micros(metrics.get("highTopOfPageBidMicros")),
+            "currency": currency,
+        })
+    return ideas
+
+
+def keyword_ideas(*, customer_id: str, login_customer_id: str | None, access_token: str, developer_token: str,
+                  keywords: list[str], url: str | None = None, language: str | None = None, geo_targets: list[str] | None = None,
+                  currency: str | None = None, max_pages: int = 1, page_size: int = 100,
+                  api_version: str = DEFAULT_API_VERSION, transport: Transport | None = None) -> dict[str, Any]:
+    customer = normalize_customer_id(customer_id)
+    if not customer:
+        raise ValueError("customer ID must be 10 digits")
+    if not keywords and not url:
+        raise ValueError("provide at least one seed keyword or a seed URL")
+    login = normalize_customer_id(login_customer_id) if login_customer_id else None
+    client = AdsClient(access_token=access_token, developer_token=developer_token, login_customer_id=login, api_version=api_version, transport=transport)
+    body: dict[str, Any] = {"pageSize": max(1, min(page_size, 1000)), "includeAdultKeywords": False, "keywordPlanNetwork": "GOOGLE_SEARCH"}
+    if keywords and url:
+        body["keywordAndUrlSeed"] = {"keywords": keywords, "url": url}
+    elif keywords:
+        body["keywordSeed"] = {"keywords": keywords}
+    else:
+        body["urlSeed"] = {"url": url}
+    if language:
+        body["language"] = language if language.startswith("languageConstants/") else f"languageConstants/{language}"
+    if geo_targets:
+        body["geoTargetConstants"] = [item if item.startswith("geoTargetConstants/") else f"geoTargetConstants/{item}" for item in geo_targets]
+    results: list[Any] = []
+    pages = 0
+    while pages < max(1, max_pages):
+        status, payload = client.request("POST", f"customers/{customer}:generateKeywordIdeas", body)
+        pages += 1
+        if status != 200:
+            return {"schemaVersion": "maggie-google-ads-keyword-ideas.v1", "passed": False, "customerId": customer, "ideas": normalize_ideas(results, currency),
+                    "pages": pages, "remediation": {key: value for key, value in _failure(status, payload).items() if key != "provider"}, "mutationsAllowed": False}
+        results.extend(payload.get("results") or [])
+        token = payload.get("nextPageToken")
+        if not token:
+            break
+        body = {**body, "pageToken": token}
+    return {"schemaVersion": "maggie-google-ads-keyword-ideas.v1", "passed": True, "customerId": customer, "pages": pages,
+            "ideas": normalize_ideas(results, currency), "mutationsAllowed": False}

package/bundled-tools/runtime/google_capabilities.py

@@ -6,6 +6,8 @@ import re
 from typing import Any
 from urllib.parse import urlsplit
 
+from google_remediation import classify as classify_failure
+
 
 SCHEMA_VERSION = "maggie-google-capability-report.v2"
 CAPABILITY_NAMES = ("read", "report", "edit", "publish")
@@ -172,7 +174,7 @@ def validate_report(report: Any) -> dict[str, Any]:
             errors.append(f"{prefix} must be an object")
             continue
         required = {"provider", "resource", "activeAccount", "target", "authMode", "scopes", "productRole", "evidence", "capabilities", "nextAction"}
-        unknown = sorted(set(row) - required)
+        unknown = sorted(set(row) - required - {"failure"})
         if unknown:
             errors.append(f"{prefix} contains unsupported fields")
         provider = row.get("provider")
@@ -253,6 +255,15 @@ def validate_report(report: Any) -> dict[str, Any]:
                 errors.append(f"{prefix}.evidence.adsPrerequisites requires developer token and customer ID presence")
         elif prerequisites is not None:
             errors.append(f"{prefix}.evidence.adsPrerequisites is only valid for google-ads")
+        remediation = None
+        failure = row.get("failure")
+        if failure is not None:
+            if not isinstance(failure, dict) or set(failure) - {"code", "reason", "httpStatus"} or not any(failure.get(key) for key in ("code", "reason", "httpStatus")):
+                errors.append(f"{prefix}.failure must contain only code, reason, and httpStatus")
+            elif any(not isinstance(failure.get(key), str) or len(failure[key]) > 300 for key in ("code", "reason") if key in failure):
+                errors.append(f"{prefix}.failure.code and reason must be bounded strings")
+            else:
+                remediation = classify_failure(failure, provider=provider)
         normalized.append({
             "provider": provider,
             "resource": resource,
@@ -269,7 +280,8 @@ def validate_report(report: Any) -> dict[str, Any]:
                 "writeTested": isinstance(evidence.get("writeTest"), dict),
             },
             "capabilities": safe_capabilities,
-            "nextAction": row.get("nextAction"),
+            "nextAction": remediation["nextAction"] if remediation else row.get("nextAction"),
+            **({"remediation": remediation} if remediation else {}),
         })
 
     return {
@@ -277,5 +289,9 @@ def validate_report(report: Any) -> dict[str, Any]:
         "passed": not errors,
         "errors": sorted(set(errors)),
         "providerResults": normalized,
+        "remediation": [
+            {"provider": item["provider"], "resource": item["resource"], **{key: item["remediation"][key] for key in ("code", "prerequisite", "nextAction", "httpStatus")}}
+            for item in normalized if item.get("remediation")
+        ],
         "mutationsAllowed": False,
     }

package/bundled-tools/runtime/google_remediation.py

@@ -0,0 +1,152 @@
+"""Map redacted Google provider failures to one prerequisite and one safe action.
+
+The classifier is deterministic and offline. It reads an error code, HTTP
+status, and short message only to choose a rule; it never returns the input
+message, so tokens or raw provider payloads cannot leak into a report.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Any
+
+
+# Ordered: the first matching rule wins, so specific product errors precede
+# generic HTTP-status fallbacks.
+RULES: tuple[dict[str, Any], ...] = (
+    {
+        "code": "adc_invalid_scope",
+        "patterns": (r"invalid_scope",),
+        "prerequisite": "oauth-scope-request",
+        "nextAction": "Re-run the ADC login or impersonation command requesting only the exact allowlisted scope for this provider (see the scope allowlist); do not reuse a token minted without that scope.",
+    },
+    {
+        "code": "token_scope_insufficient",
+        "patterns": (r"ACCESS_TOKEN_SCOPE_INSUFFICIENT", r"insufficient(?:_| )(?:authentication )?scopes?", r"Request had insufficient authentication scopes"),
+        "prerequisite": "oauth-granted-scope",
+        "nextAction": "Mint a new short-lived token that includes the provider's required scope, then repeat the same read-only request.",
+    },
+    {
+        "code": "redirect_uri_mismatch",
+        "patterns": (r"redirect_uri_mismatch",),
+        "prerequisite": "oauth-client-redirect-uri",
+        "nextAction": "Add the exact callback URL used by this connect path to the OAuth client's authorized redirect URIs, or switch to the client that already lists it.",
+    },
+    {
+        "code": "oauth_consent_not_configured",
+        "patterns": (r"consent screen", r"OAuth consent", r"access_denied.*(?:not completed|verification)", r"app (?:is )?(?:not verified|blocked)", r"org_internal"),
+        "prerequisite": "oauth-consent-configuration",
+        "nextAction": "Configure the OAuth consent screen (user type, test users or verification status) in the Cloud project that owns the client, then reconnect.",
+    },
+    {
+        "code": "developer_token_prohibited",
+        "patterns": (r"DEVELOPER_TOKEN_PROHIBITED", r"developer token is not allowed with the project", r"DEVELOPER_TOKEN_(?:MISMATCH|INVALID_FOR_PROJECT)"),
+        "prerequisite": "ads-developer-token-project-pairing",
+        "nextAction": "Use the OAuth client from the Cloud project already paired with this developer token, or request access for the new project; one developer token is bound to one project.",
+    },
+    {
+        "code": "developer_token_not_approved",
+        "patterns": (r"DEVELOPER_TOKEN_NOT_APPROVED", r"only approved for use with test accounts", r"DEVELOPER_TOKEN_NOT_ON_ALLOWLIST"),
+        "prerequisite": "ads-developer-token-access-level",
+        "nextAction": "Apply for Basic or Standard access for the developer token, or run against a Google Ads test account until it is approved.",
+    },
+    {
+        "code": "developer_token_missing",
+        "patterns": (r"DEVELOPER_TOKEN_PARAMETER_MISSING", r"developer[- ]token (?:header )?(?:is )?(?:missing|required)", r"DEVELOPER_TOKEN_(?:INVALID|MISSING)"),
+        "prerequisite": "ads-developer-token",
+        "nextAction": "Install the developer token in the host secret store and send it as the developer-token header; record only its presence.",
+    },
+    {
+        "code": "login_customer_mismatch",
+        "patterns": (r"login[-_ ]customer[-_ ]id", r"LOGIN_CUSTOMER_ID", r"USER_PERMISSION_DENIED.*manager"),
+        "prerequisite": "ads-login-customer-id",
+        "nextAction": "Set login-customer-id to the manager account that links to the target customer (digits only), or omit it when the user has direct access.",
+    },
+    {
+        "code": "ads_user_permission_denied",
+        "patterns": (r"USER_PERMISSION_DENIED", r"CUSTOMER_NOT_FOUND", r"NOT_ADS_USER"),
+        "prerequisite": "ads-account-access",
+        "nextAction": "Grant the authenticated Google user access to the target Ads customer (or its manager), then repeat listAccessibleCustomers before any report.",
+    },
+    {
+        "code": "ga4_property_membership",
+        "patterns": (r"does not have sufficient permissions for this property", r"User does not have (?:sufficient )?permission.*propert", r"properties/\d+.*PERMISSION_DENIED"),
+        "prerequisite": "ga4-property-membership",
+        "nextAction": "Add the principal (user or service account email) to the GA4 property with Viewer or higher in Property Access Management.",
+    },
+    {
+        "code": "gsc_property_membership",
+        "patterns": (r"User does not have sufficient permission for site", r"sites/.*PERMISSION_DENIED"),
+        "prerequisite": "gsc-property-membership",
+        "nextAction": "Add the principal as a user of the exact Search Console property (URL-prefix or domain) being queried.",
+    },
+    {
+        "code": "api_disabled",
+        "patterns": (r"SERVICE_DISABLED", r"has not been used in project .* or it is disabled", r"API .*is disabled", r"accessNotConfigured"),
+        "prerequisite": "cloud-api-enablement",
+        "nextAction": "Enable this provider's API in the Cloud project that owns the OAuth client or service account, wait a few minutes, then retry.",
+    },
+    {
+        "code": "quota_exhausted",
+        "patterns": (r"RESOURCE_EXHAUSTED", r"RATE_LIMIT_EXCEEDED", r"quota (?:exceeded|exhausted)", r"rateLimitExceeded", r"RESOURCE_TEMPORARILY_EXHAUSTED"),
+        "prerequisite": "provider-quota",
+        "nextAction": "Stop retrying, wait for the quota window or request more quota; record the request as blocked rather than repeating it.",
+    },
+    {
+        "code": "iam_token_creator_missing",
+        "patterns": (r"iam\.serviceAccounts\.getAccessToken", r"serviceAccountTokenCreator"),
+        "prerequisite": "service-account-impersonation",
+        "nextAction": "Grant the caller roles/iam.serviceAccountTokenCreator on the target service account, then re-run the impersonation command.",
+    },
+    {
+        "code": "product_role_denied",
+        "patterns": (r"PERMISSION_DENIED", r"The caller does not have permission", r"forbidden"),
+        "prerequisite": "product-role",
+        "nextAction": "Grant the principal the needed product-level role on the selected resource; Cloud IAM alone does not grant product access.",
+    },
+    {
+        "code": "invalid_grant",
+        "patterns": (r"invalid_grant", r"Token has been expired or revoked", r"UNAUTHENTICATED", r"invalid_token"),
+        "prerequisite": "oauth-credential-validity",
+        "nextAction": "Reconnect the account to obtain a fresh credential; the stored token is expired or revoked.",
+    },
+)
+
+STATUS_FALLBACK = {
+    401: RULES[-1],
+    403: next(rule for rule in RULES if rule["code"] == "product_role_denied"),
+    429: next(rule for rule in RULES if rule["code"] == "quota_exhausted"),
+}
+
+UNKNOWN = {
+    "code": "unclassified",
+    "prerequisite": "unknown",
+    "nextAction": "Record the provider error code and HTTP status (no payload) and check the prerequisites in order: scope, consent, API enablement, product access, quota.",
+}
+
+
+def classify(error: Any = None, *, status: int | None = None, provider: str | None = None) -> dict[str, Any]:
+    """Return {code, prerequisite, nextAction, provider, httpStatus}; never echoes input text."""
+    if isinstance(error, dict):
+        status = status if status is not None else error.get("httpStatus", error.get("status"))
+        parts = [error.get(key) for key in ("code", "reason", "status", "message")]
+        text = " ".join(str(item) for item in parts if isinstance(item, (str, int)))
+        provider = provider or error.get("provider")
+    else:
+        text = str(error or "")
+    text = text[:2000]
+    rule = None
+    for candidate in RULES:
+        if any(re.search(pattern, text, re.IGNORECASE) for pattern in candidate["patterns"]):
+            rule = candidate
+            break
+    if rule is None and isinstance(status, int):
+        rule = STATUS_FALLBACK.get(status)
+    rule = rule or UNKNOWN
+    return {
+        "code": rule["code"],
+        "prerequisite": rule["prerequisite"],
+        "nextAction": rule["nextAction"],
+        "provider": provider if isinstance(provider, str) else None,
+        "httpStatus": status if isinstance(status, int) else None,
+    }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@topy-ai/maggie",
-  "version": "0.7.47",
+  "version": "0.7.49",
   "description": "Install and manage Maggie Skills for AI coding agents",
   "license": "MIT",
   "type": "module",

package/references/browser-inspection.md

@@ -75,3 +75,28 @@ appearance. For every stateful component capture state A and state B and
 record the trigger and transition. Keep screenshots and extracted data under
 the target's namespaced research root so multiple URLs cannot overwrite one
 another.
+
+## Network interception and write safety
+
+Any skill that drives a browser against a running app (QA, clone, design
+review) must assume the app may talk to a real API. A local development build
+is often configured with the production API base URL, so a click in local QA
+can change live accounts.
+
+- Do not rely on page-level stubs such as overriding `window.fetch` from the
+  console or an injected script. Bundled API clients usually capture `fetch`
+  at module load, use `XMLHttpRequest`, or run in a service worker, so the
+  override never sees their requests.
+- Intercept at the network layer instead: Playwright `page.route()` /
+  `context.route()`, Puppeteer request interception, or CDP `Fetch.enable`.
+  Deny by default every non-GET request to a production origin and let only
+  explicitly listed reads through.
+- Verify the interception before any write flow: trigger one harmless request
+  and confirm in the browser's network log that it was intercepted, not sent.
+- Without network-layer interception, run write flows only against a
+  non-production API, or after the user gives explicit consent naming the
+  account and the data that will change. Record a backup or restore path first.
+
+`maggie qa start --api-base URL --production-api URL` records the API target.
+Scenarios marked `"mutates": true` are blocked against a production API unless
+`--allow-production-writes` is given. See the `maggie-qa-workflow` skill.

package/references/google-integrations-runbook.md

@@ -119,6 +119,60 @@ selected `resource`. A report that only proves account discovery, or comes from
 the wrong browser account/property, is rejected before a write workflow can use
 it.
 
+## Failure remediation
+
+A failed check must name the one prerequisite that failed, not a generic
+"access denied". Put only the provider error code/reason and HTTP status in the
+row's optional `failure` field; the validator returns `remediation` with a
+stable `code`, the failed `prerequisite`, and one safe `nextAction`. It never
+echoes the input text. `maggie ops google-diagnose` applies the same mapping to
+one error.
+
+| Signal | Failed prerequisite | Safe next action |
+|---|---|---|
+| `invalid_scope` (ADC) | OAuth scope request | Re-run the ADC/impersonation command with the exact allowlisted scope |
+| `ACCESS_TOKEN_SCOPE_INSUFFICIENT` | Granted token scope | Mint a new token that includes the provider scope |
+| `redirect_uri_mismatch` | OAuth client redirect URI | Add the exact callback URL to the client, or use the client that lists it |
+| Consent screen not configured / app not verified | OAuth consent configuration | Configure user type, test users, or verification in the client's project |
+| `SERVICE_DISABLED` / `accessNotConfigured` | Cloud API enablement | Enable the API in the project that owns the client or service account |
+| `RESOURCE_EXHAUSTED` / HTTP 429 | Provider quota | Stop retrying; wait for the window or request quota; record `blocked` |
+| `DEVELOPER_TOKEN_PARAMETER_MISSING` | Ads developer token | Install the token in the host secret store; send the `developer-token` header |
+| `DEVELOPER_TOKEN_NOT_APPROVED` | Ads token access level | Apply for Basic/Standard access, or use a test account |
+| `DEVELOPER_TOKEN_PROHIBITED` | Developer token/project pairing | Use the OAuth client from the paired Cloud project, or request access for the new project |
+| `USER_PERMISSION_DENIED` with a manager | `login-customer-id` | Set it to the manager that links the target, or omit it for direct access |
+| `USER_PERMISSION_DENIED` / `CUSTOMER_NOT_FOUND` | Ads account access | Grant the user access to the customer or its manager |
+| GA4 "insufficient permissions for this property" | GA4 property membership | Add the principal to the property with Viewer or higher |
+| `iam.serviceAccounts.getAccessToken` denied | Service-account impersonation | Grant `roles/iam.serviceAccountTokenCreator` on the target service account |
+| Other `PERMISSION_DENIED` / HTTP 403 | Product role | Grant the product-level role; Cloud IAM alone is insufficient |
+| `invalid_grant` / HTTP 401 | Credential validity | Reconnect; the stored token is expired or revoked |
+
+## Google Ads read-only preflight and Keyword Planner
+
+`maggie ops google-ads-preflight` checks, in order and independently: customer
+and `login-customer-id` format (10 digits; hyphens stripped), developer-token
+presence (environment variable name only), the `adwords` scope via token
+introspection (token sent in a POST body, never a URL),
+`customers:listAccessibleCustomers`, the manager hierarchy through
+`customer_client` when a manager is used, a `customer` read (currency, manager,
+test-account flags), and Keyword Planner readiness. The Keyword Planner check
+reports `ready` without spending a request unless `--probe-keyword-planner` is
+passed, which sends one one-result `generateKeywordIdeas` call. Every failure
+carries the same `remediation` mapping as above.
+
+`maggie ops google-ads-keyword-ideas` sends read-only `generateKeywordIdeas`
+requests (keyword, URL, or keyword+URL seed; language and geo-target constants;
+bounded pagination) and normalizes each idea to `text`, `avgMonthlySearches`,
+`competition`, `competitionIndex`, and `lowTopOfPageBid`/`highTopOfPageBid`
+converted from micros into the customer currency.
+
+The adapter refuses any request outside `listAccessibleCustomers`,
+`googleAds:search`, and `generateKeywordIdeas`, so it cannot mutate campaigns,
+budgets, or keywords. The REST API version defaults to `v21` and can be set with
+`--api-version` or `MAGGIE_GOOGLE_ADS_API_VERSION`; check Google's sunset
+schedule and use a currently supported version. Keyword Planner volumes are
+estimates for planning and require an approved developer token on a real
+account; test accounts return no metrics.
+
 ## Capability matrix
 
 Every provider/resource row must expose this shape:

package/references/provider-adapter-contract.md

@@ -150,6 +150,39 @@ image-processing contract: optimisation may use Cloudflare Images
 transformations, Astro build tooling or a provider-specific implementation
 behind the same interface.
 
+## OAuth connections
+
+A provider connection is only as reliable as its weakest connect path:
+
+- Each adapter declares one canonical OAuth scope set. Every client that
+  starts the flow (dashboard, mobile app, CLI) requests exactly that set.
+  LinkedIn invalidates a member's earlier tokens when a later sign-in asks for
+  a different scope set, so a mobile app that omits `email` silently revokes
+  the dashboard's token while the database still says `active`.
+- Prefer one OAuth client per product. When a client ID is shared with other
+  products or callbacks, record it as `client_shared_with`; their sign-ins can
+  revoke this product's tokens unless they use the identical scope set.
+- Treat stored connection status as a cache. A token that the provider has
+  revoked, or that the serving host cannot decrypt, is `needs_reconnect`
+  before anything is scheduled on it — not when a post fails.
+- Provider media URLs (for example `media.licdn.com` with an `e=` expiry) are
+  signed and expire. Cache the bytes in owned storage or refresh on readback.
+
+`maggie tool maggie_social_share.py adapters` and `connections` check these
+rules from a redacted JSON manifest; see the Social Share skill for shapes.
+
+## Structured model output
+
+Keep structured-output schemas small. Gemini rejected a JSON schema whose enum
+had 125 values with `400 INVALID_ARGUMENT`, and the caller silently fell back
+for every request. For a large vocabulary (styles, categories, catalogue IDs):
+
+1. ask for a free string (optionally with a short list of examples in the
+   prompt) instead of a large `enum`;
+2. validate the returned value server-side against the authoritative list;
+3. treat a schema rejection or an unknown value as a visible, counted failure —
+   never a silent fallback to a default.
+
 ## Adding a provider
 
 1. Implement the relevant interface in `src/lib/providers/`.