agentcode 0.9.0

data/lib/agentcode/concerns/has_audit_trail.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+module AgentCode
+  # Automatic change logging concern.
+  # Mirrors the Laravel HasAuditTrail trait.
+  #
+  # Tracks: created, updated, deleted, force_deleted, restored
+  # Records: old/new values, user_id, organization_id, ip_address, user_agent
+  #
+  # Usage:
+  #   class Post < ApplicationRecord
+  #     include AgentCode::HasAuditTrail
+  #
+  #     # Optional: exclude sensitive fields from audit logging
+  #     agentcode_audit_exclude :password, :remember_token
+  #   end
+  module HasAuditTrail
+    extend ActiveSupport::Concern
+
+    included do
+      class_attribute :audit_exclude_fields, default: %w[password remember_token]
+
+      has_many :audit_logs, -> { order(created_at: :desc) },
+               as: :auditable,
+               class_name: "AgentCode::AuditLog",
+               dependent: :destroy
+
+      after_create :log_audit_created
+      after_update :log_audit_updated
+      after_destroy :log_audit_deleted
+
+      # For soft deletes restoration
+      if respond_to?(:after_undiscard)
+        after_undiscard :log_audit_restored
+      end
+    end
+
+    class_methods do
+      def agentcode_audit_exclude(*fields)
+        self.audit_exclude_fields = fields.map(&:to_s)
+      end
+    end
+
+    private
+
+    def log_audit_created
+      log_audit("created", nil, auditable_attributes)
+    end
+
+    def log_audit_updated
+      changes = saved_changes.except("updated_at")
+      return if changes.blank?
+
+      old_values = {}
+      new_values = {}
+
+      changes.each do |field, (old_val, new_val)|
+        next if audit_exclude_fields.include?(field)
+        old_values[field] = old_val
+        new_values[field] = new_val
+      end
+
+      return if new_values.blank?
+
+      log_audit("updated", old_values, new_values)
+    end
+
+    def log_audit_deleted
+      action = respond_to?(:discarded?) && discarded? ? "deleted" : "force_deleted"
+      log_audit(action, auditable_attributes, nil)
+    end
+
+    def log_audit_restored
+      log_audit("restored", nil, auditable_attributes)
+    end
+
+    def log_audit(action, old_values, new_values)
+      return unless audit_log_table_exists?
+
+      attributes = {
+        auditable: self,
+        action: action,
+        old_values: old_values,
+        new_values: new_values,
+        user_id: current_audit_user_id,
+        ip_address: current_audit_ip_address,
+        user_agent: current_audit_user_agent
+      }
+
+      # Add organization_id if available
+      org = current_audit_organization
+      attributes[:organization_id] = org.id if org
+
+      AgentCode::AuditLog.create!(attributes)
+    rescue StandardError => e
+      Rails.logger.warn("AgentCode::HasAuditTrail: Failed to log audit: #{e.message}")
+    end
+
+    def auditable_attributes
+      attributes.except(*audit_exclude_fields)
+    end
+
+    def current_audit_user_id
+      RequestStore.store[:agentcode_current_user]&.id if defined?(RequestStore)
+    end
+
+    def current_audit_ip_address
+      RequestStore.store[:agentcode_ip_address] if defined?(RequestStore)
+    end
+
+    def current_audit_user_agent
+      RequestStore.store[:agentcode_user_agent] if defined?(RequestStore)
+    end
+
+    def current_audit_organization
+      RequestStore.store[:agentcode_organization] if defined?(RequestStore)
+    end
+
+    def audit_log_table_exists?
+      @_audit_log_table_exists ||= ActiveRecord::Base.connection.table_exists?("audit_logs")
+    rescue StandardError
+      false
+    end
+  end
+end

