d365fo-mcp 1.0.0

package/dist/utils/suggestionEngine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"suggestionEngine.d.ts","sourceRoot":"","sources":["../../src/utils/suggestionEngine.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAStD,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,UAAU,GAAG,SAAS,CAAC;IAClD,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;GAEG;AACH,wBAAgB,yBAAyB,CACvC,KAAK,EAAE,MAAM,EACb,cAAc,EAAE,MAAM,EAAE,EACxB,aAAa,EAAE,GAAG,CAAC,MAAM,EAAE,SAAS,EAAE,CAAC,EACvC,cAAc,GAAE,MAAU,GACzB,gBAAgB,EAAE,CAkBpB;AA+GD;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,WAAW,EAAE,gBAAgB,EAAE,GAAG,MAAM,CAuCzE"}

package/dist/utils/suggestionEngine.js

@@ -0,0 +1,145 @@
+/**
+ * Search Suggestion Engine
+ * Provides intelligent suggestions for failed or empty search results
+ */
+import { findFuzzyMatches, isProbableTypo, generateBroaderSearches, generateNarrowerSearches, extractRootTerm } from './fuzzyMatching.js';
+/**
+ * Generate suggestions for a failed search query
+ */
+export function generateSearchSuggestions(query, allSymbolNames, symbolsByTerm, maxSuggestions = 5) {
+    const suggestions = [];
+    const typoSuggestions = generateTypoSuggestions(query, allSymbolNames);
+    suggestions.push(...typoSuggestions);
+    const broaderSuggestions = generateBroaderSuggestions(query);
+    suggestions.push(...broaderSuggestions);
+    const narrowerSuggestions = generateNarrowerSuggestions(query);
+    suggestions.push(...narrowerSuggestions);
+    const relatedSuggestions = generateRelatedSuggestions(query, symbolsByTerm);
+    suggestions.push(...relatedSuggestions);
+    return suggestions
+        .sort((a, b) => b.confidence - a.confidence)
+        .slice(0, maxSuggestions);
+}
+/**
+ * Generate typo correction suggestions
+ */
+function generateTypoSuggestions(query, allSymbolNames) {
+    const suggestions = [];
+    const matches = findFuzzyMatches(query, allSymbolNames, 0.7, 5);
+    for (const match of matches) {
+        const isTypo = isProbableTypo(query, match.term, match.score);
+        suggestions.push({
+            type: 'typo',
+            query: match.term,
+            reason: isTypo
+                ? `Did you mean "${match.term}"?`
+                : `Similar term: "${match.term}" (${Math.round(match.score * 100)}% match)`,
+            confidence: match.score
+        });
+    }
+    return suggestions;
+}
+/**
+ * Generate broader search suggestions
+ */
+function generateBroaderSuggestions(query) {
+    const suggestions = [];
+    const broaderSearches = generateBroaderSearches(query);
+    for (const broaderQuery of broaderSearches) {
+        const isWildcard = broaderQuery.endsWith('*');
+        suggestions.push({
+            type: 'broader',
+            query: broaderQuery,
+            reason: isWildcard
+                ? `Try wildcard search for "${broaderQuery.slice(0, -1)}" prefix`
+                : `Try broader search without suffix`,
+            confidence: isWildcard ? 0.6 : 0.7
+        });
+    }
+    return suggestions;
+}
+/**
+ * Generate narrower search suggestions
+ */
+function generateNarrowerSuggestions(query) {
+    const suggestions = [];
+    const narrowerSearches = generateNarrowerSearches(query);
+    // Only suggest the most common suffixes
+    const topSuffixes = ['Helper', 'Service', 'Manager'];
+    for (const narrowerQuery of narrowerSearches) {
+        const suffix = narrowerQuery.replace(query, '');
+        if (topSuffixes.includes(suffix)) {
+            suggestions.push({
+                type: 'narrower',
+                query: narrowerQuery,
+                reason: `Try with common suffix "${suffix}"`,
+                confidence: 0.65
+            });
+        }
+    }
+    return suggestions;
+}
+/**
+ * Generate related term suggestions based on usage patterns
+ */
+function generateRelatedSuggestions(query, symbolsByTerm) {
+    const suggestions = [];
+    const rootTerm = extractRootTerm(query);
+    const relatedTerms = new Set();
+    for (const [term, _symbols] of symbolsByTerm) {
+        const termRoot = extractRootTerm(term);
+        if (termRoot.toLowerCase().includes(rootTerm.toLowerCase()) ||
+            rootTerm.toLowerCase().includes(termRoot.toLowerCase())) {
+            if (term.toLowerCase() !== query.toLowerCase()) {
+                relatedTerms.add(term);
+            }
+        }
+    }
+    for (const term of Array.from(relatedTerms).slice(0, 3)) {
+        suggestions.push({
+            type: 'related',
+            query: term,
+            reason: `Related term with similar root`,
+            confidence: 0.6
+        });
+    }
+    return suggestions;
+}
+/**
+ * Format suggestions for display
+ */
+export function formatSuggestions(suggestions) {
+    if (suggestions.length === 0)
+        return '';
+    const lines = [];
+    const typoSuggestions = suggestions.filter(s => s.type === 'typo');
+    const broaderSuggestions = suggestions.filter(s => s.type === 'broader');
+    const narrowerSuggestions = suggestions.filter(s => s.type === 'narrower');
+    const relatedSuggestions = suggestions.filter(s => s.type === 'related');
+    if (typoSuggestions.length > 0) {
+        lines.push('\n### 🔍 Did you mean?');
+        typoSuggestions.forEach(s => {
+            lines.push(`• **"${s.query}"** - ${s.reason}`);
+        });
+    }
+    if (broaderSuggestions.length > 0) {
+        lines.push('\n### 🔎 Try broader search');
+        broaderSuggestions.forEach(s => {
+            lines.push(`• **"${s.query}"** - ${s.reason}`);
+        });
+    }
+    if (narrowerSuggestions.length > 0) {
+        lines.push('\n### 🎯 Try narrower search');
+        narrowerSuggestions.forEach(s => {
+            lines.push(`• **"${s.query}"** - ${s.reason}`);
+        });
+    }
+    if (relatedSuggestions.length > 0) {
+        lines.push('\n### 🔗 Related terms');
+        relatedSuggestions.forEach(s => {
+            lines.push(`• **"${s.query}"** - ${s.reason}`);
+        });
+    }
+    return lines.join('\n');
+}
+//# sourceMappingURL=suggestionEngine.js.map

