XDG migration

Author: nfgrep

CLAUDE.md

@@ -186,7 +186,7 @@ When creating GitHub issues, always check available labels, projects, and milest
 
 ```bash
 # List all available labels
-gh api repos/Shopify/roast/labels | jq '.[].name'
+gh label list --repo Shopify/roast --json name --jq '.[].name'
 
 # List all milestones
 gh api repos/Shopify/roast/milestones | jq '.[] | {title: .title, number: .number, state: .state}'

README.md

@@ -490,8 +490,8 @@ This feature is particularly useful when:
 - Resuming after failures in long-running workflows
 
 **Storage Locations:**
-- SQLite: `~/.roast/sessions.db` (configurable via `ROAST_SESSIONS_DB`)
-- Filesystem: `.roast/sessions/` directory in your project
+- SQLite: `$XDG_DATA_HOME/roast/sessions.db` (default: `~/.local/share/roast/sessions.db`, configurable via `ROAST_SESSIONS_DB`)
+- Filesystem: `$XDG_DATA_HOME/roast/sessions/` (default: `~/.local/share/roast/sessions/`)
 
 #### Target Option (`-t, --target`)
 
@@ -1030,10 +1030,11 @@ See the [MCP tools example](examples/mcp/) for complete documentation and more e
 
 ### Custom Tools
 
-You can create your own tools using the [Raix function dispatch pattern](https://github.com/OlympiaAI/raix-rails?tab=readme-ov-file#use-of-toolsfunctions). Custom tools should be placed in `.roast/initializers/` (subdirectories are supported):
+You can create your own tools using the [Raix function dispatch pattern](https://github.com/OlympiaAI/raix-rails?tab=readme-ov-file#use-of-toolsfunctions). Custom tools should be placed in initializers directories (subdirectories are supported):
 
 ```ruby
-# .roast/initializers/tools/git_analyzer.rb
+# ~/.config/roast/initializers/tools/git_analyzer.rb
+# OR {workflow_directory}/initializers/tools/git_analyzer.rb
 module MyProject
   module Tools
     module GitAnalyzer
@@ -1081,22 +1082,45 @@ The tool will be available to the AI model during workflow execution, and it can
 
 ### Project-specific Configuration
 
-You can extend Roast with project-specific configuration by creating initializers in `.roast/initializers/`. These are automatically loaded when workflows run, allowing you to:
+You can extend Roast with project-specific configuration by creating initializers. These are automatically loaded when workflows run, allowing you to:
 
 - Add custom instrumentation
 - Configure monitoring and metrics
 - Set up project-specific tools
 - Customize workflow behavior
 
-Example structure:
+Roast supports initializers in multiple locations (in priority order):
+
+1. **Workflow-local initializers**: Place alongside your workflow steps
+2. **Global XDG config**: Shared across all projects using XDG Base Directory specification
+
+Example structures:
 ```
-your-project/
-  ├── .roast/
-  │   └── initializers/
-  │       ├── metrics.rb
-  │       ├── logging.rb
-  │       └── custom_tools.rb
+# Workflow-local (highest priority)
+your-workflow/
+  ├── workflow.yml
+  ├── analyze_code/
+  ├── initializers/
+  │   ├── metrics.rb
+  │   ├── logging.rb
+  │   └── custom_tools.rb
   └── ...
+
+# Global XDG config (user-wide)
+~/.config/roast/
+  └── initializers/
+      ├── shopify_defaults.rb
+      └── custom_tools.rb
+```
+
+**XDG Configuration Directories:**
+- Config: `$XDG_CONFIG_HOME/roast` (default: `~/.config/roast`)
+- Cache: `$XDG_CACHE_HOME/roast` (default: `~/.cache/roast`)
+
+You can customize these locations by setting XDG environment variables:
+```bash
+export XDG_CONFIG_HOME="/custom/config"
+export XDG_CACHE_HOME="/fast/ssd/cache"
 ```
 
 ### Pre/Post Processing Framework

exe/roast

