@dotsetlabs/bellwether 0.10.0

package/dist/cli/commands/registry.js

@@ -0,0 +1,146 @@
+/**
+ * Registry command - search and lookup MCP servers from the registry.
+ */
+import { Command } from 'commander';
+import chalk from 'chalk';
+import { RegistryClient, generateRunCommand, } from '../../registry/index.js';
+import { EXIT_CODES } from '../../constants.js';
+import { loadConfig, ConfigNotFoundError } from '../../config/loader.js';
+import * as output from '../output.js';
+/**
+ * Create a new registry command instance.
+ * Useful for testing where fresh command instances are needed.
+ */
+export function createRegistryCommand() {
+    return new Command('registry')
+        .alias('lookup')
+        .description('Search the MCP Registry for servers')
+        .argument('[query]', 'Search query (server name or keyword)')
+        .option('-c, --config <path>', 'Path to config file')
+        .option('-l, --limit <number>', 'Maximum results to show')
+        .option('--json', 'Output as JSON')
+        .action(async (query, options) => {
+        await handleRegistry(query, options);
+    });
+}
+export const registryCommand = createRegistryCommand();
+async function handleRegistry(query, options) {
+    let config;
+    try {
+        config = loadConfig(options.config);
+    }
+    catch (error) {
+        if (error instanceof ConfigNotFoundError) {
+            output.error(error.message);
+            process.exit(EXIT_CODES.ERROR);
+        }
+        throw error;
+    }
+    // Allow overriding registry URL for testing
+    const registryUrl = process.env.BELLWETHER_REGISTRY_URL;
+    const client = new RegistryClient(registryUrl ? { baseUrl: registryUrl } : undefined);
+    const limit = parseInt(options.limit ?? String(config.registry.limit), 10) || config.registry.limit;
+    const outputJson = options.json ? true : config.registry.json;
+    try {
+        let servers;
+        if (query) {
+            output.info(chalk.gray(`Searching for "${query}"...`));
+            servers = await client.searchServers(query, limit);
+        }
+        else {
+            output.info(chalk.gray('Fetching popular servers...'));
+            const response = await client.listServers({ limit });
+            servers = response.servers;
+        }
+        if (outputJson) {
+            output.json(servers);
+            return;
+        }
+        if (servers.length === 0) {
+            output.info(chalk.yellow('No servers found.'));
+            if (query) {
+                output.info(chalk.gray(`Try a different search term or browse all servers with: bellwether registry`));
+            }
+            return;
+        }
+        // Header
+        output.newline();
+        output.info(chalk.bold(`Found ${servers.length} server(s)`));
+        output.info('─'.repeat(60));
+        output.newline();
+        // Display each server
+        for (const entry of servers) {
+            displayServer(entry);
+            output.newline();
+        }
+        // Footer with usage hint
+        output.info('─'.repeat(60));
+        output.info(chalk.gray('To test a server, run:'));
+        if (servers.length > 0) {
+            const firstServer = servers[0].server;
+            const runCmd = generateRunCommand(firstServer);
+            if (runCmd) {
+                output.info(chalk.cyan(`  bellwether check ${runCmd}`));
+            }
+        }
+    }
+    catch (error) {
+        if (error instanceof Error) {
+            output.error(chalk.red(`Error: ${error.message}`));
+        }
+        else {
+            output.error(chalk.red('An unexpected error occurred'));
+        }
+        process.exit(EXIT_CODES.ERROR);
+    }
+}
+function displayServer(entry) {
+    const { server } = entry;
+    const meta = entry._meta?.['io.modelcontextprotocol.registry/official'];
+    // Name and version
+    let nameLine = chalk.bold.blue(server.name);
+    if (server.version) {
+        nameLine += chalk.gray(` v${server.version}`);
+    }
+    if (meta?.status === 'active') {
+        nameLine += chalk.green(' ✓');
+    }
+    output.info(nameLine);
+    // Description
+    if (server.description) {
+        output.info(chalk.white(`  ${server.description}`));
+    }
+    // Run command
+    const runCmd = generateRunCommand(server);
+    if (runCmd) {
+        output.info(chalk.gray('  Run: ') + chalk.cyan(runCmd));
+    }
+    // Transport and package info
+    if (server.packages && server.packages.length > 0) {
+        const pkg = server.packages[0];
+        const details = [];
+        if (pkg.registryType) {
+            details.push(pkg.registryType);
+        }
+        if (pkg.transport?.type) {
+            details.push(`transport: ${pkg.transport.type}`);
+        }
+        if (details.length > 0) {
+            output.info(chalk.gray(`  [${details.join(', ')}]`));
+        }
+        // Required arguments
+        const requiredArgs = pkg.packageArguments?.filter(a => a.isRequired) ?? [];
+        if (requiredArgs.length > 0) {
+            output.info(chalk.gray('  Required args:'));
+            for (const arg of requiredArgs) {
+                const desc = arg.description ? ` - ${arg.description}` : '';
+                output.info(chalk.gray(`    --${arg.name}${desc}`));
+            }
+        }
+    }
+    // Links
+    if (server.repository?.url) {
+        output.info(chalk.gray(`  Repository: ${server.repository.url}`));
+    }
+}
+//# sourceMappingURL=registry.js.map

