fleetwrit-server 0.0.1__py3-none-any.whl

fleetwrit_server/__init__.py

@@ -0,0 +1,5 @@
+"""Fleetwrit v0 local server (fleetwrit-server)."""
+
+from .app import app
+
+__all__ = ["app"]

fleetwrit_server/app.py

@@ -0,0 +1,169 @@
+"""Fleetwrit v0 local server (the `fleetwrit dev` path): FastAPI + SQLite.
+
+Implements the agent-facing /v1 API the SDK's HttpTransport calls, plus the
+dashboard-facing read/decide API. Auth is off (local/demo mode). Long-poll
+returns {"outcome":"pending"} when undecided so the SDK re-polls.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import os
+from pathlib import Path
+from typing import Any
+
+from fastapi import FastAPI, Request
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.responses import JSONResponse
+from fastapi.staticfiles import StaticFiles
+from starlette.exceptions import HTTPException as StarletteHTTPException
+
+from .store import Store
+from .seed import seed_demo
+
+store = Store(os.getenv("FLEETWRIT_DB", "fleetwrit-dev.db"))
+app = FastAPI(title="Fleetwrit dev server", version="0.1.0")
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["*"],
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+# Start empty by default — a local dev server is for your own data. Set
+# FLEETWRIT_SEED=1 (or `fleetwrit dev --demo`) to load the sample agents/requests.
+if os.getenv("FLEETWRIT_SEED", "0") == "1":
+    seed_demo(store)
+
+
+# --- agent-facing /v1 (key auth in prod; off in local mode) ----------------
+@app.post("/v1/agents/register")
+async def register(req: Request) -> dict[str, Any]:
+    body = await req.json()
+    store.register(body.get("agent", {}), body.get("action_types", []), body.get("runtime"))
+    return {"ok": True}
+
+
+@app.post("/v1/requests")
+async def create_request(req: Request) -> JSONResponse:
+    body = await req.json()
+    try:
+        return JSONResponse(store.create_request(body))
+    except ValueError as exc:
+        return JSONResponse({"error": str(exc)}, status_code=400)
+
+
+@app.get("/v1/requests/{rid}/decision")
+async def get_decision(rid: str, wait: int = 25) -> JSONResponse:
+    deadline = asyncio.get_event_loop().time() + min(max(wait, 0), 25)
+    while True:
+        d = store.decision(rid)
+        if d is None:
+            return JSONResponse({"error": "not found"}, status_code=404)
+        if d.get("outcome") != "pending":
+            return JSONResponse(d)
+        if asyncio.get_event_loop().time() >= deadline:
+            return JSONResponse({"outcome": "pending"})
+        await asyncio.sleep(0.4)
+
+
+@app.post("/v1/requests/{rid}/ack")
+async def ack(rid: str) -> JSONResponse:
+    try:
+        store.ack(rid)
+    except ValueError as exc:
+        return JSONResponse({"error": str(exc)}, status_code=409)
+    return JSONResponse({"ok": True})
+
+
+@app.post("/v1/requests/{rid}/cancel")
+async def cancel(rid: str) -> dict[str, Any]:
+    store.cancel(rid)
+    return {"ok": True}
+
+
+# --- dashboard-facing ------------------------------------------------------
+@app.get("/v1/overview")
+async def overview() -> dict[str, Any]:
+    return store.overview()
+
+
+@app.get("/v1/inbox")
+async def inbox() -> dict[str, Any]:
+    return {"requests": store.inbox()}
+
+
+@app.get("/v1/requests/{rid}")
+async def request_detail(rid: str) -> JSONResponse:
+    r = store.get_request(rid)
+    if not r:
+        return JSONResponse({"error": "not found"}, status_code=404)
+    return JSONResponse(r)
+
+
+@app.post("/v1/requests/{rid}/decide")
+async def decide(rid: str, req: Request) -> JSONResponse:
+    body = await req.json()
+    reviewer = body.get("reviewer") or {
+        "subject": "you@acme.com", "email": "you@acme.com",
+        "name": "You", "issuer": "https://fleetwrit.local",
+    }
+    try:
+        result = store.decide(rid, body.get("outcome", "approved"), body.get("edits"), body.get("reason"), reviewer, body.get("value"), body.get("option"))
+    except KeyError:
+        return JSONResponse({"error": "not found"}, status_code=404)
+    except ValueError as exc:
+        return JSONResponse({"error": str(exc)}, status_code=409)
+    return JSONResponse(result)
+
+
+@app.get("/v1/agents")
+async def agents() -> dict[str, Any]:
+    return {"agents": store.agents()}
+
+
+@app.get("/v1/action-types")
+async def action_types() -> dict[str, Any]:
+    return {"action_types": store.action_types()}
+
+
+@app.get("/v1/ledger")
+async def ledger() -> dict[str, Any]:
+    return {"events": store.ledger()}
+
+
+@app.get("/v1/ledger/verify")
+async def ledger_verify() -> dict[str, Any]:
+    return store.verify_chain()
+
+
+# --- operational -----------------------------------------------------------
+@app.get("/healthz")
+async def healthz() -> dict[str, Any]:
+    return {"ok": True}
+
+
+@app.get("/.well-known/jwks.json")
+async def jwks() -> dict[str, Any]:
+    return store.jwks()
+
+
+# --- bundled dashboard -----------------------------------------------------
+# When the built dashboard is packaged into ./static, serve it at / so the whole
+# app is one process on one port. Mounted last, so the API routes above win; a
+# 404 falls back to index.html for the SPA's client-side routes.
+_STATIC = Path(__file__).with_name("static")
+
+
+class _SPAStaticFiles(StaticFiles):
+    async def get_response(self, path: str, scope: Any) -> Any:
+        try:
+            return await super().get_response(path, scope)
+        except StarletteHTTPException as exc:
+            if exc.status_code == 404:
+                return await super().get_response("index.html", scope)
+            raise
+
+
+if (_STATIC / "index.html").is_file():
+    app.mount("/", _SPAStaticFiles(directory=str(_STATIC), html=True), name="dashboard")

fleetwrit_server/cli.py

@@ -0,0 +1,141 @@
+"""`fleetwrit-server` console entrypoint.
+
+Bare command runs the API with uvicorn (back-compat). `fleetwrit-server dev`
+also launches the dashboard, so the whole local stack comes up in one command.
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+import shutil
+import socket
+import subprocess
+import sys
+import time
+from pathlib import Path
+
+
+def _free_port(preferred: int, host: str = "127.0.0.1", tries: int = 20) -> int:
+    """Return the first bindable port at or after ``preferred`` (up to ``tries``)."""
+    for port in range(preferred, preferred + tries):
+        with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as probe:
+            try:
+                probe.bind((host, port))
+                return port
+            except OSError:
+                continue
+    raise RuntimeError(f"no free port in {preferred}..{preferred + tries - 1}")
+
+
+def _run_server_only(port: int) -> None:
+    import uvicorn
+
+    uvicorn.run("fleetwrit_server.app:app", host="127.0.0.1", port=port, reload=False)
+
+
+def _find_dashboard(start: str | None) -> Path | None:
+    """Look for a sibling ``dashboard/`` (with a package.json) from here upward."""
+    here = Path(start or os.getcwd()).resolve()
+    for base in (here, *here.parents):
+        candidate = base / "dashboard"
+        if (candidate / "package.json").is_file():
+            return candidate
+    return None
+
+
+def run_dev(
+    port: int = 4100,
+    dashboard_port: int = 5174,
+    dashboard: bool = True,
+    seed: bool = False,
+    path: str | None = None,
+) -> int:
+    """Start the server, and (if found) the dashboard, then wait for Ctrl-C."""
+    env = {**os.environ, "FLEETWRIT_SEED": "1" if seed else "0"}
+    procs: list[subprocess.Popen] = []
+
+    resolved = _free_port(port)
+    if resolved != port:
+        print(f"· port {port} is busy — using {resolved} instead", flush=True)
+        port = resolved
+
+    server = subprocess.Popen(
+        [sys.executable, "-m", "uvicorn", "fleetwrit_server.app:app",
+         "--host", "127.0.0.1", "--port", str(port)],
+        env=env,
+    )
+    procs.append(server)
+    print(f"→ server   http://localhost:{port}  (API, seeded demo data)", flush=True)
+
+    # Prefer the dashboard bundled into the server: it is served by the API on
+    # the same port, so a pip-installed user needs no repo checkout and no Node.
+    bundled = (Path(__file__).with_name("static") / "index.html").is_file()
+    if dashboard and bundled:
+        print(f"→ dashboard http://localhost:{port}  (bundled, served by the API)", flush=True)
+    elif dashboard:
+        dash_dir = _find_dashboard(path)
+        npm = shutil.which("npm")
+        if dash_dir is None:
+            print("! no bundled dashboard and no sibling dashboard/ — running the server only.", flush=True)
+        elif npm is None:
+            print("! npm not found on PATH — running the server without the dashboard.", flush=True)
+        else:
+            if not (dash_dir / "node_modules").is_dir():
+                print("· installing dashboard deps (first run)…", flush=True)
+                subprocess.run([npm, "install"], cwd=dash_dir, check=False)
+            dashboard_port = _free_port(dashboard_port)
+            dash_env = {**env, "VITE_FLEETWRIT_URL": f"http://localhost:{port}"}
+            procs.append(subprocess.Popen(
+                [npm, "run", "dev", "--", "--port", str(dashboard_port), "--strictPort"],
+                cwd=dash_dir, env=dash_env,
+            ))
+            print(f"→ dashboard http://localhost:{dashboard_port}  (live against the server)", flush=True)
+
+    print("Press Ctrl-C to stop.", flush=True)
+    try:
+        while True:
+            for p in procs:
+                if p.poll() is not None:
+                    raise KeyboardInterrupt
+            time.sleep(0.5)
+    except KeyboardInterrupt:
+        pass
+    finally:
+        for p in procs:
+            if p.poll() is None:
+                p.terminate()
+        for p in procs:
+            try:
+                p.wait(timeout=5)
+            except subprocess.TimeoutExpired:
+                p.kill()
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="fleetwrit-server", description="Fleetwrit dev server")
+    sub = parser.add_subparsers(dest="command")
+
+    dev = sub.add_parser("dev", help="Run the server and the dashboard together")
+    dev.add_argument("--port", type=int, default=int(os.getenv("PORT", "4100")))
+    dev.add_argument("--dashboard-port", type=int, default=5174)
+    dev.add_argument("--no-dashboard", action="store_true", help="Run the server only")
+    dev.add_argument("--demo", action="store_true", help="Load sample agents/requests (default: empty)")
+    dev.add_argument("--path", default=None, help="Repo root to find dashboard/ (default: cwd)")
+
+    args = parser.parse_args(argv)
+    if args.command == "dev":
+        return run_dev(
+            port=args.port,
+            dashboard_port=args.dashboard_port,
+            dashboard=not args.no_dashboard,
+            seed=args.demo,
+            path=args.path,
+        )
+    _run_server_only(int(os.getenv("PORT", "4100")))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

