roast-ai 0.1.7 → 0.2.1

data/docs/ITERATION_SYNTAX.md

@@ -0,0 +1,147 @@
+# Using Iteration with Standardized Syntax
+
+## Overview
+
+Roast supports powerful iteration constructs with the `repeat` and `each` workflow steps. These features now support a standardized approach to evaluating expressions using the double-curly braces syntax (`{{...}}`).
+
+## Syntax Options for Iteration Inputs
+
+Both `until` conditions (in `repeat`) and collection expressions (in `each`) accept the following formats:
+
+### 1. Ruby Expressions with `{{...}}` Syntax
+
+For evaluating Ruby code in the workflow context:
+
+```yaml
+# Repeat until a condition is met
+- repeat:
+    steps:
+      - process_item
+    until: "{{output['counter'] >= 5}}"
+    max_iterations: 10
+
+# Iterate over a collection
+- each: "{{output['items'].filter { |item| item.active? }}}"
+  as: "current_item"
+  steps:
+    - process_item
+```
+
+### 2. Bash Commands with `$(...)` Syntax
+
+For executing shell commands and using their results:
+
+```yaml
+# Repeat until a command succeeds
+- repeat:
+    steps:
+      - check_service
+    until: "$(curl -s -o /dev/null -w '%{http_code}' http://service.local/ | grep -q 200)"
+    max_iterations: 20
+
+# Iterate over files returned by a command
+- each: "$(find . -name '*.rb' -type f)"
+  as: "current_file"
+  steps:
+    - process_file
+```
+
+### 3. Step Names (as strings)
+
+For using the result of another step:
+
+```yaml
+# Repeat until a step returns a truthy value
+- repeat:
+    steps:
+      - process_batch
+    until: "check_completion"
+    max_iterations: 100
+
+# Iterate over items returned by a step
+- each: "get_pending_items"
+  as: "pending_item"
+  steps:
+    - process_pending_item
+```
+
+### 4. Prompt Content
+
+For defining prompts directly in the workflow:
+
+```yaml
+# Using a prompt to determine continuation
+- repeat:
+    steps:
+      - process_content
+    until:
+      prompt: prompts/check_completion.md
+      model: claude-3-haiku
+    max_iterations: 10
+
+# Using a prompt to generate a collection
+- each:
+    prompt: prompts/generate_test_cases.md
+    model: claude-3-haiku
+  as: "test_case"
+  steps:
+    - run_test
+```
+
+## Type Coercion
+
+### Smart Defaults
+
+Roast applies intelligent defaults for boolean coercion based on the type of expression:
+
+- **Ruby expressions** (`{{expr}}`) → Regular boolean coercion (`!!value`)
+- **Bash commands** (`$(cmd)`) → Exit code interpretation (0 = true, non-zero = false)
+- **Inline prompts/step names** → LLM boolean interpretation (analyzes yes/no intent)
+
+### Manual Coercion
+
+You can override the smart defaults by specifying `coerce_to` directly in the step:
+
+```yaml
+# Override prompt to use regular boolean instead of LLM boolean
+- repeat:
+    until: "check_condition"
+    coerce_to: boolean
+    steps:
+      - process_item
+
+# Force a step result to be treated as iterable
+- each: "get_items"
+  as: "item"
+  coerce_to: iterable
+  steps:
+    - process: "{{item}}"
+```
+
+Available coercion types:
+- `boolean` - Standard Ruby truthiness (`!!` operator)
+- `llm_boolean` - Natural language yes/no interpretation
+- `iterable` - Convert to array (splits strings on newlines)
+
+## Migrating Existing Workflows
+
+If you're updating existing workflows:
+
+1. For Ruby expressions, wrap them in `{{...}}`:
+   ```yaml
+   # Old
+   until: "output['counter'] >= 5"
+   
+   # New
+   until: "{{output['counter'] >= 5}}"
+   ```
+
+2. Bash commands, step names, and prompts can remain unchanged.
+
+## Best Practices
+
+- Use `{{...}}` for all Ruby expressions to make them explicit
+- For complex conditions, consider creating a dedicated step that returns a boolean
+- For collections, ensure they return iterable objects (arrays, hashes, etc.)
+- Always set reasonable `max_iterations` limits on repeat loops
+- Use meaningful variable names in `each` loops

