@dotsetlabs/bellwether 2.1.2 → 2.1.3

package/dist/interview/types.d.ts

@@ -5,11 +5,14 @@ import type { ResponseSchemaEvolution } from '../baseline/response-schema-tracke
 import type { ErrorAnalysisSummary } from '../baseline/error-analyzer.js';
 import type { DocumentationScore } from '../baseline/documentation-scorer.js';
 import type { SemanticInference } from '../validation/semantic-types.js';
-import type { Persona, QuestionCategory } from '../persona/types.js';
+import type { Persona } from '../persona/types.js';
+import type { QuestionCategory } from './question-category.js';
 import type { Workflow, WorkflowResult, WorkflowTimeoutConfig } from '../workflow/types.js';
 import type { LoadedScenarios, ScenarioResult } from '../scenarios/types.js';
 import type { ToolResponseCache } from '../cache/response-cache.js';
-import type { TestFixturesConfig } from './schema-test-generator.js';
+import type { TestFixturesConfig } from './test-fixtures.js';
+import type { InterviewQuestion, OutcomeAssessment } from './question-types.js';
+export type { ExpectedOutcome, InterviewQuestion, OutcomeAssessment } from './question-types.js';
 /**
  * Server context extracted during discovery/initial probing.
  * Used to generate contextually appropriate test cases.
@@ -112,84 +115,6 @@ export interface InterviewConfig {
     /** Test fixtures for overriding default parameter values */
     testFixtures?: TestFixturesConfig;
 }
-/**
- * Expected outcome for a test question.
- * - 'success': Test expects the tool to execute successfully
- * - 'error': Test expects the tool to reject/fail (validation test)
- * - 'either': Test outcome is acceptable either way
- */
-export type ExpectedOutcome = 'success' | 'error' | 'either';
-/**
- * A question to ask about a tool's behavior.
- */
-export interface InterviewQuestion {
-    /** Description of what this question tests */
-    description: string;
-    /** Category of question */
-    category: QuestionCategory;
-    /** Arguments to pass to the tool */
-    args: Record<string, unknown>;
-    /**
-     * Expected outcome of this test.
-     * Used to determine if the tool behaved correctly.
-     * - 'success': Expects successful execution (happy path)
-     * - 'error': Expects rejection/error (validation test)
-     * - 'either': Either outcome is acceptable
-     */
-    expectedOutcome?: ExpectedOutcome;
-    /** Semantic validation metadata (for tests generated from semantic type inference) */
-    metadata?: {
-        /** The inferred semantic type being tested */
-        semanticType?: string;
-        /** Expected behavior: 'reject' for invalid values, 'accept' for valid */
-        expectedBehavior?: 'reject' | 'accept';
-        /** Confidence level of the semantic type inference (0-1) */
-        confidence?: number;
-        /** Stateful testing metadata */
-        stateful?: {
-            /** Keys injected from prior tool outputs */
-            usedKeys?: string[];
-            /** Keys captured from this response */
-            providedKeys?: string[];
-        };
-        /**
-         * Whether this tool uses operation-based dispatch pattern.
-         * Tools with this pattern have different required args per operation.
-         */
-        operationBased?: boolean;
-        /** The parameter name that selects the operation (e.g., "operation", "action") */
-        operationParam?: string;
-        /** The parameter name that holds operation-specific args (e.g., "args", "params") */
-        argsParam?: string;
-        /**
-         * Whether this tool requires prior state (session, chain, etc.).
-         * These tools need an active session before they can work.
-         */
-        selfStateful?: boolean;
-        /** Reason for self-stateful detection */
-        selfStatefulReason?: string;
-        /**
-         * Whether this tool has complex array schemas requiring structured data.
-         * Simple test data generation often fails for these tools.
-         */
-        hasComplexArrays?: boolean;
-        /** Array parameters with complex item schemas */
-        complexArrayParams?: string[];
-    };
-}
-/**
- * Assessment of whether a tool interaction outcome matched expectations.
- */
-export interface OutcomeAssessment {
-    /** What outcome was expected */
-    expected: ExpectedOutcome;
-    /** What actually happened */
-    actual: 'success' | 'error';
-    /** Whether the tool behaved correctly (matches expectation) */
-    correct: boolean;
-    /** True if this was a validation test that correctly rejected invalid input */
-    isValidationSuccess?: boolean;
-}
 /**
  * Result of asking a single question.
  */