package/dist/utils/suggestionEngine.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"suggestionEngine.js","sourceRoot":"","sources":["../../src/utils/suggestionEngine.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EACL,gBAAgB,EAChB,cAAc,EACd,uBAAuB,EACvB,wBAAwB,EACxB,eAAe,EAChB,MAAM,oBAAoB,CAAC;AAS5B;;GAEG;AACH,MAAM,UAAU,yBAAyB,CACvC,KAAa,EACb,cAAwB,EACxB,aAAuC,EACvC,cAAc,GAAW,CAAC;IAE1B,MAAM,WAAW,GAAuB,EAAE,CAAC;IAE3C,MAAM,eAAe,GAAG,uBAAuB,CAAC,KAAK,EAAE,cAAc,CAAC,CAAC;IACvE,WAAW,CAAC,IAAI,CAAC,GAAG,eAAe,CAAC,CAAC;IAErC,MAAM,kBAAkB,GAAG,0BAA0B,CAAC,KAAK,CAAC,CAAC;IAC7D,WAAW,CAAC,IAAI,CAAC,GAAG,kBAAkB,CAAC,CAAC;IAExC,MAAM,mBAAmB,GAAG,2BAA2B,CAAC,KAAK,CAAC,CAAC;IAC/D,WAAW,CAAC,IAAI,CAAC,GAAG,mBAAmB,CAAC,CAAC;IAEzC,MAAM,kBAAkB,GAAG,0BAA0B,CAAC,KAAK,EAAE,aAAa,CAAC,CAAC;IAC5E,WAAW,CAAC,IAAI,CAAC,GAAG,kBAAkB,CAAC,CAAC;IAExC,OAAO,WAAW;SACf,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,GAAG,CAAC,CAAC,UAAU,CAAC;SAC3C,KAAK,CAAC,CAAC,EAAE,cAAc,CAAC,CAAC;AAC9B,CAAC;AAED;;GAEG;AACH,SAAS,uBAAuB,CAC9B,KAAa,EACb,cAAwB;IAExB,MAAM,WAAW,GAAuB,EAAE,CAAC;IAC3C,MAAM,OAAO,GAAG,gBAAgB,CAAC,KAAK,EAAE,cAAc,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC;IAEhE,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;QAC5B,MAAM,MAAM,GAAG,cAAc,CAAC,KAAK,EAAE,KAAK,CAAC,IAAI,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC;QAE9D,WAAW,CAAC,IAAI,CAAC;YACf,IAAI,EAAE,MAAM;YACZ,KAAK,EAAE,KAAK,CAAC,IAAI;YACjB,MAAM,EAAE,MAAM;gBACZ,CAAC,CAAC,iBAAiB,KAAK,CAAC,IAAI,IAAI;gBACjC,CAAC,CAAC,kBAAkB,KAAK,CAAC,IAAI,MAAM,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,KAAK,GAAG,GAAG,CAAC,UAAU;YAC7E,UAAU,EAAE,KAAK,CAAC,KAAK;SACxB,CAAC,CAAC;IACL,CAAC;IAED,OAAO,WAAW,CAAC;AACrB,CAAC;AAED;;GAEG;AACH,SAAS,0BAA0B,CAAC,KAAa;IAC/C,MAAM,WAAW,GAAuB,EAAE,CAAC;IAC3C,MAAM,eAAe,GAAG,uBAAuB,CAAC,KAAK,CAAC,CAAC;IAEvD,KAAK,MAAM,YAAY,IAAI,eAAe,EAAE,CAAC;QAC3C,MAAM,UAAU,GAAG,YAAY,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC;QAE9C,WAAW,CAAC,IAAI,CAAC;YACf,IAAI,EAAE,SAAS;YACf,KAAK,EAAE,YAAY;YACnB,MAAM,EAAE,UAAU;gBAChB,CAAC,CAAC,4BAA4B,YAAY,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,UAAU;gBACjE,CAAC,CAAC,mCAAmC;YACvC,UAAU,EAAE,UAAU,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG;SACnC,CAAC,CAAC;IACL,CAAC;IAED,OAAO,WAAW,CAAC;AACrB,CAAC;AAED;;GAEG;AACH,SAAS,2BAA2B,CAAC,KAAa;IAChD,MAAM,WAAW,GAAuB,EAAE,CAAC;IAC3C,MAAM,gBAAgB,GAAG,wBAAwB,CAAC,KAAK,CAAC,CAAC;IAEzD,wCAAwC;IACxC,MAAM,WAAW,GAAG,CAAC,QAAQ,EAAE,SAAS,EAAE,SAAS,CAAC,CAAC;IAErD,KAAK,MAAM,aAAa,IAAI,gBAAgB,EAAE,CAAC;QAC7C,MAAM,MAAM,GAAG,aAAa,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;QAEhD,IAAI,WAAW,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC;YACjC,WAAW,CAAC,IAAI,CAAC;gBACf,IAAI,EAAE,UAAU;gBAChB,KAAK,EAAE,aAAa;gBACpB,MAAM,EAAE,2BAA2B,MAAM,GAAG;gBAC5C,UAAU,EAAE,IAAI;aACjB,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IAED,OAAO,WAAW,CAAC;AACrB,CAAC;AAED;;GAEG;AACH,SAAS,0BAA0B,CACjC,KAAa,EACb,aAAuC;IAEvC,MAAM,WAAW,GAAuB,EAAE,CAAC;IAC3C,MAAM,QAAQ,GAAG,eAAe,CAAC,KAAK,CAAC,CAAC;IACxC,MAAM,YAAY,GAAG,IAAI,GAAG,EAAU,CAAC;IAEvC,KAAK,MAAM,CAAC,IAAI,EAAE,QAAQ,CAAC,IAAI,aAAa,EAAE,CAAC;QAC7C,MAAM,QAAQ,GAAG,eAAe,CAAC,IAAI,CAAC,CAAC;QAEvC,IAAI,QAAQ,CAAC,WAAW,EAAE,CAAC,QAAQ,CAAC,QAAQ,CAAC,WAAW,EAAE,CAAC;YACvD,QAAQ,CAAC,WAAW,EAAE,CAAC,QAAQ,CAAC,QAAQ,CAAC,WAAW,EAAE,CAAC,EAAE,CAAC;YAC5D,IAAI,IAAI,CAAC,WAAW,EAAE,KAAK,KAAK,CAAC,WAAW,EAAE,EAAE,CAAC;gBAC/C,YAAY,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;YACzB,CAAC;QACH,CAAC;IACH,CAAC;IAED,KAAK,MAAM,IAAI,IAAI,KAAK,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC;QACxD,WAAW,CAAC,IAAI,CAAC;YACf,IAAI,EAAE,SAAS;YACf,KAAK,EAAE,IAAI;YACX,MAAM,EAAE,gCAAgC;YACxC,UAAU,EAAE,GAAG;SAChB,CAAC,CAAC;IACL,CAAC;IAED,OAAO,WAAW,CAAC;AACrB,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,iBAAiB,CAAC,WAA+B;IAC/D,IAAI,WAAW,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IAExC,MAAM,KAAK,GAAa,EAAE,CAAC;IAE3B,MAAM,eAAe,GAAG,WAAW,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,MAAM,CAAC,CAAC;IACnE,MAAM,kBAAkB,GAAG,WAAW,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC;IACzE,MAAM,mBAAmB,GAAG,WAAW,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,UAAU,CAAC,CAAC;IAC3E,MAAM,kBAAkB,GAAG,WAAW,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC;IAEzE,IAAI,eAAe,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC/B,KAAK,CAAC,IAAI,CAAC,wBAAwB,CAAC,CAAC;QACrC,eAAe,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE;YAC1B,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,KAAK,SAAS,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC;QACjD,CAAC,CAAC,CAAC;IACL,CAAC;IAED,IAAI,kBAAkB,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAClC,KAAK,CAAC,IAAI,CAAC,6BAA6B,CAAC,CAAC;QAC1C,kBAAkB,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE;YAC7B,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,KAAK,SAAS,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC;QACjD,CAAC,CAAC,CAAC;IACL,CAAC;IAED,IAAI,mBAAmB,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACnC,KAAK,CAAC,IAAI,CAAC,8BAA8B,CAAC,CAAC;QAC3C,mBAAmB,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE;YAC9B,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,KAAK,SAAS,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC;QACjD,CAAC,CAAC,CAAC;IACL,CAAC;IAED,IAAI,kBAAkB,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAClC,KAAK,CAAC,IAAI,CAAC,wBAAwB,CAAC,CAAC;QACrC,kBAAkB,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE;YAC7B,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,KAAK,SAAS,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC;QACjD,CAAC,CAAC,CAAC;IACL,CAAC;IAED,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC"}

