@skillsmith/mcp-server 0.4.2 → 0.4.3

package/dist/src/context.async.d.ts

@@ -0,0 +1,48 @@
+/**
+ * @fileoverview Async Tool Context Creation with WASM Fallback
+ * @module @skillsmith/mcp-server/context.async
+ * @see SMI-2207: Async database functions with WASM fallback
+ * @see SMI-2741: Split from context.ts to meet 500-line standard
+ *
+ * Provides async context creation for cross-platform compatibility:
+ * 1. Try better-sqlite3 native module first (fastest)
+ * 2. Fall back to sql.js WASM if native is unavailable
+ */
+import type { ToolContext, ToolContextOptions } from './context.types.js';
+/**
+ * Create the shared tool context asynchronously with WASM fallback
+ *
+ * This is the recommended way to initialize context for cross-platform
+ * compatibility. It will:
+ * 1. Try better-sqlite3 native module first (fastest)
+ * 2. Fall back to sql.js WASM if native is unavailable
+ *
+ * @param options - Configuration options
+ * @returns Promise resolving to initialized tool context
+ *
+ * @see SMI-898: Path traversal protection
+ * @see SMI-2207: Async initialization for WASM fallback
+ *
+ * @example
+ * // Initialize with WASM fallback support
+ * const context = await createToolContextAsync();
+ *
+ * @throws Error if dbPath contains path traversal attempt
+ * @throws Error if no database driver is available
+ */
+export declare function createToolContextAsync(options?: ToolContextOptions): Promise<ToolContext>;
+/**
+ * Get or create the global async tool context
+ *
+ * Uses a separate singleton from the sync version to prevent caching issues
+ * where the sync path might be triggered first and cached.
+ *
+ * @param options - Configuration options (only used on first call)
+ * @returns Promise resolving to the global tool context
+ */
+export declare function getToolContextAsync(options?: ToolContextOptions): Promise<ToolContext>;
+/**
+ * Reset the async global context (for testing)
+ */
+export declare function resetAsyncToolContext(): Promise<void>;
+//# sourceMappingURL=context.async.d.ts.map

package/dist/src/context.async.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.async.d.ts","sourceRoot":"","sources":["../../src/context.async.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AA0BH,OAAO,KAAK,EAAE,WAAW,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAA;AAKzE;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAsB,sBAAsB,CAC1C,OAAO,GAAE,kBAAuB,GAC/B,OAAO,CAAC,WAAW,CAAC,CAiLtB;AAED;;;;;;;;GAQG;AACH,wBAAsB,mBAAmB,CAAC,OAAO,CAAC,EAAE,kBAAkB,GAAG,OAAO,CAAC,WAAW,CAAC,CAS5F;AAED;;GAEG;AACH,wBAAsB,qBAAqB,IAAI,OAAO,CAAC,IAAI,CAAC,CAsB3D"}

package/dist/src/context.async.js

