@topy-ai/maggie 0.7.52 → 0.7.54

package/bundled-tools/clis/maggie_qa_app_preflight.py

@@ -12,6 +12,13 @@ broken change or quietly damaged real data:
   (iframes, tabs, parallel viewports) refresh at once, and a local dev server
   that talks to a production API turns QA clicks into production writes.
 
+Two more failures hid stale code: a dev server killed and replaced by another
+session's server on the same port, and a watcher that kept serving the old
+bundle after edits. ``--expect-symbol NAME`` fetches the served entry bundle
+from ``--base-url`` and fails when it lacks a name from the edit just made;
+the report also names the process holding the base URL's port and when it
+started, so a server restarted by someone else is obvious.
+
 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,
@@ -28,7 +35,8 @@ import subprocess
 import sys
 from datetime import datetime, timezone
 from pathlib import Path
-from urllib.parse import urlsplit
+from urllib.parse import urljoin, urlsplit
+from urllib.request import Request, urlopen
 
 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)
@@ -78,6 +86,84 @@ def list_processes() -> list[dict]:
     return found
 
 
+def process_started_at(pid: int) -> str | None:
+    """ISO start time of a Linux process from /proc/<pid>/stat and the boot time; None elsewhere."""
+    try:
+        stat = Path(f"/proc/{pid}/stat").read_text(encoding="utf-8")
+        ticks = int(stat.rsplit(")", 1)[1].split()[19])
+        boot = next(int(line.split()[1]) for line in Path("/proc/stat").read_text(encoding="utf-8").splitlines() if line.startswith("btime "))
+        return datetime.fromtimestamp(boot + ticks / os.sysconf("SC_CLK_TCK"), timezone.utc).isoformat(timespec="seconds")
+    except (OSError, ValueError, IndexError, StopIteration):
+        return None
+
+
+def port_owner(port: int) -> dict | None:
+    """The process listening on a TCP port (Linux /proc); command line trimmed to the program and script."""
+    inodes = set()
+    for table in ("/proc/net/tcp", "/proc/net/tcp6"):
+        try:
+            lines = Path(table).read_text(encoding="utf-8").splitlines()[1:]
+        except OSError:
+            continue
+        for line in lines:
+            fields = line.split()
+            if len(fields) > 9 and fields[3] == "0A" and int(fields[1].rsplit(":", 1)[1], 16) == port:
+                inodes.add(fields[9])
+    if not inodes:
+        return None
+    for entry in Path("/proc").iterdir():
+        if not entry.name.isdigit():
+            continue
+        links = set()
+        try:
+            descriptors = list((entry / "fd").iterdir())
+        except OSError:
+            continue
+        for fd in descriptors:
+            try:
+                links.add(os.readlink(fd))
+            except OSError:
+                continue
+        if any(f"socket:[{inode}]" in links for inode in inodes):
+            try:
+                cmdline = (entry / "cmdline").read_bytes().replace(b"\0", b" ").decode("utf-8", "replace").strip()
+                cwd = os.readlink(entry / "cwd")
+            except OSError:
+                cmdline, cwd = "", None
+            return {"pid": int(entry.name), "command": " ".join(cmdline.split()[:3])[:160], "cwd": cwd, "startedAt": process_started_at(int(entry.name))}
+    return {"pid": None, "command": "unknown (owned by another user)", "cwd": None, "startedAt": None}
+
+
+SCRIPT_SRC = re.compile(r"<script[^>]+src=[\"']([^\"']+)[\"']", re.I)
+
+
+def _fetch(url: str, limit: int) -> bytes:
+    request = Request(url, headers={"User-Agent": "maggie-qa-app-preflight"})
+    with urlopen(request, timeout=60) as response:  # noqa: S310 - local dev server URL given by the operator
+        return response.read(limit)
+
+
+def bundle_symbols(base_url: str, symbols: list[str], limit: int = 80_000_000) -> dict:
+    """Fetch the page at base_url and its same-origin scripts; report which expected names they contain."""
+    origin = urlsplit(base_url)
+    html = _fetch(base_url, 5_000_000).decode("utf-8", "replace")
+    scripts = []
+    for src in SCRIPT_SRC.findall(html):
+        url = urljoin(base_url, src)
+        if urlsplit(url).netloc == origin.netloc:
+            scripts.append(url)
+    found: dict[str, list[str]] = {symbol: [] for symbol in symbols}
+    fetched = []
+    for url in scripts[:12]:
+        body = _fetch(url, limit).decode("utf-8", "replace")
+        path = urlsplit(url).path
+        fetched.append({"path": path, "bytes": len(body)})
+        for symbol in symbols:
+            if symbol in body:
+                found[symbol].append(path)
+    return {"scripts": fetched, "found": {symbol: bool(paths) for symbol, paths in found.items()}, "foundIn": 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())
@@ -158,7 +244,7 @@ def refresh_token_signals(app_dir: Path, limit: int = 4000) -> dict:
     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:
