@skillsmith/mcp-server 0.1.0

package/dist/src/suggestions/suggestion-engine.d.ts

@@ -0,0 +1,185 @@
+/**
+ * @fileoverview Contextual Skill Suggestion Engine
+ * @module @skillsmith/mcp-server/suggestions/suggestion-engine
+ * @see SMI-913: Contextual skill suggestions after first success
+ *
+ * Provides intelligent skill recommendations based on project context detection.
+ * Implements rate limiting, opt-out functionality, and persistent state management.
+ *
+ * @example
+ * import { SuggestionEngine } from './suggestion-engine.js'
+ * import { detectProjectContext } from '../context/project-detector.js'
+ *
+ * const engine = new SuggestionEngine()
+ * const context = detectProjectContext()
+ * const suggestions = engine.getSuggestions(context, ['installed/skill1'])
+ *
+ * if (suggestions.length > 0) {
+ *   console.log(`Suggestion: ${suggestions[0].skillName} - ${suggestions[0].reason}`)
+ *   engine.recordSuggestionShown()
+ * }
+ */
+import type { ProjectContext } from '../context/project-detector.js';
+import type { SkillSuggestion, SuggestionConfig, SuggestionState } from './types.js';
+/**
+ * Engine for generating contextual skill suggestions
+ *
+ * Manages suggestion state, rate limiting, and skill recommendations
+ * based on detected project context.
+ *
+ * @example
+ * const engine = new SuggestionEngine({ cooldownMs: 10 * 60 * 1000 })
+ * const context = detectProjectContext('/path/to/project')
+ * const suggestions = engine.getSuggestions(context, ['installed/skill'])
+ */
+export declare class SuggestionEngine {
+    private config;
+    private state;
+    private stateDir;
+    private stateFile;
+    /**
+     * Create a new SuggestionEngine instance
+     *
+     * @param config - Partial configuration to override defaults
+     *
+     * @example
+     * // Use defaults
+     * const engine = new SuggestionEngine()
+     *
+     * // Override cooldown
+     * const engine = new SuggestionEngine({ cooldownMs: 10 * 60 * 1000 })
+     *
+     * // Custom state directory (for testing)
+     * const engine = new SuggestionEngine({ stateDir: '/tmp/test-state' })
+     */
+    constructor(config?: Partial<SuggestionConfig>);
+    /**
+     * Load suggestion state from disk
+     *
+     * Resets daily count if it's a new day.
+     *
+     * @returns Loaded or default suggestion state
+     */
+    private loadState;
+    /**
+     * Get default suggestion state
+     *
+     * @returns Fresh default state object
+     */
+    private getDefaultState;
+    /**
+     * Save suggestion state to disk
+     *
+     * Creates the state directory if it doesn't exist.
+     */
+    private saveState;
+    /**
+     * Check if suggestions can be shown based on rate limits
+     *
+     * Checks:
+     * - User has not opted out
+     * - Daily limit not reached
+     * - Cooldown period has passed
+     *
+     * @returns True if suggestions are allowed
+     *
+     * @example
+     * if (engine.canSuggest()) {
+     *   const suggestions = engine.getSuggestions(context)
+     *   // Show suggestion to user
+     * }
+     */
+    canSuggest(): boolean;
+    /**
+     * Get skill suggestions based on project context
+     *
+     * Returns empty array if rate limited or opted out.
+     * Filters out already installed and dismissed skills.
+     * Returns at most one suggestion (the highest priority match).
+     *
+     * @param context - Detected project context from project-detector
+     * @param installedSkills - Array of currently installed skill IDs
+     * @returns Array of skill suggestions (at most one)
+     *
+     * @example
+     * const context = detectProjectContext()
+     * const suggestions = engine.getSuggestions(context, ['user/docker'])
+     *
+     * if (suggestions.length > 0) {
+     *   console.log(`Try: ${suggestions[0].skillName}`)
+     * }
+     */
+    getSuggestions(context: ProjectContext, installedSkills?: string[]): SkillSuggestion[];
+    /**
+     * Get list of context attributes that are true
+     *
+     * @param context - Project context to analyze
+     * @returns Array of context match strings
+     */
+    private getContextMatches;
+    /**
+     * Record that a suggestion was shown to the user
+     *
+     * Updates the last suggestion time and increments daily counter.
+     * Should be called after displaying a suggestion.
+     *
+     * @example
+     * const suggestions = engine.getSuggestions(context)
+     * if (suggestions.length > 0) {
+     *   displaySuggestion(suggestions[0])
+     *   engine.recordSuggestionShown()
+     * }
+     */
+    recordSuggestionShown(): void;
+    /**
+     * Dismiss a skill so it won't be suggested again
+     *
+     * User can dismiss skills they're not interested in.
+     *
+     * @param skillId - Full skill identifier to dismiss
+     *
+     * @example
+     * // User clicks "Don't show again" on docker suggestion
+     * engine.dismissSkill('community/docker')
+     */
+    dismissSkill(skillId: string): void;
+    /**
+     * Permanently opt out of all suggestions
+     *
+     * User can disable all suggestions. Use optIn() to reverse.
+     *
+     * @example
+     * // User clicks "Never show suggestions"
+     * engine.optOut()
+     */
+    optOut(): void;
+    /**
+     * Opt back in to suggestions after opting out
+     *
+     * @example
+     * // User re-enables suggestions in settings
+     * engine.optIn()
+     */
+    optIn(): void;
+    /**
+     * Reset all suggestion state to defaults
+     *
+     * Clears dismissed skills, resets counters, and re-enables suggestions.
+     *
+     * @example
+     * // User clicks "Reset suggestions"
+     * engine.resetState()
+     */
+    resetState(): void;
+    /**
+     * Get a deep copy of the current suggestion state
+     *
+     * @returns Deep copy of current state (modifications don't affect engine)
+     *
+     * @example
+     * const state = engine.getState()
+     * console.log(`Suggestions today: ${state.suggestionsToday}`)
+     */
+    getState(): SuggestionState;
+}
+//# sourceMappingURL=suggestion-engine.d.ts.map

