@topy-ai/maggie 0.7.46 → 0.7.48

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_social_queue.py

@@ -0,0 +1,338 @@
+#!/usr/bin/env python3
+"""Pure, deterministic checks for Maggie Social Share adapters, connections, and the slot queue.
+
+No function in this module calls a provider, a model, or the network. Every
+input is a reviewable JSON document and every output is a JSON-serialisable
+report, so the same contract can be enforced in CI, in the CLI, and in a host
+application's own tests.
+"""
+from __future__ import annotations
+
+from datetime import date, datetime, time, timedelta, timezone
+from urllib.parse import parse_qsl, urlsplit
+from zoneinfo import ZoneInfo, ZoneInfoNotFoundError
+
+
+WEEKDAYS = ("mon", "tue", "wed", "thu", "fri", "sat", "sun")
+SECRET_KEYS = {"client_secret", "access_token", "refresh_token", "token", "secret"}
+REVOKED_PROVIDER_STATES = {"revoked", "invalid", "expired", "unauthorized"}
+# Hosts whose avatar/media URLs are known to be signed with an expiry.
+SIGNED_MEDIA_HOSTS = ("media.licdn.com", "fbcdn.net", "cdninstagram.com", "pbs.twimg.com")
+# Query parameters that carry an absolute expiry (unix seconds, or hex for Meta's `oe`).
+EXPIRY_PARAMS = ("e", "oe", "expires", "Expires")
+RELATIVE_EXPIRY_PARAMS = ("X-Amz-Expires", "X-Goog-Expires")
+CAMPAIGN_STATUSES = {"planned", "started", "paused", "completed"}
+IDEA_STATUSES = {"planned", "written"}
+
+
+def parse_instant(value: str, label: str) -> datetime:
+    try:
+        parsed = datetime.fromisoformat(str(value).replace("Z", "+00:00"))
+    except ValueError as error:
+        raise ValueError(f"{label} must be an ISO 8601 date-time") from error
+    if parsed.tzinfo is None:
+        raise ValueError(f"{label} must include a UTC offset")
+    return parsed
+
+
+def iso(value: datetime) -> str:
+    return value.isoformat().replace("+00:00", "Z")
+
+
+# --- T01: canonical OAuth scope sets -----------------------------------------------------------
+
+
+def validate_adapters(manifest: dict) -> dict:
+    """Fail when connect paths disagree on scopes; warn about OAuth clients shared across products.
+
+    LinkedIn (and other providers) invalidate a member's earlier tokens when a
+    later sign-in requests a different scope set, so every connect path for one
+    provider must request exactly the adapter's canonical set.
+    """
+    errors: list[str] = []
+    warnings: list[str] = []
+    adapters = manifest.get("adapters")
+    if not isinstance(adapters, list) or not adapters:
+        return {"valid": False, "errors": ["adapters must be a non-empty list"], "warnings": []}
+    seen_clients: dict[str, str] = {}
+    for index, adapter in enumerate(adapters):
+        label = f"adapters[{index}]"
+        if not isinstance(adapter, dict):
+            errors.append(f"{label} must be an object")
+            continue
+        provider = adapter.get("provider") or label
+        label = f"adapter {provider}"
+        leaked = sorted(SECRET_KEYS & set(adapter))
+        if leaked:
+            errors.append(f"{label} must not contain secret fields: {', '.join(leaked)}")
+        canonical = adapter.get("canonical_scopes")
+        if not isinstance(canonical, list) or not canonical or not all(isinstance(scope, str) and scope for scope in canonical):
+            errors.append(f"{label} must declare canonical_scopes as a non-empty list of strings")
+            continue
+        canonical_set = set(canonical)
+        paths = adapter.get("connect_paths")
+        if not isinstance(paths, list) or not paths:
+            errors.append(f"{label} must list connect_paths (every client that starts the OAuth flow)")
+            paths = []
+        for path in paths:
+            path_id = path.get("id") if isinstance(path, dict) else None
+            scopes = path.get("scopes") if isinstance(path, dict) else None
+            if not path_id or not isinstance(scopes, list):
+                errors.append(f"{label} connect path needs id and scopes")
+                continue
+            missing = sorted(canonical_set - set(scopes))
+            extra = sorted(set(scopes) - canonical_set)
+            if missing or extra:
+                detail = "; ".join(part for part in (
+                    f"missing {', '.join(missing)}" if missing else "",
+                    f"extra {', '.join(extra)}" if extra else "",
+                ) if part)
+                errors.append(f"{label} connect path {path_id} requests a different scope set ({detail}); "
+                              "a sign-in with a different scope set can revoke tokens issued to the other paths")
+        client = str(adapter.get("client_id_ref") or "")
+        if client:
+            if client in seen_clients and seen_clients[client] != provider:
+                warnings.append(f"{label} reuses OAuth client {client} from adapter {seen_clients[client]}")
+            seen_clients.setdefault(client, provider)
+        shared = adapter.get("client_shared_with") or []
+        if shared:
+            warnings.append(f"{label} OAuth client is shared with {len(shared)} other product(s); their sign-ins can "
+                            "revoke this product's tokens unless they request the identical scope set — prefer a dedicated client")
+        hosts = sorted({urlsplit(uri).hostname or "" for uri in adapter.get("redirect_uris") or [] if isinstance(uri, str)} - {""})
+        if len(hosts) > 1 and not shared:
+            warnings.append(f"{label} redirect URIs span {len(hosts)} hosts ({', '.join(hosts)}); confirm they belong to "
+                            "one product or record them in client_shared_with")
+    return {"valid": not errors, "errors": errors, "warnings": warnings}
+
+
+# --- T02: connection health --------------------------------------------------------------------
+
+
+def avatar_expiry(url: str) -> tuple[bool, datetime | None]:
+    """Return (is_signed, absolute_expiry) for a provider media URL."""
+    parsed = urlsplit(url)
+    host = (parsed.hostname or "").lower()
+    query = dict(parse_qsl(parsed.query, keep_blank_values=True))
+    for key in EXPIRY_PARAMS:
+        raw = query.get(key)
+        if not raw:
+            continue
+        try:
+            seconds = int(raw, 16) if key == "oe" else int(raw)
+        except ValueError:
+            continue
+        if seconds > 10**12:
+            seconds //= 1000
+        return True, datetime.fromtimestamp(seconds, tz=timezone.utc)
+    if any(key in query for key in RELATIVE_EXPIRY_PARAMS) or "Signature" in query or "X-Amz-Signature" in query:
+        return True, None
+    return any(host == known or host.endswith("." + known) for known in SIGNED_MEDIA_HOSTS), None
+
+
+def connection_health(document: dict, now: datetime) -> dict:
+    """Derive each connection's real status before anything is scheduled on it."""
+    connections = document.get("connections")
+    if not isinstance(connections, list):
+        return {"valid": False, "errors": ["connections must be a list"], "warnings": [], "connections": []}
+    errors: list[str] = []
+    warnings: list[str] = []
+    report = []
+    for connection in connections:
+        if not isinstance(connection, dict):
+            errors.append("each connection must be an object")
+            continue
+        cid = connection.get("id") or "?"
+        stored = connection.get("status")
+        reasons: list[str] = []
+        if connection.get("token_decryptable") is False:
+            reasons.append("token cannot be decrypted on this host (check encryption-key parity)")
+        provider_state = (connection.get("provider_check") or {}).get("status")
+        if provider_state in REVOKED_PROVIDER_STATES:
+            reasons.append(f"provider reports token {provider_state}")
+        elif provider_state in (None, "unknown"):
+            warnings.append(f"connection {cid} has no provider token check; verify before scheduling")
+        derived = "needs_reconnect" if reasons else (stored or "unknown")
+        if reasons and stored == "active":
+            scheduled = int(connection.get("scheduled_items") or 0)
+            errors.append(f"connection {cid} is stored as active but must be needs_reconnect: {'; '.join(reasons)}"
+                          + (f" ({scheduled} scheduled item(s) would fail at publish time)" if scheduled else ""))
+        avatar = connection.get("avatar_url")
+        avatar_state = "none"
+        if isinstance(avatar, str) and avatar:
+            signed, expires = avatar_expiry(avatar)
+            avatar_state = "stable"
+            if signed:
+                avatar_state = "signed"
+                if expires and expires <= now:
+                    avatar_state = "expired"
+                if not connection.get("avatar_cached") and not connection.get("avatar_refresh_on_read"):
+                    when = f" (expires {iso(expires)})" if expires else ""
+                    errors.append(f"connection {cid} stores a signed, expiring provider avatar URL{when}; cache the image "
+                                  "bytes in owned storage or refresh the URL on readback")
+        report.append({"id": cid, "provider": connection.get("provider"), "stored_status": stored,
+                       "status": derived, "reasons": reasons, "avatar": avatar_state})
+    return {"valid": not errors, "errors": errors, "warnings": warnings, "connections": report}
+
+
+# --- T03: campaign idea stage ------------------------------------------------------------------
+
+
+def campaign_readiness(campaign: dict) -> list[str]:
+    """Return the blockers that prevent a campaign from starting (empty list = can start)."""
+    blockers: list[str] = []
+    ideas = campaign.get("ideas")
+    if not isinstance(ideas, list) or not ideas:
+        return ["campaign has no ideas"]
+    for idea in ideas:
+        status = idea.get("status") if isinstance(idea, dict) else None
+        if status not in IDEA_STATUSES:
+            blockers.append(f"idea {idea.get('id') if isinstance(idea, dict) else '?'} has invalid status")
+        elif status == "planned":
+            blockers.append(f"idea {idea.get('id')} is not written yet")
+        elif not idea.get("draft_id"):
+            blockers.append(f"idea {idea.get('id')} is written but has no draft_id")
+    orders = [idea.get("order") for idea in ideas if isinstance(idea, dict)]
+    if any(not isinstance(order, int) for order in orders) or len(set(orders)) != len(orders):
+        blockers.append("ideas need unique integer order values")
+    try:
+        date.fromisoformat(str(campaign.get("start_day")))
+    except ValueError:
+        blockers.append("start_day (YYYY-MM-DD) is required")
+    per_day = campaign.get("posts_per_day")
+    if not isinstance(per_day, int) or per_day < 1:
+        blockers.append("posts_per_day must be a positive integer")
+    return blockers
+
+
+def check_campaigns(document: dict) -> dict:
+    errors: list[str] = []
+    report = []
+    for campaign in document.get("campaigns") or []:
+        cid = campaign.get("id") or "?"
+        status = campaign.get("status", "planned")
+        if status not in CAMPAIGN_STATUSES:
+            errors.append(f"campaign {cid} has invalid status {status}")
+            continue
+        blockers = campaign_readiness(campaign)
+        if status == "started" and blockers:
+            errors.append(f"campaign {cid} is started but not startable: {'; '.join(blockers)}")
+        report.append({"id": cid, "status": status, "can_start": not blockers, "blockers": blockers,
+                       "ideas_planned": sum(1 for idea in campaign.get("ideas") or [] if idea.get("status") == "planned"),
+                       "ideas_written": sum(1 for idea in campaign.get("ideas") or [] if idea.get("status") == "written")})
+    return {"valid": not errors, "errors": errors, "campaigns": report}
+
+
+# --- T03: slot-based queue planner ------------------------------------------------------------
+
+
+def parse_posting_hours(hours: dict) -> dict[int, list[time]]:
+    if not isinstance(hours, dict) or not hours:
+        raise ValueError("posting_hours must map weekdays (mon..sun) to HH:MM lists")
+    result: dict[int, list[time]] = {}
+    for key, values in hours.items():
+        if key not in WEEKDAYS:
+            raise ValueError(f"posting_hours has unknown weekday {key}")
+        slots = []
+        for value in values or []:
+            try:
+                slots.append(time.fromisoformat(value))
+            except (TypeError, ValueError) as error:
+                raise ValueError(f"posting_hours.{key} has invalid time {value!r}") from error
+        result[WEEKDAYS.index(key)] = sorted(set(slots))
+    if not any(result.values()):
+        raise ValueError("posting_hours must contain at least one time")
+    return result
+
+
+def iter_slots(start: datetime, zone: ZoneInfo, hours: dict[int, list[time]], skipped: list[str]):
+    """Yield aware slot instants >= start, in order. Non-existent DST wall times are skipped and reported."""
+    day = start.astimezone(zone).date()
+    while True:
+        for wall in hours.get(day.weekday(), []):
+            local = datetime.combine(day, wall, tzinfo=zone)  # fold=0: first occurrence of an ambiguous time
+            if local.astimezone(timezone.utc).astimezone(zone).replace(tzinfo=None) != local.replace(tzinfo=None):
+                skipped.append(f"{day.isoformat()}T{wall.isoformat('minutes')} does not exist in {zone.key} (DST gap)")
+                continue
+            if local >= start:
+                yield local
+        day += timedelta(days=1)
+
+
+def plan_queue(document: dict, start: datetime, slot_count: int) -> dict:
+    """Assign queued and campaign posts to the next `slot_count` posting slots.
+
+    Rules: each slot posts one item; the standalone queue is newest-first (a new
+    post goes to the front); a stored time is only a not-before bound, so an
+    overdue item is simply eligible; each started campaign publishes its written
+    ideas in idea order from its start day, at most posts_per_day per local day;
+    the standalone queue and started campaigns take turns (round-robin), and a
+    source with nothing eligible is skipped for that slot.
+    """
+    if slot_count < 1 or slot_count > 1000:
+        raise ValueError("slot count must be between 1 and 1000")
+    try:
+        zone = ZoneInfo(str(document.get("timezone")))
+    except (ZoneInfoNotFoundError, ValueError) as error:
+        raise ValueError("timezone must be an IANA time zone such as Europe/London") from error
+    hours = parse_posting_hours(document.get("posting_hours"))
+    warnings: list[str] = []
+    skipped: list[str] = []
+
+    queue = []
+    for item in document.get("queue") or []:
+        if not item.get("id") or not item.get("queued_at"):
+            raise ValueError("queue items need id and queued_at")
+        queue.append({"id": item["id"], "queued_at": parse_instant(item["queued_at"], f"queue {item['id']} queued_at"),
+                      "not_before": parse_instant(item["not_before"], f"queue {item['id']} not_before") if item.get("not_before") else None})
+    # Newest first; id breaks ties so the plan is deterministic.
+    queue.sort(key=lambda item: (-item["queued_at"].timestamp(), item["id"]))
+
+    campaigns = []
+    for campaign in document.get("campaigns") or []:
+        cid = campaign.get("id") or "?"
+        if campaign.get("status") != "started":
+            warnings.append(f"campaign {cid} is {campaign.get('status', 'planned')}; its posts are not scheduled until it starts")
+            continue
+        blockers = campaign_readiness(campaign)
+        if blockers:
+            warnings.append(f"campaign {cid} is started but not startable and was skipped: {'; '.join(blockers)}")
+            continue
+        posted = set(campaign.get("posted_idea_ids") or [])
+        ideas = [idea for idea in sorted(campaign["ideas"], key=lambda idea: idea["order"]) if idea["id"] not in posted]
+        campaigns.append({"id": cid, "start_day": date.fromisoformat(campaign["start_day"]),
+                          "per_day": campaign["posts_per_day"], "ideas": ideas, "used": {}})
+
+    sources = ["queue"] + [campaign["id"] for campaign in campaigns]
+    by_id = {campaign["id"]: campaign for campaign in campaigns}
+    pointer = 0
+    assignments = []
+    empty_slots = 0
+    slots = iter_slots(start, zone, hours, skipped)
+    for _ in range(slot_count):
+        slot = next(slots)
+        chosen = None
+        for offset in range(len(sources)):
+            source = sources[(pointer + offset) % len(sources)]
+            if source == "queue":
+                index = next((i for i, item in enumerate(queue) if item["not_before"] is None or item["not_before"] <= slot), None)
+                if index is not None:
+                    item = queue.pop(index)
+                    chosen = {"post_id": item["id"], "source": "queue",
+                              "overdue": bool(item["not_before"] and item["not_before"] < start)}
+            else:
+                campaign = by_id[source]
+                local_day = slot.astimezone(zone).date()
+                if campaign["ideas"] and local_day >= campaign["start_day"] and campaign["used"].get(local_day, 0) < campaign["per_day"]:
+                    idea = campaign["ideas"].pop(0)
+                    campaign["used"][local_day] = campaign["used"].get(local_day, 0) + 1
+                    chosen = {"post_id": idea["draft_id"], "idea_id": idea["id"], "source": f"campaign:{source}"}
+            if chosen:
+                pointer = (pointer + offset + 1) % len(sources)
+                break
+        if chosen is None:
+            empty_slots += 1
+        assignments.append({"slot": slot.isoformat(), "slot_utc": iso(slot.astimezone(timezone.utc)), **(chosen or {"post_id": None})})
+    remaining = [item["id"] for item in queue] + [idea["draft_id"] for campaign in campaigns for idea in campaign["ideas"]]
+    return {"schema_version": "maggie-social-queue-plan.v1", "timezone": zone.key, "from": iso(start),
+            "assignments": assignments, "empty_slots": empty_slots, "remaining": remaining,
+            "skipped_wall_times": skipped, "warnings": warnings}