+def preflight(project: Path, app_dir: Path | None, base_url: str | None, rotating: str, processes: list[dict] | None = None, expect_symbols: list[str] | None = None) -> dict:
     project = project.resolve()
     errors: list[str] = []
     warnings: list[str] = []
@@ -174,7 +260,7 @@ def preflight(project: Path, app_dir: Path | None, base_url: str | None, rotatin
     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}
+        record = {"pid": item.get("pid"), "cwd": rel(cwd) if cwd else None, "ciMode": bool(item.get("ci")), "noWatch": "--no-watch" in command, "startedAt": item.get("startedAt") or (process_started_at(item["pid"]) if isinstance(item.get("pid"), int) else None)}
         if cwd and not Path(cwd).resolve().is_relative_to(project):
             record["scope"] = "other project"
             servers.append(record)
@@ -189,6 +275,35 @@ def preflight(project: Path, app_dir: Path | None, base_url: str | None, rotatin
     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")
+    owner = None
+    if base_url:
+        parts = urlsplit(base_url)
+        port = parts.port or (443 if parts.scheme == "https" else 80)
+        if classify_host(base_url) == "local":
+            owner = port_owner(port)
+            if owner is None:
+                errors.append(f"nothing is listening on port {port}; the dev server was stopped or killed (check for exit 137) — start it from {rel(app_dir)}")
+            else:
+                owner = {**owner, "port": port, "cwd": rel(owner["cwd"]) if owner.get("cwd") else None}
+                known = {server["pid"] for server in in_project}
+                if owner["pid"] is not None and owner["pid"] not in known:
+                    where = owner["cwd"] or "an unknown folder"
+                    errors.append(f"port {port} is held by pid {owner['pid']} ({owner['command']}, started {owner['startedAt'] or 'unknown'}) from {where}, not by a dev server of {rel(app_dir)}; another session may have replaced it")
+    bundle = None
+    if expect_symbols:
+        if not base_url:
+            errors.append("--expect-symbol needs --base-url to fetch the served bundle")
+        else:
+            try:
+                bundle = bundle_symbols(base_url, expect_symbols)
+            except (OSError, ValueError) as error:
+                errors.append(f"could not fetch the served bundle from --base-url: {error}")
+            else:
+                if not bundle["scripts"]:
+                    errors.append("the page at --base-url has no same-origin script, so the served bundle could not be checked")
+                missing = [symbol for symbol, ok in bundle["found"].items() if not ok]
+                if bundle["scripts"] and missing:
+                    errors.append("the served bundle does not contain " + ", ".join(missing) + ": the dev server is serving old code (stale watcher, wrong folder or another session's server); restart it before QA")
     signals = refresh_token_signals(app_dir)
     rotating_tokens = rotating == "yes" or (rotating == "auto" and signals["refreshTokenFiles"] > 0)
     if rotating_tokens:
@@ -213,6 +328,8 @@ def preflight(project: Path, app_dir: Path | None, base_url: str | None, rotatin
         "appDir": rel(app_dir),
         "appCandidates": [rel(path) for path in apps],
         "devServers": servers,
+        "portOwner": owner,
+        "servedBundle": bundle,
         "refreshTokens": {"rotating": rotating_tokens, "source": rotating, **signals},
         "apiTargets": targets,
         "status": "failed" if errors else ("warning" if warnings else "passed"),
@@ -229,10 +346,11 @@ def main(argv: list[str] | None = None) -> int:
     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("--expect-symbol", action="append", default=[], metavar="NAME", help="a name from the edit just made (component, string, export); fails when the served bundle lacks it")
     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)
+        report = preflight(args.project, args.app_dir, args.base_url, args.rotating_refresh_tokens, expect_symbols=args.expect_symbol)
     except (OSError, ValueError) as error:
         print(f"BLOCKED: maggie qa app-preflight: {error}", file=sys.stderr)
         return 2

package/bundled-tools/clis/maggie_qa_fit.py

@@ -0,0 +1,217 @@
+#!/usr/bin/env python3
+"""Fit-to-screen check for dashboards (``maggie qa fit-check``).
+
+Some dashboards must never scroll the page: everything fits the viewport, and
+long content scrolls inside a pane, a drawer or a pager. Checking this by hand
+misses states — a tab that is hidden at load measures zero, so a list inside
+it looks fine until it is shown. This command loads each route at each
+viewport (default a short laptop 1536x687 and a 390x844 phone), measures page
+overflow, then **activates every tab** (DOM click, so a background browser
+window still works) and **opens every drawer trigger** and measures again
+after each change. Hidden panels are only measured after activation.
+
+Requests other than GET/HEAD/OPTIONS are failed by default (``--allow-write``
+lets a token refresh through), so opening drawers on a production-backed app
+cannot change data. One tab, one state at a time: safe with rotating refresh
+tokens. Output is ``maggie-qa-fit-check.v1`` JSON; exit 1 when a state
+overflows.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "runtime"))
+from cdp_client import Browser, CdpError, attach, launch  # noqa: E402
+
+SCHEMA = "maggie-qa-fit-check.v1"
+DEFAULT_VIEWPORTS = ("1536x687", "390x844")
+WRITE_METHODS = {"POST", "PUT", "PATCH", "DELETE"}
+
+# Icon fonts put private-use glyphs into innerText (React Native Web tabs read
+# "\nImage" or "Home"); labels drop them and prefer aria-label.
+HELPERS = r"""
+const __fit = window.__maggieFit = window.__maggieFit || {};
+__fit.label = (el) => {
+  const aria = el.getAttribute('aria-label') || '';
+  const text = (aria || el.innerText || el.textContent || '').replace(/[-]/g, '').replace(/\s+/g, ' ').trim();
+  return text.slice(0, 60);
+};
+__fit.visible = (el) => { const r = el.getBoundingClientRect(); const s = getComputedStyle(el); return r.width > 0 && r.height > 0 && s.visibility !== 'hidden' && s.display !== 'none'; };
+__fit.measure = (config) => {
+  const doc = document.scrollingElement || document.documentElement;
+  // Mobile emulation widens the layout viewport to fit wide content, so compare with the requested size.
+  const W = config.width || window.innerWidth, H = config.height || window.innerHeight;
+  const result = {width: W, height: H, pageOverflowY: Math.max(0, doc.scrollHeight - H), pageOverflowX: Math.max(0, doc.scrollWidth - W)};
+  if (result.pageOverflowX > 1) {
+    const wide = [...document.body.querySelectorAll('*')].find((el) => { const r = el.getBoundingClientRect(); return r.right > W + 1 && r.width > 0 && __fit.visible(el); });
+    if (wide) result.widest = (wide.tagName.toLowerCase() + (wide.id ? '#' + wide.id : '') + (typeof wide.className === 'string' && wide.className ? '.' + wide.className.trim().split(/\s+/).slice(0, 2).join('.') : '')).slice(0, 80);
+  }
+  if (config.sidebarSelector) {
+    const side = document.querySelector(config.sidebarSelector);
+    if (side) result.sidebarOverflowY = Math.max(0, side.scrollHeight - side.clientHeight);
+  }
+  const dialog = [...document.querySelectorAll('[role=dialog], dialog[open], [aria-modal=true]')].find(__fit.visible);
+  if (dialog) {
+    const r = dialog.getBoundingClientRect();
+    const inner = [dialog, ...dialog.querySelectorAll('*')].some((el) => el.scrollHeight > el.clientHeight + 1 && /(auto|scroll)/.test(getComputedStyle(el).overflowY));
+    result.dialog = {label: __fit.label(dialog), fits: r.left >= -1 && r.top >= -1 && r.right <= W + 1 && r.bottom <= H + 1, scrollsInside: inner};
+  }
+  return result;
+};
+__fit.targets = (selector) => [...document.querySelectorAll(selector)].filter(__fit.visible);
+"""
+
+
+def parse_viewport(value: str) -> tuple[int, int]:
+    match = re.fullmatch(r"(\d{3,4})x(\d{3,4})", value.strip())
+    if not match:
+        raise ValueError(f"viewport must look like 1536x687, got {value!r}")
+    return int(match.group(1)), int(match.group(2))
+
+
+def verdict(states: list[dict], tolerance: int = 1) -> list[str]:
+    """Failures for measured states: page overflow on either axis, a drawer outside the viewport."""
+    failures = []
+    for state in states:
+        where = f"{state['route']} @ {state['viewport']} [{state['state']}]"
+        m = state.get("measure") or {}
+        if state.get("error"):
+            failures.append(f"{where}: {state['error']}")
+            continue
+        if m.get("pageOverflowY", 0) > tolerance:
+            failures.append(f"{where}: the page scrolls vertically by {m['pageOverflowY']} px; move long content into a pane, drawer or pager")
+        if m.get("pageOverflowX", 0) > tolerance:
+            failures.append(f"{where}: the page scrolls sideways by {m['pageOverflowX']} px" + (f" (first wide element: {m['widest']})" if m.get("widest") else ""))
+        if m.get("sidebarOverflowY", 0) > tolerance:
+            failures.append(f"{where}: the sidebar overflows by {m['sidebarOverflowY']} px")
+        dialog = m.get("dialog")
+        if dialog and not dialog.get("fits"):
+            failures.append(f"{where}: drawer {dialog.get('label') or ''!r} extends past the viewport")
+    return failures
+
+
+def _install_read_only(browser: Browser, allow: list[str], blocked: list[str]) -> None:
+    def paused(params: dict) -> None:
+        request = params.get("request", {})
+        url = request.get("url", "")
+        if request.get("method", "GET").upper() in WRITE_METHODS and not any(token in url for token in allow):
+            blocked.append(f"{request.get('method')} {url.split('?')[0][:120]}")
+            browser.call("Fetch.failRequest", {"requestId": params["requestId"], "errorReason": "BlockedByClient"})
+        else:
+            browser.call("Fetch.continueRequest", {"requestId": params["requestId"]})
+    browser.handlers["Fetch.requestPaused"] = paused
+    browser.call("Fetch.enable", {"patterns": [{"urlPattern": "*", "requestStage": "Request"}]})
+
+
+def _load(browser: Browser, url: str, settle: float, budget: float) -> None:
+    browser.call("Page.navigate", {"url": url})
+    browser.wait_for("Page.loadEventFired", budget)
+    browser.pump(settle)
+    browser.evaluate(HELPERS)
+
+
+def check(browser: Browser, base_url: str, routes: list[str], viewports: list[tuple[int, int]], options: dict, settle_ms: int = 800, budget_ms: int = 20000, read_only: bool = True, allow_write: list[str] | None = None) -> dict:
+    settle, budget = settle_ms / 1000, budget_ms / 1000
+    blocked: list[str] = []
+    browser.open_tab()
+    browser.call("Page.enable")
+    if read_only:
+        _install_read_only(browser, allow_write or [], blocked)
+    states: list[dict] = []
+    for width, height in viewports:  # sequential: one app instance at a time
+        browser.call("Emulation.setDeviceMetricsOverride", {"width": width, "height": height, "deviceScaleFactor": 1, "mobile": width < 768})
+        viewport = f"{width}x{height}"
+        config = json.dumps({"sidebarSelector": options.get("sidebarSelector"), "width": width, "height": height})
+        for route in routes:
+            url = base_url.rstrip("/") + route
+            _load(browser, url, settle, budget)
+            states.append({"route": route, "viewport": viewport, "state": "initial", "measure": browser.evaluate(f"__maggieFit.measure({config})")})
+            tab_selector = json.dumps(options["tabSelector"])
+            tabs = browser.evaluate(f"__maggieFit.targets({tab_selector}).map(__maggieFit.label)") or []
+            for index, label in enumerate(tabs):
+                clicked = browser.evaluate(f"(() => {{ const el = __maggieFit.targets({tab_selector})[{index}]; if (!el) return false; el.click(); return true; }})()")
+                browser.pump(settle)
+                entry = {"route": route, "viewport": viewport, "state": f"tab {index + 1}: {label or '(no label)'}"}
+                if clicked:
+                    entry["measure"] = browser.evaluate(f"__maggieFit.measure({config})")
+                    entry["hash"] = browser.evaluate("location.hash")
+                else:
+                    entry["error"] = "tab disappeared before it could be activated"
+                states.append(entry)
+            if options.get("drawerSelector"):
+                drawer_selector = json.dumps(options["drawerSelector"])
+                _load(browser, url, settle, budget)
+                triggers = browser.evaluate(f"__maggieFit.targets({drawer_selector}).map(__maggieFit.label)") or []
+                for index, label in enumerate(triggers[: options.get("maxDrawers", 12)]):
+                    if index:
+                        _load(browser, url, settle, budget)  # a fresh page per drawer, so states never stack
+                    browser.evaluate(f"(() => {{ const el = __maggieFit.targets({drawer_selector})[{index}]; if (el) el.click(); }})()")
+                    browser.pump(settle)
+                    measure = browser.evaluate(f"__maggieFit.measure({config})")
+                    entry = {"route": route, "viewport": viewport, "state": f"drawer {index + 1}: {label or '(no label)'}", "measure": measure}
+                    if not (measure or {}).get("dialog"):
+                        entry["warning"] = "no visible role=dialog after the click"
+                    states.append(entry)
+    failures = verdict(states)
+    return {
+        "schemaVersion": SCHEMA,
+        "baseUrl": base_url,
+        "routes": routes,
+        "viewports": [f"{w}x{h}" for w, h in viewports],
+        "states": states,
+        "blockedWrites": sorted(set(blocked)),
+        "status": "failed" if failures else "passed",
+        "failures": failures,
+        "checkedAt": datetime.now(timezone.utc).isoformat(),
+    }
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="maggie qa fit-check", description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    parser.add_argument("--base-url", required=True)
+    parser.add_argument("--route", action="append", required=True, help="path to check; repeat for every dashboard route")
+    parser.add_argument("--viewport", action="append", default=[], help="WIDTHxHEIGHT; repeatable (default 1536x687 and 390x844)")
+    session = parser.add_mutually_exclusive_group(required=True)
+    session.add_argument("--cdp-url", help="attach to a signed-in Chrome started with --remote-debugging-port")
+    session.add_argument("--profile-dir", type=Path, help="dedicated QA Chrome profile (never your everyday profile)")
+    parser.add_argument("--chrome", default="")
+    parser.add_argument("--headed", action="store_true")
+    parser.add_argument("--tab-selector", default="[role=tab]")
+    parser.add_argument("--drawer-selector", help="elements that open a drawer or dialog, e.g. [data-drawer-trigger]")
+    parser.add_argument("--sidebar-selector", help="sidebar that must not overflow either")
+    parser.add_argument("--allow-write", action="append", default=[], help="URL substring allowed to POST (token refresh)")
+    parser.add_argument("--allow-writes", action="store_true", help="do not block write requests (non-production API only)")
+    parser.add_argument("--settle-ms", type=int, default=800)
+    parser.add_argument("--output", type=Path)
+    args = parser.parse_args(argv)
+    browser = None
+    try:
+        viewports = [parse_viewport(value) for value in (args.viewport or DEFAULT_VIEWPORTS)]
+        if args.cdp_url:
+            browser = attach(args.cdp_url)
+        else:
+            from maggie_icon_glyph_check import find_chrome
+            browser = launch(args.chrome or find_chrome(), args.profile_dir.resolve(), headless=not args.headed)
+        report = check(browser, args.base_url, args.route, viewports, {"tabSelector": args.tab_selector, "drawerSelector": args.drawer_selector, "sidebarSelector": args.sidebar_selector}, args.settle_ms, read_only=not args.allow_writes, allow_write=args.allow_write)
+    except (OSError, ValueError, CdpError, RuntimeError) as error:
+        print(f"BLOCKED: maggie qa fit-check: {error}", file=sys.stderr)
+        return 2
+    finally:
+        if browser:
+            browser.close()
+    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["failures"] 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 "fit-check" in sys.argv[1:3]:
+        from maggie_qa_fit import main as fit_main
+        argv = sys.argv[1:]
+        index = argv.index("fit-check")
+        return fit_main(argv[:index] + argv[index + 1:])
     if "app-preflight" in sys.argv[1:3]:
         from maggie_qa_app_preflight import main as app_preflight_main
         argv = sys.argv[1:]

package/bundled-tools/clis/maggie_schema_complexity.py

@@ -0,0 +1,84 @@
+#!/usr/bin/env python3
+"""Estimate structured-output JSON schema complexity before a model rejects it.
+
+Gemini answers ``400 INVALID_ARGUMENT`` (with no detail) when a response
+schema is too complex. The limit is complexity, not vocabulary size: an enum
+of 5-6 values inside the items of an array with ``maxItems: 20`` fails, while
+4 values or ``maxItems: 10`` pass. The size of the state space is roughly
+enum values x repeated array items x nesting, so the check:
+
+- fails on any ``enum``/``const`` list inside repeated array items: describe
+  the allowed values in the prompt or the field description and validate
+  server-side instead;
+- fails on enums over 20 values anywhere, and on arrays without ``maxItems``
+  around nested objects;
+- reports an estimated complexity score (sum of enum values and properties,
+  each multiplied by the ``maxItems`` of every enclosing array) and warns
+  above 200, plus nesting deeper than 5.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+ENUM_LIMIT = 20
+SCORE_WARN = 200
+DEPTH_WARN = 5
+
+
+def check_schema(schema: dict) -> dict:
+    errors: list[str] = []
+    warnings: list[str] = []
+    score = 0
+    deepest = 0
+
+    def walk(node: object, path: str, multiplier: int, in_array: bool, depth: int) -> None:
+        nonlocal score, deepest
+        if not isinstance(node, dict):
+            return
+        deepest = max(deepest, depth)
+        values = node.get("enum") if isinstance(node.get("enum"), list) else None
+        if values is not None:
+            score += len(values) * multiplier
+            if in_array:
+                errors.append(f"{path}: enum of {len(values)} inside repeated array items (x{multiplier}); describe the allowed values in the prompt and validate server-side")
+            elif len(values) > ENUM_LIMIT:
+                errors.append(f"{path}: enum of {len(values)} values; use a string, list examples in the prompt, validate server-side")
+        properties = node.get("properties") if isinstance(node.get("properties"), dict) else {}
+        score += len(properties) * multiplier
+        for name, child in properties.items():
+            walk(child, f"{path}.{name}", multiplier, in_array, depth + 1)
+        items = node.get("items")
+        if isinstance(items, dict):
+            max_items = node.get("maxItems")
+            if not isinstance(max_items, int):
+                if isinstance(items.get("properties"), dict) or isinstance(items.get("enum"), list):
+                    errors.append(f"{path}: array of objects/enums without maxItems; set a small maxItems")
+                max_items = 10
+            walk(items, f"{path}[]", multiplier * max(1, max_items), True, depth + 1)
+        for key in ("anyOf", "oneOf", "allOf"):
+            for index, child in enumerate(node.get(key) or []):
+                walk(child, f"{path}.{key}[{index}]", multiplier, in_array, depth + 1)
+
+    walk(schema, "$", 1, False, 0)
+    if score > SCORE_WARN:
+        warnings.append(f"estimated complexity {score} is high; lower maxItems, split the call, or move vocabularies into the prompt")
+    if deepest > DEPTH_WARN:
+        warnings.append(f"nesting depth {deepest}; flatten the schema")
+    return {"schemaVersion": "maggie-schema-complexity.v1", "valid": not errors, "score": score, "depth": deepest, "errors": errors, "warnings": warnings}
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="maggie social schema-check", description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    parser.add_argument("input", type=Path, help="JSON schema file (responseJsonSchema)")
+    args = parser.parse_args(argv)
+    result = check_schema(json.loads(args.input.read_text(encoding="utf-8")))
+    print(json.dumps(result, indent=2, ensure_ascii=False))
+    return 0 if result["valid"] else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/bundled-tools/clis/maggie_seo_routes.py

@@ -0,0 +1,154 @@
+#!/usr/bin/env python3
+"""Route-check guards for SEO release checks (``maggie seo origin-check|fragment-check``).
+
+``origin-check`` proves which site a base URL serves before route checks run
+against it. Check scripts that default to ``http://127.0.0.1:4321`` silently hit
+whatever else runs on that port and report false "foreign URL" and sitemap
+failures. The command fetches the page and ``/robots.txt`` and compares the
+canonical / ``og:url`` / sitemap host with the project's configured site
+(``site`` in ``astro.config.*``, or ``--expect-host``), and prints the origin it
+checked.
+
+``fragment-check`` checks personalised HTML fragments (recently viewed,
+recommendations, "your bookings" partials): each must answer
+``Cache-Control: private, no-store`` (no ``public``/``s-maxage``) and
+``X-Robots-Tag: noindex``. Global middleware that sets public caching on every
+``text/html`` response must keep a route's private header; otherwise a CDN
+caches one person's fragment and serves it to others.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+from pathlib import Path
+from urllib.error import HTTPError, URLError
+from urllib.parse import urljoin, urlsplit
+from urllib.request import Request, urlopen
+
+CANONICAL = re.compile(r"<link[^>]+rel=[\"']canonical[\"'][^>]*href=[\"']([^\"']+)|<link[^>]+href=[\"']([^\"']+)[\"'][^>]*rel=[\"']canonical[\"']", re.I)
+OG_URL = re.compile(r"<meta[^>]+property=[\"']og:url[\"'][^>]*content=[\"']([^\"']+)", re.I)
+SITE_CONFIG = re.compile(r"\bsite\s*:\s*[\"'`](https?://[^\"'`]+)[\"'`]")
+
+
+def fetch(url: str, headers: dict | None = None, limit: int = 2_000_000) -> tuple[int, dict, str]:
+    request = Request(url, headers={"User-Agent": "maggie-seo-route-check", **(headers or {})})
+    try:
+        with urlopen(request, timeout=20) as response:  # noqa: S310 - operator-supplied check URL
+            return response.status, {k.lower(): v for k, v in response.headers.items()}, response.read(limit).decode("utf-8", "replace")
+    except HTTPError as error:
+        return error.code, {k.lower(): v for k, v in error.headers.items()}, ""
+
+
+def host(url: str) -> str:
+    return (urlsplit(url).hostname or "").lower().removeprefix("www.")
+
+
+def configured_host(project: Path) -> str | None:
+    for name in ("astro.config.mjs", "astro.config.ts", "astro.config.js", "astro.config.mts"):
+        path = project / name
+        if path.is_file():
+            match = SITE_CONFIG.search(path.read_text(encoding="utf-8", errors="replace"))
+            if match:
+                return host(match.group(1))
+    return None
+
+
+def origin_check(base_url: str, project: Path, expect_host: str | None = None, fetcher=fetch) -> dict:
+    parts = urlsplit(base_url)
+    if parts.scheme not in {"http", "https"} or not parts.netloc:
+        raise ValueError("--base-url must be an absolute http(s) URL; route checks must never assume a default port")
+    origin = f"{parts.scheme}://{parts.netloc}"
+    expected = (expect_host or configured_host(project) or "").lower().removeprefix("www.") or None
+    errors: list[str] = []
+    warnings: list[str] = []
+    try:
+        status, _, html = fetcher(base_url)
+        robots_status, _, robots = fetcher(urljoin(origin + "/", "robots.txt"))
+    except (URLError, OSError) as error:
+        return {"schemaVersion": "maggie-seo-origin-check.v1", "origin": origin, "passed": False, "errors": [f"nothing answered at {origin}: {error}"], "warnings": []}
+    seen = {}
+    canonical = CANONICAL.search(html)
+    if canonical:
+        seen["canonical"] = host(canonical.group(1) or canonical.group(2))
+    og = OG_URL.search(html)
+    if og:
+        seen["og:url"] = host(og.group(1))
+    sitemap = re.search(r"^\s*sitemap:\s*(\S+)", robots, re.I | re.M) if robots_status == 200 else None
+    if sitemap:
+        seen["robots sitemap"] = host(sitemap.group(1))
+    if status >= 400:
+        errors.append(f"{base_url} answered {status}")
+    if not expected:
+        warnings.append("no expected host: set `site` in astro.config or pass --expect-host, so a different local project on this port is detected")
+    elif not seen:
+        warnings.append(f"{origin} shows no canonical, og:url or robots sitemap to identify the site")
+    else:
+        foreign = {source: value for source, value in seen.items() if value and value != expected and not value.endswith("." + expected)}
+        if foreign:
+            errors.append(f"{origin} serves another site ({', '.join(f'{k}: {v}' for k, v in foreign.items())}), not {expected}; start this project's server or pass the right --base-url")
+    return {"schemaVersion": "maggie-seo-origin-check.v1", "origin": origin, "expectedHost": expected, "seenHosts": seen, "passed": not errors, "errors": errors, "warnings": warnings}
+
+
+def fragment_problems(headers: dict) -> list[str]:
+    cache = headers.get("cache-control", "").lower()
+    directives = {item.strip().split("=")[0] for item in cache.split(",") if item.strip()}
+    problems = []
+    if "private" not in directives:
+        problems.append("Cache-Control lacks private")
+    if "no-store" not in directives:
+        problems.append("Cache-Control lacks no-store")
+    if directives & {"public", "s-maxage"}:
+        problems.append("Cache-Control allows shared caching (" + ", ".join(sorted(directives & {"public", "s-maxage"})) + "); middleware must keep the route's private header")
+    if "noindex" not in headers.get("x-robots-tag", "").lower():
+        problems.append("X-Robots-Tag lacks noindex")
+    if headers.get("cdn-cache-control") or headers.get("surrogate-control"):
+        problems.append("a CDN-specific cache header is set; remove it for personalised fragments")
+    return problems
+
+
+def fragment_check(urls: list[str], cookie: str | None = None, fetcher=fetch) -> dict:
+    rows = []
+    errors = []
+    for url in urls:
+        try:
+            status, headers, _ = fetcher(url, {"Cookie": cookie} if cookie else None)
+        except (URLError, OSError) as error:
+            errors.append(f"{url}: {error}")
+            continue
+        problems = fragment_problems(headers)
+        rows.append({"url": url, "status": status, "cacheControl": headers.get("cache-control"), "xRobotsTag": headers.get("x-robots-tag"), "problems": problems})
+        errors += [f"{url}: {problem}" for problem in problems]
+    return {"schemaVersion": "maggie-seo-fragment-check.v1", "fragments": rows, "passed": not errors, "errors": errors}
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="maggie seo", description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    sub = parser.add_subparsers(dest="command", required=True)
+    origin = sub.add_parser("origin-check")
+    origin.add_argument("--base-url", required=True)
+    origin.add_argument("--project", type=Path, default=Path("."))
+    origin.add_argument("--expect-host")
+    fragment = sub.add_parser("fragment-check")
+    fragment.add_argument("--url", action="append", required=True, help="personalised fragment URL; repeat")
+    fragment.add_argument("--cookie-env", help="environment variable holding a test session cookie (never pass the value on the command line)")
+    args = parser.parse_args(argv)
+    try:
+        if args.command == "origin-check":
+            report = origin_check(args.base_url, args.project.resolve(), args.expect_host)
+        else:
+            import os
+            report = fragment_check(args.url, os.environ.get(args.cookie_env) if args.cookie_env else None)
+    except ValueError as error:
+        print(f"BLOCKED: maggie seo {args.command}: {error}", file=sys.stderr)
+        return 2
+    print(json.dumps(report, indent=2, ensure_ascii=False))
+    if args.command == "origin-check":
+        print(f"checked origin: {report['origin']}", file=sys.stderr)
+    return 0 if report["passed"] else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())