@dotsetlabs/bellwether 0.10.0

package/dist/transport/types.d.ts

@@ -0,0 +1,125 @@
+/**
+ * JSON-RPC 2.0 types for MCP protocol communication.
+ */
+export interface JSONRPCRequest {
+    jsonrpc: '2.0';
+    id: string | number;
+    method: string;
+    params?: unknown;
+}
+export interface JSONRPCResponse {
+    jsonrpc: '2.0';
+    id: string | number;
+    result?: unknown;
+    error?: JSONRPCError;
+}
+export interface JSONRPCError {
+    code: number;
+    message: string;
+    data?: unknown;
+}
+export interface JSONRPCNotification {
+    jsonrpc: '2.0';
+    method: string;
+    params?: unknown;
+}
+export type JSONRPCMessage = JSONRPCRequest | JSONRPCResponse | JSONRPCNotification;
+/**
+ * MCP Protocol types
+ */
+export interface MCPTool {
+    name: string;
+    description?: string;
+    inputSchema?: Record<string, unknown>;
+}
+export interface MCPPrompt {
+    name: string;
+    description?: string;
+    arguments?: MCPPromptArgument[];
+}
+export interface MCPPromptArgument {
+    name: string;
+    description?: string;
+    required?: boolean;
+}
+export interface MCPServerCapabilities {
+    tools?: Record<string, unknown>;
+    prompts?: Record<string, unknown>;
+    resources?: Record<string, unknown>;
+    logging?: Record<string, unknown>;
+}
+export interface MCPServerInfo {
+    name: string;
+    version: string;
+}
+export interface MCPInitializeResult {
+    protocolVersion: string;
+    capabilities: MCPServerCapabilities;
+    serverInfo: MCPServerInfo;
+}
+export interface MCPToolCallResult {
+    content: MCPContentBlock[];
+    isError?: boolean;
+}
+export interface MCPContentBlock {
+    type: 'text' | 'image' | 'resource';
+    text?: string;
+    data?: string;
+    mimeType?: string;
+}
+export interface MCPToolsListResult {
+    tools: MCPTool[];
+}
+export interface MCPPromptsListResult {
+    prompts: MCPPrompt[];
+}
+/**
+ * MCP Resource types
+ */
+export interface MCPResource {
+    /** URI identifying the resource */
+    uri: string;
+    /** Human-readable name */
+    name: string;
+    /** Description of the resource */
+    description?: string;
+    /** MIME type of the resource content */
+    mimeType?: string;
+}
+export interface MCPResourcesListResult {
+    resources: MCPResource[];
+}
+export interface MCPResourceReadResult {
+    contents: MCPResourceContent[];
+}
+export interface MCPResourceContent {
+    /** URI of the resource */
+    uri: string;
+    /** MIME type of the content */
+    mimeType?: string;
+    /** Text content (for text resources) */
+    text?: string;
+    /** Binary content as base64 (for binary resources) */
+    blob?: string;
+}
+export interface MCPPromptMessage {
+    role: 'user' | 'assistant';
+    content: MCPPromptContent;
+}
+export interface MCPPromptContent {
+    type: 'text' | 'image' | 'resource';
+    text?: string;
+    data?: string;
+    mimeType?: string;
+}
+export interface MCPPromptGetResult {
+    description?: string;
+    messages: MCPPromptMessage[];
+}
+/**
+ * Type guards
+ */
+export declare function isRequest(msg: JSONRPCMessage): msg is JSONRPCRequest;
+export declare function isResponse(msg: JSONRPCMessage): msg is JSONRPCResponse;
+export declare function isNotification(msg: JSONRPCMessage): msg is JSONRPCNotification;
+//# sourceMappingURL=types.d.ts.map

package/dist/transport/types.js

@@ -0,0 +1,16 @@
+/**
+ * JSON-RPC 2.0 types for MCP protocol communication.
+ */
+/**
+ * Type guards
+ */
+export function isRequest(msg) {
+    return 'method' in msg && 'id' in msg && msg.id !== undefined;
+}
+export function isResponse(msg) {
+    return 'id' in msg && ('result' in msg || 'error' in msg);
+}
+export function isNotification(msg) {
+    return 'method' in msg && !('id' in msg && msg.id !== undefined);
+}
+//# sourceMappingURL=types.js.map

