@jagilber-org/index-server 1.19.1

package/dist/services/indexRepository.d.ts

@@ -0,0 +1,32 @@
+import { InstructionEntry } from '../models/instruction';
+export interface IndexSnapshot {
+    entries: InstructionEntry[];
+    hash: string;
+}
+export declare class FileIndexRepository {
+    private baseDir;
+    /**
+     * @param baseDir - Absolute path to the directory containing JSON instruction files
+     */
+    constructor(baseDir: string);
+    /**
+     * List all `.json` filenames found in the base directory.
+     * @returns Array of filename strings (basename only), or an empty array if the directory is unreadable
+     */
+    listFiles(): string[];
+    /**
+     * Load all instruction entries from disk and compute a content hash of the directory state.
+     * @returns Snapshot containing the loaded entries and a SHA-256 content hash
+     */
+    load(): IndexSnapshot;
+    /**
+     * Atomically write an instruction entry to disk as `<id>.json`.
+     * @param entry - Instruction entry to persist
+     */
+    save(entry: InstructionEntry): void;
+    /**
+     * Remove the JSON file for the given instruction ID, if it exists.
+     * @param id - Instruction ID whose file should be deleted
+     */
+    remove(id: string): void;
+}

package/dist/services/indexRepository.js

@@ -0,0 +1,71 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FileIndexRepository = void 0;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const crypto_1 = __importDefault(require("crypto"));
+const atomicFs_1 = require("./atomicFs");
+class FileIndexRepository {
+    baseDir;
+    /**
+     * @param baseDir - Absolute path to the directory containing JSON instruction files
+     */
+    constructor(baseDir) {
+        this.baseDir = baseDir;
+    }
+    /**
+     * List all `.json` filenames found in the base directory.
+     * @returns Array of filename strings (basename only), or an empty array if the directory is unreadable
+     */
+    listFiles() {
+        try {
+            return fs_1.default.readdirSync(this.baseDir).filter(f => f.endsWith('.json'));
+        }
+        catch {
+            return [];
+        }
+    }
+    /**
+     * Load all instruction entries from disk and compute a content hash of the directory state.
+     * @returns Snapshot containing the loaded entries and a SHA-256 content hash
+     */
+    load() {
+        const files = this.listFiles();
+        const entries = [];
+        const hash = crypto_1.default.createHash('sha256');
+        for (const f of files) {
+            const fp = path_1.default.join(this.baseDir, f);
+            try {
+                const raw = JSON.parse(fs_1.default.readFileSync(fp, 'utf8'));
+                entries.push(raw);
+                hash.update(raw.id + ':' + (raw.sourceHash || ''), 'utf8');
+            }
+            catch { /* skip */ }
+        }
+        return { entries, hash: hash.digest('hex') };
+    }
+    /**
+     * Atomically write an instruction entry to disk as `<id>.json`.
+     * @param entry - Instruction entry to persist
+     */
+    save(entry) {
+        const fp = path_1.default.join(this.baseDir, `${entry.id}.json`);
+        (0, atomicFs_1.atomicWriteJson)(fp, entry);
+    }
+    /**
+     * Remove the JSON file for the given instruction ID, if it exists.
+     * @param id - Instruction ID whose file should be deleted
+     */
+    remove(id) {
+        const fp = path_1.default.join(this.baseDir, `${id}.json`);
+        try {
+            if (fs_1.default.existsSync(fp))
+                fs_1.default.unlinkSync(fp);
+        }
+        catch { /* ignore */ }
+    }
+}
+exports.FileIndexRepository = FileIndexRepository;

package/dist/services/indexingService.d.ts

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

package/dist/services/indexingService.js

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

package/dist/services/instructions.dispatcher.d.ts

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

package/dist/services/instructions.dispatcher.js

