fraser-gate 0.1.0__py3-none-any.whl

fraser_gate/__init__.py

@@ -0,0 +1,12 @@
+"""FRASER Experience Merge-Gate client — MCP server + CLI for AI coding agents.
+
+A thin, dependency-light client for the hosted FRASER API: point a persona swarm at a build, read
+grounded machine-readable experience findings, ship a fix, and re-run the identical cast to gate the
+fix pass/fail. FRASER is the loop's brain and eyes; it never writes or merges your code.
+"""
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("fraser-gate")
+except PackageNotFoundError:  # running from a source checkout, not an installed dist
+    __version__ = "0.0.0+source"

fraser_gate/cli.py

@@ -0,0 +1,181 @@
+#!/usr/bin/env python3
+"""fraser — thin CLI for the FRASER Experience Merge-Gate.
+
+A machine caller (CI, a coding agent, a person) runs FRASER's persona swarm against a DEPLOYED
+preview URL and reads back grounded, machine-readable experience findings. Talks the FRASER HTTP API
+with a bearer token — imports nothing from the backend, no third-party deps (stdlib only), so a CI
+can `python gate_client/cli.py ...` with just Python.
+
+Env:
+  FRASER_API_KEY   required — your FRASER MCP/API token (Settings -> Connect MCP -> Generate token)
+  FRASER_API_URL   base URL (default http://localhost:8000)
+
+Commands:
+  fraser review <url> [--mode visual|battle] [--objective TEXT] [--auth-notes TEXT] [--wait]
+  fraser status  <run_id>
+  fraser findings <run_id>
+  fraser validate <project_id> <flow_id> <baseline_run_id> <new_url> [--wait]   # Phase 2
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+import time
+import urllib.error
+import urllib.request
+
+# accept either naming — the dashboard "Generate MCP token" flow emits FRASER_BASE_URL/FRASER_API_TOKEN
+API = (os.environ.get("FRASER_API_URL") or os.environ.get("FRASER_BASE_URL") or "http://localhost:8000").rstrip("/")
+KEY = os.environ.get("FRASER_API_KEY") or os.environ.get("FRASER_API_TOKEN") or ""
+TERMINAL = ("complete", "failed", "cancelled", "timed_out")
+
+
+def _req(method: str, path: str, body: dict | None = None) -> tuple[int, dict]:
+    data = json.dumps(body).encode() if body is not None else None
+    req = urllib.request.Request(
+        API + path, data=data, method=method,
+        headers={"Authorization": f"Bearer {KEY}", "Content-Type": "application/json"})
+    try:
+        with urllib.request.urlopen(req, timeout=120) as r:
+            return r.status, json.loads(r.read().decode() or "{}")
+    except urllib.error.HTTPError as e:
+        try:
+            return e.code, json.loads(e.read().decode() or "{}")
+        except Exception:  # noqa: BLE001
+            return e.code, {"detail": e.reason}
+    except urllib.error.URLError as e:
+        _die(f"cannot reach {API} ({e.reason}); is the server running / FRASER_API_URL right?")
+
+
+def _die(msg: str, code: int = 1):
+    print(f"error: {msg}", file=sys.stderr)
+    sys.exit(code)
+
+
+def _need_key():
+    if not KEY:
+        _die("set FRASER_API_KEY (your FRASER API token)")
+
+
+def _poll_until_done(run_id: str, poll_ms: int) -> dict:
+    """Poll status to a terminal state, printing progress to stderr (so stdout stays clean JSON)."""
+    delay = max(1.0, min(poll_ms / 1000.0, 10.0))
+    while True:
+        time.sleep(delay)
+        st, s = _req("GET", f"/api/runs/{run_id}/status")
+        if st != 200:
+            _die(f"status failed ({st}): {s.get('detail')}")
+        p = s.get("progress", {})
+        print(f"  [{s.get('status')}] testers {p.get('personas_done')}/{p.get('total')} "
+              f"· findings {s.get('finding_count')} · goal {s.get('goal_outcome')}", file=sys.stderr)
+        if s.get("status") in TERMINAL:
+            return s
+
+
+def cmd_review(a):
+    _need_key()
+    body = {"target_url": a.url, "mode": a.mode}
+    if a.objective:
+        body["objective"] = a.objective
+    if a.context:
+        body["context"] = a.context
+    if a.testers:
+        body["num_testers"] = a.testers
+    if a.max_steps:
+        body["max_steps"] = a.max_steps
+    if a.auth_notes:
+        body["auth_notes"] = a.auth_notes
+        body["auth_mode"] = "credentials"
+    st, env = _req("POST", "/api/reviews", body)
+    if st != 200:
+        _die(f"review rejected ({st}): {env.get('detail')}")
+    if env.get("notice"):
+        print(f"note: {env['notice']}", file=sys.stderr)
+    if not a.wait:
+        # not waiting → the envelope IS the result (stdout); tell the user how to follow up
+        print(json.dumps(env, indent=2))
+        print(f"\npoll:   fraser status {env['run_id']}\nresult: fraser findings {env['run_id']}",
+              file=sys.stderr)
+        return
+    # waiting → keep stdout clean for the findings JSON; envelope + progress go to stderr
+    print(json.dumps(env), file=sys.stderr)
+    final = _poll_until_done(env["run_id"], env.get("poll_interval_ms", 5000))
+    if final.get("status") != "complete":
+        _die(f"run ended {final.get('status')}: {final.get('error', '')}", code=2)
+    st, f = _req("GET", f"/api/reviews/{env['run_id']}/findings")
+    print(json.dumps(f, indent=2))
+
+
+def cmd_status(a):
+    _need_key()
+    st, s = _req("GET", f"/api/runs/{a.run_id}/status")
+    print(json.dumps(s, indent=2))
+    sys.exit(0 if st == 200 else 1)
+
+
+def cmd_findings(a):
+    _need_key()
+    st, f = _req("GET", f"/api/reviews/{a.run_id}/findings")
+    print(json.dumps(f, indent=2))
+    sys.exit(0 if st == 200 else 1)
+
+
+def cmd_validate(a):
+    _need_key()
+    body = {"flow_id": a.flow_id, "baseline_run_id": a.baseline_run_id, "target_url": a.new_url}
+    st, env = _req("POST", f"/api/projects/{a.project_id}/validate", body)
+    if st != 200:
+        _die(f"validate rejected ({st}): {env.get('detail')}")
+    if not a.wait:
+        print(json.dumps(env, indent=2))
+        return
+    print(json.dumps(env), file=sys.stderr)     # keep stdout clean for the verdict JSON
+    _poll_until_done(env["run_id"], env.get("poll_interval_ms", 5000))
+    st, v = _req("GET", f"/api/runs/{env['run_id']}/validation?baseline={a.baseline_run_id}")
+    print(json.dumps(v, indent=2))
+    print(f"gate: {v.get('gate')}", file=sys.stderr)
+    sys.exit(0 if v.get("gate") == "pass" else 3)   # non-zero exit on a FAIL gate → CI blocks the merge
+
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(prog="fraser", description="FRASER Experience Merge-Gate CLI")
+    sub = p.add_subparsers(dest="cmd", required=True)
+
+    r = sub.add_parser("review", help="start a persona review of a deployed URL")
+    r.add_argument("url")
+    r.add_argument("--mode", default="visual", choices=["visual", "battle"])
+    r.add_argument("--objective", default="")
+    r.add_argument("--context", default="", help="product background shared with every tester")
+    r.add_argument("--testers", type=int, default=0, help="number of persona testers (0 = default cast)")
+    r.add_argument("--max-steps", dest="max_steps", type=int, default=0, help="per-tester move budget")
+    r.add_argument("--auth-notes", dest="auth_notes", default="", help="app login creds (SECRET)")
+    r.add_argument("--wait", action="store_true", help="block until done, then print findings")
+    r.set_defaults(fn=cmd_review)
+
+    s = sub.add_parser("status", help="poll a run's async status")
+    s.add_argument("run_id")
+    s.set_defaults(fn=cmd_status)
+
+    fi = sub.add_parser("findings", help="the scrubbed machine findings for a run")
+    fi.add_argument("run_id")
+    fi.set_defaults(fn=cmd_findings)
+
+    v = sub.add_parser("validate", help="re-run the identical cast and gate the fix (Phase 2)")
+    v.add_argument("project_id")
+    v.add_argument("flow_id")
+    v.add_argument("baseline_run_id")
+    v.add_argument("new_url")
+    v.add_argument("--wait", action="store_true")
+    v.set_defaults(fn=cmd_validate)
+    return p
+
+
+def main(argv=None):
+    a = build_parser().parse_args(argv)
+    a.fn(a)
+
+
+if __name__ == "__main__":
+    main()

fraser_gate/mcp_server.py

@@ -0,0 +1,185 @@
+"""FRASER Experience Merge-Gate — MCP server (the primary distribution surface, §6.1).
+
+Six tools a coding agent (Claude Code, Cursor, Copilot, …) uses to run FRASER's persona swarm against
+a deployed preview URL — or its OWN localhost — read grounded, machine-readable experience findings,
+ship a fix, and re-validate to a PASS/FAIL merge-gate. This is a THIN local process: it runs on the
+agent's machine (stdio), holds the FRASER API token, and proxies the hosted HTTP API. Its one piece of
+real magic is the localhost tunnel (frictionless: the agent points at localhost:3000 and this opens an
+ephemeral public tunnel so the hosted engine can reach it — no setup).
+
+Run:  FRASER_API_KEY=<token> FRASER_API_URL=<https://fraser.lythe.ai> uvx --from . fraser-gate-mcp
+.mcp.json:  {"mcpServers":{"fraser":{"type":"stdio","command":"...","env":{"FRASER_API_KEY":"..."}}}}
+"""
+from __future__ import annotations
+
+import asyncio
+import os
+
+import httpx
+from mcp.server.fastmcp import FastMCP
+
+try:
+    from .tunnel import Tunnel, is_local_url, open_tunnel
+except ImportError:  # run as a plain script (not a package)
+    from tunnel import Tunnel, is_local_url, open_tunnel
+
+# accept either naming — the dashboard "Generate MCP token" flow emits FRASER_BASE_URL/FRASER_API_TOKEN
+API = (os.environ.get("FRASER_API_URL") or os.environ.get("FRASER_BASE_URL") or "http://localhost:8000").rstrip("/")
+KEY = os.environ.get("FRASER_API_KEY") or os.environ.get("FRASER_API_TOKEN") or ""
+TERMINAL = ("complete", "failed", "cancelled", "timed_out")
+
+mcp = FastMCP("fraser-gate")
+_tunnels: dict[str, Tunnel] = {}   # run_id -> live localhost tunnel, closed when the run finishes
+
+
+async def _req(method: str, path: str, body: dict | None = None) -> tuple[int, dict]:
+    if not KEY:
+        return 0, {"detail": "set FRASER_API_KEY to your FRASER API token"}
+    try:
+        async with httpx.AsyncClient(timeout=120) as c:
+            r = await c.request(method, API + path, json=body,
+                                headers={"Authorization": f"Bearer {KEY}"})
+    except Exception as e:  # noqa: BLE001
+        return 0, {"detail": f"cannot reach FRASER at {API}: {e}"}
+    try:
+        return r.status_code, r.json()
+    except Exception:  # noqa: BLE001
+        return r.status_code, {"detail": r.text[:400]}
+
+
+def _close_tunnel(run_id: str) -> None:
+    t = _tunnels.pop(run_id, None)
+    if t:
+        t.close()
+
+
+async def _start_tunnel_if_local(target_url: str) -> tuple[str, Tunnel | None]:
+    if is_local_url(target_url):
+        tun = await asyncio.to_thread(open_tunnel, target_url)
+        return tun.public_url, tun
+    return target_url, None
+
+
+@mcp.tool()
+async def fraser_start_review(target_url: str, mode: str = "visual", objective: str = "",
+                              context: str = "", num_testers: int = 0, auth_notes: str = "",
+                              auth_mode: str = "") -> dict:
+    """Start a persona EXPERIENCE review of a deployed preview URL (or your localhost). Returns a job
+    envelope immediately — this is ASYNC and SLOW: FRASER first generates ICP personas from your app,
+    then drives a real browser as each one, which takes SEVERAL MINUTES. Do NOT wait inline; poll
+    fraser_get_status(run_id) every ~5s until status is terminal, then fraser_get_findings(run_id).
+
+    localhost is handled for you: if target_url is on your machine (localhost / 127.0.0.1 / a private
+    IP), this opens an ephemeral public tunnel automatically so the hosted engine can reach it — you
+    set nothing up. The tunnel closes when the run finishes.
+
+    Knobs (defaults are good — override only with a reason):
+      mode: 'visual' = experience/design-friction critique (DEFAULT, what you usually want);
+            'battle' = an adversarial functional defect sweep (pure bug-hunting).
+      num_testers: 0 = the grounded ICP cast (recommended). 2–3 for a fast pass; capped by your plan.
+      context: one line on what the product IS — anchors the personas when the app is new/thin.
+      objective: the specific task to exercise, e.g. 'sign up and create your first project'.
+      auth_notes: app login credentials if it's behind your own login (SECRET — never echoed/logged);
+                  auth_mode defaults to 'credentials' when you pass this.
+    Cost: ~1 simulation credit; estimated_cost_cents is in the envelope.
+    """
+    url, tunnel = await _start_tunnel_if_local(target_url)
+    body: dict = {"target_url": url, "mode": mode, "origin": "mcp"}
+    if objective:
+        body["objective"] = objective
+    if context:
+        body["context"] = context
+    if num_testers:
+        body["num_testers"] = num_testers
+    if auth_notes:
+        body["auth_notes"] = auth_notes
+        body["auth_mode"] = auth_mode or "credentials"
+    st, env = await _req("POST", "/api/reviews", body)
+    if st != 200:
+        if tunnel:
+            tunnel.close()
+        return {"error": env.get("detail", "review failed"), "status_code": st}
+    if tunnel:
+        _tunnels[env["run_id"]] = tunnel      # keep the tunnel up until the run is terminal
+        env["tunneled_from"] = target_url
+    return env
+
+
+@mcp.tool()
+async def fraser_get_status(run_id: str) -> dict:
+    """Poll a review/validate job (cheap). Returns status (queued|running|complete|failed|cancelled|
+    timed_out), progress {personas_done,total,step}, and finding_count. A run takes minutes — poll
+    every ~5s. When it reads complete, call fraser_get_findings (review) or fraser_get_validation via
+    fraser_validate_fix's follow-up. 'failed' = the app broke the tester; 'timed_out' = retry-able."""
+    _, s = await _req("GET", f"/api/runs/{run_id}/status")
+    if s.get("status") in TERMINAL:
+        _close_tunnel(run_id)     # engine is done with the localhost tunnel
+    return s
+
+
+@mcp.tool()
+async def fraser_get_findings(run_id: str) -> dict:
+    """The scrubbed, machine-readable findings for a COMPLETE review — each with a stable finding_id
+    (map fix→verify on it), defect_class, severity, the exact reproduction path, a screenshot_url, and
+    a non-authoritative fix_hint; plus a run-level fix_prompt (a deterministic brief). Known
+    false-positives are already withheld. YOU (the agent) fix from these — FRASER never edits code.
+    Then redeploy and call fraser_validate_fix to gate the fix."""
+    st, f = await _req("GET", f"/api/reviews/{run_id}/findings")
+    if st != 200:
+        return {"error": f.get("detail", "findings unavailable"), "status_code": st}
+    return f
+
+
+@mcp.tool()
+async def fraser_validate_fix(project_id: str, flow_id: str, baseline_run_id: str,
+                              target_url: str, with_control: bool = True) -> dict:
+    """After you ship a fix, re-run the IDENTICAL persona cast against the fixed deploy and gate it.
+    ASYNC + SLOW like a review — returns a job envelope; poll fraser_get_status(run_id) to terminal,
+    then read the verdict with fraser_get_validation(run_id, baseline_run_id).
+
+    MUST pass the SAME project_id + flow_id + baseline_run_id from the original review (never start a
+    fresh review for validation — that breaks the cast + the diff). localhost is tunneled for you.
+    with_control=True also runs a paired no-change control for the noise floor (costs 1 more credit);
+    set False to save a credit at lower confidence."""
+    url, tunnel = await _start_tunnel_if_local(target_url)
+    body = {"flow_id": flow_id, "baseline_run_id": baseline_run_id, "target_url": url,
+            "with_control": with_control, "origin": "mcp"}
+    st, env = await _req("POST", f"/api/projects/{project_id}/validate", body)
+    if st != 200:
+        if tunnel:
+            tunnel.close()
+        return {"error": env.get("detail", "validate failed"), "status_code": st}
+    if tunnel:
+        _tunnels[env["run_id"]] = tunnel
+        env["tunneled_from"] = target_url
+    env["read_verdict_with"] = f"fraser_get_validation(run_id='{env['run_id']}', baseline_run_id='{baseline_run_id}')"
+    return env
+
+
+@mcp.tool()
+async def fraser_get_validation(run_id: str, baseline_run_id: str) -> dict:
+    """The PASS/FAIL merge-gate verdict for a COMPLETE validate run vs its baseline: gate=pass|fail,
+    each prior finding classified {fixed|still_present|regressed}, plus any new_findings the fix
+    introduced. gate='fail' means the EXPERIENCE is still broken even if your build/tests are green —
+    do not merge. This is the whole point: a build can pass its own self-test and still fail a user."""
+    st, v = await _req("GET", f"/api/runs/{run_id}/validation?baseline={baseline_run_id}")
+    if st != 200:
+        return {"error": v.get("detail", "validation unavailable"), "status_code": st}
+    return v
+
+
+@mcp.tool()
+async def fraser_cancel(run_id: str) -> dict:
+    """Stop a running review/validate (keeps whatever partial findings it gathered) and tear down its
+    localhost tunnel."""
+    st, r = await _req("POST", f"/api/runs/{run_id}/control", {"action": "stop"})
+    _close_tunnel(run_id)
+    return r if st == 200 else {"error": r.get("detail", "cancel failed"), "status_code": st}
+
+
+def main() -> None:
+    mcp.run()
+
+
+if __name__ == "__main__":
+    main()

