agentcode 0.9.0

data/lib/agentcode/policies/resource_policy.rb

@@ -0,0 +1,197 @@
+# frozen_string_literal: true
+
+module AgentCode
+  # Base policy for all AgentCode resources.
+  # Mirrors the Laravel ResourcePolicy exactly.
+  #
+  # Permission format: '{slug}.{action}' (e.g., 'posts.index', 'blogs.store')
+  # Supports wildcards:
+  #   - '*' grants access to everything
+  #   - 'posts.*' grants access to all actions on posts
+  #
+  # Usage:
+  #   class PostPolicy < AgentCode::ResourcePolicy
+  #     # Override for custom logic:
+  #     def update?(user, record)
+  #       super && record.user_id == user.id
+  #     end
+  #
+  #     # Attribute permissions:
+  #     def permitted_attributes_for_show(user)
+  #       has_role?(user, 'admin') ? ['*'] : ['id', 'title']
+  #     end
+  #
+  #     def hidden_attributes_for_show(user)
+  #       has_role?(user, 'admin') ? [] : ['internal_notes']
+  #     end
+  #
+  #     def permitted_attributes_for_create(user)
+  #       has_role?(user, 'admin') ? ['*'] : ['title', 'content']
+  #     end
+  #
+  #     def permitted_attributes_for_update(user)
+  #       has_role?(user, 'admin') ? ['*'] : ['title', 'content']
+  #     end
+  #   end
+  class ResourcePolicy
+    attr_reader :user, :record
+
+    def initialize(user, record)
+      @user = user
+      @record = record
+    end
+
+    # The resource slug used for permission checks.
+    # Override in child policies, or it will be auto-resolved from config.
+    def self.resource_slug
+      @resource_slug
+    end
+
+    def self.resource_slug=(slug)
+      @resource_slug = slug
+    end
+
+    # ------------------------------------------------------------------
+    # Convention-based CRUD authorization
+    # ------------------------------------------------------------------
+
+    def index?
+      check_permission("index")
+    end
+
+    alias_method :view_any?, :index?
+
+    def show?
+      check_permission("show")
+    end
+
+    alias_method :view?, :show?
+
+    def create?
+      check_permission("store")
+    end
+
+    def update?
+      check_permission("update")
+    end
+
+    def destroy?
+      check_permission("destroy")
+    end
+
+    alias_method :delete?, :destroy?
+
+    # ------------------------------------------------------------------
+    # Soft Delete authorization
+    # ------------------------------------------------------------------
+
+    def view_trashed?
+      check_permission("trashed")
+    end
+
+    def restore?
+      check_permission("restore")
+    end
+
+    def force_delete?
+      check_permission("forceDelete")
+    end
+
+    # ------------------------------------------------------------------
+    # Attribute Permissions
+    # ------------------------------------------------------------------
+
+    # Override to whitelist which columns are visible in API responses.
+    # Return ['*'] to allow all columns (default).
+    #
+    # @param user [Object, nil] The authenticated user
+    # @return [Array<String>]
+    def permitted_attributes_for_show(user)
+      ['*']
+    end
+
+    # Override to blacklist columns from API responses.
+    # These are always hidden, even if listed in permitted_attributes_for_show.
+    #
+    # @param user [Object, nil] The authenticated user
+    # @return [Array<String>]
+    def hidden_attributes_for_show(user)
+      []
+    end
+
+    # Override to whitelist which fields a user can submit on create.
+    # Return ['*'] to allow all fields (default).
+    #
+    # @param user [Object, nil] The authenticated user
+    # @return [Array<String>]
+    def permitted_attributes_for_create(user)
+      ['*']
+    end
+
+    # Override to whitelist which fields a user can submit on update.
+    # Return ['*'] to allow all fields (default).
+    #
+    # @param user [Object, nil] The authenticated user
+    # @return [Array<String>]
+    def permitted_attributes_for_update(user)
+      ['*']
+    end
+
+    # ------------------------------------------------------------------
+    # Helpers
+    # ------------------------------------------------------------------
+
+    # Check if the user has a specific role in the current organization.
+    # Convenience method for use in child policies.
+    #
+    # @param user [Object, nil] The authenticated user
+    # @param role_slug [String, Symbol] Role slug (e.g. 'admin', 'editor')
+    # @return [Boolean]
+    def has_role?(user, role_slug)
+      return false unless user
+      return false unless user.respond_to?(:role_slug_for_validation)
+
+      organization = current_organization
+      user.role_slug_for_validation(organization) == role_slug.to_s
+    end
+
+    private
+
+    # Check if the user has the given permission for this resource.
+    def check_permission(action)
+      return false unless user
+
+      slug = resolve_resource_slug
+      return false unless slug
+
+      permission = "#{slug}.#{action}"
+
+      if user.respond_to?(:has_permission?)
+        organization = current_organization
+        user.has_permission?(permission, organization)
+      else
+        # Fallback: if the user model doesn't implement has_permission?, allow
+        true
+      end
+    end
+
+    def resolve_resource_slug
+      # 1. Explicit resource_slug on the policy class
+      return self.class.resource_slug if self.class.resource_slug
+
+      # 2. Auto-resolve from AgentCode config
+      model_class = record.is_a?(Class) ? record : record.class
+      slug = AgentCode.config.slug_for(model_class)
+
+      # Cache for subsequent calls
+      self.class.resource_slug = slug if slug
+      slug
+    end
+
+    def current_organization
+      if defined?(RequestStore)
+        RequestStore.store[:agentcode_organization]
+      end
+    end
+  end
+end

