@codemcp/workflows 5.3.0 → 6.0.2

package/packages/core/dist/interfaces/task-backend-client.interface.js

@@ -0,0 +1,8 @@
+/**
+ * Task Backend Client Interface
+ *
+ * Defines the contract for task backend operations (CLI commands, etc.).
+ * Enables clean abstraction of different task backends (beads, GitHub Issues, etc.).
+ */
+export {};
+//# sourceMappingURL=task-backend-client.interface.js.map

package/packages/core/dist/interfaces/task-backend-client.interface.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"task-backend-client.interface.js","sourceRoot":"","sources":["../../src/interfaces/task-backend-client.interface.ts"],"names":[],"mappings":"AAAA;;;;;GAKG"}

package/packages/core/dist/logger.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Logging utility for Vibe Feature MCP Server
+ *
+ * Provides structured logging with proper MCP compliance:
+ * - Uses stderr for all local logging (MCP requirement)
+ * - Supports MCP log message notifications to client
+ * - Provides structured logging with proper levels:
+ *   - debug: Tracing and detailed execution flow
+ *   - info: Success operations and important milestones
+ *   - warn: Expected errors and recoverable issues
+ *   - error: Caught but unexpected errors
+ */
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare enum LogLevel {
+    DEBUG = 0,
+    INFO = 1,
+    WARN = 2,
+    ERROR = 3,
+    SILENT = 4
+}
+export interface LogContext {
+    component?: string;
+    conversationId?: string;
+    phase?: string;
+    operation?: string;
+    [key: string]: unknown;
+}
+/**
+ * Set the MCP server instance for log notifications
+ */
+export declare function setMcpServerForLogging(server: McpServer): void;
+/**
+ * Set the logging level from MCP client request
+ */
+export declare function setMcpLoggingLevel(level: string): void;
+declare class Logger {
+    private component;
+    private explicitLogLevel?;
+    constructor(component: string, logLevel?: LogLevel);
+    private getCurrentLogLevel;
+    private getLogLevelFromEnv;
+    private shouldLog;
+    private formatMessage;
+    /**
+     * Send log message to MCP client if server is available and level is appropriate
+     */
+    private sendMcpLogMessage;
+    debug(message: string, context?: LogContext): void;
+    info(message: string, context?: LogContext): void;
+    /**
+     * Send enhanced MCP notifications with better formatting for important events
+     */
+    private sendEnhancedMcpNotification;
+    /**
+     * Capitalize phase name for display
+     */
+    private capitalizePhase;
+    warn(message: string, context?: LogContext): void;
+    error(message: string, error?: Error, context?: LogContext): void;
+    child(childComponent: string): Logger;
+}
+export declare function createLogger(component: string, logLevel?: LogLevel): Logger;
+export declare const logger: Logger;
+export {};

package/packages/core/dist/logger.js

