pg_sql_triggers 1.1.1 → 1.3.0

data/lib/pg_sql_triggers/errors.rb

@@ -0,0 +1,245 @@
+# frozen_string_literal: true
+
+module PgSqlTriggers
+  # Base error class for all PgSqlTriggers errors
+  #
+  # All errors in PgSqlTriggers inherit from this base class and include
+  # error codes for programmatic handling, standardized messages, and
+  # recovery suggestions.
+  class Error < StandardError
+    attr_reader :error_code, :recovery_suggestion, :context
+
+    def initialize(message = nil, error_code: nil, recovery_suggestion: nil, context: {})
+      @context = context || {}
+      @error_code = error_code || default_error_code
+      @recovery_suggestion = recovery_suggestion || default_recovery_suggestion
+      super(message || default_message)
+    end
+
+    # Returns a user-friendly error message suitable for UI display
+    def user_message
+      msg = message
+      msg += "\n\nRecovery: #{recovery_suggestion}" if recovery_suggestion
+      msg
+    end
+
+    # Returns error details as a hash for programmatic access
+    def to_h
+      {
+        error_class: self.class.name,
+        error_code: error_code,
+        message: message,
+        recovery_suggestion: recovery_suggestion,
+        context: context
+      }
+    end
+
+    protected
+
+    def default_error_code
+      # Convert class name to error code (e.g., "PermissionError" -> "PERMISSION_ERROR")
+      class_name = self.class.name.split("::").last
+      class_name.gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2')
+                .gsub(/([a-z\d])([A-Z])/, '\1_\2')
+                .upcase
+    end
+
+    def default_message
+      "An error occurred in PgSqlTriggers"
+    end
+
+    def default_recovery_suggestion
+      "Please check the logs for more details and contact support if the issue persists."
+    end
+  end
+
+  # Error raised when permission checks fail
+  #
+  # @example
+  #   raise PgSqlTriggers::PermissionError.new(
+  #     "Permission denied: enable_trigger requires Operator level access",
+  #     error_code: "PERMISSION_DENIED",
+  #     recovery_suggestion: "Contact your administrator to request Operator or Admin access",
+  #     context: { action: :enable_trigger, required_role: "Operator" }
+  #   )
+  class PermissionError < Error
+    def default_error_code
+      "PERMISSION_DENIED"
+    end
+
+    def default_message
+      "Permission denied for this operation"
+    end
+
+    def default_recovery_suggestion
+      if context[:required_role]
+        "This operation requires #{context[:required_role]} level access. " \
+          "Contact your administrator to request appropriate permissions."
+      else
+        "This operation requires elevated permissions. Contact your administrator."
+      end
+    end
+  end
+
+  # Error raised when kill switch blocks an operation
+  #
+  # @example
+  #   raise PgSqlTriggers::KillSwitchError.new(
+  #     "Kill switch is active for production environment",
+  #     error_code: "KILL_SWITCH_ACTIVE",
+  #     recovery_suggestion: "Provide confirmation text to override: EXECUTE OPERATION_NAME",
+  #     context: { operation: :trigger_enable, environment: "production" }
+  #   )
+  class KillSwitchError < Error
+    def default_error_code
+      "KILL_SWITCH_ACTIVE"
+    end
+
+    def default_message
+      "Kill switch is active for this environment"
+    end
+
+    def default_recovery_suggestion
+      ctx = @context || {}
+      ctx[:operation] || "this operation"
+      environment = ctx[:environment] || "this environment"
+      "Kill switch is active for #{environment}. " \
+        "To override, provide the required confirmation text. " \
+        "For CLI/rake tasks, use: KILL_SWITCH_OVERRIDE=true CONFIRMATION_TEXT=\"...\" rake your:task"
+    end
+  end
+
+  # Error raised when drift is detected
+  #
+  # @example
+  #   raise PgSqlTriggers::DriftError.new(
+  #     "Trigger 'users_email_validation' has drifted from definition",
+  #     error_code: "DRIFT_DETECTED",
+  #     recovery_suggestion: "Run migration to sync trigger, or re-execute trigger to apply current definition",
+  #     context: { trigger_name: "users_email_validation", drift_type: "function_body" }
+  #   )
+  class DriftError < Error
+    def default_error_code
+      "DRIFT_DETECTED"
+    end
+
+    def default_message
+      "Trigger has drifted from its definition"
+    end
+
+    def default_recovery_suggestion
+      trigger_name = context[:trigger_name] || "trigger"
+      "Trigger '#{trigger_name}' has drifted. " \
+        "Run 'rake trigger:migrate' to sync the trigger, or use the re-execute feature " \
+        "to apply the current definition."
+    end
+  end
+
+  # Error raised when validation fails
+  #
+  # @example
+  #   raise PgSqlTriggers::ValidationError.new(
+  #     "Invalid trigger definition: table name is required",
+  #     error_code: "VALIDATION_FAILED",
+  #     recovery_suggestion: "Ensure all required fields are provided in the trigger definition",
+  #     context: { field: :table_name, errors: ["is required"] }
+  #   )
+  class ValidationError < Error
+    def default_error_code
+      "VALIDATION_FAILED"
+    end
+
+    def default_message
+      "Validation failed"
+    end
+
+    def default_recovery_suggestion
+      if context[:field]
+        "Please fix the #{context[:field]} field and try again."
+      else
+        "Please review the input and ensure all required fields are provided."
+      end
+    end
+  end
+
+  # Error raised when SQL execution fails
+  #
+  # @example
+  #   raise PgSqlTriggers::ExecutionError.new(
+  #     "SQL execution failed: syntax error near 'INVALID'",
+  #     error_code: "EXECUTION_FAILED",
+  #     recovery_suggestion: "Review SQL syntax and ensure all references are valid",
+  #     context: { sql: "SELECT * FROM...", database_error: "..." }
+  #   )
+  class ExecutionError < Error
+    def default_error_code
+      "EXECUTION_FAILED"
+    end
+
+    def default_message
+      "SQL execution failed"
+    end
+
+    def default_recovery_suggestion
+      if context[:database_error]
+        "Review the SQL syntax and database error. Ensure all table and column names are correct."
+      else
+        "Review the SQL and ensure it is valid PostgreSQL syntax."
+      end
+    end
+  end
+
+  # Error raised when unsafe migrations are attempted
+  #
+  # @example
+  #   raise PgSqlTriggers::UnsafeMigrationError.new(
+  #     "Migration contains unsafe DROP + CREATE operations",
+  #     error_code: "UNSAFE_MIGRATION",
+  #     recovery_suggestion: "Review migration safety or set allow_unsafe_migrations=true",
+  #     context: { violations: [...] }
+  #   )
+  class UnsafeMigrationError < Error
+    def default_error_code
+      "UNSAFE_MIGRATION"
+    end
+
+    def default_message
+      "Migration contains unsafe operations"
+    end
+
+    def default_recovery_suggestion
+      "Review the migration for unsafe operations. " \
+        "If you are certain the migration is safe, you can set " \
+        "PgSqlTriggers.configure { |c| c.allow_unsafe_migrations = true } " \
+        "or use the kill switch override mechanism."
+    end
+  end
+
+  # Error raised when a trigger is not found
+  #
+  # @example
+  #   raise PgSqlTriggers::NotFoundError.new(
+  #     "Trigger 'users_email_validation' not found",
+  #     error_code: "TRIGGER_NOT_FOUND",
+  #     recovery_suggestion: "Verify trigger name or create the trigger first",
+  #     context: { trigger_name: "users_email_validation" }
+  #   )
+  class NotFoundError < Error
+    def default_error_code
+      "NOT_FOUND"
+    end
+
+    def default_message
+      "Resource not found"
+    end
+
+    def default_recovery_suggestion
+      if context[:trigger_name]
+        "Trigger '#{context[:trigger_name]}' not found. " \
+          "Verify the trigger name or create the trigger first using the generator or DSL."
+      else
+        "The requested resource was not found. Verify the identifier and try again."
+      end
+    end
+  end
+end

