@exaudeus/workrail 0.0.20 → 0.1.1

package/README.md

@@ -16,6 +16,15 @@ It follows [Model Context Protocol (MCP)](https://modelcontextprotocol.org) conv
 
 The codebase now implements the full MVP described in the original specification, refactored with Clean Architecture for long-term maintainability.
 
+### ✨ New in v0.1.0: Loop Support
+WorkRail now supports powerful iteration patterns with four loop types:
+- **while**: Continue while a condition is true
+- **until**: Continue until a condition is met  
+- **for**: Execute a fixed number of times
+- **forEach**: Process items in an array
+
+See the [Loop Documentation](docs/features/loops.md) for details.
+
 ---
 
 ## 🚀 Quick Start
@@ -58,11 +67,18 @@ workrail start
   - `workflow_next` - Get the next step in a workflow
   - `workflow_validate` - Advanced validation of step outputs with schema, context-aware, and composition rules
   - `workflow_validate_json` - Direct JSON workflow validation with comprehensive error reporting and actionable suggestions
+* **Loop Support (v0.1.0)** – Four loop types for powerful iteration patterns:
+  - `while` loops - Continue while a condition is true
+  - `until` loops - Continue until a condition is met
+  - `for` loops - Execute a fixed number of times
+  - `forEach` loops - Process items in an array
 * **Dependency Injection** – pluggable components are wired by `src/container.ts` (Inversify-style, no runtime reflection).
 * **Async, Secure Storage** – interchangeable back-ends: in-memory (default for tests) and file-based storage with path-traversal safeguards.
 * **Advanced ValidationEngine** – Three-tier validation system with JSON Schema validation (AJV), Context-Aware Validation (conditional rules), and Logical Composition (and/or/not operators) for comprehensive step output quality assurance.
 * **Typed Error Mapping** – domain errors (`WorkflowNotFoundError`, `ValidationError`, …) automatically translate to proper JSON-RPC codes.
-* **CLI Validation** – `validate` command for testing workflow files locally with comprehensive error reporting.
+* **CLI Tools** – 
+  - `validate` - Test workflow files locally with comprehensive error reporting
+  - `migrate` - Automatically migrate workflows from v0.0.1 to v0.1.0
 * **Comprehensive Test Coverage** – 81 tests passing, 7 failing (performance optimizations in progress), 88 total tests covering storage, validation, error mapping, CLI, and server logic.
 
 ---

package/dist/application/services/context-optimizer.d.ts

@@ -0,0 +1,11 @@
+import { EnhancedContext } from '../../types/workflow-types';
+type ConditionContext = Record<string, any>;
+export declare class ContextOptimizer {
+    static createEnhancedContext(base: ConditionContext, enhancements: Partial<EnhancedContext>): EnhancedContext;
+    static mergeLoopState(context: EnhancedContext, loopId: string, loopState: any): EnhancedContext;
+    static addWarnings(context: EnhancedContext, category: string, key: string, warnings: string[]): EnhancedContext;
+    static hasProperty(context: ConditionContext, property: string): boolean;
+    static getProperty(context: ConditionContext, property: string): any;
+    static getOwnPropertiesSize(context: ConditionContext): number;
+}
+export {};

package/dist/application/services/context-optimizer.js

@@ -0,0 +1,62 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ContextOptimizer = void 0;
+class ContextOptimizer {
+    static createEnhancedContext(base, enhancements) {
+        const hasOverlap = Object.keys(enhancements).some(key => key in base);
+        if (!hasOverlap) {
+            return Object.assign({}, base, enhancements);
+        }
+        return { ...base, ...enhancements };
+    }
+    static mergeLoopState(context, loopId, loopState) {
+        if (!context._loopState) {
+            return ContextOptimizer.createEnhancedContext(context, {
+                _loopState: { [loopId]: loopState }
+            });
+        }
+        if (context._loopState[loopId] === loopState) {
+            return context;
+        }
+        return ContextOptimizer.createEnhancedContext(context, {
+            _loopState: { ...context._loopState, [loopId]: loopState }
+        });
+    }
+    static addWarnings(context, category, key, warnings) {
+        if (warnings.length === 0) {
+            return context;
+        }
+        const existingWarnings = context._warnings || {};
+        const categoryWarnings = existingWarnings[category] || {};
+        return ContextOptimizer.createEnhancedContext(context, {
+            _warnings: {
+                ...existingWarnings,
+                [category]: {
+                    ...categoryWarnings,
+                    [key]: warnings
+                }
+            }
+        });
+    }
+    static hasProperty(context, property) {
+        return property in context;
+    }
+    static getProperty(context, property) {
+        return context[property];
+    }
+    static getOwnPropertiesSize(context) {
+        const ownProps = Object.getOwnPropertyNames(context);
+        let size = 0;
+        for (const prop of ownProps) {
+            const value = context[prop];
+            if (typeof value === 'string') {
+                size += value.length;
+            }
+            else {
+                size += JSON.stringify(value).length;
+            }
+        }
+        return size;
+    }
+}
+exports.ContextOptimizer = ContextOptimizer;

package/dist/application/services/loop-execution-context.d.ts

@@ -0,0 +1,18 @@
+import { LoopConfig, LoopState, EnhancedContext } from '../../types/workflow-types';
+import { ConditionContext } from '../../utils/condition-evaluator';
+export declare class LoopExecutionContext {
+    private loopId;
+    private loopConfig;
+    private state;
+    private readonly maxExecutionTime;
+    constructor(loopId: string, loopConfig: LoopConfig, existingState?: LoopState[string]);
+    incrementIteration(): void;
+    getCurrentState(): LoopState[string];
+    shouldContinue(context: ConditionContext): boolean;
+    initializeForEach(context: ConditionContext): void;
+    injectVariables(context: ConditionContext): EnhancedContext;
+    private resolveCount;
+    private addWarning;
+    getLoopId(): string;
+    getLoopConfig(): LoopConfig;
+}

package/dist/application/services/loop-execution-context.js

@@ -0,0 +1,127 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LoopExecutionContext = void 0;
+const condition_evaluator_1 = require("../../utils/condition-evaluator");
+class LoopExecutionContext {
+    constructor(loopId, loopConfig, existingState) {
+        this.maxExecutionTime = 5 * 60 * 1000;
+        this.loopId = loopId;
+        this.loopConfig = loopConfig;
+        this.state = existingState || {
+            iteration: 0,
+            started: Date.now(),
+            warnings: []
+        };
+        if (loopConfig.type === 'forEach' && loopConfig.items && this.state.index === undefined) {
+            this.state.index = 0;
+        }
+    }
+    incrementIteration() {
+        this.state.iteration++;
+        if (this.loopConfig.type === 'forEach' && typeof this.state.index === 'number') {
+            this.state.index++;
+        }
+    }
+    getCurrentState() {
+        return { ...this.state };
+    }
+    shouldContinue(context) {
+        if (this.state.iteration >= this.loopConfig.maxIterations) {
+            this.addWarning(`Maximum iterations (${this.loopConfig.maxIterations}) reached`);
+            return false;
+        }
+        const executionTime = Date.now() - this.state.started;
+        if (executionTime > this.maxExecutionTime) {
+            this.addWarning(`Maximum execution time (${this.maxExecutionTime / 1000}s) exceeded`);
+            return false;
+        }
+        switch (this.loopConfig.type) {
+            case 'while':
+                return this.loopConfig.condition
+                    ? (0, condition_evaluator_1.evaluateCondition)(this.loopConfig.condition, context)
+                    : false;
+            case 'until':
+                return this.loopConfig.condition
+                    ? !(0, condition_evaluator_1.evaluateCondition)(this.loopConfig.condition, context)
+                    : false;
+            case 'for':
+                const count = this.resolveCount(context);
+                return this.state.iteration < count;
+            case 'forEach':
+                return this.state.items
+                    ? (this.state.index || 0) < this.state.items.length
+                    : false;
+            default:
+                return false;
+        }
+    }
+    initializeForEach(context) {
+        if (this.loopConfig.type === 'forEach' && this.loopConfig.items) {
+            const items = context[this.loopConfig.items];
+            if (Array.isArray(items)) {
+                this.state.items = items;
+                this.state.index = 0;
+            }
+            else {
+                this.addWarning(`Expected array for forEach items '${this.loopConfig.items}', got ${typeof items}`);
+                this.state.items = [];
+            }
+        }
+    }
+    injectVariables(context) {
+        const enhancements = {
+            _loopState: {
+                ...context._loopState,
+                [this.loopId]: this.getCurrentState()
+            }
+        };
+        const iterationVar = this.loopConfig.iterationVar || 'currentIteration';
+        enhancements[iterationVar] = this.state.iteration + 1;
+        if (this.loopConfig.type === 'forEach' && this.state.items) {
+            const index = this.state.index || 0;
+            const itemVar = this.loopConfig.itemVar || 'currentItem';
+            enhancements[itemVar] = this.state.items[index];
+            const indexVar = this.loopConfig.indexVar || 'currentIndex';
+            enhancements[indexVar] = index;
+        }
+        if (this.state.warnings && this.state.warnings.length > 0) {
+            const existingWarnings = context._warnings || {};
+            const existingLoopWarnings = existingWarnings.loops || {};
+            enhancements._warnings = {
+                ...existingWarnings,
+                loops: {
+                    ...existingLoopWarnings,
+                    [this.loopId]: [...this.state.warnings]
+                }
+            };
+        }
+        return { ...context, ...enhancements };
+    }
+    resolveCount(context) {
+        if (this.loopConfig.type !== 'for' || !this.loopConfig.count) {
+            return 0;
+        }
+        if (typeof this.loopConfig.count === 'number') {
+            return this.loopConfig.count;
+        }
+        const count = context[this.loopConfig.count];
+        if (typeof count === 'number') {
+            return count;
+        }
+        this.addWarning(`Invalid count value for 'for' loop: ${this.loopConfig.count}`);
+        return 0;
+    }
+    addWarning(message) {
+        if (!this.state.warnings) {
+            this.state.warnings = [];
+        }
+        this.state.warnings.push(message);
+    }
+    getLoopId() {
+        return this.loopId;
+    }
+    getLoopConfig() {
+        return { ...this.loopConfig };
+    }
+}
+exports.LoopExecutionContext = LoopExecutionContext;

package/dist/application/services/loop-step-resolver.d.ts

@@ -0,0 +1,11 @@
+import { Workflow, WorkflowStep } from '../../types/mcp-types';
+export declare class LoopStepResolver {
+    private resolvedStepsCache;
+    resolveLoopBody(workflow: Workflow, body: string | WorkflowStep[], currentLoopId?: string): WorkflowStep | WorkflowStep[];
+    validateStepReference(workflow: Workflow, stepId: string): boolean;
+    findAllLoopReferences(workflow: Workflow): string[];
+    validateAllReferences(workflow: Workflow): void;
+    clearCache(): void;
+    getCacheSize(): number;
+    private findStepById;
+}

package/dist/application/services/loop-step-resolver.js

@@ -0,0 +1,70 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LoopStepResolver = void 0;
+const workflow_types_1 = require("../../types/workflow-types");
+const error_handler_1 = require("../../core/error-handler");
+class LoopStepResolver {
+    constructor() {
+        this.resolvedStepsCache = new Map();
+    }
+    resolveLoopBody(workflow, body, currentLoopId) {
+        if (Array.isArray(body)) {
+            return body;
+        }
+        const cacheKey = `${workflow.id}:${body}`;
+        if (this.resolvedStepsCache.has(cacheKey)) {
+            return this.resolvedStepsCache.get(cacheKey);
+        }
+        const referencedStep = this.findStepById(workflow, body);
+        if (!referencedStep) {
+            throw new error_handler_1.StepNotFoundError(workflow.id, body);
+        }
+        if (currentLoopId && body === currentLoopId) {
+            throw new Error(`Circular reference detected: loop step '${body}' references itself`);
+        }
+        this.resolvedStepsCache.set(cacheKey, referencedStep);
+        return referencedStep;
+    }
+    validateStepReference(workflow, stepId) {
+        return this.findStepById(workflow, stepId) !== null;
+    }
+    findAllLoopReferences(workflow) {
+        const references = [];
+        for (const step of workflow.steps) {
+            if ((0, workflow_types_1.isLoopStep)(step)) {
+                const loopStep = step;
+                if (typeof loopStep.body === 'string') {
+                    references.push(loopStep.body);
+                }
+            }
+        }
+        return references;
+    }
+    validateAllReferences(workflow) {
+        const references = this.findAllLoopReferences(workflow);
+        const stepIds = new Set(workflow.steps.map(s => s.id));
+        for (const ref of references) {
+            if (!stepIds.has(ref)) {
+                throw new error_handler_1.StepNotFoundError(workflow.id, ref);
+            }
+        }
+        for (const step of workflow.steps) {
+            if ((0, workflow_types_1.isLoopStep)(step)) {
+                const loopStep = step;
+                if (typeof loopStep.body === 'string' && loopStep.body === loopStep.id) {
+                    throw new Error(`Circular reference detected: loop step '${loopStep.id}' references itself`);
+                }
+            }
+        }
+    }
+    clearCache() {
+        this.resolvedStepsCache.clear();
+    }
+    getCacheSize() {
+        return this.resolvedStepsCache.size;
+    }
+    findStepById(workflow, stepId) {
+        return workflow.steps.find(s => s.id === stepId) || null;
+    }
+}
+exports.LoopStepResolver = LoopStepResolver;

package/dist/application/services/validation-engine.d.ts

@@ -1,4 +1,5 @@
 import { Condition, ConditionContext } from '../../utils/condition-evaluator';
+import { LoopStep, Workflow } from '../../types/workflow-types';
 export interface ValidationRule {
     type: 'contains' | 'regex' | 'length' | 'schema';
     message: string;
@@ -34,4 +35,7 @@ export declare class ValidationEngine {
     private isValidationComposition;
     validate(output: string, criteria: ValidationRule[] | ValidationComposition, context?: ConditionContext): Promise<ValidationResult>;
     private evaluateRule;
+    validateLoopStep(step: LoopStep, workflow: Workflow): ValidationResult;
+    validateWorkflow(workflow: Workflow): ValidationResult;
+    private isValidVariableName;
 }

package/dist/application/services/validation-engine.js

@@ -7,6 +7,7 @@ exports.ValidationEngine = void 0;
 const error_handler_1 = require("../../core/error-handler");
 const condition_evaluator_1 = require("../../utils/condition-evaluator");
 const ajv_1 = __importDefault(require("ajv"));
+const workflow_types_1 = require("../../types/workflow-types");
 class ValidationEngine {
     constructor() {
         this.schemaCache = new Map();
@@ -203,5 +204,175 @@ class ValidationEngine {
         }
         throw new error_handler_1.ValidationError('Invalid validationCriteria format.');
     }
+    validateLoopStep(step, workflow) {
+        const issues = [];
+        const suggestions = [];
+        const validTypes = ['while', 'until', 'for', 'forEach'];
+        if (!validTypes.includes(step.loop.type)) {
+            issues.push(`Invalid loop type '${step.loop.type}'. Must be one of: ${validTypes.join(', ')}`);
+        }
+        if (typeof step.loop.maxIterations !== 'number' || step.loop.maxIterations <= 0) {
+            issues.push(`maxIterations must be a positive number`);
+            suggestions.push('Set maxIterations to a reasonable limit (e.g., 100) to prevent infinite loops');
+        }
+        else if (step.loop.maxIterations > 1000) {
+            issues.push(`maxIterations (${step.loop.maxIterations}) exceeds safety limit of 1000`);
+            suggestions.push('Consider reducing maxIterations or breaking the loop into smaller chunks');
+        }
+        switch (step.loop.type) {
+            case 'while':
+            case 'until':
+                if (!step.loop.condition) {
+                    issues.push(`${step.loop.type} loop requires a condition`);
+                    suggestions.push(`Add a condition that evaluates to false (for while) or true (for until) to exit the loop`);
+                }
+                break;
+            case 'for':
+                if (step.loop.count === undefined) {
+                    issues.push(`for loop requires a count`);
+                    suggestions.push('Set count to a number or context variable name');
+                }
+                else if (typeof step.loop.count === 'string') {
+                }
+                else if (typeof step.loop.count !== 'number' || step.loop.count <= 0) {
+                    issues.push(`for loop count must be a positive number or context variable name`);
+                }
+                break;
+            case 'forEach':
+                if (!step.loop.items) {
+                    issues.push(`forEach loop requires items`);
+                    suggestions.push('Set items to a context variable name containing an array');
+                }
+                else if (typeof step.loop.items !== 'string') {
+                    issues.push(`forEach loop items must be a context variable name`);
+                }
+                break;
+        }
+        if (!step.body) {
+            issues.push(`Loop step must have a body`);
+            suggestions.push('Set body to a step ID or array of step IDs');
+        }
+        else {
+            if (typeof step.body === 'string') {
+                const bodyStep = workflow.steps.find(s => s.id === step.body);
+                if (!bodyStep) {
+                    issues.push(`Loop body references non-existent step '${step.body}'`);
+                    suggestions.push(`Create a step with ID '${step.body}' or update the body reference`);
+                }
+                else if ((0, workflow_types_1.isLoopStep)(bodyStep)) {
+                    issues.push(`Nested loops are not currently supported. Step '${step.body}' is a loop`);
+                    suggestions.push('Refactor to avoid nested loops or use sequential loops');
+                }
+            }
+            else if (Array.isArray(step.body)) {
+                if (step.body.length === 0) {
+                    issues.push(`Loop body array cannot be empty`);
+                    suggestions.push('Add at least one step to the loop body');
+                }
+                const stepIds = new Set();
+                for (const inlineStep of step.body) {
+                    if (!inlineStep.id) {
+                        issues.push(`Inline step in loop body must have an ID`);
+                        suggestions.push('Add an ID to all inline steps');
+                    }
+                    else if (stepIds.has(inlineStep.id)) {
+                        issues.push(`Duplicate step ID '${inlineStep.id}' in loop body`);
+                        suggestions.push('Use unique IDs for each inline step');
+                    }
+                    else {
+                        stepIds.add(inlineStep.id);
+                    }
+                    if (!inlineStep.title) {
+                        issues.push(`Inline step '${inlineStep.id || 'unknown'}' must have a title`);
+                        suggestions.push('Add a title to all inline steps');
+                    }
+                    if (!inlineStep.prompt) {
+                        issues.push(`Inline step '${inlineStep.id || 'unknown'}' must have a prompt`);
+                        suggestions.push('Add a prompt to all inline steps');
+                    }
+                    if ((0, workflow_types_1.isLoopStep)(inlineStep)) {
+                        issues.push(`Nested loops are not currently supported. Inline step '${inlineStep.id}' is a loop`);
+                        suggestions.push('Refactor to avoid nested loops');
+                    }
+                }
+            }
+        }
+        if (step.loop.iterationVar && !this.isValidVariableName(step.loop.iterationVar)) {
+            issues.push(`Invalid iteration variable name '${step.loop.iterationVar}'`);
+            suggestions.push('Use a valid JavaScript variable name (alphanumeric, _, $)');
+        }
+        if (step.loop.itemVar && !this.isValidVariableName(step.loop.itemVar)) {
+            issues.push(`Invalid item variable name '${step.loop.itemVar}'`);
+            suggestions.push('Use a valid JavaScript variable name');
+        }
+        if (step.loop.indexVar && !this.isValidVariableName(step.loop.indexVar)) {
+            issues.push(`Invalid index variable name '${step.loop.indexVar}'`);
+            suggestions.push('Use a valid JavaScript variable name');
+        }
+        return {
+            valid: issues.length === 0,
+            issues,
+            suggestions
+        };
+    }
+    validateWorkflow(workflow) {
+        const issues = [];
+        const suggestions = [];
+        const stepIds = new Set();
+        for (const step of workflow.steps) {
+            if (stepIds.has(step.id)) {
+                issues.push(`Duplicate step ID '${step.id}'`);
+                suggestions.push('Ensure all step IDs are unique');
+            }
+            stepIds.add(step.id);
+        }
+        for (const step of workflow.steps) {
+            if ((0, workflow_types_1.isLoopStep)(step)) {
+                const loopResult = this.validateLoopStep(step, workflow);
+                issues.push(...loopResult.issues.map(issue => `Step '${step.id}': ${issue}`));
+                suggestions.push(...loopResult.suggestions);
+            }
+            else {
+                if (!step.id) {
+                    issues.push('Step missing required ID');
+                }
+                if (!step.title) {
+                    issues.push(`Step '${step.id}' missing required title`);
+                }
+                if (!step.prompt) {
+                    issues.push(`Step '${step.id}' missing required prompt`);
+                }
+            }
+        }
+        const loopBodySteps = new Set();
+        for (const step of workflow.steps) {
+            if ((0, workflow_types_1.isLoopStep)(step)) {
+                if (typeof step.body === 'string') {
+                    loopBodySteps.add(step.body);
+                }
+                else if (Array.isArray(step.body)) {
+                    step.body.forEach(id => {
+                        if (typeof id === 'string') {
+                            loopBodySteps.add(id);
+                        }
+                    });
+                }
+            }
+        }
+        for (const step of workflow.steps) {
+            if (loopBodySteps.has(step.id) && step.runCondition) {
+                issues.push(`Step '${step.id}' is a loop body but has runCondition - this may cause conflicts`);
+                suggestions.push('Remove runCondition from loop body steps as they are controlled by the loop');
+            }
+        }
+        return {
+            valid: issues.length === 0,
+            issues,
+            suggestions
+        };
+    }
+    isValidVariableName(name) {
+        return /^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(name);
+    }
 }
 exports.ValidationEngine = ValidationEngine;

package/dist/application/services/workflow-service.d.ts

@@ -5,6 +5,7 @@ export interface WorkflowService {
         step: import('../../types/mcp-types').WorkflowStep | null;
         guidance: import('../../types/mcp-types').WorkflowGuidance;
         isComplete: boolean;
+        context?: ConditionContext;
     }>;
     validateStepOutput(workflowId: string, stepId: string, output: string): Promise<{
         valid: boolean;
@@ -16,9 +17,11 @@ import { Workflow, WorkflowSummary, WorkflowStep, WorkflowGuidance } from '../..
 import { IWorkflowStorage } from '../../types/storage';
 import { ConditionContext } from '../../utils/condition-evaluator';
 import { ValidationEngine } from './validation-engine';
+import { EnhancedContext } from '../../types/workflow-types';
 export declare class DefaultWorkflowService implements WorkflowService {
     private readonly storage;
     private readonly validationEngine;
+    private loopStepResolver;
     constructor(storage?: IWorkflowStorage, validationEngine?: ValidationEngine);
     listWorkflowSummaries(): Promise<WorkflowSummary[]>;
     getWorkflowById(id: string): Promise<Workflow | null>;
@@ -26,11 +29,15 @@ export declare class DefaultWorkflowService implements WorkflowService {
         step: WorkflowStep | null;
         guidance: WorkflowGuidance;
         isComplete: boolean;
+        context?: ConditionContext;
     }>;
+    private buildStepPrompt;
+    private findLoopStepById;
     validateStepOutput(workflowId: string, stepId: string, output: string): Promise<{
         valid: boolean;
         issues: string[];
         suggestions: string[];
     }>;
+    updateContextForStepCompletion(workflowId: string, stepId: string, context: ConditionContext): Promise<EnhancedContext>;
 }
 export declare const defaultWorkflowService: WorkflowService;