@castandcrew/spotlight-mcp 0.1.3 → 0.1.4

package/dist/data/health.d.ts

@@ -0,0 +1,33 @@
+import { type IndexCollection } from './loader.js';
+/**
+ * Collections that must be non-empty for the index to be considered healthy.
+ *
+ * `deprecated` is deliberately excluded: it is 0 in a *healthy* index too, because
+ * it is derived from components.filter(status === 'deprecated') and nothing is
+ * deprecated today. Guarding on it would break a working tool. Tools that read
+ * `deprecated` guard on `components` instead — that is what distinguishes a
+ * truthful "nothing is deprecated" from an empty index pretending to be one.
+ */
+export declare const REQUIRED_COLLECTIONS: readonly ["components", "patterns", "tokens", "rules", "migration", "utilityClasses"];
+export type IndexCounts = Record<IndexCollection, number>;
+export interface IndexHealth {
+    indexPath: string;
+    version: string;
+    generated: string;
+    counts: IndexCounts;
+    /** Required collections that are empty. */
+    empty: IndexCollection[];
+    status: 'ok' | 'degraded';
+    /** Set only when the index could not be loaded at all. */
+    fatal?: string;
+}
+export declare function getIndexHealth(): IndexHealth;
+/**
+ * The remedy branches on where the index came from: `pnpm index` is not runnable
+ * from the published tarball (package.json files is ["dist","data"]), so the
+ * generic advice would be a dead end for exactly the users who hit an empty
+ * published index.
+ */
+export declare function remedyFor(indexPath: string): string;
+/** Multi-line stderr banner. Printed at startup in both transports. */
+export declare function formatBanner(health: IndexHealth, packageVersion: string): string;

package/dist/data/health.js

@@ -0,0 +1,111 @@
+import { loadIndex, resolveIndexPath, IndexUnusableError, INDEX_COLLECTIONS, } from './loader.js';
+/**
+ * Collections that must be non-empty for the index to be considered healthy.
+ *
+ * `deprecated` is deliberately excluded: it is 0 in a *healthy* index too, because
+ * it is derived from components.filter(status === 'deprecated') and nothing is
+ * deprecated today. Guarding on it would break a working tool. Tools that read
+ * `deprecated` guard on `components` instead — that is what distinguishes a
+ * truthful "nothing is deprecated" from an empty index pretending to be one.
+ */
+export const REQUIRED_COLLECTIONS = [
+    'components',
+    'patterns',
+    'tokens',
+    'rules',
+    'migration',
+    'utilityClasses',
+];
+export function getIndexHealth() {
+    const indexPath = resolveIndexPath();
+    try {
+        const index = loadIndex();
+        const counts = Object.fromEntries(INDEX_COLLECTIONS.map(c => [c, index[c].length]));
+        const empty = REQUIRED_COLLECTIONS.filter(c => counts[c] === 0);
+        return {
+            indexPath,
+            version: index.version,
+            generated: index.generated,
+            counts,
+            empty,
+            status: empty.length ? 'degraded' : 'ok',
+        };
+    }
+    catch (e) {
+        return {
+            indexPath,
+            version: 'unknown',
+            generated: 'unknown',
+            counts: Object.fromEntries(INDEX_COLLECTIONS.map(c => [c, 0])),
+            empty: [...REQUIRED_COLLECTIONS],
+            status: 'degraded',
+            fatal: e instanceof IndexUnusableError ? e.message : String(e),
+        };
+    }
+}
+/** True when the index came from an installed package rather than a working checkout. */
+function isInstalledPackage(indexPath) {
+    return /[/\\]node_modules[/\\]|[/\\]_npx[/\\]/.test(indexPath);
+}
+/**
+ * The remedy branches on where the index came from: `pnpm index` is not runnable
+ * from the published tarball (package.json files is ["dist","data"]), so the
+ * generic advice would be a dead end for exactly the users who hit an empty
+ * published index.
+ */
+export function remedyFor(indexPath) {
+    return isInstalledPackage(indexPath)
+        ? 'This index came from an installed copy of @castandcrew/spotlight-mcp, which shipped ' +
+            'without derived data. Point the server at a locally generated index instead: clone ' +
+            'cast-and-crew/spotlight-mcp, run "pnpm install && pnpm index /path/to/common-ui-component-library ' +
+            '&& pnpm build", then either set SPOTLIGHT_INDEX_PATH=<checkout>/data/index.json or run ' +
+            '"node <checkout>/dist/index.js" directly instead of npx.'
+        : 'Regenerate the index from the upstream component library: ' +
+            'pnpm index /path/to/common-ui-component-library   (then: pnpm build)';
+}
+const LABEL_WIDTH = 14;
+/** Multi-line stderr banner. Printed at startup in both transports. */
+export function formatBanner(health, packageVersion) {
+    const rule = '─'.repeat(70);
+    if (health.fatal) {
+        return [
+            rule,
+            `  Spotlight MCP ${packageVersion} — INDEX UNUSABLE`,
+            '',
+            `  ${health.fatal}`,
+            '',
+            `  ${remedyFor(health.indexPath)}`,
+            '',
+            '  All 12 tools will return an error until this is fixed.',
+            rule,
+        ].join('\n');
+    }
+    if (health.status === 'ok') {
+        const c = health.counts;
+        return (`Spotlight MCP ${packageVersion} — index ok ` +
+            `(${c.components} components · ${c.tokens} tokens · ${c.utilityClasses} classes · ` +
+            `${c.patterns} patterns · ${c.rules} rules), generated ${health.generated}\n` +
+            `  ${health.indexPath}`);
+    }
+    const lines = INDEX_COLLECTIONS.map(c => {
+        const n = health.counts[c];
+        const flag = health.empty.includes(c)
+            ? '   ← EMPTY'
+            : c === 'deprecated' && n === 0
+                ? '   (0 is normal — nothing is deprecated today)'
+                : '';
+        return `  ${c.padEnd(LABEL_WIDTH)}: ${String(n).padStart(4)}${flag}`;
+    });
+    return [
+        rule,
+        `  Spotlight MCP ${packageVersion} — INDEX DEGRADED`,
+        `  ${health.indexPath}  (generated ${health.generated})`,
+        '',
+        ...lines,
+        '',
+        `  Tools that need the empty collections will return an error; the rest still work.`,
+        `  ${remedyFor(health.indexPath)}`,
+        rule,
+    ].join('\n');
+}
+//# sourceMappingURL=health.js.map

