@jagilber-org/index-server 1.19.1

package/dist/dashboard/server/routes/status.routes.js

@@ -0,0 +1,183 @@
+"use strict";
+/**
+ * Status & Health Routes
+ * Routes: GET /status, GET /health, GET /system/health, GET /system/resources
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createStatusRoutes = createStatusRoutes;
+const express_1 = require("express");
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const v8_1 = __importDefault(require("v8"));
+const runtimeConfig_js_1 = require("../../../config/runtimeConfig.js");
+/** Derive short git commit (best-effort; never throws) */
+function getGitCommit() {
+    try {
+        const head = path_1.default.join(process.cwd(), '.git', 'HEAD');
+        if (!fs_1.default.existsSync(head))
+            return null;
+        let ref = fs_1.default.readFileSync(head, 'utf8').trim();
+        if (ref.startsWith('ref:')) {
+            const refPath = path_1.default.join(process.cwd(), '.git', ref.split(' ')[1]);
+            if (fs_1.default.existsSync(refPath)) {
+                ref = fs_1.default.readFileSync(refPath, 'utf8').trim();
+            }
+        }
+        return ref.substring(0, 12);
+    }
+    catch {
+        return null;
+    }
+}
+/** Approximate build time via dist/server/index-server.js mtime (falls back to null) */
+function getBuildTime() {
+    try {
+        const candidate = path_1.default.join(process.cwd(), 'dist', 'server', 'index-server.js');
+        if (fs_1.default.existsSync(candidate)) {
+            const stat = fs_1.default.statSync(candidate);
+            return new Date(stat.mtimeMs).toISOString();
+        }
+    }
+    catch { /* ignore */ }
+    return null;
+}
+function createStatusRoutes(metricsCollector) {
+    const router = (0, express_1.Router)();
+    /**
+     * GET /api/status - Server status and basic info
+     */
+    router.get('/status', (_req, res) => {
+        try {
+            const snapshot = metricsCollector.getCurrentSnapshot();
+            const git = getGitCommit();
+            const buildTime = getBuildTime();
+            // Prevent stale caching of build/version metadata in browsers / proxies
+            res.setHeader('Cache-Control', 'no-store, no-cache, must-revalidate, proxy-revalidate');
+            res.setHeader('Pragma', 'no-cache');
+            res.setHeader('Expires', '0');
+            res.json({
+                status: 'online',
+                version: snapshot.server.version,
+                build: git || undefined,
+                buildTime: buildTime || undefined,
+                uptime: snapshot.server.uptime,
+                startTime: snapshot.server.startTime,
+                timestamp: Date.now(),
+            });
+        }
+        catch (error) {
+            console.error('[API] Status error:', error);
+            res.status(500).json({
+                error: 'Failed to get server status',
+                message: error instanceof Error ? error.message : 'Unknown error',
+            });
+        }
+    });
+    /**
+     * GET /api/health - Health check endpoint
+     */
+    router.get('/health', (_req, res) => {
+        try {
+            const snapshot = metricsCollector.getCurrentSnapshot();
+            const memUsage = snapshot.server.memoryUsage;
+            // Thresholds (configurable via runtime configuration)
+            const healthConfig = (0, runtimeConfig_js_1.getRuntimeConfig)().metrics.health;
+            const memoryThreshold = healthConfig.memoryThreshold;
+            const errorRateThreshold = healthConfig.errorRateThreshold;
+            const minUptimeMs = healthConfig.minUptimeMs;
+            // Simple health indicators (boolean flags)
+            // Use V8 heap_size_limit (not heapTotal) for memory ratio -- V8 keeps
+            // heapTotal only slightly above heapUsed, so heapUsed/heapTotal is
+            // almost always >85% and would false-alarm on default thresholds.
+            const heapLimit = v8_1.default.getHeapStatistics().heap_size_limit || memUsage.heapTotal;
+            const isHealthy = {
+                uptime: snapshot.server.uptime >= minUptimeMs,
+                memory: (memUsage.heapUsed / Math.max(1, heapLimit)) < memoryThreshold,
+                errors: snapshot.performance.errorRate < errorRateThreshold,
+            };
+            const failingChecks = Object.entries(isHealthy)
+                .filter(([, ok]) => !ok)
+                .map(([k]) => k);
+            const overallHealth = failingChecks.length === 0;
+            res.status(overallHealth ? 200 : 503).json({
+                status: overallHealth ? 'healthy' : 'degraded',
+                checks: isHealthy,
+                failingChecks,
+                thresholds: {
+                    memoryRatio: memoryThreshold,
+                    errorRatePercent: errorRateThreshold,
+                    minUptimeMs
+                },
+                metrics: {
+                    uptimeMs: snapshot.server.uptime,
+                    memory: {
+                        heapUsed: memUsage.heapUsed,
+                        heapTotal: memUsage.heapTotal,
+                        heapLimit: v8_1.default.getHeapStatistics().heap_size_limit,
+                        ratio: memUsage.heapTotal ? memUsage.heapUsed / (v8_1.default.getHeapStatistics().heap_size_limit || memUsage.heapTotal) : 0
+                    },
+                    errorRate: snapshot.performance.errorRate
+                },
+                timestamp: Date.now(),
+            });
+        }
+        catch (error) {
+            console.error('[API] Health check error:', error);
+            res.status(500).json({
+                status: 'error',
+                error: 'Health check failed',
+                message: error instanceof Error ? error.message : 'Unknown error',
+                timestamp: Date.now(),
+            });
+        }
+    });
+    /**
+     * GET /api/system/health - Advanced system health metrics
+     */
+    router.get('/system/health', (_req, res) => {
+        try {
+            const systemHealth = metricsCollector.getSystemHealth();
+            res.json({
+                success: true,
+                data: systemHealth,
+                timestamp: Date.now()
+            });
+        }
+        catch (error) {
+            console.error('[API] System health error:', error);
+            res.status(500).json({
+                error: 'Failed to get system health',
+                message: error instanceof Error ? error.message : 'Unknown error',
+            });
+        }
+    });
+    /**
+     * GET /api/system/resources - CPU & memory sample history (for long-term monitoring UI)
+     * query params: limit (number of most recent samples)
+     */
+    router.get('/system/resources', (req, res) => {
+        try {
+            const limit = req.query.limit ? parseInt(req.query.limit, 10) : 200;
+            const history = metricsCollector.getResourceHistory(limit);
+            res.json({
+                success: true,
+                data: history,
+                limit,
+                sampleCount: history.samples.length,
+                timestamp: Date.now()
+            });
+        }
+        catch (error) {
+            console.error('[API] System resources error:', error);
+            res.status(500).json({
+                success: false,
+                error: 'Failed to get system resource history',
+                message: error instanceof Error ? error.message : 'Unknown error',
+            });
+        }
+    });
+    return router;
+}