package/dist/utils/symbolLookup.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Index-safe case-insensitive symbol lookups.
+ *
+ * `name = ? COLLATE NOCASE` cannot use the BINARY-collated name indexes and
+ * degrades to a scan of the 1.17M-row symbols table — 13–180 s on a
+ * production-size DB with a cold file cache. better-sqlite3 is synchronous,
+ * so that scan blocks the event loop until MCP clients time out and kill the
+ * server.
+ *
+ * Pattern (proven in prepare, d93f004): exact-case probe on idx_name_type
+ * (sub-ms) first, FTS5 phrase match (case-folded by the tokenizer) as the
+ * fallback for differently-cased input. The FTS candidates are re-checked
+ * with `COLLATE NOCASE`, so FTS can only narrow the result, never widen it.
+ *
+ * `COLLATE NOCASE` stays acceptable only inside an already-narrow indexed
+ * range — e.g. `WHERE parent_name = ? AND type = ? AND name = ? COLLATE
+ * NOCASE` after the parent name has been canonicalized through one of these
+ * lookups.
+ */
+/** Minimal DB surface these helpers need — satisfied by better-sqlite3. */
+export interface DbLike {
+    prepare(sql: string): {
+        get(...params: unknown[]): unknown;
+        all(...params: unknown[]): unknown[];
+    };
+}
+export interface SymbolHit {
+    name: string;
+    type: string;
+    model: string | null;
+    extends_class: string | null;
+    file_path: string | null;
+}
+/** Quote a name as an FTS5 phrase (strips embedded double quotes). */
+export declare function ftsPhrase(name: string): string;
+/**
+ * Case-insensitive lookup of top-level symbols (parent_name IS NULL) by name,
+ * optionally scoped to a set of types. Exact-case rows come first; rows with
+ * different casing are found through the FTS fallback and deduplicated.
+ */
+export declare function lookupSymbolsNocase(db: DbLike, name: string, opts?: {
+    types?: readonly string[];
+    limit?: number;
+}): SymbolHit[];
+/** First case-insensitive top-level hit for a name, or undefined. */
+export declare function lookupSymbolNocase(db: DbLike, name: string, types?: readonly string[]): SymbolHit | undefined;
+/**
+ * Canonical (as-indexed) casing of a top-level object name, or undefined when
+ * the name is not in the index. Use this to canonicalize a user-supplied name
+ * once, so follow-up probes on parent_name/base_object_name stay BINARY and
+ * on-index.
+ */
+export declare function canonicalSymbolName(db: DbLike, name: string, types?: readonly string[]): string | undefined;
+/**
+ * All DISTINCT symbol types recorded for a name under any casing and any
+ * parent (methods and fields included) — index-safe replacement for
+ * `SELECT DISTINCT type FROM symbols WHERE name = ? COLLATE NOCASE`.
+ */
+export declare function distinctSymbolTypesNocase(db: DbLike, name: string, limit?: number): string[];
+//# sourceMappingURL=symbolLookup.d.ts.map

