@topy-ai/maggie 0.7.52 → 0.7.54

package/bundled-tools/clis/maggie_service_migration.py

@@ -0,0 +1,272 @@
+#!/usr/bin/env python3
+"""Dry run of moving a business's clients, future appointments and gift cards (``maggie service migrate-check``).
+
+Switching a real business from Fresha (or any system with CSV exports) needs
+more than the service catalogue: clients with consent, future appointments
+and gift-card balances. This command reads the exports and writes nothing:
+
+- recognises columns by synonyms (export headers vary by report and locale)
+  and lists anything it could not map, so the owner can fix the mapping;
+- clients: de-duplicates by e-mail, then by phone normalised to E.164 for the
+  market; keeps marketing consent only when the export says opted in;
+- appointments: keeps only future, not-cancelled rows; converts local times
+  with the **venue's** zone; matches services and staff by normalised name;
+  reports clashes (one team member, overlapping times) instead of forcing
+  them;
+- gift cards: keeps code + remaining balance (+ expiry) in their own
+  namespace (``IMPORT:<code>``) so they can never collide with new codes;
+- returns counts, a sample, row errors and the import plan with an undo key.
+
+Values (names, e-mails, phones, codes) never appear in the report: only
+counts, column names, row numbers and unmatched service/staff names.
+"""
+
+from __future__ import annotations
+
+import argparse
+import csv
+import hashlib
+import json
+import re
+import sys
+from datetime import datetime, timedelta, timezone
+from pathlib import Path
+from zoneinfo import ZoneInfo
+
+SYNONYMS = {
+    "first_name": ["first name", "firstname", "given name"],
+    "last_name": ["last name", "lastname", "surname", "family name"],
+    "name": ["client", "client name", "customer", "customer name", "full name", "name"],
+    "email": ["email", "e-mail", "email address", "client email"],
+    "phone": ["mobile number", "mobile", "phone", "phone number", "telephone", "client phone"],
+    "marketing": ["marketing consent", "accepts marketing", "marketing opt-in", "email marketing", "subscribed", "marketing notifications"],
+    "notes": ["notes", "client notes", "note"],
+    "external_id": ["client id", "customer id", "id", "ref #", "reference"],
+    "date": ["appointment date", "date", "scheduled date"],
+    "time": ["start time", "time", "scheduled time"],
+    "start": ["start", "start date time", "scheduled at", "appointment start"],
+    "service": ["service", "service name", "treatment"],
+    "staff": ["team member", "staff", "staff member", "employee", "therapist"],
+    "duration": ["duration", "duration (min)", "duration minutes"],
+    "price": ["price", "amount", "total", "sale price"],
+    "status": ["status", "appointment status"],
+    "code": ["code", "voucher code", "gift card code", "card code"],
+    "balance": ["balance", "remaining balance", "remaining", "value remaining"],
+    "expiry": ["expiry", "expires", "expiry date", "expiration date"],
+}
+YES = {"yes", "y", "true", "1", "opted in", "subscribed", "accepted"}
+CANCELLED = re.compile(r"cancel|no.?show|deleted", re.I)
+COUNTRY_CODES = {"uk": "44", "us": "1"}
+
+
+def norm(value: str) -> str:
+    return re.sub(r"[^a-z0-9]+", " ", (value or "").lower()).strip()
+
+
+def map_columns(headers: list[str], wanted: list[str]) -> tuple[dict[str, str], list[str]]:
+    mapping: dict[str, str] = {}
+    for header in headers:
+        key = norm(header)
+        for field in wanted:
+            if field not in mapping and key in {norm(s) for s in SYNONYMS[field]}:
+                mapping[field] = header
+                break
+    unmapped = [h for h in headers if h not in mapping.values()]
+    return mapping, unmapped
+
+
+def e164(phone: str, market: str) -> str | None:
+    digits = re.sub(r"\D", "", phone or "")
+    if not digits:
+        return None
+    if (phone or "").strip().startswith("+"):
+        return "+" + digits
+    code = COUNTRY_CODES[market]
+    if digits.startswith("00"):
+        return "+" + digits[2:]
+    if market == "uk" and digits.startswith("0"):
+        return "+44" + digits[1:]
+    if market == "us" and len(digits) == 10:
+        return "+1" + digits
+    return "+" + (digits if digits.startswith(code) else code + digits)
+
+
+def money(value: str) -> int | None:
+    text = re.sub(r"[^\d.,-]", "", value or "").replace(",", "")
+    if not text:
+        return None
+    try:
+        return int(round(float(text) * 100))
+    except ValueError:
+        return None
+
+
+def parse_local(row: dict, mapping: dict[str, str], zone: ZoneInfo) -> datetime | None:
+    if "start" in mapping and row.get(mapping["start"]):
+        text = row[mapping["start"]].strip()
+    elif "date" in mapping and "time" in mapping:
+        text = f"{row.get(mapping['date'], '').strip()} {row.get(mapping['time'], '').strip()}"
+    else:
+        return None
+    for fmt in ("%Y-%m-%d %H:%M", "%Y-%m-%dT%H:%M", "%d/%m/%Y %H:%M", "%m/%d/%Y %H:%M", "%d %b %Y %H:%M", "%Y-%m-%d %I:%M %p", "%d/%m/%Y %I:%M %p", "%m/%d/%Y %I:%M %p"):
+        try:
+            return datetime.strptime(text, fmt).replace(tzinfo=zone)
+        except ValueError:
+            continue
+    return None
+
+
+def read_csv(path: Path) -> tuple[list[str], list[dict]]:
+    with path.open(encoding="utf-8-sig", newline="") as handle:
+        reader = csv.DictReader(handle)
+        return list(reader.fieldnames or []), list(reader)
+
+
+def migrate_check(clients: Path | None, appointments: Path | None, gift_cards: Path | None, timezone_name: str, market: str, now: datetime,
+                  services: list[str], staff: list[str], date_order: str = "auto") -> dict:
+    zone = ZoneInfo(timezone_name)
+    report: dict = {"schemaVersion": "maggie-service-migration-dry-run.v1", "writes": False, "timezone": timezone_name, "market": market}
+    errors: list[str] = []
+    warnings: list[str] = []
+    digest = hashlib.sha256()
+    if clients:
+        headers, rows = read_csv(clients)
+        digest.update(clients.read_bytes())
+        mapping, unmapped = map_columns(headers, ["first_name", "last_name", "name", "email", "phone", "marketing", "notes", "external_id"])
+        if not ({"email", "phone"} & set(mapping)):
+            errors.append("clients: no e-mail or phone column recognised; map one before importing")
+        seen_email, seen_phone, dupes, consented, kept, row_errors = set(), set(), 0, 0, 0, []
+        for index, row in enumerate(rows, start=2):
+            email = (row.get(mapping.get("email", ""), "") or "").strip().lower()
+            phone = e164(row.get(mapping.get("phone", ""), ""), market) if "phone" in mapping else None
+            if not email and not phone and not (row.get(mapping.get("name", ""), "") or row.get(mapping.get("first_name", ""), "")):
+                row_errors.append(f"row {index}: empty")
+                continue
+            if (email and email in seen_email) or (not email and phone and phone in seen_phone):
+                dupes += 1
+                continue
+            if email:
+                seen_email.add(email)
+            if phone:
+                seen_phone.add(phone)
+            kept += 1
+            if "marketing" in mapping and (row.get(mapping["marketing"], "") or "").strip().lower() in YES:
+                consented += 1
+        report["clients"] = {"rows": len(rows), "toImport": kept, "duplicatesMerged": dupes, "marketingConsent": consented, "columns": mapping, "unmappedColumns": unmapped, "rowErrors": row_errors[:20]}
+        if "marketing" not in mapping:
+            warnings.append("clients: no marketing-consent column; imported clients get no marketing (consent is never assumed)")
+    if appointments:
+        headers, rows = read_csv(appointments)
+        digest.update(appointments.read_bytes())
+        mapping, unmapped = map_columns(headers, ["start", "date", "time", "service", "staff", "duration", "price", "status", "email", "phone", "name", "external_id"])
+        if not ("start" in mapping or {"date", "time"} <= set(mapping)) or "service" not in mapping:
+            errors.append("appointments: need a start (or date + time) and a service column")
+        service_keys = {norm(name): name for name in services}
+        staff_keys = {norm(name): name for name in staff}
+        future, past, cancelled, unmatched_services, unmatched_staff, bad_rows = [], 0, 0, set(), set(), []
+        for index, row in enumerate(rows, start=2):
+            if "status" in mapping and CANCELLED.search(row.get(mapping["status"], "") or ""):
+                cancelled += 1
+                continue
+            start = parse_local(row, mapping, zone)
+            if start is None:
+                bad_rows.append(f"row {index}: unreadable date/time")
+                continue
+            if start.astimezone(timezone.utc) <= now:
+                past += 1
+                continue
+            duration = int(re.sub(r"\D", "", row.get(mapping.get("duration", ""), "") or "") or 60)
+            service = row.get(mapping["service"], "")
+            person = row.get(mapping.get("staff", ""), "") if "staff" in mapping else ""
+            if services and norm(service) not in service_keys:
+                unmatched_services.add(service)
+            if person and staff and norm(person) not in staff_keys:
+                unmatched_staff.add(person)
+            future.append({"row": index, "startUtc": start.astimezone(timezone.utc), "end": start.astimezone(timezone.utc) + timedelta(minutes=duration), "staff": norm(person)})
+        clashes = []
+        by_staff: dict[str, list[dict]] = {}
+        for item in sorted(future, key=lambda a: a["startUtc"]):
+            if not item["staff"]:
+                continue
+            for other in by_staff.get(item["staff"], []):
+                if other["end"] > item["startUtc"]:
+                    clashes.append(f"rows {other['row']} and {item['row']}: same team member at overlapping times")
+            by_staff.setdefault(item["staff"], []).append(item)
+        report["appointments"] = {"rows": len(rows), "future": len(future), "pastSkipped": past, "cancelledSkipped": cancelled, "clashes": clashes[:20], "unmatchedServices": sorted(unmatched_services)[:20],
+                                  "unmatchedStaff": sorted(unmatched_staff)[:20], "rowErrors": bad_rows[:20], "columns": mapping, "unmappedColumns": unmapped,
+                                  "firstUtc": _iso(min(a["startUtc"] for a in future)) if future else None}
+        if unmatched_services:
+            warnings.append(f"appointments: {len(unmatched_services)} service name(s) match no imported service; map them or create them first")
+        if clashes:
+            warnings.append(f"appointments: {len(clashes)} clash(es) are reported, not forced; resolve them with the business")
+    if gift_cards:
+        headers, rows = read_csv(gift_cards)
+        digest.update(gift_cards.read_bytes())
+        mapping, unmapped = map_columns(headers, ["code", "balance", "expiry"])
+        if not {"code", "balance"} <= set(mapping):
+            errors.append("gift cards: need code and balance columns")
+        codes, total, zero, bad = set(), 0, 0, []
+        for index, row in enumerate(rows, start=2):
+            code = (row.get(mapping.get("code", ""), "") or "").strip().upper()
+            balance = money(row.get(mapping.get("balance", ""), ""))
+            if not code or balance is None:
+                bad.append(f"row {index}: missing code or balance")
+                continue
+            if balance <= 0:
+                zero += 1
+                continue
+            if code in codes:
+                bad.append(f"row {index}: duplicate code")
+                continue
+            codes.add(code)
+            total += balance
+        report["giftCards"] = {"rows": len(rows), "toImport": len(codes), "zeroBalanceSkipped": zero, "totalBalanceMinor": total, "namespace": "IMPORT:<code>", "rowErrors": bad[:20], "columns": mapping, "unmappedColumns": unmapped}
+    report["undoKey"] = "import-" + digest.hexdigest()[:16]
+    report["plan"] = [
+        "create the import record (undo key) before writing",
+        "clients: insert or merge by e-mail then phone; marketing consent only when opted in",
+        "appointments: create bookings with source=import in the venue time zone; clashes stay unimported",
+        "gift cards: issue codes in the IMPORT: namespace with their balance and expiry in a paused 'Imported gift cards' voucher",
+        "undo deletes the import's bookings and the clients/team it created when unused, and voids untouched imported codes",
+        "send the optional \"we've moved\" e-mail once, only to imported clients with marketing consent, while online booking is live",
+    ]
+    report["errors"], report["warnings"] = errors, warnings
+    report["status"] = "failed" if errors else ("warning" if warnings else "ready")
+    return report
+
+
+def _iso(value: datetime) -> str:
+    return value.strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="maggie service migrate-check", description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    parser.add_argument("--project", type=Path, default=Path("."))
+    parser.add_argument("--clients", type=Path)
+    parser.add_argument("--appointments", type=Path)
+    parser.add_argument("--gift-cards", type=Path)
+    parser.add_argument("--timezone", required=True, help="the venue's IANA zone, e.g. Europe/London")
+    parser.add_argument("--market", choices=sorted(COUNTRY_CODES), default="uk")
+    parser.add_argument("--service", action="append", default=[], help="service name already in the catalogue (repeat)")
+    parser.add_argument("--staff", action="append", default=[], help="team member name (repeat)")
+    parser.add_argument("--now", help="ISO instant (default: now)")
+    parser.add_argument("--output", type=Path)
+    args = parser.parse_args(argv)
+    if not (args.clients or args.appointments or args.gift_cards):
+        parser.error("pass at least one of --clients, --appointments, --gift-cards")
+    now = datetime.fromisoformat(args.now.replace("Z", "+00:00")) if args.now else datetime.now(timezone.utc)
+    try:
+        report = migrate_check(args.clients, args.appointments, args.gift_cards, args.timezone, args.market, now, args.service, args.staff)
+    except (OSError, ValueError, csv.Error) as error:
+        print(f"BLOCKED: maggie service migrate-check: {error}", file=sys.stderr)
+        return 2
+    text = json.dumps(report, indent=2, ensure_ascii=False, default=str)
+    if args.output:
+        args.output.parent.mkdir(parents=True, exist_ok=True)
+        args.output.write_text(text + "\n", encoding="utf-8")
+    print(text)
+    return 1 if report["status"] == "failed" else 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/bundled-tools/clis/maggie_social_queue.py