@@ -0,0 +1,215 @@
+/**
+ * @fileoverview Async Tool Context Creation with WASM Fallback
+ * @module @skillsmith/mcp-server/context.async
+ * @see SMI-2207: Async database functions with WASM fallback
+ * @see SMI-2741: Split from context.ts to meet 500-line standard
+ *
+ * Provides async context creation for cross-platform compatibility:
+ * 1. Try better-sqlite3 native module first (fastest)
+ * 2. Fall back to sql.js WASM if native is unavailable
+ */
+import { existsSync } from 'fs';
+import { createDatabaseAsync, openDatabaseAsync, initializeSchema, SearchService, SkillRepository, validateDbPath, SkillsmithApiClient, initializePostHog, shutdownPostHog, generateAnonymousId, SyncConfigRepository, SyncHistoryRepository, SyncEngine, SkillVersionRepository, CoInstallRepository, BackgroundSyncService, getApiKey, } from '@skillsmith/core';
+import { LLMFailoverChain } from './llm/failover.js';
+import { getDefaultDbPath, ensureDbDirectory } from './context.helpers.js';
+// Separate singleton for async context (prevents caching conflict with sync)
+let asyncGlobalContext = null;
+/**
+ * Create the shared tool context asynchronously with WASM fallback
+ *
+ * This is the recommended way to initialize context for cross-platform
+ * compatibility. It will:
+ * 1. Try better-sqlite3 native module first (fastest)
+ * 2. Fall back to sql.js WASM if native is unavailable
+ *
+ * @param options - Configuration options
+ * @returns Promise resolving to initialized tool context
+ *
+ * @see SMI-898: Path traversal protection
+ * @see SMI-2207: Async initialization for WASM fallback
+ *
+ * @example
+ * // Initialize with WASM fallback support
+ * const context = await createToolContextAsync();
+ *
+ * @throws Error if dbPath contains path traversal attempt
+ * @throws Error if no database driver is available
+ */
+export async function createToolContextAsync(options = {}) {
+    let dbPath;
+    if (options.dbPath) {
+        // SMI-898: Validate custom path for path traversal
+        const validation = validateDbPath(options.dbPath, {
+            allowInMemory: true,
+            allowTempDir: true,
+        });
+        if (!validation.valid) {
+            throw new Error(`Invalid database path: ${validation.error}. ` +
+                'Path must be within ~/.skillsmith, ~/.claude, or temp directories.');
+        }
+        dbPath = validation.resolvedPath;
+    }
+    else {
+        dbPath = getDefaultDbPath();
+    }
+    // Ensure directory exists (skip for in-memory)
+    if (dbPath !== ':memory:') {
+        ensureDbDirectory(dbPath);
+    }
+    // SMI-2207: Use async database creation with WASM fallback
+    let db;
+    if (dbPath !== ':memory:' && existsSync(dbPath)) {
+        db = await openDatabaseAsync(dbPath);
+    }
+    else {
+        db = await createDatabaseAsync(dbPath);
+        // SMI-2207: createDatabaseAsync returns a bare connection (no schema).
+        // openDatabaseAsync runs runMigrationsSafe internally; for new/in-memory
+        // databases we must call initializeSchema explicitly to match the sync path.
+        initializeSchema(db);
+    }
+    // Initialize services
+    const searchService = new SearchService(db, {
+        cacheTtl: options.searchCacheTtl ?? 300,
+    });
+    const skillRepository = new SkillRepository(db);
+    const coInstallRepository = new CoInstallRepository(db);
+    // SMI-1851: Use shared config module (handles env var > config file precedence)
+    const apiKey = options.apiKey || getApiKey();
+    // SMI-1183: Initialize API client with configuration
+    const apiClient = new SkillsmithApiClient({
+        baseUrl: options.apiClientConfig?.baseUrl,
+        anonKey: options.apiClientConfig?.anonKey,
+        apiKey,
+        timeout: options.apiClientConfig?.timeout ?? 10000,
+        maxRetries: options.apiClientConfig?.maxRetries ?? 3,
+        debug: options.apiClientConfig?.debug,
+        offlineMode: options.apiClientConfig?.offlineMode,
+    });
+    // SMI-1184: Initialize PostHog telemetry (opt-in, privacy first)
+    let distinctId;
+    const telemetryEnabled = process.env.SKILLSMITH_TELEMETRY_ENABLED === 'true' || options.telemetryConfig?.enabled === true;
+    const postHogApiKey = process.env.POSTHOG_API_KEY || options.telemetryConfig?.postHogApiKey;
+    if (telemetryEnabled && postHogApiKey) {
+        distinctId = generateAnonymousId();
+        initializePostHog({
+            apiKey: postHogApiKey,
+            host: options.telemetryConfig?.postHogHost,
+            disabled: false,
+        });
+    }
+    // Initialize background sync service if enabled
+    let backgroundSync;
+    const backgroundSyncEnabled = process.env.SKILLSMITH_BACKGROUND_SYNC !== 'false' &&
+        options.backgroundSyncConfig?.enabled !== false;
+    if (backgroundSyncEnabled) {
+        const syncConfigRepo = new SyncConfigRepository(db);
+        const syncHistoryRepo = new SyncHistoryRepository(db);
+        const skillVersionRepo = new SkillVersionRepository(db);
+        const syncConfig = syncConfigRepo.getConfig();
+        if (syncConfig.enabled) {
+            const syncEngine = new SyncEngine(apiClient, skillRepository, syncConfigRepo, syncHistoryRepo, skillVersionRepo);
+            backgroundSync = new BackgroundSyncService(syncEngine, syncConfigRepo, {
+                syncOnStart: true,
+                debug: options.backgroundSyncConfig?.debug ?? false,
+                onSyncComplete: (result) => {
+                    if (options.backgroundSyncConfig?.debug) {
+                        console.log(`[skillsmith] Background sync complete: ${result.skillsAdded} added, ${result.skillsUpdated} updated`);
+                    }
+                },
+                onSyncError: (error) => {
+                    if (options.backgroundSyncConfig?.debug) {
+                        console.error(`[skillsmith] Background sync error: ${error.message}`);
+                    }
+                },
+            });
+            backgroundSync.start();
+        }
+    }
+    // SMI-1524: Initialize LLM failover chain if enabled
+    let llmFailover;
+    const llmFailoverEnabled = process.env.SKILLSMITH_LLM_FAILOVER_ENABLED === 'true' ||
+        options.llmFailoverConfig?.enabled === true;
+    if (llmFailoverEnabled) {
+        llmFailover = new LLMFailoverChain({
+            ...options.llmFailoverConfig,
+            enabled: true,
+            debug: options.llmFailoverConfig?.debug ?? false,
+        });
+        llmFailover.initialize().catch((error) => {
+            console.error(`[skillsmith] LLM failover initialization error: ${error.message}`);
+        });
+        if (options.llmFailoverConfig?.debug) {
+            console.log('[skillsmith] LLM failover chain initialized');
+        }
+    }
+    // Create signal handlers for cleanup
+    const signalHandlers = [];
+    if (backgroundSync || llmFailover) {
+        const cleanup = () => {
+            backgroundSync?.stop();
+            llmFailover?.close();
+        };
+        const sigTermHandler = () => cleanup();
+        const sigIntHandler = () => cleanup();
+        process.on('SIGTERM', sigTermHandler);
+        process.on('SIGINT', sigIntHandler);
+        signalHandlers.push({ signal: 'SIGTERM', handler: sigTermHandler }, { signal: 'SIGINT', handler: sigIntHandler });
+    }
+    return {
+        db,
+        searchService,
+        skillRepository,
+        coInstallRepository,
+        sessionInstalledSkillIds: [],
+        apiClient,
+        distinctId,
+        backgroundSync,
+        llmFailover,
+        _signalHandlers: signalHandlers.length > 0 ? signalHandlers : undefined,
+    };
+}
+/**
+ * Get or create the global async tool context
+ *
+ * Uses a separate singleton from the sync version to prevent caching issues
+ * where the sync path might be triggered first and cached.
+ *
+ * @param options - Configuration options (only used on first call)
+ * @returns Promise resolving to the global tool context
+ */
+export async function getToolContextAsync(options) {
+    if (!asyncGlobalContext) {
+        asyncGlobalContext = await createToolContextAsync(options);
+    }
+    else if (options) {
+        console.warn('[skillsmith] getToolContextAsync called with options after context was already initialized. Options ignored.');
+    }
+    return asyncGlobalContext;
+}
+/**
+ * Reset the async global context (for testing)
+ */
+export async function resetAsyncToolContext() {
+    if (asyncGlobalContext) {
+        // Inline close to avoid circular import with context.ts
+        const context = asyncGlobalContext;
+        asyncGlobalContext = null;
+        if (context._signalHandlers) {
+            for (const { signal, handler } of context._signalHandlers) {
+                process.removeListener(signal, handler);
+            }
+        }
+        if (context.backgroundSync) {
+            context.backgroundSync.stop();
+        }
+        if (context.llmFailover) {
+            context.llmFailover.close();
+        }
+        context.db.close();
+        if (context.distinctId) {
+            await shutdownPostHog();
+        }
+    }
+}
+//# sourceMappingURL=context.async.js.map

