clavix 2.4.3 → 2.5.0

package/dist/core/config-manager.js

@@ -0,0 +1,267 @@
+"use strict";
+/**
+ * ConfigManager - Manages .clavix-implement-config.json
+ *
+ * This class handles:
+ * - Reading/writing implementation configuration
+ * - Tracking task completion state
+ * - Managing resume checkpoints
+ * - Storing git commit strategy preferences
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ConfigManager = void 0;
+const fs = __importStar(require("fs-extra"));
+const path = __importStar(require("path"));
+/**
+ * ConfigManager class
+ *
+ * Manages implementation configuration and task tracking state
+ */
+class ConfigManager {
+    /**
+     * Read implementation config from file
+     * @param configPath - Path to config file (.clavix-implement-config.json)
+     * @returns Implementation configuration
+     */
+    async read(configPath) {
+        if (!(await fs.pathExists(configPath))) {
+            throw new Error(`Config file not found: ${configPath}\n\nHint: Run "clavix implement" first to initialize configuration`);
+        }
+        try {
+            const config = await fs.readJson(configPath);
+            // Migrate old config format if needed
+            return this.migrateConfig(config);
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : 'Unknown error';
+            throw new Error(`Failed to read config file: ${errorMessage}`);
+        }
+    }
+    /**
+     * Write implementation config to file
+     * @param configPath - Path to config file
+     * @param config - Configuration to write
+     * @param options - Update options
+     */
+    async write(configPath, config, options = {}) {
+        const { validate = true } = options;
+        if (validate) {
+            this.validateConfig(config);
+        }
+        try {
+            await fs.writeJson(configPath, config, { spaces: 2 });
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : 'Unknown error';
+            throw new Error(`Failed to write config file: ${errorMessage}`);
+        }
+    }
+    /**
+     * Update specific fields in config
+     * @param configPath - Path to config file
+     * @param updates - Partial config updates
+     */
+    async update(configPath, updates) {
+        const existing = await this.read(configPath);
+        const updated = {
+            ...existing,
+            ...updates,
+            timestamp: new Date().toISOString(),
+        };
+        await this.write(configPath, updated);
+    }
+    /**
+     * Track a task completion
+     * @param configPath - Path to config file
+     * @param taskId - ID of completed task
+     */
+    async trackCompletion(configPath, taskId) {
+        const config = await this.read(configPath);
+        // Initialize tracking arrays if not present
+        if (!config.completedTaskIds) {
+            config.completedTaskIds = [];
+        }
+        if (!config.completionTimestamps) {
+            config.completionTimestamps = {};
+        }
+        // Add to completed tasks (avoid duplicates)
+        if (!config.completedTaskIds.includes(taskId)) {
+            config.completedTaskIds.push(taskId);
+        }
+        // Record completion timestamp
+        config.completionTimestamps[taskId] = new Date().toISOString();
+        // Update last completed task
+        config.lastCompletedTaskId = taskId;
+        // Update timestamp
+        config.timestamp = new Date().toISOString();
+        await this.write(configPath, config);
+    }
+    /**
+     * Add a blocked task
+     * @param configPath - Path to config file
+     * @param taskId - ID of blocked task
+     * @param reason - Reason for blocking
+     */
+    async addBlockedTask(configPath, taskId, reason) {
+        const config = await this.read(configPath);
+        if (!config.blockedTasks) {
+            config.blockedTasks = [];
+        }
+        // Remove existing entry for this task if present
+        config.blockedTasks = config.blockedTasks.filter(b => b.taskId !== taskId);
+        // Add new blocked task
+        config.blockedTasks.push({
+            taskId,
+            reason,
+            timestamp: new Date().toISOString(),
+        });
+        config.timestamp = new Date().toISOString();
+        await this.write(configPath, config);
+    }
+    /**
+     * Remove a blocked task (unblock)
+     * @param configPath - Path to config file
+     * @param taskId - ID of task to unblock
+     */
+    async removeBlockedTask(configPath, taskId) {
+        const config = await this.read(configPath);
+        if (config.blockedTasks) {
+            config.blockedTasks = config.blockedTasks.filter(b => b.taskId !== taskId);
+            config.timestamp = new Date().toISOString();
+            await this.write(configPath, config);
+        }
+    }
+    /**
+     * Get current implementation state
+     * @param configPath - Path to config file
+     * @returns State summary
+     */
+    async getState(configPath) {
+        const config = await this.read(configPath);
+        return {
+            currentTaskId: config.currentTask.id,
+            completedCount: config.completedTaskIds?.length ?? 0,
+            remainingCount: config.stats.remaining,
+            blockedCount: config.blockedTasks?.length ?? 0,
+            lastCompletedTaskId: config.lastCompletedTaskId,
+            lastCompletionTime: config.lastCompletedTaskId
+                ? config.completionTimestamps?.[config.lastCompletedTaskId]
+                : undefined,
+        };
+    }
+    /**
+     * Check if a task has been completed
+     * @param configPath - Path to config file
+     * @param taskId - Task ID to check
+     * @returns true if task is in completed list
+     */
+    async isTaskCompleted(configPath, taskId) {
+        const config = await this.read(configPath);
+        return config.completedTaskIds?.includes(taskId) ?? false;
+    }
+    /**
+     * Validate config structure
+     * @param config - Configuration to validate
+     * @throws Error if config is invalid
+     */
+    validateConfig(config) {
+        if (!config.commitStrategy) {
+            throw new Error('Config validation failed: commitStrategy is required');
+        }
+        if (!config.tasksPath) {
+            throw new Error('Config validation failed: tasksPath is required');
+        }
+        if (!config.currentTask) {
+            throw new Error('Config validation failed: currentTask is required');
+        }
+        if (!config.stats) {
+            throw new Error('Config validation failed: stats is required');
+        }
+        const validStrategies = ['per-task', 'per-5-tasks', 'per-phase', 'none'];
+        if (!validStrategies.includes(config.commitStrategy)) {
+            throw new Error(`Config validation failed: invalid commitStrategy "${config.commitStrategy}"`);
+        }
+    }
+    /**
+     * Migrate old config format to new format
+     * @param config - Old config format
+     * @returns Migrated config
+     */
+    migrateConfig(config) {
+        // If already has new fields, return as-is
+        if (config.completedTaskIds !== undefined) {
+            return config;
+        }
+        // Migrate from old format
+        const migrated = {
+            commitStrategy: config.commitStrategy,
+            tasksPath: config.tasksPath,
+            currentTask: config.currentTask,
+            stats: config.stats,
+            timestamp: config.timestamp ?? new Date().toISOString(),
+            completedTaskIds: [],
+            completionTimestamps: {},
+            blockedTasks: [],
+        };
+        return migrated;
+    }
+    /**
+     * Create a resume checkpoint
+     * @param configPath - Path to config file
+     * @param currentTaskId - Current task being worked on
+     * @param phaseProgress - Progress by phase (phase name -> completed count)
+     */
+    async createResumeCheckpoint(configPath, currentTaskId, phaseProgress) {
+        const config = await this.read(configPath);
+        config.resumeCheckpoint = {
+            lastTaskId: currentTaskId,
+            phaseProgress,
+            sessionStartTime: new Date().toISOString(),
+        };
+        config.timestamp = new Date().toISOString();
+        await this.write(configPath, config);
+    }
+    /**
+     * Get the config file path for a PRD directory
+     * @param prdPath - Path to PRD directory
+     * @returns Path to config file
+     */
+    static getConfigPath(prdPath) {
+        return path.join(prdPath, '.clavix-implement-config.json');
+    }
+}
+exports.ConfigManager = ConfigManager;
+//# sourceMappingURL=config-manager.js.map

