pg_sql_triggers 1.2.0 → 1.4.0

data/lib/pg_sql_triggers/sql/kill_switch.rb

@@ -2,299 +2,205 @@
 
 module PgSqlTriggers
   module SQL
-    # KillSwitch is a centralized safety gate that prevents dangerous operations
-    # from being executed in protected environments (typically production).
-    #
-    # It operates on three levels:
-    # 1. Configuration Level: Environment-based activation via PgSqlTriggers.kill_switch_enabled
-    # 2. Runtime Level: ENV variable override support (KILL_SWITCH_OVERRIDE)
-    # 3. Explicit Confirmation Level: Typed confirmation text for critical operations
-    #
-    # @example Basic usage in a dangerous operation
-    #   KillSwitch.check!(
-    #     operation: :migrate_up,
-    #     environment: Rails.env,
-    #     confirmation: params[:confirmation_text],
-    #     actor: { type: 'UI', id: current_user.email }
-    #   )
-    #
-    # @example Using override block
-    #   KillSwitch.override(confirmation: "EXECUTE MIGRATE_UP") do
-    #     # dangerous operation here
-    #   end
+    # Private helpers for KillSwitch – not part of the public API.
+    module KillSwitchHelpers
+      def validate_confirmation!(confirmation, operation)
+        expected = expected_confirmation(operation)
+
+        if confirmation.nil? || confirmation.strip.empty?
+          raise PgSqlTriggers::KillSwitchError.new(
+            "Confirmation text required. Expected: '#{expected}'",
+            error_code: "KILL_SWITCH_CONFIRMATION_REQUIRED",
+            recovery_suggestion: "Provide the confirmation text: #{expected}",
+            context: { operation: operation, expected_confirmation: expected }
+          )
+        end
+
+        return if confirmation.strip == expected
+
+        raise PgSqlTriggers::KillSwitchError.new(
+          "Invalid confirmation text. Expected: '#{expected}', got: '#{confirmation.strip}'",
+          error_code: "KILL_SWITCH_CONFIRMATION_INVALID",
+          recovery_suggestion: "Use the exact confirmation text: #{expected}",
+          context: {
+            operation: operation,
+            expected_confirmation: expected,
+            provided_confirmation: confirmation.strip
+          }
+        )
+      end
+
+      def kill_switch_enabled?
+        return true unless PgSqlTriggers.respond_to?(:kill_switch_enabled)
+
+        value = PgSqlTriggers.kill_switch_enabled
+        value.nil? || value
+      end
+
+      def protected_environment?(env)
+        return false if env.nil?
+
+        configured = PgSqlTriggers.kill_switch_environments if PgSqlTriggers.respond_to?(:kill_switch_environments)
+        Array(configured || %i[production staging]).map(&:to_s).include?(env.to_s)
+      end
+
+      def resolve_environment(environment)
+        return environment.to_s if environment.present?
+        return Rails.env.to_s if defined?(Rails) && Rails.respond_to?(:env)
+
+        if PgSqlTriggers.respond_to?(:default_environment) && PgSqlTriggers.default_environment.respond_to?(:call)
+          begin
+            return PgSqlTriggers.default_environment.call.to_s
+          rescue NameError, NoMethodError => e # rubocop:disable Lint/ShadowedException
+            logger&.debug "[KILL_SWITCH] Could not resolve default_environment: #{e.message}"
+          end
+        end
+
+        ENV["RAILS_ENV"] || ENV["RACK_ENV"] || "development"
+      end
+
+      def confirmation_required?
+        return true unless PgSqlTriggers.respond_to?(:kill_switch_confirmation_required)
+
+        value = PgSqlTriggers.kill_switch_confirmation_required
+        value.nil? || value
+      end
+
+      def expected_confirmation(operation)
+        if PgSqlTriggers.respond_to?(:kill_switch_confirmation_pattern) &&
+           PgSqlTriggers.kill_switch_confirmation_pattern.respond_to?(:call)
+          PgSqlTriggers.kill_switch_confirmation_pattern.call(operation)
+        else
+          "EXECUTE #{operation.to_s.upcase}"
+        end
+      end
+
+      def logger
+        if PgSqlTriggers.respond_to?(:kill_switch_logger)
+          PgSqlTriggers.kill_switch_logger
+        elsif defined?(Rails) && Rails.respond_to?(:logger)
+          Rails.logger
+        end
+      end
+
+      def log(level, status, **context)
+        actor = context[:actor]
+        actor_str = if actor.is_a?(Hash)
+                      "#{actor[:type] || 'unknown'}:#{actor[:id] || 'unknown'}"
+                    else
+                      actor&.to_s || "unknown"
+                    end
+        msg = "[KILL_SWITCH] #{status}: operation=#{context[:operation]} " \
+              "environment=#{context[:environment]} actor=#{actor_str}"
+        msg = "#{msg} #{context[:extra]}" if context[:extra]
+        logger&.public_send(level, msg)
+      end
+    end
+    private_constant :KillSwitchHelpers
+
+    # KillSwitch: three-layer safety gate for dangerous operations.
     #
