compass-code 0.1.0__py3-none-any.whl

compass_cli/commands/ingest.py

@@ -0,0 +1,310 @@
+"""The `compass ingest` command."""
+
+from __future__ import annotations
+
+import time
+from pathlib import Path
+
+import typer
+
+import compass_core.languages.python  # noqa: F401 — registers the Python plugin
+from compass_cli import display
+from compass_cli.errors import handle_errors
+from compass_cli.progress import IngestReporter
+from compass_cli.types import IngestSummary
+from compass_core.ir.graph import ResolvedGraph
+from compass_core.logger import setup as setup_logging
+from compass_core.phases.base import IngestContext
+from compass_core.phases.pipeline import Pipeline
+from compass_core.shared_types import Language, SymbolKind
+
+
+def _format_debug_section(phase: str, ctx: IngestContext) -> str:
+    """Human-readable dump of everything a phase produced, for --debug-log."""
+    lines: list[str] = [f"===== {phase} =====", ""]
+
+    if phase == "discovery":
+        assert ctx.manifest is not None
+        m = ctx.manifest
+        lines.append(
+            f"dirs_scanned={m.dirs_scanned} ignored_count={m.ignored_count} files={len(m.files)}"
+        )
+        lines.append("")
+        for f in m.files:
+            lines.append(f"  {f.path}  [{f.language}]  {f.content_hash}")
+
+    elif phase == "parse":
+        assert ctx.parsed_files is not None
+        for pf in ctx.parsed_files:
+            lines.append(f"  {pf.path}  [{pf.language}]  module={pf.module_name}")
+            if pf.degraded:
+                lines.append(f"    DEGRADED: {pf.error}")
+            lines.append(
+                f"    definitions={len(pf.definitions)} imports={len(pf.imports)} "
+                f"call_sites={len(pf.call_sites)}"
+            )
+            for d in pf.definitions:
+                lines.append(f"      {d.kind.value}: {d.id}  (lines {d.line_start}-{d.line_end})")
+                if d.signature:
+                    lines.append(f"        signature: {d.signature}")
+                if d.docstring:
+                    lines.append(f"        docstring: {d.docstring!r}")
+                if d.raw_calls:
+                    lines.append(f"        raw_calls: {d.raw_calls}")
+                lines.append("        source:")
+                for src_line in d.source.splitlines():
+                    lines.append(f"          {src_line}")
+
+    elif phase == "symbol_table":
+        assert ctx.symbol_table is not None
+        assert ctx.import_map is not None
+        lines.append(f"symbol_table ({len(ctx.symbol_table)} entries):")
+        for symbol_key, symbol_id in ctx.symbol_table.items():
+            lines.append(f"  {symbol_key} -> {symbol_id}")
+        lines.append("")
+        lines.append(f"import_map ({len(ctx.import_map)} entries):")
+        for module_path, imported_names in ctx.import_map.items():
+            lines.append(f"  {module_path} -> {imported_names}")
+
+    elif phase == "resolution":
+        assert ctx.resolved_graph is not None
+        g = ctx.resolved_graph
+        lines.append(f"call_edges ({len(g.call_edges)}):")
+        for call in g.call_edges:
+            lines.append(
+                f"  {call.caller_id} -> {call.callee_id}  [{call.call_type} conf={call.confidence}]"
+            )
+        lines.append("")
+        lines.append(f"external_call_edges ({len(g.external_call_edges)}):")
+        for ext_call in g.external_call_edges:
+            lines.append(f"  {ext_call.caller_id} -> {ext_call.full_ref}  [{ext_call.library}]")
+        lines.append("")
+        lines.append(f"import_edges ({len(g.import_edges)}):")
+        for imp in g.import_edges:
+            lines.append(f"  {imp.from_path} -> {imp.to_path}")
+        lines.append("")
+        lines.append(f"inherit_edges ({len(g.inherit_edges)}):")
+        for inherit in g.inherit_edges:
+            lines.append(f"  {inherit.child_id} -> {inherit.parent_id}")
+
+    elif phase == "validation":
+        assert ctx.report is not None
+        r = ctx.report
+        lines.append(f"orphan_node_count={r.orphan_node_count}")
+        lines.append(f"dangling_import_count={r.dangling_import_count}")
+        lines.append(f"degraded_file_count={r.degraded_file_count}")
+        lines.append(f"resolved_by_language={_by_language_name(r.resolved_by_language)}")
+        lines.append(f"unresolved_by_language={_by_language_name(r.unresolved_by_language)}")
+
+    elif phase == "persistence":
+        assert ctx.write_result is not None
+        lines.append(f"node_count={ctx.write_result.node_count}")
+        lines.append(f"edge_count={ctx.write_result.edge_count}")
+        lines.append(f"dropped_edges={ctx.write_result.dropped_edges}")
+
+    lines.append("")
+    return "\n".join(lines)
+
+
+def _count_definitions(resolved_graph: ResolvedGraph) -> tuple[int, int]:
+    """Return (class_count, function_count) across all files in the graph."""
+    class_count = 0
+    function_count = 0
+    for pf in resolved_graph.files:
+        for d in pf.definitions:
+            if d.kind is SymbolKind.CLASS:
+                class_count += 1
+            elif d.kind in (SymbolKind.FUNCTION, SymbolKind.METHOD):
+                function_count += 1
+    return class_count, function_count
+
+
+def _db_size(db_path: Path) -> int:
+    """Total bytes on disk for the database — a single file or a directory."""
+    if db_path.is_file():
+        return db_path.stat().st_size
+    if db_path.is_dir():
+        return sum(f.stat().st_size for f in db_path.rglob("*") if f.is_file())
+    return 0
+
+
+def _resolved_pct(graph: ResolvedGraph) -> float:
+    """Overall resolved-call ratio across all languages (1.0 if no calls at all)."""
+    total_raw = sum(len(d.raw_calls) for pf in graph.files for d in pf.definitions)
+    if total_raw == 0:
+        return 1.0
+    return len(graph.call_edges) / total_raw
+
+
+def _by_language_name(ratios: dict[Language, float]) -> dict[str, float]:
+    return {language.value: ratio for language, ratio in ratios.items()}
+
+
+def _language_counts(ctx: IngestContext) -> dict[Language, int]:
+    assert ctx.manifest is not None
+    counts: dict[Language, int] = {}
+    for f in ctx.manifest.files:
+        counts[f.language] = counts.get(f.language, 0) + 1
+    return counts
+
+
+def _relative_db_path(db_path: Path, repo_path: Path) -> Path:
+    """Express db_path relative to repo_path for display, falling back to the absolute path."""
+    try:
+        return db_path.relative_to(repo_path)
+    except ValueError:
+        return db_path
+
+
+def _stage_result(
+    phase: str, ctx: IngestContext, *, repo_path: Path, db_path: Path
+) -> tuple[str, str, bool]:
+    """Build (primary, secondary, warn) display text for a just-finished phase."""
+    if phase == "discovery":
+        assert ctx.manifest is not None
+        m = ctx.manifest
+        num_languages = len(_language_counts(ctx))
+        language_word = "language" if num_languages == 1 else "languages"
+        primary = f"{len(m.files):,} files"
+        secondary = f"{num_languages} {language_word} · {m.dirs_scanned:,} dirs · {m.ignored_count:,} ignored"
+        return primary, secondary, False
+
+    if phase == "parse":
+        assert ctx.parsed_files is not None
+        degraded = sum(1 for pf in ctx.parsed_files if pf.degraded)
+        primary = f"{len(ctx.parsed_files):,} parsed"
+        secondary = f"{degraded:,} degraded"
+        return primary, secondary, degraded > 0
+
+    if phase == "symbol_table":
+        assert ctx.symbol_table is not None
+        assert ctx.import_map is not None
+        primary = f"{len(ctx.symbol_table):,} symbols"
+        secondary = f"{len(ctx.import_map):,} import entries"
+        return primary, secondary, False
+
+    if phase == "resolution":
+        assert ctx.resolved_graph is not None
+        g = ctx.resolved_graph
+        total = (
+            len(g.import_edges)
+            + len(g.inherit_edges)
+            + len(g.call_edges)
+            + len(g.external_call_edges)
+        )
+        primary = f"{total:,} edges"
+        secondary = (
+            f"import {len(g.import_edges):,} · call {len(g.call_edges):,} · "
+            f"external {len(g.external_call_edges):,} · inherit {len(g.inherit_edges):,}"
+        )
+        return primary, secondary, False
+
+    if phase == "validation":
+        assert ctx.report is not None
+        assert ctx.resolved_graph is not None
+        r = ctx.report
+        primary = f"{r.orphan_node_count:,} orphan nodes"
+        secondary = (
+            f"{r.dangling_import_count:,} dangling imports · {r.degraded_file_count:,} degraded files · "
+            f"{_resolved_pct(ctx.resolved_graph):.0%} resolved"
+        )
+        return primary, secondary, r.orphan_node_count > 0
+
+    if phase == "persistence":
+        assert ctx.write_result is not None
+        display_db = _relative_db_path(db_path, repo_path)
+        primary = f"{ctx.write_result.node_count:,} nodes · {ctx.write_result.edge_count:,} edges"
+        secondary = f"{display.fmt_size(_db_size(db_path))} · {display_db}"
+        dropped = ctx.write_result.dropped_edges
+        if dropped:
+            secondary = f"{dropped:,} skipped · {secondary}"
+        return primary, secondary, dropped > 0
+
+    return "", "", False
+
+
+def _run_ingest(
+    repo_path: Path,
+    db_path: Path,
+    *,
+    workers: int | None,
+    verbose: bool,
+    debug_log: Path | None,
+) -> IngestSummary:
+    """Run the ingest pipeline and return its summary."""
+    start = time.monotonic()
+
+    display.ingest_header(repo_path)
+
+    if debug_log is not None:
+        debug_log.parent.mkdir(parents=True, exist_ok=True)
+        debug_log.write_text("", encoding="utf-8")
+
+    with IngestReporter(console=display.console) as reporter:
+
+        def _on_phase_complete(phase: str, ctx: IngestContext) -> None:
+            primary, secondary, warn = _stage_result(
+                phase, ctx, repo_path=repo_path, db_path=db_path
+            )
+            reporter.complete(phase, primary, secondary, warn=warn)
+            if debug_log is not None:
+                with debug_log.open("a", encoding="utf-8") as f:
+                    f.write(_format_debug_section(phase, ctx) + "\n")
+
+        ctx = Pipeline(max_workers=workers).run(
+            repo_path, db_path, reporter=reporter, on_phase_complete=_on_phase_complete
+        )
+        reporter.finalize()
+    display.console.print()
+
+    assert ctx.manifest is not None
+    assert ctx.resolved_graph is not None
+    assert ctx.report is not None
+    assert ctx.write_result is not None
+
+    display_db = _relative_db_path(db_path, repo_path)
+    class_count, function_count = _count_definitions(ctx.resolved_graph)
+
+    return IngestSummary(
+        file_count=len(ctx.manifest.files),
+        class_count=class_count,
+        function_count=function_count,
+        elapsed=time.monotonic() - start,
+        node_count=ctx.write_result.node_count,
+        edge_count=ctx.write_result.edge_count,
+        db_path=display_db,
+        db_size=_db_size(db_path),
+        skipped=ctx.report.degraded_file_count,
+        resolved_pct=_resolved_pct(ctx.resolved_graph),
+        orphan_count=ctx.report.orphan_node_count,
+        language_counts=_language_counts(ctx),
+        dropped_edges=ctx.write_result.dropped_edges,
+    )
+
+
+@handle_errors
+def ingest(
+    path: str = typer.Argument(..., help="Path to the repository to ingest"),
+    db: str | None = typer.Option(
+        None, "--db", help="Path to LadybugDB database (default: <repo>/.compass/graph.ladybug)"
+    ),
+    workers: int | None = typer.Option(None, "--workers", help="Number of parallel parse workers"),
+    verbose: bool = typer.Option(False, "--verbose", "-v", help="Enable debug logging"),
+    debug_log: bool = typer.Option(
+        False, "--debug-log", help="Append phase-by-phase output to .compass/ingest_debug.log"
+    ),
+) -> None:
+    """Ingest a repository for code intelligence."""
+    setup_logging(level="DEBUG" if verbose else "WARNING", show_path=verbose)
+
+    repo_path = Path(path).resolve()
+    db_path = Path(db).resolve() if db else repo_path / ".compass" / "graph.ladybug"
+    db_path.parent.mkdir(parents=True, exist_ok=True)
+    debug_log_path = repo_path / ".compass" / "ingest_debug.log" if debug_log else None
+
+    summary = _run_ingest(
+        repo_path, db_path, workers=workers, verbose=verbose, debug_log=debug_log_path
+    )
+
+    display.summary(summary)
+    display.next_steps()

