roast-ai 1.1.0 → 1.2.0

data/internal/rubocop/cop/roast/no_test_class_nesting.rb

@@ -0,0 +1,126 @@
+# typed: false
+# frozen_string_literal: true
+
+module RuboCop
+  module Cop
+    module Roast
+      # Prevents nesting classes or modules inside reopened (non-test) class
+      # definitions in test files.
+      #
+      # When a class is reopened in a test file (e.g., `class Agent < Cog`) and
+      # contains nested class or module definitions, IDE test runners like
+      # RubyMine fail to discover test suites. Use `::` scoping instead.
+      #
+      # The cop walks the entire subtree of the offending class, so deeply
+      # nested structures (e.g., `class Agent < Cog; module Providers; ...`)
+      # are caught even when the nested definitions are not direct children.
+      #
+      # Classes nested inside test classes are exempt — helper stubs and
+      # fixtures defined inside a test suite are perfectly fine.
+      #
+      # @example Bad — reopened class with nested module
+      #   class Agent < Cog
+      #     module Providers
+      #       class Claude::MessageTest < ActiveSupport::TestCase
+      #         # ...
+      #       end
+      #     end
+      #   end
+      #
+      # @example Bad — reopened class with nested test class
+      #   class Agent < Cog
+      #     class ConfigTest < ActiveSupport::TestCase
+      #       # ...
+      #     end
+      #   end
+      #
+      # @example Good — :: scoping, no class reopening
+      #   module Agent::Providers
+      #     class Claude::MessageTest < ActiveSupport::TestCase
+      #       # ...
+      #     end
+      #   end
+      #
+      # @example Good — :: scoped test class
+      #   class Agent::ConfigTest < ActiveSupport::TestCase
+      #     # ...
+      #   end
+      #
+      # @example Good — helper class inside a test class
+      #   class Agent::OutputTest < ActiveSupport::TestCase
+      #     class FakeAdapter
+      #       def call; end
+      #     end
+      #   end
+      #
+      class NoTestClassNesting < Base
+        MSG = "Do not nest classes or modules inside reopened class `%<parent>s` in test files. " \
+          "Use `::` scoping instead (e.g., `class %<parent>s::Nested` or `module %<parent>s::Nested`)."
+
+        # @!method test_base_class?(node)
+        def_node_matcher :test_base_class?, <<~PATTERN
+          {
+            (const (const {nil? cbase} :ActiveSupport) :TestCase)
+            (const (const {nil? cbase} :Minitest) :Test)
+            (const {nil? cbase} :Minitest)
+          }
+        PATTERN
+
+        def on_class(node)
+          # Test classes are allowed to contain nested definitions (helpers, stubs)
+          return if test_class?(node)
+
+          # Classes nested inside a test class are helpers — leave them alone
+          return if inside_test_class?(node)
+
+          # Flag if this non-test class contains any nested class or module
+          return unless contains_nested_definitions?(node)
+
+          message = format(MSG, parent: node.identifier.const_name)
+          add_offense(node.loc.keyword.join(node.identifier.source_range), message: message)
+        end
+
+        private
+
+        def test_class?(node)
+          node.parent_class && test_base_class?(node.parent_class)
+        end
+
+        # Returns true if any ancestor of +node+ is a test class.
+        def inside_test_class?(node)
+          current = node.parent
+          while current
+            return true if current.class_type? && test_class?(current)
+
+            current = current.parent
+          end
+          false
+        end
+
+        # Returns true if +node+ contains any nested class or module definition
+        # at any depth, excluding those sheltered inside an intermediate test class.
+        def contains_nested_definitions?(node)
+          node.each_descendant(:class, :module) do |descendant|
+            next if sheltered_by_test_class?(descendant, node)
+
+            return true
+          end
+          false
+        end
+
+        # Returns true if there is a test class between +descendant+ and +stop_at+
+        # in the ancestor chain — meaning the descendant is a helper inside a test
+        # class and should not count as a problematic nested definition.
+        def sheltered_by_test_class?(descendant, stop_at)
+          current = descendant.parent
+          while current && current != stop_at
+            return true if current.class_type? && test_class?(current)
+
+            current = current.parent
+          end
+          false
+        end
+      end
+    end
+  end
+end

data/internal/rubocop/rubocop-roast.yml