package/dist/persona/types.d.ts

@@ -1,11 +1,9 @@
 /**
  * Persona types for configurable interviewer personalities.
  */
-import type { InterviewQuestion } from '../interview/types.js';
-/**
- * Question categories that can be weighted by personas.
- */
-export type QuestionCategory = 'happy_path' | 'edge_case' | 'error_handling' | 'boundary' | 'security';
+import type { InterviewQuestion } from '../interview/question-types.js';
+import type { QuestionCategory } from '../interview/question-category.js';
+export type { QuestionCategory } from '../interview/question-category.js';
 /**
  * Weight distribution for question categories.
  * Values should be 0-1 and represent relative likelihood.

package/dist/scenarios/types.d.ts

@@ -4,7 +4,7 @@
  * These types define the schema for user-defined test cases
  * that can be provided via bellwether-tests.yaml files.
  */
-import type { QuestionCategory } from '../persona/types.js';
+import type { QuestionCategory } from '../interview/question-category.js';
 /**
  * Valid assertion conditions for scenario expectations.
  */

package/dist/transport/auth-errors.d.ts

@@ -0,0 +1,15 @@
+import { ServerAuthError } from '../errors/types.js';
+interface AuthErrorConfig {
+    unauthorizedMessage: string;
+    forbiddenMessage: string;
+    proxyMessage?: string;
+    unauthorizedHint?: string;
+    forbiddenHint?: string;
+    proxyHint?: string;
+}
+/**
+ * Map HTTP auth-related status codes to typed transport auth errors.
+ */
+export declare function createServerAuthError(status: number, config: AuthErrorConfig): ServerAuthError | null;
+export {};
+//# sourceMappingURL=auth-errors.d.ts.map

package/dist/transport/auth-errors.js

@@ -0,0 +1,22 @@
+import { ServerAuthError } from '../errors/types.js';
+const DEFAULT_HINTS = {
+    unauthorized: 'Add server.headers.Authorization (for example: Bearer token) in bellwether.yaml or pass --header.',
+    forbidden: 'Credentials are recognized but lack required permissions. Verify token scopes/roles.',
+    proxy: 'Configure proxy credentials and retry.',
+};
+/**
+ * Map HTTP auth-related status codes to typed transport auth errors.
+ */
+export function createServerAuthError(status, config) {
+    if (status === 401) {
+        return new ServerAuthError(config.unauthorizedMessage, 401, config.unauthorizedHint ?? DEFAULT_HINTS.unauthorized);
+    }
+    if (status === 403) {
+        return new ServerAuthError(config.forbiddenMessage, 403, config.forbiddenHint ?? DEFAULT_HINTS.forbidden);
+    }
+    if (status === 407) {
+        return new ServerAuthError(config.proxyMessage ?? 'Proxy authentication required (407)', 407, config.proxyHint ?? DEFAULT_HINTS.proxy);
+    }
+    return null;
+}
+//# sourceMappingURL=auth-errors.js.map

package/dist/transport/http-transport.js

@@ -1,6 +1,6 @@
 import { BaseTransport } from './base-transport.js';
 import { TIMEOUTS, DISPLAY_LIMITS, MCP } from '../constants.js';