data/lib/agentcode/concerns/has_auto_scope.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module AgentCode
+  # Auto-detect and apply global scopes by convention.
+  # Mirrors the Laravel HasAutoScope trait.
+  #
+  # Looks for a scope class at `Scopes::{ModelName}Scope`
+  # (e.g., `Scopes::PostScope` for `Post` model).
+  #
+  # The scope class can either:
+  #
+  # 1. Extend +AgentCode::ResourceScope+ (recommended) — provides access to
+  #    +user+, +organization+, and +role+ inside the +apply+ instance method:
+  #
+  #   module Scopes
+  #     class PostScope < AgentCode::ResourceScope
+  #       def apply(relation)
+  #         if role == "viewer"
+  #           relation.where(published: true)
+  #         else
+  #           relation
+  #         end
+  #       end
+  #     end
+  #   end
+  #
+  # 2. Implement +self.apply(relation)+ as a class method (legacy/simple):
+  #
+  #   module Scopes
+  #     class PostScope
+  #       def self.apply(relation)
+  #         relation.where(active: true)
+  #       end
+  #     end
+  #   end
+  #
+  module HasAutoScope
+    extend ActiveSupport::Concern
+
+    included do
+      default_scope lambda {
+        model = is_a?(ActiveRecord::Relation) ? self.klass : self
+        if model.respond_to?(:agentcode_auto_scope_class)
+          scope_class = model.agentcode_auto_scope_class
+          if scope_class
+            model.apply_agentcode_scope(scope_class, where(nil))
+          else
+            where(nil)
+          end
+        else
+          where(nil)
+        end
+      }
+    end
+
+    class_methods do
+      def agentcode_auto_scope_class
+        return @agentcode_auto_scope_class if instance_variable_defined?(:@agentcode_auto_scope_class)
+
+        result = find_auto_scope_class
+        # Only cache non-nil results to avoid permanently caching nil
+        # when the scope class hasn't been autoloaded yet (Zeitwerk)
+        @agentcode_auto_scope_class = result if result
+        result
+      end
+
+      # Apply the scope class to a relation.
+      # Supports both ResourceScope subclasses (instance method) and
+      # plain classes with self.apply (class method).
+      def apply_agentcode_scope(scope_class, relation)
+        if scope_class < AgentCode::ResourceScope
+          scope_class.new.apply(relation)
+        elsif scope_class.respond_to?(:apply)
+          scope_class.apply(relation)
+        else
+          relation
+        end
+      end
+
+      private
+
+      def find_auto_scope_class
+        return nil if name.nil?
+
+        model_name = name.demodulize
+        "Scopes::#{model_name}Scope".safe_constantize ||
+          "ModelScopes::#{model_name}Scope".safe_constantize
+      end
+    end
+  end
+end