@@ -14,4 +14,7 @@ require "bundler/setup"
 require "roast"
 
 puts "🔥🔥🔥 Everyone loves a good roast 🔥🔥🔥\n\n"
+
+Roast::XDGMigration.warn_if_migration_needed
+
 Roast::CLI.start(ARGV)

lib/roast.rb

@@ -39,11 +39,29 @@
 
 # Set up Zeitwerk autoloader
 loader = Zeitwerk::Loader.for_gem
+
+# Configure custom inflector for XDG acronym
+loader.inflector.inflect("xdg_migration" => "XDGMigration")
+
 loader.setup
 
 module Roast
   ROOT = File.expand_path("../..", __FILE__)
 
+  # https://specifications.freedesktop.org/basedir-spec/latest/
+  XDG_CONFIG_HOME = ENV.fetch("XDG_CONFIG_HOME", File.join(Dir.home, ".config"))
+  XDG_CACHE_HOME = ENV.fetch("XDG_CACHE_HOME", File.join(Dir.home, ".cache"))
+  XDG_DATA_HOME = ENV.fetch("XDG_DATA_HOME", File.join(Dir.home, ".local", "share"))
+
+  CONFIG_DIR = File.join(XDG_CONFIG_HOME, "roast")
+  CACHE_DIR = File.join(XDG_CACHE_HOME, "roast")
+  DATA_DIR = File.join(XDG_DATA_HOME, "roast")
+
+  GLOBAL_INITIALIZERS_DIR = File.join(CONFIG_DIR, "initializers")
+  FUNCTION_CACHE_DIR = File.join(CACHE_DIR, "function_calls")
+  SESSION_DATA_DIR = File.join(DATA_DIR, "sessions")
+  SESSION_DB_PATH = ENV.fetch("ROAST_SESSIONS_DB", File.join(DATA_DIR, "sessions.db"))
+
   class CLI < Thor
     desc "execute [WORKFLOW_CONFIGURATION_FILE] [FILES...]", "Run a configured workflow"
     option :concise, type: :boolean, aliases: "-c", desc: "Optional flag for use in output templates"
@@ -65,6 +83,9 @@ def execute(*paths)
         File.expand_path("roast/#{workflow_path}/workflow.yml")
       end
 
+      context_path = File.dirname(expanded_workflow_path)
+      Roast::XDGMigration.warn_if_migration_needed(context_path)
+
       raise Thor::Error, "Expected a Roast workflow configuration file, got directory: #{expanded_workflow_path}" if File.directory?(expanded_workflow_path)
 
       Roast::Workflow::ConfigurationParser.new(expanded_workflow_path, files, options.transform_keys(&:to_sym)).begin!
@@ -81,6 +102,9 @@ def resume(workflow_path)
         File.expand_path("roast/#{workflow_path}/workflow.yml")
       end
 
+      context_path = File.dirname(expanded_workflow_path)
+      Roast::XDGMigration.warn_if_migration_needed(context_path)
+
       unless File.exist?(expanded_workflow_path)
         raise Thor::Error, "Workflow file not found: #{expanded_workflow_path}"
       end
@@ -140,6 +164,8 @@ def list
       puts "Available workflows:"
       puts
 
+      Roast::XDGMigration.warn_if_migration_needed
+
       workflow_files.each do |file|
         workflow_name = File.dirname(file.sub("#{roast_dir}/", ""))
         puts "  #{workflow_name} (from project)"
@@ -152,6 +178,9 @@ def list
     desc "validate [WORKFLOW_CONFIGURATION_FILE]", "Validate a workflow configuration"
     option :strict, type: :boolean, aliases: "-s", desc: "Treat warnings as errors"
     def validate(workflow_path = nil)
+      context_path = workflow_path ? File.dirname(workflow_path) : nil
+      Roast::XDGMigration.warn_if_migration_needed(context_path)
+
       validation_command = Roast::Workflow::ValidationCommand.new(options)
       validation_command.execute(workflow_path)
     end
@@ -203,6 +232,8 @@ def sessions
 
     desc "session SESSION_ID", "Show details for a specific session"
     def session(session_id)
