@skillsmith/core 0.5.5 → 0.5.6

package/dist/session/metrics-collector.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"metrics-collector.js","sourceRoot":"","sources":["../../src/session/metrics-collector.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAA;AAGpD;;;;GAIG;AACH,MAAM,UAAU,kBAAkB,CAAC,YAAoB;IACrD,MAAM,OAAO,GAAG,UAAU,EAAE,CAAA;IAC5B,OAAO,CAAC,gBAAgB,CAAC,GAAG,CAAC,YAAY,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC,CAAA;AACjE,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,qBAAqB;IACnC,MAAM,OAAO,GAAG,UAAU,EAAE,CAAA;IAC5B,4EAA4E;IAC5E,OAAO,CAAC,eAAe,CAAC,SAAS,CAAC,EAAE,IAAI,EAAE,mBAAmB,EAAE,CAAC,CAAA;AAClE,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,uBAAuB,CAAC,MAA2B;IACjE,MAAM,OAAO,GAAG,UAAU,EAAE,CAAA;IAE5B,QAAQ,MAAM,EAAE,CAAC;QACf,KAAK,SAAS;YACZ,OAAO,CAAC,aAAa,CAAC,SAAS,CAAC,EAAE,IAAI,EAAE,iBAAiB,EAAE,CAAC,CAAA;YAC5D,MAAK;QACP,KAAK,WAAW;YACd,OAAO,CAAC,aAAa,CAAC,SAAS,CAAC,EAAE,IAAI,EAAE,mBAAmB,EAAE,CAAC,CAAA;YAC9D,MAAK;QACP,KAAK,MAAM;YACT,OAAO,CAAC,aAAa,CAAC,SAAS,CAAC,EAAE,IAAI,EAAE,cAAc,EAAE,CAAC,CAAA;YACzD,MAAK;QACP,qCAAqC;IACvC,CAAC;AACH,CAAC"}

package/dist/session/typed-event-emitter.d.ts

@@ -0,0 +1,70 @@
+/**
+ * SMI-1189: Typed Event Emitter
+ *
+ * Generic TypedEventEmitter that provides type-safe event handling.
+ * Replaces ~182 lines of repetitive type overloads with a single generic class.
+ */
+import { EventEmitter } from 'node:events';
+/**
+ * Constraint type for event maps.
+ * Events must be a record of event names to argument tuples.
+ */
+export type EventMap = {
+    [K: string]: unknown[];
+};
+/**
+ * Type-safe EventEmitter wrapper.
+ *
+ * @typeParam Events - Object mapping event names to their argument tuples
+ *
+ * @example
+ * ```typescript
+ * interface MyEvents {
+ *   data: [payload: string];
+ *   error: [error: Error, code: number];
+ *   complete: [];
+ * }
+ *
+ * class MyEmitter extends TypedEventEmitter<MyEvents> {
+ *   doSomething() {
+ *     this.emit('data', 'hello');  // Type-checked!
+ *     this.emit('error', new Error('oops'), 500);
+ *   }
+ * }
+ * ```
+ */
+export declare class TypedEventEmitter<Events extends EventMap> extends EventEmitter {
+    /**
+     * Adds a listener function to the end of the listeners array for the specified event.
+     */
+    on<K extends keyof Events & string>(event: K, listener: (...args: Events[K]) => void): this;
+    /**
+     * Synchronously calls each of the listeners registered for the event.
+     */
+    emit<K extends keyof Events & string>(event: K, ...args: Events[K]): boolean;
+    /**
+     * Removes the specified listener from the listener array for the specified event.
+     */
+    off<K extends keyof Events & string>(event: K, listener: (...args: Events[K]) => void): this;
+    /**
+     * Adds a one-time listener function for the specified event.
+     */
+    once<K extends keyof Events & string>(event: K, listener: (...args: Events[K]) => void): this;
+    /**
+     * Alias for on().
+     */
+    addListener<K extends keyof Events & string>(event: K, listener: (...args: Events[K]) => void): this;
+    /**
+     * Alias for off().
+     */
+    removeListener<K extends keyof Events & string>(event: K, listener: (...args: Events[K]) => void): this;
+    /**
+     * Adds a listener to the beginning of the listeners array.
+     */
+    prependListener<K extends keyof Events & string>(event: K, listener: (...args: Events[K]) => void): this;
+    /**
+     * Adds a one-time listener to the beginning of the listeners array.
+     */
+    prependOnceListener<K extends keyof Events & string>(event: K, listener: (...args: Events[K]) => void): this;
+}
+//# sourceMappingURL=typed-event-emitter.d.ts.map

