pi-context-map 0.3.1 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## [0.4.0] - 2026-06-14
+### Live Localhost Server
+- **Live SSE Server**: New `LiveReportServer` binds to 127.0.0.1 on a free port and serves the report at `/`.
+- **Auto-Updates**: Server-Sent Events endpoint at `/events` pushes the latest HTML whenever the analysis re-runs (e.g., after each assistant message).
+- **Token Auth**: Each server instance generates a unique session token; the HTML client picks it up via a `<meta>` tag and includes it in the SSE URL to prevent unauthorized access.
+- **Origin Validation**: Only connections from `http://127.0.0.1:<port>` or `http://localhost:<port>` are allowed.
+- **Graceful Shutdown**: `/context-map stop` or `session_shutdown` event stops the server cleanly.
+- **Auto-Refresh**: The `message_end` event triggers an automatic re-analysis when the live server is running, so the browser view stays in sync.
+- **Health & Stop Endpoints**: `/health` for liveness, `POST /stop` for remote termination.
+
 ## [0.3.1] - 2026-06-14
 ### Design & Interactivity Upgrade
 - **Linear Design System**: Refactored CSS to use the Linear design tokens (canvas #010102, accent #5e6ad2) for a professional, near-black aesthetic.

package/README.md

@@ -48,6 +48,27 @@ The extension categorizes files to help you manage context bloat:
 3. **Categorization**: It calculates the temporal distance between the current turn and the last file access.
 4. **Visualization**: It generates a standalone HTML dashboard featuring a stacked composition bar, a file-weight grid with search/filter, and an interactive insights section.
 
+## Live Localhost Server
+
+When the extension loads, it automatically starts a local HTTP server on `127.0.0.1` (a random free port). The server:
+
+- Serves the current report at `http://127.0.0.1:<port>/`.
+- Pushes live updates via Server-Sent Events at `/events?token=<sessionToken>`.
+- Authenticates the SSE connection with a per-session token (injected into the HTML as a `<meta>` tag).
+- Auto-refreshes after each assistant message, so the browser view stays in sync.
+
+**Commands:**
+
+- `/context-map` — Generate a fresh report and broadcast it to the browser.
+- `/context-map stop` — Stop the live server.
+
+**Endpoints:**
+
+- `GET /` or `/report.html` — The current report HTML.
+- `GET /events?token=...` — Server-Sent Events stream of updates.
+- `GET /health` — Returns `{ "status": "ok", "port": <number> }`.
+- `POST /stop` — Gracefully stops the server.
+
 ## Design
 
 The report uses the **Linear design system** (canvas `#010102`, accent `#5e6ad2`) with **shadcn/ui card patterns**. See `docs/design.md` for the full specification. The output is a single self-contained HTML file with no external dependencies.

package/extensions/generator.ts

@@ -615,6 +615,37 @@ export class ReportGenerator {
 
     <script>
         (function() {
+            // ===== Live update via Server-Sent Events =====
+            // Token is injected into the script via a meta tag (set by the server).
+            // Connect to /events?token=...; when the server pushes a new html payload, replace the document.
+            try {
+                var tokenMeta = document.querySelector('meta[name="context-map-token"]');
+                var token = tokenMeta ? tokenMeta.getAttribute('content') : '';
+                var evtSource = new EventSource('/events?token=' + encodeURIComponent(token));
+                evtSource.onmessage = function(e) {
+                    try {
+                        var payload = JSON.parse(e.data);
+                        if (payload.html) {
+                            // Replace the document body with the new HTML
+                            var parser = new DOMParser();
+                            var newDoc = parser.parseFromString(payload.html, 'text/html');
+                            document.documentElement.replaceChild(
+                                document.importNode(newDoc.documentElement, true),
+                                document.documentElement
+                            );
+                        }
+                    } catch (err) {
+                        console.warn('Failed to apply live update:', err);
+                    }
+                };
+                evtSource.onerror = function() {
+                    // Silently close on error; user can refresh the page to reconnect
+                    evtSource.close();
+                };
+            } catch (err) {
+                // EventSource not available; fall back to manual refresh
+            }
+
             // ===== Insight collapse/expand =====
             document.querySelectorAll('.insight-header[data-toggle]').forEach(function(btn) {
                 btn.addEventListener('click', function() {
@@ -630,7 +661,7 @@ export class ReportGenerator {
             var grid = document.getElementById('fileGrid');
             var count = document.getElementById('fileCount');
             var empty = document.getElementById('emptyState');
-            var cards = Array.prototype.slice.call(grid.querySelectorAll('.file-card'));
+            var cards = grid ? Array.prototype.slice.call(grid.querySelectorAll('.file-card')) : [];
             var total = cards.length;
 
             function applyFilters() {

package/extensions/index.ts

@@ -1,15 +1,22 @@
 /**
  * pi-context-map
  * Professional Context Profiler for Pi.
+ * v0.4.0 - Adds live localhost server with auto-updates.
  */
 
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { ContextAnalyzer } from "./analyzer";
 import { ReportGenerator } from "./generator";
 import { InsightEngine } from "./insights";
+import { LiveReportServer } from "./live-server";
+import * as path from "node:path";
+import * as os from "node:os";
+
+const REPORT_PATH = path.join(os.homedir(), ".pi", "context-map", "report.html");
 
 export default async function piContextMap(pi: ExtensionAPI) {
 	const analyzer = new ContextAnalyzer();
+	const liveServer = new LiveReportServer();
 
 	async function runAnalysis() {
 		const messages = (pi as any).session?.messages || [];
@@ -17,30 +24,53 @@ export default async function piContextMap(pi: ExtensionAPI) {
 		const composition = analyzer.analyzeByType(messages, currentTurn);
 		const insights = InsightEngine.generate(composition);
 		const html = ReportGenerator.generateHTML(composition, insights);
-		const reportPath = ReportGenerator.writeReport(html);
-		return { composition, insights, reportPath };
+
+		// Write to disk (for offline access / persistence)
+		try {
+			const fs = await import("node:fs");
+			const dir = path.dirname(REPORT_PATH);
+			if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+			fs.writeFileSync(REPORT_PATH, html, "utf8");
+		} catch (err: any) {
+			console.error(`[pi-context-map] Failed to write report to disk: ${err.message}`);
+		}
+
+		// Push to live server (if running) so the browser updates instantly
+		if (liveServer.isRunning) {
+			liveServer.update(html, REPORT_PATH);
+		}
+
+		return { composition, insights, reportPath: REPORT_PATH };
 	}
 
+	// Start the live server on load
+	const serverUrl = await liveServer.start();
+
 	pi.registerCommand("context-map", {
-		description: "Generate a visual context map with actionable insights.",
-		handler: async (_args: any, ctx: any) => {
+		description: "Generate a visual context map with actionable insights. Use 'stop' to terminate the live server.",
+		handler: async (args: any, ctx: any) => {
+			// Handle subcommand: /context-map stop
+			if (typeof args === "string" && args.trim().toLowerCase() === "stop") {
+				liveServer.stop();
+				ctx.ui.notify("Live server stopped.", "info");
+				return;
+			}
+
 			ctx.ui.notify("Analyzing session context...", "info");
 			try {
-				const { reportPath, insights } = await runAnalysis();
-				const criticalCount = insights.filter(
-					(i) => i.severity === "critical",
-				).length;
-				const summary =
-					criticalCount > 0
-						? `Context map generated. ${criticalCount} critical insight(s) found.`
-						: `Context map generated successfully.`;
-				ctx.ui.notify(
-					`${summary} Path: ${reportPath}`,
-					criticalCount > 0 ? "warning" : "success",
-				);
-			} catch (error) {
-				const message = error instanceof Error ? error.message : String(error);
-				ctx.ui.notify(`Failed to generate context map: ${message}`, "error");
+				const { insights, reportPath } = await runAnalysis();
+				const criticalCount = insights.filter((i: any) => i.severity === "critical").length;
+				const summary = criticalCount > 0
+					? `Context map generated. ${criticalCount} critical insight(s) found.`
+					: `Context map generated successfully.`;
+
+				let details = `File: ${reportPath}`;
+				if (serverUrl) {
+					details += ` Live: ${serverUrl}`;
+				}
+				ctx.ui.notify(`${summary} ${details}`, criticalCount > 0 ? "warning" : "success");
+			} catch (error: any) {
+				ctx.ui.notify(`Failed to generate context map: ${error.message}`, "error");
 			}
 		},
 	});
@@ -48,7 +78,7 @@ export default async function piContextMap(pi: ExtensionAPI) {
 	pi.registerTool({
 		name: "context-map",
 		description:
-			"Analyze the current session context composition and return actionable insights.",
+			"Analyze the current session context composition and return actionable insights. The live localhost report will auto-update.",
 		parameters: {
 			type: "object",
 			properties: {},
@@ -72,12 +102,14 @@ export default async function piContextMap(pi: ExtensionAPI) {
 						summaries: composition.summaries.tokens,
 						total: composition.total.tokens,
 					},
-					insights: insights.map((i) => ({
+					insights: insights.map((i: any) => ({
 						severity: i.severity,
 						title: i.title,
 						message: i.message,
 						command: i.command,
 					})),
+					liveUrl: serverUrl,
+					reportPath: REPORT_PATH,
 				};
 			} catch (error: any) {
 				return { error: error.message };
@@ -86,7 +118,7 @@ export default async function piContextMap(pi: ExtensionAPI) {
 	});
 
 	pi.on("session_before_compact", (event: any, ctx: any) => {
-		const tokens = (event as any).preparation?.tokensBefore;
+		const tokens = event?.preparation?.tokensBefore;
 		if (tokens && tokens > 100_000) {
 			ctx.ui.notify(
 				`High context load detected (${(tokens / 1000).toFixed(1)}k tokens). Try /context-map to see what's consuming space.`,
@@ -94,4 +126,26 @@ export default async function piContextMap(pi: ExtensionAPI) {
 			);
 		}
 	});
+
+	// Auto-refresh: re-run analysis after each assistant message so the live view stays current
+	pi.on("message_end", async (event: any) => {
+		if (event?.message?.role === "assistant" && liveServer.isRunning) {
+			try {
+				await runAnalysis();
+			} catch {
+				// Silently ignore auto-refresh failures
+			}
+		}
+	});
+
+	// Graceful shutdown: stop the live server when the session ends
+	pi.on("session_shutdown", () => {
+		liveServer.stop();
+	});
+
+	// Log the live URL once on startup
+	if (serverUrl) {
+		console.log(`[pi-context-map] Live server running at ${serverUrl}`);
+		console.log(`[pi-context-map] Run /context-map to generate a report, or /context-map stop to terminate.`);
+	}
 }

package/extensions/live-server.ts

@@ -0,0 +1,283 @@
+/**
+ * LiveReportServer
+ * Serves the context map HTML report on a local HTTP server with live updates via SSE.
+ *
+ * Features:
+ *  - Auto-assigns a free port (pass 0 to OS).
+ *  - Binds to 127.0.0.1 only (no external access).
+ *  - Serves the current report HTML at `/`.
+ *  - Streams updates via Server-Sent Events at `/events`.
+ *  - Graceful shutdown via `stop()`.
+ *  - Null-safe error handling throughout.
+ */
+import * as http from "node:http";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import * as os from "node:os";
+import * as crypto from "node:crypto";
+import type { AddressInfo } from "node:net";
+
+const DEFAULT_REPORT_PATH = path.join(os.homedir(), ".pi", "context-map", "report.html");
+
+/**
+ * Allowed origins for SSE connections. Only localhost variants are allowed.
+ */
+function isAllowedOrigin(origin: string | undefined, port: number): boolean {
+	if (!origin) return true; // No Origin header (e.g., direct curl) is allowed
+	const allowed = [
+		`http://127.0.0.1:${port}`,
+		`http://localhost:${port}`,
+		"http://127.0.0.1",
+		"http://localhost",
+	];
+	return allowed.some((o) => origin.startsWith(o));
+}
+
+export class LiveReportServer {
+	private server: http.Server | null = null;
+	private clients: Set<http.ServerResponse> = new Set();
+	private currentHtml: string = "";
+	private port: number = 0;
+	private host: string = "127.0.0.1";
+	/** Session token to prevent unauthorized access. */
+	public readonly token: string = crypto.randomBytes(16).toString("hex");
+
+	/**
+	 * Start the server. Returns a Promise that resolves to the URL, or null on failure.
+	 */
+	public start(): Promise<string | null> {
+		if (this.server) {
+			return Promise.resolve(this.url);
+		}
+
+		return new Promise((resolve) => {
+			try {
+				this.server = http.createServer((req, res) => this.handleRequest(req, res));
+				this.server.on("error", (err) => {
+					console.error(`[pi-context-map] Server error: ${err.message}`);
+					this.stop();
+				});
+
+				this.server.listen(0, this.host, () => {
+					const addr = this.server?.address() as AddressInfo | null;
+					if (addr) {
+						this.port = addr.port;
+						console.log(`[pi-context-map] Live server: ${this.url}`);
+						resolve(this.url);
+					} else {
+						resolve(null);
+					}
+				});
+			} catch (err: any) {
+				console.error(`[pi-context-map] Failed to start server: ${err.message}`);
+				resolve(null);
+			}
+		});
+	}
+
+	/**
+	 * Stop the server and close all client connections.
+	 */
+	public stop(): void {
+		if (!this.server) return;
+
+		// Close all SSE clients
+		for (const client of this.clients) {
+			try {
+				client.end();
+			} catch (err) {
+				// Ignore errors on close
+			}
+		}
+		this.clients.clear();
+
+		// Close the server
+		this.server.close((err) => {
+			if (err) {
+				console.error(`[pi-context-map] Error closing server: ${err.message}`);
+			}
+		});
+		this.server = null;
+		this.port = 0;
+	}
+
+	/**
+	 * Update the report content and broadcast to all connected clients.
+	 * @param html The new HTML content.
+	 * @param reportPath Optional path to the report file to also write to disk.
+	 */
+	public update(html: string, reportPath?: string): void {
+		this.currentHtml = html;
+
+		// Optionally write to disk
+		if (reportPath) {
+			try {
+				const dir = path.dirname(reportPath);
+				if (!fs.existsSync(dir)) {
+					fs.mkdirSync(dir, { recursive: true });
+				}
+				fs.writeFileSync(reportPath, html, "utf8");
+			} catch (err: any) {
+				console.error(`[pi-context-map] Failed to write report: ${err.message}`);
+			}
+		}
+
+		// Broadcast to all SSE clients
+		for (const client of this.clients) {
+			try {
+				client.write(`data: ${JSON.stringify({ html, timestamp: Date.now() })}\n\n`);
+			} catch (err) {
+				// Client may have disconnected; remove it
+				this.clients.delete(client);
+			}
+		}
+	}
+
+	/**
+	 * Get the URL the server is listening on, or null if not started.
+	 */
+	public get url(): string | null {
+		if (!this.server || this.port === 0) return null;
+		return `http://${this.host}:${this.port}`;
+	}
+
+	/**
+	 * Whether the server is currently running.
+	 */
+	public get isRunning(): boolean {
+		return this.server !== null;
+	}
+
+	/**
+	 * Handle incoming HTTP requests.
+	 */
+	private handleRequest(req: http.IncomingMessage, res: http.ServerResponse): void {
+		if (!req.url) {
+			res.writeHead(400);
+			res.end("Bad request");
+			return;
+		}
+
+		const url = new URL(req.url, `http://${this.host}:${this.port}`);
+
+		// SSE endpoint for live updates
+		if (url.pathname === "/events") {
+			this.handleSSE(req, res);
+			return;
+		}
+
+		// Health check
+		if (url.pathname === "/health") {
+			res.writeHead(200, { "Content-Type": "application/json" });
+			res.end(JSON.stringify({ status: "ok", port: this.port }));
+			return;
+		}
+
+		// Stop endpoint
+		if (url.pathname === "/stop" && req.method === "POST") {
+			res.writeHead(200, { "Content-Type": "application/json" });
+			res.end(JSON.stringify({ status: "stopping" }));
+			setTimeout(() => this.stop(), 100);
+			return;
+		}
+
+		// Main page: serve the current HTML or load from disk
+		if (url.pathname === "/" || url.pathname === "/report.html") {
+			let html = this.currentHtml;
+			if (!html) {
+				// Try to load from disk as fallback
+				try {
+					html = fs.readFileSync(DEFAULT_REPORT_PATH, "utf8");
+				} catch {
+					html = this.placeholderHtml();
+				}
+			}
+			// Inject the session token so the client can authenticate to /events
+			if (html.includes("<head>")) {
+				html = html.replace(
+					"<head>",
+					`<head><meta name="context-map-token" content="${this.token}">`,
+				);
+			}
+			res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
+			res.end(html);
+			return;
+		}
+
+		// 404 for everything else
+		res.writeHead(404);
+		res.end("Not found");
+	}
+
+	/**
+	 * Handle Server-Sent Events connection.
+	 */
+	private handleSSE(req: http.IncomingMessage, res: http.ServerResponse): void {
+		// Token-based auth: require ?token=<sessionToken> to prevent unauthorized SSE subscriptions
+		if (!req.url) {
+			res.writeHead(400);
+			res.end("Bad request");
+			return;
+		}
+		const reqUrl = new URL(req.url, `http://${this.host}:${this.port}`);
+		const providedToken = reqUrl.searchParams.get("token");
+		if (providedToken !== this.token) {
+			res.writeHead(401, { "Content-Type": "text/plain" });
+			res.end("Unauthorized: invalid or missing token");
+			return;
+		}
+
+		// Origin validation: only allow connections from localhost
+		if (!isAllowedOrigin(req.headers.origin, this.port)) {
+			res.writeHead(403, { "Content-Type": "text/plain" });
+			res.end("Forbidden: origin not allowed");
+			return;
+		}
+
+		res.writeHead(200, {
+			"Content-Type": "text/event-stream",
+			"Cache-Control": "no-cache",
+			Connection: "keep-alive",
+			"Access-Control-Allow-Origin": `http://127.0.0.1:${this.port}`,
+		});
+
+		// Send initial state if we have content
+		if (this.currentHtml) {
+			res.write(`data: ${JSON.stringify({ html: this.currentHtml, timestamp: Date.now() })}\n\n`);
+		} else {
+			res.write(`data: ${JSON.stringify({ waiting: true })}\n\n`);
+		}
+
+		this.clients.add(res);
+
+		// Heartbeat to keep connection alive (every 30s)
+		const heartbeat = setInterval(() => {
+			try {
+				res.write(": heartbeat\n\n");
+			} catch {
+				clearInterval(heartbeat);
+				this.clients.delete(res);
+			}
+		}, 30000);
+
+		req.on("close", () => {
+			clearInterval(heartbeat);
+			this.clients.delete(res);
+		});
+	}
+
+	/**
+	 * Placeholder HTML shown when no report has been generated yet.
+	 */
+	private placeholderHtml(): string {
+		return `<!DOCTYPE html>
+<html><head><title>pi-context-map</title>
+<style>body{font-family:-apple-system,BlinkMacSystemFont,sans-serif;background:#010102;color:#f7f8f8;display:flex;align-items:center;justify-content:center;height:100vh;margin:0;}</style>
+</head><body>
+<div style="text-align:center;">
+<h1 style="color:#5e6ad2;font-size:24px;font-weight:600;">pi-context-map</h1>
+<p style="color:#8a8f98;margin-top:8px;">No report generated yet. Run <code>/context-map</code> in Pi to generate one.</p>
+</div>
+</body></html>`;
+	}
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-context-map",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "description": "Professional context profiler for Pi that visualizes the session context window, token distribution, and integrates with Nexus packages for actionable insights.",
   "keywords": [
     "pi-package",