@jagilber-org/index-server 1.19.1

package/dist/dashboard/server/DashboardServer.js

@@ -0,0 +1,159 @@
+"use strict";
+/* eslint-disable @typescript-eslint/no-explicit-any */
+/* eslint-disable */
+/**
+ * DashboardServer - Enhanced Phase 2 Dashboard with Real-time Features
+ *
+ * Coordinator class that wires together:
+ *  - Express middleware and routes (via mountDashboardRoutes)
+ *  - HTTP/HTTPS server lifecycle (via httpLifecycle)
+ *  - WebSocket initialization and metrics broadcast (via wsInit)
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DashboardServer = void 0;
+exports.createDashboardServer = createDashboardServer;
+const crypto_1 = __importDefault(require("crypto"));
+const express_1 = __importDefault(require("express"));
+const path_1 = __importDefault(require("path"));
+const MetricsCollector_js_1 = require("./MetricsCollector.js");
+const WebSocketManager_js_1 = require("./WebSocketManager.js");
+const httpLifecycle_js_1 = require("./httpLifecycle.js");
+const wsInit_js_1 = require("./wsInit.js");
+const index_js_1 = require("./routes/index.js");
+class DashboardServer {
+    app;
+    server = null;
+    metricsCollector = (0, MetricsCollector_js_1.getMetricsCollector)();
+    webSocketManager = (0, WebSocketManager_js_1.getWebSocketManager)();
+    metricsBroadcastTimer = null;
+    options;
+    get tlsEnabled() { return !!this.options.tls; }
+    get httpProtocol() { return this.tlsEnabled ? 'https' : 'http'; }
+    get wsProtocol() { return this.tlsEnabled ? 'wss' : 'ws'; }
+    constructor(options = {}) {
+        this.options = {
+            host: options.host || '127.0.0.1',
+            port: options.port || 8989,
+            maxPortTries: options.maxPortTries || 10,
+            enableWebSockets: options.enableWebSockets ?? true,
+            enableCors: options.enableCors ?? true,
+            metricsBroadcastIntervalMs: options.metricsBroadcastIntervalMs || 5000,
+            tls: options.tls,
+            graphEnabled: options.graphEnabled ?? false,
+        };
+        this.app = (0, express_1.default)();
+        this.setupMiddleware();
+        (0, index_js_1.mountDashboardRoutes)(this.app, {
+            metricsCollector: this.metricsCollector,
+            enableWebSockets: this.options.enableWebSockets,
+            enableCors: this.options.enableCors,
+            graphEnabled: this.options.graphEnabled,
+            wsProtocol: this.wsProtocol,
+            getServerInfo: () => this.getServerInfo(),
+        });
+    }
+    async start() {
+        for (let attempt = 0; attempt < this.options.maxPortTries; attempt++) {
+            const currentPort = this.options.port + attempt;
+            try {
+                this.server = (0, httpLifecycle_js_1.buildHttpServer)(this.app, this.options.tls);
+                await (0, httpLifecycle_js_1.bindToPort)(this.server, currentPort, this.options.host);
+                // eslint-disable-next-line no-console
+                console.log(`[Dashboard] Server started on ${this.httpProtocol}://${this.options.host}:${currentPort}`);
+                if (this.options.enableWebSockets) {
+                    (0, wsInit_js_1.initWebSocket)(this.server, this.webSocketManager);
+                    // eslint-disable-next-line no-console
+                    console.log(`[Dashboard] WebSocket support enabled on ${this.wsProtocol}://${this.options.host}:${currentPort}/ws`);
+                    this.metricsBroadcastTimer = (0, wsInit_js_1.startMetricsBroadcast)(this.webSocketManager, this.metricsCollector, this.options.metricsBroadcastIntervalMs);
+                }
+                return {
+                    url: `${this.httpProtocol}://${this.options.host}:${currentPort}/`,
+                    port: currentPort,
+                    close: () => this.stop(),
+                };
+            }
+            catch (error) {
+                if (error?.code === 'EADDRINUSE') {
+                    // eslint-disable-next-line no-console
+                    console.log(`[Dashboard] Port ${currentPort} in use, trying ${currentPort + 1}`);
+                    continue;
+                }
+                throw error;
+            }
+        }
+        throw new Error(`Failed to start dashboard server after ${this.options.maxPortTries} attempts`);
+    }
+    async stop() {
+        if (this.server) {
+            if (this.options.enableWebSockets) {
+                this.webSocketManager.close();
+                if (this.metricsBroadcastTimer) {
+                    clearInterval(this.metricsBroadcastTimer);
+                    this.metricsBroadcastTimer = null;
+                }
+            }
+            await (0, httpLifecycle_js_1.closeHttpServer)(this.server);
+        }
+    }
+    getServerInfo() {
+        if (!this.server?.listening) {
+            return null;
+        }
+        const address = this.server.address();
+        if (!address || typeof address === 'string') {
+            return null;
+        }
+        return {
+            port: address.port,
+            host: this.options.host,
+            url: `${this.httpProtocol}://${this.options.host}:${address.port}`,
+        };
+    }
+    setupMiddleware() {
+        if (this.options.enableCors) {
+            this.app.use((req, res, next) => {
+                const origin = req.headers.origin;
+                if (origin && /^https?:\/\/(localhost|127\.0\.0\.1)(:\d+)?$/.test(origin)) {
+                    res.header('Access-Control-Allow-Origin', origin);
+                }
+                res.header('Access-Control-Allow-Methods', 'GET, POST, PUT, DELETE, OPTIONS');
+                res.header('Access-Control-Allow-Headers', 'Origin, X-Requested-With, Content-Type, Accept, Authorization');
+                if (req.method === 'OPTIONS') {
+                    res.sendStatus(200);
+                    return;
+                }
+                next();
+            });
+        }
+        // Remove X-Powered-By (technology fingerprinting) and enforce strong ETags
+        this.app.disable('x-powered-by');
+        this.app.set('etag', 'strong');
+        // Per-request CSP nonce + security headers
+        this.app.use((_req, res, next) => {
+            const nonce = crypto_1.default.randomBytes(16).toString('base64');
+            res.locals.cspNonce = nonce;
+            res.header('X-Content-Type-Options', 'nosniff');
+            res.header('X-Frame-Options', 'DENY');
+            res.header('X-XSS-Protection', '1; mode=block');
+            res.header('Referrer-Policy', 'strict-origin-when-cross-origin');
+            res.header('Content-Security-Policy', `default-src 'self'; script-src 'self' 'nonce-${nonce}' 'unsafe-inline'; style-src 'self' 'unsafe-inline'; font-src 'self'; img-src 'self' data:; connect-src 'self' ${this.tlsEnabled ? 'wss:' : 'ws:'}; frame-ancestors 'none'; form-action 'self'`);
+            if (this.tlsEnabled) {
+                res.header('Strict-Transport-Security', 'max-age=31536000; includeSubDomains');
+            }
+            next();
+        });
+        this.app.use(express_1.default.json());
+        this.app.use(express_1.default.static(path_1.default.join(__dirname, '..', 'client'), {
+            etag: true,
+            lastModified: true,
+        }));
+    }
+}
+exports.DashboardServer = DashboardServer;
+function createDashboardServer(options = {}) {
+    return new DashboardServer(options);
+}
+exports.default = createDashboardServer;

package/dist/dashboard/server/FileMetricsStorage.d.ts

@@ -0,0 +1,49 @@
+import { MetricsSnapshot } from './MetricsCollector';
+/**
+ * File-based storage for metrics snapshots to prevent memory accumulation
+ * Stores snapshots as individual JSON files with timestamp-based naming
+ */
+export declare class FileMetricsStorage {
+    private storageDir;
+    private maxFiles;
+    private retentionMinutes;
+    constructor(options?: {
+        storageDir?: string;
+        maxFiles?: number;
+        retentionMinutes?: number;
+    });
+    /**
+     * Store a metrics snapshot to disk
+     */
+    storeSnapshot(snapshot: MetricsSnapshot): Promise<void>;
+    /**
+     * Get recent snapshots from disk (for dashboard/analysis)
+     */
+    getRecentSnapshots(count?: number): Promise<MetricsSnapshot[]>;
+    /**
+     * Get snapshots within a time range
+     */
+    getSnapshotsInRange(startTime: number, endTime: number): Promise<MetricsSnapshot[]>;
+    /**
+     * Get storage statistics
+     */
+    getStorageStats(): Promise<{
+        fileCount: number;
+        totalSizeKB: number;
+        oldestTimestamp?: number;
+        newestTimestamp?: number;
+    }>;
+    /**
+     * Clear all stored metrics
+     */
+    clearAll(): Promise<void>;
+    private ensureStorageDir;
+    private getSnapshotFiles;
+    private extractTimestampFromFilename;
+    private cleanupOldFiles;
+}
+export declare function getFileMetricsStorage(options?: {
+    storageDir?: string;
+    maxFiles?: number;
+    retentionMinutes?: number;
+}): FileMetricsStorage;