data/lib/pg_sql_triggers/generator/service.rb

@@ -6,9 +6,24 @@ require "active_support/core_ext/string/inflections"
 
 module PgSqlTriggers
   module Generator
+    # Service object for generating trigger DSL files, migration files, and registering triggers.
+    #
+    # This service follows the service object pattern with class methods for stateless operations.
+    #
+    # @example Generate trigger files
+    #   form = PgSqlTriggers::Generator::Form.new(trigger_name: "users_email_validation", ...)
+    #   result = PgSqlTriggers::Generator::Service.create_trigger(form, actor: current_user)
+    #
+    #   if result[:success]
+    #     puts "Created: #{result[:migration_path]}"
+    #   end
     # rubocop:disable Metrics/ClassLength
     class Service
       class << self
+        # Generates the DSL trigger definition code from a form.
+        #
+        # @param form [PgSqlTriggers::Generator::Form] The form containing trigger parameters
+        # @return [String] The generated DSL code
         def generate_dsl(form)
           # Generate DSL trigger definition
           events_list = form.events.compact_blank.map { |e| ":#{e}" }.join(", ")
@@ -44,6 +59,10 @@ module PgSqlTriggers
           code
         end
 
+        # Generates the migration file code from a form.
+        #
+        # @param form [PgSqlTriggers::Generator::Form] The form containing trigger parameters
+        # @return [String] The generated migration code
         def generate_migration(form)
           # Generate migration class code
           # Use Rails migration naming convention: Add{TriggerName}
