roast-ai 0.2.0 → 0.2.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8ab27704514fc6ddfa09003464d2aa324b852379b0548619e2f0023bebe793ae
-  data.tar.gz: 18c0936f2b5dc2b54ef420be2ac089b8252f64a02227ab33d98db9d2e6249136
+  metadata.gz: 64b0bfad5bc7ce9abd2d750ff52695ba997a750556a403e3ab4fc449dfb28946
+  data.tar.gz: 526beebc0ca0697df5ce2f871468fff246440615634ae516439b4c0740f8ce90
 SHA512:
-  metadata.gz: 50552385cdb280592a1e331c4a3ec5de2924fa05636af5deb742b96f2fde229e3448e61e6516e570c02a8dc0f416a3b9a3c3d884a800eb89987c90c856a0258d
-  data.tar.gz: 8feeb510d87e6e6256c46cbca3e13fbc65701ceb28b049452e5bea2f44815f7770e688f8422487b431a85c5f459beffadcce590e7b860cde8a1ab4ee939ff50e
+  metadata.gz: 0600537a7242638e683a884a0b22b4d5f7fd58bb02d0c7a04240c8720d197a1f4f5e2d5f44c1a7f0335506f7822b51b6c245fd1c5f25627c8a580319d63b1250
+  data.tar.gz: e368630d036c6c3ac6efe00d102ddbf89d438332916ed1adb5aa54fe6cb5f9b34f9adf637c6e36c5baab07015c6f0fb848f675476d4233accd005a98b9630642

data/.github/workflows/ci.yaml

@@ -17,10 +17,14 @@ jobs:
       matrix:
         os: [ubuntu]
         ruby: ['3.2', '3.3', '3.4']
+        gemfile: ['activesupport7', 'activesupport8']
     runs-on: ${{ matrix.os }}-latest
-    continue-on-error: ${{ matrix.ruby == 'ruby-head' }}
+    env:
+      BUNDLE_GEMFILE: ${{ github.workspace }}/gemfiles/${{ matrix.gemfile }}.gemfile
     steps:
       - uses: actions/checkout@v4
+      - name: Install ripgrep
+        run: sudo apt-get update && sudo apt-get install -y ripgrep
       - uses: ruby/setup-ruby@v1
         with:
           ruby-version: ${{ matrix.ruby }}

data/.gitignore

@@ -11,4 +11,32 @@
 **/.claude/settings.local.json
 
 **/CLAUDE.local.md
