stackthread 0.1.0.dev2__py3-none-any.whl

stackthread/server/app.py

@@ -0,0 +1,696 @@
+"""HTTP server on the stdlib: routes, JSON API, server-sent events, static UI."""
+
+from __future__ import annotations
+
+import collections
+import json
+import mimetypes
+import queue
+import re
+import sys
+import threading
+import time
+import webbrowser
+from http import HTTPStatus
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from pathlib import Path
+from typing import Any
+from urllib.parse import parse_qs, urlsplit
+
+from stackthread import SCHEMA_VERSION, __version__, adapters, lineage, logs, report
+from stackthread.project import Poller, Project, Snapshot
+from stackthread.server import edit, security
+
+PREFIX = "/__stackthread"
+_log = logs.get("server")
+_http = logs.get("http")
+_edit = logs.get("edit")
+_client = logs.get("client")
+CLIENT_SOURCES = ("ui", "overlay", "vite")
+CLIENT_LEVELS = {"error": 40, "warning": 30, "info": 20}
+CLIENT_PER_MINUTE = 60
+SLOW_LINEAGE_MS = 1000
+STATIC = Path(__file__).resolve().parents[1] / "static"
+MAX_BODY = 4 * 1024 * 1024
+EDITOR_URLS = {
+    "vscode": "vscode://file/{path}:{line}:{col}",
+    "cursor": "cursor://file/{path}:{line}:{col}",
+    "windsurf": "windsurf://file/{path}:{line}:{col}",
+    "zed": "zed://file/{path}:{line}:{col}",
+    "idea": "idea://open?file={path}&line={line}",
+    "pycharm": "pycharm://open?file={path}&line={line}",
+    "webstorm": "webstorm://open?file={path}&line={line}",
+    "none": "",
+}
+
+
+class Events:
+    """Fan-out of server-sent events to every open UI."""
+
+    def __init__(self) -> None:
+        self._clients: list[queue.Queue[str]] = []
+        self._lock = threading.Lock()
+
+    def publish(self, kind: str, data: dict[str, Any]) -> None:
+        message = f"event: {kind}\ndata: {json.dumps(data)}\n\n"
+        with self._lock:
+            for q in self._clients:
+                q.put(message)
+
+    def connect(self) -> queue.Queue[str]:
+        q: queue.Queue[str] = queue.Queue(maxsize=200)
+        with self._lock:
+            self._clients.append(q)
+        return q
+
+    def disconnect(self, q: queue.Queue[str]) -> None:
+        with self._lock:
+            if q in self._clients:
+                self._clients.remove(q)
+
+
+class ClientLimiter:
+    """At most CLIENT_PER_MINUTE messages a minute from each browser source; the rest are counted, then reported."""
+
+    def __init__(self) -> None:
+        self._sent: dict[str, collections.deque[float]] = collections.defaultdict(collections.deque)
+        self._dropped: dict[str, int] = collections.defaultdict(int)
+        self._lock = threading.Lock()
+
+    def allow(self, source: str) -> tuple[bool, int]:
+        """Whether to log this one, and how many were dropped since the last one that was."""
+        now = time.monotonic()
+        with self._lock:
+            sent = self._sent[source]
+            while sent and now - sent[0] > 60:
+                sent.popleft()
+            if len(sent) >= CLIENT_PER_MINUTE:
+                self._dropped[source] += 1
+                return False, 0
+            sent.append(now)
+            dropped, self._dropped[source] = self._dropped[source], 0
+            return True, dropped
+
+
+class App:
+    def __init__(self, project: Project, port: int, token: str) -> None:
+        self.project = project
+        self.port = port
+        self.token = token
+        self.events = Events()
+        self.dev_urls: list[str] = []
+        self.limiter = ClientLimiter()
+        self._last_progress = 0.0
+        logs.hide(token)
+        project.subscribe(self._on_snapshot)
+        project.on_activity(self._on_activity)
+
+    @property
+    def snapshot(self) -> Snapshot:
+        if self.project.snapshot is None:
+            raise edit.EditError(503, "stackthread is still reading the code; try again in a moment")
+        return self.project.snapshot
+
+    def _on_activity(self, activity: dict[str, Any]) -> None:
+        # progress while indexing is throttled to ten a second; every change of state goes out at once
+        now = time.monotonic()
+        in_progress = activity.get("state") == "indexing" and 0 < activity.get("done", 0) < activity.get("total", 0)
+        if in_progress and now - self._last_progress < 0.1:
+            return
+        self._last_progress = now
+        self.events.publish("activity", activity)
+
+    def _on_snapshot(self, snap: Snapshot) -> None:
+        self.events.publish(
+            "rev",
+            {
+                "rev": snap.rev,
+                "changed": snap.changed[:50],
+                "ms": round(snap.built_ms),
+                "findings": len(snap.graph.findings),
+            },
+        )
+
+    # ---- API ----
+
+    def meta(self) -> dict[str, Any]:
+        cfg, snap = self.project.config, self.project.snapshot
+        if snap is None:
+            return {
+                "name": cfg.name,
+                "version": __version__,
+                "schema": SCHEMA_VERSION,
+                "ready": False,
+                "activity": self.project.activity,
+            }
+        return {
+            "name": cfg.name,
+            "version": __version__,
+            "schema": SCHEMA_VERSION,
+            "ready": True,
+            "activity": self.project.activity,
+            "rev": snap.rev,
+            "root": str(cfg.root),
+            "platform": sys.platform,
+            "editor": {"name": cfg.server.editor, "url": EDITOR_URLS.get(cfg.server.editor, "")},
+            "edit": cfg.server.edit,
+            "detected": cfg.detected,
+            "config": str(cfg.path) if cfg.path else None,
+            "sources": [
+                {
+                    "name": s.name,
+                    "lang": s.lang,
+                    "role": s.role,
+                    "root": s.root,
+                    "files": len(snap.facts.get(s.name, {})),
+                }
+                for s in cfg.sources
+            ],
+            "warnings": snap.warnings,
+            "devUrls": self.dev_urls,
+            "counts": {
+                k: sum(1 for n in snap.graph.nodes.values() if n.kind == k)
+                for k in ("page", "component", "function", "hook", "endpoint", "model", "class", "method")
+            },
+        }
+
+    def node(self, node_id: str) -> dict[str, Any]:
+        g = self.snapshot.graph
+        node = g.nodes.get(node_id)
+        if node is None:
+            raise edit.EditError(404, "no such node")
+
+        def side(e: Any, other: str) -> dict[str, Any]:
+            n = g.nodes[other]
+            data = {
+                "id": n.id,
+                "kind": n.kind,
+                "name": n.name,
+                "qualname": n.qualname,
+                "file": n.file,
+                "line": n.line,
+                "layer": n.layer,
+                "edge": e.kind,
+                "confidence": e.confidence,
+                "label": e.label,
+            }
+            if e.site:
+                data["site"] = f"{e.site.file}:{e.site.line}"
+            return data
+
+        return {
+            "node": node.to_json(),
+            "out": [side(e, e.dst) for e in g.out(node_id) if e.kind != "contains"],
+            "in": [side(e, e.src) for e in g.into(node_id) if e.kind != "contains"],
+            "children": [side(e, e.dst) for e in g.out(node_id, "contains")],
+            "parent": next((side(e, e.src) for e in g.into(node_id, "contains")), None),
+        }
+
+    def search(self, q: str, limit: int) -> list[dict[str, Any]]:
+        q = q.strip().lower()
+        if not q:
+            return []
+        scored = []
+        for n in self.snapshot.graph.nodes.values():
+            name, qual, file = n.name.lower(), (n.qualname or "").lower(), n.file.lower()
+            if name == q:
+                score = 0
+            elif name.startswith(q):
+                score = 1
+            elif q in name:
+                score = 2
+            elif q in qual:
+                score = 3
+            elif q in file:
+                score = 4
+            else:
+                continue
+            if "test" in n.tags:
+                score += 3
+            scored.append((score, len(n.name), n))
+        scored.sort(key=lambda x: (x[0], x[1]))
+        return [
+            {
+                "id": n.id,
+                "kind": n.kind,
+                "name": n.name,
+                "qualname": n.qualname,
+                "file": n.file,
+                "line": n.line,
+                "layer": n.layer,
+                "source": n.source,
+            }
+            for _, _, n in scored[:limit]
+        ]
+
+    def pages(self) -> dict[str, Any]:
+        g = self.snapshot.graph
+        pages = []
+        for p in sorted(g.of_kind("page"), key=lambda n: n.attrs.get("path", "")):
+            comp = g.nodes.get(p.attrs.get("component", ""))
+            pages.append(
+                {
+                    "id": p.id,
+                    "path": p.attrs.get("path"),
+                    "source": p.source,
+                    "file": p.file,
+                    "line": p.line,
+                    "component": comp.name if comp else None,
+                    "componentId": comp.id if comp else None,
+                }
+            )
+        views = [v.to_json() for v in adapters.views(self.project)]
+        return {"pages": pages, "views": views, "params": self.project.config.page_params}
+
+    def findings(self) -> list[dict[str, Any]]:
+        order = {"error": 0, "warning": 1, "info": 2}
+        return [f.to_json() for f in sorted(self.snapshot.graph.findings, key=lambda f: (order[f.severity], f.file))]
+
+
+def _json(handler: BaseHTTPRequestHandler, data: Any, status: int = 200) -> None:
+    body = json.dumps(data, separators=(",", ":")).encode("utf-8")
+    handler.send_response(status)
+    handler.send_header("Content-Type", "application/json; charset=utf-8")
+    handler.send_header("Content-Length", str(len(body)))
+    handler.send_header("Cache-Control", "no-store")
+    handler.end_headers()
+    handler.wfile.write(body)
+
+
+def make_handler(app: App) -> type[BaseHTTPRequestHandler]:
+    class Handler(BaseHTTPRequestHandler):
+        server_version = f"stackthread/{__version__}"
+        protocol_version = "HTTP/1.1"
+
+        def parse_request(self) -> bool:
+            self._started = time.perf_counter()
+            return super().parse_request()
+
+        def log_request(self, code: int | str = "-", size: int | str = "-") -> None:
+            status = int(code) if str(code).isdigit() else 0
+            path = re.sub(r"([?&]token=)[^&]*", r"\1[hidden]", getattr(self, "path", ""))
+            ms = (time.perf_counter() - getattr(self, "_started", time.perf_counter())) * 1000
+            level = 40 if status >= 500 else 10
+            _http.log(
+                level,
+                "%s %s %s %.0f ms",
+                self.command,
+                path,
+                status,
+                ms,
+                extra=logs.ctx(method=self.command, path=path, status=status, ms=round(ms, 1)),
+            )
+
+        def log_error(self, format: str, *args: Any) -> None:
+            _http.debug(format, *args)
+
+        def log_message(self, format: str, *args: Any) -> None:
+            _http.debug(format, *args)
+
+        def _security_headers(self) -> None:
+            self.send_header("X-Content-Type-Options", "nosniff")
+            self.send_header("Referrer-Policy", "no-referrer")
+
+        def end_headers(self) -> None:
+            self._security_headers()
+            super().end_headers()
+
+        def _fail(self, status: int, message: str) -> None:
+            if self.command in ("POST", "PUT"):
+                self.close_connection = True  # an unread body must not be parsed as the next request
+            _json(self, {"error": message}, status)
+
+        def _refuse(self, status: int, reason: str, **fields: Any) -> bool:
+            _http.warning(
+                "refused %s %s: %s",
+                self.command,
+                urlsplit(self.path).path,
+                reason,
+                extra=logs.ctx(status=status, **fields),
+            )
+            self._fail(status, reason)
+            return False
+
+        def _guard(self, needs_token: bool, query: dict[str, list[str]]) -> bool:
+            if not security.host_allowed(self.headers.get("Host"), app.port):
+                return self._refuse(HTTPStatus.MISDIRECTED_REQUEST, "bad Host header", host=self.headers.get("Host"))
+            if not security.origin_allowed(self.headers.get("Origin")):
+                return self._refuse(
+                    HTTPStatus.FORBIDDEN, "cross-origin requests are not allowed", origin=self.headers.get("Origin")
+                )
+            if needs_token:
+                given = self.headers.get(security.TOKEN_HEADER) or query.get("token", [""])[0]
+                if not security.token_ok(app.token, given):
+                    return self._refuse(HTTPStatus.UNAUTHORIZED, "missing or wrong session token")
+            return True
+
+        def _body(self) -> Any:
+            length = int(self.headers.get("Content-Length") or 0)
+            if length > MAX_BODY:
+                raise edit.EditError(413, "request body too large")
+            if not (self.headers.get("Content-Type") or "").startswith("application/json"):
+                raise edit.EditError(415, "send application/json")
+            return json.loads(self.rfile.read(length) or b"{}")
+
+        # ---- routing ----
+
+        def do_GET(self) -> None:
+            url = urlsplit(self.path)
+            query = parse_qs(url.query)
+            path = url.path
+            if path in ("/", ""):
+                if not self._guard(False, query):
+                    return
+                self.send_response(302)
+                self.send_header("Location", f"{PREFIX}/")
+                self.send_header("Content-Length", "0")
+                self.end_headers()
+                return
+            if not path.startswith(PREFIX):
+                self._fail(404, "not found")
+                return
+            sub = path[len(PREFIX) :] or "/"
+            if sub.startswith("/api/"):
+                if not self._guard(True, query):
+                    return
+                try:
+                    self._api_get(sub[5:], query)
+                except edit.EditError as e:
+                    if e.status not in (404, 503):
+                        _http.warning("GET %s: %s", sub, e.message, extra=logs.ctx(status=e.status))
+                    self._fail(e.status, e.message)
+                except Exception as e:  # report instead of dropping the connection
+                    _http.exception("GET %s failed", sub)
+                    self._fail(500, f"{type(e).__name__}: {e}")
+                return
+            if not self._guard(False, query):
+                return
+            self._static(sub)
+
+        def do_POST(self) -> None:
+            self._mutate("POST")
+
+        def do_PUT(self) -> None:
+            self._mutate("PUT")
+
+        def _mutate(self, method: str) -> None:
+            url = urlsplit(self.path)
+            query = parse_qs(url.query)
+            sub = url.path[len(PREFIX) :] if url.path.startswith(PREFIX) else ""
+            if not sub.startswith("/api/"):
+                self._fail(404, "not found")
+                return
+            if not self._guard(True, query):
+                return
+            try:
+                body = self._body()
+                name = sub[5:]
+                if method == "POST" and name == "lineage":
+                    started = time.perf_counter()
+                    result = lineage.for_selection(app.project, app.snapshot, body)
+                    self._log_lineage(result, started)
+                    _json(self, result)
+                elif method == "PUT" and name == "source":
+                    file = str(body.get("file", ""))
+                    try:
+                        written = edit.write(
+                            app.project.config, file, str(body.get("hash", "")), str(body.get("text", ""))
+                        )
+                    except edit.EditError as e:
+                        _edit.warning(
+                            "did not save %s: %s", file, e.message, extra=logs.ctx(file=file, status=e.status)
+                        )
+                        raise
+                    _edit.info(
+                        "saved %s%s",
+                        file,
+                        " and formatted it" if written.formatted else "",
+                        extra=logs.ctx(file=file, formatted=written.formatted),
+                    )
+                    if written.output and not written.formatted:
+                        _edit.warning("the formatter reported a problem with %s: %s", file, written.output[-500:])
+                    app.project.invalidate([file])
+                    threading.Thread(target=app.project.poll, name="stackthread-after-save", daemon=True).start()
+                    _json(self, {"hash": written.hash, "formatted": written.formatted, "output": written.output})
+                elif method == "POST" and name == "hello":
+                    dev = str(body.get("devUrl", ""))
+                    if (
+                        re.match(r"^https?://(localhost|127\.0\.0\.1|\[::1\])(:\d+)?/?$", dev)
+                        and dev.rstrip("/") not in app.dev_urls
+                    ):
+                        app.dev_urls.append(dev.rstrip("/"))
+                        _log.info("the Vite dev server at %s connected", dev, extra=logs.ctx(dev_url=dev))
+                    _json(self, {"ok": True, "name": app.project.config.name})
+                elif method == "POST" and name == "log":
+                    self._client_log(body)
+                elif method == "POST" and name == "report":
+                    self._report(body)
+                else:
+                    self._fail(404, "not found")
+            except edit.EditError as e:
+                self._fail(e.status, e.message)
+            except json.JSONDecodeError:
+                self._fail(400, "body is not valid JSON")
+            except Exception as e:
+                _http.exception("%s %s failed", method, sub)
+                self._fail(500, f"{type(e).__name__}: {e}")
+
+        def _log_lineage(self, result: dict[str, Any], started: float) -> None:
+            ms = (time.perf_counter() - started) * 1000
+            target = result.get("target", {})
+            places = sum(len(layer.get("rows", [])) for layer in result.get("layers", []))
+            loc = target.get("loc") or target.get("file", "")
+            _log.log(
+                30 if ms > SLOW_LINEAGE_MS else 10,
+                "%s %s in %.0f ms (%d places)",
+                "slow explanation of" if ms > SLOW_LINEAGE_MS else "explained",
+                loc,
+                ms,
+                places,
+                extra=logs.ctx(loc=loc, ms=round(ms, 1), places=places, known=target.get("known")),
+            )
+
+        def _client_log(self, body: Any) -> None:
+            """Errors the browser reports: the UI, the in-app overlay, the Vite plugin. Size-capped and rate-limited."""
+            if not isinstance(body, dict):
+                raise edit.EditError(400, "send a JSON object")
+            source = str(body.get("source", ""))
+            level = str(body.get("level", "error"))
+            message = str(body.get("message", "")).strip()
+            if source not in CLIENT_SOURCES or level not in CLIENT_LEVELS or not message:
+                raise edit.EditError(400, f"need source ({', '.join(CLIENT_SOURCES)}), level and message")
+            allowed, dropped = app.limiter.allow(source)
+            if dropped:
+                _client.warning("dropped %d messages from the %s because it sent too many", dropped, source)
+            if allowed:
+                fields: dict[str, Any] = {"source": source}
+                for key, limit in (("url", 500), ("stack", 8000), ("where", 300)):
+                    if body.get(key):
+                        fields[key] = str(body[key])[:limit]
+                detail = body.get("detail")
+                if isinstance(detail, dict):
+                    text = json.dumps(detail, default=str)
+                    fields["detail"] = detail if len(text) <= 2000 else text[:2000]
+                _client.log(CLIENT_LEVELS[level], "[%s] %s", source, message[:2000], extra=logs.ctx(**fields))
+            _json(self, {"ok": True, "logged": allowed})
+
+        def _report(self, body: Any) -> None:
+            note = str(body.get("note", "")) if isinstance(body, dict) else ""
+            data, names = report.build(app.project.config, app.project.snapshot, note, app.project.activity)
+            path = report.save(app.project.config, data)
+            _log.info("made a problem report: %s", path.name, extra=logs.ctx(path=str(path), size=len(data)))
+            self.send_response(200)
+            self.send_header("Content-Type", "application/zip")
+            self.send_header("Content-Length", str(len(data)))
+            self.send_header("Content-Disposition", f'attachment; filename="{path.name}"')
+            self.send_header("X-Report-Path", str(path.relative_to(app.project.config.root)).replace("\\", "/"))
+            self.send_header("X-Report-Files", ",".join(names))
+            self.send_header("Cache-Control", "no-store")
+            self.end_headers()
+            self.wfile.write(data)
+
+        def _api_get(self, name: str, query: dict[str, list[str]]) -> None:
+            q = {k: v[0] for k, v in query.items()}
+            if name == "meta":
+                _json(self, app.meta())
+            elif name == "graph":
+                etag = f'"{app.snapshot.rev}"'
+                if self.headers.get("If-None-Match") == etag:
+                    self.send_response(304)
+                    self.send_header("ETag", etag)
+                    self.send_header("Content-Length", "0")
+                    self.end_headers()
+                    return
+                body = json.dumps(
+                    {"rev": app.snapshot.rev, **app.snapshot.graph.to_json()}, separators=(",", ":")
+                ).encode()
+                self.send_response(200)
+                self.send_header("Content-Type", "application/json; charset=utf-8")
+                self.send_header("Content-Length", str(len(body)))
+                self.send_header("ETag", etag)
+                self.send_header("Cache-Control", "no-cache")
+                self.end_headers()
+                self.wfile.write(body)
+            elif name == "node":
+                _json(self, app.node(q.get("id", "")))
+            elif name == "source":
+                text, digest = edit.read(app.project.config, q.get("file", ""))
+                _json(self, {"file": q.get("file"), "text": text, "hash": digest})
+            elif name == "explain":
+                started = time.perf_counter()
+                result = lineage.for_location(app.project, app.snapshot, q.get("loc", ""))
+                self._log_lineage(result, started)
+                _json(self, result)
+            elif name == "logs":
+                limit = min(int(q.get("n", "100") or 100), 1000)
+                _json(
+                    self,
+                    logs.recent(app.project.config.state_dir, q.get("level", "info"), limit, q.get("area") or None),
+                )
+            elif name == "pages":
+                _json(self, app.pages())
+            elif name == "search":
+                _json(self, app.search(q.get("q", ""), min(int(q.get("limit", "30") or 30), 200)))
+            elif name == "findings":
+                _json(self, app.findings())
+            elif name == "events":
+                self._events()
+            else:
+                self._fail(404, "not found")
+
+        def _events(self) -> None:
+            self.send_response(200)
+            self.send_header("Content-Type", "text/event-stream")
+            self.send_header("Cache-Control", "no-store")
+            self.send_header("Connection", "keep-alive")
+            self.end_headers()
+            q = app.events.connect()
+            _log.debug("a browser window connected for live updates")
+            try:
+                snap = app.project.snapshot
+                hello = {"rev": snap.rev if snap else 0, "activity": app.project.activity}
+                self.wfile.write(f"event: hello\ndata: {json.dumps(hello, default=str)}\n\n".encode())
+                self.wfile.flush()
+                while True:
+                    try:
+                        message = q.get(timeout=15)
+                    except queue.Empty:
+                        message = ": ping\n\n"
+                    self.wfile.write(message.encode())
+                    self.wfile.flush()
+            except (BrokenPipeError, ConnectionResetError, ConnectionAbortedError, OSError):
+                pass
+            finally:
+                app.events.disconnect(q)
+                _log.debug("a browser window disconnected")
+                self.close_connection = True
+
+        def _static(self, sub: str) -> None:
+            name = sub.strip("/") or "index.html"
+            if "/" in name or "." not in name:  # client-side routes all serve the app shell
+                name = "index.html"
+            path = (STATIC / name).resolve()
+            if not path.is_relative_to(STATIC.resolve()):
+                self._fail(404, "not found")
+                return
+            if not path.is_file() and name != "index.html":
+                self._fail(404, "not found")
+                return
+            if not path.is_file():
+                body = _missing_ui().encode()
+                ctype = "text/html; charset=utf-8"
+            else:
+                body = path.read_bytes()
+                ctype = mimetypes.guess_type(path.name)[0] or "application/octet-stream"
+                if path.name == "index.html":
+                    boot = json.dumps({"token": app.token, "base": PREFIX, "version": __version__})
+                    body = body.replace(
+                        b"<!--stackthread-boot-->",
+                        f'<script id="stackthread-boot" type="application/json">{boot}</script>'.encode(),
+                    )
+                    ctype = "text/html; charset=utf-8"
+            self.send_response(200)
+            self.send_header("Content-Type", ctype)
+            self.send_header("Content-Length", str(len(body)))
+            self.send_header("Cache-Control", "no-cache" if path.name == "index.html" else "max-age=60")
+            if path.name == "index.html" or not path.is_file():
+                self.send_header(
+                    "Content-Security-Policy",
+                    "default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline'; "
+                    "img-src 'self' data:; connect-src 'self'; frame-src 'self' http://localhost:* "
+                    "http://127.0.0.1:*; frame-ancestors 'self' http://localhost:* http://127.0.0.1:*",
+                )
+            self.end_headers()
+            self.wfile.write(body)
+
+    return Handler
+
+
+def _missing_ui() -> str:
+    return (
+        "<!doctype html><meta charset=utf-8><title>stackthread</title><body style='font:15px system-ui;padding:2rem'>"
+        "<h1>stackthread is running</h1><p>The browser UI is not built in this checkout. Run <code>npm run build</code>"
+        " in <code>js/</code>, or install stackthread from PyPI. The API is available under "
+        "<code>/__stackthread/api/</code>.</p>"
+    )
+
+
+class Server(ThreadingHTTPServer):
+    daemon_threads = True
+    allow_reuse_address = False
+
+
+def bind(port: int, attempts: int = 10) -> tuple[Server, int]:
+    """Bind to 127.0.0.1 on the first free port from `port`. Never binds other interfaces."""
+    last: OSError | None = None
+    for candidate in range(port, port + attempts):
+        try:
+            return Server(("127.0.0.1", candidate), BaseHTTPRequestHandler), candidate
+        except OSError as e:
+            last = e
+    raise OSError(f"no free port from {port} to {port + attempts - 1}: {last}")
+
+
+def _first_index(project: Project, poller: Poller | None) -> None:
+    """The first full read of the code, while the server already answers. Then start watching for changes."""
+    try:
+        project.scan()
+    except Exception as e:
+        _log.exception("the first indexing run failed")
+        project._set_activity("failed", error=f"{type(e).__name__}: {e}")
+    if poller is not None:
+        poller.start()
+
+
+def serve(project: Project, port: int | None = None, open_browser: bool = True, watch: bool = True) -> None:
+    config = project.config
+    server, actual = bind(port or config.server.port)
+    token = security.new_token()
+    app = App(project, actual, token)
+    server.RequestHandlerClass = make_handler(app)
+    session = security.write_session(config.state_dir, actual, token, config.root)
+    url = f"http://127.0.0.1:{actual}{PREFIX}/"
+    poller = Poller(project) if watch else None
+    _log.info(
+        "stackthread %s serving %s at %s",
+        __version__,
+        config.name,
+        url,
+        extra=logs.ctx(port=actual, edit=config.server.edit, watch=watch, session=str(session)),
+    )
+    _log.info("with the Vite plugin, open http://localhost:<vite port>/__stackthread/ for the live inspector")
+    _log.info("logs are kept in %s", logs.log_dir(config.state_dir))
+    threading.Thread(target=_first_index, args=(project, poller), name="stackthread-index", daemon=True).start()
+    if open_browser and config.server.open_browser:
+        threading.Timer(0.4, lambda: webbrowser.open(url)).start()
+    try:
+        server.serve_forever(poll_interval=0.5)
+    except KeyboardInterrupt:
+        _log.info("stopping")
+    finally:
+        if poller is not None:
+            poller.stop()
+        server.server_close()
+        security.clear_session(config.state_dir, token)
+        project.close()
+        _log.info("stopped")