@jagilber-org/index-server 1.19.1

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

@@ -0,0 +1,88 @@
+/**
+ * SessionPersistenceManager
+ *
+ * Manages persistent storage of admin sessions, websocket connections, and session history
+ * with deduplication, atomic writes, and backup integration.
+ */
+import { SessionPersistenceConfig, SessionPersistenceData } from '../../models/SessionPersistence.js';
+export declare class SessionPersistenceManager {
+    private static persistenceQueues;
+    private config;
+    private persistenceTimer;
+    private lastPersistedData;
+    private isShuttingDown;
+    constructor(config?: Partial<SessionPersistenceConfig>);
+    /**
+     * Load configuration from the centralized dashboard config module
+     */
+    private loadConfigFromEnvironment;
+    /**
+     * Setup periodic persistence timer
+     */
+    private setupPeriodicPersistence;
+    /**
+     * Setup graceful shutdown handler
+     */
+    private setupShutdownHandler;
+    /**
+     * Calculate checksum for deduplication
+     */
+    private calculateChecksum;
+    /**
+     * Check if data has changed since last persistence
+     */
+    private hasDataChanged;
+    /**
+     * Ensure persistence directories exist
+     */
+    private ensureDirectories;
+    /**
+     * Atomic file write with backup
+     */
+    private atomicWrite;
+    private getQueueKey;
+    private withPersistenceLock;
+    private defaultManifest;
+    private createDefaultMetadata;
+    private archiveCorruptFile;
+    private parseJsonFileOrFallback;
+    /**
+     * Apply retention policies to data
+     */
+    private applyRetentionPolicies;
+    /**
+     * Create backup of current persistence data
+     */
+    private createBackup;
+    /**
+     * Persist session data to disk
+     */
+    persistData(data: SessionPersistenceData): Promise<void>;
+    /**
+     * Load persisted session data from disk
+     */
+    loadData(): Promise<SessionPersistenceData | null>;
+    /**
+     * Clear all session history (for UI clear history button)
+     */
+    clearHistory(): Promise<void>;
+    /**
+     * Get persistence status and statistics
+     */
+    getStatus(): {
+        enabled: boolean;
+        lastPersisted: string | null;
+        totalSessions: number;
+        totalConnections: number;
+        totalHistoryEntries: number;
+        config: SessionPersistenceConfig;
+    };
+    /**
+     * Placeholder for current state persistence (to be implemented by callers)
+     */
+    persistCurrentState(): Promise<void>;
+    /**
+     * Cleanup - stop timers and persist final state
+     */
+    cleanup(): Promise<void>;
+}

package/dist/dashboard/server/SessionPersistenceManager.js