package/dist/cli/commands/shared.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Shared utilities for check and explore commands.
+ *
+ * This module contains code that is common to both commands to avoid duplication
+ * and ensure consistent behavior.
+ */
+import type { ServerContext } from '../../interview/types.js';
+import type { BellwetherConfig } from '../../config/loader.js';
+import type { DiscoveryResult } from '../../discovery/types.js';
+import { MCPClient } from '../../transport/mcp-client.js';
+import { type MetricsCollector } from '../../metrics/collector.js';
+import { type ResponseCache } from '../../cache/response-cache.js';
+import { type LoadedScenarios } from '../../scenarios/index.js';
+/**
+ * Extract server context from command and arguments.
+ *
+ * Analyzes the server command to provide hints about the server type
+ * (filesystem, database, git, etc.) and extracts path arguments for
+ * allowed directories.
+ */
+export declare function extractServerContextFromArgs(command: string, args: string[]): ServerContext;
+/**
+ * Detect if running in a CI environment.
+ */
+export declare function isCI(): boolean;
+/**
+ * Common setup context for both check and explore commands.
+ */
+export interface CommandSetupContext {
+    mcpClient: MCPClient;
+    discovery: DiscoveryResult;
+    metricsCollector: MetricsCollector;
+    cache: ResponseCache;
+    fullServerCommand: string;
+    customScenarios?: LoadedScenarios;
+}
+/**
+ * Options for setting up a command.
+ */
+export interface SetupCommandOptions {
+    serverCommand: string;
+    args: string[];
+    config: BellwetherConfig;
+    verbose: boolean;
+    personaCount?: number;
+}
+/**
+ * Set up common infrastructure for check and explore commands.
+ *
+ * This handles the shared setup logic:
+ * - Initializing metrics collector
+ * - Initializing cache
+ * - Creating MCP client
+ * - Connecting to server
+ * - Discovering capabilities
+ * - Loading custom scenarios
+ */
+export declare function setupCommandInfrastructure(options: SetupCommandOptions): Promise<CommandSetupContext>;
+/**
+ * Ensure output directories exist.
+ */
+export declare function ensureOutputDirs(outputDir: string, docsDir: string): void;
+/**
+ * Display scenario results summary.
+ */
+export declare function displayScenarioResults(scenarioResults: Array<{
+    passed: boolean;
+    scenario: {
+        tool?: string;
+        prompt?: string;
+        description: string;
+    };
+    error?: string;
+}>): void;
+/**
+ * Handle common error messages and provide helpful diagnostics.
+ */
+export declare function handleCommandError(error: unknown, commandName: 'check' | 'explore'): never;
+//# sourceMappingURL=shared.d.ts.map

