@codemcp/workflows 5.2.4 → 6.0.1

package/packages/core/dist/persistence-interface.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Persistence Interface
+ *
+ * Defines the contract for conversation state and interaction log persistence.
+ * This interface abstracts the storage mechanism, allowing for different
+ * implementations (SQLite, file-based, etc.) to be used interchangeably.
+ */
+import type { ConversationState, InteractionLog } from './types.js';
+/**
+ * Interface for persistence operations
+ *
+ * Implementations must handle errors gracefully, especially user-corrupted data:
+ * - Missing files/data should return null or empty arrays
+ * - Corrupted data should be logged but not crash the application
+ * - Partial recovery should be attempted when possible (e.g., skip corrupted lines)
+ */
+export interface IPersistence {
+    /**
+     * Initialize the persistence layer
+     * Creates necessary storage structures (tables, directories, etc.)
+     *
+     * @throws Error if initialization fails
+     */
+    initialize(): Promise<void>;
+    /**
+     * Save or update a conversation state
+     *
+     * @param state - The conversation state to save
+     * @throws Error if save operation fails
+     */
+    saveConversationState(state: ConversationState): Promise<void>;
+    /**
+     * Get a conversation state by ID
+     *
+     * @param conversationId - The conversation ID to retrieve
+     * @returns The conversation state, or null if not found or corrupted
+     */
+    getConversationState(conversationId: string): Promise<ConversationState | null>;
+    /**
+     * Get all conversation states
+     *
+     * @returns Array of all conversation states (skips corrupted entries)
+     */
+    getAllConversationStates(): Promise<ConversationState[]>;
+    /**
+     * Delete a conversation state
+     *
+     * @param conversationId - The conversation ID to delete
+     * @returns True if deleted, false if not found
+     */
+    deleteConversationState(conversationId: string): Promise<boolean>;
+    /**
+     * Log an interaction
+     *
+     * @param log - The interaction log entry to save
+     * @throws Error if logging fails
+     */
+    logInteraction(log: InteractionLog): Promise<void>;
+    /**
+     * Get interaction logs for a conversation
+     *
+     * @param conversationId - The conversation ID to get logs for
+     * @returns Array of interaction logs (skips corrupted entries, empty if none exist)
+     */
+    getInteractionLogs(conversationId: string): Promise<InteractionLog[]>;
+    /**
+     * Get interaction logs by conversation ID (alias for compatibility)
+     *
+     * @param conversationId - The conversation ID to get logs for
+     * @returns Array of interaction logs (skips corrupted entries, empty if none exist)
+     */
+    getInteractionsByConversationId(conversationId: string): Promise<InteractionLog[]>;
+    /**
+     * Soft delete interaction logs for a conversation
+     * (Actual behavior depends on implementation - may be hard delete)
+     *
+     * @param conversationId - The conversation ID to delete logs for
+     */
+    softDeleteInteractionLogs(conversationId: string): Promise<void>;
+    /**
+     * Reset conversation state (update timestamp)
+     * Used for testing and state management
+     *
+     * @param conversationId - The conversation ID to reset
+     */
+    resetConversationState(conversationId: string): Promise<void>;
+    /**
+     * Close the persistence layer and clean up resources
+     */
+    close(): Promise<void>;
+}

package/packages/core/dist/persistence-interface.js

@@ -0,0 +1,9 @@
+/**
+ * Persistence Interface
+ *
+ * Defines the contract for conversation state and interaction log persistence.
+ * This interface abstracts the storage mechanism, allowing for different
+ * implementations (SQLite, file-based, etc.) to be used interchangeably.
+ */
+export {};
+//# sourceMappingURL=persistence-interface.js.map

package/packages/core/dist/persistence-interface.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"persistence-interface.js","sourceRoot":"","sources":["../src/persistence-interface.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG"}

package/{dist/components/beads/beads-plan-manager.d.ts → packages/core/dist/plan-manager.d.ts}

