@minded-ai/mindedjs 3.0.4-beta.3 → 3.0.6-beta.1

package/src/cli/validateFlow.ts

@@ -0,0 +1,502 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import * as yaml from 'js-yaml';
+import { CronExpressionParser } from 'cron-parser';
+
+interface ValidationResult {
+  success: boolean;
+  flowName?: string;
+  stats?: {
+    nodes: number;
+    edges: number;
+    nodeTypes: string[];
+    edgeTypes: string[];
+  };
+  errors?: string[];
+  warnings?: string[];
+  message: string;
+}
+
+/**
+ * Validates a cron expression format using cron-parser.
+ * Cron format: minute hour day month day-of-week (5 fields)
+ */
+export function validateCronExpression(cronExpression: string): { valid: boolean; error?: string } {
+  if (typeof cronExpression !== 'string' || cronExpression.trim() === '') {
+    return { valid: false, error: 'Cron expression must be a non-empty string' };
+  }
+
+  try {
+    CronExpressionParser.parse(cronExpression.trim());
+    return { valid: true };
+  } catch (error) {
+    return {
+      valid: false,
+      error: error instanceof Error ? error.message : 'Invalid cron expression format',
+    };
+  }
+}
+
+/**
+ * Validates an IANA timezone identifier.
+ * Uses Intl.DateTimeFormat to check if the timezone is valid.
+ */
+export function validateTimezone(timezone: string): { valid: boolean; error?: string } {
+  if (typeof timezone !== 'string' || timezone.trim() === '') {
+    return { valid: false, error: 'Timezone must be a non-empty string' };
+  }
+
+  try {
+    // Try to create a date formatter with the timezone
+    const formatter = new Intl.DateTimeFormat('en-US', { timeZone: timezone });
+    // Test if the timezone is valid by trying to format a date
+    formatter.format(new Date());
+    return { valid: true };
+  } catch {
+    return {
+      valid: false,
+      error: `Invalid IANA timezone identifier: "${timezone}"`,
+    };
+  }
+}
+
+/**
+ * Validates a schedule trigger node configuration.
+ * Returns an array of error messages (empty if valid).
+ */
+export function validateScheduleTrigger(
+  node: any,
+  nodeIndex: string
+): { errors: string[]; warnings: string[] } {
+  const errors: string[] = [];
+  const warnings: string[] = [];
+
+  if (!node.cronExpression) {
+    errors.push(`${nodeIndex} "${node.name}": schedule trigger missing required field "cronExpression"`);
+  } else if (typeof node.cronExpression !== 'string') {
+    errors.push(`${nodeIndex} "${node.name}": schedule trigger "cronExpression" must be a string`);
+  } else {
+    const cronValidation = validateCronExpression(node.cronExpression);
+    if (!cronValidation.valid) {
+      errors.push(`${nodeIndex} "${node.name}": invalid cron expression - ${cronValidation.error}`);
+    }
+  }
+
+  if (node.timezone !== undefined) {
+    if (typeof node.timezone !== 'string') {
+      errors.push(`${nodeIndex} "${node.name}": schedule trigger "timezone" must be a string`);
+    } else {
+      const timezoneValidation = validateTimezone(node.timezone);
+      if (!timezoneValidation.valid) {
+        errors.push(`${nodeIndex} "${node.name}": ${timezoneValidation.error}`);
+      }
+    }
+  }
+
+  return { errors, warnings };
+}
+
+/**
+ * Validates a MindedJS YAML flow file.
+ */
+export function validateFlow(flowPath: string): ValidationResult {
+  // Resolve the path
+  const resolvedPath = path.isAbsolute(flowPath) ? flowPath : path.join(process.cwd(), flowPath);
+
+  // Read the file
+  let flowContent: string;
+  try {
+    flowContent = fs.readFileSync(resolvedPath, 'utf-8');
+  } catch (error) {
+    return {
+      success: false,
+      message: `Failed to read file: ${error instanceof Error ? error.message : String(error)}`,
+    };
+  }
+
+  // Parse YAML
+  let flow: any;
+  try {
+    flow = yaml.load(flowContent);
+  } catch (error) {
+    return {
+      success: false,
+      message: `Invalid YAML syntax: ${error instanceof Error ? error.message : String(error)}`,
+    };
+  }
+
+  // Validate flow structure
+  const errors: string[] = [];
+  const warnings: string[] = [];
+
+  // Check for required top-level fields
+  if (!flow.name) {
+    errors.push('Flow is missing required field: "name"');
+  }
+
+  if (!flow.nodes || !Array.isArray(flow.nodes)) {
+    errors.push('Flow is missing required field: "nodes" (must be an array)');
+  }
+
+  if (!flow.edges || !Array.isArray(flow.edges)) {
+    errors.push('Flow is missing required field: "edges" (must be an array)');
+  }
+
+  // If basic structure is invalid, return early
+  if (errors.length > 0) {
+    return {
+      success: false,
+      errors,
+      warnings,
+      message: `Flow validation failed with ${errors.length} error(s)`,
+    };
+  }
+
+  // Create a set of node names for validation
+  const nodeNames = new Set<string>();
+  const nodesByName = new Map<string, any>();
+
+  // Validate nodes
+  for (let i = 0; i < flow.nodes.length; i++) {
+    const node = flow.nodes[i];
+    const nodeIndex = `Node ${i + 1}`;
+
+    // Check for required name field
+    if (!node.name) {
+      errors.push(`${nodeIndex}: Missing required field "name"`);
+      continue;
+    }
+
+    // Check for duplicate node names
+    if (nodeNames.has(node.name)) {
+      errors.push(`${nodeIndex} "${node.name}": Duplicate node name`);
+    }
+    nodeNames.add(node.name);
+    nodesByName.set(node.name, node);
+
+    // Check for required type field
+    if (!node.type) {
+      errors.push(`${nodeIndex} "${node.name}": Missing required field "type"`);
+      continue;
+    }
+
+    // Validate node based on type
+    switch (node.type) {
+      case 'trigger':
+        if (!node.triggerType) {
+          errors.push(`${nodeIndex} "${node.name}": trigger node missing required field "triggerType"`);
+        } else if (!['manual', 'app', 'webhook', 'schedule'].includes(node.triggerType)) {
+          errors.push(
+            `${nodeIndex} "${node.name}": invalid triggerType "${node.triggerType}". Must be one of: manual, app, webhook, schedule`
+          );
+        }
+        if (node.triggerType === 'app' && !node.appTriggerId) {
+          errors.push(`${nodeIndex} "${node.name}": app trigger missing required field "appTriggerId"`);
+        }
+        if (node.triggerType === 'schedule') {
+          const scheduleValidation = validateScheduleTrigger(node, nodeIndex);
+          errors.push(...scheduleValidation.errors);
+          warnings.push(...scheduleValidation.warnings);
+        }
+        break;
+
+      case 'promptNode':
+        if (!node.prompt) {
+          errors.push(`${nodeIndex} "${node.name}": promptNode missing required field "prompt"`);
+        }
+        if (!node.displayName || node.displayName.trim() === '') {
+          errors.push(`${nodeIndex} "${node.name}": promptNode missing required non-empty field "displayName"`);
+        }
+        if (node.llmConfig) {
+          if (!node.llmConfig.name) {
+            errors.push(`${nodeIndex} "${node.name}": llmConfig missing required field "name"`);
+          }
+          if (!node.llmConfig.properties) {
+            warnings.push(`${nodeIndex} "${node.name}": llmConfig missing "properties" field`);
+          }
+        }
+        break;
+
+      case 'thinking':
+        if (!node.prompt) {
+          errors.push(`${nodeIndex} "${node.name}": thinking node missing required field "prompt"`);
+        }
+        if (node.humanInTheLoop !== undefined) {
+          errors.push(
+            `${nodeIndex} "${node.name}": thinking node does not support "humanInTheLoop" property (only prompt nodes support this)`
+          );
+        }
+        if (node.canStayOnNode !== undefined) {
+          errors.push(
+            `${nodeIndex} "${node.name}": thinking node does not support "canStayOnNode" property (only prompt nodes support this)`
+          );
+        }
+        if (node.llmConfig) {
+          if (!node.llmConfig.name) {
+            errors.push(`${nodeIndex} "${node.name}": llmConfig missing required field "name"`);
+          }
+          if (!node.llmConfig.properties) {
+            warnings.push(`${nodeIndex} "${node.name}": llmConfig missing "properties" field`);
+          }
+        }
+        break;
+
+      case 'tool':
+        if (!node.toolName) {
+          errors.push(`${nodeIndex} "${node.name}": tool node missing required field "toolName"`);
+        }
+        break;
+
+      case 'junction':
+        // Junction only requires name and type, which we already checked
+        break;
+
+      case 'jumpToNode':
+        if (!node.targetNodeId) {
+          errors.push(`${nodeIndex} "${node.name}": jumpToNode missing required field "targetNodeId"`);
+        }
+        break;
+
+      case 'browserTask':
+        if (!node.prompt) {
+          errors.push(`${nodeIndex} "${node.name}": browserTask node missing required field "prompt"`);
+        }
+        break;
+
+      default:
+        warnings.push(`${nodeIndex} "${node.name}": unknown node type "${node.type}"`);
+    }
+  }
+
+  // Create a map to track which nodes have edges
+  const nodesWithEdges = new Set<string>();
+
+  // Validate edges
+  for (let i = 0; i < flow.edges.length; i++) {
+    const edge = flow.edges[i];
+    const edgeIndex = `Edge ${i + 1}`;
+
+    // Check for required fields
+    if (!edge.source) {
+      errors.push(`${edgeIndex}: Missing required field "source"`);
+      continue;
+    }
+
+    if (!edge.target) {
+      errors.push(`${edgeIndex}: Missing required field "target"`);
+      continue;
+    }
+
+    if (!edge.type) {
+      errors.push(`${edgeIndex}: Missing required field "type"`);
+      continue;
+    }
+
+    // Track nodes that have edges
+    nodesWithEdges.add(edge.source);
+    nodesWithEdges.add(edge.target);
+
+    // Check if source and target nodes exist
+    if (!nodeNames.has(edge.source)) {
+      errors.push(`${edgeIndex}: source node "${edge.source}" does not exist`);
+    }
+
+    if (!nodeNames.has(edge.target)) {
+      errors.push(`${edgeIndex}: target node "${edge.target}" does not exist`);
+    }
+
+    // Validate edge based on type
+    switch (edge.type) {
+      case 'stepForward':
+        // stepForward only requires source, target, and type
+        break;
+
+      case 'promptCondition':
+        if (!edge.prompt) {
+          errors.push(`${edgeIndex}: promptCondition edge missing required field "prompt"`);
+        }
+        break;
+
+      case 'logicalCondition':
+        if (!edge.condition) {
+          errors.push(`${edgeIndex}: logicalCondition edge missing required field "condition"`);
+        }
+        break;
+
+      default:
+        warnings.push(`${edgeIndex}: unknown edge type "${edge.type}"`);
+    }
+  }
+
+  // Check for orphaned nodes (nodes without any edges)
+  // Note: Trigger nodes can be entry points without incoming edges
+  for (const nodeName of nodeNames) {
+    const node = nodesByName.get(nodeName);
+    if (!nodesWithEdges.has(nodeName) && node.type !== 'trigger') {
+      warnings.push(`Node "${nodeName}": orphaned node (not connected to any edges)`);
+    }
+  }
+
+  // Check for trigger nodes - at least one trigger should exist
+  const triggerNodes = flow.nodes.filter((n: any) => n.type === 'trigger');
+  if (triggerNodes.length === 0) {
+    warnings.push('Flow has no trigger nodes (entry points)');
+  }
+
+  const success = errors.length === 0;
+
+  return {
+    success,
+    flowName: flow.name,
+    stats: {
+      nodes: flow.nodes.length,
+      edges: flow.edges.length,
+      nodeTypes: [...new Set(flow.nodes.map((n: any) => n.type))] as string[],
+      edgeTypes: [...new Set(flow.edges.map((e: any) => e.type))] as string[],
+    },
+    errors: errors.length > 0 ? errors : undefined,
+    warnings: warnings.length > 0 ? warnings : undefined,
+    message:
+      errors.length === 0
+        ? warnings.length === 0
+          ? 'Flow is valid with no issues'
+          : `Flow is valid but has ${warnings.length} warning(s)`
+        : `Flow validation failed with ${errors.length} error(s)`,
+  };
+}
+
+interface MindedConfig {
+  flows?: string[];
+  tools?: string[];
+  playbooks?: string[];
+  agent?: string;
+}
+
+/**
+ * Finds all YAML files in a directory recursively.
+ */
+function findYamlFiles(dir: string): string[] {
+  const files: string[] = [];
+
+  if (!fs.existsSync(dir)) {
+    return files;
+  }
+
+  const entries = fs.readdirSync(dir, { withFileTypes: true });
+
+  for (const entry of entries) {
+    const fullPath = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      files.push(...findYamlFiles(fullPath));
+    } else if (entry.isFile() && (entry.name.endsWith('.yaml') || entry.name.endsWith('.yml'))) {
+      files.push(fullPath);
+    }
+  }
+
+  return files;
+}
+
+/**
+ * CLI command handler for validate
+ */
+export function runValidateCommand(): void {
+  const mindedConfigPath = path.join(process.cwd(), 'minded.json');
+
+  // Check if minded.json exists
+  if (!fs.existsSync(mindedConfigPath)) {
+    console.error('Error: minded.json not found in the current directory');
+    console.error('Make sure you are running this command from a MindedJS agent project root');
+    process.exit(1);
+  }
+
+  // Read and parse minded.json
+  let mindedConfig: MindedConfig;
+  try {
+    const configContent = fs.readFileSync(mindedConfigPath, 'utf8');
+    mindedConfig = JSON.parse(configContent);
+  } catch (error) {
+    console.error(`Error: Failed to read or parse minded.json: ${error instanceof Error ? error.message : String(error)}`);
+    process.exit(1);
+  }
+
+  // Get flows folders
+  const flowsFolders = mindedConfig.flows;
+  if (!flowsFolders || flowsFolders.length === 0) {
+    console.error('Error: No flows folders configured in minded.json');
+    process.exit(1);
+  }
+
+  // Find all YAML files in flow folders
+  const flowFiles: string[] = [];
+  for (const folder of flowsFolders) {
+    const resolvedFolder = path.isAbsolute(folder) ? folder : path.join(process.cwd(), folder);
+    flowFiles.push(...findYamlFiles(resolvedFolder));
+  }
+
+  if (flowFiles.length === 0) {
+    console.error('Error: No flow YAML files found in configured flows folders');
+    process.exit(1);
+  }
+
+  console.log(`\nValidating ${flowFiles.length} flow(s)...\n`);
+
+  // Validate each flow
+  const results: { path: string; result: ValidationResult }[] = [];
+  let totalErrors = 0;
+  let totalWarnings = 0;
+
+  for (const flowFile of flowFiles) {
+    const result = validateFlow(flowFile);
+    results.push({ path: flowFile, result });
+    totalErrors += result.errors?.length ?? 0;
+    totalWarnings += result.warnings?.length ?? 0;
+  }
+
+  // Print results for each flow
+  for (const { path: flowPath, result } of results) {
+    const relativePath = path.relative(process.cwd(), flowPath);
+    const statusIcon = result.success ? '✅' : '❌';
+
+    console.log(`${statusIcon} ${relativePath}`);
+
+    if (result.flowName) {
+      console.log(`   Flow: ${result.flowName}`);
+    }
+
+    if (result.stats) {
+      console.log(`   Stats: ${result.stats.nodes} nodes, ${result.stats.edges} edges`);
+    }
+
+    if (result.errors && result.errors.length > 0) {
+      console.log('   Errors:');
+      result.errors.forEach((error) => {
+        console.log(`     ❌ ${error}`);
+      });
+    }
+
+    if (result.warnings && result.warnings.length > 0) {
+      console.log('   Warnings:');
+      result.warnings.forEach((warning) => {
+        console.log(`     ⚠️  ${warning}`);
+      });
+    }
+
+    console.log('');
+  }
+
+  // Print summary
+  const allPassed = totalErrors === 0;
+  console.log('─'.repeat(50));
+
+  if (allPassed) {
+    console.log(`\n✅ All ${flowFiles.length} flow(s) validated successfully!`);
+  } else {
+    console.log(`\n❌ Validation failed!`);
+  }
+
+  console.log(`   Total: ${flowFiles.length} flow(s), ${totalErrors} error(s), ${totalWarnings} warning(s)\n`);
+
+  if (!allPassed) {
+    process.exit(1);
+  }
+}