package/dist/session/typed-event-emitter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"typed-event-emitter.d.ts","sourceRoot":"","sources":["../../src/session/typed-event-emitter.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAE1C;;;GAGG;AACH,MAAM,MAAM,QAAQ,GAAG;IAAE,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,EAAE,CAAA;CAAE,CAAA;AAEjD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,qBAAa,iBAAiB,CAAC,MAAM,SAAS,QAAQ,CAAE,SAAQ,YAAY;IAC1E;;OAEG;IACM,EAAE,CAAC,CAAC,SAAS,MAAM,MAAM,GAAG,MAAM,EACzC,KAAK,EAAE,CAAC,EACR,QAAQ,EAAE,CAAC,GAAG,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC,KAAK,IAAI,GACrC,IAAI;IAIP;;OAEG;IACM,IAAI,CAAC,CAAC,SAAS,MAAM,MAAM,GAAG,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,GAAG,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC,GAAG,OAAO;IAIrF;;OAEG;IACM,GAAG,CAAC,CAAC,SAAS,MAAM,MAAM,GAAG,MAAM,EAC1C,KAAK,EAAE,CAAC,EACR,QAAQ,EAAE,CAAC,GAAG,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC,KAAK,IAAI,GACrC,IAAI;IAIP;;OAEG;IACM,IAAI,CAAC,CAAC,SAAS,MAAM,MAAM,GAAG,MAAM,EAC3C,KAAK,EAAE,CAAC,EACR,QAAQ,EAAE,CAAC,GAAG,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC,KAAK,IAAI,GACrC,IAAI;IAIP;;OAEG;IACM,WAAW,CAAC,CAAC,SAAS,MAAM,MAAM,GAAG,MAAM,EAClD,KAAK,EAAE,CAAC,EACR,QAAQ,EAAE,CAAC,GAAG,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC,KAAK,IAAI,GACrC,IAAI;IAIP;;OAEG;IACM,cAAc,CAAC,CAAC,SAAS,MAAM,MAAM,GAAG,MAAM,EACrD,KAAK,EAAE,CAAC,EACR,QAAQ,EAAE,CAAC,GAAG,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC,KAAK,IAAI,GACrC,IAAI;IAIP;;OAEG;IACM,eAAe,CAAC,CAAC,SAAS,MAAM,MAAM,GAAG,MAAM,EACtD,KAAK,EAAE,CAAC,EACR,QAAQ,EAAE,CAAC,GAAG,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC,KAAK,IAAI,GACrC,IAAI;IAIP;;OAEG;IACM,mBAAmB,CAAC,CAAC,SAAS,MAAM,MAAM,GAAG,MAAM,EAC1D,KAAK,EAAE,CAAC,EACR,QAAQ,EAAE,CAAC,GAAG,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC,KAAK,IAAI,GACrC,IAAI;CAGR"}

package/dist/session/typed-event-emitter.js

@@ -0,0 +1,79 @@
+/**
+ * SMI-1189: Typed Event Emitter
+ *
+ * Generic TypedEventEmitter that provides type-safe event handling.
+ * Replaces ~182 lines of repetitive type overloads with a single generic class.
+ */
+import { EventEmitter } from 'node:events';
+/**
+ * Type-safe EventEmitter wrapper.
+ *
+ * @typeParam Events - Object mapping event names to their argument tuples
+ *
+ * @example
+ * ```typescript
+ * interface MyEvents {
+ *   data: [payload: string];
+ *   error: [error: Error, code: number];
+ *   complete: [];
+ * }
+ *
+ * class MyEmitter extends TypedEventEmitter<MyEvents> {
+ *   doSomething() {
+ *     this.emit('data', 'hello');  // Type-checked!
+ *     this.emit('error', new Error('oops'), 500);
+ *   }
+ * }
+ * ```
+ */
+export class TypedEventEmitter extends EventEmitter {
+    /**
+     * Adds a listener function to the end of the listeners array for the specified event.
+     */
+    on(event, listener) {
+        return super.on(event, listener);
+    }
+    /**
+     * Synchronously calls each of the listeners registered for the event.
+     */
+    emit(event, ...args) {
+        return super.emit(event, ...args);
+    }
+    /**
+     * Removes the specified listener from the listener array for the specified event.
+     */
+    off(event, listener) {
+        return super.off(event, listener);
+    }
+    /**
+     * Adds a one-time listener function for the specified event.
+     */
+    once(event, listener) {
+        return super.once(event, listener);
+    }
+    /**
+     * Alias for on().
+     */
+    addListener(event, listener) {
+        return super.addListener(event, listener);
+    }
+    /**
+     * Alias for off().
+     */
+    removeListener(event, listener) {
+        return super.removeListener(event, listener);
+    }
+    /**
+     * Adds a listener to the beginning of the listeners array.
+     */
+    prependListener(event, listener) {
+        return super.prependListener(event, listener);
+    }
+    /**
+     * Adds a one-time listener to the beginning of the listeners array.
+     */
+    prependOnceListener(event, listener) {
+        return super.prependOnceListener(event, listener);
+    }
+}
+//# sourceMappingURL=typed-event-emitter.js.map