package/dist/dashboard/server/routes/synthetic.routes.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Synthetic Activity Routes
+ * Routes: POST /admin/synthetic/activity, GET /admin/synthetic/status
+ */
+import { Router } from 'express';
+import { MetricsCollector } from '../MetricsCollector.js';
+export declare function createSyntheticRoutes(_metricsCollector: MetricsCollector): Router;

package/dist/dashboard/server/routes/synthetic.routes.js

@@ -0,0 +1,195 @@
+"use strict";
+/**
+ * Synthetic Activity Routes
+ * Routes: POST /admin/synthetic/activity, GET /admin/synthetic/status
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createSyntheticRoutes = createSyntheticRoutes;
+const express_1 = require("express");
+const registry_js_1 = require("../../../server/registry.js");
+const WebSocketManager_js_1 = require("../WebSocketManager.js");
+function createSyntheticRoutes(_metricsCollector) {
+    const router = (0, express_1.Router)();
+    // Module-private state
+    let syntheticActiveRequests = 0;
+    let lastSyntheticSummary = null;
+    let lastSyntheticRunId = null;
+    /**
+     * POST /api/admin/synthetic/activity - Generate synthetic tool activity to exercise metrics
+     * body: { iterations?: number, concurrency?: number }
+     */
+    router.post('/admin/synthetic/activity', async (req, res) => {
+        try {
+            const iterations = Math.min(Math.max(parseInt(req.body.iterations || '10', 10), 1), 500);
+            const concurrency = Math.min(Math.max(parseInt(req.body.concurrency || '2', 10), 1), 25);
+            const start = Date.now();
+            const runId = `${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 8)}`;
+            const wantTrace = req.query.trace === '1' || req.body?.trace === true || req.query.debug === '1' || req.body?.debug === true;
+            const wantStream = wantTrace && (req.query.stream === '1' || req.body?.stream === true);
+            // Whitelist of safe, read-only or idempotent methods + minimal params
+            const PARAM_MAP = {
+                'health_check': {},
+                'metrics_snapshot': {},
+                'meta_tools': {},
+                'gates_evaluate': {},
+                'index_dispatch:add': { action: 'add', entry: { id: `synthetic-${runId}`, title: 'Synthetic Instruction', body: 'Temporary synthetic entry', audience: 'all', requirement: 'optional', priority: 'low', categories: ['synthetic'], owner: 'synthetic' }, overwrite: true, lax: true },
+                'index_dispatch:get': { action: 'get', id: `synthetic-${runId}` },
+                'index_dispatch:list': { action: 'list' },
+                'index_dispatch:query': { action: 'query', keyword: 'Synthetic', categoriesAll: [], requirement: undefined },
+                'index_dispatch:update': { action: 'add', entry: { id: `synthetic-${runId}`, title: 'Synthetic Instruction Updated', body: 'Updated body', audience: 'all', requirement: 'optional', priority: 'medium', categories: ['synthetic', 'updated'], owner: 'synthetic' }, overwrite: true, lax: true },
+                'index_dispatch:remove': { action: 'remove', id: `synthetic-${runId}` },
+                'usage_track': { id: 'synthetic.activity' }
+            };
+            const allRegistered = (0, registry_js_1.listRegisteredMethods)();
+            const expandedParamEntries = Object.entries(PARAM_MAP).map(([k, v]) => {
+                if (k.startsWith('index_dispatch:'))
+                    return ['index_dispatch', v];
+                return [k, v];
+            });
+            const available = allRegistered.filter(m => expandedParamEntries.some(([name]) => name === m));
+            if (!available.length) {
+                return res.status(503).json({
+                    success: false,
+                    error: 'No safe tools available for synthetic activity',
+                    registeredCount: allRegistered.length,
+                    registeredSample: allRegistered.slice(0, 15),
+                    expectedAnyOf: Object.keys(PARAM_MAP),
+                    hint: 'If this persists, ensure handlers.* imports occur before dashboard start (see server/index.ts import order).',
+                    timestamp: Date.now()
+                });
+            }
+            let executed = 0;
+            let errors = 0;
+            let missingHandlerCount = 0;
+            const traces = [];
+            let seq = 0;
+            const wsManager = wantStream ? (0, WebSocketManager_js_1.getWebSocketManager)() : null;
+            const runOne = async () => {
+                const picked = expandedParamEntries[Math.floor(Math.random() * expandedParamEntries.length)];
+                const method = picked[0];
+                if (!available.includes(method))
+                    return;
+                const payload = picked[1];
+                const handler = (0, registry_js_1.getLocalHandler)(method);
+                const started = Date.now();
+                try {
+                    syntheticActiveRequests++;
+                    if (handler) {
+                        await Promise.resolve(handler(payload));
+                        const ended = Date.now();
+                        if (wantTrace && traces.length < iterations)
+                            traces.push({ method, success: true, durationMs: ended - started, started, ended });
+                        if (wantStream && wsManager) {
+                            try {
+                                wsManager.broadcast({ type: 'synthetic_trace', timestamp: Date.now(), data: { runId, seq: ++seq, total: iterations, method, success: true, durationMs: ended - started, started, ended } });
+                            }
+                            catch { /* ignore */ }
+                        }
+                    }
+                    else {
+                        missingHandlerCount++;
+                        const ended = Date.now();
+                        if (wantTrace && traces.length < iterations)
+                            traces.push({ method, success: false, durationMs: ended - started, started, ended, error: 'handler_not_registered', skipped: true });
+                        if (wantStream && wsManager) {
+                            try {
+                                wsManager.broadcast({ type: 'synthetic_trace', timestamp: Date.now(), data: { runId, seq: ++seq, total: iterations, method, success: false, durationMs: ended - started, started, ended, error: 'handler_not_registered', skipped: true } });
+                            }
+                            catch { /* ignore */ }
+                        }
+                    }
+                }
+                catch (err) {
+                    errors++;
+                    const ended = Date.now();
+                    if (wantTrace && traces.length < iterations)
+                        traces.push({ method, success: false, durationMs: ended - started, started, ended, error: err instanceof Error ? err.message : String(err) });
+                    if (wantStream && wsManager) {
+                        try {
+                            wsManager.broadcast({ type: 'synthetic_trace', timestamp: Date.now(), data: { runId, seq: ++seq, total: iterations, method, success: false, durationMs: ended - started, started, ended, error: err instanceof Error ? err.message : String(err) } });
+                        }
+                        catch { /* ignore */ }
+                    }
+                }
+                executed++;
+                syntheticActiveRequests--;
+            };
+            // Concurrency control
+            const inFlight = [];
+            for (let i = 0; i < iterations; i++) {
+                if (inFlight.length >= concurrency) {
+                    await Promise.race(inFlight);
+                }
+                const p = runOne().finally(() => {
+                    const idx = inFlight.indexOf(p);
+                    if (idx >= 0)
+                        inFlight.splice(idx, 1);
+                });
+                inFlight.push(p);
+            }
+            await Promise.all(inFlight);
+            const durationMs = Date.now() - start;
+            const debug = req.query.debug === '1' || req.body?.debug === true;
+            const traceReason = wantTrace && traces.length === 0
+                ? (available.length === 0
+                    ? 'no_safe_tools_registered'
+                    : missingHandlerCount === iterations
+                        ? 'all_selected_handlers_missing'
+                        : 'no_traces_captured')
+                : undefined;
+            lastSyntheticRunId = runId;
+            lastSyntheticSummary = {
+                runId,
+                executed,
+                errors,
+                durationMs,
+                iterationsRequested: iterations,
+                concurrency,
+                availableCount: available.length,
+                missingHandlerCount,
+                traceReason,
+                timestamp: Date.now()
+            };
+            syntheticActiveRequests = 0; // safety reset
+            res.json({
+                success: true,
+                message: 'Synthetic activity completed',
+                runId,
+                executed,
+                errors,
+                durationMs,
+                iterationsRequested: iterations,
+                concurrency,
+                availableCount: available.length,
+                missingHandlerCount,
+                ...(traceReason ? { traceReason } : {}),
+                ...(debug ? { available } : {}),
+                ...(wantTrace ? { traces } : {}),
+                timestamp: Date.now()
+            });
+        }
+        catch (error) {
+            console.error('[API] Synthetic activity error:', error);
+            res.status(500).json({
+                success: false,
+                error: 'Failed to run synthetic activity',
+                message: error instanceof Error ? error.message : 'Unknown error'
+            });
+        }
+    });
+    /**
+     * GET /api/admin/synthetic/status - real-time synthetic run status (active in-flight requests)
+     */
+    router.get('/admin/synthetic/status', (_req, res) => {
+        res.json({
+            success: true,
+            activeRequests: syntheticActiveRequests,
+            lastRunId: lastSyntheticRunId,
+            lastSummary: lastSyntheticSummary,
+            timestamp: Date.now()
+        });
+    });
+    /** Expose activeSyntheticRequests for other modules (e.g. metrics.routes /performance/detailed) */
+    router.getSyntheticActiveRequests = () => syntheticActiveRequests;
+    return router;
+}