package/dist/src/suggestions/suggestion-engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"suggestion-engine.d.ts","sourceRoot":"","sources":["../../../src/suggestions/suggestion-engine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAKH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gCAAgC,CAAA;AACpE,OAAO,KAAK,EAAE,eAAe,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAqFpF;;;;;;;;;;GAUG;AACH,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,MAAM,CAAkB;IAChC,OAAO,CAAC,KAAK,CAAiB;IAC9B,OAAO,CAAC,QAAQ,CAAQ;IACxB,OAAO,CAAC,SAAS,CAAQ;IAEzB;;;;;;;;;;;;;;OAcG;gBACS,MAAM,GAAE,OAAO,CAAC,gBAAgB,CAAM;IAOlD;;;;;;OAMG;IACH,OAAO,CAAC,SAAS;IAuBjB;;;;OAIG;IACH,OAAO,CAAC,eAAe;IASvB;;;;OAIG;IACH,OAAO,CAAC,SAAS;IAOjB;;;;;;;;;;;;;;;OAeG;IACH,UAAU,IAAI,OAAO;IAQrB;;;;;;;;;;;;;;;;;;OAkBG;IACH,cAAc,CAAC,OAAO,EAAE,cAAc,EAAE,eAAe,GAAE,MAAM,EAAO,GAAG,eAAe,EAAE;IA4B1F;;;;;OAKG;IACH,OAAO,CAAC,iBAAiB;IAWzB;;;;;;;;;;;;OAYG;IACH,qBAAqB,IAAI,IAAI;IAM7B;;;;;;;;;;OAUG;IACH,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAOnC;;;;;;;;OAQG;IACH,MAAM,IAAI,IAAI;IAKd;;;;;;OAMG;IACH,KAAK,IAAI,IAAI;IAKb;;;;;;;;OAQG;IACH,UAAU,IAAI,IAAI;IAKlB;;;;;;;;OAQG;IACH,QAAQ,IAAI,eAAe;CAM5B"}

package/dist/src/suggestions/suggestion-engine.js

