From f1b9af65b6091254ab979ed2450691f6610f7654 Mon Sep 17 00:00:00 2001
From: Robert DeRienzo <rderienzo@voloridge.com>
Date: Mon, 2 Mar 2026 19:27:11 +0000
Subject: [PATCH] feat: wire up web dashboard via `libscope serve --dashboard`
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Add --dashboard flag to the serve command that starts the web UI server
from src/web/server.ts (default port 3377). The dashboard serves:
- GET / → HTML dashboard with document stats, topics, recent activity
- GET /graph → Knowledge graph visualization

Port and host are configurable via --port and --host flags.
Updated CLI reference docs.

Closes #259

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 docs/reference/cli.md | 15 +++++++++------
 src/cli/index.ts      | 28 ++++++++++++++++++----------
 2 files changed, 27 insertions(+), 16 deletions(-)

diff --git a/docs/reference/cli.md b/docs/reference/cli.md
index 3278f1f..f8c8b2a 100644
--- a/docs/reference/cli.md
+++ b/docs/reference/cli.md
@@ -11,7 +11,7 @@
 | `libscope search <query>` | Semantic search |
 | `libscope ask <question>` | RAG question-answering |
 | `libscope repl` | Interactive search REPL |
-| `libscope serve` | Start MCP server (or `--api` for REST API) |
+| `libscope serve` | Start MCP server, REST API (`--api`), or web dashboard (`--dashboard`) |
 
 ### `libscope add`
 
@@ -84,18 +84,21 @@ libscope ask "How do I configure OAuth2?" --library my-lib --top-k 8
 
 ### `libscope serve`
 
-Start the MCP server or REST API.
+Start the MCP server, REST API, or web dashboard.
 
 ```bash
-libscope serve          # MCP server (stdio)
-libscope serve --api    # REST API
-libscope serve --api --port 3378
+libscope serve                # MCP server (stdio)
+libscope serve --api          # REST API (port 3378)
+libscope serve --dashboard    # Web dashboard UI (port 3377)
+libscope serve --dashboard --port 8080
 ```
 
 | Option | Description |
 |--------|-------------|
 | `--api` | Start REST API instead of MCP server |
-| `--port <n>` | REST API port (default: 3378) |
+| `--dashboard` | Start the web dashboard UI |
+| `--port <n>` | Server port (default: 3378 for API, 3377 for dashboard) |
+| `--host <h>` | Server host (default: localhost) |
 
 ## Document Management
 
diff --git a/src/cli/index.ts b/src/cli/index.ts
index 38163cb..7746b0b 100644
--- a/src/cli/index.ts
+++ b/src/cli/index.ts
@@ -710,19 +710,27 @@ program
 // serve
 program
   .command("serve")
-  .description("Start the MCP server (or REST API with --api)")
+  .description("Start the MCP server, REST API (--api), or web dashboard (--dashboard)")
   .option("--api", "Start the REST API server instead of MCP")
-  .option("--port <port>", "API server port", "3378")
-  .option("--host <host>", "API server host", "localhost")
-  .action(async (opts: { api?: boolean; port: string; host: string }) => {
-    if (opts.api) {
+  .option("--dashboard", "Start the web dashboard UI")
+  .option("--port <port>", "Server port (default: 3378 for API, 3377 for dashboard)")
+  .option("--host <host>", "Server host", "localhost")
+  .action(async (opts: { api?: boolean; dashboard?: boolean; port?: string; host: string }) => {
+    if (opts.dashboard) {
+      const { db, provider } = initializeAppWithEmbedding();
+      const { startWebServer } = await import("../web/server.js");
+      const defaultPort = 3377;
+      const port = opts.port ? parseIntOption(opts.port, "--port") : defaultPort;
+      await startWebServer(db, provider, { port, host: opts.host });
+      console.log(`LibScope dashboard running at http://${opts.host}:${port}`);
+      console.log("Press Ctrl+C to stop");
+    } else if (opts.api) {
       const { db, provider } = initializeAppWithEmbedding();
       const { startApiServer } = await import("../api/server.js");
-      const { port } = await startApiServer(db, provider, {
-        port: parseIntOption(opts.port, "--port"),
-        host: opts.host,
-      });
-      console.log(`LibScope API server listening on http://${opts.host}:${port}`);
+      const defaultPort = 3378;
+      const port = opts.port ? parseIntOption(opts.port, "--port") : defaultPort;
+      const result = await startApiServer(db, provider, { port, host: opts.host });
+      console.log(`LibScope API server listening on http://${opts.host}:${result.port}`);
       console.log("Press Ctrl+C to stop");
     } else {
       await import("../mcp/server.js");