@exaudeus/workrail 0.4.0 → 0.5.0

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

@@ -0,0 +1,20 @@
+import { IWorkflowStorage } from '../../types/storage';
+import { ValidationEngine } from './validation-engine';
+import { DocumentationResult } from '../../types/documentation-types';
+export interface IDocumentationService {
+    resolveDocumentation(workflowId: string, mode?: 'preview' | 'full', sections?: string[], format?: string): Promise<DocumentationResult>;
+    isDocumentationAvailable(workflowId: string): Promise<boolean>;
+    getWorkrailHelp(section?: string, format?: string): Promise<DocumentationResult>;
+}
+export declare class DefaultDocumentationService implements IDocumentationService {
+    private readonly storage;
+    private readonly validationEngine;
+    constructor(storage: IWorkflowStorage, validationEngine: ValidationEngine);
+    resolveDocumentation(workflowId: string, mode?: 'preview' | 'full', sections?: string[], format?: string): Promise<DocumentationResult>;
+    isDocumentationAvailable(workflowId: string): Promise<boolean>;
+    getWorkrailHelp(section?: string, format?: string): Promise<DocumentationResult>;
+    private parseMarkdownSections;
+    private createPreview;
+    private generateFallbackDocumentation;
+    private generateWorkrailHelp;
+}

package/dist/application/services/documentation-service.js