@@ -0,0 +1,283 @@
+/**
+ * Logging utility for Vibe Feature MCP Server
+ *
+ * Provides structured logging with proper MCP compliance:
+ * - Uses stderr for all local logging (MCP requirement)
+ * - Supports MCP log message notifications to client
+ * - Provides structured logging with proper levels:
+ *   - debug: Tracing and detailed execution flow
+ *   - info: Success operations and important milestones
+ *   - warn: Expected errors and recoverable issues
+ *   - error: Caught but unexpected errors
+ */
+export var LogLevel;
+(function (LogLevel) {
+    LogLevel[LogLevel["DEBUG"] = 0] = "DEBUG";
+    LogLevel[LogLevel["INFO"] = 1] = "INFO";
+    LogLevel[LogLevel["WARN"] = 2] = "WARN";
+    LogLevel[LogLevel["ERROR"] = 3] = "ERROR";
+    LogLevel[LogLevel["SILENT"] = 4] = "SILENT";
+})(LogLevel || (LogLevel = {}));
+// Global MCP server reference for log notifications
+let mcpServerInstance = null;
+// Unified logging level - can be set by MCP client or environment
+let currentLoggingLevel = null;
+// Test mode detection function to check at runtime
+function isTestMode() {
+    // Check explicit environment variables
+    if (process.env.NODE_ENV === 'test' || process.env.VITEST === 'true') {
+        return true;
+    }
+    // Check if running in a temporary directory (common for tests)
+    const cwd = process.cwd();
+    if (cwd.includes('/tmp/') || cwd.includes('temp') || cwd.includes('test-')) {
+        return true;
+    }
+    // Check if LOG_LEVEL is explicitly set to ERROR
+    if (process.env.LOG_LEVEL === 'ERROR') {
+        return true;
+    }
+    return false;
+}
+/**
+ * Set the MCP server instance for log notifications
+ */
+export function setMcpServerForLogging(server) {
+    mcpServerInstance = server;
+}
+/**
+ * Set the logging level from MCP client request
+ */
+export function setMcpLoggingLevel(level) {
+    // Map MCP levels to our internal levels
+    const levelMap = {
+        debug: LogLevel.DEBUG,
+        info: LogLevel.INFO,
+        notice: LogLevel.INFO,
+        warning: LogLevel.WARN,
+        error: LogLevel.ERROR,
+        critical: LogLevel.ERROR,
+        alert: LogLevel.ERROR,
+        emergency: LogLevel.ERROR,
+    };
+    currentLoggingLevel = levelMap[level] ?? LogLevel.INFO;
+}
+class Logger {
+    component;
+    explicitLogLevel;
+    constructor(component, logLevel) {
+        this.component = component;
+        this.explicitLogLevel = logLevel;
+    }
+    getCurrentLogLevel() {
+        // Check environment variable first (allows SILENT to override test mode)
+        const envLevel = this.getLogLevelFromEnv();
+        if (envLevel === LogLevel.SILENT) {
+            return LogLevel.SILENT;
+        }
+        // Force ERROR level in test environments (unless SILENT)
+        if (isTestMode()) {
+            return LogLevel.ERROR;
+        }
+        // Use MCP-set level if available (takes precedence)
+        if (currentLoggingLevel !== null) {
+            return currentLoggingLevel;
+        }
+        // Use environment variable level
+        if (envLevel !== null) {
+            return envLevel;
+        }
+        // If explicit log level was provided, use it
+        if (this.explicitLogLevel !== undefined) {
+            return this.explicitLogLevel;
+        }
+        // Default to INFO
+        return LogLevel.INFO;
+    }
+    getLogLevelFromEnv() {
+        const envLevel = process.env.LOG_LEVEL?.toUpperCase();
+        switch (envLevel) {
+            case 'DEBUG':
+                return LogLevel.DEBUG;
+            case 'INFO':
+                return LogLevel.INFO;
+            case 'WARN':
+                return LogLevel.WARN;
+            case 'ERROR':
+                return LogLevel.ERROR;
+            case 'SILENT':
+                return LogLevel.SILENT;
+            default:
+                return null;
+        }
+    }
+    shouldLog(level) {
+        return level >= this.getCurrentLogLevel();
+    }
+    formatMessage(level, message, context) {
+        const timestamp = new Date().toISOString();
+        const contextStr = context ? ` ${JSON.stringify(context)}` : '';
+        return `[${timestamp}] ${level.toUpperCase()} [${this.component}] ${message}${contextStr}`;
+    }
+    /**
+     * Send log message to MCP client if server is available and level is appropriate
+     */
+    async sendMcpLogMessage(level, message, context) {
+        if (mcpServerInstance) {
+            try {
+                // Safely serialize context to avoid JSON issues
+                let logData = message;
+                if (context) {
+                    try {
+                        const contextStr = JSON.stringify(context, null, 0);
+                        logData = `${message} ${contextStr}`;
+                    }
+                    catch (_error) {
+                        // If JSON serialization fails, just use the message
+                        logData = `${message} [context serialization failed]`;
+                    }
+                }
+                await mcpServerInstance.server.notification({
+                    method: 'notifications/message',
+                    params: {
+                        level,
+                        logger: this.component,
+                        data: logData,
+                    },
+                });
+            }
+            catch (error) {
+                // Fallback to stderr if MCP notification fails
+                // Don't use this.error to avoid infinite recursion
+                if (!isTestMode()) {
+                    process.stderr.write(`[MCP-LOG-ERROR] Failed to send log notification: ${error}\n`);
+                }
+            }
+        }
+    }
+    debug(message, context) {
+        if (this.shouldLog(LogLevel.DEBUG)) {
+            const formattedMessage = this.formatMessage('debug', message, context);
+            // Always log to stderr for MCP compliance
+            process.stderr.write(formattedMessage + '\n');
+            // Also send to MCP client if available (only for debug level)
+            this.sendMcpLogMessage('debug', message, context).catch(() => {
+                // Ignore MCP notification errors for debug messages
+            });
+        }
+    }
+    info(message, context) {
+        if (this.shouldLog(LogLevel.INFO)) {
+            const formattedMessage = this.formatMessage('info', message, context);
+            // Always log to stderr for MCP compliance
+            process.stderr.write(formattedMessage + '\n');
+            // Send enhanced notifications for important events
+            this.sendEnhancedMcpNotification('info', message, context).catch(() => {
+                // Ignore MCP notification errors for info messages
+            });
+        }
+    }
+    /**
+     * Send enhanced MCP notifications with better formatting for important events
+     */
+    async sendEnhancedMcpNotification(level, message, context) {
+        if (mcpServerInstance) {
+            try {
+                let enhancedMessage = message;
+                let notificationLevel = level;
+                // Enhance phase transition messages
+                if (context &&
+                    (context.from || context.to) &&
+                    message.includes('transition')) {
+                    const from = context.from
+                        ? this.capitalizePhase(context.from)
+                        : '';
+                    const to = context.to
+                        ? this.capitalizePhase(context.to)
+                        : '';
+                    if (from && to) {
+                        enhancedMessage = `Phase Transition: ${from} → ${to}`;
+                        notificationLevel = 'info';
+                    }
+                }
+                // Enhance initialization messages
+                if (message.includes('initialized successfully')) {
+                    enhancedMessage = '🚀 Vibe Feature MCP Server Ready';
+                    notificationLevel = 'info';
+                }
+                // Safely serialize context to avoid JSON issues
+                let logData = enhancedMessage;
+                if (context) {
+                    try {
+                        const contextStr = JSON.stringify(context, null, 0);
+                        logData = `${enhancedMessage} ${contextStr}`;
+                    }
+                    catch (_error) {
+                        // If JSON serialization fails, just use the message
+                        logData = `${enhancedMessage} [context serialization failed]`;
+                    }
+                }
+                // Use the underlying server's notification method
+                await mcpServerInstance.server.notification({
+                    method: 'notifications/message',
+                    params: {
+                        level: notificationLevel,
+                        logger: this.component,
+                        data: logData,
+                    },
+                });
+            }
+            catch (error) {
+                // Fallback to stderr if MCP notification fails
+                // Don't use this.error to avoid infinite recursion
+                if (!isTestMode()) {
+                    process.stderr.write(`[MCP-LOG-ERROR] Failed to send log notification: ${error}\n`);
+                }
+            }
+        }
+    }
+    /**
+     * Capitalize phase name for display
+     */
+    capitalizePhase(phase) {
+        return phase
+            .split('_')
+            .map(word => word.charAt(0).toUpperCase() + word.slice(1))
+            .join(' ');
+    }
+    warn(message, context) {
+        if (this.shouldLog(LogLevel.WARN)) {
+            const formattedMessage = this.formatMessage('warn', message, context);
+            // Always log to stderr for MCP compliance
+            process.stderr.write(formattedMessage + '\n');
+            // Also send to MCP client if available
+            this.sendEnhancedMcpNotification('warning', message, context).catch(() => {
+                // Ignore MCP notification errors for warn messages
+            });
+        }
+    }
+    error(message, error, context) {
+        if (this.shouldLog(LogLevel.ERROR)) {
+            const errorContext = error
+                ? { ...context, error: error.message, stack: error.stack }
+                : context;
+            const formattedMessage = this.formatMessage('error', message, errorContext);
+            // Always log to stderr for MCP compliance
+            process.stderr.write(formattedMessage + '\n');
+            // Also send to MCP client if available
+            this.sendEnhancedMcpNotification('error', message, errorContext).catch(() => {
+                // Ignore MCP notification errors for error messages
+            });
+        }
+    }
+    child(childComponent) {
+        return new Logger(`${this.component}:${childComponent}`, this.explicitLogLevel);
+    }
+}
+// Factory function to create loggers
+export function createLogger(component, logLevel) {
+    return new Logger(component, logLevel);
+}
+// Default logger for the main application
+export const logger = createLogger('VibeFeatureMCP');
+//# sourceMappingURL=logger.js.map

