agentcode 0.9.0

data/lib/agentcode/engine.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require "pundit"
+require "pagy"
+require "discard"
+
+module AgentCode
+  class Engine < ::Rails::Engine
+    isolate_namespace AgentCode
+
+    rake_tasks do
+      load File.expand_path("tasks/agentcode.rake", __dir__)
+    end
+
+    initializer "agentcode.autoloads" do
+      # Concerns
+      require "agentcode/concerns/has_agentcode"
+      require "agentcode/concerns/has_validation"
+      require "agentcode/concerns/has_permissions"
+      require "agentcode/concerns/has_audit_trail"
+      require "agentcode/concerns/belongs_to_organization"
+      require "agentcode/concerns/hidable_columns"
+      require "agentcode/concerns/has_uuid"
+      require "agentcode/concerns/has_auto_scope"
+
+      # Policies
+      require "agentcode/policies/resource_policy"
+      require "agentcode/policies/invitation_policy"
+
+      # Query builder and routes
+      require "agentcode/query_builder"
+      require "agentcode/routes"
+
+      # Controllers
+      require "agentcode/controllers/resources_controller"
+      require "agentcode/controllers/auth_controller"
+      require "agentcode/controllers/invitations_controller"
+
+      # Mailers (only if ActionMailer is available)
+      require "agentcode/mailers/invitation_mailer" if defined?(ActionMailer)
+    end
+
+    # Models that inherit from ApplicationRecord must be loaded after
+    # the app has initialized (so ApplicationRecord is defined)
+    initializer "agentcode.models", after: :load_active_record do
+      config.after_initialize do
+        require "agentcode/models/agentcode_model"
+        require "agentcode/models/audit_log"
+        require "agentcode/models/organization_invitation"
+      end
+    end
+
+    initializer "agentcode.routes", after: :load_config_initializers do |app|
+      app.routes.append do
+        AgentCode::Routes.draw(self)
+      end
+    end
+
+    initializer "agentcode.pundit" do
+      ActiveSupport.on_load(:action_controller) do
+        include Pundit::Authorization if defined?(Pundit)
+      end
+    end
+  end
+end

data/lib/agentcode/mailers/invitation_mailer.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module AgentCode
+  # ActionMailer for invitation emails — mirrors Laravel InvitationNotification.
+  class InvitationMailer < ActionMailer::Base
+    def invite(invitation)
+      @invitation = invitation
+      @organization = invitation.organization
+      @role = invitation.role
+      @invited_by = invitation.inviter
+
+      frontend_url = ENV.fetch("FRONTEND_URL", "http://localhost:5173")
+      @url = "#{frontend_url}/accept-invitation?token=#{invitation.token}"
+      @expires_at = invitation.expires_at
+
+      mail(
+        to: invitation.email,
+        subject: "You've been invited to join #{@organization&.name}"
+      )
+    end
+  end
+end

data/lib/agentcode/middleware/resolve_organization_from_route.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module AgentCode
+  module Middleware
+    # Rack middleware that extracts the organization from the route parameter.
+    # Mirrors the Laravel ResolveOrganizationFromRoute middleware.
+    #
+    # For route-prefix multi-tenancy: /api/{organization}/posts
+    class ResolveOrganizationFromRoute
+      def initialize(app)
+        @app = app
+      end
+
+      def call(env)
+        request = ActionDispatch::Request.new(env)
+
+        # Extract organization identifier from route params
+        org_identifier = request.path_parameters[:organization]
+
+        if org_identifier.present?
+          organization = find_organization(org_identifier)
+
+          unless organization
+            return [404, { "Content-Type" => "application/json" }, ['{"message":"Organization not found"}']]
+          end
+
+          # Check if authenticated user belongs to this organization
+          user = resolve_user(request)
+          if user && !user_belongs_to_organization?(user, organization)
+            return [404, { "Content-Type" => "application/json" }, ['{"message":"Organization not found"}']]
+          end
+
+          env["agentcode.organization"] = organization
+
+          if defined?(RequestStore)
+            RequestStore.store[:agentcode_organization] = organization
+          end
+        end
+
+        @app.call(env)
+      end
+
+      private
+
+      def find_organization(identifier)
+        org_class = "Organization".safe_constantize
+        return nil unless org_class
+
+        column = AgentCode.config.multi_tenant[:organization_identifier_column] || "id"
+        org_class.find_by(column => identifier)
+      end
+
+      def resolve_user(request)
+        token = request.headers["Authorization"]&.sub(/\ABearer /, "")
+        return nil unless token
+
+        user_class = "User".safe_constantize
+        return nil unless user_class
+
+        if user_class.column_names.include?("api_token")
+          user_class.find_by(api_token: token)
+        end
+      end
+
+      def user_belongs_to_organization?(user, organization)
+        return true unless user.respond_to?(:user_roles)
+
+        user.user_roles.exists?(organization_id: organization.id)
+      end
+    end
+  end
+end