@@ -0,0 +1,457 @@
+"use strict";
+/**
+ * SessionPersistenceManager
+ *
+ * Manages persistent storage of admin sessions, websocket connections, and session history
+ * with deduplication, atomic writes, and backup integration.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SessionPersistenceManager = void 0;
+const fs_1 = require("fs");
+const path_1 = require("path");
+const crypto_1 = require("crypto");
+const SessionPersistence_js_1 = require("../../models/SessionPersistence.js");
+const runtimeConfig_js_1 = require("../../config/runtimeConfig.js");
+class SessionPersistenceManager {
+    static persistenceQueues = new Map();
+    config;
+    persistenceTimer = null;
+    lastPersistedData = null;
+    isShuttingDown = false;
+    constructor(config) {
+        this.config = { ...SessionPersistence_js_1.DEFAULT_SESSION_PERSISTENCE_CONFIG, ...config };
+        this.loadConfigFromEnvironment();
+        if (this.config.enabled) {
+            this.setupPeriodicPersistence();
+            this.setupShutdownHandler();
+        }
+    }
+    /**
+     * Load configuration from the centralized dashboard config module
+     */
+    loadConfigFromEnvironment() {
+        const sp = (0, runtimeConfig_js_1.getRuntimeConfig)().dashboard.sessionPersistence;
+        this.config.enabled = sp.enabled;
+        this.config.persistenceDir = sp.persistenceDir;
+        this.config.backupIntegration = sp.backupIntegration;
+        this.config.retention.maxHistoryEntries = sp.retention.maxHistoryEntries;
+        this.config.retention.maxHistoryDays = sp.retention.maxHistoryDays;
+        this.config.retention.maxConnectionHistoryDays = sp.retention.maxConnectionHistoryDays;
+        this.config.persistence.intervalMs = sp.persistenceIntervalMs;
+        this.config.deduplication.enabled = sp.deduplicationEnabled;
+    }
+    /**
+     * Setup periodic persistence timer
+     */
+    setupPeriodicPersistence() {
+        if (this.config.persistence.intervalMs > 0) {
+            this.persistenceTimer = setInterval(() => {
+                if (!this.isShuttingDown) {
+                    this.persistCurrentState().catch(err => {
+                        console.error('[SessionPersistence] Periodic persistence failed:', err);
+                    });
+                }
+            }, this.config.persistence.intervalMs);
+        }
+    }
+    /**
+     * Setup graceful shutdown handler
+     */
+    setupShutdownHandler() {
+        if (this.config.persistence.onShutdown) {
+            const gracefulShutdown = async () => {
+                if (!this.isShuttingDown) {
+                    this.isShuttingDown = true;
+                    console.log('[SessionPersistence] Graceful shutdown initiated...');
+                    // Clear periodic timer
+                    if (this.persistenceTimer) {
+                        clearInterval(this.persistenceTimer);
+                        this.persistenceTimer = null;
+                    }
+                    // Final persistence
+                    try {
+                        await this.persistCurrentState();
+                        console.log('[SessionPersistence] Final state persisted successfully');
+                    }
+                    catch (err) {
+                        console.error('[SessionPersistence] Final persistence failed:', err);
+                    }
+                }
+            };
+            process.on('SIGTERM', gracefulShutdown);
+            process.on('SIGINT', gracefulShutdown);
+            process.on('beforeExit', gracefulShutdown);
+        }
+    }
+    /**
+     * Calculate checksum for deduplication
+     */
+    calculateChecksum(data) {
+        return (0, crypto_1.createHash)(this.config.deduplication.checksumAlgorithm)
+            .update(data)
+            .digest('hex');
+    }
+    /**
+     * Check if data has changed since last persistence
+     */
+    hasDataChanged(data) {
+        if (!this.config.deduplication.enabled || !this.lastPersistedData) {
+            return true;
+        }
+        const currentChecksums = {
+            sessions: this.calculateChecksum(JSON.stringify(data.adminSessions.map((s) => s.id).sort())),
+            connections: this.calculateChecksum(JSON.stringify(data.webSocketConnections.map((c) => c.id).sort())),
+            history: this.calculateChecksum(JSON.stringify(data.sessionHistory.map((h) => h.id).sort()))
+        };
+        const lastChecksums = this.lastPersistedData.metadata.checksums;
+        return (currentChecksums.sessions !== lastChecksums.sessions ||
+            currentChecksums.connections !== lastChecksums.connections ||
+            currentChecksums.history !== lastChecksums.history);
+    }
+    /**
+     * Ensure persistence directories exist
+     */
+    async ensureDirectories() {
+        const sessionsDir = (0, path_1.join)(this.config.persistenceDir, 'sessions');
+        const backupsDir = (0, path_1.join)(this.config.persistenceDir, 'backups');
+        await fs_1.promises.mkdir(sessionsDir, { recursive: true });
+        if (this.config.backupIntegration) {
+            await fs_1.promises.mkdir(backupsDir, { recursive: true });
+        }
+    }
+    /**
+     * Atomic file write with backup
+     */
+    async atomicWrite(filePath, content) {
+        if (!this.config.atomicWrites.enabled) {
+            await fs_1.promises.writeFile(filePath, content, 'utf8');
+            return;
+        }
+        const tempPath = `${filePath}.${process.pid}.${Date.now()}.${Math.random().toString(36).slice(2)}${this.config.atomicWrites.tempSuffix}`;
+        const backupPath = filePath + this.config.atomicWrites.backupSuffix;
+        try {
+            // Write to temporary file
+            await fs_1.promises.writeFile(tempPath, content, 'utf8');
+            // Backup existing file if it exists
+            try {
+                await fs_1.promises.access(filePath);
+                await fs_1.promises.copyFile(filePath, backupPath);
+            }
+            catch {
+                // File doesn't exist, no backup needed
+            }
+            // Atomic move
+            await fs_1.promises.rename(tempPath, filePath);
+            // Remove backup if successful
+            try {
+                await fs_1.promises.unlink(backupPath);
+            }
+            catch {
+                // Backup removal failure is not critical
+            }
+        }
+        catch (err) {
+            // Cleanup temp file on failure
+            try {
+                await fs_1.promises.unlink(tempPath);
+            }
+            catch {
+                // Cleanup failure is not critical
+            }
+            throw err;
+        }
+    }
+    getQueueKey() {
+        return (0, path_1.join)(this.config.persistenceDir, 'sessions');
+    }
+    async withPersistenceLock(work) {
+        const queueKey = this.getQueueKey();
+        const previous = SessionPersistenceManager.persistenceQueues.get(queueKey) ?? Promise.resolve();
+        let release;
+        const current = new Promise((resolve) => {
+            release = resolve;
+        });
+        const tail = previous.catch(() => undefined).then(() => current);
+        SessionPersistenceManager.persistenceQueues.set(queueKey, tail);
+        await previous.catch(() => undefined);
+        try {
+            return await work();
+        }
+        finally {
+            release?.();
+            if (SessionPersistenceManager.persistenceQueues.get(queueKey) === tail) {
+                SessionPersistenceManager.persistenceQueues.delete(queueKey);
+            }
+        }
+    }
+    defaultManifest() {
+        return {
+            metadata: this.createDefaultMetadata([], [], []),
+            files: {
+                adminSessions: SessionPersistence_js_1.SESSION_PERSISTENCE_FILES.ADMIN_SESSIONS,
+                webSocketConnections: SessionPersistence_js_1.SESSION_PERSISTENCE_FILES.WEBSOCKET_CONNECTIONS,
+                sessionHistory: SessionPersistence_js_1.SESSION_PERSISTENCE_FILES.SESSION_HISTORY,
+            },
+            retention: this.config.retention,
+        };
+    }
+    createDefaultMetadata(adminSessions, webSocketConnections, sessionHistory) {
+        return {
+            lastPersisted: new Date(0).toISOString(),
+            version: 1,
+            totalSessions: adminSessions.length,
+            totalConnections: webSocketConnections.length,
+            totalHistoryEntries: sessionHistory.length,
+            checksums: {
+                sessions: this.calculateChecksum(JSON.stringify(adminSessions.map(session => session.id).sort())),
+                connections: this.calculateChecksum(JSON.stringify(webSocketConnections.map(connection => connection.id).sort())),
+                history: this.calculateChecksum(JSON.stringify(sessionHistory.map(entry => entry.id).sort())),
+            },
+        };
+    }
+    async archiveCorruptFile(filePath) {
+        const corruptPath = `${filePath}.corrupt-${Date.now()}`;
+        try {
+            await fs_1.promises.rename(filePath, corruptPath);
+        }
+        catch {
+            // Best effort only; keep going with fallback content.
+        }
+    }
+    async parseJsonFileOrFallback(filePath, fallback, validate, label) {
+        try {
+            const content = await fs_1.promises.readFile(filePath, 'utf8');
+            const parsed = JSON.parse(content.replace(/^\uFEFF/, ''));
+            if (validate(parsed)) {
+                return parsed;
+            }
+            throw new Error(`Unexpected ${label} shape`);
+        }
+        catch (err) {
+            if (err.code === 'ENOENT') {
+                return fallback;
+            }
+            console.warn(`[SessionPersistence] Invalid ${label} in ${filePath}; archiving corrupt file and using fallback.`, err);
+            await this.archiveCorruptFile(filePath);
+            await this.atomicWrite(filePath, JSON.stringify(fallback, null, 2));
+            return fallback;
+        }
+    }
+    /**
+     * Apply retention policies to data
+     */
+    applyRetentionPolicies(data) {
+        const now = new Date();
+        const maxHistoryDate = new Date(now.getTime() - (this.config.retention.maxHistoryDays * 24 * 60 * 60 * 1000));
+        const maxConnectionDate = new Date(now.getTime() - (this.config.retention.maxConnectionHistoryDays * 24 * 60 * 60 * 1000));
+        // Filter session history by date and count
+        const filteredHistory = data.sessionHistory
+            .filter(entry => {
+            const entryDate = new Date(entry.startTime);
+            return entryDate >= maxHistoryDate;
+        })
+            .sort((a, b) => new Date(b.startTime).getTime() - new Date(a.startTime).getTime())
+            .slice(0, this.config.retention.maxHistoryEntries);
+        // Filter connection history by date
+        const filteredConnections = data.webSocketConnections
+            .filter(conn => {
+            const connDate = new Date(conn.connectedAt);
+            return connDate >= maxConnectionDate;
+        });
+        return {
+            ...data,
+            sessionHistory: filteredHistory,
+            webSocketConnections: filteredConnections
+        };
+    }
+    /**
+     * Create backup of current persistence data
+     */
+    async createBackup(data) {
+        if (!this.config.backupIntegration) {
+            return;
+        }
+        const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+        const backupDir = (0, path_1.join)(this.config.persistenceDir, 'backups', timestamp);
+        await fs_1.promises.mkdir(backupDir, { recursive: true });
+        const backupFiles = [
+            { name: SessionPersistence_js_1.SESSION_PERSISTENCE_FILES.ADMIN_SESSIONS, data: data.adminSessions },
+            { name: SessionPersistence_js_1.SESSION_PERSISTENCE_FILES.WEBSOCKET_CONNECTIONS, data: data.webSocketConnections },
+            { name: SessionPersistence_js_1.SESSION_PERSISTENCE_FILES.SESSION_HISTORY, data: data.sessionHistory },
+            { name: SessionPersistence_js_1.SESSION_PERSISTENCE_FILES.METADATA, data: data.metadata }
+        ];
+        for (const file of backupFiles) {
+            const backupPath = (0, path_1.join)(backupDir, file.name);
+            await fs_1.promises.writeFile(backupPath, JSON.stringify(file.data, null, 2), 'utf8');
+        }
+        // Create manifest
+        const manifest = {
+            metadata: data.metadata,
+            files: {
+                adminSessions: SessionPersistence_js_1.SESSION_PERSISTENCE_FILES.ADMIN_SESSIONS,
+                webSocketConnections: SessionPersistence_js_1.SESSION_PERSISTENCE_FILES.WEBSOCKET_CONNECTIONS,
+                sessionHistory: SessionPersistence_js_1.SESSION_PERSISTENCE_FILES.SESSION_HISTORY
+            },
+            retention: this.config.retention
+        };
+        await fs_1.promises.writeFile((0, path_1.join)(backupDir, SessionPersistence_js_1.SESSION_PERSISTENCE_FILES.MANIFEST), JSON.stringify(manifest, null, 2), 'utf8');
+    }
+    /**
+     * Persist session data to disk
+     */
+    async persistData(data) {
+        if (!this.config.enabled) {
+            return;
+        }
+        // Check for changes if deduplication is enabled
+        if (!this.hasDataChanged(data)) {
+            return; // No changes, skip persistence
+        }
+        // Apply retention policies
+        const filteredData = this.applyRetentionPolicies(data);
+        // Update metadata
+        const now = new Date().toISOString();
+        filteredData.metadata = {
+            ...filteredData.metadata,
+            lastPersisted: now,
+            totalSessions: filteredData.adminSessions.length,
+            totalConnections: filteredData.webSocketConnections.length,
+            totalHistoryEntries: filteredData.sessionHistory.length,
+            checksums: {
+                sessions: this.calculateChecksum(JSON.stringify(filteredData.adminSessions.map(s => s.id).sort())),
+                connections: this.calculateChecksum(JSON.stringify(filteredData.webSocketConnections.map(c => c.id).sort())),
+                history: this.calculateChecksum(JSON.stringify(filteredData.sessionHistory.map(h => h.id).sort()))
+            }
+        };
+        await this.withPersistenceLock(async () => {
+            await this.ensureDirectories();
+            const sessionsDir = (0, path_1.join)(this.config.persistenceDir, 'sessions');
+            // Create backup before writing new data
+            await this.createBackup(filteredData);
+            // Write data files
+            await this.atomicWrite((0, path_1.join)(sessionsDir, SessionPersistence_js_1.SESSION_PERSISTENCE_FILES.ADMIN_SESSIONS), JSON.stringify(filteredData.adminSessions, null, 2));
+            await this.atomicWrite((0, path_1.join)(sessionsDir, SessionPersistence_js_1.SESSION_PERSISTENCE_FILES.WEBSOCKET_CONNECTIONS), JSON.stringify(filteredData.webSocketConnections, null, 2));
+            await this.atomicWrite((0, path_1.join)(sessionsDir, SessionPersistence_js_1.SESSION_PERSISTENCE_FILES.SESSION_HISTORY), JSON.stringify(filteredData.sessionHistory, null, 2));
+            await this.atomicWrite((0, path_1.join)(sessionsDir, SessionPersistence_js_1.SESSION_PERSISTENCE_FILES.METADATA), JSON.stringify(filteredData.metadata, null, 2));
+            // Write manifest
+            const manifest = {
+                metadata: filteredData.metadata,
+                files: {
+                    adminSessions: SessionPersistence_js_1.SESSION_PERSISTENCE_FILES.ADMIN_SESSIONS,
+                    webSocketConnections: SessionPersistence_js_1.SESSION_PERSISTENCE_FILES.WEBSOCKET_CONNECTIONS,
+                    sessionHistory: SessionPersistence_js_1.SESSION_PERSISTENCE_FILES.SESSION_HISTORY
+                },
+                retention: this.config.retention
+            };
+            await this.atomicWrite((0, path_1.join)(sessionsDir, SessionPersistence_js_1.SESSION_PERSISTENCE_FILES.MANIFEST), JSON.stringify(manifest, null, 2));
+            this.lastPersistedData = filteredData;
+        }).catch((err) => {
+            console.error('[SessionPersistence] Failed to persist data:', err);
+            throw err;
+        });
+    }
+    /**
+     * Load persisted session data from disk
+     */
+    async loadData() {
+        if (!this.config.enabled) {
+            return null;
+        }
+        const sessionsDir = (0, path_1.join)(this.config.persistenceDir, 'sessions');
+        const manifestPath = (0, path_1.join)(sessionsDir, SessionPersistence_js_1.SESSION_PERSISTENCE_FILES.MANIFEST);
+        try {
+            // Check if manifest exists
+            await fs_1.promises.access(manifestPath);
+            const manifest = await this.parseJsonFileOrFallback(manifestPath, this.defaultManifest(), (value) => !!value && typeof value === 'object' && !Array.isArray(value), 'session persistence manifest');
+            // Load data files
+            const [adminSessions, webSocketConnections, sessionHistory, metadata] = await Promise.all([
+                this.parseJsonFileOrFallback((0, path_1.join)(sessionsDir, manifest.files.adminSessions), [], Array.isArray, 'admin sessions'),
+                this.parseJsonFileOrFallback((0, path_1.join)(sessionsDir, manifest.files.webSocketConnections), [], Array.isArray, 'websocket connections'),
+                this.parseJsonFileOrFallback((0, path_1.join)(sessionsDir, manifest.files.sessionHistory), [], Array.isArray, 'session history'),
+                this.parseJsonFileOrFallback((0, path_1.join)(sessionsDir, SessionPersistence_js_1.SESSION_PERSISTENCE_FILES.METADATA), this.createDefaultMetadata([], [], []), (value) => !!value && typeof value === 'object' && !Array.isArray(value), 'session metadata')
+            ]);
+            const data = {
+                adminSessions,
+                webSocketConnections,
+                sessionHistory,
+                metadata: {
+                    ...this.createDefaultMetadata(adminSessions, webSocketConnections, sessionHistory),
+                    ...metadata,
+                    totalSessions: adminSessions.length,
+                    totalConnections: webSocketConnections.length,
+                    totalHistoryEntries: sessionHistory.length,
+                }
+            };
+            this.lastPersistedData = data;
+            return data;
+        }
+        catch (err) {
+            if (err.code === 'ENOENT') {
+                // No persisted data exists yet
+                return null;
+            }
+            console.error('[SessionPersistence] Failed to load data:', err);
+            throw err;
+        }
+    }
+    /**
+     * Clear all session history (for UI clear history button)
+     */
+    async clearHistory() {
+        if (!this.config.enabled) {
+            return;
+        }
+        // Load current data
+        const currentData = await this.loadData();
+        if (!currentData) {
+            return;
+        }
+        // Clear history but keep active sessions and connections
+        const clearedData = {
+            ...currentData,
+            sessionHistory: [],
+            metadata: {
+                ...currentData.metadata,
+                totalHistoryEntries: 0,
+                checksums: {
+                    ...currentData.metadata.checksums,
+                    history: this.calculateChecksum('[]')
+                }
+            }
+        };
+        await this.persistData(clearedData);
+    }
+    /**
+     * Get persistence status and statistics
+     */
+    getStatus() {
+        return {
+            enabled: this.config.enabled,
+            lastPersisted: this.lastPersistedData?.metadata.lastPersisted || null,
+            totalSessions: this.lastPersistedData?.metadata.totalSessions || 0,
+            totalConnections: this.lastPersistedData?.metadata.totalConnections || 0,
+            totalHistoryEntries: this.lastPersistedData?.metadata.totalHistoryEntries || 0,
+            config: this.config
+        };
+    }
+    /**
+     * Placeholder for current state persistence (to be implemented by callers)
+     */
+    async persistCurrentState() {
+        // No-op stub — callers (AdminPanel, WebSocketManager) may override.
+    }
+    /**
+     * Cleanup - stop timers and persist final state
+     */
+    async cleanup() {
+        this.isShuttingDown = true;
+        if (this.persistenceTimer) {
+            clearInterval(this.persistenceTimer);
+            this.persistenceTimer = null;
+        }
+        if (this.config.persistence.onShutdown) {
+            await this.persistCurrentState();
+        }
+    }
+}
+exports.SessionPersistenceManager = SessionPersistenceManager;

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

