@sugar-crash-studios/vibe-forge 0.4.0

package/bin/dashboard/api/dispatch.js

@@ -0,0 +1,483 @@
+/**
+ * Dispatch API - Create task files for agent execution
+ *
+ * This is the key feature that transforms the dashboard from a viewer
+ * into a command center. Users can click dispatch buttons to create
+ * task files that agents will pick up.
+ *
+ * Endpoint:
+ *   POST /api/dispatch - Create and dispatch a task
+ *
+ * Request body:
+ *   {
+ *     "type": "stale-docs",           // Issue type
+ *     "target": "README.md",          // Target file/resource
+ *     "agent": "scribe",              // Suggested agent
+ *     "context": { ... }              // Additional context
+ *   }
+ */
+
+const fs = require('fs');
+const path = require('path');
+const tasksApi = require('./tasks');
+
+// Dispatch type configurations
+const DISPATCH_TYPES = {
+    'stale-docs': {
+        prefix: 'DOC',
+        priority: 'medium',
+        suggestedAgent: 'scribe',
+        titleTemplate: (target) => `Update stale documentation: ${target}`,
+        descriptionTemplate: (target, context) =>
+            `The file "${target}" has not been updated in ${context.daysSinceUpdate || 'many'} days and may contain outdated information.`,
+        acceptanceCriteria: [
+            'Documentation reviewed and updated',
+            'All code references are accurate',
+            'Examples are current and working'
+        ]
+    },
+    'failing-test': {
+        prefix: 'TEST',
+        priority: 'high',
+        suggestedAgent: 'crucible',
+        titleTemplate: (target) => `Fix failing test: ${target}`,
+        descriptionTemplate: (target, context) =>
+            `Test file "${target}" has ${context.failureCount || 'some'} failing test(s). Error: ${context.error || 'Unknown'}`,
+        acceptanceCriteria: [
+            'All tests passing',
+            'No test skips introduced',
+            'Root cause addressed'
+        ]
+    },
+    'security-issue': {
+        prefix: 'SEC',
+        priority: 'critical',
+        suggestedAgent: 'aegis',
+        titleTemplate: (target) => `Security issue: ${target}`,
+        descriptionTemplate: (target, context) =>
+            `Security vulnerability detected: ${context.vulnerability || target}. Severity: ${context.severity || 'unknown'}`,
+        acceptanceCriteria: [
+            'Vulnerability patched',
+            'No regressions introduced',
+            'Security tests added if applicable'
+        ]
+    },
+    'low-coverage': {
+        prefix: 'COV',
+        priority: 'medium',
+        suggestedAgent: 'crucible',
+        titleTemplate: (target) => `Improve test coverage: ${target}`,
+        descriptionTemplate: (target, context) =>
+            `File "${target}" has low test coverage (${context.coverage || '<50'}%). Add tests to improve coverage.`,
+        acceptanceCriteria: [
+            'Coverage improved to acceptable threshold',
+            'Critical paths covered',
+            'Edge cases tested'
+        ]
+    },
+    'todo-fixme': {
+        prefix: 'TODO',
+        priority: 'low',
+        suggestedAgent: null, // Auto-assign based on file type
+        titleTemplate: (target) => `Address TODO/FIXME: ${target}`,
+        descriptionTemplate: (target, context) =>
+            `TODO/FIXME marker found in "${target}": ${context.marker || 'Review and address'}`,
+        acceptanceCriteria: [
+            'TODO/FIXME addressed or documented',
+            'Code improved as needed',
+            'Marker removed if resolved'
+        ]
+    },
+    'pending-review': {
+        prefix: 'REV',
+        priority: 'high',
+        suggestedAgent: 'temper',
+        titleTemplate: (target) => `Review pending: ${target}`,
+        descriptionTemplate: (target, context) =>
+            `PR #${context.prNumber || target} has been waiting for review for ${context.hoursWaiting || 'many'} hours.`,
+        acceptanceCriteria: [
+            'PR reviewed',
+            'Feedback provided',
+            'Approval or changes requested'
+        ]
+    },
+    'custom': {
+        prefix: 'TASK',
+        priority: 'medium',
+        suggestedAgent: null,
+        titleTemplate: (target) => target, // Use target as title
+        descriptionTemplate: (target, context) =>
+            context.description || 'Custom task dispatched from dashboard.',
+        acceptanceCriteria: [
+            'Task completed as specified'
+        ]
+    }
+};
+
+/**
+ * Generate unique dispatch task ID
+ * @param {string} prefix - ID prefix
+ * @returns {string} Task ID
+ */
+function generateDispatchId(prefix) {
+    const now = new Date();
+    const seq = Math.floor(Math.random() * 1000).toString().padStart(3, '0');
+    return `${prefix}-${now.toISOString().slice(0, 10).replace(/-/g, '')}-${seq}`;
+}
+
+/**
+ * Determine agent based on file type
+ * @param {string} target - Target file path
+ * @returns {string|null} Suggested agent
+ */
+function suggestAgentForFile(target) {
+    if (!target) return null;
+
+    const ext = path.extname(target).toLowerCase();
+    const dir = path.dirname(target).toLowerCase();
+
+    // Backend files
+    if (dir.includes('/api/') || dir.includes('/services/') ||
+        dir.includes('/models/') || dir.includes('/middleware/')) {
+        return 'furnace';
+    }
+
+    // Frontend files
+    if (dir.includes('/components/') || dir.includes('/pages/') ||
+        dir.includes('/ui/') || ext === '.tsx' || ext === '.jsx') {
+        return 'anvil';
+    }
+
+    // Test files
+    if (target.includes('.test.') || target.includes('.spec.') ||
+        dir.includes('/test')) {
+        return 'crucible';
+    }
+
+    // Documentation
+    if (ext === '.md' || dir.includes('/docs/')) {
+        return 'scribe';
+    }
+
+    // Security-related
+    if (target.includes('auth') || target.includes('security') ||
+        target.includes('permission')) {
+        return 'aegis';
+    }
+
+    // Style files
+    if (ext === '.css' || ext === '.scss' || ext === '.less') {
+        return 'pixel';
+    }
+
+    return null;
+}
+
+const MAX_TARGET_LENGTH = 500
+const MAX_TITLE_LENGTH = 200
+const MAX_CONTEXT_STRING_LENGTH = 10_000
+const AGENT_ID_PATTERN = /^[a-z0-9_-]+$/
+
+/**
+ * Validate dispatch request
+ * @param {Object} data - Request data
+ * @returns {Object} Validation result
+ */
+function validateDispatchRequest(data) {
+    const errors = [];
+
+    if (!data.type) {
+        errors.push('type is required');
+    } else if (!DISPATCH_TYPES[data.type]) {
+        errors.push(`unknown type: ${data.type}. Valid types: ${Object.keys(DISPATCH_TYPES).join(', ')}`);
+    }
+
+    if (!data.target && data.type !== 'custom') {
+        errors.push('target is required');
+    } else if (data.target) {
+        if (typeof data.target !== 'string') {
+            errors.push('target must be a string');
+        } else if (data.target.length > MAX_TARGET_LENGTH) {
+            errors.push(`target too long (max ${MAX_TARGET_LENGTH} chars)`);
+        }
+    }
+
+    if (data.title && data.title.length > MAX_TITLE_LENGTH) {
+        errors.push(`title too long (max ${MAX_TITLE_LENGTH} chars)`);
+    }
+
+    if (data.agent) {
+        if (typeof data.agent !== 'string') {
+            errors.push('agent must be a string');
+        } else if (!AGENT_ID_PATTERN.test(data.agent)) {
+            errors.push('agent must contain only lowercase letters, numbers, underscores, and hyphens');
+        }
+    }
+
+    if (data.context) {
+        if (typeof data.context !== 'object' || Array.isArray(data.context)) {
+            errors.push('context must be an object');
+        } else {
+            // Limit total serialized context size to prevent oversized payloads
+            const contextSize = JSON.stringify(data.context).length;
+            if (contextSize > MAX_CONTEXT_STRING_LENGTH) {
+                errors.push(`context too large (${contextSize} chars serialized, max ${MAX_CONTEXT_STRING_LENGTH})`);
+            }
+        }
+    }
+
+    return {
+        valid: errors.length === 0,
+        errors
+    };
+}
+
+/**
+ * Dispatch a task
+ * @param {string} projectRoot - Project root directory
+ * @param {Object} data - Dispatch request data
+ * @param {Function} broadcast - WebSocket broadcast function
+ * @returns {Object} Created task
+ */
+// Sentinel error type so the server can distinguish validation (400) from runtime (500)
+class DispatchValidationError extends Error {
+    constructor(errors) {
+        super(`Invalid dispatch request: ${errors.join(', ')}`)
+        this.name = 'DispatchValidationError'
+        this.errors = errors
+        this.statusCode = 400
+    }
+}
+
+async function dispatch(projectRoot, data, broadcast) {
+    // Validate request — throws DispatchValidationError (400) on failure
+    const validation = validateDispatchRequest(data);
+    if (!validation.valid) {
+        throw new DispatchValidationError(validation.errors);
+    }
+
+    const dispatchType = DISPATCH_TYPES[data.type];
+
+    // Sanitize context strings: strip any markdown frontmatter (prevents injecting fake task metadata)
+    const rawContext = data.context || {};
+    const context = Object.fromEntries(
+        Object.entries(rawContext).map(([k, v]) => [
+            k,
+            typeof v === 'string' ? v.replace(/^---[\s\S]*?---\n?/, '').trim() : v
+        ])
+    );
+
+    // Determine agent
+    let agent = data.agent || dispatchType.suggestedAgent;
+    if (!agent) {
+        agent = suggestAgentForFile(data.target);
+    }
+
+    // Generate task ID
+    const taskId = generateDispatchId(dispatchType.prefix);
+
+    // Build task title and description
+    const title = data.title || dispatchType.titleTemplate(data.target);
+    const description = dispatchType.descriptionTemplate(data.target, context);
+
+    // Build acceptance criteria
+    const criteria = data.acceptanceCriteria || dispatchType.acceptanceCriteria;
+
+    // Create task content
+    const taskData = {
+        id: taskId,
+        title: title,
+        type: mapDispatchTypeToTaskType(data.type),
+        priority: data.priority || dispatchType.priority,
+        assignedTo: agent,
+        createdBy: 'dashboard-dispatch',
+        summary: description,
+        context: buildContextSection(data, context)
+    };
+
+    // Build full task file content
+    const tasksDir = path.join(projectRoot, 'tasks', 'pending');
+    const slug = title
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-|-$/g, '')
+        .substring(0, 50);
+
+    const filename = `${taskId}-${slug}.md`;
+    const filePath = path.join(tasksDir, filename);
+
+    const now = new Date().toISOString();
+    const content = `---
+id: ${taskId}
+title: "${title.replace(/"/g, '\\"')}"
+type: ${taskData.type}
+priority: ${taskData.priority}
+status: pending
+created_at: ${now}
+created_by: dashboard-dispatch
+assigned_to: ${agent || 'null'}
+dispatch_type: ${data.type}
+---
+
+# ${title}
+
+## Summary
+
+${description}
+
+## Context
+
+${buildContextSection(data, context)}
+
+## Target
+
+${data.target ? `- File/Resource: \`${data.target}\`` : '- No specific target'}
+
+## Acceptance Criteria
+
+${criteria.map(c => `- [ ] ${c}`).join('\n')}
+
+## Dispatch Info
+
+- **Dispatched via:** Dashboard Web UI
+- **Dispatch type:** ${data.type}
+- **Suggested agent:** ${agent || 'auto-assign'}
+- **Timestamp:** ${now}
+`;
+
+    // Ensure directory exists
+    if (!fs.existsSync(tasksDir)) {
+        fs.mkdirSync(tasksDir, { recursive: true });
+    }
+
+    // Write task file
+    fs.writeFileSync(filePath, content, 'utf8');
+
+    console.log(`[Dispatch] Created task: ${filename}`);
+
+    // Read back the created task
+    const createdTask = tasksApi.readTaskFile(filePath);
+
+    // Broadcast task creation
+    if (broadcast) {
+        broadcast({
+            type: 'task-created',
+            task: createdTask,
+            dispatch: {
+                type: data.type,
+                target: data.target,
+                agent: agent
+            }
+        });
+    }
+
+    return {
+        success: true,
+        task: createdTask,
+        file: filename,
+        dispatchType: data.type,
+        suggestedAgent: agent
+    };
+}
+
+/**
+ * Map dispatch type to task type
+ * @param {string} dispatchType - Dispatch type
+ * @returns {string} Task type
+ */
+function mapDispatchTypeToTaskType(dispatchType) {
+    const typeMap = {
+        'stale-docs': 'documentation',
+        'failing-test': 'bug',
+        'security-issue': 'security',
+        'low-coverage': 'test',
+        'todo-fixme': 'improvement',
+        'pending-review': 'review',
+        'custom': 'task'
+    };
+    return typeMap[dispatchType] || 'task';
+}
+
+/**
+ * Build context section for task
+ * @param {Object} data - Dispatch data
+ * @param {Object} context - Additional context
+ * @returns {string} Context section content
+ */
+function buildContextSection(data, context) {
+    const lines = [];
+
+    if (data.type === 'stale-docs') {
+        lines.push(`This documentation has not been updated recently.`);
+        if (context.lastUpdated) {
+            lines.push(`Last updated: ${context.lastUpdated}`);
+        }
+        if (context.daysSinceUpdate) {
+            lines.push(`Days since update: ${context.daysSinceUpdate}`);
+        }
+    }
+
+    if (data.type === 'failing-test') {
+        lines.push(`Test failure detected during automated testing.`);
+        if (context.error) {
+            lines.push(`\nError message:\n\`\`\`\n${context.error}\n\`\`\``);
+        }
+        if (context.failureCount) {
+            lines.push(`Failure count: ${context.failureCount}`);
+        }
+    }
+
+    if (data.type === 'security-issue') {
+        lines.push(`Security issue detected.`);
+        if (context.vulnerability) {
+            lines.push(`Vulnerability: ${context.vulnerability}`);
+        }
+        if (context.severity) {
+            lines.push(`Severity: ${context.severity}`);
+        }
+        if (context.cve) {
+            lines.push(`CVE: ${context.cve}`);
+        }
+    }
+
+    if (data.type === 'low-coverage') {
+        lines.push(`Code coverage is below acceptable threshold.`);
+        if (context.coverage) {
+            lines.push(`Current coverage: ${context.coverage}%`);
+        }
+        if (context.threshold) {
+            lines.push(`Required threshold: ${context.threshold}%`);
+        }
+    }
+
+    if (context.reason) {
+        lines.push(`\nReason: ${context.reason}`);
+    }
+
+    if (context.notes) {
+        lines.push(`\nNotes: ${context.notes}`);
+    }
+
+    return lines.length > 0 ? lines.join('\n') : 'Dispatched from dashboard.';
+}
+
+/**
+ * Get available dispatch types
+ * @returns {Object} Dispatch type configurations
+ */
+function getDispatchTypes() {
+    return Object.entries(DISPATCH_TYPES).map(([key, config]) => ({
+        type: key,
+        prefix: config.prefix,
+        priority: config.priority,
+        suggestedAgent: config.suggestedAgent
+    }));
+}
+
+module.exports = {
+    dispatch,
+    getDispatchTypes,
+    validateDispatchRequest,
+    DispatchValidationError,
+    DISPATCH_TYPES
+};