package/dist/data/health.js.map

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

package/dist/data/loader.d.ts

@@ -1,3 +1,22 @@
 import type { SpotlightIndex } from '../types.js';
+/**
+ * Every collection a Spotlight index must declare as an array. A file missing any
+ * of these is not an index, however well-formed its JSON is.
+ */
+export declare const INDEX_COLLECTIONS: readonly ["components", "patterns", "tokens", "rules", "migration", "deprecated", "utilityClasses"];
+export type IndexCollection = (typeof INDEX_COLLECTIONS)[number];
+/**
+ * The index could not be loaded at all — missing file, unreadable, not JSON, or
+ * not shaped like an index. Distinct from a *degraded* index, which parses fine
+ * but has empty collections; that case is handled per-tool by the guard.
+ */
+export declare class IndexUnusableError extends Error {
+    readonly indexPath: string;
+    constructor(indexPath: string, message: string);
+}
+/** Single source of truth for where the index comes from, so errors can name it. */
+export declare function resolveIndexPath(): string;
 export declare function loadIndex(): SpotlightIndex;
 export declare function reloadIndex(): SpotlightIndex;
+/** Drop the memoized index without immediately reloading. Used by the guard tests. */
+export declare function clearIndexCache(): void;

package/dist/data/loader.js

@@ -2,18 +2,75 @@ import { readFileSync } from 'fs';
 import { resolve, dirname } from 'path';
 import { fileURLToPath } from 'url';
 const __dirname = dirname(fileURLToPath(import.meta.url));
+/**
+ * Every collection a Spotlight index must declare as an array. A file missing any
+ * of these is not an index, however well-formed its JSON is.
+ */
+export const INDEX_COLLECTIONS = [
+    'components',
+    'patterns',
+    'tokens',
+    'rules',
+    'migration',
+    'deprecated',
+    'utilityClasses',
+];
+/**
+ * The index could not be loaded at all — missing file, unreadable, not JSON, or
+ * not shaped like an index. Distinct from a *degraded* index, which parses fine
+ * but has empty collections; that case is handled per-tool by the guard.
+ */
+export class IndexUnusableError extends Error {
+    indexPath;
+    constructor(indexPath, message) {
+        super(message);
+        this.indexPath = indexPath;
+        this.name = 'IndexUnusableError';
+    }
+}
 let cached = null;
