@jagilber-org/index-server 1.19.1

package/dist/dashboard/server/InstanceManager.js

@@ -0,0 +1,284 @@
+"use strict";
+/**
+ * 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)
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.writePortFile = writePortFile;
+exports.removePortFile = removePortFile;
+exports.cleanStalePortFiles = cleanStalePortFiles;
+exports.getActiveInstances = getActiveInstances;
+exports.validateInstances = validateInstances;
+exports._resetStateDir = _resetStateDir;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const http_1 = __importDefault(require("http"));
+const https_1 = __importDefault(require("https"));
+const runtimeConfig_1 = require("../../config/runtimeConfig");
+const PORT_FILE_PREFIX = 'dashboard-';
+const PORT_FILE_SUFFIX = '.json';
+let _stateDir;
+/** Track the port/host/protocol this process registered so self-healing can recreate the file. */
+let _registeredPort = 0;
+let _registeredHost = '';
+/** Resolve the state directory (cached after first call). */
+function getStateDir() {
+    if (!_stateDir) {
+        _stateDir = (0, runtimeConfig_1.getRuntimeConfig)().dashboard.admin.stateDir;
+    }
+    return _stateDir;
+}
+/** Build the port file path for a given PID. */
+function portFilePath(pid) {
+    return path_1.default.join(getStateDir(), `${PORT_FILE_PREFIX}${pid}${PORT_FILE_SUFFIX}`);
+}
+/** Ensure the state directory exists. */
+function ensureStateDir() {
+    const dir = getStateDir();
+    if (!fs_1.default.existsSync(dir)) {
+        fs_1.default.mkdirSync(dir, { recursive: true });
+    }
+}
+/**
+ * Write a port file for the current process.
+ * Called once when the dashboard HTTP server starts listening.
+ */
+function writePortFile(port, host) {
+    ensureStateDir();
+    const tlsEnabled = (0, runtimeConfig_1.getRuntimeConfig)().dashboard.http.tls.enabled;
+    const entry = {
+        pid: process.pid,
+        port,
+        host,
+        startedAt: new Date().toISOString(),
+        protocol: tlsEnabled ? 'https' : 'http',
+    };
+    const filePath = portFilePath(process.pid);
+    fs_1.default.writeFileSync(filePath, JSON.stringify(entry, null, 2), 'utf8');
+    _registeredPort = port;
+    _registeredHost = host;
+}
+/**
+ * Remove the port file for the current process.
+ * Called during graceful shutdown.
+ */
+function removePortFile() {
+    try {
+        const filePath = portFilePath(process.pid);
+        if (fs_1.default.existsSync(filePath)) {
+            fs_1.default.unlinkSync(filePath);
+        }
+    }
+    catch {
+        // Best-effort removal; ignore errors during shutdown.
+    }
+}
+/**
+ * Check whether a process with the given PID is still alive.
+ * Uses signal-0 which doesn't actually send a signal but checks existence.
+ */
+function isProcessAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Remove stale port files for processes that no longer exist.
+ * Called on startup to clean up after crashes.
+ */
+function cleanStalePortFiles() {
+    const dir = getStateDir();
+    if (!fs_1.default.existsSync(dir))
+        return;
+    let files;
+    try {
+        files = fs_1.default.readdirSync(dir);
+    }
+    catch {
+        return;
+    }
+    for (const file of files) {
+        if (!file.startsWith(PORT_FILE_PREFIX) || !file.endsWith(PORT_FILE_SUFFIX))
+            continue;
+        const pidStr = file.slice(PORT_FILE_PREFIX.length, -PORT_FILE_SUFFIX.length);
+        const pid = parseInt(pidStr, 10);
+        if (!Number.isFinite(pid) || pid <= 0)
+            continue;
+        if (!isProcessAlive(pid)) {
+            try {
+                fs_1.default.unlinkSync(path_1.default.join(dir, file));
+            }
+            catch {
+                // Ignore removal errors.
+            }
+        }
+    }
+}
+/**
+ * Get a list of all active dashboard instances by reading port files.
+ * Stale files (dead PIDs) are cleaned up automatically.
+ */
+function getActiveInstances() {
+    const dir = getStateDir();
+    if (!fs_1.default.existsSync(dir))
+        return [];
+    let files;
+    try {
+        files = fs_1.default.readdirSync(dir);
+    }
+    catch {
+        return [];
+    }
+    const instances = [];
+    for (const file of files) {
+        if (!file.startsWith(PORT_FILE_PREFIX) || !file.endsWith(PORT_FILE_SUFFIX))
+            continue;
+        const fullPath = path_1.default.join(dir, file);
+        try {
+            const raw = fs_1.default.readFileSync(fullPath, 'utf8');
+            const entry = JSON.parse(raw);
+            // Validate expected shape
+            if (typeof entry.pid !== 'number' || typeof entry.port !== 'number')
+                continue;
+            const alive = isProcessAlive(entry.pid);
+            if (!alive) {
+                // Clean up stale file
+                try {
+                    fs_1.default.unlinkSync(fullPath);
+                }
+                catch { /* ignore */ }
+                continue;
+            }
+            instances.push({
+                ...entry,
+                current: entry.pid === process.pid,
+                alive,
+            });
+        }
+        catch {
+            // Skip malformed files.
+        }
+    }
+    // Sort: current instance first, then by port ascending
+    instances.sort((a, b) => {
+        if (a.current && !b.current)
+            return -1;
+        if (!a.current && b.current)
+            return 1;
+        return a.port - b.port;
+    });
+    // Self-healing: if this process registered a port but has no port file, recreate it.
+    if (_registeredPort > 0 && !instances.some(i => i.current)) {
+        try {
+            writePortFile(_registeredPort, _registeredHost);
+            instances.unshift({
+                pid: process.pid,
+                port: _registeredPort,
+                host: _registeredHost,
+                startedAt: new Date().toISOString(),
+                current: true,
+                alive: true,
+            });
+        }
+        catch { /* ignore self-heal failures */ }
+    }
+    return instances;
+}
+/**
+ * Ping an instance to verify it is a live MCP dashboard server.
+ * Uses HTTPS when the port file indicates the instance runs with TLS.
+ * Returns true if the instance responds within the timeout, false otherwise.
+ */
+function pingInstance(host, port, protocol = 'http', timeoutMs = 3000) {
+    return new Promise((resolve) => {
+        const transport = protocol === 'https' ? https_1.default : http_1.default;
+        const opts = {
+            hostname: host || '127.0.0.1',
+            port,
+            path: '/api/instances',
+            timeout: timeoutMs,
+            ...(protocol === 'https' ? { rejectUnauthorized: false } : {}),
+        };
+        const req = transport.get(opts, (res) => {
+            // Any HTTP response means the server is alive (even 4xx/5xx)
+            res.resume(); // drain the response
+            resolve(true);
+        });
+        req.on('error', () => resolve(false));
+        req.on('timeout', () => { req.destroy(); resolve(false); });
+    });
+}
+/**
+ * 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).
+ */
+async function validateInstances() {
+    const dir = getStateDir();
+    if (!fs_1.default.existsSync(dir))
+        return;
+    let files;
+    try {
+        files = fs_1.default.readdirSync(dir);
+    }
+    catch {
+        return;
+    }
+    for (const file of files) {
+        if (!file.startsWith(PORT_FILE_PREFIX) || !file.endsWith(PORT_FILE_SUFFIX))
+            continue;
+        const fullPath = path_1.default.join(dir, file);
+        try {
+            const raw = fs_1.default.readFileSync(fullPath, 'utf8');
+            const entry = JSON.parse(raw);
+            if (typeof entry.pid !== 'number' || typeof entry.port !== 'number')
+                continue;
+            // Skip current process -- we know we're alive
+            if (entry.pid === process.pid)
+                continue;
+            // First: fast PID check. If process is dead, clean up immediately.
+            if (!isProcessAlive(entry.pid)) {
+                try {
+                    fs_1.default.unlinkSync(fullPath);
+                }
+                catch { /* ignore */ }
+                continue;
+            }
+            // PID is alive, but verify it's actually serving HTTP on the expected port.
+            // This catches orphaned processes (alive but not functional) and recycled PIDs.
+            const proto = entry.protocol || 'http';
+            const responds = await pingInstance(entry.host, entry.port, proto);
+            if (!responds) {
+                try {
+                    process.stderr.write(`[instance-validate] removing stale port file: pid=${entry.pid} port=${entry.port} (HTTP unreachable)\n`);
+                    fs_1.default.unlinkSync(fullPath);
+                }
+                catch { /* ignore */ }
+            }
+        }
+        catch {
+            // Skip malformed files.
+        }
+    }
+}
+/** Reset the cached state dir (useful for testing). */
+function _resetStateDir() {
+    _stateDir = undefined;
+}

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

