@topy-ai/maggie 0.7.47 → 0.7.49

package/bundled-tools/clis/maggie_palette.py

@@ -0,0 +1,280 @@
+#!/usr/bin/env python3
+"""Generate and validate a semantic palette role contract for a template.
+
+A template exposes colour roles instead of raw hex values in markup. The
+signature palette is the template's own; variants are derived from it by
+moving hue while keeping lightness, capping accent saturation, and forcing
+the contrast rules that make the roles safe to swap without editing markup.
+The command is deterministic and makes no network or model calls.
+"""
+
+from __future__ import annotations
+
+import argparse
+import colorsys
+import json
+import re
+import sys
+from pathlib import Path
+
+SCHEMA_VERSION = "maggie-palette-roles-v1"
+ROLES = ("canvas", "panel", "soft", "text", "accent", "accentText", "onAccent", "dark", "deep")
+HEX = re.compile(r"^#[0-9A-Fa-f]{6}$")
+MIN_TEXT_CONTRAST = 4.5
+DEFAULT_MAX_SATURATION = 0.65
+DEFAULT_VARIANT_COUNT = 17
+MIN_HUE_DISTANCE = 15.0
+
+# Named hue anchors used for variants. Order is the output order.
+HUE_ANCHORS = (
+    ("rose", "Rose", 350), ("coral", "Coral", 10), ("terracotta", "Terracotta", 20),
+    ("amber", "Amber", 36), ("ochre", "Ochre", 45), ("olive", "Olive", 65),
+    ("moss", "Moss", 90), ("sage", "Sage", 130), ("jade", "Jade", 155),
+    ("teal", "Teal", 178), ("lagoon", "Lagoon", 190), ("ocean", "Ocean", 205),
+    ("cobalt", "Cobalt", 220), ("indigo", "Indigo", 240), ("iris", "Iris", 258),
+    ("violet", "Violet", 275), ("plum", "Plum", 300), ("orchid", "Orchid", 322),
+)
+
+
+def parse_hex(value: str) -> tuple[float, float, float]:
+    if not isinstance(value, str) or not HEX.match(value):
+        raise ValueError(f"colour must be #RRGGBB: {value!r}")
+    return tuple(int(value[index:index + 2], 16) / 255 for index in (1, 3, 5))  # type: ignore[return-value]
+
+
+def to_hex(rgb: tuple[float, float, float]) -> str:
+    return "#" + "".join(f"{round(max(0.0, min(1.0, channel)) * 255):02X}" for channel in rgb)
+
+
+def to_hsl(value: str) -> tuple[float, float, float]:
+    hue, lightness, saturation = colorsys.rgb_to_hls(*parse_hex(value))
+    return hue * 360, saturation, lightness
+
+
+def from_hsl(hue: float, saturation: float, lightness: float) -> str:
+    return to_hex(colorsys.hls_to_rgb((hue % 360) / 360, max(0.0, min(1.0, lightness)), max(0.0, min(1.0, saturation))))
+
+
+def luminance(value: str) -> float:
+    def linear(channel: float) -> float:
+        return channel / 12.92 if channel <= 0.03928 else ((channel + 0.055) / 1.055) ** 2.4
+    red, green, blue = (linear(channel) for channel in parse_hex(value))
+    return 0.2126 * red + 0.7152 * green + 0.0722 * blue
+
+
+def contrast(first: str, second: str) -> float:
+    high, low = sorted((luminance(first), luminance(second)), reverse=True)
+    return (high + 0.05) / (low + 0.05)
+
+
+def hue_distance(first: float, second: float) -> float:
+    delta = abs(first - second) % 360
+    return min(delta, 360 - delta)
+
+
+def mix(first: str, second: str, amount: float) -> str:
+    a, b = parse_hex(first), parse_hex(second)
+    return to_hex(tuple(x + (y - x) * amount for x, y in zip(a, b)))  # type: ignore[arg-type]
+
+
+def ensure_contrast(colour: str, background: str, minimum: float = MIN_TEXT_CONTRAST) -> str:
+    """Move only lightness, away from the background, until contrast passes."""
+    if contrast(colour, background) >= minimum:
+        return colour
+    hue, saturation, lightness = to_hsl(colour)
+    step = -0.01 if luminance(background) > 0.18 else 0.01
+    candidate = colour
+    for _ in range(101):
+        lightness = max(0.0, min(1.0, lightness + step))
+        candidate = from_hsl(hue, saturation, lightness)
+        if contrast(candidate, background) >= minimum:
+            return candidate
+    return candidate
+
+
+def pick_on_accent(accent: str, candidates: list[str]) -> str:
+    return max(candidates, key=lambda candidate: (round(contrast(candidate, accent), 4), candidate))
+
+
+def complete_roles(roles: dict[str, str]) -> dict[str, str]:
+    """Fill derived roles for a signature; supplied roles are never changed."""
+    missing = [name for name in ("canvas", "text", "accent") if not roles.get(name)]
+    if missing:
+        raise ValueError("signature needs canvas, text and accent; missing " + ", ".join(missing))
+    for name, value in roles.items():
+        if name not in ROLES:
+            raise ValueError(f"unknown palette role: {name}")
+        parse_hex(value)
+    filled = {name: roles[name].upper() for name in roles}
+    canvas, text, accent = filled["canvas"], filled["text"], filled["accent"]
+    filled.setdefault("panel", mix(canvas, text, 0.04))
+    filled.setdefault("soft", mix(canvas, accent, 0.12))
+    # The dark band is the text colour on light canvases and a deeper canvas on dark ones.
+    if luminance(canvas) > 0.18:
+        filled.setdefault("dark", text)
+    else:
+        canvas_hue, canvas_saturation, canvas_lightness = to_hsl(canvas)
+        filled.setdefault("dark", from_hsl(canvas_hue, canvas_saturation, canvas_lightness * 0.8))
+    deep_hue, deep_saturation, deep_lightness = to_hsl(filled["dark"])
+    filled.setdefault("deep", from_hsl(deep_hue, deep_saturation, deep_lightness * 0.7))
+    filled.setdefault("accentText", ensure_contrast(accent, canvas))
+    filled.setdefault("onAccent", pick_on_accent(accent, ["#FFFFFF", filled["deep"], text, canvas]))
+    return {name: filled[name] for name in ROLES}
+
+
+def derive_variant(signature: dict[str, str], anchor: tuple[str, str, int], max_saturation: float) -> dict[str, object]:
+    identifier, name, target = anchor
+    accent_hue, accent_saturation, accent_lightness = to_hsl(signature["accent"])
+    shift = target - accent_hue
+    roles: dict[str, str] = {}
+    for role in ("canvas", "panel", "soft", "text", "dark", "deep"):
+        hue, saturation, lightness = to_hsl(signature[role])
+        # Neutrals follow the hue move but never gain chroma.
+        roles[role] = from_hsl(hue + shift, min(saturation, max_saturation), lightness)
+    roles["text"] = ensure_contrast(roles["text"], roles["canvas"])
+    roles["text"] = ensure_contrast(roles["text"], roles["panel"])
+    accent = from_hsl(target, min(accent_saturation, max_saturation), accent_lightness)
+    candidates = ["#FFFFFF", roles["deep"], roles["text"], roles["canvas"]]
+    on_accent = pick_on_accent(accent, candidates)
+    if contrast(on_accent, accent) < MIN_TEXT_CONTRAST:
+        accent = ensure_contrast(accent, on_accent)
+        on_accent = pick_on_accent(accent, candidates)
+    roles["accent"] = accent
+    roles["onAccent"] = on_accent
+    roles["accentText"] = ensure_contrast(accent, roles["canvas"])
+    return {"id": identifier, "name": name, "roles": {role: roles[role] for role in ROLES}}
+
+
+def generate(roles: dict[str, str], *, template: str | None = None, name: str = "Signature",
+             count: int = DEFAULT_VARIANT_COUNT, max_saturation: float = DEFAULT_MAX_SATURATION) -> dict[str, object]:
+    if not 0 < max_saturation <= 1:
+        raise ValueError("max saturation must be in (0, 1]")
+    if count < 0:
+        raise ValueError("count must not be negative")
+    signature = complete_roles(roles)
+    accent_hue = to_hsl(signature["accent"])[0]
+    anchors = [anchor for anchor in HUE_ANCHORS if hue_distance(anchor[2], accent_hue) >= MIN_HUE_DISTANCE]
+    variants = [derive_variant(signature, anchor, max_saturation) for anchor in anchors[:count]]
+    return {
+        "schemaVersion": SCHEMA_VERSION,
+        "template": template,
+        "signature": {"id": "signature", "name": name, "roles": signature},
+        "variants": variants,
+    }
+
+
+def validate(palette: dict[str, object], max_saturation: float = DEFAULT_MAX_SATURATION) -> dict[str, object]:
+    errors: list[str] = []
+    warnings: list[str] = []
+    if palette.get("schemaVersion") != SCHEMA_VERSION:
+        errors.append(f"schemaVersion must be {SCHEMA_VERSION}")
+    template = palette.get("template")
+    if template is not None and not isinstance(template, str):
+        errors.append("template must be a string or null")
+    entries: list[tuple[dict, bool]] = []
+    if isinstance(palette.get("signature"), dict):
+        entries.append((palette["signature"], False))  # type: ignore[arg-type]
+    else:
+        errors.append("signature must be an object")
+    if isinstance(palette.get("variants"), list):
+        entries.extend((variant, True) for variant in palette["variants"])  # type: ignore[union-attr]
+    else:
+        errors.append("variants must be a list")
+    seen: set[str] = set()
+    checked = 0
+    for entry, is_variant in entries:
+        if not isinstance(entry, dict):
+            errors.append("each palette entry must be an object")
+            continue
+        identifier = str(entry.get("id") or "")
+        label = identifier or "<missing id>"
+        if not identifier or not str(entry.get("name") or "").strip():
+            errors.append(f"{label}: id and name are required")
+        if identifier in seen:
+            errors.append(f"{label}: duplicate palette id")
+        seen.add(identifier)
+        roles = entry.get("roles")
+        if not isinstance(roles, dict):
+            errors.append(f"{label}: roles must be an object")
+            continue
+        missing = [role for role in ROLES if role not in roles]
+        invalid = [role for role in ROLES if role in roles and not (isinstance(roles[role], str) and HEX.match(roles[role]))]
+        if missing:
+            errors.append(f"{label}: missing roles " + ", ".join(missing))
+        if invalid:
+            errors.append(f"{label}: roles must be #RRGGBB: " + ", ".join(invalid))
+        if missing or invalid:
+            continue
+        checked += 1
+        for foreground, background in (("text", "canvas"), ("text", "panel"), ("accentText", "canvas"), ("onAccent", "accent")):
+            ratio = contrast(roles[foreground], roles[background])
+            if ratio < MIN_TEXT_CONTRAST:
+                errors.append(f"{label}: {foreground} on {background} is {ratio:.2f}:1; needs {MIN_TEXT_CONTRAST}:1")
+        saturation = to_hsl(roles["accent"])[1]
+        if is_variant and saturation > max_saturation + 0.01:
+            errors.append(f"{label}: accent saturation {saturation:.2f} exceeds cap {max_saturation:.2f}")
+        if contrast(roles["text"], roles["soft"]) < MIN_TEXT_CONTRAST:
+            warnings.append(f"{label}: text on soft is below {MIN_TEXT_CONTRAST}:1; avoid body copy on soft surfaces")
+    return {"schemaVersion": "maggie-palette-validation.v1", "passed": not errors, "checkedPalettes": checked, "errors": errors, "warnings": warnings}
+
+
+def _load_roles(args: argparse.Namespace) -> dict[str, str]:
+    roles: dict[str, str] = {}
+    if args.roles:
+        data = json.loads(args.roles.read_text(encoding="utf-8"))
+        if isinstance(data.get("signature"), dict):
+            data = data["signature"].get("roles") or {}
+        elif isinstance(data.get("roles"), dict):
+            data = data["roles"]
+        roles.update({key: value for key, value in data.items() if isinstance(value, str)})
+    for role in ROLES:
+        value = getattr(args, role, None)
+        if value:
+            roles[role] = value
+    return roles
+
+
+def _emit(payload: dict[str, object], output: Path | None) -> None:
+    encoded = json.dumps(payload, indent=2, ensure_ascii=False) + "\n"
+    if output:
+        output.parent.mkdir(parents=True, exist_ok=True)
+        output.write_text(encoded, encoding="utf-8")
+    print(encoded, end="")
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="maggie design palette", description=__doc__.splitlines()[0])
+    sub = parser.add_subparsers(dest="command", required=True)
+    generate_parser = sub.add_parser("generate", help="derive contrast-safe variants from a signature palette")
+    generate_parser.add_argument("--roles", type=Path, help="JSON roles object, or an existing palette file")
+    for role in ROLES:
+        generate_parser.add_argument(f"--{role}", dest=role, help=f"{role} colour as #RRGGBB")
+    generate_parser.add_argument("--template", help="template id recorded in the contract")
+    generate_parser.add_argument("--name", default="Signature", help="signature palette display name")
+    generate_parser.add_argument("--count", type=int, default=DEFAULT_VARIANT_COUNT)
+    generate_parser.add_argument("--max-saturation", type=float, default=DEFAULT_MAX_SATURATION)
+    generate_parser.add_argument("--output", type=Path)
+    validate_parser = sub.add_parser("validate", help="check roles, hex values, contrast and saturation cap")
+    validate_parser.add_argument("--palette", type=Path, required=True)
+    validate_parser.add_argument("--max-saturation", type=float, default=DEFAULT_MAX_SATURATION)
+    args = parser.parse_args(argv)
+    try:
+        if args.command == "generate":
+            palette = generate(_load_roles(args), template=args.template, name=args.name, count=args.count, max_saturation=args.max_saturation)
+            report = validate(palette, args.max_saturation)
+            if not report["passed"]:
+                print(json.dumps(report, indent=2), file=sys.stderr)
+                print("BLOCKED: maggie-design palette generate: the signature palette fails the contrast contract", file=sys.stderr)
+                return 1
+            _emit(palette, args.output)
+            return 0
+        report = validate(json.loads(args.palette.read_text(encoding="utf-8")), args.max_saturation)
+        _emit(report, None)
+        return 0 if report["passed"] else 1
+    except (OSError, ValueError, json.JSONDecodeError) as error:
+        print(f"BLOCKED: maggie-design palette {args.command}: {error}", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/bundled-tools/clis/maggie_qa_workflow.py

@@ -16,7 +16,9 @@ import re
 import sys
 from datetime import datetime, timezone
 from pathlib import Path
+from urllib.error import HTTPError, URLError
 from urllib.parse import urlsplit, urlunsplit
+from urllib.request import Request, urlopen
 
 
 DEFAULT_SCENARIOS = Path(".maggie") / "scenario-manifest.json"
@@ -29,6 +31,9 @@ SECRET_RE = re.compile(
     r"(?i)(bearer\s+|(?:api[_-]?key|token|secret|password|authorization|cookie)\s*[=:]\s*)[^\s,;]+"
 )
 EMAIL_RE = re.compile(r"\b[\w.+-]+@[\w.-]+\.[A-Za-z]{2,}\b")
+CORS_SAFELISTED_METHODS = {"GET", "HEAD", "POST"}
+DEFAULT_CORS_METHODS = ("GET", "POST", "PUT", "PATCH", "DELETE")
+MUTATING_METHODS = {"POST", "PUT", "PATCH", "DELETE"}
 QUERY_SECRET_RE = re.compile(r"(?i)([?&](?:token|key|secret|password|code|id_token|access_token)=)[^&\s]+")
 
 
@@ -149,6 +154,11 @@ def start(args: argparse.Namespace) -> int:
     path = run_directory(project) / f"{run_id}.json"
     if path.exists():
         raise ValueError(f"QA run already exists: {path}")
+    api_base = safe_base_url(args.api_base) if getattr(args, "api_base", "") else ""
+    production_hosts = {host for host in (api_host(value) for value in getattr(args, "production_api", []) or []) if host}
+    targets_production = bool(api_base) and api_host(api_base) in production_hosts
+    allow_writes = bool(getattr(args, "allow_production_writes", False))
+    write_policy = "allowed" if not targets_production else ("allowed-by-consent" if allow_writes else "read-only")
     scenarios = {
         item["id"]: {
             "id": item["id"],
@@ -164,6 +174,20 @@ def start(args: argparse.Namespace) -> int:
         }
         for item in records
     }
+    blocked_writes = []
+    if write_policy == "read-only":
+        for item in records:
+            if item.get("mutates") is True:
+                scenario = scenarios[item["id"]]
+                scenario["status"] = "blocked"
+                scenario["mutates"] = True
+                scenario["history"].append({
+                    "at": now(),
+                    "phase": "guard",
+                    "status": "blocked",
+                    "summary": "Mutating scenario blocked: the API target is production and --allow-production-writes was not given",
+                })
+                blocked_writes.append(item["id"])
     try:
         manifest_label = str(manifest_path.relative_to(project))
     except ValueError:
@@ -183,11 +207,22 @@ def start(args: argparse.Namespace) -> int:
         "commit": safe_text(args.commit),
         "release": safe_text(args.release),
         "scenarioManifest": manifest_label,
+        "apiTarget": {
+            "baseUrl": api_base,
+            "production": targets_production,
+            "writePolicy": write_policy,
+            "interception": "network-layer required; page-level window.fetch stubs do not intercept bundled clients",
+        },
         "scenarios": scenarios,
     }
     run["summary"] = calculate(run)
     write_json(path, run)