+/** Single source of truth for where the index comes from, so errors can name it. */
+export function resolveIndexPath() {
+    return process.env.SPOTLIGHT_INDEX_PATH
+        ? resolve(process.env.SPOTLIGHT_INDEX_PATH)
+        : resolve(__dirname, '../../data/index.json');
+}
 export function loadIndex() {
     if (cached)
         return cached;
-    const indexPath = process.env.SPOTLIGHT_INDEX_PATH
-        ? resolve(process.env.SPOTLIGHT_INDEX_PATH)
-        : resolve(__dirname, '../../data/index.json');
-    cached = JSON.parse(readFileSync(indexPath, 'utf-8'));
+    const indexPath = resolveIndexPath();
+    let raw;
+    try {
+        raw = readFileSync(indexPath, 'utf-8');
+    }
+    catch (e) {
+        throw new IndexUnusableError(indexPath, `Cannot read the Spotlight index at ${indexPath} - ${e.message}`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (e) {
+        throw new IndexUnusableError(indexPath, `${indexPath} is not valid JSON - ${e.message}`);
+    }
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+        throw new IndexUnusableError(indexPath, `${indexPath} does not contain a JSON object.`);
+    }
+    const missing = INDEX_COLLECTIONS.filter(k => !Array.isArray(parsed[k]));
+    if (missing.length) {
+        throw new IndexUnusableError(indexPath, `${indexPath} is not a Spotlight index - missing or non-array key(s): ${missing.join(', ')}.`);
+    }
+    // Deliberately only cached on success: a later fix plus reloadIndex() recovers
+    // without restarting the server.
+    cached = parsed;
     return cached;
 }
 export function reloadIndex() {
     cached = null;
     return loadIndex();
 }
+/** Drop the memoized index without immediately reloading. Used by the guard tests. */
+export function clearIndexCache() {
+    cached = null;
+}
 //# sourceMappingURL=loader.js.map

package/dist/data/loader.js.map

@@ -1 +1 @@
-{"version":3,"file":"loader.js","sourceRoot":"","sources":["../../src/data/loader.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,IAAI,CAAC;AAClC,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,MAAM,CAAC;AACxC,OAAO,EAAE,aAAa,EAAE,MAAM,KAAK,CAAC;AAGpC,MAAM,SAAS,GAAG,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;AAE1D,IAAI,MAAM,GAA0B,IAAI,CAAC;AAEzC,MAAM,UAAU,SAAS;IACvB,IAAI,MAAM;QAAE,OAAO,MAAM,CAAC;IAC1B,MAAM,SAAS,GAAG,OAAO,CAAC,GAAG,CAAC,oBAAoB;QAChD,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,oBAAoB,CAAC;QAC3C,CAAC,CAAC,OAAO,CAAC,SAAS,EAAE,uBAAuB,CAAC,CAAC;IAChD,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,SAAS,EAAE,OAAO,CAAC,CAAmB,CAAC;IACxE,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,MAAM,UAAU,WAAW;IACzB,MAAM,GAAG,IAAI,CAAC;IACd,OAAO,SAAS,EAAE,CAAC;AACrB,CAAC"}
+{"version":3,"file":"loader.js","sourceRoot":"","sources":["../../src/data/loader.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,IAAI,CAAC;AAClC,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,MAAM,CAAC;AACxC,OAAO,EAAE,aAAa,EAAE,MAAM,KAAK,CAAC;AAGpC,MAAM,SAAS,GAAG,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;AAE1D;;;GAGG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG;IAC/B,YAAY;IACZ,UAAU;IACV,QAAQ;IACR,OAAO;IACP,WAAW;IACX,YAAY;IACZ,gBAAgB;CACR,CAAC;AAIX;;;;GAIG;AACH,MAAM,OAAO,kBAAmB,SAAQ,KAAK;IAEhC;IADX,YACW,SAAiB,EAC1B,OAAe;QAEf,KAAK,CAAC,OAAO,CAAC,CAAC;QAHN,cAAS,GAAT,SAAS,CAAQ;QAI1B,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAC;IACnC,CAAC;CACF;AAED,IAAI,MAAM,GAA0B,IAAI,CAAC;AAEzC,oFAAoF;AACpF,MAAM,UAAU,gBAAgB;IAC9B,OAAO,OAAO,CAAC,GAAG,CAAC,oBAAoB;QACrC,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,oBAAoB,CAAC;QAC3C,CAAC,CAAC,OAAO,CAAC,SAAS,EAAE,uBAAuB,CAAC,CAAC;AAClD,CAAC;AAED,MAAM,UAAU,SAAS;IACvB,IAAI,MAAM;QAAE,OAAO,MAAM,CAAC;IAC1B,MAAM,SAAS,GAAG,gBAAgB,EAAE,CAAC;IAErC,IAAI,GAAW,CAAC;IAChB,IAAI,CAAC;QACH,GAAG,GAAG,YAAY,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;IACzC,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,MAAM,IAAI,kBAAkB,CAC1B,SAAS,EACT,sCAAsC,SAAS,MAAO,CAAW,CAAC,OAAO,EAAE,CAC5E,CAAC;IACJ,CAAC;IAED,IAAI,MAAe,CAAC;IACpB,IAAI,CAAC;QACH,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAC3B,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,MAAM,IAAI,kBAAkB,CAC1B,SAAS,EACT,GAAG,SAAS,wBAAyB,CAAW,CAAC,OAAO,EAAE,CAC3D,CAAC;IACJ,CAAC;IAED,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,KAAK,IAAI,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;QAC3E,MAAM,IAAI,kBAAkB,CAAC,SAAS,EAAE,GAAG,SAAS,kCAAkC,CAAC,CAAC;IAC1F,CAAC;IAED,MAAM,OAAO,GAAG,iBAAiB,CAAC,MAAM,CACtC,CAAC,CAAC,EAAE,CAAC,CAAC,KAAK,CAAC,OAAO,CAAE,MAAkC,CAAC,CAAC,CAAC,CAAC,CAC5D,CAAC;IACF,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;QACnB,MAAM,IAAI,kBAAkB,CAC1B,SAAS,EACT,GAAG,SAAS,4DAA4D,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAC9F,CAAC;IACJ,CAAC;IAED,+EAA+E;IAC/E,iCAAiC;IACjC,MAAM,GAAG,MAAwB,CAAC;IAClC,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,MAAM,UAAU,WAAW;IACzB,MAAM,GAAG,IAAI,CAAC;IACd,OAAO,SAAS,EAAE,CAAC;AACrB,CAAC;AAED,sFAAsF;AACtF,MAAM,UAAU,eAAe;IAC7B,MAAM,GAAG,IAAI,CAAC;AAChB,CAAC"}

package/dist/lib/regex-safety.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Heuristic catastrophic-backtracking detector. Flags the classic shapes —
+ * a quantified group containing another quantified group or alternation
+ * (`(a+)+`, `(a|a)*`, `(a+)*b`) — that cause exponential worst-case matching
+ * in a backtracking engine. Not a formal proof of safety or danger, just a
+ * cheap gate on patterns nobody should be hand-authoring anyway.
+ */
+export declare function isCatastrophicPattern(source: string): boolean;
+export interface PatternCheckResult {
+    ok: boolean;
+    reason?: string;
+}
+/** Compiles the pattern and runs the heuristic. Used for both build-time and test-time checks. */
+export declare function checkPattern(source: string): PatternCheckResult;

package/dist/lib/regex-safety.js

@@ -0,0 +1,34 @@
+// SPT-1835 follow-up: Snyk flagged `new RegExp(rule.pattern).test(code)` in
+// validate_usage as a ReDoS sink (CWE-400). `rule.pattern` is maintainer-authored
+// (content/rules/*.md, docs/SPOTLIGHT_RULES.md) but `code` — the string it is
+// tested against — is caller-supplied and unbounded, so a catastrophic pattern
+// would let any caller hang the process. This checks patterns at index-build
+// time, where refusing to write is cheap, instead of at request time.
+/**
+ * Heuristic catastrophic-backtracking detector. Flags the classic shapes —
+ * a quantified group containing another quantified group or alternation
+ * (`(a+)+`, `(a|a)*`, `(a+)*b`) — that cause exponential worst-case matching
+ * in a backtracking engine. Not a formal proof of safety or danger, just a
+ * cheap gate on patterns nobody should be hand-authoring anyway.
+ */
+export function isCatastrophicPattern(source) {
+    // A group, quantified, that itself contains a quantified sub-group or an
+    // alternation — the two shapes that create ambiguous repetition.
+    const nestedQuantifier = /\([^()]*[+*][^()]*\)[+*]/.test(source) || // (x+)+ / (x*)+ / (x+)* / (x*)*
+        /\([^()]*\|[^()]*\)[+*]\s*[^$]/.test(source); // (a|a)*  followed by more pattern
+    return nestedQuantifier;
+}
+/** Compiles the pattern and runs the heuristic. Used for both build-time and test-time checks. */
+export function checkPattern(source) {
+    try {
+        new RegExp(source);
+    }
+    catch (e) {
+        return { ok: false, reason: `does not compile: ${e}` };
+    }
+    if (isCatastrophicPattern(source)) {
+        return { ok: false, reason: 'looks catastrophically backtracking (nested quantifier or repeated alternation)' };
+    }
+    return { ok: true };
+}
+//# sourceMappingURL=regex-safety.js.map

package/dist/lib/regex-safety.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"regex-safety.js","sourceRoot":"","sources":["../../src/lib/regex-safety.ts"],"names":[],"mappings":"AAAA,4EAA4E;AAC5E,kFAAkF;AAClF,8EAA8E;AAC9E,+EAA+E;AAC/E,6EAA6E;AAC7E,sEAAsE;AAEtE;;;;;;GAMG;AACH,MAAM,UAAU,qBAAqB,CAAC,MAAc;IAClD,yEAAyE;IACzE,iEAAiE;IACjE,MAAM,gBAAgB,GACpB,0BAA0B,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,gCAAgC;QAC3E,+BAA+B,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,mCAAmC;IAEnF,OAAO,gBAAgB,CAAC;AAC1B,CAAC;AAOD,kGAAkG;AAClG,MAAM,UAAU,YAAY,CAAC,MAAc;IACzC,IAAI,CAAC;QACH,IAAI,MAAM,CAAC,MAAM,CAAC,CAAC;IACrB,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,qBAAqB,CAAC,EAAE,EAAE,CAAC;IACzD,CAAC;IACD,IAAI,qBAAqB,CAAC,MAAM,CAAC,EAAE,CAAC;QAClC,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,iFAAiF,EAAE,CAAC;IAClH,CAAC;IACD,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC;AACtB,CAAC"}

package/dist/server.js

@@ -11,10 +11,34 @@ import { registerSearchUtilityClasses } from './tools/search_utility_classes.js'
 import { registerAskSpotlight } from './tools/ask_spotlight.js';
 import { registerIdentifyPattern } from './tools/identify_pattern.js';
 import { registerGetRecipe } from './tools/get_recipe.js';
+import { getIndexHealth, formatBanner } from './data/health.js';
+import { PACKAGE_VERSION } from './version.js';
+let bannerPrinted = false;
+/**
+ * Report index health to stderr once per process.
+ *
+ * stderr only — stdout carries JSON-RPC in stdio mode. Never throws and never
+ * exits: if the server dies the client reports only "failed to connect" and the
+ * model never sees the reason, which is a silent failure with extra steps. An
+ * unusable index surfaces in-band instead, as an error from every tool that
+ * needs it.
+ */
+function reportIndexHealth() {
+    if (bannerPrinted)
+        return;
+    bannerPrinted = true;
+    try {
+        console.error(formatBanner(getIndexHealth(), PACKAGE_VERSION));
+    }
+    catch {
+        // Diagnostics must never take the server down.
+    }
+}
 export function createServer() {
+    reportIndexHealth();
     const server = new McpServer({
         name: 'spotlight-mcp',
-        version: '0.1.0',
+        version: PACKAGE_VERSION,
     });
     registerGetComponent(server);
     registerSearchComponents(server);

package/dist/server.js.map

@@ -1 +1 @@
-{"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACpE,OAAO,EAAE,oBAAoB,EAAE,MAAM,0BAA0B,CAAC;AAChE,OAAO,EAAE,wBAAwB,EAAE,MAAM,8BAA8B,CAAC;AACxE,OAAO,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AACxD,OAAO,EAAE,oBAAoB,EAAE,MAAM,0BAA0B,CAAC;AAChE,OAAO,EAAE,yBAAyB,EAAE,MAAM,gCAAgC,CAAC;AAC3E,OAAO,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AAC5D,OAAO,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AAClE,OAAO,EAAE,sBAAsB,EAAE,MAAM,4BAA4B,CAAC;AACpE,OAAO,EAAE,4BAA4B,EAAE,MAAM,mCAAmC,CAAC;AACjF,OAAO,EAAE,oBAAoB,EAAE,MAAM,0BAA0B,CAAC;AAChE,OAAO,EAAE,uBAAuB,EAAE,MAAM,6BAA6B,CAAC;AACtE,OAAO,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAE1D,MAAM,UAAU,YAAY;IAC1B,MAAM,MAAM,GAAG,IAAI,SAAS,CAAC;QAC3B,IAAI,EAAE,eAAe;QACrB,OAAO,EAAE,OAAO;KACjB,CAAC,CAAC;IAEH,oBAAoB,CAAC,MAAM,CAAC,CAAC;IAC7B,wBAAwB,CAAC,MAAM,CAAC,CAAC;IACjC,gBAAgB,CAAC,MAAM,CAAC,CAAC;IACzB,oBAAoB,CAAC,MAAM,CAAC,CAAC;IAC7B,yBAAyB,CAAC,MAAM,CAAC,CAAC;IAClC,kBAAkB,CAAC,MAAM,CAAC,CAAC;IAC3B,qBAAqB,CAAC,MAAM,CAAC,CAAC;IAC9B,sBAAsB,CAAC,MAAM,CAAC,CAAC;IAC/B,4BAA4B,CAAC,MAAM,CAAC,CAAC;IACrC,oBAAoB,CAAC,MAAM,CAAC,CAAC;IAC7B,uBAAuB,CAAC,MAAM,CAAC,CAAC;IAChC,iBAAiB,CAAC,MAAM,CAAC,CAAC;IAE1B,OAAO,MAAM,CAAC;AAChB,CAAC"}
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACpE,OAAO,EAAE,oBAAoB,EAAE,MAAM,0BAA0B,CAAC;AAChE,OAAO,EAAE,wBAAwB,EAAE,MAAM,8BAA8B,CAAC;AACxE,OAAO,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AACxD,OAAO,EAAE,oBAAoB,EAAE,MAAM,0BAA0B,CAAC;AAChE,OAAO,EAAE,yBAAyB,EAAE,MAAM,gCAAgC,CAAC;AAC3E,OAAO,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AAC5D,OAAO,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AAClE,OAAO,EAAE,sBAAsB,EAAE,MAAM,4BAA4B,CAAC;AACpE,OAAO,EAAE,4BAA4B,EAAE,MAAM,mCAAmC,CAAC;AACjF,OAAO,EAAE,oBAAoB,EAAE,MAAM,0BAA0B,CAAC;AAChE,OAAO,EAAE,uBAAuB,EAAE,MAAM,6BAA6B,CAAC;AACtE,OAAO,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAC1D,OAAO,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAChE,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAE/C,IAAI,aAAa,GAAG,KAAK,CAAC;AAE1B;;;;;;;;GAQG;AACH,SAAS,iBAAiB;IACxB,IAAI,aAAa;QAAE,OAAO;IAC1B,aAAa,GAAG,IAAI,CAAC;IACrB,IAAI,CAAC;QACH,OAAO,CAAC,KAAK,CAAC,YAAY,CAAC,cAAc,EAAE,EAAE,eAAe,CAAC,CAAC,CAAC;IACjE,CAAC;IAAC,MAAM,CAAC;QACP,+CAA+C;IACjD,CAAC;AACH,CAAC;AAED,MAAM,UAAU,YAAY;IAC1B,iBAAiB,EAAE,CAAC;IAEpB,MAAM,MAAM,GAAG,IAAI,SAAS,CAAC;QAC3B,IAAI,EAAE,eAAe;QACrB,OAAO,EAAE,eAAe;KACzB,CAAC,CAAC;IAEH,oBAAoB,CAAC,MAAM,CAAC,CAAC;IAC7B,wBAAwB,CAAC,MAAM,CAAC,CAAC;IACjC,gBAAgB,CAAC,MAAM,CAAC,CAAC;IACzB,oBAAoB,CAAC,MAAM,CAAC,CAAC;IAC7B,yBAAyB,CAAC,MAAM,CAAC,CAAC;IAClC,kBAAkB,CAAC,MAAM,CAAC,CAAC;IAC3B,qBAAqB,CAAC,MAAM,CAAC,CAAC;IAC9B,sBAAsB,CAAC,MAAM,CAAC,CAAC;IAC/B,4BAA4B,CAAC,MAAM,CAAC,CAAC;IACrC,oBAAoB,CAAC,MAAM,CAAC,CAAC;IAC7B,uBAAuB,CAAC,MAAM,CAAC,CAAC;IAChC,iBAAiB,CAAC,MAAM,CAAC,CAAC;IAE1B,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/tools/_fuzzy.d.ts

@@ -0,0 +1,49 @@
+import type Fuse from 'fuse.js';
+import type { FuseResult } from 'fuse.js';
+/**
+ * Search a pre-configured Fuse instance the normal (whole-query) way first;
+ * if that yields nothing, fall back to searching term-by-term (OR semantics)
+ * and merge the results.
+ *
+ * Fuse.js scores a whole query string as a single fuzzy pattern. With
+ * multi-word queries (e.g. "alert warning inline notification banner") the
+ * full string sometimes fails to match any indexed field closely enough to
+ * clear the configured threshold, even though a single term ("alert") would
+ * match cleanly — so callers got `[]` for exactly the kind of query the model
+ * is most likely to send (SPT-1828).
+ *
+ * The whole-query search is tried first (and returned as-is when it finds
+ * anything) because it is more precise. Per-term OR is only used as a
+ * fallback for the zero-result case the bug describes.
+ *
+ * Use this for tools whose Fuse keys are short fields (names, descriptions,
+ * categories) — `search_components`, `search_tokens`. For `identify_pattern`,
+ * whose pool also weighs a large `content` field very low, use
+ * `searchOrPerTermStrict` instead (see its docstring for why).
+ */
+export declare function searchOrPerTerm<T>(fuse: Fuse<T>, query: string, limit?: number): FuseResult<T>[];
+/**
+ * Stricter per-term fallback for `identify_pattern`'s natural-language
+ * `useCase` queries.
+ *
+ * `identify_pattern`'s pool weighs a pattern's full `content` field very low
+ * (0.1) specifically so a big text blob only matters when several query
+ * terms line up together — plain per-term OR search defeats that: almost
+ * any short single word fuzzy-matches *something* inside a 10k+ character
+ * blob purely by chance (Bitap fuzzy matching on long strings), which both
+ * resurfaces noise for genuine queries and breaks the "no match" case for
+ * unrelated/nonsense queries (SPT-1828 regression check).
+ *
+ * To keep the fallback honest, this variant:
+ *   1. Drops filler words (short + stopwords) before splitting into terms.
+ *   2. Only keeps an item if a majority of the remaining terms (>=60%, min 2)
+ *      independently matched it — coincidental single-term noise matches
+ *      don't reach quorum.
+ *   3. Only keeps an item whose best per-term score is very tight (<= 0.15)
+ *      — genuine matches on title/id/description land near 0, while noise
+ *      from the diluted content field scores much worse.
+ *
+ * Falls back to the plain whole-query result (usually `[]`) if nothing
+ * clears both bars, which is what drives `identify_pattern`'s `noMatch`.
+ */
+export declare function searchOrPerTermStrict<T>(fuse: Fuse<T>, query: string, limit?: number): FuseResult<T>[];

package/dist/tools/_fuzzy.js

@@ -0,0 +1,103 @@
+/**
+ * Run one Fuse search per whitespace-separated term and merge the results,
+ * keeping the best (lowest) score and a per-item match count when the same
+ * item is hit by more than one term.
+ */
+function searchPerTerm(fuse, terms) {
+    const best = new Map();
+    for (const term of terms) {
+        for (const result of fuse.search(term)) {
+            const existing = best.get(result.item);
+            if (!existing) {
+                best.set(result.item, { result, hits: 1 });
+            }
+            else {
+                existing.hits += 1;
+                if ((result.score ?? 1) < (existing.result.score ?? 1))
+                    existing.result = result;
+            }
+        }
+    }
+    return [...best.values()];
+}
+/**
+ * Search a pre-configured Fuse instance the normal (whole-query) way first;
+ * if that yields nothing, fall back to searching term-by-term (OR semantics)
+ * and merge the results.
+ *
+ * Fuse.js scores a whole query string as a single fuzzy pattern. With
+ * multi-word queries (e.g. "alert warning inline notification banner") the
+ * full string sometimes fails to match any indexed field closely enough to
+ * clear the configured threshold, even though a single term ("alert") would
+ * match cleanly — so callers got `[]` for exactly the kind of query the model
+ * is most likely to send (SPT-1828).
+ *
+ * The whole-query search is tried first (and returned as-is when it finds
+ * anything) because it is more precise. Per-term OR is only used as a
+ * fallback for the zero-result case the bug describes.
+ *
+ * Use this for tools whose Fuse keys are short fields (names, descriptions,
+ * categories) — `search_components`, `search_tokens`. For `identify_pattern`,
+ * whose pool also weighs a large `content` field very low, use
+ * `searchOrPerTermStrict` instead (see its docstring for why).
+ */
+export function searchOrPerTerm(fuse, query, limit) {
+    const wholeQueryResults = fuse.search(query, limit ? { limit } : undefined);
+    if (wholeQueryResults.length > 0)
+        return wholeQueryResults;
+    const terms = query.trim().split(/\s+/).filter(Boolean);
+    if (terms.length <= 1)
+        return wholeQueryResults;
+    const merged = searchPerTerm(fuse, terms)
+        .map(({ result }) => result)
+        .sort((a, b) => (a.score ?? 1) - (b.score ?? 1));
+    return limit ? merged.slice(0, limit) : merged;
+}
+const FALLBACK_STOPWORDS = new Set([
+    'a', 'an', 'the', 'to', 'of', 'is', 'no', 'when', 'with', 'for', 'and', 'or',
+    'in', 'on', 'at', 'be', 'are', 'i', 'you', 'your', 'it', 'this', 'that', 'as',
+]);
+/**
+ * Stricter per-term fallback for `identify_pattern`'s natural-language
+ * `useCase` queries.
+ *
+ * `identify_pattern`'s pool weighs a pattern's full `content` field very low
+ * (0.1) specifically so a big text blob only matters when several query
+ * terms line up together — plain per-term OR search defeats that: almost
+ * any short single word fuzzy-matches *something* inside a 10k+ character
+ * blob purely by chance (Bitap fuzzy matching on long strings), which both
+ * resurfaces noise for genuine queries and breaks the "no match" case for
+ * unrelated/nonsense queries (SPT-1828 regression check).
+ *
+ * To keep the fallback honest, this variant:
+ *   1. Drops filler words (short + stopwords) before splitting into terms.
+ *   2. Only keeps an item if a majority of the remaining terms (>=60%, min 2)
+ *      independently matched it — coincidental single-term noise matches
+ *      don't reach quorum.
+ *   3. Only keeps an item whose best per-term score is very tight (<= 0.15)
+ *      — genuine matches on title/id/description land near 0, while noise
+ *      from the diluted content field scores much worse.
+ *
+ * Falls back to the plain whole-query result (usually `[]`) if nothing
+ * clears both bars, which is what drives `identify_pattern`'s `noMatch`.
+ */
+export function searchOrPerTermStrict(fuse, query, limit) {
+    const wholeQueryResults = fuse.search(query, limit ? { limit } : undefined);
+    if (wholeQueryResults.length > 0)
+        return wholeQueryResults;
+    const terms = query
+        .trim()
+        .toLowerCase()
+        .split(/\s+/)
+        .filter(t => t.length >= 3 && !FALLBACK_STOPWORDS.has(t));
+    if (terms.length < 2)
+        return wholeQueryResults;
+    const quorum = Math.max(2, Math.ceil(terms.length * 0.6));
+    const STRICT_SCORE_CEILING = 0.15;
+    const merged = searchPerTerm(fuse, terms)
+        .filter(({ result, hits }) => hits >= quorum && (result.score ?? 1) <= STRICT_SCORE_CEILING)
+        .map(({ result }) => result)
+        .sort((a, b) => (a.score ?? 1) - (b.score ?? 1));
+    return limit ? merged.slice(0, limit) : merged;
+}
+//# sourceMappingURL=_fuzzy.js.map

package/dist/tools/_fuzzy.js.map

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

package/dist/tools/_guard.d.ts

@@ -0,0 +1,31 @@
+import { type IndexCollection } from '../data/loader.js';
+import type { SpotlightIndex } from '../types.js';
+export type ToolResult = {
+    content: {
+        type: 'text';
+        text: string;
+    }[];
+    isError?: boolean;
+};
+/**
+ * Returns null when every collection this tool depends on has data, otherwise a
+ * ready-to-return MCP error naming the problem and the fix.
+ *
+ * The "do not answer from memory" line is deliberate: the observed failure mode of
+ * an empty index is a model quietly substituting remembered or MUI component and
+ * token names for real Spotlight ones.
+ */
+export declare function requireCollections(tool: string, ...needed: IndexCollection[]): ToolResult | null;
+/**
+ * Guard + load in one call:
+ *
+ *   const { index, error } = guardedIndex('get_component', 'components');
+ *   if (error) return error;
+ */
+export declare function guardedIndex(tool: string, ...needed: IndexCollection[]): {
+    index: SpotlightIndex;
+    error?: undefined;
+} | {
+    index?: undefined;
+    error: ToolResult;
+};

package/dist/tools/_guard.js

@@ -0,0 +1,62 @@
+// Not a tool. Shared guard every tool calls before touching the index, so an
+// empty or unusable index can never be reported as an honest negative answer.
+import { loadIndex } from '../data/loader.js';
+import { getIndexHealth, remedyFor } from '../data/health.js';
+function errorResult(payload) {
+    return {
+        content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }],
+        isError: true,
+    };
+}
+/**
+ * Returns null when every collection this tool depends on has data, otherwise a
+ * ready-to-return MCP error naming the problem and the fix.
+ *
+ * The "do not answer from memory" line is deliberate: the observed failure mode of
+ * an empty index is a model quietly substituting remembered or MUI component and
+ * token names for real Spotlight ones.
+ */
+export function requireCollections(tool, ...needed) {
+    const health = getIndexHealth();
+    if (health.fatal) {
+        return errorResult({
+            error: 'SPOTLIGHT_INDEX_UNREADABLE',
+            tool,
+            message: `${health.fatal} This server has no design-system data. ` +
+                'Do not answer from memory or invent component/token names — tell the user the index ' +
+                'could not be loaded and how to fix it.',
+            indexPath: health.indexPath,
+            remedy: remedyFor(health.indexPath),
+        });
+    }
+    const missing = needed.filter(c => health.counts[c] === 0);
+    if (!missing.length)
+        return null;
+    return errorResult({
+        error: 'SPOTLIGHT_INDEX_EMPTY',
+        tool,
+        message: `The Spotlight index has no ${missing.join(' and no ')}. ` +
+            `"${tool}" cannot answer until the index is rebuilt. ` +
+            'Do not answer from memory or invent component/token names — tell the user the index is ' +
+            'empty and how to fix it.',
+        missing,
+        indexPath: health.indexPath,
+        indexVersion: health.version,
+        generated: health.generated,
+        counts: health.counts,
+        remedy: remedyFor(health.indexPath),
+    });
+}
+/**
+ * Guard + load in one call:
+ *
+ *   const { index, error } = guardedIndex('get_component', 'components');
+ *   if (error) return error;
+ */
+export function guardedIndex(tool, ...needed) {
+    const error = requireCollections(tool, ...needed);
+    if (error)
+        return { error };
+    return { index: loadIndex() };
+}
+//# sourceMappingURL=_guard.js.map

package/dist/tools/_guard.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"_guard.js","sourceRoot":"","sources":["../../src/tools/_guard.ts"],"names":[],"mappings":"AAAA,6EAA6E;AAC7E,8EAA8E;AAC9E,OAAO,EAAE,SAAS,EAAwB,MAAM,mBAAmB,CAAC;AACpE,OAAO,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAQ9D,SAAS,WAAW,CAAC,OAAgC;IACnD,OAAO;QACL,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAe,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,CAAC;QAC5E,OAAO,EAAE,IAAI;KACd,CAAC;AACJ,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,kBAAkB,CAChC,IAAY,EACZ,GAAG,MAAyB;IAE5B,MAAM,MAAM,GAAG,cAAc,EAAE,CAAC;IAEhC,IAAI,MAAM,CAAC,KAAK,EAAE,CAAC;QACjB,OAAO,WAAW,CAAC;YACjB,KAAK,EAAE,4BAA4B;YACnC,IAAI;YACJ,OAAO,EACL,GAAG,MAAM,CAAC,KAAK,0CAA0C;gBACzD,sFAAsF;gBACtF,wCAAwC;YAC1C,SAAS,EAAE,MAAM,CAAC,SAAS;YAC3B,MAAM,EAAE,SAAS,CAAC,MAAM,CAAC,SAAS,CAAC;SACpC,CAAC,CAAC;IACL,CAAC;IAED,MAAM,OAAO,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC;IAC3D,IAAI,CAAC,OAAO,CAAC,MAAM;QAAE,OAAO,IAAI,CAAC;IAEjC,OAAO,WAAW,CAAC;QACjB,KAAK,EAAE,uBAAuB;QAC9B,IAAI;QACJ,OAAO,EACL,8BAA8B,OAAO,CAAC,IAAI,CAAC,UAAU,CAAC,IAAI;YAC1D,IAAI,IAAI,8CAA8C;YACtD,yFAAyF;YACzF,0BAA0B;QAC5B,OAAO;QACP,SAAS,EAAE,MAAM,CAAC,SAAS;QAC3B,YAAY,EAAE,MAAM,CAAC,OAAO;QAC5B,SAAS,EAAE,MAAM,CAAC,SAAS;QAC3B,MAAM,EAAE,MAAM,CAAC,MAAM;QACrB,MAAM,EAAE,SAAS,CAAC,MAAM,CAAC,SAAS,CAAC;KACpC,CAAC,CAAC;AACL,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,YAAY,CAC1B,IAAY,EACZ,GAAG,MAAyB;IAE5B,MAAM,KAAK,GAAG,kBAAkB,CAAC,IAAI,EAAE,GAAG,MAAM,CAAC,CAAC;IAClD,IAAI,KAAK;QAAE,OAAO,EAAE,KAAK,EAAE,CAAC;IAC5B,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,EAAE,CAAC;AAChC,CAAC"}

package/dist/tools/_synonyms.d.ts

@@ -0,0 +1 @@
+export declare function expandWithSynonyms(query: string): string;