compass_cli/commands/mcp.py

@@ -0,0 +1,25 @@
+"""The ``compass mcp`` command: serve the code graph to coding agents over MCP (stdio)."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import typer
+
+from compass_mcp.server import build_server
+
+REPO = typer.Option(
+    None,
+    "--repo",
+    file_okay=False,
+    help="Repository to serve; default: the one containing the working directory.",
+)
+
+
+def mcp(repo: Path | None = REPO) -> None:
+    """Run the MCP server on stdin/stdout for Claude Code, Codex and other MCP clients.
+
+    Nothing else is printed: stdout carries the protocol. Register it with
+    `compass setup --mcp`, or point a client at the command `compass mcp`.
+    """
+    build_server(repo).run("stdio")

compass_cli/commands/query.py

@@ -0,0 +1,181 @@
+"""Query commands: ``status``, ``search``, ``describe``, ``impact`` and ``overview``.
+
+Each command finds the index, opens it read-only, calls one ``compass_core.query``
+function and prints its result: in a terminal, Rich tables and panels
+(``compass_cli.result_views``); when piped, as for a script or a coding agent, the compact
+one-line-per-item text of ``compass_core.render``; and the contract JSON with
+``--format json``. Queries never write; without an index they exit with a message saying
+to run ``compass ingest``.
+
+Answers go to stdout. An ambiguous or unknown reference is an answer too (the candidates
+or suggestions), printed to stdout with its own exit code; failures go to stderr. Exit
+codes come from ``ERROR_MAPPINGS``: 0 ok, 2 invalid argument, 3 not found, 4 ambiguous,
+5 no index, 6 index busy, 7 index must be rebuilt, 8 timeout.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from pathlib import Path
+from typing import NoReturn, TypeVar
+
+import typer
+from rich.console import RenderableType
+
+from compass_cli import result_views
+from compass_cli.display import console
+from compass_cli.types import OutputFormat
+from compass_core.contract.errors import ERROR_MAPPINGS, ErrorResponse, to_error_response
+from compass_core.contract.params import (
+    DEFAULT_IMPACT_DEPTH,
+    DEFAULT_LIMIT,
+    DEFAULT_MIN_CONFIDENCE,
+    MAX_DEPTH,
+    MAX_LIMIT,
+    ImpactParams,
+    SearchParams,
+)
+from compass_core.contract.results import AmbiguousReference, Lookup, SymbolNotFound
+from compass_core.contract.serialize import Serializable, to_json
+from compass_core.errors import ErrorCode, QueryError
+from compass_core.graph.db import GraphDB
+from compass_core.index.locate import IndexLocation, locate_index, locate_repo_index
+from compass_core.query.detail import describe as describe_symbol
+from compass_core.query.impact import impact as impact_of
+from compass_core.query.overview import overview as repo_overview
+from compass_core.query.search import find_symbols
+from compass_core.query.status import index_status
+from compass_core.render import (
+    render_ambiguous,
+    render_describe,
+    render_error,
+    render_impact,
+    render_not_found,
+    render_overview,
+    render_search,
+    render_status,
+)
+from compass_core.shared_types import SymbolKind
+
+R = TypeVar("R")
+
+FORMAT = typer.Option(
+    OutputFormat.TEXT,
+    "--format",
+    "-f",
+    help="text (default; tables in a terminal, compact lines when piped) or json.",
+)
+REPO = typer.Option(
+    None,
+    "--repo",
+    help="Repository to query; default: the one containing the current directory.",
+    file_okay=False,
+)
+KIND = typer.Option(None, "--kind", "-k", help="Only this kind of symbol.")
+LIMIT = typer.Option(DEFAULT_LIMIT, "--limit", "-n", min=1, max=MAX_LIMIT, help="Most items.")
+
+
+def _fail(error: ErrorResponse, fmt: OutputFormat) -> NoReturn:
+    message = to_json(error) if fmt is OutputFormat.JSON else render_error(error)
+    typer.echo(message, err=True)
+    raise typer.Exit(code=ERROR_MAPPINGS[error.code].exit_code)
+
+
+def _run(
+    repo: Path | None, fmt: OutputFormat, operation: Callable[[GraphDB, IndexLocation], R]
+) -> R:
+    """Locate and open the index read-only, then run ``operation`` on it."""
+    try:
+        location = locate_repo_index(repo) if repo else locate_index()
+        with GraphDB(location.db_path, read_only=True) as db:
+            return operation(db, location)
+    except QueryError as exc:
+        _fail(to_error_response(exc), fmt)
+
+
+def _print(result: Serializable, text: str, fmt: OutputFormat) -> None:
+    typer.echo(to_json(result) if fmt is OutputFormat.JSON else text)
+
+
+def _show(
+    result: Serializable,
+    text: Callable[[], str],
+    view: Callable[[], RenderableType],
+    fmt: OutputFormat,
+) -> None:
+    """Print a result: Rich ``view`` in a terminal, else compact ``text`` or JSON."""
+    if fmt is OutputFormat.TEXT and console.is_terminal:
+        console.print(view())
+        console.print()
+    else:
+        _print(result, text(), fmt)
+
+
+def _found(result: Lookup[R], fmt: OutputFormat) -> R:
+    """Return a found result; print the candidates or suggestions and exit otherwise."""
+    if isinstance(result, AmbiguousReference):
+        _print(result, render_ambiguous(result), fmt)
+        raise typer.Exit(code=ERROR_MAPPINGS[ErrorCode.AMBIGUOUS].exit_code)
+    if isinstance(result, SymbolNotFound):
+        _print(result, render_not_found(result), fmt)
+        raise typer.Exit(code=ERROR_MAPPINGS[ErrorCode.NOT_FOUND].exit_code)
+    return result
+
+
+def status(fmt: OutputFormat = FORMAT, repo: Path | None = REPO) -> None:
+    """Show which index is used, when it was built and whether files changed since."""
+    result = _run(repo, fmt, lambda db, location: index_status(location, db))
+    _show(result, lambda: render_status(result), lambda: result_views.status_view(result), fmt)
+
+
+def search(
+    text: str = typer.Argument(..., help="Name, qualified name, or part of either."),
+    kind: SymbolKind | None = KIND,
+    limit: int = LIMIT,
+    fmt: OutputFormat = FORMAT,
+    repo: Path | None = REPO,
+) -> None:
+    """Find files, classes, functions and methods by name. Best matches first."""
+    params = SearchParams(query=text, kind=kind, limit=limit)
+    result = _run(repo, fmt, lambda db, location: find_symbols(db, location, params))
+    _show(result, lambda: render_search(result), lambda: result_views.search_view(result), fmt)
+
+
+def describe(
+    ref: str = typer.Argument(..., help="Symbol id, file path, qualified name or name."),
+    source: bool = typer.Option(False, "--source", help="Also print the source text."),
+    fmt: OutputFormat = FORMAT,
+    repo: Path | None = REPO,
+) -> None:
+    """Show one symbol: location, signature, docstring, callers, callees and members."""
+    detail = _found(_run(repo, fmt, lambda db, location: describe_symbol(db, location, ref)), fmt)
+    _show(
+        detail,
+        lambda: render_describe(detail, include_source=source),
+        lambda: result_views.describe_view(detail, include_source=source),
+        fmt,
+    )
+
+
+def impact(
+    ref: str = typer.Argument(..., help="Symbol id, file path, qualified name or name."),
+    depth: int = typer.Option(
+        DEFAULT_IMPACT_DEPTH, "--depth", "-d", min=1, max=MAX_DEPTH, help="Most hops."
+    ),
+    min_confidence: float = typer.Option(
+        DEFAULT_MIN_CONFIDENCE, "--min-confidence", min=0.0, max=1.0, help="Skip weaker calls."
+    ),
+    limit: int = LIMIT,
+    fmt: OutputFormat = FORMAT,
+    repo: Path | None = REPO,
+) -> None:
+    """List what may break if a symbol or file changes, nearest first."""
+    params = ImpactParams(depth=depth, min_confidence=min_confidence, limit=limit)
+    result = _found(_run(repo, fmt, lambda db, location: impact_of(db, location, ref, params)), fmt)
+    _show(result, lambda: render_impact(result), lambda: result_views.impact_view(result), fmt)
+
+
+def overview(fmt: OutputFormat = FORMAT, repo: Path | None = REPO) -> None:
+    """Summarise the repository: totals, entry points and the most connected symbols."""
+    result = _run(repo, fmt, lambda db, location: repo_overview(db, location))
+    _show(result, lambda: render_overview(result), lambda: result_views.overview_view(result), fmt)

