@codemcp/workflows-core 3.1.16

package/dist/project-docs-manager.js

@@ -0,0 +1,357 @@
+/**
+ * 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 { writeFile, access, mkdir, unlink, symlink, lstat, stat, readdir, } from 'node:fs/promises';
+import { join, dirname, relative, extname, basename } from 'node:path';
+import { createLogger } from './logger.js';
+import { TemplateManager } from './template-manager.js';
+const logger = createLogger('ProjectDocsManager');
+export class ProjectDocsManager {
+    templateManager; // Make public for access from other classes
+    constructor() {
+        this.templateManager = new TemplateManager();
+    }
+    /**
+     * Get project docs directory path
+     */
+    getDocsPath(projectPath) {
+        return join(projectPath, '.vibe', 'docs');
+    }
+    /**
+     * Determine the appropriate extension for a document based on source path
+     */
+    async getDocumentExtension(sourcePath) {
+        if (!sourcePath) {
+            return '.md'; // Default for templates
+        }
+        try {
+            const stats = await stat(sourcePath);
+            if (stats.isDirectory()) {
+                return ''; // No extension for directories
+            }
+            // For files, preserve the original extension
+            const ext = extname(sourcePath);
+            return ext || '.md'; // Default to .md if no extension
+        }
+        catch (_error) {
+            return '.md'; // Default if we can't stat the source
+        }
+    }
+    /**
+     * Get the target filename for a document type
+     */
+    async getDocumentFilename(type, sourcePath) {
+        const extension = await this.getDocumentExtension(sourcePath);
+        // Always use the standardized document type name
+        // This ensures consistent symlink names regardless of source path
+        return extension === '' ? type : `${type}${extension}`;
+    }
+    /**
+     * Get paths for all project documents
+     */
+    getDocumentPaths(projectPath) {
+        const docsPath = this.getDocsPath(projectPath);
+        return {
+            architecture: join(docsPath, 'architecture.md'),
+            requirements: join(docsPath, 'requirements.md'),
+            design: join(docsPath, 'design.md'),
+        };
+    }
+    /**
+     * Get paths for all project documents with dynamic extensions based on source paths
+     */
+    async getDocumentPathsWithExtensions(projectPath, sourcePaths) {
+        const docsPath = this.getDocsPath(projectPath);
+        const archFilename = await this.getDocumentFilename('architecture', sourcePaths?.architecture);
+        const reqFilename = await this.getDocumentFilename('requirements', sourcePaths?.requirements);
+        const designFilename = await this.getDocumentFilename('design', sourcePaths?.design);
+        return {
+            architecture: join(docsPath, archFilename),
+            requirements: join(docsPath, reqFilename),
+            design: join(docsPath, designFilename),
+        };
+    }
+    /**
+     * Check which project documents exist
+     */
+    async getProjectDocsInfo(projectPath) {
+        const paths = this.getDocumentPaths(projectPath);
+        const checkExists = async (path) => {
+            try {
+                await access(path);
+                return true;
+            }
+            catch (_error) {
+                return false;
+            }
+        };
+        // Check for documents with different extensions using simple logic
+        const checkExistsWithExtensions = async (basePath, docType) => {
+            // First check the default .md path
+            if (await checkExists(basePath)) {
+                return { exists: true, actualPath: basePath };
+            }
+            // Check for the document type with any extension or as directory
+            const docsDir = dirname(basePath);
+            try {
+                const entries = await readdir(docsDir);
+                // Look for entries that match the document type exactly or start with it
+                for (const entry of entries) {
+                    const entryWithoutExt = entry.replace(/\.[^/.]+$/, '');
+                    if (entryWithoutExt === docType || entry === docType) {
+                        const entryPath = join(docsDir, entry);
+                        if (await checkExists(entryPath)) {
+                            return { exists: true, actualPath: entryPath };
+                        }
+                    }
+                }
+            }
+            catch (_error) {
+                // Directory might not exist yet
+            }
+            return { exists: false, actualPath: basePath };
+        };
+        const archResult = await checkExistsWithExtensions(paths.architecture, 'architecture');
+        const reqResult = await checkExistsWithExtensions(paths.requirements, 'requirements');
+        const designResult = await checkExistsWithExtensions(paths.design, 'design');
+        return {
+            architecture: {
+                path: archResult.actualPath,
+                exists: archResult.exists,
+            },
+            requirements: {
+                path: reqResult.actualPath,
+                exists: reqResult.exists,
+            },
+            design: {
+                path: designResult.actualPath,
+                exists: designResult.exists,
+            },
+        };
+    }
+    /**
+     * Create project documents using templates (legacy method for backward compatibility)
+     */
+    async createProjectDocs(projectPath, options) {
+        const result = await this.createOrLinkProjectDocs(projectPath, options, {});
+        return {
+            created: result.created,
+            skipped: result.skipped,
+        };
+    }
+    /**
+     * Create or link project documents using templates and/or file paths
+     */
+    async createOrLinkProjectDocs(projectPath, templateOptions, filePaths) {
+        const defaults = await this.templateManager.getDefaults();
+        const finalTemplateOptions = { ...defaults, ...templateOptions };
+        const docsPath = this.getDocsPath(projectPath);
+        // Use dynamic paths that consider source file extensions
+        const paths = await this.getDocumentPathsWithExtensions(projectPath, filePaths);
+        // Check existing documents using the old static paths for backward compatibility
+        const info = await this.getProjectDocsInfo(projectPath);
+        // Ensure docs directory exists
+        await mkdir(docsPath, { recursive: true });
+        const created = [];
+        const linked = [];
+        const skipped = [];
+        // Handle architecture document
+        if (!info.architecture.exists) {
+            if (filePaths?.architecture) {
+                await this.createSymlink(filePaths.architecture, paths.architecture);
+                const filename = basename(paths.architecture);
+                linked.push(filename);
+            }
+            else {
+                await this.createDocument('architecture', finalTemplateOptions.architecture, paths.architecture, docsPath);
+                const filename = basename(paths.architecture);
+                created.push(filename);
+            }
+        }
+        else {
+            skipped.push('architecture.md');
+        }
+        // Handle requirements document
+        if (!info.requirements.exists) {
+            if (filePaths?.requirements) {
+                await this.createSymlink(filePaths.requirements, paths.requirements);
+                const filename = basename(paths.requirements);
+                linked.push(filename);
+            }
+            else {
+                await this.createDocument('requirements', finalTemplateOptions.requirements, paths.requirements, docsPath);
+                const filename = basename(paths.requirements);
+                created.push(filename);
+            }
+        }
+        else {
+            skipped.push('requirements.md');
+        }
+        // Handle design document
+        if (!info.design.exists) {
+            if (filePaths?.design) {
+                await this.createSymlink(filePaths.design, paths.design);
+                const filename = basename(paths.design);
+                linked.push(filename);
+            }
+            else {
+                await this.createDocument('design', finalTemplateOptions.design, paths.design, docsPath);
+                const filename = basename(paths.design);
+                created.push(filename);
+            }
+        }
+        else {
+            skipped.push('design.md');
+        }
+        logger.info('Project docs creation/linking completed', {
+            created,
+            linked,
+            skipped,
+            projectPath,
+            templateOptions: finalTemplateOptions,
+            filePaths,
+        });
+        return { created, linked, skipped };
+    }
+    /**
+     * Create a symlink to an existing file
+     */
+    async createSymlink(sourcePath, targetPath) {
+        try {
+            // Remove existing file/symlink if it exists
+            await this.removeExistingDocument(targetPath);
+            // Create relative symlink for better portability
+            const targetDir = dirname(targetPath);
+            const relativePath = relative(targetDir, sourcePath);
+            await symlink(relativePath, targetPath);
+            logger.debug('Symlink created successfully', {
+                sourcePath,
+                targetPath,
+                relativePath,
+            });
+        }
+        catch (error) {
+            logger.error('Failed to create symlink', error, {
+                sourcePath,
+                targetPath,
+            });
+            throw new Error(`Failed to create symlink: ${error instanceof Error ? error.message : 'Unknown error'}`);
+        }
+    }
+    /**
+     * Remove existing document or symlink
+     */
+    async removeExistingDocument(documentPath) {
+        try {
+            const stats = await lstat(documentPath);
+            await unlink(documentPath);
+            logger.debug('Existing document removed', {
+                documentPath,
+                wasSymlink: stats.isSymbolicLink(),
+            });
+        }
+        catch (error) {
+            // File doesn't exist, which is fine
+            if (error instanceof Error &&
+                'code' in error &&
+                error.code !== 'ENOENT') {
+                logger.debug('Failed to remove existing document', {
+                    documentPath,
+                    error: error instanceof Error ? error.message : 'Unknown error',
+                });
+            }
+        }
+    }
+    /**
+     * Create a single document from template
+     */
+    async createDocument(type, template, documentPath, docsPath) {
+        try {
+            const templateResult = await this.templateManager.loadTemplate(type, template);
+            // Write the main document
+            await writeFile(documentPath, templateResult.content, 'utf-8');
+            // Write additional files (like images for arc42)
+            if (templateResult.additionalFiles) {
+                for (const file of templateResult.additionalFiles) {
+                    const filePath = join(docsPath, file.relativePath);
+                    const fileDir = dirname(filePath);
+                    // Ensure directory exists
+                    await mkdir(fileDir, { recursive: true });
+                    // Write file
+                    await writeFile(filePath, file.content);
+                }
+            }
+            logger.debug(`Created ${type} document`, { documentPath, template });
+        }
+        catch (error) {
+            logger.error(`Failed to create ${type} document`, error, {
+                documentPath,
+                template,
+            });
+            throw error;
+        }
+    }
+    /**
+     * Get variable substitutions for workflow instructions
+     */
+    getVariableSubstitutions(projectPath) {
+        const paths = this.getDocumentPaths(projectPath);
+        return {
+            $ARCHITECTURE_DOC: paths.architecture,
+            $REQUIREMENTS_DOC: paths.requirements,
+            $DESIGN_DOC: paths.design,
+        };
+    }
+    /**
+     * Get variable substitutions for workflow instructions with dynamic paths
+     */
+    async getVariableSubstitutionsWithExtensions(projectPath, sourcePaths) {
+        const paths = await this.getDocumentPathsWithExtensions(projectPath, sourcePaths);
+        return {
+            $ARCHITECTURE_DOC: paths.architecture,
+            $REQUIREMENTS_DOC: paths.requirements,
+            $DESIGN_DOC: paths.design,
+        };
+    }
+    /**
+     * Read a project document - returns the path for LLM to read as needed
+     */
+    async readDocument(projectPath, type) {
+        // Use the dynamic path detection to get the actual document path
+        const docsInfo = await this.getProjectDocsInfo(projectPath);
+        const documentPath = docsInfo[type].path;
+        if (!docsInfo[type].exists) {
+            throw new Error(`${type} document not found: ${documentPath}`);
+        }
+        // Return the pure path for the LLM to read as needed
+        // This is more efficient for large documents and gives LLM full control
+        return documentPath;
+    }
+    /**
+     * Check if all project documents exist
+     */
+    async allDocumentsExist(projectPath) {
+        const info = await this.getProjectDocsInfo(projectPath);
+        return (info.architecture.exists && info.requirements.exists && info.design.exists);
+    }
+    /**
+     * Check if a document is a symlink
+     */
+    async isSymlink(projectPath, type) {
+        const paths = this.getDocumentPaths(projectPath);
+        const documentPath = paths[type];
+        try {
+            const stats = await lstat(documentPath);
+            return stats.isSymbolicLink();
+        }
+        catch (_error) {
+            return false;
+        }
+    }
+}
+//# sourceMappingURL=project-docs-manager.js.map