-import { ServerAuthError } from '../errors/types.js';
+import { createServerAuthError } from './auth-errors.js';
 /**
  * HTTPTransport connects to MCP servers over HTTP using POST requests.
  *
@@ -112,14 +112,12 @@ export class HTTPTransport extends BaseTransport {
             });
             clearTimeout(timeoutId);
             if (!response.ok) {
-                if (response.status === 401) {
-                    throw new ServerAuthError('Remote MCP server authentication failed (401 Unauthorized)', 401, 'Add server.headers.Authorization (for example: Bearer token) in bellwether.yaml or pass --header.');
-                }
-                if (response.status === 403) {
-                    throw new ServerAuthError('Remote MCP server authorization failed (403 Forbidden)', 403, 'Credentials are recognized but lack required permissions. Verify token scopes/roles.');
-                }
-                if (response.status === 407) {
-                    throw new ServerAuthError('Proxy authentication required (407)', 407, 'Configure proxy credentials and retry.');
+                const authError = createServerAuthError(response.status, {
+                    unauthorizedMessage: 'Remote MCP server authentication failed (401 Unauthorized)',
+                    forbiddenMessage: 'Remote MCP server authorization failed (403 Forbidden)',
+                });
+                if (authError) {
+                    throw authError;
                 }
                 // MCP 2025-11-25: 404 means session expired, clear session ID
                 if (response.status === 404 && this.sessionId) {

package/dist/transport/mcp-client.d.ts

@@ -60,10 +60,6 @@ export declare class MCPClient {
     /** Whether to run an explicit preflight before remote connection */
     private remotePreflight;
     constructor(options?: MCPClientOptions);
