@sschepis/robodev 1.0.0

package/src/structured-dev/flow-manager.mjs

@@ -0,0 +1,321 @@
+// Flow Manager
+// Enforces the Discovery -> Interface -> Implementation loop
+// Validates transitions and interacts with the ManifestManager
+
+import { consoleStyler } from '../ui/console-styler.mjs';
+import { ProjectBootstrapper } from './project-bootstrapper.mjs';
+import fs from 'fs';
+import path from 'path';
+import { exec } from 'child_process';
+import util from 'util';
+
+const execPromise = util.promisify(exec);
+
+export class FlowManager {
+    constructor(manifestManager) {
+        this.manifestManager = manifestManager;
+    }
+
+    // Phases definition
+    static PHASES = {
+        DISCOVERY: 'Discovery',
+        DESIGN_REVIEW: 'Design Review',
+        INTERFACE: 'Interface',
+        IMPLEMENTATION: 'Implementation',
+        LOCKED: 'Locked'
+    };
+
+    // Initialize structured development
+    // If targetDir is provided and contains a design doc, bootstrap from it.
+    async initStructuredDev(targetDir = null) {
+        const dir = targetDir || this.manifestManager.workingDir;
+
+        // Attempt bootstrap from design document
+        const bootstrapper = new ProjectBootstrapper(this.manifestManager);
+        const bootstrapResult = await bootstrapper.bootstrap(dir);
+
+        if (bootstrapResult.bootstrapped) {
+            // Design file was found and manifest was pre-populated
+            const hooksResult = await this.initHooks();
+            return `${bootstrapResult.message}\n${hooksResult}`;
+        }
+
+        // No design file found or manifest already exists — fall back to default init
+        consoleStyler.log('system', bootstrapResult.message);
+        const manifestResult = await this.manifestManager.initManifest();
+        const hooksResult = await this.initHooks();
+        return `${manifestResult}\n${hooksResult}`;
+    }
+
+    // Initialize Default Hooks
+    async initHooks() {
+        const hooksDir = path.join(this.manifestManager.workingDir, '.ai-man');
+        const hooksPath = path.join(hooksDir, 'hooks.json.example');
+        
+        if (!fs.existsSync(hooksDir)) {
+            await fs.promises.mkdir(hooksDir, { recursive: true });
+        }
+
+        if (!fs.existsSync(hooksPath)) {
+            const defaultHooks = {
+                "on_lock": [
+                    { "command": "echo 'Locked feature: ${featureId}'" }
+                ],
+                "on_phase_change": [
+                    { "command": "echo 'Phase changed for ${featureId}'" }
+                ]
+            };
+            await fs.promises.writeFile(hooksPath, JSON.stringify(defaultHooks, null, 2), 'utf8');
+            return "Created .ai-man/hooks.json.example";
+        }
+        return "Hooks example already exists.";
+    }
+
+    // Submit a technical design (Phase I)
+    // Validates that the feature is in Discovery or new
+    async submitTechnicalDesign(featureId, designDoc) {
+        if (!this.manifestManager.hasManifest()) {
+            return "Error: No manifest found. Run init_structured_dev first.";
+        }
+
+        // Logic to validate design doc (placeholder for now)
+        if (!designDoc || designDoc.length < 50) {
+            return "Error: Design document is too short. Please provide a comprehensive technical design.";
+        }
+
+        // Update manifest: Move to Design Review phase
+        // In a real implementation, we might save the design doc to a file
+        await this.manifestManager.addFeature(featureId, "Unknown Feature", "Active", FlowManager.PHASES.DESIGN_REVIEW, "None");
+        
+        // Log snapshot
+        await this.manifestManager.updateSection('4. State Snapshots', `- [${new Date().toISOString()}] Design submitted for ${featureId}. Entering Design Review.`);
+
+        return `Technical design for ${featureId} submitted. Phase moved to ${FlowManager.PHASES.DESIGN_REVIEW}. Waiting for approval.`;
+    }
+
+    // Approve design (Phase I.5)
+    // Moves feature from Design Review to Interface
+    async approveDesign(featureId, feedback = "") {
+         if (!this.manifestManager.hasManifest()) {
+            return "Error: No manifest found.";
+        }
+
+        const manifest = await this.manifestManager.readManifest();
+        if (!manifest.includes(`| ${featureId}`)) {
+             return `Error: Feature ${featureId} not found.`;
+        }
+
+        // Simple check: Is it in Design Review?
+        // (For robustness, we should parse the table, but regex check is okay for now)
+        // We'll trust the manifest update to handle the transition correctly if we just set the new phase.
+        
+        await this.manifestManager.addFeature(featureId, "Unknown Feature", "Active", FlowManager.PHASES.INTERFACE, "None");
+        await this.manifestManager.updateSection('4. State Snapshots', `- [${new Date().toISOString()}] Design approved for ${featureId}. Feedback: ${feedback}`);
+        
+        return `Design for ${featureId} APPROVED. Phase moved to ${FlowManager.PHASES.INTERFACE}.`;
+    }
+
+
+    // Lock interfaces (Phase II)
+    // Validates that the feature is in Interface phase
+    async lockInterfaces(featureId, interfaceDefinitions) {
+         if (!this.manifestManager.hasManifest()) {
+            return "Error: No manifest found.";
+        }
+
+        // Verify feature state (simplified)
+        const manifest = await this.manifestManager.readManifest();
+        if (!manifest.includes(`| ${featureId}`)) {
+             // Implicitly allow if not strictly tracked yet, or fail. Let's auto-add for flexibility.
+             await this.manifestManager.addFeature(featureId, "Unknown Feature", "Active", FlowManager.PHASES.INTERFACE, "Partial");
+        }
+        
+        // Check if feature is in Design Review (Must initiate approval first)
+        // We need a more robust way to check phase than just string inclusion if we want to be strict.
+        // For now, if the manifest line contains "Design Review", we should block.
+        const featureRow = manifest.split('\n').find(line => line.includes(`| ${featureId} `));
+        if (featureRow) {
+            const cols = featureRow.split('|').map(c => c.trim());
+            // | ID | Name | Status | Phase | Lock | Priority | Dependencies |
+            // Index 4 is Phase
+            if (cols[4] === FlowManager.PHASES.DESIGN_REVIEW) {
+                return `Error: Feature ${featureId} is in Design Review. You must call 'approve_design' before locking interfaces.`;
+            }
+        }
+
+        // Automated Validation
+        const validationErrors = this.validateInterfaces(interfaceDefinitions);
+        if (validationErrors.length > 0) {
+            return `Error: Interface validation failed:\n- ${validationErrors.join('\n- ')}`;
+        }
+
+        // Logic to validate interfaces (e.g., check for .d.ts content)
+        if (!interfaceDefinitions.includes('interface') && !interfaceDefinitions.includes('type')) {
+             return "Error: No interface definitions found.";
+        }
+
+        // Update manifest
+        await this.manifestManager.addFeature(featureId, "Unknown Feature", "Active", FlowManager.PHASES.IMPLEMENTATION, "Interface");
+        
+        // Trigger hooks
+        await this.executeHooks('on_lock', { featureId });
+
+        return `Interfaces for ${featureId} LOCKED. Phase moved to ${FlowManager.PHASES.IMPLEMENTATION}.`;
+    }
+
+    validateInterfaces(definitions) {
+        const errors = [];
+        
+        // 1. Syntax Check
+        // We look for 'interface X' or 'type X =' patterns.
+        const interfaceMatch = definitions.match(/interface\s+(\w+)/g);
+        const typeMatch = definitions.match(/type\s+(\w+)\s*=/g);
+
+        if (!interfaceMatch && !typeMatch) {
+            errors.push("No 'interface' or 'type' definitions found.");
+        }
+
+        // 2. Strict JSDoc Check
+        // Ensure that EVERY interface or type is immediately preceded by a JSDoc comment.
+        // We'll iterate through lines to check this relationship.
+        const lines = definitions.split('\n');
+        let expectingDef = false;
+        
+        // This is a heuristic parser.
+        // A perfect parser would use the TypeScript compiler API, but that's heavy.
+        // We will scan for definitions and check if the previous non-empty lines constitute a JSDoc block.
+        
+        const definedTypes = [];
+        if (interfaceMatch) interfaceMatch.forEach(m => definedTypes.push(m.split(/\s+/)[1]));
+        if (typeMatch) typeMatch.forEach(m => definedTypes.push(m.split(/\s+/)[1]));
+
+        for (const typeName of definedTypes) {
+             // Find line index of definition
+             const defIndex = lines.findIndex(l => l.includes(`interface ${typeName}`) || l.includes(`type ${typeName}`));
+             if (defIndex === -1) continue;
+
+             // Look backwards for JSDoc end '*/'
+             let foundJSDoc = false;
+             for (let i = defIndex - 1; i >= 0; i--) {
+                 const line = lines[i].trim();
+                 if (line === '') continue; // Skip empty lines
+                 if (line.endsWith('*/')) {
+                     foundJSDoc = true;
+                     break;
+                 }
+                 // If we hit code or something else before '*/', then it's undocumented
+                 if (line.length > 0) break;
+             }
+
+             if (!foundJSDoc) {
+                 errors.push(`Missing JSDoc for '${typeName}'.`);
+             }
+        }
+
+        return errors;
+    }
+
+    // Submit critique (Phase III)
+    // Mandatory step before final implementation
+    async submitCritique(featureId, critique) {
+        if (!this.manifestManager.hasManifest()) {
+            return "Error: No manifest found.";
+        }
+
+        // Check for 3 flaws
+        const flaws = critique.match(/\d+\./g) || [];
+        if (flaws.length < 3) {
+            return "Error: Critique must identify at least 3 potential flaws.";
+        }
+
+        // Update manifest
+        await this.manifestManager.updateSection('4. State Snapshots', `- [${new Date().toISOString()}] Critique submitted for ${featureId}`);
+
+        return `Critique accepted for ${featureId}. You may proceed with final implementation.`;
+    }
+    
+    // Read the current manifest
+    async readManifest() {
+        return await this.manifestManager.readManifest();
+    }
+
+    // Visualize Architecture (Dependency Graph)
+    async visualizeArchitecture() {
+        if (!this.manifestManager.hasManifest()) {
+            return "Error: No manifest found.";
+        }
+        
+        const manifest = await this.manifestManager.readManifest();
+        const graphSection = manifest.match(/## 3. Dependency Graph([\s\S]*?)(?=##|$)/);
+        
+        if (!graphSection) {
+            return "graph TD;\nError[No Dependency Graph Section Found]";
+        }
+
+        // Parse section
+        const lines = graphSection[1].trim().split('\n');
+        let mermaid = "graph TD;\n";
+        
+        // Simple parser: "- A: Description" or "- A depends on B"
+        // Better: rely on Feature Registry Dependencies column
+        
+        const registrySection = manifest.match(/## 2. Feature Registry([\s\S]*?)(?=## 3|$)/);
+        if (registrySection) {
+            const rows = registrySection[1].trim().split('\n').filter(l => l.trim().startsWith('|') && !l.includes('Feature ID') && !l.includes('---'));
+            
+            for (const row of rows) {
+                const cols = row.split('|').map(c => c.trim());
+                // | ID | Name | Status | Phase | Lock | Priority | Dependencies |
+                // Index 1 = ID, 2 = Name, 7 = Dependencies
+                if (cols.length >= 8) {
+                    const id = cols[1];
+                    const name = cols[2];
+                    const deps = cols[7];
+                    
+                    mermaid += `    ${id}["${id}: ${name}"]\n`;
+                    
+                    if (deps && deps !== '-') {
+                        const depList = deps.split(',').map(d => d.trim());
+                        for (const dep of depList) {
+                            mermaid += `    ${dep} --> ${id}\n`;
+                        }
+                    }
+                }
+            }
+        }
+        
+        return mermaid;
+    }
+
+    // Execute External Hooks
+    async executeHooks(event, context) {
+        const hooksPath = path.join(this.manifestManager.workingDir, '.ai-man', 'hooks.json');
+        if (!fs.existsSync(hooksPath)) return; // No hooks configured
+
+        try {
+            const hooksConfig = JSON.parse(await fs.promises.readFile(hooksPath, 'utf8'));
+            const commands = hooksConfig[event];
+
+            if (commands && Array.isArray(commands)) {
+                for (const cmdObj of commands) {
+                    let cmd = cmdObj.command;
+                    // Interpolate context
+                    for (const [key, value] of Object.entries(context)) {
+                        cmd = cmd.replace(new RegExp(`\\$\{${key}\\}`, 'g'), value);
+                    }
+                    
+                    consoleStyler.log('system', `Executing hook: ${cmd}`);
+                    try {
+                        const { stdout, stderr } = await execPromise(cmd, { cwd: this.manifestManager.workingDir });
+                        if (stdout) console.log(`Hook Output: ${stdout}`);
+                        if (stderr) console.error(`Hook Error: ${stderr}`);
+                    } catch (e) {
+                         consoleStyler.log('error', `Hook failed: ${e.message}`);
+                    }
+                }
+            }
+        } catch (error) {
+             consoleStyler.log('error', `Failed to execute hooks: ${error.message}`);
+        }
+    }
+}

package/src/structured-dev/implementation-planner.mjs

@@ -0,0 +1,223 @@
+// Implementation Planner
+// Analyzes the System Map to generate a parallel execution plan for multi-agent implementation.
+
+import { ManifestManager } from './manifest-manager.mjs';
+import fs from 'fs';
+import path from 'path';
+
+export class ImplementationPlanner {
+    constructor(manifestManager) {
+        this.manifestManager = manifestManager;
+    }
+
+    // Main entry point to create a plan
+    async createExecutionPlan(outputFile = 'implementation-plan.json', numDevelopers = 3) {
+        if (!this.manifestManager.hasManifest()) {
+            return { success: false, message: "No manifest found. Run init_structured_dev first." };
+        }
+
+        const manifest = await this.manifestManager.readManifest();
+        const features = this.parseFeatureRegistry(manifest);
+        
+        if (features.length === 0) {
+            return { success: false, message: "No features found in the registry." };
+        }
+
+        try {
+            const stages = this.scheduleTasks(features, numDevelopers);
+            const plan = {
+                created_at: new Date().toISOString(),
+                num_developers: numDevelopers,
+                stages: stages
+            };
+
+            const planPath = path.join(this.manifestManager.workingDir, outputFile);
+            await fs.promises.writeFile(planPath, JSON.stringify(plan, null, 2), 'utf8');
+
+            return { 
+                success: true, 
+                message: `Execution plan created with ${stages.length} stages for ${numDevelopers} developers.`,
+                plan_path: planPath,
+                plan: plan 
+            };
+        } catch (error) {
+            return { success: false, message: `Failed to create plan: ${error.message}` };
+        }
+    }
+
+    // Parse the Feature Registry table from markdown
+    parseFeatureRegistry(manifestContent) {
+        const lines = manifestContent.split('\n');
+        const features = [];
+        const featureMap = new Map();
+        let inRegistry = false;
+
+        // 1. Parse Registry Table
+        for (const line of lines) {
+            if (line.includes('## 2. Feature Registry')) {
+                inRegistry = true;
+                continue;
+            }
+            if (inRegistry && line.startsWith('## ')) {
+                break; // End of section
+            }
+            
+            if (inRegistry && line.trim().startsWith('|') && !line.includes('Feature ID') && !line.includes('---')) {
+                const cols = line.split('|').map(c => c.trim());
+                if (cols.length >= 8) {
+                    const id = cols[1];
+                    const name = cols[2];
+                    const status = cols[3];
+                    const phase = cols[4];
+                    const priority = cols[6];
+                    const depsRaw = cols[7];
+                    
+                    const dependencies = (depsRaw === '-' || !depsRaw) 
+                        ? [] 
+                        : depsRaw.split(',').map(d => d.trim());
+
+                    const feature = {
+                        id,
+                        name,
+                        status,
+                        phase,
+                        priority,
+                        dependencies
+                    };
+                    features.push(feature);
+                    featureMap.set(id, feature);
+                }
+            }
+        }
+
+        // 2. Parse Dependency Graph Section
+        // Syntax: - FEAT-A -> FEAT-B, FEAT-C (Meaning A is a dependency for B and C)
+        const graphRegex = /-\s*([A-Za-z0-9-]+)\s*->\s*(.+)/;
+        let inGraph = false;
+
+        for (const line of lines) {
+            if (line.includes('## 3. Dependency Graph')) {
+                inGraph = true;
+                continue;
+            }
+            if (inGraph && line.startsWith('## ')) {
+                break;
+            }
+
+            if (inGraph) {
+                const match = line.match(graphRegex);
+                if (match) {
+                    const prerequisite = match[1].trim();
+                    const dependents = match[2].split(',').map(d => d.trim());
+
+                    dependents.forEach(depId => {
+                        const feature = featureMap.get(depId);
+                        if (feature) {
+                            if (!feature.dependencies.includes(prerequisite)) {
+                                feature.dependencies.push(prerequisite);
+                            }
+                        }
+                    });
+                }
+            }
+        }
+
+        return features;
+    }
+
+    // Schedule tasks into parallel stages using topological sort logic with resource constraints
+    scheduleTasks(features, numDevelopers = 3) {
+        const pendingFeatures = features.filter(f => f.status !== 'Completed');
+        const completedFeatureIds = new Set(features.filter(f => f.status === 'Completed').map(f => f.id));
+        
+        // Build adjacency list and in-degree map for pending tasks
+        const graph = new Map(); // id -> [dependents]
+        const inDegree = new Map(); // id -> count of pending dependencies
+        const featureMap = new Map(); // id -> feature object
+
+        // Initialize
+        pendingFeatures.forEach(f => {
+            featureMap.set(f.id, f);
+            inDegree.set(f.id, 0);
+            if (!graph.has(f.id)) graph.set(f.id, []);
+        });
+
+        // Populate graph based on dependencies
+        pendingFeatures.forEach(feature => {
+            feature.dependencies.forEach(depId => {
+                // If dependency is already completed, it doesn't block
+                if (completedFeatureIds.has(depId)) return;
+
+                // If dependency is pending, add edge
+                if (featureMap.has(depId)) {
+                    if (!graph.has(depId)) graph.set(depId, []);
+                    graph.get(depId).push(feature.id);
+                    inDegree.set(feature.id, (inDegree.get(feature.id) || 0) + 1);
+                } else {
+                    // Dependency exists but not in our list (external or typo)
+                    // We should treat this as a potential blocker or at least warn.
+                    // For robustness, we'll log it but not block, assuming manual resolution or external dependency.
+                    console.warn(`[ImplementationPlanner] Warning: Feature ${feature.id} depends on unknown/missing feature ${depId}. Ignoring dependency.`);
+                }
+            });
+        });
+
+        const stages = [];
+        let readyQueue = [];
+
+        // Initial set of ready tasks (in-degree 0)
+        inDegree.forEach((count, id) => {
+            if (count === 0) readyQueue.push(id);
+        });
+
+        // Simple List Scheduling Algorithm
+        // While we have tasks to schedule
+        while (readyQueue.length > 0) {
+            // Take up to numDevelopers tasks for this stage
+            // We sort by number of dependents (heuristic: prioritize tasks that unlock more work)
+            readyQueue.sort((a, b) => {
+                const depsA = graph.get(a)?.length || 0;
+                const depsB = graph.get(b)?.length || 0;
+                return depsB - depsA; // Descending
+            });
+
+            const currentStageTasks = readyQueue.splice(0, numDevelopers);
+            
+            // Map IDs to full feature objects for the plan
+            const stageTasksWithDetails = currentStageTasks.map(id => featureMap.get(id));
+
+            stages.push({
+                id: stages.length + 1,
+                tasks: stageTasksWithDetails
+            });
+
+            // Simulate completion of these tasks to find new ready tasks
+            const nextReady = [];
+            
+            for (const completedId of currentStageTasks) {
+                const dependents = graph.get(completedId) || [];
+                for (const dependentId of dependents) {
+                    inDegree.set(dependentId, inDegree.get(dependentId) - 1);
+                    if (inDegree.get(dependentId) === 0) {
+                        nextReady.push(dependentId);
+                    }
+                }
+            }
+
+            // Add newly ready tasks to the queue
+            readyQueue.push(...nextReady);
+        }
+
+        // Check for cycles (remaining in-degrees > 0)
+        const unscheduled = [];
+        inDegree.forEach((count, id) => {
+            if (count > 0) unscheduled.push(id);
+        });
+
+        if (unscheduled.length > 0) {
+            throw new Error(`Cyclic dependency or unresolvable dependencies detected for features: ${unscheduled.join(', ')}`);
+        }
+
+        return stages;
+    }
+}