package/dist/session/typed-event-emitter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"typed-event-emitter.js","sourceRoot":"","sources":["../../src/session/typed-event-emitter.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAQ1C;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,OAAO,iBAA2C,SAAQ,YAAY;IAC1E;;OAEG;IACM,EAAE,CACT,KAAQ,EACR,QAAsC;QAEtC,OAAO,KAAK,CAAC,EAAE,CAAC,KAAK,EAAE,QAAwC,CAAC,CAAA;IAClE,CAAC;IAED;;OAEG;IACM,IAAI,CAAkC,KAAQ,EAAE,GAAG,IAAe;QACzE,OAAO,KAAK,CAAC,IAAI,CAAC,KAAK,EAAE,GAAG,IAAI,CAAC,CAAA;IACnC,CAAC;IAED;;OAEG;IACM,GAAG,CACV,KAAQ,EACR,QAAsC;QAEtC,OAAO,KAAK,CAAC,GAAG,CAAC,KAAK,EAAE,QAAwC,CAAC,CAAA;IACnE,CAAC;IAED;;OAEG;IACM,IAAI,CACX,KAAQ,EACR,QAAsC;QAEtC,OAAO,KAAK,CAAC,IAAI,CAAC,KAAK,EAAE,QAAwC,CAAC,CAAA;IACpE,CAAC;IAED;;OAEG;IACM,WAAW,CAClB,KAAQ,EACR,QAAsC;QAEtC,OAAO,KAAK,CAAC,WAAW,CAAC,KAAK,EAAE,QAAwC,CAAC,CAAA;IAC3E,CAAC;IAED;;OAEG;IACM,cAAc,CACrB,KAAQ,EACR,QAAsC;QAEtC,OAAO,KAAK,CAAC,cAAc,CAAC,KAAK,EAAE,QAAwC,CAAC,CAAA;IAC9E,CAAC;IAED;;OAEG;IACM,eAAe,CACtB,KAAQ,EACR,QAAsC;QAEtC,OAAO,KAAK,CAAC,eAAe,CAAC,KAAK,EAAE,QAAwC,CAAC,CAAA;IAC/E,CAAC;IAED;;OAEG;IACM,mBAAmB,CAC1B,KAAQ,EACR,QAAsC;QAEtC,OAAO,KAAK,CAAC,mBAAmB,CAAC,KAAK,EAAE,QAAwC,CAAC,CAAA;IACnF,CAAC;CACF"}

package/dist/sources/BaseSourceAdapter.d.ts

