@codemcp/workflows-core 3.1.16

package/dist/path-validation-utils.js

@@ -0,0 +1,202 @@
+/**
+ * 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 } 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
+            ],
+        };
+    }
+}
+//# sourceMappingURL=path-validation-utils.js.map

package/dist/path-validation-utils.js.map

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

package/dist/plan-manager.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Plan Manager
+ *
+ * Handles the creation, updating, and maintenance of project development plan files.
+ * Manages markdown plan files that serve as long-term project memory.
+ * Supports custom state machine definitions for dynamic plan file generation.
+ */
+import type { YamlStateMachine } from './state-machine-types.js';
+export interface PlanFileInfo {
+    path: string;
+    exists: boolean;
+    content?: string;
+}
+export declare class PlanManager {
+    private stateMachine;
+    /**
+     * Set the state machine definition for dynamic plan generation
+     */
+    setStateMachine(stateMachine: YamlStateMachine): void;
+    /**
+     * Get plan file information
+     */
+    getPlanFileInfo(planFilePath: string): Promise<PlanFileInfo>;
+    /**
+     * Create initial plan file if it doesn't exist
+     */
+    ensurePlanFile(planFilePath: string, projectPath: string, gitBranch: string): Promise<void>;
+    /**
+     * Create initial plan file with template content
+     */
+    private createInitialPlanFile;
+    /**
+     * Generate initial plan file content based on state machine definition
+     */
+    private generateInitialPlanContent;
+    /**
+     * Update plan file with new content (this is typically done by the LLM)
+     */
+    updatePlanFile(planFilePath: string, content: string): Promise<void>;
+    /**
+     * Get plan file content for LLM context
+     */
+    getPlanFileContent(planFilePath: string): Promise<string>;
+    /**
+     * Generate phase-specific plan file guidance based on state machine
+     */
+    generatePlanFileGuidance(phase: string): string;
+    /**
+     * Delete plan file
+     */
+    deletePlanFile(planFilePath: string): Promise<boolean>;
+    /**
+     * Ensure plan file is deleted (verify deletion)
+     */
+    ensurePlanFileDeleted(planFilePath: string): Promise<boolean>;
+    /**
+     * Capitalize phase name for display
+     */
+    private capitalizePhase;
+    /**
+     * Generate workflow documentation URL for predefined workflows
+     * Returns undefined for custom workflows
+     */
+    private generateWorkflowDocumentationUrl;
+}

package/dist/plan-manager.js