data/lib/agentcode/concerns/has_permissions.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+module AgentCode
+  # Permission checking concern for the User model.
+  # Mirrors the Laravel HasPermissions trait.
+  #
+  # Usage:
+  #   class User < ApplicationRecord
+  #     include AgentCode::HasPermissions
+  #
+  #     has_many :user_roles
+  #   end
+  #
+  # Permission format: '{slug}.{action}' (e.g., 'posts.index', 'blogs.store')
+  # Wildcard support:
+  #   - '*' grants access to everything
+  #   - 'posts.*' grants access to all actions on posts
+  #
+  # Two permission sources:
+  #   - users.permissions: used for non-tenant route groups (no organization context).
+  #     Stored as a JSON array directly on the user model.
+  #   - role.permissions (via user_roles): used for tenant route groups (organization context present).
+  #     Resolved per-organization via the user_roles → role association.
+  #
+  # Resolution:
+  #   1. When an organization is provided (tenant route group) → checks role.permissions
+  #      for that specific organization via user_roles.
+  #   2. When no organization is provided (non-tenant route group) → checks users.permissions
+  #      directly on the user model.
+  module HasPermissions
+    extend ActiveSupport::Concern
+
+    # Check if the user has a specific permission.
+    #
+    # @param permission [String] Permission string like 'posts.index'
+    # @param organization [Object, nil] Organization to check permissions for
+    # @return [Boolean]
+    def has_permission?(permission, organization = nil)
+      return false if permission.blank?
+
+      if organization
+        # Tenant route group: check permissions for this organization
+        user_role = find_user_role(organization)
+
+        if user_role
+          # Check user_role.permissions first (per-user-org permissions on the pivot)
+          ur_permissions = parse_permissions(user_role.respond_to?(:permissions) ? user_role.permissions : nil)
+          if ur_permissions.present?
+            return matches_permission?(permission, ur_permissions)
+          end
+
+          # Fallback to role.permissions (shared role-level permissions)
+          role = user_role.respond_to?(:role) ? user_role.role : nil
+          if role
+            role_permissions = parse_permissions(role.respond_to?(:permissions) ? role.permissions : nil)
+            return matches_permission?(permission, role_permissions) if role_permissions.present?
+          end
+        end
+
+        return false
+      end
+
+      # Non-tenant route group: check users.permissions directly
+      user_perms = parse_permissions(respond_to?(:permissions) ? self.permissions : nil)
+      matches_permission?(permission, user_perms)
+    end
+
+    # Get the role slug for validation purposes.
+    #
+    # @param organization [Object, nil] Organization context
+    # @return [String, nil] Role slug or nil
+    def role_slug_for_validation(organization = nil)
+      user_role = find_user_role(organization)
+      return nil unless user_role
+
+      role = user_role.respond_to?(:role) ? user_role.role : nil
+      return nil unless role
+
+      role.respond_to?(:slug) ? role.slug : nil
+    end
+
+    private
+
+    def matches_permission?(permission, granted_permissions)
+      return true if granted_permissions.include?(permission)
+      return true if granted_permissions.include?("*")
+
+      resource = permission.split(".").first
+      return true if granted_permissions.include?("#{resource}.*")
+
+      false
+    end
+
+    def parse_permissions(perms)
+      return [] if perms.blank?
+
+      if perms.is_a?(String)
+        begin
+          JSON.parse(perms)
+        rescue JSON::ParserError
+          []
+        end
+      elsif perms.is_a?(Array)
+        perms
+      else
+        []
+      end
+    end
+
+    def find_user_role(organization)
+      return nil unless respond_to?(:user_roles)
+      return nil unless organization
+
+      user_roles.find_by(organization_id: organization.id)
+    end
+  end
+end

data/lib/agentcode/concerns/has_uuid.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module AgentCode
+  # Auto-generate UUID on model creation.
+  # Mirrors the Laravel HasUuid trait.
+  #
+  # Usage:
+  #   class Post < ApplicationRecord
+  #     include AgentCode::HasUuid
+  #   end
+  #
+  # Requires a `uuid` column in the migration.
+  module HasUuid
+    extend ActiveSupport::Concern
+
+    included do
+      before_create :generate_uuid
+    end
+
+    private
+
+    def generate_uuid
+      self.uuid ||= SecureRandom.uuid if respond_to?(:uuid=)
+    end
+  end
+end

data/lib/agentcode/concerns/has_validation.rb

