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

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

@@ -10,6 +10,41 @@ Format: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) — [SemVer](ht
 
 ---
 
+## [0.4.0] — 2026-11-03
+
+### Added
+
+- **A web interface in `dev serve`.** Overview, runs, a code view and capabilities from your sources, as plain files in
+  the package: no Node and no build step. Runs are shown live, survive a tab reload and a lost connection, name any
+  events no longer kept, and stop only when you press Cancel. It works from the keyboard and on a phone. Pages that
+  don't exist yet say so and name the commands that work today. Guide: [The local gateway](docs/guides/gateway.md).
+- `GET /api/v1/runs`, the runs in a workspace.
+- Real-Chrome journeys for the interface, on a temporary workspace they build themselves (`make web-journeys`, and part
+  of the acceptance suite).
+- [ROADMAP.md](ROADMAP.md): what's released and what's planned.
+- Dependabot for `uv` and GitHub Actions, with a seven-day cooldown.
+
+### Changed
+
+- Needs Ananke 0.3.19 or newer, for its fixes to path traversal and vulnerable dependencies.
+- CI grants `security-events: write` only to the jobs that upload findings.
+- Releases are created with `gh release` rather than a third-party action.
+- CI installs Trivy with retries and a pinned SHA-256 rather than through a third-party action, so one failed DNS lookup can't block a release.
+
+### Fixed
+
+- The run console could stop without showing a run's final event, if it read between the run's final state and that event.
+
+- The gateway answered a login token or CSRF token that wasn't ASCII with a `500`. It's now the usual refusal. No request
+  got through either way.
+
+### Security
+
+- Reviewed two Semgrep findings as false positives and marked each in the code with its reason. Reviewed findings no
+  longer reappear as new alerts when a line moves.
+
+---
+
 ## [0.3.0] — 2026-11-03
 
 ### Added

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

@@ -1,7 +1,7 @@
 Metadata-Version: 2.5
 Name: dev-guru
-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.
+Version: 0.4.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, offline HTML reports and a local web interface.
 Project-URL: Homepage, https://github.com/Neo-Pragnya/Dev-Guru
 Project-URL: Repository, https://github.com/Neo-Pragnya/Dev-Guru
 Project-URL: Issues, https://github.com/Neo-Pragnya/Dev-Guru/issues
@@ -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.17
+Requires-Dist: ananke-plexus<0.4,>=0.3.19
 Requires-Dist: markdown-it-py<5,>=3
 Requires-Dist: pydantic<3,>=2.11
 Requires-Dist: rich>=13
@@ -90,7 +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 serve                            # a local web interface: live runs, the code graph, your capabilities
 dev learning review NAME             # review what Ananke learned before it becomes reusable
 ```
 
@@ -104,11 +104,20 @@ with GuruClient(workspace="path/to/project") as guru:
     guru.export(result, output="explorer.html")
 ```
 
+## In your browser
+
+`dev serve` opens a web interface to what Ananke computes. It shows what's connected, starts and follows runs (which
+survive a reload or a lost connection, and stop only when you press Cancel), browses the code graph, and searches your
+capabilities. It listens only on your computer, only the link it prints gets in, and it needs no Node: everything comes
+from the [Dev Guru package on PyPI](https://pypi.org/project/dev-guru/). See [The local gateway](docs/guides/gateway.md).
+
+What's coming next, including code maps, flows, ERDs and CVE views, is in the [roadmap](ROADMAP.md).
+
 ## How it fits together
 
 | Repository | Role |
 | --- | --- |
-| **Dev Guru** (this repo) | The product: CLI and SDK, report view models and renderers, later a local web UI |
+| **Dev Guru** (this repo) | The product: CLI and SDK, report view models and renderers, a local web interface |
 | [Ananke Plexus](https://github.com/Neo-Pragnya/Ananke-Plexus) | The harness: code graph, analysis, workflows, policy, runs and evidence |
 | [Dex Trove](https://github.com/Neo-Pragnya/Dex-Trove) | Optional capability memory: curated skills, agents, instructions and workflows |
 
@@ -119,7 +128,8 @@ required. See [Architecture](docs/concepts/architecture.md) and [How Dev Guru ta
 
 ```bash
 make verify             # ruff, ruff format, strict mypy, pytest
-make acceptance-wheel   # capability scenarios on the built wheel, including real-Chrome report journeys
+make acceptance-wheel   # capability scenarios on the built wheel, including real-Chrome journeys
+make web-journeys       # just the web interface, in real Chrome, on a temporary workspace
 make scan               # gitleaks, pip-audit, GuardDog and Bandit on dist/
 ```
 

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

@@ -47,7 +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 serve                            # a local web interface: live runs, the code graph, your capabilities
 dev learning review NAME             # review what Ananke learned before it becomes reusable
 ```
 
@@ -61,11 +61,20 @@ with GuruClient(workspace="path/to/project") as guru:
     guru.export(result, output="explorer.html")
 ```
 
+## In your browser
+
+`dev serve` opens a web interface to what Ananke computes. It shows what's connected, starts and follows runs (which
+survive a reload or a lost connection, and stop only when you press Cancel), browses the code graph, and searches your
+capabilities. It listens only on your computer, only the link it prints gets in, and it needs no Node: everything comes
+from the [Dev Guru package on PyPI](https://pypi.org/project/dev-guru/). See [The local gateway](docs/guides/gateway.md).
+
+What's coming next, including code maps, flows, ERDs and CVE views, is in the [roadmap](ROADMAP.md).
+
 ## How it fits together
 
 | Repository | Role |
 | --- | --- |
-| **Dev Guru** (this repo) | The product: CLI and SDK, report view models and renderers, later a local web UI |
+| **Dev Guru** (this repo) | The product: CLI and SDK, report view models and renderers, a local web interface |
 | [Ananke Plexus](https://github.com/Neo-Pragnya/Ananke-Plexus) | The harness: code graph, analysis, workflows, policy, runs and evidence |
 | [Dex Trove](https://github.com/Neo-Pragnya/Dex-Trove) | Optional capability memory: curated skills, agents, instructions and workflows |
 
@@ -76,7 +85,8 @@ required. See [Architecture](docs/concepts/architecture.md) and [How Dev Guru ta
 
 ```bash
 make verify             # ruff, ruff format, strict mypy, pytest
-make acceptance-wheel   # capability scenarios on the built wheel, including real-Chrome report journeys
+make acceptance-wheel   # capability scenarios on the built wheel, including real-Chrome journeys
+make web-journeys       # just the web interface, in real Chrome, on a temporary workspace
 make scan               # gitleaks, pip-audit, GuardDog and Bandit on dist/
 ```
 

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

@@ -5,7 +5,7 @@ build-backend = "hatchling.build"
 [project]
 name = "dev-guru"
 dynamic = ["version"]
-description = "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."
+description = "Dev Guru: understand, improve, verify and learn from your software. A local-first developer product on the Ananke Plexus harness: Python SDK and CLI, offline HTML reports and a local web interface."
 readme = "README.md"
 requires-python = ">=3.11"
 license = "Apache-2.0"
@@ -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.17,<0.4",
+  "ananke-plexus>=0.3.19,<0.4",
   "markdown-it-py>=3,<5",
   "pydantic>=2.11,<3",
   "rich>=13",

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

@@ -125,6 +125,9 @@ class InProcessAnanke:
     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_history(self, workspace: Path) -> dict[str, Any]:
+        return dict(self._call(workspace, lambda f: f.evidence_view()))
+
     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)))
 

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

@@ -11,7 +11,7 @@ import importlib
 import re
 from importlib import metadata
 
-SUPPORTED_ANANKE = ">=0.3.17,<0.4"  # keep in step with pyproject.toml (tests/test_packaging.py)
+SUPPORTED_ANANKE = ">=0.3.19,<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
 
 # Capability id -> (module, attribute path). Required ones are what this release of Dev Guru calls.
@@ -57,6 +57,8 @@ def probe(capabilities: dict[str, tuple[str, str]] = CAPABILITIES) -> dict[str,
     found: dict[str, bool] = {}
     for cap, (module, attr_path) in capabilities.items():
         try:
+            # False positive: module names come from the fixed CAPABILITIES table above, never from a request or a file.
+            # nosemgrep: python.lang.security.audit.non-literal-import.non-literal-import
             obj: object = importlib.import_module(module)
             for part in attr_path.split("."):
                 obj = getattr(obj, part)

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

@@ -141,6 +141,8 @@ class AnankeClient(Protocol):
 
     def get_run(self, workspace: Path, run_id: str) -> dict[str, Any]: ...
 
+    def run_history(self, workspace: Path) -> 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]: ...

{dev_guru-0.3.0 → dev_guru-0.4.0}/src/dev_guru/gateway/server.py

@@ -19,6 +19,7 @@ import hmac
 import json
 import re
 import secrets
+import sys
 import threading
 from concurrent.futures import ThreadPoolExecutor
 from http.cookies import CookieError, SimpleCookie
@@ -35,6 +36,13 @@ HOST = "127.0.0.1"
 MAX_BODY_BYTES = 2_000_000
 RUN_WORKERS = 2
 CSRF_HEADER = "X-Dev-Guru-CSRF"
+# A fixed list, so no request path ever becomes a file path.
+_STATIC = {
+    "/": ("index.html", "text/html; charset=utf-8"),
+    "/app.js": ("app.js", "text/javascript; charset=utf-8"),
+    "/app.css": ("app.css", "text/css; charset=utf-8"),
+    "/favicon.svg": ("favicon.svg", "image/svg+xml"),
+}
 _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.
@@ -48,6 +56,20 @@ _REFUSAL_STATUS = {
 }
 
 
+def _same(sent: str, secret: str) -> bool:
+    """Compare in constant time. As bytes, because ``compare_digest`` raises on text that isn't ASCII."""
+    return hmac.compare_digest(sent.encode("utf-8", "replace"), secret.encode())
+
+
+class _Server(ThreadingHTTPServer):
+    daemon_threads = True
+
+    def handle_error(self, request: Any, client_address: Any) -> None:
+        """A browser dropping a connection is normal, and shouldn't print a stack trace in the user's terminal."""
+        if not isinstance(sys.exc_info()[1], ConnectionError):
+            super().handle_error(request, client_address)
+
+
 class _Reject(Exception):
     def __init__(self, status: int, code: str, message: str) -> None:
         super().__init__(message)
@@ -69,8 +91,7 @@ class Gateway:
         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._server = _Server((HOST, port), _handler_for(self))
         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}"}
@@ -84,13 +105,13 @@ class Gateway:
     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):
+            if self._login_token and _same(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)
+        return _same(value, self._session)
 
     def session_cookie(self) -> str:
         return f"{self.cookie_name}={self._session}; HttpOnly; SameSite=Strict; Path=/"
@@ -195,7 +216,7 @@ class _Handler(BaseHTTPRequestHandler):
 
     def _check_csrf(self) -> None:
         sent = self.headers.get(CSRF_HEADER, "")
-        if not hmac.compare_digest(sent, self.gateway.csrf):
+        if not _same(sent, self.gateway.csrf):
             raise _Reject(403, "CSRF_REJECTED", f"a change needs the {CSRF_HEADER} header")
 
     def _read_json(self) -> dict[str, Any]:
@@ -251,9 +272,10 @@ class _Handler(BaseHTTPRequestHandler):
             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")
+        served = _STATIC.get(url.path)
+        if served:
+            page = (Path(__file__).parent / "static" / served[0]).read_bytes()
+            self._send(200, page, served[1])
             return
         self._api_get(url.path, query)
 
@@ -309,6 +331,8 @@ class _Handler(BaseHTTPRequestHandler):
                     depth=self._int(query, "depth", 1),
                 )
             )