package/dist/dashboard/server/routes/tools.routes.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Tools Routes — REST bridge for MCP tool handlers
+ * Routes: POST /tools/:name, GET /tools
+ */
+import { Router } from 'express';
+export declare function createToolsRoutes(): Router;

package/dist/dashboard/server/routes/tools.routes.js

@@ -0,0 +1,46 @@
+"use strict";
+/**
+ * Tools Routes — REST bridge for MCP tool handlers
+ * Routes: POST /tools/:name, GET /tools
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createToolsRoutes = createToolsRoutes;
+const express_1 = require("express");
+const registry_js_1 = require("../../../server/registry.js");
+function createToolsRoutes() {
+    const router = (0, express_1.Router)();
+    /**
+     * GET /api/tools — List all registered tool names
+     */
+    router.get('/tools', (_req, res) => {
+        res.json({ tools: (0, registry_js_1.listRegisteredMethods)() });
+    });
+    /**
+     * POST /api/tools/:name — Invoke a registered MCP tool handler by name
+     * Body: JSON params passed directly to the handler
+     * Returns: handler result or error
+     */
+    router.post('/tools/:name', async (req, res) => {
+        const toolName = req.params.name;
+        if (!toolName || !/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(toolName)) {
+            res.status(400).json({ error: 'Invalid tool name' });
+            return;
+        }
+        const handler = (0, registry_js_1.getLocalHandler)(toolName);
+        if (!handler) {
+            res.status(404).json({ error: `Tool not found: ${toolName}`, available: (0, registry_js_1.listRegisteredMethods)() });
+            return;
+        }
+        try {
+            const result = await handler(req.body);
+            res.json(result);
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message
+                : (typeof err === 'object' && err !== null) ? JSON.stringify(err)
+                    : String(err);
+            res.status(500).json({ error: message });
+        }
+    });
+    return router;
+}