package/dist/utils/symbolLookup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"symbolLookup.d.ts","sourceRoot":"","sources":["../../src/utils/symbolLookup.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,2EAA2E;AAC3E,MAAM,WAAW,MAAM;IACrB,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG;QACpB,GAAG,CAAC,GAAG,MAAM,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC;QACnC,GAAG,CAAC,GAAG,MAAM,EAAE,OAAO,EAAE,GAAG,OAAO,EAAE,CAAC;KACtC,CAAC;CACH;AAED,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B;AAED,sEAAsE;AACtE,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE9C;AAYD;;;;GAIG;AACH,wBAAgB,mBAAmB,CACjC,EAAE,EAAE,MAAM,EACV,IAAI,EAAE,MAAM,EACZ,IAAI,GAAE;IAAE,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAO,GACvD,SAAS,EAAE,CA6Bb;AAED,qEAAqE;AACrE,wBAAgB,kBAAkB,CAChC,EAAE,EAAE,MAAM,EACV,IAAI,EAAE,MAAM,EACZ,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,GACxB,SAAS,GAAG,SAAS,CAEvB;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CACjC,EAAE,EAAE,MAAM,EACV,IAAI,EAAE,MAAM,EACZ,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,GACxB,MAAM,GAAG,SAAS,CAEpB;AAED;;;;GAIG;AACH,wBAAgB,yBAAyB,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,SAAK,GAAG,MAAM,EAAE,CAsBxF"}

package/dist/utils/symbolLookup.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"symbolLookup.js","sourceRoot":"","sources":["../../src/utils/symbolLookup.ts"],"names":[],"mappings":"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"}

package/dist/utils/terminalUi.d.ts