package/dist/utils/concurrency.d.ts

@@ -0,0 +1,123 @@
+/**
+ * Concurrency utilities for parallel execution with limits.
+ */
+/**
+ * Options for parallel execution.
+ */
+export interface ParallelOptions<T> {
+    /** Maximum concurrent tasks (default: 3) */
+    concurrency?: number;
+    /** Callback when a task completes */
+    onTaskComplete?: (result: T, index: number) => void;
+    /** Callback when a task fails */
+    onTaskError?: (error: Error, index: number) => void;
+}
+/**
+ * Result of a parallel execution.
+ */
+export interface ParallelResult<T> {
+    /** Successful results */
+    results: T[];
+    /** Errors by index */
+    errors: Map<number, Error>;
+    /** Whether all tasks succeeded */
+    allSucceeded: boolean;
+}
+/**
+ * Execute tasks in parallel with a concurrency limit.
+ * Uses a semaphore pattern to limit concurrent execution.
+ *
+ * @param tasks - Array of async task functions to execute
+ * @param options - Parallel execution options
+ * @returns Results of all tasks
+ */
+export declare function parallelLimit<T>(tasks: Array<() => Promise<T>>, options?: ParallelOptions<T>): Promise<ParallelResult<T>>;
+/**
+ * Execute tasks in parallel with a concurrency limit, collecting all results.
+ * Unlike parallelLimit, this version preserves order and includes errors inline.
+ *
+ * @param items - Array of items to process
+ * @param fn - Async function to process each item
+ * @param options - Parallel execution options
+ * @returns Array of results (or errors) in original order
+ */
+export declare function mapLimit<T, R>(items: T[], fn: (item: T, index: number) => Promise<R>, options?: ParallelOptions<R>): Promise<Array<{
+    success: true;
+    value: R;
+} | {
+    success: false;
+    error: Error;
+}>>;
+/**
+ * Create a semaphore for limiting concurrent access to a resource.
+ */
+export declare function createSemaphore(limit: number): {
+    acquire(): Promise<void>;
+    release(): void;
+    readonly available: number;
+    readonly waiting: number;
+};
+/**
+ * Mutex for ensuring exclusive access to a resource.
+ */
+export declare function createMutex(): {
+    acquire(): Promise<void>;
+    release(): void;
+    readonly available: number;
+    readonly waiting: number;
+};
+/**
+ * Thread-safe accumulator for collecting results from parallel tasks.
+ */
+export declare class SafeAccumulator<T> {
+    private items;
+    private mutex;
+    /**
+     * Add an item to the accumulator.
+     */
+    add(item: T): Promise<void>;
+    /**
+     * Add multiple items to the accumulator.
+     */
+    addAll(items: T[]): Promise<void>;
+    /**
+     * Get all accumulated items.
+     */
+    getAll(): T[];
+    /**
+     * Get the current count.
+     */
+    get count(): number;
+}
+/**
+ * Thread-safe map for collecting keyed results.
+ */
+export declare class SafeMap<K, V> {
+    private map;
+    private mutex;
+    /**
+     * Set a value in the map.
+     */
+    set(key: K, value: V): Promise<void>;
+    /**
+     * Get a value from the map.
+     */
+    get(key: K): V | undefined;
+    /**
+     * Check if a key exists.
+     */
+    has(key: K): boolean;
+    /**
+     * Get all entries.
+     */
+    entries(): IterableIterator<[K, V]>;
+    /**
+     * Get all values.
+     */
+    values(): IterableIterator<V>;
+    /**
+     * Get the current size.
+     */
+    get size(): number;
+}
+//# sourceMappingURL=concurrency.d.ts.map

package/dist/utils/concurrency.js