@@ -318,6 +318,8 @@ def check_campaigns(document: dict) -> dict:
             errors.append(f"campaign {cid} has invalid status {status}")
             continue
         blockers = campaign_readiness(campaign)
+        if campaign.get("plan_status") == "failed" and not campaign.get("ideas"):
+            errors.append(f"campaign {cid} was created only to be planned and the plan failed: delete it (or create it only after the plan succeeds) so retries do not pile up empty drafts")
         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,

package/bundled-tools/clis/maggie_social_share.py

@@ -7,7 +7,9 @@ import json
 import sys
 from datetime import datetime, timezone
 from pathlib import Path
+from urllib.error import HTTPError, URLError
 from urllib.parse import parse_qsl, urlencode, urlsplit, urlunsplit
+from urllib.request import Request, urlopen
 
 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
@@ -15,6 +17,18 @@ from maggie_social_queue import check_campaigns, connection_health, parse_instan
 
 LIMITS = {"linkedin": 3000, "facebook": 63206, "x": 280}
 REQUIRED = ("source_content_id", "title", "canonical_url")
+PUBLISH_MODES = ("image", "link_preview")
+LIVE_STATUSES = {"approved", "scheduled", "publishing", "published"}
+
+
+def host_of(url: str) -> str:
+    return (urlsplit(str(url or "")).hostname or "").lower().removeprefix("www.")
+
+
+def on_workspace_domain(url: str, domain: str) -> bool:
+    """True when the URL's host is the workspace domain or one of its subdomains."""
+    host, domain = host_of(url), str(domain or "").lower().strip().removeprefix("www.").rstrip(".")
+    return bool(host and domain) and (host == domain or host.endswith("." + domain))
 
 
 def read(path: Path) -> dict:
@@ -31,38 +45,163 @@ def tracked_url(url: str, channel: str) -> str:
     return urlunsplit((parsed.scheme, parsed.netloc, parsed.path, urlencode(query), parsed.fragment))
 
 
-def plan(content: dict, channels: list[str]) -> dict:
+# Only a definite "gone" answer drops an article. Blocked (403/429), failing
+# (5xx) or unreachable pages are kept: a firewall or an outage must never empty
+# the list of articles to share.
+GONE = {404, 410}
+
+
+def fetch_status(url: str, timeout: float = 10.0) -> int | None:
+    """Final HTTP status after redirects, or None when the page could not be reached."""
+    for method in ("HEAD", "GET"):
+        request = Request(url, method=method, headers={"User-Agent": "MaggieSocialShare/1.0 (+link check)", "Accept": "text/html,*/*"})
+        try:
+            with urlopen(request, timeout=timeout) as response:
+                return int(response.status)
+        except HTTPError as error:
+            # Some servers refuse HEAD; ask again with GET before deciding.
+            if method == "HEAD" and error.code in {400, 403, 405, 501}:
+                continue
+            return int(error.code)
+        except (URLError, TimeoutError, OSError):
+            return None
+    return None
+
+
+def link_verdict(status: int | None) -> str:
+    if status in GONE:
+        return "gone"
+    if status is not None and 200 <= status < 400:
+        return "live"
+    return "unknown"
+
+
+def check_links(urls: list[str], cache_path: Path | None, ttl_hours: float, now: datetime, fetch=fetch_status) -> dict:
+    cache: dict = {}
+    if cache_path and cache_path.is_file():
+        try:
+            cache = json.loads(cache_path.read_text(encoding="utf-8"))
+        except (OSError, json.JSONDecodeError):
+            cache = {}
+    results = []
+    for url in dict.fromkeys(urls):
+        cached = cache.get(url)
+        fresh = False
+        if isinstance(cached, dict) and cached.get("checked_at"):
+            try:
+                fresh = (now - parse_instant(cached["checked_at"], "checked_at")).total_seconds() < ttl_hours * 3600
+            except ValueError:
+                fresh = False
+        if fresh:
+            status, source = cached.get("status"), "cache"
+        else:
+            status, source = fetch(url), "fetched"
+            cache[url] = {"status": status, "checked_at": now.isoformat().replace("+00:00", "Z")}
+        results.append({"url": url, "status": status, "verdict": link_verdict(status), "source": source})
+    if cache_path:
+        cache_path.parent.mkdir(parents=True, exist_ok=True)
+        cache_path.write_text(json.dumps(cache, indent=2) + "\n", encoding="utf-8")
+    gone = [item for item in results if item["verdict"] == "gone"]
+    return {"valid": True, "checked": len(results), "skip": gone, "keep": [item for item in results if item["verdict"] != "gone"], "results": results}
+
+
+def plan(content: dict, channels: list[str], workspace_domain: str | None = None) -> dict:
     errors = [f"missing {key}" for key in REQUIRED if not content.get(key)]
     invalid = [channel for channel in channels if channel not in LIMITS]
     if invalid:
         errors.append("unsupported channels: " + ", ".join(invalid))