package/dist/dashboard/server/routes/usage.routes.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Usage Signal Routes
+ * Routes: GET /usage/snapshot - returns per-instruction usage signals
+ */
+import { Router } from 'express';
+export declare function createUsageRoutes(): Router;

package/dist/dashboard/server/routes/usage.routes.js

@@ -0,0 +1,25 @@
+"use strict";
+/**
+ * Usage Signal Routes
+ * Routes: GET /usage/snapshot - returns per-instruction usage signals
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createUsageRoutes = createUsageRoutes;
+const express_1 = require("express");
+const indexContext_js_1 = require("../../../services/indexContext.js");
+function createUsageRoutes() {
+    const router = (0, express_1.Router)();
+    /**
+     * GET /api/usage/snapshot - Get the usage snapshot (per-instruction signals)
+     */
+    router.get('/usage/snapshot', (_req, res) => {
+        try {
+            const snap = (0, indexContext_js_1.loadUsageSnapshot)();
+            res.json({ success: true, snapshot: snap, count: Object.keys(snap).length, timestamp: Date.now() });
+        }
+        catch (error) {
+            res.status(500).json({ success: false, error: 'Failed to load usage snapshot', message: error instanceof Error ? error.message : 'Unknown error' });
+        }
+    });
+    return router;
+}

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