data/lib/agentcode/query_builder.rb

@@ -0,0 +1,278 @@
+# frozen_string_literal: true
+
+module AgentCode
+  # Custom query builder that provides AgentCode's exact URL parameter format.
+  # Replaces Spatie QueryBuilder for Rails.
+  #
+  # Supports:
+  #   - Filtering:    ?filter[status]=published&filter[user_id]=1
+  #   - Sorting:      ?sort=-created_at,title
+  #   - Search:       ?search=term
+  #   - Pagination:   ?page=1&per_page=20
+  #   - Fields:       ?fields[posts]=id,title,status
+  #   - Includes:     ?include=user,comments
+  class QueryBuilder
+    attr_reader :scope, :model_class, :params
+
+    def initialize(model_class, params: {})
+      @model_class = model_class
+      @scope = model_class.all
+      @params = params
+    end
+
+    # Apply all query modifications based on params and model config.
+    def build
+      apply_filters
+      apply_default_sort
+      apply_sorts
+      apply_search
+      apply_fields
+      apply_includes
+      self
+    end
+
+    # Get the final ActiveRecord relation.
+    def to_scope
+      @scope
+    end
+
+    # Execute with pagination. Returns { items:, pagination: }.
+    def paginate(per_page: nil, page: nil)
+      per_page = (per_page || params[:per_page] || model_class.try(:agentcode_per_page_count) || 25).to_i
+      per_page = [[per_page, 1].max, 100].min # clamp between 1 and 100
+      page = (page || params[:page] || 1).to_i
+      page = [page, 1].max
+
+      total = @scope.count
+      last_page = (total.to_f / per_page).ceil
+      last_page = [last_page, 1].max
+
+      items = @scope.offset((page - 1) * per_page).limit(per_page)
+
+      {
+        items: items,
+        pagination: {
+          current_page: page,
+          last_page: last_page,
+          per_page: per_page,
+          total: total
+        }
+      }
+    end
+
+    private
+
+    # ------------------------------------------------------------------
+    # Filtering: ?filter[status]=published&filter[user_id]=1
+    # ------------------------------------------------------------------
+
+    def apply_filters
+      filter_params = params[:filter]
+      return unless filter_params.is_a?(ActionController::Parameters) || filter_params.is_a?(Hash)
+
+      allowed = model_class.try(:allowed_filters) || []
+      return if allowed.empty? && filter_params.present?
+
+      filter_params.each do |key, value|
+        key = key.to_s
+        next unless allowed.include?(key)
+
+        if value.to_s.include?(",")
+          # Multiple values: OR condition
+          values = value.to_s.split(",").map(&:strip)
+          values = coerce_filter_values(key, values)
+          @scope = @scope.where(key => values)
+        else
+          @scope = @scope.where(key => coerce_filter_value(key, value))
+        end
+      end
+    end
+
+    # ------------------------------------------------------------------
+    # Sorting: ?sort=-created_at,title
+    # ------------------------------------------------------------------
+
+    def apply_default_sort
+      return if params[:sort].present?
+
+      default = model_class.try(:default_sort_field)
+      return unless default
+
+      apply_sort_string(default)
+    end
+
+    def apply_sorts
+      sort_param = params[:sort]
+      return unless sort_param.present?
+
+      apply_sort_string(sort_param.to_s)
+    end
+
+    def apply_sort_string(sort_string)
+      allowed = model_class.try(:allowed_sorts) || []
+
+      sort_string.split(",").each do |field|
+        field = field.strip
+        if field.start_with?("-")
+          column = field[1..]
+          direction = :desc
+        else
+          column = field
+          direction = :asc
+        end
+
+        next unless allowed.empty? || allowed.include?(column)
+
+        @scope = @scope.order(column => direction)
+      end
+    end
+
+    # ------------------------------------------------------------------
+    # Search: ?search=term
+    # ------------------------------------------------------------------
+
+    def apply_search
+      search_term = params[:search]
+      return unless search_term.present?
+
+      columns = model_class.try(:allowed_search) || []
+      return if columns.empty?
+
+      term = "%#{search_term.to_s.downcase}%"
+      conditions = []
+      values = []
+
+      columns.each do |column|
+        if column.include?(".")
+          # Relationship search: 'user.name' -> joins(:user).where("users.name ILIKE ?", term)
+          parts = column.split(".", 2)
+          relation = parts[0]
+          field = parts[1]
+
+          # Determine the table name from the association
+          assoc = model_class.reflect_on_association(relation.to_sym)
+          if assoc
+            begin
+              table_name = assoc.klass.table_name
+              @scope = @scope.left_outer_joins(relation.to_sym)
+              conditions << "LOWER(#{table_name}.#{field}) LIKE ?"
+              values << term
+            rescue NoMethodError, NameError
+              next
+            end
+          end
+        else
+          conditions << "LOWER(#{model_class.table_name}.#{column}) LIKE ?"
+          values << term
+        end
+      end
+
+      return if conditions.empty?
+
+      @scope = @scope.where(conditions.join(" OR "), *values)
+    end
+
+    # ------------------------------------------------------------------
+    # Sparse fieldsets: ?fields[posts]=id,title,status
+    # ------------------------------------------------------------------
+
+    def apply_fields
+      fields_params = params[:fields]
+      return unless fields_params.is_a?(ActionController::Parameters) || fields_params.is_a?(Hash)
+
+      allowed = model_class.try(:allowed_fields) || []
+      return if allowed.empty?
+
+      # Find fields for this model's table
+      slug = AgentCode.config.slug_for(model_class)
+      model_fields = fields_params[slug.to_s] || fields_params[model_class.table_name]
+      return unless model_fields
+
+      requested = model_fields.to_s.split(",").map(&:strip)
+      # Only allow fields that are in the allowed list
+      valid_fields = requested.select { |f| allowed.include?(f) }
+
+      if valid_fields.any?
+        # Always include the primary key
+        valid_fields.unshift(model_class.primary_key) unless valid_fields.include?(model_class.primary_key)
+        @scope = @scope.select(valid_fields.map { |f| "#{model_class.table_name}.#{f}" })
+      end
+    end
+
+    # ------------------------------------------------------------------
+    # Eager loading: ?include=user,comments
+    # ------------------------------------------------------------------
+
+    def apply_includes
+      include_param = params[:include]
+      return unless include_param.present?
+
+      allowed = model_class.try(:allowed_includes) || []
+      return if allowed.empty?
+
+      requested = include_param.to_s.split(",").map(&:strip)
+
+      includes_list = []
+      requested.each do |inc|
+        base = resolve_base_include(inc, allowed)
+        next unless base
+
+        if inc.include?(".")
+          # Nested include: 'comments.user' -> { comments: :user }
+          parts = inc.split(".")
+          nested = parts.reverse.inject { |inner, outer| { outer.to_sym => inner.to_sym } }
+          includes_list << nested
+        elsif inc.end_with?("Count") || inc.end_with?("Exists")
+          # Count/Exists suffixes are handled separately in serialization
+          next
+        else
+          includes_list << inc.to_sym
+        end
+      end
+
+      @scope = @scope.includes(*includes_list) if includes_list.any?
+    end
+
+    # Coerce a single filter value to the column's type (e.g. string → integer).
+    def coerce_filter_value(column, value)
+      col = model_class.columns_hash[column]
+      return value unless col
+
+      case col.type
+      when :integer, :bigint
+        value.to_s.match?(/\A-?\d+\z/) ? value.to_i : value
+      when :float, :decimal
+        value.to_s.match?(/\A-?\d+(\.\d+)?\z/) ? value.to_f : value
+      when :boolean
+        ActiveModel::Type::Boolean.new.cast(value)
+      else
+        value
+      end
+    end
+
+    # Coerce an array of filter values.
+    def coerce_filter_values(column, values)
+      values.map { |v| coerce_filter_value(column, v) }
+    end
+
+    # Resolve an include segment to the base relationship name.
+    # Handles Count/Exists suffixes.
+    def resolve_base_include(segment, allowed)
+      return segment if allowed.include?(segment)
+
+      # Check Count suffix
+      if segment.end_with?("Count")
+        base = segment.sub(/Count\z/, "")
+        return base if allowed.include?(base)
+      end
+
+      # Check Exists suffix
+      if segment.end_with?("Exists")
+        base = segment.sub(/Exists\z/, "")
+        return base if allowed.include?(base)
+      end
+
+      nil
+    end
+  end
+end

