forge-server 0.1.0

package/dist/tools/registration-tools.js

@@ -0,0 +1,391 @@
+// registration-tools.ts — B16
+// MCP tool handlers for repo registration and initialization.
+// Tools: register, init, list_repos, get_manifest, index_repo, get_index_status
+import { z } from 'zod';
+import { fullIndex } from '../ingestion/indexer.js';
+import { getUptimeSeconds } from '../memory/session-tracker.js';
+import { join, resolve } from 'node:path';
+import { logger } from '../util/logger.js';
+// ---------------------------------------------------------------------------
+// Input schemas
+// ---------------------------------------------------------------------------
+export const registerSchema = z.object({
+    path: z.string().optional(),
+    auto: z.boolean().default(true),
+});
+export const initSchema = z.object({
+    path: z.string().optional(),
+    name: z.string().min(1, 'name is required'),
+    stack: z.array(z.string()).min(1, 'at least one stack tag is required'),
+    sharing: z.enum(['team', 'private', 'public']).default('private'),
+    org: z.string().optional(),
+});
+export const listReposSchema = z.object({});
+export const getManifestSchema = z.object({
+    repo_path: z.string().optional(),
+});
+export const indexRepoSchema = z.object({
+    repo_id: z.string().optional(),
+    path: z.string().optional(),
+    force: z.boolean().default(false),
+});
+export const getIndexStatusSchema = z.object({
+    repo_id: z.string().optional(),
+});
+// ---------------------------------------------------------------------------
+// Tool factory
+// ---------------------------------------------------------------------------
+export function createRegistrationTools(registry, stores) {
+    return {
+        'register': {
+            schema: registerSchema,
+            description: 'Register a repo with the forge server, loading its .forge/manifest.yaml and syncing knowledge to Qdrant',
+            handler: async (input) => {
+                try {
+                    const repoPath = resolve(input.path ?? process.cwd());
+                    const result = await registry.register(repoPath, {
+                        auto: input.auto,
+                    });
+                    logger.info('registration-tools.register: completed', {
+                        repoId: result.repo_id,
+                        name: result.name,
+                        newlyRegistered: result.newly_registered,
+                    });
+                    const response = {
+                        repo_id: result.repo_id,
+                        name: result.name,
+                        path: result.path,
+                        remote: result.remote,
+                        stack: result.stack,
+                        sharing: result.sharing,
+                        newly_registered: result.newly_registered,
+                        knowledge_items_loaded: result.knowledge_items_loaded,
+                    };
+                    // Auto-index after registration when auto: true and stores are available
+                    if (input.auto && stores?.vectorStore) {
+                        try {
+                            const indexResult = await runIndex(registry, stores, result.repo_id, result.path, result.stack, false);
+                            response.index_result = {
+                                files_processed: indexResult.filesProcessed,
+                                files_skipped: indexResult.filesSkipped,
+                                files_errored: indexResult.filesErrored,
+                                chunks_created: indexResult.chunksCreated,
+                                knowledge_items_extracted: indexResult.knowledgeItemsExtracted,
+                                duration_ms: indexResult.durationMs,
+                            };
+                            logger.info('registration-tools.register: auto-index completed', {
+                                repoId: result.repo_id,
+                                filesProcessed: indexResult.filesProcessed,
+                                chunksCreated: indexResult.chunksCreated,
+                            });
+                        }
+                        catch (indexErr) {
+                            // Non-fatal: registration still succeeds
+                            response.index_warning = `Auto-index failed: ${String(indexErr)}`;
+                            logger.warn('registration-tools.register: auto-index failed (non-fatal)', {
+                                repoId: result.repo_id,
+                                error: String(indexErr),
+                            });
+                        }
+                    }
+                    return response;
+                }
+                catch (err) {
+                    logger.error('registration-tools.register: error', { error: String(err) });
+                    return {
+                        error: 'REGISTER_FAILED',
+                        message: String(err),
+                    };
+                }
+            },
+        },
+        'init': {
+            schema: initSchema,
+            description: 'Initialize the .forge/ directory structure in a repo, creating manifest.yaml and empty knowledge YAML files',
+            handler: async (input) => {
+                try {
+                    const repoPath = resolve(input.path ?? process.cwd());
+                    const manifest = {
+                        name: input.name,
+                        stack: input.stack,
+                        sharing: input.sharing,
+                        org: input.org,
+                        repo_id_override: null,
+                    };
+                    const { forgePath, filesCreated } = registry.initForge(repoPath, manifest);
+                    logger.info('registration-tools.init: completed', {
+                        forgePath,
+                        filesCreated: filesCreated.length,
+                    });
+                    return {
+                        forge_dir: forgePath,
+                        manifest_path: join(forgePath, 'manifest.yaml'),
+                        knowledge_dir: join(forgePath, 'knowledge'),
+                        files_created: filesCreated,
+                    };
+                }
+                catch (err) {
+                    logger.error('registration-tools.init: error', { error: String(err) });
+                    return {
+                        error: 'INIT_FAILED',
+                        message: String(err),
+                    };
+                }
+            },
+        },
+        'list_repos': {
+            schema: listReposSchema,
+            description: 'List all registered repos with their stack tags and last-seen timestamps',
+            handler: async (_input) => {
+                try {
+                    const repos = registry.listRepos();
+                    logger.debug('registration-tools.list_repos: completed', {
+                        count: repos.length,
+                    });
+                    return {
+                        repos: repos.map(r => ({
+                            id: r.id,
+                            name: r.name,
+                            path: r.path,
+                            stack: r.stack,
+                            sharing: r.sharing,
+                            last_seen: new Date(r.lastSeenAt).toISOString(),
+                            knowledge_count: r.knowledge_count,
+                        })),
+                    };
+                }
+                catch (err) {
+                    logger.error('registration-tools.list_repos: error', { error: String(err) });
+                    return {
+                        error: 'LIST_REPOS_FAILED',
+                        message: String(err),
+                        repos: [],
+                    };
+                }
+            },
+        },
+        'get_manifest': {
+            schema: getManifestSchema,
+            description: 'Read and return the .forge/manifest.yaml from a repo path',
+            handler: async (input) => {
+                try {
+                    const repoPath = resolve(input.repo_path ?? process.cwd());
+                    const forgePath = join(repoPath, '.forge');
+                    const manifest = registry.readManifest(forgePath);
+                    const forgeExists = registry.forgeDirectoryExists(repoPath);
+                    return {
+                        manifest: manifest
+                            ? {
+                                name: manifest.name,
+                                stack: manifest.stack,
+                                sharing: manifest.sharing,
+                                org: manifest.org,
+                            }
+                            : null,
+                        forge_dir_exists: forgeExists,
+                    };
+                }
+                catch (err) {
+                    logger.error('registration-tools.get_manifest: error', { error: String(err) });
+                    return {
+                        error: 'GET_MANIFEST_FAILED',
+                        message: String(err),
+                        manifest: null,
+                        forge_dir_exists: false,
+                    };
+                }
+            },
+        },
+        'index_repo': {
+            schema: indexRepoSchema,
+            description: 'Index a registered repo, populating vector and graph stores with code chunks and extracting knowledge from markdown docs',
+            handler: async (input) => {
+                if (!stores?.vectorStore) {
+                    return {
+                        error: 'INDEX_UNAVAILABLE',
+                        message: 'Vector store (Qdrant) is not available. Cannot index without it.',
+                    };
+                }
+                try {
+                    // Resolve repo by ID or path
+                    let repo;
+                    if (input.repo_id) {
+                        repo = registry.getRepo(input.repo_id);
+                        if (!repo) {
+                            return {
+                                error: 'REPO_NOT_FOUND',
+                                message: `Repo not found: ${input.repo_id}. Run 'forge register' first.`,
+                            };
+                        }
+                    }
+                    else {
+                        const repoPath = resolve(input.path ?? process.cwd());
+                        repo = registry.findRepoByPath(repoPath);
+                        if (!repo) {
+                            return {
+                                error: 'REPO_NOT_FOUND',
+                                message: `No registered repo found at ${repoPath}. Run 'forge register' first.`,
+                            };
+                        }
+                    }
+                    const result = await runIndex(registry, stores, repo.id, repo.path, repo.stack, input.force);
+                    logger.info('registration-tools.index_repo: completed', {
+                        repoId: repo.id,
+                        filesProcessed: result.filesProcessed,
+                        chunksCreated: result.chunksCreated,
+                        knowledgeItemsExtracted: result.knowledgeItemsExtracted,
+                    });
+                    return {
+                        repo_id: result.repoId,
+                        files_processed: result.filesProcessed,
+                        files_skipped: result.filesSkipped,
+                        files_errored: result.filesErrored,
+                        chunks_created: result.chunksCreated,
+                        knowledge_items_extracted: result.knowledgeItemsExtracted,
+                        duration_ms: result.durationMs,
+                        errors: result.errors.length > 0 ? result.errors.slice(0, 10) : undefined,
+                    };
+                }
+                catch (err) {
+                    logger.error('registration-tools.index_repo: error', { error: String(err) });
+                    return {
+                        error: 'INDEX_FAILED',
+                        message: String(err),
+                    };
+                }
+            },
+        },
+        'get_index_status': {
+            schema: getIndexStatusSchema,
+            description: 'Get health and index status for all backends (Qdrant, FalkorDB, file cache). Optionally filter by repo_id for per-repo stats.',
+            handler: async (input) => {
+                try {
+                    // --- Repo listing ---
+                    const allRepos = registry.listRepos();
+                    const filteredRepos = input.repo_id
+                        ? allRepos.filter(r => r.id === input.repo_id)
+                        : allRepos;
+                    const repoStatuses = filteredRepos.map(r => ({
+                        repoId: r.id,
+                        path: r.path,
+                        filesIndexed: 0, // Approximate — exact count requires scanning
+                        filesTotal: 0,
+                        lastIndexedAt: r.lastSeenAt,
+                        staleFiles: 0,
+                    }));
+                    // --- Vector store health ---
+                    let vectorCounts = { codeChunks: 0, observations: 0 };
+                    let qdrantHealthy = false;
+                    if (stores?.vectorStore) {
+                        try {
+                            qdrantHealthy = await stores.vectorStore.isHealthy();
+                            if (qdrantHealthy) {
+                                vectorCounts = await stores.vectorStore.getCounts();
+                            }
+                        }
+                        catch (err) {
+                            logger.warn('get_index_status: Qdrant getCounts failed', { error: String(err) });
+                        }
+                    }
+                    // --- Graph store health ---
+                    let graphCounts = { totalNodes: 0, totalEdges: 0, byLabel: {} };
+                    let graphHealthy = false;
+                    if (stores?.graphStore) {
+                        try {
+                            graphHealthy = await stores.graphStore.isHealthy();
+                            if (graphHealthy) {
+                                graphCounts = await stores.graphStore.getCounts();
+                            }
+                        }
+                        catch (err) {
+                            logger.warn('get_index_status: FalkorDB getCounts failed', { error: String(err) });
+                        }
+                    }
+                    // --- Cache stats ---
+                    const cacheStats = stores?.fileCache
+                        ? stores.fileCache.getStats()
+                        : { entries: 0, memoryUsageMb: 0, hitRate: 0, evictionCount: 0, oldestEntryAgeSeconds: 0 };
+                    // --- Overall health ---
+                    let health;
+                    if (qdrantHealthy && graphHealthy) {
+                        health = 'healthy';
+                    }
+                    else if (qdrantHealthy || graphHealthy) {
+                        health = 'degraded';
+                    }
+                    else {
+                        health = 'unavailable';
+                    }
+                    const result = {
+                        repos: repoStatuses,
+                        graph: {
+                            total_nodes: graphCounts.totalNodes,
+                            total_edges: graphCounts.totalEdges,
+                            node_counts: graphCounts.byLabel,
+                        },
+                        vector: {
+                            code_chunks_count: vectorCounts.codeChunks,
+                            observations_count: vectorCounts.observations,
+                        },
+                        cache: cacheStats,
+                        health,
+                        embedding_model: 'Xenova/all-MiniLM-L6-v2',
+                        uptime_seconds: getUptimeSeconds(),
+                    };
+                    logger.debug('registration-tools.get_index_status: completed', {
+                        repoCount: repoStatuses.length,
+                        health,
+                        uptimeSeconds: result.uptime_seconds,
+                    });
+                    return result;
+                }
+                catch (err) {
+                    logger.error('registration-tools.get_index_status: error', { error: String(err) });
+                    return {
+                        error: 'GET_INDEX_STATUS_FAILED',
+                        message: String(err),
+                    };
+                }
+            },
+        },
+    };
+}
+// ---------------------------------------------------------------------------
+// Shared indexing helper
+// ---------------------------------------------------------------------------
+async function runIndex(registry, stores, repoId, repoPath, stackTags, force) {
+    // Build a no-op graph store if FalkorDB is unavailable
+    const effectiveGraphStore = stores.graphStore ?? createNoOpGraphStore();
+    const repoConfig = {
+        id: repoId,
+        path: repoPath,
+        ownership: 'owned',
+        watch: false,
+        languages: stackTags,
+    };
+    return fullIndex({
+        repoConfig,
+        graphStore: effectiveGraphStore,
+        vectorStore: stores.vectorStore,
+        fileCache: stores.fileCache,
+        allRepos: [repoConfig],
+    });
+}
+/**
+ * Minimal no-op graph store for when FalkorDB is unavailable.
+ */
+function createNoOpGraphStore() {
+    return {
+        connect: async () => { },
+        disconnect: async () => { },
+        isHealthy: async () => false,
+        query: async () => ({ nodes: [], edges: [], raw: [] }),
+        upsertNode: async () => { },
+        upsertEdge: async () => { },
+        deleteFile: async () => { },
+        deleteRepo: async () => { },
+        getCounts: async () => ({ totalNodes: 0, totalEdges: 0, byLabel: {} }),
+        ensureIndexes: async () => { },
+    };
+}
+//# sourceMappingURL=registration-tools.js.map

