@jagilber-org/index-server 1.19.1

package/dist/minimal/index.js

@@ -0,0 +1,140 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+// Minimal standalone MCP server (handshake + health + ping) with strict ordering
+// Inspired by simplified PowerShell reference: respond to initialize, then emit server/ready, then tools/list_changed.
+// No SDK, no fallbacks, no extra watchdogs. Deterministic ordering and tiny surface.
+const readline_1 = require("readline");
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const runtimeConfig_1 = require("../config/runtimeConfig");
+// High resolution timestamp helper for ordering diagnostics
+function ts() {
+    try {
+        return Number(process.hrtime.bigint() % BigInt(1e12)).toString().padStart(12, '0');
+    }
+    catch {
+        return Date.now().toString();
+    }
+}
+const VERSION = (() => { try {
+    const p = path_1.default.join(process.cwd(), 'package.json');
+    return JSON.parse(fs_1.default.readFileSync(p, 'utf8')).version || '0.0.0';
+}
+catch {
+    return '0.0.0';
+} })();
+const rl = (0, readline_1.createInterface)({ input: process.stdin });
+const DEBUG_ORDER = (0, runtimeConfig_1.getRuntimeConfig)().minimal.debugOrdering;
+function write(obj) { try {
+    process.stdout.write(JSON.stringify(obj) + '\n');
+}
+catch { /* ignore */ } }
+function debug(msg) { if (DEBUG_ORDER) {
+    try {
+        process.stderr.write('[minimal-debug] ' + msg + '\n');
+    }
+    catch { /* ignore */ }
+} }
+function sendInitResult(id, protocolVersion) {
+    const payload = { jsonrpc: '2.0', id: id ?? 1, result: { protocolVersion, serverInfo: { name: 'mcp-minimal-server', version: VERSION }, capabilities: { tools: { listChanged: true } }, instructions: 'minimal mode' } };
+    const line = JSON.stringify(payload) + '\n';
+    try {
+        debug(`init-write-start hr=${ts()}`);
+        // Synchronous write to eliminate any chance the initialize line isn't flushed before ready scheduling.
+        // fs.writeSync bypasses stream buffering semantics of process.stdout.write callback timing.
+        fs_1.default.writeSync(1, line);
+        // Extra hard flush (rarely needed, but guards against odd buffering on some platforms / CI setups)
+        try {
+            fs_1.default.fsyncSync(1);
+        }
+        catch { /* ignore */ }
+        // Emit a deterministic sentinel (debuggable) to stdout directly after initialize result for test harness correlation.
+        // If tests ever report missing initialize but this sentinel appears, the loss happened in parsing logic not emission.
+        fs_1.default.writeSync(1, JSON.stringify({ jsonrpc: '2.0', method: 'minimal/handshake_sentinel', params: { hr: ts() } }) + '\n');
+        debug(`init-write-done hr=${ts()} bytes=${line.length}`);
+    }
+    catch (e) {
+        debug('init-write-error ' + e.message);
+    }
+    // Originally this used setImmediate; move to nextTick for tighter ordering while still deferring until after synchronous writes.
+    // Empirically reduces rare duplicate ready observations caused by unexpected re-entrancy in exotic environments.
+    process.nextTick(() => scheduleReady('post-init-nextTick'));
+}
+function scheduleReady(reason) {
+    if (recentReadyEmitted) {
+        debug(`ready-skip-duplicate hr=${ts()} reason=${reason}`);
+        return;
+    }
+    // Single scheduling point; we assume initialize already flushed.
+    recentReadyEmitted = true;
+    debug(`ready-start hr=${ts()} reason=${reason}`);
+    write({ jsonrpc: '2.0', method: 'server/ready', params: { version: VERSION, reason, hr: ts() } });
+    write({ jsonrpc: '2.0', method: 'notifications/tools/list_changed', params: { hr: ts() } });
+    debug(`ready-done hr=${ts()}`);
+}
+let recentReadyEmitted = false;
+rl.on('line', line => {
+    const raw = line.trim();
+    if (!raw)
+        return;
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return;
+    }
+    if (!isRequest(parsed))
+        return;
+    const m = parsed;
+    switch (m.method) {
+        case 'initialize': {
+            const proto = m.params?.protocolVersion || '2025-06-18';
+            sendInitResult(m.id, proto);
+            return;
+        }
+        case 'ping': {
+            write({ jsonrpc: '2.0', id: m.id ?? null, result: { timestamp: new Date().toISOString() } });
+            return;
+        }
+        case 'tools/list': {
+            write({ jsonrpc: '2.0', id: m.id ?? null, result: { tools: [] } });
+            return;
+        }
+        case 'tools/call': {
+            const name = typeof m.params?.name === 'string' ? m.params.name : undefined;
+            if (name === 'health_check') {
+                write({ jsonrpc: '2.0', id: m.id ?? null, result: { content: [{ type: 'text', text: JSON.stringify({ status: 'ok', version: VERSION }) }] } });
+            }
+            else {
+                write({ jsonrpc: '2.0', id: m.id ?? null, error: { code: -32601, message: 'Unknown tool', data: { method: name } } });
+            }
+            return;
+        }
+        case 'shutdown': {
+            write({ jsonrpc: '2.0', id: m.id ?? null, result: { shuttingDown: true } });
+            return;
+        }
+        case 'exit': {
+            write({ jsonrpc: '2.0', id: m.id ?? null, result: { exiting: true } });
+            setTimeout(() => process.exit(0), 0);
+            return;
+        }
+        default: {
+            if (Object.prototype.hasOwnProperty.call(m, 'id')) {
+                write({ jsonrpc: '2.0', id: m.id ?? null, error: { code: -32601, message: 'Method not found', data: { method: m.method } } });
+            }
+        }
+    }
+});
+function isRequest(v) {
+    if (!v || typeof v !== 'object')
+        return false;
+    const obj = v;
+    return obj.jsonrpc === '2.0' && typeof obj.method === 'string';
+}
+// Keep alive in case no stdin activity yet
+process.stdin.resume();

