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

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

@@ -10,6 +10,57 @@ 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 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.4.0}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.5
 Name: dev-guru
-Version: 0.2.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.13
+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,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 web interface: live runs, the code graph, your capabilities
 dev learning review NAME             # review what Ananke learned before it becomes reusable
 ```
 
@@ -103,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 |
 
@@ -118,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.2.0 → dev_guru-0.4.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 web interface: live runs, the code graph, your capabilities
 dev learning review NAME             # review what Ananke learned before it becomes reusable
 ```
 
@@ -60,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 |
 
@@ -75,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.2.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.13,<0.4",
+  "ananke-plexus>=0.3.19,<0.4",
   "markdown-it-py>=3,<5",
   "pydantic>=2.11,<3",
   "rich>=13",

{dev_guru-0.2.0 → dev_guru-0.4.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.4.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,58 @@ 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_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)))
+
+    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.4.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.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
-_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
@@ -53,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.2.0 → dev_guru-0.4.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,32 @@ 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_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]: ...
+
+    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.4.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.4.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"]