+      Roast::XDGMigration.warn_if_migration_needed
+
       repository = Workflow::StateRepositoryFactory.create
 
       unless repository.respond_to?(:get_session_details)
@@ -253,6 +284,9 @@ def session(session_id)
     desc "diagram WORKFLOW_FILE", "Generate a visual diagram of a workflow"
     option :output, type: :string, aliases: "-o", desc: "Output file path (defaults to workflow_name_diagram.png)"
     def diagram(workflow_file)
+      context_path = File.dirname(workflow_file)
+      Roast::XDGMigration.warn_if_migration_needed(context_path)
+
       unless File.exist?(workflow_file)
         raise Thor::Error, "Workflow file not found: #{workflow_file}"
       end
@@ -266,6 +300,13 @@ def diagram(workflow_file)
       raise Thor::Error, "Error generating diagram: #{e.message}"
     end
 
+    desc "xdg-migrate", "Migrate legacy .roast directories to XDG directories"
+    option :auto_confirm, type: :boolean, aliases: "-a", desc: "Automatically confirm all prompts"
+    option :workflow_context, type: :string, aliases: "-w", desc: "Workflow context path"
+    def xdg_migrate
+      Roast::XDGMigration.migrate(options[:workflow_context], options[:auto_confirm])
+    end
+
     private
 
     def show_example_picker

lib/roast/helpers/function_caching_interceptor.rb

@@ -14,11 +14,11 @@ def dispatch_tool_function(function_name, params)
         })
 
         # Handle workflows with or without configuration
-        result = if !respond_to?(:configuration) || configuration.nil?
+        result = if !respond_to?(:workflow_configuration) || workflow_configuration.nil?
           super(function_name, params)
         else
-          function_config = if configuration.respond_to?(:function_config)
-            configuration.function_config(function_name)
+          function_config = if workflow_configuration.respond_to?(:function_config)
+            workflow_configuration.function_config(function_name)
           else
             {}
           end

lib/roast/helpers/logger.rb

@@ -51,7 +51,7 @@ def create_logger(stdout)
             msg_string = format_message(msg)
 
             if severity == "INFO" && !msg_string.start_with?("[")
-              msg_string
+              msg_string + "\n"
             else
               "[#{datetime.strftime("%Y-%m-%d %H:%M:%S")}] #{severity}: #{msg_string.gsub(/^\[|\]$/, "").strip}\n"
             end

lib/roast/initializers.rb

@@ -3,36 +3,48 @@
 module Roast
   class Initializers
     class << self
-      def config_root(starting_path = Dir.pwd, ending_path = File.dirname(Dir.home))
-        paths = []
-        candidate = starting_path
-        while candidate != ending_path
-          paths << File.join(candidate, ".roast")
-          candidate = File.dirname(candidate)
+      def load_all(workflow_context_path = Dir.pwd)
+        # .reverse so we load the highest priority files last, letting them override lower priority files
+        initializer_files(workflow_context_path).reverse.each do |file|
+          load_initializer(file)
         end
-
-        first_existing = paths.find { |path| Dir.exist?(path) }
-        first_existing || paths.first
+      rescue => e
+        puts "ERROR: Error loading initializers: #{e.message}"
+        Roast::Helpers::Logger.error("Error loading initializers: #{e.message}")
+        # Don't fail the workflow if initializers can't be loaded
       end
 
-      def initializers_path
-        File.join(Roast::Initializers.config_root, "initializers")
-      end
+      private
 
-      def load_all
-        project_initializers = Roast::Initializers.initializers_path
-        return unless Dir.exist?(project_initializers)
+      # Get all possible initializer directories in priority order
+      def initializer_files(workflow_context_path = Dir.pwd)
+        initializer_files = []
+        # 1. Workflow-local initializers (highest priority)
+        local_dir = local_initializers_dir(workflow_context_path)
+        if Dir.exist?(local_dir)
+          initializer_files.concat(Dir.glob(File.join(local_dir, "**/*.rb")))
+        end
 