compass_cli/commands/serve.py

@@ -0,0 +1,123 @@
+"""The `compass serve` command."""
+
+from __future__ import annotations
+
+import subprocess
+import sys
+import time
+import urllib.request
+import webbrowser
+from enum import StrEnum
+from pathlib import Path
+
+import typer
+
+from compass_cli import display
+from compass_cli.errors import handle_errors
+from compass_core.logger import setup as setup_logging
+from compass_server.settings import server_settings
+from compass_server.web_bundle import has_bundled_ui
+
+
+def _wait_for_server(url: str, timeout: int = 30) -> bool:
+    """Poll url until it responds or timeout (seconds) is reached."""
+    deadline = time.monotonic() + timeout
+    while time.monotonic() < deadline:
+        try:
+            urllib.request.urlopen(url, timeout=1)
+            return True
+        except Exception:
+            time.sleep(0.5)
+    return False
+
+
+class UiMode(StrEnum):
+    """Where ``compass serve`` gets the web UI from.
+
+    Attributes:
+        BUNDLED: The static UI built into ``compass_server``, served on the API's own port
+            (an installed package).
+        DEV: The Next.js dev server from a source checkout, with hot reload.
+        NONE: No UI; only the API.
+    """
+
+    BUNDLED = "bundled"
+    DEV = "dev"
+    NONE = "none"
+
+
+WEB_DIR = Path(__file__).parents[5] / "apps" / "web"
+"""The web app in a source checkout; absent in an installed package."""
+
+
+def ui_mode(*, no_frontend: bool, dev: bool) -> UiMode:
+    """Pick the UI to serve: the dev server when asked or unbundled, else the bundle.
+
+    Args:
+        no_frontend: Serve only the API.
+        dev: Prefer the Next.js dev server even when a bundled UI exists.
+
+    Returns:
+        The mode.
+
+    Example:
+        In an installed package, ``ui_mode(no_frontend=False, dev=False)`` is
+        ``UiMode.BUNDLED``.
+    """
+    if no_frontend:
+        return UiMode.NONE
+    if WEB_DIR.exists() and (dev or not has_bundled_ui()):
+        return UiMode.DEV
+    return UiMode.BUNDLED if has_bundled_ui() else UiMode.NONE
+
+
+@handle_errors
+def serve(
+    host: str = typer.Option(server_settings.API_HOST, help="Host for the API server"),
+    port: int = typer.Option(server_settings.API_PORT, help="Port for the API server"),
+    no_frontend: bool = typer.Option(False, "--no-frontend", help="Serve only the API"),
+    dev: bool = typer.Option(
+        False, "--dev", help="Run the web UI's dev server from a source checkout"
+    ),
+    verbose: bool = typer.Option(False, "--verbose", "-v", help="Enable debug logging"),
+) -> None:
+    """Start the API server and the web UI, then open the UI in a browser."""
+    setup_logging(level="DEBUG" if verbose else "WARNING", show_path=verbose)
+
+    mode = ui_mode(no_frontend=no_frontend, dev=dev)
+    api_url = f"http://{host}:{port}"
+    procs: list[subprocess.Popen[bytes]] = []
+
+    try:
+        display.console.print(f"[bold green]Starting API server[/bold green] on {api_url}")
+        command = [sys.executable, "-m", "uvicorn", "compass_server.main:app"]
+        command += ["--host", host, "--port", str(port)]
+        if mode is UiMode.DEV:
+            command.append("--reload")
+        procs.append(subprocess.Popen(command))
+
+        if mode is UiMode.BUNDLED:
+            display.console.print(f"[bold green]Web UI[/bold green] on {api_url}")
+            if _wait_for_server(f"{api_url}/health"):
+                webbrowser.open(api_url)
+        elif mode is UiMode.DEV:
+            frontend_url = server_settings.FRONTEND_URL
+            display.console.print(f"[bold green]Starting frontend[/bold green] on {frontend_url}")
+            procs.append(subprocess.Popen(["pnpm", "dev"], cwd=WEB_DIR))
+            # Poll until the dev server is ready, then open the browser.
+            if _wait_for_server(
+                f"http://{server_settings.FRONTEND_HOST}:{server_settings.FRONTEND_PORT}"
+            ):
+                webbrowser.open(frontend_url)
+
+        display.console.print("[dim]Press Ctrl+C to stop.[/dim]")
+
+        for proc in procs:
+            proc.wait()
+
+    except KeyboardInterrupt:
+        display.console.print("\n[yellow]Shutting down...[/yellow]")
+        for proc in procs:
+            proc.terminate()
+        for proc in procs:
+            proc.wait()