@@ -0,0 +1,85 @@
+/**
+ * terminalUi — capability-aware console formatting for the dev/HTTP startup banner.
+ *
+ * Legacy Windows terminals (PowerShell 5.1/conhost) render UTF-8 emoji as
+ * mojibake, so we detect Unicode-capable terminals and fall back to ASCII
+ * glyphs ([OK]/[!]/-> instead of ✓/⚠/›) elsewhere. ANSI colour is likewise
+ * disabled for pipes, NO_COLOR, and dumb terminals.
+ */
+/**
+ * Whether the terminal reliably renders Unicode (box-drawing + emoji).
+ * On Windows only modern hosts qualify. Honour FORCE_UNICODE=1/0 as an override.
+ */
+export declare const supportsUnicode: boolean;
+/**
+ * Whether to emit ANSI colour codes. Disabled for non-TTY (pipes/redirects),
+ * NO_COLOR, and dumb terminals; FORCE_COLOR=1 forces it on.
+ */
+export declare const supportsColor: boolean;
+export declare const c: {
+    bold: (s: string) => string;
+    dim: (s: string) => string;
+    red: (s: string) => string;
+    green: (s: string) => string;
+    yellow: (s: string) => string;
+    blue: (s: string) => string;
+    magenta: (s: string) => string;
+    cyan: (s: string) => string;
+    gray: (s: string) => string;
+};
+export declare const glyph: {
+    tl: string;
+    tr: string;
+    bl: string;
+    br: string;
+    h: string;
+    v: string;
+    dot: string;
+    ok: string;
+    warn: string;
+    err: string;
+    info: string;
+    arrow: string;
+    bullet: string;
+    ellipsis: string;
+};
+/** Replace/strip emoji & fancy punctuation so legacy code pages don't show mojibake. No-op on Unicode terminals. */
+export declare function sanitize(text: string): string;
+/** Visible length of a string, ignoring ANSI colour codes. */
+export declare function visibleLen(s: string): number;
+/**
+ * Draw a rounded box around the given rows. Each row is a pre-styled string;
+ * width is derived from the widest visible row (min `minWidth`), capped sensibly.
+ */
+export declare function box(rows: string[], minWidth?: number): string[];
+/** Build a left/right justified line of total visible `width`. */
+export declare function spread(left: string, right: string, width: number): string;
+/** A `label  value` row with the label dimmed and padded to `labelWidth`. */
+export declare function kv(label: string, value: string, labelWidth?: number): string;
+/** A section header (uppercased, accented). */
+export declare function sectionTitle(title: string): string;
+/** A status line such as "✓ Ready in 3.2s". `kind` picks the glyph + colour. */
+export declare function statusLine(kind: 'step' | 'ok' | 'warn' | 'err' | 'info', msg: string): string;
+/** Warnings emitted during startup, collected for an end-of-startup summary. */
+export declare const startupWarnings: string[];
+/**
+ * Convenience status loggers for the startup sequence. Resolve console.*
+ * lazily at call time so stdio/HTTP overrides installed in main() apply.
+ *  - step/ok/info → stdout (suppressed in stdio mode)
+ *  - warn/err     → stderr (kept visible to MCP clients in stdio mode)
+ *  - detail       → dimmed, indented sub-line under the preceding status
+ */
+export declare const log: {
+    step: (msg: string) => void;
+    ok: (msg: string) => void;
+    info: (msg: string) => void;
+    warn: (msg: string) => void;
+    err: (msg: string) => void;
+    detail: (msg: string) => void;
+};
+/**
+ * Render a path relative to `cwd` (prefixed with "./") when it lives under it,
+ * otherwise return the absolute path unchanged. Keeps long startup paths short.
+ */
+export declare function shortPath(p: string, cwd?: string): string;
+//# sourceMappingURL=terminalUi.d.ts.map

package/dist/utils/terminalUi.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"terminalUi.d.ts","sourceRoot":"","sources":["../../src/utils/terminalUi.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAMH;;;GAGG;AACH,eAAO,MAAM,eAAe,EAAE,OAW1B,CAAC;AAEL;;;GAGG;AACH,eAAO,MAAM,aAAa,EAAE,OAKxB,CAAC;AAML,eAAO,MAAM,CAAC;IACZ,IAAI,MAJ4C,MAAM,KAAG,MAAM;IAK/D,GAAG;IACH,GAAG;IACH,KAAK;IACL,MAAM;IACN,IAAI;IACJ,OAAO;IACP,IAAI;IACJ,IAAI;CACL,CAAC;AAIF,eAAO,MAAM,KAAK;;;;;;;;;;;;;;;CAejB,CAAC;AA6BF,oHAAoH;AACpH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAO7C;AAKD,8DAA8D;AAC9D,wBAAgB,UAAU,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAE5C;AAQD;;;GAGG;AACH,wBAAgB,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,QAAQ,SAAK,GAAG,MAAM,EAAE,CAQ3D;AAED,kEAAkE;AAClE,wBAAgB,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAGzE;AAED,6EAA6E;AAC7E,wBAAgB,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,UAAU,SAAI,GAAG,MAAM,CAEvE;AAED,+CAA+C;AAC/C,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAElD;AAED,gFAAgF;AAChF,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,GAAG,KAAK,GAAG,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAU7F;AAED,gFAAgF;AAChF,eAAO,MAAM,eAAe,EAAE,MAAM,EAAO,CAAC;AAE5C;;;;;;GAMG;AACH,eAAO,MAAM,GAAG;IACd,IAAI,QAAQ,MAAM,KAAG,IAAI;IACzB,EAAE,QAAQ,MAAM,KAAG,IAAI;IACvB,IAAI,QAAQ,MAAM,KAAG,IAAI;IACzB,IAAI,QAAQ,MAAM,KAAG,IAAI;IACzB,GAAG,QAAQ,MAAM,KAAG,IAAI;IACxB,MAAM,QAAQ,MAAM,KAAG,IAAI;CAC5B,CAAC;AAEF;;;GAGG;AACH,wBAAgB,SAAS,CAAC,CAAC,EAAE,MAAM,EAAE,GAAG,SAAgB,GAAG,MAAM,CAGhE"}