package/bundled-tools/clis/maggie_social_share.py

@@ -1,12 +1,17 @@
 #!/usr/bin/env python3
-"""Create and validate a deterministic Maggie Social Share draft contract."""
+"""Create and validate deterministic Maggie Social Share drafts, adapters, connections, campaigns, and the slot queue."""
 from __future__ import annotations
 
 import argparse
 import json
+import sys
+from datetime import datetime, timezone
 from pathlib import Path
 from urllib.parse import parse_qsl, urlencode, urlsplit, urlunsplit
 
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+from maggie_social_queue import check_campaigns, connection_health, parse_instant, plan_queue, validate_adapters  # noqa: E402
+
 
 LIMITS = {"linkedin": 3000, "facebook": 63206, "x": 280}
 REQUIRED = ("source_content_id", "title", "canonical_url")
@@ -64,23 +69,51 @@ def validate(value: dict) -> list[str]:
 def main() -> int:
     parser = argparse.ArgumentParser(description=__doc__)
     sub = parser.add_subparsers(dest="command", required=True)
-    create = sub.add_parser("plan")
+    create = sub.add_parser("plan", help="create a draft channel contract from one content object")
     create.add_argument("input")
     create.add_argument("--channels", default="linkedin,facebook")
     create.add_argument("--output")