fraser_gate/tunnel.py

@@ -0,0 +1,132 @@
+"""Frictionless localhost exposure for the MCP server.
+
+The hardest part of the loop: a HOSTED FRASER engine can't reach the coding agent's `localhost:3000`.
+The agent shouldn't have to think about this. So when a review targets a localhost / private URL, the
+LOCAL MCP process (which runs on the agent's own machine) opens an ephemeral Cloudflare Quick Tunnel
+(`*.trycloudflare.com`, no account, dies with the process) and hands the hosted engine that public URL.
+
+cloudflared is a single binary; if it isn't on PATH we download it once to a cache and reuse it. The
+client does nothing but say "review my localhost app" — the tunnel is invisible. FRASER hosts no
+tunnel and stays read-only-over-HTTPS (§6.4).
+"""
+from __future__ import annotations
+
+import ipaddress
+import os
+import pathlib
+import platform
+import re
+import stat
+import subprocess
+import threading
+import time
+import urllib.parse
+import urllib.request
+
+_CACHE = pathlib.Path(os.path.expanduser("~")) / ".fraser" / "bin"
+_TRYCF = re.compile(r"https://[-a-z0-9]+\.trycloudflare\.com")
+
+
+def is_local_url(url: str) -> bool:
+    """True if the URL points at the caller's own machine / a private network the hosted engine can't
+    reach directly (so it needs a tunnel)."""
+    host = (urllib.parse.urlparse(url).hostname or "").lower()
+    if host in ("localhost", "127.0.0.1", "::1", "0.0.0.0") or host.endswith(".local"):
+        return True
+    try:
+        return ipaddress.ip_address(host).is_private
+    except ValueError:
+        return False
+
+
+def _asset() -> tuple[str, str]:
+    """(download URL, binary filename) for this OS/arch."""
+    sysname = platform.system().lower()
+    arch = "amd64" if platform.machine().lower() in ("x86_64", "amd64") else "arm64"
+    base = "https://github.com/cloudflare/cloudflared/releases/latest/download/"
+    if sysname == "windows":
+        return base + f"cloudflared-windows-{arch}.exe", "cloudflared.exe"
+    if sysname == "darwin":
+        return base + f"cloudflared-darwin-{arch}.tgz", "cloudflared"  # tgz — extracted below
+    return base + f"cloudflared-linux-{arch}", "cloudflared"
+
+
+def ensure_cloudflared() -> str:
+    """Path to a usable cloudflared, downloading it once into ~/.fraser/bin if needed."""
+    from shutil import which
+    found = which("cloudflared")
+    if found:
+        return found
+    _CACHE.mkdir(parents=True, exist_ok=True)
+    url, fname = _asset()
+    dest = _CACHE / fname
+    if dest.exists():
+        return str(dest)
+    tmp = dest.with_suffix(dest.suffix + ".part")
+    urllib.request.urlretrieve(url, tmp)  # noqa: S310 — pinned to the official cloudflare release host
+    if url.endswith(".tgz"):
+        import tarfile
+        with tarfile.open(tmp) as t:
+            member = next(m for m in t.getmembers() if m.name.endswith("cloudflared"))
+            with t.extractfile(member) as src, open(dest, "wb") as out:
+                out.write(src.read())
+        tmp.unlink(missing_ok=True)
+    else:
+        tmp.replace(dest)
+    dest.chmod(dest.stat().st_mode | stat.S_IEXEC | stat.S_IRWXU)
+    return str(dest)
+
+
+class Tunnel:
+    """A live Quick Tunnel to a local URL. `public_url` is the https address to hand the engine."""
+
+    def __init__(self, local_url: str, public_url: str, proc: subprocess.Popen):
+        self.local_url = local_url
+        self.public_url = public_url
+        self._proc = proc
+
+    def close(self) -> None:
+        try:
+            self._proc.terminate()
+            self._proc.wait(timeout=10)
+        except Exception:  # noqa: BLE001
+            try:
+                self._proc.kill()
+            except Exception:  # noqa: BLE001
+                pass
+
+
+def open_tunnel(local_url: str, *, timeout: float = 30.0) -> Tunnel:
+    """Start a cloudflared Quick Tunnel to `local_url` and return a Tunnel once the public URL is up.
+    Raises TimeoutError if the URL doesn't appear in time."""
+    exe = ensure_cloudflared()
+    proc = subprocess.Popen(
+        [exe, "tunnel", "--url", local_url, "--no-autoupdate"],
+        stdout=subprocess.PIPE, stderr=subprocess.STDOUT, text=True, bufsize=1)
+    url_box: list[str] = []
+
+    def _scan():
+        for line in proc.stdout:  # type: ignore[union-attr]
+            m = _TRYCF.search(line)
+            if m:
+                url_box.append(m.group(0))
+                break
+
+    t = threading.Thread(target=_scan, daemon=True)
+    t.start()
+    deadline = time.monotonic() + timeout
+    while time.monotonic() < deadline:
+        if url_box:
+            return Tunnel(local_url, url_box[0], proc)
+        if proc.poll() is not None:
+            raise RuntimeError("cloudflared exited before a tunnel URL appeared")
+        time.sleep(0.2)
+    proc.terminate()
+    raise TimeoutError("timed out waiting for the cloudflared tunnel URL")
+
+
+if __name__ == "__main__":  # tiny self-check: fraser tunnel demo (expects something serving :5050)
+    tun = open_tunnel("http://127.0.0.1:5050")
+    print("public:", tun.public_url)
+    time.sleep(2)
+    tun.close()