package/dist/core/git-manager.d.ts

@@ -15,7 +15,9 @@ export type CommitStrategy = 'per-phase' | 'per-5-tasks' | 'per-task' | 'none';
  * Options for creating a commit
  */
 export interface CommitOptions {
-    tasks: string[];
+    message?: string;
+    description?: string;
+    tasks?: string[];
     phase?: string;
     projectName?: string;
 }
@@ -41,6 +43,30 @@ export declare class GitManager {
      * Generate commit message from tasks
      */
     private generateCommitMessage;
+    /**
+     * Validate that tasks are marked before committing
+     * This ensures the tasks.md file matches what we expect to commit
+     * @param tasksPath - Path to tasks.md file
+     * @param completedTaskIds - Array of task IDs that should be completed
+     * @returns Validation result with any errors
+     */
+    validateBeforeCommit(tasksPath: string, completedTaskIds: string[]): Promise<{
+        valid: boolean;
+        errors?: string[];
+    }>;
+    /**
+     * Create commit with validation
+     * Validates that tasks are marked before committing
+     * @param options - Commit options
+     * @param tasksPath - Path to tasks.md file
+     * @param completedTaskIds - Array of task IDs that should be completed
+     * @returns Commit result with validation status
+     */
+    createCommitWithValidation(options: CommitOptions, tasksPath?: string, completedTaskIds?: string[]): Promise<{
+        success: boolean;
+        validated: boolean;
+        errors?: string[];
+    }>;
     /**
      * Escape commit message for shell
      */

package/dist/core/git-manager.js

@@ -8,6 +8,39 @@
  * - Generating commit messages
  * - Handling commit strategies (per task, per phase, per N tasks)
  */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.CommitScheduler = exports.GitManager = void 0;
 const child_process_1 = require("child_process");
@@ -54,8 +87,8 @@ class GitManager {
             }
             // Stage all changes
             await execAsync('git add .');
-            // Generate commit message
-            const message = this.generateCommitMessage(options);
+            // Use provided message or generate one
+            const message = options.message ?? this.generateCommitMessage(options);
             // Create commit
             await execAsync(`git commit -m "${this.escapeCommitMessage(message)}"`);
             return true;
@@ -70,31 +103,102 @@ class GitManager {
      * Generate commit message from tasks
      */
     generateCommitMessage(options) {
-        const { tasks, phase, projectName } = options;
+        const { description, tasks = [], phase, projectName } = options;
         let message = '';
         // Header
         if (phase) {
             message += `clavix: ${phase}\n\n`;
         }
+        else if (description) {
+            message += `clavix: ${description}\n\n`;
+        }
         else if (tasks.length === 1) {
             message += `clavix: ${tasks[0]}\n\n`;
         }
-        else {
+        else if (tasks.length > 1) {
             message += `clavix: implement ${tasks.length} tasks\n\n`;
         }
-        // Task list
-        message += 'Completed tasks:\n';
-        tasks.forEach((task) => {
-            message += `- ${task}\n`;
-        });
+        else {
+            message += `clavix: task completed\n\n`;
+        }
+        // Task list (if provided)
+        if (tasks.length > 0) {
+            message += 'Completed tasks:\n';
+            tasks.forEach((task) => {
+                message += `- ${task}\n`;
+            });
+            message += '\n';
+        }
         // Footer
-        message += '\n';
         if (projectName) {
             message += `Project: ${projectName}\n`;
         }
         message += 'Generated by Clavix /clavix:implement';
         return message;
     }
+    /**
+     * Validate that tasks are marked before committing
+     * This ensures the tasks.md file matches what we expect to commit
+     * @param tasksPath - Path to tasks.md file
+     * @param completedTaskIds - Array of task IDs that should be completed
+     * @returns Validation result with any errors
+     */
+    async validateBeforeCommit(tasksPath, completedTaskIds) {
+        const errors = [];
+        try {
+            // Read tasks.md file
+            const fs = await Promise.resolve().then(() => __importStar(require('fs-extra')));
+            if (!(await fs.pathExists(tasksPath))) {
+                errors.push(`Tasks file not found: ${tasksPath}`);
+                return { valid: false, errors };
+            }
+            const content = await fs.readFile(tasksPath, 'utf-8');
+            // Check each task ID is marked as complete in the file
+            for (const taskId of completedTaskIds) {
+                // Look for the task in the file (should have [x] checkbox)
+                const hasCompleteCheckbox = content.includes(`[x]`) && content.includes(taskId);
+                if (!hasCompleteCheckbox) {
+                    errors.push(`Task ${taskId} not marked as completed in tasks.md`);
+                }
+            }
+            return {
+                valid: errors.length === 0,
+                errors: errors.length > 0 ? errors : undefined,
+            };
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : 'Unknown error';
+            errors.push(`Validation failed: ${errorMessage}`);
+            return { valid: false, errors };
+        }
+    }
+    /**
+     * Create commit with validation
+     * Validates that tasks are marked before committing
+     * @param options - Commit options
+     * @param tasksPath - Path to tasks.md file
+     * @param completedTaskIds - Array of task IDs that should be completed
+     * @returns Commit result with validation status
+     */
+    async createCommitWithValidation(options, tasksPath, completedTaskIds) {
+        // If validation info provided, validate first
+        if (tasksPath && completedTaskIds) {
+            const validation = await this.validateBeforeCommit(tasksPath, completedTaskIds);
+            if (!validation.valid) {
+                return {
+                    success: false,
+                    validated: false,
+                    errors: validation.errors,
+                };
+            }
+        }
+        // Create commit
+        const success = await this.createCommit(options);
+        return {
+            success,
+            validated: tasksPath !== undefined && completedTaskIds !== undefined,
+        };
+    }
     /**
      * Escape commit message for shell
      */

package/dist/core/task-manager.d.ts

@@ -133,6 +133,37 @@ export declare class TaskManager {
      * Escape special regex characters
      */
     private escapeRegex;
+    /**
+     * Validate that a task exists in the phases
+     * @param phases - Array of task phases
+     * @param taskId - Task ID to validate
+     * @returns The task if found, null otherwise
+     */
+    validateTaskExists(phases: TaskPhase[], taskId: string): Task | null;
+    /**
+     * Verify that a task was successfully marked as completed in the file
+     * @param tasksPath - Path to tasks.md file
+     * @param taskId - Task ID to verify
+     * @returns true if task is marked completed, false otherwise
+     */
+    verifyTaskMarked(tasksPath: string, taskId: string): Promise<boolean>;
+    /**
+     * Mark a task as completed with validation and error recovery
+     * Enhanced version with pre/post validation
+     * @param tasksPath - Path to tasks.md file
+     * @param taskId - Task ID to mark as completed
+     * @param options - Optional configuration for error recovery
+     * @returns Object with success status and any warnings/errors
+     */
+    markTaskCompletedWithValidation(tasksPath: string, taskId: string, options?: {
+        retryOnFailure?: boolean;
+        createBackup?: boolean;
+    }): Promise<{
+        success: boolean;
+        alreadyCompleted?: boolean;
+        error?: string;
+        warnings?: string[];
+    }>;
     /**
      * Get task completion statistics
      */

package/dist/core/task-manager.js

@@ -605,6 +605,148 @@ class TaskManager {
     escapeRegex(str) {
         return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
     }
+    /**
+     * Validate that a task exists in the phases
+     * @param phases - Array of task phases
+     * @param taskId - Task ID to validate
+     * @returns The task if found, null otherwise
+     */
+    validateTaskExists(phases, taskId) {
+        for (const phase of phases) {
+            const task = phase.tasks.find(t => t.id === taskId);
+            if (task) {
+                return task;
+            }
+        }
+        return null;
+    }
+    /**
+     * Verify that a task was successfully marked as completed in the file
+     * @param tasksPath - Path to tasks.md file
+     * @param taskId - Task ID to verify
+     * @returns true if task is marked completed, false otherwise
+     */
+    async verifyTaskMarked(tasksPath, taskId) {
+        try {
+            const phases = await this.readTasksFile(tasksPath);
+            const task = this.validateTaskExists(phases, taskId);
+            return task ? task.completed : false;
+        }
+        catch (error) {
+            // If we can't read the file, verification failed
+            return false;
+        }
+    }
+    /**
+     * Mark a task as completed with validation and error recovery
+     * Enhanced version with pre/post validation
+     * @param tasksPath - Path to tasks.md file
+     * @param taskId - Task ID to mark as completed
+     * @param options - Optional configuration for error recovery
+     * @returns Object with success status and any warnings/errors
+     */
+    async markTaskCompletedWithValidation(tasksPath, taskId, options = {}) {
+        const { retryOnFailure = true, createBackup = true } = options;
+        const warnings = [];
+        // Pre-validation: Check if file exists
+        if (!(await fs.pathExists(tasksPath))) {
+            return {
+                success: false,
+                error: `Tasks file not found: ${tasksPath}`,
+            };
+        }
+        // Create backup if requested
+        let backupPath = null;
+        if (createBackup) {
+            backupPath = `${tasksPath}.backup`;
+            try {
+                await fs.copyFile(tasksPath, backupPath);
+            }
+            catch (error) {
+                warnings.push('Failed to create backup file');
+            }
+        }
+        try {
+            // Read and validate task exists
+            const phases = await this.readTasksFile(tasksPath);
+            const task = this.validateTaskExists(phases, taskId);
+            if (!task) {
+                // Task not found - provide helpful error
+                const allTaskIds = phases.flatMap(p => p.tasks.map(t => t.id));
+                return {
+                    success: false,
+                    error: `Task ID "${taskId}" not found. Available task IDs:\n${allTaskIds.join('\n')}`,
+                };
+            }
+            // Check if already completed
+            if (task.completed) {
+                return {
+                    success: true,
+                    alreadyCompleted: true,
+                    warnings: [`Task "${taskId}" was already marked as completed`],
+                };
+            }
+            // Attempt to mark task completed
+            await this.markTaskCompleted(tasksPath, taskId);
+            // Post-validation: Verify the checkbox was actually changed
+            const verified = await this.verifyTaskMarked(tasksPath, taskId);
+            if (!verified) {
+                // Verification failed - attempt recovery if enabled
+                if (retryOnFailure && backupPath) {
+                    warnings.push('First attempt failed verification, retrying...');
+                    // Restore from backup and try again
+                    await fs.copyFile(backupPath, tasksPath);
+                    await this.markTaskCompleted(tasksPath, taskId);
+                    // Verify again
+                    const secondVerification = await this.verifyTaskMarked(tasksPath, taskId);
+                    if (!secondVerification) {
+                        // Still failed - restore backup and return error
+                        await fs.copyFile(backupPath, tasksPath);
+                        return {
+                            success: false,
+                            error: 'Failed to mark task as completed even after retry. File has been restored from backup.',
+                            warnings,
+                        };
+                    }
+                    warnings.push('Task marked successfully on retry');
+                }
+                else {
+                    // No retry - just fail
+                    return {
+                        success: false,
+                        error: 'Task completion verification failed',
+                        warnings,
+                    };
+                }
+            }
+            // Clean up backup on success
+            if (backupPath && await fs.pathExists(backupPath)) {
+                await fs.remove(backupPath);
+            }
+            return {
+                success: true,
+                warnings: warnings.length > 0 ? warnings : undefined,
+            };
+        }
+        catch (error) {
+            // Restore from backup if available
+            if (backupPath && await fs.pathExists(backupPath)) {
+                try {
+                    await fs.copyFile(backupPath, tasksPath);
+                    warnings.push('Restored tasks.md from backup due to error');
+                }
+                catch (restoreError) {
+                    warnings.push('Failed to restore from backup');
+                }
+            }
+            const errorMessage = error instanceof Error ? error.message : 'Unknown error';
+            return {
+                success: false,
+                error: `Error marking task as completed: ${errorMessage}`,
+                warnings: warnings.length > 0 ? warnings : undefined,
+            };
+        }
+    }
     /**
      * Get task completion statistics
      */