data/examples/case_when/README.md

@@ -0,0 +1,58 @@
+# Case/When/Else Example
+
+This example demonstrates the use of `case/when/else` control flow in Roast workflows.
+
+## Overview
+
+The `case/when/else` construct allows you to execute different steps based on the value of an expression, similar to Ruby's case statement or switch statements in other languages.
+
+## Syntax
+
+```yaml
+- case: <expression>
+  when:
+    <value1>:
+      - <steps>
+    <value2>:
+      - <steps>
+  else:
+    - <steps>
+```
+
+## Features Demonstrated
+
+1. **Basic case/when/else**: Detect file language and execute language-specific analysis
+2. **Bash command evaluation**: Use environment variables to determine deployment strategy
+3. **Complex expressions**: Use Ruby expressions to categorize numeric values
+
+## Expression Types
+
+The `case` expression can be:
+- A simple string value
+- An interpolated workflow output: `{{ workflow.output.variable }}`
+- A Ruby expression: `{{ workflow.output.count > 10 ? 'high' : 'low' }}`
+- A bash command: `$(echo $ENVIRONMENT)`
+- A reference to a previous step's output
+
+## How It Works
+
+1. The `case` expression is evaluated to produce a value
+2. The value is compared against each key in the `when` clause
+3. If a match is found, the steps under that key are executed
+4. If no match is found and an `else` clause exists, those steps are executed
+5. If no match is found and no `else` clause exists, execution continues
+
+## Running the Example
+
+```bash
+roast execute examples/case_when/workflow.yml
+```
+
+This will process all Ruby, JavaScript, Python, and Go files in the current directory, detecting their language and running appropriate analysis steps.
+
+## Use Cases
+
+- **Multi-language projects**: Different linting/testing for different file types
+- **Environment-specific workflows**: Different deployment steps for prod/staging/dev
+- **Conditional processing**: Different handling based on file size, complexity, or other metrics
+- **Error handling**: Different recovery strategies based on error types

data/examples/case_when/detect_language/prompt.md

@@ -0,0 +1,16 @@
+# Detect Programming Language
+
+Based on the file extension and content, determine the primary programming language of this file:
+- If it's a `.rb` file, return "ruby"
+- If it's a `.js` file, return "javascript"
+- If it's a `.py` file, return "python"
+- If it's a `.go` file, return "go"
+- Otherwise, return "unknown"
+
+Return ONLY the language name in lowercase, nothing else.
+
+File: {{ context.resource_uri }}
+Content:
+```
+{{ context.resource }}
+```

data/examples/case_when/workflow.yml

@@ -0,0 +1,58 @@
+name: "Case/When/Else Example"
+
+tools:
+  - Roast::Tools::Cmd
+  - Roast::Tools::ReadFile
+  - Roast::Tools::WriteFile
+
+target: "**/*.{rb,js,py,go}"
+
+steps:
+  - detect_language
+
+  - case: "{{ workflow.output.detect_language }}"
+    when:
+      ruby:
+        - analyze_ruby
+        - generate_ruby_report
+      javascript:
+        - analyze_javascript
+        - generate_js_report
+      python:
+        - analyze_python
+        - generate_python_report
+      go:
+        - analyze_go
+        - generate_go_report
+    else:
+      - analyze_generic
+      - generate_generic_report
+
+  # Another example using bash command for case expression
+  - get_environment: $(echo $ENVIRONMENT || echo "development")
+
+  - case: "{{ workflow.output.get_environment }}"
+    when:
+      production:
+        - production_checks
+        - deploy_production
+      staging:
+        - staging_checks
+        - deploy_staging
+      development:
+        - run_tests
+        - local_deploy
+    else:
+      - unknown_environment
+
+  # Example with numeric case values
+  - count_issues
+
+  - case: "{{ workflow.output.count_issues.to_i > 10 ? 'high' : workflow.output.count_issues.to_i > 5 ? 'medium' : 'low' }}"
+    when:
+      high:
+        - high_priority_alert
+      medium:
+        - medium_priority_notice
+      low:
+        - low_priority_info

data/examples/conditional/README.md

