@dotsetlabs/bellwether 2.1.0 → 2.1.1

package/README.md

@@ -31,6 +31,15 @@ bellwether check
 
 That's it. No API keys. No LLM costs. Runs in seconds.
 
+## Product Focus
+
+Bellwether is intentionally opinionated:
+
+- **Core workflow (default)**: `init` -> `check` -> `baseline`
+- **Advanced workflow (opt-in)**: `explore`, `watch`, `discover`, `golden`, `contract`, `registry`
+
+If you only need CI-safe drift detection, you can stay entirely in the core workflow.
+
 ## Two Modes
 
 | Mode | Purpose | Cost | When to Use |
@@ -85,45 +94,29 @@ jobs:
 
 Comparisons are **protocol-version-aware** — version-specific fields (annotations, titles, output schemas, etc.) are only compared when both baselines support the relevant MCP protocol version.
 
-## Commands
-
-### Essential Commands
-
-```bash
-bellwether init <server-command>   # Create config
-bellwether check                   # Detect drift (free, deterministic)
-bellwether baseline save           # Save baseline to compare against
-bellwether baseline compare        # Compare current vs saved baseline
-```
+## Command Tiers
 
-### Explore Command (Optional)
+### Core Commands (Recommended)
 
-```bash
-bellwether init --preset local npx @mcp/server  # Uses Ollama (free)
-bellwether explore                              # LLM-powered testing
-```
-
-Requires LLM (Ollama for free local, or OpenAI/Anthropic). Generates `AGENTS.md` with behavioral documentation.
+| Command | Purpose |
+|:--------|:--------|
+| `init` | Create `bellwether.yaml` |
+| `check` | Deterministic schema drift detection |
+| `baseline save` | Save snapshot for future comparisons |
+| `baseline compare` | Compare latest check output to saved baseline |
 
-### All Commands
+### Advanced Commands (Optional)
 
 | Command | Purpose |
 |:--------|:--------|
-| `init` | Create `bellwether.yaml` config |
-| `check` | Schema drift detection (free) |
-| `explore` | LLM behavioral testing |
-| `baseline save` | Save test results as baseline |
-| `baseline compare` | Compare against baseline |
-| `baseline show` | Display baseline contents |
-| `baseline accept` | Accept drift as intentional |
-| `baseline diff` | Compare two baselines |
-| `discover` | Show server capabilities |
+| `explore` | LLM behavioral testing and `AGENTS.md` generation |
 | `watch` | Continuous checking on file changes |
+| `discover` | Capability inspection without tests |
 | `registry` | Search MCP Registry |
 | `golden` | Golden output regression testing |
-| `contract` | Contract validation (generate/validate/show) |
+| `contract` | Contract validation and generation |
 | `auth` | Manage LLM provider API keys |
-| `validate-config` | Validate bellwether.yaml without running tests |
+| `validate-config` | Validate `bellwether.yaml` without running tests |
 
 ## CI/CD Exit Codes
 
@@ -139,9 +132,9 @@ Requires LLM (Ollama for free local, or OpenAI/Anthropic). Generates `AGENTS.md`
 ## GitHub Action
 
 ```yaml
-- uses: dotsetlabs/bellwether@v2.0.0
+- uses: dotsetlabs/bellwether@v2.1.1
   with:
-    version: '2.0.0'
+    version: '2.1.1'
     server-command: 'npx @mcp/your-server'
     baseline-path: './bellwether-baseline.json'
     fail-on-severity: 'warning'
@@ -170,8 +163,17 @@ bellwether init --preset local npx @mcp/server # Local Ollama (free)
 **[docs.bellwether.sh](https://docs.bellwether.sh)** — Full reference for configuration and commands.
 
 - [Quick Start](https://docs.bellwether.sh/quickstart)
+- [Core vs Advanced](https://docs.bellwether.sh/concepts/core-vs-advanced)
 - [CLI Reference](https://docs.bellwether.sh/cli/init)
 - [CI/CD Integration](https://docs.bellwether.sh/guides/ci-cd)
+- [Golden Paths](https://docs.bellwether.sh/guides/golden-paths)
+- [Compatibility Policy](https://docs.bellwether.sh/concepts/compatibility-policy)
+
+## Project Governance
+
+- [Roadmap](./ROADMAP.md)
+- [Changelog](./CHANGELOG.md)
+- [Security Policy](./SECURITY.md)
 
 ## Community
 

package/dist/cli/index.js

@@ -86,42 +86,37 @@ Bellwether - MCP Server Validation & Documentation
 const examples = `
 Examples:
 