package/src/playbooks/playbooks.ts

@@ -11,7 +11,8 @@ import { Environment } from '../types/Platform.types';
 export type Playbook = {
   id: string;
   name: string;
-  blocks: OutputBlockData[];
+  blocks?: OutputBlockData[];
+  prompt?: string;
 };
 
 /**
@@ -147,7 +148,7 @@ function loadPlaybooksFromDirectories(directories: string[]): Playbook[] {
         const fileContent = fs.readFileSync(file, 'utf8');
         const playbook = yaml.load(fileContent) as Playbook;
 
-        if (playbook && playbook.name && playbook.blocks) {
+        if (playbook && playbook.name && (playbook.blocks || playbook.prompt)) {
           playbooks.push(playbook);
           logger.info({ msg: `Loaded playbook: ${playbook.name} from ${file}` });
         } else {
@@ -191,7 +192,13 @@ export function combinePlaybooks(playbooks: Playbook[]): string | null {
 
   // Combine all playbooks into sections
   const sections = playbooks.map((playbook) => {
-    const markdownContent = editorJsToMarkdown(playbook.blocks);
+    let markdownContent = playbook.prompt;
+    if (!markdownContent && playbook.blocks) {
+      markdownContent = editorJsToMarkdown(playbook.blocks);
+    }
+    if (!markdownContent) {
+      throw new Error('Playbook must have either a prompt or blocks');
+    }
     return `# ${playbook.name}\n${markdownContent}`;
   });