@@ -0,0 +1,231 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const registry_1 = require("../server/registry");
+const handlers_instructions_1 = require("./handlers.instructions");
+const errors_1 = require("./errors");
+const tracing_1 = require("./tracing");
+const indexContext_1 = require("./indexContext");
+const bootstrapGating_1 = require("./bootstrapGating");
+const runtimeConfig_1 = require("../config/runtimeConfig");
+const handlers_search_1 = require("./handlers.search");
+const mutationMethods = new Set([
+    'index_add', 'index_import', 'index_remove', 'index_reload', 'index_groom', 'index_repair', 'index_enrich', 'index_governanceUpdate', 'usage_flush'
+]);
+function isMutationEnabled() {
+    const cfg = (0, runtimeConfig_1.getRuntimeConfig)();
+    return cfg.mutation.enabled;
+}
+(0, registry_1.registerHandler)('index_dispatch', async (params) => {
+    const timing = (0, runtimeConfig_1.getRuntimeConfig)().mutation.dispatcherTiming;
+    const t0 = timing ? Date.now() : 0;
+    const action = (params && params.action);
+    if ((0, tracing_1.traceEnabled)(1)) {
+        try {
+            const dir = (0, indexContext_1.getInstructionsDir)();
+            // Avoid heavy work unless hash diag explicitly requested
+            let hash;
+            if ((0, runtimeConfig_1.getRuntimeConfig)().trace.has('dispatchDiag')) {
+                try {
+                    const st = (0, indexContext_1.ensureLoaded)();
+                    hash = st.hash;
+                }
+                catch { /* ignore */ }
+            }
+            (0, tracing_1.emitTrace)('[trace:dispatch:start]', { action, keys: Object.keys(params || {}).filter(k => k !== 'action'), pid: process.pid, dir, hash });
+        }
+        catch { /* ignore */ }
+    }
+    if (typeof action !== 'string' || !action.trim()) {
+        try {
+            if ((0, runtimeConfig_1.getRuntimeConfig)().logging.verbose)
+                process.stderr.write('[dispatcher] semantic_error code=-32602 reason=missing_action\n');
+        }
+        catch { /* ignore */ }
+        (0, errors_1.semanticError)(-32602, 'Missing action', { method: 'index_dispatch', reason: 'missing_action', hint: 'Provide an "action" parameter. Use action="capabilities" to list all valid actions.', schema: { required: ['action'], properties: { action: { type: 'string', enum: ['list', 'get', 'search', 'query', 'categories', 'diff', 'export', 'add', 'import', 'remove', 'reload', 'groom', 'repair', 'enrich', 'governanceHash', 'governanceUpdate', 'health', 'inspect', 'dir', 'capabilities', 'batch', 'manifestStatus', 'manifestRefresh', 'manifestRepair'] } } }, example: { action: 'search', q: 'build validate' } });
+    }
+    // Capability listing
+    if (action === 'capabilities') {
+        try {
+            if ((0, runtimeConfig_1.getRuntimeConfig)().logging.verbose)
+                process.stderr.write('[dispatcher] capabilities invoked\n');
+        }
+        catch { /* ignore */ }
+        return { version: process.env.npm_package_version || '0.0.0', supportedActions: Object.keys(handlers_instructions_1.instructionActions).concat(['add', 'import', 'remove', 'reload', 'groom', 'repair', 'enrich', 'governanceHash', 'governanceUpdate', 'health', 'inspect', 'dir', 'capabilities', 'batch', 'manifestStatus', 'manifestRefresh', 'manifestRepair']), mutationEnabled: isMutationEnabled() };
+    }
+    // Batch execution
+    if (action === 'batch') {
+        // Accept both 'operations' and 'ops' for flexibility / backward compatibility
+        const rawOps = params.operations || params.ops;
+        const ops = Array.isArray(rawOps) ? rawOps.filter(o => o && typeof o === 'object') : [];
+        const results = [];
+        for (const op of ops) {
+            try {
+                const rHandler = (0, registry_1.getHandler)('index_dispatch');
+                if (!rHandler)
+                    throw new Error('dispatcher recursion handler missing');
+                const r = await Promise.resolve(rHandler({ ...op }));
+                results.push(r);
+            }
+            catch (e) {
+                const errObj = e;
+                results.push({ error: { message: errObj?.message || String(e), code: errObj?.code } });
+            }
+        }
+        return { results };
+    }
+    // Map dispatcher actions to legacy mutation handlers or internal pure actions
+    // Read-only internal actions
+    const READ_ACTIONS_WITH_META = new Set(['get', 'list', 'listScoped', 'search', 'query']);
+    const autoTrack = (0, runtimeConfig_1.getRuntimeConfig)().index?.autoUsageTrack;
+    if (Object.prototype.hasOwnProperty.call(handlers_instructions_1.instructionActions, action)) {
+        const t1 = timing ? Date.now() : 0;
+        const fn = handlers_instructions_1.instructionActions[action];
+        const shouldAddMeta = READ_ACTIONS_WITH_META.has(action);
+        // Specialized reliability wrapper for 'get': automatically attempt late materialization
+        // using internal getEnhanced when initial index lookup fails but on-disk file exists.
+        if (action === 'get') {
+            const id = params.id;
+            if (typeof id === 'string' && id.trim()) {
+                const base = fn({ id });
+                if (base.notFound) {
+                    try {
+                        const enhanced = handlers_instructions_1.instructionActions.getEnhanced?.({ id });
+                        if (enhanced && !enhanced.notFound) {
+                            if (autoTrack) {
+                                try {
+                                    (0, indexContext_1.incrementUsage)(id, { action: 'get' });
+                                }
+                                catch { /* fire-and-forget */ }
+                            }
+                            return { ...enhanced, _meta: (0, handlers_search_1.buildAfterRetrievalMeta)() }; // lateMaterialized success
+                        }
+                    }
+                    catch { /* swallow fallback errors to preserve original semantics */ }
+                }
+                if (shouldAddMeta && !base.notFound) {
+                    if (autoTrack) {
+                        try {
+                            (0, indexContext_1.incrementUsage)(id, { action: 'get' });
+                        }
+                        catch { /* fire-and-forget */ }
+                    }
+                    return { ...base, _meta: (0, handlers_search_1.buildAfterRetrievalMeta)() };
+                }
+                return base;
+            }
+        }
+        const r = await Promise.resolve(fn(params));
+        if ((0, tracing_1.traceEnabled)(1)) {
+            try {
+                (0, tracing_1.emitTrace)('[trace:dispatch:internal]', { action, elapsed: timing ? (Date.now() - t1) : undefined });
+            }
+            catch { /* ignore */ }
+        }
+        if (timing) {
+            try {
+                process.stderr.write(`[dispatcher:timing] action=${action} phase=internal elapsed=${Date.now() - t1}ms total=${Date.now() - t0}ms\n`);
+            }
+            catch { /* ignore */ }
+        }
+        if (shouldAddMeta && r && typeof r === 'object' && !r.notFound && !r.error)
+            return { ...r, _meta: (0, handlers_search_1.buildAfterRetrievalMeta)() };
+        return r;
+    }
+    // Manifest actions (002 Phase 2b consolidation)
+    if (action === 'manifestStatus' || action === 'manifestRefresh' || action === 'manifestRepair') {
+        if (action !== 'manifestStatus') {
+            const gated = (0, bootstrapGating_1.mutationGatedReason)();
+            if (gated)
+                return { error: 'mutation_blocked', reason: gated, target: action, bootstrap: true };
+        }
+        const mName = action === 'manifestStatus' ? 'manifest_status' : action === 'manifestRefresh' ? 'manifest_refresh' : 'manifest_repair';
+        const mHandler = (0, registry_1.getHandler)(mName);
+        if (!mHandler)
+            (0, errors_1.semanticError)(-32601, `${mName} handler not found`, { action });
+        const mResult = await Promise.resolve(mHandler({}));
+        if (action === 'manifestStatus')
+            return { present: mResult.manifestPresent, ...mResult };
+        return mResult;
+    }
+    // Map selected action tokens to existing registered methods for mutation / governance
+    const methodMap = {
+        add: 'index_add', import: 'index_import', remove: 'index_remove', reload: 'index_reload', groom: 'index_groom', repair: 'index_repair', enrich: 'index_enrich', governanceHash: 'index_governanceHash', governanceUpdate: 'index_governanceUpdate', health: 'index_health', inspect: 'index_inspect', dir: 'index_dir'
+    };
+    const target = methodMap[action];
+    if (!target) {
+        try {
+            if ((0, runtimeConfig_1.getRuntimeConfig)().logging.verbose)
+                process.stderr.write(`[dispatcher] semantic_error code=-32601 reason=unknown_action action=${action}\n`);
+        }
+        catch { /* ignore */ }
+        const validActions = ['list', 'get', 'search', 'query', 'categories', 'diff', 'export', 'add', 'import', 'remove', 'reload', 'groom', 'repair', 'enrich', 'governanceHash', 'governanceUpdate', 'health', 'inspect', 'dir', 'capabilities', 'batch', 'manifestStatus', 'manifestRefresh', 'manifestRepair'];
+        (0, errors_1.semanticError)(-32601, `Unknown action: ${action}. Call with action="capabilities" to list all valid actions.`, { action, reason: 'unknown_action', hint: 'Use action="capabilities" for full list. Common actions: list, get, search, add, query, categories.', validActions, schema: { required: ['action'], properties: { action: { type: 'string', enum: validActions } } }, examples: { list: { action: 'list' }, get: { action: 'get', id: 'instruction-id' }, search: { action: 'search', q: 'keyword' } } });
+    }
+    if (mutationMethods.has(target) && !isMutationEnabled()) {
+        // Dispatcher design intent: allow mutation-style actions even when direct mutation tools
+        // are disabled. The previous logic incorrectly blocked these calls, causing silent timeouts
+        // in tests expecting dispatcher add to succeed without INDEX_SERVER_MUTATION=1.
+        // We now log (if verbose) and proceed instead of throwing a semantic error.
+        try {
+            if ((0, runtimeConfig_1.getRuntimeConfig)().logging.verbose)
+                process.stderr.write(`[dispatcher] mutation_allowed_via_dispatcher action=${action} target=${target} (INDEX_SERVER_MUTATION not set)\n`);
+        }
+        catch { /* ignore */ }
+    }
+    const handler = (0, registry_1.getHandler)(target);
+    if (!handler) {
+        try {
+            if ((0, runtimeConfig_1.getRuntimeConfig)().logging.verbose)
+                process.stderr.write(`[dispatcher] semantic_error code=-32601 reason=unknown_handler action=${action} target=${target}\n`);
+        }
+        catch { /* ignore */ }
+        (0, errors_1.semanticError)(-32601, 'Unknown action handler', { action, target, reason: 'unknown_handler' });
+    }
+    // Strip action key for downstream handler params
+    const { action: _ignoredAction, ...rest } = params;
+    // Backward-compatible convenience: allow single 'id' for remove instead of 'ids' array
+    if (action === 'remove' && typeof rest.id === 'string' && !rest.ids) {
+        rest.ids = [rest.id];
+        delete rest.id;
+    }
+    // Flat-param assembly for 'add': agents send flat params (id, body, title, ...)
+    // because the dispatch schema cannot express nested 'entry' wrappers.
+    // When 'entry' is absent but 'id' is present, assemble the entry from flat params.
+    if (action === 'add' && !rest.entry && typeof rest.id === 'string') {
+        const entryFields = ['id', 'body', 'title', 'rationale', 'priority', 'audience', 'requirement', 'categories', 'deprecatedBy', 'riskScore', 'version', 'owner', 'status', 'priorityTier', 'classification', 'lastReviewedAt', 'nextReviewDue', 'semanticSummary', 'changeLog'];
+        const entry = {};
+        for (const k of entryFields) {
+            if (rest[k] !== undefined) {
+                entry[k] = rest[k];
+                delete rest[k];
+            }
+        }
+        rest.entry = entry;
+    }
+    void _ignoredAction; // explicitly ignore for lint
+    // Mark invocation origin so guard() can allow dispatcher-mediated mutations even if
+    // INDEX_SERVER_MUTATION is not globally enabled.
+    rest._viaDispatcher = true;
+    const hStart = timing ? Date.now() : 0;
+    // Gating: block mutation targets if bootstrap confirmation required or reference mode active.
+    if (mutationMethods.has(target)) {
+        const gated = (0, bootstrapGating_1.mutationGatedReason)();
+        if (gated) {
+            return { error: 'mutation_blocked', reason: gated, target: action, bootstrap: true };
+        }
+    }
+    const out = await Promise.resolve(handler(rest));
+    if ((0, tracing_1.traceEnabled)(1)) {
+        try {
+            (0, tracing_1.emitTrace)('[trace:dispatch:handler]', { action, elapsed: timing ? (Date.now() - hStart) : undefined, total: timing ? (Date.now() - t0) : undefined });
+        }
+        catch { /* ignore */ }
+    }
+    if (timing) {
+        try {
+            process.stderr.write(`[dispatcher:timing] action=${action} phase=targetHandler elapsedTotal=${Date.now() - t0}ms\n`);
+        }
+        catch { /* ignore */ }
+    }
+    return out;
+});

