meta_workflows 0.7.0

data/lib/meta_workflows/asset_installer.rb

@@ -0,0 +1,509 @@
+# frozen_string_literal: true
+
+require 'yaml'
+require 'fileutils'
+
+module MetaWorkflows
+  # Asset installer class to handle file discovery and path resolution
+  class AssetInstaller
+    attr_reader :gem_root, :host_app_root
+
+    # Custom exception for installation errors
+    class InstallationError < StandardError; end
+    class ValidationError < InstallationError; end
+    class PermissionError < InstallationError; end
+    class SourceError < InstallationError; end
+
+    def initialize
+      @gem_root = Gem::Specification.find_by_name('meta_workflows').gem_dir
+      @host_app_root = Rails.root
+      @rollback_files = []
+    rescue Gem::LoadError
+      raise InstallationError, 'meta_workflows gem not found. Please ensure it is properly installed.'
+    end
+
+    # Validate environment before installation
+    def valid_environment?
+      puts 'Validating installation environment...'
+
+      errors = validation_errors
+
+      if errors.any?
+        puts 'Validation failed:'
+        errors.each { |error| puts "  ✗ #{error}" }
+        return false
+      end
+
+      puts '✓ Environment validation passed'
+      true
+    end
+
+    # Discover all assets that can be installed
+    def discover_assets
+      puts 'Discovering available assets...'
+
+      assets = []
+
+      begin
+        # Discover JavaScript controllers
+        js_assets = discover_javascript_assets
+        assets.concat(js_assets)
+        puts "  ✓ Found #{js_assets.count} JavaScript asset(s)" if js_assets.any?
+
+        # Discover stylesheets
+        css_assets = discover_stylesheet_assets
+        assets.concat(css_assets)
+        puts "  ✓ Found #{css_assets.count} stylesheet asset(s)" if css_assets.any?
+
+        # Validate discovered assets
+        validate_assets(assets)
+
+        assets
+      rescue StandardError => e
+        raise SourceError, "Failed to discover assets: #{e.message}"
+      end
+    end
+
+    # Install assets with comprehensive error handling and rollback capability
+    def install_assets(assets)
+      copied_count = 0
+      skipped_count = 0
+      failed_count = 0
+      success = true
+
+      puts 'Installing assets...'
+
+      # Clear rollback tracking
+      @rollback_files.clear
+
+      assets.each do |asset|
+        result = process_single_asset(asset)
+        case result
+        when :copied
+          copied_count += 1
+          puts "✓ Copied #{asset[:relative_path]}"
+        when :skipped
+          skipped_count += 1
+          puts "⚠ Skipped #{asset[:relative_path]} (already exists)"
+        when :failed
+          failed_count += 1
+          success = false
+          puts "✗ Failed to copy #{asset[:relative_path]}"
+        end
+      rescue StandardError => e
+        handle_installation_error(e, asset, failed_count)
+        failed_count += 1
+        success = false
+      end
+
+      {
+        success: success,
+        copied: copied_count,
+        skipped: skipped_count,
+        failed: failed_count
+      }
+    end
+
+    # Display comprehensive integration instructions after successful installation
+    def display_integration_instructions(assets, _result)
+      puts '=' * 80
+      puts '🎉 INTEGRATION INSTRUCTIONS'
+      puts '=' * 80
+      puts
+
+      # Analyze what was actually copied
+      copied_controllers = assets.select do |asset|
+        asset[:type] == :javascript && asset[:relative_path].include?('controllers/')
+      end
+      copied_stylesheets = assets.select { |asset| asset[:type] == :stylesheet }
+
+      display_controller_instructions(copied_controllers) if copied_controllers.any?
+      display_stylesheet_instructions(copied_stylesheets) if copied_stylesheets.any?
+      display_general_instructions
+      display_troubleshooting_guide
+
+      puts '=' * 80
+      puts '✨ Happy coding with meta_workflows!'
+      puts '=' * 80
+    end
+
+    private
+
+    def validation_errors
+      errors = []
+
+      # Check if we can find the gem
+      errors << "meta_workflows gem directory not found at: #{@gem_root}" unless File.exist?(@gem_root)
+
+      # Check if host application root exists
+      errors << "Host application root not found at: #{@host_app_root}" unless File.exist?(@host_app_root)
+
+      # Check basic write permissions to host app
+      unless writable_directory?(@host_app_root)
+        errors << "No write permission to host application directory: #{@host_app_root}"
+      end
+
+      # Check for required directories in host app
+      required_dirs = [
+        File.join(@host_app_root, 'app'),
+        File.join(@host_app_root, 'app', 'javascript'),
+        File.join(@host_app_root, 'app', 'assets')
+      ]
+
+      required_dirs.each do |dir|
+        errors << "Required directory missing: #{dir}" unless File.exist?(dir)
+      end
+
+      errors
+    end
+
+    def process_single_asset(asset)
+      install_single_asset(asset)
+    rescue StandardError
+      :failed
+    end
+
+    def handle_installation_error(error, asset, _failed_count)
+      puts "✗ Failed to copy #{asset[:relative_path]}: #{error.message}"
+
+      # If we have critical failures, consider rollback
+      return unless should_rollback?(error)
+
+      puts 'Critical error encountered. Rolling back changes...'
+      rollback_installation
+      raise InstallationError, "Installation failed and was rolled back: #{error.message}"
+    end
+
+    # Display instructions for Stimulus controllers
+    def display_controller_instructions(controllers)
+      puts '📋 STIMULUS CONTROLLERS'
+      puts '-' * 40
+      puts
+      puts 'The following Stimulus controllers have been installed:'
+      puts
+
+      controllers.each do |controller|
+        controller_name = File.basename(controller[:relative_path], '.js').gsub('_controller', '').tr('_', '-')
+        puts "• #{controller_name.upcase}_CONTROLLER"
+        puts "  Location: #{controller[:relative_path]}"
+        puts "  Usage: data-controller=\"meta-workflows--#{controller_name}\""
+        puts
+      end
+
+      puts '🔧 STIMULUS SETUP REQUIRED:'
+      puts
+      puts 'Add the following line to your app/javascript/controllers/index.js file:'
+      puts
+      puts '   import { eagerLoadControllersFrom } from "@hotwired/stimulus-loading"'
+      puts '   eagerLoadControllersFrom("controllers/meta_workflows", application)'
+      puts
+      puts 'This will automatically load and register all meta_workflows controllers with the'
+      puts '"meta-workflows--" prefix (e.g., "meta-workflows--redirect").'
+      puts
+
+      display_controller_usage_examples
+    end
+
+    # Display usage examples for each controller
+    def display_controller_usage_examples
+      puts '📖 CONTROLLER USAGE EXAMPLES:'
+      puts
+      puts '• REDIRECT CONTROLLER:'
+      puts '  <div data-controller="meta-workflows--redirect"'
+      puts '       data-meta-workflows--redirect-url-value="/success"'
+      puts '       data-meta-workflows--redirect-delay-value="2000">'
+      puts '    Redirecting...'
+      puts '  </div>'
+      puts
+      puts '• RESPONSE SCROLL CONTROLLER:'
+      puts '  <div data-controller="meta-workflows--response-scroll"'
+      puts '       id="response-content-container">'
+      puts '    <!-- Auto-scrolls to bottom as content changes -->'
+      puts '  </div>'
+      puts
+      puts '• LOADING PHRASES CONTROLLER:'
+      puts '  <div data-controller="meta-workflows--loading-phrases"'
+      loading_phrases_example_line
+      puts '    <span data-meta-workflows--loading-phrases-target="message">Loading...</span>'
+      puts '  </div>'
+      puts
+    end
+
+    def loading_phrases_example_line
+      puts '       data-meta-workflows--loading-phrases-phrases-value=' \
+           '\'["Processing...", "Almost done...", "Finishing up..."]\'>'
+    end
+
+    # Display instructions for stylesheets
+    def display_stylesheet_instructions(stylesheets)
+      puts '🎨 STYLESHEETS'
+      puts '-' * 40
+      puts
+      puts 'The following stylesheets have been installed:'
+      puts
+
+      stylesheets.each do |stylesheet|
+        puts "• #{stylesheet[:relative_path]}"
+      end
+      puts
+
+      puts '🔧 STYLESHEET SETUP REQUIRED:'
+      puts
+      puts '1. Add to your application.css file:'
+      puts
+      puts '   /*'
+      puts '    *= require meta_workflows/application'
+      puts '    */'
+      puts
+      puts '2. Or with Sass/SCSS, add to application.scss:'
+      puts
+      puts '   @import "meta_workflows/application";'
+      puts
+      puts '3. With CSS imports, add to your main CSS file:'
+      puts
+      puts '   @import url("./meta_workflows/application.css");'
+      puts
+    end
+
+    # Display general integration instructions
+    def display_general_instructions
+      puts '⚙️  GENERAL INTEGRATION NOTES'
+      puts '-' * 40
+      puts
+      puts '• Ensure your Rails application has Hotwire/Stimulus properly configured'
+      puts '• Controllers use the "meta-workflows--" prefix to avoid naming conflicts'
+      puts '• All assets maintain the meta_workflows namespace structure'
+      puts '• Assets are copied to standard Rails asset directories for easy management'
+      puts '• You can customize the copied files as needed for your application'
+      puts
+      puts '📁 ASSET LOCATIONS:'
+      puts '  • JavaScript Controllers: app/javascript/controllers/meta_workflows/'
+      puts '  • Stylesheets: app/assets/stylesheets/meta_workflows/'
+      puts
+    end
+
+    # Display troubleshooting guide
+    def display_troubleshooting_guide
+      puts '🔍 TROUBLESHOOTING'
+      puts '-' * 40
+      puts
+      puts 'If controllers are not working:'
+      puts '  1. Check that Stimulus is properly installed and configured'
+      puts '  2. Verify controllers are registered in your application.js'
+      puts '  3. Check browser console for JavaScript errors'
+      puts '  4. Ensure data-controller attributes use correct naming: "meta-workflows--controller-name"'
+      puts
+      puts 'If stylesheets are not loading:'
+      puts '  1. Verify CSS imports in your application.css or application.scss'
+      puts '  2. Check that Rails asset pipeline is properly configured'
+      puts '  3. Run "rails assets:precompile" in production'
+      puts
+      puts 'For additional help:'
+      puts '  • Check the meta_workflows gem documentation'
+      puts '  • Review Rails asset pipeline documentation'
+      puts '  • Verify Hotwire/Stimulus setup in your application'
+      puts
+    end
+
+    # Install a single asset with comprehensive error handling
+    def install_single_asset(asset)
+      validate_source_file(asset)
+      destination_dir = File.dirname(asset[:destination_path])
+      create_destination_directory(destination_dir)
+      check_destination_permissions(destination_dir)
+
+      # Check if file already exists
+      return :skipped if File.exist?(asset[:destination_path]) && !should_overwrite?(asset[:relative_path])
+
+      copy_asset_file(asset)
+    end
+
+    def validate_source_file(asset)
+      # Validate source file exists
+      raise SourceError, "Source file not found: #{asset[:source_path]}" unless File.exist?(asset[:source_path])
+
+      # Validate source file is readable
+      return if File.readable?(asset[:source_path])
+
+      raise PermissionError, "Cannot read source file: #{asset[:source_path]}"
+    end
+
+    def create_destination_directory(destination_dir)
+      FileUtils.mkdir_p(destination_dir)
+    rescue Errno::EACCES
+      raise PermissionError, "Cannot create destination directory: #{destination_dir}"
+    rescue Errno::ENOSPC
+      raise InstallationError, "No space left on device when creating: #{destination_dir}"
+    end
+
+    def check_destination_permissions(destination_dir)
+      return if writable_directory?(destination_dir)
+
+      raise PermissionError, "No write permission to destination directory: #{destination_dir}"
+    end
+
+    def copy_asset_file(asset)
+      FileUtils.cp(asset[:source_path], asset[:destination_path])
+      verify_file_copy(asset)
+      @rollback_files << asset[:destination_path]
+      :copied
+    rescue Errno::EACCES
+      raise PermissionError, "Permission denied when copying to: #{asset[:destination_path]}"
+    rescue Errno::ENOSPC
+      raise InstallationError, "No space left on device when copying to: #{asset[:destination_path]}"
+    rescue Errno::EIO
+      raise InstallationError, "I/O error when copying to: #{asset[:destination_path]}"
+    end
+
+    def verify_file_copy(asset)
+      # Verify the copy was successful
+      unless File.exist?(asset[:destination_path])
+        raise InstallationError, 'File copy appeared successful but destination file not found'
+      end
+
+      # Verify file sizes match
+      return if File.size(asset[:source_path]) == File.size(asset[:destination_path])
+
+      raise InstallationError, 'File copy incomplete - size mismatch'
+    end
+
+    # Check if directory is writable
+    def writable_directory?(path)
+      File.writable?(path) && File.executable?(path)
+    end
+
+    # Validate discovered assets
+    def validate_assets(assets)
+      errors = []
+
+      assets.each do |asset|
+        errors << "Source file missing: #{asset[:source_path]}" unless File.exist?(asset[:source_path])
+
+        errors << "Source file not readable: #{asset[:source_path]}" unless File.readable?(asset[:source_path])
+
+        destination_dir = File.dirname(asset[:destination_path])
+        if File.exist?(destination_dir) && !writable_directory?(destination_dir)
+          errors << "Cannot write to destination directory: #{destination_dir}"
+        end
+      end
+
+      return unless errors.any?
+
+      error_message = "Asset validation failed:\n#{errors.map { |e| "  - #{e}" }.join("\n")}"
+      raise ValidationError, error_message
+    end
+
+    # Prompt user for overwrite confirmation
+    def should_overwrite?(relative_path)
+      print "File #{relative_path} already exists. Overwrite? (y/N): "
+      response = $stdin.gets.chomp
+      response.downcase.start_with?('y')
+    end
+
+    # Determine if we should rollback based on the error type
+    def should_rollback?(error)
+      # Rollback on critical errors that could leave system in inconsistent state
+      error.is_a?(PermissionError) ||
+        (error.is_a?(InstallationError) && error.message.include?('No space left'))
+    end
+
+    # Rollback installation by removing copied files
+    def rollback_installation
+      return if @rollback_files.empty?
+
+      puts "Rolling back #{@rollback_files.count} file(s)..."
+
+      @rollback_files.reverse_each do |file_path|
+        if File.exist?(file_path)
+          File.delete(file_path)
+          puts "  ✓ Removed #{file_path}"
+        end
+      rescue StandardError => e
+        puts "  ✗ Could not remove #{file_path}: #{e.message}"
+      end
+
+      @rollback_files.clear
+    end
+
+    # Discover JavaScript controllers in the meta_workflows namespace
+    def discover_javascript_assets
+      assets = []
+      js_source_dir = File.join(gem_root, 'app', 'assets', 'javascripts', 'meta_workflows')
+
+      return assets unless Dir.exist?(js_source_dir)
+
+      begin
+        Dir.glob(File.join(js_source_dir, '**', '*.js')).each do |source_path|
+          assets << build_javascript_asset(source_path, js_source_dir)
+        end
+      rescue StandardError => e
+        raise SourceError, "Error discovering JavaScript assets: #{e.message}"
+      end
+
+      assets
+    end
+
+    def build_javascript_asset(source_path, js_source_dir)
+      relative_path = source_path.sub("#{js_source_dir}/", '')
+
+      # Determine destination based on file type
+      if relative_path.start_with?('controllers/')
+        build_controller_asset(source_path, relative_path)
+      else
+        build_general_js_asset(source_path, relative_path)
+      end
+    end
+
+    def build_controller_asset(source_path, relative_path)
+      controller_name = File.basename(relative_path)
+      destination_path = File.join(host_app_root, 'app', 'javascript', 'controllers', 'meta_workflows',
+                                   controller_name)
+      display_path = "app/javascript/controllers/meta_workflows/#{controller_name}"
+
+      {
+        type: :javascript,
+        source_path: source_path,
+        destination_path: destination_path,
+        relative_path: display_path
+      }
+    end
+
+    def build_general_js_asset(source_path, relative_path)
+      destination_path = File.join(host_app_root, 'app', 'javascript', 'meta_workflows', relative_path)
+      display_path = "app/javascript/meta_workflows/#{relative_path}"
+
+      {
+        type: :javascript,
+        source_path: source_path,
+        destination_path: destination_path,
+        relative_path: display_path
+      }
+    end
+
+    # Discover stylesheets in the meta_workflows namespace
+    def discover_stylesheet_assets
+      assets = []
+      css_source_dir = File.join(gem_root, 'app', 'assets', 'stylesheets', 'meta_workflows')
+
+      return assets unless Dir.exist?(css_source_dir)
+
+      begin
+        Dir.glob(File.join(css_source_dir, '**', '*.css')).each do |source_path|
+          relative_path = source_path.sub("#{css_source_dir}/", '')
+          destination_path = File.join(host_app_root, 'app', 'assets', 'stylesheets', 'meta_workflows', relative_path)
+
+          assets << {
+            type: :stylesheet,
+            source_path: source_path,
+            destination_path: destination_path,
+            relative_path: "app/assets/stylesheets/meta_workflows/#{relative_path}"
+          }
+        end
+      rescue StandardError => e
+        raise SourceError, "Error discovering stylesheet assets: #{e.message}"
+      end
+
+      assets
+    end
+  end
+end