@@ -0,0 +1,213 @@
+/**
+ * Concurrency utilities for parallel execution with limits.
+ */
+/**
+ * Execute tasks in parallel with a concurrency limit.
+ * Uses a semaphore pattern to limit concurrent execution.
+ *
+ * @param tasks - Array of async task functions to execute
+ * @param options - Parallel execution options
+ * @returns Results of all tasks
+ */
+export async function parallelLimit(tasks, options = {}) {
+    const { concurrency = 3, onTaskComplete, onTaskError } = options;
+    const results = new Array(tasks.length);
+    const errors = new Map();
+    let running = 0;
+    let index = 0;
+    return new Promise((resolve) => {
+        const startNext = () => {
+            // Check if we're done
+            if (index >= tasks.length && running === 0) {
+                resolve({
+                    results,
+                    errors,
+                    allSucceeded: errors.size === 0,
+                });
+                return;
+            }
+            // Start tasks up to concurrency limit
+            while (running < concurrency && index < tasks.length) {
+                const currentIndex = index++;
+                running++;
+                tasks[currentIndex]()
+                    .then((result) => {
+                    results[currentIndex] = result;
+                    onTaskComplete?.(result, currentIndex);
+                })
+                    .catch((error) => {
+                    const err = error instanceof Error ? error : new Error(String(error));
+                    errors.set(currentIndex, err);
+                    onTaskError?.(err, currentIndex);
+                })
+                    .finally(() => {
+                    running--;
+                    startNext();
+                });
+            }
+        };
+        // Handle empty task list
+        if (tasks.length === 0) {
+            resolve({
+                results: [],
+                errors: new Map(),
+                allSucceeded: true,
+            });
+            return;
+        }
+        startNext();
+    });
+}
+/**
+ * Execute tasks in parallel with a concurrency limit, collecting all results.
+ * Unlike parallelLimit, this version preserves order and includes errors inline.
+ *
+ * @param items - Array of items to process
+ * @param fn - Async function to process each item
+ * @param options - Parallel execution options
+ * @returns Array of results (or errors) in original order
+ */
+export async function mapLimit(items, fn, options = {}) {
+    const tasks = items.map((item, i) => async () => fn(item, i));
+    const { results, errors } = await parallelLimit(tasks, options);
+    return items.map((_, i) => {
+        const error = errors.get(i);
+        if (error) {
+            return { success: false, error };
+        }
+        return { success: true, value: results[i] };
+    });
+}
+/**
+ * Create a semaphore for limiting concurrent access to a resource.
+ */
+export function createSemaphore(limit) {
+    let current = 0;
+    const queue = [];
+    return {
+        async acquire() {
+            if (current < limit) {
+                current++;
+                return;
+            }
+            return new Promise((resolve) => {
+                queue.push(() => {
+                    current++;
+                    resolve();
+                });
+            });
+        },
+        release() {
+            current--;
+            if (queue.length > 0) {
+                const next = queue.shift();
+                next?.();
+            }
+        },
+        get available() {
+            return limit - current;
+        },
+        get waiting() {
+            return queue.length;
+        },
+    };
+}
+/**
+ * Mutex for ensuring exclusive access to a resource.
+ */
+export function createMutex() {
+    return createSemaphore(1);
+}
+/**
+ * Thread-safe accumulator for collecting results from parallel tasks.
+ */
+export class SafeAccumulator {
+    items = [];
+    mutex = createMutex();
+    /**
+     * Add an item to the accumulator.
+     */
+    async add(item) {
+        await this.mutex.acquire();
+        try {
+            this.items.push(item);
+        }
+        finally {
+            this.mutex.release();
+        }
+    }
+    /**
+     * Add multiple items to the accumulator.
+     */
+    async addAll(items) {
+        await this.mutex.acquire();
+        try {
+            this.items.push(...items);
+        }
+        finally {
+            this.mutex.release();
+        }
+    }
+    /**
+     * Get all accumulated items.
+     */
+    getAll() {
+        return [...this.items];
+    }
+    /**
+     * Get the current count.
+     */
+    get count() {
+        return this.items.length;
+    }
+}
+/**
+ * Thread-safe map for collecting keyed results.
+ */
+export class SafeMap {
+    map = new Map();
+    mutex = createMutex();
+    /**
+     * Set a value in the map.
+     */
+    async set(key, value) {
+        await this.mutex.acquire();
+        try {
+            this.map.set(key, value);
+        }
+        finally {
+            this.mutex.release();
+        }
+    }
+    /**
+     * Get a value from the map.
+     */
+    get(key) {
+        return this.map.get(key);
+    }
+    /**
+     * Check if a key exists.
+     */
+    has(key) {
+        return this.map.has(key);
+    }
+    /**
+     * Get all entries.
+     */
+    entries() {
+        return this.map.entries();
+    }
+    /**
+     * Get all values.
+     */
+    values() {
+        return this.map.values();
+    }
+    /**
+     * Get the current size.
+     */
+    get size() {
+        return this.map.size;
+    }
+}
+//# sourceMappingURL=concurrency.js.map

