@syrin/cli 1.3.0

package/dist/cli/utils/command-error-handler.js

@@ -0,0 +1,35 @@
+/**
+ * Command error handling utilities.
+ * Provides consistent error handling patterns for CLI commands.
+ */
+import { logger, log } from '../../utils/logger.js';
+import { ConfigurationError, normalizeError, getErrorMessage, } from '../../utils/errors.js';
+import { Messages } from '../../constants/index.js';
+/**
+ * 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 function handleCommandError(error, defaultMessage = Messages.ERROR_UNEXPECTED) {
+    if (error instanceof ConfigurationError) {
+        // For user-facing errors, don't show verbose structured logs
+        // The structured logger will only output in debug mode (set via setLevel)
+        // For now, we skip structured logging for user-facing errors to keep output clean
+        log.blank();
+        log.error(error.message);
+        log.blank();
+        process.exit(1);
+    }
+    const err = normalizeError(error);
+    // Only log to structured logger (won't output unless debug mode is enabled)
+    logger.error('Command failed', err);
+    const message = getErrorMessage(error) || defaultMessage;
+    log.blank();
+    log.error(message);
+    log.blank();
+    process.exit(1);
+}
+//# sourceMappingURL=command-error-handler.js.map

package/dist/cli/utils/common-types.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Common types and interfaces shared across CLI commands.
+ * This centralizes common option interfaces to avoid duplication.
+ */
+import type { TransportType } from '../../config/types.js';
+/**
+ * Common transport-related options used by multiple commands.
+ * Commands that need transport configuration should extend this interface.
+ */
+export interface TransportCommandOptions {
+    /** Transport type override */
+    transport?: TransportType;
+    /** MCP server URL (for HTTP transport) */
+    url?: string;
+    /** Command/script to run (for stdio transport) */
+    script?: string;
+    /** Project root directory */
+    projectRoot?: string;
+    /** Environment variables to pass to MCP server (for stdio transport) */
+    env?: Record<string, string>;
+    /** Authentication headers (for HTTP transport) */
+    authHeaders?: Record<string, string>;
+}
+//# sourceMappingURL=common-types.d.ts.map

package/dist/cli/utils/common-types.js

@@ -0,0 +1,6 @@
+/**
+ * Common types and interfaces shared across CLI commands.
+ * This centralizes common option interfaces to avoid duplication.
+ */
+export {};
+//# sourceMappingURL=common-types.js.map