@@ -0,0 +1,6 @@
+Roast/NoTestClassNesting:
+  Description: "Prevents nesting test classes inside reopened production classes. Use :: scoping instead."
+  Enabled: true
+  VersionAdded: "0.1.0"
+  Include:
+    - "test/**/*.rb"

data/internal/workflows/maintenance/branch_docs_impact.rb

@@ -0,0 +1,97 @@
+# typed: true
+# frozen_string_literal: true
+
+#: self as Roast::Workflow
+
+# Gets the committed diff of the current branch vs origin/main, then analyzes it for potential
+# documentation impacts, and optionally applies fixes. This is meant to be run as a pre-merge check, to
+# catch any potential documentation issues before they get merged into main.
+#
+# Accepts a `--fix` flag to apply any suggested fixes in place. Otherwise, it just reports the analysis
+# and recommended fixes without applying them.
+
+config do
+  agent do
+    provider :claude
+    model "claude-opus-4-7"
+    quiet!
+  end
+  chat do
+    provider :openai
+    model "gpt-5"
+    quiet!
+  end
+end
+
+execute do
+  cmd(:diff) do
+    merge_base = %x(git merge-base origin/main HEAD).strip
+    fail!("could not determine merge-base with origin/main — run `git fetch origin main` first") if merge_base.empty?
+    "git diff #{merge_base} HEAD"
+  end
+
+  agent(:analyzer) do
+    skip! if cmd!(:diff).text.strip.empty?
+    fail!("diff too large (#{cmd!(:diff).text.bytesize} bytes) to analyze — narrow the branch or exclude generated files") if cmd!(:diff).text.bytesize > 500_000
+    <<~PROMPT
+      You are checking whether a git diff makes any existing documentation stale.
+
+      Rules:
+      - Use ONLY the diff below. Do not run any commands.
+      - Be thorough about finding real issues — do not be conservative.
+      - But do NOT speculate about docs you cannot see in the diff.
+      - No markdown headers, no preamble, no caveats, no "limitations" sections.
+
+      Output format — pick exactly one:
+
+      If nothing in the diff affects existing docs, output a single line:
+        No documentation impact.
+
+      Otherwise, output one block per affected doc, separated by blank lines:
+        <doc/path.md>
+        Stale because: <one sentence>
+        Fix: <one sentence>
+
+      --- DIFF START ---
+      #{cmd!(:diff).text}
+      --- DIFF END ---
+    PROMPT
+  end
+
+  chat(:report) do
+    skip! if cmd!(:diff).text.strip.empty?
+    <<~PROMPT
+      Based on the following analysis, summarize the impact of the changes in this branch on the project's documentation.
+      Highlight any significant improvements or regressions, and provide recommendations for any additional documentation updates that may be necessary.
+      Do not suggest updates that are not needed.
+      Do not be verbose. Be super concise.
+
+      Analysis:
+      #{agent!(:analyzer).response}
+    PROMPT
+  end
+
+  agent(:fixer) do
+    skip! unless arg?(:fix)
+    skip! if cmd!(:diff).text.strip.empty?
+    skip! if agent!(:analyzer).response.strip == "No documentation impact."
+    <<~PROMPT
+      Apply the documentation fixes suggested in the analysis below. Edit the
+      affected files in place. Do not modify any code files; docs only.
+
+      #{agent!(:analyzer).response}
+    PROMPT
+  end
+
+  ruby(:output) do
+    if cmd!(:diff).text.strip.empty?
+      puts "No changes vs origin/main — nothing to analyze."
+    else
+      files = cmd!(:diff).out.scan(%r{^diff --git a/.+ b/(.+)$}).flatten
+      puts "Files considered (#{files.size}):"
+      files.each { |f| puts "  #{f}" }
+      puts "ANALYSIS:\n#{chat!(:report).response}"
+      puts(agent?(:fixer) ? "Fixes applied." : "(Next time, run with `-- fix` to auto-apply suggested edits)")
+    end
+  end
+end

data/internal/workflows/maintenance/deprecated_models_docs_updater.rb