data/lib/agentcode/railtie.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module AgentCode
+  class Railtie < ::Rails::Railtie
+    railtie_name :agentcode
+
+    rake_tasks do
+      load File.expand_path("tasks/agentcode.rake", __dir__)
+    end
+  end
+end

data/lib/agentcode/resource_scope.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module AgentCode
+  # Base class for auto-discovered model scopes.
+  #
+  # Provides access to the current user and organization from RequestStore,
+  # so scopes can implement role-based or user-specific filtering.
+  #
+  # Usage:
+  #   # app/models/scopes/project_scope.rb
+  #   module Scopes
+  #     class ProjectScope < AgentCode::ResourceScope
+  #       def apply(relation)
+  #         if role == "viewer"
+  #           relation.where(status: "active")
+  #         else
+  #           relation
+  #         end
+  #       end
+  #     end
+  #   end
+  #
+  # Available methods inside +apply+:
+  #   - +user+          — the current authenticated user (or nil)
+  #   - +organization+  — the current organization (or nil)
+  #   - +role+          — shortcut for the user's role slug in the current org (or nil)
+  #
+  class ResourceScope
+    # The current authenticated user, if any.
+    # @return [User, nil]
+    def user
+      RequestStore.store[:agentcode_current_user] if defined?(RequestStore)
+    end
+
+    # The current organization, if any.
+    # @return [Organization, nil]
+    def organization
+      RequestStore.store[:agentcode_organization] if defined?(RequestStore)
+    end
+
+    # Shortcut: the user's role slug in the current organization.
+    # @return [String, nil]
+    def role
+      return nil unless user && organization
+
+      if user.respond_to?(:role_slug_for_validation)
+        user.role_slug_for_validation(organization)
+      end
+    end
+
+    # Subclasses must implement this method.
+    #
+    # @param relation [ActiveRecord::Relation] the current query scope
+    # @return [ActiveRecord::Relation] the modified scope
+    def apply(relation)
+      raise NotImplementedError, "#{self.class.name} must implement #apply(relation)"
+    end
+  end
+end