package/dist/src/context.async.js.map

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

package/dist/src/context.d.ts

@@ -3,6 +3,7 @@
  * @module @skillsmith/mcp-server/context
  * @see SMI-792: Add database initialization to MCP server
  * @see SMI-898: Path traversal protection for DB_PATH
+ * @see SMI-2741: Async context split into context.async.ts to meet 500-line standard
  *
  * Provides shared context for MCP tool handlers including:
  * - SQLite database connection with FTS5 search
@@ -17,115 +18,10 @@
  * // Pass to tool handlers
  * const result = await executeSearch(input, context);
  */
-import { SearchService, SkillRepository, SkillsmithApiClient, BackgroundSyncService, type ApiClientConfig, type DatabaseType } from '@skillsmith/core';
-import { LLMFailoverChain, type LLMFailoverConfig } from './llm/failover.js';
-/**
- * Shared context for MCP tool handlers
- * SMI-1183: Added apiClient for live API access with local fallback
- * SMI-1184: Added distinctId for telemetry tracking
- * SMI-1524: Added llmFailover for multi-LLM support with circuit breaker
- */
-export interface ToolContext {
-    /** SQLite database connection */
-    db: DatabaseType;
-    /** Search service with FTS5/BM25 (fallback) */
-    searchService: SearchService;
-    /** Skill repository for CRUD operations (fallback) */
-    skillRepository: SkillRepository;
-    /** API client for live Supabase API (primary) */
-    apiClient: SkillsmithApiClient;
-    /** Anonymous user ID for telemetry (undefined if telemetry disabled) */
-    distinctId?: string;
-    /** Background sync service (if enabled) */
-    backgroundSync?: BackgroundSyncService;
-    /** LLM failover chain for multi-provider support (SMI-1524) */
-    llmFailover?: LLMFailoverChain;
-    /** Internal: Signal handlers for cleanup (prevents memory leaks) */
-    _signalHandlers?: Array<{
-        signal: NodeJS.Signals;
-        handler: () => void;
-    }>;
-}
-/**
- * Telemetry configuration for PostHog (SMI-1184)
- * Privacy-first: disabled by default (opt-in)
- */
-export interface TelemetryConfig {
-    /**
-     * Enable telemetry collection (default: false for privacy)
-     * Can also be set via SKILLSMITH_TELEMETRY_ENABLED env var
-     */
-    enabled?: boolean;
-    /**
-     * PostHog API key (starts with phc_)
-     * Can also be set via POSTHOG_API_KEY env var
-     */
-    postHogApiKey?: string;
-    /**
-     * PostHog host URL (default: https://app.posthog.com)
-     */
-    postHogHost?: string;
-}
-/**
- * Background sync configuration
- */
-export interface BackgroundSyncConfig {
-    /**
-     * Enable background sync during MCP server sessions
-     * Can also be set via SKILLSMITH_BACKGROUND_SYNC env var
-     * Default: true (syncs if config.enabled is true)
-     */
-    enabled?: boolean;
-    /**
-     * Enable debug logging for sync operations
-     */
-    debug?: boolean;
-}
-/**
- * Options for creating tool context
- */
-export interface ToolContextOptions {
-    /** Custom database path (defaults to ~/.skillsmith/skills.db) */
-    dbPath?: string;
-    /** Search cache TTL in seconds (default: 300) */
-    searchCacheTtl?: number;
-    /** API client configuration (SMI-1183) */
-    apiClientConfig?: ApiClientConfig;
-    /**
-     * API key for authenticated requests
-     * Can also be set via SKILLSMITH_API_KEY env var
-     * SMI-XXXX: API Key Authentication
-     */
-    apiKey?: string;
-    /**
-     * Telemetry configuration (SMI-1184)
-     * Privacy-first: telemetry is OPT-IN and disabled by default
-     */
-    telemetryConfig?: TelemetryConfig;
-    /**
-     * Background sync configuration
-     * Enables automatic registry sync during MCP server sessions
-     */
-    backgroundSyncConfig?: BackgroundSyncConfig;
-    /**
-     * LLM failover chain configuration (SMI-1524)
-     * Enables multi-provider LLM support with automatic failover
-     * Disabled by default - set enabled: true to activate
-     */
-    llmFailoverConfig?: LLMFailoverConfig;
-}
-/**
- * Get the default database path
- * Respects SKILLSMITH_DB_PATH environment variable
- *
- * @see SMI-898: Path traversal protection
- * - Validates SKILLSMITH_DB_PATH against path traversal attacks
- * - Rejects paths with ".." traversal sequences
- * - Ensures path is within allowed directories
- *
- * @throws Error if SKILLSMITH_DB_PATH contains path traversal attempt
- */
-export declare function getDefaultDbPath(): string;
+export type { ToolContext, TelemetryConfig, BackgroundSyncConfig, ToolContextOptions, } from './context.types.js';
+export { getDefaultDbPath, ensureDbDirectory } from './context.helpers.js';
+export { createToolContextAsync, getToolContextAsync, resetAsyncToolContext, } from './context.async.js';
+import type { ToolContext, ToolContextOptions } from './context.types.js';
 /**
  * Create the shared tool context with database and services
  *
@@ -175,40 +71,4 @@ export declare function getToolContext(options?: ToolContextOptions): ToolContex
  * SMI-1184: Made async to properly shutdown PostHog
  */
 export declare function resetToolContext(): Promise<void>;