-.roast/
+.roast/
+
+bin/_guard-core
+bin/bundle
+bin/coderay
+bin/dotenv
+bin/erb
+bin/guard
+bin/htmldiff
+bin/irb
+bin/ldiff
+bin/listen
+bin/pry
+bin/racc
+bin/rake
+bin/rbs
+bin/rdbg
+bin/rdoc
+bin/ri
+bin/rubocop
+bin/ruby-lsp
+bin/ruby-lsp-check
+bin/ruby-lsp-launcher
+bin/ruby-lsp-test-exec
+bin/ruby-parse
+bin/ruby-rewrite
+bin/thor
+
+gemfiles/*.lock

data/CHANGELOG.md

@@ -5,6 +5,42 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.2.2] - 2025-05-29
+
+### Added
+- Pre/post processing framework for workflows with `pre_processing` and `post_processing` sections (#86)
+  - Support for `output.txt` ERB templates in post-processing phase for custom output formatting
+  - Pre/post processing support for single-target workflows (not just multi-target)
+  - Simplified access to pre-processing data in target workflows (removed `output` intermediary level)
+- Verbose mode improvements for better debugging experience (#98)
+  - Command outputs are now displayed when using the `--verbose` flag
+  - Commands executed within conditional branches also show output in verbose mode
+- User-friendly error reporting for workflow failures (#98)
+  - Clear ❌ indicators when commands or steps fail
+  - Command failures show exit status and output (no verbose needed for failures)
+  - Step failures provide helpful context about what might be wrong
+  - Exit handler displays actionable suggestions for resolving issues
+- Automatic workflow discovery by name (#97)
+  - Can now run workflows by name without full path: `roast execute my_workflow`
+  - Automatically looks for `roast/my_workflow/workflow.yml` in current directory
+- Configurable base URI for API endpoints (#83)
+
+### Fixed
+- Search file tool now correctly prefixes paths when searching (#92)
+- Support for Ruby projects using ActiveSupport 7.0+ (#95)
+
+### Changed
+- ActiveSupport dependency relaxed to >= 7.0 for broader compatibility
+
+## [0.2.1]
+
+### Added
+- Smart coercion defaults for boolean expressions based on step type
+  - Ruby expressions (`{{expr}}`) default to regular boolean coercion
+  - Bash commands (`$(cmd)`) default to exit code interpretation
+  - Inline prompts and regular steps default to "smart" LLM-powered interpretation (looks for truthy or falsy language)
+- Direct syntax for step configuration - `coerce_to` and other options are now specified directly on iteration steps
+
 ## [0.2.0] - 2025-05-26
 
 ### Added

data/CLAUDE.md

@@ -50,6 +50,11 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
   - IterationExecutor handles iterations (each, repeat)
   - ConditionalExecutor handles conditionals (if, unless)
   - Don't combine different responsibilities in one class
+- **Do not implement prompts "inline" using a prompt: attribute nested under step names, that violates the primary design architecture of Roast**
+
+## Guidance and Expectations
+
+- Do not decide unilaterally to leave code for the sake of "backwards compatibility"... always run those decisions by me first.
 
 ## Git Workflow Practices
 

data/CLAUDE_NOTES.md

@@ -0,0 +1,68 @@
+# Important Notes for Claude
+
+## Roast Workflow Syntax
+
+### IMPORTANT: No inline configuration for steps!
+
+Roast workflows DO NOT support inline configuration syntax like this:
+```yaml
+# WRONG - This syntax does NOT exist:
+steps:
+  - step_name:
+      prompt: "some prompt"
+      output: variable_name
+```
+
+The correct syntax is:
+```yaml
+# CORRECT - Steps are just names or hash assignments:
+steps:
+  - step_name
+  - variable_name: step_name
+  - variable_name: $(command)
+```
+
+### Control flow structures
+
+Only control flow structures (if/unless, case/when/else, each, repeat) support nested configuration:
+
+```yaml
+steps:
+  # Simple step - just the name
+  - detect_language
+  
+  # Variable assignment
+  - my_var: detect_language
+  
+  # Command execution with assignment
+  - env_type: $(echo $ENVIRONMENT)
+  
+  # Control flow - these DO have nested structure
+  - if: "{{ condition }}"
+    then:
+      - step1
+      - step2
+      
+  - case: "{{ expression }}"
+    when:
+      value1:
+        - step1
+      value2:
+        - step2
+    else:
+      - step3
+```
+
+### Step Configuration
+
+Step configuration (prompts, outputs, etc.) is handled through:
+1. File naming conventions (step_name/prompt.md, step_name/output.txt)
+2. The workflow configuration file itself (tools, target, etc.)
+
+NOT through inline step configuration in the steps array.
+
+## Remember:
+- Steps array contains step names, not step configurations
+- Only control flow structures have nested configuration
+- Variable assignment uses hash syntax: `var_name: step_name`
+- Commands use $() syntax: `var_name: $(command)`

data/Gemfile.lock

@@ -1,8 +1,8 @@
 PATH
   remote: .
   specs:
-    roast-ai (0.2.0)
-      activesupport (~> 8.0)
+    roast-ai (0.2.2)
+      activesupport (>= 7.0)
       cli-ui
       diff-lcs (~> 1.5)
       faraday-retry
@@ -13,7 +13,7 @@ PATH
 GEM
   remote: https://rubygems.org/
   specs:
-    activesupport (8.0.2)
+    activesupport (7.2.2.1)
       base64
       benchmark (>= 0.3)
       bigdecimal
@@ -25,7 +25,6 @@ GEM
       minitest (>= 5.1)
       securerandom (>= 0.3)
       tzinfo (~> 2.0, >= 2.0.5)
-      uri (>= 0.13.1)
     addressable (2.8.7)
       public_suffix (>= 2.0.2, < 7.0)
     ast (2.4.3)

data/README.md

@@ -4,6 +4,18 @@
 
 A convention-oriented framework for creating structured AI workflows, maintained by the Augmented Engineering team at Shopify.
 
+## Installation
+
+```bash
+$ gem install roast-ai
+```
+
+Or add to your Gemfile:
+
+```ruby
+gem 'roast-ai'
+```
+
 ## Why you should use Roast
 
 Roast provides a structured, declarative approach to building AI workflows with:
@@ -64,6 +76,42 @@ steps:
   - Summarize the changes made to {{File.basename(file)}}.
 ```
 
+## Try it
+
+If you don’t have one already, get an OpenAI key from [here](https://platform.openai.com/settings/organization/api-keys). You will need an account with a credit card, make sure that a basic completion works.
+
+```bash
+export OPENAI_API_KEY=sk-proj-....
+
+curl -H "Content-Type: application/json" \
+    -H "Authorization: Bearer $API_TOKEN" \
+    -d '{"model":"gpt-4.1-mini","messages":[{"role":"user","content":"What is 1+1?"}]}' \
+    https://api.openai.com/v1/chat/completions
+```
+
+The [test grading workflow](examples/grading/workflow.md) in this repository is a senior software engineer and testing expert that evaluates the quality of a test based on guidelines.
+
+Try the workflow.
+
+```bash
+./exe/roast execute examples/grading/workflow.yml test/roast/resources_test.rb
+
+🔥🔥🔥 Everyone loves a good roast 🔥🔥🔥
+...
+```
+
+This will output a test grade.
+
+```
+========== TEST GRADE REPORT ==========
+Test file: test/roast/resources_test.rb
+
+FINAL GRADE:
+  Score: 80/100
+  Letter Grade: B
+```
+Note that you may also need `shadowenv` and `rg`, on MacOS run `brew install shadowenv` and `brew install rg`.
+
 ## How to use Roast
 
 1. Create a workflow YAML file defining your steps and tools
@@ -76,6 +124,9 @@ roast execute workflow.yml target_file.rb
 
 # Or for a targetless workflow (API calls, data generation, etc.)
 roast execute workflow.yml
+
+# Roast will automatically search in `project_root/roast/workflow_name` if the path is incomplete.
+roast execute my_cool_workflow # Equivalent to `roast execute roast/my_cool_workflow/workflow.yml
 ```
 
 ### Understanding Workflows
@@ -178,7 +229,37 @@ Roast supports several types of steps:
    - Until conditions: `until: "{{condition}}"`
    - Maximum iterations: `max_iterations: 10`
 
-6. **Raw prompt step**: Simple text prompts for the model without tools
+6. **Case/when/else steps**: Select different execution paths based on a value (similar to Ruby's case statement)
+   ```yaml
+   steps:
+     - detect_language
+     
+     - case: "{{ workflow.output.detect_language }}"
+       when:
+         ruby:
+           - lint_with_rubocop
+           - test_with_rspec
+         javascript:
+           - lint_with_eslint
+           - test_with_jest
+         python:
+           - lint_with_pylint
+           - test_with_pytest
+       else:
+         - analyze_generic
+         - generate_basic_report
+   ```
+   
+   Case expressions can be:
+   - Workflow outputs: `case: "{{ workflow.output.variable }}"`
+   - Ruby expressions: `case: "{{ count > 10 ? 'high' : 'low' }}"`
+   - Bash commands: `case: "$(echo $ENVIRONMENT)"`
+   - Direct values: `case: "production"`
+   
+   The value is compared against each key in the `when` clause, and matching steps are executed.
+   If no match is found, the `else` steps are executed (if provided).
+
+7. **Raw prompt step**: Simple text prompts for the model without tools
    ```yaml
    steps:
      - Summarize the changes made to the codebase.
@@ -398,9 +479,9 @@ Benefits of using OpenRouter:
 
 When using OpenRouter, specify fully qualified model names including the provider prefix (e.g., `anthropic/claude-3-opus-20240229`).
 
-#### Dynamic API Tokens
+#### Dynamic API Tokens and URIs
 
-Roast allows you to dynamically fetch API tokens using shell commands directly in your workflow configuration:
+Roast allows you to dynamically fetch attributes such as API token and URI base (to use with a proxy) via shell commands directly in your workflow configuration:
 
 ```yaml
 # This will execute the shell command and use the result as the API token
@@ -412,8 +493,13 @@ api_token: $(echo $OPENAI_API_KEY)
 # For OpenRouter (requires api_provider setting)
 api_provider: openrouter
 api_token: $(echo $OPENROUTER_API_KEY)
-```
 
+# Static Proxy URI
+uri_base: https://proxy.example.com/v1
+
+# Dynamic Proxy URI
+uri_base: $(echo $AI_PROXY_URI_BASE)
+```
 
 This makes it easy to use environment-specific tokens without hardcoding credentials, especially useful in development environments or CI/CD pipelines. Alternatively, Roast will fall back to `OPENROUTER_API_KEY` or `OPENAI_API_KEY` environment variables based on the specified provider.
 
@@ -668,18 +754,157 @@ your-project/
   └── ...
 ```
 
-## Installation
+### Pre/Post Processing Framework
 
-```bash
-$ gem install roast-ai
+Roast supports pre-processing and post-processing phases for workflows. This enables powerful workflows that need setup/teardown or result aggregation across all processed files.
+
+#### Overview
+
+- **Pre-processing**: Steps executed once before any targets are processed
+- **Post-processing**: Steps executed once after all targets have been processed
+- **Shared state**: Pre-processing results are available to all subsequent steps
+- **Result aggregation**: Post-processing has access to all workflow execution results
+- **Single-target support**: Pre/post processing works with single-target workflows too
+- **Output templates**: Post-processing supports `output.txt` templates for custom formatting
+
+#### Configuration
+
+```yaml
+name: optimize_tests
+model: gpt-4o
+target: "test/**/*_test.rb"
+
+# Pre-processing steps run once before any test files
+pre_processing:
+  - gather_baseline_metrics
+  - setup_test_environment
+
+# Main workflow steps run for each test file
+steps:
+  - analyze_test
+  - improve_coverage
+  - optimize_performance
+
+# Post-processing steps run once after all test files
+post_processing:
+  - aggregate_results
+  - generate_report
+  - cleanup_environment
 ```
 
-Or add to your Gemfile:
+#### Directory Structure
 
-```ruby
-gem 'roast-ai'
+Pre and post-processing steps follow the same conventions as regular steps but are organized in their own directories:
+
+```
+workflow.yml
+pre_processing/
+  ├── gather_baseline_metrics/
+  │   └── prompt.md
+  └── setup_test_environment/
+      └── prompt.md
+analyze_test/
+  └── prompt.md
+improve_coverage/
+  └── prompt.md
+optimize_performance/
+  └── prompt.md
+post_processing/
+  ├── output.txt
+  ├── aggregate_results/
+  │   └── prompt.md
+  ├── generate_report/
+  │   └── prompt.md
+  └── cleanup_environment/
+      └── prompt.md
 ```
 