data/lib/meta_workflows/configuration.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module MetaWorkflows
+  class Configuration
+    attr_accessor :default_workflow_timeout,
+                  :max_retry_attempts,
+                  :workflow_definitions_path,
+                  :enable_ui_components,
+                  :sidekiq_queue_name
+
+    def initialize
+      @default_workflow_timeout = 1800 # 30 minutes in seconds
+      @max_retry_attempts = 3
+      @workflow_definitions_path = if defined?(Rails) && Rails.respond_to?(:root) && Rails.root
+                                     Rails.root.join(
+                                       'config/workflows'
+                                     )
+                                   end
+      @enable_ui_components = true
+      @sidekiq_queue_name = 'meta_workflows'
+    end
+  end
+
+  class << self
+    attr_writer :configuration
+
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield(configuration)
+    end
+
+    def reset_configuration!
+      @configuration = Configuration.new
+    end
+  end
+end

data/lib/meta_workflows/engine.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module MetaWorkflows
+  class Engine < ::Rails::Engine
+    isolate_namespace MetaWorkflows
+
+    # Add autoload paths for engine components
+    config.autoload_paths += %W[
+      #{root}/app/controllers/concerns
+      #{root}/app/models/concerns
+      #{root}/app/services
+      #{root}/app/components
+      #{root}/app/jobs
+      #{root}/app/sidekiq
+      #{root}/lib
+    ]
+
+    # Configure generators
+    config.generators do |g|
+      g.test_framework :rspec
+      g.fixture_replacement :factory_bot
+      g.factory_bot dir: 'spec/factories'
+    end
+
+    # Initialize engine configuration
+    initializer 'meta_workflows.configure' do |app|
+      # Ensure Sidekiq is available for background jobs
+      if defined?(Sidekiq)
+        # Configure Sidekiq for MetaWorkflows jobs
+        app.config.active_job.queue_adapter = :sidekiq
+      end
+
+      # Configure ViewComponent if available
+      if defined?(ViewComponent)
+        existing_paths = [*ViewComponent::Base.view_component_path]
+        engine_component_path = root.join('app', 'components').to_s
+
+        app.config.view_component.view_component_path = (existing_paths + [engine_component_path]).uniq
+      end
+    end
+
+    # Configure routes
+    initializer 'meta_workflows.routes' do |app|
+      # Routes will be mounted by the host application
+    end
+  end
+end