package/dist/services/logPrefix.d.ts

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

package/dist/services/logPrefix.js

@@ -0,0 +1,30 @@
+"use strict";
+// Global stderr console redirection for MCP protocol safety.
+// Redirects console.log / console.debug / console.info to stderr so dashboard
+// server-side code never contaminates the MCP JSON-RPC stdio protocol stream on stdout.
+// Does NOT patch stderr.write — NDJSON log lines must pass through unmodified.
+// Safe to import multiple times (idempotent guard).
+Object.defineProperty(exports, "__esModule", { value: true });
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+if (!global.__mcpConsoleRedirected) {
+    try {
+        const stderrWrite = process.stderr.write.bind(process.stderr);
+        const redirect = (original) => {
+            return (...args) => {
+                try {
+                    const msg = args.map(a => (typeof a === 'string' ? a : JSON.stringify(a))).join(' ');
+                    stderrWrite(msg + '\n');
+                }
+                catch {
+                    original(...args);
+                }
+            };
+        };
+        console.log = redirect(console.log);
+        console.debug = redirect(console.debug);
+        console.info = redirect(console.info);
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        global.__mcpConsoleRedirected = true;
+    }
+    catch { /* ignore */ }
+}

package/dist/services/logger.d.ts

@@ -0,0 +1,52 @@
+export type LogLevel = 'TRACE' | 'DEBUG' | 'INFO' | 'WARN' | 'ERROR';
+export interface LogRecord {
+    ts: string;
+    level: LogLevel;
+    msg: string;
+    detail?: string;
+    tool?: string;
+    ms?: number;
+    pid?: number;
+    port?: string;
+    correlationId?: string;
+}
+/**
+ * Generate a new random correlation ID (16 hex characters).
+ * @returns Hex string suitable for tagging a single request context
+ */
+export declare function newCorrelationId(): string;
+/**
+ * Emit a structured NDJSON log record at the specified level.
+ * @param level - TRACE | DEBUG | INFO | WARN | ERROR
+ * @param msg - Message with [module] prefix for heatmap matching
+ * @param fields - Additional fields (detail, tool, ms, correlationId, etc.)
+ */
+export declare function log(level: LogLevel, msg: string, fields?: Partial<Omit<LogRecord, 'level' | 'ts' | 'msg'>>): void;
+/** TRACE — function entry/exit tracing and low-level diagnostics.
+ * Use `→ Class.method` / `← Class.method` prefixes for call graph support.
+ * @param msg - Message (use → / ← prefixes for function tracing)
+ * @param detail - Optional data serialized into the detail field
+ */
+export declare const logTrace: (msg: string, detail?: unknown) => void;
+/** DEBUG — diagnostic information for development.
+ * @param msg - Message with [module] prefix
+ * @param detail - Optional data serialized into the detail field
+ */
+export declare const logDebug: (msg: string, detail?: unknown) => void;
+/** INFO — normal operational events.
+ * @param msg - Message with [module] prefix
+ * @param detail - Optional data serialized into the detail field
+ */
+export declare const logInfo: (msg: string, detail?: unknown) => void;
+/** WARN — potential issues. Captures V8 call-site stack into detail for Error Trace Flow.
+ * Error instances use their own stack; non-Error detail is serialized with call-site stack appended.
+ * @param msg - Message with [module] prefix
+ * @param detail - Optional Error, string, or data; Error.stack or V8 call-site stack used
+ */
+export declare const logWarn: (msg: string, detail?: unknown) => void;
+/** ERROR — failures. Captures V8 call-site stack into detail for Error Trace Flow.
+ * Error instances use their own stack; non-Error detail is serialized with call-site stack appended.
+ * @param msg - Message with [module] prefix
+ * @param detail - Optional Error, string, or data; Error.stack or V8 call-site stack used
+ */
+export declare const logError: (msg: string, detail?: unknown) => void;