@@ -0,0 +1,161 @@
+# Conditional Execution in Roast Workflows
+
+This example demonstrates how to use conditional execution (`if` and `unless`) in Roast workflows.
+
+## Overview
+
+Conditional execution allows workflows to execute different steps based on runtime conditions. This feature supports:
+
+- `if` conditions - execute steps when a condition is true
+- `unless` conditions - execute steps when a condition is false  
+- `then` branches - steps to execute when the condition matches
+- `else` branches - steps to execute when the condition doesn't match (optional, only for `if`)
+
+## Syntax
+
+### If Statement
+
+```yaml
+- if: "{{expression}}"
+  then:
+    - step1
+    - step2
+  else:
+    - step3
+    - step4
+```
+
+### Unless Statement
+
+```yaml
+- unless: "{{expression}}"
+  then:
+    - step1
+    - step2
+```
+
+## Condition Types
+
+Conditions can be:
+
+1. **Ruby Expressions** - Wrapped in `{{...}}`
+   ```yaml
+   - if: "{{output.previous_step.success == true}}"
+   ```
+
+2. **Bash Commands** - Wrapped in `$(...)`
+   ```yaml
+   - if: "$(test -f /path/to/file && echo true || echo false)"
+   ```
+
+3. **Step References** - Reference to previous step output
+   ```yaml
+   - if: "check_condition"  # References a previous step
+   ```
+
+4. **File Checks**
+   ```yaml
+   - if: "{{File.exist?('/tmp/myfile.txt')}}"
+   ```
+
+## Examples
+
+### Basic Example
+
+```yaml
+name: Conditional Example
+tools:
+  - Roast::Tools::Cmd
+
+steps:
+  - check_status: "echo 'success'"
+  
+  - if: "{{output.check_status.strip == 'success'}}"
+    then:
+      - success_action: "echo 'Operation succeeded!'"
+    else:
+      - failure_action: "echo 'Operation failed!'"
+```
+
+### Unless Example
+
+```yaml
+name: Unless Example
+tools: []
+
+steps:
+  - check_file: "test -f /tmp/important.txt && echo exists || echo missing"
+  
+  - unless: "{{output.check_file.strip == 'exists'}}"
+    then:
+      - create_file: "touch /tmp/important.txt"
+      - notify: "echo 'Created missing file'"
+```
+
+### Nested Conditionals
+
+```yaml
+name: Nested Conditionals
+tools: []
+
+steps:
+  - outer_check: "echo 'true'"
+  - inner_check: "echo 'false'"
+  
+  - if: "{{output.outer_check.strip == 'true'}}"
+    then:
+      - if: "{{output.inner_check.strip == 'true'}}"
+        then:
+          - both_true: "echo 'Both conditions are true'"
+        else:
+          - only_outer: "echo 'Only outer condition is true'"
+    else:
+      - outer_false: "echo 'Outer condition is false'"
+```
+
+### Platform-Specific Actions
+
+```yaml
+name: Platform Detection
+tools:
+  - Roast::Tools::Cmd
+
+steps:
+  - detect_os: "uname -s"
+  
+  - if: "{{output.detect_os.strip == 'Darwin'}}"
+    then:
+      - mac_setup: "brew --version || echo 'Homebrew not installed'"
+    else:
+      - if: "{{output.detect_os.strip == 'Linux'}}"
+        then:
+          - linux_setup: "apt-get --version || yum --version"
+        else:
+          - unknown_os: "echo 'Unknown operating system'"
+```
+
+## Best Practices
+
+1. **Use Clear Conditions**: Make your conditions explicit and easy to understand
+2. **Handle Edge Cases**: Always consider what happens when conditions fail
+3. **Test Both Branches**: Ensure both `then` and `else` branches work correctly
+4. **Avoid Deep Nesting**: Keep conditional logic simple and readable
+5. **Use Unless Sparingly**: `unless` can be less intuitive than `if` with negation
+
+## Debugging
+
+To debug conditional execution:
+
+1. Check the workflow output to see which branch was executed
+2. Look for keys like `if_condition_name` or `unless_condition_name` in the output
+3. These keys contain information about the condition evaluation and branch taken
+
+## Running the Example
+
+```bash
+# Run the simple conditional example
+roast execute examples/conditional/simple_workflow.yml
+
+# Run the full conditional example (requires API configuration)
+roast execute examples/conditional/workflow.yml
+```