fraser_gate-0.1.0.dist-info/METADATA

@@ -0,0 +1,97 @@
+Metadata-Version: 2.4
+Name: fraser-gate
+Version: 0.1.0
+Summary: MCP server + CLI that lets an AI coding agent run FRASER's persona swarm against a build and gate the fix pass/fail
+Project-URL: Homepage, https://fraser.lythe.ai
+Author-email: Lythe <team@lythe.ai>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai-agents,code-review,coding-agent,experience,fraser,mcp,merge-gate,model-context-protocol,qa,testing
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Requires-Dist: mcp>=1.2.0
+Description-Content-Type: text/markdown
+
+# FRASER Experience Merge-Gate — for AI coding agents
+
+Point FRASER's persona swarm at a build, get back grounded, machine-readable **experience** findings,
+ship a fix, then re-run the **identical** cast to gate the fix `pass | fail`. FRASER is the loop's
+**brain and eyes** — it finds where real users break and verifies the fix helped. It **never writes or
+merges your code**; your agent does that.
+
+Why this exists: a build can pass its own typecheck + unit tests and still have a user drop off. That
+gap — **experience ≠ correctness** — is what the gate catches.
+
+## The loop
+
+```
+your agent builds + deploys ─▶ fraser_start_review(target_url)   → {run_id, project_id, flow_id}
+                                     │  (async, minutes — poll)
+                              fraser_get_status(run_id) ─▶ complete
+                              fraser_get_findings(run_id)
+                                     │  → findings[] {finding_id, screenshot, reproduction, fix_hint} + fix_prompt
+   your agent fixes + redeploys ◀────┘   (FRASER never touches code)
+                                     ▼
+                              fraser_validate_fix(project_id, flow_id, baseline_run_id, new_url)
+                              fraser_get_validation(run_id, baseline_run_id)
+                                     │  → {gate: pass|fail, per-finding {fixed|still_present|regressed}, new_findings}
+                              gate=fail ⇒ don't merge · gate=pass ⇒ ship
+```
+
+## Setup (one paste)
+
+Get an API token from the FRASER dashboard (**Settings → Connect MCP → Generate token**), then add to
+your agent's `.mcp.json`:
+
+```jsonc
+{
+  "mcpServers": {
+    "fraser": {
+      "command": "uvx",
+      "args": ["--from", "fraser-gate", "fraser-gate-mcp"],
+      "env": { "FRASER_API_KEY": "<your token>", "FRASER_API_URL": "https://fraser.lythe.ai" }
+    }
+  }
+}
+```
+
+That's it. **localhost just works** — if you point a review at `http://localhost:3000`, the MCP opens
+an ephemeral public tunnel automatically so the hosted engine can reach your machine; you set nothing up.
+
+## Tools (6)
+
+| Tool | Use |
+|------|-----|
+| `fraser_start_review(target_url, mode?, objective?, context?, num_testers?, auth_notes?)` | Start a review. Async — returns a `run_id`. |
+| `fraser_get_status(run_id)` | Poll until terminal (`complete`/`failed`/`timed_out`). Runs take **minutes**. |
+| `fraser_get_findings(run_id)` | Scrubbed findings + `fix_prompt`. You fix from these. |
+| `fraser_validate_fix(project_id, flow_id, baseline_run_id, target_url)` | Re-run the identical cast on the fix. Async. |
+| `fraser_get_validation(run_id, baseline_run_id)` | The `pass`/`fail` gate verdict. |
+| `fraser_cancel(run_id)` | Stop a run. |
+
+**It takes minutes.** FRASER generates personas from your app, then drives a real browser as each one.
+Start the review, do other work, and poll `fraser_get_status` every few seconds.
+
+**Knobs** (defaults are good): `mode` = `visual` (experience critique, default) or `battle` (defect
+sweep); `num_testers` `0` = the grounded cast; `context` = one line on what the product is (anchors the
+personas for a new/thin app); `auth_notes` = app login creds if it's behind your own login (secret).
+
+## CLI (same loop, for CI without MCP)
+
+```bash
+export FRASER_API_KEY=<token> FRASER_API_URL=https://fraser.lythe.ai
+fraser review https://myapp-pr42.vercel.app --wait          # prints findings JSON
+fraser validate <project_id> <flow_id> <baseline_run_id> <new_url> --wait   # exits non-zero on a FAIL gate
+```
+
+Local dev of this package: `pip install -e .` then run `python mcp_server.py` (stdio) or `python cli.py`.