-    # @example CLI usage with ENV override
-    #   KILL_SWITCH_OVERRIDE=true CONFIRMATION_TEXT="EXECUTE MIGRATE_UP" rake pg_sql_triggers:migrate
+    # Layer 1 – config:  PgSqlTriggers.kill_switch_enabled / kill_switch_environments
+    # Layer 2 – ENV:     KILL_SWITCH_OVERRIDE=true (+ optional confirmation)
+    # Layer 3 – explicit: confirmation text passed directly to check!
     #
-    # rubocop:disable Metrics/ModuleLength
+    # @example
+    #   KillSwitch.check!(operation: :migrate_up, environment: Rails.env,
+    #                     confirmation: params[:confirmation_text],
+    #                     actor: { type: "UI", id: current_user.email })
     module KillSwitch
-      # Thread-local storage key for override state
       OVERRIDE_KEY = :pg_sql_triggers_kill_switch_override
 
       class << self
-        # Checks if the kill switch is active for the given environment and operation.
-        #
-        # @param environment [String, Symbol, nil] The environment to check (defaults to current environment)
-        # @param operation [String, Symbol, nil] The operation being performed (for logging)
-        # @return [Boolean] true if kill switch is active, false otherwise
-        def active?(environment: nil, operation: nil)
-          # Check if kill switch is globally disabled
-          return false unless kill_switch_enabled?
-
-          # Detect environment
-          env = detect_environment(environment)
+        include KillSwitchHelpers
 
-          # Check if this environment is protected
-          is_active = protected_environment?(env)
+        private :kill_switch_enabled?, :protected_environment?,
+                :resolve_environment, :confirmation_required?, :expected_confirmation, :logger, :log
 
-          # Log the check if logger is available and operation is provided
-          if logger && operation
-            logger.debug "[KILL_SWITCH] Check: operation=#{operation} environment=#{env} active=#{is_active}"
-          end
+        def active?(environment: nil, operation: nil)
+          return false unless kill_switch_enabled?
 
-          is_active
+          env    = resolve_environment(environment)
+          active = protected_environment?(env)
+          logger&.debug "[KILL_SWITCH] Check: operation=#{operation} environment=#{env} active=#{active}" if operation
+          active
         end
 
-        # Checks if an operation should be blocked by the kill switch.
-        # Raises KillSwitchError if the operation is blocked.
-        #
-        # @param operation [String, Symbol] The operation being performed
-        # @param environment [String, Symbol, nil] The environment (defaults to current)
-        # @param confirmation [String, nil] The confirmation text provided by the user
-        # @param actor [Hash, nil] Information about who is performing the operation
-        # @raise [PgSqlTriggers::KillSwitchError] if the operation is blocked
-        # @return [void]
         def check!(operation:, environment: nil, confirmation: nil, actor: nil)
