@topy-ai/maggie 0.7.48 → 0.7.49

package/bundled-tools/clis/maggie_email_localization.py

@@ -0,0 +1,382 @@
+#!/usr/bin/env python3
+"""Check localized email templates and consent-aware lifecycle email plans.
+
+Both commands are read-only validators. They never render with real customer
+data, call a provider, or send email. ``email-matrix`` can write preview files
+filled from declared fixtures for human review.
+"""
+
+from __future__ import annotations
+
+import argparse
+import html
+import json
+import re
+import sys
+from pathlib import Path
+
+EMAIL_SCHEMA = "maggie-email-localization.v1"
+LIFECYCLE_SCHEMA = "maggie-lifecycle-email.v1"
+
+LOCALE_SOURCES = ("user", "market", "account", "fallback")
+UNSAFE_LOCALE_SOURCES = ("accept-language", "hard-coded")
+FIELDS = ("subject", "html", "text")
+CATEGORIES = ("transactional", "support", "marketing")
+PLACEHOLDER = re.compile(r"\{\{\s*([A-Za-z_][\w.]*)\s*\}\}|\{([A-Za-z_][\w.]*)\}")
+TAG = re.compile(r"<[^>]+>")
+
+LIFECYCLE_STAGES = ("plan", "segment", "consent-check", "preview", "approve", "schedule", "send", "report")
+LIBRARY_KINDS = (
+    "opt-in-confirmation", "welcome", "digest", "recommendation", "gift-follow-up",
+    "voucher-follow-up", "waitlist-follow-up", "merchant-lead-digest",
+    "campaign-announcement", "re-engagement",
+)
+CONSENT_BASES = ("opt-in", "double-opt-in", "soft-opt-in", "legitimate-interest-b2b")
+# The confirmation request is sent before marketing consent exists, so it is
+# transactional and needs no unsubscribe link, but it still has a frequency cap.
+PRE_CONSENT_KINDS = ("opt-in-confirmation",)
+
+
+def placeholders(value: str) -> set[str]:
+    return {a or b for a, b in PLACEHOLDER.findall(value or "")}
+
+
+def visible_text(value: str) -> str:
+    stripped = PLACEHOLDER.sub("", TAG.sub(" ", value or ""))
+    return re.sub(r"\s+", " ", html.unescape(stripped)).strip()
+
+
+def language(locale: str) -> str:
+    return (locale or "").split("-")[0].lower()
+
+
+def route_ok(route: str) -> bool:
+    return isinstance(route, str) and (route.startswith("/") or route.startswith("https://"))
+
+
+def check_locale_resolution(template: dict, errors: list[str]) -> None:
+    tid = template.get("id")
+    order = template.get("localeResolution")
+    if not isinstance(order, list) or not order:
+        errors.append(f"{tid}: localeResolution must list the locale sources explicitly")
+        return
+    unsafe = [item for item in order if item in UNSAFE_LOCALE_SOURCES]
+    if unsafe:
+        errors.append(f"{tid}: localeResolution must not use {', '.join(unsafe)}; resolve from user, market, account, then fallback")
+    known = [item for item in order if item in LOCALE_SOURCES]
+    if known != [item for item in LOCALE_SOURCES if item in known]:
+        errors.append(f"{tid}: localeResolution precedence must be user > market > account > fallback")
+    if order[-1] != "fallback":
+        errors.append(f"{tid}: localeResolution must end with fallback")
+
+
+def check_call_sites(manifest: dict, errors: list[str], warnings: list[str]) -> None:
+    templates = {item.get("id"): item for item in manifest.get("templates", []) if isinstance(item, dict)}
+    for site in manifest.get("callSites", []) or []:
+        source = site.get("localeSource")
+        tid = site.get("template")
+        label = f"call site {site.get('id') or tid}"
+        if tid not in templates:
+            errors.append(f"{label}: unknown template {tid}")
+        if source == "hard-coded":
+            errors.append(f"{label}: sends with a hard-coded locale; pass the resolved recipient locale")
+        elif source == "accept-language":
+            category = templates.get(tid, {}).get("category")
+            if site.get("path") == "fulfilment" or category == "transactional":
+                errors.append(f"{label}: fulfilment/transactional email must not use Accept-Language alone; resolve user > market > account > fallback")
+            else:
+                warnings.append(f"{label}: Accept-Language is only a hint; prefer a stored user or market locale")
+        elif source not in ("resolved",) + LOCALE_SOURCES:
+            errors.append(f"{label}: localeSource must be resolved, user, market, account or fallback")
+
+
+def check_template(manifest: dict, template: dict, preview_dir: Path | None, errors: list[str], warnings: list[str]) -> list[dict]:
+    tid = template.get("id") or "<unnamed>"
+    source_locale = manifest.get("sourceLocale")
+    required = template.get("requiredLocales") or manifest.get("locales") or []
+    declared = set(template.get("variables") or [])
+    markets = manifest.get("markets") or {}
+    glossary = manifest.get("glossary") or []
+    if template.get("category") not in CATEGORIES:
+        errors.append(f"{tid}: category must be one of {', '.join(CATEGORIES)}")
+    check_locale_resolution(template, errors)
+    locales = template.get("locales") or {}
+    source = locales.get(source_locale) or {}
+    if not source:
+        errors.append(f"{tid}: missing source locale {source_locale}")
+    rows = []
+    for locale in required:
+        entry = locales.get(locale)
+        if not isinstance(entry, dict):
+            errors.append(f"{tid}: missing locale {locale}")
+            continue
+        for field in FIELDS:
+            if not isinstance(entry.get(field), str) or not entry[field].strip():
+                errors.append(f"{tid}/{locale}: missing {field}")
+        used = set()
+        for field in FIELDS:
+            value = entry.get(field) or ""
+            found = placeholders(value)
+            used |= found
+            undeclared = found - declared
+            if undeclared:
+                errors.append(f"{tid}/{locale}: {field} uses undeclared variables {', '.join(sorted(undeclared))}")
+            if locale != source_locale and source.get(field):
+                expected = placeholders(source[field])
+                if found != expected:
+                    missing, extra = sorted(expected - found), sorted(found - expected)
+                    errors.append(f"{tid}/{locale}: {field} variables changed from source (missing {missing or '[]'}, extra {extra or '[]'})")
+                if language(locale) != language(source_locale) and visible_text(value) and visible_text(value) == visible_text(source[field]):
+                    errors.append(f"{tid}/{locale}: {field} is identical to the source text (untranslated)")
+        if placeholders(entry.get("html", "")) != placeholders(entry.get("text", "")):
+            errors.append(f"{tid}/{locale}: HTML and plain-text bodies use different variables")
+        route = entry.get("ctaRoute", template.get("cta", {}).get("route"))
+        if template.get("cta") or entry.get("ctaRoute"):
+            if not route_ok(route):
+                errors.append(f"{tid}/{locale}: CTA route must be a site path or https URL")
+            else:
+                market = entry.get("market")
+                prefix = (markets.get(market) or {}).get("routePrefix") if market else None
+                if market and market not in markets:
+                    errors.append(f"{tid}/{locale}: unknown market {market}")
+                elif prefix and route.startswith("/") and not (route == prefix or route.startswith(prefix.rstrip("/") + "/")):
+                    errors.append(f"{tid}/{locale}: CTA route {route} does not use market prefix {prefix}")
+                if market and locale not in ((markets.get(market) or {}).get("locales") or [locale]):
+                    errors.append(f"{tid}/{locale}: market {market} does not serve locale {locale}")
+                base = template.get("cta", {}).get("route") or ""
+                if placeholders(route) != placeholders(base) and base:
+                    errors.append(f"{tid}/{locale}: CTA route parameters differ from the template route")
+                for field in ("html", "text"):
+                    body = entry.get(field) or ""
+                    if route.split("{")[0] and route.split("{")[0] not in body and "{{ctaUrl}}" not in body and "{ctaUrl}" not in body:
+                        warnings.append(f"{tid}/{locale}: {field} body does not include the CTA route or {{{{ctaUrl}}}}")
+        if locale != source_locale:
+            for term in glossary:
+                if term.get("locale") != locale:
+                    continue
+                src_term, target = str(term.get("term", "")), str(term.get("translation", ""))
+                if src_term and src_term.lower() in visible_text(source.get("text", "")).lower() and target and target not in (entry.get("text") or ""):
+                    warnings.append(f"{tid}/{locale}: glossary term '{src_term}' is not rendered as '{target}'")
+        approval = entry.get("approval") or {}
+        approved = approval.get("status") == "approved" and bool(approval.get("reviewer"))
+        if not approved:
+            warnings.append(f"{tid}/{locale}: not approved; not publishable")
+        rows.append({"template": tid, "locale": locale, "market": entry.get("market"), "approved": approved})
+        if preview_dir is not None:
+            write_preview(preview_dir, tid, locale, entry, template.get("fixtures") or {}, route)
+    unused = declared - set().union(*(placeholders((locales.get(l) or {}).get(f, "")) for l in required for f in FIELDS)) if required else set()
+    if unused:
+        warnings.append(f"{tid}: declared variables never used: {', '.join(sorted(unused))}")
+    return rows
+
+
+def fill(value: str, fixtures: dict, escape: bool) -> str:
+    def replace(match: re.Match) -> str:
+        key = match.group(1) or match.group(2)
+        raw = str(fixtures.get(key, f"[{key}]"))
+        return html.escape(raw) if escape else raw
+    return PLACEHOLDER.sub(replace, value or "")
+
+
+def safe_name(value: str) -> str:
+    return re.sub(r"[^A-Za-z0-9_.-]+", "-", value).strip("-") or "template"
+
+
+def write_preview(directory: Path, tid: str, locale: str, entry: dict, fixtures: dict, route: str | None) -> None:
+    directory.mkdir(parents=True, exist_ok=True)
+    stem = f"{safe_name(tid)}.{safe_name(locale)}"
+    subject = fill(entry.get("subject", ""), fixtures, escape=False)
+    banner = f"<p data-maggie-preview>Preview only — fixture data, not sent. Subject: {html.escape(subject)}. CTA: {html.escape(str(route or ''))}</p>"
+    (directory / f"{stem}.html").write_text(banner + fill(entry.get("html", ""), fixtures, escape=True), encoding="utf-8")
+    (directory / f"{stem}.txt").write_text(f"Subject: {subject}\n\n" + fill(entry.get("text", ""), fixtures, escape=False), encoding="utf-8")
+
+
+def email_matrix(manifest: dict, preview_dir: Path | None = None, require_approved: bool = False) -> dict:
+    errors: list[str] = []
+    warnings: list[str] = []
+    if manifest.get("schemaVersion") != EMAIL_SCHEMA:
+        errors.append(f"schemaVersion must be {EMAIL_SCHEMA}")
+    if not manifest.get("sourceLocale"):
+        errors.append("sourceLocale is required")
+    templates = manifest.get("templates")
+    if not isinstance(templates, list) or not templates:
+        errors.append("templates must be a non-empty list")
+        templates = []
+    seen: set[str] = set()
+    rows: list[dict] = []
+    for template in templates:
+        if not isinstance(template, dict):
+            errors.append("template entries must be objects")
+            continue
+        if template.get("id") in seen:
+            errors.append(f"duplicate template id {template.get('id')}")
+        seen.add(template.get("id"))
+        rows.extend(check_template(manifest, template, preview_dir, errors, warnings))
+    check_call_sites(manifest, errors, warnings)
+    if require_approved:
+        errors.extend(f"{row['template']}/{row['locale']}: approval required" for row in rows if not row["approved"])
+    return {
+        "schemaVersion": "maggie-email-localization-report.v1",
+        "status": "failed" if errors else "passed",
+        "templates": len(seen),
+        "matrix": rows,
+        "publishable": not errors and all(row["approved"] for row in rows),
+        "errors": errors,
+        "warnings": warnings,
+        "previewDir": str(preview_dir) if preview_dir else None,
+        "sends": False,
+    }
+
+
+def approved(record: dict | None) -> bool:
+    return isinstance(record, dict) and record.get("status") == "approved" and bool(record.get("reviewer")) and bool(record.get("approvedAt"))
+
+
+def lifecycle_validate(plan: dict) -> dict:
+    errors: list[str] = []
+    warnings: list[str] = []
+    if plan.get("schemaVersion") != LIFECYCLE_SCHEMA:
+        errors.append(f"schemaVersion must be {LIFECYCLE_SCHEMA}")
+    stages = plan.get("stages")
+    if stages != list(LIFECYCLE_STAGES):
+        errors.append(f"stages must be exactly {', '.join(LIFECYCLE_STAGES)} in order")
+    if (plan.get("defaults") or {}).get("send") != "disabled":
+        errors.append("defaults.send must be 'disabled' (no send until approved)")
+    templates = plan.get("templates") or []
+    ids: dict[str, dict] = {}
+    for template in templates:
+        tid = template.get("id") or "<unnamed>"
+        if tid in ids:
+            errors.append(f"duplicate template id {tid}")
+        ids[tid] = template
+        kind = template.get("kind")
+        category = template.get("category")
+        if kind not in LIBRARY_KINDS:
+            errors.append(f"{tid}: kind must be one of {', '.join(LIBRARY_KINDS)}")
+        if category not in CATEGORIES:
+            errors.append(f"{tid}: category must be one of {', '.join(CATEGORIES)}")
+        if kind in PRE_CONSENT_KINDS:
+            if category != "transactional":
+                errors.append(f"{tid}: opt-in confirmation is sent before consent and must be transactional, with no promotional content")
+        elif category == "marketing":
+            consent = template.get("consent") or {}
+            if consent.get("basis") not in CONSENT_BASES:
+                errors.append(f"{tid}: marketing template needs consent.basis ({', '.join(CONSENT_BASES)})")
+            if not consent.get("category"):
+                errors.append(f"{tid}: marketing template needs consent.category (preference-centre category)")
+            if not route_ok((template.get("unsubscribe") or {}).get("path")):
+                errors.append(f"{tid}: marketing template needs an unsubscribe path")
+            if not route_ok(template.get("preferenceCentre")):
+                errors.append(f"{tid}: marketing template needs a preference-centre path")
+            attribution = (template.get("attribution") or {}).get("fields") or []
+            if not attribution:
+                errors.append(f"{tid}: marketing template needs attribution fields (e.g. source, utm_campaign)")
+        elif category == "transactional" and kind not in PRE_CONSENT_KINDS:
+            warnings.append(f"{tid}: {kind} is normally marketing; confirm it carries no promotional content")
+        frequency = template.get("frequency") or {}
+        if not (isinstance(frequency.get("maxPerWindow"), int) and frequency["maxPerWindow"] >= 1 and frequency.get("window")):
+            errors.append(f"{tid}: frequency needs maxPerWindow >= 1 and a window (e.g. P7D)")
+        if template.get("sendable") and not approved(template.get("approval")):
+            errors.append(f"{tid}: sendable without an approved approval record (status, reviewer, approvedAt)")
+    for campaign in plan.get("campaigns") or []:
+        cid = campaign.get("id") or "<unnamed>"
+        for tid in campaign.get("templates") or []:
+            if tid not in ids:
+                errors.append(f"campaign {cid}: unknown template {tid}")
+            elif campaign.get("sendable") and not ids[tid].get("sendable"):
+                errors.append(f"campaign {cid}: template {tid} is not approved for sending")
+        audience = campaign.get("audience") or {}
+        uses_marketing = any(ids.get(tid, {}).get("category") == "marketing" for tid in campaign.get("templates") or [])
+        if uses_marketing and not audience.get("requiresConsent"):
+            errors.append(f"campaign {cid}: marketing audience must require consent")
+        if not audience.get("suppression"):
+            errors.append(f"campaign {cid}: audience must honour suppression")
+        if not audience.get("dedupe"):
+            errors.append(f"campaign {cid}: audience must deduplicate contacts")
+        if campaign.get("sendable") and not approved(campaign.get("approval")):
+            errors.append(f"campaign {cid}: sendable without an approved approval record")
+        if campaign.get("sendable") and not campaign.get("schedule"):
+            errors.append(f"campaign {cid}: sendable campaign needs a schedule")
+        if not (campaign.get("report") or {}).get("metrics"):
+            warnings.append(f"campaign {cid}: no aggregate report metrics declared")
+    missing = [kind for kind in LIBRARY_KINDS if kind not in {t.get("kind") for t in templates}]
+    return {
+        "schemaVersion": "maggie-lifecycle-email-report.v1",
+        "status": "failed" if errors else "passed",
+        "templates": len(ids),
+        "sendable": sorted(tid for tid, item in ids.items() if item.get("sendable")),
+        "libraryCoverage": {"missing": missing},
+        "errors": errors,
+        "warnings": warnings,
+        "sends": False,
+    }
+
+
+def library() -> dict:
+    """A starter plan: every template drafted, nothing sendable."""
+    templates = []
+    for kind in LIBRARY_KINDS:
+        pre = kind in PRE_CONSENT_KINDS
+        entry = {
+            "id": kind,
+            "kind": kind,
+            "category": "transactional" if pre else "marketing",
+            "frequency": {"maxPerWindow": 1, "window": "P1D" if pre else "P7D"},
+            "approval": {"status": "pending"},
+            "sendable": False,
+        }
+        if not pre:
+            entry.update({
+                "consent": {"basis": "opt-in", "category": "marketing.updates"},
+                "unsubscribe": {"path": "/email/unsubscribe/{token}"},
+                "preferenceCentre": "/account/notifications",
+                "attribution": {"fields": ["source", "utm_source", "utm_medium", "utm_campaign"]},
+            })
+        templates.append(entry)
+    return {"schemaVersion": LIFECYCLE_SCHEMA, "stages": list(LIFECYCLE_STAGES), "defaults": {"send": "disabled"}, "templates": templates, "campaigns": []}
+
+
+def load(path: Path) -> dict:
+    data = json.loads(path.read_text(encoding="utf-8"))
+    if not isinstance(data, dict):
+        raise ValueError(f"{path} must contain a JSON object")
+    return data
+
+
+def add_parsers(sub: argparse._SubParsersAction) -> None:
+    matrix = sub.add_parser("email-matrix", help="Check localized email templates (locales, variables, routes, parity, approval)")
+    matrix.add_argument("manifest", type=Path)
+    matrix.add_argument("--preview-dir", type=Path, help="write fixture-filled HTML/text previews for review")
+    matrix.add_argument("--require-approved", action="store_true", help="fail when any template locale is not approved")
+    lifecycle = sub.add_parser("lifecycle", help="Validate a consent-aware lifecycle/marketing email plan; never sends")
+    lifecycle.add_argument("plan", type=Path, nargs="?")
+    lifecycle.add_argument("--library", action="store_true", help="print the starter template library (nothing sendable)")
+
+
+def run(args: argparse.Namespace) -> int:
+    if args.command == "email-matrix":
+        result = email_matrix(load(args.manifest), args.preview_dir, args.require_approved)
+    else:
+        if args.library:
+            print(json.dumps(library(), indent=2))
+            return 0
+        if not args.plan:
+            raise ValueError("lifecycle needs a plan file or --library")
+        result = lifecycle_validate(load(args.plan))
+    print(json.dumps(result, indent=2, ensure_ascii=False))
+    return 0 if result["status"] == "passed" else 1
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    add_parsers(parser.add_subparsers(dest="command", required=True))
+    args = parser.parse_args()
+    try:
+        return run(args)
+    except (OSError, ValueError, json.JSONDecodeError) as error:
+        print(f"ERROR: {error}", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/bundled-tools/clis/maggie_feedback.py

@@ -382,7 +382,14 @@ def list_feedback(args: argparse.Namespace) -> int:
 
 def collect_batch(args: argparse.Namespace) -> int:
     """Create one privacy-safe draft per item while retaining shared batch context."""
-    manifest = load_json(Path(args.batch_file).expanduser().resolve())
+    if args.batch_file == "-":
+        # Reading JSON from stdin lets a quoted heredoc carry multiline text and
+        # backticks without shell interpolation.
+        manifest = json.loads(sys.stdin.read())
+        if not isinstance(manifest, dict):
+            raise ValueError("batch input must be a JSON object")
+    else:
+        manifest = load_json(Path(args.batch_file).expanduser().resolve())
     batch_id = safe_text(manifest.get("batchId"))
     if not SAFE_BATCH_ID_RE.fullmatch(batch_id):
         raise ValueError("batch file requires a safe batchId")
@@ -655,7 +662,7 @@ def main() -> int:
     collect_parser.add_argument("--relationship", dest="relationships", action="append", default=[], help="safe relation=target pointer")
     batch_parser = sub.add_parser("batch")
     batch_parser.add_argument("--project", default=argparse.SUPPRESS)
-    batch_parser.add_argument("--batch-file", required=True)
+    batch_parser.add_argument("--batch-file", required=True, help="batch JSON file, or - to read JSON from stdin")
     summary_parser = sub.add_parser("session-summary", help="draft batch items from git commit subjects for review")
     summary_parser.add_argument("--project", default=argparse.SUPPRESS)
     summary_parser.add_argument("--since", required=True, help="git revision; commits after it are summarized")