wupbro 0.1.2__tar.gz

wupbro-0.1.2/PKG-INFO

@@ -0,0 +1,154 @@
+Metadata-Version: 2.4
+Name: wupbro
+Version: 0.1.2
+Summary: WUP Browser Dashboard — FastAPI backend for WUP regression watcher
+Author: WUP contributors
+Author-email: Tom Sapletta <tom@sapletta.com>
+License: Apache-2.0
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: fastapi>=0.110
+Requires-Dist: uvicorn[standard]>=0.27
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic>=2.0
+Requires-Dist: jinja2>=3.1
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Requires-Dist: httpx>=0.27; extra == "dev"
+Requires-Dist: goal>=2.1.0; extra == "dev"
+Requires-Dist: costs>=0.1.20; extra == "dev"
+Requires-Dist: pfix>=0.1.60; extra == "dev"
+
+# wupbro
+
+FastAPI backend + minimal HTML dashboard for the WUP regression watcher.
+
+## Architecture
+
+```
+┌──────────────────────┐   POST /events    ┌──────────────────────┐
+│  WUP agent (shell)   │ ───────────────▶  │  wupbro (FastAPI)   │
+│  - file watcher      │                   │  - /events (sink)    │
+│  - testql runner     │                   │  - /drivers/*        │
+│  - visual diff       │                   │  - /dashboard (UI)   │
+└──────────────────────┘                   └──────────────────────┘
+                                                      │
+                                                      ▼
+                                            ┌─────────────────┐
+                                            │ Browser UI      │
+                                            │ (auto-refresh)  │
+                                            └─────────────────┘
+```
+
+## Endpoints
+
+| Path                              | Method | Purpose                                     |
+|-----------------------------------|--------|---------------------------------------------|
+| `/events`                         | POST   | Receive event from a WUP agent              |
+| `/events`                         | GET    | List recent events (filter by type/service) |
+| `/events/stats`                   | GET    | Aggregate counts by type                    |
+| `/events`                         | DELETE | Clear store (admin/debug)                   |
+| `/drivers/dom-diff/capture`       | POST   | One-shot Playwright DOM snapshot + diff     |
+| `/drivers/browserless/screenshot` | POST   | Proxy to a `browserless/chrome` container   |
+| `/drivers/anomaly/report`         | POST   | Record numeric anomaly as ANOMALY event     |
+| `/drivers/health`                 | GET    | Driver capability discovery                 |
+| `/`, `/dashboard`                 | GET    | HTML dashboard                              |
+| `/healthz`                        | GET    | Liveness probe                              |
+| `/openapi.json`, `/docs`          | GET    | OpenAPI spec + Swagger UI                   |
+
+## Event types
+
+`REGRESSION`, `PASS`, `ANOMALY`, `VISUAL_DIFF`, `HEALTH_TRANSITION`.
+
+Schema (Pydantic):
+
+```json
+{
+  "type": "REGRESSION",
+  "service": "users-web",
+  "file": "app/users/routes.py",
+  "endpoint": "/api/users",
+  "status": "fail",
+  "stage": "quick",
+  "reason": "TestQL exit code 1",
+  "timestamp": 1730000000
+}
+```
+
+Extra fields are preserved via `model_config = {"extra": "allow"}`.
+
+## Run
+
+```bash
+# Install
+pip install -e wupbro/
+
+# Dev server (auto-reload)
+wupbro --reload --port 8000
+
+# Or directly
+uvicorn wupbro.main:app --host 0.0.0.0 --port 8000 --reload
+```
+
+Dashboard: <http://localhost:8000/>
+
+OpenAPI docs: <http://localhost:8000/docs>
+
+## Configure WUP agent to send events
+
+In your `wup.yaml`:
+
+```yaml
+web:
+  enabled: true
+  endpoint: "http://localhost:8000"
+  endpoint_env: "WUPBRO_ENDPOINT"   # fallback if endpoint is empty
+  timeout_s: 2.0                     # short — must not block watcher
+  api_key: ""                        # optional bearer token
+```
+
+Or via environment variable:
+
+```bash
+export WUPBRO_ENDPOINT=http://localhost:8000
+wup watch . --mode testql
+```
+
+The agent will POST events fire-and-forget on:
+
+- service health transitions (up ↔ down)
+- regressions (when TestQL fails)
+- visual DOM diffs (when significant changes detected)
+
+## Browserless integration
+
+```bash
+docker run -d --name browserless -p 3000:3000 browserless/chrome
+export BROWSERLESS_URL=http://localhost:3000
+wup-web
+```
+
+Then:
+
+```bash
+curl -X POST http://localhost:8000/drivers/browserless/screenshot \
+  -H "Content-Type: application/json" \
+  -d '{"url": "http://example.com", "full_page": true}'
+```
+
+## Storage
+
+Events are kept in an in-memory ring buffer (capacity 1000) and persisted to `.wupbro/events.jsonl` for restart durability.
+
+## Tests
+
+```bash
+PYTHONPATH=wupbro python3 -m pytest wupbro/tests/ -v
+```
+
+17 tests covering events router, drivers (anomaly, browserless, dom-diff, health), dashboard HTML, OpenAPI schema.
+
+## License
+
+Licensed under Apache-2.0.