-  Initialize configuration:
-    $ bellwether init                       # Create bellwether.yaml
-    $ bellwether init --preset ci           # Optimized for CI/CD
-    $ bellwether init --preset local        # Local LLM with Ollama
+  Core workflow (recommended):
+    $ bellwether init npx @mcp/my-server    # Create bellwether.yaml
+    $ bellwether check                      # Free, deterministic drift detection
+    $ bellwether baseline save              # Save baseline snapshot
+    $ bellwether check --fail-on-drift      # CI/CD gating
 
-  Check for drift (free, fast, deterministic):
-    $ bellwether check npx @mcp/my-server   # Validate schemas
-    $ bellwether baseline save              # Save baseline
-    $ bellwether baseline compare ./bellwether-baseline.json  # Detect drift
-
-  Explore behavior (LLM-powered):
-    $ bellwether explore npx @mcp/my-server # Generate AGENTS.md documentation
-
-  Discover server capabilities:
-    $ bellwether discover npx @mcp/server-postgres
-
-  Search MCP Registry:
-    $ bellwether registry filesystem
+  Advanced workflow (opt-in):
+    $ bellwether explore                    # LLM behavioral exploration
+    $ bellwether discover                   # Quick capability inspection
+    $ bellwether watch                      # Continuous checking
 
 Documentation: https://docs.bellwether.sh
 `;
 program
     .name('bellwether')
     .description(`${banner}
-Check MCP servers for drift. Explore behavior. Generate documentation.
+Deterministic MCP drift detection with an optional advanced analysis layer.
 
-Commands:
-  check    - Schema validation and drift detection (free, fast, deterministic)
-  explore  - LLM-powered behavioral exploration and documentation
-  discover - Quick capability discovery (no tests)
-  registry - Search the MCP Registry
-  baseline - Manage baselines (save/compare/accept/diff/show)
-  golden   - Golden output regression testing
-  contract - Contract validation (generate/validate/show)
-  watch    - Continuous checking on file changes
-  auth     - Manage LLM provider API keys
+Core commands (default path):
+  init     - Create bellwether.yaml configuration
+  check    - Schema validation and drift detection (free, deterministic)
+  baseline - Save and compare baseline snapshots
+
+Advanced commands (opt-in):
+  explore         - LLM-powered behavioral exploration and documentation
+  discover        - Quick capability discovery (no tests)
+  watch           - Continuous checking on file changes
+  registry        - Search the MCP Registry
+  golden          - Golden output regression testing
+  contract        - Contract validation (generate/validate/show)
+  auth            - Manage LLM provider API keys
   validate-config - Validate bellwether.yaml without running tests
 
 For more information on a specific command, use:
@@ -155,19 +150,17 @@ For more information on a specific command, use:
     }
 })
     .addHelpText('after', examples);
-// Add command groups for better organization
-program.addHelpText('beforeAll', '\nCore Commands:');
-// Core commands - check and explore
+program.addCommand(initCommand.description('Create a new bellwether.yaml configuration file'));
 program.addCommand(checkCommand.description('Check MCP server schema and detect drift (free, fast, deterministic)'));
+program.addCommand(baselineCommand.description('Manage baselines for drift detection (save, compare, show, diff)'));
+// Advanced commands
 program.addCommand(exploreCommand.description('Explore MCP server behavior with LLM-powered testing'));
 program.addCommand(watchCommand.description('Watch for MCP server changes and auto-check'));
 program.addCommand(discoverCommand.description('Discover MCP server capabilities (tools, prompts, resources)'));
-program.addCommand(initCommand.description('Create a new bellwether.yaml configuration file'));
-program.addCommand(authCommand.description('Manage LLM provider API keys (keychain storage)'));
-program.addCommand(baselineCommand.description('Manage baselines for drift detection (save, compare, show, diff)'));
 program.addCommand(goldenCommand.description('Manage golden outputs for tool validation (save, compare, list, delete)'));
 program.addCommand(registryCommand.description('Search the MCP Registry for servers'));
 program.addCommand(contractCommand.description('Validate MCP servers against contract definitions (validate, generate, show)'));