package/dist/cli/commands/shared.js

@@ -0,0 +1,196 @@
+/**
+ * Shared utilities for check and explore commands.
+ *
+ * This module contains code that is common to both commands to avoid duplication
+ * and ensure consistent behavior.
+ */
+import { mkdirSync } from 'fs';
+import { MCPClient } from '../../transport/mcp-client.js';
+import { discover } from '../../discovery/discovery.js';
+import { getMetricsCollector, resetMetricsCollector } from '../../metrics/collector.js';
+import { getGlobalCache, resetGlobalCache } from '../../cache/response-cache.js';
+import { loadScenariosFromFile, tryLoadDefaultScenarios, DEFAULT_SCENARIOS_FILE } from '../../scenarios/index.js';
+import { EXIT_CODES } from '../../constants.js';
+import * as output from '../output.js';
+/**
+ * Extract server context from command and arguments.
+ *
+ * Analyzes the server command to provide hints about the server type
+ * (filesystem, database, git, etc.) and extracts path arguments for
+ * allowed directories.
+ */
+export function extractServerContextFromArgs(command, args) {
+    const context = {
+        allowedDirectories: [],
+        constraints: [],
+        hints: [],
+    };
+    const fullCommand = `${command} ${args.join(' ')}`.toLowerCase();
+    const pathArgs = args.filter((arg) => arg.startsWith('/') && !arg.startsWith('--'));
+    if (fullCommand.includes('filesystem') || fullCommand.includes('file-system')) {
+        context.allowedDirectories = pathArgs;
+        if (context.allowedDirectories.length > 0) {
+            context.hints.push(`Filesystem server with allowed directories: ${context.allowedDirectories.join(', ')}`);
+        }
+        context.constraints.push('Operations limited to specified directories');
+    }
+    else if (fullCommand.includes('postgres') || fullCommand.includes('mysql') || fullCommand.includes('sqlite')) {
+        context.hints.push('Database server - SQL operations expected');
+        context.constraints.push('Database operations only');
+    }
+    else if (fullCommand.includes('git')) {
+        context.allowedDirectories = pathArgs;
+        context.hints.push('Git server - repository operations expected');
+    }
+    else {
+        context.allowedDirectories = pathArgs;
+    }
+    return context;
+}
+/**
+ * Detect if running in a CI environment.
+ */
+export function isCI() {
+    return !!(process.env.CI ||
+        process.env.CONTINUOUS_INTEGRATION ||
+        process.env.GITHUB_ACTIONS ||
+        process.env.GITLAB_CI ||
+        process.env.CIRCLECI ||
+        process.env.JENKINS_URL ||
+        process.env.TRAVIS ||
+        process.env.BUILDKITE);
+}
+/**
+ * Set up common infrastructure for check and explore commands.
+ *
+ * This handles the shared setup logic:
+ * - Initializing metrics collector
+ * - Initializing cache
+ * - Creating MCP client
+ * - Connecting to server
+ * - Discovering capabilities
+ * - Loading custom scenarios
+ */
+export async function setupCommandInfrastructure(options) {
+    const { serverCommand, args, config, verbose, personaCount = 0 } = options;
+    // Initialize metrics collector
+    resetMetricsCollector();
+    const metricsCollector = getMetricsCollector();
+    metricsCollector.startInterview();
+    // Initialize cache
+    resetGlobalCache();
+    const cacheEnabled = config.cache.enabled;
+    const cache = getGlobalCache({ enabled: cacheEnabled });
+    if (cacheEnabled && verbose) {
+        output.info('Response caching enabled');
+    }
+    // Initialize MCP client
+    const mcpClient = new MCPClient({
+        timeout: config.server.timeout,
+        debug: config.logging.level === 'debug',
+        transport: 'stdio',
+    });
+    // Connect to MCP server
+    output.info('Connecting to MCP server...');
+    await mcpClient.connect(serverCommand, args, config.server.env);
+    // Discovery phase
+    output.info('Discovering capabilities...');
+    const discovery = await discover(mcpClient, serverCommand, args);
+    const resourceCount = discovery.resources?.length ?? 0;
+    const discoveryParts = [`${discovery.tools.length} tools`, `${discovery.prompts.length} prompts`];
+    if (resourceCount > 0) {
+        discoveryParts.push(`${resourceCount} resources`);
+    }
+    output.info(`Found ${discoveryParts.join(', ')}\n`);
+    // Update metrics
+    metricsCollector.updateInterviewCounters({
+        toolsDiscovered: discovery.tools.length,
+        personasUsed: personaCount,
+    });
+    // Load custom scenarios
+    const outputDir = config.output.dir;
+    let customScenarios;
+    if (config.scenarios.path) {
+        customScenarios = loadScenariosFromFile(config.scenarios.path);
+        output.info(`Loaded ${customScenarios.toolScenarios.length} tool scenarios from ${config.scenarios.path}`);
+    }
+    else {
+        const defaultScenarios = tryLoadDefaultScenarios(outputDir);
+        if (defaultScenarios) {
+            customScenarios = defaultScenarios;
+            output.info(`Auto-loaded ${customScenarios.toolScenarios.length} scenarios from ${DEFAULT_SCENARIOS_FILE}`);
+        }
+    }
+    const fullServerCommand = `${serverCommand} ${args.join(' ')}`.trim();
+    return {
+        mcpClient,
+        discovery,
+        metricsCollector,
+        cache,
+        fullServerCommand,
+        customScenarios,
+    };
+}
+/**
+ * Ensure output directories exist.
+ */
+export function ensureOutputDirs(outputDir, docsDir) {
+    mkdirSync(outputDir, { recursive: true });
+    if (docsDir !== outputDir) {
+        mkdirSync(docsDir, { recursive: true });
+    }
+}
+/**
+ * Display scenario results summary.
+ */
+export function displayScenarioResults(scenarioResults) {
+    if (!scenarioResults || scenarioResults.length === 0) {
+        return;
+    }
+    const passed = scenarioResults.filter((r) => r.passed).length;
+    const failed = scenarioResults.length - passed;
+    const statusIcon = failed === 0 ? '\u2713' : '\u2717';
+    output.info(`\nCustom scenarios: ${passed}/${scenarioResults.length} passed ${statusIcon}`);
+    if (failed > 0) {
+        output.info('\nFailed scenarios:');
+        for (const scenarioResult of scenarioResults.filter((r) => !r.passed)) {
+            const scenario = scenarioResult.scenario;
+            const toolOrPrompt = scenario.tool || scenario.prompt || 'unknown';
+            output.info(`  - ${toolOrPrompt}: ${scenario.description}`);
+            if (scenarioResult.error) {
+                output.info(`    Error: ${scenarioResult.error}`);
+            }
+        }
+    }
+}
+/**
+ * Handle common error messages and provide helpful diagnostics.
+ */
+export function handleCommandError(error, commandName) {
+    const errorMessage = error instanceof Error ? error.message : String(error);
+    const title = commandName === 'check' ? 'Check Failed' : 'Exploration Failed';
+    output.error(`\n--- ${title} ---`);
+    output.error(`Error: ${errorMessage}`);
+    if (errorMessage.includes('ECONNREFUSED') || errorMessage.includes('Connection refused')) {
+        output.error('\nPossible causes:');
+        output.error('  - The MCP server is not running');
+        output.error('  - The server address/port is incorrect');
+    }
+    else if (errorMessage.includes('timeout') || errorMessage.includes('Timeout')) {
+        output.error('\nPossible causes:');
+        output.error('  - The MCP server is taking too long to respond');
+        output.error('  - Increase server.timeout in bellwether.yaml');
+    }
+    else if (errorMessage.includes('ENOENT') || errorMessage.includes('not found')) {
+        output.error('\nPossible causes:');
+        output.error('  - The server command was not found');
+        output.error('  - Check that the command is installed and in PATH');
+    }
+    else if (errorMessage.includes('API key') || errorMessage.includes('authentication')) {
+        output.error('\nPossible causes:');
+        output.error('  - Missing or invalid API key');
+        output.error('  - Run "bellwether auth" to configure API keys');
+    }
+    process.exit(EXIT_CODES.ERROR);
+}
+//# sourceMappingURL=shared.js.map