@@ -1,14 +1,14 @@
 /**
- * Beads Plan Manager
+ * Plan Manager
  *
- * Beads-specific implementation of IPlanManager.
- * Manages plan files optimized for beads task management workflow.
+ * 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 IPlanManager, type PlanFileInfo, type YamlStateMachine, type TaskBackendConfig } from '@codemcp/workflows-core';
-/**
- * Beads-specific plan manager implementation
- */
-export declare class BeadsPlanManager implements IPlanManager {
+import type { YamlStateMachine } from './state-machine-types.js';
+import type { TaskBackendConfig } from './task-backend.js';
+import type { IPlanManager, PlanFileInfo } from './interfaces/plan-manager.interface.js';
+export declare class PlanManager implements IPlanManager {
     private stateMachine;
     /**
      * Set the state machine definition for dynamic plan generation
@@ -27,15 +27,15 @@ export declare class BeadsPlanManager implements IPlanManager {
      */
     ensurePlanFile(planFilePath: string, projectPath: string, gitBranch: string): Promise<void>;
     /**
-     * Create initial plan file optimized for beads workflow
+     * Create initial plan file with template content
      */
-    private createInitialBeadsPlanFile;
+    private createInitialPlanFile;
     /**
-     * Generate initial plan file content optimized for beads workflow
+     * Generate initial plan file content based on state machine definition
      */
-    private generateBeadsInitialPlanContent;
+    private generateInitialPlanContent;
     /**
-     * Update plan file with new content
+     * Update plan file with new content (this is typically done by the LLM)
      */
     updatePlanFile(planFilePath: string, content: string): Promise<void>;
     /**
@@ -43,7 +43,7 @@ export declare class BeadsPlanManager implements IPlanManager {
      */
     getPlanFileContent(planFilePath: string): Promise<string>;
     /**
-     * Generate phase-specific plan file guidance optimized for beads
+     * Generate phase-specific plan file guidance based on state machine
      */
     generatePlanFileGuidance(phase: string): string;
     /**
@@ -60,7 +60,7 @@ export declare class BeadsPlanManager implements IPlanManager {
     private capitalizePhase;
     /**
      * Generate workflow documentation URL for predefined workflows
+     * Returns undefined for custom workflows
      */
     private generateWorkflowDocumentationUrl;
 }
-//# sourceMappingURL=beads-plan-manager.d.ts.map

package/{dist/components/beads/beads-plan-manager.js → packages/core/dist/plan-manager.js}

@@ -1,25 +1,24 @@
 /**
- * Beads Plan Manager
+ * Plan Manager
  *
- * Beads-specific implementation of IPlanManager.
- * Manages plan files optimized for beads task management workflow.
+ * 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 { createLogger, getPathBasename, } from '@codemcp/workflows-core';
 import { writeFile, readFile, access } from 'node:fs/promises';
 import { dirname } from 'node:path';
 import { mkdir } from 'node:fs/promises';
-const logger = createLogger('BeadsPlanManager');
-/**
- * Beads-specific plan manager implementation
- */
-export class BeadsPlanManager {
+import { createLogger } from './logger.js';
+import { getPathBasename } from './path-validation-utils.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 beads plan manager', {
+        logger.debug('State machine set for plan manager', {
             name: stateMachine.name,
             phases: Object.keys(stateMachine.states),
         });
@@ -28,8 +27,9 @@ export class BeadsPlanManager {
      * Set the task backend configuration
      */
     setTaskBackend(taskBackend) {
-        // Task backend is implicit for beads plan manager (always beads)
-        logger.debug('Task backend set for beads plan manager', {
+        // Default plan manager only supports markdown backend
+        // Task backend information is not stored as it's not used for markdown plan generation
+        logger.debug('Task backend set for plan manager (markdown mode)', {
             backend: taskBackend.backend,
             available: taskBackend.isAvailable,
         });
@@ -58,28 +58,28 @@ export class BeadsPlanManager {
      * Create initial plan file if it doesn't exist
      */
     async ensurePlanFile(planFilePath, projectPath, gitBranch) {
-        logger.debug('Ensuring beads plan file exists', {
+        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 beads-optimized plan', {
+            logger.info('Plan file not found, creating initial plan', {
                 planFilePath,
             });
-            await this.createInitialBeadsPlanFile(planFilePath, projectPath, gitBranch);
-            logger.info('Beads plan file created successfully', { 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 optimized for beads workflow
+     * Create initial plan file with template content
      */
-    async createInitialBeadsPlanFile(planFilePath, projectPath, gitBranch) {
-        logger.debug('Creating beads-optimized plan file', { planFilePath });
+    async createInitialPlanFile(planFilePath, projectPath, gitBranch) {
+        logger.debug('Creating initial plan file', { planFilePath });
         try {
             // Ensure directory exists
             await mkdir(dirname(planFilePath), { recursive: true });
@@ -88,25 +88,25 @@ export class BeadsPlanManager {
             });
             const projectName = getPathBasename(projectPath, 'Unknown Project');
             const branchInfo = gitBranch !== 'no-git' ? ` (${gitBranch} branch)` : '';
-            const initialContent = this.generateBeadsInitialPlanContent(projectName, branchInfo);
+            const initialContent = this.generateInitialPlanContent(projectName, branchInfo);
             await writeFile(planFilePath, initialContent, 'utf-8');
-            logger.info('Beads plan file written successfully', {
+            logger.info('Initial plan file written successfully', {
                 planFilePath,
                 contentLength: initialContent.length,
                 projectName,
             });
         }
         catch (error) {
-            logger.error('Failed to create beads plan file', error, {
+            logger.error('Failed to create initial plan file', error, {
                 planFilePath,
             });
             throw error;
         }
     }
     /**
-     * Generate initial plan file content optimized for beads workflow
+     * Generate initial plan file content based on state machine definition
      */
-    generateBeadsInitialPlanContent(projectName, branchInfo) {
+    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.');
@@ -123,39 +123,44 @@ export class BeadsPlanManager {
 
 ## Goal
 *Define what you're building or fixing - this will be updated as requirements are gathered*
+`;
+        content += `## Key Decisions
+*Important decisions will be documented here as they are made*
 
-## ${this.capitalizePhase(initialPhase)}
-<!-- beads-phase-id: TBD -->
+## Notes
+*Additional context and observations*
+
+`;
+        content += `## ${this.capitalizePhase(initialPhase)}
 ### Tasks
+- [ ] *Tasks will be added as they are identified*
 
-*Tasks managed via \`bd\` CLI*
+### Completed
+- [x] Created development plan file
 
 `;
-        // Generate sections for each phase with beads-specific guidance
+        // Generate simple sections for each phase
         for (const phase of phases) {
             if (phase !== initialPhase) {
                 content += `## ${this.capitalizePhase(phase)}
-<!-- beads-phase-id: TBD -->
 ### Tasks
+- [ ] *To be added when this phase becomes active*
 
-*Tasks managed via \`bd\` CLI*
+### Completed
+*None yet*
 
 `;
             }
         }
-        content += `## Key Decisions
-*Important decisions will be documented here as they are made*
-
-## Notes
-*Additional context and observations*
+        content += `
 
 ---
-*This plan is maintained by the LLM and uses beads CLI for task management. Tool responses provide guidance on which bd commands to use for task management.*
+*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
+     * Update plan file with new content (this is typically done by the LLM)
      */
     async updatePlanFile(planFilePath, content) {
         // Ensure directory exists
@@ -173,41 +178,51 @@ export class BeadsPlanManager {
         return planInfo.content || '';
     }
     /**
-     * Generate phase-specific plan file guidance optimized for beads
+     * Generate phase-specific plan file guidance based on state machine
      */
     generatePlanFileGuidance(phase) {
+        if (phase === null || phase === undefined) {
+            throw new Error('Phase parameter cannot be null or undefined');
+        }
+        if (typeof phase !== 'string') {
+            throw new Error('Phase parameter must be a string');
+        }
+        if (phase.trim() === '') {
+            throw new Error('Phase parameter cannot be empty');
+        }
         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 beads plan file guidance', { phase });
-            return `Track key decisions and take notes in the plan file. Use bd CLI for all task management.`;
+            logger.warn('Unknown phase for plan file guidance', { phase });
+            return `Update the ${this.capitalizePhase(phase)} section with current progress and mark completed tasks.`;
         }
-        return `Track key decisions and take notes in the plan file. Use bd CLI exclusively for task management - never use checkboxes. Document important decisions in the Key Decisions section.`;
+        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 beads plan file', { 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('Beads plan file deleted successfully', { planFilePath });
+            logger.info('Plan file deleted successfully', { planFilePath });
             return true;
         }
         catch (error) {
             if (error.code === 'ENOENT') {
-                logger.debug('Beads plan file does not exist, nothing to delete', {
+                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 beads plan file', error, {
+            logger.error('Failed to delete plan file', error, {
                 planFilePath,
             });
             throw error;
@@ -217,24 +232,24 @@ export class BeadsPlanManager {
      * Ensure plan file is deleted (verify deletion)
      */
     async ensurePlanFileDeleted(planFilePath) {
-        logger.debug('Ensuring beads plan file is deleted', { planFilePath });
+        logger.debug('Ensuring plan file is deleted', { planFilePath });
         try {
             await access(planFilePath);
             // If we reach here, file still exists
-            logger.warn('Beads plan file still exists after deletion attempt', {
+            logger.warn('Plan file still exists after deletion attempt', {
                 planFilePath,
             });
             return false;
         }
         catch (error) {
             if (error.code === 'ENOENT') {
-                logger.debug('Beads plan file successfully deleted (does not exist)', {
+                logger.debug('Plan file successfully deleted (does not exist)', {
                     planFilePath,
                 });
                 return true;
             }
             // Some other error occurred
-            logger.error('Error checking beads plan file deletion', error, {
+            logger.error('Error checking plan file deletion', error, {
                 planFilePath,
             });
             throw error;
@@ -251,6 +266,7 @@ export class BeadsPlanManager {
     }
     /**
      * Generate workflow documentation URL for predefined workflows
+     * Returns undefined for custom workflows
      */
     generateWorkflowDocumentationUrl(workflowName) {
         // Don't generate URL for custom workflows
@@ -261,4 +277,4 @@ export class BeadsPlanManager {
         return `https://mrsimpson.github.io/responsible-vibe-mcp/workflows/${workflowName}`;
     }
 }
-//# sourceMappingURL=beads-plan-manager.js.map
+//# sourceMappingURL=plan-manager.js.map

package/packages/core/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/packages/core/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, gitBranch?: 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>;
+}