package/dist/dashboard/server/FileMetricsStorage.js

@@ -0,0 +1,195 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FileMetricsStorage = void 0;
+exports.getFileMetricsStorage = getFileMetricsStorage;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+/**
+ * File-based storage for metrics snapshots to prevent memory accumulation
+ * Stores snapshots as individual JSON files with timestamp-based naming
+ */
+class FileMetricsStorage {
+    storageDir;
+    maxFiles;
+    retentionMinutes;
+    constructor(options = {}) {
+        this.storageDir = options.storageDir || path_1.default.join(process.cwd(), 'metrics');
+        this.maxFiles = options.maxFiles || 720; // 12 hours at 1-minute intervals
+        this.retentionMinutes = options.retentionMinutes || 60;
+        this.ensureStorageDir();
+    }
+    /**
+     * Store a metrics snapshot to disk
+     */
+    async storeSnapshot(snapshot) {
+        try {
+            const filename = `metrics-${snapshot.timestamp}.json`;
+            const filepath = path_1.default.join(this.storageDir, filename);
+            await fs_1.default.promises.writeFile(filepath, JSON.stringify(snapshot, null, 2), 'utf8');
+            // Clean up old files periodically (every 10th write)
+            if (snapshot.timestamp % 10 === 0) {
+                await this.cleanupOldFiles();
+            }
+        }
+        catch (error) {
+            console.error('Failed to store metrics snapshot:', error);
+        }
+    }
+    /**
+     * Get recent snapshots from disk (for dashboard/analysis)
+     */
+    async getRecentSnapshots(count = 60) {
+        try {
+            const files = await this.getSnapshotFiles();
+            const recentFiles = files.slice(-count);
+            const snapshots = [];
+            for (const file of recentFiles) {
+                try {
+                    const content = await fs_1.default.promises.readFile(path_1.default.join(this.storageDir, file), 'utf8');
+                    snapshots.push(JSON.parse(content));
+                }
+                catch (error) {
+                    console.warn(`Failed to read metrics file ${file}:`, error);
+                }
+            }
+            return snapshots.sort((a, b) => a.timestamp - b.timestamp);
+        }
+        catch (error) {
+            console.error('Failed to load recent snapshots:', error);
+            return [];
+        }
+    }
+    /**
+     * Get snapshots within a time range
+     */
+    async getSnapshotsInRange(startTime, endTime) {
+        try {
+            const files = await this.getSnapshotFiles();
+            const snapshots = [];
+            for (const file of files) {
+                const timestamp = this.extractTimestampFromFilename(file);
+                if (timestamp >= startTime && timestamp <= endTime) {
+                    try {
+                        const content = await fs_1.default.promises.readFile(path_1.default.join(this.storageDir, file), 'utf8');
+                        snapshots.push(JSON.parse(content));
+                    }
+                    catch (error) {
+                        console.warn(`Failed to read metrics file ${file}:`, error);
+                    }
+                }
+            }
+            return snapshots.sort((a, b) => a.timestamp - b.timestamp);
+        }
+        catch (error) {
+            console.error('Failed to load snapshots in range:', error);
+            return [];
+        }
+    }
+    /**
+     * Get storage statistics
+     */
+    async getStorageStats() {
+        try {
+            const files = await this.getSnapshotFiles();
+            if (files.length === 0) {
+                return { fileCount: 0, totalSizeKB: 0 };
+            }
+            let totalSize = 0;
+            for (const file of files) {
+                try {
+                    const stat = await fs_1.default.promises.stat(path_1.default.join(this.storageDir, file));
+                    totalSize += stat.size;
+                }
+                catch {
+                    // Ignore individual file errors
+                }
+            }
+            const timestamps = files.map(f => this.extractTimestampFromFilename(f)).filter(t => t > 0);
+            return {
+                fileCount: files.length,
+                totalSizeKB: Math.round(totalSize / 1024),
+                oldestTimestamp: timestamps.length > 0 ? Math.min(...timestamps) : undefined,
+                newestTimestamp: timestamps.length > 0 ? Math.max(...timestamps) : undefined,
+            };
+        }
+        catch (error) {
+            console.error('Failed to get storage stats:', error);
+            return { fileCount: 0, totalSizeKB: 0 };
+        }
+    }
+    /**
+     * Clear all stored metrics
+     */
+    async clearAll() {
+        try {
+            const files = await this.getSnapshotFiles();
+            await Promise.all(files.map(file => fs_1.default.promises.unlink(path_1.default.join(this.storageDir, file)).catch(() => { })));
+        }
+        catch (error) {
+            console.error('Failed to clear metrics storage:', error);
+        }
+    }
+    async ensureStorageDir() {
+        try {
+            await fs_1.default.promises.mkdir(this.storageDir, { recursive: true });
+        }
+        catch (error) {
+            console.error('Failed to create metrics storage directory:', error);
+        }
+    }
+    async getSnapshotFiles() {
+        try {
+            const files = await fs_1.default.promises.readdir(this.storageDir);
+            return files
+                .filter(f => f.startsWith('metrics-') && f.endsWith('.json'))
+                .sort(); // Chronological order due to timestamp-based naming
+        }
+        catch (error) {
+            return [];
+        }
+    }
+    extractTimestampFromFilename(filename) {
+        const match = filename.match(/^metrics-(\d+)\.json$/);
+        return match ? parseInt(match[1], 10) : 0;
+    }
+    async cleanupOldFiles() {
+        try {
+            const files = await this.getSnapshotFiles();
+            const now = Date.now();
+            const cutoffTime = now - (this.retentionMinutes * 60 * 1000);
+            // Remove files older than retention period
+            const expiredFiles = files.filter(file => {
+                const timestamp = this.extractTimestampFromFilename(file);
+                return timestamp < cutoffTime;
+            });
+            // Remove excess files (keep only maxFiles most recent)
+            let filesToDelete = expiredFiles;
+            if (files.length > this.maxFiles) {
+                const excessCount = files.length - this.maxFiles;
+                const oldestFiles = files.slice(0, excessCount);
+                filesToDelete = [...new Set([...expiredFiles, ...oldestFiles])];
+            }
+            if (filesToDelete.length > 0) {
+                await Promise.all(filesToDelete.map(file => fs_1.default.promises.unlink(path_1.default.join(this.storageDir, file)).catch(() => { })));
+                console.log(`Cleaned up ${filesToDelete.length} old metrics files`);
+            }
+        }
+        catch (error) {
+            console.error('Failed to cleanup old metrics files:', error);
+        }
+    }
+}
+exports.FileMetricsStorage = FileMetricsStorage;
+/**
+ * Global file storage instance
+ */
+let globalFileStorage = null;
+function getFileMetricsStorage(options) {
+    if (!globalFileStorage) {
+        globalFileStorage = new FileMetricsStorage(options);
+    }
+    return globalFileStorage;
+}