-    /**
-     * Merge two header maps, giving precedence to override values.
-     */
-    private mergeHeaders;
     /**
      * Optional remote connectivity/auth preflight (enabled by default).
      * Uses GET (not HEAD/OPTIONS) for broader compatibility.

package/dist/transport/mcp-client.js

@@ -8,6 +8,8 @@ import { VERSION } from '../version.js';
 import { getFeatureFlags, isKnownProtocolVersion, } from '../protocol/index.js';
 import { filterSpawnEnv } from './env-filter.js';
 import { ConnectionError, ServerAuthError } from '../errors/types.js';
+import { mergeHeaderMaps } from '../utils/http-headers.js';
+import { createServerAuthError } from './auth-errors.js';
 const DEFAULT_TIMEOUT = TIMEOUTS.DEFAULT;
 const DEFAULT_STARTUP_DELAY = TIMEOUTS.SERVER_STARTUP;
 /**
@@ -56,31 +58,6 @@ export class MCPClient {
         this.httpConfig = options?.httpConfig;
         this.remotePreflight = options?.remotePreflight ?? true;
     }
-    /**
-     * Merge two header maps, giving precedence to override values.
-     */
-    mergeHeaders(base, override) {
-        if (!base && !override)
-            return undefined;
-        const merged = {};
-        const apply = (headers) => {
-            if (!headers)
-                return;
-            for (const [name, value] of Object.entries(headers)) {
-                const normalized = name.toLowerCase();
-                for (const existing of Object.keys(merged)) {
-                    if (existing.toLowerCase() === normalized) {
-                        delete merged[existing];
-                        break;
-                    }
-                }
-                merged[name] = value;
-            }
-        };
-        apply(base);
-        apply(override);
-        return Object.keys(merged).length > 0 ? merged : undefined;
-    }
     /**
      * Optional remote connectivity/auth preflight (enabled by default).
      * Uses GET (not HEAD/OPTIONS) for broader compatibility.
@@ -112,17 +89,16 @@ export class MCPClient {
                     // Ignore body cancellation failures; preflight status handling is primary.
                 }
             };
-            if (response.status === 401) {
-                await closePreflightBody();
-                throw new ServerAuthError(`Remote MCP preflight failed: unauthorized (${response.status})`, response.status, 'Add authentication headers (for example Authorization) and retry.');
-            }
-            if (response.status === 403) {
-                await closePreflightBody();
-                throw new ServerAuthError(`Remote MCP preflight failed: forbidden (${response.status})`, response.status, 'Credentials are valid but lack required permissions/scopes.');
-            }
-            if (response.status === 407) {
+            const authError = createServerAuthError(response.status, {
+                unauthorizedMessage: `Remote MCP preflight failed: unauthorized (${response.status})`,
+                forbiddenMessage: `Remote MCP preflight failed: forbidden (${response.status})`,
+                proxyMessage: `Remote MCP preflight failed: proxy authentication required (${response.status})`,
+                unauthorizedHint: 'Add authentication headers (for example Authorization) and retry.',
+                forbiddenHint: 'Credentials are valid but lack required permissions/scopes.',
+            });
+            if (authError) {
                 await closePreflightBody();
-                throw new ServerAuthError(`Remote MCP preflight failed: proxy authentication required (${response.status})`, response.status, 'Configure proxy credentials and retry.');
+                throw authError;
             }
             if (!response.ok) {
                 // Non-auth HTTP statuses are compatibility-safe to continue:
@@ -388,8 +364,8 @@ export class MCPClient {
         };
         this.logger.info({ url, transport }, 'Connecting to remote MCP server');
         const mergedHeaders = transport === 'sse'
-            ? this.mergeHeaders(this.sseConfig?.headers, options?.headers)
-            : this.mergeHeaders(this.httpConfig?.headers, options?.headers);
+            ? mergeHeaderMaps(this.sseConfig?.headers, options?.headers)
+            : mergeHeaderMaps(this.httpConfig?.headers, options?.headers);
         await this.preflightRemote(url, transport, mergedHeaders);
         if (transport === 'sse') {
             const sseTransport = new SSETransport({

package/dist/transport/sse-transport.d.ts

@@ -30,7 +30,6 @@ export interface SSETransportConfig extends BaseTransportConfig {
  */
 export declare class SSETransport extends BaseTransport {
     private streamAbortController;
-    private abortController;
     private connected;
     private reconnectAttempts;
     private readonly baseUrl;

package/dist/transport/sse-transport.js

@@ -1,7 +1,7 @@
 import { BaseTransport } from './base-transport.js';
 import { TIME_CONSTANTS, TIMEOUTS } from '../constants.js';
 import { isLocalhost } from '../utils/index.js';
-import { ServerAuthError } from '../errors/types.js';
+import { createServerAuthError } from './auth-errors.js';
 /**
  * Validate that a URL uses HTTPS in production contexts.
  * Allows HTTP only for localhost/127.0.0.1 for local development.
@@ -103,7 +103,6 @@ class SSEParser {
  */
 export class SSETransport extends BaseTransport {
     streamAbortController = null;
-    abortController = null;
     connected = false;
     reconnectAttempts = 0;
     baseUrl;
@@ -162,14 +161,12 @@ export class SSETransport extends BaseTransport {
             signal: this.streamAbortController.signal,
         });
         if (!response.ok) {
-            if (response.status === 401) {
-                throw new ServerAuthError('Remote MCP SSE authentication failed (401 Unauthorized)', 401, 'Add server.headers.Authorization (for example: Bearer token) in bellwether.yaml or pass --header.');
-            }
-            if (response.status === 403) {
-                throw new ServerAuthError('Remote MCP SSE authorization failed (403 Forbidden)', 403, 'Credentials are recognized but lack required permissions. Verify token scopes/roles.');
-            }
-            if (response.status === 407) {
-                throw new ServerAuthError('Proxy authentication required (407)', 407, 'Configure proxy credentials and retry.');
+            const authError = createServerAuthError(response.status, {
+                unauthorizedMessage: 'Remote MCP SSE authentication failed (401 Unauthorized)',
+                forbiddenMessage: 'Remote MCP SSE authorization failed (403 Forbidden)',
+            });
+            if (authError) {
+                throw authError;
             }
             throw new Error(`Failed to connect to SSE endpoint: HTTP ${response.status}`);
         }
@@ -344,14 +341,12 @@ export class SSETransport extends BaseTransport {
             .then(async (response) => {
             clearTimeout(timeoutId);
             if (!response.ok) {
-                if (response.status === 401) {
-                    throw new ServerAuthError('Remote MCP message authentication failed (401 Unauthorized)', 401, 'Add server.headers.Authorization (for example: Bearer token) in bellwether.yaml or pass --header.');
-                }
-                if (response.status === 403) {
-                    throw new ServerAuthError('Remote MCP message authorization failed (403 Forbidden)', 403, 'Credentials are recognized but lack required permissions. Verify token scopes/roles.');
-                }
-                if (response.status === 407) {
-                    throw new ServerAuthError('Proxy authentication required (407)', 407, 'Configure proxy credentials and retry.');
+                const authError = createServerAuthError(response.status, {
+                    unauthorizedMessage: 'Remote MCP message authentication failed (401 Unauthorized)',
+                    forbiddenMessage: 'Remote MCP message authorization failed (403 Forbidden)',
+                });
+                if (authError) {
+                    throw authError;
                 }
                 const errorText = await response.text().catch(() => 'Unknown error');
                 throw new Error(`HTTP ${response.status}: ${errorText}`);
@@ -404,16 +399,6 @@ export class SSETransport extends BaseTransport {
             }
             this.streamAbortController = null;
         }
-        // Abort any in-flight HTTP requests
-        if (this.abortController) {
-            try {
-                this.abortController.abort();
-            }
-            catch {
-                // Ignore abort errors
-            }
-            this.abortController = null;
-        }
         this.messageEndpoint = null;
         this.reconnectAttempts = 0;
         this.emit('close');

package/dist/utils/content-type.d.ts

@@ -0,0 +1,14 @@
+export type DetectedContentType = 'json' | 'markdown' | 'text';
+export interface DetectContentTypeOptions {
+    /**
+     * Markdown detection mode:
+     * - `strict`: conservative heading/link/fence patterns (legacy contract/golden behavior)
+     * - `lenient`: broader markdown indicators (legacy smart-truncate behavior)
+     */
+    markdownHeuristics?: 'strict' | 'lenient';
+}
+/**
+ * Detect whether content is JSON, Markdown, or plain text.
+ */
+export declare function detectContentType(content: string, options?: DetectContentTypeOptions): DetectedContentType;
+//# sourceMappingURL=content-type.d.ts.map

package/dist/utils/content-type.js

@@ -0,0 +1,37 @@
+function looksLikeMarkdownStrict(trimmed) {
+    return /^#|^\*{1,3}[^*]|\[.*\]\(.*\)|^```/.test(trimmed);
+}
+function looksLikeMarkdownLenient(trimmed) {
+    if (looksLikeMarkdownStrict(trimmed)) {
+        return true;
+    }
+    return (trimmed.includes('\n#') ||
+        /^[-*]\s/.test(trimmed) ||
+        /^\d+\.\s/.test(trimmed) ||
+        trimmed.includes('```') ||
+        trimmed.includes('**') ||
+        trimmed.includes('__'));
+}
+/**
+ * Detect whether content is JSON, Markdown, or plain text.
+ */
+export function detectContentType(content, options = {}) {
+    const mode = options.markdownHeuristics ?? 'strict';
+    const trimmed = content.trim();
+    if ((trimmed.startsWith('{') && trimmed.endsWith('}')) ||
+        (trimmed.startsWith('[') && trimmed.endsWith(']'))) {
+        try {
+            JSON.parse(trimmed);
+            return 'json';
+        }
+        catch {
+            // Not valid JSON
+        }
+    }
+    const isMarkdown = mode === 'lenient' ? looksLikeMarkdownLenient(trimmed) : looksLikeMarkdownStrict(trimmed);
+    if (isMarkdown) {
+        return 'markdown';
+    }
+    return 'text';
+}
+//# sourceMappingURL=content-type.js.map

package/dist/utils/http-headers.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Merge HTTP header maps case-insensitively, preserving latest key casing.
+ */
+export declare function mergeHeaderMaps(base?: Record<string, string>, override?: Record<string, string>): Record<string, string> | undefined;
+/**
+ * Set a header while treating header names as case-insensitive.
+ */
+export declare function setHeaderCaseInsensitive(headers: Record<string, string>, name: string, value: string): void;
+//# sourceMappingURL=http-headers.d.ts.map

package/dist/utils/http-headers.js

@@ -0,0 +1,34 @@
+/**
+ * Merge HTTP header maps case-insensitively, preserving latest key casing.
+ */
+export function mergeHeaderMaps(base, override) {
+    if (!base && !override) {
+        return undefined;
+    }
+    const merged = {};
+    if (base) {
+        for (const [name, value] of Object.entries(base)) {
+            setHeaderCaseInsensitive(merged, name, value);
+        }
+    }
+    if (override) {
+        for (const [name, value] of Object.entries(override)) {
+            setHeaderCaseInsensitive(merged, name, value);
+        }
+    }
+    return Object.keys(merged).length > 0 ? merged : undefined;
+}
+/**
+ * Set a header while treating header names as case-insensitive.
+ */
+export function setHeaderCaseInsensitive(headers, name, value) {
+    const normalized = name.toLowerCase();
+    for (const existing of Object.keys(headers)) {
+        if (existing.toLowerCase() === normalized) {
+            delete headers[existing];
+            break;
+        }
+    }
+    headers[name] = value;
+}
+//# sourceMappingURL=http-headers.js.map

package/dist/utils/smart-truncate.js

@@ -11,6 +11,7 @@
  * - Provide helpful truncation indicators
  */
 import { EXAMPLE_OUTPUT } from '../constants.js';
+import { detectContentType as detectGeneralContentType } from './content-type.js';
 // ==================== Main Functions ====================
 /**
  * Smart truncate content based on type.
@@ -321,29 +322,7 @@ function truncateAtSentence(text, maxLength) {
  * @returns Detected content type
  */
 export function detectContentType(content) {
-    const trimmed = content.trim();
-    // Check for JSON
-    if ((trimmed.startsWith('{') && trimmed.endsWith('}')) ||
-        (trimmed.startsWith('[') && trimmed.endsWith(']'))) {
-        try {
-            JSON.parse(trimmed);
-            return 'json';
-        }
-        catch {
-            // Not valid JSON
-        }
-    }
-    // Check for Markdown indicators
-    if (trimmed.includes('\n#') ||
-        trimmed.startsWith('#') ||
-        /^[-*]\s/.test(trimmed) ||
-        /^\d+\.\s/.test(trimmed) ||
-        trimmed.includes('```') ||
-        trimmed.includes('**') ||
-        trimmed.includes('__')) {
-        return 'markdown';
-    }
-    return 'text';
+    return detectGeneralContentType(content, { markdownHeuristics: 'lenient' });
 }
 /**
  * Get the appropriate example length based on options.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dotsetlabs/bellwether",
-  "version": "2.1.2",
+  "version": "2.1.3",
   "description": "The open-source MCP testing tool. Structural drift detection and behavioral documentation for Model Context Protocol servers.",
   "type": "module",
   "main": "dist/index.js",
@@ -34,7 +34,7 @@
     "format:check": "prettier --check \"src/**/*.ts\"",
     "check:consistency": "node ./scripts/validate-consistency.mjs",
     "clean": "rm -rf dist",
-    "docs:generate": "npm --prefix website run build",
+    "docs:generate": "node ./scripts/build-docs.mjs",
     "docs:dev": "npm --prefix website run start",
     "prepublishOnly": "npm run build"
   },