@ai-setting/roy-agent-cli 1.0.0

package/src/commands/workflow/validators/nodes/merge-node-validator.ts

@@ -0,0 +1,46 @@
+/**
+ * @fileoverview Merge node validator
+ */
+
+import { BaseNodeValidator } from '../node-validator';
+import { ValidationErrorType } from '../types';
+import type { RawNodeDefinition, ValidationError } from '../types';
+
+export class MergeNodeValidator extends BaseNodeValidator {
+  readonly nodeType = 'merge';
+  
+  protected getRequiredFields(): string[] {
+    // No required fields, but depends_on should be validated externally
+    return [];
+  }
+  
+  protected validateTypeSpecific(node: RawNodeDefinition): ValidationError[] {
+    const errors: ValidationError[] = [];
+    
+    const strategy = node.config?.strategy;
+    if (strategy !== undefined) {
+      const validStrategies = ['collect', 'first', 'last', 'merge'];
+      if (typeof strategy === 'string' && !validStrategies.includes(strategy)) {
+        errors.push({
+          type: ValidationErrorType.INVALID_FIELD_TYPE,
+          description: 'Field "strategy" has invalid value',
+          expected: `strategy must be one of: ${validStrategies.join(', ')}`,
+          actual: String(strategy),
+          fix: `Change strategy to one of: ${validStrategies.join(', ')}`,
+          nodeId: node.id,
+        });
+      } else if (typeof strategy !== 'string') {
+        errors.push({
+          type: ValidationErrorType.INVALID_FIELD_TYPE,
+          description: 'Field "strategy" has invalid type',
+          expected: 'strategy must be a string',
+          actual: typeof strategy,
+          fix: 'Change strategy to a string value',
+          nodeId: node.id,
+        });
+      }
+    }
+    
+    return errors;
+  }
+}

package/src/commands/workflow/validators/nodes/skill-node-validator.ts

@@ -0,0 +1,33 @@
+/**
+ * @fileoverview Skill node validator
+ */
+
+import { BaseNodeValidator } from '../node-validator';
+import { ValidationErrorType } from '../types';
+import type { RawNodeDefinition, ValidationError } from '../types';
+
+export class SkillNodeValidator extends BaseNodeValidator {
+  readonly nodeType = 'skill';
+  
+  protected getRequiredFields(): string[] {
+    return ['skill'];
+  }
+  
+  protected validateTypeSpecific(node: RawNodeDefinition): ValidationError[] {
+    const errors: ValidationError[] = [];
+    
+    const skill = node.config?.skill;
+    if (skill !== undefined && typeof skill !== 'string') {
+      errors.push({
+        type: ValidationErrorType.INVALID_FIELD_TYPE,
+        description: 'Field "skill" has invalid type',
+        expected: 'skill must be a string (e.g., "text-summarizer")',
+        actual: `typeof skill is "${typeof skill}"`,
+        fix: `Change skill value to a string: skill: "${String(skill)}"`,
+        nodeId: node.id,
+      });
+    }
+    
+    return errors;
+  }
+}

package/src/commands/workflow/validators/nodes/tool-node-validator.ts

@@ -0,0 +1,54 @@
+/**
+ * @fileoverview Tool node validator
+ */
+
+import { BaseNodeValidator } from '../node-validator';
+import { ValidationErrorType } from '../types';
+import type { RawNodeDefinition, ValidationError } from '../types';
+
+export class ToolNodeValidator extends BaseNodeValidator {
+  readonly nodeType = 'tool';
+  
+  protected getRequiredFields(): string[] {
+    return ['tool'];
+  }
+  
+  protected validateTypeSpecific(node: RawNodeDefinition): import('../types').ValidationError[] {
+    const errors: import('../types').ValidationError[] = [];
+    
+    const tool = node.config?.tool;
+    
+    // Check tool is string
+    if (tool !== undefined && typeof tool !== 'string') {
+      errors.push({
+        type: ValidationErrorType.INVALID_FIELD_TYPE,
+        description: 'Field "tool" has invalid type',
+        expected: 'tool must be a string (e.g., "bash", "read-file")',
+        actual: `typeof tool is "${typeof tool}"`,
+        fix: `Change tool value to a string: tool: "${String(tool)}"`,
+        nodeId: node.id,
+      });
+    }
+    
+    // Check timeout if present
+    const timeoutError = this.checkFieldType(node, 'timeout', 'number', 'positive number (milliseconds)');
+    if (timeoutError) {
+      errors.push(timeoutError);
+    }
+    
+    // Check input if present
+    const input = node.config?.input;
+    if (input !== undefined && (typeof input !== 'object' || input === null || Array.isArray(input))) {
+      errors.push({
+        type: ValidationErrorType.INVALID_FIELD_TYPE,
+        description: 'Field "input" has invalid type',
+        expected: 'input must be an object (key-value pairs)',
+        actual: Array.isArray(input) ? 'array' : typeof input,
+        fix: 'Change input to an object: input: { key: "value" }',
+        nodeId: node.id,
+      });
+    }
+    
+    return errors;
+  }
+}