@@ -0,0 +1,64 @@
+/**
+ * ThinClient - Stdio-to-HTTP bridge for MCP clients.
+ *
+ * **EXPERIMENTAL** — APIs, configuration, and behavior may change.
+ *
+ * A lightweight process that MCP hosts (VS Code, Claude) spawn via stdio.
+ * Instead of loading the full index, it forwards JSON-RPC frames to
+ * the leader server's HTTP endpoint.
+ *
+ * Flow:  MCP Host --stdio--> ThinClient --HTTP--> Leader Server
+ *
+ * Features:
+ * - Reads JSON-RPC frames from stdin, POSTs to leader
+ * - Writes responses to stdout
+ * - Auto-discovers leader from instance state files
+ * - Reconnects on leader failover
+ */
+export interface ThinClientOptions {
+    /** URL of the leader's MCP transport (e.g., http://127.0.0.1:9090/mcp) */
+    leaderUrl?: string;
+    /** State directory to discover leader from port files */
+    stateDir?: string;
+    /** Retry settings */
+    maxRetries?: number;
+    retryDelayMs?: number;
+    /** Health check interval (ms) */
+    healthCheckMs?: number;
+}
+export declare class ThinClient {
+    private leaderUrl;
+    private readonly stateDir;
+    private readonly maxRetries;
+    private readonly retryDelayMs;
+    private _connected;
+    private _stopped;
+    private healthTimer;
+    constructor(options?: ThinClientOptions);
+    get connected(): boolean;
+    /**
+     * Discover the leader URL from the state directory.
+     */
+    discoverLeader(): string | null;
+    /**
+     * Resolve the leader URL (explicit or discovered).
+     * Re-discovers if the cached URL might be stale (leader changed port/host).
+     */
+    resolveLeaderUrl(): string | null;
+    /**
+     * Send a JSON-RPC request to the leader and return the response.
+     */
+    sendRpc(method: string, params?: unknown, id?: number | string): Promise<unknown>;
+    /**
+     * Check if the leader is healthy.
+     */
+    checkHealth(): Promise<boolean>;
+    /**
+     * Process a raw JSON-RPC frame (as received from stdin).
+     */
+    processFrame(frame: string): Promise<string>;
+    stop(): void;
+    private httpPost;
+    private httpGet;
+    private sleep;
+}