fleetwrit_server/schema.sql

@@ -0,0 +1,30 @@
+CREATE TABLE IF NOT EXISTS agents(
+  agent_id TEXT, environment TEXT, version TEXT, runtime TEXT,
+  owner TEXT, last_seen TEXT, disabled INTEGER DEFAULT 0,
+  volume30d INTEGER DEFAULT 0,
+  PRIMARY KEY(agent_id, environment));
+
+CREATE TABLE IF NOT EXISTS action_types(
+  type TEXT PRIMARY KEY, version TEXT, title TEXT, risk TEXT,
+  reversible INTEGER, editable TEXT, queue TEXT, owner TEXT,
+  summary TEXT, args_schema TEXT, display TEXT,
+  undeclared INTEGER DEFAULT 0, approval_rate REAL);
+
+CREATE TABLE IF NOT EXISTS requests(
+  id TEXT PRIMARY KEY, idempotency_key TEXT UNIQUE, kind TEXT,
+  agent_id TEXT, environment TEXT, type TEXT, action_version TEXT,
+  tool TEXT, args TEXT, reversible INTEGER, fingerprint TEXT,
+  summary TEXT, context TEXT, queue TEXT, provenance TEXT,
+  risk TEXT, editable TEXT, title TEXT, display TEXT,
+  created_at TEXT, expires_at TEXT, on_expiry TEXT,
+  state TEXT, viewed_at TEXT, verdict TEXT);
+
+CREATE TABLE IF NOT EXISTS decisions(
+  request_id TEXT PRIMARY KEY, outcome TEXT, final_args TEXT,
+  original_fingerprint TEXT, final_fingerprint TEXT, reason TEXT,
+  reviewer TEXT, receipt TEXT, value TEXT, option TEXT,
+  decided_at TEXT, consumed_at TEXT);
+
+CREATE TABLE IF NOT EXISTS ledger(
+  seq INTEGER PRIMARY KEY AUTOINCREMENT, ts TEXT, actor TEXT,
+  event TEXT, payload_hash TEXT, refs TEXT, prev_hash TEXT, hash TEXT);

