d365fo-mcp 1.8.0 → 1.8.2

package/dist/bootstrapEnv.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Configuration bootstrap — import this FIRST from every entry point.
+ *
+ * Importing this module loads config/d365fo-mcp.json, config/secrets.json and
+ * .env onto process.env as a side effect (see loadEnv for the precedence rules).
+ *
+ * Why a module instead of a plain call
+ * ------------------------------------
+ * ESM evaluates every `import` declaration before the first statement of the
+ * importing module's body. Entry points used to be written as
+ *
+ *     import { loadEnv } from './utils/loadEnv.js';
+ *     loadEnv(import.meta.url);          // <- reads first, runs last
+ *     import { apiKeyAuth } from './middleware/apiKeyAuth.js';
+ *
+ * which looks like configuration is loaded up front but is not: every module in
+ * the import graph — including the ones that snapshot process.env into a
+ * module-level const — had already been evaluated by the time loadEnv() ran, so
+ * they all saw the unconfigured environment. That silently disabled API-key
+ * authentication for keys supplied through .env or config/secrets.json, and made
+ * METADATA_PATH, the MCP tool timeouts and the rate-limit settings unreadable
+ * from those files.
+ *
+ * A side-effect import is subject to the same evaluation order it is trying to
+ * control, so being *first* is what makes it correct — an import placed above it
+ * still wins. tests/server/envConfigTiming.test.ts enforces that ordering.
+ *
+ * This file deliberately lives next to index.ts rather than in utils/: loadEnv
+ * resolves the installation directory from the caller's own location, so the
+ * bootstrap must sit at the same depth the entry points do.
+ */
+export {};
+//# sourceMappingURL=bootstrapEnv.d.ts.map

package/dist/bootstrapEnv.js

@@ -0,0 +1,34 @@
+/**
+ * Configuration bootstrap — import this FIRST from every entry point.
+ *
+ * Importing this module loads config/d365fo-mcp.json, config/secrets.json and
+ * .env onto process.env as a side effect (see loadEnv for the precedence rules).
+ *
+ * Why a module instead of a plain call
+ * ------------------------------------
+ * ESM evaluates every `import` declaration before the first statement of the
+ * importing module's body. Entry points used to be written as
+ *
+ *     import { loadEnv } from './utils/loadEnv.js';
+ *     loadEnv(import.meta.url);          // <- reads first, runs last
+ *     import { apiKeyAuth } from './middleware/apiKeyAuth.js';
+ *
+ * which looks like configuration is loaded up front but is not: every module in
+ * the import graph — including the ones that snapshot process.env into a
+ * module-level const — had already been evaluated by the time loadEnv() ran, so
+ * they all saw the unconfigured environment. That silently disabled API-key
+ * authentication for keys supplied through .env or config/secrets.json, and made
+ * METADATA_PATH, the MCP tool timeouts and the rate-limit settings unreadable
+ * from those files.
+ *
+ * A side-effect import is subject to the same evaluation order it is trying to
+ * control, so being *first* is what makes it correct — an import placed above it
+ * still wins. tests/server/envConfigTiming.test.ts enforces that ordering.
+ *
+ * This file deliberately lives next to index.ts rather than in utils/: loadEnv
+ * resolves the installation directory from the caller's own location, so the
+ * bootstrap must sit at the same depth the entry points do.
+ */
+import { loadEnv } from './utils/loadEnv.js';
+loadEnv(import.meta.url);
+//# sourceMappingURL=bootstrapEnv.js.map

package/dist/bridge/bridgeAdapter.js