-          env = detect_environment(environment)
+          env = resolve_environment(environment)
 
-          # Check if kill switch is active for this environment
           unless active?(environment: env, operation: operation)
-            log_allowed(operation: operation, environment: env, actor: actor, reason: "not_protected_environment")
+            log(:info, "ALLOWED",
+                operation: operation,
+                environment: env,
+                actor: actor,
+                extra: "reason=not_protected_environment")
             return
           end
 
-          # Check for thread-local override
-          if thread_override_active?
-            log_override(operation: operation, environment: env, actor: actor, source: "thread_local")
+          if Thread.current[OVERRIDE_KEY]
+            log(:warn, "OVERRIDDEN",
+                operation: operation,
+                environment: env,
+                actor: actor,
+                extra: "source=thread_local")
             return
           end
 
-          # Check for ENV override
-          if env_override_active?
-            # If ENV override is present, check confirmation if required
+          if ENV["KILL_SWITCH_OVERRIDE"]&.downcase == "true"
             if confirmation_required?
               validate_confirmation!(confirmation, operation)
-              log_override(operation: operation, environment: env, actor: actor, source: "env_with_confirmation",
-                           confirmation: confirmation)
+              log(:warn, "OVERRIDDEN",
+                  operation: operation,
+                  environment: env,
+                  actor: actor,
+                  extra: "source=env_with_confirmation confirmation=#{confirmation}")
             else
-              log_override(operation: operation, environment: env, actor: actor, source: "env_without_confirmation")
+              log(:warn, "OVERRIDDEN",
+                  operation: operation,
+                  environment: env,
+                  actor: actor,
+                  extra: "source=env_without_confirmation")
             end
             return
           end
 
-          # If confirmation is provided, validate it
           unless confirmation.nil?
             validate_confirmation!(confirmation, operation)
-            log_override(operation: operation, environment: env, actor: actor, source: "explicit_confirmation",
-                         confirmation: confirmation)
+            log(:warn, "OVERRIDDEN",
+                operation: operation,
+                environment: env,
+                actor: actor,
+                extra: "source=explicit_confirmation confirmation=#{confirmation}")
             return
           end
 
-          # No override mechanism satisfied - block the operation
-          log_blocked(operation: operation, environment: env, actor: actor)
-          raise_blocked_error(operation: operation, environment: env)
+          log(:error, "BLOCKED", operation: operation, environment: env, actor: actor)
+          expected = expected_confirmation(operation)
+          raise PgSqlTriggers::KillSwitchError.new(
+            "Kill switch is active for #{env} environment. Operation '#{operation}' has been blocked.\n\n" \
+            "To override: KILL_SWITCH_OVERRIDE=true or provide confirmation text: #{expected}",
+            error_code: "KILL_SWITCH_ACTIVE",
+            recovery_suggestion: "Provide the confirmation text: #{expected}",
+            context: { operation: operation, environment: env, expected_confirmation: expected }
+          )
         end
 
-        # Temporarily overrides the kill switch for the duration of the block.
-        # Uses thread-local storage to ensure thread safety.
-        #
-        # @param confirmation [String, nil] Optional confirmation text
-        # @yield The block to execute with kill switch overridden
-        # @return The return value of the block
         def override(confirmation: nil)
           raise ArgumentError, "Block required for kill switch override" unless block_given?
 
-          # Validate confirmation if provided and required
-          if confirmation.present? && confirmation_required?
-            # NOTE: We can't validate against a specific operation here since we don't know it
-            # The block itself will call check! with the operation, which will see the override
+          if confirmation.present?
             logger&.info "[KILL_SWITCH] Override block initiated with confirmation: #{confirmation}"
           end
-
-          # Set thread-local override
-          previous_value = Thread.current[OVERRIDE_KEY]
+          previous = Thread.current[OVERRIDE_KEY]
           Thread.current[OVERRIDE_KEY] = true
-
           begin
             yield
           ensure