@@ -0,0 +1,78 @@
+# typed: true
+# frozen_string_literal: true
+
+#: self as Roast::Workflow
+
+# Looks at the Anthropic (https://platform.claude.com/docs/en/about-claude/model-deprecations) and
+# OpenAI (https://developers.openai.com/api/docs/deprecations) model-deprecation pages and updates all
+# docs, doc comments and code references to deprecated/retired models to reflect those changes. This is
+# meant to be run periodically to keep all the references to models up to date.
+
+config do
+  agent do
+    provider :claude
+    model "claude-opus-4-8"
+    quiet!
+  end
+end
+
+execute do
+  agent(:model_verifier) do
+    <<~PROMPT
+      Check both of these pages for deprecated/retired models and their suggested replacements:
+      - Anthropic (Claude): https://platform.claude.com/docs/en/about-claude/model-deprecations
+      - OpenAI: https://developers.openai.com/api/docs/deprecations
+
+      Include every deprecated or retired model that has a recommended replacement, from both pages.
+      Only include models — ignore deprecated API endpoints, tools, or other non-model features.
+
+      Output ONLY a JSON object of exactly this shape, with no surrounding prose:
+      {"outdated": [{"model": "<outdated_model>", "replacement": "<replacement_model>"}]}
+
+      If there are none, output {"outdated": []}.
+    PROMPT
+  end
+
+  agent(:model_finder) do
+    <<~PROMPT
+      You are a code search engine. Search through the codebase and documentation for any references to
+      the outdated models below, including test files, and list every place where they are mentioned.
+
+      The input is a JSON object of the form:
+      {"outdated": [{"model": "<outdated_model>", "replacement": "<replacement_model>"}]}
+
+      INPUT:
+      #{agent!(:model_verifier).response}
+
+      Output ONLY a JSON object of exactly this shape, with no surrounding prose, carrying the
+      replacement through for each model you find a reference to:
+      {"references": [{"model": "<outdated_model>", "replacement": "<replacement_model>", "locations": ["<file_path>:<line_number>"]}]}
+
+      If you find no references, output {"references": []}.
+    PROMPT
+  end
+
+  agent(:updater) do |my|
+    finder = agent!(:model_finder)
+    skip! if finder.json![:references].blank?
+    my.session = finder.session
+    <<~PROMPT
+      For each reference you found of an outdated model, update the reference to use the suggested replacement model instead. Make sure to update all types of references, including documentation, doc comments and code references. Output the list of updated references in the following format:
+      <outdated_model_1> -> <replacement_model_1>:
+      - <file_path>:<line_number>
+      <outdated_model_2> -> <replacement_model_2>:
+      - <file_path>:<line_number>
+      ...
+    PROMPT
+  end
+
+  ruby(:output) do
+    if agent?(:updater)
+      puts "[OUTDATED MODELS & REPLACEMENTS]\n #{agent!(:model_verifier).response}"
+      puts "[REFERENCES IN CODEBASE]\n #{agent!(:model_finder).response}"
+      puts "[UPDATED REFERENCES]\n #{agent!(:updater).response}"
+    else
+      puts "No references to outdated models found — nothing to update."
+    end
+  end
+end

data/lib/roast/cog/config.rb

@@ -230,7 +230,7 @@ module Roast
       #
       #: () -> bool
       def abort_on_failure?
-        !!@values[:abort_on_failure]
+        @values.fetch(:abort_on_failure, true)
       end
 
       # Configure the cog to run external commands in the specified working directory

data/lib/roast/cog_input_manager.rb

@@ -159,7 +159,7 @@ module Roast
     # Supports both relative shorthand paths like "greeting" and full absolute paths.
     #
     # @param path [String, Pathname] The template path to resolve. Can be:
-    #   - Shorthand name: "greeting" -> searches for prompts/greeting.md.erb
+    #   - Shorthand name: "greeting" -> searches for prompts/greeting.md.erb or templates/greeting.md.erb
     #   - With extension: "template.erb" -> searches for template.erb
     #   - Absolute path: "/full/path/to/template.erb" -> uses as-is
     # @param args [Hash] Template variables for ERB interpolation
@@ -175,13 +175,14 @@ module Roast
     # 1. Absolute path as-is (if absolute)
     # 2-4. Workflow directory: path, path.erb, path.md.erb
     # 5-7. Workflow directory prompts/: prompts/path, prompts/path.erb, prompts/path.md.erb
-    # 8-10. Current directory: path, path.erb, path.md.erb
-    # 11-13. Current directory prompts/: prompts/path, prompts/path.erb, prompts/path.md.erb
+    # 8-10. Workflow directory templates/: templates/path, templates/path.erb, templates/path.md.erb
+    # 11-13. Current directory: path, path.erb, path.md.erb
+    # 14-16. Current directory prompts/: prompts/path, prompts/path.erb, prompts/path.md.erb
+    # 17-19. Current directory templates/: templates/path, templates/path.erb, templates/path.md.erb
+    # 20-22. Tilde-expanded path: path, path.erb, path.md.erb
     #
     #: (String | Pathname, ?Hash) -> String
     def template(path, args = {})