@@ -95,6 +114,10 @@ module PgSqlTriggers
           RUBY
         end
 
+        # Generates a PL/pgSQL function stub template.
+        #
+        # @param form [PgSqlTriggers::Generator::Form] The form containing trigger parameters
+        # @return [String, nil] The generated function stub SQL, or nil if not requested
         def generate_function_stub(form)
           return nil unless form.generate_function_stub
 
@@ -138,6 +161,10 @@ module PgSqlTriggers
           SQL
         end
 
+        # Returns the file paths where the migration and DSL files will be created.
+        #
+        # @param form [PgSqlTriggers::Generator::Form] The form containing trigger parameters
+        # @return [Hash] Hash with :migration and :dsl keys containing relative file paths
         def file_paths(form)
           # NOTE: These paths are relative to the host Rails app, not the gem
           # Generate both migration file and DSL file
@@ -148,6 +175,11 @@ module PgSqlTriggers
           }
         end
 
+        # Creates trigger files (DSL and migration) and registers the trigger in the registry.
+        #
+        # @param form [PgSqlTriggers::Generator::Form] The form containing trigger parameters
+        # @param actor [Hash, nil] Optional actor information for audit logging
+        # @return [Hash] Result hash with :success (Boolean), :migration_path, :dsl_path, and optional :error
         def create_trigger(form, actor: nil) # rubocop:disable Lint/UnusedMethodArgument
           paths = file_paths(form)
           base_path = rails_base_path

data/lib/pg_sql_triggers/permissions/checker.rb

@@ -22,8 +22,15 @@ module PgSqlTriggers
         unless can?(actor, action, environment: environment)
           action_sym = action.to_sym
           required_level = Permissions::ACTIONS[action_sym] || "unknown"
-          raise PgSqlTriggers::PermissionError,
-                "Permission denied: #{action_sym} requires #{required_level} level access"
+          message = "Permission denied: #{action_sym} requires #{required_level} level access"
+          recovery = "Contact your administrator to request #{required_level} level access for this operation."
+
+          raise PgSqlTriggers::PermissionError.new(
+            message,
+            error_code: "PERMISSION_DENIED",
+            recovery_suggestion: recovery,
+            context: { action: action_sym, required_role: required_level, environment: environment }
+          )
         end
         true
       end

data/lib/pg_sql_triggers/registry/manager.rb

@@ -33,8 +33,13 @@ module PgSqlTriggers
           trigger_name = definition.name
 
           # Use cached lookup if available to avoid N+1 queries during trigger file loading
-          existing = _registry_cache[trigger_name] ||=
-            PgSqlTriggers::TriggerRegistry.find_by(trigger_name: trigger_name)
+          # Explicitly check cache first to avoid query in some Ruby versions where ||= may evaluate RHS
+          existing = if _registry_cache.key?(trigger_name)
+                       _registry_cache[trigger_name]
+                     else
+                       _registry_cache[trigger_name] =
+                         PgSqlTriggers::TriggerRegistry.find_by(trigger_name: trigger_name)
+                     end
 
           # Calculate checksum using field-concatenation (consistent with TriggerRegistry model)
           checksum = calculate_checksum(definition)
@@ -51,17 +56,27 @@ module PgSqlTriggers
           }
 
           if existing