+    domain = workspace_domain or content.get("workspace_domain")
+    if not domain:
+        errors.append("workspace_domain is required: posts may only share articles published on the workspace's own site")
+    elif content.get("canonical_url") and not on_workspace_domain(content["canonical_url"], domain):
+        errors.append(f"canonical_url is on {host_of(content['canonical_url'])}, not {domain}: pick an article published on this workspace's own domain")
     if errors:
         raise ValueError("; ".join(errors))
+    image = content.get("image_url")
     return {
         "schema_version": "1.0",
         "status": "draft",
         "source_content_id": content["source_content_id"],
         "title": content["title"],
         "canonical_url": content["canonical_url"],
+        "workspace_domain": domain,
         "cta": content.get("cta"),
-        "channels": [{"name": channel, "character_limit": LIMITS[channel], "tracked_url": tracked_url(content["canonical_url"], channel), "copy": None, "status": "needs-copy"} for channel in channels],
+        "image_url": image,
+        # A post with its own image goes out as an image post with the link in the text;
+        # link_preview is the default only without an image, or when the person switches it.
+        "channels": [{"name": channel, "character_limit": LIMITS[channel], "tracked_url": tracked_url(content["canonical_url"], channel), "publish_mode": "image" if image else "link_preview", "copy": None, "status": "needs-copy"} for channel in channels],
         "approval_required": True,
         "publish_requires": ["approved", "active provider connection", "explicit execute flag"],
     }
 
 
