dev-guru 0.2.0__tar.gz → 0.3.0__tar.gz

{dev_guru-0.2.0 → dev_guru-0.3.0}/CHANGELOG.md

@@ -10,6 +10,22 @@ Format: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) — [SemVer](ht
 
 ---
 
+## [0.3.0] — 2026-11-03
+
+### Added
+
+- **`dev serve`, a local gateway to Ananke.** It listens on loopback only. A single-use link signs in one browser, and
+  changes also need a same-origin `Origin`, a CSRF token and a JSON body. Workspaces are named by opaque id, and no route
+  takes a command or path to run. It starts and cancels runs, reads events and artifacts, previews workflows and serves
+  the code graph. There's no web interface yet. Guide: [The local gateway](docs/guides/gateway.md).
+- The client port gains run, event, artifact, plan and code graph operations, so the gateway reaches Ananke only through it.
+
+### Changed
+
+- Needs Ananke 0.3.17 or newer, for its facade that's safe across threads.
+
+---
+
 ## [0.2.0] — 2026-11-03
 
 ### Added

{dev_guru-0.2.0 → dev_guru-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: dev-guru
-Version: 0.2.0
+Version: 0.3.0
 Summary: Dev Guru: understand, improve, verify and learn from your software. A local-first developer product on the Ananke Plexus harness: Python SDK and CLI first, offline HTML reports, later a local web UI.
 Project-URL: Homepage, https://github.com/Neo-Pragnya/Dev-Guru
 Project-URL: Repository, https://github.com/Neo-Pragnya/Dev-Guru
@@ -22,7 +22,7 @@ Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Software Development :: Quality Assurance
 Classifier: Typing :: Typed
 Requires-Python: >=3.11
-Requires-Dist: ananke-plexus<0.4,>=0.3.13
+Requires-Dist: ananke-plexus<0.4,>=0.3.17
 Requires-Dist: markdown-it-py<5,>=3
 Requires-Dist: pydantic<3,>=2.11
 Requires-Dist: rich>=13
@@ -90,6 +90,7 @@ dev present talk.md                  # Markdown slides → one offline, accessib
 dev diagram docs/arch.md             # an animated SVG of what a document states, every edge cited
 dev explore . --profile public       # a report safe to publish: no source, docstrings or Git revision
 dev sources                          # capabilities from your folders, private Git and Dex Trove
+dev serve                            # a local, authenticated gateway to Ananke for browsers
 dev learning review NAME             # review what Ananke learned before it becomes reusable
 ```
 

{dev_guru-0.2.0 → dev_guru-0.3.0}/README.md

@@ -47,6 +47,7 @@ dev present talk.md                  # Markdown slides → one offline, accessib
 dev diagram docs/arch.md             # an animated SVG of what a document states, every edge cited
 dev explore . --profile public       # a report safe to publish: no source, docstrings or Git revision
 dev sources                          # capabilities from your folders, private Git and Dex Trove
+dev serve                            # a local, authenticated gateway to Ananke for browsers
 dev learning review NAME             # review what Ananke learned before it becomes reusable
 ```
 

{dev_guru-0.2.0 → dev_guru-0.3.0}/pyproject.toml

@@ -28,7 +28,7 @@ classifiers = [
 # Dev Guru is a client of Ananke: the harness owns analysis, execution and evidence (docs/architecture.md).
 # Keep this range in step with SUPPORTED_ANANKE in src/dev_guru/client/negotiation.py (tests/test_packaging.py).
 dependencies = [
-  "ananke-plexus>=0.3.13,<0.4",
+  "ananke-plexus>=0.3.17,<0.4",
   "markdown-it-py>=3,<5",
   "pydantic>=2.11,<3",
   "rich>=13",

{dev_guru-0.2.0 → dev_guru-0.3.0}/src/dev_guru/cli.py

@@ -286,6 +286,43 @@ def learning_review(
         webbrowser.open(out.resolve().as_uri())
 
 
+@app.command()
+def serve(
+    workspaces: Annotated[
+        list[Path] | None, typer.Argument(help="Projects the browser may reach (default: here)")
+    ] = None,
+    port: Annotated[int, typer.Option(help="Local port (default: any free one)")] = 0,
+    open_browser: Annotated[bool, typer.Option("--open/--no-open", help="Open the browser")] = True,
+    transport: TransportOpt = "in-process",
+) -> None:
+    """Start the local web gateway. It only listens on this computer, and only the printed link gets in."""
+    from dev_guru.gateway import Gateway
+
+    try:
+        client = connect(transport)
+        client.require_compatible()  # type: ignore[attr-defined]
+        gateway = Gateway(workspaces or [Path.cwd()], client, port=port)
+    except errors.GuruError as exc:
+        _fail(exc, False, 2)
+    except OSError as exc:
+        _fail(
+            errors.GuruError(errors.INVALID_INPUT, f"can't listen on port {port}: {exc}"), False, 2
+        )
+    # printed plainly: rich would wrap a long link, and this link is the way in
+    print(
+        f"Dev Guru is listening on this computer only. Open this link, which works once:\n{gateway.login_url}",
+        flush=True,
+    )
+    if open_browser:
+        webbrowser.open(gateway.login_url)
+    try:
+        gateway.serve_forever()
+    except KeyboardInterrupt:
+        pass
+    finally:
+        gateway.shutdown()
+
+
 @app.command()
 def diagram(
     document: Annotated[Path, typer.Argument(help="An approved Markdown document")],

{dev_guru-0.2.0 → dev_guru-0.3.0}/src/dev_guru/client/inprocess.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 from collections import Counter
+from collections.abc import Callable
 from pathlib import Path
 from typing import Any
 
@@ -87,6 +88,55 @@ class InProcessAnanke:
             raise errors.GuruError(errors.HARNESS_INCOMPATIBLE, exc.message) from exc
         return facade
 
+    def _call(self, workspace: Path, work: Callable[[Any], Any]) -> Any:
+        """Run one facade call, turning what Ananke refuses into a typed error that keeps its code."""
+        from ananke.plexus.app import AppError
+
+        facade = self._facade(self._root(workspace))
+        try:
+            return work(facade)
+        except AppError as exc:
+            raise errors.HarnessRefused(exc.code, exc.message, retryable=exc.retryable) from exc
+
+    def harness_capabilities(self, workspace: Path) -> dict[str, Any]:
+        return dict(self._call(workspace, lambda f: f.capabilities()))
+
+    def code_view(self, workspace: Path, **filters: Any) -> dict[str, Any]:
+        return dict(self._call(workspace, lambda f: f.code_view(**filters)))
+
+    def prepare_plan(self, workspace: Path, draft: dict[str, Any]) -> dict[str, Any]:
+        return dict(self._call(workspace, lambda f: f.preview_workflow(draft)))
+
+    def submit_run(
+        self, workspace: Path, kind: str, parameters: dict[str, Any], idempotency_key: str
+    ) -> dict[str, Any]:
+        return dict(
+            self._call(
+                workspace,
+                lambda f: f.submit_run(
+                    f.prepare_run(kind, parameters), idempotency_key, start=False
+                ),
+            )
+        )
+
+    def drive_run(self, workspace: Path, run_id: str) -> dict[str, Any]:
+        return dict(self._call(workspace, lambda f: f.drive(run_id)))
+
+    def get_run(self, workspace: Path, run_id: str) -> dict[str, Any]:
+        return dict(self._call(workspace, lambda f: f.get_run(run_id)))
+
+    def run_events(self, workspace: Path, run_id: str, after: int = 0) -> dict[str, Any]:
+        return dict(self._call(workspace, lambda f: f.stream_events(run_id, after)))
+
+    def cancel_run(self, workspace: Path, run_id: str) -> dict[str, Any]:
+        return dict(self._call(workspace, lambda f: f.cancel_run(run_id)))
+
+    def run_artifacts(self, workspace: Path, run_id: str) -> list[dict[str, Any]]:
+        return list(self._call(workspace, lambda f: f.list_artifacts(run_id)))
+
+    def read_artifact(self, workspace: Path, run_id: str, name: str) -> bytes:
+        return bytes(self._call(workspace, lambda f: f.read_artifact(run_id, name)))
+
     def graph_data(self, workspace: Path) -> GraphData:
         """Run Ananke's graph build through the app facade and read the snapshot artifact it produced."""
         info = self.require_compatible()

{dev_guru-0.2.0 → dev_guru-0.3.0}/src/dev_guru/client/negotiation.py

@@ -11,10 +11,8 @@ import importlib
 import re
 from importlib import metadata
 
-SUPPORTED_ANANKE = ">=0.3.13,<0.4"  # keep in step with pyproject.toml (tests/test_packaging.py)
-_MIN = (0, 3, 13)
+SUPPORTED_ANANKE = ">=0.3.17,<0.4"  # keep in step with pyproject.toml (tests/test_packaging.py)
 APP_PROTOCOL = "ananke-app/1"  # the app facade protocol this Dev Guru speaks
-_BELOW = (0, 4, 0)
 
 # Capability id -> (module, attribute path). Required ones are what this release of Dev Guru calls.
 CAPABILITIES: dict[str, tuple[str, str]] = {
@@ -36,6 +34,12 @@ def parse_version(text: str) -> tuple[int, int, int] | None:
     return (int(m.group(1)), int(m.group(2)), int(m.group(3))) if m else None
 
 
+_MIN, _BELOW = (
+    tuple(int(part) for part in bound.split("."))
+    for bound in re.fullmatch(r">=([\d.]+),<([\d.]+)", SUPPORTED_ANANKE).groups()  # type: ignore[union-attr]
+)
+
+
 def supported(version: str) -> bool:
     parsed = parse_version(version)
     return parsed is not None and _MIN <= parsed < _BELOW

{dev_guru-0.2.0 → dev_guru-0.3.0}/src/dev_guru/client/port.py

@@ -9,7 +9,7 @@ silently swapped for another (docs/concepts/ananke-client.md).
 from __future__ import annotations
 
 from pathlib import Path
-from typing import Protocol, runtime_checkable
+from typing import Any, Protocol, runtime_checkable
 
 from pydantic import BaseModel, Field
 
@@ -125,6 +125,30 @@ class AnankeClient(Protocol):
 
     def learning_candidate(self, workspace: Path, name: str) -> LearningCandidate: ...
 
+    def harness_capabilities(self, workspace: Path) -> dict[str, Any]: ...
+
+    def code_view(self, workspace: Path, **filters: Any) -> dict[str, Any]: ...
+
+    def prepare_plan(self, workspace: Path, draft: dict[str, Any]) -> dict[str, Any]: ...
+
+    def submit_run(
+        self, workspace: Path, kind: str, parameters: dict[str, Any], idempotency_key: str
+    ) -> dict[str, Any]:
+        """Record a run without starting it. The same key and request return the same run."""
+        ...
+
+    def drive_run(self, workspace: Path, run_id: str) -> dict[str, Any]: ...
+
+    def get_run(self, workspace: Path, run_id: str) -> dict[str, Any]: ...
+
+    def run_events(self, workspace: Path, run_id: str, after: int = 0) -> dict[str, Any]: ...
+
+    def cancel_run(self, workspace: Path, run_id: str) -> dict[str, Any]: ...
+
+    def run_artifacts(self, workspace: Path, run_id: str) -> list[dict[str, Any]]: ...
+
+    def read_artifact(self, workspace: Path, run_id: str, name: str) -> bytes: ...
+
 
 __all__ = [
     "AnankeClient",

{dev_guru-0.2.0 → dev_guru-0.3.0}/src/dev_guru/errors.py

@@ -10,6 +10,7 @@ UNSUPPORTED_TRANSPORT = "UNSUPPORTED_TRANSPORT"
 WORKSPACE_INVALID = "WORKSPACE_INVALID"
 HARNESS_FAILED = "HARNESS_FAILED"
 INVALID_INPUT = "INVALID_INPUT"
+HARNESS_REFUSED = "HARNESS_REFUSED"
 CODES = frozenset(
     {
         HARNESS_MISSING,
@@ -19,6 +20,7 @@ CODES = frozenset(
         WORKSPACE_INVALID,
         HARNESS_FAILED,
         INVALID_INPUT,
+        HARNESS_REFUSED,
     }
 )
 
@@ -44,3 +46,12 @@ class GuruError(Exception):
             "hint": self.hint,
             "run_id": self.run_id,
         }
+
+
+class HarnessRefused(GuruError):
+    """Ananke refused a request. ``harness_code`` is its own stable code, kept so a client can branch on it."""
+
+    def __init__(self, harness_code: str, message: str, *, retryable: bool = False) -> None:
+        super().__init__(HARNESS_REFUSED, message)
+        self.harness_code = harness_code
+        self.retryable = retryable

dev_guru-0.3.0/src/dev_guru/gateway/__init__.py

@@ -0,0 +1,5 @@
+"""The local web gateway: authenticates one browser session and forwards to the Ananke client port."""
+
+from dev_guru.gateway.server import Gateway
+
+__all__ = ["Gateway"]

dev_guru-0.3.0/src/dev_guru/gateway/server.py

@@ -0,0 +1,366 @@
+"""A loopback HTTP gateway from one browser session to the Ananke client port.
+
+It holds no domain logic: Ananke compiles, authorizes, runs and records. The gateway's job is to make sure the caller
+is this user's browser session, because any web page the user visits can send requests to a local port:
+
+- it binds to the loopback address only, with no option to change that;
+- ``Host`` must name this server, which stops DNS rebinding;
+- a single-use token from the terminal is exchanged for a session cookie, then scrubbed from the URL;
+- requests that change anything also need a same-origin ``Origin``, a CSRF token and a JSON body;
+- there are no CORS headers, so other origins can't read a response;
+- browsers name a workspace by opaque id, so no request can reach a path outside the roots given at start;
+- no route accepts a command or a path to run.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+import json
+import re
+import secrets
+import threading
+from concurrent.futures import ThreadPoolExecutor
+from http.cookies import CookieError, SimpleCookie
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from pathlib import Path
+from typing import Any
+from urllib.parse import parse_qs, urlsplit
+
+from dev_guru import errors
+from dev_guru.client.port import AnankeClient
+from dev_guru.version import __version__
+
+HOST = "127.0.0.1"
+MAX_BODY_BYTES = 2_000_000
+RUN_WORKERS = 2
+CSRF_HEADER = "X-Dev-Guru-CSRF"
+_RUN_ID = r"run-[0-9a-f]+"
+_ARTIFACT = r"[A-Za-z0-9_][A-Za-z0-9_.-]*"
+# The status for what Ananke refuses; anything retryable is 503, and anything else here is 400.
+_REFUSAL_STATUS = {
+    "RUN_NOT_FOUND": 404,
+    "ARTIFACT_NOT_FOUND": 404,
+    "SOURCE_NOT_FOUND": 404,
+    "IDEMPOTENCY_CONFLICT": 409,
+    "STALE_PLAN": 409,
+    "DIGEST_MISMATCH": 409,
+}
+
+
+class _Reject(Exception):
+    def __init__(self, status: int, code: str, message: str) -> None:
+        super().__init__(message)
+        self.status, self.code, self.message = status, code, message
+
+
+class Gateway:
+    def __init__(self, roots: list[Path], client: AnankeClient, *, port: int = 0) -> None:
+        if not roots:
+            raise errors.GuruError(errors.INVALID_INPUT, "the gateway needs at least one workspace")
+        self.client = client
+        self.roots: dict[str, Path] = {}
+        for root in roots:
+            resolved = root.expanduser().resolve()
+            if not resolved.is_dir():
+                raise errors.GuruError(errors.WORKSPACE_INVALID, f"{resolved} is not a directory")
+            self.roots[hashlib.sha256(str(resolved).encode()).hexdigest()[:12]] = resolved
+        self._session = secrets.token_urlsafe(32)
+        self._login_token: str | None = secrets.token_urlsafe(32)
+        self._login_lock = threading.Lock()
+        self.csrf = hmac.new(self._session.encode(), b"csrf", hashlib.sha256).hexdigest()
+        self._server = ThreadingHTTPServer((HOST, port), _handler_for(self))
+        self._server.daemon_threads = True
+        self.port = int(self._server.server_address[1])
+        self.cookie_name = f"dev_guru_session_{self.port}"  # cookies aren't separated by port
+        self.origins = {f"http://{HOST}:{self.port}", f"http://localhost:{self.port}"}
+        self.hosts = {f"{HOST}:{self.port}", f"localhost:{self.port}"}
+        self.runs = ThreadPoolExecutor(max_workers=RUN_WORKERS, thread_name_prefix="dev-guru-run")
+
+    @property
+    def login_url(self) -> str:
+        return f"http://{HOST}:{self.port}/login?token={self._login_token}"
+
+    def redeem(self, token: str) -> bool:
+        """The login token works once. A link left in a history or a terminal log opens nothing later."""
+        with self._login_lock:
+            if self._login_token and hmac.compare_digest(token, self._login_token):
+                self._login_token = None
+                return True
+        return False
+
+    def is_session(self, value: str) -> bool:
+        return hmac.compare_digest(value, self._session)
+
+    def session_cookie(self) -> str:
+        return f"{self.cookie_name}={self._session}; HttpOnly; SameSite=Strict; Path=/"
+
+    def serve_forever(self) -> None:
+        self._server.serve_forever()
+
+    def shutdown(self) -> None:
+        self._server.shutdown()
+        self._server.server_close()
+        self.runs.shutdown(wait=True)
+
+    def workspace(self, workspace_id: object) -> Path:
+        root = self.roots.get(str(workspace_id))
+        if root is None:
+            raise _Reject(404, "WORKSPACE_NOT_FOUND", "no such workspace: see /api/v1/workspaces")
+        return root
+
+    def drive(self, root: Path, run_id: str) -> None:
+        try:
+            self.client.drive_run(root, run_id)
+        except (
+            Exception
+        ):  # the harness records failures on the run itself; this thread has nowhere to report
+            return
+
+
+def _handler_for(gateway: Gateway) -> type[BaseHTTPRequestHandler]:
+    class Handler(_Handler):
+        pass
+
+    Handler.gateway = gateway
+    return Handler
+
+
+class _Handler(BaseHTTPRequestHandler):
+    gateway: Gateway
+    server_version = "DevGuruGateway"
+    sys_version = ""
+    protocol_version = "HTTP/1.1"
+
+    def log_message(self, format: str, *args: Any) -> None:
+        """Silent: a request line can carry the login token."""
+
+    # ------------------------------------------------------------------ responses
+    def _security_headers(self) -> None:
+        self.send_header("X-Content-Type-Options", "nosniff")
+        self.send_header("Referrer-Policy", "no-referrer")
+        self.send_header("Cache-Control", "no-store")
+        self.send_header("Cross-Origin-Resource-Policy", "same-origin")
+        self.send_header(
+            "Content-Security-Policy",
+            "default-src 'self'; frame-ancestors 'none'; base-uri 'none'; form-action 'self'",
+        )
+
+    def _send(self, status: int, body: bytes, media_type: str, *extra: tuple[str, str]) -> None:
+        self.send_response(status)
+        self.send_header("Content-Type", media_type)
+        self.send_header("Content-Length", str(len(body)))
+        self._security_headers()
+        for name, value in extra:
+            self.send_header(name, value)
+        self.end_headers()
+        self.wfile.write(body)
+
+    def _json(self, payload: object, status: int = 200) -> None:
+        self._send(status, json.dumps(payload).encode(), "application/json")
+
+    def _error(self, status: int, code: str, message: str, *, retryable: bool = False) -> None:
+        self.close_connection = True  # an unread body mustn't be parsed as the next request
+        self._json(
+            {"ok": False, "error": {"code": code, "message": message, "retryable": retryable}},
+            status,
+        )
+
+    # ------------------------------------------------------------------ checks
+    def _check_host(self) -> None:
+        if self.headers.get("Host", "") not in self.gateway.hosts:
+            raise _Reject(403, "HOST_REJECTED", "this request isn't addressed to this gateway")
+
+    def _check_origin(self, *, required: bool) -> None:
+        origin = self.headers.get("Origin")
+        if origin is None:
+            if required:
+                raise _Reject(403, "ORIGIN_REJECTED", "a change needs a same-origin Origin header")
+        elif origin not in self.gateway.origins:
+            raise _Reject(403, "ORIGIN_REJECTED", "requests from other origins aren't accepted")
+        if self.headers.get("Sec-Fetch-Site", "same-origin") not in ("same-origin", "none"):
+            raise _Reject(403, "ORIGIN_REJECTED", "requests from other sites aren't accepted")
+
+    def _has_session(self) -> bool:
+        try:
+            cookies = SimpleCookie(self.headers.get("Cookie", ""))
+        except CookieError:
+            return False
+        morsel = cookies.get(self.gateway.cookie_name)
+        return morsel is not None and self.gateway.is_session(morsel.value)
+
+    def _check_session(self) -> None:
+        if not self._has_session():
+            raise _Reject(401, "NOT_AUTHENTICATED", "open the link `dev serve` printed")
+
+    def _check_csrf(self) -> None:
+        sent = self.headers.get(CSRF_HEADER, "")
+        if not hmac.compare_digest(sent, self.gateway.csrf):
+            raise _Reject(403, "CSRF_REJECTED", f"a change needs the {CSRF_HEADER} header")
+
+    def _read_json(self) -> dict[str, Any]:
+        if self.headers.get_content_type() != "application/json":
+            raise _Reject(415, "UNSUPPORTED_MEDIA_TYPE", "send application/json")
+        try:
+            length = int(self.headers.get("Content-Length", ""))
+        except ValueError:
+            raise _Reject(411, "LENGTH_REQUIRED", "send a Content-Length") from None
+        if not 0 <= length <= MAX_BODY_BYTES:
+            raise _Reject(413, "TOO_LARGE", f"a request may be at most {MAX_BODY_BYTES} bytes")
+        try:
+            body = json.loads(self.rfile.read(length) or b"{}")
+        except ValueError:
+            raise _Reject(400, "INVALID_JSON", "the body isn't valid JSON") from None
+        if not isinstance(body, dict):
+            raise _Reject(400, "INVALID_JSON", "the body must be a JSON object")
+        return body
+
+    # ------------------------------------------------------------------ dispatch
+    def _guarded(self, work: Any) -> None:
+        try:
+            self._check_host()
+            work()
+        except _Reject as exc:
+            self._error(exc.status, exc.code, exc.message)
+        except errors.HarnessRefused as exc:
+            status = 503 if exc.retryable else _REFUSAL_STATUS.get(exc.harness_code, 400)
+            self._error(status, exc.harness_code, exc.message, retryable=exc.retryable)
+        except errors.GuruError as exc:
+            self._error(503, exc.code, exc.message)
+        except (BrokenPipeError, ConnectionResetError):
+            self.close_connection = True
+        except Exception:  # never hand internals to a browser
+            self._error(500, "INTERNAL_ERROR", "the gateway hit an unexpected error")
+
+    def do_GET(self) -> None:
+        self._guarded(self._get)
+
+    def do_POST(self) -> None:
+        self._guarded(self._post)
+
+    def _refuse_method(self) -> None:
+        self._guarded(lambda: self._error(405, "METHOD_NOT_ALLOWED", "use GET or POST"))
+
+    do_PUT = do_PATCH = do_DELETE = do_OPTIONS = do_HEAD = do_TRACE = _refuse_method
+
+    def _get(self) -> None:
+        url = urlsplit(self.path)
+        query = {k: v[-1] for k, v in parse_qs(url.query).items()}
+        if url.path == "/login":
+            self._login(query.get("token", ""))
+            return
+        self._check_origin(required=False)
+        self._check_session()
+        if url.path == "/":
+            page = (Path(__file__).parent / "static" / "index.html").read_bytes()
+            self._send(200, page, "text/html; charset=utf-8")
+            return
+        self._api_get(url.path, query)
+
+    def _login(self, token: str) -> None:
+        if not self.gateway.redeem(token):
+            raise _Reject(401, "NOT_AUTHENTICATED", "this link was already used or isn't valid")
+        self.send_response(303)
+        self.send_header("Location", "/")
+        self.send_header("Set-Cookie", self.gateway.session_cookie())
+        self.send_header("Content-Length", "0")
+        self._security_headers()
+        self.end_headers()
+
+    @staticmethod
+    def _int(query: dict[str, str], name: str, default: int) -> int:
+        try:
+            return int(query.get(name, default))
+        except ValueError:
+            raise _Reject(400, "INVALID_REQUEST", f"{name} must be a whole number") from None
+
+    def _api_get(self, path: str, query: dict[str, str]) -> None:
+        gateway, client = self.gateway, self.gateway.client
+        if path == "/api/v1/session":
+            self._json({"csrf_header": CSRF_HEADER, "csrf_token": gateway.csrf})
+        elif path == "/api/v1/health":
+            info = client.info()
+            self._json(
+                {"ok": info.compatible, "gateway": __version__, "harness": info.model_dump()}
+            )
+        elif path == "/api/v1/workspaces":
+            rows = [{"id": k, "name": v.name, "path": str(v)} for k, v in gateway.roots.items()]
+            self._json({"workspaces": rows})
+        else:
+            root = gateway.workspace(query.get("workspace"))
+            self._api_get_in(path, query, root)
+
+    def _api_get_in(self, path: str, query: dict[str, str], root: Path) -> None:
+        client = self.gateway.client
+        if path == "/api/v1/capabilities":
+            self._json(client.harness_capabilities(root))
+        elif path == "/api/v1/sources":
+            found = client.discover_capabilities(root, query.get("q", ""))
+            self._json({"capabilities": [c.model_dump() for c in found]})
+        elif path == "/api/v1/code":
+            self._json(
+                client.code_view(
+                    root,
+                    path_prefix=query.get("path", ""),
+                    query=query.get("q", ""),
+                    kinds=[k for k in query.get("kinds", "").split(",") if k],
+                    budget=self._int(query, "budget", 500),
+                    collapse=query.get("collapse", "none"),
+                    depth=self._int(query, "depth", 1),
+                )
+            )
+        elif match := re.fullmatch(rf"/api/v1/runs/({_RUN_ID})", path):
+            self._json(client.get_run(root, match[1]))
+        elif match := re.fullmatch(rf"/api/v1/runs/({_RUN_ID})/events", path):
+            self._json(client.run_events(root, match[1], self._int(query, "after", 0)))
+        elif match := re.fullmatch(rf"/api/v1/runs/({_RUN_ID})/artifacts", path):
+            self._json({"artifacts": client.run_artifacts(root, match[1])})
+        elif match := re.fullmatch(rf"/api/v1/runs/({_RUN_ID})/artifacts/({_ARTIFACT})", path):
+            data = client.read_artifact(root, match[1], match[2])
+            # always a download, and sandboxed if opened anyway: an artifact can hold anything
+            self._send(
+                200,
+                data,
+                "application/octet-stream",
+                ("Content-Disposition", f'attachment; filename="{match[2]}"'),
+                ("Content-Security-Policy", "sandbox"),
+            )
+        else:
+            raise _Reject(404, "NOT_FOUND", "no such route")
+
+    def _post(self) -> None:
+        self._check_origin(required=True)
+        self._check_session()
+        self._check_csrf()
+        body = self._read_json()
+        path = urlsplit(self.path).path
+        root = self.gateway.workspace(body.get("workspace"))
+        client = self.gateway.client
+        if path == "/api/v1/plans/prepare":
+            self._json(client.prepare_plan(root, self._object(body, "draft")))
+        elif path == "/api/v1/runs":
+            run = client.submit_run(
+                root,
+                str(body.get("kind", "")),
+                self._object(body, "parameters", default={}),
+                str(body.get("idempotency_key", "")),
+            )
+            if run["state"] == "queued":
+                self.gateway.runs.submit(self.gateway.drive, root, run["run_id"])
+            self._json(run, 202)
+        elif match := re.fullmatch(rf"/api/v1/runs/({_RUN_ID})/cancel", path):
+            self._json(client.cancel_run(root, match[1]))
+        else:
+            raise _Reject(404, "NOT_FOUND", "no such route")
+
+    @staticmethod
+    def _object(
+        body: dict[str, Any], name: str, default: dict[str, Any] | None = None
+    ) -> dict[str, Any]:
+        value = body.get(name, default)
+        if not isinstance(value, dict):
+            raise _Reject(400, "INVALID_REQUEST", f"{name} must be a JSON object")
+        return value
+
+
+__all__ = ["CSRF_HEADER", "HOST", "MAX_BODY_BYTES", "Gateway"]

dev_guru-0.3.0/src/dev_guru/gateway/static/index.html

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Dev Guru</title>
+<body>
+<main>
+<h1>Dev Guru</h1>
+<p>The local gateway is running. The web interface isn't part of this version yet; the API is at <code>/api/v1/</code>.</p>
+</main>
+</body>
+</html>

{dev_guru-0.2.0 → dev_guru-0.3.0}/src/dev_guru/version.py

@@ -1,3 +1,3 @@
 """The package version, in a module that imports nothing (so any module can use it without an import cycle)."""
 
-__version__ = "0.2.0"
+__version__ = "0.3.0"

dev_guru-0.3.0/tests/test_gateway.py

@@ -0,0 +1,423 @@
+"""The gateway over real HTTP on a real socket, driving the real Ananke harness."""
+
+from __future__ import annotations
+
+import http.client
+import json
+import subprocess
+import threading
+import time
+from collections.abc import Iterator
+from pathlib import Path
+from typing import Any
+from urllib.parse import urlsplit
+
+import pytest
+
+from dev_guru import errors
+from dev_guru.client import connect
+from dev_guru.gateway import Gateway
+from dev_guru.gateway.server import CSRF_HEADER, HOST, MAX_BODY_BYTES
+
+
+@pytest.fixture
+def repo(tmp_path: Path) -> Path:
+    root = tmp_path / "repo"
+    root.mkdir()
+    (root / "a.py").write_text("def one():\n    return 1\n")
+    subprocess.run(["git", "init", "-q", str(root)], check=True)
+    subprocess.run(["git", "-C", str(root), "add", "-A"], check=True)
+    subprocess.run(
+        [
+            "git",
+            "-C",
+            str(root),
+            "-c",
+            "user.name=t",
+            "-c",
+            "user.email=t@example.com",
+            "commit",
+            "-qm",
+            "i",
+        ],
+        check=True,
+    )
+    return root
+
+
+@pytest.fixture
+def gateway(repo: Path) -> Iterator[Gateway]:
+    g = Gateway([repo], connect("in-process"))
+    thread = threading.Thread(target=g.serve_forever, daemon=True)
+    thread.start()
+    yield g
+    g.shutdown()
+
+
+class Browser:
+    """Sends exactly the headers a browser would, so each test can take one away."""
+
+    def __init__(self, gateway: Gateway) -> None:
+        self.g = gateway
+        self.origin = f"http://{HOST}:{gateway.port}"
+        self.cookie = ""
+        self.workspace = next(iter(gateway.roots))
+
+    def raw(
+        self,
+        method: str,
+        path: str,
+        *,
+        headers: dict[str, str] | None = None,
+        body: bytes | None = None,
+    ) -> tuple[int, dict[str, str], bytes]:
+        conn = http.client.HTTPConnection(HOST, self.g.port, timeout=30)
+        conn.putrequest(method, path, skip_host=True, skip_accept_encoding=True)
+        sent = {"Host": f"{HOST}:{self.g.port}", **(headers or {})}
+        if self.cookie and "Cookie" not in sent:
+            sent["Cookie"] = self.cookie
+        if body is not None:
+            sent["Content-Length"] = str(len(body))
+        for name, value in sent.items():
+            if value:
+                conn.putheader(name, value)
+        conn.endheaders(body)
+        response = conn.getresponse()
+        data = response.read()
+        result = (response.status, {k.lower(): v for k, v in response.getheaders()}, data)
+        conn.close()
+        return result
+
+    def login(self) -> Browser:
+        split = urlsplit(self.g.login_url)
+        status, headers, _ = self.raw("GET", f"{split.path}?{split.query}")
+        assert status == 303 and headers["location"] == "/"
+        self.cookie = headers["set-cookie"].split(";")[0]
+        return self
+
+    def get(self, path: str) -> tuple[int, Any]:
+        sep = "&" if "?" in path else "?"
+        status, _, data = self.raw("GET", f"{path}{sep}workspace={self.workspace}")
+        return status, json.loads(data)
+
+    def post(self, path: str, payload: dict[str, Any], **headers: str) -> tuple[int, Any]:
+        sent = {
+            "Origin": self.origin,
+            "Content-Type": "application/json",
+            CSRF_HEADER: self.g.csrf,
+            **{k.replace("_", "-"): v for k, v in headers.items()},
+        }
+        body = json.dumps({"workspace": self.workspace, **payload}).encode()
+        status, _, data = self.raw("POST", path, headers=sent, body=body)
+        return status, json.loads(data)
+
+    def finish(self, run_id: str) -> dict[str, Any]:
+        for _ in range(300):
+            status, run = self.get(f"/api/v1/runs/{run_id}")
+            assert status == 200
+            if run["state"] in ("succeeded", "failed", "cancelled"):
+                return run
+            time.sleep(0.05)
+        raise AssertionError("the run didn't finish")
+
+
+@pytest.fixture
+def browser(gateway: Gateway) -> Browser:
+    return Browser(gateway).login()
+
+
+def code(response: tuple[int, Any]) -> str:
+    return str(response[1]["error"]["code"])
+
+
+# ------------------------------------------------------------------ who gets in
+def test_it_listens_on_loopback_only(gateway: Gateway) -> None:
+    assert gateway._server.server_address[0] == "127.0.0.1"
+
+
+def test_the_login_link_works_once_and_leaves_the_url(gateway: Gateway) -> None:
+    b = Browser(gateway)
+    split = urlsplit(gateway.login_url)
+    target = f"{split.path}?{split.query}"
+    assert b.raw("GET", target)[0] == 303
+    assert b.raw("GET", target)[0] == 401
+
+
+def test_the_session_cookie_is_strict(gateway: Gateway) -> None:
+    b = Browser(gateway)
+    split = urlsplit(gateway.login_url)
+    cookie = b.raw("GET", f"{split.path}?{split.query}")[1]["set-cookie"]
+    assert "HttpOnly" in cookie and "SameSite=Strict" in cookie
+    assert f"dev_guru_session_{gateway.port}=" in cookie
+
+
+@pytest.mark.parametrize("path", ["/", "/api/v1/health", "/api/v1/session", "/api/v1/workspaces"])
+def test_nothing_is_served_without_a_session(gateway: Gateway, path: str) -> None:
+    assert Browser(gateway).raw("GET", path)[0] == 401
+
+
+def test_a_wrong_token_and_a_wrong_cookie_get_nothing(gateway: Gateway) -> None:
+    b = Browser(gateway)
+    assert b.raw("GET", "/login?token=guess")[0] == 401
+    b.cookie = f"{gateway.cookie_name}=guess"
+    assert b.raw("GET", "/api/v1/health")[0] == 401
+    b.cookie = "not a ; valid = cookie;;"
+    assert b.raw("GET", "/api/v1/health")[0] == 401
+
+
+@pytest.mark.parametrize(
+    "host", ["evil.example", "evil.example:80", "127.0.0.1", "localhost:1", ""]
+)
+def test_a_rebound_host_is_refused_even_with_a_session(browser: Browser, host: str) -> None:
+    status, _, data = browser.raw("GET", "/api/v1/health", headers={"Host": host})
+    assert status == 403 and json.loads(data)["error"]["code"] == "HOST_REJECTED"
+
+
+def test_localhost_is_accepted_as_the_same_server(browser: Browser, gateway: Gateway) -> None:
+    host = f"localhost:{gateway.port}"
+    assert browser.raw("GET", "/api/v1/health", headers={"Host": host})[0] == 200
+
+
+# ------------------------------------------------------------------ a page on another site
+def test_a_change_needs_origin_csrf_and_json(browser: Browser) -> None:
+    payload = {"kind": "graph.build", "idempotency_key": "k"}
+    path = "/api/v1/runs"
+    assert code(browser.post(path, payload, Origin="https://evil.example")) == "ORIGIN_REJECTED"
+    assert code(browser.post(path, payload, Origin="")) == "ORIGIN_REJECTED"
+    assert code(browser.post(path, payload, Sec_Fetch_Site="cross-site")) == "ORIGIN_REJECTED"
+    assert (
+        code(browser.post(path, payload, **{CSRF_HEADER.replace("-", "_"): ""})) == "CSRF_REJECTED"
+    )
+    assert (
+        code(browser.post(path, payload, **{CSRF_HEADER.replace("-", "_"): "guess"}))
+        == "CSRF_REJECTED"
+    )
+    assert code(browser.post(path, payload, Content_Type="text/plain")) == "UNSUPPORTED_MEDIA_TYPE"
+    assert (
+        code(browser.post(path, payload, Content_Type="application/x-www-form-urlencoded"))
+        == "UNSUPPORTED_MEDIA_TYPE"
+    )
+    assert not (Path(browser.g.roots[browser.workspace]) / ".ananke" / "app" / "runs").exists()
+
+
+def test_a_read_from_another_origin_is_refused_and_never_gets_cors(browser: Browser) -> None:
+    status, headers, _ = browser.raw(
+        "GET", "/api/v1/health", headers={"Origin": "https://evil.example"}
+    )
+    assert status == 403 and "access-control-allow-origin" not in headers
+    status, headers, _ = browser.raw("OPTIONS", "/api/v1/runs", headers={"Origin": browser.origin})
+    assert status == 405 and "access-control-allow-origin" not in headers
+    status, headers, _ = browser.raw("GET", "/api/v1/health", headers={"Origin": browser.origin})
+    assert status == 200 and "access-control-allow-origin" not in headers
+
+
+def test_responses_carry_security_headers(browser: Browser) -> None:
+    _, headers, _ = browser.raw("GET", "/")
+    assert headers["x-content-type-options"] == "nosniff"
+    assert headers["referrer-policy"] == "no-referrer"
+    assert "frame-ancestors 'none'" in headers["content-security-policy"]
+
+
+@pytest.mark.parametrize(
+    ("body", "expected", "status"),
+    [(b"not json", "INVALID_JSON", 400), (b"[1, 2]", "INVALID_JSON", 400)],
+)
+def test_a_bad_body_is_refused(browser: Browser, body: bytes, expected: str, status: int) -> None:
+    sent = {
+        "Origin": browser.origin,
+        "Content-Type": "application/json",
+        CSRF_HEADER: browser.g.csrf,
+    }
+    got, _, data = browser.raw("POST", "/api/v1/runs", headers=sent, body=body)
+    assert got == status and json.loads(data)["error"]["code"] == expected
+
+
+def test_an_oversized_body_is_refused_without_reading_it(browser: Browser) -> None:
+    sent = {
+        "Origin": browser.origin,
+        "Content-Type": "application/json",
+        CSRF_HEADER: browser.g.csrf,
+        "Content-Length": str(MAX_BODY_BYTES + 1),
+    }
+    got, _, data = browser.raw("POST", "/api/v1/runs", headers=sent)
+    assert got == 413 and json.loads(data)["error"]["code"] == "TOO_LARGE"
+
+
+# ------------------------------------------------------------------ scope
+def test_a_workspace_is_an_id_and_a_path_reaches_nothing(browser: Browser, tmp_path: Path) -> None:
+    status, listed = browser.get("/api/v1/workspaces")
+    assert status == 200 and [w["id"] for w in listed["workspaces"]] == [browser.workspace]
+    for attempt in (str(tmp_path), "..", "../..", "/etc", "nope"):
+        browser.workspace = attempt
+        assert code(browser.get("/api/v1/code")) == "WORKSPACE_NOT_FOUND"
+        assert (
+            code(browser.post("/api/v1/runs", {"kind": "graph.build", "idempotency_key": "x"}))
+            == "WORKSPACE_NOT_FOUND"
+        )
+
+
+@pytest.mark.parametrize(
+    "path",
+    [
+        "/api/v1/runs/..%2F..%2Fsecrets",
+        "/api/v1/runs/run-abc/artifacts/..%2F..%2Frun.json",
+        "/api/v1/runs/run-abc/artifacts/.env",
+        "/api/v1/shell",
+        "/api/v1/exec",
+        "/static/../../etc/passwd",
+    ],
+)
+def test_odd_paths_reach_nothing(browser: Browser, path: str) -> None:
+    assert browser.get(path)[0] == 404
+
+
+def test_no_route_runs_a_command(browser: Browser) -> None:
+    status, run = browser.post(
+        "/api/v1/runs",
+        {"kind": "shell", "parameters": {"command": "touch pwned"}, "idempotency_key": "x"},
+    )
+    assert status == 400 and run["error"]["code"] == "UNKNOWN_RUN_KIND"
+    assert not (browser.g.roots[browser.workspace] / "pwned").exists()
+
+
+def test_an_unknown_workspace_at_start_is_refused(tmp_path: Path) -> None:
+    with pytest.raises(errors.GuruError):
+        Gateway([tmp_path / "missing"], connect("in-process"))
+    with pytest.raises(errors.GuruError):
+        Gateway([], connect("in-process"))
+
+
+# ------------------------------------------------------------------ the real harness behind it
+def test_a_run_goes_through_the_harness_with_events_and_artifacts(browser: Browser) -> None:
+    status, run = browser.post("/api/v1/runs", {"kind": "graph.build", "idempotency_key": "one"})
+    assert status == 202 and run["state"] in ("queued", "running", "succeeded")
+    done = browser.finish(run["run_id"])
+    assert done["state"] == "succeeded"
+
+    status, seen = browser.get(f"/api/v1/runs/{run['run_id']}/events")
+    types = [e["type"] for e in seen["events"]]
+    assert types[0] == "run.queued" and types[-1] == "run.succeeded"
+    status, later = browser.get(
+        f"/api/v1/runs/{run['run_id']}/events?after={seen['events'][-1]['seq']}"
+    )
+    assert later["events"] == []
+
+    _, listed = browser.get(f"/api/v1/runs/{run['run_id']}/artifacts")
+    assert [a["name"] for a in listed["artifacts"]] == ["graph-snapshot.json"]
+    status, headers, data = browser.raw(
+        "GET",
+        f"/api/v1/runs/{run['run_id']}/artifacts/graph-snapshot.json?workspace={browser.workspace}",
+    )
+    assert status == 200 and json.loads(data)["nodes"]
+    assert headers["content-disposition"].startswith("attachment")
+    assert headers["content-type"] == "application/octet-stream"
+    assert "sandbox" in headers["content-security-policy"]
+
+    status, view = browser.get("/api/v1/code?collapse=file&budget=5")
+    assert status == 200 and view["collapse"] == "file"
+
+
+def test_a_reloaded_tab_and_a_second_tab_see_the_same_run(
+    browser: Browser, gateway: Gateway
+) -> None:
+    _, run = browser.post("/api/v1/runs", {"kind": "graph.build", "idempotency_key": "same"})
+    _, again = browser.post("/api/v1/runs", {"kind": "graph.build", "idempotency_key": "same"})
+    assert again["run_id"] == run["run_id"]
+    assert browser.finish(run["run_id"])["state"] == "succeeded"
+    second = Browser(gateway)
+    second.cookie = browser.cookie
+    assert second.finish(run["run_id"])["state"] == "succeeded"
+
+
+def test_what_ananke_refuses_keeps_its_code_and_a_fitting_status(browser: Browser) -> None:
+    assert code(browser.get("/api/v1/runs/run-0123")) == "RUN_NOT_FOUND"
+    assert browser.get("/api/v1/runs/run-0123")[0] == 404
+    status, body = browser.get("/api/v1/code")
+    assert status == 503 and body["error"]["code"] == "GRAPH_MISSING" and body["error"]["retryable"]
+    assert code(browser.get("/api/v1/code?budget=x")) == "INVALID_REQUEST"
+    browser.post("/api/v1/runs", {"kind": "graph.build", "idempotency_key": "k"})
+    status, conflict = browser.post(
+        "/api/v1/runs",
+        {"kind": "graph.impact", "parameters": {"changed_files": ["a.py"]}, "idempotency_key": "k"},
+    )
+    assert status == 409 and conflict["error"]["code"] == "IDEMPOTENCY_CONFLICT"
+
+
+def test_a_cancelled_run_stays_cancelled(browser: Browser, monkeypatch: pytest.MonkeyPatch) -> None:
+    release = threading.Event()
+    original = browser.g.drive
+    monkeypatch.setattr(
+        browser.g, "drive", lambda root, run_id: (release.wait(10), original(root, run_id))
+    )
+    _, run = browser.post("/api/v1/runs", {"kind": "graph.build", "idempotency_key": "c"})
+    status, cancelled = browser.post(f"/api/v1/runs/{run['run_id']}/cancel", {})
+    assert status == 200 and cancelled["state"] == "cancelled"
+    release.set()
+    time.sleep(0.2)
+    assert browser.get(f"/api/v1/runs/{run['run_id']}")[1]["state"] == "cancelled"
+
+
+def test_a_workflow_previews_and_runs_through_the_gateway(browser: Browser) -> None:
+    root = browser.g.roots[browser.workspace]
+    skill = root / "skills" / "demo"
+    skill.mkdir(parents=True)
+    (skill / "SKILL.md").write_text(
+        "---\nname: demo\ndescription: A demo skill for the gateway test.\nversion: 1.0.0\n---\n# Demo\nSay ping.\n"
+    )
+    from ananke.plexus.registry.registry import Registry
+
+    Registry.for_project(root, create=True).learn(str(skill), namespace="local")
+    subprocess.run(["git", "-C", str(root), "add", "-A"], check=True)
+    subprocess.run(
+        [
+            "git",
+            "-C",
+            str(root),
+            "-c",
+            "user.name=t",
+            "-c",
+            "user.email=t@example.com",
+            "commit",
+            "-qm",
+            "s",
+        ],
+        check=True,
+    )
+    draft = {
+        "schema_version": "1.0.0",
+        "workflow_id": "demo/one",
+        "nodes": [
+            {
+                "id": "a",
+                "capability_ref": "local/demo@1.0.0",
+                "kind": "skill",
+                "inputs": [],
+                "outputs": [],
+            }
+        ],
+        "edges": [],
+    }
+    status, preview = browser.post("/api/v1/plans/prepare", {"draft": draft})
+    assert status == 200 and preview["ok"]
+    _, run = browser.post(
+        "/api/v1/runs",
+        {
+            "kind": "workflow.run",
+            "parameters": {"draft": draft, "backend": "fake", "plan_hash": preview["plan_hash"]},
+            "idempotency_key": "w",
+        },
+    )
+    done = browser.finish(run["run_id"])
+    assert done["state"] == "succeeded" and done["complete"] is False
+    assert {w["code"] for w in done["warnings"]} == {"SIMULATED_BACKEND"}
+
+
+def test_an_unexpected_error_tells_the_browser_nothing_internal(
+    browser: Browser, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    def boom(*_: object, **__: object) -> None:
+        raise RuntimeError("secret path /home/me/.env")
+
+    monkeypatch.setattr(browser.g.client, "get_run", boom)
+    status, _, data = browser.raw("GET", f"/api/v1/runs/run-1?workspace={browser.workspace}")
+    assert status == 500 and b"secret" not in data and b"INTERNAL_ERROR" in data

{dev_guru-0.2.0 → dev_guru-0.3.0}/tests/test_negotiation.py

@@ -11,10 +11,10 @@ from dev_guru.client import inprocess, negotiation
 @pytest.mark.parametrize(
     ("version", "ok"),
     [
-        ("0.3.13", True),
-        ("0.3.12", False),
+        ("0.3.17", True),
+        ("0.3.16", False),
         ("0.3.99", True),
-        ("0.3.11", False),
+        ("0.3.13", False),
         ("0.4.0", False),
         ("1.0.0", False),
         ("junk", False),