data/lib/agentcode/routes.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+module AgentCode
+  # Dynamic route registration from AgentCode configuration.
+  # Mirrors the Laravel routes/api.php behavior exactly.
+  module Routes
+    class << self
+      def draw(router)
+        config = AgentCode.config
+        route_groups = config.route_groups
+
+        # Sort: literal prefixes first, parameterized (containing ':') last
+        sorted_groups = route_groups.sort_by { |_name, cfg| cfg[:prefix].include?(":") ? 1 : 0 }
+
+        router.instance_eval do
+          scope path: "api", defaults: { format: :json } do
+            # ---------------------------------------------------------------
+            # Auth Routes (always registered)
+            # ---------------------------------------------------------------
+            scope path: "auth" do
+              post "login", to: "agentcode/auth#login"
+              post "password/recover", to: "agentcode/auth#recover_password"
+              post "password/reset", to: "agentcode/auth#reset"
+              post "register", to: "agentcode/auth#register_with_invitation"
+              post "logout", to: "agentcode/auth#logout"
+            end
+
+            # ---------------------------------------------------------------
+            # Invitation accept (public, always registered)
+            # ---------------------------------------------------------------
+            post "invitations/accept", to: "agentcode/invitations#accept"
+
+            # ---------------------------------------------------------------
+            # Tenant-specific routes (invitations + nested)
+            # ---------------------------------------------------------------
+            if config.has_tenant_group?
+              tenant_config = route_groups[:tenant]
+              tenant_prefix = tenant_config[:prefix]
+
+              # Invitation routes under tenant prefix
+              invitation_prefix = tenant_prefix.present? ? "#{tenant_prefix}/invitations" : "invitations"
+
+              scope path: invitation_prefix do
+                get "/", to: "agentcode/invitations#index"
+                post "/", to: "agentcode/invitations#create"
+                post ":id/resend", to: "agentcode/invitations#resend"
+                delete ":id", to: "agentcode/invitations#cancel"
+              end
+
+              # Nested operations under tenant prefix
+              nested_config = config.nested
+              nested_path = nested_config[:path] || "nested"
+              nested_prefix = tenant_prefix.present? ? "#{tenant_prefix}/#{nested_path}" : nested_path
+
+              post nested_prefix, to: "agentcode/resources#nested", as: :agentcode_nested
+            else
+              # No tenant group — register nested at top level
+              nested_config = config.nested
+              nested_path = nested_config[:path] || "nested"
+              post nested_path, to: "agentcode/resources#nested", as: :agentcode_nested
+            end
+
+            # ---------------------------------------------------------------
+            # Per-group CRUD routes
+            # ---------------------------------------------------------------
+            sorted_groups.each do |group_name, group_config|
+              group_prefix = group_config[:prefix]
+              group_models = config.models_for_group(group_name)
+
+              group_models.each do |slug|
+                model_class_name = config.models[slug]
+                model_class = begin
+                  model_class_name.constantize
+                rescue NameError
+                  next
+                end
+
+                except_actions = model_class.try(:agentcode_except_actions_list) || []
+
+                route_prefix = [group_prefix, slug.to_s].reject(&:blank?).join("/")
+
+                scope path: route_prefix, defaults: { model_slug: slug.to_s, route_group: group_name.to_s } do
+                  unless except_actions.include?("index")
+                    get "/", to: "agentcode/resources#index", as: "agentcode_#{group_name}_#{slug}_index"
+                  end
+
+                  unless except_actions.include?("store")
+                    post "/", to: "agentcode/resources#store", as: "agentcode_#{group_name}_#{slug}_store"
+                  end
+
+                  if model_class.try(:uses_soft_deletes?)
+                    unless except_actions.include?("trashed")
+                      get "trashed", to: "agentcode/resources#trashed", as: "agentcode_#{group_name}_#{slug}_trashed"
+                    end
+
+                    unless except_actions.include?("restore")
+                      post ":id/restore", to: "agentcode/resources#restore", as: "agentcode_#{group_name}_#{slug}_restore"
+                    end
+
+                    unless except_actions.include?("forceDelete")
+                      delete ":id/force-delete", to: "agentcode/resources#force_delete", as: "agentcode_#{group_name}_#{slug}_force_delete"
+                    end
+                  end
+
+                  unless except_actions.include?("show")
+                    get ":id", to: "agentcode/resources#show", as: "agentcode_#{group_name}_#{slug}_show"
+                  end
+
+                  unless except_actions.include?("update")
+                    put ":id", to: "agentcode/resources#update", as: "agentcode_#{group_name}_#{slug}_update"
+                  end
+
+                  unless except_actions.include?("destroy")
+                    delete ":id", to: "agentcode/resources#destroy", as: "agentcode_#{group_name}_#{slug}_destroy"
+                  end
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end