@@ -0,0 +1,352 @@
+/**
+ * @fileoverview Contextual Skill Suggestion Engine
+ * @module @skillsmith/mcp-server/suggestions/suggestion-engine
+ * @see SMI-913: Contextual skill suggestions after first success
+ *
+ * Provides intelligent skill recommendations based on project context detection.
+ * Implements rate limiting, opt-out functionality, and persistent state management.
+ *
+ * @example
+ * import { SuggestionEngine } from './suggestion-engine.js'
+ * import { detectProjectContext } from '../context/project-detector.js'
+ *
+ * const engine = new SuggestionEngine()
+ * const context = detectProjectContext()
+ * const suggestions = engine.getSuggestions(context, ['installed/skill1'])
+ *
+ * if (suggestions.length > 0) {
+ *   console.log(`Suggestion: ${suggestions[0].skillName} - ${suggestions[0].reason}`)
+ *   engine.recordSuggestionShown()
+ * }
+ */
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'fs';
+import { join } from 'path';
+import { homedir } from 'os';
+/** Cooldown period between suggestions in milliseconds (5 minutes) */
+const SUGGESTION_COOLDOWN_MS = 5 * 60 * 1000;
+/** Maximum suggestions per day per user */
+const MAX_SUGGESTIONS_PER_DAY = 3;
+/** Default directory for storing Skillsmith configuration and state */
+const DEFAULT_SUGGESTIONS_DIR = join(homedir(), '.skillsmith');
+/** Default configuration values */
+const DEFAULT_CONFIG = {
+    cooldownMs: SUGGESTION_COOLDOWN_MS,
+    maxSuggestionsPerDay: MAX_SUGGESTIONS_PER_DAY,
+    enableOptOut: true,
+};
+/**
+ * Skill suggestion rules based on project context
+ *
+ * Rules are evaluated in order. Each rule checks for specific project
+ * characteristics and suggests relevant skills.
+ */
+const SUGGESTION_RULES = [
+    {
+        condition: (ctx) => ctx.hasDocker && ctx.hasNativeModules,
+        skillId: 'community/docker',
+        skillName: 'docker',
+        reason: 'Your project uses native modules - Docker ensures consistent builds',
+        priority: 1,
+    },
+    {
+        condition: (ctx) => ctx.hasLinear,
+        skillId: 'user/linear',
+        skillName: 'linear',
+        reason: 'Automate Linear issue updates from your commits',
+        priority: 2,
+    },
+    {
+        condition: (ctx) => ctx.hasGitHub,
+        skillId: 'anthropic/review-pr',
+        skillName: 'review-pr',
+        reason: 'Get AI-powered code review suggestions for your PRs',
+        priority: 2,
+    },
+    {
+        condition: (ctx) => ctx.testFramework === 'jest',
+        skillId: 'community/jest-helper',
+        skillName: 'jest-helper',
+        reason: 'Generate and improve Jest tests automatically',
+        priority: 3,
+    },
+    {
+        condition: (ctx) => ctx.testFramework === 'vitest',
+        skillId: 'community/vitest-helper',
+        skillName: 'vitest-helper',
+        reason: 'Generate and improve Vitest tests automatically',
+        priority: 3,
+    },
+    {
+        condition: (ctx) => ctx.apiFramework === 'express' || ctx.apiFramework === 'nextjs',
+        skillId: 'community/api-docs',
+        skillName: 'api-docs',
+        reason: 'Generate OpenAPI documentation for your API endpoints',
+        priority: 4,
+    },
+];
+/**
+ * Engine for generating contextual skill suggestions
+ *
+ * Manages suggestion state, rate limiting, and skill recommendations
+ * based on detected project context.
+ *
+ * @example
+ * const engine = new SuggestionEngine({ cooldownMs: 10 * 60 * 1000 })
+ * const context = detectProjectContext('/path/to/project')
+ * const suggestions = engine.getSuggestions(context, ['installed/skill'])
+ */
+export class SuggestionEngine {
+    config;
+    state;
+    stateDir;
+    stateFile;
+    /**
+     * Create a new SuggestionEngine instance
+     *
+     * @param config - Partial configuration to override defaults
+     *
+     * @example
+     * // Use defaults
+     * const engine = new SuggestionEngine()
+     *
+     * // Override cooldown
+     * const engine = new SuggestionEngine({ cooldownMs: 10 * 60 * 1000 })
+     *
+     * // Custom state directory (for testing)
+     * const engine = new SuggestionEngine({ stateDir: '/tmp/test-state' })
+     */
+    constructor(config = {}) {
+        this.config = { ...DEFAULT_CONFIG, ...config };
+        this.stateDir = config.stateDir || DEFAULT_SUGGESTIONS_DIR;
+        this.stateFile = join(this.stateDir, 'suggestions-state.json');
+        this.state = this.loadState();
+    }
+    /**
+     * Load suggestion state from disk
+     *
+     * Resets daily count if it's a new day.
+     *
+     * @returns Loaded or default suggestion state
+     */
+    loadState() {
+        if (existsSync(this.stateFile)) {
+            try {
+                const data = JSON.parse(readFileSync(this.stateFile, 'utf-8'));
+                // Reset daily count if new day
+                const today = new Date().toDateString();
+                const lastDay = new Date(data.lastSuggestionTime || 0).toDateString();
+                if (today !== lastDay) {
+                    data.suggestionsToday = 0;
+                }
+                return data;
+            }
+            catch (error) {
+                console.warn('[suggestion-engine] Failed to load state:', this.stateFile, error instanceof Error ? error.message : String(error));
+                return this.getDefaultState();
+            }
+        }
+        return this.getDefaultState();
+    }
+    /**
+     * Get default suggestion state
+     *
+     * @returns Fresh default state object
+     */
+    getDefaultState() {
+        return {
+            lastSuggestionTime: 0,
+            suggestionsToday: 0,
+            optedOut: false,
+            dismissedSkills: [],
+        };
+    }
+    /**
+     * Save suggestion state to disk
+     *
+     * Creates the state directory if it doesn't exist.
+     */
+    saveState() {
+        if (!existsSync(this.stateDir)) {
+            mkdirSync(this.stateDir, { recursive: true });
+        }
+        writeFileSync(this.stateFile, JSON.stringify(this.state, null, 2));
+    }
+    /**
+     * Check if suggestions can be shown based on rate limits
+     *
+     * Checks:
+     * - User has not opted out
+     * - Daily limit not reached
+     * - Cooldown period has passed
+     *
+     * @returns True if suggestions are allowed
+     *
+     * @example
+     * if (engine.canSuggest()) {
+     *   const suggestions = engine.getSuggestions(context)
+     *   // Show suggestion to user
+     * }
+     */
+    canSuggest() {
+        if (this.state.optedOut)
+            return false;
+        if (this.state.suggestionsToday >= this.config.maxSuggestionsPerDay)
+            return false;
+        const timeSinceLastSuggestion = Date.now() - this.state.lastSuggestionTime;
+        return timeSinceLastSuggestion >= this.config.cooldownMs;
+    }
+    /**
+     * Get skill suggestions based on project context
+     *
+     * Returns empty array if rate limited or opted out.
+     * Filters out already installed and dismissed skills.
+     * Returns at most one suggestion (the highest priority match).
+     *
+     * @param context - Detected project context from project-detector
+     * @param installedSkills - Array of currently installed skill IDs
+     * @returns Array of skill suggestions (at most one)
+     *
+     * @example
+     * const context = detectProjectContext()
+     * const suggestions = engine.getSuggestions(context, ['user/docker'])
+     *
+     * if (suggestions.length > 0) {
+     *   console.log(`Try: ${suggestions[0].skillName}`)
+     * }
+     */
+    getSuggestions(context, installedSkills = []) {
+        if (!this.canSuggest())
+            return [];
+        const suggestions = [];
+        for (const rule of SUGGESTION_RULES) {
+            // Skip if already installed
+            if (installedSkills.some((s) => s.includes(rule.skillName)))
+                continue;
+            // Skip if dismissed
+            if (this.state.dismissedSkills.includes(rule.skillId))
+                continue;
+            // Check condition
+            if (rule.condition(context)) {
+                suggestions.push({
+                    skillId: rule.skillId,
+                    skillName: rule.skillName,
+                    reason: rule.reason,
+                    priority: rule.priority,
+                    contextMatch: this.getContextMatches(context),
+                });
+            }
+        }
+        // Sort by priority and return top suggestion
+        return suggestions.sort((a, b) => a.priority - b.priority).slice(0, 1);
+    }
+    /**
+     * Get list of context attributes that are true
+     *
+     * @param context - Project context to analyze
+     * @returns Array of context match strings
+     */
+    getContextMatches(context) {
+        const matches = [];
+        if (context.hasDocker)
+            matches.push('hasDocker');
+        if (context.hasLinear)
+            matches.push('hasLinear');
+        if (context.hasGitHub)
+            matches.push('hasGitHub');
+        if (context.testFramework)
+            matches.push(`testFramework:${context.testFramework}`);
+        if (context.apiFramework)
+            matches.push(`apiFramework:${context.apiFramework}`);
+        if (context.hasNativeModules)
+            matches.push('hasNativeModules');
+        return matches;
+    }
+    /**
+     * Record that a suggestion was shown to the user
+     *
+     * Updates the last suggestion time and increments daily counter.
+     * Should be called after displaying a suggestion.
+     *
+     * @example
+     * const suggestions = engine.getSuggestions(context)
+     * if (suggestions.length > 0) {
+     *   displaySuggestion(suggestions[0])
+     *   engine.recordSuggestionShown()
+     * }
+     */
+    recordSuggestionShown() {
+        this.state.lastSuggestionTime = Date.now();
+        this.state.suggestionsToday++;
+        this.saveState();
+    }
+    /**
+     * Dismiss a skill so it won't be suggested again
+     *
+     * User can dismiss skills they're not interested in.
+     *
+     * @param skillId - Full skill identifier to dismiss
+     *
+     * @example
+     * // User clicks "Don't show again" on docker suggestion
+     * engine.dismissSkill('community/docker')
+     */
+    dismissSkill(skillId) {
+        if (!this.state.dismissedSkills.includes(skillId)) {
+            this.state.dismissedSkills.push(skillId);
+            this.saveState();
+        }
+    }
+    /**
+     * Permanently opt out of all suggestions
+     *
+     * User can disable all suggestions. Use optIn() to reverse.
+     *
+     * @example
+     * // User clicks "Never show suggestions"
+     * engine.optOut()
+     */
+    optOut() {
+        this.state.optedOut = true;
+        this.saveState();
+    }
+    /**
+     * Opt back in to suggestions after opting out
+     *
+     * @example
+     * // User re-enables suggestions in settings
+     * engine.optIn()
+     */
+    optIn() {
+        this.state.optedOut = false;
+        this.saveState();
+    }
+    /**
+     * Reset all suggestion state to defaults
+     *
+     * Clears dismissed skills, resets counters, and re-enables suggestions.
+     *
+     * @example
+     * // User clicks "Reset suggestions"
+     * engine.resetState()
+     */
+    resetState() {
+        this.state = this.getDefaultState();
+        this.saveState();
+    }
+    /**
+     * Get a deep copy of the current suggestion state
+     *
+     * @returns Deep copy of current state (modifications don't affect engine)
+     *
+     * @example
+     * const state = engine.getState()
+     * console.log(`Suggestions today: ${state.suggestionsToday}`)
+     */
+    getState() {
+        return {
+            ...this.state,
+            dismissedSkills: [...this.state.dismissedSkills],
+        };
+    }
+}
+//# sourceMappingURL=suggestion-engine.js.map

