@topy-ai/maggie 0.7.47 → 0.7.49

package/bundled-tools/clis/maggie_social_queue.py

@@ -0,0 +1,442 @@
+#!/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")
+        if adapter.get("publishes"):
+            errors.extend(f"{label} {problem}" for problem in publish_contract_errors(adapter))
+        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}
+
+
+# --- D33: publish contract and reconciliation ----------------------------------------------------
+
+
+RETRY_CLASSES = ("retryable", "terminal", "unknown_outcome")
+READBACK_LOOKUPS = {"by_idempotency_key", "by_marker", "by_recent_posts"}
+
+
+def publish_contract_errors(adapter: dict) -> list[str]:
+    """A publishing adapter declares limits, media rules, pending behaviour, retry classes, idempotency, and readback."""
+    problems: list[str] = []
+    limits = adapter.get("limits")
+    if not isinstance(limits, dict) or not isinstance(limits.get("text_max"), int) or limits["text_max"] <= 0:
+        problems.append("publish contract needs limits.text_max")
+    media = adapter.get("media")
+    if not isinstance(media, dict) or not isinstance(media.get("types"), list) or not isinstance(media.get("max_bytes"), int):
+        problems.append("publish contract needs media.types and media.max_bytes")
+    pending = adapter.get("pending")
+    if not isinstance(pending, dict) or not isinstance(pending.get("max_pending_seconds"), int) or not pending.get("states"):
+        problems.append("publish contract needs pending.states and pending.max_pending_seconds")
+    retry = adapter.get("retry_classes")
+    if not isinstance(retry, dict) or any(not isinstance(retry.get(name), list) for name in RETRY_CLASSES):
+        problems.append("publish contract needs retry_classes.retryable, .terminal and .unknown_outcome lists")
+    else:
+        overlap = (set(retry["retryable"]) & set(retry["terminal"])) | (set(retry["retryable"]) & set(retry["unknown_outcome"]))
+        if overlap:
+            problems.append(f"retry classes overlap: {', '.join(sorted(overlap))}")
+        if "timeout" in retry["retryable"]:
+            problems.append("timeout must be classed unknown_outcome, not retryable: the post may already exist")
+    idem = adapter.get("idempotency")
+    if not isinstance(idem, dict) or not idem.get("key_source"):
+        problems.append("publish contract needs idempotency.key_source")
+        idem = {}
+    readback = adapter.get("readback")
+    if not isinstance(readback, dict) or readback.get("lookup") not in READBACK_LOOKUPS:
+        problems.append(f"publish contract needs readback.lookup ({', '.join(sorted(READBACK_LOOKUPS))})")
+    elif not idem.get("provider_supported") and readback["lookup"] == "by_idempotency_key":
+        problems.append("provider has no idempotency support; readback must look up by_marker or by_recent_posts")
+    return problems
+
+
+def _matches(post: dict, key: str) -> bool:
+    return post.get("idempotency_key") == key or (isinstance(post.get("marker"), str) and key in post["marker"])
+
+
+def reconcile(document: dict) -> dict:
+    """Decide the next safe action per queue item from the attempt log and provider readback.
+
+    Timeout-after-success never produces a duplicate: an unknown outcome waits
+    for readback, a readback post carrying the idempotency key is adopted, and
+    a retry always reuses the original key.
+    """
+    errors: list[str] = []
+    warnings: list[str] = []
+    attempts = document.get("attempts")
+    readback = document.get("readback") or {}
+    posts = readback.get("posts") if isinstance(readback, dict) else None
+    if not isinstance(attempts, list) or not isinstance(posts, list):
+        return {"valid": False, "errors": ["attempts and readback.posts must be lists"], "warnings": [], "items": []}
+    complete = bool(readback.get("complete"))
+    by_item: dict[str, list[dict]] = {}
+    for attempt in attempts:
+        if not isinstance(attempt, dict) or not attempt.get("queue_item_id") or not attempt.get("idempotency_key"):
+            errors.append("each attempt needs queue_item_id and idempotency_key")
+            continue
+        by_item.setdefault(attempt["queue_item_id"], []).append(attempt)
+    items = []
+    for item_id, history in by_item.items():
+        keys = {attempt["idempotency_key"] for attempt in history}
+        if len(keys) > 1:
+            errors.append(f"queue item {item_id} used {len(keys)} idempotency keys; retries must reuse the original key")
+        key = history[0]["idempotency_key"]
+        matched = [post for post in posts if isinstance(post, dict) and _matches(post, key)]
+        claimed = sorted({attempt["provider_post_id"] for attempt in history if attempt.get("provider_post_id")})
+        ids = sorted({post.get("id") for post in matched} | set(claimed))
+        if len(matched) > 1 or len(ids) > 1:
+            errors.append(f"queue item {item_id} has duplicate provider posts ({', '.join(map(str, ids))}); delete extras and keep the first")
+            items.append({"queue_item_id": item_id, "action": "resolve_duplicate", "provider_post_ids": ids, "retry_allowed": False})
+            continue
+        last = history[-1].get("status")
+        if matched:
+            action, status = "adopt", "published"
+        elif claimed:
+            action, status = "verify_readback", "published"
+            warnings.append(f"queue item {item_id} reports {claimed[0]} but readback did not find it")
+        elif last in {"timeout", "pending", "unknown"}:
+            if complete:
+                action, status = "retry_same_key", "retrying"
+            else:
+                action, status = "await_readback", "pending"
+        elif last == "failed_retryable":
+            action, status = "retry_same_key", "retrying"
+        elif last == "failed_terminal":
+            action, status = "fail", "failed"
+        else:
+            action, status = "await_readback", "pending"
+            warnings.append(f"queue item {item_id} has unclassified last status {last!r}")
+        items.append({"queue_item_id": item_id, "idempotency_key": key, "action": action, "status": status,
+                      "provider_post_id": (matched[0].get("id") if matched else (claimed[0] if claimed else None)),
+                      "retry_allowed": action == "retry_same_key"})
+    return {"valid": not errors, "errors": errors, "warnings": warnings, "readback_complete": complete, "items": items}
+
+
+# --- 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, the slot queue, and publish reconciliation."""
 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, reconcile, validate_adapters  # noqa: E402
+
 
 LIMITS = {"linkedin": 3000, "facebook": 63206, "x": 280}
 REQUIRED = ("source_content_id", "title", "canonical_url")
@@ -64,23 +69,55 @@ 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")
+    rec = sub.add_parser("reconcile", help="decide adopt/await/retry per queue item from attempts and provider readback")
+    rec.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 == "reconcile":
+            result = reconcile(value)
+        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