tachibot-mcp 2.0.2

package/dist/src/validators/interpolation-validator.js

@@ -0,0 +1,222 @@
+/**
+ * Interpolation validator - validates ${...} references in workflow
+ */
+export class InterpolationValidator {
+    constructor() {
+        // Matches ${anything} patterns
+        this.interpolationRegex = /\$\{([^}]+)\}/g;
+    }
+    validate(context) {
+        const errors = [];
+        // Build step index for quick lookup
+        const stepNames = new Set(context.workflow.steps.map(s => s.name));
+        const stepOrder = new Map(context.workflow.steps.map((s, i) => [s.name, i]));
+        // Build list of step output variables
+        const stepOutputVars = new Set();
+        context.workflow.steps.forEach(step => {
+            if (step.output?.variable) {
+                stepOutputVars.add(step.output.variable);
+            }
+        });
+        // Add runtime variables that are always available
+        const runtimeVars = ['input', 'timestamp', 'query'];
+        // Validate each step's interpolations
+        context.workflow.steps.forEach((step, index) => {
+            this.validateStepInterpolations(step, index, stepNames, stepOrder, context, errors, stepOutputVars, runtimeVars);
+        });
+        // Validate output interpolations if present
+        if (context.workflow.output?.saveToFile && typeof context.workflow.output.saveToFile === 'string') {
+            const allVars = [
+                ...Array.from(stepOutputVars),
+                ...runtimeVars,
+                ...(context.workflow.variables ? Object.keys(context.workflow.variables) : [])
+            ];
+            this.validateStringInterpolations(context.workflow.output.saveToFile, stepNames, allVars, '$.output.saveToFile', errors, stepOrder.size // All steps are valid for output
+            );
+        }
+        return errors;
+    }
+    validateStepInterpolations(step, stepIndex, stepNames, stepOrder, context, errors, stepOutputVars, runtimeVars) {
+        // Collect all available variables at this point
+        const availableVars = [
+            ...Array.from(stepOutputVars),
+            ...runtimeVars,
+            ...(context.workflow.variables ? Object.keys(context.workflow.variables) : [])
+        ];
+        // Validate input field interpolations
+        if (step.input) {
+            const inputStr = JSON.stringify(step.input);
+            this.validateStringInterpolations(inputStr, stepNames, availableVars, `$.steps[${stepIndex}].input`, errors, stepIndex, stepOrder);
+        }
+        // Validate 'when' condition interpolations
+        if (step.when) {
+            this.validateStringInterpolations(step.when, stepNames, availableVars, `$.steps[${stepIndex}].when`, errors, stepIndex, stepOrder);
+        }
+        // Validate loadFiles references
+        if (step.loadFiles && Array.isArray(step.loadFiles)) {
+            step.loadFiles.forEach((fileRef, idx) => {
+                if (!stepNames.has(fileRef)) {
+                    errors.push({
+                        type: 'interpolation',
+                        severity: 'error',
+                        message: `loadFiles references unknown step '${fileRef}'`,
+                        path: `$.steps[${stepIndex}].loadFiles[${idx}]`,
+                        suggestion: `Ensure step '${fileRef}' is defined and has saveToFile: true`
+                    });
+                }
+                else if (stepOrder.get(fileRef) >= stepIndex) {
+                    errors.push({
+                        type: 'interpolation',
+                        severity: 'error',
+                        message: `loadFiles references step '${fileRef}' that comes after current step`,
+                        path: `$.steps[${stepIndex}].loadFiles[${idx}]`,
+                        suggestion: 'Can only load files from previous steps'
+                    });
+                }
+                else {
+                    // Check for redundancy: is this loadFiles unnecessary?
+                    const referencedStep = context.workflow.steps.find(s => s.name === fileRef);
+                    if (referencedStep?.output?.variable) {
+                        const varName = referencedStep.output.variable;
+                        const inputStr = step.input ? JSON.stringify(step.input) : '';
+                        if (inputStr.includes(`\${${varName}}`)) {
+                            errors.push({
+                                type: 'redundancy',
+                                severity: 'warning',
+                                message: `loadFiles includes '${fileRef}' but its output variable '\${${varName}}' is already used in input`,
+                                path: `$.steps[${stepIndex}].loadFiles[${idx}]`,
+                                suggestion: `Remove '${fileRef}' from loadFiles - data is already in memory from previous step`
+                            });
+                        }
+                    }
+                }
+            });
+        }
+        // Validate dependsOn references
+        if (step.dependsOn && Array.isArray(step.dependsOn)) {
+            step.dependsOn.forEach((depName, idx) => {
+                if (!stepNames.has(depName)) {
+                    errors.push({
+                        type: 'interpolation',
+                        severity: 'error',
+                        message: `dependsOn references unknown step '${depName}'`,
+                        path: `$.steps[${stepIndex}].dependsOn[${idx}]`,
+                        suggestion: `Ensure step '${depName}' is defined`
+                    });
+                }
+                else if (stepOrder.get(depName) >= stepIndex) {
+                    errors.push({
+                        type: 'interpolation',
+                        severity: 'error',
+                        message: `dependsOn references step '${depName}' that comes after current step`,
+                        path: `$.steps[${stepIndex}].dependsOn[${idx}]`,
+                        suggestion: 'Dependencies must come before dependent steps'
+                    });
+                }
+            });
+        }
+    }
+    validateStringInterpolations(content, stepNames, variables, path, errors, currentStepIndex, stepOrder) {
+        const matches = content.matchAll(this.interpolationRegex);
+        for (const match of matches) {
+            const fullMatch = match[0]; // e.g., "${step1.output}"
+            const reference = match[1]; // e.g., "step1.output"
+            this.validateSingleReference(reference, fullMatch, stepNames, variables, path, errors, currentStepIndex, stepOrder);
+        }
+    }
+    validateSingleReference(reference, fullMatch, stepNames, variables, path, errors, currentStepIndex, stepOrder) {
+        // Check for step output reference: step_name.output or step_name.something
+        if (reference.includes('.')) {
+            const parts = reference.split('.');
+            const stepName = parts[0];
+            const property = parts.slice(1).join('.');
+            // Validate step exists
+            if (!stepNames.has(stepName)) {
+                errors.push({
+                    type: 'interpolation',
+                    severity: 'error',
+                    message: `Reference '${fullMatch}' points to undefined step '${stepName}'`,
+                    path,
+                    suggestion: `Define step '${stepName}' or correct the reference`
+                });
+                return;
+            }
+            // Validate step order (if applicable)
+            if (currentStepIndex !== undefined && stepOrder) {
+                const refStepIndex = stepOrder.get(stepName);
+                if (refStepIndex !== undefined && refStepIndex >= currentStepIndex) {
+                    errors.push({
+                        type: 'interpolation',
+                        severity: 'error',
+                        message: `Reference '${fullMatch}' points to step '${stepName}' which appears later in the workflow`,
+                        path,
+                        suggestion: `Move step '${stepName}' before the current step, or remove the reference`
+                    });
+                }
+            }
+            // Validate property name - accept 'output' as valid
+            if (!property || property.trim() === '') {
+                errors.push({
+                    type: 'interpolation',
+                    severity: 'warning',
+                    message: `Reference '${fullMatch}' is missing property after '${stepName}.'`,
+                    path,
+                    suggestion: 'Common properties: output, result, data'
+                });
+            }
+            else if (property !== 'output') {
+                // Warn if using non-standard property (not 'output')
+                errors.push({
+                    type: 'interpolation',
+                    severity: 'warning',
+                    message: `Reference '${fullMatch}' uses property '${property}' - only '.output' is guaranteed to exist`,
+                    path,
+                    suggestion: `Use '\${${stepName}.output}' for step outputs, or '\${${stepName}}' for direct reference`
+                });
+            }
+            // else property === 'output' → Valid, no error
+        }
+        // Variable reference (no dot)
+        else {
+            // Check if this is a direct step reference (valid - runtime supports this)
+            if (stepNames.has(reference)) {
+                // ✅ VALID: Direct step reference like ${step-name}
+                // Runtime will use the step's output
+                // Validate step order (if applicable)
+                if (currentStepIndex !== undefined && stepOrder) {
+                    const refStepIndex = stepOrder.get(reference);
+                    if (refStepIndex !== undefined && refStepIndex >= currentStepIndex) {
+                        errors.push({
+                            type: 'interpolation',
+                            severity: 'error',
+                            message: `Reference '${fullMatch}' points to step '${reference}' which appears later in the workflow`,
+                            path,
+                            suggestion: `Move step '${reference}' before the current step`
+                        });
+                    }
+                }
+                return; // Valid step reference, no error
+            }
+            // Check variable name format
+            if (!/^[a-z][a-z0-9_]*$/.test(reference)) {
+                errors.push({
+                    type: 'interpolation',
+                    severity: 'warning',
+                    message: `Variable reference '${fullMatch}' should use snake_case`,
+                    path,
+                    suggestion: 'Use lowercase with underscores, e.g., "${my_variable}"'
+                });
+            }
+            // Check if variable is defined
+            if (!variables.includes(reference)) {
+                errors.push({
+                    type: 'interpolation',
+                    severity: 'error',
+                    message: `Reference '${fullMatch}' points to undefined variable '${reference}'`,
+                    path,
+                    suggestion: 'Define the variable in the workflow variables section'
+                });
+            }
+        }
+    }
+}