@@ -0,0 +1,35 @@
+/**
+ * KnowledgeStore - In-memory + file-backed key-value store
+ * for cross-repo agent performance insights.
+ *
+ * Persists to {dataDir}/knowledge-store.json.
+ * Requested by mcp-agent-manager (feedback d664a9239632f287).
+ */
+export interface KnowledgeEntry {
+    key: string;
+    content: string;
+    metadata: Record<string, unknown>;
+    createdAt: string;
+    updatedAt: string;
+}
+declare class KnowledgeStore {
+    private entries;
+    private filePath;
+    constructor(dataDir?: string);
+    private loadFromDisk;
+    private saveToDisk;
+    upsert(key: string, content: string, metadata?: Record<string, unknown>): KnowledgeEntry;
+    get(key: string): KnowledgeEntry | undefined;
+    search(query: string, options?: {
+        category?: string;
+        limit?: number;
+    }): KnowledgeEntry[];
+    delete(key: string): boolean;
+    count(): number;
+}
+export declare function getKnowledgeStore(): KnowledgeStore;
+/** Reset singleton — for tests only */
+export declare function resetKnowledgeStore(): void;
+/** Create a standalone store with custom data dir — for tests */
+export declare function createKnowledgeStore(dataDir: string): KnowledgeStore;
+export {};