-    print(json.dumps({"runId": run_id, "path": str(path), "summary": run["summary"]}, ensure_ascii=False, indent=2))
+    report = {"runId": run_id, "path": str(path), "summary": run["summary"], "writePolicy": write_policy}
+    if blocked_writes:
+        report["blockedMutatingScenarios"] = blocked_writes
+    if not api_base:
+        report["warnings"] = ["--api-base was not given; declare the API the build talks to so writes against production can be blocked"]
+    print(json.dumps(report, ensure_ascii=False, indent=2))
     return 0
 
 
@@ -217,6 +252,16 @@ def record(args: argparse.Namespace) -> int:
         raise ValueError(f"phase must be one of: {', '.join(sorted(VALID_PHASES))}")
     if phase in {"test", "retest"} and args.status not in VALID_STATUSES - {"pending"}:
         raise ValueError("test and retest require status pass, fail, blocked or inconclusive")
+    if (
+        phase in {"test", "retest"}
+        and item.get("mutates") is True
+        and (run.get("apiTarget") or {}).get("writePolicy") == "read-only"
+        and args.status in {"pass", "fail"}
+    ):
+        raise ValueError(
+            "this mutating scenario targets a production API without consent; "
+            "rerun QA against a non-production API or start a new run with --allow-production-writes"
+        )
     if phase == "fix" and not args.resolution:
         raise ValueError("fix requires --resolution")
     if phase == "fix" and item.get("status") != "fail":