package/dist/src/validators/output-usage-validator.js

@@ -0,0 +1,151 @@
+/**
+ * Output usage validator - detects unused step outputs
+ * Ensures every step's output is consumed (unless it's final, parallel, or explicitly saved)
+ */
+export class OutputUsageValidator {
+    constructor() {
+        this.interpolationRegex = /\$\{([^}]+)\}/g;
+    }
+    validate(context) {
+        const errors = [];
+        const steps = context.workflow.steps;
+        if (steps.length === 0)
+            return errors;
+        // Build usage maps
+        const interpolationUsage = this.buildInterpolationUsageMap(steps);
+        const fileUsage = this.buildFileUsageMap(steps);
+        // Check each step (except last)
+        steps.forEach((step, index) => {
+            const isLast = index === steps.length - 1;
+            // Skip validation for special cases
+            if (isLast)
+                return; // Final step output is always "used"
+            if (step.parallel === true)
+                return; // Parallel steps are side effects
+            const stepName = step.name;
+            const usedViaInterpolation = interpolationUsage.has(stepName);
+            const usedViaFile = fileUsage.has(stepName);
+            const hasSaveToFile = step.saveToFile === true;
+            // Case 1: Not used at all → ERROR
+            if (!usedViaInterpolation && !usedViaFile) {
+                errors.push({
+                    type: 'output-usage',
+                    severity: 'error',
+                    message: `Step '${stepName}' produces output but nothing uses it`,
+                    path: `$.steps[${index}]`,
+                    suggestion: hasSaveToFile
+                        ? `Add 'loadFiles: ["${stepName}"]' to a later step, or remove 'saveToFile'`
+                        : `Either:\n      - Remove this step to save cost\n      - Reference it in a later step: \${${stepName}}\n      - Add 'saveToFile: true' and load it later`
+                });
+            }
+            // Case 2: Saved to file but never loaded → WARNING
+            else if (hasSaveToFile && !usedViaFile) {
+                errors.push({
+                    type: 'output-usage',
+                    severity: 'warning',
+                    message: `Step '${stepName}' saves output to file but no step loads it`,
+                    path: `$.steps[${index}]`,
+                    suggestion: usedViaInterpolation
+                        ? `File is saved but unused. Consider removing 'saveToFile: true' to save disk space`
+                        : `Add 'loadFiles: ["${stepName}"]' to a later step, or remove 'saveToFile'`
+                });
+            }
+            // Case 3: Only used via file (not interpolated) → INFO
+            else if (usedViaFile && !usedViaInterpolation && hasSaveToFile) {
+                // This is actually fine - file-based workflows are intentional
+                // Only warn if output is large (can't determine here, so skip)
+            }
+        });
+        return errors;
+    }
+    /**
+     * Build map of which steps are referenced via ${step-name} or ${variable} interpolation
+     */
+    buildInterpolationUsageMap(steps) {
+        const used = new Set();
+        // Build map of variable names to step names
+        const varToStep = new Map();
+        steps.forEach(step => {
+            if (step.output?.variable) {
+                varToStep.set(step.output.variable, step.name);
+                console.error(`[DEBUG] Mapped variable '${step.output.variable}' → step '${step.name}'`);
+            }
+        });
+        console.error(`[DEBUG] varToStep has ${varToStep.size} entries`);
+        steps.forEach((step) => {
+            // Check input field
+            if (step.input) {
+                const inputStr = JSON.stringify(step.input);
+                const matches = inputStr.matchAll(this.interpolationRegex);
+                for (const match of matches) {
+                    const reference = match[1]; // e.g., "step-name", "step-name.output", or "variable_name"
+                    // Extract step name (remove .output suffix if present)
+                    const stepName = reference.includes('.')
+                        ? reference.split('.')[0]
+                        : reference;
+                    // Check if it's a direct step reference
+                    if (steps.some(s => s.name === stepName)) {
+                        console.error(`[DEBUG] Found step reference: ${stepName}`);
+                        used.add(stepName);
+                    }
+                    // Check if it's a variable name that maps to a step
+                    else if (varToStep.has(reference)) {
+                        const mappedStep = varToStep.get(reference);
+                        console.error(`[DEBUG] Found variable reference: ${reference} → ${mappedStep}`);
+                        used.add(mappedStep);
+                    }
+                    else {
+                        console.error(`[DEBUG] Unknown reference: ${reference}`);
+                    }
+                }
+            }
+            // Check 'when' condition
+            if (step.when) {
+                const matches = step.when.matchAll(this.interpolationRegex);
+                for (const match of matches) {
+                    const reference = match[1];
+                    const stepName = reference.includes('.')
+                        ? reference.split('.')[0]
+                        : reference;
+                    if (steps.some(s => s.name === stepName)) {
+                        used.add(stepName);
+                    }
+                    else if (varToStep.has(reference)) {
+                        used.add(varToStep.get(reference));
+                    }
+                }
+            }
+            // Check condition.if field
+            if (step.condition?.if) {
+                const matches = step.condition.if.matchAll(this.interpolationRegex);
+                for (const match of matches) {
+                    const reference = match[1];
+                    const stepName = reference.includes('.')
+                        ? reference.split('.')[0]
+                        : reference;
+                    if (steps.some(s => s.name === stepName)) {
+                        used.add(stepName);
+                    }
+                    else if (varToStep.has(reference)) {
+                        used.add(varToStep.get(reference));
+                    }
+                }
+            }
+        });
+        return used;
+    }
+    /**
+     * Build map of which steps are loaded via loadFiles
+     */
+    buildFileUsageMap(steps) {
+        const used = new Set();
+        steps.forEach((step) => {
+            if (step.loadFiles && Array.isArray(step.loadFiles)) {
+                step.loadFiles.forEach((fileRef) => {
+                    used.add(fileRef);
+                });
+            }
+        });
+        return used;
+    }
+}