-    check = sub.add_parser("validate")
+    check = sub.add_parser("validate", help="validate a draft channel contract")
     check.add_argument("input")
+    adapters = sub.add_parser("adapters", help="check canonical OAuth scope sets and shared OAuth clients")
+    adapters.add_argument("input")
+    health = sub.add_parser("connections", help="derive connection status (needs_reconnect) and expiring avatar URLs")
+    health.add_argument("input")
+    health.add_argument("--now", help="ISO 8601 instant used for expiry checks (default: current time)")
+    campaigns = sub.add_parser("campaigns", help="check the campaign idea stage and Start gate")
+    campaigns.add_argument("input")
+    queue = sub.add_parser("queue", help="assign queued and campaign posts to the next posting slots")
+    queue.add_argument("input")
+    queue.add_argument("--from", dest="start", help="ISO 8601 instant to plan from (default: current time)")
+    queue.add_argument("--slots", type=int, default=14)
+    queue.add_argument("--output")
     args = parser.parse_args()
     try:
         value = read(Path(args.input))
-        if args.command == "plan":
-            value = plan(value, [item.strip() for item in args.channels.split(",") if item.strip()])
+        now = datetime.now(timezone.utc)
+        if args.command == "adapters":
+            result = validate_adapters(value)
+        elif args.command == "connections":
+            result = connection_health(value, parse_instant(args.now, "--now") if args.now else now)
+        elif args.command == "campaigns":
+            result = check_campaigns(value)
+        elif args.command == "queue":
+            result = plan_queue(value, parse_instant(args.start, "--from") if args.start else now, args.slots)
             if args.output:
                 Path(args.output).parent.mkdir(parents=True, exist_ok=True)
-                Path(args.output).write_text(json.dumps(value, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
-        errors = validate(value) if args.command == "validate" else []
-        print(json.dumps({"valid": not errors, "errors": errors, "draft": value}, indent=2, ensure_ascii=False))
-        return 0 if not errors else 1
+                Path(args.output).write_text(json.dumps(result, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+            print(json.dumps(result, indent=2, ensure_ascii=False))
+            return 0
+        else:
+            if args.command == "plan":
+                value = plan(value, [item.strip() for item in args.channels.split(",") if item.strip()])
+                if args.output:
+                    Path(args.output).parent.mkdir(parents=True, exist_ok=True)
+                    Path(args.output).write_text(json.dumps(value, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+            errors = validate(value) if args.command == "validate" else []
+            result = {"valid": not errors, "errors": errors, "draft": value}
+        print(json.dumps(result, indent=2, ensure_ascii=False))
+        return 0 if result["valid"] else 1
     except (OSError, ValueError, json.JSONDecodeError) as error:
         parser.error(str(error))
         return 2