@topy-ai/maggie 0.7.52 → 0.7.54

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

@@ -20,19 +20,42 @@ fails. It checks, per build profile and platform:
 
 ``plan`` prints the build / submit / update commands with a cost notice and
 never runs them. Nothing is uploaded and no credentials are read.
+
+An OTA update must be fingerprinted with the config files the store build was
+made from: ``eas.json`` and ``package.json`` usually changed since. ``plan
+--build-ref <git ref>`` adds the swap steps, and ``ota --build-ref REF
+--build-id ID`` performs them: put the build commit's copies in place, run
+``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
 
 import argparse
+import hashlib
 import json
+import os
 import re
+import shlex
+import subprocess
 import sys
 from datetime import datetime, timezone
 from pathlib import Path
 
 SCHEMA = "maggie-mobile-release-preflight.v1"
 PLATFORMS = ("ios", "android")
+BUILD_CONFIG_FILES = ("eas.json", "package.json")
 VERSION_POLICIES = {"appVersion", "nativeVersion", "sdkVersion"}
 
 
@@ -167,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 ".",
@@ -185,7 +211,33 @@ def cost_notice(platforms: list[str], profile: str) -> str:
             "build minutes even if a later step fails. EAS Update publishes are counted against monthly update users. Confirm before running.")
 
 
-def plan_commands(profile: str, platforms: list[str], auto_submit: bool, channel: str | None, environment: str | None = None) -> list[dict]:
+def git_root(path: Path) -> Path:
+    completed = subprocess.run(["git", "-C", str(path), "rev-parse", "--show-toplevel"], capture_output=True, text=True, check=False)
+    if completed.returncode:
+        raise ValueError("the app folder is not inside a git repository; --build-ref needs git")
+    return Path(completed.stdout.strip()).resolve()
+
+
+def build_config_drift(app: Path, build_ref: str) -> list[dict]:
+    """Config files whose working copy differs from the build commit's copy (git object paths, never contents)."""
+    if build_ref.startswith("-") or not re.fullmatch(r"[A-Za-z0-9._/@{}~^:-]{1,200}", build_ref):
+        raise ValueError("--build-ref must be a git revision such as a tag or commit")
+    root = git_root(app)
+    files = []
+    for name in BUILD_CONFIG_FILES:
+        path = app / name
+        rel = path.resolve().relative_to(root).as_posix()
+        shown = subprocess.run(["git", "-C", str(root), "show", f"{build_ref}:{rel}"], capture_output=True, check=False)
+        if shown.returncode:
+            if name == "eas.json":
+                raise ValueError(f"{rel} does not exist at {build_ref}; is that the commit the store build was made from?")
+            continue
+        current = path.read_bytes() if path.is_file() else b""
+        files.append({"file": rel, "differs": current != shown.stdout, "buildBytes": shown.stdout, "workingSha256": hashlib.sha256(current).hexdigest()})
+    return files
+
+
+def plan_commands(profile: str, platforms: list[str], auto_submit: bool, channel: str | None, environment: str | None = None, build_ref: str | None = None, drift: list[dict] | None = None) -> list[dict]:
     environment = environment or (profile if profile in {"development", "preview", "production"} else "production")
     platform_arg = "all" if len(platforms) == 2 else platforms[0]
     commands = [{"step": "preflight", "command": f"maggie mobile preflight --profile {profile} --platform {platform_arg}" + (" --auto-submit" if auto_submit else ""), "spends": False}]
