@topy-ai/maggie 0.7.48 → 0.7.49

package/bundled-tools/clis/maggie_marketing_run.py

@@ -0,0 +1,272 @@
+#!/usr/bin/env python3
+"""Validate provider-neutral Maggie marketing runs and their named schedule layers.
+
+A marketing run (`maggie-marketing-run-v1`) is one project-scoped record that
+joins content, Social Share, Ads, and measurement work. It references source
+revisions, capability evidence, approvals, mutations, and readbacks by ID; it
+never copies provider secrets or large payloads.
+
+Schedule layers keep four different meanings of "when" apart:
+
+- `infrastructure`: when a worker wakes up (cron, systemd timer, queue);
+  validated by `maggie_schedule.py`.
+- `content_calendar`: when reviewed content or a social post may publish.
+- `campaign_flight`: when paid campaigns may run and spend.
+- `measurement_window`: the data collection and attribution period, including
+  conversion lag.
+
+No function in this module calls a provider, a model, or the network.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+from datetime import date, datetime
+from pathlib import Path
+from zoneinfo import ZoneInfo, ZoneInfoNotFoundError
+
+
+SCHEMA_VERSION = "maggie-marketing-run-v1"
+SCHEDULE_LAYERS = {
+    "infrastructure": "Operations: when a worker wakes up (cron/systemd/queue); never a publish time.",
+    "content_calendar": "Editor/marketer: when a reviewed content or social item may publish.",
+    "campaign_flight": "Ads owner: when a paid campaign may run and spend.",
+    "measurement_window": "Analytics: data collection and attribution period, including conversion lag.",
+}
+LAYER_STATUSES = {"planned", "active", "paused", "completed", "cancelled"}
+RUN_MODES = {"draft", "scheduled", "executing", "completed", "cancelled"}
+APPROVAL_STATES = {"pending", "approved", "rejected", "not_required"}
+MUTATION_STATUSES = {"planned", "pending", "succeeded", "failed", "cancelled"}
+MUTATION_KINDS = {"external_publication", "ads_change", "content_delivery", "draft_creation", "configuration"}
+# Workflow stages a regulated-content policy may annotate. Only external
+# publication can be gated by the policy review; everything else continues.
+STAGES = ("delivery", "draft", "seo_geo", "measurement", "external_publication")
+POLICY_GATED_STAGES = {"external_publication"}
+REVIEW_STATES = {"not_required", "pending", "approved", "rejected"}
+SECRET_KEY = re.compile(r"(?:^|_)(?:secret|token|password|api_?key|authorization|cookie)s?$", re.I)
+SECRET_VALUE = re.compile(r"^(?:Bearer\s|sk_(?:live|test)_|ya29\.|AIza)", re.I)
+RUN_ID = re.compile(r"^[a-z0-9][a-z0-9._-]{2,127}$")
+
+
+def _day(value: object) -> date | None:
+    if not isinstance(value, str):
+        return None
+    try:
+        return datetime.fromisoformat(value.replace("Z", "+00:00")).date() if "T" in value else date.fromisoformat(value)
+    except ValueError:
+        return None
+
+
+def _zone(value: object) -> bool:
+    if not isinstance(value, str) or not value:
+        return False
+    try:
+        ZoneInfo(value)
+    except (ZoneInfoNotFoundError, ValueError):
+        return False
+    return True
+
+
+def _secrets(value: object, path: str, found: list[str]) -> None:
+    if isinstance(value, dict):
+        for key, item in value.items():
+            if SECRET_KEY.search(str(key)) and not str(key).endswith(("_ref", "Ref")):
+                found.append(f"{path}.{key}")
+            _secrets(item, f"{path}.{key}", found)
+    elif isinstance(value, list):
+        for index, item in enumerate(value):
+            _secrets(item, f"{path}[{index}]", found)
+    elif isinstance(value, str) and SECRET_VALUE.search(value):
+        found.append(path)
+
+
+def validate_layers(layers: object, *, label: str = "scheduleLayers") -> tuple[list[str], list[str]]:
+    """Validate named schedule layers shared by maggie-schedule, Social Share, Ads, and analytics."""
+    errors: list[str] = []
+    warnings: list[str] = []
+    if not isinstance(layers, list) or not layers:
+        return [f"{label} must be a non-empty list"], warnings
+    seen: set[tuple[str, str]] = set()
+    for index, layer in enumerate(layers):
+        prefix = f"{label}[{index}]"
+        if not isinstance(layer, dict):
+            errors.append(f"{prefix} must be an object")
+            continue
+        name = layer.get("layer")
+        if name not in SCHEDULE_LAYERS:
+            errors.append(f"{prefix}.layer must be one of {', '.join(SCHEDULE_LAYERS)}")
+            continue
+        key = (name, str(layer.get("id") or ""))
+        if key in seen:
+            errors.append(f"{prefix} duplicates layer {name} id {key[1] or '(none)'}")
+        seen.add(key)
+        if not _zone(layer.get("timezone")):
+            errors.append(f"{prefix}.timezone must be an IANA time zone")
+        for field in ("owner", "reconciliation"):
+            if not isinstance(layer.get(field), str) or not layer[field].strip():
+                errors.append(f"{prefix}.{field} is required")
+        if layer.get("status") not in LAYER_STATUSES:
+            errors.append(f"{prefix}.status must be one of {', '.join(sorted(LAYER_STATUSES))}")
+        if name == "infrastructure":
+            if not layer.get("scheduleRef"):
+                errors.append(f"{prefix}.scheduleRef must point at the maggie-schedule job (infrastructure has no publish time)")
+            if "start" in layer or "end" in layer:
+                warnings.append(f"{prefix} infrastructure layers describe wake-up intervals; start/end are ignored")
+            continue
+        start, end = _day(layer.get("start")), _day(layer.get("end"))
+        if not start:
+            errors.append(f"{prefix}.start must be an ISO date or date-time")
+        if name != "content_calendar" and not end:
+            errors.append(f"{prefix}.end is required for {name}")
+        if start and end and end < start:
+            errors.append(f"{prefix}.end is before start")
+        if name == "measurement_window" and not isinstance(layer.get("lagDays"), int):
+            warnings.append(f"{prefix}.lagDays is not set; attribution lag will be ignored")
+    return errors, warnings
+
+
+def validate_policy(policy: object, stages: object, mutations: list) -> tuple[list[str], list[str]]:
+    """Regulated-content review gates only external publication (default off, backward compatible)."""
+    errors: list[str] = []
+    warnings: list[str] = []
+    if policy is None:
+        policy = {}
+    if not isinstance(policy, dict):
+        return ["policy must be an object"], warnings
+    required = bool(policy.get("regulatedContent") and policy.get("reviewRequired", True))
+    review = policy.get("reviewState", "pending" if required else "not_required")
+    if review not in REVIEW_STATES:
+        errors.append(f"policy.reviewState must be one of {', '.join(sorted(REVIEW_STATES))}")
+    if isinstance(stages, dict):
+        for stage, state in stages.items():
+            if stage not in STAGES:
+                errors.append(f"stages.{stage} is not a known stage ({', '.join(STAGES)})")
+                continue
+            blocked = isinstance(state, dict) and state.get("status") == "blocked" and state.get("reason") == "policy_review"
+            if blocked and stage not in POLICY_GATED_STAGES:
+                errors.append(f"stages.{stage} is blocked by policy review; regulated-content review may only gate "
+                              "external publication — delivery, drafts, SEO/GEO and measurement must continue")
+    elif stages is not None:
+        errors.append("stages must be an object keyed by stage")
+    if required and review != "approved":
+        for mutation in mutations:
+            if isinstance(mutation, dict) and mutation.get("kind") == "external_publication" and mutation.get("status") in {"pending", "succeeded"}:
+                errors.append(f"mutation {mutation.get('mutationId')} publishes regulated content before policy review is approved")
+        if review == "pending":
+            warnings.append("regulated-content review is pending; external publication stays held, other stages continue")
+    return errors, warnings
+
+
+def validate_run(run: object) -> dict:
+    errors: list[str] = []
+    warnings: list[str] = []
+    if not isinstance(run, dict):
+        return {"valid": False, "errors": ["marketing run must be a JSON object"], "warnings": []}
+    if run.get("schemaVersion") != SCHEMA_VERSION:
+        errors.append(f"schemaVersion must be {SCHEMA_VERSION}")
+    if not isinstance(run.get("runId"), str) or not RUN_ID.match(run["runId"]):
+        errors.append("runId must be a lowercase slug (3-128 chars)")
+    for field in ("projectRef", "objective"):
+        if not isinstance(run.get(field), str) or not run[field].strip():
+            errors.append(f"{field} is required")
+    conversion = run.get("conversion")
+    if not isinstance(conversion, dict) or not conversion.get("event") or not conversion.get("source"):
+        errors.append("conversion needs event and source")
+    channels = run.get("channels")
+    if not isinstance(channels, list) or not channels or not all(isinstance(item, str) and item for item in channels):
+        errors.append("channels must be a non-empty list of channel names")
+    if not _zone(run.get("timezone")):
+        errors.append("timezone must be an IANA time zone")
+    if run.get("mode") not in RUN_MODES:
+        errors.append(f"mode must be one of {', '.join(sorted(RUN_MODES))}")
+    if "scheduled_at" in run or "scheduledAt" in run:
+        errors.append("a run must not carry a single scheduled_at; use named scheduleLayers")
+    for index, revision in enumerate(run.get("sourceRevisions") or []):
+        if not isinstance(revision, dict) or not revision.get("sourceId") or not revision.get("revision"):
+            errors.append(f"sourceRevisions[{index}] needs sourceId and revision")
+    for index, ref in enumerate(run.get("capabilityEvidence") or []):
+        if not isinstance(ref, str) or not ref:
+            errors.append(f"capabilityEvidence[{index}] must be an evidence ID or path reference")
+    approval = run.get("approval")
+    if not isinstance(approval, dict) or approval.get("state") not in APPROVAL_STATES:
+        errors.append(f"approval.state must be one of {', '.join(sorted(APPROVAL_STATES))}")
+        approval = {}
+    if approval.get("state") == "approved" and not (approval.get("actor") and approval.get("approvalId")):
+        errors.append("an approved run needs approval.actor and approval.approvalId")
+    layer_errors, layer_warnings = validate_layers(run.get("scheduleLayers"))
+    errors += layer_errors
+    warnings += layer_warnings
+    mutations = run.get("mutations") or []
+    if not isinstance(mutations, list):
+        errors.append("mutations must be a list")
+        mutations = []
+    mutation_ids: set[str] = set()
+    for index, mutation in enumerate(mutations):
+        prefix = f"mutations[{index}]"
+        if not isinstance(mutation, dict) or not mutation.get("mutationId"):
+            errors.append(f"{prefix} needs mutationId")
+            continue
+        mutation_ids.add(mutation["mutationId"])
+        if mutation.get("kind") not in MUTATION_KINDS:
+            errors.append(f"{prefix}.kind must be one of {', '.join(sorted(MUTATION_KINDS))}")
+        if mutation.get("status") not in MUTATION_STATUSES:
+            errors.append(f"{prefix}.status must be one of {', '.join(sorted(MUTATION_STATUSES))}")
+        if mutation.get("kind") in {"external_publication", "ads_change"}:
+            if not mutation.get("idempotencyKey"):
+                errors.append(f"{prefix} external mutation needs an idempotencyKey")
+            if mutation.get("status") in {"pending", "succeeded"} and approval.get("state") != "approved":
+                errors.append(f"{prefix} executed before the run was approved")
+    readback_refs = set()
+    for index, readback in enumerate(run.get("readbacks") or []):
+        if not isinstance(readback, dict) or not readback.get("readbackId"):
+            errors.append(f"readbacks[{index}] needs readbackId")
+            continue
+        ref = readback.get("mutationRef")
+        if ref and ref not in mutation_ids:
+            errors.append(f"readbacks[{index}].mutationRef {ref} does not match a mutation")
+        readback_refs.add(ref)
+    for mutation in mutations:
+        if isinstance(mutation, dict) and mutation.get("status") == "succeeded" and mutation.get("mutationId") not in readback_refs:
+            message = f"mutation {mutation.get('mutationId')} succeeded without a readback reference"
+            (errors if run.get("mode") == "completed" else warnings).append(message)
+    policy_errors, policy_warnings = validate_policy(run.get("policy"), run.get("stages"), mutations)
+    errors += policy_errors
+    warnings += policy_warnings
+    leaked: list[str] = []
+    _secrets(run, "run", leaked)
+    if leaked:
+        errors.append("run must reference secrets, not contain them: " + ", ".join(leaked))
+    return {"valid": not errors, "errors": errors, "warnings": warnings,
+            "runId": run.get("runId"), "layers": sorted({layer.get("layer") for layer in run.get("scheduleLayers") or [] if isinstance(layer, dict)} - {None})}
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    sub = parser.add_subparsers(dest="command", required=True)
+    check = sub.add_parser("validate", help="validate a maggie-marketing-run-v1 document")
+    check.add_argument("input")
+    layers = sub.add_parser("layers", help="validate a scheduleLayers list, or print the layer model with no input")
+    layers.add_argument("input", nargs="?")
+    args = parser.parse_args()
+    try:
+        if args.command == "layers" and not args.input:
+            print(json.dumps({"layers": SCHEDULE_LAYERS}, indent=2))
+            return 0
+        value = json.loads(Path(args.input).read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError) as error:
+        parser.error(str(error))
+        return 2
+    if args.command == "validate":
+        result = validate_run(value)
+    else:
+        items = value.get("scheduleLayers") if isinstance(value, dict) else value
+        errors, warnings = validate_layers(items)
+        result = {"valid": not errors, "errors": errors, "warnings": warnings}
+    print(json.dumps(result, indent=2, ensure_ascii=False))
+    return 0 if result["valid"] else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())