@@ -417,6 +462,104 @@ def assertion_audit(args: argparse.Namespace) -> int:
     return 0 if passed else 1
 
 
+def api_host(value: object) -> str:
+    try:
+        parsed = urlsplit(str(value or "").strip())
+    except ValueError:
+        return ""
+    if not parsed.hostname:
+        return ""
+    return f"{parsed.hostname.lower()}:{parsed.port}" if parsed.port else parsed.hostname.lower()
+
+
+def header_tokens(value: str | None) -> set[str]:
+    return {item.strip().lower() for item in (value or "").split(",") if item.strip()}
+
+
+def preflight_method(url: str, origin: str, method: str, request_headers: list[str], timeout: float) -> dict:
+    """Send one CORS preflight; never sends the method itself, so it cannot mutate data."""
+    headers = {"Origin": origin, "Access-Control-Request-Method": method, "User-Agent": "MaggieQA/1.0"}
+    if request_headers:
+        headers["Access-Control-Request-Headers"] = ",".join(request_headers)
+    status = 0
+    response_headers: dict[str, str] = {}
+    error = ""
+    try:
+        with urlopen(Request(url, headers=headers, method="OPTIONS"), timeout=timeout) as response:
+            status = response.status
+            response_headers = {key.lower(): value for key, value in response.headers.items()}
+    except HTTPError as failure:
+        status = failure.code
+        response_headers = {key.lower(): value for key, value in failure.headers.items()}
+    except (URLError, TimeoutError, OSError) as failure:
+        error = safe_text(getattr(failure, "reason", failure), 200)
+    allow_origin = response_headers.get("access-control-allow-origin", "")
+    allow_methods = {item.upper() for item in header_tokens(response_headers.get("access-control-allow-methods"))}
+    allow_headers = header_tokens(response_headers.get("access-control-allow-headers"))
+    reasons = []
+    if error:
+        reasons.append(f"preflight request failed: {error}")
+    elif not 200 <= status < 300:
+        reasons.append(f"preflight returned HTTP {status}")
+    if not error and allow_origin not in {origin, "*"}:
+        reasons.append("Access-Control-Allow-Origin does not allow this origin")
+    if not error and method not in CORS_SAFELISTED_METHODS and method not in allow_methods and "*" not in allow_methods:
+        reasons.append(f"{method} is not in Access-Control-Allow-Methods")
+    missing_headers = sorted(header.lower() for header in request_headers if header.lower() not in allow_headers and "*" not in allow_headers)
+    if not error and missing_headers:
+        reasons.append("request headers not allowed: " + ", ".join(missing_headers))
+    return {
+        "method": method,
+        "status": status,
+        "allowed": not reasons,
+        "allowOrigin": allow_origin if allow_origin in {origin, "*"} else ("other" if allow_origin else ""),
+        "allowMethods": sorted(allow_methods),
+        "reasons": reasons,
+    }
+
+
+def cors_preflight(args: argparse.Namespace) -> int:
+    url = str(args.url).strip()
+    parsed = urlsplit(url)
+    if parsed.scheme not in {"http", "https"} or not parsed.hostname:
+        raise ValueError("--url must be an absolute http(s) URL")
+    origin = safe_base_url(args.origin)
+    if not urlsplit(origin).hostname:
+        raise ValueError("--origin must be an absolute origin such as https://app.example.com")
+    methods = []
+    for value in args.method or list(DEFAULT_CORS_METHODS):
+        for item in str(value).split(","):
+            item = item.strip().upper()
+            if item and item not in methods:
+                if not re.fullmatch(r"[A-Z]{3,10}", item):
+                    raise ValueError(f"invalid HTTP method: {item}")
+                methods.append(item)
+    request_headers = []
+    for value in args.request_header:
+        request_headers.extend(item.strip() for item in str(value).split(",") if item.strip())
+    results = [preflight_method(url, origin, method, request_headers, args.timeout) for method in methods]
+    blocked = [item["method"] for item in results if not item["allowed"]]
+    report = {
+        "schemaVersion": "maggie.qa-cors-preflight.v1",
+        "checkedAt": now(),
+        "url": safe_base_url(url) + (parsed.path or "/"),
+        "origin": origin,
+        "requestHeaders": [header.lower() for header in request_headers],
+        "methods": results,
+        "blocked": blocked,
+        "passed": not blocked,
+        "mutation": "not executed; only OPTIONS preflights were sent",
+    }
+    if args.output:
+        project = project_root(args.project)
+        output = Path(args.output)
+        if not output.is_absolute():
+            output = project / output
+        write_json(output, report)
+    print(json.dumps(report, ensure_ascii=False, indent=2))
+    return 0 if report["passed"] else 1
+
+
 def parser() -> argparse.ArgumentParser:
     root = argparse.ArgumentParser(description=__doc__)
     root.add_argument("--project", default=".")