@@ -194,16 +246,141 @@ def plan_commands(profile: str, platforms: list[str], auto_submit: bool, channel
     if not auto_submit:
         for platform in platforms:
             commands.append({"step": f"submit-{platform}", "command": f"npx eas-cli submit -p {platform} --profile {profile} --latest --non-interactive", "spends": False})
+    swapped = [item["file"] for item in (drift or []) if item["differs"]]
+    if channel and build_ref:
+        commands.append({"step": "ota-from-build-config", "command": f"maggie mobile ota --profile {profile} --platform {platform_arg} --build-ref {build_ref} --build-id <installed build id> --message \"<what changed>\" --confirm", "spends": True,
+                         "note": ("swaps " + ", ".join(swapped) + f" for the copies at {build_ref}, runs fingerprint:compare and the update, then restores the working copies" if swapped else f"the config files match {build_ref}; no swap needed")})
+        return commands
     if channel:
         commands.append({"step": "fingerprint-gate", "command": "npx eas-cli fingerprint:compare --build-id <installed build id>", "spends": False, "note": "must report no difference; editing eas.json, native config or dependencies after the build changes the fingerprint and the update would reach no installed build"})
         commands.append({"step": "ota-update", "command": f"npx eas-cli update --channel {channel} --environment {environment} --platform {platform_arg} --message \"<what changed>\" --non-interactive", "spends": True, "note": "only JS/asset changes; a native change needs a new build (the fingerprint policy enforces this)"})
     return commands
 
 
+def eas_command() -> list[str]:
+    """The EAS CLI invocation; MAGGIE_MOBILE_EAS overrides it (tests, a pinned eas-cli)."""
+    return shlex.split(os.environ.get("MAGGIE_MOBILE_EAS", "npx eas-cli"))
+
+
+def fingerprint_hashes(stdout: str) -> tuple[str, str] | None:
+    """(build hash, project hash) from `eas fingerprint:compare --json`, or None when the output is not that."""
+    start = stdout.find("{")
+    try:
+        data = json.loads(stdout[start:]) if start >= 0 else {}
+        return str(data["fingerprint1"]["hash"]), str(data["fingerprint2"]["hash"])
+    except (ValueError, KeyError, TypeError):
+        return None
+
+
+def ota(app: Path, build_ref: str, build_id: str, channel: str, environment: str, platform_arg: str, message: str, confirm: bool) -> dict:
+    """Fingerprint and publish an update with the build's own config files; always restore the working copies."""
+    if not re.fullmatch(r"[A-Za-z0-9-]{8,64}", build_id):
+        raise ValueError("--build-id must be the EAS build id of the installed build")
+    if not message.strip():
+        raise ValueError("--message is required")
+    drift = build_config_drift(app, build_ref)
+    root = git_root(app)
+    # fingerprint:compare exits 0 even when the fingerprints differ; --json prints both, so compare the hashes.
+    compare = eas_command() + ["fingerprint:compare", "--build-id", build_id, "--json", "--non-interactive"]
+    update = eas_command() + ["update", "--channel", channel, "--environment", environment, "--platform", platform_arg, "--message", message, "--non-interactive"]
+    report = {"buildRef": build_ref, "swapped": [item["file"] for item in drift if item["differs"]], "commands": [shlex.join(compare), shlex.join(update)], "executed": False}
+    if not confirm:
+        report["status"] = "dry-run"
+        report["note"] = "nothing was changed; re-run with --confirm to swap, compare, publish and restore"
+        return report
+    originals = {item["file"]: (root / item["file"]).read_bytes() for item in drift if item["differs"]}
+    steps = []
+    try:
+        for item in drift:
+            if item["differs"]:
+                (root / item["file"]).write_bytes(item["buildBytes"])
+        result = subprocess.run(compare, cwd=app, capture_output=True, text=True, check=False)
+        hashes = fingerprint_hashes(result.stdout)
+        steps.append({"step": "fingerprint-compare", "exit": result.returncode, "match": bool(hashes) and hashes[0] == hashes[1]})
+        if result.returncode or not hashes:
+            report.update(status="failed", reason="fingerprint:compare did not return two fingerprints; nothing was published")
+            return report
+        if hashes[0] != hashes[1]:
+            report.update(status="failed", reason="the fingerprint with the build's config files does not match the installed build; this change needs a new native build")
+            return report
+        result = subprocess.run(update, cwd=app, capture_output=True, text=True, check=False)
+        steps.append({"step": "update", "exit": result.returncode})
+        report["executed"] = True
+        report["status"] = "published" if result.returncode == 0 else "failed"
+        if result.returncode:
+            report["reason"] = "eas update failed; see its output"
+        return report
+    finally:
+        for rel, data in originals.items():
+            (root / rel).write_bytes(data)
+        report["restored"] = {rel: hashlib.sha256((root / rel).read_bytes()).hexdigest() == hashlib.sha256(data).hexdigest() for rel, data in originals.items()}
+        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"):
+    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")
@@ -213,6 +390,18 @@ def main(argv: list[str] | None = None) -> int:
         command.add_argument("--auto-submit", action="store_true", help="the build will run with --auto-submit --non-interactive")
         command.add_argument("--environment", help="EAS environment for updates (default: the profile when it is development/preview/production)")
         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)
+            command.add_argument("--confirm", action="store_true", help="actually swap, compare, publish and restore; without it nothing changes")
     args = parser.parse_args(argv)
     platforms = list(PLATFORMS) if args.platform == "all" else [args.platform]
     try:
@@ -220,14 +409,40 @@ def main(argv: list[str] | None = None) -> int:
     except (OSError, ValueError) as error:
         print(f"BLOCKED: maggie mobile {args.command}: {error}", file=sys.stderr)
         return 2