data/lib/agentcode/models/agentcode_model.rb

@@ -0,0 +1,387 @@
+# frozen_string_literal: true
+
+module AgentCode
+  # AgentCodeModel -- Pre-composed base class for AgentCode-powered ActiveRecord models.
+  #
+  # Extends +ApplicationRecord+ and includes the most commonly needed concerns
+  # for AgentCode's automatic REST API generation. Subclass this instead of
+  # +ApplicationRecord+ to get query building, validation, column hiding,
+  # and auto-scopes out of the box.
+  #
+  # == Quick Start
+  #
+  #   class Post < AgentCode::AgentCodeModel
+  #     agentcode_filters :status, :user_id
+  #     agentcode_sorts :created_at, :title
+  #     agentcode_default_sort '-created_at'
+  #     agentcode_includes :user, :comments
+  #     agentcode_search :title, :content
+  #
+  #     # Standard Rails validations for type/format (NOT presence — use allow_nil: true)
+  #     validates :title, length: { maximum: 255 }, allow_nil: true
+  #     validates :status, inclusion: { in: %w[draft published] }, allow_nil: true
+  #
+  #     # Field permissions are controlled by the policy (PostPolicy).
+  #     # See: permitted_attributes_for_create / permitted_attributes_for_update
+  #
+  #     belongs_to :user
+  #     has_many :comments
+  #   end
+  #
+  # == Included Concerns
+  #
+  #   Concern           | Purpose
+  #   ------------------|-----------------------------------------------------------
+  #   HasAgentCode         | Query builder DSL (filters, sorts, includes, etc.)
+  #   HasValidation     | Format validation for request data
+  #   HidableColumns    | Dynamic column hiding from API responses
+  #   HasAutoScope      | Auto-discovery of ModelScopes::{Model}Scope classes
+  #
+  # == Optional Concerns (add manually when needed)
+  #
+  # These concerns are NOT included in AgentCodeModel because they require
+  # additional database columns, gems, or relationships. Include them in
+  # your model subclass as needed:
+  #
+  #   Concern                     | Purpose
+  #   ----------------------------|---------------------------------------------------
+  #   AgentCode::HasAuditTrail       | Automatic change logging to +audit_logs+ table
+  #   AgentCode::HasUuid             | Auto-generated UUID on creation
+  #   AgentCode::BelongsToOrganization | Multi-tenant organization scoping
+  #   AgentCode::HasPermissions      | Permission checking (User model only)
+  #   Discard::Model              | Soft deletes via the Discard gem
+  #
+  #   class Invoice < AgentCode::AgentCodeModel
+  #     include AgentCode::HasAuditTrail
+  #     include AgentCode::BelongsToOrganization
+  #     include Discard::Model
+  #
+  #     agentcode_filters :status, :client_id
+  #     agentcode_sorts :created_at, :amount
+  #
+  #     validates :amount, numericality: { greater_than_or_equal_to: 0 }, allow_nil: true
+  #     validates :client_id, numericality: { only_integer: true }, allow_nil: true
+  #
+  #   end
+  #
+  # @see AgentCode::HasAgentCode       Query builder configuration
+  # @see AgentCode::HasValidation   Format validation
+  # @see AgentCode::HidableColumns  Column visibility control
+  # @see AgentCode::HasAutoScope    Automatic scope discovery
+  #
+  class AgentCodeModel < ::ApplicationRecord
+    self.abstract_class = true
+
+    include AgentCode::HasAgentCode
+    include AgentCode::HasValidation
+    include AgentCode::HidableColumns
+    include AgentCode::HasAutoScope
+
+    # =========================================================================
+    # QUERY BUILDER -- Filtering, Sorting, Search, Includes, Fields
+    # =========================================================================
+    # Provided by: AgentCode::HasAgentCode
+    #
+    # All class_attributes below are set via DSL methods. You can also
+    # override them directly using +self.attribute_name = value+ in the
+    # class body if you prefer a declarative style.
+    # =========================================================================
+
+    # @!attribute [rw] allowed_filters
+    #   Filterable columns.
+    #
+    #   Controls which fields can be filtered via +?filter[field]=value+.
+    #   Only whitelisted fields are accepted -- unlisted fields are silently ignored.
+    #
+    #   Set via DSL: +agentcode_filters :status, :user_id, :category_id+
+    #
+    #   Query: +GET /api/posts?filter[status]=published&filter[user_id]=5+
+    #
+    #   @return [Array<String>]
+    #   @example
+    #     agentcode_filters :status, :user_id, :category_id, :is_published
+    #   @example Direct assignment
+    #     self.allowed_filters = %w[status user_id category_id]
+    self.allowed_filters = []
+
+    # @!attribute [rw] allowed_sorts
+    #   Sortable columns.
+    #
+    #   Controls which fields can be used for sorting via +?sort=field+.
+    #   Prefix with +-+ for descending order.
+    #
+    #   Set via DSL: +agentcode_sorts :created_at, :title, :status+
+    #
+    #   Query: +GET /api/posts?sort=-created_at+ or +GET /api/posts?sort=title+
+    #
+    #   @return [Array<String>]
+    #   @example
+    #     agentcode_sorts :created_at, :title, :status, :updated_at
+    self.allowed_sorts = []
+
+    # @!attribute [rw] default_sort_field
+    #   Default sort expression applied when no explicit +?sort+ is given.
+    #   Prefix with +-+ for descending. Set to +nil+ for database insertion order.
+    #
+    #   Set via DSL: +agentcode_default_sort '-created_at'+
+    #
+    #   @return [String, nil]
+    #   @example
+    #     agentcode_default_sort '-created_at'   # newest first
+    #     agentcode_default_sort 'title'          # alphabetical ascending
+    self.default_sort_field = nil
+
+    # @!attribute [rw] allowed_fields
+    #   Selectable columns (sparse fieldsets).
+    #
+    #   Controls which columns can be selected via +?fields[model]=field1,field2+.
+    #   Limits the payload size by returning only requested columns.
+    #
+    #   Set via DSL: +agentcode_fields :id, :title, :status, :created_at+
+    #
+    #   Query: +GET /api/posts?fields[posts]=id,title,status+
+    #
+    #   @return [Array<String>]
+    #   @example
+    #     agentcode_fields :id, :title, :status, :created_at, :user_id
+    self.allowed_fields = []
+
+    # @!attribute [rw] allowed_includes
+    #   Eager-loadable relationships.
+    #
+    #   Controls which relationships can be included via +?include=relation+.
+    #   Must correspond to defined ActiveRecord associations on the model.
+    #   Supports nested includes: +'comments.user'+.
+    #
+    #   Set via DSL: +agentcode_includes :user, :comments, :tags+
+    #
+    #   Query: +GET /api/posts?include=user,comments+
+    #
+    #   @return [Array<String>]
+    #   @example
+    #     agentcode_includes :user, :comments, :tags, 'comments.user'
+    self.allowed_includes = []
+
+    # @!attribute [rw] allowed_search
+    #   Searchable columns (full-text search across multiple fields).
+    #
+    #   When +?search=term+ is used, AgentCode performs a case-insensitive LIKE
+    #   search across all listed fields. Supports dot notation for relationships.
+    #
+    #   Set via DSL: +agentcode_search :title, :content, 'user.name'+
+    #
+    #   Query: +GET /api/posts?search=rails+
+    #
+    #   @return [Array<String>]
+    #   @example
+    #     agentcode_search :title, :content, :excerpt, 'user.name'
+    self.allowed_search = []
+
+    # =========================================================================
+    # PAGINATION
+    # =========================================================================
+
+    # @!attribute [rw] pagination_enabled
+    #   Whether pagination is enabled for the index endpoint.
+    #
+    #   When +true+, responses include X-* pagination headers:
+    #   +X-Current-Page+, +X-Last-Page+, +X-Per-Page+, +X-Total+.
+    #
+    #   When +false+, the API returns all records. Clients can still
+    #   request pagination via +?per_page=N+.
+    #
+    #   Set via DSL: +agentcode_pagination_enabled true+
+    #
+    #   @return [Boolean]
+    #   @example
+    #     agentcode_pagination_enabled true
+    #     agentcode_pagination_enabled false  # disable to return all records
+    self.pagination_enabled = false
+
+    # @!attribute [rw] agentcode_per_page_count
+    #   Default number of records per page.
+    #
+    #   Override on your model to change the default. The +?per_page+ query
+    #   parameter overrides this value per-request (clamped 1-100).
+    #
+    #   Set via DSL: +agentcode_per_page 25+
+    #
+    #   @return [Integer]
+    #   @example
+    #     agentcode_per_page 25
+    #     agentcode_per_page 50
+    self.agentcode_per_page_count = 25
+
+    # =========================================================================
+    # MIDDLEWARE
+    # =========================================================================
+
+    # @!attribute [rw] agentcode_model_middleware
+    #   Middleware names applied to every action on this model.
+    #
+    #   Set via DSL: +agentcode_middleware 'throttle:60,1', 'auth'+
+    #
+    #   @return [Array<String>]
+    #   @example
+    #     agentcode_middleware 'throttle:60,1', 'auth'
+    self.agentcode_model_middleware = []
+
+    # @!attribute [rw] agentcode_middleware_actions_map
+    #   Per-action middleware.
+    #
+    #   Keys are action names: +'index'+, +'show'+, +'store'+, +'update'+,
+    #   +'destroy'+, +'trashed'+, +'restore'+, +'force_delete'+.
+    #
+    #   Set via DSL: +agentcode_middleware_actions store: ['verified']+
+    #
+    #   @return [Hash{String => Array<String>}]
+    #   @example
+    #     agentcode_middleware_actions(
+    #       store: ['verified'],
+    #       update: ['verified'],
+    #       destroy: ['admin']
+    #     )
+    self.agentcode_middleware_actions_map = {}
+
+    # =========================================================================
+    # ROUTE EXCLUSION
+    # =========================================================================
+
+    # @!attribute [rw] agentcode_except_actions_list
+    #   Actions to exclude from route registration.
+    #
+    #   Available actions: +'index'+, +'show'+, +'store'+, +'update'+,
+    #   +'destroy'+, +'trashed'+, +'restore'+, +'force_delete'+.
+    #
+    #   Set via DSL: +agentcode_except_actions :destroy, :force_delete+
+    #
+    #   @return [Array<String>]
+    #   @example
+    #     # Disable delete endpoints entirely
+    #     agentcode_except_actions :destroy, :force_delete
+    #   @example Read-only API
+    #     agentcode_except_actions :store, :update, :destroy
+    self.agentcode_except_actions_list = []
+
+    # =========================================================================
+    # OWNERSHIP / MULTI-TENANCY
+    # =========================================================================
+
+    # @internal Auto-detected from belongs_to associations.
+    self.agentcode_owner_path = nil
+
+    # =========================================================================
+    # VALIDATION (provided by AgentCode::HasValidation)
+    # =========================================================================
+    # Format validation uses standard ActiveModel +validates+ declarations
+    # on your model (always with +allow_nil: true+).
+    #
+    #   validates :title, length: { maximum: 255 }, allow_nil: true
+    #   validates :status, inclusion: { in: %w[draft published] }, allow_nil: true
+    #
+    # Field permissions (which attributes are accepted on create/update)
+    # are controlled by the policy. See +permitted_attributes_for_create+
+    # and +permitted_attributes_for_update+ on your policy class.
+    # =========================================================================
+
+    # Field permissions (which attributes are accepted on create/update) are
+    # controlled by the policy, not the model. Implement
+    # +permitted_attributes_for_create+ and +permitted_attributes_for_update+
+    # on your policy class.
+
+    # =========================================================================
+    # HIDDEN COLUMNS (provided by AgentCode::HidableColumns)
+    # =========================================================================
+
+    # @!attribute [rw] additional_hidden_columns
+    #   Additional columns to hide from API responses (on top of base defaults).
+    #
+    #   Base hidden columns (always hidden): +password+, +password_digest+,
+    #   +remember_token+, +created_at+, +updated_at+, +deleted_at+,
+    #   +discarded_at+, +email_verified_at+.
+    #
+    #   For per-user column hiding, implement +hidden_attributes_for_show+ /
+    #   +permitted_attributes_for_show+ on your Policy.
+    #
+    #   Set via DSL: +agentcode_additional_hidden :api_token, :stripe_id+
+    #
+    #   @return [Array<String>]
+    #   @example
+    #     agentcode_additional_hidden :api_token, :stripe_id, :internal_notes
+    self.additional_hidden_columns = []
+
+    # =========================================================================
+    # SOFT DELETES (requires Discard gem)
+    # =========================================================================
+    # Add +include Discard::Model+ to enable soft deletes.
+    # Requires a +discarded_at+ datetime column in your migration.
+    #
+    # When enabled, unlocks trash/restore/force-delete API endpoints.
+    #
+    #   class Post < AgentCode::AgentCodeModel
+    #     include Discard::Model
+    #   end
+    # =========================================================================
+
+    # =========================================================================
+    # AUDIT TRAIL (requires AgentCode::HasAuditTrail concern)
+    # =========================================================================
+    # When including +AgentCode::HasAuditTrail+, every create/update/delete
+    # is logged to the +audit_logs+ table via ActiveRecord callbacks.
+    #
+    # Exclude sensitive fields from audit snapshots:
+    #   agentcode_audit_exclude :password, :remember_token, :api_key
+    #
+    # Access audit logs:
+    #   post.audit_logs.order(created_at: :desc)
+    #
+    #   class Post < AgentCode::AgentCodeModel
+    #     include AgentCode::HasAuditTrail
+    #     agentcode_audit_exclude :password, :secret_token
+    #   end
+    # =========================================================================
+
+    # =========================================================================
+    # MULTI-TENANCY (requires AgentCode::BelongsToOrganization concern)
+    # =========================================================================
+    # When including +AgentCode::BelongsToOrganization+:
+    # - +organization_id+ is auto-set from the request on create
+    # - A default scope filters queries by the current organization
+    # - +belongs_to :organization+ is set up automatically
+    #
+    #   class Project < AgentCode::AgentCodeModel
+    #     include AgentCode::BelongsToOrganization
+    #   end
+    #
+    # For nested ownership (e.g. Task -> Project -> Organization),
+    # the path is auto-detected from belongs_to associations.
+    # =========================================================================
+
+    # =========================================================================
+    # UUID (requires AgentCode::HasUuid concern)
+    # =========================================================================
+    # When including +AgentCode::HasUuid+, a UUID is auto-generated on
+    # creation if the model has a +uuid+ column.
+    #
+    #   class Post < AgentCode::AgentCodeModel
+    #     include AgentCode::HasUuid
+    #   end
+    # =========================================================================
+
+    # =========================================================================
+    # PERMISSIONS (requires AgentCode::HasPermissions -- User model only)
+    # =========================================================================
+    # When including +AgentCode::HasPermissions+:
+    # - +has_permission?(permission, organization)+ checks permissions
+    # - +role_slug_for_validation(organization)+ resolves the role slug
+    #
+    # Permission format: +{slug}.{action}+ e.g. +'posts.index'+
+    # Wildcards: +'*'+ (all) or +'posts.*'+ (all actions on posts)
+    #
+    #   class User < AgentCode::AgentCodeModel
+    #     include AgentCode::HasPermissions
+    #     has_many :user_roles
+    #   end
+    # =========================================================================
+  end
+end