package/dist/tools/registration-tools.js.map

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

package/dist/util/circuit-breaker.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Circuit breaker pattern for external service calls.
+ *
+ * States:
+ *   CLOSED   — normal operation, failures are counted
+ *   OPEN     — failing, all calls rejected immediately after failureThreshold reached
+ *   HALF_OPEN — testing recovery, one probe request allowed
+ *
+ * Transitions:
+ *   CLOSED  → OPEN       after failureThreshold consecutive failures
+ *   OPEN    → HALF_OPEN  after resetTimeoutMs has elapsed
+ *   HALF_OPEN → CLOSED   if the probe request succeeds
+ *   HALF_OPEN → OPEN     if the probe request fails
+ */
+export type CircuitState = 'CLOSED' | 'OPEN' | 'HALF_OPEN';
+export interface CircuitBreakerOptions {
+    /** Number of consecutive failures before tripping to OPEN. Default: 5 */
+    failureThreshold?: number;
+    /** Milliseconds to wait in OPEN before transitioning to HALF_OPEN. Default: 30000 */
+    resetTimeoutMs?: number;
+    /** Name for log messages. */
+    name: string;
+}
+export declare class CircuitBreaker {
+    private state;
+    private consecutiveFailures;
+    private lastFailureTime;
+    private halfOpenProbeInFlight;
+    private readonly failureThreshold;
+    private readonly resetTimeoutMs;
+    private readonly name;
+    constructor(opts: CircuitBreakerOptions);
+    /**
+     * Current state of the circuit breaker.
+     */
+    getState(): CircuitState;
+    /**
+     * Returns true when the breaker allows the call to proceed.
+     * Returns false when OPEN (or HALF_OPEN but a probe is already in flight).
+     */
+    isAllowed(): boolean;
+    /**
+     * Call this when a protected operation succeeds.
+     */
+    recordSuccess(): void;
+    /**
+     * Call this when a protected operation fails.
+     */
+    recordFailure(): void;
+    /**
+     * Execute a function with circuit breaker protection.
+     * Throws CircuitOpenError if the circuit is open.
+     * Automatically records success/failure.
+     */
+    execute<T>(fn: () => Promise<T>): Promise<T>;
+    /**
+     * Convenience: returns true when the circuit is healthy enough to allow requests.
+     * Equivalent to `isAllowed()` but does not reserve the HALF_OPEN probe slot.
+     */
+    isHealthy(): boolean;
+    /**
+     * Force-reset the breaker to CLOSED state. Useful for testing or manual recovery.
+     */
+    reset(): void;
+    /** Internal: check if we should transition from OPEN to HALF_OPEN due to timeout. */
+    private maybeTransitionToHalfOpen;
+    private transitionTo;
+}
+/**
+ * Thrown when a call is rejected because the circuit is open.
+ */
+export declare class CircuitOpenError extends Error {
+    constructor(message: string);
+}
+//# sourceMappingURL=circuit-breaker.d.ts.map