-/**
- * Create the shared tool context asynchronously with WASM fallback
- *
- * This is the recommended way to initialize context for cross-platform
- * compatibility. It will:
- * 1. Try better-sqlite3 native module first (fastest)
- * 2. Fall back to sql.js WASM if native is unavailable
- *
- * @param options - Configuration options
- * @returns Promise resolving to initialized tool context
- *
- * @see SMI-898: Path traversal protection
- * @see SMI-2207: Async initialization for WASM fallback
- *
- * @example
- * // Initialize with WASM fallback support
- * const context = await createToolContextAsync();
- *
- * @throws Error if dbPath contains path traversal attempt
- * @throws Error if no database driver is available
- */
-export declare function createToolContextAsync(options?: ToolContextOptions): Promise<ToolContext>;
-/**
- * Get or create the global async tool context
- *
- * Uses a separate singleton from the sync version to prevent caching issues
- * where the sync path might be triggered first and cached.
- *
- * @param options - Configuration options (only used on first call)
- * @returns Promise resolving to the global tool context
- */
-export declare function getToolContextAsync(options?: ToolContextOptions): Promise<ToolContext>;
-/**
- * Reset the async global context (for testing)
- */
-export declare function resetAsyncToolContext(): Promise<void>;
 //# sourceMappingURL=context.d.ts.map