-        $stderr.puts "Loading project initializers from #{project_initializers}"
-        pattern = File.join(project_initializers, "**/*.rb")
-        Dir.glob(pattern, sort: true).each do |file|
-          $stderr.puts "Loading initializer: #{file}"
-          require file
+        # 2. XDG global config initializers
+        if Dir.exist?(Roast::GLOBAL_INITIALIZERS_DIR)
+          initializer_files.concat(Dir.glob(File.join(Roast::GLOBAL_INITIALIZERS_DIR, "**/*.rb")))
         end
-      rescue => e
-        puts "ERROR: Error loading initializers: #{e.message}"
-        Roast::Helpers::Logger.error("Error loading initializers: #{e.message}")
-        # Don't fail the workflow if initializers can't be loaded
+
+        # 3. Legacy .roast directory support (with deprecation warning)
+        initializer_files.concat(Roast::XDGMigration.legacy_initializers)
+
+        unique_initializer_files = initializer_files.uniq { |file| File.basename(file) }
+
+        unique_initializer_files
+      end
+
+      def local_initializers_dir(workflow_context_path)
+        File.join(workflow_context_path, "initializers")
+      end
+
+      def load_initializer(file)
+        Roast::Helpers::Logger.info("Loading initializer: #{file}")
+        require file
       end
     end
   end

lib/roast/tools.rb

@@ -4,15 +4,8 @@ module Roast
   module Tools
     extend self
 
-    # Initialize cache and ensure .gitignore exists
-    cache_dir = File.join(Dir.pwd, ".roast", "cache")
-    FileUtils.mkdir_p(cache_dir) unless File.directory?(cache_dir)
-
-    # Add .gitignore to cache directory
-    gitignore_path = File.join(cache_dir, ".gitignore")
-    File.write(gitignore_path, "*") unless File.exist?(gitignore_path)
-
-    CACHE = ActiveSupport::Cache::FileStore.new(cache_dir)
+    # Initialize cache using XDG cache directory
+    CACHE = ActiveSupport::Cache::FileStore.new(FUNCTION_CACHE_DIR)
 
     def file_to_prompt(file)
       <<~PROMPT

lib/roast/workflow/session_manager.rb

@@ -71,7 +71,7 @@ def workflow_directory(session_name, file_path)
         file_id = Digest::MD5.hexdigest(file_path || Dir.pwd)
         file_basename = File.basename(file_path || Dir.pwd).parameterize.underscore
         human_readable_id = "#{file_basename}_#{file_id[0..7]}"
-        File.join(Dir.pwd, ".roast", "sessions", workflow_dir_name, human_readable_id)
+        File.join(SESSION_DATA_DIR, workflow_dir_name, human_readable_id)
       end
 
       def find_latest_session_directory(workflow_dir)

lib/roast/workflow/sqlite_state_repository.rb

@@ -7,8 +7,6 @@ module Workflow
     # SQLite-based implementation of StateRepository
     # Provides structured, queryable session storage with better performance
     class SqliteStateRepository < StateRepository
-      DEFAULT_DB_PATH = File.expand_path("~/.roast/sessions.db")
-
       def initialize(db_path: nil, session_manager: SessionManager.new)
         super()
 
@@ -19,7 +17,17 @@ def initialize(db_path: nil, session_manager: SessionManager.new)
           raise LoadError, "SQLite storage requires the 'sqlite3' gem. Please add it to your Gemfile or install it: gem install sqlite3"
         end
 
-        @db_path = db_path || ENV["ROAST_SESSIONS_DB"] || DEFAULT_DB_PATH
+        # Priority order
+        paths = [
+          db_path,
+          Roast::SESSION_DB_PATH,
+          Roast::XDGMigration.legacy_sessions_db_path,
+        ]
+
+        # If multiple options exist, prefer the first one that exists
+        @db_path = paths.find { |path| path && File.exist?(path) }
+        # If no options exist as paths, use the first one that is not nil
+        @db_path ||= paths.find { |path| !path.nil? }
         @session_manager = session_manager
         ensure_database
       end