workflow-validator

Validate workflow.json files for Build0 agents without executing them.

Installation

npm install -g workflow-validator

Or use directly with npx:

npx workflow-validator workflow.json

Usage

CLI

# Validate a workflow file
validate-workflow workflow.json

# Or with npx
npx workflow-validator workflow.json

Exit codes:

• 0 - Workflow is valid
• 1 - Workflow is invalid or file not found

Programmatic Usage

import { validateWorkflowFile, WorkflowSchema } from 'workflow-validator';

// Validate a file
const result = validateWorkflowFile('./workflow.json');
if (result.valid) {
  console.log('Valid workflow:', result.workflow);
} else {
  console.error('Errors:', result.errors);
}

// Or use the Zod schema directly
import { WorkflowSchema } from 'workflow-validator/schemas';

const workflow = WorkflowSchema.parse(jsonData);

Validation Rules

Schema Validation (Zod)

1. Required top-level fields: name, version, steps
2. Steps array must be non-empty
3. Each step must have id, type, name
4. Step type must be "command" or "sleep"
5. Command steps require command field
6. Sleep steps require positive duration field

Semantic Validation

7. All step IDs must be unique
8. onErrorGoto must reference an existing step ID
9. If onErrorGoto is present, onError must be "goto"
10. Step references in templates (steps['id'].output) must reference earlier steps
11. Template braces {{ }} must be balanced

Optional References

References using optional chaining (steps['id']?.output) are treated as optional and are allowed to:

• Reference steps defined later in the workflow (forward references)
• Reference steps that may not exist

This supports loop patterns where the first iteration uses one step's output and subsequent iterations use another's.

Workflow Structure

{
  "name": "My Workflow",
  "version": "1.0",
  "steps": [
    {
      "id": "step-1",
      "type": "command",
      "name": "Run command",
      "command": "echo hello",
      "env": {
        "VAR": "{{ input.value }}"
      },
      "retries": 2,
      "retryDelay": 1000,
      "onError": "goto",
      "onErrorGoto": "error-handler",
      "if": "{{ condition }}"
    },
    {
      "id": "step-2",
      "type": "sleep",
      "name": "Wait",
      "duration": 5000
    }
  ]
}

License

MIT