@@ -0,0 +1,155 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DefaultDocumentationService = void 0;
+const error_handler_1 = require("../../core/error-handler");
+class DefaultDocumentationService {
+    constructor(storage, validationEngine) {
+        this.storage = storage;
+        this.validationEngine = validationEngine;
+    }
+    async resolveDocumentation(workflowId, mode = 'preview', sections, format = 'text') {
+        try {
+            const workflow = await this.storage.getWorkflowById(workflowId);
+            if (!workflow) {
+                throw new error_handler_1.WorkflowNotFoundError(workflowId);
+            }
+            if (workflow.documentation) {
+                return {
+                    source: 'json',
+                    format: 'json',
+                    content: workflow.documentation
+                };
+            }
+            if (this.storage.getWorkflowReadme) {
+                const readme = await this.storage.getWorkflowReadme(workflowId);
+                if (readme) {
+                    const sections = this.parseMarkdownSections(readme);
+                    return {
+                        source: 'readme',
+                        format: 'markdown',
+                        content: mode === 'preview' ? this.createPreview(readme) : readme,
+                        sections
+                    };
+                }
+            }
+            return this.generateFallbackDocumentation(workflow, format);
+        }
+        catch (error) {
+            if (error instanceof error_handler_1.WorkflowNotFoundError) {
+                throw error;
+            }
+            return {
+                source: 'fallback',
+                format: 'text',
+                content: `Documentation unavailable for workflow: ${workflowId}. Error: ${error instanceof Error ? error.message : String(error)}`
+            };
+        }
+    }
+    async isDocumentationAvailable(workflowId) {
+        try {
+            const workflow = await this.storage.getWorkflowById(workflowId);
+            if (!workflow) {
+                return false;
+            }
+            if (workflow.documentation) {
+                return true;
+            }
+            if (this.storage.hasDocumentation) {
+                return await this.storage.hasDocumentation(workflowId);
+            }
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    async getWorkrailHelp(section, format = 'text') {
+        const helpContent = this.generateWorkrailHelp(section);
+        return {
+            source: 'fallback',
+            format: 'text',
+            content: helpContent
+        };
+    }
+    parseMarkdownSections(markdown) {
+        const sections = {};
+        const lines = markdown.split('\n');
+        let currentSection = '';
+        let currentContent = [];
+        for (const line of lines) {
+            if (line.startsWith('# ') || line.startsWith('## ')) {
+                if (currentSection && currentContent.length > 0) {
+                    sections[currentSection] = currentContent.join('\n').trim();
+                }
+                currentSection = line.replace(/^#+\s*/, '').toLowerCase().replace(/\s+/g, '-');
+                currentContent = [];
+            }
+            else {
+                currentContent.push(line);
+            }
+        }
+        if (currentSection && currentContent.length > 0) {
+            sections[currentSection] = currentContent.join('\n').trim();
+        }
+        return sections;
+    }
+    createPreview(content) {
+        const lines = content.split('\n');
+        const previewLines = [];
+        let lineCount = 0;
+        const maxLines = 20;
+        for (const line of lines) {
+            if (lineCount >= maxLines) {
+                previewLines.push('\n[... content truncated for preview mode ...]');
+                break;
+            }
+            previewLines.push(line);
+            lineCount++;
+        }
+        return previewLines.join('\n');
+    }
+    generateFallbackDocumentation(workflow, format) {
+        const content = `# ${workflow.name}
+
+${workflow.description}
+
+**Version:** ${workflow.version}
+**Steps:** ${workflow.steps?.length || 0} steps
+
+${workflow.preconditions?.length ? `**Prerequisites:**\n${workflow.preconditions.map((p) => `- ${p}`).join('\n')}\n` : ''}
+
+*This is auto-generated documentation. For detailed guidance, consider adding a documentation object to the workflow JSON or creating a README file.*`;
+        return {
+            source: 'fallback',
+            format: 'text',
+            content
+        };
+    }
+    generateWorkrailHelp(section) {
+        const baseHelp = `# WorkRail Documentation System
+
+WorkRail provides structured workflow orchestration with built-in documentation support.
+
+## Available Commands
+- \`workflow_list\` - List all available workflows
+- \`workflow_get\` - Get detailed workflow information
+- \`workflow_docs\` - Get workflow-specific documentation
+- \`workrail_help\` - Get general platform help (this command)
+
+## Documentation Sources
+WorkRail resolves documentation in this priority order:
+1. **JSON Documentation** - Structured metadata in workflow files
+2. **README Files** - Markdown documentation alongside workflows  
+3. **Fallback** - Auto-generated from workflow metadata
+
+## Getting Help
+- Use \`workflow_docs\` for specific workflow documentation
+- Use \`workrail_help\` for general platform information
+- Check workflow descriptions in \`workflow_list\` output`;
+        if (section) {
+            return `${baseHelp}\n\n*Note: Section-specific help for "${section}" is not yet implemented.*`;
+        }
+        return baseHelp;
+    }
+}
+exports.DefaultDocumentationService = DefaultDocumentationService;

package/dist/application/use-cases/get-workflow-docs.d.ts

@@ -0,0 +1,4 @@
+import { IDocumentationService } from '../services/documentation-service';
+import { DocumentationResult } from '../../types/documentation-types';
+export declare function createGetWorkflowDocs(service: IDocumentationService): (id: string, mode?: "preview" | "full", sections?: string[], format?: string) => Promise<DocumentationResult>;
+export declare function getWorkflowDocs(service: IDocumentationService, id: string, mode?: 'preview' | 'full', sections?: string[], format?: string): Promise<DocumentationResult>;

package/dist/application/use-cases/get-workflow-docs.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createGetWorkflowDocs = createGetWorkflowDocs;
+exports.getWorkflowDocs = getWorkflowDocs;
+function createGetWorkflowDocs(service) {
+    return async (id, mode, sections, format) => {
+        return await service.resolveDocumentation(id, mode, sections, format);
+    };
+}
+async function getWorkflowDocs(service, id, mode, sections, format) {
+    return createGetWorkflowDocs(service)(id, mode, sections, format);
+}

package/dist/application/use-cases/get-workrail-help.d.ts

@@ -0,0 +1,4 @@
+import { IDocumentationService } from '../services/documentation-service';
+import { DocumentationResult } from '../../types/documentation-types';
+export declare function createGetWorkrailHelp(service: IDocumentationService): (section?: string, format?: string) => Promise<DocumentationResult>;
+export declare function getWorkrailHelp(service: IDocumentationService, section?: string, format?: string): Promise<DocumentationResult>;

package/dist/application/use-cases/get-workrail-help.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createGetWorkrailHelp = createGetWorkrailHelp;
+exports.getWorkrailHelp = getWorkrailHelp;
+function createGetWorkrailHelp(service) {
+    return async (section, format) => {
+        return await service.getWorkrailHelp(section, format);
+    };
+}
+async function getWorkrailHelp(service, section, format) {
+    return createGetWorkrailHelp(service)(section, format);
+}

package/dist/types/documentation-types.d.ts

@@ -0,0 +1,37 @@
+export interface DocumentationInput {
+    name: string;
+    required?: boolean;
+    description?: string;
+}
+export interface DocumentationMetadata {
+    summary: string;
+    whenToUse: string[];
+    whenNotToUse?: string[];
+    inputs: DocumentationInput[];
+    outputs: string[];
+    assumptions?: string[];
+    risks: string[];
+    relatedWorkflows?: string[];
+    helpHint?: string;
+}
+export interface SensitivityMetadata {
+    level?: string;
+    notes?: string;
+}
+export interface DocumentationResult {
+    source: 'json' | 'readme' | 'fallback';
+    format: 'json' | 'markdown' | 'text';
+    content: DocumentationMetadata | string;
+    sections?: Record<string, string>;
+}
+export interface DocumentationOptions {
+    mode?: 'preview' | 'full';
+    sections?: string[];
+    format?: 'text' | 'markdown' | 'json';
+}
+export interface DocumentationAvailability {
+    hasJsonDocs: boolean;
+    hasReadme: boolean;
+    hasAnyDocs: boolean;
+    helpHint?: string;
+}

package/dist/types/documentation-types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/utils/condition-evaluator.d.ts

@@ -9,6 +9,10 @@ export interface Condition {
     gte?: number;
     lt?: number;
     lte?: number;
+    contains?: string;
+    startsWith?: string;
+    endsWith?: string;
+    matches?: string;
     and?: Condition[];
     or?: Condition[];
     not?: Condition;

package/dist/utils/condition-evaluator.js

@@ -2,6 +2,40 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.evaluateCondition = evaluateCondition;
 exports.validateCondition = validateCondition;
+function lenientEquals(a, b) {
+    if (a == null && b == null) {
+        return true;
+    }
+    if (a == null || b == null) {
+        return false;
+    }
+    if (typeof a === 'string' && typeof b === 'string') {
+        return a.trim().toLowerCase() === b.trim().toLowerCase();
+    }
+    if ((typeof a === 'string' && typeof b === 'number') ||
+        (typeof a === 'number' && typeof b === 'string')) {
+        const numA = Number(a);
+        const numB = Number(b);
+        if (!isNaN(numA) && !isNaN(numB)) {
+            return numA === numB;
+        }
+    }
+    if (typeof a === 'string' && typeof b === 'boolean') {
+        const lowerA = a.trim().toLowerCase();
+        return (b === true && (lowerA === 'true' || lowerA === '1' || lowerA === 'yes')) ||
+            (b === false && (lowerA === 'false' || lowerA === '0' || lowerA === 'no'));
+    }
+    if (typeof b === 'string' && typeof a === 'boolean') {
+        return lenientEquals(b, a);
+    }
+    return a === b;
+}
+function normalizeToString(value) {
+    if (value == null) {
+        return '';
+    }
+    return String(value).trim();
+}
 function evaluateCondition(condition, context = {}) {
     if (!condition || typeof condition !== 'object') {
         return true;
@@ -20,11 +54,11 @@ function evaluateCondition(condition, context = {}) {
 function evaluateConditionUnsafe(condition, context) {
     if (condition.var !== undefined) {
         const value = context[condition.var];
-        if (condition.equals !== undefined) {
-            return value === condition.equals;
+        if ('equals' in condition) {
+            return lenientEquals(value, condition.equals);
         }
-        if (condition.not_equals !== undefined) {
-            return value !== condition.not_equals;
+        if ('not_equals' in condition) {
+            return !lenientEquals(value, condition.not_equals);
         }
         if (condition.gt !== undefined) {
             return typeof value === 'number' && value > condition.gt;
@@ -38,6 +72,32 @@ function evaluateConditionUnsafe(condition, context) {
         if (condition.lte !== undefined) {
             return typeof value === 'number' && value <= condition.lte;
         }
+        if (condition.contains !== undefined) {
+            const valueStr = normalizeToString(value).toLowerCase();
+            const searchStr = normalizeToString(condition.contains).toLowerCase();
+            return valueStr.includes(searchStr);
+        }
+        if (condition.startsWith !== undefined) {
+            const valueStr = normalizeToString(value).toLowerCase();
+            const searchStr = normalizeToString(condition.startsWith).toLowerCase();
+            return valueStr.startsWith(searchStr);
+        }
+        if (condition.endsWith !== undefined) {
+            const valueStr = normalizeToString(value).toLowerCase();
+            const searchStr = normalizeToString(condition.endsWith).toLowerCase();
+            return valueStr.endsWith(searchStr);
+        }
+        if (condition.matches !== undefined) {
+            const valueStr = normalizeToString(value);
+            try {
+                const regex = new RegExp(condition.matches, 'i');
+                return regex.test(valueStr);
+            }
+            catch (error) {
+                console.warn('Invalid regex pattern in condition:', condition.matches);
+                return false;
+            }
+        }
         return !!value;
     }
     if (condition.and !== undefined) {
@@ -62,7 +122,9 @@ function validateCondition(condition) {
         return;
     }
     const supportedKeys = [
-        'var', 'equals', 'not_equals', 'gt', 'gte', 'lt', 'lte', 'and', 'or', 'not'
+        'var', 'equals', 'not_equals', 'gt', 'gte', 'lt', 'lte',
+        'contains', 'startsWith', 'endsWith', 'matches',
+        'and', 'or', 'not'
     ];
     const conditionKeys = Object.keys(condition);
     const unsupportedKeys = conditionKeys.filter(key => !supportedKeys.includes(key));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@exaudeus/workrail",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "MCP server for structured workflow orchestration and step-by-step task guidance",
   "license": "MIT",
   "bin": {

package/workflows/coding-task-workflow-with-loops.json

@@ -43,7 +43,8 @@
         "Maintain existing coding conventions and architectural patterns found in the codebase.",
         "COMMIT STRATEGY: Auto-commit after successful steps for High automation; suggest for Medium/Low. Use conventional format: type(scope): description. Commit at milestones and after verification passes.",
         "When you see function calls like updateDecisionLog() or createFile(spec.md), refer to the function definitions above for full instructions.",
-        "For resumption: Include function definitions in CONTEXT.md so new sessions understand these references. Always provide explicit workflow_get and workflow_next instructions."
+        "For resumption: Include function definitions in CONTEXT.md so new sessions understand these references. Always provide explicit workflow_get and workflow_next instructions.",
+        "Auto-advance: after completing each step, immediately get the next step; only pause for explicit requireConfirmation or missing critical inputs."
     ],
     "steps": [
         {