data/lib/agentcode/models/audit_log.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module AgentCode
+  class AuditLog < ActiveRecord::Base
+    self.table_name = "audit_logs"
+
+    belongs_to :auditable, polymorphic: true
+    belongs_to :user, optional: true
+
+    validates :action, presence: true
+
+    # old_values and new_values are json columns (native serialization).
+    # No explicit `serialize` call needed — ActiveRecord handles json
+    # columns automatically. If using text columns instead, add
+    # `serialize :old_values, coder: JSON` in your app's subclass.
+  end
+end

data/lib/agentcode/models/organization_invitation.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module AgentCode
+  class OrganizationInvitation < ActiveRecord::Base
+    self.table_name = "organization_invitations"
+
+    belongs_to :organization
+    belongs_to :role, optional: true
+    belongs_to :inviter, class_name: "User", foreign_key: "invited_by", optional: true
+
+    validates :email, presence: true
+    validates :token, presence: true, uniqueness: true
+
+    before_create :generate_token
+    before_create :set_expiration
+
+    scope :pending, -> { where(status: "pending").where("expires_at > ?", Time.current) }
+    scope :expired, -> { where(status: "pending").where("expires_at <= ?", Time.current) }
+
+    STATUSES = %w[pending accepted expired cancelled].freeze
+
+    def expired?
+      status == "pending" && expires_at.present? && expires_at <= Time.current
+    end
+
+    def pending?
+      status == "pending" && !expired?
+    end
+
+    def accept!(user)
+      update!(
+        status: "accepted",
+        accepted_at: Time.current
+      )
+
+      # Add user to organization via pivot table
+      if defined?(UserRole)
+        UserRole.find_or_create_by!(
+          user_id: user.id,
+          organization_id: organization_id,
+          role_id: role_id
+        )
+      end
+    end
+
+    private
+
+    def generate_token
+      self.token ||= SecureRandom.hex(32) # 64-char token
+    end
+
+    def set_expiration
+      expires_days = AgentCode.config.invitations[:expires_days] || 7
+      self.expires_at ||= expires_days.days.from_now
+    end
+  end
+end