package/packages/core/dist/logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.js","sourceRoot":"","sources":["../src/logger.ts"],"names":[],"mappings":"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"}

package/packages/core/dist/path-validation-utils.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Path Validation Utilities
+ *
+ * Provides utilities for validating file paths, resolving relative paths,
+ * and ensuring security constraints for the file linking functionality.
+ */
+export interface PathValidationResult {
+    isValid: boolean;
+    resolvedPath?: string;
+    error?: string;
+}
+export declare class PathValidationUtils {
+    /**
+     * Validate if a string is a known template name
+     */
+    static isTemplateName(value: string, availableTemplates: string[]): boolean;
+    /**
+     * Validate and resolve a file path
+     */
+    static validateFilePath(filePath: string, projectPath: string): Promise<PathValidationResult>;
+    /**
+     * Validate and resolve a file or directory path
+     */
+    static validateFileOrDirectoryPath(filePath: string, projectPath: string): Promise<PathValidationResult>;
+    /**
+     * Resolve a file path to absolute, handling various formats
+     */
+    static resolvePath(filePath: string, projectPath: string): string;
+    /**
+     * Check if a resolved path is within safe boundaries
+     * Prevents directory traversal attacks
+     */
+    static isPathSafe(resolvedPath: string, projectPath: string): boolean;
+    /**
+     * Validate parameter as either template name or file path
+     */
+    static validateParameter(value: string, availableTemplates: string[], projectPath: string): Promise<{
+        isTemplate: boolean;
+        isFilePath: boolean;
+        resolvedPath?: string;
+        error?: string;
+    }>;
+    /**
+     * Get common file patterns for documentation
+     */
+    static getCommonDocumentationPatterns(): {
+        architecture: string[];
+        requirements: string[];
+        design: string[];
+    };
+}
+/**
+ * Cross-platform utility to extract the last component of a path.
+ * Handles both forward slashes (/) and backslashes (\) regardless of
+ * the platform the code is running on.
+ *
+ * Note: Node.js's `path.basename()` only handles the native path separator
+ * for the current platform. This function normalizes paths to handle both
+ * Unix and Windows paths on any platform.
+ *
+ * @param filePath - The file path to extract from
+ * @param fallback - Fallback value if path is empty (default: 'unknown')
+ * @returns The last component of the path, or the fallback value
+ *
+ * @example
+ * // Unix-style paths
+ * getPathBasename('/home/user/project') // 'project'
+ *
+ * // Windows-style paths (works on any platform)
+ * getPathBasename('c:\\work\\project') // 'project'
+ *
+ * // Mixed paths
+ * getPathBasename('c:/work/project') // 'project'
+ */
+export declare function getPathBasename(filePath: string, fallback?: string): string;