fleetwrit_server/seed.py

@@ -0,0 +1,96 @@
+"""Seed the dev server with synthetic agents, action types and a little history.
+
+Idempotent: does nothing if agents already exist. Not real data — @acme.com only.
+"""
+
+from __future__ import annotations
+
+import uuid
+from datetime import datetime, timedelta, timezone
+from typing import Any
+
+from fleetwrit.fingerprint import fingerprint
+
+
+def _iso(dt: datetime) -> str:
+    return dt.astimezone(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+AGENTS = [
+    {"agent": {"id": "sre-remediation", "environment": "prod", "version": "0.1.0a3"}, "runtime": "LangGraph"},
+    {"agent": {"id": "support-refunds", "environment": "prod", "version": "0.4.2"}, "runtime": "OpenAI Agents"},
+    {"agent": {"id": "ap-invoices", "environment": "staging", "version": "0.11.0"}, "runtime": "LlamaIndex"},
+]
+
+ACTION_TYPES = [
+    {"type": "deploy.rollback", "version": "a1", "title": "Roll back deployment", "risk": "high", "reversible": False,
+     "editable": ["version"], "queue": "sre-oncall", "owner": "platform@acme.com",
+     "summary": "Roll back {service} to version {version}", "approval_rate": 0.98},
+    {"type": "service.restart", "version": "b2", "title": "Restart service", "risk": "medium", "reversible": True,
+     "editable": [], "queue": "sre-oncall", "owner": "platform@acme.com", "summary": "Restart {service}", "approval_rate": 0.99},
+    {"type": "refund.issue", "version": "c3", "title": "Issue refund", "risk": "high", "reversible": False,
+     "editable": ["amount"], "queue": "finance-ops", "owner": "payments-platform@acme.com",
+     "summary": "Refund {amount} on charge {charge}",
+     "display": {"amount": {"kind": "money", "currency_field": "currency"}}, "approval_rate": 0.96},
+    {"type": "payment.release", "version": "d4", "title": "Release vendor payment", "risk": "high", "reversible": False,
+     "editable": ["amount"], "queue": "finance-ops", "owner": "ap@acme.com",
+     "summary": "Release {amount} to {supplier}", "approval_rate": 0.9},
+    {"type": "data.delete", "version": "e5", "title": "Delete customer records", "risk": "critical", "reversible": False,
+     "editable": [], "queue": "privacy", "owner": "privacy@acme.com", "summary": "Delete {count} records", "approval_rate": 0.85},
+]
+
+AGENT_ACTIONS = {
+    "sre-remediation": ["deploy.rollback", "service.restart", "data.delete"],
+    "support-refunds": ["refund.issue"],
+    "ap-invoices": ["payment.release"],
+}
+
+
+def _payload(agent: str, env: str, atype: str, aversion: str, tool: str | None, args: dict[str, Any],
+             summary: str, queue: str, context: dict[str, Any], reversible: bool, mins_ago: int, ttl_min: int) -> dict[str, Any]:
+    created = datetime.now(timezone.utc) - timedelta(minutes=mins_ago)
+    fp = fingerprint(type=atype, version=aversion, tool=tool, args=args, agent_id=agent, environment=env)
+    return {
+        "schema": "fleetwrit/v1", "kind": "approve",
+        "agent": {"id": agent, "environment": env, "version": None},
+        "action": {"type": atype, "version": aversion, "tool": tool, "args": args, "reversible": reversible},
+        "fingerprint": fp, "summary": summary, "context": context, "queue": queue,
+        "provenance": {"run_id": "run_" + uuid.uuid4().hex[:8], "parent_request_id": None, "trace_id": None},
+        "idempotency_key": "seed_" + uuid.uuid4().hex[:12],
+        "created_at": _iso(created), "expires_at": _iso(created + timedelta(minutes=ttl_min)), "on_expiry": "reject",
+    }
+
+
+def seed_demo(store: Any) -> None:
+    if store.agents():
+        return
+    for a in AGENTS:
+        acts = [t for t in ACTION_TYPES if t["type"] in AGENT_ACTIONS[a["agent"]["id"]]]
+        store.register(a["agent"], acts, a["runtime"])
+
+    reviewer = {"subject": "marcus@acme.com", "email": "marcus@acme.com", "name": "Marcus Okonkwo", "issuer": "https://acme.okta.com"}
+
+    # pending requests (populate the inbox)
+    store.create_request(_payload("support-refunds", "prod", "refund.issue", "c3", "stripe.refunds.create",
+        {"charge": "ch_123", "amount": 400000, "currency": "gbp"}, "Refund £4,000 on charge ch_123",
+        "finance-ops", {"ticket": "ZD-99120", "prior_refunds": 0}, False, 6, 30))
+    store.create_request(_payload("sre-remediation", "prod", "deploy.rollback", "a1", "kubectl.rollout.undo",
+        {"service": "payments-api", "version": 42}, "Roll back payments-api to version 42",
+        "sre-oncall", {"alert": "PD-4471", "p95_ms": 920}, False, 3, 30))
+    store.create_request(_payload("sre-remediation", "prod", "data.delete", "e5", None,
+        {"count": 2410, "scope": "stale-sessions"}, "Delete 2,410 stale session records",
+        "privacy", {"policy": "gdpr-erasure"}, False, 1, 60))
+    # an undeclared action type observed on ap-invoices -> shows a coverage gap
+    store.create_request(_payload("ap-invoices", "staging", "vendor.payout", "z9", None,
+        {"supplier": "INV-7781", "amount": 1250000, "currency": "gbp"}, "Vendor payout INV-7781",
+        "finance-ops", {}, False, 8, 60))
+
+    # a little decided history (for overview counts + the ledger)
+    hist1 = store.create_request(_payload("support-refunds", "prod", "refund.issue", "c3", "stripe.refunds.create",
+        {"charge": "ch_884", "amount": 400000, "currency": "gbp"}, "Refund £4,000 on charge ch_884",
+        "finance-ops", {"ticket": "ZD-99044"}, False, 90, 240))
+    store.decide(hist1["id"], "approved", {"amount": 50000}, "Approved at £500 per policy cap", reviewer)
+    hist2 = store.create_request(_payload("sre-remediation", "prod", "deploy.rollback", "a1", "kubectl.rollout.undo",
+        {"service": "search-indexer", "version": 12}, "Roll back search-indexer to version 12",
+        "sre-oncall", {"alert": "PD-4460"}, False, 120, 240))
+    store.decide(hist2["id"], "rejected", None, "Prefer forward-fix; rollback drops the new index", reviewer)