wupbro-0.1.2/README.md

@@ -0,0 +1,132 @@
+# wupbro
+
+FastAPI backend + minimal HTML dashboard for the WUP regression watcher.
+
+## Architecture
+
+```
+┌──────────────────────┐   POST /events    ┌──────────────────────┐
+│  WUP agent (shell)   │ ───────────────▶  │  wupbro (FastAPI)   │
+│  - file watcher      │                   │  - /events (sink)    │
+│  - testql runner     │                   │  - /drivers/*        │
+│  - visual diff       │                   │  - /dashboard (UI)   │
+└──────────────────────┘                   └──────────────────────┘
+                                                      │
+                                                      ▼
+                                            ┌─────────────────┐
+                                            │ Browser UI      │
+                                            │ (auto-refresh)  │
+                                            └─────────────────┘
+```
+
+## Endpoints
+
+| Path                              | Method | Purpose                                     |
+|-----------------------------------|--------|---------------------------------------------|
+| `/events`                         | POST   | Receive event from a WUP agent              |
+| `/events`                         | GET    | List recent events (filter by type/service) |
+| `/events/stats`                   | GET    | Aggregate counts by type                    |
+| `/events`                         | DELETE | Clear store (admin/debug)                   |
+| `/drivers/dom-diff/capture`       | POST   | One-shot Playwright DOM snapshot + diff     |
+| `/drivers/browserless/screenshot` | POST   | Proxy to a `browserless/chrome` container   |
+| `/drivers/anomaly/report`         | POST   | Record numeric anomaly as ANOMALY event     |
+| `/drivers/health`                 | GET    | Driver capability discovery                 |
+| `/`, `/dashboard`                 | GET    | HTML dashboard                              |
+| `/healthz`                        | GET    | Liveness probe                              |
+| `/openapi.json`, `/docs`          | GET    | OpenAPI spec + Swagger UI                   |
+
+## Event types
+
+`REGRESSION`, `PASS`, `ANOMALY`, `VISUAL_DIFF`, `HEALTH_TRANSITION`.
+
+Schema (Pydantic):
+
+```json
+{
+  "type": "REGRESSION",
+  "service": "users-web",
+  "file": "app/users/routes.py",
+  "endpoint": "/api/users",
+  "status": "fail",
+  "stage": "quick",
+  "reason": "TestQL exit code 1",
+  "timestamp": 1730000000
+}
+```
+
+Extra fields are preserved via `model_config = {"extra": "allow"}`.
+
+## Run
+
+```bash
+# Install
+pip install -e wupbro/
+
+# Dev server (auto-reload)
+wupbro --reload --port 8000
+
+# Or directly
+uvicorn wupbro.main:app --host 0.0.0.0 --port 8000 --reload
+```
+
+Dashboard: <http://localhost:8000/>
+
+OpenAPI docs: <http://localhost:8000/docs>
+
+## Configure WUP agent to send events
+
+In your `wup.yaml`:
+
+```yaml
+web:
+  enabled: true
+  endpoint: "http://localhost:8000"
+  endpoint_env: "WUPBRO_ENDPOINT"   # fallback if endpoint is empty
+  timeout_s: 2.0                     # short — must not block watcher
+  api_key: ""                        # optional bearer token
+```
+
+Or via environment variable:
+
+```bash
+export WUPBRO_ENDPOINT=http://localhost:8000
+wup watch . --mode testql
+```
+
+The agent will POST events fire-and-forget on:
+
+- service health transitions (up ↔ down)
+- regressions (when TestQL fails)
+- visual DOM diffs (when significant changes detected)
+
+## Browserless integration
+
+```bash
+docker run -d --name browserless -p 3000:3000 browserless/chrome
+export BROWSERLESS_URL=http://localhost:3000
+wup-web
+```
+
+Then:
+
+```bash
+curl -X POST http://localhost:8000/drivers/browserless/screenshot \
+  -H "Content-Type: application/json" \
+  -d '{"url": "http://example.com", "full_page": true}'
+```
+
+## Storage
+
+Events are kept in an in-memory ring buffer (capacity 1000) and persisted to `.wupbro/events.jsonl` for restart durability.
+
+## Tests
+
+```bash
+PYTHONPATH=wupbro python3 -m pytest wupbro/tests/ -v
+```
+
+17 tests covering events router, drivers (anomaly, browserless, dom-diff, health), dashboard HTML, OpenAPI schema.
+
+## License
+
+Licensed under Apache-2.0.