fraser_gate-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+fraser_gate/__init__.py,sha256=-GMbv-wp9NUuu8crB2PC9xYECie579rn59ekFZZX6mI,602
+fraser_gate/cli.py,sha256=koZJ4JCcpj1x7_MRp6WuZQeE4JWnUIROG96in7IRcmg,7429
+fraser_gate/mcp_server.py,sha256=TFnHhCPcydB_y_Pr6ebhycxdQdgfpZDUNRfkSCcAkpU,9367
+fraser_gate/tunnel.py,sha256=XlTXaWf8EfygbnRcK8Kxv9ZXcnQQ_ARpr3gRLrmPYnk,5127
+fraser_gate-0.1.0.dist-info/METADATA,sha256=kWb6lCQA-dfJgkW4mT7oHTgboKUezY81IOhYTvSQf_c,4716
+fraser_gate-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+fraser_gate-0.1.0.dist-info/entry_points.txt,sha256=3ElKJ1NRo2RREyXifQ28FS1wkKSAIZ_MsVR-7L_zCU8,99
+fraser_gate-0.1.0.dist-info/licenses/LICENSE,sha256=EQXLBOFxLucplu6CLqbf0wK6LS0DPXagRrsV_MwFZwU,1062
+fraser_gate-0.1.0.dist-info/RECORD,,

fraser_gate-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

fraser_gate-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+fraser-gate = fraser_gate.cli:main
+fraser-gate-mcp = fraser_gate.mcp_server:main

fraser_gate-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lythe
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.