package/src/commands/workflow/validators/nodes/workflow-node-validator.ts

@@ -0,0 +1,33 @@
+/**
+ * @fileoverview Workflow node validator
+ */
+
+import { BaseNodeValidator } from '../node-validator';
+import { ValidationErrorType } from '../types';
+import type { RawNodeDefinition, ValidationError } from '../types';
+
+export class WorkflowNodeValidator extends BaseNodeValidator {
+  readonly nodeType = 'workflow';
+  
+  protected getRequiredFields(): string[] {
+    return ['workflow_name'];
+  }
+  
+  protected validateTypeSpecific(node: RawNodeDefinition): ValidationError[] {
+    const errors: ValidationError[] = [];
+    
+    const workflowName = node.config?.workflow_name;
+    if (workflowName !== undefined && typeof workflowName !== 'string') {
+      errors.push({
+        type: ValidationErrorType.INVALID_FIELD_TYPE,
+        description: 'Field "workflow_name" has invalid type',
+        expected: 'workflow_name must be a string',
+        actual: `typeof workflow_name is "${typeof workflowName}"`,
+        fix: `Change workflow_name value to a string: workflow_name: "${String(workflowName)}"`,
+        nodeId: node.id,
+      });
+    }
+    
+    return errors;
+  }
+}

package/src/commands/workflow/validators/types.ts

@@ -0,0 +1,78 @@
+/**
+ * @fileoverview Workflow validation types
+ */
+
+/**
+ * Validation error types
+ */
+export enum ValidationErrorType {
+  MISSING_REQUIRED_FIELD = 'MISSING_REQUIRED_FIELD',
+  INVALID_FIELD_TYPE = 'INVALID_FIELD_TYPE',
+  INVALID_NODE_TYPE = 'INVALID_NODE_TYPE',
+  INVALID_REFERENCE = 'INVALID_REFERENCE',
+  CIRCULAR_DEPENDENCY = 'CIRCULAR_DEPENDENCY',
+  EMPTY_NODES = 'EMPTY_NODES',
+  DUPLICATE_NODE_ID = 'DUPLICATE_NODE_ID',
+  INVALID_TEMPLATE_REFERENCE = 'INVALID_TEMPLATE_REFERENCE',
+}
+
+/**
+ * Validation error detail
+ */
+export interface ValidationError {
+  /** Error identifier for programmatic handling */
+  type: ValidationErrorType;
+  /** Human-readable error description */
+  description: string;
+  /** Expected value or format */
+  expected: string;
+  /** Actual value encountered */
+  actual: string;
+  /** Suggested fix */
+  fix: string;
+  /** Node ID if error is node-specific */
+  nodeId?: string;
+  /** Template reference if error is template-related (e.g., "{{nodes.step-one.output}}") */
+  template?: string;
+  /** Referenced node ID if the template references a non-existent node */
+  referencedNodeId?: string;
+}
+
+/**
+ * Validation result
+ */
+export interface ValidationResult {
+  /** Whether validation passed */
+  valid: boolean;
+  /** List of validation errors */
+  errors: ValidationError[];
+  /** Validated workflow name */
+  workflowName?: string;
+  /** Number of nodes validated */
+  nodeCount?: number;
+}
+
+/**
+ * Raw node definition from YAML (before strict typing)
+ */
+export interface RawNodeDefinition {
+  id?: string;
+  type?: string;
+  name?: string;
+  config?: Record<string, unknown>;
+  depends_on?: string[];
+  condition?: string;
+  timeout?: unknown;
+  retry?: unknown;
+}
+
+/**
+ * Raw workflow definition from YAML
+ */
+export interface RawWorkflowDefinition {
+  name?: unknown;
+  version?: unknown;
+  description?: unknown;
+  nodes?: RawNodeDefinition[];
+  config?: unknown;
+}

package/src/commands/workflow/validators/workflow-validator.test.ts