package/dist/src/suggestions/suggestion-engine.js.map

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

package/dist/src/suggestions/types.d.ts

@@ -0,0 +1,88 @@
+/**
+ * @fileoverview Type definitions for Contextual Skill Suggestions
+ * @module @skillsmith/mcp-server/suggestions/types
+ * @see SMI-913: Contextual skill suggestions after first success
+ *
+ * Defines interfaces for the suggestion engine that recommends relevant Tier 2 skills
+ * after a user successfully uses a Tier 1 skill, based on project context.
+ *
+ * @example
+ * import type { SkillSuggestion, SuggestionConfig, SuggestionState } from './types.js'
+ *
+ * const suggestion: SkillSuggestion = {
+ *   skillId: 'community/docker',
+ *   skillName: 'docker',
+ *   reason: 'Your project uses native modules - Docker ensures consistent builds',
+ *   priority: 1,
+ *   contextMatch: ['hasDocker', 'hasNativeModules'],
+ * }
+ */
+/**
+ * A skill suggestion generated based on project context
+ *
+ * @example
+ * const suggestion: SkillSuggestion = {
+ *   skillId: 'community/docker',
+ *   skillName: 'docker',
+ *   reason: 'Your project uses native modules - Docker ensures consistent builds',
+ *   priority: 1,
+ *   contextMatch: ['hasDocker', 'hasNativeModules'],
+ * }
+ */
+export interface SkillSuggestion {
+    /** Full skill identifier (e.g., 'community/docker', 'user/linear') */
+    skillId: string;
+    /** Short skill name for display (e.g., 'docker', 'linear') */
+    skillName: string;
+    /** Human-readable reason why this skill is being suggested */
+    reason: string;
+    /** Priority level (1 = highest priority, higher numbers = lower priority) */
+    priority: number;
+    /** Context attributes that matched this suggestion (e.g., ['hasDocker', 'testFramework:jest']) */
+    contextMatch: string[];
+}
+/**
+ * Configuration options for the suggestion engine
+ *
+ * @example
+ * const config: SuggestionConfig = {
+ *   cooldownMs: 5 * 60 * 1000,  // 5 minutes
+ *   maxSuggestionsPerDay: 3,
+ *   enableOptOut: true,
+ * }
+ */
+export interface SuggestionConfig {
+    /** Minimum time between suggestions in milliseconds (default: 5 minutes) */
+    cooldownMs: number;
+    /** Maximum number of suggestions per day (default: 3) */
+    maxSuggestionsPerDay: number;
+    /** Whether to allow permanent opt-out from suggestions (default: true) */
+    enableOptOut: boolean;
+    /** Custom state directory path (default: ~/.skillsmith) - primarily for testing */
+    stateDir?: string;
+}
+/**
+ * Persistent state for the suggestion engine
+ *
+ * This state is persisted to disk in ~/.skillsmith/suggestions-state.json
+ * and tracks suggestion history, rate limiting, and user preferences.
+ *
+ * @example
+ * const state: SuggestionState = {
+ *   lastSuggestionTime: Date.now(),
+ *   suggestionsToday: 1,
+ *   optedOut: false,
+ *   dismissedSkills: ['community/docker'],
+ * }
+ */
+export interface SuggestionState {
+    /** Timestamp of the last suggestion shown (for cooldown calculation) */
+    lastSuggestionTime: number;
+    /** Number of suggestions shown today (resets at midnight) */
+    suggestionsToday: number;
+    /** Whether the user has permanently opted out of suggestions */
+    optedOut: boolean;
+    /** Array of skill IDs the user has dismissed (won't be suggested again) */
+    dismissedSkills: string[];
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/src/suggestions/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/suggestions/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,eAAe;IAC9B,sEAAsE;IACtE,OAAO,EAAE,MAAM,CAAA;IAEf,8DAA8D;IAC9D,SAAS,EAAE,MAAM,CAAA;IAEjB,8DAA8D;IAC9D,MAAM,EAAE,MAAM,CAAA;IAEd,6EAA6E;IAC7E,QAAQ,EAAE,MAAM,CAAA;IAEhB,kGAAkG;IAClG,YAAY,EAAE,MAAM,EAAE,CAAA;CACvB;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,gBAAgB;IAC/B,4EAA4E;IAC5E,UAAU,EAAE,MAAM,CAAA;IAElB,yDAAyD;IACzD,oBAAoB,EAAE,MAAM,CAAA;IAE5B,0EAA0E;IAC1E,YAAY,EAAE,OAAO,CAAA;IAErB,mFAAmF;IACnF,QAAQ,CAAC,EAAE,MAAM,CAAA;CAClB;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,eAAe;IAC9B,wEAAwE;IACxE,kBAAkB,EAAE,MAAM,CAAA;IAE1B,6DAA6D;IAC7D,gBAAgB,EAAE,MAAM,CAAA;IAExB,gEAAgE;IAChE,QAAQ,EAAE,OAAO,CAAA;IAEjB,2EAA2E;IAC3E,eAAe,EAAE,MAAM,EAAE,CAAA;CAC1B"}

package/dist/src/suggestions/types.js

@@ -0,0 +1,21 @@
+/**
+ * @fileoverview Type definitions for Contextual Skill Suggestions
+ * @module @skillsmith/mcp-server/suggestions/types
+ * @see SMI-913: Contextual skill suggestions after first success
+ *
+ * Defines interfaces for the suggestion engine that recommends relevant Tier 2 skills
+ * after a user successfully uses a Tier 1 skill, based on project context.
+ *
+ * @example
+ * import type { SkillSuggestion, SuggestionConfig, SuggestionState } from './types.js'
+ *
+ * const suggestion: SkillSuggestion = {
+ *   skillId: 'community/docker',
+ *   skillName: 'docker',
+ *   reason: 'Your project uses native modules - Docker ensures consistent builds',
+ *   priority: 1,
+ *   contextMatch: ['hasDocker', 'hasNativeModules'],
+ * }
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/src/suggestions/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/suggestions/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG"}