@@ -431,6 +574,9 @@ def parser() -> argparse.ArgumentParser:
     start_parser.add_argument("--browser", default="chrome")
     start_parser.add_argument("--commit", default="")
     start_parser.add_argument("--release", default="")
+    start_parser.add_argument("--api-base", default="", help="API origin the build under test talks to")
+    start_parser.add_argument("--production-api", action="append", default=[], help="production API origin; repeat")
+    start_parser.add_argument("--allow-production-writes", action="store_true", help="explicit consent to run mutating scenarios against a production API")
 
     record_parser = commands.add_parser("record")
     record_parser.add_argument("--project", default=argparse.SUPPRESS)
@@ -453,6 +599,14 @@ def parser() -> argparse.ArgumentParser:
         command.add_argument("--run", required=True)
         if name == "summary": command.add_argument("--format", choices=("json", "markdown"), default="json")
         else: command.add_argument("--output", required=True)
+    cors_parser = commands.add_parser("cors-preflight", help="preflight every HTTP method a client uses through the public edge")
+    cors_parser.add_argument("--project", default=argparse.SUPPRESS)
+    cors_parser.add_argument("--url", required=True, help="public API URL as the browser reaches it")
+    cors_parser.add_argument("--origin", required=True, help="app origin that sends the requests")
+    cors_parser.add_argument("--method", action="append", default=[], help="method or comma list; default GET,POST,PUT,PATCH,DELETE")
+    cors_parser.add_argument("--request-header", action="append", default=[], help="non-safelisted request header the client sends, e.g. authorization,content-type")
+    cors_parser.add_argument("--timeout", type=float, default=10.0)
+    cors_parser.add_argument("--output")
     assertion_parser = commands.add_parser("assertion-audit")
     assertion_parser.add_argument("--project", default=argparse.SUPPRESS)
     assertion_parser.add_argument("--assertions", required=True, help="runtime assertion manifest JSON")