-      # NOTE: Pathname does not expand ~ for home directory automatically.
-      # This is tracked in issue https://github.com/Shopify/roast/issues/663.
       path = Pathname.new(path) unless path.is_a?(Pathname)
 
       # Priority stack of places to look for a matching file
@@ -201,17 +202,37 @@ module Roast
       candidate_paths << workflow_dir / "prompts" / "#{path}.erb"
       candidate_paths << workflow_dir / "prompts" / "#{path}.md.erb"
 
-      # 8-10. Relative to current working directory
+      # 8-10. Relative to workflow directory templates folder
+      candidate_paths << workflow_dir / "templates" / path
+      candidate_paths << workflow_dir / "templates" / "#{path}.erb"
+      candidate_paths << workflow_dir / "templates" / "#{path}.md.erb"
+
+      # 11-13. Relative to current working directory
       pwd = Pathname.pwd
       candidate_paths << pwd / path
       candidate_paths << pwd / "#{path}.erb"
       candidate_paths << pwd / "#{path}.md.erb"
 
-      # 11-13. Relative to current working directory prompts folder
+      # 14-16. Relative to current working directory prompts folder
       candidate_paths << pwd / "prompts" / path
       candidate_paths << pwd / "prompts" / "#{path}.erb"
       candidate_paths << pwd / "prompts" / "#{path}.md.erb"
 
+      # 17-19. Relative to current working directory templates folder
+      candidate_paths << pwd / "templates" / path
+      candidate_paths << pwd / "templates" / "#{path}.erb"
+      candidate_paths << pwd / "templates" / "#{path}.md.erb"
+
+      # 20-22. Tilde expanded path
+      begin
+        expanded_path = Pathname.new(File.expand_path(path))
+        candidate_paths << expanded_path
+        candidate_paths << Pathname.new(File.expand_path("#{expanded_path}.erb"))
+        candidate_paths << Pathname.new(File.expand_path("#{expanded_path}.md.erb"))
+      rescue ArgumentError
+        # File.expand_path raises when expanding ~something/foo (assuming "something" is not a real user).
+        # Nothing to do here, falls back to other candidate paths without tilde expansion.
+      end
       # Use the first path that exists
       resolved_path = candidate_paths.find(&:exist?)
 

data/lib/roast/cogs/agent/config.rb

@@ -51,7 +51,7 @@ module Roast
         def valid_provider!
           provider = @values[:provider] || VALID_PROVIDERS.first
           unless VALID_PROVIDERS.include?(provider)
-            raise ArgumentError, "'#{provider}' is not a valid provider. Available providers include: #{VALID_PROVIDERS.join(", ")}"
+            raise InvalidConfigError, "'#{provider}' is not a valid provider. Available providers include: #{VALID_PROVIDERS.join(", ")}"
           end
 
           provider

data/lib/roast/cogs/agent/providers/claude/claude_invocation.rb

@@ -77,7 +77,7 @@ module Roast
               raise ClaudeAlreadyStartedError if started?
 
               @started = true
-              puts "[USER PROMPT] #{@prompt}" if @show_prompt
+              Event << { block: { header: "USER PROMPT", content: @prompt } } if @show_prompt
               _stdout, stderr, status = CommandRunner.execute(
                 command_line,
                 working_directory: @working_directory,
@@ -87,7 +87,7 @@ module Roast
 
               if status.success?
                 @completed = true
-                puts "[AGENT RESPONSE] #{@result.response}" if @show_response
+                Event << { block: { header: "AGENT RESPONSE", content: @result.response } } if @show_response
               else
                 @failed = true
                 @result.success = false

data/lib/roast/cogs/agent/providers/claude/messages/result_message.rb

@@ -31,7 +31,7 @@ module Roast
                 @content = hash.delete(:result) || ""
                 @success = hash.delete(:success) || subtype == "success"
                 if hash.delete(:is_error) || subtype == "error"
-                  @content = @content || hash.dig(:error, :message) || "Unknown error"
+                  @content = @content.presence || hash.dig(:error, :message) || "Unknown error"
                   hash.delete(:error)
                 end