pg_sql_triggers 1.2.0 → 1.3.0

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.rb

@@ -1,59 +1,187 @@
 # 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
 
-    # Console APIs for trigger operations
-    # These methods provide a convenient interface for managing triggers from the Rails console
-
+    # 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)
+      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)
+      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)
@@ -65,7 +193,12 @@ module PgSqlTriggers
     def self.find_trigger!(trigger_name)
       PgSqlTriggers::TriggerRegistry.find_by!(trigger_name: trigger_name)
     rescue ActiveRecord::RecordNotFound
-      raise ArgumentError, "Trigger '#{trigger_name}' not found in registry"
+      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!
 

data/lib/pg_sql_triggers/sql/kill_switch.rb

@@ -143,14 +143,23 @@ module PgSqlTriggers
           expected = expected_confirmation(operation)
 
           if confirmation.nil? || confirmation.strip.empty?
-            raise PgSqlTriggers::KillSwitchError,
-                  "Confirmation text required. Expected: '#{expected}'"
+            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,
-                "Invalid confirmation text. Expected: '#{expected}', got: '#{confirmation.strip}'"
+          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
 
         private
@@ -291,7 +300,26 @@ module PgSqlTriggers
             Make sure you understand the implications before proceeding.
           ERROR
 
-          raise PgSqlTriggers::KillSwitchError, message
+          recovery = <<~RECOVERY
+            To override, provide the confirmation text: #{expected}
+
+            For CLI/rake tasks:
+              KILL_SWITCH_OVERRIDE=true CONFIRMATION_TEXT="#{expected}" rake your:task
+
+            For console operations:
+              PgSqlTriggers::SQL::KillSwitch.override(confirmation: "#{expected}") do
+                # your operation here
+              end
+
+            For UI operations, enter the confirmation text in the modal.
+          RECOVERY
+
+          raise PgSqlTriggers::KillSwitchError.new(
+            message,
+            error_code: "KILL_SWITCH_ACTIVE",
+            recovery_suggestion: recovery.strip,
+            context: { operation: operation, environment: environment, expected_confirmation: expected }
+          )
         end
       end
     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.3.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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: pg_sql_triggers
 version: !ruby/object:Gem::Version
-  version: 1.2.0
+  version: 1.3.0
 platform: ruby
 authors:
 - samaswin
@@ -9,6 +9,20 @@ bindir: exe
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: csv
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.0'
 - !ruby/object:Gem::Dependency
   name: pg
   requirement: !ruby/object:Gem::Requirement
@@ -196,17 +210,25 @@ files:
 - RELEASE.md
 - Rakefile
 - app/assets/javascripts/pg_sql_triggers/application.js
+- app/assets/javascripts/pg_sql_triggers/trigger_actions.js
 - app/assets/stylesheets/pg_sql_triggers/application.css
+- app/controllers/concerns/pg_sql_triggers/error_handling.rb
+- app/controllers/concerns/pg_sql_triggers/kill_switch_protection.rb
+- app/controllers/concerns/pg_sql_triggers/permission_checking.rb
 - app/controllers/pg_sql_triggers/application_controller.rb
+- app/controllers/pg_sql_triggers/audit_logs_controller.rb
 - app/controllers/pg_sql_triggers/dashboard_controller.rb
 - app/controllers/pg_sql_triggers/generator_controller.rb
 - app/controllers/pg_sql_triggers/migrations_controller.rb
 - app/controllers/pg_sql_triggers/sql_capsules_controller.rb
 - app/controllers/pg_sql_triggers/tables_controller.rb
 - app/controllers/pg_sql_triggers/triggers_controller.rb
+- app/helpers/pg_sql_triggers/permissions_helper.rb
 - app/models/pg_sql_triggers/application_record.rb
+- app/models/pg_sql_triggers/audit_log.rb
 - app/models/pg_sql_triggers/trigger_registry.rb
 - app/views/layouts/pg_sql_triggers/application.html.erb
+- app/views/pg_sql_triggers/audit_logs/index.html.erb
 - app/views/pg_sql_triggers/dashboard/index.html.erb
 - app/views/pg_sql_triggers/generator/new.html.erb
 - app/views/pg_sql_triggers/generator/preview.html.erb
@@ -223,16 +245,16 @@ files:
 - config/routes.rb
 - db/migrate/20251222000001_create_pg_sql_triggers_tables.rb
 - db/migrate/20251229071916_add_timing_to_pg_sql_triggers_registry.rb
+- db/migrate/20260103000001_create_pg_sql_triggers_audit_log.rb
 - docs/README.md
 - docs/api-reference.md
+- docs/audit-trail.md
 - docs/configuration.md
 - docs/getting-started.md
 - docs/kill-switch.md
-- docs/screenshots/.gitkeep
-- docs/screenshots/Generate Trigger.png
-- docs/screenshots/Triggers Page.png
-- docs/screenshots/kill error.png
-- docs/screenshots/kill modal for migration down.png
+- docs/permissions.md
+- docs/troubleshooting.md
+- docs/ui-guide.md
 - docs/usage-guide.md
 - docs/web-ui.md
 - lib/generators/pg_sql_triggers/install_generator.rb
@@ -251,6 +273,7 @@ files:
 - lib/pg_sql_triggers/dsl.rb
 - lib/pg_sql_triggers/dsl/trigger_definition.rb
 - lib/pg_sql_triggers/engine.rb
+- lib/pg_sql_triggers/errors.rb
 - lib/pg_sql_triggers/generator.rb
 - lib/pg_sql_triggers/generator/form.rb
 - lib/pg_sql_triggers/generator/service.rb

data/docs/screenshots/.gitkeep

@@ -1 +0,0 @@
-# This directory is for storing screenshot images referenced in the documentation.