@@ -467,6 +621,7 @@ def main() -> int:
         if args.command == "record": return record(args)
         if args.command == "summary": return summary(args)
         if args.command == "assertion-audit": return assertion_audit(args)
+        if args.command == "cors-preflight": return cors_preflight(args)
         return export_run(args)
     except (OSError, ValueError, json.JSONDecodeError) as error:
         print(f"QA workflow error: {safe_text(error)}", file=sys.stderr)

package/bundled-tools/clis/maggie_schedule.py

@@ -1,5 +1,11 @@
 #!/usr/bin/env python3
-"""Validate and materialise safe Maggie scheduled-job definitions."""
+"""Validate and materialise safe Maggie scheduled-job definitions.
+
+These jobs are the `infrastructure` schedule layer: when a worker wakes up.
+They never carry a content-calendar publish time, a campaign flight, or a
+measurement window; those layers are declared in a marketing run and checked
+by `maggie_marketing_run.py` (see `maggie_marketing_run.py layers`).
+"""
 
 from __future__ import annotations
 
@@ -68,11 +74,15 @@ def validate(manifest: object, project: Path | None = None) -> dict:
             errors.append(f"{prefix}.maxRetries must be between 0 and 5")
         if job.get("overlapPolicy") != "skip-if-running":
             errors.append(f"{prefix}.overlapPolicy must be skip-if-running")
+        if job.get("layer", "infrastructure") != "infrastructure":
+            errors.append(f"{prefix}.layer must be infrastructure; content calendars, campaign flights and measurement windows belong in a marketing run")
+        if any(key in job for key in ("scheduled_at", "scheduledAt", "publishAt", "publish_at")):
+            errors.append(f"{prefix} must not carry a publish time; a timer only wakes the worker")
         if not job.get("lockKey"):
             errors.append(f"{prefix}.lockKey is required")
         if re.search(r"(?:API_KEY|SECRET|TOKEN|PASSWORD)\s*=|https?://[^ $]+:[^ $]+@", str(job.get("command", "")), re.I):
             errors.append(f"{prefix}.command must not contain credentials")
-    return {"passed": not errors, "errors": errors, "jobs": len(jobs), "sourceChecks": source_checks, "mutation": "not executed"}
+    return {"passed": not errors, "errors": errors, "jobs": len(jobs), "sourceChecks": source_checks, "layer": "infrastructure", "mutation": "not executed"}
 
 
 def write_units(output_dir: Path, manifest: dict) -> None: