@topy-ai/maggie 0.7.49 → 0.7.51

package/bundled-tools/clis/maggie_product_release.py

@@ -0,0 +1,303 @@
+#!/usr/bin/env python3
+"""Release checks for a product's own CLI and MCP packages (``maggie product``).
+
+Maggie's own release gates cover only ``@topy-ai/maggie``. These commands
+apply the same discipline to the CLIs and MCP servers a product ships:
+
+- ``release-check``: npm metadata (bin targets, ``files``, license,
+  repository/directory, engines, public access for scoped names, provenance),
+  version agreement with the changelog and an MCP registry ``server.json``
+  (``mcpName`` ↔ ``name``, versions, package identifier), and optionally the
+  packed file list (``--pack``: bins included, no ``.env``/keys/``.npmrc``);
+- ``smoke``: pack, install the tarball into an empty folder, run each binary
+  with ``--version``/``--help`` and require the package version;
+- ``mcp-check``: a remote MCP endpoint's OAuth protected-resource metadata
+  (RFC 9728) and its unauthenticated 401 challenge — read-only requests;
+- ``review-status``: third-party review states (ChatGPT app, Claude
+  directory, MCP registry, App Store, Google Play) from a tracked JSON file,
+  including ChatGPT app test cases.
+
+Nothing is published. Tokens are never read or printed.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import shutil
+import subprocess
+import sys
+import tempfile
+from datetime import date, datetime, timezone
+from pathlib import Path
+from urllib.error import HTTPError, URLError
+from urllib.parse import urlsplit
+from urllib.request import Request, urlopen
+
+SEMVER = re.compile(r"^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$")
+SECRET_FILES = re.compile(r"(?:^|/)(?:\.env(?:\..+)?|\.npmrc|id_rsa|.*\.pem|.*\.key|.*\.p8|.*\.p12|service-account.*\.json)$", re.I)
+REVIEW_SURFACES = ("chatgpt-app", "claude-directory", "mcp-registry", "app-store", "google-play", "npm")
+REVIEW_STATES = ("draft", "submitted", "in-review", "changes-requested", "approved", "rejected", "live")
+
+
+def _json(path: Path) -> dict:
+    value = json.loads(path.read_text(encoding="utf-8"))
+    if not isinstance(value, dict):
+        raise ValueError(f"{path.name} must be a JSON object")
+    return value
+
+
+def changelog_version(path: Path) -> str | None:
+    for line in path.read_text(encoding="utf-8").splitlines():
+        match = re.match(r"^#{1,3}\s*\[?v?(\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?)\]?", line)
+        if match:
+            return match.group(1)
+    return None
+
+
+def release_check(package_dir: Path, server_json: Path | None, changelog: Path | None, pack: bool) -> dict:
+    package_path = package_dir / "package.json"
+    if not package_path.is_file():
+        raise ValueError("package.json not found; pass --package <folder>")
+    package = _json(package_path)
+    errors: list[str] = []
+    warnings: list[str] = []
+    name, version = str(package.get("name", "")), str(package.get("version", ""))
+    if not re.fullmatch(r"(?:@[a-z0-9-~][a-z0-9-._~]*/)?[a-z0-9-~][a-z0-9-._~]*", name):
+        errors.append("package name is missing or invalid")
+    if not SEMVER.match(version):
+        errors.append("version is not semver")
+    if package.get("private") is True:
+        errors.append("package is private: true and cannot be published")
+    bins = package.get("bin", {})
+    if isinstance(bins, str):
+        bins = {name.split("/")[-1]: bins}
+    files = package.get("files")
+    if not isinstance(files, list) or not files:
+        warnings.append("no files whitelist; everything not in .npmignore is published")
+        files = None
+    for command, target in (bins or {}).items():
+        target_path = package_dir / str(target)
+        if not target_path.is_file():
+            warnings.append(f"bin {command} → {target} does not exist yet (build before publishing)")
+        elif not target_path.read_text(encoding="utf-8", errors="replace").startswith("#!"):
+            errors.append(f"bin {command} → {target} has no #! shebang; npx would not run it")
+        if files is not None and not any(str(target).lstrip("./").startswith(str(entry).rstrip("/").lstrip("./")) for entry in files):
+            errors.append(f"bin {command} → {target} is not covered by files")
+    if not package.get("license"):
+        errors.append("license is missing")
+    repository = package.get("repository")
+    if not repository:
+        warnings.append("repository is missing; npm provenance and the registry page link to it")
+    elif isinstance(repository, dict) and (package_dir / ".." / "..").resolve().joinpath("package.json").is_file() and not repository.get("directory"):
+        warnings.append("repository.directory is missing for a package inside a monorepo")
+    if not package.get("engines", {}).get("node"):
+        warnings.append("engines.node is missing")
+    if name.startswith("@") and package.get("publishConfig", {}).get("access") != "public":
+        errors.append("scoped package needs publishConfig.access public (or `npm publish --access public`)")
+    if not package.get("publishConfig", {}).get("provenance"):
+        warnings.append("publishConfig.provenance is not set; publish from CI with OIDC and --provenance so the registry shows where it was built")
+    if not (package_dir / "README.md").is_file():
+        errors.append("README.md is missing")
+    facts = {"name": name, "version": version, "bins": sorted(bins or {})}
+    if changelog:
+        top = changelog_version(changelog) if changelog.is_file() else None
+        facts["changelogVersion"] = top
+        if top != version:
+            errors.append(f"changelog top entry is {top}, package version is {version}")
+    mcp_name = package.get("mcpName")
+    if server_json:
+        server = _json(server_json)
+        facts["serverJson"] = {"name": server.get("name"), "version": server.get("version")}
+        if not mcp_name:
+            errors.append("package.json mcpName is required for the MCP registry to verify npm ownership")
+        elif server.get("name") != mcp_name:
+            errors.append(f"server.json name {server.get('name')!r} must equal package.json mcpName {mcp_name!r}")
+        if server.get("version") != version:
+            errors.append(f"server.json version {server.get('version')} differs from package version {version}")
+        packages = [item for item in server.get("packages", []) if isinstance(item, dict)]
+        npm = [item for item in packages if item.get("registryType", item.get("registry_type")) == "npm"]
+        if not npm:
+            errors.append("server.json lists no npm package")
+        for item in npm:
+            if item.get("identifier") != name:
+                errors.append(f"server.json package identifier {item.get('identifier')!r} differs from {name!r}")
+            if item.get("version") not in (None, version):
+                errors.append(f"server.json package version {item.get('version')} differs from {version}")
+        if mcp_name and not re.fullmatch(r"io\.github\.[A-Za-z0-9-]+/[A-Za-z0-9._-]+|[a-z0-9.-]+\.[a-z]{2,}/[A-Za-z0-9._-]+", str(mcp_name)):
+            warnings.append("mcpName should be a reverse-DNS namespace you can prove (io.github.<owner>/<name> or <domain>/<name>)")
+    if pack:
+        npm_bin = shutil.which("npm")
+        if not npm_bin:
+            errors.append("npm is required for --pack")
+        else:
+            completed = subprocess.run([npm_bin, "pack", "--dry-run", "--json", "--ignore-scripts"], cwd=package_dir, capture_output=True, text=True, check=False, timeout=180)
+            try:
+                listing = json.loads(completed.stdout or "[]")
+                packed = [entry["path"] for entry in listing[0].get("files", [])] if listing else []
+            except (json.JSONDecodeError, KeyError, IndexError):
+                packed = []
+                errors.append("npm pack --dry-run did not return a file list")
+            facts["packedFiles"] = len(packed)
+            for bad in [path for path in packed if SECRET_FILES.search(path)]:
+                errors.append(f"packed file looks like a secret: {bad}")
+            for command, target in (bins or {}).items():
+                if packed and str(target).lstrip("./") not in packed:
+                    errors.append(f"bin {command} → {target} is not in the packed tarball")
+    return {"schemaVersion": "maggie-product-release-check.v1", "passed": not errors, "facts": facts, "errors": errors, "warnings": warnings, "published": False}
+
+
+def smoke(package_dir: Path, timeout: int) -> dict:
+    npm_bin = shutil.which("npm")
+    if not npm_bin:
+        raise ValueError("npm is required for smoke")
+    package = _json(package_dir / "package.json")
+    version = str(package.get("version", ""))
+    bins = package.get("bin", {})
+    if isinstance(bins, str):
+        bins = {str(package.get("name", "")).split("/")[-1]: bins}
+    results, errors = [], []
+    with tempfile.TemporaryDirectory(prefix="maggie-product-smoke-") as directory:
+        work = Path(directory)
+        packed = subprocess.run([npm_bin, "pack", "--json", "--pack-destination", str(work)], cwd=package_dir, capture_output=True, text=True, check=False, timeout=600)
+        if packed.returncode:
+            raise ValueError("npm pack failed: " + packed.stderr[-300:])
+        tarball = work / json.loads(packed.stdout)[0]["filename"].split("/")[-1]
+        install_dir = work / "install"; install_dir.mkdir()
+        (install_dir / "package.json").write_text('{"name":"smoke","private":true}', encoding="utf-8")
+        installed = subprocess.run([npm_bin, "install", "--no-audit", "--no-fund", str(tarball)], cwd=install_dir, capture_output=True, text=True, check=False, timeout=timeout)
+        if installed.returncode:
+            raise ValueError("installing the packed tarball failed: " + installed.stderr[-300:])
+        for command in sorted(bins or {}):
+            executable = install_dir / "node_modules" / ".bin" / command
+            for flag in ("--version", "--help"):
+                run = subprocess.run([str(executable), flag], cwd=install_dir, capture_output=True, text=True, check=False, timeout=60)
+                ok = run.returncode == 0 and (flag != "--version" or version in run.stdout)
+                results.append({"bin": command, "flag": flag, "exitCode": run.returncode, "ok": ok})
+                if not ok:
+                    errors.append(f"{command} {flag} failed or did not print {version}" if flag == "--version" else f"{command} {flag} exited {run.returncode}")
+    return {"schemaVersion": "maggie-product-smoke.v1", "passed": not errors and bool(results), "version": version, "results": results, "errors": errors or ([] if results else ["package declares no bin"])}
+
+
+def _get(url: str, method: str = "GET", body: bytes | None = None, headers: dict | None = None) -> tuple[int, dict, bytes]:
+    request = Request(url, data=body, method=method, headers={"User-Agent": "maggie-product-mcp-check/1", **(headers or {})})
+    try:
+        with urlopen(request, timeout=20) as response:
+            return response.status, dict(response.headers), response.read(200_000)
+    except HTTPError as error:
+        return error.code, dict(error.headers or {}), (error.read() or b"")[:200_000]
+
+
+def mcp_check(mcp_url: str) -> dict:
+    parts = urlsplit(mcp_url)
+    if parts.scheme != "https" and parts.hostname not in {"localhost", "127.0.0.1"}:
+        raise ValueError("--mcp-url must be https (or localhost)")
+    origin = f"{parts.scheme}://{parts.netloc}"
+    errors, checks = [], {}
+    metadata = None
+    for candidate in (f"{origin}/.well-known/oauth-protected-resource{parts.path.rstrip('/')}", f"{origin}/.well-known/oauth-protected-resource"):
+        try:
+            status, _, body = _get(candidate)
+        except URLError as error:
+            raise ValueError(f"MCP host unreachable: {error.reason}") from error
+        checks[candidate.replace(origin, "")] = status
+        if status == 200:
+            try:
+                metadata = json.loads(body)
+            except json.JSONDecodeError:
+                errors.append("protected-resource metadata is not JSON")
+            break
+    if metadata is None:
+        errors.append("no OAuth protected-resource metadata (RFC 9728) at /.well-known/oauth-protected-resource")
+    else:
+        if not str(metadata.get("resource", "")).startswith(origin):
+            errors.append("metadata resource must be the MCP server URL on this origin")
+        if not metadata.get("authorization_servers"):
+            errors.append("metadata authorization_servers is empty")
+        if "header" not in (metadata.get("bearer_methods_supported") or ["header"]):
+            errors.append("bearer_methods_supported must include header")
+    initialize = json.dumps({"jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {"protocolVersion": "2025-06-18", "capabilities": {}, "clientInfo": {"name": "maggie-check", "version": "1"}}}).encode()
+    status, headers, _ = _get(mcp_url, "POST", initialize, {"Content-Type": "application/json", "Accept": "application/json, text/event-stream"})
+    challenge = next((value for key, value in headers.items() if key.lower() == "www-authenticate"), "")
+    checks["unauthenticatedInitialize"] = status
+    if status != 401:
+        errors.append(f"unauthenticated initialize returned {status}; an OAuth-protected server answers 401")
+    elif "resource_metadata=" not in challenge:
+        errors.append("401 has no WWW-Authenticate Bearer resource_metadata=… pointer; clients cannot discover the authorization server")
+    return {"schemaVersion": "maggie-product-mcp-check.v1", "passed": not errors, "checks": checks, "errors": errors, "authenticatedCalls": False}
+
+
+def review_status(reviews_path: Path, package_version: str | None, chatgpt_plugin: Path | None, today: date | None = None) -> dict:
+    data = _json(reviews_path)
+    today = today or datetime.now(timezone.utc).date()
+    errors, warnings, rows = [], [], []
+    for entry in data.get("reviews", []):
+        surface, state = entry.get("surface"), entry.get("status")
+        if surface not in REVIEW_SURFACES:
+            errors.append(f"unknown review surface {surface!r}"); continue
+        if state not in REVIEW_STATES:
+            errors.append(f"{surface}: unknown status {state!r}"); continue
+        row = {"surface": surface, "status": state, "version": entry.get("version")}
+        submitted = entry.get("submittedAt")
+        if state in {"submitted", "in-review"} and submitted:
+            days = (today - date.fromisoformat(str(submitted)[:10])).days
+            row["daysWaiting"] = days
+            if days > 14:
+                warnings.append(f"{surface}: {state} for {days} days; follow up or resubmit")
+        if state in {"changes-requested", "rejected"} and not entry.get("nextAction"):
+            errors.append(f"{surface}: {state} needs a nextAction")
+        if package_version and entry.get("version") and state in {"approved", "live"} and entry["version"] != package_version:
+            warnings.append(f"{surface}: approved/live version {entry['version']} differs from the release {package_version}")
+        rows.append(row)
+    if chatgpt_plugin:
+        plugin = _json(chatgpt_plugin)
+        cases = plugin.get("review", {}).get("test_cases", []) if isinstance(plugin.get("review"), dict) else []
+        positive = [case for case in cases if case.get("tools_triggered")]
+        negative = [case for case in cases if not case.get("tools_triggered")]
+        for case in cases:
+            missing = [key for key in ("description", "prompt", "expected_behavior") if not str(case.get(key, "")).strip()]
+            if missing:
+                errors.append(f"ChatGPT test case '{str(case.get('description', ''))[:40]}' misses {', '.join(missing)}")
+        if len(positive) < 5 or len(negative) < 3:
+            warnings.append(f"ChatGPT app review has {len(positive)} positive and {len(negative)} negative test cases; reviewers expect at least 5 and 3")
+    return {"schemaVersion": "maggie-product-review-status.v1", "passed": not errors, "reviews": rows, "errors": errors, "warnings": warnings}
+
+
+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)
+    check = sub.add_parser("release-check")
+    check.add_argument("--package", type=Path, default=Path("."), help="folder with package.json")
+    check.add_argument("--server-json", type=Path, help="MCP registry server.json")
+    check.add_argument("--changelog", type=Path)
+    check.add_argument("--pack", action="store_true", help="inspect `npm pack --dry-run` output")
+    smoke_parser = sub.add_parser("smoke")
+    smoke_parser.add_argument("--package", type=Path, default=Path("."))
+    smoke_parser.add_argument("--timeout", type=int, default=600)
+    mcp = sub.add_parser("mcp-check")
+    mcp.add_argument("--mcp-url", required=True)
+    review = sub.add_parser("review-status")
+    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")
+    args = parser.parse_args(argv)
+    try:
+        if 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)
+        elif args.command == "mcp-check":
+            report = mcp_check(args.mcp_url)
+        else:
+            version = _json(args.package / "package.json").get("version") if args.package else None
+            report = review_status(args.reviews, version, args.chatgpt_plugin)
+    except (OSError, ValueError, json.JSONDecodeError, subprocess.SubprocessError) as error:
+        print(f"BLOCKED: maggie product {args.command}: {error}", file=sys.stderr)
+        return 2
+    print(json.dumps(report, indent=2, ensure_ascii=False))
+    return 0 if report["passed"] else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/bundled-tools/clis/maggie_qa_app_preflight.py

@@ -0,0 +1,248 @@
+#!/usr/bin/env python3
+"""Preflight an app dev server before browser QA (``maggie qa app-preflight``).
+
+Three failures made browser QA of an Expo / React Native Web app look like a
+broken change or quietly damaged real data:
+
+- a Metro/Expo dev server started with ``CI=1`` (or ``--no-watch``) never
+  rebuilds, so the browser keeps serving the old bundle;
+- a dev server started from the monorepo root or the wrong ``apps/*`` folder
+  serves a different project;
+- a signed-in SPA that rotates refresh tokens is revoked when two instances
+  (iframes, tabs, parallel viewports) refresh at once, and a local dev server
+  that talks to a production API turns QA clicks into production writes.
+
+The command inspects running dev-server processes (Linux ``/proc``; other
+systems fall back to ``ps``), the app's environment files and auth code, and
+reports environment variable names and host classes only — never values,
+tokens, or full URLs.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import re
+import subprocess
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+from urllib.parse import urlsplit
+
+SCHEMA = "maggie-qa-app-preflight.v1"
+DEV_SERVER = re.compile(r"(expo(?:/cli)?[^ ]*\s+start|@expo/cli.*\bstart\b|react-native\s+start|metro(?:\.js)?\s|node_modules/\.bin/metro|expo-router)", re.I)
+API_KEY = re.compile(r"^(?:EXPO_PUBLIC_|NEXT_PUBLIC_|VITE_|PUBLIC_|REACT_APP_)?[A-Z0-9_]*(?:API|BACKEND|SERVER|GRAPHQL|SUPABASE)[A-Z0-9_]*(?:URL|BASE|ORIGIN|HOST|ENDPOINT)[A-Z0-9_]*$")
+LOCAL_HOST = re.compile(r"^(?:localhost|127\.\d+\.\d+\.\d+|0\.0\.0\.0|10\.\d+\.\d+\.\d+|192\.168\.\d+\.\d+|\[?::1\]?|[^.]+\.local|host\.docker\.internal)$", re.I)
+NON_PROD_HOST = re.compile(r"(?:^|[.-])(?:dev|development|staging|stage|test|testing|qa|preview|sandbox|local)(?:[.-]|$)", re.I)
+REFRESH = re.compile(r"refresh[_-]?token|refreshToken|grant_type\W+refresh_token", re.I)
+ROTATION = re.compile(r"rotat|reuse|revok|one[-_ ]time", re.I)
+SOURCE_SUFFIXES = {".ts", ".tsx", ".js", ".jsx", ".mjs"}
+SKIP_DIRS = {"node_modules", ".git", ".expo", "dist", "build", ".next", "ios", "android", ".maggie", "coverage", "web-build"}
+
+
+def list_processes() -> list[dict]:
+    """Return dev-server-like processes with cmdline, cwd and CI flag (values never kept)."""
+    found: list[dict] = []
+    proc = Path("/proc")
+    if proc.is_dir():
+        for entry in proc.iterdir():
+            if not entry.name.isdigit():
+                continue
+            try:
+                cmdline = (entry / "cmdline").read_bytes().replace(b"\0", b" ").decode("utf-8", "replace").strip()
+            except OSError:
+                continue
+            if not DEV_SERVER.search(cmdline + " "):
+                continue
+            item = {"pid": int(entry.name), "cmdline": cmdline, "cwd": None, "ci": None}
+            try:
+                item["cwd"] = os.readlink(entry / "cwd")
+            except OSError:
+                pass
+            try:
+                env = dict(line.split("=", 1) for line in (entry / "environ").read_bytes().decode("utf-8", "replace").split("\0") if "=" in line)
+                item["ci"] = env.get("CI", "").lower() in {"1", "true", "yes"}
+            except OSError:
+                pass
+            found.append(item)
+        return found
+    try:  # macOS / BSD: `ps eww` shows the environment after the command for own processes
+        output = subprocess.run(["ps", "-Ewwo", "pid=,command="], capture_output=True, text=True, timeout=10, check=False).stdout
+    except (OSError, subprocess.SubprocessError):
+        return found
+    for line in output.splitlines():
+        pid, _, command = line.strip().partition(" ")
+        if pid.isdigit() and DEV_SERVER.search(command + " "):
+            found.append({"pid": int(pid), "cmdline": command, "cwd": None, "ci": bool(re.search(r"(?:^|\s)CI=(?:1|true|yes)(?:\s|$)", command, re.I))})
+    return found
+
+
+def find_app_dirs(project: Path) -> list[Path]:
+    """Expo apps in the project: the root itself, or monorepo apps/* and packages/*."""
+    candidates = [project] + sorted(path for pattern in ("apps/*", "packages/*") for path in project.glob(pattern) if path.is_dir())
+    apps = []
+    for path in candidates:
+        package = path / "package.json"
+        if (path / "app.json").is_file() or (path / "app.config.ts").is_file() or (path / "app.config.js").is_file():
+            try:
+                deps = json.loads(package.read_text(encoding="utf-8")) if package.is_file() else {}
+            except json.JSONDecodeError:
+                deps = {}
+            names = {**deps.get("dependencies", {}), **deps.get("devDependencies", {})}
+            if "expo" in names or (path / "app.json").is_file():
+                apps.append(path)
+    return apps
+
+
+def classify_host(url: str) -> str:
+    host = (urlsplit(url).hostname or "").lower()
+    if not host:
+        return "unknown"
+    if LOCAL_HOST.match(host):
+        return "local"
+    if NON_PROD_HOST.search(host):
+        return "non-production"
+    return "production-like"
+
+
+def env_api_targets(app_dir: Path) -> list[dict]:
+    """API base settings from env files and app.json extra; names and host class only."""
+    targets = []
+    for name in (".env", ".env.local", ".env.development", ".env.development.local"):
+        path = app_dir / name
+        if not path.is_file():
+            continue
+        for line in path.read_text(encoding="utf-8", errors="replace").splitlines():
+            key, sep, value = line.strip().partition("=")
+            key = key.removeprefix("export ").strip()
+            if sep and API_KEY.match(key):
+                value = value.strip().strip('"').strip("'")
+                if value.startswith(("http://", "https://")):
+                    targets.append({"source": name, "key": key, "hostClass": classify_host(value)})
+    app_json = app_dir / "app.json"
+    if app_json.is_file():
+        try:
+            extra = json.loads(app_json.read_text(encoding="utf-8")).get("expo", {}).get("extra", {})
+        except json.JSONDecodeError:
+            extra = {}
+        for key, value in (extra.items() if isinstance(extra, dict) else []):
+            if isinstance(value, str) and value.startswith(("http://", "https://")) and re.search(r"api|backend|server|base", key, re.I):
+                targets.append({"source": "app.json expo.extra", "key": key, "hostClass": classify_host(value)})
+    return targets
+
+
+def refresh_token_signals(app_dir: Path, limit: int = 4000) -> dict:
+    """Look for refresh-token handling and rotation hints in the app's own source."""
+    files = refresh = rotation = 0
+    examples: list[str] = []
+    for root, dirs, names in os.walk(app_dir):
+        dirs[:] = [name for name in dirs if name not in SKIP_DIRS]
+        for name in names:
+            path = Path(root) / name
+            if path.suffix not in SOURCE_SUFFIXES:
+                continue
+            files += 1
+            if files > limit:
+                break
+            try:
+                text = path.read_text(encoding="utf-8", errors="replace")
+            except OSError:
+                continue
+            if REFRESH.search(text):
+                refresh += 1
+                if ROTATION.search(text):
+                    rotation += 1
+                if len(examples) < 5:
+                    examples.append(str(path.relative_to(app_dir)))
+    return {"filesScanned": files, "refreshTokenFiles": refresh, "rotationHintFiles": rotation, "examples": examples}
+
+
+def preflight(project: Path, app_dir: Path | None, base_url: str | None, rotating: str, processes: list[dict] | None = None) -> dict:
+    project = project.resolve()
+    errors: list[str] = []
+    warnings: list[str] = []
+    guidance: list[str] = []
+    apps = find_app_dirs(project)
+    if app_dir is None:
+        if len(apps) > 1:
+            errors.append("several app folders found (" + ", ".join(str(path.relative_to(project)) or "." for path in apps) + "); pass --app-dir so QA checks the right one")
+        app_dir = apps[0] if apps else project
+    app_dir = (project / app_dir).resolve() if not app_dir.is_absolute() else app_dir.resolve()
+    rel = lambda path: (str(Path(path).resolve().relative_to(project)) or ".") if Path(path).resolve().is_relative_to(project) else "outside the project"
+    servers = []
+    for item in (list_processes() if processes is None else processes):
+        cwd = item.get("cwd")
+        command = item.get("cmdline", "")
+        record = {"pid": item.get("pid"), "cwd": rel(cwd) if cwd else None, "ciMode": bool(item.get("ci")), "noWatch": "--no-watch" in command}
+        if cwd and not Path(cwd).resolve().is_relative_to(project):
+            record["scope"] = "other project"
+            servers.append(record)
+            continue
+        if record["ciMode"]:
+            errors.append(f"dev server pid {record['pid']} was started with CI=1: Metro does not watch files, so edits never reach the browser; restart it without CI")
+        if record["noWatch"]:
+            errors.append(f"dev server pid {record['pid']} runs without file watching; restart it with watching enabled")
+        if cwd and Path(cwd).resolve() != app_dir:
+            errors.append(f"dev server pid {record['pid']} was started from {record['cwd']}, not {rel(app_dir)}: it serves a different project; restart it from the app folder")
+        servers.append(record)
+    in_project = [server for server in servers if server.get("scope") != "other project"]
+    if not in_project:
+        warnings.append("no running Metro/Expo dev server found for this project; start one from the app folder without CI=1")
+    signals = refresh_token_signals(app_dir)
+    rotating_tokens = rotating == "yes" or (rotating == "auto" and signals["refreshTokenFiles"] > 0)
+    if rotating_tokens:
+        warnings.append("the app stores refresh tokens; if they rotate, reusing one revokes the session")
+        guidance += [
+            "Render one app instance at a time: no parallel iframes, tabs or viewports of the signed-in app.",
+            "Park the parent/QA tab on a static same-origin asset (for example /favicon.ico) so it does not refresh the session while a viewport renders.",
+            "Collect responsive evidence with `maggie design app-collect`, which renders viewports sequentially in one tab.",
+        ]
+    targets = env_api_targets(app_dir)
+    production = [target for target in targets if target["hostClass"] == "production-like"]
+    if production:
+        warnings.append("the local app talks to a production-like API (" + ", ".join(sorted({t["key"] for t in production})) + ")")
+        guidance += [
+            "Keep QA read-only: answer approval cards No, do not submit forms, and run `maggie design app-collect --read-only --allow-write <token refresh path>`.",
+            "Record the production-backed server in the QA run (`maggie qa start --api-base ... --production-api ...`) so mutating scenarios are refused.",
+        ]
+    if base_url and classify_host(base_url) == "production-like":
+        warnings.append("--base-url is a production-like host; QA should target the local dev server")
+    return {
+        "schemaVersion": SCHEMA,
+        "appDir": rel(app_dir),
+        "appCandidates": [rel(path) for path in apps],
+        "devServers": servers,
+        "refreshTokens": {"rotating": rotating_tokens, "source": rotating, **signals},
+        "apiTargets": targets,
+        "status": "failed" if errors else ("warning" if warnings else "passed"),
+        "errors": errors,
+        "warnings": warnings,
+        "guidance": guidance,
+        "checkedAt": datetime.now(timezone.utc).isoformat(),
+    }
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="maggie qa app-preflight", description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    parser.add_argument("--project", type=Path, default=Path("."))
+    parser.add_argument("--app-dir", type=Path, help="app folder inside a monorepo, e.g. apps/app")
+    parser.add_argument("--base-url", help="URL the browser QA will open")
+    parser.add_argument("--rotating-refresh-tokens", choices=("auto", "yes", "no"), default="auto")
+    parser.add_argument("--output", type=Path)
+    args = parser.parse_args(argv)
+    try:
+        report = preflight(args.project, args.app_dir, args.base_url, args.rotating_refresh_tokens)
+    except (OSError, ValueError) as error:
+        print(f"BLOCKED: maggie qa app-preflight: {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)
+    return 1 if report["errors"] else 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/bundled-tools/clis/maggie_qa_workflow.py

@@ -615,6 +615,11 @@ def parser() -> argparse.ArgumentParser:
 
 
 def main() -> int:
+    if "app-preflight" in sys.argv[1:3]:
+        from maggie_qa_app_preflight import main as app_preflight_main
+        argv = sys.argv[1:]
+        index = argv.index("app-preflight")
+        return app_preflight_main(argv[:index] + argv[index + 1:])
     args = parser().parse_args()
     try:
         if args.command == "start": return start(args)