package/dist/src/context.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../src/context.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAKH,OAAO,EAOL,aAAa,EACb,eAAe,EAEf,mBAAmB,EAOnB,qBAAqB,EAErB,KAAK,eAAe,EAEpB,KAAK,YAAY,EAClB,MAAM,kBAAkB,CAAA;AACzB,OAAO,EAAE,gBAAgB,EAAE,KAAK,iBAAiB,EAAE,MAAM,mBAAmB,CAAA;AAE5E;;;;;GAKG;AACH,MAAM,WAAW,WAAW;IAC1B,iCAAiC;IACjC,EAAE,EAAE,YAAY,CAAA;IAChB,+CAA+C;IAC/C,aAAa,EAAE,aAAa,CAAA;IAC5B,sDAAsD;IACtD,eAAe,EAAE,eAAe,CAAA;IAChC,iDAAiD;IACjD,SAAS,EAAE,mBAAmB,CAAA;IAC9B,wEAAwE;IACxE,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,2CAA2C;IAC3C,cAAc,CAAC,EAAE,qBAAqB,CAAA;IACtC,+DAA+D;IAC/D,WAAW,CAAC,EAAE,gBAAgB,CAAA;IAC9B,oEAAoE;IACpE,eAAe,CAAC,EAAE,KAAK,CAAC;QAAE,MAAM,EAAE,MAAM,CAAC,OAAO,CAAC;QAAC,OAAO,EAAE,MAAM,IAAI,CAAA;KAAE,CAAC,CAAA;CACzE;AAED;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B;;;OAGG;IACH,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB;;OAEG;IACH,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC;;;;OAIG;IACH,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB;;OAEG;IACH,KAAK,CAAC,EAAE,OAAO,CAAA;CAChB;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,iEAAiE;IACjE,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,iDAAiD;IACjD,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,0CAA0C;IAC1C,eAAe,CAAC,EAAE,eAAe,CAAA;IACjC;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,CAAA;IACf;;;OAGG;IACH,eAAe,CAAC,EAAE,eAAe,CAAA;IACjC;;;OAGG;IACH,oBAAoB,CAAC,EAAE,oBAAoB,CAAA;IAC3C;;;;OAIG;IACH,iBAAiB,CAAC,EAAE,iBAAiB,CAAA;CACtC;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,IAAI,MAAM,CAqBzC;AAeD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,GAAE,kBAAuB,GAAG,WAAW,CA+K/E;AAED;;;;;;GAMG;AACH,wBAAsB,gBAAgB,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAyB1E;AAKD;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAAC,OAAO,CAAC,EAAE,kBAAkB,GAAG,WAAW,CAUxE;AAED;;;GAGG;AACH,wBAAsB,gBAAgB,IAAI,OAAO,CAAC,IAAI,CAAC,CAKtD;AASD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAsB,sBAAsB,CAC1C,OAAO,GAAE,kBAAuB,GAC/B,OAAO,CAAC,WAAW,CAAC,CAuKtB;AAED;;;;;;;;GAQG;AACH,wBAAsB,mBAAmB,CAAC,OAAO,CAAC,EAAE,kBAAkB,GAAG,OAAO,CAAC,WAAW,CAAC,CAS5F;AAED;;GAEG;AACH,wBAAsB,qBAAqB,IAAI,OAAO,CAAC,IAAI,CAAC,CAK3D"}
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../src/context.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AA2BH,YAAY,EACV,WAAW,EACX,eAAe,EACf,oBAAoB,EACpB,kBAAkB,GACnB,MAAM,oBAAoB,CAAA;AAC3B,OAAO,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAA;AAC1E,OAAO,EACL,sBAAsB,EACtB,mBAAmB,EACnB,qBAAqB,GACtB,MAAM,oBAAoB,CAAA;AAG3B,OAAO,KAAK,EAAE,WAAW,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAA;AAEzE;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,GAAE,kBAAuB,GAAG,WAAW,CAyL/E;AAED;;;;;;GAMG;AACH,wBAAsB,gBAAgB,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAyB1E;AAKD;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAAC,OAAO,CAAC,EAAE,kBAAkB,GAAG,WAAW,CAUxE;AAED;;;GAGG;AACH,wBAAsB,gBAAgB,IAAI,OAAO,CAAC,IAAI,CAAC,CAKtD"}