+program.addCommand(authCommand.description('Manage LLM provider API keys (keychain storage)'));
 program.addCommand(validateConfigCommand.description('Validate bellwether.yaml configuration (no tests)'));
 // Custom help formatting
 program.configureHelp({

package/dist/constants/core.d.ts

@@ -7,8 +7,8 @@ export declare const TIMEOUTS: {
     readonly WATCH_INTERVAL: 5000;
     /** Server startup delay (500ms) */
     readonly SERVER_STARTUP: 500;
-    /** Minimum server startup wait (5 seconds) */
-    readonly MIN_SERVER_STARTUP_WAIT: 5000;
+    /** Minimum server startup wait (500ms) */
+    readonly MIN_SERVER_STARTUP_WAIT: 500;
     /** Server ready poll interval (100ms) */
     readonly SERVER_READY_POLL: 100;
     /** Process shutdown SIGKILL timeout (5 seconds) */

package/dist/constants/core.js

@@ -7,8 +7,8 @@ export const TIMEOUTS = {
     WATCH_INTERVAL: 5000,
     /** Server startup delay (500ms) */
     SERVER_STARTUP: 500,
-    /** Minimum server startup wait (5 seconds) */
-    MIN_SERVER_STARTUP_WAIT: 5000,
+    /** Minimum server startup wait (500ms) */
+    MIN_SERVER_STARTUP_WAIT: 500,
     /** Server ready poll interval (100ms) */
     SERVER_READY_POLL: 100,
     /** Process shutdown SIGKILL timeout (5 seconds) */

package/dist/logging/logger.js

@@ -1,11 +1,14 @@
 import pino from 'pino';
+const IS_TEST_ENV = process.env.NODE_ENV === 'test' ||
+    process.env.VITEST === 'true' ||
+    process.env.VITEST_WORKER_ID !== undefined;
 /**
  * Default configuration.
  * Default level is 'warn' to keep CLI output clean.
  * Users can enable verbose output with --log-level info or --log-level debug.
  */
 const DEFAULT_CONFIG = {
-    level: 'warn',
+    level: IS_TEST_ENV ? 'silent' : 'warn',
     pretty: false,
     timestamp: true,
 };
@@ -50,7 +53,7 @@ export function createLogger(config = {}) {
  */
 export function getLogger(name) {
     if (!globalLogger) {
-        globalLogger = createLogger({ level: 'warn' });
+        globalLogger = createLogger({ level: DEFAULT_CONFIG.level });
     }
     if (name) {
         return globalLogger.child({ component: name });

package/dist/transport/env-filter.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Filter sensitive variables from process.env before spawning subprocesses.
+ * Explicitly provided additional environment variables are still allowed.
+ */
+export declare function filterSpawnEnv(baseEnv: NodeJS.ProcessEnv, additionalEnv?: Record<string, string>): Record<string, string>;
+//# sourceMappingURL=env-filter.d.ts.map

package/dist/transport/env-filter.js

@@ -0,0 +1,76 @@
+/**
+ * Environment variables to filter out when spawning MCP server processes.
+ * These may contain sensitive credentials that should not be exposed.
+ */
+const FILTERED_ENV_VARS = new Set([
+    // LLM API keys
+    'OPENAI_API_KEY',
+    'ANTHROPIC_API_KEY',
+    'GOOGLE_API_KEY',
+    'AZURE_OPENAI_API_KEY',
+    'COHERE_API_KEY',
+    'HUGGINGFACE_API_KEY',
+    'REPLICATE_API_TOKEN',
+    // Provider credentials
+    'AWS_SECRET_ACCESS_KEY',
+    'AWS_SESSION_TOKEN',
+    'AZURE_CLIENT_SECRET',
+    'GOOGLE_APPLICATION_CREDENTIALS',
+    // SCM/CI tokens
+    'GITHUB_TOKEN',
+    'GH_TOKEN',
+    'GITLAB_TOKEN',
+    'BITBUCKET_TOKEN',
+    'NPM_TOKEN',
+    'PYPI_TOKEN',
+    // Database credentials
+    'DATABASE_URL',
+    'DATABASE_PASSWORD',
+    'POSTGRES_PASSWORD',
+    'MYSQL_PASSWORD',
+    'REDIS_PASSWORD',
+    'MONGODB_URI',
+    // Application secrets
+    'COOKIE_SECRET',
+    'SESSION_SECRET',
+    'JWT_SECRET',
+    'ENCRYPTION_KEY',
+    'PRIVATE_KEY',
+]);
+/**
+ * Patterns for environment variable names that should be filtered.
+ * Matches common naming conventions for secrets.
+ */
+const FILTERED_ENV_PATTERNS = [
+    /_API_KEY$/i,
+    /_SECRET$/i,
+    /_TOKEN$/i,
+    /_PASSWORD$/i,
+    /_PRIVATE_KEY$/i,
+    /_CREDENTIALS$/i,
+    /^SECRET_/i,
+    /^PRIVATE_/i,
+];
+function isSensitiveEnvVar(name) {
+    if (FILTERED_ENV_VARS.has(name)) {
+        return true;
+    }
+    return FILTERED_ENV_PATTERNS.some((pattern) => pattern.test(name));
+}
+/**
+ * Filter sensitive variables from process.env before spawning subprocesses.
+ * Explicitly provided additional environment variables are still allowed.
+ */
+export function filterSpawnEnv(baseEnv, additionalEnv) {
+    const filtered = {};
+    for (const [key, value] of Object.entries(baseEnv)) {
+        if (value !== undefined && !isSensitiveEnvVar(key)) {
+            filtered[key] = value;
+        }
+    }
+    if (additionalEnv) {
+        Object.assign(filtered, additionalEnv);
+    }
+    return filtered;
+}
+//# sourceMappingURL=env-filter.js.map

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

@@ -86,15 +86,6 @@ export declare class MCPClient {
      */
     getTransportType(): TransportType;
     private log;
-    /**
-     * Check if an environment variable name looks like a secret.
-     */
-    private isSensitiveEnvVar;
-    /**
-     * Filter sensitive environment variables before passing to subprocess.
-     * Uses both explicit list and pattern matching to catch common secret naming conventions.
-     */
-    private filterEnv;
     /**
      * Connect to an MCP server by spawning it as a subprocess.
      */

package/dist/transport/mcp-client.js

@@ -6,59 +6,7 @@ import { getLogger, startTiming } from '../logging/logger.js';
 import { TIMEOUTS, MCP, TRANSPORT_ERRORS } from '../constants.js';
 import { VERSION } from '../version.js';
 import { getFeatureFlags, isKnownProtocolVersion, } from '../protocol/index.js';
-/**
- * Environment variables to filter out when spawning MCP server processes.
- * These may contain sensitive credentials that should not be exposed.
- */
-const FILTERED_ENV_VARS = new Set([
-    // LLM API keys
-    'OPENAI_API_KEY',
-    'ANTHROPIC_API_KEY',
-    'GOOGLE_API_KEY',
-    'AZURE_OPENAI_API_KEY',
-    'COHERE_API_KEY',
-    'HUGGINGFACE_API_KEY',
-    'REPLICATE_API_TOKEN',
-    // Provider credentials
-    'AWS_SECRET_ACCESS_KEY',
-    'AWS_SESSION_TOKEN',
-    'AZURE_CLIENT_SECRET',
-    'GOOGLE_APPLICATION_CREDENTIALS',
-    // SCM/CI tokens
-    'GITHUB_TOKEN',
-    'GH_TOKEN',
-    'GITLAB_TOKEN',
-    'BITBUCKET_TOKEN',
-    'NPM_TOKEN',
-    'PYPI_TOKEN',
-    // Database credentials
-    'DATABASE_URL',
-    'DATABASE_PASSWORD',
-    'POSTGRES_PASSWORD',
-    'MYSQL_PASSWORD',
-    'REDIS_PASSWORD',
-    'MONGODB_URI',
-    // Application secrets
-    'COOKIE_SECRET',
-    'SESSION_SECRET',
-    'JWT_SECRET',
-    'ENCRYPTION_KEY',
-    'PRIVATE_KEY',
-]);
-/**
- * Patterns for environment variable names that should be filtered.
- * Matches common naming conventions for secrets.
- */
-const FILTERED_ENV_PATTERNS = [
-    /_API_KEY$/i,
-    /_SECRET$/i,
-    /_TOKEN$/i,
-    /_PASSWORD$/i,
-    /_PRIVATE_KEY$/i,
-    /_CREDENTIALS$/i,
-    /^SECRET_/i,
-    /^PRIVATE_/i,
-];
+import { filterSpawnEnv } from './env-filter.js';
 const DEFAULT_TIMEOUT = TIMEOUTS.DEFAULT;
 const DEFAULT_STARTUP_DELAY = TIMEOUTS.SERVER_STARTUP;
 /**
@@ -247,35 +195,6 @@ export class MCPClient {
             this.logger.debug({ args }, 'MCP Debug');
         }
     }
-    /**
-     * Check if an environment variable name looks like a secret.
-     */
-    isSensitiveEnvVar(name) {
-        // Check explicit list
-        if (FILTERED_ENV_VARS.has(name)) {
-            return true;
-        }
-        // Check patterns
-        return FILTERED_ENV_PATTERNS.some((pattern) => pattern.test(name));
-    }
-    /**
-     * Filter sensitive environment variables before passing to subprocess.
-     * Uses both explicit list and pattern matching to catch common secret naming conventions.
-     */
-    filterEnv(baseEnv, additionalEnv) {
-        const filtered = {};
-        // Copy process.env, filtering out sensitive variables
-        for (const [key, value] of Object.entries(baseEnv)) {
-            if (value !== undefined && !this.isSensitiveEnvVar(key)) {
-                filtered[key] = value;
-            }
-        }
-        // Add additional env vars (these are explicitly provided, so allow them)
-        if (additionalEnv) {
-            Object.assign(filtered, additionalEnv);
-        }
-        return filtered;
-    }
     /**
      * Connect to an MCP server by spawning it as a subprocess.
      */
@@ -291,7 +210,7 @@ export class MCPClient {
             args,
         };
         // Filter out sensitive environment variables before spawning subprocess
-        const filteredEnv = this.filterEnv(process.env, env);
+        const filteredEnv = filterSpawnEnv(process.env, env);
         this.process = spawn(command, args, {
             stdio: ['pipe', 'pipe', 'pipe'],
             env: filteredEnv,
@@ -418,7 +337,7 @@ export class MCPClient {
      */
     async waitForStartup() {
         // Enforce minimum startup delay to allow server to fully start
-        // npx-based servers often need significant time to download and start
+        // while still honoring explicit higher startupDelay values from config/tests.
         const delay = Math.max(this.startupDelay, TIMEOUTS.MIN_SERVER_STARTUP_WAIT);
         this.logger.debug({ delay }, 'Waiting for server startup');
         await new Promise((resolve) => setTimeout(resolve, delay));

package/dist/version.js

@@ -29,8 +29,8 @@ function getPackageVersion() {
         return packageJson.version;
     }
     catch {
-        // Fallback version - should match package.json
-        return '2.1.0';
+        // Final fallback to avoid hardcoded release drift.
+        return process.env.BELLWETHER_VERSION || '0.0.0';
     }
 }
 /**

package/man/bellwether.1

@@ -1,4 +1,4 @@
-.TH "BELLWETHER" "1" "2026\-02\-11" "Bellwether 2.1.0" "User Commands"
+.TH "BELLWETHER" "1" "2026\-02\-14" "Bellwether 2.1.1" "User Commands"
 .SH NAME
 .PP
 bellwether \[em] MCP server testing and validation tool

package/man/bellwether.1.md

@@ -2,8 +2,8 @@
 title: BELLWETHER
 section: 1
 header: User Commands
-footer: Bellwether 2.1.0
-date: 2026-02-11
+footer: Bellwether 2.1.1
+date: 2026-02-14
 ---
 
 # NAME

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dotsetlabs/bellwether",
-  "version": "2.1.0",
+  "version": "2.1.1",
   "description": "The open-source MCP testing tool. Structural drift detection and behavioral documentation for Model Context Protocol servers.",
   "type": "module",
   "main": "dist/index.js",
@@ -23,7 +23,7 @@
   },
   "scripts": {
     "build": "tsc",
-    "postbuild": "chmod +x dist/cli/index.js",
+    "postbuild": "node ./scripts/postbuild.mjs",
     "dev": "tsc --watch",
     "test": "vitest run",
     "test:watch": "vitest",
@@ -32,6 +32,7 @@
     "lint:fix": "eslint src --ext .ts --fix",
     "format": "prettier --write \"src/**/*.ts\"",
     "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:dev": "npm --prefix website run start",