@@ -0,0 +1,273 @@
+/**
+ * @fileoverview WorkflowValidator tests
+ */
+
+import { describe, it, expect } from 'vitest';
+import { WorkflowValidator } from './workflow-validator';
+import { ValidationErrorType } from './types';
+
+describe('WorkflowValidator', () => {
+  const validator = new WorkflowValidator();
+  
+  describe('structure validation', () => {
+    it('should fail when name is missing', () => {
+      const result = validator.validate({
+        nodes: [{ id: 'node-1', type: 'tool', config: { tool: 'echo' } }],
+      });
+      expect(result.valid).toBe(false);
+      expect(result.errors[0].type).toBe(ValidationErrorType.MISSING_REQUIRED_FIELD);
+    });
+    
+    it('should fail when nodes is empty', () => {
+      const result = validator.validate({ name: 'test' });
+      expect(result.valid).toBe(false);
+      expect(result.errors[0].type).toBe(ValidationErrorType.EMPTY_NODES);
+    });
+    
+    it('should pass valid workflow', () => {
+      const result = validator.validate({
+        name: 'test-workflow',
+        version: '1.0',
+        nodes: [
+          { id: 'node-1', type: 'tool', config: { tool: 'echo', message: 'hello' } },
+        ],
+      });
+      expect(result.valid).toBe(true);
+      expect(result.errors).toHaveLength(0);
+    });
+  });
+  
+  describe('node validation', () => {
+    it('should validate tool node', () => {
+      const result = validator.validate({
+        name: 'test',
+        nodes: [{ id: 'node-1', type: 'tool', config: {} }],
+      });
+      expect(result.valid).toBe(false);
+      expect(result.errors.some(e => e.nodeId === 'node-1')).toBe(true);
+    });
+    
+    it('should detect agent node using agentName instead of agent_type', () => {
+      // 常见错误：使用 agentName 而不是 agent_type
+      const result = validator.validate({
+        name: 'test',
+        nodes: [{
+          id: 'agent-1',
+          type: 'agent',
+          config: {
+            agentName: 'my-agent',  // 错误：应该是 agent_type
+            prompt: 'hello world'
+          }
+        }],
+      });
+      expect(result.valid).toBe(false);
+      // 应该有 MISSING_REQUIRED_FIELD 错误
+      expect(result.errors.some(e => 
+        e.type === ValidationErrorType.MISSING_REQUIRED_FIELD && 
+        e.description.includes('agent_type')
+      )).toBe(true);
+    });
+    
+    it('should pass agent node with correct agent_type field', () => {
+      const result = validator.validate({
+        name: 'test',
+        nodes: [{
+          id: 'agent-1',
+          type: 'agent',
+          config: {
+            agent_type: 'general',  // 正确：使用 agent_type
+            prompt: 'hello world'
+          }
+        }],
+      });
+      expect(result.valid).toBe(true);
+    });
+  });
+  
+  describe('dependency validation', () => {
+    it('should fail on invalid reference', () => {
+      const result = validator.validate({
+        name: 'test',
+        nodes: [
+          { id: 'node-1', type: 'tool', config: { tool: 'echo' }, depends_on: ['non-existent'] },
+        ],
+      });
+      expect(result.valid).toBe(false);
+      expect(result.errors.some(e => e.type === ValidationErrorType.INVALID_REFERENCE)).toBe(true);
+    });
+    
+    it('should fail on circular dependency', () => {
+      const result = validator.validate({
+        name: 'test',
+        nodes: [
+          { id: 'node-1', type: 'tool', config: { tool: 'echo' }, depends_on: ['node-2'] },
+          { id: 'node-2', type: 'tool', config: { tool: 'echo' }, depends_on: ['node-1'] },
+        ],
+      });
+      expect(result.valid).toBe(false);
+      expect(result.errors.some(e => e.type === ValidationErrorType.CIRCULAR_DEPENDENCY)).toBe(true);
+    });
+  });
+
+  describe('template reference validation', () => {
+    it('should pass when template references existing node', () => {
+      const result = validator.validate({
+        name: 'test',
+        nodes: [
+          {
+            id: 'step-one',
+            type: 'tool',
+            config: { tool: 'echo', message: 'hello' }
+          },
+          {
+            id: 'step-two',
+            type: 'tool',
+            config: { tool: 'echo', message: '{{step-one.output}}' },
+            depends_on: ['step-one']
+          },
+        ],
+      });
+      expect(result.valid).toBe(true);
+      expect(result.errors.some(e => e.type === ValidationErrorType.INVALID_TEMPLATE_REFERENCE)).toBe(false);
+    });
+
+    it('should fail when template references non-existent node', () => {
+      const result = validator.validate({
+        name: 'test',
+        nodes: [
+          {
+            id: 'step-two',
+            type: 'tool',
+            config: { tool: 'echo', message: '{{non-existent-node.output}}' },
+          },
+        ],
+      });
+      expect(result.valid).toBe(false);
+      const templateError = result.errors.find(e => e.type === ValidationErrorType.INVALID_TEMPLATE_REFERENCE);
+      expect(templateError).toBeDefined();
+      expect(templateError?.referencedNodeId).toBe('non-existent-node');
+      expect(templateError?.fix).toContain('non-existent-node');
+    });
+
+    it('should fail when template uses nodes.xxx syntax with non-existent node', () => {
+      const result = validator.validate({
+        name: 'test',
+        nodes: [
+          {
+            id: 'step-two',
+            type: 'tool',
+            config: { tool: 'echo', message: '{{nodes.missing-step.output}}' },
+          },
+        ],
+      });
+      expect(result.valid).toBe(false);
+      const templateError = result.errors.find(e => e.type === ValidationErrorType.INVALID_TEMPLATE_REFERENCE);
+      expect(templateError).toBeDefined();
+    });
+
+    it('should detect similar node ID with hyphen/underscore mismatch', () => {
+      const result = validator.validate({
+        name: 'test',
+        nodes: [
+          {
+            id: 'step_one',  // underscore
+            type: 'tool',
+            config: { tool: 'echo', message: 'hello' }
+          },
+          {
+            id: 'step-two',
+            type: 'tool',
+            config: { tool: 'echo', message: '{{step-one.output}}' },  // hyphen
+          },
+        ],
+      });
+      expect(result.valid).toBe(false);
+      const templateError = result.errors.find(e => e.type === ValidationErrorType.INVALID_TEMPLATE_REFERENCE);
+      expect(templateError).toBeDefined();
+      expect(templateError?.fix).toContain('step_one');
+    });
+
+    it('should pass when template references workflow input', () => {
+      const result = validator.validate({
+        name: 'test',
+        nodes: [
+          {
+            id: 'step-one',
+            type: 'tool',
+            config: { tool: 'echo', message: '{{input.userName}}' },
+          },
+        ],
+      });
+      expect(result.valid).toBe(true);
+    });
+
+    it('should pass when using $-style template syntax', () => {
+      const result = validator.validate({
+        name: 'test',
+        nodes: [
+          {
+            id: 'step-one',
+            type: 'tool',
+            config: { tool: 'echo', message: 'hello' }
+          },
+          {
+            id: 'step-two',
+            type: 'tool',
+            config: { tool: 'echo', message: '${step-one.output}' },
+            depends_on: ['step-one']
+          },
+        ],
+      });
+      expect(result.valid).toBe(true);
+    });
+
+    it('should fail when $-style template references non-existent node', () => {
+      const result = validator.validate({
+        name: 'test',
+        nodes: [
+          {
+            id: 'step-two',
+            type: 'tool',
+            config: { tool: 'echo', message: '${missing-step.output}' },
+          },
+        ],
+      });
+      expect(result.valid).toBe(false);
+      const templateError = result.errors.find(e => e.type === ValidationErrorType.INVALID_TEMPLATE_REFERENCE);
+      expect(templateError).toBeDefined();
+      expect(templateError?.referencedNodeId).toBe('missing-step');
+    });
+
+    it('should handle nested template references in complex configs', () => {
+      const result = validator.validate({
+        name: 'test',
+        nodes: [
+          {
+            id: 'fetch-data',
+            type: 'tool',
+            config: { tool: 'http-request', url: 'https://api.example.com' }
+          },
+          {
+            id: 'process',
+            type: 'tool',
+            config: {
+              tool: 'transform',
+              data: {
+                source: '{{fetch-data.output.body}}',
+                format: '{{input.format}}',
+                missing: '{{non-existent.output}}'
+              }
+            },
+            depends_on: ['fetch-data']
+          },
+        ],
+      });
+      expect(result.valid).toBe(false);
+      const templateError = result.errors.find(e => 
+        e.type === ValidationErrorType.INVALID_TEMPLATE_REFERENCE &&
+        e.referencedNodeId === 'non-existent'
+      );
+      expect(templateError).toBeDefined();
+    });
+  });
+});