package/dist/models/SessionPersistence.d.ts

@@ -0,0 +1,115 @@
+/**
+ * Session Persistence Schema Design
+ *
+ * Persistent storage design for admin sessions, websocket connections, and session history
+ * with deduplication, atomic writes, and backup integration.
+ */
+export interface PersistedAdminSession {
+    id: string;
+    userId: string;
+    startTime: string;
+    lastActivity: string;
+    ipAddress: string;
+    userAgent: string;
+    permissions: string[];
+    persistedAt: string;
+    version: number;
+}
+export interface PersistedWebSocketConnection {
+    id: string;
+    clientId: string;
+    connectedAt: string;
+    lastActivity: string;
+    ipAddress?: string;
+    userAgent?: string;
+    isActive: boolean;
+    disconnectedAt?: string;
+    disconnectReason?: string;
+    persistedAt: string;
+    version: number;
+}
+export interface PersistedSessionHistoryEntry {
+    id: string;
+    userId: string;
+    startTime: string;
+    endTime?: string;
+    ipAddress: string;
+    userAgent: string;
+    terminated?: boolean;
+    terminationReason?: string;
+    persistedAt: string;
+    version: number;
+}
+export interface SessionPersistenceMetadata {
+    lastPersisted: string;
+    version: number;
+    totalSessions: number;
+    totalConnections: number;
+    totalHistoryEntries: number;
+    checksums: {
+        sessions: string;
+        connections: string;
+        history: string;
+    };
+}
+export interface SessionPersistenceManifest {
+    metadata: SessionPersistenceMetadata;
+    files: {
+        adminSessions: string;
+        webSocketConnections: string;
+        sessionHistory: string;
+    };
+    retention: {
+        maxHistoryEntries: number;
+        maxHistoryDays: number;
+        maxConnectionHistoryDays: number;
+    };
+}
+export interface SessionPersistenceData {
+    adminSessions: PersistedAdminSession[];
+    webSocketConnections: PersistedWebSocketConnection[];
+    sessionHistory: PersistedSessionHistoryEntry[];
+    metadata: SessionPersistenceMetadata;
+}
+export interface SessionPersistenceConfig {
+    enabled: boolean;
+    persistenceDir: string;
+    backupIntegration: boolean;
+    retention: {
+        maxHistoryEntries: number;
+        maxHistoryDays: number;
+        maxConnectionHistoryDays: number;
+    };
+    deduplication: {
+        enabled: boolean;
+        checksumAlgorithm: 'sha256' | 'sha512';
+    };
+    atomicWrites: {
+        enabled: boolean;
+        tempSuffix: string;
+        backupSuffix: string;
+    };
+    persistence: {
+        intervalMs: number;
+        onShutdown: boolean;
+        onSessionChange: boolean;
+    };
+}
+export declare const SESSION_PERSISTENCE_FILES: {
+    readonly MANIFEST: "session-manifest.json";
+    readonly ADMIN_SESSIONS: "admin-sessions.json";
+    readonly WEBSOCKET_CONNECTIONS: "websocket-connections.json";
+    readonly SESSION_HISTORY: "session-history.json";
+    readonly METADATA: "session-metadata.json";
+};
+export declare const DEFAULT_SESSION_PERSISTENCE_CONFIG: SessionPersistenceConfig;
+export declare const SESSION_PERSISTENCE_ENV_VARS: {
+    readonly ENABLED: "INDEX_SERVER_SESSION_PERSISTENCE_ENABLED";
+    readonly PERSISTENCE_DIR: "INDEX_SERVER_SESSION_PERSISTENCE_DIR";
+    readonly BACKUP_INTEGRATION: "INDEX_SERVER_SESSION_BACKUP_INTEGRATION";
+    readonly MAX_HISTORY_ENTRIES: "INDEX_SERVER_SESSION_MAX_HISTORY_ENTRIES";
+    readonly MAX_HISTORY_DAYS: "INDEX_SERVER_SESSION_MAX_HISTORY_DAYS";
+    readonly MAX_CONNECTION_HISTORY_DAYS: "INDEX_SERVER_SESSION_MAX_CONNECTION_HISTORY_DAYS";
+    readonly PERSISTENCE_INTERVAL_MS: "INDEX_SERVER_SESSION_PERSISTENCE_INTERVAL_MS";
+    readonly DEDUPLICATION_ENABLED: "INDEX_SERVER_SESSION_DEDUPLICATION_ENABLED";
+};