@@ -0,0 +1,144 @@
+/**
+ * Base Source Adapter
+ * Abstract base class providing common functionality for source adapters
+ *
+ * SMI-1013: Enhanced with token bucket rate limiting and request queuing
+ */
+import type { ISourceAdapter } from './ISourceAdapter.js';
+import { RateLimiter, type RateLimitConfig as TokenBucketConfig } from '../security/index.js';
+import { type RetryConfig } from '../utils/retry.js';
+import type { SourceConfig, SourceLocation, SourceRepository, SourceSearchOptions, SourceSearchResult, SkillContent, SourceHealth } from './types.js';
+/**
+ * Extended source config with token bucket rate limiting (SMI-1013)
+ */
+export interface ExtendedSourceConfig extends SourceConfig {
+    /** Use token bucket rate limiter with queue support (SMI-1013) */
+    useTokenBucket?: boolean;
+    /** Token bucket configuration (overrides legacy rateLimit) */
+    tokenBucketConfig?: TokenBucketConfig;
+    /** Enable retry logic for transient network failures (SMI-880) */
+    enableRetry?: boolean;
+    /** Retry configuration (SMI-880) */
+    retryConfig?: RetryConfig;
+}
+/**
+ * Abstract base class for source adapters
+ *
+ * Provides:
+ * - Configuration management
+ * - Rate limiting
+ * - Request timing
+ * - Error handling utilities
+ *
+ * Subclasses must implement:
+ * - search()
+ * - getRepository()
+ * - fetchSkillContent()
+ * - doHealthCheck()
+ */
+export declare abstract class BaseSourceAdapter implements ISourceAdapter {
+    readonly config: ExtendedSourceConfig;
+    readonly id: string;
+    readonly name: string;
+    readonly type: string;
+    protected initialized: boolean;
+    protected lastRequestTime: number;
+    protected requestCount: number;
+    protected windowStart: number;
+    /** Token bucket rate limiter (SMI-1013) */
+    protected rateLimiter: RateLimiter | null;
+    constructor(config: SourceConfig | ExtendedSourceConfig);
+    /**
+     * Initialize the adapter
+     * Override in subclasses for custom initialization
+     */
+    initialize(): Promise<void>;
+    /**
+     * Subclass initialization hook
+     */
+    protected doInitialize(): Promise<void>;
+    /**
+     * Check source health
+     */
+    checkHealth(): Promise<SourceHealth>;
+    /**
+     * Subclass health check implementation
+     */
+    protected abstract doHealthCheck(): Promise<Partial<SourceHealth>>;
+    /**
+     * Search for repositories
+     */
+    abstract search(options: SourceSearchOptions): Promise<SourceSearchResult>;
+    /**
+     * Get repository metadata
+     */
+    abstract getRepository(location: SourceLocation): Promise<SourceRepository>;
+    /**
+     * Fetch skill content
+     */
+    abstract fetchSkillContent(location: SourceLocation): Promise<SkillContent>;
+    /**
+     * Check if skill exists at location
+     */
+    skillExists(location: SourceLocation): Promise<boolean>;
+    /**
+     * Get skill file SHA for change detection
+     */
+    getSkillSha(location: SourceLocation): Promise<string | null>;
+    /**
+     * Dispose of resources
+     */
+    dispose(): Promise<void>;
+    /**
+     * Subclass disposal hook
+     */
+    protected doDispose(): Promise<void>;
+    /**
+     * Wait for rate limit before making a request
+     */
+    protected waitForRateLimit(): Promise<void>;
+    /**
+     * Make a rate-limited fetch request with retry support
+     *
+     * SMI-1013: Uses token bucket rate limiter with queue support when enabled,
+     * otherwise falls back to legacy window-based rate limiting.
+     *
+     * SMI-880: Automatically retries on transient network failures (ETIMEDOUT,
+     * ECONNRESET, 5xx) with exponential backoff when enableRetry is true.
+     */
+    protected fetchWithRateLimit(url: string, options?: RequestInit): Promise<Response>;
+    /**
+     * Get rate limiter status (SMI-1013)
+     *
+     * Returns information about the token bucket rate limiter state,
+     * including queue status if queuing is enabled.
+     */
+    getRateLimiterStatus(): {
+        usingTokenBucket: boolean;
+        queueStatus?: {
+            totalQueued: number;
+            queues: Map<string, number>;
+        } | number;
+    };
+    /**
+     * Update rate limit tracking from response headers
+     */
+    protected updateRateLimitFromResponse(response: Response): void;
+    /**
+     * Build the default skill file path
+     */
+    protected getDefaultSkillPath(location: SourceLocation): string;
+    /**
+     * Build the default branch
+     */
+    protected getDefaultBranch(location: SourceLocation): string;
+    /**
+     * Delay helper
+     */
+    protected delay(ms: number): Promise<void>;
+    /**
+     * Validate configuration
+     */
+    protected validateConfig(): void;
+}
+//# sourceMappingURL=BaseSourceAdapter.d.ts.map

package/dist/sources/BaseSourceAdapter.d.ts.map

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

package/dist/sources/BaseSourceAdapter.js