package/dist/src/validators/syntax-validator.js

@@ -0,0 +1,102 @@
+/**
+ * Syntax validator - validates YAML/JSON structure
+ */
+import { load as yamlLoad } from 'js-yaml';
+export class SyntaxValidator {
+    validate(workflowContent, isJson = false) {
+        const errors = [];
+        let workflow;
+        try {
+            // Parse YAML or JSON
+            workflow = isJson
+                ? JSON.parse(workflowContent)
+                : yamlLoad(workflowContent);
+            // Ensure workflow is not undefined
+            if (!workflow) {
+                errors.push({
+                    type: 'syntax',
+                    severity: 'error',
+                    message: 'Failed to parse workflow content',
+                    path: '$'
+                });
+                return { valid: false, errors };
+            }
+            // Validate required fields
+            if (!workflow.name) {
+                errors.push({
+                    type: 'syntax',
+                    severity: 'error',
+                    message: 'Missing required field: name',
+                    path: '$.name'
+                });
+            }
+            if (!workflow.steps || !Array.isArray(workflow.steps)) {
+                errors.push({
+                    type: 'syntax',
+                    severity: 'error',
+                    message: 'Missing or invalid required field: steps (must be an array)',
+                    path: '$.steps'
+                });
+            }
+            // Validate each step has required fields
+            if (workflow.steps && Array.isArray(workflow.steps)) {
+                workflow.steps.forEach((step, index) => {
+                    if (!step.name) {
+                        errors.push({
+                            type: 'syntax',
+                            severity: 'error',
+                            message: 'Step is missing required field: name',
+                            path: `$.steps[${index}].name`
+                        });
+                    }
+                    if (!step.tool) {
+                        errors.push({
+                            type: 'syntax',
+                            severity: 'error',
+                            message: 'Step is missing required field: tool',
+                            path: `$.steps[${index}].tool`
+                        });
+                    }
+                    // Check for valid step name format (snake_case or kebab-case)
+                    if (step.name && !/^[a-z][a-z0-9_-]*$/.test(step.name)) {
+                        errors.push({
+                            type: 'syntax',
+                            severity: 'warning',
+                            message: `Step name '${step.name}' should use snake_case or kebab-case`,
+                            path: `$.steps[${index}].name`,
+                            suggestion: 'Use lowercase with underscores or hyphens, e.g., "my_step" or "my-step"'
+                        });
+                    }
+                });
+            }
+            // Validate variable names if present
+            if (workflow.variables) {
+                for (const varName of Object.keys(workflow.variables)) {
+                    if (!/^[a-z][a-z0-9_]*$/.test(varName)) {
+                        errors.push({
+                            type: 'syntax',
+                            severity: 'warning',
+                            message: `Variable name '${varName}' should use snake_case`,
+                            path: `$.variables.${varName}`,
+                            suggestion: 'Use lowercase with underscores, e.g., "my_variable"'
+                        });
+                    }
+                }
+            }
+        }
+        catch (e) {
+            errors.push({
+                type: 'syntax',
+                severity: 'error',
+                message: `Invalid ${isJson ? 'JSON' : 'YAML'} syntax: ${e.message}`,
+                path: '$',
+                suggestion: 'Check for proper indentation, missing colons, or invalid characters'
+            });
+        }
+        return {
+            valid: errors.filter(e => e.severity === 'error').length === 0,
+            errors,
+            workflow
+        };
+    }
+}