+def shared_picture_errors(posts: list[dict], label: str) -> list[str]:
+    """Posts written together for several channels share one picture.
+
+    A channel may differ only when a person picked its picture
+    (`image_source: "user"`)."""
+    automatic = [post for post in posts if post.get("image_source") != "user"]
+    pictures = {post.get("image_url") or None for post in automatic}
+    if len(pictures) <= 1:
+        return []
+    by_picture: dict[str, list[str]] = {}
+    for post in automatic:
+        by_picture.setdefault(post.get("image_url") or "(none)", []).append(str(post.get("channel") or post.get("name") or post.get("id")))
+    detail = "; ".join(f"{', '.join(names)}: {picture}" for picture, names in by_picture.items())
+    return [f"{label}: channels written together must share one picture ({detail}); set image_source user on a channel whose picture a person chose"]
+
+
+def picture_groups(value: dict) -> dict:
+    """Check that drafts written from one idea share one picture across channels."""
+    drafts = value.get("drafts", []) if isinstance(value, dict) else value
+    groups: dict[str, list[dict]] = {}
+    for draft in drafts:
+        key = draft.get("idea_id") or draft.get("group_id")
+        if key:
+            groups.setdefault(str(key), []).append(draft)
+    errors: list[str] = []
+    report = []
+    for key, items in sorted(groups.items()):
+        problems = shared_picture_errors(items, f"idea {key}")
+        errors.extend(problems)
+        automatic = [item.get("image_url") for item in items if item.get("image_source") != "user"]
+        report.append({"idea_id": key, "channels": [item.get("channel") for item in items], "picture": automatic[0] if automatic and not problems else None, "shared": not problems})
+    return {"valid": not errors, "errors": errors, "ideas": report}
+
+
 def validate(value: dict) -> list[str]:
     errors = [f"missing {key}" for key in REQUIRED if not value.get(key)]
     if value.get("status") not in {"draft", "approved", "scheduled", "publishing", "published", "failed", "cancelled"}:
         errors.append("invalid status")
     if value.get("status") == "published" and not value.get("provider_post_id"):
         errors.append("published draft requires provider_post_id")