package/dist/project-docs-manager.js.map

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

package/dist/state-machine-loader.d.ts

@@ -0,0 +1,60 @@
+/**
+ * State Machine Loader
+ *
+ * Loads and validates YAML-based state machine definitions
+ */
+import { YamlStateMachine, YamlTransition } from './state-machine-types.js';
+/**
+ * Loads and manages YAML-based state machine definitions
+ */
+export declare class StateMachineLoader {
+    private stateMachine;
+    private validPhases;
+    /**
+     * Get all valid phases from the loaded state machine
+     */
+    getValidPhases(): string[];
+    /**
+     * Get the initial state from the loaded state machine
+     */
+    getInitialState(): string;
+    /**
+     * Load state machine from YAML file
+     *
+     * Checks for custom state machine file in project directory first,
+     * then falls back to waterfall workflow as default
+     */
+    loadStateMachine(projectPath: string): YamlStateMachine;
+    /**
+     * Load state machine from specific file path
+     */
+    loadFromFile(filePath: string): YamlStateMachine;
+    /**
+     * Validate the state machine structure and references
+     */
+    private validateStateMachine;
+    /**
+     * Get transition instructions for a specific state change
+     */
+    getTransitionInstructions(fromState: string, toState: string, trigger?: string): {
+        instructions: string;
+        transitionReason: string;
+        isModeled: boolean;
+    };
+    /**
+     * Get all possible transitions from a given state
+     */
+    getPossibleTransitions(fromState: string): YamlTransition[];
+    /**
+     * Check if a transition is modeled (shown in state diagram)
+     */
+    isModeledTransition(fromState: string, toState: string): boolean;
+    /**
+     * Check if a phase is valid in the current state machine
+     */
+    isValidPhase(phase: string): boolean;
+    /**
+     * Get phase-specific instructions for continuing work in current phase
+     */
+    getContinuePhaseInstructions(phase: string): string;
+}