package/dist/utils/terminalUi.js

@@ -0,0 +1,182 @@
+/**
+ * terminalUi — capability-aware console formatting for the dev/HTTP startup banner.
+ *
+ * Legacy Windows terminals (PowerShell 5.1/conhost) render UTF-8 emoji as
+ * mojibake, so we detect Unicode-capable terminals and fall back to ASCII
+ * glyphs ([OK]/[!]/-> instead of ✓/⚠/›) elsewhere. ANSI colour is likewise
+ * disabled for pipes, NO_COLOR, and dumb terminals.
+ */
+import { relative, isAbsolute, sep } from 'path';
+const isWin = process.platform === 'win32';
+/**
+ * Whether the terminal reliably renders Unicode (box-drawing + emoji).
+ * On Windows only modern hosts qualify. Honour FORCE_UNICODE=1/0 as an override.
+ */
+export const supportsUnicode = (() => {
+    if (process.env.FORCE_UNICODE === '1')
+        return true;
+    if (process.env.FORCE_UNICODE === '0')
+        return false;
+    if (!isWin)
+        return process.env.TERM !== 'linux';
+    return (Boolean(process.env.WT_SESSION) || // Windows Terminal
+        process.env.TERM_PROGRAM === 'vscode' ||
+        Boolean(process.env.ConEmuTask) || // ConEmu / Cmder
+        process.env.TERM === 'xterm-256color' ||
+        process.env.WSLENV !== undefined // WSL interop
+    );
+})();
+/**
+ * Whether to emit ANSI colour codes. Disabled for non-TTY (pipes/redirects),
+ * NO_COLOR, and dumb terminals; FORCE_COLOR=1 forces it on.
+ */
+export const supportsColor = (() => {
+    if (process.env.FORCE_COLOR && process.env.FORCE_COLOR !== '0')
+        return true;
+    if ('NO_COLOR' in process.env)
+        return false;
+    if (process.env.TERM === 'dumb')
+        return false;
+    return Boolean(process.stdout.isTTY);
+})();
+// Colour helpers
+const wrap = (open, close) => (s) => supportsColor ? `\x1b[${open}m${s}\x1b[${close}m` : s;
+export const c = {
+    bold: wrap(1, 22),
+    dim: wrap(2, 22),
+    red: wrap(31, 39),
+    green: wrap(32, 39),
+    yellow: wrap(33, 39),
+    blue: wrap(34, 39),
+    magenta: wrap(35, 39),
+    cyan: wrap(36, 39),
+    gray: wrap(90, 39),
+};
+// Glyphs (Unicode with ASCII fallback)
+const U = supportsUnicode;
+export const glyph = {
+    tl: U ? '╭' : '+',
+    tr: U ? '╮' : '+',
+    bl: U ? '╰' : '+',
+    br: U ? '╯' : '+',
+    h: U ? '─' : '-',
+    v: U ? '│' : '|',
+    dot: U ? '·' : '-',
+    ok: U ? '✓' : 'OK',
+    warn: U ? '▲' : '!',
+    err: U ? '✗' : 'x',
+    info: U ? 'ℹ' : 'i',
+    arrow: U ? '›' : '>',
+    bullet: U ? '•' : '*',
+    ellipsis: U ? '…' : '...',
+};
+// Emoji -> ASCII sanitiser. Maps semantic emoji to short ASCII tags, then strips
+// remaining decorative emoji + variation selectors. No-op when Unicode is supported.
+// Trailing space (if any) is preserved so "✅ Loaded" becomes "[OK] Loaded".
+const EMOJI_TAGS = [
+    [/✅|✔️?/g, '[OK]'],
+    [/❌/g, '[X]'],
+    [/⚠️?/g, '[!]'],
+    [/ℹ️?/g, '[i]'],
+    [/⏭️?/g, '[skip]'],
+];
+// Decorative emoji / pictographs (+ variation selector & ZWJ) plus any spaces
+// immediately following them, so real indentation is preserved after stripping.
+const EMOJI_STRIP = /(?:[\u{1F000}-\u{1FAFF}\u{2600}-\u{27BF}\u{2B00}-\u{2BFF}\u{FE0F}\u{200D}\u{2190}-\u{21FF}\u{2300}-\u{23FF}])+ */gu;
+// Fancy punctuation that also mojibakes on legacy code pages (cp852/cp1250); transliterate to plain ASCII.
+const PUNCT_MAP = [
+    [/[—–‒―]/g, '-'],
+    [/…/g, '...'],
+    [/[·•]/g, '-'],
+    [/[‘’‛]/g, "'"],
+    [/[“”‟]/g, '"'],
+    [/[‹›]/g, '>'],
+    [/→/g, '->'],
+    [/×/g, 'x'],
+    [/ /g, ' '], // non-breaking space
+];
+/** Replace/strip emoji & fancy punctuation so legacy code pages don't show mojibake. No-op on Unicode terminals. */
+export function sanitize(text) {
+    if (supportsUnicode)
+        return text;
+    let out = text;
+    for (const [re, tag] of EMOJI_TAGS)
+        out = out.replace(re, tag);
+    out = out.replace(EMOJI_STRIP, '');
+    for (const [re, rep] of PUNCT_MAP)
+        out = out.replace(re, rep);
+    return out;
+}
+// Layout helpers
+const ANSI_RE = /\x1b\[[0-9;]*m/g;
+/** Visible length of a string, ignoring ANSI colour codes. */
+export function visibleLen(s) {
+    return s.replace(ANSI_RE, '').length;
+}
+/** Pad `s` (accounting for ANSI codes) with spaces to `width` on the right. */
+function padEndVisible(s, width) {
+    const pad = width - visibleLen(s);
+    return pad > 0 ? s + ' '.repeat(pad) : s;
+}
+/**
+ * Draw a rounded box around the given rows. Each row is a pre-styled string;
+ * width is derived from the widest visible row (min `minWidth`), capped sensibly.
+ */
+export function box(rows, minWidth = 48) {
+    const inner = Math.max(minWidth, ...rows.map(visibleLen));
+    const top = c.gray(glyph.tl + glyph.h.repeat(inner + 2) + glyph.tr);
+    const bottom = c.gray(glyph.bl + glyph.h.repeat(inner + 2) + glyph.br);
+    const body = rows.map((r) => c.gray(glyph.v) + ' ' + padEndVisible(r, inner) + ' ' + c.gray(glyph.v));
+    return [top, ...body, bottom];
+}
+/** Build a left/right justified line of total visible `width`. */
+export function spread(left, right, width) {
+    const gap = Math.max(1, width - visibleLen(left) - visibleLen(right));
+    return left + ' '.repeat(gap) + right;
+}
+/** A `label  value` row with the label dimmed and padded to `labelWidth`. */
+export function kv(label, value, labelWidth = 9) {
+    return '  ' + c.dim(padEndVisible(label, labelWidth)) + value;
+}
+/** A section header (uppercased, accented). */
+export function sectionTitle(title) {
+    return '  ' + c.bold(c.cyan(title.toUpperCase()));
+}
+/** A status line such as "✓ Ready in 3.2s". `kind` picks the glyph + colour. */
+export function statusLine(kind, msg) {
+    const map = {
+        step: [glyph.arrow, c.cyan],
+        ok: [glyph.ok, c.green],
+        warn: [glyph.warn, c.yellow],
+        err: [glyph.err, c.red],
+        info: [glyph.info, c.gray],
+    };
+    const [g, paint] = map[kind];
+    return '  ' + paint(g) + ' ' + msg;
+}
+/** Warnings emitted during startup, collected for an end-of-startup summary. */
+export const startupWarnings = [];
+/**
+ * Convenience status loggers for the startup sequence. Resolve console.*
+ * lazily at call time so stdio/HTTP overrides installed in main() apply.
+ *  - step/ok/info → stdout (suppressed in stdio mode)
+ *  - warn/err     → stderr (kept visible to MCP clients in stdio mode)
+ *  - detail       → dimmed, indented sub-line under the preceding status
+ */
+export const log = {
+    step: (msg) => console.log(statusLine('step', msg)),
+    ok: (msg) => console.log(statusLine('ok', msg)),
+    info: (msg) => console.log(statusLine('info', msg)),
+    warn: (msg) => { startupWarnings.push(msg); console.error(statusLine('warn', msg)); },
+    err: (msg) => console.error(statusLine('err', msg)),
+    detail: (msg) => console.log('      ' + c.dim(msg)),
+};
+/**
+ * Render a path relative to `cwd` (prefixed with "./") when it lives under it,
+ * otherwise return the absolute path unchanged. Keeps long startup paths short.
+ */
+export function shortPath(p, cwd = process.cwd()) {
+    const rel = relative(cwd, p);
+    return rel && !rel.startsWith('..') && !isAbsolute(rel) ? '.' + sep + rel : p;
+}
+//# sourceMappingURL=terminalUi.js.map

package/dist/utils/terminalUi.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"terminalUi.js","sourceRoot":"","sources":["../../src/utils/terminalUi.ts"],"names":[],"mappings":"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"}