package/dist/src/context.helpers.d.ts

@@ -0,0 +1,25 @@
+/**
+ * @fileoverview Tool Context Helper Utilities
+ * @module @skillsmith/mcp-server/context.helpers
+ * @see SMI-898: Path traversal protection for DB_PATH
+ * @see SMI-2741: Split from context.ts to meet 500-line standard
+ *
+ * Shared helpers used by both sync and async context creation.
+ */
+/**
+ * Get the default database path
+ * Respects SKILLSMITH_DB_PATH environment variable
+ *
+ * @see SMI-898: Path traversal protection
+ * - Validates SKILLSMITH_DB_PATH against path traversal attacks
+ * - Rejects paths with ".." traversal sequences
+ * - Ensures path is within allowed directories
+ *
+ * @throws Error if SKILLSMITH_DB_PATH contains path traversal attempt
+ */
+export declare function getDefaultDbPath(): string;
+/**
+ * Ensure the database directory exists
+ */
+export declare function ensureDbDirectory(dbPath: string): void;
+//# sourceMappingURL=context.helpers.d.ts.map

package/dist/src/context.helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.helpers.d.ts","sourceRoot":"","sources":["../../src/context.helpers.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAOH;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,IAAI,MAAM,CAqBzC;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAKtD"}

package/dist/src/context.helpers.js