-            begin
-              existing.update!(attributes)
-              # Update cache with the modified record (reload to get fresh data)
-              reloaded = existing.reload
-              _registry_cache[trigger_name] = reloaded
-              reloaded
-            rescue ActiveRecord::RecordNotFound
-              # Cached record was deleted, create a new one
-              new_record = PgSqlTriggers::TriggerRegistry.create!(attributes)
-              _registry_cache[trigger_name] = new_record
-              new_record
+            # Check if attributes have actually changed to avoid unnecessary queries
+            attributes_changed = attributes.any? do |key, value|
+              existing.send(key) != value
+            end
+
+            if attributes_changed
+              begin
+                existing.update!(attributes)
+                # Update cache with the modified record (reload to get fresh data)
+                reloaded = existing.reload
+                _registry_cache[trigger_name] = reloaded
+                reloaded
+              rescue ActiveRecord::RecordNotFound
+                # Cached record was deleted, create a new one
+                new_record = PgSqlTriggers::TriggerRegistry.create!(attributes)
+                _registry_cache[trigger_name] = new_record
+                new_record
+              end
+            else
+              # No changes, return cached record without any queries
+              existing
             end
           else
             new_record = PgSqlTriggers::TriggerRegistry.create!(attributes)

data/lib/pg_sql_triggers/registry.rb

@@ -1,36 +1,210 @@
 # frozen_string_literal: true
 
 module PgSqlTriggers
+  # Registry module provides a unified API for querying and managing triggers.
+  #
+  # @example Query triggers
+  #   # List all triggers
+  #   triggers = PgSqlTriggers::Registry.list
+  #
+  #   # Get enabled/disabled triggers
+  #   enabled = PgSqlTriggers::Registry.enabled
+  #   disabled = PgSqlTriggers::Registry.disabled
+  #
+  #   # Get triggers for a specific table
+  #   user_triggers = PgSqlTriggers::Registry.for_table(:users)
+  #
+  #   # Check for drift
+  #   drift_info = PgSqlTriggers::Registry.diff
+  #
+  # @example Manage triggers
+  #   # Enable a trigger
+  #   PgSqlTriggers::Registry.enable("users_email_validation",
+  #                                   actor: current_user,
+  #                                   confirmation: "EXECUTE TRIGGER_ENABLE")
+  #
+  #   # Disable a trigger
+  #   PgSqlTriggers::Registry.disable("users_email_validation",
+  #                                    actor: current_user,
+  #                                    confirmation: "EXECUTE TRIGGER_DISABLE")
+  #
+  #   # Drop a trigger
+  #   PgSqlTriggers::Registry.drop("old_trigger",
+  #                                 actor: current_user,
+  #                                 reason: "No longer needed",
+  #                                 confirmation: "EXECUTE TRIGGER_DROP")
+  #
+  #   # Re-execute a trigger
+  #   PgSqlTriggers::Registry.re_execute("drifted_trigger",
+  #                                       actor: current_user,
+  #                                       reason: "Fix drift",
+  #                                       confirmation: "EXECUTE TRIGGER_RE_EXECUTE")
   module Registry
     autoload :Manager, "pg_sql_triggers/registry/manager"
     autoload :Validator, "pg_sql_triggers/registry/validator"
 
+    # Registers a trigger definition in the registry.
+    #
+    # @param definition [PgSqlTriggers::DSL::TriggerDefinition] The trigger definition to register
+    # @return [PgSqlTriggers::TriggerRegistry] The registered trigger record
     def self.register(definition)
       Manager.register(definition)
     end
 
+    # Returns all registered triggers.
+    #
+    # @return [ActiveRecord::Relation<PgSqlTriggers::TriggerRegistry>] All trigger records
     def self.list
       Manager.list
     end
 
+    # Returns only enabled triggers.
+    #
+    # @return [ActiveRecord::Relation<PgSqlTriggers::TriggerRegistry>] Enabled trigger records
     def self.enabled
       Manager.enabled
     end
 
+    # Returns only disabled triggers.
+    #
+    # @return [ActiveRecord::Relation<PgSqlTriggers::TriggerRegistry>] Disabled trigger records
     def self.disabled
       Manager.disabled
     end
 
+    # Returns triggers for a specific table.
+    #
+    # @param table_name [String, Symbol] The table name to filter by
+    # @return [ActiveRecord::Relation<PgSqlTriggers::TriggerRegistry>] Triggers for the specified table
     def self.for_table(table_name)
       Manager.for_table(table_name)
     end
 