package/dist/utils/toolMetrics.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Lightweight in-memory tool usage metrics.
+ *
+ * Tracks per-tool call counts, total latency, and empty-result counts.
+ * Stats are logged to stderr periodically and exposed via getMetricsSnapshot().
+ * All state is in-process only — resets on server restart.
+ */
+/** Call before dispatching a tool. Returns a finish() callback. */
+export declare function recordToolStart(toolName: string): (isEmpty: boolean) => void;
+/**
+ * Record a call in the sequence buffer and return the number of occurrences
+ * of this exact tool+args combination within the recent window (including
+ * the call just recorded). 1 = first occurrence, 3+ = likely loop.
+ */
+export declare function recordCallSequence(toolName: string, argsKey: string): number;
+/** Test/maintenance helper — clears the sequence buffer. */
+export declare function resetCallSequence(): void;
+/** Returns a snapshot of current metrics sorted by call count descending. */
+export declare function getMetricsSnapshot(): Array<{
+    tool: string;
+    calls: number;
+    avgLatencyMs: number;
+    emptyRatio: number;
+    duplicateCalls: number;
+}>;
+/**
+ * Start periodic logging of metrics to stderr.
+ * Safe to call multiple times — only the first call starts the interval.
+ * @param intervalMs default 5 minutes
+ */
+export declare function startMetricsLogging(intervalMs?: number): void;
+//# sourceMappingURL=toolMetrics.d.ts.map

