@skillsmith/core 0.5.5 → 0.5.6

package/dist/utils/rate-limit.test.js.map

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

package/dist/utils/retry.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Retry Utility - SMI-880
+ *
+ * Exponential backoff retry logic for transient network failures.
+ * Handles ETIMEDOUT, ECONNRESET, and 5xx HTTP errors.
+ */
+/**
+ * Configuration for retry behavior
+ */
+export interface RetryConfig {
+    /** Maximum number of retry attempts (default: 3) */
+    maxRetries?: number;
+    /** Initial delay in milliseconds (default: 1000) */
+    initialDelayMs?: number;
+    /** Maximum delay in milliseconds (default: 30000) */
+    maxDelayMs?: number;
+    /** Backoff multiplier (default: 2) */
+    backoffMultiplier?: number;
+    /** Add jitter to prevent thundering herd (default: true) */
+    jitter?: boolean;
+    /** Custom function to determine if error is retryable */
+    isRetryable?: (error: unknown) => boolean;
+    /** Callback on each retry attempt */
+    onRetry?: (attempt: number, error: unknown, delayMs: number) => void;
+}
+/**
+ * Default retry configuration
+ */
+export declare const DEFAULT_RETRY_CONFIG: Required<Omit<RetryConfig, 'isRetryable' | 'onRetry'>>;
+/**
+ * Determines if an error is a transient network error
+ */
+export declare function isTransientError(error: unknown): boolean;
+/**
+ * Determines if an HTTP response status is retryable
+ */
+export declare function isRetryableStatus(status: number): boolean;
+/**
+ * Error class for retry exhaustion.
+ *
+ * Note: This class is exported for use by external callers who may want to
+ * wrap retry failures in a structured error type. The withRetry function
+ * itself throws the original error when retries are exhausted, allowing
+ * callers to handle the specific error type rather than a generic wrapper.
+ */
+export declare class RetryExhaustedError extends Error {
+    readonly attempts: number;
+    readonly lastError: unknown;
+    constructor(message: string, attempts: number, lastError: unknown);
+}
+/**
+ * Retry a function with exponential backoff
+ *
+ * @param fn - Async function to retry
+ * @param config - Retry configuration
+ * @returns Result of the function
+ * @throws The original error when retries are exhausted or error is not retryable
+ *
+ * @example
+ * ```typescript
+ * const result = await withRetry(
+ *   () => fetch('https://api.example.com/data'),
+ *   { maxRetries: 3, initialDelayMs: 1000 }
+ * )
+ * ```
+ */
+export declare function withRetry<T>(fn: () => Promise<T>, config?: RetryConfig): Promise<T>;
+/**
+ * Retry a fetch request with exponential backoff
+ *
+ * Automatically retries on:
+ * - Network errors (ETIMEDOUT, ECONNRESET, etc.)
+ * - 5xx HTTP errors
+ * - 429 Too Many Requests (with Retry-After header support)
+ *
+ * @param url - URL to fetch
+ * @param options - Fetch options
+ * @param retryConfig - Retry configuration
+ * @returns Fetch Response
+ *
+ * @example
+ * ```typescript
+ * const response = await fetchWithRetry(
+ *   'https://api.github.com/repos/owner/repo',
+ *   { headers: { Authorization: 'token xxx' } },
+ *   { maxRetries: 3 }
+ * )
+ * ```
+ */
+export declare function fetchWithRetry(url: string, options?: RequestInit, retryConfig?: RetryConfig): Promise<Response>;
+/**
+ * Parse Retry-After header value
+ * @param value - Retry-After header value (seconds or HTTP-date)
+ * @returns Delay in milliseconds, or null if invalid
+ */
+export declare function parseRetryAfter(value: string | null): number | null;
+//# sourceMappingURL=retry.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"retry.d.ts","sourceRoot":"","sources":["../../src/utils/retry.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAMH;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,oDAAoD;IACpD,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,oDAAoD;IACpD,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,qDAAqD;IACrD,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,sCAAsC;IACtC,iBAAiB,CAAC,EAAE,MAAM,CAAA;IAC1B,4DAA4D;IAC5D,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB,yDAAyD;IACzD,WAAW,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,OAAO,CAAA;IACzC,qCAAqC;IACrC,OAAO,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,KAAK,IAAI,CAAA;CACrE;AAED;;GAEG;AACH,eAAO,MAAM,oBAAoB,EAAE,QAAQ,CAAC,IAAI,CAAC,WAAW,EAAE,aAAa,GAAG,SAAS,CAAC,CAMvF,CAAA;AA4BD;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAoBxD;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAEzD;AAED;;;;;;;GAOG;AACH,qBAAa,mBAAoB,SAAQ,KAAK;aAG1B,QAAQ,EAAE,MAAM;aAChB,SAAS,EAAE,OAAO;gBAFlC,OAAO,EAAE,MAAM,EACC,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,OAAO;CASrC;AAkCD;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,SAAS,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EAAE,MAAM,GAAE,WAAgB,GAAG,OAAO,CAAC,CAAC,CAAC,CAiD7F;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAsB,cAAc,CAClC,GAAG,EAAE,MAAM,EACX,OAAO,CAAC,EAAE,WAAW,EACrB,WAAW,GAAE,WAAgB,GAC5B,OAAO,CAAC,QAAQ,CAAC,CA8CnB;AAeD;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,GAAG,IAAI,CA2BnE"}