data/lib/meta_workflows/export_execution_service.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module MetaWorkflows
+  class ExportExecutionService
+    def initialize(execution)
+      @execution = execution
+    end
+
+    def export_data
+      {
+        execution: execution_data,
+        workflow: workflow_data,
+        workflow_steps: workflow_steps_data
+      }
+    end
+
+    private
+
+    def execution_data
+      {
+        id: @execution.id,
+        workflow_id: @execution.workflow_id,
+        workflow_name: @execution.workflow.name,
+        record_type: @execution.record_type,
+        record_id: @execution.record_id,
+        current_step: @execution.current_step,
+        completed: @execution.completed,
+        workflow_params: @execution.workflow_params,
+        created_at: @execution.created_at,
+        updated_at: @execution.updated_at
+      }
+    end
+
+    def workflow_data
+      {
+        id: @execution.workflow.id,
+        name: @execution.workflow.name,
+        recipe: @execution.workflow.recipe
+      }
+    end
+
+    def workflow_steps_data
+      @execution.workflow_steps.order(:step).map do |step|
+        {
+          id: step.id,
+          step: step.step,
+          workflow_execution_id: step.workflow_execution_id,
+          chat_id: step.chat_id,
+          created_at: step.created_at,
+          updated_at: step.updated_at,
+          chat: step.chat&.as_json(include: { messages: { include: :tool_calls } })
+        }
+      end
+    end
+  end
+end

data/lib/meta_workflows/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module MetaWorkflows
+  VERSION = '0.7.0'
+end

data/lib/meta_workflows.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require 'meta_workflows/version'
+require 'meta_workflows/configuration'
+require 'meta_workflows/engine'
+
+module MetaWorkflows
+  # Engine provides the main interface for configuration and setup
+end

data/lib/services/meta_workflows/application_service.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Services
+  module MetaWorkflows
+    class ApplicationService
+      def self.call(*, &)
+        new(*, &).call
+      end
+    end
+  end
+end