package/dist/dashboard/server/KnowledgeStore.js

@@ -0,0 +1,105 @@
+"use strict";
+/**
+ * KnowledgeStore - In-memory + file-backed key-value store
+ * for cross-repo agent performance insights.
+ *
+ * Persists to {dataDir}/knowledge-store.json.
+ * Requested by mcp-agent-manager (feedback d664a9239632f287).
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getKnowledgeStore = getKnowledgeStore;
+exports.resetKnowledgeStore = resetKnowledgeStore;
+exports.createKnowledgeStore = createKnowledgeStore;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const runtimeConfig_1 = require("../../config/runtimeConfig");
+class KnowledgeStore {
+    entries = new Map();
+    filePath;
+    constructor(dataDir) {
+        const dir = dataDir || (0, runtimeConfig_1.getRuntimeConfig)().index?.baseDir || path_1.default.join(process.cwd(), 'data');
+        this.filePath = path_1.default.join(dir, 'knowledge-store.json');
+        this.loadFromDisk();
+    }
+    loadFromDisk() {
+        try {
+            if (fs_1.default.existsSync(this.filePath)) {
+                const raw = JSON.parse(fs_1.default.readFileSync(this.filePath, 'utf-8'));
+                if (Array.isArray(raw)) {
+                    for (const entry of raw) {
+                        if (entry.key)
+                            this.entries.set(entry.key, entry);
+                    }
+                }
+            }
+        }
+        catch { /* ignore corrupt/missing file */ }
+    }
+    saveToDisk() {
+        try {
+            const dir = path_1.default.dirname(this.filePath);
+            if (!fs_1.default.existsSync(dir))
+                fs_1.default.mkdirSync(dir, { recursive: true });
+            fs_1.default.writeFileSync(this.filePath, JSON.stringify(Array.from(this.entries.values()), null, 2));
+        }
+        catch { /* ignore write errors */ }
+    }
+    upsert(key, content, metadata = {}) {
+        const now = new Date().toISOString();
+        const existing = this.entries.get(key);
+        const entry = {
+            key,
+            content,
+            metadata: { ...metadata },
+            createdAt: existing?.createdAt || now,
+            updatedAt: now,
+        };
+        this.entries.set(key, entry);
+        this.saveToDisk();
+        return entry;
+    }
+    get(key) {
+        return this.entries.get(key);
+    }
+    search(query, options) {
+        const q = query.toLowerCase();
+        const limit = options?.limit || 20;
+        const results = [];
+        for (const entry of this.entries.values()) {
+            if (results.length >= limit)
+                break;
+            if (options?.category && entry.metadata?.category !== options.category)
+                continue;
+            const searchable = [entry.key, entry.content, ...Object.values(entry.metadata).map(v => String(v))].join(' ').toLowerCase();
+            if (searchable.includes(q))
+                results.push(entry);
+        }
+        return results;
+    }
+    delete(key) {
+        const existed = this.entries.delete(key);
+        if (existed)
+            this.saveToDisk();
+        return existed;
+    }
+    count() {
+        return this.entries.size;
+    }
+}
+let instance = null;
+function getKnowledgeStore() {
+    if (!instance)
+        instance = new KnowledgeStore();
+    return instance;
+}
+/** Reset singleton — for tests only */
+function resetKnowledgeStore() {
+    instance = null;
+}
+/** Create a standalone store with custom data dir — for tests */
+function createKnowledgeStore(dataDir) {
+    return new KnowledgeStore(dataDir);
+}

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