package/dist/dashboard/server/HttpTransport.d.ts

@@ -0,0 +1,23 @@
+/**
+ * HttpTransport - HTTP/JSON-RPC transport for the Index Server leader.
+ *
+ * **EXPERIMENTAL** — APIs, configuration, and behavior may change.
+ *
+ * When running as leader, the server exposes an HTTP endpoint that thin clients
+ * can forward JSON-RPC requests to. This reuses the existing handler registry
+ * so all MCP tools work over HTTP without any handler changes.
+ *
+ * Endpoints:
+ *   POST /mcp/rpc    - JSON-RPC 2.0 request/response
+ *   GET  /mcp/health - Health check for thin clients
+ *   GET  /mcp/leader - Leader info (PID, port, role)
+ */
+import { Router } from 'express';
+export interface HttpTransportOptions {
+    /** Handler lookup function (defaults to registry getHandler) */
+    handlerLookup?: (method: string) => ((params: unknown) => Promise<unknown>) | undefined;
+}
+/**
+ * Create an Express router for the MCP HTTP transport.
+ */
+export declare function createMcpTransportRoutes(options?: HttpTransportOptions): Router;

package/dist/dashboard/server/HttpTransport.js

@@ -0,0 +1,116 @@
+"use strict";
+/**
+ * HttpTransport - HTTP/JSON-RPC transport for the Index Server leader.
+ *
+ * **EXPERIMENTAL** — APIs, configuration, and behavior may change.
+ *
+ * When running as leader, the server exposes an HTTP endpoint that thin clients
+ * can forward JSON-RPC requests to. This reuses the existing handler registry
+ * so all MCP tools work over HTTP without any handler changes.
+ *
+ * Endpoints:
+ *   POST /mcp/rpc    - JSON-RPC 2.0 request/response
+ *   GET  /mcp/health - Health check for thin clients
+ *   GET  /mcp/leader - Leader info (PID, port, role)
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createMcpTransportRoutes = createMcpTransportRoutes;
+const express_1 = __importStar(require("express"));
+const registry_1 = require("../../server/registry");
+/**
+ * Create an Express router for the MCP HTTP transport.
+ */
+function createMcpTransportRoutes(options = {}) {
+    const router = (0, express_1.Router)();
+    const lookup = options.handlerLookup ?? registry_1.getLocalHandler;
+    // Health check for thin client connectivity probing
+    router.get('/health', (_req, res) => {
+        res.json({
+            status: 'ok',
+            pid: process.pid,
+            uptime: process.uptime(),
+            timestamp: new Date().toISOString(),
+        });
+    });
+    // Leader info endpoint
+    router.get('/leader', (_req, res) => {
+        res.json({
+            pid: process.pid,
+            port: (res.req.socket.localPort || 0),
+            role: 'leader',
+            timestamp: new Date().toISOString(),
+        });
+    });
+    // JSON-RPC 2.0 endpoint
+    router.post('/rpc', express_1.default.json({ limit: '1mb' }), async (req, res) => {
+        const body = req.body;
+        // Validate JSON-RPC structure
+        if (!body || body.jsonrpc !== '2.0' || !body.method) {
+            return res.status(400).json({
+                jsonrpc: '2.0',
+                error: { code: -32600, message: 'Invalid Request: missing jsonrpc or method' },
+                id: body?.id ?? null,
+            });
+        }
+        const { method, params, id } = body;
+        // Look up handler
+        const handler = lookup(method);
+        if (!handler) {
+            return res.status(404).json({
+                jsonrpc: '2.0',
+                error: { code: -32601, message: `Method not found: ${method}` },
+                id: id ?? null,
+            });
+        }
+        try {
+            const result = await handler(params ?? {});
+            res.json({
+                jsonrpc: '2.0',
+                result,
+                id: id ?? null,
+            });
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : 'Internal error';
+            res.status(500).json({
+                jsonrpc: '2.0',
+                error: { code: -32603, message },
+                id: id ?? null,
+            });
+        }
+    });
+    return router;
+}