package/dist/models/SessionPersistence.js

@@ -0,0 +1,66 @@
+"use strict";
+/**
+ * Session Persistence Schema Design
+ *
+ * Persistent storage design for admin sessions, websocket connections, and session history
+ * with deduplication, atomic writes, and backup integration.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SESSION_PERSISTENCE_ENV_VARS = exports.DEFAULT_SESSION_PERSISTENCE_CONFIG = exports.SESSION_PERSISTENCE_FILES = void 0;
+// File naming constants
+exports.SESSION_PERSISTENCE_FILES = {
+    MANIFEST: 'session-manifest.json',
+    ADMIN_SESSIONS: 'admin-sessions.json',
+    WEBSOCKET_CONNECTIONS: 'websocket-connections.json',
+    SESSION_HISTORY: 'session-history.json',
+    METADATA: 'session-metadata.json'
+};
+// Directory structure:
+// {persistenceDir}/
+//   sessions/
+//     session-manifest.json
+//     admin-sessions.json
+//     websocket-connections.json
+//     session-history.json
+//     session-metadata.json
+//   backups/
+//     {timestamp}/
+//       session-manifest.json
+//       admin-sessions.json
+//       websocket-connections.json
+//       session-history.json
+exports.DEFAULT_SESSION_PERSISTENCE_CONFIG = {
+    enabled: true,
+    persistenceDir: './data/sessions',
+    backupIntegration: true,
+    retention: {
+        maxHistoryEntries: 1000,
+        maxHistoryDays: 30,
+        maxConnectionHistoryDays: 7
+    },
+    deduplication: {
+        enabled: true,
+        checksumAlgorithm: 'sha256'
+    },
+    atomicWrites: {
+        enabled: true,
+        tempSuffix: '.tmp',
+        backupSuffix: '.bak'
+    },
+    persistence: {
+        intervalMs: 30000, // 30 seconds
+        onShutdown: true,
+        onSessionChange: true
+    }
+};
+// Environment variable mappings
+exports.SESSION_PERSISTENCE_ENV_VARS = {
+    ENABLED: 'INDEX_SERVER_SESSION_PERSISTENCE_ENABLED',
+    PERSISTENCE_DIR: 'INDEX_SERVER_SESSION_PERSISTENCE_DIR',
+    BACKUP_INTEGRATION: 'INDEX_SERVER_SESSION_BACKUP_INTEGRATION',
+    MAX_HISTORY_ENTRIES: 'INDEX_SERVER_SESSION_MAX_HISTORY_ENTRIES',
+    MAX_HISTORY_DAYS: 'INDEX_SERVER_SESSION_MAX_HISTORY_DAYS',
+    MAX_CONNECTION_HISTORY_DAYS: 'INDEX_SERVER_SESSION_MAX_CONNECTION_HISTORY_DAYS',
+    PERSISTENCE_INTERVAL_MS: 'INDEX_SERVER_SESSION_PERSISTENCE_INTERVAL_MS',
+    DEDUPLICATION_ENABLED: 'INDEX_SERVER_SESSION_DEDUPLICATION_ENABLED'
+};

package/dist/models/instruction.d.ts

@@ -0,0 +1,45 @@
+export type AudienceScope = 'individual' | 'group' | 'all';
+export type RequirementLevel = 'mandatory' | 'critical' | 'recommended' | 'optional' | 'deprecated';
+export type ContentType = 'instruction' | 'template' | 'chat-session' | 'reference' | 'example' | 'agent';
+export interface InstructionEntry {
+    id: string;
+    title: string;
+    body: string;
+    rationale?: string;
+    priority: number;
+    audience: AudienceScope;
+    requirement: RequirementLevel;
+    categories: string[];
+    contentType: ContentType;
+    primaryCategory?: string;
+    sourceHash: string;
+    schemaVersion: string;
+    deprecatedBy?: string;
+    createdAt: string;
+    updatedAt: string;
+    usageCount?: number;
+    firstSeenTs?: string;
+    lastUsedAt?: string;
+    riskScore?: number;
+    workspaceId?: string;
+    userId?: string;
+    teamIds?: string[];
+    version?: string;
+    status?: 'draft' | 'review' | 'approved' | 'deprecated';
+    owner?: string;
+    priorityTier?: 'P1' | 'P2' | 'P3' | 'P4';
+    classification?: 'public' | 'internal' | 'restricted';
+    lastReviewedAt?: string;
+    nextReviewDue?: string;
+    reviewIntervalDays?: number;
+    changeLog?: {
+        version: string;
+        changedAt: string;
+        summary: string;
+    }[];
+    supersedes?: string;
+    archivedAt?: string;
+    semanticSummary?: string;
+    createdByAgent?: string;
+    sourceWorkspace?: string;
+}

package/dist/models/instruction.js

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

package/dist/perf/benchmark.d.ts

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

package/dist/perf/benchmark.js

@@ -0,0 +1,50 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const perf_hooks_1 = require("perf_hooks");
+const crypto_1 = __importDefault(require("crypto"));
+function measure(fn, iterations) {
+    const samples = [];
+    for (let i = 0; i < iterations; i++) {
+        const s = perf_hooks_1.performance.now();
+        fn();
+        const e = perf_hooks_1.performance.now();
+        samples.push(e - s);
+    }
+    samples.sort((a, b) => a - b);
+    const p95Index = Math.floor(samples.length * 0.95) - 1;
+    return {
+        name: fn.name || 'anon',
+        iterations,
+        totalMs: samples.reduce((a, b) => a + b, 0),
+        p95Ms: samples[Math.max(0, p95Index)],
+        maxMs: samples[samples.length - 1]
+    };
+}
+function syntheticEntries(n) {
+    const entries = [];
+    for (let i = 0; i < n; i++) {
+        const body = `Instruction body ${i} ` + 'x'.repeat(50);
+        const hash = crypto_1.default.createHash('sha256').update(body).digest('hex');
+        entries.push({ id: `id-${i}`, title: `Title ${i}`, body, priority: (i % 100) + 1, audience: 'all', requirement: 'mandatory', categories: ['bench'], sourceHash: hash, schemaVersion: '1', createdAt: new Date().toISOString(), updatedAt: new Date().toISOString() });
+    }
+    return entries;
+}
+function run() {
+    const sizes = [100, 1000, 5000];
+    const results = [];
+    for (const size of sizes) {
+        const index = syntheticEntries(size);
+        // measure search
+        const term = 'Instruction body';
+        const stat = measure(() => {
+            const lower = term.toLowerCase();
+            index.filter(e => e.title.toLowerCase().includes(lower) || e.body.toLowerCase().includes(lower));
+        }, 50);
+        results.push({ size, searchP95: stat.p95Ms.toFixed(4), searchMax: stat.maxMs.toFixed(4) });
+    }
+    console.log(JSON.stringify({ benchmark: 'search', results }, null, 2));
+}
+run();

package/dist/portableClientWrapper.d.ts

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

package/dist/portableClientWrapper.js

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

package/dist/schemas/index.d.ts

@@ -0,0 +1,128 @@
+export declare const instructionEntry: {
+    readonly type: "object";
+    readonly additionalProperties: false;
+    readonly required: readonly ["id", "title", "body", "priority", "audience", "requirement", "categories", "sourceHash", "schemaVersion", "createdAt", "updatedAt", "version", "status", "owner", "priorityTier", "classification", "lastReviewedAt", "nextReviewDue", "changeLog", "semanticSummary"];
+    readonly properties: {
+        readonly id: {
+            readonly type: "string";
+            readonly minLength: 1;
+        };
+        readonly title: {
+            readonly type: "string";
+        };
+        readonly body: {
+            readonly type: "string";
+        };
+        readonly rationale: {
+            readonly type: "string";
+        };
+        readonly priority: {
+            readonly type: "number";
+        };
+        readonly audience: {
+            readonly enum: readonly ["individual", "group", "all"];
+        };
+        readonly requirement: {
+            readonly enum: readonly ["mandatory", "critical", "recommended", "optional", "deprecated"];
+        };
+        readonly categories: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "string";
+            };
+        };
+        readonly sourceHash: {
+            readonly type: "string";
+        };
+        readonly schemaVersion: {
+            readonly type: "string";
+        };
+        readonly deprecatedBy: {
+            readonly type: "string";
+        };
+        readonly createdAt: {
+            readonly type: "string";
+        };
+        readonly updatedAt: {
+            readonly type: "string";
+        };
+        readonly usageCount: {
+            readonly type: "number";
+        };
+        readonly firstSeenTs: {
+            readonly type: "string";
+        };
+        readonly lastUsedAt: {
+            readonly type: "string";
+        };
+        readonly riskScore: {
+            readonly type: "number";
+        };
+        readonly workspaceId: {
+            readonly type: "string";
+        };
+        readonly userId: {
+            readonly type: "string";
+        };
+        readonly teamIds: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "string";
+            };
+        };
+        readonly version: {
+            readonly type: "string";
+        };
+        readonly status: {
+            readonly enum: readonly ["draft", "review", "approved", "deprecated"];
+        };
+        readonly owner: {
+            readonly type: "string";
+        };
+        readonly priorityTier: {
+            readonly enum: readonly ["P1", "P2", "P3", "P4"];
+        };
+        readonly classification: {
+            readonly enum: readonly ["public", "internal", "restricted"];
+        };
+        readonly lastReviewedAt: {
+            readonly type: "string";
+        };
+        readonly nextReviewDue: {
+            readonly type: "string";
+        };
+        readonly changeLog: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "object";
+                readonly required: readonly ["version", "changedAt", "summary"];
+                readonly additionalProperties: false;
+                readonly properties: {
+                    readonly version: {
+                        readonly type: "string";
+                    };
+                    readonly changedAt: {
+                        readonly type: "string";
+                    };
+                    readonly summary: {
+                        readonly type: "string";
+                    };
+                };
+            };
+        };
+        readonly supersedes: {
+            readonly type: "string";
+        };
+        readonly semanticSummary: {
+            readonly type: "string";
+        };
+        readonly createdByAgent: {
+            readonly type: "string";
+        };
+        readonly sourceWorkspace: {
+            readonly type: "string";
+        };
+    };
+};
+export declare const schemas: Record<string, unknown>;
+export type SchemaMap = typeof schemas;