package/dist/cli/commands/teams.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Teams command for managing team selection in Bellwether Cloud.
+ *
+ * Allows users to list their teams and switch the active team for API requests.
+ */
+import { Command } from 'commander';
+export declare const teamsCommand: Command;
+//# sourceMappingURL=teams.d.ts.map

package/dist/cli/commands/teams.js

@@ -0,0 +1,169 @@
+/**
+ * Teams command for managing team selection in Bellwether Cloud.
+ *
+ * Allows users to list their teams and switch the active team for API requests.
+ */
+import { Command } from 'commander';
+import { getStoredSession, getSessionTeams, setActiveTeam, getTeamId, TEAM_ID_ENV_VAR, } from '../../cloud/auth.js';
+import { EXIT_CODES } from '../../constants.js';
+import * as output from '../output.js';
+export const teamsCommand = new Command('teams')
+    .description('Manage team selection for cloud operations')
+    .option('--json', 'Output as JSON')
+    .action(async (options) => {
+    // List teams by default
+    const session = getStoredSession();
+    if (!session) {
+        output.error('Not logged in.');
+        output.error('Run `bellwether login` first.');
+        process.exit(EXIT_CODES.ERROR);
+    }
+    const teams = getSessionTeams();
+    if (teams.length === 0) {
+        output.warn('No teams found in session.');
+        output.info('Try logging out and back in: `bellwether login --logout && bellwether login`');
+        return;
+    }
+    // Check for env var override
+    const envTeamId = process.env[TEAM_ID_ENV_VAR];
+    const effectiveTeamId = getTeamId();
+    if (options.json) {
+        output.info(JSON.stringify({
+            teams,
+            activeTeamId: session.activeTeamId,
+            effectiveTeamId,
+            envOverride: envTeamId || null,
+        }, null, 2));
+        return;
+    }
+    output.info('Your Teams');
+    output.info('-----------');
+    for (const team of teams) {
+        const isActive = team.id === session.activeTeamId;
+        const isEffective = team.id === effectiveTeamId;
+        const markers = [];
+        if (isActive)
+            markers.push('active');
+        if (envTeamId && isEffective)
+            markers.push('env override');
+        const suffix = markers.length > 0 ? ` (${markers.join(', ')})` : '';
+        const roleStr = `[${team.role}]`;
+        output.info(`  ${isEffective ? '>' : ' '} ${team.name} ${roleStr} - ${team.plan}${suffix}`);
+        output.info(`      ID: ${team.id}`);
+    }
+    if (envTeamId) {
+        output.info(`\nNote: ${TEAM_ID_ENV_VAR} is set, overriding session team.`);
+    }
+    if (teams.length > 1) {
+        output.info('\nUse `bellwether teams switch <team-id>` to change active team.');
+    }
+});
+// Subcommand: switch
+teamsCommand
+    .command('switch [team-id]')
+    .description('Switch to a different team')
+    .action(async (teamIdArg) => {
+    const session = getStoredSession();
+    if (!session) {
+        output.error('Not logged in.');
+        output.error('Run `bellwether login` first.');
+        process.exit(EXIT_CODES.ERROR);
+    }
+    const teams = getSessionTeams();
+    if (teams.length === 0) {
+        output.warn('No teams found in session.');
+        output.info('Try logging out and back in: `bellwether login --logout && bellwether login`');
+        return;
+    }
+    if (teams.length === 1) {
+        output.info(`You only have access to one team: ${teams[0].name}`);
+        return;
+    }
+    const targetTeamId = teamIdArg;
+    // If no team ID provided, show interactive selection
+    if (!targetTeamId) {
+        output.info('Select a team:\n');
+        for (let i = 0; i < teams.length; i++) {
+            const team = teams[i];
+            const isActive = team.id === session.activeTeamId;
+            const marker = isActive ? ' (current)' : '';
+            output.info(`  ${i + 1}. ${team.name} [${team.role}]${marker}`);
+            output.info(`     ID: ${team.id}`);
+        }
+        output.info('\nRun `bellwether teams switch <team-id>` with a team ID from above.');
+        return;
+    }
+    // Find the target team
+    const targetTeam = teams.find(t => t.id === targetTeamId || t.name.toLowerCase() === targetTeamId.toLowerCase());
+    if (!targetTeam) {
+        output.error(`Team not found: ${targetTeamId}`);
+        output.error('\nAvailable teams:');
+        for (const team of teams) {
+            output.error(`  - ${team.name} (${team.id})`);
+        }
+        process.exit(EXIT_CODES.ERROR);
+    }
+    // Check if already active
+    if (targetTeam.id === session.activeTeamId) {
+        output.info(`Already using team: ${targetTeam.name}`);
+        return;
+    }
+    // Switch team
+    const success = setActiveTeam(targetTeam.id);
+    if (success) {
+        output.info(`Switched to team: ${targetTeam.name}`);
+        output.info(`\nAll cloud commands will now use this team context.`);
+        // Warn about env var override
+        const envTeamId = process.env[TEAM_ID_ENV_VAR];
+        if (envTeamId && envTeamId !== targetTeam.id) {
+            output.warn(`\nNote: ${TEAM_ID_ENV_VAR} is set and will override this selection.`);
+            output.warn(`Unset it with: unset ${TEAM_ID_ENV_VAR}`);
+        }
+    }
+    else {
+        output.error('Failed to switch team. Please try logging in again.');
+        process.exit(EXIT_CODES.ERROR);
+    }
+});
+// Subcommand: current
+teamsCommand
+    .command('current')
+    .description('Show the current active team')
+    .option('--json', 'Output as JSON')
+    .action(async (options) => {
+    const session = getStoredSession();
+    if (!session) {
+        output.error('Not logged in.');
+        process.exit(EXIT_CODES.ERROR);
+    }
+    const effectiveTeamId = getTeamId();
+    const envTeamId = process.env[TEAM_ID_ENV_VAR];
+    const teams = getSessionTeams();
+    const activeTeam = teams.find(t => t.id === effectiveTeamId);
+    if (options.json) {
+        output.info(JSON.stringify({
+            team: activeTeam || null,
+            source: envTeamId ? 'environment' : 'session',
+            envVar: envTeamId || null,
+        }, null, 2));
+        return;
+    }
+    if (!activeTeam) {
+        output.warn('No active team.');
+        if (teams.length > 0) {
+            output.info('Run `bellwether teams switch` to select a team.');
+        }
+        else {
+            output.info('Try logging out and back in: `bellwether login --logout && bellwether login`');
+        }
+        return;
+    }
+    output.info(`Current team: ${activeTeam.name}`);
+    output.info(`  ID:   ${activeTeam.id}`);
+    output.info(`  Role: ${activeTeam.role}`);
+    output.info(`  Plan: ${activeTeam.plan}`);
+    if (envTeamId) {
+        output.info(`\nSource: ${TEAM_ID_ENV_VAR} environment variable`);
+    }
+});
+//# sourceMappingURL=teams.js.map

package/dist/cli/commands/test.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Test command - the simplified, config-driven MCP server testing command.
+ *
+ * All settings are read from bellwether.yaml (created by `bellwether init`).
+ * The only optional argument is the server command, which can also be in config.
+ */
+import { Command } from 'commander';
+export declare const testCommand: Command;
+//# sourceMappingURL=test.d.ts.map