package/dist/util/circuit-breaker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"circuit-breaker.d.ts","sourceRoot":"","sources":["../../src/util/circuit-breaker.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAIH,MAAM,MAAM,YAAY,GAAG,QAAQ,GAAG,MAAM,GAAG,WAAW,CAAC;AAE3D,MAAM,WAAW,qBAAqB;IACpC,yEAAyE;IACzE,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,qFAAqF;IACrF,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,6BAA6B;IAC7B,IAAI,EAAE,MAAM,CAAC;CACd;AAED,qBAAa,cAAc;IACzB,OAAO,CAAC,KAAK,CAA0B;IACvC,OAAO,CAAC,mBAAmB,CAAK;IAChC,OAAO,CAAC,eAAe,CAAK;IAC5B,OAAO,CAAC,qBAAqB,CAAS;IAEtC,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAS;IAC1C,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAS;IACxC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAS;gBAElB,IAAI,EAAE,qBAAqB;IAMvC;;OAEG;IACH,QAAQ,IAAI,YAAY;IAKxB;;;OAGG;IACH,SAAS,IAAI,OAAO;IAkBpB;;OAEG;IACH,aAAa,IAAI,IAAI;IAcrB;;OAEG;IACH,aAAa,IAAI,IAAI;IA0BrB;;;;OAIG;IACG,OAAO,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IAiBlD;;;OAGG;IACH,SAAS,IAAI,OAAO;IAKpB;;OAEG;IACH,KAAK,IAAI,IAAI;IAOb,qFAAqF;IACrF,OAAO,CAAC,yBAAyB;IAajC,OAAO,CAAC,YAAY;CAOrB;AAED;;GAEG;AACH,qBAAa,gBAAiB,SAAQ,KAAK;gBAC7B,OAAO,EAAE,MAAM;CAI5B"}

