@topy-ai/maggie 0.7.53 → 0.7.55

package/bundled-tools/clis/maggie_live_urls.py

@@ -0,0 +1,147 @@
+#!/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:
+
+* every post without a live URL is matched, including one already tracked
+  with an empty value (a slug missing from the record is read from its
+  delivered address);
+* 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 slug_from(address: object) -> str:
+    path = urlsplit(str(address or "")).path.rstrip("/")
+    return path.rsplit("/", 1)[-1] if path else ""
+
+
+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
+        # A post already tracked with an empty (or blank) URL still needs one.
+        if str(record.get("live_url") or "").strip():
+            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("/") or slug_from(record.get("canonical_url"))
+        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())

package/bundled-tools/clis/maggie_mobile.py

@@ -28,6 +28,16 @@ made from: ``eas.json`` and ``package.json`` usually changed since. ``plan
 ``eas fingerprint:compare``, publish the update only when it matches, and
 always put the working copies back (verified by hash), even on failure. ``ota``
 is a dry run unless ``--confirm`` is given, because the update is published.
+
+``ota-guard`` checks the runtime an update would target against the runtimes
+of builds people have installed (a runtimes file kept with the app) and
+refuses when none matches. In a pnpm monorepo the fingerprint also hashes
+pnpm's virtual-store paths (``node_modules/.pnpm/<pkg>_<peer hash>``), so a
+dependency change in any workspace package can move the runtime;
+``ignorePaths`` and ``fileHookTransform`` cannot help because native module
+folders are added by their real path. With ``--publish --confirm`` it runs
+``eas update`` after a match and checks that the published runtime is the one
+that was checked.
 """
 
 from __future__ import annotations
@@ -180,6 +190,9 @@ def preflight(project: Path, app_dir: Path | None, config_json: Path | None, pro
     package = _load(app / "package.json") if (app / "package.json").is_file() else {}
     ignore = (app / ".fingerprintignore").read_text(encoding="utf-8") if (app / ".fingerprintignore").is_file() else ""
     errors, warnings, facts = check_profile(expo, eas, package, profile, platforms, auto_submit, raw, ignore)
+    if is_pnpm_monorepo(app) and any(runtime_policy(expo, platform)[0] == {"policy": "fingerprint"} or runtime_policy(expo, platform)[0] == "fingerprint" for platform in platforms):
+        warnings.append("pnpm monorepo with a fingerprint runtime: pnpm's virtual-store paths are part of the fingerprint, so a dependency change in another workspace package can move the runtime. Publish updates through `maggie mobile ota-guard --runtimes FILE` and set an explicit runtimeVersion (plus a native-change check) at the next native build")
+        facts["pnpmMonorepo"] = True
     return {
         "schemaVersion": SCHEMA,
         "appDir": str(app.relative_to(project)) if app.is_relative_to(project) else ".",
@@ -304,10 +317,70 @@ def ota(app: Path, build_ref: str, build_id: str, channel: str, environment: str
         report["steps"] = steps
 
 
+def is_pnpm_monorepo(app: Path) -> bool:
+    for folder in (app, *app.parents):
+        if (folder / "pnpm-workspace.yaml").is_file():
+            return True
+        if (folder / ".git").exists():
+            break
+    return False
+
+
+def load_runtimes(path: Path, platform: str) -> list[dict]:
+    """`maggie-mobile-runtimes.v1` ({"ios": [{"build", "eas_build_id", "runtime"}], "android": [...]})."""
+    data = _load(path)
+    builds = data.get(platform) or []
+    if not isinstance(builds, list) or not all(isinstance(item, dict) and item.get("runtime") for item in builds):
+        raise ValueError(f"{path} has no `{platform}` list of {{build, runtime}} entries")
+    return builds
+
+
+def fingerprint_command(platform: str) -> list[str]:
+    return shlex.split(os.environ.get("MAGGIE_MOBILE_FINGERPRINT", f"npx expo-updates fingerprint:generate --platform {platform}"))
+
+
+def ota_guard(app: Path, runtimes: Path, platform: str, runtime: str | None, publish: bool, channel: str | None, environment: str, message: str | None, confirm: bool) -> dict:
+    builds = load_runtimes(runtimes, platform)
+    report: dict = {"schemaVersion": "maggie-mobile-ota-guard.v1", "platform": platform, "installedBuilds": [{"build": item.get("build"), "runtime": item["runtime"]} for item in builds], "executed": False}
+    if not runtime:
+        result = subprocess.run(fingerprint_command(platform), cwd=app, capture_output=True, text=True, check=False)
+        try:
+            runtime = str(json.loads(result.stdout[result.stdout.find("{"):])["hash"]) if result.returncode == 0 else None
+        except (ValueError, KeyError):
+            runtime = None
+        if not runtime:
+            return {**report, "status": "failed", "reason": "could not compute the fingerprint (expo-updates fingerprint:generate)"}
+    report["runtime"] = runtime
+    match = next((item for item in builds if item["runtime"] == runtime), None)
+    if not match:
+        report.update(status="failed", reason=f"no installed build has runtime {runtime}; an update published now would reach nobody",
+                      fix=["the change needs a native build (new native module, permission, native config): build, then add its runtime to the runtimes file",
+                           "or only install paths moved (a dependency change elsewhere in the monorepo): publish from a temporary worktree with the build's lockfile and workspace file, after a frozen install, and confirm the fingerprint equals the build's runtime",
+                           "next native build: set an explicit runtimeVersion and keep a native-change check, so unrelated workspace changes cannot move it"])
+        return report
+    report["matchedBuild"] = match.get("build")
+    if not publish:
+        return {**report, "status": "passed"}
+    if not (channel and message):
+        raise ValueError("--publish needs an EAS Update channel on the profile and --message")
+    update = eas_command() + ["update", "--channel", channel, "--environment", environment, "--platform", platform, "--message", message, "--non-interactive"]
+    report["command"] = shlex.join(update)
+    if not confirm:
+        return {**report, "status": "dry-run", "note": "runtime matches; re-run with --confirm to publish"}
+    result = subprocess.run(update, cwd=app, capture_output=True, text=True, check=False)
+    published = re.search(r"Runtime version\s+([0-9a-f]{8,})", result.stdout or "")
+    report.update(executed=True, publishedRuntime=published.group(1) if published else None)
+    if result.returncode:
+        return {**report, "status": "failed", "reason": "eas update failed; see its output"}
+    if not published or published.group(1) != runtime:
+        return {**report, "status": "failed", "reason": "the published runtime differs from the checked one; check `eas update:list`"}
+    return {**report, "status": "published"}
+
+
 def main(argv: list[str] | None = None) -> int:
     parser = argparse.ArgumentParser(prog="maggie mobile", description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
     sub = parser.add_subparsers(dest="command", required=True)
-    for name in ("preflight", "plan", "ota"):
+    for name in ("preflight", "plan", "ota", "ota-guard"):
         command = sub.add_parser(name)
         command.add_argument("--project", type=Path, default=Path("."))
         command.add_argument("--app-dir", type=Path, help="Expo app folder inside a monorepo, e.g. apps/app")
@@ -319,6 +392,12 @@ def main(argv: list[str] | None = None) -> int:
         command.add_argument("--output", type=Path)
         if name in {"plan", "ota"}:
             command.add_argument("--build-ref", help="git commit or tag the installed store build was made from")
+        if name == "ota-guard":
+            command.add_argument("--runtimes", type=Path, required=True, help="maggie-mobile-runtimes.v1 JSON: installed builds' runtimes per platform")
+            command.add_argument("--runtime", help="use this runtime instead of computing the fingerprint")
+            command.add_argument("--publish", action="store_true", help="publish the update after a match")
+            command.add_argument("--message")
+            command.add_argument("--confirm", action="store_true")
         if name == "ota":
             command.add_argument("--build-id", required=True, help="EAS build id of the installed build (for fingerprint:compare)")
             command.add_argument("--message", required=True)
@@ -341,6 +420,10 @@ def main(argv: list[str] | None = None) -> int:
             report = {"schemaVersion": "maggie-mobile-release-plan.v1", "preflight": {key: report[key] for key in ("status", "errors", "warnings")}, "commands": plan_commands(args.profile, platforms, args.auto_submit, channel, args.environment, args.build_ref, drift), "costNotice": report["costNotice"], "executed": False}
             if drift is not None:
                 report["buildConfig"] = [{"file": item["file"], "differsFromBuild": item["differs"]} for item in drift]
+        elif args.command == "ota-guard":
+            if args.platform == "all":
+                raise ValueError("--platform ios or android: runtimes differ per platform")
+            report = ota_guard(app, (project / args.runtimes) if not args.runtimes.is_absolute() else args.runtimes, args.platform, args.runtime, args.publish, channel, environment, args.message, args.confirm)
         elif args.command == "ota":
             if report["status"] == "failed":
                 raise ValueError("preflight failed: " + "; ".join(report["errors"]))

package/bundled-tools/clis/maggie_ops.py

@@ -335,6 +335,8 @@ def main() -> int:
     favicon.add_argument("--declared-url")
     favicon.add_argument("--timeout", type=int, default=15)
     favicon.set_defaults(func=command_favicon_check)
+    from maggie_ops_routines import add_parsers as add_routine_parsers
+    add_routine_parsers(sub)
     record = sub.add_parser("record", help="record an explicitly authorised operation")
     record.add_argument("operation", choices=("sync", "sitemap-match", "rewrite-queue", "rewrite-approve", "publish", "migration"))
     record.add_argument("--dry-run", action="store_true")