@@ -0,0 +1,81 @@
+/**
+ * LeaderElection - Manages leader/follower roles for multi-instance MCP servers.
+ *
+ * **EXPERIMENTAL** — APIs, configuration, and behavior may change.
+ *
+ * Uses a lock file + PID-based election strategy:
+ * - Leader is the instance that successfully acquires the lock file
+ * - On leader death, the surviving instance with the lowest PID promotes
+ * - Heartbeat mechanism keeps leader.lock fresh (stale = dead leader)
+ *
+ * Lock file location: `<stateDir>/leader.lock`
+ */
+import { EventEmitter } from 'events';
+export type InstanceRole = 'leader' | 'follower' | 'standalone' | 'candidate';
+export interface LeaderLockEntry {
+    pid: number;
+    port: number;
+    host: string;
+    startedAt: string;
+    heartbeat: string;
+}
+export interface LeaderElectionOptions {
+    stateDir: string;
+    port: number;
+    host: string;
+    heartbeatIntervalMs?: number;
+    staleThresholdMs?: number;
+}
+export declare class LeaderElection extends EventEmitter {
+    private readonly stateDir;
+    private readonly port;
+    private readonly host;
+    private readonly heartbeatIntervalMs;
+    private readonly staleThresholdMs;
+    private _role;
+    private heartbeatTimer;
+    private watchTimer;
+    private _leaderInfo;
+    private _stopped;
+    constructor(options: LeaderElectionOptions);
+    get role(): InstanceRole;
+    get leaderInfo(): LeaderLockEntry | null;
+    get lockFilePath(): string;
+    /**
+     * Attempt to become leader via atomic lock file creation.
+     * Returns true if this instance is now the leader.
+     */
+    tryAcquireLock(): boolean;
+    /**
+     * Check existing lock file. If holder is dead or stale, try to take over.
+     */
+    private handleExistingLock;
+    /**
+     * Start the election process and heartbeat/watch timers.
+     */
+    start(): InstanceRole;
+    /**
+     * Stop all timers and release the lock if leader.
+     */
+    stop(): void;
+    /**
+     * Update the heartbeat timestamp in the lock file (leader only).
+     * Uses atomic write-to-temp-then-rename to prevent corruption if
+     * the process dies mid-write.
+     */
+    updateHeartbeat(): void;
+    /**
+     * Remove the lock file (leader relinquishing).
+     */
+    releaseLock(): void;
+    /**
+     * Check if the current leader is still alive.
+     */
+    isLeaderAlive(): boolean;
+    private startHeartbeat;
+    private startWatcher;
+    private isLeaderStale;
+    private buildLockEntry;
+    private ensureStateDir;
+    isProcessAlive(pid: number): boolean;
+}