-    for channel in value.get("channels", []):
+    domain = value.get("workspace_domain")
+    if domain and value.get("canonical_url") and not on_workspace_domain(value["canonical_url"], domain):
+        errors.append(f"canonical_url is on {host_of(value['canonical_url'])}, not the workspace domain {domain}")
+    elif not domain and value.get("status") in LIVE_STATUSES:
+        errors.append("workspace_domain is required before approval: the source must be published on the workspace's own domain")
+    channels = value.get("channels", [])
+    if value.get("image_url"):
+        errors.extend(shared_picture_errors([{**channel, "image_url": channel.get("image_url", value["image_url"])} for channel in channels], "draft"))
+    for channel in channels:
         name = channel.get("name")
         if name not in LIMITS:
             errors.append(f"unsupported channel: {name}")
-        if channel.get("copy") and len(channel["copy"]) > LIMITS.get(name, 0):
-            errors.append(f"copy exceeds {name} limit")
+        mode = channel.get("publish_mode")
+        if mode is not None and mode not in PUBLISH_MODES:
+            errors.append(f"{name}: publish_mode must be image or link_preview")
+        has_image = bool(channel.get("image_url") or value.get("image_url"))
+        if has_image and mode is None:
+            errors.append(f"{name}: the post has an image, so publish_mode must be set (image by default)")
+        if has_image and mode == "link_preview" and channel.get("publish_mode_source") != "user":
+            errors.append(f"{name}: an attached image would not be published as a link preview; use publish_mode image, or record publish_mode_source user when the person chose the preview")
+        if mode == "image" and not has_image:
+            errors.append(f"{name}: publish_mode image needs an image")
+        copy = channel.get("copy")
+        if copy and mode == "image" and channel.get("tracked_url") and channel["tracked_url"] not in copy and value.get("canonical_url", "") not in copy:
+            errors.append(f"{name}: an image post carries the link in its text; add the tracked URL to the copy")
+        if copy and len(copy) > LIMITS.get(name, 0):
+            errors.append(f"copy exceeds {name} limit" + (" (the link counts)" if mode == "image" else ""))
     return errors
 
 
@@ -72,7 +211,15 @@ def main() -> int:
     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("--workspace-domain", help="the workspace's own site domain; the source must be published there")
     create.add_argument("--output")