package/dist/dashboard/server/InstanceManager.d.ts

@@ -0,0 +1,53 @@
+/**
+ * InstanceManager - Discovers running Index Server dashboard instances.
+ *
+ * Each dashboard writes a small JSON port file on startup and removes it on
+ * shutdown. Other instances (and the `/api/instances` endpoint) read these
+ * files to present a list of all active servers the user can switch between.
+ *
+ * Port file location: `<stateDir>/dashboard-<pid>.json`
+ * Default stateDir:   `<cwd>/data/state`  (override via INDEX_SERVER_STATE_DIR)
+ */
+export interface PortFileEntry {
+    pid: number;
+    port: number;
+    host: string;
+    startedAt: string;
+    protocol?: 'http' | 'https';
+}
+export interface InstanceInfo extends PortFileEntry {
+    current: boolean;
+    alive: boolean;
+}
+/**
+ * Write a port file for the current process.
+ * Called once when the dashboard HTTP server starts listening.
+ */
+export declare function writePortFile(port: number, host: string): void;
+/**
+ * Remove the port file for the current process.
+ * Called during graceful shutdown.
+ */
+export declare function removePortFile(): void;
+/**
+ * Remove stale port files for processes that no longer exist.
+ * Called on startup to clean up after crashes.
+ */
+export declare function cleanStalePortFiles(): void;
+/**
+ * Get a list of all active dashboard instances by reading port files.
+ * Stale files (dead PIDs) are cleaned up automatically.
+ */
+export declare function getActiveInstances(): InstanceInfo[];
+/**
+ * Validate all registered instances by HTTP health check.
+ * Removes port files for instances that are alive (PID exists) but no longer
+ * respond on their registered port -- i.e., orphaned processes whose dashboard
+ * HTTP server has shut down or whose PID was recycled.
+ *
+ * Called periodically from a background timer (every ~30s). Skips the current
+ * process (always considered valid).
+ */
+export declare function validateInstances(): Promise<void>;
+/** Reset the cached state dir (useful for testing). */
+export declare function _resetStateDir(): void;