@@ -0,0 +1,250 @@
+# frozen_string_literal: true
+
+module AgentCode
+  # Format validation concern for models.
+  #
+  # This concern runs ActiveModel validations on request data before
+  # it reaches the database. Field permissions (which fields each role
+  # can write) are controlled by the policy, not the model.
+  #
+  # Also provides cross-tenant FK validation: any belongs_to FK in the
+  # submitted data is checked to ensure the referenced record belongs
+  # to the current organization (directly or via FK chain).
+  #
+  # Usage:
+  #   class Post < ApplicationRecord
+  #     include AgentCode::HasValidation
+  #
+  #     # Standard Rails validations for type/format (use allow_nil: true)
+  #     validates :title, length: { maximum: 255 }, allow_nil: true
+  #     validates :status, inclusion: { in: %w[draft published] }, allow_nil: true
+  #   end
+  #
+  # Field permissions are defined on the policy:
+  #   class PostPolicy < AgentCode::ResourcePolicy
+  #     def permitted_attributes_for_create(user)
+  #       has_role?(user, 'admin') ? ['*'] : ['title', 'content']
+  #     end
+  #   end
+  module HasValidation
+    extend ActiveSupport::Concern
+
+    # Validate data for a given action.
+    # Filters to only permitted fields, then runs ActiveModel validations
+    # and cross-tenant FK validation.
+    #
+    # @param params [Hash] The request data
+    # @param permitted_fields [Array<String>] Fields the user is allowed to set (['*'] for all)
+    # @param organization [Object, nil] Current organization for FK scoping (optional)
+    # @return [Hash] { valid: Boolean, errors: Hash, validated: Hash }
+    def validate_for_action(params, permitted_fields:, organization: nil)
+      # Filter to only permitted fields
+      if permitted_fields == ['*']
+        filtered = params.each_with_object({}) { |(k, v), h| h[k.to_s] = v }
+      else
+        permitted = permitted_fields.map(&:to_s)
+        filtered = params.each_with_object({}) do |(k, v), h|
+          h[k.to_s] = v if permitted.include?(k.to_s)
+        end
+      end
+
+      # Remove organization_id from validated data — managed by framework
+      filtered.delete("organization_id") if organization
+
+      # Run ActiveModel validations on a temp instance
+      temp = self.class.new
+      safe_attrs = filtered.select { |k, _| temp.respond_to?("#{k}=") }
+      temp.assign_attributes(safe_attrs)
+
+      errors = {}
+      unless temp.valid?
+        temp.errors.each do |error|
+          field_name = error.attribute.to_s
+          if filtered.key?(field_name)
+            errors[field_name] ||= []
+            errors[field_name] << error.message
+          end
+        end
+      end
+
+      # Cross-tenant FK validation
+      if organization
+        fk_errors = validate_foreign_keys_for_organization(filtered, organization)
+        errors.merge!(fk_errors)
+      end
+
+      if errors.any?
+        { valid: false, errors: errors, validated: {} }
+      else
+        { valid: true, errors: {}, validated: filtered }
+      end
+    end
+
+    private
+
+    # Cache for FK chain lookups (class-level)
+    @@fk_chain_cache = {}
+    @@org_column_cache = {}
+
+    # Validate that all FK references in the data belong to the current organization.
+    # Walks belongs_to associations on the model, checks if the referenced table
+    # is org-scoped (directly or via FK chain), and verifies the record exists
+    # within the org's scope.
+    def validate_foreign_keys_for_organization(data, organization)
+      errors = {}
+      org_id = organization.id
+
+      self.class.reflect_on_all_associations(:belongs_to).each do |assoc|
+        fk_column = assoc.foreign_key.to_s
+        next unless data.key?(fk_column)
+        next if data[fk_column].nil?
+
+        # Skip organization_id itself
+        next if fk_column == "organization_id"
+
+        begin
+          related_class = assoc.klass
+          related_table = related_class.table_name
+        rescue StandardError
+          next
+        end
+
+        # Direct: related table has organization_id
+        if table_has_organization_id?(related_table)
+          unless related_class.where(
+            related_class.primary_key => data[fk_column],
+            organization_id: org_id
+          ).exists?
+            errors[fk_column] = ["does not belong to your organization"]
+          end
+          next
+        end
+
+        # Indirect: walk FK chain to find org-scoped ancestor
+        chain = find_organization_fk_chain(related_table)
+        next unless chain
+
+        unless record_belongs_to_organization?(related_table, related_class.primary_key, data[fk_column], org_id, chain)
+          errors[fk_column] = ["does not belong to your organization"]
+        end
+      end
+
+      errors
+    end
+
+    # Check if a table has an organization_id column.
+    def table_has_organization_id?(table)
+      unless @@org_column_cache.key?(table)
+        @@org_column_cache[table] = ActiveRecord::Base.connection.column_exists?(table, :organization_id)
+      end
+      @@org_column_cache[table]
+    end
+
+    # Find the FK chain from a table to an org-scoped ancestor.
+    # Returns array of steps or nil.
+    # Each step: { local_column:, foreign_table:, foreign_column: }
+    def find_organization_fk_chain(table)
+      return @@fk_chain_cache[table] if @@fk_chain_cache.key?(table)
+
+      chain = walk_fk_chain(table, 5, [])
+      @@fk_chain_cache[table] = chain
+      chain
+    end
+
+    def walk_fk_chain(table, max_depth, visited)
+      return nil if max_depth <= 0 || visited.include?(table)
+
+      visited = visited + [table]
+
+      begin
+        foreign_keys = ActiveRecord::Base.connection.foreign_keys(table)
+      rescue StandardError
+        return nil
+      end
+
+      foreign_keys.each do |fk|
+        local_column = fk.column
+        foreign_table = fk.to_table
+        foreign_column = fk.primary_key || "id"
+
+        if table_has_organization_id?(foreign_table)
+          return [{ local_column: local_column, foreign_table: foreign_table, foreign_column: foreign_column }]
+        end
+
+        deeper = walk_fk_chain(foreign_table, max_depth - 1, visited)
+        if deeper
+          deeper.unshift({ local_column: local_column, foreign_table: foreign_table, foreign_column: foreign_column })
+          return deeper
+        end
+      end
+
+      nil
+    end
+
+    # Check if a specific record belongs to the organization via FK chain.
+    # Builds a SQL EXISTS query with nested subqueries.
+    def record_belongs_to_organization?(table, pk_column, pk_value, org_id, chain)
+      # Build from innermost (org-scoped table) outward
+      # The chain goes: table → chain[0].foreign_table → chain[1].foreign_table → ... → org-scoped table
+      # We need to verify: record in `table` with pk_value → chain walks → org_id matches
+
+      query = build_chain_exists_query(table, pk_column, pk_value, org_id, chain, 0)
+      ActiveRecord::Base.connection.select_value(query).present?
+    end
+
+    def build_chain_exists_query(table, pk_column, pk_value, org_id, chain, index)
+      step = chain[index]
+
+      if index == chain.length - 1
+        # Last step: the foreign table has organization_id
+        sanitize_sql([
+          "SELECT 1 FROM #{quote_table(table)} " \
+          "WHERE #{quote_column(pk_column)} = ? " \
+          "AND #{quote_column(step[:local_column])} IN (" \
+          "SELECT #{quote_column(step[:foreign_column])} FROM #{quote_table(step[:foreign_table])} " \
+          "WHERE organization_id = ?)",
+          pk_value, org_id
+        ])
+      else
+        # Intermediate step: recurse deeper
+        inner = build_inner_chain_query(step[:foreign_table], step[:foreign_column], org_id, chain, index + 1)
+        sanitize_sql([
+          "SELECT 1 FROM #{quote_table(table)} " \
+          "WHERE #{quote_column(pk_column)} = ? " \
+          "AND #{quote_column(step[:local_column])} IN (#{inner})",
+          pk_value
+        ])
+      end
+    end
+
+    def build_inner_chain_query(table, pk_column, org_id, chain, index)
+      step = chain[index]
+
+      if index == chain.length - 1
+        sanitize_sql([
+          "SELECT #{quote_column(pk_column)} FROM #{quote_table(table)} " \
+          "WHERE #{quote_column(step[:local_column])} IN (" \
+          "SELECT #{quote_column(step[:foreign_column])} FROM #{quote_table(step[:foreign_table])} " \
+          "WHERE organization_id = ?)",
+          org_id
+        ])
+      else
+        inner = build_inner_chain_query(step[:foreign_table], step[:foreign_column], org_id, chain, index + 1)
+        "SELECT #{quote_column(pk_column)} FROM #{quote_table(table)} " \
+        "WHERE #{quote_column(step[:local_column])} IN (#{inner})"
+      end
+    end
+
+    def sanitize_sql(args)
+      ActiveRecord::Base.send(:sanitize_sql_array, args)
+    end
+
+    def quote_table(name)
+      ActiveRecord::Base.connection.quote_table_name(name)
+    end
+
+    def quote_column(name)
+      ActiveRecord::Base.connection.quote_column_name(name)
+    end
+  end
+end