package/dist/utils/formatters.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Centralized formatting utilities.
+ */
+/**
+ * Format a date as ISO date string (YYYY-MM-DD).
+ */
+export declare function formatDateISO(date: Date): string;
+/**
+ * Format an ISO date string for display with locale formatting.
+ */
+export declare function formatDateLocale(isoString: string): string;
+/**
+ * Format a duration in milliseconds for human-readable display.
+ */
+export declare function formatDuration(ms: number): string;
+//# sourceMappingURL=formatters.d.ts.map

package/dist/utils/formatters.js

@@ -0,0 +1,37 @@
+/**
+ * Centralized formatting utilities.
+ */
+/**
+ * Format a date as ISO date string (YYYY-MM-DD).
+ */
+export function formatDateISO(date) {
+    return date.toISOString().split('T')[0];
+}
+/**
+ * Format an ISO date string for display with locale formatting.
+ */
+export function formatDateLocale(isoString) {
+    const date = new Date(isoString);
+    return date.toLocaleString(undefined, {
+        year: 'numeric',
+        month: 'short',
+        day: 'numeric',
+        hour: '2-digit',
+        minute: '2-digit',
+    });
+}
+/**
+ * Format a duration in milliseconds for human-readable display.
+ */
+export function formatDuration(ms) {
+    if (ms < 1000) {
+        return `${ms}ms`;
+    }
+    if (ms < 60000) {
+        return `${(ms / 1000).toFixed(1)}s`;
+    }
+    const minutes = Math.floor(ms / 60000);
+    const seconds = Math.floor((ms % 60000) / 1000);
+    return `${minutes}m ${seconds}s`;
+}
+//# sourceMappingURL=formatters.js.map

package/dist/utils/index.d.ts

@@ -0,0 +1,8 @@
+export { formatDateISO, formatDateLocale, formatDuration } from './formatters.js';
+export { sanitizeForPrompt, sanitizeObjectForPrompt, sanitizeToolForPrompt, createDataSection, hasInjectionPatterns, truncateForPrompt, type SanitizeResult, } from './sanitize.js';
+export { withTimeout, withTimeoutResult, withTimeoutAll, withTimeoutRetry, createTimeoutAbortController, createDeadline, TimeoutError, DEFAULT_TIMEOUTS, type TimeoutConfig, } from './timeout.js';
+export { parallelLimit, mapLimit, createSemaphore, createMutex, SafeAccumulator, SafeMap, type ParallelOptions, type ParallelResult, } from './concurrency.js';
+export { parsePath, getValueAtPath, getValueBySegments, isValidPath, normalizePath, type ParseResult, } from './jsonpath.js';
+export { escapeTableCell, escapeCodeBlock, escapeMermaid, mermaidLabel, validateJsonForCodeBlock, escapeInlineCode, escapeLinkTitle, escapeListItem, wrapTableCell, buildTable, type JsonCodeBlockOptions, type JsonCodeBlockResult, } from './markdown.js';
+export { isLocalhost } from './network.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/utils/index.js

