@topy-ai/maggie 0.7.48 → 0.7.49

package/bundled-tools/clis/maggie_notifications.py

@@ -0,0 +1,528 @@
+#!/usr/bin/env python3
+"""Provider-neutral website notification operations checks.
+
+Offline and read-only: validates a notification catalogue, compares it with
+local templates and a provider template export, checks provider configuration
+by environment variable name only, evaluates queue health snapshots, and plans
+retention purges as a dry run. It never calls a provider API, never sends a
+message, and never prints secret values or recipient addresses.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import re
+import sys
+from datetime import datetime, timedelta, timezone
+from pathlib import Path
+
+
+CATALOGUE_SCHEMA = "maggie-notification-catalogue.v1"
+TEMPLATES_SCHEMA = "maggie-notification-templates.v1"
+SNAPSHOT_SCHEMA = "maggie-notification-queue-snapshot.v1"
+INVENTORY_SCHEMA = "maggie-notification-retention-inventory.v1"
+
+SECTIONS = ("identity-security", "account", "business", "billing", "support", "marketing", "deliverability-ops")
+CATEGORIES = ("transactional", "support", "marketing")
+CONSENT = ("not-required", "opt-in-required", "operator-only")
+AUDIENCES = ("visitor", "user", "merchant", "team", "operator")
+CHANNELS = ("email", "in-app", "sms")
+STATUSES = ("implemented", "provider-owned", "reserved", "missing")
+DELIVERY = ("outbox", "direct", "provider")
+QUEUES = ("user", "operations", "marketing")
+RETENTION_KINDS = ("webhook-payload", "delivery-record", "rendered-snapshot", "template-variables")
+ALIAS = re.compile(r"^[a-z0-9][a-z0-9._-]{0,99}$")
+VARIABLE = re.compile(r"^[A-Za-z_][A-Za-z0-9_]{0,63}$")
+LOCALE = re.compile(r"^[a-z]{2,3}(-[A-Za-z0-9]{2,8})*$")
+PLACEHOLDER = re.compile(r"\{\{\{?\s*([A-Za-z_][A-Za-z0-9_.]*)\s*\}?\}\}")
+EMAIL = re.compile(r"[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}")
+
+# Resend-aware defaults. Each requirement lists accepted variable names; the
+# preflight reports presence only and never reads or prints values, except the
+# template map whose alias keys (not IDs) are compared with the catalogue.
+RESEND_REQUIREMENTS = (
+    ("api_key", ("RESEND_API_KEY",)),
+    ("sender", ("RESEND_EMAIL", "RESEND_FROM", "RESEND_SENDER")),
+    ("worker_secret", ("NOTIFICATION_WORKER_SECRET",)),
+    ("support_recipients", ("NOTIFICATION_SUPPORT_RECIPIENTS",)),
+    ("webhook_secret", ("RESEND_WEBHOOK_SECRET",)),
+    ("template_map", ("RESEND_TEMPLATE_IDS_JSON",)),
+)
+
+# Operator alert templates. They are delivered on the operations queue/channel,
+# never through the user or marketing notification queue they describe, so a
+# failing provider cannot suppress its own alert.
+ALERTS = {
+    "queue.pending_backlog": {"severity": "warning", "owner": "site operator", "recovery": "Check worker timer/last run, provider status, and rate limits; drain the queue before releasing new triggers.", "escalation": "critical after 2x threshold or 60 minutes"},
+    "queue.oldest_pending_age": {"severity": "critical", "owner": "site operator", "recovery": "Confirm the worker runs and claims rows; inspect the newest dispatcher error without printing recipients.", "escalation": "page the on-call developer"},
+    "queue.dead_letter_growth": {"severity": "critical", "owner": "site operator", "recovery": "Group dead letters by error code, fix the cause, then replay with a recorded reason.", "escalation": "page the on-call developer"},
+    "queue.expired_leases": {"severity": "warning", "owner": "developer", "recovery": "Worker crashed or exceeded lease time; check worker logs and lease duration.", "escalation": "critical when leases keep expiring across runs"},
+    "worker.stale_run": {"severity": "critical", "owner": "site operator", "recovery": "Restart the timer/cron and verify one successful run with a health snapshot.", "escalation": "page the on-call developer"},
+    "webhook.lag": {"severity": "warning", "owner": "developer", "recovery": "Check webhook endpoint reachability and signing secret; reconcile delivery state from provider readback.", "escalation": "critical when bounces/complaints cannot be suppressed"},
+    "deliverability.bounce_rate": {"severity": "warning", "owner": "marketing owner", "recovery": "Suppress hard bounces, review list sources, pause campaigns above threshold.", "escalation": "critical above provider suspension threshold"},
+    "deliverability.complaint_rate": {"severity": "critical", "owner": "marketing owner", "recovery": "Pause marketing sends, review consent evidence and frequency policy.", "escalation": "business owner"},
+    "deliverability.sender_domain": {"severity": "critical", "owner": "developer", "recovery": "Re-verify SPF/DKIM/DMARC records for the sending domain before resuming.", "escalation": "business owner"},
+    "templates.provider_drift": {"severity": "warning", "owner": "developer", "recovery": "Run templates drift, review the diff, then sync with an explicit apply.", "escalation": "block the next deploy"},
+}
+
+DEFAULT_THRESHOLDS = {
+    "max_pending": 500,
+    "max_oldest_pending_minutes": 30,
+    "max_dead_letter": 0,
+    "max_expired_leases": 0,
+    "max_webhook_lag_minutes": 60,
+    "max_since_last_success_minutes": 30,
+    "max_bounce_rate": 0.04,
+    "max_complaint_rate": 0.001,
+}
+
+
+def load_json(path: str | Path) -> dict:
+    data = json.loads(Path(path).read_text(encoding="utf-8"))
+    if not isinstance(data, dict):
+        raise ValueError(f"{path}: expected a JSON object")
+    return data
+
+
+def parse_time(value: object, label: str) -> datetime:
+    if not isinstance(value, str) or not value:
+        raise ValueError(f"{label} must be an ISO timestamp")
+    parsed = datetime.fromisoformat(value.replace("Z", "+00:00"))
+    return parsed if parsed.tzinfo else parsed.replace(tzinfo=timezone.utc)
+
+
+def emit(result: dict) -> int:
+    print(json.dumps(result, indent=2, ensure_ascii=False))
+    return 0 if result.get("passed") else 1
+
+
+# --- catalogue -------------------------------------------------------------
+
+def validate_catalogue(data: dict) -> dict:
+    errors: list[str] = []
+    warnings: list[str] = []
+    if data.get("schemaVersion") != CATALOGUE_SCHEMA:
+        errors.append(f"schemaVersion must be {CATALOGUE_SCHEMA}")
+    retention = data.get("retention") if isinstance(data.get("retention"), dict) else {}
+    if not retention:
+        errors.append("retention policy is required (webhook payloads, delivery records, snapshots, template variables)")
+    for kind in RETENTION_KINDS:
+        days = retention.get(kind, {}).get("days") if isinstance(retention.get(kind), dict) else None
+        if not isinstance(days, int) or days < 1:
+            errors.append(f"retention.{kind}.days must be a positive integer")
+    if isinstance(retention.get("webhook-payload"), dict) and retention["webhook-payload"].get("storeRawPayload") is True:
+        warnings.append("retention.webhook-payload stores raw provider payloads; store minimized fields (event, provider id, status, timestamps) instead")
+    entries = data.get("entries")
+    if not isinstance(entries, list) or not entries:
+        errors.append("entries must be a non-empty list")
+        entries = []
+    seen: set[str] = set()
+    coverage: dict[str, dict[str, int]] = {section: {status: 0 for status in STATUSES} for section in SECTIONS}
+    for index, entry in enumerate(entries):
+        label = f"entries[{index}]"
+        if not isinstance(entry, dict):
+            errors.append(f"{label} must be an object")
+            continue
+        alias = entry.get("alias")
+        if not isinstance(alias, str) or not ALIAS.match(alias):
+            errors.append(f"{label}.alias must match {ALIAS.pattern}")
+        else:
+            label = alias
+            if alias in seen:
+                errors.append(f"{alias}: duplicate alias")
+            seen.add(alias)
+        for field, allowed in (("section", SECTIONS), ("category", CATEGORIES), ("consent", CONSENT), ("audience", AUDIENCES), ("status", STATUSES), ("delivery", DELIVERY), ("queue", QUEUES)):
+            if entry.get(field) not in allowed:
+                errors.append(f"{label}.{field} must be one of {', '.join(allowed)}")
+        if not isinstance(entry.get("trigger"), str) or not entry["trigger"].strip():
+            errors.append(f"{label}.trigger is required")
+        channels = entry.get("channels")
+        if not isinstance(channels, list) or not channels or any(item not in CHANNELS for item in channels):
+            errors.append(f"{label}.channels must be a non-empty subset of {', '.join(CHANNELS)}")
+            channels = []
+        locales = entry.get("locales")
+        if not isinstance(locales, list) or not locales or any(not isinstance(item, str) or not LOCALE.match(item) for item in locales):
+            errors.append(f"{label}.locales must list BCP 47 locales")
+        if "markets" in entry and (not isinstance(entry["markets"], list) or not all(isinstance(item, str) and item for item in entry["markets"])):
+            errors.append(f"{label}.markets must be a list of market codes")
+        variables = entry.get("variables")
+        if not isinstance(variables, list) or any(not isinstance(item, str) or not VARIABLE.match(item) for item in variables):
+            errors.append(f"{label}.variables must list identifier names")
+        idempotency = entry.get("idempotencyKey")
+        if not isinstance(idempotency, str) or "{" not in idempotency:
+            errors.append(f"{label}.idempotencyKey must be a template with at least one {{placeholder}}")
+        cta = entry.get("cta")
+        if cta is not None:
+            route = cta.get("route") if isinstance(cta, dict) else None
+            if not isinstance(route, str) or not (route.startswith("/") or route.startswith("https://")):
+                errors.append(f"{label}.cta.route must be a site path or https URL")
+            elif route.startswith("https://") and "{" in route.split("/", 3)[2]:
+                errors.append(f"{label}.cta.route must not template the host")
+        if not isinstance(entry.get("retentionDays"), int) or entry.get("retentionDays", 0) < 1:
+            errors.append(f"{label}.retentionDays must be a positive integer")
+        if not isinstance(entry.get("provider"), str) or not entry["provider"].strip():
+            errors.append(f"{label}.provider is required (e.g. resend, local, auth-provider)")
+        category = entry.get("category")
+        if category == "marketing":
+            if entry.get("consent") != "opt-in-required":
+                errors.append(f"{label}: marketing messages require consent opt-in-required")
+            if entry.get("unsubscribe") is not True:
+                errors.append(f"{label}: marketing messages require unsubscribe and preference-centre links (unsubscribe: true)")
+            if entry.get("queue") != "marketing":
+                errors.append(f"{label}: marketing messages must use the marketing queue")
+        elif entry.get("consent") == "opt-in-required" and category == "transactional":
+            warnings.append(f"{label}: transactional message marked opt-in-required; confirm it is not marketing")
+        if entry.get("section") == "deliverability-ops" and entry.get("queue") != "operations":
+            errors.append(f"{label}: operational alerts must be delivered on the operations queue, outside the user/marketing queue they report on")
+        if entry.get("lead") is True and entry.get("status") == "implemented" and entry.get("delivery") != "outbox":
+            errors.append(f"{label}: external-recipient lead email (contact, waitlist, interest) must use durable outbox delivery with retry and dead-letter, not a direct send")
+        elif entry.get("delivery") == "direct" and entry.get("audience") in ("visitor", "merchant") and entry.get("status") == "implemented":
+            warnings.append(f"{label}: direct send to an external recipient has no retry/dead-letter evidence")
+        if entry.get("section") in coverage and entry.get("status") in STATUSES:
+            coverage[entry["section"]][entry["status"]] += 1
+    for section, counts in coverage.items():
+        if not sum(counts.values()):
+            warnings.append(f"section {section} has no catalogue entries")
+    missing = [entry.get("alias") for entry in entries if isinstance(entry, dict) and entry.get("status") == "missing"]
+    return {
+        "schemaVersion": "maggie-notification-catalogue-report.v1",
+        "passed": not errors,
+        "entries": len(entries),
+        "coverage": coverage,
+        "missing": missing,
+        "errors": errors,
+        "warnings": warnings,
+    }
+
+
+# --- templates drift --------------------------------------------------------
+
+def load_local_templates(path: Path) -> dict[tuple[str, str], dict]:
+    templates: dict[tuple[str, str], dict] = {}
+    if path.is_dir():
+        for file in sorted(path.rglob("*")):
+            if not file.is_file():
+                continue
+            parts = file.name.split(".")
+            if len(parts) < 3 or not LOCALE.match(parts[-2]):
+                continue
+            alias = ".".join(parts[:-2])
+            key = (alias, parts[-2])
+            found = set(name.split(".")[0] for name in PLACEHOLDER.findall(file.read_text(encoding="utf-8", errors="replace")))
+            current = templates.setdefault(key, {"variables": set(), "version": None, "formats": set()})
+            current["variables"] |= found
+            current["formats"].add(parts[-1])
+        return templates
+    data = load_json(path)
+    if data.get("schemaVersion") != TEMPLATES_SCHEMA:
+        raise ValueError(f"local template manifest must use {TEMPLATES_SCHEMA}")
+    for item in data.get("templates", []):
+        key = (item.get("alias"), item.get("locale"))
+        templates[key] = {"variables": set(item.get("variables", [])), "version": item.get("version"), "formats": set(item.get("formats", []))}
+    return templates
+
+
+def load_provider_pages(paths: list[str]) -> tuple[dict[tuple[str, str], dict], list[str]]:
+    errors: list[str] = []
+    templates: dict[tuple[str, str], dict] = {}
+    for index, path in enumerate(paths):
+        page = load_json(path)
+        if index == len(paths) - 1 and page.get("has_more") is True:
+            errors.append("provider export is incomplete: the last page reports has_more=true; export every page before comparing")
+        for item in page.get("data", []):
+            alias = item.get("alias") or item.get("name")
+            locale = item.get("locale") or "default"
+            if isinstance(alias, str) and "." in alias and LOCALE.match(alias.rsplit(".", 1)[1]) and not item.get("locale"):
+                alias, locale = alias.rsplit(".", 1)
+            variables = item.get("variables", [])
+            names = {entry.get("key") if isinstance(entry, dict) else entry for entry in variables}
+            templates[(alias, locale)] = {"variables": {name for name in names if name}, "version": item.get("version") or item.get("updated_at")}
+    return templates, errors
+
+
+def templates_drift(catalogue: dict, local_path: Path | None, provider_paths: list[str], provider_name: str) -> dict:
+    errors: list[str] = []
+    findings: dict[str, list] = {"missingLocal": [], "missingProvider": [], "extraProvider": [], "extraLocal": [], "localeGaps": [], "variableMismatches": [], "versionDrift": []}
+    entries = [entry for entry in catalogue.get("entries", []) if isinstance(entry, dict)]
+    expected: dict[tuple[str, str], set[str]] = {}
+    provider_aliases: set[str] = set()
+    for entry in entries:
+        if entry.get("status") != "implemented" or "email" not in entry.get("channels", []):
+            continue
+        for locale in entry.get("locales", []):
+            expected[(entry["alias"], locale)] = set(entry.get("variables", []))
+        if entry.get("provider") == provider_name:
+            provider_aliases.add(entry["alias"])
+    catalogue_aliases = {entry.get("alias") for entry in entries}
+    local = load_local_templates(local_path) if local_path else {}
+    provider, page_errors = load_provider_pages(provider_paths) if provider_paths else ({}, [])
+    errors.extend(page_errors)
+    for (alias, locale), variables in sorted(expected.items()):
+        if local_path and (alias, locale) not in local:
+            findings["missingLocal"].append(f"{alias}.{locale}")
+        if provider_paths and alias in provider_aliases and (alias, locale) not in provider:
+            findings["missingProvider"].append(f"{alias}.{locale}")
+        for source, table in (("local", local), ("provider", provider)):
+            if (alias, locale) in table:
+                actual = table[(alias, locale)]["variables"]
+                undeclared, unused = sorted(actual - variables), sorted(variables - actual)
+                if undeclared:
+                    findings["variableMismatches"].append({"template": f"{alias}.{locale}", "source": source, "undeclared": undeclared})
+                if unused and source == "local":
+                    findings["variableMismatches"].append({"template": f"{alias}.{locale}", "source": source, "unusedDeclared": unused})
+        if (alias, locale) in local and (alias, locale) in provider:
+            local_version, provider_version = local[(alias, locale)].get("version"), provider[(alias, locale)].get("version")
+            if local_version and provider_version and str(local_version) != str(provider_version):
+                findings["versionDrift"].append({"template": f"{alias}.{locale}", "local": local_version, "provider": provider_version})
+    for alias, locale in sorted(provider):
+        if alias not in catalogue_aliases:
+            findings["extraProvider"].append(f"{alias}.{locale}")
+    for alias, locale in sorted(local):
+        if alias not in catalogue_aliases:
+            findings["extraLocal"].append(f"{alias}.{locale}")
+    expected_locales: dict[str, set[str]] = {}
+    for alias, locale in expected:
+        expected_locales.setdefault(alias, set()).add(locale)
+    for table_name, table in (("local", local), ("provider", provider)):
+        present: dict[str, set[str]] = {}
+        for alias, locale in table:
+            present.setdefault(alias, set()).add(locale)
+        for alias, locales in present.items():
+            gaps = sorted(expected_locales.get(alias, set()) - locales)
+            if gaps and (table_name == "local" or alias in provider_aliases):
+                findings["localeGaps"].append({"alias": alias, "source": table_name, "missingLocales": gaps})
+    drift = any(findings[key] for key in findings)
+    return {
+        "schemaVersion": "maggie-notification-template-drift.v1",
+        "passed": not drift and not errors,
+        "provider": provider_name,
+        "compared": {"catalogue": len(expected), "local": len(local), "provider": len(provider)},
+        "findings": findings,
+        "errors": errors,
+        "next": "Review the diff, then sync with the project's sync --dry-run and an explicit apply; never send real messages to test a template." if drift else "",
+    }
+
+
+# --- provider preflight -----------------------------------------------------
+
+def env_names(files: list[Path]) -> tuple[set[str], dict[str, str]]:
+    names = {name for name, value in os.environ.items() if value}
+    template_values: dict[str, str] = {}
+    for file in files:
+        if not file.is_file():
+            continue
+        for line in file.read_text(encoding="utf-8", errors="replace").splitlines():
+            stripped = line.strip()
+            if not stripped or stripped.startswith("#") or "=" not in stripped:
+                continue
+            name, value = stripped.removeprefix("export ").split("=", 1)
+            name, value = name.strip(), value.strip().strip("'\"")
+            if value:
+                names.add(name)
+                if name == "RESEND_TEMPLATE_IDS_JSON":
+                    template_values[name] = value
+    if os.environ.get("RESEND_TEMPLATE_IDS_JSON") and "RESEND_TEMPLATE_IDS_JSON" not in template_values:
+        template_values["RESEND_TEMPLATE_IDS_JSON"] = os.environ["RESEND_TEMPLATE_IDS_JSON"]
+    return names, template_values
+
+
+def resend_preflight(project: Path, env_files: list[str], catalogue: dict | None, extra: list[str]) -> dict:
+    files = [project / item for item in env_files] if env_files else [project / ".env", project / ".env.production"]
+    names, template_values = env_names(files)
+    checks: dict[str, dict] = {}
+    errors: list[str] = []
+    warnings: list[str] = []
+    for check, accepted in RESEND_REQUIREMENTS:
+        present = [name for name in accepted if name in names]
+        checks[check] = {"present": bool(present), "names": list(accepted)}
+        if not present:
+            errors.append(f"{check}: set one of {', '.join(accepted)}")
+    for name in extra:
+        checks[name] = {"present": name in names, "names": [name]}
+        if name not in names:
+            errors.append(f"{name}: required variable is not set")
+    coverage: dict[str, object] = {}
+    if catalogue is not None:
+        expected = sorted(entry["alias"] for entry in catalogue.get("entries", []) if isinstance(entry, dict) and entry.get("provider") == "resend" and entry.get("status") == "implemented" and "email" in entry.get("channels", []))
+        mapped: set[str] = set()
+        raw = template_values.get("RESEND_TEMPLATE_IDS_JSON")
+        if raw:
+            try:
+                parsed = json.loads(raw)
+                mapped = {key.rsplit(".", 1)[0] if "." in key and LOCALE.match(key.rsplit(".", 1)[1]) else key for key in parsed} if isinstance(parsed, dict) else set()
+            except json.JSONDecodeError:
+                errors.append("template_map: RESEND_TEMPLATE_IDS_JSON is not valid JSON (value not shown)")
+        missing = [alias for alias in expected if alias not in mapped]
+        coverage = {"catalogueAliases": len(expected), "mappedAliases": len(mapped), "missing": missing, "unmapped": sorted(mapped - set(expected))}
+        if missing:
+            errors.append(f"template_map: {len(missing)} implemented Resend aliases have no template ID mapping")
+    warnings.append("Presence only: sending-domain verification, webhook reachability, timer health and authenticated synthetic delivery still need post-deploy evidence (see notifications health).")
+    return {"schemaVersion": "maggie-notification-provider-preflight.v1", "provider": "resend", "passed": not errors, "checks": checks, "templateCoverage": coverage, "errors": errors, "warnings": warnings, "valuesPrinted": False}
+
+
+# --- queue health -----------------------------------------------------------
+
+def queue_health(snapshot: dict, thresholds: dict, now: datetime) -> dict:
+    errors: list[str] = []
+    if snapshot.get("schemaVersion") != SNAPSHOT_SCHEMA:
+        errors.append(f"schemaVersion must be {SNAPSHOT_SCHEMA}")
+    if EMAIL.search(json.dumps(snapshot)):
+        errors.append("snapshot contains an email address; health evidence must be aggregate-only")
+    counts = snapshot.get("counts") if isinstance(snapshot.get("counts"), dict) else {}
+    alerts: list[dict] = []
+
+    def alert(code: str, observed: object, limit: object) -> None:
+        alerts.append({"code": code, "observed": observed, "threshold": limit, "channel": "operations", **ALERTS[code]})
+
+    pending = int(counts.get("pending", 0))
+    if pending > thresholds["max_pending"]:
+        alert("queue.pending_backlog", pending, thresholds["max_pending"])
+    dead = int(counts.get("deadLetter", 0))
+    if dead > thresholds["max_dead_letter"]:
+        alert("queue.dead_letter_growth", dead, thresholds["max_dead_letter"])
+    expired = int(snapshot.get("expiredLeases", 0))
+    if expired > thresholds["max_expired_leases"]:
+        alert("queue.expired_leases", expired, thresholds["max_expired_leases"])
+    ages: dict[str, float | None] = {}
+    for field, code, key in (("oldestPendingAt", "queue.oldest_pending_age", "max_oldest_pending_minutes"), ("lastWebhookAt", "webhook.lag", "max_webhook_lag_minutes"), ("lastSuccessfulRunAt", "worker.stale_run", "max_since_last_success_minutes")):
+        value = snapshot.get(field)
+        if value is None:
+            ages[field] = None
+            if field == "lastSuccessfulRunAt":
+                errors.append("lastSuccessfulRunAt is required; a timer can be active while the worker never succeeds")
+            continue
+        minutes = round((now - parse_time(value, field)).total_seconds() / 60, 1)
+        ages[field] = minutes
+        if field == "oldestPendingAt" and not pending:
+            continue
+        if field == "lastWebhookAt" and not int(counts.get("awaitingWebhook", 0)):
+            continue
+        if minutes > thresholds[key]:
+            alert(code, minutes, thresholds[key])
+    rates = snapshot.get("rates") if isinstance(snapshot.get("rates"), dict) else {}
+    if float(rates.get("bounce", 0)) > thresholds["max_bounce_rate"]:
+        alert("deliverability.bounce_rate", rates["bounce"], thresholds["max_bounce_rate"])
+    if float(rates.get("complaint", 0)) > thresholds["max_complaint_rate"]:
+        alert("deliverability.complaint_rate", rates["complaint"], thresholds["max_complaint_rate"])
+    if snapshot.get("senderDomainVerified") is False:
+        alert("deliverability.sender_domain", False, True)
+    critical = any(item["severity"] == "critical" for item in alerts)
+    return {
+        "schemaVersion": "maggie-notification-queue-health.v1",
+        "passed": not errors and not alerts,
+        "status": "failed" if errors or critical else ("degraded" if alerts else "healthy"),
+        "counts": {key: int(counts.get(key, 0)) for key in ("pending", "processing", "deadLetter", "awaitingWebhook")},
+        "ageMinutes": ages,
+        "thresholds": thresholds,
+        "alerts": alerts,
+        "errors": errors,
+    }
+
+
+# --- retention dry run ------------------------------------------------------
+
+def retention_plan(catalogue: dict, inventory: dict, now: datetime) -> dict:
+    errors: list[str] = []
+    if inventory.get("schemaVersion") != INVENTORY_SCHEMA:
+        errors.append(f"inventory schemaVersion must be {INVENTORY_SCHEMA}")
+    if EMAIL.search(json.dumps(inventory)):
+        errors.append("inventory contains an email address; provide aggregate counts only")
+    policy = catalogue.get("retention") if isinstance(catalogue.get("retention"), dict) else {}
+    plan: dict[str, dict[str, int]] = {}
+    for index, row in enumerate(inventory.get("records", [])):
+        kind = row.get("kind")
+        if kind not in RETENTION_KINDS:
+            errors.append(f"records[{index}].kind must be one of {', '.join(RETENTION_KINDS)}")
+            continue
+        days = policy.get(kind, {}).get("days") if isinstance(policy.get(kind), dict) else None
+        if not isinstance(days, int):
+            errors.append(f"catalogue retention.{kind}.days is missing")
+            continue
+        bucket = plan.setdefault(kind, {"retentionDays": days, "keep": 0, "purge": 0, "heldForSupport": 0})
+        count = int(row.get("count", 0))
+        if row.get("legalHold") or row.get("openSupportCase"):
+            bucket["heldForSupport"] += count
+        elif now - parse_time(row.get("createdBefore") or row.get("createdAt"), f"records[{index}].createdAt") > timedelta(days=days):
+            bucket["purge"] += count
+        else:
+            bucket["keep"] += count
+    return {"schemaVersion": "maggie-notification-retention-plan.v1", "passed": not errors, "dryRun": True, "plan": plan, "errors": errors, "note": "Dry run only. Apply purges through the host's reviewed migration/job; suppression entries keep a hashed address only."}
+
+
+# --- CLI -------------------------------------------------------------------
+
+def thresholds_from(args: argparse.Namespace) -> dict:
+    values = dict(DEFAULT_THRESHOLDS)
+    for key in DEFAULT_THRESHOLDS:
+        value = getattr(args, key, None)
+        if value is not None:
+            values[key] = value
+    return values
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="maggie ops notifications", description=__doc__)
+    parser.add_argument("--project", default=".")
+    sub = parser.add_subparsers(dest="area", required=True)
+
+    catalogue = sub.add_parser("catalogue", help="validate a website notification catalogue")
+    catalogue.add_argument("action", choices=("validate",))
+    catalogue.add_argument("--catalogue", required=True)
+
+    templates = sub.add_parser("templates", help="compare catalogue, local templates and a provider export")
+    templates.add_argument("action", choices=("drift",))
+    templates.add_argument("--catalogue", required=True)
+    templates.add_argument("--local", help="template directory (<alias>.<locale>.<ext>) or maggie-notification-templates.v1 manifest")
+    templates.add_argument("--provider-export", action="append", default=[], help="provider list export page; repeat for every page in order")
+    templates.add_argument("--provider", default="resend")
+
+    preflight = sub.add_parser("preflight", help="check provider configuration by variable name only")
+    preflight.add_argument("--provider", choices=("resend",), default="resend")
+    preflight.add_argument("--env-file", action="append", default=[])
+    preflight.add_argument("--catalogue")
+    preflight.add_argument("--require", action="append", default=[])
+
+    health = sub.add_parser("health", help="evaluate an aggregate queue snapshot against thresholds")
+    health.add_argument("--snapshot", required=True)
+    health.add_argument("--now")
+    for key, value in DEFAULT_THRESHOLDS.items():
+        health.add_argument("--" + key.replace("_", "-"), dest=key, type=type(value))
+
+    retention = sub.add_parser("retention", help="dry-run retention purge plan from aggregate inventory")
+    retention.add_argument("action", choices=("plan",))
+    retention.add_argument("--catalogue", required=True)
+    retention.add_argument("--inventory", required=True)
+    retention.add_argument("--now")
+
+    sub.add_parser("alerts", help="print operator alert templates")
+
+    args = parser.parse_args(argv)
+    project = Path(args.project).resolve()
+
+    def path(value: str) -> Path:
+        candidate = Path(value)
+        return candidate if candidate.is_absolute() else project / candidate
+
+    try:
+        if args.area == "catalogue":
+            return emit(validate_catalogue(load_json(path(args.catalogue))))
+        if args.area == "templates":
+            return emit(templates_drift(load_json(path(args.catalogue)), path(args.local) if args.local else None, [str(path(item)) for item in args.provider_export], args.provider))
+        if args.area == "preflight":
+            return emit(resend_preflight(project, args.env_file, load_json(path(args.catalogue)) if args.catalogue else None, args.require))
+        if args.area == "health":
+            now = parse_time(args.now, "--now") if args.now else datetime.now(timezone.utc)
+            return emit(queue_health(load_json(path(args.snapshot)), thresholds_from(args), now))
+        if args.area == "retention":
+            now = parse_time(args.now, "--now") if args.now else datetime.now(timezone.utc)
+            return emit(retention_plan(load_json(path(args.catalogue)), load_json(path(args.inventory)), now))
+        print(json.dumps({"schemaVersion": "maggie-notification-alerts.v1", "channel": "operations", "alerts": ALERTS}, indent=2))
+        return 0
+    except (OSError, ValueError, json.JSONDecodeError) as error:
+        print(json.dumps({"passed": False, "errors": [str(error)]}, indent=2))
+        return 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/bundled-tools/clis/maggie_ops.py

@@ -15,6 +15,8 @@ from seed_evidence import validate_manifest
 from agent_runtime import preflight as agent_preflight
 from restart_gate import validate as validate_restart_gate
 from google_capabilities import validate_report as validate_google_capability_report
+from google_remediation import classify as classify_google_failure
+import google_ads
 from maggie_favicon import check_favicon
 from external_write import validate as validate_external_write
 
@@ -187,11 +189,63 @@ def command_google_capabilities(args: argparse.Namespace) -> int:
             for item in result["providerResults"]
         ],
         "failedChecks": result["errors"],
+        "remediation": result["remediation"],
         "mutationsAllowed": False,
     }, indent=2, ensure_ascii=False))
     return 0 if result["passed"] else 1
 
 
+def command_google_diagnose(args: argparse.Namespace) -> int:
+    result = classify_google_failure({"code": args.code or "", "reason": args.reason or ""}, status=args.http_status, provider=args.provider)
+    print(json.dumps({"schemaVersion": "maggie-google-remediation.v1", **result}, indent=2, ensure_ascii=False))
+    return 0
+
+
+def env_secret(name: str) -> str | None:
+    import os
+    value = os.environ.get(name, "").strip()
+    return value or None
+
+
+def command_google_ads_preflight(args: argparse.Namespace) -> int:
+    result = google_ads.preflight(
+        customer_id=args.customer_id,
+        login_customer_id=args.login_customer_id,
+        access_token=env_secret(args.access_token_env),
+        developer_token=env_secret(args.developer_token_env),
+        api_version=args.api_version,
+        probe_keyword_planner=args.probe_keyword_planner,
+    )
+    if args.output:
+        write_json(Path(args.output).resolve(), result)
+    print(json.dumps(result, indent=2, ensure_ascii=False))
+    return 0 if result["passed"] else 1
+
+
+def command_google_ads_keyword_ideas(args: argparse.Namespace) -> int:
+    access_token = env_secret(args.access_token_env)
+    developer_token = env_secret(args.developer_token_env)
+    if not access_token or not developer_token:
+        raise ValueError(f"set {args.access_token_env} and {args.developer_token_env}; run google-ads-preflight first")
+    result = google_ads.keyword_ideas(
+        customer_id=args.customer_id,
+        login_customer_id=args.login_customer_id,
+        access_token=access_token,
+        developer_token=developer_token,
+        keywords=[item.strip() for item in args.keyword if item.strip()],
+        url=args.url,
+        language=args.language,
+        geo_targets=args.geo_target,
+        currency=args.currency,
+        max_pages=args.max_pages,
+        api_version=args.api_version,
+    )
+    if args.output:
+        write_json(Path(args.output).resolve(), result)
+    print(json.dumps(result, indent=2, ensure_ascii=False))
+    return 0 if result["passed"] else 1
+
+
 def command_external_write_gate(args: argparse.Namespace) -> int:
     evidence = read_json(Path(args.evidence).resolve())
     result = validate_external_write(evidence)
@@ -218,6 +272,12 @@ def command_favicon_check(args: argparse.Namespace) -> int:
 
 
 def main() -> int:
+    argv = sys.argv[1:]
+    positional = [item for index, item in enumerate(argv) if not item.startswith("-") and (index == 0 or argv[index - 1] != "--project")]
+    if positional and positional[0] == "notifications":
+        from maggie_notifications import main as notifications_main
+        argv.remove("notifications")
+        return notifications_main(argv)
     parser = argparse.ArgumentParser(description=__doc__)
     parser.add_argument("--project", default=".")
     sub = parser.add_subparsers(dest="command", required=True)
@@ -239,6 +299,33 @@ def main() -> int:
     google.add_argument("--report", required=True)
     google.add_argument("--output")
     google.set_defaults(func=command_google_capabilities)
+    diagnose = sub.add_parser("google-diagnose", help="map a redacted Google error code/reason to one prerequisite and safe next action")
+    diagnose.add_argument("--code", help="provider error code, e.g. SERVICE_DISABLED")
+    diagnose.add_argument("--reason", help="short redacted reason; never paste tokens or payloads")
+    diagnose.add_argument("--http-status", type=int)
+    diagnose.add_argument("--provider", choices=("gsc", "ga4", "gtm", "google-ads", "firebase"))
+    diagnose.set_defaults(func=command_google_diagnose)
+    for name, handler, help_text in (
+        ("google-ads-preflight", command_google_ads_preflight, "read-only Google Ads prerequisite checks (scope, developer token, customer IDs, access, hierarchy, Keyword Planner readiness)"),
+        ("google-ads-keyword-ideas", command_google_ads_keyword_ideas, "read-only KeywordPlanIdeaService request with normalized results"),
+    ):
+        ads = sub.add_parser(name, help=help_text)
+        ads.add_argument("--customer-id", required=True)
+        ads.add_argument("--login-customer-id")
+        ads.add_argument("--access-token-env", default="GOOGLE_ADS_ACCESS_TOKEN", help="environment variable holding a short-lived OAuth access token")
+        ads.add_argument("--developer-token-env", default="GOOGLE_ADS_DEVELOPER_TOKEN")
+        ads.add_argument("--api-version", default=google_ads.DEFAULT_API_VERSION)
+        ads.add_argument("--output")
+        if name == "google-ads-preflight":
+            ads.add_argument("--probe-keyword-planner", action="store_true", help="spend one read-only one-result Keyword Planner request")
+        else:
+            ads.add_argument("--keyword", action="append", default=[])
+            ads.add_argument("--url")
+            ads.add_argument("--language", help="language constant ID, e.g. 1000 for English")
+            ads.add_argument("--geo-target", action="append", default=[], help="geo target constant ID, e.g. 2826 for the UK")
+            ads.add_argument("--currency", help="customer currency code for bid display (from preflight)")
+            ads.add_argument("--max-pages", type=int, default=1)
+        ads.set_defaults(func=handler)
     external_write = sub.add_parser("external-write-gate", help="validate idempotent provider write/readback evidence")
     external_write.add_argument("--evidence", required=True)
     external_write.add_argument("--output")