package/dist/util/circuit-breaker.js

@@ -0,0 +1,159 @@
+/**
+ * Circuit breaker pattern for external service calls.
+ *
+ * States:
+ *   CLOSED   — normal operation, failures are counted
+ *   OPEN     — failing, all calls rejected immediately after failureThreshold reached
+ *   HALF_OPEN — testing recovery, one probe request allowed
+ *
+ * Transitions:
+ *   CLOSED  → OPEN       after failureThreshold consecutive failures
+ *   OPEN    → HALF_OPEN  after resetTimeoutMs has elapsed
+ *   HALF_OPEN → CLOSED   if the probe request succeeds
+ *   HALF_OPEN → OPEN     if the probe request fails
+ */
+import { logger } from './logger.js';
+export class CircuitBreaker {
+    state = 'CLOSED';
+    consecutiveFailures = 0;
+    lastFailureTime = 0;
+    halfOpenProbeInFlight = false;
+    failureThreshold;
+    resetTimeoutMs;
+    name;
+    constructor(opts) {
+        this.name = opts.name;
+        this.failureThreshold = opts.failureThreshold ?? 5;
+        this.resetTimeoutMs = opts.resetTimeoutMs ?? 30_000;
+    }
+    /**
+     * Current state of the circuit breaker.
+     */
+    getState() {
+        this.maybeTransitionToHalfOpen();
+        return this.state;
+    }
+    /**
+     * Returns true when the breaker allows the call to proceed.
+     * Returns false when OPEN (or HALF_OPEN but a probe is already in flight).
+     */
+    isAllowed() {
+        this.maybeTransitionToHalfOpen();
+        if (this.state === 'CLOSED')
+            return true;
+        if (this.state === 'HALF_OPEN') {
+            // Allow exactly one probe through
+            if (!this.halfOpenProbeInFlight) {
+                this.halfOpenProbeInFlight = true;
+                return true;
+            }
+            return false;
+        }
+        // OPEN — reject
+        return false;
+    }
+    /**
+     * Call this when a protected operation succeeds.
+     */
+    recordSuccess() {
+        // Ensure state is up to date before evaluating
+        this.maybeTransitionToHalfOpen();
+        if (this.state === 'HALF_OPEN') {
+            logger.info(`Circuit breaker [${this.name}] recovered — closing`, {
+                previousFailures: this.consecutiveFailures,
+            });
+            this.transitionTo('CLOSED');
+        }
+        this.consecutiveFailures = 0;
+        this.halfOpenProbeInFlight = false;
+    }
+    /**
+     * Call this when a protected operation fails.
+     */
+    recordFailure() {
+        // Ensure state is up to date before evaluating
+        this.maybeTransitionToHalfOpen();
+        this.consecutiveFailures++;
+        this.lastFailureTime = Date.now();
+        this.halfOpenProbeInFlight = false;
+        if (this.state === 'HALF_OPEN') {
+            logger.warn(`Circuit breaker [${this.name}] probe failed — re-opening`, {
+                consecutiveFailures: this.consecutiveFailures,
+            });
+            this.transitionTo('OPEN');
+            return;
+        }
+        if (this.state === 'CLOSED' && this.consecutiveFailures >= this.failureThreshold) {
+            logger.warn(`Circuit breaker [${this.name}] tripped OPEN`, {
+                consecutiveFailures: this.consecutiveFailures,
+                failureThreshold: this.failureThreshold,
+                resetTimeoutMs: this.resetTimeoutMs,
+            });
+            this.transitionTo('OPEN');
+        }
+    }
+    /**
+     * Execute a function with circuit breaker protection.
+     * Throws CircuitOpenError if the circuit is open.
+     * Automatically records success/failure.
+     */
+    async execute(fn) {
+        if (!this.isAllowed()) {
+            throw new CircuitOpenError(`Circuit breaker [${this.name}] is OPEN — request rejected`);
+        }
+        try {
+            const result = await fn();
+            this.recordSuccess();
+            return result;
+        }
+        catch (err) {
+            this.recordFailure();
+            throw err;
+        }
+    }
+    /**
+     * Convenience: returns true when the circuit is healthy enough to allow requests.
+     * Equivalent to `isAllowed()` but does not reserve the HALF_OPEN probe slot.
+     */
+    isHealthy() {
+        this.maybeTransitionToHalfOpen();
+        return this.state === 'CLOSED' || this.state === 'HALF_OPEN';
+    }
+    /**
+     * Force-reset the breaker to CLOSED state. Useful for testing or manual recovery.
+     */
+    reset() {
+        logger.info(`Circuit breaker [${this.name}] manually reset`);
+        this.transitionTo('CLOSED');
+        this.consecutiveFailures = 0;
+        this.halfOpenProbeInFlight = false;
+    }
+    /** Internal: check if we should transition from OPEN to HALF_OPEN due to timeout. */
+    maybeTransitionToHalfOpen() {
+        if (this.state === 'OPEN' &&
+            Date.now() - this.lastFailureTime >= this.resetTimeoutMs) {
+            logger.info(`Circuit breaker [${this.name}] entering HALF_OPEN — probing`, {
+                elapsed: Date.now() - this.lastFailureTime,
+                resetTimeoutMs: this.resetTimeoutMs,
+            });
+            this.transitionTo('HALF_OPEN');
+        }
+    }
+    transitionTo(next) {
+        this.state = next;
+        if (next === 'CLOSED') {
+            this.lastFailureTime = 0;
+            this.halfOpenProbeInFlight = false;
+        }
+    }
+}
+/**
+ * Thrown when a call is rejected because the circuit is open.
+ */
+export class CircuitOpenError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'CircuitOpenError';
+    }
+}
+//# sourceMappingURL=circuit-breaker.js.map

package/dist/util/circuit-breaker.js.map

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