data/examples/conditional/check_condition/prompt.md

@@ -0,0 +1 @@
+Check if the OS is macOS or Linux and return true if it's macOS, false otherwise.

data/examples/conditional/simple_workflow.yml

@@ -0,0 +1,15 @@
+name: Simple Conditional Test
+tools: []
+
+steps:
+  - set_value: "$(echo 'true')"
+  
+  - if: "{{output.set_value.strip == 'true'}}"
+    then:
+      - success: "$(echo 'If condition worked!')"
+    else:
+      - failure: "$(echo 'If condition failed!')"
+  
+  - unless: "{{output.set_value.strip == 'false'}}"
+    then:
+      - unless_success: "$(echo 'Unless condition worked!')"

data/examples/conditional/workflow.yml

@@ -0,0 +1,23 @@
+name: Conditional Execution Example
+tools:
+  - Roast::Tools::Cmd
+
+steps:
+  - check_os: "$(uname -s)"
+  
+  - if: "{{output.check_os.strip == 'Darwin'}}"
+    then:
+      - mac_message: "$(echo 'Running on macOS!')"
+      - mac_info: "$(sw_vers)"
+    else:
+      - linux_message: "$(echo 'Running on Linux!')"
+      - linux_info: "$(lsb_release -a)"
+  
+  - check_file: "$(test -f /tmp/roast_test.txt && echo exists || echo missing)"
+  
+  - unless: "{{output.check_file.strip == 'exists'}}"
+    then:
+      - create_file: "$(touch /tmp/roast_test.txt && echo 'File created')"
+  
+  - verify_file: "$(ls -la /tmp/roast_test.txt)"
+  - cleanup: "$(rm -f /tmp/roast_test.txt)"

data/examples/direct_coerce_syntax/README.md

@@ -0,0 +1,32 @@
+# Direct Coerce Syntax
+
+This example demonstrates the simplified syntax for specifying `coerce_to` and other configuration options directly on iteration steps.
+
+## Direct Syntax
+
+Configuration options are specified directly on the step:
+
+```yaml
+- repeat:
+    until: "condition"
+    coerce_to: boolean
+    print_response: true
+    model: "claude-3-haiku"
+    steps: [...]
+```
+
+## Benefits
+
+1. **Cleaner YAML** - No unnecessary nesting
+2. **More intuitive** - Configuration options are at the same level as other step properties
+3. **Consistent** - Matches how other step properties are specified
+
+## Supported Options
+
+All step configuration options can be specified directly:
+- `coerce_to` - Type coercion (boolean, llm_boolean, iterable)
+- `print_response` - Whether to print LLM responses
+- `loop` - Auto-loop behavior
+- `json` - JSON response mode
+- `params` - Additional parameters
+- `model` - Model override

data/examples/direct_coerce_syntax/workflow.yml

@@ -0,0 +1,36 @@
+name: Direct Coerce Syntax Demo
+description: Demonstrates the simplified coerce_to syntax without config blocks
+
+steps:
+  # Example 1: Direct coerce_to on repeat
+  - repeat:
+      until: "check_api_ready"
+      coerce_to: boolean  # Direct syntax - no config block needed
+      max_iterations: 5
+      steps:
+        - check_api_ready:
+            prompt: "Check if the API endpoint returns a 200 status"
+        - wait: 2
+  
+  # Example 2: Direct coerce_to on each  
+  - get_data_sources:
+      prompt: "List available data sources, one per line"
+  
+  - each: "get_data_sources"
+    as: "source"
+    coerce_to: iterable  # Direct syntax
+    steps:
+      - validate_source: "Validating {{source}}..."
+      - process_source:
+          prompt: "Process data from {{source}}"
+  
+  # Example 3: Multiple configuration options
+  - repeat:
+      until: "all_tests_pass"
+      coerce_to: llm_boolean  # Override default
+      print_response: true     # Other options work too
+      max_iterations: 10
+      steps:
+        - run_tests: "$(rake test)"
+        - all_tests_pass:
+            prompt: "Did all tests pass successfully?"

data/examples/dot_notation/README.md