package/dist/cli/utils/connection-handler.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Connection handling utilities.
+ * Provides shared logic for establishing MCP connections with consistent error handling.
+ */
+import type { TransportType } from '../../config/types.js';
+import type { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import type { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
+import type { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
+export interface ConnectionResult {
+    client: Client;
+    transport: StreamableHTTPClientTransport | StdioClientTransport;
+}
+export interface ConnectionOptions {
+    transport: TransportType;
+    url?: string;
+    script?: string;
+    urlSource?: 'config' | 'cli';
+    env?: Record<string, string>;
+    authHeaders?: Record<string, string>;
+}
+/**
+ * Establish an MCP connection with proper error handling.
+ * This centralizes connection logic and error handling for all commands.
+ *
+ * @param options - Connection options including transport type and connection details
+ * @returns Connected client and transport instances
+ * @throws ConfigurationError with helpful error messages for common connection failures
+ */
+export declare function establishConnection(options: ConnectionOptions): Promise<ConnectionResult>;
+/**
+ * Safely close a connection, handling any errors gracefully.
+ * This ensures connections are always cleaned up even if errors occur.
+ *
+ * @param transport - The transport to close (may be undefined)
+ */
+export declare function safeCloseConnection(transport: StreamableHTTPClientTransport | StdioClientTransport | undefined): Promise<void>;
+//# sourceMappingURL=connection-handler.d.ts.map

package/dist/cli/utils/connection-handler.js

@@ -0,0 +1,90 @@
+/**
+ * Connection handling utilities.
+ * Provides shared logic for establishing MCP connections with consistent error handling.
+ */
+import { getConnectedClient, getConnectedStdioClient, closeConnection, } from '../../runtime/mcp/index.js';
+import { ConfigurationError } from '../../utils/errors.js';
+import { Messages, TransportTypes } from '../../constants/index.js';
+/**
+ * Establish an MCP connection with proper error handling.
+ * This centralizes connection logic and error handling for all commands.
+ *
+ * @param options - Connection options including transport type and connection details
+ * @returns Connected client and transport instances
+ * @throws ConfigurationError with helpful error messages for common connection failures
+ */
+export async function establishConnection(options) {
+    const { transport, url, script, urlSource, env, authHeaders } = options;
+    try {
+        if (transport === TransportTypes.HTTP) {
+            if (!url) {
+                throw new ConfigurationError(Messages.TRANSPORT_URL_REQUIRED);
+            }
+            const connection = await getConnectedClient(url, authHeaders);
+            return {
+                client: connection.client,
+                transport: connection.transport,
+            };
+        }
+        else {
+            if (!script) {
+                throw new ConfigurationError(Messages.TRANSPORT_SCRIPT_REQUIRED);
+            }
+            const connection = await getConnectedStdioClient(script, env);
+            return {
+                client: connection.client,
+                transport: connection.transport,
+            };
+        }
+    }
+    catch (connectionError) {
+        // Provide helpful error messages for connection failures
+        const errorMessage = connectionError instanceof Error
+            ? connectionError.message
+            : String(connectionError);
+        if (transport === TransportTypes.HTTP) {
+            // Check for common HTTP connection errors
+            if (errorMessage.includes('fetch failed') ||
+                errorMessage.includes('ECONNREFUSED') ||
+                errorMessage.includes('NetworkError') ||
+                errorMessage.includes('ENOTFOUND')) {
+                const configSource = urlSource === 'config'
+                    ? Messages.LIST_SOURCE_CONFIG
+                    : Messages.LIST_SOURCE_CLI_URL;
+                throw new ConfigurationError(Messages.CONNECTION_FAILED(url || '', configSource, 'http'));
+            }
+            else if (errorMessage.includes('timeout')) {
+                throw new ConfigurationError(Messages.CONNECTION_TIMEOUT_HTTP(url || ''));
+            }
+        }
+        else {
+            // stdio transport errors
+            if (errorMessage.includes('spawn') || errorMessage.includes('ENOENT')) {
+                throw new ConfigurationError(Messages.CONNECTION_FAILED_STDIO(script || ''));
+            }
+            else if (errorMessage.includes('timeout')) {
+                throw new ConfigurationError(Messages.CONNECTION_TIMEOUT_STDIO);
+            }
+        }
+        // Re-throw if we don't have a specific handler
+        throw connectionError;
+    }
+}
+/**
+ * Safely close a connection, handling any errors gracefully.
+ * This ensures connections are always cleaned up even if errors occur.
+ *
+ * @param transport - The transport to close (may be undefined)
+ */
+export async function safeCloseConnection(transport) {
+    if (transport) {
+        try {
+            await closeConnection(transport);
+        }
+        catch {
+            // Log but don't throw - cleanup errors shouldn't fail the command
+            // The structured logger will capture this if needed
+        }
+    }
+}
+//# sourceMappingURL=connection-handler.js.map

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

@@ -0,0 +1,11 @@
+/**
+ * CLI utilities exports.
+ */
+export * from './command-error-handler.js';
+export * from './common-types.js';
+export * from './connection-handler.js';
+export * from './option-parsers.js';
+export * from './output-utils.js';
+export * from './transport-resolver.js';
+export * from './version-banner.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/cli/utils/index.js

@@ -0,0 +1,11 @@
+/**
+ * CLI utilities exports.
+ */
+export * from './command-error-handler.js';
+export * from './common-types.js';
+export * from './connection-handler.js';
+export * from './option-parsers.js';
+export * from './output-utils.js';
+export * from './transport-resolver.js';
+export * from './version-banner.js';
+//# sourceMappingURL=index.js.map

package/dist/cli/utils/option-parsers.d.ts

@@ -0,0 +1,41 @@
+/**
+ * CLI option parsing utilities.
+ * Provides functions to parse complex CLI options like env vars and headers.
+ */
+/**
+ * Parse environment variable option from CLI.
+ * Supports format: KEY=value or KEY (uses process.env[KEY])
+ *
+ * @param envOption - Environment variable string in format "KEY=value" or "KEY"
+ * @returns Parsed key-value pair
+ */
+export declare function parseEnvOption(envOption: string): {
+    key: string;
+    value: string;
+};
+/**
+ * Parse multiple environment variable options.
+ *
+ * @param envOptions - Array of environment variable strings
+ * @returns Record of key-value pairs
+ */
+export declare function parseEnvOptions(envOptions: string[] | undefined): Record<string, string>;
+/**
+ * Parse authentication header option from CLI.
+ * Supports format: "Header: Value" or "Header=Value"
+ *
+ * @param headerOption - Header string in format "Header: Value" or "Header=Value"
+ * @returns Parsed key-value pair
+ */
+export declare function parseAuthHeaderOption(headerOption: string): {
+    key: string;
+    value: string;
+};
+/**
+ * Parse multiple authentication header options.
+ *
+ * @param headerOptions - Array of header strings
+ * @returns Record of header key-value pairs
+ */
+export declare function parseAuthHeaderOptions(headerOptions: string[] | undefined): Record<string, string>;
+//# sourceMappingURL=option-parsers.d.ts.map

package/dist/cli/utils/option-parsers.js

@@ -0,0 +1,92 @@
+/**
+ * CLI option parsing utilities.
+ * Provides functions to parse complex CLI options like env vars and headers.
+ */
+/**
+ * Parse environment variable option from CLI.
+ * Supports format: KEY=value or KEY (uses process.env[KEY])
+ *
+ * @param envOption - Environment variable string in format "KEY=value" or "KEY"
+ * @returns Parsed key-value pair
+ */
+export function parseEnvOption(envOption) {
+    const equalIndex = envOption.indexOf('=');
+    if (equalIndex === -1) {
+        // No = sign, treat as env var name and get from process.env
+        const key = envOption.trim();
+        const value = process.env[key] || '';
+        return { key, value };
+    }
+    const key = envOption.slice(0, equalIndex).trim();
+    const value = envOption.slice(equalIndex + 1).trim();
+    return { key, value };
+}
+/**
+ * Parse multiple environment variable options.
+ *
+ * @param envOptions - Array of environment variable strings
+ * @returns Record of key-value pairs
+ */
+export function parseEnvOptions(envOptions) {
+    if (!envOptions || envOptions.length === 0) {
+        return {};
+    }
+    const env = {};
+    for (const option of envOptions) {
+        const { key, value } = parseEnvOption(option);
+        if (key) {
+            env[key] = value;
+        }
+    }
+    return env;
+}
+/**
+ * Parse authentication header option from CLI.
+ * Supports format: "Header: Value" or "Header=Value"
+ *
+ * @param headerOption - Header string in format "Header: Value" or "Header=Value"
+ * @returns Parsed key-value pair
+ */
+export function parseAuthHeaderOption(headerOption) {
+    // Try "Header: Value" format first
+    const colonIndex = headerOption.indexOf(':');
+    if (colonIndex !== -1) {
+        const key = headerOption.slice(0, colonIndex).trim();
+        const value = headerOption.slice(colonIndex + 1).trim();
+        return { key, value };
+    }
+    // Try "Header=Value" format
+    const equalIndex = headerOption.indexOf('=');
+    if (equalIndex !== -1) {
+        const key = headerOption.slice(0, equalIndex).trim();
+        const value = headerOption.slice(equalIndex + 1).trim();
+        return { key, value };
+    }
+    // If no separator and not empty, treat as Bearer token
+    const trimmed = headerOption.trim();
+    if (!trimmed) {
+        return { key: '', value: '' };
+    }
+    return { key: 'Authorization', value: `Bearer ${trimmed}` };
+}
+/**
+ * Parse multiple authentication header options.
+ *
+ * @param headerOptions - Array of header strings
+ * @returns Record of header key-value pairs
+ */
+export function parseAuthHeaderOptions(headerOptions) {
+    if (!headerOptions || headerOptions.length === 0) {
+        return {};
+    }
+    const headers = {};
+    for (const option of headerOptions) {
+        const { key, value } = parseAuthHeaderOption(option);
+        // Skip entries without both key and value
+        if (key && value && value.trim()) {
+            headers[key] = value;
+        }
+    }
+    return headers;
+}
+//# sourceMappingURL=option-parsers.js.map

package/dist/cli/utils/output-utils.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Output utility functions for CLI commands.
+ * Provides shared utilities for output handling and formatting.
+ */
+/**
+ * Flush stdout to ensure all output is written before process exit.
+ * This is useful for commands that exit immediately after output.
+ *
+ * @returns Promise that resolves when output is flushed
+ */
+export declare function flushOutput(): Promise<void>;
+//# sourceMappingURL=output-utils.d.ts.map

package/dist/cli/utils/output-utils.js

@@ -0,0 +1,21 @@
+/**
+ * Output utility functions for CLI commands.
+ * Provides shared utilities for output handling and formatting.
+ */
+/**
+ * Flush stdout to ensure all output is written before process exit.
+ * This is useful for commands that exit immediately after output.
+ *
+ * @returns Promise that resolves when output is flushed
+ */
+export async function flushOutput() {
+    return new Promise(resolve => {
+        if (process.stdout.writable) {
+            process.stdout.write('', () => resolve());
+        }
+        else {
+            resolve();
+        }
+    });
+}
+//# sourceMappingURL=output-utils.js.map

package/dist/cli/utils/transport-resolver.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Transport configuration resolution utilities.
+ * Provides functions to resolve transport, URL, and script options from config and command options.
+ */
+import type { TransportType, SyrinConfig } from '../../config/types.js';
+export interface TransportOptions {
+    transport?: TransportType;
+    url?: string;
+    script?: string;
+    projectRoot?: string;
+    env?: Record<string, string>;
+    authHeaders?: Record<string, string>;
+}
+export interface ResolvedTransportConfig {
+    transport: TransportType;
+    url?: string;
+    script?: string;
+    config: SyrinConfig;
+    urlSource?: 'config' | 'cli';
+    scriptSource?: 'config' | 'cli';
+    env?: Record<string, string>;
+    authHeaders?: Record<string, string>;
+}
+/**
+ * Resolve transport configuration from command options and config file.
+ * This centralizes the logic for determining transport type, URL, and script.
+ *
+ * @param options - Command options containing transport, url, script, and projectRoot
+ * @returns Resolved transport configuration
+ * @throws ConfigurationError if required parameters are missing
+ */
+export declare function resolveTransportConfig(options: TransportOptions): ResolvedTransportConfig;
+//# sourceMappingURL=transport-resolver.d.ts.map

package/dist/cli/utils/transport-resolver.js

@@ -0,0 +1,82 @@
+/**
+ * Transport configuration resolution utilities.
+ * Provides functions to resolve transport, URL, and script options from config and command options.
+ */
+import { loadConfig } from '../../config/loader.js';
+import { ConfigurationError } from '../../utils/errors.js';
+import { Messages, TransportTypes } from '../../constants/index.js';
+/**
+ * Resolve transport configuration from command options and config file.
+ * This centralizes the logic for determining transport type, URL, and script.
+ *
+ * @param options - Command options containing transport, url, script, and projectRoot
+ * @returns Resolved transport configuration
+ * @throws ConfigurationError if required parameters are missing
+ */
+export function resolveTransportConfig(options) {
+    const { transport, url, script, projectRoot } = options;
+    // Load config to get default values
+    const config = loadConfig(projectRoot);
+    // Determine transport type
+    // If --script is provided, force stdio transport
+    // If --url is provided, force http transport
+    // Otherwise use explicit transport option or config default
+    let transportType;
+    if (script) {
+        transportType = TransportTypes.STDIO;
+    }
+    else if (url) {
+        transportType = TransportTypes.HTTP;
+    }
+    else {
+        transportType = transport || config.transport;
+    }
+    let mcpUrl;
+    let mcpScript;
+    let urlSource;
+    let scriptSource;
+    if (transportType === TransportTypes.HTTP) {
+        // Use provided URL or fall back to config
+        if (url) {
+            mcpUrl = url;
+            urlSource = 'cli';
+        }
+        else {
+            mcpUrl = config.mcp_url;
+            if (mcpUrl) {
+                urlSource = 'config';
+            }
+        }
+    }
+    else {
+        // Use provided script or fall back to config.script
+        if (script) {
+            mcpScript = script;
+            scriptSource = 'cli';
+        }
+        else {
+            mcpScript = config.script ? String(config.script) : undefined;
+            if (mcpScript) {
+                scriptSource = 'config';
+            }
+        }
+    }
+    // Validate required parameters
+    if (transportType === TransportTypes.HTTP && !mcpUrl) {
+        throw new ConfigurationError(Messages.TRANSPORT_URL_REQUIRED);
+    }
+    if (transportType === TransportTypes.STDIO && !mcpScript) {
+        throw new ConfigurationError(Messages.TRANSPORT_SCRIPT_REQUIRED);
+    }
+    return {
+        transport: transportType,
+        url: mcpUrl,
+        script: mcpScript,
+        config,
+        urlSource,
+        scriptSource,
+        env: options.env,
+        authHeaders: options.authHeaders,
+    };
+}
+//# sourceMappingURL=transport-resolver.js.map

package/dist/cli/utils/version-banner.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Version banner utility for CLI commands.
+ * Displays version information at the start of commands.
+ */
+/**
+ * Display version banner for a command.
+ * Shows version with update information.
+ */
+export declare function showVersionBanner(): Promise<void>;
+//# sourceMappingURL=version-banner.d.ts.map

package/dist/cli/utils/version-banner.js

@@ -0,0 +1,26 @@
+/**
+ * Version banner utility for CLI commands.
+ * Displays version information at the start of commands.
+ */
+import { getVersionDisplayString } from '../../utils/version-display.js';
+import { log } from '../../utils/logger.js';
+/**
+ * Display version banner for a command.
+ * Shows version with update information.
+ */
+export async function showVersionBanner() {
+    try {
+        const versionString = await getVersionDisplayString();
+        log.label(`Syrin ${versionString}`);
+        log.blank();
+    }
+    catch {
+        // If version check fails, just show current version
+        // This should rarely happen, but we don't want to break commands
+        const { getCurrentVersion } = await import('../../utils/version-checker.js');
+        const currentVersion = getCurrentVersion();
+        log.label(`Syrin v${currentVersion}`);
+        log.blank();
+    }
+}
+//# sourceMappingURL=version-banner.js.map

package/dist/config/env-checker.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Environment variable checker.
+ * Validates that required environment variables are set.
+ */
+export interface EnvCheckResult {
+    /** Whether the environment variable is set */
+    isSet: boolean;
+    /** The value of the environment variable (if set) */
+    value?: string;
+    /** Whether .env file exists */
+    envFileExists: boolean;
+    /** Whether the key exists in .env file */
+    keyExistsInEnvFile?: boolean;
+    /** Error message explaining why the variable is not set */
+    errorMessage?: string;
+}
+/**
+ * Check if an environment variable is set.
+ * Checks both process.env and .env file, providing detailed error messages.
+ * @param varName - Name of the environment variable
+ * @param projectRoot - Root directory of the project
+ * @returns Check result with detailed error information
+ */
+export declare function checkEnvVar(varName: string, projectRoot?: string): EnvCheckResult;
+/**
+ * Check if a command exists and is executable.
+ * @param command - Command to check (e.g., "python3", "node")
+ * @returns true if command exists
+ */
+export declare function checkCommandExists(command: string): boolean;
+/**
+ * Extract command name from a script string.
+ * @param script - Script command (e.g., "python3 server.py")
+ * @returns Command name (e.g., "python3")
+ */
+export declare function extractCommandName(script: string): string;
+//# sourceMappingURL=env-checker.d.ts.map