@@ -0,0 +1,16 @@
+/**
+ * wsInit — WebSocket server initialization and metrics broadcast wiring.
+ * Extracted from DashboardServer.ts to keep the coordinator within line limits.
+ */
+import { Server as HttpServer } from 'http';
+import { WebSocketManager } from './WebSocketManager.js';
+import { MetricsCollector } from './MetricsCollector.js';
+/** Attaches the WebSocket server to an existing HTTP/HTTPS server instance. */
+export declare function initWebSocket(server: HttpServer, wsManager: WebSocketManager): void;
+/**
+ * Starts a recurring timer that broadcasts the full metrics snapshot to all
+ * connected WebSocket clients. Returns the timer handle so the caller can clear it.
+ *
+ * A lower-bound of 250 ms is enforced regardless of the configured interval.
+ */
+export declare function startMetricsBroadcast(wsManager: WebSocketManager, metricsCollector: MetricsCollector, intervalMs: number): NodeJS.Timeout;

package/dist/dashboard/server/wsInit.js

@@ -0,0 +1,35 @@
+"use strict";
+/**
+ * wsInit — WebSocket server initialization and metrics broadcast wiring.
+ * Extracted from DashboardServer.ts to keep the coordinator within line limits.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.initWebSocket = initWebSocket;
+exports.startMetricsBroadcast = startMetricsBroadcast;
+/** Attaches the WebSocket server to an existing HTTP/HTTPS server instance. */
+function initWebSocket(server, wsManager) {
+    wsManager.initialize(server);
+}
+/**
+ * Starts a recurring timer that broadcasts the full metrics snapshot to all
+ * connected WebSocket clients. Returns the timer handle so the caller can clear it.
+ *
+ * A lower-bound of 250 ms is enforced regardless of the configured interval.
+ */
+function startMetricsBroadcast(wsManager, metricsCollector, intervalMs) {
+    const safeInterval = Math.max(250, intervalMs);
+    return setInterval(() => {
+        try {
+            const snapshot = metricsCollector.getCurrentSnapshot();
+            wsManager.broadcast({
+                type: 'metrics_update',
+                timestamp: Date.now(),
+                data: snapshot,
+            });
+        }
+        catch (e) {
+            // eslint-disable-next-line no-console
+            console.error('[Dashboard] metrics broadcast failed', e);
+        }
+    }, safeInterval);
+}

package/dist/externalClientLib.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/externalClientLib.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/minimal/index.d.ts

@@ -0,0 +1 @@
+export {};