package/dist/src/validators/tool-registry-validator.js

@@ -0,0 +1,123 @@
+/**
+ * Tool registry validator - validates tool names against enabled tools
+ */
+export class ToolRegistryValidator {
+    validate(context) {
+        const errors = [];
+        context.workflow.steps.forEach((step, index) => {
+            // Check if tool exists in all known tools
+            const isKnownTool = context.allKnownTools.has(step.tool);
+            const isEnabled = context.enabledTools.has(step.tool);
+            if (!isKnownTool) {
+                // Unknown tool (misspelled or doesn't exist) → ERROR
+                errors.push({
+                    type: 'tool',
+                    severity: 'error',
+                    message: `Tool '${step.tool}' does not exist`,
+                    path: `$.steps[${index}].tool`,
+                    suggestion: this.suggestSimilarTool(step.tool, context.allKnownTools)
+                });
+            }
+            else if (!isEnabled) {
+                // Known tool but disabled → WARNING
+                errors.push({
+                    type: 'tool',
+                    severity: 'warning',
+                    message: `Tool '${step.tool}' is disabled in tools.config.json`,
+                    path: `$.steps[${index}].tool`,
+                    suggestion: `Enable '${step.tool}' in your tools.config.json or active profile`
+                });
+            }
+            // Validate tool name format
+            if (step.tool && !this.isValidToolName(step.tool)) {
+                errors.push({
+                    type: 'tool',
+                    severity: 'warning',
+                    message: `Tool name '${step.tool}' has unusual format`,
+                    path: `$.steps[${index}].tool`,
+                    suggestion: 'Tool names should use snake_case or be known MCP tools'
+                });
+            }
+        });
+        return errors;
+    }
+    /**
+     * Check if tool name follows valid conventions
+     */
+    isValidToolName(toolName) {
+        // Valid formats:
+        // - snake_case: my_tool
+        // - Known tool patterns: focus, scout, verifier, etc.
+        return /^[a-z][a-z0-9_]*$/.test(toolName);
+    }
+    /**
+     * Check if this is a known tool name (might be disabled)
+     */
+    isKnownToolName(toolName) {
+        const knownTools = [
+            // Core
+            'think', 'focus', 'nextThought',
+            // Perplexity
+            'perplexity_ask', 'perplexity_reason', 'perplexity_research',
+            // Grok
+            'grok_reason', 'grok_code', 'grok_debug', 'grok_architect', 'grok_brainstorm', 'grok_search',
+            // OpenAI
+            'openai_compare', 'openai_brainstorm', 'openai_gpt5_reason', 'openai_code_review', 'openai_explain',
+            // Gemini
+            'gemini_brainstorm', 'gemini_analyze_code', 'gemini_analyze_text',
+            // Qwen
+            'qwen_coder',
+            // Advanced modes
+            'verifier', 'scout', 'challenger', 'hunter',
+            // Workflow
+            'workflow', 'list_workflows', 'create_workflow', 'visualize_workflow',
+            // Collaborative
+            'pingpong', 'qwen_competitive'
+        ];
+        return knownTools.includes(toolName);
+    }
+    /**
+     * Suggest a similar tool name using Levenshtein distance
+     */
+    suggestSimilarTool(toolName, enabledTools) {
+        const suggestions = [];
+        for (const tool of enabledTools) {
+            const distance = this.levenshteinDistance(toolName, tool);
+            if (distance <= 3) { // Only suggest if reasonably close
+                suggestions.push({ tool, distance });
+            }
+        }
+        if (suggestions.length === 0) {
+            return 'Check tools.config.json for available tools';
+        }
+        suggestions.sort((a, b) => a.distance - b.distance);
+        const topSuggestions = suggestions.slice(0, 3).map(s => s.tool);
+        return `Did you mean: ${topSuggestions.join(', ')}?`;
+    }
+    /**
+     * Calculate Levenshtein distance between two strings
+     */
+    levenshteinDistance(a, b) {
+        const matrix = [];
+        for (let i = 0; i <= b.length; i++) {
+            matrix[i] = [i];
+        }
+        for (let j = 0; j <= a.length; j++) {
+            matrix[0][j] = j;
+        }
+        for (let i = 1; i <= b.length; i++) {
+            for (let j = 1; j <= a.length; j++) {
+                if (b.charAt(i - 1) === a.charAt(j - 1)) {
+                    matrix[i][j] = matrix[i - 1][j - 1];
+                }
+                else {
+                    matrix[i][j] = Math.min(matrix[i - 1][j - 1] + 1, // substitution
+                    matrix[i][j - 1] + 1, // insertion
+                    matrix[i - 1][j] + 1 // deletion
+                    );
+                }
+            }
+        }
+        return matrix[b.length][a.length];
+    }
+}