@topy-ai/maggie 0.7.51 → 0.7.53

package/bundled-tools/clis/maggie_design_lint.py

@@ -7,11 +7,21 @@ pressable in JSX/TSX. React Native Web renders ``Pressable`` and the
 remove control becomes ``<button>`` inside ``<button>``: invalid DOM, and taps
 land on the wrong control.
 
-``layer-check`` flags unlayered CSS that competes with Tailwind v4 utilities.
+``layer-check`` flags unlayered CSS that competes with Tailwind v4 utilities,
+and warns about ``width: max-content`` (or ``w-max``) strips that can push a
+390 px page sideways. ``textinput-check`` flags React Native Web multiline
+inputs without a height and grow-only auto-grow.
 Tailwind v4 emits utilities inside ``@layer utilities``; any unlayered rule
 wins over every layer regardless of specificity, so an unlayered
 ``h1 { font-family }`` beats ``font-*`` and ``.ph { display: inline-block }``
 beats ``hidden`` and ``group-open:inline``.
+
+``safe-area-check`` flags ``<SafeAreaView>`` used as the inset source inside an
+Expo Router modal route (``presentation: "transparentModal"``, ``"modal"``,
+``"fullScreenModal"``, ...) or a React Native ``<Modal>``. On iOS those
+surfaces can measure a 0 top inset, so the header and Close button sit under
+the notch or Dynamic Island; web screenshots cannot show it. Read insets with
+``useSafeAreaInsets()`` from the root ``SafeAreaProvider`` instead.
 """
 
 from __future__ import annotations
@@ -232,12 +242,41 @@ def _rule_findings(source: str, start: int, end: int, layered: bool, display: st
         index = close + 1
 
 
+MAX_CONTENT_RULE = re.compile(r"([^{}]+)\{([^{}]*\b(?:min-)?width\s*:\s*max-content[^{}]*)\}", re.I)
+MAX_CONTENT_CLASS = re.compile(r"class(?:Name)?\s*=\s*[\"'`{]([^\"'`}]*\bw-max\b[^\"'`}]*)", re.I)
+OVERFLOW_GUARD = re.compile(r"\b(?:max-width|overflow(?:-x)?)\s*:", re.I)
+
+
+def overflow_findings(project: Path, css_sources: dict[Path, str], markup: list[Path]) -> list[dict[str, object]]:
+    """width: max-content on a tab strip or toolbar makes a phone page scroll sideways unless it can shrink or scroll."""
+    findings: list[dict[str, object]] = []
+    for path, source in css_sources.items():
+        for match in MAX_CONTENT_RULE.finditer(source):
+            body = match.group(2)
+            if OVERFLOW_GUARD.search(body):
+                continue
+            selector = " ".join(match.group(1).split())[-80:]
+            findings.append({"file": _display(path, project), "line": source.count("\n", 0, match.start(2)) + 1, "selector": selector, "kind": "max-content", "severity": "warning",
+                             "message": "width: max-content without max-width/overflow can push a 390 px page sideways; give the strip overflow-x: auto inside a min-width: 0 parent, or max-width: 100%"})
+    for path in markup:
+        source = path.read_text(encoding="utf-8", errors="replace")
+        for match in MAX_CONTENT_CLASS.finditer(source):
+            classes = match.group(1)
+            if re.search(r"\b(?:overflow-x-auto|overflow-auto|overflow-x-scroll|max-w-[\w\[\]%-]+)\b", classes):
+                continue
+            findings.append({"file": _display(path, project), "line": source.count("\n", 0, match.start()) + 1, "selector": classes.strip()[:80], "kind": "max-content", "severity": "warning",
+                             "message": "w-max without overflow-x-auto or a max-w-* can make the page scroll sideways at 390 px"})
+    return findings
+
+
 def layer_check(project: Path, paths: list[Path], force_v4: bool) -> dict[str, object]:
     files = iter_files(paths or [project], (".css", ".pcss", ".postcss"))
     sources = {path.resolve(): _strip_css_comments(path.read_text(encoding="utf-8", errors="replace")) for path in files}
+    markup = iter_files(paths or [project], (".tsx", ".jsx", ".astro", ".vue", ".svelte", ".html"))
+    overflow = overflow_findings(project, sources, markup)
     tailwind_v4 = force_v4 or any(TAILWIND_V4_IMPORT.search(source) for source in sources.values())
     if not tailwind_v4:
-        return {"schemaVersion": "maggie-design-layer-check.v1", "passed": True, "status": "skipped", "reason": "no Tailwind v4 entry (@import \"tailwindcss\") found", "checkedFiles": len(files), "findings": []}
+        return {"schemaVersion": "maggie-design-layer-check.v1", "passed": True, "status": "skipped", "reason": "no Tailwind v4 entry (@import \"tailwindcss\") found", "checkedFiles": len(files), "findings": overflow, "warnings": len(overflow)}
     layered_files: set[Path] = set()
     for path, source in sources.items():
         for target in LAYERED_IMPORT.findall(source):
@@ -245,10 +284,100 @@ def layer_check(project: Path, paths: list[Path], force_v4: bool) -> dict[str, o
     findings: list[dict[str, object]] = []
     for path, source in sources.items():
         _rule_findings(source, 0, len(source), path in layered_files, _display(path, project), findings)
+    findings += overflow
     errors = [item for item in findings if item["severity"] == "error"]
     return {"schemaVersion": "maggie-design-layer-check.v1", "passed": not errors, "status": "checked", "checkedFiles": len(files), "errors": len(errors), "warnings": len(findings) - len(errors), "findings": findings}
 
 
+MODAL_PRESENTATIONS = ("transparentModal", "containedTransparentModal", "modal", "containedModal", "fullScreenModal", "formSheet")
+SAFE_AREA_ALLOW = "maggie-allow-safe-area-view"
+SCREEN_TAG = re.compile(r"<(?:Stack|Tabs|Drawer)\.Screen\b(?:[^<>]|=>|\{[^{}]*(?:\{[^{}]*\}[^{}]*)*\})*?/?>", re.S)
+PRESENTATION = re.compile(r"presentation\s*:\s*[\"'](" + "|".join(MODAL_PRESENTATIONS) + r")[\"']")
+
+
+def _route_file(layout: Path, name: str) -> Path | None:
+    for candidate in (layout.parent / f"{name}.tsx", layout.parent / f"{name}.jsx", layout.parent / name / "index.tsx", layout.parent / name / "index.jsx"):
+        if candidate.is_file():
+            return candidate
+    return None
+
+
+def _line(source: str, index: int) -> int:
+    return source.count("\n", 0, index) + 1
+
+
+def safe_area_check(project: Path, paths: list[Path]) -> dict[str, object]:
+    project = project.resolve()
+    files = iter_files(paths or [project], (".tsx", ".jsx"))
+    modal_routes: dict[Path, str] = {}
+    for path in files:
+        source = _strip_jsx_comments(path.read_text(encoding="utf-8", errors="replace"))
+        for tag in SCREEN_TAG.finditer(source):
+            presentation = PRESENTATION.search(tag.group(0))
+            if not presentation:
+                continue
+            name = re.search(r"\bname\s*=\s*[\"']([^\"']+)[\"']", tag.group(0))
+            target = _route_file(path, name.group(1)) if name and path.stem == "_layout" else (path if not name else None)
+            if target:
+                modal_routes[target.resolve()] = presentation.group(1)
+    findings: list[dict[str, object]] = []
+    for path in files:
+        raw = path.read_text(encoding="utf-8", errors="replace")
+        if SAFE_AREA_ALLOW in raw or "SafeAreaView" not in raw:
+            continue
+        source = _strip_jsx_comments(raw)
+        display = _display(path, project)
+        presentation = modal_routes.get(path.resolve())
+        if presentation:
+            match = re.search(r"<SafeAreaView\b", source)
+            if match:
+                findings.append({"file": display, "line": _line(source, match.start()), "kind": "modal-route", "presentation": presentation, "message": f"route presented as {presentation} uses <SafeAreaView>; on iOS it can measure a 0 top inset, so pad with useSafeAreaInsets() instead"})
+                continue
+        if re.search(r"import\s*\{[^}]*\bModal\b[^}]*\}\s*from\s*[\"']react-native[\"']", source):
+            for modal in re.finditer(r"<Modal\b", source):
+                end = source.find("</Modal>", modal.end())
+                inner = source[modal.end(): end if end >= 0 else len(source)]
+                safe = re.search(r"<SafeAreaView\b", inner)
+                if safe:
+                    findings.append({"file": display, "line": _line(source, modal.end() + safe.start()), "kind": "rn-modal", "message": "<SafeAreaView> inside a React Native <Modal> can report a 0 top inset on iOS; use useSafeAreaInsets() padding"})
+    return {"schemaVersion": "maggie-design-safe-area-check.v1", "passed": not findings, "checkedFiles": len(files), "modalRoutes": sorted(_display(path, project) for path in modal_routes), "findings": findings,
+            "recommendation": "Wrap the app once in SafeAreaProvider; in modals read const insets = useSafeAreaInsets() and pad the header/footer. Verify on a notched iPhone (or simulator) — web screenshots cannot show the inset."}
+
+
+TEXTINPUT_TAG = re.compile(r"<TextInput\b(?:[^<>]|=>|\{[^{}]*(?:\{[^{}]*(?:\{[^{}]*\}[^{}]*)*\}[^{}]*)*\})*?/?>", re.S)
+TEXTINPUT_ALLOW = "maggie-allow-textinput"
+
+
+def textinput_check(project: Path, paths: list[Path]) -> dict[str, object]:
+    """React Native Web renders a multiline TextInput as a 2-row textarea; flag inputs without a height and grow-only auto-grow."""
+    project = project.resolve()
+    files = iter_files(paths or [project], (".tsx", ".jsx"))
+    findings: list[dict[str, object]] = []
+    for path in files:
+        raw = path.read_text(encoding="utf-8", errors="replace")
+        if "TextInput" not in raw or TEXTINPUT_ALLOW in raw:
+            continue
+        source = _strip_jsx_comments(raw)
+        display = _display(path, project)
+        for tag in TEXTINPUT_TAG.finditer(source):
+            text = tag.group(0)
+            if not re.search(r"\bmultiline\b(?!\s*=\s*\{\s*false\s*\})", text):
+                continue
+            line = _line(source, tag.start())
+            sized = re.search(r"\bnumberOfLines\s*=|\brows\s*=|\b(?:height|minHeight)\s*:", text)
+            style_ref = re.search(r"\bstyle\s*=\s*\{\s*(?:\[)?\s*(?:styles|s)\.(\w+)", text)
+            if not sized and style_ref and re.search(rf"\b{style_ref.group(1)}\s*:\s*\{{[^{{}}]*\b(?:height|minHeight)\s*:", source):
+                sized = True
+            if not sized:
+                findings.append({"file": display, "line": line, "kind": "multiline-without-height", "severity": "error",
+                                 "message": "multiline TextInput without numberOfLines or an explicit height renders a 2-row textarea on web (placeholder high, buttons misaligned); set one line of height and grow by measuring"})
+            if "onContentSizeChange" in text and "scrollHeight" not in source:
+                findings.append({"file": display, "line": line, "kind": "grow-only-autogrow", "severity": "warning",
+                                 "message": "onContentSizeChange never reports a smaller size on web, so this composer grows but never shrinks; on web collapse to the minimum, read scrollHeight, then set the height"})
+    errors = [item for item in findings if item["severity"] == "error"]
+    return {"schemaVersion": "maggie-design-textinput-check.v1", "passed": not errors, "checkedFiles": len(files), "findings": findings}
+
+
 def main(argv: list[str] | None = None) -> int:
     parser = argparse.ArgumentParser(prog="maggie design", description="Static design checks that run before browser QA.")
     sub = parser.add_subparsers(dest="command", required=True)
@@ -260,9 +389,19 @@ def main(argv: list[str] | None = None) -> int:
     layers.add_argument("--project", type=Path, default=Path.cwd())
     layers.add_argument("--css", type=Path, action="append", default=[], help="CSS file or directory to scan; defaults to the project")
     layers.add_argument("--tailwind-v4", action="store_true", help="check even when no @import \"tailwindcss\" entry is found")
+    safe = sub.add_parser("safe-area-check", help="flag SafeAreaView inside Expo Router modal routes and React Native Modal (.tsx/.jsx)")
+    safe.add_argument("--project", type=Path, default=Path.cwd())
+    safe.add_argument("--path", type=Path, action="append", default=[], help="file or directory to scan; defaults to the project")
+    textinput = sub.add_parser("textinput-check", help="flag multiline TextInput without a height and grow-only auto-grow on React Native Web (.tsx/.jsx)")
+    textinput.add_argument("--project", type=Path, default=Path.cwd())
+    textinput.add_argument("--path", type=Path, action="append", default=[], help="file or directory to scan; defaults to the project")
     args = parser.parse_args(argv)
     try:
-        if args.command == "pressable-check":
+        if args.command == "textinput-check":
+            report = textinput_check(args.project, args.path)
+        elif args.command == "safe-area-check":
+            report = safe_area_check(args.project, args.path)
+        elif args.command == "pressable-check":
             report = pressable_check(args.project, args.path, args.pressable)
         else:
             report = layer_check(args.project, args.css, args.tailwind_v4)

package/bundled-tools/clis/maggie_feedback.py

@@ -459,6 +459,12 @@ def collect_batch(args: argparse.Namespace) -> int:
     return 0
 
 
+AREA_SUBJECT_RE = re.compile(r"^([A-Za-z][A-Za-z0-9 /&._-]{0,30}):\s+(\S.*)$")
+SCOPE_RE = re.compile(r"^[a-z]+\(([^)]{1,40})\)!?:", re.IGNORECASE)
+SKILL_HINT_RE = re.compile(r"\b(?:maggie[\w-]*|skills?|cli|mcp|codex|claude)\b", re.IGNORECASE)
+SUMMARY_ITEM_CAP = 49
+
+
 def classify_subject(subject: str, include_all: bool) -> tuple[str, str] | None:
     """Return (type, text) for one commit subject, or ``None`` to skip it."""
     merge = MERGE_PR_RE.match(subject)
@@ -474,22 +480,58 @@ def classify_subject(subject: str, include_all: bool) -> tuple[str, str] | None:
         return "bug", subject
     if PLAIN_FEATURE_RE.search(subject):
         return "improvement", subject
+    # "Area: sentence" is how many product teams describe a change; it is a
+    # change in that area even when the sentence has no recognised verb.
+    if AREA_SUBJECT_RE.match(subject):
+        return "improvement", subject
     return ("general", subject) if include_all else None
 
 
-def _summary_repos(values: list[str]) -> list[tuple[str, Path]]:
-    """Parse ``--repo [LABEL=]PATH`` values; unlabeled repositories become repo1, repo2, ..."""
+def subject_scope(subject: str) -> str:
+    """The conventional-commit scope or ``Area:`` prefix of a subject, lower-cased; ``""`` when absent."""
+    match = SCOPE_RE.match(subject)
+    if match:
+        return match.group(1).strip().lower()
+    if FIX_SUBJECT_RE.match(subject) or FEATURE_SUBJECT_RE.match(subject) or CHORE_SUBJECT_RE.match(subject):
+        return ""
+    area = AREA_SUBJECT_RE.match(subject)
+    return area.group(1).strip().lower() if area else ""
+
+
+def _summary_repos(values: list[str], default_rev: str = "") -> list[tuple[str, Path, str]]:
+    """Parse ``--repo [LABEL=]PATH[@REV]`` values; unlabeled repositories become repo1, repo2, ..."""
     repos = []
     for index, value in enumerate(values or ["."], start=1):
         label, sep, path = value.partition("=")
         if not sep or not re.fullmatch(r"[A-Za-z0-9][A-Za-z0-9._-]{0,40}", label):
             label, path = f"repo{index}", value
-        repos.append((label, Path(path).expanduser().resolve()))
-    if len({label for label, _ in repos}) != len(repos):
+        rev = default_rev
+        head, at, tail = path.rpartition("@")
+        if at and head and not Path(path).expanduser().exists():
+            path, rev = head, tail
+        if rev and (rev.startswith("-") or not re.fullmatch(r"[A-Za-z0-9._/@{}~^:-]{1,200}", rev)):
+            raise ValueError("revision must be a branch, tag or commit such as origin/main")
+        repos.append((label, Path(path).expanduser().resolve(), rev or "HEAD"))
+    if len({label for label, _, _ in repos}) != len(repos):
         raise ValueError("--repo labels must be unique")
     return repos
 
 
+def _behind_upstream(repo: Path, rev: str) -> tuple[str, int] | None:
+    """When reading HEAD, report (upstream, commits HEAD lacks) from local refs; never fetches."""
+    if rev != "HEAD":
+        return None
+    upstream = subprocess.run(["git", "-C", str(repo), "rev-parse", "--abbrev-ref", "--symbolic-full-name", "@{u}"], capture_output=True, text=True, check=False)
+    if upstream.returncode or not upstream.stdout.strip():
+        return None
+    count = subprocess.run(["git", "-C", str(repo), "rev-list", "--count", "HEAD..@{u}"], capture_output=True, text=True, check=False)
+    try:
+        behind = int(count.stdout.strip() or 0)
+    except ValueError:
+        return None
+    return (upstream.stdout.strip(), behind) if behind else None
+
+
 def session_summary(args: argparse.Namespace) -> int:
     """Draft a reviewable batch file from commit subjects; nothing is collected or submitted."""
     since = str(args.since or "").strip()
@@ -503,32 +545,53 @@ def session_summary(args: argparse.Namespace) -> int:
     batch_id = safe_text(args.batch_id) or f"session-{datetime.now(timezone.utc).strftime('%Y%m%d-%H%M%S')}"
     if not SAFE_BATCH_ID_RE.fullmatch(batch_id):
         raise ValueError("batch ID is invalid")
-    repos = _summary_repos(args.repo)
+    repos = _summary_repos(args.repo, str(getattr(args, "rev", "") or "").strip())
     include_all = bool(getattr(args, "all", False))
-    items = []
+    skill_relevant = bool(getattr(args, "skill_relevant", False))
+    skill_hint = safe_text(args.skill).lower().removeprefix("maggie-")
+    candidates = []
     skipped = 0
+    project_commits = 0
+    seen = 0
     per_repo = {}
-    for label, repo in repos:
+    warnings = []
+    for label, repo, rev in repos:
         command = ["git", "-C", str(repo), "log", "--format=%h%x1f%s"]
         if not getattr(args, "merges", False):
             command.append("--no-merges")
-        command += [f"--since={since_date}", "HEAD"] if since_date else [f"{since}..HEAD"]
+        command += [f"--since={since_date}", rev] if since_date else [f"{since}..{rev}"]
         completed = subprocess.run(command, capture_output=True, text=True, check=False)
         if completed.returncode:
-            raise ValueError(f"git log failed for {label}; check --repo and --since")
+            raise ValueError(f"git log failed for {label}; check --repo, --rev and --since")
+        lag = _behind_upstream(repo, rev)
+        if lag:
+            warnings.append(f"{label}: local HEAD is {lag[1]} commit(s) behind {lag[0]}; commits pushed from worktrees are missing. Re-run with --repo {label}=PATH@{lag[0]} (git fetch first).")
         counted = 0
         for line in completed.stdout.splitlines():
             sha, _, subject = line.partition("\x1f")
             subject = safe_text(subject)[:200]
             if not sha or not subject:
                 continue
+            seen += 1
             classified = classify_subject(subject, include_all)
             if classified is None:
                 skipped += 1
                 continue
+            scope = subject_scope(subject)
+            if skill_relevant and not (SKILL_HINT_RE.search(subject) or (skill_hint and skill_hint in subject.lower())):
+                project_commits += 1
+                continue
             kind, text = classified
             text = text[:1].upper() + text[1:] if text else subject
             commit = f"{label}@{sha}" if len(repos) > 1 else sha
+            candidates.append({"kind": kind, "text": text, "commit": commit, "scope": scope or label})
+            counted += 1
+        per_repo[label] = counted
+    grouped = len(candidates) > SUMMARY_ITEM_CAP
+    items = []
+    if not grouped:
+        for candidate in candidates:
+            commit, text, kind = candidate["commit"], candidate["text"], candidate["kind"]
             item = {
                 "type": kind,
                 "summary": text,
@@ -540,10 +603,24 @@ def session_summary(args: argparse.Namespace) -> int:
             if kind in {"bug", "improvement"}:
                 item.update({"fixed": True, "resolution": text})
             items.append(item)
-            counted += 1
-            if len(items) >= 49:
-                break
-        per_repo[label] = counted
+    else:
+        # Too many commits for one batch: one item per scope, so nothing is dropped silently.
+        scopes: dict[str, list[dict]] = {}
+        for candidate in candidates:
+            scopes.setdefault(candidate["scope"], []).append(candidate)
+        ordered = sorted(scopes.items(), key=lambda pair: (-len(pair[1]), pair[0]))
+        for scope, entries in ordered[:SUMMARY_ITEM_CAP]:
+            bugs = sum(1 for entry in entries if entry["kind"] == "bug")
+            items.append({
+                "type": "bug" if bugs * 2 > len(entries) else "improvement",
+                "summary": f"{scope}: {len(entries)} commit(s) ({bugs} fix) — keep only if a Maggie skill or CLI fell short",
+                "expected": f"{REVIEW_MARKER} what the skill or CLI should have done",
+                "actual": f"{REVIEW_MARKER} summarise the {scope} commits that came from a skill gap",
+                "validation": f"{REVIEW_MARKER} the test or check that verified the {scope} commits",
+                "evidence": [f"commit:{entry['commit']}" for entry in entries[:20]],
+            })
+        if len(ordered) > SUMMARY_ITEM_CAP:
+            warnings.append(f"{len(ordered) - SUMMARY_ITEM_CAP} scope(s) did not fit in one batch; narrow --since-date or use --skill-relevant.")
     items.append({
         "type": "feature",
         "summary": f"{REVIEW_MARKER} describe an open ask from this session, or delete this item",
@@ -557,6 +634,7 @@ def session_summary(args: argparse.Namespace) -> int:
         "phase": safe_text(args.phase) or "session-summary",
         "reviewRequired": True,
         "note": "Draft only. Remove items unrelated to Maggie skills or CLIs, replace every REVIEW: and delete the open-ask placeholder if unused. `maggie feedback batch` rejects unedited REVIEW: fields.",
+        "commits": {"seen": seen, "drafted": len(candidates), "skipped": skipped, "projectOnly": project_commits, "groupedByScope": grouped},
         "items": items,
     }
     project = Path(args.project).resolve()
@@ -567,7 +645,9 @@ def session_summary(args: argparse.Namespace) -> int:
         raise ValueError("output already exists; choose another --output or --batch-id")
     output.parent.mkdir(parents=True, exist_ok=True)
     output.write_text(json.dumps(manifest, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
-    print(json.dumps({"status": "draft-written", "batchId": batch_id, "items": len(items), "skippedCommits": skipped, "repositories": per_repo, "output": str(output), "submitted": False}, ensure_ascii=False))
+    if grouped:
+        warnings.append(f"{len(candidates)} commits exceed the {SUMMARY_ITEM_CAP}-item batch limit, so they were grouped into one item per scope.")
+    print(json.dumps({"status": "draft-written", "batchId": batch_id, "items": len(items), "commitsSeen": seen, "draftedCommits": len(candidates), "skippedCommits": skipped, "projectOnlyCommits": project_commits, "groupedByScope": grouped, "repositories": per_repo, "warnings": warnings, "output": str(output), "submitted": False}, ensure_ascii=False))
     return 0
 
 
@@ -716,7 +796,9 @@ def main() -> int:
     summary_parser.add_argument("--project", default=argparse.SUPPRESS)
     summary_parser.add_argument("--since", default="", help="git revision; commits after it are summarized")
     summary_parser.add_argument("--since-date", default="", help="ISO date/time; use across several repositories")
-    summary_parser.add_argument("--repo", action="append", default=[], help="[LABEL=]PATH of a git repository; repeat for app, backend, edge (default: current directory)")
+    summary_parser.add_argument("--repo", action="append", default=[], help="[LABEL=]PATH[@REV] of a git repository; repeat for app, backend, edge (default: current directory at HEAD)")
+    summary_parser.add_argument("--rev", default="", help="revision to read in every repository without its own @REV, e.g. origin/main")
+    summary_parser.add_argument("--skill-relevant", action="store_true", help="keep only commits that mention Maggie, a skill, a CLI or MCP (or the --skill name); count the rest as project-only")
     summary_parser.add_argument("--all", action="store_true", help="also draft unclassified and chore subjects as general items")
     summary_parser.add_argument("--merges", action="store_true", help="include merge commits (PR branch names are classified)")
     summary_parser.add_argument("--batch-id", default="")

package/bundled-tools/clis/maggie_mobile.py

@@ -20,19 +20,32 @@ 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.
 """
 
 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"}
 
 
@@ -68,7 +81,7 @@ def runtime_policy(expo: dict, platform: str) -> tuple[object, str]:
     return expo.get("runtimeVersion"), "expo.runtimeVersion"
 
 
-def check_profile(expo: dict, eas: dict, package: dict, profile: str, platforms: list[str], auto_submit: bool, raw_app_json: str | None) -> tuple[list[str], list[str], dict]:
+def check_profile(expo: dict, eas: dict, package: dict, profile: str, platforms: list[str], auto_submit: bool, raw_app_json: str | None, app_dir_ignore_text: str = "") -> tuple[list[str], list[str], dict]:
     errors: list[str] = []
     warnings: list[str] = []
     facts: dict = {"profile": profile, "platforms": platforms}
@@ -140,6 +153,17 @@ def check_profile(expo: dict, eas: dict, package: dict, profile: str, platforms:
                 warnings.append(f"android: submit.{profile}.android.serviceAccountKeyPath is not set; provide it or EXPO_ANDROID_SERVICE_ACCOUNT_KEY_PATH, and keep the key file out of git")
             if android.get("track", "internal") not in {"internal", "alpha", "beta", "production"}:
                 errors.append("android: submit track must be internal, alpha, beta or production")
+    for script_name, command in (package.get("scripts", {}) or {}).items():
+        text = str(command)
+        if re.search(r"\beas(?:-cli)?\s+update\b(?!:)", text):
+            if "--non-interactive" in text and "--environment" not in text:
+                errors.append(f"package.json script {script_name!r} runs `eas update --non-interactive` without --environment; EAS refuses it ('The --environment flag must be set'). Add --environment matching the channel")
+            if "fingerprint:compare" not in text and uses_updates:
+                warnings.append(f"package.json script {script_name!r} publishes an update without `eas fingerprint:compare --build-id <build>`; a fingerprint mismatch sends the update to a runtime no installed build has")
+    if uses_updates and any(isinstance(runtime_policy(expo, p)[0], dict) and runtime_policy(expo, p)[0].get("policy") == "fingerprint" for p in platforms):
+        ignore = app_dir_ignore_text
+        if "eas.json" not in ignore.split():
+            warnings.append("runtime policy fingerprint includes eas.json: editing eas.json after a build (for example adding ascAppId) changes the fingerprint and silently stops OTA updates reaching that build. Add eas.json to .fingerprintignore with the next native build, and run `eas fingerprint:compare --build-id <build>` before every update")
     if raw_app_json and "\t" in raw_app_json:
         warnings.append("app.json is tab-indented; `eas update:configure` rewrites it with spaces (a large diff) — prefer editing runtimeVersion and updates by hand")
     return errors, warnings, facts
@@ -154,7 +178,8 @@ def preflight(project: Path, app_dir: Path | None, config_json: Path | None, pro
         raise ValueError("eas.json not found; run `npx eas-cli build:configure` once, then review the file")
     eas = _load(eas_path)
     package = _load(app / "package.json") if (app / "package.json").is_file() else {}
-    errors, warnings, facts = check_profile(expo, eas, package, profile, platforms, auto_submit, raw)
+    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)
     return {
         "schemaVersion": SCHEMA,
         "appDir": str(app.relative_to(project)) if app.is_relative_to(project) else ".",
@@ -173,7 +198,34 @@ 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) -> 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}]
     build = f"npx eas-cli build -p {platform_arg} --profile {profile} --non-interactive" + (" --auto-submit" if auto_submit else "")
@@ -181,16 +233,81 @@ 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:
-        environment = f" --environment {profile}" if profile in {"development", "preview", "production"} else ""
-        commands.append({"step": "ota-update", "command": f"npx eas-cli update --channel {channel}{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)"})
+        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 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"):
         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")
@@ -198,7 +315,14 @@ def main(argv: list[str] | None = None) -> int:
         command.add_argument("--profile", default="production")
         command.add_argument("--platform", choices=("ios", "android", "all"), default="all")
         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":
+            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:
@@ -206,14 +330,36 @@ 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), "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":
+            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