@topy-ai/maggie 0.7.51 → 0.7.53

package/bundled-tools/clis/maggie_deployment_ops.py

@@ -0,0 +1,461 @@
+#!/usr/bin/env python3
+"""Deployment operations that were run by hand and went wrong (``maggie deployment ...``).
+
+- ``cloudflare-preflight``: refuse ``wrangler deploy`` when CLOUDFLARE_API_TOKEN
+  or CLOUDFLARE_ACCOUNT_ID is empty. Wrangler then silently uses its cached
+  OAuth login — possibly another Cloudflare account — uploads a stray Worker
+  there and fails with "Can't infer zone from route ... [code: 10082]".
+  Checks the config's ``account_id`` and, with ``--verify-zone``, that the
+  token's account owns the zone of every custom-domain route (read-only API
+  calls).
+- ``file-parity``: before a surgical multi-host copy, hash the files about to
+  be replaced on every host and compare them with the copies at the commit
+  that is deployed (and across hosts), instead of ad-hoc md5sum loops.
+- ``warm-check``: send warm-up requests first, then judge latency; the first
+  requests after a restart (8-16 s) are worker start-up, not a regression.
+- ``vps-release``: one command for the SSR Node release done by hand: git
+  archive of a commit → upload → install → build **as the deploy user** with
+  the server env file → switch ``current`` → restart → health/smoke with
+  warm-up → prune to N releases → a roadmap line. Dry run unless ``--confirm``.
+  Building with ``sudo`` leaves root-owned ``dist``/cache files that the
+  unprivileged prune cannot remove; the release refuses that and names the
+  one-time fix.
+
+Values of secrets are never printed; only variable names and digests.
+"""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import os
+import re
+import shlex
+import subprocess
+import sys
+import time
+from datetime import datetime, timezone
+from pathlib import Path
+from urllib.error import HTTPError, URLError
+from urllib.parse import quote
+from urllib.request import Request, urlopen
+
+CF_REQUIRED = ("CLOUDFLARE_API_TOKEN", "CLOUDFLARE_ACCOUNT_ID")
+CF_NEAR_MISS = re.compile(r"^(?:CF_|CLOUDFLARE_)(?:API_)?(?:TOKEN|KEY|ACCOUNT(?:_ID)?|ACCOUNTID)$")
+OAUTH_CACHES = ("~/.config/.wrangler/config/default.toml", "~/.wrangler/config/default.toml", "~/Library/Preferences/.wrangler/config/default.toml")
+SAFE_REF = re.compile(r"^[A-Za-z0-9._/@{}~^:-]{1,200}$")
+SAFE_PATH = re.compile(r"^[A-Za-z0-9._/@+-][A-Za-z0-9._/@+ -]{0,300}$")
+
+
+def _env_file(path: Path | None) -> dict[str, str]:
+    values: dict[str, str] = {}
+    if not path or not path.is_file():
+        return values
+    for line in path.read_text(encoding="utf-8", errors="replace").splitlines():
+        line = line.strip()
+        if not line or line.startswith("#") or "=" not in line:
+            continue
+        key, value = line.removeprefix("export ").split("=", 1)
+        values[key.strip()] = value.strip().strip("\"'")
+    return values
+
+
+def _strip_jsonc(text: str) -> str:
+    out, i, in_string = [], 0, False
+    while i < len(text):
+        char = text[i]
+        if in_string:
+            out.append(char)
+            if char == "\\" and i + 1 < len(text):
+                out.append(text[i + 1]); i += 2; continue
+            if char == '"':
+                in_string = False
+        elif char == '"':
+            in_string = True; out.append(char)
+        elif text.startswith("//", i):
+            while i < len(text) and text[i] != "\n":
+                i += 1
+            continue
+        elif text.startswith("/*", i):
+            end = text.find("*/", i + 2)
+            i = len(text) if end < 0 else end + 2
+            continue
+        else:
+            out.append(char)
+        i += 1
+    return re.sub(r",(\s*[}\]])", r"\1", "".join(out))
+
+
+def wrangler_config(project: Path, config: Path | None, env_name: str | None) -> dict:
+    """account_id and route patterns/zones from wrangler.json(c) or wrangler.toml (minimal TOML reading)."""
+    candidates = [config] if config else [project / name for name in ("wrangler.jsonc", "wrangler.json", "wrangler.toml")]
+    path = next((p for p in candidates if p and p.is_file()), None)
+    if path is None:
+        raise ValueError("no wrangler.jsonc / wrangler.json / wrangler.toml found; pass --config")
+    text = path.read_text(encoding="utf-8")
+    routes: list[dict] = []
+    if path.suffix in {".json", ".jsonc"}:
+        data = json.loads(_strip_jsonc(text))
+        section = data.get("env", {}).get(env_name, {}) if env_name else data
+        account = section.get("account_id") or data.get("account_id")
+        raw = section.get("routes") or ([section["route"]] if section.get("route") else [])
+        for route in raw:
+            routes.append(route if isinstance(route, dict) else {"pattern": route})
+    else:
+        account_match = re.search(r'^\s*account_id\s*=\s*"([^"]+)"', text, re.M)
+        account = account_match.group(1) if account_match else None
+        for match in re.finditer(r'\{\s*pattern\s*=\s*"([^"]+)"([^}]*)\}', text):
+            extra = match.group(2)
+            zone = re.search(r'zone_name\s*=\s*"([^"]+)"', extra)
+            routes.append({"pattern": match.group(1), "custom_domain": "custom_domain = true" in extra.replace("  ", " "), **({"zone_name": zone.group(1)} if zone else {})})
+        for match in re.finditer(r'^\s*route\s*=\s*"([^"]+)"', text, re.M):
+            routes.append({"pattern": match.group(1)})
+    for route in routes:
+        if not route.get("zone_name"):
+            host = str(route.get("pattern", "")).split("/")[0].lstrip("*.")
+            parts = host.split(".")
+            route["zone_guess"] = ".".join(parts[-2:]) if len(parts) >= 2 else host
+    return {"path": path.name, "accountId": account, "routes": routes}
+
+
+def _cf_get(token: str, path: str) -> dict:
+    request = Request("https://api.cloudflare.com/client/v4" + path, headers={"Authorization": f"Bearer {token}", "Accept": "application/json"})
+    try:
+        with urlopen(request, timeout=20) as response:  # noqa: S310 - fixed Cloudflare API host
+            return json.loads(response.read())
+    except HTTPError as error:
+        return {"success": False, "status": error.code}
+    except (URLError, OSError, ValueError) as error:
+        return {"success": False, "error": str(error)[:120]}
+
+
+def cloudflare_preflight(project: Path, config: Path | None, env_name: str | None, env_file: Path | None, verify_zone: bool, environ: dict | None = None, home: Path | None = None, api=_cf_get) -> dict:
+    environ = dict(os.environ if environ is None else environ)
+    file_values = _env_file(env_file)
+    errors: list[str] = []
+    warnings: list[str] = []
+    resolved = {}
+    for name in CF_REQUIRED:
+        value = (environ.get(name) or "").strip()
+        source = "environment" if value else None
+        if not value and file_values.get(name, "").strip():
+            value, source = file_values[name].strip(), "env-file"
+        resolved[name] = value
+        if not value:
+            errors.append(f"{name} is empty: wrangler would fall back to its cached OAuth login (maybe another account) — set it before deploying")
+        else:
+            resolved[name + ":source"] = source
+    near = sorted(key for key in set(file_values) | set(environ) if CF_NEAR_MISS.match(key) and key not in CF_REQUIRED and (file_values.get(key) or environ.get(key)))
+    if near and any(not resolved[name] for name in CF_REQUIRED):
+        warnings.append("found " + ", ".join(near) + " but wrangler reads " + " and ".join(CF_REQUIRED) + "; the deploy script may read the wrong names")
+    home = home or Path.home()
+    caches = [path for path in OAUTH_CACHES if (home / path.removeprefix("~/")).is_file()]
+    if caches:
+        warnings.append("wrangler has a cached OAuth login (" + caches[0] + "); it is used whenever the token is missing. Keep CLOUDFLARE_API_TOKEN set for deploys, or run `wrangler logout` on deploy machines")
+    cfg = wrangler_config(project, config, env_name)
+    account = resolved.get("CLOUDFLARE_ACCOUNT_ID")
+    if not cfg["accountId"]:
+        warnings.append(f"{cfg['path']} has no account_id; set it so wrangler cannot deploy into another account")
+    elif account and cfg["accountId"] != account:
+        errors.append(f"{cfg['path']} account_id differs from CLOUDFLARE_ACCOUNT_ID; the deploy would target another account")
+    zones = sorted({route.get("zone_name") or route.get("zone_guess") for route in cfg["routes"] if route.get("zone_name") or route.get("zone_guess")})
+    zone_checks = []
+    if verify_zone and not errors:
+        token = resolved["CLOUDFLARE_API_TOKEN"]
+        verify = api(token, "/user/tokens/verify")
+        if not verify.get("success"):
+            errors.append("CLOUDFLARE_API_TOKEN did not verify (expired, revoked or a different token type)")
+        for zone in zones:
+            found = api(token, f"/zones?name={quote(zone)}&account.id={quote(account or '')}")
+            owned = bool(found.get("success") and found.get("result"))
+            zone_checks.append({"zone": zone, "ownedByAccount": owned})
+            if not owned:
+                errors.append(f"zone {zone} is not in account {account[-6:] if account else '?'} for this token: routes on it fail with code 10082")
+    elif zones:
+        warnings.append("zone ownership not verified; add --verify-zone (read-only API calls) before the first deploy to a domain")
+    return {
+        "schemaVersion": "maggie-cloudflare-preflight.v1",
+        "config": cfg["path"],
+        "variables": {name: bool(resolved[name]) for name in CF_REQUIRED},
+        "sources": {name: resolved.get(name + ":source") for name in CF_REQUIRED},
+        "routes": [route.get("pattern") for route in cfg["routes"]],
+        "zones": zone_checks or [{"zone": zone, "ownedByAccount": None} for zone in zones],
+        "status": "failed" if errors else ("warning" if warnings else "passed"),
+        "errors": errors,
+        "warnings": warnings,
+    }
+
+
+# --- hosts --------------------------------------------------------------------------
+
+def run_on(host: str, script: str, ssh_args: list[str], stdin: bytes | None = None, timeout: int = 1800) -> subprocess.CompletedProcess:
+    """Run a bash script on a host over ssh stdin ("local" runs it here, for tests and single-host setups)."""
+    if host == "local":
+        return subprocess.run(["bash", "-c", script], input=stdin, capture_output=True, timeout=timeout, check=False)
+    payload = script.encode() if stdin is None else stdin
+    command = ["ssh", "-o", "BatchMode=yes", *ssh_args, host]
+    command += ["bash -s"] if stdin is None else ["bash -c " + shlex.quote(script)]
+    return subprocess.run(command, input=payload, capture_output=True, timeout=timeout, check=False)
+
+
+def file_parity(hosts: list[str], root: str, paths: list[str], repo: Path, ref: str, subdir: str, ssh_args: list[str]) -> dict:
+    if not SAFE_REF.match(ref) or ref.startswith("-"):
+        raise ValueError("--ref must be a git revision")
+    for path in paths:
+        if not SAFE_PATH.match(path) or ".." in path.split("/"):
+            raise ValueError(f"unsafe path {path!r}")
+    expected = {}
+    for path in paths:
+        blob = subprocess.run(["git", "-C", str(repo), "show", f"{ref}:{(subdir.strip('/') + '/' if subdir else '')}{path}"], capture_output=True, check=False)
+        expected[path] = hashlib.sha256(blob.stdout).hexdigest() if blob.returncode == 0 else None
+    script = "set -u\ncd " + shlex.quote(root) + " || exit 3\n" + "".join(
+        f"if [ -f {shlex.quote(p)} ]; then printf '%s %s\\n' \"$(sha256sum < {shlex.quote(p)} | cut -c1-64)\" {shlex.quote(p)}; else printf 'MISSING %s\\n' {shlex.quote(p)}; fi\n" for p in paths)
+    observed: dict[str, dict[str, str | None]] = {}
+    errors: list[str] = []
+    for host in hosts:
+        result = run_on(host, script, ssh_args, timeout=120)
+        if result.returncode:
+            errors.append(f"{host}: could not read {root} (exit {result.returncode})")
+            continue
+        observed[host] = {}
+        for line in result.stdout.decode().splitlines():
+            digest, _, path = line.partition(" ")
+            observed[host][path] = None if digest == "MISSING" else digest
+    rows = []
+    for path in paths:
+        row = {"path": path, "expected": (expected[path] or "")[:12] or None, "hosts": {}}
+        digests = set()
+        for host, files in observed.items():
+            digest = files.get(path)
+            digests.add(digest)
+            state = "missing" if digest is None else ("match" if digest == expected[path] else "differs")
+            row["hosts"][host] = state
+            if expected[path] is None:
+                row["hosts"][host] = "new-file" if digest is None else "unexpected"
+            if state == "differs" and expected[path]:
+                errors.append(f"{host}: {path} differs from {ref}; someone changed it on the host — copying over it would hide that")
+            if state == "missing" and expected[path]:
+                errors.append(f"{host}: {path} is missing although it exists at {ref}")
+        if len(digests) > 1:
+            errors.append(f"{path}: hosts disagree with each other")
+        rows.append(row)
+    return {"schemaVersion": "maggie-file-parity.v1", "ref": ref, "root": root, "files": rows, "passed": not errors, "errors": sorted(set(errors))}
+
+
+def timed_get(url: str, timeout: float = 30.0) -> tuple[int, float]:
+    started = time.monotonic()
+    try:
+        with urlopen(Request(url, headers={"User-Agent": "maggie-warm-check", "Cache-Control": "no-cache"}), timeout=timeout) as response:  # noqa: S310
+            response.read(65536)
+            status = response.status
+    except HTTPError as error:
+        status = error.code
+    except (URLError, OSError):
+        status = 0
+    return status, round((time.monotonic() - started) * 1000, 1)
+
+
+def warm_check(urls: list[str], warm: int, samples: int, budget_ms: float, fetch=timed_get) -> dict:
+    """Warm each URL (one request per worker you expect), then judge latency on later samples only."""
+    results = []
+    errors = []
+    for url in urls:
+        warmups = [fetch(url) for _ in range(warm)]
+        measured = [fetch(url) for _ in range(samples)]
+        times = sorted(ms for status, ms in measured if 200 <= status < 400)
+        statuses = sorted({status for status, _ in measured})
+        median = times[len(times) // 2] if times else None
+        row = {"url": url, "warmupMs": [ms for _, ms in warmups], "statuses": statuses, "medianMs": median, "maxMs": times[-1] if times else None}
+        if not times or any(not 200 <= s < 400 for s in statuses):
+            errors.append(f"{url}: status {statuses} after warm-up")
+        elif budget_ms and median > budget_ms:
+            errors.append(f"{url}: median {median} ms after {warm} warm-up request(s), budget {budget_ms} ms")
+        results.append(row)
+    return {"schemaVersion": "maggie-warm-check.v1", "warm": warm, "samples": samples, "results": results, "passed": not errors, "errors": errors}
+
+
+# --- vps release -----------------------------------------------------------------------
+
+REMOTE_RELEASE = r'''set -euo pipefail
+RELEASE_ROOT=__ROOT__
+RELEASE_NAME=__NAME__
+ENV_FILE=__ENV__
+REL="$RELEASE_ROOT/releases/$RELEASE_NAME"
+CURRENT="$RELEASE_ROOT/current"
+KEEP=__KEEP__
+say() { printf '{"step":"%s","detail":"%s"}\n' "$1" "${2:-}"; }
+[ "$(id -u)" != 0 ] || { say refused "do not release as root: builds as root leave root-owned files the prune cannot remove"; exit 4; }
+[ -d "$REL" ] || { say refused "release folder missing"; exit 4; }
+[ -r "$ENV_FILE" ] || { say refused "the deploy user cannot read $ENV_FILE; make it group-readable by the deploy group (chgrp deploy, chmod 640) instead of building with sudo"; exit 4; }
+PREVIOUS="$(readlink -f "$CURRENT" 2>/dev/null || true)"
+cd "$REL"
+( set -a; . "$ENV_FILE"; set +a; __INSTALL__ ) >"$REL/.maggie-install.log" 2>&1 || { say failed "install (see $REL/.maggie-install.log)"; exit 5; }
+say installed
+( set -a; . "$ENV_FILE"; set +a; __BUILD__ ) >"$REL/.maggie-build.log" 2>&1 || { say failed "build (see $REL/.maggie-build.log)"; exit 5; }
+say built
+FOREIGN="$(find "$REL" ! -user "$(id -un)" -print -quit 2>/dev/null || true)"
+[ -z "$FOREIGN" ] || { say failed "files not owned by $(id -un) appeared in the release ($FOREIGN)"; exit 5; }
+ln -sfn "$REL" "$RELEASE_ROOT/.current.tmp" && mv -T "$RELEASE_ROOT/.current.tmp" "$CURRENT"
+say switched "$RELEASE_NAME"
+__RESTART__ || { say failed "restart; current points at the new release, roll back with: ln -sfn $PREVIOUS $CURRENT"; exit 6; }
+say restarted
+__HEALTH__
+pruned=0; blocked=""
+for candidate in $(ls -1dt "$RELEASE_ROOT"/releases/*/ 2>/dev/null | sed 's:/$::' | tail -n +$((KEEP + 1))); do
+  [ "$candidate" = "$REL" ] && continue
+  [ "$KEEP" -ge 2 ] && [ "$candidate" = "$PREVIOUS" ] && continue
+  if [ -n "$(find "$candidate" ! -user "$(id -un)" -print -quit 2>/dev/null)" ]; then blocked="$blocked $(basename "$candidate")"; continue; fi
+  rm -rf -- "$candidate"; pruned=$((pruned + 1))
+done
+say pruned "$pruned"
+[ -z "$blocked" ] || say prune-blocked "root-owned files from an earlier sudo build in:$blocked — one-time fix: sudo chown -R $(id -un): $RELEASE_ROOT/releases/<name>"
+'''
+
+HEALTH_SNIPPET = r'''for url in __URLS__; do
+  ok=""
+  for attempt in $(seq 1 30); do
+    status="$(curl -s -o /dev/null -w '%{http_code}' "$url" || printf 000)"
+    case "$status" in 2??|3??) ok=1; break ;; 000|502|503|504) sleep 2 ;; *) break ;; esac
+  done
+  [ -n "$ok" ] || { say failed "health $url returned $status; roll back with: ln -sfn $PREVIOUS $CURRENT and restart"; exit 7; }
+  for warm in $(seq 1 __WARM__); do curl -s -o /dev/null "$url" || true; done
+  ms="$(curl -s -o /dev/null -w '%{time_total}' "$url" || printf 0)"
+  say healthy "$url ${ms}s after __WARM__ warm-up request(s)"
+done
+'''
+
+
+def release_name(repo: Path, ref: str, now: datetime | None = None) -> tuple[str, str]:
+    sha = subprocess.run(["git", "-C", str(repo), "rev-parse", "--short=10", f"{ref}^{{commit}}"], capture_output=True, text=True, check=False)
+    if sha.returncode:
+        raise ValueError(f"{ref} is not a commit in {repo}")
+    stamp = (now or datetime.now(timezone.utc)).strftime("%Y%m%dT%H%M%SZ")
+    return f"{stamp}-{sha.stdout.strip()}", sha.stdout.strip()
+
+
+def remote_release_script(root: str, name: str, env_file: str, keep: int, install: str, build: str, restart: str, health_urls: list[str], warm: int) -> str:
+    health = HEALTH_SNIPPET.replace("__URLS__", " ".join(shlex.quote(u) for u in health_urls)).replace("__WARM__", str(int(warm))) if health_urls else 'say healthy "no --health-url given"\n'
+    return (REMOTE_RELEASE.replace("__ROOT__", shlex.quote(root)).replace("__NAME__", shlex.quote(name)).replace("__ENV__", shlex.quote(env_file))
+            .replace("__KEEP__", str(int(keep))).replace("__INSTALL__", install).replace("__BUILD__", build).replace("__RESTART__", restart).replace("__HEALTH__", health))
+
+
+def vps_release(args: argparse.Namespace, ssh_args: list[str]) -> dict:
+    repo = Path(args.repo).resolve()
+    if not SAFE_REF.match(args.ref) or args.ref.startswith("-"):
+        raise ValueError("--ref must be a git revision")
+    if not 1 <= args.keep <= 5:
+        raise ValueError("--keep must be 1-5")
+    name, sha = release_name(repo, args.ref)
+    restart = args.restart or f"sudo -n systemctl restart {shlex.quote(args.service)}"
+    script = remote_release_script(args.release_root, name, args.env_file, args.keep, args.install, args.build, restart, args.health_url, args.warm)
+    tree = f"{args.ref}:{args.subdir.strip('/')}" if args.subdir else args.ref
+    plan = {
+        "schemaVersion": "maggie-vps-release.v1",
+        "host": args.host, "release": name, "commit": sha, "releaseRoot": args.release_root,
+        "steps": [f"git archive {tree} → {args.release_root}/releases/{name}", f"install as the deploy user: {args.install}", f"build with {args.env_file}: {args.build}",
+                  "refuse root-owned files", "switch current atomically", f"restart: {restart}", f"health {args.health_url or '-'} with {args.warm} warm-up request(s)", f"prune to {args.keep} release(s)"],
+        "executed": False,
+    }
+    if not args.confirm:
+        plan["remoteScript"] = script
+        plan["note"] = "dry run: nothing was uploaded; re-run with --confirm"
+        return plan
+    archive = subprocess.run(["git", "-C", str(repo), "archive", "--format=tar", tree], capture_output=True, check=False)
+    if archive.returncode:
+        raise ValueError(f"git archive {tree} failed")
+    target = f"{args.release_root.rstrip('/')}/releases/{name}"
+    unpack = f"set -e; test ! -e {shlex.quote(target)}; mkdir -p {shlex.quote(target)}; tar -x -C {shlex.quote(target)}"
+    uploaded = run_on(args.host, unpack, ssh_args, stdin=archive.stdout, timeout=600)
+    if uploaded.returncode:
+        raise ValueError(f"upload failed (exit {uploaded.returncode}): {uploaded.stderr.decode(errors='replace')[-300:]}")
+    result = run_on(args.host, script, ssh_args, timeout=args.timeout)
+    steps = []
+    for line in result.stdout.decode(errors="replace").splitlines():
+        try:
+            steps.append(json.loads(line))
+        except json.JSONDecodeError:
+            continue
+    plan.update(executed=True, exitCode=result.returncode, log=steps, status="released" if result.returncode == 0 else "failed")
+    if result.returncode == 0:
+        health = "; ".join(step["detail"] for step in steps if step["step"] == "healthy")
+        plan["roadmapLine"] = f"{datetime.now(timezone.utc).strftime('%Y-%m-%d %H:%M')} UTC — released {sha} as {name} on {args.host}; {health or 'no health URL'}; pruned {next((s['detail'] for s in steps if s['step'] == 'pruned'), '0')}"
+    else:
+        plan["stderr"] = result.stderr.decode(errors="replace")[-500:]
+    return plan
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="maggie deployment", description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    sub = parser.add_subparsers(dest="command", required=True)
+    cf = sub.add_parser("cloudflare-preflight")
+    cf.add_argument("--project", type=Path, default=Path("."))
+    cf.add_argument("--config", type=Path)
+    cf.add_argument("--env", dest="env_name", help="wrangler environment, e.g. production")
+    cf.add_argument("--env-file", type=Path, help="file the deploy script loads (names only are reported)")
+    cf.add_argument("--verify-zone", action="store_true", help="read-only Cloudflare API calls: token verify + zone lookup in the account")
+    ssh_parent = argparse.ArgumentParser(add_help=False)
+    ssh_parent.add_argument("--ssh-key")
+    ssh_parent.add_argument("--ssh-port", default="22")
+    fp = sub.add_parser("file-parity", parents=[ssh_parent])
+    fp.add_argument("--host", action="append", required=True, help="ssh target; repeat per host (\"local\" = this machine)")
+    fp.add_argument("--root", required=True, help="deployed folder on the hosts, e.g. /srv/api/current")
+    fp.add_argument("--path", action="append", required=True, help="file relative to --root that the deploy will copy")
+    fp.add_argument("--repo", default=".")
+    fp.add_argument("--subdir", default="", help="folder in the repo that maps to --root")
+    fp.add_argument("--ref", default="HEAD", help="commit currently deployed (the copies the hosts should hold)")
+    wc = sub.add_parser("warm-check")
+    wc.add_argument("--url", action="append", required=True)
+    wc.add_argument("--warm", type=int, default=3, help="warm-up requests per URL (one per worker process)")
+    wc.add_argument("--samples", type=int, default=5)
+    wc.add_argument("--budget-ms", type=float, default=0)
+    vr = sub.add_parser("vps-release", parents=[ssh_parent])
+    vr.add_argument("--host", required=True, help="deploy user's ssh target (never root)")
+    vr.add_argument("--release-root", required=True)
+    vr.add_argument("--service", required=True)
+    vr.add_argument("--env-file", required=True, help="server env file, readable by the deploy user")
+    vr.add_argument("--repo", default=".")
+    vr.add_argument("--subdir", default="", help="app folder inside the repo")
+    vr.add_argument("--ref", default="HEAD")
+    vr.add_argument("--install", default="npm ci")
+    vr.add_argument("--build", default="npm run build")
+    vr.add_argument("--restart", help="default: sudo -n systemctl restart SERVICE")
+    vr.add_argument("--health-url", action="append", default=[])
+    vr.add_argument("--warm", type=int, default=3)
+    vr.add_argument("--keep", type=int, default=2)
+    vr.add_argument("--timeout", type=int, default=1800)
+    vr.add_argument("--confirm", action="store_true")
+    for command in (cf, fp, wc, vr):
+        command.add_argument("--output", type=Path)
+    args = parser.parse_args(argv)
+    ssh_args = []
+    if getattr(args, "ssh_key", None):
+        ssh_args += ["-i", os.path.expanduser(args.ssh_key)]
+    if getattr(args, "ssh_port", "22") != "22":
+        ssh_args += ["-p", args.ssh_port]
+    try:
+        if args.command == "cloudflare-preflight":
+            report = cloudflare_preflight(args.project.resolve(), args.config, args.env_name, args.env_file, args.verify_zone)
+            failed = report["status"] == "failed"
+        elif args.command == "file-parity":
+            report = file_parity(args.host, args.root, args.path, Path(args.repo).resolve(), args.ref, args.subdir, ssh_args)
+            failed = not report["passed"]
+        elif args.command == "warm-check":
+            report = warm_check(args.url, max(0, args.warm), max(1, args.samples), args.budget_ms)
+            failed = not report["passed"]
+        else:
+            report = vps_release(args, ssh_args)
+            failed = report.get("status") == "failed"
+    except (OSError, ValueError, subprocess.SubprocessError) as error:
+        print(f"BLOCKED: maggie deployment {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)
+    return 1 if failed else 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/bundled-tools/clis/maggie_design.py

@@ -208,7 +208,7 @@ APP_CAPABILITY_STATES = {
     "notifications": ["permission", "granted", "denied"],
     "media-library": ["permission", "granted", "denied", "empty"],
 }
-APP_PATTERNS = ("tabbed-modal", "editor-sheet-assistant", "usage-hero", "site-switcher")
+APP_PATTERNS = ("tabbed-modal", "editor-sheet-assistant", "usage-hero", "site-switcher", "background-job", "chat-composer", "hash-tabs", "right-drawer", "two-column-sheet", "screen-pager")
 
 
 def parse_app_capabilities(value: str | None) -> list[str]:
@@ -356,6 +356,7 @@ def app_surface_init(project: Path, route: str, auth_mode: str, force: bool, con
     for name in capabilities:
         if name != "camera":
             scenarios.append({"id": f"{name}-permission", "viewport": "mobile", "assertions": [f"{name} permission is explained before the system prompt", "denied permission leaves an actionable fallback"]})
+    scenarios.append({"id": "ios-safe-area", "viewport": "notched iPhone (device or simulator)", "assertions": ["header and Close sit below the status bar / Dynamic Island in every modal and sheet", "insets come from useSafeAreaInsets(), not SafeAreaView inside a modal (`maggie design safe-area-check`)", "web screenshots cannot prove this; record a device screenshot"]})
     for pattern in patterns:
         scenarios.append({"id": f"pattern-{pattern}", "viewport": "all", "assertions": APP_PATTERN_ACCEPTANCE[pattern]})
     if auth_mode != "none":
@@ -374,6 +375,12 @@ APP_PATTERN_ACCEPTANCE = {
     "editor-sheet-assistant": ["'Ask the assistant' turns the same sheet into a short contextual chat", "writes appear as an approval card; nothing changes until approved", "dismissing the chat restores the unsaved edit"],
     "usage-hero": ["plan name, used and remaining quota are visible without scrolling", "the over-limit state names the next action"],
     "site-switcher": ["favicon falls back to the site initial", "search appears from 5 sites", "the current site is marked and keyboard reachable"],
+    "background-job": ["start returns at once and the item shows a spinner on its preview", "the same action becomes Stop while the job runs", "starting another item asks 'Stop it and start this one?' (409 busy + replace)", "one toast when the job finishes or fails; reloading the page shows the running job", "a stale job expires and the item is usable again"],
+    "chat-composer": ["the empty composer is one line tall with the placeholder and buttons vertically centred", "it grows with the text up to a maximum and shrinks again when text is deleted", "send and attach buttons stay aligned to the last line"],
+    "hash-tabs": ["the active tab is in the URL hash and survives reload and back/forward", "a hidden panel is measured and paged only after its tab is shown", "no page scroll at 1536x687 or 390 px on any tab"],
+    "right-drawer": ["details and long forms open in a drawer from the right that owns its scroll", "Escape and the close button return focus to the opener", "the page behind does not scroll while the drawer is open"],
+    "two-column-sheet": ["a large modal shows sections in two columns from 1024 px and one column below", "a quick-nav lists the sections and scrolls the sheet to each", "the sheet body is the only scroll owner"],
+    "screen-pager": ["the page size fits the visible rows of the viewport", "it re-measures on resize and when its tab is shown", "it never pages data the server already pages"],
 }
 
 
@@ -1003,6 +1010,8 @@ commands:
   markup-check validate optional style attributes, content keys, and entities
   pressable-check flag pressables/buttons nested in another pressable (JSX/TSX)
   layer-check  flag unlayered CSS that overrides Tailwind v4 utilities
+  safe-area-check flag SafeAreaView inside iOS modal routes / RN Modal
+  textinput-check flag multiline TextInput without a height / grow-only auto-grow (RN Web)
   palette      generate or validate a semantic palette role contract
   verify       run automatable design-job steps and record evidence
   icon-glyph-check render icons and prove font load and glyph paint
@@ -1010,7 +1019,7 @@ commands:
   reference-ui, init, validate-ui, app-init, app-validate, rebrand, review
 """)
         return 0
-    if len(sys.argv) > 1 and sys.argv[1] in {"pressable-check", "layer-check"}:
+    if len(sys.argv) > 1 and sys.argv[1] in {"pressable-check", "layer-check", "safe-area-check", "textinput-check"}:
         from maggie_design_lint import main as lint_main
         return lint_main(sys.argv[1:])
     if len(sys.argv) > 1 and sys.argv[1] == "verify":