-            # Restore previous value
-            Thread.current[OVERRIDE_KEY] = previous_value
+            Thread.current[OVERRIDE_KEY] = previous
           end
         end
-
-        # Validates the confirmation text against the expected pattern for the operation.
-        #
-        # @param confirmation [String, nil] The confirmation text to validate
-        # @param operation [String, Symbol] The operation being confirmed
-        # @raise [PgSqlTriggers::KillSwitchError] if confirmation is invalid
-        # @return [void]
-        def validate_confirmation!(confirmation, operation)
-          expected = expected_confirmation(operation)
-
-          if confirmation.nil? || confirmation.strip.empty?
-            raise PgSqlTriggers::KillSwitchError,
-                  "Confirmation text required. Expected: '#{expected}'"
-          end
-
-          return if confirmation.strip == expected
-
-          raise PgSqlTriggers::KillSwitchError,
-                "Invalid confirmation text. Expected: '#{expected}', got: '#{confirmation.strip}'"
-        end
-
-        private
-
-        # Checks if kill switch is globally enabled in configuration
-        def kill_switch_enabled?
-          return true unless PgSqlTriggers.respond_to?(:kill_switch_enabled)
-
-          # Default to true (fail-safe) if not configured
-          value = PgSqlTriggers.kill_switch_enabled
-          value.nil? || value
-        end
-
-        # Checks if the given environment is protected by the kill switch
-        def protected_environment?(environment)
-          return false if environment.nil?
-
-          protected_envs = if PgSqlTriggers.respond_to?(:kill_switch_environments)
-                             value = PgSqlTriggers.kill_switch_environments
-                             value.nil? ? %i[production staging] : value
-                           else
-                             %i[production staging]
-                           end
-
-          protected_envs = Array(protected_envs).map(&:to_s)
-          protected_envs.include?(environment.to_s)
-        end
-
-        # Detects the current environment
-        def detect_environment(environment)
-          return environment.to_s if environment.present?
-
-          # Try Rails environment
-          return Rails.env.to_s if defined?(Rails) && Rails.respond_to?(:env)
-
-          # Try PgSqlTriggers default_environment
-          if PgSqlTriggers.respond_to?(:default_environment) && PgSqlTriggers.default_environment.respond_to?(:call)
-            begin
-              return PgSqlTriggers.default_environment.call.to_s
-            rescue NameError, NoMethodError # rubocop:disable Lint/ShadowedException
-              # Fall through to next option if default_environment proc references undefined constants
-            end
-          end
-
-          # Fall back to RAILS_ENV or RACK_ENV
-          ENV["RAILS_ENV"] || ENV["RACK_ENV"] || "development"
-        end
-
-        # Checks if thread-local override is active
-        def thread_override_active?
-          Thread.current[OVERRIDE_KEY] == true
-        end
-
-        # Checks if ENV override is active
-        def env_override_active?
-          ENV["KILL_SWITCH_OVERRIDE"]&.downcase == "true"
-        end
-
-        # Checks if confirmation is required for overrides
-        def confirmation_required?
-          return true unless PgSqlTriggers.respond_to?(:kill_switch_confirmation_required)
-
-          # Default to true (safer) if not configured
-          value = PgSqlTriggers.kill_switch_confirmation_required
-          value.nil? || value
-        end
-
-        # Generates the expected confirmation text for an operation
-        def expected_confirmation(operation)
-          if PgSqlTriggers.respond_to?(:kill_switch_confirmation_pattern) &&
-             PgSqlTriggers.kill_switch_confirmation_pattern.respond_to?(:call)
-            PgSqlTriggers.kill_switch_confirmation_pattern.call(operation)
-          else
-            # Default pattern
-            "EXECUTE #{operation.to_s.upcase}"
-          end
-        end
-
-        # Returns the configured logger
-        def logger
-          if PgSqlTriggers.respond_to?(:kill_switch_logger)
-            PgSqlTriggers.kill_switch_logger
-          elsif defined?(Rails) && Rails.respond_to?(:logger)
-            Rails.logger
-          end
-        end
-
-        # Logs an allowed operation
-        def log_allowed(operation:, environment:, actor:, reason:)
-          actor_info = format_actor(actor)
-          logger&.info "[KILL_SWITCH] ALLOWED: operation=#{operation} environment=#{environment} " \
-                       "actor=#{actor_info} reason=#{reason}"
-        end
-
-        # Logs an overridden operation
-        def log_override(operation:, environment:, actor:, source:, confirmation: nil)
-          actor_info = format_actor(actor)
-          conf_info = confirmation ? " confirmation=#{confirmation}" : ""
-          logger&.warn "[KILL_SWITCH] OVERRIDDEN: operation=#{operation} environment=#{environment} " \
-                       "actor=#{actor_info} source=#{source}#{conf_info}"
-        end
-
-        # Logs a blocked operation
-        def log_blocked(operation:, environment:, actor:)
-          actor_info = format_actor(actor)
-          logger&.error "[KILL_SWITCH] BLOCKED: operation=#{operation} environment=#{environment} actor=#{actor_info}"
-        end
-
-        # Formats actor information for logging
-        def format_actor(actor)
-          return "unknown" if actor.nil?
-          return actor.to_s unless actor.is_a?(Hash)
-
-          "#{actor[:type] || 'unknown'}:#{actor[:id] || 'unknown'}"
-        end
-
-        # Raises a kill switch error with helpful message
-        def raise_blocked_error(operation:, environment:)
-          expected = expected_confirmation(operation)
-
-          message = <<~ERROR
-            Kill switch is active for #{environment} environment.
-            Operation '#{operation}' has been blocked for safety.
-
-            To override this protection, you must provide confirmation.
-
-            For CLI/rake tasks, use:
-              KILL_SWITCH_OVERRIDE=true CONFIRMATION_TEXT="#{expected}" rake your:task
-
-            For console operations, use:
-              PgSqlTriggers::SQL::KillSwitch.override(confirmation: "#{expected}") do
-                # your dangerous operation here
-              end
-
-            For UI operations, enter the confirmation text: #{expected}
-
-            This protection prevents accidental destructive operations in production.
-            Make sure you understand the implications before proceeding.
-          ERROR
-
-          raise PgSqlTriggers::KillSwitchError, message
-        end
       end
     end
