@topy-ai/maggie 0.7.53 → 0.7.54

package/bundled-tools/clis/maggie_feedback.py

@@ -20,6 +20,10 @@ from urllib.request import Request, urlopen
 
 
 DEFAULT_ENDPOINT = "https://feedback.noblox.app/api/feedback"
+# Both hosts accept the same anonymous contract and de-duplicate on feedbackId,
+# so a draft is offered to the next one only when the previous host failed
+# before storing it (network error or a 5xx such as Cloudflare's 52x).
+DEFAULT_ENDPOINTS = (DEFAULT_ENDPOINT, "https://feedback.cmo.so/api/feedback")
 SECRET_RE = re.compile(r"(?i)(bearer\s+|(?:api[_-]?key|token|secret|password|npm_config[^=]*|authorization)\s*[=:]\s*)[^\s,;]+")
 LOCAL_PATH_RE = re.compile(
     r"(?<![A-Za-z0-9])(?:~/(?:[^\s,;:)\]}]+/)*[^\s,;:)\]}]+|"
@@ -348,28 +352,52 @@ def hosted_payload(data: dict) -> dict:
     return payload
 
 
+def submit_endpoints(value: object) -> list[str]:
+    endpoints = [value] if isinstance(value, str) else list(value or DEFAULT_ENDPOINTS)
+    result = []
+    for endpoint in endpoints:
+        endpoint = str(endpoint).rstrip("/")
+        parsed = urlparse(endpoint)
+        if parsed.scheme != "https" or not parsed.netloc:
+            raise ValueError("endpoint must be an absolute HTTPS URL")
+        if endpoint not in result:
+            result.append(endpoint)
+    return result
+
+
 def submit(args: argparse.Namespace) -> int:
     if not args.confirm:
         raise ValueError("submit requires --confirm; feedback is never sent implicitly")
     path = Path(args.feedback)
     data = read_feedback(path)
-    endpoint = args.endpoint.rstrip("/")
-    parsed = urlparse(endpoint)
-    if parsed.scheme != "https" or not parsed.netloc:
-        raise ValueError("endpoint must be an absolute HTTPS URL")
+    endpoints = submit_endpoints(args.endpoint)
     payload = hosted_payload(data)
     payload["projectContext"] = data.get("projectContext") if data.get("privacy", {}).get("projectContextAllowed") else None
-    request = Request(endpoint, data=json.dumps(payload, ensure_ascii=False).encode(), headers={"Content-Type": "application/json", "Accept": "application/json", "User-Agent": "MaggieFeedback/0.1"}, method="POST")
-    try:
-        with urlopen(request, timeout=20) as response:
-            raw = response.read(1_000_000).decode("utf-8", "replace")
-            result = json.loads(raw) if raw else {}
-    except (HTTPError, URLError, TimeoutError) as error:
-        raise RuntimeError(f"feedback submission failed: {error}") from error
+    body = json.dumps(payload, ensure_ascii=False).encode()
+    failures = []
+    for endpoint in endpoints:
+        request = Request(endpoint, data=body, headers={"Content-Type": "application/json", "Accept": "application/json", "User-Agent": "MaggieFeedback/0.1"}, method="POST")
+        try:
+            with urlopen(request, timeout=20) as response:
+                raw = response.read(1_000_000).decode("utf-8", "replace")
+                result = json.loads(raw) if raw else {}
+            break
+        except HTTPError as error:
+            failures.append({"endpoint": endpoint, "error": f"HTTP {error.code}"})
+            # A 4xx is the host rejecting this draft; another host would too.
+            if error.code < 500:
+                raise RuntimeError(f"feedback submission failed: {endpoint} answered HTTP {error.code}") from error
+        except (URLError, TimeoutError, OSError) as error:
+            failures.append({"endpoint": endpoint, "error": safe_text(getattr(error, "reason", error))})
+    else:
+        tried = "; ".join(f"{item['endpoint']} ({item['error']})" for item in failures)
+        raise RuntimeError(f"feedback submission failed on every endpoint: {tried}")
     ack = acknowledgement(result)
     data["submission"] = {"status": "submitted", "endpoint": endpoint, "submittedAt": now(), "acknowledgement": ack}
+    if failures:
+        data["submission"]["failedEndpoints"] = failures
     path.write_text(json.dumps(data, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
-    print(json.dumps({"feedbackId": data["feedbackId"], "status": "submitted", "acknowledgement": ack}, indent=2, ensure_ascii=False))
+    print(json.dumps({"feedbackId": data["feedbackId"], "status": "submitted", "endpoint": endpoint, "failedEndpoints": failures, "acknowledgement": ack}, indent=2, ensure_ascii=False))
     return 0
 
 
@@ -815,7 +843,7 @@ def main() -> int:
     preview_parser.add_argument("--format", choices=("json", "markdown"), default="json")
     submit_parser = sub.add_parser("submit")
     submit_parser.add_argument("feedback")
-    submit_parser.add_argument("--endpoint", default=DEFAULT_ENDPOINT)
+    submit_parser.add_argument("--endpoint", action="append", help="HTTPS endpoint; repeat for an ordered fallback list (default: the NoBlox host, then feedback.cmo.so)")
     submit_parser.add_argument("--confirm", action="store_true")
     list_parser = sub.add_parser("list")
     list_parser.add_argument("--project", default=argparse.SUPPRESS)

package/bundled-tools/clis/maggie_live_urls.py

@@ -0,0 +1,138 @@
+#!/usr/bin/env python3
+"""Record where API Pull deliveries went live, from the site's sitemap.
+
+A delivered post is useful to other channels (social posts, internal links)
+only once its live URL is known. The site should report it when it publishes;
+this matcher fills the gaps from the sitemap with two rules:
+
+* additive only: a record that already has a live URL keeps it, and a record
+  that matches nothing in this run is left as it was (never marked unmatched),
+  so the match can run on a schedule;
+* the original page first: when translated copies share the slug
+  (``/blog/x`` and ``/zh-hans/blog/x``), the URL without a locale segment wins.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+import xml.etree.ElementTree as ET
+from datetime import datetime, timezone
+from pathlib import Path
+from urllib.parse import urlsplit
+from urllib.request import Request, urlopen
+
+LOCALE_SEGMENT = re.compile(r"^[a-z]{2}(?:[-_][a-z0-9]{2,8})?$", re.I)
+MAX_SITEMAPS = 50
+
+
+def now() -> str:
+    return datetime.now(timezone.utc).isoformat().replace("+00:00", "Z")
+
+
+def fetch(location: str) -> str:
+    if not location.startswith(("http://", "https://")):
+        return Path(location).read_text(encoding="utf-8")
+    with urlopen(Request(location, headers={"User-Agent": "MaggieLiveUrls/1.0"}), timeout=20) as response:
+        return response.read(20_000_000).decode("utf-8", "replace")
+
+
+def sitemap_urls(location: str) -> list[str]:
+    """Every <loc> of a sitemap, following sitemap indexes (bounded)."""
+    seen: set[str] = set()
+    urls: list[str] = []
+    queue = [location]
+    while queue and len(seen) < MAX_SITEMAPS:
+        current = queue.pop(0)
+        if current in seen:
+            continue
+        seen.add(current)
+        root = ET.fromstring(fetch(current))
+        tag = root.tag.rsplit("}", 1)[-1]
+        locs = [element.text.strip() for element in root.iter() if element.tag.rsplit("}", 1)[-1] == "loc" and element.text]
+        if tag == "sitemapindex":
+            queue.extend(locs)
+        else:
+            urls.extend(locs)
+    return list(dict.fromkeys(urls))
+
+
+def has_locale_segment(url: str) -> bool:
+    parts = [part for part in urlsplit(url).path.split("/") if part]
+    return len(parts) > 1 and bool(LOCALE_SEGMENT.match(parts[0]))
+
+
+def best_match(slug: str, urls: list[str]) -> str | None:
+    candidates = [url for url in urls if [part for part in urlsplit(url).path.split("/") if part][-1:] == [slug]]
+    if not candidates:
+        return None
+    # Original before translated copies, then the shortest path.
+    return sorted(candidates, key=lambda url: (has_locale_segment(url), len(urlsplit(url).path), url))[0]
+
+
+def match(state: dict, urls: list[str]) -> dict:
+    records = state.get("content", {}) if isinstance(state.get("content"), dict) else {}
+    matched, kept, missing = [], [], []
+    for key, record in records.items():
+        if not isinstance(record, dict):
+            continue
+        if record.get("live_url"):
+            kept.append({"remote_content_id": record.get("remote_content_id") or key, "live_url": record["live_url"], "source": record.get("live_url_source", "")})
+            continue
+        slug = str(record.get("slug") or "").strip("/")
+        url = best_match(slug, urls) if slug else None
+        if url:
+            record["live_url"] = url
+            record["live_url_source"] = "sitemap"
+            record["live_url_matched_at"] = now()
+            matched.append({"remote_content_id": record.get("remote_content_id") or key, "slug": slug, "live_url": url})
+        else:
+            missing.append({"remote_content_id": record.get("remote_content_id") or key, "slug": slug})
+    return {"matched": matched, "kept": kept, "notFound": missing}
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
+    sub = parser.add_subparsers(dest="command", required=True)
+    run = sub.add_parser("match", help="fill missing live URLs of delivered posts from the sitemap (additive)")
+    run.add_argument("--project", default=".")
+    run.add_argument("--state", help="lifecycle state (default: .maggie/ai-cmo-lifecycle.json)")
+    run.add_argument("--sitemap", required=True, help="sitemap URL or file (indexes are followed)")
+    run.add_argument("--write", action="store_true", help="save the new live URLs into the state file")
+    run.add_argument("--report-body", help="write a report-state body for the newly matched posts (send with `maggie api report-state --body-file`)")
+    record = sub.add_parser("record", help="record a live URL the site reported when it published a delivered post")
+    record.add_argument("--project", default=".")
+    record.add_argument("--state")
+    record.add_argument("--content-id", required=True)
+    record.add_argument("--url", required=True)
+    args = parser.parse_args()
+    state_path = Path(args.state) if args.state else Path(args.project) / ".maggie" / "ai-cmo-lifecycle.json"
+    try:
+        state = json.loads(state_path.read_text(encoding="utf-8"))
+        if args.command == "record":
+            if urlsplit(args.url).scheme not in {"http", "https"}:
+                raise ValueError("--url must be an absolute http(s) URL")
+            target = state.get("content", {}).get(args.content_id)
+            if not isinstance(target, dict):
+                raise ValueError(f"no delivered post {args.content_id} in {state_path}")
+            # The site's own report is authoritative and replaces a sitemap guess.
+            target.update({"live_url": args.url, "live_url_source": "site", "live_url_matched_at": now()})
+            state_path.write_text(json.dumps(state, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+            print(json.dumps({"status": "recorded", "remote_content_id": args.content_id, "live_url": args.url}, indent=2))
+            return 0
+        result = match(state, sitemap_urls(args.sitemap))
+        if args.write:
+            state_path.write_text(json.dumps(state, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+        if args.report_body and result["matched"]:
+            body = {"items": [{"content_id": item["remote_content_id"], "url": item["live_url"], "status": "published"} for item in result["matched"]][:500]}
+            Path(args.report_body).write_text(json.dumps(body, indent=2) + "\n", encoding="utf-8")
+        print(json.dumps({"status": "matched" if args.write else "dry-run", **{key: value for key, value in result.items()}, "counts": {key: len(value) for key, value in result.items()}}, indent=2, ensure_ascii=False))
+        return 0
+    except (OSError, ValueError, json.JSONDecodeError, ET.ParseError) as error:
+        print(f"maggie live-urls: {error}", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/bundled-tools/clis/maggie_localization.py

@@ -17,6 +17,7 @@ from localization_runner import generate, process_adapter
 
 sys.path.insert(0, str(Path(__file__).resolve().parent))
 import maggie_email_localization as email_localization
+import maggie_localization_keys as localization_keys
 
 
 def generate_job(args: argparse.Namespace) -> int:
@@ -399,6 +400,7 @@ def main() -> int:
     for name in ("stale", "glossary"):
         command = sub.add_parser(name); command.add_argument("--project", type=Path, default=Path("."))
     email_localization.add_parsers(sub)
+    localization_keys.add_parsers(sub)
     args = parser.parse_args()
     try:
         if args.command == "generate": return generate_job(args)
@@ -411,6 +413,7 @@ def main() -> int:
         if args.command == "publish": return publish(args.job, args.confirm)
         if args.command == "stale": return stale_jobs(args.project)
         if args.command in ("email-matrix", "lifecycle"): return email_localization.run(args)
+        if args.command in ("key-check", "fragments"): return localization_keys.run(args)
         return glossary(args.project)
     except (OSError, ValueError, json.JSONDecodeError) as error:
         print(f"ERROR: {error}", file=sys.stderr); return 1

package/bundled-tools/clis/maggie_localization_keys.py

@@ -0,0 +1,151 @@
+"""Translation keys for generated pages: text keys are site-wide, positions are not.
+
+A translation stored under its source text applies to every page that shows
+that text. That is right for a shared header, wrong for generic phrases on
+generated pages ("your practice" is a clinic on one page and a firm on
+another). `key-check` reads per-page translation rows and lists the texts that
+need position keys. `fragments` reads rendered HTML and lists text split
+around an inline span (a styled brand name) into pieces too short to translate
+on their own ("Can", "No.", "What").
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import re
+from html.parser import HTMLParser
+from pathlib import Path
+
+INLINE = {"span", "strong", "em", "b", "i", "a", "mark", "small", "sup", "sub", "u"}
+BLOCK = {"p", "h1", "h2", "h3", "h4", "h5", "h6", "li", "td", "th", "dt", "dd", "figcaption", "blockquote", "button", "label", "summary", "caption"}
+SKIP = {"script", "style", "noscript", "template", "svg", "code", "pre"}
+WORD = re.compile(r"[\w'’-]+", re.UNICODE)
+
+
+def load_rows(path: Path) -> list[dict]:
+    value = json.loads(path.read_text(encoding="utf-8"))
+    rows = value.get("rows", []) if isinstance(value, dict) else value
+    if not isinstance(rows, list):
+        raise ValueError("rows must be a list of {page, position?, text, translation}")
+    return [row for row in rows if isinstance(row, dict)]
+
+
+def key_check(rows: list[dict], locale: str | None = None) -> dict:
+    """Source texts whose translation differs between pages cannot share a text key."""
+    by_text: dict[str, dict[str, set[str]]] = {}
+    for row in rows:
+        if locale and row.get("locale") not in (None, locale):
+            continue
+        text = " ".join(str(row.get("text") or "").split())
+        translation = " ".join(str(row.get("translation") or "").split())
+        if not text or not translation:
+            continue
+        by_text.setdefault(text, {}).setdefault(translation, set()).add(str(row.get("page") or "?"))
+    conflicts = []
+    for text, translations in sorted(by_text.items()):
+        if len(translations) > 1:
+            pages = sorted({page for group in translations.values() for page in group})
+            conflicts.append({"text": text, "translations": {translation: sorted(group)[:5] for translation, group in translations.items()}, "pages": len(pages)})
+    shared = sum(1 for translations in by_text.values() if len({page for group in translations.values() for page in group}) > 1)
+    return {
+        "valid": not conflicts,
+        "texts": len(by_text),
+        "sharedAcrossPages": shared,
+        "needPositionKeys": len(conflicts),
+        "conflicts": conflicts[:200],
+        "advice": "Store these under per-page position keys (render the source page, then key each node by page + position with a source hash); keep text keys only as a fallback for genuinely shared text." if conflicts else "",
+    }
+
+
+class FragmentParser(HTMLParser):
+    """Collect, per block element, the run of text pieces and inline spans."""
+
+    def __init__(self, brand: re.Pattern[str]) -> None:
+        super().__init__(convert_charrefs=True)
+        self.brand = brand
+        self.stack: list[str] = []
+        self.blocks: list[list[tuple[str, str]]] = []  # (kind, text): kind is "text" or "inline"
+        self.inline_depth = 0
+        self.inline_text = ""
+        self.skip = 0
+        self.findings: list[dict] = []
+
+    def handle_starttag(self, tag: str, attrs) -> None:  # noqa: ANN001
+        if tag in SKIP:
+            self.skip += 1
+            return
+        if tag in BLOCK:
+            self.blocks.append([])
+        elif tag in INLINE and self.blocks:
+            if self.inline_depth == 0:
+                self.inline_text = ""
+            self.inline_depth += 1
+
+    def handle_endtag(self, tag: str) -> None:
+        if tag in SKIP:
+            self.skip = max(0, self.skip - 1)
+            return
+        if tag in INLINE and self.inline_depth:
+            self.inline_depth -= 1
+            if self.inline_depth == 0 and self.blocks:
+                self.blocks[-1].append(("inline", self.inline_text))
+        elif tag in BLOCK and self.blocks:
+            self.finish(self.blocks.pop())
+
+    def handle_data(self, data: str) -> None:
+        if self.skip or not self.blocks:
+            return
+        if self.inline_depth:
+            self.inline_text += data
+        elif data.strip():
+            self.blocks[-1].append(("text", data))
+
+    def finish(self, parts: list[tuple[str, str]]) -> None:
+        if not any(kind == "inline" and self.brand.search(text) for kind, text in parts):
+            return
+        sentence = " ".join(" ".join(text.split()) for _, text in parts).strip()
+        for index, (kind, text) in enumerate(parts):
+            if kind != "text":
+                continue
+            neighbours = [parts[i] for i in (index - 1, index + 1) if 0 <= i < len(parts)]
+            if not any(other_kind == "inline" and self.brand.search(other_text) for other_kind, other_text in neighbours):
+                continue
+            words = WORD.findall(text)
+            if 1 <= len(words) <= 2:
+                self.findings.append({"fragment": " ".join(text.split()), "words": len(words), "sentence": sentence[:200]})
+
+
+def fragments(paths: list[Path], brand: str) -> dict:
+    pattern = re.compile(re.escape(brand), re.I)
+    findings = []
+    for path in paths:
+        parser = FragmentParser(pattern)
+        parser.feed(path.read_text(encoding="utf-8", errors="replace"))
+        findings.extend({"file": str(path), **item} for item in parser.findings)
+    return {
+        "valid": not findings,
+        "files": len(paths),
+        "fragments": findings[:500],
+        "advice": f"Translate the whole sentence around {brand!r} as one unit (keep the span as a placeholder such as {{brand}}) instead of storing these short pieces." if findings else "",
+    }
+
+
+def add_parsers(sub: argparse._SubParsersAction) -> None:
+    keys = sub.add_parser("key-check", help="list source texts translated differently on different pages (they need per-page position keys)")
+    keys.add_argument("rows", type=Path, help='JSON rows [{"page", "position"?, "text", "translation", "locale"?}]')
+    keys.add_argument("--locale")
+    split = sub.add_parser("fragments", help="find text split around an inline brand span into pieces too short to translate")
+    split.add_argument("--html", type=Path, nargs="+", required=True, help="rendered HTML files or directories (searched for *.html)")
+    split.add_argument("--brand", required=True, help="the inline span's text, e.g. the brand name")
+
+
+def run(args: argparse.Namespace) -> int:
+    if args.command == "key-check":
+        result = key_check(load_rows(args.rows), args.locale)
+    else:
+        files: list[Path] = []
+        for item in args.html:
+            files.extend(sorted(item.rglob("*.html")) if item.is_dir() else [item])
+        result = fragments(files, args.brand)
+    print(json.dumps(result, indent=2, ensure_ascii=False))
+    return 0 if result["valid"] else 1

package/bundled-tools/clis/maggie_media_generate.py

@@ -0,0 +1,174 @@
+#!/usr/bin/env python3
+"""Generate page pictures with a chosen engine, and plan a large run first.
+
+Engines:
+
+* ``codex`` — the local ``codex`` CLI's image tool on the signed-in ChatGPT
+  plan. No per-image charge, but it draws from the plan's quota and is slow
+  (about 75 s per picture observed). Accepts reference pictures (``--image``).
+* ``gemini`` — Gemini image generation with the project's own
+  ``GEMINI_API_KEY`` (billed to that Google account). Faster (about 19 s at 2K
+  observed). No reference pictures in this tool.
+
+``engine-plan`` states the time and cost of each engine for a run before it
+starts; ``generate`` draws one picture and never runs without ``--confirm``.
+"""
+from __future__ import annotations
+
+import argparse
+import base64
+import json
+import math
+import os
+import shutil
+import subprocess
+import sys
+import tempfile
+import time
+from pathlib import Path
+from urllib.error import HTTPError, URLError
+from urllib.request import Request, urlopen
+
+GEMINI_MODEL = "gemini-3.1-flash-image"
+GEMINI_ENDPOINT = "https://generativelanguage.googleapis.com/v1beta/models/{model}:generateContent"
+RATIOS = ("21:9", "16:9", "3:2", "4:3", "5:4", "1:1", "4:5", "3:4", "2:3", "9:16")
+# Observed seconds per picture (one worker); override with --seconds-codex / --seconds-gemini.
+OBSERVED_SECONDS = {"codex": 75.0, "gemini": 19.0}
+
+
+def parse_size(value: str) -> tuple[int, int]:
+    try:
+        width, height = (int(part) for part in value.lower().split("x"))
+    except ValueError as error:
+        raise ValueError("--size must look like 2400x1000") from error
+    if width < 64 or height < 64:
+        raise ValueError("--size is too small")
+    return width, height
+
+
+def nearest_ratio(width: int, height: int) -> str:
+    target = width / height
+    return min(RATIOS, key=lambda ratio: abs(math.log((int(ratio.split(":")[0]) / int(ratio.split(":")[1])) / target)))
+
+
+def image_size(width: int, height: int) -> str:
+    longest = max(width, height)
+    return "4K" if longest > 2600 else "2K" if longest > 1300 else "1K"
+
+
+def engine_plan(count: int, width: int, height: int, workers: int, references: bool, seconds: dict[str, float], gemini_unit_cost: float | None, currency: str) -> dict:
+    engines = []
+    for engine in ("codex", "gemini"):
+        per = seconds[engine]
+        wall = math.ceil(count / max(1, workers)) * per
+        row = {"engine": engine, "secondsPerPicture": per, "workers": workers, "estimatedMinutes": round(wall / 60, 1)}
+        if engine == "codex":
+            row.update({"billing": "ChatGPT plan quota (no per-picture charge)", "quotaPictures": count, "cost": None, "referenceImages": True})
+        else:
+            row.update({"billing": "the project's GEMINI_API_KEY (its Google account)", "aspectRatio": nearest_ratio(width, height), "imageSize": image_size(width, height),
+                        "cost": round(count * gemini_unit_cost, 2) if gemini_unit_cost is not None else None, "currency": currency if gemini_unit_cost is not None else None,
+                        "costNote": None if gemini_unit_cost is not None else "pass --gemini-unit-cost from the current Gemini price list to state the cost", "referenceImages": False})
+        engines.append(row)
+    usable = [row for row in engines if not (references and not row["referenceImages"])]
+    fastest = min(usable, key=lambda row: row["estimatedMinutes"])["engine"] if usable else None
+    return {"schemaVersion": "maggie-media-engine-plan.v1", "pictures": count, "size": f"{width}x{height}", "needsReferenceImages": references, "engines": engines, "fastest": fastest,
+            "confirmBeforeRunning": True, "note": "State this plan to the person and wait for a yes before a large run."}
+
+
+def gemini_generate(prompt: str, width: int, height: int, model: str, timeout: float) -> bytes:
+    key = os.environ.get("GEMINI_API_KEY", "")
+    if not key:
+        raise RuntimeError("--engine gemini needs GEMINI_API_KEY in the environment")
+    endpoint = os.environ.get("GEMINI_API_ENDPOINT") or GEMINI_ENDPOINT.format(model=model)
+    body = json.dumps({"contents": [{"role": "user", "parts": [{"text": prompt}]}],
+                       "generationConfig": {"responseModalities": ["IMAGE"], "imageConfig": {"aspectRatio": nearest_ratio(width, height), "imageSize": image_size(width, height)}}}).encode()
+    for attempt in range(1, 5):
+        request = Request(endpoint, data=body, method="POST", headers={"content-type": "application/json", "x-goog-api-key": key})
+        status, data = 0, {}
+        try:
+            with urlopen(request, timeout=timeout) as response:
+                status, data = response.status, json.loads(response.read() or b"{}")
+        except HTTPError as error:
+            status = error.code
+            try:
+                data = json.loads(error.read() or b"{}")
+            except json.JSONDecodeError:
+                data = {}
+        except (URLError, TimeoutError, OSError) as error:
+            data = {"error": {"message": type(error).__name__}}
+        parts = (((data.get("candidates") or [{}])[0].get("content") or {}).get("parts") or [])
+        image = next((part["inlineData"]["data"] for part in parts if isinstance(part, dict) and part.get("inlineData", {}).get("data")), None)
+        if 200 <= status < 300 and image:
+            return base64.b64decode(image)
+        if attempt == 4 or (400 <= status < 500 and status != 429):
+            reason = (data.get("error") or {}).get("message") or ((data.get("candidates") or [{}])[0].get("finishReason")) or f"HTTP {status}"
+            raise RuntimeError(f"Gemini: {str(reason)[:300]}")
+        time.sleep(float(os.environ.get("MAGGIE_MEDIA_RETRY_SECONDS", attempt * 15)))
+    raise RuntimeError("Gemini: no image")
+
+
+def codex_generate(prompt: str, width: int, height: int, images: list[Path], timeout: float) -> bytes:
+    if not shutil.which("codex"):
+        raise RuntimeError("--engine codex needs the codex CLI on PATH (signed in to ChatGPT)")
+    shape = "wide landscape (about 3:2 or wider)" if width >= height * 1.4 else "landscape" if width > height else "portrait" if width < height else "square"
+    with tempfile.TemporaryDirectory(prefix="maggie-media-") as work:
+        reference = "Use the attached image only as a reference for layout and content. " if images else ""
+        instruction = f"Use your image generation tool to create exactly one image, {shape}. {reference}{prompt} Save the final image into the current directory as out.png. Reply only with the saved path."
+        # `-i` takes several files, so `--` ends the list before the prompt.
+        argv = ["codex", "exec", "--skip-git-repo-check", "--sandbox", "workspace-write", *[item for path in images for item in ("-i", str(path.resolve()))], *(["--"] if images else []), instruction]
+        subprocess.run(argv, cwd=work, stdin=subprocess.DEVNULL, stdout=subprocess.DEVNULL, timeout=timeout, check=False)
+        out = Path(work) / "out.png"
+        if not out.is_file():
+            raise RuntimeError("codex did not save out.png")
+        return out.read_bytes()
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="maggie media", description=__doc__.splitlines()[0])
+    sub = parser.add_subparsers(dest="command", required=True)
+    plan = sub.add_parser("engine-plan", help="time and cost of each engine for a run, before it starts")
+    plan.add_argument("--count", type=int, required=True)
+    plan.add_argument("--size", default="1600x1200")
+    plan.add_argument("--workers", type=int, default=1)
+    plan.add_argument("--reference-images", action="store_true", help="the run redraws screenshots (codex only)")
+    plan.add_argument("--seconds-codex", type=float, default=OBSERVED_SECONDS["codex"])
+    plan.add_argument("--seconds-gemini", type=float, default=OBSERVED_SECONDS["gemini"])
+    plan.add_argument("--gemini-unit-cost", type=float, help="price of one picture at this size from the current Gemini price list")
+    plan.add_argument("--currency", default="USD")
+    gen = sub.add_parser("generate", help="draw one picture with the chosen engine")
+    gen.add_argument("--engine", choices=("codex", "gemini"), default="codex")
+    gen.add_argument("--prompt", required=True)
+    gen.add_argument("--size", default="1600x1200")
+    gen.add_argument("--image", type=Path, action="append", default=[], help="reference picture (codex only, repeatable)")
+    gen.add_argument("--output", type=Path, required=True, help="PNG path to write")
+    gen.add_argument("--model", default=GEMINI_MODEL)
+    gen.add_argument("--timeout", type=float, default=600)
+    gen.add_argument("--confirm", action="store_true")
+    args = parser.parse_args(argv)
+    try:
+        width, height = parse_size(args.size)
+        if args.command == "engine-plan":
+            print(json.dumps(engine_plan(args.count, width, height, args.workers, args.reference_images, {"codex": args.seconds_codex, "gemini": args.seconds_gemini}, args.gemini_unit_cost, args.currency), indent=2))
+            return 0
+        if not args.confirm:
+            print("CONFIRMATION_REQUIRED: generating a picture uses plan quota (codex) or a paid API (gemini); rerun with --confirm", file=sys.stderr)
+            return 2
+        for path in args.image:
+            if not path.is_file():
+                raise ValueError(f"--image {path} not found")
+        if args.engine == "gemini" and args.image:
+            raise ValueError("--image needs the codex engine")
+        started = time.monotonic()
+        data = gemini_generate(args.prompt, width, height, args.model, args.timeout) if args.engine == "gemini" else codex_generate(args.prompt, width, height, args.image, args.timeout)
+        args.output.parent.mkdir(parents=True, exist_ok=True)
+        args.output.write_bytes(data)
+        print(json.dumps({"engine": args.engine, "output": str(args.output), "bytes": len(data), "seconds": round(time.monotonic() - started, 1), "aspectRatio": nearest_ratio(width, height) if args.engine == "gemini" else None, "imageSize": image_size(width, height) if args.engine == "gemini" else None,
+                          "next": "resize/crop to the exact size and convert to WebP before use"}, indent=2))
+        return 0
+    except (OSError, ValueError, RuntimeError, subprocess.TimeoutExpired) as error:
+        print(f"BLOCKED: maggie media: {error}", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())