data/lib/agentcode/policies/invitation_policy.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module AgentCode
+  class InvitationPolicy
+    attr_reader :user, :invitation
+
+    def initialize(user, invitation)
+      @user = user
+      @invitation = invitation
+    end
+
+    def index?
+      user_belongs_to_organization?
+    end
+
+    def create?
+      user_belongs_to_organization? && role_allowed?
+    end
+
+    def update?
+      user_belongs_to_organization? && invitation.pending?
+    end
+
+    def destroy?
+      user_belongs_to_organization? && invitation.pending?
+    end
+
+    private
+
+    def user_belongs_to_organization?
+      return false unless user
+      return false unless invitation.respond_to?(:organization_id)
+
+      if user.respond_to?(:user_roles)
+        user.user_roles.exists?(organization_id: invitation.organization_id)
+      else
+        true
+      end
+    end
+
+    def role_allowed?
+      allowed_roles = AgentCode.config.invitations[:allowed_roles]
+      return true if allowed_roles.nil?
+
+      if user.respond_to?(:role_slug_for_validation)
+        org = invitation.respond_to?(:organization) ? invitation.organization : nil
+        role_slug = user.role_slug_for_validation(org)
+        allowed_roles.include?(role_slug)
+      else
+        true
+      end
+    end
+  end
+end