-    # rubocop:enable Metrics/ModuleLength
   end
 end

data/lib/pg_sql_triggers/sql.rb

@@ -2,14 +2,8 @@
 
 module PgSqlTriggers
   module SQL
-    autoload :Capsule, "pg_sql_triggers/sql/capsule"
-    autoload :Executor, "pg_sql_triggers/sql/executor"
     autoload :KillSwitch, "pg_sql_triggers/sql/kill_switch"
 
-    def self.execute_capsule(capsule_name, **options)
-      Executor.execute_capsule(capsule_name, **options)
-    end
-
     def self.kill_switch_active?
       KillSwitch.active?
     end

data/lib/pg_sql_triggers/testing/function_tester.rb

@@ -110,6 +110,8 @@ module PgSqlTriggers
                 results[:function_executed] = false
                 results[:success] = false
                 results[:errors] << "Error during function verification: #{e.message}"
+                # Also add the original error message to ensure it's searchable in tests
+                results[:errors] << e.message unless results[:errors].include?(e.message)
                 results[:output] << "✓ Function created (verification failed)"
               end
             else

data/lib/pg_sql_triggers/version.rb

@@ -11,5 +11,5 @@
 # 3. Run: bundle exec rake release
 # See RELEASE.md for detailed release instructions
 module PgSqlTriggers
-  VERSION = "1.2.0"
+  VERSION = "1.4.0"
 end

data/lib/pg_sql_triggers.rb

@@ -1,15 +1,12 @@
 # frozen_string_literal: true
 
 require_relative "pg_sql_triggers/version"