-    if args.command == "plan":
-        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, report["facts"].get("channel") if report["facts"].get("easUpdate") else None, args.environment), "costNotice": report["costNotice"], "executed": False}
+    project = args.project.resolve()
+    app = (project / args.app_dir).resolve() if args.app_dir and not args.app_dir.is_absolute() else (args.app_dir.resolve() if args.app_dir else project)
+    channel = report["facts"].get("channel") if report["facts"].get("easUpdate") else None
+    environment = args.environment or (args.profile if args.profile in {"development", "preview", "production"} else "production")
+    platform_arg = "all" if len(platforms) == 2 else platforms[0]
+    try:
+        if args.command == "plan":
+            drift = build_config_drift(app, args.build_ref) if args.build_ref else None
+            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"]))
+            if not channel:
+                raise ValueError("the profile has no EAS Update channel")
+            if not args.build_ref:
+                raise ValueError("--build-ref is required: the commit the installed build was made from")
+            report = {"schemaVersion": "maggie-mobile-ota.v1", **ota(app, args.build_ref, args.build_id, channel, environment, platform_arg, args.message, args.confirm)}
+    except (OSError, ValueError) as error:
+        print(f"BLOCKED: maggie mobile {args.command}: {error}", file=sys.stderr)
+        return 2
     text = json.dumps(report, indent=2, ensure_ascii=False)
     if args.output:
         args.output.parent.mkdir(parents=True, exist_ok=True)
         args.output.write_text(text + "\n", encoding="utf-8")
     print(text)
     status = report["status"] if "status" in report else report["preflight"]["status"]
+    if report.get("restored") and not all(report["restored"].values()):
+        return 1
     return 1 if status == "failed" else 0
 
 

package/bundled-tools/clis/maggie_product_release.py

@@ -27,6 +27,7 @@ import json
 import re
 import shutil
 import subprocess
+import time
 import sys
 import tempfile
 from datetime import date, datetime, timezone
@@ -264,6 +265,44 @@ def review_status(reviews_path: Path, package_version: str | None, chatgpt_plugi
     return {"schemaVersion": "maggie-product-review-status.v1", "passed": not errors, "reviews": rows, "errors": errors, "warnings": warnings}
 
 
+STAGED_ERROR = re.compile(r"cannot publish over (?:the )?previously (?:staged|published) version", re.I)
+
+
+def npm_view(package: str, npm_bin: str) -> dict:
+    completed = subprocess.run([npm_bin, "view", package, "dist-tags", "versions", "--json"], capture_output=True, text=True, check=False, timeout=60)
+    if completed.returncode:
+        return {}
+    try:
+        value = json.loads(completed.stdout or "{}")
+    except json.JSONDecodeError:
+        return {}
+    return value if isinstance(value, dict) else {}
+
+
+def published(package: str, version: str, tag: str, wait: int, interval: float, publish_log: Path | None, view=None, sleep=time.sleep) -> dict:
+    """Wait until `version` is the registry's `tag` (latest). A staged publish can lag for minutes."""
+    npm_bin = shutil.which("npm") or "npm"
+    view = view or (lambda: npm_view(package, npm_bin))
+    log_says_staged = bool(publish_log and publish_log.is_file() and STAGED_ERROR.search(publish_log.read_text(encoding="utf-8", errors="replace")))
+    deadline = time.monotonic() + wait
+    checks = 0
+    while True:
+        checks += 1
+        data = view()
+        tags = data.get("dist-tags") or {}
+        versions = data.get("versions") or []
+        listed = version in (versions if isinstance(versions, list) else [versions])
+        current = tags.get(tag)
+        if current == version:
+            return {"passed": True, "package": package, "version": version, "tag": tag, "state": "live", "checks": checks,
+                    "note": "the earlier publish attempt was already accepted (staged), not a failure" if log_says_staged else None}
+        if time.monotonic() >= deadline:
+            state = "staged" if listed or log_says_staged else "missing"
+            return {"passed": False, "package": package, "version": version, "tag": tag, "state": state, "registryTag": current, "checks": checks,
+                    "note": "still propagating: check again before reporting it" if state == "staged" else "not on the registry: the publish did not happen"}
+        sleep(interval)
+
+
 def main(argv: list[str] | None = None) -> int:
     parser = argparse.ArgumentParser(prog="maggie product", description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
     sub = parser.add_subparsers(dest="command", required=True)
@@ -281,9 +320,18 @@ def main(argv: list[str] | None = None) -> int:
     review.add_argument("--reviews", type=Path, required=True, help="maggie-product-reviews.v1 JSON")
     review.add_argument("--package", type=Path)
     review.add_argument("--chatgpt-plugin", type=Path, help="ChatGPT app plugin.json with review.test_cases")
+    pub = sub.add_parser("published", help="wait until a just-published version is the registry's latest (staged publishes lag)")
+    pub.add_argument("--package-name", required=True)
+    pub.add_argument("--version", required=True)
+    pub.add_argument("--tag", default="latest")
+    pub.add_argument("--wait", type=int, default=600, help="seconds to keep checking (default 600)")
+    pub.add_argument("--interval", type=float, default=20)
+    pub.add_argument("--publish-log", type=Path, help="output of the publish command; 'Cannot publish over previously staged version' means it was already accepted")
     args = parser.parse_args(argv)
     try:
-        if args.command == "release-check":
+        if args.command == "published":
+            report = published(args.package_name, args.version, args.tag, args.wait, args.interval, args.publish_log)
+        elif args.command == "release-check":
             report = release_check(args.package.resolve(), args.server_json, args.changelog, args.pack)
         elif args.command == "smoke":
             report = smoke(args.package.resolve(), args.timeout)