@@ -965,6 +965,9 @@ export async function bridgeRefreshProvider(bridge) {
     if (!bridge?.isReady || !bridge.metadataAvailable)
         return null;
     try {
+        // Recorded so callers that only need the provider to be no older than a
+        // given write can skip a redundant rebuild — see debouncedRefresh.
+        debouncedRefresh.markRefreshStarted();
         return await bridge.refreshProvider();
     }
     catch (e) {

package/dist/bridge/debouncedRefresh.d.ts

@@ -4,6 +4,12 @@
  */
 import type { BridgeClient } from './bridgeClient.js';
 import type { BridgeRefreshResult } from './bridgeClient.js';
+/** Epoch ms at which the last provider refresh started; 0 if none yet. */
+export declare function getLastRefreshStartedAt(): number;
+/** Record that a refresh is starting now. Called by every refresh path. */
+export declare function markRefreshStarted(at?: number): void;
+/** Forget the recorded refresh time (test isolation). */
+export declare function resetRefreshTracking(): void;
 /**
  * Request a bridge refresh. If one is already pending, the settle timer
  * resets (up to MAX_WAIT_MS). All callers receive the same result.

package/dist/bridge/debouncedRefresh.js

@@ -5,6 +5,30 @@
 const SETTLE_MS = 400;
 const MAX_WAIT_MS = 2_000;
 let pending = null;
+/**
+ * When the most recent provider refresh STARTED (epoch ms), across both this
+ * module and the direct bridgeRefreshProvider() path.
+ *
+ * Start rather than completion, because only a refresh that began after a file
+ * was written is guaranteed to have read it. Callers use this to skip a refresh
+ * that would rediscover nothing: a create/modify already refreshes the provider
+ * on its way out, so the update_symbol_index call that follows it was paying for
+ * a second full DiskProvider rebuild that could not see anything new.
+ */
+let lastRefreshStartedAt = 0;
+/** Epoch ms at which the last provider refresh started; 0 if none yet. */
+export function getLastRefreshStartedAt() {
+    return lastRefreshStartedAt;
+}
+/** Record that a refresh is starting now. Called by every refresh path. */
+export function markRefreshStarted(at = Date.now()) {
+    if (at > lastRefreshStartedAt)
+        lastRefreshStartedAt = at;
+}
+/** Forget the recorded refresh time (test isolation). */
+export function resetRefreshTracking() {
+    lastRefreshStartedAt = 0;
+}
 /**
  * Request a bridge refresh. If one is already pending, the settle timer
  * resets (up to MAX_WAIT_MS). All callers receive the same result.
@@ -50,6 +74,7 @@ function executeRefresh() {
         return;
     const { resolve, bridge } = pending;
     pending = null;
+    markRefreshStarted();
     bridge.refreshProvider()
         .then(result => resolve(result))
         .catch(err => {

package/dist/index.d.ts

@@ -2,5 +2,5 @@
  * X++ MCP Code Completion Server
  * Main entry point
  */
-export {};
+import './bootstrapEnv.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -2,9 +2,10 @@
  * X++ MCP Code Completion Server
  * Main entry point
  */
-// Load .env — supports ENV_FILE env var for multi-instance setups (see src/utils/loadEnv.ts).
-import { loadEnv } from './utils/loadEnv.js';
-loadEnv(import.meta.url);
+// Load configuration onto process.env — MUST stay the first import: ESM
+// evaluates imports before any module body, so anything above this line is
+// evaluated before the configuration exists (see src/bootstrapEnv.ts).
+import './bootstrapEnv.js';
 import { fileURLToPath } from 'url';
 import { dirname, resolve } from 'path';
 import express from 'express';
@@ -23,6 +24,8 @@ import { TOOL_ANNOTATIONS } from './server/toolAnnotations.js';
 import { apiKeyAuth } from './middleware/apiKeyAuth.js';
 import { VERSION } from './version.js';
 import { setInitializeParams } from './utils/stdioSessionInfo.js';
+import { setModelObjectNameSource } from './utils/modelPrefixInference.js';
+import { createShutdownCoordinator } from './utils/gracefulShutdown.js';
 import { box, kv, sectionTitle, statusLine, spread, c, glyph, sanitize, supportsUnicode, log, shortPath, startupWarnings } from './utils/terminalUi.js';
 import * as fs from 'fs/promises';
 import * as fsSync from 'node:fs';
@@ -120,6 +123,11 @@ const serverState = {
     isHealthy: false,
     statusMessage: 'Starting...',
 };
+// Graceful shutdown — see src/utils/gracefulShutdown.ts for why and how.
+const shutdownCoordinator = createShutdownCoordinator({
+    deadlineMs: Math.max(1_000, parseInt(process.env.SHUTDOWN_TIMEOUT_MS || '5000', 10) || 5_000),
+});
+const onShutdown = shutdownCoordinator.onShutdown;
 async function initializeServices() {
     // -----------------------------------------------------------------------
     // write-only mode: skip all database/symbol work — LOCAL_TOOLS
@@ -239,6 +247,10 @@ async function initializeServices() {
                 throw error;
             }
         }
+        // Let object naming learn each model's prefix from the objects that model
+        // already contains, instead of applying one configured EXTENSION_PREFIX to
+        // every model a developer works in (see utils/modelPrefixInference.ts).
+        setModelObjectNameSource(model => symbolIndex.getModelObjectNames(model));
         const parser = new XppMetadataParser();
         // Check if database needs indexing
         if (!dbHasSymbols) {
@@ -370,6 +382,10 @@ async function initializeBridge(targetContext) {
         });
         if (bridge) {
             targetContext.bridge = bridge;
+            // dispose() ends the child's stdin and escalates to SIGTERM/SIGKILL, so the
+            // bridge gets the chance to finish an in-flight AOT write and close its own
+            // metadata handles rather than being cut off mid-file.
+            onShutdown('C# bridge', () => bridge.dispose());
             const cap = `metadata ${bridge.metadataAvailable ? 'yes' : 'no'} ${glyph.dot} xref ${bridge.xrefAvailable ? 'yes' : 'no'}`;
             return { ok: true, summary: `C# bridge connected (${devEnvType}) ${glyph.dot} ${cap}` };
         }
@@ -384,6 +400,18 @@ async function initializeBridge(targetContext) {
     }
 }
 async function main() {
+    // Registered first so it runs LAST (cleanups run in reverse): the log file is
+    // where the other steps report, so it has to outlive them.
+    onShutdown('log file', () => {
+        if (_logStream) {
+            _logStream.end();
+            _logStream = undefined;
+        }
+    });
+    // Covers whichever index ended up in serverState — the real one, the in-memory
+    // stub, or the replacement built after a corrupt-DB recovery.
+    onShutdown('symbol index', () => serverState.symbolIndex?.close?.());
+    shutdownCoordinator.registerSignalHandlers({ stdio: isStdioMode });
     // ─────────────────────────────────────────────────────────────────────────────
     // Stdin sniffer: capture the `initialize` request params for get_workspace_info.
     // ─────────────────────────────────────────────────────────────────────────────
@@ -635,7 +663,13 @@ async function main() {
             });
         });
         // Bind port immediately — Azure requires the port to be open within ~230 s