+    create.add_argument("--check-link", action="store_true", help="fetch canonical_url first and refuse a definite 404/410")
+    pictures = sub.add_parser("pictures", help="check that drafts written from one idea share one picture on every channel")
+    pictures.add_argument("input", help='JSON: {"drafts": [{"id", "idea_id", "channel", "image_url", "image_source"?}]}')
+    links = sub.add_parser("link-check", help="drop articles whose link is gone (404/410) before planning posts; keep blocked or failing pages")
+    links.add_argument("input", help="JSON: a list of URLs or article objects with canonical_url, or {\"articles\": [...]}")
+    links.add_argument("--cache", default=".maggie/social-link-cache.json", help="verdict cache (default: .maggie/social-link-cache.json); 'none' disables it")
+    links.add_argument("--ttl-hours", type=float, default=6.0)
     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")
@@ -89,14 +236,30 @@ def main() -> int:
     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")
+    schema = sub.add_parser("schema-check", help="estimate a structured-output JSON schema's complexity before a model rejects it")
+    schema.add_argument("input")
     args = parser.parse_args()
     try:
+        if args.command == "link-check":
+            raw = json.loads(Path(args.input).read_text(encoding="utf-8"))
+            articles = raw.get("articles", []) if isinstance(raw, dict) else raw
+            urls = [item if isinstance(item, str) else item.get("canonical_url") or item.get("url") for item in articles]
+            result = check_links([url for url in urls if url], None if args.cache == "none" else Path(args.cache), args.ttl_hours, datetime.now(timezone.utc))
+            by_url = {item["url"]: item for item in result["results"]}
+            result["articles"] = [item for item in articles if by_url.get(item if isinstance(item, str) else (item.get("canonical_url") or item.get("url")), {}).get("verdict") != "gone"]
+            print(json.dumps(result, indent=2, ensure_ascii=False))
+            return 0
         value = read(Path(args.input))
         now = datetime.now(timezone.utc)
-        if args.command == "adapters":
+        if args.command == "schema-check":
+            from maggie_schema_complexity import check_schema
+            result = check_schema(value)
+        elif 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 == "pictures":
+            result = picture_groups(value if isinstance(value, dict) else {"drafts": value})
         elif args.command == "reconcile":
             result = reconcile(value)
         elif args.command == "campaigns":
@@ -110,7 +273,11 @@ def main() -> int:
             return 0
         else:
             if args.command == "plan":
-                value = plan(value, [item.strip() for item in args.channels.split(",") if item.strip()])
+                if args.check_link and value.get("canonical_url"):
+                    status = fetch_status(value["canonical_url"])
+                    if link_verdict(status) == "gone":
+                        raise ValueError(f"canonical_url answers HTTP {status}: the article is gone; pick a live article (blocked or failing pages are not treated as gone)")
+                value = plan(value, [item.strip() for item in args.channels.split(",") if item.strip()], args.workspace_domain)
                 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")

package/bundled-tools/integrations/maggie-api-pull.md

@@ -74,6 +74,28 @@ The import is draft-only and never publishes. It rejects missing IDs, invalid
 slugs, and empty content; changed source checksums stop for manual conflict
 review. Approval and publication are separate MaggieDash transitions.
 
+## Where a delivered post went live
+
+A pulled post is useful to other channels (social posts that link it,
+internal links) only once its live URL is known; without it a planner falls
+back to an older stored URL, which after a platform move answers 404. So:
+
+1. When the site publishes a delivered post, it reports the URL it went live
+   at (`POST /content-tracking/report-state` with the content ID, the URL and
+   `published`) and records it locally:
+   `maggie blog live-urls record --content-id ID --url URL`. The site's report
+   is authoritative.
+2. A scheduled sitemap match fills the gaps:
+   `maggie blog live-urls match --sitemap https://example.com/sitemap.xml --write --report-body .maggie/live-urls-report.json`,
+   then send that body with `maggie api report-state --body-file … --execute`.
+
+Matching is **additive**: a post that already has a live URL keeps it, and a
+post this run did not find is left as it was — never marked unmatched — so the
+match can run daily without retiring earlier matches. When translated copies
+share the slug (`/blog/x`, `/zh-hans/blog/x`), the URL **without a locale
+segment** wins. The same two rules apply to the platform's own sitemap
+matching for API Pull destinations.
+
 ## Project context synchronization
 
 `GET /project-context` returns sanitized, read-only context scoped by the API