+        elif path == "/api/v1/runs":
+            self._json(client.run_history(root))
         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):

dev_guru-0.4.0/src/dev_guru/gateway/static/app.css

@@ -0,0 +1,73 @@
+/* Dev Guru "Lantern": warm parchment by day, plum-black lit by a flame at night. */
+:root {
+  color-scheme: light dark;
+  --bg: #fbf4e6; --surface: #fffaf1; --surface-2: #f5e9d2; --ink: #2a1d14; --muted: #6d5a49; --line: #e3cfab;
+  --link: #a33f0c; --ok: #0b6157; --bad: #a62a1a; --warn: #7a4900; --ok-soft: #d6f3ee; --bad-soft: #fde3dc; --warn-soft: #fff0d4;
+  --flame: linear-gradient(135deg, #ffd27a, #ffb347 35%, #ff6b3d 75%, #e94f7a);
+  --display: Georgia, "Times New Roman", serif;
+  --body: system-ui, -apple-system, "Segoe UI", Roboto, sans-serif;
+  --mono: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
+}
+:root[data-theme="dark"] {
+  --bg: #0f0b13; --surface: #1a121f; --surface-2: #241a2b; --ink: #f6ecdf; --muted: #bfae9f; --line: #3a2a41;
+  --link: #ffbe73; --ok: #7fe6d8; --bad: #ffb197; --warn: #ffd58e; --ok-soft: #0e2f2b; --bad-soft: #3a1b12; --warn-soft: #3a2a10;
+}
+* { box-sizing: border-box; }
+html, body { margin: 0; }
+body { min-height: 100vh; background: var(--bg); color: var(--ink); font: 16px/1.55 var(--body); }
+a { color: var(--link); }
+:focus-visible { outline: 3px solid #ff6b3d; outline-offset: 2px; border-radius: 4px; }
+main:focus { outline: none; }
+.skip { position: absolute; left: -999px; top: 8px; background: var(--surface); padding: 8px 12px; z-index: 5; }
+.skip:focus { left: 8px; }
+.top { display: flex; flex-wrap: wrap; align-items: center; gap: 12px 16px; padding: 12px 20px; background: var(--surface); border-bottom: 1px solid var(--line); }
+.brand { display: inline-flex; align-items: center; gap: 10px; font: 600 20px var(--display); color: var(--ink); text-decoration: none; margin-right: auto; }
+.flame { width: 14px; height: 20px; border-radius: 50% 50% 50% 50% / 62% 62% 38% 38%; background: var(--flame); box-shadow: 0 0 14px #ff8a3d99; animation: flicker 2.6s ease-in-out infinite; }
+@keyframes flicker { 0%, 100% { transform: scale(1); opacity: 1; } 40% { transform: scale(1.08, .95); opacity: .86; } 70% { transform: scale(.95, 1.06); opacity: .95; } }
+.field { display: inline-flex; align-items: center; gap: 8px; font-size: 14px; color: var(--muted); min-width: 0; }
+select, input { font: inherit; color: var(--ink); background: var(--bg); border: 1px solid var(--line); border-radius: 8px; padding: 6px 8px; max-width: 100%; min-width: 0; }
+button { font: inherit; font-weight: 600; cursor: pointer; border: 0; border-radius: 10px; padding: 8px 14px; background: var(--flame); color: #1d0f05; }
+button.ghost { background: transparent; color: var(--ink); border: 1px solid var(--line); font-weight: 500; }
+button:disabled { opacity: .55; cursor: default; }
+.pill { font-size: 13px; padding: 3px 10px; border-radius: 99px; background: var(--surface-2); overflow-wrap: anywhere; }
+.pill.ok, .succeeded { background: var(--ok-soft); color: var(--ok); }
+.pill.bad, .failed { background: var(--bad-soft); color: var(--bad); }
+.pill.warn, .cancelled { background: var(--warn-soft); color: var(--warn); }
+.running, .queued { position: relative; background: var(--warn-soft); color: var(--warn); animation: glow 1.4s ease-in-out infinite; }
+@keyframes glow { 50% { box-shadow: 0 0 12px #ff8a3d88; } }
+.banner { padding: 10px 20px; background: var(--warn-soft); color: var(--warn); border-bottom: 1px solid var(--line); overflow-wrap: anywhere; }
+.banner.bad { background: var(--bad-soft); color: var(--bad); }
+.layout { display: grid; grid-template-columns: 210px minmax(0, 1fr); }
+nav { padding: 18px 14px; border-right: 1px solid var(--line); display: flex; flex-direction: column; gap: 2px; }
+nav a { padding: 7px 10px; border-radius: 8px; color: var(--ink); text-decoration: none; }
+nav a:hover { background: var(--surface-2); }
+nav a[aria-current="page"] { background: var(--surface-2); font-weight: 600; box-shadow: inset 3px 0 0 #ff6b3d; }
+.nav-title { margin: 14px 10px 4px; font-size: 12px; letter-spacing: .06em; text-transform: uppercase; color: var(--muted); }
+.nav-title:first-child { margin-top: 0; }
+main { padding: 24px clamp(16px, 4vw, 40px) 60px; min-width: 0; }
+h1 { font: 600 30px/1.2 var(--display); margin: 0 0 6px; }
+h2 { font: 600 20px var(--display); margin: 26px 0 8px; }
+.lede { color: var(--muted); margin: 0 0 18px; max-width: 70ch; }
+.card { background: var(--surface); border: 1px solid var(--line); border-radius: 14px; padding: 16px 18px; margin: 12px 0; overflow-wrap: anywhere; }
+.cards { display: grid; gap: 12px; grid-template-columns: repeat(auto-fit, minmax(210px, 1fr)); }
+.cards .card { margin: 0; }
+.stat { font: 600 26px var(--display); display: block; }
+.row { display: flex; flex-wrap: wrap; gap: 10px; align-items: center; margin: 12px 0; }
+.wrap { overflow-x: auto; }
+table { border-collapse: collapse; width: 100%; font-size: 14px; }
+th, td { text-align: left; padding: 7px 10px; border-bottom: 1px solid var(--line); vertical-align: top; overflow-wrap: anywhere; }
+th { color: var(--muted); font-weight: 600; }
+code, .mono { font: 13px var(--mono); overflow-wrap: anywhere; }
+.events { list-style: none; margin: 0; padding: 0 0 0 18px; border-left: 2px solid var(--line); }
+.events li { position: relative; padding: 5px 0 5px 8px; animation: rise .3s ease-out; overflow-wrap: anywhere; }
+.events li::before { content: ""; position: absolute; left: -24px; top: 12px; width: 10px; height: 10px; border-radius: 50%; background: var(--flame); }
+@keyframes rise { from { opacity: 0; transform: translateY(4px); } }
+.muted { color: var(--muted); }
+.warning { border-left: 4px solid #ff6b3d; }
+@media (max-width: 760px) {
+  .layout { grid-template-columns: minmax(0, 1fr); }
+  nav { flex-direction: row; flex-wrap: wrap; border-right: 0; border-bottom: 1px solid var(--line); padding: 10px 12px; }
+  .nav-title { width: 100%; margin: 6px 4px 0; }
+  .brand { width: 100%; }
+}
+@media (prefers-reduced-motion: reduce) { *, *::before { animation: none !important; transition: none !important; } }

dev_guru-0.4.0/src/dev_guru/gateway/static/app.js

@@ -0,0 +1,405 @@
+// The Dev Guru web interface. No build step and no dependencies. Text from the server only ever reaches the page through
+// textContent, so a hostile file name or message stays text. All domain decisions are Ananke's; this only shows them.
+"use strict";
+
+const ACTIVE = new Set(["queued", "running"]);
+const POLL_MS = 1000;
+const MAX_BACKOFF_MS = 8000;
+const RUN_ID = /^run-[0-9a-f]+$/; // the only form the gateway accepts
+const LINK = /^(#\/|\/api\/v1\/)/; // pages here and gateway routes, so no value can become a javascript: link
+const state = { csrf: null, csrfHeader: null, workspaces: [], workspace: null, stop: null, graphKey: null, shown: 0 };
+
+function el(tag, props, ...children) {
+  const node = document.createElement(tag);
+  for (const [key, value] of Object.entries(props || {})) {
+    if (key === "text") node.textContent = value;
+    else if (key === "href" && !LINK.test(value)) throw new TypeError("not a link this interface makes");
+    else if (key === "on") for (const [name, fn] of Object.entries(value)) node.addEventListener(name, fn);
+    else if (value !== undefined && value !== null && value !== false) node.setAttribute(key, value === true ? "" : value);
+  }
+  for (const child of children) if (child !== null && child !== undefined) node.append(child);
+  return node;
+}
+
+class ApiError extends Error {
+  constructor(status, code, message, retryable) {
+    super(message);
+    Object.assign(this, { status, code, retryable });
+  }
+}
+
+async function api(path, body) {
+  const options = { credentials: "same-origin" };
+  if (body !== undefined) {
+    options.method = "POST";
+    options.headers = { "Content-Type": "application/json", [state.csrfHeader]: state.csrf };
+    options.body = JSON.stringify({ workspace: state.workspace, ...body });
+  }
+  let response;
+  try {
+    response = await fetch(path, options);
+  } catch {
+    throw new ApiError(0, "UNREACHABLE", "Can't reach the gateway.", true);
+  }
+  let data = null;
+  try {
+    data = await response.json();
+  } catch {
+    throw new ApiError(response.status, "BAD_RESPONSE", "The gateway sent an unreadable response.", false);
+  }
+  if (response.ok) return data;
+  const error = data.error || {};
+  if (response.status === 401) banner("Your session has ended. Run dev serve again and open the new link.", true);
+  throw new ApiError(response.status, error.code || "ERROR", error.message || "The request failed.", !!error.retryable);
+}
+
+const scoped = (path, query = {}) => {
+  const params = new URLSearchParams({ workspace: state.workspace, ...query });
+  return `${path}?${params}`;
+};
+
+function banner(text, bad = false) {
+  const node = document.querySelector("#banner");
+  node.hidden = !text;
+  node.textContent = text || "";
+  node.classList.toggle("bad", bad);
+}
+
+function showError(main, error, ...actions) {
+  main.append(el("div", { class: "card warning", role: "alert" },
+    el("strong", { text: error.code }), el("p", { text: error.message }), ...actions));
+}
+
+function page(title, lede) {
+  // A new section each time: whatever an earlier page is still waiting for lands in one that's gone.
+  const section = el("section", {}, el("h1", { text: title }));
+  if (lede) section.append(el("p", { class: "lede", text: lede }));
+  document.querySelector("#main").replaceChildren(section);
+  document.title = `${title} · Dev Guru`;
+  return section;
+}
+
+const statePill = (value) => el("span", { class: `pill ${value}`, text: value });
+
+function when(iso) {
+  const date = new Date(iso);
+  return Number.isNaN(date.getTime()) ? String(iso || "") : date.toLocaleString();
+}
+
+function warnings(run) {
+  return (run.warnings || []).map((w) => el("div", { class: "card warning" },
+    el("strong", { text: w.code }), el("p", { text: w.message })));
+}
+
+// ------------------------------------------------------------------ overview
+async function overview() {
+  const main = page("Overview", "What's connected. Ananke does the work; Dev Guru shows it to you.");
+  try {
+    const [health, caps, runs] = await Promise.all([
+      api("/api/v1/health"), api(scoped("/api/v1/capabilities")), api(scoped("/api/v1/runs")),
+    ]);
+    main.append(el("div", { class: "cards" },
+      el("div", { class: "card" }, el("span", { class: "stat", text: health.harness.ananke_version || "none" }), "Ananke Plexus"),
+      el("div", { class: "card" }, el("span", { class: "stat", text: health.gateway }), "Dev Guru"),
+      el("div", { class: "card" }, el("span", { class: "stat", text: String(runs.total) }), "Runs in this workspace")));
+    main.append(el("h2", { text: "What the harness can run" }));
+    main.append(el("div", { class: "row" }, ...caps.run_kinds.map((k) => el("code", { class: "pill", text: k }))));
+    main.append(el("div", { class: "row" }, el("a", { href: "#/runs", text: "Go to runs" }), el("a", { href: "#/code", text: "Explore the code" })));
+  } catch (error) {
+    showError(main, error);
+  }
+}
+
+// ------------------------------------------------------------------ runs
+async function startGraphRun(after) {
+  // Trying again after a lost connection repeats the same request, in case the first one did arrive.
+  state.graphKey = state.graphKey || crypto.randomUUID();
+  let run;
+  try {
+    run = await api("/api/v1/runs", { kind: "graph.build", parameters: {}, idempotency_key: state.graphKey });
+  } catch (error) {
+    if (error.status !== 0) state.graphKey = null;
+    throw error;
+  }
+  state.graphKey = null;
+  after(run);
+}
+
+async function runs() {
+  const main = page("Runs", "Runs live in Ananke, so they survive a reload or a closed tab.");
+  const start = el("button", { type: "button", id: "start-graph", text: "Build the code graph" });
+  const slot = el("div");
+  start.addEventListener("click", async () => {
+    start.disabled = true;
+    slot.replaceChildren();
+    try {
+      await startGraphRun((run) => { location.hash = `#/runs/${run.run_id}`; });
+    } catch (error) {
+      start.disabled = false;
+      const retry = error.code === "STALE_PLAN" ? el("button", { type: "button", class: "ghost", text: "Rescan and try again", on: { click: () => start.click() } }) : null;
+      showError(slot, error, retry);
+    }
+  });
+  main.append(el("div", { class: "row" }, start), slot);
+  try {
+    const history = await api(scoped("/api/v1/runs"));
+    if (!history.runs.length) {
+      main.append(el("p", { class: "muted", text: "No runs in this workspace yet." }));
+      return;
+    }
+    if (history.total > history.runs.length) main.append(el("p", { class: "muted", text: `The latest ${history.runs.length} of ${history.total} runs.` }));
+    const body = el("tbody");
+    for (const run of history.runs) {
+      body.append(el("tr", {},
+        el("td", {}, el("a", { href: `#/runs/${run.run_id}`, class: "mono", text: run.run_id })),
+        el("td", { text: run.kind }), el("td", {}, statePill(run.state)), el("td", { text: when(run.created_at) })));
+    }
+    main.append(el("div", { class: "wrap" }, el("table", {},
+      el("thead", {}, el("tr", {}, ...["Run", "Kind", "State", "Started"].map((h) => el("th", { scope: "col", text: h })))), body)));
+  } catch (error) {
+    showError(main, error);
+  }
+}
+
+async function runDetail(runId, loaded) {
+  const main = page("Run", "");
+  main.append(el("p", { class: "mono", id: "run-id", text: runId }));
+  const head = el("div", { class: "row", id: "run-state" });
+  const notes = el("div", { id: "run-warnings" });
+  const timeline = el("ol", { class: "events", id: "events", "aria-label": "Run events" });
+  const files = el("div", { id: "artifacts" });
+  const cancel = el("button", { type: "button", class: "ghost", id: "cancel", text: "Cancel run", hidden: true });
+  main.append(head, el("div", { class: "row" }, cancel), notes, el("h2", { text: "Events" }), timeline, el("h2", { text: "Artifacts" }), files,
+    el("p", {}, el("a", { href: "#/runs", text: "All runs" })));
+
+  let stopped = false;
+  state.stop = () => { stopped = true; };
+  let after = 0;
+  let wait = POLL_MS;
+  let lastEvent = null;
+  // Ananke records a run's final state just before its final event, so a read can land between the two.
+  let finalChecks = 3;
+
+  cancel.addEventListener("click", async () => {
+    cancel.disabled = true;
+    try {
+      await api(`/api/v1/runs/${runId}/cancel`, {});
+    } catch (error) {
+      cancel.disabled = false;
+      banner(`${error.code}: ${error.message}`, true);
+    }
+  });
+
+  const addEvent = (event) => {
+    const text = event.payload && event.payload.step ? `${event.type}: ${event.payload.step}` : event.type;
+    timeline.append(el("li", {}, el("span", { text }), " ", el("span", { class: "muted", text: when(event.at) })));
+  };
+
+  async function refresh() {
+    const run = await api(scoped(`/api/v1/runs/${runId}`));
+    head.replaceChildren(statePill(run.state), el("span", { text: run.kind }),
+      run.complete ? el("span", { class: "muted", text: "Evidence complete" }) : null);
+    cancel.hidden = !ACTIVE.has(run.state);
+    notes.replaceChildren(...warnings(run));
+    const seen = await api(scoped(`/api/v1/runs/${runId}/events`, { after }));
+    if (seen.gap) timeline.append(el("li", { class: "muted", text: `Events ${seen.gap.from} to ${seen.gap.to} are no longer kept.` }));
+    for (const event of seen.events) { addEvent(event); after = event.seq; lastEvent = event.type; }
+    const listed = await api(scoped(`/api/v1/runs/${runId}/artifacts`));
+    files.replaceChildren(listed.artifacts.length
+      ? el("ul", {}, ...listed.artifacts.map((a) => el("li", {},
+        el("a", { href: scoped(`/api/v1/runs/${runId}/artifacts/${encodeURIComponent(a.name)}`), download: a.name, text: a.name }),
+        el("span", { class: "muted", text: ` ${a.size} bytes · ${a.producer}` }))))
+      : el("p", { class: "muted", text: ACTIVE.has(run.state) ? "None yet." : "This run produced none." }));
+    return run;
+  }
+
+  while (!stopped) {
+    try {
+      const run = await refresh();
+      if (stopped) return;
+      banner("");
+      wait = POLL_MS;
+      if (!ACTIVE.has(run.state) && (lastEvent === `run.${run.state}` || --finalChecks <= 0)) return;
+    } catch (error) {
+      if (stopped) return;
+      if (!error.retryable) {
+        showError(main, error);
+        return;
+      }
+      banner(`Connection lost. The run carries on in Ananke. Trying again in ${Math.round(wait / 1000)}s.`);
+      wait = Math.min(wait * 2, MAX_BACKOFF_MS);
+    } finally {
+      loaded();
+    }
+    await new Promise((resolve) => setTimeout(resolve, wait));
+  }
+}
+
+// ------------------------------------------------------------------ code
+async function code(query) {
+  const main = page("Code", "A view of Ananke's code graph, kept within a node budget. Nothing here changes your files.");
+  const collapse = query.get("collapse") || "directory";
+  const path = query.get("path") || "";
+  const go = (changes) => {
+    const next = new URLSearchParams({ collapse, ...(path ? { path } : {}), ...changes });
+    if (!next.get("path")) next.delete("path");
+    location.hash = `#/code?${next}`;
+  };
+  const select = el("select", { id: "collapse", on: { change: (e) => go({ collapse: e.target.value }) } },
+    ...[["directory", "Folders"], ["file", "Files"], ["none", "Every symbol"]].map(([value, text]) =>
+      el("option", { value, text, selected: value === collapse })));
+  main.append(el("div", { class: "row" }, el("label", { class: "field" }, "Group by", select),
+    path ? el("button", { type: "button", class: "ghost", text: `Showing ${path}: show everything`, on: { click: () => go({ path: "" }) } }) : null));
+  try {
+    const view = await api(scoped("/api/v1/code", { collapse, budget: 200, ...(path ? { path } : {}) }));
+    const a = view.edge_accounting;
+    main.append(el("p", { class: "muted", id: "accounting",
+      text: `${view.nodes.length} of ${view.total_nodes} shown. Links: ${a.shown} shown, ${a.inside_a_group} inside a group, ${a.to_nodes_not_shown} to items not shown, ${a.external_imports} third-party imports.` }));
+    if (view.truncated) main.append(el("p", { class: "muted", text: "Over budget: the most connected items are shown. Narrow it down by opening a folder." }));
+    const body = el("tbody");
+    for (const node of view.nodes) {
+      const openable = node.kind === "directory" || node.kind === "file";
+      const name = openable && collapse !== "none"
+        ? el("button", { type: "button", class: "ghost", text: node.path || node.name, on: { click: () => go(node.kind === "directory" ? { collapse: "file", path: node.path === "." ? "" : `${node.path}/` } : { collapse: "none", path: node.path }) } })
+        : el("span", { text: node.name });
+      body.append(el("tr", {}, el("td", {}, name), el("td", { text: node.kind }),
+        el("td", { class: "mono", text: node.members !== undefined ? `${node.members} items` : (node.source_location || "") })));
+    }
+    main.append(el("div", { class: "wrap" }, el("table", { id: "code-table" },
+      el("thead", {}, el("tr", {}, ...["Name", "Kind", "Where"].map((h) => el("th", { scope: "col", text: h })))), body)));
+    main.append(el("h2", { text: "Links" }));
+    const links = el("tbody");
+    for (const edge of view.edges.slice(0, 200)) {
+      const kinds = edge.kinds ? Object.entries(edge.kinds).map(([k, n]) => `${k} ${n}`).join(", ") : edge.kind;
+      const inferred = edge.origins ? edge.origins.inferred > 0 : edge.origin === "inferred";
+      links.append(el("tr", {}, el("td", { class: "mono", text: edge.source }), el("td", { class: "mono", text: edge.target }),
+        el("td", { text: inferred ? `${kinds} (includes inferred)` : kinds })));
+    }
+    main.append(view.edges.length ? el("div", { class: "wrap" }, el("table", { id: "link-table" },
+      el("thead", {}, el("tr", {}, ...["From", "To", "How"].map((h) => el("th", { scope: "col", text: h })))), links))
+      : el("p", { class: "muted", text: "No links between these items." }));
+    if (view.edges.length > 200) main.append(el("p", { class: "muted", text: `The first 200 of ${view.edges.length} links.` }));
+    main.append(el("p", { class: "muted mono", text: `Source ${view.source_snapshot}` }));
+  } catch (error) {
+    const build = error.code === "GRAPH_MISSING"
+      ? el("button", { type: "button", id: "build-graph", text: "Build the code graph", on: { click: () => startGraphRun((run) => { location.hash = `#/runs/${run.run_id}`; }).catch((e) => banner(`${e.code}: ${e.message}`, true)) } })
+      : null;
+    showError(main, error, build);
+  }
+}
+
+// ------------------------------------------------------------------ capabilities
+async function sources(query) {
+  const main = page("Capabilities", "What your configured sources offer. Being listed doesn't mean a capability is trusted or will run.");
+  const words = query.get("q") || "";
+  const input = el("input", { type: "search", id: "search", value: words, "aria-label": "Search capabilities", placeholder: "Search" });
+  const form = el("form", { class: "row", on: { submit: (e) => { e.preventDefault(); location.hash = `#/sources?${new URLSearchParams({ q: input.value })}`; } } },
+    input, el("button", { type: "submit", class: "ghost", text: "Search" }));
+  main.append(form);
+  try {
+    const found = await api(scoped("/api/v1/sources", { q: words }));
+    if (!found.capabilities.length) {
+      main.append(el("p", { class: "muted", text: words ? "Nothing matches." : "No capabilities from this workspace's sources." }));
+      return;
+    }
+    const body = el("tbody");
+    for (const c of found.capabilities) {
+      body.append(el("tr", {}, el("td", { class: "mono", text: c.identity }), el("td", { text: c.kind }),
+        el("td", { text: c.version }), el("td", { text: c.licence }), el("td", { text: c.summary })));
+    }
+    main.append(el("div", { class: "wrap" }, el("table", {},
+      el("thead", {}, el("tr", {}, ...["Identity", "Kind", "Version", "Licence", "About"].map((h) => el("th", { scope: "col", text: h })))), body)));
+  } catch (error) {
+    showError(main, error);
+  }
+}
+
+// ------------------------------------------------------------------ not here yet: say so, and say what works today
+const UNSUPPORTED = {
+  workflows: ["Workflows", "Assembling workflows in the browser isn't in this version.", ["ananke app workflow-preview DRAFT", "ananke app workflow-run DRAFT --backend B --plan-hash H --key K"]],
+  quality: ["Quality", "Quality views aren't in this version.", ["dev explore ."]],
+  docs: ["Documentation", "The documentation studio isn't in this version.", ["dev present SLIDES.md", "dev diagram DOCUMENT.md"]],
+  learning: ["Learning review", "Reviewing learning candidates in the browser isn't in this version.", ["dev learning review NAME"]],
+};
+
+function unsupported([title, text, commands]) {
+  const main = page(title, text);
+  main.append(el("h2", { text: "What works today" }), el("ul", {}, ...commands.map((c) => el("li", {}, el("code", { text: c })))));
+}
+
+// ------------------------------------------------------------------ shell
+async function route(moveFocus = true) {
+  if (state.stop) state.stop();
+  state.stop = null;
+  banner("");
+  const [path, search] = location.hash.replace(/^#\/?/, "").split("?");
+  const query = new URLSearchParams(search || "");
+  const [section, id] = path.split("/");
+  for (const link of document.querySelectorAll("nav a")) {
+    if (link.dataset.route === section) link.setAttribute("aria-current", "page");
+    else link.removeAttribute("aria-current");
+  }
+  const main = document.querySelector("#main");
+  const shown = ++state.shown;
+  // busy until this page has its data; a later page takes over the mark
+  const loaded = () => { if (shown === state.shown) main.removeAttribute("aria-busy"); };
+  main.setAttribute("aria-busy", "true");
+  if (section === "runs" && id) {
+    if (!RUN_ID.test(id)) { page("Not found", "That isn't a run's address."); loaded(); if (moveFocus) main.focus(); return; }
+    const detail = runDetail(id, loaded);
+    if (moveFocus) main.focus();
+    await detail;
+    return;
+  }
+  if (section === "") await overview();
+  else if (section === "runs") await runs();
+  else if (section === "code") await code(query);
+  else if (section === "sources") await sources(query);
+  else if (Object.hasOwn(UNSUPPORTED, section)) unsupported(UNSUPPORTED[section]);
+  else page("Not found", "There's no such page.");
+  loaded();
+  if (moveFocus && shown === state.shown) main.focus(); // not on first load: the keyboard starts at the top, with the skip link
+}
+
+function setTheme(theme) {
+  document.documentElement.dataset.theme = theme;
+  try { localStorage.setItem("dev-guru-theme", theme); } catch { /* the choice just won't be remembered */ }
+}
+
+async function init() {
+  let saved = null;
+  try { saved = localStorage.getItem("dev-guru-theme"); } catch { /* not available here */ }
+  setTheme(saved || (matchMedia("(prefers-color-scheme: dark)").matches ? "dark" : "light"));
+  document.querySelector("#theme").addEventListener("click", () => setTheme(document.documentElement.dataset.theme === "dark" ? "light" : "dark"));
+  // The address holds the page, so the skip link moves focus instead of changing it.
+  document.querySelector(".skip").addEventListener("click", (event) => { event.preventDefault(); document.querySelector("#main").focus(); });
+  try {
+    const session = await api("/api/v1/session");
+    state.csrf = session.csrf_token;
+    state.csrfHeader = session.csrf_header;
+    state.workspaces = (await api("/api/v1/workspaces")).workspaces;
+    const health = await api("/api/v1/health");
+    const pill = document.querySelector("#harness");
+    pill.textContent = health.ok ? `Ananke ${health.harness.ananke_version}` : "Ananke isn't compatible";
+    pill.classList.add(health.ok ? "ok" : "bad");
+  } catch (error) {
+    showError(page("Dev Guru", ""), error);
+    return;
+  }
+  const picker = document.querySelector("#workspace");
+  for (const w of state.workspaces) picker.append(el("option", { value: w.id, title: w.path, text: w.name }));
+  let remembered = null;
+  try { remembered = sessionStorage.getItem("dev-guru-workspace"); } catch { /* not available here */ }
+  state.workspace = state.workspaces.some((w) => w.id === remembered) ? remembered : state.workspaces[0].id;
+  picker.value = state.workspace;
+  picker.addEventListener("change", () => {
+    state.workspace = picker.value;
+    try { sessionStorage.setItem("dev-guru-workspace", state.workspace); } catch { /* not available here */ }
+    if (location.hash.startsWith("#/runs/")) location.hash = "#/runs";
+    else route();
+  });
+  addEventListener("hashchange", () => route());
+  route(false);
+}
+
+init();

dev_guru-0.4.0/src/dev_guru/gateway/static/favicon.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 32"><defs><linearGradient id="f" x1="0" y1="0" x2="1" y2="1"><stop offset="0" stop-color="#ffd27a"/><stop offset="1" stop-color="#ff6b3d"/></linearGradient></defs><rect width="32" height="32" rx="8" fill="#120d16"/><path d="M16 5c1 5 7 8 7 14a7 7 0 0 1-14 0c0-3 2-5 3-7 1 2 2 3 3 3 1-3 0-7 1-10z" fill="url(#f)"/></svg>

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

@@ -0,0 +1,37 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Dev Guru</title>
+<link rel="icon" href="/favicon.svg" type="image/svg+xml">
+<link rel="stylesheet" href="/app.css">
+<script src="/app.js" defer></script>
+</head>
+<body>
+<a class="skip" href="#main">Skip to content</a>
+<header class="top">
+  <a class="brand" href="#/"><span class="flame" aria-hidden="true"></span>Dev Guru</a>
+  <label class="field">Workspace <select id="workspace"></select></label>
+  <span id="harness" class="pill" role="status"></span>
+  <button id="theme" class="ghost" type="button">Theme</button>
+</header>
+<div id="banner" class="banner" role="status" aria-live="polite" hidden></div>
+<div class="layout">
+  <nav aria-label="Main">
+    <p class="nav-title">Available</p>
+    <a href="#/" data-route="">Overview</a>
+    <a href="#/runs" data-route="runs">Runs</a>
+    <a href="#/code" data-route="code">Code</a>
+    <a href="#/sources" data-route="sources">Capabilities</a>
+    <p class="nav-title">Not in this version</p>
+    <a href="#/workflows" data-route="workflows">Workflows</a>
+    <a href="#/quality" data-route="quality">Quality</a>
+    <a href="#/docs" data-route="docs">Documentation</a>
+    <a href="#/learning" data-route="learning">Learning review</a>
+  </nav>
+  <main id="main" tabindex="-1"></main>
+</div>
+<noscript><p>This interface needs JavaScript. The <code>dev</code> commands work without it.</p></noscript>
+</body>
+</html>

{dev_guru-0.3.0 → dev_guru-0.4.0}/src/dev_guru/reports/render.py

@@ -21,6 +21,9 @@ import os
 import re
 import subprocess
 from datetime import UTC, datetime
+
+# False positive: this package needs Python 3.11 or newer (requires-python), where importlib.resources always exists.
+# nosemgrep: python.lang.compatibility.python37.python37-compatibility-importlib2
 from importlib import resources
 from pathlib import Path
 from typing import Any

{dev_guru-0.3.0 → dev_guru-0.4.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.3.0"
+__version__ = "0.4.0"

{dev_guru-0.3.0 → dev_guru-0.4.0}/tests/test_gateway.py

@@ -4,6 +4,9 @@ from __future__ import annotations
 
 import http.client
 import json
+import re
+import socket
+import struct
 import subprocess
 import threading
 import time
@@ -421,3 +424,224 @@ def test_an_unexpected_error_tells_the_browser_nothing_internal(
     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
+
+
+def test_a_browser_dropping_a_connection_prints_nothing(
+    gateway: Gateway, capfd: pytest.CaptureFixture[str]
+) -> None:
+    conn = socket.create_connection((HOST, gateway.port))
+    conn.setsockopt(
+        socket.SOL_SOCKET, socket.SO_LINGER, struct.pack("ii", 1, 0)
+    )  # close with a reset
+    conn.send(b"GET ")
+    conn.close()
+    time.sleep(0.3)
+    assert "Traceback" not in capfd.readouterr().err
+
+
+@pytest.mark.parametrize(
+    ("path", "media"),
+    [
+        ("/", "text/html"),
+        ("/app.js", "text/javascript"),
+        ("/app.css", "text/css"),
+        ("/favicon.svg", "image/svg+xml"),
+    ],
+)
+def test_the_interface_files_need_a_session_and_have_the_right_type(
+    browser: Browser, gateway: Gateway, path: str, media: str
+) -> None:
+    assert Browser(gateway).raw("GET", path)[0] == 401
+    status, headers, body = browser.raw("GET", path)
+    assert status == 200 and headers["content-type"].startswith(media) and body
+
+
+@pytest.mark.parametrize(
+    "path", ["/index.html", "/static/app.js", "/../server.py", "/app.js/../../server.py"]
+)
+def test_only_listed_files_are_served(browser: Browser, path: str) -> None:
+    assert browser.raw("GET", path)[0] == 404
+
+
+def test_the_page_has_no_inline_code_for_the_content_policy_to_block(browser: Browser) -> None:
+    _, _, page = browser.raw("GET", "/")
+    text = page.decode()
+    assert "<style" not in text and " onclick" not in text
+    assert all('src="' in tag for tag in text.split("<script")[1:])
+
+
+# ------------------------------------------------------------------ every route, not just the first ones written
+GET_ROUTES = [
+    "/",
+    "/app.js",
+    "/app.css",
+    "/favicon.svg",
+    "/api/v1/session",
+    "/api/v1/health",
+    "/api/v1/workspaces",
+    "/api/v1/capabilities?workspace=W",
+    "/api/v1/sources?workspace=W",
+    "/api/v1/code?workspace=W",
+    "/api/v1/runs?workspace=W",
+    "/api/v1/runs/run-0123?workspace=W",
+    "/api/v1/runs/run-0123/events?workspace=W",
+    "/api/v1/runs/run-0123/artifacts?workspace=W",
+    "/api/v1/runs/run-0123/artifacts/graph-snapshot.json?workspace=W",
+]
+POST_ROUTES = ["/api/v1/plans/prepare", "/api/v1/runs", "/api/v1/runs/run-0123/cancel"]
+
+
+@pytest.mark.parametrize("path", GET_ROUTES)
+def test_every_read_needs_a_session_and_refuses_other_sites(
+    browser: Browser, gateway: Gateway, path: str
+) -> None:
+    target = path.replace("W", browser.workspace)
+    assert Browser(gateway).raw("GET", target)[0] == 401
+    for headers in ({"Origin": "https://evil.example"}, {"Sec-Fetch-Site": "cross-site"}):
+        status, sent, data = browser.raw("GET", target, headers=headers)
+        assert status == 403 and json.loads(data)["error"]["code"] == "ORIGIN_REJECTED"
+        assert "access-control-allow-origin" not in sent
+
+
+@pytest.mark.parametrize("path", POST_ROUTES)
+def test_every_change_needs_session_origin_csrf_and_json(
+    browser: Browser, gateway: Gateway, path: str
+) -> None:
+    body = json.dumps({"workspace": browser.workspace}).encode()
+    good = {"Origin": browser.origin, "Content-Type": "application/json", CSRF_HEADER: gateway.csrf}
+    for change, expected in (
+        ({"Origin": ""}, "ORIGIN_REJECTED"),
+        ({"Origin": "https://evil.example"}, "ORIGIN_REJECTED"),
+        ({"Origin": "null"}, "ORIGIN_REJECTED"),
+        ({"Sec-Fetch-Site": "same-site"}, "ORIGIN_REJECTED"),
+        ({CSRF_HEADER: ""}, "CSRF_REJECTED"),
+        ({CSRF_HEADER: "guess"}, "CSRF_REJECTED"),
+        ({"Content-Type": "text/plain"}, "UNSUPPORTED_MEDIA_TYPE"),
+    ):
+        status, _, data = browser.raw("POST", path, headers={**good, **change}, body=body)
+        assert status >= 400 and json.loads(data)["error"]["code"] == expected, change
+    assert Browser(gateway).raw("POST", path, headers=good, body=body)[0] == 401
+    assert not (browser.g.roots[browser.workspace] / ".ananke" / "app" / "runs").exists()
+
+
+@pytest.mark.parametrize("method", ["PUT", "PATCH", "DELETE", "OPTIONS", "HEAD", "TRACE"])
+def test_other_methods_are_refused_with_no_cors(browser: Browser, method: str) -> None:
+    status, headers, _ = browser.raw(method, "/api/v1/runs", headers={"Origin": browser.origin})
+    assert status == 405 and "access-control-allow-origin" not in headers
+
+
+@pytest.mark.parametrize(
+    ("change", "status", "expected"),
+    [
+        ({"Cookie": "dev_guru_session_PORT=caf\xe9"}, 401, "NOT_AUTHENTICATED"),
+        ({CSRF_HEADER: "caf\xe9"}, 403, "CSRF_REJECTED"),
+    ],
+)
+def test_text_that_isnt_ascii_is_a_refusal_not_a_crash(
+    browser: Browser, gateway: Gateway, change: dict[str, str], status: int, expected: str
+) -> None:
+    sent = {
+        "Origin": browser.origin,
+        "Content-Type": "application/json",
+        CSRF_HEADER: gateway.csrf,
+        "Cookie": browser.cookie,
+        **{k: v.replace("PORT", str(gateway.port)) for k, v in change.items()},
+    }
+    body = json.dumps({"workspace": browser.workspace}).encode()
+    got, _, data = browser.raw("POST", "/api/v1/runs", headers=sent, body=body)
+    assert got == status and json.loads(data)["error"]["code"] == expected
+
+
+def test_a_login_token_that_isnt_ascii_is_a_refusal_not_a_crash(gateway: Gateway) -> None:
+    status, _, data = Browser(gateway).raw("GET", "/login?token=caf%C3%A9")
+    assert status == 401 and json.loads(data)["error"]["code"] == "NOT_AUTHENTICATED"
+
+
+def test_the_content_policy_is_strict_on_everything_served(
+    browser: Browser, gateway: Gateway
+) -> None:
+    answers = [browser.raw("GET", path.replace("W", browser.workspace)) for path in GET_ROUTES[:9]]
+    answers.append(Browser(gateway).raw("GET", "/"))  # a refusal
+    answers.append(browser.raw("GET", "/nope"))
+    for _, headers, _ in answers:
+        policy = headers["content-security-policy"]
+        assert "default-src 'self'" in policy and "frame-ancestors 'none'" in policy
+        assert "base-uri 'none'" in policy and "unsafe" not in policy and "*" not in policy
+        assert headers["x-content-type-options"] == "nosniff"
+
+
+# ------------------------------------------------------------------ what the page does with server text
+STATIC = Path(__file__).parents[1] / "src" / "dev_guru" / "gateway" / "static"
+
+
+def test_server_text_has_no_way_to_become_markup() -> None:
+    script = (STATIC / "app.js").read_text()
+    for sink in (
+        "innerHTML",
+        "outerHTML",
+        "insertAdjacentHTML",
+        "document.write",
+        "eval(",
+        "new Function",
+        "srcdoc",
+        'setAttribute("on',
+    ):
+        assert sink not in script, sink
+
+
+def test_every_link_the_page_builds_starts_somewhere_fixed() -> None:
+    script = (STATIC / "app.js").read_text()
+    hrefs = re.findall(r"\bhref:\s*([^,}]+)", script)
+    assert len(hrefs) >= 4
+    for value in hrefs:
+        assert value.startswith(('"#/', "`#/", "scoped(`/api/v1/")), value
+    assert ".href =" not in script and 'setAttribute("href"' not in script
+    assert 'if (key === "href" && !LINK.test(value))' in script
+    assert "const LINK = /^(#\\/|\\/api\\/v1\\/)/;" in script
+
+
+def test_the_page_loads_only_this_gateways_files() -> None:
+    page = (STATIC / "index.html").read_text()
+    assert "http://" not in page and "https://" not in page and "//" not in page.replace("<!--", "")
+    assert set(re.findall(r'(?:src|href)="(/[^"]*)"', page)) == {
+        "/favicon.svg",
+        "/app.css",
+        "/app.js",
+    }
+    for name in ("app.js", "app.css", "favicon.svg"):
+        text = (STATIC / name).read_text()
+        assert "http://" not in text.replace("http://www.w3.org/2000/svg", "")
+        assert "https://" not in text and "@import" not in text
+
+
+# ------------------------------------------------------------------ the run console's API
+def test_run_history_lists_runs_newest_first(browser: Browser) -> None:
+    assert browser.get("/api/v1/runs")[1] == {"total": 0, "runs": []}
+    _, one = browser.post("/api/v1/runs", {"kind": "graph.build", "idempotency_key": "one"})
+    browser.finish(one["run_id"])
+    _, two = browser.post("/api/v1/runs", {"kind": "graph.build", "idempotency_key": "two"})
+    browser.finish(two["run_id"])
+    status, history = browser.get("/api/v1/runs")
+    assert status == 200 and history["total"] == 2
+    assert {r["run_id"] for r in history["runs"]} == {one["run_id"], two["run_id"]}
+    assert history["runs"][0]["created_at"] >= history["runs"][1]["created_at"]
+
+
+def test_events_dropped_from_the_record_come_back_as_a_gap_with_the_run(browser: Browser) -> None:
+    _, run = browser.post("/api/v1/runs", {"kind": "graph.build", "idempotency_key": "g"})
+    browser.finish(run["run_id"])
+    log = (
+        browser.g.roots[browser.workspace]
+        / ".ananke"
+        / "app"
+        / "runs"
+        / run["run_id"]
+        / "events.jsonl"
+    )
+    lines = log.read_text().splitlines()
+    log.write_text("\n".join(lines[2:]) + "\n")
+    status, seen = browser.get(f"/api/v1/runs/{run['run_id']}/events")
+    assert status == 200 and seen["gap"] == {"from": 1, "to": 2}
+    assert seen["run"]["state"] == "succeeded" and seen["events"][-1]["type"] == "run.succeeded"
+    last = seen["events"][-1]["seq"]
+    assert "gap" not in browser.get(f"/api/v1/runs/{run['run_id']}/events?after={last}")[1]

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

@@ -11,8 +11,8 @@ from dev_guru.client import inprocess, negotiation
 @pytest.mark.parametrize(
     ("version", "ok"),
     [
-        ("0.3.17", True),
-        ("0.3.16", False),
+        ("0.3.19", True),
+        ("0.3.18", False),
         ("0.3.99", True),
         ("0.3.13", False),
         ("0.4.0", False),

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

@@ -1,12 +0,0 @@
-<!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>