-        await new Promise(resolve => app.listen(PORT, host, () => resolve()));
+        const httpServer = await new Promise(resolve => {
+            const s = app.listen(PORT, host, () => resolve(s));
+        });
+        // Stop accepting new connections and let in-flight requests finish. Bounded
+        // by the shutdown deadline, so a held-open keep-alive socket cannot stall the
+        // exit.
+        onShutdown('HTTP server', () => new Promise(resolve => httpServer.close(() => resolve())));
         // Initialise services in the background; register MCP routes once ready
         initializeServices().then(async ({ mcpServer, symbolIndex, parser, workspaceScanner, hybridSearch, context }) => {
             // Register MCP transport (Express supports dynamic route registration)

package/dist/metadata/buildIndexWorker.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Index-build worker thread.
+ *
+ * CREATE INDEX over an already-populated table is a full table read plus a
+ * B-tree write — ~8 s on the 2 GB production symbol DB. node:sqlite is
+ * synchronous, so running that on the main thread blocks the event loop for its
+ * whole duration and the MCP client (VS Code Copilot) can time the server out
+ * before it answers its first request. Running it here, on its own connection,
+ * keeps the main thread serving; WAL mode lets this write proceed alongside the
+ * main thread's readers.
+ *
+ * Spawned by XppSymbolIndex.ensureFilePathIndexes() and posts a single message:
+ *   { ok: true, elapsedMs } | { ok: false, error }
+ *
+ * The connection is NOT read-only (unlike symbolCountsWorker) — this one writes.
+ */
+export {};
+//# sourceMappingURL=buildIndexWorker.d.ts.map

package/dist/metadata/buildIndexWorker.js

@@ -0,0 +1,38 @@
+/**
+ * Index-build worker thread.
+ *
+ * CREATE INDEX over an already-populated table is a full table read plus a
+ * B-tree write — ~8 s on the 2 GB production symbol DB. node:sqlite is
+ * synchronous, so running that on the main thread blocks the event loop for its
+ * whole duration and the MCP client (VS Code Copilot) can time the server out
+ * before it answers its first request. Running it here, on its own connection,
+ * keeps the main thread serving; WAL mode lets this write proceed alongside the
+ * main thread's readers.
+ *
+ * Spawned by XppSymbolIndex.ensureFilePathIndexes() and posts a single message:
+ *   { ok: true, elapsedMs } | { ok: false, error }
+ *
+ * The connection is NOT read-only (unlike symbolCountsWorker) — this one writes.
+ */
+import { parentPort, workerData } from 'node:worker_threads';
+import Database from '../database/sqlite.js';
+const { dbPath, sql } = workerData;
+try {
+    const db = new Database(dbPath);
+    try {
+        // A WAL checkpoint racing with a main-thread reader returns SQLITE_BUSY
+        // immediately without this; the build is background work, so it can afford
+        // to wait far longer than the 5 s used elsewhere.
+        db.pragma('busy_timeout = 120000');
+        const started = Date.now();
+        db.exec(sql);
+        parentPort.postMessage({ ok: true, elapsedMs: Date.now() - started });
+    }
+    finally {
+        db.close();
+    }
+}
+catch (e) {
+    parentPort.postMessage({ ok: false, error: String(e) });
+}
+//# sourceMappingURL=buildIndexWorker.js.map

package/dist/metadata/symbolIndex.d.ts

@@ -21,6 +21,7 @@ export declare class XppSymbolIndex {
     private labelsReadPool;
     private readPoolRR;
     private dbPath;
+    private labelsDbPath;
     private symbolCountsCache;
     private symbolCountsPromise;
     private perConnStmtCache;
@@ -61,6 +62,33 @@ export declare class XppSymbolIndex {
      */
     private rowToSymbol;
     private initializeDatabase;
+    /**
+     * Index `symbols.file_path` and `labels.file_path`.
+     *
+     * Both are the lookup key of removeSymbolsByFile()/removeLabelsByFile(), which
+     * every update_symbol_index, undo_last_modification and resync runs first.
+     * Unindexed, each of those calls scans the entire table — measured on the 2 GB
+     * production DB at 319 s (the SELECT of object names) + 173 s (the DELETE) for
+     * indexing a SINGLE new object, versus 0 ms once the index exists. That is why
+     * indexing one freshly created object cost as much as a rebuild.
+     *
+     * Deliberately not part of the CREATE INDEX block above. node:sqlite is
+     * synchronous, and building this index over an already-populated production
+     * table takes ~8 s, so doing it inline would block the event loop for the whole
+     * of startup — the failure mode that makes MCP clients time out and kill the
+     * server. On an empty or small DB (a fresh build, the test suite, :memory:) the
+     * build is instant and runs here; on a large existing DB it is handed to a
+     * worker thread, and until it finishes those deletes simply stay as slow as
+     * they are today.
+     */
+    private ensureFilePathIndexes;
+    /**
+     * Build one index on a separate thread so the main event loop keeps serving.
+     * WAL mode allows the worker's write to proceed alongside main-thread readers.
+     * Best-effort: a failure leaves the index absent, which is exactly the state
+     * the server ran in before, so it is logged and never thrown.
+     */
+    private buildIndexInWorker;
     /**
      * Create FTS triggers for keeping symbols_fts in sync
      * Extracted to allow disabling during bulk inserts and re-enabling after
@@ -94,6 +122,16 @@ export declare class XppSymbolIndex {
      * even when the DB stores a different path form than the caller passed.
      * Returns the names of top-level objects that were removed (for cache invalidation).
      */
+    /**
+     * Top-level object names belonging to one model — the evidence from which a
+     * model's naming prefix is inferred (see utils/modelPrefixInference.ts).
+     *
+     * Deliberately narrow and bounded: only `name`, only root objects, capped at
+     * `limit`. Reading whole rows here would pull source snippets across the wire
+     * and turn a 450 ms lookup into a slow one. Extension objects are included on
+     * purpose — a dot-notation extension states the model's infix outright.
+     */
+    getModelObjectNames(model: string, limit?: number): string[];
     removeSymbolsByFile(filePath: string): {
         deletedCount: number;
         objectNames: string[];

package/dist/metadata/symbolIndex.js

@@ -39,6 +39,9 @@ export class XppSymbolIndex {
     // Symbol-count scans are expensive (full index scan of 1M+ rows, 30-60 s
     // cold) — memoize the result and compute it off-thread (see getSymbolCounts).
     dbPath;
+    // Needed alongside dbPath so ensureFilePathIndexes() can size the labels DB
+    // and hand its path to the background index builder.
+    labelsDbPath = ':memory:';
     symbolCountsCache = null;
     symbolCountsPromise = null;
     // Per-connection prepared-statement cache.  Prepared statements are bound to
@@ -55,6 +58,7 @@ export class XppSymbolIndex {
         // Labels live in a separate DB so the main symbol DB stays small and fast;
         // labels can be huge (20M+ rows) without affecting search performance.
         const labelPath = labelsDbPath || dbPath.replace('.db', '-labels.db');
+        this.labelsDbPath = labelPath;
         this.labelsDb = new Database(labelPath);
         // journal_mode should be set by caller (MEMORY for build, WAL for production).
         // pragma() returns a string like "wal"/"delete" — always truthy, so compare the value, not !pragma(...).
@@ -649,6 +653,95 @@ export class XppSymbolIndex {
       CREATE INDEX IF NOT EXISTS idx_md_define ON macro_defines(define_name);
       CREATE INDEX IF NOT EXISTS idx_md_model ON macro_defines(model);
     `);
+        this.ensureFilePathIndexes();
+    }
+    /**
+     * Index `symbols.file_path` and `labels.file_path`.
+     *
+     * Both are the lookup key of removeSymbolsByFile()/removeLabelsByFile(), which
+     * every update_symbol_index, undo_last_modification and resync runs first.
+     * Unindexed, each of those calls scans the entire table — measured on the 2 GB
+     * production DB at 319 s (the SELECT of object names) + 173 s (the DELETE) for
+     * indexing a SINGLE new object, versus 0 ms once the index exists. That is why
+     * indexing one freshly created object cost as much as a rebuild.
+     *
+     * Deliberately not part of the CREATE INDEX block above. node:sqlite is
+     * synchronous, and building this index over an already-populated production
+     * table takes ~8 s, so doing it inline would block the event loop for the whole
+     * of startup — the failure mode that makes MCP clients time out and kill the
+     * server. On an empty or small DB (a fresh build, the test suite, :memory:) the
+     * build is instant and runs here; on a large existing DB it is handed to a
+     * worker thread, and until it finishes those deletes simply stay as slow as
+     * they are today.
+     */
+    ensureFilePathIndexes() {
+        const missing = (db, indexName) => !db.prepare(`SELECT 1 FROM sqlite_master WHERE type = 'index' AND name = ?`).get(indexName);
+        // Size is read off the file rather than counted, because COUNT(*) on the
+        // table we are trying to speed up is itself one of the slow scans.
+        const isLarge = (dbFile) => {
+            if (dbFile === ':memory:')
+                return false;
+            try {
+                return fs.statSync(dbFile).size > 200 * 1024 * 1024;
+            }
+            catch {
+                return false;
+            }
+        };
+        const labelsPath = this.labelsDbPath;
+        const work = [];
+        if (missing(this.db, 'idx_symbols_file_path')) {
+            work.push({
+                db: this.db,
+                dbFile: this.dbPath,
+                name: 'idx_symbols_file_path',
+                sql: 'CREATE INDEX IF NOT EXISTS idx_symbols_file_path ON symbols(file_path);',
+            });
+        }
+        if (missing(this.labelsDb, 'idx_labels_file_path')) {
+            work.push({
+                db: this.labelsDb,
+                dbFile: labelsPath,
+                name: 'idx_labels_file_path',
+                sql: 'CREATE INDEX IF NOT EXISTS idx_labels_file_path ON labels(file_path);',
+            });
+        }
+        for (const item of work) {
+            if (isLarge(item.dbFile)) {
+                this.buildIndexInWorker(item.dbFile, item.sql, item.name);
+            }
+            else {
+                item.db.exec(item.sql);
+            }
+        }
+    }
+    /**
+     * Build one index on a separate thread so the main event loop keeps serving.
+     * WAL mode allows the worker's write to proceed alongside main-thread readers.
+     * Best-effort: a failure leaves the index absent, which is exactly the state
+     * the server ran in before, so it is logged and never thrown.
+     */
+    buildIndexInWorker(dbPath, sql, indexName) {
+        try {
+            const worker = new Worker(new URL('./buildIndexWorker.js', import.meta.url), {
+                workerData: { dbPath, sql, indexName },
+            });
+            // unref() so a pending index build never keeps the process alive on exit.
+            worker.unref();
+            worker.once('message', (msg) => {
+                if (msg.ok) {
+                    console.error(`[SymbolIndex] Built ${indexName} in background (${msg.elapsedMs}ms)`);
+                }
+                else {
+                    console.error(`[SymbolIndex] Background build of ${indexName} failed: ${msg.error}`);
+                }
+                void worker.terminate();
+            });
+            worker.once('error', e => console.error(`[SymbolIndex] ${indexName} worker error: ${e}`));
+        }
+        catch (e) {
+            console.error(`[SymbolIndex] Could not start ${indexName} worker: ${e}`);
+        }
     }
     /**
      * Create FTS triggers for keeping symbols_fts in sync
@@ -736,6 +829,27 @@ export class XppSymbolIndex {
      * even when the DB stores a different path form than the caller passed.
      * Returns the names of top-level objects that were removed (for cache invalidation).
      */
+    /**
+     * Top-level object names belonging to one model — the evidence from which a
+     * model's naming prefix is inferred (see utils/modelPrefixInference.ts).
+     *
+     * Deliberately narrow and bounded: only `name`, only root objects, capped at
+     * `limit`. Reading whole rows here would pull source snippets across the wire
+     * and turn a 450 ms lookup into a slow one. Extension objects are included on
+     * purpose — a dot-notation extension states the model's infix outright.
+     */
+    getModelObjectNames(model, limit = 400) {
+        if (!model)
+            return [];
+        const rows = this.getReadDb()
+            .prepare(`SELECT name FROM symbols
+         WHERE model = ?
+           AND parent_name IS NULL
+           AND type NOT IN ('method', 'field')
+         LIMIT ?`)
+            .all(model, limit);
+        return rows.map(r => r.name);
+    }
     removeSymbolsByFile(filePath) {
         const forms = this.filePathForms(filePath);
         const placeholders = forms.map(() => '?').join(', ');
@@ -2782,17 +2896,42 @@ export class XppSymbolIndex {
         }));
     }
     getApiUsagePatterns(className) {
-        // Find all methods that reference this class in their used_types.
+        // Find methods that reference this class in their used_types.
         // Cap at 20 rows — fetching source_snippet for 50+ rows on a 584K-row table causes timeout.
+        //
+        // `used_types LIKE '%name%'` was wrong on both counts. used_types is a
+        // comma-separated list of exact type names, so a substring test answered
+        // "SalesTable" with methods that only use AxSalesTable or
+        // MCRSalesTableRefRecId. And it could not use an index: LIMIT 20 only stops
+        // the scan once 20 matches exist, so a name with no matches read used_types
+        // out of all 627 K method rows — each carrying source_snippet and source in
+        // overflow pages. Measured on the 2 GB index: over 7 minutes, synchronously,
+        // which blocks the whole server until the client gives up and kills it.
+        //
+        // The FTS pre-filter makes the candidate set small (an indexed token match on
+        // source_snippet), and exact membership in the list then decides. Same
+        // measurement: 0–230 ms, with the false positives gone.
+        //
+        // The pre-filter also narrows what can be returned: a method whose
+        // used_types names the class but whose stored snippet does not mention it is
+        // no longer reported. That is acceptable here specifically — this tool
+        // exists to show usage examples, and the caller reads initialization
+        // patterns straight out of source_snippet, so a row whose snippet lacks the
+        // name has no example to contribute.
+        const safe = className.replace(/["\(\)\\]/g, '').trim();
+        if (!safe)
+            return [];
         let stmt = this.stmtCache.get('getApiUsagePatterns');
         if (!stmt) {
             stmt = this.db.prepare(`SELECT name, parent_name, method_calls, source_snippet
            FROM symbols
-          WHERE type = 'method' AND used_types LIKE ?
+          WHERE type = 'method'
+            AND id IN (SELECT rowid FROM symbols_fts WHERE symbols_fts MATCH ?)
+            AND ', ' || used_types || ', ' LIKE ? COLLATE NOCASE
           LIMIT 20`);
             this.stmtCache.set('getApiUsagePatterns', stmt);
         }
-        const methods = stmt.all(`%${className}%`);
+        const methods = stmt.all(`{source_snippet} : "${safe}"`, `%, ${className}, %`);
         if (methods.length === 0) {
             return [];
         }

package/dist/middleware/apiKeyAuth.js

@@ -13,8 +13,18 @@ import { timingSafeEqual } from 'node:crypto';
  * existing deployments keep working without changes.
  *
  * Timing-safe comparison is used to prevent timing side-channel attacks.
+ *
+ * The key is read per request rather than snapshotted at module load. ESM
+ * evaluates this module as part of the entry point's import graph, which under
+ * the old ordering happened before the configuration was loaded onto
+ * process.env — so a key set in .env or config/secrets.json read as "no key
+ * configured" and authentication silently disabled itself. src/bootstrapEnv.ts
+ * fixes that ordering; reading late means this file no longer depends on it.
  */
-const API_KEY = process.env.API_KEY?.trim();
+function configuredApiKey() {
+    const key = process.env.API_KEY?.trim();
+    return key ? key : undefined;
+}
 /** Paths that never require authentication */
 const PUBLIC_PATHS = new Set(['/', '/health']);
 /**
@@ -47,8 +57,9 @@ function extractApiKey(req) {
  * Mount BEFORE any route handlers.
  */
 export function apiKeyAuth(req, res, next) {
+    const apiKey = configuredApiKey();
     // No API_KEY configured → auth disabled, pass through
-    if (!API_KEY) {
+    if (!apiKey) {
         next();
         return;
     }
@@ -58,7 +69,7 @@ export function apiKeyAuth(req, res, next) {
         return;
     }
     const provided = extractApiKey(req);
-    if (!provided || !safeCompare(provided, API_KEY)) {
+    if (!provided || !safeCompare(provided, apiKey)) {
         res.status(401).json({
             error: 'Unauthorized',
             message: 'Missing or invalid API key. Provide it via X-Api-Key header or Authorization: Bearer <key>.',

package/dist/middleware/rateLimiter.d.ts

@@ -1,7 +1,8 @@
+import type { Request, RequestHandler } from 'express';
+export declare function generateRateLimitKey(req: Request): string;
 /**
- * General API rate limiter. Default 500 requests per 15 minutes per user
- * token (or IP as fallback) — a single chat interaction can consume 10-20
- * requests, so this stays generous. Override via RATE_LIMIT_MAX_REQUESTS.
+ * Express middleware entry point. Delegates to the limiter, constructing it on
+ * the first request so it picks up the fully loaded configuration.
  */
-export declare const apiRateLimiter: import("express-rate-limit").RateLimitRequestHandler;
+export declare const apiRateLimiter: RequestHandler;
 //# sourceMappingURL=rateLimiter.d.ts.map