@jagilber-org/index-server 1.19.1

package/dist/services/handlers.feedback.js

@@ -0,0 +1,378 @@
+"use strict";
+/**
+ * Feedback/Emit System for Index Server
+ *
+ * Provides MCP protocol-compliant tools for clients to submit structured feedback,
+ * status reports, security issues, feature requests, and other communications
+ * to server administrators or monitoring systems.
+ *
+ * This system follows MCP best practices:
+ * - Tools are discoverable via tools/list
+ * - Input validation via JSON schemas
+ * - Structured responses for programmatic consumption
+ * - Proper error handling and logging
+ * - Audit trail for security and compliance
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const registry_1 = require("../server/registry");
+const logger_1 = require("./logger");
+const runtimeConfig_1 = require("../config/runtimeConfig");
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const crypto_1 = require("crypto");
+// Directory is resolved dynamically so tests can override via env per test case.
+// Fall back to config for max entries; tests may still override INDEX_SERVER_FEEDBACK_DIR.
+function getMaxEntries() {
+    return (0, runtimeConfig_1.getRuntimeConfig)().feedback.maxEntries;
+}
+function getFeedbackDir() {
+    return (0, runtimeConfig_1.getRuntimeConfig)().feedback.dir;
+}
+function getFeedbackFile() {
+    return path_1.default.join(getFeedbackDir(), 'feedback-entries.json');
+}
+function ensureFeedbackDir() {
+    const dir = getFeedbackDir();
+    if (!fs_1.default.existsSync(dir)) {
+        try {
+            fs_1.default.mkdirSync(dir, { recursive: true });
+        }
+        catch (error) {
+            (0, logger_1.logError)('[feedback] Failed to create feedback directory', { error: String(error), dir });
+        }
+    }
+    return dir;
+}
+/**
+ * Load feedback entries from storage
+ */
+function loadFeedbackStorage() {
+    const file = getFeedbackFile();
+    ensureFeedbackDir();
+    try {
+        if (fs_1.default.existsSync(file)) {
+            const content = fs_1.default.readFileSync(file, 'utf8');
+            const parsed = JSON.parse(content);
+            // Validate structure
+            if (!parsed.entries || !Array.isArray(parsed.entries)) {
+                throw new Error('Invalid feedback storage format');
+            }
+            return parsed;
+        }
+    }
+    catch (error) {
+        (0, logger_1.logWarn)('[feedback] Failed to load feedback storage, initializing empty', { error: String(error) });
+    }
+    return {
+        entries: [],
+        lastUpdated: new Date().toISOString(),
+        version: '1.0.0'
+    };
+}
+/**
+ * Save feedback entries to storage
+ */
+function saveFeedbackStorage(storage) {
+    const file = getFeedbackFile();
+    ensureFeedbackDir();
+    try {
+        // Limit storage size
+        const maxEntries = getMaxEntries();
+        if (storage.entries.length > maxEntries) {
+            // Keep most recent entries
+            storage.entries = storage.entries
+                .sort((a, b) => b.timestamp.localeCompare(a.timestamp))
+                .slice(0, maxEntries);
+        }
+        storage.lastUpdated = new Date().toISOString();
+        const content = JSON.stringify(storage, null, 2);
+        fs_1.default.writeFileSync(file, content, 'utf8');
+    }
+    catch (error) {
+        (0, logger_1.logError)('[feedback] Failed to save feedback storage', error instanceof Error ? error : { error: String(error) });
+        throw error;
+    }
+}
+/**
+ * Generate unique ID for feedback entry
+ */
+function generateFeedbackId(type, timestamp) {
+    const hash = (0, crypto_1.createHash)('sha256');
+    hash.update(`${type}-${timestamp}-${Math.random()}`);
+    return hash.digest('hex').substring(0, 16);
+}
+/**
+ * feedback_submit - Submit new feedback entry
+ */
+(0, registry_1.registerHandler)('feedback_submit', (params) => {
+    // Validate required parameters
+    if (!params.type || !params.severity || !params.title || !params.description) {
+        throw new Error('Missing required parameters: type, severity, title, description');
+    }
+    // Validate enum values
+    const validTypes = ['issue', 'status', 'security', 'feature-request', 'bug-report', 'performance', 'usability', 'other'];
+    const validSeverities = ['low', 'medium', 'high', 'critical'];
+    if (!validTypes.includes(params.type)) {
+        throw new Error(`Invalid type. Must be one of: ${validTypes.join(', ')}`);
+    }
+    if (!validSeverities.includes(params.severity)) {
+        throw new Error(`Invalid severity. Must be one of: ${validSeverities.join(', ')}`);
+    }
+    const timestamp = new Date().toISOString();
+    const entry = {
+        id: generateFeedbackId(params.type, timestamp),
+        timestamp,
+        type: params.type,
+        severity: params.severity,
+        title: params.title.substring(0, 200), // Limit title length
+        description: params.description.substring(0, 10000), // Limit description length
+        context: params.context,
+        metadata: params.metadata,
+        tags: params.tags?.slice(0, 10), // Limit number of tags
+        status: 'new'
+    };
+    const storage = loadFeedbackStorage();
+    storage.entries.push(entry);
+    saveFeedbackStorage(storage);
+    // Log feedback submission for audit trail
+    (0, logger_1.logInfo)('[feedback] Feedback submitted', {
+        id: entry.id,
+        type: entry.type,
+        severity: entry.severity,
+        title: entry.title
+    });
+    // For security issues, also log to stderr for immediate visibility
+    if (entry.type === 'security' || entry.severity === 'critical') {
+        try {
+            process.stderr.write(`[SECURITY/CRITICAL] Feedback ID: ${entry.id}, Type: ${entry.type}, Title: ${entry.title}\n`);
+        }
+        catch {
+            // Ignore stderr write failures
+        }
+    }
+    return {
+        success: true,
+        feedbackId: entry.id,
+        timestamp: entry.timestamp,
+        message: 'Feedback submitted successfully'
+    };
+});
+/**
+ * feedback_list - List feedback entries with filtering
+ */
+(0, registry_1.registerHandler)('feedback_list', (params) => {
+    const storage = loadFeedbackStorage();
+    let entries = [...storage.entries];
+    // Apply filters
+    if (params.type) {
+        entries = entries.filter(e => e.type === params.type);
+    }
+    if (params.severity) {
+        entries = entries.filter(e => e.severity === params.severity);
+    }
+    if (params.status) {
+        entries = entries.filter(e => e.status === params.status);
+    }
+    if (typeof params.since === 'string' && params.since) {
+        const sinceVal = params.since;
+        entries = entries.filter(e => e.timestamp >= sinceVal);
+    }
+    if (params.tags && params.tags.length > 0) {
+        entries = entries.filter(e => e.tags && params.tags.some(tag => e.tags.includes(tag)));
+    }
+    // Sort by timestamp (newest first)
+    entries.sort((a, b) => b.timestamp.localeCompare(a.timestamp));
+    // Apply pagination
+    const limit = Math.min(params.limit || 50, 200); // Max 200 entries per request
+    const offset = params.offset || 0;
+    const paginatedEntries = entries.slice(offset, offset + limit);
+    return {
+        entries: paginatedEntries,
+        total: entries.length,
+        limit,
+        offset,
+        hasMore: offset + limit < entries.length
+    };
+});
+/**
+ * feedback_get - Get specific feedback entry by ID
+ */
+(0, registry_1.registerHandler)('feedback_get', (params) => {
+    if (!params.id) {
+        throw new Error('Missing required parameter: id');
+    }
+    const storage = loadFeedbackStorage();
+    const entry = storage.entries.find(e => e.id === params.id);
+    if (!entry) {
+        return { notFound: true, id: params.id, hint: `No feedback entry found with id "${params.id}". Use feedback_list to see all entries.` };
+    }
+    return { entry };
+});
+/**
+ * feedback_update - Update feedback entry status (admin function)
+ */
+(0, registry_1.registerHandler)('feedback_update', (params) => {
+    if (!params.id) {
+        throw new Error('Missing required parameter: id');
+    }
+    const validStatuses = ['new', 'acknowledged', 'in-progress', 'resolved', 'closed'];
+    if (params.status && !validStatuses.includes(params.status)) {
+        throw new Error(`Invalid status. Must be one of: ${validStatuses.join(', ')}`);
+    }
+    const storage = loadFeedbackStorage();
+    const entryIndex = storage.entries.findIndex(e => e.id === params.id);
+    if (entryIndex === -1) {
+        return { notFound: true, id: params.id, hint: `No feedback entry found with id "${params.id}". Use feedback_list to see all entries.` };
+    }
+    const entry = storage.entries[entryIndex];
+    const oldStatus = entry.status;
+    // Update fields
+    if (params.status) {
+        entry.status = params.status;
+    }
+    if (params.metadata) {
+        entry.metadata = { ...entry.metadata, ...params.metadata };
+    }
+    // Add update timestamp to metadata
+    entry.metadata = {
+        ...entry.metadata,
+        lastUpdated: new Date().toISOString(),
+        updatedBy: 'system' // Could be enhanced to track admin user
+    };
+    storage.entries[entryIndex] = entry;
+    saveFeedbackStorage(storage);
+    (0, logger_1.logInfo)('[feedback] Feedback entry updated', {
+        id: entry.id,
+        oldStatus,
+        newStatus: entry.status,
+        type: entry.type
+    });
+    return {
+        success: true,
+        entry,
+        message: 'Feedback entry updated successfully'
+    };
+});
+/**
+ * feedback_stats - Get feedback statistics and metrics
+ */
+(0, registry_1.registerHandler)('feedback_stats', (params) => {
+    const storage = loadFeedbackStorage();
+    let entries = storage.entries;
+    // Filter by date if specified
+    if (params.since) {
+        const sinceDate = params.since;
+        entries = entries.filter(e => e.timestamp >= sinceDate);
+    }
+    // Calculate statistics
+    const stats = {
+        total: entries.length,
+        byType: {},
+        bySeverity: {},
+        byStatus: {},
+        recentActivity: {
+            last24h: 0,
+            last7d: 0,
+            last30d: 0
+        }
+    };
+    const now = Date.now();
+    const day = 24 * 60 * 60 * 1000;
+    entries.forEach(entry => {
+        // Count by type
+        stats.byType[entry.type] = (stats.byType[entry.type] || 0) + 1;
+        // Count by severity
+        stats.bySeverity[entry.severity] = (stats.bySeverity[entry.severity] || 0) + 1;
+        // Count by status
+        stats.byStatus[entry.status] = (stats.byStatus[entry.status] || 0) + 1;
+        // Count recent activity
+        const entryTime = new Date(entry.timestamp).getTime();
+        const age = now - entryTime;
+        if (age <= day)
+            stats.recentActivity.last24h++;
+        if (age <= 7 * day)
+            stats.recentActivity.last7d++;
+        if (age <= 30 * day)
+            stats.recentActivity.last30d++;
+    });
+    return {
+        stats,
+        storageInfo: {
+            lastUpdated: storage.lastUpdated,
+            version: storage.version,
+            maxEntries: getMaxEntries()
+        }
+    };
+});
+/**
+ * feedback_health - Health check for feedback system
+ */
+(0, registry_1.registerHandler)('feedback_health', () => {
+    const dir = getFeedbackDir();
+    const file = getFeedbackFile();
+    const health = {
+        status: 'ok',
+        timestamp: new Date().toISOString(),
+        storage: {
+            accessible: false,
+            writable: false,
+            directory: dir,
+            file
+        },
+        config: {
+            maxEntries: getMaxEntries(),
+            feedbackDir: dir
+        }
+    };
+    try {
+        // Check if storage is accessible
+        if (fs_1.default.existsSync(file)) {
+            fs_1.default.accessSync(file, fs_1.default.constants.R_OK);
+            health.storage.accessible = true;
+        }
+        else {
+            // File doesn't exist but directory should be writable
+            health.storage.accessible = fs_1.default.existsSync(dir);
+        }
+        // Check if writable
+        ensureFeedbackDir();
+        fs_1.default.accessSync(dir, fs_1.default.constants.W_OK);
+        health.storage.writable = true;
+    }
+    catch (error) {
+        health.status = 'degraded';
+        (0, logger_1.logWarn)('[feedback] Health check failed', error instanceof Error ? error : { error: String(error) });
+    }
+    return health;
+});
+// Unified feedback dispatch handler (002 Phase 2a)
+(0, registry_1.registerHandler)('feedback_dispatch', async (params) => {
+    const { action, ...rest } = params;
+    if (!action)
+        throw new Error('Missing required parameter: action');
+    const validActions = ['submit', 'list', 'get', 'update', 'stats', 'health'];
+    if (!validActions.includes(action)) {
+        throw new Error(`Unknown feedback action: ${action}. Valid: ${validActions.join(', ')}`);
+    }
+    // Flat-param alias: agents may send 'body' instead of 'description' (v1.8.2+)
+    if (action === 'submit' && rest.body != null && rest.description == null) {
+        rest.description = rest.body;
+        delete rest.body;
+    }
+    const handler = (0, registry_1.getHandler)(`feedback_${action}`);
+    if (!handler)
+        throw new Error(`Handler not found for feedback_${action}`);
+    const result = await Promise.resolve(handler(rest));
+    // Reshape results for consistent dispatch API
+    if (action === 'submit') {
+        return { id: result.feedbackId, status: 'new', ...result };
+    }
+    if (action === 'stats') {
+        const stats = result.stats;
+        return { total: stats?.total, ...result };
+    }
+    return result;
+});