@@ -0,0 +1,256 @@
+/**
+ * Plan Manager
+ *
+ * Handles the creation, updating, and maintenance of project development plan files.
+ * Manages markdown plan files that serve as long-term project memory.
+ * Supports custom state machine definitions for dynamic plan file generation.
+ */
+import { writeFile, readFile, access } from 'node:fs/promises';
+import { dirname } from 'node:path';
+import { mkdir } from 'node:fs/promises';
+import { createLogger } from './logger.js';
+const logger = createLogger('PlanManager');
+export class PlanManager {
+    stateMachine = null;
+    /**
+     * Set the state machine definition for dynamic plan generation
+     */
+    setStateMachine(stateMachine) {
+        this.stateMachine = stateMachine;
+        logger.debug('State machine set for plan manager', {
+            name: stateMachine.name,
+            phases: Object.keys(stateMachine.states),
+        });
+    }
+    /**
+     * Get plan file information
+     */
+    async getPlanFileInfo(planFilePath) {
+        try {
+            await access(planFilePath);
+            const content = await readFile(planFilePath, 'utf-8');
+            return {
+                path: planFilePath,
+                exists: true,
+                content,
+            };
+        }
+        catch (_error) {
+            return {
+                path: planFilePath,
+                exists: false,
+            };
+        }
+    }
+    /**
+     * Create initial plan file if it doesn't exist
+     */
+    async ensurePlanFile(planFilePath, projectPath, gitBranch) {
+        logger.debug('Ensuring plan file exists', {
+            planFilePath,
+            projectPath,
+            gitBranch,
+        });
+        const planInfo = await this.getPlanFileInfo(planFilePath);
+        if (!planInfo.exists) {
+            logger.info('Plan file not found, creating initial plan', {
+                planFilePath,
+            });
+            await this.createInitialPlanFile(planFilePath, projectPath, gitBranch);
+            logger.info('Initial plan file created successfully', { planFilePath });
+        }
+        else {
+            logger.debug('Plan file already exists', { planFilePath });
+        }
+    }
+    /**
+     * Create initial plan file with template content
+     */
+    async createInitialPlanFile(planFilePath, projectPath, gitBranch) {
+        logger.debug('Creating initial plan file', { planFilePath });
+        try {
+            // Ensure directory exists
+            await mkdir(dirname(planFilePath), { recursive: true });
+            logger.debug('Plan file directory ensured', {
+                directory: dirname(planFilePath),
+            });
+            const projectName = projectPath.split('/').pop() || 'Unknown Project';
+            const branchInfo = gitBranch !== 'no-git' ? ` (${gitBranch} branch)` : '';
+            const initialContent = this.generateInitialPlanContent(projectName, branchInfo);
+            await writeFile(planFilePath, initialContent, 'utf-8');
+            logger.info('Initial plan file written successfully', {
+                planFilePath,
+                contentLength: initialContent.length,
+                projectName,
+            });
+        }
+        catch (error) {
+            logger.error('Failed to create initial plan file', error, {
+                planFilePath,
+            });
+            throw error;
+        }
+    }
+    /**
+     * Generate initial plan file content based on state machine definition
+     */
+    generateInitialPlanContent(projectName, branchInfo) {
+        const timestamp = new Date().toISOString().split('T')[0];
+        if (!this.stateMachine) {
+            throw new Error('State machine not set. This should not happen as state machine is always loaded.');
+        }
+        const phases = Object.keys(this.stateMachine.states);
+        const initialPhase = this.stateMachine.initial_state;
+        const documentationUrl = this.generateWorkflowDocumentationUrl(this.stateMachine.name);
+        let content = `# Development Plan: ${projectName}${branchInfo}
+
+*Generated on ${timestamp} by Vibe Feature MCP*
+*Workflow: ${documentationUrl
+            ? '[' + this.stateMachine.name + ']' + '(' + documentationUrl + ')'
+            : this.stateMachine.name}*
+
+## Goal
+*Define what you're building or fixing - this will be updated as requirements are gathered*
+
+## ${this.capitalizePhase(initialPhase)}
+### Tasks
+- [ ] *Tasks will be added as they are identified*
+
+### Completed
+- [x] Created development plan file
+
+`;
+        // Generate simple sections for each phase
+        for (const phase of phases) {
+            if (phase !== initialPhase) {
+                content += `## ${this.capitalizePhase(phase)}
+### Tasks
+- [ ] *To be added when this phase becomes active*
+
+### Completed
+*None yet*
+
+`;
+            }
+        }
+        content += `## Key Decisions
+*Important decisions will be documented here as they are made*
+
+## Notes
+*Additional context and observations*
+
+---
+*This plan is maintained by the LLM. Tool responses provide guidance on which section to focus on and what tasks to work on.*
+`;
+        return content;
+    }
+    /**
+     * Update plan file with new content (this is typically done by the LLM)
+     */
+    async updatePlanFile(planFilePath, content) {
+        // Ensure directory exists
+        await mkdir(dirname(planFilePath), { recursive: true });
+        await writeFile(planFilePath, content, 'utf-8');
+    }
+    /**
+     * Get plan file content for LLM context
+     */
+    async getPlanFileContent(planFilePath) {
+        const planInfo = await this.getPlanFileInfo(planFilePath);
+        if (!planInfo.exists) {
+            return 'Plan file does not exist yet. It will be created when the LLM updates it.';
+        }
+        return planInfo.content || '';
+    }
+    /**
+     * Generate phase-specific plan file guidance based on state machine
+     */
+    generatePlanFileGuidance(phase) {
+        if (!this.stateMachine) {
+            throw new Error('State machine not set. This should not happen as state machine is always loaded.');
+        }
+        const phaseDefinition = this.stateMachine.states[phase];
+        if (!phaseDefinition) {
+            logger.warn('Unknown phase for plan file guidance', { phase });
+            return `Update the ${this.capitalizePhase(phase)} section with current progress and mark completed tasks.`;
+        }
+        const capitalizedPhase = this.capitalizePhase(phase);
+        return `Update the ${capitalizedPhase} section with progress. Mark completed tasks with [x] and add new tasks as they are identified.`;
+    }
+    /**
+     * Delete plan file
+     */
+    async deletePlanFile(planFilePath) {
+        logger.debug('Deleting plan file', { planFilePath });
+        try {
+            // Check if file exists first
+            await access(planFilePath);
+            // Import unlink dynamically to avoid issues
+            const { unlink } = await import('node:fs/promises');
+            await unlink(planFilePath);
+            logger.info('Plan file deleted successfully', { planFilePath });
+            return true;
+        }
+        catch (error) {
+            if (error.code === 'ENOENT') {
+                logger.debug('Plan file does not exist, nothing to delete', {
+                    planFilePath,
+                });
+                return true; // Consider it successful if file doesn't exist
+            }
+            logger.error('Failed to delete plan file', error, {
+                planFilePath,
+            });
+            throw error;
+        }
+    }
+    /**
+     * Ensure plan file is deleted (verify deletion)
+     */
+    async ensurePlanFileDeleted(planFilePath) {
+        logger.debug('Ensuring plan file is deleted', { planFilePath });
+        try {
+            await access(planFilePath);
+            // If we reach here, file still exists
+            logger.warn('Plan file still exists after deletion attempt', {
+                planFilePath,
+            });
+            return false;
+        }
+        catch (error) {
+            if (error.code === 'ENOENT') {
+                logger.debug('Plan file successfully deleted (does not exist)', {
+                    planFilePath,
+                });
+                return true;
+            }
+            // Some other error occurred
+            logger.error('Error checking plan file deletion', error, {
+                planFilePath,
+            });
+            throw error;
+        }
+    }
+    /**
+     * Capitalize phase name for display
+     */
+    capitalizePhase(phase) {
+        return phase
+            .split('_')
+            .map(word => word.charAt(0).toUpperCase() + word.slice(1))
+            .join(' ');
+    }
+    /**
+     * Generate workflow documentation URL for predefined workflows
+     * Returns undefined for custom workflows
+     */
+    generateWorkflowDocumentationUrl(workflowName) {
+        // Don't generate URL for custom workflows
+        if (workflowName === 'custom') {
+            return undefined;
+        }
+        // Generate URL for predefined workflows
+        return `https://mrsimpson.github.io/responsible-vibe-mcp/workflows/${workflowName}`;
+    }
+}
+//# sourceMappingURL=plan-manager.js.map