@@ -0,0 +1,8 @@
+export { formatDateISO, formatDateLocale, formatDuration } from './formatters.js';
+export { sanitizeForPrompt, sanitizeObjectForPrompt, sanitizeToolForPrompt, createDataSection, hasInjectionPatterns, truncateForPrompt, } from './sanitize.js';
+export { withTimeout, withTimeoutResult, withTimeoutAll, withTimeoutRetry, createTimeoutAbortController, createDeadline, TimeoutError, DEFAULT_TIMEOUTS, } from './timeout.js';
+export { parallelLimit, mapLimit, createSemaphore, createMutex, SafeAccumulator, SafeMap, } from './concurrency.js';
+export { parsePath, getValueAtPath, getValueBySegments, isValidPath, normalizePath, } from './jsonpath.js';
+export { escapeTableCell, escapeCodeBlock, escapeMermaid, mermaidLabel, validateJsonForCodeBlock, escapeInlineCode, escapeLinkTitle, escapeListItem, wrapTableCell, buildTable, } from './markdown.js';
+export { isLocalhost } from './network.js';
+//# sourceMappingURL=index.js.map

package/dist/utils/jsonpath.d.ts

@@ -0,0 +1,87 @@
+/**
+ * JSONPath parsing utilities.
+ *
+ * Supports a subset of JSONPath syntax for accessing nested values:
+ * - Dot notation: "foo.bar.baz"
+ * - Bracket notation: "foo['bar']" or "foo[\"bar\"]"
+ * - Array indices: "items[0]" or "items['0']"
+ * - Mixed: "foo.items[0].bar"
+ * - Escaped characters: "foo['bar.baz']" for keys containing dots
+ * - Special characters: "foo['key with spaces']" or "foo['key\"with\"quotes']"
+ */
+/**
+ * Token types for JSONPath parsing.
+ */
+type TokenType = 'property' | 'index' | 'bracket_property';
+/**
+ * A parsed path segment.
+ */
+interface PathSegment {
+    type: TokenType;
+    value: string | number;
+}
+/**
+ * Result of parsing a JSONPath expression.
+ */
+export interface ParseResult {
+    segments: PathSegment[];
+    error?: string;
+}
+/**
+ * Parse a JSONPath expression into segments.
+ *
+ * @param path - The JSONPath expression to parse
+ * @returns ParseResult with segments or error
+ */
+export declare function parsePath(path: string): ParseResult;
+/**
+ * Get a value from an object using a parsed path.
+ *
+ * @param obj - The object to access
+ * @param segments - The parsed path segments
+ * @returns The value at the path, or undefined if not found
+ */
+export declare function getValueBySegments(obj: unknown, segments: PathSegment[]): unknown;
+/**
+ * Get a value from an object using a JSONPath expression.
+ *
+ * This is the main API function combining parsing and value retrieval.
+ *
+ * @param obj - The object to access
+ * @param path - The JSONPath expression
+ * @returns The value at the path, or undefined if not found or path is invalid
+ *
+ * @example
+ * // Simple paths
+ * getValueAtPath({ a: { b: 1 } }, 'a.b') // => 1
+ *
+ * @example
+ * // Array access
+ * getValueAtPath({ items: [1, 2, 3] }, 'items[1]') // => 2
+ *
+ * @example
+ * // Keys with dots
+ * getValueAtPath({ 'key.with.dots': 42 }, "['key.with.dots']") // => 42
+ *
+ * @example
+ * // Keys with spaces
+ * getValueAtPath({ 'my key': 'value' }, "['my key']") // => 'value'
+ */
+export declare function getValueAtPath(obj: unknown, path: string): unknown;
+/**
+ * Check if a path is valid JSONPath syntax.
+ *
+ * @param path - The path to validate
+ * @returns True if the path is valid, false otherwise
+ */
+export declare function isValidPath(path: string): boolean;
+/**
+ * Convert a JSONPath expression to a normalized form.
+ * Useful for comparing paths that may use different notations.
+ *
+ * @param path - The path to normalize
+ * @returns Normalized path string, or the original if parsing fails
+ */
+export declare function normalizePath(path: string): string;
+export {};
+//# sourceMappingURL=jsonpath.d.ts.map