package/dist/services/handlers.gates.d.ts

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

package/dist/services/handlers.gates.js

@@ -0,0 +1,46 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const registry_1 = require("../server/registry");
+const indexContext_1 = require("./indexContext");
+(0, registry_1.registerHandler)('gates_evaluate', () => { const st = (0, indexContext_1.ensureLoaded)(); const gatesPath = path_1.default.join((0, indexContext_1.getInstructionsDir)(), 'gates.json'); if (!fs_1.default.existsSync(gatesPath))
+    return { notConfigured: true }; let data; try {
+    data = JSON.parse(fs_1.default.readFileSync(gatesPath, 'utf8'));
+}
+catch {
+    return { error: 'invalid gates file' };
+} const results = []; for (const g of data.gates || []) {
+    if (g.type !== 'count')
+        continue;
+    const matches = st.list.filter(e => { const w = g.where || {}; let ok = true; if (w.requirement !== undefined)
+        ok = ok && e.requirement === w.requirement; if (w.priorityGt !== undefined)
+        ok = ok && e.priority > w.priorityGt; return ok; });
+    const count = matches.length;
+    const v = g.value;
+    let passed = true;
+    switch (g.op) {
+        case '>=':
+            passed = count >= v;
+            break;
+        case '>':
+            passed = count > v;
+            break;
+        case '<=':
+            passed = count <= v;
+            break;
+        case '<':
+            passed = count < v;
+            break;
+        case '==':
+            passed = count === v;
+            break;
+        case '!=':
+            passed = count !== v;
+            break;
+    }
+    results.push({ id: g.id, passed, count, op: g.op, value: v, severity: g.severity, description: g.description });
+} const summary = { errors: results.filter(r => !r.passed && r.severity === 'error').length, warnings: results.filter(r => !r.passed && r.severity === 'warn').length, total: results.length }; return { generatedAt: new Date().toISOString(), results, summary }; });