package/dist/plan-manager.js.map

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

package/dist/project-docs-manager.d.ts

@@ -0,0 +1,119 @@
+/**
+ * Project Docs Manager
+ *
+ * Manages project documentation artifacts (architecture.md, requirements.md, design.md)
+ * separate from the workflow-specific plan files. Handles creation, validation, and
+ * path resolution for project documents. Now supports both template creation and
+ * file linking via symlinks.
+ */
+import { TemplateManager, TemplateOptions } from './template-manager.js';
+export interface ProjectDocsInfo {
+    architecture: {
+        path: string;
+        exists: boolean;
+    };
+    requirements: {
+        path: string;
+        exists: boolean;
+    };
+    design: {
+        path: string;
+        exists: boolean;
+    };
+}
+export interface CreateOrLinkResult {
+    created: string[];
+    linked: string[];
+    skipped: string[];
+}
+export declare class ProjectDocsManager {
+    templateManager: TemplateManager;
+    constructor();
+    /**
+     * Get project docs directory path
+     */
+    getDocsPath(projectPath: string): string;
+    /**
+     * Determine the appropriate extension for a document based on source path
+     */
+    private getDocumentExtension;
+    /**
+     * Get the target filename for a document type
+     */
+    private getDocumentFilename;
+    /**
+     * Get paths for all project documents
+     */
+    getDocumentPaths(projectPath: string): {
+        architecture: string;
+        requirements: string;
+        design: string;
+    };
+    /**
+     * Get paths for all project documents with dynamic extensions based on source paths
+     */
+    getDocumentPathsWithExtensions(projectPath: string, sourcePaths?: Partial<{
+        architecture: string;
+        requirements: string;
+        design: string;
+    }>): Promise<{
+        architecture: string;
+        requirements: string;
+        design: string;
+    }>;
+    /**
+     * Check which project documents exist
+     */
+    getProjectDocsInfo(projectPath: string): Promise<ProjectDocsInfo>;
+    /**
+     * Create project documents using templates (legacy method for backward compatibility)
+     */
+    createProjectDocs(projectPath: string, options?: TemplateOptions): Promise<{
+        created: string[];
+        skipped: string[];
+    }>;
+    /**
+     * Create or link project documents using templates and/or file paths
+     */
+    createOrLinkProjectDocs(projectPath: string, templateOptions?: Partial<TemplateOptions>, filePaths?: Partial<{
+        architecture: string;
+        requirements: string;
+        design: string;
+    }>): Promise<CreateOrLinkResult>;
+    /**
+     * Create a symlink to an existing file
+     */
+    createSymlink(sourcePath: string, targetPath: string): Promise<void>;
+    /**
+     * Remove existing document or symlink
+     */
+    private removeExistingDocument;
+    /**
+     * Create a single document from template
+     */
+    private createDocument;
+    /**
+     * Get variable substitutions for workflow instructions
+     */
+    getVariableSubstitutions(projectPath: string): Record<string, string>;
+    /**
+     * Get variable substitutions for workflow instructions with dynamic paths
+     */
+    getVariableSubstitutionsWithExtensions(projectPath: string, sourcePaths?: Partial<{
+        architecture: string;
+        requirements: string;
+        design: string;
+    }>): Promise<Record<string, string>>;
+    /**
+     * Read a project document - returns the path for LLM to read as needed
+     */
+    readDocument(projectPath: string, type: 'architecture' | 'requirements' | 'design'): Promise<string>;
+    /**
+     * Check if all project documents exist
+     */
+    allDocumentsExist(projectPath: string): Promise<boolean>;
+    /**
+     * Check if a document is a symlink
+     */
+    isSymlink(projectPath: string, type: 'architecture' | 'requirements' | 'design'): Promise<boolean>;
+}