@syrin/cli 1.3.0

package/dist/cli/index.js

@@ -0,0 +1,342 @@
+/**
+ * CLI entry point for Syrin.
+ * Sets up command parsing and routes to command handlers.
+ */
+import { Command } from 'commander';
+import { executeInit } from '../cli/commands/init.js';
+import { executeDoctor } from '../cli/commands/doctor.js';
+import { executeTest } from '../cli/commands/test.js';
+import { executeList } from '../cli/commands/list.js';
+import { executeAnalyse } from '../cli/commands/analyse.js';
+import { executeDev } from '../cli/commands/dev.js';
+import { executeUpdate } from '../cli/commands/update.js';
+import { executeRollback } from '../cli/commands/rollback.js';
+import { logger, log } from '../utils/logger.js';
+import { Messages, ListTypes } from '../constants/index.js';
+import { getCurrentVersion } from '../utils/version-checker.js';
+/**
+ * Report analyse command error with consolidated logging.
+ * Logs full error to internal logger and concise message to user.
+ */
+function reportAnalyseError(error) {
+    logger.error('Analyse command failed', error);
+    log.error(`Analyse command failed: ${error.message}`);
+}
+const program = new Command();
+/**
+ * Initialize the CLI program.
+ */
+export function setupCLI() {
+    // Get current version
+    const currentVersion = getCurrentVersion();
+    program
+        .name('syrin')
+        .description('Syrin - Runtime intelligence system for MCP servers')
+        .version(currentVersion, '-v, --version', 'Display version number');
+    // init command
+    program
+        .command('init')
+        .description('Initialize a new Syrin project')
+        .option('-y, --yes', 'Skip interactive prompts and use default values')
+        .option('--project-root <path>', 'Project root directory (defaults to current directory)')
+        .action(async (options) => {
+        try {
+            await executeInit({
+                yes: options.yes || false,
+                projectRoot: options.projectRoot,
+            });
+        }
+        catch (error) {
+            // Handle ALREADY_INITIALIZED case first with early return
+            if (error instanceof Error && error.message === 'ALREADY_INITIALIZED') {
+                // Already handled in executeInit, just exit
+                return;
+            }
+            // Handle other Error cases
+            if (error instanceof Error) {
+                logger.error('Init command failed', error);
+                log.blank();
+                log.error(`Error: ${error.message}`);
+                log.blank();
+                process.exit(1);
+            }
+            // Re-throw non-Error values
+            throw error;
+        }
+    });
+    // doctor command
+    program
+        .command('doctor')
+        .description('Validate Syrin project configuration and setup')
+        .option('--project-root <path>', 'Project root directory (defaults to current directory)')
+        .action(async (options) => {
+        try {
+            await executeDoctor(options.projectRoot);
+        }
+        catch (error) {
+            // Error handling is done in executeDoctor, this is a safety net
+            if (error instanceof Error) {
+                logger.error('Doctor command failed', error);
+            }
+        }
+    });
+    // test command
+    program
+        .command('test')
+        .description('Validate tool contracts (default) or test MCP connection (--connection)')
+        .argument('[url-or-script]', 'MCP URL (for http transport) or script (for stdio transport). Only used with --connection flag')
+        .option('--connection', 'Test MCP connection only (legacy behavior). Without this flag, validates tool contracts.')
+        .option('--tool <name>', 'Test specific tool only (for tool validation mode)')
+        .option('--path <path>', 'Test all tools in a specific path (relative to tools directory, e.g., "weather" or "server")')
+        .option('--strict', 'Treat warnings as errors')
+        .option('--json', 'Output results as JSON')
+        .option('--ci', 'CI mode: minimal output, exit code 1 on errors')
+        .option('--show-errors', 'Show sandbox process error output (stderr from MCP server)')
+        .option('--tools-dir <path>', 'Tools directory (overrides config, default: tools)')
+        .option('--transport <type>', 'Transport type (http or stdio). Only used with --connection flag')
+        .option('--url <url>', 'MCP URL to test (for http transport). Only used with --connection flag')
+        .option('--script <script>', 'Script to test (for stdio transport). Only used with --connection flag')
+        .option('--project-root <path>', 'Project root directory (defaults to current directory)')
+        .option('--env <key=value>', 'Environment variable to pass to MCP server (for stdio transport). Can be specified multiple times. Format: KEY=value or KEY (uses process.env[KEY])', (value, previous = []) => {
+        previous.push(value);
+        return previous;
+    })
+        .option('--auth-header <header>', 'Authentication header (for HTTP transport). Can be specified multiple times. Format: "Header: Value" or "Header=Value" or token (treated as Bearer token)', (value, previous = []) => {
+        previous.push(value);
+        return previous;
+    })
+        .action(async (urlOrScript, options) => {
+        try {
+            const { parseEnvOptions, parseAuthHeaderOptions } = await import('../cli/utils/option-parsers.js');
+            // If --connection flag, use legacy connection testing
+            if (options.connection) {
+                // Check for conflicting options that will be ignored
+                const ignoredOptions = [];
+                if (options.tool)
+                    ignoredOptions.push('--tool');
+                if (options.strict)
+                    ignoredOptions.push('--strict');
+                if (options.toolsDir)
+                    ignoredOptions.push('--tools-dir');
+                if (ignoredOptions.length > 0) {
+                    console.warn(`Warning: The following options are ignored when using --connection mode: ${ignoredOptions.join(', ')}`);
+                }
+                // Determine if positional argument is URL or script based on transport
+                let finalUrl = options.url;
+                let finalScript = options.script;
+                if (urlOrScript) {
+                    const transport = options.transport;
+                    if (transport === 'http' ||
+                        (!transport && urlOrScript.startsWith('http'))) {
+                        finalUrl = urlOrScript;
+                    }
+                    else {
+                        finalScript = urlOrScript;
+                    }
+                }
+                await executeTest({
+                    connection: true,
+                    transport: options.transport,
+                    url: finalUrl,
+                    script: finalScript,
+                    projectRoot: options.projectRoot,
+                    env: parseEnvOptions(options.env),
+                    authHeaders: parseAuthHeaderOptions(options.authHeader),
+                });
+            }
+            else {
+                // Tool validation mode - check for unused connection-related options
+                const unusedOptions = [];
+                if (urlOrScript)
+                    unusedOptions.push('positional URL/script argument');
+                if (options.transport && !options.url && !options.script)
+                    unusedOptions.push('--transport');
+                if (unusedOptions.length > 0) {
+                    console.warn(`Warning: The following connection-related options are unused in tool validation mode: ${unusedOptions.join(', ')}`);
+                }
+                await executeTest({
+                    tool: options.tool,
+                    path: options.path,
+                    strict: options.strict,
+                    json: options.json,
+                    ci: options.ci,
+                    showErrors: options.showErrors,
+                    toolsDir: options.toolsDir,
+                    projectRoot: options.projectRoot,
+                    env: parseEnvOptions(options.env),
+                    authHeaders: parseAuthHeaderOptions(options.authHeader),
+                });
+            }
+        }
+        catch (error) {
+            // Error handling is done in executeTest
+            if (error instanceof Error) {
+                logger.error('Test command failed', error);
+            }
+        }
+    });
+    // list command
+    program
+        .command('list')
+        .description('List tools, resources, or prompts from an MCP server')
+        .argument('[type]', `Type to list: ${ListTypes.TOOLS}, ${ListTypes.RESOURCES}, or ${ListTypes.PROMPTS} (default: ${ListTypes.TOOLS})`, ListTypes.TOOLS)
+        .option('--transport <type>', 'Transport type (http or stdio). If not provided, uses transport from config.yaml')
+        .option('--url <url>', 'MCP URL (for http transport). If not provided, uses URL from config.yaml')
+        .option('--script <script>', 'Script (for stdio transport). If not provided, uses script from config.yaml')
+        .option('--project-root <path>', 'Project root directory (defaults to current directory)')
+        .option('--env <key=value>', 'Environment variable to pass to MCP server (for stdio transport). Can be specified multiple times. Format: KEY=value or KEY (uses process.env[KEY])', (value, previous = []) => {
+        previous.push(value);
+        return previous;
+    })
+        .option('--auth-header <header>', 'Authentication header (for HTTP transport). Can be specified multiple times. Format: "Header: Value" or "Header=Value" or token (treated as Bearer token)', (value, previous = []) => {
+        previous.push(value);
+        return previous;
+    })
+        .action(async (type, options) => {
+        try {
+            const listType = type;
+            if (![ListTypes.TOOLS, ListTypes.RESOURCES, ListTypes.PROMPTS].includes(listType)) {
+                log.blank();
+                log.error(Messages.LIST_INVALID_TYPE(type));
+                log.plain(Messages.LIST_VALID_TYPES);
+                log.blank();
+                process.exit(1);
+            }
+            const { parseEnvOptions, parseAuthHeaderOptions } = await import('../cli/utils/option-parsers.js');
+            await executeList({
+                type: listType,
+                transport: options.transport,
+                url: options.url,
+                script: options.script,
+                projectRoot: options.projectRoot,
+                env: parseEnvOptions(options.env),
+                authHeaders: parseAuthHeaderOptions(options.authHeader),
+            });
+        }
+        catch (error) {
+            // Error handling is done in executeList
+            if (error instanceof Error) {
+                logger.error('List command failed', error);
+            }
+        }
+    });
+    // analyse command
+    program
+        .command('analyse')
+        .alias('analyze')
+        .description('Perform static analysis on MCP tool contracts')
+        .option('--ci', 'CI mode: minimal output, exit code 1 on errors')
+        .option('--json', 'Output results as JSON')
+        .option('--graph', 'Include dependency graph in output')
+        .option('--transport <type>', 'Transport type (http or stdio). If not provided, uses transport from config.yaml')
+        .option('--url <url>', 'MCP URL (for http transport). If not provided, uses URL from config.yaml')
+        .option('--script <script>', 'Script (for stdio transport). If not provided, uses script from config.yaml')
+        .option('--project-root <path>', 'Project root directory (defaults to current directory)')
+        .option('--env <key=value>', 'Environment variable to pass to MCP server (for stdio transport). Can be specified multiple times. Format: KEY=value or KEY (uses process.env[KEY])', (value, previous = []) => {
+        previous.push(value);
+        return previous;
+    })
+        .option('--auth-header <header>', 'Authentication header (for HTTP transport). Can be specified multiple times. Format: "Header: Value" or "Header=Value" or token (treated as Bearer token)', (value, previous = []) => {
+        previous.push(value);
+        return previous;
+    })
+        .action(async (options) => {
+        try {
+            const { parseEnvOptions, parseAuthHeaderOptions } = await import('../cli/utils/option-parsers.js');
+            await executeAnalyse({
+                ci: options.ci,
+                json: options.json,
+                graph: options.graph,
+                transport: options.transport,
+                url: options.url,
+                script: options.script,
+                projectRoot: options.projectRoot,
+                env: parseEnvOptions(options.env),
+                authHeaders: parseAuthHeaderOptions(options.authHeader),
+            });
+        }
+        catch (error) {
+            // Error handling is done in executeAnalyse, but ensure we log if something unexpected happens
+            if (error instanceof Error) {
+                reportAnalyseError(error);
+            }
+            // Don't exit here - executeAnalyse handles exit codes
+        }
+    });
+    // dev command
+    program
+        .command('dev')
+        .description('Enter interactive development mode for testing MCP tools')
+        .option('--exec', 'Execute tool calls (default: preview mode, shows what would be executed)')
+        .option('--llm <provider>', 'Override default LLM provider (e.g., openai, claude, ollama)')
+        .option('--project-root <path>', 'Project root directory (defaults to current directory)')
+        .option('--save-events', 'Save events to file for debugging')
+        .option('--event-file <path>', 'Directory path for event files (default: .syrin/events). Events are saved as {sessionId}.jsonl')
+        .option('--run-script', 'Run script to spawn server internally. If not provided, stdio uses script automatically, http connects to existing server')
+        .action(async (options) => {
+        try {
+            await executeDev({
+                exec: options.exec || false,
+                llm: options.llm,
+                projectRoot: options.projectRoot,
+                saveEvents: options.saveEvents || false,
+                eventFile: options.eventFile,
+                runScript: options.runScript || false,
+            });
+        }
+        catch (error) {
+            // Error handling is done in executeDev
+            if (error instanceof Error) {
+                logger.error('Dev command failed', error);
+            }
+        }
+    });
+    // update command
+    program
+        .command('update')
+        .description('Update Syrin to the latest version')
+        .action(async () => {
+        try {
+            await executeUpdate();
+        }
+        catch (error) {
+            // Error handling is done in executeUpdate
+            if (error instanceof Error) {
+                logger.error('Update command failed', error);
+            }
+        }
+    });
+    // rollback command
+    program
+        .command('rollback')
+        .description('Rollback Syrin to a previous version')
+        .argument('<version>', 'Version to rollback to (e.g., 1.0.0 or v1.0.0)')
+        .action(async (version) => {
+        try {
+            await executeRollback({ version });
+        }
+        catch (error) {
+            // Error handling is done in executeRollback
+            if (error instanceof Error) {
+                logger.error('Rollback command failed', error);
+            }
+        }
+    });
+    // Parse command line arguments
+    program.parse();
+}
+/**
+ * Run the CLI.
+ */
+export function run() {
+    try {
+        setupCLI();
+    }
+    catch (error) {
+        const err = error instanceof Error ? error : new Error(String(error));
+        logger.error('CLI setup failed', err);
+        log.error(Messages.CLI_START_FAILED);
+        process.exit(1);
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/cli/prompts/index.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Prompt utilities exports.
+ */
+export * from './init-prompt.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/cli/prompts/index.js

@@ -0,0 +1,5 @@
+/**
+ * Prompt utilities exports.
+ */
+export * from './init-prompt.js';
+//# sourceMappingURL=index.js.map

package/dist/cli/prompts/init-prompt.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Interactive prompts for the `syrin init` command.
+ */
+import type { InitOptions } from '../../config/types.js';
+/**
+ * Prompt user for project initialization details.
+ * @param defaults - Default values for non-interactive mode
+ * @returns User's answers
+ */
+export declare function promptInitOptions(defaults?: Partial<InitOptions>): Promise<InitOptions>;
+/**
+ * Create default init options for non-interactive mode.
+ * @param projectRoot - Root directory of the project
+ * @returns Default options
+ */
+export declare function getDefaultInitOptions(projectRoot: string): InitOptions;
+//# sourceMappingURL=init-prompt.d.ts.map

package/dist/cli/prompts/init-prompt.js

@@ -0,0 +1,263 @@
+/**
+ * Interactive prompts for the `syrin init` command.
+ */
+import inquirer from 'inquirer';
+import * as path from 'path';
+import { makeProjectName, makeAgentName, makeMCPURL, makeAPIKey, makeModelName, makeScriptCommand, } from '../../types/factories.js';
+import { Messages, TransportTypes, LLMProviders, LLMProviderDisplayNames, Defaults, EnvVars, } from '../../constants/index.js';
+/**
+ * Prompt user for project initialization details.
+ * @param defaults - Default values for non-interactive mode
+ * @returns User's answers
+ */
+export async function promptInitOptions(defaults) {
+    const currentDirName = path.basename(process.cwd());
+    const defaultProjectName = defaults?.projectName ||
+        currentDirName.replace(/[^a-z0-9-]/gi, '-').toLowerCase();
+    const answers = await inquirer.prompt([
+        {
+            type: 'input',
+            name: 'projectName',
+            message: 'Project name:',
+            default: defaultProjectName,
+            validate: (input) => {
+                if (!input.trim()) {
+                    return Messages.PROMPT_PROJECT_NAME_REQUIRED;
+                }
+                if (!/^[a-z0-9-]+$/i.test(input)) {
+                    return Messages.PROMPT_PROJECT_NAME_INVALID;
+                }
+                return true;
+            },
+        },
+        {
+            type: 'input',
+            name: 'agentName',
+            message: 'Agent name:',
+            default: defaults?.agentName
+                ? String(defaults.agentName)
+                : Defaults.AGENT_NAME,
+            validate: (input) => {
+                if (!input.trim()) {
+                    return Messages.PROMPT_AGENT_NAME_REQUIRED;
+                }
+                return true;
+            },
+        },
+        {
+            type: 'list',
+            name: 'transport',
+            message: 'Transport type:',
+            choices: [
+                {
+                    name: `${TransportTypes.STDIO} - Spawn MCP server as a subprocess`,
+                    value: TransportTypes.STDIO,
+                },
+                {
+                    name: `${TransportTypes.HTTP} - Connect to a running MCP server via HTTP`,
+                    value: TransportTypes.HTTP,
+                },
+            ],
+            default: defaults?.transport || Defaults.TRANSPORT,
+        },
+        {
+            type: 'input',
+            name: 'mcpUrl',
+            message: 'MCP server URL:',
+            default: defaults?.mcpUrl ? String(defaults.mcpUrl) : Defaults.MCP_URL,
+            when: (answers) => answers?.transport === TransportTypes.HTTP,
+            validate: (input, answers) => {
+                if (answers?.transport === TransportTypes.HTTP) {
+                    if (!input.trim()) {
+                        return Messages.PROMPT_MCP_URL_REQUIRED;
+                    }
+                    try {
+                        new URL(input);
+                        return true;
+                    }
+                    catch {
+                        return Messages.PROMPT_URL_INVALID;
+                    }
+                }
+                return true;
+            },
+        },
+        {
+            type: 'input',
+            name: 'script',
+            message: 'Script command to run MCP server:',
+            default: defaults?.script ? String(defaults.script) : 'python3 server.py',
+            validate: (input) => {
+                if (!input.trim()) {
+                    return Messages.PROMPT_SCRIPT_REQUIRED;
+                }
+                return true;
+            },
+        },
+        {
+            type: 'checkbox',
+            name: 'llmProviders',
+            message: 'Select LLM providers to configure:',
+            choices: [
+                {
+                    name: LLMProviderDisplayNames.OPENAI,
+                    value: LLMProviders.OPENAI,
+                    checked: true,
+                },
+                {
+                    name: LLMProviderDisplayNames.CLAUDE,
+                    value: LLMProviders.CLAUDE,
+                },
+                {
+                    name: LLMProviderDisplayNames.OLLAMA,
+                    value: LLMProviders.OLLAMA,
+                },
+            ],
+            default: defaults?.llmProviders
+                ? Object.keys(defaults.llmProviders)
+                : [LLMProviders.OPENAI],
+            validate: (input) => {
+                if (input.length === 0) {
+                    return Messages.PROMPT_LLM_PROVIDER_REQUIRED;
+                }
+                return true;
+            },
+        },
+        {
+            type: 'input',
+            name: 'openaiApiKey',
+            message: 'OpenAI API Key (env var name or direct value):',
+            default: EnvVars.OPENAI_API_KEY,
+            when: (answers) => answers.llmProviders?.includes(LLMProviders.OPENAI) ?? false,
+            validate: (input, answers) => {
+                if (answers?.llmProviders?.includes(LLMProviders.OPENAI) &&
+                    !input.trim()) {
+                    return 'OpenAI API key is required';
+                }
+                return true;
+            },
+        },
+        {
+            type: 'input',
+            name: 'openaiModel',
+            message: 'OpenAI Model Name (env var name or direct value):',
+            default: EnvVars.OPENAI_MODEL_NAME,
+            when: (answers) => answers.llmProviders?.includes(LLMProviders.OPENAI) ?? false,
+            validate: (input, answers) => {
+                if (answers?.llmProviders?.includes(LLMProviders.OPENAI) &&
+                    !input.trim()) {
+                    return Messages.PROMPT_OPENAI_MODEL_REQUIRED;
+                }
+                return true;
+            },
+        },
+        {
+            type: 'input',
+            name: 'claudeApiKey',
+            message: 'Claude API Key (env var name or direct value):',
+            default: EnvVars.CLAUDE_API_KEY,
+            when: (answers) => answers.llmProviders?.includes(LLMProviders.CLAUDE) ?? false,
+            validate: (input, answers) => {
+                if (answers?.llmProviders?.includes(LLMProviders.CLAUDE) &&
+                    !input.trim()) {
+                    return Messages.PROMPT_CLAUDE_API_KEY_REQUIRED;
+                }
+                return true;
+            },
+        },
+        {
+            type: 'input',
+            name: 'claudeModel',
+            message: 'Claude Model Name (env var name or direct value):',
+            default: EnvVars.CLAUDE_MODEL_NAME,
+            when: (answers) => answers.llmProviders?.includes(LLMProviders.CLAUDE) ?? false,
+            validate: (input, answers) => {
+                if (answers?.llmProviders?.includes(LLMProviders.CLAUDE) &&
+                    !input.trim()) {
+                    return Messages.PROMPT_CLAUDE_MODEL_REQUIRED;
+                }
+                return true;
+            },
+        },
+        {
+            type: 'input',
+            name: 'ollamaModelName',
+            message: 'Ollama Model Name (e.g., "llama2", "mistral", "codellama"):',
+            default: EnvVars.OLLAMA_MODEL_NAME,
+            when: (answers) => answers.llmProviders?.includes(LLMProviders.OLLAMA) ?? false,
+            validate: (input, answers) => {
+                if (answers?.llmProviders?.includes(LLMProviders.OLLAMA) &&
+                    !input.trim()) {
+                    return Messages.PROMPT_OLLAMA_MODEL_REQUIRED;
+                }
+                return true;
+            },
+        },
+        {
+            type: 'list',
+            name: 'defaultProvider',
+            message: 'Default LLM provider:',
+            choices: (answers) => answers.llmProviders || [],
+            default: (answers) => answers.llmProviders?.[0] || 'openai',
+        },
+    ]);
+    // Build LLM providers config
+    const llmProviders = {};
+    if (answers.llmProviders.includes('openai')) {
+        llmProviders.openai = {
+            apiKey: makeAPIKey(answers.openaiApiKey || ''),
+            modelName: makeModelName(answers.openaiModel || ''),
+            default: answers.defaultProvider === 'openai' || false,
+        };
+    }
+    if (answers.llmProviders.includes('claude')) {
+        llmProviders.claude = {
+            apiKey: makeAPIKey(answers.claudeApiKey || ''),
+            modelName: makeModelName(answers.claudeModel || ''),
+            default: answers.defaultProvider === 'claude' || false,
+        };
+    }
+    if (answers.llmProviders.includes('ollama')) {
+        llmProviders.ollama = {
+            modelName: answers.ollamaModelName
+                ? makeModelName(answers.ollamaModelName)
+                : undefined,
+            default: answers.defaultProvider === 'ollama' || false,
+        };
+    }
+    return {
+        projectName: makeProjectName(answers.projectName),
+        agentName: makeAgentName(answers.agentName),
+        transport: answers.transport,
+        mcpUrl: answers.mcpUrl ? makeMCPURL(answers.mcpUrl) : undefined,
+        script: makeScriptCommand(answers.script),
+        llmProviders,
+        nonInteractive: false,
+    };
+}
+/**
+ * Create default init options for non-interactive mode.
+ * @param projectRoot - Root directory of the project
+ * @returns Default options
+ */
+export function getDefaultInitOptions(projectRoot) {
+    const currentDirName = path.basename(projectRoot);
+    const defaultProjectNameStr = currentDirName
+        .replace(/[^a-z0-9-]/gi, '-')
+        .toLowerCase();
+    return {
+        projectName: makeProjectName(defaultProjectNameStr),
+        agentName: makeAgentName(Defaults.AGENT_NAME),
+        transport: Defaults.TRANSPORT,
+        script: makeScriptCommand(Defaults.SCRIPT_COMMAND),
+        llmProviders: {
+            openai: {
+                apiKey: makeAPIKey(EnvVars.OPENAI_API_KEY),
+                modelName: makeModelName(EnvVars.OPENAI_MODEL_NAME),
+                default: true,
+            },
+        },
+        nonInteractive: true,
+    };
+}
+//# sourceMappingURL=init-prompt.js.map

package/dist/cli/utils/command-error-handler.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Command error handling utilities.
+ * Provides consistent error handling patterns for CLI commands.
+ */
+/**
+ * Handle and display command errors with consistent formatting.
+ * This ensures all commands have uniform error handling.
+ *
+ * @param error - The error to handle
+ * @param defaultMessage - Default error message if error is not an Error instance
+ * @returns Never returns (always exits process)
+ */
+export declare function handleCommandError(error: unknown, defaultMessage?: string): never;
+//# sourceMappingURL=command-error-handler.d.ts.map