@@ -0,0 +1,287 @@
+/**
+ * Base Source Adapter
+ * Abstract base class providing common functionality for source adapters
+ *
+ * SMI-1013: Enhanced with token bucket rate limiting and request queuing
+ */
+import { validateUrl } from '../validation/index.js';
+import { RateLimiter, InMemoryRateLimitStorage, RATE_LIMIT_PRESETS, } from '../security/index.js';
+import { fetchWithRetry } from '../utils/retry.js';
+/**
+ * Default rate limit configuration (legacy window-based)
+ */
+const DEFAULT_RATE_LIMIT = {
+    maxRequests: 30,
+    windowMs: 60000,
+    minDelayMs: 150,
+};
+/**
+ * Abstract base class for source adapters
+ *
+ * Provides:
+ * - Configuration management
+ * - Rate limiting
+ * - Request timing
+ * - Error handling utilities
+ *
+ * Subclasses must implement:
+ * - search()
+ * - getRepository()
+ * - fetchSkillContent()
+ * - doHealthCheck()
+ */
+export class BaseSourceAdapter {
+    config;
+    id;
+    name;
+    type;
+    initialized = false;
+    lastRequestTime = 0;
+    requestCount = 0;
+    windowStart = 0;
+    /** Token bucket rate limiter (SMI-1013) */
+    rateLimiter = null;
+    constructor(config) {
+        this.config = {
+            ...config,
+            rateLimit: config.rateLimit ?? DEFAULT_RATE_LIMIT,
+        };
+        this.id = config.id;
+        this.name = config.name;
+        this.type = config.type;
+        // Initialize token bucket rate limiter if enabled (SMI-1013)
+        const extConfig = config;
+        if (extConfig.useTokenBucket) {
+            const tokenBucketConfig = extConfig.tokenBucketConfig ?? {
+                ...RATE_LIMIT_PRESETS.STANDARD,
+                enableQueue: true,
+                queueTimeoutMs: 30000,
+                maxQueueSize: 100,
+                keyPrefix: `adapter:${config.id}`,
+            };
+            this.rateLimiter = new RateLimiter(tokenBucketConfig, new InMemoryRateLimitStorage());
+        }
+    }
+    /**
+     * Initialize the adapter
+     * Override in subclasses for custom initialization
+     */
+    async initialize() {
+        if (this.initialized)
+            return;
+        await this.doInitialize();
+        this.initialized = true;
+    }
+    /**
+     * Subclass initialization hook
+     */
+    async doInitialize() {
+        // Default: no-op, override in subclasses
+    }
+    /**
+     * Check source health
+     */
+    async checkHealth() {
+        const startTime = Date.now();
+        try {
+            const result = await this.doHealthCheck();
+            return {
+                healthy: result.healthy ?? true,
+                responseTimeMs: Date.now() - startTime,
+                lastCheck: new Date().toISOString(),
+                rateLimitRemaining: result.rateLimitRemaining,
+                rateLimitReset: result.rateLimitReset,
+                error: result.error,
+            };
+        }
+        catch (error) {
+            return {
+                healthy: false,
+                responseTimeMs: Date.now() - startTime,
+                lastCheck: new Date().toISOString(),
+                error: error instanceof Error ? error.message : 'Unknown error',
+            };
+        }
+    }
+    /**
+     * Check if skill exists at location
+     */
+    async skillExists(location) {
+        try {
+            await this.fetchSkillContent(location);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Get skill file SHA for change detection
+     */
+    async getSkillSha(location) {
+        try {
+            const content = await this.fetchSkillContent(location);
+            return content.sha;
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Dispose of resources
+     */
+    async dispose() {
+        // SMI-1013: Dispose rate limiter
+        if (this.rateLimiter) {
+            this.rateLimiter.dispose();
+            this.rateLimiter = null;
+        }
+        await this.doDispose();
+        this.initialized = false;
+    }
+    /**
+     * Subclass disposal hook
+     */
+    async doDispose() {
+        // Default: no-op, override in subclasses
+    }
+    /**
+     * Wait for rate limit before making a request
+     */
+    async waitForRateLimit() {
+        const config = this.config.rateLimit ?? DEFAULT_RATE_LIMIT;
+        const now = Date.now();
+        // Reset window if expired
+        if (now - this.windowStart > config.windowMs) {
+            this.windowStart = now;
+            this.requestCount = 0;
+        }
+        // Check if we've exceeded the rate limit
+        if (this.requestCount >= config.maxRequests) {
+            const waitTime = config.windowMs - (now - this.windowStart);
+            if (waitTime > 0) {
+                await this.delay(waitTime);
+                this.windowStart = Date.now();
+                this.requestCount = 0;
+            }
+        }
+        // Ensure minimum delay between requests
+        const timeSinceLastRequest = now - this.lastRequestTime;
+        if (timeSinceLastRequest < config.minDelayMs) {
+            await this.delay(config.minDelayMs - timeSinceLastRequest);
+        }
+        this.lastRequestTime = Date.now();
+        this.requestCount++;
+    }
+    /**
+     * Make a rate-limited fetch request with retry support
+     *
+     * SMI-1013: Uses token bucket rate limiter with queue support when enabled,
+     * otherwise falls back to legacy window-based rate limiting.
+     *
+     * SMI-880: Automatically retries on transient network failures (ETIMEDOUT,
+     * ECONNRESET, 5xx) with exponential backoff when enableRetry is true.
+     */
+    async fetchWithRateLimit(url, options) {
+        validateUrl(url);
+        // SMI-1013: Use token bucket rate limiter if available
+        if (this.rateLimiter) {
+            // waitForToken will queue the request if rate limited
+            await this.rateLimiter.waitForToken(this.id);
+        }
+        else {
+            // Legacy window-based rate limiting
+            await this.waitForRateLimit();
+        }
+        const headers = new Headers(options?.headers);
+        // Add auth header if configured
+        if (this.config.auth?.type === 'token' && this.config.auth.credentials) {
+            headers.set('Authorization', `Bearer ${this.config.auth.credentials}`);
+        }
+        else if (this.config.auth?.type === 'basic' && this.config.auth.credentials) {
+            headers.set('Authorization', `Basic ${this.config.auth.credentials}`);
+        }
+        const fetchOptions = {
+            ...options,
+            headers,
+        };
+        // SMI-880: Use retry logic if explicitly enabled
+        const extendedConfig = this.config;
+        let response;
+        if (extendedConfig.enableRetry === true) {
+            // Opt-in retry for resilience against transient failures
+            response = await fetchWithRetry(url, fetchOptions, extendedConfig.retryConfig);
+        }
+        else {
+            response = await fetch(url, fetchOptions);
+        }
+        // Update rate limit info from response headers if available
+        this.updateRateLimitFromResponse(response);
+        return response;
+    }
+    /**
+     * Get rate limiter status (SMI-1013)
+     *
+     * Returns information about the token bucket rate limiter state,
+     * including queue status if queuing is enabled.
+     */
+    getRateLimiterStatus() {
+        if (!this.rateLimiter) {
+            return { usingTokenBucket: false };
+        }
+        return {
+            usingTokenBucket: true,
+            queueStatus: this.rateLimiter.getQueueStatus(),
+        };
+    }
+    /**
+     * Update rate limit tracking from response headers
+     */
+    updateRateLimitFromResponse(response) {
+        // Common rate limit headers (GitHub, GitLab, etc.)
+        const remaining = response.headers.get('x-ratelimit-remaining');
+        const reset = response.headers.get('x-ratelimit-reset');
+        if (remaining !== null) {
+            const remainingNum = parseInt(remaining, 10);
+            if (remainingNum <= 0 && reset) {
+                // We've hit the rate limit, update window
+                const _resetTime = parseInt(reset, 10) * 1000;
+                this.windowStart = Date.now();
+                this.requestCount = this.config.rateLimit?.maxRequests ?? DEFAULT_RATE_LIMIT.maxRequests;
+            }
+        }
+    }
+    /**
+     * Build the default skill file path
+     */
+    getDefaultSkillPath(location) {
+        return location.path ?? 'SKILL.md';
+    }
+    /**
+     * Build the default branch
+     */
+    getDefaultBranch(location) {
+        return location.branch ?? 'main';
+    }
+    /**
+     * Delay helper
+     */
+    delay(ms) {
+        return new Promise((resolve) => setTimeout(resolve, ms));
+    }
+    /**
+     * Validate configuration
+     */
+    validateConfig() {
+        if (!this.config.id) {
+            throw new Error('Source adapter requires an id');
+        }
+        if (!this.config.name) {
+            throw new Error('Source adapter requires a name');
+        }
+        if (!this.config.baseUrl) {
+            throw new Error('Source adapter requires a baseUrl');
+        }
+    }
+}
+//# sourceMappingURL=BaseSourceAdapter.js.map

package/dist/sources/BaseSourceAdapter.js.map

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