+require_relative "pg_sql_triggers/errors"
 require_relative "pg_sql_triggers/engine"
 
 module PgSqlTriggers
-  class Error < StandardError; end
-  class PermissionError < Error; end
-  class DriftError < Error; end
-  class KillSwitchError < Error; end
-  class ValidationError < Error; end
-  class UnsafeMigrationError < Error; end
+  # Error classes are defined in lib/pg_sql_triggers/errors.rb
+  # They include error codes, standardized messages, and recovery suggestions
 
   # Configuration
   mattr_accessor :kill_switch_enabled
@@ -39,6 +36,10 @@ module PgSqlTriggers
   mattr_accessor :allow_unsafe_migrations
   self.allow_unsafe_migrations = false
 
+  # PostgreSQL schema used by DbQueries. Override for non-public schemas.
+  mattr_accessor :db_schema
+  self.db_schema = "public"
+
   # Drift states
   DRIFT_STATE_IN_SYNC = "in_sync"
   DRIFT_STATE_DRIFTED = "drifted"
@@ -58,7 +59,6 @@ module PgSqlTriggers
   autoload :Permissions, "pg_sql_triggers/permissions"
   autoload :SQL, "pg_sql_triggers/sql"
   autoload :DatabaseIntrospection, "pg_sql_triggers/database_introspection"
-  autoload :Generator, "pg_sql_triggers/generator"
   autoload :Testing, "pg_sql_triggers/testing"
   autoload :Migration, "pg_sql_triggers/migration"
   autoload :Migrator, "pg_sql_triggers/migrator"

data/pg_sql_triggers.gemspec

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require_relative "lib/pg_sql_triggers/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "pg_sql_triggers"
+  spec.version = PgSqlTriggers::VERSION
+  spec.authors = ["samaswin"]
+  spec.email = ["samaswin@gmail.com"]
+
+  spec.summary = "A PostgreSQL Trigger Control Plane for Rails"
+  spec.description = "Production-grade PostgreSQL trigger management for Rails with " \
+                     "lifecycle management, safe deploys, versioning, drift detection, " \
+                     "and a mountable UI."
+  spec.homepage = "https://github.com/samaswin/pg_sql_triggers"
+  spec.license = "MIT"
+  spec.required_ruby_version = ">= 3.0.0"
+
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = "https://github.com/samaswin/pg_sql_triggers"
+  spec.metadata["changelog_uri"] = "https://github.com/samaswin/pg_sql_triggers/blob/main/CHANGELOG.md"
+  spec.metadata["github_repo"] = "ssh://github.com/samaswin/pg_sql_triggers"
+  spec.metadata["rubygems_mfa_required"] = "true"
+
+  # Specify which files should be added to the gem when it is released.
+  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
+  spec.files = Dir.chdir(__dir__) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      (File.expand_path(f) == __FILE__) ||
+        f.start_with?(*%w[bin/ test/ spec/ features/ .git appveyor Gemfile docs/screenshots/])
+    end
+  end
+  spec.bindir = "exe"
+  spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  # Runtime dependencies
+  spec.add_dependency "csv", ">= 3.0"
+  spec.add_dependency "pg", ">= 1.0"
+  spec.add_dependency "rails", ">= 6.1"
+
+  # Development dependencies
+  spec.add_development_dependency "database_cleaner-active_record", "~> 2.0"
+  spec.add_development_dependency "erb_lint", "~> 0.9"
+  spec.add_development_dependency "factory_bot_rails", "~> 6.0"
+  spec.add_development_dependency "rails-controller-testing", "~> 1.0"
+  spec.add_development_dependency "rspec", "~> 3.0"
+  spec.add_development_dependency "rspec-rails", "~> 6.0"
+  spec.add_development_dependency "rubocop", "~> 1.50"
+  spec.add_development_dependency "rubocop-rails", "~> 2.19"
+  spec.add_development_dependency "rubocop-rspec", "~> 2.20"
+  spec.add_development_dependency "simplecov", "~> 0.21"
+end