@@ -0,0 +1,49 @@
+/**
+ * @fileoverview Tool Context Helper Utilities
+ * @module @skillsmith/mcp-server/context.helpers
+ * @see SMI-898: Path traversal protection for DB_PATH
+ * @see SMI-2741: Split from context.ts to meet 500-line standard
+ *
+ * Shared helpers used by both sync and async context creation.
+ */
+import { homedir } from 'os';
+import { join, dirname } from 'path';
+import { mkdirSync, existsSync } from 'fs';
+import { validateDbPath } from '@skillsmith/core';
+/**
+ * Get the default database path
+ * Respects SKILLSMITH_DB_PATH environment variable
+ *
+ * @see SMI-898: Path traversal protection
+ * - Validates SKILLSMITH_DB_PATH against path traversal attacks
+ * - Rejects paths with ".." traversal sequences
+ * - Ensures path is within allowed directories
+ *
+ * @throws Error if SKILLSMITH_DB_PATH contains path traversal attempt
+ */
+export function getDefaultDbPath() {
+    const envPath = process.env.SKILLSMITH_DB_PATH;
+    if (envPath) {
+        // SMI-898: Validate environment variable path for path traversal
+        const validation = validateDbPath(envPath, {
+            allowInMemory: true,
+            allowTempDir: true,
+        });
+        if (!validation.valid) {
+            throw new Error(`Invalid SKILLSMITH_DB_PATH: ${validation.error}. ` +
+                'Path must be within ~/.skillsmith, ~/.claude, or temp directories.');
+        }
+        return validation.resolvedPath;
+    }
+    return join(homedir(), '.skillsmith', 'skills.db');
+}
+/**
+ * Ensure the database directory exists
+ */
+export function ensureDbDirectory(dbPath) {
+    const dir = dirname(dbPath);
+    if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true });
+    }
+}
+//# sourceMappingURL=context.helpers.js.map

package/dist/src/context.helpers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.helpers.js","sourceRoot":"","sources":["../../src/context.helpers.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,IAAI,CAAA;AAC5B,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,MAAM,CAAA;AACpC,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,IAAI,CAAA;AAC1C,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAA;AAEjD;;;;;;;;;;GAUG;AACH,MAAM,UAAU,gBAAgB;IAC9B,MAAM,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC,kBAAkB,CAAA;IAE9C,IAAI,OAAO,EAAE,CAAC;QACZ,iEAAiE;QACjE,MAAM,UAAU,GAAG,cAAc,CAAC,OAAO,EAAE;YACzC,aAAa,EAAE,IAAI;YACnB,YAAY,EAAE,IAAI;SACnB,CAAC,CAAA;QAEF,IAAI,CAAC,UAAU,CAAC,KAAK,EAAE,CAAC;YACtB,MAAM,IAAI,KAAK,CACb,+BAA+B,UAAU,CAAC,KAAK,IAAI;gBACjD,oEAAoE,CACvE,CAAA;QACH,CAAC;QAED,OAAO,UAAU,CAAC,YAAa,CAAA;IACjC,CAAC;IAED,OAAO,IAAI,CAAC,OAAO,EAAE,EAAE,aAAa,EAAE,WAAW,CAAC,CAAA;AACpD,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,iBAAiB,CAAC,MAAc;IAC9C,MAAM,GAAG,GAAG,OAAO,CAAC,MAAM,CAAC,CAAA;IAC3B,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;QACrB,SAAS,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAA;IACrC,CAAC;AACH,CAAC"}