package/dist/state-machine-loader.js

@@ -0,0 +1,235 @@
+/**
+ * State Machine Loader
+ *
+ * Loads and validates YAML-based state machine definitions
+ */
+import fs from 'node:fs';
+import yaml from 'js-yaml';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { createLogger } from './logger.js';
+const logger = createLogger('StateMachineLoader');
+/**
+ * Loads and manages YAML-based state machine definitions
+ */
+export class StateMachineLoader {
+    stateMachine = null;
+    validPhases = new Set();
+    /**
+     * Get all valid phases from the loaded state machine
+     */
+    getValidPhases() {
+        if (!this.stateMachine) {
+            throw new Error('State machine not loaded');
+        }
+        return Array.from(this.validPhases);
+    }
+    /**
+     * Get the initial state from the loaded state machine
+     */
+    getInitialState() {
+        if (!this.stateMachine) {
+            throw new Error('State machine not loaded');
+        }
+        return this.stateMachine.initial_state;
+    }
+    /**
+     * Load state machine from YAML file
+     *
+     * Checks for custom state machine file in project directory first,
+     * then falls back to waterfall workflow as default
+     */
+    loadStateMachine(projectPath) {
+        // Check for custom state machine file in project directory
+        const customFilePaths = [
+            path.join(projectPath, '.vibe', 'workflow.yaml'),
+            path.join(projectPath, '.vibe', 'workflow.yml'),
+        ];
+        // Try to load custom state machine file
+        for (const filePath of customFilePaths) {
+            if (fs.existsSync(filePath)) {
+                logger.info('Loading custom state machine file', { filePath });
+                try {
+                    return this.loadFromFile(filePath);
+                }
+                catch (error) {
+                    logger.warn('Failed to load custom state machine, falling back to default', {
+                        filePath,
+                        error: error.message,
+                    });
+                    // Continue to try next file or fall back to default
+                }
+            }
+        }
+        // Fall back to waterfall workflow as default
+        // Use import.meta.url to get the current file's path in ESM
+        const currentFileUrl = import.meta.url;
+        const currentFilePath = fileURLToPath(currentFileUrl);
+        // Go up from packages/core/dist/ to project root (4 levels up)
+        const projectRoot = path.dirname(path.dirname(path.dirname(path.dirname(currentFilePath))));
+        const defaultFilePath = path.join(projectRoot, 'resources', 'workflows', 'waterfall.yaml');
+        logger.info('Loading default state machine file', { defaultFilePath });
+        return this.loadFromFile(defaultFilePath);
+    }
+    /**
+     * Load state machine from specific file path
+     */
+    loadFromFile(filePath) {
+        try {
+            const yamlContent = fs.readFileSync(path.resolve(filePath), 'utf8');
+            const stateMachine = yaml.load(yamlContent);
+            // Validate the state machine
+            this.validateStateMachine(stateMachine);
+            // Store valid phases for later validation
+            this.validPhases = new Set(Object.keys(stateMachine.states));
+            this.stateMachine = stateMachine;
+            logger.info('State machine loaded successfully', {
+                name: stateMachine.name,
+                stateCount: Object.keys(stateMachine.states).length,
+                phases: Array.from(this.validPhases),
+            });
+            return stateMachine;
+        }
+        catch (error) {
+            logger.error('Failed to load state machine', error);
+            throw new Error(`Failed to load state machine: ${error.message}`);
+        }
+    }
+    /**
+     * Validate the state machine structure and references
+     */
+    validateStateMachine(stateMachine) {
+        // Check required properties
+        if (!stateMachine.name ||
+            !stateMachine.description ||
+            !stateMachine.initial_state ||
+            !stateMachine.states) {
+            throw new Error('State machine is missing required properties');
+        }
+        // Get all state names
+        const stateNames = Object.keys(stateMachine.states);
+        // Check initial state is valid
+        if (!stateNames.includes(stateMachine.initial_state)) {
+            throw new Error(`Initial state "${stateMachine.initial_state}" is not defined in states`);
+        }
+        // Validate states and transitions
+        for (const [stateName, state] of Object.entries(stateMachine.states)) {
+            // Check required state properties
+            if (!state.description || !state.default_instructions) {
+                throw new Error(`State "${stateName}" is missing required properties (description or default_instructions)`);
+            }
+            if (!state.transitions || !Array.isArray(state.transitions)) {
+                throw new Error(`State "${stateName}" has invalid transitions property`);
+            }
+            for (const transition of state.transitions) {
+                if (!stateNames.includes(transition.to)) {
+                    throw new Error(`State "${stateName}" has transition to unknown state "${transition.to}"`);
+                }
+                if (!transition.transition_reason) {
+                    throw new Error(`Transition from "${stateName}" to "${transition.to}" is missing transition_reason`);
+                }
+            }
+        }
+        logger.debug('State machine validation successful');
+    }
+    /**
+     * Get transition instructions for a specific state change
+     */
+    getTransitionInstructions(fromState, toState, trigger) {
+        if (!this.stateMachine) {
+            throw new Error('State machine not loaded');
+        }
+        // Get target state definition
+        const targetState = this.stateMachine.states[toState];
+        if (!targetState) {
+            throw new Error(`Target state "${toState}" not found`);
+        }
+        // Look for a modeled transition first
+        const fromStateDefinition = this.stateMachine.states[fromState];
+        if (fromStateDefinition) {
+            const transition = fromStateDefinition.transitions.find(t => t.to === toState && (!trigger || t.trigger === trigger));
+            if (transition) {
+                // For modeled transitions, compose instructions
+                let composedInstructions = targetState.default_instructions;
+                // If transition has specific instructions, use those instead of default
+                if (transition.instructions) {
+                    composedInstructions = transition.instructions;
+                }
+                // If transition has additional instructions, combine them
+                if (transition.additional_instructions) {
+                    composedInstructions = `${composedInstructions}\n\n**Additional Context:**\n${transition.additional_instructions}`;
+                }
+                return {
+                    instructions: composedInstructions,
+                    transitionReason: transition.transition_reason,
+                    isModeled: true,
+                };
+            }
+        }
+        // Fall back to target state's default instructions for unmodeled transitions
+        return {
+            instructions: targetState.default_instructions,
+            transitionReason: `Direct transition to ${toState} phase`,
+            isModeled: false,
+        };
+    }
+    /**
+     * Get all possible transitions from a given state
+     */
+    getPossibleTransitions(fromState) {
+        if (!this.stateMachine) {
+            throw new Error('State machine not loaded');
+        }
+        const stateDefinition = this.stateMachine.states[fromState];
+        return stateDefinition ? stateDefinition.transitions : [];
+    }
+    /**
+     * Check if a transition is modeled (shown in state diagram)
+     */
+    isModeledTransition(fromState, toState) {
+        if (!this.stateMachine) {
+            throw new Error('State machine not loaded');
+        }
+        const stateDefinition = this.stateMachine.states[fromState];
+        if (!stateDefinition)
+            return false;
+        return stateDefinition.transitions.some(t => t.to === toState);
+    }
+    /**
+     * Check if a phase is valid in the current state machine
+     */
+    isValidPhase(phase) {
+        return this.validPhases.has(phase);
+    }
+    /**
+     * Get phase-specific instructions for continuing work in current phase
+     */
+    getContinuePhaseInstructions(phase) {
+        if (!this.stateMachine) {
+            throw new Error('State machine not loaded');
+        }
+        const stateDefinition = this.stateMachine.states[phase];
+        if (!stateDefinition) {
+            logger.error('Unknown phase', new Error(`Unknown phase: ${phase}`));
+            throw new Error(`Unknown phase: ${phase}`);
+        }
+        // Look for a self-transition (continue in same phase)
+        const continueTransition = stateDefinition.transitions.find(t => t.to === phase);
+        if (continueTransition) {
+            // Compose instructions for continue transition
+            let composedInstructions = stateDefinition.default_instructions;
+            // If transition has specific instructions, use those instead of default
+            if (continueTransition.instructions) {
+                composedInstructions = continueTransition.instructions;
+            }
+            // If transition has additional instructions, combine them
+            if (continueTransition.additional_instructions) {
+                composedInstructions = `${composedInstructions}\n\n**Additional Context:**\n${continueTransition.additional_instructions}`;
+            }
+            return composedInstructions;
+        }
+        // Fall back to default instructions for the phase
+        return stateDefinition.default_instructions;
+    }
+}
+//# sourceMappingURL=state-machine-loader.js.map