package/packages/core/dist/path-validation-utils.js

@@ -0,0 +1,238 @@
+/**
+ * Path Validation Utilities
+ *
+ * Provides utilities for validating file paths, resolving relative paths,
+ * and ensuring security constraints for the file linking functionality.
+ */
+import { access, stat } from 'node:fs/promises';
+import { resolve, isAbsolute, join, normalize, basename } from 'node:path';
+import { createLogger } from './logger.js';
+const logger = createLogger('PathValidationUtils');
+export class PathValidationUtils {
+    /**
+     * Validate if a string is a known template name
+     */
+    static isTemplateName(value, availableTemplates) {
+        return availableTemplates.includes(value);
+    }
+    /**
+     * Validate and resolve a file path
+     */
+    static async validateFilePath(filePath, projectPath) {
+        try {
+            // Resolve the path to absolute
+            const resolvedPath = this.resolvePath(filePath, projectPath);
+            // Security validation - prevent directory traversal
+            if (!this.isPathSafe(resolvedPath, projectPath)) {
+                return {
+                    isValid: false,
+                    error: 'Path is outside project boundaries for security reasons',
+                };
+            }
+            // Check if file exists and is readable
+            await access(resolvedPath);
+            // Verify it's a file (not a directory)
+            const stats = await stat(resolvedPath);
+            if (!stats.isFile()) {
+                return {
+                    isValid: false,
+                    error: 'Path points to a directory, not a file',
+                };
+            }
+            logger.debug('File path validated successfully', {
+                originalPath: filePath,
+                resolvedPath,
+            });
+            return {
+                isValid: true,
+                resolvedPath,
+            };
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : 'Unknown error';
+            logger.debug('File path validation failed', {
+                filePath,
+                error: errorMessage,
+            });
+            return {
+                isValid: false,
+                error: `File not found or not accessible: ${errorMessage}`,
+            };
+        }
+    }
+    /**
+     * Validate and resolve a file or directory path
+     */
+    static async validateFileOrDirectoryPath(filePath, projectPath) {
+        try {
+            // Resolve the path to absolute
+            const resolvedPath = this.resolvePath(filePath, projectPath);
+            // Security validation - prevent directory traversal
+            if (!this.isPathSafe(resolvedPath, projectPath)) {
+                return {
+                    isValid: false,
+                    error: 'Path is outside project boundaries for security reasons',
+                };
+            }
+            // Check if file or directory exists and is readable
+            await access(resolvedPath);
+            // Verify it's either a file or directory
+            const stats = await stat(resolvedPath);
+            if (!stats.isFile() && !stats.isDirectory()) {
+                return {
+                    isValid: false,
+                    error: 'Path is neither a file nor a directory',
+                };
+            }
+            logger.debug('File or directory path validated successfully', {
+                originalPath: filePath,
+                resolvedPath,
+                isFile: stats.isFile(),
+                isDirectory: stats.isDirectory(),
+            });
+            return {
+                isValid: true,
+                resolvedPath,
+            };
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : 'Unknown error';
+            logger.debug('File or directory path validation failed', {
+                filePath,
+                error: errorMessage,
+            });
+            return {
+                isValid: false,
+                error: `File or directory not found or not accessible: ${errorMessage}`,
+            };
+        }
+    }
+    /**
+     * Resolve a file path to absolute, handling various formats
+     */
+    static resolvePath(filePath, projectPath) {
+        // If already absolute, return as-is
+        if (isAbsolute(filePath)) {
+            return normalize(filePath);
+        }
+        // Handle relative paths (./file, ../file, file)
+        return resolve(projectPath, filePath);
+    }
+    /**
+     * Check if a resolved path is within safe boundaries
+     * Prevents directory traversal attacks
+     */
+    static isPathSafe(resolvedPath, projectPath) {
+        const normalizedResolved = normalize(resolvedPath);
+        const normalizedProject = normalize(projectPath);
+        // Allow paths within the project directory
+        if (normalizedResolved.startsWith(normalizedProject)) {
+            return true;
+        }
+        // Allow paths in common documentation locations relative to project
+        const allowedPaths = [
+            normalize(join(projectPath, '..')), // Parent directory (for monorepos)
+            '/usr/share/doc', // System documentation
+            '/opt/docs', // Optional documentation
+        ];
+        return allowedPaths.some(allowedPath => normalizedResolved.startsWith(allowedPath));
+    }
+    /**
+     * Validate parameter as either template name or file path
+     */
+    static async validateParameter(value, availableTemplates, projectPath) {
+        // First check if it's a template name
+        if (this.isTemplateName(value, availableTemplates)) {
+            return {
+                isTemplate: true,
+                isFilePath: false,
+            };
+        }
+        // Then validate as file or directory path
+        const pathValidation = await this.validateFileOrDirectoryPath(value, projectPath);
+        if (pathValidation.isValid) {
+            return {
+                isTemplate: false,
+                isFilePath: true,
+                resolvedPath: pathValidation.resolvedPath,
+            };
+        }
+        // Neither template nor valid file/directory path
+        return {
+            isTemplate: false,
+            isFilePath: false,
+            error: `Invalid parameter: not a known template (${availableTemplates.join(', ')}) and not a valid file or directory path (${pathValidation.error})`,
+        };
+    }
+    /**
+     * Get common file patterns for documentation
+     */
+    static getCommonDocumentationPatterns() {
+        return {
+            architecture: [
+                'ARCHITECTURE.md',
+                'ARCHITECTURE.txt',
+                'architecture.md',
+                'Architecture.md',
+                'docs/ARCHITECTURE.md',
+                'docs/architecture.md',
+                'README.md', // Can contain architecture info
+            ],
+            requirements: [
+                'REQUIREMENTS.md',
+                'REQUIREMENTS.txt',
+                'requirements.md',
+                'Requirements.md',
+                'docs/REQUIREMENTS.md',
+                'docs/requirements.md',
+                'README.md', // Often contains requirements
+            ],
+            design: [
+                'DESIGN.md',
+                'DESIGN.txt',
+                'design.md',
+                'Design.md',
+                'docs/DESIGN.md',
+                'docs/design.md',
+                'README.md', // Can contain design info
+            ],
+        };
+    }
+}
+/**
+ * Cross-platform utility to extract the last component of a path.
+ * Handles both forward slashes (/) and backslashes (\) regardless of
+ * the platform the code is running on.
+ *
+ * Note: Node.js's `path.basename()` only handles the native path separator
+ * for the current platform. This function normalizes paths to handle both
+ * Unix and Windows paths on any platform.
+ *
+ * @param filePath - The file path to extract from
+ * @param fallback - Fallback value if path is empty (default: 'unknown')
+ * @returns The last component of the path, or the fallback value
+ *
+ * @example
+ * // Unix-style paths
+ * getPathBasename('/home/user/project') // 'project'
+ *
+ * // Windows-style paths (works on any platform)
+ * getPathBasename('c:\\work\\project') // 'project'
+ *
+ * // Mixed paths
+ * getPathBasename('c:/work/project') // 'project'
+ */
+export function getPathBasename(filePath, fallback = 'unknown') {
+    if (!filePath) {
+        return fallback;
+    }
+    // Normalize backslashes to forward slashes for cross-platform support
+    // This ensures Windows paths are handled correctly on Unix and vice versa
+    const normalizedPath = filePath.replace(/\\/g, '/');
+    // Remove trailing slashes
+    const trimmedPath = normalizedPath.replace(/\/+$/, '');
+    // Use basename on the normalized path
+    const result = basename(trimmedPath);
+    return result || fallback;
+}
+//# sourceMappingURL=path-validation-utils.js.map