@@ -0,0 +1,37 @@
+# Dot Notation Access Example
+
+This example demonstrates the new dot notation access feature for workflow outputs.
+
+## Usage
+
+With the new dot notation feature, you can access output values using Ruby's method syntax instead of hash syntax:
+
+### Before (hash syntax):
+```yaml
+until: "output[:update_fix_count][:fixes_applied] >= 5 || output[:select_next_issue][:no_issues_left] == true"
+```
+
+### After (dot notation):
+```yaml
+until: "output.update_fix_count.fixes_applied >= 5 || output.select_next_issue.no_issues_left?"
+```
+
+### Even cleaner (omitting output prefix):
+```yaml
+until: "update_fix_count.fixes_applied >= 5 || select_next_issue.no_issues_left?"
+```
+
+## Features
+
+1. **Nested access**: `output.step_name.nested.value`
+2. **Boolean predicates**: `output.step_name.is_complete?` returns false for nil/false values
+3. **Direct access**: Omit the `output.` prefix for cleaner syntax
+4. **Backward compatible**: Hash syntax still works (`output[:step_name][:value]`)
+
+## Example Workflow
+
+See `workflow.yml` for a complete example that demonstrates:
+- Setting values in output
+- Using dot notation in conditions
+- Boolean predicate methods
+- Nested value access

data/examples/dot_notation/workflow.yml

@@ -0,0 +1,44 @@
+name: dot_notation_example
+description: Example demonstrating dot notation access for workflow outputs
+
+steps:
+  initialize:
+    prompt: |
+      Initialize the workflow with some sample data.
+      
+      Set output.counter to 0
+      Set output.config.max_iterations to 5
+      Set output.config.enabled to true
+
+  process_items:
+    repeat:
+      # Using dot notation in conditions
+      until: "counter >= config.max_iterations || !config.enabled?"
+      steps:
+        - increment_counter
+        - check_status
+
+  increment_counter:
+    prompt: |
+      Increment the counter by 1.
+      Current counter value: {{counter}}
+      
+      Set output.counter to {{counter}} + 1
+
+  check_status:
+    prompt: |
+      Check if we should continue processing.
+      
+      Current counter: {{counter}}
+      Max iterations: {{config.max_iterations}}
+      
+      If counter is 3, set output.config.enabled to false
+      Set output.status.last_checked to current counter value
+
+  summarize:
+    prompt: |
+      Summarize the results:
+      - Total iterations: {{counter}}
+      - Last checked at: {{status.last_checked}}
+      - Was enabled: {{config.enabled}}
+      - Hit max iterations: {{counter >= config.max_iterations ? "Yes" : "No"}}

data/examples/exit_on_error/README.md

@@ -0,0 +1,50 @@
+# Exit on Error Example
+
+This example demonstrates how to use the `exit_on_error` configuration option to continue workflow execution even when a command fails.
+
+## Use Case
+
+When running a linter like RuboCop on a file with syntax errors or style violations, the command will exit with a non-zero status. By default, this would halt the workflow. However, we often want to:
+
+1. Capture the linter output (including errors)
+2. Analyze what went wrong
+3. Apply fixes based on the analysis
+
+## Configuration
+
+The key configuration is in the step configuration section:
+
+```yaml
+lint_check:
+  exit_on_error: false
+```
+
+This tells Roast to:
+- Continue workflow execution even if the command fails
+- Capture the full output (stdout and stderr)
+- Append the exit status to the output
+
+## Output Format
+
+When a command fails with `exit_on_error: false`, the output will look like:
+
+```
+lib/example.rb:5:3: C: Style/StringLiterals: Prefer double-quoted strings
+  'hello'
+  ^^^^^^^
+[Exit status: 1]
+```
+
+This allows subsequent steps to process both the error output and the exit status.
+
+## Running the Example
+
+```bash
+roast execute workflow.yml path/to/file.rb
+```
+
+The workflow will:
+1. Run RuboCop on the file
+2. Continue even if RuboCop finds issues
+3. Analyze the linter output
+4. Apply fixes based on the analysis

data/examples/exit_on_error/analyze_lint_output/prompt.md

@@ -0,0 +1,9 @@
+The linter output from the previous step shows issues with the code.
+Please analyze the output and identify the specific problems that need to be fixed.
+
+Focus on:
+- Syntax errors
+- Style violations
+- Best practice violations
+
+Provide a structured list of issues found.