wupbro-0.1.2/pyproject.toml

@@ -0,0 +1,74 @@
+[build-system]
+requires = ["setuptools>=61", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "wupbro"
+version = "0.1.2"
+description = "WUP Browser Dashboard — FastAPI backend for WUP regression watcher"
+readme = "README.md"
+requires-python = ">=3.9"
+authors = [{ name = "WUP contributors" }, {name = "Tom Sapletta",email = "tom@sapletta.com"}]
+dependencies = [
+    "fastapi>=0.110",
+    "uvicorn[standard]>=0.27",
+    "httpx>=0.27",
+    "pydantic>=2.0",
+    "jinja2>=3.1",
+]
+
+[project.license]
+text = "Apache-2.0"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8",
+    "pytest-asyncio>=0.23",
+    "httpx>=0.27",
+    "goal>=2.1.0",
+    "costs>=0.1.20",
+    "pfix>=0.1.60",
+]
+
+[project.scripts]
+wupbro = "wupbro.__main__:main"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["wupbro*"]
+
+[tool.setuptools.package-data]
+"wupbro" = ["templates/*.html", "static/*"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+
+[tool.pfix]
+# Self-healing Python configuration
+model = "openrouter/qwen/qwen3-coder-next"
+auto_apply = true
+auto_install_deps = true
+auto_restart = false
+max_retries = 3
+create_backups = false
+git_auto_commit = false
+
+[tool.pfix.runtime_todo]
+enabled = true
+todo_file = "TODO.md"
+min_severity = "low"
+deduplicate = true
+
+[tool.costs]
+# AI Cost tracking configuration
+badge = true
+update_readme = true
+readme_path = "README.md"
+default_model = "openrouter/qwen/qwen3-coder-next"
+analysis_mode = "byok"
+full_history = true
+max_commits = 500
+
+# Cost thresholds for badge colors (USD)
+badge_color_thresholds = { low = 1.0, medium = 5.0, high = 10.0, critical = 50.0 }

wupbro-0.1.2/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

wupbro-0.1.2/tests/test_dashboard.py

@@ -0,0 +1,35 @@
+"""Tests for the dashboard HTML and meta endpoints."""
+
+from __future__ import annotations
+
+
+def test_root_serves_dashboard(client):
+    resp = client.get("/")
+    assert resp.status_code == 200
+    assert resp.headers["content-type"].startswith("text/html")
+    assert "WUP Dashboard" in resp.text
+
+
+def test_dashboard_alias(client):
+    resp = client.get("/dashboard")
+    assert resp.status_code == 200
+    assert "WUP Dashboard" in resp.text
+
+
+def test_healthz(client):
+    resp = client.get("/healthz")
+    assert resp.status_code == 200
+    body = resp.json()
+    assert body["ok"] is True
+    assert "version" in body
+
+
+def test_openapi_schema_includes_routes(client):
+    resp = client.get("/openapi.json")
+    assert resp.status_code == 200
+    spec = resp.json()
+    paths = spec["paths"]
+    assert "/events" in paths
+    assert "/events/stats" in paths
+    assert "/drivers/anomaly/report" in paths
+    assert "/drivers/health" in paths

wupbro-0.1.2/tests/test_drivers.py

@@ -0,0 +1,50 @@
+"""Tests for /drivers/* router."""
+
+from __future__ import annotations
+
+
+def test_anomaly_report_creates_event(client):
+    resp = client.post("/drivers/anomaly/report", json={
+        "service": "billing",
+        "metric": "p95_latency",
+        "value": 1500.0,
+        "threshold": 1000.0,
+    })
+    assert resp.status_code == 201
+    assert resp.json()["accepted"] is True
+
+    events = client.get("/events").json()
+    assert events["total"] == 1
+    e = events["items"][0]
+    assert e["type"] == "ANOMALY"
+    assert e["service"] == "billing"
+    assert "p95_latency" in e["reason"]
+
+
+def test_driver_health_reports_capabilities(client):
+    resp = client.get("/drivers/health")
+    assert resp.status_code == 200
+    caps = resp.json()
+    assert caps["events"] is True
+    assert caps["anomaly"] is True
+    assert "dom_diff" in caps          # bool depending on wup install
+    assert "playwright" in caps        # bool depending on playwright install
+
+
+def test_browserless_unreachable_returns_503(client, monkeypatch):
+    monkeypatch.setenv("BROWSERLESS_URL", "http://127.0.0.1:1")  # closed port
+    resp = client.post("/drivers/browserless/screenshot", json={"url": "http://example.com"})
+    assert resp.status_code == 503
+
+
+def test_dom_diff_endpoint_exists(client):
+    """Endpoint accepts request payload (actual diff requires Playwright)."""
+    # Using a non-routable URL — VisualDiffer logs a warning and returns
+    # a result with status='error' but does NOT raise.
+    resp = client.post("/drivers/dom-diff/capture", json={
+        "url": "http://127.0.0.1:1/",
+        "service": "demo",
+        "max_depth": 3,
+    })
+    # Either 200 (gracefully degraded) or 503 (wup not installed). Both acceptable.
+    assert resp.status_code in (200, 503)

wupbro-0.1.2/tests/test_events.py

@@ -0,0 +1,95 @@
+"""Tests for /events router and EventStore."""
+
+from __future__ import annotations
+
+
+def test_post_event_accepted(client):
+    resp = client.post("/events", json={
+        "type": "REGRESSION",
+        "service": "users",
+        "file": "app/users/routes.py",
+        "endpoint": "/api/users",
+        "status": "fail",
+        "reason": "boom",
+    })
+    assert resp.status_code == 201
+    body = resp.json()
+    assert body["accepted"] is True
+    assert body["type"] == "REGRESSION"
+
+
+def test_post_event_invalid_type_rejected(client):
+    resp = client.post("/events", json={"type": "NOT_A_TYPE"})
+    assert resp.status_code == 422
+
+
+def test_list_events_returns_recent(client):
+    for i in range(3):
+        client.post("/events", json={"type": "PASS", "service": f"svc-{i}"})
+    resp = client.get("/events")
+    assert resp.status_code == 200
+    body = resp.json()
+    assert body["total"] == 3
+    services = [e["service"] for e in body["items"]]
+    # newest first
+    assert services == ["svc-2", "svc-1", "svc-0"]
+
+
+def test_list_events_filter_by_type(client):
+    client.post("/events", json={"type": "REGRESSION", "service": "a"})
+    client.post("/events", json={"type": "PASS", "service": "b"})
+    client.post("/events", json={"type": "REGRESSION", "service": "c"})
+
+    resp = client.get("/events?type=REGRESSION")
+    assert resp.status_code == 200
+    body = resp.json()
+    assert body["total"] == 2
+    assert all(e["type"] == "REGRESSION" for e in body["items"])
+
+
+def test_list_events_filter_by_service(client):
+    client.post("/events", json={"type": "PASS", "service": "users"})
+    client.post("/events", json={"type": "PASS", "service": "billing"})
+    resp = client.get("/events?service=users")
+    body = resp.json()
+    assert body["total"] == 1
+    assert body["items"][0]["service"] == "users"
+
+
+def test_list_events_limit(client):
+    for i in range(20):
+        client.post("/events", json={"type": "PASS", "service": f"s{i}"})
+    resp = client.get("/events?limit=5")
+    body = resp.json()
+    assert body["total"] == 5
+
+
+def test_event_stats(client):
+    client.post("/events", json={"type": "REGRESSION", "service": "x"})
+    client.post("/events", json={"type": "PASS", "service": "x"})
+    client.post("/events", json={"type": "PASS", "service": "y"})
+    resp = client.get("/events/stats")
+    assert resp.status_code == 200
+    stats = resp.json()
+    assert stats["total"] == 3
+    assert stats["by_type"]["REGRESSION"] == 1
+    assert stats["by_type"]["PASS"] == 2
+
+
+def test_clear_events(client):
+    client.post("/events", json={"type": "PASS", "service": "x"})
+    resp = client.delete("/events")
+    assert resp.status_code == 204
+    body = client.get("/events").json()
+    assert body["total"] == 0
+
+
+def test_event_extra_fields_preserved(client):
+    client.post("/events", json={
+        "type": "VISUAL_DIFF",
+        "service": "users",
+        "url": "http://localhost/users",
+        "diff": {"status": "changed", "counts": {"added": 5}},
+    })
+    body = client.get("/events").json()
+    assert body["items"][0]["diff"]["counts"]["added"] == 5

wupbro-0.1.2/wupbro/__init__.py

@@ -0,0 +1,7 @@
+"""WUP Browser Dashboard — FastAPI backend for WUP regression watcher."""
+
+__version__ = "0.1.2"
+
+from .main import create_app, app
+
+__all__ = ["create_app", "app", "__version__"]

wupbro-0.1.2/wupbro/__main__.py

@@ -0,0 +1,21 @@
+"""CLI entry-point: `python -m wupbro` or `wupbro`."""
+
+from __future__ import annotations
+
+import argparse
+import os
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(prog="wupbro", description="WUP Browser Dashboard")
+    parser.add_argument("--host", default=os.environ.get("WUPBRO_HOST", "0.0.0.0"))
+    parser.add_argument("--port", type=int, default=int(os.environ.get("WUPBRO_PORT", "8000")))
+    parser.add_argument("--reload", action="store_true", help="auto-reload (dev)")
+    args = parser.parse_args()
+
+    import uvicorn
+    uvicorn.run("wupbro.main:app", host=args.host, port=args.port, reload=args.reload)
+
+
+if __name__ == "__main__":
+    main()

wupbro-0.1.2/wupbro/main.py

@@ -0,0 +1,44 @@
+"""FastAPI entry-point for wupbro."""
+
+from __future__ import annotations
+
+from fastapi import FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+
+from . import __version__
+from .routers import dashboard, drivers, events
+
+
+def create_app() -> FastAPI:
+    app = FastAPI(
+        title="WUP Browser Dashboard",
+        version=__version__,
+        description=(
+            "Backend for the WUP regression watcher. Receives events from "
+            "WUP agents (REGRESSION, PASS, ANOMALY, VISUAL_DIFF, HEALTH_TRANSITION), "
+            "exposes drivers (DOM diff, browserless, anomaly), and serves a dashboard."
+        ),
+    )
+
+    # Permissive CORS — dashboard usually served from same origin, but agents
+    # may live elsewhere. Tighten in production.
+    app.add_middleware(
+        CORSMiddleware,
+        allow_origins=["*"],
+        allow_methods=["*"],
+        allow_headers=["*"],
+    )
+
+    app.include_router(events.router)
+    app.include_router(drivers.router)
+    app.include_router(dashboard.router)
+
+    @app.get("/healthz", tags=["meta"])
+    async def healthz():
+        return {"ok": True, "version": __version__}
+
+    return app
+
+
+# Module-level instance for `uvicorn wupbro.main:app`
+app = create_app()

wupbro-0.1.2/wupbro/models.py

@@ -0,0 +1,59 @@
+"""Pydantic models for wupbro events and driver requests."""
+
+from __future__ import annotations
+
+import time
+from typing import Any, Dict, List, Literal, Optional
+
+from pydantic import BaseModel, Field
+
+
+EventType = Literal[
+    "REGRESSION",
+    "PASS",
+    "ANOMALY",
+    "VISUAL_DIFF",
+    "HEALTH_TRANSITION",
+]
+
+
+class Event(BaseModel):
+    """Generic WUP event posted by an agent."""
+
+    type: EventType
+    service: Optional[str] = None
+    file: Optional[str] = None
+    endpoint: Optional[str] = None
+    url: Optional[str] = None
+    status: Optional[str] = None
+    stage: Optional[str] = None
+    reason: Optional[str] = None
+    diff: Optional[Dict[str, Any]] = None
+    timestamp: int = Field(default_factory=lambda: int(time.time()))
+
+    # Forward-compat: allow extra keys to land in `extra`
+    model_config = {"extra": "allow"}
+
+
+class EventList(BaseModel):
+    items: List[Event]
+    total: int
+
+
+class DomDiffRequest(BaseModel):
+    url: str
+    service: str = "default"
+    max_depth: int = 10
+
+
+class ScreenshotRequest(BaseModel):
+    url: str
+    full_page: bool = True
+
+
+class AnomalyReport(BaseModel):
+    service: str
+    metric: str
+    value: float
+    threshold: float
+    timestamp: int = Field(default_factory=lambda: int(time.time()))

wupbro-0.1.2/wupbro/routers/__init__.py

@@ -0,0 +1 @@
+"""Routers for wupbro."""