-    def self.diff
-      Manager.diff
+    # Checks for drift between DSL definitions and database state.
+    #
+    # @param trigger_name [String, nil] Optional trigger name to check specific trigger, or nil for all triggers
+    # @return [Hash] Drift information with keys: :in_sync, :drifted, :manual_override, :disabled, :dropped, :unknown
+    def self.diff(trigger_name = nil)
+      Manager.diff(trigger_name)
     end
 
+    # Returns all triggers that have drifted from their expected state.
+    #
+    # @return [Array<Hash>] Array of drift result hashes for drifted triggers
+    def self.drifted
+      Manager.drifted
+    end
+
+    # Returns all triggers that are in sync with their expected state.
+    #
+    # @return [Array<Hash>] Array of drift result hashes for in-sync triggers
+    def self.in_sync
+      Manager.in_sync
+    end
+
+    # Returns all unknown (external) triggers not managed by this gem.
+    #
+    # @return [Array<Hash>] Array of drift result hashes for unknown triggers
+    def self.unknown_triggers
+      Manager.unknown_triggers
+    end
+
+    # Returns all triggers that have been dropped from the database.
+    #
+    # @return [Array<Hash>] Array of drift result hashes for dropped triggers
+    def self.dropped
+      Manager.dropped
+    end
+
+    # Validates all triggers in the registry.
+    #
+    # @raise [PgSqlTriggers::ValidationError] If validation fails
+    # @return [true] If validation passes
     def self.validate!
       Validator.validate!
     end
+
+    # Enables a trigger by name.
+    #
+    # @param trigger_name [String] The name of the trigger to enable
+    # @param actor [Hash] Information about who is performing the action (must have :type and :id keys)
+    # @param confirmation [String, nil] Optional confirmation text for kill switch protection
+    # @raise [PgSqlTriggers::PermissionError] If actor lacks permission
+    # @raise [PgSqlTriggers::KillSwitchError] If kill switch blocks the operation
+    # @raise [PgSqlTriggers::NotFoundError] If trigger not found
+    # @return [PgSqlTriggers::TriggerRegistry] The updated trigger record
+    def self.enable(trigger_name, actor:, confirmation: nil)
+      check_permission!(actor, :enable_trigger)
+      trigger = find_trigger!(trigger_name)
+      trigger.enable!(confirmation: confirmation, actor: actor)
+    end
+
+    # Disables a trigger by name.
+    #
+    # @param trigger_name [String] The name of the trigger to disable
+    # @param actor [Hash] Information about who is performing the action (must have :type and :id keys)
+    # @param confirmation [String, nil] Optional confirmation text for kill switch protection
+    # @raise [PgSqlTriggers::PermissionError] If actor lacks permission
+    # @raise [PgSqlTriggers::KillSwitchError] If kill switch blocks the operation
+    # @raise [PgSqlTriggers::NotFoundError] If trigger not found
+    # @return [PgSqlTriggers::TriggerRegistry] The updated trigger record
+    def self.disable(trigger_name, actor:, confirmation: nil)
+      check_permission!(actor, :disable_trigger)
+      trigger = find_trigger!(trigger_name)
+      trigger.disable!(confirmation: confirmation, actor: actor)
+    end
+
+    # Drops a trigger by name.
+    #
+    # @param trigger_name [String] The name of the trigger to drop
+    # @param actor [Hash] Information about who is performing the action (must have :type and :id keys)
+    # @param reason [String] Required reason for dropping the trigger
+    # @param confirmation [String, nil] Optional confirmation text for kill switch protection
+    # @raise [PgSqlTriggers::PermissionError] If actor lacks permission
+    # @raise [PgSqlTriggers::KillSwitchError] If kill switch blocks the operation
+    # @raise [PgSqlTriggers::NotFoundError] If trigger not found
+    # @raise [ArgumentError] If reason is missing or empty
+    # @return [true] If drop succeeds
+    def self.drop(trigger_name, actor:, reason:, confirmation: nil)
+      check_permission!(actor, :drop_trigger)
+      trigger = find_trigger!(trigger_name)
+      trigger.drop!(reason: reason, confirmation: confirmation, actor: actor)
+    end
+
+    # Re-executes a trigger by name (drops and recreates it).
+    #
+    # @param trigger_name [String] The name of the trigger to re-execute
+    # @param actor [Hash] Information about who is performing the action (must have :type and :id keys)
+    # @param reason [String] Required reason for re-executing the trigger
+    # @param confirmation [String, nil] Optional confirmation text for kill switch protection
+    # @raise [PgSqlTriggers::PermissionError] If actor lacks permission
+    # @raise [PgSqlTriggers::KillSwitchError] If kill switch blocks the operation
+    # @raise [PgSqlTriggers::NotFoundError] If trigger not found
+    # @raise [ArgumentError] If reason is missing or empty
+    # @return [PgSqlTriggers::TriggerRegistry] The updated trigger record
+    def self.re_execute(trigger_name, actor:, reason:, confirmation: nil)
+      check_permission!(actor, :drop_trigger) # Re-execute requires same permission as drop
+      trigger = find_trigger!(trigger_name)
+      trigger.re_execute!(reason: reason, confirmation: confirmation, actor: actor)
+    end
+
+    # Private helper methods
+
+    def self.find_trigger!(trigger_name)
+      PgSqlTriggers::TriggerRegistry.find_by!(trigger_name: trigger_name)
+    rescue ActiveRecord::RecordNotFound
+      raise PgSqlTriggers::NotFoundError.new(
+        "Trigger '#{trigger_name}' not found in registry",
+        error_code: "TRIGGER_NOT_FOUND",
+        recovery_suggestion: "Verify the trigger name or create the trigger first using the generator or DSL.",
+        context: { trigger_name: trigger_name }
+      )
+    end
+    private_class_method :find_trigger!
+
+    def self.check_permission!(actor, action)
+      PgSqlTriggers::Permissions.check!(actor, action)
+    end
+    private_class_method :check_permission!
   end
 end

