messages

Adding New Message Types Guide

Use this guide to add a new message type to the safe-output messages system so it works in frontmatter, compiler parsing, JavaScript, and bundling.

Overview

The messages system lets workflow authors customize safe-output messages. Message flow:

1. Frontmatter (YAML) → 2. JSON Schema → 3. Go Compiler → 4. JavaScript Modules → 5. Bundler

Step 1: Update JSON Schema

Add the new message field to pkg/parser/schemas/main_workflow_schema.json in the messages object:

{
  "messages": {
    "properties": {
      "my-new-message": {
        "type": "string",
        "description": "Description of when this message is used. Available placeholders: {placeholder1}, {placeholder2}.",
        "examples": [
          "Example message with {placeholder1}"
        ]
      }
    }
  }
}

Key points:

• Use kebab-case for the YAML field name (e.g., my-new-message)
• Document all available placeholders in the description
• Provide helpful examples
• Run make build after changes (schema is embedded in binary)

Step 2: Update Go Struct

Add the new field to SafeOutputMessagesConfig in pkg/workflow/compiler.go:

type SafeOutputMessagesConfig struct {
	// ... existing fields ...
	MyNewMessage string `yaml:"my-new-message,omitempty" json:"myNewMessage,omitempty"` // Description of the message
}

Key points:

• Use CamelCase for Go field name
• Use kebab-case for YAML tag (matches frontmatter)
• Use camelCase for JSON tag (used in JavaScript)
• Add omitempty to both tags

Step 3: Update Go Parser

If needed, update the parser in pkg/workflow/safe_outputs.go:

func parseMessagesConfig(messagesMap map[string]any) *SafeOutputMessagesConfig {
	config := &SafeOutputMessagesConfig{}
	// ... existing parsing ...
	
	if myNewMessage, ok := messagesMap["my-new-message"].(string); ok {
		config.MyNewMessage = myNewMessage
	}
	
	return config
}

Note: The parser uses reflection for most fields, so this step may not be needed for simple string fields.