+#### Data Access
+
+**Pre-processing results in target workflows:**
+
+Target workflows have access to pre-processing results through the `pre_processing_data` variable with dot notation:
+
+```erb
+# In a target workflow step prompt
+The baseline metrics from pre-processing:
+<%= pre_processing_data.gather_baseline_metrics %>
+
+Environment setup details:
+<%= pre_processing_data.setup_test_environment %>
+```
+
+**Post-processing data access:**
+
+Post-processing steps have access to:
+
+- `pre_processing`: Direct access to pre-processing results with dot notation
+- `targets`: Hash of all target workflow results, keyed by file paths
+
+Example post-processing prompt:
+```markdown
+# Generate Summary Report
+
+Based on the baseline metrics:
+<%= pre_processing.gather_baseline_metrics %>
+
+Environment configuration:
+<%= pre_processing.setup_test_environment %>
+
+And the results from processing all files:
+<% targets.each do |file, target| %>
+File: <%= file %>
+Analysis results: <%= target.output.analyze_test %>
+Coverage improvements: <%= target.output.improve_coverage %>
+Performance optimizations: <%= target.output.optimize_performance %>
+<% end %>
+
+Please generate a comprehensive summary report showing:
+1. Overall improvements achieved
+2. Files with the most significant changes
+3. Recommendations for further optimization
+```
+
+#### Output Templates
+
+Post-processing supports custom output formatting using ERB templates. Create an `output.txt` file in your `post_processing` directory to format the final workflow output:
+
+```erb
+# post_processing/output.txt
+=== Workflow Summary Report ===
+Generated at: <%= Time.now.strftime("%Y-%m-%d %H:%M:%S") %>
+
+Environment: <%= pre_processing.setup_test_environment %>
+
+Files Processed: <%= targets.size %>
+
+<% targets.each do |file, target| %>
+- <%= file %>: <%= target.output.analyze_test %>
+<% end %>
+
+<%= output.generate_report %>
+===============================
+```
+
+The template has access to:
+- `pre_processing`: All pre-processing step outputs with dot notation
+- `targets`: Hash of all target workflow results with dot notation (each target has `.output` and `.final_output`)
+- `output`: Post-processing step outputs with dot notation
+
+#### Use Cases
+
+This pattern is ideal for:
+
+- **Code migrations**: Setup migration tools, process files, generate migration report
+- **Test optimization**: Baseline metrics, optimize tests, aggregate improvements
+- **Documentation generation**: Analyze codebase, generate docs per module, create index
+- **Dependency updates**: Check versions, update files, verify compatibility
+- **Security audits**: Setup scanners, check each file, generate security report
+- **Performance analysis**: Establish baselines, analyze components, summarize findings
+
+See the [pre/post processing example](examples/pre_post_processing) for a complete working demonstration.
+
+
 ## Development
 
 After checking out the repo, run `bundle install` to install dependencies. Then, run `bundle exec rake` to run the tests and linter. You can also run `bin/console` for an interactive prompt that will allow you to experiment.

data/docs/ITERATION_SYNTAX.md

@@ -90,10 +90,38 @@ For defining prompts directly in the workflow:
 
 ## Type Coercion
 
-Values are automatically coerced to the appropriate types:
+### Smart Defaults
 
-- For `until` conditions: Values are coerced to booleans (using Ruby's truthiness rules)
-- For `each` collections: Values are coerced to iterables (converted to arrays of lines if needed)
+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
 

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