data/lib/pg_sql_triggers/sql/capsule.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+require "digest"
+
+module PgSqlTriggers
+  module SQL
+    # Capsule represents a named SQL capsule with environment declaration and purpose
+    # Used for emergency operations and manual SQL execution
+    #
+    # @example Creating a SQL capsule
+    #   capsule = PgSqlTriggers::SQL::Capsule.new(
+    #     name: "fix_user_permissions",
+    #     environment: "production",
+    #     purpose: "Emergency fix for user permission issue",
+    #     sql: "UPDATE users SET role = 'admin' WHERE email = 'admin@example.com';"
+    #   )
+    #
+    class Capsule
+      attr_reader :name, :environment, :purpose, :sql, :created_at
+
+      # @param name [String] The name of the SQL capsule
+      # @param environment [String] The environment this capsule is intended for
+      # @param purpose [String] Description of what this capsule does and why
+      # @param sql [String] The SQL to execute
+      # @param created_at [Time, nil] The timestamp when the capsule was created (defaults to now)
+      def initialize(name:, environment:, purpose:, sql:, created_at: nil)
+        @name = name
+        @environment = environment
+        @purpose = purpose
+        @sql = sql
+        @created_at = created_at || Time.current
+        validate!
+      end
+
+      # Calculates the checksum of the SQL content
+      # @return [String] The SHA256 checksum of the SQL
+      def checksum
+        @checksum ||= Digest::SHA256.hexdigest(sql.to_s)
+      end
+
+      # Converts the capsule to a hash suitable for storage
+      # @return [Hash] The capsule data
+      def to_h
+        {
+          name: name,
+          environment: environment,
+          purpose: purpose,
+          sql: sql,
+          checksum: checksum,
+          created_at: created_at
+        }
+      end
+
+      # Returns the registry trigger name for this capsule
+      # SQL capsules are stored in the registry with a special naming pattern
+      # @return [String] The trigger name for registry storage
+      def registry_trigger_name
+        "sql_capsule_#{name}"
+      end
+
+      private
+
+      def validate!
+        errors = []
+        errors << "Name cannot be blank" if name.nil? || name.to_s.strip.empty?
+        errors << "Environment cannot be blank" if environment.nil? || environment.to_s.strip.empty?
+        errors << "Purpose cannot be blank" if purpose.nil? || purpose.to_s.strip.empty?
+        errors << "SQL cannot be blank" if sql.nil? || sql.to_s.strip.empty?
+
+        # Validate name format (alphanumeric, underscores, hyphens only)
+        unless name.to_s.match?(/\A[a-z0-9_-]+\z/i)
+          errors << "Name must contain only letters, numbers, underscores, and hyphens"
+        end
+
+        raise ArgumentError, "Invalid capsule: #{errors.join(', ')}" if errors.any?
+      end
+    end
+  end
+end