package/dist/services/handlers.graph.d.ts

@@ -0,0 +1,53 @@
+import { getRuntimeConfig } from '../config/runtimeConfig';
+type GraphConfigSnapshot = ReturnType<typeof getRuntimeConfig>['graph'];
+export interface GraphExportParams {
+    includeEdgeTypes?: Array<'primary' | 'category' | 'belongs'>;
+    maxEdges?: number;
+    format?: 'json' | 'dot' | 'mermaid';
+    enrich?: boolean;
+    includeCategoryNodes?: boolean;
+    includeUsage?: boolean;
+}
+interface GraphNodeV1 {
+    id: string;
+}
+interface GraphNodeV2 extends GraphNodeV1 {
+    categories?: string[];
+    primaryCategory?: string;
+    priority?: number;
+    priorityTier?: string;
+    requirement?: string;
+    owner?: string;
+    status?: string;
+    createdAt?: string;
+    updatedAt?: string;
+    usageCount?: number;
+    nodeType?: 'instruction' | 'category';
+}
+type GraphNode = GraphNodeV1 | GraphNodeV2;
+interface GraphEdgeBase {
+    from: string;
+    to: string;
+    type: 'primary' | 'category' | 'belongs';
+}
+interface GraphEdgeEnriched extends GraphEdgeBase {
+    weight?: number;
+}
+type GraphEdge = GraphEdgeBase | GraphEdgeEnriched;
+interface GraphMeta {
+    graphSchemaVersion: 1 | 2;
+    nodeCount: number;
+    edgeCount: number;
+    truncated?: boolean;
+    notes?: string[];
+}
+interface GraphResult {
+    meta: GraphMeta;
+    nodes: GraphNode[];
+    edges: GraphEdge[];
+    dot?: string;
+    mermaid?: string;
+}
+export declare function buildGraph(params: GraphExportParams, graphCfg?: GraphConfigSnapshot): GraphResult;
+export declare function __resetGraphCache(): void;
+export {};