package/dist/utils/retry.js

@@ -0,0 +1,267 @@
+/**
+ * Retry Utility - SMI-880
+ *
+ * Exponential backoff retry logic for transient network failures.
+ * Handles ETIMEDOUT, ECONNRESET, and 5xx HTTP errors.
+ */
+import { createLogger } from './logger.js';
+const log = createLogger('RetryUtil');
+/**
+ * Default retry configuration
+ */
+export const DEFAULT_RETRY_CONFIG = {
+    maxRetries: 3,
+    initialDelayMs: 1000,
+    maxDelayMs: 30000,
+    backoffMultiplier: 2,
+    jitter: true,
+};
+/**
+ * Error codes that indicate transient network failures
+ */
+const TRANSIENT_ERROR_CODES = new Set([
+    'ETIMEDOUT',
+    'ECONNRESET',
+    'ECONNREFUSED',
+    'ENOTFOUND',
+    'ENETUNREACH',
+    'EHOSTUNREACH',
+    'EPIPE',
+    'EAI_AGAIN',
+]);
+/**
+ * HTTP status codes that are retryable
+ */
+const RETRYABLE_STATUS_CODES = new Set([
+    408, // Request Timeout
+    429, // Too Many Requests
+    500, // Internal Server Error
+    502, // Bad Gateway
+    503, // Service Unavailable
+    504, // Gateway Timeout
+]);
+/**
+ * Determines if an error is a transient network error
+ */
+export function isTransientError(error) {
+    if (error instanceof Error) {
+        // Check for Node.js network error codes
+        const code = error.code;
+        if (code && TRANSIENT_ERROR_CODES.has(code)) {
+            return true;
+        }
+        // Check for fetch abort errors (timeout)
+        if (error.name === 'AbortError') {
+            return true;
+        }
+        // Check for network errors in fetch
+        if (error.message.includes('network') || error.message.includes('fetch failed')) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Determines if an HTTP response status is retryable
+ */
+export function isRetryableStatus(status) {
+    return RETRYABLE_STATUS_CODES.has(status);
+}
+/**
+ * Error class for retry exhaustion.
+ *
+ * Note: This class is exported for use by external callers who may want to
+ * wrap retry failures in a structured error type. The withRetry function
+ * itself throws the original error when retries are exhausted, allowing
+ * callers to handle the specific error type rather than a generic wrapper.
+ */
+export class RetryExhaustedError extends Error {
+    attempts;
+    lastError;
+    constructor(message, attempts, lastError) {
+        super(message);
+        this.attempts = attempts;
+        this.lastError = lastError;
+        this.name = 'RetryExhaustedError';
+        // Preserve cause chain
+        if (lastError instanceof Error) {
+            this.cause = lastError;
+        }
+    }
+}
+/**
+ * Calculate delay with exponential backoff and optional jitter
+ */
+function calculateDelay(attempt, initialDelayMs, maxDelayMs, backoffMultiplier, jitter) {
+    // Exponential backoff: initialDelay * (multiplier ^ attempt)
+    let delay = initialDelayMs * Math.pow(backoffMultiplier, attempt);
+    // Cap at max delay
+    delay = Math.min(delay, maxDelayMs);
+    // Add jitter (±25%) to prevent thundering herd
+    if (jitter) {
+        const jitterFactor = 0.75 + Math.random() * 0.5; // 0.75 to 1.25
+        delay = Math.floor(delay * jitterFactor);
+    }
+    return delay;
+}
+/**
+ * Sleep for a specified duration
+ */
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+ * Retry a function with exponential backoff
+ *
+ * @param fn - Async function to retry
+ * @param config - Retry configuration
+ * @returns Result of the function
+ * @throws The original error when retries are exhausted or error is not retryable
+ *
+ * @example
+ * ```typescript
+ * const result = await withRetry(
+ *   () => fetch('https://api.example.com/data'),
+ *   { maxRetries: 3, initialDelayMs: 1000 }
+ * )
+ * ```
+ */
+export async function withRetry(fn, config = {}) {
+    const { maxRetries = DEFAULT_RETRY_CONFIG.maxRetries, initialDelayMs = DEFAULT_RETRY_CONFIG.initialDelayMs, maxDelayMs = DEFAULT_RETRY_CONFIG.maxDelayMs, backoffMultiplier = DEFAULT_RETRY_CONFIG.backoffMultiplier, jitter = DEFAULT_RETRY_CONFIG.jitter, isRetryable = isTransientError, onRetry, } = config;
+    let _lastError;
+    for (let attempt = 0; attempt <= maxRetries; attempt++) {
+        try {
+            return await fn();
+        }
+        catch (error) {
+            _lastError = error;
+            // Check if we should retry
+            if (attempt >= maxRetries || !isRetryable(error)) {
+                throw error;
+            }
+            // Calculate delay for this attempt
+            const delayMs = calculateDelay(attempt, initialDelayMs, maxDelayMs, backoffMultiplier, jitter);
+            // Log retry attempt
+            log.debug(`Retry attempt ${attempt + 1}/${maxRetries}`, {
+                error: error instanceof Error ? error.message : String(error),
+                delayMs,
+            });
+            // Call retry callback if provided
+            if (onRetry) {
+                onRetry(attempt + 1, error, delayMs);
+            }
+            // Wait before retrying
+            await sleep(delayMs);
+        }
+    }
+    // This point is unreachable: the loop always exits via return (on success)
+    // or throw (when retries exhausted or error not retryable). The loop runs
+    // attempt from 0 to maxRetries inclusive. On the final iteration
+    // (attempt === maxRetries), if fn() throws, the condition `attempt >= maxRetries`
+    // is true, causing the original error to be thrown immediately.
+    throw new Error('Unreachable: loop invariant violated');
+}
+/**
+ * Retry a fetch request with exponential backoff
+ *
+ * Automatically retries on:
+ * - Network errors (ETIMEDOUT, ECONNRESET, etc.)
+ * - 5xx HTTP errors
+ * - 429 Too Many Requests (with Retry-After header support)
+ *
+ * @param url - URL to fetch
+ * @param options - Fetch options
+ * @param retryConfig - Retry configuration
+ * @returns Fetch Response
+ *
+ * @example
+ * ```typescript
+ * const response = await fetchWithRetry(
+ *   'https://api.github.com/repos/owner/repo',
+ *   { headers: { Authorization: 'token xxx' } },
+ *   { maxRetries: 3 }
+ * )
+ * ```
+ */
+export async function fetchWithRetry(url, options, retryConfig = {}) {
+    const config = {
+        ...retryConfig,
+        isRetryable: (error) => {
+            // Check for network errors
+            if (isTransientError(error)) {
+                return true;
+            }
+            // Check for HTTP response errors (from our custom throw below)
+            if (error instanceof HttpRetryableError) {
+                return true;
+            }
+            return false;
+        },
+    };
+    return withRetry(async () => {
+        const response = await fetch(url, options);
+        // Check if we should retry based on status code
+        if (isRetryableStatus(response.status)) {
+            // Check for Retry-After header
+            const retryAfter = response.headers.get('Retry-After');
+            const retryAfterMs = parseRetryAfter(retryAfter);
+            if (retryAfterMs !== null && retryAfterMs > 0) {
+                // SMI-1029: Double-delay behavior is intentional
+                // We sleep here for the Retry-After duration, then throw HttpRetryableError.
+                // When withRetry catches this error, it will apply its own exponential backoff
+                // delay before the next attempt. This results in a total delay of:
+                //   Retry-After + exponential backoff
+                //
+                // This is by design for two reasons:
+                // 1. Safety margin: The server's Retry-After is a minimum; adding backoff
+                //    provides buffer for clock skew and processing time.
+                // 2. Thundering herd prevention: If many clients received the same Retry-After,
+                //    the additional jittered backoff spreads out retry attempts.
+                await sleep(retryAfterMs);
+            }
+            throw new HttpRetryableError(response.status, `HTTP ${response.status} - retryable`);
+        }
+        return response;
+    }, config);
+}
+/**
+ * Error thrown for HTTP responses that should be retried
+ */
+class HttpRetryableError extends Error {
+    status;
+    constructor(status, message) {
+        super(message);
+        this.status = status;
+        this.name = 'HttpRetryableError';
+    }
+}
+/**
+ * Parse Retry-After header value
+ * @param value - Retry-After header value (seconds or HTTP-date)
+ * @returns Delay in milliseconds, or null if invalid
+ */
+export function parseRetryAfter(value) {
+    if (value === null || value.trim() === '') {
+        return null;
+    }
+    const trimmed = value.trim();
+    // Try parsing as seconds (must be non-negative integer string)
+    // Matches only pure integer strings like "120", not "12.5" or "12abc"
+    if (/^-?\d+$/.test(trimmed)) {
+        const seconds = parseInt(trimmed, 10);
+        if (seconds < 0) {
+            return null;
+        }
+        return seconds * 1000;
+    }
+    // Try parsing as HTTP-date (must contain letters, e.g., "Wed, 21 Oct 2015 07:28:00 GMT")
+    // This prevents numeric-like strings like "12.5" from being parsed as dates
+    if (/[a-zA-Z]/.test(trimmed)) {
+        const date = Date.parse(trimmed);
+        if (!isNaN(date)) {
+            return Math.max(0, date - Date.now());
+        }
+    }
+    return null;
+}
+//# sourceMappingURL=retry.js.map

package/dist/utils/retry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry.js","sourceRoot":"","sources":["../../src/utils/retry.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAE1C,MAAM,GAAG,GAAG,YAAY,CAAC,WAAW,CAAC,CAAA;AAsBrC;;GAEG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAA2D;IAC1F,UAAU,EAAE,CAAC;IACb,cAAc,EAAE,IAAI;IACpB,UAAU,EAAE,KAAK;IACjB,iBAAiB,EAAE,CAAC;IACpB,MAAM,EAAE,IAAI;CACb,CAAA;AAED;;GAEG;AACH,MAAM,qBAAqB,GAAG,IAAI,GAAG,CAAC;IACpC,WAAW;IACX,YAAY;IACZ,cAAc;IACd,WAAW;IACX,aAAa;IACb,cAAc;IACd,OAAO;IACP,WAAW;CACZ,CAAC,CAAA;AAEF;;GAEG;AACH,MAAM,sBAAsB,GAAG,IAAI,GAAG,CAAC;IACrC,GAAG,EAAE,kBAAkB;IACvB,GAAG,EAAE,oBAAoB;IACzB,GAAG,EAAE,wBAAwB;IAC7B,GAAG,EAAE,cAAc;IACnB,GAAG,EAAE,sBAAsB;IAC3B,GAAG,EAAE,kBAAkB;CACxB,CAAC,CAAA;AAEF;;GAEG;AACH,MAAM,UAAU,gBAAgB,CAAC,KAAc;IAC7C,IAAI,KAAK,YAAY,KAAK,EAAE,CAAC;QAC3B,wCAAwC;QACxC,MAAM,IAAI,GAAI,KAA+B,CAAC,IAAI,CAAA;QAClD,IAAI,IAAI,IAAI,qBAAqB,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;YAC5C,OAAO,IAAI,CAAA;QACb,CAAC;QAED,yCAAyC;QACzC,IAAI,KAAK,CAAC,IAAI,KAAK,YAAY,EAAE,CAAC;YAChC,OAAO,IAAI,CAAA;QACb,CAAC;QAED,oCAAoC;QACpC,IAAI,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAC,IAAI,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAC,EAAE,CAAC;YAChF,OAAO,IAAI,CAAA;QACb,CAAC;IACH,CAAC;IAED,OAAO,KAAK,CAAA;AACd,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,iBAAiB,CAAC,MAAc;IAC9C,OAAO,sBAAsB,CAAC,GAAG,CAAC,MAAM,CAAC,CAAA;AAC3C,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,OAAO,mBAAoB,SAAQ,KAAK;IAG1B;IACA;IAHlB,YACE,OAAe,EACC,QAAgB,EAChB,SAAkB;QAElC,KAAK,CAAC,OAAO,CAAC,CAAA;QAHE,aAAQ,GAAR,QAAQ,CAAQ;QAChB,cAAS,GAAT,SAAS,CAAS;QAGlC,IAAI,CAAC,IAAI,GAAG,qBAAqB,CAAA;QACjC,uBAAuB;QACvB,IAAI,SAAS,YAAY,KAAK,EAAE,CAAC;YAC/B,IAAI,CAAC,KAAK,GAAG,SAAS,CAAA;QACxB,CAAC;IACH,CAAC;CACF;AAED;;GAEG;AACH,SAAS,cAAc,CACrB,OAAe,EACf,cAAsB,EACtB,UAAkB,EAClB,iBAAyB,EACzB,MAAe;IAEf,6DAA6D;IAC7D,IAAI,KAAK,GAAG,cAAc,GAAG,IAAI,CAAC,GAAG,CAAC,iBAAiB,EAAE,OAAO,CAAC,CAAA;IAEjE,mBAAmB;IACnB,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,UAAU,CAAC,CAAA;IAEnC,+CAA+C;IAC/C,IAAI,MAAM,EAAE,CAAC;QACX,MAAM,YAAY,GAAG,IAAI,GAAG,IAAI,CAAC,MAAM,EAAE,GAAG,GAAG,CAAA,CAAC,eAAe;QAC/D,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,GAAG,YAAY,CAAC,CAAA;IAC1C,CAAC;IAED,OAAO,KAAK,CAAA;AACd,CAAC;AAED;;GAEG;AACH,SAAS,KAAK,CAAC,EAAU;IACvB,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,CAAA;AAC1D,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,CAAC,KAAK,UAAU,SAAS,CAAI,EAAoB,EAAE,SAAsB,EAAE;IAC/E,MAAM,EACJ,UAAU,GAAG,oBAAoB,CAAC,UAAU,EAC5C,cAAc,GAAG,oBAAoB,CAAC,cAAc,EACpD,UAAU,GAAG,oBAAoB,CAAC,UAAU,EAC5C,iBAAiB,GAAG,oBAAoB,CAAC,iBAAiB,EAC1D,MAAM,GAAG,oBAAoB,CAAC,MAAM,EACpC,WAAW,GAAG,gBAAgB,EAC9B,OAAO,GACR,GAAG,MAAM,CAAA;IAEV,IAAI,UAAmB,CAAA;IAEvB,KAAK,IAAI,OAAO,GAAG,CAAC,EAAE,OAAO,IAAI,UAAU,EAAE,OAAO,EAAE,EAAE,CAAC;QACvD,IAAI,CAAC;YACH,OAAO,MAAM,EAAE,EAAE,CAAA;QACnB,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,UAAU,GAAG,KAAK,CAAA;YAElB,2BAA2B;YAC3B,IAAI,OAAO,IAAI,UAAU,IAAI,CAAC,WAAW,CAAC,KAAK,CAAC,EAAE,CAAC;gBACjD,MAAM,KAAK,CAAA;YACb,CAAC;YAED,mCAAmC;YACnC,MAAM,OAAO,GAAG,cAAc,CAAC,OAAO,EAAE,cAAc,EAAE,UAAU,EAAE,iBAAiB,EAAE,MAAM,CAAC,CAAA;YAE9F,oBAAoB;YACpB,GAAG,CAAC,KAAK,CAAC,iBAAiB,OAAO,GAAG,CAAC,IAAI,UAAU,EAAE,EAAE;gBACtD,KAAK,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC;gBAC7D,OAAO;aACR,CAAC,CAAA;YAEF,kCAAkC;YAClC,IAAI,OAAO,EAAE,CAAC;gBACZ,OAAO,CAAC,OAAO,GAAG,CAAC,EAAE,KAAK,EAAE,OAAO,CAAC,CAAA;YACtC,CAAC;YAED,uBAAuB;YACvB,MAAM,KAAK,CAAC,OAAO,CAAC,CAAA;QACtB,CAAC;IACH,CAAC;IAED,2EAA2E;IAC3E,0EAA0E;IAC1E,iEAAiE;IACjE,kFAAkF;IAClF,gEAAgE;IAChE,MAAM,IAAI,KAAK,CAAC,sCAAsC,CAAC,CAAA;AACzD,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAClC,GAAW,EACX,OAAqB,EACrB,cAA2B,EAAE;IAE7B,MAAM,MAAM,GAAgB;QAC1B,GAAG,WAAW;QACd,WAAW,EAAE,CAAC,KAAK,EAAE,EAAE;YACrB,2BAA2B;YAC3B,IAAI,gBAAgB,CAAC,KAAK,CAAC,EAAE,CAAC;gBAC5B,OAAO,IAAI,CAAA;YACb,CAAC;YAED,+DAA+D;YAC/D,IAAI,KAAK,YAAY,kBAAkB,EAAE,CAAC;gBACxC,OAAO,IAAI,CAAA;YACb,CAAC;YAED,OAAO,KAAK,CAAA;QACd,CAAC;KACF,CAAA;IAED,OAAO,SAAS,CAAC,KAAK,IAAI,EAAE;QAC1B,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,GAAG,EAAE,OAAO,CAAC,CAAA;QAE1C,gDAAgD;QAChD,IAAI,iBAAiB,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC;YACvC,+BAA+B;YAC/B,MAAM,UAAU,GAAG,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,aAAa,CAAC,CAAA;YACtD,MAAM,YAAY,GAAG,eAAe,CAAC,UAAU,CAAC,CAAA;YAChD,IAAI,YAAY,KAAK,IAAI,IAAI,YAAY,GAAG,CAAC,EAAE,CAAC;gBAC9C,iDAAiD;gBACjD,6EAA6E;gBAC7E,+EAA+E;gBAC/E,mEAAmE;gBACnE,sCAAsC;gBACtC,EAAE;gBACF,qCAAqC;gBACrC,0EAA0E;gBAC1E,yDAAyD;gBACzD,gFAAgF;gBAChF,iEAAiE;gBACjE,MAAM,KAAK,CAAC,YAAY,CAAC,CAAA;YAC3B,CAAC;YAED,MAAM,IAAI,kBAAkB,CAAC,QAAQ,CAAC,MAAM,EAAE,QAAQ,QAAQ,CAAC,MAAM,cAAc,CAAC,CAAA;QACtF,CAAC;QAED,OAAO,QAAQ,CAAA;IACjB,CAAC,EAAE,MAAM,CAAC,CAAA;AACZ,CAAC;AAED;;GAEG;AACH,MAAM,kBAAmB,SAAQ,KAAK;IAElB;IADlB,YACkB,MAAc,EAC9B,OAAe;QAEf,KAAK,CAAC,OAAO,CAAC,CAAA;QAHE,WAAM,GAAN,MAAM,CAAQ;QAI9B,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAA;IAClC,CAAC;CACF;AAED;;;;GAIG;AACH,MAAM,UAAU,eAAe,CAAC,KAAoB;IAClD,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC;QAC1C,OAAO,IAAI,CAAA;IACb,CAAC;IAED,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,EAAE,CAAA;IAE5B,+DAA+D;IAC/D,sEAAsE;IACtE,IAAI,SAAS,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC;QAC5B,MAAM,OAAO,GAAG,QAAQ,CAAC,OAAO,EAAE,EAAE,CAAC,CAAA;QACrC,IAAI,OAAO,GAAG,CAAC,EAAE,CAAC;YAChB,OAAO,IAAI,CAAA;QACb,CAAC;QACD,OAAO,OAAO,GAAG,IAAI,CAAA;IACvB,CAAC;IAED,yFAAyF;IACzF,4EAA4E;IAC5E,IAAI,UAAU,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC;QAC7B,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAA;QAChC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;YACjB,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC,CAAA;QACvC,CAAC;IACH,CAAC;IAED,OAAO,IAAI,CAAA;AACb,CAAC"}

package/dist/utils/safe-fs.d.ts

@@ -0,0 +1,63 @@
+/**
+ * SMI-2274: Safe filesystem operations
+ * @module @skillsmith/core/utils/safe-fs
+ *
+ * Provides symlink-safe file write operations to prevent
+ * path traversal attacks via symlink substitution.
+ *
+ * Attack scenario:
+ * 1. Attacker creates a symlink at ~/.claude/skills/evil -> /etc/passwd
+ * 2. Install tool writes SKILL.md content to that path
+ * 3. Content overwrites /etc/passwd instead of skill file
+ *
+ * Defense:
+ * - SMI-2285: Uses O_NOFOLLOW to atomically refuse symlinks (eliminates TOCTOU race)
+ * - SMI-2290: Checks nlink count to detect hardlinks
+ * - SMI-2288: Properly handles string encoding options for permissions
+ */
+import type { WriteFileOptions } from 'fs';
+/**
+ * Error thrown when a symlink is detected at a write destination.
+ */
+export declare class SymlinkError extends Error {
+    readonly filePath: string;
+    constructor(filePath: string);
+}
+/**
+ * Error thrown when a hardlinked file is detected at a write destination.
+ * SMI-2290: Hardlinks can alias files, allowing writes to bypass symlink checks.
+ */
+export declare class HardlinkError extends Error {
+    readonly filePath: string;
+    constructor(filePath: string);
+}
+/**
+ * Write a file safely, refusing to write if the destination is a symlink or hardlink.
+ *
+ * SMI-2285: Uses O_NOFOLLOW to atomically refuse symlinks, eliminating the
+ * TOCTOU race condition in the previous lstat-then-write approach.
+ * SMI-2290: Checks nlink count to detect hardlinks before writing.
+ * SMI-2288: Properly extracts mode from string options (encoding strings).
+ *
+ * @param filePath - Absolute path to write to
+ * @param content - File content (string or Buffer)
+ * @param options - Optional fs.writeFile options (encoding, mode, flag) or encoding string
+ * @throws {SymlinkError} if the destination is a symlink
+ * @throws {HardlinkError} if the destination has multiple hardlinks
+ *
+ * @example
+ * ```typescript
+ * import { safeWriteFile } from '@skillsmith/core'
+ *
+ * // Safe write - rejects symlinks and hardlinks
+ * await safeWriteFile('/path/to/file.md', content)
+ *
+ * // With explicit permissions
+ * await safeWriteFile('/path/to/file.md', content, { mode: 0o644 })
+ *
+ * // With encoding string (uses default 0o644 permissions)
+ * await safeWriteFile('/path/to/file.md', content, 'utf-8')
+ * ```
+ */
+export declare function safeWriteFile(filePath: string, content: string | Buffer, options?: WriteFileOptions | string): Promise<void>;
+//# sourceMappingURL=safe-fs.d.ts.map

package/dist/utils/safe-fs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"safe-fs.d.ts","sourceRoot":"","sources":["../../src/utils/safe-fs.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAGH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,IAAI,CAAA;AAW1C;;GAEG;AACH,qBAAa,YAAa,SAAQ,KAAK;IACrC,SAAgB,QAAQ,EAAE,MAAM,CAAA;gBACpB,QAAQ,EAAE,MAAM;CAK7B;AAED;;;GAGG;AACH,qBAAa,aAAc,SAAQ,KAAK;IACtC,SAAgB,QAAQ,EAAE,MAAM,CAAA;gBACpB,QAAQ,EAAE,MAAM;CAK7B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAsB,aAAa,CACjC,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,GAAG,MAAM,EACxB,OAAO,CAAC,EAAE,gBAAgB,GAAG,MAAM,GAClC,OAAO,CAAC,IAAI,CAAC,CA6Cf"}

package/dist/utils/safe-fs.js

@@ -0,0 +1,119 @@
+/**
+ * SMI-2274: Safe filesystem operations
+ * @module @skillsmith/core/utils/safe-fs
+ *
+ * Provides symlink-safe file write operations to prevent
+ * path traversal attacks via symlink substitution.
+ *
+ * Attack scenario:
+ * 1. Attacker creates a symlink at ~/.claude/skills/evil -> /etc/passwd
+ * 2. Install tool writes SKILL.md content to that path
+ * 3. Content overwrites /etc/passwd instead of skill file
+ *
+ * Defense:
+ * - SMI-2285: Uses O_NOFOLLOW to atomically refuse symlinks (eliminates TOCTOU race)
+ * - SMI-2290: Checks nlink count to detect hardlinks
+ * - SMI-2288: Properly handles string encoding options for permissions
+ */
+import { open, lstat, constants } from 'fs/promises';
+/**
+ * O_NOFOLLOW: refuse to open symlinks
+ * Prefer runtime constant from fs.constants, fall back to platform-specific values
+ * if unavailable (e.g., Windows where O_NOFOLLOW is not defined).
+ */
+const O_NOFOLLOW = constants.O_NOFOLLOW ??
+    (process.platform === 'darwin' ? 0x100 : 0x20000);
+/**
+ * Error thrown when a symlink is detected at a write destination.
+ */
+export class SymlinkError extends Error {
+    filePath;
+    constructor(filePath) {
+        super(`Refusing to write to symlink: ${filePath}`);
+        this.name = 'SymlinkError';
+        this.filePath = filePath;
+    }
+}
+/**
+ * Error thrown when a hardlinked file is detected at a write destination.
+ * SMI-2290: Hardlinks can alias files, allowing writes to bypass symlink checks.
+ */
+export class HardlinkError extends Error {
+    filePath;
+    constructor(filePath) {
+        super(`Refusing to write to hardlinked file: ${filePath}`);
+        this.name = 'HardlinkError';
+        this.filePath = filePath;
+    }
+}
+/**
+ * Write a file safely, refusing to write if the destination is a symlink or hardlink.
+ *
+ * SMI-2285: Uses O_NOFOLLOW to atomically refuse symlinks, eliminating the
+ * TOCTOU race condition in the previous lstat-then-write approach.
+ * SMI-2290: Checks nlink count to detect hardlinks before writing.
+ * SMI-2288: Properly extracts mode from string options (encoding strings).
+ *
+ * @param filePath - Absolute path to write to
+ * @param content - File content (string or Buffer)
+ * @param options - Optional fs.writeFile options (encoding, mode, flag) or encoding string
+ * @throws {SymlinkError} if the destination is a symlink
+ * @throws {HardlinkError} if the destination has multiple hardlinks
+ *
+ * @example
+ * ```typescript
+ * import { safeWriteFile } from '@skillsmith/core'
+ *
+ * // Safe write - rejects symlinks and hardlinks
+ * await safeWriteFile('/path/to/file.md', content)
+ *
+ * // With explicit permissions
+ * await safeWriteFile('/path/to/file.md', content, { mode: 0o644 })
+ *
+ * // With encoding string (uses default 0o644 permissions)
+ * await safeWriteFile('/path/to/file.md', content, 'utf-8')
+ * ```
+ */
+export async function safeWriteFile(filePath, content, options) {
+    // SMI-2288: Extract mode and encoding from options (handles string encoding case)
+    const mode = typeof options === 'string' ? 0o644 : (options?.mode ?? 0o644);
+    const encoding = typeof options === 'string'
+        ? options
+        : (options?.encoding ?? undefined);
+    // SMI-2290: Check for hardlinks on existing files
+    try {
+        const stats = await lstat(filePath);
+        if (stats.isSymbolicLink()) {
+            throw new SymlinkError(filePath);
+        }
+        if (stats.nlink > 1) {
+            throw new HardlinkError(filePath);
+        }
+    }
+    catch (error) {
+        if (error.code === 'ENOENT') {
+            // File doesn't exist — safe to create
+        }
+        else if (error instanceof SymlinkError || error instanceof HardlinkError) {
+            throw error;
+        }
+        else {
+            throw error;
+        }
+    }
+    // SMI-2285: Open with O_NOFOLLOW to prevent TOCTOU race
+    let fd;
+    try {
+        fd = await open(filePath, constants.O_WRONLY | constants.O_CREAT | constants.O_TRUNC | O_NOFOLLOW, mode);
+        const data = typeof content === 'string' && encoding
+            ? Buffer.from(content, encoding)
+            : typeof content === 'string'
+                ? Buffer.from(content, 'utf-8')
+                : content;
+        await fd.write(data);
+    }
+    finally {
+        await fd?.close();
+    }
+}
+//# sourceMappingURL=safe-fs.js.map

package/dist/utils/safe-fs.js.map

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

package/dist/utils/version-check.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Version check utility for auto-update notifications
+ * @see SMI-1952: Add auto-update check to MCP server startup
+ */
+/**
+ * Result of a version check against npm registry
+ */
+export interface VersionCheckResult {
+    /** Currently installed version */
+    currentVersion: string;
+    /** Latest version available on npm */
+    latestVersion: string;
+    /** True if a newer version is available */
+    updateAvailable: boolean;
+    /** Command to update the package */
+    updateCommand: string;
+}
+/**
+ * Check for updates to a package by querying the npm registry
+ *
+ * @param packageName - The npm package name to check (e.g., '@skillsmith/mcp-server')
+ * @param currentVersion - The currently installed version
+ * @returns Version check result, or null if check failed (network error, timeout, etc.)
+ *
+ * @example
+ * ```typescript
+ * const result = await checkForUpdates('@skillsmith/mcp-server', '0.3.0')
+ * if (result?.updateAvailable) {
+ *   console.log(`Update available: ${result.latestVersion}`)
+ * }
+ * ```
+ */
+export declare function checkForUpdates(packageName: string, currentVersion: string): Promise<VersionCheckResult | null>;
+/**
+ * Format update notification message for stderr output
+ *
+ * @param result - Version check result with update available
+ * @returns Formatted message string
+ */
+export declare function formatUpdateNotification(result: VersionCheckResult): string;
+//# sourceMappingURL=version-check.d.ts.map

package/dist/utils/version-check.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"version-check.d.ts","sourceRoot":"","sources":["../../src/utils/version-check.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,kCAAkC;IAClC,cAAc,EAAE,MAAM,CAAA;IACtB,sCAAsC;IACtC,aAAa,EAAE,MAAM,CAAA;IACrB,2CAA2C;IAC3C,eAAe,EAAE,OAAO,CAAA;IACxB,oCAAoC;IACpC,aAAa,EAAE,MAAM,CAAA;CACtB;AAKD;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,eAAe,CACnC,WAAW,EAAE,MAAM,EACnB,cAAc,EAAE,MAAM,GACrB,OAAO,CAAC,kBAAkB,GAAG,IAAI,CAAC,CA8BpC;AAED;;;;;GAKG;AACH,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,kBAAkB,GAAG,MAAM,CAK3E"}