package/dist/utils/toolMetrics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"toolMetrics.d.ts","sourceRoot":"","sources":["../../src/utils/toolMetrics.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAuBH,mEAAmE;AACnE,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,CAAC,OAAO,EAAE,OAAO,KAAK,IAAI,CAS5E;AAiBD;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAS5E;AAED,4DAA4D;AAC5D,wBAAgB,iBAAiB,IAAI,IAAI,CAExC;AAED,6EAA6E;AAC7E,wBAAgB,kBAAkB,IAAI,KAAK,CAAC;IAC1C,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;IACnB,cAAc,EAAE,MAAM,CAAC;CACxB,CAAC,CAUD;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,UAAU,SAAgB,GAAG,IAAI,CAepE"}

package/dist/utils/toolMetrics.js

@@ -0,0 +1,89 @@
+/**
+ * Lightweight in-memory tool usage metrics.
+ *
+ * Tracks per-tool call counts, total latency, and empty-result counts.
+ * Stats are logged to stderr periodically and exposed via getMetricsSnapshot().
+ * All state is in-process only — resets on server restart.
+ */
+const stats = new Map();
+let logIntervalHandle = null;
+function getStats(toolName) {
+    let s = stats.get(toolName);
+    if (!s) {
+        s = { calls: 0, totalLatencyMs: 0, emptyResults: 0, duplicateCalls: 0 };
+        stats.set(toolName, s);
+    }
+    return s;
+}
+/** Call before dispatching a tool. Returns a finish() callback. */
+export function recordToolStart(toolName) {
+    const t0 = Date.now();
+    return (isEmpty) => {
+        const elapsed = Date.now() - t0;
+        const s = getStats(toolName);
+        s.calls++;
+        s.totalLatencyMs += elapsed;
+        if (isEmpty)
+            s.emptyResults++;
+    };
+}
+// Call-sequence tracking (agentic-loop detection): a ring buffer of recent
+// tool calls (tool + args hash). recordCallSequence returns how many times an
+// exact call appeared in the recent window so callers can flag likely loops.
+const SEQUENCE_WINDOW = 15;
+const SEQUENCE_BUFFER_MAX = 30;
+const recentCalls = [];
+/**
+ * Record a call in the sequence buffer and return the number of occurrences
+ * of this exact tool+args combination within the recent window (including
+ * the call just recorded). 1 = first occurrence, 3+ = likely loop.
+ */
+export function recordCallSequence(toolName, argsKey) {
+    recentCalls.push({ tool: toolName, argsKey, at: Date.now() });
+    if (recentCalls.length > SEQUENCE_BUFFER_MAX) {
+        recentCalls.splice(0, recentCalls.length - SEQUENCE_BUFFER_MAX);
+    }
+    const window = recentCalls.slice(-SEQUENCE_WINDOW);
+    const occurrences = window.filter(e => e.tool === toolName && e.argsKey === argsKey).length;
+    if (occurrences > 1)
+        getStats(toolName).duplicateCalls++;
+    return occurrences;
+}
+/** Test/maintenance helper — clears the sequence buffer. */
+export function resetCallSequence() {
+    recentCalls.length = 0;
+}
+/** Returns a snapshot of current metrics sorted by call count descending. */
+export function getMetricsSnapshot() {
+    return Array.from(stats.entries())
+        .map(([tool, s]) => ({
+        tool,
+        calls: s.calls,
+        avgLatencyMs: s.calls > 0 ? Math.round(s.totalLatencyMs / s.calls) : 0,
+        emptyRatio: s.calls > 0 ? Math.round((s.emptyResults / s.calls) * 100) / 100 : 0,
+        duplicateCalls: s.duplicateCalls,
+    }))
+        .sort((a, b) => b.calls - a.calls);
+}
+/**
+ * Start periodic logging of metrics to stderr.
+ * Safe to call multiple times — only the first call starts the interval.
+ * @param intervalMs default 5 minutes
+ */
+export function startMetricsLogging(intervalMs = 5 * 60 * 1000) {
+    if (logIntervalHandle)
+        return;
+    logIntervalHandle = setInterval(() => {
+        const snapshot = getMetricsSnapshot();
+        if (snapshot.length === 0)
+            return;
+        const top10 = snapshot.slice(0, 10);
+        const lines = top10.map(r => `  ${r.tool.padEnd(40)} calls=${r.calls}  avgMs=${r.avgLatencyMs}  emptyRatio=${r.emptyRatio}`);
+        console.error('[metrics] Tool usage (top 10 by calls):\n' + lines.join('\n'));
+    }, intervalMs);
+    // Don't prevent Node from exiting
+    if (logIntervalHandle && typeof logIntervalHandle === 'object' && 'unref' in logIntervalHandle) {
+        logIntervalHandle.unref();
+    }
+}
+//# sourceMappingURL=toolMetrics.js.map