@cephalization/phoenix-insight 0.4.0 → 1.0.0

package/dist/server/ui.js

@@ -0,0 +1,232 @@
+/**
+ * HTTP server for Phoenix Insight UI.
+ * Serves the static build of @cephalization/phoenix-insight-ui package.
+ *
+ * Binds to localhost only for security (no external network access).
+ * Handles SPA routing by serving index.html for non-asset routes.
+ */
+import { createServer } from "node:http";
+import { createReadStream, existsSync, statSync } from "node:fs";
+import { extname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+// ============================================================================
+// MIME Type Mapping
+// ============================================================================
+const MIME_TYPES = {
+    ".html": "text/html; charset=utf-8",
+    ".css": "text/css; charset=utf-8",
+    ".js": "text/javascript; charset=utf-8",
+    ".mjs": "text/javascript; charset=utf-8",
+    ".json": "application/json; charset=utf-8",
+    ".svg": "image/svg+xml",
+    ".png": "image/png",
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".gif": "image/gif",
+    ".ico": "image/x-icon",
+    ".webp": "image/webp",
+    ".woff": "font/woff",
+    ".woff2": "font/woff2",
+    ".ttf": "font/ttf",
+    ".eot": "application/vnd.ms-fontobject",
+    ".map": "application/json",
+};
+/**
+ * Get MIME type for a file extension
+ */
+function getMimeType(filePath) {
+    const ext = extname(filePath).toLowerCase();
+    return MIME_TYPES[ext] ?? "application/octet-stream";
+}
+// ============================================================================
+// Path Resolution
+// ============================================================================
+/**
+ * Resolve the UI package dist directory path.
+ *
+ * Resolution order:
+ * 1. Bundled dist/ui (copied during build, used for npm published package)
+ * 2. import.meta.resolve (finds package in node_modules, used for development)
+ * 3. Relative path fallback (for development before packages are linked)
+ */
+export function resolveUIDistPath() {
+    const __dirname = fileURLToPath(new URL(".", import.meta.url));
+    // First check for bundled UI dist (copied during CLI build)
+    // This is the path when installed from npm
+    const bundledPath = resolve(__dirname, "../ui");
+    if (existsSync(bundledPath) && existsSync(join(bundledPath, "index.html"))) {
+        return bundledPath;
+    }
+    try {
+        // Resolve the UI package's package.json using import.meta.resolve
+        // import.meta.resolve returns a file URL (file:///...)
+        const packageJsonUrl = import.meta.resolve("@cephalization/phoenix-insight-ui/package.json");
+        const packageJsonPath = fileURLToPath(packageJsonUrl);
+        const packageDir = resolve(packageJsonPath, "..");
+        return join(packageDir, "dist");
+    }
+    catch {
+        // Fallback: try to resolve relative to this file (for development)
+        return resolve(__dirname, "../../../ui/dist");
+    }
+}
+// ============================================================================
+// Static File Server
+// ============================================================================
+/**
+ * Determine if a path should be served as a static asset.
+ * Asset paths have file extensions (e.g., .js, .css, .png).
+ * Non-asset paths (routes) should get the SPA index.html.
+ */
+function isAssetPath(urlPath) {
+    // Check for file extension in the last segment
+    const lastSegment = urlPath.split("/").pop() ?? "";
+    return lastSegment.includes(".");
+}
+/**
+ * Sanitize URL path to prevent directory traversal attacks.
+ * Returns null if the path is invalid.
+ */
+function sanitizePath(urlPath, basePath) {
+    // Decode URI and normalize slashes
+    let decoded;
+    try {
+        decoded = decodeURIComponent(urlPath);
+    }
+    catch {
+        return null;
+    }
+    // Remove query string and hash
+    const withoutQuery = decoded.split("?")[0] ?? decoded;
+    decoded = withoutQuery.split("#")[0] ?? withoutQuery;
+    // Resolve the full path
+    const fullPath = resolve(basePath, "." + decoded);
+    // Ensure the resolved path is within the base directory
+    if (!fullPath.startsWith(basePath)) {
+        return null;
+    }
+    return fullPath;
+}
+/**
+ * Create an HTTP server that serves the Phoenix Insight UI.
+ *
+ * Features:
+ * - Serves static files from the UI package dist directory
+ * - SPA fallback: non-asset routes serve index.html
+ * - Binds to localhost only (127.0.0.1) for security
+ * - Proper MIME types for all common web assets
+ *
+ * @param options - Server configuration options
+ * @returns Promise resolving to UIServer instance
+ */
+export function createUIServer(options = {}) {
+    const port = options.port ?? 6007;
+    const host = options.host ?? "127.0.0.1";
+    const distPath = options.distPath ?? resolveUIDistPath();
+    // Verify dist directory exists
+    if (!existsSync(distPath)) {
+        return Promise.reject(new Error(`UI dist directory not found at: ${distPath}\n` +
+            "Make sure to build the UI package first: pnpm --filter @cephalization/phoenix-insight-ui build"));
+    }
+    // Verify index.html exists
+    const indexPath = join(distPath, "index.html");
+    if (!existsSync(indexPath)) {
+        return Promise.reject(new Error(`UI index.html not found at: ${indexPath}\n` +
+            "Make sure to build the UI package first: pnpm --filter @cephalization/phoenix-insight-ui build"));
+    }
+    return new Promise((resolve, reject) => {
+        const httpServer = createServer((req, res) => {
+            const urlPath = req.url ?? "/";
+            // Sanitize the path to prevent directory traversal
+            let filePath = sanitizePath(urlPath, distPath);
+            if (!filePath) {
+                res.writeHead(400, { "Content-Type": "text/plain" });
+                res.end("Bad Request");
+                return;
+            }
+            // SPA fallback: if not an asset path, serve index.html
+            if (!isAssetPath(urlPath)) {
+                filePath = indexPath;
+            }
+            // Check if file exists
+            if (!existsSync(filePath)) {
+                // For missing assets, return 404
+                // For missing routes, serve index.html (SPA)
+                if (isAssetPath(urlPath)) {
+                    res.writeHead(404, { "Content-Type": "text/plain" });
+                    res.end("Not Found");
+                    return;
+                }
+                filePath = indexPath;
+            }
+            // Get file stats
+            let stats;
+            try {
+                stats = statSync(filePath);
+            }
+            catch {
+                res.writeHead(500, { "Content-Type": "text/plain" });
+                res.end("Internal Server Error");
+                return;
+            }
+            // If it's a directory, serve index.html
+            if (stats.isDirectory()) {
+                filePath = indexPath;
+                try {
+                    stats = statSync(filePath);
+                }
+                catch {
+                    res.writeHead(500, { "Content-Type": "text/plain" });
+                    res.end("Internal Server Error");
+                    return;
+                }
+            }
+            // Set response headers
+            const mimeType = getMimeType(filePath);
+            res.writeHead(200, {
+                "Content-Type": mimeType,
+                "Content-Length": stats.size,
+                "Cache-Control": filePath === indexPath
+                    ? "no-cache" // Don't cache index.html for SPA
+                    : "public, max-age=31536000", // Cache assets for 1 year
+            });
+            // Stream the file
+            const stream = createReadStream(filePath);
+            stream.pipe(res);
+            stream.on("error", () => {
+                res.writeHead(500, { "Content-Type": "text/plain" });
+                res.end("Internal Server Error");
+            });
+        });
+        // Handle server errors
+        httpServer.on("error", (err) => {
+            reject(err);
+        });
+        // Start listening
+        httpServer.listen(port, host, () => {
+            // Get the actual assigned port (important when port 0 is specified)
+            const address = httpServer.address();
+            const actualPort = typeof address === "object" && address !== null
+                ? address.port
+                : port;
+            resolve({
+                httpServer,
+                port: actualPort,
+                host,
+                distPath,
+                close() {
+                    return new Promise((resolveClose, rejectClose) => {
+                        httpServer.close((err) => {
+                            if (err) {
+                                rejectClose(err);
+                            }
+                            else {
+                                resolveClose();
+                            }
+                        });
+                    });
+                },
+            });
+        });
+    });
+}

package/dist/server/websocket.js

@@ -0,0 +1,212 @@
+/**
+ * WebSocket server for Phoenix Insight CLI.
+ * Provides bidirectional communication between the CLI agent and the web UI.
+ *
+ * Binds to localhost only for security (no external network access).
+ * Handles HTTP upgrade requests, manages client connections, and broadcasts messages.
+ */
+import { WebSocketServer, WebSocket } from "ws";
+// ============================================================================
+// Phoenix WebSocket Server
+// ============================================================================
+/**
+ * Phoenix WebSocket server wrapper providing typed message handling
+ * and connection management.
+ */
+export class PhoenixWebSocketServer {
+    wss = null;
+    clients = new Set();
+    options;
+    constructor(options = {}) {
+        this.options = {
+            path: "/ws",
+            onMessage: () => { },
+            onConnection: () => { },
+            onDisconnection: () => { },
+            onError: () => { },
+            ...options,
+        };
+    }
+    /**
+     * Attach the WebSocket server to an existing HTTP server.
+     * Uses the upgrade event to handle WebSocket handshakes.
+     */
+    attach(httpServer) {
+        if (this.wss) {
+            throw new Error("WebSocket server is already attached");
+        }
+        // Create WebSocket server with noServer mode to handle upgrade ourselves
+        this.wss = new WebSocketServer({ noServer: true });
+        // Handle HTTP upgrade requests
+        httpServer.on("upgrade", (request, socket, head) => {
+            this.handleUpgrade(request, socket, head);
+        });
+        // Set up WebSocket server event handlers
+        this.setupEventHandlers();
+    }
+    /**
+     * Handle HTTP upgrade request for WebSocket connection.
+     * Only accepts connections on the configured path and from localhost.
+     */
+    handleUpgrade(request, socket, head) {
+        if (!this.wss) {
+            socket.destroy();
+            return;
+        }
+        // Parse the request URL
+        const url = new URL(request.url ?? "/", `http://${request.headers.host}`);
+        // Only accept connections on the configured path
+        if (url.pathname !== this.options.path) {
+            socket.destroy();
+            return;
+        }
+        // Complete the WebSocket handshake
+        this.wss.handleUpgrade(request, socket, head, (ws) => {
+            this.wss?.emit("connection", ws, request);
+        });
+    }
+    /**
+     * Set up event handlers for the WebSocket server.
+     */
+    setupEventHandlers() {
+        if (!this.wss)
+            return;
+        this.wss.on("connection", (ws) => {
+            this.clients.add(ws);
+            this.options.onConnection(ws);
+            ws.on("message", (data) => {
+                this.handleMessage(data, ws);
+            });
+            ws.on("close", (code, reason) => {
+                this.clients.delete(ws);
+                this.options.onDisconnection(ws, code, reason.toString());
+            });
+            ws.on("error", (error) => {
+                this.options.onError(error, ws);
+            });
+        });
+        this.wss.on("error", (error) => {
+            this.options.onError(error);
+        });
+    }
+    /**
+     * Handle incoming message from a client.
+     * Parses JSON and validates message structure before calling handler.
+     */
+    handleMessage(data, client) {
+        try {
+            const rawMessage = data.toString();
+            const parsed = JSON.parse(rawMessage);
+            // Basic validation of message structure
+            if (!parsed || typeof parsed !== "object") {
+                throw new Error("Invalid message structure: expected object");
+            }
+            const obj = parsed;
+            if (!("type" in obj) || typeof obj.type !== "string") {
+                throw new Error("Invalid message structure: missing type field");
+            }
+            const messageType = obj.type;
+            if (messageType !== "query" && messageType !== "cancel") {
+                throw new Error(`Unknown message type: ${messageType}`);
+            }
+            // Now we know this is a valid ClientMessage
+            const message = parsed;
+            this.options.onMessage(message, client);
+        }
+        catch (error) {
+            // Send error message back to the client
+            const errorMessage = {
+                type: "error",
+                payload: {
+                    message: error instanceof Error
+                        ? error.message
+                        : "Failed to parse message",
+                },
+            };
+            this.sendToClient(client, errorMessage);
+        }
+    }
+    /**
+     * Send a message to a specific client.
+     */
+    sendToClient(client, message) {
+        if (client.readyState === WebSocket.OPEN) {
+            client.send(JSON.stringify(message));
+        }
+    }
+    /**
+     * Broadcast a message to all connected clients.
+     */
+    broadcast(message) {
+        const data = JSON.stringify(message);
+        for (const client of this.clients) {
+            if (client.readyState === WebSocket.OPEN) {
+                client.send(data);
+            }
+        }
+    }
+    /**
+     * Broadcast a message to all clients with a specific session ID.
+     * This requires tracking session-to-client mapping externally.
+     * For now, it broadcasts to all clients (to be refined in cli-agent-session).
+     */
+    broadcastToSession(sessionId, message) {
+        // For now, broadcast to all clients.
+        // Session-to-client mapping will be implemented in cli-agent-session task.
+        this.broadcast(message);
+    }
+    /**
+     * Get the number of connected clients.
+     */
+    get clientCount() {
+        return this.clients.size;
+    }
+    /**
+     * Get all connected clients.
+     */
+    getClients() {
+        return new Set(this.clients);
+    }
+    /**
+     * Close the WebSocket server and disconnect all clients.
+     */
+    close() {
+        return new Promise((resolve, reject) => {
+            if (!this.wss) {
+                resolve();
+                return;
+            }
+            // Close all client connections
+            for (const client of this.clients) {
+                client.close(1000, "Server shutting down");
+            }
+            this.clients.clear();
+            // Close the WebSocket server
+            this.wss.close((err) => {
+                this.wss = null;
+                if (err) {
+                    reject(err);
+                }
+                else {
+                    resolve();
+                }
+            });
+        });
+    }
+}
+// ============================================================================
+// Factory Function
+// ============================================================================
+/**
+ * Create and attach a WebSocket server to an HTTP server.
+ * The WebSocket server binds to localhost only (through the HTTP server).
+ *
+ * @param httpServer - HTTP server to attach WebSocket handling to
+ * @param options - WebSocket server options
+ * @returns PhoenixWebSocketServer instance
+ */
+export function createWebSocketServer(httpServer, options) {
+    const server = new PhoenixWebSocketServer(options);
+    server.attach(httpServer);
+    return server;
+}

package/dist/tsconfig.esm.tsbuildinfo

@@ -1 +1 @@
-{"root":["../src/cli.ts","../src/index.ts","../src/progress.ts","../src/agent/index.ts","../src/commands/index.ts","../src/commands/px-fetch-more-spans.ts","../src/commands/px-fetch-more-trace.ts","../src/config/index.ts","../src/config/loader.ts","../src/config/schema.ts","../src/modes/index.ts","../src/modes/local.ts","../src/modes/sandbox.ts","../src/modes/types.ts","../src/observability/index.ts","../src/prompts/index.ts","../src/prompts/system.ts","../src/snapshot/client.ts","../src/snapshot/context.ts","../src/snapshot/datasets.ts","../src/snapshot/experiments.ts","../src/snapshot/index.ts","../src/snapshot/projects.ts","../src/snapshot/prompts.ts","../src/snapshot/spans.ts","../src/snapshot/utils.ts"],"version":"5.9.3"}
+{"root":["../src/cli.ts","../src/index.ts","../src/progress.ts","../src/agent/index.ts","../src/commands/index.ts","../src/commands/px-fetch-more-spans.ts","../src/commands/px-fetch-more-trace.ts","../src/commands/report-tool.ts","../src/config/index.ts","../src/config/loader.ts","../src/config/schema.ts","../src/modes/index.ts","../src/modes/local.ts","../src/modes/sandbox.ts","../src/modes/types.ts","../src/observability/index.ts","../src/prompts/index.ts","../src/prompts/system.ts","../src/server/session.ts","../src/server/ui.ts","../src/server/websocket.ts","../src/snapshot/client.ts","../src/snapshot/context.ts","../src/snapshot/datasets.ts","../src/snapshot/experiments.ts","../src/snapshot/index.ts","../src/snapshot/projects.ts","../src/snapshot/prompts.ts","../src/snapshot/spans.ts","../src/snapshot/utils.ts"],"version":"5.9.3"}